--- title: 源码架构与包边界 description: 理解共享契约、业务服务和 Harness 适配之间的关系。 lastVerified: 2026-10-02 --- # 6.7 源码架构与包边界 客户端表达用户操作，后端维护业务状态，Harness 适配执行模型与工具，共享契约连接这些层。 ```text React 工作界面 │ 共享契约 Harness / RPC 适配 ── DSH 模型、会话和工具 │ 业务服务 ── PostgreSQL │ 资源、任务、员工、群与自动化 ``` 产品架构为 **AI Team / Agent Studio / Agent Harness**，解释团队、工作定义与运行底座。上图和下方包表属于系统实现视图，不与产品三层一一对应，也不把业务面、数据面、执行面混入产品架构图。原生 Plugin、Bundle、运行配置和 Agent 的映射约定见[业务能力与执行引擎边界](https://docs.teloa.ai/v/0.2.0/markdown/develop/engine-integration.md)。 ## 代码放在哪 | 包 | 职责 | | --- | --- | | `packages/contract` | 共享类型、数据格式与校验 | | `packages/backend` | 持久化、业务规则、事务与幂等 | | `packages/harness-dsh` | DSH 接入、RPC、执行与授权检查 | | `packages/client/ui-workbench` | React 产品界面及交互状态 | | `packages/client/ui-kit` | 共用界面能力 | | `packages/bundle` | 插件组合与预设 | | `packages/mcp-reference` | 最小只读资料服务 | | `packages/local-embedding` | 开发试点：可选本地嵌入扩展、锁定版本的模型文件准备与推理子进程 | ## 岗位协作与原生执行 产品用语分为两层：AI 员工是保留技能、岗位记忆和授权的长期岗位身份，工作群承载用户与员工的业务合作；执行小组围绕当前任务分工，执行助手是其中的临时成员。普通会话的主 Agent 或某位 AI 员工均可发起执行小组，不要求先有工作群。 执行小组由 **DSH Agent Team** 实现。Teloa 复用官方成员名册、邮箱、任务依赖、消息和执行服务，通过薄适配维护业务归属、授权与交付投影，不另建 Agent 引擎或并行 DAG。Task/Run 是业务归属与验收真源，官方 Team 与 jobs 是执行事实真源。 受管 Run 的临时 teammate 使用本次运行固定的授权与额度，不自动绑定长期岗位，不因成员名称取得另一位员工的身份或权限。停止后先阻止派发，再取消已关联的成员和后台工作，实际结束后再收口；成员完成不等于业务交付。 持续分工使用官方 `spawn_teammate`，受管一次性委派保留 `subagent_task`。旧子会话继续使用官方读取与控制服务，不迁成伪造的 Team 成员。产品界面与用户指南使用「执行小组／执行助手」，实现名称只在开发者文档中说明。 岗位会话复用 DSH `0.1.7-rc.1` 的公开 `system-prompt/assemble` 异步接口，将当前岗位定义交给官方 runtime-context 投影，不以本人消息自动首发长角色文字。宿主逐次核对本人会话绑定、创建请求身份、有效岗位关联和当前岗位定义；身份或版本变化才由官方投影产生新快照，原始用户消息保持不变。手动自我介绍只发送简短请求。Task/Run 保留原有固定任务上下文，原生子 agent 不继承这条普通岗位会话适配；工具与资料授权仍走原有检查。读取失败、退役或固定请求与关联不一致时拒绝请求，不静默降为普通会话。 ## 本地垂类模型的交付边界 开发者交付的本地模型应对应用户可理解的能力，例如语音转写、文档识别或告警辅助分类。DSH 已有的本地语音 provider 负责权重准备、状态和推理；Teloa 复用它，逐步补齐市场发现、方案依赖和业务调用。新增非语音 provider 需单独验证，不能把通用本地聊天模型可用当作垂类生态已经完成。 本地语音资源为 `teloa.model.sensevoice`：市场「模型」 > 「准备本地语音」 > Teloa 设置内的原生插件列表 > 「语音输入」。首次启用后需要重启，再由用户确认下载和准备。目录保存 `delivery: reference`、`model.form: local-specialist`、用途 `speech-to-text` 及固定的原生 provider 引用，不保存权重、安装命令或另一份下载状态。官方 `plugins.bundle.config` 由原生插件管理页唯一承载，不能在市场重复声明；当前原生页面没有公开的插件详情深链，入口到插件列表后需选择「语音输入」。 SenseVoice 使用已核对的 `dsh-speech / sensevoice-local` 绑定。该资源的在线索引兼容范围从 `0.2.0-alpha.7` 起，避免旧读取器无法理解新形态。本地检索实现另增加 `teloa-embedding / qwen3-embedding-0.6b` 的严格契约绑定，生产官方目录接入仍待完成。模型权重许可与源码许可分列。搜索或会话引导不会启用插件、下载权重或更改聊天模型。第三方 OCR、分类、重排等适配尚未实现，不应只改目录中的 provider 名就声称可安装。 插件代码、模型权重与本机运行绑定分开管理。已有原生准备器直接复用；大权重不进入 Skill 文本内容仓。专用模型绑定对应能力或工具，只有对话模型进入聊天选择器；主助手可继续使用云端模型。本地指 Teloa 宿主，例如用户部署的 Mac mini，不一定是打开网页的设备。硬件兼容、内存和质量以具体模型的实测为准。通用的第三方模型发布和运行适配仍在建设中。 私有化中、大模型由用户自行部署在 GPU 服务器上，Teloa 通过 DSH 原生自定义模型 API 接入，不负责 GPU 部署和调度，也不向客户端下载这些权重。远程备用可以是用户私有模型服务；“远程”不等同公有云，首选与备用遵循用户配置。连接私有模型服务不等于整个任务已被限制在内网，后者还需要核验工具和子任务的出站行为。 ### 端侧中文检索 ::: info 能力与目录状态 本地检索扩展包含在 alpha.7 源码中，默认不启用，需要另行准备运行时和模型。生产官方目录的模型资源接入尚未完成；第三方 provider 安装入口未开放。具备检索实现不等于任意市场模型均可安装。 ::: `@teloa/local-embedding` 将 Qwen3-Embedding-0.6B 用于授权资料内的定位，提供 1024 维嵌入。它是可停用的 Teloa 扩展，不是 DSH 原生语音服务，也不进入会话、员工或默认聊天模型的候选。主助手仍使用自己的聊天模型；“本地”指运行 Teloa 的宿主。 ```text 本人显式加入资料 -> ResourceService 读取 -> 分块 -> 本机嵌入 -> PostgreSQL 索引 原生检索工具 -> 会话/岗位授权 -> 查询嵌入 -> 授权候选排序 -> ResourceService 事务回读 -> 带来源、版本和原文区间的摘录 ``` 索引构建与嵌入计算在 Teloa 宿主本地执行。检索工具返回的原文摘录会进入当前聊天模型的上下文；会话使用远程模型时，摘录可发送到该模型服务，包括用户自行部署的私有远程模型服务。因此，本地检索不保证整段问答完全在本机或离线完成。 核对 DSH **0.1.7-rc.1** 后，试点复用 Cordis 的可选服务发现与生命周期、`ctx.subprocess` 的进程管理、`dshHomePath()` 的宿主目录、`withFileLock` 的准备互斥，以及 `ctx.tools.register(defineTool(...))` 和原生 ToolRuntime。该版本没有公开的通用嵌入推理或模型文件准备接口，SenseVoice 的准备器也未导出供非语音复用，因此补充范围限于锁定版本的模型文件校验、ONNX worker 与 `teloaEmbedding` 状态服务。语音链路继续使用官方实现。 #### 准备与模型文件来源 扩展不在默认组合内，启停设置重启生效；启用只检查缓存，不下载、安装或加载模型。用户在准备界面核对来源、容量与许可并确认后，才依次准备运行时和模型文件。运行时 **`onnxruntime-node@1.30.0`** 不随应用发行，复用 Teloa 既有受管安装器、随附 lock、`npm ci --ignore-scripts` 和完整性核验。`embed()` 只接受 `ready/standby`，待机时按需启动 worker，未准备时明确拒绝，不通过查询隐式安装。 模型采用 `onnx-community/Qwen3-Embedding-0.6B-ONNX` 的锁定 revision：**社区转换，不是原厂发布的文件**。原厂为 `Qwen/Qwen3-Embedding-0.6B`；分词文件取原厂锁定的 revision。fp32 的 ONNX 图与外部权重合计约 **2.40 GB**，另需分词文件与受管运行时。固定 URL、字节数、SHA-256、变体与配置保存在 `runtime/assets.json`，运行时配方位于 `runtime/onnxruntime.json`；来源和上游 Apache-2.0 许可依据见扩展的 `PROVENANCE.md` 与 `LICENSE-MODEL`。Teloa 不转换、托管或镜像权重。准备只接受固定的 npm/Hugging Face 来源及允许的 CDN 跳转主机；也可在准备界面改选国内镜像 `hf-mirror.com`，只换主机、路径与固定 revision 不变，每个文件仍按固定字节数与 SHA-256 核对，选择只用于本次准备、不保存；推理不自动转到远程嵌入服务。 #### 授权、索引与共享依赖 本人逐份显式加入资料，Agent 不能自行加入或扩大范围。本人普通会话在模型就绪后默认可调用 `teloa_knowledge_search`，按真实会话绑定范围检索；受管任务还须岗位工具授权及任务资料授权。工具只接受问题和结果上限，不接受模型指定的资料路径、本人身份或权限范围。结果说明已检索与待建资料，单条摘录最多 2 KiB、合计最多 16 KiB，沿用 ResourceService 的读取边界。 索引与资料元数据同存 PostgreSQL，只存向量、原文区间及摘要，不另存分块正文。每块向量为 1024 个 float32，共 4096 字节。索引绑定本人、资料/正文版本、范围、模型 `profileHash` 和分块器版本；查询每次重验这些绑定，再在事务内通过 ResourceService 回读正文。向量内存缓存不缓存授权。撤回、移出或版本不匹配的索引不参与命中；加入状态按来源跟随修订，新版本须重新建索引。启动及服务出现时对账，停用不删除权重或受管运行时。 v3 方案可在实际入口声明 `teloa.model.qwen3-embedding-0-6b@1.0.0`、`usage: embedding` 的依赖；声明不授予检索工具或资料权限。两个方案可共用同一 provider，卸载一方不清理共享模型。停用扩展后，新建或再次执行依赖它的入口会被阻断，无依赖入口与历史任务读取保持可用。目录或版本尚不支持时保留声明并显示状态，不能用测试资源绕过生产读取器。 #### 模型与硬件限制 默认使用 **fp32 与官方查询指令**；int8 仅供评估。相似度不保证资料中存在答案。**M1/M2 Mac mini 8 GB 未实机验证**，不能仅凭模型文件大小推断内存或速度。质量与容量需在目标设备及业务资料上核对；不要将单元测试或模拟目录当作生产资源接入证据。 开发者提交同类 provider 时需提供用途与输入输出契约、锁定版本的模型文件和来源说明、运行时配方与 lock、许可，以及状态机、未就绪拒绝、下载完整性、取消与空闲释放、质量和硬件证据。现有扩展包可作为接口参考；目录仍使用经审核的绑定白名单，不能通过填写任意 provider 名安装第三方代码。 ### 方案如何声明模型依赖 ::: info 协议适用范围 alpha.7 支持 `teloa.business-package/v3` 的模型依赖声明。声明本身不安装模型或授予工具权限；能否运行取决于已审核的目录绑定、对应 provider 的真实状态与当前业务授权。 ::: v3 的 `skill` 或 `work-template` 资源可声明 `modelDependencies`，将模型依赖放在实际使用它的入口上。v2 保持原有结构，拒绝该新字段。每项只允许 `catalogId`、固定目录 `version`、`usage` 和 `required`；字段存在时须有 1～16 项，同一模型与用途不能重复。清单不接受下载 URL、命令、凭据或运行地址。 下面两份文件构成最小方案。它示范前置依赖：用户通过原生语音输入生成并核对文字，任务负责整理文字。**依赖声明不会自动获得音频转写工具，也不会把 SenseVoice 设置为聊天主模型。** 若任务需要直接处理音频文件，仍需另行接入和授权实际工具。 `teloa.json`： ```json { "format": "teloa.business-package/v3", "id": "voice-notes", "title": "语音工作笔记", "version": "1.0.0", "domain": "general", "scope": "general", "description": "整理用户通过原生语音输入得到的文字。", "resources": [ { "id": "summarize-notes", "kind": "work-template", "title": "整理语音笔记", "version": "1.0.0", "required": true, "source": {"kind": "local", "path": "tasks/voice-notes.json"}, "modelDependencies": [ { "catalogId": "teloa.model.sensevoice", "version": "1.0.0", "usage": "speech-to-text", "required": true } ] } ], "relations": [], "entrypoints": ["summarize-notes"] } ``` `tasks/voice-notes.json`： ```json { "format": "teloa.work-template/v1", "id": "summarize-notes", "title": "整理语音笔记", "version": "1.0.0", "domain": "general", "description": "整理用户提供的转写文本，不读取或转写音频文件。", "requirements": ["用户已核对的转写文字"], "output": "包含要点与待办事项的工作笔记。", "skills": [] } ``` 通过方案导入流程载入目录或归档后，准备清单展示模型、目录版本及宿主当前状态。`1.0.0` 是目录资源版本；实际权重版本、摘要和下载校验仍属于 DSH 原生准备器。首次准备经现有设置页由用户确认，不混入方案一键准备的自动下载步骤。 | 情况 | 处理方式 | | --- | --- | | 合法声明对应的目录、版本或用途暂不支持 | 方案仍可导入，保留声明并展示状态 | | 必需模型未就绪 | 仅阻断依赖它的入口；其他入口继续可用 | | 可选模型不可用 | 显示缺项，不因此阻断入口；开发者需说明替代操作 | | provider 为 `ready` 或 `standby` | 可用；待机模型由对应服务按需唤醒 | | 创建或再次执行受管任务、计划任务 | 重新检查依赖，不能把创建时的就绪状态永久缓存 | | 两个方案引用同一模型 | 共用对应 provider；卸载方案不删除共享权重 | 声明保存在现有固定内容和资源快照中，状态来自对应 provider 服务。版本升级改变模型 ID、版本、用途或必需标记时，必须明确采用候选资源；原有“保留”仅保留本地实例，不能保留旧模型声明。要继续使用旧依赖，应取消本次升级。前后端均需校验该选择。 契约位于 `packages/contract/src/industry-model-dependencies.ts`；后端负责内容与固定快照。Harness 的 `industry-model-readiness.ts` 按目录用途与绑定，经 Cordis 公开 `ctx.reflect.get('speechToText')` 或 `ctx.reflect.get('teloaEmbedding')` 发现当前活跃的可选服务，再只读 `snapshot()`。未注入的插件作用域不能直接访问 `ctx.speechToText`，也不能为了读取状态把可停用扩展变成必需依赖。准备面板和任务链路复用同一检查。任务、计划和业务动作再次执行时按已固定的内容及资源版本重验，不追随当前方案或重建任务。 Skill 安装、预览只核验并固定正文，不要求模型先就绪，也不触发模型准备。通过方案使用 Skill 时按该方案的声明检查；同一公共 Skill 可被多个方案共享，不能把首次安装来源的条件变成全局前置条件。 普通原生会话读取方案包内 Skill（`industry-local`）时，在 provider 的 `get` 边界按固定包内来源重验模型依赖。公共引用 Skill（`industry-public`）的独立调用不继承引用方案附加的模型条件；当前原子 Skill 格式也没有模型依赖字段。依赖不可用时明确报错，不回退到同名其他技能。这些检查不覆盖已经进入上下文的技能正文或任意第三方 Skill。 用途词表包含 `speech-to-text`、`text-to-speech`、`embedding`、`rerank`、`ocr`、`classification`、`extraction` 和 `chat`，名称不代表已实现通用 provider 适配。新增非语音 provider 需提供锁定版本的模型文件、许可、硬件要求、工具权限和质量证据。 ## 统一输入与工作执行 ::: info 当前版本 本节说明 alpha.7 的统一输入与受管交办。模型、员工授权和业务数据源需实际可用。操作入口见[工作台指南](https://docs.teloa.ai/v/0.2.0/markdown/guides/workbench.md)和[任务指南](https://docs.teloa.ai/v/0.2.0/markdown/guides/tasks.md)。 ::: ### 首页与会话共用原生输入 首页首次发送建立或复用本次会话，欢迎区原地展开为工作会话，首条消息已提交；进入已有会话则延续上下文。首页不要求用户先判断「对话／工作」，也不在发送后要求再次「带入输入框」。会话记录可从最近工作找回，正式任务按需要建立。 两处复用 DSH 原生输入组件、草稿与提交链路，保留文本编辑、`/` 命令、Skills、`@` 引用、文件、图片、模型、权限和可用时的语音入口。Teloa 经公开 slot／服务补充业务范围和业务资料；不复制编辑器，也不另写功能缩水的首页 textarea。附件、模型和语音能力仍以实际运行配置为准。业务入口在原生工具栏中排在“知识与能力”左侧，不常驻“接手偏好”选择器；普通聊天沿用当前助手，明确人选由交办工具核验，已有指定人选约束继续显式保留。 首页与会话的差异在目标上下文：新会话开始新工作，已有会话继续当前工作。模型选择默认作用于当前主助手，不能静默覆盖员工与执行助手的配置；选择业务或改变会话权限不能扩大岗位授权。群编辑器保留自己的提及、话题与共享附件语义，不要求复制一对一布局。 分身和员工的一对一会话使用原生模型菜单，选择保存在该会话，实际请求与图片准入读取同一选择，不改写全局默认。普通本人会话沿用 DSH 的默认模型保存行为；正式岗位任务使用创建 Run 时固定的主选与备用策略。宿主按已有身份关联判断归属，读取失败时不写全局配置。备用仅使用用户明确配置的模型，切换结果持久保存。普通会话中的 `teloa_model_prepare` 需要本人确认；任务会话与子 Agent 不能发起。该机制不等于自动为每项任务规划模型，也不保证备用服务可用。 DSH 原生的「自定义模型 API」已经能够连接 Ollama；用户自行配置端点即可使用。Teloa 新增的是市场资源、下载确认与进度、权重及运行容量核验，以及员工/任务模型策略。实际推理、工具执行、选模和消息渲染继续复用 DSH。Ollama 是可选的独立运行时；当前管理代码内置，不要求用户安装，也尚未做成可独立启停的市场扩展。 本地模型的思考能力必须来自 Ollama 官方元数据，映射到 DSH 的 `reasoningEfforts`，正文与思考由原生适配器分离和渲染。不能把所有 Qwen 模型一概视为可关闭思考，也不能自行删掉正文中的思考标签。已验收 Ollama 0.34.4；思考模型在旧版缺少必要元数据时保留已下载权重，提示升级后重试接入。模型能装入内存不等于复杂任务质量达标，目录中的实验状态仍按逐模型验收维护。 ### 主助手、员工与任务 主助手处理通用需求，必要时选择合适员工或组织执行小组，负责向用户汇总。新会话不新增长期员工。明确指定的人选须核对职责、权限和在岗状态；派发被真实执行服务接受后才显示接手，不能靠提示词扮演另一位员工。 需要明确责任、持续跟进和交付的工作形成正式任务；普通问答和一次查询直接在会话完成。调用工具本身不构成创建任务的理由。会话可以关联多项任务，Task/Run、原生执行记录和成果记录分别维护责任、过程与交付，通过关联展示同一件事。 | 请求 | 目标行为与依据 | | --- | --- | | 今日工作统计 | 查询真实任务、执行与交付记录，给出范围和截至时间；不唤醒全部员工 | | 请所有员工重新汇报 | 收集新回复，区分已回复、等待、不可用，默认给汇总并支持展开个人汇报 | | SOC 近 30 天告警统计 | 查询实际告警数据源，显示日期、时区、来源和覆盖范围；任务数不能代替告警数 | | 深度调查事件 | 关联确定的事件、负责人和受管执行，展示真实步骤、证据、缺口与最终报告 | 「全部业务」是本人有权查看的查询视角，「通用工作」是工作的归属业务，两者不能混为同一个授权范围。从 SOC 发起默认限 SOC；私有日志与岗位记忆不能因为请求汇总就对全部 Agent 开放。正式任务的责任业务必须明确，跨业务协调也不自动扩权。 ### 提交、恢复与交付约束 一次用户发送要关联同一个请求、会话及按需创建的任务与执行。重复点击或重试复用原请求；响应丢失先核对服务端结果，不能重新建任务并再次派发。受理前失败保留原生可恢复草稿；消息已受理后派发失败则保留原会话消息和交办请求，沿原请求核对与继续，不承诺自动回填已消费的草稿。迟到回执不能清掉用户新编辑的内容或串到另一会话。刷新后无法恢复的本地附件需明确要求重新添加。 进度来自真实执行事实；暂停、配置缺失、部分失败和待审批均需可见。审批发生在命中政策的具体动作上，发送需求不等于授权所有后续操作。执行助手结束不能代替业务验收。 成果回到发起会话或原群话题，并关联任务与事件；群内结果还要核对共享边界。普通回复展示可读名称与来源链接，内部编号留在追溯信息中。准备内容的核验、防覆盖和恢复机制保留给导入及冲突场景，不作为每次正常发送的必经页面。 ### 实现位置与边界 `HomeNativeConversation.tsx` 包裹官方 `main.conversation`，复用完整原生会话、编辑器和提交服务。首页与已有会话保持同一挂载位置，`WorkHome.tsx` 只提供概况。待用会话使用稳定身份，尚未发送时不列入最近工作。`BindingClient` 在打开新会话前完成业务上下文或员工／任务关联，避免首次发送落入错误身份。资料通过原生草稿的版本核对写入；`PreparedPromptCard.tsx` 仅保留给导入与恢复。 `conversation-work.ts` 持久化可信业务上下文、原始用户消息和固定交办名单。`conversation-work-tools.ts` 为本人主会话提供目录、派发、汇报、状态、停止、续办、工作统计和业务查询工具；身份来自实际会话，不接受模型声明的本人身份。`conversation-work-dispatch.ts` 复用现有任务、岗位、资料授权和 Run 服务。请求、Task 和 Run 按原消息固定；新轮次续办也沿用原请求。普通协调会话关联任务后仍可继续协调，专属岗位、任务执行和原生子会话保留自己的边界。 `HomeWorkRequestCard.tsx` 从服务端读取状态，提供原任务入口和停止／续办操作。`conversation-work-publisher.ts` 将已核验的回复写回原会话的原生通知；按稳定内容去重，单个原会话异常不阻塞其他结果。收到员工回复与业务验收完成是不同状态。 原生文件和图片继续通过当前会话的原生输入链路提交。**跨会话交给岗位执行，目前支持文字与已授权的 Teloa 资料引用；含上传附件或其他结构化块的交办会在建任务前明确拒绝，原消息保留。** 不会把图片悄悄降为文件名，也不会据此声称完整附件委派已完成。文件与图片的跨岗位授权快照仍需后续接入。真实 SOC 查询需要配置业务数据源；脚本模型和合成告警源的集成测试不能替代客户真实数据源验收。 正式交办目前要求真实员工。主助手的通用工作沿用原生执行，未新增本人 Task 的受管 Run，也未新增任务专属会话的自动子工作。新汇报使用持久批次与成员任务，没有额外父任务；回复不会自动保存成成果或完成业务验收。原生草稿刷新后保留资料引用的规范文本，但不恢复引用芯片样式或临时本地附件。 ## 修改一个跨包字段 先修改契约和默认值，再检查后端存储、适配层解析、客户端读取和测试夹具。精确键集解析器可能拒绝新字段；只改类型并不能证明运行期兼容。 对新增任务状态、计划来源或资料引用，应有至少一条真实数据库与宿主的集成用例，覆盖从创建到展示的整条路径。 ## 依赖方向 不要让纯契约依赖数据库或 UI。业务服务不直接操纵浏览器组件；客户端也不绕过适配层直接改库。新的 Harness 可以沿清晰边界设计，但当前公开教程只针对已实现的 DSH 适配。