Mission to Agents（mission-to-agents）
> 当前版本：v0.9.1 · 发布：2026-10-24 · 许可：MIT ｜ 变更记录见 CHANGELOG.md ｜ SkillHub slug：nexus-mission-to-agents
> 一图看懂：assets/overview.svg ｜ 不想读文档：node scripts/guide.mjs（3 个问题 → 一条命令）
面向 TRAE / WorkBuddy 这类 AI 工作台：把工作台里每一个任务，变成一个独立的 Agent ——
独立身份档案、独立工作区（worktree）、独立分支、明确职责边界，且全程本地可控（只本地提交，
集成与推送分级授权）。对多 AI 并行开发的 git 仓库，一键建立并长期维护这套「权责清晰、
机器可强制」的协作约束，产出物全部由根目录 constraints.config.json 驱动 —— 改配置即可适配
不同仓库结构，无需手改规则文本。
> 本文件是路由层（唯一入口）：只做「意图 → 指向」，细节在各功能模块（references/）里。
> 全量文件索引见 references/INDEX.md，文件规范见 references/structure.md。
一句话准则
> 并行开发 AI 只在自己的 feature/* 分支上开发并本地提交；合并进本地 main 由自动化任务
> （集成发布负责人身份）审查后执行；所有推送，统一由负责人先与项目管理者确认再执行。
这个 skill 解决什么
多个 AI（或多个会话）在同一仓库并行开发时，常见灾难：互相覆盖、误提交、抢改热点文件、
版本号混乱、身份无法追溯、谁都能 push 到主干。本 skill 用三段式权责把它们关进笼子：
| 阶段 | 谁 | 能做什么 |
|---|---|---|
| ① 编码 | 并行开发 AI（各自 worktree + feature 分支） | 只在自己分支上改、只本地提交 |
| ② 本地集成 | 自动化任务 / 集成发布负责人（保留 ID AI-00） |
rebase → merge --no-ff 进 main、递增版本号、打本地 tag |
| ③ 云端提交 | 集成发布负责人 + 项目管理者确认 | 唯一可 push 远端的人，且每次推送前先确认 |
配套强制手段：git 钩子（身份/分支/尾注/范围/推送权限校验）+ 身份档案（一 ID 一文件，
登记 范围 作为职责边界）+ 版本号单一事实源（VERSION 出，其余位置脚本同步）+
自动化任务自动构建（CI 版本守卫 + 门禁，见 automation.md）。
层级路由（用户引导）
先定意图，再看场景，最后落到命令 / 文档。完整路由表见 references/routing.md。
| 用户说 | 意图 | 去向 |
|---|---|---|
| 「给仓库加多 AI 并行开发规范 / 约束」「一键构建约束」「要分支权限、提交钩子、身份校验」 | 建立约束 | adopt.mjs（三层门户，见 onboarding.md） |
| 「体检约束是否完整 / 有没有漂移」 | 体检 | audit.mjs |
| 「约束升级了，把仓库同步到最新模板」「把仓库规则回流到 skill」 | 同步 | sync.mjs |
| 「打包 / 发布 skill」 | 发布 | pack.mjs（见 maintenance.md） |
| 「三段式 / 版本号 / 钩子 / 格式规范 / 自动化…是怎么设计的」 | 了解规范 | 概念文档，见下表 |
30 秒决策树
| 你现在的情况 | 直接做 |
|---|---|
| 全新目录，还没 git | node scripts/bootstrap.mjs --target . |
| 已有 git 仓库，第一次接入 | node scripts/adopt.mjs --target .（先计划，确认后 --apply） |
| 已接入旧版，想对齐 | audit → adopt / sync --to-repo --write |
| 遇到报错 / 不知道错在哪 | troubleshooting.md |
| 有「为什么/怎么办」类疑问 | faq.md |
| 完全不想记命令 | node scripts/guide.mjs |
快速开始
# 推荐入口：按场景接入（默认只出计划，不落盘；看到计划并确认后再加 --apply）
node <skill>/scripts/adopt.mjs --target . # 三层门户：自动判定 S1 / S2 / S3
node <skill>/scripts/adopt.mjs --target . --apply # 审批后执行（幂等、非破坏、不提交、不推送）
# 传统入口（已接入仓库的重复构建 / 维护仍可用）
node <skill>/scripts/bootstrap.mjs --target . # 一键构建（幂等；不提交、不推送）
# 编辑 constraints.config.json，按仓库真实结构改（模块 / 门禁 / 热点文件 / 受保护文件）
# 约束体检（CI / 自动化任务可当门禁：退出码 0 = 通过）
node <skill>/scripts/audit.mjs --target .
# skill 升级后，把仓库文件对齐到最新模板（先 dry-run，确认后加 --write）
node <skill>/scripts/sync.mjs --target . --to-repo
> <skill> 指本 skill 所在目录。每个脚本结束都会打印统一的使用结果汇报（见下）。
> 加 --json 可同时得到结构化汇报。
使用结果汇报（统一格式）
任何时候触发本 skill（跑脚本或 Agent 主导接入），结束都必须给出一份同构的「使用结果汇报」 ——
固定字段：技能 / 动作 / 目标 / 场景 / 结论 / 计数 / 要点 / 自动化 / 告警 / 下一步。
脚本由 scripts/lib/report.mjs 统一输出；Agent 主导接入时请按同格式手工汇报（动作键 manual）。
格式与字段见 references/report.md。
两个档位（profile）
| 档位 | 面向 | 生成内容 |
|---|---|---|
team（默认） |
多 AI 并行开发 | 全套：身份档案 + git 钩子 + 三段式权责 + 版本号工具 + 规则文件 |
solo |
单人 / 轻量 | 精简：版本号工具 + AGENTS.md 与规则（只留版本号单一事实源 + 提交规范），不含身份体系；仅一个可绕过的 pre-push 轻量门 |
改 constraints.config.json 的 profile 后，重跑 bootstrap --force（或 sync --to-repo --write）即可切换。
六个脚本
| 脚本 | 作用 | 关键参数 |
|---|---|---|
scripts/guide.mjs |
新手向导：问 3 个问题，输出一条可复制命令（不读写仓库） | --target |
scripts/adopt.mjs |
按场景接入（三层门户）：只读识别 S1/S2/S3 → 出计划 → 审批后非破坏执行；含云端引导与任务种子 | --target --scene --plan --apply --emit-task --force --init-git --profile --providers --json |
scripts/bootstrap.mjs |
一键构建：配置 + 受管文件 + 冲突兜底 + 钩子 + 忽略项 + 版本初始化 + AI-00 档案 |
--target --config --profile --providers --force --json |
scripts/audit.mjs |
体检：结构/渲染/钩子/忽略/版本/身份/保护/冲突兜底/平台 十类检查；退出码 0=通过 | --target --json |
scripts/sync.mjs |
双向同步：模板→仓库（升级跟进）/ 仓库→模板（维护者回流） | --to-repo --from-repo --write --json |
scripts/pack.mjs |
打包：装配 SkillHub 发布包并生成 zip（维护者发布用） | --out --no-zip |
共享库：lib/config.mjs（配置/变量/渲染/受管清单）、lib/apply.mjs（写入/差异/环境设置）、
lib/detect.mjs（场景识别 + 现状反推）、lib/report.mjs（统一结果汇报）。详见 INDEX.md。
生成到目标仓库的文件
受管文件（已存在默认跳过，--force 覆盖；adopt 额外产出任务种子与代际标记）：
AGENTS.md # 主规则文件（全文；WorkBuddy 下自动用摘要版，控制在 8000 字符内）
.trae/rules/git-version-control.md # TRAE 规则（trae provider）
.trae/rules/git-commit-message.md # TRAE 提交规则（scene: git_message）
.codebuddy/rules/*/RULE.mdc # WorkBuddy 规则（alwaysApply，正文同源）
.githooks/pre-commit commit-msg pre-push # 身份/尾注/推送权限校验（team）
.githooks/pre-push # 版本一致 + 提交格式（solo 轻量门）
tools/ai-id.mjs # 身份与边界管理（team）
tools/version.mjs # 版本号管理（读 constraints.config.json）
.trae/agents/{out-of-scope.md, ids/*} # 越界报备与身份档案（team）
.github/workflows/ci.yml # 版本守卫 + 门禁 + 约束体检（GitHub 平台）
<模块>/.trae/rules/module-context.md # 模块级 globs 规则（traeModuleRules=true）
CHANGELOG.md # 变更日志
constraints.config.json # 配置契约（驱动以上全部）
非受管（adopt 产出、仓库可自行改写）：.trae/agent-tasks/AI-00 项目管理.md（任务种子）、
.mta.json（代际标记）。另追加 .gitignore 条目与 core.hooksPath = .githooks。
配置契约（摘要）
constraints.config.json 是唯一可参数化入口。主要字段：
| 字段 | 作用 |
|---|---|
profile / mainBranch |
档位（team / solo）与主干分支名 |
projectName / projectIntro / modules |
项目定位与模块表 |
worktrees.root / prefix |
并行开发位目录规范 |
identity.* |
负责人 ID、档案目录、身份文件、报备文件、远端名 |
version.source / tsConstPrefix / landings |
版本号单一事实源与落地位置 |
commitFormat.enabled / types |
是否由钩子强制 [类型] 描述（默认关闭） |
protectedFiles / hotFiles / gates |
受保护文件、热点文件、按范围触发的门禁 |
workbench.* / cloud.* |
任务种子与云端引导（均只打印、绝不自动推送） |
adoption.* |
接入：代际标记、现状反推、非破坏分类 |
automation.* |
自动化任务自动构建：平台 / 运行时 / 安装命令 / CI 落盘 / 体检作业 |
conventions.enabled |
是否在 AGENTS.md 渲染「格式规范速查」 |
rulesProviders / agentsMode |
平台规则载体（trae/workbuddy/auto/none）与 AGENTS 形态（full/summary/auto） |
soloPushGate / traeModuleRules |
solo 轻量门开关、TRAE 模块级 globs 规则（opt-in） |
逐项说明见 references/configuration.md。
概念与规范（按需加载）
| 想了解 | 文档 |
|---|---|
| 三层门户接入与场景判定 | onboarding.md |
| 三段式权责模型 | three-stage-model.md |
| 身份 ID 与职责边界 | identity-and-scope.md |
| 钩子与提交门禁 | hooks-and-gates.md |
| 版本号规范 | versioning.md |
| 配置字段契约 | configuration.md |
| 格式规范（提交/版本/分支/尾注/档案…） | conventions.md |
| 自动化任务与自动构建 | automation.md |
| 使用结果汇报格式 | report.md |
| 文件结构规范 / 全量索引 / 层级路由 | structure.md · INDEX.md · routing.md |
| 遇到报错 / 症状 → 修复 | troubleshooting.md |
| 常见问题（档位/覆盖/推送/版本/CI…） | faq.md |
| 维护者手册 | maintenance.md |
按需加载与体积
- 启动只读本文件（约 3k tokens）；
references/**按需打开，不要一次性全读。 - 每次只打开 1 篇：排障 →
troubleshooting.md；接入 →onboarding.md；字段 →configuration.md。 - SkillHub 显示的 token 数是整包估算（含维护文档与模板）；实际会话启动成本以本文件为准。
- 维护文档（
MANAGE.md、RELEASE-NOTES.html）不参与日常使用，可忽略。
维护与发布
- 本 skill 由专职维护 AI 负责（见根目录
MANAGE.md）。 - 仓库演进 →
sync.mjs --from-repo回流模板；skill 升级 →sync.mjs --to-repo下发。 - 任何模板/脚本改动都要：提升
metadata.version（本 skill 版本的单一事实源）、在CHANGELOG.md记录、
跑audit验证无回归、node scripts/pack.mjs出包。 - 结构优化后：新增文件须登记进 INDEX.md，并符合 structure.md。
