# 能力描述规范（一页）

> 模型选工具靠的是能力描述，不是猜。描述写不好，等于意图识别失败——这个锅不在引擎，在平台。

**一句话原则**：能力描述是写给模型看的接口文档，不是写给人看的注释。

## 1 七要素

| # | 要素 | 要求 |
| --- | --- | --- |
| 1 | 能力 id | 小写点分：`<系统>.<资源>.<动作>`，如 `aps.schedule.preview`。禁用 `do` / `handle` / `process` 这类含糊动词 |
| 2 | 一句话用途 | 「做什么 + 对什么对象」，40 字以内 |
| 3 | 何时不用 | 反例优先。同族能力之间必须写清分界（试排 / 正式排产 / 重排） |
| 4 | 参数 schema | 每个参数给类型、必填、枚举、单位、默认值。单位写进描述（分钟 / 台 / 件） |
| 5 | 业务黑话与同义词 | 现场怎么叫就写进去：换型、插单、交期承诺、能力池、抛料、试排 |
| 6 | 示例 | 一到两条自然语言问法 + 该调用什么 |
| 7 | 副作用与影响面 | 只读 / 草稿 / 写；影响哪些数据、能否回滚。写操作必须能被确认卡压成参数摘要 |

## 2 反例对照

| 反例 | 问题 | 改法 |
| --- | --- | --- |
| `doSchedule` | 动词含糊、无对象 | `aps.schedule.preview` |
| 「处理数据」 | 没说做什么 | 「按当前项目数据试排一版方案，不发布到 APS」 |
| 不写同义词 | 用户说「换型」，模型不认识 | 描述里带上 换型 / setup / 换模 |
| 枚举不给、默认值不写 | 模型乱填 mode | 枚举锁死 + 明确默认值 |
| 只说正例 | 模型不知道边界 | 「只读预览用这个；要落库请用 `aps.schedule.publish`」 |

## 3 近义能力的裁决规则

| 情况 | 规则 |
| --- | --- |
| 同一动作多个系统都有（查库存 ERP / EMS） | 不给模型二选一；要么提供一个检索类能力由用户选，要么按项目配置固定数据源 |
| APS 内部同族动作（试排 / 正式排产 / 重排） | 名称含区别词，描述第一句写分界 |
| 读与写成对出现 | 成对命名（`preview` / `publish`），描述互相指路 |

## 4 提交检查项

Provider 作者自检，评审逐条打勾：

1. id 符合 `<系统>.<资源>.<动作>`，无含糊动词
2. 一句话用途 ≤ 40 字，含对象
3. 写了「何时不用」，同族能力有分界
4. 参数都有类型、必填、枚举、单位、默认值
5. 含业务黑话与同义词
6. 至少一条示例问法
7. 副作用与影响面写清，写操作可压成参数摘要

## 5 示例

```yaml
id: aps.schedule.preview
用途: 按当前项目的订单与产能试排一版方案，只出结果不发布
何时不用: 要落库生效请用 aps.schedule.publish；只想看现有方案用 aps.schedule.query
同义词: 试排、排一下、跑一版、预排、模拟排产
参数:
  project: 项目 id，必填，默认当前项目
  horizon_days: 排产跨度，整数天，默认 30
  strategy: 规则枚举 rule | cpsat | hybrid，默认项目配置
示例: 「按新订单试排一版看看」→ aps.schedule.preview
副作用: 只读；不写 APS，不产生版本
```

## 6 责任与落地

- Provider 作者写，平台评审；从 A5 首个真实 Provider 起强制执行
- 能力描述随 Provider 契约一起入库，纳入 CI 检查（七要素缺项即失败）
- 规范本身随 Provider 契约文档同步演进，位置：`docs/spec/capability-description.md`