ForgeWorks — 基于 Claude Code 运行时机制的 AI 研发循环引擎

🇨🇳 本 README 为中文主版;工程调优指南 docs/PRECISION-TUNING.md 为英文。深度文档见 docs/。

1. 项目概述

ForgeWorks 是一套把 Claude Code 运行时机制抽离为独立 Python 实现、并以"收敛式 Loop 工程引擎"为核心基石的 AI 研发质量框架。

它解决的问题是:现有 AI 编程工具止步于"给建议",质量保障(是否真修对、是否引入新问题、是否达标)仍全靠人工——"AI 看似能写、质量没保障"。ForgeWorks 把审查 → 修根因 → 跑测试 → 质量门禁做成自动收敛的闭环:AI 不达标不放行,不收敛升级人工,不静默失败、不无限循环。

目标用户:需要 PR 质量闭环的研发团队与个人开发者、构建企业自有 AI Agent 系统的平台/架构团队、要求模型自主可控与权限分层的安全/合规团队。核心价值:已用 50 次真实 LLM 调用验证(召回 100% / 精度 71% 可调至 90%+ / 根因修复 100%),模型无关、中转代理友好、辅助不替代。

2. 适用场景

PR 提交前自审(最高 ROI) — 开发者提交 PR 前用 code-reviewer 4 视角并行扫变更。痛点:人工 review 易漏、返工轮次多。介入:30 秒出 [{severity, file:line, 置信度}],高置信快速采纳、低置信人工看,比裸审假阳性 −78%(18→4),减少返工。
偶发/竞态 bug 修复闭环 — 支付等关键路径偶发竞态,人工难复现。痛点:症状补丁易复发。介入:完整 loop 审查定位 → 根因五步法修复(实测 hard 级竞态用双重检查锁定 DCL 修根因)→ 真跑测试验证 → 置信度 0.92 → 达标收敛,根因率 100%(5/5)。
Kafka/MQ 流程集成测试 — 消息流测试三大坑:异步断言、消费者组 offset 串扰、broker 行为(mock 漏序列化/partition)。介入:mq.strategy: real 用 testcontainers 真 broker + per_test group-id 隔离 + test-sink topic 异步轮询断言(不 sleep),消除 flaky 测试。
CI 自动质量门禁 — PR 卡在质量门。痛点:人工把关主观、易放宽。介入:CI 跑 python run.py . --no-dry-run,exit 0 可 merge / exit 2 需人工;5 道门禁(无 Critical / 测试过 / 覆盖率行 80% 分支 70% / 置信度阈值)客观可审计。
企业多项目模型统一管控 — 多业务线、不同风险等级。痛点:绑定单一供应商、调用不可审计。介入:每 Agent 独立 base_url 走企业网关(one-api/litellm),过载自动 fallback;关键系统 project_overrides 提标准线(覆盖率 90% + 强制置信度)。
构建自有 AI Agent 平台 — 平台团队要自建 agent 系统。痛点:从零造权限/fallback/hook 成本高。介入:skillforge 12 引擎(6 层权限/FallbackChain/Hook 系统/WorkflowDSL/Compaction…)作积木,Convention-over-Config 放文件即注册。

3. 核心功能列表

功能	简述	入口
6 阶段收敛 Loop	Scope→Review→Fix→TestData→Test→Confidence→Gate,达标放行/不收敛升级	`python run.py src/ --no-dry-run`
多视角并行审查	correctness/security/quality/tests 4 视角真并行 + 合并去重	`code-reviewer` agent
根因修复	bug-hunting 五步法(复现→追踪→根因→最小修复→验证),修根因不修症状	`bug-fixer` agent
4 类测试数据 + 5 策略	fixtures/DB/API/MQ(含 Kafka 真 broker)+ synthetic/anonymize/replay 等	`test_data` 配置段
真实测试执行	真跑 pytest/jest/go test/cargo test,绝不编造结果	`test-runner` agent
可辩护置信度	每条修复 0–1 评分 + `file:line` 证据 + checklist,≤0.4 必不过	`confidence-evaluator` agent
质量门禁	5 道门禁,exit 0/1/2	`QualityGates` / `gates` 配置段
FallbackChain	错误分类重试:过载重试/模型不存在永久切换/认证立即失败	`agent_models.<agent>.fallbacks`
跨会话 Memory	记已修 + 假阳性签名,重跑去重	`.qa-memory.json`
断点续跑	每轮 checkpoint 落盘	`python run.py src/ --resume`
精度五杠杆 + 预设	①阈值校准/②diff锚定/③finding-verifier/④杀手共识/⑤假阳性记忆	`review.precision_preset`
skillforge 12 引擎	AgentLoop/Hook/6层权限/SkillLoader/WorkflowDSL/Compaction/Worktree…	`SkillForge.create('.')`
11 个技能	7 原子 + 4 组合(bug-hunting/security-patterns/…)	`skills/<name>/SKILL.md`

4. 原理与机制

4.1 双子项目,一框架一产品

┌─────────────────────────────────────────────────────────────┐
│  loop-engine (产品, 开箱即用)     skillforge (框架, 造工具)    │
│  6 阶段收敛 Loop + 6 Agent         12 核心引擎 + SDK + 11 技能  │
│  + FallbackChain + QualityGates   (Claude Code 模式的可读实现) │
│  自包含, 零 skillforge 依赖        零外部依赖                   │
└─────────────────────────────────────────────────────────────┘
            │ call_fn (按 provider 注入 anthropic/openai SDK)
            ▼
       模型层 (模型无关: 直连或中转 relay, 每 Agent 独立配置)

4.2 Loop 引擎:收敛闭环(核心基石)

单轮时序:

[0 Scope] scope-analyzer → {scope_report, change_plan}        (只读)
[1 Review] code-reviewer 4视角并行 → Finding[] (去重 + memory 去重)
           ↳ ②diff锚定 / ③finding-verifier / ④skeptic共识 (精度杠杆, 默认关)
[2 Fix] bug-fixer 根因五步法 → 写回 status/solution
[3 TestData] 5策略×4类源 → TestDataReport
[4 Test] test-runner 真实执行 → TestStatus(覆盖率)
[5 Confidence] confidence-evaluator → 0-1 + 证据 + checklist
[6 Gate] QualityGates → pass / continue(回Fix) / escalate(AskUser)

收敛防抖:Gate 不过 → 回 Fix;连续 escalate_on_new_critical(默认 2)轮新 Critical → 升级人工;达 max_iterations(5)未收敛 → 升级。不静默失败、不无限烧钱。

4.3 Claude Code 运行时机制(11 条映射)

Claude Code 机制	ForgeWorks 实现
Agent Loop + Stop Hook 强制收敛	Gate 不过回 Fix;`Stop` hook block
Fallback Model Chain + 错误分类	`FallbackChain`(过载重试/不存在永久切/认证即败)
Markdown Agent 定义	`agents/*.md` = 角色+system_prompt+输出契约+工具
多视角并行审查	4 视角 ThreadPoolExecutor / WorkflowEngine.parallel
跨会话 Memory	`.qa-memory.json`(known_fixed + known_false_positive)
Compaction + 防抖	上下文 >80% 压缩;3 次失败抛错不无限循环
渐进式技能加载(三级)	元数据常驻(~2% 预算)→ body 按需 → references 惰性
6 层权限防御	Mode→Rules→Enterprise→Sandbox→Hook→Hierarchy(default-deny)
Workflow DSL	`agent/parallel/pipeline/phase`,并发 16、总量 1000、budget 硬约束
Git-First Worktree 隔离	每 Agent 独立工作树,并行写不冲突
Convention-over-Config	放 `agents/*.md`/`skills/<n>/SKILL.md`/`hooks.json` 即注册,无构建步

4.4 关键设计原则

结构化 Agent 通信:Agent 间传 JSON dataclass(Finding/TestStatus/TestDataReport),parse_output 解析回结构,可靠可审计。
默认限制、显式放行:6 层权限 deny 优先,企业层可锁低层不可放宽。
协同静默回退:forgeworks 部署(skillforge 在 import path)自动启用 WorkflowEngine/Hook 协同;独立部署自动回退,行为不变。
assist, not replace:AI 只建议,不自动 merge/commit/push。

5. 底层依赖(Claude Code / Claude 模型集成)

诚实声明:ForgeWorks 不依赖 Claude Code 运行时,也不绑定 Claude 模型——它把 Claude Code 的架构模式重写为独立 Python 实现,模型层完全无关。

5.1 模型集成方式

run.py 的 make_llm_call_fn() 按 provider 注入调用层:

provider	协议	SDK	关键调用
`anthropic`	Anthropic Messages API(中转无 `/v1` 也走此)	`anthropic` SDK	`client.messages.create(model, max_tokens=4096, system, messages)`
`openai` / `custom`	OpenAI 兼容(中转带 `/v1` / one-api / litellm)	`openai` SDK	`client.chat.completions.create(model, messages)`

实验层 experiment/llm_call.py 用 urllib 直调中转:POST {base}/v1/messages,header x-api-key + anthropic-version: 2023-06-01。

5.2 关键能力调用

代码分析/审查:code-reviewer 以 Bash(git diff:*)/Read/Grep/Glob 为工具面,4 视角并行,输出结构化 Finding[] JSON。
代码生成/修复:bug-fixer 用 Write/Edit/Bash(git diff:*),输出 {status, solution}。
推理/评估:confidence-evaluator/finding-verifier 需深度推理,建议用强模型(如 claude-sonnet-4-6 级);scope-analyzer/test-runner/test-data-preparer 用快模型(如 gpt-4o-mini)省成本。

5.3 配置(`config/qa-loop.yaml` → `agent_models`)

agent_models:
  code-reviewer:
    provider: anthropic
    base_url: "https://your-relay.example.com"   # 中转代理; 不填 = 直连
    api_key: "${RELAY_API_KEY}"                  # 从环境变量读, 勿明文
    model: "claude-sonnet-4-6"                   # 任意模型 ID, 改 yaml 不改代码
    fallbacks:
      - { provider: openai, base_url: "https://your-relay.example.com/v1", model: "gpt-4o" }

实验复跑所用模型(参考,非硬依赖):deepseek-v4(review/fix)+ qwen3.7(judge),经 Anthropic 格式中转。reasoning 模型适配已沉淀(跳过 thinking block 取 text、max_tokens 调大 4096)。

6. 可信度与可靠性说明

6.1 测试与质量门

35 个单元测试(loop-engine 35 + skillforge 29),覆盖纯逻辑:FallbackChain 错误分类/永久切换/立即失败、parse_output 解析、QualityGates 五门禁、Finding 签名去重、_merge_findings 共识、_anchor_filter diff 锚定、_apply_verdicts、精度预设、跨会话 memory 往返。
CI 三道关(.github/workflows/ci.yml):ruff 全仓库 lint(语法+未定义名+pyflakes)+ 两套 pytest + dry_run 冒烟(exit 0)。本地实测:35 passed, ruff clean, dry_run exit 0。
未测项:无覆盖率 %(未接 coverage 工具);LLM 行为不进单测,走 experiment/ 可复跑脚本。

6.2 实测验证(非纸面)

50 次真实 LLM 调用,10 个已知 bug 金标准(易/中/难 × 安全/正确性/边界):

维度	结果	决策门	判定
审查召回率	100% (10/10)	≥70%	✅
审查精度(增强 vs 裸)	71% vs 36%	假阳性 ≤30%	✅
假阳性数	4 vs 18	—	−78%
修复正确率	100% (5/5)	≥70%	✅
修根因率	100% (5/5)	—	✅ 超预期

可复跑:cd loop-engine/experiment && python run_group_a.py && python run_group_b.py(见 REPRODUCE.md)。

6.3 运行稳定性

dry_run 确定性:不调模型,验证 6 阶段编排收敛,exit 0。
防失控:max_iterations=5 + escalate_on_new_critical=2 + WorkflowEngine 总量上限 1000 + Compaction 连续 3 次失败抛错——规模再大不烧钱、不无限循环。
错误分类重试:FallbackChain 不无脑重试,省钱稳定。
跨会话记忆 + 断点续跑:重跑去重、--resume 续跑。

6.4 已知限制(诚实)

Alpha, pre-1.0:语义化版本,minor 可能破坏兼容。
skillforge 部分为参考实现:fallback_chain._default_call、WorkflowEngine._default_agent_runner、hook_system._execute_prompt_hook、compaction._summarize 是占位,接真实 SDK/LLM 前不用于生产;loop-engine 主链路为真链路。
② diff 锚定无法在金标准消融(金标准是整文件无 diff),需在真实 PR 测。
精度"调后 90%+"是预期区间,非实测:真实数字需用户跑 calibrate_threshold.py + run_precision_ablation.py 得到(无 key 无法编造)。
无外部社区反馈:pre-release,尚未有外部用户。
不建议裸跑生产关键路径:信任积累后再上。

7. 安装与快速开始

7.1 依赖

Python 3.10+、Git、bash。核心零外部硬依赖;推荐 pyyaml,真实运行按 provider 装 anthropic/openai。

cd loop-engine
pip install -r requirements.txt   # pyyaml + anthropic + openai + pytest

7.2 三步上手

# 1) dry_run: 无需 API key, 验证 6 阶段编排收敛 (exit 0)
PYTHONIOENCODING=utf-8 python run.py src/sample/

# 2) 真实运行: 改 config/qa-loop.yaml 的 agent_models + export RELAY_API_KEY
PYTHONIOENCODING=utf-8 python run.py src/your-code/ --no-dry-run

# 3) 断点续跑
PYTHONIOENCODING=utf-8 python run.py src/your-code/ --resume

退出码:0 收敛 / 1 门禁未过 / 2 升级人工。

7.3 使用示例

独立调单 Agent(PR 自审,不跑整个 loop):

from qa_loop import QALoop
from run import make_llm_call_fn
qa = QALoop(config_path="config/qa-loop.yaml", agent_md_dir="agents",
            call_fn=make_llm_call_fn())
findings = qa.agent("code-reviewer").run("review src/auth/")   # 直接拿 Finding[]

CI 质量门:

# .github/workflows/qa-loop.yml
- run: python run.py . --no-dry-run
  env: { RELAY_API_KEY: "${{ secrets.RELAY_API_KEY }}" }

7.4 配置说明

主配置 loop-engine/config/qa-loop.yaml,关键段:

段	作用
`loop`	`max_iterations: 5`、`escalate_on_new_critical: 2`
`phases`	6 阶段调度顺序
`gates`	5 道门禁(覆盖率行 80%/分支 70%)
`agent_models`	核心:每 Agent 独立 provider/base_url/api_key/model/fallbacks,`${VAR}` 从环境读
`review`	精度杠杆 + `precision_preset: low/balanced/strict`
`test_data`	5 策略 × 4 类源(含 Kafka real broker + PII 脱敏)
`project_overrides`	按项目提标准线(关键系统覆盖率 90% + 强制置信度)

环境变量见 .env.example:RELAY_API_KEY、TEST_DB_DSN、TEST_KAFKA 等。

精度调优见 docs/PRECISION-TUNING.md(五杠杆 + 预设 + 测量脚本 + 取舍)。

贡献指南

见 CONTRIBUTING.md。要点:fork → branch → pytest tests/ -q 绿 → 带 PR 模板提 PR。Convention-over-Config:放 agents/*.md、skills/<name>/SKILL.md、hooks.json 到正确位置即生效,无构建步。

不接受:硬编码密钥、auto-merge/commit/push、默认放宽权限、破坏 loop-engine 零 skillforge 依赖契约。

安全漏洞私报,勿开公开 issue——见 SECURITY.md。

许可证

文档导航

文档	内容
`docs/01_项目概述与功能详解.md`	背景、用户、价值、功能模块详解
`docs/02_运行原理与架构设计.md`	架构图、数据流、关键组件、机制
`docs/03_模块使用指南.md`	分步教程、参数、配置、联动场景
`docs/04_AI提效与平台化能力说明.md`	量化提效、平台化能力、案例
`docs/05_功能示例与部署指南.md`	端到端示例 + 生产部署 + FAQ
`docs/PRECISION-TUNING.md`	审查精度五杠杆 + 预设 + 测量脚本
`loop-engine/experiment/REPRODUCE.md`	验证实验复跑指南

Loop 引擎为核 · Claude Code 机制为骨 · 已验证 · 模型无关 · 辅助不替代。

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
docs		docs
loop-engine		loop-engine
skillforge		skillforge
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
ruff.toml		ruff.toml

Navigation Menu

Repository files navigation

ForgeWorks — 基于 Claude Code 运行时机制的 AI 研发循环引擎

1. 项目概述

2. 适用场景

3. 核心功能列表

4. 原理与机制

4.1 双子项目,一框架一产品

4.2 Loop 引擎:收敛闭环(核心基石)

4.3 Claude Code 运行时机制(11 条映射)

4.4 关键设计原则

5. 底层依赖(Claude Code / Claude 模型集成)

5.1 模型集成方式

5.2 关键能力调用

5.3 配置(`config/qa-loop.yaml` → `agent_models`)

6. 可信度与可靠性说明

6.1 测试与质量门

6.2 实测验证(非纸面)

6.3 运行稳定性

6.4 已知限制(诚实)

7. 安装与快速开始

7.1 依赖

7.2 三步上手

7.3 使用示例

7.4 配置说明

贡献指南

许可证

文档导航

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

ForgeWorks — 基于 Claude Code 运行时机制的 AI 研发循环引擎

1. 项目概述

2. 适用场景

3. 核心功能列表

4. 原理与机制

4.1 双子项目,一框架一产品

4.2 Loop 引擎:收敛闭环(核心基石)

4.3 Claude Code 运行时机制(11 条映射)

4.4 关键设计原则

5. 底层依赖(Claude Code / Claude 模型集成)

5.1 模型集成方式

5.2 关键能力调用

5.3 配置(config/qa-loop.yaml → agent_models)

6. 可信度与可靠性说明

6.1 测试与质量门

6.2 实测验证(非纸面)

6.3 运行稳定性

6.4 已知限制(诚实)

7. 安装与快速开始

7.1 依赖

7.2 三步上手

7.3 使用示例

7.4 配置说明

贡献指南

许可证

文档导航

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

5.3 配置(`config/qa-loop.yaml` → `agent_models`)