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

# 6.10 资源格式与内部接口

这些格式服务于当前 Alpha 的导入与内部通信，版本升级时应重新验证，不是永久兼容的公开 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` | 岗位定义 | 职责、资料范围、执行范围 |
| `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.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 接口。

系统集成优先使用[已支持的 MCP 路径](https://docs.teloa.ai/v/0.2.3/markdown/develop/mcp.md)。若需要新的稳定集成接口，先明确身份、权限、幂等、版本和错误契约，再实现适配。

## 项目接口

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

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