Cs Onboard

cs-onboard

把仓库接入 CodeStable 工作流体系——白纸或已有零散文档的都行。本技能只做两件事：搭骨架、归旧档。骨架搭好后子工作流（feature / issue / compound 等）即可直接运行。

两条路径

启动后先扫一次自动判断，不要让用户选——TA 大概率不知道项目里现有哪些文档。扫描结果模糊（如只有 README）就明说判断依据并问用户。

标准骨架（目标状态）

共享路径与命名约定的权威版本是项目里的 .codestable/reference/shared-conventions.md——本技能从技能包复制过去。下面只列 onboard 创建 / 检查的骨架文件。

.codestable/
├── .gitignore                  忽略 CodeStable 运行期 Python 缓存等机器产物
├── attention.md                CodeStable 技能启动必读的项目注意事项
├── requirements/               需求聚合根（空目录 .gitkeep）
│                               （CONTEXT.md / adrs/ 由 cs-domain 按需 lazy 创建）
├── roadmap/                    规划层聚合根
├── goals/                      目标聚合根（bounded goal 自主迭代 + 功能验收）
├── features/                   feature 聚合根
├── issues/                     issue 聚合根
├── refactors/                  重构聚合根（beta）
├── audits/                     审计聚合根
├── brainstorms/                脑暴 / interview 持久记录聚合根
├── compound/                   沉淀类统一目录（cs-keep 写自由 markdown，grep 检索）
├── gates/                      workflow gate 配置（onboard 释放）
│   └── roadmap-goal-gates.yaml roadmap goal 阶段 gate policy
├── tools/                      跨工作流共享脚本（onboard 整目录释放）
│   ├── search-yaml.py / validate-yaml.py
│   ├── codestable-worktree-gate.py / codestable-ai-branch-guard.py / codestable-main-publish.py
│   └── codestable-doctor.py / codestable-spec-governance.py / codestable-dod-runner.py …
├── hooks/                      agent hook 配置（onboard 释放）
│   └── hooks.codex.json        PreToolUse branch-guard，拦截 main/master 上的实现
└── reference/                  跨子技能共享参考（onboard 整目录释放）
    ├── shared-conventions.md / tools.md / maintainer-notes.md
    ├── approval-conventions.md / goal-conventions.md / execution-conventions.md
    └── spec-governance-tools.md / branch-guard-hooks.md / tools-context.md

gates/、tools/ 与 reference/ 由 onboard 整目录复制，自动带上 workflow gate 配置、gate 工具与共享口径。hooks/ 是可选的分支保护层，详见下文「分支保护 hook」。

启动检查

先检查一次现状：

1. 检查 .codestable/：不存在 → 空仓库候选；存在但不完整 → 迁移（部分补齐）

2. 旧 CodeStable兼容 CodeStable 经过多次改名，从 easysdd 到 codestable 再到 .codestable，如果遇到旧版的codestable目录，提示用户：

   检测到旧版codestable。建议直接 git mv easysdd .codestable，结构 / frontmatter 完全兼容，rename 后即用。要我执行吗？

   同意 → git mv easysdd .codestable，按迁移路径走（这时只需补齐可能缺失的 attention.md、gates/、tools/ 和 reference/）。想保留旧目录 → 告诉他子技能只读 .codestable/，旧目录不会被读；按空仓库路径走新骨架

3. Glob 全仓库 .md（排除 node_modules/ .git/）：根目录 DESIGN.md / ARCHITECTURE.md / SPEC.md / README.md；docs/ doc/ design/ spec/ wiki/；现有 .codestable/ 下文件

4. 检查 .codestable/attention.md：缺失则列为骨架待补齐项

5. 汇报扫描结论：找到的相关文档（列路径）+ 走哪条路径 + 判断依据 + 不确定项

空仓库路径

步骤 1：和用户确认范围

• 项目名 / 简介（汇报时引用）
• attention.md 只建最小骨架；用户已经给出的项目硬约束才写入，不凭空代填

步骤 2：创建目录骨架

按下面顺序执行，不等用户逐步确认——骨架是整体一次性的：

• .codestable/{requirements,roadmap,goals,features,issues,refactors,audits,brainstorms,compound}/.gitkeep
• .codestable/.gitignore（从技能包 cs-onboard/codestable.gitignore 复制，忽略运行期缓存）
• .codestable/attention.md（最小骨架模板见同目录 reference.md）
• .codestable/gates/（用 cp -rf / Copy-Item -Recurse -Force 整目录拷贝技能包 cs-onboard/gates/）
• .codestable/tools/（用 cp -rf / Copy-Item -Recurse -Force 整目录拷贝技能包 cs-onboard/tools/，不要 Read 再 Write）
• .codestable/reference/（同上）
• .codestable/hooks/（同上；可选的分支保护层，见下文「分支保护 hook」）

requirements/CONTEXT.md 和 requirements/adrs/ 不在骨架里——交给 cs-domain 在用户第一次需要术语 / ADR 时 lazy 创建。

落盘用 shell 整目录覆盖，不要 Read 再 Write——这两个目录是机器共享资产，Read+Write 会截断大文件、改缩进、吃空行，还慢费 token。具体命令见迁移路径步骤 4。

步骤 3：attention.md 提醒

attention.md 已创建但默认只有空骨架。汇报时提醒用户：有编译前置、测试命令、目录禁区、凭证规则、报告语言偏好这类"每次 CodeStable 技能启动都必须知道"的信息，后续用 cs-note 一条条追加。

步骤 4：验收汇报

列建了哪些文件：

CodeStable 骨架已就绪。现在可以：开始新功能 cs-feat / 报告问题 cs-issue / 沉淀知识 cs-keep

迁移路径

步骤 1：生成审计报告

置信度：高 = 语义明确匹配；中 = 可推断有歧义；低 = 不明确或映射多个位置都合理。

步骤 2：逐条对齐

中 / 低置信度的用 AskUserQuestion 问：

• 中：给推断理由，问"按这个方式归位？"
• 低：描述文件内容，给 2-3 个候选位置 + "跳过"

高置信度不逐条问但要在汇报里列，给用户复审机会——逐条问会让节奏失控。

步骤 3：处理已部分存在的 .codestable/

• 命名不符规范（YYYY-MM-DD-{slug} 格式）但有内容 → 提示用户问是否重命名
• 空占位（.gitkeep / 空 .md）→ 直接补齐不问

步骤 4：补齐缺失骨架

对照标准骨架补齐用户确认后仍缺失的目录 / 文件。已有内容不覆盖。

.codestable/gates/、.codestable/tools/ 和 .codestable/reference/ 一律用技能包新版本覆盖——这些目录是技能包维护的共享资产，权威源在 cs-onboard/gates/、cs-onboard/tools/ 和 cs-onboard/reference/，项目里的只是落盘副本。技能包升级后再跑 onboard 的目的之一就是刷新副本，留旧版本会让子技能按过时口径工作。

覆盖前在汇报列出被覆盖文件让用户知道；用户明确说"我改过 tools/xxx.py 请保留"才例外保留并标红。这是迁移路径唯一强制覆盖的动作，其他已有文件遵守"不经确认不动"。

落盘命令：

# macOS / Linux
cp -rf <技能包路径>/cs-onboard/gates/.      .codestable/gates/
cp -rf <技能包路径>/cs-onboard/tools/.      .codestable/tools/
cp -rf <技能包路径>/cs-onboard/reference/.  .codestable/reference/
cp -rf <技能包路径>/cs-onboard/hooks/.      .codestable/hooks/
cp -f  <技能包路径>/cs-onboard/codestable.gitignore .codestable/.gitignore
find .codestable/tools -type d -name __pycache__ -prune -exec rm -rf {} +
find .codestable/tools -type f -name '*.pyc' -delete

# Windows PowerShell
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\gates\*      .codestable\gates\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\tools\*      .codestable\tools\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\reference\*  .codestable\reference\
Copy-Item -Recurse -Force <技能包路径>\cs-onboard\hooks\*      .codestable\hooks\
Copy-Item -Force <技能包路径>\cs-onboard\codestable.gitignore .codestable\.gitignore
Remove-Item -Recurse -Force .codestable\tools\__pycache__ -ErrorAction SilentlyContinue
Get-ChildItem .codestable\tools -Recurse -Filter *.pyc | Remove-Item -Force

不要：Read+Write 手工搬（截断 / 改缩进）、一个个 cp（多步骤多出错）、先比 diff（规则就是无条件覆盖）。

技能包路径一般是 skill 安装目录（~/.claude/skills/cs-onboard/ 或插件目录）。不确定先 ls 定位。拷完 ls .codestable/gates/ .codestable/tools/ .codestable/reference/ 验证。

步骤 5：处理不迁移的文件

用户选"跳过"的文件：不移动 / 不删除 / 不重命名，汇报标"保留原位（未纳入 CodeStable）"。绝不允许未经确认就动——onboard 只允许 AI 整理不允许替用户做删除决定。

步骤 6：attention.md 提醒（同空仓库路径步骤 3）

步骤 7：验收汇报

列：迁移文件清单（from → to）、新建骨架、未迁移文件（保留原位）、下一步建议。

骨架文件模板

attention.md 最小模板见同目录 reference.md。

分支保护 hook（可选）

.codestable/hooks/hooks.codex.json 注册一个 PreToolUse 钩子，调用 .codestable/tools/codestable-ai-branch-guard.py，在 AI 试图于 main/master 等受保护分支上 Edit/Write/Bash 改代码时拦截，强制改动落到 linked worktree 的类型分支（feat/ / fix/ / refactor/）。详细规则见 .codestable/reference/branch-guard-hooks.md。

• 接入：把 hooks.codex.json 的内容合并进 agent 的 hook 配置（Claude Code .claude/settings.json 或 Codex 等价位置）。onboard 只释放文件，不自动改 agent 全局配置——是否启用由 owner 决定。
• 侵入性：启用后日常在 main 上的直接编辑会被挡下，需走 worktree 流程。不想要这套强约束就不接入，留着 tools/ 里的 gate 脚本手动调用即可。
• 关闭：从 agent hook 配置移除该条即可，工具脚本仍可被各实现技能显式调用。

行级代码审查工具 open-code-review（可选）

cs-code-review 的审查分两环节：独立隔离 agent review（必需）+ OCR 行级扫描（增强）。OCR 用的是 open-code-review 的 ocr CLI——装上后 cs-code-review 会自动检测并调用，没装则自然降级，不阻塞。

1. 安装：先检测，已装就别重装

which ocr   # 已经有路径 → 跳过安装，直接进第 2 步

只有 which ocr 找不到时，才问 owner 是否安装（默认建议装），同意后全局装：

npm install -g @alibaba-group/open-code-review

全局安装是 owner 环境改动（需联网），必须先确认再装，不自动执行。owner 拒绝 → 不装，cs-code-review 检测不到会记 not-available 并继续。

2. 配置 LLM：用 provider 体系，别用旧 llm.* 块

⚠️ 最容易踩的坑：ocr v1.x 用的是 provider / providers 体系。网上 / 旧文档教的 ocr config set llm.url ...（llm.* 块）在新版不生效——配了也会被忽略，ocr 仍按默认 provider 连官方端点，表现为 ocr llm test 卡住超时（context deadline exceeded）。

ocr 是独立 CLI 进程，不复用 codex / claude agent 的模型——agent 只是替它执行 ocr review 命令，ocr 自己去连配置好的 LLM backend，必须单独配。

内置 provider 列表用 ocr llm providers 查。配置（以 anthropic 兼容网关为例）：

ocr config set provider anthropic
ocr config set providers.anthropic.url <网关 base-url>   # 不含 /v1/messages，ocr 按协议自动拼
ocr config set providers.anthropic.api_key <api-key>
ocr config set model <model>                             # 如 claude-opus-4-8
ocr llm test                                             # 必须看到 ✓ Connection test successful

• 字段名是 url 不是 base_url；anthropic 协议下 ocr 会自动拼 /v1/messages。
• OpenAI 兼容网关同理：ocr config set provider <name>（用 openai 协议的内置 provider 或自定义）+ providers.<name>.url + .api_key。
• 绝不替 owner 编造 / 硬编码 API key——只给命令模板，由 owner 自己填。

3. 收尾自检

跑 python3 .codestable/tools/codestable-doctor.py --root .，输出末尾 OCR tool: 行会报 configured / unconfigured / misconfigured / not-installed，并对错配（如残留旧 llm.* 块、provider 缺失）给出精确修复指引。doctor 只做静态体检、不发网络请求，连通性仍以 ocr llm test 为准。

退出条件

• .codestable/ 各聚合根目录（requirements/roadmap/goals/features/issues/refactors/audits/brainstorms/compound）都存在
• .codestable/.gitignore 已安装
• .codestable/attention.md 已建
• .codestable/gates/、.codestable/tools/、.codestable/reference/、.codestable/hooks/ 已从技能包复制
• 已告知 owner 分支保护 hook 是可选项及如何接入 / 关闭
• 已 which ocr 检测：已装则跳过安装、确认配置为 provider 体系（非旧 llm.* 块）；未装则询问 owner 是否安装并记录结果
• 迁移路径：每条映射都有明确处理结果（迁移 / 保留原位）
• 迁移路径：没有未经确认就移动的文件
• 验收汇报已给出

容易踩的坑

• 未经确认就移动 / 删除已有文件——迁移核心原则是用户拍板
• 替用户填 attention.md 实质内容——必须项目 owner 来定，AI 只提供模板
• 重新引入 AGENTS.md / CLAUDE.md 兼容路径——CodeStable 的启动注意事项入口固定为 .codestable/attention.md
• 建完骨架立刻开始 feature/issue——onboard 是"搭环境"不是"开始干活"
• 低置信度直接执行——低 = 必须问
• .codestable/gates/、.codestable/tools/ 和 .codestable/reference/ 走"不覆盖"保守策略——这些目录必须用技能包新版本覆盖，否则升级后用户停留在过时口径
• 用 Read + Write 手工搬——必须 cp -rf / Copy-Item -Recurse -Force 整目录覆盖
• 把 __pycache__ / *.pyc 带进目标项目——复制后必须清理生成缓存，不能把本机运行产物当技能资产
• Glob 时忘记排除 node_modules/ .git/——会让扫描结果充斥噪声

相关文档

• .codestable/reference/system-overview.md — CodeStable 体系总览
• .codestable/reference/shared-conventions.md — 目录结构和共享口径的权威版本
• .codestable/attention.md — CodeStable 技能启动必读的项目注意事项