andrepontesmelo/dsh-wayfinder-ui

dsh-wayfinder-ui

License: MIT
Node >=22
DSH plugin

一个与追踪器无关的 Wayfinder 运行器插件，适用于 DeepSeek Harness (DSH)：每个新会话都会学习一个三动词注册契约，映射保存在每个工作区的注册表文件 .wayfinder-runner/state.json 中（已提交），UI 轮询 /dsh-wayfinder/state.json。

何时使用它

你为 DSH 工作绘制 Wayfinder 映射，并希望每个就绪任务都由其自己的顶层会话接手，同时依赖映射实时跟踪进度——无论任务在哪里被追踪（dex、Jira、GitHub issues、markdown 文件）。

前置条件

- Node.js ≥22（参见 package.json 中的 engines）
- 带有 web profile 的 DSH（~/.dsh/profiles/web/）
- 用于本地开发的 pnpm 或 npm

安装

1. 克隆到任意位置
git clone https://github.com/andrepontesmelo/dsh-wayfinder-ui.git
2. 符号链接到 web profile
ln -s /path/to/dsh-wayfinder-ui ~/.dsh/profiles/web/node_modules/dsh-wayfinder-ui

将插件行追加到 ~/.dsh/profiles/web/cordis.patch.yml：

- insert:
- id: wayfinder
name: 'dsh-wayfinder-ui'

派生的会话继承派生会话的路由（provider/model）；wayfinder_spawn_session 上可选的 provider/model 参数会按调用覆盖该继承。

它们也会加入派生会话的工作区；当调用方为 Ungrouped——或者 wayfinder 根目录位于调用方自身工作区目录之外（上游附加验证会拒绝这种情况）——派生会话会保持 Ungrouped，而不会被强制重新分组。

重启 GUI。模型工具和映射面板都会在启动时加载。

npm： npm install dsh-wayfinder-ui 计划在手动验证后发布——在此之前，GitHub 是安装来源。

如果满足以下条件，说明它正在正常工作

- 新会话在启动时收到三动词契约，并且 Settings → Wayfinder 列出了这些开关。
- wayfinder_map_create 写入 .wayfinder-runner/state.json，右侧栏渲染你的映射的任务行。
- 一次已批准的派生会为每个就绪任务打开一个顶层会话，并且工作线程的 wayfinder_task_resolve 会将其行翻转为完成。

工具

插件安装后，全部七个工具均可由模型调用。

- wayfinder_snippet — 打印协议：向人类提出就绪的 wayfinder 任务，请求明确批准，然后恰好调用一次 wayfinder_spawn_session。未经批准绝不派生。它还记录了种子消息格式和路由继承规则。
- wayfinder_spawn_session — 为每个就绪任务并行生成一个顶层 DSH 会话。任务来自注册表前沿：省略 tasks 即可生成所有就绪任务（派生状态为 todo；已完成以及被未完成任务阻塞的行会被跳过）。每个种子都带有一行 Task locator，指向该任务的工作所在之处，这样无论任务实际跟踪在哪里——dex、Jira、GitHub issues、markdown 文件——工作者都能找到自己真正的工单。每个生成的会话都会加入生成它的会话的工作区，并继承其路由；可传入可选的 provider/model 以按调用覆盖。
- wayfinder_map_create — 将一张新地图绘制到注册表中：校验 tasks: [{id, title, type?, locator, blockedBy?}]，将其持久化到 /.wayfinder-runner/state.json，并使其成为选中的打开地图。
- wayfinder_task_resolve — 因某个工作者完成了任务而将某个任务标记为已完成（工作者报告路径），并将报告会话盖章到该行上。
- wayfinder_task_set_status — 手动覆盖某个任务的状态（todo|done|running|waiting|blocked）。对于工作者完成报告，优先使用 wayfinder_task_resolve。
- wayfinder_map_sync — 按名称创建或替换一张地图，并附带完整的任务列表；同时也注册为 /wayfinder-map-sync 恢复入口。
- wayfinder_grilling_start — 报告某个拷问任务的会话已开始拷问一批内容并等待用户。会在该行上盖章 grillingSince，从而在面板（右侧栏 + 会话内卡片）中点亮一团火焰；wayfinder_task_resolve 会清除它。拷问类型的生成会在其种子中携带该指令。

工作原理

1. 绘制 — wayfinder_map_create 校验任务列表，并将该地图持久化为工作区注册表中选中的打开地图。
2. 生成 — 每个已批准的任务都会获得一个顶层 DSH 会话，其种子为 /wayfinder work on task (TASK_ID) of map (MAP_NAME)（开头的 /wayfinder 手势会让 harness 注入技能内容，就像人类输入了该斜杠命令一样），外加其 Task locator 行。
3. 报告 — 工作者通过调用 wayfinder_task_resolve 来完成，这会将他们的任务标记为已完成并关联报告会话。
4. 派生 — done 来自报告/手动覆盖，blocked 来自 blockedBy 边，而 running/waiting 则从生成的会话实时计算得出（运行中的 agent；其最新模型可见事件为助手消息的空闲 agent）。
5. 重启 — 插件会重新加载状态文件：selectedMapId 优先（回退到最新的打开地图），并且会话会通过匹配种子消息重新关联到各自的行。

界面

- 会话内卡片 — 位于输入框上方的可折叠 To-dos 风格卡片仅在绘制该地图的会话中渲染：载荷携带 createdBySessionId，而 dock 会将其与自己的会话进行比较。没有盖章所有者的地图（手写注册表）不会在任何地方显示卡片；从你的会话中调用一次 wayfinder_map_sync 即可认领它。
- 右侧栏和环境侧边栏徽章有意保持工作区级别：任务控制中心应当从每个会话都可见。两者在 设置 → Wayfinder 中仍可单独切换。
- 会话链接——右侧栏上的任务行（以及展开卡片上的任务行）在该行生成会话时会带有一个 ↗ 链接；点击即可打开该会话，与点击其侧边栏行完全一样。
- 拷问火焰——每个进行中的拷问批次显示一个 🔥：当拷问类型的会话开始拷问并等待你时，它会调用 wayfinder_grilling_start；右侧栏和卡片会显示一个火焰标签（N grilling），以及每行的火焰，直到任务解决。

开发

pnpm install
pnpm test        # node --test

已知限制

- 仅限 Web 配置：卡片、右侧栏和侧边栏徽章位于 DSH GUI 中。
- 生成目标为注册表中选定的打开地图（selectedMapId，回退到最新的打开地图）。

许可证

MIT © 2026 Andre Melo