dsh-file-bookmark
A DeepSeek Harness tool plugin generated by create-dsh-plugin.
由 create-dsh-plugin 生成的 DeepSeek Harness 工具插件。
用于将文件或者常用的文件夹添加到DeepSeek Harness中，方便快速访问。并提供了工程的快速创建功能。
Registers the dsh_file_bookmark tool via defineTool().
Quick start / 快速开始
pnpm install
pnpm run build # tsc → dist/index.js (pure ESM)
# From the PARENT directory, install into a profile and boot:
dsh plugin --profile my-profile add ./dsh-file-bookmark
dsh --profile my-profile # watch for: [dsh-file-bookmark] registered "dsh_file_bookmark" — listed=true
注意：dsh plugin add <dir> 的相对路径锚定「调用目录」，请在插件父目录执行。
Verify without an API key / 无 key 验证
dsh --profile my-profile --dump-config | grep dsh-file-bookmark # 配置层含本行
dsh plugin --profile headless add ./dsh-file-bookmark
dsh --profile headless "run a probe" # session/event 触发；模型调用会 MISSING_CREDENTIAL
Dependencies pinned / 依赖锁定
@deepseek-ai/dsh-tools: 0.1.5-rc.2 (exact — the next-tag line; npm latest is stale).@deepseek-ai/cordis: ^4.0.2 (peerDependency — host provides it; types-only in code).
Theme & Skin Compatibility / 主题与皮肤兼容
This plugin has no host-rendered UI of its own (tool results render through the official
chat surface), so it is compatible by construction. If you later add a panel, follow the
DSH Web styling contract: colors via --dsw-alias-* tokens only, and emit
data-dsh-plugin / data-dsh-part / data-dsh-surface semantic attributes
(dsh-web skin-center contracts).
本插件没有自有宿主 UI（工具结果走官方聊天面渲染），天然兼容。若以后加面板：
颜色只用 --dsw-alias-* 令牌，并输出 data-dsh-* 语义属性（见上方契约链接）。
Pitfalls / 坑（从真实 spike 提炼，防呆）
-
Node version: DSH requires Node ^22.19.0 || >=24.0.0. Older Node (e.g. v22.17) only warns EBADENGINE but may hit runtime issues — upgrade if you can.
- Node 版本：DSH 要求 ^22.19.0 || >=24.0.0。旧版本（如 v22.17）只告警 EBADENGINE，不阻断，但建议升级。
-
npm dist-tag trap (the big one): @deepseek-ai/dsh-tools latest is a STALE 0.0.1-rc.1; the real line is under the next tag (0.1.0-rc.x). This scaffold pins the next-tag version for you — never npm i @deepseek-ai/dsh-tools over it.
- npm dist-tag 坑（最大）：
@deepseek-ai/dsh-tools 的 latest 是过期的 0.0.1-rc.1，正确版本在 next tag。本脚手架已锁 next 版本，勿再手动 npm i 覆盖。
-
Version-line alignment: keep every @deepseek-ai/dsh-* package on the same 0.1.0-rc.x line so pnpm does not install two module copies.
- 版本线对齐：所有 @deepseek-ai/dsh-* 包统一用同一 0.1.0-rc.x 线，避免 pnpm 装两份模块。
-
@deepseek-ai/cordis is a peerDependency: import only type { Context } (erased at compile). At runtime the host hands you ctx — never import cordis values at runtime.
- @deepseek-ai/cordis 是 peerDep：只 import type（编译期擦除），运行时 ctx 由宿主传入。
-
Pure ESM: package.json must set "type": "module"; build with module: esnext + moduleResolution: bundler to keep bare specifiers.
- 纯 ESM：package.json 必须 "type": "module"；tsc 用 module:esnext + moduleResolution:bundler 保留 bare specifier。
-
dsh plugin add <dir> anchors relative paths to the INVOKING directory — run it from the parent directory, not from inside the plugin.
- dsh plugin add 的相对路径锚定调用目录——要在插件的父目录执行。
-
In the bundle cordis.patch.yml, name is a package name (resolved via node_modules / $DSH_HOME/profiles/node_modules), not a relative path.
- bundle 的 cordis.patch.yml 里 name 用包名（走 node_modules 解析），不要用相对路径。
-
Registrations are effects: ctx.tools.register() / ctx.on() auto-dispose on unload. Wrap your OWN resources (timers/connections) in ctx.effect(() => { acquire; return cleanup }).
- 注册是 effect：ctx.tools.register()/ctx.on() 卸载自动清理；自己的资源（timer/连接）要包 ctx.effect(() => {…; return cleanup})。
-
Load order = service dependencies, never file order: export const inject = ['tools'] makes the plugin wait until ctx.tools is ready.
- 加载顺序靠服务依赖（inject），不靠文件顺序。
-
Full end-to-end (model actually calls your tool) needs DEEPSEEK_API_KEY; without it --verify proves load/list/event, and the model call fails with MISSING_CREDENTIAL.
- 端到端（模型真正调工具）需 DEEPSEEK_API_KEY；无 key 时 --verify 只能证明加载/列出/事件，模型调用会 MISSING_CREDENTIAL。
