brunovicco/codex-python-engineering-harness

# Codex Python 工程框架 [](https://github.com/brunovicco/codex-python-engineering-harness/actions/workflows/harness-quality.yml) [](https://www.python.org/) [](LICENSE) 一个原生 Codex、配置文件驱动的引导工具，专为面向生产的 Python 仓库设计。它可以创建独立的服务、库或虚拟工作区项目，并包含持久的 Codex 指令、项目配置、技能、生命周期钩子、架构检查、MCP 治理以及统一的质量门禁。 ## 快速开始 ``` python bootstrap.py \ --name payments-api \ --package payments_api \ --target ../payments-api \ --profile service \ --git-init \ --lock ``` 配置文件： - `service`：可部署的 `src/` 包、容器文件、日志记录与追踪边界。 - `library`：可复用的类型化包，不包含服务/容器假设。 - `workspace`：虚拟 uv 工作区根目录；它不会创建任何人为的包或成员。 | 配置文件 | 适用场景 | 是否创建包 | 容器和运行时边界 | |---|---|---:|---:| | `service` | API、worker、agent 和可部署进程 | 是 | 是 | | `library` | 可复用的类型化 Python 包 | 是 | 否 | | `workspace` | 成员将在稍后添加的多包仓库 | 否 | 否 | 该引导工具还支持 `--dry-run`、非破坏性的 `--merge` 以及 `--check`。运行 `python bootstrap.py --help` 获取完整接口信息。 治理是一个独立的生成器维度，为了向后兼容，默认保持禁用状态。根据需要启用功能配置文件并重复应用 overlay： ``` python bootstrap.py \ --name payments-agent \ --package payments_agent \ --target ../payments-agent \ --profile service \ --governance-profile agentic \ --governance-overlay dora \ --governance-overlay iso-iec-42001 ``` 治理配置文件包括 `none`、`baseline`、`ai-assisted` 和 `agentic`。可用的 overlay 包括 `dora`、`iso-iec-42001` 和 `nist-sp-800-53`。框架映射仅描述控制支持，并不声明组织级别的合规性或认证。 ## 五分钟评估 要求：Python 3.12 或更高版本以及 `uv`。 ``` target="$(mktemp -d)/harness-evaluation" python bootstrap.py --name evaluation --package evaluation --target "$target" --profile service cd "$target" uv sync --all-groups --extra observability uv run python scripts/quality_gate.py ``` 然后检查 `AGENTS.md`、`.codex/config.toml`、`.codex/hooks.json`、`.agents/skills/` 和 `docs/ARCHITECTURE.md`。此评估仅创建一个一次性的本地项目，无需任何凭据。当你想要一个强约定、由仓库拥有的工程基线时，请使用此框架；如果现有项目无法采用其 uv 工作流或架构约束，则请勿使用。 ## 生成的项目工作流 ``` uv lock --check uv sync --frozen --all-groups uv run ruff check . uv run ruff format --check . uv run mypy src tests uv run pytest uv run python scripts/quality_gate.py python /path/to/harness/bootstrap.py --target . --check ``` 在期望 `.codex/config.toml` 和 `.codex/hooks.json` 加载之前，请先信任该仓库。在 Codex 中使用 `/hooks` 来审查并信任新增或修改的钩子。生成的项目不需要任何个人 Codex 配置，也不需要用于构建或测试的凭据。 ## 仓库布局 - `template/`：复制到生成的项目中的兼容 service 的基础模板。 - `profiles/`：用于 `service`、`library` 和 `workspace` 的 overlay 与排除项。 - `governance/`：规范控制、能力配置文件、合规性 overlay 和 schema。 - `plugins/python-engineering-harness/`：带有可复用技能和钩子的可安装 Codex 插件。 - `.agents/plugins/marketplace.json`：仓库 marketplace 条目。 - `tests/`：bootstrap、hook、验证器和分发回归测试。 - `docs/ARCHITECTURE.md`：移植决策和源码映射。 ## 插件 将此仓库作为本地 marketplace 添加，命令为 `codex plugin marketplace add /absolute/path/to/codex-python-engineering-harness`，重启 桌面应用，然后安装 **Python Engineering Harness**。marketplace 不会自动安装或认证任何内容。 ## 验证 ``` uv sync --all-groups uv run python scripts/quality_gate.py ``` 请参阅 `VALIDATION.md` 获取最新的验证记录，以及 `SOURCES.md` 获取此移植使用的官方 OpenAI 参考资料。请参阅 `docs/EVALUATION.md` 获取可复现的评估指南和验收标准，`docs/VERSIONING.md` 获取 artifact 生命周期，`docs/UPGRADING.md` 获取非破坏性升级（葡萄牙语版本：`docs/UPGRADING.pt-BR.md`），`docs/ENTERPRISE_ROLLOUT.md` 获取推广指南，`CHANGELOG.md` 获取发布历史，以及 `SECURITY.md` 获取私密的漏洞报告方式。社区参与相关事宜请参阅 `CONTRIBUTING.md`、`SUPPORT.md` 和 `CODE_OF_CONDUCT.md`。与同级项目 `claude-python-engineering-harness` 的结构一致性已通过 CI 中的 `scripts/parity_check.py` 基于 `parity-manifest.json` 进行检查。

标签：AI治理, MCP协议, Python, SOC Prime, 安全规则引擎, 开发工具, 无后门, 请求拦截, 项目脚手架