feat(investigation): publish incremental reference graphs

Publish graph deltas using the Server-owned cumulative graph contract. Validate historical comparison chart publications and consolidate Agent documentation.
2026-11-11 19:10:41 +08:00
parent 5ee93329a4
commit db87323b69
28 changed files with 2329 additions and 90 deletions
@@ -0,0 +1,68 @@
+# 供水 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) 选择，不在文档整理时执行付费推理、修改生产身份平台或重启用户服务。本地静态检查、模拟测试、原生能力探针、真实项目验收和实际发布分别记录。