# @eduwork/dsh-annotation 中文文档

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

版本：0\.1\.5
npm 元数据更新时间：2026-11-12T07:53:46.869Z
中文译文更新时间：2026-11-13T07:36:32.201Z
软件包许可：MulanPSL-2\.0 AND MIT

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

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

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

- 包体积（解压后）：73.3 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=24\.18\.0
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0，@deepseek-ai/dsh-client-ui-chat \>=0\.2\.1-rc\.2 \<0\.3\.0-0 \|\| \>=0\.2\.2-rc\.1 \<0\.2\.3-0，@deepseek-ai/dsh-client-ui-primitives \>=0\.2\.1-rc\.2 \<0\.3\.0-0 \|\| \>=0\.2\.2-rc\.1 \<0\.2\.3-0，@deepseek-ai/dsh-client-ui-conversation \>=0\.2\.1-rc\.2 \<0\.3\.0-0 \|\| \>=0\.2\.2-rc\.1 \<0\.2\.3-0，@deepseek-ai/dsh-client-ui-input-trigger \>=0\.2\.1-rc\.2 \<0\.3\.0-0 \|\| \>=0\.2\.2-rc\.1 \<0\.2\.3-0
- 首次发布：2026-10-22T05:48:38.408Z
- 最新版本发布：2026-11-12T07:53:46.477Z
- 近 30 天下载量：2656（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

使用本地 DSH 作曲引用的编号响应说明

## 安装

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

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

## README

# 选段引用与批注

[English](https://npmcn.com/package/%40eduwork/dsh-annotation/README_EN.md)

`@eduwork/dsh-annotation` 是一个可选的 DSH 插件：选中已完成回复中的文字，添加批注，在原回复底部查看编号，并与问题一起发送。引用、草稿保存与发送沿用 DSH 原生机制。

## 安装

在 EduWork 的「插件」页选择「添加插件」，填写 `@eduwork/dsh-annotation`，安装后启用。停用和卸载在同一页面完成。其他兼容 DSH 客户端也可以通过插件管理器安装这个独立 npm 包。

需要提供官方 Chat 视图与输入框扩展的 DSH 客户端（`>=0.2.1-rc.2 <0.3.0-0`）。已发送批注在气泡上方显示编号，需要 EduWork 的 `conversation.chat.user.decorate` 扩展入口；未提供该入口的客户端通过官方文本插槽显示引用卡片，仍可独立使用。排队等原生文本界面也使用卡片显示。

从 0.1.2 起兼容 DSH `0.2.2-rc.1`，选区菜单复用官方文字交互入口，将「引用文本」「批注」和可选侧聊合在同一操作栏；原生引用与批注可以在同一草稿中编辑、撤销和恢复。旧宿主继续使用原有选区适配。

选区与基础引用由官方负责，批注沿用官方草稿和发送入口；本插件补充逐段评论、编号与编辑。新版宿主的可见选区文本直接使用官方投影，批注详情的定位与外部点击关闭复用官方 UI primitives。旧消息、评论协议和来源编号保持兼容；插件不维护另一套会话或草稿存储。

## 使用

1.  在已结束回合的最终回复中选中文字，在悬浮操作栏中点「批注」。
2.  写批注（可留空），点「加入输入框」或按 Enter；Shift+Enter 换行。拼音组词时，Enter 只确认候选词，结束组词后再按 Enter 加入输入框。
3.  原回复底部出现批注编号；输入框保留原生引用块，并显示「N 条批注」。点击编号、引用块或汇总列表，可查看完整摘录、编辑或删除批注。
4.  可以继续添加多处批注，再输入问题一起发送；也可以只发送批注。发送后，当前草稿对应的编号与汇总自动清空。
5.  已发送消息在气泡上方显示「批注 1、2…」，悬停、点击或键盘聚焦编号可查看摘录与批注。气泡内只展示问题正文；只有批注时不生成空白气泡。

引用块随草稿保存，可与普通文字、文件引用混用。刷新页面后会恢复待发送批注与来源编号。编号按当前输入框中的批注顺序排列，删除和原生撤销会同步更新。发送仍由客户端的原生流程完成，排队与插入运行中回合的行为遵循你的设置。

编辑批注不会覆盖输入框里的其他内容；「取消」保留原批注。编辑时切换焦点不会自动关闭编辑框。若引用已变化或输入框正处于命令、提交状态，保存或删除会拒绝执行，保留输入供重试。只读预览可通过点击弹窗外、切换窗口或 Escape 关闭。

如果输入框暂时无法接收引用，批注编辑框会保留原文与输入内容，可稍后重试。浮层会跟随选中文字的位置，包括滚动和图片加载等排版变化。

## 功能边界

可选的侧聊插件还允许从中间回复和正在输出的助手文字直接提问，不必等待本轮结束。此时只提供侧聊动作，普通批注编号仍只绑定已完成的最终回复；流式摘录不伪造消息 ID，也不改变发送协议。

从 `0.1.1` 起，选区操作栏支持可选扩展。另行安装并启用 `@eduwork/dsh-side-chat@0.1.0` 后，同一操作栏会增加「在侧边聊天提问」：摘录作为未发送批注加入侧聊输入框，可编辑、删除或继续添加，不修改原会话草稿。侧聊要求 DSH `0.2.1-rc.3` 起的兼容接口；两个包可分别启停，单独安装批注时保留原有批注功能。

-   编号显示在原回复底部，随消息自然滚动；不在选中的每个字上绘制高亮或浮动编号。
-   待发送批注在原回复底部编号；已发送批注从用户消息里的结构化前缀还原，在该消息气泡上方显示，不维护另一套历史批注库。
-   新批注限定为官方 Chat 中已完成回合的最终回复；不对流式内容、工具输出、用户输入或侧栏文件挂编号。
-   摘录本身是完整快照。新增引用还会保存来源消息 ID 和选区前后各最多 320 字符的可见上下文，不代表读取了完整来源。来源暂未加载时，仍能查看和发送；旧版无来源信息的引用仍兼容。旧的 Markdown 引用消息保持原样。

## 开发

```sh
node scripts/packages/manage.mjs install dsh-annotation
node scripts/packages/manage.mjs check dsh-annotation
```

插件通过官方 `conversation.chat.turnTail`、`conversation.input.left` 和 `conversation.input.overlay` 插槽添加界面。待发送批注和顺序来自公开的 `InputState.occurrences`；编辑、删除通过带版本校验的原生输入区间操作完成，不直接修改 Lexical 或整段草稿。`src/client/draft.js` 集中处理引用坐标换算及公开 Chat 快照中的来源消息解析。

rc.1 的公开 `InputState` 未包含原生 Quote 区间，因此编辑/删除批注还通过输入框 facade 的只读 `draftSnapshot` getter 取得完整语义草稿，并核对文本和引用列表与当前状态一致后换算坐标。该 getter 尚未写入上游公开的 `SessionInput` 类型契约，是需要随上游升级复核的窄适配点；缺失或不一致时保留草稿并拒绝修改。插件不读取编辑器内部节点或浏览器存储。

选区只通过官方 Chat 行的 `data-chat-node-key` 查找消息身份，并以 DOM Range 截取同一行的有限前后文；不修改正文 DOM、不全局扫描文字。宿主更换 Chat 行结构时需重新核对此适配点，不能回退为猜测来源。

发送时，引用 codec 生成带版本的中间片段，宿主 `agent/pre-step` 将同一条用户消息里的片段整理成一次固定 prompt、`<eduwork-response-annotations>` JSON 和问题正文。消息角色、ID、附件以及原生 Queue/Steer 流程保留。JSON 对 XML 边界和原生引用符号转义；摘录与前后文明确作为引用材料处理。重试不会重复包装。

`agent/pre-step` 整理后的内容会由官方 Agent 写入会话历史，不是仅存在于临时模型请求中。展示组件只投影消息文本；编号、摘录、批注与上下文都从消息自身恢复，不维护第二套存储。未知版本、未知字段、损坏格式、代码示例保留原文，不静默删除额外数据。`src/protocol.js` 是发送与展示共用的协议实现；原生文本卡片沿用 `uiConversation.userText` 和 `conversation.user.text.node`，也兼容旧版测试消息。

通用气泡装饰入口由 `scripts/patch-chat-user-content-runtime.mjs` 对锁定的 Runtime 副本适配，并写入构建回执。补丁不含批注业务逻辑，插件未启用时回到原生渲染；正文、附件与消息操作仍由原生组件负责。补丁严格核对包版本和文件 SHA-256，上游文件变化时停止装配，必须重新评估或移除适配，不能跳过检查。未加补丁的官方客户端使用上述卡片回退；上游提供等价扩展入口后应移除此补丁。

主许可证：木兰宽松许可证第 2 版；历史 MIT 代码与适用范围见 [LICENSING.md](https://npmcn.com/package/%40eduwork/dsh-annotation/LICENSING.md)。

## 常见问题

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

使用本地 DSH 作曲引用的编号响应说明

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

在项目目录运行 npm install @eduwork/dsh-annotation，或使用 pnpm add / yarn add / bun add。

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

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/eduwork\_\_dsh-annotation 是否存在。

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

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

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

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

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

@eduwork/dsh-annotation 使用 MulanPSL-2\.0 AND MIT 许可。声明的许可为 MulanPSL-2\.0 AND MIT，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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