CataForge 把同一份 .cataforge/ 工作流规范部署到 Claude Code、Cursor、CodeX、OpenCode 四个 AI IDE，省去你为每个 IDE 重写 Agent / Skill / Hook / MCP 的工作。
# 安装（推荐 uv tool）
uv tool install cataforge
# 在你的项目根目录下执行
cataforge bootstrap --platform cursor # 或 claude-code / codex / opencode成功标志：终端最后一行打印 Diagnostics complete.。在对应 IDE 中打开项目即可使用。
先看不写盘：cataforge bootstrap --platform cursor --dry-run。
零安装试用：uvx cataforge bootstrap --platform cursor --dry-run。
其它安装方式（pip / 项目 venv / Windows 最小清单）见 安装指南。
| 问题 | CataForge 的做法 |
|---|---|
| 在 4 个 IDE 之间维护 4 套 Agent / Skill 定义 | 写一份 .cataforge/，cataforge deploy 翻译成各 IDE 的原生产物 |
| 某 IDE 不支持某个能力 | PlatformAdapter 按能力矩阵自动降级（rules_injection / prompt_check），而不是直接放弃 |
| 升级时怕覆盖手改的文件 | upgrade apply 前自动快照到 .cataforge/.backups/<ts>/，upgrade rollback 可回退 |
| 项目从零搭 SDLC 流程 | 内置 13 个 Agent + 28 个 Skill，覆盖需求 → 架构 → 设计 → TDD → 评审 |
CataForge 专为中文开发团队设计。13 个内置 Agent 的指令、28 个 Skill 的定义、全套 SDLC 文档模板（PRD、架构文档、开发计划等）均以中文撰写，Agent 之间通过中文语义传递上下文。你无需在英文 prompt 和中文需求之间反复翻译——输入中文需求，输出中文文档，代码注释和 commit 风格也遵循团队约定。
内置 workflow-framework-generator skill，输入工作流类型和目标 IDE，生成一套完整的 CataForge 兼容框架（Agent 角色、Skill 流程、文档模板、平台配置），覆盖软件开发之外的任意领域（公众号写作、电商运营、研究分析……）。CataForge 本身也运行在自己的 .cataforge/ 规范上（dogfood 模式），framework.json 内置 15 条迁移检查持续验证自身 scaffold 完整性。
生成的框架通过 cataforge bootstrap 一条命令落地（setup → upgrade → deploy → doctor 全链路，幂等，重跑无副作用）：
cataforge bootstrap --platform claude-code
cataforge bootstrap --platform claude-code --dry-run # 先预览再写盘RED → GREEN → REFACTOR 三阶段流水线，每阶段由独立 SubAgent 在隔离上下文中执行；REFACTOR 仅在 implementer 自报告 refactor_needed=true 时触发，不对每个任务跑一次 code-review。四档执行模式按任务规模自动路由：standard（完整三次 dispatch）、light-dispatch（合并 RED+GREEN 为一次 dispatch）、light-inline（满足条件时主线程直产，零子代理启动）、prototype-inline（agile-prototype 专用，强制跳过 REFACTOR）。
三种工作流模式，在 orchestrator 启动时选择并写入 CLAUDE.md，无需改配置文件：
- standard（7 阶段）：需求 → 架构 → UI 设计 → 开发计划 → TDD 开发 → QA 测试 → 部署发布，每阶段有质量门禁（
doc-review+code-review），适合交付质量要求高的项目 - agile-lite（精简敏捷）：PM + 架构师阶段产出 lite 文档（TDD 默认 light 模式），减少文档开销，保留质量评审
- agile-prototype（快速原型）：PM 产出一页
brief.md合并前 4 阶段，直接进 TDD light 模式，最快路径验证想法
整个链路由 orchestrator Agent 在主线程调度，状态机管理阶段跃迁和质量门禁，不走 SubAgent 嵌套，避免协调链断裂。
每次你覆盖 Agent 的建议（修改输出、否定方案、要求重做），detect_correction Hook 自动捕获这一信号并双写 docs/reviews/CORRECTIONS-LOG.md 和 docs/EVENT-LOG.jsonl。当 CORRECTIONS-LOG 中 hard+review 类条目累计达到阈值（默认 5 条），orchestrator 调度 skill-improvement 任务，将纠错模式内化为 Skill 定义的修订，下次同类任务不再重蹈覆辙。
用 cataforge correction record 手动写入 interrupt-override 通路的纠错条目；detect_correction hook 和 detect_review_flag hook 负责 option-override / review-flag 两条通路的自动捕获。
回流到上游：当下游使用 CataForge 时发现框架本身的 bug、改进点、或累积了若干 --deviation upstream-gap 纠偏（表"上游 baseline 在此场景下不准/不全"），用 cataforge feedback bug --gh（或 --clip / --print，v0.3.0 起）把 doctor + 最近 EVENT-LOG + upstream-gap corrections + framework-review FAIL 摘要聚合为 markdown 通过单条命令发回 CataForge 仓库。等价 skill 入口 cataforge skill run framework-feedback，每次运行会向 EVENT-LOG 写一条 state_change，便于 orchestrator 在 upstream-gap 累计达 RETRO_TRIGGER_UPSTREAM_GAP_DEFAULT（默认 3）时自动调起。详见 §feedback CLI。
同一份 .cataforge/ 规范通过 PlatformAdapter 翻译成各 IDE 的原生产物：Claude Code 输出 CLAUDE.md + .claude/settings.json，Cursor 输出 .cursor/rules/，CodeX 输出 AGENTS.md，OpenCode 输出任务清单。平台缺失某项能力时自动降级（rules_injection / prompt_checklist），不报错退出。
模型选择同样平台无关：AGENT.md 用 model_tier: light | standard | heavy 声明算力档位，部署时按各平台 profile.yaml.model_routing.tier_map 翻译为原生 model id（Claude Code 走 haiku/sonnet/opus，Cursor 类同，Codex 与 OpenCode 因 per_agent_model: false / user_resolved: true 自动省略 model: 字段交由用户运行时决定）。framework.json#/constants/AGENT_MODEL_DEFAULTS 集中管理 12 个内置 Agent 的默认档位，AGENT_MODEL_TIER_HEAVY_WHITELIST 显式控制 heavy 成本面（默认仅 architect / debugger），framework-review 的 B7 检查在 CI 阻拦档位漂移与 heavy 滥用。
验证状态：Claude Code 上经过充分验证；Cursor、CodeX、OpenCode 的适配逻辑已实现，但尚未经过等同程度的端到端验证，实际使用中可能遇到边界问题。
| 你想…… | 去这里 |
|---|---|
| 5 分钟跑通第一个部署 | 快速开始 |
| 一页纸速查（平台 / CLI / 产物路径） | 速查卡 |
| 在你的 IDE 中真实落地 | 平台适配指南 |
| 端到端验证四平台 | 手动验证 |
| 升级到新版本 | 升级指南 |
| 查 CLI 命令参数 | CLI 参考 |
| 改配置 | 配置参考 |
| 定制 Agent / Skill | Agent & Skill 清单 |
| 理解内部如何工作 | 架构概览 |
| 解决报错 | 故障排查 · FAQ |
- Issue 与 PR：见 CONTRIBUTING.md（开发环境、代码规范、测试基线、PR 约定、发布流程）
- 行为准则：CODE_OF_CONDUCT.md
- MIT License：LICENSE