DSCC
主页 / verification

文档命令验证规范

本文件规定了 DSCC 文档中 shell 命令的验证流程与 # [待验证] 标记的去除规则。

分层

层级 含义 所需证据
Tier 1 — 代码自证 命令形态由源码可确认；运行只是复现 clap/bash 已保证的行为。如 dscc --help、dscc --version、export ANTHROPIC_API_KEY=...、cargo build。 指向相应解析器或 README 行号的 file:line 引用。
Tier 2 — 本机 smoke 无网络、无凭据、在沙箱中退出码 0。如 dscc init、dscc agents、dscc skills、dscc system-prompt、dscc dump-manifests、dscc bootstrap-plan。 docs/verification/logs/tier2/<slug>.log，含 exit: 0 和关键输出片段。
Tier 3 — 依赖 API 需要真实 provider。如 dscc --model <id> prompt "..." 与全部 cookbook 案例。 docs/verification/logs/tier3/<slug>.log，含退出码 0、非空模型返回，以及与 cookbook 预期一致的工具调用轨迹。
Tier 4 — 仅交互 无法脚本化：REPL 会话、OAuth（dscc login）、需要加载后再输入 / 命令的场景。 # [待验证] 改写为 # [交互]，并补一行人工操作说明。

标记的生命周期

  1. 作者 编写命令时加 # [待验证]。
  2. 验证者 按上表层级执行。
  3. PASS：去掉标记，把日志路径（Tier 2/3）或代码引用（Tier 1）记入 docs/verification/registry.md。
  4. FAIL：保留标记，把失败原因写入 registry，并修正文档（命令本身或周围的说法）。
  5. Tier 4 永远不去标记，而是改写为 # [交互]。

日志格式

每条 Tier 2/3 日志包含：

# <file-relative-path>:<line> — <short description>
$ <exact command invoked>
<stdout + stderr as captured>
---
exit: <code>
duration: <seconds>s
model: <model id, Tier 3 only>
verdict: PASS | FAIL
notes: <one-line explanation>

API key 与敏感 URL 禁止 落盘。日志里出现时以 <REDACTED> 替换。

目录结构

docs/
├── verification.md           # 本文件
└── verification/
    ├── registry.md           # PASS/FAIL 索引，每条命令一行
    └── logs/
        ├── tier2/<slug>.log
        └── tier3/<slug>.log