@dev-workflow/skill 0.1.0

package/skills/execution/devFlow/domains/frontend/scripts/contract_check_static.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+function parseArgs(argv) {
+  const args = {
+    routeDir: null,
+    service: null,
+    types: null,
+    constants: null,
+    json: false
+  }
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--route-dir=')) args.routeDir = arg.slice('--route-dir='.length)
+    else if (arg.startsWith('--service=')) args.service = arg.slice('--service='.length)
+    else if (arg.startsWith('--types=')) args.types = arg.slice('--types='.length)
+    else if (arg.startsWith('--constants=')) args.constants = arg.slice('--constants='.length)
+    else if (arg === '--json') args.json = true
+  }
+  return args
+}
+
+function exists(filePath) {
+  return Boolean(filePath && fs.existsSync(filePath))
+}
+
+function isKebabCase(value) {
+  return /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(value)
+}
+
+function isPascalCase(value) {
+  return /^[A-Z][A-Za-z0-9]*\.tsx$/.test(value)
+}
+
+function exportsPascalComponent(filePath) {
+  const source = fs.readFileSync(filePath, 'utf-8')
+  return (
+    /export\s+function\s+[A-Z][A-Za-z0-9]*\s*\(/.test(source) ||
+    /export\s+const\s+[A-Z][A-Za-z0-9]*\s*=/.test(source)
+  )
+}
+
+function collectFiles(dir) {
+  if (!fs.existsSync(dir)) return []
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...collectFiles(full))
+    else out.push(full)
+  }
+  return out
+}
+
+async function checkRouteTreeModified() {
+  const gitDir = '.git'
+  if (!fs.existsSync(gitDir)) return { status: 'unknown', modified: false }
+  try {
+    const { execSync } = await import('node:child_process')
+    const output = execSync('git status --porcelain -- src/routeTree.gen.ts', { encoding: 'utf-8' })
+    return { status: 'ok', modified: output.trim().length > 0 }
+  } catch {
+    return { status: 'unknown', modified: false }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv)
+  const checks = []
+
+  if (!args.routeDir) {
+    checks.push({ name: 'routeDir', ok: false, message: 'missing --route-dir' })
+  } else {
+    checks.push({
+      name: 'routeDirExists',
+      ok: fs.existsSync(args.routeDir),
+      message: args.routeDir
+    })
+    const rel = path.relative('src/routes', args.routeDir)
+    const segments = rel.split(path.sep).filter(Boolean)
+    checks.push({
+      name: 'routeDirNaming',
+      ok: !rel.startsWith('..') && segments.every(isKebabCase),
+      message: rel
+    })
+    checks.push({
+      name: 'routeFileExists',
+      ok: exists(path.join(args.routeDir, 'route.tsx')),
+      message: path.join(args.routeDir, 'route.tsx')
+    })
+
+    const componentFiles = collectFiles(args.routeDir).filter(
+      (file) =>
+        file.endsWith('.tsx') &&
+        path.basename(file) !== 'route.tsx' &&
+        path.basename(file) !== 'index.tsx'
+    )
+    const componentExports = componentFiles.filter(exportsPascalComponent)
+    const badComponents = componentExports.filter((file) => !isPascalCase(path.basename(file)))
+    checks.push({
+      name: 'componentFileNaming',
+      ok: badComponents.length === 0,
+      message:
+        badComponents.length === 0
+          ? `${componentExports.length} component files checked`
+          : badComponents
+    })
+  }
+
+  const typesPath = args.types ?? (args.routeDir ? path.join(args.routeDir, 'types.ts') : null)
+  const constantsPath =
+    args.constants ?? (args.routeDir ? path.join(args.routeDir, 'constants.ts') : null)
+  checks.push({ name: 'typesExists', ok: exists(typesPath), message: typesPath })
+  checks.push({ name: 'constantsExists', ok: exists(constantsPath), message: constantsPath })
+  if (args.service)
+    checks.push({ name: 'serviceExists', ok: exists(args.service), message: args.service })
+
+  const routeTree = await checkRouteTreeModified()
+  checks.push({
+    name: 'routeTreeNotModified',
+    ok: !routeTree.modified,
+    message: routeTree.status === 'unknown' ? 'git status unavailable' : 'src/routeTree.gen.ts'
+  })
+
+  const result = {
+    ok: checks.every((check) => check.ok),
+    checks
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  for (const check of checks) {
+    console.log(
+      `${check.ok ? 'PASS' : 'FAIL'} ${check.name}: ${Array.isArray(check.message) ? check.message.join(', ') : check.message}`
+    )
+  }
+  process.exit(result.ok ? 0 : 1)
+}
+
+main().catch((error) => {
+  console.error(error.message)
+  process.exit(1)
+})

package/skills/execution/devFlow/domains/frontend/scripts/generate_foundation_summary.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import fs from 'node:fs'
+import path from 'node:path'
+
+const AUTO_HEADER = '<!-- AUTO-GENERATED. Do not edit. Regenerate from source files. -->'
+
+function parseArgs(argv) {
+  const args = { routeDir: null, service: null, out: null, check: false }
+  for (const arg of argv.slice(2)) {
+    if (arg.startsWith('--route-dir=')) args.routeDir = arg.slice('--route-dir='.length)
+    else if (arg.startsWith('--service=')) args.service = arg.slice('--service='.length)
+    else if (arg.startsWith('--out=')) args.out = arg.slice('--out='.length)
+    else if (arg === '--check') args.check = true
+  }
+  return args
+}
+
+function collectFiles(dir) {
+  if (!fs.existsSync(dir)) return []
+  const out = []
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...collectFiles(full))
+    else out.push(full)
+  }
+  return out.sort()
+}
+
+function read(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf-8') : ''
+}
+
+function rel(file) {
+  return file ? path.relative(process.cwd(), file) : ''
+}
+
+function extractComponentProps(file) {
+  const source = read(file)
+  const out = []
+  const interfaceRe = /export\s+interface\s+([A-Z][A-Za-z0-9]*Props)\s*{([\s\S]*?)\n}/g
+  let m
+  while ((m = interfaceRe.exec(source)) !== null) {
+    out.push(`${m[1]} { ${m[2].replace(/\s+/g, ' ').trim()} }`)
+  }
+  const typeRe = /export\s+type\s+([A-Z][A-Za-z0-9]*Props)\s*=\s*([^;\n]+)/g
+  while ((m = typeRe.exec(source)) !== null) out.push(`${m[1]} = ${m[2].trim()}`)
+  return out
+}
+
+function extractExports(source, keyword) {
+  const re = new RegExp(`export\\s+${keyword}\\s+([A-Za-z0-9_]+)`, 'g')
+  const out = []
+  let m
+  while ((m = re.exec(source)) !== null) out.push(m[1])
+  return out
+}
+
+function extractServiceFunctions(file) {
+  const source = read(file)
+  const out = []
+  const re = /export\s+(?:async\s+)?function\s+([A-Za-z0-9_]+)\s*\(([^)]*)\)/g
+  let m
+  while ((m = re.exec(source)) !== null) out.push(`${m[1]}(${m[2].replace(/\s+/g, ' ').trim()})`)
+  return out
+}
+
+function renderList(items) {
+  return items.length > 0 ? items.map((item) => `- ${item}`).join('\n') : '- 未发现'
+}
+
+function renderTable(rows, empty) {
+  return rows.length > 0 ? rows.join('\n') : empty
+}
+
+function buildSummary({ routeDir, service }) {
+  const files = collectFiles(routeDir)
+  const routeFile = path.join(routeDir, 'route.tsx')
+  const componentFiles = files.filter(
+    (file) =>
+      file.endsWith('.tsx') &&
+      path.basename(file) !== 'route.tsx' &&
+      path.basename(file) !== 'index.tsx'
+  )
+  const typesFile = path.join(routeDir, 'types.ts')
+  const constantsFile = path.join(routeDir, 'constants.ts')
+  const serviceFile = service && fs.existsSync(service) ? service : null
+
+  const componentRows = componentFiles.map((file) => {
+    const props = extractComponentProps(file)
+    return `| ${path.basename(file, '.tsx')} | ${rel(file)} | ${props.length > 0 ? props.join('<br/>') : '-'} | ${props.length > 0 ? 'OK' : 'NO_PROPS_EXPORT'} |`
+  })
+  const serviceRows = serviceFile
+    ? extractServiceFunctions(serviceFile).map(
+        (signature) => `| ${signature.split('(')[0]} | ${rel(serviceFile)} | \`${signature}\` |`
+      )
+    : []
+  const typeRows = fs.existsSync(typesFile)
+    ? [
+        ...extractExports(read(typesFile), 'interface'),
+        ...extractExports(read(typesFile), 'type')
+      ].map((name) => `| ${name} | ${rel(typesFile)} |`)
+    : []
+  const constRows = fs.existsSync(constantsFile)
+    ? extractExports(read(constantsFile), 'const').map(
+        (name) => `| ${name} | ${rel(constantsFile)} |`
+      )
+    : []
+
+  const pending = []
+  if (!fs.existsSync(routeFile)) pending.push('route.tsx 未发现')
+  if (!fs.existsSync(typesFile)) pending.push('types.ts 未发现')
+  if (!fs.existsSync(constantsFile)) pending.push('constants.ts 未发现')
+  if (!serviceFile) pending.push('service 文件未指定或未发现')
+
+  return `${AUTO_HEADER}
+
+# foundation-summary：${path.basename(routeDir)}
+
+## 1. 生成信息
+
+- routeDir：${rel(routeDir)}
+- generatedAt：${new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')}
+- generator：.agent/skills/devFlow/domains/frontend/scripts/generate_foundation_summary.mjs
+
+## 2. 文件事实
+
+### route
+
+${fs.existsSync(routeFile) ? `- ${rel(routeFile)}` : '- 未发现'}
+
+### components
+
+${renderList(componentFiles.map(rel))}
+
+### service
+
+${serviceFile ? `- ${rel(serviceFile)}` : '- 未发现'}
+
+### types
+
+${fs.existsSync(typesFile) ? `- ${rel(typesFile)}` : '- 未发现'}
+
+### constants
+
+${fs.existsSync(constantsFile) ? `- ${rel(constantsFile)}` : '- 未发现'}
+
+## 3. 组件 props
+
+| 组件 | 文件 | Props | 解析状态 |
+|---|---|---|---|
+${renderTable(componentRows, '| - | - | - | 未发现组件 |')}
+
+## 4. service 函数签名
+
+| 函数 | 文件 | 签名 |
+|---|---|---|
+${renderTable(serviceRows, '| - | - | 未发现 service 函数 |')}
+
+## 5. types 导出
+
+| 类型 | 文件 |
+|---|---|
+${renderTable(typeRows, '| - | 未发现类型导出 |')}
+
+## 6. constants 导出
+
+| 常量 | 文件 |
+|---|---|
+${renderTable(constRows, '| - | 未发现常量导出 |')}
+
+## 7. figmaSync 允许修改范围
+
+- 布局。
+- CSS。
+- Apex UI 组件选型和 props。
+- 局部展示结构。
+- PLAN.md 和 figma-plan.css。
+
+## 8. figmaSync 禁止修改范围
+
+- 路由路径。
+- service 契约。
+- API 请求基础封装。
+- 类型语义。
+- 页面核心状态模型。
+- 业务组件边界。
+- 权限逻辑。
+- Wujie bridge。
+- src/routeTree.gen.ts。
+
+## 9. 待确认项
+
+${renderList(pending)}
+`
+}
+
+function main() {
+  const args = parseArgs(process.argv)
+  if (!args.routeDir || !fs.existsSync(args.routeDir)) {
+    console.error('[foundation-summary] missing or invalid --route-dir')
+    process.exit(1)
+  }
+  const out = args.out ?? path.join(args.routeDir, 'foundation-summary.md')
+  const next = buildSummary({ routeDir: args.routeDir, service: args.service })
+  const prev = fs.existsSync(out) ? fs.readFileSync(out, 'utf-8') : null
+  if (args.check) {
+    if (normalizeForCompare(prev) !== normalizeForCompare(next)) {
+      console.error(`[foundation-summary] out of date: ${out}`)
+      process.exit(1)
+    }
+    console.log(`[foundation-summary] up to date: ${out}`)
+    return
+  }
+  fs.writeFileSync(out, next)
+  console.log(`[foundation-summary] wrote ${out}`)
+  if (prev && prev !== next)
+    console.log('[foundation-summary] changed from previous snapshot; ask Human to confirm impact.')
+}
+
+main()
+
+function normalizeForCompare(text) {
+  return String(text ?? '').replace(/generatedAt：.+/g, 'generatedAt：<ignored>')
+}

package/skills/execution/devFlow/domains/frontend/templates/contract-report.md

@@ -0,0 +1,66 @@
+# contract-report：{页面名称}
+
+## 1. 总结论
+
+- 结论：通过 / 不通过 / 阻塞
+- 是否允许进入 page-build：是 / 否
+- 结论说明：
+
+## 2. 输入材料
+
+| 材料                  | 来源 | 是否已读取 | 关键证据 |
+| --------------------- | ---- | ---------- | -------- |
+| 页面方案              |      |            |          |
+| API 文档 / Apifox MCP |      |            |          |
+| 当前项目结构          |      |            |          |
+| 相似页面              |      |            |          |
+
+## 3. 检查范围
+
+- 目标 route：
+- 目标页面目录：
+- 目标 service：
+- 目标组件：
+- 不检查范围：
+
+## 4. Checklist
+
+| 检查项         | 结论 | 证据 | 问题 | 是否阻塞 |
+| -------------- | ---- | ---- | ---- | -------- |
+| 路由路径       |      |      |      |          |
+| 目录和文件命名 |      |      |      |          |
+| API 契约       |      |      |      |          |
+| 页面状态       |      |      |      |          |
+| 组件映射       |      |      |      |          |
+| 待确认项       |      |      |      |          |
+
+## 5. API 契约明细
+
+| 接口 | 请求路径 | Method | 入参 | 响应 | 调用组件 | 触发交互 | 刷新范围 | 异常反馈 | 证据 | 结论 |
+| ---- | -------- | ------ | ---- | ---- | -------- | -------- | -------- | -------- | ---- | ---- |
+
+## 6. 页面状态明细
+
+| 状态 | 来源 | 变化条件 | 消费组件 | 证据 | 结论 |
+| ---- | ---- | -------- | -------- | ---- | ---- |
+
+## 7. 组件映射明细
+
+| 组件 | 页面功能 | 输入 | 输出 / 事件 | 证据 | 结论 |
+| ---- | -------- | ---- | ----------- | ---- | ---- |
+
+## 8. 阻塞项
+
+| 阻塞项 | 影响 | 需要补充的信息 | 建议回到章节 |
+| ------ | ---- | -------------- | ------------ |
+
+## 9. 非阻塞待确认项
+
+| 待确认项 | 影响 | 后续处理 |
+| -------- | ---- | -------- |
+
+## 10. page-build 准入结论
+
+- 准入结论：
+- 可进入 page-build 的文件范围：
+- 不允许 page-build 处理的内容：

package/skills/execution/devFlow/domains/frontend/templates/mini-plan-l0.md

@@ -0,0 +1,7 @@
+# L0 Mini Plan：{任务名称}
+
+- 档位：L0
+- 要改什么：
+- 涉及文件：
+- 不改什么：
+- 验证方式：

package/skills/execution/devFlow/domains/frontend/templates/mini-plan-l1.md

@@ -0,0 +1,9 @@
+# L1 Mini Plan：{任务名称}
+
+- 档位：L1
+- 上下文：
+- 要改什么：
+- 涉及文件：
+- 不改什么：
+- 风险：
+- 验证方式：

package/skills/execution/devFlow/domains/frontend/templates/page-build/component.tsx.tpl

@@ -0,0 +1,8 @@
+export function {{componentName}}() {
+  return (
+    <section>
+      {/* TODO(figmaSync): implement final layout and Apex UI component selection after design sync. */}
+      {/* TODO(api): connect confirmed service functions and page states. */}
+    </section>
+  )
+}

package/skills/execution/devFlow/domains/frontend/templates/page-build/constants.ts.tpl

@@ -0,0 +1,5 @@
+export const {{queryKeyConstName}} = {{queryKeyPrefix}} as const
+
+export const {{initialStateConstName}} = {
+  // TODO(api): confirm initial query params and UI state.
+} as const

package/skills/execution/devFlow/domains/frontend/templates/page-build/index.ts.tpl

@@ -0,0 +1 @@
+export { Route } from './route'

package/skills/execution/devFlow/domains/frontend/templates/page-build/route.tsx.tpl

@@ -0,0 +1,11 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+import { {{pageComponentName}}Shell } from './components/{{pageComponentName}}Shell'
+
+export const Route = createFileRoute('{{routePath}}')({
+  component: {{pageComponentName}}
+})
+
+function {{pageComponentName}}() {
+  return <{{pageComponentName}}Shell />
+}

package/skills/execution/devFlow/domains/frontend/templates/page-build/service.ts.tpl

@@ -0,0 +1,17 @@
+import request, { type RequestOptions } from '@/services/request'
+
+export interface {{listParamsName}} {
+  // TODO(api): confirm request params.
+}
+
+export interface {{listResultName}} {
+  // TODO(api): confirm response shape.
+}
+
+const {{apiPathsConstName}} = {
+  list: 'TODO(api): confirm endpoint path'
+} as const
+
+export function {{listFunctionName}}(params: {{listParamsName}}, options?: RequestOptions) {
+  return request.post<{{listResultName}}>({{apiPathsConstName}}.list, params, options)
+}

package/skills/execution/devFlow/domains/frontend/templates/page-build/types.ts.tpl

@@ -0,0 +1,11 @@
+import type { {{listParamsName}}, {{listResultName}} } from '{{serviceModulePath}}'
+
+export interface {{pageStateName}} {
+  params: {{listParamsName}}
+}
+
+export type {{pageListResultName}} = {{listResultName}}
+
+export interface {{pageViewModelName}} {
+  // TODO(api): map confirmed response fields to page view model.
+}

package/skills/execution/devFlow/domains/frontend/templates/page-tech.md

@@ -0,0 +1,103 @@
+# 页面开发技术方案：{页面名称}
+
+## 1. 背景与目标
+
+## 2. 页面范围
+
+### 2.1 页面入口
+
+### 2.2 页面结构
+
+### 2.3 页面状态
+
+### 2.4 非目标范围
+
+## 3. 需求拆解
+
+### 3.1 功能与接口映射
+
+| 功能 | PRD 交互项 | 接口 | 入参 | 响应数据 | 页面展示 / 行为 | 状态变化 | 成功后刷新 | 异常反馈 |
+| ---- | ---------- | ---- | ---- | -------- | --------------- | -------- | ---------- | -------- |
+
+### 3.2 用户流程
+
+### 3.3 关键交互
+
+| PRD 交互项 | 触发条件 | 前端行为 | 接口或状态影响 | 用户反馈 | 待确认 |
+| ---------- | -------- | -------- | -------------- | -------- | ------ |
+
+## 4. 数据与接口
+
+### 4.1 依赖数据
+
+### 4.2 接口补充说明
+
+### 4.3 请求参数
+
+### 4.4 响应数据
+
+### 4.5 异常处理
+
+## 5. 前端实现方案
+
+### 5.1 目录结构与产物路径
+
+### 5.2 可复用资源清单
+
+### 5.3 UI 库组件清单
+
+### 5.4 组件拆分
+
+### 5.5 状态设计
+
+### 5.6 数据流
+
+```mermaid
+flowchart LR
+  A["用户操作"] --> B["页面状态"]
+  B --> C["接口请求"]
+  C --> D["页面展示"]
+```
+
+### 5.7 提交表单与校验（如涉及）
+
+## 6. UI 与体验约束
+
+### 6.1 设计稿信息
+
+### 6.2 响应式要求
+
+### 6.3 Loading 状态
+
+### 6.4 空状态
+
+### 6.5 错误反馈
+
+## 7. 非功能性设计
+
+### 7.1 性能设计
+
+### 7.2 权限与安全
+
+### 7.3 可访问性
+
+### 7.4 埋点与监控
+
+### 7.5 可维护性
+
+### 7.6 可测试性
+
+## 8. 边界场景
+
+## 9. 完成标准
+
+## 10. 风险与待确认项
+
+### 10.1 风险项
+
+#### PRD / 接口 / 仓库 / 规范冲突项
+
+| 冲突项 | PRD 描述 | 接口或仓库现状 | 影响 | 建议确认对象 |
+| ------ | -------- | -------------- | ---- | ------------ |
+
+### 10.2 待确认问题