# 自提升 SDK

让应用与语义层在使用中**持续变好**：把反馈、操作、使用、数据画像，加上你手里的文件、技能（SKILL.md）、对话摘录整合起来，提出具体的改进提案；语义类的提案一键应用成新的语义版本，应用类的交给开发者 / 智能体改代码发新版本——被采纳的反馈自动标记为已处理，闭环。

```js
import { improve } from "/developer/sdk/v1/aidc.js";
```

只给本公司开发者（开发者 Key、应用里的 developer 访客）。

## 一轮迭代

```js
// 1. 看证据：使用、反馈、操作、错误、语义定义与数据画像（空值率、被人改过几次、样例值）
const ev = await improve.evidence({ app: "tj8100-live", days: 30 });

// 2. 让模型起草提案（按公司计费；材料由你带来）
const { proposals } = await improve.suggest({
  app: "tj8100-live",
  files: [{ name: "生产日报口径.md", text: reportSpec }],
  skills: [{ name: "SKILL.md", text: skillText }],
  conversations: [{ name: "班组长群 09-26", text: chatExcerpt }],
});

// 3. 决定、应用
await improve.decide(proposals[0].id, "accept");
const { appliedRef } = await improve.apply(proposals[0].id);   // 语义类 → "v5"（自动发了新语义版本）
await improve.apply(appProposal.id, { version: "1.2.0" });     // 应用类 → 回填落地它的应用版本号
```

也可以自己（或你的智能体）直接提：

```js
await improve.propose({
  target: "semantic",
  title: "说清楚「累计合格」的口径",
  rationale: "三条反馈都在问是当班还是当天",
  patch: [
    { op: "describe", entity: "production.order_line", column: "ok", description: "当天到此刻的累计合格件数（ZPP015 口径）" },
    { op: "synonyms", entity: "production.order_line", column: "ok", add: ["合格数", "良品数"] },
  ],
  evidence: [{ kind: "feedback", ref: feedbackId, excerpt: "「累计合格」是当班还是当天？" }],
  feedback: [feedbackId],        // 这些反馈 → 已排期；应用后 → 已处理
});
```

## 语义补丁只做加法

| op | 做什么 |
| --- | --- |
| `describe` | 改对象类型 / 属性的显示名、说明、单位 |
| `synonyms` | 加同义词（智能体按业务说法找到属性） |
| `addColumn` | 加一个只在语义层维护的新属性（备注、负责人…） |
| `addEnumValues` | 给枚举加值 |
| `addAction` | 加一个新 Action |

删属性、改类型、改主键这类破坏性变更不走自提升，由开发者手动定义、确认影响后发布。应用补丁前会做引用闭合校验，通不过整条提案不生效。

## 让智能体自己跑这一轮

智能体（带开发者 Key）定期：`aidc improve evidence` → 结合自己的记忆与对话 → `aidc improve propose --spec …` 或 `aidc improve suggest` → 人在 Developer 里看提案、`aidc improve accept` → `aidc improve apply`。应用类提案由智能体改代码、`aidc app deploy` 进测试、人确认后 `aidc app publish`，最后 `aidc improve apply <id> --version 1.2.0`。

```bash
aidc improve evidence tj8100-live
aidc improve suggest tj8100-live --file 生产日报口径.md --skill SKILL.md --conversation 群聊.txt
aidc improve proposals --status open
aidc improve accept <id> && aidc improve apply <id>
```

## API

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| GET | `/api/v1/developer/improve/{命名空间}/evidence` | 证据 |
| POST | `/api/v1/developer/improve/{命名空间}/suggest` | 模型起草提案 |
| GET / POST | `/api/v1/developer/improve/{命名空间}/proposals` | 提案列表 / 新提案 |
| PATCH | `/api/v1/developer/improve/{命名空间}/proposals/{id}` | 采纳 / 拒绝 |
| POST | `/api/v1/developer/improve/{命名空间}/proposals/{id}/apply` | 应用 |