292 lines
7.3 KiB
Markdown
292 lines
7.3 KiB
Markdown
# 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. 保存并传递用户的鉴权信息（accessToken, actorKey）、项目上下文（projectId, projectKey）以及 traceId。
|
||
5. 把 opencode 输出适配成前端需要的 SSE 事件。
|
||
6. 为 `.opencode/tools/dynamic_http_call.ts` 等工具提供内部回调接口。
|
||
7. 代理调用真实 TJWater 后端 API。
|
||
|
||
主要目录结构说明：
|
||
|
||
| 目录 | 职责 |
|
||
| --- | --- |
|
||
| `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
|
||
POST /api/v1/chat/message
|
||
```
|
||
|
||
该接口返回 SSE 格式数据。
|
||
|
||
## `.opencode/` 的职责
|
||
|
||
`.opencode/` 是给 opencode 运行时读取的项目资产目录，不是对外 HTTP 服务的主代码目录。
|
||
|
||
### agents
|
||
|
||
```text
|
||
.opencode/agents/instruction.md
|
||
```
|
||
|
||
这里定义默认 agent 的角色、行为规则、模型配置和工具使用策略。目前的 `default_agent` 配置为 `instruction`。
|
||
|
||
### tools
|
||
|
||
```text
|
||
.opencode/tools/
|
||
dynamic_http_call.ts # 动态 HTTP 调用，通过回调 host 服务获取鉴权
|
||
fetch_result_ref.ts # 获取结果引用
|
||
locate_features.ts # 地图定位
|
||
memory_manager.ts # 记忆管理
|
||
skill_manager.ts # 技能管理
|
||
show_chart.ts # 图表展示
|
||
...
|
||
```
|
||
|
||
这些是 opencode 可以调用的自定义工具。
|
||
|
||
### skills
|
||
|
||
```text
|
||
.opencode/skills/
|
||
SKILL.md # 根索引
|
||
analytics/ # 分析类技能（SCADA、水力模拟、爆管分析等）
|
||
business/ # 业务类技能（模型配置、资产管理、项目环境等）
|
||
data/ # 数据类技能（时序数据访问）
|
||
platform/ # 平台类技能（审计、缓存、元数据等）
|
||
```
|
||
|
||
这里保存 TJWater 技能树，保持树结构以符合渐进式披露设计。
|
||
|
||
## 启动与开发
|
||
|
||
项目使用 `bun` 作为包管理器和运行环境。
|
||
|
||
```bash
|
||
# 安装依赖
|
||
bun install
|
||
|
||
# 启动开发环境（带 watch 模式）
|
||
bun run dev
|
||
|
||
# 类型检查
|
||
bun run check
|
||
```
|
||
|
||
这里保存 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
|
||
``` |