Neo-ZQYY/docs/cursor_migration.md

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

验证

.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 中的源/目标路径恢复即可。