# weaver-work-cli 业务 Skill 风格

`weaver-work-cli` 的业务 Skill 借鉴飞书 CLI 的组织方式，但有自己的固定边界：入口做路由，reference 写细节，共享规则集中在 `weaver-e10-shared`，业务调用必须走 `weaver-work-cli`。使用 Skill Maker 生成新业务模块时，必须同步生成或更新对应 `src/shortcuts/<module>` CLI，并让 Skill 只引用已实现的 operation。

## 目录结构

Skill 目录名用 `<skill>`（业务系统名/拼音），CLI 源码目录用 `<command>`（英文动作名）：

```text
skills/weaver-e10-<skill>/
  SKILL.md
  references/
    <operation-or-topic>.md
    source-manifest.json
skill-template/product.json
```

仓库内还需要同步：

```text
src/shortcuts/<command>/
docs/<command>.md
skill-template/business-info.json      # key = weaver-e10-<skill>
skill-template/domains/<skill>.md
```

必要时更新文档索引：

```text
docs/_catalog.md
docs/SKILL.md
README.md
```

## 入口 SKILL.md

入口文件保持轻量，必须包含：

- frontmatter：使用检测工具认可的顶层字段，禁止 `metadata:` 嵌套。
- CRITICAL：要求先读 `../weaver-e10-shared/SKILL.md`；若共享规则不存在、CLI 未安装或读取失败，必须调用宿主提供的提问/确认弹框说明缺失项与补齐计划，并在确认信息中原样展示 `npm install -g weaver-work-cli`（仅缺 CLI 时执行）和 `weaver-work-cli skills install shared --target-dir <当前Agent的Skills目录>`；用户明确确认后由 Agent 直接代为按顺序执行且每条仅执行一次，不得要求用户手动执行；安装或读取失败时停止。业务模块安装前版本检查统一写在 shared Skill 中，不在各业务入口重复。
- 路由优先级：先判断是否属于该业务模块，再选 operation。
- 高优先级语义：业务对象、别名、关键字段、常见用户说法。
- 命令表：用户意图、CLI operation、按需读取的 reference。
- 处理链：常见多步流程，尤其是文件处理和写操作确认。
- 执行原则：最小必要查询、大结果摘要、错误语义驱动、文件处理确认。
- 写操作失败决策树：涉及写操作时必须写；纯只读模块可写明没有高风险写链。
- 不在范围：禁止绕过 CLI、未暴露 operation、未自动化能力。

入口不要承载完整接口手册，也不要把 shared 规则全文复制一遍。基于 Git 源码更新时，也不要把 diff、提交日志或大段源码复制进 `SKILL.md`；入口只记录路由和高优先级业务语义，具体字段、命令、风险和失败处理拆到 `references/`，源资料边界、版本信息和覆盖状态记录到 `references/source-manifest.json`。入口轻量不等于业务压缩；凡会影响执行的规则必须能在 schema、handler、reference、测试或禁用边界中找到。

frontmatter 推荐模板：

```yaml
name: weaver-e10-<skill>
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"
```

这些字段需通过泛微技能检测工具默认 `weaver` 模式。`display_name` 必须以「泛微」开头，`version` 必须是三段数字 SemVer，目录名必须等于 `name`（即 `weaver-e10-<skill>`，`<skill>` 用业务系统名/拼音，如 `yepiaotong`）。业务模块 Skill 的 `cliHelp` 指向 `weaver-work-cli <command> --help`，其中 `<command>` 是独立的 CLI 命令后缀（如 `invoice`），可与 `<skill>` 不同。

## Reference 写法

每个 reference 只服务一个明确意图或一小组强相关 operation。推荐结构：

```markdown
# <业务动作>

## 何时使用

## 输入要点

## 命令

Windows PowerShell：

\```powershell
weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"key":"value"}'
\```

macOS/Linux（bash/zsh）：

\```bash
weaver-work-cli --json MODULE_COMMAND run MODULE_NAME.operation --input-json '{"key":"value"}'
\```

## 输出处理

## 注意

## 失败处理
```

命令示例、提示词和 docs 必须同时兼容 Windows 和 macOS/Linux。凡涉及 JSON 输入、用户目录、路径分隔符、Python 启动器、文件删除、目录查看或文件比对，必须同时给 Windows PowerShell 与 macOS/Linux（bash/zsh）两套示例；Agent 先根据当前系统和 shell 选择对应示例，不确定时用 `node -p "process.platform"` 判断。简单 JSON 优先使用 `--input-json '<json>'`；复杂 JSON 可保存为 UTF-8 文件后按平台传给 `--input`。Windows/PowerShell 示例不要使用 `printf`、`$HOME/...`、`~/...`、bash 反斜杠续行、`rm/ls/diff/python3` 等 Unix-only 写法。

Reference 要业务保真，禁止把源文档压缩成泛泛说明。写法要求：

- 源资料里的字段表、枚举、状态码、固定参数、分页/排序口径、权限前置、ID 解析、流程分支、错误码、返回结构、示例和禁用能力，只要影响执行，就必须在 reference 或 schema 中可查。
- 长文档按业务对象、operation、源文档标题或使用场景拆成多个 reference；不要为了让单个文件变短而删掉业务分支。
- 可以重写措辞、合并重复内容、删除无关营销/截图描述和敏感值，但不能丢失可执行约束。无法迁移的内容要转入“待确认”或“禁用边界”，并说明缺少接口路径、字段、权限、回查、幂等或确认条件中的哪一项。
- 对复杂 operation，reference 至少保留一个小而完整的 JSON 示例；示例优先来自 manifest `inputExamples`。源资料已有样例时标注为源资料样例，源资料没有样例但字段完整时可以标注为 `synthetic` 推导样例，源资料没有样例且参数事实不足时只登记 `missingExamples` 和待补参数，不要编造可运行入参。
- Reference 命令中的 `--input-json` 字段必须与 `inputSchema.properties`、`deprecatedInputAliases` 和 manifest `inputExamples` 对齐。若 reference 为了说明占位而使用不可解析片段，必须同时给出字段来源和补充方式，不能让 Agent 通过反复试错推测格式。

缺少参数事实时，reference 只说明待补项和阻断原因，具体结构化清单写入 `source-manifest.json` 的参数覆盖矩阵。状态使用 `converted`、`fixed`、`derived`、`deprecatedAlias`、`withheld`、`needs-confirmation`、`not-applicable`；最终交付时必须把 `needs-confirmation` 参数和 `missingExamples` 单独列给用户后续补充。

涉及附件、图片、本地文件、远程 URL、OCR、导入或解析时，`## 注意` 必须说明用户需先确认文件内容可能进入大模型上下文，也可能发送到业务系统或解析服务。

写入、删除、导入、更新等高风险操作必须使用 CLI 暴露的确认链。若 schema 中是 `prepare/apply`，reference 必须写清：

1. `prepare` 只预览和生成 continuation。
2. 向用户摘要目标、差异、风险和 continuation 绑定含义。
3. 用户明确确认后才调用 `apply`。
4. `apply` 不可盲目重试；遇到不确定结果先停止，再做一次只读回查。

## product.json

源码只维护 `skill-template/product.json`，`skills/` 根目录和业务 Skill 目录下都不要放重复副本。打包 ZIP 或执行 `skills install` 时，脚本会给每个 Skill 产物根目录注入完整 `product.json`；`productVersion`、`packageName` 和 Node engine 来自 `package.json`。

```json
{
  "schemaVersion": 1,
  "product": "weaver-work-cli",
  "command": "weaver-work-cli"
}
```

## business-info 和 domain

`skill-template/business-info.json` 的 key 必须与 `skills/` 下的目录名一致，value 是用于聚合路由的关键词数组。关键词只放高信号业务词，不放泛词。

`skill-template/domains/<module>.md` 用一小段话说明该业务域的 reference 拆分、路由语义和关键安全边界。它必须提到 `references/`，以满足仓库结构约定。

## 常见禁止项

- 禁止要求 Agent 读取、复制或解析认证目录、Cookie、ETEAMSID、业务 Token。
- 禁止把源文档里的原始接口路径当成 Agent 可直接调用的路径。
- 禁止把未暴露在 `schema` 中的能力写成可用 operation；先按 CLI 规范实现并测试。
- 禁止复制大段接口文档或代码进 `SKILL.md`。
- 禁止把多份源 MD 压缩成一个笼统能力概述；业务细节必须拆进 reference/schema/handler/test/禁用边界。
- 禁止新增安装后会丢失的依赖脚本；当前 Skill 安装和 ZIP 打包会过滤 `scripts/` 与 `assets/`。
- 禁止生成会被检测工具阻断的结构：`metadata:` 嵌套、过深目录、缺失 reference、二进制文件、默认系统地址、真实 IP 或硬编码凭证。