OrgTJWater/TJWaterAgent
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0446728f60fa3eab4cbc1d6baf1ad46398ba5b64
TJWaterAgent/README.md
T
jiang f92598803f
Agent CI/CD / validate (push) Failing after 2m17s
Details
Agent CI/CD / docker-image (push) Has been skipped
Details
Agent CI/CD / deploy-fallback-log (push) Has been skipped
Details
新增 opencode 配置文件，移除嵌入式服务器支持
2026-05-18 17:15:42 +08:00

7.3 KiB
Raw Blame History

TJWaterAgent 目录结构说明

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

总体边界

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 的主接口：

POST /api/v1/chat/message

该接口返回 SSE 格式数据。

.opencode/ 的职责

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

agents

.opencode/agents/instruction.md

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

tools

.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

.opencode/skills/
  SKILL.md               # 根索引
  analytics/             # 分析类技能（SCADA、水力模拟、爆管分析等）
  business/              # 业务类技能（模型配置、资产管理、项目环境等）
  data/                  # 数据类技能（时序数据访问）
  platform/              # 平台类技能（审计、缓存、元数据等）

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

启动与开发

项目使用 bun 作为包管理器和运行环境。

# 安装依赖
bun install

# 启动开发环境（带 watch 模式）
bun run dev

# 类型检查
bun run check

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

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

依赖边界

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

根目录依赖

TJWaterAgent/package.json

用于服务本体，例如：

@opencode-ai/sdk
express
zod
pino

.opencode 依赖

TJWaterAgent/.opencode/package.json

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

@opencode-ai/plugin
typescript
@types/node

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

启动与部署

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

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

本地开发

cd TJWaterAgent
bun install
bun run dev

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

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

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

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

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

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

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

生产启动

cd TJWaterAgent
bun install
bun run check
bun run start

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

cd TJWaterAgent
bun install
bun run start:prod

Docker Compose 启动

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

cd TJWaterAgent
docker compose up -d --build

查看日志：

docker compose logs -f tjwater-agent

停止并清理容器：

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 模型为：

deepseek/deepseek-v4-pro

涉及位置：

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

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

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

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

DEEPSEEK_API_KEY=sk-xxx bun run start

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

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

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

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，可以配置：

OPENCODE_BASE_URL=http://127.0.0.1:4096
Reference in New Issue View Git Blame Copy Permalink