AutoSwarm‑Shadow‑Adapter

它是什么 – 一个用于 AutoSwarm AI 代理编排框架的插件，允许基于 DAG 的工作流在某个步骤需要人工审核（“Carbon”员工）或外部 GPU 工作者（“Silicon”BYOC 工作者）时进行非阻塞暂停。暂停由轻量级的 ShadowModeAdapter 处理，它将待处理任务存储在隔离的 SQLite WAL 数据库中，并立即返回 AWAITING_HUMAN 状态，因此并行 DAG 的其余部分继续运行。

核心能力

功能	作用
非阻塞拦截	在 < 50 毫秒内捕获任务，将其暂存到 `shadow_tasks.db` 中，并释放引擎线程。
人工与远程工作者门户	基于 FastAPI 的 REST API + React 19 + Tailwind UI（`http://localhost:8800`），人工可以认领任务、查看 Markdown 简报，并上传最多 5 个文件（总计 ≤ 50 MB）。
BYOC 计算	远程节点运行 `shadow-worker` 守护进程，通过 JWT 认证，拉取任务，执行本地模型（Ollama、Anthropic、OpenAI 等）并推送结果。
审计就绪的持久化	所有提交都带有时间戳、归属信息，并以不可变方式存储；SQLite WAL 确保崩溃恢复和状态恢复。
零核心更改	适配器在 AutoSwarm 的 `ADAPTER_CLASSES["shadow"]` 注册表中注册自身；无需修改 AutoSwarm 主代码库。
企业工件注册表	上传的交付物保存在 `CorporateArtifacts` 下，并带有 SHA-256 哈希，使下游代理可以搜索。

工作原理（高层流程）

AutoSwarm 创建工作项，并看到该角色的 preferred_external_agent: shadow。
ShadowModeAdapter 拦截任务，构建 Markdown 简报，将记录写入 shadow_tasks.db，并返回 AWAITING_HUMAN。
人工或硅基工作者登录 React 门户（或运行 shadow-worker）并认领待处理任务。
工作者查看上下文，编写解决方案说明，并可选上传文件。
适配器将 Phase.APPROVED 写入 AutoSwarm 的原生 store.db（WAL 模式），触发原生 DAG 钩子。
下游节点自动恢复，并将新上传的工件作为其输入的一部分。

快速开始（Python 3.10+）

# 1️⃣ 从 PyPI 安装包
pip install AutoSwarm-shadow-adapter

# 2️⃣ 在 AutoSwarm 入口点注册适配器
#    （例如，AutoSwarm 应用程序的 main.py）
from opc.layer3_agent.adapters.registry import ADAPTER_CLASSES
from shadow_adapter import ShadowModeAdapter, start_server_in_thread

ADAPTER_CLASSES["shadow"] = ShadowModeAdapter   # 插件注册
start_server_in_thread(port=8800)               # 启动 FastAPI + React UI

# 3️⃣ 像平常一样运行你的 AutoSwarm DAG。

如果你更喜欢单独的进程，只需运行 side-car 服务器： shadow-serve --port 8800。

远程硅基工作者（BYOC）

# 示例：使用 Ollama 的远程 GPU 工作站
export OLLAMA_HOST="http://localhost:11434"
shadow-worker \
  --server-url http://192.168.1.100:8800 \
  --username dev_node_1 \
  --password secret123 \
  --role senior_developer \
  --provider ollama \
  --model llama3.3:70b

守护进程持续轮询 API，认领与其 role 匹配的任务，在本地运行指定模型，并将结果发布回去。

配置（环境变量 / .env）

变量	必需？	默认值	含义
`SHADOW_JWT_SECRET`	是	–	用于签名 JWT 令牌的密钥（≥ 32 个字符）。
`SHADOW_DB_PATH`	否	`./shadow_tasks.db`	隔离的 SQLite WAL 数据库的路径。
`SHADOW_OPC_STORE_PATH`	否	`.opc/projects/default/store.db`	AutoSwarm 主存储数据库的路径（适配器在其中写入恢复阶段）。
`SHADOW_UPLOAD_DIR`	否	`./shadow_uploads`	上传文件存储的目录。
`SHADOW_MAX_FILES_PER_SUBMISSION`	否	`5`	每个任务的最大文件数。
`SHADOW_MAX_FILE_SIZE_MB`	否	`10`	每个文件的最大大小。
`SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB`	否	`50`	每次提交的最大总负载。
`SHADOW_API_PORT`	否	`8800`	FastAPI 服务器和 React SPA 的端口。

谁会使用这个？

自由职业者或独立创始人，希望将繁重的工作外包给远程 GPU 节点，同时保留最终的人工签字。
企业，需要审计级的人工参与检查点（SOC 2、ISO 27001、GDPR），而不会停止并行 AI 工作。
团队，同时运行多个客户合同，需要基于队列的“人工即服务”层。

限制与注意事项

适配器仅适用于 AutoSwarm（它针对的特定 DAG 引擎）。它不是其他框架的通用 HITL 层。
人工任务存储在 单独的 SQLite WAL 中；如果需要长期保留，必须备份 shadow_tasks.db。
文件上传上限为 5 × 10 MB（可配置）——大型二进制资产需要外部存储。
安全性依赖于 JWT + bcrypt；你必须保护 SHADOW_JWT_SECRET，并在生产环境中通过 TLS 运行门户。

开发与测试

# 运行完整测试套件（55 个测试）并带有覆盖率
pytest tests/ -v --cov=shadow_adapter --cov-report=term-missing

# 模拟 AutoSwarm 引擎以进行快速演示
python tests/mock_AutoSwarm_engine.py

该仓库包含类型检查代码、基于属性的模糊测试和集成测试，验证适配器在引擎重启和并发任务负载下能够存活。

链接

GitHub: https://github.com/AhmadHassan-BTed/AutoSwarm-shadow-adapter
PyPI: https://pypi.org/project/AutoSwarm-shadow-adapter/
AutoSwarm 核心仓库: https://github.com/HKUDS/AutoSwarm

为 AutoSwarm 社区构建——一座非侵入式、人工参与的桥梁，让 AI 代理和真实人员能够协同工作，而不会使工作流死锁。

AhmadHassan-BTed/AutoSwarm-Shadow-Adapter