From d3f6213187bb5101e77526a7ca1839f83a9166d2 Mon Sep 17 00:00:00 2001 From: Huarch Date: Mon, 18 May 2026 17:13:45 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E4=BB=A5?= =?UTF-8?q?=E5=8C=B9=E9=85=8D=E5=BD=93=E5=89=8D=E4=BB=A3=E7=A0=81=E7=BB=93?= =?UTF-8?q?=E6=9E=84=E5=92=8C=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 91 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 46 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 67adb44..e1a9c5c 100644 --- a/README.md +++ b/README.md @@ -30,41 +30,30 @@ TJWaterAgent/ 1. 启动 HTTP 服务。 2. 通过 `@opencode-ai/sdk` 启动内嵌 opencode server，或连接外部 opencode server。 3. 管理前端 `session_id -> opencode sessionId` 的映射。 -4. 保存并传递用户 `Authorization`、`x-user-id`、`x-project-id`、`x-trace-id`。 +4. 保存并传递用户的鉴权信息（accessToken, actorKey）、项目上下文（projectId, projectKey）以及 traceId。 5. 把 opencode 输出适配成前端需要的 SSE 事件。 -6. 为 `.opencode/tools/dynamic_http_call.ts` 提供内部回调接口。 +6. 为 `.opencode/tools/dynamic_http_call.ts` 等工具提供内部回调接口。 7. 代理调用真实 TJWater 后端 API。 -当前 Agent API 的主入口： +主要目录结构说明： -```text -POST /api/v1/agent/chat/stream -``` - -该接口返回 SSE，事件包括： - -| event | 用途 | +| 目录 | 职责 | | --- | --- | -| `progress` | 前端过程可视化，展示规划、工具调用和完成状态 | -| `token` | 最终回答文本流 | -| `tool_call` | 前端地图/面板/图表动作 | -| `done` | 当前轮完成 | -| `error` | 当前轮失败 | +| `src/routes/` | 路由定义，如 `chat.ts` 处理聊天请求 | +| `src/chat/` | 会话桥接逻辑，负责 Express 与 opencode 会话的同步 | +| `src/runtime/` | opencode 运行时管理，控制 SDK 的启动与状态检查 | +| `src/session/` | 会话注册中心和工具执行时的上下文关联存储 | +| `src/tools/` | 内部工具执行器，如 `dynamicHttpExecutor` 负责构造真实的业务请求 | +| `src/learning/` | Agent 学习状态协调器，负责处理记忆累积和知识更新 | +| `src/audit/` | 审计记录，包含学习过程和 LLM 请求审计 | -主要目录和文件： +当前 Agent API 的主接口： ```text -src/ - server.ts - config.ts - runtime/ - session/ - chat/ - routes/ - tools/ +POST /api/v1/chat/message ``` -其中 `src/` 是业务服务层，不直接放 opencode skill 或 agent prompt。 +该接口返回 SSE 格式数据。 ## `.opencode/` 的职责 @@ -73,40 +62,52 @@ src/ ### agents ```text -.opencode/agents/agent.md +.opencode/agents/instruction.md ``` -这里定义默认 agent 的角色、行为规则、模型配置和工具使用策略。 - -当前项目已将 always-loaded instructions 收敛到 `agent.md`，`opencode.json` 不再额外配置 `instructions` 数组。 +这里定义默认 agent 的角色、行为规则、模型配置和工具使用策略。目前的 `default_agent` 配置为 `instruction`。 ### tools ```text .opencode/tools/ - dynamic_http_call.ts - locate_features.ts - view_history.ts - view_scada.ts - show_chart.ts + dynamic_http_call.ts # 动态 HTTP 调用，通过回调 host 服务获取鉴权 + fetch_result_ref.ts # 获取结果引用 + locate_features.ts # 地图定位 + memory_manager.ts # 记忆管理 + skill_manager.ts # 技能管理 + show_chart.ts # 图表展示 + ... ``` 这些是 opencode 可以调用的自定义工具。 -`dynamic_http_call.ts` 不直接保存用户 token，也不直接访问后端。它会回调 `TJWaterAgent` 的内部接口，由上级服务层根据当前 session 补上用户 token、项目 ID 和 trace ID，再调用 TJWater 后端。 - -前端类工具如 `locate_features`、`view_history`、`view_scada`、`show_chart` 主要用于触发 UI 动作或可视化，不应被当作数据查询工具。 - ### skills ```text -.opencode/skills/tjwater-skills-root-index/ - SKILL.md - ai/ - analytics/ - business/ - data/ - platform/ +.opencode/skills/ + SKILL.md # 根索引 + analytics/ # 分析类技能（SCADA、水力模拟、爆管分析等） + business/ # 业务类技能（模型配置、资产管理、项目环境等） + data/ # 数据类技能（时序数据访问） + platform/ # 平台类技能（审计、缓存、元数据等） +``` + +这里保存 TJWater 技能树，保持树结构以符合渐进式披露设计。 + +## 启动与开发 + +项目使用 `bun` 作为包管理器和运行环境。 + +```bash +# 安装依赖 +bun install + +# 启动开发环境（带 watch 模式） +bun run dev + +# 类型检查 +bun run check ``` 这里保存 TJWater 技能树，并保持树结构，符合渐进式披露设计。