6.10 源码架构与包边界
本篇面向修改 Teloa 源码的开发者。先找到功能所在的包，再沿用户操作、业务状态和执行结果检查完整链路。
从一项工作看代码分工
text
用户提交 -> React 工作界面 -> Harness / RPC -> 业务服务 -> PostgreSQL
|
-> 原生会话、模型与工具
|
执行事件 -> Task / Run 状态与成果 -> 原会话和任务界面Teloa 保存员工、任务、审批与成果的业务归属；DSH 提供原生执行。模型回复、执行结束和业务验收是不同事实。
修改什么，去哪里找
| 目录 | 主要职责 | 常见变更 |
|---|---|---|
packages/contract | 类型、格式读取器和校验 | 新字段、模板格式、请求与返回 |
packages/backend | 存储、事务、幂等与业务规则 | 任务状态、固定结果、权限记录 |
packages/harness-dsh | 原生引擎适配与工具授权 | 会话上下文、派发、停止、结果回流 |
packages/client/ui-workbench | 工作台界面与状态呈现 | 员工、群、任务、设置与详情抽屉 |
packages/client/ui-kit | 共享界面组件 | 通用控件与交互容器 |
packages/bundle | 固定插件组合与运行预设 | 引擎组合和预设配置 |
packages/sdk | 对外员工调用合同与客户端 | HTTP、SDK、MCP 的共用格式 |
packages/cli | 原生安装与服务生命周期 | 启动、停止、备份与升级 |
packages/mcp-reference | 只读资料 MCP 服务 | 资料列举、固定版本读取与拒绝路径 |
packages/local-embedding | 本地检索适配 | 权重准备、嵌入、索引与检索 |
产品的 AI Team、Agent Studio、Agent Harness 分层见产品架构。它们说明产品职责，不与上表逐包对应。
跟踪一次员工调用
以对外员工 API 为例，按以下顺序读源码：
packages/sdk/contract.mjs：检查请求字段、状态与结果格式。packages/harness-dsh/src/employee-integration-host.ts：看 HTTP/MCP 如何鉴权和派发。packages/backend/src/work/employee-integrations.ts：看员工版本、业务与权限如何固定。packages/backend/src/work/employee-api-work.ts：看工作、轮次、幂等、结果与事件如何保存。packages/harness-dsh/src/task-runs.ts：看原生执行如何准备、开始、核对和停止。packages/client/ui-workbench/src/client/EmployeeIntegrationSettings.tsx：看本人如何创建和管理集成。
接口行为的完整例子见调用员工。读代码时沿同一个 work ID、Task ID 和 Run ID 跟踪，不把日志中另一项工作的结果拼到本任务上。
修改一个跨包字段
例如给任务增加一项可显示的信息：先修改契约和默认值，再修改数据库读写、适配层解析与客户端显示。增加必要的迁移和兼容读取，最后覆盖旧数据、新数据和非法值。
只改 TypeScript 类型不够：运行期读取器可能严格拒绝未知字段。也不要让 UI 直接读写数据库来绕过业务服务。