dsh-global-todo 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [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.
+
+- **`.gt-inner` needed `min-height: 0`.** A flex item defaults to `min-height: auto`, so the
+  column refused to shrink below its content: with a long list it grew to 2236px inside a 680px
+  slot, `.gt-groups` never got a scroll range, and the host's own overflow clipped everything
+  below the fold — measured `scrollTop 0 → 0` after a wheel, i.e. nothing moved.
+- **`.gt-root` now clips its own overflow**, so the header and toolbar stay put and the list is the
+  only scroll area (measured after the fix: `.gt-groups` 480px viewport over a 2036px list, wheel
+  moves 0 → 800).
+- **`check:render` asserts the contract**: panel clips, column may shrink, list scrolls. This class
+  of bug is invisible to the server-rendered preview screenshot, which is why it shipped.
+
 ## [0.9.0] — 2026-10-20
 
 Competitive ground: the hand-off now has a return path, capture carries its source, and the

package/README.md

@@ -269,7 +269,7 @@ 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/capture` | `{ sessionId? }` — ask the current conversation to collect its follow-ups |
@@ -282,6 +282,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 |

package/README.zh.md

@@ -161,7 +161,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 +175,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 原样报回，不擅自送到别处 |

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

package/docs/ROADMAP.md

@@ -174,25 +174,22 @@ assistant message plus a link to open it.
 - Why second: the panel currently cannot answer "did the thing I handed over get anywhere",
   which is the question people actually ask.
 
-### 3. Markdown / TaskPaper import and export
+### 3. ~~Markdown import and export~~ — landed in 0.10.0
 
-JSON round-trips byte for byte; the text formats are what let the list live in a repo and
-diff.
+`GET /export?format=md` writes a task list with indented metadata; `POST /import` with
+`{ markdown }` reads it back through `create` (new items, never an overwrite — Markdown has no
+ids, so a shared id must not be able to replace a record). Parser is tolerant: a bad date is
+dropped, unknown lines ignored, an empty task line is not a todo. Tests: `test/markdown.test.mjs`.
 
-- Today: only `GET /export` / `POST /import` over JSON.
-- Effort: medium — a serializer plus a tolerant parser, both with round-trip tests.
-- Why third: cheap portability, and it is the only way to compare this list with another
-  tool's.
+TaskPaper is still not implemented, and deliberately: the Markdown shape covers "diff it in a
+repo", and a second text format is a second parser to keep honest.
 
-### 4. The weekly agent report
+### 4. ~~The weekly agent report~~ — landed in 0.10.0
 
-Per-todo completion records already carry a summary and the changed files. A cross-todo
-view — "what did the sessions finish this week, and what did they touch" — turns that into
-something reviewable.
-
-- Today: the data exists (`completion.artifacts`), the aggregate does not.
-- Effort: small-medium; the honest version is a date-bounded list filtered on
-  `completion.by === 'agent'`, with `review` state beside each row.
+`GET /report?days=7` aggregates completion records into finished items (newest first), the number
+of conversations involved, files touched with counts, and how many wait for review — derived every
+time, never stored. The panel shows it from `⋯ → 本周报告`. Tests:
+`test/markdown.test.mjs` (pure aggregation) and `test/routes.test.mjs`.
 
 ### 5. Image attachments
 

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 = 'ui48'
+    const UI_REV = 'ui50'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -301,6 +301,17 @@ window.__ModuleLoader__.load({
       'detail.notes': '进展记录',
       'detail.readback': '会话回读',
       'detail.evidence': '原话',
+      'action.exportMd': '导出 Markdown',
+      'import.markdownAdded': '已从 Markdown 新增 {n} 条',
+      'report.title': '本周报告',
+      'report.empty': '这一段时间没有 Agent 完成的记录。',
+      'report.finished': '完成 {n} 条',
+      'report.sessions': '涉及 {n} 个会话',
+      'report.created': '新增 {n} 条',
+      'report.pending': '{n} 条待确认',
+      'report.files': '触及的文件',
+      'report.byAgent': 'Agent',
+      'report.byHuman': '人',
       'readback.none': '这条还没有交给过会话。',
       'readback.alive': '会话在跑',
       'readback.dormant': '会话已休眠',
@@ -608,6 +619,17 @@ window.__ModuleLoader__.load({
       'detail.notes': 'Progress notes',
       'detail.readback': 'Session read-back',
       'detail.evidence': 'In the author’s words',
+      'action.exportMd': 'Export Markdown',
+      'import.markdownAdded': 'Added {n} from Markdown',
+      'report.title': 'This week',
+      'report.empty': 'No agent completions in this window.',
+      'report.finished': '{n} finished',
+      'report.sessions': '{n} conversations',
+      'report.created': '{n} added',
+      'report.pending': '{n} awaiting review',
+      'report.files': 'Files touched',
+      'report.byAgent': 'Agent',
+      'report.byHuman': 'Person',
       'readback.none': 'This has never been handed to a conversation.',
       'readback.alive': 'Conversation is running',
       'readback.dormant': 'Conversation is dormant',
@@ -972,6 +994,16 @@ window.__ModuleLoader__.load({
       }
       if (props.name === 'clock') return h('svg', common, h('circle', { cx: 8, cy: 8, r: 5.6 }), h('path', { d: 'M8 4.8V8l2.2 1.4' }))
       if (props.name === 'close') return h('svg', common, h('path', { d: 'M4.2 4.2l7.6 7.6M11.8 4.2l-7.6 7.6' }))
+      if (props.name === 'chart') {
+        return h(
+          'svg',
+          common,
+          h('path', { d: 'M3 13.2h10' }),
+          h('rect', { x: 3.4, y: 8.2, width: 2.4, height: 4.2, rx: 0.6 }),
+          h('rect', { x: 6.8, y: 5, width: 2.4, height: 7.4, rx: 0.6 }),
+          h('rect', { x: 10.2, y: 2.8, width: 2.4, height: 9.6, rx: 0.6 }),
+        )
+      }
       if (props.name === 'gear') {
         return h(
           'svg',
@@ -999,8 +1031,14 @@ window.__ModuleLoader__.load({
 
     const CSS = `
 .gt-root { position: relative; display: flex; flex-direction: column; height: 100%; min-height: 0; min-width: 0;
+  /* The panel clips; the list inside it scrolls. Without this the column grew past the
+     slot and the host's own overflow hid the rest of the list — the "cannot scroll" bug. */
+  overflow: hidden;
   color: var(--dsw-alias-label-primary); font-size: 13px; line-height: 1.5; }
 .gt-inner { display: flex; flex-direction: column; gap: 14px; width: 100%; max-width: 1040px; min-width: 0;
+  /* min-height is the load-bearing line: a flex item defaults to min-height:auto, so the
+     column refused to shrink below its content and .gt-groups never got a scroll range. */
+  min-height: 0;
   box-sizing: border-box; margin: 0 auto; padding: 20px 24px 32px; flex: 1; }
 .gt-head { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; }
 .gt-head-actions { display: flex; align-items: center; gap: 6px; margin-left: auto; flex: 0 0 auto; }
@@ -1221,6 +1259,18 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
 .gt-settings-foot { display: flex; flex: 0 0 auto; justify-content: flex-end; gap: 8px;
   padding: 12px 16px; border-top: 1px solid var(--dsw-alias-border-l1); }
 .gt-keys { width: 320px; }
+.gt-report { width: 420px; }
+.gt-report-body { display: flex; flex-direction: column; gap: 12px; }
+.gt-report-summary { display: flex; flex-wrap: wrap; gap: 6px 12px; font-size: 13px; color: var(--dsw-alias-label-primary); }
+.gt-report-warn { color: var(--dsw-alias-state-warn-primary); }
+.gt-report-list { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 8px; }
+.gt-report-item { display: flex; flex-direction: column; gap: 2px; padding: 8px 0; border-top: 1px solid var(--dsw-alias-border-l1); }
+.gt-report-title { font-size: 13px; line-height: 20px; font-weight: 600; }
+.gt-report-meta { font-size: 12px; line-height: 18px; color: var(--dsw-alias-label-secondary); }
+.gt-report-summary-text { font-size: 12px; line-height: 18px; color: var(--dsw-alias-label-secondary);
+  display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden; }
+.gt-report-files { display: flex; flex-direction: column; gap: 6px; }
+.gt-report-file { display: flex; align-items: baseline; justify-content: space-between; gap: 8px; }
 .gt-key-row { display: flex; align-items: center; gap: 10px; }
 .gt-key-row .gt-kbd { min-width: 44px; text-align: center; }
 .gt-group-select { display: none; min-height: 28px; max-width: 150px; padding: 0 8px; font: inherit;
@@ -2466,6 +2516,25 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
       // reach without curl.
       const [settingsOpen, setSettingsOpen] = useState(initialSettingsOpen)
       const [keysOpen, setKeysOpen] = useState(false)
+      const [reportOpen, setReportOpen] = useState(false)
+      const [report, setReport] = useState(null)
+
+      // The week's evidence, fetched when the card opens: it is an aggregate over every
+      // record, so it must not be derived from the page the panel happens to be showing.
+      useEffect(() => {
+        if (!reportOpen) return undefined
+        let alive = true
+        call('report', { query: { days: 7 } })
+          .then((data) => {
+            if (alive) setReport(data?.report ?? null)
+          })
+          .catch(() => {
+            if (alive) setReport(null)
+          })
+        return () => {
+          alive = false
+        }
+      }, [reportOpen])
       const [settingsBox, setSettingsBox] = useState(null)
       // The detail card's breakpoint follows the panel's own width, not the viewport: the
       // slot is ~265px narrower than the window, so a viewport query opens the two-column
@@ -2830,6 +2899,10 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
             (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable === true)
           if (event.key === 'Escape') {
             if (typing && typeof target.blur === 'function') target.blur()
+            if (reportOpen) {
+              setReportOpen(false)
+              return
+            }
             if (keysOpen) {
               setKeysOpen(false)
               return
@@ -2856,7 +2929,7 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         }
         document.addEventListener('keydown', onKey)
         return () => document.removeEventListener('keydown', onKey)
-      }, [settingsOpen, keysOpen, adding])
+      }, [settingsOpen, keysOpen, reportOpen, adding])
 
       // The settings card floats over the list, so a click anywhere else dismisses it
       // the way every other popover on the web does.
@@ -3191,6 +3264,26 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
        * unchanged, and the panel's copy carries runtime annotations (a live session's
        * directory, a dead attachment flag) that do not belong in a file.
        */
+      /** Same list, in the format a repository can diff. */
+      const exportMarkdown = async () => {
+        try {
+          const data = await call('export', { query: { format: 'md' } })
+          const text = typeof data?.markdown === 'string' ? data.markdown : ''
+          const url = window.URL.createObjectURL(new window.Blob([text], { type: 'text/markdown' }))
+          const link = document.createElement('a')
+          link.href = url
+          link.download = 'global-todo-' + new Date().toISOString().slice(0, 10) + '.md'
+          link.click()
+          window.URL.revokeObjectURL(url)
+          setError(null)
+          setNotice({ text: t('notice.exported', { n: data?.count ?? 0 }), sessionId: '' })
+          setTimeout(() => setNotice(null), 6000)
+        } catch (failure) {
+          reportFailure('export-markdown', { message: failure?.message })
+          setError(failure)
+        }
+      }
+
       const exportJson = async () => {
         try {
           const data = await call('export')
@@ -3223,9 +3316,20 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         const file = input?.files?.[0]
         if (file === undefined) return
         try {
+          const text = await file.text()
+          // A .md file (or anything that is not JSON) is read as a task list: those items
+          // are new by definition and go through create, not through the document restore.
+          if (/\.md$/i.test(file.name ?? '') || text.trimStart().startsWith('#')) {
+            const preview = await call('import', { method: 'POST', body: { markdown: text, dryRun: true } })
+            setError(null)
+            setNotice({ text: t('import.markdownAdded', { n: preview?.imported ?? 0 }), sessionId: '' })
+            setTimeout(() => setNotice(null), 6000)
+            void reload()
+            return
+          }
           let parsed
           try {
-            parsed = JSON.parse(await file.text())
+            parsed = JSON.parse(text)
           } catch {
             throw new Error(t('import.badJson'))
           }
@@ -3631,7 +3735,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               label: t('action.overflow'),
               items: [
                 { key: 'refresh', label: t('action.refresh'), icon: 'refresh', onSelect: () => void reload() },
+                { key: 'report', label: t('report.title'), icon: 'chart', onSelect: () => setReportOpen(true) },
                 { key: 'export', label: t('action.export'), icon: 'doc', onSelect: () => void exportJson() },
+                { key: 'exportMd', label: t('action.exportMd'), icon: 'doc', onSelect: () => void exportMarkdown() },
                 { key: 'import', label: t('action.import'), icon: 'plus', onSelect: () => importRef.current?.click?.() },
                 { key: 'settings', label: t('settings.title'), icon: 'gear', onSelect: () => openSettings() },
                 { key: 'keys', label: t('action.keys'), icon: 'kebab', onSelect: () => setKeysOpen(true) },
@@ -3851,6 +3957,83 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
               )
             : null,
 
+          reportOpen
+            ? h(
+                'div',
+                { className: 'gt-settings gt-report', role: 'dialog', 'aria-label': t('report.title') },
+                h(
+                  'div',
+                  { className: 'gt-settings-head' },
+                  h('span', { className: 'gt-settings-title' }, t('report.title')),
+                  h(
+                    'button',
+                    { type: 'button', className: 'gt-iconbtn', title: t('action.hide'), 'aria-label': t('action.hide'), onClick: () => setReportOpen(false) },
+                    h(Icon, { name: 'close', size: 13 }),
+                  ),
+                ),
+                h(
+                  'div',
+                  { className: 'gt-settings-body' },
+                  report === null
+                    ? h('div', { className: 'gt-muted' }, t('loading'))
+                    : h(
+                        'div',
+                        { className: 'gt-report-body' },
+                        h(
+                          'div',
+                          { className: 'gt-report-summary' },
+                          h('span', null, t('report.finished', { n: report.finished.length })),
+                          h('span', null, t('report.sessions', { n: report.sessions })),
+                          h('span', null, t('report.created', { n: report.created })),
+                          report.pendingReview > 0 ? h('span', { className: 'gt-report-warn' }, t('report.pending', { n: report.pendingReview })) : null,
+                        ),
+                        report.finished.length === 0
+                          ? h('div', { className: 'gt-muted' }, t('report.empty'))
+                          : h(
+                              'ul',
+                              { className: 'gt-report-list' },
+                              report.finished.map((item) =>
+                                h(
+                                  'li',
+                                  { key: item.id, className: 'gt-report-item' },
+                                  h(
+                                    'div',
+                                    { className: 'gt-report-title' },
+                                    item.seq > 0 ? h('span', { className: 'gt-seq' }, '#' + item.seq + ' ') : null,
+                                    item.title,
+                                  ),
+                                  h(
+                                    'div',
+                                    { className: 'gt-report-meta' },
+                                    item.by === 'agent' ? t('report.byAgent') : t('report.byHuman'),
+                                    ' · ',
+                                    absoluteTime(item.at),
+                                    item.artifactCount > 0 ? ' · ' + item.artifactCount + ' 个产出' : '',
+                                  ),
+                                  item.summary === '' ? null : h('div', { className: 'gt-report-summary-text' }, item.summary),
+                                ),
+                              ),
+                            ),
+                        report.files.length === 0
+                          ? null
+                          : h(
+                              'div',
+                              { className: 'gt-report-files' },
+                              h('div', { className: 'gt-settings-group-title' }, t('report.files')),
+                              ...report.files.map((file) =>
+                                h(
+                                  'div',
+                                  { key: file.path, className: 'gt-report-file', title: file.titles.join(' / ') },
+                                  h('span', { className: 'gt-mono' }, file.path),
+                                  h('span', { className: 'gt-hint' }, '×' + file.count),
+                                ),
+                              ),
+                            ),
+                      ),
+                ),
+              )
+            : null,
+
           error !== null
             ? h(
                 'div',

package/lib/index.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.9.0'
+export const VERSION = '0.10.0'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'

package/lib/markdown.js

@@ -0,0 +1,135 @@
+/**
+ * Markdown, both ways.
+ *
+ * The JSON export is the round-trip format; this one is for humans and for repositories:
+ * it diffs line by line, it renders on GitHub, and it survives being edited by hand.
+ *
+ * The shape is deliberately plain — a task list with indented metadata — so that reading
+ * it needs no documentation and writing it needs no schema:
+ *
+ *   - [ ] 标题
+ *         优先级: 高 · 截止: 2026-10-21T18:00 · 标签: 发布, 文档
+ *         描述: 第一行
+ *         - [x] 一步
+ *
+ * Import is tolerant: unknown lines are ignored, a bad date is dropped instead of failing
+ * the whole file, and anything that is not a task line simply does not become a todo.
+ */
+
+const PRIORITY_LABELS = { urgent: '紧急', high: '高', normal: '常规', low: '低' }
+const PRIORITY_BY_LABEL = new Map(Object.entries(PRIORITY_LABELS).map(([key, label]) => [label, key]))
+const STATUS_HEADINGS = [
+  ['active', '未完成'],
+  ['done', '已完成'],
+  ['archived', '已归档'],
+]
+
+/** @param {string} text @returns {string} */
+function clean(text) {
+  return String(text ?? '').replace(/\r\n?/g, '\n')
+}
+
+/**
+ * @param {{ todos: object[] }} doc
+ * @param {{ now?: number, title?: string }} [options]
+ * @returns {string}
+ */
+export function toMarkdown(doc, options = {}) {
+  const todos = Array.isArray(doc?.todos) ? doc.todos : []
+  const now = options.now ?? Date.now()
+  const lines = [
+    '# ' + (options.title ?? '全局待办'),
+    '',
+    '> 导出时间 ' + new Date(now).toISOString() + '，共 ' + todos.length + ' 条。',
+    '',
+  ]
+  for (const [status, heading] of STATUS_HEADINGS) {
+    const group = todos.filter((todo) => {
+      const resolved = todo.status === 'done' ? 'done' : todo.status === 'archived' ? 'archived' : 'active'
+      return resolved === status
+    })
+    if (group.length === 0) continue
+    lines.push('## ' + heading, '')
+    for (const todo of group) {
+      lines.push('- [' + (todo.status === 'done' ? 'x' : ' ') + '] ' + todo.title)
+      const meta = []
+      if (todo.priority !== 'normal') meta.push('优先级: ' + (PRIORITY_LABELS[todo.priority] ?? todo.priority))
+      if (todo.dueAt !== null && todo.dueAt !== undefined) meta.push('截止: ' + todo.dueAt)
+      if (Array.isArray(todo.tags) && todo.tags.length > 0) meta.push('标签: ' + todo.tags.join(', '))
+      if (todo.seq > 0) meta.push('#: ' + todo.seq)
+      if (meta.length > 0) lines.push('      ' + meta.join(' · '))
+      if (todo.evidence) lines.push('      原话: ' + todo.evidence)
+      if (todo.description) {
+        for (const line of clean(todo.description).split('\n')) lines.push('      描述: ' + line)
+      }
+      for (const step of todo.steps ?? []) lines.push('      - [' + (step.done === true ? 'x' : ' ') + '] ' + step.text)
+      for (const link of todo.links ?? []) lines.push('      附件: ' + link.value)
+      lines.push('')
+    }
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Read back what {@link toMarkdown} wrote, tolerantly.
+ *
+ * @param {string} text
+ * @returns {{ todos: object[] }} the same document shape `/import` accepts
+ */
+export function fromMarkdown(text) {
+  const todos = []
+  let current = null
+  for (const raw of clean(text).split('\n')) {
+    const line = raw.replace(/\s+$/, '')
+    const task = /^- \[([ xX])\] (.+)$/.exec(line)
+    if (task !== null) {
+      current = {
+        title: task[2].trim(),
+        status: task[1].toLowerCase() === 'x' ? 'done' : 'open',
+        description: '',
+        priority: 'normal',
+        tags: [],
+        steps: [],
+        links: [],
+      }
+      todos.push(current)
+      continue
+    }
+    const step = /^\s+- \[([ xX])\] (.+)$/.exec(line)
+    if (step !== null && current !== null) {
+      current.steps.push({ text: step[2].trim(), done: step[1].toLowerCase() === 'x' })
+      continue
+    }
+    const field = /^\s{2,}(优先级|截止|标签|描述|原话|附件|#): ?(.*)$/.exec(line)
+    if (field === null || current === null) continue
+    const [, key, value] = field
+    if (key === '描述') {
+      // Description lines are free text: they may contain ' · ' or anything else.
+      current.description = current.description === '' ? value : current.description + '\n' + value
+      continue
+    }
+    if (key === '原话') {
+      current.evidence = value
+      continue
+    }
+    if (key === '附件') {
+      current.links.push(value.trim())
+      continue
+    }
+    // One meta line packs several fields ('优先级: 高 · 截止: … · 标签: …'): split it back
+    // into segments before reading any of them.
+    for (const segment of (key + ': ' + value).split(' · ')) {
+      const one = /^(优先级|截止|标签|#): ?(.*)$/.exec(segment)
+      if (one === null) continue
+      const [, name, raw] = one
+      if (name === '优先级') current.priority = PRIORITY_BY_LABEL.get(raw.trim()) ?? 'normal'
+      else if (name === '标签') current.tags = raw.split(',').map((tag) => tag.trim()).filter((tag) => tag !== '')
+      else if (name === '#') current.seq = Number.parseInt(raw, 10) || 0
+      else if (name === '截止') {
+        // A date that does not parse is dropped: one bad line must not fail the file.
+        if (!Number.isNaN(Date.parse(raw))) current.dueAt = new Date(raw).toISOString()
+      }
+    }
+  }
+  return { todos }
+}

package/lib/report.js

@@ -0,0 +1,88 @@
+/**
+ * What the agents did, this week.
+ *
+ * The per-todo completion record already holds the facts: who finished it, what they said,
+ * and which files the work produced. This turns those records into the one page a person
+ * actually asks for — "what moved, and did any of it land in code" — without inventing a
+ * second source of truth: everything here is derived from `completion`, `doneAt` and
+ * `review`.
+ *
+ * Pure and time-explicit: the caller passes `now`, so a test never depends on the clock.
+ */
+
+/** How many files are listed before the tail is summarised. */
+const FILE_LIMIT = 12
+
+/**
+ * @param {object[]} todos
+ * @param {{ now?: number, days?: number }} [options]
+ * @returns {{
+ *   since: number,
+ *   days: number,
+ *   finished: object[],
+ *   created: number,
+ *   sessions: number,
+ *   files: Array<{ path: string, count: number, titles: string[] }>,
+ *   pendingReview: number,
+ * }}
+ */
+export function weeklyReport(todos, options = {}) {
+  const now = options.now ?? Date.now()
+  const days = Number.isFinite(options.days) && options.days > 0 ? Math.min(options.days, 90) : 7
+  const since = now - days * 24 * 60 * 60 * 1000
+  const list = Array.isArray(todos) ? todos : []
+
+  const finished = []
+  let created = 0
+  const sessions = new Set()
+  const files = new Map()
+  let pendingReview = 0
+
+  for (const todo of list) {
+    if (typeof todo.createdAt === 'number' && todo.createdAt >= since) created += 1
+    if (todo.status === 'done' && todo.review?.pending === true) pendingReview += 1
+    const completion = todo.completion
+    if (completion === null || completion === undefined) continue
+    const at = Number.isFinite(completion.at) ? completion.at : todo.doneAt
+    if (!Number.isFinite(at) || at < since) continue
+
+    const artifacts = Array.isArray(completion.artifacts) ? completion.artifacts : []
+    finished.push({
+      id: todo.id,
+      seq: todo.seq ?? 0,
+      title: todo.title,
+      at,
+      by: completion.by,
+      summary: completion.summary ?? '',
+      sessionId: completion.sessionId ?? '',
+      reviewPending: todo.review?.pending === true,
+      artifacts: artifacts.slice(0, 5).map((link) => ({ kind: link.kind, value: link.value, title: link.title })),
+      artifactCount: artifacts.length,
+    })
+
+    if (typeof completion.sessionId === 'string' && completion.sessionId !== '') sessions.add(completion.sessionId)
+    for (const link of artifacts) {
+      if (link?.kind !== 'file') continue
+      const path = String(link.value ?? '')
+      if (path === '') continue
+      const entry = files.get(path) ?? { path, count: 0, titles: [] }
+      entry.count += 1
+      if (entry.titles.length < 3) entry.titles.push(todo.title)
+      files.set(path, entry)
+    }
+  }
+
+  finished.sort((a, b) => b.at - a.at)
+  const topFiles = [...files.values()].sort((a, b) => b.count - a.count || a.path.localeCompare(b.path))
+
+  return {
+    since,
+    days,
+    finished,
+    created,
+    sessions: sessions.size,
+    files: topFiles.slice(0, FILE_LIMIT),
+    fileCount: topFiles.length,
+    pendingReview,
+  }
+}

package/lib/routes.js

@@ -27,6 +27,8 @@ import path from 'node:path'
 
 import { TodoError, asTodoError } from './errors.js'
 import { MAX_INGEST_ITEMS } from './ingest.js'
+import { fromMarkdown, toMarkdown } from './markdown.js'
+import { weeklyReport } from './report.js'
 
 /** Route prefix. The client appends this to the document base. */
 export const ROUTE_BASE = '/api/global-todo'
@@ -362,8 +364,13 @@ export function createRoutes(deps) {
      * This is the store's own document, not the annotated `/list` shape: an export
      * is something `/import` has to be able to hand back unchanged.
      */
-    exact('GET', `${ROUTE_BASE}/export`, async () => {
+    exact('GET', `${ROUTE_BASE}/export`, async (request) => {
       const doc = await service.exportDocument()
+      // `format=md` is for people and repositories: it diffs, it renders, it can be edited
+      // by hand. The JSON document stays the round-trip format.
+      if ((params(request).get('format') ?? '') === 'md') {
+        return { markdown: toMarkdown(doc), count: doc.todos.length, exportedAt: new Date().toISOString() }
+      }
       return { doc, count: doc.todos.length, exportedAt: new Date().toISOString() }
     }),
 
@@ -376,9 +383,31 @@ export function createRoutes(deps) {
      */
     exact('POST', `${ROUTE_BASE}/import`, async (request) => {
       const body = await readJsonBody(request)
+      if (typeof body.markdown === 'string') {
+        // Markdown has no ids, so it is not a document restore: it is a list of items to
+        // add. Going through `create` means one validation path, honest ids, and a file
+        // can never silently overwrite a record that happened to share an id.
+        const parsed = fromMarkdown(body.markdown).todos
+        if (parsed.length === 0) throw new TodoError('invalid-body', '这份 Markdown 里没有可识别的待办（- [ ] 标题）')
+        const created = []
+        for (const item of parsed) created.push(await service.create(item, { by: 'human' }))
+        return { mode: 'markdown', imported: created.length, todos: created }
+      }
       return service.importDocument(body.doc ?? body, { mode: body.mode, dryRun: body.dryRun === true })
     }),
 
+    /**
+     * What the agents finished in the last N days, and what it touched.
+     *
+     * Derived, never stored: completion records already hold the facts, and a cached
+     * aggregate would be a second truth to keep honest.
+     */
+    exact('GET', `${ROUTE_BASE}/report`, async (request) => {
+      const days = Number.parseInt(params(request).get('days') ?? '', 10)
+      const todos = await service.listAll()
+      return { report: weeklyReport(todos, { days: Number.isFinite(days) ? days : 7 }) }
+    }),
+
     exact('GET', `${ROUTE_BASE}/health`, async () => {
       // Counted once: the size feeds the metrics snapshot and the counts the panel
       // reads are the same numbers, so /health cannot contradict itself.

package/lib/service.js

@@ -246,6 +246,18 @@ export function createService(options) {
    * @param {{ status?: string, query?: string, tag?: string, sort?: string, limit?: number }} [query]
    * @returns {Promise<{ todos: object[], counts: object, matched: number, truncated: boolean }>}
    */
+  /**
+   * Every stored todo, unfiltered and unpaged.
+   *
+   * For aggregates that must not be narrowed by whatever the panel is currently
+   * showing — a weekly report over the visible page would be a lie of omission.
+   *
+   * @returns {Promise<object[]>}
+   */
+  async function listAll() {
+    return store.all()
+  }
+
   async function list(query = {}) {
     const todos = await store.all()
     const selected = select(todos, query)
@@ -799,6 +811,7 @@ export function createService(options) {
 
   return {
     list,
+    listAll,
     get,
     create,
     update,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.9.0",
+  "version": "0.10.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",