6.7 源码架构与包边界
客户端表达用户操作，后端维护业务状态，Harness 适配执行模型与工具，共享契约连接这些层。
React 工作界面
│ 共享契约
Harness / RPC 适配 ── DSH 模型、会话和工具
│
业务服务 ── PostgreSQL
│
资源、任务、员工、群与自动化产品架构为 AI Team / Agent Studio / Agent Harness，解释团队、工作定义与运行底座。上图和下方包表属于系统实现视图，不与产品三层一一对应，也不把业务面、数据面、执行面混入产品架构图。原生 Plugin、Bundle、运行配置和 Agent 的映射约定见业务能力与执行引擎边界。
代码放在哪
| 包 | 职责 |
|---|---|
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 起，避免旧读取器无法理解新形态。本地检索使用 Qwen3 Embedding 0.6B 与 EmbeddingGemma 2 的固定适配，与市场模型目录分开维护。模型权重许可与源码许可分列。搜索或会话引导不会启用插件、下载权重或更改聊天模型。第三方 OCR、分类、重排等适配尚未实现，不应只改目录中的 provider 名就声称可安装。
插件代码、模型权重与本机运行绑定分开管理。已有原生准备器直接复用；大权重不进入 Skill 文本内容仓。专用模型绑定对应能力或工具，只有对话模型进入聊天选择器；主助手可继续使用云端模型。本地指 Teloa 宿主，例如用户部署的 Mac mini，不一定是打开网页的设备。硬件兼容、内存和质量以具体模型的实测为准。通用的第三方模型发布和运行适配仍在建设中。
私有化中、大模型由用户自行部署在 GPU 服务器上，Teloa 通过 DSH 原生自定义模型 API 接入，不负责 GPU 部署和调度，也不向客户端下载这些权重。远程备用可以是用户私有模型服务；“远程”不等同公有云，首选与备用遵循用户配置。连接私有模型服务不等于整个任务已被限制在内网，后者还需要核验工具和子任务的出站行为。
端侧中文检索
能力与目录状态
当前发行随附 Qwen3 Embedding 0.6B 与 EmbeddingGemma 2 检索适配。本人可在资料页的检索模型面板查看来源、容量与许可，确认准备后选择使用。这些固定适配与官方市场模型目录分开维护，任意第三方模型不能仅修改目录即可安装。
@teloa/local-embedding 将 Qwen3-Embedding-0.6B 用于授权资料内的定位，提供 1024 维嵌入。它是可停用的 Teloa 扩展，不是 DSH 原生语音服务，也不进入会话、员工或默认聊天模型的候选。主助手仍使用自己的聊天模型；“本地”指运行 Teloa 的宿主。
本人显式加入资料 -> 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 名安装第三方代码。
方案如何声明模型依赖
协议适用范围
业务包支持 teloa.business-package/v3 的模型依赖声明。声明本身不安装模型或授予工具权限；能否运行取决于已审核的目录绑定、对应 provider 的真实状态与当前业务授权。
v3 的 skill 或 work-template 资源可声明 modelDependencies，将模型依赖放在实际使用它的入口上。v2 保持原有结构，拒绝该新字段。每项只允许 catalogId、固定目录 version、usage 和 required；字段存在时须有 1～16 项，同一模型与用途不能重复。清单不接受下载 URL、命令、凭据或运行地址。
下面两份文件构成最小方案。它示范前置依赖：用户通过原生语音输入生成并核对文字，任务负责整理文字。依赖声明不会自动获得音频转写工具，也不会把 SenseVoice 设置为聊天主模型。 若任务需要直接处理音频文件，仍需另行接入和授权实际工具。
teloa.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：
{
"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 需提供锁定版本的模型文件、许可、硬件要求、工具权限和质量证据。
统一输入与工作执行
首页与会话共用原生输入
首页首次发送建立或复用本次会话，欢迎区原地展开为工作会话，首条消息已提交；进入已有会话则延续上下文。首页不要求用户先判断「对话／工作」，也不在发送后要求再次「带入输入框」。会话记录可从最近工作找回，正式任务按需要建立。
两处复用 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 查询需要配置业务数据源；脚本模型和合成告警源的集成测试不能替代客户真实数据源验收。
正式交办可由 AI 员工承担，也可在通用工作中交给通用 Agent，无需预先创建员工。通用任务使用本人的执行授权、任务专属会话和受管 Run，保留原消息、资料及额度边界；按本次授权委派子工作。收到回复不等于成果已保存或业务验收完成。
修改一个跨包字段
先修改契约和默认值，再检查后端存储、适配层解析、客户端读取和测试夹具。精确键集解析器可能拒绝新字段；只改类型并不能证明运行期兼容。
对新增任务状态、计划来源或资料引用，应有至少一条真实数据库与宿主的集成用例，覆盖从创建到展示的整条路径。
依赖方向
不要让纯契约依赖数据库或 UI。业务服务不直接操纵浏览器组件；客户端也不绕过适配层直接改库。新的 Harness 可以沿清晰边界设计，但当前公开教程只针对已实现的 DSH 适配。