# dsh-coderag — 项目文档 > **文档版本**:1.0 | **撰写日期**:2026-09-17 | **状态**:待开工 > **配套文档**:[`AGENTS.md`](./AGENTS.md)(AI 自动化开发规范与约束)——**两份必须一起读**。 > > 本文档的每个设计决策都标注了**调研依据**。依据来自 2026-09-17 完成的四类线上调研(编码 Agent、IDE 编程助手、Agent 框架、RAG 技术栈)与本机 DSH 源码的一手核实,来源集中列在第 8 章。 > > **项目名已定:`dsh-coderag`**(2026-09-17 确定,不再是占位符)。命名如下表,**全项目一律照此书写**,不得出现其他变体: | 用途 | 定名 | 出现位置 | |---|---|---| | 仓库 / 项目名 / 目录 | `dsh-coderag` | GitHub 仓库、本地目录、`package.json` 的 `name` | | Python 发行包与模块 | `dsh_coderag` | `pyproject.toml`、`import dsh_coderag`、`python -m dsh_coderag.server` | | MCP `serverName` | `coderag` | `cordis.patch.yml` 的 `config.serverName`;工具在模型侧的名字是 **`mcp__coderag__code_search`** | | 索引数据目录 | `.coderag/` | `<工作区根>/.coderag/index.sqlite3` | | 项目忽略文件 | `.coderagignore` | 工作区根 | | 环境变量 | `CODERAG_*` | `CODERAG_ROOT` / `CODERAG_MAX_FILES` / `CODERAG_MAX_TOKENS` / `CODERAG_PYTHON`;可选向量后端另用 `CODERAG_SEMANTIC`(开关,默认未设=关闭)/ `_BACKEND` / `_URL` / `_MODEL` / `_TIMEOUT` / `_BATCH` / `_MAX_CHUNKS`(冻结于 `ADR-16` §4),**云端后端**再加 `_API_KEY`(只从环境读)与 `_ALLOW_REMOTE`(非 loopback 的第二把钥匙,冻结于 `ADR-17` §4),安装侧开关为 `CODERAG_WITH_SEMANTIC` | | 开发用 DSH profile | `coderag-dev` | 本地开发,**不要用 `web`** | | 评测用 DSH profile | `eval-coderag` / `eval-baseline` | A/B 对照 | > ⚠️ 以下两个名字**看起来像但必须保持不变**,改了就错: > - **`CodeRAG-Bench`** —— 学术基准名(arXiv 2406.14497),第 2、8 章引用它 > - **`forBSH`** —— 你本机的 conda 环境名,环境搭建命令里引用它 --- ## 0. 阅读指南 ### 0.1 四份文档的分工 | 文档 | 内容 | 什么时候读 | |---|---|---| | **`AGENTS.md`** | **强制性约束**:10 条红线、6 条 DSH 环境约束、代码/安全/测试/文档/提交规范、反模式清单 | **写任何代码之前必读**,并在每个任务开始前复查 §1、§2 | | **`PROJECT.md`**(本文) | 项目概况、调研依据、架构、环境、实现方案、56 个原子任务、风险 | 开工前通读;每个任务查 §6 | | **[`EVAL.md`](./EVAL.md)** | 评测方案:三层评测、24 条评测集构造流程、失败归因表、A/B 配置、现成工具 | **做 M3 时通读**;平时遇到"检索不准"查 §2.8 | | **[`TESTING.md`](./TESTING.md)** | 测试方案:10 类必测、MCP 内存传输用法、确定性/属性/快照测试、CI | **写第一个测试之前通读** | **冲突时的优先级**:`AGENTS.md`(约束) > `EVAL.md` / `TESTING.md`(专项方案) > `PROJECT.md`(其余)。**`EVAL.md` 已取代本文 §5.8 与 §6.3 中关于评测的原始描述;`TESTING.md` 是 `AGENTS.md` §5 的展开。** ### 0.2 按角色选路径 | 你是谁 | 先读 | 再读 | |---|---|---| | 人类项目负责人 | 第 1 章(要做什么)、第 6 章(什么时候做完) | 第 7 章(风险)、《EVAL.md》§2.4(你要亲自做的 3 小时) | | AI 编码助手 | **先读 `AGENTS.md`** | 第 3 章(架构)、第 5 章(实现)、第 6 章(任务)、《TESTING.md》 | | 只想快速上手 | 第 4.3 节(环境搭建命令) | 第 6.1 节(M1 任务) | **术语约定**:非显而易见的术语在首次出现处附一句话解释。若某个术语在本项目中含义有歧义,以第 3.7 节「关键设计决策记录」为准。 --- ## 1. 项目概况 ### 1.1 一句话定义 **`dsh-coderag` 是一个以 MCP(Model Context Protocol,模型上下文协议)服务形态提供的代码库检索引擎,让 DeepSeek Harness 的 Agent 能"按语义和结构"找到代码,而不是靠猜关键词去 grep。** ### 1.2 要解决的问题 DeepSeek Harness(下称 DSH)是一个"一切皆插件"的 Agent 框架,但它**刻意没有内置任何语义检索能力**。以下是在本机 DSH 源码中逐条核实的事实: | 事实 | 源码位置 | |---|---| | 文件检索只有 `glob` 和 `grep`,底层是打包的 ripgrep,纯关键词匹配 | `packages/fs/tool-fs-search/README.md` | | 会话检索用 SQLite FTS5,但其 README 自述限制为 *"Token recall, not arbitrary substrings"* | `packages/session-query/session-query-sqlite/README.md` | | LSP 提供精确定位(跳定义/找引用),但需自行配置语言服务器,且是可选插件 | `packages/lsp/README.md` | | **全仓库没有 tree-sitter、没有 embedding、没有向量库、没有 rerank** | 全仓库 grep 零命中 | | LLM 适配器接口只有 chat,**没有 embeddings** | `packages/llm/llm/src/` | | 官方明说记忆不是 DSH 的职责,"DSH **不负责**选择模型或 embedding 提供方" | `docs/user/guide/mcp-memory.zh.md` | | 官方扩展手册把"记忆"列为"section 提供方 + 工具",**但仓库里没有这个包** | `docs/cookbook/extension-cookbook.zh.md` | **后果**:Agent 理解一个大仓库时,只能靠自己猜关键词去 grep。改一个跨 5 个文件的重构时,它猜不到另外 3 个文件的存在——这正是本项目要解决的问题。 ### 1.3 目标与非目标 **目标(必须做到)** 1. 让 DSH 的 Agent 通过一个工具调用,就能拿到**相关的代码片段 + 精确的文件名与行号**。 2. **不修改 DSH 的任何核心代码**(`packages/` 目录在整个开发过程中保持只读)。 3. 结果可被**机械验证**:有一套可重复运行的评测集,能量化"有检索 vs 无检索"的差异。 4. 可分发给他人使用:一条 `dsh plugin add` 命令完成安装。 5. 同一个检索引擎可**被其他 Agent 宿主复用**(Claude Code / Cursor / Codex 等任何支持 MCP 的客户端)。 **非目标(明确不做,避免范围蔓延)** | 不做 | 理由 | |---|---| | 通用文档 RAG(PDF/Word/网页) | 本项目只做**代码库**检索。文档 RAG 是另一套分块与解析问题 | | Web GUI 管理面板 | 第一期不做。DSH 已提供 Web UI,面板是锦上添花 | | 多用户 / 服务端部署 / 权限体系 | 单机本地工具,不做多租户 | | 替换 DSH 的 agent loop | DSH 的 loop 是它的核心资产,重造没有收益 | | 跨会话长期记忆 | 这是另一个产品(记忆),本项目只做**代码检索** | | 自动修改代码 | 本项目只提供**只读检索**。写文件由 DSH 自己的工具负责 | ### 1.4 成功标准(可量化) 项目成功的判据**不是"功能做完了",而是下面这些标准同时成立**(`S1`–`S4` 是 v1.0 的判据;`S5`/`S6` 是 v2.0.0 为可选向量后端追加的两条): | # | 标准 | 度量方式 | 阈值 | |---|---|---|---| | **S1** | **检索本身有效** | 在自建评测集上,`code_search` 的 **Success@5** | ≥ 0.80 | | **S2** | **排序质量合格** | 正确文件在结果中的平均排名 **MRR** | ≥ 0.60 | | **S3** | **端到端有提升** | 评测集任务通过率:有检索 vs 无检索 | 相对提升 ≥ 10 个百分点 | | **S4** | **成本可接受** | 单次 `code_search` 返回的 token 数 | 中位数 ≤ 4000 | > `S1`–`S4` 是本项目的稳定标识——`§6.8 覆盖矩阵` 与 `EVAL.md` 都按这些 ID 引用它们,**不要改名**;`S5`/`S6`(v2.0.0 追加)同样是稳定标识。 > **为什么把 S3 设成必要条件**:调研中有一条关键实证——Repoformer 的测量显示**最多 80% 的检索结果并不提升下游任务性能**,只有约 20% 的实例真正受益。如果 S3 不成立,说明检索在做无用功,**此时砍掉它是正确的工程决策,而不是项目失败**(依据:CodeRAG-Bench / Repoformer,见第 8 章)。 **v2.0.0 追加两条**(可选向量后端;`ADR-16` §7.1): | # | 标准 | 度量方式 | 阈值 | |---|---|---|---| | **S5** | **可选后端补齐自然语言短板** | 开启后端(`CODERAG_SEMANTIC=on`)后,**`natural` 桶**的 `Success@5`(其余口径与 L1 相同:30 条、宏平均、`k=5`) | ≥ **0.40**(沿用 `EVAL.md` §2.7 的 `natural` 桶阈值;7 条里至少 3 条命中) | | **S6** | **默认路径零回归** | **未配置** `CODERAG_SEMANTIC` 时,30 条 query 的结果与 `1.0.0` 基线**逐条一致**(逐 query diff 的回归条数,由 `T3-12` 门禁给出) | 回归条数 **= 0**,且 `exact` 桶 `S@5` 保持 **1.000** | > **S5 的适用范围**:它只约束**已发布的**向量路径。若 `T5-14` 的天花板探针给出 no-go,或 `T3-11` 按 `ADR-14` §10.4 的 **V4** 判定"C 组不能显著优于 B 组",则**该路径不发布**,`S5` 不参与判定(`ADR-16` §1.7/§7.3)。 > **S6 是 2.0.0 的硬门禁,无条件适用**:不满足 `S6` 就不算发布成功——默认安装必须与 `1.0.0` 行为一致(`RL-10` 的可验收形式)。 ### 1.5 交付形态 | ID | 交付物 | 落点 | 判据 | |---|---|---|---| | **D1** | Python 包 `dsh_coderag` | `src/dsh_coderag/` + `pyproject.toml` | `pip install .` 可安装;`dsh-coderag --version` 可用 | | **D2** | MCP 服务(stdio 传输) | `src/dsh_coderag/server.py` | 4 个工具可被任何 MCP 宿主发现并调用 | | **D3** | DSH bundle(npm 包) | 仓库根 `package.json` + `cordis.patch.yml` | `dsh plugin add` 一条命令安装 | | **D4** | 评测集与评测脚本 | `eval/tasks.jsonl` + `src/dsh_coderag/eval/` | 可重复跑出 S1–S4 的数字 | | **D5** | README(含安全声明与限制) | `README.md` | 顶部披露插件权限范围;含实测数据与已知限制 | > `D1`–`D5` 是稳定标识,被 `§6.8 覆盖矩阵` 引用,**不要改名**。 **2.0.0 的交付形态:两段式安装(默认段不变 + 可选段显式)**(`ADR-16` §7.1) | 段 | 装什么 | 命令 | 谁需要 | |---|---|---|---| | **默认段(不变)** | 只有 `mcp` / `tree-sitter` / `tree-sitter-language-pack` / `pathspec`;bundle tarball 与 `scripts/install.sh` 的**默认路径零向量依赖** | `pip install .`(或 `pip install dsh-coderag`)+ `dsh plugin add .` | **所有人**。与 `1.0.0` 完全相同的安装步骤 | | **可选段(opt-in)** | extra **`semantic`**(内容只有 `numpy`),以及用户自己装的 **Ollama + `bge-m3`** | `pip install -e ".[semantic]"` 或 `CODERAG_WITH_SEMANTIC=1 bash scripts/install.sh`,再设 `CODERAG_SEMANTIC=on` | 只有想要语义检索的人 | > **两段都不做的人也永远不会碰到向量**:不装 extra 就没有 `numpy`,不设 `CODERAG_SEMANTIC` 就不联网、行为与 `1.0.0` 逐条一致(`S6`)。**这是 `RL-10` 的可验收形式。** --- ### 1.6 分发方式与许可(**已决定,不再讨论**) #### 1.6.1 仓库布局:**仓库根同时是 npm bundle 和 Python 项目** ``` dsh-coderag/ ← 仓库根 ├── package.json ← npm bundle 清单(dsh.bundle → ./cordis.patch.yml) ├── cordis.patch.yml ← DSH 补丁层:既是 dev overlay,也是分发内容 ├── pyproject.toml ← Python 包配置 ├── src/dsh_coderag/ ← Python 引擎 ├── tests/ eval/ scripts/ docs/ ├── AGENTS.md PROJECT.md ← 约束与项目文档 ├── EVAL.md TESTING.md ← 评测方案与测试方案 ├── README.md LICENSE CHANGELOG.md └── .gitignore ``` **为什么这样放**:让**两条安装路径同时成立**—— | 安装路径 | 命令 | 为什么可行 | |---|---|---| | 本地开发 / tarball | `dsh plugin --profile
add .` 或 `add ./dsh-coderag-1.0.0.tgz` | bundle 清单在仓库根 | | 从 GitHub 直装(最终目标) | `dsh plugin --profile
add github:<你>/dsh-coderag` | npm 包必须在仓库根,pnpm 才能识别 |
| Python 引擎 | `pip install .` 或 `pip install dsh-coderag` | `pyproject.toml` 在仓库根 |
**bundle 里没有任何 JavaScript**:`cordis.patch.yml` 插入的行引用的是 DSH **内置**包 `@deepseek-ai/dsh-mcp-client`,内置包名始终从 dsh 安装目录解析。仓库自己的示例(`apps/cli/config/examples/schedule/cordis.yml`)就是这么做的。
**这顺带彻底绕开了约束 C11(pnpm 拒绝 install script)**——没有 JS 就没有构建脚本,没有 `allowBuilds` 问题。
#### 1.6.2 分发路线:**三阶段,先跑通再上架**
| 阶段 | 时机 | 做什么 | 需要账号吗 |
|---|---|---|---|
| **阶段 1** | M4 出口 | GitHub 仓库 + `scripts/install.sh` + GitHub Release 附 `pnpm pack` 出的 tarball | ❌ 不需要 |
| **阶段 2** | 项目稳定、有评测数据后 | 发布 **PyPI**(`dsh-coderag`)→ `pip install dsh-coderag` | 需要 PyPI 账号 |
| **阶段 3** | 有人真的在用之后 | 发布 **npm**(`dsh-coderag`)→ `dsh plugin add dsh-coderag` 一条命令 | 需要 npm 账号 |
**理由**:阶段 1 零门槛,能立刻验证「别人装得上吗」这个最难的问题;registry 发布是可选的锦上添花,不应该阻塞主线。两个 registry 同名(npm 与 PyPI 是独立命名空间),版本号保持一致。
**不要做的事**:不要用 npm 的 `postinstall` 去 `pip install`(约束 E-05)。Python 依赖由 `scripts/install.sh` 显式安装,README 写清步骤。
#### 1.6.3 许可:**MIT**
| 依赖 | 许可 | 是否兼容 MIT 分发 |
|---|---|---|
| `mcp`(官方 MCP Python SDK) | MIT | ✅ |
| `tree-sitter`(py-tree-sitter) | MIT | ✅ |
| `tree-sitter-language-pack` | MIT | ✅ |
| `pathspec` | MPL-2.0(文件级 copyleft) | ✅ 只要不修改 pathspec 自身的文件 |
| DSH 本身 | MIT | ✅ |
**选 MIT 的理由**:
1. **零障碍**——这是本项目最需要的。你希望别人能一条命令装上,任何额外的许可条款都会降低安装率。
2. **与生态一致**——DSH 本身是 MIT,绝大多数 DSH 插件也是 MIT。
3. **依赖全部兼容**——不需要处理任何 copyleft 传染问题。
**被否决的方案**:
- **AGPL-3.0**(`dsh-knowledge` 的选择):能防止别人拿去做闭源 SaaS,但对一个本地工具没有任何意义(用户在自己机器上跑,不构成网络服务分发),**只会白白劝退使用者**。
#### 1.6.4 可选依赖:2.0.0 的 extra(**不进默认安装**)
| 项 | 冻结内容 | 依据 |
|---|---|---|
| extra 名 | **`semantic`** | `ADR-16` §3.2 |
| extra 内容 | **只有 `numpy`**(HTTP 走标准库 `urllib.request`,因此不引入 `httpx`;不引入任何向量数据库) | `ADR-16` §3.1/§3.2 |
| 是否进 tarball | **否**。bundle 仍未含任何 JS,也仍未含任何 Python 依赖——tarball 依旧只有 `package.json` / `cordis.patch.yml` / `LICENSE` / `README.md` | `ADR-16` §7.1 |
| 是否进 `install.sh` 默认路径 | **否**。`CODERAG_WITH_SEMANTIC` 未设时脚本**不装任何向量依赖** | `ADR-16` §3.2 |
| 用户侧的另一半 | **Ollama + `bge-m3`**:由用户自己安装的系统服务,**不是**本项目的 Python 依赖,也**不是**安装前置 | `ADR-16` §3.1 |
| **可选后端之二:云端**(`CODERAG_SEMANTIC_BACKEND=openai`) | 任何兼容 **OpenAI `/v1/embeddings`** 的线上服务;**不需任何额外 Python 依赖**(HTTP 走标准库 `urllib`)。需 `CODERAG_SEMANTIC_ALLOW_REMOTE=1` 才允许非 loopback 地址,key 只从环境读(`RL-02`) | `ADR-17` §1/§2/§4 |
> ⚠️ **云端后端的安全风险(`ADR-17` §5,逐字同源)**:**开启它 = 你的部分源码文本会离开这台机器。**外发内容是已入库 chunk 的文本**及其上下文前缀行——因此包含工作区相对路径与符号名**;被三层过滤拦下的密钥文件从来没有 chunk,不会被外发;云端按 token **计费**,首次索引是全量支出(`CODERAG_SEMANTIC_MAX_CHUNKS` 是硬闸,超限显式失败);代码可能是公司资产,**外发前请自行确认授权**;API key 只从环境读、**绝不写入仓库/日志/状态**;远端地址需 `ALLOW_REMOTE=1` 且**请使用 `https://`**。**默认安装与此无关**——两条后端都默认关闭(`RL-10`)。
> **为什么不把 `numpy` 放进 `dependencies`**:默认安装的承诺是"clone + `pip install .` + 一个 YAML、零 install script"。多一个依赖就多一份装不上的概率,而**大多数用户用不到语义检索**。`RL-10` 把这条写成了红线。
- **Apache-2.0**:多了明确的专利授权,对企业用户更友好。**如果你将来发现有大公司要用,可以再换成 Apache-2.0**——两者兼容,迁移只需改 `LICENSE` 与 `package.json`/`pyproject.toml` 的 `license` 字段。
**落地动作**:`T4-07` 产出 `LICENSE` 时用 **MIT 全文**,年份 2026,版权人填你的名字或 ID。
---
## 2. 技术选型依据(调研结论 → 设计决策)
本章说明**为什么是这套方案**。每一条都对应一个已核实的调研发现。
### 2.1 同类公开项目是怎么做的
**编码 Agent 类(独立进程形态)**
| 项目 | 语言 | 代码理解方案 | 对本项目的启示 |
|---|---|---|---|
| **Aider** | Python | **tree-sitter 符号图 + 图排序**(PageRank 选最重要的片段),**明确不用 embedding** | ✅ 直接采用:tree-sitter + 图/符号排序 |
| **Cline** | TS | **完全不做索引**,官方原话 *"No RAG. No embeddings. No vector databases."*,纯 ripgrep + 符号列表 + 子代理 | ⚠️ 警示:不做索引也能用,说明检索是增强而非必需 |
| **Roo Code** | TS | tree-sitter 语义分块(1000/50 字符,无 overlap)+ Qdrant 纯向量 | ⚠️ 该项目已停服;其分块思路可借鉴,纯向量不可取 |
| **Kilo Code** | TS | 同源分块 + LanceDB/Qdrant | ⚠️ **2026-04 新版扩展一度摘掉了代码索引**(官方 issue #6144) |
| **Continue** | TS | 三套 artifact:FTS5 trigram+BM25 / tree-sitter 符号 / LanceDB 向量;内容寻址 + 分支缓存 | ✅ 最佳范本:**混合检索**与增量设计直接对标 |
| **OpenHands** | TS壳+Py核 | file search,grep 三级降级 | ✅ 采用:**永不报错,逐级降级** |
| **SWE-agent** | Python | Agent-Computer Interface | 参考其工具设计 |
**关键裁决数据(代码检索)**
| 发现 | 数字 | 来源 |
|---|---|---|
| **BM25 在代码上打败纯向量** | RepoEval NDCG@10:**BM25 93.2 vs BGE-large 80.4** | CodeRAG-Bench (arXiv 2406.14497) |
| **代码专用 embedding 在真实任务上输给 BM25** | SWE-bench-Lite:voyage-code **29.1** vs BM25 **43.0** | 同上 |
| **检索经常没用** | **最多 80% 的检索不提升性能**,仅约 20% 实例受益 | Repoformer (arXiv 2403.10059) |
| **混合检索 + 重排的收益(文档域)** | 失败率 5.7% → Contextual Embedding **3.7%**(-35%) → +BM25 **2.9%**(-49%) → +rerank **1.9%**(-67%) | Anthropic Contextual Retrieval |
> **→ 设计决策**:**第一版只做 BM25(FTS5)+ 符号结构,不做向量。** 等评测集证明 BM25 不够用,再考虑上向量。
### 2.2 为什么选「Python + MCP」而不是「原生 TypeScript 插件」
| 维度 | Windows 权重 | Python + MCP(本项目) | 原生 TS 插件 |
|---|---|---|---|
| 复用你已有的技能 | 高 | ✅ 你会 Python | ❌ 要从零学 TypeScript + Cordis |
| 不修改 DSH 源码 | 高 | ✅ 完全不动 | ✅ 不动(但要学它的插件 API) |
| 上游升级影响 | 中 | ✅ 零影响 | ⚠️ 小(插件 API 可能变) |
| 拿得到 DSH 内部能力 | 中 | ❌ 不能注入 system prompt、不能进审批链 | ✅ 全都能 |
| 用户安装难度 | 中 | ⚠️ 需要 Python | ✅ 只要 Node |
| 跨宿主复用 | 高 | ✅ Claude Code / Cursor / Codex 都能用 | ❌ 只能 DSH |
| 出第一版的时间 | 高 | ✅ 1–2 天 | ❌ 1–3 周 |
**并且已有一手先例**:社区的 `dsh-kb-rag`、`code-rag-mcp`、`dsh-memtrace` 都采用"引擎在外部、DSH 侧零代码"的范式。
> **→ 设计决策**:采用范式 C(MCP 桥接)。若将来确认需要深度集成(自动上下文注入、审批链、settings 面板),再升级为范式 A(原生插件)——**届时业务逻辑(分块、索引、检索)可整块搬移,只换外壳**。
### 2.3 为什么第一版不做向量检索(最重要的一个决定)
三条独立证据指向同一结论:
1. **BM25 在代码检索上本来就赢**(93.2 vs 80.4)。
2. **向量检索经常白做**(80% 的检索不提升性能)。
3. **一个已商业化的产品直接把它删了**:Kilo Code 在 2026-04 重建扩展时移除了代码索引。
> **→ 设计决策**:把"上不上向量"设为一个**由数据决定的决策门**(见第 6.3 节 M3-DECIDE),而不是默认架构。**M3 之前禁止引入任何 embedding 依赖。**
**v2.0.0 的范围(决策门之后的实际结果)**:决策门 `T3-07` 已裁定——R2 命中(`ADR-14`),但端到端目标已由纯词法达成,所以向量**先暂缓**(`ADR-15`),再于 2.0.0 以**可选后端**重启(`ADR-16`)。因此本节的三条证据**至今没有被推翻**,它们现在约束的是**默认路径**:
- **默认路径仍是纯 BM25**,`ADR-16` 的形态是"补齐、不替换"(RRF k=60,`exact` 桶必须保持 1.000);
- 上面第 1 条(BM25 赢纯向量)与第 2 条(80% 检索不提升)正是**为什么向量只做可选**的理由——它没有强到值得成为默认;
- 是否发布这条路径,**由 `T5-14` 的天花板探针先给 go/no-go**,再服从 `ADR-14` §10.4 的 V1–V4(V4:C 组不显著优于 B 组就不发布,`ADR-16` §7.2)。
> 换句话说:本节回答"**为什么第一版不做**",`ADR-16` 回答"**第二版怎么做成可选的**";两者不冲突。**"不做"从不等于"永远不做"**,而是"不默认做"。
### 2.4 从真实 issue 学到的硬约束(全部已核实)
这些不是"最佳实践建议",**是会导致项目失败的硬约束**:
| # | 约束 | 证据 |
|---|---|---|
| C1 | **MCP 工具调用默认 60 秒超时** → 索引必须异步(立即返回 taskId) | `packages/mcp/mcp-client/README.md`:`toolCallTimeoutMs` 默认 `60,000` |
| C2 | **stdio 子进程环境被清洗**:匹配 `/KEY\|PASSWORD\|SECRET\|TOKEN/i` 的变量与所有 `DSH_*` 都被删除 | 同上,"Environment scrubbing (stdio)" |
| C3 | **不要在 `complete: true` 的 preset 上依赖 system-prompt 注入**:会被**静默丢弃且不报错** | `packages/preset/persona/README.md` 第 49 行 |
| C4 | **MCP 工具集必须固定**:`list_changed` 重同步可能撞 namespace 抢占导致工具集清空 | DSH discussion #618 |
| C5 | **中文检索必须专门处理**:`unicode61` 匹配不了中文子串;`trigram` 分词器可以,但**最小匹配单位是 3 字**,2 字中文词("认证"、"令牌"、"重试")全部召回失败 | `session-query-sqlite/README.md` 自述 + **本机 PoC 实测**(见 §5.3.1) |
| C6 | **索引未就绪必须返回结构化状态,绝不返回空结果** | RGB 基准(arXiv 2309.01431):文档全不含答案时模型仍作答,最好拒答率仅中文 43.33% |
| C7 | **忽略规则是安全边界,不是体验优化** | Kilo issue #11637:`.kilocodeignore` 未能阻止 `read` 返回 `.env.local` |
| C8 | **批处理参数必须自适应,不能硬编码** | Roo issue #8875:硬编码 `BATCH_SEGMENT_THRESHOLD` / `BATCH_PROCESSING_CONCURRENCY` 在 4 核 i5 上卡死 VS Code |
| C9 | **文件数上限必须显式报错,不能静默截断** | Roo/Kilo 源码硬编码 `MAX_LIST_FILES_LIMIT_CODE_INDEX = 50_000`;Kilo issue #4080 的仓库有 80,138 文件,被静默截断 |
| C10 | **索引状态必须跨重启持久化** | Roo issue #5656:清空索引后忽略规则丢失,直到重启才恢复 |
| C11 | **pnpm 10+ 拒绝运行 install script,会导致插件"装了但永不加载"** | dsh-zvec-grep README + DSH discussion #656 |
| C12 | **DSH 的三档权限不约束插件,插件 = 完整机器权限** | `packages/extensions/tool-cordis/README.md` 第 182 行;`.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md` 第 145 行「安全与权限是非目标」 |
### 2.5 检索结果排序的一条实证
NVIDIA 论文(arXiv 2409.01666)在 ∞Bench 上的实测:
| 排序方式 | EN.QA F1 |
|---|---|
| 按相关度降序(vanilla RAG) | 38.40 |
| **按原文顺序(order-preserving)** | **44.43** |
同一篇论文还给出:**检索 16K token 的 F1(44.43)超过塞满 117K 上下文的 Llama3.1-70B(34.26)和 196K 的 Gemini-1.5-Pro(43.08)**;且存在**倒 U 形**——检索块数过多反而变差(8B 模型峰值在 16K,70B 在 48K)。
> **→ 设计决策**:检索时**按分数选 top-k,但输出时按(文件路径, 起始行号)重新排序**。默认返回的 token 预算控制在 4000 以内(对应 S4)。
---
## 3. 架构设计
### 3.1 分层
```
┌─────────────────────────────────────────────────────────────────────┐
│ 第 4 层 · 分发层 │
│ npm 包 dsh-coderag-dsh │
│ package.json 声明 dsh.bundle → cordis.patch.yml │
│ 用户执行:dsh plugin --profile web add github:<你>/dsh-coderag │
└──────────────────────────────┬──────────────────────────────────────┘
│ 装载一行 MCP client 配置
┌──────────────────────────────▼──────────────────────────────────────┐
│ 第 3 层 · 桥接层(DSH 官方,本项目零代码) │
│ @deepseek-ai/dsh-mcp-client │
│ · stdio 启动子进程、清洗环境变量、发现工具、注册到 ctx.tools │
│ · 工具在模型侧的名字:mcp__coderag__code_search │
└──────────────────────────────┬──────────────────────────────────────┘
│ JSON-RPC over stdio(MCP 协议)
┌──────────────────────────────▼──────────────────────────────────────┐
│ 第 2 层 · 协议层 │
│ 4 个 MCP 工具(见 3.5) │
│ 工具集固定不变(约束 C4) │
└──────────────────────────────┬──────────────────────────────────────┘
│ 进程内函数调用
┌──────────────────────────────▼──────────────────────────────────────┐
│ 第 1 层 · 引擎层(Python 包 dsh_coderag) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ walker │→ │ chunker │→ │ indexer │→ │ searcher │ │
│ │ 文件遍历 │ │ 分块 │ │ 索引 │ │ 检索 │ │
│ │ + 安全 │ │ tree- │ │ SQLite │ │ FTS5 BM25│ │
│ │ 过滤 │ │ sitter │ │ FTS5 │ │ + 顺序 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ └──────────────┴─────────────┴──────────────┘ │
│ │ │
│ ┌──────▼──────┐ ┌──────────┐ ┌──────────┐ │
│ │ taskman │ │ server │ │ eval │ │
│ │ 异步任务管理 │ │ MCP 入口 │ │ 评测 │ │
│ └─────────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────────┘
```
### 3.2 索引数据流
```
用户/模型调用 code_index(root)
│
├─► taskman.create() ──► 立刻返回 {taskId, state:"pending"} ← 约束 C1
│
└─► (后台线程/进程)
│
├─ 1. walker.walk(root)
│ ├─ 读 .gitignore + .coderagignore + 内置密钥黑名单 ← 约束 C7
│ ├─ 跳过二进制/超长行/超大文件
│ └─ 产出 [(abs_path, size, mtime_ns)]
│ │
│ └─► 文件总数 > maxFiles ? → 立刻 fail 并报告实际数量 ← 约束 C9
│
├─ 2. 增量判定:与 files 表比对 content_hash
│ └─ 只处理 新增/修改/删除 三类 ← 约束 C10
│
├─ 3. chunker.chunk(path) (逐文件,可并发但受自适应限流)
│ ├─ tree-sitter 解析 → 按声明边界切分
│ ├─ 产出 Chunk{seq, start_line, end_line, symbol, text}
│ └─ 净化:剔除密钥内容 ← 约束 C7
│
├─ 4. indexer.upsert(chunks)
│ ├─ 事务写入 chunks / chunks_fts
│ └─ 每批更新 done_chunks 进度
│
└─ 5. taskman.finish(taskId, {total, done, state:"ready"})
```
### 3.3 检索数据流
```
code_search(query, path, limit, mode)
│
├─ 0. 预检:任务状态
│ └─ 索引未就绪 → 返回 {status:"indexing", progress:0.42} ← 约束 C6
│ (绝不返回 [] 让模型误以为"代码里没有")
│
├─ 1. 查询预处理
│ ├─ 提取标识符/路径/扩展名等结构化线索
│ └─ to_bigrams() 转换 + 精度/召回双模式(见 §5.3.1)
│
├─ 2. FTS5 BM25 检索
│ └─ SELECT ... FROM chunks_fts WHERE chunks_fts MATCH ? ORDER BY bm25(...) LIMIT k
│
├─ 3. 结构化加分(可选的符号图信号)
│ ├─ 命中 symbol_name 完全匹配 → 加权
│ └─ 同文件多命中 → 轻微加权(局部性)
│
├─ 4. 截断到 limit
│
├─ 5. 【顺序保持】按 (path, start_line) 重新排序 ← 第 2.5 节依据
│
├─ 6. 预算裁剪:累加 token 估算,超过 maxTokens 就停
│
└─ 7. 渲染为模型可见文本(含文件名 + 行号 + 符号名 + chunk 序号)
```
### 3.4 模块划分
| 模块 | 文件 | 职责 | 不负责 |
|---|---|---|---|
| `config` | `src/dsh_coderag/config.py` | **运行时参数的唯一读取入口**:`load_config(environ)` 从环境变量读取全部参数并校验(见下方「配置来源」)、自适应并发/批大小推导 | 不做默认值猜测(缺失必填项要报错);**不读任何配置文件** |
| `types` | `src/dsh_coderag/types.py` | 跨模块数据类与错误码枚举 | 不含行为 |
| `parser` | `src/dsh_coderag/parser.py` | 按扩展名探测语言、提供 tree-sitter grammar/parser | 不解析语法树、不遍历工作区 |
| `text` | `src/dsh_coderag/text.py` | 中文 bigram 预转换(索引与查询两侧共用) | 不做分词决策 |
| `sanitize` | `src/dsh_coderag/sanitize.py` | 密钥文件名/路径黑名单与内容正则扫描 | 不遍历、不读文件、不写库 |
| `sqlite_caps` | `src/dsh_coderag/sqlite_caps.py` | FTS5 能力探测 | 不打开索引数据库 |
| `walker` | `src/dsh_coderag/walker.py` | 遍历工作区、应用忽略规则与密钥黑名单、上报 skip 原因与文件数上限 | 不读文件内容 |
| `chunker` | `src/dsh_coderag/chunker.py` | tree-sitter 声明感知分块、超大符号拆分、module 头、无 grammar 降级、上下文前缀 | 不写数据库 |
| `indexer` | `src/dsh_coderag/indexer.py` | SQLite schema、增量写入、幂等、三类变更、批量写库、内容级 redact、审计转储 | 不做检索 |
| `searcher` | `src/dsh_coderag/searcher.py` | FTS5 查询、打分、顺序保持、预算裁剪、标点路由、path 过滤、`code_outline` 符号树 | 不做索引 |
| `taskman` | `src/dsh_coderag/taskman.py` | 异步任务创建/进度/取消/持久化 | 不执行具体索引逻辑 |
| `render` | `src/dsh_coderag/render.py` | 把 search/status 结果渲染成模型可见文本 | 不做检索决策 |
| `log` | `src/dsh_coderag/log.py` | JSON-Lines 日志(stderr)与 `last-index.json` 审计 | 不写 stdout、不索引/检索 |
| `server` | `src/dsh_coderag/server.py` | MCP 协议实现、4 个工具注册、outline 文本渲染 | 不含业务逻辑(薄层) |
| `eval` | `src/dsh_coderag/eval/` | 评测集加载与校验、L1 运行/指标/归因/报告、L2 A/B runner、门禁 CLI(`tasks.py` / `runner.py` / `metrics.py` / `attribute.py` / `report.py` / `ab.py`) | 不参与生产检索路径;除 `ab.py` 拉起 headless DSH 外不调模型 |
#### 配置来源:**只有环境变量,没有用户配置文件**
**运行时参数 100% 从环境变量读,唯一入口是 `src/dsh_coderag/config.py` 的 `load_config(environ)`。**本项目**没有** `.coderagrc` / `config.toml` / 之类用户配置文件——这是刻意的:引擎由 DSH 以**工作区为 cwd** 拉起,放配置文件会被当成被索引内容,而用户目录又被 `S-03` 排除。
| 组 | 变量 | 默认 | 冻结于 |
|---|---|---|---|
| 基础 | `CODERAG_ROOT` | **无默认,缺失即 `ConfigError`** | — |
| 基础 | `CODERAG_MAX_FILES` / `CODERAG_MAX_TOKENS` / `CODERAG_MAX_FILE_BYTES` | `20000` / `4000` / `1048576` | — |
| 基础 | `CODERAG_BATCH_SIZE` / `CODERAG_MAX_WORKERS` | 不设则按机器自适应(`RL-07` 禁止硬编码) | — |
| 本地后端 | `CODERAG_SEMANTIC`(只有 `on` 启用)/ `_BACKEND=ollama` / `_URL` / `_MODEL` / `_TIMEOUT` / `_BATCH` / `_MAX_CHUNKS` | 关闭 / `ollama` / `http://127.0.0.1:11434` / `bge-m3` / `30` / `16` / `100000` | `ADR-16` §4 |
| 云端后端 | `_BACKEND=openai` / `_URL`(必须显式给出)/ `_MODEL`(必须显式给出)/ `_API_KEY` / `_ALLOW_REMOTE` | 关闭 / 无 / 无 / 无(缺失 → `SEMANTIC_AUTH_MISSING`,**不发起请求**)/ 未设 = 不允许 | `ADR-17` §4 |
| 安装侧 | `CODERAG_WITH_SEMANTIC`(只有 `1` 才装 extra) | 未设 = 不装 | `ADR-16` §3.2 |
| DSH 侧 | `CODERAG_PYTHON` | 作者机器路径(**请覆盖**) | `E-06`;由 `cordis.patch.yml` 的 `command:` 在宿主侧求值,不由 `config.py` 读 |
**取值规则(三条,全部已冻结)**:
1. **必填缺失要报错**,不得猜默认值(`AGENTS.md` §3.2 的既有约定);
2. **空字符串(含纯空白)= 未设**,默认值继续生效(`ADR-17` §4 冻结;沿用 `config.py` 既有的 `raw is None or not raw.strip()` 语义);
3. **不得硬编码**并发度/批大小/上限,必须可被上述变量覆盖(`RL-07`)。
**投递通道**:这些变量由 `cordis.patch.yml` 的 `config.env` **显式列出**后才可靠到达 MCP 子进程——DSH 会清洗**继承来**的环境(名字匹配 `/KEY|PASSWORD|SECRET|TOKEN/i` 与所有 `DSH_*` 的会被丢掉),**显式配置的项在清洗之后合并、能存活**(`E-02`)。因此 `CODERAG_MAX_TOKENS`(名字含 `TOKEN`)与 `CODERAG_SEMANTIC_API_KEY` **export 不生效,只能在 patch 的 `env` 里给出**。配置入口与安全警告见仓库根的 `cordis.patch.yml`,用户可读的说明见 `README.md` 的「配置」一节。
| `cli` | `src/dsh_coderag/__main__.py` | 命令行入口(`index` / `search`) | 供人调试用,非模型接口 |
**模块依赖方向(禁止反向依赖)**:
```
server ──► {taskman, searcher, indexer, render, walker, sqlite_caps, config, types}
cli ─────► {indexer, searcher, types}
taskman ─► {indexer, types}
searcher ► {indexer, walker, chunker, parser, text, sqlite_caps, config, types}
indexer ─► {walker, chunker, sanitize, text, log, sqlite_caps, config, types}
walker ──► {sanitize, config, types}
chunker ─► {parser, types}
render ──► types
eval ────► {searcher, indexer, walker, text, config, types}(`runner` 复用生产检索;`attribute` 读 walker/indexer/text 做归因;markdown 渲染是 eval 自己的)
config / types / parser / text / sanitize / log / sqlite_caps:叶子模块,不依赖其它 dsh_coderag 模块;
config 与 types 被所有模块只读引用。render 只被 server 调用(eval 有自己的 markdown 渲染器)。
```
### 3.5 MCP 工具契约
> **设计原则**:工具集**固定为 4 个**,不动态增删(约束 C4)。所有变化通过参数表达,不通过新增工具。
>
> **命名原则**:工具名描述**模型要达成的目标**,不描述实现机制。不用 `fts5_query`、`bm25_search` 这类实现词汇。
#### 工具 1:`code_search`
```jsonc
{
"name": "code_search",
"description": "Search the workspace codebase for relevant code. Returns ranked code snippets with exact file paths and line numbers. Prefer this over grep when you do not know the exact identifier, or when searching for behaviour across multiple files. When the index is not ready the result reports a structured status instead of an empty list.",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "Natural language or identifiers describing what you are looking for." },
"path": { "type": "string", "description": "Workspace-relative directory to search within. Defaults to the workspace root." },
"limit": { "type": "integer", "description": "Maximum number of snippets. Defaults to 5, maximum 50." },
"max_tokens": { "type": "integer", "description": "Approximate token budget for the returned snippets. Defaults to 4000." }
},
"required": ["query"]
}
}
```
**返回格式(模型可见,逐字符稳定,改动必须更新快照)**:
```
status: ready
query: "如何校验用户令牌"
scanned: 1284 files / 9632 chunks
hits: 5 (sorted by source order)
skipped: 42 (gitignored: 28, secret_file: 12, too_large: 2)
── src/auth/token.py:42-67 [function verify_token] (chunk 7)
def verify_token(raw: str) -> Claims:
...
── src/auth/middleware.py:15-33 [function require_auth] (chunk 3)
...
[1 more hit omitted by token budget; raise max_tokens to see it]
```
**未就绪时的返回(关键,约束 C6)**:
```
status: indexing
message: The code index for this workspace is still being built.
progress: 42% (540/1284 files, 3900/9632 chunks)
hint: Results would be incomplete. Retry shortly, or use grep for exact identifiers now.
```
**失败时**:
```
status: error
code: INDEX_READ_FAILED
message: ...
```
#### 工具 2:`code_outline`
```jsonc
{
"name": "code_outline",
"description": "Return the symbol outline (classes, functions, methods) of one file, with line numbers. Use this to understand a file's structure before reading it in full.",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "Workspace-relative file path." },
"max_depth": { "type": "integer", "description": "Nesting depth to include. Defaults to 2." }
},
"required": ["path"]
}
}
```
**返回格式(模型可见)**:
```
status: ready
path: src/auth/token.py
symbols: 3
class TokenService lines 10-40
method verify_token lines 12-20
method issue_token lines 22-30
function helper lines 42-44
```
#### 工具 3:`code_index`
```jsonc
{
"name": "code_index",
"description": "Start (or refresh) the code index for a workspace directory. Returns immediately with a task id; indexing continues in the background. Poll index_status for progress.",
"inputSchema": {
"type": "object",
"properties": {
"path": { "type": "string", "description": "Workspace-relative directory to index. Defaults to the workspace root." },
"force": { "type": "boolean", "description": "Rebuild from scratch instead of incrementally. Defaults to false." }
}
}
}
```
**返回**:`{"taskId": "idx-20260917-8f3a", "state": "pending", "hint": "Poll index_status with this taskId."}`
#### 工具 4:`index_status`
```jsonc
{
"name": "index_status",
"description": "Report the state and progress of an indexing task, or of the workspace index when no task id is given.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": { "type": "string", "description": "Task id returned by code_index. Omit to report the current workspace index." }
}
}
}
```
**状态机**:`pending → running → ready | failed | cancelled`
### 3.6 SQLite 数据模型
**验证记录**:本机 `forBSH` 环境实测为 **Python 3.10.21 + SQLite 3.53.4**,`fts5` **已确认可用**。⚠️ **但中文必须走 bigram 预处理**——`trigram` 分词器对本项目不可用,原因见 §5.3.1 的实测。
```sql
PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
-- 索引运行记录(约束 C10:跨重启持久化)
CREATE TABLE IF NOT EXISTS index_runs (
task_id TEXT PRIMARY KEY,
root TEXT NOT NULL,
state TEXT NOT NULL, -- pending|running|ready|failed|cancelled
total_files INTEGER NOT NULL DEFAULT 0,
done_files INTEGER NOT NULL DEFAULT 0,
total_chunks INTEGER NOT NULL DEFAULT 0,
done_chunks INTEGER NOT NULL DEFAULT 0,
message TEXT,
started_at INTEGER NOT NULL,
finished_at INTEGER
);
-- 文件层(增量判定的依据)
CREATE TABLE IF NOT EXISTS files (
id INTEGER PRIMARY KEY,
path TEXT NOT NULL UNIQUE, -- 工作区相对路径,正斜杠
size INTEGER NOT NULL,
mtime_ns INTEGER NOT NULL,
content_hash TEXT NOT NULL, -- sha256,用于幂等
lang TEXT, -- tree-sitter 语言名
indexed_at INTEGER NOT NULL
);
-- 分块层
CREATE TABLE IF NOT EXISTS chunks (
id INTEGER PRIMARY KEY,
file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
seq INTEGER NOT NULL, -- 文件内序号,用于"原文顺序"
start_line INTEGER NOT NULL, -- 1-based,闭区间
end_line INTEGER NOT NULL, -- 1-based,闭区间
symbol_kind TEXT, -- function|method|class|struct|union|enum|namespace|interface|module
symbol_name TEXT,
text TEXT NOT NULL,
content_hash TEXT NOT NULL,
UNIQUE (file_id, seq)
);
CREATE INDEX IF NOT EXISTS idx_chunks_order ON chunks (file_id, seq);
CREATE INDEX IF NOT EXISTS idx_chunks_symbol ON chunks (symbol_name);
-- 全文索引:中文走 bigram 预转换 + unicode61(约束 C5,见 §5.3.1 的实测依据)。
-- 不用 content= 外部内容表:写入前需要对中文做 to_bigrams() 转换,
-- 转换后的文本必须真实存在索引里。用 UNINDEXED 列承载删除所需的外键。
CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5 (
text_bigram, -- to_bigrams(chunk.text),中文已切成 bigram
symbol, -- 原始符号名(拉丁标识符,无需转换)
path, -- 原始路径
chunk_id UNINDEXED,
file_id UNINDEXED,
tokenize = 'unicode61'
);
-- 工作区索引代(用于检索时判断是否 stale)
CREATE TABLE IF NOT EXISTS workspace_index (
root TEXT PRIMARY KEY,
db_schema INTEGER NOT NULL,
ready INTEGER NOT NULL DEFAULT 0,
last_task_id TEXT,
updated_at INTEGER NOT NULL
);
```
**存储位置**:`
`Successfully built dsh-coderag`
`Installing collected packages: dsh-coderag`
`Successfully installed dsh-coderag-0.1.0`
`dsh-coderag 0.1.0`
(forBSH 环境,退出码 0) | `954d1ca` | 产出三文件;仅打包骨架,无独立单测 |
| T1-02 | 已完成 | `$ python -m pytest tests/test_config.py -q`
`... [100%]`
(退出码 0;3 个点 = 3 个用例通过) | `8c11c80` | 正常 / 缺必填 / 类型错误 |
| T1-03 | 已完成 | `$ python -c "from dsh_coderag.types import ErrorCode; print(len(ErrorCode))"`
`10`
(≥9;§5.6 现有 10 个,含新增的 FTS5_UNAVAILABLE,任务描述里的「9 个」已过时) | `16859d5` | tests/test_types.py 5 例全过;ruff/mypy 通过 |
| T1-04 | 已完成 | `$ python -m pytest tests/test_walker.py -q`
`..... [100%]`
(退出码 0;5 个用例通过) | `1a528cb` | 新增 tests/fixtures/tiny 与 conftest 的 tiny_repo fixture |
| T1-05 | 已完成 | `$ python -m pytest tests/test_chunker.py -q`
`.............. [100%]`
(退出码 0;14 个用例通过) | `ca85e60` | 固定 80 行 / 20 行重叠;symbol_kind=None;每行至少被一个 chunk 覆盖 |
| T1-06 | 已完成 | `$ python -m pytest tests/test_schema.py tests/test_text.py -q`
`.................... [100%]`
(退出码 0;20 个用例通过) | `36c000c` | 5 张表(不含 embeddings);WAL;chunks_fts=unicode61;bigram 索引/查询对称且幂等;§5.3.1 代码块同步为实际实现(原文有首尾空格且非幂等) |
| T1-07 | 已完成 | `$ dsh-coderag index tests/fixtures/tiny`
`indexed 3 files, 3 chunks into /Users/vermi/个人项目/python/dsh-coderag/tests/fixtures/tiny/.coderag/index.sqlite3`
`$ sqlite3 tests/fixtures/tiny/.coderag/index.sqlite3 "select count(*) from chunks;"`
`3`
(files: app.ts / lib.c / main.py;行区间 1-3 / 1-3 / 1-2) | `ced4777` | 新增 open_index 与 CLI index 子命令;重复索引不产生重复行 |
| T1-08 | 已完成 | `$ dsh-coderag search add`(在 tests/fixtures/tiny 内,已先 `dsh-coderag index tests/fixtures/tiny`)
`lib.c:1-3`
`main.py:1-2`
`app.ts:1-3`
(退出码 0;按 bm25 排序,T2-14 再改为顺序保持) | `716c4db` | 新增 search() 与 CLI search 子命令;无索引时抛 FileNotFoundError,不返回空列表 |
| T1-09 | 已完成 | `$ python -m pytest tests/test_render.py -q`
`.... [100%]`
(退出码 0;4 个用例通过,含 2 个 inline-snapshot 快照) | `0e638e8` | 格式见 §3.5;符号缺失时省略 [];omitted>0 时输出 token 预算提示 |
| T1-10 | 已完成 | `$ python -m pytest tests/test_taskman.py -q`
`....... [100%]`
(退出码 0;7 个用例通过,含 pending→running→ready 与持久化) | `e1c51d6` | TaskManager: create/status/cancel + mark_running/ready/failed;非法流转抛 TaskStateError |
| T1-11 | 已完成 | `$ python -m dsh_coderag.server`(stdin 发 initialize + notifications/initialized + tools/list)
`{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"tools":{"listChanged":false}},"serverInfo":{"name":"coderag","version":"0.1.0"}}}`
`tools: 4`
`names: ['code_search', 'code_outline', 'code_index', 'index_status']`
`serverInfo: {'name': 'coderag', 'version': '0.1.0'}`
(stdout 全部为合法 JSON-RPC;stderr 为空) | `fcdc300` | 4 工具 schema 与 §3.5 一致;code_outline 返回未实现的结构化状态;code_index 暂同步(T1-12 改异步) |
| T1-12 | 已完成 | `code_index` 内存传输实测(50 个文件的工作区)
`elapsed_ms: 3.1`
`returned_state: pending`
`taskId_prefix_ok: True`
`final_state: ready files: 50 chunks: 50`
(< 200 ms 要求;后台线程走 pending→running→ready) | `c8aba73` | 新增 TaskManager.start(worker) 后台线程;失败写入 failed + 日志到 stderr |
| T1-13 | 已完成 | `$ python -m pytest tests/test_status_contract.py -q`
`... [100%]`
(退出码 0;3 个用例通过) | `808ac17` | search() 返回 SearchResult;无索引→indexing、无命中→empty、异常→error,均不含裸 [] |
| T1-14 | 已完成 | `$ ./scripts/dsh web --patch ./cordis.patch.yml --dump-config`(E-07:dsh 命令经包装脚本)
`- id: mcp-coderag`
` name: '@deepseek-ai/dsh-mcp-client'`
` config:`
` serverName: coderag`
` transport: stdio`
` command: !!js process.env.CODERAG_PYTHON ?? '/opt/anaconda3/envs/forBSH/bin/python'`
(rc=0,stderr 为空)
配置的 command 实测:`serverInfo {name: coderag, version: 0.1.0}`、`tools [code_search, code_outline, code_index, index_status]` | `41f5d54` | 同一文件兼作 dev overlay 与 bundle patch;未真正 boot web(避免占用 3080),用 --dump-config + 直接跑配置命令验证 |
| T1-15 | 已完成 | 人工验收(DSH Web :3099,工作区 `examples/demo-workspace`,创造模式)
问「用户令牌在哪里校验」→ 先 grep×2,再调 `mcp__coderag__code_search`,返回 `status: ready` / `hits: 1` / `── src/auth/token.py:1-20`
问「连接池代码在哪?」→ **首发** code_search,参数 `{"query":"连接池 connection pool","limit":10}`,返回 `── src/db/pool.py:1-8` | `cd71afa` | 工具出现且被调用,返回正确文件+行号;R5 部分缓解(未知标识符时优先 code_search,已知标识符仍可能先 grep) |
| T1-16 | 已完成 | `$ test -f docs/m1-findings.md && grep -c '^### 观察' docs/m1-findings.md`
`exists`
`8` | `7dcdb57` | 8 条具体观察 + 3 条开发期缺陷修复记录 + 已知限制 |
| T2-01 | 已完成 | `$ python -m pytest tests/test_parser.py -q`
`...................... [100%]`
(退出码 0;22 个用例通过。其中 4 例对 python/c/cpp/typescript 四种 grammar 做实际解析,断言 root 节点分别为 module / translation_unit / translation_unit / program 且 `has_error` 为 False;1 例断言 `EXTENSION_LANGUAGES` 覆盖 `walker.CODE_EXTENSIONS` 全部 7 个后缀) | `ea49999` | 新增 `parser.py`:扩展名→grammar 名映射 + `get_language`/`get_parser`;`pyproject.toml` 钉 `tree-sitter-language-pack>=0.13,<0.14`(原未钉版本装到 1.20.0,实际运行时需联网从 GitHub 下载 grammar,本机实测 `available_languages()==0`、`get_language('python')` 报 DownloadError,离线不可用) |
| T2-02 | 已完成 | `$ python -m pytest tests/test_chunker_decl.py -q`
`................ [100%]`
(退出码 0;16 个用例通过。其中 4 个语言 fixture 各有一例断言**完整 chunk 列表**(kind/name/start/end)与人工标注逐条一致:sample.py 5 块(4 声明)/ sample.c 3 块(2 声明)/ sample.cpp 4 块(3 声明)/ sample.ts 4 块(2 声明);另含 2 条 Hypothesis 性质测试:覆盖全文、区间不重叠) | `818ec58` | 新增 4 语言 fixture `tests/fixtures/decl/*`、`decl_repo` fixture 与 `tests/test_chunker_decl.py`;重写 `tests/test_chunker.py`(朴素定长切分被声明感知替换,仅对无 grammar 语言保留非重叠定长 fallback);chunker.py 按 tree-sitter 声明边界切分,并对声明外非空行补 gap chunk,保证覆盖全文且不重叠 |
| T2-03 | 已完成 | `$ python -m pytest -k "oversized" -q`
`...... [100%]`
(退出码 0;6 个用例通过。1000 行函数切成 5 片,命名 `big_function#part/1..5`,每片 ≤200 行、连续覆盖 [1,1000] 且区间不重叠;`max_chunk_lines` 可覆盖;小声明不加后缀) | `6e9c2fb` | 新增 `tests/fixtures/oversized/big.py`(1000 行)与 `tests/test_chunker_oversized.py`;chunker.py 增加 `MAX_CHUNK_LINES=200`,按 body 直接子语句/注释边界二次切分;`pyproject.toml` 钉 `tree-sitter>=0.25.2,<0.26`(0.26.0 与 language-pack 0.13 不兼容,释放大 Tree 时段错误) |
| T2-04 | 已完成 | `$ python -m pytest -k "module_header or fallback" -q`
`....... [100%]`
(退出码 0;7 个用例通过:3 条 module header(领先区块标记 `symbol_kind="module"`、上限 40 行、文件以声明开头时无 header)+ 4 条 fallback(按空行分段、`low_confidence=true`、覆盖全文、不重叠)) | `1ca177a` | chunker.py 新增 `MODULE_HEADER_LINES=40` 与 `_module_header`;L4 fallback 改为按空行分段并统一标记 `low_confidence`(超 200 行段落再按窗口切分);移除旧定长 fallback 常量 |
| T2-05 | 已完成 | `$ python -m pytest -k "contextual_prefix" -q`
`..... [100%]`
(退出码 0;5 个用例通过:每个 chunk 文本以 `// file: ... \| symbol: ... \| lines M-N` 前缀开头、前缀进入 `chunks.text` 与 `chunks_fts.text_bigram`、渲染时前缀被剥离且代码正文只出现一次、非前缀注释不误伤) | `9fc358a` | chunker.py 为每个 chunk 拼接 §5.1 上下文前缀;render.py 新增 `strip_context_prefix`,输出前剥离(位置信息已由 `── path:lines [symbol] (chunk N)` 单独成行,避免重复、不污染代码正文);覆盖度/属性测试改为先剥前缀再比对 |
| T2-06 | 已完成 | `$ python -m pytest tests/test_security.py -q`
`........ [100%]`
(退出码 0;8 个用例通过:`.env` / `id_rsa` / `credentials.py` / `.gnupg/settings.py` / `config.py`(含 `AKIA...`)均未进入 `chunks`;`ignored_dir/`(`.coderagignore`)与运行时 `.gitignore` 目录被排除;反向用例 `normal.py`、`env_reader.py`(`os.environ`)正常入库) | `72ab575` | 新增 `sanitize.py`(第 1 层文件名/路径黑名单 + 第 3 层内容正则,只返回模式名、不返回或记录内容);重写 `walker.py` 接入 pathspec(先 `.gitignore` 后 `.coderagignore`,`GitIgnoreSpec`);`indexer.py` 写库前对每个 chunk 调 `scan_secret`,命中即丢弃,整文件全 redact 时不写 `files` 行;新增 `tests/fixtures/secrets/`(全假凭据)与 `tests/test_security.py` |
| T2-07 | 已完成 | `$ python -m pytest -k "skip_report" -q`
`...... [100%]`
(退出码 0;6 个用例通过:`walk_with_report` 把 `credentials.py`/`.gnupg/settings.py` 计为 `secret_file`、`ignored_dir/skipped.py` 计为 `gitignored`;`search()` 附带 SkipReport 并渲染出 `skipped: 3 (gitignored: 1, secret_file: 2)`;`index_status` JSON 含 `skipped: {count, reasons}`;零跳过时输出 `skipped: 0`) | `7a43bf3` | types.py 加 `SkipReport`;walker 加 `walk_with_report`(`walk` 返回类型不变);searcher 检索时基于当前 walk 附加 skipped;render.py 新增 `_format_skip_report` 与 `render_status(skipped=...)`;server.py 的 `index_status` 返回 skipped JSON;同步 §3.5 返回格式示例。按方案 A 未做 schema 持久化,redacted chunk 数留待 T2-09/T2-16 |
| T2-08 | 已完成 | `$ python -m pytest -k "incremental" -q`
`..... [100%]`
(退出码 0;5 个用例通过:二次索引 `files`/`chunks` 的 id 与 content_hash 全部不变、`summary.chunks == 0`;monkeypatch 证明内容未变的文件不再调用 `chunk_text`;改动过的文件被重建;一个文件变更时其它文件 id 不变;文件从正常变为含密钥时旧行被清除) | `bf3d043` | indexer.py:`_index_file` 先算 sha256 与 `files.content_hash` 比对,命中则整文件跳过;新增 `_delete_file_rows` 统一清理;全 redact 分支也清旧行 |
| T2-09 | 已完成 | `$ python -m pytest -k "add_modify_delete" -q`
`... [100%]`
(退出码 0;3 个用例分别验证 chunks 表状态:新增文件后出现其 chunk;修改文件后旧 chunk 被替换(旧符号消失、新符号出现)且 `files` 仍为 1 行;删除文件后其 `chunks`/`files`/`chunks_fts` 行级联清除) | `ea40021` | indexer.py:`index_sync` 收集本次 walk 的路径集合,新增 `_remove_missing_files` 在一个事务内级联删除工作区已不存在的文件;新增/修改沿用 T2-08 的每文件事务(先删后插) |
| T2-10 | 已完成 | `$ python -m pytest -k "adaptive_concurrency" -q`
`......... [100%]`
(退出码 0;9 个用例通过:`adaptive_workers(cpu_count=1/4/16)` 得 1/3/8,内存上限把 8 压到 2/1;`next_batch_size` 慢批减半、快批翻倍、中间不变且封顶 512;`IndexConfig(batch_size=7, max_workers=2)` 覆盖生效;env `CODERAG_BATCH_SIZE`/`CODERAG_MAX_WORKERS` 生效;`index_sync(config=...)` 跑通) | `ae0083a` | config.py 新增 `adaptive_workers`/`next_batch_size` 与常量,`IndexConfig` 增可选 `batch_size`/`max_workers` 及 `workers`/`start_batch_size` 属性;indexer.py 重构为「并行 prepare(读+hash+chunk+密钥扫描)→ 自适应批量串行写库」;本机 workers=8,50 文件并发索引实测 files/chunks 均 50,全量套件重复 5 次稳定 |
| T2-11 | 已完成 | `$ python -m pytest -k "too_many_files" -q`
`.... [100%]`
(退出码 0;4 个用例通过:3 个可索引文件 + `max_files=2` 时抛 `TooManyFilesError`,`actual_count==3`、`max_files==2`、`code==INDEX_TOO_MANY_FILES`,`payload` 为 `{code, actual_count, max_files, message}`;恰好等于上限不报错;非代码扩展名与密钥文件不计入上限;`index_sync` 超限时在写任何 `files` 行前失败,DB files 计数为 0,绝不静默截断) | `c2d7300` | walker.py 新增 `TooManyFilesError(actual_count, max_files)`(带 `code` 与 `payload`)及 `walk`/`walk_with_report` 的 `max_files` 参数,走完全部文件后超限即抛;indexer.py 把 `IndexConfig.max_files` 传给 walk(无 config 时用默认 20000);异常 message 含实际数量,异步索引失败时经 `index_status` 可见 |
| T2-12 | 已完成 | `$ python -m pytest -k "cancel" -q`
`..... [100%]`
(退出码 0;5 个用例通过:`TaskManager.start` 为每个任务建 `threading.Event` 并把 `should_cancel` 传给 worker,`cancel()` 置位并写 `cancelled`;worker 取消后不再 `mark_ready`(状态保持 cancelled);`index_sync(should_cancel=...)` 在每个文件/批次边界轮询,取消后不写库、不 mark ready;取消前已提交的批次保留) | `366dc8d` | taskman.py 新增 `IndexWorker` Protocol 与每任务 `threading.Event`,`cancel` 置位事件,`_run_worker` 取消后跳过 mark_ready 并容忍 `TaskStateError`;indexer.py `index_sync` 新增关键字参数 `should_cancel`,prepare 与写库循环在每个文件边界轮询 |
| T2-13 | 已完成 | `$ python -m pytest tests/test_outline.py -q`
`...... [100%]`
(退出码 0;6 个用例通过:`outline(sample.py)` 返回 4 个顶层符号 + `class Pool` 下的 `method acquire`(行号 4-5 / 8-9 / 12-14 / 17-19 / 18-19);`max_depth=1` 不展开方法;未知语言返回空;路径越界抛 `ValueError`;MCP `code_outline` 精确渲染符号树;缺失文件返回 `status: empty`) | `7e28014` | searcher.py 新增 `OutlineSymbol` 与 `outline()`(复用 chunker 的 `DECLARATION_KINDS`/`WRAPPER_NODE_TYPES`,按 body 递归,类内函数标 `method`,wrapper 取外层 span);server.py 用真实实现替换 T1-11 占位并渲染缩进树;§3.5 增加 code_outline 返回示例;更新原占位断言 |
| T2-14 | 已完成 | `$ python -m pytest -k "order_preserving" -q`
`... [100%]`
(退出码 0;3 个用例通过:`b.py` 命中次数远多于 `a.py`(bm25 更优),但输出仍为 `a.py` → `b.py` 且 `hits[0].score > hits[1].score`;同一文件内多 chunk 按 `start_line` 升序;跨文件按 `(path, start_line)` 稳定排序) | `dfdc0b1` | searcher.py `_search` 的 SQL 加 `c.id` 作为 bm25 并列时的唯一 tiebreaker,取 top-k 后对 hits 按 `(path, start_line)` 重排(ADR-05:选按分数、排按位置) |
| T2-15 | 已完成 | `$ python -m pytest -k "token_budget" -q`
`..... [100%]`
(退出码 0;5 个用例通过:5 条约 100 字符的命中在 `max_tokens=20` 下只保留 1 条并报 `omitted=4`;大预算全保留;`render_search_result` 末尾输出 `[4 more hits omitted by token budget; raise max_tokens to see them]`;`omitted=1` 用单数;极小预算仍至少保留 1 条) | `59e5fe3` | searcher.py `search` 新增 `max_tokens`(默认 4000),按输出顺序累加 `len(text)/3.5` 裁剪并记录 `omitted`;types.py `SearchResult` 增 `omitted` 字段;render.py 改从 `result.omitted` 生成省略提示;server.py 把 MCP `max_tokens` 传入 search |
| T2-16 | 已完成 | `$ python -m pytest tests/test_log.py -q`
`..... [100%]`
(退出码 0;5 个用例通过:`log_event` 每行一个合法 JSON 且含 `ts/level/event/task_id/duration_ms`,stdout 保持为空;索引后 stderr 依次输出 `index_start`/`index_done` 两条合法 JSON;`.coderag/last-index.json` 含 `root/task_id/files/chunks/skipped{count,reasons}/redacted{count}/duration_ms{walk,prepare,write,cleanup,total}`;skipped/redacted 计数正确) | `7f3fb79` | 新增 `log.py`(JSON-Lines 到 stderr + `build_audit_record` + `write_audit_dump`,绝不写 stdout);indexer.py 在索引起止发日志、按阶段计时、写 `last-index.json`;`_PreparedFile.redacted` 由 bool 改为计数 |
| T2-17 | 已完成 | 人工验收(DSH 参考源码 `0d1f50007f` 的复制,3063 个 `.ts`):`$ dsh-coderag index
`indexed 3074 files, 51230 chunks`(墙钟 **3.42 s**;audit total 3299.0 ms = walk 188.6 / prepare 2066.5 / write 1034.3 / cleanup 1.2;skipped 3 / redacted 2;二次增量 **0 chunk / 0.47 s**)
5 个真实问题的标识符改写查询 **5/5 命中正确文件**(Q1 `packages/mcp/mcp-client/src/index.ts` 名次 4;Q2 `.../mcp-client/src/transport.ts` 1;Q3 `packages/sandbox/sandbox-policy/src/session-mode.ts` 2;Q4 `packages/preset/persona/src/index.ts` 1;Q5 `packages/spill/spill-local/src/store.ts` 1);纯中文原问句 5/5 返回 `empty` | `f47fe4d` | 产出 `docs/m2-findings.md`(索引耗时分解、5 问结果、7 条观察、2 个依赖阻断记录、已知限制);为遵守 RL-01/S-03 用 rsync 复制目录而非原地索引;发现「中文原问句 AND-of-bigrams 全 empty」与「测试/实验文件在 BM25 中压过实现文件」两项 M2 质量缺口,指向 T2-19/T3 归因 |
| T2-18 | 已完成 | 人工抽检(DSH 参考源码 3074 文件 / 51230 chunk):`docs/m2-chunk-audit.md` 含 **20 条逐条结论**(4 个 `#part/N` + 4 function + 2 class + 3 interface + 3 module + 4 gap)。核心判据:**声明块 >200 行 = 0**,抽检的 function/class/interface 均边界完整、花括号净 0,**无"半个函数"**。发现 3 个 gap 侧问题:gap 无行数上限(最大 **3080 行**)、gap 碎片化(单行 4980 / ≤2 行 6977)、TS `type`/`const` 未纳入声明(gap 占比 69.6%) | `cc35258` | 产出 `docs/m2-chunk-audit.md`;按 AGENTS §9 把两个越界缺陷记入新增 `docs/backlog.md`(未顺手修);`#part/N` 拆分不自包含是 §5.1 L2 既定取舍,依赖 T2-05 上下文前缀 |
| T2-19 | 已完成 | `$ python -m pytest tests/test_tokenizer_semantics.py -q`
`................ [100%]`
(退出码 0;16 个用例全绿,覆盖三条语义:**标点路由** 7 个纯标点查询返回 `status: empty` 且 hint 含 `grep`,而 `self.authenticate`/`std::vector` 正常 READY;**无词干化** `connection` 不命中 `connect_only.py`,且 `chunks_fts` schema 为 `unicode61`、不含 `porter`;**停用词可检索** `for/if/and/in/not` 均命中 `stopwords.py`) | `5f02646` | searcher.py 新增 `_is_punctuation_only`(无标识符/CJK 即路由)与 `PUNCTUATION_QUERY_HINT`,`_build_match` 保持 `to_bigrams` 两侧对称;`tests/test_tokenizer_semantics.py` 在 tmp_path 内建语料。**取舍**:ADR-13 的规则是「去掉标点后无可检索词才路由」,故 `self.(`/`std::` 仍会正常检索(TESTING §3.11 的示例参数与此冲突,以 PROJECT/ADR-13 为准);按 AGENTS §9 把「精度/召回双模式未实现」记入 `docs/backlog.md` |
| T2-20 | 已完成 | `$ python -m pytest -k "path_filter" -q`
`...... [100%]`
(退出码 0;6 个用例通过:`path="pkg"` 只返回 `pkg/a.py`;省略 path 时四个目录都返回(行为不变);`path` 可指向单个文件;`my_pkg` 不会因 `_` 通配误匹配 `myXpkg`(LIKE 转义);`../outside` 返回 `status: error` + `SEARCH_INVALID_QUERY`;MCP `code_search` 传 `path` 生效) | `4c555ee` | searcher.py `search` 新增 `path` 参数与 `_path_prefix`(resolve 后必须仍在工作区内)+ `_escape_like`;`_search` 加 `f.path = ? OR f.path LIKE ? ESCAPE '\'` 过滤;server.py 把工具 `path` 参数传入 search |
| T2-21 | 已完成 | `$ python -m pytest -k "too_large" -q`
`...... [100%]`
(退出码 0;6 个用例通过:超过 `max_file_bytes` 的文件在读内容前被跳过并计入 `skipped.reasons["too_large"]`;`index_sync` 后 `files` 表只含小文件;审计转储含 `too_large`;恰好等于上限的文件保留;`DEFAULT_MAX_FILE_BYTES == 1 MiB`;env `CODERAG_MAX_FILE_BYTES` 覆盖生效) | `8cab6ed` | config.py 新增 `max_file_bytes`(默认 1 MiB)+ env;walker.py `walk_with_report` 用 `stat` 大小在读内容前跳过并记 `too_large`;indexer.py 传入 `config.max_file_bytes`;新增 `tests/test_file_size_limit.py` | |
| T2-22 | 已完成 | `$ python -m pytest -k "fts5_unavailable" -q`
`...... [100%]`
(退出码 0;6 个用例通过:本机 `fts5_available()` 为 True;mock 不可用时 `search()` 返回 `status: error` + `code: FTS5_UNAVAILABLE` + 可操作 hint;`index_sync` 抛 `Fts5UnavailableError`;MCP `code_search`/`code_index` 均返回结构化错误且 `isError` 不为 True;`_dispatch` 兜底把未预期异常转成 `SEARCH_FAILED`) | `2c9b405` | 新增 `sqlite_caps.py`(`fts5_available()` + `Fts5UnavailableError` + `FTS5_HINT`);searcher/indexer 开库前探测;server 的 `_code_index`/`_index_status` 加 FTS5 守卫、`_dispatch` 加 `except Exception` 兜底(RL-09);新增 `tests/test_fts5_unavailable.py` | |
| T3-00 | 已完成 | `$ ./scripts/dsh plugin --profile eval-coderag add github:BiBoyang/dsh-eval-harness`
首次:`Error: ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`(git-hosted `prepare` 被 pnpm 10+ 拦截)
按报错把精确 key 写入 `allowBuilds` 后:
`✓ Lockfile passes supply-chain policies (verified 5m ago)`
`Lockfile is up to date, resolution step is skipped`
`Done in 2.3s using pnpm v12.4.2`
`$ ./scripts/dsh --profile eval-coderag --dump-config`(stderr 0 字节)
`# == dsh-eval-harness`
`- id: dsh-eval-harness`
` name: dsh-eval-harness`
跑 `cases/real/01-bash-tool.yml`:`summary: total 1 / passed 0 / failed 0 / errored 1`;`error: no session log (session.jsonl / session.jsonl.zstd) ...`;DSH 实际落盘 `session.v3.jsonl.zstd` | `49841d3` | 插件可安装、可装载;但 harness 0.4.0 的 trace 收集器只认 v0 文件名,运行用例不兼容。按 T3-00 失败分支改走 `EVAL.md` §3.6 自建薄 runner,T3-05/T3-06 不依赖该插件。详细实际输出见 `docs/m3-eval-harness-check.md` |
| T3-01 | 已完成 | `$ test -f eval/schema.json && test -f eval/README.md && echo "files exist"`
`files exist`
`$ python3 -c "import json, jsonschema; jsonschema.Draft202012Validator.check_schema(json.load(open('eval/schema.json'))); print('schema OK')"`
`schema OK` | `48fd9ea` | 新增 `eval/schema.json`(JSON Schema Draft 2020-12,约束单条 task)与 `eval/README.md`(字段表、A/B 配比、构造硬规则、校验方法)。`golden_version` 按 EVAL.md §2.7 作为文件级元数据留在 `eval/tasks.meta.json`,不重复进每行。 |
| **T3-02a** | 已完成 | `$ python3 scripts/verify-tasks.py eval/tasks.jsonl /Users/vermi/projects/dsh`
`== verify-tasks ==`
`tasks : eval/tasks.jsonl`
`corpus: /Users/vermi/projects/dsh`
`解析到 10 条任务(exact 4 / crossfile 4 / natural 2)`
`[V1 ] 读取与解析 PASS 10 条有效任务`
`[V2 ] schema PASS 10/10 条通过 schema.json`
`[V3 ] 唯一 ID PASS 10 个唯一 ID / 10 条`
`[V4 ] 路径格式 PASS 14 条路径`
`[V5 ] 路径存在 PASS 14/14 条路径存在`
`[V6 ] 无答案泄漏 PASS 10 条 query`
`[V7 ] exact 标识符存在 PASS 4 条 exact`
`[V8 ] natural 无标识符 PASS 2 条 natural`
`[V9 ] class 配比 PASS exact/crossfile/natural = 4/4/2,目标比例 12:11:7(±1)`
`[V10] 任务数下限 PASS 10 ≥ 10`
`PASS: 10 条任务全部通过 10 项检查`
(退出码 0。同一脚本的变异测试:`$ python3 scripts/test-verify-tasks.py` → `PASS: 基线通过,13 个变异全部被预期检查检出`) | `4229eb0` | 新增 `scripts/verify-tasks.py`(V1–V10:解析 / schema / 唯一 ID / 路径格式 / 路径存在 / 无答案泄漏 / exact 标识符真实存在 / natural 零标识符 / class 配比 / 任务数下限)与 `scripts/test-verify-tasks.py`(13 个变异逐一证明每项检查会失败)。**修正 A 批评测集 2 类缺陷**:10 条 `expect_paths` 的前导 `/`(绝对路径,V4 检出)与 L-007 的 `types.ts` 被截断成 `types.t`(V5 检出)。V6 必须带标识符边界,否则 `delegationDepthOf` 里的 `depth` 会误报为泄漏。pytest 221 例全绿,ruff / mypy 干净 |
| T3-03 | 已完成 | `$ python -m pytest tests/test_eval.py -q`(forBSH 环境)
`...........................s [100%]`
(27 passed / 1 skipped;跳过的 1 条是需 `CODERAG_EVAL_CORPUS` 门控的 A 批集成用例)
`$ CODERAG_EVAL_CORPUS=/tmp/dsh-coderag-t3-03-corpus python -m pytest tests/test_eval.py -q`
`............................ [100%]`
(28 passed,A 批集成用例实跑)
被评测语料(DSH checkout 的 rsync 副本,遵守 RL-01/S-03 不原地索引):
`$ python -m dsh_coderag index /tmp/dsh-coderag-t3-03-corpus`
`indexed 3967 files, 63046 chunks into /private/tmp/dsh-coderag-t3-03-corpus/.coderag/index.sqlite3`
`$ python -m dsh_coderag.eval run --tasks eval/tasks.jsonl --root /tmp/dsh-coderag-t3-03-corpus --k 5`
`task_count=10 hit_count=1 k=5`
`class_counts: {"exact": {"total": 4, "hit": 1}, "crossfile": {"total": 4, "hit": 0}, "natural": {"total": 2, "hit": 0}}`
`L-001 exact hit=True rank=1 status=ready matched=packages/mcp/mcp-client/src/index.ts`
`L-002 exact hit=False rank=None status=empty matched=None`
`L-003 exact hit=False rank=None status=empty matched=None`
`L-004 exact hit=False rank=None status=empty matched=None`
`L-005 crossfile hit=False rank=None status=empty matched=None`
`L-006 crossfile hit=False rank=None status=empty matched=None`
`L-007 crossfile hit=False rank=None status=empty matched=None`
`L-008 crossfile hit=False rank=None status=empty matched=None`
`L-009 natural hit=False rank=None status=empty matched=None`
`L-010 natural hit=False rank=None status=empty matched=None`
(逐条结果 JSON 由 `build_report`/`write_report` 产出;A 批全部 10 条跑通) | `84b1c4e` | 新增 `src/dsh_coderag/eval/`:`tasks.py`(`load_tasks`/`validate_tasks`)、`runner.py`(`run_eval`,直接复用生产 `searcher.search`,k=5 按 EVAL §2.5 选项 A)、`report.py`(逐 query JSON)、`__main__.py`(CLI)、`__init__.py`。**纯 Python、不调 LLM**。测试 27 例用 tmp_path 合成语料(T-03/T-04),1 条 A 批集成用例由环境变量门控。**重要发现**:A 批仅 1/10 命中——9 条含中文 query 全部 `status: empty`,根因是 `_build_match` 把 CJK bigram 一并 AND(裸标识符可回到 top-5:名次 5/3/4);且 exact 定义处在裸查询下也只排 3–5(被 spec/使用处压过)。二者均**不在 T3-03 范围内**,按 AGENTS §9 记入 `docs/backlog.md`,未顺手修。ruff / `mypy --strict src/` 干净,全量 249 例通过 |
| T3-04 | 已完成 | `$ python -m pytest tests/test_metrics.py -q`(forBSH 环境)
`............................ [100%]`
(28 passed,退出码 0。期望值全部在测试里**手工算出**、不复用实现:Wilson `24/30 → low=0.626943 high=0.904949`,与 EVAL §2.6 的「≈[0.63, 0.90]」一致;边界 `0/10 → [0, 0.277533]`、`10/10 → [0.722467, 1.0]` 不越界;MRR ranks `[1,2,None,4] → 0.4375`;`must_not` 只在 k 前缀内判负;空桶的 success / interval / MRR / token 一律报 `None` 而非 `0.0`;分层测试证明 overall 是「每条 query 等权」的 1/4,而不是类均值 (1.0+0.0)/2)
附:同模块跑真实 A 批(`/tmp/dsh-coderag-t3-03-corpus`)得到第一组分层数字:
`overall n=10 S@1=0.100 [0.02,0.40] S@3=0.100 [0.02,0.40] S@5=0.100 [0.02,0.40] MRR=0.100 tokens_med=0`
`exact n=4 S@1=0.250 [0.05,0.70] S@3=0.250 [0.05,0.70] S@5=0.250 [0.05,0.70] MRR=0.250 tokens_med=0`
`crossfile n=4 S@1=0.000 [0.00,0.49] S@3=0.000 [0.00,0.49] S@5=0.000 [0.00,0.49] MRR=0.000 tokens_med=0`
`natural n=2 S@1=0.000 [0.00,0.66] S@3=0.000 [0.00,0.66] S@5=0.000 [0.00,0.66] MRR=0.000 tokens_med=0` | `f238f09` | 新增 `src/dsh_coderag/eval/metrics.py`:`count_hits`/`is_hit_at`/`success_at_k`、`mean_reciprocal_rank`、`median_tokens`、`wilson_interval`(用 `statistics.NormalDist`,**零新依赖**)、`compute_metrics`、`layered_metrics`(overall + 3 桶,宏平均)。`must_not_paths` 与 `expect_symbols` 在**每个 k 的前缀上**判定;空桶显式报 `None`。**未改 `__init__.py` / `report.py`**——指标接线属 T3-04c/T3-06。全量 277 例通过,ruff / `mypy --strict src/` 干净 |
| **T3-04b** | 已完成 | `$ python -m pytest tests/test_attribute.py -q`(forBSH 环境)
`.............................. [100%]`
(30 passed,退出码 0。`classify` 对 7 个码各有一条纯样例,A1/A3 的判据是**目标文件**而非全语料——全语料判据会误标 L-004)
A 批真实归因(`/tmp/dsh-coderag-t3-03-corpus`,9 条失败):
`L-002 exact A1 query 要求命中目标文件里不存在的词 ['定义','义在','在哪'];其中 ['义在','在哪'] 在整个索引中也不存在`
`L-003 exact A1 同上`
`L-004 exact A1 query 要求命中目标文件里不存在的词 ['的定','定义']`
`L-005 crossfile A1 目标文件缺少 18 个词,其中 10 个全索引皆无`
`L-006 crossfile A5 query 的任何一个词都不出现在目标文件的索引文本中`
`L-007 crossfile A5 同上`
`L-008 crossfile A1 目标文件缺少 16 个词,其中 11 个全索引皆无`
`L-009 natural A5 同上`
`L-010 natural A5 同上`
`distribution: {"overall": {"A1": 5, "A5": 4}, "exact": {"A1": 3}, "crossfile": {"A1": 2, "A5": 2}, "natural": {"A5": 2}}`
`natural_a5_share: 1.0` | `76b49e8` | 新增 `src/dsh_coderag/eval/attribute.py`:`collect_evidence`(只读地查文件系统 / `files`+`chunks_fts` / 一次 `probe_k=50` 广搜)+ 纯函数 `classify`(固定优先级 A4→A6→A7/A2→A5→A1→A3)+ `attribute_run` / `attribution_distribution` / `natural_a5_share` / `build_attribution_report`,**零新依赖**。⚠️ **R2 的两项字面条件都已满足**(`S@5=0.10<0.80`、natural 失败 100% 为 A5),但 §2.8 还要求「A1–A4/A6/A7 全部修完再考虑向量」,而 5 条 A1 恰是实现 bug;且当前只是 A 批 10 条。**T3-07 必须显式处理这个冲突,不能直接照字面判 R2**。全量 307 例通过,ruff / `mypy --strict src/` 干净。**后续修复 `bd9fd8d`**:A4 判据原先拿 probe 的**源码顺序位置**与 `run_k` 比较,几乎永不命中,30 条复测时把 2 条 A4 误判成 A3;改为「目标出现在 probe_k 候选集内即 A4」并补了回归用例 |
| **T3-13** | 已完成 | `$ python -m pytest tests/test_cjk_recall.py -q`(forBSH 环境)
`...... [100%]`
(6 passed,退出码 0:2 字词可检索;精度模式 `用户令牌` 只命中 `token.py`、排除只含「用户」「令牌」的 `separate.py`;`令牌未定义词` 精度落空后由召回命中;`verify_token未定义词` 混合查询命中;两种模式都空仍是 `status: empty` + hint;标点路由不经过召回)
同一语料(`/tmp/dsh-coderag-t3-03-corpus`,查询侧改动**无需重建索引**)A 批前后对比:
`exact S@5 0.250 [0.05,0.70] -> 1.000 [0.51,1.00] MRR 0.250 -> 0.412`
`overall S@5 0.100 [0.02,0.40] -> 0.400 [0.17,0.69] MRR 0.100 -> 0.165`
`crossfile S@5 0.000 -> 0.000` | `natural S@5 0.000 -> 0.000`
逐条:L-002 `empty → ready rank 5`、L-003 `empty → ready rank 5`、L-004 `empty → ready rank 4`;其余 6 条仍未命中
归因:`{"overall":{"A1":5,"A5":4}} → {"overall":{"A1":2,"A5":4}}`,`natural_a5_share` 仍为 `1.0` | `e7d7624` | 新增 `_build_recall_match`(OR 构造)与 `_join_phrases`;`search()` 仅在**精度模式 0 条**时用召回模式重试一次,两者都 0 才 `empty`——即 §5.3.1 的流程 1→2→3。**未改精度模式语义**(重叠 bigram 使 AND 等价于精确子串,新文件有断言)。因行为变化同步更新 `tests/test_attribute.py` 里依赖旧行为的 3 个用例——改成直接喂**显式失败结果**只测 collector+classifier,判据未被放宽(T-08)。**exact 桶已回到 EVAL §2.7 的 0.90 阈值之上(1.000)**;crossfile/natural 仍不达标,A5 仍是 natural 失败的全部,故 R2 的字面条件依旧成立——**T3-07 仍须处理 R2 与 §2.8「A1 先修完」的冲突**。全量 314 例通过,ruff / `mypy --strict src/` 干净 |
| **T3-02b** | 已完成 | `$ python3 scripts/verify-tasks.py eval/tasks.jsonl /Users/vermi/projects/dsh`
`解析到 30 条任务(exact 12 / crossfile 11 / natural 7)`
`[V1 ] 读取与解析 PASS 30 条有效任务`
`[V2 ] schema PASS 30/30 条通过 schema.json`
`[V3 ] 唯一 ID PASS 30 个唯一 ID / 30 条`
`[V4 ] 路径格式 PASS 46 条路径`
`[V5 ] 路径存在 PASS 46/46 条路径存在`
`[V6 ] 无答案泄漏 PASS 30 条 query`
`[V7 ] exact 标识符存在 PASS 12 条 exact`
`[V8 ] natural 无标识符 PASS 7 条 natural`
`[V9 ] class 配比 PASS exact/crossfile/natural = 12/11/7,目标比例 12:11:7(±1)`
`[V10] 任务数下限 PASS 30 ≥ 10`
`PASS: 30 条任务全部通过 10 项检查`
(退出码 0,被评测仓库 `/Users/vermi/projects/dsh`) | `43a2b65` | 新增 **L-011..L-030**(8 exact / 7 crossfile / 5 natural),凑齐 12/11/7。**每行的 `notes` 都写了出处(`file:line` + 原文片段)与选取理由**;crossfile 全部改成「定义处 → 使用/写入处 → 复用/封锁处」的三文件链路。**按用户指示提前执行**:任务表原依赖 `T3-04c`(尚未完成),此处按 A 批已暴露的 crossfile/natural 缺口定重点,未使用 `T3-04c` 的 diff。**未跑 L1 评测**——用户要先人工排查 query 是否泄漏答案,在其复核前不对评测集调参(EVAL §2.9 陷阱 3/14)。⚠️ `eval/tasks.meta.json` 尚未创建(属 T3-04d),**T3-04d 必须把初始 `golden_version` 定为本次 B 批后的状态**,否则踩 EVAL §2.9 陷阱 15。golden 集改动已按 EVAL §2.7 单独成一个提交(`43a2b65`) |
| **T3-14** | 已完成 | `$ python -m pytest tests/test_ranking_signals.py -q`(forBSH 环境)
`.......... [100%]`
(10 passed,退出码 0:先断言**原始 bm25 冠军确实是 spec**、再断言选中 impl;四种测试路径形态(`tests/`、`__tests__/`、`*.spec.*`、`*.test.*`)都被降级,而 `tests_helper.py` 不被降级;输出仍按源码顺序、结果可重复;`symbol_name` 完全匹配可在 SQL 中被加权、部分匹配不加权)
30 条 golden 集复测(同一语料,查询侧改动**无需重建索引**):
`exact S@5 0.833 -> 1.000 [0.76,1.00] MRR 0.582 -> 0.700`
`crossfile S@5 0.000 -> 0.091 [0.02,0.38] MRR 0.000 -> 0.091`
`natural S@5 0.000 -> 0.000`
`overall S@5 0.333 -> 0.433 [0.27,0.61] MRR 0.233 -> 0.313`
逐条:L-013 `未命中 -> rank 1`、L-018 `未命中 -> rank 3`、**L-005 `未命中 -> rank 1`**;L-003 名次 5→3
归因:`{"A4":2,"A1":2,"A5":16} -> {"A5":16,"A1":1}`,**A4 清零** | `1559cf3`, `0d269d1` | 两轮迭代。**第一轮**(`1559cf3`):候选池放宽到 `max(4k,20)` 后按 `selection_key` 重排,测试路径整体降到非测试之后(无魔数),`symbol_name` 完全匹配减 `SYMBOL_MATCH_BOOST=2.0`。**第二轮**(`0d269d1`):(a) 把测试路径降级**移进 SQL 的 ORDER BY 第一层**——原来的池 20 会被 `*_spec/*.e2e` 打满、目标根本进不了池(L-005 正是这样漏的),放进 SQL 后 `LIMIT k` 直接看到最终排序,候选池常量随之删除;(b) 召回从两级改为**三级**(精度 AND → 仅标识符 OR → 含 CJK bigram 的 OR),因为中文 bigram 精度极低,在带 `locales.ts` 的仓库里会以超高 bm25 压掉真正的代码。输出顺序始终 `(path, start_line)`(ADR-05 不变)。**未实现** §3.3 的「同文件局部性加权」与「声明定义处加权」——数据不支持,未引入。全量 326 例通过,ruff / `mypy --strict src/` 干净 |
| **T3-07** | 已完成 | `$ test -f docs/adr/ADR-14-semantic-retrieval.md && echo "ADR-14 exists" && wc -l < docs/adr/ADR-14-semantic-retrieval.md`
`ADR-14 exists`
`168`
`$ grep -n "R2 命中\|natural_a5_share = 1.0\|\"A5\": 16\|裁决:R2" docs/adr/ADR-14-semantic-retrieval.md`
`54:overall {"A5": 16, "A1": 1}`
`58:natural_a5_share = 1.0`
`88:| R2 | S@5 < 0.80 且 natural 失败中 A5 ≥ 50% | 0.433 < 0.80 ✅;natural_a5_share = 1.0 ≥ 0.50 ✅ | ✅ **命中** |`
`91:**裁决:R2 命中 → 引入向量检索。**`
(文档含明确结论 + 分层指标与 Wilson CI + 归因分布 + 30 条逐条结果 + R1/R2/R3 对账 + 6 条限制) | `8842a38` | 新增 `docs/adr/ADR-14-semantic-retrieval.md`(`docs/adr/` 此前不存在,这是第一个 ADR 文件)。**裁决:R2 命中 → 引入向量**(执行 T3-08..T3-11),并明确"**只补齐、不替换**"——exact 已 1.000,替换只会回退。**执行偏差**:`T3-07` 原依赖 `T3-06`(B 组 L2 对照),本次在 `T3-06` 未完成时裁决,原因与边界写在 ADR §9——R2 只看 L1 指标,而 **S3 未测量**,所以结论只覆盖"词法够不到中文自然语言",**不等于"向量能提升端到端"**。ADR §4 记录了决策前按 §2.8 但书修完 A1(T3-13)与 A4(T3-14)、避免踩 §2.9 陷阱 8;§7 列出 6 条必须与结论同时引用的限制(30 条 CI 宽 [0.274,0.608]、诊断配比非真实流量、L-008 判据偏差、第二轮对比需把 α 收紧到 0.025 等)。**后续 `ADR-15`(2026-09-20):R2 结论保留但执行暂缓**——v1.0 不含向量,`T3-08`–`T3-11` 标为暂缓,后续版本以**可选后端**引入(默认关闭)。依据是 S3 已由纯词法 + 采纳率修复达成(+59.0pp)、分块修复实测对 S1/S2 零收益、以及向量要求用户装 Ollama + 1.2 GB 模型 |
| **T3-15** | 已完成 | `$ python -m pytest tests/test_ab_eval.py -q`(forBSH 环境)
`........................................ [100%]`
(40 passed,退出码 0,**全程离线**:无网络、无 API key。覆盖用例加载与 4 类非法输入、会话日志解析(tool/最终文本/步数/turn_end/usage/interrupted/错误结果)、会话发现(版本化文件名、跳过子代理日志、压缩日志给出可操作报错、多根歧义)、9 类断言的通过与失败、`pass@k`/`pass^k` 的**无偏**组合数定义、命令构造、门禁回归条数与 delta、两种 Markdown 报告,以及用**假 dsh** 跑通的端到端)
`$ python scripts/ab_eval.py --help`
`usage: ab_eval.py [-h] {run,gate} ...`
`L2 end-to-end A/B runner for dsh-coderag.`
`$ python scripts/ab_eval.py gate --baseline ... --current ...` 退出码 0/1 = 门禁是否无回归 | `adbcdbb` | 新增 `src/dsh_coderag/eval/ab.py`(全部逻辑)、`scripts/ab_eval.py`(薄 CLI)、`tests/test_ab_eval.py`(40 例)。补齐了 `T3-00` 判定失败后 `EVAL.md` §3.6 一直悬空的自建 runner。**三处与骨架的有意差异**(已同步进 `EVAL.md` §3.6 表):① 读 `session.v{version}.jsonl`,通过 overlay 把 `session-persistence-jsonl` 配成 `compression: none`,**因此不需要 zstd 依赖**;② 用例是 **JSON 不是 YAML**(项目未声明 YAML 依赖、`mypy`/测试环境也没有,不为一个用例格式加依赖);③ 实现 §3.4 的 9 类断言,`output_judge` **显式报错拒绝**而不是静默忽略。`pass@k`/`pass^k` 用 `C(c,k)/C(n,k)` 无偏估计,门禁看**回归条数**。**未运行真实 A/B**(需要模型 API key,且要先把 DSH 副本索引好)——那是 `T3-05`/`T3-06`。同时更新了 `T3-05`/`T3-06` 的验收命令(不再引用不可用的 `dsh-eval-harness`)。全量 366 例通过,ruff / `mypy --strict src/` 干净。**后续修复(T3-05 冒烟暴露,各自单独提交)**:`cea83f3` 断言匹配折叠 DSH 的 `mcp__
`.........s [100%]`
(9 passed / 1 skipped;跳过的 1 条是需要语料的索引成员校验)
`$ CODERAG_L2_CORPUS=/tmp/dsh-coderag-t3-03-corpus python -m pytest tests/test_cases.py -q`
`.......... [100%]`
(10 passed:**13 条用例的 answer_paths 全部在索引内**) | `3597b3a` | 新增 `cases/*.json` **13 条**(locate 4 / crossfile 5 / regression 2 / negative 2)与 `tests/test_cases.py`。每条在 `notes` 里写了**出处(`file:line` + 符号)与选取理由**,`answer_paths` 作为复核元数据(不参与判分,但被测试用来卡"答案文件必须在索引里"这个公平性陷阱)。**桶的设计意图**:`locate`/`crossfile` 断言 `tools_called: [code_search]`(同时测检索质量与工具采纳);`regression` **不**断言工具被调用,用来验证"检索不该让简单题变差";`negative` 是**反臆造控制组**,断言只要求出现"没有/not found"一类措辞——两条负例(Kafka、Elasticsearch)都在全副本 grep 过 **0 命中**。**未运行**(需要 API key)——那是 `T3-05`/`T3-06`。**后续 `7a9936b`**:每条用例补 `accept`/`reject` 审核样例,测试逐条真跑正则(必须接受全部正确、拒绝全部错误)——这一关当场抓到两条反臆造控制组的假通过(`没有` 匹配到「我没有细看」),收窄为「否定词 + 技术名」后修掉;另收紧 8 条过松/过严正则。**审核办法直接写在对话里,不额外产出文档**;出处与理由留在每行的 `notes` 里。全量 376 例通过,ruff(我新增的文件)/ `mypy --strict src/` 干净。**后续 `a94054f`**:crossfile 桶 `max_steps` 12→16(T3-05 冒烟发现 12 连基线都误杀——`crossfile-todo-snapshot` 的 `output_matches` 在 A/B 两组都已通过,只是步数超限;正确性由答案断言独立把关,16 对另外 4 条 crossfile 用例非绑定) |
| **T3-05** | 已完成 | `$ python scripts/ab_eval.py run --cases cases --group eval-baseline --out eval/runs/a-v1 --profile headless --workspace /tmp/dsh-coderag-t3-03-corpus --trials 3`
`eval-baseline: taskSuccess 0.3076923076923077 (12/39) -> eval/runs/a-v1/report.json`
(39 次 attempt 的 `error` 全为空、`session_log` 全非空;A 组墙钟约 22 min) | `2a2e8d8`(产物入库) | trials=3。分层:`locate 0/12`、`crossfile 0/15`、`regression 6/6`、`negative 6/6`;Wilson 95% `[0.186, 0.464]`。基线无 `code_search`,**凡断言 `tools_called: [code_search]` 的 9 条必失败**,且失败原因全是该断言本身而非答错;4 条不涉及该断言的用例(negative×2、regression×2)全过。语料 `/tmp/dsh-coderag-t3-03-corpus`(3967 文件 / 63046 chunk,`chunks_fts` 同数)。产物**已入库**:`2a2e8d8` 把 `eval/runs/` 的报告与门禁结论纳入 git,只忽略原始 `.sessions/` 与每次重跑都会变的派生输出(`l1-current`/`l1-gate`)——这是"工作区干净"(`AGENTS.md` §7.0)与 CI 里 L1 门禁能生效的前提 |
| **T3-06** | 已完成 | `$ python scripts/ab_eval.py run --cases cases --group eval-coderag --out eval/runs/b-v1 --profile headless --patch cordis.patch.yml --workspace /tmp/dsh-coderag-t3-03-corpus --trials 3`
`eval-coderag: taskSuccess 0.5641025641025641 (22/39) -> eval/runs/b-v1/report.json`
`$ python scripts/ab_eval.py gate --baseline eval/runs/a-v1/report.json --current eval/runs/b-v1/report.json --out eval/runs/gate-v1.json --markdown eval/runs/gate-v1.md`
`delta: +25.6pp | S3(≥+10pp): True | gate: PASS(回归 0 条)`
`改善 6 条,回归 0 条` | `5a867a7` | 产出 `docs/eval-report-m3.md`(**分层指标 + 逐条 diff + L2 失败归因**)。**核心结论:接入 coderag 的 B 组比不接入的 A 组高 `+25.6pp`(0.308 → 0.564),S3 成立**。提升全部来自 `locate`(0 → 0.333)与 `crossfile`(0 → 0.400);`regression`/`negative` 两组均 1.000,即 A 组也过的 4 条**无区分度**。B 的 17 条失败中 **16 条是没调用 `code_search`**(R5 工具采纳),1 条工具报错,**0 条 `max_steps` 撞顶**——没有一条是"检索返回了错误文件",故 `+25.6pp` 衡量的是"工具被采纳的用例变多",不是排序变准(后者属 L1)。`pass@3` A 4/13 → B 10/13;`pass^3` 两组均 4/13(尚未把任何用例变成 3/3 稳定通过)。Wilson 区间 `[0.186,0.464]` vs `[0.410,0.707]` 有重叠且 attempt 间不独立,`+25.6pp` 是小样本估计,不等于真实流量上的效应。`eval/runs/` 的报告与门禁结论已入库(`2a2e8d8`);原始 `session.v3.jsonl` 按 `.gitignore` 排除。**R5 之后的当前 B 组见 `T3-06` 的后续记录与 `docs/eval-report-m3.md` §9**(taskSuccess 0.897、S3 +59.0pp) |
| **T3-04c** | 已完成 | `$ python -m pytest tests/test_report_diff.py`(forBSH 环境)
`....................... [100%]`
`23 passed in 0.07s`
真实金标集(30 条,`/tmp/dsh-coderag-t3-03-corpus`):自比 + 注入一条回归
`[self-diff] compared=30 regressions=0 unchanged=30 gate_passed=True`
`[one flipped] victim=L-001 regressions=1 gate_passed=False`
`## 回归(命中 → 未命中)`
`- **L-001**(exact):hit #1 (packages/mcp/mcp-client/src/index.ts) → miss | DEFAULT_TOOL_CALL_TIMEOUT_MS`
全量 `412 passed, 2 skipped`;`ruff check src tests` / `mypy --strict src/` 干净 | `350c99a` | `report.py` 新增 `QueryDiff` / `diff_runs` / `gate_diff` / `render_diff_markdown`,加 `tests/test_report_diff.py` 23 例。**口径**:只有"命中→未命中"算回归,名次变化单列 `rank_improved`/`rank_regressed`;只对比**两侧都存在**的 query,单侧的进 `only_in_baseline`/`only_in_current` 且**不计入回归**;命中率只按可比集合计算,避免"增删一条 query"污染均值。**门禁默认容忍 0 条回归**:EVAL §2.7 引的"≥2 条才失败"是行业起点,同节又说本项目更严("有没有单条回归"),且 L2 的 `ab.py` 已是"任何回归即失败",故取更严口径并留 `max_regressions` 显式放宽。`waivers` 保留人工豁免通道(对应 EVAL §2.7 的"除非能解释清楚"),被豁免的回归仍列出,**未匹配到回归的 waiver 显式报出**(不静默吞掉)。`k` 不一致直接报错(排名不可比);schema 或结果行非法报错。**未改 `__main__.py`**(T3-04c 的产出文件只有 `report.py`),CLI 接线留给 `T3-12` 的 `eval-gate.sh` |
| **T3-04d** | 已完成 | `$ python -m pytest tests/test_golden_version.py`(forBSH 环境)
`.................. [100%]`
`18 passed in 0.21s`
真实金标集(30 条)三种走法:
`$ python -m dsh_coderag.eval run --tasks eval/tasks.jsonl --root /tmp/dsh-coderag-t3-03-corpus --expect-golden-version m3-b1`
`tasks 30 / hit 13 (k=5, corpus=/tmp/dsh-coderag-t3-03-corpus, golden_version=m3-b1)` → **exit 0**
把 `--expect-golden-version` 换成 `m3-b2`:
`golden_version 不匹配:期望 'm3-b2',实际 'm3-b1'。改了 golden 集就必须同步升版本号,否则分数变化无法归因(EVAL.md 2.7 / 2.9 陷阱 15)。若本次确实是在重建基线,请显式传 --rebaseline。` → **exit 2,且未写出报告**
同上再加 `--rebaseline` → exit 0
全量 `430 passed, 2 skipped`;`ruff check src tests` / `mypy --strict src/` 干净 | `9a96ee7` | 新增 `eval/tasks.meta.json`(**初始 `golden_version = m3-b1`**,即 T3-02b 冻结的 30 条 B 批状态)与 `tests/test_golden_version.py` 18 例;`runner.py` 新增 `GoldenMeta` / `load_golden_meta` / `check_golden_version` / `GoldenVersionError`,`EvalRun` 带上 `golden_version` 作为溯源字段;`__main__.py` 的 `run` 增加 `--expect-golden-version` 与 `--rebaseline`。**校验发生在 `validate_tasks` 与任何检索之前**——方法论破坏要快速失败,不能跑完再报(有专门用例锁这一点)。元数据缺失、JSON 非法、`golden_version` 缺失/空/非字符串**一律报错,不设默认值**。**范围说明**:本任务「产出文件」只列了 `runner.py`,但"版本不符时报错退出"必须落到 CLI,故一并改了 `__main__.py`;`eval/tasks.meta.json` 由 T3-02b 的备注明确指派给 T3-04d;`eval/README.md` 同步为当前状态。**未把 `golden_version` 写进报告 JSON**(那属 `report.py`,本任务范围外)——目前只在 stderr 摘要与 `EvalRun` 上可见,**建议后续补进报告**以支持报告级溯源 |
| **T3-12** | 已完成 | `$ bash scripts/eval-gate.sh`(`CODERAG_GATE_PYTHON` 指向 forBSH python)
**干净基线**:`══ 门禁:PASS ══`,**退出码 0**
`S1 Success@5 = 0.433`
`S2 MRR = 0.313`
`S4 token_median = 2492`
`S3 E2E delta = +25.6pp`
`回归条数 = L1 0(逐 query) + L2 0(用例级) = 0`
**注入一条回归**(把 baseline 里一条 miss 改成 hit 再跑):`回归条数 = L1 1(逐 query) + L2 0(用例级) = 1` → `══ 门禁:FAIL ══`,**退出码 1**
全量 `440 passed, 2 skipped`;`ruff check src tests` / `mypy --strict src/` 干净 | `7ff58c6` | 新增 `scripts/eval-gate.sh` 与 `tests/test_eval_gate_cli.py`(5 例)。脚本串起三层:L1 `pytest` → **L1 指标 + 逐 query 门禁**(`python -m dsh_coderag.eval gate`)→ **L2 A/B 门禁**(`scripts/ab_eval.py gate`),输出 **S1–S4 + 回归条数**。**退出码 0/1/2**:0 通过、1 有回归 / pytest 红 / L2 FAIL、2 环境不可用(缺语料或缺 baseline)——**缺 baseline 绝不静默放行**。为拿到 S1/S2/S4,`eval/__main__.py` 新增 `gate` 子命令(**T3-04c 备注里明确把这条接线留给 T3-12**):它把 **baseline 报告里的 `golden_version` 当作 pin**,于是"改了题却没升版本号"直接判 FAIL,而不是悄悄重定义对比基线;版本破坏记为门禁失败(1)而非输入错误(2)。**前置**:需要一份 L1 baseline 报告(`CODERAG_L1_BASELINE`,默认 `eval/runs/l1-baseline.json`);L2 报告可选,缺则跳过并提示。⚠️ **`eval/runs/` 已被 `.gitignore` 忽略**,baseline 因此不入库 → 新克隆上脚本以 2 退出并打印生成命令;**待定项**:是否把 L1 baseline 提交到 `eval/baselines/`,否则 CI 里的 L1 门禁无法生效 |
| **T4-01** | 已完成 | `$ node -e "console.log(require('./package.json').dsh.bundle)"`
`{ patch: './cordis.patch.yml' }`
`$ node -e "const p=require('./package.json'); console.log('main:',p.main,'\| bin:',p.bin,'\| scripts:',p.scripts)"`
`main: undefined \| bin: undefined \| scripts: undefined`
`$ npm pack --dry-run`
`npm notice 1.1kB LICENSE`
`npm notice 14.8kB README.md`
`npm notice 1.5kB cordis.patch.yml`
`npm notice 270B package.json`
`npm notice total files: 4`(`package size: 9.5 kB`) | `340cf5f` | 新增仓库根 `package.json`:`name`/`version`/`description`/`license` + `files: ["cordis.patch.yml"]` + `dsh.bundle.patch: "./cordis.patch.yml"`,**无任何 JS 入口**(`main`/`bin`/`scripts` 全为 `undefined`)。DSH 的解析方式已在 `dsh-app-boot` 源码核实:`patchPath = join(packageDir, declared)`(相对包目录解析)。tarball 只含 4 个文件 / 9.5 kB,`cordis.patch.yml` 是唯一的分发内容 → bundle 里没有构建脚本,**C11(pnpm 拒绝 install script)从根上不适用**,正是 §1.6.1 的设计意图。**下一任务 `T4-02` 才真正验证 `dsh plugin add .` 能装载这一层**(本任务只做清单) |
| **T4-02** | 已完成 | `$ ./scripts/dsh plugin --profile coderag-dev add .`(E-07:经包装脚本;沙箱先拒绝写 `~/.dsh`,按沙箱规则提权一次)
`dsh: initialized profile coderag-dev at /Users/vermi/.dsh/profiles/coderag-dev`
`Already up to date`
`dependencies:`
`+ dsh-coderag link:../../../个人项目/python/dsh-coderag`
`Done in 1.7s using pnpm v12.4.2`(rc=0,**无 install script 报错**,无 `ERR_PNPM_*`)
`$ ./scripts/dsh --profile coderag-dev --dump-config`
`# == @deepseek-ai/dsh-base`
`…(# == @deepseek-ai/dsh-base 层:84 条 / 332 行)…`
`# == dsh-coderag`
`- id: mcp-coderag`
` name: '@deepseek-ai/dsh-mcp-client'`
` config:`
` serverName: coderag`
` transport: stdio`
` command: !!js process.env.CODERAG_PYTHON ?? '/opt/anaconda3/envs/forBSH/bin/python'`
` args:`
` - '-c'`
` - import dsh_coderag.server as s; s.run()`
` env:`
` CODERAG_ROOT: !!js process.env.CODERAG_ROOT ?? process.cwd()`
(rc=0;stdout `10843` 字节 / stderr `0` 字节,即无 patch 应用警告。期望两项逐项对应:本插件的层 = `# == dsh-coderag`(第 333 行,层标签取**包名**);MCP 行 = `- id: mcp-coderag`(第 334 行)。登记后 profile 清单 `dsh.profile.bundles` 由 `["@deepseek-ai/dsh-base"]` 变为 `["@deepseek-ai/dsh-base", "dsh-coderag"]`) | `269ac19` | 新增 `docs/m4-bundle.md`(分发形态、DSH 源码核实的解析/登记行为、验收实录、8 项自检清单、复现步骤与已知边界)。**`cordis.patch.yml` 无需改动**——T1-14 已把同一文件写成 dev overlay 兼 bundle patch;本任务确认为"已就绪"。tarball 只含 4 文件且无 `scripts`,**C11/E-05 从根上不适用**。**范围外发现**(未顺手改,AGENTS §9):`README.md` 第 44–48 行仍写"本地 `dsh plugin add .` 属 T4-02、尚未验证",本任务完成后该句过期,留给 `T4-06`/`T4-08` 一并更新 |
| **T4-03** | 已完成 | `$ CODERAG_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/install.sh`(第 1 次)
`conda :当前 shell 激活的是 base → /opt/anaconda3`
`解释器 :/opt/anaconda3/envs/forBSH/bin/python(来源:CODERAG_PYTHON)`
`版本 :3.10.21 ✅`
`FTS5 :可用 ✅(预检)`
`安装 :检测到本仓库已 editable 装在此解释器上,保持 editable(改 src/ 立即生效)`
`安装 :"...python" -m pip install -e .`
`Successfully installed dsh-coderag-0.1.0`
`FTS5 :可用 ✅`
`bigram :幂等 ✅ '用户令牌' -> '用户 户令 令牌'`
`往返 :中文查询命中 ✅ 标识符命中 ✅ 无关词不命中 ✅`
`包版本 :dsh_coderag 0.1.0`
`完成:安装与自检通过 ✅`(rc=0)
**第 2 次(幂等)**:同样 rc=0;脚本自身输出与第 1 次逐字相同——两次完整输出的 diff 只差 pip 自己的临时 wheel 缓存目录与 sha256(那是 pip 的输出,不是脚本的)
`$ CODERAG_PYTHON=/nonexistent/python bash scripts/install.sh`
`错误:解释器不可执行或不存在:/nonexistent/python(来源:CODERAG_PYTHON)`(rc=2)
`$ python -m pytest tests/test_install_script.py`
`5 passed in 0.58s` | `55702df` | 新增 `scripts/install.sh`(**产出文件只列了它**;`tests/test_install_script.py` 5 例是按 DoD §5.1 第 5 条补的)。流程:① 选解释器 `CODERAG_PYTHON` → 当前激活的 conda 环境 → PATH 上的 python3/python,并单独报告 conda 状态;② 版本门禁 `>=3.10,<3.13`(对应风险 R8),不符时打印实际版本与 `conda create` 指引;③ **FTS5 预检放在 pip 之前**(只用 stdlib:缺 FTS5 就没必要装,早失败);④ `pip install`,`CODERAG_PIP_ARGS` 支持受限网络镜像,PEP 668 给 conda/venv 指引;⑤ 自检做**真实 FTS5 往返**(`unicode61` + bigram,含"无关词不命中"阴性对照与 `to_bigrams` 幂等),再打印下一步。**关键设计——editable 保护**:本机 forBSH 是 `pip install -e .`,而普通 `pip install .` 会把开发安装冻结成 site-packages 副本、之后改 `src/` 不生效,**后续任务会在不知情下测到旧代码**;故检测到"本仓库已 editable 装在该解释器上"时保持 editable,可用 `CODERAG_EDITABLE=0/1` 强制。退出码 0/1/2(pip 失败 1、环境不可用 2)与 `scripts/eval-gate.sh` 一致。测试用 `CODERAG_SKIP_INSTALL=1` 做到**离线**(`TESTING.md` T-02),并断言两次运行 stdout 逐字相同以锁住"幂等"这一验收项 |
| **T4-04** | 已完成 | 人工审阅(`README.md`,`D-04` 要求安全声明在第一个屏幕内)
`$ sed -n '1,8p' README.md \| grep -n "机器权限"`
`5:> **安装本插件等于授予它与本机账号同等的机器权限。**`
(第 5 行,位于文档顶部引用块;同块还写明三档权限**不约束插件**(`E-04`)与"只在你信任的仓库与本机安装") | `d483e64` | 新建 `README.md`;顶部安全声明对应约束 `C12`/`E-04`。**此前未列入 §6.7 是历史遗漏**,本行按用户指示补记,README 内容未改 |
| **T4-05** | 已完成 | 人工审阅(`README.md` 含能力说明 / 安装 / 配置 / 限制 / 评测数据 / 已知问题,`D-03`)
`$ grep -c '^## ' README.md`
`13`(装上去能带来什么、当前状态、它是怎么工作的、安装、配置、工具、CLI、实测评测数据、已知限制、安全与隐私、开发、文档、许可)
`$ grep -E '^[\|] \*\*S[1-4]\*\*' README.md`
`\| **S1** \| 检索本身有效:Success@5 \| ≥ 0.80 \| **0.433**(30 条,95% CI [0.274, 0.608]) \| ❌ \|`
`\| **S2** \| 排序质量:MRR \| ≥ 0.60 \| **0.313** \| ❌ \|`
`\| **S3** \| 端到端有提升(有检索 vs 无检索) \| ≥ +10pp \| **+59.0pp**(0.308 → 0.897) \| ✅ \|`
`\| **S4** \| 成本:单次返回 token 中位数 \| ≤ 4000 \| **2492** \| ✅ \|`
(S1–S4 全部为实测数字;另有分层指标表、L2 A/B 表与失败归因) | `d5c6f84`, `ca51c5f` | 补全 README 全部章节;此后 `a33c44e` 对齐了 4 处过期陈述。**此前未列入 §6.7 是历史遗漏**,本行按用户指示补记。**后续 `ca51c5f`**(用户指示):在**靠前位置**新增「装上去能带来什么(冒烟测试实测)」章节——数据取自已入库的冒烟运行 `eval/runs/a-smoke` / `b-smoke` / `gate-smoke.md`(13 条 × 1 次:A 4/13 = 0.308 → B 10/13 = 0.769,**+46.2pp、0 回归**;`locate` 0/4→3/4、`crossfile` 0/5→3/5、`regression`/`negative` 保持 2/2 不变差),并如实标注"冒烟级小样本、不回答排序准不准"、指向完整 3-trial L2 与 L1;同时改掉 `T4-02` 造成过期的陈述(M4 状态行、`cordis.patch.yml` 的"将来的分发 patch"、安装注意块、"尚未打包"限制)并补全文档表(新增 `ADR-15` 与 `docs/m4-bundle.md`)。**证据命令改为与行号无关**:用 `grep -E '^[|] \*\*S[1-4]\*\*'` 而不是 `sed -n 'A,Bp'`——每次在 README 前面插内容都会让硬编码行号失效并打印出错误的行 |
| **T4-06** | 已完成 | 人工审阅(README 新增 `### 安装故障排查`:pnpm 10+ 的 `allowBuilds` 报错原文、登记失败的自查方法、以及 pnpm 缺失 / 解释器路径 / PEP 668 / 缺 FTS5 几类现象与对策)
**干净 profile 实测**(全新 `DSH_HOME`,profile `clean-test` 此前不存在):
`$ rm -rf /tmp/dsh-coderag-t4-06 && DSH_HOME=/tmp/dsh-coderag-t4-06 ./scripts/dsh plugin --profile clean-test add .`
`dsh: initialized profile clean-test at /tmp/dsh-coderag-t4-06/profiles/clean-test`
`Already up to date`
`dependencies:`
`+ dsh-coderag link:../../../../../Users/vermi/个人项目/python/dsh-coderag`
`Done in 5.3s using pnpm v12.4.2`(**rc=0**)
`$ … add . 2>&1 \| grep -iE "ERR_PNPM\|allowBuilds\|build script\|prepare"`
(**无匹配**,grep 退出码 1——四类关键字一个都没出现)
干净 profile 的 `pnpm-workspace.yaml` 只有 `packages:` / `nodeLinker: hoisted` / `autoInstallPeers: false`——**没有 `allowBuilds`**
`$ DSH_HOME=/tmp/dsh-coderag-t4-06 ./scripts/dsh --profile clean-test --dump-config \| grep -n -A6 '^# == dsh-coderag'`
`333:# == dsh-coderag`
`334:- id: mcp-coderag`
`335- name: '@deepseek-ai/dsh-mcp-client'`
(rc=0,stderr 0 字节) | `59e77e7` | 新增 `docs/m4-install-verification.md`(方法、实际输出、坑本身、尚未验证部分;T4-08 会往同一文件追加端到端)。README 的新小节用 `###` 而非 `##`,以免改动 `grep -c '^## '` 这个 T4-05 证据。**核心结论**:干净 profile 首次 `add` **完全不需要 `allowBuilds`**——本 bundle 的 `package.json` 连 `scripts` 段都没有(`T4-01`),pnpm 没有可拒绝的东西,**C11/E-05 从根上不适用**;坑的文本仍写进 README,因为**别的**带 `prepare` 的 git 插件会踩它,而 `dsh plugin add` 在 pnpm 非零退出时**静默跳过 bundle 登记**,用户会误以为装了却没加载,所以文档给了 `--dump-config` 这条自查。**范围修正**:README 里"安装脚本(`T4-03`)还没做"与"无 `scripts/install.sh`"两处在 T4-03 落地后已过期,本任务一并改掉并指向 `bash scripts/install.sh` |
| **T4-07** | 已完成 | `$ test -f LICENSE && test -f CHANGELOG.md && echo "两份文件都在"`
`两份文件都在`
`$ head -3 LICENSE`
`MIT License`
`(空行)`
`Copyright (c) 2026 Vermilion Pasvikin`
`$ grep -cE "Permission is hereby granted, free of charge\|The above copyright notice and this permission notice\|THE SOFTWARE IS PROVIDED" LICENSE`
`3`(MIT 三个必备条款都在)
`$ grep -cE "YEAR\|
`0`(无占位符) | `101a51a` | `LICENSE` **在初始提交 `9ed8bcd` 时就是 MIT 全文**(年份 2026、版权人 `Vermilion Pasvikin`),本任务核实后**无需改动**——与 `T4-02` 的 `cordis.patch.yml` 同类情况。新增 `CHANGELOG.md`(Keep a Changelog 格式,`[0.1.0] - 2026-09-23`):按「新增 / 安全」列出 4 个 MCP 工具、FTS5 + bigram 索引、三层安全过滤、声明感知分块、增量索引与自适应并发、顺序保持检索、bundle 与安装脚本、L1 + L2 评测;并写明**尚未发布到 PyPI/npm**、**不含向量**(指向 `ADR-15`)。**范围修正**(README 由本任务造成的过期陈述):M4 状态行改为"只差 `T4-08`";「已知限制」里"无 `CHANGELOG.md`"删掉;文档表补 `CHANGELOG.md` 一行 |
| **T4-08** | 已完成 | **M4 出口判据**。全新 `DSH_HOME=/tmp/dsh-coderag-t4-08` + 全新 profile `clean-test`(此前不存在):
`$ DSH_HOME=/tmp/dsh-coderag-t4-08 ./scripts/dsh plugin --profile clean-test add .`
`dsh: initialized profile clean-test at /tmp/dsh-coderag-t4-08/profiles/clean-test`
`+ dsh-coderag link:../../../../../Users/vermi/个人项目/python/dsh-coderag`
`Done in 31ms using pnpm v12.4.2`(rc=0)
零状态工作区:`rsync --exclude .coderag examples/demo-workspace/ /tmp/dsh-coderag-t4-08-ws/`(**无任何索引**)
用 `--dump-config` 里那一行**原样**启动子进程(`/opt/anaconda3/envs/forBSH/bin/python -c 'import dsh_coderag.server as s; s.run()'`,工作区走 `config.env` 的 `CODERAG_ROOT`),在 stdin/stdout 上说换行分隔 JSON-RPC:
`<<< serverInfo {"name":"coderag","version":"0.1.0"}`
`--- tools --- ['code_search', 'code_outline', 'code_index', 'index_status']`
`code_index -> {"taskId": "idx-20260923-5fc3", "state": "pending"}`
`index_status -> running -> {"state": "ready", "total_files": 3, "total_chunks": 7}`
`code_search("用户令牌在哪里校验") ->`
`status: ready`
`hits: 1 (sorted by source order)`
`── src/auth/token.py:1-6 [module] (chunk 0)`
(4 次 `tools/call` 的 `isError` 全为 `false`;子进程退出码 `0`;stderr 仅 2 行 JSON-Lines 日志,stdout 每一行都是合法 JSON-RPC) | `ab94dcf` | 把 `docs/m4-install-verification.md` 第 5 节写成 T4-08 的端到端记录(方法 / 原始报文 / stderr 日志 / **这次不覆盖什么**)。**驱动不经过模型**:用 stdlib 直接说 JSON-RPC,所以它证明的是"装完之后工具真的可用、返回结构化结果",**不**证明"模型会用得好"(后者是 L2 A/B)。**命中是易例**:`用户令牌在哪里校验` 与 demo 工作区 `token.py` 的 docstring 有 bigram 重叠,属"有词法线索";**纯中文自然语言在大仓库上仍是 `S@5 = 0.000`**(L1 `natural` 桶),文档明确写了这条限制不因本任务改变。探针脚本事后**不留在仓库**(本任务产出文件只列文档),启动方式与协议报文都记进文档以便复现。**范围修正**(README 由本任务造成的过期陈述):M4 状态行改为"出口判据已通过,剩 `T4-09`/`T4-10`";安装注意块与「已知限制」不再说"干净 profile 未验证",只保留"registry 安装未验证";文档表描述同步 |
| **T4-09** | 已完成 | 验收命令是「浏览器确认 / topic 已加」。**用 GitHub API 核实**(topic 发现页会滞后,仓库的 topic 列表才是这个任务的确切目标):
`$ curl -s https://api.github.com/repos/VermilionPasvikin/dsh-coderag/topics`
`{"names":["dsh-plugins","mcp","python","rag","vibe-coding","dsh-plugin"]}`
`$ curl -s https://api.github.com/repos/VermilionPasvikin/dsh-coderag`
`"topics":["dsh-plugin","dsh-plugins","mcp","python","rag","vibe-coding"]`(两个端点一致)
DSH 官方 README 第 46 行要求的正是**单数** `dsh-plugin`:
`- Add the [dsh-plugin](https://github.com/topics/dsh-plugin) topic to your plugin repository for discoverability.` | —(本任务无仓库改动,仅 GitHub 仓库设置) | **由用户执行**(Agent 无仓库写权限)。**第一次加的是 `dsh-plugins`(复数),不满足官方要求**——我用 API 核实后报告,用户随即补上单数形式,本行证据是**补好之后**重新验的两次 API 返回。`README.md` 除 M4 状态行外无需改动(M4 状态行已由"剩 `T4-09`/`T4-10`"改为**已完成**) |
| **T4-10** | 已完成 | 验收命令是「人工对照代码审阅 / 无过时描述」,审阅方法:抽出 `AGENTS.md` 里**所有可核对的声明**(章节引用、文件路径、工具可用性、分支、scope 列表),逐条对**已安装的 DSH 包**与**本仓库代码**核对,并用 AST 统计编码规范的实际符合度。
实际测量:
`C-09 缺 future import 的模块: 无`
`C-03 裸 except: 无`
`C-04 超过 50 行的函数: 12`(最长 `indexer.index_sync` 99 行)
`C-02 的 pydocstyle: No module named pydocstyle`
`C-07 Windows 风格路径测试: 无命中`
`git branch -a → 只有 main`
`AGENTS 的 §引用全部存在(§1.3/§2.3/§2.4/§3.4–3.7/§4.3.1/§5.3.1/§6.7…)`
新增 `docs/architecture.md`(222 行);修正 AGENTS 5 处 | `6c7335b` | 新增 **`docs/architecture.md`**:运行时形态(DSH 如何拉起、为什么用 `-c`)、模块表与**用真实 import 图核对过的**依赖方向、索引/检索数据流、5 张表的数据模型、工具契约、安全模型、异步与上限、可观测性、评测分层、非目标。**AGENTS.md 修正 5 处**:① C-02 的检查方式(`pydocstyle` **未安装**、`ruff` 的 `D` 规则也未开 → 改为"只靠人看");② C-04 标注**当前未达标**(12 个函数 > 50 行,规则不放宽);③ C-07 标注**当前未达标**(6 处 `as_posix()` 合规,但零 Windows 路径测试);④ §7.1 的 scope 列表补齐(原表漏了 `types`/`parser`/`text`/`sanitize`/`sqlite_caps`/`log`,以及实际在用的 `bundle`/`install`/`adr`/`repo`/`readme`/`project`/`testing`/`cases`);⑤ §7.3 分支改为实情(**只有 `main`**,M1–M4 都没开里程碑分支)。另新增两条 backlog 欠账(C-04 / C-07),修掉 `PROJECT.md` §3.4 里"`eval` **当前未创建**"与"`render` 被 M3 的 eval 调用"两处过期陈述,并把 eval 的依赖改成实测值(`runner`→searcher;`attribute`→indexer/walker/text)。**核实教训**:核查 DSH 侧引用必须读**已安装的包**——E-04 引的 `tool-cordis/README.md` 第 182 行在安装版里属实,但本机 `~/projects/dsh` 参考副本较旧(只有 76 行),一度被我误判为错误引用;已把这条写进 E-04 的依据格 |
| **T5-01** | 已完成 | `$ grep -c -e tests/test_retrieval_quality.py -e indexed_workspace -e "limit 默认是" EVAL.md`
`0`(三项旧表述全部 0 命中)
`$ grep -n dsh-eval-harness EVAL.md`
10 处命中(`:378` `:383` `:394` `:396` `:415` `:475` `:500` `:587` `:639` `:644`),**全部是"未采用/不兼容"结论或调研记录**,无一处再把它作为 L2 的工具选择:`:378` 选型表结论列 `已否决——T3-00 实测与本机 DSH 不兼容`;`:383` `当时看中…的理由(记录用,日后若要重估可从这里接手)`;`:394`/`:396`/`:415` §3.2 标题与 `T3-00` 实测结论;`:475` `已被 T3-00 判定不兼容并否决`;`:500` §3.6 状态;`:587` §5.1 `未采用…L2 用自建 scripts/ab_eval.py`;`:639`/`:644` §6 修订记录(后者标 `已撤销`)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.10s` | `5635909`(`EVAL.md`), `a2fb5d8`(backlog 欠账记录) | 纯文档改动(`EVAL.md` + 一条 backlog 记录),无代码变更。**审计清单逐条落地**:① L2 工具列与第 3 章标题不再写"现成 `dsh-eval-harness`";② `T3-00` 不再写作"新增前置任务",改为实测结论(可装载但 trace 采集器只认 `session.jsonl(.zstd)`,本机落盘 `session.v3.jsonl.zstd` → 判定不兼容);③ 三处 `tests/test_retrieval_quality.py` 与 `indexed_workspace` fixture 换成真实落点(`tests/test_eval.py` 等 + `eval_corpus` fixture / `CODERAG_EVAL_CORPUS` opt-in);④ `eval validate` 补 `--tasks`/`--root`;⑤ `limit` 默认值 12 → **5**;⑥ "L2 只在 M3 决策门跑一次"改为实情(已跑 `a-v1`/`b-v1`/`b-r5`/`a-smoke`/`b-smoke` 多轮);⑦ "3~4 小时" → **4–5h**(与 §2.1/§2.4 一致);⑧ §5.1 与 §7 速查的 `eval_run`/`eval_gate` 换成 `scripts/ab_eval.py`,§3.5 的示例代码改为**可实际执行**的命令。**另外三处同类的文档错误一并修正并记录在此**:§2.4 完整流程的 Step 2/Step 3 条数写 `10 exact`/`9 crossfile`(合计 26),与 §2.3 的 12/11 及 `eval/tasks.jsonl` 实际 30 条矛盾,改为 **12/11**;§6 修订记录里"`T3-05`/`T3-06` 改用 `dsh-eval-harness`"标为**已撤销**;§8「未能核实的事项」删掉已被 `T3-00` 实测回答的 `dsh-eval-harness` 兼容性一条。**顺带发现一个越界缺陷**(已按 `AGENTS.md` §9 记入 `docs/backlog.md`,未顺手修):`tests/test_eval.py::test_a_batch_runs_against_indexed_corpus` 仍断言 `len(tasks) == 10`,而 golden 集已是 30 条;该用例由 `CODERAG_EVAL_CORPUS` opt-in,默认套件与 `eval-gate.sh` 都不设它,故不影响门禁,但设了就会假红(实测 `AssertionError: assert 30 == 10`)。`EVAL.md` §4.1 已在引用处标注这条欠账 |
| **T5-02** | 已完成 | `$ grep -c -e test_retrieval_quality -e "tests/e2e/" -e indexed_eval_corpus TESTING.md`
`0`(三项旧表述全部 0 命中;无命中时 `grep -c` 退出码为 1,属预期)
`$ grep -n "多平台矩阵" TESTING.md`
`763:**跑多平台矩阵**(3 OS × 2 Python)…**这一条推翻了本文件 1.0 版的"第一版只跑 macOS"建议**`
`803:**⚠️ 为什么多平台矩阵是必要的(推翻了本文件早先"第一版只跑 macOS"的建议)**`
`873:多平台矩阵:按 §5.1 跑(3 OS × 2 Python)——本文件 1.0 版"第一版只跑 macOS"的建议已被推翻`
(三处口径一致,都指向"跑";原先 §7 速查里那句 `不做多平台矩阵` 已删——它正是唯一与本结论冲突的一处)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.59s` | `1aafdb5`(`TESTING.md`) | 纯文档改动(`TESTING.md`),无代码变更。**审计清单逐条落地**:① 目录树里的 `test_retrieval_quality.py`(从未创建)与 `tests/e2e/…`(目录不存在)删掉,换成真实落点,并给整棵树加"**代表性命中,不是完整清单**"的口径 + 当前真实数量(**44** 个 `test_*.py`);② 属性测试落点改正——Hypothesis **只在** `tests/test_chunker_decl.py`(M6 的两条不变式 `test_chunker_never_loses_content`/`test_chunker_never_overlaps`),`test_too_many_files.py` 的 M8 是**手写例子**、不含 hypothesis,`test_properties.py` 不存在;③ 中文用例主落点补上 `test_cjk_recall.py`(`T3-13`),并写明 `cjk_corpus` 是建在该文件里的 `tmp_path` fixture、`tests/fixtures/cjk/` 不存在;④ 不存在的 `indexed_eval_corpus` fixture 换成 `eval_corpus`(`tmp_path` 小语料)+ `CODERAG_EVAL_CORPUS` 的 opt-in 回放;⑤ §5.1 与 §7 的多平台矩阵口径统一为"跑(3 OS × 2 Python)";⑥ `FTS5_UNAVAILABLE` 不再写"必须同步加进去",改为"早已加进去并已实现"(`T1-03`/`T2-22` 两行)。**另外三处同类问题一并修正并记录在此**:§3.3 的"更严版本"指向不存在的 `tests/e2e/test_stdio_protocol.py`,改为真实落点 `tests/test_cwd_shadowing.py::test_launcher_serves_mcp_with_shadowing_modules_in_cwd`;§3.8 代码块里的 `tests/test_properties.py` 改为"设计稿"标注;§3.3 不再声称子进程级用例已断言"stdout 每一行合法 + stderr 是 JSON Lines"——**实测该用例只读第一条回答并断言 `serverInfo.name == "coderag"`**,完整覆盖现状(进程内 `tests/test_server.py::test_no_stdout_pollution_during_tool_call` + `tests/test_log.py::test_index_writes_json_lines_to_stderr`;子进程级的更强断言**尚未落地**)已如实写进文档。**核实教训**:本任务在提交前自查出三处自己刚写下的错误断言(`grep -c` 那次命中来自我新加的说明文字本身;`PROJECT.md` §5.6 错误码表里 `FTS5_UNAVAILABLE` 的位置我先写成"第 6 个"、实为**第 2 个**;子进程级用例的断言范围被高估),三处都是**跑命令核对**才发现的——**文档里的每个"事实"都必须逐条跑命令验证,不能凭印象写** |
| **T5-03** | 已完成 | `$ grep -c "后续更新" docs/adr/ADR-14-semantic-retrieval.md`
`3`(三处各一条,全部带日期 `2026-09-23`)
`$ grep -n "后续更新" docs/adr/ADR-14-semantic-retrieval.md`
`139:` §7.1 → `S3 **已测量**(2026-09-20 的复核,数据见 §10.1):…A 组 12/39 = **0.308** → B 组 22/39 = **0.564**,**+25.6pp**,门禁 0 回归 / 6 条改善`
`158:` §8 表 → `表中 T3-12 **已完成**(7ff58c6,产物 scripts/eval-gate.sh)…S1 0.433 / S2 0.313 / S4 2492 / S3 +25.6pp,回归条数 L1 0 + L2 0 = 0,门禁 PASS 退出码 0;注入一条回归后退出码 1`
`162:` §8 未决前置 → `该前置**已完成**——自建薄 runner 由 T3-15 落地(src/dsh_coderag/eval/ab.py + scripts/ab_eval.py,adbcdbb),T3-05/T3-06 已在它上面跑完(报告入库于 2a2e8d8)`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.33s` | `05d81b8`(`docs/adr/ADR-14-semantic-retrieval.md`) | 纯文档改动(`docs/adr/ADR-14-semantic-retrieval.md`)。**只加"后续更新"块,原句一字未改**(`git diff` 只有 3 处新增、0 删除行)——`ADR` 是**决策时快照**、不是现状描述(`D-06` 的边界),所以历史结论保持原样、由日期化现状块并置说明。三处的依据都指向**已有产物**而非转述:`7ff58c6`(`T3-12`)、`adbcdbb`(`T3-15` 自建 runner)、`2a2e8d8`(`T3-05` 报告入库),数字取自 §10.1 与 `PROJECT.md` §6.7 的对应行。**边界说明**:§7 只声明"限制 1 已过期、限制 2–6 仍有效",没有动 §1 的裁决;§8 只声明那两个前置已完成,**没有**改 `T3-08`–`T3-11` 的执行状态——那属 `T5-12` 的范围 |
| **T5-04** | 已完成 | `$ grep -c "后续状态" docs/m4-bundle.md docs/m1-findings.md docs/m2-findings.md`
`docs/m4-bundle.md:1`
`docs/m1-findings.md:1`
`docs/m2-findings.md:1`(每份恰好 1 条**汇总**标注,不逐行改写)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.34s` | `c22cd34`(3 份里程碑快照) | 纯文档改动(3 份里程碑快照)。**只新增汇总块,原句一字未改**——三份都是**当时观测的存档**,按 `D-06` 的边界不改写历史。① `docs/m4-bundle.md`:§1 表里"干净 profile 端到端 ⏳ 属 `T4-08`"**已完成**(全新 `DSH_HOME`+全新 profile `clean-test`,原样 argv 起子进程走完 `initialize`/`tools/list`/`tools/call`,4 次调用 `isError` 全 `false`、退出码 0、stdout 每行合法 JSON-RPC,`ab94dcf`),并声明该注同样覆盖 §5「已知边界」里同源的两条;**"从 registry 安装 ⏳ 未发布"明确保留**(本项目迄今未发布到 PyPI/npm)。② `docs/m1-findings.md`:`path`/`max_tokens` **已生效**(`tests/test_path_filter.py` / `tests/test_token_budget.py`),召回模式/查询改写/标点路由**已落地**(`T2-19`=`5f02646`、`T3-13`=`e7d7624`)。③ `docs/m2-findings.md`:观察 3 的结论与"已知限制"里同一条**已落地**,并**明确保留根因**——纯中文原问句在大仓库上 `natural` 桶 `S@5` 仍是 **0.000**,那是 M5 的目标。**三份都同时写明"其余限制仍然有效"**,避免日期化标注被读成"整份文件已过期" |
| **T5-05** | 已完成 | `$ test -f docs/adr/ADR-16-optional-vector-backend.md`
(退出码 0,文件存在)
`$ grep -c "^## " docs/adr/ADR-16-optional-vector-backend.md`
`10`(决策 / 形态 / 后端与依赖 / 配置与环境变量命名 / 向量索引落点 / 失败模式与结构化状态 / 发布范围与验收判据 / 数据与安全 / 诚实的限制 / 与其它决策的关系;要求 ≥6)
`$ python3 scripts/verify-plan.py .`
`✅ [B1] ADR: 16 条全部在矩阵里`
`✅ [F4] 矩阵 48 行 ≥ 下限 45`(原 47 行 + `ADR-16` 一行)
`✅ [B4] 48 个矩阵键全部对应真实定义`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.34s` | `608f08c`(`ADR-16` + §3.7/§6.8 行 + 命名表) | 新增 `docs/adr/ADR-16-optional-vector-backend.md`,并**同一次提交**更新 `PROJECT.md` 的 §3.7 ADR 表行与 §6.8 覆盖矩阵行(`verify-plan` 的 `B1` 强制),另补了文首命名表的环境变量行。**冻结的条文**(逐条对应 `ADR-15` §3 的重启条件):① 形态=默认关闭 + opt-in + **关闭态输出与 1.0.0 逐字节一致**(否则 M9 快照全红、`S6` 无从判定);② 后端=**本地 Ollama + `bge-m3`**,云端 embedding 因 `S-01`/`S-02` 否决;③ 依赖=extra **`semantic`,内容只有 `numpy`**,HTTP 走 stdlib `urllib`(不引入 httpx)、不引入向量库,`CODERAG_WITH_SEMANTIC` 未设则 `install.sh` 不装;④ 配置命名冻结 `CODERAG_SEMANTIC`(只有 `on` 启用)/`_BACKEND`/`_URL`(**必须 loopback**)/`_MODEL`/`_TIMEOUT`/`_BATCH`/`_MAX_CHUNKS`,全部可覆盖(`RL-07`);⑤ 索引落点 `
(**无匹配**,grep 退出码 1——两句旧表述都 0 命中)
`$ grep -c "默认路径或必需依赖" AGENTS.md`
`1`(RL-10 新表述)
`$ grep -c "干净回退 BM25" AGENTS.md`
`1`(RL-10 新表述)
`$ grep -c "本地后端" AGENTS.md`
`1`(S-01 新增的"本地后端也不得默认启用")
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.53s` | `ff9eb78`(`AGENTS.md` + §6.8 `RL-10` 行) | 纯文档改动(`AGENTS.md` + `PROJECT.md` 的 §6.8 `RL-10` 行)。**RL-10 改写为发布范围约束**:"向量不得进入默认路径或必需依赖;未配置时必须干净回退 BM25",并逐项点名 `dependencies` / tarball / `install.sh` 默认路径 / README 安装前置四处;**旧表述的历史保留在同格的理由里**("旧 RL-10 的使命已完成——`T3-07` 已裁定,`ADR-15` §4 明确它不因暂缓而恢复"),并把"新红线保护的对象换了"写明:从"别过早引入"变成"**别把可选做成必需**"。**§3.2** 的"不引入向量数据库(M3 决策前)"改为"不引入向量**数据库**"——理由换成 `ADR-14` 的"≤10 万 chunk 用 `numpy` 暴力余弦即可",做法列"默认路径 SQLite FTS5;可选向量后端用 `numpy`(`ADR-16` §3.1)"。**S-01** 补上"**本地后端(如 Ollama)同样不得默认启用**",并把 `CODERAG_SEMANTIC` 未设即关闭、`_URL` 只允许 loopback 两条可验收细节写进去。**§8 反模式清单**里"过早引入重依赖"的正确做法同步补上"向量只做可选 extra 且默认关闭"(原先只引 RL-10,而 RL-10 已不再讲"过早")。**§6.8 矩阵行**同步:强制点由 `T3-07`(旧红线的落点)改为 **`T3-10, T5-15, T5-16`**——分别强制"未配置时逐条回退纯 BM25"、"默认安装零向量依赖"、"默认安装的解释器里没有 numpy",这三个正是新 RL-10 的可验收形式 |
| **T5-07** | 已完成 | `$ python3 scripts/verify-plan.py .`
` ✅ [B1] 成功标准 S*: 6 条全部在矩阵里`
` ✅ [F4] 矩阵 50 行 ≥ 下限 45`(原 48 行 + `S5`/`S6` 两行)
` ✅ [B4] 50 个矩阵键全部对应真实定义`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.92s` | `1b78f72`(§1.4 + §6.8 的 `S5`/`S6` 行) | 纯文档改动(`PROJECT.md`)。**`S1`–`S4` 一行未改**(稳定标识不得改名),新增两条:`S5` = 开启后端后 **`natural` 桶 `Success@5` ≥ 0.40**(沿用 `EVAL.md` §2.7 已有的 natural 桶阈值,不新造数字;7 条里至少命中 3 条,0.40 对 7 条是可判定的),`S6` = 未配置时 30 条逐条与 `1.0.0` 一致、**回归条数 = 0** 且 `exact` 桶保持 **1.000**(由 `T3-12` 门禁给出)。**两条的适用范围写清了**(这是本任务最容易写错的地方):`S5` **只约束已发布的向量路径**——探针 no-go、或 `T3-11` 按 V4 判定「C 不显著优于 B」而不发布时,`S5` 不参与判定;`S6` 则**无条件适用**,是 2.0.0 的硬门禁。同时把 §1.4 的两处措辞对齐到六条:导语由「下面这四条同时成立」改为「下面这些标准同时成立(`S1`–`S4` 是 v1.0 判据;`S5`/`S6` 是 v2.0.0 追加)」,稳定标识说明补上 `S5`/`S6`(首次编辑时误留了一条重复的稳定标识说明,已删)。`§6.8` 的强制点分别指向 `T3-11, T5-15`(`S5`:C 组判定 + 打包出 extra)与 `T3-10, T5-16`(`S6`:干净回退 + 默认安装零向量依赖) |
| **T5-21** | 已完成 | `$ grep -c "CODERAG_SEMANTIC_ALLOW_REMOTE" cordis.patch.yml README.md`
`cordis.patch.yml:3`
`README.md:3`
`$ grep -c -e "SECURITY WARNING" -e "OFF THIS MACHINE" cordis.patch.yml`
`2`
`$ grep -c -e "安全风险" -e "离开这台机器" README.md`
`2`
`$ grep -c cordis.patch.local.yml .gitignore`
`1`
`$ DSH_HOME=/tmp/dsh-v2 ./scripts/dsh plugin --profile v add . && DSH_HOME=/tmp/dsh-v2 ./scripts/dsh --profile v --dump-config`
`dump 退出码=0`,`env` 块含 **11 项**(`CODERAG_ROOT` + `CODERAG_MAX_TOKENS` + 9 个 `CODERAG_SEMANTIC_*`),全部以 `!!js` 表达式呈现
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ python3 scripts/test-verify-plan.py .`
`全部 19 个变异均被检出 ✅`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.73s` | `9b67ead`(patch / README / AGENTS / .gitignore / ADR-17 / PROJECT.md) | 需求:发布后用户要**方便**地配 API 与 key,且约束要放松、警告要落到配置与说明文件。**① 配置入口(`cordis.patch.yml`)**:`config.env` 新增 `CODERAG_MAX_TOKENS`(该名字含 `TOKEN`,**ambient 会被清洗,只能在这里显式列出**——这正是我上一轮实测发现的坑)与 **9 项关闭态的 `CODERAG_SEMANTIC_*`**(空串=未设),全部用 `!!js process.env.X ?? ''` 形式;文件头新增 "Where to configure" 说明**三种写法与两处覆盖位置**,并点明"**user patch 是整体替换、不是深合并**"。**② 约束放松**(三处,都留了理由):`RL-02` 从"key 只从运行时环境读"放宽为"**允许**仓库之外 DSH 本机层(`$DSH_HOME/profiles/*/cordis.patch.yml`、`$DSH_HOME/cordis.patch.yml`)里的**字面值**——因为那两个文件不入库也不随包分发",**仓库内仍只能用 `!!js` 表达式**;`S-05` 把**凭据**明确纳入日志禁令(结构化状态与异常一并适用);`S-01` 点明"把 URL+key 写进本机层是受支持路径,不算放松默认不联网"。**③ 安全警告**(`D-08` 要求随每一处配置出现):patch 里加 `SECURITY WARNING` 段(英文,与该文件通篇英文一致)与 README 云端小节的 ⚠️ 段(中文),两处都要点齐全——外发内容**含上下文前缀行因此含路径与符号名**、被过滤的密钥文件不会外发、按 token 计费且首次索引是全量支出、合规自负、key 不得入库/入日志/入状态、非 loopback 需 `ALLOW_REMOTE=1`、建议 https。**④ 顺带修掉上一轮发现的文档缺陷**:README 配置章节原来只说"要么 config.env、要么在 shell 里 export",现在明确列出**哪些变量 export 不生效**(`CODERAG_MAX_TOKENS`、API key)与**配置写在哪三处**,并给出整体替换的正确 YAML 示例。**⑤ 防误提交护栏**:`.gitignore` 新增 `cordis.patch.local.yml` / `*.local.yml`,并注释为什么(放宽后用户可能就地建含字面 key 的文件)。**⑥ 记录两处额外发现并固化**:`ADR-17` §4 新增"**空字符串 = 未设**(冻结)"——因为 patch 现在会下发空串,必须沿用 `config.py` 既有的 `raw is None or not raw.strip()` 语义,**禁止** `os.environ.get(name, default)`(否则 `MODEL=""` 会覆盖掉 `bge-m3` 默认值);该条同时写进 `T5-20` 的验收(含 `MODEL` 为空串仍用 `bge-m3` 的断言)。`D-08` 放宽为"**语言随文件**(中文文档用中文、英文交付件用英文),但要点一条不能少"。**⑦ 任务表相应去重**:`T5-15` 收窄为"只做 extra 与 `install.sh` 开关"(配置入口与 README 说明归 `T5-21`,不再两处重复定义);`T5-21` 依赖由 `T5-20` 改为 `T5-18`(它的验收是 grep + `--dump-config`,**不需要引擎**,因此可以也就在实现前落地);`T5-22` 依赖补 `T5-20`(它要测引擎的失败路径)。**⑧ 自查纠错两处**:我在重生成 §6.6 时把围栏偏移写错(`+7` 应为 `+8`),导致围栏行与注释行被并成一行、`C5` 立刻报不一致,已按整段重写修好;另外 `T5-21` 的验收原本要求 patch 里出现中文"安全风险",而该文件通篇英文注释,故改为按文件分别锚定(patch 用 `SECURITY WARNING`),并把这层宽容写进 `D-08` |
| **T5-18** | 已完成 | `$ test -f docs/adr/ADR-17-optional-cloud-embedding.md`
(退出码 0,文件存在)
`$ grep -c "^## " docs/adr/ADR-17-optional-cloud-embedding.md`
`8`(决策 / 为什么冻结 OpenAI 兼容协议 / 形态 / 配置与环境变量命名 / **安全风险声明** / 失败模式与结构化状态 / 发布范围与验收判据 / 与其它决策的关系;要求 ≥6)
`$ python3 scripts/verify-plan.py .`
` ✅ [B1] ADR: 17 条全部在矩阵里`
` ✅ [F4] 任务数 91 ≥ 下限 50`(原 86 + `T5-18`–`T5-22` 五个)
` ✅ [C-DEP] 91 个任务 / 107 条依赖边,引用全部有效`(原 100 条 + 新增 7 条)
` ✅ [C-CYCLE] 依赖图无环`
` ✅ [D3] 根 = T1-01;91/91 个任务可达根`
` ✅ [C5] §6.6 与任务表逐行一致(91 行)`
` ✅ [F4] 矩阵 51 行 ≥ 下限 45`(原 50 + `ADR-17` 行)
` ✅ [B4] 51 个矩阵键全部对应真实定义`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ python3 scripts/test-verify-plan.py .`
`全部 19 个变异均被检出 ✅`(校验脚本自身的变异自测仍全绿——说明改了任务表之后检查器没有失效)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.97s` | `8e3f320`(`ADR-17` + `ADR-16` 指针 + `AGENTS.md` + `PROJECT.md`) | 需求变更(用户指示,2026-09-23):向量后端除本地 Ollama 外,还要**可选**支持线上模型 API,且风险声明必须写进配置处 / README / 一切配置与说明书性质的文件。**按项目自己的规则办**(`AGENTS.md` §9、`R-03`):**不改写 ADR-16,另立 `ADR-17`** 记录"为什么推翻"——`ADR-16` 只加一条日期化指针,逐条声明**哪四处只对 `ollama` 继续有效**(§1.3 云端否决、§3.1 云端行、§6 `SEMANTIC_BACKEND_NOT_LOCAL`、§8.1 loopback 硬限制),其余条文(默认关闭/干净回退/extra/落点/RRF/V1–V4)**两条后端同等继承**,原文一字未改。**新冻结的形态**:`openai` 兼容 `/v1/embeddings`(一份实现覆盖多家,改 URL+model 即换供应商;继续用 stdlib `urllib`,**不引入任何厂商 SDK**);**双重开关**(`CODERAG_SEMANTIC=on` **且** `CODERAG_SEMANTIC_ALLOW_REMOTE=1` 才允许非 loopback)——防止"改一个 URL 就把代码发出去";key 只从环境读;新增失败码 `SEMANTIC_AUTH_MISSING` / `_AUTH_REJECTED` / `_RATE_LIMITED`;`S5`/`V1–V4` **按实际启用的后端独立满足**,不得互相背书。**约束改动四处 + 新增一条**:`S-01`(两条后端都不得默认启用 + 云端双重开关)、`S-02`(**唯一例外**:显式启用的云端后端,外发内容以清单为准,其余路径仍零外发)、`RL-02`(key 只从环境读,patch 里只许出现 `!!js` 表达式,日志/状态/异常也不得出现)、`RL-10`(覆盖两条后端,且云端也不需要额外 Python 依赖)、新增 **`D-08`**(风险声明必须随每一处配置出现,缺一处即文档缺陷,与 `D-04` 同级)。**`E-02` 补了一条已核实的实现事实**(读已安装的 `@deepseek-ai/dsh-mcp-client`:`{...scrubbedParentEnv(), ...extra}`,即**显式写进 `config.env` 的值在清洗之后合并、能存活**)——这既是 key 的投递路径,也解释了"为什么直接在 shell 里 export 不管用、而 patch 里放表达式是安全的"。**一处自查纠错**:我最初把 `D-08` 也加进了 §6.8 矩阵,`B4` 立刻报 `矩阵有 1 个键不对应真实定义:['D-08']`——因为校验器解析的是 §1.5 的 `D1`–`D5` 系列,而 `AGENTS.md` 用的是 `D-01`…`D-07` **点号系列**(本来就不进矩阵)。已在提交前撤掉该行,并把 `T5-18` 的期望结果改成只要求 `ADR-17` 行 |
| **T5-08** | 已完成 | `$ grep -c "v2.0" PROJECT.md`
`11`(要求 ≥3)
`$ grep -c "两段式安装" PROJECT.md`
`2`
`$ grep -n "^#### 1.6.4" PROJECT.md`
`203:#### 1.6.4 可选依赖:2.0.0 的 extra(**不进默认安装**)`
`$ grep -c "第二版怎么做成可选的" PROJECT.md`
`1`(§2.3 新增块的结句)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.53s` | `750627a`(§1.5/§1.6/§2.3) | 纯文档改动(`PROJECT.md`)。**先说明验收口径的局限**:`grep -c "v2.0"` 这个阈值**在我改动之前就已满足**(任务表 §6.5 与 §1.4 里的 `v2.0.0` 字样本身就会命中),所以它不是一个有效的代理指标——我另外用三条锚点 grep 证明"该写的内容真的写进去了"(见左列第 2–4 条)。**实际改动三处**:① **§1.5** 在 `D1`–`D5` 表后加"**2.0.0 的交付形态:两段式安装**"表——默认段(`pip install .` + `dsh plugin add .`,依赖只有四个,**与 1.0.0 步骤完全相同**)与可选段(extra `semantic` + 用户自装 Ollama,再设 `CODERAG_SEMANTIC=on`),并写明"两段都不做的人也永远不会碰到向量";② **§1.6 新增 `1.6.4`**:把 extra 名/内容/是否进 tarball/是否进 `install.sh` 默认路径/用户侧那一半逐项冻结(全部指向 `ADR-16` §3.1/§3.2/§7.1),并解释"为什么不把 numpy 放进 `dependencies`";③ **§2.3** 补"**v2.0.0 的范围**"块——写明决策门 `T3-07` 已裁定(R2 命中 → `ADR-14`;端到端已由纯词法达成 → 先暂缓 `ADR-15`、再重启为可选 `ADR-16`),并**明确本节三条证据至今未被推翻**、它们现在约束的是默认路径:"`不做`从不等于`永远不做`,而是`不默认做`",结句指向 `ADR-16`("本节回答为什么第一版不做,`ADR-16` 回答第二版怎么做成可选的")。**自查修正一处笔误**:初稿把 `ADR-16` 打成 `ADDER-16`,提交前用 `grep -c ADDER` 复核为 0
**复核(2026-09-23,用户要求修复)**:同一条命令重跑得 **12**(当时记 11),T5-09 那行也从 23 涨到 27——**这两条命令是自指的**:记录 `grep -c "<模式>"` 的**证据行本身就含该模式**,所以每多一行证据就 +1,历史读数再也复现不出来。判据(≥3)两次都成立,但**把一个会漂的数字当证据是错的**。可复现的度量(排除 §6.7 的证据行,因为证据行都以 `| **T5-` 开头):`grep -v '^| \*\*T5-' PROJECT.md | grep -c "v2.0"` → **10**(≥3,且此后不再随新增证据漂移)。教训已写进 `AGENTS.md` §5.3。 |
| **T5-09** | 已完成 | `$ grep -c "可选后端" PROJECT.md`
`23`(要求 ≥3)
`$ grep -n "向量索引的落点\|可选:2.0.0 的 extra\|第 2 阶段:可选后端路径" PROJECT.md`
`659:**向量索引的落点(2.0.0 的可选后端,**默认关闭**、默认不创建)**(ADR-16 §5)`
`746:**可选:2.0.0 的 extra semantic(**默认关闭**、默认不装)**(ADR-16 §3.2)`
`1002:**第 2 阶段:可选后端路径(ADR-16;**默认关闭**)**`
(三处都写明"默认关闭")
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.48s` | `b936dfc`(§3.6/§4.2/§5.3 等) | 纯文档改动(`PROJECT.md`)。**三处指定修改**:① **§3.6** 的"预留的向量表(M3 决策通过后才创建)"改为可选后端口径——**向量不进 `index.sqlite3`**,而是 `
**复核(2026-09-23,用户要求修复)**:同一条命令重跑得 **27**(当时记 23)——与 T5-08 同因:**证据行自指**(记录 `grep -c "可选后端"` 的那行本身含该字样)。可复现的度量:`grep -v '^| \*\*T5-' PROJECT.md | grep -c "可选后端"` → **23**(恰好回到当时的值,因此"当时 23"这个读数本身没错,错的是它不可复现;≥3 成立)。教训已写进 `AGENTS.md` §5.3。 |
| **T5-10** | 已完成 | `$ grep -c "C 组" EVAL.md`
`6`
`$ grep -c "天花板探针" EVAL.md`
`2`
`$ grep -c "0.025" EVAL.md`
`7`(三项各自 ≥1)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.38s` | `91ab96f`(`EVAL.md` §3.7) | 纯文档改动(`EVAL.md` 新增 §3.7)。**先核实 schema 再写命令,并在提交前把每条命令真跑一遍**——这是本任务唯一容易做假的地方(写出一堆看着合理但跑不通的"判定命令")。实测:L2 `report.json` 的真 schema 是 `cases[].{name,successes,trials,pass@k,pass^k}`(**没有** `results`/`metrics`);L1 `gate` 的真 schema 是 `metrics.{exact,natural,...}.success["5"]` + `regression_count`。据此写的三条命令都实跑过:V3 的配对符号检验用 `b-v1` vs `b-r5` 当替身 → `C better on 8, worse on 0, discordant n=8, one-sided p=0.0039` → `V3: PASS`;V1/V2 的两条 `python -c` 对 `eval/runs/l1-gate.json` → `exact@5 = 1.0 regressions = 0`、`natural@5 = 0.0`。**内容**:① §3.7.1 天花板探针(`T5-14`)——目标/语料/脚本落点(**一次性脚本不进 `src/`,因此不背测试与覆盖率义务**)/必须记录项/判定(`natural` 上限低于 `S5` 的 0.40 即 no-go),并写清探针(理论上限)与 C 组(真实链路:RRF、top-k、预算裁剪)的分工——**先看天花板,因为天花板不够就不必看落地**;② §3.7.2 C 组命令与**五条配对要求**(同 13 条用例 / 同工作区 / 同 trials=3 / 同 profile+patch / 逐条对比),并逐条写明违反后的后果;③ §3.7.3 把 **V1–V4 逐条落到命令**:V1/V2 走 L1 `gate`(`natural@5 ≥ 0.40` 且 > B 组的 0.000;`exact@5 == 1.0` 且 `regressions == 0`),V3 走配对符号检验(**单侧**、**α = 0.025**、要求报告显式声明"这是第二次检验"),V4 是**发布决定而非统计量**(V1 或 V3 未过即不发布;`S6` 仍须无条件成立) |
| **T5-11** | 已完成 | `$ grep -c "默认关闭" TESTING.md`
`6`
`$ grep -c "回退" TESTING.md`
`8`(各 ≥1)
`$ python3 scripts/verify-plan.py .`
` ✅ [E2] 必测清单 11 项:M1, M2, M3, M4, M5, M6, M7, M8, M9, M10, M11`
` ✅ [E3] 必测清单引用的 14 个任务全部存在`
` ✅ [E4] 必测清单覆盖 L3 端到端层`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.66s` | `4ba69b7`(`TESTING.md`) | 纯文档改动(`TESTING.md`)。**§2 必测清单新增 M11**「可选后端默认关闭且未配置时回退」,层列为 `L1+L2`,对应任务列引用 `T3-08, T3-09, T3-10, T3-11, T5-15`(`E3` 校验通过:14 个被引用任务全部存在);`E2` 由 10 项变 **11 项**(脚本的 `MIN_TEST_ITEMS = 10` 是下限,增项被接受)。**新增 §3.12 给出离线可测的方法**(它正是 M11 那格引用的落点):三组用例——① 默认关闭(`monkeypatch.delenv`,断言"与纯 BM25 逐条一致"即 `S6`,并断言 `sys.modules` 里没有 numpy);② 开关打开但后端不可用(**把 `CODERAG_SEMANTIC_URL` 指向 `http://127.0.0.1:1`**,于是不需要 Ollama、也不需要网络,就满足了 `T-02`);③ 非 loopback URL 必须被拒绝(安全拒绝)。另列四条"不许这样测"的反例,其中最关键的一条:**只断言 `status != "error"` 是太弱的**——回退的定义是"逐条与纯 BM25 一致",必须比结果而不是比状态字段;以及"只断言 `isError is False`"漏掉 `RL-06` 的另一半(不能返回空列表)。**同时把 §7 速查的"必须有的十类测试"改为"十一类"**并补 M11(否则速查与 §2 立刻不一致)。**一处诚实标注**:`SEMANTIC_*` code 尚未进 `ErrorCode`(`ADR-16` §6 写明是契约先行),所以第二、三组用例在 `T3-10` 之前会因 code 不存在而红——这是测试正确地指向未实现的契约,不是测试写错 |
| **T5-12** | 已完成 | `$ grep -c -e "已重启" -e "执行中" docs/adr/ADR-14-semantic-retrieval.md docs/adr/ADR-15-defer-semantic-retrieval.md`
`docs/adr/ADR-14-semantic-retrieval.md:1`
`docs/adr/ADR-15-defer-semantic-retrieval.md:3`(两份合计 **4** ≥ 2)
`$ grep -c "暂缓" docs/adr/ADR-15-defer-semantic-retrieval.md`
`7`(**历史理由仍在**)
`$ git diff --stat`
`ADR-14: 2 +-`、`ADR-15: 6 ++++++`(**7 insertions, 1 deletion**——唯一被删的是 ADR-14 的状态行本身,且替换后 `复核:2026-09-20 维持` 与指向 `ADR-15` 的引用都保留)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.38s` | `52f3fc3`(两份 ADR) | 纯文档改动(两份 ADR)。**`ADR-14` 只改状态行的"执行"字段**:`执行:**暂缓**` → `执行状态(2026-09-23):**已重启**为可选后端(2.0.0)——形态冻结在 ADR-16;此前的暂缓见 ADR-15`,其余(`已决定(T3-07)`/`复核 2026-09-20 维持`/`裁决日期`)一字未动。**`ADR-15` 是纯新增 6 行**:① 状态行下加"执行状态(2026-09-23):暂缓**已结束**、`T3-08`–`T3-11` **已重启**",并**明写快照性质不变**(§2 暂缓理由 / §3 重启条件 / §6 限制都按原文保留);② §1 加"后续更新"——四条里第 1 条的暂缓已结束、第 2 条的形态要求被 ADR-16 冻结成可验收条文、第 3/4 条不变(**"重启的是执行,不是重开决策门"**);③ §3 加"后续更新"——四条重启条件**逐条兑现**(形态 / `T5-14` 探针先行 / V1–V4 继承且 α=0.025 / `T3-11` 验收命令换成自建 runner),并附上 `T3-11` 的完整命令;④ §5 后果那一条加一行"这三项**已重启**——本行只描述 2026-09-20 的状态"。**全部保留历史**:`暂缓` 在 ADR-15 里仍有 **7** 处命中,§2 的"端到端目标已由纯词法达成"等原始理由未删改;`git diff` 显示 7 增 1 删,删的那一行是 ADR-14 状态行自身(已按上句替换,无信息丢失) |
| **T5-13** | 已完成 | `$ grep -c "可选后端" README.md docs/architecture.md`
`README.md:3`
`docs/architecture.md:4`(两份合计 **7** ≥ 2)
`$ sed -n '1,8p' README.md \| grep -c "机器权限"`
`1`(`D-04`:安全声明仍在第一屏)
`$ sed -n '/^## 可选语义后端/,/^## 工具/p' README.md \| grep -c "1\.0\.0\|v1\.0\|2\.0\.0\|v2\.0"`
`0`(**新增段落不含任何版本号**——版本号属 `T5-17`)
`$ tail -c 1 README.md \| xxd`→`0a`、`docs/architecture.md` 同(`D-07`:末尾恰好一个换行)
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.31s` | `56d0545`(`README.md` + `docs/architecture.md`) | 纯文档改动(两份)。**README 新增 `## 可选语义后端(默认关闭)`**(放在「配置」与「工具」之间):它解决什么问题(`natural` 桶 0.000、100% 归因零词法重叠)、**两段式装法**(`pip install -e ".[semantic]"`/`CODERAG_WITH_SEMANTIC=1 bash scripts/install.sh` + 用户自装 `ollama pull bge-m3`)、**开关表**(`CODERAG_SEMANTIC` 未设即关闭、`_URL` 只允许本机、`_MODEL`/`_TIMEOUT`/`_BATCH`/`_MAX_CHUNKS`)、失败行为(干净回退、带 `SEMANTIC_*` code、不 `isError`、不空列表),以及**"限制如何变化"对照表**(自然语言 0.000 → 目标 ≥0.40 但**明确写"是否达标要看探针与 C 组数据,本节不预先承诺"**;`S1`/`S2` 与端到端**不变**;依赖多一个 numpy;默认路径行为是硬门禁 `S6`)。**`## 已知限制` 第一条改为"默认安装下,纯中文自然语言检索不可用"**(原写"基本不可用(已知且已决定暂缓)"),并把 `ADR-15` 的"暂缓"与 `ADR-16` 的"重启为可选后端"两句都保留、指向新小节。**`docs/architecture.md` 三处**:① 模块表 **`searcher` 行补可选后端路径**(向量召回 + RRF,并写明"关闭时不得 import numpy");② **新增 `embed` 模块行**(`embed.py`:调 Ollama 生成/缓存 embedding、读写 `.coderag/vectors/`;不排序不融合、不参与 BM25 路径、未启用时不得成为导入或启动的阻塞点);③ 依赖方向图加 `searcher ──► embed`(**仅在可选后端启用时**,延迟导入);④ §11 非目标的"v1.0.0 不含向量检索"改为"**默认路径不含向量检索**"并补 `ADR-16` 的四条形态要点——**同时把这条里的版本号去掉**,于是 `architecture.md` 只剩第 8 行"实现版本"一处版本号(那正是 `T5-17` 要改的),`T5-17` 不必再碰这一条 |
| **T5-19** | 已完成 | `$ grep -c -e "ALLOW_REMOTE" -e "按后端" EVAL.md TESTING.md`
`EVAL.md:7`
`TESTING.md:4`(两份都 ≥1;再分模式核对:`ALLOW_REMOTE` EVAL 4 / TESTING 3,`按后端` EVAL 3 / TESTING 2)
`$ python3 scripts/verify-plan.py .`
` ✅ [E1] TESTING.md 读取到 975 行`
` ✅ [E2] 必测清单 11 项:M1, M2, M3, M4, M5, M6, M7, M8, M9, M10, M11`
` ✅ [E3] 必测清单引用的 16 个任务全部存在`
` ✅ [E4] 必测清单覆盖 L3 端到端层`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.433`
`S2 MRR = 0.313`
`S4 token_median = 2492`
`S3 E2E delta = +59.0pp`
`回归条数 = L1 0(逐 query) + L2 0(用例级) = 0`
`══ 门禁:PASS ══`(退出码 0)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 2.36s` | `e1ebef6`(`EVAL.md` + `TESTING.md` + backlog) | 纯文档改动,无代码变更。**`EVAL.md` §3.7 新增两小节**:① §3.7.4「判据**按后端独立判定**」——`S5`/`V1–V4` 由实际启用的那个后端独立满足,**本地探针不得给云端背书**(`ADR-17` §1.6);给出本地/云端两条 C 组命令(云端带 `ALLOW_REMOTE=1` 双重开关、key 只从运行时环境读、报告必须分 `c-ollama`/`c-cloud` 两份),并写明没有 key 就不跑、如实标注"已实现未验证"。② §3.7.5「云端后端的**失败注入**(离线优先)」——用 **loopback 桩 + 空/假 key** 注入无 key / 401·403 / 429 / 超时四种失败,逐项给出期望 code(`SEMANTIC_AUTH_MISSING`/`_AUTH_REJECTED`/`_RATE_LIMITED`/`_EMBED_FAILED`);四种失败的共同断言四条(干净回退、结构化状态不 `isError` 不空列表、**假 key 哨兵串在 stdout/stderr/JSON/异常里零命中**、未启用时零连接)。**`TESTING.md` 三处**:§2 的 `M11` 格扩到**本地+云端**(新增 `ALLOW_REMOTE`、按后端独立成立、四种失败、key 禁入日志,任务列补 `T5-20`/`T5-22`);§3.12 新增**第四组**云端四种失败的参数化用例骨架(loopback 桩、假 key 哨兵、离线),并补"空串=未设"与"双重开关的拒绝路径"两条额外要求;§7 速查改为"本地+云端,离线可测"。**离线约束仍成立**:桩只监听 `127.0.0.1`,四条注入全部不联网、不需要真 key(`T-02`)。**一处越界发现记入 backlog**(`AGENTS.md` §9,未顺手修):`ADR-17` §5 落点表第 3 项(`config.py` 的 `SemanticConfig` 字段说明)与 §6 的 code 登记动作被指派给 `T5-19`,但两者此刻都不存在、属被 `T5-14` 阻塞的 `T3-08`–`T3-11`,且 `T5-19` 的产出文件列只有两份文档——落点表任务号疑似应为 `T5-20`/`T3-08`,已请项目所有者裁决(**2026-09-24 已裁决并处置**:`T3-08` 产出文件扩容、`ADR-17` §5/§6 归属改为 `T3-08`,见 `docs/backlog.md` 该条与 `da30e0b` 之后的范围修正提交) |
| **T5-14** | 已完成 | `$ test -f docs/m5-vector-probe.md && echo "文件存在 ✅"`
`文件存在 ✅`
`$ grep -c -e natural -e crossfile -e "S@5" docs/m5-vector-probe.md`
`31`(四项指标(S@1/S@3/S@5/MRR)逐桶可查;另含后端 `bge-m3`、维度 `1024`、耗时 `168.5 min`)
**探针结论:`natural` 桶 `S@5` 上限 = 0.429(3/7)≥ `S5` 的 0.40 → GO(边际)**
分层(生产排序档位下):`overall 0.700 | exact 0.917 | crossfile 0.636 | natural 0.429`;对照 B 组(纯 BM25):`crossfile 0.091 → 0.636(+54.5pp)`、`natural 0.000 → 0.429(+42.9pp)`、`exact 1.000 → 0.917(-8.3pp,故只能 RRF 补齐、不能替换)`
**探针自身的对照**:真实 `3/7` | 打乱「向量行↔路径」对应 `0/7` | 随机单位向量当 query `0/7`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.433 (exact 1.000 / crossfile 0.091 / natural 0.000)`
`S2 MRR = 0.313`
`S4 token_median = 2492.000`
`回归条数 = 0(改善 0)| 门禁:PASS`
`S3 E2E delta = +59.0pp` | `══ 门禁:PASS ══`(退出码 0)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`445 passed, 2 skipped in 3.16s` | `663d4a3`(`docs/m5-vector-probe.md`) | 探针脚本 `/tmp/m5-vector-probe.py`(**不进 `src/`/`scripts/`**,无测试与覆盖率义务;命令记在报告 §7)。**方法**:Ollama `bge-m3`(dim 1024)对**全量 63046 chunk + 30 条 query** 做 embedding,归一化后全量暴力余弦取 top-5,按 `EVAL.md` §2.5 的命中判据算分桶 `S@1/S@3/S@5`、`MRR`、Wilson 区间。冷跑 **168.5 min**(M4,Ollama 串行;实测 2/4 并发不提升吞吐),embedding 按 2048/分片缓存在 `/tmp` 可续跑。**⚠️ 一处自查纠错(决定了结论方向,必须记录)**:第一版探针只按纯余弦排序,得 `natural 0.000 → NO-GO`;但生产检索的第一层排序是「**非测试路径优先**」(`searcher.TEST_PATH_TIER_SQL`,`T3-14` 放进 SQL `ORDER BY` 第一层),而本语料 **38489/63046(61%)的 chunk 来自测试文件**——不继承该档位时 `tests/*.spec.ts` 会压掉真实实现(L-026 的正确文件在纯余弦下不进 top-5,它自己的 spec 是 top-1)。向量路径必须继承生产档位,否则既不是生产口径、`exact` 也会直接回退。套上该档位后重算(判据与生产**逐字相同**):`natural 0.429`、`overall 0.700`、`crossfile 0.636`、`exact 0.917`。报告里**两个读数都保留**并写明哪个是生产口径。**零假设对照**(`natural`):真实 3/7、打乱「向量行↔路径」0/7、随机 query 向量 0/7——证明命中来自真实语义对齐,不是排序档位的伪影。**结论只到「值不值得实施」**:`natural` 仅 7 条,**再少一条就跌破 0.40**(Wilson [0.158, 0.750]),发布与否仍由 C 组 `V1`/`V3`(α=0.025)决定。**未做**:云端后端**没有**被本探针背书(`ADR-17` §1.6/§7 要求各后端自行重跑)。**裁决(2026-09-24,项目所有者)**:接受本 GO。「向量路径继承非测试优先档位」这一实现前提已冻结进 `ADR-16` 的「后续更新(2026-09-24)」(`c2666a3`),`T3-09`/`T3-10` 必须兑现 |
| **T3-08** | 已完成 | `$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -k "embed" -q`
`................ [100%]`
(**证据保真修正**:任务行的 `-q` 与 `pyproject.toml` 的 `addopts = "-q …"` 叠加成 `-qq`,汇总行被抑制,所以上面这条命令**不会**打印计数。下面去掉多余的 `-q` 才得到数字——这才是本节最初记的 `16 passed` 的真实来源)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -k "embed"`
`16 passed, 459 deselected in 4.39s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`473 passed, 2 skipped in 6.35s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m ruff check src tests`
`All checks passed!`
`$ /opt/anaconda3/envs/forBSH/bin/python -m mypy --strict src/`
`Success: no issues found in 25 source files`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.433 (exact 1.000 / crossfile 0.091 / natural 0.000)`
`S2 MRR = 0.313`
`S4 token_median = 2492.000`
`回归条数 = 0(改善 0)| 门禁:PASS`
`S3 E2E delta = +59.0pp` | `══ 门禁:PASS ══`(退出码 0) | `4fb7349`(`embed.py` + `config.py` + `types.py` + 三个测试文件) | **范围**:按 2026-09-24 的裁决(`246bb16`)执行——产出文件由只有 `embed.py` 扩为 `embed.py` + `config.py` + `types.py` + `tests/test_embed.py` + `tests/test_config.py` + `tests/test_types.py`。**`types.py`**:登记 `ADR-16` §6 的 7 个 + `ADR-17` §6 的 3 个 `SEMANTIC_*` code,`ErrorCode` 10 → **20**,`tests/test_types.py` 增一条「与冻结集合逐名相等」的断言。**`config.py`**:新增 `SemanticConfig` 与 `load_semantic_config`,字段名/默认值/命名逐条对齐 `ADR-16` §4 与 `ADR-17` §4;**空串(含纯空白)= 未设**,一律走 `_read_optional_str` / `_read_positive_int`(不用 `os.environ.get(name, default)`),所以 patch 下发的 `MODEL=""` 不会抹掉 `bge-m3` 默认值;**只有精确的 `on` 才启用**(`1`/`true`/`yes`/`ON` 一律关闭并在 `switch_value` 里保留原值供状态说明,`switch_invalid` 可查);`ALLOW_REMOTE` 只认精确的 `1`;**后端关闭时不做任何校验**(默认安装绝不被它阻塞),云端后端启用时缺 URL/MODEL 直接 `ConfigError`(不猜默认值)。`SemanticConfig` 的 docstring 按 `D-08` §5 第 3 项带上**英文的完整云端风险声明**(外发含上下文前缀行→路径与符号名、被三层过滤拦下的密钥文件不外发、按 token 计费且首次索引是全量、合规自负、key 只从环境读且禁入仓库/日志/状态/异常、非 loopback 需 `ALLOW_REMOTE=1`、建议 https)。**`embed.py`**:`ollama` 的 `/api/embed`,stdlib `urllib`(**不 import numpy、不 import httpx**);批量大小取 `config.batch`、超时取 `config.timeout_s`(不硬编码,`RL-07`);**重试上限 2**(总尝试 3 次,`ADR-16` §6),每次失败用 `log_event` 记 `url`/`model`/`attempt`/异常类型(**不含 key、不含代码内容**,`S-05`);`EmbeddingCache` 以 `(model, sha256(text))` 为键(键是摘要、不存第二份文本),跨调用复用;响应条数与请求不符即 `SEMANTIC_EMBED_FAILED`(不静默截断,`RL-08`);错误一律是携带冻结 code 的 `SemanticError`,由上层转结构化状态并继续 BM25(`RL-06`/`RL-09`);本地后端非 loopback 在发请求**之前**就拒绝(`SEMANTIC_BACKEND_NOT_LOCAL`,`ADR-16` §8.1);`openai` 目前返回 `SEMANTIC_BACKEND_UNSUPPORTED`——实现属 `T5-20`。**模块导入零副作用**(不联网、不需要 numpy)。**测试(全离线,`T-02`)**:`tests/test_embed.py` 16 例——导入安全(子进程断言 `numpy not in sys.modules`)、关闭时不发请求、同文本两次调用只打一次后端且结果相同(缓存生效)、批量按 `config.batch` 切分 `[2,2,1]`、单次调用内重复文本只 embed 一次且顺序保持、非 loopback 与未知后端在请求前被拒、重试恰好 `RETRY_LIMIT+1` 次、响应条数不符、**假 key 哨兵串不出现在异常文本与 hint 中**(`S-05`)、真实 urllib 打 loopback 桩的收发报文、超时映射、端口关闭映射;`tests/test_config.py` 增 11 例覆盖默认值/空串=未设/只有 `on` 启用/数值覆盖/非法数值/`ALLOW_REMOTE`/云端必填与关闭时不校验。**自查纠错一处**:`embed_texts` 初版 73 行,超过 `C-04` 的 50 行上限,已拆成 `_fill_from_cache` / `_embed_pending` / `_require_complete`(现 0 个函数 >50 行)。**未做(属后续任务)**:向量落盘与暴力余弦(`T3-09`,含 `SEMANTIC_INDEX_TOO_LARGE` 的 `_MAX_CHUNKS` 闸门)、RRF 融合与接进 `searcher` 的干净回退(`T3-10`)、云端 `openai` 请求(`T5-20`)、C 组与 `V1`–`V4` 判定(`T3-11`)。**默认路径零回归**:`S1`/`S2`/`S4` 与接入前逐字相同 |
| **T3-09** | 已完成 | `$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -k "vector_search" -q`
`.......... [100%]`
(同 `T3-08` 的保真说明:`-q` 与 `addopts` 的 `-q` 叠加成 `-qq`,汇总被抑制;计数用下面这条)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -k "vector_search"`
`10 passed, 486 deselected in 0.47s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`494 passed, 2 skipped in 6.52s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m ruff check src tests`
`All checks passed!`
`$ /opt/anaconda3/envs/forBSH/bin/python -m mypy --strict src/`
`Success: no issues found in 26 source files`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.433 (exact 1.000 / crossfile 0.091 / natural 0.000)`
`S2 MRR = 0.313`
`S4 token_median = 2492.000`
`回归条数 = 0(改善 0)| 门禁:PASS`
`S3 E2E delta = +59.0pp` | `══ 门禁:PASS ══`(退出码 0) | `f75419b`(`vectors.py` + `searcher.py` + 两个测试文件) | **范围**:按 2026-09-24 裁决(`9413c9f`)新建 `vectors.py` 承载落盘与 manifest,`searcher.py` 只加余弦召回。**环境前提(已获准)**:`numpy` 装进 forBSH(**2.2.6**,满足 `ADR-16` §3.2 的 `numpy>=1.26`),因为 `T5-15` 的 extra 排在 `T3-10` 之后、不装就无法跑 `T3-09` 的验收;默认路径不受影响(见下)。**`vectors.py`**:落点 `
`................ [100%]`
(同前:`-q` 与 `addopts` 的 `-q` 叠加成 `-qq`,汇总被抑制;计数见下)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -k "rrf"`
`16 passed, 498 deselected in 0.41s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`512 passed, 2 skipped in 6.66s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m ruff check src tests`
`All checks passed!`
`$ /opt/anaconda3/envs/forBSH/bin/python -m mypy --strict src/`
`Success: no issues found in 26 source files`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.433 (exact 1.000 / crossfile 0.091 / natural 0.000)`
`S2 MRR = 0.313`
`S4 token_median = 2492.000`
`回归条数 = 0(改善 0)| 门禁:PASS`
`S3 E2E delta = +59.0pp` | `══ 门禁:PASS ══`(退出码 0) | `6922975`(`searcher.py` + `types.py` + `render.py` + 两个测试文件) | **范围**:按 2026-09-24 裁决(`7a02f6e`)扩为 4 个源文件——回退原因必须进入**新增的结构化字段**并对模型可见(`ADR-16` §2/§6),所以带上 `types.py` 与 `render.py`。**RRF**:`RRF_K = 60`(`PROJECT.md` §5.3 冻结;docstring 明写**不能照抄 Qdrant 的 2**),`reciprocal_rank_fusion()` 只吃**名次**(`1/(k+rank)` 求和),因此 BM25 的无界负分与余弦的 `[-1,1]` 从不发生量纲接触;`fuse_candidates()` 先做并集去重(键 = `(path, seq)`),再按**冻结的「非测试优先」档位** → RRF 降序 → `(path, start_line)` 确定性兜底排序,取 `limit` 后**回到源码顺序**(`ADR-05` 不变)。`is_test_path()` 是 `TEST_PATH_TIER_SQL` 的 Python 孪生,配一条**同义性测试**:对 12 个路径逐条比对 Python 判据与真实 SQLite `LIKE` 谓词,两者必须选出**完全相同**的集合。**门控只看开关**(`ADR-16` §2):`search()` 新增 keyword-only 的 `semantic`(默认从环境读),只有 `enabled` 才走可选路径;后端可用性**只影响状态不影响回退**。**干净回退**(冻结含义三条逐条兑现):`_apply_semantic()` 捕获 `SemanticError` 后**原样返回 BM25 候选**(条数/路径/行号/顺序不变)、`status` 仍是 `ready`、**不是空列表**(`RL-06`),失败信息只出现在新增字段里;启用但不可用 / 未知后端 / 索引缺失 / 环境非法(`ConfigError`:如启用 `openai` 却缺 URL)都映射成 `SEMANTIC_*` notice。**新增字段与渲染**:`SearchResult.semantic: SemanticNotice \| None`(`types.py`),`render_search_result()` 仅在**非 None** 时多输出**一行**`semantic: BM25 only (CODE) —
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest tests/test_index_vectors.py`
`6 passed in 1.78s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`518 passed, 2 skipped in 8.25s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m ruff check src tests`
`All checks passed!`
`$ /opt/anaconda3/envs/forBSH/bin/python -m mypy --strict src/`
`Success: no issues found in 26 source files`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.433 (exact 1.000 / crossfile 0.091 / natural 0.000)`
`S2 MRR = 0.313`
`S4 token_median = 2492.000`
`回归条数 = 0(改善 0)| 门禁:PASS`
`S3 E2E delta = +59.0pp` | `══ 门禁:PASS ══`(退出码 0) | `9da6ce5`(接线), `bad5777`(增量复用), `bb93ac7`(进度日志), `fd49168`(档位修复), `60919b1`(评测报告) , `c5d5848`(扩桶到 43 条 / `m3-b2`), `c3d2892`(扩桶后复测) , `187767f`(目标核对与 4 条修正 / `m3-b3`) | **缺口(本任务开工时发现)**:`vectors.build_index()` 有实现有测试,但**生产路径从未调用它**——`index_sync` / `code_index` 都不碰向量,于是 `CODERAG_SEMANTIC=on` 时只会走到 `SEMANTIC_INDEX_MISSING` 干净回退,**向量功能永远不会生效**。按 2026-09-24 裁决(`e630f2c`)把接线归入本任务。**接线实现**:`index_sync` 在 BM25 索引写完并 `_mark_ready` 之后,经由新的 `_finish_index_run()` 调 `_maybe_build_vector_index()`;**只有 `CODERAG_SEMANTIC` 为 `on` 才建**(关闭 = 零向量目录、零网络),chunk 列表按 `id` 升序取自索引库(与 `ADR-16` §5 的行序冻结一致)。**可选路径绝不能拖垮默认路径**(`RL-10`):`SemanticError` 记 `warning`(带冻结 code)、`OSError` 记 `error`,两者都**只记日志并返回**,BM25 索引已经 ready;**被取消的 run 既不标 ready 也不建向量**;取消信号经 `_cancellable_transport()` 注入,取消时抛 `SemanticError`(不在重试捕获列表里,因此立即中止而不是重试 3 次)。**测试(全离线,`T-02`)**:`tests/test_index_vectors.py` 6 例——关闭态不产生向量目录;开启态(loopback 桩)产出 manifest 且 `chunk_ids` 与库内**升序完全一致**、`dim`/`model` 正确;后端不可达(`127.0.0.1:1`)时 BM25 索引照常 ready 且 `search` 仍返回命中并带 `SEMANTIC_EMBED_FAILED`;构建抛错不使 `index_sync` 失败;取消态不建向量;逐 chunk 内容哈希与 chunk 数一一对应。**子步骤 1.5/2:增量复用未变向量(已完成,`bad5777`)**:`build_index()` 先按 `(chunk_id, content_hash)` 从盘上旧索引复用未变行,只对新增/改动/换模型的 chunk 调 embedding;**整个仓库没变时一次 embedding 调用都不发**。复用键含 `chunk_id`——改动的文件会被删行重插、拿到新 id,因此该文件的 chunk 整体重算(正确且简单),未改动文件零成本。旧索引缺失/模型不符/manifest 损坏时自动退回全量重建(原因记 `semantic_index_no_reuse`),并记 `semantic_index_built`(带 `reused`/`embedded` 计数,便于观测)。证据:`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest tests/test_vectors.py tests/test_index_vectors.py`
`25 passed in 2.35s`(新增 7 例:首次全量、只重算改动的那一条、**无改动零调用**(注入爆炸 transport)、换模型全量、manifest 损坏全量、删 chunk 后其余仍复用、空工作区显式拒绝;另有一条端到端:改一个文件后第二次 embedding 条数**严格少于**第一次)。**效果**:第二次索引的成本从「全量 ≈168 min」降到「改动量 ÷ 6–10 chunk/s」。**子步骤 2/2:真实评测(已完成)**——`$ CODERAG_SEMANTIC=on … caffeinate -i python -c "… index_sync('/tmp/dsh-coderag-t3-03-corpus')"`
`{"event": "semantic_index_built", "model": "bge-m3", "chunks": 63046, "reused": 0, "embedded": 63046}`
`{"event": "semantic_index_ready", "model": "bge-m3", "dim": 1024, "chunks": 63046, "duration_ms": 7659505.6}`(冷跑 **127.7 min**;落盘 `embeddings.npy` 258 MB + `manifest.json` 5.2 MB)
`$ CODERAG_SEMANTIC=on … python -m dsh_coderag.eval gate --tasks eval/tasks.jsonl --root … --baseline eval/runs/l1-baseline.json …`
`S1 Success@5 = 0.567 (exact 0.917 / crossfile 0.455 / natural 0.143)`
`S2 MRR = 0.228`
`S4 token_median = 1974.500`
`回归条数 = 1(改善 5)| 门禁:FAIL`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`529 passed, 2 skipped in 9.56s`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
**判定(`docs/eval-report-m3c.md`)**:**`V1` 未达**(`natural@5 = 0.143 < 0.40`;> B 的 0.000 但不足 0.40)、**`V2` 未达**(`exact@5 = 0.917 ≠ 1.000`,且未豁免回归 1 条 `L-015`)→ 按 `ADR-14` §10.4 的 **`V4`:向量路径不发布**。**`V3` 未跑**:`ADR-14` §10.4 是「`V1` **或** `V3` 未过即不发布」的**析取**,`V1` 已未达,`V3` 无法改变结论;L2 需模型 key,且用户事前已批准「V1/V2 不过则不跑 L2」。**如实标注 `V3` 未测量**,本报告不声称「C 与 B 无显著差异」。**本任务发现并修复一个真 bug(`fd49168`)**:冻结的「非测试优先」档位原先只在**融合阶段**生效,向量腿仍是「先按余弦取 top-5 再套档位」;本语料 61% 的 chunk 是测试文件,正确文件**从未进入候选并集**,`natural` 一度为 **0.000**。改为在 `cosine_top_k()` 的 **top-k 截断之前**生效(`TEST_PATH_TIER_SQL` 是 Python 侧档位的唯一来源)后:`natural 0.000 → 0.143`、`crossfile 0.182 → 0.455`。**修复只把分数抬到仍不达标的水平,不改变 `V4` 判定**。同一次修复还处理了 macOS Accelerate BLAS 的 FP 误报(实测 `m @ q` 全有限、与 float64 最大差 `1.4e-8`、top-20 一致),现以 `errstate` 抑制并**显式校验有限性**。**为什么融合后远低于探针上限(0.143 vs 0.429)**:向量腿本身正确(`L-009` 单路返回目标文件第 3 名),但 **BM25 对中文自然语言查询总是返回一整页非空却无关的 `locales.ts`**,等权 RRF 下 `BM25 #1` 的 `1/61` 压过`向量 #3` 的 `1/63`,目标被挤出 top-5——这是 RRF 在该语料上的**固有行为**,不是实现 bug。`T5-14` 的 GO 是**必要非充分条件**。**默认路径零回归**:B 组(关闭态)`S1`/`S2`/`S4` 仍为 0.433 / 0.313 / 2492,既有 M9 快照全绿。**后续(2026-09-25):扩桶复测,`V4` 结论不变且证据更强**——`V1` 是**桶级**判据,7 条时单条 = 14.3pp,故把 `natural` 由 7 扩到 **20**(新增 `L-031`…`L-043`,`golden_version` `m3-b1 → m3-b2`,`RATIO` 12:11:7 → 12:11:20,`EVAL.md` §2.3/§2.6 同步)。**这 13 条是在融合机制设计完成之后加入、且逐条结果未被查看的 → 对那套机制构成 holdout**。扩桶后 B 基线(43 条):`overall 13/43 = 0.302`、`exact 12/12`、`crossfile 1/11`、**`natural 0/20`**(13 条新题 BM25 全 miss,确认零词法重叠)。**只读原型**(`/tmp/m5-fusion-probe.py`,不进仓库;`S0` 逐字复现生产)实测五种融合策略:`S0 现状 = 0.917 / 0.455 / 0.150`(回归 1)、`S1 档位门控 = 1.000 / 0.455 / 0.250`、`S2 +数据档位`、`S3 +按分数裁剪 = 1.000 / 0.636 / 0.250`、**`S4 = 三者合并 = 1.000 / 0.636 / 0.300`(0 回归,MRR 0.170→0.367)**。**判定:`S4` 的 `natural = 6/20 = 0.300 < 0.40` → `V1` 仍未达 → `V4` 不发布**;`V2` 只在 `S4` 下达标,**现状(`S0`)下未达标**。**关键发现:`3/7 = 0.429` 的那次「贴线通过」是小样本假象**,20 条把它证伪——这正是 `EVAL.md` §2.4 Step 6 ③ 要求 holdout 的理由;`S4` 的 6 条命中里有 3 条来自新题(`L-032`/`L-034`/`L-036`),说明机制**有**泛化能力但**幅度不够**。**后续需裁决(报告 §9/§10)**:向量不发布后 `T5-15`/`T5-16`/`T5-17` 的「可选 extra」前提不成立;云端(`T5-20`)要过 `V1`/`V2` 才能发布而本机无 key;另有一条 backlog:`README.md`/`PROJECT.md` 的实测数字仍停留在 `m3-b1`(30 条)口径,需在 `T5-13`/`T5-17` 里改标为 `m3-b2`。**目标核对(2026-09-25,用户要求)**:13 条新题逐个到真实仓库 `/Users/vermi/projects/dsh` 核对——全部 `expect_paths` 存在且与 `/tmp` 语料副本 **sha256 一致**;逐条打开文件取证后发现 **4 条不合格**并已修正(`L-037`/`L-038`/`L-041` 把**包入口当成了实现**:持久化在 `schedule/src/persistence.ts`+`projection.ts`、签名校验在 `webhook-github/src/handler.ts`、输出上限在 `terminal-bash/src/session.ts`;`L-040` 题面写「写之前校验」而实现是**读取时校验**,已改写题面),其余 9 条确认无误;`golden_version` `m3-b2 → m3-b3`、基线重建(仍 `13/43`)、`S4` 仍 `natural 6/20 = 0.300`——**分数不变,消除的是潜在假阴性**。教训已固化为 `EVAL.md` §2.4 Step 6 的**第 ④ 道人工保险**(目标必须是实现该行为的文件,包入口常常只是 wiring) |
| **T5-17** | 已完成 | `$ python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])"`
`2.0.0`
`$ node -e "console.log(require('./package.json').version)"`
`2.0.0`
`$ grep -n '__version__ =' src/dsh_coderag/__init__.py`
`44:__version__ = "2.0.0"`
`$ grep -n '^## \[2\.0\.0\]' CHANGELOG.md`
`8:## [2.0.0] - 2026-09-25`
`$ grep -n 'dsh-coderag 2\.0\.0\|当前版本' README.md`
`90:> **当前版本 `2.0.0` 同样只在 GitHub 上以 tag / release 发布**(`v2.0.0`),PyPI 与 npm 上没有任何版本。`
`101:dsh-coderag --version # 期望输出:dsh-coderag 2.0.0`
`$ grep -n '实现版本' docs/architecture.md`
`8:> 实现版本:`2.0.0`|Python `>=3.10,<3.13`|验证环境 macOS + DSH `0.1.5-rc.1`。`
`$ grep -rn '1\.0\.0' CHANGELOG.md README.md docs/architecture.md`
`CHANGELOG.md:12:**默认安装与 `1.0.0` 逐条一致**(成功标准 `S6`:30 条 query 逐条 diff 回归条数 = 0、`exact` 桶保持 `1.000`),`
`CHANGELOG.md:48:- 版本号 `1.0.0` → `2.0.0`(`pyproject.toml`、`package.json`、`src/dsh_coderag/__init__.py`)。`
`CHANGELOG.md:60:## [1.0.0] - 2026-09-23`
`CHANGELOG.md:62:首个版本。仓库内 `pyproject.toml` 与 `package.json` 均为 `1.0.0`;**尚未发布到 PyPI 与 npm**。`
(**历史证据里的 `1.0.0` 全部保留**:`[1.0.0]` 条目原文未动,其余 3 处是本次新增文案里对 1.0.0 基线的引用;README / `docs/architecture.md` 已无 `1.0.0`)
`$ python3 -c "import tomllib; d=tomllib.load(open('pyproject.toml','rb')); p=d['project']; deps=' '.join(p['dependencies']).lower(); print('dependencies =', p['dependencies']); print('optional-dependencies =', sorted(p.get('optional-dependencies', {}))); [print(f'{b}: {\"FOUND\" if b in deps else \"absent\"}') for b in ('numpy','httpx','faiss','chroma','lancedb','sentence-transformers')]"`
`dependencies = ['mcp>=1.28,<2', 'tree-sitter>=0.25.2,<0.26', 'tree-sitter-language-pack>=0.13,<0.14', 'pathspec>=0.12']`
`optional-dependencies = ['dev']`
`numpy: absent`
`httpx: absent`
`faiss: absent`
`chroma: absent`
`lancedb: absent`
`sentence-transformers: absent`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest`
`529 passed, 2 skipped in 9.63s`
`$ /opt/anaconda3/envs/forBSH/bin/python -m ruff check src tests`
`All checks passed!`
`$ /opt/anaconda3/envs/forBSH/bin/python -m mypy --strict src/`
`Success: no issues found in 26 source files`
`$ CODERAG_GATE_PYTHON=/opt/anaconda3/envs/forBSH/bin/python bash scripts/eval-gate.sh`
`S1 Success@5 = 0.302 (exact 1.000 / crossfile 0.091 / natural 0.000)`
`S2 MRR = 0.219`
`S4 token_median = 2876.000`
`回归条数 = L1 0(逐 query) + L2 0(用例级) = 0`
`S3 E2E delta = +59.0pp` | `══ 门禁:PASS ══`(退出码 0) | `5b53cda`(`pyproject.toml` / `package.json` / `src/dsh_coderag/__init__.py` / `CHANGELOG.md` / `README.md` / `docs/architecture.md`) | **范围**:六个产出文件全部落地,**无代码逻辑改动**——`src/dsh_coderag/__init__.py` 只改 `__version__` 一行。**版本号 `1.0.0` → `2.0.0`**:`pyproject.toml` / `package.json` / `__init__.py`,以及 README 的安装示例输出(`dsh-coderag --version` 的期望值)与 `docs/architecture.md` 的「实现版本」。**历史证据一律未动**:`CHANGELOG.md` 的 `## [1.0.0] - 2026-09-23` 整条保持原样(含「均为 `1.0.0`」那句),`PROJECT.md` §6.7 里所有 `1.0.0` 读数、`ADR-16`/`ADR-17`/`PROJECT.md` §1.4 的 `S6` 条文(「与 `1.0.0` 逐条一致」是判据的一部分)也一字未改。**`CHANGELOG.md` 新增 `## [2.0.0] - 2026-09-25`**(置于 `[Unreleased]` 之后、`[1.0.0]` 之前,Keep a Changelog 倒序),按任务要求写清三件事——① **默认路径实测提升**:同一份 DSH 语料(3967 文件 / 63046 chunk)、13 题 × 3 次共 78 个真实会话,任务成功率 `11/39 = 28.2% → 32/39 = 82.1%`(**+53.8pp**,Wilson `[0.165, 0.438]` 与 `[0.673, 0.910]` **不重叠**)、中位 token/次 `80,072 → 72,909`(**−8.9%**)、每个做对的任务 `560,868 → 209,311`(**−62.7%**),并**用引用块显式标注这是诊断性配比**(13 条刻意偏向「需要检索」的两类,`locate`+`crossfile` 占 10/13;配比按诊断价值、非真实频率;单语料单模型、3 次尝试不独立 → 真实置信区间比 Wilson 更宽),原始数据指向 `eval/runs/clean-a3/report.md` 与 `clean-b3/report.md`;② **可选向量路径已实现但按 `V4` 不发布**:写明 `embed.py`/`vectors.py`/RRF(k=60) 已在仓库内,`CODERAG_SEMANTIC` 未设即关闭(零网络、不 import `numpy`),不发布的依据是 `V1` 未达(`natural 6/20 = 0.300 < 0.40`)、`V2` 未达(`exact 0.917 ≠ 1.000`,1 条回归)、`V3` 未测量(`V1` 已是析取项),并**明确 `ADR-16`/`ADR-17` 条文仍然有效**、只是发布对象不存在(`T5-15`/`T5-16`/`T5-20`/`T5-22` 因此移出 2.0.0);③ **不发布到 PyPI / npm**:`[2.0.0]` 条目的第一段即声明「只发布在 GitHub(tag / release,`v2.0.0`)」,并同步在 README 的发布方式块补一行「当前版本 `2.0.0` 同样只在 GitHub 上以 tag / release 发布,PyPI 与 npm 上没有任何版本」。**默认安装零向量依赖已核对**:`dependencies` 仍是 `mcp` / `tree-sitter` / `tree-sitter-language-pack` / `pathspec` 四个,`numpy` / `httpx` / `faiss` / `chroma` / `lancedb` / `sentence-transformers` **逐个 absent**;`optional-dependencies` 只有 `dev`(`T5-15` 的 extra `semantic` 已按裁定移出 2.0.0,故不存在——`CHANGELOG` 里也如实写明这条路径本版本不发布)。**一处需要说明的读数变化**:门禁的 `S1` 由证据行里常见的 `0.433` 变为 **`0.302`**、`S2` `0.313 → 0.219`、`S4` `2492 → 2876`——这不是本次改动引起的回归,而是 `natural` 桶已由 7 条扩到 **20** 条(`m3-b3` 口径,总题数 30 → 43)导致的**口径变化**:`回归条数 = 0`(L1 逐 query + L2 用例级)证明默认路径行为未变,`T3-11` 那行记录的扩桶后基线正是 `13/43 = 0.302`。**提交与 tag 的边界**:本任务只做仓库内改动与证据,`git tag` 与 GitHub Release 由项目所有者推送 |
| **T6-01** | 已完成 | `$ Test-Path docs/m6-crossplatform-baseline.md`
`True`
(Windows 上没有 `test -f` 与 `grep`,这两条验收命令按等价语义执行,下同)
`$ "F:\conda\envs\dsh-coderag\python.exe" -c "统计含『已核实』与『未验证』的行数"`
`已核实 : 20`
`未验证 : 16`
`union : 31`
`$ "F:\conda\envs\dsh-coderag\python.exe" scripts/verify-plan.py .`(**须先设 `PYTHONIOENCODING=utf-8`**;否则 cp936 控制台下第 434 行打印 `✅` 抛 `UnicodeEncodeError`,实测 `EXIT=1`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
四项事实的完整实际输出在 `docs/m6-crossplatform-baseline.md` §3:① **win_amd64 wheel 齐备**——PyPI 清单 + 本机真实安装,四个直接依赖与**完整传递闭包零源码编译**,`Successfully installed` 37 个包、`EXIT=0`(Linux 侧 manylinux x86_64 + aarch64 清单亦已核实);② **FTS5 可用**——`sqlite3` `3.53.4`、`compile_options` 含 `ENABLE_FTS5`、FTS5 虚表建成;③ **离线 grammar 可用**——`tree-sitter-language-pack 0.13.0` 带 **170 个已编译 `.pyd`**,socket 全封下 7 个扩展名全部 `has_error=False`;④ **MCP 子进程可拉起**——按 patch 的 `command` 与 `args` 启动,`coderag 2.0.0`、4 个工具、exit 0、stderr 0 字节 | `791d472` | 四项事实**按平台**分区记录「已核实 / 未验证」,未实测的平台一律标未验证。**推翻** §6.5.1「依赖的 Windows wheel 是否齐备未经核实」这条已知阻碍。顺带登记四条 Windows 环境事实(`python3`/`python` 是 Microsoft Store 占位符、`verify-plan.py` 在 cp936 下崩、`pwsh` 不存在只有 PowerShell 5.1、`sh`/`bash`/`grep`/`sed` 均不在 PATH)——**只登记不修**,修法归 `T6-02`/`T6-03`/`T6-05` |
| **T6-02** | 已完成 | `$ "F:\conda\envs\dsh-coderag\python.exe" -m dsh_coderag doctor --help`
`usage: dsh-coderag doctor [-h]`
`options:`
` -h, --help show this help message and exit`
(退出码 0)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m dsh_coderag install-deps --help`
`usage: dsh-coderag install-deps [-h] [--skip-install]`
`options:`
` -h, --help show this help message and exit`
` --skip-install Only self-check; same as CODERAG_SKIP_INSTALL=1.`
(退出码 0)
(Windows 上没有 `grep`,第 3、4 条验收命令按等价语义执行)
`$ python -c "统计含 CODERAG_PYTHON 或 import dsh_coderag 的行数"`
`scripts/install.sh:2`
`scripts/dsh:5`
`$ python -c "两者总行数"`
`scripts/install.sh: total lines = 38`
`scripts/dsh: total lines = 34`
(各 ≤ 40 ✅;两者均**纯 LF**、无 CR)
`$ "F:\conda\envs\dsh-coderag\python.exe" scripts/verify-plan.py .`(须先设 `PYTHONIOENCODING=utf-8`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0)
**实际跑通(不止 `--help`)**:`$ CODERAG_PYTHON=
`$ "F:\conda\envs\dsh-coderag\python.exe" -m dsh_coderag doctor` → `[ok] 解释器:F:\conda\envs\dsh-coderag\python.exe` / `[ok] 版本:3.10.21(要求 >=3.10,<3.13)` / `[ok] FTS5:可用` + 两行可复制的 `CODERAG_PYTHON`,rc=0
`$ "F:\conda\envs\dsh-coderag\python.exe" -m pytest --ignore=tests/test_vectors.py --ignore=tests/test_vector_search.py`
`6 failed, 528 passed, 2 skipped in 38.53s`(**这 6 条失败在 HEAD 的独立 worktree 上用同一解释器同样失败**,即既有 Windows 基线,已逐条登记 `docs/backlog.md`)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m ruff check src tests`
`All checks passed!`
`$ "F:\conda\envs\dsh-coderag\python.exe" -m mypy --strict src/`
`src\dsh_coderag\vectors.py:31: error: Cannot find implementation or library stub for module named "numpy" [import-not-found]`
`Found 1 error in 1 file (checked 26 source files)`(既有环境项:numpy 属可选 extra,本机按 `RL-10` 不装;已登记 backlog) | `e146569` | **范围经项目所有者裁定扩一个文件**(2026-09-30):新增 `src/dsh_coderag/__init__.py`——实测 `import dsh_coderag` 会立即导入 `indexer → tree_sitter`,于是在依赖尚未安装的机器上「`python -m dsh_coderag doctor` 根本起不来」,而 `install.sh` 的版本校验与 FTS5 预检**原本就发生在 `pip install` 之前**;改为 PEP 562 惰性导入后,全新 clone 上 CLI 即可运行。**动手时撞到的真回归**:第一版把 `from typing import …` 放在「丢弃工作目录」**之前**,工作区里的 `types.py` 立刻打断导入(`typing → functools → from types import GenericAlias`)——`tests/test_cwd_shadowing.py` 当场抓到;已把丢弃动作移回所有可被遮蔽的导入之前,并把这条约束写进该函数的 docstring。**按 DoD 第 5 条动测试**:`tests/test_cli.py` 扩到两个新子命令、重写 `tests/test_install_script.py`(薄包装契约)、新增 `tests/test_dsh_script.py`(导出 CODERAG_PYTHON、参数转发,以及「拒绝导出 Microsoft Store 占位符」);按 §9 把三条既有 Windows 失败与 LF 保证写进 `docs/backlog.md`,**未顺手修** |
| **T6-03a** | 已完成 | **Windows 半程全部实测通过**(原 `T6-03` 的 Windows 部分;macOS 复跑已按 2026-09-30 裁决拆给 `T6-03b`)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m pytest`
`568 passed, 2 skipped in 48.76s`(**零失败、零 xfail**)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m pytest -rs`
`SKIPPED [1] tests\test_cases.py:95: set CODERAG_L2_CORPUS to the prepared DSH copy`
`SKIPPED [1] tests\test_eval.py:347: set CODERAG_EVAL_CORPUS to an indexed DSH copy to replay the golden set`
(两个 skip 都是 **opt-in 语料用例**,与平台无关)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m ruff check src tests`
`All checks passed!`
`$ "F:\conda\envs\dsh-coderag\python.exe" -m mypy --strict src/`
`Success: no issues found in 26 source files`(此前因缺 numpy 报 1 条,现已消失)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m pytest tests/test_path_filter.py -v`
`collected 10 items` … `10 passed in 1.44s`(原 6 例 + 新增 4 例)
`$ "F:\conda\envs\dsh-coderag\python.exe" scripts/verify-plan.py .`(须先设 `PYTHONIOENCODING=utf-8`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0)
**三类已知失败逐条归因**:① **路径规范化**——`tests/test_walker.py` 的 `_relative_paths` 用 `str(relative_to())`,Windows 上产出 `pkg\sub\util.js`;改用 `.as_posix()`,**断言一字未改**。新增 C-07 用例把 `files.path` 钉成 `pkg/sub/util.py`(断言无反斜杠、无 `:`、非绝对),并参数化覆盖 `pkg/sub`、`pkg\sub`、`.\pkg\sub` 三种输入(后者用 `PureWindowsPath` 构造)。② **行尾——实测结论:不存在**:同一份代码分别以 LF 与 CRLF 写入同一工作区,切出的 chunk 行区间与符号**完全相同**(`1-2` / `5-6`,`kind=function`),入库文本里**没有任何 `\r`**,剥掉上下文前缀后正文逐字符相同(`chunker.py` 用通用换行读文本)。③ **文件句柄——实测结论:机制真实但当前不可达**:`index_sync` 返回后 `.coderag/` 只剩 `index.sqlite3` 与 `last-index.json`(**无 `-wal`/`-shm` 残留**),此时删目录成功;**故意留一个未关闭连接**再删则报 `PermissionError`,关闭后立即成功——`TESTING.md` §6 警示的机制成立,但现有 fixture 不触发,故无需改代码。④ **反向依赖**:`numpy` 恢复为**可选** extra `semantic`(2026-09-30 裁决),全量由 `6 failed, 528 passed` 变为全绿 | `c4e4c11`(计划裁决), `70c4e39`(Wilson 端点), `4190885`(C-07 用例), `8bd6e6d`(extra) | macOS 复跑已按 2026-09-30 裁决**拆给 `T6-03b`**(本机无 macOS 机器),本任务的期望结果同步收窄为 Windows 半边。**基线对照**:`T6-02` 记录的 6 条失败在 HEAD(`dc7d971`)的独立 worktree 上用同一解释器**同样失败**,本次处置的是既有基线、不是新引入的回归。**范围说明**:`pyproject.toml`(extra)、`AGENTS.md`(C-07 标注)、`PROJECT.md` §6.5.1/§6.8(裁决)都在任务行产出文件之外,已由项目所有者 2026-09-30 裁决授权归入本任务。**读数的复现条件(重要)**:上面那个 `568 passed, 2 skipped` 是**当时**的读数(`T6-03b` 之后同一套代码是 `570 passed, 2 skipped`);而它成立的前提是 **`bash` 在 `PATH` 上**(把 Git for Windows 的 `usr/bin` 放进去,使 `shutil.which("bash")` 找得到)。`bash` 不在 `PATH` 上时,同一个提交给出 `555 passed, 17 skipped`——差值恰好是 `tests/test_dsh_script.py`(7 条)与 `tests/test_install_script.py`(8 条)按既有的 `skipif(BASH is None)` 跳过,**两次收集到的用例总数都是 572**,不是回归。macOS 侧天然有 `bash`,所以 `T6-03b` 的 `567 passed, 5 skipped` 与它可比 |
| **T6-03b** | 已完成 | **M6 的 macOS 集中复核完成**(2026-09-30 裁决的执行载体;`T6-04` 的 macOS 栏并入本文)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -rs`
`SKIPPED [1] tests/test_cases.py:95: set CODERAG_L2_CORPUS to the prepared DSH copy`
`SKIPPED [1] tests/test_eval.py:347: set CODERAG_EVAL_CORPUS to an indexed DSH copy to replay the golden set`
`SKIPPED [3] tests/test_path_filter.py:72: backslash separators only resolve as path separators on Windows`
`567 passed, 5 skipped in 11.23s`(**0 failed、0 xfail**)
`$ /opt/anaconda3/envs/forBSH/bin/python -m ruff check src tests`
`All checks passed!`
`$ /opt/anaconda3/envs/forBSH/bin/python -m mypy --strict src/`
`Success: no issues found in 26 source files`
`$ python3 scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
**`T6-04` 的 macOS 栏(端到端冒烟,全新 `DSH_HOME` + 全新 profile `m6mac`)**:`$ DSH_HOME=/tmp/dsh-m6-t603b/dshhome ./scripts/dsh plugin --profile m6mac add .`
`dsh: initialized profile m6mac at …/profiles/m6mac` / `+ dsh-coderag link:…` / `Done in 2s using pnpm v12.4.2`(EXIT=0)
`$ ./scripts/dsh --profile m6mac --dump-config`(EXIT=0,354 行)
`333:# == dsh-coderag` → `- id: mcp-coderag` / `command: !!js process.env.CODERAG_PYTHON ?? …`;扫 `ERR_PNPM`/`error`/`skipped` **0/0/0 命中**,stderr 为空
demo 干净副本(`git archive HEAD examples/demo-workspace`,4 文件、无 `.coderag/`)上真实 MCP 冒烟:`initialize: {name: coderag, version: 2.0.0}` / `final index_status: {state: ready, total_files: 3, total_chunks: 7}` / `code_search` → `status: ready`、`hits: 1`、`── src/auth/token.py:1-6 [module] (chunk 0)`、`isError: False`;索引只落副本,**原仓库未被污染** | `e9dcb2f`(`docs/m6-macos-verification.md` + `scripts/dsh` + `scripts/install.sh` + `tests/test_dsh_script.py`) | **先行失败已查清并修掉(本行最重要的部分)**:首次 macOS 全量是 `1 failed, 564 passed, 5 skipped`,失败在 `tests/test_dsh_script.py::test_dsh_script_does_not_export_an_unusable_interpreter`。三层根因:① **测试未隔离 `CONDA_PREFIX`**——`run_dsh` 只清 `CODERAG_*`,于是包装脚本走 `${CONDA_PREFIX}/bin/python` 分支、导出本机**可用**的 `/opt/anaconda3/bin/python`(3.13.5),而断言要的是 `unset`;决定性证据:`env -u CONDA_PREFIX` 下同一条用例**通过** → macOS 上是**假红**,它在 Windows 上通过只是因为 `
**Windows 侧实测**(`docs/m6-windows-smoke.md`)——冒烟环境:全新解释器 `…\dsh-m6-t604\fresh-python`(Python 3.10.21,装前只有 `pip`+`setuptools`)、全新 `DSH_HOME` `…\dsh-m6-t604\dshhome`、全新 profile `m6smoke`、`dsh` = `F:\dsh\resources\runtime\cli\bin\dsh.cmd`(**0.2.0-rc.2**)、自带 pnpm **v11.7.0**、demo 工作区干净副本 `…\dsh-m6-t604\demo-ws`
**(a) 默认安装路径零向量依赖(过渡式断言)**
`$ …\fresh-python\Scripts\python.exe -m dsh_coderag install-deps`
`安装 :… -m pip install .`
`== 自检:FTS5 可用 + 中文 bigram 往返 ==`
`[ok] 中文往返:'用户令牌' -> ['token.py']`
`完成:安装与自检通过`(EXIT=0)
`$ …\fresh-python\Scripts\python.exe -c "import numpy"`
`ModuleNotFoundError: No module named 'numpy'`(**EXIT=1**)
`$ …\fresh-python\Scripts\python.exe -m pip show dsh-coderag`
`Requires: mcp, pathspec, tree-sitter, tree-sitter-language-pack`(**无 numpy**)
**(b) 全新 DSH_HOME + 全新 profile:`dsh plugin add .`**
`dependencies:`
`+ dsh-coderag link:F:/PersonalProjects/python/dsh-coderag/dsh-coderag`
`✓ Lockfile passes supply-chain policies (verified 2m ago)`
`Done in 366ms using pnpm v11.7.0`(EXIT=0;**无 `ERR_PNPM…`、无静默跳过**)
`$ dsh --profile m6smoke --dump-config`(exit 0,383 行)
`# == dsh-coderag`;插入行含 `id: mcp-coderag` 与 `args: ['-c', 'import dsh_coderag.server as s; s.run()']`;对整个 dump 扫 `ERR_PNPM`、`error`、`skipped` **无命中**
**(c) demo 副本上的真实 code_search**(按 patch 的 `command`/`args` 直连子进程)
`initialize: {'name': 'coderag', 'version': '2.0.0'}`
`code_index: {'taskId': 'idx-20260930-e2e0', 'state': 'pending', …}`
`final index_status: {'state': 'ready', 'total_files': 3, 'total_chunks': 7, …}`
`status: ready` / `hits: 1 (sorted by source order)` / `── src/auth/token.py:1-6 [module] (chunk 0)`;`hit target file: True`;`child exit: 0`
索引只落在副本的 `.coderag/`(`index.sqlite3` 65536 B + `last-index.json`);原仓库 `examples/demo-workspace` **无** `.coderag`;冒烟后 `git status --short` 为空
**(d) 终端与 CODERAG_PYTHON**
`powershell.exe` = `C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe`;`pwsh` = **NOT INSTALLED**;`$PSVersionTable` = `5.1.26100.5074 (Desktop)`
`CODERAG_PYTHON=C:\Users\15349\AppData\Local\Temp\dsh-m6-t604\fresh-python\Scripts\python.exe`
验收读数:`Test-Path docs/m6-windows-smoke.md` → `True`;三项各自 ≥1 → `code_search 7`、`dump-config 9`、`CODERAG_PYTHON 11`
`$ …python.exe scripts/verify-plan.py .`(须先设 `PYTHONIOENCODING=utf-8`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0) | `dd0fc2e`(冒烟), `37e77ad`(补两平台栏) | **收口(2026-09-30,拉取 macOS 侧后在 Windows 复验)**:macOS 栏已由 `T6-03b` 的集中复核补齐,期望结果全部成立。**两平台对账闭合**:收集用例数两边都是 **572**;Windows `570 passed, 2 skipped`、macOS `567 passed, 5 skipped`,差值恰好是 `tests/test_path_filter.py` 里 `skipif(sys.platform != "win32")` 的 3 条(`570 − 3 = 567`、`2 + 3 = 5`)。**拉取 macOS 改动后 Windows 曾红一条**——`test_dsh_script_prefers_a_usable_conda_interpreter` 按原始字符串比较,而 Windows 的 `CONDA_PREFIX` 本身就是 Windows 路径、包装脚本算出的候选是混合分隔符;已由 `f4b8f24` 改成按**路径值**比较修好(比较的身份不变,不是放宽断言;另两条 `unset` 断言还一并收紧了)。修正后 Windows 复跑 `570 passed, 2 skipped`、ruff 与 `mypy --strict` 干净。**两处与既有记录的偏差已并列声明**:① 本机自带的 `dsh` 是 **0.2.0-rc.2**,而 `scripts/dsh` 钉的是 `0.1.5-rc.1`(本机无该版本、npx 缓存为空),故结论是「在 `0.2.0-rc.2` + pnpm `11.7.0` 下成立」;② `--dump-config` 把 `command` 渲染成**未求值的 `!!js` 表达式**,因此它**不能**证明 `CODERAG_PYTHON` 覆盖已生效——「DSH 真的用该解释器拉起子进程」这一环未直接测(`dsh` 只有 `plugin` 与启动 profile,`headless` 需 model key)。**顺带实测三条(只记录、不改文件)**:`bash scripts/install.sh` 在 Git for Windows 的 bash 下能把**空**解释器装好(靠 MSYS2 把 POSIX 形式的 `PYTHONPATH` 转成 Windows 形式,措辞归 `T6-05`);`--dump-config` 不求值 `!!js`(别把它当覆盖证据);`install-deps` 重定向时 pip 子进程的输出会**排在自己的进度行之前**(Python 块缓冲 vs 子进程直写 fd),属观感问题、若修应另立条目。**本任务未修改任何已有文件**——产物只有 `docs/m6-windows-smoke.md` |
| **T6-05** | 已完成 | (Windows 上没有 `grep`,三条 grep 验收命令按等价语义执行)
`$ python -c "统计关键词行数"`
`README Windows=11 PowerShell=4`(要求 ≥2 处)
`docs/architecture.md Windows=4`(要求 ≥1 处)
`README "只发布在 GitHub"=1`(**发布状态那段仍在**)
`$ "F:\conda\envs\dsh-coderag\python.exe" scripts/verify-plan.py .`(须先设 `PYTHONIOENCODING=utf-8`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0)
**改了什么**:① `README.md` 的「安装」章节由纯 Unix 拆成 **`### macOS / Linux(POSIX shell)`** 与 **`### Windows(PowerShell)`**,两段各自给出可照抄的命令(macOS:`bash scripts/install.sh` → `"$CODERAG_PYTHON" -m dsh_coderag doctor` → `./scripts/dsh --profile web --patch …`;Windows:`python -m pip install .` → `python -m dsh_coderag doctor` → `$env:CODERAG_PYTHON = …` → `dsh --profile web --patch .\cordis.patch.yml`,并给出无全局 `dsh` 时的 `npx` 形态);平台状态段由「只有 macOS 已实测、Windows 尚未验证」改为**实测清单**(macOS 26.4 + Windows 10 26100),并明确 **Linux 未实测、因此不声称支持**;`--dump-config` 自查与排障表补上 Windows 等价写法;前置条件里的「pnpm」改为「`dsh` 自带」(实测 Windows 的 `PATH` 上没有 pnpm 也能装成)。② `docs/architecture.md` 的「验证环境」由「仅 macOS + DSH `0.1.5-rc.1`」改为**实测平台清单**,并把「两平台实测用的 DSH 版本不同(`0.1.5-rc.1` / `0.2.0-rc.2`)、没有任何一个版本被两平台都跑过」写进同一处;**Linux 仍不写进去**。③ `docs/m4-install-verification.md` 的「非 macOS / 非 conda」限制按 `T6-04` 的实测**收窄**,同时声明**本文件自身的实测仍全部来自 macOS、原文不改** | `de89a0a`(README), `4cc1d85`(另两份文档) `bf16078`(Windows 安装/配置复核) | **证据只取实际输出**:`T6-01`/`T6-03b`/`T6-04` 的三份报告(`docs/m6-crossplatform-baseline.md`、`docs/m6-macos-verification.md`、`docs/m6-windows-smoke.md`)被逐一链接,没有一条平台声明是推断出来的。**未实测的平台不写成「照做即可」**:Windows 段全部来自 `docs/m6-windows-smoke.md` 的实跑,macOS 段全部来自 `docs/m6-macos-verification.md` 的实跑,而 **Linux 在 README 与 architecture.md 里都写成「未实测、不声称支持」**——这正是 M6 出口判据的要求。**`D-08` 未被触碰**:README 的「安全与隐私警告」小节(云端后端外发的 7 条要点)在本次 diff 里**零改动**(`git diff` 无一行命中 `安全风险` / `离开这台机器` / `外发`);**`D-04` 仍在**:第一屏的机器权限声明未动。
**复核(2026-09-30,用户要求把 Windows 的安装与配置方法写进 README 并自测)**:逐条实跑文档里的 Windows 命令后,**改掉三处照抄会失败的写法、并改正一处空承诺**——① 原安装段用**裸 `python`**,而 Windows 上 `python` / `python3` 可能是 Microsoft Store 占位符(本机实测报 `Python was not found; run without arguments to install from the Microsoft Store …`);改为显式路径变量 `$py` 并给出 `py -0p` 的识别方法。② 原安装段用**裸 `dsh`**,而本机 `dsh` **不在 `PATH` 上**(`E-07`);改为 `$dsh` 变量并给出**实测可用**的两种取法(桌面版自带的 `<安装目录>\resources\runtime\cli\bin\dsh.cmd`;Git Bash + `bash scripts/dsh`)。③ 原「怎么确认装上了」用 `# == dsh-coderag` 标记,却把启动写成 `--patch` 路线——**实测两条路线不同**:`plugin add` 的 dump 有该标记(1 处),`--patch` 的 dump**没有**(0 处,只有 `- id: mcp-coderag`);已按路线分别给出正确的核对命令,并写明「新起的 profile 名拿不到 web 应用」。④ 配置表曾承诺 5 个上限变量,**实测全部不生效**(`CODERAG_MAX_TOKENS` 设 1 与设 8000 输出逐字相同;`CODERAG_MAX_FILES=1` 仍索引 6 个文件;`CODERAG_MAX_FILE_BYTES=20` 仍索引 48 字节文件),根因是 `server.py:295` 裸传 `index_sync`、`load_config()` 只取 `.root`、`server.py:218` 硬编码 4000;表格已改成「当前是否真的生效」并指向 `docs/backlog.md` 的专条,**不修代码**(本任务产出文件只有文档)。新增内容:Windows 的配置落点(`%USERPROFILE%\.dsh\...`,实测 `$DSH_HOME` 就是它)、一段**实测过**的 `cordis.patch.yml` 覆盖示例、「整体替换」的**实测**后果(只写 `env` 会让 `serverName`/`transport`/`args` 消失,与 DSH schema 自述 *"A patch config replaces the whole config."* 一致) |
| **T6-06** | 已完成 | `$ "F:\conda\envs\dsh-coderag\python.exe" -m dsh_coderag --version`
`dsh-coderag 2.1.0`(退出码 0)
`$ node -e "console.log(require('./package.json').version)"`
`2.1.0`(退出码 0)
`$ python -c "统计 CHANGELOG 的二级小节"`
`2.1.0 headings : 1`
`2.0.0 headings : 1`(**历史条目保留**)
`$ git tag -l v2.1.0`
`v2.1.0`
`$ git ls-remote --tags origin v2.1.0`
`07b7078dc312bec31015997052526a33282e658e refs/tags/v2.1.0`(**已推送到 origin**,指向发布提交 `7ea1823`)
`$ "F:\conda\envs\dsh-coderag\python.exe" scripts/verify-plan.py .`(须先设 `PYTHONIOENCODING=utf-8`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0)
`$ "F:\conda\envs\dsh-coderag\python.exe" -m pytest`(`bash` 在 `PATH` 上)
`570 passed, 2 skipped in 47.41s`
**六处版本号**:`pyproject.toml` / `package.json` / `src/dsh_coderag/__init__.py` / `CHANGELOG.md`(新增 `## [2.1.0] - 2026-09-30`)/ `README.md` 的「当前版本」/ `docs/architecture.md` 的「实现版本」——`git diff --stat` 恰好是任务行声明的这 6 个文件(56 insertions / 5 deletions)。**发布状态仍在**:README 的「只发布在 GitHub」= 1 行;**`CHANGELOG` 的历史条目一字未动**(`[2.0.0]` 与 `[1.0.0]` 小节原样保留) | `7ea1823`(发布), tag `v2.1.0`(**带注释**,指向 `7ea1823`) | **`CHANGELOG` 的 `[2.1.0]` 写清了 M6 的四件事**:Python CLI 成为唯一跨平台入口(两份 shell 脚本退为薄包装,38 / 31 行)、实测平台清单 = macOS 26.4 + Windows 10 26100、`semantic` extra 恢复为 numpy 的声明住所而 `dependencies` 仍不含 numpy(`RL-10`)、**Linux 未实测因此不声称支持**;并写明两平台实测用的 DSH 版本不同、没有任何一个版本被两平台都跑过。**发布范围**:只推 GitHub(提交 + 带注释 tag),**没有任何 PyPI / npm 动作**。**过程中的一次网络故障如实记录**:首次 `git push` 报 `Failed to connect to github.com port 443 after 21057 ms: Timed out`(同刻 `api.github.com` 返回 `200`、`github.com:443` 不可达),重试第 2 次成功;提交与 tag 全程在本地,**没有丢任何东西** |
| **T6-07** | 已完成 | `$ "F:\conda\envs\dsh-coderag\python.exe" -m pytest tests/test_server.py -q`
`.......... [100%]`(**10 passed**:原有 7 条 + 新增 3 条)
`$ "…python.exe" -m ruff check src tests`
`All checks passed!`
`$ "…python.exe" -m mypy --strict src/`
`Success: no issues found in 26 source files`
`$ "…python.exe" -m pytest`(`bash` 在 PATH 上;修复前是 570,新增 3 条后 573)
`573 passed, 2 skipped in 46.60s`
`$ "…python.exe" scripts/verify-plan.py .`
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0)
**关键证据(这 3 条测试确实能证明修复)**:把 `server.py` 临时退回 `HEAD` 后重跑 → `3 failed, 7 deselected`,症状正是缺陷本身——`assert 2 == 1`(字节上限没生效,两个文件都入库)与 `assert "hits: 2" not in text`(预算没生效,命中数未被裁剪)。**不是放宽断言**(`T-08`):断言在修复前后一字未改 | `c4eb4d4`(修复 + 3 条测试 + README 配置表 + backlog 标记已修) | **改了什么**:新增 `server.py::workspace_config(root)`——把已知的 `root` 填进环境副本再调 `load_config()`,因此 `build_server(root=...)`(测试与嵌入调用)**在不设 `CODERAG_ROOT` 时也读得到可调变量**,显式设置的值仍优先、格式错误仍抛 `ConfigError`(不放宽 `config.py` 的校验契约)。接进**三处**:① **建索引** ← `TaskManager(...).start(target, partial(index_sync, config=config))`;② **检索默认预算** ← `arguments.get("max_tokens", …max_tokens)`(工具参数仍可逐次覆盖);③ **工作区形态 `index_status` 的 skip 统计** ← `walk_with_report(root, max_files=…, max_file_bytes=…)`——这是修 ② 时被新测试**顺带抓出来的第二处未接线**(`total_files=1` 已正确,但 `skipped` 仍报 0,违反 `§4.2`「过滤必须可见」),并让它超限时返回 `INDEX_TOO_MANY_FILES` 而不是兜底的 `SEARCH_FAILED`。**`RL-08` 未被放松**:超限仍显式失败 + 报实际数量。`README.md` 的配置表由「5 行 ⚠️ 未生效」改回真实状态并注明曾经历;`docs/backlog.md` 该条标记为由 `T6-07` 修复 |
| **T6-08** | 已完成 | **发布后 macOS 复跑:`T6-07` 的修复在 macOS 上同样生效,零退化**(被复核的提交 = `98186cf`,与派单预期一致;解释器 `Python 3.10.21`)
`$ /opt/anaconda3/envs/forBSH/bin/python -m pytest -rs`
`SKIPPED [1] tests/test_cases.py:95: set CODERAG_L2_CORPUS to the prepared DSH copy`
`SKIPPED [1] tests/test_eval.py:347: set CODERAG_EVAL_CORPUS to an indexed DSH copy to replay the golden set`
`SKIPPED [3] tests/test_path_filter.py:72: backslash separators only resolve as path separators on Windows`
`570 passed, 5 skipped in 11.42s`(**0 failed、0 xfail**;另跑 `-rxX` 无 xfail/xpass 报告)
`$ …python -m pytest --collect-only` → `575 tests collected in 0.28s`(**算术闭合**:`570 + 5 = 575`)
**单独验修复本身**:`$ …python -m pytest tests/test_server.py -rs`
`10 passed in 0.37s`(该文件 7 → **10** 条,**零 skip**——新增的 3 条是**平台中立**的「走 MCP 工具」用例:`max_files` 超限报实际数、`max_file_bytes` 计入 `skipped.too_large`、不传 `max_tokens` 时预算取自环境。跳过就等于没验,故它们必须在 macOS 上 passed)
`$ …python -m ruff check src tests` → `All checks passed!`;`$ …python -m mypy --strict src/` → `Success: no issues found in 26 source files`;`$ python3 scripts/verify-plan.py .` → `计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`
**两平台并列(收集总数 575 闭合)**:Windows `573 passed, 2 skipped` ↔ macOS `570 passed, 5 skipped`。**差值 3 的归因**:`tests/test_path_filter.py:72` 的 `test_path_filter_accepts_windows_style_separators` 是**平台守卫的参数化用例**(`skipif(sys.platform != "win32")`,3 个参数)——Windows 跑这 3 条(进 `passed`)、macOS 跳这 3 条(进 `skipped`),故 `573 + 2 = 575`、`570 + 5 = 575` 两边总数一致;另 2 条 skip 是两侧相同、与平台无关的语料 opt-in 用例 | `5349abd`(`docs/m6-macos-verification.md` §7 + `PROJECT.md`) | **为什么要有这次复跑**:v2.1.0(tag `v2.1.0` → `7ea1823`)发布后才发现 `CODERAG_MAX_FILES` / `_MAX_TOKENS` / `_MAX_FILE_BYTES` / `_BATCH_SIZE` / `_MAX_WORKERS` 在 **MCP 路径上完全不生效**(`server.py` 把 `index_sync` 裸传给 `TaskManager`、检索预算硬编码 `4000`),修复在 `c4eb4d4`(`T6-07`);而 macOS 上一次实跑停在 `e9dcb2f`,此后 **18 个提交**没在 macOS 上跑过——本次把这 18 个提交补上。**纯复跑与记录**:`src/` / `tests/` 一行未动,未改任何断言、未放宽任何判据(`T-08`)。**保留的边界**:Linux 仍未实测(README / `docs/architecture.md` 仍写「不声称支持」);macOS **不提供** `RL-10` 的「默认安装路径不装 numpy」证据(forBSH 里装着 numpy,那是向量 extra 的前提);两平台实测的 DSH 版本不同(macOS `0.1.5-rc.1` / Windows `0.2.0-rc.2`),**没有任何一个版本被两平台都跑过**;未打新 tag、未发 `v2.1.1`、未跑 L1/L2 评测门禁 |
| **T6-09** | 已完成 | `$ "F:\conda\envs\dsh-coderag\python.exe" -m dsh_coderag --version`
`dsh-coderag 2.1.1`(退出码 0)
`$ node -e "console.log(require('./package.json').version)"`
`2.1.1`(退出码 0)
`$ python -c "统计 CHANGELOG 的二级小节与 README 的发布状态"`
`2.1.1: 1,2.1.0: 1,2.0.0: 1,只发布在 GitHub: 1`(**历史条目全部保留**、发布状态那段仍在)
`$ git tag -l v2.1.1`
`v2.1.1`
`$ git ls-remote --tags origin v2.1.1`
`9bf66e44434c5c357b3557186a4aee1ca9f3657a refs/tags/v2.1.1`(**已推送到 origin**,指向发布提交 `6b88e20`)
`$ "…python.exe" scripts/verify-plan.py .`(须先设 `PYTHONIOENCODING=utf-8`)
`计划完备性:通过 ✅ (28 项检查全部实际执行,无空过)`(退出码 0)
`$ "…python.exe" -m pytest`(`bash` 在 PATH 上)
`573 passed, 2 skipped in 48.07s`
**额外自查**:`git archive --format=tar v2.1.1` 能正常打包(`tar bytes: 3102723`)——tag 确实指向一个可归档的发布物。`git diff --stat` 恰好是任务行声明的 6 个文件(39 insertions / 5 deletions) | `6b88e20`(发布), tag `v2.1.1`(**带注释**,指向 `6b88e20`) | **本版本只做一件事**:把 `T6-07` 的接线修复做成**可消费**的补丁发布。`CHANGELOG.md` 的 `[2.1.1]` 条目写清三件事——① **修复**:5 个可调上限在 MCP 路径上不生效的**根因**(`index_sync` 裸传 + 预算硬编码 `4000`)与修法(`workspace_config(root)` 接进建索引 / 检索默认预算 / 工作区 skip 统计);② `index_status` 的过滤统计随之与配置一致、超限报 `INDEX_TOO_MANY_FILES` 而非兜底 `SEARCH_FAILED`;③ **新增**那 3 条走 MCP 工具的测试,并注明**它们在修复前会红**、以及原有 `T2-11` / `T2-21` 单测为何一直全绿。**发布范围**:只推 GitHub(提交 + 带注释 tag),**没有任何 PyPI / npm 动作**。**与 `v2.1.0` 的关系已在条目里写明**:`2.1.0` 的 README 当时把受影响的 5 个变量**如实标注为「未生效」**,所以那不是发布物撒谎,本版本只是把接线补上——这条对齐了 `D-06`(文档描述当前状态)与 `D-08`(未触碰云端警告) |
---
### 6.8 覆盖矩阵(**完备性的可验证形式**)
> **为什么需要这张表**:覆盖关系**不能自动推断**。例如红线 RL-01("禁止修改 DSH 文件")约束的是**所有**任务,不会被任何一个任务"引用";而 ADR-07(中文分词)则由 `T1-06` 和 `T2-19` 具体落地。
> 本表把每条定义**显式**映射到"由谁强制",然后由 `scripts/verify-plan.py` 反向验证**这张表自身完整且引用有效**。
**强制点的三种取值**:
- `T*-**` —— 由某个具体任务实现/验证
- `*全局*` —— 适用于所有任务的边界规则,无单一落点
- `—` —— 已被其他文档的规则取代,本项目不单独落地(须在「说明」里写明)
| 定义 | 强制点 | 说明 |
|---|---|---|
| ADR-01 | *全局* | 架构决策(Python + MCP)。由 §1.6 的仓库布局与 T1-14 落地 |
| ADR-02 | T3-07 | 第一版只做 BM25;由决策门强制,`RL-10` 是它的红线形式 |
| ADR-03 | T1-11 | 工具集固定为 4 个;`RL-05` 是它的红线形式 |
| ADR-04 | T1-12 | 索引异步化,立刻返回 taskId |
| ADR-05 | T2-14, T3-14 | 检索结果按源码顺序输出 |
| ADR-06 | T1-13 | 索引未就绪返回结构化状态;`RL-06` 是它的红线形式 |
| ADR-07 | T1-06, T2-19, T3-13 | 中文 bigram 预处理 + 精度/召回双模式 |
| ADR-08 | T2-06 | 三层安全过滤(密钥黑名单 / 忽略规则 / 内容扫描) |
| ADR-09 | T2-09 | 索引状态与忽略规则一并持久化 |
| ADR-10 | T2-11 | 超过文件数上限显式失败并报实际数量 |
| ADR-11 | T2-10 | 并发度与批大小自适应,不硬编码 |
| ADR-12 | T3-04 | 指标用 `Success@k`,不用 nDCG |
| ADR-13 | T2-19 | 标点/短符号查询路由到 `grep`,不做全表 `LIKE` |
| ADR-14 | T3-07, T3-08, T3-09, T3-10, T3-11 | R2 命中:词法为底 + 向量补齐自然语言查询;执行由已重启的 `T3-08`–`T3-11` 落地,判据是 `ADR-14` §10.4 的 V1–V4 |
| ADR-15 | T3-08, T3-11, T5-16 | **已重启为可选后端(2.0.0)**:默认关闭、未配置时干净退回纯 BM25、**不得进入必需依赖**;重启条件见 `ADR-15` §3,形态由 `ADR-16`(`T5-05`)冻结 |
| ADR-16 | T3-08, T3-09, T3-10, T3-11, T6-03a | **可选后端的可验收形态(2.0.0)**:默认关闭 + opt-in、未配置时输出与 1.0.0 逐字节一致、extra 名 `semantic`(只有 numpy)/后端 `ollama`+`bge-m3`/索引落点 `