dsh-global-todo 0.7.2 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,35 @@
+## [0.9.0] — 2026-10-20
+
+Competitive ground: the hand-off now has a return path, capture carries its source, and the
+first screen says what the plugin is for.
+
+- **Session read-back.** Every `assistant/message` updates a bounded in-memory tail (200 sessions,
+  400 chars); `GET /session?id=` returns it with `alive` / `dir`, and the detail shows 「会话在跑 /
+  已休眠」, the last thing the conversation said, and a button to open it. No disk read per row, no
+  new persistence.
+- **Evidence on captured items.** `evidence` is the sentence an item came from, quoted verbatim
+  (≤300 chars), asked for by the capture prompt and shown under 「原话」 in the detail. A todo you
+  typed yourself simply has none.
+- **A landing page instead of a manual.** Both READMEs open with three sentences, a 20-second
+  state tour (`docs/screenshots/tour.gif`, built reproducibly by `npm run tour`), and the install
+  command — the reference material moved below the fold.
+
+## [0.8.0] — 2026-10-20
+
+A todo can carry its plan, and the plan is what the agent receives.
+
+- **`steps[]` on a todo**: `{ text, done }`, up to 20 steps of 200 characters. Strings are accepted
+  wherever steps are (create, agent tools), a blank line is not a step, and a longer plan is
+  refused rather than truncated — twenty steps means the todo should have been split.
+- **The dispatch prompt numbers them**, marking the ones already done. Handing over "1. 对齐版本号
+  2. 跑 verify 3. 打 tag" is worth more than handing over a paragraph.
+- **The panel shows progress without opening the row** (`步骤 2/4` in the metadata), renders the
+  ticks in the detail, and takes one step per line in the add form.
+- **Agent guidance says so too**: multi-round work should be recorded with 3–6 steps, and a
+  finished step is one `global_todo_update`.
+- Replacement semantics (like `links`): the array travels whole through `applyPatch`, so there is
+  still one validation and one write path.
+
 ## [0.7.2] — 2026-10-20
 
 The roadmap audited against the tree, and the review feature brought up to the same standard

package/README.md

@@ -1,12 +1,24 @@
 # dsh-global-todo
 
-**One todo list for the whole DeepSeek Harness, owned by you and written by your agent too.**
+**A cross-session todo list for DeepSeek Harness: one file you own, written by you and your
+agent, and handed to a conversation in one click.**
 
-Every entry records when it was added, carries a description, can attach any number of
-documents and addresses, and can be handed to an agent session with one click — so
-"continue this" is a button, not a paragraph of context you retype.
+Three things it does that a session-local plan cannot:
 
-[中文说明](README.zh.md)
+1. **One JSON file is the whole list.** `cat`, diff, commit it, put it on a NAS, carry it to
+   another machine. Nothing lives inside a session log.
+2. **Hand-off is a button, not a paragraph.** Four modes, the working directory checked, and
+   the todo's own **steps** arrive as a numbered plan.
+3. **An agent saying "done" is a claim.** It lands in **待确认 / Needs review** until a person
+   confirms it — or sends it back to the list.
+
+![The panel in use: list, detail, steps, review, inbox, reminders, selection](docs/screenshots/tour.gif)
+
+```sh
+dsh plugin add dsh-global-todo
+```
+
+[中文说明](README.zh.md) · [Every state has a baseline image](#screenshots) · [Design notes](docs/DESIGN.md)
 
 ---
 
@@ -203,7 +215,7 @@ Your list is not touched by install or uninstall: it lives outside the plugin, a
 
 | Tool | Purpose |
 |---|---|
-| `global_todo_add` | Record an item — description, attachments, tags, priority, due time |
+| `global_todo_add` | Record an item — description, attachments, steps, tags, priority, due time |
 | `global_todo_note` | Append a progress note — where you are, what blocks you, who must decide |
 | `global_todo_capture` | **Record a batch**: for 「抓一下待办」 or a turn that produced several follow-ups; each entry is validated on its own |
 | `global_todo_list` | Query by state, tag or text; every row carries its creation time |
@@ -264,7 +276,7 @@ fence when that service is present, and by a strict loopback check otherwise.
 | 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 |
 | GET | `/api/global-todo/health` | — (store location, counts, dispatch capabilities, plus **tool registration** and **whether the completion watcher attached** — both fail quietly, so both are reported — and `metrics`: dispatch success rate, agent tool calls, list growth; `autoCollect`: why each waiting conversation was or was not asked, counters, and how the settings file loaded) |
-| POST | `/api/global-todo/create` | `{ title, description?, links?, tags?, priority?, dueAt? }` |
+| POST | `/api/global-todo/create` | `{ title, description?, links?, steps?, tags?, priority?, dueAt? }` |
 | POST | `/api/global-todo/update` | `{ id, ...fields, by?: human\|agent }` |
 | POST | `/api/global-todo/status` | `{ id, status, by?: human\|agent }` |
 | POST | `/api/global-todo/remove` | `{ id }` |

package/README.zh.md

@@ -1,11 +1,20 @@
 # dsh-global-todo · 全局待办
 
-**一份属于你的全局待办清单，Agent 和你读写同一份。**
+**一份跨会话的待办清单：一个属于你的文件，你和 Agent 读写同一份，一键交给某个对话继续干。**
 
-每条都会记下**加入时间**，可以带描述，可以挂**任意多个相关文档和地址**，
-还能**一键交给 Agent 继续干**——「接着做这个」是一个按钮，而不是一段你每次都要重打的上下文。
+三件会话级计划做不到的事：
 
-[English](README.md)
+1. **一个 JSON 文件就是全部**。能 `cat`、能 diff、能提交进仓库、能放 NAS、换机带走——不藏在任何会话日志里。
+2. **交接是一个按钮，不是一段话**。四种模式、会先检查工作目录，待办自己的**步骤**会作为编号计划一起交出去。
+3. **Agent 说「做完了」不算数**。它先进**待确认**，人点头才算完成，或者被退回清单。
+
+![面板实况：列表、详情、步骤、待确认、收件箱、提醒、批量选择](docs/screenshots/tour.gif)
+
+```sh
+dsh plugin add dsh-global-todo
+```
+
+[English](README.md) · [每个条件状态都有基线图](#截图) · [设计说明](docs/DESIGN.md)
 
 ---
 
@@ -128,7 +137,7 @@ dsh plugin --profile web remove dsh-global-todo
 
 | 工具 | 用途 |
 |---|---|
-| `global_todo_add` | 登记一条：描述、附件、标签、优先级、截止时间；同时记下「在哪个工作目录、哪个会话里写的」 |
+| `global_todo_add` | 登记一条：描述、附件、步骤、标签、优先级、截止时间；同时记下「在哪个工作目录、哪个会话里写的」 |
 | `global_todo_note` | 追加一条**进展记录**（做到哪了、卡在哪、需要谁做什么）；不改写你的描述 |
 | `global_todo_capture` | **一次登记多条**（批量抓取）：用户说「抓一下待办」，或你一轮里发现好几件要跟进的；逐条校验，坏的那条只跳过它自己 |
 | `global_todo_list` | 按状态/标签/关键词查询，每条都带上加入时间 |
@@ -160,7 +169,7 @@ dsh plugin --profile web remove dsh-global-todo
 | POST | `/api/global-todo/bulk` | `{ ids, status?, addTags?, removeTags? }`——一次改一整批；失效的 id 进 `unmatched`，不会让整批失败 |
 | POST | `/api/global-todo/ingest` | `{ items: [{ title, source: { kind }, confidence }], dryRun? }`，带 `Authorization: Bearer <settings.ingestToken>`——外部条目；置信度低于 `ingestConfirmBelow` 的先进收件箱 |
 | GET | `/api/global-todo/health` | —（数据位置、统计、派发能力，以及**工具注册状态**与**自动收尾观察者是否挂上**——这两种失败是静默的，所以必须能查；还有 `metrics`：派发成功率、工具调用次数、清单增长；`autoCollect`：每个候选对话**为什么被问/没被问**、计次，以及设置文件是怎么加载进来的） |
-| POST | `/api/global-todo/create` | `{ title, description?, links?, tags?, priority?, dueAt? }` |
+| POST | `/api/global-todo/create` | `{ title, description?, links?, steps?, tags?, priority?, dueAt? }` |
 | POST | `/api/global-todo/update` | `{ id, ...字段, by?: human\|agent }` |
 | POST | `/api/global-todo/status` | `{ id, status, by?: human\|agent }` |
 | POST | `/api/global-todo/remove` | `{ id }` |

package/docs/DESIGN.md

@@ -57,6 +57,56 @@ $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.
 
+## Reading the conversation back
+
+Handing work over used to be one-way: the panel knew a conversation was bound, and nothing about
+what came of it. The read-back closes that loop with the cheapest mechanism available.
+
+- **Where the text comes from.** The plugin already listens on `session/event`; every
+  `assistant/message` also updates a bounded cache (200 sessions, 400 characters each). Nothing is
+  read from disk per row and nothing is persisted — a stale tail is better than a slow panel, and
+  the panel says when it is dormant.
+- **Why not read the session log on demand.** Opening a row is the most common click in the panel.
+  A per-row disk read would make it wait on I/O, and a conversation that the Host had unloaded
+  answers nothing anyway.
+- **The route is separate** (`GET /session?id=`): `/list` is polled, a tail is not, and folding
+  them together would read every session on every poll. A missing tail is a normal answer, not an
+  error.
+- **What the person sees:** 会话在跑 / 会话已休眠, the last thing it said (three lines, full text in
+  the tooltip), and a button that opens that conversation.
+
+## The sentence an item came from
+
+A captured todo is somebody's summary of what a person said, which is exactly the step where
+meaning drifts. So capture now carries `evidence`: the sentence, quoted verbatim, at most 300
+characters, stored on the record and shown under 「原话」 in the detail (a quiet blockquote, not a
+badge — it is reference material, not a status).
+
+- The capture prompt asks for it in as many words: quote, do not paraphrase.
+- A todo the person typed themselves has no evidence, and that is not an error — the field is
+  empty rather than absent, so the panel never has to guess.
+- Too long is refused, like every other text field: evidence that is not the sentence is not
+  evidence.
+
+## A plan inside the todo
+
+A todo is one line, but the work behind it is often five steps. Rather than grow a second object
+(a "project", a "plan file"), a todo may carry `steps[]` — text plus a tick, order is the plan.
+
+- **Why inside the todo:** the dispatch prompt is the product here. Handing an agent "ship the
+  plugin" is a paragraph; handing it "1. 对齐版本号 2. 跑 verify 3. 打 tag 4. 补截图" is a plan it
+  can execute and report against. The steps are also what a person reviews afterwards.
+- **Shape:** `{ text, done }`, capped at `LIMITS.steps` (20) and 200 characters per step. Strings
+  are accepted wherever an array of steps is (create, agent tools) so a caller never has to spell
+  out `{ done: false }`; a blank line is a typo, not a step, and a plan longer than the cap is
+  refused rather than truncated — twenty steps means the todo should have been split.
+- **Replacement, not patching:** `steps` travels as a whole array through `applyPatch`, the same
+  rule as `links`. Toggling one tick is a client-side rewrite of the array, which keeps one write
+  path and one validation.
+- **Where it shows:** the row's metadata gets `步骤 2/4` (progress without opening anything), the
+  detail renders the ticks, the panel's add form takes one step per line, and the dispatch prompt
+  numbers them with `[已完成]` on the ones already behind us.
+
 ## On a wide window, the detail stands beside the list
 
 Expanding a row inline is right on a narrow window and wrong on a wide one: the list jumps, the

package/docs/ROADMAP.md

@@ -152,17 +152,15 @@ reminder) photographed into `docs/screenshots/` by `npm run screenshots`, and
 Ordered by value against effort, and audited against the tree on 2026-10-20 — "today"
 means what the code actually does, not what the last plan hoped.
 
-### 1. Checklist inside a todo — the highest-value gap
+### 1. ~~Checklist inside a todo~~ — landed in 0.8.0
 
-Large items ("ship the plugin") are a list of steps wearing a title. Proposed: an optional
-`steps[]` (text + done) per todo, rendered as checkboxes in the row and the detail, and
-shipped to the agent as a numbered plan in the dispatch prompt.
+`steps[]` (text + tick) ships on the todo, renders as `步骤 2/4` in the row and as ticks in the
+detail, is editable from the panel's add form, and travels in the dispatch prompt as a numbered
+plan. `normalizeSteps()` in `lib/model.js`, `dispatchPrompt()` in `lib/service.js`; tests in
+`test/model.test.mjs` and `test/service.test.mjs`.
 
-- Today: nothing named `steps` exists in `lib/`; `grep -rn steps lib` is empty.
-- Effort: medium — model (create / `applyPatch` / `normalizeStored`), a tool field, the
-  panel, and the prompt builder that already assembles the dispatch text.
-- Why first: it improves the *quality of every hand-off*, not just one screen. A dispatch
-  that arrives as "step 2 of 5" is worth more than one that arrives as a paragraph.
+What is left of the original idea: making a step addressable on its own (a tool that ticks step 3
+without resending the array) — not worth a tenth tool today.
 
 ### 2. Session read-back — makes hand-off stop being fire-and-forget
 

package/lib/client.js

@@ -50,7 +50,7 @@ window.__ModuleLoader__.load({
      * different mechanisms (restart vs. hot reload), so "which one am I looking
      * at" needs an answer that the bundle itself carries.
      */
-    const UI_REV = 'ui46'
+    const UI_REV = 'ui48'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -288,10 +288,24 @@ window.__ModuleLoader__.load({
       'meta.session.noDirHint': '这个会话没有工作目录，agent 在里面做不了事；用「派发：开新会话」重派一次',
       'meta.dispatchFailed': '上次派发失败',
       'detail.description': '描述',
+      'meta.steps': '步骤 {done}/{total}',
+      'detail.steps': '步骤',
+      'steps.none': '还没有步骤。',
+      'field.steps': '第一步…（一行一步）',
+      'field.stepsHint': '一行一步；派发时会作为编号计划交给 Agent。',
+      'step.done': '标记这一步完成',
+      'step.undo': '取消这一步的完成标记',
       'detail.noDescription': '没有描述。',
       'detail.links': '相关文档与地址',
       'detail.completion': '完成记录',
       'detail.notes': '进展记录',
+      'detail.readback': '会话回读',
+      'detail.evidence': '原话',
+      'readback.none': '这条还没有交给过会话。',
+      'readback.alive': '会话在跑',
+      'readback.dormant': '会话已休眠',
+      'readback.silent': '这个会话还没说过话。',
+      'readback.open': '打开会话',
       'note.placeholder': '记一条进展：做到哪了、卡在哪、需要谁做什么',
       'note.add': '记录进展',
       'note.by.agent': 'Agent',
@@ -561,6 +575,13 @@ window.__ModuleLoader__.load({
       'meta.session.noDirHint': 'This conversation has no working directory, so an agent cannot do anything in it; hand it off again with a new conversation.',
       'meta.dispatchFailed': 'last hand-off failed',
       'detail.description': 'Description',
+      'meta.steps': 'steps {done}/{total}',
+      'detail.steps': 'Steps',
+      'steps.none': 'No steps yet.',
+      'field.steps': 'First step… (one per line)',
+      'field.stepsHint': 'One per line; they ship to the agent as a numbered plan.',
+      'step.done': 'Mark this step done',
+      'step.undo': 'Clear this step',
       'detail.noDescription': 'No description.',
       'detail.links': 'Documents and links',
       'detail.noLinks': 'No attachments. Attach an absolute document path, or a URL.',
@@ -585,6 +606,13 @@ window.__ModuleLoader__.load({
       'group.conversation': 'Conversation',
       'detail.completion': 'Completion',
       'detail.notes': 'Progress notes',
+      'detail.readback': 'Session read-back',
+      'detail.evidence': 'In the author’s words',
+      'readback.none': 'This has never been handed to a conversation.',
+      'readback.alive': 'Conversation is running',
+      'readback.dormant': 'Conversation is dormant',
+      'readback.silent': 'This conversation has not said anything yet.',
+      'readback.open': 'Open conversation',
       'note.placeholder': 'Add a note: where this stands, what is blocking it, who needs to act',
       'note.add': 'Add note',
       'note.by.agent': 'Agent',
@@ -1281,6 +1309,24 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
 .gt-links { display: flex; flex-direction: column; gap: 4px; margin: 0; padding: 0; list-style: none; }
 .gt-link { display: flex; gap: 8px; align-items: center; padding: 4px 0; min-width: 0; }
 .gt-link-main { display: flex; align-items: center; gap: 6px; min-width: 0; flex: 1; }
+.gt-evidence { margin: 0; padding: 2px 0 2px 10px; border-left: 2px solid var(--dsw-alias-border-l2);
+  color: var(--dsw-alias-label-secondary); font-size: 13px; line-height: 20px;
+  white-space: pre-wrap; word-break: break-word; }
+.gt-readback { display: flex; flex-direction: column; gap: 6px; align-items: flex-start; }
+.gt-readback-meta { font-size: 12px; line-height: 18px; color: var(--dsw-alias-label-secondary); }
+.gt-readback-text { font-size: 13px; line-height: 20px; color: var(--dsw-alias-label-primary);
+  display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden;
+  word-break: break-word; }
+.gt-textarea-steps { min-height: 76px; }
+.gt-steps { display: flex; flex-direction: column; gap: 2px; margin: 0; padding: 0; list-style: none; }
+.gt-step { display: flex; align-items: flex-start; gap: 8px; padding: 3px 0; }
+.gt-step-check { flex: 0 0 auto; width: 18px; height: 18px; margin-top: 2px; padding: 0; cursor: pointer;
+  border-radius: 5px; border: 1.4px solid var(--dsw-alias-border-l2); background: transparent;
+  color: transparent; display: inline-flex; align-items: center; justify-content: center; }
+.gt-step[data-done="1"] .gt-step-check { border-color: var(--dsw-alias-state-success-primary);
+  background: var(--dsw-alias-state-success-primary); color: var(--dsw-alias-bg-base); }
+.gt-step-text { font-size: 13px; line-height: 20px; word-break: break-word; }
+.gt-step[data-done="1"] .gt-step-text { color: var(--dsw-alias-label-secondary); text-decoration: line-through; }
 .gt-note-item { display: flex; flex-direction: column; gap: 4px; padding: 8px 0; }
 .gt-note-item + .gt-note-item { border-top: 1px solid var(--dsw-alias-border-l1); }
 .gt-note-meta { display: flex; align-items: center; gap: 6px; font-size: 12px; color: var(--dsw-alias-label-secondary);
@@ -1612,6 +1658,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       // viewport; the click looked like it did nothing. Bring the row into view
       // when it opens, without yanking the page when it closes.
       const rootRef = useRef(null)
+      // What the bound conversation last said. Fetched once per open, because the row is
+      // the only place the question "did it get anywhere" is asked.
+      const [tail, setTail] = useState(null)
       const [linkValue, setLinkValue] = useState('')
       const [linkTitle, setLinkTitle] = useState('')
       const [draft, setDraft] = useState({
@@ -1621,6 +1670,26 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         priority: todo.priority,
       })
 
+      useEffect(() => {
+        if (open !== true || todo.sessionId === '') {
+          setTail(null)
+          return undefined
+        }
+        let alive = true
+        call('session', { query: { id: todo.sessionId } })
+          .then((data) => {
+            // A conversation this process has not seen speak answers null: that is not an
+            // error, it is the normal case for an old hand-off.
+            if (alive) setTail(data?.session ?? null)
+          })
+          .catch(() => {
+            if (alive) setTail(null)
+          })
+        return () => {
+          alive = false
+        }
+      }, [open, todo.sessionId])
+
       // Re-seed the edit draft whenever the record changes underneath us.
       useEffect(() => {
         setDraft({
@@ -1671,6 +1740,12 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         )
       }
       meta.push(h('span', { key: 'added', title: new Date(todo.createdAt).toLocaleString() }, ageText(lang, todo.createdAt, now)))
+      // Progress on the plan, when there is one: the row shows where it stands without
+      // opening the detail.
+      if (Array.isArray(todo.steps) && todo.steps.length > 0) {
+        const done = todo.steps.filter((step) => step.done === true).length
+        meta.push(h('span', { key: 'steps' }, t('meta.steps', { done, total: todo.steps.length })))
+      }
       if (todo.tags.length > 0) {
         const shown = todo.tags.slice(0, 4)
         meta.push(
@@ -2057,6 +2132,37 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               h(
                 'div',
                 { className: 'gt-section' },
+                h('div', { className: 'gt-section-title' }, t('detail.readback')),
+                tail === null
+                  ? h('div', { className: 'gt-muted' }, t('readback.none'))
+                  : h(
+                      'div',
+                      { className: 'gt-readback' },
+                      h('div', { className: 'gt-readback-meta' },
+                        tail.alive === true ? t('readback.alive') : t('readback.dormant'),
+                        tail.tail?.at === undefined ? null : h('span', null, ' · ' + absoluteTime(tail.tail.at)),
+                      ),
+                      tail.tail === null || tail.tail === undefined
+                        ? h('div', { className: 'gt-muted' }, t('readback.silent'))
+                        : h('div', { className: 'gt-readback-text', title: tail.tail.text }, tail.tail.text),
+                      typeof ctx?.uiWorkspace?.openSession === 'function'
+                        ? h(
+                            'button',
+                            {
+                              type: 'button',
+                              className: 'gt-btn gt-btn-quiet',
+                              onClick: () => {
+                                try {
+                                  ctx.uiWorkspace.openSession(todo.sessionId)
+                                } catch {
+                                  /* opening a conversation is a nicety, never a failure */
+                                }
+                              },
+                            },
+                            t('readback.open'),
+                          )
+                        : null,
+                    ),
                 h('div', { className: 'gt-section-title' }, t('detail.notes')),
                 (todo.notes ?? []).length === 0
                   ? h('div', { className: 'gt-muted' }, t('note.none'))
@@ -2105,6 +2211,14 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                   ),
                 ),
               ),
+              todo.evidence === '' || todo.evidence === undefined
+                ? null
+                : h(
+                    'div',
+                    { className: 'gt-section' },
+                    h('div', { className: 'gt-section-title' }, t('detail.evidence')),
+                    h('blockquote', { className: 'gt-evidence' }, todo.evidence),
+                  ),
               todo.completion === null || todo.completion === undefined
                 ? null
                 : h(
@@ -2155,6 +2269,40 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                           ),
                         ),
                   ),
+              h(
+                'div',
+                { className: 'gt-section' },
+                h('div', { className: 'gt-section-title' }, t('detail.steps')),
+                (todo.steps ?? []).length === 0
+                  ? h('div', { className: 'gt-muted' }, t('steps.none'))
+                  : h(
+                      'ul',
+                      { className: 'gt-steps' },
+                      todo.steps.map((step, index) =>
+                        h(
+                          'li',
+                          { key: `${index}:${step.text}`, className: 'gt-step', 'data-done': step.done === true ? '1' : '0' },
+                          h(
+                            'button',
+                            {
+                              type: 'button',
+                              className: 'gt-step-check',
+                              'aria-pressed': step.done === true,
+                              title: step.done === true ? t('step.undo') : t('step.done'),
+                              'aria-label': step.done === true ? t('step.undo') : t('step.done'),
+                              disabled: busy,
+                              onClick: () =>
+                                onAction('steps', todo, {
+                                  steps: todo.steps.map((item, i) => (i === index ? { text: item.text, done: item.done !== true } : { text: item.text, done: item.done === true })),
+                                }),
+                            },
+                            step.done === true ? h(Icon, { name: 'check', size: 11 }) : null,
+                          ),
+                          h('span', { className: 'gt-step-text' }, step.text),
+                        ),
+                      ),
+                    ),
+              ),
               h(
                 'div',
                 { className: 'gt-section' },
@@ -2349,7 +2497,7 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       const [more, setMore] = useState(false)
       const [collapsed, setCollapsed] = useState({})
       const [undo, setUndo] = useState(null)
-      const [draft, setDraft] = useState({ title: '', description: '', links: '', tags: '', priority: 'normal', due: '' })
+      const [draft, setDraft] = useState({ title: '', description: '', links: '', steps: '', tags: '', priority: 'normal', due: '' })
       // Conversations come from the shell's own sessions service, declared in this
       // plugin's `inject` list the way the shipped panels do it
       // (`ui-subagent` / `agent-team`: ["sessions", "uiWorkspace", "slots", "locale"]).
@@ -2750,6 +2898,11 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
           .split(',')
           .map((part) => part.trim())
           .filter((part) => part !== '')
+        // One step per line: the shape a person already writes a plan in.
+        const steps = (draft.steps ?? '')
+          .split('\n')
+          .map((line) => line.trim())
+          .filter((line) => line !== '')
         await run('__new__', () =>
           call('create', {
             method: 'POST',
@@ -2757,13 +2910,14 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               title,
               ...(draft.description.trim() === '' ? {} : { description: draft.description.trim() }),
               ...(links.length === 0 ? {} : { links }),
+              ...(steps.length === 0 ? {} : { steps }),
               ...(tags.length === 0 ? {} : { tags }),
               ...(draft.priority === 'normal' ? {} : { priority: draft.priority }),
               ...(draft.due === '' ? {} : { dueAt: new Date(draft.due).toISOString() }),
             },
           }),
         )
-        setDraft({ title: '', description: '', links: '', tags: '', priority: 'normal', due: '' })
+        setDraft({ title: '', description: '', links: '', steps: '', tags: '', priority: 'normal', due: '' })
         setMore(false)
       }
 
@@ -3197,6 +3351,7 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         if (kind === 'archive') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'archived' } }))
         if (kind === 'unarchive') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'open' } }))
         if (kind === 'save') return run(todo.id, () => call('update', { method: 'POST', body: { id: todo.id, ...payload } }))
+        if (kind === 'steps') return run(todo.id, () => call('update', { method: 'POST', body: { id: todo.id, steps: payload.steps } }))
         if (kind === 'note') return run(todo.id, () => call('note', { method: 'POST', body: { id: todo.id, ...payload } }))
         if (kind === 'link') return run(todo.id, () => call('link', { method: 'POST', body: { id: todo.id, ...payload } }))
         if (kind === 'unlink') return run(todo.id, () => call('link', { method: 'POST', body: { id: todo.id, remove: [payload.index] } }))
@@ -3770,6 +3925,19 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                     }),
                     h('span', { className: 'gt-hint' }, t('field.linksHint')),
                   ),
+                  h(
+                    'div',
+                    { className: 'gt-field' },
+                    h('label', { className: 'gt-field-label', htmlFor: 'gt-new-steps' }, t('detail.steps')),
+                    h('textarea', {
+                      id: 'gt-new-steps',
+                      className: 'gt-textarea gt-textarea-steps',
+                      placeholder: t('field.steps'),
+                      value: draft.steps,
+                      onChange: (event) => setDraft({ ...draft, steps: event.target.value }),
+                    }),
+                    h('span', { className: 'gt-hint' }, t('field.stepsHint')),
+                  ),
                   h(
                     'div',
                     { className: 'gt-field-row' },

package/lib/completion.js

@@ -67,7 +67,7 @@ const VERDICT_TOOLS = Object.freeze([
  * @param {unknown} message
  * @returns {string}
  */
-function messageText(message) {
+export function messageText(message) {
   const content = message?.content
   if (!Array.isArray(content)) return ''
   return content

package/lib/index.js

@@ -23,7 +23,7 @@
 import { readFile, writeFile } from 'node:fs/promises'
 import path from 'node:path'
 
-import { createCompletionWatcher } from './completion.js'
+import { createCompletionWatcher, messageText } from './completion.js'
 import { createDispatcher } from './dispatch.js'
 import { createSettings, explainAutoCollect, idleSessions, retryDelayMs } from './settings.js'
 import { createDiagnostics } from './diagnostics.js'
@@ -36,7 +36,7 @@ import { createStore, resolveStorePath } from './store.js'
 import { createTools } from './tools.js'
 
 /** Must equal `package.json`'s version; `npm run check` enforces that. */
-export const VERSION = '0.7.2'
+export const VERSION = '0.9.0'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'
@@ -74,6 +74,7 @@ const GUIDANCE = [
   '- 用户说「记一下 / 别忘了 / 回头办」。',
   '**不要记**：你这一步就能做完的、本会话内的执行计划、纯闲聊。宁可少记。',
   '记的时候：标题一句话说清要做什么；把相关文档**绝对路径**或网址挂进 `links`（接手时会作为上下文一起交出去）；需要精确时间的写 `dueAt`。',
+  '**大活拆步骤**：一件需要多轮才能做完的事，用 `steps` 记下 3–6 步（`global_todo_add` 的 `steps` 参数）——派发时这些步骤会作为编号计划原样交给接手的 Agent，比一段散文有用得多；做完一步就用 `global_todo_update` 把该步的 `done` 置为 true。',
   '记完用一句话说明记了什么（别复述整条描述）。做完用 `global_todo_done` 留痕，**不要删**。',
   '**一轮收尾时顺手划掉**：如果清单里某条就是你刚做完的事，直接 `global_todo_done` 结束它，别留着占地方（插件也会在你安静下来后自动划掉，但你先划更准）。',
   '做不到 / 卡住了：用 `global_todo_note` 追加一条进展，说明卡在哪、需要用户做什么——**不要**改写待办的 description（那是用户自己的文字）。',
@@ -131,6 +132,21 @@ export function apply(ctx, config) {
   // reached the wrong conversation once already.
   const recentFile = path.join(path.dirname(file), 'recent-session.json')
   const recentSession = { id: '', watching: typeof ctx?.on === 'function', file: recentFile }
+  // What a bound conversation last said, remembered while its events stream by.
+  // Read-back has to be cheap: the panel asks on every opened row, and going to the
+  // session log per row would make opening a todo wait on disk. Bounded, text-only,
+  // never persisted — a stale tail is better than no answer, and it costs no write.
+  const SESSION_TAIL_LIMIT = 200
+  const sessionTails = new Map()
+  const rememberTail = (sessionId, text, at) => {
+    if (sessionId === '' || text === '') return
+    if (sessionTails.size >= SESSION_TAIL_LIMIT && !sessionTails.has(sessionId)) {
+      // Oldest insertion first: a Map keeps insertion order, so one delete is enough.
+      const oldest = sessionTails.keys().next()
+      if (oldest.done !== true) sessionTails.delete(oldest.value)
+    }
+    sessionTails.set(sessionId, { text: text.slice(0, 400), at, length: text.length })
+  }
 
   /** Best-effort: losing this file costs a guess, never a write. */
   const rememberSession = (sessionId) => {
@@ -157,6 +173,11 @@ export function apply(ctx, config) {
         try {
           const session = first?.id !== undefined && first?.header !== undefined ? first : second
           const event = typeof first?.type === 'string' ? first : typeof second?.type === 'string' ? second : undefined
+          // Every assistant message updates the read-back cache; only a person typing
+          // moves the recent-session pointer.
+          if (event !== undefined && event.type === 'assistant/message' && typeof session?.id === 'string') {
+            rememberTail(session.id, messageText(event.data?.message), Date.now())
+          }
           if (event === undefined || event.type !== 'user/message') return
           // `source.kind === 'user'` means a person typed it: model turns, tool
           // results and plugin injections all carry a different kind.
@@ -519,6 +540,7 @@ export function apply(ctx, config) {
         tools: toolState,
         completion: watcherState,
         target: recentSession,
+        sessionTail: (sessionId) => sessionTails.get(sessionId) ?? null,
         settings,
         autoCollect: autoCollectState,
         reminders: reminderState,

package/lib/model.js

@@ -52,6 +52,13 @@ export const LIMITS = Object.freeze({
   activity: 50,
   note: 2000,
   notes: 50,
+  // A todo is a unit of work, not a project plan: a list longer than this is a sign the
+  // item should be split, and a cap keeps the dispatch prompt from becoming a document.
+  steps: 20,
+  step: 200,
+  // The sentence the item came from. A captured todo without its source reads as an
+  // opinion later; with it, the person can check whether it was heard correctly.
+  evidence: 300,
 })
 
 /**
@@ -201,6 +208,11 @@ export function createTodo(input, options = {}) {
     dueAt: normalizeDue(raw.dueAt ?? raw.due),
     tags: normalizeTags(raw.tags),
     links,
+    // An optional plan inside the todo: the steps a person or an agent broke it into.
+    // Shipped to the agent as a numbered list, so hand-off stops being one paragraph.
+    steps: normalizeSteps(raw.steps),
+    // Where it came from, in the author's own words: empty means "typed here".
+    evidence: normalizeText(raw.evidence, '原话', LIMITS.evidence, 'invalid-evidence'),
     createdAt: now,
     updatedAt: now,
     createdBy: by,
@@ -305,6 +317,14 @@ export function normalizeStored(raw, options = {}) {
       }
     })(),
     links,
+    evidence: typeof raw.evidence === 'string' ? raw.evidence.slice(0, LIMITS.evidence) : '',
+    steps: (() => {
+      try {
+        return normalizeSteps(raw.steps)
+      } catch {
+        return []
+      }
+    })(),
     createdAt,
     updatedAt: Number.isFinite(raw.updatedAt) ? Number(raw.updatedAt) : createdAt,
     createdBy: normalizeActor(raw.createdBy),
@@ -563,11 +583,30 @@ export function applyPatch(todo, patch, options = {}) {
       changed.push('tags')
     }
   }
+  if (patch.evidence !== undefined) {
+    const evidence = normalizeText(patch.evidence, '原话', LIMITS.evidence, 'invalid-evidence')
+    if (evidence !== todo.evidence) {
+      todo.evidence = evidence
+      changed.push('evidence')
+    }
+  }
+  if (patch.steps !== undefined) {
+    const steps = normalizeSteps(patch.steps)
+    const same =
+      steps.length === todo.steps.length && steps.every((step, index) => step.text === todo.steps[index].text && step.done === todo.steps[index].done)
+    if (!same) {
+      todo.steps = steps
+      changed.push('steps')
+    }
+  }
   if (patch.status !== undefined) {
     const status = normalizeEnum(patch.status, STATUSES, 'invalid-status', '状态', todo.status)
     if (status !== todo.status) {
       todo.status = status
       todo.doneAt = status === 'done' ? now : null
+      // Reaching done through a patch carries the same review rule as the dedicated
+      // status path: an agent's "done" is a claim, a person's is a decision.
+      todo.review = status === 'done' && by === 'agent' ? { pending: true, at: now, by } : null
       changed.push('status')
     }
   }
@@ -626,6 +665,40 @@ export function setStatus(todo, status, options = {}) {
   return true
 }
 
+/**
+ * An optional plan inside a todo.
+ *
+ * A step is text plus a tick, and the order is the plan. Strings are accepted for the
+ * common case (create, or an agent rewriting the plan) so a caller never has to spell out
+ * `{ done: false }` for every line.
+ *
+ * @param {unknown} value
+ * @returns {Array<{ text: string, done: boolean }>}
+ */
+export function normalizeSteps(value) {
+  if (value === null || value === undefined) return []
+  if (!Array.isArray(value)) throw new TodoError('invalid-steps', '步骤必须是数组')
+  if (value.length > LIMITS.steps) {
+    throw new TodoError('invalid-steps', `步骤最多 ${LIMITS.steps} 条，收到 ${value.length} 条`)
+  }
+  const out = []
+  for (const item of value) {
+    if (typeof item === 'string') {
+      const text = item.trim().slice(0, LIMITS.step)
+      // A blank line in a textarea is a typo, not a step.
+      if (text !== '') out.push({ text, done: false })
+      continue
+    }
+    if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+      throw new TodoError('invalid-steps', '步骤必须是字符串或 { text, done }')
+    }
+    const text = typeof item.text === 'string' ? item.text.trim().slice(0, LIMITS.step) : ''
+    if (text === '') continue
+    out.push({ text, done: item.done === true })
+  }
+  return out
+}
+
 /**
  * @param {object} todo
  * @param {unknown} link

package/lib/routes.js

@@ -334,6 +334,28 @@ export function createRoutes(deps) {
       return { todo: service.annotateLinks(await service.get(id)) }
     }),
 
+    /**
+     * What a bound conversation last said, plus whether it is still around.
+     *
+     * Deliberately a separate route: the list is polled and a hand-off's tail is not,
+     * so folding this into /list would read every session on every poll. A missing
+     * tail is the normal answer for a conversation this process has not seen speak.
+     */
+    exact('GET', `${ROUTE_BASE}/session`, async (request) => {
+      const id = params(request).get('id') ?? ''
+      if (id === '') return { session: null }
+      const tailOf = typeof deps.sessionTail === 'function' ? deps.sessionTail : () => null
+      let alive = false
+      let dir = ''
+      try {
+        alive = dispatcher?.sessionAlive?.(id) === true
+        dir = dispatcher?.sessionDir?.(id) ?? ''
+      } catch {
+        /* a missing dispatcher is not an error here */
+      }
+      return { session: { id, alive, dir, tail: tailOf(id) } }
+    }),
+
     /**
      * The whole list as JSON.
      *

package/lib/service.js

@@ -555,6 +555,15 @@ export function createService(options) {
     if (todo.description !== '') {
       lines.push('', '描述：', todo.description)
     }
+    // The plan, if there is one: a numbered list is what makes a hand-off concrete, and
+    // the ticks say which parts are already behind us.
+    const steps = Array.isArray(todo.steps) ? todo.steps : []
+    if (steps.length > 0) {
+      lines.push('', `步骤（共 ${steps.length} 步）：`)
+      steps.forEach((step, index) => {
+        lines.push(`${index + 1}. ${step.done === true ? '[已完成] ' : ''}${step.text}`)
+      })
+    }
     if (todo.links.length > 0) {
       lines.push('', '相关文档与地址：')
       for (const link of todo.links) {
@@ -596,6 +605,9 @@ export function createService(options) {
       '该记的：等对方回复、待确认的决定、答应别人的事、还没收尾且需要另开一个会话继续的一步。',
       '每条必要时补描述、挂上相关文档**绝对路径**或网址，并标级别（P0 紧急 / P1 高 / P2 常规 / P3 低）。',
       '',
+      '**带上原话**（重要）：每条用 `evidence` 逐字引用用户说的那一句（最多 200 字，不要改写、不要总结）。',
+      '以后看到这条待办的人，要能一眼核对「有没有听错」；没有原话的抓取，只是一条无从核对的转述。',
+      '',
       '记完用**一句话**汇总（例如「记了 2 条：X 与 Y」），不要逐条复述。',
     ].join('\n')
   }

package/lib/tools.js

@@ -20,6 +20,34 @@ import { LIMITS, PRIORITIES, PRIORITY_LABELS, STATUSES } from './model.js'
 
 const text = (value) => [{ type: 'text', text: value }]
 
+const STEPS_INPUT = {
+  type: 'array',
+  description:
+    '要做成的几步（可选，最多 ' + LIMITS.steps + ' 条）。每步一句话；已完成的写 { text, done: true }。'
+    + '派发时会把它们作为编号计划交给 Agent。',
+  items: {
+    oneOf: [
+      { type: 'string' },
+      {
+        type: 'object',
+        properties: { text: { type: 'string' }, done: { type: 'boolean' } },
+        required: ['text'],
+        additionalProperties: false,
+      },
+    ],
+  },
+}
+
+const STEPS_SHAPE = {
+  type: 'array',
+  items: {
+    type: 'object',
+    properties: { text: { type: 'string' }, done: { type: 'boolean' } },
+    required: ['text'],
+    additionalProperties: false,
+  },
+}
+
 const LINKS_INPUT = {
   type: 'array',
   description:
@@ -42,9 +70,17 @@ const LINKS_INPUT = {
 }
 
 /** One todo's worth of input, shared by `add` and `capture`. */
+const EVIDENCE_INPUT = {
+  type: 'string',
+  description:
+    `原话（可选，最多 ${LIMITS.evidence} 字）：用户说的那**一句**，逐字引用，用来让人核对有没有听错。`
+    + '抓取时几乎总该带；自己顺手记一条时可以不写。',
+}
+
 const ITEM_PROPERTIES = {
   title: { type: 'string', description: `一句话说清要做什么（最多 ${LIMITS.title} 字）` },
   description: { type: 'string', description: '补充说明、验收标准、已知的坑' },
+  evidence: EVIDENCE_INPUT,
   links: LINKS_INPUT,
   tags: { type: 'array', items: { type: 'string' }, description: `标签，最多 ${LIMITS.tags} 个` },
   priority: { type: 'string', enum: [...PRIORITIES], description: 'P0 紧急 / P1 高 / P2 常规（缺省）/ P3 低' },
@@ -92,6 +128,8 @@ const TODO_SHAPE = {  type: 'object',
     priority: { type: 'string', enum: [...PRIORITIES] },
     dueAt: { oneOf: [{ type: 'string' }, { type: 'null' }] },
     tags: { type: 'array', items: { type: 'string' } },
+    evidence: { type: 'string', description: '原话（空串表示是自己记的，不是抓的）' },
+    steps: STEPS_SHAPE,
     links: {
       type: 'array',
       items: {
@@ -152,6 +190,8 @@ export function presentTodo(todo, now = Date.now()) {
     priority: todo.priority,
     dueAt: todo.dueAt,
     tags: [...todo.tags],
+    evidence: todo.evidence ?? '',
+    steps: (todo.steps ?? []).map((step) => ({ text: step.text, done: step.done === true })),
     links: todo.links.map((link) => ({ ...link })),
     createdAt: todo.createdAt,
     createdAtIso: new Date(todo.createdAt).toISOString(),
@@ -301,6 +341,8 @@ export function createTools(service, options = {}) {
           title: { type: 'string', description: `一句话说清要做什么（最多 ${LIMITS.title} 字）` },
           description: { type: 'string', description: '补充说明、验收标准、已知的坑' },
           links: LINKS_INPUT,
+          steps: STEPS_INPUT,
+          evidence: EVIDENCE_INPUT,
           tags: { type: 'array', items: { type: 'string' }, description: `标签，最多 ${LIMITS.tags} 个` },
           priority: { type: 'string', enum: [...PRIORITIES], description: 'P0 紧急 / P1 高 / P2 常规（缺省）/ P3 低' },
           dueAt: { type: 'string', description: 'ISO-8601 截止时间，例如 2026-10-20T10:00 或 2026-10-20' },
@@ -528,7 +570,7 @@ export function createTools(service, options = {}) {
     {
       name: 'global_todo_update',
       description:
-        '改一条全局待办。只传要改的字段；`dueAt: ""` 清空截止时间，`tags: []` 清空标签，`links` 是整体替换（要单独加附件请用 global_todo_link），`status` 可以设为 archived（归档，不删除）。',
+        '改一条全局待办。只传要改的字段；`dueAt: ""` 清空截止时间，`tags: []` 清空标签，`links` / `steps` 是整体替换（要单独加附件请用 global_todo_link），`status` 可以设为 archived（归档，不删除）。',
       parameters: {
         type: 'object',
         properties: {
@@ -542,6 +584,8 @@ export function createTools(service, options = {}) {
           dueAt: { oneOf: [{ type: 'string' }, { type: 'null' }], description: '空串或 null 表示清空' },
           tags: { type: 'array', items: { type: 'string' } },
           links: LINKS_INPUT,
+          steps: STEPS_INPUT,
+          evidence: EVIDENCE_INPUT,
         },
         required: ['id'],
         additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "icon": "./docs/icon.svg",
   "description": "Global, cross-session todos for DeepSeek Harness: one list owned by the human and the agent together, with creation time, attached documents and links, and one-click hand-off to an agent session. 全局待办：跨会话一份清单，记录加入时间，可挂文档与地址，可一键交给 Agent 继续干。",
   "type": "module",
@@ -58,6 +58,7 @@
     "verify": "npm run check && npm run check:render && npm test",
     "preview": "node tools/preview.mjs",
     "screenshots": "npm run preview && node tools/screenshot.mjs",
+    "tour": "node tools/tour.mjs",
     "prepack": "npm run verify",
     "check:render": "node tools/preview.mjs --check",
     "check:live": "node tools/live-check.mjs",