co-app

用数据流蓝图约束 agent 行为的编排引擎。把任务拆成节点，在节点间加校验和 带反馈的改进循环，让 agent 产出可控；co-app 自身可作为节点嵌套复用。

设计文档见 docs/superpowers/specs/2026-07-02-co-app-design.md。

当前状态

• ✅ *.coapp.json 工程文件标准（@co-app/schema）
• ✅ 执行引擎：加载校验、图结构检查、数据流调度、JSONL 运行轨迹（@co-app/engine）
• ✅ worker 节点：hardcoded（本地 JS 模块）与 agent（Claude Agent SDK）
• ✅ validator 节点：pass/fail 分支分流（agent / hardcoded / co-app 实现）
• ✅ looper 节点：continue 反馈回灌、break/maxIterations 终止
• ✅ 嵌套 co-app：worker / validator / looper body 三种用法，循环引用检测，scoped trace
• ✅ 蓝图编辑器（只读）：渲染工程文件蓝图、JSONL 轨迹回放（apps/editor）
• ✅ 蓝图编辑器（编辑）：增删改节点/连线、属性面板、连线校验、撤销/重做、 布局持久化（顶层可选 ui 字段）、保存回 .coapp.json

快速开始

pnpm install
pnpm test
pnpm coapp run examples/greeting/greeting.coapp.json --input name=World

looper 示例（无需 LLM）

pnpm coapp run examples/review-loop/slogan.coapp.json --input product=co-app

agent 示例（需 Claude Code 登录或 ANTHROPIC_API_KEY）

pnpm coapp run examples/haiku/haiku.coapp.json --input topic=秋雨 --trace haiku.jsonl

agent 节点需要本机可用的 Claude Agent SDK 凭据（Claude Code 登录或 ANTHROPIC_API_KEY）。

蓝图编辑器

pnpm --filter @co-app/editor dev

浏览器打开后，拖入工程文件与轨迹即可：

• 蓝图：拖入任意 *.coapp.json（如 examples/review-loop/slogan.coapp.json）
• 回放：拖入运行时 --trace 生成的 *.jsonl（仓库自带 examples/review-loop/demo-trace.jsonl，pnpm demo:trace 可重新生成）

时间轴每个刻度是一个轨迹事件（颜色=事件类型），点击跳转、←/→ 单步、 "播放"自动步进；未触发的分支节点以虚线暗显（node_skipped）。

编辑：打开工程文件后即可拖动节点（位置存入文件顶层可选 ui 字段，引擎忽略）、 从输出端口拖到输入端口连线（自动校验：输入单边、类型兼容、防环）、 Backspace 删除选中节点/边、工具栏添加节点、⌘Z/⇧⌘Z 撤销重做、⌘S 或"保存" 写回文件（Chrome 走系统保存对话框，其他浏览器下载）。加载轨迹进入回放模式时 编辑自动锁定，"关闭轨迹"恢复。

往返保证：打开 → 保存不改变文档内容（键序固定 coapp, name, description, inputs, outputs, nodes, edges, ui，2 空格缩进）。

已知限制：连线校验尚不阻止"互斥分支汇聚到同一下游节点的不同输入端口"（该节点永不触发）； 完整的分支可达性分析计划在后续版本加入。

工程文件（示例）

见 examples/greeting/greeting.coapp.json：节点声明输入/输出端口， 边按 $in.<port> / <node>.out.<port> → <node>.in.<port> / $out.<port> 连线，引擎按数据流调度（输入就绪即触发，无依赖节点并行）。

节点类型

kind	输出端口	说明
worker	自行声明	agent / hardcoded / coapp 实现
validator	pass（透传输入）/ fail（{input, reason}）	恰好一个输入端口
looper	done（最终产物）/ failed（{reason, lastResult, iterations}）	body+judge，continue 反馈回灌

安全提示：运行 .coapp.json 会通过动态 import 执行其引用的本地 JS 模块， 信任模型等同 npm run——只运行你信任的工程文件。