95 lines
3.6 KiB
Markdown
95 lines
3.6 KiB
Markdown
# TJWater Skills Runbook（工具调用链）
|
||
|
||
## 1) 总体原则
|
||
|
||
- Skills 仅负责**可复用的多步工作流**。
|
||
- 原子操作（单次查询/单项分析）由 Agent 直接调用 `tjwater_cli` 工具。
|
||
- `tjwater-cli` 输出 JSON，`"ok": true` 表示成功，`"ok": false` 时检查 `error.code`。
|
||
- Agent 运行 `tjwater-cli help` 发现可用命令和参数。
|
||
- 会话完成后，运行时基于 transcript 做后台 learning review；这一步用于判断是否需要更新 memory 或 skill，而不是替代主任务回答。
|
||
|
||
## 1.1) 自我学习闭环
|
||
|
||
- **memory_manager**：保存用户长期偏好 / 约束
|
||
- **skill_manager**：保存经过验证、可复用的 workflow 方法模式
|
||
- **session_search**：检索历史会话，避免把一次性案例写入 memory
|
||
|
||
## 2) 请求入口（前端）
|
||
|
||
- `POST /api/v1/agent/chat/stream`（唯一前端入口）
|
||
|
||
SSE 事件：
|
||
|
||
| event | 用途 |
|
||
|---|---|
|
||
| `progress` | Agent 处理过程、规划和工具进度 |
|
||
| `token` | 面向用户的回答文本 |
|
||
| `tool_call` | 驱动前端地图/面板/图表动作 |
|
||
| `done` | 当前轮对话结束 |
|
||
| `error` | 当前轮失败 |
|
||
|
||
## 3) tjwater_cli 工具约定
|
||
|
||
```json
|
||
{
|
||
"reason": "查询当前项目数据库健康状态",
|
||
"command": "project db-health",
|
||
"timeout": 120
|
||
}
|
||
```
|
||
|
||
- `command`：tjwater-cli 子命令（不含二进制路径和 `--auth-context`）
|
||
- `timeout`：可选超时秒数，默认 120，大结果集建议 300+
|
||
- 认证上下文（token、server、project）由内部桥接自动注入
|
||
|
||
## 4) 工具参数约定（前端工具）
|
||
|
||
- 所有前端工具 `locate_features`、`view_scada`、`view_history`、`show_chart`、`render_junctions` 需带 `reason`
|
||
|
||
## 5) 学习工具约定
|
||
|
||
- 所有学习类工具必须带 `reason`
|
||
- `memory_manager`：`add / list / replace / remove`
|
||
- `skill_manager`：`list / write_skill / remove_skill / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script`
|
||
- `session_search`：只搜索当前用户 + 当前项目作用域
|
||
- `skill_manager` 写入落到：`SKILL.md`、`## Learned Patterns`、`references/*.md`、`scripts/*.py`
|
||
- 目录入口同样走 `skill_manager`：`skill_path="workflow"` 维护 `skills/workflow/SKILL.md`，`skill_path="__root__"` 维护 `skills/SKILL.md`
|
||
|
||
## 6) 用户上下文注入
|
||
|
||
- `Authorization`（Bearer Token）
|
||
- `X-Project-Id`
|
||
- 执行器附带 `X-Trace-Id` 用于链路排查
|
||
|
||
## 7) 排障要点
|
||
|
||
- CLI 返回 `"ok": false` → 检查 `error.code` 和 `error.message`
|
||
- `UNAUTHENTICATED`：检查 token 和项目权限
|
||
- `COMMAND_NOT_FOUND` / `INPUT_NOT_FOUND`：检查命令拼写或文件路径
|
||
- `SERVER_ERROR`：记录 `request_id`，结合后端日志排查
|
||
- `REQUEST_TIMEOUT` / `TIMEOUT`：增大 `timeout` 参数
|
||
|
||
## 8) 前端工具调用链
|
||
|
||
```
|
||
用户消息 → opencode agent → tool calling → 调用前端工具
|
||
↓
|
||
tool handler:
|
||
1) 推送 SSE tool_call 事件到前端
|
||
2) 返回简短确认给 opencode agent
|
||
↓
|
||
前端同时收到:
|
||
- SSE event: progress → 展示处理状态
|
||
- SSE event: tool_call → 前端执行操作
|
||
- SSE event: token → 渲染文字回复
|
||
```
|
||
|
||
`tjwater_cli`：Agent 桥接调用 CLI，结果返回给 opencode agent 做后续分析。
|
||
前端工具：仅推送 SSE 事件，前端直接执行。
|
||
|
||
## 9) 复盘与沉淀建议
|
||
|
||
- 复杂多工具任务完成后，判断是否产生了稳定 workflow，可写入 `skill_manager`
|
||
- 用户明确纠正表达风格、输出格式时，写入 `memory_manager`
|
||
- 确认"以前是否处理过类似问题"，用 `session_search`
|