主题
SuccApp 工作区
SuccApp 工作区是一个本地目录，用来保存从 SuccApp 服务器克隆下来的元数据项目、服务器配置、同步基线、编辑器辅助配置、AI 协作文件和 Git 版本历史。可以把它理解为 SuccApp 元数据开发的项目目录：人在这里编辑文件，AI Agent 在这里读取规则和修改元数据，SuccApp CLI 和 SuccApp for VS Code 在这里检查差异、拉取和推送服务器变化。
SuccApp CLI 也可以直接读取或修改服务器上的远端文件，但正式项目更建议基于工作区修改本地文件。工作区能把一次修改变成可搜索、可审查、可回退、可协作的文件变更，更适合大项目、AI Agent 批量理解和修改、多文件联动调整、工作区版本管理和团队评审。
工作区与工具的关系
工作区不是某一个工具的私有目录，而是多个工具共同协作的项目边界。
| 工具或角色 | 在工作区中的作用 |
|---|---|
| SuccApp CLI | 初始化工作区，执行状态检查、diff、拉取、推送、修复和脚本化自动化。 |
| SuccApp for VS Code | 浏览服务器项目，查看 Changes、文件历史和差异，并执行交互式同步操作。 |
| Git | 记录本地元数据文件的修改历史，支持评审、回退、分支协作和发布流程。 |
| AI Agent | 读取工作区规则和同类文件，在本地修改元数据，再交给人和工具检查。 |
需要了解 CLI 如何操作工作区时，阅读 SuccApp CLI；需要了解 VS Code 图形界面时，阅读 SuccApp for VS Code。
初始化工作区
工作区可以从服务器克隆出初始内容，也可以从团队 Git 仓库恢复已有内容。AI Agent 和脚本化流程通常优先使用 SuccApp CLI；人工需要图形界面时再配合 SuccApp for VS Code。具体步骤见初始化工作区。
版本管理
正式项目建议使用 Git 管理工作区。Git 记录团队版本历史、分支、提交、评审和回退；SuccApp 负责连接服务器、维护本地 mirror、检查本地变化和远端变化。推荐入库内容、忽略规则、提交流程和回退方式见工作区版本管理。
工作区目录结构
典型工作区结构如下。不同项目可能只包含其中一部分目录，实际结构以当前工作区为准。
text
sales-ops-workspace/ # 工作区根目录，通常也是 Git 仓库根目录
├── .git/ # Git 本地版本库，由 Git 维护
├── .gitignore # Git 忽略规则，排除 SuccApp 运行时文件和本机临时文件
├── AGENTS.md # Codex 等 AI 工具优先读取的工作区说明
├── CLAUDE.md # Claude Code 入口，通常引用 AGENTS.md
├── .github/ # GitHub Copilot 等仓库级配置
│ └── copilot-instructions.md # GitHub Copilot 仓库级说明
├── .agents/ # AI 协作规则、技能和阶段性产物
│ ├── README.md # AI 工作区说明
│ ├── rules/ # 团队长期规则
│ ├── skills/ # 官方离线文档同步成功后写入 succapp-docs/
│ ├── plans/ # AI 实施计划和迁移计划
│ ├── reviews/ # AI 评审记录
│ ├── reports/ # AI 调查和验证报告
│ └── tmp/ # 一次性临时脚本和草稿
├── .succapp/ # SuccApp 工作区运行时目录，通常不提交 Git
│ ├── .gitignore # SuccApp 运行时文件的忽略规则
│ ├── config.json # 当前工作区的服务器地址簿和活跃服务器
│ ├── remote/ # 本地 mirror，保存上次同步时的服务器基线
│ ├── json-schemas/ # 编辑器结构提示辅助文件
│ ├── succ-types/ # 脚本 TypeScript 诊断使用的类型声明
│ ├── tsconfig.action.json # 服务端脚本 TypeScript 诊断配置
│ ├── tsconfig.browser.json # 浏览器脚本 TypeScript 诊断配置
│ ├── merge-base/ # 拉取和合并前保存的服务器基线副本
│ ├── merge-backup/ # 拉取和合并前保存的本地文件备份
│ ├── locks/ # 同步任务锁
│ ├── cache/ # 本地缓存
│ ├── *.log # 本机日志
│ └── state.json # 本机同步状态
├── .vscode/ # VS Code 工作区配置
│ └── settings.json # 文件关联、结构提示、隐藏规则等推荐设置
├── sales-ops/ # 元数据项目目录，对应服务器上的 SALES_OPS 项目
│ ├── .meta # 项目根目录直接子资源的服务器资源标识和附加信息
│ ├── settings/ # 项目级设置、主题、模板和附件
│ │ ├── .meta # settings 目录直接子资源的元信息
│ │ ├── settings.json # 项目设置
│ │ └── themes/ # 项目主题目录
│ ├── data/ # 项目级公共数据模型、查询和加工资源
│ │ ├── .meta # data 目录直接子资源的元信息
│ │ └── tables/ # 公共数据模型目录
│ │ ├── .meta # tables 目录直接子资源的元信息
│ │ ├── SALES_ORDER.tbl # 销售订单数据模型
│ │ ├── CUSTOMER_PROFILE.tbl # 客户画像数据模型
│ │ └── SALES_KPI.query # 销售指标查询
│ ├── app/ # 低代码应用目录
│ │ ├── .meta # app 目录直接子资源的元信息
│ │ └── sales-center.app/ # 销售运营中心应用
│ │ ├── .meta # 应用目录直接子资源的元信息
│ │ ├── settings.json # 应用设置
│ │ ├── index.spg # 应用首页
│ │ ├── customer-list.spg # 客户列表页面
│ │ ├── order-detail.spg # 订单详情页面
│ │ ├── data/ # 应用内私有数据模型或查询
│ │ ├── scripts/ # 应用内脚本
│ │ └── assets/ # 应用内图片、图标等素材
│ ├── ana/ # 跨应用共用的仪表板和报表
│ │ ├── .meta # ana 目录直接子资源的元信息
│ │ ├── sales-overview.dash # 销售总览仪表板
│ │ └── monthly-sales.rpt # 月度销售报表
│ └── public/ # 项目公开静态资源
│ ├── .meta # public 目录直接子资源的元信息
│ └── images/ # 项目公开图片资源
└── tsconfig.json # 工作区脚本 TypeScript 诊断入口配置项目目录、资源文件和目录级 .meta 是需要协作管理的元数据，通常应纳入 Git。.meta 是 SuccApp 判断本地目录和服务器资源关系的重要文件，新增、移动、重命名或删除资源时，不要把相关 .meta 当作普通临时文件删除。
工作区根目录下可以有多个元数据项目，例如 sales-ops/、finance-reporting/ 或 sysdata/。一个目录必须包含项目级 .meta，才会被 SuccApp 识别为工作区中的元数据项目。
本地文件、mirror 和服务器
SuccApp 用三类内容判断同步状态：
| 内容 | 位置 | 说明 |
|---|---|---|
| 工作区文件 | 项目目录 | 人和 AI 实际编辑的本地元数据文件。 |
| 本地 mirror | .succapp/remote/ | 上次同步时记录的服务器基线。 |
| 服务器当前内容 | SuccApp 服务器 | 当前正在测试或生产环境生效的元数据。 |
本地文件和 mirror 不一致时，会产生本地变化；mirror 和服务器当前内容不一致时，会产生远端变化；本地和服务器同时改了同一资源时，可能产生冲突。
AI 协作文件
SuccApp 推荐工作区设置会初始化常见 AI 协作入口：
| 文件或目录 | 用途 |
|---|---|
AGENTS.md | AI 工具优先读取的工作区规则入口。 |
CLAUDE.md | Claude Code 入口，通常引用 AGENTS.md。 |
.github/copilot-instructions.md | GitHub Copilot 仓库级说明。 |
.agents/rules/ | 团队长期规则。 |
.agents/skills/succapp-docs/ | 官方离线文档 skill，同步成功后生成。 |
.agents/plans/、.agents/reviews/、.agents/reports/ | 计划、评审和报告。 |
.agents/tmp/ | 一次性临时脚本和草稿。 |
默认情况下，计划、评审、报告和临时文件不应直接进入 Git；需要长期保留时，由团队确认后再调整忽略规则。
给 AI 安排任务时，不建议把所有规则都写成很长的个人提示词。长期规则放在 AGENTS.md、.agents/rules/ 或团队文档中；单次任务提示词只补充本次目标、环境、范围、参考、禁区和验收方式。
| 信息 | 说明 |
|---|---|
| 目标 | 要解决的业务问题或期望效果。 |
| 环境 | 当前连接的是测试环境还是生产环境。 |
| 范围 | 允许 AI 查找或修改的项目、目录、页面、模型、脚本或数据源。 |
| 参考 | 已知入口、同类文件、截图、页面路径或业务样例。 |
| 禁区 | 不允许修改或执行的内容，例如权限、流程、生产配置、数据源和 SQL 写操作。 |
| 验收 | 人工如何确认任务完成，例如打开哪个页面、检查哪个 diff 或执行哪类业务流程。 |
如果目标、环境、范围或禁区不清楚，应先让 AI 列出候选文件和判断依据，再确认是否允许修改。
推荐协作方式
- 每个客户或交付项目使用独立工作区。
- 同一个工作区只管理同一套业务系统的测试和生产服务器。
- 开始修改前先拉取 Git，再拉取服务器变化。
- AI 修改前先读取规则和同类文件。
- 修改后通过 SuccApp diff 和 Git diff 双重检查。
- 测试环境验证通过后再提交 Git。
后续修改、拉取和推送流程见修改、对比、拉取与推送。
