@doubao-dev/cli 0.0.19 → 0.0.20

package/skills/doubao-agentic-service-development/references/manifest-guide.md

@@ -287,7 +287,7 @@ tools:
 entities:
   github_repo:
     schema:
-      entity_id: { type: string, description: 仓库业务 ID, is_entity_id: true }
+      entity_id: { type: string, description: 仓库业务 ID, is_entity_id: true, is_refresh_key: true }
       entity_type: { type: string, description: 业务实体类型, llm_visible: false }
       full_name: { type: string, description: 仓库全名 }
       stars: { type: int, description: Star 数 }
@@ -308,7 +308,7 @@ entities:
 - entity 结构复杂或字段很多时，`schema` 不必完整枚举业务返回；只强制声明稳定业务 ID、明确需要进入模型上下文的字段，以及使用 `llm_modifiable` 等平台能力所需的字段。其它未声明字段仍会原样透传给卡片，但不会自动进入模型上下文。
 - `entities.<entity_type>.tool_card_binding` 与 `schema` 同级；key 是工具名，value 是该工具返回该 entity 时使用的前端 `widget_id`。
 - `widget_id` 来自前端工程 `src/app.config.ts` 的 `defineAppConfig({ widgets })`：显式对象写法取 `widgets[].id`，字符串简写取 `widgets` 目录下的目录名。
-- `entities.<entity_type>.history_card_refresh` 与 `schema` 同级，用于声明是否支持历史卡片刷新。
+- `entities.<entity_type>.history_card_refresh` 与 `schema` 同级，用于声明是否支持历史卡片刷新。历史卡片刷新的匹配键来自 `schema` 中被 `is_refresh_key: true` 标记的字段值；实体 schema 中必须声明 `is_refresh_key` 字段才能使用历史卡刷新。
 - `tools.<tool>.output.kind` 声明工具返回按哪类结果处理。
 - `tools.<tool>.output.entity_types` 只在 `kind=entities` 时配置，并且每个类型都应出现在 `entities`。
 - Manifest 不声明模板字段、JSONPath、列表槽位、按钮动作、点击参数或 tool 级 `rendering`。
@@ -323,13 +323,14 @@ entities:
 | `schema.<field>.type` | 字段类型；使用平台支持的 Manifest schema 类型。 |
 | `schema.<field>.description` | 字段说明。 |
 | `schema.<field>.is_entity_id` | 是否为顶层 entity 的稳定业务 ID；每个 entity 应选择一个稳定 ID 字段。 |
+| `schema.<field>.is_refresh_key` | 是否为卡片刷新键；卡片下发时该字段值会作为卡片的 `refresh_key`，服务端可通过「刷新卡片实例」API 用相同值更新卡片数据。同一 entity 内最多一个字段可标记为刷新键，允许位于顶层或 object 内，不能位于 array items 内。历史卡片刷新也依赖该字段匹配。 |
 | `schema.<field>.llm_visible` | 字段是否给模型感知；不配置时按可见处理，跳转、图片、内部 ID 等渲染/执行字段通常设为 `false`。 |
 | `schema.<field>.llm_modifiable` | 字段是否允许模型修改；当前用于 `type: array` 的列表字段，语义是模型可从原始 item 中筛选子集。 |
 | `schema.<field>.items` | `type: array` 时的 item schema。 |
 | `schema.<field>.properties` | `type: object` 或 array item 为 object 时的子字段定义。 |
 | `tool_card_binding` | 当前 entity 在不同 tool 返回时使用的卡片 widget 映射。 |
 | `tool_card_binding.<tool_name>` | key 是实际 MCP tool 名，value 是前端工程中声明或推导出的 `widget_id`。 |
-| `history_card_refresh` | 历史卡片刷新配置。 |
+| `history_card_refresh` | 历史卡片刷新配置。匹配键来自 `schema` 中被 `is_refresh_key: true` 标记的字段值。 |
 | `history_card_refresh.enabled` | 是否支持历史卡片刷新。 |
 | `history_card_refresh.scope` | 刷新范围；文档示例为 `same_conversation`。 |
 | `history_card_refresh.refresh_to` | 刷新目标样式；文档示例为 `fixed_style`。 |
@@ -398,7 +399,7 @@ entities:
 - 每个顶层 entity schema 应有且只有合理的稳定业务 ID 字段标记 `is_entity_id: true`。
 - `tool_card_binding` 的 key 应是实际 MCP tool 名。
 - `tool_card_binding` 的 value 应是前端工程中已注册的卡片 `widget_id`，不是 `@doubao-apps/template` 组件名。
-- 如需支持历史卡片刷新，按文档配置 `history_card_refresh.enabled`、`scope`、`refresh_to`。
+- 如需支持历史卡片刷新，需在 `schema` 中声明 `is_refresh_key: true` 字段，并按文档配置 `history_card_refresh.enabled`、`scope`、`refresh_to`。
 - 业务 ToolResult 只需要按工具类型返回 `content`、`structuredContent` 和 `isError`。
 - 不要把 UI 字段映射写进 Manifest；字段展示由卡片代码读取 entity 数据后处理。
 ## 工具运行配置

package/skills/doubao-agentic-service-development/references/mcp-protocol.md

@@ -105,7 +105,7 @@
 entities:
   route:
     schema:
-      entity_id: { type: string, description: 路线业务 ID, is_entity_id: true }
+      entity_id: { type: string, description: 路线业务 ID, is_entity_id: true, is_refresh_key: true }
       entity_type: { type: string, description: 业务实体类型, llm_visible: false }
       title: { type: string, description: 路线标题 }
       duration_minutes: { type: int, description: 预计耗时 }
@@ -124,10 +124,11 @@ entities:
 
 - `entity_type` 是业务实体类型，业务返回中必带，并且必须命中 Manifest 中声明的实体类型。
 - `is_entity_id: true` 标记顶层 entity 的稳定业务 ID。字段名由业务 schema 决定。
+- `is_refresh_key: true` 标记卡片刷新键。卡片下发时该字段值会作为卡片的 `refresh_key`，服务端可通过「刷新卡片实例」API 用相同值更新卡片数据。同一 entity 内最多一个字段可标记为刷新键。历史卡片刷新也依赖该字段匹配。
 - `llm_visible` 控制字段是否投影给模型，默认 `true`。
 - `llm_modifiable` 控制字段是否允许模型修改；首期只支持 `type: array` 的列表字段，语义是模型可从原始列表中筛选 item 子集。
 - `tool_card_binding` 与 `schema` 同级，key 是工具名，value 是当前工具返回该 entity 时使用的前端 `widget_id`。
-- `history_card_refresh` 与 `schema` 同级，用于声明是否支持历史卡片刷新。
+- `history_card_refresh` 与 `schema` 同级，用于声明是否支持历史卡片刷新。匹配键来自 `schema` 中被 `is_refresh_key: true` 标记的字段值；实体 schema 中必须声明 `is_refresh_key` 字段才能使用历史卡刷新。
 
 复杂 entity 的 schema 可以按模型需要精简，不必复制完整的业务返回结构：
 
@@ -218,7 +219,7 @@ tools:
 entities:
   route:
     schema:
-      entity_id: { type: string, is_entity_id: true }
+      entity_id: { type: string, is_entity_id: true, is_refresh_key: true }
       entity_type: { type: string, llm_visible: false }
       title: { type: string }
       duration_minutes: { type: int }