agent-q

Agent-Q

开发状态：Agent-Q 是一个正在积极开发的项目，已通过硬件测试验证 CLI、MCP 和受支持的提供方流程中的 Sui 签名路径。 当前的 StackChan CoreS3 Firmware 路径使用 DEV_PROFILE 材料，仅用于开发和演示，不用于托管真实资产。存储和配置文件的限制请参阅 Current Status。

概念

Agent-Q 将执行界面与签名权限分离。

执行能力不等于签名权限。对于由 Agent 驱动的 Sui 签名流程和本地 Sui 签名流程，Agent-Q 会明确保持这一边界。

本 README 介绍 Agent-Q 在本地 Sui 签名流程中的权限边界架构。当前的实现状态和配置文件限制记录在 docs/IMPLEMENTATION_STATUS.md 中。

MCP 客户端、Sui CLI 和受支持的 Sui 应用适配器通过本地 agent-q 主机进程提交受限请求。AI Agent 运行时通常通过 MCP 客户端访问 Agent-Q。主机负责中继请求；它不存储签名材料、不制定策略，也不批准签名。

Agent-Q Firmware 运行在独立的签名设备上。它持有已实现材料配置文件对应的签名材料和策略，检查设备状态和请求内容，应用已实现的策略或设备本地审批机制，并返回签名结果或明确的失败信息。

签名请求传输始终在本地进行。签名权限始终保留在设备上。请求方可以请求签名，但不能持有签名材料、选择授权模式或批准自己的请求。

结构

Agent-Q 包含三种角色：

• 请求方创建签名、账户、策略读取、策略提案提交或状态请求。MCP 客户端、Sui CLI、Sui 应用适配器和管理页面都是请求界面，而非签名权限持有者。
• 主机进程是本地的 agent-q 进程。它提供 MCP stdio 工具、本地 HTTP API、管理页面和面向适配器的请求界面，然后将受限请求中继给 Firmware。
• Agent-Q Firmware 是运行在签名设备上的软件。Firmware 负责策略检查、设备本地审批机制、签名、持久化和清理，并持有已实现材料配置文件对应的签名材料。

Agent-Q 使用简单的权限模型：

• 请求方创建请求；
• 主机进程中继请求；
• Firmware 根据设备本地状态处理每种已实现的请求类型。

对于签名请求，Firmware 会判断已实现的策略或设备本地审批机制是否允许签名。

不受支持的链和方法会明确报错。

使用 Agent-Q

• Sui 用户可以将 agent-q-sui-signer 注册为 Sui CLI 外部签名器。请参阅 packages/agent-q/README.md。
• MCP 客户端可以运行本地服务并调用 Agent-Q MCP 工具。请参阅 packages/agent-q/README.md。
• Sui 应用开发者可以使用 Sui 提供方包来支持 Wallet Standard 适配器流程。请参阅 packages/provider-sui/README.md 和 packages/sample-sui-dapp-kit/README.md。
• Sui zkLogin 浏览器设置和仅签名交易检查位于非生产测试 Web 示例中。请参阅 packages/sample-zklogin-test-web/README.md。
• 从事设备自有签名策略、本地审批和受限签名流程的 Firmware 与硬件开发者，请从 firmware/README.md 开始。

软件包

软件包	适用于……
@stelis/agent-q-core	发现设备、打开会话、调用 Agent-Q 协议并解析 Firmware 结果。
@stelis/agent-q	运行本地 MCP 服务、管理页面和 agent-q-sui-signer。
@stelis/agent-q-provider-sui	通过 provider / Wallet Standard 适配器，将 Sui 应用连接到 Agent-Q 设备。
packages/sample-sui-dapp-kit	运行一个通过 Agent-Q 签名的小型 dapp-kit 示例。
packages/sample-zklogin-test-web	运行一个非生产环境的浏览器测试工具，通过 Agent-Q 浏览器 provider 和 Web Serial 准备 / 提议 Sui zkLogin 证明，并检查仅签名交易。

当前实现亮点

当前实现包含以下由设备负责的路径。这些是开发 / 演示功能；DEV_PROFILE 和产品启用限制请参阅下方的“当前状态”。

• 设备本地 BIP-39 设置：Firmware 可以在设备上生成新的 12 词 BIP-39 备份短语，显示该短语以供备份，并且仅在本地确认备份且重复输入本地 PIN 后， 才存储 DEV_PROFILE 根熵。
• 设备本地助记词恢复：Firmware 可以通过设备 UI 接受 12 词 BIP-39 导入、验证校验和，并进入相同的本地 PIN 设置流程。尚未实现通过 USB、主机进程和 MCP 导入助记词。
• Sui zkLogin 活跃身份：浏览器测试流程可以通过 provider / Web Serial 路径准备并提议 有界的 zkLogin 证明材料。Firmware 会在设备上审核提议，要求通过本地 PIN 批准，存储一条 有界证明记录，并映射出活跃的 zkLogin Sui 账户。启用 zkLogin 时，同一签名请求路径会在 正常的 Firmware 授权关卡后生成 zkLogin 签名信封。Firmware 不存储原始 JWT。
• 大型 Sui 交易负载：sign_transaction 支持内联 txBytes，也支持在同一会话中分阶段 传送较大的 Sui 交易字节，最大可达 Sui 序列化交易上限。这是负载和适配器输入容量的说明， 并不表示所有 Sui 交易形态在语义上都可签名；不受支持或无法绑定的形态会在签名前失败。
• Sui 赞助交易接收路径：Firmware 提供设备本地的 Sui 账户设置，用于控制是否接受已解析的 sender 为活跃账户、已解析的 gas owner 为其他赞助方的交易。接受后，Agent-Q 仍只返回活跃 sender 的签名；赞助方签名收集和交易执行组装不属于 Agent-Q 的范围。

请求流程

flowchart LR
  Agent[AI agent] --> MCP[MCP API]
  Admin[Admin Page] --> HTTP[HTTP API]
  SuiCLI[Sui CLI] --> Signer[agent-q-sui-signer]
  App[Sui app] --> Provider[Sui provider]

  MCP --> Server[agent-q local server]
  HTTP --> Server
  Signer --> Server
  Provider --> Server

  Server --> Core[Agent-Q core]
  Core --> Firmware[Firmware]

当前签名路径概述如下。在本 README 中，product-active 表示 docs/IMPLEMENTATION_STATUS.md 中已完成匹配的源代码、文档、测试、构建、当前代码树目标硬件证据和视觉证据。 某条路径可能已经实现并通过硬件测试，但其 product-active 证据仍在完善中。

链	方法	当前行为
sui	sign_transaction	当前实现支持内联或同一会话暂存的 Sui 交易字节。它会验证请求，在可用时解析有界的离线交易事实，应用设备本地策略或用户授权门，并且只有在该门授权签名后才生成签名响应。解析出的发送方必须与当前账户匹配；除非当前账户的设备本地 Sui 账户设置允许燃料赞助方，否则解析出的燃料所有者也必须匹配。若缺少必需的策略覆盖、覆盖不完整、不匹配或命中拒绝规则，策略模式将默认拒绝。用户模式仅在 Firmware 能够推导出所需语义事实，并能将所需审核详情纳入有界的显示摘要时，才会显示已覆盖的离线事实；解析成功本身并不保证审核清晰。否则，对于绑定到当前账户的有效交易，它会显示设备本地盲签名警告。盲签名是指确认可签名字节，但无法通过离线事实完整审核其交易详情。
sui	sign_personal_message	当前实现支持在用户授权模式下进行有界的 Sui 个人消息签名。策略授权模式对此方法默认拒绝。

当前实现包含 Sui zkLogin 活跃身份路径，但 docs/IMPLEMENTATION_STATUS.md 尚未将其标记为 product-active。示例测试网页通过 Web Serial 执行浏览器到设备的证明设置和仅签名交易检查。Enoki、OAuth、证明器工作和 Google OAuth 测试网设置均保留在浏览器测试层；Agent-Q 仅接收有界的证明提案。该示例不会显示 JWT 或证明 JSON，也不会将其写入浏览器存储。

不支持的链和不支持的方法会明确失败。链通过共享协议公开；Agent-Q 不会创建单独的、特定于链的产品 API。

权限边界基础

本节说明谁可以请求操作，以及谁可以做出决定。DEV_PROFILE 存储和 product-active 状态见“当前状态”。

• 主机进程、MCP、Sui CLI 工具、提供方、应用和 Agent 都是请求方，而非签名授权方。
• 主机进程不存储签名材料，也不做出签名或策略决定。
• 对于已实现的材料配置，Firmware 持有签名材料和策略，并负责做出签名决定。
• Firmware 根据设备本地状态选择签名授权门。请求无法选择策略授权模式或用户授权模式。
• Agent-Q 无法验证创建签名请求之前，Agent、应用、钱包 UI 或主机进程内部发生了什么。
• 所有外部请求都是不可信输入。签名前，Firmware 必须解析有界的请求内容。

当前状态

详细状态见 docs/IMPLEMENTATION_STATUS.md。

当前实现包括上文列出的 Sui 签名路由、MCP 工具、provider-sui 和 StackChan CoreS3 Firmware 路径。硬件冒烟测试覆盖情况记录在 docs/IMPLEMENTATION_STATUS.md 中；只有当相应状态行表明源代码、文档、测试、构建、硬件和视觉证据均已完备时，才宣称签名支持已可用于产品。

当前限制：

• 当前 StackChan CoreS3 Firmware 路径使用的是面向开发和演示的 DEV_PROFILE 材料，不适用于真实资产托管。
• 在 DEV_PROFILE 中，根熵、活动策略记录和本地 PIN 验证器存储在普通 NVS 中。Secure Boot、Flash Encryption 和 NVS Encryption 均未配置。
• DEV_PROFILE 是唯一已实现的材料配置。
• Sui 是唯一可执行的链。
• Sui 交易解析有界且离线。Agent-Q 不会模拟 Sui 执行，也不会获取链上状态。
• Sui 赞助交易支持仅限于上文所述的发送方绑定接收路径。Agent-Q 不会生成、收集或组装赞助方签名，也不会执行或提交 Sui 交易。
• 尚未实现策略授权的个人消息签名。
• Sui zkLogin 浏览器到设备的设置、清除、重新连接和签名路径尚未进入产品启用状态。
• 浏览器 dapp 签名需要 provider/浏览器运行时路径，而非 Node 本地 provider 工厂。

进阶

• 协议约定：specs/PROTOCOL.md
• 安全模型：docs/SECURITY_MODEL.md
• 状态模型：docs/STATE_MODEL.md
• 当前策略架构和 Sui 策略事实：docs/POLICY_SCHEMA.md
• 实现状态：docs/IMPLEMENTATION_STATUS.md
• 固件概述：firmware/README.md
• StackChan CoreS3 目标：firmware/src/stackchan-cores3/README.md

开发

安装工作区依赖：

npm install

构建所有包：

npm run build

运行根目录测试套件：

npm test

固件构建说明因目标而异。请先查看 firmware/README.md 和 firmware/src/<hardware-id>/ 下的目标 README。

.WORK/ 用于本地规划、临时文件和调查材料。它不会由 Git 跟踪，用户可见的构建或运行说明也不得依赖它。