Forgeo 是一个面向编码智能体的软件工厂（software factory）。它的核心思路是：你提供一个待办清单（backlog）和一个智能体 CLI，Forgeo 负责挑选下一个可运行的任务、运行智能体，并提交结果。进度以纯文件形式记录，并提供 Web 仪表盘，只有在需要人工决策时才会打断你。
用途与定位 Forgeo 用于把编码智能体接入一个可调度、可追踪的自动化工作流。它适合希望让智能体按清单持续处理开发任务、并自动提交到主分支的场景。它明确采用“无分支、无 PR”的模式，每个任务的结果直接提交到 main。
主要能力
- 任务调度：一次处理一个任务，选择最旧的、依赖项已 COMPLETED 的 OPEN 任务，或按 run_at 计划执行。REVIEW 状态会阻塞其依赖任务，但不阻塞独立任务。
- 智能体无关：任何读取 FORGEO_TASK 环境变量的 CLI 均可使用（例如 aider、Claude、自定义脚本）。
- 空闲重构：当待办清单为空时，运行一次重构流程。
- 失败处理：需要人工输入时标记为 BLOCKED（通过 BLOCKER.md）；失败时按重试策略标记为 FAILED；对文件型待办清单提供快照；支持 Telegram/webhook 通知。
- 可选审查：review_mode: branch 时，提交到 forgeo/review/TASK-001 分支，标记为 REVIEW，推送并等待人工合并后变为 Complete。
使用方式 前置条件：需要终端、一个 git 仓库和一个智能体 CLI。 安装：提供无需 root 的安装方式，可重复运行以升级。 初始化：在项目根目录运行向导，创建 forgeo.yaml 和 .forgeo/（包含 backlog、日志、blockers）。向导会提示选择待办清单提供方（file / github / gitlab / jira / http）和智能体命令。对于 issue 提供方，可选择 PAT 或 OAuth 登录（forgeo auth login → ~/.config/forgeo/tokens/）；GitHub 仓库检测在可能时自动完成，Jira 则需要提供其 URL 和 JQL。 填写待办清单后，每个周期执行：挑选任务 → 运行智能体 → 提交/推送（或在 review_mode: branch 时推送到 REVIEW 分支）。待办清单为空时执行重构流程。 Web 控制台：forgeo web 默认在 0.0.0.0:8790 开放。在共享主机上可使用 forgeo web --token 启用 bearer 认证。 隔离运行智能体：仓库以相同路径绑定挂载，任务通过 FORGEO_TASK 传入。 多实例：每个仓库一份配置，完全独立（各自的待办清单、日志、锁）。可使用实例注册表。
待办清单提供方与仪表盘 提供方包括：file、HTTP、Jira、GitHub、GitLab。file/HTTP 交换完整文档；Jira/GitHub/GitLab 逐个同步 issue。文件型待办清单在每次运行前会生成快照（backlog.json.bak），若损坏则恢复。 仪表盘：forgeo web 聚合所有实例。对于 file/http，它是主要编辑器；对于 jira/github/gitlab，它是只读为主的镜像（链接到原生 issue，展示 BLOCKED/FAILED 原因和重试状态）。
适用场景 适合希望让编码智能体按 JSON 待办清单自动执行任务、并直接提交到主分支的开发工作流；适合需要定时调度、失败重试、人工阻塞提示和 Web 进度查看的自动化开发场景。
限制与说明 需要终端、git 仓库和智能体 CLI。采用无分支、无 PR 模式，结果直接提交到 main（除非启用 review_mode: branch）。贡献指南中提到的质量门禁包括 pytest、ruff check、mypy src/forgeo。许可证为 MIT。
