dsh-researcher

1. Project Introduction — 项目介绍

EN — Evolving toward a Project Cognition Infrastructure for AI Software Engineering.
中文 — 正在向 AI 软件工程项目认知基础设施方向发展(演化中,不是已完成的基础设施)。

EN — dsh-researcher is an AI project-cognition research tool and a Project Cognition Infrastructure prototype. It builds an evidence-backed model of a software project — its purpose, architecture, constraints, risks, and change impact — before any code is changed, and persists that cognition across sessions.

中文 — dsh-researcher 是 AI 项目认知研究工具与 Project Cognition Infrastructure 原型。它在动手修改之前,建立一份基于证据的软件项目认知模型(项目目的、架构、约束、风险与修改影响),并让这份认知跨会话持续存在。

第一眼定位 / First-glance positioning:

• ✅ 是 / It is:项目认知研究工具 · Project Cognition Infrastructure 原型 · AI 编码时代的项目理解层
• ❌ 不是 / It is not:AI chatbot · 普通 repository analyzer · 更强的 Research Agent(优越性未验证)· 已完成的基础设施

EN — The problem is not that AI can't write code. It's that AI can modify code quickly while not knowing why the project was designed this way. Local correctness does not guarantee global correctness.
中文 — 问题不是 AI 不会写代码,而是 AI 可以快速修改代码,却不知道这个项目为什么这样设计。局部正确不保证全局正确(米格-25 效应)。

2. Why This Exists — 为什么需要它

传统 Agent 的工作方式 / Traditional agents:

read repository
    ↓
generate answer
    ↓
forget(会话结束,上下文丢弃 — context discarded at session end)

dsh-researcher 的工作方式 / dsh-researcher:

observe project
    ↓
build cognition state(claims/evidence/依赖图,版本化)
    ↓
maintain understanding(证据锚定,局部失效)
    ↓
continue future reasoning(export/import 跨会话迁移)

EN — AI coding tools have made implementation cheap, but software development has another bottleneck: understanding the whole system. A single change may be correct; a hundred correct changes may still create architectural drift, outdated assumptions, and loss of original intent. The structural problem is that agent cognition is session-local: each session re-derives what the previous one already learned. dsh-researcher separates the production of cognition (Research Mode) from the carriage of cognition (Infrastructure) — the research direction, not a completed product.

中文 — AI 编码工具让实现变得廉价,但软件开发还有另一个瓶颈:理解整个系统。一次修改可能是正确的;一百次正确的修改仍可能累积出架构漂移、过期假设与最初意图的丢失。结构性问题是 agent 认知是会话局部的:每次会话重新推导上一次已学到的东西。dsh-researcher 将认知的生产(Research Mode)与认知的承载(Infrastructure)分离 —— 这是研究方向,不是已完成产品。

3. Architecture Overview — 架构总览

dsh-researcher — Project Cognition System(演化中 / evolving)
    |
    +-------------------------------------------+
    |                                           |
Infrastructure Layer                      Application Layer
Project Cognition Infrastructure          Research Mode
  - cognition-state                       - repository research
  - claims graph                          - architecture analysis
  - evidence anchors                      - risk analysis
  - dependency tracking                   - decision support
  - revision tracking                     - handoff
  - export / import migration
  - evaluation governance

EN — Application consumes Infrastructure; the two layers must not be conflated. Research Mode (the application layer) produces cognition through the eleven-stage pipeline and research_checkpoint; the Infrastructure layer carries it: a versioned, dependency-carrying state machine with evidence anchors, revision history, cross-session export/import migration, and evaluation governance. The application layer's superiority over ordinary agents is not yet validated; the infrastructure layer's engineering capability is validated (see §4).

中文 — Application 消费 Infrastructure;两层不可混淆。 Research Mode(应用层)通过十一阶段管道与 research_checkpoint 生产认知;Infrastructure 层(底层)承载认知:版本化、带依赖的状态机,含证据锚、修订历史、跨会话 export/import 迁移与评测治理。应用层相对普通 agent 的优越性尚未验证;基础设施层的工程能力已验证(见 §4)。

Research Mode 输出 / Output:Project Cognition Report(7 节用户层 + AI 内部层附录:Evidence Ledger / Claims / Confidence / Certificate / Checkpoint State)+ Decision Memo(BUILD / DON'T BUILD / INVESTIGATE)+ research_handoff.json。

4. Validation Status — 验证状态表

依据:Experiment A(commander.js,12 runs)+ Experiment C+(cognition-state inheritance,12 runs)。完整结论:docs/evaluation-cplus-conclusion.md。

✅ Validated(已验证 —— 基础设施层)

❌ Invalidated / Not Admissible(已证伪或不可采信)

❓ Unknown(未知 —— 需后续实验)

5. Experiment C+ Honest Result — 诚实结论(含漏洞披露)

Experiment C+ — Cognition-State Inheritance(2026-08,commander.js,6 mutations × (A stateless / B inherited)):

• Validated:状态注入管线可运行(6/6 B-runs G2 PASS:importState + export:true 验证);跨会话认知迁移技术上可行(B-runs 展示证据锚定的旧认知失效,成本 0.93×);评测系统能检测完整性问题(抓住 QUOTA 失败)。
• Invalidated:snapshot isolation leakage —— T1 快照建于 commander.js-cplus-t1/,与原始 T0 同级;只读沙箱允许读 workspace 之外,5/6 A-runs(和 2 个 B-runs)读取了 sibling mutation 目录或原始 T0,获得外部 ground truth。因此 Mutation Recall 的 A/B 比较不成立,Researcher 优越性结论不成立。 本问题不隐藏。
• 失败记录(QUOTA 中断 7 runs)与泄漏记录全部保留 —— 失败是可信度资产。

完整结论与剩余验证路径(R1 隔离重跑 / R2 机制隔离 / R3 长期维护):docs/evaluation-cplus-conclusion.md。实验产物:evaluation/results/experiment-cplus/。

6. Roadmap — 路线图

详见 docs/roadmap.md。每阶段由前一步结果裁决;失败保留为反例资产。

Trust — 为什么相信它：Research Runtime Health Gate

EN — Many agents claim to be safe. Researcher proves its operating conditions.
中文 — 很多 Agent 声称自己安全。Researcher 证明自己的运行条件。

Researcher Runtime Certificate
Run: #1
History: none (first run)
Preset:        PASS   (composedPreset=researcher)
Sandbox:       PASS   (mode=read-only)
Approval:      PASS   (policy=never)
Write tools:   PASS   (write/edit = refusing stubs)
Shell surface: PASS   (git_read only; no pwsh/bash)
Checkpoint:    PASS
Replay:        PASS   (log folds deterministically)
Overall: SAFE

EN — The certificate is an enforced first step: every other tool is refused by the health gate until it is produced; in a bad environment the certificate still renders UNSAFE as the explanation. Every run is numbered with history (Run #N + History: #1 SAFE · #2 DEGRADED), every report starts with the certificate block — Researcher itself is an auditable system (see docs/runtime-certificates/).
中文 — 证书是执行级强制首步：在它产出之前，其他一切工具被健康门禁拒绝；环境不达标时证书照常渲染 UNSAFE 作为解释。每次运行可编号、带历史（Run #N + History: #1 SAFE · #2 DEGRADED），每一份报告以证书块开头——Researcher 自己也是可审计系统（见 docs/runtime-certificates/）。

Proof — 证明：Benchmark Suite

EN — Three public, reproducible synthetic cases with ground truth and a scorer — the moat: anyone can write a research prompt; we publish an evaluation standard.
中文 — 三个公开、可复现的合成案例（带 ground truth 与打分器）——这是第一道护城河：别人可以写 Research Prompt，我们提供公开评测标准。

node fixtures/benchmark/benchmark-runner.js generate <dir>
node fixtures/benchmark/benchmark-runner.js score <case-dir> <report.md>

（marker 打分是下限，证据引用与证书由人工复核。/ Marker matching is a floor; citations and the certificate are human-reviewed.）

Historical Blind Benchmark — Phase A（范围声明，不是广告）

EN — The first real-world blind evaluation (pallets/flask @ 2025-11-17, 4 modes × 3 runs, deepseek-v4-flash, full protocol in docs/evaluation-protocol-v1.md) is published as-is in evaluation/cases/flask/evaluation-result.md. The honest summary:
中文 — 第一次真实仓库盲测（pallets/flask @ 2025-11-17，4 模式 × 3 次，deepseek-v4-flash，完整协议见 docs/evaluation-protocol-v1.md）原样公开在 evaluation/cases/flask/evaluation-result.md。诚实的结论：

EN — What the experiment proved: structured project understanding (claims ledger, evidence tiers, architecture mapping, risk analysis, handoff, certificate) — what ordinary agents do not natively produce. What it did not prove: prediction of specific future bugs. The benchmark suite is being extended with Understanding / Risk / Change Impact / Drift benchmarks (see docs/evaluation.md).
中文 — 实验证明的：结构化项目理解（claims ledger、证据分级、架构映射、风险分析、交接包、证书）——普通 Agent 不天然具备的能力。实验没有证明的：预测具体未来 Bug。评测套件正在扩展 Understanding / Risk / Change Impact / Drift 四个基准（见 docs/evaluation.md）。

How it works — 工作原理（三层 / three layers）

Layer 1 — Understand 理解：Repository → Code / Docs / History / Tests / Issues / External context → Project Model（项目身份 / 架构地图 / 核心组件 / 设计决策）
Layer 2 — Judge 判断：Claim → Evidence → Confidence → Contradiction → Risk Map（证据分级 evidence tiers C0–C4 + 裁决态 verdicts Known/Likely/Claimed/Unknown/Contradicted；风险 = "这里未来容易错"，不是"这里错了"）
Layer 3 — Guide 引导：Risk Map → Decision Memo（BUILD / DON'T BUILD / INVESTIGATE） → Plan Mode

十一阶段管道 Pipeline：DISCOVER → RECONSTRUCT → EVIDENCE MAP → DIAGNOSE → TRADEOFF ANALYSIS → EXTERNAL RESEARCH → COMPARE → CHALLENGE → SHAPE → CLASSIFY → SELF-EVAL → HANDOFF。The pipeline is linear in execution but stateful in reasoning. 执行是线性的，推理是有状态的。

Non-goals — 明确不做什么

Researcher is NOT：

• ❌ 一个 Coding Agent（它从不修改代码）/ a coding agent (it never modifies code)
• ❌ 自动重构工具（它只诊断，不执行）/ an automatic refactoring tool (it diagnoses, it does not execute)
• ❌ Bug 预测器（未来 issue 召回 0/60 是范围声明）/ a bug predictor (0/60 future-issue recall is the scope statement)
• ❌ AI 架构师（它提供架构师式的理解流程，不承诺最优架构决策）/ an AI architect (it offers architect-style understanding, not architecture decisions)
• ❌ 通用网页调研器（它面向代码仓库，不是 Deep Research）/ a general web researcher (it targets code repositories, not web deep research)
• ❌ 架构分析工具的替代品（GitNexus / Serena / RepoMap 等 L0/L1 能力应被整合，见 docs/landscape.md）/ a replacement for architecture tools (integrate L0/L1 instead)

它负责 It does：✅ Understanding 理解 ✅ Evidence 证据 ✅ Risk Discovery 风险发现 ✅ Decision 决策依据。

Install — 快速安装

npx -y github:TLNing260310/dsh-researcher

EN — One line (no clone, no npm publish) installs into ${DSH_HOME}/.agent-presets/researcher; --force overwrites. Alternatives: git clone + install.ps1/sh, or Download ZIP and copy manually.
中文 — 一行安装（无需 clone、无需 npm 发布），装进 ${DSH_HOME}/.agent-presets/researcher；--force 覆盖更新。备选：git clone + install.ps1/sh，或 Download ZIP 手动复制。

EN Usage — New session → preset「项目研究 Project Research」→ permission read-only + approval never → the first tool call is automatically research_doctor (Runtime Certificate) → research after SAFE; the final report starts with the certificate block and ends with the handoff package.
中文 使用 — 新建会话 → 预设选「项目研究 Project Research」→ 权限 read-only + 审批 never → 第一次工具调用自动是 research_doctor（Runtime Certificate）→ SAFE 后开始研究，最终报告以证书块开头、以交接包结尾。

Docs — 深入文档

社区索引约定 Community index convention：以 GitHub topic dsh-plugin 打标；内置市场提案见 / marketplace proposal: deepseek-harness#2994。

Compatibility — 兼容性

EN — Verified on DeepSeek Harness 0.1.0-rc.6; on other versions the guard fails closed (refuses to start rather than degrading silently).
中文 — 已验证 DeepSeek Harness 0.1.0-rc.6；其他版本守卫 fail-closed（拒绝启动而非静默退化）。

License

MIT © 2026 TLNing260310