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 路径。若需要新的稳定集成接口，先明确身份、权限、幂等、版本和错误契约，再实现适配。
项目接口
内部端点 projects/list、projects/get、projects/create、projects/edit 和 projects/candidates 共用项目契约。本人身份由认证会话提供；创建使用请求 UUID，编辑携带 expectedVersion 并拒绝冲突覆盖。创建后业务范围不可修改。
关联由 task、group、role、plan、resource 或 artifact 类型与记录 ID 组成。新关联只接受范围内可用记录，详情按关联记录推导任务进度与成果。关联不等于执行授权，也不修改原记录。