dsh-global-todo 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [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.

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)
 
 ---
 

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)
 
 ---
 

package/docs/DESIGN.md

@@ -57,6 +57,37 @@ $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

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 = 'ui47'
+    const UI_REV = 'ui48'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -299,6 +299,13 @@ window.__ModuleLoader__.load({
       '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',
@@ -599,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',
@@ -1295,6 +1309,14 @@ 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; }
@@ -1636,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({
@@ -1645,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({
@@ -2087,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'))
@@ -2135,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(

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.8.0'
+export const VERSION = '0.9.0'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'
@@ -132,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) => {
@@ -158,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.
@@ -520,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

@@ -56,6 +56,9 @@ export const LIMITS = Object.freeze({
   // 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,
 })
 
 /**
@@ -208,6 +211,8 @@ export function createTodo(input, options = {}) {
     // 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,
@@ -312,6 +317,7 @@ export function normalizeStored(raw, options = {}) {
       }
     })(),
     links,
+    evidence: typeof raw.evidence === 'string' ? raw.evidence.slice(0, LIMITS.evidence) : '',
     steps: (() => {
       try {
         return normalizeSteps(raw.steps)
@@ -577,6 +583,13 @@ 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 =

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

@@ -605,6 +605,9 @@ export function createService(options) {
       '该记的：等对方回复、待确认的决定、答应别人的事、还没收尾且需要另开一个会话继续的一步。',
       '每条必要时补描述、挂上相关文档**绝对路径**或网址，并标级别（P0 紧急 / P1 高 / P2 常规 / P3 低）。',
       '',
+      '**带上原话**（重要）：每条用 `evidence` 逐字引用用户说的那一句（最多 200 字，不要改写、不要总结）。',
+      '以后看到这条待办的人，要能一眼核对「有没有听错」；没有原话的抓取，只是一条无从核对的转述。',
+      '',
       '记完用**一句话**汇总（例如「记了 2 条：X 与 Y」），不要逐条复述。',
     ].join('\n')
   }

package/lib/tools.js

@@ -70,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 低' },
@@ -120,6 +128,7 @@ 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',
@@ -181,6 +190,7 @@ 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,
@@ -332,6 +342,7 @@ export function createTools(service, options = {}) {
           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' },
@@ -574,6 +585,7 @@ export function createTools(service, options = {}) {
           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.8.0",
+  "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",