Code Factory

自动生成完整项目结构(README+requirements+test+ASSET_MANIFEST)，运行测试验证后才交付

Code Factory — 代码交付工厂 Skill (v1.0)

将自然语言需求自动转化为可交付的完整项目资产。

架构：分层模块化设计，状态机驱动 + 契约校验 + 事务保护 + 熔断容错。

触发方式

触发短语	动作
"生产一个项目"	激活完整交付流程
"交付一个项目"	激活完整交付流程
"帮我写一个完整的项目"	激活完整交付流程
"创建一个项目叫..."	激活完整交付流程
"给我写一个 [功能] 的工具"	激活完整交付流程

自动触发条件

当检测到用户请求生成完整项目/工具/应用时自动激活。

---

架构概览

text

用户输入
  │
  ▼
┌──────────────────────────────────────────────┐
│  contracts/    数据契约层                     │
│  ├─ input_schema.py    → ProjectRequest      │
│  ├─ output_schema.py   → ProjectResult       │
│  ├─ step_context.py    → StepContext         │
│  └─ asset_manifest_schema.py                 │
└──────────────────────────────────────────────┘
  │
  ▼
┌──────────────────────────────────────────────┐
│  layers/orchestrator.py  状态机编排引擎       │
│  Phase0 → Step1 → Step2 → ... → Step6        │
│  每步独立执行、独立失败、独立回滚              │
└──────────────────────────────────────────────┘
  │          │          │          │
  ▼          ▼          ▼          ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│prefl │ │spec  │ │asset │ │verifier  │  ...
│ight  │ │engine│ │gen   │ │          │
└──────┘ └──────┘ └──────┘ └──────────┘
  │          │          │          │
  └──────────┴──────────┴──────────┘
        middlewares/ 横切中间件
        ├─ circuit_breaker.py    熔断器
        ├─ transaction_manager.py 事务管理
        ├─ anti_corruption.py    防腐层
        └─ side_effect_log.py    副作用追踪

---

执行流程

Phase 0: Preflight — 环境预检

实现模块: layers/preflight.py

生成前先验证环境完整性，避免生成后跑不通：

1. 检查 Python 版本是否满足项目需求
2. 检查目标目录是否存在、可写
3. 检查必要依赖是否已安装
4. 检查磁盘空间是否充足（≥100MB）
5. 不通过则直接报告缺少什么，后续步骤全部 SKIPPED

Step 1: 环境快照

实现模块: layers/orchestrator.py → _run_environment_snapshot()

结构化采集环境信息，经过 anti_corruption.py 校验后存入 StepContext。

Step 2: Spec 推导与计划生成

实现模块: layers/spec_engine.py

根据用户需求推导内部规格（spec），输出格式受 contracts/ Schema 约束：

1. Spec 推导：从用户需求中提取功能范围、输入输出、边界条件、验收标准
2. 验收标准格式：每条用 Given/When/Then + P1/P2/P3 优先级标记
3. 用户完全无感知——不要求用户写任何 spec，AI 内部完成

Step 3: 生成资产文件

实现模块: layers/asset_generator.py + templates/

所有文件写入通过 TransactionManager 暂存到 staging 区域：

• 验证全部通过 → tx.commit() 原子提交
• 任何步骤失败 → tx.rollback() 完整回滚

标准化项目结构：

text

project_assets/[project_name]/
├── src/                        # 源码目录
│   └── main.py                 # 主程序（<!-- HARD-GATE --> 标记）
├── tests/                      # 测试目录
│   └── test_main.py            # pytest 测试
├── docs/                       # 文档目录
│   └── README.md               # 使用说明/安装/依赖
├── requirements.txt            # 依赖清单
├── run.sh                      # 一键运行脚本
├── SKILL.md                     # AI 技能元数据头
├── ASSET_MANIFEST.md           # 人类可读版资源地图表
├── manifest.json               # 机器可读版资产清单
└── environment.toml             # 环境隔离配置

Step 4: 自动验证（含依赖图谱检查）

实现模块: layers/verifier.py

1. 依赖影响预检：分析模块间依赖，检查是否有循环引用
2. HARD-GATE 强制门禁验证：凡标记 <!-- HARD-GATE --> 的关键函数/API，必须通过独立验证
3. 运行 pytest tests/ -v → 确认全部测试通过
4. 输出结构化审查报告（Risk Assessment → 逐个文件 → 缺失测试 → 建议）

Step 5: 智能重试

实现模块: layers/retry_controller.py

受 circuit_breaker.py 熔断器保护：

• 第 1 次失败：自动分析错误→修改代码→重新验证
• 第 2 次失败：更换修复策略（缩小修改范围）→重新验证
• 第 3 次失败：记录结构化失败模式到 learnings/failure_patterns.json → 暂停并报告

Step 6: 交付

实现模块: layers/deliverer.py

输出：

• 项目路径（绝对路径）
• README.md 内容预览
• ASSET_MANIFEST.md 资源地图摘要
• manifest.json 机器可读摘要
• 测试结果摘要

---

状态机定义

text

PENDING ──→ RUNNING ──→ SUCCESS
                    ├──→ FAILED ──→ (retry ≤ 3) ──→ RUNNING
                    │         └──→ (retry exhausted) ──→ 记录失败模式
                    ├──→ TIMED_OUT (单步骤 > 120s)
                    └──→ ROLLED_BACK (事务回滚)
PENDING ──→ SKIPPED (前置条件不满足，如 Phase 0 失败)

全局熔断规则 (middlewares/circuit_breaker.py)：

• 全局超时：600s
• 单步骤超时：120s
• 连续 3 次失败 → 熔断打开，拒绝后续请求

---

数据契约（见 contracts/ 目录）

契约文件	约束内容
input_schema.py	ProjectRequest — project_name 格式、description 长度、python_version 格式
output_schema.py	ProjectResult, StepResult, StepStatus — 统一成功/失败标准
step_context.py	StepContext — 步骤间唯一数据载体，杜绝口头协议耦合
asset_manifest_schema.py	AssetManifest — 锁定 manifest.json 字段格式

---

代码规范（强制）

1. 简洁优先：10行能解决→不写20行
2. 单一职责：每个函数≤30行，只做一件事
3. 命名清晰：不用 x/tmp/data 等无意义变量名
4. 类型提示：所有函数参数+返回值加 type hints
5. 错误处理：不用 pass 或裸 except
6. 零硬编码：魔法数字/路径/配置提取为常量或参数
7. 无调试print：最终代码不含 print，用正式日志或异常
8. HARD-GATE 强制门禁：关键函数/API 入口前必须插入 <!-- HARD-GATE --> 注释标记
9. 每个公开函数≥1个测试用例
10. 必须包含边界条件测试（空列表/零值/文件不存在）

---

注意事项

• 所有文件使用 UTF-8 编码
• 如果用户指定了项目名以外的路径偏好，使用用户指定路径
• 不要修改项目目录以外的任何文件
• 如果用户只说了功能没给项目名，用功能名加小写下划线命名
• 技能自身的测试位于 tests/ 目录，运行 pytest tests/ -v

---

运行技能自身测试

bash

pip install -e ".[dev]"
pytest tests/ -v

✅ 自检清单

检查项	状态	说明
name 存在	✅	code-factory
name = 目录名	✅	vs code-factory
description 存在	✅	自动生成项目结构...
触发方式清晰	✅	5 个触发短语表
有 H1 标题	✅	# Code Factory
分层架构	✅	contracts + layers + middlewares + templates
状态机驱动	✅	PENDING→RUNNING→SUCCESS/FAILED/ROLLED_BACK
事务保护	✅	TransactionManager staging + atomic commit
熔断容错	✅	CircuitBreaker 全局 600s / 步骤 120s
契约校验	✅	防腐层 + Pydantic-style Schema
副作用追踪	✅	SideEffectTracker 审计 + 幂等性检测
零外部 API 依赖	✅	纯本地生成
验证机制	✅	Phase 0 预检 + Step 4 验证 + Step 5 智能重试
双格式输出	✅	ASSET_MANIFEST.md（人类）+ manifest.json（机器）
标准化结构	✅	src/tests/docs 三级目录
失败闭环	✅	learnings/failure_patterns.json 结构化记录
Spec 驱动	✅	内部 spec→plan→tasks 三段式
依赖预检	✅	依赖图谱 + HARD-GATE 验证
环境隔离	✅	environment.toml + venv
技能元数据	✅	自动生成标准 SKILL.md 头部
审查报告	✅	结构化输出 Risk→Files→Tests→Suggestions
可测试	✅	tests/ 6 个测试文件 + pyproject.toml