feat(agent): add credential refresh and unify learning tools

README.md

@@ -5,7 +5,7 @@
 ## 主要能力
 
 - 提供 `POST /api/v1/agent/sessions/{session_id}/runs` SSE 聊天接口。
-- 支持 embedded OpenCode 运行时，也可连接外部 OpenCode server。
+- 以内嵌模式启动并预热 OpenCode 运行时。
 - 管理前端 `session_id` 与 OpenCode session 的映射。
 - 在服务端保存当前会话的用户 token、项目、network 和 trace 上下文。
 - 通过 `.opencode/tools` 和 MCP 工具驱动地图定位、图表、SCADA、历史数据和业务 API 调用。
@@ -67,13 +67,13 @@ OPENCODE_MODE=embedded
 TJWATER_API_BASE_URL=http://127.0.0.1:8000
 ```
 
-Client 模式连接外部 OpenCode server：
+当前仅支持 Embedded 模式，不支持连接外部 OpenCode server。
 
-```bash
-OPENCODE_MODE=client
-OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
-TJWATER_API_BASE_URL=http://127.0.0.1:8000
-```
+## 认证续期与学习工具
+
+后端工具调用遇到即将过期的 access token 或首次 `401` 时，Agent 会通过当前 SSE 流发送 `credential_refresh_required`。前端使用服务端保存的 Keycloak refresh token 强制换取新 access token，再调用 `POST /api/v1/agent/sessions/{session_id}/credential-refreshes` 唤醒原工具调用。等待上限为 30 秒，同一会话的并发请求合并为一次续期，原调用最多重试一次；`403` 不触发续期。
+
+`memory_manager` 和 `skill_manager` 在 OpenCode 侧只保留内部 HTTP 桥，读取会话上下文和持久化数据的逻辑统一在 Agent 主进程中执行。长期记忆、自动学习和显式工具写入因此共享同一组 `MemoryStore`、`SkillStore` 和运行时会话上下文。
 
 本地可使用 `.local.env` 保存开发配置；系统环境变量优先级更高。