源码系统概览
文章正文
Cairn 是一个通用型状态空间搜索引擎，给定起点与目标，在未知状态空间中搜索一条可行路径。
它的首个已验证场景是授权渗透测试与 CTF，但架构本身并不限定角色或工作流，可推广到任何「起点明确、目标明确、路径未知」的问题。
项目以黑板架构与 OODA 循环智能体工人为核心，在腾讯云黑客马拉松 AI 渗透测试挑战赛中取得过全题 AK 的成绩。
本文从架构、技术栈与部署角度对这份开源源码做中性梳理，强调其授权使用边界，供安全与 AI 工程从业者合规参考。
源码简介
Cairn 的本质是通用问题求解引擎，采用黑板架构（Blackboard Architecture），以 Fact、Intent、Hint 三类原语构成显式的事实意图图。
Fact 表示已确认的客观发现，Intent 表示已声明的探索方向，Hint 是人类随时注入的判断，下次读取时被智能体吸收。
智能体工人遵循 Observe、Orient、Decide、Act 的 OODA 循环，无固定角色，任务运行时从图状态动态生成，仅通过共享板协调。
三种任务类型（Bootstrap、Reason、Explore）由同一组工人执行，分别处理开局解题、图状态研判与具体探索写回。
适用场景
授权渗透测试与 CTF 解题，作为状态空间搜索的验证场景，在明确授权环境中探索目标路径。
数学证明、规划类问题等具备「起点到目标路径未知」结构的研究，复用其通用搜索框架。
AI 工程学习：研究多智能体如何通过黑板与 Stigmergy（间接协调）完成复杂搜索，而无需中心化调度。
功能亮点
黑板架构：Fact-Intent-Hint 图作为唯一事实来源，智能体仅向黑板读写，实现解耦与可追溯。
OODA 循环工人：Observe 观察全图、Orient 定位状态、Decide 决定意图、Act 探索写回，动态适应。
多后端支持：Worker 后端支持 Claude Code、Codex、Pi 等，也可使用 mock 后端做测试。
两种运行模式：容器模式（每项目一容器）与本地模式（runtime.execution 设为 local，复用宿主 CLI，无 API key 写入配置）。
健康检查与故障转移：最新提交将健康检测改为进程内 HTTP 请求，支持启动期与任务级检查及不健康中止。
技术架构与部署指南
| 维度 | 本套源码 | 同类通用方案 |
|---|---|---|
| 技术栈 | 前端：无独立前端框架，提供轻量静态页面（cairn/server/static）展示项目与图状态。 | 依具体方案选型，需自行搭建与维护 |
| 部署方式 | 克隆仓库后，参考 dispatch.example.yaml 与 dispatch.local.example.yaml | 多托管于第三方平台或订阅云服务 |
| 功能侧重 | 黑板架构：Fact-Intent-Hint 图作为唯一事实来源，智能体仅向黑板读写，实现解耦与可追溯。 | 功能通用，定制深度有限 |
| 数据归属 | 数据自持，部署在自有服务器，不出站 | 数据通常留存于服务商侧 |
| 成本模式 | 获取后自主部署，无持续授权费用 | 通常按订阅或调用量计费 |
技术栈与运行环境
前端：无独立前端框架，提供轻量静态页面（cairn/server/static）展示项目与图状态。
后端：Python 3.11 以上 FastAPI（Server 维护图一致性，Dispatcher 调度任务与管理容器）。
数据库：SQLite（服务端本地存储项目、事实、意图与提示，无需独立数据库服务）。
运行环境：Linux / macOS，Python 虚拟环境；容器模式需 Docker 守护进程，本地模式复用宿主已配置 CLI。
其他依赖：PyYAML、Pydantic、FastAPI、Uvicorn，以及对应 Worker 后端所需的 CLI 或 SDK。
安装与部署提示
克隆仓库后，参考 dispatch.example.yaml 与 dispatch.local.example.yaml 配置调度器、公共环境变量与 Worker 后端。
本地模式将 runtime.execution 设为 local，并配置 ANTHROPIC_MODEL、CODEX_MODEL 或 PI_MODEL 等后端凭证。
容器模式通过 docker-compose.yaml 或 container 目录构建 Worker 镜像，Dispatcher 为每个项目启动独立容器。
启动 Cairn Server 后，通过 REST 创建项目（含 origin 与 goal），Worker 自动认领 Intent 并写入探索结果。
Worker 凭证建议在配置中以环境变量注入，避免在配置文件中明文写入密钥，并优先使用本地模式隔离凭据。
截图与演示说明
项目横幅展示 Cairn 的定位：超越 AI 渗透测试的通用状态空间搜索引擎，并标注其与腾讯云黑客马拉松的关联。
腾讯与赛事标识截图，说明 Cairn 在第二届腾讯云黑客马拉松 AI 渗透测试挑战赛中的参赛与验证背景。
赛事相关截图，佐证其在真实 CTF 场景中的表现（54 比 54 题目全部 AK，总排名第三）。
运行时截图展示事实意图图与 Worker 执行状态，体现黑板架构下多智能体协作的可视化界面。
常见问题
问：Cairn 只能用于渗透测试吗？
答：不是。渗透测试只是其第一个验证场景，架构通用，可推广到数学证明等同样具备「起点到目标路径未知」结构的问题。
问：本地模式与容器模式有何区别？
答：容器模式为每个项目启动独立 Worker 容器，隔离更彻底；本地模式复用宿主已配置 CLI，无需 Docker，但需自行管理凭据与隔离。
问：支持哪些智能体后端？
答：Worker 后端支持 Claude Code、Codex、Pi，也提供 mock 后端用于测试与开发，可通过配置灵活切换。
安全风险提示
特别提示：本源码未检测安全风险文件，下载后请务必进行安全审计，删除恶意代码后再部署使用！
合规提醒：Cairn 虽为通用引擎，但其首个验证场景为授权渗透测试，仅可在你拥有明确授权的环境中使用。
未经所有者许可，不得对系统、网络、应用或数据运行 Cairn 的探索能力，未授权测试可能违法并承担相应责任。
部署本地模式时建议仅在受控环境运行，避免在公共机器上写入后端 API 凭证，并定期审计配置与日志。
下载说明
源码仅供学习研究、测试部署和二次开发参考，商用前请自行确认授权、版权和安全风险。
本仓库为开源项目，遵循 GNU AGPLv3 许可证，个人与教育用途免费，商业用途需联系作者获取商业许可。
重要合规提示：本项目仅适用于授权渗透测试、CTF 与安全研究，使用者须自行确保具备合法授权。
任何将本源码用于未经授权攻击、破坏或入侵的行为，均违反法律法规与开源协议，作者与发布方不承担任何责任。
GitHub项目开源地址：https://github.com/oritera/Cairn