应用开发与 Manifest v1 协议
公开受约束应用的字段、数据源、组件和版本规则,给出可核对的 JSON 示例。
协议用途与运行边界
当前应用描述由受约束 JSON 声明数据源与组件,运行时负责取数和呈现。它不是允许任意脚本、HTML 或插件代码运行的通用扩展协议。manifest 通过结构校验也不代表有权读取数据,仍需验证组织、用户、数据源和发布版本。外部开发者导入或上架流程需另行验证和约定。
最小可核对示例
以下示例对应当前 parseMiniApp 校验结构,只读展示项目数量和项目列表。source 决定可用字段,不支持自行加入 URL、密钥或脚本。该示例验证的是数据结构,实际显示仍依赖已授权数据与兼容运行时。
{
"schemaVersion": 1,
"title": "Project overview",
"summary": "Read-only authorized project overview",
"source": "company.projects.read",
"icon": "chart",
"accent": "blue",
"widgets": [
{
"type": "metric",
"label": "Active projects",
"field": "activeProjects"
},
{
"type": "table",
"label": "Projects",
"columns": [
{
"field": "title",
"label": "Title"
},
{
"field": "status",
"label": "Status"
}
]
}
]
}顶层字段与封闭校验
当前结构拒绝未知字段。所有标签需为非空字符串,不允许控制字符和尖括号,保存和本地渲染前均应使用同一契约校验。schemaVersion 表示结构版本,不等于某个应用的内容修订号。
| 字段 | 约束 |
|---|---|
| schemaVersion | 固定为数字 1 |
| title / summary | 标题最多 40 字符;摘要最多 160 字符 |
| source | 只能选择已声明的数据源之一 |
| icon | chart / table / activity |
| accent | blue / green / rose |
| widgets | 1–6 个组件;最多一个 table 或 worklist |
数据源与字段白名单
这些名称来自当前源码契约,不是面向公网开放的查询接口。新增源需要服务端取数、权限与运行时适配,不能只修改 manifest。读取结果应保留捕获时间、口径、范围与完整性说明。
| source | metric 字段 | table 列 |
|---|---|---|
| company.projects.read | projectCount, activeProjects | title, status, objective |
| company.work.read | openTasks, awaitingReview, blockedTasks, overdueTasks | title, status, project, assignee, dueAt |
| store.completedServices.read | serviceItemCount, ordersWithoutItems | productId, count |
组件约束与错误样本
metric 使用 type、label、field,field 必须属于所选 source 的指标;table 使用 type、label、columns,列数为 1–3 且字段不得重复;worklist 只允许 company.work.read。组件 label 最多 40 字符,列 label 最多 30 字符。跨源字段、重复表格、未知组件、空标题和额外属性都应被拒绝,而不是静默丢弃。
版本、审批与发布
应用内容修订应保存父版本、摘要、生成状态和批准信息。只发布指定的已就绪版本,校验其数据范围和审批依据;修改来源、字段或业务口径后重新验收。平台内部存在修订与候选结构不代表已提供外部上架 API,正式接入需确认发布入口、回退及兼容策略。
开发者需要交付什么
交付 manifest、数据源说明、权限矩阵、正常与错误样本、兼容版本、业务验收记录和维护负责人。若需求涉及任意前端代码、交互写入或新数据源,将其作为单独扩展方案评估,不将这些能力写成 Manifest v1 的既有功能。