@cxx42/dsh-tool-notes 1.0.0 → 1.0.1

package/README.md

@@ -1,171 +1,28 @@
-# dsh-tool-notes
+# @cxx42/dsh-tool-notes
 
-一个给 DeepSeek Harness 用的**最小可运行工具插件**：给模型新增三个「个人笔记库」工具。
+A small DeepSeek Harness **tool** plugin that gives the model a personal note vault.
 
-| 工具 | 作用 |
+| Tool | Purpose |
 |---|---|
-| `note_add` | 把一条笔记追加到本地 JSONL 库（`~/.dsh/notes/notes.jsonl`） |
-| `note_search` | 在标题 / 正文 / 标签里做大小写不敏感的子串搜索，按新到旧返回 |
-| `note_list` | 列出最近的笔记，可按标签过滤 |
+| `note_add` | Append a note to a local JSONL vault (`~/.dsh/notes/notes.jsonl` by default) |
+| `note_search` | Case-insensitive substring search over title / body / tags, newest first |
+| `note_list` | List recent notes, optionally filtered by tag |
 
-这个包本身就是**一个 bundle**（`package.json` 里声明了 `dsh.bundle.patch`），
-`cordis.patch.yml` 插入一行自引用（`name: 'dsh-tool-notes'`）——和官方
-`@deepseek-ai/dsh-web-app` 的写法一致。
+These are **model tools**, not UI buttons: in a session the agent calls them when appropriate (e.g. "记一下…", "搜一下笔记里关于 …"). The calls show up in the conversation as tool-call cards, and notes persist across sessions.
 
-## 使用方法
-
-插件不给用户提供按钮/命令，它是模型的工具：**新会话**里的 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
-```
+## Install
 
 ```powershell
-# 方式 B（彻底重建）：删掉拷贝再让 pnpm 重建
-Remove-Item "C:\Users\cxx\.dsh\profiles\desktop\node_modules\dsh-tool-notes" -Recurse -Force
-dsh plugin --profile desktop install
+dsh plugin add @cxx42/dsh-tool-notes
 ```
 
-## 常见问题
-
-### 启动崩溃：`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
-```
+Then **restart** the desktop / web so the bundle is recomposed, and start a fresh session to use the tools.
 
-（回滚本身是安全的：三个文件会恢复成安装前的字节，验证哈希一致即可放心清理。）
+## Configuration
 
-## 扩展
+The bundle row sets `vaultDir` to `~/.dsh/notes` (via `dshHomePath('notes')`) and `maxSearchResults` to `10`. Override these in your profile patch if needed.
 
-想加第四个工具，照葫芦画瓢即可：在 `index.js` 里再写一个
-`ctx.tools.register(defineTool({...}))`，其余不用动（本 bundle 只有一行 patch）。
-注意改完按「方式 A/B」刷新拷贝。
+## Notes
 
+- Data is written to the configured `vaultDir` using plain `node:fs` — no shell, no path escape from that directory.
+- Requires `@deepseek-ai/dsh-tools`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cxx42/dsh-tool-notes",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Personal note vault tools for DeepSeek Harness: add, search, and list notes as JSONL",
   "type": "module",
   "main": "index.js",