@modus-ai/modus 0.2.10 → 0.2.11

package/templates/skills/modus-init/strategies/frontend-init.md

@@ -0,0 +1,298 @@
+---
+title: Frontend Strategy — React / Vue / Next / Nuxt 项目扫描与 Skill 生成
+parent_skill: modus-init
+load_when: "Router SKILL.md 在 Step 0.5 检测到 primaryStack=frontend-react / frontend-vue / frontend-other 时加载"
+stack: frontend-react | frontend-vue | frontend-other
+---
+
+# Frontend Strategy（React / Vue / Next / Nuxt / Vite）
+
+> 当 Router 在 Step 0.5 检测到 `primaryStack` 以 `frontend-` 开头时加载本文档。
+> - **§3** React 子流程（`primaryStack=frontend-react`）
+> - **§4** Vue 子流程（`primaryStack=frontend-vue`）
+> - **§5** 其他/通用前端（`primaryStack=frontend-other`，包含 Svelte / Angular / 纯 JS 等）
+
+---
+
+## §1 适用范围
+
+| 信号（package.json deps） | 适用子流程 |
+|------|---------|
+| `react` / `next` / `@remix-run/react` / `vite + react` | §3 React |
+| `vue` / `@vue/cli` / `nuxt` / `nuxt3` | §4 Vue |
+| `svelte` / `@angular/core` / 纯 JS / 无明显框架 | §5 其他/通用 |
+
+---
+
+## §2 5 轮扫描信号映射（前端通用）
+
+> 与 Java 栈对应的 5 轮结构保持一致，仅替换信号词。
+
+| 轮次 | 名称 | Java 信号 | 前端信号 |
+|------|------|---------|-----------|
+| 1 | 模块发现 | Maven Module / Gradle 子项目 | `package.json` workspaces / `pnpm-workspace.yaml` / `turbo.json` / `lerna.json` |
+| 2 | 文件分类清单 | Controller/Service/Mapper/Entity | **9 类前端文件**（见下） |
+| 3 | 域语义分析 | Service 公开方法签名 | **路由 + Page + Hook/Composable** 的语义聚类 |
+| 4 | 跨域依赖 | `@DubboReference` / `@KafkaListener` | **跨包 import + 跨服务环境变量 + WebSocket/SSE 监听** |
+| 5 | 资源所有权 | XML Mapper + `@TableName` | **API endpoint 所有权图谱**（哪些前端模块调哪些 endpoint） |
+
+### 前端 9 类核心文件（轮 2 统计）
+
+| # | 类型 | 路径模式（React） | 路径模式（Vue） | 后缀 | 角色 |
+|---|------|-----------------|-----------------|------|------|
+| 1 | **路由配置** | `src/router/`、`src/routes/`、`app/`(Next 14)、`pages/`(Next 旧)、根 `<Routes>` | `src/router/index.ts` | `.ts/.tsx/.js` | 入口（≈ Controller 路径表） |
+| 2 | **Page / View** | `src/pages/`、`app/**/page.tsx`、`src/views/` | `src/views/`、`pages/`(Nuxt) | `.tsx/.vue` | 业务编排（≈ Controller） |
+| 3 | **Component** | `src/components/`、`src/ui/` | `src/components/` | `.tsx/.vue` | UI 组合 |
+| 4 | **Hook / Composable** | `src/hooks/`、`use*.ts` | `src/composables/`、`useXxx.ts` | `.ts` | 业务逻辑（≈ Service） |
+| 5 | **Store** | `src/store/`、`src/redux/`、`src/zustand/` | `src/stores/`(Pinia)、`src/vuex/` | `.ts` | 全局状态 |
+| 6 | **API / Service** | `src/api/`、`src/services/`、`src/lib/api/` | `src/api/`、`src/services/` | `.ts` | 后端调用（≈ Mapper） |
+| 7 | **Type / Schema** | `src/types/`、`src/models/`、`src/schemas/` | 同 | `.ts` | 数据模型（≈ Domain） |
+| 8 | **Constant / Enum** | `src/constants/`、`src/enums/` | 同 | `.ts` | 常量 |
+| 9 | **Util / Helper** | `src/utils/`、`src/helpers/`、`src/lib/` | 同 | `.ts` | 工具方法 |
+
+### scanRules 默认值（前端栈）
+
+```
+默认 include_extensions: [.ts, .tsx, .js, .jsx, .mjs, .cjs, .vue, .svelte, .astro]
+默认 exclude_patterns:
+  node_modules/**, dist/**, build/**, .next/**, .nuxt/**, .vite/**,
+  coverage/**, storybook-static/**, .turbo/**, .git/**,
+  **/*.test.{ts,tsx}, **/*.spec.{ts,tsx}, **/__tests__/**,
+  public/**, *.lock, *.lockb, *.log
+```
+
+---
+
+## §3 React 子流程（`primaryStack=frontend-react`）
+
+### 3.1 域语义分析（轮 3，三层递进）
+
+**层 A：路由前缀语义**（最强证据）
+扫描以下任一来源的路由定义：
+- `src/router/*.ts` 中的 `<Routes>` 路径
+- `app/[seg]/page.tsx`（Next 14 App Router）
+- `pages/[seg]/*.tsx`（Next 旧版 Pages Router）
+- `src/routes/**/route.tsx`（Remix）
+- `@tanstack/router` 的路径定义
+
+路由前缀 `/order/*`、`/user/*`、`/payment/*` → 直接对应业务域（置信度 High）
+
+**层 B：Page 文件名语义**
+- `pages/Order/List.tsx` + `pages/Order/Detail.tsx` + `pages/Order/Edit.tsx` → 同业务名词 ≥ 3 次 → 确认 `order` 域
+
+**层 C：Hook + API 双重证据**
+- 命名前缀：`useOrder.ts` / `orderApi.ts` / `orderStore.ts`
+- import 链路：`Page → Hook → API` 跨模块 import 的归属信号
+
+**特殊处理：**
+- `common/`、`shared/`、`ui/` → 通用层，不算业务域
+- `layouts/`、`guards/` → 框架层
+- `locales/`、`i18n/` → 国际化层
+
+### 3.2 跨域依赖扫描（轮 4）
+
+| 信号 | 含义 |
+|------|------|
+| `import @/order/* from @/payment/*` | 跨模块 import，order 依赖 payment |
+| `import.meta.env.VITE_API_USER_BASE` / `process.env.NEXT_PUBLIC_API_PAYMENT` | 调用独立微服务 |
+| `socket.on('order:created', ...)` / `eventBus.on(...)` | 跨域事件订阅 |
+| `'use server'` 标注的函数（Next 14） | Server Action ≈ 后端 Service 调用 |
+
+### 3.3 API endpoint 所有权图谱（轮 5）
+
+扫描所有 `src/api/*.ts` / `src/services/*.ts`，提取调用模式：
+
+```typescript
+fetch('/api/order/list')                 // → /api/order/* 归 order 域
+axios.post('/api/payment/refund', ...)   // → /api/payment/* 归 payment 域
+useSWR('/api/user/me', fetcher)          // → /api/user/* 归 user 域
+useQuery({ queryKey: ['orders'], queryFn: () => api.get('/api/order/...') })
+```
+
+**输出 endpoint 所有权矩阵：**
+
+```
+/api/order/*       → [order]
+/api/payment/*     → [payment]
+/api/user/*        → [user, payment]   ← ⚠️ 共享 endpoint
+```
+
+孤儿 endpoint（无任何前端模块调用）：报警，可能是死代码 / 后端先行。
+
+### 3.4 React 项目置信度评分矩阵
+
+| 评分维度 | 评分规则 |
+|---------|---------|
+| ① 路由前缀内聚度 | 高=2 / 中=1 / 低=0 |
+| ② API endpoint 独占率 | >70%=2 / >40%=1 / <40%=0 |
+| ③ Page 完备性 | 有 list+detail+edit=2 / 仅 list=1 / 无=0 |
+| ④ 类型独立性 | 仅本域 import=2 / 跨域共享=1 / 无 type=0 |
+| ⑤ 状态管理集中度 | 集中本域 store/hook=2 / 分散=1 / 无=0 |
+
+### 3.5 React 业务 Skill 17 节填充指南
+
+| 节 | React 栈填充重点 |
+|---|------------|
+| **2 核心实体** | TS `interface` / Zod `schema`，可选标记 `?` |
+| **3 业务规则** | `[guideline]` 加 表单校验规则 / 权限判断 / 状态转换条件 |
+| **4 关键文件索引** | 层次 = `路由 / Page / Hook / Store / API / Type` |
+| **5 API 契约** | 调用的后端 endpoint 列表 + Request/Response TS 类型 + 鉴权方式（JWT/Cookie/Bearer） |
+| **6 项目特有模式** | Hook 命名约定 / 状态管理选型（Redux/Zustand/Jotai/Recoil） / 表单库（react-hook-form + zod） / 错误边界 |
+| **7 代码示例** | Page + Hook + API 的协作骨架，体现自定义 Hook 抽象 |
+| **8 状态机** | XState 状态机 / 表单流程 / 页面流（idle→loading→success→error） |
+| **9 错误处理** | toast 时机 / fallback UI / `<ErrorBoundary>` / 表单字段错误展示 / 路由守卫拦截 |
+| **10 跨模块依赖** | upstream/downstream 模块 + 跨服务调用 |
+| **11 数据流向** | React Query / SWR 的请求-缓存-渲染链路 / WebSocket 订阅 / Server Actions |
+| **12 关键 API 调用模式** | debounce / throttle / 重试 / 缓存（QueryClient 配置） / 取消（AbortController） / 乐观更新 |
+| **13 开发陷阱** | Closure 陷阱 / 依赖数组 / SSR Hydration 不一致 / Memory Leak / 不必要 re-render / 异步 setState 时机 |
+| **14 性能优化** | 路由懒加载（React.lazy） / 虚拟列表 / `React.memo`/`useMemo`/`useCallback` / Suspense / Code Split / 预加载 |
+| **15 业务不变量** | 「金额展示永远 toFixed(2)」「未登录不展示订单」等 |
+
+### 3.6 React 栈 key_files 选取优先级
+
+最多 20 个：
+
+**优先级 1（必选）**
+- 路由配置文件（`src/router.ts` / `app/[domain]/page.tsx`）
+- 主 Page（list/detail/edit）
+- 核心 Hook（`use{Domain}*.ts`）
+- 核心 API（`{domain}Api.ts` / `{domain}Service.ts`）
+- 核心 Type（`{Domain}.ts` / `{domain}Schema.ts`）
+- Store slice（`{domain}Slice.ts` / `{domain}Store.ts`）
+
+**优先级 2（强烈建议）**
+- 权限/鉴权相关（`{domain}Permissions.ts`、路由守卫）
+- 常量枚举（`{Domain}Status.ts`）
+- 表单 schema（`{domain}FormSchema.ts`，zod/yup）
+
+**优先级 3（有则加入）**
+- WebSocket/SSE 监听（`{domain}Socket.ts`）
+- Service Worker / 离线缓存
+- E2E 测试入口（cypress / playwright）
+
+### 3.7 React 栈 frontmatter 特化
+
+```yaml
+stack: frontend-react
+format_version: v3-frontend-react
+external_deps:                          # 从 package.json deps + devDeps 提取，排除工具链
+  react: "^18.2"
+  "@tanstack/react-query": "^5.0"
+  zustand: "^4.4"
+  "react-hook-form": "^7.45"
+  zod: "^3.22"
+key_files: [...]
+```
+
+---
+
+## §4 Vue 子流程（`primaryStack=frontend-vue`）
+
+### 4.1 与 React 的差异点
+
+| 维度 | React | Vue |
+|------|-------|-----|
+| 业务逻辑封装 | Custom Hook（`useXxx.ts`） | Composable（`useXxx.ts`，内部用 ref/computed/watch） |
+| 状态管理 | Redux/Zustand/Jotai | Pinia/Vuex |
+| 路由 | react-router | vue-router（`createRouter`） |
+| Meta 框架 | Next/Remix | Nuxt（`pages/`、`server/`） |
+| 模板 | JSX/TSX | SFC（`.vue` 单文件，`<template>/<script setup>/<style>`） |
+| 表单库 | react-hook-form + zod | VeeValidate + zod / FormKit |
+| 数据获取 | React Query / SWR | `@tanstack/vue-query` / `useFetch`(Nuxt) |
+
+### 4.2 Vue 特有扫描信号
+
+**SFC 解析（轮 3 增强）：**
+```vue
+<script setup lang="ts">
+  // → ref/reactive/computed/watch 使用模式
+  // → defineProps/defineEmits/defineExpose 组件契约
+</script>
+<template>
+  <!-- → <RouterLink :to="..."> 路由跳转 -->
+  <!-- → 子组件 import 依赖 -->
+</template>
+<style scoped>
+  /* → 样式隔离 */
+</style>
+```
+
+**实施提示：** MVP 阶段使用正则提取 `<script>` 块，复杂场景调用 `@vue/compiler-sfc`。
+
+**Vue 3 特有 API：**
+- `provide` / `inject` → 跨层级依赖（≈ React Context）
+- `defineModel`（Vue 3.4+） → 双向绑定契约
+- Pinia: `defineStore('xxx', ...)` 或 `useXxxStore` 函数式
+
+### 4.3 Vue 栈 17 节填充指南差异（与 React 共享 §3.5 大部分）
+
+仅列出与 React 不同的节：
+
+| 节 | Vue 栈填充重点 |
+|---|------------|
+| **6 项目特有模式** | Composable 命名（`useXxx`） / 组件通信（props/emit/v-model/provide-inject/Pinia） / 路由守卫（`beforeEach`/`beforeEnter`） / Suspense + AsyncComponent |
+| **12 API 调用模式** | axios interceptor 全局拦截 / Pinia store action 调 API / `vue-query` 的 `useQuery`/`useMutation` / Nuxt 的 `$fetch`/`useFetch` SSR 一致性 |
+| **13 开发陷阱** | ref vs reactive 解构丢响应式 / watch immediate vs watchEffect / v-for + v-if 同元素冲突 / 深层 watch 性能 / Nuxt useState 服务端复用 / `unref`/`toValue` 与 `.value` 不一致 |
+
+### 4.4 Vue 栈 frontmatter 特化
+
+```yaml
+stack: frontend-vue
+format_version: v3-frontend-vue
+external_deps:
+  vue: "^3.4"
+  pinia: "^2.1"
+  "vue-router": "^4.2"
+  "@tanstack/vue-query": "^5.0"
+  "@vee-validate/zod": "^4.12"
+```
+
+---
+
+## §5 其他/通用前端（`primaryStack=frontend-other`）
+
+适用：Svelte / Angular / 纯 JS / 未识别框架。
+
+### 退化策略
+
+- 跳过 §3.1 / §4.1 的精细域语义分析，改用**目录前缀分组**
+- 17 节生成时简化为以下 8 节，跳过状态机/扩展点/数据流向：
+  1 域概述 / 2 核心实体 / 3 业务规则 / 4 文件索引 / 5 API 契约 / 9 错误处理 / 13 陷阱 / 17 新人手册
+- 业务 Skill 标记 `format_version: v3-frontend-other`
+- 在 Step 14 完成回报中提示用户：`⚠️ 当前栈未深度适配，业务 Skill 简化为 8 节。如需完整 17 节支持，请运行 /modus:platform -add 提需求或手动升级 strategy。`
+
+---
+
+## §6 前端栈完成回报片段（Router 在 Step 14 拼接）
+
+```
+✅ 前端栈业务知识库已生成（基于 frontend-{react|vue|other} strategy）
+
+域置信度报告：
+┌─────────────────┬──────┬──────┬──────┬──────┬──────┬──────────┐
+│ 域名            │置信度│规则数│状态机│API完备│不变量│隐性知识率│
+├─────────────────┼──────┼──────┼──────┼──────┼──────┼──────────┤
+│ biz-order       │ 8/10 │  6条 │ 100% │ 100% │  4条 │   70%    │
+│ biz-checkout    │ 7/10 │  5条 │ 100% │  90% │  3条 │   60%    │
+└─────────────────┴──────┴──────┴──────┴──────┴──────┴──────────┘
+
+API endpoint 所有权图谱：
+  /api/order/*    → [biz-order]
+  /api/payment/*  → [biz-checkout]   ← ⚠️ 共享：biz-order 也调用，建议人工确认主域
+
+外部依赖快照（来自 package.json）：
+  react: ^18.2 | @tanstack/react-query: ^5.0 | zustand: ^4.4 | zod: ^3.22
+```
+
+---
+
+## §7 风险与权衡（实施提示）
+
+| 风险 | 应对 |
+|------|------|
+| `.vue` SFC 解析复杂 | MVP 用正则；复杂场景上 `@vue/compiler-sfc` |
+| Next 14 Server Component 与 Client Component 混合 | 单独标注 `'use server'` 文件为"server-action 域"，与 client 域区分；体现在 Section 11 |
+| Monorepo 跨 package 依赖爆炸 | 每个 package 单独 init，workspace-catalog 顶层路由 |
+| Pinia store 命名千差万别 | 至少识别两种范式：`useXxxStore` 函数 vs `defineStore('xxx', ...)` |
+| 团队不用 TypeScript（纯 JS） | 显式提示降级，按 `frontend-other` 走简化 8 节 |
+| Hooks 与 Composables 命名重叠 | 用文件路径区分：`hooks/` ≈ React，`composables/` ≈ Vue |

package/templates/skills/modus-init/strategies/java-init.md

@@ -0,0 +1,278 @@
+---
+title: Java Strategy — Spring Boot / MyBatis 后端项目扫描与 Skill 生成
+parent_skill: modus-init
+load_when: "Router SKILL.md 在 Step 0.5 检测到 primaryStack=java 后，在 Step 5 与 Step 8 加载本文档执行"
+stack: java
+---
+
+# Java Strategy（Spring Boot / MyBatis 后端项目）
+
+> 当 Router 在 Step 0.5 检测到 `primaryStack=java` 时加载本文档。本 Strategy 负责：
+> - **Step 5**：5 轮 Java 项目结构化扫描
+> - **Step 8**：生成符合 Java 语义的业务 Skill（基于 `shared/universal-skill-format.md` 17 节骨架）
+>
+> **不负责**：参数解析、平台同步、catalog 生成、回报——这些都在 Router 中（栈无关）。
+
+---
+
+## 适用范围
+
+| 信号 | 是否适用 |
+|------|---------|
+| `pom.xml` / `build.gradle` / `build.gradle.kts` | ✅ |
+| Spring Boot / Spring Cloud / Dubbo / Spring MVC | ✅ |
+| MyBatis / MyBatis-Plus / JPA | ✅ |
+| Gradle 多模块项目 | ✅ |
+| 纯 Kotlin 项目（基于 Spring） | ✅（信号词等价） |
+
+---
+
+## Step 5（Java 版）：5 轮全量扫描
+
+### 扫描前置：读取 scanRules
+
+读取 `modus/config.yaml.scanRules`，与 Java 默认值合并：
+
+```
+默认 include_extensions: [.java, .kt]
+默认 exclude_patterns:
+  target/**, build/**, .gradle/**, .idea/**, .vscode/**,
+  generated/**, **/*Generated.java, .git/**, .github/**,
+  **/*Test.java, **/*Tests.java, **/*IT.java
+```
+
+### 轮次 1：模块发现
+
+**信号：** `pom.xml`（Maven）或 `settings.gradle` / `settings.gradle.kts`（Gradle）
+
+输出：模块列表（含模块名、路径、构建文件路径）
+
+```
+[1/5 模块发现] ✓ 发现 {N} 个 Maven Module — order-core, order-api, order-job
+```
+
+### 轮次 2：包级清单（Java 类型分布统计）
+
+对每个模块，逐包统计文件数 + 以下 **10 类 Java 类型** 分布：
+
+| 类型 | 信号词 |
+|------|--------|
+| `Controller` | `@Controller` / `@RestController` 类 |
+| `Facade` | 类名后缀 `*Facade` |
+| `Service` | `@Service` / 类名后缀 `*Service` |
+| `Manager` | 类名后缀 `*Manager` |
+| `Mapper / DAO` | `@Mapper` / 类名后缀 `*Mapper` / `*Dao` |
+| `Domain / Entity` | `@TableName` / 类位于 `domain/`、`entity/` 包下 |
+| `Enum / Constant` | `enum` 关键字 / 含静态 final 常量集合 |
+| `DTO / VO / Request / Response` | 类名含 `*DTO` / `*VO` / `*Request` / `*Response` |
+| `Exception / ErrorCode` | 类名含 `*Exception` / 枚举类名含 `ErrorCode` |
+| `MQ Consumer / Producer` | `@KafkaListener` / `@RocketMQMessageListener` / `kafkaTemplate` / `rocketMQTemplate` |
+| `XML Mapper` | `resources/**/mapper/*.xml` |
+| `@Configuration` | `@Configuration` / `@Component` 注解的配置类 |
+
+输出格式（按文件数排序，全量展示不截断）：
+
+```
+包级清单（共 {N} 个包）：
+  order（43个文件）   Controller✓ Facade✓  主要概念: 订单创建/支付/状态流转
+  payment（31个文件） Controller✓          主要概念: 支付发起/回调/退款
+  ...
+```
+
+### 轮次 3：域语义分析（方法签名级，三层递进）
+
+**层 A：包名语义词匹配**（快速初判）
+- 包名 `order/pay/user/payment/inventory` 等业务名词 → 直接归入对应域（置信度 High）
+
+**层 B：公开方法签名分析**（语义细化）
+- 对 Service/Manager/Facade 提取所有 `public` 方法：
+  - 方法名（动词 + 名词，如 `confirmOrder` → 操作=confirm，对象=Order）
+  - 返回类型（`List`/`PageResult`/`void` → 推断查询/写/事件）
+  - 参数 DTO 名（`CreateOrderRequest` → 明确归入 order 域）
+- 同包内方法名含同一业务名词 ≥ 3 个 → 确认域归属
+
+**层 C：回退策略**
+- 类名含多语义域（`OrderPaymentService`） → 标"待人工确认"
+- 包仅 1-2 个文件 → 标"⚠️ 小包候选"
+
+输出（含代表性方法签名）：
+
+```
+域识别结果（共 {N} 个域）：
+  order（订单域）  [置信度 High]
+    核心方法：createOrder(CreateOrderReq) → OrderVO
+             cancelOrder(Long orderId) → void
+             queryOrderPage(OrderPageQuery) → PageResult<OrderVO>
+    → 关键文件：OrderService, OrderManager, OrderMapper
+```
+
+### 轮次 4：跨域依赖
+
+扫描以下信号绘制域间依赖图：
+
+| 信号 | 含义 |
+|------|------|
+| `@DubboReference` / `@FeignClient` | 跨域 RPC 依赖 |
+| `kafkaTemplate.send()` / `rocketMQTemplate.send()` | MQ 发布 |
+| `@KafkaListener` / `@RocketMQMessageListener` | MQ 订阅 |
+| 跨业务包的 `@Autowired` 注入 | Spring 跨域注入 |
+| `ApplicationEventPublisher.publishEvent()` + `@EventListener` | 事件驱动隐式依赖 |
+
+### 轮次 5：数据库表所有权图谱
+
+扫描以下两类信号构建全局表归属：
+
+| 信号 | 提取方法 |
+|------|--------|
+| `resources/**/mapper/*.xml` | 解析 `<select>/<insert>/<update>/<delete>` 中的 FROM/INTO/UPDATE 子句 |
+| `@TableName("xxx")` | MyBatis-Plus Entity 注解 |
+
+输出：
+
+```
+order_main        → [order]          ← 独占表
+payment_record    → [payment]        ← 独占表
+user_account      → [user, payment]  ← ⚠️ 共享表
+config_dict       → [order, user, payment] ← 公共配置表（排除统计）
+
+孤立表：{N} 张无域归属，需用户决策
+```
+
+---
+
+## 域置信度评分矩阵（Java 版，5 轮全部完成后执行）
+
+| 评分维度 | 评分规则 | 权重 |
+|---------|---------|------|
+| ① 包名语义内聚度 | 高=2 / 中=1 / 低=0 | 2 |
+| ② 数据库表独占率 | >70%=2 / >40%=1 / <40%=0 | 2 |
+| ③ 对外入口完备性 | 有 Controller/Facade=2 / 仅内部=1 / 无入口=0 | 2 |
+| ④ 核心实体独立性 | 仅本域路径=2 / 跨域共享=1 / 无 Entity=0 | 2 |
+| ⑤ 事务边界清晰度 | 集中本域 Service=2 / 跨域=1 / 无=0 | 2 |
+
+**分级处理：**
+- ≥ 7 分 → ✅ 自动确认
+- 4-6 分 → ⚠️ 用户确认
+- < 4 分 → ❌ 强制暂停决策
+
+---
+
+## Step 8（Java 版）：生成业务 Skill
+
+### 文件分批扫描（无文件数量上限）
+
+每个 SubAgent 按 git 最近修改时间排序，分三批扫描该域**全量文件**：
+
+**第一批（核心知识，必扫）**
+- ① Controller / Facade → API 契约、权限注解（`@PreAuthorize`、`@UserAuthorization`）
+- ② Service / Manager → 业务规则、`@Transactional` 边界
+- ③ Domain / Entity → 核心字段、业务方法
+- ⑥ Enum / Constant → 完整枚举值和业务含义
+
+**第二批（细节知识，全量扫）**
+- ④ Mapper / DAO → 数据操作模式
+- ⑤ XML Mapper → 关键 SQL（JOIN / 子查询 / 复杂条件）
+- ⑦ DTO / VO / Request / Response → 字段约束、JSR-303 校验
+
+**第三批（扩展知识）**
+- ⑧ Exception / ErrorCode → 错误码体系
+- ⑨ MQ Consumer / Producer → 消息契约、幂等保障
+- ⑩ `@Configuration` → 开关配置、扩展点
+
+### Java 业务 Skill 17 节填充指南
+
+> 节骨架严格遵循 `shared/universal-skill-format.md`。本节仅给出 Java 栈的"节内填充重点"。
+
+| 节 | Java 栈填充重点 |
+|---|---------|
+| **2 核心实体** | Java 类型（`Long`/`String`/`BigDecimal`），关键字段含 `@TableField` / `@TableId` / 校验注解 |
+| **3 业务规则** | `[guideline]` 加 `AopContext.currentProxy()` / `@DistributedLock` / `BaseRpcResponse.build()` |
+| **4 关键文件索引** | 层次 = `Controller / Facade / Service / Manager / Mapper / Domain` |
+| **5 API 契约** | Controller/Facade 暴露的 REST/RPC，含权限注解、错误码、幂等标注 |
+| **6 项目特有模式** | `@Transactional` + 同类调用陷阱 / 分布式锁注解 / 统一响应包装 / `@SaTokenAuth`/`@UserAuthorization` |
+| **7 代码示例** | Java 类风格，体现校验→业务→Domain→Mapper→MQ 发布→响应包装的完整链 |
+| **8 状态机** | Domain Entity 的 `status` 字段，状态图含 `@Transactional` 标注 |
+| **9 错误码** | ErrorCode 枚举 + Exception 类 + HTTP 状态映射（`@RestControllerAdvice`） |
+| **10 跨域依赖** | `@DubboReference` / `@FeignClient` / MQ Topic |
+| **11 数据流向** | MQ Topic + Spring Event；含幂等保障（DB 唯一索引/业务唯一键） |
+| **12 关键 SQL 模式** | XML Mapper 的复杂 SQL，含 JOIN/索引命中/数据量级/慢查询风险 |
+| **13 开发陷阱** | 同类 `@Transactional` 失效 / 枚举存 `name()` / 并发未加分布式锁 / `Long.equals` 拆箱 NPE |
+| **14 扩展点** | 策略模式（`Map<String, Strategy>` 注入）/ `@ConditionalOnProperty` / SPI |
+| **15 业务不变量** | 来源：`if/else` 推断 + JSR-303 校验器 + 访谈问卷 |
+
+### Java 栈 key_files 选取优先级
+
+最多 20 个，按以下优先级选取：
+
+**优先级 1（必选）**
+- `src/.../service/{Domain}Service.java`
+- `src/.../manager/{Domain}Manager.java`
+- `src/.../dao/{Domain}Mapper.java` 或 `src/.../dao/{Domain}CustomMapper.java`
+- `src/.../domain/{Domain}.java`
+
+**优先级 2（强烈建议）**
+- `src/.../enums/{Domain}Status.java`
+- `src/.../enums/{Domain}Type.java`
+- `src/.../exception/{Domain}Exception.java`
+- `src/.../enums/{Domain}ErrorCode.java`
+
+**优先级 3（有则加入）**
+- `src/.../mq/{Domain}Consumer.java`
+- `src/.../mq/{Domain}Producer.java`
+- `src/.../config/{Domain}Config.java`
+- `src/.../controller/{Domain}Controller.java`
+- `src/.../facade/{Domain}Facade.java`
+
+> 满 20 个时从优先级 3 末尾截断。
+
+### Java 栈 frontmatter 必填项（在通用规范基础上的特化）
+
+```yaml
+stack: java
+format_version: v3-java
+external_deps:                  # 自动从 pom.xml 提取，排除 java.* / javax.* / springframework.*
+  spring-boot: "~2.7"
+  mybatis-plus: ">=3.5 <4.0"
+  dubbo: "~3.1"
+key_files:                      # 见上方优先级清单
+  - src/.../service/OrderService.java
+  - ...
+```
+
+> 其他防腐字段（`last_hash`、`file_hashes`、`usage_count` 等）见 `shared/frontmatter-spec.md`。
+
+---
+
+## Step 7（Java 版）：访谈问卷触发条件
+
+> Step 7 框架在 Router 中（栈无关）。本节仅列出 Java 栈特有的触发条件。
+
+| 触发条件 | 生成的问题模板 | 写入目标 |
+|---------|-------------|---------|
+| 状态机有孤立状态（无入/出转换） | "❓ 状态 `{STATUS}` 无明确出口转换，请问：什么情况结束？由谁操作？" | Section 8 |
+| `create/pay/submit` 接口无幂等保护 | "❓ 接口 `{METHOD} {PATH}` 未发现幂等机制，请问：是否有业务层防重？key 是什么？" | Section 5 |
+| 跨域 RPC 无超时/降级配置 | "❓ `{ServiceA}` 调用 `{ServiceB}` 未发现超时配置，请问：超时业务兜底逻辑？" | Section 10 |
+| `//TODO:` 超过 3 处 | "❓ 发现 {N} 处 TODO，是否是已知技术债务？" | Section 13 |
+| 共享数据库表（多域访问） | "❓ 表 `{table}` 被 {A} 和 {B} 访问，谁是主域？" | Section 10 |
+| 无 ErrorCode 的 RuntimeException | "❓ `{ExceptionClass}` 无对应错误码枚举，前端展示什么？HTTP 码？" | Section 9 |
+| 金额字段类型为 Double/Float | "❓ `{field}` 用 Double 存金额，是有意还是技术债？" | Section 15 |
+
+---
+
+## Java 栈完成回报片段（Router 在 Step 14 中拼接）
+
+```
+✅ Java 栈业务知识库已生成（基于 java strategy，Spring Boot + MyBatis）
+
+域置信度报告：
+┌─────────────────┬──────┬──────┬──────┬──────┬──────┬──────────┐
+│ 域名            │置信度│规则数│状态机│API完备│不变量│隐性知识率│
+├─────────────────┼──────┼──────┼──────┼──────┼──────┼──────────┤
+│ biz-order       │ 9/10 │  8条 │ 100% │ 100% │  3条 │   80%    │
+└─────────────────┴──────┴──────┴──────┴──────┴──────┴──────────┘
+
+外部依赖快照（来自 pom.xml）：
+  spring-boot: ~2.7
+  mybatis-plus: >=3.5 <4.0
+  dubbo: ~3.1
+```