多模型编排框架调研报告（v1.0）：旗舰主控与订阅制 CLI 执行的协作方式
| 字段 | 内容 |
|---|---|
| 文档类型 | 调研报告 |
| 版本 | v1.0 |
| 状态 | 已完成 |
| 密级 | 公开 |
| 作者 | zhenjun.feng |
| 生成日期 | 2026-10-16 |
| 研究截点 | 2026-10-16 02:49–02:59 UTC（GitHub API / raw 与官方文档实查；star 与推送为当日快照；三条调用链已核到函数+行号） |
| 目标读者 | 采用「旗舰模型管理 + 多模型执行」形态的工程师与技术负责人；关注 AI 代理编排、额度成本治理与人工接管的开发者 |
| 调研问题 | 现有框架是否真支持「强模型管理/路由/验收 + 轻量模型执行」；管理者能否脱离执行循环；如何贴合订阅制 CLI 会话形态并明确各候选的适配空缺；唤醒/去重/预算、持续执行与状态真实性、人工接管、经验学习如何落地；安全与迁移代价；哪些值得借鉴 |
| 覆盖范围 | 深入 3 项：Paperclip、Microsoft Agent Framework（Magentic 编排）、CLI 原生层（claude-code-router、ruflo）；辅以 LangGraph、OpenAI Agents SDK、crewAI、OpenHands、Letta/mem0、claude-squad 对照；含归档与维护状态快照 |
| 排除范围 | 未安装、未运行任何框架；不做公开 API 价格换算与省 token 百分比推算；不涉及具体硬件平台 |
姊妹短评：《OpenAI Dots 观察短评》——对「云端常驻代理」形态与主控职责的对照；其结论（长期主控职责高度相近、集成路径未证实——不直接迁移，保留评估）不改变本报告结论。
摘要
- 三层里都存在可用代码而非概念稿：平台层 Paperclip（心跳执行、唤醒合并、运行时评审/审批、预算结构）、模式层 Magentic（经理代理 + 任务/进度台账、停摆重规划）、客户端层 claude-code-router 与 ruflo（请求路由、插件/观察面）；三条与本场景最相关的机制已核到函数+行号 [S02][S24][S09][S12]。
- 与「CLI 会话 + 订阅额度 + 单机部署」边界兼容的路径是「分机制借鉴」而非整装平台：合并去重（调度层已核，见发现一）、台账五字段、回执强制今天即可用（零依赖）；CCR 属请求路由类、与心跳/台账不同层，其端点覆盖与订阅兼容均未知——非当前优先采用 [S24][S09][S12]。
- 订阅制 CLI 的适配空缺已逐项核清：Paperclip 清单未见 Qoder 适配器且其 process 适配器无跨运行会话持久（可自建 External Plugin）；CCR 支持清单亦未见 Qoder（能否接入取决于端点覆盖能力，未核）；ruflo 仅 MCP 面或可用（插件面为 Claude Code 专属）；Magentic 需自建 wrapper [S25][S12][S13][S07]。
- 选型与措辞纪律：全文按 doc/fn/path/meta 四级标注核验等级；维护状态只写「截至快照最近 push 日期」，不推断「停更」；对比表不使用「✖」而用「未见/未核」——无否定依据不下否定结论 [S26][S10][S21]。
- 经验学习：调研过程即示范——每项发现带 来源编号 / 核验等级 / 适用范围 三元组；将其推广到项目账本与技能升版，可避免把官方宣称写成实测、把推断写成事实 [S20][S14]。
背景与现状
本报告的出发场景是一类常见分工：旗舰模型担任「主控」，负责规划、派发与验收；订阅制 CLI（固定额度）承担具体执行；用户通过任务文件与执行端交互，并保留随时接管。这种形态的成本收益清晰，但四类问题反复出现：其一，主控过度参与排障与日志阅读，旗舰额度被机械性消耗；其二，管理者与执行者耦合在同一循环，缺少可靠的「完成/阻塞」事件与防重复派活；其三，验收依赖人肉记忆，没有运行时的评审/审批强制；其四，经验散落在会话里，无法检索、复用与去重。本次调研据此筛选出三层代表并深挖。本报告的适用假设：读者已有（或计划建设）「订阅制 CLI 执行 + 主控规划/验收」的自托管工作流，且关注点是不破坏现有订阅与权限形态、控制迁移成本——建议与结论均在此前提下给出，前提变化（如官方接口形态变化）时应按新场景重估。
口径与核验纪律：只读检索（2026-10-16），未安装未运行任何框架。核验分四级——doc（打开官方文档/README 原文）、fn（读函数级源码，给出文件+函数+行号+commit）、path（目录/文件结构级）、meta（仓库元数据快照）。两条措辞规则：带「未见」的表述=在已读材料中未发现（非绝对否定）；未归档且无官方声明时，只写「截至快照最近 push 日期」，不推断「停更/未维护」。三个深入对象各配一条与本场景直接相关的调用链（链 A/B/C，见下）。
图 1：三层开源方案与典型痛点的映射。来源：按来源台账的官方文档与源码整理（[S02][S03][S06][S08][S12][S13]）；数据口径：2026-10-16 实查，四级核验标注。
见图 1。它把痛点与三层方案对齐：平台层（Paperclip）把「心跳、评审/审批、预算、看板」做成产品能力；模式层（Magentic）把「经理 + 台账 + 停摆重规划」做成可嵌入代码；客户端层（CCR/ruflo）在 CLI 旁边加路由与观察面。读图要点：其一，三层的核验深度不同——前两层的机制已到函数级，客户端层多为 doc/path 级；其二，不是每层选一个，而是各取最小子集；其三，灰色虚线是「可直接借鉴」的边，其余机制不是不可用，而是对当前边界收益不足。
调研发现（一）：Paperclip——平台把唤醒、验收与预算做成运行时能力
Paperclip（paperclipai/paperclip，MIT，Node.js + React）定位「用 AI 代理团队干活」的编排应用：BYO agents、每代理可选模型与 harness、看板跟踪任务与成本 [S01]（读到的 master 提交 90924d61；快照时 head 已前移 560d8953，引用一律以 pin 为准 [S26]）。机制一（链 A，fn 级，两轮核验）：心跳执行 + 运行中唤醒合并。文档侧（doc）：代理不常驻，仅在被唤醒后开启短执行窗口（启动适配器→注入提示→运行至退出/超时/取消→回写 状态/token/错误/日志）；唤醒四源（timer/指派/按需/自动化）；运行中重复唤醒「merged (coalesced) instead of launching duplicate runs」[S02]。调度侧（fn，两轮核验后修正）：真正的忙时合并发生在 server/src/services/heartbeat/queue.ts（@90924d61，4667 行）的准入路径——议题存在活动执行（if (activeExecutionRun)，L3653）时：①通用路径调用 wakeQueue.admitWakeBehindIssueExecution(...)（L3700），返回 kind:"coalesced" 即把新唤醒合并进正在运行的执行（L3739）；②Dot 适配器路径把未消费输入写成 status="deferred_issue_execution" 的持久排队唤醒，同键合并时 coalescedCount + 1（L3681），已被读取则记 status="coalesced"（L3688）；③评论/交互响应类输入走 shouldQueueFollowupForRunningIssueWake（定义 L313、调用 L4181）另开运行边界而非合并。运行结束的续接由未读输入留存语义保证：「a finish racing the event tick must leave unread input available for the next assignment」（L3661）；准入事务接线在 server/src/modules/wake-queue/index.ts（L85-98）。更正说明（初版误引）：先前引为合并主体的 execution-wait.ts recordExecutionWait()（L14-54）实为「已知门控等待（依赖阻塞/对账）诊断回执」路径——它合并的是同 idempotencyKey 的 skipped 记录，头注明确「诊断不是抑制未来 wake 的依据」（L10-11），不能单独证明调度级合并；该结论现以 queue/wake-queue 两文件为准 [S24]。代理侧触发按心跳协议五步：取身份（含预算）→ 先处理审批 → 拉「收件箱」→ 选活 → checkout 认领后才开工 [S24]。这组语义（准入合并 + deferred 排队 + 评论另开边界 + 未读输入留存）可复刻到自建的巡检/通知脚本。
机制二（doc 级）：运行时强制验收——执行策略不是「代理记得请求评审」，而是运行时强制「每次运行必须回写评论（恒定不变量）→ 可选评审（可打回）→ 可选审批（人/代理参与，运行时排除原执行者）」；approvalsNeeded: 1，多审批暂不支持 [S03]。机制三（path 级）：预算三件套（budget_policies.ts、budget_incidents.ts、budget-reservations.ts）与 heartbeat-run.ts 入口 [S06]——即预算是有策略/事故/预留语义的一等公民，但限额算法未读（未知），不据此做订阅额度换算。人类操作面成体系（审批/成本与预算/委派/活动日志/仪表盘）[S05]。适配器面（doc 级）：claude_local、codex_local、opencode_local、cursor、pi_local、hermes_local/gateway、process、http；本地适配器「假设 CLI 已安装且已登录」——据此推断登录态留在本机 CLI 侧；平台侧是否另存令牌未核（未知）[S04]。选型视角：机制全盘可借鉴；整装部署（部署+流程重编）暂不进入。
| 对象（Paperclip 内） | 官方文档宣称（doc） | 源码确证（fn/path） | 未知 |
|---|---|---|---|
| 心跳/四类唤醒/唤醒合并 | 运行时指南原文 [S02] | 链 A（两轮核验修正）：heartbeat/queue.ts L3653/3661/3681/3688/3700/3739/4181 与 wake-queue/index.ts L85-98（fn）；execution-wait.ts 为门控回执路径（fn） | 并发边界细节 |
| 运行时 评审/审批/回写 | 执行策略原文 [S03] | —（doc 级） | 多审批时间表 |
| 预算策略/事故/预留 | 概述（doc） | 三路径 + 运行入口 [S06]（path，算法未读） | 限额算法与订阅口径 |
| 本地 CLI 适配器与登录假设 | 适配器文档原文 [S04] | 目录实查 [S04] | 平台侧令牌存储（未知） |
调研发现（二）：Microsoft Agent Framework · Magentic——经理台账与停摆重规划
选型背景（meta/doc 级）：microsoft/autogen 主仓截至快照最近 push 为 2026-04-15（未归档）；官方 Discussion #7066 宣布与 Semantic Kernel 合并为 Microsoft Agent Framework，后者同团队维护、2026-02 迁移博文面向 RC [S10][S11]。Magentic 由 AutoGen 时代 Magentic-One 演进为 Agent Framework 官方编排模式（文档发布 2026-09-21/更新 2026-10-06）[S08]。
机制（链 B，fn 级）：经理代理产出任务台账并进入协调循环——按上下文动态选择下一位执行者；每轮更新进度台账五字段（满足/绕圈/推进/下一位/指令）。停摆判定在 python/packages/orchestrations/agent_framework_orchestrations/_magentic.py（@deecbcb0，1859 行）：_run_inner_loop_helper（L1100）中 L1149-1158——「无推进或绕圈」则 stall_count += 1（否则 max(0, stall_count-1) 衰减），超过 max_stall_count 即 _reset_and_replan(ctx)；_reset_and_replan（L1189）依次执行 magentic_context.reset()（L1200；实现 L388-396：清历史、stall_count=0、reset_count += 1）→ 重置参与者（L1203）→ manager.replan（L1206）→ 广播 REPLANNED 事件（L1207）。人工介入链：计划评审响应 handle_plan_review_response（L1027-1057）支持 Approve 放行 / Revise 打回并重规划；检查点暂停-恢复在文档示例中演示；上限有三：max_round_count/max_stall_count/max_reset_count；并发警告：不要跨并发工作流共享有状态 manager（用 manager_factory 隔离）[S09][S08]。供应商面（path 级）：python/packages/ 供应商/存储包矩阵齐全（anthropic/openai/gemini/ollama/mistral/mem0/redis/postgres…），代理级独立 client 使「强模型经理 + 轻量模型执行」在结构上成立；跨供应商混搭无官方实测数据（未知，不作省额度承诺） [S07][S08]。
选型视角：价值在信息结构（台账五字段→中文进度卡；停摆→巡检告警；计划评审→开工确认点）；形态不达标（库，需自建进程），且无任何现成 CLI 接线（见适配空缺节）[S07][S08]。另注：Magentic 的经理本身在编排循环内逐轮驱动，本报告只借鉴台账字段与停摆思想，不照搬「每轮调用旗舰模型」的用法。
图 2：Paperclip 心跳循环与 Magentic 协调循环对照。来源：Paperclip 运行时/执行策略文档与链 A 源码 [S02][S24]、Magentic 文档与链 B 源码 [S08][S09]；数据口径：doc+fn 级核验，关键源码以 commit pin 引用。
见图 2。左半「唤醒→合并→执行→记录→评审/审批」：管理者参与点是策略配置与结果回写，不在每一步；右半「计划→评审→选人→执行→台账→重规划」：经理代理本身在循环内逐轮驱动并更新台账（可能每轮调用模型），人工参与点则是计划评审与终稿验收。读图要点：其一，两循环都用结构化事件与台账替代人读日志，是主控额度问题的结构性解法（只借台账字段与停摆思想，不照搬每轮调用旗舰模型）；其二，「重复」与「停摆」都有显式处理（coalesce 与 stall-counter），可平移为巡检参考规则；其三，图底最小子集（合并唤醒 + 进度台账 + 运行时回写）零依赖可做。
调研发现（三）：CLI 原生层——本地网关路由（CCR）与插件化团队（ruflo）
claude-code-router（doc+fn 级）：定位「面向编码代理的本地模型网关与控制面」——给一批 CLI 一个稳定本地端点（默认 http://127.0.0.1:3456），其后统一管理 providers/模型/账号/路由规则；能力含重试、凭据池、键轮转、有序回退与请求日志/令牌/成本观测；协议面覆盖 OpenAI/Anthropic/Gemini/OpenRouter/DeepSeek/SiliconFlow/Moonshot/Mistral/Z.AI/Bailian 与自定义端点 [S12]。链 C（分两层核验）：脚本层（fn）——packages/core/src/routing/route-script-runtime.ts 的 RouteScriptRuntime（L57）执行 resolveRouteScript（L83/L125），其熔断键（L130）与超时（L146）管理的是用户路由脚本 worker 的执行，不代表供应商层行为 [S12]；供应商层（doc）——重试、凭据池、键轮转、有序回退为 README 功能清单声明，本次未见实现级核验，两层不可混同。接线方式的准确说法是「客户端需一次性指向本地端点（CCR 以 Agent Profiles 的 environment/launch 入口管理这一步，README L228），此后切换供应商/模型才无需改各 CLI 配置」——「不改配置即生效」的表述并不充分 [S12]。支持清单未见 Qoder（空缺见下节）[S12]。
ruflo（doc+path 级）：包名 claude-flow v3.56.10（MIT），以 Claude Code 插件市场直装（ruflo-core/console/mods），其他客户端经 npx ruflo mcp start 接 MCP；TUI 含 Overview/Cost/Swarm/Events/Missions 视图 [S13]。结构实查：plugin/{agents,commands,hooks,scripts,skills}、v3/@claude-flow/cli、v3/mcp/tools/swarm-tools.ts、plugins/ruflo-console/hooks/cost.ts 等 [S14]。作者自述边界：「Claude Code 与 Codex 已有强原生能力，RuFlo 是附加的协调/记忆/工作流层」[S15]；hook support depends on the client（原文）——Qoder 仅 MCP 面或可用 [S13]。记忆与 swarm 的机制未逐读（未知）。
同层对照与措辞修正：claude-squad 用 tmux+worktree 管多 CLI 会话（快照最近 push 2026-08-20，未归档；其余能力未见/未核）[S16]；coder/agentapi 已归档 [S17]；LangGraph 的 checkpoint 系与 prebuilt/interrupt 仍在主仓维护，langgraph-supervisor-py 已归档（2026-07-15）[S18]；RouteLLM 截至快照最近 push 2024-08（未归档，维护状态未确认——不作「停更」断言）[S21]。
订阅制 CLI 执行端的适配空缺（逐项核）
以下为各候选与订阅制 CLI 执行端（以 Qoder CLI 为重点核对对象；其他订阅制 CLI 同理）的适配空缺核对结果：
| 候选 | 结论 | 依据（等级） |
|---|---|---|
| Paperclip | 需自建：适配器清单未见 Qoder；process 适配器可包任意 shell 命令但官方明示无跨运行会话持久（不适合交互式会话复用）；提供 External Plugin 机制可自建适配器（须处理会话持久与人工接管） | S04/S25（doc） |
| claude-code-router | 未核：支持清单未见 Qoder；能否接入取决于 Qoder CLI 是否支持自定义端点覆盖——未知 | S12（doc） |
| ruflo | 部分：插件面（console/mods/hooks）为 Claude Code 专属→不可用；MCP 面面向支持 MCP 的客户端→Qoder CLI 具备 MCP 配置能力，或可用、需实测 | S13/S14（doc+path） |
| Magentic / Agent Framework | 需自建 wrapper：库形态，无任何现成 CLI 接线 | S07/S08（path+doc） |
选型护栏（工程约束三条）：保持订阅制 CLI 为执行者与交互会话形态、人工接管不被替换；不新增常驻「经理模型」；不把执行改为按量计费 API 调用。以上空缺意味着：对 Paperclip/CCR/ruflo 的任何试点，第一步都是「接入可行性验证」（端点覆盖或 MCP 形态），而不是流程改造。
框架对比与「最适合」的判定
主对比表（图例：✅原生已核 / ◐部分或需自建 / 未见=已读材料未发现（非绝对否定）/ 未核=本次未核到 / —不适用；不使用 ✖）：
| 项目（层级） | 管理/执行分工 | 多模型供应商 | CLI/tmux 接入 | Qoder 适配 | 状态/交接 | 预算/事件 | 学习/记忆 | 部署边界 | 迁移代价 |
|---|---|---|---|---|---|---|---|---|---|
| Paperclip（平台） | ✅ 评审/审批；执行者=本机 CLI [S03] | ✅ 每代理模型/harness [S01] | 本机 CLI 适配器 [S04] | 需自建（S25） | ✅ 心跳+合并（链 A）[S24] | ✅ 预算三件套(path)+看板 [S06][S05] | 未见（未核） | 自托管 Node+React [S01] | 高（整装） |
| Magentic/Agent Framework（模式） | ✅ 台账模式 [S08] | ✅ 包矩阵、代理级 client [S07] | 未见（库形态） | 需自建 wrapper | ✅ 停摆重规划+检查点（链 B）[S09] | ◐ 三上限；无预算 | ◐ 存储包可组合 [S07] | Python/.NET 进程 [S07] | 中高 |
| claude-code-router（网关） | 未见管理者概念 | ◐ 多协议/回退=文档声明(doc)；实现未核 [S12] | ✅ 一次性接线后接管 | 未核（端点覆盖能力未知） | ◐ 脚本层熔断/超时（fn）；供应商回退未核 [S12] | ◐ 成本观测；无策略 | 未见（未核） | 本机进程 [S12] | 低 |
| ruflo（插件/MCP） | ◐ swarm 工具存在；管理概念未核 | 取决于所接 CLI（未核） | ✅ 插件直装（CC 系）/MCP | 部分（仅 MCP 面或可用）[S13] | ◐ 视图已核；交接未核 | ◐ Cost/Events 视图 | ◐ 结构已核、机制未读 [S14] | 插件按账号权限 [S13] | 低-中 |
「最适合」判定标准（只认边界不认热度）：①贴合 CLI 会话形态；②不改变订阅额度形态（不接受必须转按量计费 API）；③部署增量越小越好。按此三条：Paperclip 机制满分、整装不达标；Magentic 信息结构满分、形态不达标且无现成 CLI 接线；CCR 属请求路由类，与心跳/台账不同层，且端点覆盖与订阅兼容均未知——非当前优先采用；ruflo 仅 MCP 面可探。结论：分机制借鉴（不引入组件）——合并唤醒与台账字段今天就能用。
图 3：三条工程边界到建议分级的判定路径。来源：按本报告选型标准与建议章节整理（[S24][S09][S12][S01][S07]）；数据口径：2026-10-16。
见图 3。它把「是否采用」的讨论收敛为三个可操作的判定档：机制符合且形态突破小的（合并唤醒、台账字段、回执强制）马上可做；收益/成本比尚不明的（CCR）列入观察；违背护栏或整装增量大的（整装平台、自建编排、执行转 API）暂不做。读图要点：其一，判定标准是工程边界而非社区热度——热度高的整装平台照样落在「暂不做」；其二，三档之间是显式条件（突破小/比不明/违护栏），边界变化时按条件重新归类，而不是一次定死。
| 判定 | 结论 | 依据 |
|---|---|---|
| 机制借鉴（马上可做） | 合并唤醒三件套（链 A）；台账五字段与停摆规则（链 B）；回执强制 [S03] | fn 级 [S24][S09] |
| 观察（非当前优先） | CCR 属请求路由类（与心跳/台账不同层）；端点覆盖与订阅兼容均未知——不进入试点清单 | doc+fn（脚本层）[S12] |
| 待论证（暂不做） | Paperclip 整装 / Magentic 自建 / ruflo swarm / 记忆服务化 / 上述任何「执行转 API」的方案 | [S01][S07][S14][S20] |
落地建议（唤醒/去重/预算、持续执行与状态真实性、人工接管、学习依据）
四组建议全部落在现有终端会话 + 本地脚本 + 项目文件内，零新依赖；每条给「来源机制（带等级）→ 最小做法 → 可数验收口径」。护栏重申：不新增常驻经理模型、不转 API、人工接管保留。四组均为工程建议，未经运行实测；效果以可数验收口径为准，非已验证的节省数据。
A. 主控的事件唤醒、去重与预算。 机制来源：链 A（coalesce+幂等键+回执不吞未来唤醒，fn，[S24]）、四类唤醒语义（doc，[S02]）、预算三件套（path，[S06]）。最小做法：①「唤醒主控」限定三类事件——任务完成回执、真阻塞/需决策、用户点名；②幂等分两层：事件层按「任务 / 事件 / 修订版本」标识——同一事件的重复触发可去重；通知层区分发送成功与接收/处理确认（sent 与 ack 分离），同一任务产生新 revision 时不因旧 sent 记录被吞，已发送或处理期间出现的新进展保留为未读版本、衔接进下一次通知（等价 coalesce 的「更新原通知」语义，但以 revision 为最小单位）；③预算三层观察表只统计三个可数指标：每日被唤醒次数/必读汉字量/重复派活次数（不换算公开 API 价）。验收：按预期事件 ID/版本对账——抽查恢复（暂停后继续）、重复（同事件重触发）、修改（同任务新 revision）三类场景均无漏报、无吞报，再核对三指标连续两周下降（不只看「回执数=完成数」的总数比对）。
B. 执行端持续执行与「状态真实性」。 机制来源：台账五字段（doc+fn，[S08][S09]）、comment-required（doc，[S03]）、停摆思想（fn，[S09]）。最小做法：①进度卡固定五字段：目标/当前事实/是否推进/下一步/执行者；②状态必须绑定可复核锚点（报告路径、sha256、日志名、命令输出片段），口号式「已完成」不算数（本报告的元数据与来源台账即示范）；③完成回执强制（成败都回写「结论+路径」）；④巡检加「疑似停摆」判定：须结合任务 handle（承诺的阶段产出）、阶段时限与可观测进度综合判断；长编译/长启动类等待不因两次巡检无新产物自动认定停摆（仅标黄提示、不打扰）。验收：随机抽 3 条状态行，按锚点 60 秒内复核通过。
C. 人工接管。 机制来源：计划评审 Approve/Revise 与检查点续跑（doc+fn，[S08][S09]）、活动日志信息结构（doc，[S05]）。最小做法：①任务单顶部「确认区」（目标/边界/验收），改动即视为介入；②接管靠「阶段账本」（进度文件顶部三行摘要）而非回放日志；③接管留痕：人工改写标注 [接管：谁/何时/改了什么]。验收：第三人按任务单+三行摘要在 5 分钟内复述状态并指出下一步。
D. 学习与依据。 机制来源：发现三元组（本报告方法示范）、ruflo 技能/记忆结构（path，[S14]）、记忆服务（meta，[S20]）。最小做法：①项目 Findings 文件每项带 source_ids / verification / applies_to / date，新增前查重同题；②Skill/HANDOFF 升版必须附来源锚点与核验等级——禁止把 doc 级宣称写成实测；③过期以「复核日期+重跑来源」处理，被推翻保留「已更正」行。验收：一个月后随机抽 5 条沉淀结论可复现到来源。
| 建议 | 分级 | 负责人 | 验证办法 | 回滚 |
|---|---|---|---|---|
| A 三类事件+合并去重+三指标 | 马上可做 | 主控 + 巡检脚本 | 两周指标曲线 | 恢复旧通知策略 |
| B 五字段+锚点绑定+回执强制 | 马上可做 | 执行端（模板） | 抽 3 条 60 秒复核 | 退回自由文本 |
| C 确认区+阶段账本+接管留痕 | 小范围试验 | 用户与主控 | 一次接管演练 | 取消确认区 |
| D 发现三元组+升版锚点纪律 | 马上可做 | 调研团队（本报告示范） | 抽 5 条复现 | 保留旧格式 |
| E CCR（请求路由类） | 观察（非当前优先） | — | 仅当出现端点覆盖与订阅兼容的可行依据再评估 [S12] | — |
| F Paperclip 整装 / Magentic 自建 / 记忆服务化 / 转 API 方案 | 暂不做 | 待论证 | 先跑 A-D 再评估 | — |
结论与建议
三条结论。第一，当前改进重点是补「事件与台账」，而非引入新工具：Paperclip 的合并唤醒（两轮核验后核到 heartbeat/queue.ts 准入路径）与 Magentic 的停摆重规划（fn 级核到 _magentic.py L1149/L1189）都是用结构化事件替代人读日志，本报告的 A/B 两组建议即为零依赖复刻 [S24][S09]。第二，CCR 属「请求路由类」，与心跳/台账层不同，且其端点覆盖与订阅兼容均未知——非当前优先采用；先做事件+台账+真实交付（建议 A–D），不改动现有认证与模型路由；整装平台与自建编排在边界内收益/成本比不成立 [S12][S01][S07]。第三，适配空缺是硬约束而非细节：Paperclip/CCR/ruflo/Magentic 均无现成 Qoder 通道（Paperclip 需自建 External Plugin，process 适配器无会话持久），任何落地讨论都不应绕过「保住订阅会话与人工接管、不新增常驻经理模型、不转 API」的护栏 [S25][S12][S13][S07][S08]。
行动清单：先做 A/B/D（零依赖，两周出曲线），准备 C 的接管演练；CCR 仅观察，待出现端点覆盖与订阅兼容的可行依据再评估，当前不开展接入或路由试验；其余保持「机制已借鉴、组件不引入」。以上建议均以背景所列适用假设为前提（保留现有订阅与权限形态、迁移成本受控）；对公开信息的小范围试用、以及对官方接口变化的增量评估不受此限。本报告为公开调研性质，未安装未运行任何框架、未做成本外推；结论与建议以来源台账与三条调用链为准。
参考来源
- [S01] Paperclip 仓库与 README（BYO agents、每代理模型/harness、看板；pin 90924d61；快照 head 560d8953）。 仓库
- [S02] Paperclip
docs/agents-runtime.md（心跳、四类唤醒、合并、限额；2026-03-26 更新）。 原文 - [S03] Paperclip
docs/guides/execution-policy.md（运行时强制 回写→评审→审批）。 原文 - [S04] Paperclip
docs/adapters/（claude-local、codex-local、opencode-local、cursor、pi_local、hermes、process、http 等；本机已登录假设）。 目录 - [S05] Paperclip
docs/guides/board-operator/（审批、成本与预算、委派、活动日志、仪表盘）。 目录 - [S06] Paperclip 预算路径（budget_policies / budget_incidents / budget-reservations / heartbeat-run）。 budget-reservations
- [S07] Microsoft Agent Framework（供应商包矩阵与编排包；@deecbcb0）。 仓库
- [S08] Magentic 官方文档（任务/进度台账、停摆重规划、三上限、计划评审、检查点；2026-09-21/10-06）。 文档
- [S09] Magentic 源码
_magentic.py（停摆 L1149-1158；_reset_and_replanL1189；reset L388/395-396；评审 L1027；循环 L1100/L1227；上限 L1262；@deecbcb0）。 源码 - [S10] microsoft/autogen：快照最近 push 2026-04-15（未归档）；官方 Discussion #7066（并入 Agent Framework）。 讨论
- [S11] Agent Framework 迁移博文（2026-02-20）。 博文
- [S12] claude-code-router README + 路由源码（网关 :3456；Profiles L228；RouteScriptRuntime L57/83/125/130/146 为脚本层 fn；供应商重试/回退/凭据池为 README 声明、未核实现；@057abaa1）。 README · 路由源码
- [S13] ruflo README（claude-flow v3.56.10；插件安装；MCP；TUI；hook depends on client）。 仓库
- [S14] ruflo 结构（plugin/*、v3 CLI、swarm-tools、console hooks；@1882006a）。 结构
- [S15] ruflo 概念指南（2026-09-07）。 文档
- [S16] claude-squad（tmux+worktree；快照最近 push 2026-08-20；未归档）。 仓库
- [S17] coder/agentapi（已归档）。 仓库
- [S18] LangGraph（checkpoint 系与 prebuilt/interrupt；supervisor 包已归档 2026-07-15）。 主仓 · 归档包
- [S19] OpenAI Agents SDK。 仓库
- [S20] Letta / mem0。 letta · mem0
- [S21] RouteLLM（快照最近 push 2024-08；未归档；维护状态未确认）。 仓库
- [S22] OpenHands。 仓库
- [S23] crewAI。 仓库
- [S24] Paperclip 合并唤醒两轮核验（@90924d61）：调度层
heartbeat/queue.ts（L3653/3661/3681/3688/3700/3739/4181）与modules/wake-queue/index.ts（L85-98）；门控回执层execution-wait.ts（L14-54）与heartbeat-protocol.md（心跳五步）。 queue.ts · wake-queue · execution-wait.ts - [S25] Paperclip 自建适配路径：
process.md（通用 shell；无跨运行会话持久）与creating-an-adapter.md（External Plugin）。 process · 自建适配器 - [S26] GitHub REST API 元数据快照（15 仓库；2026-10-16 02:59Z 采集，按研究截点，快照摘要 SHA256 014153fd…；当前 API 用于复查，复查入口为各仓库 API 对象链接，如 paperclipai/paperclip、microsoft/autogen、coder/agentapi、langchain-ai/langgraph-supervisor-py 等）
附录 A：主要结论与依据对照
| 结论 | 依据（来源与核验等级） |
|---|---|
| 唤醒合并调度链：主准入合并（admitWakeBehindIssueExecution→coalesced）与 deferred 排队合并（coalescedCount+1） | 链 A（两轮核验修正）：heartbeat/queue.ts L3653-3739、wake-queue/index.ts L85-98（fn）[S24] |
| 停摆→重规划有函数级实现与三上限 | 链 B：_magentic.py L1149-1158/L1189/L1262（fn）[S09][S08] |
| 运行时强制验收（回写→评审→审批） | 执行策略文档原文（doc）[S03] |
| 本地网关：脚本层熔断/超时（fn）；供应商重试/回退为文档声明（doc）；接线=一次性指向端点 | 链 C 分层：route-script-runtime.ts L57-146（fn）+ README L175/L228（doc）[S12] |
| 无现成 Qoder 适配：Paperclip 需自建、CCR 未核、ruflo 仅 MCP 面、Magentic 需 wrapper | S25/S12/S13/S07（doc/path）[S25][S12][S13][S07] |
| 归档/状态事实：agentapi 已归档；supervisor 包已归档；autogen/RouteLLM 快照 push 日期 | meta 快照 [S17][S18][S10][S21][S26] |
| 学习沉淀须带 来源编号+核验等级+适用范围 | 本报告方法与来源台账示范（自证）[S20][S14] |
附录 B：检查与验收清单
| 检查项 | 方法 | 结果 |
|---|---|---|
| 来源可溯（每条含 URL） | 台账 S01–S25 全部含可点击 URL；S26 为公开 REST API 采集的元数据快照（按研究截点），复查入口为各仓库 API 对象链接 [S08][S26] | 通过 |
| 核验等级分层 | 全文采用 doc/fn/path/meta 四级；「code-verified」旧称已废除（路径级改称 path-verified）[S24][S09][S12] | 通过 |
| 三条调用链抽查 | 链 A（两轮核验修正：heartbeat/queue.ts L3653-3739 + wake-queue L85-98；execution-wait 为门控回执）、链 B（_magentic.py L1149-1189）、链 C 脚本层（L57-146；供应商层 doc 未核）[S24][S09][S12] | 通过 |
| 措辞规则 | 「未见/未核」替代 ✖；未归档项目仅写快照 push 日期（autogen/RouteLLM/claude-squad）[S10][S21][S16] | 通过 |
| 适配空缺逐项核 | 四候选逐一给结论与依据；护栏（不转 API/不新增常驻经理模型）写入正文 [S25][S12][S13][S07] | 通过 |
| 凭证类表述条件化 | 「登录假设」（doc）与「令牌不出本机」（推断）已分离，后者标未核 [S04] | 通过 |
| 未安装未运行声明 | 全流程只读（GitHub API/raw、官方文档页）；关键源码以 commit pin 引用 [S26] | 通过 |
| 不做成本外推 | 建议不含省 token 百分比；额度效果以两周可数指标为准 | 通过 |
| 公开合规 | 公开版去除内部环境与调度细节；来源均为公开 URL；官方英文原文不整页转载 | 通过 |
| 图注合规 | 三图图注含来源/口径与来源编号；正文均「见图 N」[S02][S08][S24] | 通过 |
附录 C：研究方法与局限
方法：按七个调研问题筛选约二十个候选（元数据快查），选出三层代表后逐项打开官方文档原文（GitHub raw 全文、官方文档页），并对三个最相关对象各选定一条与本场景直接相关的调用链做函数级核验（链 A：Paperclip 合并唤醒；链 B：Magentic 停摆重规划；链 C：CCR 路由运行时），全部记录 文件+函数+行号+commit。选型排序只按三条边界，不用 star 热度。局限：其一，除三条调用链外均为 doc/path 级，未安装、未运行，「效果类」宣称（省额度、swarm 产出、记忆质量）一律未验证标未知；其二，Paperclip 预算限额算法、ruflo 记忆机制、CCR 场景配置细节未深读；其三，Qoder 与 CCR/ruflo 的接入可行性为未核（本报告给出的可行路径均为条件式）；其四，快照随时间变化——Paperclip head 在会话内即从 90924d61 前移至 560d8953，引用以 pin 为准；其五，建议章节含作者对目标边界的判断，边界变化时需重估。复核指令（复现以 pin commit 读内容为准；查当前 HEAD 只是增量复查、不替代旧 pin）：gh api repos/paperclipai/paperclip/commits/90924d61b378495e5a7f5239fcac03b81060ad60 --jq .sha、gh api repos/microsoft/agent-framework/commits/deecbcb062198f926516f89b65e5b1676e4514c2 --jq .sha、gh api repos/musistudio/claude-code-router/commits/057abaa1 --jq .sha（依次对应链 A、链 B、链 C 的 pin；HEAD 是否前移另用 gh api repos/paperclipai/paperclip/commits/master --jq .sha 一类查询作增量复查）。
修订说明（2026-10-16）：其一，链 A 初版把 execution-wait.ts 的门控回执误作调度合并依据，已改用 heartbeat/queue.ts 与 modules/wake-queue 重新核验并更正正文与台账；其二，CCR 的脚本层（fn）与供应商层（doc）已分层，供应商回退未获实现级核验；其三，Magentic 停摆证据仅作借鉴来源；其四，Dots 相关结论见姊妹短评《OpenAI Dots 观察短评》。