docs: codex - add setup readme and global agents

config/.codex/AGENTS.md

@@ -1,28 +1,29 @@
-# config/.codex 目录 Agent 指南
+# Codex CLI 全局指令（可直接用作 `~/.codex/AGENTS.md`）
 
-本目录用于维护 **Codex CLI 的项目级配置**（主要是 `config.toml`）。目标是：让团队/自己在不同机器上有一份可追踪、可回滚的配置基线。
+本文件建议与 `config.toml` 配套使用：把它们复制到你的 Codex Home（默认 `~/.codex/`）后即会生效。
 
-## 目录结构
+目标：让 Codex 在“自动化效率”和“工程可控性”之间取得平衡，**以可回滚、可审计、可维护为第一优先级**。
 
-```text
+## 核心行为准则
-config/.codex/
-├── AGENTS.md     # 本文件（目录级约束与说明）
-└── config.toml   # Codex CLI 配置（含详细中文注释）
-```
 
-## 操作规范
+- 优先做 **最小变更**：能局部修就不大改；能补齐文档就不重写结构。
+- 输出必须 **可验证**：给出验证命令/最小复现/预期结果（能跑则跑，不能跑说明原因）。
+- 不确定就标注 **假设**：关键事实缺失时，明确写出假设并降低动作幅度。
+- 保持结构稳定：避免无意义的重排与改名，减少 diff 噪音。
 
-### 允许
+## 安全与不可逆操作（强约束）
-- 维护 `config.toml` 的结构、注释与默认值（以“可理解 + 可回滚”为第一优先级）
-- 增补/更新配置项的中文注释（说明用途、风险、推荐值）
 
-### 禁止 / 强烈不推荐
+- 任何可能导致数据丢失的动作（删除、覆盖、清库、强推等）都必须 **先停下来确认**。
-- 在 `config.toml` 或本目录写入任何密钥、Token、个人隐私路径等敏感信息
+- 禁止把密钥/Token/个人隐私路径写入仓库、配置或日志。
-- 把配置写成“只有你自己机器能用”的硬编码（如必须存在的绝对路径）
+- 处理不可信脚本/目录时，先只读检查，再决定是否执行。
 
-## 维护原则（约定）
+## 命令执行约束
 
-- **注释优先**：新增配置项时必须写清楚“为什么需要它、不开会怎样、风险是什么”。
+- 优先使用只读命令（例如 `rg`、`git diff`、`ls`）定位问题，再运行写操作。
-- **最小惊讶**：默认值尽量保守；高风险选项（例如放开权限）要明确标注风险与适用场景。
+- 批量操作必须可回滚：优先 `git` 可追踪的改动；必要时先提交快照或做备份。
-- **结构稳定**：同类配置放在同一段落，避免频繁无意义的重排导致 diff 噪音。
+- 长时间运行的命令必须说明用途、预计影响面，并尽量带非交互参数。
 
+## 文档与配置维护原则
+
+- 新增配置项必须写清楚：用途、默认值理由、风险、何时需要改。
+- 能用相对路径就不用绝对路径；如不得不用，必须解释并给出替代方案。

config/.codex/README.md

@@ -0,0 +1,49 @@
+# `config/.codex/` 用法说明
+
+本目录用于在仓库内版本化管理 Codex CLI 的“全局配置基线”，便于多人同步、审阅与回滚。
+
+你只需要把本目录里的两个文件复制到 **Codex Home**（默认 `~/.codex/`）即可生效：
+
+- `config/.codex/config.toml` → `~/.codex/config.toml`
+- `config/.codex/AGENTS.md` → `~/.codex/AGENTS.md`
+
+## 1. 一键安装（推荐）
+
+在仓库根目录执行：
+
+```bash
+mkdir -p ~/.codex
+cp -f config/.codex/config.toml ~/.codex/config.toml
+cp -f config/.codex/AGENTS.md ~/.codex/AGENTS.md
+```
+
+## 2. 路径示例
+
+### Linux / WSL（实际生效位置）
+
+- `\\wsl.localhost\\Ubuntu\\home\\<你的用户名>\\.codex\\config.toml`
+- `\\wsl.localhost\\Ubuntu\\home\\<你的用户名>\\.codex\\AGENTS.md`
+
+（在 WSL 内对应：`~/.codex/config.toml` 与 `~/.codex/AGENTS.md`）
+
+### Windows（原生）
+
+Codex Home 默认是 `~/.codex/`；在 Windows 上 `~` 通常展开为用户目录：
+
+- `C:\\Users\\<你的用户名>\\.codex\\config.toml`
+- `C:\\Users\\<你的用户名>\\.codex\\AGENTS.md`
+
+如果你自己的 Codex Home 被改到了其它位置（例如 `C:\\Users\\<你的用户名>\\.config\\...`），请把两份文件复制到你实际的 Codex Home。
+
+## 3. 配置优先级（重要）
+
+- **全局配置**：`~/.codex/config.toml`
+- **项目覆盖**：在项目根目录创建 `.codex/config.toml`（仅对当前项目生效）
+
+如果你想把某些配置“只对本仓库生效”，建议使用项目覆盖（`.codex/config.toml`），全局配置只保留你长期通用的习惯与安全策略。
+
+## 4. 参考（官方文档）
+
+- Configuration / Config file：说明 `~/.codex/config.toml` 与项目级 `.codex/config.toml` 的优先级
+- Custom instructions / Global instructions：说明 `~/.codex/AGENTS.md` 的全局指令加载方式
+