Release v1.0.108: precipitate user-facing copy contract

references/ACTIONS.md

@@ -167,6 +167,47 @@ Action 是否提供、挂哪些 `placements`，由本技能 **入口定位表**
 
 示例：[`assets/examples/selection-mode-optional.action.example.json`](../assets/examples/selection-mode-optional.action.example.json)。
 
+弹窗上的 `description` / 参数说明须用**普通用户中文**（见下节「用户可见文案」）；`pickCount` 等只作 **property 名 / CLI 参数名**，不要写进用户可读句子。
+
+### 用户可见文案（双受众，必读）
+
+宿主会把下列字段**原样展示给普通用户**（数据管理弹窗、任务中心时间线、表说明等）：
+
+| 字段 | 出现位置 |
+|------|----------|
+| Action `description` | 弹窗顶部说明 |
+| `confirmation.message` | 确认/表单黄条 |
+| `inputSchema` 各字段 `title` / `description` | 参数区标签与帮助 |
+| CLI / `finish` 返回的用户向 `message` | 任务中心、失败摘要 |
+| 表/列 `display_name`、表 `description` | 数据管理侧栏与表头帮助 |
+
+**总原则：** 以上文案 = **产品用语、全中文**。Agent 路由禁令、实现细节、契约自述放在 **`SKILL.md` / `references/`**，**不要**塞进弹窗 `description`。
+
+**允许写：** 待下载、任务中心、打开浏览器、有勾选 / 没有勾选、下载数量、按钮中文名（如「导入待下载链接」）。
+
+**禁止写进用户文案（常见反例）：**
+
+| 类型 | 反例 |
+|------|------|
+| 字段名 / CLI 子命令 | `pickCount`、`itemIds`、`import-urls`、`enqueue` |
+| 英文状态 / 条件式 | `pending`、`status=pending`、`failed` |
+| 执行剖面黑话 | `async`、`sync`、单独甩 `Job`（可说「任务中心」） |
+| Agent 禁令 | 「不是明确 URL 入口」「不要先 download-enqueue…」 |
+| 契约自述 | 「示例：bind.selectionMode=optional」 |
+
+**对照：**
+
+| 差（开发者备注） | 好（普通用户） |
+|------------------|----------------|
+| 按 `pickCount` 从 `pending` 领取（async） | 没有勾选则按下方数量从待下载队列领取；进度可在任务中心查看 |
+| 请先 import-urls | 请先在数据管理录入链接，或使用「导入待下载链接」 |
+
+**边界：**
+
+- `inputSchema` **属性名**、`entrypoint` 参数、库表状态枚举值可以仍是英文；变的是 **title / description / message**。
+- `label` 仍遵循上文「Action 按钮中文名」；本节约束的是说明与帮助文字。
+- 与 `bind.selectionMode` 正交：行为对了，文案仍须对人说人话。
+
 ### 数据管理：选择摘要（宿主默认能力）
 
 当用户在数据管理**勾选行**（或行内打开带行上下文的动作）后打开 `confirm` / `form` 弹层时，若当前 Action 的 `selectionMode` 会**应用**表勾选（`required`，或 `optional` 且已勾选），宿主会展示通用 **「已选择 · N 条」** 摘要（`#主键` + 可读标签；超过约 3 条可展开查看全部）。这是**宿主 UX**，对适用技能默认生效：