前言¶

在 DSH 里做 HanaMesh 相关插件或工作流时，往往需要知道「用户是否同意上报」「本机记录了哪些 open/use/install」以及如何把最小结构化事实同步到服务端，同时避免把 prompt、对话正文或凭据写进存储。若只靠各插件各自落盘，Consent、设备身份与上报格式很难统一。下面介绍社区插件 hanamesh-usage：它在宿主内保留本机 Declaration 三态使用摘要，并提供同意门、设备签名、事件缓冲与服务器上报；生产路径只保存结构化最小信息。

这是什么¶

hanamesh-usage 是 HanaMesh 体系中的 Usage（activity）插件，由维护者 yzsnstotz 发布，在 SkillHub 目录中归类为工作流。仓库描述为：Consent-gated, device-signed HanaMesh usage events for DSH（MIT 许可证）。它与可选的 hanamesh-core 配合获取设备身份与同意开关；core 缺席时仍可在本机记录，但不向 Server 上报。

核心功能¶

本机摘要与事件管线¶

插件在本机维护 Declaration 三态使用摘要，并处理 Usage 事件的采集、签名与缓冲。上线事件在同意通过且字段完整时才会创建并上报；未同意时不创建 UsageEvent，也不向 Server 上报，本机 Declaration 摘要仍可保留。

同意撤回时，先清空本地事件缓冲，再调用 Server 删除接口；离线时只完成本地删除并保留可重试状态。Declaration 仅留本机，不会作为 summary 上传。

同意门与上报边界¶

上线事件必含 deviceId、hanaRef、action、occurredAt、eventId、nonce、signature 七个键。自 rc.7 起，可选字段 sourceHanaRef、targetRef、receipt 仅在非 null 时随事件上线；回执只含供应商 id、模型名和次数，不含 prompt、响应或凭据。生产路径不保存 prompt、对话、文件、完整结果、私有路径或凭据。

客户端与命令观测¶

Usage 客户端经 Cordis internal/get 包装部分功能位（如 main、settings.section、plugins.bundle.config、plugins.row.config），在组件提交有内容的 DOM 后通过自有 Remote 报告 issue / presented；Host 侧经 Cordis 包装 commands 注册，配对 command/run 与 command/done(success) 产出与 use 消费同形的事实。record 供其它 HanaMesh 插件投递 open / use；安装与卸载由 Loader 观测产生，并支持可选归因与 use 专用回执字段，同一 idempotencyKey 冲突投递会得到 rejected: EVENT_IDENTITY_CONFLICT。

本地 HTTP 与 Cordis 服务¶

Host 暴露一组本机接口，例如：

• GET /api/hanamesh/usage
• GET /api/hanamesh/usage/view
• POST /api/hanamesh/usage/export
• GET /api/hanamesh/usage/health
• GET /api/hanamesh/usage/events
• GET /api/hanamesh/usage/panel 及 /panel/view、/panel/remote（rc.16 起）

ctx.hanameshUsage 提供 query、export、health、drain、reconcile、record、panel 与 remote 等能力。GET /api/hanamesh/usage/health 在 core 缺席时会体现 core: 'absent'。

Usage 开发小面板¶

正常安装 bundle 后，客户端通过 settings.section 注册「Usage 开发小面板」。入口：HanaMesh.app → Settings → Usage 开发小面板。刷新时仅 GET 本包认证路由 /api/hanamesh/usage/panel/view，HTML 在无脚本、无表单的 sandbox iframe 中展示；读取失败显示有界错误，不创建事件。面板展示当前 Core 设备的事件、动作、时间与签名校验状态，不输出 nonce 或原始签名。

服务端读回（本设备）¶

remote() 与 GET /api/hanamesh/usage/panel/remote 只读本设备在服务端的记录（经 Core 对公开路由签名请求，窗口为当前起往前 90 天）。读回不写本机状态、不受同意开关影响，可用于撤回后核对删除。无服务端地址时为 offline；拒绝或不可达时为 state:'unknown'。

可配置项（Q61）¶

Cordis 插件 config 支持例如：

{"eventRetentionDays": 90, "queryLimit": 100}

• eventRetentionDays 默认 90，只裁剪已发送终态且超出保留窗口的事件；pending 不按年龄裁剪。
• queryLimit 默认 100，范围 1–1000，声明与事件查询共用。

无效值报 INVALID_CONFIG。Usage 开发小面板及 panel().policy 会显示实际值；读取配置不会写入或改变同意。

安装与启用¶

hanamesh-usage 是声明了 dsh.bundle.patch 的 DSH bundle。在指定 profile 下执行：

dsh plugin --profile <p> add hanamesh-usage

装完即激活，不需要手写 cordis.patch.yml。hanamesh-core 与本包各只插入自己的 Loader 条目；本包不从 Core 传递安装，也不导入其他 HanaMesh 插件。

依赖说明： 设备身份与同意来自 hanamesh-core（可选）。core 缺席时只在本机记录、不上报。

从旧版 @hanamesh/dsh-activity（rc.3）升级： storage-domain 由 hanamesh_activity 改为 hanamesh_usage，旧记录不迁入、不删除；需保留请先在 rc.3 上调用 POST /api/hanamesh/activity/export 导出。

宿主版本： 公开 peer 范围包含 DSH >=0.2.0-rc.2 <0.3.0-0 || >=0.2.1-0 <0.3.0-0 及对应 Cordis、zod 区间；范围准入不代表每个版本都在真实 Desktop 验过，安装前请对照仓库兼容文档与当前 DSH 版本。

首次 Plugin Manager 扫描会把当前 profile 自有插件记为 install，occurredAt 为扫描时刻，属于 Adoption 弱证据。

典型用法¶

1. 安装后查看健康与摘要¶

安装 bundle 并（可选）启用 hanamesh-core 后，可用本机 API 查看状态，例如：

curl -s http://127.0.0.1:<port>/api/hanamesh/usage/health

根据返回判断 core 是否缺席、上报链路是否可用。

2. 在设置里打开开发小面板¶

路径：HanaMesh.app → Settings → Usage 开发小面板。用于查看本设备事件与签名校验结果，不触发额外采集逻辑。

3. 其它 HanaMesh 插件投递使用事实¶

在 Host 侧通过 ctx.hanameshUsage.record 投递 open 或 use（安装/卸载由 Loader 观测）。可选传入 sourceHanaRef、targetRef，以及仅用于 use 的 receipt { providerId, model, count }；需遵守 idempotency 与字段合约，避免身份冲突拒绝。

4. 导出与查询¶

• 导出：POST /api/hanamesh/usage/export
• 查询：通过 ctx.hanameshUsage.query 或 GET /api/hanamesh/usage / /view，注意 queryLimit 与分页参数。

5. 核对服务端本设备记录¶

在 Connection 与 Core 可用时，使用 remote() 或认证路由 GET /api/hanamesh/usage/panel/remote 读回服务端本设备事件列表，用于与本地或撤回结果对照。

适用场景与注意¶

适合谁： 正在开发或集成 HanaMesh 插件、需要在 DSH 内统一 Consent、设备签名 Usage 事件、并控制上报最小字段的开发者与团队。

权限与安全： 插件以当前 DSH 进程权限运行；安装前应阅读 GitHub 仓库 源码与 MIT 许可证，确认同意门与数据边界符合你的合规要求。客户端 DOM/命令观测机制不证明被攻陷客户端的渲染真实性；面板与测试供给标识（如 panelTestSupply）未标为测试的仍应视为「真实性未知」。

生态说明： DSH 采用「一切皆插件」思路；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。

版本： 仓库 package.json 当前为 0.3.0-rc.5；README 持续记录 rc 级兼容与 nonce 历史事件等行为，升级前请阅读仓库 docs/compatibility/ 与发布说明，一般无需删除 storage。

结尾¶

hanamesh-usage 把 HanaMesh Usage 的同意门、本机 Declaration、设备签名事件与受限上报收拢到一个 DSH bundle，并给出本地 API、开发小面板与服务端读回入口。目录页：https://www.skillhub.cn/plugins/yzsnstotz/hanamesh-usage；源码与完整说明：https://github.com/yzsnstotz/hanamesh-usage。