Codex-up

Codex_up

中文 | English

English

Codex_up is a local governance toolkit for building a reproducible, auditable, and portable Codex Desktop / Codex CLI work environment.

It started as a personal Codex environment reference package and has been productized into a PowerShell-first toolkit with golden CLI regression tests, schema checks, rollout audits, assistant workflow governance, migration runbooks, and safety-first apply planning.

What It Does

• Checks local Codex environment health.
• Validates project startup assets.
• Audits secrets, filesystem allowlists, MCP availability, skills, memory governance, automation status, and host toolchain readiness.
• Produces JSON and Markdown reports.
• Maintains golden CLI regression coverage.
• Plans safe apply behavior before global writes.
• Validates controlled write, restore, and rollback behavior inside run-local sandboxes.
• Provides offline-first personal assistant templates and connector permission governance.
• Provides a governed PPT production workflow with editable PowerPoint output, GPT-image-2 asset presets, Figma design references, and deck QA templates.
• Provides DESIGN.md authoring and agentic engineering governance workflows adapted from vetted research objects.
• Documents portable migration, install, upgrade, and rollback operations.

Safety Model

Default behavior is read-only or local-report-only.

Codex_up does not automatically:

• Write global Codex configuration.
• Install external connectors.
• Send email, chat, calendar, or document writes.
• Rotate secrets.
• Rewrite Git history.
• Publish packages.

Runtime validation artifacts are written under 03-validation-results/. Run-specific artifacts under 03-validation-results/runs/ are intentionally ignored by Git.

Quick Start

powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" --help
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" schema validate --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" doctor run --quick --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" rollout audit --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" local monitor --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" local acceptance --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\tests\run_codex_up_cli_golden.ps1"

Core Commands

.\cli\codex_up.ps1 help show --format json
.\cli\codex_up.ps1 doctor run --quick --format json
.\cli\codex_up.ps1 project check --format json
.\cli\codex_up.ps1 audit secrets --format json
.\cli\codex_up.ps1 schema validate --format json
.\cli\codex_up.ps1 host validate --format json
.\cli\codex_up.ps1 rollout audit --format json
.\cli\codex_up.ps1 local monitor --format json
.\cli\codex_up.ps1 local acceptance --format json
.\cli\codex_up.ps1 provider check --format json
.\cli\codex_up.ps1 provider models --format json
.\cli\codex_up.ps1 provider review-test --format json
.\cli\codex_up.ps1 context evaluate --dry-run --format json
.\cli\codex_up.ps1 manifest refresh --dry-run --format json
.\cli\codex_up.ps1 mcp check --format json
.\cli\codex_up.ps1 skill validate --format json
.\cli\codex_up.ps1 skill lint --format json
.\cli\codex_up.ps1 memory audit --format json
.\cli\codex_up.ps1 skill crystallize --dry-run --format json
.\cli\codex_up.ps1 assistant cn-pack --format json
.\cli\codex_up.ps1 computer-use doctor --format json
.\cli\codex_up.ps1 content pipeline --format json
.\cli\codex_up.ps1 progress update --format json
.\cli\codex_up.ps1 regression final --format json

Current CLI envelope version: 1.1-design-agentic.

Project Layout

• 00-overview/: product specs, research notes, and environment setup overviews.
• 01-global-config/: global Codex configuration references.
• 02-project-reference/: source project reference assets and scripts.
• 03-validation-results/: canonical validation reports and latest regression evidence.
• 04-deployment-kit/: deployment checklist and dry-run installer.
• 05-secret-migration/: secret migration tooling and redacted inventory. The vault/ directory is ignored by Git.
• cli/: PowerShell CLI and modules.
• config/: governance configuration.
• docs/: CLI, rollout, and publication documentation.
• schemas/: JSON schema contracts.
• skills/: archived, suggested, and converted Codex skill assets.
• templates/: project, assistant, report, and security templates.
• tests/golden/: expected CLI behavior.

Current Status

The initial planning scope is complete through v1.0.

• Golden CLI validation: 125/125
• Global progress governance: 100/100
• Local implementation rollout: v1.2-local 6/6
• Next hardening wave: v1.x-next N8/8
• Final project/local environment audit: 03-validation-results/20260507_report_project-final-completion-and-local-environment-audit.md
• Current remaining warnings: historical secret exposure remains intentionally unrotated by user decision, and archived skill-library metadata is intentionally less strict than installable global skills.

See ROADMAP.md and docs/20260506_plan_github-publication-and-local-rollout.md.

PPT Production

Codex_up includes a governed PPT workflow for future presentation work:

• Guide: docs/20260507_spec_ppt-production-workflow.md
• Config: config/presentation-production.json
• Brief template: templates/presentations/deck-brief.md
• GPT-image-2 prompt template: templates/presentations/gpt-image-2-asset-prompt.md
• QA rubric: templates/presentations/deck-qa-rubric.md

Default principle: build editable PowerPoint with the Presentations plugin, and use GPT-image-2 only for supporting raster assets such as covers, editorial visuals, textures, and concept imagery.

DESIGN.md And Agentic Engineering

Codex_up v1.1 adds two research-backed workflow packs:

• DESIGN.md authoring, based on the awesome-design-md pattern: config/design-md-governance.json, templates/design/DESIGN.md, and the design-md-authoring global skill.
• Agentic engineering governance, based on Claude Code best-practice research: config/agentic-engineering-governance.json, templates/agentic-engineering/capability-map.md, and the agentic-engineering-governance global skill.

Both packs are adapted for Codex rather than copied from other tool ecosystems.

Deployment

Start with dry-run only:

powershell -NoProfile -ExecutionPolicy Bypass -File ".\04-deployment-kit\install_codex_up.ps1"

Do not run write-capable deployment steps until copy targets, backup behavior, sensitive exclusions, and rollback paths have been reviewed.

Security

See SECURITY.md.

Do not commit:

• .env or .env.*
• private keys
• token or credential files
• 05-secret-migration/vault/
• 03-validation-results/runs/

中文说明

Codex_up 是一套本地 Codex 环境治理工具，用于搭建可复现、可审计、可迁移的 Codex Desktop / Codex CLI 工作环境。

它最初是个人 Codex 环境参考包，后来被产品化为以 PowerShell 为主入口的治理工具，覆盖 golden CLI 回归测试、Schema 校验、发布审计、助理工作流治理、迁移运行手册，以及以安全为前提的 apply 规划。

能做什么

• 检查本地 Codex 环境健康状态。
• 验证项目启动所需资产。
• 审计密钥暴露、文件系统 allowlist、MCP 可用性、skills、memory governance、automation 状态和宿主机工具链。
• 输出 JSON 和 Markdown 报告。
• 维护 golden CLI 回归测试覆盖。
• 在写入全局配置前生成安全 apply 计划。
• 在 run-local 沙盒范围内验证受控写入、恢复和回滚行为。
• 提供离线优先的个人助理模板和连接器权限治理。
• 提供受治理的 PPT 生产工作流，覆盖可编辑 PowerPoint 输出、GPT-image-2 资产预设、Figma 设计参考和 deck QA 模板。
• 提供基于研究对象吸收转化的 DESIGN.md 编写和 agentic engineering 治理工作流。
• 文档化可迁移的安装、升级、回滚和运行流程。

安全模型

默认行为是只读或仅生成本地报告。

Codex_up 不会自动执行以下操作：

• 写入全局 Codex 配置。
• 安装外部连接器。
• 发送邮件、聊天消息、日历事件或文档写入。
• 轮换密钥。
• 重写 Git 历史。
• 发布软件包。

运行验证产物写入 03-validation-results/。每次运行生成的 03-validation-results/runs/ 已被 Git 忽略。

快速开始

powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" --help
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" schema validate --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" doctor run --quick --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" rollout audit --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" local monitor --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\cli\codex_up.ps1" local acceptance --format json
powershell -NoProfile -ExecutionPolicy Bypass -File ".\tests\run_codex_up_cli_golden.ps1"

核心命令

.\cli\codex_up.ps1 help show --format json
.\cli\codex_up.ps1 doctor run --quick --format json
.\cli\codex_up.ps1 project check --format json
.\cli\codex_up.ps1 audit secrets --format json
.\cli\codex_up.ps1 schema validate --format json
.\cli\codex_up.ps1 host validate --format json
.\cli\codex_up.ps1 rollout audit --format json
.\cli\codex_up.ps1 local monitor --format json
.\cli\codex_up.ps1 local acceptance --format json
.\cli\codex_up.ps1 provider check --format json
.\cli\codex_up.ps1 provider models --format json
.\cli\codex_up.ps1 provider review-test --format json
.\cli\codex_up.ps1 context evaluate --dry-run --format json
.\cli\codex_up.ps1 manifest refresh --dry-run --format json
.\cli\codex_up.ps1 mcp check --format json
.\cli\codex_up.ps1 skill validate --format json
.\cli\codex_up.ps1 skill lint --format json
.\cli\codex_up.ps1 memory audit --format json
.\cli\codex_up.ps1 skill crystallize --dry-run --format json
.\cli\codex_up.ps1 assistant cn-pack --format json
.\cli\codex_up.ps1 computer-use doctor --format json
.\cli\codex_up.ps1 content pipeline --format json
.\cli\codex_up.ps1 progress update --format json
.\cli\codex_up.ps1 regression final --format json

当前 CLI envelope 版本：1.1-design-agentic。

项目结构

• 00-overview/：产品规格、研究笔记和环境建设概览。
• 01-global-config/：全局 Codex 配置参考。
• 02-project-reference/：源项目参考资产和脚本。
• 03-validation-results/：权威验证报告和最新回归证据。
• 04-deployment-kit/：部署检查清单和 dry-run 安装器。
• 05-secret-migration/：密钥迁移工具和脱敏清单；vault/ 目录已被 Git 忽略。
• cli/：PowerShell CLI 和模块。
• config/：治理配置。
• docs/：CLI、落地和发布文档。
• schemas/：JSON Schema 契约。
• skills/：归档、建议和转换后的 Codex skill 资产。
• templates/：项目、助理、报告和安全模板。
• tests/golden/：CLI 预期行为基线。

当前状态

初始规划范围已完成到 v1.0。

• Golden CLI 验证：125/125
• 全局进度治理：100/100
• 本地实施落地：v1.2-local 6/6
• 下一轮环境加固：v1.x-next N8/8
• 最终项目/本地环境审计：03-validation-results/20260507_report_project-final-completion-and-local-environment-audit.md
• 当前剩余 warning：历史密钥暴露风险按用户决策暂不轮换；归档 skill 库的元数据要求低于可全局安装的 skill。

参见 ROADMAP.md 和 docs/20260506_plan_github-publication-and-local-rollout.md。

PPT 生产

Codex_up 已加入面向后续演示文稿制作的治理流程：

• 指南：docs/20260507_spec_ppt-production-workflow.md
• 配置：config/presentation-production.json
• 简报模板：templates/presentations/deck-brief.md
• GPT-image-2 提示词模板：templates/presentations/gpt-image-2-asset-prompt.md
• QA 评分表：templates/presentations/deck-qa-rubric.md

默认原则：用 Presentations 插件生成可编辑 PowerPoint；GPT-image-2 只用于封面、编辑性视觉、纹理、概念图等辅助位图资产。

DESIGN.md 与 Agentic Engineering

Codex_up v1.1 新增两个研究驱动的工作流包：

• DESIGN.md 编写，吸收 awesome-design-md 模式：config/design-md-governance.json、templates/design/DESIGN.md 和全局 skill design-md-authoring。
• Agentic engineering 治理，吸收 Claude Code best-practice 研究：config/agentic-engineering-governance.json、templates/agentic-engineering/capability-map.md 和全局 skill agentic-engineering-governance。

两者都转译为 Codex 原生资产，而不是直接复制其他工具生态的配置。

部署

先从 dry-run 开始：

powershell -NoProfile -ExecutionPolicy Bypass -File ".\04-deployment-kit\install_codex_up.ps1"

在确认复制目标、备份行为、敏感文件排除和回滚路径前，不要执行具备写入能力的部署步骤。

安全

参见 SECURITY.md。

不要提交：

• .env 或 .env.*
• 私钥
• token 或凭证文件
• 05-secret-migration/vault/
• 03-validation-results/runs/