供水 Agent 的 OpenCode 资产

这里维护服务使用的 Agent 指令、插件和工具。管理员通过这些入口管理可复用 Skill 和外部 MCP 连接。

agent-plugin.json 是本项目的描述清单，列出各项能力的用途、文件路径和配置来源，方便检索和交接。它是管理索引，不参与运行时加载；字段中的相对路径以 .opencode/ 为基准，环境变量指定的路径仍遵循服务原有解析规则。

目录与加载入口

入口	作用	实际加载方式
agents/instruction.md	供水 Agent 的业务指令	配置生成器读取正文，设为 `instruction` Agent 的 system 指令
tjwater-plugin/package.json	插件包名称、版本、描述和导出入口	OpenCode 显式加载该目录包
tjwater-plugin/index.ts	插件包入口	导出 `plugins/tjwater-tools.ts` 的默认插件
plugins/tjwater-tools.ts	`tjwater.tools` 插件实现	注册业务与待办工具、沙箱、MCP 策略和内部 RPC
`skills/`	可复用流程及引用、脚本	默认 Skill 根目录，可由 `OPENCODE_SKILLS_ROOT_DIR` 替换
../opencode.json	工具权限和 MCP 连接	服务合并部署覆盖配置后校验并交给 OpenCode
../agent-models.json	模型和 provider	统一生成 OpenCode 模型定义，不在描述清单中重复配置

serviceOpencodeConfig 将可信插件包、Agent 指令和 Skill 根目录解析为绝对路径。会话目录位于 .agent-workspaces/ 时也能加载这些服务资产。插件包名 tjwater-tools-plugin、运行时插件 ID tjwater.tools、Agent ID instruction 各有用途，新增描述时应保留它们的对应关系。

原生插件通过 Plugin.define({ id, setup }) 注册，额外插件使用 OpenCode 的 plugins 配置。参考 OpenCode 插件文档。本项目显式加载可信目录包，新增文件不等于已经注册了业务能力，需检查运行时工具目录。

管理 Skill

Skill 是模型按需读取的流程说明，工具负责实际执行。一个 Skill 推荐使用以下结构：

skills/
└── supply-data-review/
    ├── SKILL.md
    ├── references/
    │   └── field-guide.md
    └── scripts/
        └── summarize.py

SKILL.md 至少包含名称、用途和适用条件，正文引用的文件路径相对于该 Skill 目录：

---
name: supply-data-review
description: 核对供水数据的时间范围、单位和缺失情况。
---

# 供水数据核对

适用于已通过受控工具取得的数据。

1. 核对查询范围、时间和单位。
2. 将真实缺失与接口错误分别记录。
3. 输出数据结论和未确认事项，保留实际证据来源。

目录名称决定 OpenCode 的 Skill ID，frontmatter 的 name 用于显示。推荐使用唯一的小写名称，避免同名 Skill 被后加载的来源覆盖；完整规则见 OpenCode Skill 文档。

当前 Skill 根目录由 OPENCODE_SKILLS_ROOT_DIR 统一指定，供 OpenCode 加载和 Agent 的 SkillStore 使用。描述清单只引用该入口，不维护另一份 Skill 名单。使用绝对路径可减少外部 OpenCode 和 Agent 的启动目录差异。

skill_manager 支持列出、写入和删除 Skill，以及维护 pattern、reference 和 script。它通过可信内部工具桥调用 SkillStore，对内容、路径和写入历史进行处理；默认备份位于 data/backup/skills/。当前 Skill 存储按部署实例共享，应保存通用方法，避免写入用户凭据、具体会话数据和未经验证的业务结论。

服务当前的指令要求：流程已经验证可复用，且用户明确需要保存时，才通过 skill_manager 沉淀。Skill 中的执行步骤不能改变工具权限；引用脚本仍需通过批准的会话沙箱执行，业务 API 仍使用类型化工具。

skills/ 被 Git 忽略，保存或交付 Skill 时需要单独准备目录和持久化挂载，克隆仓库不包含已有实例的 Skill。修改后重启相关运行时以重新发现；需要后续实现在线刷新时使用原生 Skill reload 接口，当前管理桥不保证即时刷新 OpenCode 目录。

管理 MCP

真实连接配置统一在仓库根目录 opencode.json 的 mcp.servers 中，部署覆盖使用 OPENCODE_CONFIG_CONTENT。agent-plugin.json 只指向该位置，不存地址、命令或认证头。

服务名使用 mcp_ 前缀。添加、修改或禁用连接时，按根目录 README 的 MCP 配置说明操作；支持远程 Streamable HTTP 和本地 stdio，详细字段参考 OpenCode MCP 文档。

密钥通过 {env:NAME} 引用 .local.env 或部署环境。需要 OAuth 时，由管理员使用同一服务账号和 XDG 数据目录执行认证，不把 TJWater 用户令牌转交给 MCP 服务。修改连接后重启运行时；client 模式需同步外部 OpenCode 的配置与可信插件。

查看会话中实际加载的服务和工具：

GET /api/v1/agent/chat/session/:session_id/mcp

该接口使用产品 Bearer、项目头及会话归属校验，只返回服务名、类型、状态、配置协议和实际工具 ID。connected 只表示连接状态，仍需检查工具 ID 是否已出现；响应不包含地址、进程命令或凭据。

MCP 执行策略由 mcp-policy.ts 和服务配置校验维护：

会话	调用规则
普通聊天、任务协作	管理员明确允许的只读工具可自动执行，其他调用需审批
后台任务	仅调用精确的只读白名单工具
学习复盘	禁用 MCP 调用

只读白名单需在 permissions 中使用状态接口返回的精确工具名，不能用宽泛的 mcp_* allow 替代。Code Mode 和通用资源访问也应用同一策略。本地 stdio MCP 运行于可信宿主进程，不受会话 Shell 沙箱约束，环境过滤不等于 OS 隔离。

修改后的检查

更新 Agent、插件或管理入口时，同步修改描述清单和相关说明，保持路径及 ID 对应。插件的运行时代码变更需要类型检查和相关测试：

bun run check
bun test tests/frontendAction/callIdPlugin.test.ts tests/runtime/opencode.test.ts

MCP 策略变更使用 MCP 相关测试，实际连接联调可选择根目录 README 列出的本地 smoke 脚本。模型配置修改使用 bun run check:models。这些命令从仓库根目录运行；仅修改描述或说明时检查路径、JSON 和 git diff --check 即可。

运行时确认以 Agent 的启动预热和 /health 为准。client 模式要同时更新外部 OpenCode 使用的资产。服务启动、工作区保留和容器挂载参见根目录 README，代码修改约束见 AGENTS.md。

本地交互式回答

tools/present_answer.ts 注册本地交互式回答工具。组件契约来自前端导出的 ../src/chat/answer-ui-catalog.json，由服务与前端同时校验；注册入口仍是 plugins/tjwater-tools.ts。更新后需要重新加载 Agent/OpenCode 的可信插件资产。发现验证使用 bun run tests/integration/answer-ui-smoke.ts，从 Agent 仓库根目录运行。

7.5 KiB Raw Blame History Unescape Escape