Skip to content

AGENT-DEPLOY.md

Latest commit

 

History

History
144 lines (106 loc) · 7.94 KB

AGENT-DEPLOY.md

File metadata and controls

144 lines (106 loc) · 7.94 KB
Raw

dsh-agent-relay — DSH 自主部署任务书

本文档是给 DSH（DeepSeek Harness）的部署 prompt，不是给人看的教程。 首次安装 dsh-agent-relay 插件后，DSH 必须完整阅读本文档，并亲自完成部署操作。 部署采用 Agent 驱动方式：由你（DSH）完成 broker 初始化、启动、Agent 接入与验证。不要依赖"复制粘贴"的手动流程，也不要让用户自己敲命令。

0. 你的角色与任务

你是部署执行者。任务：把多 Agent 协作中继（dsh-agent-relay）部署到本机，让各 Agent（dsh / Codex / Claude / Hermes / 其他）能经 broker 安全互发消息。

  • 你负责：初始化配置与密钥、启动 broker、接入各 Agent、验证闭环。
  • 只动与 relay 相关的文件与配置；不改动各 Agent 的其他配置、会话历史、技能文件。
  • 完成标准见第 3 节验证清单，全部满足才算完成。

1. 前置信息（先解析，禁止猜测）

1.1 两种部署模式

模式 适用 说明
单机（默认） 本机多 Agent broker 与 Agent 同机，全回环 127.0.0.1:19121，零网络暴露
分布式（进阶） 多台机器 一台服务器 + 各机器 Agent；必须 TLS，secret 分发要谨慎

1.2 部署决策（能从环境推断就用默认，不能推断才向用户确认，一次问完）

  1. 模式：默认单机回环；用户要跨机器才选分布式。
  2. broker host/port：默认 127.0.0.1:19121；改端口只需改 broker/config.yaml。
  3. 接入哪些 Agent：默认接入已检测到的（dsh 插件 / CLI 客户端 / Python 客户端），检测不到的不接。

1.3 可用组件（npm 包已自带全部，无需 git clone）

组件 位置 用途
broker <包目录>/broker/ 零依赖 Node 中继服务（HMAC 认证 / JSONL 存储 / HTTP 服务）
setup <包目录>/setup/ setup.js：init（生成密钥+配置）/ start（启动）/ selfcheck（验证）
dsh 插件 <包目录>/lib/ relay_send / relay_recv / relay_peers / relay_history 模型工具
CLI 客户端 <包目录>/adapters/cli/relay.mjs 脚本 / Codex / Claude 包装用
Python 客户端 <包目录>/adapters/hermes/relay_client.py 纯标准库，Hermes 风格接入

路径注意：<包目录> = 你（DSH）能找到本插件包的位置。若是 npm 安装，通常在 <profile>/node_modules/dsh-agent-relay/；若是 git clone，就是仓库根目录。用实际解析结果，不要假设。

2. 部署流程（按顺序执行，一步一验）

Step 0 读任务书、定模式

  • 完整读完本文档。
  • 确认模式（1.2）：单机回环（默认）还是分布式。
  • 记录 <包目录> 与决定。

Step 1 确认组件就位

  • 检查 <包目录>/broker/src/index.js、<包目录>/setup/setup.js、<包目录>/lib/index.js 存在。
  • 缺失 → 说明包不完整，改用 git clone https://github.com/Noelune/dsh-agent-relay.git 后重试。

Step 2 生成配置与密钥

  • 运行 node <包目录>/setup/setup.js init。
  • 生成 broker/config.yaml，内含一个随机 64-hex 密钥。绝不提交、不外泄、不写入任何日志。
  • 若已存在 config.yaml：保留，直接复用其中的 secret（幂等）。

Step 3 启动 broker

  • 前台启动：node <包目录>/setup/setup.js start（会按 config.yaml 绑定）。
  • 或后台/容器：见 docs/DEPLOY.md 的 Docker 小节。
  • 启动后验证：node <包目录>/setup/setup.js selfcheck → all checks passed。
  • 单机模式：确认 broker 绑定 127.0.0.1（config.yaml host: 127.0.0.1），不要改成 0.0.0.0 除非后面有 TLS。

Step 4 接入 Agent

  • dsh（插件）：
    • dsh plugin --profile web add dsh-agent-relay
    • 配置共享密钥：DSH_RELAY_SECRET=<config.yaml 里的 secret>（环境变量或插件设置），以及稳定的 DSH_RELAY_AGENT=<名字>。
  • CLI 客户端（脚本 / Codex / Claude 包装）：
    • node adapters/cli/relay.mjs register --agent alpha --secret <secret>
    • 用 peers 确认上线。
  • Python 客户端（Hermes 风格）：
    • from relay_client import RelayClient; client = RelayClient(broker_url="http://127.0.0.1:19121", agent="beta", secret="<secret>"); client.register()
  • 每个接入的 Agent 名字要稳定唯一；重启后重新 register（心跳续期）。

Step 5 验证闭环

  • node <包目录>/setup/setup.js selfcheck → all checks passed。
  • 端到端：两个 Agent 互发一条消息，接收方 recv 能取到（node adapters/cli/relay.mjs send <b> "hello" --agent <a> --secret <s>，再 recv）。
  • 若接了 dsh 插件：确认 relay_peers 工具能看到已注册 Agent。

Step 6 汇报

按第 4 节格式输出部署报告。

3. 验证清单（Definition of Done，全部满足才算完成）

  • broker/config.yaml 存在，含 ≥32 位随机 secret，且未被纳入版本控制。
  • broker 启动，selfcheck 全部 ok（config 有效 / broker 可达 / 插件模块加载）。
  • 至少两个 Agent 注册成功，peers 能看到它们。
  • 一条消息端到端送达（发送方收到 accepted:true，接收方 recv 取到）。
  • （v1.1 租约）接收方用 pull 取到消息 → 处理完成后 ack completed → 状态变 done；retry 会 attempts+1 并重新入队。
  • 单机模式 broker 绑定回环地址；未向公网暴露明文端口。
  • 未在任何日志、配置、汇报中出现 secret 明文以外的敏感信息。
  • 消息内容仅存于 broker 的 TTL 限定期限投递队列（JSONL，默认 7 天清理），绝不写入应用日志；插件只记内存 id 级历史。

4. 汇报格式（部署完成后输出）

## 部署完成报告

**模式**：单机回环 / 分布式
**broker**：<host>:<port>（config.yaml 路径）
**密钥**：已生成/复用（长度 <N> hex，绝不回显）

| Agent | 接入方式 | 注册名 | 验证 |
|---|---|---|---|
| dsh | 插件 | <agent> | ✅/❌ |
| CLI | adapters/cli | alpha | ✅/❌ |
| Python | adapters/hermes | beta | ✅/❌ |

**selfcheck**：全部 ok / 列出失败项
**备注**：未满足的清单项、需要用户确认的事项（如分布式服务器、端口占用）、下一步（重启各 Agent 会话使插件生效）

5. 防坑清单（常见问题，执行前先过一遍）

  1. 密钥即凭据：broker/config.yaml 含共享密钥，绝不提交版本库、绝不进日志/汇报。分布式部署用带外方式（密码管理器/密封信封）分发。
  2. 单机默认回环：broker 默认 127.0.0.1。绝不要把明文 broker 暴露到公网——HMAC 只防伪造不防窃听。
  3. 分布式必须 TLS：跨机器部署时，broker 保持回环绑定，用反向代理（nginx/Caddy）终结 HTTPS，再转发到 127.0.0.1:19121。
  4. 端口占用：19121 被占用时报错——改 broker/config.yaml 的 port，并同步各 Agent 的 DSH_RELAY_BROKER_URL。
  5. Agent 名字稳定唯一：接入时用固定名字，避免每次随机。
  6. 幂等反复部署：config.yaml 已存在时保留复用；重复 register 无害（心跳续期）。
  7. Windows：路径用 C:/ 或 C:\ 形式；Node ≥ 20；不要在 shell heredoc 里拼多行配置。
  8. 不碰无关配置：各 Agent 的其他配置、会话历史、技能文件不在本任务范围。
  9. 无法满足的项：任何一步遇到障碍（端口被占、权限不足、包不完整），停下来在汇报里说明，不要绕过或降级完成。

6. 与 unified-agent-memory 的关系

dsh-agent-relay 只负责消息中继，不存记忆。共享记忆请用 unified-agent-memory（Obsidian vault 为最高事实源）。 两者可同时部署：relay 让 Agent 互发消息，unified-agent-memory 让它们共享事实。