# 供水 Agent 架构与维护边界

整理日期：2026-11-10。本文合并原 Harness 简介与架构报告，按当前源码说明宿主职责；启动、模型、MCP 和部署参数统一见 [README](../README.md)，不在此维护第二份配置表。旧架构原文见 [历史资料](history/legacy-harness-design.md)。

## 总体链路

```mermaid
flowchart LR
  Frontend[前端聊天与工作台] --> Host[Agent 宿主]
  Worker[Server 调查 Worker] --> Host
  Host --> Identity[Server 验证身份与任务归属]
  Host --> Runtime[OpenCode 运行时]
  Runtime --> MCP[宿主管理的产品 MCP]
  MCP --> Server[TJWater Server 与项目数据]
  Runtime --> Tools[受控发布与展示插件]
  Tools --> Host
  Host --> Persistence[会话文件、状态与审计]
  Host --> Frontend
```

模型负责推理与工具选择。Agent 宿主负责身份、运行生命周期、可信工具桥、流式事件、会话文件和取消；Server 负责业务事实、项目权限、任务与报告权威状态。图表展示、报告发布、模型轮次结束与任务执行完成分别处理。

## 代码职责

| 层 | 当前入口 | 职责 |
| --- | --- | --- |
| 启动与装配 | [src/server.ts](../src/server.ts) | 组装身份、存储、运行时、内部桥和 HTTP 服务；就绪检查失败不开始正常服务 |
| 聊天与输入 | [src/routes/chat.ts](../src/routes/chat.ts) · [chat-run-accumulator.ts](../src/routes/chat-run-accumulator.ts) | HTTP/SSE、运行事件累加、权限与问题投影、追加输入和中断 |
| 原生运行时 | [src/runtime/opencode.ts](../src/runtime/opencode.ts) · [opencode2-config.ts](../src/runtime/opencode2-config.ts) | embedded/client 接入、可信原生配置、会话绑定、事件与取消 |
| 业务 MCP | [mcp-query-client.ts](../src/product/mcp-query-client.ts) · [product-mcp-tools.ts](../src/runtime/product-mcp-tools.ts) | 授权上下文、专用 OAuth、工具目录和访问策略；实际目录由代码维护 |
| 发布与任务 | [task-publication-bridge.ts](../src/routes/task-publication-bridge.ts) · [task-command-bridge.ts](../src/routes/task-command-bridge.ts) | 类型化任务命令、进度、报告和展示发布，校验会话用途与运行归属 |
| 前端动作 | [src/frontendAction/](../src/frontendAction/) · [UI 协议](agent-ui-protocol.md) | 受控展示 command 与回执，内容渲染不重放动作 |
| 存储与隔离 | [workspace-store.ts](../src/sessions/workspace-store.ts) · [session-scope.ts](../src/sessions/session-scope.ts) | 从已验证会话取得 actor、scope 与所有权，管理 host-owned chat 和模型可写 workspace |
| 记忆与技能 | [src/learning/orchestrator.ts](../src/learning/orchestrator.ts) · [src/memory/](../src/memory/) | 按既有规则组织学习、记忆和技能；Skill 存储不宣称按用户或项目隔离 |
| Shell 沙箱 | [landlockSandbox.ts](../src/sandbox/landlockSandbox.ts) | 受许可的本地 Shell 及系统级访问限制，不作为自由业务查询入口 |

## 身份、数据与工具

生产聊天必须通过 Server 验证 Bearer。个人会话使用个人范围，不能获得项目业务凭据；项目会话还需核验 `X-Project-Id` 和成员权限。调查执行绑定 task/run/execution_request 和实际 Agent 实例，客户端或模型不能自行指定身份、产品 URL、凭据或数据范围。

业务查询通过原生 `mcp_tjwater` 连接，由宿主持有 OAuth 凭据。业务写入和计算按目录元数据、会话用途、原生许可及 Server 权限处理，不将 `readOnlyHint` 当作授权。普通聊天与学习不启动子代理；后台调查的受控只读 reader 边界见 [README](../README.md#后台调查子代理)。

发布、前端动作、消息、记忆和技能沿用可信插件与类型化宿主桥。旧 `tjwater_cli`、自由业务命令桥、独立结果引用存储和 render-ref 回读 API 已退役；不要据历史 Harness 图重新建立这些入口。文件结果保存到会话 `files/`，通过会话身份及相对路径下载。

## 会话与持久化

会话根目录由配置管理，通常位于 `data/session-workspaces/`。host-owned `chat/` 保存 UI 状态、transcript 和学习记录；模型仅绑定 `workspace/`，通过其中的 `files/`、`tmp/` 和 `.cache/` 工作。OpenCode 原生历史、UI state 和脱敏 transcript 各有用途，不能相互替代。

只共享不可变资料或配置，不将用户凭据、其他会话和仓库源码复制到模型工作目录。会话目录属于持久用户数据；部署需保留实际 data root 与 OpenCode 数据库。删除、旧目录迁移和失败重试的规则见 [用户隔离](user-isolation.md) 与仓库 `AGENTS.md`，不能作为构建缓存清理。

## 生命周期与可观察性

- 原生事件进入宿主累加器，再持久化并推送浏览器；断开浏览器订阅不等于中止后台运行。
- `ask_user` 的请求、答案和投递记录独立保存，答案已保存与推理已继续分别反馈；见 [前端交互状态](../../next-tjwater-frontend/docs/agent-interaction-state-design.md)。
- 后台任务以 Server 持久化状态及 claim、heartbeat、complete/fail 为准，不能以 SSE done 或最终文字替代；见 [任务执行边界](execution-plan.md)。
- 启动检查、业务审计、原生 call ID、取消、超时和故障清理均保留各自证据。收到 queued/running 或一次 HTTP 超时不能据此宣布任务完成或业务失败。

## 验证入口

从 Agent 仓库运行：

```bash
bun run check
bun run check:openapi
bun test tests/routes tests/sessions tests/product tests/frontendAction
```

模型配置检查、隔离集成和部署检查按 [README](../README.md) 选择，不在文档整理时执行付费推理、修改生产身份平台或重启用户服务。本地静态检查、模拟测试、原生能力探针、真实项目验收和实际发布分别记录。