dmk-intent-vocabulary

DMK 意图词汇表

此技能会将开发者的非正式请求映射到正确的 DMK 组件和操作，确保在开始实现前识别出正确的 API。当执行前意图不明确时，ledger-dmk-implementation/SKILL.md 也会将其作为连接器加载。

---

约定

派生路径是由开发者设置的常量，绝不能作为用户输入，也绝不能由 Agent 推断。 它们必须以字面值的形式出现在应用代码中（例如 "44'/501'/0'/0'"）。如果调用上下文中缺少派生路径，请停止并询问开发者——不要替换、设置默认值或猜测。错误的路径会生成一个看似有效、实际来自另一把密钥的结果，且不会触发运行时错误。

---

词汇表

设备发现

常见说法：“查找我的 Ledger”、“检测硬件钱包”、“扫描设备”、“Ledger 未显示”、“未找到设备”、“USB 未检测到设备”、“WebHID 没有找到任何内容”

对应： dmk.startDiscovering() — 返回 Observable<DiscoveredDevice>

注意： 连接前的第一步。开发者必须订阅并等待数据发出，然后才能连接。

---

设备连接和会话管理

常见说法：“连接 Ledger”、“打开会话”、“建立连接”、“断开后重新连接”、“获取会话 ID”、“设备已连接但无法发送命令”、“如何断开连接？”

对应：

• dmk.connect({ device, sessionRefresherOptions: { isRefresherDisabled: false } }) — 返回 Promise<DeviceSessionId>
• dmk.disconnect({ sessionId })
• dmk.getConnectedDevice({ sessionId }) — 设备型号和名称，仅供参考

注意： 所有后续交互都需要 sessionId。

---

设备状态

常见说法：“设备是否已锁定？”、“正在等待 PIN”、“当前打开了什么应用？”、“设备正忙”、“观察设备”、“监听设备状态变化”、“电池电量”、“不发送命令获取固件版本”、“设备刚刚断开连接”

对应： dmk.getDeviceSessionState({ sessionId }) — 返回 Observable<DeviceSessionState>

注意： 会持续发出数据。包含设备状态（ready、busy、locked、disconnected）、设备名称、操作系统信息、电池状态和当前打开的应用。优先使用此方法，而不要通过发送命令轮询。

---

应用管理

常见说法：“打开 Bitcoin 应用”、“启动 Ethereum 应用”、“切换应用”、“应用无法打开”、“正在等待用户确认启动应用”、“签名之前确保打开了正确的应用”、“关闭应用”、“检测正在运行的应用”

对应：

• OpenAppDeviceAction — 包含在设备上等待用户确认的完整流程（面向用户的流程首选）
• OpenAppCommand — 较低层级的直接命令
• CloseAppCommand
• GetAppAndVersionCommand — 返回正在运行的应用名称和版本

---

固件和操作系统信息

常见说法：“获取固件版本”、“设备上运行的是什么操作系统？”、“MCU 版本”、“引导加载程序版本”、“SE 版本”、“固件是否为最新版本？”

对应：

• GetOsVersionCommand — 返回 seVersion、mcuSephVersion、mcuBootloaderVersion
• 或通过会话状态获取：dmk.getDeviceSessionState 已包含操作系统信息，无需额外命令

---

原始 APDU 命令

常见说法：“发送原始 APDU”、“低级命令”、“自定义 CLA/INS”、“APDU 字节”、“预构建命令无法满足我的用例”

对应：

• ApduBuilder + dmk.sendApdu({ sessionId, apdu })
• 或扩展 Command 类并使用 dmk.sendCommand（比原始 APDU 更推荐）

不要将原始 APDU 用于签名操作。 如果目标是签名，且该链有对应的签名器包，请使用该包。原始 APDU 会绕过预检、可观察的确认状态和错误分类逻辑。它只适用于非签名命令或确实不受支持的链。

---

获取加密货币地址

常见说法：“获取我的 Ethereum 地址”“派生钱包地址”“在设备上显示地址”“在屏幕上验证地址”“从 Ledger 获取公钥”“获取 Bitcoin 地址”“获取 Solana 公钥”

映射到（按链）：

• ETH：signerEth.getAddress(derivationPath, options)
• BTC：Bitcoin 签名器的等效方法
• Solana：Solana 签名器的等效方法

**注意：**返回一个可观察对象。对于向用户提供收款地址的任何流程，请使用 checkOnDevice: true。跳过此步骤意味着用户无法在设备屏幕上查看地址，而设备屏幕是他们唯一可以用来核对地址是否与可能已遭入侵的主机显示内容一致的地方。

---

签署交易

常见说法：“签署交易”“签署 ETH 交易”“签署并广播”“清晰签名”“用户在屏幕上确认交易详情”“签署 Bitcoin 交易”“签署 Solana 交易”“硬件钱包签名流程”“用户拒绝了交易”

映射到（按链）：

• ETH：signerEth.signTransaction(derivationPath, transaction, options)
• BTC：Bitcoin 签名器的等效方法
• Solana：Solana 签名器的等效方法

**注意：**返回一个可观察对象。处理 Pending 状态（用户在设备上的操作）和 Completed 状态以获取签名。用户拒绝会以错误状态的形式呈现。

---

签署消息（personal_sign）

常见说法：“签署消息”“personal_sign”“证明钱包所有权”“通过签名进行身份验证”“钱包身份验证流程”“使用 Ledger 签署文本”

映射到：signerEth.signMessage(derivationPath, message)

**注意：**哈希前会添加前缀 \x19Ethereum Signed Message:\n，这个前缀正是其安全性的保障。此方法不同于类型化数据签名。

不要将 eth_sign 映射到此方法。eth_sign 会签署不带安全前缀的原始哈希，是已知的钓鱼攻击途径。如果开发者要求实现 eth_sign 行为，请先指出安全风险再继续。

---

签署类型化数据（EIP-712）

常见说法：“签署类型化数据”“EIP-712”“signTypedData_v4”“域分隔符”“MetaMask 风格签名”“permit 签名”“链下订单”

映射到：signerEth.signTypedData(derivationPath, typedData)

**注意：**需要完整的类型化数据对象（domain + types + message）。用于 DeFi 授权、链下订单和委托。

---

委托授权（EIP-7702）

常见说法：“EIP-7702”“委托授权”“签署委托”“账户抽象签名”“将权限委托给合约”

映射到：signerEth.signDelegationAuthorization(derivationPath, delegationAuthorization)

---

测试与调试

常见说法：“模拟设备”“无需真实 Ledger 即可测试”“模拟硬件钱包”“Speculos”“模拟器”“使用 Ledger 进行 CI 测试”“设备日志”“调试 APDU”“单元测试 DMK”

映射到：

• Speculos 传输：@ledgerhq/device-transport-kit-speculos
• 开发者工具：DevToolsLogger、DevToolsDmkInspector、WebSocket 连接器或 Rozenite
• React Native：Rozenite 连接器

**仅用于测试和 CI。**切勿在生产环境中配置 Speculos、模拟传输或 setStub(true)。它们会绕过真实设备交互，使安全模型失效。

---

常见错误状态

常见说法：“设备已锁定”“打开了错误的应用”“未安装应用”“用户拒绝”“用户在设备上取消”“设备在流程中途断开连接”“状态字不是 9000”“可观察对象始终未完成”“操作卡在 pending 状态”“HID 错误”“USB 权限被拒绝”

**注意：**如果设备已锁定，大多数命令都会被拒绝——请先检查 DeviceSessionState。状态字错误（!= 0x9000）会通过命令解析逻辑呈现。用户拒绝会以 DeviceActionStatus.Error 的形式呈现。USB 权限被拒绝属于浏览器安全限制——必须通过用户手势触发设备访问。

→ 如需了解完整的错误分类以及 ABORT/ESCALATE 路由，请加载 ledger-dmk-implementation/SKILL.md。

---

真伪检查

表达方式：“验证设备是否为正品”“真伪检查”“这台 Ledger 是真的吗？”“检查设备真伪”“认证设备”“这是真正的 Ledger 吗？”

**映射到：**通过 dmk.executeDeviceAction() 调用 GenuineCheckDeviceAction

**注意：**需要安全通道（HSM 后端）。返回 output.isGenuine: boolean。每次设备重启后首次使用时会提示 AllowSecureConnection。

---

列出已安装的应用

表达方式：“设备上有哪些应用？”“列出应用”“安装了哪些应用？”“显示已安装的应用”“检查是否安装了 Ethereum 应用”

**映射到：**通过 dmk.executeDeviceAction() 调用 ListInstalledAppsDeviceAction

**注意：**返回 output.installedApps: InstalledApp[]。需要安全通道。

---

安装／卸载应用

表达方式：“安装 Ethereum 应用”“向 Ledger 添加应用”“移除应用”“卸载 Bitcoin 应用”“尚未安装应用——安装它”“将应用部署到设备”

映射到：

• 安装：通过 dmk.executeDeviceAction() 调用 InstallAppDeviceAction
• 卸载：通过 dmk.executeDeviceAction() 调用 UninstallAppDeviceAction

**注意：**安装会在 intermediateValue.progress 中输出进度（0–100）。应用名称必须与 Ledger Live 使用的名称完全一致。需要安全通道。

→ 如需安全通道代码模式，请加载 ledger-dmk-implementation/SKILL.md。