TJWater Agent 实验服务

基于 OpenCode 的实验性 Agent 服务，用于编排 TJWater 前端交互。

本仓库与生产环境中的 TJWaterAgent 历史代码相互独立，不包含用户认证，也不包含旧版 tjwater-cli 桥接层。运行时请求默认使用本地上下文，后续可通过 src/context/ 接入实际的认证提供方。

当前边界

不包含 Keycloak 或元数据认证上下文。
不强制要求 Authorization 或 X-Project-Id 请求头。
不包含 cli/、tjwater_cli OpenCode 工具或自由形式的 CLI 命令桥接。
Agent 的结构化界面输出使用 agent-ui@1 UIEnvelope 事件；受控浏览器操作使用 frontend-action@1 前端动作。
依赖 TJWater Server 的工具处于禁用状态，Agent 不能访问任意 URL、SQL、Shell 命令或文件系统路径。

主要 API

GET    /health
GET    /api/v1/agent/chat/models
GET    /api/v1/agent/chat/ui-registry
GET    /api/v1/agent/chat/frontend-action-registry
POST   /api/v1/agent/chat/frontend-actions/:action_id/result
POST   /api/v1/agent/chat/session
GET    /api/v1/agent/chat/sessions
GET    /api/v1/agent/chat/session/:session_id
GET    /api/v1/agent/chat/session/:session_id/stream
POST   /api/v1/agent/chat/stream
POST   /api/v1/agent/chat/abort

POST /api/v1/agent/chat/stream 通过 SSE 返回事件流。主要事件如下：

事件	用途
`progress`	Agent 规划和工具执行进度
`token`	助手回复的增量文本
`ui_envelope`	供可信前端渲染的结构化界面描述
`frontend_action`	请求可信前端执行受控动作
`tool_call`	用于兼容和调试的旧版工具调用事件
`permission_request`	运行时权限请求
`question_request`	运行时向用户发起的澄清请求
`todo_update`	Agent 待办事项更新
`session_title`	会话标题更新
`done`	本次运行完成
`error`	本次运行失败或被中止

本地上下文

服务通过 src/context/localContext.ts 提供本地上下文，默认值如下：

AGENT_LOCAL_USER_ID=local-user
AGENT_LOCAL_PROJECT_ID=local-project
AGENT_LOCAL_NETWORK=local-network

监测时序数据从 Agent 项目的 source/ 目录读取，并通过经过校验的本地技能进行分析。get_project_context、list_scada_assets、query_scada_readings、web_search 和 geocode 依赖 TJWater Server，因此当前不对外开放。

实验期间可以通过以下请求头覆盖本地上下文：

X-Agent-Local-User
X-Agent-Local-Project
X-Agent-Local-Network
X-Trace-Id

UIEnvelope 与前端动作

UIEnvelope 注册表通过以下接口提供：

GET /api/v1/agent/chat/ui-registry

该接口用于兼容 agent-ui@1 协议。目前没有注册图表语法、界面组件或 UIEnvelope 动作。

前端动作使用独立的注册表：

GET /api/v1/agent/chat/frontend-action-registry

当前提供 render_scada_analysis 和 clear_scada_analysis 两个地图叠加层动作。浏览器需要在流式请求中声明 frontend-action@1 能力，执行动作后再通过以下接口回传结果：

POST /api/v1/agent/chat/frontend-actions/:action_id/result

协议详情参见 Agent UI 协议。

本地开发

bun install
bun run dev
bun run check
bun test tests/**/*.test.ts

bun run check 会检查服务代码和 .opencode 工具的类型。

3.4 KiB Raw Permalink Blame History