dsh-worktodo 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# 更新日志
+
+## 0.1.0
+
+首个可用版本。
+
+### 核心
+
+- **人机共享的工作待办**：一份逻辑（`src/service.mjs`）同时供侧栏面板与 agent 工具调用，
+  所以「面板点完成」和「agent 调 `worktodo_done`」在数据上的行为完全一致。
+- **富字段**：优先级（高/普通/低）、截止日期、项目、备注——补上官方 `todo_write`
+  只有「内容 + 三态」的空缺。
+- **逐项编辑**：按 id、完整标题或唯一标题前缀定位单条修改，不像 `todo_write` 那样整表替换。
+- **跨会话持久**：数据不属于任何会话，重启、换会话、换项目都还在。
+- **分组视图**：逾期 / 今天 / 本周 / 以后 / 已完成，含统计（未完成 / 逾期 / 今天 / 进行中 / 今日完成）。
+
+### agent 工具
+
+- `worktodo_add` / `worktodo_list` / `worktodo_update` / `worktodo_done` / `worktodo_remove`
+- `worktodo_adopt`：把本会话 `todo_write` 的条目提升为工作待办（按标题去重），
+  桥接官方会话计划与人的长期列表。
+
+### 存储
+
+- 优先官方 `ctx.storageDomain`（`$DSH_HOME/storages`）：跨重启保留但不进会话事件日志。
+- 回退 JSON 文件（`$DSH_HOME/worktodo/todos.json`）：**原子写**（临时文件 + rename）、
+  写入串行化、坏文件不静默清空、单条坏记录跳过；文件是人能直接打开手改、能进 git 的形态。
+- 支持 `storePath` 配置固定位置；`~` 会展开。
+
+### 兼容与降级
+
+- 目标 **DSH 0.2.x**（0.2.0-rc.2 实测），Node ≥ 22.19.0，`dependencies` 为空。
+- 平台包全部声明为**可选 peer**：`tools` 或 `webServer` 缺失时，插件以「少一半能力」的形态继续工作；
+  `@deepseek-ai/dsh-tools` 解析不到时只失去工具能力，面板照常可用（日志写明原因）。
+
+### 修复（发布前真机回归发现）
+
+- **工具返回值必须是 lossless JSON**：`worktodo_add` 在不传截止日期时返回了
+  `due: undefined`，被 DSH 的返回值校验判为无效，**整次调用被拒**——而「加一条没有截止日期的
+  待办」正是最常见的用法（`worktodo_update` 清空截止日期后同理）。已改为可选字段缺席时**删键**
+  而不是留 `undefined`。真机重试后暴露的第二个现象见 `docs/verification.md`：
+  以 `link:` 安装的插件，源码改动需要**重启**才会换模块 generation。
+- 新增可观测性：`/worktodo/health` 现在报告运行中的实际 `version` 与
+  `tools: { status, registered, names, error }`——工具静默没注册这类问题不用再翻日志猜。
+
+### 测试（116 例，均不需要启动 DSH）
+
+- `tools/verify-records.mjs`（22）：日期归一化与相对日期、状态/优先级同义词、完成时间维护、
+  引用解析（id / 标题 / 前缀 / 歧义）、分组边界（本周日 vs 下周一）、统计口径、筛选、坏记录修复。
+- `tools/verify-store.mjs`（11）：官方 `defineDomain` 契约、领域名合法、记录 schema 与官方读取路径一致、
+  domain 后端增删改查、文件后端原子写与并发写、坏文件与坏记录容忍、`~` 展开。
+- `tools/verify-service.mjs`（18）：显式状态（`empty-title` / `not-found` / `ambiguous-ref` /
+  `empty-patch` / `store-unreadable` / `store-write-failed`）、完成与取消完成的 `completedAt` 语义、
+  统计不随筛选变化、提升去重、变更通知。
+- `tools/smoke-host.mjs`（26）：假 ctx 里跑通 `apply` → 7 条路由 → 服务 → 存储的完整增删改查，
+  方法围栏与 `connection` 准入，失败路径（空标题、坏 JSON、未知 filter），health 自检字段，
+  6 个工具经**官方 `defineTool`** 校验注册并真实执行，以及 5 条「工具返回值必须无损」的断言——
+  判定用的是 **DSH 自己的校验器** `snapshotJsonValue`（来自 `@deepseek-ai/dsh-util-values`，
+  就是 `@deepseek-ai/dsh-tools` 报 "value is not lossless JSON" 时用的那一个函数），
+  并有一条专门断言「旧写法 `due: undefined` 必须被它拒绝」，用来证明这条守卫确实有牙齿。
+- `tools/smoke-contract.mjs`（12）：**客户端 ↔ 宿主契约**。从 `src/client/index.js` 静态提取它实际请求的
+  路径与字段名，与宿主真实注册的路由、真正消费的字段比对——防「字段名打错 → 那个功能永远静默失效」
+  （例如截止日期永远存不上，而没有任何红灯）；再用客户端字面上的报文形状打真实路由，验证两处清空约定
+  （create 用 `due: null`，行内编辑用 `due: ''` / `project: ''`）以及 toggle / adopt / remove / list 的字段完整性。
+  已做变异验证：路径改成 `/statuss` 会红 3 条，字段 `due` 改成 `duedate` 会红 1 条。
+- `tools/smoke-client.mjs`（14）：客户端 bundle 的模块加载器格式（id 必须等于包名）、
+  bundle 只允许 require react（官方规范禁止依赖 Harness 客户端包）、侧栏与主面板注册到正确的 slot
+  且 id/key 同名、locale 字典 zh/en 键一一对应、**首屏渲染不抛异常**（白屏是最致命的失败模式）、
+  挂载后确实发起 `/worktodo/list` 请求、`useProjection` 缺失或返回空值时安全。
+- `tools/verify-submission.mjs`（13）：**收录 PR 的本地门禁**。上游（deepseek1024.com 的目录仓）
+  会对提交的 `catalog/plugins/*.json` 跑静态审查并**读仓库核对**，所以先在本地把这些规则跑一遍，
+  免得提一个必被拒的 PR：字段集合与 schema 一致、id 与文件名派生规则、`repository`/`name` 与
+  `package.json` 一致、`category` 在 11 个法定分类内、`added` 是合法日期、描述里没有最上级措辞。
+  另外两条只在 **GitHub 分发路径**下才致命、npm 发布看不出来的检查：`main` / `cordis.patch.yml` /
+  `lib/client.js` 等**必须都在 `git ls-files` 里**（git 安装只拿跟踪文件、且不跑构建），
+  以及 patch 里那一行的 `name` **必须等于包名**（否则新用户装上去 Loader 解析不到插件）。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oli20
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,101 @@
+# Work Todo · dsh-worktodo
+
+**A work todo list that belongs to you, not to a session.** A dedicated DSH sidebar panel, plus `worktodo_*` tools so the agent reads and writes **the same** list you do.
+
+> Works with **DSH 0.2.x** (tested on 0.2.0-rc.2) · **zero npm runtime dependencies** (`dependencies: {}`) · community plugin, unofficial
+
+## The gap it fills
+
+DSH ships `todo_write`: the plan of **one agent session**. It replaces the whole list every call, has only `pending / in_progress / completed`, and — quoting the official docs — "the list belongs to the one agent session that created it… there is no way to share a list across agents". No priority, no due date, no project, no per-item edit. Close the session and the plan is gone.
+
+So the things that actually need to survive — waiting on a reply, waiting on review, shipping next week — have nowhere to live.
+
+**This list is for the human.** Priorities, due dates, projects, notes. It persists across sessions and projects. The agent can read and write it, but the source of truth is yours.
+
+| | official `todo_write` | **dsh-worktodo** |
+|---|---|---|
+| Owned by | one agent session | **you** (cross-session, cross-project) |
+| Update | whole-list replacement | **per-item create / edit / delete** |
+| Fields | content + 3 states | content + **priority + due date + project + notes** |
+| Shared across agents | ❌ not supported | ✅ one list, human and agent both read/write |
+| Views | in-session checklist | **overdue / today / this week / later / done** + stats |
+| Storage | session event log | `$DSH_HOME/storages` (official storage) or `~/.dsh/worktodo/todos.json` |
+
+The two are complementary: `worktodo_adopt` promotes the entries worth keeping from this session's `todo_write` into your work list.
+
+## Install
+
+**Option 1: straight from GitHub** (no npm package needed; restart DSH afterwards)
+
+```bash
+dsh plugin --profile desktop add github:olimc2016/dsh-worktodo
+```
+
+This path is verified (see `docs/verification.md`): the browser half's build output `lib/client.js` is committed,
+and the package declares no `prepare`/`install` build script, so a git install needs **no build authorization**
+and pulls none of the development dependencies — measured: **1 package** resolved, **316 KB** installed,
+no nested `node_modules`, and the installed tree matches the npm tarball file for file.
+
+**Option 2: from npm** (once the package is published)
+
+```bash
+dsh plugin --profile desktop add dsh-worktodo
+```
+
+**Option 3**: use the DSH sidebar — **Plugins → Add plugin** — and enter `dsh-worktodo` or the repository URL.
+
+## Usage
+
+**Panel**: stats on top (open / overdue / today / in progress / completed today), a quick-add box (title + due date + priority, Enter to save), then the grouped list. Each row can be checked off, edited inline by clicking the title, or deleted (with a second-click confirmation).
+
+**Agent tools**: the model can file, query, advance and archive your work todos without you relaying anything.
+
+| Tool | Purpose |
+|---|---|
+| `worktodo_add` | File a task (optional due date, priority, project, notes) |
+| `worktodo_list` | List with `open` / `today` / `overdue` / `week` / `doing` / `completed` / `all`, filterable by project or keyword |
+| `worktodo_update` | Edit one item without touching the rest |
+| `worktodo_done` | Mark done, or back to in-progress / pending |
+| `worktodo_remove` | Delete (use `worktodo_done` to keep the record instead) |
+| `worktodo_adopt` | Promote this session's `todo_write` entries, de-duplicated by title |
+
+One sentence is enough:
+
+> "File the three things I need to follow up today into my work todos, and mark tomorrow morning's as high priority."
+
+## Where the data lives
+
+Chosen automatically; the actual location is reported by `/worktodo/health` and shown at the bottom of the panel:
+
+1. **Official storage** (`ctx.storageDomain`, mounted by DSH by default) — data lands in `$DSH_HOME/storages`. This is the documented place for plugin-owned state that must survive restarts without becoming session events; a few dozen todos do not belong in the session history.
+2. **JSON file fallback** — `$DSH_HOME/worktodo/todos.json`, used automatically in minimal compositions without the storage service. That file is meant to be opened, hand-edited and committed to git; a corrupted file is never silently wiped, and a single bad record is skipped rather than losing the list.
+
+Pin your own path in `cordis.patch.yml`:
+
+```yaml
+- id: worktodo
+  name: 'dsh-worktodo'
+  config:
+    storePath: /Users/me/notes/worktodo.json
+```
+
+## Compatibility
+
+- **DSH 0.2.x** (tested against 0.2.0-rc.2 APIs; DSH's version gate rejects plugins pinned to older lines)
+- **Node ≥ 22.19.0**
+- No runtime npm dependencies. Platform packages (`@deepseek-ai/dsh-tools`, `dsh-storage-domain`, `dsh-home-paths`) are **optional peers** resolved from the DSH installation; if one genuinely cannot be resolved the plugin degrades to panel-only instead of failing to load, and logs the reason.
+
+## Development
+
+```bash
+pnpm install            # esbuild ships a prebuilt binary; no approve-builds needed
+pnpm run build          # build lib/client.js (browser half)
+pnpm test               # 116 cases: data model / storage / service / host wiring and tools / client contract / client bundle / catalog gate
+pnpm run watch          # incremental client build
+```
+
+No DSH instance is needed to run the suite: `verify-records` (pure data), `verify-store` (real file IO plus a genuine **official `defineDomain` contract check**), `verify-service` (explicit statuses and boundaries), `smoke-host` (apply → routes → service → storage in a fake context, plus tool registration and execution with schemas validated by the **official `defineTool`**), `smoke-contract` (extracts the paths and field names the client actually sends and checks them against the host's real routes — catching silent failures where a mistyped field means, for instance, that due dates never save), `smoke-client` (bundle format, slot registration, and a first render that must not throw), and `verify-submission` (a local gate for the catalog PR: fields, filename, category and date, plus checks that only matter on the GitHub distribution path, such as whether every file a git install needs is actually tracked).
+
+## License
+
+MIT © 2026 oli20

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# 工作待办 · dsh-worktodo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**归你所有、跨会话持久的工作待办。** DSH 侧栏一个独立面板，agent 通过 `worktodo_*` 工具读写**同一份**列表。
+
+> 兼容 **DSH 0.2.x**（0.2.0-rc.2 实测）· **零 npm 依赖**（`dependencies: {}`）· 社区插件，非官方
+
+---
+
+## 它解决什么问题
+
+DSH 自带的 `todo_write` 是**当前这个 agent 会话**的计划：整表替换、只有 `pending / in_progress / completed` 三态、**只属于那一个会话**。官方文档写得很直白——「任务列表属于创建它的那一个 agent 会话……不存在跨 agent 共享列表的方式」，而且**没有优先级、没有截止日期、没有项目、没有逐项编辑**。会话一关，那份计划就翻篇了。
+
+于是真实工作里那些「明天还得接着办」的事没有地方放：等对方回复、等评审、下周要交的东西、这个月要跟的活。
+
+**这份列表是给人的**：有优先级、截止日期、项目和备注，跨会话、跨项目一直在；agent 能读能写，但真源在你手里。
+
+| | 官方 `todo_write` | **dsh-worktodo** |
+|---|---|---|
+| 归属 | 单个 agent 会话 | **你**（跨会话、跨项目） |
+| 更新方式 | 整表替换 | **逐项增删改** |
+| 字段 | 内容 + 三态 | 内容 + **优先级 + 截止日期 + 项目 + 备注** |
+| 跨 agent 共享 | ❌ 官方明确不支持 | ✅ 同一份列表，人与 agent 都读写 |
+| 视图 | 会话内清单 | **逾期 / 今天 / 本周 / 以后 / 已完成** 分组 + 统计 |
+| 数据位置 | 会话事件日志 | `$DSH_HOME/storages`（官方 storage）或 `~/.dsh/worktodo/todos.json` |
+
+两者不冲突：`worktodo_adopt` 可以把你这个会话的 `todo_write` 里值得留下的条目**一键提升**成工作待办。
+
+## 安装
+
+**方式一：直接从 GitHub 装**（不依赖 npm 上的包；装完重启 DSH）
+
+```bash
+dsh plugin --profile desktop add github:olimc2016/dsh-worktodo
+```
+
+这条路是实测过的（见 `docs/verification.md`）：仓库里提交了浏览器半侧的构建产物 `lib/client.js`，
+包内没有 `prepare`/`install` 这类构建脚本，所以 **git 安装不需要任何构建授权**，也不会把开发依赖装进来
+——实测只解析 **1 个包**、整个安装 **316 KB**、包内无嵌套 `node_modules`，且安装结果与 npm 发布包逐一相同。
+
+**方式二：从 npm 装**（包发布后可用）
+
+```bash
+dsh plugin --profile desktop add dsh-worktodo
+```
+
+**方式三**：在 DSH 侧栏「插件 → 添加插件」里填 `dsh-worktodo` 或仓库地址。
+
+装好后侧栏会多一个**「待办」**入口，设置 → 插件里也能看到它。
+
+## 用起来
+
+**面板**：顶部是统计（未完成 / 逾期 / 今天 / 进行中 / 今日完成），中间是快速添加框（标题 + 截止日期 + 优先级，回车即存），下面是分组列表。每行可以直接勾完成、点标题行内改、删除（二次确认）。
+
+**agent 工具**：模型可以自己登记、查询、推进和归档工作待办，不需要你转述。
+
+| 工具 | 用途 |
+|---|---|
+| `worktodo_add` | 登记一件事（可带截止日期、优先级、项目、备注） |
+| `worktodo_list` | 查列表：`open` / `today` / `overdue` / `week` / `doing` / `completed` / `all`，可按项目或关键词过滤 |
+| `worktodo_update` | 逐项修改（不会像整表替换那样动到别的条目） |
+| `worktodo_done` | 标完成，或标回进行中 / 待办 |
+| `worktodo_remove` | 删除（做完的事请用 `worktodo_done` 留痕） |
+| `worktodo_adopt` | 把本会话 `todo_write` 的条目提升为工作待办，按标题去重 |
+
+给 agent 的一句话就能用起来：
+
+> 「把今天要跟进的三件事记到工作待办里，明天上午的标高优先级。」
+
+## 数据存在哪
+
+按优先级自动选择，`/worktodo/health` 与面板底部都会显示当前实际位置：
+
+1. **官方 storage**（`ctx.storageDomain`，DSH 默认挂载）——数据落在 `$DSH_HOME/storages`。
+   这是官方给「插件自有、跨重启保留、不进会话事件」的数据指定位置：几十条待办不必变成会话历史。
+2. **JSON 文件回退**——`$DSH_HOME/worktodo/todos.json`。storage 服务缺失的精简组合里自动走这条路；
+   这个文件**是人能直接打开、手改、进 git** 的形态，写坏了也不会被静默清空（单条坏记录跳过，其余照常读出）。
+
+想在 `cordis.patch.yml` 里固定路径（例如放进自己的笔记仓库）：
+
+```yaml
+- id: worktodo
+  name: 'dsh-worktodo'
+  config:
+    storePath: /Users/me/notes/worktodo.json
+```
+
+## 兼容
+
+- **DSH 0.2.x**（官方版本闸门会把锁在旧版本的插件拒掉，本插件按 0.2.0-rc.2 的 API 编写并实测）
+- **Node ≥ 22.19.0**
+- `dependencies` 为空：不装任何运行期 npm 包。平台包（`@deepseek-ai/dsh-tools`、
+  `dsh-storage-domain`、`dsh-home-paths`）都声明为**可选 peer**——DSH 自带这些包，从安装目录解析；
+  真解析不到时插件会降级成「只有面板」而不是加载失败（日志里会写一行原因）。
+
+## 开发
+
+```bash
+pnpm install            # esbuild 用预编译二进制，无需 approve-builds
+pnpm run build          # 打 lib/client.js（浏览器半侧）
+pnpm test               # 116 个用例：数据模型 / 存储 / 服务 / 宿主接线与工具 / 客户端↔宿主契约 / 客户端 bundle / 收录门禁
+pnpm run watch          # 改客户端时增量构建
+```
+
+测试策略：不用启动 DSH 就能跑完——
+`verify-records`（纯数据）、`verify-store`（真实文件 IO + **官方 `defineDomain` 契约校验**）、
+`verify-service`（显式状态与边界）、`smoke-host`（假 ctx 里跑通 apply → 路由 → 服务 → 存储，
+以及工具注册与执行，工具 schema 由**官方 `defineTool`** 校验）、
+`smoke-contract`（从客户端源码提取它实际发的路径与字段，与宿主真实路由比对——防字段名打错导致的
+静默失效，例如截止日期永远存不上）、`smoke-client`（bundle 格式、slot 注册、首屏渲染不抛异常）、`verify-submission`
+（收录 PR 的本地门禁：字段/文件名/分类/日期 + 「git 安装必需的文件是否都已入库」这类只在 GitHub
+分发路径下才致命的检查）。
+
+## License
+
+MIT © 2026 oli20

package/cordis.patch.yml

@@ -0,0 +1,16 @@
+# worktodo bundle patch：把自己插进 DSH 的 profile 层栈。
+# 宿主半侧（Node）由 Loader 按 `name` 加载 lib/index.js；
+# 浏览器半侧由 package.json 的 dsh.client 声明并组合成 bundle。
+#
+# row id 必须唯一：这里用 `worktodo`（与包名短名一致，也用于面板 slot id 与 /worktodo 路由前缀）。
+# 官方 @deepseek-ai/dsh-tool-todo 占的是 `tool-todo`，不冲突——两者互补：
+# 官方那份是单个 agent 会话的计划（整表替换、三态），本插件是人的跨会话工作待办。
+- insert:
+    - id: worktodo
+      name: 'dsh-worktodo'
+      config:
+        # 留空即用默认值：优先官方 storage（$DSH_HOME/storages），
+        # storage 不可用时回退 $DSH_HOME/worktodo/todos.json。
+        # 想固定存到自己的路径（例如放进 git 仓库）就写 storePath：
+        # storePath: /Users/me/notes/worktodo.json
+        {}

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" width="48" height="48" role="img" aria-label="工作待办">
+  <!-- 底色用实心圆角块：任何主题（深/浅）下都能看清，不依赖宿主背景色 -->
+  <rect x="2" y="2" width="44" height="44" rx="12" fill="#2563EB"/>
+  <!-- 第一行：已勾选的事（勾 + 删除线感的短线） -->
+  <path d="M12.5 16.5l3.2 3.2 6.3-6.8" fill="none" stroke="#FFFFFF" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+  <rect x="26" y="14.5" width="10" height="3" rx="1.5" fill="#FFFFFF" opacity="0.75"/>
+  <!-- 第二行：进行中的事（空心圈） -->
+  <circle cx="14.2" cy="27.5" r="3.4" fill="none" stroke="#FFFFFF" stroke-width="2.4"/>
+  <rect x="26" y="26" width="10" height="3" rx="1.5" fill="#FFFFFF" opacity="0.75"/>
+  <!-- 第三行：还没开始的事（空心圈，更淡） -->
+  <circle cx="14.2" cy="37.5" r="3.4" fill="none" stroke="#FFFFFF" stroke-width="2.4" opacity="0.6"/>
+  <rect x="26" y="36" width="7" height="3" rx="1.5" fill="#FFFFFF" opacity="0.55"/>
+</svg>