hoyyang/dsh-plan-board

dsh-plan-board

banner

把整个项目画成一张会自己动的「任务思维导图」，并且让 Agent 真的照着它走——跑偏当场拦下。

计划 → 模块 → 任务三层展开，跨分支依赖画成紫色箭头，拓扑执行序号实时刷新，Agent 在图上 GPS 站位前行；改图必须过「人审门」才生效，任务完成必须附证据，工具越界被当场 deny，git 里出现计划外改动立即漂移阻断。

English · Releases · 更新日志 · 设计文档

安装

dsh plugin --profile web add github:hoyyang/dsh-plan-board
构建产物随仓库提交，免本地构建

重启 dsh web：会话头部右侧（「⋯ 更多操作」左边）出现 PlanBoard 按钮即成功。点它打开面板，填项目根绝对路径即可。

dsh plugin --profile web remove @dsh-external/dsh-plan-board   # 卸载

最低 dsh >= 0.1.5-rc.1（实测版本）。零配置：不需要 API Key，规划数据全部落在你自己的项目目录里。

看看长什么样

- 左：面板（561×720）——计划 → 模块 → 任务三层思维导图，模块间紫色虚线是依赖，任务前的 #N 是拓扑执行序号，绿色=done；顶部横幅是 L7 越界拦截，底部是事件时间线（status_changed / human_edit / guard_alert 全量留痕）。
- 入口按钮：静止收成 31×31 正圆（左），悬停向左展开成完整胶囊（右）——两态圆角同为 15.5px（= 高度一半），所以弧度全程不变；右缘固定，右邻「⋯ 更多操作」不动。

  

它解决什么问题

Agent 跑偏不是「不听话」，是没有可执行的计划权威：计划活在对话里，压缩一次就没了；任务做到哪一步没人知道；说「做完了」也没有证据；改计划不留痕。dsh-plan-board 把计划变成项目里的一份机器权威文件（/.plan-board/plan.board.json），再用七层机制让 Agent 只能顺着它走。

Agent 工具（5 个）

| 工具 | 作用 |
| --- | --- |
| plan_map | 读图：模块/任务树 + 依赖 + 拓扑序号 + 站位 + 漂移块 + 待批改动（新会话/压缩后第一件事） |
| plan_edit | 改图：结构变更进待批队列，人在面板点头才生效（L2 人审门） |
| plan_next | 发号：唯一下一个可做任务（依赖已就绪 + 优先级排序），当场标记 doing（L1 单发号硬锁） |
| task_update | 流转：planned/ready → doing → done/blocked；done 必须附证据（L3 证据门），模块收卷也走这里 |
| plan_link | 对账：经 ai-memory 与 ~/.ai 项目记忆双向同步（push/pull） |

防跑偏七层

| 层 | 机制 | 默认 |
| --- | --- | --- |
| L1 | 单发号硬锁：同时只允许一个 doing；已有进行中任务时 plan_next 直接拒绝 | 开 |
| L2 | 改图人审门：plan_edit 结构变更进待批队列，面板「确认生效/驳回」 | 开 |
| L3 | 证据门：done 不带证据 → EVIDENCE_REQUIRED（任务与模块一视同仁） | 开 |
| L4 | git 交叉核对：doing 期间的 commit 若不落在任务 scope 内 → 漂移告警/阻断 | 开 |
| L5 | 漂移阻断：存在未处置漂移时拒绝发号，人须在面板「解除阻断」 | 开 |
| L6 | LLM 仲裁 + watchdog | M4 未排期 |
| L7 | 工具观测 + 越界拦截：write/edit 路径未命中当前 doing 任务 scope → 当场 deny（具名理由 + 出路）；看类操作宽放行；bash/run_code 先放行只记录 | 开（enforceScope: false 可降级） |

功能

- 思维导图面板：React + 自绘 SVG 横向树，模块分组自动布局；滚轮缩放（原生 non-passive，不带动面板滚动）、拖背景平移、拖拽节点自定义位置（pos 仅视图状态，不进 lint）。
- 面板直编辑：点节点开编辑卡（标题 / 优先级 / 备注 / 验收标准 / scope / 依赖多选）、拖拽、紫点拖出连线改依赖（拖到 B 即 B 依赖它，再拖一次撤销）、＋子任务 / 删除节点。
- 保存门控：面板上的一切改动先进草稿态（横幅显示「N 项未保存更改」），点「保存更改」才批量 POST /edit 落盘并记 human_edit 事件；点「放弃」全部回滚。保存前客户端预检环依赖，服务端 lint 兜底；status 不在面板直改（状态流转只走 task_update 的证据门）。
- 模块级依赖真的算数（v0.2.0）：写在模块上的依赖会向下冒泡到它的子任务——「大任务3 依赖 大任务2」会真正卡住小任务3-1 的发号。模块在「自身 done」或「名下任务全部 done/canceled」时算完成；空模块不自动完成；声明无环但冒泡后成环的死锁会在提交时被 lint 拒绝。
- 实时刷新：/stream NDJSON 推送 + 4s 轮询兜底；待批 diff、漂移横幅、拦截横幅、事件时间线全部实时。
- 入口按钮（会话头部）：静止时收成 31×31 正圆只留银河图标，悬停/键盘聚焦/面板开启时向左展开成完整胶囊（两态圆角同为 15.5px，弧度不跳变；右缘固定，邻居平滑让位）；状态点每 15s 轮询 GET /state：青=无进行中 · 琥珀=N 个进行中 · 红=漂移阻断或阻塞 · 灰=未设置路径；收起态由图标光晕颜色继续传达状态。深浅主题同款，aria-pressed / focus-visible / prefers-reduced-motion 齐备。
- 存储：/.plan-board/ 三件套——plan.board.json（机器权威，乐观锁 version + SHA-256 digest）、events.jsonl（只追加审计流）、ROADMAP.md（人读镜像）；加上 memory.link.json 与 ~/.ai 的对账指针。全进 git。
- ~/.ai 强关联：plan_link push/pull 经 ai-memory 读写项目记忆，规划记录与叙述性记忆互为索引。

数据权威

规划与任务状态以 .plan-board/plan.board.json 为唯一权威；叙述性记忆以 ~/.ai 为权威。两者经 plan_link 对账，插件从不直写 canonical 记忆文件。

使用

1. Agent 侧：新会话/压缩后先 plan_map；plan_next 领任务（一次一个）；做完 task_update 为 done 并附证据；改规划用 plan_edit（等人点头）；里程碑后 plan_link push。
2. 人类侧：点头部 PlanBoard 按钮开面板 → 填项目根绝对路径 → 待批项「确认生效/驳回」→ 漂移横幅「解除阻断」→ 拦截横幅「暂停拦截/恢复拦截」（内存态，重启恢复拦截）。

边界（明确不做）

- 不做看板（Kanban）形态——思维导图是主形态（用户拍板）。
- 不替代 issue tracker：单项目单板，不做多人协作/权限/通知。
- status 不在面板直改（必须走 task_update 的证据门）。
- L7 第一版的观测边界：run_code 程序内直接 fs、终端任意重定向不经工具通道，无法精确拦截（已按拍板：bash/run_code 先放行只记录，观测面 tool-calls.jsonl 全量留痕）。
- 甘特/关键路径视图、LLM 仲裁（M4）未排期。

开发

npm install                      # 取本地 devDependencies（tsdown 等）
bash scripts/build.sh            # host：tsc 编译到 lib/（自动探测 DSH_CHECKOUT 或 npm 安装的 dsh）
npm run build:client             # client：tsdown 编译面板（react 为 external）
bash /path/to/dsh-plugin-build/scripts/boot-check.sh web   # 冷启动三故障静态检测

改完源码请把 lib/ 一起提交（GitHub 安装依赖它）。

卸载

dsh plugin --profile web remove @dsh-external/dsh-plan-board

卸载不会删除你项目里的 .plan-board/ 数据；彻底清除请手动删除该目录。

License

BSD-3-Clause