# TJWaterAgent 目录结构说明

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

## 总体边界

```text
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-user-id`、`x-project-id`、`x-trace-id`。
5. 把 opencode 输出适配成前端需要的 SSE 事件。
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` | 当前轮失败 |

主要目录和文件：

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

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

## `.opencode/` 的职责

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

### agents

```text
.opencode/agents/agent.md
```

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

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

### tools

```text
.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

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

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

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

## 依赖边界

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

### 根目录依赖

```text
TJWaterAgent/package.json
```

用于服务本体，例如：

```text
@opencode-ai/sdk
express
zod
pino
```

### `.opencode` 依赖

```text
TJWaterAgent/.opencode/package.json
```

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

```text
@opencode-ai/plugin
typescript
@types/node
```

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

## 启动与部署

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

根目录的 Bun scripts 已经封装 `.opencode` 依赖安装和类型检查，日常只需要在 `TJWaterAgent/` 根目录操作。

### 本地开发

```bash
cd TJWaterAgent
bun install
bun run dev
```

`bun install` 会通过 `postinstall` 自动执行 `.opencode` 依赖安装；`bun run dev` 启动前会检查 `.opencode/tools` 的类型。

开发模式支持热重载，以下文件变化会触发服务重启并重新拉起 embedded opencode：

```text
src/**
.opencode/**
opencode.json
.local.env
```

因此修改 agent prompt、tools、skills、模型配置或本地环境变量后，不需要手动重启 `bun run dev`。

本地开发可以在项目根目录的 `.local.env` 中配置环境变量：

```bash
DEEPSEEK_API_KEY=sk-xxx
TJWATER_API_BASE_URL=http://127.0.0.1:8000
```

服务启动时会自动读取 `.local.env`，但系统环境变量优先级更高，适合在本机保存开发用 key。

### 生产启动

```bash
cd TJWaterAgent
bun install
bun run check
bun run start
```

也可以使用一条命令完成构建并启动：

```bash
cd TJWaterAgent
bun install
bun run start:prod
```

### Docker Compose 启动

项目根目录已提供 `Dockerfile` 和 `docker-compose.yml`，可直接使用：

```bash
cd TJWaterAgent
docker compose up -d --build
```

查看日志：

```bash
docker compose logs -f tjwater-agent
```

停止并清理容器：

```bash
docker compose down
```

### 常用脚本

| 命令 | 作用 |
| --- | --- |
| `bun run dev` | 类型检查 `.opencode` tools 后，以 watch 模式直接运行 `src/server.ts` |
| `bun run check` | 执行完整类型检查（服务与 `.opencode` tools） |
| `bun run start` | 直接运行 `src/server.ts` |
| `bun run start:prod` | 先类型检查再启动 |
| `bun run install:opencode` | 手动安装 `.opencode` 依赖 |

### 模型与 API 配置

默认 Agent 模型为：

```text
deepseek/deepseek-v4-pro
```

涉及位置：

```text
opencode.json
.opencode/agents/tjwater-assistant.md
src/config.ts 的 OPENCODE_MODEL 默认值
```

如果需要临时覆盖模型，可以在启动时设置：

```bash
OPENCODE_MODEL=deepseek/deepseek-v4-pro bun run start
```

DeepSeek API key 不写入代码，部署时通过环境变量设置：

```bash
DEEPSEEK_API_KEY=sk-xxx bun run start
```

`opencode.json` 已配置从环境变量读取：

```json
{
  "provider": {
    "deepseek": {
      "options": {
        "apiKey": "{env:DEEPSEEK_API_KEY}"
      }
    }
  }
}
```

如果需要自定义 DeepSeek 兼容 API 地址，可以通过 opencode 的 provider 配置增加 `baseURL`，例如在部署环境使用 `OPENCODE_CONFIG_CONTENT` 覆盖：

```bash
OPENCODE_CONFIG_CONTENT='{"provider":{"deepseek":{"options":{"baseURL":"https://your-api.example.com/v1"}}}}' \
DEEPSEEK_API_KEY=sk-xxx \
bun run start
```

也可以使用 opencode 的 `/connect` 命令写入用户级凭据，但服务部署更推荐使用环境变量。

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

```bash
OPENCODE_BASE_URL=http://127.0.0.1:4096
```

配置后，`TJWaterAgent` 会连接该外部 opencode server，而不是自行启动 embedded opencode server。
>>>>>>> 414247d (新增 skills、README，指定  opencode 的启动行为)