fakechris/dsh-track

dsh-track · Track Bridge

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

状态 Active · 测试 240 passing · 构建 pnpm run build · 版本 0.5.0

v0.6.0 · 会话执行图 + 日历纱线 + 证据纪律（main · 未发布，2026-08-18）：会话执行图（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）
日历纱线（跨项目 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 标签页），看到「捕获想法」和「任务」两栏即安装成功。

📖 核心工作流

🧰 工具清单

🖥️ 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/*）：

🏗️ 架构

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/<name>）+ 分支 + 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。