TJWaterAgent/README.md

TJWaterAgent 目录结构说明

TJWaterAgent/ 是新的 opencode Agent 服务工程目录，负责对外提供 TJWater 智能助手接口，并通过 opencode SDK 启动或连接 opencode 运行时。

总体边界

TJWaterAgent/
  package.json
  tsconfig.json
  src/
  opencode.json
  .opencode/
    agents/
    tools/
    skills/
    package.json
    tsconfig.json

位置	主要作用	典型内容
TJWaterAgent/	服务宿主、API 层和编排层	Express 服务、SSE 接口、会话管理、鉴权上下文、后端 API 代理、opencode SDK 启动逻辑
TJWaterAgent/.opencode/	opencode 项目资产目录	agent prompt、自定义 tools、skills 树、plugins 相关依赖

TJWaterAgent/ 根目录的职责

根目录是 Node/TypeScript 服务本体，主要负责：

1. 启动 HTTP 服务。
2. 通过 @opencode-ai/sdk 启动内嵌 opencode server，或连接外部 opencode server。
3. 管理前端 session_id -> opencode sessionId 的映射。
4. 保存并传递用户 Authorization、x-project-id、x-trace-id。
5. 把 opencode 输出适配成前端需要的 SSE 事件。
6. 为 .opencode/tools/dynamic_http_call.ts 提供内部回调接口。
7. 代理调用真实 TJWater 后端 API。

主要目录和文件：

src/
  server.ts
  config.ts
  runtime/
  session/
  chat/
  routes/
  tools/

其中 src/ 是业务服务层，不直接放 opencode skill 或 agent prompt。

.opencode/ 的职责

.opencode/ 是给 opencode 运行时读取的项目资产目录，不是对外 HTTP 服务的主代码目录。

agents

.opencode/agents/tjwater-assistant.md

这里定义默认 agent 的角色、行为规则、模型配置和工具使用策略。

当前项目已将 always-loaded instructions 收敛到 tjwater-assistant.md，opencode.json 不再额外配置 instructions 数组。

tools

.opencode/tools/
  dynamic_http_call.ts
  locate_features.ts
  view_history.ts
  view_scada.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

.opencode/skills/tjwater-skills-root-index/
  SKILL.md
  ai/
  analytics/
  business/
  data/
  platform/

这里保存 TJWater 技能树，并保持树结构，符合渐进式披露设计。

agent 需要某个领域知识时再按需加载对应 skill，不把整棵技能树作为 always-loaded prompt 一次性注入。

依赖边界

根目录和 .opencode/ 使用两组 npm 依赖，职责不同。

根目录依赖

TJWaterAgent/package.json

用于服务本体，例如：

@opencode-ai/sdk
express
zod
pino

.opencode 依赖

TJWaterAgent/.opencode/package.json

用于 opencode 自定义 tools/plugins，例如：

@opencode-ai/plugin
typescript
@types/node

这两组依赖不要混在一起：根目录负责服务运行，.opencode 负责 opencode 扩展资产的类型检查和运行依赖。

部署安装

默认部署不需要全局安装 opencode CLI。服务会通过 @opencode-ai/sdk 的 embedded 模式启动 opencode server。

推荐安装和启动流程：

cd TJWaterAgent
npm install
npm run build

cd .opencode
npm install

cd ..
npm run start

如果需要连接外部独立运行的 opencode server，可以配置：

OPENCODE_BASE_URL=http://127.0.0.1:4096

配置后，TJWaterAgent 会连接该外部 opencode server，而不是自行启动 embedded opencode server。

414247d (新增 skills、README，指定 opencode 的启动行为)