迁移 Claude/Codex/Cursor 开发环境与追溯资产

Co-Authored-By: OpenAI Codex <codex@openai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

docs/codex_migration.md

@@ -0,0 +1,108 @@
+# 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/`