EveGoodEvening/dsh-autoresearch

dsh-autoresearch

面向 DeepSeek Harness 的有界、指标驱动的自动研究插件。

dsh-autoresearch 为 DeepSeek Harness agent 提供单一工具 —— autoresearch —— 它在隔离的 Git worktree 内运行一个基线优先、有界的保留/拒绝优化循环。

该设计灵感来自 Karpathy 的 autoresearch：一种提议 → 编辑 → 运行 → 度量 → 保留/回退的搜索，其中编码 agent 提出候选方案，而固定的机械指标作为事实来源。受信任的 Host 配置选择评估器；Host 代码负责评估、指标决策、持久化、取消和恢复。提议模型不能提交评估器命令、指标定义、数据集权威或评估器环境。

- 单一标量指标。 针对已度量基线的严格 minimize / maximize 改进；没有隐藏的平局决胜规则或单独的复杂度评分。
- Host 选择的评估器。 新运行通过 evaluator_id 指定一个部署注册；不可变的 argv、指标、环境、评估器文件和数据集身份会被持久化，并在基线、候选和恢复时重新校验。
- 狭窄的可变表面。 只有 mutable_globs 路径可以更改；已注册的评估器和本地数据集文件即使在宽泛的 glob 下也保持受保护。
- 持久化的 SQLite 证据。 每次运行、实验、尝试和有界产物记录都经过状态转换检查并绑定哈希。
- 默认后台作业。 运行是 dsh-jobs 后台作业；使用通用作业工具检查或停止它们。
- 故障关闭式恢复。 恢复会在变更或生成评估器之前，协调持久化的 Host 证据。

要求

- Node.js ^22.19.0 || >=24.0.0（使用 node:sqlite）
- pnpm 11.7.0
- DeepSeek Harness 0.1.1-rc.2；此开发者预览集成会针对每个受支持的 DSH 版本重新测试并重新固定。
- Host 必须提供 agents、jobs、subprocess、systemPrompt 和 tools。后台模式还要求调用 Agent 挂载 dsh-tool-jobs；Web standard Agent 预设以及 base/headless 组合都会这样做。不需要 Host 全局的 job_ 工具。

自动接管因 Host 异常死亡而遗留的控制器声明，需要 Linux /proc//stat 启动令牌证据。正常受管执行并未声明仅限 Linux，但在非 Linux 系统上，过期声明会保守地保持阻塞；仅凭租约到期并不能证明其所有者已死亡。

安装

通过 DSH 的 profile 插件管理器安装已发布的包：

dsh plugin --profile  add dsh-autoresearch
dsh --profile  --dump-config

dsh plugin 会将包规格转发给所选 profile 内的 pnpm，然后将声明了 dsh.bundle 的已安装包添加到该 profile 的有序 bundle 列表中。单纯的 pnpm add 不会执行该 DSH 协调。
对于从当前检出进行类似发布的安装，请构建并安装由 pnpm pack 生成的产物（文件名由 package.json 派生）：

pnpm install --frozen-lockfile
TARBALL=$(pnpm pack --silent)
dsh plugin --profile  add "./$TARBALL"
dsh --profile  --dump-config

对于本地开发，改为安装指向已构建检出的链接：

pnpm install --frozen-lockfile
pnpm run build
dsh plugin --profile  add .
dsh --profile  --dump-config

DSH 会将诸如 . 和 pnpm pack 输出的路径等相对文件系统规格锚定到你调用 dsh 时所在的目录。配置转储应包含 id: autoresearch 和 name: dsh-autoresearch。

该包附带一个 Cordis 补丁行（cordis.patch.yml），通过 package.json 中的 dsh.bundle.patch 声明。DeepSeek Harness 的树外功能以可选加入的 bundle 形式发布：稳定补丁会插入一个普通的 Cordis 插件行，其配置会被整体替换，而非深度合并，因此你想要的每个默认值都必须在补丁行中显式声明。

工作原理

┌─────────────┐  proposal   ┌──────────────────┐  evaluator id  ┌──────────────────┐
│  proposal   │ ─────────► │ AutoresearchRun  │ ─────────────► │ Host registration│
│   agent     │ ◄───────── │    Controller    │ ◄───────────── │ + managed argv   │
└─────────────┘  memory     └────────┬─────────┘     metric     └──────────────────┘
│ persist
▼
┌──────────────────┐
│  DurableTracker  │  SQLite; current schema authority:
└──────────────────┘  TRACKER_SCHEMA_VERSION in src/tracker.ts

1. 基线。 控制器检出不可变的起始提交，解析 Host 注册，为已注册的本地评估器/数据集文件派生哈希，并测量基线。无基线 → baseline-blocked。
2. 提议。 一个被委派的提议 agent（继承的工具：read、write、edit、glob、grep）仅编辑 mutable_globs，并提交一条有界的、不受信任的注解。后续的提议提示会收到有界的研究记忆：截断的子假设/摘要，加上 Host 派生的提交、变更路径/差异统计、指标、决策和失败事实——而非完整日志或补丁。仅精确配置的机密值会被脱敏；所有子注解仍必须被视为可能敏感的不可信数据。
3. 评估。 检出候选提交，并通过托管的 ctx.subprocess 提供程序运行已注册的无 shell argv。对于每次尝试，不可变的注册以及运行创建时的评估器/本地数据集清单会在提供程序启动前后立即重新验证。
4. 决定。 配置的标量指标相对于当前最佳值严格改进 → accept；否则 reject。constraints 是不可变的、哈希绑定的提案指导。它们不是 Host 强制执行的简单性标准、复杂度字段、权威报告字段或接受平局决胜项。将所需的简单性编码到受信任的评估器/目标或可变路径策略中。
5. 继续或停止。 已证实的静默候选超时、非零退出、信号、输出限制失败、指标协议失败或提供程序生成失败会被记录，消耗该候选序号，恢复已接受的工作树，并允许下一个有界候选。基线失败、取消、不确定的进程状态、策略/来源/注册违规、持久化或 Git 矛盾以及耗尽的恢复重跑会停止或阻止运行。
6. 持久化与重放。 每次转换都会写入 SQLite 跟踪器。取消会记录并重放取消前的精确运行状态（lastState）和规范谱系；恢复不会推断替代的起始状态。

运行时权威位于 AutoresearchRunController（src/controller.ts）；它组合了现有的 agents、jobs、subprocess、systemPrompt 和 tools 服务——没有单独的工作流引擎或子代理服务。

信任与隔离边界

Host 选择的评估器注册和受管理的 DSH 子进程提供程序是受信任的。插件管理精确的 argv、封闭的评估器环境、有界的 stdout/stderr 捕获、每次尝试的墙钟超时、取消、进程树终止和静默检查。它不使用单独的 DSH 沙箱接缝，也不提供针对恶意代码的文件系统、进程、同 UID、权限或网络隔离。隔离的 Git 工作树保护仓库状态；它不是操作系统安全边界。

不要基于此插件的强度运行恶意的评估器或候选代码。需要该属性的部署必须单独选择并验证外部沙箱或只读执行提供程序。对该更广泛威胁模型的一手支持需要明确的产品变更，定义并测试沙箱/部署契约。

超时是安全看门狗，不是固定步数、轮次、CPU/GPU 时间、FLOPs 或精确的公平计算预算。可比较的计算方法属于受信任的评估器，并通过用于基线、候选和恢复的冻结注册保持一致。

autoresearch 工具

由 src/index.ts 中的 apply() 注册。默认作为后台作业运行；设置 mode: 'foreground' 以阻塞调用者直到完成。

| 参数 | 必需 | 描述 |
| --- | --- | --- |
| repository | 否 | 仓库或 cwd；默认为发起代理的 cwd。 |
| objective | 是 | 不可变的优化目标。 |
| mutable_globs | 是 | 提案代理可以编辑的窄相对路径/glob。 |
| run_tag | 新运行 | 全新的 Git 安全排除标签；与 evaluator_id 一起为必填项，恢复运行时禁止使用。 |
| evaluator_id | 新运行 | 宿主提供的评估器注册 ID；与 run_tag 一起为必填项，恢复运行时禁止使用。 |
| resume_run_id | 恢复 | 持久化运行 ID；与 run_tag 和 evaluator_id 互斥。存储的注册信息和策略仍为权威来源。 |
| constraints | 否 | 不可变的、哈希绑定的建议性提案指导；不是接受规则。 |
| timeout_ms | 否 | 每次尝试的挂钟看门狗，受部署策略约束。 |
| max_experiments | 否 | 该运行的不可变候选上限；基线单独计算。 |
| target | 否 | 有限停止阈值。 |
| mode | 否 | 仅执行分派：background（默认）或 foreground；恢复运行时可以更改。 |

评估器命令、参数、cwd、环境、指标名称/方向、评估器文件以及数据集注册均属于 evaluatorRegistrations 下的部署配置；它们有意不出现在工具输入中。新运行会在恰好起始提交处冻结规范化注册信息，并对其隔离工作树中的本地文件进行哈希。本地数据集声明仓库文件；外部数据集提供算法限定的不可变摘要。如果当前宿主注册信息、持久化指纹或冻结字节不一致，恢复会在生成前以失败关闭方式终止。

输出 是带判别标签的 JSON：background（运行 + 作业已启动）、background-start-failed 或 foreground（完整运行结果）。运行结果包含 status、counts、best、artifacts 和阻塞项 evidence。

规范运行 JSON 的验证独立于 maxResultChars；该设置仅适用于渲染后和后台作业的呈现。

配置

Config 模式（src/config.ts）在部署时加载。默认值（也在 cordis.patch.yml 中）：

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| gitExecutable | git | Git 二进制文件。 |
| stateRoot | dsh-autoresearch | 跟踪器 + 工作树状态目录。 |
| branchPrefix | autoresearch/ | 运行分支前缀（必须以 / 结尾）。 |
| defaultMaxExperiments | 20 | 默认候选上限；基线单独计算。 |
| maxExperiments | 100 | 配置的部署最大候选上限（随附默认值，并非通用代码常量）。 |
| maxHandoffChars | 16384 | 序列化有界研究记忆交接的最大值。 |
| defaultTimeoutMs | 900000 | 每次尝试 15 分钟挂钟看门狗。 |
| maxTimeoutMs | 3600000 | 每次尝试配置的最大看门狗。 |
| terminationGraceMs | 5000 | 终止评估器进程树前的宽限期。 |
| maxActiveRunsPerRepository | 1 | 每个仓库的并发运行上限。 |
| maxStdoutBytes / maxStderrBytes | 1048576 | 评估器输出捕获限制。 |
| maxResultChars | 16384 | 渲染工具和后台作业呈现限制；规范运行结果不受影响。 |
| artifactRetentionDays | 30 | 产物字节保留窗口，对安全终态运行惰性执行。 |
| retainFailedArtifacts | true | 如果为 false，在安全终态结算时清除失败尝试的字节。 |
| retainWorktrees | true | 保留终态工作树；false 启用终态清理。 |
| cleanupWorktreesOnSuccess | false | 在 retainWorktrees: false 时，将清理限制为 target-reached / budget-limited。 |
| exportTsv | true | 每次运行导出一个 TSV 摘要。 |
| evaluatorRegistrations | [] | 宿主拥有的评估器、指标、环境、冻结文件和数据集契约，可通过 evaluator_id 选择。 |
| tsvRetentionDays | 30 | TSV 保留窗口，从导出文件的 mtime 起算。 |

运行是有界的。随附默认值为 20 个候选实验，随附部署最大值为 100；每个可安全继续的候选失败消耗一个序号。基线是独立的，目标、取消、阻塞条件或候选上限耗尽都可能提前停止。没有无限模式或自动运行链；操作员可以显式启动另一次运行。

保留是仓库本地的且惰性的：每次控制器启动都会清扫没有活跃控制器所有者的安全终态运行，并且每次安全终态结算都会对当前运行应用相同策略。修剪会移除产物字节，但保留 SQLite 产物标识、大小、哈希和结果元数据，以便终态重放保持确定性。retainWorktrees: false 会移除每个安全终态工作树，除非 cleanupWorktreesOnSuccess: true 将移除范围缩小到成功的终态状态。

项目布局

src/
index.ts            Plugin entry: registers the autoresearch tool + direct-human guidance
controller.ts       AutoresearchRunController — sole owner of the run state machine
config.ts           Config schema, defaults, run-policy normalization
types.ts            Tool parameters, output schema, durable state types
evaluator.ts        Shell-free evaluator boundary, provenance freezing, final-line JSON metric
git.ts              Worktree/lock/claim/commit reconciliation, candidate validation
tracker.ts          DurableTracker — SQLite; TRACKER_SCHEMA_VERSION is authoritative
recovery.ts         Crash-safe run reconciliation from durable state
agent.ts            Delegated proposal agent + autoresearch_report tool
render.ts           Tool result rendering with bounded truncation
invariant.ts        Package invariant companion (dsh-invariants)
state-layout.ts     SQLite state layout
retention.ts        Lazy artifact/TSV retention sweeps and current-run pruning
evaluator-artifacts.ts  Evaluator stdout/stderr artifact capture

旧版运行
在 Host-registration 契约之前创建的运行会作为历史证据保留，绝不会被自动转换或重新解释为满足当前 Host-registration 契约。普通的 SQLite tracker schema 迁移在保留期间或其他可写维护期间仍可能发生；这些迁移不会创建评估器注册，也不会授予恢复权限。遗留的终端运行仍可检查，并有资格进行正常的保留处理。尝试恢复遗留的非终端运行会以 legacy-evaluator-policy-unsupported 失败关闭；请检查其 tracker/artifacts，根据操作员策略保留或归档它们，然后如果实验应继续，则使用 run_tag 和 Host 提供的 evaluator_id 显式启动新的运行。

开发

pnpm install
pnpm run typecheck      # tsc --noEmit
pnpm run test           # vitest run
pnpm run test:coverage  # vitest run --coverage
pnpm run build          # tsc -p tsconfig.json → lib/
pnpm run check          # typecheck + test + build
pnpm run release:smoke  # packed-artifact release verification

发布验证会在检出目录之外运行打包产物：检查 allowlist，在不使用本地链接的情况下安装，导入生成的 ESM/声明，安装/转储真实的命名 dsh profile，并启动实际的 Web profile 足够长时间以获取其 HTML 界面。集成测试套件另外通过 Web standard Agent preset 执行 autoresearch，并使用 owner 作用域的 job_ 控件。

许可证

MIT © 2026 EveGoodEvening