sillyspec 3.27.1 → 3.27.5

package/.claude/worktrees/sillyspec-data-model-research/templates/claude-instruction.md

@@ -0,0 +1,23 @@
+# Claude Code 指引
+
+## 项目说明
+本项目使用 **SillySpec** 管理变更，采用文档驱动开发。SillySpec 是给 Agent 调用的 CLI 流程控制器，不是给人类直接使用的产品，也不是处理业务逻辑的工具——你（Agent）通过 CLI 告诉它"我在哪"，它告诉你"下一步做什么"；你执行步骤，它校验产出、推进状态，人类只在关键决策点介入审批。要考虑多 agent 同时操作代码，代码随时可能变化。所有变更以稳定、可用、可维护为目标，按生产级标准处理。
+
+## 核心规则
+1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
+2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md）或现有代码依据，无依据不改。
+3. **新功能 / 大改动走完整流程**：`brainstorm → plan → execute → verify → archive`。
+4. **小修复 / 小调整走 quick**：`sillyspec run quick`。
+5. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档。
+6. **判规模选档**：≤3 文件、范围明确走 `quick`；多阶段 / 架构级走完整流程。
+7. **代码先行不补流程（倒推 B 模式）**：代码若已先写好，**不回头补 brainstorm/plan 装样子**——用 `quick --done` 收尾 + 补 quicklog 条目，把已落盘改动如实登记进进度库。
+8. **实证核验再 `--done`**：`quick --done` 前，触及 `src`/`test` 的改动先 `npm test` + `npm run lint`；纯 doc/配置改动可跳过（lint 不扫 docs/，空转无信息），以落盘文件与测试结果为准，不信口头"已完成"。
+9. **中途停下不靠额外命令存进度**——进度已由上一次 `--done` 自动落盘；恢复时用 `sillyspec progress show` 查看进度，再用 `sillyspec run <stage>` 续跑，不直接 commit 半成品。
+10. **实现完成后对照文档验收**（design.md / 模块文档），并检查是否影响已有测试。
+11. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
+12. **hook 拦截提交时禁止跳过**（`.husky/pre-push`），修复问题后再提交。
+13. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
+14. **任务记录隔离**：永不重置 / reset / 清零已存在的 change；多个活跃 change 各自 `--change <名>` 隔离不重叠；quick 同一 QUICKLOG 按 ql-ID 条目追加，不冲突。
+15. **quicklog 结构化落盘**：末步 `--done` 用四参数 `--req/--cause/--solution/--result`（CLI 合成结构化 output 并自动提取标题/四段分行）；文件括注用 `--file-notes "path::注 || path2"`。骨架由 CLI 接管，`--done` 后按需核对即可，勿手拼模板。
+16. **代码可能随时在修改**（多 agent 并行），Edit 前重跑 + 查最新态；破坏性 git op 前先备份。
+17. **不奉承用户**，禁止"你说得对"类话术，直接给结论、依据、方案。

package/.claude/worktrees/sillyspec-data-model-research/templates/prompts/taskcard-rules.md

@@ -0,0 +1,28 @@
+TaskCard 格式规则（必须严格遵守）：
+- 总长度 20~40 行，不要写成长文档
+- frontmatter 只含必要字段，不加 estimated_hours
+- title 用英文短语（kebab 风格动词短语，如 "Add readonly auxiliary constant"），title_zh 用对应中文标题——两字段是同一任务的双语表示，非不同信息；归档产物与 sillyhub 平台解析各取所需（title_zh 为中文展示首选）
+- goal: 一句话，用 > 多行字符串
+- implementation: 列表，每条一个具体步骤
+- acceptance: 列表，每条可独立验证（不是表格）
+- verify: 列表，实际可执行的命令
+- constraints: 列表，明确边界（含 brownfield 兼容、异常处理）
+- 不需要：修改文件章节、覆盖来源章节、接口定义章节、TDD 步骤章节、参考章节
+- frontmatter 必须以三减号结尾闭合（开头和结尾各一行 ---）。缺结尾会让 postcheck 提取不到 frontmatter，误报「字段缺失 / allowed_paths 为空」
+- allowed_paths 用块式写法（键名换行后每项一行「  - 路径」），不要用流式方括号 [path]——块式与所有校验器一致最稳
+- implementation / acceptance / constraints / verify 的每条列表项是 YAML plain scalar，避免以下特殊字符触发 ScannerError：
+  - 冒号+空格（如代码签名 provider_id:str、queryUsage(id:string)）会被当映射键报 mapping values are not allowed here——去掉冒号后空格或改成中文描述
+  - 花括号且内部含冒号或引号（如 JS 对象、JS 模板字面量）会报 expected block end——改用不含这些字符的中文描述
+  - 引号不成对会报扫描错误
+  - 注：goal 用 > 折叠标量可容忍花括号，goal 里写占位符不炸；只有上述 plain scalar 列表项需注意
+- provides / expects_from 是可选字段：仅当跨 task 契约（一个 task 的接口/DTO/响应被另一个 task 消费）时才填，单 task 或无对外接口场景留空即可
+- 填写后 plan-postcheck 会做硬对账：consumer 的每个 expects_from[provider].needs 字段必须在对应 provider 的 provides.fields 里，否则 plan 阶段阻断（不进入 execute）
+- 不要把内部实现字段塞进 provides；只暴露给其他 task 的对外契约形状
+- related_tests 是可选字段：当本 task 改动会导致既有测试断言失效时填（判据 = 是否有既有测试因本次改动而失败，而非源文件是否共享——覆盖改共享/被多 task 依赖源文件、改被测试精确匹配的值如 UI 文案/按钮文本/错误信息/常量/枚举字面量、改函数签名或返回结构等单文件场景），列出失效测试文件 + 为何失效。关键：这些测试路径必须同时写进本 task 的 allowed_paths（否则子代理被 allowed_paths 铁律锁死、改不了测试 → 退化成主代理事后兜底）；若测试由独立的测试 task 负责，则在该测试 task 的 allowed_paths 覆盖、本字段留空
+- 如果存在 decisions.md，无法覆盖的 D-xxx@vN 在 constraints 中标注
+- **保存前格式自检**（plan-postcheck 会硬校验，不通过到 Step 4 会批量报错，先在这里逐条自查）：
+  - **硬校验字段**（缺失 plan-postcheck 直接报错阻断，必须齐全）：id、title、title_zh、allowed_paths、goal、implementation、acceptance、verify、constraints
+  - **规范约定字段**（应填但不硬校验，缺失不阻断完成、只影响规范性）：author、created_at、priority、depends_on、blocks
+  - allowed_paths 非空（至少一个真实源文件路径；回归类 task 无源码改动时填被验证的关键入口文件）
+  - acceptance 与 verify 都在 frontmatter 内（漏写会被 plan-postcheck 报「缺少验收标准」/「缺少验证步骤」）
+- **生成方式**：用 `sillyspec taskcard <change-name> --task task-NN [--all]` 生成安全骨架（LF 行尾 + frontmatter 必闭合 + 九个硬校验字段齐全 + author/created_at 自动填），再往骨架里填语义内容——**勿用 Write tool 整文件手写**（CRLF / 漏闭合 `---` / 漏字段的根源，postcheck 报错大多由此来）；已存在的卡命令会跳过不覆盖，局部修改用 Edit 定点改

package/.claude/worktrees/sillyspec-data-model-research/templates/prompts/testcase-design.md

@@ -0,0 +1,12 @@
+### 测试用例设计（写测试时按此检查）
+
+写测试是为了拦住回归，不是"有测试文件"。
+**基础习惯照做、不展开**：FIRST（快/独立/可重复/自校验/及时）、金字塔分层（单元为主/集成少量/E2E 只冒烟）、AAA 结构、测试名描述场景、测试数据轻量构造（Object Mother/Builder）、覆盖率不追数字。
+
+逐条对照检查：
+1. **覆盖**：正常路径 + 边界 + 异常/非法输入，不只写业务正例；单测全绿 ≠ 集成正确。
+2. **断言**：断言真实输出/副作用，禁止只"不抛错"的空断言；不 mock 被测方法自身。
+3. **行为 vs 实现**：走公开 API 测行为；重构后功能不变，测试不应失败。
+4. **契约与回归**：覆盖本次改动会破坏的既有行为与相邻模块接口；改公共签名/文案/常量时同步修复受影响既有测试并跑全量，禁止删断言凑绿。
+5. **时间敏感分支**：超时/重试/并发分支别真等——超时参数做成可注入，测试传毫秒级极小值或注入可控时钟推进，再断言超时后的行为（走哪个分支/返回什么/资源是否回收）。
+6. **隔离确定性**：独立 fixture、可重复跑，不依赖共享状态/执行顺序。

package/.claude/worktrees/sillyspec-data-model-research/templates/prompts/verify-probes.md

@@ -0,0 +1,32 @@
+### 自动探针（必须先执行）
+
+> 🔧 **先跑 CLI 机械探针（一条命令）**：`sillyspec verify-probes --change <change-name> [--init]`
+> 输出已包含四个纯机械探针的结果（可直接进验证报告）：**探针 1** 未实现标记扫描（design 清单文件逐行 TODO/FIXME 命中 + 行号）、**探针 3** 测试文件递归查找（含 co-located tests/，逐 task 覆盖）、**探针 5** API 契约对账表（endpoints.json × 前端调用 diff）、**探针 6** 删除对账三态（git 事实 × design 声明）。`--init` 顺带生成 verify-result.md 九章节骨架（探针结果已预填，`<!--TODO-->` 占位替换即可）。
+>
+> 下列条目中，只有**半语义部分**需要你执行：探针 2（关键词提取）、探针 3.4 集成盲区标注、探针 3.5 断言有效性抽查、探针 4（决策追踪闭环判定）。CLI 已跑的部分勿重复手跑——对 CLI 输出的 warning 项做语义复核即可。
+
+**探针 2：设计关键词覆盖探针（你执行——关键词提取是语义）**
+1. 读取 design.md，从中提取所有能力关键词（如"登录"、"导出"、"批量"、"删除"、"搜索"等动作词）
+2. 对每个关键词，在源码目录中 grep 确认是否有对应的实现代码：
+```bash
+grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" --include="*.py"
+```
+3. 如果某个关键词在源码中完全没有匹配，标记为 ⚠️ 可能未实现
+
+**探针 3 补充（CLI 已查存在性，你补语义）**
+- **集成盲区提示**：测试文件存在 ≠ 集成正确——路由/layout 守卫重定向、跨模块装配这类集成 bug 组件单测覆盖不到，只有集成/冒烟/E2E 才暴露。对路由/layout/跨进程装配敏感的 task，额外检查是否有集成冒烟覆盖；无则标 ⚠️ 集成层未验证（需人工或部署确认）
+- **断言有效性抽查（与 execute「测试用例设计」闭环）**：测试文件存在 ≠ 测试有效。对最能代表本次变更行为的 2-3 个核心测试做抽查：① 断言验证真实输出/副作用，不是只"不抛错"的空断言、只测 getter/setter；② 覆盖边界/异常分支，不只业务正例；③ 走公开 API 测行为，不测实现细节（重构后功能不变测试不应失败）。不达标标 ⚠️ 断言薄弱或无效（advisory：CLI 不阻断，是否 FAIL 由你诚实判定；execute 已按「测试用例设计」写的，这里只抽查核验，不重审全量）
+
+**探针 4：决策追踪覆盖探针（如存在 decisions.md——闭环图机械，证据真伪是语义）**
+1. 从 decisions.md 提取所有当前版本 D-xxx@vN
+2. 检查 requirements.md 是否引用每个 D-xxx@vN，并映射到 FR-xxx
+3. 检查 plan.md 或 tasks/task-NN.md 是否引用每个 FR-xxx/D-xxx@vN
+4. 检查本步骤收集的实现证据是否能回指到对应 D-xxx@vN/FR-xxx
+5. 任意 D-xxx@vN 无下游覆盖时标记为 ⚠️ 决策未闭环
+6. 任意 P0/P1 unresolved/blocking 决策标记为 FAIL blocker
+
+**探针 5 补充（CLI 已出对账表，你做诚实判定）**
+CLI 的 missing backend endpoint 是 advisory（不硬阻断归档）——但 contract gap 是真实集成缺陷，应诚实标 FAIL 并回 execute 补端点，勿因 CLI 不拦而放行。后端 router 的端点清单可用 `sillyspec endpoints extract --change <变更名> --task <task-NN>` 重新静态提取（勿手扫装饰器）。
+
+**探针 6 补充（CLI 已出三态判定，你做终审）**
+以 git 事实为准（真实 > 声明）；CLI 的三态（合规/高风险/未声明）是机械判定，是否构成 FAIL blocker 由你诚实判定，务必如实记录——静默删除代码是 verify 的最大盲区。

package/.claude/worktrees/sillyspec-data-model-research/templates/workflows/archive-impact.yaml

@@ -0,0 +1,79 @@
+name: archive-impact
+description: 分析变更影响的模块并同步模块文档
+spec_version: 1
+
+roles:
+  - id: impact-analyzer
+    name: "影响分析"
+    task: "分析 git diff，提取变更影响模块"
+    inputs:
+      paths: [".sillyspec/changes/", ".sillyspec/docs/*/modules/"]
+      hints:
+        grep_patterns: ["_module-map", "module-impact", "git diff"]
+    outputs:
+      - path: ".sillyspec/changes/<change-name>/module-impact.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 20
+          - type: contains_sections
+            sections: ["模块影响矩阵", "未匹配文件"]
+    constraints:
+      - "以 git diff 为准（真实 > 声明）"
+      - "影响类型：逻辑变更/数据结构变更/接口变更/调用关系变更/配置变更/新增"
+      - "需要 review 标记不确定的影响"
+
+  - id: doc-syncer
+    name: "文档同步"
+    task: "根据 module-impact.md 同步更新模块索引和卡片"
+    depends_on:
+      - impact-analyzer
+    inputs:
+      from_role: impact-analyzer
+      output: module-impact
+      output_description: "变更影响分析结果，包含模块影响矩阵"
+      paths: [".sillyspec/docs/*/modules/"]
+      hints:
+        grep_patterns: ["_module-map", "module-impact"]
+    outputs:
+      - path: ".sillyspec/docs/sillyspec/modules/_module-map.yaml"
+        required: false
+        checks:
+          - type: file_exists
+      - path: ".sillyspec/docs/sillyspec/modules/<module-id>.md"
+        required: false
+        # checks 跳过：路径含动态 <module-id> 占位符，不适合静态检查
+    constraints:
+      - "结构化事实改 _module-map.yaml，语义解释改模块卡片"
+      - "人工备注区域永远保护，不覆盖"
+      - "更新前展示 diff 摘要，请用户确认"
+
+orchestration:
+  mode: sequential
+  timeout_per_role: 180
+
+checks:
+  role_level:
+    - type: file_exists
+    - type: min_lines
+      min: 10
+  workflow_level:
+    - type: file_exists
+      path: ".sillyspec/changes/<change-name>/module-impact.md"
+
+retry:
+  max_attempts: 1
+  include_failure_context: true
+  retry_scope: failed_role_only
+
+on_check_failure: prompt_retry
+
+permissions:
+  write_mode: patch_only
+  write_scope:
+    - ".sillyspec/docs/"
+    - ".sillyspec/changes/<change-name>/"
+  allow_shell: true
+  allow_network: false
+  allow_git: true

package/.claude/worktrees/sillyspec-data-model-research/templates/workflows/scan-docs.yaml

@@ -0,0 +1,132 @@
+name: scan-docs
+description: 并行生成项目的扫描文档（7份）
+spec_version: 1
+
+roles:
+  - id: arch
+    name: "技术架构"
+    task: "生成 ARCHITECTURE.md"
+    inputs:
+      paths:
+        - "src/*.js"
+        - "package.json"
+      hints:
+        grep_patterns: ["class ", "export ", "import ", "schema", "CREATE TABLE"]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/ARCHITECTURE.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 20
+          - type: contains_sections
+            sections: ["技术栈", "架构概览"]
+    constraints:
+      - "禁止读源码全文，只用 grep/rg 搜索"
+      - "Schema 只记表名+说明+字段数"
+
+  - id: conventions
+    name: "代码约定"
+    task: "生成 CONVENTIONS.md"
+    inputs:
+      paths: ["src/"]
+      hints:
+        grep_patterns: ["function ", "const ", "async ", "try ", "catch "]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/CONVENTIONS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+          - type: contains_sections
+            sections: ["框架隐形规则", "代码风格"]
+    constraints:
+      - "禁止读源码全文"
+      - "提取 3-5 个典型模式"
+
+  - id: structure
+    name: "目录结构+外部集成"
+    task: "生成 STRUCTURE.md 和 INTEGRATIONS.md"
+    inputs:
+      paths: ["./"]
+      hints:
+        grep_patterns: ["fetch", "http", "WebSocket", "ws", "chokidar"]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/STRUCTURE.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+      - path: "{SPEC_ROOT}/docs/<project>/scan/INTEGRATIONS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+    constraints:
+      - "STRUCTURE: 目录树+模块说明"
+      - "INTEGRATIONS: 按类型分组外部依赖"
+
+  - id: quality
+    name: "测试+债务+概览"
+    task: "生成 TESTING.md、CONCERNS.md、PROJECT.md"
+    inputs:
+      paths: ["src/", "packages/"]
+      hints:
+        grep_patterns: ["TODO", "FIXME", "deprecated", "test", "describe"]
+    outputs:
+      - path: "{SPEC_ROOT}/docs/<project>/scan/TESTING.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 10
+          - type: no_placeholder
+      - path: "{SPEC_ROOT}/docs/<project>/scan/CONCERNS.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 10
+          - type: contains_sections
+            sections: ["代码质量", "依赖风险"]
+      - path: "{SPEC_ROOT}/docs/<project>/scan/PROJECT.md"
+        required: true
+        checks:
+          - type: file_exists
+          - type: min_lines
+            min: 15
+          - type: contains_sections
+            sections: ["项目简介", "技术栈"]
+    constraints:
+      - "CONCERNS 按严重程度分组（🔴/🟡/🟢）"
+      - "不编造不存在的测试"
+
+orchestration:
+  mode: parallel
+  max_concurrent: 4
+  timeout_per_role: 120
+
+checks:
+  workflow_level:
+    - type: file_count
+      path: "scan/"
+      min: 7
+    - type: no_empty_files
+
+retry:
+  max_attempts: 1
+  include_failure_context: true
+  retry_scope: failed_role_only
+
+on_check_failure: prompt_retry
+
+permissions:
+  write_mode: direct
+  write_scope:
+    - "{SPEC_ROOT}/docs/<project>/scan/"
+  allow_shell: true
+  allow_network: false
+  allow_git: false

package/README.md

@@ -141,7 +141,7 @@ sillyspec doctor                 全量自检 + 修复进度
 - **进度持久化** — SQLite（node:sqlite）持久化，支持断点恢复
 - **模块文档** — 模块级知识库，AI 执行时按需加载相关上下文
 - **浏览器自动化** — 可选 MCP（Playwright / Chrome DevTools），供集成/E2E 冒烟验证
-- **平台同步** — 可选对接 SillyHub，文档同步 + 团队审批
+- **平台同步** — 可选对接 SillyHub，文档同步 + 团队审批 + 本地 agent 会话日志路径主动上报（平台会话展示本地 agent 完整日志；支持 Claude Code / Codex / ZCode 自动探测，其他 CLI 用 `SILLYSPEC_AGENT_LOG` 显式指定）
 
 ## 可靠性保障
 

package/eval/README.md

@@ -0,0 +1,86 @@
+# SillySpec A/B 评测
+
+客观量化回答一个问题：**同一个 agent，走 SillySpec 流程（B 臂）比裸跑（A 臂）到底好多少？**
+
+- 同任务、同模型、同判分脚本（每任务一个 `verify.mjs`，退出码 0 = 通过），唯一变量是「有没有 SillySpec」。
+- 产出：分臂通过率 + Wilson 95% 置信区间、Δ(B−A) 区间、flaky 剔除、token/费用/耗时、基线回归对比。
+- 所有结果落 SQLite（`eval/results/eval.db`），可审计、可复跑。
+
+## 快速开始
+
+```bash
+node eval/run.mjs --dry-run        # ① 零 token：假 agent 验证整条管道（先跑这个）
+node eval/run.mjs --preflight      # ② 零 token：检查 Node 版本与 agent CLI 可用
+node eval/run.mjs --pilot          # ③ 真跑：前 20 个任务 × 双臂（从这里开始烧 token）
+node eval/run.mjs --report         # 查看报告
+node eval/run.mjs --set-baseline   # 成绩满意后固化为回归基线（发版前对比）
+```
+
+npm 快捷方式：`npm run eval:dry`、`npm run eval:pilot`。
+
+## 认证与 apikey（重要）
+
+**不需要把 apikey 配置在本评测的任何脚本或配置文件里。**
+
+CLI 适配器只是以子进程方式调起你本机的 headless agent CLI（默认 `claude -p`，可换 zcode / codex 等），认证完全沿用该 CLI 自己的登录态或它读取的环境变量——你之前怎么用它，评测就怎么用。评测脚本不接管、不存储、不转发任何密钥，`eval.config.json` 可以安全提交。
+
+前置条件只有一条：目标 agent CLI 已安装、已登录、终端里能跑通。拿不准就先 `node eval/run.mjs --preflight`。
+
+未来若要接裸 API（如 GLM 的 OpenAI 兼容端点）跑自研 agent 循环，那才需要环境变量方式的 key（同样是环境变量，不进脚本）——届时新增一个 adapter 即可。
+
+## 命令一览
+
+| 命令 | 用途 | token 消耗 |
+|---|---|---|
+| `--dry-run[=mixed\|pass\|fail]` | 假 agent 跑管道（mixed 会确定性制造两臂差异） | 0 |
+| `--preflight` | Node 版本 + agent CLI 探活 | 0 |
+| `--pilot` | 前 20 任务双臂真跑 | 真实消耗 |
+| `--task <id>` / `--arm A\|B` / `--sample N` | 收窄范围 | 按范围 |
+| `--rerun-failed` | 只重跑上轮 fail/timeout/error | 定向，省钱 |
+| `--force` | 忽略缓存强制重跑 | 按范围 |
+| `--report [--dry-run]` | 报告（CI / Δ / flaky / 基线） | 0 |
+| `--set-baseline` | 固化当前成绩为回归基线 | 0 |
+
+## 省 token 机制（内建）
+
+1. **缓存**：同 `(config_hash, task, arm)` 已有 pass/fail 终态自动跳过；改了提示词/流程/任务内容会换 hash，只重跑受影响部分。
+2. **定向重跑**：`--rerun-failed` 不碰已通过的任务。
+3. **双重熔断**：单任务 agent 超时（`adapter.timeoutMs`）+ 判分超时（`verifyTimeoutMs`），死循环烧不穿。
+4. **dry-run / preflight 全零 token**，烧钱的大跑之前管道一定先验通。
+
+## 任务格式
+
+每个任务一个目录，四件套：
+
+```
+eval/tasks/001-slugify/
+├── task.json     # id / instruction（两臂收到同一份需求文本）
+├── verify.mjs    # 判分：以被测工作目录为 cwd 执行，退出码 0 = 通过
+├── files/        # 工作副本脚手架（复制后交给 agent；棕地任务在这里放待改代码）
+└── solution/     # 参考解（仅 dry-run 假 agent 使用，不参与指纹）
+```
+
+写任务的要点：instruction 必须无歧义（判分才有唯一正确解）；verify 只看行为不看出身。当前 3 个种子任务偏小（用于验管道），正式 pilot 前应扩充到 20+，并逐步引入更贴近 SillySpec 甜区的中等规模功能任务。后续如需对接 Terminal-Bench 2.0 等外部任务源，写一个「外部任务 → 本格式」的导入器即可，编排与报告层不用动。
+
+## 配置（eval.config.json）
+
+- `arms.A / arms.B`：两臂的 `setup`（agent 进场前执行的命令，B 臂默认 `npx sillyspec init`；dry-run 跳过）与 `promptTemplate`（`{instruction}` 占位）。
+- `adapter`：`command` 数组 + `stdin: "prompt"`（prompt 走 stdin，规避跨平台引号问题；也可在 command 里用 `{prompt}` 占位改为参数注入）；`{workdir}` / `{maxTurns}` 占位可用；`parseStdoutJson: true` 时尽力从 stdout JSON 提取 token/费用（提不到记 null，不瞎填）。
+- 换被测 agent：改 `adapter.tool` + `adapter.command`（如 zcode / codex 的 headless 形式），两臂 prompt 模板不用动。
+
+## 目录
+
+```
+eval/
+├── run.mjs            # 入口
+├── eval.config.json   # 配置（无密钥，可提交）
+├── lib/               # 编排/报告/适配器/DB
+├── tasks/             # 任务集
+└── results/           # 运行产物（eval.db / 工作副本 / 日志 / baseline.json）——已 gitignore
+```
+
+## 已知边界
+
+- 通过率只统计 pass/fail；timeout / error（agent 崩溃、臂 setup 失败）单列不计入分母，避免把管道故障算成 agent 失败。
+- 同任务同臂多次运行结果摇摆会被标记 flaky 并从通过率剔除——放量前建议每任务跑 2 次，flaky 高说明任务本身不稳定，先修任务。
+- 单臂 n < 30 时报告会提示区间仅供方向参考。

package/eval/eval.config.json

@@ -0,0 +1,28 @@
+{
+  "tasksDir": "./tasks",
+  "resultsDir": "./results",
+  "defaultSample": 20,
+  "verifyTimeoutMs": 120000,
+  "regressionThresholdPp": 5,
+  "arms": {
+    "A": {
+      "label": "裸agent",
+      "setup": [],
+      "promptTemplate": "你在当前目录工作，直接完成以下需求（不要提问，直接实现，确保代码可运行）：\n\n{instruction}"
+    },
+    "B": {
+      "label": "SillySpec",
+      "setup": ["npx sillyspec init --dir {workdir} --tool {tool}"],
+      "promptTemplate": "当前项目已安装 SillySpec 工作流。请按 SillySpec 流程完成以下需求（小任务走 quick 模式），完成后确保代码可运行：\n\n{instruction}"
+    }
+  },
+  "adapter": {
+    "type": "cli",
+    "tool": "claude",
+    "command": ["claude", "-p", "--output-format", "json", "--max-turns", "{maxTurns}"],
+    "stdin": "prompt",
+    "timeoutMs": 900000,
+    "maxTurns": 60,
+    "parseStdoutJson": true
+  }
+}

package/eval/lib/adapters/cli.mjs

@@ -0,0 +1,63 @@
+// CLI 适配器：以子进程调起本机 headless agent CLI（claude -p / zcode / codex 等，见 eval.config.json）。
+// 认证沿用该 CLI 自身的登录态或其读取的环境变量——本评测不接管、不存储任何密钥。
+// prompt 默认经 stdin 注入（{prompt} 占位符是备选），规避跨平台引号转义。
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnCapture } from '../util.mjs';
+
+export async function run({ adapter, prompt, workdir, logDir }) {
+  const timeoutMs = adapter.timeoutMs ?? 900_000;
+  const replacements = {
+    '{workdir}': workdir,
+    '{maxTurns}': String(adapter.maxTurns ?? 0),
+    '{tool}': adapter.tool ?? '',
+  };
+  let args = adapter.command.map((a) => {
+    let s = String(a);
+    for (const [k, v] of Object.entries(replacements)) s = s.replaceAll(k, v);
+    return s;
+  });
+  const viaStdin = (adapter.stdin ?? 'prompt') === 'prompt' && !args.some((a) => a.includes('{prompt}'));
+  args = args.map((a) => a.replaceAll('{prompt}', prompt));
+
+  mkdirSync(logDir, { recursive: true });
+  writeFileSync(join(logDir, 'prompt.txt'), prompt, 'utf8');
+  const res = await spawnCapture({ args, cwd: workdir, timeoutMs, input: viaStdin ? prompt : null });
+  try {
+    writeFileSync(join(logDir, 'stdout.txt'), res.stdout, 'utf8');
+    writeFileSync(join(logDir, 'stderr.txt'), res.stderr, 'utf8');
+  } catch { /* 日志落盘失败不影响评测本身 */ }
+
+  const usage = adapter.parseStdoutJson ? extractUsage(res.stdout) : {};
+  return {
+    code: res.code,
+    timedOut: res.timedOut,
+    stdout: res.stdout,
+    stderr: res.stderr,
+    tokensIn: usage.tokensIn ?? null,
+    tokensOut: usage.tokensOut ?? null,
+    costUsd: usage.costUsd ?? null,
+    logDir,
+  };
+}
+
+// 宽松提取 token/费用字段：兼容 claude -p --output-format json 等常见 stdout 形状，
+// 提不到就留空（null），报告里显示为缺测而非 0。
+function extractUsage(stdout) {
+  const trimmed = (stdout ?? '').trim();
+  if (!trimmed.startsWith('{')) return {};
+  let obj = null;
+  for (const candidate of [trimmed, trimmed.split('\n').pop()]) {
+    try { obj = JSON.parse(candidate); break; } catch { /* 试下一候选 */ }
+  }
+  if (!obj || typeof obj !== 'object') return {};
+  const out = {};
+  const scan = (o) => {
+    if (!o || typeof o !== 'object') return;
+    if (typeof o.input_tokens === 'number') out.tokensIn ??= o.input_tokens;
+    if (typeof o.output_tokens === 'number') out.tokensOut ??= o.output_tokens;
+    if (typeof o.total_cost_usd === 'number') out.costUsd ??= o.total_cost_usd;
+  };
+  scan(obj); scan(obj.usage); scan(obj.cost); scan(obj.message?.usage);
+  return out;
+}

package/eval/lib/adapters/dryrun.mjs

@@ -0,0 +1,27 @@
+// dry-run 假 agent：零 token 验证管道（工作副本、verify、落库、报告整条链路）。
+// mixed 模式确定性制造两臂差异：A 臂全过，B 臂按任务号奇偶过——报告能展示通过率/Δ/置信区间的完整形态。
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { copyInto } from '../workdir.mjs';
+
+export function run({ task, arm, workdir, solutionDir, mode = 'mixed' }) {
+  const numeric = Number.parseInt(String(task.id).split('-')[0], 10);
+  let pass;
+  if (mode === 'pass') pass = true;
+  else if (mode === 'fail') pass = false;
+  else pass = arm === 'A' ? true : Number.isInteger(numeric) && numeric % 2 === 1;
+
+  if (pass) copyInto(workdir, solutionDir);
+  else writeFileSync(join(workdir, 'DRY_RUN_WRONG_ANSWER.mjs'), '// dry-run 失败路径占位产物\n');
+
+  return {
+    code: 0,
+    timedOut: false,
+    stdout: `[dry-run mode=${mode}] pass=${pass}`,
+    stderr: '',
+    tokensIn: 0,
+    tokensOut: 0,
+    costUsd: 0,
+    logDir: null,
+  };
+}

package/eval/lib/config.mjs

@@ -0,0 +1,82 @@
+// eval 配置加载 + 实验指纹（config hash）：改动任务内容/臂定义/适配器/版本都会换新分组，
+// 旧缓存不再命中，报告也不会把两轮不同实验混在一起。
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { sha256, stableStringify } from './util.mjs';
+
+export const EVAL_ROOT = dirname(dirname(fileURLToPath(import.meta.url))); // eval/
+export const EVAL_SCHEMA_VERSION = 1;
+
+// 与 eval/eval.config.json 保持同构；文件缺失/部分字段缺失时以此兜底
+const DEFAULTS = {
+  tasksDir: './tasks',
+  resultsDir: './results',
+  defaultSample: 20,
+  verifyTimeoutMs: 120_000,
+  regressionThresholdPp: 5,
+  arms: {
+    A: {
+      label: '裸agent',
+      setup: [],
+      promptTemplate: '你在当前目录工作，直接完成以下需求（不要提问，直接实现，确保代码可运行）：\n\n{instruction}',
+    },
+    B: {
+      label: 'SillySpec',
+      setup: ['npx sillyspec init --dir {workdir} --tool {tool}'],
+      promptTemplate: '当前项目已安装 SillySpec 工作流。请按 SillySpec 流程完成以下需求（小任务走 quick 模式），完成后确保代码可运行：\n\n{instruction}',
+    },
+  },
+  adapter: {
+    type: 'cli',
+    tool: 'claude',
+    command: ['claude', '-p', '--output-format', 'json', '--max-turns', '{maxTurns}'],
+    stdin: 'prompt',
+    timeoutMs: 900_000,
+    maxTurns: 60,
+    parseStdoutJson: true,
+  },
+};
+
+function deepMerge(target, src) {
+  for (const key of Object.keys(src)) {
+    const sv = src[key];
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])) {
+      deepMerge(target[key], sv);
+    } else {
+      target[key] = sv;
+    }
+  }
+  return target;
+}
+
+export function loadConfig(configPath = resolve(EVAL_ROOT, 'eval.config.json')) {
+  let file = {};
+  if (existsSync(configPath)) file = JSON.parse(readFileSync(configPath, 'utf8'));
+  const config = deepMerge(structuredClone(DEFAULTS), file);
+  config.tasksDir = resolve(EVAL_ROOT, config.tasksDir);
+  config.resultsDir = resolve(EVAL_ROOT, config.resultsDir);
+  config._path = configPath;
+  return config;
+}
+
+export function sillyspecVersion() {
+  const pkg = JSON.parse(readFileSync(resolve(EVAL_ROOT, '..', 'package.json'), 'utf8'));
+  return pkg.version;
+}
+
+/**
+ * 实验分组哈希：臂定义（prompt/setup）+ 适配器 + 任务指纹 + SillySpec 版本 + schema 版本。
+ * 注意 tasksDir/resultsDir 不参与——目录挪位置不该让实验换组。
+ */
+export function computeConfigHash(config, adapterType, tasksFingerprint) {
+  const payload = {
+    schema: EVAL_SCHEMA_VERSION,
+    adapterType,
+    arms: config.arms,
+    adapter: config.adapter,
+    tasksFingerprint,
+    sillyspecVersion: sillyspecVersion(),
+  };
+  return sha256(stableStringify(payload)).slice(0, 12);
+}