docs(api): api-client → v0.52（approval_notice 帧 + 策略落盘 + graph props 新键）+ api-reference 去假陈述
- 新增下行帧 approval_notice（§3.11，主代理代审小字，owner+admin，fail-closed 默认档）； 审计口径 who=角色名 / what=approval.<工具> / result=granted|denied - 工具策略落盘口径写入端点表（载体 tool_policies，迁移 0012，先落库后改内存） - graph_update 节点 props 新增四类可选键（tool args_keys/args_summary、guardrail、memory、orchestration）， 纯增量 + 发布前脱敏；帧名/事件名/顶层字段集未动 - api-reference:439 的「仅内存标记，重启复位」改为「落盘 tool_policies，重启保留」；§4.17 补旁路节点 span - 按实现修正 7 处表述：args_keys 是「全部参数名」（只有 args_summary 限放行表）、explain 带「」引号、 detail 只截目标部分、allowed=false 还覆盖无代审者/代审报错两条 fail-closed 路径等
This commit is contained in:
AskaEth committed
1 parent
b99268d019
commit
b8fa53e43c
2 files changed
+26
-6
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# Cyrene v2 后端 API 参考（api-reference.md）
|
||||
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.51`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **权威归属（先读这条）**：**契约以 `Docs/api-client.md` 为准**——那是版本化的跨平台客户端契约，每个端点的形状 / 语义 / 版本变更都记在那里（当前 `v0.52`）。**本文件是内部与运维参考**：端点全集索引 + 示例 + 部署细节。**凡是与 api-client 重复的契约性描述，一律以 api-client 为准（本文件不再维护第二份契约）；发现两者不一致时，改本文件而不是改 api-client。**
|
||||
> **本文件的正确用法**：查「有哪些端点、大致形状、错误码、部署注意事项」可以；**写客户端代码时请以 `Docs/api-client.md` 为准**，本文件的字段表 / 示例可能滞后。
|
||||
> **历史包袱（如实）**：本文件长期自称「全部后端 API 的唯一详细参考 / 超详细主文档 / 每变更必同步」，但实际**系统性滞后于实现与 api-client**（2026-10-03 的 16 路 design-vs-code 审计结论）。本次已修正与实现**直接矛盾**的陈述、并把若干复述型段落改为引用 api-client；**仍未登记的端点 / WS 事件清单见 `DevDocs/audit/00-总览.md` §4④**，属后续「文档补全」批次，本文件暂不补全。
|
||||
> **其余仍成立**：所有字段名、取值、鉴权规则、状态码最终**以代码为准**（`internal/services/gateway/*.go`）；契约变更版本化（REST 走 `/api/v1`，破坏性变更升 v2），不得破坏既有客户端（版本化承诺本身记在 api-client §5）。
|
||||
@@ -436,7 +436,7 @@ curl -s http://<host>:8080/api/v1/admin/memories -H "Authorization: Bearer $TOKE
|
||||
```
|
||||
|
||||
### 4.4 GET /api/v1/admin/plugins
|
||||
- **响应**：`200 {"data":[<PluginSummary>...]}`（`PluginSummary` = `{name, kind, description, allowInGroup, allowInStranger}`）。`kind` 为能力类型，实际取值 = `tool|skill|channel|mcp|iot`（`internal/capability/registry` 的 `KindTool`/`KindSkill`/`KindChannel`/`KindMCP`/`KindIoT`）；`allowInGroup/allowInStranger` 为可达性策略（**仅内存标记，重启复位**）。curl：
|
||||
- **响应**：`200 {"data":[<PluginSummary>...]}`（`PluginSummary` = `{name, kind, description, allowInGroup, allowInStranger}`）。`kind` 为能力类型，实际取值 = `tool|skill|channel|mcp|iot`（`internal/capability/registry` 的 `KindTool`/`KindSkill`/`KindChannel`/`KindMCP`/`KindIoT`）；`allowInGroup/allowInStranger` 为可达性策略（**落盘 `tool_policies`，重启保留**——迁移 `0012_tool_policy`；`SetPolicy` 先落库后改内存，落盘失败内存保持旧值并返回错误，无行的能力按默认 owner-only）。curl：
|
||||
|
||||
```bash
|
||||
curl -s http://<host>:8080/api/v1/admin/plugins -H "Authorization: Bearer $TOKEN" -H 'X-API-Version: 1'
|
||||
@@ -575,6 +575,7 @@ curl -s http://<host>:8080/api/v1/admin/observability/metrics -H "Authorization:
|
||||
### 4.17 GET /api/v1/admin/observability/trace
|
||||
- **Query**：`?limit=N`（默认 50，上限 500）。
|
||||
- **响应**：`200 {"data":[<AdminTraceSpan>...]}`（newest first）。`AdminTraceSpan` = `{id, parentId?, name, kind, status, startedAt, endedAt?, durationNs, props?, events?}`。`kind` ∈ `llm_call|tool_call|orchestration|state_transition|subagent|memory|guardrail`；`events` 为 `[{time,type,props?}]`；时间 RFC3339。
|
||||
- **旁路节点的 span 现已真实产生**（裁决 11.4.2 / 11.4.3，2026-10-04）：`memory.recall` / `memory.write` / `guardrail.input` / `guardrail.output` / `orchestration.spawn` 均由真实生产者开出，因此 `kind` 取值集里的 `memory|guardrail|orchestration` 不再只是枚举——trace 列表中会真的出现这三类 span（此前三者无生产者，全仓只有 `llm_call`/`tool_call`/`subagent`/`state_transition`）。它们只带元数据（记忆作用域/条数/字节数、护栏裁决与耗时、被派发的子代理 id 与目标角色 id），**不含记忆正文、不含提示词、不含密钥**；见 `design/19 §1`。
|
||||
- 来源：环形缓冲（默认 512 条），由 `ObserveSpan`/`TraceSink` 注入。curl：
|
||||
|
||||
```bash
|
||||
|
||||
Reference in new issue
Block a user