能力开发

能力把业务 API 转换为智能体可理解、可鉴权、可确认和可审计的动作。

能力分类

• 只读能力：查询候选项、本人数据、状态和统计指标。
• 写能力：创建、修改或执行某项业务动作。
• 辅助能力：文件解析、重复检查、格式转换和状态查询。

设计步骤

1. 定义明确、单一的业务语义。
2. 设计稳定的结构化请求和响应。
3. 指定连接器、接口路径和鉴权方式。
4. 配置权限码、风险等级和确认策略。
5. 定义业务错误与面向用户的说明。
6. 为写操作设计幂等键和结果查询。
7. 使用普通员工进行越权和重复调用测试。

请求设计

• 字段名称表达业务含义，不暴露数据库列名。
• 枚举同时提供代码和中文名称。
• 日期、金额和 ID 使用明确类型。
• 从登录态可以确定的租户和用户，不接受模型自由传入。
• 关键附件使用可信文件引用或上下文 ID。

响应设计

只读能力返回结构化数据、口径和查询时间；写能力返回业务主键、单号、状态、详情路径和是否复用已有结果。

错误设计

错误应区分：参数缺失、无权限、状态不允许、数据失效、重复业务、外部服务异常和系统异常。不要把所有失败都包装为“模型调用失败”。

测试清单

• 正常参数成功。
• 必填项缺失失败。
• 无权限用户失败。
• 其他租户数据失败。
• 业务状态不允许失败。
• 超时重试不产生重复数据。
• 中途异常完整回滚。