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