boboozeng/dsh-annotation-plugin

dsh-annotation-plugin

将选中的助手文本引用到你的下一次请求中——一个用于 DeepSeek Harness 的独立插件。

该插件在一个 npm 包中同时提供该功能的两部分：

- 宿主部分（dsh.bundle + cordis.patch.yml）：一个 annotation 插件，将引用记录为仅日志的会话事件（annotation/added / annotation/removed），暴露一个 Typert Remote（record / list / discard），并在 agent/pre-step 阶段将待处理的引用物化到面向模型的消息批次中。
- 浏览器部分（dsh.client）：每条助手消息上的引用按钮，以及编辑器上方一个浮动的、可折叠的待处理引用卡片。

安装

需要一个组合了 @deepseek-ai/dsh-base 的 DeepSeek Harness 配置文件（官方基础层提供 session、agent、web 以及客户端运行时）。

从 npm 安装（推荐）

dsh plugin --profile  add dsh-annotation-plugin

发布的包附带预构建产物，因此安装时无需构建任何内容。

从 GitHub 安装

git 安装获取的是源代码，而非构建产物——该包的 prepare 脚本（tsdown）会在检出后构建 lib/，而 pnpm 在你明确允许之前会拒绝运行 git 依赖的 prepare。第一次 add 会失败，dsh 会打印出需要允许的确切包键：

dsh plugin --profile  add github:you/dsh-annotation-plugin
→ pnpm refuses to run the prepare script; copy the package key it prints
into the profile's pnpm-workspace.yaml, then re-run the add:

/pnpm-workspace.yaml
allowBuilds:
dsh-annotation-plugin: true

dsh plugin --profile  add github:you/dsh-annotation-plugin   # re-run

该许可是允许在安装时于你的机器上执行该包的代码，且处于 agent 所运行的任何沙箱之外。只允许你信任其源代码的包，并固定一个提交，这样后续的推送就无法悄悄改变运行的内容：

dsh plugin --profile  add github:you/dsh-annotation-plugin#

如果你不想要求用户授予该许可，请改为安装 npm 构建版本（或分发来自 pnpm pack 的 tarball——两者都不需要任何构建权限）。

bundle 层插入 annotation 插件行；client-modules 表会识别 dsh.client 声明，并在 Web GUI 中加载浏览器 bundle。

用法

1. 在助手消息中选择文本。
2. 点击消息操作栏中的引用按钮（✎）——所选内容会被记录，编辑器上方会出现一个浮动卡片：Quotes · N ▴。
3. 点击卡片展开引用文本列表；使用某一行上的 ✕ 取消该引用。
4. 发送你的消息——待处理的引用会被物化为面向模型的引用上下文，卡片随之消失。

要求

| 包 | 版本 |
|---|---|
| @deepseek-ai/dsh-base | ^0.1.0-rc.5 |
| react（宿主 web bundle） | ^18.2.0 |
对等依赖（@deepseek-ai/dsh-session、@deepseek-ai/dsh-client-ui-conversation、……）由该 profile 的依赖树满足。

开发

pnpm install
pnpm build        # tsdown: lib/index.mjs (node half) + lib/client.js (browser bundle)
pnpm test         # vitest (jsdom client specs)
pnpm typecheck

重新生成 Remote contribution

src/remote.ts 是 Typert 生成的描述符的已提交副本。在更改 src/index.ts 中任何 @Remote 方法签名后，重新生成它（例如从官方 checkout：pnpm run build:lib:host，然后将 packages/session/annotation/lib/typert.remote-client.js 复制到 src/remote.ts 并调整 package id）。过期的描述符会在客户端静默剥离字段——即典型的“schema 缺少字段”故障。

注意事项

- Host 部分使用命名空间插件形式（name / inject / apply 命名导出）。不要添加 export default——Loader 的 unwrapExports 会丢弃该命名空间。
- 浏览器部分挂载自己的 Typert Remote contribution（ctx.remote.$mount），因为已发布的 @deepseek-ai/dsh-api-remotes 不包含 annotation 命名空间。
- discard Remote 导出映射到 remove 方法（method: "discard"、implementation: "remove"）；保持生成的描述符同步。

许可证

MIT