架构总览
Status: Active Updated: 2026-02-27
范围
ForgeOps 负责“多步骤 AI 研发流水线”的控制与观测，强调：
- 运行时可替换
- 状态可追踪
- 失败可恢复
核心执行循环
- 服务启动时执行强 precheck（git/gh 身份与开发凭据、codex runtime 可用性）。
- 项目初始化时执行产品类型工具链 precheck（miniapp/web/ios/microservice/android/serverless）。
- CLI/API 创建 run。
- 创建 run 时读取项目级工作流配置（
<projectRoot>/.forgeops/workflow.yaml）。 - 创建 run 时注入项目上下文（
context.md+project.yaml+agent-skills.json+governance.md+invariants.json）。 - 创建 run 前执行 GitHub 强约束校验（git 仓库、git 身份已配置、origin=GitHub、gh 已登录）。
- 为 run 创建独立 worktree（
<repo>/.forgeops/worktrees/<runId>）与分支（forgeops/<runId>）。 - Worker 按 DAG 依赖认领所有可执行 pending step（可并发）。
- Runtime Adapter 在 run worktree 中执行 step，按统一解析器加载角色技能（优先级：project-local > user-global > official）。
issue步骤会把需求升级为结构化 issue，并在信息缺失时补齐假设与偏好信号（写入 step outputs / artifacts）。cleanup步骤可产出技能候选并落盘到项目目录（.forgeops/skills/candidates/）以支持本地方法论沉淀。implement/test/review完成后自动执行不变量检查器（机械 gate，若配置了platform-smoke也会执行）。- 不变量
error触发阻塞重试；warn默认不阻塞，并在review步骤自动创建 follow-up GitHub issue。 - Scheduler 读取
<projectRoot>/.forgeops/scheduler.yaml，按 Cron 周期托管 cleanup、issueAutoRun、skillPromotion、globalSkillPromotion 四类任务（含按 GitHub label 触发 run 与技能候选自动晋升）。 - Store 推进 step/run 状态并记录事件与产物，同时聚合
CI Gate/Platform Gate状态。 - API + SSE 实时供前端展示；同时支持通过
attach-terminal旁观指定 run/step/session 的 Codex thread（只读观测语义）。 - 技能候选晋升走独立 PR 链路（手动 CLI/API + 定时自动晋升两种触发），统一通过独立 worktree + draft PR 人审，不进入默认需求交付 DAG。
- 自动晋升默认采用稳定技能目标路径（同名技能持续编辑演进），避免每轮候选都新增碎片技能文件。
- user-global 技能库固定在
$FORGEOPS_HOME/skills-global，通过独立 PR +audit.ndjson做跨项目审计与沉淀。
默认交付步骤（线性示例）：
- architect
- issue
- implement
- test
- review
- cleanup（Garbage Collection）
组件划分
- 状态存储：
src/core/store.js - 工作流定义：
src/core/workflow.js - 运行时适配器：
src/runtime/* - 调度引擎：
src/worker/engine.js - 服务接口：
src/server/app.js - 仪表盘：
frontend/src/*
v1 非目标
- 多运行时智能调度优化
- 分布式 worker 集群
- 全自动发布流水线