dsh-global-todo 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.15.0] — 2026-10-22
+
+Image attachments: a reference that renders, not a copy that goes stale.
+
+- **`kind: "image"` is a third attachment kind** beside `url` and `file`. The path stays an
+  absolute reference — the list still never stores bytes — but it must have a renderable
+  extension (png / jpg / jpeg / webp / gif / avif; SVG is excluded because it can carry script
+  when served inline). A bare path is never guessed into an image: the caller states it.
+- **`GET /asset?id=&index=` serves the bytes**, reading the path out of the store rather than from
+  the request, so there is no traversal surface. Capped at 8 MB with `nosniff`, and only for
+  `image` links — a document link asked through this route is a 400, a missing index a 404.
+- **The panel shows a thumbnail on the row and a preview in the detail**, both lazy, and the
+  existing "file is gone" marker still applies: a dead image renders as a bad chip, not a broken
+  frame.
+- Tool schemas accept `kind: "image"` wherever an attachment does, so an agent can attach a
+  screenshot of what it built.
+
 ## [0.14.0] — 2026-10-22
 
 Choose how much surface a deployment pays for.

package/README.md

@@ -211,7 +211,10 @@ Your list is not touched by install or uninstall: it lives outside the plugin, a
 ### The panel
 
 - **Add** — type a title and press Enter. "More fields" reveals the description, the
-  attachment box (one document path or URL per line), tags, priority and a due time.
+  attachment box (one document path or URL per line), tags, priority and a due time. An
+  attachment may also be `{ kind: "image", value: "/abs/shot.png" }` — the row then shows a
+  thumbnail and the detail a preview, with the bytes read on demand (png/jpg/jpeg/webp/gif/avif,
+  ≤8 MB) and never copied into the list.
 - **Filters** — all / open / doing / done / overdue, plus a text search across titles,
   descriptions, tags and attachments. The count chips in the header are filters too.
 - **Grouped by urgency** — overdue / today / next up / later / no due date / done, each
@@ -390,6 +393,7 @@ fence when that service is present, and by a strict loopback check otherwise.
 | 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`) |
+| GET | `/api/global-todo/asset?id=&index=` | the bytes of an **image** attachment (path read from the store, never from the request; ≤8 MB, png/jpg/jpeg/webp/gif/avif) |
 | 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

@@ -188,6 +188,7 @@ dsh plugin --profile web remove dsh-global-todo
 
 ### 面板
 
+- **图片附件**：附件也可以写成 `{ "kind": "image", "value": "/绝对路径/shot.png" }`，行上显示缩略图、详情里显示预览；字节按需读取（png/jpg/jpeg/webp/gif/avif，≤8MB），**不复制进清单**。
 - **添加**：写一句标题回车即存。「更多字段」展开描述、附件框（一行一个文档绝对路径或网址）、
   标签、优先级、截止时间。
 - **筛选**：全部 / 未完成 / 进行中 / 已完成 / 逾期，外加跨标题、描述、标签、附件的文本搜索；
@@ -293,6 +294,7 @@ dsh plugin --profile web remove dsh-global-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`） |
+| GET | `/api/global-todo/asset?id=&index=` | 读**图片附件**的字节（路径只从待办记录里取，不接受请求传路径；≤8MB，png/jpg/jpeg/webp/gif/avif） |
 | 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/lib/client.js

@@ -40,6 +40,11 @@ window.__ModuleLoader__.load({
     const LOCALE_NS = 'global-todo'
     /** Route prefix, relative to the document base. */
     const API = 'api/global-todo'
+    /**
+     * Where an image attachment's bytes come from. The route reads the path out of the
+     * store, so this URL carries an id and an index — never a filesystem path.
+     */
+    const assetUrl = (id, index) => `${API}/asset?id=${encodeURIComponent(id)}&index=${index}`
     const POLL_MS = 20000
     /** How long a deleted todo can be brought back. */
     const UNDO_MS = 8000
@@ -1329,6 +1334,11 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
 .gt-attach .gt-chip { max-width: 280px; color: var(--dsw-alias-label-secondary); }
 .gt-attach a.gt-chip:hover { color: var(--dsw-alias-label-primary); border-color: var(--dsw-alias-border-l2); }
 .gt-attach-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.gt-chip-img { padding: 2px 8px 2px 3px; }
+.gt-thumb { width: 16px; height: 16px; object-fit: cover; border-radius: 999px; display: block; }
+.gt-shot-wrap { display: inline-flex; }
+.gt-shot { width: 84px; height: 56px; object-fit: cover; border-radius: 6px;
+  border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2); }
 .gt-menu { position: absolute; top: 40px; right: 10px; z-index: 3; min-width: 184px; display: flex;
   flex-direction: column; padding: 5px; background: var(--dsw-alias-bg-overlay);
   border: 1px solid var(--dsw-alias-border-l2); border-radius: 10px; }
@@ -1935,7 +1945,21 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                   'div',
                   { className: 'gt-attach' },
                   todo.links.slice(0, MAX_LINK_CHIPS).map((link, index) =>
-                    link.kind === 'url'
+                    link.kind === 'image' && link.missing !== true
+                      ? h(
+                          'a',
+                          {
+                            key: `${index}:${link.value}`,
+                            className: 'gt-chip gt-chip-img',
+                            href: assetUrl(todo.id, index),
+                            target: '_blank',
+                            rel: 'noreferrer noopener',
+                            title: link.value,
+                          },
+                          h('img', { className: 'gt-thumb', src: assetUrl(todo.id, index), alt: link.title, loading: 'lazy' }),
+                          h('span', { className: 'gt-attach-title' }, link.title),
+                        )
+                      : link.kind === 'url'
                       ? h(
                           'a',
                           {
@@ -2376,6 +2400,19 @@ button.gt-chip[data-on="1"] { color: var(--dsw-alias-label-primary); border-colo
                         h(
                           'li',
                           { className: 'gt-link', key: `${link.kind}:${link.value}` },
+                          link.kind === 'image' && link.missing !== true
+                            ? h(
+                                'a',
+                                {
+                                  className: 'gt-shot-wrap',
+                                  href: assetUrl(todo.id, index),
+                                  target: '_blank',
+                                  rel: 'noreferrer noopener',
+                                  title: link.value,
+                                },
+                                h('img', { className: 'gt-shot', src: assetUrl(todo.id, index), alt: link.title, loading: 'lazy' }),
+                              )
+                            : null,
                           h(
                             'span',
                             { className: 'gt-link-main' },

package/lib/index.js

@@ -37,7 +37,7 @@ import { createStore, resolveStorePath } from './store.js'
 import { createTools, normalizeToolGroups, selectTools } from './tools.js'
 
 /** Must equal `package.json`'s version; `npm run check` enforces that. */
-export const VERSION = '0.14.0'
+export const VERSION = '0.15.0'
 
 /** Plugin id. Also the Loader row id in `cordis.patch.yml`. */
 export const name = 'dsh-global-todo'

package/lib/links.js

@@ -17,8 +17,28 @@
 
 import { TodoError } from './errors.js'
 
-/** Accepted attachment kinds. */
-export const LINK_KINDS = Object.freeze(['url', 'file'])
+/**
+ * Accepted attachment kinds.
+ *
+ * `image` is a reference like `file` — the bytes stay where they are — but it is
+ * declared rather than inferred, because the panel renders it and a guess would
+ * turn a random document into a broken thumbnail. The list still never copies
+ * bytes; `GET /asset` reads the referenced file on demand.
+ */
+export const LINK_KINDS = Object.freeze(['url', 'file', 'image'])
+
+/** Extensions the panel can actually render. SVG is excluded: served inline from the same
+ * origin it can carry script. */
+export const IMAGE_EXTENSIONS = Object.freeze(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.avif'])
+
+/**
+ * @param {string} value
+ * @returns {boolean} whether the path looks like a renderable image
+ */
+export function isImagePath(value) {
+  const lower = String(value ?? '').toLowerCase()
+  return IMAGE_EXTENSIONS.some((extension) => lower.endsWith(extension))
+}
 
 const MAX_URL = 2048
 const MAX_PATH = 4096
@@ -27,6 +47,8 @@ const MAX_TITLE = 200
 /**
  * Guess the kind of a bare string attachment.
  *
+ * `image` is never inferred: it is a rendering decision the caller states.
+ *
  * @param {string} value
  * @returns {'url' | 'file'}
  */
@@ -91,6 +113,9 @@ export function normalizeLink(input, options = {}) {
   if (!isAbsolutePath(value)) {
     throw new TodoError('invalid-link', `文档请给绝对路径（相对路径会在不同会话下指向不同文件）：${value}`)
   }
+  if (kind === 'image' && !isImagePath(value)) {
+    throw new TodoError('invalid-link', `图片附件需要图片扩展名（${IMAGE_EXTENSIONS.join(' / ')}）：${value}`)
+  }
   if (options.requireExistingFiles === true && typeof options.exists === 'function' && !options.exists(value)) {
     throw new TodoError('invalid-link', `找不到这个文件：${value}`)
   }
@@ -113,7 +138,7 @@ export function isAbsolutePath(value) {
  * @returns {string}
  */
 export function defaultLinkTitle(kind, value) {
-  if (kind === 'file') {
+  if (kind === 'file' || kind === 'image') {
     const parts = value.split(/[\\/]/).filter(Boolean)
     return parts.length === 0 ? value : parts[parts.length - 1]
   }

package/lib/routes.js

@@ -21,7 +21,7 @@
  */
 
 import { createHash, timingSafeEqual } from 'node:crypto'
-import { readdir, stat } from 'node:fs/promises'
+import { readFile, readdir, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import path from 'node:path'
 
@@ -81,6 +81,21 @@ export function isLoopbackRequest(request) {
  * @param {number} status
  * @param {unknown} body
  */
+/** Cap for an inline image; a screenshot is a few hundred KB, a 4K render is not. */
+const MAX_ASSET_BYTES = 8 * 1024 * 1024
+
+/**
+ * @param {string} file
+ * @returns {string} the content type for a served image extension
+ */
+function mimeForImage(file) {
+  const lower = String(file).toLowerCase()
+  if (lower.endsWith('.png')) return 'image/png'
+  if (lower.endsWith('.webp')) return 'image/webp'
+  if (lower.endsWith('.gif')) return 'image/gif'
+  if (lower.endsWith('.avif')) return 'image/avif'
+  return 'image/jpeg'
+}
 function sendJson(response, status, body) {
   const payload = JSON.stringify(body)
   response.statusCode = status
@@ -403,6 +418,38 @@ export function createRoutes(deps) {
      * Derived, never stored: completion records already hold the facts, and a cached
      * aggregate would be a second truth to keep honest.
      */
+
+    /**
+     * Serve the bytes of an image attachment.
+     *
+     * The path comes from the store, never from the request: the caller names a todo and
+     * a link index, so there is no traversal surface here. The list still stores only a
+     * reference; this route reads the file when the panel needs a thumbnail.
+     */
+    exact('GET', `${ROUTE_BASE}/asset`, async (request, response) => {
+      const query = params(request)
+      const id = (query.get('id') ?? '').trim()
+      const index = Number.parseInt(query.get('index') ?? '', 10)
+      if (id === '' || !Number.isInteger(index) || index < 0) {
+        throw new TodoError('invalid-body', 'asset 需要 id 与 index')
+      }
+      const todo = await service.get(id)
+      const link = (todo.links ?? [])[index]
+      if (link === undefined) throw new TodoError('not-found', '这条待办没有这个附件')
+      if (link.kind !== 'image') throw new TodoError('invalid-link', '只有图片附件可以这样读取')
+      const info = await stat(link.value).catch(() => null)
+      if (info === null || info.isFile() !== true) throw new TodoError('not-found', '图片不在了')
+      if (info.size > MAX_ASSET_BYTES) {
+        throw new TodoError('payload-too-large', `图片超过 ${Math.round(MAX_ASSET_BYTES / 1024 / 1024)}MB`)
+      }
+      const bytes = await readFile(link.value)
+      response.statusCode = 200
+      response.setHeader('content-type', mimeForImage(link.value))
+      response.setHeader('cache-control', 'no-store')
+      response.setHeader('x-content-type-options', 'nosniff')
+      response.end(bytes)
+    }),
+
     exact('GET', `${ROUTE_BASE}/report`, async (request) => {
       const days = Number.parseInt(params(request).get('days') ?? '', 10)
       const todos = await service.listAll()

package/lib/tools.js

@@ -52,14 +52,14 @@ const STEPS_SHAPE = {
 const LINKS_INPUT = {
   type: 'array',
   description:
-    '相关文档与地址。字符串写法按内容自动判别：http(s):// 开头算地址，其余必须是以 / 或盘符开头的绝对路径（文档原地引用，不复制内容）。也可给对象 { kind: "url"|"file", value, title }。',
+    '相关文档与地址。字符串写法按内容自动判别：http(s):// 开头算地址，其余必须是以 / 或盘符开头的绝对路径（文档原地引用，不复制内容）。也可给对象 { kind: "url"|"file"|"image", value, title }；kind:"image" 用于截图，必须是图片路径（png/jpg/jpeg/webp/gif/avif），面板会显示缩略图。',
   items: {
     oneOf: [
       { type: 'string' },
       {
         type: 'object',
         properties: {
-          kind: { type: 'string', enum: ['url', 'file'] },
+          kind: { type: 'string', enum: ['url', 'file', 'image'] },
           value: { type: 'string' },
           title: { type: 'string' },
         },
@@ -136,7 +136,7 @@ const TODO_SHAPE = {  type: 'object',
       items: {
         type: 'object',
         properties: {
-          kind: { type: 'string', enum: ['url', 'file'] },
+          kind: { type: 'string', enum: ['url', 'file', 'image'] },
           value: { type: 'string' },
           title: { type: 'string' },
         },
@@ -815,7 +815,7 @@ export function createTools(service, options = {}) {
             items: {
               type: 'object',
               properties: {
-                kind: { type: 'string', enum: ['url', 'file'] },
+                kind: { type: 'string', enum: ['url', 'file', 'image'] },
                 value: { type: 'string' },
                 title: { type: 'string' },
               },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-global-todo",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "icon": "./docs/icon.svg",
   "description": "Cross-session todo list for DeepSeek Harness: one JSON file a person and an agent both write to, with step plans that ship as a numbered hand-off, session read-back, and a human confirmation before an agent's \"done\" counts.",
   "type": "module",