Files

T

jiang db87323b69 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

5.8 KiB

Raw Blame History

供水 Agent 架构与维护边界

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

总体链路

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

身份、数据与工具

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

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

发布、前端动作、消息、记忆和技能沿用可信插件与类型化宿主桥。旧 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 数据库。删除、旧目录迁移和失败重试的规则见用户隔离与仓库 AGENTS.md，不能作为构建缓存清理。

生命周期与可观察性

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

验证入口

从 Agent 仓库运行：

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

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

5.8 KiB Raw Blame History