来源：GitHub (★97)
URL: https://github.com/LeXwDeX/OpenCode-GraphAgent
精读日期：2026-08-19
模型：DeepSeek V4 Flash（AI 生成，人工未审校）
正文获取：全文

一、核心论点/事实

  • OpenCode-GraphAgent 是一个将任务分解为有向无环图（DAG） 子代理依赖图并驱动其完成的编码代理，状态持久化、崩溃可恢复、终端可全程检视与控制。
  • 项目以 GraphAgent 为产品名发布，与 OpenCode 官方无关联或背书；v1 版本仅接受影响稳定性、数据完整性或核心 DAG 的窄范围兼容补丁，不新增平台功能或大型基础重构。
  • 工作流由节点和依赖边构成：每个节点是拥有独立代理和上下文窗口的真实子会话，边表示下游节点消费上游节点输出；节点按依赖顺序逐波（wave）并行执行，独立工作并行、依赖工作等待。
  • 父代理（主对话）拥有图，设计图后启动，节点上报或工作流完成时被唤醒，从不轮询；某波失败时父代理重写失败段，引擎继续执行，视图始终显示当前图而非重写历史。
  • 节点支持超时、重试预算、结构化输出契约；门控节点（Gate）负责判断（审查/验证/仲裁），输出裁决（verdict）并条件化下游节点。
  • 工作流库支持项目/全局/内置三级作用域，可按名称启动；workflow 命令选取参考拓扑并重定向到当前任务。
  • 事件溯源状态配合显式状态机，SQLite 读模型在发布事务内投影；崩溃恢复从持久证据调和，绝不伪造提供商工作。
  • 执行位置权威：每个工作流行携带创建会话的目录戳，每次所有权检查从数据库重读，防止同一项目兄弟工作树互相操作对方工作流。
  • 深度模式准入：有界问答（1/3/5 轮）生成带指纹的需求简报并给出裁决，之后才启动昂贵图执行。

二、方法/架构拆解

  • 核心架构：DAG 执行引擎 + 事件溯源状态机 + SQLite 读模型投影；节点按波次并行，受并发限制；父代理通过回调唤醒，非轮询。
  • 节点类型：普通节点（单提示词代理，可配超时/重试/结构化输出）、门控节点（审查/验证/仲裁，输出裁决）、自定义代理。
  • 工作流规范：YAML 文件描述图结构，支持编译为节点图；低层节点字段保留供 blocks 无法表达的场景使用；工具模式渲染为结构化 YAML 规范，字段名错误由提供商拒绝而非验证时发现。
  • 模型解析顺序：节点级 tier → worker 代理模型 → 父会话模型；均未配置则工作流不创建并提示配置；节点永不自行命名模型，由图声明。
  • 工作流库三级作用域：项目（仓库内提交，团队共享）→ 全局（opencode 配置目录）→ 内置（随发布安装）；解析顺序为项目 > 全局 > 内置，同名项目文件遮蔽全局。
  • 文件指针优化：节点输出为单个绝对文件路径时捕获为指针，结果操作返回指针，父代理读取文件；内联和结构化负载不变。
  • 终端控制：命令面板提供工作流列表、波序节点视图（实时状态）、节点详情（截止倒计时）；侧边栏面板显示每会话进度；HTTP API 镜像所有工具操作。
  • 兼容性：支持 Claude Code hooks（26 事件 × 5 执行类型）、CJK/IME 终端修复、每工作流工作树隔离、独立 Go 配置助手。
  • 关键配置：required: true 标记关键节点，审查/仲裁 worker；推理变体用于 DAG 子会话；tier 覆盖全局配置。
  • 最小示例：依赖审计工作流——标记 {{inventory}} 中过期/重复依赖并提出升级顺序，通过 "run the dependency-audit workflow" 按名启动。
  • 保存规则：已保存规范不得固定模型、模板变量必须存在且必填；"save this as a reusable workflow" 可交互建立阶段和门控并写入指定作用域。

三、值得注意的局限/争议

作者承认的局限：

  • v1 不新增平台功能或大型基础重构，后继项目将独立重新设计运行时，不扩展 v1 架构。
  • 不兼容或未修复的架构缺陷（影响稳定性、数据完整性或核心 DAG）仅接受窄范围补丁。
  • 与 OpenCode 官方无关联，可能暗示 API/生态兼容性不受官方保障。

AI 判断的局限/争议：

  • 事件溯源 + SQLite 投影虽保证一致性，但复杂图（大量节点/波次）下事务内投影可能成为性能瓶颈。
  • 目录戳所有权检查依赖会话移动时戳随动，若会话跨机器迁移或容器重建，戳的有效性存疑。
  • 深度模式准入（1/3/5 轮问答）可能对简单任务过度设计，增加延迟；对复杂任务又可能简报不充分。
  • 文件指针优化仅针对单绝对路径输出，多文件或目录输出仍走内联，可能造成大负载传输。
  • 模型解析顺序中 tier 优先于 worker 模型，若 tier 配置错误可能导致所有节点意外使用同一模型，降低灵活性。

四、与 RRLab 研究的关联

  • Harness 工程：事件溯源 + 状态机 + SQLite 读模型投影的崩溃恢复设计，可直接借鉴到 RRLab 的 Agent 执行框架，提升任务持久化和故障恢复能力；目录戳所有权检查为多工作树隔离提供参考。
  • 多模型协同：节点级模型解析顺序（tier → worker → 父会话）和"节点永不自行命名模型"的声明式设计，为多模型编排提供清晰的分层策略；门控节点（审查/仲裁）模式可复用于多模型交叉验证。
  • 模型评测：深度模式准入（有界问答 + 需求简报 + 裁决）可作为评测前置过滤机制，降低无效任务对评测资源的消耗；波次并行执行和重写历史不计数到终态的设计，为评测中的失败重试策略提供参考。
  • Agent 落地：工作流库三级作用域（项目/全局/内置）和按名启动机制，适合企业内标准化流程沉淀与分发；Claude Code hooks 兼容性（26 事件 × 5 执行类型）为跨平台 Agent 集成提供适配思路。
  • AI 原生产品：终端实时图检视 + 侧边栏进度 + HTTP API 镜像的全方位可观测性设计，是 AI 原生工具"透明可控"理念的实践范本；"无需配置即可试用"的渐进式配置哲学值得产品化借鉴。

本笔记由 DeepSeek V4 Flash 自动生成，未经人工审校。原文链接：https://github.com/LeXwDeX/OpenCode-GraphAgent