Agent 发现与 DAG 编排系统 · 设计文档

⚠ 架构已迁移（2026-10-29）：本文描述的是 v2.0 的 DNS SRV + 静态 dns/agents.db 方案， 已被 SVCB + CoreDNS 动态注册 取代。现网实现见 docs/svcb-registration.md，本文仅作历史设计留档， 其中的 agents.db、_tcp SRV 查询名、固定 IP 等细节均已不再适用。 版本 2.0.0 · 域名 agents.internal · 控制台 http://192.168.1.30:18089/ · 本页 /docs 本文所有数字均来自 2026-10-23 在 9400f 上的真实运行结果（GET /api/discovery、GET /api/traces），不是估算值。

0. 这个系统要验证什么

它不是「让几个 Agent 串起来跑通」的演示，而是一组可被证伪的工程命题的验证装置。每个命题都写清了如果不成立，会在哪里暴露，以及用什么指标判定。

V1 · 能力寻址能否完全取代硬编码调用链

命题：一个任务的执行路径可以完全由「运行时声明的能力」推导出来，调用方不需要知道任何 Agent 的地址、数量或实现。

判定：GET /api/discovery 中 7 个能力全部 available=true 且 source=role_srv，srv_fallbacks=0；编排全程没有任何硬编码 endpoint 常量。

若失败：会出现某个能力 available=false，或必须走 generic_srv_filtered 兜底才能凑齐节点。

实测：7/7 能力 role_srv 直接命中，兜底路径一次都没触发，索引 149.04ms 完成。

V2 · 发现成本能否与 Agent 总数解耦

命题：查询成本应随能力数量增长，而不是随 Agent 实例数量增长。加十个同能力的 Agent 副本，不应让索引变慢。

判定：SRV 查询次数 ≈ 能力数 × 单次查询的记录数，而不是「先拉全量再逐个抓 Card」。

若失败：srv_queries 或 card_fetches 会随实例数线性上升。

实测：srv_queries=56、card_fetches=48、card_cache_hits=57、card_failures=0 —— 缓存命中数高于实际抓取数，说明重复索取确实被拦住了。

V3 · 局部故障能否被限制在局部

命题：单个 Agent 挂掉、Card 超时、或上游模型 5xx，不应让整条任务链中断。

判定：故障发生时应出现 node_attempt_failed → node_retry → 换候选成功，或该节点降级而其它节点继续；最终状态是 degraded 而不是 failed。

若失败：任何一次单点异常都会让 status=failed 并且后续节点全部不执行。

机制：候选链回退 + 8s 负缓存 + return_exceptions=True + provider 回退链（xmkai → deepseek）。

V4 · 串行延迟能否被 DAG 分层真正压掉

命题：互不依赖的节点必须并发执行，总耗时等于关键路径而不是节点耗时之和。

判定：对比「所有节点延迟之和」与「实际端到端耗时」。

若失败：实测耗时 ≈ 各节点之和，说明分层没生效，仍在排队。

实测（trace ed320e1a6e93）：

事件流里能看到真实的分层推进：layer_started{0,[n1,n2],parallel} → {1,[n3,n4],parallel} → {2,[n5],serial} → {3,[n6],serial}。剩余 11.9s 是索引、规划模型调用与交付物拼装的开销。

V5 · 编排过程能否被完整复现

命题：任何一次任务事后都应能回答「查了哪些 DNS、每步考虑了谁、实际绑定了谁、Agent 收到了什么上下文、输出了什么」。

判定：trace 详情里 nodes（每节点 Agent/依赖/分组/耗时/字数）+ events（45 条，含 node_input 全文）+ plan 三者齐全，且前端能边跑边看。

若失败：只能拿到最终字符串，出问题必须加日志重跑。

实测：ed320e1a6e93 留下 6 节点、45 条事件、完整 plan，可回放每一层的进出。

V6 · 语义相近的任务能否被区分开

命题：「写一份派对策划」与「实现一个下线接口」都含「方案/步骤」字样，但必须路由到不同能力的 Agent。

判定：前者走 writing，后者走 implementation，且在归一化阶段的 warnings 里能查到改判痕迹。

若失败：两个任务都被送进 coder，产出无法执行的代码或没有正文的方案。

实测：设计一个用户下线接口 → implementation；设计一份生日派对策划 → writing。

1. 解决了什么问题

1.1 问题域：多智能体协作落地时的六个硬约束

把一个任务交给多个专职 Agent 完成，工程上真正卡住的不是「Agent 能不能写」，而是下面六件事：

这六条正是 V1~V5 要逐一否证的对象 —— 命题与问题的对应关系：V1↔P1、V2↔P2+P3、V3↔P4、V4↔P5、V5↔P6。

1.2 对应解法

1.3 附带解决的语义歧义（V6）

「写一份派对策划」和「实现一个下线接口」都含「方案/步骤」这类词，只靠关键词会把它们路由到同一个 Agent。系统做了两道判定：

1. 规划器 prompt 明确写死：implementation 只用于交付可运行代码/配置/接口改动；写方案、策划、文案、报告一律 writing。
2. 归一化阶段硬校验：若节点能力是 implementation，但该节点的 purpose 里没有任何编码信号（且原文也不是编码任务），强制改判为 writing，并写入 warnings。

实测效果：设计一个用户下线接口 → 走 implementation；设计一份生日派对策划 → 走 writing。

2. 设计思路

2.1 四层结构

┌──────────────────────────────────────────────────────────────┐
│  接入层     浏览器 / CLI                                     │
│             POST /api/start  →  GET /api/stream/{trace_id}    │
├──────────────────────────────────────────────────────────────┤
│  观测层     dashboard (:18089)                               │
│             静态页面 + /api/run 代理 + SSE + trace 查询/删除   │
├──────────────────────────────────────────────────────────────┤
│  编排层     analyst-agent                                    │
│             能力索引 → DAG 计划 → 分层执行 → 结果拼装          │
├──────────────────────────────────────────────────────────────┤
│  发现层     agent-dns (CoreDNS :53)  +  Agent Card            │
│             agents.db（A / 通用 SRV / 角色 SRV）               │
├──────────────────────────────────────────────────────────────┤
│  执行层     planner / researcher / verifier / coder /         │
│             writer / synthesizer （各自 :8000）                │
└──────────────────────────────────────────────────────────────┘

设计上让发现层不依赖编排层：CoreDNS 只认 zone 文件，即使 analyst 挂了，任何新进程仍可用同一条 DNS 查询找到全部 Agent。编排层也不持有 Agent 列表 —— 每次任务都从索引现取，索引本身又是 DNS + Card 的投影。

2.2 能力目录（CATALOG）

能力目录是唯一的枚举，同时被三处消费：规划器 prompt 的可用能力表、索引的切片维度、Card 的能力白名单。

注意 verifier-agent 同时承载 security_review 和 validation —— 一个实例注册多种能力，是 SRV 按能力切片后自然支持的结果，不需要额外抽象。

2.3 为什么用 DNS SRV 而不是手写注册表

• SRV 自带 priority + weight + port：负载均衡策略不用自己发明，priority 做粗筛、weight 做加权随机，语义是现成的。
• 零 SDK：任何语言、任何进程，只要会发 DNS 查询就能发现服务，不需要引一个注册中心客户端。
• 天然分层 key：_<capability>._tcp.<domain> 让「按能力查」变成一次独立的 DNS 查询，而不是「先拿全量再过滤」。
• 运维面小：CoreDNS 一个容器 + 一个 zone 文件，没有额外数据库要备份。

dns/agents.db 里三类记录：

; 1) 地址：给 SRV target 落地
planner-agent IN A 172.19.0.6

; 2) 通用索引：仅兜底，按能力查不到角色型 SRV 时才回落到这里，再按 Card 过滤
_agent._tcp IN SRV 10 10 8000 planner-agent.

; 3) 能力切片：查询成本 O(能力数)，与 Agent 总数无关
_planning._tcp IN SRV 10 10 8000 planner-agent.

一个必须注意的细节：compose 里每个容器的 aliases 必须与 zone 文件里的 SRV target 完全一致（本版统一为 <name>-agent 短名，且容器 DNS 指向 172.19.0.5），否则 SRV 解出的短名会被 Docker 内嵌 DNS 判成 NXDOMAIN。

2.4 Agent Card：能力索取的契约

每个 Agent 暴露 GET /.well-known/agent-card.json（schema_version: 2.0）：

Card 是准静态数据：版本化发布、很少变。因此它适合被缓存，而不适合每请求现取 —— 这是 P3 的直接依据。

2.5 索引与缓存策略

single-flight：每次抓取前先抢 asyncio.Lock("card:<endpoint>")，抢到后再查一次缓存。并发 N 个节点同时需要同一个 Agent 的 Card 时，只有一个请求真正发出去。

两级回退：

1. 先查 _<capability>._tcp.<domain>（source = role_srv）。
2. 无记录时回落 _agent._tcp.<domain> 全量 SRV，再按每个 Card 的 capability_ids 过滤（source = generic_srv_filtered），结果按 CARD_TTL 缓存。

选择策略：先按 priority 取最优组，再在组内按 weight 加权随机 —— priority_then_weighted_random。健康探测失败的候选被剔出可用集；全部不健康时退回未验证列表（宁可用不确定的，也不返回空）。

2.6 DAG 计划与校验

规划器（一次模型调用）输出：

{
  "intent": "≤30字意图",
  "nodes": [{"id":"n1","capability":"research","depends_on":[],"parallel_group":"g1","purpose":"一句话目的"}],
  "final_node": "n4",
  "reasoning": "为什么这样分层"
}

normalize_plan() 做七道硬处理，不信任模型输出：

1. 非 dict / 无 nodes → 直接降级为 fallback_plan（固定顺序执行，链路仍可跑）。
2. 未知能力 → 丢弃并记 warnings。
3. 重复能力 → 去重。
4. implementation 语义误判 → 改判 writing（见 1.3）。
5. 非法依赖（引用不存在 / 自引用）→ 剔除并记 warnings。
6. 依赖环 → 只保留「依赖序号小于自身」的边，天然打断环。
7. synthesis 强制为 final_node，依赖全集，且移到列表末尾；删除重复能力后再闭合一次依赖。

之后 levels() 用拓扑排序分层：depends_on 为空的进第 0 层，每层内可并发。带 guard < 20 兜底，剩余节点无法推进时一次性跑完，避免死循环。

节点上限 MAX_NODES = 6：超过后规划质量下降、延迟线性上升，且 context 预算不够分。

2.7 分层执行与故障隔离

层 0: [n1 research] [n2 planning]      ← asyncio.gather，同层并发
层 1: [n3 implementation] [n4 validation]
层 2: [n5 synthesis]                   ← 依赖全集，只跑一次

每个节点内部：

1. bind_agents() 已提前绑定服务与 alternates；绑定为空 → 记 capability_unavailable 事件、节点标 unavailable，不静默跳过。
2. build_context() 压缩上游输出 → 发 node_input 事件（含 Agent 实际收到的上下文文本与字数）。
3. 按 [primary] + alternates 逐个 POST /process；每个失败都发 node_attempt_failed，换候选时发 node_retry。
4. 全部失败 → 节点 failed + 记入 failures，链路继续（不会中断其它节点）。
5. 成功 → 发 node_succeeded 与 node_output（全文），落库字数与 token 估算。

超时矩阵（全部可在 compose 调）：

模型侧还有一层独立的故障隔离：provider 回退链 xmkai → deepseek（或反向）。xmkai 在 Cloudflare 后面且是单点，实测 2 个并发长请求就 524，因此按 provider 限流（xmkai 并发 1，deepseek 并发 4）。RETRYABLE = {408,425,429,500,502,503,504,520,522,523,524} 重试一次；finish_reason=length 时不把 reasoning_content 当答案，而是把 token 预算翻倍重试（上限 4096）。

2.8 Context 压缩

上游结果不能原样往下传，否则 token 随层数线性爆炸。策略：

• 预算：CONTEXT_BUDGET_TOKENS=1800，单节点 CONTEXT_PER_NODE_TOKENS=320（约 1 token ≈ 1.8 中文字符）。
• 单节点先裁剪（头 65% + 尾 + 截断标记），再按总量裁剪：每轮挑当前最长的非交付物节点压到 60%，压到 120 字仍超标则丢弃最早的普通中间节点。
• PRESERVE_CAPS = {writing, implementation} 的输出是交付物正文，上限放到整个上下文预算，且最后才压、绝不丢弃。理由：实测宽松策略会把 2400 字的方案正文截断，最终答案变成半截方案。
• 记录 compaction 明细（原始字数、保留字数、丢弃节点、估算 token、是否因正文超预算），随 context_compacted 事件进 trace。

2.9 可观测性

SQLite（WAL 模式，analyst 写、dashboard 读）三张表：

WAL 允许一写多读，所以 dashboard 能在 analyst 写的同时轮询增量读。reap_stale(300) 在 dashboard 启动时把「无任何事件超过 300s 的 running」标记为 aborted —— 判活信号取最近事件时间而不是 started_at，避免误杀正在跑的长任务。

3. 请求流程

3.1 端到端时序

浏览器          dashboard          analyst           CoreDNS        Agent实例
  │                │                  │                 │              │
  │ 1 POST /api/start (text,provider)  │                 │              │
  ├───────────────►│                  │                 │              │
  │                │ 2 生成 trace_id，落一行 running     │              │
  │                │ 3 POST /process ─►│                 │              │
  │ 4 {trace_id} ◄─┤   （立即返回，任务在后台跑）         │              │
  │                │                  │                 │              │
  │ 5 GET /api/stream/{trace_id}       │                 │              │
  ├───────────────►│                  │                 │              │
  │                │ 6 轮询 SQLite 增量事件 → SSE 下发    │              │
  │◄═══════════════┤                  │                 │              │
  │                │                  │ 7 SRV _cap._tcp │              │
  │                │                  ├────────────────►│              │
  │                │                  │◄────────────────┤ 记录列表     │
  │                │                  │ 8 GET /.well-known/agent-card.json
  │                │                  ├───────────────────────────────►│
  │                │                  │ 9 GET /health                 │
  │                │                  ├───────────────────────────────►│
  │                │                  │ 10 模型调用 → DAG plan        │
  │                │                  │ 11 分层执行 POST /process     │
  │                │                  ├───────────────────────────────►│
  │                │                  │ 12 结果落库 + 事件 ──► SSE ──► 页面逐节点刷新

3.2 阶段一：发现（Discovery）

1. INDEX.warm() 对所有 CATALOG 能力并发 candidates(cap)。
2. 每个能力发一次 SRV _<cap>._tcp.agents.internal（CoreDNS file 插件 + cache 30）。
3. 拿到 (target, port, priority, weight)，拼成 endpoint = target:port。
4. 并发抓该能力所有候选的 Card（带缓存与 single-flight），失败的写 8s 负缓存并进 failed[]。
5. 并发探测 /health，status=="ok" 才算健康。
6. 汇总为 discovery_view：每能力的 source / available / reason / candidates / failed / stats。

实测（7 个能力，全 role_srv 命中）：149.04ms，srv_queries=56、card_fetches=48、card_cache_hits=57、card_failures=0、health_probes=80。

3.3 阶段二：规划（Planning）

1. plan_prompt(CATALOG, available) 把能力表 + 索引里真实可用的能力喂给模型，要求只输出 JSON。
2. 模型返回 → _extract_json() 容错解析（先找 json 围栏代码块，再取首个 { 到末个 }，最后修补 ,}/,]）。
3. 解析失败或调用异常 → fallback_plan()（固定顺序 planning→research→security_review→implementation→synthesis）并标 degraded=True。
4. normalize_plan() 七道校验（见 2.6）。
5. 落库 save_plan()，发 plan_ready（含 levels 分层结果，前端据此立即可视化）。

3.4 阶段三：绑定（Binding）

对每个节点 INDEX.pick(capability)：

• 有候选 → 记录 service、完整 card、selection（priority/weight/pool/strategy）、最多 3 个 alternates。
• 无候选 → 记录 reason（no_srv_record / all_cards_unreachable / capability_unavailable）与 failed[]，发 capability_unavailable 事件。

前端收到 agents_bound 后把 Agent 名写进对应节点框，在节点开跑之前就能看到「谁将执行」。

3.5 阶段四：执行（Execution）

for layer in levels(plan):                      # 层间串行
    emit layer_started(layer, mode=parallel|serial)
    results = gather(run_node(n) for n in layer) # 同层并发，return_exceptions=True
    emit layer_finished(layer, {node: status})

run_node 的完整子流程：

1. node_start 落库 → 发 node_started。
2. 无绑定 → node_failed(stage=binding) → 返回 unavailable。
3. build_context()：取 depends_on 指向的上游输出 → compact_context() 压缩 → 发 context_compacted。
4. 组装 payload {input, caller:"analyst", trace_id, context, provider, capability} → 发 node_input。
5. 遍历 [primary] + alternates：POST http://<endpoint>/process（NODE_TIMEOUT）；失败发 node_attempt_failed，换人发 node_retry。
6. 全部失败 → node_failed + failures[]，链路继续。
7. 成功 → node_succeeded（耗时/字数/模型/尝试次数）+ node_output（全文）。

3.6 阶段五：汇总与交付物拼装

1. 取 final_node（必然是 synthesis）的输出作为摘要。
2. 确定性兜底：把所有 writing / implementation 节点的正文原样附加到摘要之后，并标注 <!-- 交付物正文 · <node> · <capability> -->。理由：synthesis 的 prompt 只能「尽量」引用正文，实测模型会只写摘要，导致用户拿不到方案内容。
3. status 判定：final 失败且无任何成功 → failed；final 失败但有其它成功，或存在 failures → degraded；否则 ok。
4. end_trace(status, duration, summary, stats) + trace_finished 事件。

3.7 前端实时流（SSE）

• POST /api/start 先写一行 running 的 trace，立刻返回 trace_id。这样 SSE 首帧就能查到 trace，不会 404。
• 前端用 EventSource('/api/stream/{trace_id}')，服务端每 250ms 轮询 SQLite，按 seq > last 增量下发；trace 结束发 __done__；空闲超过 420s 发 stream_timeout。
• 保留 POST /api/run 同步接口给 CLI/脚本，但前端不用它 —— 否则只能看到终态，看不到动画。

事件类型与页面反应：

3.8 请求示例

启动一次任务：

curl -s -X POST http://192.168.1.30:18089/api/start \
  -H 'content-type: application/json' \
  -d '{"text":"设计一个家庭局域网安全智能体发现系统，分析风险、查找证据并给出实现和验收方案","provider":"deepseek"}'
# {"trace_id":"ed320e1a6e93","status":"started"}

看实时事件：

curl -N http://192.168.1.30:18089/api/stream/ed320e1a6e93

直接查发现结果（不经编排）：

curl -s http://192.168.1.30:18089/api/discovery | head -c 800

4. 部署与接口

4.1 服务拓扑

所有业务容器 dns: 172.19.0.5，共享卷 tracedata → /data/traces.db。

4.2 接口一览

Agent 侧：

4.3 部署

./deploy.sh   # rsync 到 192.168.1.30:/home/shj/agent-discovery-demo，构建并 up -d

rsync --exclude .env 是硬要求 —— 远程 .env 存 AGENT_LLM_API_KEY，不能删。模型走 192.168.1.50:8080 的 Hy2 代理（NO_PROXY 覆盖内网与 .internal）。

5. 实测数据（2026-10-23）

索引（GET /api/discovery）：

7 个能力全部 available=true、source=role_srv，Card version=2.0.0：

近期 trace：

6. 已知限制与后续方向

文档由 docs/agent-discovery.md 生成，页面路由 /docs 由 dashboard.py 提供，HTML 在 docs_page.py。