---
title: 源码架构与包边界
description: 找到功能所在的包，沿一条任务链路修改和验证。
lastVerified: 2026-10-23
---

# 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 分层见[产品架构](https://docs.teloa.ai/v/0.2.27/markdown/concepts/layers.md)。它们说明产品职责，不与上表逐包对应。

## 跟踪一次员工调用

以对外员工 API 为例，按以下顺序读源码：

1. `packages/sdk/contract.mjs`：检查请求字段、状态与结果格式。
2. `packages/harness-dsh/src/employee-integration-host.ts`：看 HTTP/MCP 如何鉴权和派发。
3. `packages/backend/src/work/employee-integrations.ts`：看员工版本、业务与权限如何固定。
4. `packages/backend/src/work/employee-api-work.ts`：看工作、轮次、幂等、结果与事件如何保存。
5. `packages/harness-dsh/src/task-runs.ts`：看原生执行如何准备、开始、核对和停止。
6. `packages/client/ui-workbench/src/client/EmployeeIntegrationSettings.tsx`：看本人如何创建和管理集成。

接口行为的完整例子见[调用员工](https://docs.teloa.ai/v/0.2.27/markdown/develop/employee-api.md)。读代码时沿同一个 work ID、Task ID 和 Run ID 跟踪，不把日志中另一项工作的结果拼到本任务上。

## 修改一个跨包字段

例如给任务增加一项可显示的信息：先修改契约和默认值，再修改数据库读写、适配层解析与客户端显示。增加必要的迁移和兼容读取，最后覆盖旧数据、新数据和非法值。

只改 TypeScript 类型不够：运行期读取器可能严格拒绝未知字段。也不要让 UI 直接读写数据库来绕过业务服务。

## 扩展点

- 新做事方法：优先[SKILL](https://docs.teloa.ai/v/0.2.27/markdown/develop/skills.md)，通常不需要修改核心。
- 新外部系统：优先[MCP 应用](https://docs.teloa.ai/v/0.2.27/markdown/develop/apps.md)，权限在服务端和员工侧分别核验。
- 新模板资源：修改契约读取器、预览、导入、分享与测试，核对四类主体的限制。
- 新执行组件：按[执行引擎边界](https://docs.teloa.ai/v/0.2.27/markdown/develop/engine-integration.md)保留身份、授权、取消与结果来源。
- 本地模型：已有语音和检索配置见[设置指南](https://docs.teloa.ai/v/0.2.27/markdown/guides/settings.md)；新增 provider 需分别验证准备、运行与授权。

先按[本地运行](https://docs.teloa.ai/v/0.2.27/markdown/develop/local-development.md)搭好隔离环境。完成变更的验证方法见[测试与贡献](https://docs.teloa.ai/v/0.2.27/markdown/develop/testing.md)。