feat(agent): unify MCP tools and adopt Responses delivery

Move project and host queries into native MCP with host-owned OAuth/context, while retaining memory, skills, actions and publication plugins. Add nearby-model queries and explicit chat/task/learning model defaults. Adopt Responses HTTP/SSE and native steer/queue inbox delivery, preserving scoped session ownership, pending input edits and investigation communication. Disable local-provider discovery: Server /health allowed native vLLM to probe /v1/models on port 8000. A native before/after regression prevents recurrence. Validation: 170 focused Bun tests; service/plugin typechecks; native discovery, provider-discovery and input-inbox smoke checks; no paid model inference.
2026-10-19 18:46:58 +08:00
parent f5c3cde2c2
commit 6a49d2209e
164 changed files with 12286 additions and 2368 deletions
@@ -12,11 +12,33 @@
 | API key、服务地址、端口等环境变量 | 仓库根目录 `.local.env` | 本地私有文件，已被 Git 忽略；字段参考 [.env.example](.env.example) |
 | 工具权限、外部 MCP 连接 | [opencode.json](opencode.json) | 不再单独配置模型和 provider |
 | Agent 的业务指令 | [.opencode/agents/instruction.md](.opencode/agents/instruction.md) | 指令文件不指定模型 |
+| 后台调查与只读子代理 | [.opencode/agents/investigation.md](.opencode/agents/investigation.md)、[investigation-reader.md](.opencode/agents/investigation-reader.md) | 主对话禁用子代理，后台任务按可信用途选择独立配置 |
 | Agent、插件、Skill 和 MCP 的管理索引 | [.opencode/agent-plugin.json](.opencode/agent-plugin.json) | 描述用途和实际配置入口；管理方法见 [.opencode/README.md](.opencode/README.md) |
 | 代码修改规则 | [AGENTS.md](AGENTS.md) | 面向维护代码的 Agent |

 服务自动读取根目录的 `.local.env`，已有系统环境变量优先。普通启动不会自动读取 `.env`；部署时应由容器或进程管理器注入环境变量。

+本地 MCP issuer 可在 `NODE_ENV=development` 下使用内网 HTTP：把 `TJWATER_MCP_DEV_HTTP_ISSUER_URI` 设置为与 `TJWATER_MCP_ISSUER_URI` 完全相同的 RFC1918 IPv4 issuer。该例外只允许此认证服务的同源 HTTP 发现与令牌端点，不放行远程 HTTP MCP resource。Server 本地实例也须使用同一 issuer、相同白名单及 `ENVIRONMENT=development`；正式 `.env` 使用 HTTPS 域名，白名单留空。issuer 必须与令牌 `iss` 完全一致。
+
+环境文件只保留简短分组和必要注释。MCP 的 `CLIENT_ID` 填 Keycloak 客户端 ID，`CLIENT_SECRET` 单独填写 Credentials 页的密钥。后端连接使用 `TJWATER_SERVER_BASE_URL` / `TJWATER_SERVER_TIMEOUT_MS`，当前版本不读取旧的 `TJWATER_API_*` 名称。
+
+### 后台调查子代理
+
+`serviceOpencodeConfig` 区分三个原生配置：`instruction` 用于主对话、人工协作和学习，
+禁止子代理；`investigation` 用于服务端标记的后台任务，只能调用 `investigation-reader`；
+后者只有任务上下文和任务数据查询两项工具。保持全局 `subagent: deny`，不通过用户提示
+或前端参数放开。父调查使用 `agent-models.json` 的 task 模型，子代理沿用父会话模型。
+
+每个后台调查最多同时两个只读子代理，仅一层，使用并行工具调用批次及前台等待，
+不启用脱离父调用的 background 子任务，不恢复旧子会话。查询保存原有证据快照，
+项目身份和凭据由服务端从原生直接父子关系核验，仅在父任务运行期间代理读取；
+凭据不复制给子会话。子代理不发布进度、正式报告或动作，不进行审批、控制或 Shell 操作。
+主 Agent 核对实际证据后统一发布，可用 Mermaid 表示真实并行分支与汇总，图不驱动调度。
+
+配置生效需要 Agent/OpenCode 加载更新的可信插件；外部 client 模式须同步更新两侧配置。
+无需数据库迁移。独立验证：`bun tests/integration/task-agent-smoke.ts`，只使用临时数据库
+和原生权限接口，不调用模型或真实任务。实际模型并行与动态图仍须业务联调确认。
+
 如果不想修改仓库自带的模型配置，可以复制为 `agent-models.local.json`，再在 `.local.env` 中设置：

 ```dotenv
@@ -25,14 +47,31 @@ AGENT_MODEL_CONFIG_PATH=./agent-models.local.json

 该文件已被 Git 和镜像构建忽略。它会替换整份模型配置，不与 `agent-models.json` 合并；相对路径按启动目录解析。

+## 调查消息与稳定引用
+
+主聊天通过 `mcp_tjwater_list_investigation_tasks`、`mcp_tjwater_get_investigation_task` 获取 Server 已有的
+`task_id`、`run_id` 及 `agent_session_id`，不读取其他用户聊天或内部推理。
+`send_task_message` 指定任务和轮次，Server 保存后再经 OpenCode `session.synthetic`
+以 `steer` 投递。`mcp_tjwater_read_agent_messages` 查询当前会话消息，`reply_agent_message`
+只沿已建立的通信关系回复。入队、进入上下文和收到回复是不同状态。
+
+执行中的主聊天接收来信；空闲时仅保存和提醒，下次交互再处理，不自动唤醒。
+普通消息不新增调查轮次、不自动写为人工证据，也不授权工单执行或设备控制。
+正式新轮次仍创建新的 Run 和执行会话；旧轮次未投递消息不会自动转投。
+消息由 Server 持久化，现有工况 Worker 补偿投递；浏览器关闭不影响调查。
+
+部署前需要先应用 Server 的 `024_agent_messages.sql` 并发布 Server，再更新
+Agent/OpenCode 可信工具及 Worker，最后更新前端。不会自动迁移数据库。
+回退前保留消息表与会话数据；不新增外部账号、消息中间件或环境变量。
+
 ## 本地启动

 在本仓库目录执行命令。运行环境需要 Bun、OpenCode 2、Python 3 和 `libseccomp2`，Linux 内核需支持 Landlock ABI 4 或更高版本。服务启动时会实际探测沙箱，失败会停止启动。

-仓库使用 OpenCode `2.0.24`，安装并检查 CLI：
+仓库使用 OpenCode 正式版 `2.0.27`，CLI、客户端和插件依赖保持同版。继续使用正式包提供的 `opencode2` 兼容命令，避免与本机旧版 `opencode` 冲突。安装并检查 CLI：

 ```bash
-bun add --global --trust --exact @opencode/cli@2.0.24
+bun add --global --trust --exact @opencode/cli@2.0.27
 opencode2 --version
 bun install
 ```
@@ -71,21 +110,27 @@ curl --fail http://127.0.0.1:8787/health

 正常响应中 `ok`、`ready`、`warmed_up` 均为 `true`，并包含 OpenCode 版本和沙箱探测结果。`bun run dev` 使用 watch 模式；无 watch 的启动命令是 `bun run start`。修改模型配置或密钥后需重启服务，不依赖 watch 自动加载配置文件。

-开发环境允许无凭据的本地对话，但访问 Server 业务数据仍需产品凭据。生产环境中的聊天接口要求 `Authorization: Bearer ...` 和 `X-Project-Id`，用户身份和项目权限由 Server 验证。项目 ID 应使用 Server 返回的项目 UUID；本地上下文头不能替代产品鉴权。
+开发环境允许无凭据的本地对话，使用共享的本地开发身份。生产聊天始终要求 `Authorization: Bearer ...`：个人会话不发送项目头，Server 通过 `/api/v1/access-context` 验证用户；项目会话还发送 `X-Project-Id`，通过 `/api/v1/agent-auth-context` 验证项目权限。项目 ID 使用 Server 返回的 UUID，本地上下文头不能替代产品鉴权。个人会话不能调用需要项目凭据的 TJWater 业务 API。

 ## 配置模型和自定义 provider

-[agent-models.json](agent-models.json) 同时控制聊天菜单和 OpenCode 的模型定义。当前仅包含地址为 `https://llm.waternetwork.cn/v1` 的 `waternetwork` provider，保留两个模型：`gpt-6-luna` 显示为“快速”，使用闪电图标；`gpt-6.1-sol` 显示为“专家”，使用星光图标。两者的上下文窗口均配置为 272,000 tokens。
+[agent-models.json](agent-models.json) 同时控制聊天菜单和 OpenCode 的模型定义。`defaults` 集中选择各用途的默认模型，`providers` 保存供应商连接及其模型目录。当前仅包含地址为 `https://llm.waternetwork.cn/v1` 的 `waternetwork` provider，保留两个模型：`gpt-6-luna` 显示为“快速”，使用闪电图标，上下文配置为 272,000 tokens；`gpt-6.1-sol` 显示为“专家”，使用星光图标，上下文配置为 475,000 tokens。

 三个默认模型分别用于：

 | 字段 | 用途 | 当前配置 |
 | --- | --- | --- |
-| `default_model` | 普通聊天默认值 | `waternetwork/gpt-6-luna` |
-| `task_model` | 后台工况任务首选模型 | `waternetwork/gpt-6-luna` |
-| `learning_gate_model` | 判断是否需要学习复盘 | `waternetwork/gpt-6-luna` |
+| `defaults.chat` | 普通聊天默认值，必填 | `waternetwork/gpt-6-luna` |
+| `defaults.task` | 后台工况任务首选模型，必填 | `waternetwork/gpt-6-luna` |
+| `defaults.learning_gate` | 判断是否需要学习复盘，必填 | `waternetwork/gpt-6-luna` |

-后两项省略时沿用 `default_model`。三个引用都必须指向已定义、启用且声明支持文本输出和工具调用的模型；聊天默认模型还必须在菜单中可选。
+三项均须显式填写，即使使用同一个模型也不能省略；缺失、空值或空白字符串会在加载配置时被拒绝，不自动继承其他用途。三个引用都必须指向已定义、启用且声明支持文本输出和工具调用的模型；聊天默认模型还必须在菜单中可选。
+
+Agent 关闭 OpenCode 内置的 vLLM、LM Studio 和 Ollama 自动发现插件，避免其定期探测本机端口；例如 vLLM 默认探测 `127.0.0.1:8000`，会把 TJWater Server 的 `/health` 成功响应当作继续请求 `/v1/models` 的依据。需要使用本地模型时，在 `providers` 中显式配置地址和模型即可，不依赖自动发现。此设置由 `serviceOpencodeConfig` 统一生成，独立 OpenCode 客户端模式也必须同步该配置，修改后需重启运行进程。
+
+可运行 `bun tests/integration/provider-discovery-smoke.ts` 验证：隔离实例先复现旧配置的探测请求，再确认当前配置不再探测，并保留显式配置的本地模型；测试仅请求本地模拟服务，不调用模型推理或业务服务。
+
+旧配置文件的顶层 `default_model`、`task_model`、`learning_gate_model` 须分别迁移到 `defaults.chat`、`defaults.task`、`defaults.learning_gate`；旧字段和新旧混用均会被拒绝。通过 `AGENT_MODEL_CONFIG_PATH` 指定的替代配置也使用此结构。公开模型 ID 仍为 `provider/模型名`，已有会话的模型引用无需迁移。

 ### 使用 WaterNetwork 的最小配置

@@ -93,9 +138,11 @@ curl --fail http://127.0.0.1:8787/health

 ```json
 {
-  "default_model": "waternetwork/gpt-6.1-sol",
-  "task_model": "waternetwork/gpt-6.1-sol",
-  "learning_gate_model": "waternetwork/gpt-6.1-sol",
+  "defaults": {
+    "chat": "waternetwork/gpt-6.1-sol",
+    "task": "waternetwork/gpt-6.1-sol",
+    "learning_gate": "waternetwork/gpt-6.1-sol"
+  },
  "providers": {
    "waternetwork": {
      "name": "WaterNetwork",
@@ -106,7 +153,7 @@ curl --fail http://127.0.0.1:8787/health
          "name": "通用助手",
          "description": "对话与任务处理",
          "icon": "sparkle",
-          "limit": { "context": 272000 }
+          "limit": { "context": 475000 }
        }
      }
    }
@@ -114,7 +161,7 @@ curl --fail http://127.0.0.1:8787/health
 }
 ```

-新增其他 provider 时，在 `providers` 下增加同样结构的一项，并换成自己的地址、密钥变量名和模型名。provider 名只允许字母、数字、下划线和连字符。
+新增其他 provider 时，在 `providers` 下增加同样结构的一项，并换成自己的地址、密钥变量名和模型名。provider 名只允许字母、数字、下划线和连字符。不同供应商可以配置同名模型，使用完整的 `provider/模型名` 引用区分，能力和上下文限制分别配置；各用途可通过 `defaults` 选择不同供应商的模型。

 `api_url` 填 API 基础地址，例如以 `/v1` 结尾的地址，不填 `/chat/completions`；不允许在地址中嵌入账号、密码、查询参数或片段。默认使用 OpenAI compatible 运行包，真实密钥始终放在环境变量中。

@@ -174,25 +221,52 @@ bun run start:integration:isolated

 默认端口为 Agent `18787`、OpenCode `14096`，数据保存在 `data/integration-18787/`，不复用默认会话数据。可通过 `INTEGRATION_AGENT_PORT`、`INTEGRATION_OPENCODE_PORT` 和 `INTEGRATION_DATA_DIR` 修改。启动器负责配对配置和停止自己创建的两个进程。

-## `.agent-workspaces` 是什么
+联调目录保存该环境的聊天、任务会话索引、原生执行记录和审计日志。聊天同样按用户、个人或项目范围、会话保存到其 `session-workspaces/`。原生数据库固定为该目录的 `xdg-data/opencode/opencode.db`，不继承外部 `OPENCODE_DB` 覆盖，确保联调运行使用独立数据库。

-这是会话的文件工作区，默认位置由 `CONVERSATION_WORKSPACE_ROOT=./.agent-workspaces` 决定。每创建一个会话，就创建一个独立目录，即使该会话尚未调用 Shell，也可能已有空工作区：
+停止联调环境后，可清理 `xdg-cache/` 中的模型目录缓存和 Bun 编译缓存；下次启动会重建。`xdg-data/` 包含原生数据库与文件快照，`session-workspaces/` 保存聊天和计算文件，`logs/` 保存审计信息。清理整个联调目录会丢失这些历史记录，不能把它们当作缓存处理。
+
+## `data/session-workspaces` 是什么
+
+这是用户的会话工作空间，默认根目录为 `CONVERSATION_WORKSPACE_ROOT=./data/session-workspaces`。按用户、范围和会话组织，个人会话不需要归属项目：

 ```text
-.agent-workspaces/
-└── conversation-<uuid>/
-    ├── files/    生成文件、计算脚本、结果和较长的 Shell 输出
-    ├── tmp/      临时文件
-    └── .cache/   运行缓存
+data/
+└── session-workspaces/
+    └── actor-<用户键>/
+        ├── personal/
+        │   └── session-<会话 ID 的 SHA-256>/
+        └── project-<项目键>/
+            └── session-<会话 ID 的 SHA-256>/
+                ├── chat/
+                │   ├── owner.json       会话与用户、范围的绑定
+                │   ├── messages.json    完整前端聊天状态、工具与计划展示
+                │   ├── transcript.json  用于搜索和学习的问答摘要
+                │   └── learning.json    学习检查和复盘进度
+                └── workspace/
+                    ├── files/    生成文件、计算脚本、结果和较长的 Shell 输出
+                    ├── tmp/      临时文件
+                    └── .cache/   运行缓存
 ```

-OpenCode 会话保存与该目录的绑定，恢复时继续使用原目录。会话分支使用独立的空工作区；历史上绑定到仓库根目录的旧会话会在继续执行前迁入新工作区，不复制源码、凭据或其他会话文件。
+两类会话使用相同的内部结构。用户和项目键由可信身份派生，不直接使用用户名作为路径；`owner.json` 保存原会话 ID，便于核对目录。`data/session-metadata/` 保留为会话归属与历史列表的索引，完整聊天状态、问答摘要和学习进度写入对应工作空间的 `chat/`。索引按用户和范围缓存在服务进程内，写入时同步更新；同一数据目录使用一个 Agent 写入进程。手工修改索引后需要重启服务。

-Shell 默认在 `files/` 中运行，只能写入上述三个子目录，工作区根目录只读。目录隔离配合 Landlock 和 seccomp 限制文件访问、网络与进程行为；目录本身不等于 OS 沙箱。限制覆盖 Shell 及其子进程，OpenCode 服务和类型化业务工具仍由可信宿主进程运行。本地 stdio MCP 也不在这个沙箱中。
+OpenCode 的 `location.directory` 绑定 `workspace/`，不绑定整个工作空间，恢复时继续使用计算文件。分支得到独立计算目录，只复制用户选择保留的聊天上下文。旧 `.agent-workspaces/`、联调 `conversation-workspaces/` 和平铺 `conversation-<uuid>/` 在恢复执行时迁入可信用户的对应 `workspace/`，保留文件并更新原生绑定；目标冲突不覆盖，绑定失败可重试。

-Shell 和文件修改需要用户审批，即使聊天设置了 `approval_mode=always` 也会请求确认。Shell 不能联网或访问源码、密钥、其他会话；业务查询、网页搜索和地址解析使用类型化工具。超时单位为秒，默认 120 秒、最大 1800 秒；stdout 默认限制 1 MiB、stderr 最多 256 KiB、单文件最多 128 MiB。较长输出以文件保存在 `files/`，工具返回预览和路径；取消、超时、超限和命令结束均清理该进程组，不保留后台进程。
+启动时将旧 `data/session-ui-states/`、`data/session-transcripts/` 和 `data/session-learning-state/` 迁入对应 `chat/`，不覆盖已有新记录。旧文件经逐字节备份核对后，归档到 `PERSISTENCE_BACKUP_DIR/legacy-chat/`，原迁移目录不再保留已归档副本。备份按用户、范围和会话存放，文件名包含内容哈希；`migration.json` 记录版本、来源和迁移结果，来源目录未变化时跳过重复导入。无归属的记录继续保留在旧目录，不分配给任意用户。三个旧存储环境变量仅指定迁移来源，新写入由工作空间根目录统一管理。

-工作区已被 Git 和镜像构建忽略，但其中的文件需要随会话保留。目前没有自动过期清理，删除聊天记录也不会同步删除工作区。启动探测、预热和创建失败产生的临时工作区会清理。
+迁移核对完成后，可以清理已迁入工作空间的旧记录备份和空迁移目录；保留 `legacy-chat/migration.json` 作为完成记录。服务使用工作空间存储时不会重新创建三个旧目录。当前本机的 139 份旧记录备份已核对并清理，现行记录继续保存在各会话的 `chat/` 中。
+
+迁移备份尚保留时，回滚到旧存储实现前需将其恢复到旧目录：UI 文件名按会话 ID 的旧 `slugify` 规则计算，摘要为 `<actorKey>__<projectKey>__<sessionId>.json`，学习进度为 `<sessionId>.json`。恢复时保留现有工作空间，不覆盖更新的记录。已经清理迁移备份的部署，需要使用其他部署备份恢复旧存储；只回滚代码不会恢复旧记录文件。
+
+Shell 默认在 `workspace/files/` 中运行，只能写入计算目录中的三个子目录，计算目录根只读。`chat/` 只由 Agent 服务读写，目录权限为 `0700`、记录文件为 `0600`，模型文件工具及 Shell 不能访问。OpenCode 仅为受管理的计算目录增加文件权限，插件还验证目录属于当前原生会话；其他业务记录、聊天记录和 `logs/` 继续禁止访问。目录隔离配合 Landlock 和 seccomp 限制文件访问、网络与进程行为；目录本身不等于 OS 沙箱。限制覆盖 Shell 及其子进程，OpenCode 服务和类型化业务工具仍由可信宿主进程运行。本地 stdio MCP 也不在这个沙箱中。
+
+Shell 和文件修改仍经过原生权限审批。聊天选择“请求批准”（`approval_mode=request`）时逐次询问；选择“始终允许”（`approval_mode=always`）后，Agent 自动批准本轮进入审批流程的请求，包括 Shell、文件修改和 MCP 请求。每次仅回复原生 `once`，不把本轮选择保存为后续轮次授权；明确拒绝的操作不会进入自动批准，业务权限、MCP 会话策略和沙箱限制继续执行。只读白名单工具可直接执行，不因选择“请求批准”而增加询问。
+
+Shell 不能联网或访问源码、密钥、其他会话；业务查询和地址解析使用 MCP，网页搜索使用原生 `websearch`。超时单位为秒，默认 120 秒、最大 1800 秒；stdout 默认限制 1 MiB、stderr 最多 256 KiB、单文件最多 128 MiB。较长输出以文件保存在 `files/`，工具返回预览和路径；取消、超时、超限和命令结束均清理该进程组，不保留后台进程。
+
+工作区已被 Git 和镜像构建忽略，没有自动过期清理。归档会话保留记录；删除会话会取消聊天和学习任务，删除原生会话、聊天内容、学习进度、计算目录及该会话的旧记录和迁移备份。索引与 `chat/` 保留最小删除标记，阻止迟到写入和旧数据重新导入。清理失败返回 `503 SESSION_CLEANUP_PENDING`，会话已从历史和搜索隐藏，可重试同一删除请求。审计日志、已形成的记忆、共享 Skills 和 Server 业务报告按各自职责保留，见 [用户隔离与会话存储](docs/user-isolation.md)。
+
+启动探测、预热、标题生成、学习检查、复盘和创建失败产生的内部会话会在结束时释放原生会话及自己的计算目录。未确认原生绑定的历史空目录不会被批量删除。

 删除仍被会话引用的目录会丢失生成文件，并可能使会话后续文件操作失败。需要改变根目录时，应同步保留会话数据库及目录绑定，不能只改环境变量后丢弃原目录。服务目前没有工作区附件下载接口。

@@ -200,33 +274,45 @@ Shell 和文件修改需要用户审批，即使聊天设置了 `approval_mode=a

 | 数据 | 默认位置 | 用途 |
 | --- | --- | --- |
-| 会话文件 | `.agent-workspaces/` | 文件计算和生成结果 |
-| Agent 数据 | `data/` | 会话元数据、对话记录、记忆、学习状态和结果引用 |
+| 会话文件 | `data/session-workspaces/` | 文件计算和生成结果 |
+| Agent 数据 | `data/` | 会话元数据、对话记录、记忆、学习状态和会话文件 |
 | Skill 文件 | `.opencode/skills/` | 工具可读取的 Skill，目录可由 `OPENCODE_SKILLS_ROOT_DIR` 指定 |
 | OpenCode 数据 | OpenCode 的 XDG 数据目录 | 原生会话数据库；部署时保留对应数据卷 |
 | 日志 | `logs/` | 运行审计和学习日志 |

-仅持久化 `data/` 无法保留会话生成的文件。`result_ref` 有独立的过期清理，不代表工作区也会自动清理。
+默认配置下，持久化 `data/` 会同时保留 Agent 记录和会话生成文件；OpenCode 数据库与 Skill 目录仍需分别持久化。覆盖工作区根目录时，应单独挂载对应位置。
+
+专用 OpenCode 实例可通过现有 `OPENCODE_DB` 指定独立数据库路径并纳入备份；client 模式需要在外部 OpenCode 服务侧设置。已有共享库需要停机备份后再安排迁移，不应在服务运行时直接移动。
+
+独立的 `result-refs` 存储、TTL 清理和 `/result-ref/:result_ref` 读取接口已移除。当前业务没有使用它们产生或读取结果。文件型结果保存在原生计算目录的 `files/` 中，用会话 ID 和相对路径引用，例如 `files/results/analysis.json`；Agent 使用当前会话的原生文件工具读取，保留跨会话和敏感路径校验。图表及地图展示继续使用现有类型化前端动作。浏览器附件下载接口尚未开放。

 ## 当前能做什么

 | 场景 | 工具或协议 | 说明 |
 | --- | --- | --- |
-| 查询供水数据 | `query_project_data` | 有限数据源：元素属性、SCADA 设备与历史、元素历史、分析运行和分页结果 |
+| 查询供水数据 | `mcp_tjwater_*` | 启用 Server MCP 后发现25项项目查询和10项受控分析，供普通项目会话与绑定调查使用 |
 | 地图与图表交互 | `locate_features`、`zoom_to_map`、`show_chart`、`view_history` | 通过 `frontend-action@1` 等待浏览器实际回执 |
 | SCADA 地图分析 | `render_scada_analysis`、`clear_scada_analysis` | 展示和清除受控叠加层 |
-| 网页搜索与地址解析 | `web_search`、`geocode` | 调用 Server 的 Bocha、天地图接口，模型不能指定任意 URL 或鉴权头 |
+| 网页搜索 | OpenCode 原生 `websearch` | 搜索服务由 OpenCode 配置管理，不经过 TJWater Server |
+| 地址解析 | `mcp_tjwater_geocode` | 调用 Server 的天地图接口，模型不能指定任意 URL 或鉴权头 |
 | 工况任务 | 查询、计划、报告、行动建议和人工证据工具 | 通过 Server 的任务与运行身份访问业务 |
-| 会话与学习 | `session_search`、`memory_manager`、`skill_manager` | 按会话、用户和项目范围管理记录、记忆和 Skill |
+| 调查实时进度与资料展示 | `publish_task_progress`、`publish_task_presentation` | 仅后台任务执行可发布；Server 保存进度并记录展示事件，不等待浏览器 |
+| 会话与学习 | `mcp_tjwater_session_search`、`memory_manager`、`skill_manager` | 按会话、用户和项目范围管理记录、记忆和 Skill |
 | 本地计算 | `shell` | 在会话 OS 沙箱中运行经过审批的命令 |
 | 外部资料和工具 | MCP 客户端 | 由管理员配置，并按会话权限调用 |

+配置构建器禁用 OpenCode 原生 `opencode.browser` 插件及其子插件，`browser_*` 自动化工具不再注册，浏览器权限也明确拒绝。业务前端继续使用上表的地图、图表和 SCADA 展示插件；`present_answer` / `final_answer` 返回交互界面与最终回答，`publish_task_presentation` 发布后台任务展示事件，`memory_manager` / `skill_manager` 保留完整读写插件接口。
+
 历史查询的时间窗口最长 24 小时，SCADA 字段限 `monitored_value` 和 `cleaned_value`；物理指标和单位以设备元数据为准。历史查询由 Server 校验只读权限，清洗操作仍需清洗权限。`view_history` 当前最多展示 100 个非空样本，不代表完整高频历史；缺失资产和历史缺数会返回实际状态。

-`web_search` 支持 freshness、summary、1 至 50 条结果以及域名筛选；`geocode` 返回 `center=[lon,lat]`、`source_crs=EPSG:4326`，可用于地图定位。服务密钥配置在 Server 的 `BOCHA_API_KEY` 和 `TIANDITU_GEOCODER_TOKEN` 中。
+网页搜索只使用 OpenCode 原生 `websearch`，搜索服务及其凭据由 OpenCode 管理，保留管理员的服务选择；TJWater Server 的 Bocha 接口、配置和 MCP 搜索工具已移除。搜索结果是外部资料，不自动保存为调查系统证据。`mcp_tjwater_geocode` 返回 `center=[lon,lat]`、`source_crs=EPSG:4326`，可用于地图定位；天地图密钥仍由 Server 管理。
+
+仓库默认搜索服务为 Exa，通过 `opencode.json` 的 `websearch.provider` 配置。启动时检查原生搜索工具、服务目录及有效配置，不发送实际搜索。`bun run check:websearch` 在独立 OpenCode 中检查目录；`bun run check:websearch --search` 额外搜索一次公开的 OpenCode 文档，输出服务 ID 与结果条数，不调用模型推理，也不接管现有实例。该检查使用临时原生数据库和配置目录；仅在全局 OpenCode 账户存储中的搜索凭据不会被复制。

 后台执行由 worker 提交 Server 已保存的 `task_id`、`run_id`、`execution_request_id`。Agent claim 成功后每 20 秒发送心跳，运行正常结束显式调用 `complete`，失败或中止调用 `fail`。Server 决定活动运行和租约状态；计划、报告或 `final_answer` 的发布不代表业务任务完成。执行计划规则见 [工况执行计划](docs/execution-plan.md)。

+后台调查在真实步骤开始或路线变化时发布完整进度，Mermaid 节点的显式状态和供水要素引用随进度保存；图可重绘，todo 不决定图或运行状态。资料展示命令支持要素高亮/闪烁、图表开关和证据图层，图层几何与数值由 Server 从已保存证据提取。工具返回 `recorded` 表示展示请求已记录，不表示浏览器显示成功。前端 Dev 实时跟随仅作用于浏览器；无人查看或关闭跟随时调查照常运行，不回放历史展示，也不重新触发调查。普通聊天仍使用现有 `frontend-action@1` 浏览器回执。
+
 交互会话遇到 `credential_refresh_required` 后，前端更新凭据；令牌只通过鉴权头传递，工具请求最多重试一次，403 不触发续期。后台 worker 使用已有 OAuth provider 更新凭据，不等待浏览器；无法写回失败时仍由 Server 的租约恢复处理。

 服务保留 `agent-ui@1` UIEnvelope 兼容接口，目前该注册表为空。当前 6 个浏览器动作使用独立的 `frontend-action@1` 注册表；前端需声明能力并回传动作结果。待办使用 `todoread`、`todowrite`，通过 `todo_update` 更新前端。协议见 [Agent UI 协议](docs/agent-ui-protocol.md)。
@@ -283,7 +369,7 @@ Shell 和文件修改需要用户审批，即使聊天设置了 `approval_mode=a

 ## 前端与任务接入

-聊天 API 的前缀是 `/api/v1/agent/chat`。生产请求需携带产品 Bearer 和项目头；涉及会话的操作还校验会话归属。
+Agent 服务的 API 前缀是 `/api/v1`，路径不再包含 `/agent/chat`。生产请求始终携带产品 Bearer，项目会话额外携带项目头；涉及会话的操作还校验用户及个人或项目范围。前端 Agent 面板可选择“个人会话”或“当前项目”，切换会开启新会话，历史分别加载，不改变已有会话归属。任务执行与任务协作始终属于项目。

 | 方法 | 路径 | 用途 |
 | --- | --- | --- |
@@ -291,8 +377,10 @@ Shell 和文件修改需要用户审批，即使聊天设置了 `approval_mode=a
 | GET | `/models` | 聊天模型菜单与默认值，不含 provider 凭据 |
 | POST | `/session` | 创建会话 |
 | GET | `/sessions`、`/session/:session_id` | 列表和会话内容 |
-| DELETE | `/session/:session_id` | 删除聊天记录，不同步清理工作区 |
-| POST | `/stream` | 发起对话并接收 SSE |
+| DELETE | `/session/:session_id` | 删除聊天记录及其会话工作区 |
+| POST | `/responses` | Responses 文本请求；stream=true 返回 SSE，否则返回 Response JSON |
+| GET | `/session/:session_id/inputs` | 当前会话尚未处理的用户消息 |
+| PATCH | `/session/:session_id/inputs/:input_id` | 将未处理消息切换为 steer 或 queue |
 | GET | `/session/:session_id/stream` | 订阅会话流 |
 | POST | `/abort` | 中止运行 |
 | POST | `/permission/:request_id/reply` | 回复工具审批 |
@@ -304,7 +392,19 @@ Shell 和文件修改需要用户审批，即使聊天设置了 `approval_mode=a
 | POST | `/task-executions` | 提交后台任务执行 |
 | POST | `/task/:task_id/collaboration/session` | 创建任务协作会话 |

-SSE 包含 `token`、`progress`、`ui_envelope`、`frontend_action`、`permission_request`、`question_request`、`todo_update`、`credential_refresh_required`、`session_title`、`done` 和 `error`，并保留兼容用途的 `tool_call` 事件。聊天 token 流与 Server 的 `/api/v1/workbench/events` 业务事件流相互独立。
+消息请求使用 Responses 文本子集：`input` 为字符串或 user/input_text 消息数组，`conversation` 绑定已有会话（字符串或 `{ "id": "..." }`），可选 `model`、`stream` 和标准字符串 `metadata`。`stream` 默认 false。TJWater 的 `approval_mode`、`capabilities`、`task_context` 和 `trigger_context` 放在独立的 `tjwater` 扩展对象中，不接受模型自行指定身份、项目或工具权限。发送新增用户输入即可，历史从已授权会话读取，不重复上传整份 UI 历史。
+
+运行中的普通聊天和任务协作可继续向 `/responses` 提交非流式文本，指定已有 `conversation`、`tjwater.delivery`（`steer` / `queue`）及稳定的 `tjwater.input_id`（`msg_` 加32位小写十六进制字符）。返回 HTTP 202 和 `object="tjwater.response_input"` 的收件回执，表示输入已由原生收件箱接管；`pending` 不代表模型已读取。前端默认 steer，可选择 queue；steer 在下一步引导当前工作，queue 等待当前工作完成后处理。追加输入不切换模型、审批、任务或授权上下文，也不创建第二条宿主生成循环。原生成流保持连接，`tjwater.user_input` 事件报告输入接收和处理，处理后的用户消息保存到会话历史。
+
+未处理消息通过 `/session/:session_id/inputs` 查询，可 PATCH `{ "delivery": "queue" }` 或 `{ "delivery": "steer" }` 切换；已取走时返回409，前端刷新列表。每会话最多20条待处理消息，按次最多接收500条追加输入；停止会话会取消尚未处理的本类输入。接口校验用户、项目和会话归属，不能直接追加或修改后台 `task_execution` 调查输入，也不能借此更改代理协作消息。会话收尾或启动尚未就绪时返回409，不能自动重试为新一轮。
+
+这里是现有 HTTP/SSE 服务的 `tjwater` 扩展，映射 OpenCode 原生用户收件箱；不等同于 OpenAI WebSocket 的 `response.steer` 事件，官方协议边界见 [Mid-turn steering](https://developers.openai.com/api/docs/guides/steering)。验证命令 `bun tests/integration/response-input-smoke.ts` 使用隔离 OpenCode 和本机确定性模型，验证模式切换及队列后续输出，不调用付费推理。
+
+流使用 `response.created`、`response.in_progress`、`response.output_item.added/done`、`response.content_part.added/done`、`response.output_text.delta/done` 和终态 `response.completed/failed/incomplete`，带单调递增的 `sequence_number`。中止返回 incomplete；未知原因不伪造标准 incomplete reason。进度、审批、问题、凭据续期、地图和富文本展示通过 `tjwater.<事件名>` 扩展携带 `response_id`。前端使用 Responses transport 接入现有 useChat 和 UIMessage 渲染；UIMessage 不再是生成接口的网络协议。标准流语义见 [OpenAI Responses streaming](https://developers.openai.com/api/docs/guides/streaming-responses)。
+
+当前支持文本、受权会话续接和流式/非流式生成；`previous_response_id`、客户端指定 tools、图片/文件输入及其余未实现参数均返回400，不能将此接口宣称为完整 OpenAI API 代理。模型推理仍由 OpenCode 执行，上游 provider 协议沿用 `agent-models.json` 的配置。`GET /session/:session_id/stream` 保留独立的会话状态订阅，事件包含 state、token、progress、done 等，用于历史恢复和已运行任务跟随；Server 的 `/api/v1/workbench/events` 继续承载业务事件。
+
+发布须同步 Agent、前端与 Server Worker。旧 `/agent/chat` 路径和 POST `/stream` 已移除；原会话数据目录、会话ID及权限规则不迁移。现有 Worker 进程需加载更新后的任务执行、消息投递和凭据续期地址。

 开发环境的本地上下文可通过 `AGENT_LOCAL_USER_ID`、`AGENT_LOCAL_PROJECT_ID`、`AGENT_LOCAL_NETWORK` 设置，对应请求头为 `X-Agent-Local-User`、`X-Agent-Local-Project`、`X-Agent-Local-Network`。`X-Trace-Id` 用于请求追踪。

@@ -319,7 +419,6 @@ env_file:
  - .local.env
 volumes:
  - ./agent-models.json:/app/agent-models.json:ro
-  - ./agent-workspaces:/app/.agent-workspaces
  - ./data:/app/data
  - ./logs:/app/logs
  - ./skills:/app/.opencode/skills
@@ -336,12 +435,35 @@ volumes:
 | `bun run check:models` | 通过实际 OpenCode 和上游目录检查模型，不请求推理 |
 | `bun run start:prod` | 类型检查通过后启动服务 |
 | `bun test tests/**/*.test.ts` | 全部单元测试，日常修改优先运行相关测试 |
+| `bun run tests/integration/query-mcp-smoke.ts` | 验证第一方原生 MCP 查询发现、会话元数据、权限和混合工具保留；加 `--long-calculation` 额外验证90秒预算下的65秒静默调用，不运行真实模拟或推理 |
 | `bun run tests/integration/mcp-smoke.ts` | 可选的本地 MCP 联调，使用自己的样例服务和临时数据，不请求推理 |
+| `bun run tests/integration/workspace-smoke.ts` | 可选的原生工作区权限检查，验证本会话可读、其他业务数据不可读，不请求推理 |

 [CI 工作流](.gitea/workflows/package.yml) 在推送 `v*` 标签或手动触发时调用共享容器流水线。当前镜像名为 `gitea.waternetwork.cn/orgtjwater/next-tjwater-agent`，部署服务名为 `next-agent`；仓库需设置 `REGISTRY_USERNAME`、`REGISTRY_PASSWORD`、`DEV_DEPLOY_SSH_KEY`。具体候选验证和发布步骤由共享模板定义。

 代码修改约束见 [AGENTS.md](AGENTS.md)，前端协议见 [Agent UI 协议](docs/agent-ui-protocol.md)，任务计划规则见 [工况执行计划](docs/execution-plan.md)。

+## 起始问题推荐
+
+`POST /api/v1/suggestions` 接收可选的已配置聊天模型 `model` 和最多 12 条 `activities`。每条活动包含 `id`、`kind`（alert/task/analysis/session）、`title`、`occurred_at`、`origin`（backend/agent/demo），以及可选的 `summary`、`status`；它们是当前工作台已加载的快照，不替代 Server 的权威业务记录。
+
+接口沿用聊天路由的登录身份与会话范围校验。OpenCode 在临时原生上下文中执行一次性文本生成，不派发聊天轮次或业务工具，也不写入用户会话历史；完成或失败后删除该上下文及其专用工作区。结果为 `suggestions`（最多三条 question/activity_id）及 `generated_at`，活动引用必须来自请求，演示活动的问题始终标记为演示。
+
+推荐按已验证用户、项目、模型和活动快照合并并发请求并缓存 5 分钟，失败不缓存。推理超时为 20 秒；生成失败返回 503，前端保持输入可用，不展示固定问题作为生成结果。不需要增加 provider、密钥或独立模型默认值。
+
+聚焦检查：
+
+```bash
+bun test tests/chat/promptSuggestions.test.ts tests/routes/promptSuggestions.test.ts tests/runtime/opencode.test.ts
+bun run check
+```
+
+显式联调会执行一次真实模型调用，可在独立 OpenCode 实例中验证：
+
+```bash
+OPENCODE_MODE=embedded OPENCODE_PORT=0 bun run tests/integration/prompt-suggestions-smoke.ts
+```
+
 ### 本地交互式聊天回答

 原生插件通过 `present_answer` 发布 `answer-ui@1` 内容块，现有聊天消息流输出
@@ -359,3 +481,35 @@ UI 托管服务配置或数据库迁移。详见

 原生工具发现验证：`bun run tests/integration/answer-ui-smoke.ts`，使用独立临时数据库，
 不调用模型推理，不接管既有服务。
+
+## 第一方产品 MCP 查询
+
+新增10项受控分析：标准水力模拟、爆管侦测、爆管定位、阀门隔离、DMA漏损识别、污染扩散、关阀影响、冲洗分析、调泵影响和压力监测点选址。普通项目会话与调查主Agent可按权限调用，reader保持只读。计算不保存正式方案或下发设备指令；调查结果和输入假设沿用证据链保存。计算工具支持Agent按任务指定 `timeout_seconds`，默认120秒，上限由Server工具schema公布（默认1小时）；HTTP、宿主和OpenCode同步使用相应预算，普通查询仍为30秒。修改Server上限后需重启Agent以重新发现目录并更新原生连接。长计算超时不会自动重试。能力、单位、模板隔离和发布边界见[分析工具说明](../next-tjwater-server/docs/mcp-analysis-tools.md)。
+
+本地开发手动启动Agent，读取项目 `.local.env`，已有系统环境变量优先。MCP随Server运行。仓库保留 [tjwater-agent.service](infra/systemd/tjwater-agent.service) 作为可选部署模板；用户级Server/Agent服务已移除，不与手动进程同时启用。选择systemd部署时，私有 `~/.config/next-tjwater/agent.env` 会覆盖项目同名配置，必须与Server及前端的认证环境一致，并复用已有原生会话数据库。
+
+安装时将两个仓库的 `infra/systemd/tjwater-{server,agent}.service` 分别复制到 `~/.config/systemd/user/`，准备上述私有覆盖文件，完成后端依赖和项目迁移后执行 `systemctl --user daemon-reload` 以及 `systemctl --user enable --now tjwater-server.service tjwater-agent.service`。后端读取自身 `.env`；生产覆盖中的 issuer 必须与后端、前端登录及 worker 取令牌地址一致。本机服务状态可用 `systemctl --user status tjwater-server tjwater-agent` 检查，Agent 就绪地址为 `http://127.0.0.1:8787/health`。
+
+项目及宿主只读查询统一由原生连接 `mcp_tjwater` 提供，工具 ID 为 `mcp_tjwater_<name>`。本地 MCP 使用官方 Server SDK 2.3.1，固定 MCP 2026-07-28，默认提供地理编码、会话搜索、调查任务列表与详情、消息读取和待办读取六项查询，启用上游后合计41项。公开网页搜索使用 OpenCode 原生 `websearch`。`memory_manager`、`skill_manager` 保留完整读写插件；消息发送、报告发布和地图展示等也保留插件形式。
+
+`mcp_tjwater_query_nearby_elements` 查询当前授权项目的模型管网：将 `mcp_tjwater_geocode` 返回的 EPSG:4326 `center: [经度,纬度]` 原样传入，后端负责坐标转换。`element_type` 默认 `pipe`，`radius_m` 默认200、最大10000米，`limit` 默认5、最大100，支持 `offset`。结果按点到完整几何的 WGS84 椭球最短距离排序，返回模型 `element_id`、米制 `distance_m` 和 `properties`；可用 `locate_features` 定位。原始 GIS 的 `source_fid` 不在此查询范围。空结果不自动扩大半径，空间邻近不代表连通或供水归属。普通查询预算仍为30秒，用户、项目和调查证据链沿用现有 MCP 规则。
+
+事件业务处置 Skill 由 Server 维护并经任务 MCP 分发：`get_task_context` 摘要返回 `handling_skill` 名称、版本和内容摘要，`section="skill"` 返回按已绑定任务 workflow 选择的完整流程，不保存为事件证据。Agent 本地 Skill 维护通用执行方法，不复制或覆盖 Server 业务规则；权限、人工审批与动作执行仍由 Server 控制。报告和进度的人类可读时间统一使用 Asia/Shanghai（UTC+8），API 时间保留原始时刻。更新 Agent 指令或 Server 工具 schema 后须重启 Agent 重新加载。
+
+`TJWATER_MCP_ENABLED` 默认 false，只控制上游 Server 项目查询。启用后，宿主通过官方 Client SDK 发现35项工具（25项查询、10项分析），合并到本地 MCP 目录，由 OpenCode 原生发现调用。旧 `query_project_data`、`query_operational_task_data` 和任务上下文查询插件及其 HTTP 查询桥已移除；未启用时项目业务查询不可用，不回退。普通项目会话和调查主 Agent 可使用；直接只读 reader 仍仅可使用25项查询；身份、项目和任务由宿主确定。调查查询保存 Server 证据，普通聊天不自动保存调查证据。
+
+三类 Agent 均优先单对象、有过滤条件和必要短时间窗的查询。集合默认20条，按需翻页，不自动遍历全网；offset 上限10000，超过时缩小时间窗或目标。历史组合查询按序列、时间对数据点分页；读取证据优先指定 data_path 和小页。DEMO 样本超过整份摘要校验的8MiB预算时需拆分数据源，反复缩小时间窗不能解除此限制。截断或非零offset均不能证明完整范围无异常。
+
+历史曲线展示调用从每页500个数据点起步，遇到 `RESULT_TOO_LARGE` 原位减半重试；最多读取1000条、发送16次请求，共享120秒超时（单次普通查询仍为30秒），展示最多100个有效点。空值页不等于没有历史数据，预算内仍有未读取数据时会明确说明。此预算独立于模型首次查询默认20条和时序接口单页10000条上限。
+
+`get_task_context` 默认返回固定摘要和可读章节；完整任务、指定报告、证据、动作、进度、授权申请、计划和运行信息通过 section/data_path 分页读取。预览带 `preview_only`，不能当作完整报告。详情每页默认20项、最多500项，长文本按字符分页，数据库返回前限制8KB，超限时缩页或读取更深路径。上游大结果的证据资源链接在本地转成 `evidence_read` 工具参数，原证据编号与来源保留，不要求 OpenCode 直接读取上游资源。
+
+宿主需配置 `TJWATER_MCP_ISSUER_URI`、`TJWATER_MCP_RESOURCE_URI`、`TJWATER_MCP_AUDIENCE`、`TJWATER_MCP_CLIENT_ID`、`TJWATER_MCP_CLIENT_SECRET`。用户及 worker 的产品令牌在宿主内交换成专用短期 MCP 令牌；凭据续期复用现有机制。MCP 401清缓存并重试一次，403不申请更大 scope；会话释放取消调用并清除缓存。OAuth 密钥和 Bearer 不发送到 OpenCode。
+
+认证先按401 challenge 或 well-known 发现资源及 OAuth/OIDC 元数据，严格绑定配置中的资源和 issuer，再向元数据声明的 token endpoint 发送凭据；支持 Basic 和表单客户端认证。公开发现无凭据，最多64KiB/文档、10秒/轮，缓存5分钟；MCP 401 后重新发现。两种 grant 均发送标准 resource，exchange 还发送专用 audience。启用前须确认身份平台支持 resource 到 audience 的映射；若 Keycloak 拒绝 resource，需先升级或适配。不会通过移除参数重试来绕过该前提。
+
+本地 MCP 独立监听127.0.0.1临时端口，先于原生工具发现启动；业务 HTTP 服务仍在完整预热通过后监听。公开连接描述位于元数据目录的兄弟目录 `mcp-query/connection.json`，不含密钥。embedded 自动注入 `TJWATER_AGENT_MCP_CONNECTION_PATH`；client 模式须共享该路径、同一内部密钥和同版本可信插件，Agent 重启后同步重载 MCP 连接。连接只适用于同一宿主网络空间。
+
+OpenCode 按标准 MCP `tools/call` 调用，以 `_meta["ai.opencode/sessionID"]` 传入会话关联值。该值不是凭据：本地 MCP 先校验内部密钥、loopback 地址并拒绝浏览器请求，再解析宿主会话或已验证的直接只读子会话。真实身份、项目、任务和专用 OAuth 令牌由宿主决定。精确 MCP 权限规则对直接调用和 Code Mode 均生效；reader 只可查询父任务范围，不能发布、审批、执行 Shell 或递归委派。待办读取经宿主 RPC 访问原插件存储，保留已有清单。
+
+配套 Server 的 `docs/mcp-query-implementation.md` 提供 Keycloak、SQL migration 和配置步骤。本次没有配置真实身份平台、迁移真实数据库或部署；开启前须完成真实项目验收。