feat(ssw-loop): P7 — generated command reference + drift-check

- references/command-reference.generated.md: 190 dacli commands from --help tree
  (auto-generated by dacli/scripts/gen-command-reference.ts; do not hand-edit)
- scripts/check_command_drift.py: assert template dacli --flags exist in the reference
  (advisory); whitespace-preceded flag match avoids CSS/anchor false positives
- dacli-doc-pattern.md: point subagents at the generated reference (single source of truth)

Verified: drift-check green — 37 template options all present, 0 drift.

Co-Authored-By: Claude <[email protected]>
This commit is contained in:
sswandClaude committed 2026-07-24 11:47:32 +08:00
1 parent 1d66bdeba1
commit cff2e32e44
3 files changed
+1928

No files matched your search

File diff suppressed because it is too large. Load diff
@@ -2,6 +2,12 @@
> **零应用信息**: 本文件不引用具体 HTML/MD 文件路径, 跨 appCode 通用.
> 🔒 **命令语法唯一真相源 (P7, 2026-07-24)**: 子代理写 dacli 命令前, 查
> `references/command-reference.generated.md` (从 `dacli <cmd> --help` 命令树**自动生成**,
> 190 条命令含全部选项/默认值) — **不要凭记忆或手抄命令语法** (会漂移, 典型: 漏 `--category`)。
> CLI 改过后重新生成: `npx tsx dacli/scripts/gen-command-reference.ts`。
> 校验模板无漂移: `python3 .claude/skills/ssw-loop/scripts/check_command_drift.py`。
## 🎯 核心: 永远别 Read 整个文档
| 操作 | 旧 (Read 整个文件) | 新 (dacli doc get 切片) |
@@ -0,0 +1,52 @@
#!/usr/bin/env python3
"""check_command_drift.py — ssw-loop 模板命令漂移门 (P7, 2026-07-24)
模板里 `dacli <cmd> --flag` 用到的选项, 必须在生成参考里存在。
参考 = references/command-reference.generated.md (由 dacli 命令树生成)。
漂移 (模板用了已删/改名/拼错的选项) → 告警。advisory: exit 0 (稳定后可改阻塞)。
跑: python3 .claude/skills/ssw-loop/scripts/check_command_drift.py
"""
import os, re, sys, glob
HERE = os.path.dirname(os.path.abspath(__file__))
SKILL = os.path.dirname(HERE)
REF = os.path.join(SKILL, 'references', 'command-reference.generated.md')
FLAG = re.compile(r'--[A-Za-z][A-Za-z0-9-]*') # 参考里 `--flag` (backtick 包裹)
FLAG_USED = re.compile(r'(?<=\s)--[A-Za-z][A-Za-z0-9-]*') # 模板里: 必须空格前导 (排除 CSS .a--b / 锚点 #x--y)
if not os.path.exists(REF):
print(f"⚠ 参考未生成: {REF}\n 先跑: npx tsx dacli/scripts/gen-command-reference.ts")
sys.exit(0) # advisory
# 1) 参考里的合法选项 (含 backtick 包裹的 `--flag`)
ref_text = open(REF, encoding='utf-8').read()
valid = set(FLAG.findall(ref_text))
# 2) 扫模板/参考里的 dacli 命令行选项 (排除生成文件本身)
used = {} # flag -> [file:line]
targets = (glob.glob(os.path.join(SKILL, 'templates', '**', '*.tmpl'), recursive=True)
+ glob.glob(os.path.join(SKILL, 'templates', '**', '*.md'), recursive=True)
+ glob.glob(os.path.join(SKILL, 'references', '*.md'))
+ [os.path.join(SKILL, 'SKILL.md')])
for f in targets:
if os.path.abspath(f) == os.path.abspath(REF):
continue
for i, line in enumerate(open(f, encoding='utf-8'), 1):
if 'dacli ' not in line:
continue
for m in FLAG_USED.findall(line):
used.setdefault(m, []).append(f"{os.path.relpath(f, SKILL)}:{i}")
# 3) 报告漂移 (模板用了参考里没有的选项)
drift = {f: locs for f, locs in used.items() if f not in valid}
if not drift:
print(f"✓ 命令漂移门: 模板 {len(used)} 个选项全部在生成参考中 (无漂移)")
sys.exit(0)
print(f"⚠ 命令漂移门: {len(drift)} 个模板选项不在生成参考中 (可能已删/改名/拼错):")
for f in sorted(drift):
print(f" {f} ← {drift[f][0]}" + (f" (+{len(drift[f])-1})" if len(drift[f]) > 1 else ""))
print(" 修复: 更新模板选项, 或重跑 gen-command-reference.ts 若 CLI 刚改过")
sys.exit(0) # advisory (稳定后改 sys.exit(1) 阻塞)