wk-backend/codestable/reference/tools.md

CodeStable 工具用法参考

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

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

---

1. search-yaml.py

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

基本语法

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

filter 语法

• key=value：字段精确匹配（大小写不敏感）
• key~=value：字符串字段子串匹配；列表字段元素包含匹配

排序语法

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

常用命令

沉淀类文档统一在 codestable/compound/，用 doc_type 字段区分四个子技能的产物，内部还有各自的细分字段：

# 按 doc_type 筛选
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter status=active
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --filter status=active

# doc_type + 子技能内部细分字段
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=learning --filter track=pitfall
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter category=constraint
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter type=pattern
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --filter type=question

# 按 tag（列表元素包含匹配）
python codestable/tools/search-yaml.py --dir codestable/compound --filter tags~=prisma

# 全文搜索
python codestable/tools/search-yaml.py --dir codestable/compound --query "shadow database"

# 按领域/框架/语言筛选
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter area=frontend
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter framework~=vue
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=trick --filter language=typescript

# 搜索 feature 方案 doc
python codestable/tools/search-yaml.py --dir codestable/features --filter doc_type=feature-design --filter status=approved

# 输出控制
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active --full
python codestable/tools/search-yaml.py --dir codestable/compound --filter tags~=llm --json

# 按时间排序
python codestable/tools/search-yaml.py --dir codestable/compound --sort-by date --order desc                     # 最近归档的在前
python codestable/tools/search-yaml.py --dir codestable/library-docs --sort-by last_reviewed --order asc         # 最久没 review 的在前（找陈旧文档）
python codestable/tools/search-yaml.py --dir codestable/guides --filter status=current --sort-by last_reviewed --order asc

典型使用场景

场景	命令建议
feature-design 开始前查已有归档	搜 codestable/compound 目录，按 --query "{关键词}" 全文搜；要分类看就加 --filter doc_type={learning|trick|decision|explore}
issue-analyze 根因分析前查历史	搜 codestable/compound --filter doc_type=learning --filter track=pitfall、再搜 --filter doc_type=trick --filter type=library，按相关组件/框架过滤
归档落盘后查重叠	搜 codestable/compound --query "{关键词}" --json，看有无语义重叠
新人了解项目规约	--dir codestable/compound --filter doc_type=decision --filter status=active
按技术栈浏览技巧	--dir codestable/compound --filter doc_type=trick --filter language={语言} --filter status=active
找最久没 review 的库文档 / 指南	--dir {目录} --filter status=current --sort-by last_reviewed --order asc
看最近沉淀了哪些经验	--dir codestable/compound --filter doc_type=learning --sort-by date --order desc

---

2. validate-yaml.py

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

# 校验单个文件的 YAML 语法
python codestable/tools/validate-yaml.py --file {文件路径} --yaml-only

# 校验必填字段
python codestable/tools/validate-yaml.py --file {文件路径} --require doc_type --require status

# 批量校验目录下所有文件
python codestable/tools/validate-yaml.py --dir {目录} --require doc_type --require status