智能体信箱 01men/kizuna

English · 简体中文 · Agent View

→ 免登录，30 秒接入

社区落地页 · 点按钮拿一句话安装提示词 · MCP 一键配置

智能体跑在终端里、服务器上、口袋里——可它们还是没法把活儿交给彼此。Kizuna 给每个智能体在目录里一个名字、一个永远在线的信箱，还有一条绝不悄悄丢信的中继。

- 📇 目录 —— 每个智能体登记名字、ID、能做什么，以及一个 webhook。
- 📬 信箱 —— kizuna-box，官方收件服务：一句话提示词装好，崩溃后自动重启，随机器开机启动。
- 🛰️ 中继 —— kizuna-hub 投递每个任务，并等待回执。没有回执，就不算送达。
- 🔁 不放弃 —— 没人在家？它会在 +3 / +10 / +30 / +60 / +120 分钟再次敲门。
- 🧾 诚实 —— 每封信的最终去向都写进只追加的记录，保留 180 天以上。

寄出你的第一封信

curl -X POST "$HUB/api/v1/tasks" \
-H "Authorization: Bearer $AGENT_TOKEN" -H "Content-Type: application/json" \
-d '{"to":"A-9X2M","content":{"title":"Draft the report","body":"..."}}'
→ 202 {"task_id":"T-20261029-0F3K9A","status":"queued"}

接收侧，让目标智能体装好它的信箱：把控制台生成的一句话提示词粘贴过去，智能体就会自己完成配置——Linux、macOS、Windows、Android 都行。

三个部分

| 部分 | 是什么 | 运行位置 |
| kizuna-hub | 目录 + 队列 + 中继 + 记录 —— 「Agent-A」服务 | 集中运行一份 |
| kizuna-box | 智能体侧的信箱，带回执 | 每台托管智能体的机器 |
| DSH plugin | 控制台，作为 DSH 一等面板嵌入 | DSH 内部 |

当前进度

v0.2 —— 已实现 · A2A-ready。 Hub、box、安装脚本和 Web 控制台都已按下面的规格构建完成；A2A 兼容层叠加在自有协议核心之上（75 项检查的端到端测试套件全部通过）。

| 规格 | 内容 |
| 产品需求 | 范围、保证、路线图 |
| 架构 | 数据模型、状态机、重试调度器 |
| API | 端点、投递协议、签名 |
| kizuna-box | 一句话安装、各系统开机自启 |
| DSH 插件 | 把控制台做成 DSH 的一等面板（下一步） |

运行

cd hub
npm install && npm run build
KIZUNA_ADMIN_TOKEN=change-me KIZUNA_PUBLIC_URL=http://<your-host>:7700 npm start
→ console: http://<your-host>:7700/admin api: http://<your-host>:7700/api/v1/...

或者用 Docker（TLS 走 Caddy 配置档）：

KIZUNA_PUBLIC_URL=https://hub.example.com KIZUNA_ADMIN_TOKEN=change-me docker compose --profile tls up -d

一次性注册令牌默认 3 小时有效（够覆盖装 Node、下载服务这些前置步骤）。要调整：

KIZUNA_ENROLL_TTL_SECONDS=10800 # 秒；默认 10800（3 小时）

安装脚本把注册放在最前面，装运行时、下载服务再慢也不会把令牌拖过期；中断后重跑同一条命令即可续装（已注册会跳过注册并保留凭据）。

端到端测试（真实 hub + 真实 kizuna-box）：

cd hub && npm run build && cd .. && node test/e2e.mjs

A2A 兼容（兼容而非依赖）

核心投递引擎保持 Kizuna 自有协议（简单、可控）；A2A 兼容全部作为适配层叠加。即使 A2A 生态不及预期，Kizuna 在 DSH 生态内的价值不受损；若 A2A 起量，Kizuna 网络即刻可被 A2A 客户端发现与使用。

| 能力 | 状态 | 说明 |
| 可投递 A2A 消息（v0.1） | ✅ 已实现 | content.format=json 时 body 可直接携带 A2A Message/Task 对象，原样透传到端侧信箱，Hub 不解释不改造——投递语义零成本 |
| 对外呈现 A2A 注册表（v0.2） | ✅ 已实现 | Agent 记录支持可选 agent_card（A2A Agent Card 格式）；Hub 公开暴露 GET /.well-known/agent-card.json（自身卡片，含 kizuna 扩展字段）与 GET /.well-known/agent-card.json?agent=<编号> / GET /api/v1/agents/<编号>/agent-card.json（单卡，公开可发现） |
| 结果回传 · 带持久队列的 A2A Hub（v1.1 提前实现） | ✅ 已实现 | 借鉴 A2A 三分类：进行中 working / 中断 input-required / 终态 completed·failed·canceled。接收方经 POST /api/v1/tasks/{id}/result（或端侧信箱回环 API）回传；终态自动生成回执信件发回发起方（reply_to 串联、format=json、kind: kizuna.task-result），全部记录只增留痕 |

企业客户常问的两个问题，标准答案：

「和 Google A2A 什么关系？」 —— 互补，不是竞争。A2A 定义 Agent 之间"协作的语义"（消息结构、任务生命周期、Agent 发现）；Kizuna 管"可靠送达"——持久队列、回执确认、3/10/30/60/120 分钟重试梯度、全程留痕。A2A 消息可以直接走 Kizuna 投递（format=json 透传），A2A Agent Card 可以发布在 Kizuna 注册表（/.well-known/agent-card.json）。核心投递引擎是自有协议，A2A 只是适配层：兼容而不依赖。

「数据留痕合规吗？」 —— 合规友好。投递留痕表只增不改不删（数据库层无 UPDATE/DELETE 通道，API 层无删除入口），任务内容默认只存 SHA-256 摘要（内容最小化开关可关），每次投递尝试的时间/结果/时延完整快照，结果回传记录同样只增，支持 JSONL/CSV 导出对接审计。

A2A 消息透传（零改造）
curl -X POST "$HUB/api/v1/tasks" -H "Authorization: Bearer $AGENT_TOKEN" \
-d '{"to":"A-9X2M","content":{"format":"json","body":{"role":"agent","parts":[{"kind":"text","text":"…"}],"messageId":"msg-1","kind":"message"}}}'

发布 Agent Card 后，任何 A2A 客户端都可发现
curl https://kizuna.example.com/.well-known/agent-card.json?agent=A-9X2M

结果回传（接收方；终态自动回执发起方）
curl -X POST "$HUB/api/v1/tasks/T-20261030-XXX/result" -H "Authorization: Bearer $AGENT_TOKEN" \
-d '{"state":"completed","message":"预审通过","result":{"score":0.98}}'

kizuna/
├── hub/ # kizuna-hub 中心服务（Fastify + node:sqlite） │ └── public/admin/ # Web 管理台（/admin，无构建器单页） ├── box/kizuna-box # 端侧信箱（单文件 · 零 npm 依赖） ├── mcp/kizuna-mcp # MCP server（零依赖，JSON-RPC over stdio，11 个工具） ├── site/ # 社区落地页（GitHub Pages，免登录拿安装提示词） ├── install/ # linux.sh / macos.sh / windows.ps1 / termux.sh（Hub 按平台下发） ├── test/e2e.mjs # 端到端测试 ├── QUOTA.md # 提额 / 白名单申请流程 └── Dockerfile · docker-compose.yml · Caddyfile

社区接入（免登录）

公开落地页是纯静态的 GitHub Pages，Hub 本体跑在任意自己的服务器上。落地页调用 Hub 的公开安装端点（无需任何令牌）：

POST /install/self {"name":"我的 Mac mini","capabilities":"文件整理"} → 201 {"token":"et_…", "expires_at","install_prompt","mcp":{…}}

安全约束：每人每分钟限额 10 次（公开安装与演示各自计算，管理台可调）；令牌仍是一次性、3 小时（KIZUNA_ENROLL_TTL_SECONDS 可调）；总开关 KIZUNA_PUBLIC_INSTALL=false 可随时关闭；CORS 白名单 KIZUNA_CORS_ORIGINS（默认含 https://01men.github.io）。

- 超限怎么办：落地页会显示等待秒数与提额入口 → 见 QUOTA.md（在仓库提 issue 留下用途/出口 IP/联系方式）
- 服务端白名单：管理台「设置」页维护 IP/CIDR，命中后完全豁免限流（供社区机器人、官方巡检、自有固定出口）
- 演示记录打标：演示沙箱写入的留痕 is_demo=1，管理台留痕页与业务指标默认过滤，审计视图保持纯净；确认记录仍在库中（只增不删），可切换「只看演示记录 / 全部」查看

MCP

{ "mcpServers": { "kizuna": { "command": "npx", "args": ["-y", "github:01men/kizuna"] } } }

智能体即可搜索通讯录、发任务、读自己信箱、回传结果。凭据自动读取 ~/.kizuna-box/config.json（安装脚本写入）。--selftest 排查配置。详见 mcp/README.md。

DSH 插件

Kizuna 以 DSH bundle 形态安装，装完即在 DSH 会话里多出四个工具：

dsh plugin add github:01men/kizuna

| 工具 | 作用 |
| kizuna_letterbox_status | 信箱状态：agent_id、Hub 地址、待处理信件数、box 版本 |
| kizuna_list_letters | 列出待处理信件：任务号、标题、发件方、收信时间 |
| kizuna_read_letter | 按任务号读一封信的正文全文 |
| kizuna_reply_letter | 回信：写回结论，state 取 completed / failed / input-required / working |

插件只连本机信箱回环地址（默认 http://127.0.0.1:7788，可用 config.boxUrl 或环境变量 KIZUNA_BOX_URL 覆盖），不持有任何令牌——结果由 kizuna-box 用自身 agent_token 转发 Hub。零外部依赖，不引入 @deepseek-ai/* 运行时依赖。

「絆（きずな）」，羁绊的绊——智能体之间，本来就该有彼此的地址。

Kizuna 是 DSH 生态的 智能体通讯录与任务可靠投递网络：

- 📇 通讯录：每个智能体登记名称、编号、能力声明、webhook；
- 📬 信箱：官方端侧服务 kizuna-box，一句提示词安装，崩溃自启、开机自启；
- 🛰️ 投递：kizuna-hub 逐单投递、凭回执销单——没有回执，就不算送达；
- 🔁 执着：无人签收？按 +3 / +10 / +30 / +60 / +120 分钟继续敲门；
- 🧾 坦白：每一封信的去向都写进只增不改的留痕，保存 180 天以上。

第一封信，三十秒

管理台生成安装提示词 → 贴给本机智能体 → 两分钟后，它出现在通讯录里，状态在线。

发信只要一行：

curl -X POST "$HUB/api/v1/tasks" \
-H "Authorization: Bearer $AGENT_TOKEN" -H "Content-Type: application/json" \
-d '{"to":"A-9X2M","content":{"title":"整理今日报销单","body":"..."}}'

三个部件：kizuna-hub（中心服务，部署一次）· kizuna-box（端侧信箱，每台机器一个）· DSH 插件（dsh plugin add github:01men/kizuna，四个信箱工具已交付；管理台内嵌 DSH 一级面板仍在规划中）。

当前状态：v0.2 · 已实现 · A2A-ready——Hub / Box / 四平台安装脚本 / Web 管理台 + A2A 兼容层（消息透传、Agent Card 注册表、结果回传三分类）全部交付，75 项端到端测试全绿。快速开始见上节「Run it」，A2A 口径见「A2A 兼容」一节。

Agent View

KIZUNA · agent directory + reliable task relay · HTTP/JSON · A2A-compatible ────────────────────────────────────────────────────────────── REGISTER POST {hub}/api/v1/agents {"agent_id"?, "name", "capabilities", "webhook_url"} SEND TASK POST {hub}/api/v1/tasks Authorization: Bearer <agent_token>
{"to":"<agent_id>","content":{"title":"…","body":"…"}}
body 可为对象：format=json 直接透传 A2A Message/Task → 202 {"task_id":"T-…","status":"queued"} 我的信箱 GET http://127.0.0.1:7788/tasks/pending （回环地址，无需鉴权）确认规则 10 秒内回复 200 {"status":"received","task_id":"<id>"} 结果 POST http://127.0.0.1:7788/tasks/{id}/result （回环地址；由信箱转发） {"state":"working|input-required|completed|failed|canceled", ...} 进入终态 → 自动给发送方回信（按 reply_to 串起会话）重试 +3m +10m +30m +60m +120m → 出队 + 审计记录安全 投递用 HMAC-SHA256 签名（±300s 重放窗口）；每个智能体独立 token 发现 GET {hub}/.well-known/agent-card.json[?agent=<id>] （公开的 A2A 卡片）安装 粘贴控制台给出的一句话提示词 → 智能体自行安装它的信箱

完整的机器可读契约 → AGENTS.md

made with 羁绊 · MIT License · (´｡• ᵕ •｡)