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

Co-Authored-By: OpenAI Codex <codex@openai.com> Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-02 03:11:39 +08:00
parent d269ee6401
commit 81e41730ec
33 changed files with 3734 additions and 34 deletions
--- a/docs/codex_migration_status_report_2026-04-29.md
+++ b/docs/codex_migration_status_report_2026-04-29.md
@@ -0,0 +1,207 @@
+# 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 的实际运行验收。验收完成后，再把迁移文件单独提交，之后才能稳定进入新的业务开发阶段。