# 泛微技能检测工具集成

生成或更新业务模块 Skill 后，必须用泛微技能检测工具做静态质检。目标是让产物同时符合 WorkBuddy 平台规范、泛微专项安全合规要求和通用质量规则。

## 检测工具来源

检测工具不是生成出的业务 Skill 的一部分，但它是 `weaver-work-cli` 的随包依赖。优先使用稳定入口：

```text
weaver-work-cli skills validate <skill-dir-or-zip> --json --no-html
```

运行时按以下顺序定位：

1. `weaver-work-cli` 包内的 `tools/weaver-skill-detector-1.0.13`。
2. 用户本轮明确提供的检测工具目录，通过 `weaver-work-cli skills validate --detector-dir DETECTOR_DIR ...` 使用。
3. 当前工作区中与 `weaver-work-cli` 同级的 `weaver-skill-detector-1.0.13` 目录仅作为旧版本地开发兜底；正常拉取或安装 `weaver-work-cli` 后不应依赖它。
4. 如果以上都不可用，说明当前安装包不完整或向用户询问检测工具目录，不要自行联网下载或改用其它检测器。

不要把本机个人绝对路径写入生成出的 Skill 或 `source-manifest.json`；需要记录检测器时只写工具名、版本号或用户提供的相对位置。

## 质检确认门槛

每次 Skill Maker 创建或更新 `skills/weaver-e10-<module>` 后，在安装、打包发布或最终宣布完成前，必须明确询问用户是否现在进行 Skill 质检。推荐提问：

```text
业务模块 Skill 已生成/更新。Skill 质检是必需步骤，是否现在使用泛微技能检测工具进行质检？
```

用户明确同意后，按上面的检测工具来源定位 detector 并运行检测。用户拒绝、未回复、要求稍后再做，或当前环境没有可用检测器且用户未提供目录时，停止在“待质检”状态：可以报告生成目录、待运行命令和缺少的检测器信息，但不得安装、发布、声明完成、或把该 Skill 标记为通过检测。

检测器的 zip 输入分支使用新版 Python 标准库参数。目录检测可作为本地保底；需要检测 zip 时，优先使用 WorkBuddy 托管 Python 或 Python 3.11+。如果当前环境只有旧版 Python 且 zip 检测报运行时错误，先向用户确认可用解释器路径，不要把 zip 检测失败误判为 Skill 内容不合格。

检测命令必须同时给出 Windows PowerShell 与 macOS/Linux（bash/zsh）示例。Windows 优先使用 `py -3` 或 `py -3.11`；macOS/Linux 使用 `python3` 或用户确认的 Python 路径。Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。不要把个人绝对路径写入生成产物。

## 必须满足的 frontmatter

默认 `weaver` 模式下，生成的 `SKILL.md` frontmatter 必须使用顶层字段，不得使用 `metadata:` 嵌套。至少包含：

```yaml
name: weaver-e10-<module>
display_name: 泛微<中文展示名>
display_name_en: Weaver <English Name>
description: "<200 字内的一句话中文概述，说明能力和触发场景>"
description_zh: "<中文简介>"
description_en: "<English summary>"
version: 1.0.0
author: 泛微网络科技股份有限公司
agent_created: true
requires:
  bins: ["weaver-work-cli"]
cliHelp: "weaver-work-cli <command> --help"
```

`name` 只能使用小写字母、数字和连字符，必须以 `weaver` 开头，目录名必须与 `name` 一致。`display_name` 必须以「泛微」开头，建议不超过 20 字。`description` 保持短句，详细介绍放入 `description_zh` 和 `description_en`。

## 打包与内容约束

生成的 Skill 需要满足这些硬约束：

- 入口文件名精确为 `SKILL.md`。
- 目录层级不超过两级：根目录文件、二级目录文件；不要出现 `references/topic/file.md`。
- 文件总数不超过 300。
- 只包含纯文本文件；不要把图片、PDF、压缩包或构建产物放进 Skill。
- 所有 JSON、YAML、TOML 文件必须可解析。
- `SKILL.md` 中写成 Markdown 链接或反引号路径的 `references/...` 文件必须真实存在于包内。
- 不写默认登录地址、真实 IP、凭证、个人路径、IDE 配置目录或平台虚假技术承诺。
- 默认按 `weaver` 模式检测；只有用户明确说要上架千问办公或 QwenWork，才加 `--platform qwenwork`。

## 检测命令

优先检测生成出的 Skill 目录：

Windows PowerShell：

```powershell
weaver-work-cli skills validate GENERATED_SKILL_DIR --json --no-html
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills validate GENERATED_SKILL_DIR --json --no-html
```

如果还生成了发布 zip，再用 Python 3.11+ 检测 zip：

Windows PowerShell：

```powershell
weaver-work-cli skills validate GENERATED_SKILL_ZIP --json --no-html --python "C:\Path\To\Python311\python.exe"
```

macOS/Linux（bash/zsh）：

```bash
weaver-work-cli skills validate GENERATED_SKILL_ZIP --json --no-html --python python3.11
```

退出码含义：

- `0`：通过或仅有警告。若有 WARN，发布前尽量修复；无法修复时向用户说明剩余风险。
- `1`：不通过。必须先修复 BLOCK/FAIL 项，再重新检测。
- `2`：输入非法。先修正路径或包结构。

不要主动使用 `--market-live`，除非用户明确要求联网核查市场可达性。

## 失败处理

检测失败时，按报告中的规则编号修复：

- frontmatter 缺字段或存在 `metadata:`：提升为顶层字段并补齐展示名、版本、作者、英文描述。
- 引用文件不存在：把 reference 补进包内，或移除入口里的包外 Markdown 链接。
- 目录层级过深：拍平 `references/` 下的子目录。
- 二进制或隐藏文件：从 Skill 包移除。
- 默认地址、凭证或真实 IP：改为用户显式提供、命名凭据或占位说明。

修复后必须重新运行检测。最终回复中说明检测结果、是否还有 WARN，以及使用的检测器版本。