App Skill Wizard

Skill 创建向导

交互式引导：为目标项目按模块生成 Copilot 专家 Skill，注册到类别系统，通过 GUI 部署。 支持任意平台和应用层级。当存在 project-profile.json 时自动消费其中的技术栈/分层信息。 AI 自动执行大部分操作，在 3 个检查点暂停等用户确认。

🔴 执行声明（强制）

你正在执行一个交互式向导，必须严格按照以下流程执行。 每个步骤完成后更新进度，在 🔴 检查点处必须暂停等用户确认后再继续。

启动时的开场引导（强制）

收到用户消息后，立即显示以下引导信息（在做任何操作之前）：

👋 你好！我来帮你生成 Copilot Skill。

**整个过程我来跑，你只需要在 3 个关键节点确认一下：**

1️⃣ 确认模块清单 — 我分析完代码后，你看看模块划分对不对
2️⃣ 确认生成质量 — Skill 文件生成完，我会自动 lint 检查 + 评分
3️⃣ 确认交付清单 — 最终文件列表，可选自动提交 PR 并通知审阅人

⬇️ 现在开始收集信息...

然后进入 Step 0。

执行流程

Step 0  环境 + 信息收集
  │
  ├── 0-pre 运行模式选择
  ├── 0a   提取应用名 + 命名前缀
  ├── 0a'  确定 Skill 层级（应用/平台）
  ├── 0b   获取模块列表
  └── 0c   分析平台继承关系（应用层）
  │
  ▼
🔴 CP0  模块清单确认         ◀── 暂停：展示表格，等用户确认/修改
  │
  ▼
Step 1  分批研究 + 生成
  │
  ├── 1a   读取模版 + 参考
  ├── 1b   分批深度研究（runSubagent）
  ├── 1c   基于研究报告逐批生成 SKILL.md
  ├── 1d   [应用层] 读取 XML 配置自动填充
  └── 1e   自动 lint 验证
  │
  ▼
🔴 CP1  生成质量确认         ◀── 暂停：展示 lint 结果 + 评分卡，等用户确认
  │
  ▼
Step 2  注册类别 + 配置（AI自动）
  │
  ▼
🔴 CP2  交付确认             ◀── 暂停：展示文件清单，等用户确认
  │
  ▼
Step 3  [可选] 提交 PR + 飞书通知
  │
  ├── 3-local  [多根工作区] 本地脚本 create_skill_pr.ps1
  └── 3-remote [纯目标项目] MCP create_branch → create_commit → create_pull_request
  │
  ▼
🔴 CP3  最终交付确认         ◀── 暂停：展示 PR 链接 + 通知状态

Step 0：环境 + 信息收集

0-pre-profile. 检查 project-profile.json

优先检查 .copilot-temp/project-setup/*/project-profile.json 是否存在。

如存在：

• 读取 profile 中的 techStack、layers、platform、configDiscovery
• 跳过 Step 0a'(Skill层级)和 Step 0c(平台继承分析) 中的 平台特有逻辑
• 在 Step 1b 的研究指令中注入技术栈相关搜索项
• 在 Step 1d 的配置发现中使用 profile 的 configDiscovery 规则

如不存在：

• 回退到现有交互式收集流程（完全兼容现有用法）

0-pre. 运行模式选择

自动检测当前工作区结构，使用 ask_questions 确认运行模式：

1. 检查工作区根目录列表 — 确认是否包含工具项目（含 templates/skills/ 和 data/skill_categories.json）
2. 检查 MCP 可用性 — 确认是否有 azureDevOpsHSW MCP server（可访问工具仓库）

模式选择（ask_questions）：

• header: "运行模式"
• question: "检测到当前环境支持以下模式，请选择："
• 选项A（推荐 — 如检测到工具项目）: "多根工作区模式 — 工具项目已在工作区，本地读写"
• 选项B（推荐 — 如未检测到工具项目但有 MCP）: "纯目标项目模式 — 通过 MCP 远程读写工具仓库"

如果两种模式都不可用（无工具项目 + 无 HSW MCP），使用 ask_questions 引导：

• header: "环境设置"
• question: "当前环境无法访问工具仓库。请选择以下方式之一设置环境："
• 选项A: "添加工具项目到工作区（File > Add Folder to Workspace...）"
• 选项B: "运行 GUI 工具配置 MCP（双击 点我启动.bat）"

0a. 提取应用名和命名前缀

从用户消息中提取应用名称（如 "YourApp"、"{{PLATFORM_REPO}}"），然后推导：

• 命名前缀: 全小写 + 连字符，如 cardiacct- 或 平台-
• Skill 命名格式: {前缀}{模块名}-expert

如果用户未明确说应用名，使用 ask_questions 对话框询问：

• header: "应用名称"
• question: "请输入要创建 Skill 的应用/项目名称（如 YourApp、YourPlatform、{{PLATFORM_REPO}}）"
• allowFreeformInput: true，无预设选项

0a'. 确定 Skill 层级

如已从 project-profile.json 读取层级信息，可跳过此步。

使用 ask_questions 确认 Skill 层级：

• header: "Skill层级"
• question: "这批 Skill 属于哪个层级？不同层级的模版章节和行数限制不同。"
• 选项A: "应用层 — 有配置映射，≤120 行" (recommended)
• 选项B: "平台层 — 有搜索策略+核心概念，≤150 行"

层级差异：

0b. 获取模块列表

直接在多根工作区中访问目标项目，按优先级获取模块列表：

1. 用户提到了模块清单文件 → 直接 read_file 读取
2. 搜索现有清单 → 在目标项目中 file_search 搜索 *功能模块清单*
3. 扫描目录结构推断 → list_dir 目标项目关键目录
   • 如有 project-profile.json: 使用 layers[].dirPattern 扫描对应目录
   • 平台默认: 扫描 BE/、FE/、WebFE/ 目录
   • 其他项目: 扫描 src/、packages/、modules/ 等通用目录
4. 均无法确定 → 使用 ask_questions 对话框询问用户提供模块列表

对每个模块确定：

• 模块中文名
• 模块英文标识（用于 Skill 命名）
• 一句话职责描述

0c. 分析平台继承关系

仅应用层执行，平台层跳过。

对每个模块判断与平台的关系：

• 如有 project-profile.json: 读取 platform.identifier 构建平台专家前缀
  • 搜索关键词: project-profile.platform.name 相关的 import/using/include 语句
  • 平台专家关联: #{platform_identifier}-{component}-expert
• 平台默认（无 profile 时）:
  • 依据 1: 模块名是否与已有 {{PLATFORM_PREFIX}}-*-expert 同名
  • 依据 2: 搜索 using.*平台|import.*平台 判断是否引用平台
  • 依据 3: 应用特有功能判定为 🆕 独立实现

输出两类：

• 🔄 扩展继承: 有对应平台模块 → 记录关联的平台专家
• 🆕 独立实现: 无对应平台模块

🔴 检查点 0：模块清单确认

必须暂停，向用户展示以下表格并等待确认：

## 📋 模块清单确认

**Skill 层级**: {应用层/平台层}
**应用名**: {AppName}
**命名前缀**: `{app}-`
**模块总数**: {N} 个
**计划分批**: {ceil(N/6)} 批（每批 ≤6 个模块）

| # | 模块 | Skill 名称 | 继承类型 | 关联平台专家 |
|---|------|-----------|----------|-------------|
| 1 | ... | `{app}-{mod}-expert` | 🔄/🆕 | ... |

请确认是否正确，可以增删模块、修改命名、调整继承类型。

使用 ask_questions 让用户确认：

• header: "模块确认"
• question: "请看上面的模块列表，确认划分是否合理"
• 选项A（推荐）: "没问题，继续生成"
• 选项B: "需要修改" (allowFreeformInput: true)

Step 1：分批研究 + 生成

1a. 读取模版和参考

多根工作区模式：

1. 读取 templates/skills/_templates/module-expert-skill.md — 获取标准模版结构
2. 读取一个已有的同层级 Skill 作为格式参考：
   • 应用层: templates/skills/app-*-expert/SKILL.md
   • 平台层: templates/skills/{{PLATFORM_PREFIX}}-*-expert/SKILL.md（若无，到目标项目 .github/skills/ 找）

纯目标项目模式：

1. MCP get_file_content(repo=AdvAppCommonKnowledge, path=templates/skills/_templates/module-expert-skill.md) — 远程读取模版
2. 如目标项目 .github/skills/_templates/module-expert-skill.md 存在（GUI 部署时已复制），优先用本地版本
3. 格式参考同上，优先本地 .github/skills/ 下已有的 Skill

1b. 分批深度研究

将模块按 每批 ≤6 个 分组，对每一批使用 runSubagent 进行深度研究。

Subagent 研究指令模板：

请对以下 {N} 个模块进行深度研究，目标项目在 {target_project_root}。

模块列表：{module1}, {module2}, ...

对每个模块，请调查以下内容并输出结构化报告：

1. **目录结构**: 列出各代码层级目录下的相关子目录和文件数量
2. **关键类清单**: 找出 3-8 个核心类/接口名称（精确大小写）
3. **命名空间/包名**: 查找模块的命名空间或包名模式
4. **导出/公开接口**: 查找公开接口和导出符号
5. **常见拼写陷阱**: 搜索非标准拼写
{tech_specific_instructions}

技术栈特定研究指令 ({tech_specific_instructions}):

研究报告产出到对话中，不写文件。每批完成后输出进度。

1c. 基于研究逐批生成 SKILL.md

依据研究报告 + 模版结构，为当前批次的每个模块生成 SKILL.md。

生成位置:

• 多根工作区模式: templates/skills/{app}-{module}-expert/SKILL.md（工具项目内）
• 纯目标项目模式: .github/skills/{app}-{module}-expert/SKILL.md（目标项目内，本地预览）

生成规则：

1. YAML frontmatter 必填：name 与目录名相同，description 含 ≥3 触发关键词
2. 必填章节 — 参考 module-expert-skill.md 的标记系统（[通用]/[应用必填]/[平台必填]）
3. 精确性要求（v3 核心原则）：
   • 类名、文件路径必须来自研究报告的实际扫描结果
   • 禁止编造或推测不存在的符号
   • 拼写陷阱必须有具体文件名为证
4. 行数控制: 应用层 ≤ 120 行 / 平台层 ≤ 150 行
5. 内容完整性红线（强制）：
   • ❗ 模板格式不可简化: 执行声明规范、必填章节等固定格式必须完整保留，禁止压缩或省略
   • ❗ 必要内容不可删减: 场景入口、陷阱条目、依赖行、配置映射等经验证的内容不得为了行数限制而删除或合并
   • ✅ 超限时拆分到 reference: 若行数超限，将较大的独立章节（如运行时配置映射、大型表格）拆分到 references/ 目录
   • 拆分后在 SKILL.md 中保留指针: 📖 详细内容见 \references/xxx.md``
6. 业务规则: 框架完整但内容标记 🔴 TODO: 待补充

每生成 3 个 Skill 后输出进度：

✅ 批次 {B}/{total}: 已生成 {app}-{mod1}-expert, {app}-{mod2}-expert, {app}-{mod3}-expert

1d. [应用层] 配置文件自动填充

仅应用层执行，平台层跳过。配置格式从模板 v4 的配置发现规则获取。

配置发现策略：

1. 如有 project-profile.json: 使用 configDiscovery.format 和 configDiscovery.basePath
   • XML: 搜索 {basePath}/**/*.xml，提取 <Operation>/<Handler> 等节点
   • YAML/JSON: 搜索 {basePath}/**/*.{yaml,yml,json}，提取路由/服务配置
   • none: 跳过此步
2. 平台默认（无 profile）: 搜索 XML 配置文件
   • 搜索路径: file_search("**/appdata/*/config/[你的配置目录]/[配置文件]")
   • 核心文件: [后端配置文件]、BE/WorkflowController.xml、[前端命令配置]
   • 提取内容: 按模块名 grep 相关 Operation/Widget/Model 注册项
3. 自动填充: 将提取结果写入各 SKILL.md 的「运行时配置映射」章节，标记 🤖

1e. 自动 lint 验证

所有 Skill 生成完毕后，自动在终端运行 lint 检查：

python scripts/lint_skills.py --skill {app}-*-expert

lint 检查项：

• YAML frontmatter 必填字段（name + description）
• 触发词冲突检测（与现有 Skill 无重复）
• references 文件引用有效性
• 名称规范（连字符格式，≤64 字符）

将 lint 结果纳入 CP1 评分卡。如果有 lint 错误，先自动修复，修复后重新 lint，确认全部通过后再进入 CP1。

🔴 检查点 1：生成质量确认

必须暂停，向用户展示 lint 结果 + 质量评分卡：

## 📊 生成质量评分卡

### Lint 检查
✅ 全部通过（{N} 个 Skill, 0 个错误）

### 内容评分

| Skill | 行数 | frontmatter | 场景入口 | 上下游 | 得分 |
|-------|------|:-----------:|:--------:|:------:|------|
| `{app}-xxx-expert` | 95 | ✅ | ✅ 3个 | ✅ | 4/4 |
| ... | | | | | |

**评分标准**:
- frontmatter: name + description（含 ≥3 触发关键词）
- 行数: 应用层 ≤120 / 平台层 ≤150
- 场景→入口: ≥ 2 个场景有搜索关键词
- 上下游依赖: 标注了影响程度

> ⚠️ 所有业务规则已标记 🔴 TODO，待领域专家后续补充

使用 ask_questions 让用户确认：

• header: "质量确认"
• question: "请看评分卡，如有不满意的可以在输入框里告诉我哪个 Skill 需修改"
• 选项A（推荐）: "都没问题，继续"
• 选项B: "需要调整" (allowFreeformInput: true)

Step 2：注册类别 + 配置

2a. 编辑 skill_categories.json

多根工作区模式 — 本地编辑 data/skill_categories.json：

"{app}": {
  "display_name": "{app}",
  "prefixes": ["{app}-"],
  "description": "{AppName} 应用/平台",
  "default_selected": false
}

在 presets 中添加对应预设：

"{AppName}应用开发": ["platform", "{app}"]

纯目标项目模式 — 通过 MCP create_commit 的 search/replace 模式远程修改：

• 先 MCP get_file_content 读取当前 skill_categories.json 内容
• 用 search/replace 在 "categories" 和 "presets" 中各插入一条

2b. 验证 + 部署说明

执行 python -c "import json; ..." 验证 skill_categories.json 配置正确、{app}-* Skills 数量匹配。

多根工作区模式 — 部署到目标项目：使用 ask_questions 询问是否自动部署：

• header: "自动部署"
• question: "是否立即将 Skills 部署到目标项目？"
• 选项A（推荐）: "是，自动部署"
• 选项B: "否，我稍后手动运行 GUI"

如果选择自动部署，在工具项目根目录执行：

python scripts/deploy_skills.py --target-path "{target_project_root}" --categories platform,{app} --force

💡 其他开发者需各自运行 GUI 或 CLI 部署。

纯目标项目模式：Skill 已直接生成在 .github/skills/ 下，无需额外部署。

2c. 更新用户偏好（user_preferences.json）

读取 data/user_preferences.json，在 selected_skill_categories 数组中追加 "{app}"（如果不存在的话），确保 GUI 下次启动时默认勾选新应用类别。

🔴 检查点 2：交付确认

必须暂停，向用户展示以下交付清单：

## 📦 交付清单

**应用名**: {AppName}
**Skill 数量**: {N} 个模块

### 生成的文件

| 文件路径 | 行数 | 类型 |
|---------|------|------|
| `templates/skills/{app}-xxx-expert/SKILL.md` | ... | SKILL.md |
| `templates/skills/{app}-xxx-expert/references/xxx.md` | ... | reference |
| ... | | |

### 配置注册

| 配置文件 | 变更内容 |
|---------|---------|
| `data/skill_categories.json` | 新增 `{app}` 分类 + `"{AppName}应用开发"` 预设 |

### 部署方式
重启 VS Code 后，通过 `#{app}-xxx-expert` 调用。
每位开发者需各自运行 GUI 工具部署 Skill。

展示完清单后，必须使用 ask_questions 弹出两个交互选项：

选择 1 — PR 操作：

• header: "提交PR"
• question: "Skill 已生成完毕。是否自动创建 PR 并通知审阅人？"
• 选项A（推荐）: "创建 PR 并飞书通知审阅人"
• 选项B: "只创建 PR，不发通知"
• 选项C: "跳过，我手动处理"

选择 2 — PR 审阅人（仅选择 A/B 时展示）：

• header: "审阅人"
• question: "PR 审阅人（默认从 shared_config.json 读取）"
• 选项A（推荐）: "YourName (your.email@example.com)" — 从 shared_config.json 的 notification_recipients 动态读取
• allowFreeformInput: true — 用户可输入其他审阅人姓名或邮箱

⚠️ 禁止跳过此 ask_questions 步骤。展示文件清单 ≠ 交付确认完成，必须等用户通过交互选项选择后才算 CP2 完成。

A/B → Step 3 | C → 输出部署说明，结束

Step 3：[可选] 提交 PR + 飞书通知

📚 实现原理参考: read_file("references/pr-notification.md") — Step 3 执行前必须读取！

根据 Step 0-pre 选择的运行模式，执行对应的 PR 创建流程。 根据 CP2 的选择确定通知模式：选项 A → PR 并通知 | 选项 B → 仅 PR

3-local. 多根工作区模式：本地脚本

在工具项目根目录执行（通过 run_in_terminal）：

powershell -ExecutionPolicy Bypass -File scripts/create_skill_pr.ps1 `
    -AppName "{AppName}" -AppPrefix "{app}" -ModuleCount {N} `
    -Mode "{PRAndNotify|PROnly}"

脚本输出 ===RESULT_JSON_BEGIN===/===RESULT_JSON_END=== 之间的 JSON 摘要。 退出码: 0=全成功, 1=配置错, 2=Git 失败, 3=PR 失败, 4=部分成功。

3-remote. 纯目标项目模式：MCP 远程操作

使用 azureDevOpsHSW MCP server（工具仓库在 HSW Collection）：

1. 创建分支: MCP create_branch — repo AdvAppCommonKnowledge, source master, new skill/{app}-experts
2. 推送文件: MCP create_commit — 将本地 .github/skills/{app}-*-expert/ 内容推送到 templates/skills/{app}-*-expert/
   • 新文件用 --- /dev/null 格式的 unified diff
   • skill_categories.json 用 search/replace 模式修改
3. 创建 PR: MCP create_pull_request — reviewers 从 CP2 用户选择获取
4. 飞书通知（如选择 A）: 通过飞书 MCP 或 create_skill_pr.ps1 的飞书 API 发送卡片消息

🔴 任何失败都不阻断，降级为提示用户手动处理。详见 references/pr-notification.md 中的错误处理表。

🔴 检查点 3：最终交付确认

展示最终交付结果：Skill 文件列表 + PR 链接 + 飞书通知状态 + 后续事项（业务规则 TODO、等待审阅、GUI 部署）。

进度模板

每次向用户展示消息时，在开头显示当前进度：

📋 Skill 向导 — {AppName}（{层级}）
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Step 0: 环境 + 信息收集
✅ CP0: 模块清单确认 (用户已确认)
⭕ Step 1: 分批研究 + 生成 (批次 2/4, 已完成 8/20)
⬜ CP1: 生成质量确认
⬜ Step 2: 注册 + 配置
⬜ CP2: 交付确认（含 PR 选择）
⬜ Step 3: 提交 PR + 飞书通知
⬜ CP3: 最终交付确认
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

状态图标: ✅ 完成 | ⭕ 进行中 | ⬜ 未开始

错误处理

参考文件

• 统一模版: read_file("templates/skills/_templates/module-expert-skill.md") — Step 1 前读取（纯目标项目模式用 MCP get_file_content）
• 质量标准: read_file("references/details.md")
• PR + 通知: read_file("references/pr-notification.md") — Step 3 前必须读取
• 格式参考: 任意 templates/skills/app-*-expert/SKILL.md（应用层）或 {{PLATFORM_PREFIX}}-*-expert/SKILL.md（平台层）