--- title: SuccApp 工作区 navTitle: 工作区 --- # SuccApp 工作区 SuccApp 工作区是一个本地目录，用来保存从 SuccApp 服务器克隆下来的元数据项目、服务器配置、同步基线、编辑器辅助配置、AI 协作文件和 Git 版本历史。可以把它理解为 SuccApp 元数据开发的项目目录：人在这里编辑文件，AI Agent 在这里读取规则和修改元数据，SuccApp CLI 和 SuccApp for VS Code 在这里检查差异、拉取和推送服务器变化。 SuccApp CLI 也可以直接读取或修改服务器上的远端文件，但正式项目更建议基于工作区修改本地文件。工作区能把一次修改变成可搜索、可审查、可回退、可协作的文件变更，更适合大项目、AI Agent 批量理解和修改、多文件联动调整、工作区版本管理和团队评审。 ## 工作区与工具的关系{#tools} 工作区不是某一个工具的私有目录，而是多个工具共同协作的项目边界。 | 工具或角色 | 在工作区中的作用 | | --- | --- | | SuccApp CLI | 初始化工作区，执行状态检查、diff、拉取、推送、修复和脚本化自动化。 | | SuccApp for VS Code | 浏览服务器项目，查看 Changes、文件历史和差异，并执行交互式同步操作。 | | Git | 记录本地元数据文件的修改历史，支持评审、回退、分支协作和发布流程。 | | AI Agent | 读取工作区规则和同类文件，在本地修改元数据，再交给人和工具检查。 | 需要了解 CLI 如何操作工作区时，阅读 [SuccApp CLI](./cli.md)；需要了解 VS Code 图形界面时，阅读 [SuccApp for VS Code](./vscode.md)。 ## 初始化工作区{#init} 工作区可以从服务器克隆出初始内容，也可以从团队 Git 仓库恢复已有内容。AI Agent 和脚本化流程通常优先使用 SuccApp CLI；人工需要图形界面时再配合 SuccApp for VS Code。具体步骤见[初始化工作区](../workspace/init-workspace.md)。 ## 版本管理{#versioning} 正式项目建议使用 Git 管理工作区。Git 记录团队版本历史、分支、提交、评审和回退；SuccApp 负责连接服务器、维护本地 mirror、检查本地变化和远端变化。推荐入库内容、忽略规则、提交流程和回退方式见[工作区版本管理](../workspace/git-versioning.md)。 ## 工作区目录结构{#structure} 典型工作区结构如下。不同项目可能只包含其中一部分目录，实际结构以当前工作区为准。 ```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 和服务器{#sync-model} SuccApp 用三类内容判断同步状态： | 内容 | 位置 | 说明 | | --- | --- | --- | | 工作区文件 | 项目目录 | 人和 AI 实际编辑的本地元数据文件。 | | 本地 mirror | `.succapp/remote/` | 上次同步时记录的服务器基线。 | | 服务器当前内容 | SuccApp 服务器 | 当前正在测试或生产环境生效的元数据。 | 本地文件和 mirror 不一致时，会产生本地变化；mirror 和服务器当前内容不一致时，会产生远端变化；本地和服务器同时改了同一资源时，可能产生冲突。 ## AI 协作文件{#ai-files} 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 列出候选文件和判断依据，再确认是否允许修改。 ## 推荐协作方式{#recommended} 1. 每个客户或交付项目使用独立工作区。 2. 同一个工作区只管理同一套业务系统的测试和生产服务器。 3. 开始修改前先拉取 Git，再拉取服务器变化。 4. AI 修改前先读取规则和同类文件。 5. 修改后通过 SuccApp diff 和 Git diff 双重检查。 6. 测试环境验证通过后再提交 Git。 后续修改、拉取和推送流程见[修改、对比、拉取与推送](../workspace/sync-changes.md)。