dsh-global-todo 0.4.6 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-10-19
+
+The last two pieces of the automatic-capture plan: an external door, and somewhere for its
+uncertain items to wait.
+
+- **`POST /ingest` is the only external entrance.** It is closed until `ingestEnabled` is true
+  and a token is set; the token is compared in constant time, never returned by `/health`, and
+  the settings file is chmod 600 because it may hold it. Every item must name a source
+  (`mail` / `notification` / `announcement`) and a confidence, so nothing anonymous lands in the
+  list.
+- **Low-confidence items wait in an inbox instead of joining the list.** Below
+  `ingestConfirmBelow` (default 0.8) a record is tagged `inbox`; the panel shows an inbox filter
+  chip, a 待确认 badge, and 确认 / 丢弃 in the row menu. Confirming only removes the mark;
+  discarding archives it. A weekly sweep archives inbox records nobody confirmed in seven days,
+  so the inbox cannot become a second list.
+- Items still pass the same dedupe gate as `global_todo_capture`; provenance stays visible as a
+  `source:<kind>` tag after confirmation.
+## [0.4.7] — 2026-10-19
+
+Verified against the running GUI this time, with measured numbers instead of arithmetic.
+
+- **The card no longer overlaps the list by its own padding.** `width: 360px` was applied
+  content-box, so the card was 394px wide while the list reserved 380px — a 14px overlap that
+  only showed up in a live box measurement. It is `box-sizing: border-box` now (990–1350 against
+  a list ending at 970 at 1440×900).
+- **Its vertical brackets come from the list, not the panel.** The panel fills the window, so
+  measuring its bottom put the card over the footer; the anchors now come from `.gt-groups`
+  (top + 10) and its bottom (+ 8 gap above the footer).
 ## [0.4.6] — 2026-10-19
 
 The card existed; where it landed depended on a viewport assumption that the real shell does not

package/README.md

@@ -247,6 +247,7 @@ fence when that service is present, and by a strict loopback check otherwise.
 | POST | `/api/global-todo/import` | `{ doc, mode?: replace\|merge }` — `replace` is an exact round trip, `merge` updates by id and appends (what the panel sends) |
 | POST | `/api/global-todo/capture` | `{ sessionId? }` — ask the current conversation to collect its follow-ups |
 | POST | `/api/global-todo/bulk` | `{ ids, status?, addTags?, removeTags? }` — one change across a selection; a stale id lands in `unmatched` instead of failing the batch |
+| POST | `/api/global-todo/ingest` | `{ items: [{ title, source: { kind }, confidence }], dryRun? }` with `Authorization: Bearer <settings.ingestToken>` — external items; below `ingestConfirmBelow` they wait in the inbox |
 | 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/update` | `{ id, ...fields, by?: human\|agent }` |
@@ -360,6 +361,12 @@ docs/          DESIGN.md (data model and rejected alternatives), ROADMAP.md
 
 Contributions are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md) first.
 
+## Feedback
+
+Questions, bug reports and ideas go to [Discussions](https://github.com/LUgABeEEE/dsh-global-todo/discussions).
+When reporting a bug, include the DSH version, the plugin version from the panel footer, your OS and
+the steps that reproduce it; a screenshot of the notice is worth more than a paragraph. Security
+issues go through [SECURITY.md](SECURITY.md) instead, not the discussion board.
 ## Security
 
 The HTTP surface is local-only, the list is a local file, and no credential is ever stored.

package/README.zh.md

@@ -144,6 +144,7 @@ dsh plugin --profile web remove dsh-global-todo
 | POST | `/api/global-todo/note` | `{ id, text }`（追加进展记录） |
 | POST | `/api/global-todo/capture` | `{ sessionId? }`（请当前对话把要跟进的事抓进清单） |
 | 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/update` | `{ id, ...字段, by?: human\|agent }` |
@@ -251,6 +252,11 @@ docs/          DESIGN.md（数据模型与取舍）、ROADMAP.md
 
 欢迎贡献，先读 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
+## 反馈
+
+问题、bug 和想法都发到 [Discussions](https://github.com/LUgABeEEE/dsh-global-todo/discussions)。
+报 bug 时带上 DSH 版本、面板页脚里的插件版本、系统，以及能复现的步骤；提示语截图比一段描述更有用。
+安全问题请走 [SECURITY.md](SECURITY.md)，不要发在讨论区。
 ## 安全
 
 HTTP 接口只服务本机，清单是本地文件，任何凭据都不会被存储。

package/docs/DESIGN.md

@@ -79,6 +79,16 @@ be noise) and exported through `describe()` as `externalChanges` / `lastExternal
 turns a new count into a one-line notice. `store.read` still trusts a file that parses, because
 **this process** has no way to merge two writers' intent — but the person can now see that it
 happened instead of discovering it a day later.
+## An external door with a waiting room
+
+Ingest is the only entrance a person did not open in a conversation, so it is closed by default:
+`ingestEnabled` must be true and `ingestToken` must match (compared over SHA-256 digests, in
+constant time), and `/health` reports only `tokenSet`. Every item names a source kind and a
+confidence; a kind outside the whitelist is refused rather than filed as "unknown". Below
+`ingestConfirmBelow` the record is created with the `inbox` tag — it exists, but it is not on the
+list until a person confirms it. Confirming removes the tag, discarding archives the record, and a
+weekly sweep archives what nobody touched in seven days. Provenance survives as a `source:<kind>`
+tag, because "where did this come from" is the first question a surprised person asks.
 ## Attachments: references, not uploads
 
 An attachment is either an address (`http`/`https`) or an absolute path. Rules:

package/docs/ROADMAP.md

@@ -113,6 +113,9 @@ list silently.
 **Side detail on wide windows** — above 1100px the open row's detail becomes a card at the
 panel's right edge instead of pushing the list down (CSS-only over the same markup; one detail
 implementation), while narrow windows keep the inline expansion.
+**External ingest with an inbox** — `POST /ingest` takes source-tagged, confidence-scored items
+behind a Bearer token; low-confidence records wait in an `inbox` tag view with 确认 / 丢弃 and a
+seven-day sweep, so an external source cannot silently fill the list.
 ### Partly landed
 
 - **Batch and multi-select** — the selection mode, its per-row markers and the batch

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 = 'ui29'
+    const UI_REV = 'ui31'
     /** Last language resolved for the shell; module-level so a fetch failure can be worded too. */
     let activeLang = 'zh'
 
@@ -183,6 +183,10 @@ window.__ModuleLoader__.load({
       'filter.done': '已完成',
       'filter.overdue': '逾期',
       'filter.archived': '已归档',
+      'filter.inbox': '收件箱',
+      'action.confirm': '确认',
+      'action.discard': '丢弃',
+      'meta.inbox': '待确认',
       'filter.label': '筛选',
       'field.title': '要做什么？回车即存',
       'field.description': '描述：验收标准、已知的坑…',
@@ -396,6 +400,10 @@ window.__ModuleLoader__.load({
       'filter.done': 'Done',
       'filter.overdue': 'Overdue',
       'filter.archived': 'Archived',
+      'filter.inbox': 'Inbox',
+      'action.confirm': 'Confirm',
+      'action.discard': 'Discard',
+      'meta.inbox': 'Needs review',
       'filter.label': 'Filters',
       'field.title': 'What needs doing? Enter to save',
       'field.description': 'Description: acceptance, known traps…',
@@ -984,6 +992,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
   border: 1px solid var(--dsw-alias-brand-primary); border-radius: 9px; background: var(--dsw-alias-bg-layer-1); font-size: 12.5px; }
 .gt-item-body { flex: 1; display: flex; flex-direction: column; gap: 5px; min-width: 0; }
 .gt-item-title { font-weight: 600; font-size: 13.5px; word-break: break-word; line-height: 1.45; }
+.gt-inbox { margin-left: 6px; padding: 1px 6px; border-radius: 999px; font-size: 10.5px; font-weight: 600;
+  color: var(--dsw-alias-state-warn-primary); border: 1px solid var(--dsw-alias-state-warn-primary);
+  vertical-align: 1px; }
 .gt-item[data-status="done"] .gt-item-title, .gt-item[data-status="cancelled"] .gt-item-title {
   text-decoration: line-through; color: var(--dsw-alias-label-secondary); }
 .gt-meta { display: flex; gap: 5px 8px; flex-wrap: wrap; color: var(--dsw-alias-label-secondary); font-size: 11.5px;
@@ -1021,6 +1032,9 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
        always fill the window, and a viewport-centred offset put the card over the list. */
     /* The var fallback matters for the static previews (server-rendered, so effects never
        run): they assume the panel is the centred 980px column. */
+    /* border-box matters: 360px is the whole card, so the list's 380px reservation leaves
+       a gap instead of overlapping by the padding width. */
+    box-sizing: border-box;
     position: fixed; top: var(--gt-detail-top, 208px);
     right: var(--gt-detail-right, max(24px, calc((100vw - 980px) / 2 + 24px)));
     bottom: var(--gt-detail-bottom, 64px); width: 360px;
@@ -1513,7 +1527,14 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
           h(
             'div',
             { className: 'gt-item-body' },
-            h('div', { className: 'gt-item-title' }, todo.title),
+            h(
+              'div',
+              { className: 'gt-item-title' },
+              todo.title,
+              todo.tags.some((tag) => tag.toLowerCase() === 'inbox')
+                ? h('span', { className: 'gt-inbox' }, t('meta.inbox'))
+                : null,
+            ),
             h(
               'div',
               { className: 'gt-meta' },
@@ -1629,6 +1650,12 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
             h(Menu, {
               label: t('action.menu'),
               items: [
+                ...(todo.tags.some((tag) => tag.toLowerCase() === 'inbox')
+                  ? [
+                      { key: 'confirm', label: t('action.confirm'), icon: 'check', onSelect: () => onAction('confirm', todo) },
+                      { key: 'discard', label: t('action.discard'), icon: 'trash', danger: true, onSelect: () => onAction('discard', todo) },
+                    ]
+                  : []),
                 {
                   key: 'toggle',
                   label: open ? t('action.hide') : t('action.detail'),
@@ -2160,10 +2187,18 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
 
       const reload = useCallback(
         async (next = {}) => {
-          const status = next.filter ?? filter
+          const selected = next.filter ?? filter
+          // The inbox is a tag view over active records, not a status of its own.
+          const status = selected === 'inbox' ? 'active' : selected
           const search = next.query ?? query
           try {
-            const data = await call('list', { query: { status, ...(search.trim() === '' ? {} : { query: search.trim() }) } })
+            const data = await call('list', {
+              query: {
+                status,
+                ...(selected === 'inbox' ? { tag: 'inbox' } : {}),
+                ...(search.trim() === '' ? {} : { query: search.trim() }),
+              },
+            })
             if (!mounted.current) return
             setState((current) => ({
               ...current,
@@ -2216,10 +2251,14 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
           const element = innerRef.current
           if (element === null) return
           const rect = element.getBoundingClientRect()
+          // Bracket the card against the scrolling list, not the panel box: the footer sits
+          // below the list, and the panel's own bottom is below that.
+          const groups = document.querySelector('.gt-groups')
+          const list = groups === null ? null : groups.getBoundingClientRect()
           setDetailAnchor({
-            top: Math.round(rect.top + 170),
+            top: Math.round((list === null ? rect.top + 190 : list.top) + 10),
             right: Math.round(window.innerWidth - rect.right + 20),
-            bottom: Math.round(window.innerHeight - rect.bottom + 20),
+            bottom: Math.round(window.innerHeight - (list === null ? rect.bottom : list.bottom) + 8),
           })
         }
         measure()
@@ -2708,6 +2747,14 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         if (kind === 'done') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'done' } }))
         if (kind === 'reopen') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'open' } }))
         if (kind === 'doing') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'doing' } }))
+        // Confirming keeps the record on the list; discarding archives it. Both only remove
+        // the "waiting for a person" mark — the provenance tag stays.
+        if (kind === 'confirm') {
+          return run(todo.id, () => call('bulk', { method: 'POST', body: { ids: [todo.id], removeTags: ['inbox'] } }))
+        }
+        if (kind === 'discard') {
+          return run(todo.id, () => call('bulk', { method: 'POST', body: { ids: [todo.id], status: 'archived', removeTags: ['inbox'] } }))
+        }
         // Archive keeps the history without cluttering the list; delete stays a separate,
         // deliberate action reached only through the two-step menu item.
         if (kind === 'archive') return run(todo.id, () => call('status', { method: 'POST', body: { id: todo.id, status: 'archived' } }))
@@ -2782,7 +2829,7 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
         }
       }
 
-      const counts = state.counts ?? { total: 0, open: 0, doing: 0, done: 0, cancelled: 0, archived: 0, overdue: 0 }
+      const counts = state.counts ?? { total: 0, open: 0, doing: 0, done: 0, cancelled: 0, archived: 0, overdue: 0, inbox: 0 }
       const groups = useMemo(
         () => groupTodos(state.todos, Date.now(), groupMode, sessionTitles, t),
         [state.todos, groupMode, sessionTitles, lang],
@@ -3009,6 +3056,7 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                 // Only shown once something is archived: an empty filter that exists from
                 // day one is furniture, not a control.
                 ...(counts.archived > 0 ? [['archived', counts.archived]] : []),
+                ...(counts.inbox > 0 ? [['inbox', counts.inbox]] : []),
               ].map(([key, count]) => filterChip(key, key === 'all' ? undefined : count)),
             ),
             h('span', { className: 'gt-divider' }),

package/lib/errors.js

@@ -27,6 +27,7 @@ export const ERROR_CODES = Object.freeze([
   'agents-unavailable',
   'dispatch-failed',
   'forbidden',
+  'unauthorized',
   'internal',
 ])
 

package/lib/index.js

@@ -35,7 +35,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.4.6'
+export const VERSION = '0.5.0'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'
@@ -99,6 +99,23 @@ export function apply(ctx, config) {
   // back by the plugin itself.
   const metrics = createMetrics()
   const service = createService({ store, config: resolved, logger, metrics })
+  // The inbox must not become a second list. A weekly sweep archives what nobody
+  // confirmed; the record keeps its history, it just leaves the active view.
+  ctx.effect(() => {
+    const sweep = () => {
+      void service
+        .expireInbox({ days: 7 })
+        .then((result) => {
+          if (result?.expired > 0) logger?.info?.(`dsh-global-todo: archived ${result.expired} unconfirmed inbox item(s)`)
+        })
+        .catch((error) => logger?.warn?.(`dsh-global-todo: inbox expiry failed: ${error?.message ?? error}`))
+    }
+    sweep()
+    if (typeof setInterval !== 'function') return () => {}
+    const timer = setInterval(sweep, 6 * 60 * 60 * 1000)
+    if (typeof timer.unref === 'function') timer.unref()
+    return () => clearInterval(timer)
+  }, 'dsh-global-todo: inbox expiry')
   // Which conversation did the user last write in?
   //
   // The panel is the main view while it is open, so it cannot always see that.

package/lib/ingest.js

@@ -0,0 +1,80 @@
+/**
+ * Ingest quality gate.
+ *
+ * The external door is the only entrance to the list that a person did not open in a
+ * conversation, so it gets checked before it is opened: a named source, a stated confidence,
+ * and — below the confidence threshold — the inbox rather than the main list. The rules are
+ * pure so they can be tested without a store or a route.
+ *
+ * @module dsh-global-todo/ingest
+ */
+
+import { INGEST_SOURCES } from './settings.js'
+
+/** Tag that marks a record as waiting for a person. */
+export const INBOX_TAG = 'inbox'
+/** Upper bound on one ingest request; a mail batch is not a migration. */
+export const MAX_INGEST_ITEMS = 100
+
+/**
+ * Validate one external item and decide where it lands.
+ *
+ * @param {unknown} raw
+ * @param {{ confirmBelow?: number }} [options]
+ * @returns {{ item?: object, source?: string, confidence?: number, inbox?: boolean, error?: string }}
+ */
+export function normalizeIngestItem(raw, options = {}) {
+  const confirmBelow = Number.isFinite(options.confirmBelow) ? options.confirmBelow : 0.8
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return { error: '条目必须是对象' }
+  const title = typeof raw.title === 'string' ? raw.title.trim() : ''
+  if (title === '') return { error: '缺 title' }
+  if (title.length > 500) return { error: 'title 超过 500 字' }
+  const source = raw.source !== null && typeof raw.source === 'object' && !Array.isArray(raw.source) ? raw.source : {}
+  const kind = typeof source.kind === 'string' ? source.kind.trim().toLowerCase() : ''
+  if (!INGEST_SOURCES.includes(kind)) return { error: `source.kind 必须是 ${INGEST_SOURCES.join(' / ')}` }
+  const confidence = Number(raw.confidence)
+  if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) return { error: 'confidence 必须是 0–1' }
+  // High-confidence items join the list; the rest wait. Both keep the provenance tag so a
+  // person can still see where a record came from after it is confirmed.
+  const inbox = confidence < confirmBelow
+  const tags = [INBOX_TAG, `source:${kind}`]
+  if (!inbox) tags.shift()
+  const item = { title, tags }
+  if (typeof raw.description === 'string') item.description = raw.description
+  if (raw.dueAt !== undefined) item.dueAt = raw.dueAt
+  if (raw.priority !== undefined) item.priority = raw.priority
+  if (Array.isArray(raw.links)) item.links = raw.links
+  return { item, source: kind, confidence, inbox }
+}
+
+/**
+ * Does this record still wait for a person?
+ *
+ * @param {object} todo
+ * @returns {boolean}
+ */
+export function isInbox(todo) {
+  if (todo === null || typeof todo !== 'object' || !Array.isArray(todo.tags)) return false
+  return todo.tags.some((tag) => String(tag).toLowerCase() === INBOX_TAG)
+}
+
+/**
+ * Which inbox records are old enough to be archived. The inbox must not become a second
+ * list: something nobody confirmed in a week is not a task any more, it is a decision not
+ * taken, and it belongs in the archive rather than at the top of the panel.
+ *
+ * @param {object[]} todos
+ * @param {{ now?: number, days?: number }} [options]
+ * @returns {object[]}
+ */
+export function expiredInbox(todos, options = {}) {
+  const now = Number.isFinite(options.now) ? options.now : Date.now()
+  const days = Number.isFinite(options.days) && options.days > 0 ? options.days : 7
+  const cutoff = now - days * 24 * 60 * 60 * 1000
+  return (Array.isArray(todos) ? todos : []).filter((todo) =>
+    isInbox(todo) &&
+      (todo.status === 'open' || todo.status === 'doing') &&
+      Number.isFinite(todo.createdAt) &&
+      todo.createdAt < cutoff,
+  )
+}

package/lib/model.js

@@ -663,10 +663,15 @@ export function isOverdue(todo, now = Date.now()) {
  * @returns {{ total: number, open: number, doing: number, done: number, cancelled: number, archived: number, overdue: number }}
  */
 export function counts(todos, now = Date.now()) {
-  const out = { total: todos.length, open: 0, doing: 0, done: 0, cancelled: 0, archived: 0, overdue: 0 }
+  const out = { total: todos.length, open: 0, doing: 0, done: 0, cancelled: 0, archived: 0, overdue: 0, inbox: 0 }
   for (const todo of todos) {
     if (todo.status in out) out[todo.status] += 1
     if (isOverdue(todo, now)) out.overdue += 1
+    // Waiting for a person counts only while it is still active; an archived inbox item is
+    // history, not a pending decision.
+    if ((todo.status === 'open' || todo.status === 'doing') && (todo.tags ?? []).some((tag) => tag.toLowerCase() === 'inbox')) {
+      out.inbox += 1
+    }
   }
   return out
 }

package/lib/routes.js

@@ -20,11 +20,13 @@
  * @module dsh-global-todo/routes
  */
 
+import { createHash, timingSafeEqual } from 'node:crypto'
 import { readdir, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
 
 import { TodoError, asTodoError } from './errors.js'
+import { MAX_INGEST_ITEMS } from './ingest.js'
 
 /** Route prefix. The client appends this to the document base. */
 export const ROUTE_BASE = '/api/global-todo'
@@ -119,6 +121,7 @@ async function readJsonBody(request) {
 export function statusForCode(code) {
   if (code === 'not-found') return 404
   if (code === 'payload-too-large') return 413
+  if (code === 'unauthorized') return 401
   if (code === 'forbidden') return 403
   if (code === 'store-corrupt' || code === 'store-unwritable' || code === 'internal') return 500
   if (code === 'agents-unavailable' || code === 'dispatch-failed') return 502
@@ -412,6 +415,14 @@ export function createRoutes(deps) {
           loadedAt: settingsInfo.at,
           loadSource: settingsInfo.source,
           loadError: settingsInfo.error,
+          // The token itself never leaves the settings file; the panel only needs to know
+          // whether one is set before it can usefully show the ingest section.
+          ingest: {
+            enabled: deps.settings?.get?.().ingestEnabled === true,
+            sources: deps.settings?.get?.().ingestSources ?? [],
+            confirmBelow: deps.settings?.get?.().ingestConfirmBelow ?? 0.8,
+            tokenSet: typeof deps.settings?.get?.().ingestToken === 'string' && deps.settings.get().ingestToken !== '',
+          },
         },
         autoCollect: {
           // Derived from the setting, not from a copy kept elsewhere: two sources for one
@@ -459,10 +470,52 @@ export function createRoutes(deps) {
           idleMinutes: next.idleMinutes,
           cooldownMinutes: next.cooldownMinutes,
           exemptWorkspaces: next.exemptWorkspaces,
+          ingest: {
+            enabled: next.ingestEnabled,
+            sources: next.ingestSources,
+            confirmBelow: next.ingestConfirmBelow,
+            tokenSet: next.ingestToken !== '',
+          },
         },
       }
     }),
 
+    exact('POST', `${ROUTE_BASE}/ingest`, async (request) => {
+      const settings = deps.settings?.get?.()
+      if (settings?.ingestEnabled !== true) {
+        throw new TodoError('forbidden', '外部 ingest 未开启（settings.ingestEnabled）')
+      }
+      const expected = typeof settings.ingestToken === 'string' ? settings.ingestToken : ''
+      const header = typeof request.headers.authorization === 'string' ? request.headers.authorization : ''
+      const match = /^Bearer\s+(.+)$/i.exec(header)
+      const supplied = match === null ? '' : match[1].trim()
+      // Hash both sides so the comparison is constant-time regardless of the token's length;
+      // an empty expected token refuses every request rather than matching an empty one.
+      const equal =
+        expected !== '' &&
+        supplied !== '' &&
+        timingSafeEqual(createHash('sha256').update(supplied).digest(), createHash('sha256').update(expected).digest())
+      if (!equal) throw new TodoError('unauthorized', 'ingest token 不正确')
+      const body = await readJsonBody(request)
+      if (!Array.isArray(body.items) || body.items.length === 0) {
+        throw new TodoError('invalid-body', 'items 必须是非空数组')
+      }
+      if (body.items.length > MAX_INGEST_ITEMS) {
+        throw new TodoError('invalid-body', `一次最多 ${MAX_INGEST_ITEMS} 条`)
+      }
+      const result = await service.ingest(body.items, {
+        confirmBelow: settings.ingestConfirmBelow,
+        dryRun: body.dryRun === true,
+      })
+      return {
+        dryRun: body.dryRun === true,
+        accepted: result.created.length,
+        created: result.created,
+        skipped: result.skipped,
+        preview: result.preview,
+      }
+    }),
+
     exact('POST', `${ROUTE_BASE}/assign`, async (request) => {
       const body = await readJsonBody(request)
       return dispatcher.assignMany(body ?? {})

package/lib/service.js

@@ -11,7 +11,9 @@
 
 import { existsSync } from 'node:fs'
 
+import { findDuplicate } from './capture.js'
 import { TodoError } from './errors.js'
+import { expiredInbox, normalizeIngestItem } from './ingest.js'
 import { formatLink } from './links.js'
 import {
   LIMITS,
@@ -666,6 +668,73 @@ export function createService(options) {
     }
     return { updated: updated.length, ids: updated, unmatched, errors }
   }
+
+  /**
+   * Write external items through the same path as everything else.
+   *
+   * The gate decides per item; a rejected item is reported, never silently dropped, and a
+   * partial batch is normal — one bad mail must not discard the other nine.
+   *
+   * @param {object[]} items
+   * @param {{ confirmBelow?: number, dryRun?: boolean }} [options]
+   * @returns {Promise<{ created: object[], skipped: object[], preview: object[] }>}
+   */
+  async function ingest(items, options = {}) {
+    const existing = (await store.all()).slice()
+    const created = []
+    const skipped = []
+    const preview = []
+    for (const raw of Array.isArray(items) ? items : []) {
+      const verdict = normalizeIngestItem(raw, { confirmBelow: options.confirmBelow })
+      if (verdict.error !== undefined) {
+        skipped.push({
+          title: typeof raw?.title === 'string' ? raw.title.slice(0, 80) : '',
+          reason: 'invalid',
+          error: verdict.error,
+        })
+        continue
+      }
+      const duplicate = findDuplicate({ title: verdict.item.title, existing, now: now() })
+      if (duplicate.duplicate === true) {
+        skipped.push({
+          title: verdict.item.title.slice(0, 80),
+          reason: duplicate.reason,
+          error: '清单里已有重复条目，未重复登记',
+        })
+        continue
+      }
+      if (options.dryRun === true) {
+        preview.push({ title: verdict.item.title, tags: verdict.item.tags, inbox: verdict.inbox })
+        continue
+      }
+      const todo = await create(verdict.item, { by: 'agent' })
+      created.push(todo)
+      existing.push(todo)
+    }
+    return { created, skipped, preview }
+  }
+
+  /**
+   * Archive inbox records nobody confirmed in time.
+   *
+   * @param {{ days?: number }} [options]
+   * @returns {Promise<{ expired: number }>}
+   */
+  async function expireInbox(options = {}) {
+    const days = Number.isFinite(options.days) && options.days > 0 ? options.days : 7
+    const at = now()
+    // No stale records, no write: the mount-time sweep must not touch the file just to
+    // report that it had nothing to do.
+    if (expiredInbox(await store.all(), { now: at, days }).length === 0) return { expired: 0 }
+    return store.update((doc) => {
+      const stale = expiredInbox(doc.todos, { now: at, days })
+      for (const todo of stale) {
+        setStatusOn(todo, 'archived', { now: at, by: 'agent', reason: `收件箱超过 ${days} 天未确认` })
+      }
+      return { next: doc.todos, result: { expired: stale.length } }
+    })
+  }
+
   /** @returns {Promise<object>} counts for the panel header and tool summaries */
   async function stats() {
     const todos = await store.all()
@@ -686,6 +755,8 @@ export function createService(options) {
     remove,
     restore,
     bulk,
+    ingest,
+    expireInbox,
     addLink,
     removeLink,
     recordDispatch,

package/lib/settings.js

@@ -8,7 +8,7 @@
  * @module dsh-global-todo/settings
  */
 
-import { readFile, writeFile } from 'node:fs/promises'
+import { chmod, readFile, writeFile } from 'node:fs/promises'
 
 /** How many sessions the cooldown bookkeeping remembers. */
 const ASKED_LIMIT = 50
@@ -31,6 +31,13 @@ export function retryDelayMs(attempts) {
 /** How many exempt workspaces are remembered. */
 const EXEMPT_LIMIT = 50
 
+/**
+ * Where an external item may come from. An ingest request with a kind outside this list is
+ * refused rather than filed under "unknown": provenance the list cannot name is provenance it
+ * cannot reason about later.
+ */
+export const INGEST_SOURCES = Object.freeze(['mail', 'notification', 'announcement'])
+
 export const SETTINGS_DEFAULTS = Object.freeze({
   /** Ask a conversation to collect todos on its own. Off until a person says so. */
   autoCollect: false,
@@ -52,6 +59,13 @@ export const SETTINGS_DEFAULTS = Object.freeze({
    * The path is the stable fact about such a place.
    */
   exemptWorkspaces: [],
+  /** External ingest is off until a person turns it on and sets a token. */
+  ingestEnabled: false,
+  /** Bearer token for `/ingest`. Empty refuses every request. Never returned by `/health`. */
+  ingestToken: '',
+  ingestSources: [...INGEST_SOURCES],
+  /** Items below this confidence wait in the inbox instead of joining the list. */
+  ingestConfirmBelow: 0.8,
 })
 
 /**
@@ -83,12 +97,26 @@ export function normalizeSettings(raw) {
     if (exemptWorkspaces.length >= EXEMPT_LIMIT) break
     exemptWorkspaces.push(dir)
   }
+  const sources = []
+  for (const entry of Array.isArray(source.ingestSources) ? source.ingestSources : []) {
+    if (typeof entry !== 'string') continue
+    const kind = entry.trim().toLowerCase()
+    if (!INGEST_SOURCES.includes(kind) || sources.includes(kind)) continue
+    sources.push(kind)
+  }
+  const below = Number(source.ingestConfirmBelow)
   return {
     autoCollect: source.autoCollect === true,
     cooldownMinutes: Number.isInteger(minutes) ? Math.min(Math.max(minutes, 5), 24 * 60) : SETTINGS_DEFAULTS.cooldownMinutes,
     idleMinutes: Number.isInteger(idle) ? Math.min(Math.max(idle, 5), 24 * 60) : SETTINGS_DEFAULTS.idleMinutes,
     asked,
     exemptWorkspaces,
+    ingestEnabled: source.ingestEnabled === true,
+    // A token is opaque: no shape rule beyond "not empty", trimmed and capped so a pasted
+    // blob cannot become the whole settings file.
+    ingestToken: typeof source.ingestToken === 'string' ? source.ingestToken.trim().slice(0, 512) : '',
+    ingestSources: sources.length === 0 ? [...INGEST_SOURCES] : sources,
+    ingestConfirmBelow: Number.isFinite(below) ? Math.min(Math.max(below, 0), 1) : SETTINGS_DEFAULTS.ingestConfirmBelow,
   }
 }
 
@@ -127,6 +155,9 @@ export function createSettings(options) {
   const persist = async () => {
     try {
       await writeFile(options.file, `${JSON.stringify({ version: 1, ...state }, null, 2)}\n`, 'utf8')
+      // The file can hold an ingest token; keep it readable by the Host user only. Best-effort:
+      // a filesystem without POSIX modes must not fail the write.
+      await chmod(options.file, 0o600).catch(() => {})
     } catch (error) {
       options.logger?.warn?.(`dsh-global-todo: 设置无法写入（${String(error?.message ?? error)}）`)
     }

package/package.json

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