Annotation Core

当前运行环境：DSH 0.1.5-rc.2 实例 / web profile（0.1.5rc2）。其他 DSH 版本尚未验收。

0.3.12-rc2.29 · DSH 0.1.5-rc.2

Core 提供原生会话选文动作注册、统一引用气泡、注解、发送状态及上下文接入，并向扩展提供会话数据和引用端口。不依赖 DAG、Bridge、贴纸、Maintenance 或 Launcher。

气泡显示在输入区；用户检查引用后自行发送。已发送注释可在消息下重新查看。来源准备、发送、撤销和回执遵循同一引用状态流程，失败时保留草稿，不自动重复发送。

图、笔记定位等业务分别由各插件负责。Core 默认使用本地会话能力；可选受管接入通过通用服务提供，不把 Maintenance 当作基础运行前提。历史原生上下文管理工具需要相应能力，不能因安装 Core 就宣称全部高级功能可用。

开发接口：dsh-annotation-core/client-api、host-api、protocol、typert、remote。选文动作以 registerSelectionAction 注册；会话扩展数据使用带命名空间和修订的公共端口，不直接改其它插件存储文件。完整类型随包提供。

本版补齐卸载收尾：停止接收新任务后，等待已发出的回链、引用事务和持久化回执完成，再关闭存储。详见 生命周期记录。

部署方法

当前主线版本为 0.3.12-rc2.29；安装请使用本页指向的 GitHub Release 附件，npm 的旧版本不代表本主线。

0.3.12-rc2.28 给被引用文段加引用角标：被引用的文段末尾现在有一个小圆角标，点它直接弹出该条引用的卡片（与首次写入引用时同一个默认弹出位置），不必再去左下角引用栏里翻找。角标是只读渲染，不插进消息 DOM、不改写正文，位置由引用文本范围自己算，并启发式避让贴纸角标；代价是新增的共享文本表，配惰性失效与视口裁剪，滚动重绘不再每帧重跑 TreeWalker。详见变更记录。

上一版（0.3.12-rc2.27）补齐引用额度口径：此前把会话请求的 JSON 字节数当作 token 去减模型的 token 窗口，中文长会话会把可用引用额度算成 0 并拒绝引用。提交引用、上游读取与领域层三条路径已在 rc2.24–rc2.26 改为 token 口径；rc2.27 再补齐非原生兜底路径上剩下的两处（图片句柄文本、无宿主计量时的请求体），详见变更记录与前次记录。

环境要求：Node.js 24，可正常启动的 DSH 0.1.5-rc.2 / web profile。Core 不依赖 Maintenance、Launcher、Codex 或 Obsidian。

从 Release v0.3.12-rc2.29 下载 dsh-annotation-core-0.3.12-rc2.29.tgz，然后：

$env:DSH_HOME = '<你的 DSH_HOME>'
dsh plugin --profile web add ./dsh-annotation-core-0.3.12-rc2.29.tgz

安装命令会把包写进 profile 并在 dsh.profile.bundles 注册，不要再手工向 profile 插入同名插件节点。随后正常重启 DSH 使新版本加载。

核对安装结果：

(Get-Content "$env:DSH_HOME\profiles\web\node_modules\dsh-annotation-core\package.json" -Raw | ConvertFrom-Json).version

用法：在原生会话中选中文字，用注册的引用/注释入口；待发送气泡显示在输入区，检查后自行发送。

更新：正常停止 DSH，备份 DSH_HOME，用同样的 plugin add 装新 tgz，重启并刷新页面。 卸载：dsh plugin --profile web remove dsh-annotation-core。卸载代码不等于删除业务数据，保留 DSH_HOME 才能保留恢复条件。

完整说明（安装顺序、Vault 绑定、更新卸载、故障定位）：INSTALL.md。本批为预发布，当前能力和未完成验收见 发布验证记录。

已知问题

只有引用、没有正文时发送键不可用

设计上允许「只提交引用、不写正文」：composer-binding.tsx 的 canSubmit 在 pendingCount > 0 时为真，submitCore 也只在正文与引用都为空时才报「请输入正文或添加引用」。

但原生输入框的发送键不读这个 canSubmit。它靠 Core 用空 token 去认领一个命令来放行（native-adapter.tsx），而这个认领有两个问题：

• allowEmpty 不是宿主的 CommandClaim 字段（宿主契约只有 token/hint/attachments/submit），是用交叉类型硬加的，宿主不会读到。
• 认领会把输入框推进 claimed 态，而触发条件又要求 phase === 'plain'，条件自相矛盾。

结果：只有引用、正文为空时，发送键可能保持灰色。此路径没有自动化测试覆盖。

未修复。 修法需要改客户端行为，或由宿主提供一个「允许空提交」的正式入口。

源码开发：独立克隆、锁定依赖与打包。