API Skills 使用 Runbook（工具调用链）

1) 总体原则

Skills 负责“告诉模型可做什么”。
chat/stream 内部启动 opencode 会话，并注册工具 dynamic_http_call。
opencode agent 通过工具调用后端能力，不直接发 HTTP。
TJWaterAgent 执行器负责“代表当前用户调真实后端 API”（动态路径，无白名单）。
会话完成后，运行时会基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。

1.1) 自我学习闭环

memory_manager：保存用户长期偏好 / 约束，以及稳定 workspace 事实
skill_manager：保存经过验证、可复用的 workflow / 方法 / pitfall
session_search：检索当前用户 + 当前项目范围内的历史会话 transcript，用于回忆旧案例，避免把一次性案例写入 memory

推荐分流：

需要长期遵守的偏好 / 稳定事实 → memory_manager
可复用的方法、步骤、坑点 → skill_manager
某次分析过程、历史案例、临时结论 → session_search

2) 请求入口（前端）

POST /api/v1/agent/chat/stream（唯一前端入口）

不提供 /execute 对外调用路径，统一通过 chat/stream + 工具调用链执行。

请求体：

{
  "message": "帮我分析当前管网中的水力瓶颈管道，并给出改造建议",
  "session_id": "agent-demo-001"
}

SSE 事件：

event	用途	关键字段
`progress`	展示 Agent 处理过程、规划和工具进度	`session_id`, `id`, `phase`, `status`, `title`, `detail`
`token`	渲染面向用户的最终回答文本	`session_id`, `content`
`tool_call`	驱动前端地图/面板/图表动作	`session_id`, `tool`, `params`
`done`	当前轮对话结束	`session_id`
`error`	当前轮失败	`session_id`, `message`, `detail`

progress.status 取值为 running、completed、error；前端应按相同 id 覆盖更新同一条进度，而不是重复追加。

3) 工具参数约定（opencode agent 调用工具时）

{
  "path": "/api/v1/scada/by-ids-field-time-range",
  "method": "GET",
  "arguments": {
    "device_ids": "170490",
    "field": "monitored_value",
    "start_time": "2026-03-29T07:57:47.338Z",
    "end_time": "2026-03-30T07:57:47.338Z"
  }
}

说明（工具 dynamic_http_call）：

path 必须以 / 开头。
method 支持：GET/POST/PUT/PATCH/DELETE。
arguments 会编码为 query 参数（列表会转为逗号拼接）。

3.1) 学习工具约定

所有学习类工具都必须带 reason
memory_manager 支持：add / list / replace / remove
skill_manager 支持：list / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script
session_search 只搜索当前用户 + 当前项目作用域，不接受跨项目检索
skill_manager 的结构化写入优先落到：
1. ## Learned Patterns
2. references/*.md
3. scripts/*.py 不应直接重写 skill frontmatter 或任意正文段落
scripts/*.py 仅表示当前 skill_path 私有的可复用脚本资产；不要把运行时临时脚本写进 data/

4) 用户上下文注入（后端执行阶段）

Authorization（Bearer Token）
x-project-id

执行器会附带 x-trace-id 用于链路排查（可透传或自动生成）。

5) 排障要点

400：检查工具参数 path/method/arguments 格式。
401/403：检查 token 与项目权限。
404：检查 path 是否正确。
422：检查 arguments 字段名与类型。
5xx：记录 trace_id，结合后端日志排查。

6) 前端工具调用链

前端工具（locate_features, view_history, view_scada, show_chart）的调用链与 dynamic_http_call 不同：

用户消息 → opencode agent → tool calling → 调用前端工具 (如 locate_features)
                                    ↓
                              tool handler:
                              1) 推送 SSE tool_call 事件到前端
                              2) 返回简短确认给 opencode agent（"已定位到管道"）
                                    ↓
前端同时收到:
  - SSE event: progress  → 展示规划/工具执行/完成状态
  - SSE event: tool_call → 前端执行操作（定位地图/打开面板/渲染图表）
  - SSE event: token     → 渲染 opencode agent 文字回复

关键区别：

dynamic_http_call：TJWaterAgent 代理 HTTP 请求，结果返回给 opencode agent 做后续分析。
前端工具：TJWaterAgent 仅推送 SSE 事件，前端直接执行，结果不返回 opencode agent。
show_chart：opencode agent 先通过 dynamic_http_call 查询数据，处理为 x_data + series 格式后调用 show_chart，前端直接渲染图表，不再请求后端。

7) 复盘与沉淀建议

复杂多工具任务完成后，优先判断是否产生了稳定 workflow，可写入 skill_manager
用户明确纠正表达风格、输出格式或步骤时，优先判断是否需要写入 memory_manager
如果你只是想确认“以前是不是处理过类似问题”，先用 session_search
如果结果仍然只是 preview，不要基于 preview 做 learned pattern，总是先 fetch_result_ref

5.3 KiB Raw Blame History Unescape Escape