TJWaterAgent/.opencode/skills/runbook.md

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 工具约定

{
  "reason": "查询当前项目数据库健康状态",
  "command": "project db-health",
  "timeout": 60
}

• command：tjwater-cli 子命令（不含二进制路径和 --auth-context）
• timeout：可选超时秒数，默认 60，大结果集建议 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 / append_pattern / remove_pattern / write_reference / remove_reference / write_script / remove_script
• session_search：只搜索当前用户 + 当前项目作用域
• skill_manager 写入落到：## Learned Patterns、references/*.md、scripts/*.py

6) 用户上下文注入

• Authorization（Bearer Token）
• X-Project-Id
• 执行器附带 X-Trace-Id 用于链路排查

7) 排障要点

• CLI 返回 "ok": false → 检查 error.code 和 error.message
• UNAUTHENTICATED：检查 token 和项目权限
• NOT_FOUND：检查资源 ID 或命令拼写
• SERVER_ERROR：记录 request_id，结合后端日志排查
• CLI 超时：增大 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