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，比下述单独岗位读取边界更严格。示例与分发步骤见分享指南。
AI 员工模板
teloa.role/v1 是 Teloa 当前使用的岗位模板导入格式。AI Worker 开放定义标准 1.0 描述工作个体、工作合同与协作规则；它与这里的产品导入格式分别维护，不能把标准交换文档直接当作岗位模板，也不能加入读取器未支持的字段。
模板以 name、kind、duty、dataScope 和 executionScope 描述身份、职责与范围。当前新建或编辑员工时，必须显式提交 responsibility 对象，包含以下五个字符串数组：
| 字段 | 说明 |
|---|---|
triggers | 触发：何时接手工作 |
autonomousActions | 自主：在既有授权内可自行完成什么 |
confirmationPoints | 确认：哪些步骤需要必要确认 |
escalationRules | 升级：信息不足、冲突或越界时如何报告与交接 |
deliveryChecks | 交付：成果包含什么、如何检查完成情况 |
五个字段都必须存在；每组最多 30 条，每条最多 1 000 个字符。数组允许为空，空数组不代表获得额外权限。当前模板已扩充结构化职责，文件格式编号保持 teloa.role/v1。旧模板缺少整个 responsibility 时，读取器补齐五个空数组，不会自动生成职责；编写新模板时应明确填写与岗位相符的内容。
以下示例中的指令使用英文；导入后仍保持既有授权与必要确认：
{
"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；员工访问外部资料使用已支持的 MCP 路径。两种方向的身份、授权与请求边界分别核对。
项目接口
内部端点 projects/list、projects/get、projects/create、projects/edit 和 projects/candidates 共用项目契约。本人身份由认证会话提供；创建使用请求 UUID，编辑携带 expectedVersion 并拒绝冲突覆盖。创建后业务范围不可修改。
关联由 task、group、role、plan、resource 或 artifact 类型与记录 ID 组成。新关联只接受范围内可用记录，详情按关联记录推导任务进度与成果。关联不等于执行授权，也不修改原记录。