只读研究模式 TLNing260310/dsh-researcher

dsh-researcher

CI
Release
License: MIT
Status: alpha

让 AI coding 先理解项目现实，再冻结“什么算完成”，最后由证据而不是 Agent 的自信结束工作。
Recover project reality, freeze what “done” means, and let evidence—not agent confidence—stop the loop.

dsh-researcher 是 DeepSeek Harness 的 DSH 插件。它把普通 Plan Mode 常常混在一起的三件事分开：

- Project Research：在制度性只读会话中重建项目的目的、架构、约束、风险与未知项，审查视角来自一个受策展的架构透镜库。
- Goal Governor：冻结目标、边界、预算、人工 gate 与完成定义；终态由宿主从可信事件推导，而不是由 Agent 的文字宣布。
- Research Entry（/research）：在普通编码会话中按需进入只读研究模式，并携带当前对话上下文。其余时间完全惰性。

三者可以分开使用。你可以只试用 Project Research，而不采纳 Goal Contract。

这个模式关停了什么，以及为什么

开发者的判断是：其余工具会争夺注意力预算。因此本模式在三个层级上全面关停，而不是只关一层：

| 层级 | 关停内容 |
| 沙箱层 | 会话运行在 read-only；写入被环境拒绝，而不是靠纪律 |
| 工具描述层 | write / edit 被替换为永拒桩；面向写入的引导段被同名遮蔽，根本不进入 prompt |
| 权限层 | 审批被收紧为 never——按设计不存在升级路径 |

没有 shell。唯一的子进程能力是 git_read：固定白名单，无 -c、无 alias、无 pager，忽略全局 git 配置。本模式只读与推理，从不执行。

环境要求——安装前必读。 研究模式严格且 fail-closed：要求 DSH 0.1.5-rc.3、Node ^22.19.0 || >=24.0.0，且会话必须以 Read Only 权限启动。任一不满足，preset 会拒绝启动而不是降级运行。这是有意的：无法证明只读的环境，不能运行本模式。详见部署与使用须知。

本模式当前还不能做什么。 它尚不具备按任务动态注入注意力的能力——该能力正在规划中，正在搜集知识库与成熟项目做法。现阶段的注意力引导来自固定 persona 加两个技能文件。不要向用户宣称本模式会随任务改变审查视角。

当前边界：DSH adapter、只读运行时和离线验证设施已有机械测试与真实 Web smoke；v1.5 与不完整 v1.6-v1.11 均为 INVALID，v1.12 只做离线修正且 live round 已停止。长期维护收益、真实模型端到端成功率和其他客户端 adapter 尚未证明。本项目不是"更聪明的 Agent"，也不承诺自动消除模型幻觉。

你可能正遇到这个问题

第一次让 Agent 修改仓库时，结果通常很好。第五次、第十次之后，问题开始改变：

1. 新会话重新猜测项目目的，旧结论无法区分事实、推断和过期假设。
2. 每个局部改动都看似合理，累积结果却越过原来的架构、安全或迁移边界。
3. 测试已经通过，Agent 仍继续“顺便优化”；或者测试没有通过，它却先宣布 DONE。
4. 人也不知道什么状态算完成，于是不断修改，直到时间耗尽或项目偏离初衷。

研究模式要做什么

目的是把模型的注意力放到对这个项目真正有价值的改动上，并让它留在那里。一次研究应当能够：

- 说清这个项目实际的目的，以及它真实的运行环境；
- 找出它正在偏离自身架构的地方，以及一个局部合理的改动会在哪里越界；
- 判断一个改动值不值得做，包括对提示词与上下文的修改，并给出这项修改能换来什么；
- 定位这个项目下一步最容易犯的错误；
- 在下结论之前反向提问：要让上面这个判断不成立，需要什么成立；如果换一种架构，会有什么不同。

输出是结构化报告，不是聊天。每条事实断言都带引用，否则标注未验证；结论归入 BUILD / DON'T BUILD / INVESTIGATE。

一个来自真实项目的经验知识库已在规划中：按任务需要挑选并注入，让模型去核对与当前任务真正相关的角度。目前尚不存在——见上方的诚实声明。

本项目不适合谁

直说，因为时间很贵：

- 不适合盯着某一处代码错误。 如果你已经知道哪一行错了、只想把它改掉，请用普通 Agent——研究模式不能写。
- 不适合什么都点头的模型。 本模式的设计就是反驳自己的判断；一个寻求认可的助手只会产出仪式感，不会产出发现。
- 不适合没有决策的任务。 如果没有任何东西存在疑问，就没有什么可研究的。

它特别适合两种情形：刚接触一个没做过的项目，需要快速对齐它的目的、边界与真实运行环境；以及一个项目已经过了多轮 AI 修改，看起来是对的，却在悄悄积累漏洞、或已经不再前进——此时缺的不是努力，而是对"这个项目现在到底是什么"的正确认识。

普通 Plan 记录“准备做哪些步骤”。本项目额外冻结：

项目为何存在、哪些事实可信 + 本次任务做到什么算结束、不能碰什么、最多尝试多少次 + 宿主真实观察到的工具调用、参数、结果和工作树 ↓ CONTINUE / NEEDS_HUMAN / DONE / STOPPED

60 秒看懂 Goal Governor

仓库内置一个零网络、零模型费用的可运行演示。它创建隔离临时 fixture，真实启动两次冻结 verifier 子进程，并把进程退出码交给发布代码中的 DSH replay adapter 和 host reducer：

npm run demo

1. Assistant says DONE, but supplied no trusted verifier evidence.
Host decision: CONTINUE

2. The matching host tool ran and returned exit_code=1.
Host decision: CONTINUE

3. The same frozen host tool ran after the change and returned exit_code=0.
Host decision: DONE

只有匹配的真实 verifier 通过后，宿主才判定 DONE

Agent 的最终文字不是证据。只有与已批准 verifier 的工具名、完整参数、参数哈希和结果策略匹配的宿主事件，才能满足完成条件。演示中的文件修改和 verifier 进程是真实的；DSH-shaped event envelope 与 call ID 由离线 harness 构造。演示源码见 scripts/demo-governor.js。它证明真实进程结果可被 reducer 正确裁决，不是 Live DSH、Live E1 或生产力实验。

先选你需要的层

| 你的场景 | 建议 | 当前成熟度 |
| 接手陌生仓库、重构前核对架构、只想让 Agent 只读研究 | Project Research | 可隔离试用；安全边界有真实 DSH Web smoke |
| 希望审查视角由系统代选 | 普通编码会话中运行 /research | 机制已验证；透镜选择质量未验证 |
| 编码中临时核对一个项目事实 | Governed Coding 中运行 /researcher | 可隔离试用；一次只读 turn |
| 需要冻结验收条件、预算、人工 gate 和停止状态 | Goal Governor | 高级 alpha；机制有测试，结果增益未证明 |
| 一个明显的小 bug、简单 CRUD、一次性脚本 | 继续使用普通 Agent / Plan | 本项目通常过重 |
| 只使用 Codex、Claude Code、Zed/Zcode 或 OpenClaw | 暂不安装 | Portable Core 存在，但相应 adapter 未交付 |

Project Research 与 Goal Governor 并不捆绑。你可以只安装后试用前者，不创建任何 Goal Contract。

本项目适合谁

本项目假定使用者具备判断证据的能力。它不是"装上就能用"的助手：

- 你必须能读懂证据强度。 每条断言带 file:line、commit 或 URL，并同时标注证据层级（C0–C4）与裁决态（Known / Likely / Claimed / Unknown / Contradicted）。两者是独立的两轴，组合规则见方法论技能中的可查表。
- 你必须接受研究可能一个字也跑不出来。 环境不符时 preset 直接拒绝启动，而不是降级运行。
- 你必须自己下架构决定。 本模式产出认知与候选方向，永不产出执行授权。
- 你必须接受注意力面被刻意收窄。 没有 shell、没有 MCP 工具面、没有写工具——在只读研究里，这些是注意力成本，不是能力。

安全试装

分发身份说明：本项目当前只通过固定 GitHub tag 或 GitHub Release 制品分发。npm 上未加 scope 的 dsh-researcher 属于另一位维护者和另一个仓库，请勿运行 npm install dsh-researcher。私有 scoped name @tlning260310/dsh-researcher 用于防止误发布；本项目的分发身份是 DSH preset bundle 加 Node 治理库，不宣称自己是原生 marketplace plugin。

前置条件

- DeepSeek Harness 目标版本：0.1.5-rc.3；离线设施已通过，隔离 Gate 0/live conformance 仍待完成。
- DSH 运行时 Node 要求：^22.19.0 || >=24.0.0（可移植项目核心仍为 >=22.12.0）。
- Node.js：>=22.12.0。
- 研究会话必须以 Read Only 权限启动；preset 会把审批收紧为 never（UI 显示为 Custom，这是预期的）。
- 建议使用独立 DSH_HOME 和非关键仓库副本首次试用。
- 当前版本：0.8.0-alpha.10，不承诺稳定 API。

先预览操作，不写入 preset：

npx -y github:TLNing260310/dsh-researcher#v0.8.0-alpha.10 --dry-run

确认后安装：

npx -y github:TLNing260310/dsh-researcher#v0.8.0-alpha.10

安装器默认不会覆盖已有 preset，并严格核对 DSH 版本。备份、升级、卸载、回滚以及从 GitHub Release 校验 SHA-256 后安装的完整流程见 安全安装与恢复。不要在不了解现有 preset 内容时使用覆盖选项。

路径 A：只读研究

1. 新建 DSH Web 会话，先选择 Read Only。
2. 再选择「项目研究 Project Research」。preset 会把 approval=ask 单向收紧为 never，因此 UI 显示 Custom。
3. 给出具体问题，而不是只说“看看项目”：

先运行 research_doctor。只读审阅本仓库，并用 path:line 证据回答：
1. 项目真正目的是什么？
2. 哪些架构约束不可改变？
3. README、实现和测试有哪些矛盾？
4. 下一项最值得验证的假设是什么？
无法验证的内容标记 UNKNOWN，不要写文件。

research_doctor 必须是首个工具调用；Runtime Certificate 不是 SAFE 时研究不会开始。切换到 writable 权限会撤销旧证书，并在下一次模型调用前拒绝继续。

真实 smoke 的结论并非“模型研究得很好”：发布包确实达到了 SAFE 并拒绝权限漂移，但早期本地模型也曾忘记任务、虚构 Rust 路径。这份完整记录见 DSH Web local smoke。alpha.7 候选又用 Qwen3 14B 与 DeepSeek R1 14B 做了两次本地探测：前者经纠正后仍未完成报告，后者的无证据报告被 terminal gate 拒绝。见 Project Research local-output smoke。它们证明安全门有用，同时反证了“SAFE 就等于研究质量已证明”。

两种研究入口

| 入口 | 生命周期 | 用途 |
| 项目研究 Project Research preset | 持续模式；环境级 read-only、approval never、无通用 shell | 完整或高风险项目研究 |
| /researcher | Governed Coding 中一次只读 turn，结束后自动退出 | 编码中临时核对事实 |

Governed Coding 还支持 /researcher on|off 持久 guarded mode。它有工具白名单保护，但不等同于独立 preset 的环境级只读证明。

路径 B：五分钟建立 Goal Contract

引导器一次生成 Project Cognition、Verifier Registry、Goal Contract 的待审核草稿和 REVIEW.md，并自动绑定当前 cognition hash、Git revision 与 verifier hash：

npx -y --package=github:TLNing260310/dsh-researcher#v0.8.0-alpha.10 project-cognition init .
npx -y --package=github:TLNing260310/dsh-researcher#v0.8.0-alpha.10 project-cognition quickstart --root . --out ../my-goal-review --goal-id fix-login-timeout

第一条只在项目尚未建立 .project-cognition/state.json 时执行；已有 canonical state 的项目直接运行第二条。命令均为单行，可直接用于 PowerShell 或 POSIX shell。

若无法从 package.json、Cargo.toml、pyproject.toml 或 go.mod 推断测试命令，则显式提供：

npx -y --package=github:TLNing260310/dsh-researcher#v0.8.0-alpha.10 project-cognition quickstart --root . --out ../my-goal-review --goal-id fix-login-timeout --verify-command "npm test"

省略 --verify-tool 时，Windows 默认 pwsh，Unix 默认 bash；只有 verifier 必须由其他宿主工具执行时才显式指定。

编辑生成的草稿后同步冻结引用：

npx -y --package=github:TLNing260310/dsh-researcher#v0.8.0-alpha.10 project-cognition quickstart sync ../my-goal-review --root .

引导器不会替你批准 Goal、seal 项目事实或安装 canonical state。打开生成的 REVIEW.md，审核目的、边界、MUST 条件、预算与 verifier 后，再执行其中列出的批准命令。完整说明见 五分钟 Quickstart。

批准后，在「目标治理编码 Governed Coding」中运行：

/researcher run .project-cognition/goals/.r1.json

什么算完成

- 每个 MUST criterion 都必须由冻结 verifier 或直接 human gate 证明。
- 最终 attempt 必须重新证明全部 MUST，不能继承旧 attempt 的成功。
- SHOULD 未完成不会成为继续消耗尝试的理由。
- baseline 已满足时返回 ALREADY_SATISFIED，不得为了显得有工作而修改代码。
- 达到尝试、时间、token 或连续无进展预算时返回 STOPPED。
- 合同、认知、权限或验证器漂移时返回 NEEDS_HUMAN。
- 模型不能写入或覆盖自己的终态；宿主从可信事件前缀复算决定。

Goal Contract v1 的 in_scope / out_of_scope / do_not_touch 当前是冻结的语义约束，不是通用文件路径 allowlist。E1 runner 对实验 fixture 的允许路径另有机械检查；通用 hard path enforcement 需要未来显式 schema，不在本版本能力内。

Project Cognition 如何防止架构漂移

.project-cognition/state.json 唯一 canonical 项目真相 .project-cognition/goals/.json 本次目标、边界、预算和完成条件 DSH durable session events 宿主观察到的真实执行 PROJECT_COGNITION.md 由 state.json 确定性生成的人类投影

Research Session Ledger 只保存候选 claims、假设和证据线索。模型不能把会话结论自动晋升为项目事实。唯一提升流程是：

session ledger → draft revision → owner review → seal → regenerate projection

这条边界刻意保留人工责任：自动生成草稿可以降低摩擦，但不能让同一个模型既提出事实、又批准事实、再依据自己批准的事实完成任务。

证据现状

| 层级 | 当前结论 | 它真正说明什么 |
| 单元、replay、集成与 package smoke | PASS | 哈希、revision、预算、人工 gate、伪证据拒绝、host completion 和隔离安装按设计工作 |
| project-cognition doctor . | PASS | canonical state、schema、hash、projection、Goal 与 registry 当前一致；不证明引用证据仍新鲜 |
| DSH Web Project Research smoke | PASS（运行时边界）；本地输出 probe FAIL | 精确发布 runtime 可达 SAFE 并拒绝权限漂移/未认证终态；两个本地 14B probe 未产出合格报告 |
| Goal Governor E1 infrastructure | v1.12 离线 READY；v1.5 与不完整 v1.6-v1.11 Live E1 均 INVALID | v1.11 的 resume 两进程完成但 candidate scorer scope 漂移；E1 live 已停止，不授权追加付费重试 |
| Experiment C+ | causal-invalid，永久保留 | 基础设施能运行，同时评测会拒绝 snapshot leakage 和伪正向结论 |

本地复核不会调用模型或网络：

npm run check
npm run demo
npm run adapter:discovery:check
npm run eval:e1:preflight

公开证明顺序固定为：Gate 0 → E1 → non-inferential pilot → E2 → second-adapter conformance → E3。轨迹、阈值和 invalidity rules 只以冻结的 Goal Governor Evaluation Protocol 为准，README 不复制实验定义。

不同客户端共享同一份可移植 HostEvent 与调用合同：单次 researcher.ask(...)、持续 researcher.mode.set/get(...) 与客户端原生命令最终进入同一个宿主状态机。包根导出的 adapterCore 仍是 experimental base envelope，不代表新客户端已经通过 governed conformance。

Claude Agent SDK 0.3.251 与 Codex App Server stdio 0.150.0-alpha.12.2 已建立版本锁定 discovery，但均为 HOLD。Codex 已有零模型握手 trace，并在隔离 CODEX_HOME 中重建完整 schema bundle 与 method inventory；Claude 的锁定 SDK 模块和随包 CLI 已真实加载，但没有创建会话，也没有 query/tool/resume trace。两者都没有形成安装入口、 adapter manifest 或兼容声明。

Live 模型成本边界

北京时间工作日 09:00,12:00)、[14:00,18:00) 禁止 DeepSeek 远程 API；这些时段只允许锁定到字面 loopback 地址的本地路由。其他时段和周末的远程 E1 也只能使用 official deepseek-v4-flash、精确 https://api.deepseek.com、完整 run lock、预算和显式费用确认。loopback 只证明第一跳在本机，不能证明本地服务没有再代理远程。

与 Plan、Spec 和 Memory 的区别

| 工具层 | 主要回答 |
| Plan / Tasks | 接下来准备做哪些步骤？ |
| Spec | 准备构建或改变什么？ |
| Memory | Agent 曾经学到了什么？ |
| Project Cognition | 关于项目现实的主张是什么，为什么相信，何时失效？ |
| Goal Governor | 什么状态算完成，谁有权证明，何时必须停止？ |

GitHub Spec Kit、OpenSpec、Kiro、Serena、Beads 和客户端自带 Plan/Memory 都可能是更合适的选择。本项目的差异仅在于“可失效的项目认知 + 宿主拥有的终态裁决”这一组合；每个单项能力都有成熟替代。详细边界见 [竞争与集成地图。

可移植性

Portable Core（Cognition / Goal / Verifier reducer、canonical JSON、schemas、CLI）不依赖 DSH。但客户端 adapter 只有机械证明以下能力后才能称为 governed：host-owned approval、hard stop/pause、durable ordered events、trusted verifier binding、project-root confinement。缺少任一项时只能称为 advisory。

当前只有 DSH adapter。Codex 与 Claude Code discovery 均为 HOLD；Kiro、OpenClaw 和 Zed/Zcode 仍只是候选。它们的 effect size 与 adapter 可行性仍是待验证假设，不是已交付兼容性。

仓库地图

| 入口 | 从这里得到什么 |
| 安全安装与恢复 | dry-run、安装、备份、卸载、回滚与制品校验 |
| 五分钟 Quickstart | 从任务描述到可人工审核的 Goal 草稿 |
| 项目介绍（英文） | 可复用的一句话、用户叙事、能力与诚实边界 |
| Validation Status | Validated / Unknown / Invalidated 的正式边界 |
| Project Cognition | 项目目的、不变量、已证/未证价值与下一证明 |
| 架构 | runtime、portable core、权限面和信任边界 |
| Goal Governor 指南 | 合同、验证器、状态机与完整 CLI |
| Cognition Governance | canonical truth、Session Ledger 与 promotion |
| E1 harness | run lock、成本准入、证据包和离线评分 |
| 失败与真实 smoke | 每轮运行结果、缺陷和不能推出的结论 |
| alpha.7 本地输出 smoke | 两个本地模型为何未产出可发布 Researcher 报告 |

反馈与安全

- 只试了十分钟也有价值：提交最短试用结果。
- 完整的有价值、无价值、误阻塞和错误 DONE：提交真实运行反馈。
- 自审校准案例与真实案例的准入边界见 Case Library。
- Bug 使用 issue template。
- 贡献前阅读 CONTRIBUTING.md。
- 安全问题按 SECURITY.md 私下报告。

Compatibility

- DeepSeek Harness：目标版本 0.1.5-rc.3（见 lib/runtime-requirements.js 的 VERIFIED_DSH）；不得在 Gate 0/live conformance 完成前写成“已经验证”。
- Node.js：>=22.12.0。
- 当前已发布版本：0.8.0-alpha.10；它发布时 Live E1 尚未运行。发布后的 v1.5 与不完整 v1.6-v1.11 根结果均为 INVALID；v1.12 仅作离线修正，E1 live 已停止；结果价值与多客户端可移植性仍为 NOT PROVEN。
- License：MIT。

致谢与致敬

研究模式的路线图——注意力路由、注入纪律、透镜库——不是从白纸开始的。DSH 生态中已有一批项目探索过这片区域，并且公开了他们的结论，其中还包括推翻了自己初版设计的实测结果。我们读了它们，采用了合适的部分，并在这里说明。

感谢并致敬以下项目的作者：

| 项目 | 我们学到了什么 |
| dsh-company-kb | 显式调用门禁（会话粘性 · 触发词 + 否定窗口 · 路径点名）——我们的第一级触发沿用同一原则。它的双 FTS5 + RRF 检索是我们检索层的参考实现。它的拒绝文本明确告诉模型不要反复询问，这是防注意力污染的第二道防线。 |
| dsh-experience-memory | 四表面模型（自动注入 / 无条件一行指引 / 维护 / 工具与命令），以及"够到库外的能力留在人类触发器之后"的纪律。它的 provenance audit——只标记、从不拒绝——决定了我们的透镜新鲜度规则。 |
| dsh-learn-wiki | 我们读到的最有用的一条结论：它的触发器从检索未命中改成了挣扎*，因为未命中信号太廉价（任何新话题都会未命中）。这条公开的负面结果推翻了我们的第一版触发设计。 |
| dsh-literature | 用专用 preset 承载专用工具集、其余场景一律不加载——我们作用域化研究入口沿用的组织方式。 |
| deepseek-harness | 本项目的运行时宿主。 |

另有两个项目仅影响了我们的思考——因其许可与本项目的 MIT 分发不兼容，未包含其任何代码、文本或数据：

- twiceshy（AGPL-3.0）——"绝不注入近似但错误的经验"这一原则，因为注入它会主动损害 agent；其记录结构 {症状, 适用范围, 根本原因, 防护测试} 与我们的六字段透镜 schema 独立收敛；以及推送 + 拉取的混合通道。
- dsh-context-mode（Elastic License 2.0）——以反证确认了我们的瓶颈是注意力落点，不是上下文容量。

治理层面的借鉴也明确致谢：把会改变能力的路径留在人类触发器之后、"标记"与"拒绝"的区分、以及公开负面结果而不是悄悄替换——这些纪律都来自上述项目。凡是我们做出不同选择的地方，都在设计文档里写明了理由。

完整许可全文见 licenses/；逐项目的署名与"接入 / 未接入"登记见 THIRD-PARTY-NOTICES.md。