AutoSwarm-Shadow-Adapter：给智能体 DAG 装上"人类暂停键"

一句话概括：它让 AI 智能体在需要人工签字时先把活儿挂起来，而不是卡死在那儿等，然后自动恢复下游流程。

一、一个真实的尴尬场景

想象你在用 AutoSwarm（HKUDS 出品的开源智能体编排框架）搭一条"公司流水线"：AI 经理拆任务，AI 程序员写代码，AI 法务审合同，AI 市场做投放。整条 DAG 并行跑，看起来很美。

直到某天，法务角色需要人看一眼——合规框架（SOC 2、GDPR、ISO 27001）白纸黑字写着"必须人工签署"。于是问题来了：这一层谁来批？

传统做法只有三种，都很痛：

1. 让 AI 自己拍板——合规上直接违法；
2. 在 DAG 里插一个阻塞等待——执行线程被占住，超时就是引擎崩溃，其他并行分支跟着受影响；
3. 人工介入靠人肉盯着日志——谁在等、等了多久、批没批，全靠考古。

而当你想让"别人家的显卡"参与进来（自己办公室那台 4090、朋友的云主机）时，又会遇到另一个问题：远程节点怎么安全地领任务、交成果，还不污染中央引擎？

AutoSwarm-Shadow-Adapter 就是给这两个问题的一个统一答案。

二、它到底做了什么

1. 非阻塞拦截：<50ms 让出线程

这是整个项目最核心的设计。适配器继承自 OpenOPC 的 ExternalAgentAdapter 基类，注册进 ADAPTER_CLASSES["shadow"]。当 DAG 调度到一个标记了 preferred_external_agent: shadow 的角色时：

• 适配器把任务上下文编译成结构化 Markdown 简报（brief_md）
• 落库到独立的 shadow_tasks.db（SQLite WAL 模式）
• 立刻返回 AWAITING_HUMAN 状态，执行线程马上释放

关键在于"释放线程"这四个字。DAG 里那些跟法务无关的分支——代码生成、测试执行、资料调研——继续并行跑，不会被一个待签字的节点拖死。对比 README 里那张功能对比表：标准 AutoSwarm 遇到人类响应超过 900 秒就是引擎超时崩溃，而接了 Shadow Adapter 则是"零超时，时长无上限"。

2. 影子模式：人肉外包工 + 远程硅基员工

拦截下来的任务进入一个 React 19 + Tailwind 的门户（默认 http://localhost:8800），两条领取路径：

• 人类承包商：JWT 登录后认领任务，在 TaskWorkspace 里读简报、下载上游交付物、写说明、附件提交（单次最多 5 个文件 / 10MB 单文件 / 50MB 总包）
• 远程 BYOC 节点：shadow-worker 守护进程轮询 API，可以挂 Ollama 本地模型、Claude API、OpenAI GPT-4o，各自带各的密钥和算力

作者给这套设计起了个名字叫"碳硅连续体"（Carbon-Silicon Continuum）——人类（碳）和远程机器（硅）都是集群里的一等公民员工。

3. 状态机接管：提交即恢复

任务状态在影子库里走 pending → claimed → submitted → resumed，偶尔绕一圈 rework_requested → pending（人工打回让 AI 重做）。交付物提交后，OpcResumeRepository 直接往宿主引擎的 store.db 里写 Phase.APPROVED，触发 OpenOPC 原生的 phase hook，下游 DAG 节点自动接着跑。

这里有个细节值得注意：写库用的是 OpenOPC 的 OPCStore API 带 validate_transition() 校验，还有直接 WAL 写入的兜底路径——说明作者考虑过宿主引擎接口变动或异常黑洞的情况。

4. 零修改：symbiont 架构

整个项目不改一行 OpenOPC 核心代码，只是往注册表里塞一个 key、配一份 YAML：

roles:
  legal_counsel:
    title: "Human Legal Counsel"
    execution_strategy: external
    preferred_external_agent: shadow

宿主要么用 start_server_in_thread(port=8800) 把门户嵌在自己进程里，要么跑 shadow-serve --port 8800 当独立 sidecar。对上游框架作者来说，这是最容易被接受的扩展姿势。

三、上手门槛：CLI 极简，Web 完整

对只想试试的人（CLI 路线）：

pip install openopc-shadow-adapter
shadow-serve --port 8800

门户和 REST API（/api/v1）就起来了。默认配置走 .env（项目给了 .env.example 模板），JWT 密钥、数据库路径、上传上限都能改。

对要做完整闭环的人：还得装 Node.js 18+ 构建 React 前端（npm install && npm run build，产物会被打进 wheel），并准备 OpenOPC 宿主环境。

没有 OpenOPC 也能跑：代码里做了 ImportError 兜底，会退化成一套 mock 的 dataclass（Task/TaskResult/ExternalAgentAdapter），所以单元测试可以独立跑。

四、争议与局限

必须说清楚几件事：

• 无容器化：仓库里没有 Dockerfile、没有 docker-compose、没有 K8s 清单。虽然文档提到"可以跑在 Docker 容器里"，但那指的是你自己去写，不是现成的。这对需要标准化交付的企业是硬伤。
• 强依赖宿主：虽然 opc 是可选依赖、缺失时有 mock 回退，但真正有价值的路径（phase hook 唤醒下游 DAG）必须依赖 OpenOPC 的 store.db schema 与内部 API。宿主一旦升级，OPCStore 接口或 delegation_work_items.phase 结构变化，这边就得跟着改——所谓"零修改"是针对当下版本而言。
• 单人开发：contributors 只有 1 人（58 次提交），58 个 commit 一个 release（v1.0.0，2026-08-20）。README 写 64 个测试、用 pytest + hypothesis 做模糊测试，CI 也有 workflow，但维护面窄，作者精力是最大变量。
• 文档与代码有小出入：README 徽章写 React 19，而 frontend/package.json 里实际是 react@^18.3.1；README 前言还残留着 opc.layer3_agent 命名空间与 "AutoSwarm" 品牌的混用痕迹（项目已改名为 OpenOPC）。这类不一致在快速迭代期很常见，但会让人在集成时多花时间。
• 安全默认值偏保守但到位：.env.example 里 JWT 密钥是占位符并注明生产必须替换，首个注册用户自动成为管理员，文件扩展名白名单、哈希校验（SHA-256）都在。但 SHADOW_API_HOST=0.0.0.0 默认对外监听，配合示例里的弱密码 password123，生产部署必须改。

五、行业意义：把"人在回路"从阻塞变成一等公民

这个项目最值得注意的，不是它做了什么技术，而是它选了一个被多数 agent 框架回避的痛点。

现在市面上的 agent 编排框架，绝大多数把"人类审批"当成异常路径——一个 while 循环、一句"请人工确认"、或者干脆让 LLM 用工具调用模拟人类签字。而 Shadow Adapter 把它做成了正常运行路径上的一个正式状态：有独立的数据库、有专门的 UI、有完整的状态机、有审计留痕（不可变时间线 + 用户归属）。

这背后是 agent 工程正在发生的真实转向——从"全自动"回到"可监管"。当 AI 开始承担法务、财务、安全这类有法律后果的角色，"人类必须能随时插手，并且插手之后流程能自己长回去"就变成了硬需求，而不是加分项。

"碳硅连续体"这个提法也折射出另一个方向：BYOC（自带算力）正在成为 agent 生态的标配。中心化 API 调用有配额、有延迟、有数据出境问题；让用户自己的机器跑本地模型、同时把人的判断力也纳入同一套调度协议，是更可持续的形态。

从数据看，它在 2026 年 7 月 25 日创建，到 10 月中旬已经积累 4928 star、58 次提交，单人开发四个月跑到近 5k star，在 AutoSwarm 生态（母仓 2201 star）之外开出这么一条线，说明"HITL + 分布式算力"这个组合的需求是真实的。

六、适合谁

场景	适配度
需要合规人工签署的 AI 流水线	★★★★★
想用自己/租用的 GPU 跑 agent 任务	★★★★☆
已在用 AutoSwarm/OpenOPC	★★★★★
想要开箱即用的容器化交付	★★☆☆☆
只想找开箱即用的独立 agent 框架	★★☆☆☆

一句话建议：如果你在跑 AutoSwarm/OpenOPC 生态、且工作流里有必须人签字的环节，这个项目值得直接接；如果你需要的是能独立跑、不依赖宿主的通用 agent 编排工具，它不是最优选。