dsh-worktodo 0.1.0 → 0.2.0

package/lib/index.js

@@ -16,6 +16,7 @@
  * 浏览器半侧（侧栏入口 + 面板）在 lib/client.js，按 package.json 的 dsh.client 组成 bundle。
  */
 import { readFileSync } from 'node:fs';
+
 import { createWorkTodoService } from '../src/service.mjs';
 import { openWorkTodoStore } from '../src/store.mjs';
 
@@ -113,6 +114,46 @@ function readJsonBody(request) {
  * @param {object} ctx cordis 上下文
  * @param {object} [config] 组合配置（cordis.patch.yml 的 config）
  */
+/**
+ * 给模型的用法指引（AI 推荐接口）。
+ *
+ * 为什么要有它：工具描述只讲「这个工具做什么」，而模型真正需要的是「什么时候该用哪个」——
+ * 尤其是本插件与官方 todo_write 的分工（会话内的步骤拆解 vs 人拥有的跨会话工作）。
+ * 通过 Host 的 systemPrompt.section() 贡献一段提示，是官方 practices 文档给的推荐做法。
+ * order 取 3050：官方 SECTION_ORDERS 里内置工具段是 1000–3000、MCP_SERVERS 是 3100，
+ * 插在两者之间读起来就是「插件工具的使用说明」。
+ */
+/**
+ * 版本与更新提示。
+ *
+ * 只查 npm registry 的 dist-tags.latest（不下载、不安装），结果缓存 6 小时，失败静默——
+ * 面板角落显示「当前版本」与「有新版本 vX.Y.Z」，绝不让网络问题影响面板。
+ * 测试里设 WORKTODO_NO_UPDATE_CHECK=1 可完全关掉（单元测试不该打网络）。
+ */
+const UPDATE_CHECK_OFF = process.env.WORKTODO_NO_UPDATE_CHECK === '1';
+const UPDATE_TTL_MS = 6 * 3600 * 1000;
+const PACKAGE_NAME = 'dsh-worktodo';
+
+/** 语义化版本比较：a > b 返回正数。 */
+function compareVersion(a, b) {
+  const pa = String(a).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).replace(/^v/, '').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i += 1) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+  }
+  return 0;
+}
+
+const GUIDANCE_TEXT = [
+  '工作待办（worktodo_*）：属于用户、跨会话持久的工作清单；侧栏面板与这些工具读写同一份数据。',
+  '- 该用：用户说出要办的事、承诺或截止日期（「下周要交」「等对方回复」「记一下」），或你在工作中发现超出本会话、仍需人跟进的待办 → worktodo_add。',
+  '- 不该用：当前这次任务的步骤拆解与你自己的执行顺序 → 那是会话内的 todo_write（整表替换、只属于本会话）。两者互补：todo_write 说「这一步怎么走」，工作待办说「这件事还欠着」。',
+  '- 动手前先看：worktodo_list({ filter: "today" }) 或 "overdue"；按项目看：worktodo_list({ project: "<项目>" })。用户问「今天要做什么」时先查再答，不要凭记忆。',
+  '- 加之前先查重：worktodo_list({ query: "<关键词>" })，同一条不要登记两次。',
+  '- 做完了 / 状态变了：worktodo_done（ref 可给 id 或标题）；改标题、截止、优先级、项目用 worktodo_update。',
+  '- 约定：标题写成一句简短的祈使句；project 用仓库名或产品名；priority 只在「真的卡住别人」时给 high；链接、背景与验收标准放 notes。',
+].join('\n');
+
 export async function apply(ctx, config = {}) {
   const logger = typeof ctx.logger === 'function' ? ctx.logger(name) : ctx.logger;
 
@@ -159,6 +200,58 @@ export async function apply(ctx, config = {}) {
     }, 'worktodo: agent tools');
   });
 
+  // ---- 版本与更新（后台、不阻塞任何请求）----
+  let updateState = { at: 0, latest: null, error: null };
+  const refreshUpdate = async () => {
+    if (UPDATE_CHECK_OFF) return updateState;
+    const now = Date.now();
+    if (updateState.at && now - updateState.at < UPDATE_TTL_MS) return updateState;
+    updateState = { ...updateState, at: now }; // 先占位，避免并发重复请求
+    try {
+      const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}`, {
+        headers: { accept: 'application/json' },
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const body = await res.json();
+      const latest = String(body?.['dist-tags']?.latest ?? '');
+      updateState = { at: now, latest: /^\d+\.\d+\.\d+$/.test(latest) ? latest : null, error: null };
+    } catch (error) {
+      updateState = { at: now, latest: null, error: String(error?.message ?? error) };
+    }
+    return updateState;
+  };
+  const updatePayload = () => {
+    const latest = updateState.latest;
+    return {
+      current: PLUGIN_VERSION,
+      latest: latest ?? undefined,
+      hasUpdate: Boolean(latest) && !UPDATE_CHECK_OFF && compareVersion(latest, PLUGIN_VERSION) > 0,
+      page: `https://www.npmjs.com/package/${PACKAGE_NAME}`,
+    };
+  };
+  if (!UPDATE_CHECK_OFF) void refreshUpdate(); // 启动时后台查一次（失败静默）
+
+  // ---- 给模型的用法指引（可选服务；缺 systemPrompt 时静默跳过）----
+  ctx.inject(['systemPrompt'], (spCtx) => {
+    spCtx.effect(() => {
+      if (typeof spCtx.systemPrompt?.section !== 'function') return () => {};
+      let disposeSection = () => {};
+      try {
+        disposeSection = spCtx.systemPrompt.section({
+          name: 'worktodo:guidance',
+          order: 3050,
+          text: GUIDANCE_TEXT,
+        }) ?? (() => {});
+        logger?.info?.('已注册给模型的用法指引（systemPrompt.section）');
+      } catch (error) {
+        // 段落注册失败不影响工具与面板；只记一行，方便排查
+        logger?.warn?.(`用法指引注册失败：${error?.message ?? error}`);
+      }
+      return () => { try { disposeSection?.(); } catch { /* 卸载清理失败不打断 */ } };
+    }, 'worktodo: system prompt guidance');
+  });
+
   // ---- HTTP 路由（可选服务）----
   ctx.inject(['webServer'], (webCtx) => {
     /**
@@ -211,12 +304,25 @@ export async function apply(ctx, config = {}) {
         path: `${ROUTE_BASE}/list`,
         handler: method('GET', async (request, response) => {
           const url = new URL(request.url ?? ROUTE_BASE, 'http://localhost');
+          if (!UPDATE_CHECK_OFF && Date.now() - updateState.at >= UPDATE_TTL_MS) void refreshUpdate();
           const result = await service.list({
             filter: url.searchParams.get('filter') ?? 'open',
             project: url.searchParams.get('project') ?? undefined,
             query: url.searchParams.get('query') ?? undefined,
+            sort: url.searchParams.get('sort') ?? undefined,
           });
-          reply(response, result);
+          reply(response, result.ok
+            ? { ...result, version: PLUGIN_VERSION, update: updatePayload() }
+            : result);
+        }),
+      }),
+      // 写：手动排序（拖动）。body: { ids: [待办 id，按新顺序排列] }
+      webCtx.webServer.register({
+        kind: 'exact',
+        path: `${ROUTE_BASE}/reorder`,
+        handler: method('POST', async (request, response) => {
+          const body = await readJsonBody(request);
+          reply(response, await service.reorder(body));
         }),
       }),
       // 写：新增

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-worktodo",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DSH 工作待办面板（社区插件，非官方）：归你所有、跨会话持久的工作待办——优先级 / 截止日期 / 项目 / 逾期与本周视图，agent 通过 worktodo_* 工具读写同一份列表。官方 todo_write 属于单个会话且只能整表替换，这份列表属于人。Human-owned cross-session work todo list for DeepSeek Harness: priorities, due dates, projects, overdue/week views and worktodo_* tools the agent shares with you.",
   "type": "module",
   "main": "lib/index.js",
@@ -75,31 +75,22 @@
       ]
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "@deepseek-ai/dsh-home-paths": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2"
+  },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-home-paths": ">=0.1.0-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-storage-domain": ">=0.1.0-rc.1 <0.3.0-0",
-    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.3.0-0"
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {
       "optional": true
-    },
-    "@deepseek-ai/dsh-tools": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-storage-domain": {
-      "optional": true
-    },
-    "@deepseek-ai/dsh-home-paths": {
-      "optional": true
     }
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
     "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-home-paths": "0.2.0-rc.2",
     "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
     "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
     "@deepseek-ai/dsh-ptc-runtime": "0.2.0-rc.2",
@@ -108,20 +99,19 @@
     "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
     "@deepseek-ai/dsh-session": "0.2.0-rc.2",
     "@deepseek-ai/dsh-storage": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "0.2.0-rc.2",
     "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
     "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
     "@deepseek-ai/dsh-util-values": "0.2.0-rc.2",
     "esbuild": "^0.28.2"
   },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "license": "MIT",
   "scripts": {
     "build": "node tools/build-client.mjs",
     "watch": "node tools/build-client.mjs --watch",
-    "test": "node tools/verify-all.mjs"
-  }
-}
+    "test": "node tools/verify-all.mjs",
+    "prepublishOnly": "node tools/build-client.mjs && node tools/verify-all.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT"
+}