协作工作区初始化工具

这是一个“契约驱动 + 多角色 + 多仓库协作”的初始化工具仓库。

当前阶段先验证三仓库闭环：产品、前端、后端。产品仓库内部细分功能、UI、测试契约；前端和后端只按产品仓库的 handoff 与契约包实现。

长期目标不是把当前仓库直接当作业务协作总仓库，而是生成一套可追踪的协作系统：

• 产品用自然语言、Excel、原型或客户反馈提出需求。
• AI 在产品契约仓库中补全功能契约、UI 契约、接口草案和验收标准。
• 前端、后端、测试分别在自己的区域或仓库里实现。
• 所有变更通过功能 ID 和 Git diff 关联。
• 联调中发现不合理，先改契约，再同步 UI、接口、测试和实现。

本工具仓库目录

xmszm-init-tool/
├── desktop/                 桌面启动器 UI
├── src-tauri/               Tauri/Rust 后端
├── scripts/                 init / join / ensure / validate 脚本
├── templates/
│   ├── xmszm-root/         初始化后生成的协作总仓库模板
│   └── subrepos/            初始化后生成或挂载的子仓库模板
└── .agents/skills/          初始化工具自身使用的协作 skill 源

初始化后的总仓库目录

generated-xmszm-root/
├── AGENTS.md
├── .gitmodules
├── .agents/skills/          生成后的项目内置协作 skills
├── .xmszm/                 工作区、角色、AI 配置
└── repos/
    ├── product-contract/    产品契约子仓库，内部细分功能/UI/测试
    ├── frontend-app/        前端实现子仓库
    └── backend-api/         后端实现子仓库

使用顺序

1. 项目负责人运行 xmszm init 生成协作总仓库，并添加 product、frontend、backend 三个 submodule。
2. 项目负责人提交并推送总仓库。
3. 参与者运行 xmszm join，输入总仓库链接、选择本地目录、角色和 AI。
4. AI 每轮先读 node scripts/xmszm-context.js，确认当前角色、可写仓库和缺失仓库。
5. xmszm-join-root.js 会自动按角色初始化允许的 submodule。
6. 产品把需求材料放入产品契约仓库的 raw-inputs/。
7. 产品使用 product-contract-gate 与 AI 对话确认定版。
8. AI 在产品仓库生成实施级契约包。
9. 前端和后端读取产品仓库的 handoff/<FEATURE-ID>.md 后开始实现。

真实仓库名称不要求标准化。总仓库只维护稳定别名，例如 product-contract、frontend、backend；真实仓库 URL、目录名和本地路径由 .xmszm/workspace.json 配置。

创建总仓库

交互式使用：

xmszm init

相对目录会创建在你执行命令的位置。例如在 D:\Projects 执行并输入 luyin，会生成 D:\Projects\luyin。

开发时未全局安装，直接用工具仓库里的脚本：

node scripts/xmszm.js init

如果希望在任意目录直接使用 xmszm init，先在本工具仓库执行一次：

npm link

之后去目标父目录执行 xmszm init。不要用 npm exec -- xmszm 试本地未发布工具，它会优先走 npm 解析和缓存，容易命中同名或旧包。

使用真实远端子仓库：

xmszm init --target-dir D:\Projects\DemoXmszm --project-name Demo ^
  --product-repo https://example.com/product-contract.git ^
  --frontend-repo https://example.com/frontend-app.git ^
  --backend-repo https://example.com/backend-api.git

本地试用可以自动创建三个本地子仓库：

xmszm init --target-dir C:\tmp\xmszm-demo-root --project-name Demo --local

本地试用的模拟子仓库会放在总仓库内部：

<总仓库>/.xmszm/local-subrepos/

不会在总仓库旁边额外创建 *-subrepos 目录。

生成后推送总仓库：

cd D:\Projects\DemoXmszm
git remote add origin <TOTAL_REPO_URL>
git push -u origin HEAD

加入总仓库

交互式使用：

xmszm join

产品角色：

xmszm join --repo <TOTAL_REPO_URL> --target-dir D:\Projects\DemoProduct --role product --ai codex

前端角色：

xmszm join --repo <TOTAL_REPO_URL> --target-dir D:\Projects\DemoFrontend --role frontend --ai codex

后端角色：

xmszm join --repo <TOTAL_REPO_URL> --target-dir D:\Projects\DemoBackend --role backend --ai codex

一键本地演示：

xmszm demo

未全局安装时：

node scripts/xmszm.js demo

想直接运行 xmszm demo 同样需要先在本工具仓库执行一次 npm link。

更新已有工作区

在已经初始化或已经加入的协作总仓库目录里执行：

xmszm upgrade

upgrade 的目标是“当前协作工作区”，不是模板来源。默认模板来源始终是已发布的 xmszm@latest npm 包；即使本机的 xmszm 命令是通过 npm link 指向本工具源码，默认也会从 npm 包更新规则和 skills。

也可以显式指定要更新的工作区：

xmszm upgrade --target-dir D:\Projects\DemoProduct

为了避免误操作，upgrade 会拒绝把本工具源码仓库当成目标目录。开发工具本身时，直接修改本仓库代码并发 npm 版本；不要用 upgrade 更新工具源码仓库。

一个功能的标准链路

产品输入
-> 产品仓库 functions/ 功能契约
-> 产品仓库 ui/ UI 契约
-> 产品仓库 tests/ 测试契约
-> 产品定版决策
-> handoff 实施交付入口
-> 前端/后端实现

统一功能 ID

所有仓库必须引用同一个功能 ID。

示例：

MC-ORDER-001 创建订单
MC-ORDER-002 激活订单
MC-REFUND-001 发起售后
MC-DELIVERY-001 配送接单

分支、PR、文档、接口、测试都应引用功能 ID。

桌面启动器

桌面端使用 Tauri 打包，配置见 src-tauri/。

npm install
npm run dev
npm run build

跨平台 CI 见 .github/workflows/tauri-build.yml。推送 app-v* 标签或手动触发 workflow 后，会分别构建 Windows、macOS 和 Linux 产物。

桌面启动器的初始化、加入、校验、上下文输出已经由 Rust 后端执行，不依赖 Node。子仓库拉取当前仍调用系统 Git。