@dtt_siye/atool 1.2.1 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/VERSION +1 -1
  2. package/hooks/session-start +9 -12
  3. package/lib/export-analysis.sh +100 -0
  4. package/lib/install-kiro.sh +11 -6
  5. package/lib/install-skills.sh +16 -0
  6. package/lib/knowledge-graph.sh +490 -83
  7. package/lib/pre-scan.sh +70 -5
  8. package/package.json +1 -1
  9. package/skills/doc-standards-enforcer/SKILL.md +200 -220
  10. package/skills/doc-standards-enforcer/examples/valid-document-example.md +5 -5
  11. package/skills/doc-standards-enforcer/references/101-standards-summary.md +17 -17
  12. package/skills/project-analyze/SKILL.md +157 -124
  13. package/skills/project-analyze/phases/{phase0-discovery.md → archive/phase0-discovery.md} +6 -2
  14. package/skills/project-analyze/phases/{phase1-inventory.md → archive/phase1-inventory.md} +10 -0
  15. package/skills/project-analyze/phases/{phase2-deep-analysis.md → archive/phase2-deep-analysis.md} +20 -0
  16. package/skills/project-analyze/phases/{phase3-knowledge-graph.md → archive/phase3-knowledge-graph.md} +31 -0
  17. package/skills/project-analyze/phases/{phase3a-multi-dimensional.md → archive/phase3a-multi-dimensional.md} +13 -0
  18. package/skills/project-analyze/phases/{phase5-synthesis.md → archive/phase5-synthesis.md} +20 -0
  19. package/skills/project-analyze/phases/phase1-setup.md +182 -0
  20. package/skills/project-analyze/phases/phase2-understand.md +114 -0
  21. package/skills/project-analyze/phases/phase2.5-refine.md +284 -0
  22. package/skills/project-analyze/phases/phase3-graph.md +77 -0
  23. package/skills/project-analyze/phases/phase4-synthesize.md +241 -0
  24. package/skills/project-analyze/phases/phase5-export.md +207 -0
  25. package/skills/project-analyze/prompts/{deep-analysis-agent.md → archive/deep-analysis-agent.md} +14 -1
  26. package/skills/project-analyze/prompts/understand-agent.md +424 -0
  27. package/skills/project-analyze/rules/android.md +61 -260
  28. package/skills/project-analyze/rules/devops.md +61 -421
  29. package/skills/project-analyze/rules/generic.md +53 -221
  30. package/skills/project-analyze/rules/go.md +60 -275
  31. package/skills/project-analyze/rules/harmony.md +64 -237
  32. package/skills/project-analyze/rules/java.md +47 -485
  33. package/skills/project-analyze/rules/mobile-flutter.md +57 -292
  34. package/skills/project-analyze/rules/mobile-react-native.md +65 -262
  35. package/skills/project-analyze/rules/mobile-swift.md +58 -303
  36. package/skills/project-analyze/rules/python.md +50 -296
  37. package/skills/project-analyze/rules/rust-tauri.md +51 -217
  38. package/skills/project-analyze/rules/rust.md +50 -274
  39. package/skills/project-analyze/rules/web-nextjs.md +61 -335
  40. package/skills/project-analyze/rules/web-react.md +50 -272
  41. package/skills/project-analyze/rules/web-vue.md +58 -352
  42. package/skills/project-analyze/rules/web.md +55 -347
  43. package/skills/requirements-writer/README.md +1 -1
  44. package/skills/requirements-writer/SKILL.md +423 -282
  45. package/skills/requirements-writer/examples/prd-outline-example.md +5 -5
  46. package/skills/requirements-writer/templates/module-prd-template.md +15 -15
  47. package/skills/requirements-writer/templates/prd-outline-template.md +3 -3
  48. package/skills/requirements-writer/templates/user-story-template.md +23 -23
  49. package/skills/software-architecture/SKILL.md +318 -17
  50. package/templates/CLAUDE.md.android +17 -0
  51. package/templates/CLAUDE.md.devops +17 -0
  52. package/templates/CLAUDE.md.generic +17 -0
  53. package/templates/CLAUDE.md.go +17 -0
  54. package/templates/CLAUDE.md.harmony +17 -0
  55. package/templates/CLAUDE.md.java +17 -0
  56. package/templates/CLAUDE.md.mobile-flutter +17 -0
  57. package/templates/CLAUDE.md.mobile-react-native +17 -0
  58. package/templates/CLAUDE.md.mobile-swift +17 -0
  59. package/templates/CLAUDE.md.python +17 -0
  60. package/templates/CLAUDE.md.rust +17 -0
  61. package/templates/CLAUDE.md.rust-tauri +17 -0
  62. package/templates/CLAUDE.md.web +17 -0
  63. package/templates/cursor-rules.android.mdc +17 -0
  64. package/templates/cursor-rules.devops.mdc +17 -0
  65. package/templates/cursor-rules.generic.mdc +17 -0
  66. package/templates/cursor-rules.go.mdc +17 -0
  67. package/templates/cursor-rules.harmony.mdc +17 -0
  68. package/templates/cursor-rules.java.mdc +17 -0
  69. package/templates/cursor-rules.mobile-flutter.mdc +17 -0
  70. package/templates/cursor-rules.mobile-react-native.mdc +17 -0
  71. package/templates/cursor-rules.mobile-swift.mdc +17 -0
  72. package/templates/cursor-rules.python.mdc +17 -0
  73. package/templates/cursor-rules.rust-tauri.mdc +17 -0
  74. package/templates/cursor-rules.rust.mdc +17 -0
  75. package/templates/cursor-rules.web.mdc +17 -0
  76. package/templates/kiro-steering.android.md +6 -0
  77. package/templates/kiro-steering.devops.md +6 -0
  78. package/templates/kiro-steering.generic.md +6 -0
  79. package/templates/kiro-steering.go.md +6 -0
  80. package/templates/kiro-steering.harmony.md +6 -0
  81. package/templates/kiro-steering.java.md +6 -0
  82. package/templates/kiro-steering.mobile-flutter.md +6 -0
  83. package/templates/kiro-steering.mobile-react-native.md +6 -0
  84. package/templates/kiro-steering.mobile-swift.md +6 -0
  85. package/templates/kiro-steering.python.md +6 -0
  86. package/templates/kiro-steering.rust-tauri.md +6 -0
  87. package/templates/kiro-steering.rust.md +6 -0
  88. package/templates/kiro-steering.web.md +6 -0
  89. package/templates/shared/hard-rules.md +21 -0
  90. /package/skills/project-analyze/phases/{phase0.5-prescan.md → archive/phase0.5-prescan.md} +0 -0
  91. /package/skills/project-analyze/phases/{phase2a-l4-analysis.md → archive/phase2a-l4-analysis.md} +0 -0
  92. /package/skills/project-analyze/phases/{phase2b-l5-analysis.md → archive/phase2b-l5-analysis.md} +0 -0
  93. /package/skills/project-analyze/phases/{phase4-code-quality.md → archive/phase4-code-quality.md} +0 -0
  94. /package/skills/project-analyze/phases/{phase6-validation.md → archive/phase6-validation.md} +0 -0
  95. /package/skills/project-analyze/prompts/{code-review-agent.md → archive/code-review-agent.md} +0 -0
  96. /package/skills/project-analyze/prompts/{inventory-agent.md → archive/inventory-agent.md} +0 -0
  97. /package/skills/project-analyze/prompts/{l4-analysis-agent.md → archive/l4-analysis-agent.md} +0 -0
package/skills/project-analyze/rules/web-nextjs.md CHANGED
@@ -2,363 +2,89 @@
2
2
 
3
3
  Next.js 项目专属分析规则，与 `rules/web.md` 配合使用。本文件中的规则优先于 `web.md` 中的同名字段。适用于 Next.js 13+（App Router）和 Next.js 12-（Pages Router）。
4
4
 
5
- ## 分析粒度
5
+ > **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `web-conventions` skill 作为规范约束。
6
6
 
7
- Next.js 项目按 App Router / Pages Router 路由结构 + Server/Client 组件 + API Routes 分层分析：
7
+ ## 模块发现策略
8
8
 
9
- ```
10
- Next.js 应用结构
11
- ├── App Router（推荐，Next.js 13+）
12
- │ ├── app/layout.tsx（根布局）
13
- │ ├── app/page.tsx（首页）
14
- │ ├── app/[动态路由]/
15
- │ ├── app/api/（Route Handlers）
16
- │ ├── app/(路由组)/
17
- │ ├── Server Components（默认）
18
- │ └── Client Components（'use client'）
19
- ├── Pages Router（传统）
20
- │ ├── pages/_app.tsx（自定义 App）
21
- │ ├── pages/_document.tsx（自定义 Document）
22
- │ ├── pages/index.tsx（首页）
23
- │ ├── pages/api/（API Routes）
24
- │ └── pages/[动态路由]/
25
- ├── Middleware
26
- │ └── middleware.ts（请求拦截）
27
- ├── Server Actions
28
- │ └── 'use server' 函数
29
- └── 共享模块
30
- ├── components/（UI 组件）
31
- ├── lib/（工具函数）
32
- ├── hooks/（自定义 Hooks）
33
- ├── stores/（状态管理）
34
- ├── types/（TypeScript 类型）
35
- └── styles/（样式文件）
36
- ```
37
-
38
- ## 目录扫描策略
39
-
40
- ### 1. 识别 Next.js 路由模式
41
-
42
- **信号检测：**
43
-
44
- | 模式 | 信号文件 | 说明 |
45
- |------|----------|------|
46
- | App Router | `app/layout.tsx` 或 `app/layout.js` 存在 | Next.js 13+ App Router |
47
- | Pages Router | `pages/_app.tsx` 或 `pages/_app.js` 存在 | 传统 Pages Router |
48
- | 混合模式 | `app/` 和 `pages/` 同时存在 | 两种路由共存 |
49
-
50
- **扫描文件**: `app/**/layout.tsx`, `app/**/page.tsx`, `pages/**/*.tsx`, `next.config.*`
51
-
52
- ### 2. App Router 分析
53
-
54
- **扫描文件**: `app/**/*.tsx`, `app/**/*.ts`
55
-
56
- **提取内容**:
57
- - 路由结构（目录 → URL 映射）
58
- - 布局层级（嵌套 layout.tsx）
59
- - 路由组 `(...)` 和平行路由 `@folder`
60
- - 拦截路由 `(.)` 和 `(..)`
61
- - Server Components vs Client Components（`'use client'` 指令）
62
- - Loading UI（`loading.tsx`）
63
- - Error Boundary（`error.tsx`）
64
- - Not Found 页面（`not-found.tsx`）
65
- - 路由元数据（`generateMetadata`, `metadata` 导出）
66
- - Route Handlers（`app/api/**/route.ts`）
67
-
68
- **输出示例**:
69
- ```
70
- ### App Router 结构
71
- app/
72
- ├── layout.tsx → 根布局（html + body 标签，全局 Provider）
73
- ├── page.tsx → /（首页，Server Component）
74
- ├── loading.tsx → 全局加载 UI
75
- ├── error.tsx → 全局错误边界
76
- ├── (auth)/
77
- │ ├── layout.tsx → AuthLayout（居中布局，无侧边栏）
78
- │ ├── login/page.tsx → /login（Client Component，表单交互）
79
- │ └── register/page.tsx → /register
80
- ├── (dashboard)/
81
- │ ├── layout.tsx → DashboardLayout（侧边栏 + 顶栏）
82
- │ ├── dashboard/page.tsx → /dashboard（Server Component，数据预取）
83
- │ ├── settings/page.tsx → /settings
84
- │ └── settings/
85
- │ ├── loading.tsx → settings 加载骨架屏
86
- │ └── error.tsx → settings 错误边界
87
- ├── admin/
88
- │ ├── layout.tsx → AdminLayout
89
- │ ├── users/
90
- │ │ ├── page.tsx → /admin/users（列表页）
91
- │ │ ├── [id]/page.tsx → /admin/users/:id（详情页）
92
- │ │ └── new/page.tsx → /admin/users/new（创建页）
93
- │ └── @modal/
94
- │ ├── (.)users/[id]/page.tsx → 用户详情弹窗（平行路由）
95
- │ └── default.tsx → 弹窗关闭时的默认内容
96
- └── api/
97
- ├── auth/[...nextauth]/route.ts → /api/auth/*（NextAuth）
98
- └── users/route.ts → /api/users（CRUD Route Handler）
99
-
100
- ### 组件类型统计
101
- | 类型 | 数量 | 说明 |
102
- |------|------|------|
103
- | Server Component | 12 | 默认，支持 async/await |
104
- | Client Component | 5 | 标记 'use client' |
105
- | Route Handler | 3 | app/api/**/route.ts |
106
- ```
9
+ Next.js 项目按路由目录结构发现模块边界：
107
10
 
108
- ### 3. Pages Router 分析
11
+ - **App Router**: `app/` 下每个路由目录（含嵌套 layout.tsx 的目录）为一个页面模块；`app/api/` 下每个路由目录为一个 API 模块
12
+ - **Pages Router**: `pages/` 下每个文件/目录为一个路由模块；`pages/api/` 下每文件为一个 API 模块
13
+ - **组件层**: `src/components/{name}/` 下 3+ 文件的子目录
14
+ - **Hooks 层**: `src/hooks/` 下每个文件
109
15
 
110
- **扫描文件**: `pages/**/*.tsx`, `pages/**/*.ts`
16
+ 不视为独立模块：`layout.tsx`/`page.tsx` 归入父路由模块；`utils/`/`helpers/`/`lib/` 合并为一个模块；`.next/`/`public/`/`node_modules/` 跳过。
111
17
 
112
- **提取内容**:
113
- - 路由结构（文件 → URL 映射，含动态路由 `[param]` 和通配符 `[...slug]`）
114
- - `getStaticProps` / `getServerSideProps` / `getStaticPaths` 数据获取策略
115
- - 自定义 App 组件（`_app.tsx` 中的全局布局、Provider、页面级状态持久化）
116
- - 自定义 Document 组件（`_document.tsx` 中的 `<Html>`, `<Head>`, `<Main>`, `<NextScript>`）
117
- - API Routes（`pages/api/**/*.ts`，含请求方法处理）
118
- - 中间件（`middleware.ts`，请求匹配和重写规则）
18
+ ## 入口识别
119
19
 
120
- **输出示例**:
121
- ```
122
- ### Pages Router 结构
123
- pages/
124
- ├── _app.tsx → 全局 App（ThemeProvider + SessionProvider + Layout）
125
- ├── _document.tsx → 自定义 Document（Google Fonts 加载、PWA meta）
126
- ├── _error.tsx → 自定义错误页
127
- ├── index.tsx → /（SSG，getStaticProps）
128
- ├── login.tsx → /login（CSR，客户端表单）
129
- ├── dashboard/
130
- │ └── index.tsx → /dashboard（SSR + Auth guard，getServerSideProps）
131
- ├── users/
132
- │ ├── index.tsx → /users（SSG，getStaticPaths + getStaticProps）
133
- │ └── [id].tsx → /users/:id（ISR，revalidate: 60）
134
- └── api/
135
- ├── auth/[...nextauth].ts → NextAuth API
136
- ├── users/index.ts → GET /api/users, POST /api/users
137
- └── users/[id].ts → GET/PATCH/DELETE /api/users/:id
20
+ **路由模式识别：**
138
21
 
139
- ### 数据获取策略
140
- | 页面 | 策略 | 函数 | 说明 |
141
- |------|------|------|------|
142
- | / | SSG | getStaticProps | 首页静态生成，revalidate: 3600 |
143
- | /dashboard | SSR | getServerSideProps | 服务端渲染，需鉴权 |
144
- | /users | SSG | getStaticPaths + getStaticProps | 用户列表，fallback: 'blocking' |
145
- | /users/:id | ISR | getStaticPaths + getStaticProps | 用户详情，revalidate: 60 |
146
- | /login | CSR | - | 纯客户端渲染 |
147
- ```
22
+ | 模式 | 信号文件 |
23
+ |------|----------|
24
+ | App Router | `app/layout.tsx` 存在 |
25
+ | Pages Router | `pages/_app.tsx` 存在 |
26
+ | 混合模式 | `app/` 和 `pages/` 同时存在 |
148
27
 
149
- ### 4. Server Actions 分析
28
+ **关键入口文件：**
29
+ - `middleware.ts` — 请求拦截（matcher 配置，认证/国际化路由）
30
+ - `next.config.js/mjs` — 构建模式（output: standalone/export）、rewrites/redirects、i18n 配置
31
+ - `app/layout.tsx` 根布局 — 全局 Provider 树
150
32
 
151
- **扫描文件**: `app/**/*.tsx`, `app/**/*.ts`, `lib/**/*.ts`
33
+ ## 架构模式识别
152
34
 
153
- **提取内容**:
154
- - Server Action 函数（标记 `'use server'`）
155
- - 表单绑定（`action` 属性）
156
- - `useActionState` / `useFormState` 使用
157
- - `useOptimistic` 乐观更新
158
- - 输入验证（zod / yup schema）
159
- - 重定向逻辑（`redirect()`）
160
- - Cookie 操作（`cookies()`）
35
+ **App Router 组件类型检测：**
36
+ - Server Component（默认）：无 `'use client'` 指令，可直接 async/await
37
+ - Client Component：文件顶部 `'use client'` 指令
38
+ - Route Handler：`app/api/**/route.ts`，识别 GET/POST/PUT/DELETE 处理函数
39
+ - Server Action：`'use server'` 指令函数，识别表单绑定（`<form action={action}>`）
161
40
 
162
- **输出示例**:
163
- ```
164
- ### Server Actions
165
- #### createUser
166
- - **文件**: `app/admin/users/actions.ts`
167
- - **签名**:
168
- ```typescript
169
- 'use server'
170
- async function createUser(prevState: FormState, formData: FormData): Promise<FormState>
171
- ```
172
- - **输入验证**: zod schema (name: string, email: string, role: enum)
173
- - **返回值**: `{ success: true, user: User } | { success: false, errors: FieldErrors }`
174
- - **副作用**: 创建用户后 redirect('/admin/users')
175
- - **使用位置**: `app/admin/users/new/page.tsx` 中 `<form action={createUser}>`
176
- ```
41
+ **Pages Router 数据获取策略检测：**
42
+ - `getStaticProps` → SSG（含 revalidate → ISR）
43
+ - `getServerSideProps` → SSR
44
+ - `getStaticPaths` → 动态路由预生成（fallback 模式）
45
+ - 无数据获取函数 → CSR
177
46
 
178
- ### 5. Middleware 分析
47
+ ## 数据流模式
179
48
 
180
- **扫描文件**: `middleware.ts`, `middleware.js`
49
+ 与 `rules/web-react.md` 状态管理检测规则一致，额外关注 Next.js 特有的状态边界：
181
50
 
182
- **提取内容**:
183
- - 匹配路径（matcher 配置）
184
- - 请求拦截逻辑
185
- - 重定向规则
186
- - Header 操作
187
- - 认证/鉴权检查
188
- - 国际化路由处理
51
+ - `cookies()` / `headers()` — 服务端状态读取（仅 Server Component）
52
+ - `useRouter()` / `useSearchParams()` / `usePathname()` — 路由状态（仅 Client Component）
53
+ - `useFormStatus()` / `useActionState()` — Server Action 表单状态
54
+ - **缓存策略**: `fetch()` + `cache: 'force-cache'`/`'no-store'`、`unstable_cache`、`revalidateTag`/`revalidatePath`
189
55
 
190
- **输出示例**:
191
- ```
192
- ### Middleware
193
- - **文件**: `middleware.ts`
194
- - **匹配路径**: `/dashboard/:path*`, `/admin/:path*`, `/api/:path*`
195
- - **逻辑流程**:
196
- 1. 检查 session token (cookies.get('session'))
197
- 2. 未认证 → redirect('/login')
198
- 3. API 请求未认证 → return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
199
- 4. 检查角色权限（admin 路径需要 admin 角色）
200
- 5. 添加安全 headers（X-Frame-Options, CSP）
201
- ```
56
+ ## 分析关注点
202
57
 
203
- ### 6. Next.js 配置分析
58
+ - **版本检测**: Next.js 12-（Pages Router）vs 13+（App Router）vs 14+（Server Actions 稳定）
59
+ - **Server/Client 边界**: `'use client'` 边界位置，是否在合适层级（避免整棵树 Client 化）
60
+ - **数据获取模式**: App Router 中 fetch 缓存 vs Prisma/Drizzle 直查 vs SWR/React Query 客户端获取
61
+ - **Middleware 作用域**: matcher 配置的路径范围，认证检查 vs 国际化路由处理
62
+ - **构建输出模式**: output: 'standalone'（Docker）vs output: 'export'（静态文件），影响部署分析
204
63
 
205
- **扫描文件**: `next.config.js`, `next.config.mjs`, `next.config.ts`
64
+ ## 输出示例
206
65
 
207
- **提取内容**:
208
- - `output` 模式（standalone, export）
209
- - `images` 配置（remotePatterns, domains, deviceSizes）
210
- - `rewrites` / `redirects` / `headers` 规则
211
- - `env` 环境变量
212
- - `experimental` 实验性特性
213
- - `basePath` / `i18n` 配置
214
- - Webpack / Turbopack 自定义配置
215
- - `transpilePackages` 列表
216
- - 插件列表（`withXXX` 包装函数）
217
-
218
- **输出示例**:
219
- ```
220
- ### Next.js 配置
221
- - **文件**: `next.config.mjs`
222
- - **关键配置**:
223
- | 配置项 | 值 | 说明 |
224
- |--------|-----|------|
225
- | output | 'standalone' | Docker 部署模式 |
226
- | images.remotePatterns | [{ hostname: 'cdn.example.com' }] | 允许的外部图片域名 |
227
- | rewrites | [{ source: '/api/v1/:path*', destination: '/api/:path*' }] | API 版本重写 |
228
- | i18n.locales | ['zh', 'en'] | 支持语言 |
229
- | i18n.defaultLocale | 'zh' | 默认语言 |
230
- | experimental.serverActions | true | 启用 Server Actions |
231
66
  ```
232
-
233
- ### 7. 数据获取模式分析
234
-
235
- **App Router 模式**:
236
- - `fetch()` + `cache` / `no-store` 选项
237
- - `unstable_cache` / `revalidateTag` / `revalidatePath`
238
- - Database 直接查询（Prisma / Drizzle / Kysely）
239
- - 并行数据获取（Promise.all）
240
-
241
- **Pages Router 模式**:
242
- - `getStaticProps`（静态生成）
243
- - `getServerSideProps`（服务端渲染）
244
- - `getStaticPaths`（动态路由预生成）
245
- - `unstable_revalidate`（ISR 重新验证）
246
- - SWR / React Query（客户端数据获取）
247
-
248
- **输出示例**:
249
- ```
250
- ### 数据获取模式（App Router）
67
+ ### App Router 结构
68
+ app/
69
+ ├── layout.tsx → 根布局（ThemeProvider + SessionProvider）
70
+ ├── (auth)/
71
+ │ ├── layout.tsx → AuthLayout（居中布局，无侧边栏）
72
+ │ └── login/page.tsx → /login（Client Component，表单交互）
73
+ └── (dashboard)/
74
+ ├── layout.tsx → DashboardLayout（侧边栏+顶栏）
75
+ ├── dashboard/page.tsx → /dashboard（Server Component，数据预取）
76
+ └── admin/users/
77
+ ├── page.tsx → /admin/users（列表页，Server Component）
78
+ └── [id]/page.tsx → /admin/users/:id（详情页，ISR revalidate:60）
79
+
80
+ ### 数据获取模式
251
81
  | 页面 | 模式 | 缓存策略 | 数据源 |
252
82
  |------|------|----------|--------|
253
83
  | /dashboard | 并行 fetch | revalidate: 60 | 内部 API |
254
- | /users/:id | Prisma 直接查询 | cache('force-cache') | PostgreSQL |
84
+ | /admin/users/:id | Prisma 直接查询 | cache('force-cache') | PostgreSQL |
255
85
  | /api/users | Route Handler | no-store | PostgreSQL |
256
86
 
257
- ### 客户端数据获取
258
- | 库 | 使用位置 | Query Key | 说明 |
259
- |------|----------|-----------|------|
260
- | SWR | components/UserTable.tsx | ['/api/users', filters] | 用户列表 |
261
- | TanStack Query | components/Analytics.tsx | ['analytics', dateRange] | 统计数据 |
262
- ```
263
-
264
- ## 状态管理分析
265
-
266
- 与 `rules/web-react.md` 的状态管理分析规则一致，额外关注：
267
-
268
- - Next.js 特有的 Server/Client 状态边界
269
- - `cookies()` / `headers()` 服务端状态读取
270
- - `useRouter()` / `useSearchParams()` 路由状态
271
- - `useFormStatus()` / `useFormState()` 表单状态
272
-
273
- ## 样式分析
274
-
275
- ### CSS Modules
276
-
277
- **扫描文件**: `app/**/*.module.css`, `app/**/*.module.scss`, `components/**/*.module.css`
278
-
279
- **提取内容**: 与 `rules/web-react.md` 一致。
280
-
281
- ### Tailwind CSS
282
-
283
- **扫描文件**: `tailwind.config.*`, `postcss.config.*`
284
-
285
- **提取内容**: 与 `rules/web-react.md` 一致。
286
-
287
- ### CSS-in-JS
288
-
289
- **扫描文件**: `styled-components/`, `@emotion/`, `stitches` 相关文件
290
-
291
- **提取内容**:
292
- - 使用的库及版本
293
- - Theme Provider 配置
294
- - 全局样式定义
295
-
296
- ## 输出模板
297
-
298
- ### COMPONENT.md 章节结构（Next.js 特有）
299
-
300
- ```markdown
301
- # Next.js 组件文档
302
-
303
- ## 路由结构
304
- ### App Router（如适用）
305
- 路由目录树 + URL 映射 + 组件类型标注
306
-
307
- ### Pages Router（如适用）
308
- 路由文件列表 + 数据获取策略表
309
-
310
- ## Middleware
311
- 请求拦截逻辑 + 重定向规则 + 权限检查
312
-
313
- ## Server Actions
314
- 函数签名 + 输入验证 + 使用位置
315
-
316
- ## API Routes / Route Handlers
317
- 端点列表 + 请求/响应格式 + 认证要求
318
-
319
- ## Components
320
- ### Server Components
321
- ### Client Components
322
-
323
- ## 状态管理
324
- 全局状态 + 服务端状态 + 客户端缓存策略
325
-
326
- ## 数据获取
327
- 按页面列出数据获取模式 + 缓存策略
328
-
329
- ## Next.js 配置
330
- 关键配置项 + 自定义插件
87
+ ### Middleware
88
+ - 匹配路径: /dashboard/:path*, /admin/:path*
89
+ - 逻辑: 检查 session token → 未认证 → redirect('/login') → 检查角色权限
331
90
  ```
332
-
333
- ## 模块边界识别
334
-
335
- 以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
336
-
337
- | 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
338
- |----|----------|-------------|---------------------|
339
- | 页面/视图层 | `app/{route}/`, `pages/{route}/` | 每个路由目录 | 路由路径 kebab-case |
340
- | API/服务层 | `app/api/` | 每个路由目录 | 路由路径 kebab-case |
341
- | 状态管理层 | `src/store/`, `src/stores/` | 每个子目录 | 目录名 kebab-case |
342
- | 组件层 | `src/components/{name}/` | 3+ 文件的子目录 | 目录名 kebab-case |
343
- | Hooks 层 | `src/hooks/` | 每个文件 | 文件名去后缀 kebab-case |
344
-
345
- **特殊处理**：
346
- - Route Handler（`app/api/{route}/route.ts`）每文件一个模块
347
- - Layout 和 Page 文件归入对应路由模块，不单独成模块
348
-
349
- **不视为独立模块的情况**：
350
- - 单文件入口（如 `layout.tsx`, `page.tsx` 归入父模块）
351
- - 纯导出桶文件（`index.ts` 仅有 re-export）
352
- - 工具函数目录（`utils/`, `helpers/`, `lib/`）— 合并为一个模块
353
- - `.next/`, `public/`, `node_modules/` 跳过
354
-
355
- ## Token 管理
356
-
357
- - 每个子任务分析 <=10 个 `.tsx` / `.ts` 文件
358
- - `app/` 和 `pages/` 目录按路由分组，每个路由组为一个子任务
359
- - Server Actions 文件单独分组
360
- - API Routes / Route Handlers 单独分组
361
- - `next.config.*` 单独作为一个子任务
362
- - `middleware.ts` 单独分析
363
- - `node_modules/`、`.next/`、`out/` 跳过
364
- - `.generated.*` 或 `*.generated.ts` 文件可跳过或简要分析