sillyspec 3.33.8 → 3.33.9

package/AGENTS.md

@@ -33,7 +33,7 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 1. **禁止绕过本文件规则和 SillySpec 流程**。所有变更走 sillyspec 流程，不裸改裸提交。
 2. **改代码前必须先说明依据**——依据的文档路径（design.md / 模块文档 / file-lifecycle.md（如有））或现有代码依据，无依据不改。
 3. **执行顺序**：文档 → 读代码 → 写测试 → 写实现 → 跑测试 → 验收 → 更新文档（轻量道即：FR 绑定+design 四节+用户批准先于动码，读代码探究不算动码）。测试按层适用：纯逻辑先写测试，行为契约断言用户可见行为，视觉样式与纯配置/文档不写测试（记「不适用：理由」，验收靠规范与人工）。
-4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`（未配置/标 `unavailable` → 收口跳过并留痕理由，归 pre-push/CI 门——pre-push 已跑同款 lint 的仓可标 unavailable 免重复）。以落盘文件与测试结果为准，不信口头"已完成"。自验口径＝变更测试面（新增测试+受影响既有面）即收口证据（lint 已配置时一并实测；标 `unavailable` 的仓归 git 钩子/CI 门）——全量套件归 pre-push 门，勿每变更重复手跑（共享仓全量红先做归属判别，非本变更引入如实留痕不阻断）；跑批输出落 `.sillyspec/.runtime/logs/` 日志回看尾部，勿整段吞掉。
+4. **实证核验再收口**：触及 `src`/`test` 的改动，CLI 会在收口时亲自实测（实测失败阻断收口；纯 doc/配置自动跳过）。测试面按变更动态推断（本变更测试 ∪ FR 关联回归 ∪ import 依赖，runner 自项目结构推断——无需配置）；lint 走 `.sillyspec/local.yaml` 的 `commands.lint`（未配置/标 `unavailable` → 收口跳过并留痕理由，归 pre-push/CI 门——pre-push 已跑同款 lint 的仓可标 unavailable 免重复）；指标门同款可选：`commands.metrics` 配置后收口实测该命令（非零退出阻断；未配置/`unavailable` 跳过留痕）——适合复杂度/重复率/死代码/覆盖率阈值类秒级检查（命令开放不绑定工具，`npx` 工具或 mvn/gradle 检查目标均可；执行时注入 `SILLYSPEC_CHANGE_FILES` 变更文件清单，大仓可只扫变更面），变异测试等慢工具建议 pre-push/CI；多语言/monorepo 仓可用 `metrics_routes` 路由门按路径集合配多个 gate（仅跑变更命中的 gate，gate 子进程注入 `SILLYSPEC_CHANGE_FILES`=该 gate 命中子集）。以落盘文件与测试结果为准，不信口头"已完成"。自验口径＝变更测试面（新增测试+受影响既有面）即收口证据（lint 已配置时一并实测；标 `unavailable` 的仓归 git 钩子/CI 门）——全量套件归 pre-push 门，勿每变更重复手跑（共享仓全量红先做归属判别，非本变更引入如实留痕不阻断）；跑批输出落 `.sillyspec/.runtime/logs/` 日志回看尾部，勿整段吞掉。
 5. **非测试逻辑本身有误时，禁止改测试来"通过"**——修逻辑，不修测试。
 6. **git hook 拦截提交时禁止跳过**（如 `.husky/pre-push`），修复问题后再提交。
 7. **代码必须兼容 Windows / Linux / macOS**（路径 / 换行 / 并发都要顾）。
@@ -45,4 +45,5 @@ sillyspec flow start --change <YYYY-MM-DD-名> --input "<一句 10-30 字中文
 13. **边干边勾（任务进度唯一源=变更的 tasks.md）**：完成一个任务单元（实现到位 + 相关测试跑绿）当场勾对应格——`sillyspec task tick --change <名> --task task-NN`（即时回显进度与下一任务）或直接 Edit 翻格 `- [ ]`→`- [x]`，勿攒到收口一把勾。harness 自带的 TodoWrite 类工具是会话内便利面，不替代 tasks.md——平台进度投影、收口哨兵、断点恢复只读 tasks.md。
 14. **推送前压扁**：本地未推送提交统一走 `sillyspec push`（默认 by-change；`--mode one` 需明确归属），禁止直接 `git push`、`git push --force` 或手工 `git reset --soft` 压扁；已推送历史不改写，并行会话的 staged 文件/Dirty 文件不替人提交或清理。
 
-00. **不要枚举定义开放世界 以及 不要限制死 开发语言和框架**
+00. **不要枚举定义开放世界 以及 不要限制死 开发语言和框架**
+    - 反例（任务词汇）：评测工具缺省写死两个仓的路径即违规——每条路径必须来自 `--repo` 参数或缺省当前仓；出现具体项目名/项目特定 env/硬编码仓表即违规（2026-11-02 用户原话纠正实证：「这工具是给无限制的项目使用的」）

package/eval/knowledge/README.md

@@ -0,0 +1,119 @@
+# 知识检索评测面（eval/knowledge）
+
+为 SillySpec 知识库存取提供**可复跑、分消费面、带缺陷探针**的评测尺子。
+与 `eval/`（A/B 流程评测）独立：这里测的是「检索能否把对的知识送到 agent」，不是「流程是否提升任务通过率」。
+
+## 用法
+
+```bash
+node eval/knowledge/run.mjs                     # 评当前仓（缺省），读取 baseline 并对比
+node eval/knowledge/run.mjs --repo <path>       # 评任意仓（路径；可逗号分隔多个）
+node eval/knowledge/run.mjs --repo <label>:<path>,<label>:<path>   # 显式仓标签（对齐数据集 repo 字段）
+node eval/knowledge/run.mjs --face entries      # 单面
+node eval/knowledge/run.mjs --json              # 机器可读
+node eval/knowledge/run.mjs --set-baseline      # 写入 baseline.json（提交入库）
+node eval/knowledge/run.mjs --smoke             # 零数据依赖冒烟（六类探针 + baseline 往返）
+npm run eval:knowledge                          # 等价于评当前仓
+```
+
+**工具中立**：runner 不枚举任何具体项目——仓从 `--repo` 路径解析，缺省当前仓；
+仓标签取 `label:` 显式值或路径 basename。`datasets/organic.jsonl` 里的 repo 字段只是标签，
+与本仓的实例数据一起提交；换项目时替换数据集即可，工具代码零改动。
+
+## 三个数据源
+
+| 源 | 内容 | 用途 |
+|---|---|---|
+| `datasets/organic.jsonl` | 遥测 inject query 抽样 + 人工 anchor 级标签（已冻结，不随遥测漂移） | **主质量指标** |
+| self（现场构建） | 归档 `flow-state.input` → 该变更蒸馏决策的映射 | 仅链路 smoke（自产自测偏差，禁入质量指标） |
+| `fixtures/index.mjs` | 六类缺陷的最小合成知识库 | 缺陷探针（pass=修复后期望） |
+
+organic 字段：`id / repo / face(entries|decisions|search|scope) / query / expected[] / scope_files?`。
+`expected` 含 `#` 为精确 `file#anchor`；不含 `#` 为文件级前缀匹配。空 `expected` 的 case 计入
+`skipped_cases` 并披露，绝不静默当零命中。
+
+## 五个消费面与指标
+
+| 面 | 真实入口 | rendered 口径 | k |
+|---|---|---|---|
+| entries | `matchKnowledgeHybrid` 的 entries（flow 📚 行） | 前 3（不去重） | 3 |
+| decisions | `matchKnowledgeHybrid` 的 decisionHits（rejected/死路优先） | 前 5 | 5 |
+| search | `cmdSearch` 等价（hybrid + `buildSearchMatches`，file 级） | limit 10 | 10 |
+| scope | `scopeRecall` 图遍历（引擎内建 cap 3/20，raw==rendered，truncated 恒空） | entry 3 + decision 20 | 3/20 |
+| fr | `readActiveFrDigest` + query×标题重叠（FR 索引 digest 通道） | 前 8 | 8 |
+
+entries/decisions/search 与生产入口同源（hybrid 三层 + 生产构造单一源）；fr 面承载
+「FR 条目能否被 query 找到」的刻度（生产按 design 交付清单路由域，此处以标题可达性近似）。
+`file`/`fr`/`decisions` 期望在迁移后归位：entries 面只测手工知识条目，fr/decisions 文件期望
+走各自专用面（2026-11-02 复核 P1-②——旧数据集把路由行期望挂在 entries 面，rank-denoise
+的 route-rows 修复会让它们结构性 miss，数字会假性回退）。
+
+每面同时输出 **raw**（引擎命中序）与 **rendered**（消费面实际切片）两套 Top-1/Top-3/MRR。
+`truncated` = raw 命中而 rendered 未呈现的 case——用于区分「引擎没召回」与「召回了但被截断」。
+`details` 记录每 case 的 raw_rank/rendered_rank（--json 输出）。
+
+## 数据集标签自检
+
+`validateLabels` 在每次运行校验 expected 的 file 存在性与 anchor 可达性（文件正文或 INDEX
+含该锚点串），检出「结构性不可命中」标签（如 epoch 迁移后 D-id 换了域文件）并输出
+`label_issues`——标签不会随知识库演化静默腐烂。
+
+## 六类缺陷探针（probe RED = 缺陷仍在）
+
+| 探针 | 检测对象 |
+|---|---|
+| score-contract | search 视图 score 必须等于实际命中标签数（现状 `score=keywords.length`） |
+| word-boundary | `_` / `-` 是词字符：`node` 不得命中 `node_modules`、`worktree` 不得命中 `worktree_apply` |
+| route-rows | entries 不得含 `fr/`、`decisions/` 路由行（各有专用通道） |
+| scope-manual | scope 图遍历必须能返回手工文档条目（手工知识不被第一层短路） |
+| fixed-entries | known-issues「已修复/已解决」条目默认不进 entries |
+| linkage | 语料健康：决策条目总数 / 有锚点 / 有文件字段 / 任一关联 |
+
+探针按「修复后的期望」断言：当前代码带缺陷时 RED 是**正确检出**；修复后转 GREEN。
+`linkage` 是工具自身健康报告，当前应为 GREEN。
+
+## self smoke 与泄漏对照
+
+self 集只报三个数：`own_hit_top3`（查询命中自身蒸馏决策的比例）、`name_only_top3`
+（仅变更名作查询的对照）、`leak_gap = own − name_only`。leak_gap 接近 0 表示命中主要靠
+变更名同文泄漏，查询内容贡献小（D-001：leave-one-out 落地为对照而非字面剔除索引）。
+
+## 基线与快照指纹
+
+- `baseline.json` 可提交可 diff；键序固定、浮点 4 位小数。
+- 每仓记录快照指纹 `{head, knowledge_hash, knowledge_files}`；指纹不一致时输出
+  `snapshot_mismatch` 并同时给两套指标，禁止静默覆盖。
+
+## 零副作用
+
+runner 强制 `SILLYSPEC_KNOWLEDGE_VECTOR=off`、`SILLYSPEC_HITS_PUSH=0`，只调纯读引擎；
+不写 `knowledge-hits.jsonl`、不发平台请求、不写平台能力缓存。唯一写点：`--set-baseline`
+的 baseline.json 与图派生缓存（`<specRoot>/.runtime/cache/`，可再生、非遥测）。
+
+## 数据规划注记（2026-11-02-knowledge-engine-tail）
+
+下一轮数据扩容（organic 到每仓 50）必须同时满足三条，否则尺子会重复打满：
+
+1. **flow 形态带 scope_files**：生产 flow start 恒传 scopeFiles，而 eval 的 entries/decisions 常规
+   case 目前测的是「无 scope 的 hybrid」——扩容时常规 case 整体带 scope_files，fusion 子集升为主刻度。
+2. **fusion 子集升主刻度**：当前 fusion n=2、fr prod n=1，只能证明通道存在，不能证明生产效果。
+3. **混入非标题复述查询**：现有有机 case 多为「域关键词+标题」公式化查询（平台 decisions 1.0 n=9
+   已打满），扩容时纳入真实任务描述类查询，否则 decisions/entries 面失去分辨力。
+
+## 当前基线（2026-11-02，数据集面归位后）
+
+本仓的实例基线（两仓用 `--repo sillyspec:<本仓路径>,platform:<平台仓路径>` 生成；
+仓标签与数据集 repo 字段对齐——换项目时基线与数据集一起替换）：
+
+- sillyspec：entries top1/top3 1.0（n=7）、decisions 0.6（n=5）、search 1.0（n=7）、
+  scope 0.2（n=5）、fr top3 0.3333（n=3）、self own_hit 0.0291 / leak_gap 0。
+- platform：entries 0.5556/0.8889（n=9）、decisions 1.0（n=1）、fr top3 0.2（n=5）、
+  scope n=0（未标注）、self own_hit 0.0274 / leak_gap 0.0213。
+- 探针：score-contract / word-boundary / route-rows / fixed-entries 四类 GREEN（变更 1 修复），
+  scope-manual 仍 RED（变更 2 范围）、linkage GREEN。标签自检 0 问题。
+
+注意：entries/decisions 面的 n 较小（7/5/9/1），每个 case 摆动 ~10 个百分点；fr 面 top3 偏低
+（0.2~0.33）是 FR 标题可达性的真实信号，留变更 2/3 评估。scope 面平台 n=0 待补标注。
+
+后续变更（排序降噪、scope 两跳、融合）以本 baseline 为对照，验收看各面 raw/rendered 变化
+与对应探针翻转，目标 entries/search Top-3 ≥ 0.8。