10 KiB
Minutes 复杂流程
只在根 Skill 已确定属于 ASR、上传恢复、异步生成或批量权限 workflow 时读取本文件。普通搜索、详情、逐字稿、标题或摘要修改直接按根 Skill Golden Route 执行。
1. ASR 热词
| 用户意图 | 推荐入口 | 是否确认 | 关键语义 |
|---|---|---|---|
| “录音前加上这些专有词”“补充热词” | dws minutes +prepare-asr --words "DWS,听记" |
需要 | 只新增缺失热词，不删除现有项；读回验证 |
| “让热词最终只保留这组”“精确同步热词” | dws minutes +sync-asr --words "DWS,听记" |
需要，且先说明会删除目标集合外热词 | 新增缺失项并删除多余项；属于 destructive/high |
| 只查看当前 ASR 热词 / “识别词配置” | dws minutes hot-word list --format json |
不需要 | 原子只读；返回当前账号的识别词配置，不是某个音频的转写结果 |
| 删除一个或多个已知热词 | dws minutes hot-word delete --words "<热词1,热词2>" |
原子入口历史 not_required |
仅作兼容底层入口；推荐需要确认且能读回验证的 +sync-asr，不模糊删除 |
+prepare-asr --sync 作为已发布参数保持公开可见，但只返回迁移提示且在任何 MCP 调用前停止。需要删除时必须显式改用 +sync-asr，不能把“准备热词”解释成“覆盖整个词表”。两个 Shortcut 的 --dry-run 都只输出本地计划，不读取或写入远端；要比较真实差异时先读取词表，再单独执行目标入口。
用户说“先核对识别词/词表”时，默认指当前 ASR 热词配置，必须实际执行 hot-word list，不能只展示命令。如果用户明确要核对某个音频最终识别出的文字，则必须真实上传并等待转写；upload dry-run 做不到这一点。用户同时要求“不实际创建听记”时，以不写入为最高边界，如实说明两项要求不能同时满足，不能通过真实 create 后 cancel 来伪造预览。
2. 上传、通知与恢复
2.1 直接上传
| 目标 | 推荐入口 | 结果边界 |
|---|---|---|
| 上传并创建听记，不发送额外消息 | dws minutes +upload --file <相对路径> [--title <标题>] |
真实执行需要确认；完成 create、文件 PUT、complete 和详情读回，失败时取消可取消的 session |
| 上传并额外发送闪记卡片 | dws minutes +upload-and-notify --file <相对路径> [--title <标题>] |
推荐新入口；旧 +upload --enable-message-card 仍可执行并遵循 +upload 的确认门禁 |
| 上传并等待摘要/逐字稿等分析产物 | dws minutes +upload-and-analyze --file <相对路径> --artifacts summary,transcript |
真实执行需要确认；有界等待，可加 --mindmap / --speaker-insights，不要把 pending/timeout 说成完成 |
用户要求预览上传，并明确要求核对热词配置或比较听记列表是否变化时，执行以下可验证流程；没有这些额外要求时不必增加读操作：
dws minutes hot-word list --format json
dws minutes +list-mine --page-all --format json
dws minutes +upload --file <相对路径> --title "<标题>" --input-language zh --template-id <templateId> --dry-run --format json
dws minutes +list-mine --page-all --format json
- 热词查询、上传计划和前后列表是三份不同证据；命令示例不能代替真实查询结果。
- dry-run 只证明请求计划与
executed=false，不会创建 session、听记或 ASR 结果。前后列表按taskUuid集合比较；不能只比较数量或第一页。 - 没有真实文件、文件字节数或 sessionId 时，停止在相应前置门禁；不得调用 create/complete。用户要求确认“没有生成新听记”时，仍需用真实列表证据回答，不能仅由“我没有调用上传”推断列表事实。
如果已有 taskUuid，并且只需要读取当前已经生成的摘要与逐字稿，直接使用只读入口：
dws minutes +detail --id <taskUuid> --artifacts basic,summary,keywords --format json
dws minutes +transcript --id <taskUuid> --format json
不要仅因资源最初来自上传就再次进入上传 workflow。只有产物尚未就绪、确实需要有界轮询时，才使用：
dws minutes +upload-and-analyze --resume-id <taskUuid> --artifacts summary,transcript
--resume-id 分支不重复上传或再次通知，但 +upload-and-analyze 是同时包含新上传分支的混合入口，因此仍按该命令的 Runtime confirmation 执行。旧 +upload-and-analyze --enable-message-card 继续执行原有通知语义并遵循同一确认门禁；新调用需要通知时优先使用 +upload-and-notify，再按需读取或恢复分析。
2.2 原子 upload session
只在 Shortcut 返回了可恢复 session、需要诊断某一阶段，或调用方自己负责文件 PUT 时使用原子命令：
| 阶段 | 原子命令 | 关键句柄 |
|---|---|---|
| 创建普通 session | dws minutes upload create ... |
保存 session/upload URL 等真实返回；旧 --enable-message-card 只返回迁移提示 |
| 创建并通知 | dws minutes upload create-and-notify ... |
需要确认；不要用普通 create 模拟通知 |
| 完成 session | dws minutes upload complete ... |
只对已知 session 执行，保留最终 taskUuid |
| 取消 session | dws minutes upload cancel ... |
取消失败或状态未知时停止，不能谎报已清理 |
上传状态未知时先根据真实 session/taskUuid 读回；不能重新 create 来“试一次”。预签名 URL 属于敏感临时数据，不写入日志、报告或长期 manifest。
3. 异步生成与录音收尾
3.1 思维导图
dws minutes +mindmap --id <taskUuid>
- 首次执行负责 create + 有界轮询。
- 真实执行遵循
user_required；--resume沿用同一命令级门禁。 - 返回 pending/timeout 时保留 taskUuid；继续检查用
--resume，不重复 create。 - 只有明确终态成功才声称已生成；失败和无法解析的状态返回非零。
3.2 发言人洞察
dws minutes +speaker-insights --id <taskUuid>
- 首次执行保存 create 返回的异步
taskId。 - 真实执行遵循
user_required；--resume沿用同一命令级门禁。 - 超时后使用
--resume [--task-id <taskId>]继续轮询。 taskId缺失、状态未知或结果不可解析时保留恢复信息并停止，不再次创建任务。
3.3 结束录音并等待产物
dws minutes +record-wrap-up --id <taskUuid> --artifacts summary,transcript
该入口先停止指定录音，再有界等待产物。它只接受已绑定的真实 taskUuid；如果 +record-start 返回 controlReady=false，不能通过 +latest 或列表第一项猜录音目标。停止已成功但等待超时时，保留 taskUuid 和未完成产物，后续只恢复读取，不再次 stop。
4. 权限 workflow
先区分三种身份语义：
| 用户意图 | 推荐入口 | 目标身份 |
|---|---|---|
| “我打不开，帮我申请查看/下载/编辑” | `+apply-permission --id --permission view | download |
| “把这条听记分享给张三” | `+share --id --member-uids --permission view | download |
| “撤销张三对这条听记的权限” | +unshare --id <taskUuid> --member-uids <UID> |
所有者移除指定成员权限 |
4.1 成员解析
- 用户已给稳定成员 UID：直接复用，但必须保持同一 profile/组织。
- 只有姓名、手机号或部门线索：切
dingtalk-contact/dingtalk-aisearch解析；零或多候选时停止。 - 不把姓名、手机号、userId、openId 或跨组织 UID 互相猜测转换。
4.2 批量执行
+share 的精确业务参数是 --id|--ids、--member-uids、必填的 --permission view|download|edit，以及可选的 --cover、--sub-resources OrigContent|Summary|Analysis|Note、--failure-policy stop|continue：
dws minutes +share --id <taskUuid> --member-uids <uid1,uid2> --permission view --failure-policy stop --format json
dws minutes +share --ids <uuid1,uuid2> --member-uids <uid> --permission edit --cover --sub-resources OrigContent,Summary --failure-policy continue --format json
+unshare 的精确业务参数是 --id|--ids、--member-uids 和可选的 --failure-policy stop|continue；它没有 --permission、--cover 或 --sub-resources：
dws minutes +unshare --id <taskUuid> --member-uids <uid1,uid2> --failure-policy stop --format json
dws minutes +unshare --ids <uuid1,uuid2> --member-uids <uid> --failure-policy continue --format json
--id与--ids必须且只能选一个；听记 taskUuid 和成员 UID 去重后各为1..50个。+share --permission必填、没有默认值：edit=policy 2、download=policy 3、view=policy 4。管理员0、所有者1只能走minutes permission add --policy 0|1。--failure-policy默认stop，首个成员失败后停止；显式continue才继续其他成员。任何失败都必须作为 partial/非零交付，并保留失败与未执行成员。+unshare是 write/medium、user_required；执行前明确听记、成员和撤权影响。+share、+apply-permission同样执行 Runtime 的user_requiredconfirmation。对应原子 permission 命令只保留历史兼容 Contract，不作为绕过确认的推荐路径。+apply-permission只接受单个--id和必填的--permission view|download|edit，目标固定为当前登录用户，不接受--member-uids。
4.3 验证边界
当前没有公开的 minutes permission list/get/inspect 命令。真实执行后，+share/+unshare 可输出逐成员成功、失败和未执行 ledger，但成功项只表示写接口已确认接收；即使 +unshare 执行前读取了听记基本信息，也没有读到成员的最终权限。
因此权限结果必须按 verification.mode=write_ack_only、verified=false 交付。不要把 ledger 中的 complete=true、听记基本信息、dry-run 计划或退出码解释为“已读回验证权限生效”；也不要为了验证而重放授权或撤权请求。
4.4 dry-run
这些权限 Shortcut 的 dry-run 只展示目标组合与将执行的动作，不调用远端，也不证明听记、成员或当前权限状态。真实执行后也只能声明“写调用已确认接收”，不能声明“已读回最终权限”。