docs: translate agent readme to Chinese
This commit is contained in:
@@ -1,53 +1,52 @@
|
||||
# TJWaterAgentExperimental
|
||||
# TJWater Agent 实验服务
|
||||
|
||||
Experimental opencode-based Agent service for TJWater UI orchestration.
|
||||
基于 OpenCode 的实验性 Agent 服务，用于编排 TJWater 前端交互。
|
||||
|
||||
This repository is intentionally separate from the production `TJWaterAgent`
|
||||
history. It does not include user authentication or the old `tjwater-cli`
|
||||
bridge. Runtime requests use a local default context and can later be wired to a
|
||||
real auth provider through `src/context/`.
|
||||
本仓库与生产环境中的 `TJWaterAgent` 历史代码相互独立，不包含用户认证，也不包含旧版 `tjwater-cli` 桥接层。运行时请求默认使用本地上下文，后续可通过 `src/context/` 接入实际的认证提供方。
|
||||
|
||||
## Current Boundaries
|
||||
## 当前边界
|
||||
|
||||
- No Keycloak / metadata auth context.
|
||||
- No required `Authorization` or `X-Project-Id` headers.
|
||||
- No `cli/`, no `tjwater_cli` opencode tool, no free-form CLI command bridge.
|
||||
- Agent visual output is expressed through `agent-ui@1` UIEnvelope events.
|
||||
- Tools that depend on the TJWater Server are disabled. Arbitrary URLs, SQL,
|
||||
shell commands, and filesystem paths remain unavailable.
|
||||
- 不包含 Keycloak 或元数据认证上下文。
|
||||
- 不强制要求 `Authorization` 或 `X-Project-Id` 请求头。
|
||||
- 不包含 `cli/`、`tjwater_cli` OpenCode 工具或自由形式的 CLI 命令桥接。
|
||||
- Agent 的结构化界面输出使用 `agent-ui@1` UIEnvelope 事件；受控浏览器操作使用 `frontend-action@1` 前端动作。
|
||||
- 依赖 TJWater Server 的工具处于禁用状态，Agent 不能访问任意 URL、SQL、Shell 命令或文件系统路径。
|
||||
|
||||
## Main API
|
||||
## 主要 API
|
||||
|
||||
```text
|
||||
GET /health
|
||||
GET /api/v1/agent/chat/models
|
||||
GET /api/v1/agent/chat/ui-registry
|
||||
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
|
||||
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` returns SSE. Important events:
|
||||
`POST /api/v1/agent/chat/stream` 通过 SSE 返回事件流。主要事件如下：
|
||||
|
||||
| event | Purpose |
|
||||
| 事件 | 用途 |
|
||||
| --- | --- |
|
||||
| `progress` | Agent planning/tool progress |
|
||||
| `token` | Assistant text delta |
|
||||
| `ui_envelope` | Structured UI description for trusted frontend rendering |
|
||||
| `tool_call` | Deprecated compatibility/debug event |
|
||||
| `permission_request` | Runtime permission request |
|
||||
| `question_request` | Runtime/user clarification request |
|
||||
| `done` | Run completed |
|
||||
| `error` | Run failed or aborted |
|
||||
| `progress` | Agent 规划和工具执行进度 |
|
||||
| `token` | 助手回复的增量文本 |
|
||||
| `ui_envelope` | 供可信前端渲染的结构化界面描述 |
|
||||
| `frontend_action` | 请求可信前端执行受控动作 |
|
||||
| `tool_call` | 用于兼容和调试的旧版工具调用事件 |
|
||||
| `permission_request` | 运行时权限请求 |
|
||||
| `question_request` | 运行时向用户发起的澄清请求 |
|
||||
| `todo_update` | Agent 待办事项更新 |
|
||||
| `session_title` | 会话标题更新 |
|
||||
| `done` | 本次运行完成 |
|
||||
| `error` | 本次运行失败或被中止 |
|
||||
|
||||
## Local Context
|
||||
## 本地上下文
|
||||
|
||||
The service uses `src/context/localContext.ts`.
|
||||
|
||||
Defaults:
|
||||
服务通过 `src/context/localContext.ts` 提供本地上下文，默认值如下：
|
||||
|
||||
```text
|
||||
AGENT_LOCAL_USER_ID=local-user
|
||||
@@ -55,12 +54,9 @@ AGENT_LOCAL_PROJECT_ID=local-project
|
||||
AGENT_LOCAL_NETWORK=local-network
|
||||
```
|
||||
|
||||
Monitoring time-series data is read from the agent project's `source/`
|
||||
directory and analyzed through validated local skills. `get_project_context`,
|
||||
`list_scada_assets`, `query_scada_readings`, `web_search`, and `geocode` are not
|
||||
exposed because they depend on the TJWater Server.
|
||||
监测时序数据从 Agent 项目的 `source/` 目录读取，并通过经过校验的本地技能进行分析。`get_project_context`、`list_scada_assets`、`query_scada_readings`、`web_search` 和 `geocode` 依赖 TJWater Server，因此当前不对外开放。
|
||||
|
||||
Optional request headers can override the local context during experiments:
|
||||
实验期间可以通过以下请求头覆盖本地上下文：
|
||||
|
||||
```text
|
||||
X-Agent-Local-User
|
||||
@@ -69,21 +65,31 @@ X-Agent-Local-Network
|
||||
X-Trace-Id
|
||||
```
|
||||
|
||||
## UIEnvelope
|
||||
## UIEnvelope 与前端动作
|
||||
|
||||
The registry is exposed at:
|
||||
UIEnvelope 注册表通过以下接口提供：
|
||||
|
||||
```text
|
||||
GET /api/v1/agent/chat/ui-registry
|
||||
```
|
||||
|
||||
No visual or frontend-action tools are currently exposed to the Agent. The
|
||||
registry endpoints remain available for protocol compatibility and return no
|
||||
registered charts, components, or actions.
|
||||
该接口用于兼容 `agent-ui@1` 协议。目前没有注册图表语法、界面组件或 UIEnvelope 动作。
|
||||
|
||||
See [docs/agent-ui-protocol.md](docs/agent-ui-protocol.md).
|
||||
前端动作使用独立的注册表：
|
||||
|
||||
## Development
|
||||
```text
|
||||
GET /api/v1/agent/chat/frontend-action-registry
|
||||
```
|
||||
|
||||
当前提供 `render_scada_analysis` 和 `clear_scada_analysis` 两个地图叠加层动作。浏览器需要在流式请求中声明 `frontend-action@1` 能力，执行动作后再通过以下接口回传结果：
|
||||
|
||||
```text
|
||||
POST /api/v1/agent/chat/frontend-actions/:action_id/result
|
||||
```
|
||||
|
||||
协议详情参见 [Agent UI 协议](docs/agent-ui-protocol.md)。
|
||||
|
||||
## 本地开发
|
||||
|
||||
```bash
|
||||
bun install
|
||||
@@ -92,4 +98,4 @@ bun run check
|
||||
bun test tests/**/*.test.ts
|
||||
```
|
||||
|
||||
`bun run check` typechecks the service and `.opencode` tools.
|
||||
`bun run check` 会检查服务代码和 `.opencode` 工具的类型。
|
||||
|
||||
Reference in New Issue
Block a user