Agent/examples/mode_workflow/docs/knowledge_ingest_api.md

知识导入接口(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)

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

失败响应

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

curl 示例

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