[!info] related notes

• 所属 MOC: ai-agent-application-moc
• 历史架构: hermes-ai-office-control-plane-architecture-history
• 相关概念: agent-configuration-and-execution-provenance、workflow-orchestration

ForgeFlow：工程策略与架构演进

当前代码定位（2026-10-06）

核对 GCP checkout 的 README（981410a） 与 package.json：当前包为 forgeflow-pi，版本 3.0.0-alpha.1。这是代码版本，不代表已发布稳定 Release。

当前 ForgeFlow 是 Pi Agent 的薄工程策略包，负责逻辑模型角色、确定性不变量预检、单 worktree 单 writer 约束和候选版本证据提醒。Pi 及其插件负责执行、子任务、review loop、worktree、恢复和调度；工程方法由 Skills 提供。

因此下面的 durable lifecycle controller / OpenHands 描述属于 V1 历史，不能作为当前实现承诺。项目入口见 ForgeFlow 项目资产。

V1 历史记录（2026-09-07）

下文保存 V1 的架构、验证与面试材料；其中实现判断限定于该版本。

V1 当时定位

ForgeFlow 是由早期 Pixel Agent / Hermes AI Office 方向重构演进出的独立自主软件工程系统。V1 当时仓库已经收敛到纯粹的软件工程自动化产品边界，不再以“AI 办公室 / 像素员工可视化”为核心概念。

V1 当时公开仓库为 BakerSean168/forgeflow，版本为 v1.0.0。它不是单一 Coding Agent，也不把 Agent 返回“done”视为完成；核心原则是：模型可以提出下一步动作，但 ForgeFlow 自己持有软件交付生命周期的权威状态。

核心执行链

V1 的主链路可以概括为：

Objective
  ↓
Durable Plan / dependency graph
  ↓
Dependency-ready WorkItems
  ↓
Implementation resources
  ↓
Independent exact-SHA review
  ↓ fail
Repair / retry ─────────────┐
  ↓ pass                    │
Serial integration ◀────────┘
  ↓
Provider cleanup + worktree retirement
  ↓
Delivery / release evidence

Plan、WorkItem、Execution、Review、资源选择、worktree、Supervisor state 与事件都进入 durable state；聊天上下文本身不是系统真值。

Control Plane 与执行平面

ForgeFlow 把生命周期控制权和真正写代码的 Agent 执行平面分开：

• ForgeFlow：持久化计划、依赖图、执行身份、writer ownership、资源选择、Review lineage、Recovery、Integration、Cleanup 与 Release Attestation。
• OpenHands：作为版本固定的 Agent Server / execution plane。
• Provider-native worker：例如 Antigravity，可作为另一类受控执行资源。
• Codex / Claude Code / OpenCode / DSH / ZCode 等：作为具体 Coding / Review backend 被调度。
• Agent Harness：负责给每次执行投影项目 instructions、Skills、MCP 能力；ForgeFlow 仍然负责资源与模型路由，不把能力投影层变成第二个调度控制面。

因此现在不再适合把系统描述成“Hermes -> AI Office -> OpenHands Supervisor 的 UI/桥接项目”，而应描述成独立的 autonomous software engineering control plane / lifecycle authority。

AI Supervisor 的真实边界

ForgeFlow Supervisor 消费的是 controller 生成的 bounded projection，并返回版本化 typed decision。Supervisor 可以判断：

• 创建或继续 Execution
• Retry / Switch Route
• Request Review
• Create Repair
• Replan remainder
• Create bounded child plan
• Park external/resource gate
• Escalate / No Action

但 Supervisor 不能直接修改 SQLite、执行任意 shell、伪造 evidence、批准自己的实现或绕过安全门禁。真正的副作用由 deterministic kernel / action validator 执行。

这个边界比“让一个大模型自己循环调用工具直到完成”更接近生产控制系统：模型负责判断，确定性控制器负责权限和状态变化。

Review / Repair / Quality Gate

ForgeFlow 把 Implementation 与 Review 设计成不同生命周期阶段：

• Review 与候选实现的精确 Git revision / exact SHA绑定。
• Reviewer 与 Implementation writer 分离。
• Review 失败时进入有界 Repair / retry，再进行独立 re-review。
• 多 WorkItem 集成后仍需要语义/集成门禁，而不是“Git merge 成功就算完成”。
• provider 自己报告成功不能替代 Git linkage、changed-file scope、clean committed state、Review provenance、cleanup 与 release identity 等控制器证据。

这套机制可以对外描述为 independent LLM review + deterministic evidence gate / Quality Gate；除非专门构建 Judge rubric 与校准数据集，否则不应简单包装成完整的“LLM-as-Judge 评测体系”。

Durable Recovery 与并发安全

ForgeFlow V1 当时比较有辨识度的工程点包括：

• durable Plan / Execution / Review state
• one active root Plan per project + queue
• dependency-aware parallel WorkItem wave
• literal Git worktree 与 controller-owned provenance
• single mutable writer / writer fencing
• lease、CAS、idempotency 与 duplicate suppression
• immutable retry / fallback lineage
• restart-safe reconciliation
• provider cleanup proof 与 worktree retirement barrier
• fail-closed repository / writer / provenance 校验

这里的核心不是“重试很多次”，而是即使 provider、进程或控制面重启，系统仍能依靠 durable evidence 判断谁拥有写权限、V1 当时候选 revision 是什么、是否已经被审查、是否允许继续交付。

Skills / MCP 与工具能力

V1 当时 ForgeFlow 仍然保留 Skills / MCP 能力，但职责已经比早期 AI Office 方案更清晰：

• ForgeFlow 决定 Execution 使用什么资源、模型、阶段和工作区。
• Agent Harness 为对应执行生成 capability projection。
• OpenHands / ACP backend 只接收V1 当时 execution 允许的项目指令、Skills 和 MCP。
• 缺少必须能力时可以在 execution admission 前 fail closed。

所以求职材料可以真实写 Skills / MCP / Agent Harness capability admission，但不应写成“ForgeFlow 自己实现了 MCP 协议”。

Improvement 与 Self-change

v1 已加入受约束的 Improvement Candidate / Diagnostician 路径：重复失败可以先被确定性聚合成 Improvement Candidate；可选 AI Diagnostician 只能返回 typed PROPOSE_REPAIR / NO_ACTION，不能直接获得仓库写权限。

即使是 ForgeFlow 修改自己，也需要独立的 self-change、canary、promotion gate；这些能力默认关闭。Plan 成功本身不能直接证明新版本可以发布，仍需 exact source SHA、artifact digest 与 live release provenance 对齐。

这比“Reflector 自动改 Prompt / 自动改代码”更保守：它允许系统形成改进闭环，但自我修改不会绕过普通 Plan、独立 Review、测试、canary 和 release gate。

对简历和面试的可用表述

V1 当时可以由代码与仓库直接支持的关键词：

• Autonomous Software Engineering
• Multi-Agent / Supervisor
• Durable Plan / Work Graph
• OpenHands + 多 Coding Agent backend
• typed Supervisor action + deterministic control plane
• independent exact-SHA LLM Review / Repair
• Quality Gate / provenance / evidence
• Skills / MCP / Agent Harness
• resource routing / runtime admission
• worktree isolation / single-writer
• lease / CAS / idempotency / recovery
• bounded improvement / self-change canary

不建议仅为了 JD 对齐而直接宣称：

• 使用 LangGraph 实现 ForgeFlow（V1 核心不是 LangGraph）
• 完整 Reflector 自进化框架
• 完整 LLM-as-Judge 评分体系
• GMV 归因、营销推荐、视频生成能力

这些如果岗位询问，可以说明 ForgeFlow 的 Review / Improvement 机制与 Reflection / Judge 思想存在对应关系，但保持术语边界。

V1 当时验证与仓库状态

V1 当时仓库包含 npm run check 质量入口（boundary check、typecheck、test、build），并提供真实 provider 的 autonomous lifecycle smoke；公开 release 为 v1.0.0。

这一阶段应把 ForgeFlow 视为 Pixel Agent / Hermes AI Office 的V1 当时主项目和事实来源；旧 AI Office 笔记继续作为架构演进历史，不再作为简历或面试中的默认现状说明。