# 01 · 产品需求文档（PRD）

> 产品：Kizuna · Agent 通讯录（Agent Directory）
> 版本 v0.1 · 2026-10-29 · 作者：产品组 · 状态：评审中
> 关联文档：02-技术架构设计 / 03-API规范 / 04-端侧Agent服务设计 / 05-DSH插件与管理界面设计

## 1. 背景与问题

Agent 生态正在快速铺开：一个用户手上往往同时存在多个 Agent——DSH 会话、CLI Agent、自动化 Bot、跑在办公室电脑/服务器/手机上的 Agent。但它们彼此**互不相识、无法互相派活**，缺三样东西：

1. **一本通讯录**：不知道有哪些 Agent、各自能干什么（能力声明）、怎么联系上（webhook）；
2. **一条可靠投递通道**：任务发出去了，对方到底收没收到？没收到怎么办？没有任何保障与记录；
3. **一个端侧接收器**：对方 Agent 身边没有一个稳定在线、开机即有、跨平台的 webhook 接收服务。

本产品把这三件事做成一套基础设施。

## 2. 产品定位与目标

- **定位**：DSH 生态的 Agent 基础设施——「通讯录 + 任务可靠投递」。
- **类比**：把「给某个 Agent 派个任务」做成「寄快递」：登记地址 → 下单 → 签收回执 → 未签收按节奏重投 → 全程物流可查。
- **北极星指标**：任务包投递签收成功率（目标 ≥ 99.9%，不含最终确认失败的目标不可达场景）。

### 用户与角色

| 角色 | 是谁 | 核心诉求 |
| --- | --- | --- |
| Agent（发起方/接收方） | 机器用户（DSH 会话、CLI Agent、Bot） | 通过 API 提交任务包、接收任务包并回执 |
| Agent 拥有者 | 人 | 一句提示词把端侧服务装好装稳；查自己 Agent 的投递情况 |
| 管理员 | 人 | 通过中心服务管理界面运营：通讯录维护、队列监控、留痕审计、端侧安装分发 |

## 3. 核心概念（术语表）

| 术语 | 定义 |
| --- | --- |
| **Kizuna Hub（路由 Agent-A）** | 本产品中心服务：路由字典 + 任务队列 + 投递调度 + 回执确认 + 重试 + 留痕 + 管理界面 |
| **路由字典** | Agent 登记表，四要素：**名称、编号、能力声明、webhook**；编号全局唯一 |
| **任务包** | 一条待投递任务：**来自谁、任务内容、给谁**（外加任务编号、创建时间、优先级等元数据） |
| **任务队列** | Hub 内持久化队列，存放已受理、尚未确认签收的任务包 |
| **回执（ACK）** | 端侧收到任务包后返回的「接收状态信息」；本产品约定：HTTP 2xx 且响应体 task_id 与投递一致 = 签收 |
| **重试梯度** | 未获回执时按 **+3min / +10min / +30min / +60min / +120min** 间隔重投（共 5 次重试，连同首投合计 6 次尝试），全部失败亦出队 |
| **投递留痕** | 任务包**每次出队**（签收成功 / 最终失败 / 目标无效 / 人工取消）都必须生成的不变记录，注明**任务传递状态**与全部尝试历史，只增不改 |
| **Kizuna Box** | 端侧常驻 webhook 接收服务（Agent-B 的「信箱」），本产品官方提供 |
| **安装提示词** | 一段可直接贴给本机 Agent 的提示词，Agent 据此自助完成端侧服务的安装、注册、自启与自检 |
| **DSH 插件** | 管理界面在 DSH 中的形态：侧栏一级入口 + 整页主面板 |

## 4. 需求清单

### FR-1 路由字典（Agent 登记）

登记每个 Agent 的四要素：**名称、编号、能力声明、webhook**。

- 编号全局唯一：支持系统自动分配（如 `A-7K3Q`）或自定义字符串，冲突时拒绝；
- 能力声明：自由文本 + 可选结构化标签（如 `["翻译","报关单证"]`），支持按关键词/标签检索；
- 每条记录附带上下线状态（由端侧心跳驱动，见 FR-6），仅作展示与参考，不影响投递；
- 支持 CRUD 与启停：停用后不再受理指向该 Agent 的新任务包（提交即报错），已在途任务照常走重试/留痕流程。

**验收要点**：重复编号被拒绝；删除/停用 Agent 后，指向它的任务提交返回明确错误；能力关键词检索能命中对应 Agent。

### FR-2 任务队列与投递

- 任务包三要素：**来自谁**（发起 Agent）、**任务内容**（title/body/format/可选附件引用与优先级）、**给谁**（目标编号）；
- 入队即受理（返回任务编号），调度器异步投递：读取「给谁」，在路由字典中查出目标 webhook，向其投递任务包；
- 队列持久化：Hub 重启后队列不丢，恢复继续投递/重试。

**验收要点**：任务提交后 ≤ 1 秒内可见于队列；目标 webhook 收到的任务包内容与提交一致；Hub 重启后在途任务恢复调度。

### FR-3 回执确认（ACK）

- 端侧收到任务包后返回**接收状态信息**：HTTP 2xx + `{"status":"received","task_id":"..."}`；
- **收到有效回执即视为签收**：该任务包立即从队列删除，并写入留痕（传递状态 = `delivered_confirmed`）；
- 回执判定细则（超时、task_id 不一致、签名校验失败等）见 03-API规范 §3。

**验收要点**：端侧正常回执时任务包 10 秒内出队且留痕正确；task_id 不一致的回执不作为签收。

### FR-4 失败重试

- 未收到有效回执时，按 **+3min → +10min → +30min → +60min → +120min** 间隔重投（间隔自上次尝试失败起算；连同首投共 6 次尝试，总跨度约 3 小时 43 分）；
- 梯度值可在管理界面配置（默认即上述值）；
- 全部失败：任务包同样从队列删除，写入留痕（传递状态 = `delivery_failed`）。

**验收要点**：重试时刻与梯度一致（±10s）；第 6 次失败后任务出队且留痕含 6 次尝试明细；梯度可配置并即时生效。

### FR-5 全程留痕

- **所有删除任务包的动作必须留痕**，注明任务传递状态，四种终态：
  - `delivered_confirmed` 已签收出队；
  - `delivery_failed` 重试耗尽出队；
  - `invalid_target` 目标编号不存在 / webhook 缺失（不入重试，直接出队——重试无意义）；
  - `cancelled` 管理员人工取消。
- 留痕内容：任务编号、来自谁、给谁、入队时间、出队时间、终态、尝试次数、**逐次尝试历史**（时刻、结果、HTTP 状态/错误、耗时）、备注；
- 留痕**只增不改不删**，保留期 ≥ 180 天（可配置）；任务内容可配置只存摘要（哈希）以满足最小化原则。

**验收要点**：四种终态各能产生一条完整留痕；管理界面可按状态/时间/Agent 筛选并导出；直接改库也无法改写留痕语义（只增接口，无更新/删除接口）。

### FR-6 端侧 Agent-B 服务（Kizuna Box）

- **由本产品官方提供**，不是让用户自己写 webhook 脚本；
- **一句提示词安装部署**：用户把产品生成的安装提示词贴给目标机器上的 Agent，Agent 自助完成安装、注册、自启配置与自检（提示词全文见 04 §3）；
- **稳定性**：进程崩溃自动拉起；任务「先落盘、后回执」保证 Hub 已收到回执的任务包绝不丢；断网自愈、日志轮转；
- **开机重启**：Linux systemd / macOS launchd / Windows 服务 / Android Termux 服务 / 鸿蒙（限制见 §8）；
- 平台覆盖：**Linux / macOS / Windows / Android(Termux) / 鸿蒙**，Agent 按自身环境获取对应安装脚本直接部署。

**验收要点**：一台全新 Linux/macOS/Windows 机器，仅凭安装提示词即可完成部署并出现在路由字典中（在线）；kill 进程 5 秒内自拉起；重启机器服务自动运行。

### FR-7 中心服务管理界面

- 中心服务自带 Web 管理台（`/admin`，管理员登录）；
- 六个一级页面：总览 / 通讯录 / 任务队列 / 投递留痕 / 安装部署 / 设置（页面明细见 05 §2）。

**验收要点**：管理员可完成 FR-1/FR-4（梯度配置）/FR-5（审计）/FR-6（生成安装提示词）的全部人工操作。

### FR-8 DSH 插件（一级交互面板）

- 管理界面以**插件形式直接安装进 DSH**（`install_bundle` 一键安装）；
- 在 DSH 左侧栏出现**原生风格一级入口**（与「插件」「MCP 连接器」同级），点击后中央主区域**整页切换**到管理界面（非弹窗/浮层/iframe）；
- 视觉、交互、主题、双语严格遵循团队《DSH 插件开发提示词》规范（见 05 §4）。

**验收要点**：按该规范 §9 逐项通过（侧栏入口、整页切换、1440/1080/900 三档不溢出、深浅色、控制台无报错、中英文切换无残留）。

## 5. 关键用户故事

**故事 1 · 上架（Agent 拥有者）**
小王在办公室 Windows 电脑上有一个 DSH Agent。他打开管理台「安装部署」页，填了编号/名称/能力声明，生成安装提示词，贴给本机 Agent。两分钟后，这个 Agent 出现在通讯录里，状态在线。

**故事 2 · 派单（Agent → Agent）**
DSH 会话里的 Agent-A 要把一份报关预审任务交给小王的 Agent。它 `POST /tasks` 提交任务包，拿到任务编号；Hub 查字典命中 webhook，立即投递；端侧落盘并回执；Hub 收到回执出队并留痕「已签收」。全程 3 秒。

**故事 3 · 断线重投（可靠性）**
小王的电脑正巧重启。前两次投递无人应答；+3min、+10min 各重投一次仍未成功；第 4 次（+30min）电脑已开机，端侧服务随开机自启，签收成功。任务包出队，留痕记录了 4 次尝试的完整历史。

**故事 4 · 审计（管理员）**
月底管理员在「投递留痕」页按 `delivery_failed` 筛选，发现某台设备连续 6 次投递失败已出队，逐次明细显示 DNS 解析失败——联系负责人修复，并从留痕导出记录归档。

## 6. 非功能需求

| 维度 | 要求 |
| --- | --- |
| 可靠性 | 队列与留痕持久化（SQLite WAL）；Hub/端侧崩溃或重启后状态可恢复；投递签收成功率 ≥ 99.9% |
| 性能 | 队列吞吐 ≥ 100 包/分钟；投递并发默认 32；API 本机 p99 < 200ms；回执判定超时 10s |
| 安全 | 管理端令牌、Agent 令牌、一次性注册令牌（enroll）三级鉴权；投递请求 HMAC-SHA256 签名 + 时间窗防重放；全链路 HTTPS 优先 |
| 可运维 | `/metrics` 指标（队列深度、投递成功率、重试分布、在线 Agent 数）；日志分级与轮转；数据库每日备份留痕 |
| 兼容 | 端侧覆盖 Linux / macOS / Windows / Android(Termux) / 鸿蒙（见 §8）；Node 20+ 运行时由安装脚本保障 |
| 合规/隐私 | 留痕可选只存任务内容摘要；任务内容传输 TLS；令牌轮换能力 |

## 7. 版本规划

| 版本 | 范围 |
| --- | --- |
| **v0.1 MVP** | Hub（字典/队列/投递/ACK/重试/留痕）+ Endpoint（Linux/macOS/Win）+ 安装脚本 + Web 管理台（总览/通讯录/队列/留痕/安装） |
| **v0.2** | **DSH 插件**（一级面板）+ 一句提示词安装全流程 + 心跳在线状态 + 能力检索 + 重试梯度可视化配置 |
| **v1.0** | Android(Termux) 端侧 + 人工取消/手动重发 + `/metrics` 监控 + 备份策略 + Agent 停用/权限（谁能给谁派单的 ACL） |
| **v1.1** | WSS 反向隧道模式（NAT 后端侧免公网暴露）+ 任务执行结果回传（可选回调）+ 多管理员/审计账号 |
| **v2.0** | 鸿蒙 ArkTS 原生 SDK、多 Hub 联邦、端到端加密任务包 |

## 8. 边界与限制（诚实声明）

1. **鸿蒙**：HarmonyOS NEXT 不向第三方开放后台常驻脚本运行时，**v1 不承诺鸿蒙脚本化部署**。替代路径（写入产品说明）：① 端侧服务部署在设备可达的代理机/云主机上，webhook 指向该机；② v2.0 ArkTS 原生 SDK（应用内常驻）；③ 设备若具备终端环境（部分行业定制系统）可按 Termux 方案尝试。
2. **NAT/公网可达性**：投递是 Hub → 端侧 webhook 的主动推送，端侧必须处于 Hub 可达的网络（公网 IP、同内网或端口映射）。不可达场景 v1 只能走重试+失败留痕；WSS 反向隧道模式在 v1.1 解决。
3. **ACK 的语义**：回执代表「端侧服务已收到并落盘」，**不代表** Agent 已理解或已执行任务。任务执行结果回传是 v1.1 的可选扩展。
4. **单点**：v1 为单实例 Hub（SQLite），多实例高可用在 v1.1+ 评估（Postgres + SKIP LOCKED）。

## 9. 需求追溯表（原始需求 → FR → 设计文档）

| 原始需求（立项陈述） | 对应 FR | 设计落点 |
| --- | --- | --- |
| 路由记录 Agent 的名称、编号、能力声明、webhook | FR-1 | 02 §3 `agents` 表；03 §1 |
| 队列存储任务包（来自谁、任务内容、给谁） | FR-2 | 02 §3 `tasks` 表；03 §2 |
| 收到新任务包 → 读「给谁」→ 用路由中目标 webhook 发送 | FR-2 | 02 §5 时序图；02 §6 调度器 |
| 端侧收到后返回接收状态信息 | FR-3 | 03 §3 投递协议与 ACK 判定 |
| 收到回执则在队列删除该任务包 | FR-3 | 02 §4 状态机 `delivered` |
| 未收到则隔 3/10/30/60/120min 重发，均失败也删除 | FR-4 | 02 §6 重试梯度表；02 §4 `failed` |
| 所有删除任务包的记录要留痕，注明任务传递状态 | FR-5 | 02 §3 `audit_logs`；05 §2 留痕页 |
| 端侧 webhook 脚本服务由本产品提供 | FR-6 | 04 全文 |
| 支持一句提示词安装部署 | FR-6 | 04 §3 安装提示词全文 |
| 保障稳定性与开机重启 | FR-6 | 04 §5 稳定性设计；04 §4 自启配置全文 |
| 按 linux/mac/win/安卓/鸿蒙获取脚本直接部署 | FR-6 | 04 §4 平台矩阵（鸿蒙边界见 PRD §8） |
| 中心服务有管理界面 | FR-7 | 05 §2/§3 |
| 支持以插件形式在 DSH 直接安装、内嵌一级交互面板 | FR-8 | 05 §4（§0 填充表可直接开工） |