主题
初始化工作区
SuccApp 工作区是本地目录，也是 AI、SuccApp CLI、SuccApp for VS Code 和 Git 协作的边界。初始化工作区的目标，是让本地目录具备连接服务器、克隆项目、读取 AI 规则、检查差异、编辑脚本和提交 Git 的基础条件。
AI 低代码开发应从工作区开始，而不是从单个文件开始。工作区中包含项目元数据、目录级 .meta、服务器配置、类型声明、编辑器辅助配置、Git 忽略规则和 AI 协作文件，决定了 AI 能否准确理解和安全修改项目。
理解工作区
可以把一个 SuccApp 工作区理解为一个 VS Code 项目。一个工作区通常只维护同一套元数据内容对应的服务器，例如同一个客户项目的测试环境和生产环境。
这里的“同一套元数据内容对应的服务器”，不是指服务器地址必须只有一个，而是指这些服务器之间的项目、资源和元数据内容本来就属于同一套交付或同一套业务系统。
不建议把两个无关服务器直接放在同一个工作区中混合管理。如果确实需要在两个无关服务器之间做内容交互，例如一次性的升级或迁移，可以分别把 A、B 两个服务器初始化到两个工作区，再在本地从一个工作区复制需要的文件到另一个工作区，检查后再同步到目标服务器。
选择初始化路径
初始化工作区有两种常见路径：从服务器开始创建工作区，或者从团队 Git 仓库开始恢复工作区。AI Agent 和脚本化流程建议优先使用 SuccApp CLI；人工操作也可以使用 CLI，只有需要图形化选择服务器、查看项目树或检查 Changes 时再打开 SuccApp for VS Code。
正式项目建议从一开始就启用 Git。Git 用于记录本地元数据文件的历史，SuccApp 用于连接服务器和同步元数据，两者解决的问题不同。推荐入库内容、忽略规则和提交流程见工作区版本管理。
从服务器开始
适合团队还没有 Git 仓库，或者需要从某个 SuccApp 服务器拉出初始项目内容的场景。
bash
mkdir sales-ops-workspace
cd sales-ops-workspace
git init
succapp auth login <test-server-url>
succapp workspace init --server <test-server-url>
succapp workspace project clone SALES_OPS
git status这组命令会创建本地目录，初始化 Git，登录测试服务器，写入工作区配置，克隆 SALES_OPS 项目，并生成本地同步基线。克隆完成后，确认项目目录和目录级 .meta 已出现，再提交项目目录、目录级 .meta 和团队需要共享的配置。
如果服务器上还没有项目，需要先在浏览器项目管理页面创建项目，或由有权限的用户执行 succapp server project create <project>。创建项目后，再克隆到工作区。
人工使用 SuccApp for VS Code 时，可以在命令面板中依次执行 SuccApp: 初始化工作区、SuccApp: 添加服务器 和 SuccApp: 克隆项目。
从 Git 仓库开始
适合团队已经把工作区内容纳入 Git，或者新成员接手已有项目的场景。
bash
git clone <repo-url> sales-ops-workspace
cd sales-ops-workspace
succapp auth login <test-server-url>
succapp workspace init --server <test-server-url>
succapp workspace status --json这组命令会从 Git 取得团队已有工作区，登录测试服务器，刷新本机推荐设置和服务器配置，再输出当前工作区状态。AI Agent 可以优先读取 workspace status --json 结果，判断是否存在本地变化、远端变化或冲突。
从 Git 仓库开始时，不要直接用服务器克隆结果覆盖本地目录。先确认 Git 中已有的项目目录，再连接服务器并检查状态；只有确认要接受服务器版本时，再执行 succapp workspace pull 拉取服务器变化。
人工使用 SuccApp for VS Code 时，可以打开 Git 克隆后的目录，再执行 SuccApp: 初始化工作区、SuccApp: 添加服务器 或 SuccApp: 使用服务器，最后在 Changes 视图中刷新和检查变化。
添加服务器、登录服务器、使用服务器、浏览远端文件、重置和移除项目等完整操作，请阅读连接服务器与克隆项目。
初始化工作区与刷新推荐设置
执行 succapp workspace init 或 SuccApp: 初始化工作区 后，SuccApp 会创建或检查 .succapp/config.json，并补齐推荐工作区设置、AI 协作入口、TypeScript 诊断配置、编辑器结构提示配置和 Git 忽略规则。
这个命令不要求已经连接服务器。没有服务器连接时，会先完成本地工作区初始化；需要从服务器下载的类型声明、编辑器结构提示和前端运行时依赖清单，会在后续连接服务器、添加服务器或克隆项目时刷新。显式传入 --server <server-url> 时，SuccApp CLI 会先检查这台服务器的登录状态；如果尚未登录，需要先执行 succapp auth login <server-url>。服务器版本升级后，也可以再次执行 succapp workspace init --server <server-url> 或 SuccApp: 初始化工作区（英文界面为 SuccApp: Initialize Workspace）刷新推荐设置。
初始化工作区后，可以获得这些效果：
- 将
.tbl、.query、.dash、.rpt、.meta等常见 SuccApp 元数据文件识别为 JSON，便于使用 VS Code 的语法高亮、格式化和结构检查。 - 启用 SuccApp 文件图标主题，在资源管理器中更容易区分不同类型的元数据文件。
- 隐藏
.succapp/remote/、缓存、锁、日志和合并备份等运行时文件，减少日常编辑时的干扰。 - 生成或更新
tsconfig.json、.succapp/tsconfig.action.json、.succapp/tsconfig.browser.json，让 VS Code TypeScript Server 能为服务端脚本和浏览器脚本提供语法诊断。 - 在工作区存在业务 TypeScript 脚本且服务器支持时，从服务器下载并还原
.d.ts类型声明到.succapp/succ-types/，为脚本编辑提供类型提示和 API 补全。 - 从当前连接服务器下载编辑器结构提示文件，并更新
.vscode/settings.json，为.dash、.spg、.rpt、.fapp、.tbl、.query、.kdb、.wfl、.afl、.agent、.theme、.tpg、.meta、.jdbc、settings.json、capabilities.json和扩展package.json等文件提供结构提示。 - 写入推荐的 Git 忽略和 SuccApp 同步忽略配置，避免本地运行时文件进入 Git，并避免 IDE 辅助文件同步回元数据服务器。
- 初始化常用 AI 开发工具可识别的入口文件，并在
.agents/下创建计划、评审、报告、临时文件和团队规则目录。官方离线文档同步成功后，SuccApp 会写入.agents/skills/succapp-docs/，并把前端运行时内置依赖清单作为文档 skill 的资源下载到本地，供 AI 辅助编写 FTL、浏览器脚本和 CSS 时参考。
SuccApp 会尽量保留团队已有的工作区配置：根 tsconfig.json 只追加缺失的项目引用，.vscode/settings.json 只补齐缺失的推荐项。.succapp 下由 SuccApp 生成的辅助配置会在初始化工作区时刷新。
工作区文件说明
SuccApp 工作区中常见文件如下：
text
workspace/
├── AGENTS.md # Codex 等 AI 工具可读取的工作区说明
├── CLAUDE.md # Claude Code 入口，默认引用 AGENTS.md
├── .github/
│ └── copilot-instructions.md # GitHub Copilot 仓库级说明
├── .agents/
│ ├── README.md # AI 工作区说明
│ ├── plans/ # AI 实施计划、迁移计划
│ ├── reviews/ # AI Code Review、设计评审记录
│ ├── reports/ # AI 调查、分析、验证报告
│ ├── rules/ # 团队长期 AI 协作规则
│ ├── skills/ # 官方离线文档同步成功后写入 succapp-docs/
│ └── tmp/ # AI 临时脚本、草稿和一次性排查文件
├── .gitignore # 根目录 Git 忽略配置，SuccApp 会写入系统临时文件忽略片段
├── .succapp/
│ ├── .gitignore # SuccApp 运行时文件的 Git 忽略配置
│ ├── config.json # 当前工作区的服务器地址簿和当前活跃服务器
│ ├── remote/ # 本地服务器基线副本
│ ├── locks/ # 同步任务锁
│ ├── cache/ # 本地缓存
│ ├── json-schemas/ # 编辑器结构提示辅助文件
│ ├── merge-base/ # 拉取和合并前保存的服务器基线副本
│ ├── merge-backup/ # 拉取和合并前保存的本地文件备份
│ ├── succ-types/ # 脚本 TypeScript 诊断使用的类型声明
│ ├── succ-types.tmp-*/ # 刷新类型声明时使用的临时目录
│ ├── tsconfig.action.json # 服务端脚本 TypeScript 诊断配置
│ ├── tsconfig.browser.json # 浏览器脚本 TypeScript 诊断配置
│ ├── typescript-support.json # TypeScript 诊断支持的服务器版本记录
│ ├── *.log # 日志文件
│ └── state.json # 本地同步状态文件
├── .vscode/
│ └── settings.json # VS Code 工作区设置
├── project1/ # 从服务器克隆下来的元数据项目
│ ├── .meta # 记录 project1 下直接子资源的服务器资源标识和版本信息
│ └── index.spg
├── project2/ # 同一个工作区中可以克隆多个元数据项目
│ └── .meta # 记录 project2 下直接子资源的服务器资源标识和版本信息
└── tsconfig.json # 脚本 TypeScript 诊断配置服务器配置文件
添加服务器后，当前工作区会生成 .succapp/config.json。该文件保存服务器地址列表和当前活跃服务器。
示例结构如下：
json
{
"version": 2,
"servers": [
"http://localhost:8080"
],
"activeServerUrl": "http://localhost:8080"
}注意
.succapp/config.json 只保存服务器地址，不保存 PAT、OAuth2 access token 或 refresh token。认证状态由 SuccApp 的本机认证文件管理，不应提交到 Git 仓库。
Git 忽略建议
初始化工作区后，SuccApp 会自动补齐默认 .gitignore 配置，避免 .succapp/remote/、缓存、锁、日志、本机同步状态和临时文件进入 Git。提交前仍应检查 Git 状态，确认项目目录和目录级 .meta 会被提交，而 .succapp/remote/、.succapp/cache/、.succapp/locks/、.succapp/merge-base/、.succapp/merge-backup/、.succapp/*.log、.succapp/state.json 不会进入提交。
完整入库和忽略建议见工作区版本管理。
初始化后检查
初始化完成后，建议检查：
succapp workspace status --json能正常输出当前工作区状态。- 本地项目目录已经出现。
.succapp/remote/没有进入 Git 提交。- 目录级
.meta文件没有被 Git 忽略。 - 需要脚本提示的工作区已经生成
tsconfig.json和.succapp/succ-types/。 AGENTS.md、CLAUDE.md、.github/copilot-instructions.md和.agents/已生成，AI 临时文件会写到.agents/tmp/。- 当前连接的是测试服务器，而不是生产服务器。
- 如果使用 SuccApp for VS Code，服务器视图能看到当前服务器和项目，Changes 视图可以正常刷新。
下一步可以阅读连接服务器与克隆项目和修改、对比、拉取与推送。
