97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
# 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/` 保存运行时会话元数据、结果引用和本地状态。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
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：
|
||
|
||
```bash
|
||
bun install
|
||
bun run dev
|
||
```
|
||
|
||
`bun install` 会通过 `postinstall` 安装 `.opencode` 子目录依赖。`bun run dev` 以 watch 模式启动 `src/server.ts`，修改 `src/**`、`.opencode/**`、`opencode.json` 或 `.local.env` 后会自动重启。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
OPENCODE_MODE=embedded
|
||
TJWATER_API_BASE_URL=http://127.0.0.1:8000
|
||
```
|
||
|
||
Client 模式连接外部 OpenCode server：
|
||
|
||
```bash
|
||
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`。发布前至少运行：
|
||
|
||
```bash
|
||
bun run check
|
||
```
|
||
|
||
如修改 CLI 或工具调用逻辑，同时运行：
|
||
|
||
```bash
|
||
bun run test:cli
|
||
```
|