@cxx42/dsh-tool-notes 1.0.0

package/README.md

@@ -0,0 +1,171 @@
+# dsh-tool-notes
+
+一个给 DeepSeek Harness 用的**最小可运行工具插件**：给模型新增三个「个人笔记库」工具。
+
+| 工具 | 作用 |
+|---|---|
+| `note_add` | 把一条笔记追加到本地 JSONL 库（`~/.dsh/notes/notes.jsonl`） |
+| `note_search` | 在标题 / 正文 / 标签里做大小写不敏感的子串搜索，按新到旧返回 |
+| `note_list` | 列出最近的笔记，可按标签过滤 |
+
+这个包本身就是**一个 bundle**（`package.json` 里声明了 `dsh.bundle.patch`），
+`cordis.patch.yml` 插入一行自引用（`name: 'dsh-tool-notes'`）——和官方
+`@deepseek-ai/dsh-web-app` 的写法一致。
+
+## 使用方法
+
+插件不给用户提供按钮/命令，它是模型的工具：**新会话**里的 agent 会在合适时机自动调用。
+你只需要用自然语言提需求，例如：
+
+| 你说 | 模型会调用 | 效果 |
+|---|---|---|
+| 「把 XXX 记到笔记里，标题《YYY》，标签 a、b」 | `note_add` | 追加一条笔记到 `~/.dsh/notes/notes.jsonl` |
+| 「搜一下笔记里关于 XX 的内容」 | `note_search` | 标题/正文/标签全文搜索，新到旧返回 |
+| 「列出最近的笔记，只要某标签的」 | `note_list` | 按标签过滤列出最近笔记 |
+
+效果可见处：① 对话流里的工具调用卡片（Add note / Search notes / List notes）；
+② 磁盘文件 `C:\Users\cxx\.dsh\notes\notes.jsonl`（每调用一次 `note_add` 追加一行 JSON）；③ 跨会话持久——任何会话都能搜到之前记的笔记。
+
+注意：工具列表在会话创建时绑定，**改过插件或装新工具后请新开会话**再测试。
+
+## 安装（装进你正在用的 profile）
+
+```powershell
+# 装进 desktop profile（当前 GUI 用的就是这个）
+dsh plugin --profile desktop add "file:C:\Users\cxx\Documents\DSHWorkspace\dsh_project1"
+
+# 装进 web profile 则换成
+dsh plugin --profile web add "file:C:\Users\cxx\Documents\DSHWorkspace\dsh_project1"
+```
+
+`dsh plugin` 是 pnpm 的薄封装：它会在 profile 目录里跑 `pnpm add`，
+然后把「声明了 `dsh.bundle` 的包」自动追加进 `dsh.profile.bundles` 层栈。
+装完**重启 GUI**（启动时会重新组合 bundle 层），工具就出现在模型工具列表里。
+
+## 卸载
+
+```powershell
+dsh plugin --profile desktop remove dsh-tool-notes
+```
+
+## 本地开发循环
+
+⚠️ Windows 上 `file:` 安装会在 `node_modules` 里生成**实体拷贝，重装不会自动刷新**
+（详见下方常见问题）。改完源码后，任选一种方式刷新 profile 里的拷贝：
+
+```powershell
+# 方式 A（最省事）：直接覆盖拷贝里的文件，然后重启 GUI
+Copy-Item "C:\Users\cxx\Documents\DSHWorkspace\dsh_project1\index.js" "C:\Users\cxx\.dsh\profiles\desktop\node_modules\dsh-tool-notes\index.js" -Force
+```
+
+```powershell
+# 方式 B（彻底重建）：
+Remove-Item "C:\Users\cxx\.dsh\profiles\desktop\node_modules\dsh-tool-notes" -Recurse -Force
+dsh plugin --profile desktop install
+```
+
+## 结构与原理
+
+```
+dsh_project1/
+├── package.json      # dsh.bundle.patch 指向 cordis.patch.yml；依赖 @deepseek-ai/dsh-tools
+├── cordis.patch.yml  # bundle 补丁：insert 一行 tool-notes，config 里 vaultDir 用 !!js dshHomePath('notes')
+├── index.js          # 模块插件：导出 name / inject / Config / apply
+└── README.md
+```
+
+- **插件契约**：Cordis 模块插件导出 `name`、`inject`（声明的服务就绪后才 apply）、
+  `Config`（schemastery schema，对应 patch 行的 `config:`）、`apply(ctx, config)`。
+  参考官方 `@deepseek-ai/dsh-tool-todo`。
+- **工具注册**：`ctx.tools.register(defineTool({...}))`，来自
+  `@deepseek-ai/dsh-tools`；`parameters` 用 JSON Schema 风格描述，
+  `output.schema` + `output.render` 决定 Web GUI 里的展示。
+- **配置注入**：`config.vaultDir` 来自 patch 行的 `vaultDir: !!js dshHomePath('notes')`，
+  与官方 `session-persistence-jsonl` 行的用法相同。
+
+## 注意
+
+- 本插件的工具直接使用 `node:fs` 读写 `vaultDir`（默认 `~/.dsh/notes`），
+  不走 DSH 的沙箱文件服务——这是有意为之的简单实现。它只触碰配置的目录，
+  不执行 shell，也没有路径逃逸；如果你要接通用文件访问，建议改走
+  `dsh-fs-sandbox` 服务。
+- 依赖 `@deepseek-ai/dsh-tools@^0.1.1-rc.2`：首次 `dsh plugin add` 时
+  pnpm 会从 npm registry 拉取（官方包已公开发布）。
+
+## 常见问题
+
+### 启动崩溃：`parameters.xxx.required must be true when present`
+
+`defineTool` 的参数/输出规范 DSL 里，**可选参数直接省略 `required` 字段**，
+写 `required: false` 会被 `dsh-tools` 的 schema 编译器拒绝（作者错误），
+整个插件树加载失败、harness 起不来。
+
+规则（见 `dsh-tools` 的 `runSchemaCompiler`：`required` 要么缺省、要么 `true`）：
+
+```js
+parameters: {
+  title:   { type: 'string', required: true },  // ✅ 必填
+  tags:    { type: 'array', items: { type: 'string' } },  // ✅ 可选：不写 required
+  // ❌ 错误：required: false
+}
+```
+
+### ⚠️ 关键的坑：`file:` 安装的拷贝不会自动刷新（Windows）
+
+pnpm 把这个 `file:` 依赖按 `type: directory`（链接目录协议）处理，但在 Windows 上
+`node_modules/dsh-tool-notes` 是安装时**实体拷贝出来的目录**——之后即使源目录改了、
+甚至 `add --force` 重装，**拷贝内容也不会同步**（lockfile 只记目录路径，不校验内容）。
+表现：改了插件源码、重装、重启，加载到的还是旧代码。
+
+改完源码后的两种可靠刷新方式（任选其一）：
+
+```powershell
+# 方式 A（最省事）：直接覆盖拷贝里的文件
+Copy-Item "C:\Users\cxx\Documents\DSHWorkspace\dsh_project1\index.js" "C:\Users\cxx\.dsh\profiles\desktop\node_modules\dsh-tool-notes\index.js" -Force
+```
+
+```powershell
+# 方式 B（彻底重建）：删掉拷贝再让 pnpm 重建
+Remove-Item "C:\Users\cxx\.dsh\profiles\desktop\node_modules\dsh-tool-notes" -Recurse -Force
+dsh plugin --profile desktop install
+```
+
+## 常见问题
+
+### 启动崩溃：`parameters.xxx.required must be true when present`
+
+`defineTool` 的参数/输出规范 DSL 里，**可选参数直接省略 `required` 字段**，
+写 `required: false` 会被 `dsh-tools` 的 schema 编译器拒绝（作者错误），
+整个插件树加载失败、harness 起不来。
+
+规则（见 `dsh-tools` 的 `runSchemaCompiler`：`required` 要么缺省、要么 `true`）：
+
+```js
+parameters: {
+  title:   { type: 'string', required: true },  // ✅ 必填
+  tags:    { type: 'array', items: { type: 'string' } },  // ✅ 可选：不写 required
+  // ❌ 错误：required: false
+}
+```
+
+修复后按上面的「方式 A/B」刷新 profile 里的拷贝，再重启。
+
+### 重装报错：`another plugin install recovery transaction is pending`
+
+桌面版 `dsh` 给插件安装加了崩溃恢复 WAL（备份 profile 的 package.json /
+pnpm-lock.yaml / pnpm-workspace.yaml）。装完启动失败会自动回滚，但**手动安装的回滚
+事务不会自动清除**，而事务文件存在时任何新安装都会被拒绝。清掉即可：
+
+```powershell
+Remove-Item "C:\Users\cxx\AppData\Roaming\DSH Desktop\plugin-install-recovery\state.json" -ErrorAction SilentlyContinue
+Remove-Item "C:\Users\cxx\AppData\Roaming\DSH Desktop\plugin-install-recovery\backups" -Recurse -Force -ErrorAction SilentlyContinue
+```
+
+（回滚本身是安全的：三个文件会恢复成安装前的字节，验证哈希一致即可放心清理。）
+
+## 扩展
+
+想加第四个工具，照葫芦画瓢即可：在 `index.js` 里再写一个
+`ctx.tools.register(defineTool({...}))`，其余不用动（本 bundle 只有一行 patch）。
+注意改完按「方式 A/B」刷新拷贝。
+

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# @cxx42/dsh-tool-notes bundle patch.
+#
+# Self-activating host row: registers the notes tools on `ctx.tools`. Applied
+# after dsh-base's rows so the `tools` registry already exists.
+
+- insert:
+    - id: tool-notes
+      name: '@cxx42/dsh-tool-notes'
+      config:
+        vaultDir: !!js dshHomePath('notes')
+        maxSearchResults: 10

package/index.js

@@ -0,0 +1,279 @@
+// dsh-tool-notes — a minimal but complete DSH tool plugin.
+//
+// Follows the official module-plugin contract (same shape as
+// @deepseek-ai/dsh-tool-todo): export `name`, `inject`, `Config`, and `apply`.
+// The bundle's cordis.patch.yml inserts a row naming this package, so Cordis
+// loads THIS module as the plugin and registers the tools below on `ctx.tools`.
+//
+// The vault is a plain JSONL file (one JSON note per line) under a directory
+// configured at load time (default: $DSH_HOME/notes). The tools read/write
+// ONLY that directory — no shell access, no path escape.
+
+import { mkdir, appendFile, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+
+/** Cordis plugin identity (label only). */
+export const name = '@cxx42/dsh-tool-notes';
+
+/** Services that must exist before apply() runs. */
+export const inject = ['tools'];
+
+/** Schemastery configuration schema — matches the `config:` block in cordis.patch.yml. */
+export const Config = z.object({
+  vaultDir: z.string().required(),
+  maxSearchResults: z.number().default(10),
+});
+
+// ── vault helpers ────────────────────────────────────────────────────────────
+
+/** @param {string} vaultDir */
+function vaultFile(vaultDir) {
+  return join(vaultDir, 'notes.jsonl');
+}
+
+/** Append one note object to the vault, creating the directory/file on demand. */
+async function appendNote(vaultDir, note) {
+  await mkdir(vaultDir, { recursive: true });
+  await appendFile(vaultFile(vaultDir), `${JSON.stringify(note)}\n`, 'utf8');
+  return note;
+}
+
+/** Read all notes, newest first. Corrupt lines are skipped, never fatal. */
+async function readNotes(vaultDir) {
+  let raw;
+  try {
+    raw = await readFile(vaultFile(vaultDir), 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return [];
+    throw err;
+  }
+  const notes = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      notes.push(JSON.parse(trimmed));
+    } catch {
+      // skip a corrupt line rather than failing the whole read
+    }
+  }
+  return notes.reverse();
+}
+
+/** Escape regex metacharacters so a plain query is matched literally. */
+function escapeRegex(input) {
+  return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** `$DSH_HOME/notes/notes.jsonl`, plus a human-friendly display form. */
+function describeVault(vaultDir) {
+  return vaultFile(vaultDir);
+}
+
+// ── tools ────────────────────────────────────────────────────────────────────
+
+function apply(ctx, config) {
+  const { vaultDir, maxSearchResults } = config;
+  const file = describeVault(vaultDir);
+
+  ctx.tools.register(defineTool({
+    name: 'note_add',
+    description:
+      'Append a note to your personal vault (a JSONL file on disk). ' +
+      'Use this to persist facts, preferences, decisions, and reference material ' +
+      'the user may want later — across sessions and conversations. ' +
+      `Vault file: ${file}. Keep titles short and contents self-contained; ` +
+      'tags group related notes for later search.',
+    parameters: {
+      title: {
+        type: 'string',
+        required: true,
+        description: 'Short title, <= 100 characters.',
+      },
+      content: {
+        type: 'string',
+        required: true,
+        description: 'The note body — markdown allowed, keep it accurate and useful.',
+      },
+      tags: {
+        type: 'array',
+        
+        description: 'Optional lowercase tags for grouping, e.g. ["project-x", "idea"].',
+        items: { type: 'string' },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          id: { type: 'string', required: true },
+          title: { type: 'string', required: true },
+          tags: { type: 'array', required: true, items: { type: 'string' } },
+          vault: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `Saved note "${value.title}" (id ${value.id}) to ${value.vault}`,
+      }],
+    },
+    async execute(args) {
+      const note = {
+        id: randomUUID(),
+        ts: Date.now(),
+        title: String(args.title).slice(0, 100),
+        content: String(args.content),
+        tags: Array.isArray(args.tags) ? args.tags.map(String) : [],
+      };
+      await appendNote(vaultDir, note);
+      return {
+        id: note.id,
+        title: note.title,
+        tags: note.tags,
+        vault: file,
+      };
+    },
+    presentCall: (args) => ({
+      card: 'generic',
+      title: 'Add note',
+      kind: 'other',
+      rawInput: args,
+    }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'note_search',
+    description:
+      'Full-text search over your personal note vault. Matches the query ' +
+      'against title, body, and tags (case-insensitive substring). Returns the ' +
+      'newest matches first. Use it to recall previously saved notes.',
+    parameters: {
+      query: {
+        type: 'string',
+        required: true,
+        description: 'Search text — plain words work best.',
+      },
+      limit: {
+        type: 'integer',
+        
+        description: `Max results (default ${maxSearchResults}).`,
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          matches: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                title: { type: 'string', required: true },
+                content: { type: 'string', required: true },
+                tags: { type: 'array', required: true, items: { type: 'string' } },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => value.matches.length
+        ? value.matches.map((m) => ({
+            type: 'text',
+            text: `• ${m.title}${m.tags.length ? ` [${m.tags.join(', ')}]` : ''}\n  ${m.content}`,
+          }))
+        : [{ type: 'text', text: 'No notes matched.' }],
+    },
+    async execute(args) {
+      const limit = Math.max(1, Math.min(Number(args.limit) || maxSearchResults, 50));
+      const needle = new RegExp(escapeRegex(String(args.query)), 'i');
+      const notes = await readNotes(vaultDir);
+      const matches = notes
+        .filter((n) => needle.test(n.title) || needle.test(n.content) || needle.test((n.tags ?? []).join(' ')))
+        .slice(0, limit)
+        .map((n) => ({
+          id: n.id,
+          title: n.title,
+          content: n.content,
+          tags: n.tags ?? [],
+        }));
+      return { matches };
+    },
+    presentCall: (args) => ({
+      card: 'generic',
+      title: 'Search notes',
+      kind: 'other',
+      rawInput: args,
+    }),
+  }));
+
+  ctx.tools.register(defineTool({
+    name: 'note_list',
+    description:
+      'List recent notes from your personal vault (newest first), optionally ' +
+      'filtered by tag. Lightweight overview before deciding what to read or search.',
+    parameters: {
+      limit: {
+        type: 'integer',
+        
+        description: `Max notes (default ${maxSearchResults}).`,
+      },
+      tag: {
+        type: 'string',
+        
+        description: 'Only notes carrying this exact tag.',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          notes: {
+            type: 'array',
+            required: true,
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                id: { type: 'string', required: true },
+                title: { type: 'string', required: true },
+                tags: { type: 'array', required: true, items: { type: 'string' } },
+              },
+            },
+          },
+        },
+      },
+      render: (_args, value) => value.notes.length
+        ? value.notes.map((n) => ({
+            type: 'text',
+            text: `• ${n.title}${n.tags.length ? ` [${n.tags.join(', ')}]` : ''}`,
+          }))
+        : [{ type: 'text', text: 'The vault is empty.' }],
+    },
+    async execute(args) {
+      const limit = Math.max(1, Math.min(Number(args.limit) || maxSearchResults, 50));
+      const tag = args.tag === undefined ? null : String(args.tag);
+      const notes = await readNotes(vaultDir);
+      const filtered = tag === null ? notes : notes.filter((n) => (n.tags ?? []).includes(tag));
+      return {
+        notes: filtered.slice(0, limit).map((n) => ({ id: n.id, title: n.title, tags: n.tags ?? [] })),
+      };
+    },
+    presentCall: (args) => ({
+      card: 'generic',
+      title: 'List notes',
+      kind: 'other',
+      rawInput: args,
+    }),
+  }));
+}
+
+export { apply };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@cxx42/dsh-tool-notes",
+  "version": "1.0.0",
+  "description": "Personal note vault tools for DeepSeek Harness: add, search, and list notes as JSONL",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "tool",
+    "notes"
+  ],
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}