CastrelCastrel AI
开放平台

知识管理 API

通过 PAT 认证，编程管理知识库。

面向 PAT 用户的 Knowledge API 接口。鉴权方式为 Authorization: Bearer <pat_token>，基础路径为 /personal/v1/knowledge/。

接口列表

方法路径说明
POST/personal/v1/knowledge/list获取知识列表
GET/personal/v1/knowledge/{id}获取知识详情
POST/personal/v1/knowledge/create创建知识
POST/personal/v1/knowledge/update更新知识
POST/personal/v1/knowledge/upsert保存知识（创建或更新）

通用响应结构

{
  "code": 200,
  "message": "common.success",
  "data": { ... }
}
字段类型说明
codeint状态码，200 表示成功
messagestring国际化消息 key
dataobject/null响应数据

列表接口 data 结构（PaginationData）：

字段类型说明
pageobject/null分页信息，不传分页参数时为 null
page.totalint总记录数
page.page_numint当前页码（从 1 开始）
page.page_sizeint每页记录数
itemsarray知识列表 KnowledgeResponse[]

知识对象字段（KnowledgeResponse）

字段类型说明
idint系统自增主键
namestring知识名称
typestring知识类型：default（简单知识）/ document（文档知识）
triggerstring触发条件类型（见下方枚举）
trigger_configobject触发条件配置（根据 trigger 不同而不同）
descriptionstring/null知识描述
dataobject知识内容数据（根据 type 不同而不同）
labelsobject/null标签键值对，例如 {"env": "prod"}
metadataobject/null元数据信息
application_idstring/null从 trigger_config.application_id 派生的兼容字段
application_namestring/null应用触发配置对应的显示名称
workspace_idstring/null工作空间 ID
is_publicbool是否公共知识
is_readonlybool是否只读
is_appliedbool当前 workspace 是否已订阅
sourcestring知识来源，默认 "custom"
forked_fromint/nullFork 来源知识 ID，NULL 表示原创
created_atint创建时间戳（毫秒）
updated_atint更新时间戳（毫秒）

Trigger 枚举（KnowledgeTrigger）

值说明trigger_config 要求
smart智能触发不应含 application_id 之外的配置参数
always始终触发不应含 application_id 之外的配置参数
application应用触发必须提供 application_id
service服务触发必须提供 service_id
infrastructure基础设施触发必须提供 infrastructure_id
connector连接器触发必须提供 connector_id
bridge_node桥接节点触发必须提供 bridge_node_client_id
proxy代理节点触发必须提供 proxy_id
alert告警触发必须提供非空 match_patterns 数组

KnowledgeType 枚举

值说明data 要求
default简单知识必须提供 content 字段
document文档知识必须提供 document_content 或 document_id 字段

FilterOperator 枚举

值说明
eq精确匹配
includeAny包含任一（OR）
excludeAny排除任一
like模糊匹配

接口详情

获取知识列表

POST /personal/v1/knowledge/list
Authorization: Bearer <pat_token>
Content-Type: application/json

请求体：

字段类型必填说明
filtersobject否过滤条件
filters.nameFilterValue否按知识名称过滤
filters.typeFilterValue否按知识类型过滤
filters.triggerFilterValue否按触发条件过滤
filters.labelsLabelFilter否按标签过滤
filters.application_idFilterValue否按 application_id 过滤
filters.service_idFilterValue否按 service_id 过滤
filters.infrastructure_idFilterValue否按 infrastructure_id 过滤
filters.connector_idFilterValue否按 connector_id 过滤
filters.bridge_node_client_idFilterValue否按 bridge_node_client_id 过滤
filters.proxy_idFilterValue否按 proxy_id 过滤
filters.workspace_idFilterValue否按 workspace_id 过滤
filters.is_publicFilterValue否是否公共知识
filters.is_readonlyFilterValue否是否只读
filters.sourceFilterValue否按知识来源过滤
sortobject否排序配置
sort.order_bystring是排序字段
sort.orderstring是排序方向：desc, asc
pageobject否分页配置
page.page_noint否页码，从 1 开始，默认 1
page.page_sizeint否每页记录数，1~200，默认 20
include_publicbool否是否包含公共知识，默认 false
context_visible_onlybool否是否仅使用 Context 可见集合，默认 true

FilterValue 结构：

字段类型必填说明
operatorstring是过滤操作符：eq, includeAny, excludeAny, like
valuesarray否用于数组操作的值列表
valuestring否用于单值操作的值

LabelFilter 结构：

字段类型必填说明
operatorstring是过滤操作符
valuesarray是标签过滤项列表
values.keystring是标签 key
values.valuestring/null否标签 value，为空表示只匹配 key

curl 示例：

# 查询列表（不带过滤）
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/list' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": {
      "page_no": 1,
      "page_size": 20
    },
    "sort": {
      "order_by": "created_at",
      "order": "desc"
    }
  }' | jq .

# 按名称模糊查询
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/list' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "name": {
        "operator": "like",
        "value": "告警"
      }
    },
    "page": {
      "page_no": 1,
      "page_size": 20
    }
  }' | jq .

# 按 trigger 类型过滤
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/list' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "trigger": {
        "operator": "eq",
        "value": "alert"
      }
    },
    "page": {
      "page_no": 1,
      "page_size": 50
    }
  }' | jq .

获取知识详情

GET /personal/v1/knowledge/{id}
Authorization: Bearer <pat_token>

路径参数：

参数类型说明
idint知识系统主键 ID

curl 示例：

curl -s 'http://localhost:8000/personal/v1/knowledge/1' \
  -H 'Authorization: Bearer <pat_token>' | jq .

响应示例：

{
  "code": 200,
  "message": "common.success",
  "data": {
    "id": 1,
    "name": "MySQL 连接数告警处理",
    "type": "default",
    "trigger": "alert",
    "trigger_config": {
      "match_patterns": ["MySQL 连接数"]
    },
    "description": "MySQL 连接数超限后的标准处理流程",
    "data": {
      "content": "1. 登录 MySQL 执行 SHOW PROCESSLIST\n2. 确认长事务或慢查询\n3. kill 阻塞会话"
    },
    "labels": {"env": "prod"},
    "application_id": null,
    "application_name": null,
    "workspace_id": "wks-xxx",
    "is_public": false,
    "is_readonly": false,
    "is_applied": false,
    "source": "custom",
    "forked_from": null,
    "created_at": 1717000000000,
    "updated_at": 1717000000000
  }
}

创建知识

POST /personal/v1/knowledge/create
Authorization: Bearer <pat_token>
Content-Type: application/json

请求体：

字段类型必填说明
namestring是知识名称，最长 255 字符，不能为空或纯空白
typestring是知识类型：default 或 document
triggerstring是触发条件类型
trigger_configobject是触发配置，需与 trigger 类型匹配
descriptionstring/null否知识描述
dataobject是知识内容数据
labelsobject/null否标签键值对，key 不能为空
metadataobject/null否元数据信息

curl 示例：

# 创建简单知识（default 类型 + alert 触发）
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/create' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "MySQL 连接数告警处理",
    "type": "default",
    "trigger": "alert",
    "trigger_config": {
      "match_patterns": ["MySQL 连接数"]
    },
    "description": "MySQL 连接数超限后的标准处理流程",
    "data": {
      "content": "1. 登录 MySQL 执行 SHOW PROCESSLIST\n2. 确认长事务或慢查询\n3. kill 阻塞会话"
    },
    "labels": {
      "env": "prod",
      "team": "dba"
    }
  }' | jq .

# 创建应用触发知识
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/create' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "订单服务重启流程",
    "type": "document",
    "trigger": "application",
    "trigger_config": {
      "application_id": "app-order-service"
    },
    "data": {
      "document_content": "# 订单服务重启\n\n1. 确认无正在处理的订单\n2. 执行 graceful shutdown\n3. 等待健康检查通过"
    }
  }' | jq .

更新知识

POST /personal/v1/knowledge/update
Authorization: Bearer <pat_token>
Content-Type: application/json

所有非 id 的字段均为可选。更新 data 时必须同时提供 type；更新 trigger_config 时必须同时提供 trigger。

请求体：

字段类型必填说明
idint是知识系统主键 ID
namestring/null否知识名称
typestring/null否知识类型
triggerstring/null否触发条件类型
trigger_configobject/null否触发配置（提供时必须同时提供 trigger）
descriptionstring/null否知识描述
dataobject/null否知识内容数据（提供时必须同时提供 type）
labelsobject/null否标签键值对
metadataobject/null否元数据信息

curl 示例：

# 更新知识名称和内容
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/update' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "name": "MySQL 连接数告警处理 v2",
    "type": "default",
    "data": {
      "content": "更新后的处理流程..."
    }
  }' | jq .

保存知识（Upsert）

POST /personal/v1/knowledge/upsert
Authorization: Bearer <pat_token>
Content-Type: application/json

以 name + trigger + trigger_config 作为唯一标识进行 upsert。存在则更新，不存在则创建。

请求体：

字段类型必填说明
namestring是知识名称
triggerstring是触发条件类型
trigger_configobject是触发配置
typestring/null否知识类型
descriptionstring/null否知识描述
dataobject/null否知识内容数据
labelsobject/null否标签键值对
metadataobject/null否元数据信息

curl 示例：

curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/upsert' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "MySQL 连接数告警处理",
    "type": "default",
    "trigger": "alert",
    "trigger_config": {
      "match_patterns": ["MySQL 连接数"]
    },
    "data": {
      "content": "最新的处理流程..."
    },
    "labels": {
      "env": "staging"
    }
  }' | jq .

身份认证

使用个人访问令牌（PAT）进行 Castrel API 认证。

路线图

Castrel 即将推出的功能与改进方向。