zhilv
7e491d4e60
添加 codestable/ 目录，包含项目架构文档、需求文档、 功能设计、问题追踪、参考文档、路线图及工具配置 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
# 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）。
|
||
|
||
### 基本语法
|
||
|
||
```bash
|
||
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` 字段区分四个子技能的产物，内部还有各自的细分字段：
|
||
|
||
```bash
|
||
# 按 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 语法和必填字段。
|
||
|
||
```bash
|
||
# 校验单个文件的 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
|
||
```
|