# 知识导入接口(knowledge ingest)

> 来源:`stages/import_process_knowledge.py`(`build_payload` + `ingest_one`)
> 用途:把 DB 中「已采纳」的工序解构(mode_process)逐条写入知识库。

## 基本信息

| 项 | 值 |
|----|----|
| Method | `POST` |
| URL | `{api_url}/api/v1/knowledge/ingest` |
| 默认 `api_url` | `http://47.236.83.130:8001` |
| 完整默认地址 | `http://47.236.83.130:8001/api/v1/knowledge/ingest` |
| Content-Type | `application/json` |
| 超时 | 30s |
| 成功状态码 | `201 Created` |

**一条 procedure(工序)= 一次请求 = 一条知识。** 同一个 case 下有 N 个工序就调用 N 次。

## 请求头

```
Content-Type: application/json
```

## 请求体字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `source` | object | 是 | 来源帖子信息 |
| `source.id` | string | 是 | 来源主键,直接取 DB 的 `case_id` |
| `source.source_type` | string | 是 | 固定 `"post"` |
| `source.title` | string \| null | 是 | 来源标题,空则 `null` |
| `source.author` | string \| null | 是 | 来源作者,空则 `null` |
| `source.source_metadata` | object | 是 | 来源附加元信息(见下) |
| `source.source_metadata.platform` | string | 是 | 平台,空则 `""` |
| `source.source_metadata.date` | string | 是 | 发布日期,空则 `""` |
| `source.source_metadata.url` | string \| null | 是 | 原文链接,空则 `null` |
| `source.source_metadata.excerpt` | string | 是 | 摘要,截断到 500 字符 |
| `source.source_metadata.procedure_id` | string | 是 | 工序 id,空则 `""` |
| `source.source_metadata.procedure_name` | string | 是 | 工序名,空则 `""` |
| `title` | string | 是 | 知识标题,截断到 512 字符。取工序名;为空回退 `"来源标题 — 工序N"`,再空则 `"工序N"` |
| `content` | string | 是 | 整个 procedure 对象序列化后的 JSON 字符串(`ensure_ascii=False`) |
| `dim_attributes` | string[] | 是 | 固定 `["how工序"]` |
| `dim_creations` | string[] | 是 | 固定 `["制作"]` |
| `scopes` | object[] | 否 | 作用域;为空时**不带该字段** |
| `scopes[].scope_type` | string | - | `"substance"` 或 `"form"` |
| `scopes[].value` | string | - | 由各步骤 `substance`/`form` 按顿号拆分去重 |
| `custom_ext` | object[] | 否 | 自定义扩展;为空时**不带该字段** |
| `custom_ext[].key` | string | - | `"作用"`(effect)/ `"动作"`(action)/ `"工具"`(via,`human` 除外) |
| `custom_ext[].type` | string | - | 固定 `"str"` |
| `custom_ext[].value` | string | - | 对应步骤字段按顿号拆分去重 |

> 注:`scopes` 与 `custom_ext` 仅在非空时才会出现在请求体里(脚本里条件添加)。

## 成功响应(201)

```json
{
  "knowledge_id": "<生成的知识ID>"
}
```

## 失败响应

| 情况 | 处理 |
|------|------|
| 非 201 | 读取响应 JSON 的 `detail` 字段(无则取 `text[:300]`)作为错误信息 |
| 超时(30s) | 记为失败,信息 `"超时(30s)"` |
| 网络异常 | 记为失败,信息为异常字符串 |

## curl 示例

```bash
curl -X POST http://47.236.83.130:8001/api/v1/knowledge/ingest \
  -H "Content-Type: application/json" \
  -d @knowledge_ingest_payload.json
```