reachai-capability-retrofit

1# ReachAI 业务能力改造
2 
3## 你在做什么
4 
5业务系统已经接入 ReachAI（装了 SDK、能心跳）。开发者想让 AI 多办几件事，比如“查应收款”“新建退货单”。你的工作是：读代码 → 列候选 → 等开发者勾选 → 给选中的方法加能力声明 → 编译测试 → 触发一次 SDK 同步 → 交报告。能力进入 ReachAI 后，由人在“能力变化评审”里接受，再发布给员工的 AI 工具。你不能替人评审或发布。
6 
7所有写进代码和 ReachAI 的名称、说明默认用清晰的简体中文。`name`、路径、枚举等技术标识保持英文。
8 
9## 任务通道
10 
11这个 Skill 总在一个 `CAPABILITY_RETROFIT` 任务里使用，任务有两种接法，选你手上有的那种：
12 
131. **平台 MCP（推荐）**：开发者的 AI 工具已经用自己的身份连上 ReachAI 平台 MCP。
14   - 没有任务时用 `reachai_retrofit_start`（projectCode、objective）新建，它会把任务直接领取到当前连接。
15   - 读上下文：`reachai_ai_coding_task_context`；进度：`reachai_ai_coding_task_event`；提问/读回答：`reachai_retrofit_propose`、`reachai_ai_coding_task_questions`；SDK 同步：`reachai_ai_coding_task_verify`（verificationKey=SDK_SYNC）；交报告：`reachai_ai_coding_task_artifact`。
162. **一次性交接**：页面给了激活码和 PowerShell/Bootstrap。激活后用任务令牌调用 `/api/ai-coding/tasks/{taskId}/**`（context、events、questions、verifications/SDK_SYNC、artifacts）。
17 
18不管哪种，先读任务上下文（`context`），里面有项目、目标、语言、候选清单格式、声明写法、报告契约和 Skill 地址。不要猜接口和字段。不打印、不提交任何密钥、激活码、任务令牌。
19 
20## 步骤
21 
22### 1. 盘点（只读）
23 
24- 看清语言、框架、模块结构，找出已有的 ReachAI 能力声明，已经开放的不要再列。
25- 按目标找业务方法。优先 Service 层（已有事务和权限），没有合适的再看 Controller。
26- 每个候选写清：`candidateKey`（稳定标识，如 `erp.receivable.page`）、`title`（中文名）、`description`、`sideEffect`（READ / WRITE / IRREVERSIBLE）、`sourceFile`、`symbol`（类#方法）、对应 HTTP 方法和路径（有的话）、`reason`（为什么适合）、`risk`（风险提示）、`recommended`。
27- 一次最多 20 个；目标很大时先给最有用的 20 个，在 summary 里说明还有哪些可以下一批做。
28- 不要列：登录/注册/密码、文件上传下载、导入导出、批量删除、系统配置、定时任务、框架或第三方组件自带的接口、只给管理员用的危险操作。
29- 会改数据的必须标 WRITE；删除、作废、付款、发货等无法撤回的标 IRREVERSIBLE。拿不准就标高一级。
30…