Haven-hvn/deepseek-harness-web3-agent-stack

dsh-web3

快速开始

一次性入门（构建最新的 02ca906 技术栈、测试、启动 xmtp-prod、输出二维码 + 钱包）：

bash quickstart.sh
或：MUSE_SPARK_API_KEY= bash quickstart.sh

输出 Invite URL: https://popup.convos.org/v2?i=... + ANSI 二维码（qrencode -t ANSIUTF8）以及钱包 0xa85dD3FbD8C2c831Ef156036F14638CcFf03b44e（动态 wallet_info→ctx.wallet.address）。也可使用：./show-convos-qr.sh / ./show-xmtp-qr.sh 仅显示二维码。

使用 DeepSeek harness 作为核心、一切皆为插件的自主 web3 代理 harness 的重新实现。取代 https://github.com/Haven-hvn/haven-core 和 https://github.com/Haven-hvn/haven-adapters

这里刻意没有聚合包：人们可能只想要某一项能力
而不想要另一项，因此每个包都自带 dsh.bundle.patch →
cordis.patch.yml，只插入自己的行，并独立安装：

dsh plugin --profile  add /path/to/dsh-haven/

各软件包

| 软件包 | Haven 概念 | 它所落到的 dsh 接缝 |
| --- | --- | --- |
| dsh-wallet | WalletIdentity 托管（“密钥永不离开此边界”）+ CryptoAdapter 契约 | ctx.wallet 服务；凭据按每次操作通过 ctx.credentials 解析——配置携带的是引用，绝不是密钥 |
| dsh-wallet-ethereum | EthereumCryptoAdapter → OWS 迁移计划 | 提供者插件，按链族注册一个 CryptoAdapter，由 @open-wallet-standard/core 支持（仅签名；该标准处理所有链族） |
| dsh-treasury | Treasury 机器：余额、支出、FUNDED/LOW/CRITICAL/DEPLETED 生存梯度 | 存储域表 + 派生状态；一个策略插件对 agent/request 和 tools/pre-execute 进行短路，并从 llm/token-meter 计量 |
| dsh-channel-xmtp | XmtpChannel 代理↔用户直接消息传递 | 每个会话一个 dsh 代理（ctx.agents），入站通过 agent.followup，回复通过 sendText；EOA 身份通过 ctx.wallet 签名 |
| dsh-storage-synapse | SynapseStorageAdapter + StorageBackend 固定 | ctx.synapse + synapse_pin / synapse_pin_status 代理工具；每个节点请求按每次操作由钱包签名 |
| dsh-wallet-tools | 钱包地址/余额暴露（取代硬编码人设） | 通过 ctx.tools + ctx.wallet.address() 实时提供 wallet_info 工具（无硬编码 0x...） |
| dsh-persona | Haven 人设 / 系统指令 | agent/request 组合；当被询问地址/余额/资金时调用 wallet_info 的通用指令 |

组合

dsh-wallet 是托管根；其他软件包构建于其上：

dsh-wallet  ←  dsh-wallet-ethereum   （注册 evm CryptoAdapter）
↑
├── dsh-channel-xmtp             （按每次签名签署 XMTP 身份）
├── dsh-storage-synapse          （按请求对节点请求进行签名）
└── dsh-wallet-tools             （通过 ctx.tools → ctx.wallet 暴露 wallet_info）
dsh-persona                           （组合 agent/request；调用 wallet_info，无硬编码地址）
dsh-treasury                          （独立；需要存储栈）

一个典型的完整安装：

dsh plugin --profile  add \
/path/to/dsh-haven/dsh-wallet \
/path/to/dsh-haven/dsh-wallet-ethereum \
/path/to/dsh-haven/dsh-treasury \
/path/to/dsh-haven/dsh-channel-xmtp \
/path/to/dsh-haven/dsh-storage-synapse \
@open-wallet-standard/core @xmtp/node-sdk

这两个 SDK 是可选的同级依赖：每个包在没有它们的情况下都能加载、挂载和测试
（惰性导入并带有可操作的错误；测试会替换
internals. 接缝）。

先决条件

- 存储栈（仅 dsh-treasury）：profile 必须挂载 storage、
storage-json/storage-sqlite 和 storage-domain 行（存在于
dsh-web-app 中；在 dsh-base 中不存在）。treasury 补丁不会插入
它们——由两个层插入的行 id 会导致插件被挂载两次。
- Agent 栈（仅 dsh-channel-xmtp）：agents/sessions/llm，存在于
任何运行 agent 的 profile 中。
- inject 列表未满足的插件会保持休眠而不是失败，因此
安装顺序是自由的。

设计决策：隔离的 bundle，耦合的接缝

Web3 插件作为代码是隔离的，在接缝处耦合——这是 DeepSeek harness 如何组合的
直接结果。

隔离——每个包都是一个独立的 Cordis 插件（export const name、
export const inject、export function apply(ctx, config)），拥有自己的
dsh.bundle.patch → cordis.patch.yml。没有聚合 bundle；dsh plugin add
一次安装一个能力，并且 inject 顺序是自由的（未满足的 inject 保持
休眠）。这就是为什么 dsh-wallet、dsh-channel-xmtp、dsh-storage-synapse、
dsh-treasury 和 dsh-wallet-tools 各自通过 prepare（tsdown → lib/）构建，并在
没有其他包的情况下测试（internals. 接缝）。

在接缝处耦合——如果没有声明的契约，隔离就会被破坏：
ctx.wallet（托管）、ctx.tools（面向模型的工具）、ctx.agents/ctx.sessions
（按对话的 agent）、ctx.synapse/ctx.treasury（存储）。插件通过
inject 声明这一点——例如 dsh-wallet-tools 和
dsh-storage-synapse 中的 inject = ['wallet','tools']——因此它们仅在接缝存在时挂载，并按操作
调用它（ctx.wallet.address()、ctx.wallet.signMessage()、ctx.tools.register(defineTool(...))）。

迫使这种形态的 harness 限制：
1. 单例工具运行时。 @deepseek-ai/dsh-tools 暴露一个调度器（ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare）。如果两个实例被错误地去重，Symbol 就会不匹配，每个 tool/call 都会失败并报错 Cannot read properties of undefined (reading 'prepare')。因此，各 bundle 将 dsh-tools 作为 peer 依赖（==0.1.0-rc.7），并且 link: 安装必须去重为一份副本。

2. 钱包托管是按操作进行的。 配置只携带 keyRef/wallet 名称；ctx.credentials.resolve 在 signMessage/address 内部运行，随后即被丢弃。消费者（dsh-channel-xmtp 中的 XMTP 身份、dsh-storage-synapse 中按请求的 x-synapse- 头、dsh-wallet-tools 中的 wallet_info）只能看到地址/签名。在 persona 中硬编码地址（When asked for address, answer with 0x...）会破坏轮换和与钱包无关的安装——正确的接缝是一个实时解析 ctx.wallet.address(config.wallet) 的工具。

3. Channel 是按会话的，而不是按进程的。 dsh-channel-xmtp 为每个 XMTP 会话创建一个 ctx.agents 会话（SessionId 由 conversationId 派生），在 getConversationById 之前处理 conversations.sync()、重连/同意清扫以及去重。Channel 拥有传输；agent 拥有回合。

结果：添加一次 dsh-wallet，然后组合任意子集。dsh-wallet-tools（wallet_info 工具，presentCall: {kind:'read'}）使 EVM 地址可被模型访问，而无需 persona 捷径；dsh-channel-xmtp 使其可通过 XMTP 访问；dsh-storage-synapse 使其可通过存储访问——全部通过 ctx.wallet，没有一个是通过共享密钥材料实现的。

托管模型（贯穿主线）

Haven 的规则——私钥永不离开其所在层；其他一切请求签名——映射到此处到处使用的一种 dsh 模式：

1. 配置携带名称和凭据引用（keyRef、dbEncryptionKeyRef）。粘贴的原始密钥会在插件加载时大声失败，因为密钥材料在语法上不可能是 CredentialRef。
2. 密钥只存在于单个操作内部：ctx.credentials.resolve 按调用运行，提供者签名，所有引用都被丢弃。轮换会在下一个操作立即生效，无需重启。
3. 消费者（XMTP 签名者、Synapse 请求、未来的 channel）只能通过 ctx.wallet 看到地址和签名。

开发

pnpm install       # workspace of five packages
pnpm vitest        # specs live in /tests/*

每个包都通过 prepare（tsdown → lib/）自包含构建，因此 git 或路径安装无需 monorepo 上下文即可工作。金额数字全程为整数 µUSD（USD × 1e6），与 haven-core 一致。