# Codex 迁移配置说明

本仓库已从 Claude Code 的项目配置迁移到 Codex 可识别的配置结构。

## 已迁移内容

| Claude Code | Codex | 状态 |
|-------------|-------|------|
| 根目录 `CLAUDE.md` | 根目录 `AGENTS.md` | 已迁移 |
| 子目录 `CLAUDE.md` | 子目录 `AGENTS.md` | 已迁移 |
| `.mcp.json` | `C:\Users\Administrator\.codex\config.toml` | 已迁移 |
| PostgreSQL MCP 明文 DSN | `tools/codex/mcp-postgres.ps1` 读取 `.env` / `.env.local` | 已改为间接读取 |
| `.claude/settings.local.json` 中的项目环境变量 | `shell_environment_policy.set` | 已迁移核心变量 |

## Codex 全局配置

Codex 当前读取：

```text
C:\Users\Administrator\.codex\config.toml
```

已配置的 MCP server：

- `pg-etl`：ETL 正式库，默认禁用
- `pg-etl-test`：ETL 测试库，默认启用
- `pg-app`：业务正式库，默认禁用
- `pg-app-test`：业务测试库，默认启用
- `weixin-devtools-mcp`：微信开发者工具 MCP
- `playwright`：Playwright MCP
- `openapi`：后端 OpenAPI MCP

已配置的 shell 环境变量：

- `NEOZQYY_ROOT=C:\Project\NeoZQYY`
- `VIRTUAL_ENV=C:\Project\NeoZQYY\.venv`

未覆盖全局 `PATH`，避免影响 Windows、Node.js、uv 等系统命令解析。

数据库 MCP 的 DSN 不直接写入 Codex 全局配置，启动时由 `tools/codex/mcp-postgres.ps1` 按以下优先级解析：

```text
.env < .env.local < 当前进程环境变量
```

## 验证命令

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools\codex\mcp-postgres.ps1 TEST_DB_DSN -ValidateOnly
powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools\codex\mcp-postgres.ps1 TEST_APP_DB_DSN -ValidateOnly
```

TOML 静态校验：

```powershell
@'
import pathlib, tomllib
path = pathlib.Path.home().joinpath(".codex/config.toml")
data = tomllib.loads(path.read_text(encoding="utf-8-sig"))
print(sorted(data.get("mcp_servers", {}).keys()))
'@ | .venv\Scripts\python.exe -
```

## 尚未一比一迁移的内容

Claude Code 的 `.claude/commands/*.md` 与 `.claude/hooks/*.py` 不完全等价于 Codex 当前稳定能力：

- `/audit` 等自定义命令已经沉淀在根目录 `AGENTS.md` 的审计流程中，可直接要求 Codex “执行审计流程”。
- Claude 的 `PreToolUse` / `PostToolUse` 钩子在 Codex 上仍属于实验能力，且 Windows 兼容性需要按 Codex 版本再验证；本次未默认启用，避免影响日常编辑。
- 如需恢复钩子式强校验，优先迁移 `Stop` 类审计/验证提醒，再评估文件读写前置拦截。

## 用户级 Claude 资产迁移状态

以下原始内容仍保留在 `C:\Users\Administrator\.claude` 作为备份和源材料，同时已经完成 Codex 侧迁移：

- `skills/`：10 个 Claude skill 已迁移到 `C:\Users\Administrator\.codex\skills`。
- `agents/`：8 个 Claude agent 已迁移为 Codex skill `claude-agent-roles`。
- `rules/`：`python`、`typescript`、`web`、`zh` 四组规则已迁移为 Codex skill `claude-rules-reference`，并提炼进 `C:\Users\Administrator\.codex\AGENTS.md`。
- `projects/C--Project-NeoZQYY/`：NeoZQYY 项目历史会话 94 个 JSONL 文件已摘要归档到 `docs/claude-history/`。
- `history.jsonl`、`plans/`、`file-history/` 等 Claude 本地历史与辅助状态。

Codex 不会自动学习 Claude Code 的原始历史对话，也不会自动加载 `C:\Users\Administrator\.claude\skills`。当前 Codex 可稳定读取的是：

- 仓库内 `AGENTS.md`
- `C:\Users\Administrator\.codex\config.toml`
- `C:\Users\Administrator\.codex\skills`
- 当前会话上下文与 Codex 自己生成的 memory
- `docs/claude-history/` 中的历史摘要索引

历史会话没有全文注入 Prompt，只保留脱敏摘要和索引。需要追溯时先查索引，再按需打开对应摘要；只有必要时才读取原始 JSONL。

## 使用提醒

修改 `C:\Users\Administrator\.codex\config.toml` 后，需要重启 Codex 会话或重新打开项目，MCP server 才会被重新发现。

## 本次深度迁移结果

- 用户全局习惯已写入 `C:\Users\Administrator\.codex\AGENTS.md`。
- Claude skills 已迁移 10 个到 `C:\Users\Administrator\.codex\skills`：agent-introspection-debugging, claude-api, code-tour, codebase-onboarding, repo-scan, rules-distill, search-first, security-review, strategic-compact, tdd-workflow。
- Claude agents 已迁移为 Codex skill `claude-agent-roles`，包含 8 个角色参考。
- Claude rules 已迁移为 Codex skill `claude-rules-reference`，包含 28 个规则文件。
- NeoZQYY Claude 会话历史已摘要归档到 `docs/claude-history/`：94 个会话，246 个被编辑文件索引。

### 追溯入口

- 会话索引：`docs/claude-history/session_index.csv`
- 文件索引：`docs/claude-history/file_index.csv`
- 会话摘要：`docs/claude-history/sessions/`