@dev-workflow/skill 0.1.0

package/skills/execution/devFlow/domains/frontend/references/contract-check.md

@@ -0,0 +1,270 @@
+# contract-check 子命令
+
+`contract-check` 用于在 `page-tech` 和 `page-build`
+之间做可落地性检查。它的目标不是生成代码，而是判断页面方案是否已经具备创建 admin-fe 页面基建的条件。
+
+执行 admin-fe 检查时，必须读取或内化项目根目录
+`ADMIN_FE_WORKFLOW.md`，并把其中规则作为检查标准。
+
+## 定位
+
+- 输入：`page-tech.md`、飞书文档读取结果、API 文档、Apifox
+  MCP 结果、用户补充约束和当前项目结构。
+- 输出：`contract-report.md`。
+- 结论：通过、不通过或阻塞。
+- 后续动作：通过后允许进入 `page-build`；不通过或阻塞时回到 `page-tech` 修正。
+
+## v1 形态
+
+第一版采用人工 checklist 模式。
+
+规则：
+
+- Agent 逐条核对并输出 Markdown 报告。
+- 每条结论必须引用真实证据。
+- 证据可以是文件路径、代码片段、文档章节、飞书读取内容、API 文档段落或 Apifox
+  MCP 返回结果。
+- 不承诺自动化脚本能力。
+- 不生成页面基建文件。
+- 不修改业务源码。
+
+机械规则可以用 `scripts/contract_check_static.mjs`
+辅助检查。该脚本只检查 route 目录命名、组件文件命名、service/types/constants 存在性和
+`src/routeTree.gen.ts` 是否被修改，不判断接口语义、状态语义或组件职责。
+
+## 输入要求
+
+### 必需输入
+
+- 页面方案或页面上下文：本地 `page-tech.md`、飞书文档读取结果或等价页面方案。
+- 当前项目结构：至少读取目标路由上级目录、相似 route、相关 service 目录和公共组件目录。
+- admin-fe 项目规则：读取 `ADMIN_FE_WORKFLOW.md`。
+
+### 条件输入
+
+- 页面依赖接口时，必须提供 API 文档或 Apifox MCP 读取结果。
+- 页面复用已有模块时，必须读取相关 route、component、service、types 或 constants。
+- 页面涉及 Wujie、shell、全局状态时，必须读取对应 `src/shared/wujie-bridge.ts`
+  或 `src/stores/shell-store.ts`。
+
+### 缺失处理
+
+- 必需输入缺失时，结论为阻塞。
+- 条件输入缺失且影响基建文件创建时，结论为阻塞。
+- 不影响基建创建的缺口可以列为非阻塞待确认项。
+
+## 检查项
+
+### 1. 路由路径
+
+检查目标：
+
+- 路由路径是否明确。
+- 是否位于 `src/routes`。
+- 路由目录是否使用 lowercase kebab-case。
+- 是否需要创建或修改 `src/routeTree.gen.ts`。
+
+通过标准：
+
+- route 路径可直接映射到 `src/routes/<feature>/<page>/route.tsx`。
+- 不需要手动编辑 `src/routeTree.gen.ts`。
+
+失败或阻塞：
+
+- 路由路径缺失。
+- 路由路径与现有页面冲突。
+- 方案要求手动修改 `src/routeTree.gen.ts`。
+
+### 2. 目录和文件命名
+
+检查目标：
+
+- route 目录是否符合 lowercase kebab-case。
+- React 组件文件是否符合 PascalCase。
+- 非组件文件是否符合 kebab-case。
+- service 是否按业务域放在 `src/services`。
+- UI 复用顺序是否符合 Apex UI -> `src/common` -> 业务局部组件 -> 新建局部组件。
+
+通过标准：
+
+- 文件计划可以按 admin-fe 规则直接创建。
+- 不需要跨无关模块改目录结构。
+
+失败或阻塞：
+
+- 文件命名含拼音、单字母或无意义缩写。
+- 页面局部组件被错误规划到公共目录。
+- service 模块位置与现有业务域冲突。
+
+### 3. API 契约
+
+检查目标：
+
+- 每个接口是否具备接口名。
+- 每个接口是否具备请求路径。
+- 每个接口是否具备请求 method。
+- 每个接口是否具备入参。
+- 每个接口是否具备响应。
+- 每个接口是否映射到调用组件。
+- 每个接口是否映射到触发交互。
+- 每个接口是否说明成功后的刷新范围和异常反馈。
+- API 是否统一走 `src/services/request.ts`，页面内是否避免重复封装请求基础逻辑。
+
+通过标准：
+
+- 能生成 service 函数签名。
+- 能在页面或组件中保留准确调用关系。
+- 缺失内容只限于非阻塞字段，且可用 `TODO(api)` 标记。
+
+失败或阻塞：
+
+- 列表、详情、保存、删除等核心接口缺少路径、入参或响应。
+- 接口来源无法验证。
+- Apifox 项目缺少可用 MCP 读取结果且用户要求基于 Apifox 落地。
+
+### 4. 页面状态
+
+检查目标：
+
+- 每个页面状态是否具备来源。
+- 每个页面状态是否具备变化条件。
+- 每个页面状态是否具备消费组件。
+- loading、空数据、失败、无权限、提交中等状态是否与页面能力匹配。
+- 页面临时状态是否避免使用 Zustand。
+- shell 状态是否使用 `src/stores/shell-store.ts`。
+
+通过标准：
+
+- 页面状态可以用组件 state、Context 或 useReducer 表达。
+- 不需要新增全局 Zustand store，除非方案和证据明确要求。
+
+失败或阻塞：
+
+- 状态来源不明。
+- 状态变化条件不明。
+- 方案要求创建全局状态但没有跨页面或持久化证据。
+
+### 5. 组件映射
+
+检查目标：
+
+- 每个组件是否能映射到页面功能。
+- 每个组件是否有明确输入、输出或事件。
+- 组件拆分是否符合 route 局部优先原则。
+- 组件是否错误承担 service、全局状态或 Wujie 职责。
+- 涉及 Wujie 时是否复用 `src/shared/wujie-bridge.ts`。
+
+通过标准：
+
+- 组件可以映射到 `page-build` 的 route、components、types 和 constants。
+- 页面局部组件靠近对应 route。
+
+失败或阻塞：
+
+- 组件只是设计稿图层复刻，无法映射页面功能。
+- 组件职责过大或过散，导致基建目录不可落地。
+- 缺少核心功能对应组件。
+
+### 6. 待确认项
+
+检查目标：
+
+- 待确认项是否影响 route、service、types、components 或 constants。
+- 待确认项是否影响 API 契约。
+- 待确认项是否影响页面状态模型。
+
+通过标准：
+
+- 无阻塞待确认项。
+- 非阻塞待确认项已经说明后续处理方式。
+
+失败或阻塞：
+
+- 待确认项会改变目录结构、核心接口或组件边界。
+- 待确认项数量过多，无法形成稳定 page-build 文件计划。
+
+## 证据规则
+
+每条检查必须写证据。
+
+证据格式：
+
+```text
+证据：<来源> <路径或章节> <关键片段或摘要>
+```
+
+示例：
+
+```text
+证据：仓库文件 src/routes/sales/client/route.tsx 使用 createFileRoute('/sales/client')
+证据：page-tech.md 3.1 功能与接口映射列出 client-list 的入参和响应
+证据：Apifox MCP client-list 接口返回 path=/admin/sales/client-list, method=POST
+```
+
+规则：
+
+- 不得用“按经验判断”“通常如此”作为证据。
+- 不得引用未读取的文件。
+- 不得根据接口名称推断字段。
+- 如果证据冲突，结论必须是不通过或阻塞。
+
+## 报告输出
+
+使用 `domains/frontend/templates/contract-report.md` 作为报告骨架。
+
+报告必须包含：
+
+- 总结论：通过、不通过或阻塞。
+- 输入材料。
+- 检查范围。
+- 逐项 checklist。
+- 阻塞项。
+- 非阻塞待确认项。
+- 是否允许进入 `page-build`。
+
+如果运行了静态脚本，报告必须包含脚本输出摘要，并明确哪些结论仍由人工 checklist 判断。
+
+## 结论规则
+
+### 通过
+
+满足以下条件才能通过：
+
+- route、目录命名、API 契约、页面状态、组件映射全部通过。
+- 不存在阻塞待确认项。
+- 每条结论都有真实证据。
+
+通过后输出：
+
+```text
+结论：通过，允许进入 page-build。
+```
+
+### 不通过
+
+存在明确错误但可以通过修改 `page-tech` 修复。
+
+不通过后输出：
+
+```text
+结论：不通过，需回到 page-tech 修正后重新 contract-check。
+```
+
+### 阻塞
+
+缺少必需输入或无法验证关键事实。
+
+阻塞后输出：
+
+```text
+结论：阻塞，需补充上下文后重新 contract-check。
+```
+
+## 禁止项
+
+- 不把自动化脚本结果当作完整 contract-check 结论。
+- 不创建页面基建文件。
+- 不修改业务源码。
+- 不跳过证据要求。
+- 不把 `TODO(api)` 当作核心接口缺失时的通过理由。
+- 不允许在检查不通过时进入 `page-build`。

package/skills/execution/devFlow/domains/frontend/references/foundation-freeze.md

@@ -0,0 +1,92 @@
+# foundation-freeze 子命令
+
+`foundation-freeze` 用于在 `page-build` 之后、`figmaSync plan`
+之前生成页面基建事实快照。它帮助 Human 和 Agent 明确当前代码事实，以及视觉阶段允许和禁止修改的范围。
+
+## 定位
+
+- 输入：目标页面目录、相关 service 文件、可选 `contract-report.md`。
+- 输出：`foundation-summary.md`。
+- 性质：机器生成快照，不是事实本身。
+- 最终事实：真实代码文件。
+
+## 生成规则
+
+默认使用脚本：
+
+```bash
+node .agent/skills/devFlow/domains/frontend/scripts/generate_foundation_summary.mjs --route-dir src/routes/<feature>/<page>
+```
+
+可选指定 service：
+
+```bash
+node .agent/skills/devFlow/domains/frontend/scripts/generate_foundation_summary.mjs \
+  --route-dir src/routes/<feature>/<page> \
+  --service src/services/<feature>/<page>.ts
+```
+
+规则：
+
+- `foundation-summary.md` 禁止人工编辑。
+- 每次 `figmaSync plan` 前必须重新生成或重新扫描。
+- 如果快照和上一次不一致，必须提示 Human 确认影响。
+- 快照只能汇总真实代码，不得补造组件、接口、状态或类型。
+- 快照不替代源码；与源码冲突时以源码为准。
+
+## 输出位置
+
+默认写入：
+
+```text
+src/routes/<feature>/<page>/foundation-summary.md
+```
+
+文件顶部必须包含：
+
+```html
+<!-- AUTO-GENERATED. Do not edit. Regenerate from source files. -->
+```
+
+## 内容要求
+
+必须包含：
+
+- route 文件。
+- components 文件。
+- service 文件。
+- types 文件。
+- constants 文件。
+- 组件 props。
+- service 函数签名。
+- types 导出。
+- constants 导出。
+- figmaSync 允许修改范围。
+- figmaSync 禁止修改范围。
+
+## figmaSync 允许修改范围
+
+- 目标页面或目标组件的布局。
+- CSS 文件和 className 绑定。
+- Apex UI 组件选型和 props。
+- 局部展示结构。
+- `PLAN.md` 和 `figma-plan.css`。
+
+## figmaSync 禁止修改范围
+
+- 路由路径。
+- service 契约。
+- API 请求基础封装。
+- 类型语义。
+- 页面核心状态模型。
+- 业务组件边界。
+- 权限逻辑。
+- Wujie bridge。
+- `src/routeTree.gen.ts`。
+
+## 失败处理
+
+- 目标 route 目录不存在：阻塞，先执行 `page-build` 或确认轻量 plan。
+- 无法识别 service：允许生成快照，但必须写入待确认。
+- 无法解析组件 props：允许生成文件清单，但必须标记解析盲区。
+- 发现上次快照变化：列出变化，让 Human 确认后再进入 `figmaSync plan`。

package/skills/execution/devFlow/domains/frontend/references/lightweight-flow.md

@@ -0,0 +1,55 @@
+# L0/L1 轻量流程
+
+轻量流程用于小范围、低风险需求，避免日常修复被强制拖入完整文档链路。
+
+## L0 快速协作
+
+适用：
+
+- 文案修正。
+- spacing、颜色变量替换。
+- 单字段展示。
+- 明显类型错误。
+- 单文件小修。
+
+规则：
+
+- 不生成 `page-tech.md`。
+- 不生成 `contract-report.md`。
+- 不生成 `foundation-summary.md`。
+- 不进入 figmaSync。
+- 读代码、复述最小计划、等待确认、修改、验证、总结。
+
+## L1 轻量流程
+
+适用：
+
+- 现有页面单组件改动。
+- 单接口接入。
+- 小弹窗。
+- 小筛选项。
+- 小范围 loading、空态、错误态。
+
+规则：
+
+- 通常不生成 `page-tech.md`。
+- 不生成 `contract-report.md`。
+- 不生成 `foundation-summary.md`。
+- Mini Plan 可以保留在对话中，不强制落 Markdown。
+- 如果过程中发现影响路由、多个接口、核心状态或公共组件，必须升档到 L2/L3。
+
+## Mini Plan 内容
+
+Mini Plan 必须包含：
+
+- 要改什么。
+- 涉及哪些文件。
+- 不改什么。
+- 验证方式。
+
+可使用模板：
+
+```text
+domains/frontend/templates/mini-plan-l0.md
+domains/frontend/templates/mini-plan-l1.md
+```

package/skills/execution/devFlow/domains/frontend/references/page-build.md

@@ -0,0 +1,268 @@
+# page-build 子命令
+
+`page-build`
+用于把已审核的页面方案或可验证上下文转换成 admin-fe 页面基建文件。它只负责创建可 review、可继续开发的占位骨架，不负责完成业务逻辑、最终视觉实现或复杂交互。
+
+## 定位
+
+- 输入：已审核的
+  `page-tech.md`、飞书文档链接、API 文档、Apifox 项目上下文、用户补充约束和当前仓库结构。
+- 输出：文件创建计划；Human 确认后，创建 route、页面局部 components、service、types、constants 和必要 index 导出。
+- 不输出：完整业务逻辑、最终样式、真实 mock 数据、未确认接口字段、全局状态重构。
+
+## 前置门槛
+
+进入 `page-build` 前必须校验 `contract-report.md`：
+
+- 如果存在 `contract-report.md`，先读取报告结论；报告不通过或存在阻塞项时，不进入 page-build，回到 `page-tech` 或 `contract-check` 处理后再来。
+- 如果没有 `contract-report.md`，提示先执行 `contract-check`，或让 Human 明确确认跳过检查再继续。
+- "继续"、"看起来可以"等含糊表达不算跳过确认，必须 Human 明确表达"跳过 contract-check"才能继续。
+
+## 输入来源
+
+### 本地 Markdown
+
+适用于用户提供已审核 `page-tech.md` 或其他页面方案文档。
+
+读取规则：
+
+1. 读取文档全文或与目标页面相关章节。
+2. 抽取页面名称、路由路径、页面范围、组件拆分、状态设计、接口清单、目录结构和待确认项。
+3. 如果文档没有明确“已审核”或用户没有确认，先询问是否允许进入 page-build。
+
+### 飞书文档链接
+
+适用于用户把 PRD、页面方案、接口说明或评审文档放在飞书中。
+
+读取规则：
+
+1. 先按 `lark-read` 子命令读取飞书文档。
+2. 将读取结果整理为 page-build 上下文。
+3. 不得根据链接标题、URL 或用户转述猜测内容。
+4. 如果读取失败，停止依赖该文档生成文件计划。
+
+### API 文档
+
+适用于用户直接提供接口文档、OpenAPI 片段、Markdown 表格或后端约定。
+
+抽取规则：
+
+- 接口名。
+- 请求路径。
+- 请求 method。
+- 入参类型。
+- 响应类型。
+- 触发组件或交互。
+- 成功后的刷新范围。
+- 错误处理要求。
+
+缺失任一关键信息时，不补造字段，在 service 模板中保留 `TODO(api)`。
+
+### Apifox 项目上下文
+
+适用于用户指定 Apifox 项目、目录、接口或接口分组。
+
+处理规则：
+
+1. 先发现当前运行环境是否提供 Apifox MCP 工具。
+2. 有可用工具时，通过 MCP 读取项目接口、目录、接口详情、请求参数和响应结构。
+3. 只使用 MCP 返回的真实接口事实，不根据接口名称推断字段。
+4. 如果没有 Apifox
+   MCP 工具、缺少项目权限、缺少项目 ID 或接口范围不明确，必须把问题列为阻塞待确认项。
+5. 不在 Skill 中承诺固定脚本或固定工具名；以当前可用 MCP 能力为准。
+
+## 工作流程
+
+1. 识别输入来源，读取必要上下文。
+2. 扫描当前仓库相关路径，确认现有 route、service、common、shared、stores 和相似页面写法。
+3. 抽取页面基建契约：
+   - route 路径。
+   - 页面目录。
+   - 页面局部组件。
+   - service 模块和函数签名。
+   - types 类型。
+   - constants 常量。
+   - 页面级状态来源和变化条件。
+4. 输出文件创建计划，逐个文件说明路径、用途、具体内容和 TODO。
+5. 等待 Human 明确确认后再创建或修改文件。
+6. 按最小完整范围落地模板，不扩大到无关页面或全局配置。
+7. 完成后说明已创建文件、未实现内容和下一步建议。
+
+## 创建前确认机制
+
+创建或修改任何文件前，必须向 Human 复述：
+
+- 输入来源和已确认事实。
+- 将创建或修改的完整文件清单。
+- 每个文件的具体职责和主要内容。
+- API 契约来源；如果来自 Apifox，说明 MCP 读取结果。
+- 待确认项是否阻塞 page-build。
+- 明确说明不会修改 `src/routeTree.gen.ts`。
+
+只有 Human 明确确认后才能执行文件改动。不能把“继续”“看起来可以”等含糊表达当成确认。
+
+## 文件布局规则
+
+推荐路径：
+
+```text
+src/routes/<feature>/<page>/route.tsx
+src/routes/<feature>/<page>/<component>/<Component>.tsx
+src/routes/<feature>/<page>/<page>-types.ts
+src/routes/<feature>/<page>/<page>-constants.ts
+src/routes/<feature>/<page>/index.ts
+src/services/<feature>/<page>.ts
+```
+
+当目标业务域已有同类页面时，优先对齐同业务域的真实目录结构，而不是机械使用
+`components/` 扁平目录。例如 `admin-fe` 销售模块已有
+`src/routes/sales/client/`，新建销售页面应优先采用同类分层：
+
+```text
+src/routes/sales/<page>/dashboard/<PageDashboard>.tsx
+src/routes/sales/<page>/toolbar/<PageFilters>.tsx
+src/routes/sales/<page>/toolbar/<PageScopeToolbar>.tsx
+src/routes/sales/<page>/table/<PageTable>.tsx
+src/routes/sales/<page>/detail-drawer/<PageDetailDrawer>.tsx
+src/routes/sales/<page>/modal/<PageModal>.tsx
+```
+
+只有目标业务域没有可参考页面，或页面确实只有一两个局部组件时，才使用默认
+`components/` 占位结构。
+
+规则：
+
+- 路由文件放在 `src/routes`。
+- 路由目录使用 lowercase kebab-case。
+- React 组件文件使用 PascalCase。
+- 非组件文件使用 kebab-case。
+- service 按业务域放在 `src/services` 下，优先复用已有业务域目录。
+- 不手动编辑 `src/routeTree.gen.ts`。
+- 页面仅使用的组件优先靠近 route；真正复用时再抽到公共目录。
+- UI 复用顺序：Apex UI -> `src/components` -> 业务局部组件 -> 新建局部组件。
+
+## Apex UI 组件契约规则
+
+`admin-fe` 使用 `@frontend/apex-ui--react`。page-build 中只要新增或改动 Apex
+UI 组件用法，必须先读取组件库随包提供的 LLM 文档和类型契约，不得根据 Ant
+Design、Radix UI 或原生 HTML 经验推断 props。
+
+必须读取：
+
+```text
+node_modules/@frontend/apex-ui--react/dist/llms.txt
+node_modules/@frontend/apex-ui--react/dist/llm/<component>.txt
+```
+
+必要时继续读取：
+
+```text
+node_modules/@frontend/apex-ui--react/dist/index.d.ts
+```
+
+规则：
+
+- 先从 `llms.txt` 确认组件是否存在，再读取实际使用组件对应的
+  `llm/<component>.txt`。
+- 必须核对组件 props、事件名、受控字段、数据结构、默认行为和限制。
+- 如果已有相似页面使用该组件，先对照相似页面，再以 Apex UI LLM 文档和
+  `index.d.ts` 类型声明为准。
+- 不得把 antd 的 `items`、`columns`、`onChange`、`value`、`visible`
+  等约定直接套到 Apex UI。
+- 如果文档、类型声明和实际运行行为冲突，必须记录为待确认项或技术风险；不得继续扩大该组件用法。
+- 文件创建计划中必须列出本次使用的 Apex UI 组件和已读取的文档来源。
+- 如果组件库存在已知缺陷，例如运行时 warning 或类型与行为不一致，优先在页面局部规避，并在总结中说明原因。
+
+## 模板使用
+
+使用以下模板作为占位参考：
+
+```text
+domains/frontend/templates/page-build/route.tsx.tpl
+domains/frontend/templates/page-build/component.tsx.tpl
+domains/frontend/templates/page-build/service.ts.tpl
+domains/frontend/templates/page-build/types.ts.tpl
+domains/frontend/templates/page-build/constants.ts.tpl
+domains/frontend/templates/page-build/index.ts.tpl
+```
+
+模板变量建议：
+
+- `{{routePath}}`：TanStack Router 路由路径，例如 `/sales/client`。
+- `{{pageComponentName}}`：页面组件名，例如 `SalesClientPage`。
+- `{{featureName}}`：业务域名，例如 `sales`。
+- `{{pageName}}`：页面名，例如 `client`。
+- `{{serviceModulePath}}`：service 导入路径，例如 `@/services/sales/client`。
+- `{{queryKeyPrefix}}`：query key 前缀，例如 `['sales', 'client']`。
+
+## API 落地规则
+
+- API 调用统一使用 `src/services/request.ts`。
+- service 函数签名必须从文档、飞书或 Apifox MCP 结果推导。
+- API 返回类型优先由 service function 导出，页面层通过 import type 使用。
+- 未确认接口不得写死路径、参数或响应字段。
+- 缺少接口路径时写 `TODO(api): confirm endpoint path`。
+- 缺少入参时写 `TODO(api): confirm request params`。
+- 缺少响应时写 `TODO(api): confirm response shape`。
+- 页面组件只调用 service，不直接调用 axios 或重新封装 request。
+
+## 状态规则
+
+- 页面级、临时、多实例或随生命周期销毁的状态使用组件 state、Context 或 useReducer。
+- Zustand 只用于全局、持久、跨页面或复杂状态。
+- shell 相关状态统一使用 `src/stores/shell-store.ts`。
+- Wujie 逻辑必须复用
+  `src/shared/wujie-bridge.ts`，页面内不得重写路由同步、props 同步、登录过期或主题同步。
+- page-build 不创建新的全局 store，除非已审核方案明确要求且 Human 再次确认。
+
+## 禁止项
+
+- 不写完整业务逻辑。
+- 不写最终视觉样式。
+- 不创建未确认接口字段。
+- 不创建无来源 mock 数据。
+- 不修改 `src/routeTree.gen.ts`。
+- 不重写 `src/services/request.ts`。
+- 不新增不必要的全局状态。
+- 不在页面内重写 Wujie bridge。
+- 不因为设计稿图层结构重拆业务组件。
+- 不跨越目标页面修改无关模块。
+
+## 输出格式
+
+文件改动前，输出：
+
+```md
+## page-build 文件创建计划
+
+### 输入事实
+
+### API 来源
+
+### 文件清单
+
+| 文件 | 操作 | 内容 | TODO | 是否阻塞 |
+| ---- | ---- | ---- | ---- | -------- |
+
+### 不会修改
+
+- src/routeTree.gen.ts
+
+### 待确认项
+```
+
+文件改动后，输出：
+
+- 已创建或修改文件。
+- 每个文件保留的 `TODO(api)` 和 `TODO(figmaSync)`。
+- 未验证内容。
+- 建议下一步执行的检查。
+
+## 验收标准
+
+- 能基于本地方案或飞书文档生成可 review 的文件创建计划。
+- 模板符合 admin-fe 命名、路由、请求、状态规则。
+- service 占位只使用 `src/services/request.ts`。
+- route 占位使用 TanStack Router。
+- 文件创建前存在 Human 确认机制。
+- Apifox 项目上下文只通过可用 MCP 工具读取，不编造能力。