dsh-global-todo 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## [0.11.0] — 2026-10-20
+
+Documentation and demo, treated as part of the product.
+
+- **A standalone landing page** at `docs/index.html` (GitHub Pages): hero with the install line and
+  a 24-second captioned tour, the three claims with evidence, a five-step strip through the real
+  screenshots, an honest comparison against `todo_write` and kanban boards, a 3×3 grid of every
+  conditional state, and a footer with the data path. One file, inline CSS, no CDN, bilingual
+  toggle, 15 images all verified to decode.
+- **`docs/screenshots/demo.mp4`** — a 24s captioned tour built from the same real renders by
+  `ffmpeg` (not a screen recording, and the page says so), plus the existing GIF for places that
+  cannot autoplay video.
+- **`docs/QUICKSTART.md`** (five minutes, click by click) and **`docs/FAQ.md`** (14 real questions
+  answered against the code), and `docs/screenshots/README.md` indexing what each baseline shows
+  and what a static image cannot prove.
+- **READMEs explain 0.7–0.10 at last**: steps, evidence, read-back, review, Markdown, weekly report.
+  English and Chinese kept as mirror images; stale claims (`21 routes`, `100+ tests`, `@0.4.0`)
+  corrected to 24 / 257 / 0.10.0.
+- **Fixed the two mismatches the docs pass found**: the capture prompt said 200 characters where
+  `LIMITS.evidence` is 300, and `package.json` did not publish the new docs (so their links would
+  have 404'd on npm).
+
+## [0.10.0] — 2026-10-20
+
+The two remaining high-value items, plus the layout bug written down.
+
+- **Markdown in and out.** `GET /export?format=md` writes a task list (title, priority, due,
+  tags, evidence, description, steps, attachments as indented metadata); `POST /import` with
+  `{ markdown }` reads it back through `create` — new items, never an overwrite, because Markdown
+  has no ids. The parser is tolerant: unknown lines ignored, an unreadable date dropped, a blank
+  task line is not a todo.
+- **Weekly agent report.** `GET /report?days=7` derives, from completion records alone: what
+  finished (newest first, by whom), how many conversations were involved, which files were touched
+  and how often, and how many still wait for review. Shown from `⋯ → 本周报告`; nothing is stored.
+- **The scroll bug is documented** in `DESIGN.md` with the measurements (2236px column inside a
+  680px slot, `scrollTop 0 → 0`), so the next person who touches the layout knows which two
+  declarations hold the contract.
+
 ## [0.9.1] — 2026-10-20
 
 The list could not scroll. One missing declaration, and the panel never owned its own height.

package/README.md

@@ -18,7 +18,7 @@ Three things it does that a session-local plan cannot:
 dsh plugin add dsh-global-todo
 ```
 
-[中文说明](README.zh.md) · [Every state has a baseline image](#screenshots) · [Design notes](docs/DESIGN.md)
+[中文说明](README.zh.md) · [5-minute quickstart](docs/QUICKSTART.md) · [FAQ](docs/FAQ.md) · [Every state has a baseline image](#screenshots) · [Design notes](docs/DESIGN.md)
 
 ---
 
@@ -39,6 +39,93 @@ one record:
 | Hand-off | — | **one click: reuse the bound conversation or open a session** |
 | Storage | session event log | one JSON file you can `cat`, edit, diff and back up |
 
+## What 0.9 and 0.10 added (and the two just before)
+
+Six surfaces these READMEs had never explained. Session read-back and evidence came in 0.9;
+Markdown and the weekly report in 0.10; steps in 0.8 and the review mark in 0.7, which until now
+only existed in the changelog. Each changes what a record can carry, or what you can do with it
+after the fact.
+
+### Steps: a plan inside the todo
+
+A todo can carry up to 20 steps of 200 characters (`LIMITS` in `lib/model.js`). A step is
+`{ text, done }` — a line inside one unit of work, not a subtask with its own id and status.
+
+- **Add them** in "More fields" → Steps, one per line.
+- **Tick them** in the detail panel; the row shows `steps 2/5`.
+- **Hand off** and the dispatch prompt numbers them, prefixing finished ones with `[已完成]`.
+- **Export** and Markdown writes them as nested `- [ ]` lines; import reads them back.
+
+### Evidence: the sentence it came from
+
+`evidence` is the sentence a captured todo came from, quoted verbatim, up to 300 characters.
+`global_todo_capture` asks the model for it, `global_todo_add` accepts it, and the detail panel
+shows it as a blockquote under **In the author's words**. A todo you typed yourself has none.
+
+The field exists for one reason: a capture without its source reads as an opinion later. It is
+also in the Markdown export (`原话:`).
+
+### Session read-back
+
+A hand-off starts work in another conversation, so the detail panel answers "what did it say"
+without switching away. `GET /api/global-todo/session?id=` returns `alive`, `dir` and a `tail`
+of the last assistant message; the panel shows **Session read-back** with running / dormant, the
+last sentence, and a button that opens that conversation.
+
+The tail is bounded and in memory: 200 conversations, 400 characters each, filled from every
+`assistant/message`. Nothing is written to disk, so a Host restart forgets it. A missing tail is
+normal — this process has not seen that conversation speak.
+
+### Review: "done" is a claim
+
+When an agent finishes (`global_todo_done`, or the watcher on a clean turn), the record becomes
+done **and** carries `review: { pending: true }`. The row gets a **Needs review** badge and the
+header a **Review** chip with the count.
+
+| Answer | Effect |
+|---|---|
+| **Confirm done** | stays done, the mark is dropped, the activity trail records who confirmed |
+| **Send back** | back to `open`; `doneAt` and the completion record are cleared; a `reopened` activity entry is added |
+
+Both answers are recorded as the person's action. Sending back deletes nothing: title,
+description, steps, attachments and progress notes stay.
+
+### Markdown in and out
+
+The JSON export is the round-trip format. Markdown is the one you read, diff and edit by hand:
+
+```text
+- [ ] 标题
+      优先级: 高 · 截止: 2026-10-21T18:00 · 标签: 发布, 文档
+      原话: …
+      描述: 第一行
+      - [x] 一步
+```
+
+| Direction | Where | Behaviour |
+|---|---|---|
+| Out | **More actions → Export Markdown**, or `GET /export?format=md` | Grouped 未完成 / 已完成 / 已归档; metadata indented under each task |
+| In | **More actions → Import** (a `.md` file), or `POST /import { markdown }` | Creates new todos through `create`; Markdown has no ids, so it never overwrites an existing record |
+
+Tolerant by design: unknown lines are ignored, an unparseable date is dropped, and a file with no
+`- [ ]` line is refused with a reason. Field labels are Chinese (`优先级 / 截止 / 标签 / 原话 /
+描述 / 附件 / #`), and import reads the same set.
+
+### Weekly report
+
+**More actions → This week** (`GET /report?days=7`) answers "what moved, and did any of it land
+in code". Everything is derived from completion records; nothing is stored.
+
+| Field | Meaning |
+|---|---|
+| `finished` | completions in the window, newest first, with the actor and the summary |
+| `sessions` | distinct conversations those completions came from |
+| `created` | todos added in the window |
+| `pendingReview` | done items still waiting for an answer |
+| `files` | file artifacts touched, most frequent first — 12 listed, `fileCount` total |
+
+`days` above 90 is clamped to 90; a missing or non-positive value falls back to 7.
+
 ## Screenshots
 
 ![The panel: count chips, grouped list, urgent rows marked](docs/screenshots/panel.png)
@@ -64,6 +151,9 @@ half is rendered to static HTML with no Host and no dependencies, then photograp
 into `docs/screenshots/`. Playwright is not a dependency — the tool borrows the copy a DSH
 profile already installed, or whatever `DSH_PLAYWRIGHT` points at.
 
+What each file shows, and when it is regenerated, is indexed in
+[docs/screenshots/README.md](docs/screenshots/README.md).
+
 ## Requirements
 
 - DeepSeek Harness `0.2.x` (developed and verified against `0.2.1-rc.2`; `engines.dsh` is
@@ -90,7 +180,7 @@ The plugin is a Loader row, not a hot-loaded script: **restart the host** (`dsh
 after installing, then refresh the page. A "待办 / Todos" entry appears in the sidebar.
 
 The npm package is the source of truth. A community catalog can lag behind it or point at an
-older release; pin the version you want (`dsh plugin --profile web add dsh-global-todo@0.4.0`)
+older release; pin the version you want (`dsh plugin --profile web add dsh-global-todo@0.10.0`)
 when it matters.
 
 To roll back:
@@ -118,8 +208,8 @@ Your list is not touched by install or uninstall: it lives outside the plugin, a
   documents and addresses (with 打开 / 复制路径 on each); read the activity trail.
 - **Undo a delete** — deleting keeps the record for eight seconds and offers 撤销, which
   restores it verbatim: same id, same creation time, same attachments.
-- **Keyboard** — `/` focuses search, `n` focuses the new-todo field, `Esc` collapses the
-  open detail. Row actions appear on hover or keyboard focus.
+- **Keyboard** — `/` focuses search, `n` focuses the new-todo field while the add form is
+  open, `Esc` collapses the open detail. Row actions appear on hover or keyboard focus.
 - **Reachable from the LAN and from a tunnel** — the routes defer to the Host's connection fence
   (which honours `--trusted-host`); the plugin's own loopback check is only the fallback for a
   Host without that service. `/health` reports `fence` so you can see which one is in force.
@@ -253,12 +343,12 @@ produces noise, and a noisy list is worse than an empty one:
 The boundary: it **records, it never starts work**. The list belongs to the human, and
 starting a task stays a human decision (see the non-goals in [ROADMAP](docs/ROADMAP.md)).
 
-
 Capture is not allowed to become noise. Before an item is written, the same normalized title
 (full-width, case, spacing and punctuation folded away), a close paraphrase within the last 72
 hours (Dice similarity over character bigrams, 0.8), and the same errand finished in the last 7
 days are all refused with a reason on the record; archived and cancelled rows do not block a
 new one. The rules live in `lib/capture.js` and are tested on their own.
+
 ### HTTP API
 
 The panel talks to the host over these routes. They are fenced by the host connection
@@ -269,9 +359,10 @@ fence when that service is present, and by a strict loopback check otherwise.
 | GET | `/api/global-todo/list` | `status`, `query`, `tag`, `sort`, `limit` — the reply carries `matched` and `truncated` when the page was cut |
 | GET | `/api/global-todo/dirs` | `path?` — list subdirectories for the panel's built-in folder picker (the shell's own picker is preferred when mounted) |
 | GET | `/api/global-todo/get` | `id` |
-| GET | `/api/global-todo/export` | — (the store's own JSON document, for backup or migration) |
+| GET | `/api/global-todo/export` | — (the store's own JSON document; `?format=md` gives a Markdown task list) |
 | POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge, dryRun? }` — `replace` is an exact round trip, `merge` updates by id and appends (what the panel sends); `dryRun` returns `wouldCreate` / `wouldUpdate` and writes nothing |
 | POST | `/api/global-todo/reminders/ack` | `{ ids }` — stop listing these passed deadlines as due |
+| POST | `/api/global-todo/note` | `{ id, text }` — append a progress note |
 | POST | `/api/global-todo/capture` | `{ sessionId? }` — ask the current conversation to collect its follow-ups |
 | POST | `/api/global-todo/bulk` | `{ ids, status?, addTags?, removeTags? }` — one change across a selection; a stale id lands in `unmatched` instead of failing the batch |
 | POST | `/api/global-todo/ingest` | `{ items: [{ title, source: { kind }, confidence }], dryRun? }` with `Authorization: Bearer <settings.ingestToken>` — external items; below `ingestConfirmBelow` they wait in the inbox |
@@ -282,6 +373,8 @@ fence when that service is present, and by a strict loopback check otherwise.
 | POST | `/api/global-todo/remove` | `{ id }` |
 | POST | `/api/global-todo/restore` | `{ todo }` — put a removed record back verbatim (undo) |
 | POST | `/api/global-todo/review` | `{ id, decision: confirm\|reject }` — answer an agent's completion |
+| GET | `/api/global-todo/report?days=7` | what the agents finished in the window, and the files it touched |
+| GET | `/api/global-todo/session?id=` | what a bound conversation last said (`tail`, `alive`, `dir`) |
 | POST | `/api/global-todo/link` | `{ id, add?: [...], remove?: [value \| index] }` |
 | POST | `/api/global-todo/dispatch` | `{ id, mode?: auto\|bound\|new\|current, sessionId?, dir? }` |
 | POST | `/api/global-todo/assign` | `{ ids, items?, target?, dir? }` — hand several todos over in one call; an id that matches nothing comes back instead of being sent elsewhere |
@@ -347,7 +440,7 @@ and [docs/ROADMAP.md](docs/ROADMAP.md) for what could come next.
 npm run check     # parse every file, assert the shipping shape, and — when a DSH
                   # profile is present — validate every tool schema against the
                   # Host's own validator
-npm test          # 100+ unit, contract and bundle tests, zero dependencies
+npm test          # 257 unit, contract and bundle tests, zero dependencies
 npm run verify    # both
 npm run check:matrix  # the running dsh against engines.dsh, then the manifest,
                       # bundle and tool-schema contracts (no preview writes)
@@ -364,6 +457,7 @@ page refresh; host-half edits need a host restart.
 ```sh
 npm run preview       # render the panel to preview/panel.html (+ detail and selection variants)
 npm run screenshots   # re-photograph those previews into docs/screenshots/, 1280×720
+npm run tour          # rebuild docs/screenshots/tour.gif from those PNGs (needs ffmpeg)
 ```
 
 The PNGs under `docs/screenshots/` ship with the package and are embedded in both
@@ -371,20 +465,30 @@ READMEs, so re-run `npm run screenshots` whenever the panel UI changes.
 
 ```text
 lib/
-  index.js     host entry: store + service + dispatcher + the three surfaces
-  store.js     one JSON file: atomic writes, serialized updates, tolerant loads
-  model.js     the todo entity: validation, patches, status, attachments, activity
-  links.js     attachment rules (pure: no filesystem access)
-  service.js   the single write path, filters and sorting
-  routes.js    the HTTP surface for the panel
-  tools.js     the ten agent tools
-  dispatch.js  handing a todo to an agent session
-  errors.js    typed failures with stable machine codes
-  client.js    the browser half (panel + sidebar entry)
-test/          unit, service, tool, route, dispatch, bundle and manifest tests
-tools/         preview.mjs — render the panel to static HTML without a Host
-               screenshot.mjs — photograph those previews (borrows the profile's Playwright)
-docs/          DESIGN.md (data model and rejected alternatives), ROADMAP.md
+  index.js       host entry: store + service + dispatcher + the optional surfaces
+  store.js       one JSON file: atomic writes, serialized updates, tolerant loads
+  model.js       the todo entity: validation, patches, status, attachments, steps, review, notes
+  links.js       attachment rules (pure: no filesystem access)
+  service.js     the single write path, filters, sorting and the dispatch prompt
+  routes.js      the HTTP surface for the panel
+  tools.js       the ten agent tools
+  dispatch.js    handing a todo to an agent session (auto / bound / new / current)
+  completion.js  the clean-turn watcher behind automatic completion
+  capture.js     the capture duplicate gate (title, paraphrase, recent done)
+  ingest.js      the external door and its inbox rules
+  markdown.js    Markdown export and tolerant import
+  report.js      the weekly aggregate over completion records
+  reminders.js   the due rule behind the reminder strip
+  settings.js    host-side switches and the automatic-collect policy
+  metrics.js     in-memory counters reported by /health
+  diagnostics.js the bounded client error log
+  errors.js      typed failures with stable machine codes
+  client.js      the browser half (panel + sidebar entry)
+test/            unit, service, tool, route, dispatch, bundle and manifest tests
+tools/           preview.mjs — render the panel to static HTML without a Host
+                 screenshot.mjs — photograph those previews (borrows the profile's Playwright)
+                 tour.mjs — assemble the README tour GIF from those PNGs
+docs/            DESIGN.md (data model and rejected alternatives), ROADMAP.md
 ```
 
 Contributions are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md) first.
@@ -395,6 +499,7 @@ Questions, bug reports and ideas go to [Discussions](https://github.com/LUgABeEE
 When reporting a bug, include the DSH version, the plugin version from the panel footer, your OS and
 the steps that reproduce it; a screenshot of the notice is worth more than a paragraph. Security
 issues go through [SECURITY.md](SECURITY.md) instead, not the discussion board.
+
 ## Security
 
 The HTTP surface is local-only, the list is a local file, and no credential is ever stored.

package/README.zh.md

@@ -14,7 +14,7 @@
 dsh plugin add dsh-global-todo
 ```
 
-[English](README.md) · [每个条件状态都有基线图](#截图) · [设计说明](docs/DESIGN.md)
+[English](README.md) · [5 分钟上手](docs/QUICKSTART.md) · [常见问题](docs/FAQ.md) · [每个条件状态都有基线图](#截图) · [设计说明](docs/DESIGN.md)
 
 ---
 
@@ -33,6 +33,85 @@ DSH 自带的 `todo_write` 属于**某一个 agent 会话**：整表替换、三
 | 交给 Agent | 无 | **一键：复用已绑定会话，或新开一个** |
 | 存储 | 会话事件日志 | 一个 JSON 文件，能 `cat`、能手改、能 diff、能备份 |
 
+## 0.9 / 0.10 补了什么（以及再往前两版）
+
+六个这两份 README 一直没讲的能力：会话回读与原话是 0.9 的，Markdown 与本周报告是 0.10 的，
+步骤是 0.8 的，待确认标记是 0.7 的——后两个此前只写在 CHANGELOG 里。每一个都改变了记录能装什么，
+或者改变了事后能拿它做什么。
+
+### 步骤：待办里的一份计划
+
+一条待办最多 20 个步骤、每步 200 字（`lib/model.js` 的 `LIMITS`）。步骤是 `{ text, done }`——
+一条工作里的一行，不是有自己 id 和状态的子任务。
+
+- **加**：新增表单的「更多字段」→ 步骤，一行一步。
+- **勾**：详情里每步一个勾选框；行上显示「步骤 2/5」。
+- **交出去**：派发提示词会把步骤编号，已完成的加 `[已完成]` 前缀。
+- **导出**：Markdown 里写成缩进的 `- [ ]`，导入时读回来。
+
+### 原话：这条是从哪句话来的
+
+`evidence` 是抓取时那条待办**来自的原话**，逐字引用，最多 300 字。`global_todo_capture` 会向模型要它，
+`global_todo_add` 也收，详情里以引用块显示在「原话」下面；你自己敲的条目没有这一项。
+
+它只为一件事存在：没有出处的一次抓取，过几天看起来就像一句观点。Markdown 导出里也有这一行（`原话:`）。
+
+### 会话回读
+
+派发是在**另一个对话**里开工，所以详情要能回答「它说了什么」，不用切过去。
+`GET /api/global-todo/session?id=` 返回 `alive`、`dir` 和最后一条 assistant 消息的 `tail`；
+详情里就是「会话回读」：在跑 / 已休眠、最后一句，以及一个打开该对话的按钮。
+
+tail 有上限、只在内存里：200 个会话、每个 400 字，来自每条 `assistant/message`。不落盘，宿主一重启就忘。
+查不到 tail 是正常情况——这个进程没见那个对话说过话。
+
+### 待确认：Agent 的「做完了」只是声明
+
+Agent 收尾时（`global_todo_done`，或干净一轮后的自动收尾），记录会变成已完成，**同时**带上
+`review: { pending: true }`。行上有「待确认」徽标，顶部多一个带计数的「待确认」筛选。
+
+| 你的回答 | 结果 |
+|---|---|
+| **确认完成** | 保持已完成，标记清除，动态里记下是谁确认的 |
+| **退回清单** | 回到 `open`，`doneAt` 与完成记录清空，动态里加一条 `reopened` |
+
+两个回答都按**人**的动作记录。退回不删除任何东西：标题、描述、步骤、附件、进展记录都还在。
+
+### Markdown 进与出
+
+JSON 导出是往返格式；Markdown 是拿来读、diff、手改的那份：
+
+```text
+- [ ] 标题
+      优先级: 高 · 截止: 2026-10-21T18:00 · 标签: 发布, 文档
+      原话: …
+      描述: 第一行
+      - [x] 一步
+```
+
+| 方向 | 入口 | 行为 |
+|---|---|---|
+| 出 | **更多操作 → 导出 Markdown**，或 `GET /export?format=md` | 按「未完成 / 已完成 / 已归档」分组，元数据缩进在每条下面 |
+| 入 | **更多操作 → 导入**（选 `.md`），或 `POST /import { markdown }` | 走正常 `create` 新建；Markdown 没有 id，所以**永远不会覆盖**已有记录 |
+
+解析是容错的：不认识的行直接忽略，日期解析失败就丢掉那一项，整份文件里没有一行 `- [ ]` 会明确报错。
+字段标注固定是中文（`优先级 / 截止 / 标签 / 原话 / 描述 / 附件 / #`），导入按同一套读。
+
+### 本周报告
+
+**更多操作 → 本周报告**（`GET /report?days=7`）回答「这一周动了什么、有没有落到代码上」。
+全部从完成记录推出来，不存任何东西。
+
+| 字段 | 含义 |
+|---|---|
+| `finished` | 窗口内完成的条目，最新在前，带完成者和说明 |
+| `sessions` | 这些完成来自多少个不同的对话 |
+| `created` | 窗口内新增的条数 |
+| `pendingReview` | 已完成但还没人回答的条数 |
+| `files` | 触及的文件，按次数排序——列 12 个，`fileCount` 是总数 |
+
+`days` 超过 90 会被压到 90；缺省或非正数按 7 算。
+
 ## 截图
 
 ![面板：统计胶囊、按紧迫度分组、逾期行有强调](docs/screenshots/panel.png)
@@ -56,6 +135,8 @@ DSH 自带的 `todo_write` 属于**某一个 agent 会话**：整表替换、三
 HTML（不依赖宿主、零依赖），再以 1280×720 拍进 `docs/screenshots/`。Playwright 不是依赖——工具
 借的是 DSH profile 里已经装好的那份，或 `DSH_PLAYWRIGHT` 指向的那份。
 
+每张图显示什么状态、什么时候重新生成，见 [docs/screenshots/README.md](docs/screenshots/README.md)。
+
 ## 环境要求
 
 - DeepSeek Harness `0.2.x`（按 `0.2.1-rc.2` 开发与验证；`engines.dsh` 是 `>=0.2.0-rc.1 <0.3.0`，
@@ -80,7 +161,7 @@ dsh plugin --profile web add /绝对路径/dsh-global-todo
 再刷新页面。侧栏会出现「待办」入口。
 
 npm 上的包才是事实来源。社区目录可能落后于 npm、或指向某个旧 release；需要确定版本时
-直接钉版本（`dsh plugin --profile web add dsh-global-todo@0.4.0`）。
+直接钉版本（`dsh plugin --profile web add dsh-global-todo@0.10.0`）。
 
 回滚：
 
@@ -105,7 +186,7 @@ dsh plugin --profile web remove dsh-global-todo
 - **详情**：就地改标题/描述/优先级/截止；挂上或摘掉文档与地址（每条都带「打开 / 复制路径」）；
   查看动态（谁在什么时候做了什么）。
 - **删除可撤销**：删掉的记录保留 8 秒，点「撤销」原样恢复——同一个 id、同一个加入时间、同样的附件。
-- **键盘**：`/` 聚焦搜索，`n` 聚焦新建，`Esc` 收起详情；行内操作在悬停或键盘聚焦时出现。
+- **键盘**：`/` 聚焦搜索；新增输入框展开后，`n` 聚焦它；`Esc` 收起详情。行内操作在悬停或键盘聚焦时出现。
 - **访问地址**：面板可以正常从宿主的**本机**、**受信任的局域网地址**（`--trusted-host` 里那些，如 `192.168.1.10:3080`）以及隧道访问——路由会交给宿主的连接围栏判断；只有宿主的围栏**不存在**时才退回「只接受本机请求」的保守检查。`/health` 里的 `fence` 会告诉你当前实际是哪一种。
 - **自动获取（可关，默认关）**：面板上的「自动获取」开关。打开后——你在某个对话里**正常收完一轮**、那个对话**安静满 30 分钟**、且**你人就在那个对话里**（不是派发目标/子 Agent/后台任务），插件才会自动问它一次「有没有要跟进的事」。中断/失败的轮次不问。**它问过之后，只有你在那个对话里再说一句话才会重新问**——因为那条提问本身就是对话里的一条消息，会重置安静计时、并让它自己的回答收尾成一轮，曾经正是这一点让同一个对话整夜追着自己反复问；冷却只是次要的阻尼。开关是**宿主状态**（面板关着也生效，`/health` 可见），关掉就完全靠你和 Agent 手动记。另外每个对话分组旁边有一个**「豁免」**按钮：点一下就把**该对话所在的工作区**整个排除在自动获取之外（再点一下取消）。这是给由机器驱动的对话准备的——比如微信机器人所在的聊天区，它们的会话重启后会换新 id，所以豁免**记在目录上而不是某一条对话上**，才不会悄悄失效。
 - **主动记**：插件会往 system prompt 里注入一段引导，列出该主动记的具体情形（跨会话的跟进、「先做 X 再 Y」、一轮收尾时发现还有一步），并明确写上「问用户要不要记是错的，直接记」。
@@ -148,8 +229,29 @@ dsh plugin --profile web remove dsh-global-todo
 | `global_todo_reopen` | 把**被误标完成**的一条标回未完成（只做 `done` / `cancelled` → `open`）；本来就未完成的会被拒绝，动作按 agent 记进活动轨迹 |
 | `global_todo_remove` | 永久删除（做完的请标记，不要删） |
 
-系统提示词里会注入一小段用法指引，让模型知道这份清单存在、以及它和内建 `todo_write`
-的区别。不想要就把 `guidance` 设成 `false`。
+### 实际联通检查
+
+测试用的是替身；`npm run check:live` 检查的是**真正接上线的**宿主：面板实际会调的路由、它实际读的清单，
+以及一条「删掉再撤销」之后仍然完整的记录。它会临时建一条记录，往返后逐字段比对（id、加入时间、附件、
+标签、级别、截止、描述），确认绑定记录带 `sessionAlive` / `sessionDir`，最后即使失败也会删掉这条临时记录。
+它需要一个在跑的宿主，所以不在 `verify` 里。
+
+### 主动抓取
+
+插件会往 system prompt 里注入一段引导（用 `guidance: false` 关掉）。它把两侧都写清楚：只写「记得记事」的
+提示词只会制造噪音，而吵闹的清单比空清单更糟。
+
+- **主动记**：用户提到需要跨会话跟进的事（等对方回复、下周要交、待确认的决定、答应别人的事）、
+  一轮结束时还有一步不该在本会话继续、或用户说「记一下 / 别忘了 / 回头办」；
+- **不要记**：你这一步就能做完的、本会话内的计划、纯闲聊；
+- 记完用**一句话**说明记了什么，别复述整条描述；
+- 用户说**「抓一下待办」**，就扫最近对话，用 `global_todo_capture` 一次登记，再回一句汇总。
+
+边界是：它**只负责记，从不擅自开工**。清单属于人，开不开工是人决定的（见 [ROADMAP](docs/ROADMAP.md) 里的非目标）。
+
+抓取不能变成噪音。写进去之前，同一个规范化标题（全半角、大小写、空格、标点都折叠掉）、
+最近 72 小时内意思很接近的转述（按字符二元组的 Dice 相似度，0.8），以及 7 天内刚做完的同一件事，
+都会被拒绝，并在记录上写出原因；已归档和已取消的条目不挡新条目。规则在 `lib/capture.js`，单独测试。
 
 ### HTTP 接口
 
@@ -161,7 +263,7 @@ dsh plugin --profile web remove dsh-global-todo
 | GET | `/api/global-todo/list` | `status`、`query`、`tag`、`sort`、`limit`——被截断时响应带 `matched` 与 `truncated` |
 | GET | `/api/global-todo/dirs` | `path?`——列子目录，供面板内置的目录浏览器使用（宿主自己的选择器在时会优先） |
 | GET | `/api/global-todo/get` | `id` |
-| GET | `/api/global-todo/export` | ——（存储用的那份 JSON 文档，用于备份或迁移） |
+| GET | `/api/global-todo/export` | ——（存储用的那份 JSON 文档；`?format=md` 给 Markdown 任务列表） |
 | POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge, dryRun? }`——`replace` 是无损往返，`merge` 同 id 覆盖、新 id 追加（面板用的是这个）；`dryRun` 只返回 `wouldCreate` / `wouldUpdate`，不落盘 |
 | POST | `/api/global-todo/reminders/ack` | `{ ids }`——这些已到期的提醒不再列出来 |
 | POST | `/api/global-todo/note` | `{ id, text }`（追加进展记录） |
@@ -175,6 +277,8 @@ dsh plugin --profile web remove dsh-global-todo
 | POST | `/api/global-todo/remove` | `{ id }` |
 | POST | `/api/global-todo/restore` | `{ todo }` —— 原样还原被删除的记录（撤销） |
 | POST | `/api/global-todo/review` | `{ id, decision: confirm\|reject }` —— 回答 Agent 的完成声明 |
+| GET | `/api/global-todo/report?days=7` | 这段时间里 Agent 完成了什么、触及了哪些文件 |
+| GET | `/api/global-todo/session?id=` | 绑定的会话最后说了什么（`tail` / `alive` / `dir`） |
 | POST | `/api/global-todo/link` | `{ id, add?: [...], remove?: [值 或 下标] }` |
 | POST | `/api/global-todo/dispatch` | `{ id, mode?: auto\|bound\|new\|current, sessionId?, dir? }` |
 | POST | `/api/global-todo/assign` | `{ ids, items?, target?, dir? }`——一次把多条交给 Agent；配不上的 id 原样报回，不擅自送到别处 |
@@ -235,7 +339,7 @@ epoch 与 ISO，派发提示词也带上它。因为「这事什么时候落到
 ```sh
 npm run check     # 解析全部文件、校验发布形态；本机有 DSH profile 时，还会用宿主
                   # 自己的校验器逐条验证工具 schema
-npm test          # 100+ 单元/契约/bundle 测试，零依赖
+npm test          # 257 单元/契约/bundle 测试，零依赖
 npm run verify    # 两者都跑
 npm run check:matrix  # 当前 dsh 与 engines.dsh 的实际匹配，再跑 manifest/bundle/
                       # 工具 schema 三类契约（不写 preview）
@@ -251,6 +355,7 @@ CI 里也没有构建产物。改 `lib/client.js` 刷新页面即生效；改宿
 ```sh
 npm run preview       # 把面板渲染成 preview/panel.html（另附详情态与选择态）
 npm run screenshots   # 把这些预览重新拍成 docs/screenshots/，1280×720
+npm run tour          # 用这些 PNG 重新拼 docs/screenshots/tour.gif（需要 ffmpeg）
 ```
 
 `docs/screenshots/` 下那几张 PNG 会随包发布、并嵌在两份 README 里，所以面板 UI 一改就要重跑
@@ -258,20 +363,30 @@ npm run screenshots   # 把这些预览重新拍成 docs/screenshots/，1280×72
 
 ```text
 lib/
-  index.js     宿主入口：store + service + dispatcher + 三个挂载面
-  store.js     一个 JSON 文件：原子写、串行更新、容错读取
-  model.js     待办实体：校验、补丁、状态、附件、动态
-  links.js     附件规则（纯函数，不碰文件系统）
-  service.js   唯一写入路径、筛选与排序
-  routes.js    面板用的 HTTP 接口
-  tools.js     十个 Agent 工具
-  dispatch.js  把待办交给 agent 会话
-  errors.js    带机器码的类型化失败
-  client.js    浏览器半区（面板 + 侧栏入口）
-test/          单元、service、工具、路由、派发、bundle、manifest 测试
-tools/         preview.mjs —— 不依赖宿主，把面板渲染成静态 HTML
-               screenshot.mjs —— 把预览拍成 PNG（借 profile 里的 Playwright）
-docs/          DESIGN.md（数据模型与取舍）、ROADMAP.md
+  index.js       宿主入口：store + service + dispatcher + 可选挂载面
+  store.js       一个 JSON 文件：原子写、串行更新、容错读取
+  model.js       待办实体：校验、补丁、状态、附件、步骤、待确认、进展
+  links.js       附件规则（纯函数，不碰文件系统）
+  service.js     唯一写入路径、筛选、排序与派发提示词
+  routes.js      面板用的 HTTP 接口
+  tools.js       十个 Agent 工具
+  dispatch.js    把待办交给 agent 会话（auto / bound / new / current）
+  completion.js  干净一轮之后的自动收尾观察者
+  capture.js     抓取去重闸门（同名、近义转述、刚完成）
+  ingest.js      外部写入入口与收件箱规则
+  markdown.js    Markdown 导出与容错导入
+  report.js      从完成记录推出来的周报
+  reminders.js   到点提醒的判定规则
+  settings.js    宿主侧开关与自动获取策略
+  metrics.js     /health 里的进程内计数
+  diagnostics.js 有上限的面板错误日志
+  errors.js      带机器码的类型化失败
+  client.js      浏览器半区（面板 + 侧栏入口）
+test/            单元、service、工具、路由、派发、bundle、manifest 测试
+tools/           preview.mjs —— 不依赖宿主，把面板渲染成静态 HTML
+                 screenshot.mjs —— 把预览拍成 PNG（借 profile 里的 Playwright）
+                 tour.mjs —— 用这些 PNG 拼 README 里的 tour.gif
+docs/            DESIGN.md（数据模型与取舍）、ROADMAP.md
 ```
 
 欢迎贡献，先读 [CONTRIBUTING.md](CONTRIBUTING.md)。
@@ -281,6 +396,7 @@ docs/          DESIGN.md（数据模型与取舍）、ROADMAP.md
 问题、bug 和想法都发到 [Discussions](https://github.com/LUgABeEEE/dsh-global-todo/discussions)。
 报 bug 时带上 DSH 版本、面板页脚里的插件版本、系统，以及能复现的步骤；提示语截图比一段描述更有用。
 安全问题请走 [SECURITY.md](SECURITY.md)，不要发在讨论区。
+
 ## 安全
 
 HTTP 接口只服务本机，清单是本地文件，任何凭据都不会被存储。

package/docs/DESIGN.md

@@ -57,6 +57,27 @@ $DSH_HOME/global-todo/todos.json     ← { version: 1, todos: [ … ] }
   version, and a future migration step would run before the first write, keeping the old
   file as a backup.
 
+## The panel owns its own scroll
+
+A list longer than the slot must scroll **inside** the panel: the header and toolbar stay put, and
+the rows move. That sounds obvious and was broken for two releases, because a flex column does not
+do it by default.
+
+- **The bug.** `.gt-inner` is a flex item (`flex: 1`) of `.gt-root`. A flex item's default
+  `min-height` is `auto`, so the column refused to shrink below its content: with a long list it
+  measured **2236px inside a 680px slot**, `.gt-groups` therefore never had a scroll range, and the
+  host's own overflow clipped everything below the fold. Measured proof: a wheel over the list left
+  `scrollTop` at **0**.
+- **The fix is two declarations**: `.gt-inner { min-height: 0 }` (let the column shrink) and
+  `.gt-root { overflow: hidden }` (the panel clips, so the list is the only scroll owner). After:
+  `.gt-groups` is 480px of viewport over a 2036px list, and a wheel moves it 0 → 800.
+- **Why it shipped.** Every screenshot in this repository is a server-rendered preview: no layout
+  engine, no wheel, no scrollbar. A static image cannot show that a list is stuck at the top. So the
+  render check now asserts the three declarations that make the contract
+  (`overflow: hidden` on the panel, `min-height: 0` on the column, `overflow: auto` on the list),
+  and anything about scrolling, focus or hover has to be measured with a real browser instead of
+  looked at.
+
 ## Reading the conversation back
 
 Handing work over used to be one-way: the panel knew a conversation was bound, and nothing about