# 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`