@fakechris/dsh-track

Readme

# dsh-track · Track Bridge

[![npm](https://img.shields.io/npm/v/@fakechris/dsh-track)](https://www.npmjs.com/package/@fakechris/dsh-track)
[![npm downloads](https://img.shields.io/npm/dm/@fakechris/dsh-track)](https://www.npmjs.com/package/@fakechris/dsh-track)

[English](README.en.md) | 中文

> **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 面板总览](assets/panel.png) | ![跳回来源对话](assets/jump-back.png) |
| 日历纱线（跨项目 session 生命周期 / 漂移 / 切换） | 自包含可视化导出（数据 JSON + HTML 视图，离线可交互） |
| ![日历纱线](assets/calendar-yarn.png) | 见 [`export/track-calendar-view.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 显式通道）。

## 🚀 快速开始

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

## 🏗️ 架构

**Fat skill + thin harness**：决策判据与调用纪律在 [`skills/dsh-track/SKILL.md`](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）。

## 🛠️ 开发

```sh
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](https://github.com/fakechris/dsh-track)（旧名 `dsh-external/dsh-track` 会重定向）
- 协议 skill：[`skills/dsh-track/SKILL.md`](skills/dsh-track/SKILL.md)（决策点判据、任务推进纪律）
- 仓库约定：[`AGENTS.md`](AGENTS.md)（提交 / worktree / 文档双语规范）

## 📄 License

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