tonmoy007/forge-os

# Forge OS [](https://github.com/tonmoy007/forge-os/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) **Forge OS** 是一个本地优先、内核无关的 SDLC 编排 CLI。它驱动着一个 确定性的 12 阶段软件生命周期 —— 从需求到发布 —— 并带有 强制执行的质量门禁、工件依赖跟踪、可重放的 agent 运行， 以及一个可以生成真实 AI 编码 agent 的安全审计适配器边界。所有 状态都存在于您的项目目录中；无需服务器，无云依赖，无 遥测。 编排引擎掌握着规范状态。AI 提供商、人类和插件 *仅仅是执行面* —— 只需更改配置即可切换内核，而无需 更改代码。 ``` git clone https://github.com/tonmoy007/forge-os && cd forge-os pip install -e . forge init --path ./demo --name Demo # dummy adapter — no AI provider needed cd ./demo && forge agent run --stage srs # writes SRS.md, validated against its contract ``` 只需一行配置更改，即可驱动真实的 AI 内核（Claude Code、Codex、OpenCode……）—— 请参阅 [快速开始](#quick-start) 和 [内核适配器](#kernel-adapters)。 ## 为什么 AI 编码 agent 功能强大但缺乏问责制：没有生命周期，没有门禁，没有 审计跟踪，也没有办法重放发生过的事情。Forge OS 在 agent *周围* 放置了一个确定性的编排层：每一次生成都会针对 安全配置文件进行验证，记录到仅追加的事件存储中，根据 声明的输出契约进行检查，并在工件依赖图中进行注册。 内核（Claude Code、Codex、OpenCode、终端上的人类操作员……）是 一个可插拔的细节。 **验证点：** 使用 Claude Code 适配器运行 `forge agent run --stage srs` 如今可以端到端地运行 —— 从角色设定 → subprocess → 由 agent 编写 `SRS.md` → 契约验证 → 工件注册 —— 并记录完整的生命周期。 ## 内核适配器 | 适配器 | 后端 | 状态 | |---------|---------|--------| | `dummy` | 确定性存根（无 AI） | ✅ 正常工作 —— 默认 | | `claude_code` | `claude` CLI subprocess，stream-json | ✅ 正常工作 —— 已针对 claude 2.1.x 验证 | | `claude_raw` | Anthropic Messages API | ✅ 已实现（`pip install .[claude-raw]`） | | `claude_sdk` | Claude Agent SDK | ✅ 已实现（`pip install .[claude-sdk]`） | | `codex` | Codex app-server (JSON-RPC) | ✅ 已实现（需要 `codex` CLI） | | `opencode` | OpenCode HTTP + SSE | ✅ 已实现（`pip install .[opencode]`） | | `human` | 终端操作员 | ✅ 已实现 —— 零依赖 | | `openclaw`、`local_llm` | — | 🚧 占位符 | 在初始化时选择一个内核（`forge init --adapter claude-code`），或者稍后通过 `.forge/config.yaml` 中的 `default_adapter` 进行配置。`forge adapter status` 会显示 每个适配器的可用性、功能和安装提示。使用 `pip install -e '.[all-adapters]'` 可以一次安装所有 可选的适配器后端（或者如果仅需 ACP 集成依赖，请使用 `'.[acp]'`）。 `claude_code` 适配器还支持：每次生成的事件存储记录，带有确定性 **重放**（`run_id` → 相同的句柄，无 subprocess），`.claude/settings.json` 钩子生命周期，一个在生成前严格阻断的 **SecurityEnforcer** 安全门禁（审计到 `.forge/security-audit.jsonl`），`--model` 以及 `--permission-mode`。 ## 快速开始 ``` # 安装 (Python 3.11+) git clone https://github.com/tonmoy007/forge-os && cd forge-os pip install -e . # 初始化项目 (dummy adapter — 无需任何 AI provider 即可运行) forge init --path ./my-project --name Demo cd ./my-project forge status # 或驱动真正的 Claude Code kernel (要求 PATH 中包含 `claude` CLI) forge init --path ./my-project --adapter claude-code --permission-mode acceptEdits # 运行当前阶段的 agent (SRS stage 会写入 SRS.md，并由 contract 检查) forge agent run --stage srs # 走一遍 pipeline forge stage list forge stage advance # 检查所有内容 forge adapter status # adapter availability + capabilities forge gate report # quality gates forge events tail -n 20 # lifecycle event log forge security audit # security decisions forge health check # subsystem health ``` ## 命令概览 `init` · `status` · `explain` 以及各个子应用： `config`（show、validate）· `stage`（list、start、complete、advance、override）· `events`（list、tail）· `gate`（list、check、report）· `adapter`（list、status）· `agent`（list、contracts、run）· `lesson`（list、add、approve、deprecate）· `reflection`（list、show）· `artifact`（list、register、refresh）· `context`（select、budget、lazy-stats）· `backtrack`（list、plan、approve、run）· `security`（audit）· `health`（check）· `acp`（discover、list、install、sessions、close-session）· `dreamer`（digest、scan、decay）· `daemon`（start、stop、status、logs、restart） ## 架构 严格的分层，由合并前检查强制执行： ``` cli/ ──▶ use_cases/ ──▶ core/, gates/, project/, context/, memory/, kernel/, events/, hooks/, agents/, adapters/ │ ▼ schemas/ (pure Pydantic, zero internal imports) ``` - **`StateManager`** 是 `.forge/state.json` 的唯一写入者 —— 原子写入， Pydantic 验证，每一次修改都会追加一个生命周期事件。一个 SQLite 事件 存储与其同时进行双重写入（WAL 模式），正逐步向事件溯源的 权威性发展。 - **`KernelAdapter`** 是可移植性边界：引擎从不导入 提供商的 SDK。异步适配器通过 `AsyncToSyncBridge` 插入同步引擎；兼容 ACP 的 agent 以附加方式插入。 - **状态绝不会因为适配器、钩子或插件失败而推进。** 深入探讨：[`ARCHITECTURE.md`](ARCHITECTURE.md) · [`BUILD_SPEC.md`](BUILD_SPEC.md) · [`SCHEMAS.md`](SCHEMAS.md) · 位于 [`adr/`](adr/) 中的 ADR ## 项目布局（由 `forge init` 创建） ``` .forge/ config.yaml, state.json, events.jsonl, security-audit.jsonl, lessons.yaml, reflections/, agents/{personas,contracts}/ pipeline/ stages.yaml, gates.yaml, state.md (human-readable mirror), decisions/, log/ tasks/ task plans and notes ``` ## 开发 ``` pip install -e .[dev] python -m pytest # full suite (649 tests) python -m ruff check src tests # lint (E F I UP B, line length 100) python -m compileall src tests # syntax sweep ``` 参考环境是一个干净的 `python:3.12-slim` 容器；CI （`.github/workflows/ci.yml`）在每个 PR 上运行相同的门禁。 ## 许可证 [Apache-2.0](LICENSE)

标签：AI编程助手, Python, SDLC编排, SOC Prime, 命令行工具(CLI), 开发工具, 文档结构分析, 无后门, 网络调试, 自动化