新增 skills、README，指定 opencode 的启动行为
This commit is contained in:
@@ -1,2 +1,160 @@
|
||||
# TJWaterAgent
|
||||
# TJWaterAgent 目录结构说明
|
||||
|
||||
`TJWaterAgent/` 是新的 opencode Agent 服务工程目录，负责对外提供 TJWater 智能助手接口，并通过 opencode SDK 启动或连接 opencode 运行时。
|
||||
|
||||
## 总体边界
|
||||
|
||||
```text
|
||||
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. 管理 `conversationId -> opencode sessionId` 的映射。
|
||||
4. 保存并传递用户 `Authorization`、`x-project-id`、`x-trace-id`。
|
||||
5. 把 opencode 输出适配成前端需要的 SSE 事件。
|
||||
6. 为 `.opencode/tools/dynamic_http_call.ts` 提供内部回调接口。
|
||||
7. 代理调用真实 TJWater 后端 API。
|
||||
|
||||
主要目录和文件：
|
||||
|
||||
```text
|
||||
src/
|
||||
server.ts
|
||||
config.ts
|
||||
runtime/
|
||||
session/
|
||||
chat/
|
||||
routes/
|
||||
tools/
|
||||
```
|
||||
|
||||
其中 `src/` 是业务服务层，不直接放 opencode skill 或 agent prompt。
|
||||
|
||||
## `.opencode/` 的职责
|
||||
|
||||
`.opencode/` 是给 opencode 运行时读取的项目资产目录，不是对外 HTTP 服务的主代码目录。
|
||||
|
||||
### agents
|
||||
|
||||
```text
|
||||
.opencode/agents/tjwater-assistant.md
|
||||
```
|
||||
|
||||
这里定义默认 agent 的角色、行为规则、模型配置和工具使用策略。
|
||||
|
||||
当前项目已将 always-loaded instructions 收敛到 `tjwater-assistant.md`，`opencode.json` 不再额外配置 `instructions` 数组。
|
||||
|
||||
### tools
|
||||
|
||||
```text
|
||||
.opencode/tools/
|
||||
dynamic_http_call.ts
|
||||
locate_features.ts
|
||||
view_history.ts
|
||||
view_scada.ts
|
||||
show_chart.ts
|
||||
```
|
||||
|
||||
这些是 opencode 可以调用的自定义工具。
|
||||
|
||||
`dynamic_http_call.ts` 不直接保存用户 token，也不直接访问后端。它会回调 `TJWaterAgent` 的内部接口，由上级服务层根据当前 session 补上用户 token、项目 ID 和 trace ID，再调用 TJWater 后端。
|
||||
|
||||
前端类工具如 `locate_features`、`view_history`、`view_scada`、`show_chart` 主要用于触发 UI 动作或可视化，不应被当作数据查询工具。
|
||||
|
||||
### skills
|
||||
|
||||
```text
|
||||
.opencode/skills/tjwater-skills-root-index/
|
||||
SKILL.md
|
||||
ai/
|
||||
analytics/
|
||||
business/
|
||||
data/
|
||||
platform/
|
||||
```
|
||||
|
||||
这里保存从 `TJWaterCopilot` 迁移过来的技能树，并保持原有树结构，符合渐进式披露设计。
|
||||
|
||||
agent 需要某个领域知识时再按需加载对应 skill，不把整棵技能树作为 always-loaded prompt 一次性注入。
|
||||
|
||||
## 依赖边界
|
||||
|
||||
根目录和 `.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` CLI。服务会通过 `@opencode-ai/sdk` 的 embedded 模式启动 opencode server。
|
||||
|
||||
推荐安装和启动流程：
|
||||
|
||||
```bash
|
||||
cd TJWaterAgent
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
cd .opencode
|
||||
npm install
|
||||
|
||||
cd ..
|
||||
npm run start
|
||||
```
|
||||
|
||||
如果需要连接外部独立运行的 opencode server，可以配置：
|
||||
|
||||
```bash
|
||||
OPENCODE_BASE_URL=http://127.0.0.1:4096
|
||||
```
|
||||
|
||||
配置后，`TJWaterAgent` 会连接该外部 opencode server，而不是自行启动 embedded opencode server。
|
||||
>>>>>>> 414247d (新增 skills、README，指定 opencode 的启动行为)
|
||||
|
||||
Reference in New Issue
Block a user