dsh-web3

English | 中文

面向 DeepSeek Harness (DSH) 的 Agent 安全 EVM 钱包，以 DSH bundle 的形式发布。

概要

让 Agent 帮你查余额、转代币、签 Permit、支付 x402 账单，而私钥永远不会出现在对话里。密钥只加密保存在本机。每一笔操作在签名前都要经过签名策略、硬性限额和安全检查（黑名单、制裁名单、交易模拟），有风险的操作会等你确认。DSH 设置里的 Web3 钱包页面负责账户、备份、PIN、限额和黑名单。

目录

• 使用
• 实现原理
• 模型体验
• 已知限制
• 延伸阅读

使用

环境要求

• DSH 0.2.x（bundle 声明了 @deepseek-ai/dsh-typert-protocol 的 peer 版本范围，DSH 在安装和启动时会检查）
• Node.js 20 或更高
• macOS 上使用钥匙串保存口令（其他平台使用 DSH 凭据存储）

安装

dsh plugin --profile web add dsh-web3

也可以在 DSH Web 侧边栏的插件页面安装 dsh-web3。bundle 自带的 cordis.patch.yml 会以 web3 这一行挂载插件；开启 HMR 时（默认的 web profile）立即生效，否则重启 DSH。

然后打开 设置 → Web3 钱包：创建或导入钱包、备份助记词、设置 PIN。

配置

在 profile 的 cordis.patch.yml 里覆盖 web3 这一行，所有字段都可选：

- id: web3
  config:
    vaultPath: ~/.dsh-web3       # 保险库目录（默认 ~/.dsh-web3）
    autoLockMs: 900000           # 闲置 15 分钟后锁定
    passphrase:
      mode: auto                 # auto | env | manual
    secretStore: auto            # auto（macOS 上用钥匙串）| keychain | none
    chains:
      rpc:                       # 按链覆盖 RPC
        1: https://my-eth-rpc.example
      tokens:                    # 额外显示余额的代币
        8453:
          - address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
            symbol: USDC
    disableTools: false          # true = 只提供服务，不注册 wallet_* 工具
    disableHttp: false
    unsafeAllowModelSecretReveal: false   # 不要开启：密钥会进入对话记录

| 环境变量 | 作用 | |---|---| | DSH_WALLET_PASSPHRASE | 保险库口令（env 模式，或口令解析顺序的第一位） | | DSH_WEB3_SECRET_STORE | keychain / none；细化 secretStore: auto | | DSH_WEB3_DENYLIST_REFRESH | 设为 off 时不再每天下载 OFAC / ScamSniffer 地址库（离线机器） |

设置面板

| 标签页 | 功能 | |---|---| | 资产 | 账户与网络切换、收款地址、余额、最近交易、设置提醒 | | 账户 | 创建、导入（助记词 / 私钥 / keystore）、备份、重命名、导出 keystore、删除 | | 安全 | 锁定 / 解锁、PIN、签名前安全检查与地址库状态、黑名单、Agent 权限 | | 限额 | 安全模式（预设）、含今日用量的转账上限、转账白名单与联系人、策略规则 | | 记录 | 带区块浏览器链接的交易记录、审计日志 |

凡是降低保护或涉及密钥的操作——放宽预设或限额、加入白名单、关闭某项安全检查、从黑名单移除地址、查看助记词、导出、删除账户——都需要输入 PIN。收紧设置不需要。

安全模式

| 预设 | 自动签名 | 需要你确认 | |---|---|---| | strict（推荐） | 无 | 全部 | | micropay（新钱包默认） | 商户首次付款之后，≤1 USDC/笔、≤10 USDC/天的 x402 付款 | 其他全部 | | testnet | 测试网上的小额操作 | 主网 | | power | 主网原生币转账，≤0.01/笔、≤0.05/天 | 代币、授权、Permit | | locked | 无（拒绝一切签名） | — |

硬性限额（稳定币和原生币上限、转账白名单）以及严重级别的安全检查发现，即使你在审批框点了同意也会拒绝。

服务 API（ctx.wallet）

其他插件可以使用和工具相同的流程：

const prepared = await ctx.wallet.prepareTransfer({ account: 'main', chainId: 8453, to: 'alice', amount: '25', token: 'USDC' });
// prepared.summary、prepared.security.findings、prepared.willRequire
const result = await ctx.wallet.executePrepared(prepared.preparedId, approvalGateway, { toolName: 'my-plugin' });

await ctx.wallet.checkAddress({ address: '0x…', chainId: 1 });   // 黑名单、制裁名单、相似地址
await ctx.wallet.signTypedData({ account, domain, types, value }, approvalGateway);
await ctx.wallet.authorizeX402({ account, challenge }, approvalGateway);

实现原理

签名流程

prepare  解析收款人 / 代币 / 金额 → 填充 nonce、gas、手续费
         → 解码意图 → 预检（会否回滚、余额）→ 策略试算
         → 安全检查 → 决策升级 → 一次性 preparedId（15 分钟有效）
execute  按账户加锁 → 刷新 nonce / 手续费 → 策略 → 安全复查
         → 保险库锁定状态 + 每日 PIN → 人工审批（`ask` 时）→ 签名
         → 写日志 → 广播

模型只表达意图。收款人标签、代币符号、精度和 calldata 都由钱包解析；预览的内容就是最终签名的内容；一次性 id、幂等键和"广播前先写日志"保证重试安全。

决策

1. 签名策略（policy.json）：allow / ask / deny 规则。会动资产的意图（代币转账、授权、Permit）只有在规则明确列出且未超出逐代币上限时才会自动签名；无限授权永远需要人工确认。
2. 硬性限额（limits.json）：转账白名单以及单笔 / 每日上限，违反即 deny。
3. 签名前安全检查（security.json），并行执行，每项有独立的时间预算：

| 检查 | 能发现什么 | 网络依赖 | |---|---|---| | local | 地址投毒、首次收款人、把代币转给代币合约、把授权或 Permit 给普通钱包、无限授权、期限过长的 Permit、不含 chainId 的签名 | 链 RPC | | denylist | 用户黑名单 + 本地缓存的 OFAC SDN 与 ScamSniffer 地址库（每天更新） | 决策时不联网 | | sanctions | Chainalysis 链上制裁预言机（以太坊、OP、BSC、Polygon、Arbitrum、Avalanche） | 链 RPC | | simulation | eth_simulateV1 模拟结果与解码意图对账：多出的转出、金额不符、隐藏授权、收款后立即转走资金的地址、资金流向黑名单地址 | 链 RPC | | goplus | GoPlus 地址信誉，以及你将收到的貔貅币——默认关闭，开启后会把对方地址和收到的代币地址发给 GoPlus | GoPlus API |

critical 直接拒绝；high 即使规则允许自动签名也会要求人工确认；warn / info 只展示。安全检查只会收紧决策。某项检查没能完成时会生成 SECURITY_CHECK_UNAVAILABLE，它的严重程度由用户的 onUnavailable 设置决定。

密钥与口令

• 密钥文件每个账户一个，用 scrypt + AES-256-GCM 加密，账户 id 绑定进认证标签。
• 保险库口令的解析顺序：DSH_WALLET_PASSPHRASE → macOS 钥匙串 → DSH 凭据存储；auto 模式下首次使用时生成 32 字节随机口令。在明文凭据文件里找到的口令会被迁移进钥匙串。
• 每日 PIN 以 scrypt 哈希保存，并用存放在钥匙串里的 pepper 加固。
• 工具永远不返回助记词、私钥或 PIN；备份在设置面板里完成。

文件（保险库目录）

vault.json（账户元数据，不含密钥）· keys/<id>.json（加密密钥，0600）· policy.json · limits.json · security.json · denylist.json · denylist-feeds.json · address-book.json · tx-journal.json · spend-state.json · pin.json · audit/audit-<date>.jsonl。policy.json、limits.json、security.json、denylist.json 损坏时保险库拒绝打开，而不是悄悄丢掉保护。

对外接口

• ctx.wallet——服务（src/service.ts）。
• 注册在 ctx.tools 上的 wallet_* 工具（src/tools.ts）。
• 设置面板使用的 Typert Remote 命名空间 web3/*（src/remote.ts、client/client.js）。
• 存在 http 服务时，挂载在 /api/dsh-web3/* 下的只读 HTTP 接口。
• 通过 ctx.skills.registerProvider 提供的 dsh-web3-wallet skill。

模型体验

钱包工具

模型看到什么

30 个 wallet_* 函数工具，主要的有：

| 工具 | 用途 | |---|---| | wallet_status、wallet_list、wallet_balance、wallet_chains | 状态、账户、余额、支持的链与代币符号 | | wallet_transfer → wallet_send_transaction | 用人类单位转账（amount: "25"、token: "USDC"）；dryRun 预览，凭 preparedId 执行 | | wallet_prepare_transaction、wallet_approve_token、wallet_allowance | 合约调用与 ERC-20 授权，解码为意图 | | wallet_sign_message、wallet_sign_typed_data、wallet_x402_authorize | EIP-191 / EIP-712 签名与 x402 exact 付款 | | wallet_tx_status、wallet_history、wallet_replace_transaction | 交易状态、本地历史、加速 / 取消 | | wallet_security_check、wallet_denylist | 付款前检查地址；拉黑地址（移除只能在面板） | | wallet_policy_get、wallet_policy_set | 读取策略与限额；只能收紧 | | wallet_address_book、wallet_create、wallet_import、wallet_remove_account、wallet_export_keystore、wallet_reveal_secret、wallet_pin_status、wallet_pin_verify、wallet_unlock、wallet_lock、wallet_audit_log | 联系人、账户管理、备份指引、门禁状态、审计 |

结果都带 status、next 提示和结构化的 security.findings；失败统一为 { ok: false, code, message, hint }，错误码稳定。在 DSH 聊天里，每次调用都会显示原生工具卡片，例如 25 USDC → 0x7099…79C8 · Base。

Token 影响

插件加载期间，工具声明会给每次请求增加约 18,000 字符（约 5–6 千 token）。每次调用会追加它的 JSON 结果；带模拟的预览最大，通常 1–3 千 token。

KV Cache 影响

工具声明是静态的，会和其余工具列表一起被缓存。安装、移除或禁用插件会改变工具列表，使缓存前缀失效一次。

内置 skill

模型看到什么

dsh-web3-wallet skill 在会话的 skill 目录里只占一行（约 350 字符，含中英文触发词），把钱包、转账、代币、签名、x402 和钱包策略相关请求路由到 wallet_* 工具，优先于 shell 脚本或其他钱包 skill。加载后得到完整操作手册：意图路由、铁律、标准流程、状态处理，以及如何转达安全检查结果。

Token 影响

目录里的一行始终存在；skill 正文（约 11,000 字符）只在模型加载时才进入上下文。

KV Cache 影响

目录行是静态的。加载后的 skill 正文像普通工具结果一样追加到对话中。

已知限制

• 同用户边界。 以你的系统用户身份运行的任何程序——包括拥有不受限 shell 权限的 Agent——都可以无提示地从登录钥匙串读出保险库口令并解密密钥文件。请把它当作只放小额资产的热钱包，并且不要在使用它的会话里给 Agent 不受限的 shell 权限。
• 策略、限额和安全检查只对经过本插件的签名生效；密钥一旦被盗，这些保护都会被绕过。
• 暂不支持硬件钱包和智能账户（会话密钥）。
• 威胁情报仅限 OFAC、ScamSniffer、制裁预言机和可选的 GoPlus。
• 部分 RPC（例如 Avalanche 官方公共节点）不支持 eth_simulateV1，在这些链上预览会注明没有进行模拟。
• 代码尚未经过外部安全审计。

发现漏洞请按 SECURITY.md 私下报告。

延伸阅读

• dsh-web3-core——本插件依赖的保险库、策略、意图解码、模拟与黑名单库。
• 钱包设计文档——功能地图、威胁模型和变更记录。
• 内置 skill——模型加载的操作手册。
• 更新日志

许可证

MIT