Two files, one repository
alibaba/opc-starter ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 10 | 1 | 8% |
| Commands | 2 | 10 | 1 | 15% |
| Section tags | 3 | 6 | 1 | 30% |
What each file covers
Sections
1 shared · 10 only in A · 1 only in B- − OPC-Starter AI Coding 指南
- − BMAD Method（v6.10 Native Skills）
- − Checks
- − PR 必过（根目录或 app/ 均可）
- − 一键全量（format + coverage + build + E2E）
- − Cursor Cloud specific instructions
- − Project layout
- − Running without Supabase (MSW mock mode)
- − Gotchas
- − Key commands
- + OPC-Starter Copilot 指令
- 质量门禁
Commands
2 shared · 10 only in A · 1 only in B- − npx bmad-method@latest install --yes --action update --directory . \
- − npm run lint:check && npm run type-check && npm run test && npm run build
- − npm run test:e2e:headless
- − npm test
- − npm run dev:test
- − npm install
- − npm install --registry https://registry.npmjs.org/
- − npm run lint
- − npm run dev
- − npm run build
- + npm run test
- npm run ai:check
- npm run type-check
Section tags
3 shared · 6 only in A · 1 only in B- − setup
- − build
- − code-style
- − architecture
- − testing-strategy
- − git-pr
- + docs
- test
- lint-format
- agent-behaviour
Line diff
alibaba/opc-starter · AGENTS.md
@@ −1 @@
1# OPC-Starter AI Coding 指南
2
3> 一人公司启动器 AI 开发规范 | v2.0（目录式）
4
5## 核心原则
6
71. **优先更新现有文档**，不创建新文档
82. **SQL 变更集中管理** → `app/supabase/setup.sql`
93. **操作文档更新** → `app/supabase/SUPABASE_COOKBOOK.md`
10
11## 技术栈
12
13React 19.1 · TypeScript 5.9 · Vite 7.1 · **Tailwind CSS 4.1** · Supabase 2.80 · Zustand 5.0 · Qwen-Plus (百炼) · A2UI v0.8 · react-i18next
14
15## 详细规范（按需加载）
16
17| 规范 | 文件 | 自动触发 |
18| -------------------- | ------------------------------------ | ---------------------------------------------- |
19| TypeScript 严格类型 | `.cursor/rules/typescript-strict.md` | `*.ts, *.tsx` |
20| Tailwind CSS v4 语法 | `.cursor/rules/tailwind-v4.md` | `*.tsx, *.css` |
21| Agent Studio 开发 | `.cursor/rules/agent-studio.md` | `agent/**/*` |
22| Supabase 数据模式 | `.cursor/rules/supabase-patterns.md` | `services/**/*` |
23| 测试规范 | `.cursor/rules/testing.md` | `*.test.*` |
24| 项目扩展指南 | `.cursor/rules/project-extension.md` | `pages/**/*` |
25| i18n 国际化 | `.cursor/rules/i18n.md` | `locales/**/*`、用户可见文案、`useTranslation` |
26
27## 技术文档（按需自动引入）
28
29开发过程中涉及以下场景时，**必须**先读取对应文档再动手：
30
31| 文档 | 用途 | 自动触发（涉及场景关键词） |
32| ----------------------------------- | -------------------------------- | ----------------------------------------------------- |
33| `docs/API.md` | AI Assistant API 接口 | `ai-assistant`、SSE、Agent 工具、`renderUI`、LLM 调用 |
34| `docs/Architecture.md` | 系统架构与模块关系 | 新模块设计、分层架构、核心模块职责、扩展指南 |
35| `docs/CONVENTIONS.md` | 编码规范（命名、分层、错误处理） | 文件命名、分层依赖、TypeScript 规范、权限约定 |
36| `docs/DESIGN_TOKENS.md` | 设计令牌规范 | 颜色系统、字体、圆角、阴影、Tailwind Token、UI 风格 |
37| `docs/Epics.yaml` | 项目进度 | 项目进度、Story 拆解、版本规划、Epic 状态 |
38| `docs/IHS.md` | 仓库驾驭健康报告 | 代码质量评估、技术债、测试覆盖率、代码腐化度 |
39| `docs/exec-plans/` | 历史执行计划 | 在途计划收尾、历史方案参考 |
40| `_bmad-output/` | BMAD 工作流产物 | PRD、Epic/Story、Sprint 状态、Quick Dev spec |
41| `_bmad-output/README.md` | BMAD 产物索引与命名约定 | 产物路径、与 `docs/` 的分工 |
42| `app/supabase/SUPABASE_COOKBOOK.md` | 数据库操作手册 | 表结构变更、RLS 策略、SQL 函数、数据库迁移 |
43| `app/supabase/setup.sql` | 数据库 Schema 事实源 | 建表、加字段、RLS、触发器、profiles 等表 |
44| `app/src/locales/` | 前端 i18n 文案事实源 | 多语言、locale、翻译、`useTranslation`、用户可见文案 |
45
46### 路由规则说明
47
481. **AI 助手开发**：涉及 `ai-assistant`、SSE 流、Agent Tool、`renderUI`、LLM 调用 → 先读 `docs/API.md`，工具注册还需参考 `docs/Architecture.md` 扩展指南。
492. **UI 组件开发**：新增或修改 UI 组件 → 先读 `docs/DESIGN_TOKENS.md` 确认设计语言，再按 `docs/CONVENTIONS.md` 命名和分层；涉及用户可见文案时读 `.cursor/rules/i18n.md`。
503. **页面/模块扩展**：新增页面、路由、业务模块 → 先读 `docs/Architecture.md`、`docs/CONVENTIONS.md` 和 `.cursor/rules/project-extension.md`。
514. **数据库变更**：任何 Schema、RLS、触发器、SQL 函数变更 → 先读 `app/supabase/setup.sql` 确认现状，操作步骤参考 `app/supabase/SUPABASE_COOKBOOK.md`。
525. **质量评估**：代码健康度、技术债分析 → 读 `docs/IHS.md` 获取基线数据。
536. **规划与执行**：优先更新既有 `docs/exec-plans/`、`docs/Epics.yaml` 或相关文档；确需新增文档时先确认是否已有合适承载位置。
547. **BMAD 工作流**：需求规划、Story 开发、代码审查 → 使用 `.agents/skills/bmad-*`（Cursor）或对应 IDE 的 skills 目录；不确定时先 invoke `bmad-help`。
558. **国际化（i18n）**：新增或修改用户可见文案 → 先读 `.cursor/rules/i18n.md`，在 `app/src/locales/zh-CN` 与 `en-US` 同步维护 key；初始化见 `app/src/lib/i18n.ts`。
569. **BMAD Builder（BMB）**：自建 Agent / Module / Workflow → invoke `bmad-agent-builder`、`bmad-module-builder` 或 `bmad-workflow-builder`；产物默认写入仓库根目录 `skills/`。
57
58## BMAD Method（v6.10 Native Skills）
59
60BMAD 已从旧版 YAML/XML 命令迁移为 **Native Skills** 架构（`SKILL.md` + TOML 配置）。
61
62| 模块 | 版本 | 用途 |
63| ---- | ------ | --------------------------------- |
64| core | 6.10.0 | 共享脚本、配置解析 |
65| bmm | 6.10.0 | 需求、Story、审查、Quick Dev |
66| bmb | v1.5.0 | Agent / Module / Workflow Builder |
67
68| 项 | 路径 |
69| -------------------------- | -------------------------- |
70| 主配置（安装器管理，只读） | `_bmad/config.toml` |
71| 团队定制覆盖 | `_bmad/custom/config.toml` |
72| BMB 模块配置 | `_bmad/bmb/config.yaml` |
73| Cursor / OpenCode Skills | `.agents/skills/bmad-*` |
74| Claude Code Skills | `.claude/skills/bmad-*` |
75| Antigravity Skills | `.agent/skills/bmad-*` |
76| Kiro Skills | `.kiro/skills/bmad-*` |
77| Qoder Skills | `.qoder/skills/bmad-*` |
78
79常用 Skills（BMM）：`bmad-help`、`bmad-quick-dev`、`bmad-dev-story`、`bmad-code-review`、`bmad-sprint-planning`
80
81常用 Skills（BMB）：`bmad-agent-builder`、`bmad-module-builder`、`bmad-workflow-builder`、`bmad-bmb-setup`
82
83产物目录（统一在 `_bmad-output/`，由 `_bmad/custom/config.toml` 锁定）：
84
85| 子目录 | 典型内容 |
86| --------------------------- | ------------------------------------- |
87| `planning-artifacts/` | PRD、architecture.md、epics.md |
88| `implementation-artifacts/` | sprint-status.yaml、Story 文件、Retro |
89| `specs/` | Quick Dev 独立 spec |
90| 根目录 | `project-context.md` 等 |
91
92升级命令（维护者）：
93
94```bash
95npx bmad-method@latest install --yes --action update --directory . \
96 --tools cursor,claude-code,opencode,antigravity,kiro,qoder --modules bmm,bmb \
97 --pin bmb=v1.5.0 \
98 --user-name opc-starter --communication-language Chinese \
99 --document-output-language Chinese --output-folder _bmad-output
100```
101
102> **注意**：`--modules` 必须同时包含 `bmm,bmb`。仅安装 `bmb` 会移除 BMM skills。外部模块 `bmb` 在无 `GITHUB_TOKEN` 时 `--all-stable` 可能因 GitHub API 限流失败，请使用 `--pin bmb=v1.5.0`。
103
104## 禁止事项
105
106- ❌ 使用 Tailwind CSS v2/v3 语法（`bg-opacity-*`、`bg-gradient-to-*`）
107- ❌ 直接操作 IndexedDB 或 Supabase（使用 DataService）
108- ❌ 在 A2UI 中使用未注册的组件类型
109- ❌ 直接调用 LLM API（通过 ai-assistant Edge Function）
110- ❌ 创建独立 SQL 文件或新文档文件
111
112## Checks
113
114在提交 Pull Request 之前，运行 `/check` 对 diff 执行 `.continue/checks/*.md` 中定义的 AI 审查。
115所有 Check 必须通过，或由维护者明确确认后，才能创建 PR。
116
117当前已配置的 Checks：
118
119- **分层架构守卫** — 检查依赖方向违规和 UI 层直接导入 Supabase/IndexedDB
120- **数据访问与 Agent 规范** — 检查是否绕过 Service/DataService 直接访问数据，以及 Agent/A2UI/LLM 调用是否遵守 starter 约定
121
122后续可优化候选：
123
124- **E2E 选择器迁移** — Cypress 逐步改用 `data-testid`，减少对文案/i18n 的耦合
125
126## 质量门禁
127
128AI Agent 在 commit / push / PR 前必须跑完。**Husky 仅 lint-staged，不跑单测/E2E/构建。**
129
130```bash
131# PR 必过（根目录或 app/ 均可）
132npm run lint:check && npm run type-check && npm run test && npm run build
133npm run test:e2e:headless # 改 UI / 文案 / i18n / 路由 / 认证时必跑
134
135# 一键全量（format + coverage + build + E2E）
136./scripts/quality_check.sh
137```
138
139- 用 `lint:check`，不要用 `lint`（PR Check 不带 `--fix`）
140- `npm test` 必须**全量**，禁止只 `--run` 单个文件
141- i18n 改动：同步 `*.test.*` / Cypress 断言，见 `.cursor/rules/i18n.md`
142- PR 前跑 `/check`（`.continue/checks/`）
143
144## Cursor Cloud specific instructions
145
146### Project layout
147
148All application code lives under `app/`.
149
150- Prefer `/workspace/app` for low-level application work.
151- `/workspace/package.json` exposes proxy scripts for AI tools that start at repo root, so `npm run dev:test`, `npm run ai:check`, and `npm run test:e2e:headless` also work from `/workspace`.
152
153### Running without Supabase (MSW mock mode)
154
155The app can run fully locally without a real Supabase project by using MSW mocks:
156
1571. Ensure `app/.env.test` exists with `VITE_ENABLE_MSW=true` (created automatically by the update script if missing).
1582. `npm run dev:test` — starts Vite on port **5173** with MSW intercepting all Supabase API calls.
1593. Test credentials are sourced from `app/cypress/fixtures/users.json`: `test@example.com` / `888888`.
160
161### Gotchas
162
163- The original `package-lock.json` referenced Alibaba's internal npm registry (`registry.anpm.alibaba-inc.com`), which is unreachable from Cloud VMs. If `npm install` fails with `ECONNRESET` errors from that registry, delete `package-lock.json` and `node_modules`, then run `npm install --registry https://registry.npmjs.org/`.
164- The `prepare` script runs `cd .. && husky app/.husky` which installs git hooks from the repo root. This is expected and runs automatically during `npm install`.
165- Lint command (`npm run lint`) applies `--fix` by default.
166
167### Key commands
168
169| Task | Command |
170| -------------------------- | ---------------------------- |
171| Dev server (mock) | `npm run dev:test` |
172| Dev server (real Supabase) | `npm run dev` |
173| Lint | `npm run lint` |
174| Type check | `npm run type-check` |
175| Unit tests | `npm test` |
176| E2E tests | `npm run test:e2e:headless` |
177| Core AI checks | `npm run ai:check` |
178| Full quality check | `./scripts/quality_check.sh` |
179| Build | `npm run build` |
180
alibaba/opc-starter · .github/copilot-instructions.md
@@ +1 @@
1# OPC-Starter Copilot 指令
2
3## 技术栈
4
5React 19.1 · TypeScript 5.9 (strict) · Vite 7.1 · Tailwind CSS 4.1 · Supabase 2.80 · Zustand 5.0
6
7## 关键规则
8
9- 使用 Tailwind CSS **v4** 语法，禁止 `bg-opacity-*`、`bg-gradient-to-*` 等 v2/v3 写法
10- 数据操作通过 `DataService`，禁止直接导入 `@/lib/supabase/client`
11- SQL 变更集中到 `app/supabase/setup.sql`
12- 新文件必须在顶部添加 JSDoc 文件头注释
13- `@typescript-eslint/no-explicit-any: error`，避免 `any` 类型逃逸
14
15## 代码路径别名
16
17`@/*` → `src/*`
18
19## 分层约束
20
21```
22pages → components → hooks → stores → services → lib
23```
24
25上层可导入下层，禁止逆向依赖。`pages/`、`components/`、`hooks/` 禁止直接导入 `@/lib/supabase/client`。
26
27## 质量门禁
28
29```bash
30npm run ai:check # lint + format + type-check + coverage + build
31npm run test # Vitest 单元测试
32npm run type-check # TypeScript 类型检查
33```
34
35## 文档参考
36
37- `docs/Architecture.md` — 系统架构
38- `docs/API.md` — AI Assistant API
39- `docs/CONVENTIONS.md` — 编码规范
40- `docs/DESIGN_TOKENS.md` — 设计令牌
41
@@ −1 +1 @@
1−# OPC-Starter AI Coding 指南
1+# OPC-Starter Copilot 指令
22
3−> 一人公司启动器 AI 开发规范 | v2.0（目录式）
4−
5−## 核心原则
6−
7−1. **优先更新现有文档**，不创建新文档
8−2. **SQL 变更集中管理** → `app/supabase/setup.sql`
9−3. **操作文档更新** → `app/supabase/SUPABASE_COOKBOOK.md`
10−
113 ## 技术栈
124
13−React 19.1 · TypeScript 5.9 · Vite 7.1 · **Tailwind CSS 4.1** · Supabase 2.80 · Zustand 5.0 · Qwen-Plus (百炼) · A2UI v0.8 · react-i18next
5+React 19.1 · TypeScript 5.9 (strict) · Vite 7.1 · Tailwind CSS 4.1 · Supabase 2.80 · Zustand 5.0
146
15−## 详细规范（按需加载）
7+## 关键规则
168
17−| 规范 | 文件 | 自动触发 |
18−| -------------------- | ------------------------------------ | ---------------------------------------------- |
19−| TypeScript 严格类型 | `.cursor/rules/typescript-strict.md` | `*.ts, *.tsx` |
20−| Tailwind CSS v4 语法 | `.cursor/rules/tailwind-v4.md` | `*.tsx, *.css` |
21−| Agent Studio 开发 | `.cursor/rules/agent-studio.md` | `agent/**/*` |
22−| Supabase 数据模式 | `.cursor/rules/supabase-patterns.md` | `services/**/*` |
23−| 测试规范 | `.cursor/rules/testing.md` | `*.test.*` |
24−| 项目扩展指南 | `.cursor/rules/project-extension.md` | `pages/**/*` |
25−| i18n 国际化 | `.cursor/rules/i18n.md` | `locales/**/*`、用户可见文案、`useTranslation` |
9+- 使用 Tailwind CSS **v4** 语法，禁止 `bg-opacity-*`、`bg-gradient-to-*` 等 v2/v3 写法
10+- 数据操作通过 `DataService`，禁止直接导入 `@/lib/supabase/client`
11+- SQL 变更集中到 `app/supabase/setup.sql`
12+- 新文件必须在顶部添加 JSDoc 文件头注释
13+- `@typescript-eslint/no-explicit-any: error`，避免 `any` 类型逃逸
2614
27−## 技术文档（按需自动引入）
15+## 代码路径别名
2816
29−开发过程中涉及以下场景时，**必须**先读取对应文档再动手：
17+`@/*` → `src/*`
3018
31−| 文档 | 用途 | 自动触发（涉及场景关键词） |
32−| ----------------------------------- | -------------------------------- | ----------------------------------------------------- |
33−| `docs/API.md` | AI Assistant API 接口 | `ai-assistant`、SSE、Agent 工具、`renderUI`、LLM 调用 |
34−| `docs/Architecture.md` | 系统架构与模块关系 | 新模块设计、分层架构、核心模块职责、扩展指南 |
35−| `docs/CONVENTIONS.md` | 编码规范（命名、分层、错误处理） | 文件命名、分层依赖、TypeScript 规范、权限约定 |
36−| `docs/DESIGN_TOKENS.md` | 设计令牌规范 | 颜色系统、字体、圆角、阴影、Tailwind Token、UI 风格 |
37−| `docs/Epics.yaml` | 项目进度 | 项目进度、Story 拆解、版本规划、Epic 状态 |
38−| `docs/IHS.md` | 仓库驾驭健康报告 | 代码质量评估、技术债、测试覆盖率、代码腐化度 |
39−| `docs/exec-plans/` | 历史执行计划 | 在途计划收尾、历史方案参考 |
40−| `_bmad-output/` | BMAD 工作流产物 | PRD、Epic/Story、Sprint 状态、Quick Dev spec |
41−| `_bmad-output/README.md` | BMAD 产物索引与命名约定 | 产物路径、与 `docs/` 的分工 |
42−| `app/supabase/SUPABASE_COOKBOOK.md` | 数据库操作手册 | 表结构变更、RLS 策略、SQL 函数、数据库迁移 |
43−| `app/supabase/setup.sql` | 数据库 Schema 事实源 | 建表、加字段、RLS、触发器、profiles 等表 |
44−| `app/src/locales/` | 前端 i18n 文案事实源 | 多语言、locale、翻译、`useTranslation`、用户可见文案 |
19+## 分层约束
4520
46−### 路由规则说明
47−
48−1. **AI 助手开发**：涉及 `ai-assistant`、SSE 流、Agent Tool、`renderUI`、LLM 调用 → 先读 `docs/API.md`，工具注册还需参考 `docs/Architecture.md` 扩展指南。
49−2. **UI 组件开发**：新增或修改 UI 组件 → 先读 `docs/DESIGN_TOKENS.md` 确认设计语言，再按 `docs/CONVENTIONS.md` 命名和分层；涉及用户可见文案时读 `.cursor/rules/i18n.md`。
50−3. **页面/模块扩展**：新增页面、路由、业务模块 → 先读 `docs/Architecture.md`、`docs/CONVENTIONS.md` 和 `.cursor/rules/project-extension.md`。
51−4. **数据库变更**：任何 Schema、RLS、触发器、SQL 函数变更 → 先读 `app/supabase/setup.sql` 确认现状，操作步骤参考 `app/supabase/SUPABASE_COOKBOOK.md`。
52−5. **质量评估**：代码健康度、技术债分析 → 读 `docs/IHS.md` 获取基线数据。
53−6. **规划与执行**：优先更新既有 `docs/exec-plans/`、`docs/Epics.yaml` 或相关文档；确需新增文档时先确认是否已有合适承载位置。
54−7. **BMAD 工作流**：需求规划、Story 开发、代码审查 → 使用 `.agents/skills/bmad-*`（Cursor）或对应 IDE 的 skills 目录；不确定时先 invoke `bmad-help`。
55−8. **国际化（i18n）**：新增或修改用户可见文案 → 先读 `.cursor/rules/i18n.md`，在 `app/src/locales/zh-CN` 与 `en-US` 同步维护 key；初始化见 `app/src/lib/i18n.ts`。
56−9. **BMAD Builder（BMB）**：自建 Agent / Module / Workflow → invoke `bmad-agent-builder`、`bmad-module-builder` 或 `bmad-workflow-builder`；产物默认写入仓库根目录 `skills/`。
57−
58−## BMAD Method（v6.10 Native Skills）
59−
60−BMAD 已从旧版 YAML/XML 命令迁移为 **Native Skills** 架构（`SKILL.md` + TOML 配置）。
61−
62−| 模块 | 版本 | 用途 |
63−| ---- | ------ | --------------------------------- |
64−| core | 6.10.0 | 共享脚本、配置解析 |
65−| bmm | 6.10.0 | 需求、Story、审查、Quick Dev |
66−| bmb | v1.5.0 | Agent / Module / Workflow Builder |
67−
68−| 项 | 路径 |
69−| -------------------------- | -------------------------- |
70−| 主配置（安装器管理，只读） | `_bmad/config.toml` |
71−| 团队定制覆盖 | `_bmad/custom/config.toml` |
72−| BMB 模块配置 | `_bmad/bmb/config.yaml` |
73−| Cursor / OpenCode Skills | `.agents/skills/bmad-*` |
74−| Claude Code Skills | `.claude/skills/bmad-*` |
75−| Antigravity Skills | `.agent/skills/bmad-*` |
76−| Kiro Skills | `.kiro/skills/bmad-*` |
77−| Qoder Skills | `.qoder/skills/bmad-*` |
78−
79−常用 Skills（BMM）：`bmad-help`、`bmad-quick-dev`、`bmad-dev-story`、`bmad-code-review`、`bmad-sprint-planning`
80−
81−常用 Skills（BMB）：`bmad-agent-builder`、`bmad-module-builder`、`bmad-workflow-builder`、`bmad-bmb-setup`
82−
83−产物目录（统一在 `_bmad-output/`，由 `_bmad/custom/config.toml` 锁定）：
84−
85−| 子目录 | 典型内容 |
86−| --------------------------- | ------------------------------------- |
87−| `planning-artifacts/` | PRD、architecture.md、epics.md |
88−| `implementation-artifacts/` | sprint-status.yaml、Story 文件、Retro |
89−| `specs/` | Quick Dev 独立 spec |
90−| 根目录 | `project-context.md` 等 |
91−
92−升级命令（维护者）：
93−
94−```bash
95−npx bmad-method@latest install --yes --action update --directory . \
96− --tools cursor,claude-code,opencode,antigravity,kiro,qoder --modules bmm,bmb \
97− --pin bmb=v1.5.0 \
98− --user-name opc-starter --communication-language Chinese \
99− --document-output-language Chinese --output-folder _bmad-output
10021 ```
22+pages → components → hooks → stores → services → lib
23+```
10124
102−> **注意**：`--modules` 必须同时包含 `bmm,bmb`。仅安装 `bmb` 会移除 BMM skills。外部模块 `bmb` 在无 `GITHUB_TOKEN` 时 `--all-stable` 可能因 GitHub API 限流失败，请使用 `--pin bmb=v1.5.0`。
25+上层可导入下层，禁止逆向依赖。`pages/`、`components/`、`hooks/` 禁止直接导入 `@/lib/supabase/client`。
10326
104−## 禁止事项
105−
106−- ❌ 使用 Tailwind CSS v2/v3 语法（`bg-opacity-*`、`bg-gradient-to-*`）
107−- ❌ 直接操作 IndexedDB 或 Supabase（使用 DataService）
108−- ❌ 在 A2UI 中使用未注册的组件类型
109−- ❌ 直接调用 LLM API（通过 ai-assistant Edge Function）
110−- ❌ 创建独立 SQL 文件或新文档文件
111−
112−## Checks
113−
114−在提交 Pull Request 之前，运行 `/check` 对 diff 执行 `.continue/checks/*.md` 中定义的 AI 审查。
115−所有 Check 必须通过，或由维护者明确确认后，才能创建 PR。
116−
117−当前已配置的 Checks：
118−
119−- **分层架构守卫** — 检查依赖方向违规和 UI 层直接导入 Supabase/IndexedDB
120−- **数据访问与 Agent 规范** — 检查是否绕过 Service/DataService 直接访问数据，以及 Agent/A2UI/LLM 调用是否遵守 starter 约定
121−
122−后续可优化候选：
123−
124−- **E2E 选择器迁移** — Cypress 逐步改用 `data-testid`，减少对文案/i18n 的耦合
125−
12627 ## 质量门禁
12728
128−AI Agent 在 commit / push / PR 前必须跑完。**Husky 仅 lint-staged，不跑单测/E2E/构建。**
129−
13029 ```bash
131−# PR 必过（根目录或 app/ 均可）
132−npm run lint:check && npm run type-check && npm run test && npm run build
133−npm run test:e2e:headless # 改 UI / 文案 / i18n / 路由 / 认证时必跑
134−
135−# 一键全量（format + coverage + build + E2E）
136−./scripts/quality_check.sh
30+npm run ai:check # lint + format + type-check + coverage + build
31+npm run test # Vitest 单元测试
32+npm run type-check # TypeScript 类型检查
13733 ```
13834
139−- 用 `lint:check`，不要用 `lint`（PR Check 不带 `--fix`）
140−- `npm test` 必须**全量**，禁止只 `--run` 单个文件
141−- i18n 改动：同步 `*.test.*` / Cypress 断言，见 `.cursor/rules/i18n.md`
142−- PR 前跑 `/check`（`.continue/checks/`）
35+## 文档参考
14336
144−## Cursor Cloud specific instructions
145−
146−### Project layout
147−
148−All application code lives under `app/`.
149−
150−- Prefer `/workspace/app` for low-level application work.
151−- `/workspace/package.json` exposes proxy scripts for AI tools that start at repo root, so `npm run dev:test`, `npm run ai:check`, and `npm run test:e2e:headless` also work from `/workspace`.
152−
153−### Running without Supabase (MSW mock mode)
154−
155−The app can run fully locally without a real Supabase project by using MSW mocks:
156−
157−1. Ensure `app/.env.test` exists with `VITE_ENABLE_MSW=true` (created automatically by the update script if missing).
158−2. `npm run dev:test` — starts Vite on port **5173** with MSW intercepting all Supabase API calls.
159−3. Test credentials are sourced from `app/cypress/fixtures/users.json`: `test@example.com` / `888888`.
160−
161−### Gotchas
162−
163−- The original `package-lock.json` referenced Alibaba's internal npm registry (`registry.anpm.alibaba-inc.com`), which is unreachable from Cloud VMs. If `npm install` fails with `ECONNRESET` errors from that registry, delete `package-lock.json` and `node_modules`, then run `npm install --registry https://registry.npmjs.org/`.
164−- The `prepare` script runs `cd .. && husky app/.husky` which installs git hooks from the repo root. This is expected and runs automatically during `npm install`.
165−- Lint command (`npm run lint`) applies `--fix` by default.
166−
167−### Key commands
168−
169−| Task | Command |
170−| -------------------------- | ---------------------------- |
171−| Dev server (mock) | `npm run dev:test` |
172−| Dev server (real Supabase) | `npm run dev` |
173−| Lint | `npm run lint` |
174−| Type check | `npm run type-check` |
175−| Unit tests | `npm test` |
176−| E2E tests | `npm run test:e2e:headless` |
177−| Core AI checks | `npm run ai:check` |
178−| Full quality check | `./scripts/quality_check.sh` |
179−| Build | `npm run build` |
37+- `docs/Architecture.md` — 系统架构
38+- `docs/API.md` — AI Assistant API
39+- `docs/CONVENTIONS.md` — 编码规范
40+- `docs/DESIGN_TOKENS.md` — 设计令牌
18041
