ShadowFlow

ShadowFlow 是面向"合约优先"的多智能体编排运行时。它用一份 canonical YAML/JSON

schema 描述多 agent 协作流程，通过 CLI 和 HTTP API 两个同构入口执行，并输出结构化

的 run / step / trace / artifact / checkpoint 结果。

## 我们要解决什么问题

主流 agent 框架（LangGraph / AutoGen / CrewAI）把流程逻辑、模型调用、状态管理全部

硬编码在代码里，导致工作流无法版本化、无法跨进程恢复、无法审计、也无法在不同 LLM

provider 之间迁移。更关键的是，agent 的中间状态和产物全部锁在中心化云服务里，缺

乏去中心化可信基础。

## ShadowFlow 的五个技术点

1. Contract-first schema：Tool / Skill / Role / Agent / WorkflowTemplate 五层模板与

运行时分离，可版本化、可审计。

2. 同构入口：CLI (agentgraph run) 与 HTTP API (/workflow/run) 共用同一套执行层。

3. 可插拔 provider：同一条 workflow 可在 Codex CLI / Claude CLI / OpenAI Responses /

Anthropic Messages 之间切换，并原生支持 0G Compute 的 DeepSeek / Qwen / Gemma

等 TEE 推理。

4. 0G 原生集成：checkpoint store 对接 0G KV（链上状态恢复）、artifact 上链到 0G

Storage（Merkle 可验证）、agent 注册表部署到 0G Chain（ethers v6 / evmVersion

cancun），让 agent 的"记忆 + 产物 + 契约"全部可验证、可恢复。

5. 高阶模板层：内置 single-reviewer / planner-coder-reviewer / research-review-

publish 三类 workflow pattern 与 6 种角色原型，一条 agentgraph scaffold 即可

生成完整可执行工程。

## 技术栈

Python 3.9+ · Pydantic v2 · FastAPI · React 18 · ReactFlow · TypeScript · Vite ·

Tauri · 0G Storage / KV / Chain / Compute · Solidity · ethers v6

## 面向用户

想在去中心化基础设施上构建可审计 agent 工作流的开发者、需要跨多 LLM 复现实验的

研究团队、以及需要把关键 agent 状态上链的 Web3 应用。

黑客松期间完成的核心里程碑：

【Phase 1 — Runtime 合约层】（已完成）

- 统一 runtime contract skeleton：run / step / trace / artifact / checkpoint 五元组

- CLI / HTTP API 同构入口（agentgraph run / POST /workflow/run）

- Canonical workflow schema 规范文档与模板编译器

- 并行 fan-out + barrier join 基线

- 三个端到端可重复执行样例：docs-gap-review / parallel-synthesis / research-review-loop

- 四个 provider adapter：Codex CLI / Claude CLI / OpenAI / Anthropic

- Markdown writeback 后端，runs / artifacts / checkpoints 全部结构化落盘

【Phase 2 — 0G 集成层】（已完成）

- ZeroGCheckpointStore：基于 0G KV 的链上 checkpoint store 参考实现

- httpx 客户端抽象，支持本地 Memory / File / 0G KV 三种模式切换

- 可选依赖组 shadowflow[zerog]，pip 一键启用

【Phase 3 — 自演化骨架】（本次黑客松重点）

- Step 1：ActivationBandit 上下文 bandit 学习器（contextual bandit）

- Step 2：训练数据累积脚本 + feedback writeback 回路

- Step B：ConnectionResolver v2 — 基于能力依赖图的拓扑推断

- shadowflow do：一键 goal → execute 命令，集成 Codex full-auto 模式

【高层模板】

- 6 种 role archetype + 3 种 workflow pattern 预设

- policy_matrix / stages / lanes / task-kind → pattern 推荐式入口

【未来两周】

- 示例迁移清理 + checkpoint 恢复细化

- 0G Storage artifact 上链 demo

- 可视化工作流编辑器（web/）与 Tauri 桌面端 MVP 联调

尚未启动融资，当前由核心团队自筹开发，专注打磨 Phase 3 自演化骨架与 0G 原生集成。