人在环规划 Optim-Agent/dsh-plans

dsh-plans

面向 [DeepSeek Harness]（DSH）的人在环路规划预设：改代码之前先产出经过调研、打磨的 Markdown 计划，显式交接之后再按目标驱动执行。

把一份粗略的仓库改动请求，变成 ./dsh-plans/ 下可追溯的计划；用 reviewer 或 criticizer 子代理多轮打磨这份计划；再把通过的计划交给一个持久 DSH 目标，由它驱动实现，直到计划的 Verifier Checklist 全部通过。整套流程都跑在 DSH 原生机制上——ask_user_question、子代理、目标循环、内置技能——不需要额外的执行引擎。

一次运行怎么走

1. 智能体先只读检查目标仓库，然后问一次工作区的语言设置（之后该工作区每次运行都沿用这个设置）。
2. 规划问题一次问一个，用标准选项格式（推荐项排第一，Other 排倒数第二，Auto-complete 排最后）；每个问题和回答都记进 DECISIONS.md 和运行台账。
3. 强制的最终范围确认把住初稿这一关：dsh-plans/YYYY-MM-DD-topic/PLAN_v1.md，带稳定 ID、证据，以及 ## Verifier Checklist。
4. 每个计划版本之后都问一次打磨模式——用户（或 Auto-complete）没选，reviewer 或 criticizer 就不会跑。reviewer 和 criticizer 子代理走预设自带的 run_plan_subagent 工具：天生只读，模型在该角色首次使用时选定。
5. 打磨收敛之后，问一次显式的执行交接问题，且不允许 auto-complete：现在就把计划作为 DSH 目标执行，还是规划完就停。
6. 批准之后，执行作为一个 DSH 目标运行，目标指向通过的计划及其 Verifier Checklist。实现遵循 ponytail 简化纪律和 MVP 最小测试集，只有每个清单项都通过才调用 update_goal complete。

内置技能

五个技能，由智能体按每次请求挑选：

| 技能 | 什么时候用 |
| create-a-small-plan | 小范围仓库改动，需要 1 到 3 个规划问题。推荐打磨方式：一轮 criticizer，然后接受并执行。 |
| create-a-plan | 范围广或有风险的改动，需要 5 到 10 个规划问题加网络调研。推荐打磨方式：一轮 reviewer，再一轮 criticizer，然后接受并执行。 |
| create-a-big-plan | 开放式或高风险的工作，需要 10 个以上规划问题加网络调研。推荐打磨方式：三个 reviewer 并发跑一轮，由主智能体汇总，再一轮 criticizer，然后接受并执行。 |
| diagnose-before-plan | bug、CI 失败、回归、事故、RCA 或行为异常，需要先诊断再规划。 |
| reference-before-plan | 下载的项目、文章、论文或文档，必须先分析，规划选择才安全。 |

工作流保证：
- 每个工作区，在第一个规划问题之前会询问一次语言设置，并持久保存。
- 每个角色，reviewer / criticizer / executor 的模型只在该角色首次实际使用时询问一次，并持久保存。reviewer 和 criticizer 子进程通过预设自带的 run_plan_subagent 工具运行（运行时选择模型；写工具、目标工具、用户提问和委派工具对子进程禁用）。executor 就是当前会话的目标循环，因此它确认的模型就是会话模型。
- 一次只问一个规划问题；最终范围确认是 PLAN_v1.md 的闸门。
- 每个计划版本之后，都要问一次细化模式问题——没有这个问题，reviewer 或 criticizer 绝不运行。
- 细化之后，明确问一次执行交接问题，不自动完成：现在就把计划作为 DSH 目标执行，还是规划完就停。
- 执行时作为 DSH 目标运行，遵循 ponytail 简化纪律和 MVP 最小测试集，让 token 开销与工作量成正比。

安装

mkdir -p ~/.dsh/.agent-presets
git clone https://github.com/Optim-Agent/dsh-plans.git ~/.dsh/.agent-presets/dsh-plans

名单每次读取都会重新扫描根目录，所以新预设会立刻出现在预设选择器里——新建会话时选 dsh-plans 即可（无需重启）。然后在任意目录下提问：

Create a plan for <your change>

用 git -C ~/.dsh/.agent-presets/dsh-plans pull 更新已有安装。

Code Mode 要求

dsh-plans 通过 DSH Code Mode（run_code 加上生成的 TypeScript SDK）呈现所有工具。这样能避开某些模型的原生函数 schema 不兼容问题——这些模型会给每个可选 Bash 参数都填值，同时原始 Bash 实现、沙箱升级检查、审批、后台任务和取消行为都保持不变。

宿主必须提供 codeRuntime；DSH Web 配置档已经加载 dsh-code-runtime-worker-thread。没有 code runtime 的配置档在挂载预设时会明确报错，而不是退回不兼容的 Native 工具呈现方式。智能体组装时呈现方式就固定了，所以更新后请新开一个 dsh-plans 会话。通常不需要重启整个 DSH 服务，已有会话也不会热迁移。

运行时布局

公开产物留在工作区里，随时可以提交：

dsh-plans/YYYY-MM-DD-topic/
DECISIONS.md
PROBLEM_ANALYSIS.md # diagnose-before-plan only
REF_ANALYSIS.md # reference-before-plan only
PLAN_v1.md
PLAN_v1_reviewer_comments.md
PLAN_v2.md

机器状态放在产物旁边，保持私有，绝不提交：

dsh-plans/.state/ # .gitignore contains ".state/" (created by the helper)
config.json # language + per-role model settings
active.json
runs/<run-id>/ # run.json, decisions.jsonl, subagents.jsonl, refs.jsonl
下载的大体积参考文件默认放在仓库外面，路径是 ~/.cache/dsh-plans/refs/。

预设目录结构

agent.cordis.yml 组合配置：标准智能体 + dsh-plans 各行 preset.yml 展示元数据 lib/plan-subagents.js 本地宿主插件：run_plan_subagent 工具 skills/ 五个内置技能 + 共享参考文件 scripts/dsh_plans_state.py 状态辅助命令行（仅用标准库）

组合配置通过加载器的 baseUrl 注册自己的 skills/ 目录，所以预设可以随意挪位置：把它克隆到预设根目录下的任何地方，它照样能找到自己的技能和本地插件。

安全模型

支持的边界是规划纪律、持久状态和显式交接。交接之前，工作流只写 dsh-plans/.state/ 和 dsh-plans/ 下的产物——绝不碰目标源码、配置或测试。审查者和批评者子代理在结构上就是只读的（run_plan_subagent 拒绝文件写入、目标、用户提问和委派类工具），它们通过最终输出回报结果。Auto-complete 可以回答规划和细化类问题；它绝不批准目标执行、安装、部署、合并、推送、凭据使用，或任何改变外部状态的操作。

验证

node --test scripts/test_plan_subagents.js
python3 scripts/validate_preset.py
python3 scripts/dsh_plans_state.py init --workdir /tmp/dsh-plans-smoke

许可证

MIT。见 LICENSE。

[DeepSeek Harness]: https://github.com/deepseek-ai/deepseek-harness