adspecs 0.1.19 → 0.1.21

package/skills/project-init/references/front-demo/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm view *)",
+      "Bash(npm install *)",
+      "Bash(powershell *)"
+    ]
+  }
+}

package/skills/wiki-update/SKILL.md

@@ -1,232 +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 确保跨平台兼容               |
+---
+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 确保跨平台兼容               |