前言¶
在 DSH 里做需要「设备是谁、用户是否同意、套件组件是否健康」的能力时，往往要把身份客户端、同意/撤回、设置段和健康检查拆在多个地方维护。HanaMesh 把 MOD-02 身份侧收成独立 npm 包 hanamesh-core，由维护者 yzsnstotz 发布，社区目录分类为 admin-security。它作为 DSH 插件接入宿主，提供设备身份、同意/撤回、HanaMesh 设置段、套件入口与健康观察；Usage、AppHost 需单独安装，缺件或版本不匹配时会有明确提示，身份与同意仍可用。
下面按定位、能力、安装启用、典型用法和注意事项说明，事实以 GitHub 仓库 README、package.json 与随包文档为准。
这是什么¶
hanamesh-core（npm 包名 hanamesh-core，当前资料中 package.json 版本为 0.3.18）是 HanaMesh Core：设备身份、同意、组件健康与套件入口的实现。目录页简介为 HanaMesh MOD-02 identity client plugin（plugin-identity）。
- 维护者：yzsnstotz
- 社区目录：https://www.skillhub.cn/plugins/yzsnstotz/hanamesh-core
- 源码：https://github.com/yzsnstotz/hanamesh-core
- GitHub 星标（目录线索）：0
宿主兼容目标为用户可安装的官方 Desktop/DSH 0.2.0-rc.2 起的 0.2.x（含 0.2.1-alpha.x）。公开 DSH peer 使用 semver 范围；管理器按 includePrerelease=true 检查，实际上限排除下一 minor 的预发布（<0.3.0-0）。桌面实测记录见仓库 docs/acceptance/dsh-rc2-compat-20261015.md，声明不等于运行证明。
Core 不采集事件、不实现应用容器或钱包奖励；不 import Usage/AppHost。私钥以 PKCS8 base64url 保存在 DSH storage-domain JSON 中，不通过 Core 契约、HTTP 或日志输出。
核心功能¶
身份、同意与设置¶
Core 提供设备身份与同意/撤回流程；绑定回跳通过 focus/visibility 刷新，不依赖深链。Core 首次激活前，由管理程序配置本轮 loopback/null origins、环境内 sharedIdentityDir，隔离 HOME/DSH_HOME/用户数据并清除继承凭据；正常 profile 配置输入见随包 docs/API.md。出厂合法默认值保持；设备共享路径在身份行可见，预算区只展示具名数值。
套件与健康观察¶
提供 HanaMesh 设置段与套件入口。组件启动失败时，健康行展示白名单错误码、已识别的数据域、原因与处理建议；读取失败原因最多等待 250ms，未知错误安全降级。不保存或展示原始错误、路径、堆栈或记录内容。数据格式不兼容时，文档建议先备份并安装支持该格式的组件版本，保留原数据后重新检查；Core 不迁移其他组件数据。修复前仍保持 repair 并拒绝新的受保护操作，重新检查确认组件健康后恢复 normal。
公开契约与导出¶
公开调用/类型及独立确定性 FIXTURE 验签向量见 docs/CORE_CONTRACT.md。sign 仅签原 Uint8Array；请求头签名与业务事件签名分开。
package.json 中主要入口包括：
- 插件主入口：
./lib/dsh.mjs - 子路径：
./contract、./client、./suite等 - CLI：
hanamesh-core-contract-suite、hanamesh-core-agent（对应lib/contract-cli.js、lib/agent-cli.js）
活动依赖 @deepseek-ai/dsh-typert-protocol@0.2.1-alpha.2 与宿主 peer 一并声明；干净消费者只需供给已声明的宿主依赖。
Agent 本地进程面（Session G，0.3.5 起）¶
node lib/agent-cli.js 通过 stdin/stdout JSON 提供不加载 DSH 的设备、同意、签名、注册、绑定链接与撤回入口。Usage 只调进程协议，不 import 本插件。设备沿用共享根 identity/device.json；agent 同意独立、默认关闭。state 为只读、不创建目录；任意签名/注册都等待同意。已撤回后只开放本设备固定 DELETE 操作，不开放任意签名；没有默认线上地址。Agent 0.3.6 起对明确同意代际签名，并要求事务性 v2 撤回屏障；细节见 docs/AGENT.md。
安装与启用¶
已抓取资料未给出固定的 dsh plugin add … 命令字符串，请勿凭仓库名自行拼接。启用路径建议：
- 在 SkillHub 社区目录打开插件页：https://www.skillhub.cn/plugins/yzsnstotz/hanamesh-core，按页面与当前 DSH 管理器的指引安装（社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系）。
- 安装与真实 resolved 版本/路径须保留收据；声明文本不当安装证据。
- 运行时使用隔离的
DSH_HOME；公开包不含本机 sibling tgz、研发链接或私有 registry 依赖。
若从源码参与构建与验证（维护者流程，非普通用户必做），仓库 README 给出的命令为：
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm check:contracts
pnpm verify:inputs
构建要求 Node >=24.13.1 <25、pnpm 10.33.0、TypeScript 5.9.3（开发输入）。
典型用法¶
DSH 宿主内¶
作为插件加载后，按 docs/API.md 配置 profile；套件与健康状态通过 Core 提供的 UI/逻辑入口观察。缺少 Usage 或 AppHost 时仍会提示，身份与同意能力保持可用。
Agent CLI（JSON 进程协议）¶
在已构建环境中，可通过 agent CLI 做本地集成测试或自动化。请求示例（根路径与地址由调用方明确配置）：
node lib/agent-cli.js
stdin 示例（资料原文）：
{"config":{"sharedHome":"<绝对路径>","serverOrigin":null,"websiteOrigin":null},"input":{"operation":"state"}}
成功返回 {result:{…}}；错误 {error:{code}} 并退出码 1；不导出私钥。进程接口细节与错误码见 docs/AGENT.md。
Server 注册 POST 的 Origin 为 serverOrigin；Server 的可信 Origin 须包括自己的公开地址。
契约验签¶
pnpm run test:contract
或使用 bin hanamesh-core-contract-suite 跑公开契约套件（见 docs/CORE_CONTRACT.md）。
适用场景与注意¶
适合谁
- 在 DSH 0.2.x 上搭建 HanaMesh 套件，需要统一设备身份、用户同意/撤回与健康观察的集成者。
- 需要与 Usage 解耦、通过 agent 进程协议驱动身份/同意/签名的工具或自动化（不直接 import Core 包）。
务必注意
- 插件在 当前 DSH 进程权限 下运行；安装前应自行审查源码、随包
docs/SECURITY.md与许可证，社区收录不代表审核或推荐。 - Core 不迁移其他组件数据；格式不兼容时按文档备份后换支持版本的组件，再重新检查健康。
- Agent/CLI/单元/包检查不能替代真实宿主与 owner 验收；资料中本轮平台证据为 macOS arm64 / Node 24.13.1，其他平台标注为 NOT_RUN 或无本轮支持承诺。
- 依赖与 peer 版本需与宿主 DSH 0.2.x 对齐；类型与 connection 公开类型依赖
@deepseek-ai/dsh-typert-protocol@0.2.1-alpha.2。
结尾¶
hanamesh-core 把 HanaMesh 的设备身份、同意/撤回、设置与健康观察收进一个 admin-security 向的 DSH Core 插件，并与 Usage、AppHost 解耦安装；需要本地进程集成时可走 hanamesh-core-agent JSON 协议。进一步细节见 GitHub 仓库与随包 docs/API.md、docs/AGENT.md、docs/CORE_CONTRACT.md。
