docs: 编写中文 README
This commit is contained in:
@@ -1,345 +1,92 @@
|
|||||||
# TJWaterAgent 目录结构说明
|
# TJWaterAgent 内部智能体服务
|
||||||
|
|
||||||
`TJWaterAgent/` 是新的 opencode Agent 服务工程目录，负责对外提供 TJWater 智能助手接口，并通过 opencode SDK 启动或连接 opencode 运行时。
|
`TJWaterAgent` 是 TJWater 内部版智能体服务，负责连接前端聊天界面、OpenCode 运行时、MCP 工具和 TJWater 后端 API。它面向内部研发与部署，保留完整的 Agent 编排、会话上下文、工具调用和运行时调试能力。
|
||||||
|
|
||||||
## 总体边界
|
## 主要能力
|
||||||
|
|
||||||
|
- 提供 `POST /api/v1/agent/chat/stream` SSE 聊天接口。
|
||||||
|
- 支持 embedded OpenCode 运行时，也可连接外部 OpenCode server。
|
||||||
|
- 管理前端 `session_id` 与 OpenCode session 的映射。
|
||||||
|
- 在服务端保存当前会话的用户 token、项目、network 和 trace 上下文。
|
||||||
|
- 通过 `.opencode/tools` 和 MCP 工具驱动地图定位、图表、SCADA、历史数据和业务 API 调用。
|
||||||
|
- 通过 `data/` 保存运行时会话元数据、结果引用和本地状态。
|
||||||
|
|
||||||
|
## 目录结构
|
||||||
|
|
||||||
```text
|
```text
|
||||||
TJWaterAgent/
|
src/ 服务端 TypeScript 源码
|
||||||
package.json
|
src/routes/ HTTP 路由
|
||||||
tsconfig.json
|
src/chat/ 聊天流和 SSE 事件适配
|
||||||
src/
|
src/runtime/ OpenCode 运行时管理
|
||||||
opencode.json
|
src/session/ 会话映射和运行上下文
|
||||||
.opencode/
|
src/mcp/ MCP 服务与工具桥接
|
||||||
agents/
|
.opencode/agents/ Agent prompt 和模型行为配置
|
||||||
tools/
|
.opencode/tools/ OpenCode 自定义工具
|
||||||
skills/
|
.opencode/skills/ 可复用分析工作流
|
||||||
package.json
|
node-tests/ Node CLI 测试
|
||||||
tsconfig.json
|
data/ 本地运行时数据，禁止提交
|
||||||
|
logs/ 本地日志，禁止提交
|
||||||
```
|
```
|
||||||
|
|
||||||
| 位置 | 主要作用 | 典型内容 |
|
## 本地开发
|
||||||
| --- | --- | --- |
|
|
||||||
| `TJWaterAgent/` | 服务宿主、API 层和编排层 | Express 服务、SSE 接口、会话管理、鉴权上下文、后端 API 代理、opencode SDK 启动逻辑 |
|
|
||||||
| `TJWaterAgent/.opencode/` | opencode 项目资产目录 | agent prompt、自定义 tools、skills 树、plugins 相关依赖 |
|
|
||||||
|
|
||||||
## `TJWaterAgent/` 根目录的职责
|
项目使用 Bun：
|
||||||
|
|
||||||
根目录是 Node/TypeScript 服务本体，主要负责：
|
|
||||||
|
|
||||||
1. 启动 HTTP 服务。
|
|
||||||
2. 通过 `@opencode-ai/sdk` 启动内嵌 opencode server，或连接外部 opencode server。
|
|
||||||
3. 管理前端 `session_id -> opencode sessionId` 的映射。
|
|
||||||
4. 保存并传递后端认证后的用户 token、metadata 用户 ID、项目 ID 和 trace。
|
|
||||||
5. 把 opencode 输出适配成前端需要的 SSE 事件。
|
|
||||||
6. 为 `.opencode/tools/tjwater_cli.ts` 提供内部回调接口。
|
|
||||||
7. 代理调用真实 TJWater 后端 API。
|
|
||||||
|
|
||||||
当前 Agent API 的主入口：
|
|
||||||
|
|
||||||
```text
|
|
||||||
POST /api/v1/agent/chat/stream
|
|
||||||
```
|
|
||||||
|
|
||||||
该接口返回 SSE，事件包括：
|
|
||||||
|
|
||||||
| event | 用途 |
|
|
||||||
| --- | --- |
|
|
||||||
| `progress` | 前端过程可视化，展示规划、工具调用和完成状态 |
|
|
||||||
| `token` | 最终回答文本流 |
|
|
||||||
| `tool_call` | 前端地图/面板/图表动作 |
|
|
||||||
| `done` | 当前轮完成 |
|
|
||||||
| `error` | 当前轮失败 |
|
|
||||||
| `auth_required` | 运行中 access token 过期或被后端拒绝，需要前端刷新登录态后重试 |
|
|
||||||
|
|
||||||
主要目录和文件：
|
|
||||||
|
|
||||||
```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/
|
|
||||||
tjwater_cli.ts
|
|
||||||
store_render_ref.ts
|
|
||||||
locate_features.ts
|
|
||||||
view_history.ts
|
|
||||||
view_scada.ts
|
|
||||||
show_chart.ts
|
|
||||||
render_junctions.ts
|
|
||||||
apply_layer_style.ts
|
|
||||||
memory_manager.ts
|
|
||||||
session_search.ts
|
|
||||||
skill_manager.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
这些是 opencode 可以调用的自定义工具。
|
|
||||||
|
|
||||||
`tjwater_cli.ts` 不直接保存用户 token。它会回调 `TJWaterAgent` 的内部接口，由上级服务层根据当前 session 补上用户 token、项目 ID 和 trace ID，再调用 `tjwater-cli` 二进制执行后端命令。
|
|
||||||
|
|
||||||
`store_render_ref.ts` 用于把大型 junction 渲染 payload 存成 `render_ref`，再由 `render_junctions.ts` 交给前端回读并渲染。
|
|
||||||
|
|
||||||
前端类工具如 `locate_features`、`view_history`、`view_scada`、`show_chart`、`render_junctions`、`apply_layer_style` 主要用于触发 UI 动作或可视化，不应被当作数据查询工具。
|
|
||||||
|
|
||||||
### skills
|
|
||||||
|
|
||||||
```text
|
|
||||||
.opencode/skills/
|
|
||||||
SKILL.md
|
|
||||||
examples.md
|
|
||||||
runbook.md
|
|
||||||
tjwater-cli/ ← tjwater-cli 可执行文件
|
|
||||||
workflow/ ← 可复用分析工作流
|
|
||||||
SKILL.md
|
|
||||||
simulation-diagnosis/
|
|
||||||
bottleneck-analysis/
|
|
||||||
source-service-area-analysis/
|
|
||||||
```
|
|
||||||
|
|
||||||
Skills 仅保留可复用的多步工作流。Agent 通过 `tjwater-cli help` 自行发现原子命令，无需逐接口技能树。
|
|
||||||
|
|
||||||
agent 加载技能树时按需取用对应 workflow skill。
|
|
||||||
|
|
||||||
## 依赖边界
|
|
||||||
|
|
||||||
根目录和 `.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 接入方式：
|
|
||||||
|
|
||||||
1. Embedded 模式：服务通过 `@opencode-ai/sdk` 调用 `createOpencode`，启动本地 `opencode` CLI 子进程并自动创建 client。
|
|
||||||
2. Client 模式：服务通过 `createOpencodeClient` 直接连接一个已经存在的 opencode server。
|
|
||||||
|
|
||||||
因此，只有 Embedded 模式要求运行环境已安装 `opencode` CLI；Client 模式不依赖本地 CLI。
|
|
||||||
|
|
||||||
根目录的 Bun scripts 已经封装 `.opencode` 依赖安装和类型检查，日常只需要在 `TJWaterAgent/` 根目录操作。
|
|
||||||
|
|
||||||
### 本地开发
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd TJWaterAgent
|
|
||||||
bun install
|
bun install
|
||||||
bun run dev
|
bun run dev
|
||||||
```
|
```
|
||||||
|
|
||||||
`bun install` 会通过 `postinstall` 自动执行 `.opencode` 依赖安装；`bun run dev` 启动前会检查 `.opencode/tools` 的类型。
|
`bun install` 会通过 `postinstall` 安装 `.opencode` 子目录依赖。`bun run dev` 以 watch 模式启动 `src/server.ts`，修改 `src/**`、`.opencode/**`、`opencode.json` 或 `.local.env` 后会自动重启。
|
||||||
|
|
||||||
开发模式支持热重载，以下文件变化会触发服务重启并重新拉起 embedded opencode：
|
## 常用命令
|
||||||
|
|
||||||
```text
|
```bash
|
||||||
src/**
|
bun run check
|
||||||
.opencode/**
|
bun run test:cli
|
||||||
opencode.json
|
bun run start
|
||||||
.local.env
|
bun run start:prod
|
||||||
|
docker build -t tjwater-agent:local .
|
||||||
```
|
```
|
||||||
|
|
||||||
因此修改 agent prompt、tools、skills、模型配置或本地环境变量后，不需要手动重启 `bun run dev`。
|
- `bun run check`：检查主项目和 `.opencode` 的 TypeScript 类型。
|
||||||
|
- `bun run test:cli`：运行 `node-tests/cli/*.node.mjs`。
|
||||||
|
- `bun run start`：直接启动服务。
|
||||||
|
- `bun run start:prod`：先类型检查，再启动服务。
|
||||||
|
|
||||||
本地开发可以在项目根目录的 `.local.env` 中配置环境变量。
|
## 运行模式
|
||||||
|
|
||||||
Embedded 模式示例：
|
Embedded 模式由服务进程拉起本机 OpenCode：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
OPENCODE_MODE=embedded
|
OPENCODE_MODE=embedded
|
||||||
DEEPSEEK_API_KEY=sk-xxx
|
|
||||||
TJWATER_API_BASE_URL=http://127.0.0.1:8000
|
TJWATER_API_BASE_URL=http://127.0.0.1:8000
|
||||||
```
|
```
|
||||||
|
|
||||||
Client 模式示例：
|
Client 模式连接外部 OpenCode server：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
OPENCODE_MODE=client
|
OPENCODE_MODE=client
|
||||||
OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
|
OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
|
||||||
DEEPSEEK_API_KEY=sk-xxx
|
|
||||||
TJWATER_API_BASE_URL=http://127.0.0.1:8000
|
TJWATER_API_BASE_URL=http://127.0.0.1:8000
|
||||||
```
|
```
|
||||||
|
|
||||||
服务启动时会自动读取 `.local.env`，但系统环境变量优先级更高，适合在本机保存开发用 key。
|
本地可使用 `.local.env` 保存开发配置；系统环境变量优先级更高。
|
||||||
|
|
||||||
### 生产启动
|
## 配置与安全
|
||||||
|
|
||||||
|
不要提交 `.env`、`.local.env`、`data/`、`logs/`、会话记录、模型输出、访问令牌或 `node_modules/`。部署凭据、镜像仓库账号和 webhook 地址应放在 Gitea secrets 或部署环境变量中。
|
||||||
|
|
||||||
|
## 发布
|
||||||
|
|
||||||
|
Gitea 包工作流位于 `.gitea/workflows/package.yml`。发布前至少运行：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd TJWaterAgent
|
|
||||||
bun install
|
|
||||||
bun run check
|
bun run check
|
||||||
bun run start
|
|
||||||
```
|
```
|
||||||
|
|
||||||
也可以使用一条命令完成构建并启动：
|
如修改 CLI 或工具调用逻辑，同时运行：
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd TJWaterAgent
|
bun run test:cli
|
||||||
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` 依赖 |
|
|
||||||
| `bun run pipeline:trigger` | 通过重建并强推 annotated `latest` tag 触发 Gitea CI/CD，只发布/覆盖 `latest` 镜像 |
|
|
||||||
|
|
||||||
### 模型与 API 配置
|
|
||||||
|
|
||||||
默认 Agent 模型为：
|
|
||||||
|
|
||||||
```text
|
|
||||||
deepseek/deepseek-v4-flash
|
|
||||||
```
|
|
||||||
|
|
||||||
默认聊天模型配置组为：
|
|
||||||
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"id": "deepseek/deepseek-v4-flash",
|
|
||||||
"label": "快速",
|
|
||||||
"description": "快速回答和任务执行",
|
|
||||||
"icon": "bolt"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": "deepseek/deepseek-v4-pro",
|
|
||||||
"label": "专家",
|
|
||||||
"description": "探索、解决复杂任务",
|
|
||||||
"icon": "sparkle"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
涉及位置：
|
|
||||||
|
|
||||||
```text
|
|
||||||
src/chat/modelConfig.ts 的默认模型配置组
|
|
||||||
src/config.ts 的 OPENCODE_MODEL 与 OPENCODE_MODEL_OPTIONS 默认值
|
|
||||||
opencode.json 的 opencode 运行时默认模型
|
|
||||||
```
|
|
||||||
|
|
||||||
如果需要临时覆盖默认模型和模型配置组，可以在启动时设置：
|
|
||||||
|
|
||||||
```bash
|
|
||||||
OPENCODE_MODEL=deepseek/deepseek-v4-pro \
|
|
||||||
OPENCODE_MODEL_OPTIONS='[{"id":"deepseek/deepseek-v4-flash","label":"快速","description":"快速回答和任务执行","icon":"bolt"},{"id":"deepseek/deepseek-v4-pro","label":"专家","description":"探索、解决复杂任务","icon":"sparkle"}]' \
|
|
||||||
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_MODE=client
|
|
||||||
OPENCODE_CLIENT_BASE_URL=http://127.0.0.1:4096
|
|
||||||
```
|
|
||||||
|
|
||||||
配置后，`TJWaterAgent` 会连接该外部 opencode server，而不是自行启动 embedded opencode server。
|
|
||||||
|
|||||||
Reference in New Issue
Block a user