aps-agent/docs/spec/capability-description.md

能力描述规范（一页）

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

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

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 示例

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