---
title: 资源格式与内部接口
description: 核对格式、默认值、版本和错误，不依赖未稳定的 API。
lastVerified: 2026-10-22
---

# 6.14 资源格式与内部接口

这些格式对应社区版 0.2.4 的资源导入与内部通信。升级后重新核对读取器；面向业务系统的调用契约见员工 API 指南。

## 常用资源格式

| 格式 | 用途 | 核对重点 |
| --- | --- | --- |
| `teloa.business-package/v2` | 业务包清单 | 资源身份、锁定版本、关联与范围 |
| `teloa.business-package/v3` | 带模型依赖的业务包 | 固定模型声明与逐入口准备状态 |
| `teloa.business-package/v4` | 可包含完整配置的业务包 | `business-configuration` 资源仅 v4 支持；最低 alpha.7 |
| `teloa.business-dashboard-resource/v1` | 可复用业务看板资源 | 固定身份与版本、完整配置 v2、页面与定义引用闭合；不携带记录、同步绑定或默认动作 |
| `teloa.role/v1` | AI 员工岗位模板 | 职责、资料与执行范围，以及五组结构化职责 |
| `teloa.work-template/v1` | 任务模板 | 输入要求、输出、技能引用版本 |
| `teloa.mcp-connection/v1` | MCP 连接定义 | serverName 与工具集合 |
| `teloa.reference-list/v1` | MCP 资料列表 | 来源、字节数、SHA-256 版本 |
| `teloa.reference/v1` | MCP 读取结果 | 正文与同版本来源 |

资源包的 `scope` 默认取 `domain`。引用的版本与资源定义必须一致；不要依赖 JSON 字段顺序作为对象相等判据。

## 四类分享主体

`teloa.template-share/v2` 用 `subject` 区分 `employee`（恰好一位员工）、`team`（至少两位员工）、`app`（无员工，包含技能、MCP 或扩展）、`skill`（恰好一项技能）；连接还可单独用 `mcp`。它的 `files` 包含 `teloa.json` 的 UTF-8 正文，后者使用 business-package/v2、v3 或 v4。两层身份和固定版本一致，资源所需 people/automation/connections/business 能力须声明。应用目录没有单独 app kind，不影响分享格式有 app 主体。

旧 `teloa.template-share/v1` 仍只按原固定员工格式读取。分享包中的员工定义不包含 `runtimeConfig`，比下述单独岗位读取边界更严格。示例与分发步骤见[分享指南](https://docs.teloa.ai/v/0.2.6/markdown/guides/sharing.md)。

## AI 员工模板

`teloa.role/v1` 是 Teloa 当前使用的岗位模板导入格式。[AI Worker 开放定义标准 1.0](https://github.com/teloa-ai/ai-worker-standard) 描述工作个体、工作合同与协作规则；它与这里的产品导入格式分别维护，不能把标准交换文档直接当作岗位模板，也不能加入读取器未支持的字段。

模板以 `name`、`kind`、`duty`、`dataScope` 和 `executionScope` 描述身份、职责与范围。当前新建或编辑员工时，必须显式提交 `responsibility` 对象，包含以下五个字符串数组：

| 字段 | 说明 |
| --- | --- |
| `triggers` | 触发：何时接手工作 |
| `autonomousActions` | 自主：在既有授权内可自行完成什么 |
| `confirmationPoints` | 确认：哪些步骤需要必要确认 |
| `escalationRules` | 升级：信息不足、冲突或越界时如何报告与交接 |
| `deliveryChecks` | 交付：成果包含什么、如何检查完成情况 |

五个字段都必须存在；每组最多 30 条，每条最多 1 000 个字符。数组允许为空，空数组不代表获得额外权限。当前模板已扩充结构化职责，文件格式编号保持 `teloa.role/v1`。旧模板缺少整个 `responsibility` 时，读取器补齐五个空数组，不会自动生成职责；编写新模板时应明确填写与岗位相符的内容。

以下示例中的指令使用英文；导入后仍保持既有授权与必要确认：

```json
{
  "format": "teloa.role/v1",
  "name": "Research Assistant",
  "kind": "employee",
  "duty": "Summarize supplied material and distinguish evidence from open questions.",
  "dataScope": "Only supplied material and already authorized references.",
  "executionScope": "Read and draft within existing authorization; retain required confirmations.",
  "responsibility": {
    "triggers": ["When assigned a summary of supplied material."],
    "autonomousActions": ["Read authorized material and draft a source-based summary."],
    "confirmationPoints": ["Ask before expanding the authorized data or execution scope."],
    "escalationRules": ["Report missing or conflicting evidence without inventing conclusions."],
    "deliveryChecks": ["Include sources, findings, open questions and incomplete work."]
  },
  "runtimeConfig": {
    "agentPresetId": "teloa-standard"
  }
}
```

`runtimeConfig` 可省略。模板可携带 `agentPresetId` 预设标识，是否可用仍由接收端准备时核对；模板中的 `model`、`fallbackModel` 会被忽略，不会继承来源的模型选择。模型及账户由本人在接收端选择与配置。

岗位模板不携带实例的 `scopes`、`skills`、`knowledge`、凭据或授权；这些字段不能直接塞入该文件，相关资源由包清单与接收端实例分别绑定。导入定义不会自动连接账号、开始工作或扩大权限。

## 业务看板定义与查询边界

业务看板一期新增三种业务定义，与对象类型、视图、动作一样依次走「会话草案、预览、本人确认」三步，读取器严格校验字段：

| 格式 | 用途 | 核对重点 |
| --- | --- | --- |
| `teloa.business-source-mapping/v1` | 数据源映射 | 来源只能是业务数据端口、受管 MCP 只读工具或 AI 员工成果；JSONPath 子集、主键 1–3 个、删除语义、同步周期 |
| `teloa.business-widget/v1` | 看板组件 | 七种组件；SQL 只能引用本范围已定义的对象类型（表名 `-` 换成 `_`）与字段；图表为 Vega-Lite 规范，键按白名单校验 |
| `teloa.business-dashboard/v1` | 看板 | 12 列网格、引用的组件、刷新周期（短于 60 秒须 `acknowledgeShortInterval: true`，短于 10 分钟界面提示外部额度与本机资源） |

组件 SQL 先过语法树白名单（只允许一条 SELECT、白名单函数与节点，禁止模式名、系统表、占位符与多语句），再改写为按本人、本范围读取快照表当前版本的参数化查询，二次校验与往返校验通过后才执行。执行使用只读角色 `teloa_business_reader` 与专用连接池：单条 5 秒、最多 10 000 行、单行 1 MB、累计 8 MB，每范围并发 5（进程内）。改写产物中的快照表与安全转换函数按 Teloa 表所在 schema 限定（取应用连接的 `current_schema()`，个人版为 `public`）。白名单常量在 `packages/backend/src/work/business-sql-whitelist.ts`，对应真库用例在 `packages/backend/tests/business-sql-guard.test.ts`、`business-sql-rewrite.test.ts` 与 `business-sql-executor.test.ts`。

草案工具的请求身份按「指令 + 定义种类 + 定义 id」派生：同一定义重放替换同一份草案，一条指令可以存多份不同定义。返回内容按规范化正文（键名排序）比对，不依赖字段顺序。

## 未知字段与损坏数据

多处读取器采用严格字段校验，拼错的字段不会自动忽略。格式不合法与已存数据损坏应分别处理：前者修正输入，后者保留证据并从可信备份或来源修复。

## 内部 RPC

客户端经 Harness 使用内部 RPC 请求。端点、请求信封、鉴权 Cookie 与返回解析会随版本变化，不应把浏览器抓到的请求直接当成面向第三方的稳定 REST 接口。

业务系统调用员工使用[员工工作 API、SDK 与 MCP Server](https://docs.teloa.ai/v/0.2.6/markdown/develop/employee-api.md)；员工访问外部资料使用[已支持的 MCP 路径](https://docs.teloa.ai/v/0.2.6/markdown/develop/mcp.md)。两种方向的身份、授权与请求边界分别核对。

## 项目接口

内部端点 `projects/list`、`projects/get`、`projects/create`、`projects/edit` 和 `projects/candidates` 共用项目契约。本人身份由认证会话提供；创建使用请求 UUID，编辑携带 `expectedVersion` 并拒绝冲突覆盖。创建后业务范围不可修改。

关联由 `task`、`group`、`role`、`plan`、`resource` 或 `artifact` 类型与记录 ID 组成。新关联只接受范围内可用记录，详情按关联记录推导任务进度与成果。关联不等于执行授权，也不修改原记录。