adspecs 0.1.12

package/skills/sie-front-code-review/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: sie-front-code-review
+description: 基于前端编码规范执行 React + TypeScript + Ant Design 项目的代码评审，输出按严重级别排序的问题清单与修复建议
+---
+
+# Sie Front Code Review
+
+## 目标
+
+基于 `docs/40-project_conventions/frontend-integration/05-前端编码规范.md` 对前端改动进行结构化评审，优先识别：
+
+- 功能回归风险
+- 规范违规
+- 类型与可维护性问题
+- 缺失测试与验证
+
+评审结论必须可落地，禁止泛泛而谈。
+
+## 适用范围
+
+- React 19 + TypeScript 6 + Ant Design 6 + ProComponents
+- 路由、页面、组件、hooks、stores、api、mocks、i18n 相关变更
+
+## 评审输入
+
+至少收集以下信息：
+
+1. 改动文件列表与 diff
+2. 相关需求或任务说明
+3. 影响模块（页面路径、API 域、字典、权限）
+4. 可用验证结果（build/eslint/test）
+
+## 评审输出格式（必须遵守）
+
+1. Findings（按严重级别排序）
+2. Open Questions / Assumptions
+3. Change Summary（可选，简短）
+
+每条 Finding 必须包含：
+
+- 严重级别：Critical / Important / Minor
+- 位置：文件路径 + 行号
+- 现象：当前行为
+- 风险：可能导致的问题
+- 修复建议：明确可执行
+
+如果无问题，明确写：`No findings`，并补充残余风险和验证缺口。
+
+## 严重级别判定
+
+- Critical：会导致功能错误、数据错误、安全/权限问题、路由不可达、构建失败
+- Important：不符合核心规范、较高维护风险、明显类型/状态管理问题
+- Minor：风格一致性、可读性优化、非阻断改进
+
+## 必查清单
+
+### A. 路由与页面路径
+
+1. 页面文件路径是否与后端菜单 `component` 完全对齐
+2. 动态路由场景是否可能触发 `Component not found`
+3. 外链路由是否被错误注入
+
+### B. 列表页与表单模式
+
+1. 列表页是否优先使用 `ProTable`（非树形场景）
+2. `search: false`、`valueType`、`search.transform` 用法是否规范
+3. 日期区间列是否使用 `render`（不是 `renderText`）
+4. Modal/Drawer 是否遵循约定 props（`open/id/onSuccess/onCancel|onClose`）
+5. 编辑提交是否合并 `originData`
+
+### C. Modal / Drawer 使用规范（重点审查）
+
+1. Modal 是否使用 `onCancel`，Drawer 是否使用 `onClose`，避免混用回调语义
+2. 是否使用约定四件套 props：`open`、`id`、`onSuccess`、`onCancel|onClose`，避免 `ref.open()` / `defineExpose` 模式
+3. 关闭清理策略是否正确：Modal 用 `destroyOnHidden`，Drawer 用 `destroyOnClose`
+4. 编辑模式是否通过 `originData` + `values` 合并提交，防止未挂载字段丢失
+5. 编辑态隐藏字段是否使用 `hidden={!!id}`，避免条件渲染导致 `validateFields` 漏字段
+6. Drawer 宽度是否与字段规模匹配（4~10: 256；10~20: 600；21~30: 750；>30: 1024）
+7. 表单布局是否与字段规模匹配（一栏/两栏/三栏/四栏），输入控件宽度是否统一 `width: 100%`
+8. Modal/Drawer 标题是否遵循“新增/编辑”切换规则，避免与业务状态不一致
+9. 是否存在手动 `resetFields` 与销毁策略冲突、重复清理导致状态闪烁
+10. Drawer footer 操作是否明确（取消/确定），并正确处理提交 loading 与异常兜底
+
+### D. 类型与代码质量
+
+1. 是否出现 `any` / `as any` 滥用
+2. API 入参出参、store、hook 暴露类型是否显式
+3. hooks 依赖是否完整，是否违反 `react-hooks` 规则
+4. 单文件/函数复杂度是否明显超标且未拆分
+
+### E. 业务规范一致性
+
+1. 时间字段是否统一使用 `dateFormatter`
+2. 字典字段是否使用 `DictTag` + `valueEnum/getDictOptions`
+3. 按钮是否通过 `<Access code="...">` 做权限包裹
+4. i18n 文案是否硬编码，命名空间与 key 结构是否一致
+
+### F. API / Mock / 上传
+
+1. API 是否复用统一 `request` 与 `ApiResponse/PageResult` 类型
+2. Mock handler 路径是否含 `/admin-api/` 前缀
+3. 上传组件是否规避 Upload 的 `value` 误用
+4. token / tenant-id 头是否保持一致
+
+### G. 可验证性
+
+1. 是否有 `npm run build` 通过证据
+2. 是否有 `eslint` 检查证据（至少改动文件范围）
+3. 若缺少验证，必须在输出中明确标注 Testing Gap
+
+## 评审执行流程
+
+1. 先读规范与需求，再看 diff，禁止脱离上下文评审
+2. 优先找 Critical/Important，再补 Minor
+3. 同类问题合并描述，避免重复噪音
+4. 建议给出最小改动方案，避免不必要重构
+5. 结论必须可被开发者直接执行
+
+## 禁止项
+
+- 只给“代码不错/建议优化”但无定位与风险
+- 未验证事实就下结论
+- 忽略构建、lint、权限、路径对齐等硬约束
+- 仅从风格角度评审，遗漏行为正确性
+
+## 快速评审模板
+
+```markdown
+## Findings
+
+1. [Critical] path/to/file.tsx:88
+   - 现象：...
+   - 风险：...
+   - 建议：...
+
+2. [Important] path/to/file.ts:34
+   - 现象：...
+   - 风险：...
+   - 建议：...
+
+## Open Questions / Assumptions
+
+1. ...
+
+## Change Summary
+
+- ...
+```
+
+## 参考依据
+
+- `docs/40-project_conventions/frontend-integration/05-前端编码规范.md`

package/skills/wiki-update/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: wiki-update
+description: >-
+  Use when docs/20-prd or docs/30-system-design markdown files are created or
+  modified and need to be synced to the wiki/ directory. Triggered by user
+  command or wiki-queue hook suggestion at session stop. Supports full and
+  incremental sync modes.
+---
+
+# Wiki Update
+
+将 `{PRD_DIR}/` 和 `{DESIGN_DIR}/` 下的 Markdown 文档同步到 `{WIKI_DIR}/` 目录，保持目录结构一致。
+
+## 路径配置加载
+
+在开始执行之前，先确定源目录和目标目录：
+
+1. 检查项目根目录是否存在 `.adspecs/paths.json`
+2. 如果存在，读取其中的 `paths` 对象，提取本技能需要的配置键
+3. 如果不存在或配置键缺失，使用下方表格中的默认值
+
+| 配置键       | 默认值                  | 用途                  |
+| ------------ | ----------------------- | --------------------- |
+| `prd_dir`    | `docs/20-prd`           | PRD 文档源目录        |
+| `design_dir` | `docs/30-system-design` | 系统设计文档源目录    |
+| `wiki_dir`   | `wiki`                  | Wiki 文档输出目标目录 |
+
+将解析后的路径分别记为 `PRD_DIR`、`DESIGN_DIR` 和 `WIKI_DIR`，后续步骤中引用这些变量而非硬编码路径。
+
+## When to Use
+
+- 用户执行 `/wiki-update`
+- 会话结束时 hook 提示 `[wiki-update] Run: /wiki-update --mode=incremental --flush`
+- 需要更新项目 wiki 文档时
+
+## 参数
+
+| 参数      | 值             | 说明                        |
+| --------- | -------------- | --------------------------- |
+| `--mode`  | `full`（默认） | 全量扫描并同步所有 .md 文件 |
+| `--mode`  | `incremental`  | 仅同步队列中的变更文件      |
+| `--flush` | 无值           | 增量同步后清空队列文件      |
+
+**示例调用：**
+
+- `/wiki-update` — 全量同步
+- `/wiki-update --mode=incremental --flush` — 增量同步并清空队列
+
+## 目录映射
+
+```
+{PRD_DIR}/{子路径}           → {WIKI_DIR}/20-prd/{子路径}
+{DESIGN_DIR}/{子路径} → {WIKI_DIR}/30-system-design/{子路径}
+```
+
+**完整结构示例：**
+
+```
+{WIKI_DIR}/
+├── 20-prd/
+│   └── crm/
+│       ├── customer-master-data/
+│       │   └── M03-01_客户主数据需求规格说明书.md
+│       ├── fo-order/
+│       │   └── M08-01_履约单需求规格说明书.md
+│       ├── product-master-data/
+│       │   └── M01-01_产品主数据需求规格说明书.md
+│       ├── sales-forecast/
+│       │   └── M06-01_销售预测需求规格说明书.md
+│       └── one-time-contract/
+│           └── M07-02_单次合同需求规格说明书.md
+└── 30-system-design/
+    └── crm/
+        ├── M01-01-产品主数据_system-design.md
+        ├── M01-01-产品主数据_tasks.md
+        ├── M03-01-客户主数据_system-design.md
+        └── ...（所有 .md 文件）
+```
+
+## 文件过滤规则
+
+| 文件类型          | 是否同步 | 原因                       |
+| ----------------- | -------- | -------------------------- |
+| `*.md`            | ✅ 同步  | Wiki 文档内容              |
+| `*.html`          | ❌ 跳过  | HTML 原型，非 wiki 格式    |
+| `*.sql`           | ❌ 跳过  | 数据库 schema，非文档      |
+| `*.xlsx`          | ❌ 跳过  | Excel 附件                 |
+| `checklists/*.md` | ✅ 同步  | checklist 也是文档的一部分 |
+
+## 执行步骤
+
+### Full 模式（全量同步）
+
+```
+┌─────────────────────────────────────┐
+│ 1. 扫描源目录                         │
+│    Glob: {PRD_DIR}/**/*.md          │
+│    Glob: {DESIGN_DIR}/**/*.md       │
+│                                     │
+│ 2. 对每个 .md 文件:                   │
+│    ├─ Read 源文件内容                  │
+│    ├─ 计算 wiki 目标路径               │
+│    └─ Write 到 {WIKI_DIR}/ 对应路径   │
+│                                     │
+│ 3. 输出同步报告                        │
+│    - 新增文件数                        │
+│    - 更新文件数                        │
+│    - 总文件数                          │
+└─────────────────────────────────────┘
+```
+
+**步骤 1 — 扫描源目录：**
+
+使用 Glob 工具扫描两个源目录下所有 `.md` 文件：
+
+```
+Glob("{PRD_DIR}/**/*.md")
+Glob("{DESIGN_DIR}/**/*.md")
+```
+
+**步骤 2 — 逐文件同步：**
+
+对每个扫描到的文件：
+
+1. 用 `Read` 读取完整内容
+2. 计算目标路径：将源目录前缀替换为 `{WIKI_DIR}/`
+   - `{PRD_DIR}/crm/sales-forecast/M06-01_销售预测需求规格说明书.md` → `{WIKI_DIR}/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md`
+   - `{DESIGN_DIR}/crm/M06-01-销售预测_system-design.md` → `{WIKI_DIR}/30-system-design/crm/M06-01-销售预测_system-design.md`
+3. 用 `Write` 写入 wiki 目标路径（自动创建目录）
+
+**步骤 3 — 输出报告：**
+
+```
+═══ [wiki-update] 全量同步完成 ═══════════
+  新增: 12 个文件
+  更新: 5 个文件
+  总计: 17 个文件
+═══════════════════════════════════════════
+```
+
+### Incremental 模式（增量同步）
+
+```
+┌─────────────────────────────────────┐
+│ 1. 读取队列文件                        │
+│    .claude/.wiki-update-queue       │
+│                                     │
+│ 2. 过滤: 仅保留 {PRD_DIR}/ 或        │
+│    {DESIGN_DIR}/ 下的 .md            │
+│                                     │
+│ 3. 对每个文件:                        │
+│    ├─ 检查源文件是否存在               │
+│    ├─ Read + Write 到 wiki 路径       │
+│    └─ 记录同步状态                     │
+│                                     │
+│ 4. 若指定 --flush:                    │
+│    └─ 清空 .wiki-update-queue        │
+│                                     │
+│ 5. 输出同步报告                        │
+└─────────────────────────────────────┘
+```
+
+**步骤 1 — 读取队列：**
+
+读取 `.claude/.wiki-update-queue`，每行一个文件路径。
+
+**步骤 2 — 过滤文件：**
+
+仅保留同时满足以下条件的文件：
+
+- 路径包含 `{PRD_DIR}/` 或 `{DESIGN_DIR}/`
+- 以 `.md` 结尾
+
+**步骤 3 — 同步文件：**
+
+同 full 模式的步骤 2，但仅处理过滤后的文件列表。
+
+**步骤 4 — 清空队列（--flush）：**
+
+仅移除已处理的 wiki 相关条目，保留其他路径（如 `.java`、`.ts` 等非 wiki 文件路径）：
+
+1. 重新读取 `.claude/.wiki-update-queue`
+2. 过滤掉已同步的文件路径（即匹配 `{PRD_DIR}/` 或 `{DESIGN_DIR}/` 且以 `.md` 结尾的行）
+3. 将剩余行写回队列文件；若无剩余行，写入空字符串
+
+**步骤 5 — 输出报告：**
+
+```
+═══ [wiki-update] 增量同步完成 ═══════════
+  同步: 3 个文件
+  跳过: 1 个文件（非 wiki 目录）
+  队列已清空 ✓
+═══════════════════════════════════════════
+```
+
+## 路径计算逻辑
+
+源路径到 wiki 路径的转换规则：
+
+```
+输入: {PRD_DIR}/crm/sales-forecast/M06-01_销售预测需求规格说明书.md
+      └─ 替换源目录前缀为 {WIKI_DIR}/
+
+输出: {WIKI_DIR}/20-prd/crm/sales-forecast/M06-01_销售预测需求规格说明书.md
+```
+
+代码逻辑（伪代码）：
+
+```
+wikiPath = sourcePath
+  .replace(/^\{PRD_DIR\}\//, '{WIKI_DIR}/20-prd/')
+  .replace(/^\{DESIGN_DIR\}\//, '{WIKI_DIR}/30-system-design/')
+```
+
+## 错误处理
+
+| 情况                   | 处理方式                                  |
+| ---------------------- | ----------------------------------------- |
+| 源文件不存在（已删除） | 跳过，输出 `[跳过] 文件不存在: {path}`    |
+| 队列为空               | 输出 `队列为空，无需同步`，直接结束       |
+| wiki 目录不存在        | 自动创建                                  |
+| 队列文件不存在         | 输出 `队列文件不存在`，提示使用 full 模式 |
+
+## Common Mistakes
+
+| 错误                               | 正确做法                                       |
+| ---------------------------------- | ---------------------------------------------- |
+| 同步 .sql 或 .html 文件            | 仅同步 .md 文件                                |
+| 修改 wiki 目录结构（如扁平化）     | 严格保持与 docs 相同的目录层级                 |
+| 增量模式忘记清空队列               | 指定 `--flush` 时务必清空 `.wiki-update-queue` |
+| 将 `docs/300-specs/` 等同步到 wiki | 仅同步 `20-prd` 和 `30-system-design`          |
+| 使用文件复制命令                   | 使用 Read + Write 确保跨平台兼容               |

package/src/commands/doctor.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * 环境依赖检查
+ *
+ * 检查 adspecs 运行所需的各工具是否可用，输出状态报告。
+ * 不阻断 init 执行，仅作提示。
+ */
+module.exports = async function doctor() {
+  console.log(chalk.cyan('🩺 adspecs 环境检查'));
+  console.log('');
+
+  const checks = [
+    checkNode(),
+    checkGit(),
+    checkClaudeCli(),
+    checkPython(),
+    checkPowerShell(),
+    checkPluginIntegrity(),
+  ];
+
+  const maxNameLen = Math.max(...checks.map((c) => c.name.length));
+
+  for (const check of checks) {
+    const icon = check.ok ? chalk.green('✅') : check.required ? chalk.red('❌') : chalk.yellow('⚠');
+    const paddedName = check.name.padEnd(maxNameLen);
+    const version = check.version ? chalk.gray(`(${check.version})`) : '';
+    const status = check.ok
+      ? chalk.green(check.message || '可用')
+      : check.required
+        ? chalk.red(check.message || '未找到（必需）')
+        : chalk.yellow(check.message || '未找到（可选）');
+    console.log(`   ${icon} ${paddedName}  ${status} ${version}`);
+  }
+
+  console.log('');
+
+  const failed = checks.filter((c) => !c.ok);
+  const requiredFailed = failed.filter((c) => c.required);
+
+  if (requiredFailed.length > 0) {
+    console.log(chalk.red.bold(`❌ ${requiredFailed.length} 个必需依赖缺失，部分功能不可用`));
+    console.log('');
+    console.log('   安装指南：');
+    for (const c of requiredFailed) {
+      if (c.installHint) {
+        console.log(`   - ${c.name}: ${c.installHint}`);
+      }
+    }
+  } else if (failed.length > 0) {
+    console.log(chalk.yellow(`⚠ ${failed.length} 个可选依赖缺失，部分功能受限`));
+  } else {
+    console.log(chalk.green.bold('✅ 所有依赖检查通过'));
+  }
+
+  console.log('');
+};
+
+// ============================================================
+// 各项检查
+// ============================================================
+
+function checkNode() {
+  try {
+    const version = process.version;
+    const major = parseInt(version.slice(1).split('.')[0], 10);
+    const ok = major >= 18;
+    return {
+      name: 'Node.js',
+      ok,
+      required: true,
+      version,
+      message: ok ? '可用' : '版本过低（需要 >=18.0.0）',
+      installHint: '访问 https://nodejs.org 下载最新版本',
+    };
+  } catch {
+    return { name: 'Node.js', ok: false, required: true, message: '未找到' };
+  }
+}
+
+function checkGit() {
+  try {
+    const output = execSync('git --version', { stdio: 'pipe' }).toString().trim();
+    const version = output.match(/[\d.]+/)?.[0] || '';
+    return { name: 'Git', ok: true, required: false, version, message: '可用' };
+  } catch {
+    return {
+      name: 'Git',
+      ok: false,
+      required: false,
+      message: '未找到（git 扩展功能不可用）',
+      installHint: '访问 https://git-scm.com 下载',
+    };
+  }
+}
+
+function checkClaudeCli() {
+  try {
+    const output = execSync('claude --version', { stdio: 'pipe' }).toString().trim();
+    const version = output.match(/[\d.]+/)?.[0] || '';
+    return { name: 'Claude CLI', ok: true, required: false, version, message: '可用' };
+  } catch {
+    return {
+      name: 'Claude CLI',
+      ok: false,
+      required: false,
+      message: '未找到（plugin install 命令不可用）',
+      installHint: 'npm install -g @anthropic-ai/claude-code',
+    };
+  }
+}
+
+function checkPython() {
+  try {
+    const output = execSync('python3 --version 2>&1 || python --version 2>&1', {
+      stdio: 'pipe',
+      shell: true,
+    })
+      .toString()
+      .trim();
+    const version = output.match(/[\d.]+/)?.[0] || '';
+    return { name: 'Python', ok: true, required: false, version, message: '可用' };
+  } catch {
+    return {
+      name: 'Python',
+      ok: false,
+      required: false,
+      message: '未找到（Python 脚本不可用）',
+      installHint: '访问 https://www.python.org 下载',
+    };
+  }
+}
+
+function checkPowerShell() {
+  try {
+    // 尝试 PowerShell Core (pwsh)
+    const output = execSync('pwsh --version', { stdio: 'pipe' }).toString().trim();
+    const version = output.match(/[\d.]+/)?.[0] || '';
+    return { name: 'PowerShell', ok: true, required: false, version, message: '可用 (pwsh)' };
+  } catch {
+    try {
+      // 退而尝试 Windows PowerShell
+      if (process.platform === 'win32') {
+        execSync('powershell -Command "echo ok"', { stdio: 'pipe' });
+        return {
+          name: 'PowerShell',
+          ok: true,
+          required: false,
+          version: 'Windows PowerShell',
+          message: '可用 (Windows PowerShell)',
+        };
+      }
+    } catch {
+      // ignore
+    }
+    return {
+      name: 'PowerShell',
+      ok: false,
+      required: false,
+      message: '未找到（PowerShell 脚本不可用）',
+      installHint: '访问 https://github.com/PowerShell/PowerShell 安装 pwsh',
+    };
+  }
+}
+
+function checkPluginIntegrity() {
+  const pluginDir = path.resolve(__dirname, '../..');
+  const requiredPaths = [
+    '.claude-plugin/plugin.json',
+    '.adspecs/feature.json',
+    'skills/project-init/SKILL.md',
+    'hooks/hooks.json',
+  ];
+
+  const missing = requiredPaths.filter((p) => !fs.existsSync(path.join(pluginDir, p)));
+
+  if (missing.length === 0) {
+    return {
+      name: '插件完整性',
+      ok: true,
+      required: true,
+      message: `所有核心文件存在 (${pluginDir})`,
+    };
+  }
+
+  return {
+    name: '插件完整性',
+    ok: false,
+    required: true,
+    message: `缺失文件: ${missing.join(', ')}`,
+  };
+}

package/src/commands/init.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const path = require('path');
+const chalk = require('chalk');
+const { scaffold } = require('../lib/scaffolder');
+const {
+  collectProjectInfo,
+  collectDecisions,
+  collectSubDecisions,
+  detectModeUpgrade,
+  confirmExecution,
+} = require('../lib/prompts');
+const { deriveShortName } = require('../lib/short-name');
+const { scanAreaStates } = require('../lib/area-scanner');
+const { printPlanSummary, printFinalReport } = require('../lib/report');
+
+/**
+ * init 命令实现
+ *
+ * 10 步流程：
+ *  1. 收集项目信息
+ *  2. 扫描各区域存在状态
+ *  3. 收集每区域决策（3 选项：recreate/update/skip）
+ *  4. 收集子目录决策（conventions/templates）
+ *  5. 模式升级检测
+ *  6. 输出计划摘要
+ *  7. 等待用户确认
+ *  8. 执行脚手架（带实时状态输出）
+ *  9. 输出详细最终报告
+ *
+ * @param {object} options - CLI 选项（来自 commander）
+ */
+module.exports = async function init(options) {
+  console.log(chalk.cyan('🚀 adspecs 项目初始化'));
+  console.log('');
+
+  const pluginDir = path.resolve(__dirname, '../..');
+
+  // === Step 1: 收集项目信息 ===
+  const info = await collectProjectInfo(options);
+  info.project_short_name = deriveShortName(info.project_name, info.project_dir);
+
+  const targetDir = info.project_dir
+    ? path.resolve(process.cwd(), info.project_dir)
+    : process.cwd();
+
+  // === Step 2: 扫描区域状态 ===
+  const areaStates = scanAreaStates(targetDir, info.mode);
+
+  // === Step 3: 收集每区域决策 ===
+  const decisions = await collectDecisions(areaStates, options);
+
+  // === Step 4: 收集子目录决策 ===
+  const subDecisions = await collectSubDecisions(decisions, targetDir, options);
+
+  // === Step 5: 模式升级检测 ===
+  const modeUpgrade = detectModeUpgrade(decisions, info.mode, targetDir);
+
+  // === Step 6: 输出计划摘要 ===
+  printPlanSummary(info, decisions, subDecisions, modeUpgrade, targetDir);
+
+  // === Step 7: 等待用户确认 ===
+  const confirmed = await confirmExecution(options);
+  if (!confirmed) {
+    console.log(chalk.yellow('⏹ 已取消初始化'));
+    return;
+  }
+  console.log('');
+
+  // === Step 8: 执行脚手架（带实时状态输出） ===
+  const report = await scaffold({
+    targetDir,
+    pluginDir,
+    ...info,
+    decisions,
+    subDecisions,
+    modeUpgrade,
+    logger: (msg) => console.log(`   ${msg}`),
+  });
+
+  // === Step 9: 输出详细最终报告 ===
+  printFinalReport(report, info, decisions, subDecisions, modeUpgrade);
+};