迁移 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/audit/changes/2026-04-29__codex_migration_and_claude_history_archive.md
+++ b/docs/audit/changes/2026-04-29__codex_migration_and_claude_history_archive.md
@@ -0,0 +1,60 @@
+# 变更审计记录：Codex 深度迁移与 Claude 历史摘要归档
+
+| 字段 | 值 |
+|------|-----|
+| 日期 | 2026-04-29 03:57:55 |
+
+## 操作摘要
+
+本轮将 Claude Code 的项目规则、用户习惯、skills、agents、rules 和 NeoZQYY 项目历史会话迁移到 Codex 可读取的结构。迁移目标是让 Codex 尊重用户此前的使用习惯，并在后续修改代码时能追溯“哪次 Claude 会话改了什么、影响了什么”。
+
+迁移没有把 Claude 原始对话全文注入 Prompt，而是生成脱敏摘要、会话索引和文件反向索引，避免过时信息和敏感信息污染日常上下文。
+
+## 变更文件
+
+### 新增
+
+- `AGENTS.md`：根项目 Codex 工作规范。
+- `apps/backend/AGENTS.md`：后端模块 Codex 规则。
+- `apps/etl/connectors/feiqiu/AGENTS.md`：ETL 飞球模块 Codex 规则。
+- `apps/demo-miniprogram/AGENTS.md`：demo 小程序模块保护规则。
+- `db/AGENTS.md`：数据库目录 Codex 规则。
+- `tools/codex/mcp-postgres.ps1`：Codex PostgreSQL MCP 启动脚本，按变量名读取 `.env` / `.env.local` / 当前环境。
+- `tools/codex/migrate_claude_assets.py`：Claude 资产迁移脚本。
+- `docs/codex_migration.md`：Codex 迁移状态说明。
+- `docs/claude-history/`：Claude 会话摘要归档、会话索引和文件反向索引。
+
+## 改动注解
+
+- `tools/codex/migrate_claude_assets.py`：实现可重复迁移流程，转换 Claude skills、agents、rules，生成全局 Codex 习惯文件，并对 Claude JSONL 历史做脱敏摘要和索引。
+- `tools/codex/mcp-postgres.ps1`：避免把数据库 DSN 明文写入 Codex 配置，支持 `-ValidateOnly` 做环境巡检。
+- `docs/claude-history/session_index.csv`：记录 94 个 Claude 会话的时间范围、影响范围、风险标签和摘要文件。
+- `docs/claude-history/file_index.csv`：记录 246 个被编辑文件与 Claude 会话的关联，支持按文件追溯。
+- `docs/codex_migration.md`：同步迁移结果、验证方式和追溯入口。
+- `db/AGENTS.md`：高风险目录规则文件，仅迁移原 Claude DB 指令，没有修改 DDL 或迁移 SQL。
+
+## 数据库变更
+
+无数据库 schema 变更。未新增迁移 SQL，未修改 DDL。
+
+## 风险与回滚
+
+- 中：Claude 历史摘要为脚本自动提取，可能遗漏自然语言中描述的影响。回溯关键问题时仍需查看原始 JSONL、git diff、审计记录和测试结果。
+- 中：Claude skill 中部分内容包含 Claude Code 专属命令或 agent 概念，已迁移为 Codex skill/reference，但使用时需要按 Codex 工具等价替换。
+- 低：Codex hooks 未默认启用，原 Claude hooks 的强校验不是一比一恢复；当前由 AGENTS 规则和审计流程承接。
+- 回滚：删除新增的 `AGENTS.md` / `docs/claude-history/` / `docs/codex_migration.md` / `tools/codex/*`，并恢复 `C:\Users\Administrator\.codex` 下自动生成前的备份。
+
+## 验证
+
+- `python scripts/audit/prescan.py --files "<本次迁移文件列表>"`：审计预扫描通过，未发现缺失文档同步。
+- `python -m py_compile tools/codex/migrate_claude_assets.py`：迁移脚本语法通过。
+- `powershell.exe -NoProfile -ExecutionPolicy Bypass -File tools\codex\mcp-postgres.ps1 TEST_DB_DSN -ValidateOnly`：PostgreSQL MCP 启动配置检查通过。
+- Codex skill 校验：12/12 个迁移后的 skill 通过 `quick_validate.py`。
+- 历史归档校验：生成 94 个会话摘要、94 条会话索引、246 个文件反向索引。
+- 敏感信息扫描：生成的历史摘要、迁移说明和 Codex skills 未发现常见 DSN/API key/密码形态。
+
+## 合规检查
+
+- 文档同步：已同步到 `docs/codex_migration.md` 和 `docs/claude-history/README.md`。
+- 数据库文档：不适用，本轮无 schema 变更。
+- 审计记录：已落盘。
--- a/docs/audit/changes/2026-05-01__cursor_migration.md
+++ b/docs/audit/changes/2026-05-01__cursor_migration.md
@@ -0,0 +1,47 @@
+# 变更审计记录：Cursor AI 开发环境迁移
+
+| 字段 | 值 |
+|------|-----|
+| 日期 | 2026-05-02 00:05:37 |
+
+## 操作摘要
+
+本轮将 Claude Code 与 Codex 中已经沉淀的 AI 开发习惯迁移到 Cursor 原生结构。迁移目标是让 Cursor 继承中文沟通、前置调研、验证、审计、子代理审查、MCP 测试库优先和历史追溯习惯，同时避免把长规则和原始对话全文堆入常规上下文。
+
+## 变更文件
+
+### 新增/修改
+
+- `tools/cursor/migrate_ai_environment.py`：可重复迁移脚本。
+- `.cursor/rules/`：Cursor 项目级短规则。
+- `.cursor/skills/`：审计、前置调研、文档同步和 spec 收尾流程技能。
+- `.cursor/hooks.json`、`.cursor/hooks/ai_env_guard.py`：轻量提醒/保护 hooks。
+- `docs/cursor_migration.md`：Cursor 迁移说明。
+- `docs/ai-env-history/`：Claude/Codex/Cursor 原始对话精简索引和逐会话摘要。
+- `AGENTS.md` / `CLAUDE.md`：补充 CLI / Shell 中文编码处理规则，要求 UTF-8、乱码复核、中文路径正确加引号。
+- `C:\Users\Administrator\.cursor\skills`：用户级技能迁移。
+- `C:\Users\Administrator\.cursor\agents`：用户级子代理迁移。
+
+## 数据库变更
+
+无数据库 schema 变更。未执行 DDL，未修改迁移 SQL。
+
+## 风险与回滚
+
+- 中：Cursor hooks 与 Claude hooks 事件字段不完全一致，本轮只启用轻量提醒和 ask，不启用强阻断。
+- 中：历史摘要从原始 JSONL 自动分析，仍可能遗漏自然语言里的隐含决策；关键判断需回看原文和当前代码。
+- 低：用户级 Cursor 资产覆盖前已备份，可从 manifest 恢复。
+- 低：Windows 终端中文输出可能受代码页影响；已在根规则和 Cursor 核心规则中要求 UTF-8、乱码不采信、必要时重跑。
+
+## 验证
+
+- 运行 `python tools/cursor/migrate_ai_environment.py --check` 校验生成结构。
+- 运行 `python scripts/audit/prescan.py --files "<本轮迁移文件>"` 做审计预扫描。
+- 解析 `.mcp.json`、`.cursor/hooks.json`、skill/subagent frontmatter。
+- 运行 `.venv\Scripts\python.exe scripts\audit\prescan.py --files "AGENTS.md,CLAUDE.md,.cursor/rules/neozqyy-core.mdc,tools/cursor/migrate_ai_environment.py"` 校验中文规则增量。
+
+## 合规检查
+
+- 文档同步：已新增 `docs/cursor_migration.md` 和 `docs/ai-env-history/README.md`。
+- 数据库文档：不适用，本轮无 schema 变更。
+- 审计记录：已落盘。
--- a/docs/codex_migration.md
+++ b/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/`
--- 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 的实际运行验收。验收完成后，再把迁移文件单独提交，之后才能稳定进入新的业务开发阶段。
--- a/docs/cursor_migration.md
+++ b/docs/cursor_migration.md
@@ -0,0 +1,108 @@
+# Cursor AI 开发环境迁移说明
+
+## 状态
+
+本轮把 NeoZQYY 的 AI 开发环境从 Claude Code / Codex 迁移到 Cursor 原生资产：
+
+- 项目规则：`.cursor/rules/`
+- 项目流程技能：`.cursor/skills/`
+- 用户技能：`C:\Users\Administrator\.cursor\skills`
+- 用户子代理：`C:\Users\Administrator\.cursor\agents`
+- 轻量 hooks：`.cursor/hooks.json` 与 `.cursor/hooks/`
+- 历史索引：`docs/ai-env-history/`
+
+## 去重原则
+
+1. 当前仓库 `AGENTS.md` 是项目权威规则。
+2. `CLAUDE.md` 保留为历史兼容来源。
+3. `.cursor/rules` 只放短规则和入口，不复制长文。
+4. skills 使用“短入口 + reference”，避免每次会话加载过多旧内容。
+5. 原始对话逐一分析为摘要和索引，不把原始 JSONL 全文写入仓库。
+
+## 模型偏好
+
+用户主要使用 GPT 5.5 与 Claude 4.7。Cursor 的实际模型选择由当前会话或 UI 控制；本迁移只把偏好写入规则和说明，不强写不可控的内部模型字段。
+
+## 内置流程与规则边界
+
+Cursor、GPT 5.5、Claude 4.7 都具备调研、审计、验证、子代理和工具调用能力，但它们不知道 NeoZQYY 的项目事实、历史踩坑、数据库口径、RLS 双 schema、demo 标杆保护和审计路径。因此仍需要项目规则和技能作为触发器与约束。
+
+规则不重复实现模型能力，只固化三类内容：
+
+- 项目事实：目录职责、数据库、ETL、后端、前端、小程序约定。
+- 用户习惯：中文、先调研、再改动、再验证、再审计。
+- 风险边界：生产库禁用、敏感信息不扩散、危险 git/SQL/归档目录保护。
+
+## 历史入口
+
+- 新索引：`docs/ai-env-history/README.md`
+- Claude 摘要：`docs/claude-history/README.md`
+- 审计一览：`docs/audit/audit_dashboard.md`
+- Codex 迁移说明：`docs/codex_migration.md`
+
+## 用户级资产触发策略
+
+### 保留自然触发
+
+- `neozqyy-cursor-migration`：NeoZQYY 迁移和历史追溯入口。
+- `strategic-compact`：长会话上下文压缩建议。
+- `claude-api`：仅在 Anthropic / Claude API 场景触发。
+
+### 改为显式触发
+
+- `claude-agent-roles`：旧 Claude agents 参考；日常使用 Cursor subagents。
+- `claude-rules-reference`：旧 Claude rules 档案；当前权威规则是 `AGENTS.md` 与 `.cursor/rules/`。
+- `tdd-workflow`：详细 TDD 参考；日常入口是 `tdd-guide` subagent。
+- `security-review`：详细安全 checklist；日常入口是 `security-reviewer` subagent。
+- `search-first`：通用搜索优先流程；NeoZQYY 内优先使用 `.cursor/skills/pre-change`。
+- `rules-distill`、`repo-scan`、`codebase-onboarding`、`code-tour`、`agent-introspection-debugging`：低频或重型工具，按需显式使用。
+
+保留全部 8 个用户级 subagents：`planner`、`architect`、`code-reviewer`、`security-reviewer`、`database-reviewer`、`python-reviewer`、`tdd-guide`、`refactor-cleaner`。
+
+## Hooks 强度判断
+
+当前 hooks 保持轻量提醒和 ask，不默认强阻断。建议：
+
+- `_archived/` 读取/搜索：已升级为 `failClosed` 强阻断。依据：项目规则明确禁止参考归档目录，误用概率高。
+- 危险 git 命令：保持 ask，不建议 `failClosed`。依据：极少数维护场景可能需要，必须由用户明确确认。
+- 生产库 MCP / 生产 DSN：只读调用走 ask；写入/DDL 类调用 deny。依据：测试库足够覆盖日常验证，生产库写操作风险高。
+- demo-miniprogram：保持提醒，不建议强阻断。依据：它是标杆目录，偶尔仍可能需要按用户明确要求修改。
+- DB schema 改动提醒：保持提醒。依据：是否需要文档同步要结合实际变更判断。
+
+## MCP 策略
+
+延续既有用途：
+
+- `pg-etl-test`、`pg-app-test`：测试库，默认可用。
+- `pg-etl`、`pg-app`：生产库，默认禁用或 ask，不自动执行。
+- `weixin-devtools-mcp`：小程序调试和截图验证。
+- `playwright` / `cursor-ide-browser`：Web 前端验证、截图、交互检查。
+- `openapi`：后端 API 合同查询。
+
+## VSCode Insiders 迁移
+
+- 用户数据目录：`C:\Users\Administrator\AppData\Roaming\Code - Insiders\User`
+- 扩展清单：`C:\Users\Administrator\.vscode-insiders\extensions\extensions.json`
+- Cursor 扩展对照表：`docs/ai-env-history/vscode_insiders_extensions.csv`
+- 补装脚本：`tools/cursor/install_vscode_insiders_extensions.ps1`
+- 旧环境 disabled 状态已记录；Cursor 没有稳定 CLI 持久禁用接口，补装后需要在 Cursor UI 中按清单确认禁用状态。
+
+## 主题时间线
+
+- 主题时间线：`docs/ai-env-history/topic_timeline.md`
+- 主题 CSV：`docs/ai-env-history/topic_timeline.csv`
+
+## 验证
+
+```powershell
+.venv\Scripts\python.exe tools\cursor\migrate_ai_environment.py --check
+.venv\Scripts\python.exe scripts\audit\prescan.py --files "tools/cursor/migrate_ai_environment.py,docs/cursor_migration.md"
+```
+
+## 回滚
+
+迁移脚本会把覆盖前的 Cursor 用户资产和项目 `.cursor` 资产备份到：
+
+`C:\Users\Administrator\.cursor\backups\neozqyy-cursor-migration\<timestamp>`
+
+如需回滚，按 manifest 中的源/目标路径恢复即可。