skills/codestable__codestable
1
0
Fork 0
mirror of https://github.com/codestable/CodeStable.git synced 2026-09-19 09:03:09 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
feat/cs-agent
codestable__codestable/.codestable/reference/tools.md
T
Wyatt Fang 525f185a79 release: CodeStable 1.0.4
2026-07-15 21:58:14 +08:00

13 KiB
Raw Permalink Blame History

CodeStable 工具用法参考

本文件由 cs-onboard 复制到项目的 .codestable/reference/tools.md，所有 CodeStable 子技能用项目相对路径 .codestable/reference/tools.md 引用。

当前 cs-onboard skill 包 tools/ 下共享脚本的完整用法参考。子技能里只写本技能特有的 1-2 行典型查询；完整语法和示例看这里。

命令里的 <cs-onboard skill 目录> 是当前加载的 cs-onboard/SKILL.md 所在目录。新版 CodeStable 从这个全局 skill 包运行工具；旧项目已有 .codestable/tools/ 只作兼容副本，不作为新版技能入口。

1. search-yaml.py

通用 YAML frontmatter 搜索工具。从项目根目录运行，无需安装额外依赖（PyYAML 可选，有则用，无则内建 fallback parser）。

基本语法

python3 <cs-onboard skill 目录>/tools/search-yaml.py --dir {目录} [--filter key=value]... [--query "全文关键词"] [--sort-by FIELD [--order asc|desc]] [--full] [--json]

filter 语法

  • key=value：字段精确匹配（大小写不敏感）
  • key~=value：字符串字段子串匹配；列表字段元素包含匹配
  • key=a|b|c / key~=a|b|c：同一字段多个候选值，候选之间是 OR；在 PowerShell / Bash 中请给整个 filter 加引号，例如 --filter "status=approved|draft"

排序语法

  • --sort-by FIELD：按 frontmatter 字段排序（典型字段：last_reviewed、date、updated_at）
  • --order desc|asc：desc 默认，新的在前；asc 老的在前（查"谁最久没更新"用这个）
  • 字段缺失 / 值为空的文档一律排到最后，不干扰前排结论

常用命令

search-yaml.py 用于扫带 frontmatter 的产物——feature spec / issue spec / requirements / adrs / docs/dev|user|api。

.codestable/compound/ 由 cs-keep 写纯 markdown（无 frontmatter），不用 search-yaml，直接 grep：

grep -r "关键词" .codestable/compound/
grep -rl "prisma" .codestable/compound/   # 只列文件名
ls -lt .codestable/compound/ | head        # 看最近沉淀

带 frontmatter 的目录用 search-yaml：

# 搜索 feature 方案 doc
python3 <cs-onboard skill 目录>/tools/search-yaml.py --dir .codestable/features --filter doc_type=feature-design --filter status=approved

# 按时间排序
python3 <cs-onboard skill 目录>/tools/search-yaml.py --dir docs/api --sort-by last_reviewed --order asc
python3 <cs-onboard skill 目录>/tools/search-yaml.py --dir docs/dev --filter status=current --sort-by last_reviewed --order asc

# 输出控制
python3 <cs-onboard skill 目录>/tools/search-yaml.py --dir .codestable/features --filter status=approved --full
python3 <cs-onboard skill 目录>/tools/search-yaml.py --dir .codestable/features --filter tags~=llm --json

典型使用场景

场景 命令建议
feature-design 开始前查 compound 已有沉淀 grep -r "{关键词}" .codestable/compound/
issue-analyze 根因分析前查历史 grep -rl "{关键词}" .codestable/compound/ 再人工挑相关的看
cs-keep 落盘前查重叠 grep -rl "{关键词}" .codestable/compound/，命中就先看那条决定更新还是新写
找最久没 review 的库文档 / 指南 --dir {目录} --filter status=current --sort-by last_reviewed --order asc

2. validate-yaml.py

YAML 语法校验工具。用于验证 frontmatter 语法和必填字段。

# 纯 YAML：checklist/items/goal-state 等逐文件校验
python3 <cs-onboard skill 目录>/tools/validate-yaml.py --file {文件路径}.yaml --yaml-only

# Markdown frontmatter：单文件或目录校验必填字段
python3 <cs-onboard skill 目录>/tools/validate-yaml.py --file {文件路径}.md --require doc_type --require status
python3 <cs-onboard skill 目录>/tools/validate-yaml.py --dir .codestable/features --require doc_type --require status

目录模式默认只校验 .md frontmatter；要批量校验纯 YAML 目录必须显式加 --yaml-only。不要对混有 checklist/items/goal-state 的目录直接加 --require doc_type --require status；纯 YAML 没有 Markdown frontmatter 字段，会造成假失败。

3. Roadmap Goal Gates

cs-onboard 会把技能包里的 gates/ 释放到项目 .codestable/；gate 脚本从当前 cs-onboard skill 包的 tools/ 目录运行。这些 gate 不是全局 PreToolUse 拦截器，而是由 cs-epic / cs-feat 等主入口在阶段边界显式调用。

python3 <cs-onboard skill 目录>/tools/codestable-workflow-next.py epic --roadmap .codestable/roadmap/{slug} --json
python3 <cs-onboard skill 目录>/tools/codestable-workflow-next.py feature --feature .codestable/features/YYYY-MM-DD-{slug} --epic-child-batch --json
python3 <cs-onboard skill 目录>/tools/codestable-workflow-next.py feature --feature .codestable/features/YYYY-MM-DD-{slug} --require-implementation-ready --json
python3 <cs-onboard skill 目录>/tools/validate-yaml.py --file .codestable/gates/roadmap-goal-gates.yaml --yaml-only
python3 <cs-onboard skill 目录>/tools/codestable-dod-contract-gate.py --design .codestable/features/YYYY-MM-DD-{slug}/{slug}-design.md
python3 <cs-onboard skill 目录>/tools/codestable-dod-runner.py --checklist .codestable/features/YYYY-MM-DD-{slug}/{slug}-checklist.yaml
python3 <cs-onboard skill 目录>/tools/codestable-evidence-pack.py --feature {slug} --design {design} --checklist {checklist} --dod-results {dod-results} --gate-results {gate-results} --out {slug}-evidence-pack.md
python3 <cs-onboard skill 目录>/tools/codestable-goal-consistency-gate.py --roadmap .codestable/roadmap/{slug}

roadmap-goal-gates.yaml 是阶段配置入口；codestable-scope-gate.py、codestable-dod-runner.py 和 codestable-evidence-pack.py 是 implementation.before_review 的最小 runtime。status: protocol-only 的 gate 只表示协议占位，由 review / QA / acceptance / audit 技能读取证据后执行，不代表已有独立脚本。 四个 executable feature gate 的 JSON 顶层都写 canonical feature: YYYY-MM-DD-slug 与 repo-relative inputs；文件型 inputs 同时写 SHA-256。最终 gate 核验 status=passed、gate_id、stage allowlist、feature identity、实际 design/checklist/feature_dir/out 路径及当前内容摘要，旧结果缺 identity/input/digest 时必须重跑，不能只改文件名或在 gate 后替换内容。 artifact YAML/JSON 无法解析或顶层不是 mapping 时，executable gate 必须输出结构化 failed/blocked JSON；严格 gate loader 缺少 PyYAML 时也 fail-closed，不使用宽松 fallback 猜测状态。scope gate 无法完成 git status 也必须失败，不得把检查错误当成空变更。 codestable-goal-consistency-gate.py 是 roadmap_audit.before_complete 的 runtime，先机械证明每个非 dropped item 与 accepted feature 一一对应，再检查 canonical feature 路径、frontmatter identity、两份独立 Goal authorization、approved design、review/QA/acceptance/evidence/gate/DoD 产物和 checklist 状态；它先于 goal-audit 报告执行，防止空 feature、重复 feature 或跨 feature 证据复用。 codestable-workflow-next.py 是只读下一步解析器，输出 next_action、must_continue 和 final_answer_allowed；cs-epic / cs-feat 在 child design batch 边界必须按它的 JSON 继续或停 gate。Epic child batch 先校验完整 DAG，再按拓扑选择 design-ready item：依赖为 done、dropped 或 design-review passed 可继续设计；missing/cycle/重复依赖立即结构化阻断，dropped 依赖在 goal package 前必须修订或放弃下游 item。实现前用 --require-implementation-ready 机械要求依赖严格全为 done，不能把 design readiness 冒充 implementation readiness。单 feature 按仓库事实恢复：feature goal-state 优先为 Goal；design 的完整 roadmap metadata 经 parent items 唯一证明，或被 parent items / roadmap goal-state 反向唯一认领的 child 交回 Epic；显式 feature 指针具有权威性，目录回退按精确 feature slug，多 claim 与错误 owner 结构/路径 fail-closed；ff-note 或 design 的 execution_lane: quick 恢复 Quick；旧 design 缺 lane 时恢复 Standard。Quick/Standard 的 passed review 必须有独立 reviewer 锚点，Quick 不得吞掉既有非 passed QA/acceptance；损坏的 YAML/frontmatter 或合法 YAML 中错误的路径/容器在 --json 下返回含具体路径的结构化 blocked，不得输出 traceback。 如果 skill 包缺少这些 runtime 脚本，说明本机 CodeStable 安装不完整；先更新 / 重装 CodeStable。项目缺少 gates/ 或 reference/ 时运行 runtime sync。

4. codestable-doctor.py

CodeStable 生命周期状态检查工具。只读，不修改文件。用于开始工作、恢复上下文、最终汇报前判断当前仓库是否还有阻塞项。

python3 <cs-onboard skill 目录>/tools/codestable-doctor.py --root . --json

JSON 关键字段：

  • status：idle / planning-safe / dirty / implementation-active / attention-needed / blocked
  • tooling.runtime：repo-local runtime 与 skill-global tool 静态体检；runtime-drift / version-mismatch 时运行 runtime sync，version-unavailable 时先重装或更新 cs-onboard
  • tooling.runtime.drifted_paths：内容不同、缺失或仅存在于项目端的 package-owned runtime 路径；allowlist 中的 legacy 路径不计入
  • runtime sync 删除 target-only package-owned 路径后再复制模板；source 目录缺失时不删除项目副本，managed directory / .gitignore / manifest symlink 先解除再恢复，且不得沿链接改写外部内容
  • tooling.runtime.capabilities：base / workflow-next / goal-gates 的 repo_paths、skill_tool_paths 和缺失列表
  • checkout：当前分支、默认分支
  • dirty_buckets：按 code / tests / docs / migrations / data / logs / codestable / unknown 分组的 dirty paths
  • implementation_changes：当前 dirty tree 中的实现文件
  • backlog：needs-human-review、Follow-up、accepted/deferred P2、attention.md candidates 等待处理项；canonical lifecycle 文件里 status: canceled/cancelled/abandoned 的 feature / issue / refactor 单元会被当作历史记录跳过
  • findings：按严重度列出的阻塞或待处理问题
  • next_action：下一步建议

典型用法：

# 汇报前确认没有遗漏的人审 / follow-up / runtime 阻塞
python3 <cs-onboard skill 目录>/tools/codestable-doctor.py --root . --json

5. build-review-packet.py

独立 Task agent review 的输入包生成器。它把本次 unit 文档、diff stat、聚焦 diff、验证结果和风险提示整理成一份可发给 reviewer 的 Markdown，并自动隐藏 .env / token / secret 类路径和值。--stage 用来区分 review 目的，默认 implementation 兼容旧调用。

python3 <cs-onboard skill 目录>/tools/build-review-packet.py --root . --unit .codestable/features/YYYY-MM-DD-{slug} --stage quality --output /tmp/codestable-review.md \
  --validation "uv run pytest -> passed" \
  --validation "CLI smoke -> passed"

可选 stage：

  • implementation：旧默认值，综合实现 review。
  • spec：检查是否严格满足 requirement / report / analysis / design / checklist，重点抓缺失需求、额外行为和范围漂移。
  • quality：检查可维护性、安全、边界条件、测试缺口、幂等和 crash-resume 等工程质量。
  • verification：只看 fresh validation evidence；必须传 --validation 或 --validation-file，不能接受记忆里的“已跑过”。

适用时机：feature / issue / refactor 代码写完、owner 验证命令跑完之后，触发 Task agent reviewer 之前。reviewer 只审查，不修改代码。review 结果仍要落到 {slug}-review.md，packet 只是输入材料。

输出内容：

  • unit 下的 .md / .yaml 关键文档；
  • unstaged / staged git diff --stat；
  • 排除 secret-like 路径后的 focused diff；
  • owner 传入的验证命令和结果；
  • 数据库 / 迁移 / 并发 / 幂等 / crash-resume / provider cost / deterministic LLM boundary 风险提示。

6. Context / Commit Tools

For these tools, see .codestable/reference/tools-context.md:

  • build-context-packet.py
  • check-context-sufficiency.py
  • plan-commits.py
  • codestable-backlog.py

Owner approval checkpoints are not context packets. When the owner must choose, approve, authorize, accept risk, merge, deploy, or answer a grill / interview decision, follow .codestable/reference/approval-conventions.md and write the relevant unit's approval-report.md. Context packets may be supporting evidence, not the approval surface.

Reference in New Issue View Git Blame Copy Permalink