TJWaterAgent 内部智能体服务

TJWaterAgent 是 TJWater 内部版智能体服务，负责连接前端聊天界面、OpenCode 运行时、MCP 工具和 TJWater 后端 API。它面向内部研发与部署，保留完整的 Agent 编排、会话上下文、工具调用和运行时调试能力。

主要能力

• 提供 POST /api/v1/agent/sessions/{session_id}/runs SSE 聊天接口。
• 支持 embedded OpenCode 运行时，也可连接外部 OpenCode server。
• 管理前端 session_id 与 OpenCode session 的映射。
• 在服务端保存当前会话的用户 token、项目、network 和 trace 上下文。
• 通过 .opencode/tools 和 MCP 工具驱动地图定位、图表、SCADA、历史数据和业务 API 调用。
• 通过 data/ 保存运行时会话元数据、结果引用和本地状态。

目录结构

src/                  服务端 TypeScript 源码
src/routes/           HTTP 路由
src/chat/             聊天流和 SSE 事件适配
src/runtime/          OpenCode 运行时管理
src/session/          会话映射和运行上下文
src/mcp/              MCP 服务与工具桥接
.opencode/agents/    Agent prompt 和模型行为配置
.opencode/tools/     OpenCode 自定义工具
.opencode/skills/    可复用分析工作流
node-tests/           Node CLI 测试
data/                 本地运行时数据，禁止提交
logs/                 本地日志，禁止提交

本地开发

项目使用 Bun：

bun install
bun run dev

bun install 会通过 postinstall 安装 .opencode 子目录依赖。bun run dev 以 watch 模式启动 src/server.ts，修改 src/**、.opencode/**、opencode.json 或 .local.env 后会自动重启。

常用命令

bun run check
bun run contract:generate
bun run test:api
bun run test:cli
bun run start
bun run start:prod
docker build -t tjwater-agent:local .

• bun run check：检查主项目和 .opencode 的 TypeScript 类型。
• bun run contract:generate：生成 contracts/agent-v1.openapi.json。
• bun run test:api：验证公开 REST 契约和聊天路由。
• bun run test:cli：运行 node-tests/cli/*.node.mjs。
• bun run start：直接启动服务。
• bun run start:prod：先类型检查，再启动服务。

运行模式

Embedded 模式由服务进程拉起本机 OpenCode：

OPENCODE_MODE=embedded
TJWATER_API_BASE_URL=http://127.0.0.1:8000

Client 模式连接外部 OpenCode server：

OPENCODE_MODE=client
OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
TJWATER_API_BASE_URL=http://127.0.0.1:8000

本地可使用 .local.env 保存开发配置；系统环境变量优先级更高。

配置与安全

不要提交 .env、.local.env、data/、logs/、会话记录、模型输出、访问令牌或 node_modules/。部署凭据、镜像仓库账号和 webhook 地址应放在 Gitea secrets 或部署环境变量中。

发布

Gitea 包工作流位于 .gitea/workflows/package.yml。发布前至少运行：

bun run check

如修改 CLI 或工具调用逻辑，同时运行：

bun run test:cli