文件规划持久化 Asaka-RUM/dsh-planning-with-files

dsh-planning-with-files

面向 DeepSeek Harness (dsh) 的 Manus 风格文件持久化规划插件。

工作区里的三个 Markdown 文件充当模型的"磁盘工作记忆"：

| 文件 | 用途 |
| task_plan.md | 阶段、状态、决策、错误日志 |
| findings.md | 研究发现（2-Action 规则） |
| progress.md | 会话日志、测试结果、错误日志 |

插件在每个回合开始（legacy 模式下每个 step）把计划重新注入模型上下文，因此工作进度不会因上下文丢失、/clear 或压缩而消失。

这是一个移植项目。 设计、模板与工作流均来自 planning-with-files 技能，作者 Ahmad Adi（MIT 许可，© 2026）。本项目在 DeepSeek Harness 插件平台上重新实现了该工作流。详见来源与引用及许可要求。

功能

- 回合开始注入 —— 每个 step 0 前注入计划（head + 进度尾，或 v3 模式下的 ledger 摘要），以 ===BEGIN PLAN DATA=== / ===END PLAN DATA=== 定界。
- 逐步注入（legacy 模式） —— 后续每个 step 注入精简计划头，对应上游的 PreToolUse hook。
- 五个工具 —— plan_init、plan_status、plan_switch、plan_attest、 plan_rules。
- v3 模式（autonomous / gated）：
- SHA-256 校验默认开启；与已认证哈希不一致的计划会被 [PLAN TAMPERED] 拒绝注入。
- 每个计划随机 .nonce 分隔符，抵御分隔符混淆注入。
- 用合成的 ledger 摘要替代原始 progress.md 尾部（磁盘上的自由文本不再进入上下文）。
- gated 模式带硬性完成门：agent/turn-stopping 期间调用
agent.inject()，让回合循环持续到所有阶段都报告 Status: complete，
并由持久化的 .stop_blocks 计数器（上限默认 20）与 ledger 停滞检测兜底。
- 并行写保护 —— 已完成阶段/已勾选项减少时发出告警（进程内内存检测）。
- 写入提醒 —— 写入非计划文件后提醒模型同步 progress.md / task_plan.md （每回合限次）。
- 压缩提示 —— 计划文件在磁盘上无损耗地挺过压缩；下一个 pre-step 本来就会重新读取。

安装

Harness 从 profile 的 node_modules 加载插件：

把包复制进 profile（或建软链接） Copy-Item -Recurse dsh-planning-with-files "$HOME\.dsh\profiles\node_modules\"

然后在 profile 的 patch 层注册，例如 $HOME\.dsh\profiles\web\cordis.patch.yml：

- insert:
- id: planning-with-files
name: 'dsh-planning-with-files'

重启 harness（node <dsh>/lib/bin.js --profile web），确认 Web UI 正常响应。

用法

让模型规划多步任务，或直接调用工具：

1. plan_init —— 创建三件套。带 name 时在 .planning/YYYY-MM-DD-<slug>/ 下创建独立计划（并行工作流）；不带则写在工作区根目录（legacy 模式）。
mode 接受 legacy / autonomous / gated。
2. 按阶段推进，同步 Status:（pending → in_progress → complete）并刷新 ## Next Step。
3. plan_status —— 读取计划与完成度。
4. plan_attest —— 用 SHA-256 锁定计划（v3 模式默认开启；每次审核修改后重新认证）。
5. plan_switch —— 切换 .planning/ 下的并行计划。

gated 模式示例

plan_init mode=gated name="Build Pipeline" goal="Build the release pipeline"

在所有阶段报告完成之前，模型不会被允许停止。

配置

| 键 | 默认值 | 含义 |
| enabled | true | 总开关 |
| mode | 'legacy' | legacy \| autonomous \| gated |
| planId | '' | 锁定到 .planning/<id>（相当于 PLAN_ID） |
| planRoot | '' | 锁定到绝对路径计划目录（相当于 PWF_PLAN_ROOT） |
| injectAtTurnStart | true | step 0 注入 |
| injectAtStep | true | 逐步注入（仅 legacy 模式） |
| injectSmart | false | 结构化注入（相当于 PWF_INJECT=smart） |
| guard | true | 并行写减少告警 |
| gateCap | 20 | 连续拦停上限，达到后放行停止 |
| remindOnWrite | true | 写入后进度提醒 |
| maxRemindersPerTurn | 1 | 每回合提醒上限 |
| rulesSection | true | 系统提示中的规则简报 |
| planHeadLines | 50 | 回合开始计划头行数 |
| planStepLines | 30 | 逐步计划头行数 |
| progressTailLines | 20 | 进度尾行数（legacy） |

Hook 映射（对照上游 Claude Code 技能）

| 上游 hook | dsh 对应 |
| UserPromptSubmit | agent/pre-step step 0 |
| PreToolUse | agent/pre-step step > 0（legacy 模式） |
| PostToolUse | tools/post-execute（additionalContexts） |
| Stop（门） | agent/turn-stopping + agent.inject() —— 真正的硬门 |
| PreCompact | session/event compaction/start（控制台提示） |
| 技能内容 | systemPrompt.section + plan_rules 工具 |

未移植

- session-catchup.py —— dsh 会话本身持久化；计划在每个 pre-step 从磁盘重读，恢复是天然行为。
- plan-doctor.sh、attest-plan.sh、ledger-summary.sh —— 已并入工具与 hook。
- 认证锁定/flock、计划级 SHA 缓存 —— dsh 单进程宿主上无必要。
- 并行写保护为进程内检测（与上游相同的已知上限：宿主从不设置 PWF_SESSION_ID）。

来源与引用

- 上游项目： OthmanAdi/planning-with-files —— "Persistent file-based planning for AI coding agents"，作者 Ahmad Adi （OthmanAdi），MIT 许可，© 2026。SKILL.md、三个模板以及工作流设计（hooks、v3 模式、认证、nonce 分隔符、ledger、门控保护）均源自该项目。
- 上游许可： 见 LICENSE，其中在本项目版权之外完整保留了上游版权声明。
- 上游模板保持原样，以保证现有规划文件与工作流兼容。

许可

MIT。见 LICENSE。本移植是在 dsh 插件平台上的独立重实现，与上游项目无隶属关系。