# Codex CLI 配置仓库

## 项目概述

本仓库收集了 Codex CLI 的个性化配置与提示词模板，目标是将资深全栈技术专家的工作方式固化为可复用的自动化流程。通过统一的模型参数、受信任项目列表以及丰富的工具集，本仓库帮助团队快速搭建一致、可审计、可扩展的 AI 协作环境。

## 核心特性

- **模型与推理策略统一**：`config.toml` 固定使用 `gpt-5-codex`，并启用高推理强度，保证复杂任务的可靠性。
- **项目信任分级**：针对常用项目配置 `trust_level`，在敏感仓库与普通仓库之间实现差异化的安全策略。
- **多工具协同**：预置 Context7、Sequential Thinking、时间查询、Playwright 等 MCP 服务，覆盖检索、规划、自动化操作等多种场景。
- **粒度化提示词库**：`prompts/` 目录按照任务阶段提供规划、实现、质检、文档等多种模版，支持组合调用。
- **中文工作流**：所有系统提示与输出约束均为中文，保证团队内部交流一致性。

## 目录结构

```
├── AGENTS.md                  # 顶层系统提示词与交互准则
├── config.toml                # Codex CLI 主配置，包含模型、项目、MCP 服务声明
├── internal_storage.json      # Codex CLI 内部持久化状态
└── prompts/                   # 任务提示词模板集合（Markdown + YAML Front Matter）
```

> 建议在提交新文件前运行 `tree` 或 `ls` 确认目录层级保持清晰；若新增子目录，请同步更新本节说明。

## 快速上手

1. **准备环境**
   - 安装最新的 Codex CLI（参考官方文档）。
   - 确保本地具备 Node.js ≥ 18 与 Python ≥ 3.11，以便运行 `npx` 与 `uvx` 命令。
2. **应用配置**
   - 将本仓库克隆到本地，例如 `~/projects/codex-config`。
   - 在 Codex CLI 的配置目录（默认 `~/.config/codex`）创建或更新符号链接，使其指向本仓库的 `config.toml` 与 `prompts/`。
   - 如需要自定义 `projects` 节点，请复制 `config.toml` 并在本地分支修改，避免直接覆盖主干。
3. **验证安装**
   - 运行 `codex doctor` 或执行一次简单对话，确认模型、项目信任与 MCP 服务均已正确加载。
   - 在 Codex CLI 中执行 `list prompts`（若 CLI 支持）确保自定义提示词可被发现。

## 配置详解

### 模型与推理

- `model = "gpt-5-codex"`：指定 Codex CLI 的默认模型。
- `model_reasoning_effort = "high"`：要求更高的思考深度，适合复杂架构或评审任务。

### 项目信任级

- `[projects."…"]`：为常用工程设定 `trust_level = "trusted"`，允许 CLI 在这些仓库执行写操作与高权限命令。
- 新增项目时建议：
  1. 先以 `read-only` 模式试运行，确认自动化流程安全；
  2. 再将 `trust_level` 调整为 `trusted`，并在 README 的“维护建议”中记录原因与风险缓解措施。

### MCP 服务

下表列出默认启用的 MCP 服务及其作用：

| 服务标识                          | 启动命令                                  | 主要用途                       |
| --------------------------------- | ----------------------------------------- | ------------------------------ |
| `context7`                        | `npx -y @upstash/context7-mcp@latest`     | 查询官方文档 / SDK 参数        |
| `sequential-thinking`             | `npx -y @modelcontextprotocol/server-sequential-thinking` | 复杂任务的分步规划            |
| `mcp-server-time`                 | `uvx mcp-server-time --local-timezone=Asia/Shanghai` | 时区转换与时间获取           |
| `mcp-shrimp-task-manager`         | `npx -y mcp-shrimp-task-manager`          | 任务拆解与可视化（中文模版）  |
| `playwright`                      | `npx @playwright/mcp@latest`              | 浏览器自动化与可视化验证       |

> **最佳实践**：所有 MCP 服务均以“最小必要”原则调用，使用前评估网络、隐私与合规风险；若调用失败，优先回退至离线操作，并在交互中说明降级措施。

### 内部存储

- `internal_storage.json` 记录 CLI 的轻量状态，例如模型提示词是否已展示。除非调试，通常无需修改；若需要重置，可在停止 CLI 后删除该文件。

## 提示词模板说明

### 模板结构

- 每个 Markdown 文件以 YAML Front Matter 开头（如 `description` 字段），用于在 CLI 中生成摘要信息。
- 正文包含执行步骤、输入要求与安全边界，所有文本采用中文约束，确保输出一致性。
- 模板遵循“只描述，不执行”的理念：实际的文件编辑或命令执行由 Codex CLI 调度完成。

### 分类总览

| 分类           | 文件示例                                 | 功能说明                                               |
| -------------- | ---------------------------------------- | ------------------------------------------------------ |
| 规划与分析     | `analyze.md`、`tasks.md`、`instruction-reflector.md` | 生成任务分解、校验规范、反思指令一致性                 |
| 设计与文档     | `specify.md`、`insight-documenter.md`、`api-docs.md` | 产出规格说明、知识沉淀、API 文档                       |
| 实施与测试     | `implement.md`、`gen-tests.md`、`optimize.md` | 指导编码实现、测试生成与性能优化                       |
| 质检与评审     | `review-code.md`、`github-pr-reviewer.md`、`commit-msg.md` | 代码评审、PR 审核、提交信息撰写                       |
| 调试与支持     | `debug.md`、`clarify.md`、`check-env.md` | 问题定位、需求澄清、环境检查                           |
| 专用场景       | `kiro-*.md` 系列                         | 针对 Kiro 产品线的特定流程（需求评审、特性设计等）     |
| UI/前端        | `ui-engineer.md`                         | 聚焦界面实现与交互策略                                 |

> **提示**：添加新模板时保持命名一致性（动词-名词），并在 Front Matter 的 `description` 里使用一句话中文概括，方便快速检索。

### 完整模板清单

| 模板文件 | 典型用途 |
| -------- | -------- |
| `analyze.md` | 交叉校验规格、计划与任务的一致性 |
| `api-docs.md` | 汇总或生成接口文档与参数说明 |
| `check-env.md` | 排查运行环境与依赖配置 |
| `clarify.md` | 引导澄清不完整或歧义的需求 |
| `commit-msg.md` | 帮助撰写符合规范的提交信息 |
| `constitution.md` | 定义或回顾项目的宪章级原则 |
| `db-schema.md` | 设计领域数据模型与数据库结构 |
| `debug.md` | 分析定位故障与异常原因 |
| `deep-reflector.md` | 深度反思任务执行策略与改进点 |
| `explain.md` | 解释代码、正则表达式等技术细节 |
| `gen-tests.md` | 生成或完善测试用例 |
| `github-issue-fixer.md` | 分析 GitHub Issue 并提供解决方案 |
| `github-pr-reviewer.md` | 审查 Pull Request 并输出评审意见 |
| `implement.md` | 按 tasks.md 执行实现计划 |
| `insight-documenter.md` | 记录关键洞察与技术总结 |
| `instruction-reflector.md` | 对既有指令进行复盘与优化 |
| `kiro-assistant.md` | 支持 Kiro 产品线的一般性工作流 |
| `kiro-feature-designer.md` | 规划 Kiro 新特性的需求与设计 |
| `kiro-spec-creator.md` | 为 Kiro 场景编写规格文档 |
| `kiro-task-executor.md` | 执行 Kiro 专属任务清单 |
| `kiro-task-planner.md` | 拆解 Kiro 需求并生成任务计划 |
| `optimize.md` | 优化查询、算法或系统性能 |
| `prompt-creator.md` | 辅助设计新的提示词模板 |
| `refactor.md` | 指导代码重构与结构调整 |
| `review-code.md` | 进行代码评审与缺陷识别 |
| `specify.md` | 编写或完善规格说明 |
| `tasks.md` | 生成分阶段、可执行的任务列表 |
| `ui-engineer.md` | 聚焦界面实现、交互与样式策略 |

### 使用建议

- 在 Codex CLI 中调用命令时，优先选择语义最贴近的模板；若存在流程依赖（如先 `/tasks` 后 `/implement`），请严格按模板所述顺序执行。
- 模板强调“安全边界”：若出现读写限制、需要人工审批等提醒，请在实际操作前与团队确认。
- 若某些模板需要特定项目结构（如 `.specify/` 目录），请在调用前确认目标仓库已满足前置条件。

### 命令调用示例

- `/explain "这个正则表达式：^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).{8,}$"`
- `/explain "为什么这段 Go 代码在并发下产生数据竞态？"`
- `/debug "Docker 容器启动后立即退出，exit code 137"`
- `/debug "K8s Pod 健康检查失败，Readiness probe 超时"`
- `/optimize "SELECT * FROM orders WHERE user_id = ?"`
- `/optimize "GraphQL 列表查询延迟高，如何分页与缓存？"`
- `/db-schema "博客平台：文章、评论、标签、分类、用户关注"`
- `/db-schema "电商：用户、商品、库存、订单、支付、退款"`
- `/analyze "对 feature-X 的 spec.md/plan.md/tasks.md 做一致性分析"`
- `/api-docs "订单服务 v1：列出/创建/取消订单接口，返回 JSON Schema"`
- `/check-env "Node 18 + pnpm + Docker Desktop + Postgres 需要检查哪些项？"`
- `/clarify "报表导出的‘增量模式’应该如何定义时间窗口？"`
- `/commit-msg "feat: 支持多租户鉴权与组织切换"`
- `/constitution "新增隐私数据处理原则：最小化采集、可追溯、可删除"`
- `/deep-reflector "回顾上周生产事故的根因、缓解与长期改进项"`
- `/gen-tests "为用户注册接口补充单测：邮箱校验、重复注册、速率限制"`
- `/github-issue-fixer "#1234 CI 构建偶发失败：超时 60s"`
- `/github-pr-reviewer "#5678 增加缓存层与指标打点，请给出风险与建议"`
- `/implement "按 tasks.md 的 Core 阶段开始实现并输出变更清单"`
- `/insight-documenter "总结搜索性能优化洞察：索引、分页、缓存、N+1"`
- `/instruction-reflector "审查 /optimize 模板是否与 AGENTS.md 原则一致"`
- `/kiro-assistant "整理 Kiro 看板的优先级、依赖与风险"`
- `/kiro-feature-designer "为‘智能模板’设计 MVP 范围与验收标准"`
- `/kiro-spec-creator "为‘知识库同步’编写规格：触发、冲突合并、安全"`
- `/kiro-task-executor "执行 Sprint-12 的集成与验收任务"`
- `/kiro-task-planner "将‘评论系统’拆解为 5 个可并行任务"`
- `/prompt-creator "生成用于代码评审的团队风格化提示词"`
- `/refactor "重构 monolith：拆分 auth、billing、report 三个模块"`
- `/review-code "评审 PR #4321：关注并发安全、可测试性、日志"`
- `/specify "编写‘导出报表’功能的规格：功能、非功能、边界"`
- `/tasks "基于 spec.md 与 plan.md 生成任务清单"`
- `/ui-engineer "设计订单列表的空态、加载态与错误态"`

## 维护与扩展指南

- **版本管理**：新增或更新模板后，请在提交信息中说明变更动机、适用场景与风险缓解措施。
- **一致性检查**：对 `AGENTS.md` 的改动会影响所有任务，请保持审慎；建议在合并前进行团队评审。
- **测试流程**：在真实项目中试运行新模板，记录反馈并回写到模板末尾的注意事项或到本 README 的维护章节。
- **多语言需求**：若需支持英文等其他语言，建议建立独立分支或目录，避免混用导致输出风格混乱。

## 常见问题

- **无法启动 MCP 服务？** 检查本地是否安装 `npx`、`uvx` 等命令；若网络受限，请寻求离线替代方案，并在 CLI 中提示用户。
- **提示词输出为英文？** 确认调用时没有覆盖系统提示；必要时重启 CLI，使 `AGENTS.md` 中的中文约束重新生效。
- **项目未列在 `projects` 中？** CLI 将以默认信任级运行，可能限制写操作。根据需要手动将仓库添加到 `config.toml`。

## 后续规划

- 跟随 Codex CLI 版本迭代，持续验证指令兼容性。
- 根据团队反馈扩展 UI、数据工程、运维等领域的模板，并在本 README 更新分类表。
- 探索通过 MCP 管理更多基础设施（如日志查询、工单系统），并确保遵守安全合规原则。

---

欢迎在实际使用中记录经验与改进建议，并通过 Issue 或 Pull Request 反馈，共同完善这套中文友好的 Codex 工作流。