任务轨道桥 fakechris/dsh-track

dsh-track · Track Bridge

npm
npm downloads

DeepSeek Harness 的嵌入式任务管理引擎 —— 把「念头、决策、任务」变成结构化、可追溯、可折叠的数据。
捕获零摩擦，决策留痕迹，任务有生命周期。数据全部在 harness 内部（session 事件 + storage KV），零外部依赖。

状态 Active · 测试 240 passing · 构建 pnpm run build · 版本 0.6.0 v0.6.0 · 会话执行图 + 日历纱线 + 证据纪律（2026-08-21）：会话执行图（M1）——任意会话一键建成确定性的 turn→step→tool 树（每条边带 (sessionId, seq) 引用回原始日志），可按工作区批量建图，渲染为会话标签栏的「会话结构图」tab（遵循 host conversation.view 规范）；日历纱线——跨项目 session 生命周期 / 漂移 / 切换一图可见（泳道按事件量降序、零活动仓库折叠、跨会话/跨项目连线金色菱形），可导出自包含可视化（数据 JSON + HTML 视图 + README，离线可交互）；Genealogy 语义层—— track_genealogy（fork 谱系 / issue↔session / capture→issue / decision→session / 项目归纳，默认 dry-run 预览）、 track_git_artifacts（git commit 对齐到 session 与 issue，「这个需求落到哪个 commit」）、 track_evolution_brief（零 LLM 项目简报 + 缺口建议）；证据纪律（P4/P6/P5a）——证据抽屉 + 分层 guard （确定性图与语义层两条管线分离，语义方法最多只能写 candidate）+ Output-first 交付度量（软删除 + 证据分级 + commit trailer 显式通道）；项目归属改为「实际触碰的 repo」（project = repo the session actually touched）。
v0.5.0 · 面板任务操作 + 翻页器（2026-08-14）：任务卡新增「完成/取消」直接操作（两步入确认）与「批量」模式（复选框 + 批量完成/取消）；翻页器补齐「第一页 / 页码输入跳页 / 最后一页」，翻页滚动锚定（切换页面时分页器保持在视口原位置，不再跳动）。
v0.4.0 · 自动维护机制 + 配置面板（2026-08-14）：生命周期 sweep 让僵尸任务浮出「待确认」区； capture 自动促转 + 近似重复自动归并（token 相似度阈值可配）；canceled 提议超宽限期自动确认；定时 sync（周级 v1 限额）；Track 面板 ⚙ 配置面板（/api/track/config）。lib 产物入库；
npm 发布走本地（IP 信任 + 硬件 2FA），GitHub Actions 做 tag 验证与打包产物。
v0.3.0 · 去重 + 面板修复（2026-08-14）：捕获墙不再出现重复条目——createCapture 统一闸门（持久化 per-session 标记 + 内容哈希兜底，重启后不重捕）；右侧面板/页签修复（正式版 UI 布局下挂载到真实会话根，Track 页签可开合）；底部 strip 显示真实捕获数并可点击打开面板。
v0.2.1 · final 正式版适配（2026-08-12）：官方正式版（snapshots/20260812T172954Z-final-unwatermarked）的词汇清洗中两处无别名硬改名——SessionQueryService→SessionQueryEngine（dsh-session-query）、 ctx.httpServer→ctx.webServer（dsh-host-webserver）——已适配（tsc + 342 测试 + 生产等价冒烟验证）。

🖥️ 界面预览

| 面板总览（右侧捕获墙 + 任务墙） | 跳回来源对话（高亮定位到原始 prompt） |
| dsh-track 面板总览 | 跳回来源对话 |
| 日历纱线（跨项目 session 生命周期 / 漂移 / 切换） | 自包含可视化导出（数据 JSON + HTML 视图，离线可交互） |
| 日历纱线 | 见 export/track-calendar-view.html（示例导出） |

✨ 特性

- 🧠 捕获墙（Capture Wall） —— capture_thought 零摩擦收录念头；规划时的 todo_write 也会被自动捕获，且每条都携带动机上下文（当时那条用户请求），永远不会变成"无来由的琐碎清单"。
- ⚖️ 决策账本（Decision Ledger） —— 遇到不可逆 / 风险 / 范围 / 验收类决策，先上报决策点，用户轻决策回答，选择与理由落盘可查（回答率进 funnel）。
- 📋 任务生命周期（Evidence-driven Lifecycle） —— Linear 兼容的任务模型；证据驱动的状态机，done / canceled 永不自动达成，必须用户确认。
- 🔄 历史同步（History Sync） —— 一键把工作区过往会话折叠成 epic/issue 候选，默认 dry-run，确认后才落库。
- 💰 LLM 用量账本（Usage Ledger） —— track 引擎自己调用的 LLM 费用（token / 成本）单独计量，"track 花了多少 token" 一句话可查。
- 🖥️ Web 面板 —— 右侧栏汇集墙 + 任务墙；每条记录都可 「↩ 对话」跳回来源会话的那条原始 prompt，高亮定位。
- 🕸️ 会话执行图（Session Graphs） —— track_session_graph 把任意会话建成确定性的 turn→step→tool 执行树，每条边带 (sessionId, seq) 引用回原始日志；支持按工作区批量建图（幂等，可强制重建）；会话标签栏的「会话结构图」tab 实时渲染当前会话。
- 🧵 日历纱线（Calendar Yarn） —— 跨项目 session 生命周期 / 漂移 / 切换一图看清：泳道按事件量降序、零活动仓库折叠、「只看缠绕线」线级过滤；可导出自包含可视化（数据 JSON + HTML 视图 + README，浏览器直接打开即交互）。
- 🧬 Genealogy 语义层 —— track_genealogy 把需求串成图（fork 谱系 / issue↔session / capture→issue / decision→session / 项目归纳，默认 dry-run 预览）；track_git_artifacts 把 commit 对齐到 session 与 issue；track_evolution_brief 零 LLM 生成项目状态简报与缺口建议。
- 🛡️ 证据纪律（Evidence Discipline） —— 证据抽屉 + 分层 guard：确定性图（git 事实 / 哈希链接）与语义层（LLM 聚类）两条管线分离，语义方法最多只能写 candidate，证据等级永不静默升级；Output-first 交付度量（软删除 + 证据分级 + commit trailer 显式通道）。

🚀 快速开始

1. 安装插件（官方推荐：用发布版 dsh 安装；本地已有 dsh 也可直接 dsh plugin ...）
npm 包（已发布，推荐）：
npx -p @deepseek-ai/dsh dsh plugin --profile web add @fakechris/dsh-track
git 源（npm 不可达时的备选）：
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:fakechris/dsh-track
（或本地路径：... add /absolute/path/to/dsh-track）

2. 安装协议 skill（决策点 / 任务推进的调用纪律，装到默认扫描目录）
mkdir -p ~/.dsh/skills && cp -r skills/dsh-track ~/.dsh/skills/

3. 重启 dsh web（守护会自动拉起），工具自动挂载
dsh web

验证：浏览器打开面板（右下角 ◆ 按钮，或会话标签栏的 Track 标签页），看到「捕获想法」和「任务」两栏即安装成功。

📖 核心工作流

| 流程 | 做什么 | 入口 |
| 捕获 | 随时把念头丢进捕获墙；agent 规划时（todo_write）自动捕获，自动附带动机上下文 | capture_thought · 面板输入框 |
| 决策 | 遇到不可逆 / 风险 / 价值观 / 范围 / 验收决策时上报，用户轻决策回答，选择与理由落盘 | report_decision_point → track_respond_decision |
| 任务 | 把需求变成任务；声明会话在推进它，执行证据自动累计；状态机推进，done 必须用户确认 | track_create_issue → track_attach_issue → track_update_issue_state |
| 回顾 | 把过往会话折叠成任务候选；随时跳回任何条目的来源对话与原始 prompt | track_sync_history · 面板「↩ 对话」 |

🧰 工具清单

| 工具 | 作用 |
| capture_thought(content, tags?) | 把念头零摩擦收进捕获墙 |
| report_decision_point(question, options, my_preference, rationale, impact, need) | 上报决策点；用户轻决策回答，自动存入决策账本 |
| track_respond_decision(decision_id, choice, rationale?) | 用户回答后落盘选择与理由（幂等；dismissed 表示跳过） |
| track_list_decisions(state?, since?, session_id?) | 查决策历史（待确认 / 已回答 / 已跳过） |
| track_create_issue(title, description?, priority?, acceptance?, parent_id?) | 创建 Linear 兼容任务 |
| track_attach_issue(issue_id) | 声明当前会话正在推进某任务；此后执行证据自动记到该任务 |
| track_update_issue_state(issue_id, target, note?, confirmed_by_user?) | 提议 / 确认状态变更；done / canceled 必须带 confirmed_by_user=true（系统永不自动标 done） |
| track_issue_evidence(issue_id) | 查任务的证据账本与推断状态 |
| track_list_issues(team_id?, state?) | 列出任务 |
| track_sync_history(workspace?, since?, dry_run?, max_sessions?, engine?) | 把工作区 session 历史折叠成 epic/issue 候选（默认 dry-run） |
| track_usage(since?) | 报告 track 引擎发起的 LLM 调用开销：请求数、各类 token、耗时、估算成本 |
| track_backfill_captures() | 存量捕获动机上下文回填（幂等，安全可重跑） |
| track_session_graph(session_id?, workspace?, max_sessions?, rebuild?) | 建 / 读会话执行图（turn→step→tool 树，带 seq 引用；支持工作区批量建图） |
| track_genealogy(workspace?, dry_run?) | 构建语义层（fork 谱系 / issue↔session / capture→issue / decision→session / 项目归纳；默认 dry-run） |
| track_git_artifacts(workspace?, project_level?, dry_run?, limit?) | 扫描 git commit 并对齐到 session（landed-in）与 issue |
| track_evolution_brief(project_id?) | 零 LLM 生成项目简报：状态统计、近期活动、缺口建议 |

🖥️ Web 面板与 HTTP API

面板（src/client/right-panel.ts）直接挂载在会话右侧栏，纯 DOM 注入、无框架依赖：

- 捕获墙：输入捕获、分页、两步确认删除、一键转任务；
- 任务墙：按状态分组（进行中优先）、可展开详情、删除；
- ↩ 对话：每条捕获/任务都可一键跳回来源会话的那条原始用户 prompt——自动切换左侧会话、翻页到深历史、滚动定位并高亮闪烁；旧数据无消息 id 时回退到该会话首条用户消息；
- 20s 轻量自动刷新、面板宽度可拖拽、收起后有 ◆ 悬浮按钮；
- 会话结构图 tab：会话标签栏的「会话结构图」视图实时渲染当前 session 的 turn→step→tool 执行树（遵循 host conversation.view tab 规范，下划线高亮跟随当前步骤）。

HTTP API（面板的数据面，/api/track/）：

| 端点 | 说明 |
| GET/POST /api/track/captures · DELETE /:id · POST /:id/promote | 捕获墙 CRUD + 转任务 |
| GET /api/track/issues · DELETE /:id · GET /:id/evidence | 任务列表 / 删除 / 证据账本 |
| GET /api/track/decisions?state=&since=&session_id= | 决策历史 |
| GET /api/track/usage?since=&limit= | LLM 用量汇总 + 最近明细 |
| GET /api/track/funnel | 工具调用漏斗（capture 转化率等） |
| POST /api/track/sync | 历史同步（等价 track_sync_history） |

🔗 深链跳转（Deep Links）

从外部（终端 / 其他 agent / jump 启动器 / 脚本）一键打开浏览器并定位到 Web GUI 的指定会话（可精确到某条消息）：

- 路径形式 http://:/s/[/] —— 持久化，书签/刷新/分享持续有效；
- 查询形式 http://:/?open=[&message=] —— 一次性，跳转后参数自动清理；
- 能力由 src/client/deep-link.ts 提供（复用 jumpToConversation 的 open + 滚动定位，见上节「↩ 对话」）。
- 给其他 agent / 脚本的使用指引（含获取 sessionId / messageId 的命令、验证与注意事项）：docs/deep-link-handoff.md

🏗️ 架构

Fat skill + thin harness：决策判据与调用纪律在 skills/dsh-track/SKILL.md，harness 侧只注册工具与存储，不做判断。

存储归位：决策点/todo 留 session 事件（可回放）；Capture / Issue / Decision / Usage 存 ctx.storage KV（跨会话独立），数据为 Linear 兼容形状（随时可迁）。

src/index.ts host 插件：工具注册 + 事件订阅 + store 接线 + HTTP API src/store.ts TrackStore：KV 单元封装（串行写链） src/types.ts Linear 兼容数据形状 src/capture/ 自动捕获 + 动机上下文（observer / context / backfill） src/lifecycle/ 证据观察器 + 状态机（evidence-driven lifecycle） src/sync/ 历史同步引擎（extract → segment → intent → synthesize → align） src/usage.ts LLM 用量账本（recorder + 汇总 + 成本估算） src/graph/ 会话执行图 / 日历纱线 / genealogy（build / calendar / links / commits / service） src/client/ Web 面板（right-panel / composer strip） skills/dsh-track fat skill：决策点判据 / 格式 / 纪律 cordis.patch.yml bundle patch（dsh plugin add 自动应用）

设计约束（插件开发者必读）：业务数据不写 session 自定义事件——2026-08-11 起 harness 对未知事件类型会拒读整份日志；观察会话只走官方事件流，只读不写（详见 src/types.ts 末尾注释与仓库 AGENTS.md）。

🛠️ 开发

pnpm install
pnpm run build # tsc 产物 lib/ + client bundle
pnpm test # vitest（188 tests）

- 开发用仓库内 worktree（.worktrees/）+ 分支 + PR + squash merge（见仓库 AGENTS.md L4/L5）。
- 新增 @deepseek-ai/ 依赖须同步改 tsconfig paths、vitest alias、ab-config relink（L7）。

📚 相关链接

- 仓库：github.com/fakechris/dsh-track（旧名 dsh-external/dsh-track 会重定向）
- 协议 skill：skills/dsh-track/SKILL.md（决策点判据、任务推进纪律）
- 仓库约定：AGENTS.md（提交 / worktree / 文档双语规范）

📄 License

私有插件仓库（package.json 标记 private）；skill 元数据声明 BSD-3-Clause。