Neo-ZQYY/docs/codex_migration_status_report_2026-04-29.md

# Codex 迁移阶段状态报告

| 字段 | 内容 |
|------|------|
| 生成时间 | 2026-04-29 04:01:26 |
| 范围 | 从 Claude Code 迁移至 Codex 的环境、配置、使用习惯、skills、agents、rules 与历史追溯资产 |
| 当前结论 | 已进入“深度迁移完成，等待 Codex 重启生效与后续验收”的阶段 |

## 一、按时间线看当前进行到哪一步

| 时间 | 阶段 | 状态 | 说明 |
|------|------|------|------|
| 2026-04-20 至 2026-04-22 | Claude Code 主要业务开发期 | 已归档 | Claude 历史显示这段时间有大量跨后端、admin-web、小程序、数据库、文档和脚本的修改。 |
| 2026-04-28 | Claude Code 尾声会话 | 已归档 | 最新 Claude 项目会话 `67f30f8e-2db7-467f-82e0-5395f9ed855f` 未检测到文件写入，偏向过渡/查询类会话。 |
| 2026-04-29 03:30 左右 | Codex 基础迁移 | 已完成 | 已迁移根/子目录 `AGENTS.md`、MCP 配置、PostgreSQL MCP 启动脚本、环境变量。 |
| 2026-04-29 03:54 左右 | Codex 深度迁移 | 已完成 | 已迁移 Claude skills、agents、rules、用户全局习惯，并生成 Claude 历史摘要归档。 |
| 2026-04-29 03:57 左右 | 审计固化 | 已完成 | 已生成审计记录并刷新审计面板。 |
| 当前 | 验收与生效阶段 | 进行中 | 需要重启 Codex 或重新打开项目，让新的全局规则、skills 和 MCP 配置完整加载。 |

## 二、已经完成的迁移

### 1. 项目级规则

- 根目录 `CLAUDE.md` 已迁移为 `AGENTS.md`。
- 子模块规则已补齐：
  - `apps/backend/AGENTS.md`
  - `apps/etl/connectors/feiqiu/AGENTS.md`
  - `apps/demo-miniprogram/AGENTS.md`
  - `db/AGENTS.md`

### 2. Codex 全局配置

- `C:\Users\Administrator\.codex\config.toml` 已配置 NeoZQYY 项目信任、MCP server 和 shell 环境变量。
- PostgreSQL MCP 已改为通过 `tools/codex/mcp-postgres.ps1` 间接读取 `.env` / `.env.local` / 当前环境变量，避免把 DSN 明文写入 Codex 配置。
- 已配置 MCP：
  - `pg-etl`：正式 ETL 库，默认禁用
  - `pg-etl-test`：测试 ETL 库，默认启用
  - `pg-app`：正式业务库，默认禁用
  - `pg-app-test`：测试业务库，默认启用
  - `weixin-devtools-mcp`
  - `playwright`
  - `openapi`

### 3. 用户习惯、skills、agents、rules

- 用户全局习惯已写入 `C:\Users\Administrator\.codex\AGENTS.md`。
- Claude skills 已迁移 10 个到 `C:\Users\Administrator\.codex\skills`。
- Claude agents 已迁移为 Codex skill：`claude-agent-roles`，包含 8 个角色参考。
- Claude rules/steering/pre-prompt 已迁移为 Codex skill：`claude-rules-reference`。
- Codex 当前可发现的用户级 skill 数量：12 个。

### 4. Claude 对话历史追溯

- 已生成 `docs/claude-history/`。
- 已归档 Claude 项目会话摘要：94 个。
- 已建立文件反向索引：246 个被编辑文件。
- 追溯入口：
  - `docs/claude-history/session_index.csv`
  - `docs/claude-history/file_index.csv`
  - `docs/claude-history/sessions/`

### 5. 审计与文档

- 迁移说明：`docs/codex_migration.md`
- 审计记录：`docs/audit/changes/2026-04-29__codex_migration_and_claude_history_archive.md`
- 审计面板：`docs/audit/audit_dashboard.md`
- 可重复迁移脚本：`tools/codex/migrate_claude_assets.py`

## 三、已经完成的验证

| 验证项 | 结果 |
|--------|------|
| Codex skill 校验 | 12/12 通过 |
| Claude 会话摘要数量 | 94 个 |
| 文件反向索引数量 | 246 个唯一文件 |
| PostgreSQL MCP 测试库启动配置 | `TEST_DB_DSN -ValidateOnly` 通过 |
| PowerShell MCP 脚本语法 | 通过 |
| Python 迁移脚本语法 | 通过 |
| 迁移产物敏感信息扫描 | 未发现常见 DSN/API key/密码形态 |
| 审计预扫描 | 已执行，需审计，已补审计记录 |

## 四、还没有解决或需要注意的遗留问题

### 1. Codex 需要重启生效

`config.toml`、`C:\Users\Administrator\.codex\AGENTS.md` 和新迁移的 skills 需要重启 Codex 或重新打开项目后才能稳定加载。

### 2. MCP 只完成静态与启动配置验证

当前已验证 TOML、PostgreSQL MCP 启动脚本和环境变量解析，但还没有在重启后的 Codex 会话里逐个调用 MCP 工具确认可用性。尤其需要后续确认：

- PostgreSQL 测试库 MCP 是否能列 schema / 执行只读 SQL。
- WeChat DevTools MCP 是否能连接当前微信开发者工具。
- Playwright MCP 是否能正常打开本地页面。
- OpenAPI MCP 是否能在后端服务启动后读取接口。

### 3. Claude hooks 没有一比一启用

Claude Code 的 `PreToolUse`、`PostToolUse`、`Stop` hooks 没有在 Codex 里默认启用。当前替代方式是：

- 把规则写入 `AGENTS.md`。
- 把审计流程写入项目规范。
- 保留迁移说明中关于 hooks 的差异。

遗留风险是：原来由 hooks 自动拦截的行为，现在主要依赖 Codex 遵循规则和人工/脚本验证。

### 4. Claude 历史是摘要，不是全文记忆

历史归档是脱敏摘要和索引，不是原始对话全文导入。它能回答“哪个会话可能改了哪个文件、用了哪些命令、有什么 SQL/风险线索”，但不能保证完整还原每个自然语言决策。

关键问题追溯时仍需组合使用：

- `docs/claude-history/file_index.csv`
- 对应 `sessions/<session_id>.md`
- 原始 Claude JSONL
- git diff / git blame
- `docs/audit/changes/`
- 当前代码与测试结果

### 5. 部分 Claude skill 带有 Claude 专属语境

如 `claude-api`、部分 agent/skill 文案仍可能包含 Claude Code 专属术语。它们已经可被 Codex 发现，但实际使用时需要按 Codex 工具能力做等价替换。

### 6. 工作区仍有大量既有未提交业务改动

本轮迁移没有处理此前已有的业务代码改动。当前迁移相关文件仍未提交，工作区还存在其他历史未提交内容。后续提交时需要隔离本次迁移文件，避免混入业务改动。

## 五、当前仓库内本轮新增/修改文件

### 迁移配置与规则

- `AGENTS.md`
- `apps/backend/AGENTS.md`
- `apps/demo-miniprogram/AGENTS.md`
- `apps/etl/connectors/feiqiu/AGENTS.md`
- `db/AGENTS.md`

### 工具脚本

- `tools/codex/mcp-postgres.ps1`
- `tools/codex/migrate_claude_assets.py`

### 迁移与历史文档

- `docs/codex_migration.md`
- `docs/claude-history/`
- `docs/codex_migration_status_report_2026-04-29.md`

### 审计

- `docs/audit/changes/2026-04-29__codex_migration_and_claude_history_archive.md`
- `docs/audit/audit_dashboard.md`

## 六、未来工作安排建议

### 第一阶段：生效验收

1. 重启 Codex 或重新打开 NeoZQYY 项目。
2. 确认 Codex 能看到新增 skills：
   - `claude-agent-roles`
   - `claude-rules-reference`
   - `tdd-workflow`
   - `security-review`
   - `search-first`
3. 逐个验证 MCP：
   - `pg-etl-test`
   - `pg-app-test`
   - `weixin-devtools-mcp`
   - `playwright`
   - `openapi`

### 第二阶段：迁移产物固化

1. 单独提交 Codex 迁移相关文件。
2. 不混入既有业务代码改动。
3. 提交信息使用中文描述，并按项目规范保留 Co-Authored-By 签名行。

### 第三阶段：历史追溯增强

1. 按业务模块补充历史摘要标签，例如 AI、财务看板、小程序聊天、触发器、数据库迁移。
2. 对 2026-04-20 至 2026-04-22 的高影响会话做人工二次摘要。
3. 将关键“设计决策”从历史摘要中提炼到 `docs/audit/` 或对应模块文档。

### 第四阶段：恢复强校验能力

1. 评估 Codex hooks 当前版本在 Windows 上的稳定性。
2. 优先恢复 Stop 类检查：
   - 是否需要审计
   - 是否需要测试验证
   - 是否涉及数据库文档同步
3. 再评估 PreToolUse / PostToolUse 类拦截。

### 第五阶段：继续业务开发前的固定流程

后续任何逻辑改动前，建议固定执行：

1. 查 `docs/claude-history/file_index.csv`，确认目标文件历史会话。
2. 查 `docs/audit/changes/`，确认最近审计记录。
3. 读取当前文件和调用链。
4. 输出改动前上下文摘要。
5. 实施后运行测试、输出 diff 摘要和风险清单。

## 七、阶段性结论

当前不是“刚开始迁移”，也不是“已经可以无感继续业务开发”。准确位置是：

> Codex 深度迁移已经完成，历史追溯体系已经建立；下一步是重启 Codex 让配置生效，并做 MCP/skills 的实际运行验收。验收完成后，再把迁移文件单独提交，之后才能稳定进入新的业务开发阶段。