不定义角色，
也能走出未知的路

渗透测试的形态非常干净：你知道目标是什么（一个 IP、一个站点、一个二进制），你知道成功长什么样（一个 shell、一个 flag、一份权限证明），但你不知道中间该怎么走。这条路径不在任何文档里，它藏在目标的实现细节里，只能靠一次次试探把它逼出来。

同样形状的问题还有一大把：漏洞研究（从「这段代码可疑」到「构造出崩溃」）、数学证明（从公理到目标命题）、CTF、甚至线上故障排查（从「服务 500」到「找到那行配置」）。它们的领域知识完全不同，但搜索结构是同构的。

1.1三种常见做法，三种失败

这套思路并不新。1970 年代 CMU 的 Hearsay-II 语音识别系统就提出了黑板架构：多个专家围绕一块共享黑板工作，各自读取当前状态、各自贡献新知识，没有中央调度。Cairn 做的是把黑板重新形式化：用一张有向图当黑板，用 Intent 保留完整的因果链，于是这张图同时是知识库和推理过程的审计日志。

协调机制则对应蚁群的信息素（stigmergy）：个体之间不直接通信，而是通过改变共享环境来间接协调。Agent 读图、写 Fact，就是在环境上留下信息素。

三个原语的分工非常硬：Fact 回答「现在知道什么」，Intent 回答「接下来往哪走」，Hint 回答「我认为该注意什么」。没有一个原语是「计划」「阶段」「角色」或者「任务」——因为这些东西都可以由图的状态推导出来，一旦写进数据结构，就变成了需要维护的第二种真相。

2.1为什么 Fact 必须只增不改

想象多层网络渗透里的真实场景：

1. f003：拿到 host-A 的 root shell。
2. f007：通过 host-A 做跳板，发现内网 10.0.2.0/24。
3. 十分钟后，shell 掉线了。

大多数系统会去「更新 f003 的状态」：把 alive 改成 dead。Cairn 不这么做，它直接追加 f025：“host-A 的 shell 已断开”。

这样做换来三件事：

代价也很实在：图会膨胀，旧事实永远不会消失。所以协议里明确给了 Hint 一个额外用途——写态势评估。比如「SSH 和 SQL 注入方向均已排除，攻击面集中在文件上传」。随着图变大，这类 Hint 是降低每轮读图认知成本的唯一手段。

项目的创建就是图的初始化：Server 写入两个特殊 Fact，origin 和 goal。之后所有普通 Fact 由系统分配 id（f001、f002……），所有 Intent 也从 i001 开始。id 是项目内自增的，互相不干扰。

3.1Intent 是一条边，而且可以是超边

一条 Intent 的基本结构是 from[] → to。当 from 里有多个 Fact 时，它等价于一条超边：多个源节点共同支撑同一次探索，共享同一个 description、creator 和 worker。

from=[f002, f004] → to=f005

为什么非要支持多源？因为真实推理经常是「A 和 B 合起来才能推出 C」。如果强行只留一个主节点，就会丢掉另一半上下文，后来的人（或 Agent）看到 f005 时无法还原它是怎么来的。超边把这个因果关系完整保留了下来。

3.2一条 Intent 的三种状态

这里有个容易忽略的细节：creator 和 worker 是两件事。creator 是「谁看懂了局势、提出了这个方向」，创建时写入，永不可变；worker 是「谁在真正执行」，随认领、超时、结论而变。审计时你能分清「出主意的人」和「干活的人」。

另外，last_heartbeat_at 是永久保留的：即使 worker 因为超时被清空，时间戳也不清空。这样你还能看到「上一次有人碰它是什么时候」。

3.3完成，是图上的一条边

当某个消费者判断「这些 Fact 已经足够证明 goal 达成」，它调用 POST /projects/{id}/complete。Server 不会只把状态改成 completed，它会写一条 from=[...] → to=goal 的已结论 Intent，然后把项目状态置为 completed。

这个设计让「为什么算完成」变成了图的一部分：审计时能看到是 f007、f012、f015 这三块石头共同支撑了完成判断，而不是只看到一句「项目已结束」。

3.4同一张图，两种读法

Server 提供两种导出，互补而不是重复：

4.1Server：真相源，但故意「不聪明」

Server 的职责被压到极小：存 Project / Fact / Intent / Hint，维护 claim、heartbeat、conclude 的状态机，做输入校验。它不做任何推理，不知道什么算完成，也不知道下一步该做什么。

有两个实现细节值得注意：

• 超时是「读时语义」。没有后台定时器在扫全表，而是每次读取或认领时调用 expire_workers()，把心跳超时的 open intent 的 worker 清空。简单、没有额外进程，代价是「过期」只在有人来看的时候才发生。
• 硬停止是立即生效的。项目被切到 stopped 时，Server 会当场把该项目所有未结论 Intent 的 worker 清成 null，同时清空 project.reason。这样恢复时不用等超时，所有人可以立刻重新认领。

4.2Dispatcher：控制面，也是唯一的自动化写者

Dispatcher 是这套系统真正的「工程」。它做五件事：拉项目列表 → 判断该项目现在该跑什么任务 → 选一个 Worker → 在容器里执行 → 把结构化结果写回 Server。

为什么不让 Agent 直接连 Server？三个理由，每一个都足够独立成立：

4.3容器：一个项目一个环境

Container 模式下，每个项目对应一个 Docker 容器，命名固定为 cairn-dispatch-<project_id>。容器起来后只做一件事：sleep infinity。真正的工作是 Dispatcher 用 docker exec 把 CLI 命令送进去执行。

几个工程细节：

• 每条命令外面套一层 timeout -k 5s <N>s，Dispatcher 侧再套一层 communicate(timeout=N+15)。双保险：先礼后兵，超时后 5 秒强杀。
• 图快照不会直接塞进 prompt，而是写到容器里的 /tmp/cairn-prompts/<phase>-<uuid>/graph.yaml，prompt 里只给一句「去读这个文件」。这是为了控制 prompt 体积——图会越跑越大，把它全文塞进每次调用既贵又容易截断。
• 项目 completed 之后，容器按 container.completed_action 处理：stop 保留现场（可进去复盘），remove 直接删掉。清理在独立的线程池里跑，不阻塞主调度循环。
• 领域知识放在容器镜像里，不放在引擎里。仓库的 container/AGENTS.md 就是给某次比赛写的环境说明（Kali、题目分级、反弹 shell 的出口 IP），引擎本身完全不知道「渗透测试」四个字。

4.4Local 模式：不要 Docker，也不要 API Key

把 runtime.execution 设成 local，Worker 就不进容器了，直接在 Dispatcher 宿主机上以子进程运行，复用本机已经登录好的 claude / codex / pi CLI。启动时 Dispatcher 会对每个配置到的 CLI 跑一次 --help 探测，一个都找不到就直接报错退出。

每个项目会在 local.workspace_root 下分到一个隔离子目录当工作目录。注意：这种方式没有沙箱，Agent 以你的用户权限跑，所以官方文档明确说不要把它放进 Docker 里再跑一遍。

5.1三个输出契约

Agent 的输出永远是一个 JSON 对象，最外层固定是 {accepted, data}。三种任务的数据形状不同：

{"accepted": true,
 "data": {"complete": {
   "from": ["f007"],
   "description": "flag{...} 满足 goal 要求"
 }}}

{"accepted": true,
 "data": {"intents": [
   {"from": ["f001"], "description": "目录扫描"},
   {"from": ["f002", "f004"], "description": "用凭据登录后台"}
 ]}}

{"accepted": true,
 "data": {"description":
   "对 /search 测试常见 SQLi payload，未发现注入迹象"}}

{"accepted": true,
 "data": {
   "fact": {"description": "拿到 flag 与 root shell"},
   "complete": {"description": "关键结果已验证，goal 达成"}
 }}

5.2为什么是这三类

把 OODA 拆开看：Observe + Orient + Decide 合起来是 reason——读全图、理解局势、决定是收工还是开新方向；Act 是 explore——只走一条边，只产出一个结论。多个 Agent 各自跑这个循环，通过共享图间接同步，就得到了任务式指挥（Mission Command）的结构：上级只给目标，各单位根据态势自主决策。

bootstrap 是个刻意的例外。有些问题很小，或者至少第一个突破口很近。如果连这种题都要走「reason 提 intent → explore 执行 → reason 再判断」的三轮往返，光调度开销就比解题本身贵。于是协议允许在项目最初阶段直接推进一次——但有两个约束：

• 它仍然通过一个保留 Intent 落图（from=["origin"]、description="bootstrap"、creator="dispatcher.bootstrap"），所以这次尝试在图上可见、可审计，不会因为「直接完成」而绕开事实图。
• 主阶段只有已经解决问题时才允许返回，而且必须 fact 与 complete 同时给出。这就堵死了「模型觉得差不多了就宣布完成」这条路：要么拿出证据并宣布完成，要么继续干到被收尾。

主循环的骨架非常短。真正的复杂度全在「某个项目现在该不该派任务、派哪一种」这一个判断里：

while True:
    reap_futures()              # 回收已完成任务，更新 reason checkpoint / 冷却窗口
    summaries = list_projects() # 一次拿到所有项目的元信息与计数
    init_reason_checkpoints()   # 给"有 open intent 但还没基线"的项目建基线
    refresh_runtime_projects()  # 已退出 active 的项目释放 admission 名额
    cancel_inactive_tasks()     # stopped / deleted → 立刻取消本地任务
    queue_container_cleanups()  # completed / stopped → 异步清理容器
    dispatch_available()        # 真正的派发
    sleep(interval)

6.1全局顺序：已运行的项目优先

# 1. 先把已经在跑的项目喂饱（轮转起点每轮后移，避免饿死）
for project in running_projects_round_robin:
    if has_dispatchable_bootstrap(project): dispatch_bootstrap; continue
    if has_dispatchable_reason(project):    dispatch_reason;    continue
    if has_dispatchable_explore(project):   dispatch_explore;   continue

# 2. 所有在跑项目都暂时没活干，且还有 admission 名额，才接一个新项目
if running_project_count < max_running_projects:
    maybe_start_one_new_project()

这个顺序有一个直接后果：一个项目即使暂时没有可派发的任务，也继续占用 max_running_projects 的名额，直到它真的退出 active。也就是说，admission 是「接手」语义，不是「正在执行」语义。

6.2项目内判断：五道门

注意第 4 道门在第 5 道之前：只要态势变了，reason 可以先于 explore 跑，哪怕图上还有没被认领的 Intent。这和 spec 里「reason 要求当前没有未认领 intent」的表述看起来矛盾，其实是同一件事的两面——那句约束描述的是首次触发；一旦有了基线，新 Fact / 新 Hint 就足以让 reason 再跑一次，否则新信息会被积压。

6.3reason 的去重：什么才算「新态势」

这是整个调度里最容易写错的地方。如果只要图上有一点点变化就触发 reason，系统会自激：reason 创建了一条 intent → 图变了 → 再触发 reason → 又创建一条……永远停不下来。

Cairn 的做法是给每个项目记一个 checkpoint：上次成功跑完 reason 时的 facts 数量、hints 数量、以及当时有没有 open intents。之后只有三种情况算新态势：

不算新态势的：Intent 总数变多（那通常只是上一次 reason 自己的产物）、某次 explore 失败后 release（Intent 还是 open，只是换了个人接手）、心跳丢失。

还有一个容易被忽略的启动细节：Dispatcher 启动时，会给「当前有 open intent、但还没有 checkpoint」的 active 项目补一个基线。否则它会把运行过程中新增的第一条 Fact 当成「从来没见过的变化」而误触发，或者反过来把真正的第一次变化吞掉。

6.4选哪个 Worker

规则是可预测的六步过滤，没有玄学：

1. 按任务类型筛：这个 Worker 的 task_types 里有没有当前任务。
2. 按并发筛：当前运行数是否已经到 max_running。
3. 按健康筛：是否处于「刚检查失败」的 5 秒冷却窗口里。
4. 按拒绝筛：是否在这个项目 + 这个任务类型上刚拒绝过（同样 5 秒冷却，防止同一个模型反复撞墙）。
5. 按 priority 升序：数字越小越优先。
6. 同优先级里选当前运行数最少的；再相同就随机。

最后一步（随机）不是偷懒，而是为了避免多个 Worker 在完全等价时总是打到同一个上，形成隐性偏好。

6.5四层并发，各管一段

关于 Worker 的建模有个明确约定：一个 Worker 应该对应一个独立的 API key / 配额单元，不要把同一个 key 拆成多个 Worker 来「提高并发」——那只是把限流问题藏起来。同一个模型想跑两份，就用两个不同的 key，配成两个 Worker。

6.6硬停止与取消

项目被切到 stopped 后，Dispatcher 把它当硬停止处理，顺序很严格：不再派新任务 → 对本地还在跑的 bootstrap / explore / reason 立即发取消 → 已取消的任务不再进入收尾流程（不会再多写一条 Fact）→ 后续轮次停掉容器、杀掉容器里还在跑的 Agent 进程。

「不再收尾」这个细节很重要。收尾（conclude）本来是为了「超时了也别白跑」，但如果是人主动喊停，再让模型总结一遍就违背了停止的意图——而且此时项目已经不是 active，写回也会被 403 拒绝。

6.7日志：只在状态变化时说话

调度器每 3 秒转一圈，如果每圈都打印「没有可派发的任务」，日志会变成噪音。所以实现里有一个 _log_changed(scope, ...)：同一个 scope 下，只有日志内容和参数真的变了才输出。

必须可见的是：容器创建、任务派发、容器内新进程启动、健康检查失败、超时、收尾、释放 Intent、Worker 进入冷却窗口。稳定轮询、正常心跳、重复 skip 则原则上不刷屏。

下面这个例子是虚构的，但每一步都对应真实的协议调用和调度判断。目标是一台 Web 服务器，成功条件是拿到 flag。注意观察三件事：每一轮的任务类型如何切换、每次任务留下了什么、以及「没找到」为什么也必须写进图里。

7.1看完之后，三个值得记住的点

8.1Prompt 是怎么拼出来的

Prompt 是仓库里的 markdown 文件，按 runtime.prompt_group 选目录（default 或 mock）。Dispatcher 用字符串替换把占位符填上：{graph_yaml}、{fact_ids}、{open_intents}、{intent_id}、{origin}、{goal}、{hints}、{max_intents}。

其中 {graph_yaml} 不是图本身，而是一段「去读文件」的指令。真正的 YAML 被写进容器的临时目录：

The graph YAML snapshot is stored in this file inside the current container:

/tmp/cairn-prompts/explore_execute-3f9a1c2b7d4e/graph.yaml

Before using the graph, read the entire file and treat its contents as
the YAML snapshot for this Graph section.

这个设计解决的是上下文成本问题：图会随着探索越来越大，而每次调用都把它全文塞进 prompt，既浪费 token 也容易被截断。写进文件后，模型可以自己决定读多少、怎么读——而它本来就是一个会读文件的 CLI。

8.2输出解析：先容错，再严格

模型很啰嗦，经常在 JSON 前后加一段解释，或者用 markdown 代码块包起来。所以解析分两层：

• 提取层（output_parser.py）：先试整段文本，再试所有 ``` 代码块，最后从每一个 { 开始尝试 raw_decode，直到捞出一个 dict。只要输出里有一个合法 JSON 对象，就能拿到。
• 校验层（contracts.py）：拿到 JSON 之后不再宽容。字段必须齐、类型必须对、语义必须自洽（比如 complete 和 intents 不能共存）。任何一条不满足，就按「解析失败」处理。

容错是为了兼容不同 CLI 的包装格式，严格是为了不让半成品污染图。宽容只发生在提取阶段，验证阶段一寸不让。

8.3双阶段：超时之后，别丢掉现场

一个 explore 跑了 300 秒，超时被杀。如果这时直接重来，模型之前读过的图、试过的命令、排除的方向全丢了。所以 Cairn 用「同一个会话再来一次」的方式收尾：

收尾 prompt 的措辞非常硬：不要继续探索，不要等待未完成的任务，只总结截至目前已经确认的事实。它不追求「再努力一下」，只追求「别白跑」。所以收尾产出的 fact 往往是半成品——但这半成品比没有强，而且它同样要经过严格的 JSON 校验。

8.4失败不是一种，是七种

「任务失败」这句话在实现里没有意义，因为不同失败对应完全不同的处理。这是整份代码里最值得逐行读的部分：

两个贯穿始终的原则：不做立即重试（失败就把状态留给下一轮，让图决定要不要再来一次），以及失败绝不写半条数据（conclude 是原子的，要么 fact + 边一起落定，要么什么都没有）。

8.5健康检查：验证的不是「容器活着」

Dispatcher 会在启动时（以及可选的每次任务前）对每个 Worker 发一次极小的 LLM 请求：claudecode 打 {base}/v1/messages，codex 打 {base}/responses，pi 按 PI_PROVIDER_API 选 /chat/completions 或 /responses 或 /v1/messages。它只看 HTTP 状态码：2xx 即健康。

这一步验证的是「base URL 可达 + key 有效 + model 可调用」——也就是这个 Worker 的 LLM 配置真的能用，而不是容器有没有在跑。请求还会带上 Worker 环境里的 http_proxy / https_proxy，保证健康检查和真实出网走同一条路。

Local 模式不打 API（本机 CLI 自带鉴权），改成启动时对每个 CLI 跑一次 --help 探测。

9.1它凭什么可信

README 里给了一个相当硬的证据：腾讯云黑客松 AI 渗透挑战赛第二届，610 支队伍、1345 人，Cairn 是唯一 AK（54/54 全部解出）的队伍，总排名第 3。更关键的是赛后说明——系统在比赛前从未跑过，完整链路是比赛当天凌晨 4 点第一次上线，没有训练、没有调参、没有领域专用工具，零 MCP、零 RAG、零预设 Agent 角色。

这不是「通用性」的证明，一个领域的成绩不能推出所有领域都行。但它至少说明了一件事：这套结构本身足以承载一次真实的、对抗性的搜索。领域的部分（Kali 工具链、比赛平台 API）全部放在容器镜像和 AGENTS.md 里，引擎确实不知道自己在打 CTF。

10.1前置条件

• macOS 或 Linux（Windows 建议 WSL2）
• Python ≥ 3.12
• Docker（只有容器模式需要；local 模式不需要）
• 至少一个可用的 LLM 端点：Anthropic 兼容 / OpenAI 兼容 / 自建网关都行

10.2路径 A：Docker Compose（推荐）

# Worker 容器镜像（比赛用的 Kali 环境，引擎本身不依赖它）
docker pull --platform=linux/amd64 ghcr.io/oritera/cairn-worker-container:latest

# 构建 Cairn 用的基础镜像
docker pull ghcr.io/astral-sh/uv:python3.13-trixie

cp dispatch.example.yaml dispatch.yaml
# 填好 server、workers[].env 里的 base_url / model / key

docker compose up --build

起来之后 cairn-server 监听 8000，健康检查通过后 cairn-dispatcher 启动。数据落在 ./datas/cairn/，浏览器打开 http://127.0.0.1:8000 就是控制台。

10.3路径 B：手动起两个进程

uv run --project cairn cairn serve

# 另开一个终端
uv run --project cairn cairn dispatch --config dispatch.yaml

# 只跑启动健康检查，确认 key 和模型可用
uv run --project cairn cairn dispatch --config dispatch.yaml --startup-healthcheck-only

# 只跑一轮调度（调试用）
uv run --project cairn cairn dispatch --config dispatch.yaml --once

# 回归测试（不需要 Docker / 不需要模型）
uv run --project cairn --group dev pytest

10.4路径 C：Local 模式（无 Docker、无 Key）

cp dispatch.local.example.yaml dispatch.yaml
uv run --project cairn cairn serve
uv run --project cairn cairn dispatch --config dispatch.yaml

runtime.execution: local 时，Worker 直接以子进程跑在宿主机上，复用你已经登录好的 CLI。每个项目在 local.workspace_root 下分到一个子目录。没有沙箱，用你的权限跑，所以别把它塞进 Docker 里。

10.5第一步其实应该是 mock

dispatch_mock.yaml 配了两个纯模拟的 Worker，不调用任何 LLM，只按概率和延时返回各种结果（包括超时、非法 JSON、拒绝）。想看调度器在各种失败下怎么反应，这是成本最低的方式：

cp dispatch_mock.yaml dispatch.yaml
uv run --project cairn cairn serve
uv run --project cairn cairn dispatch --config dispatch.yaml --log-level DEBUG

mock 的每个 phase 都能配延迟区间和结果分布，甚至能用 rules 按 fact_ids_gte / open_intents_empty 强制某个结果——也就是说，你可以写一个完全确定的剧本，验证「第一次 reason 提 2 条 intent、第二次提 1 条、第三次完成」这种时序。

10.6该看什么

10.7七个容易踩的坑

11.1建议的阅读顺序

1. docs/specs/server-protocol.md 的「核心概念」一节——先建立 Fact / Intent / Hint 的语义直觉。
2. server/db.py 的表结构——你会发现整套协议其实只有五张表。
3. server/routers/intents.py——看 conclude 怎么原子地「建 Fact + 落边」。
4. dispatcher/config.py——先知道有哪些旋钮，再看它们怎么被用。
5. dispatcher/scheduler/loop.py 的 _try_dispatch_project——五道门全在这一个函数里。
6. dispatcher/tasks/explore.py——最典型的任务：claim → 执行 → 解析 → 收尾 → 写回。

读完这六处，剩下的都是变体：bootstrap 是「多一个 complete」的 explore，reason 是「不执行、只判断」的 explore，其他 driver 只是换命令行。

11.2想扩展它，改哪里

11.3关键函数索引

13.1API

13.2状态码到底在说什么

13.3配置字段

13.4术语

Origin / Goal

项目创建时写入的两个特殊 Fact，图的起点与汇点，id 固定为 origin / goal。

Claim

通过 heartbeat 把一条 open Intent（或项目级 reason）占为己有，防止并发执行。

Lease

带超时的认领。心跳停止超过阈值，lease 自动失效，别人可以接手。

Conclude

探索结束的原子操作：创建一个 Fact，同时把 Intent 的 to 指向它。

Bootstrap Intent

固定三元组 description="bootstrap" + creator="dispatcher.bootstrap" + from=["origin"] 的保留 Intent，用来标记「初始阶段的一次直接推进」。

Checkpoint

Dispatcher 本地记的「上次 reason 时的 facts / hints / open intents 数量」，用来判断什么算新态势。

Stigmergy

个体之间不直接通信，通过改变共享环境间接协调。这里是「读图 / 写 Fact」。

Admission

Dispatcher 接手一个项目的动作。接手后即使暂时没活干，也继续占用 max_running_projects 名额。