# @changfenhuang/dsh-annotation 中文文档

规范地址：https://npmcn.com/package/%40changfenhuang/dsh-annotation/

版本：1\.4\.11
npm 元数据更新时间：2026-10-01T07:53:34.316Z
中文译文更新时间：2026-11-09T10:17:46.645Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40changfenhuang/dsh-annotation
原文对照：https://npmcn.com/package/%40changfenhuang/dsh-annotation/?lang=original
项目主页：https://github.com/omdsh-dev/dsh-annotation#readme
源码仓库：https://github.com/omdsh-dev/dsh-annotation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：189 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：cordis ^4\.0\.0-rc\.7 \|\| ^4\.0\.1
- 首次发布：2026-08-24T03:04:42.179Z
- 最新版本发布：2026-10-01T07:53:33.954Z
- 近 30 天下载量：3987（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

DSH Web选择-注释插件:选择助手文本,注释(可选),并按 Enter 发送注释块与您的消息——模型按数字对每次注释的回答,在回复中以可悬浮的芯片.

## 安装

```sh
npm install @changfenhuang/dsh-annotation
```

也可以使用：`pnpm add @changfenhuang/dsh-annotation`、`yarn add @changfenhuang/dsh-annotation`、`bun add @changfenhuang/dsh-annotation`

## README

# dsh-annotation

[English](https://npmcn.com/package/%40changfenhuang/dsh-annotation/README.md) · **简体中文**

DSH Web 选中批注插件：选文字 → 批注 → 回车随消息发给模型，回复按批注编号逐条对照

**🌐 [在线产品站：在 DSH 中体验 dsh-annotation](https://omdsh-dev.github.io/dsh-annotation/)**

![license](https://badgen.net/badge/license/MIT/blue)

![image](https://github.com/user-attachments/assets/c3186efc-44d3-4e7f-9523-1902d9d037e9) ![image](https://github.com/user-attachments/assets/0b48ac02-4648-4b94-8d8f-344f8b7c25b4) ![image](https://github.com/user-attachments/assets/8b2610d0-3d00-41be-b314-bac2fe616787) ![image](https://github.com/user-attachments/assets/9b66deea-3786-4296-9b0d-52873a15f5e1)

选中助手回复里的任意文字即可批注（批注内容可留空 = 仅标记原文），跨消息、跨回合连续收集；底部输入框旁出现「批注 ×N」标签（悬浮可见全部内容、可删单条）；直接回车，批注块随输入框里的问题一起发给模型。**你的消息气泡里不会出现批注块文本**——只显示问题和「批注 ×N」标签（hover 看内容，绘制前隐藏、零闪烁）；模型回复按「Annotation 1：…」逐条回应，回复里的每个 Annotation 标签都可悬浮查看对应批注的原文与内容。

形态：官方 **bundle 插件**（`dsh.bundle` + package.json `dsh.client` 声明，经 client-modules 注入浏览器端，Node half 为空实现）。**零核心改动**——不改 DSH 本体任何文件，`cordis.patch.yml` 仅一次 `insert` 自身 id，profile patch 保持 `[]`。

## 能力

侧边栏文件批注（DSH 0.1.6-alpha.1）：在工作区文件预览中选中文本、Markdown 或代码正文，即可沿用同一套批注、保存和回车发送流程。编辑器和发给模型的引用包含文件路径；刷新并重新打开原文件后恢复标记，同文不同文件可分别批注。当前不包含 PDF、图片或 iframe 内 HTML。

| 功能 | 说明 |
| --- | --- |
| 选中即批注 | 选中助手文字 → 工具条「批注」→ 直接写批注（可留空），点选外处或 Esc 收起 |
| 编号脚标 + 高亮 | 原文位置亮蓝编号 + 高亮，视口内锚定、碰撞避让，滚出屏幕不丢失 |
| 跨回合收集 | 任意多条批注跨消息/回合累积，编号从 1 开始 |
| 「批注 ×N」标签 | 输入框旁小标签，悬浮显示全部批注内容，可逐条删除 |
| 回车随消息发送 | 批注块 + 输入框问题一起发给模型（模型收到完整内容） |
| 气泡隐藏批注块 | 发送瞬间（浏览器绘制前）批注块从气泡 DOM 隐藏，只留问题 + 「批注 ×N」标签，hover 可见内容；刷新后历史消息自动修复 |
| 回复逐条对照 | 消息内注入格式指令，模型按「Annotation 1：…」…「Annotation N：…」逐条回应 |
| 回复批注芯片 | 回复里的「Annotation N：」渲染为可悬浮芯片，hover 显示该批注的原文 + 批注内容 |

## 交互流

```
选中助手文字 ──▶ 工具条「批注」──▶ 写批注/留空保存 ──▶ 原文亮蓝编号+高亮
        ▲                                                    │
        └────────────── 任意多条、跨回合累积 ◀────────────────┘
                        │
                        ▼
              输入框旁「批注 ×N」标签（hover 看内容/删除）
                        │
                    回车发送
                        ▼
   模型收到：批注块（编号+原文+批注）+ 你的问题
   你的气泡：只显示问题 +「批注 ×N」标签（零闪烁）
   模型回复：Annotation 1：… Annotation 2：…（可悬浮芯片）
```

## 安装（官方 bundle 路径 · 唯一）

```sh
# npm 公开包安装（无需 npm 账号）
dsh plugin --profile web add @changfenhuang/dsh-annotation
# 也可以直接从 GitHub 公开源码安装
dsh plugin --profile web add git+https://github.com/omdsh-dev/dsh-annotation.git
# 本地路径安装（开发调试）
cd /path/to/dsh-annotation
dsh plugin --profile web add .
# 重启 web —— 见下方「重启 web 服务」
```

如果只想把它作为 Node 依赖加入现有项目：

```sh
npm install @changfenhuang/dsh-annotation
```

> `npm install` 只添加依赖，不会把插件注册到 DSH；在 DSH 中使用时仍应执行上面的 `dsh plugin add`。

### 从旧 `@omdsh-dev` 包名迁移

如果你在 v1.4.2 之前安装过插件，请先删除旧依赖，再安装改名后的包：

```sh
dsh plugin --profile web remove @omdsh-dev/dsh-annotation
dsh plugin --profile web add @changfenhuang/dsh-annotation
```

如果 `dsh web` 仍然启动失败并提到 `@omdsh-dev/dsh-annotation`，请只删除 `~/.dsh/profiles/web/cordis.patch.yml` 中使用该旧名字的 `dsh-annotation` 登记。插件现在会自行提供 `@changfenhuang/dsh-annotation` 登记。

| 做 | 不做 |
| --- | --- |
| 只 `dsh plugin add` / 只写 `bundles` | **不要**再在 profile/home `cordis.patch.yml` insert 同 id |

自检：

```sh
dsh --profile web --dump-config | rg "id: dsh-annotation"   # 必须恰好 1 行
dsh web --no-open   # 复制输出的一次性令牌地址并在浏览器打开
```

在浏览器控制台执行 `window.__DSH_BOOT__.entries.find(({ id }) => id === '@changfenhuang/dsh-annotation')`，必须返回带 `url` 的登记；dsh 0.1.2 起不再开放旧版单插件裸地址。

## 重启 web 服务

按平台选择对应命令：

```sh
# macOS（launchd）
launchctl kickstart -k "gui/$(id -u)/com.dsh.web"

# WSL / Linux（systemd 用户服务）
# 服务名可能因安装方式而异，可用以下命令确认：
#   systemctl --user list-units | rg dsh
systemctl --user restart dsh-web
```

没有服务管理器的环境（如部分容器）通常**不需要重启**：`client.js` 按请求读取、no-cache，硬刷新（Cmd/Ctrl+Shift+R）即可加载插件改动。上面的自检命令跨平台通用。

## 架构要点

-   **纯浏览器端**：全部能力在 `client.js`（hand-written CJS bundle，无构建步骤，按请求读取 no-cache）
    
-   **消息格式**（跟随 DSH `locale` 语言偏好，zh/en 双语）：
    
    ```
    zh：我批注了以下 N 处内容…\n\n1. 原文\n   批注：…\n\n请用「Annotation 1：…」…\n\n提问：
    en：I annotated the following N passage(s)…\n\n1. quote\n   Note: …\n\nPlease respond… "Annotation 1: …"…\n\nAsk:
    ```
    
    （zh 分隔标记用「提问：」而非「问题：」——标题行「回答我的问题：」里也含它，气泡隐藏手术会误命中；en 用 `Ask:`。隐藏手术与反解析同时兼容两种语言及「问题：」老格式）
    
-   **气泡隐藏**：用户气泡是纯文本渲染（MessageText 单节点，非 markdown）；MutationObserver 微任务阶段（绘制前）按最后一个 `\n提问：` 切掉批注块、贴「批注 ×N」标签；1s 轮询兜底 + 刷新后历史消息自动修复
    
-   **回复芯片**：回复流式结束后（`data-streaming` 移除），把「Annotation N：」替换为可悬浮芯片；条目数据存于最近一条带批注标签的用户消息上（`tag.__annotationItems`），刷新后自动重建；**改 DOM 前先快照 TreeWalker 收集的文本节点再逐个替换**（遍历中途 replaceChild 会让 walker 指针失效，只处理到第一个节点）
    
-   **语言跟随**：UI 文案与批注协议块跟随 DSH `locale` 服务（zh/en，实时切换）；历史气泡跨语言可解析；locale 服务缺失时回退 zh
    
-   **IME 安全**：Enter 拦截带 `isComposing`/keyCode 229 守卫；不 DOM 硬改 composer textarea；`setDraft` 仅在提交前一刻拼批注块，不覆盖用户草稿
    
-   **不依赖发送完成事件链**：气泡装饰走 MutationObserver + 轮询（`watchInputDraft` 在初始化时会话未加载时会失效，仅作暂存入口）
    
-   **聚焦对话兼容**：支持 [dsh-focus-chat](https://github.com/dingyi222666/dsh-focus-chat) 的聚焦会话视图——其助手行是 `[data-focus-flow]` 内 class 含 `*_assistant`（CSS Modules 哈希名）的容器（流式期间行带 `data-streaming`）；选区批注、回复芯片、角标重新定位在聚焦 tab 与主视图一样可用
    

## 开发测试

[CI 与 DSH 宿主测试](https://npmcn.com/package/%40changfenhuang/dsh-annotation/docs/testing.md#%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87)

## 版本历史

| 版本 | 内容 |
| --- | --- |
| v1.4.x | 语言跟随：zh/en UI 文案与批注协议块，经 DSH `locale` 服务实时切换 |
| v1.3.x | 回复逐条对照：格式指令注入 + 「Annotation N：」可悬浮芯片（TreeWalker 快照修复） |
| v1.2.x | 气泡隐藏批注块：MutationObserver 微任务零闪烁 + 轮询兜底 + 历史消息修复 |
| v1.x | 自包含批注流（取代 v0.9 chip 设计）：capture Enter 拼稿随消息发送 |
| v0.9.x | 早期 chip 设计（insertReference + slash codec），已被 v1.x 取代 |

## 友情链接

-   [Linux.do](https://linux.do/)

## License

MIT

## 常见问题

### @changfenhuang/dsh-annotation 是什么？

DSH Web选择-注释插件:选择助手文本,注释\(可选\),并按 Enter 发送注释块与您的消息——模型按数字对每次注释的回答,在回复中以可悬浮的芯片\.

### 如何安装 @changfenhuang/dsh-annotation？

在项目目录运行 npm install @changfenhuang/dsh-annotation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：cordis（^4\.0\.0-rc\.7 \|\| ^4\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @changfenhuang/dsh-annotation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @changfenhuang/dsh-annotation 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @changfenhuang/dsh-annotation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @changfenhuang/dsh-annotation 可以商用吗？

@changfenhuang/dsh-annotation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @changfenhuang/dsh-annotation 的下载量有多少？

根据 npm 官方下载统计，@changfenhuang/dsh-annotation 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,987 次，日均约 133 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @changfenhuang/dsh-annotation 还在维护吗？

最新版本 1\.4\.11 发布于 2026/10/01（1 个月前）；至今共发布 14 个版本，其中过去 12 个月发布了 14 个；首次发布于 2026/08/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。