【Agent Preset】dsh-researcher：只读项目研究模式 —— 先理解项目，再决定要不要动手

[TLNing260310]

一句话

一个只读的"项目情报" Agent 预设：把项目当文物读，产出证据分级、逐条可复核的诊断报告；结论可以是"暂不建议行动"。定位是 Research → Plan → Code 的上游。

仓库：https://github.com/TLNing260310/dsh-researcher （MIT · DSH 0.1.0-rc.6 已验证挂载）

使用场景

• 项目迷茫期：写了一个月，不知道它现在到底是什么、值不值得继续。
• 接手陌生项目：真正看懂一个 repo，而不是跟着 README 的声称走。
• 长期项目漂移：现在的实现和最初目标是不是已经偏了。
• AI 连续代写之后：Codex / Claude / DSH 替你写了一星期，你需要恢复"全局理解"。
• 开源项目评估：成熟度、风险、竞品位置、可接入的其他开源项目。

优点

1. 零修改保证，不靠提示词：write/edit 被 per-agent 永拒桩替换、tool-fs 注入的写指引段被同段名遮蔽、沙箱 read-only、审批 never——四层机制，"写代码"根本不进入模型的行为语义空间；会话前后 git status --porcelain 一致可验。
2. 证据分级认识论（C0–C4）：README 说做到 ≠ 代码实现 ≠ 测试证明 ≠ 运行观察 ≠ 外部复现。每条结论要么带 file:line/URL 引用，要么标注"未验证（研究者推断）"；报告含完整 claim 台账（Claim / Status / Evidence / Missing evidence / Confidence）。
3. 把仓库放回现实世界：强制外部调研（papers / competitors / standards）+ 重点查找 GitHub 可复用项目（集成/组合/替代手写部分，附 stars/许可证/活跃度）+ 竞品矩阵。
4. 结论是诊断，不是计划："Recommended action: NONE" 是一等结论（附行动前必须补的实验/反馈/对比）；需要行动时给出 WHAT 与辩证权衡的候选方案，并输出一份粘贴即用的交接包，无缝交给 Plan Mode。
5. 省 token：不存在"想写→被沙箱拒→重试→审批"的回轮；写工具的 schema 与指引段全部换成永拒声明，注意力预算全部分配给"读"。

快速开始

git clone https://github.com/TLNing260310/dsh-researcher.git
cd dsh-researcher
.\install.ps1   # macOS/Linux: ./install.sh

新建会话 → 预设选「项目研究 Project Research」→ 权限 read-only + 审批 never → 发送"仓库说明 + 当前状态 + 你的困惑"。

状态

机制经 standingKeyFor 挂载校验与源码级验证；欢迎在真实仓库上端到端试跑反馈（验收清单见仓库 README）。

[TLNing260310]

v0.2.0 已发布（Build-Shaping 升级，受 AI Engineering Skills Map 框架启发）：

1. 项目模型重建：Mission / User / Problem / Value mechanism / Architecture / Current state / Evidence / Constraints——先建立 world model，再发表意见。
2. 证据台账增加裁决态：Known / Likely / Claimed / Unknown / Contradicted——杜绝"把作者意图当项目现实"。
3. Tradeoff Scanner：12 维度扫描（cost/performance/reliability/security/privacy/…/lock-in），不默认"更多工程 = 更好"——"SQLite 不够 scalable"的正确答案可能是"当前阶段 SQLite 正合适"。
4. Problem-Before-Solution 链：禁止"发现问题 → 提议功能"跳跃；每个问题先回答"它造成什么用户/业务问题、有多严重、有证据吗、值得现在干预吗"。
5. BUILD / DON'T BUILD / INVESTIGATE 分类：每个主要发现三选一收束；INVESTIGATE（"不知道"）是合法且优质的输出，禁止"研究完必须给几个改进建议"的反射。
6. 反证检索（disconfirmation search）：初始假设 → 主动搜索"什么证据会让我的判断是错的" → 修正假设。
7. 研究自查清单：研究者自身也运行 10 项 verifier（是否只看了 README？是否把 bug 当设计选择？是否提议了没有需求证据的构建？……）。

定位从"迷茫时看看"升级为：重大开发方向进入 Plan 之前的决策层（Shaping the build）。只读边界保持不变——能修复所见的 Agent 会滑向修复（goal drift），本模式被制度性禁止执行，token 全部花在理解、怀疑、比较与判断上。

仓库：https://github.com/TLNing260310/dsh-researcher （tag: v0.2.0）