dws skill | PlugMCP
Skip to content 【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。
Plug any tool into any agent. MCP servers for people who do not write servers. Gateway for volume, n8n for apps.
Product
Directory
Developers
Company
Publisher
Stars 3.0k
Agents 3
Categories 3
Download pinvou3-app/src-tauri/resources/common/bundle/dingtalk-skills/dws/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does dws live? The publisher keeps it at https://github.com/Pinvou/pinvou-agent.
Which agents can use dws? Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
SKILL.md
name dws
description 【何时用:仅当用户明确指向钉钉/DingTalk(钉钉文档、钉钉日程等)时使用;泛指做文档/表格/待办/审批默认走本地工具,不要误用钉钉】用 dws CLI 管理钉钉:AI表格/AI搜问(找人首选)/目标管理(Agoal)/组织大脑/日历/通讯录/群聊与机器人消息/待办/审批/智能合同/考勤/日志(日报周报)/DING消息/钉钉文档/云盘/Markdown文件/HTML文件/AI听记/邮箱/在线电子表格(axls)/知识库/白板/开放平台文档/个人IM与OA事件订阅。用户要求操作上述钉钉产品时使用。
cli_version >=1.0.64
metadata internal: true requires: bins: ["dws"] cliHelp: "dws --help" 钉钉全产品 Skill
通过 dws 命令管理钉钉产品能力。
⚠️ 命令与 flag 以当前 dws 二进制为准:dws <cmd> --help 是 Cobra flags 事实源,Agent 选命令/参数约束/安全确认以 leaf Schema(--compact)为准,与本文档冲突时以二者为准。
🔑 首次使用先认证:命令报 AUTH_TOKEN_EXPIRED / 未登录时,不要在会话内直接跑 dws auth login——它是阻塞式扫码设备流,会一直等待授权直至超时,用户看不到扫码链接。把命令交给用户在其终端自行执行(流程见 global-reference.md 认证章节),完成后再继续;不要因未登录直接断定技能不可用。
严格禁止 (NEVER DO)
不要使用 dws 命令以外的方式操作钉钉业务数据（禁止 curl、HTTP API、浏览器）。例外 ：① aitable 导入/导出/附件上传链路返回的预签名 uploadUrl/downloadUrl（import upload 申请的上传凭证、export data 返回的下载地址、attachment upload 返回的上传地址）允许用 curl 直传/直下（见 aitable-export-import.md 与 aitable-attachment.md ）；② 按 openapi-explorer.md 读取官方 open.dingtalk.com/llms.txt 文档并生成受限的 dws api 调用。除此之外禁止
不要编造 UUID、ID 等标识符，必须从命令返回中提取
不要猜测字段名/参数值，操作前必须先查询确认
严格要求 (MUST DO)
所有命令必须加 --format json（默认输出即 json,显式携带以防默认值变化,确保可解析）
用户明确要登录钉钉国际版、海外版或 .io 区域时，必须执行 dws auth login --intl（无头环境再加 --device），不得回退到国内 .com；--intl 只用于登录，后续业务命令按所选 profile 自动路由
危险操作必须先向用户确认，用户同意后才加 --yes 执行
直接调用 dws 批量接口（如 record update）时单次硬上限 100 条（各 record 分册同）；Agent 直连建议每批 ≤30 条以便失败重试；使用 scripts/import_records.py 批量导入时按脚本默认 50 条/批（其 DEFAULT_BATCH_SIZE=50，上限 100）
所有命令必须严格遵循 对应产品参考文档里面规定的参数格式（参数与参数值之间用空格隔开）
脚本只用于明确覆盖的复合任务 ：scripts/ 下的脚本可封装 AI 表格批量导入导出、钉盘目录树等流程；当公开
+
脚本调用约定 ：统一用 python3 调用（多数 macOS/Linux 环境没有裸 python 命令）；文档中的 scripts/... 是相对本 Skill 根目录（SKILL.md 所在目录）的路径，实际执行时应拼成完整路径（如 python3 <Skill根目录>/scripts/attendance_report_monthly.py ...），不要假设当前工作目录（CWD）已在 Skill 根目录
实时个人事件例外 ：普通 IM 消息、reaction、已读和撤回默认走 dws event +listen-im ...；OA 审批、VoIP 通话邀请、Todo、互动卡片回调、群生命周期、明确的原始 EventKey、Filter DSL、subscribe_id 或原始 envelope 使用 dws event consume ... --flatten。不要写脚本轮询消息历史、审批列表、通话记录或待办列表
Shortcut 与原子命令的使用原则 shortcut 是对常用操作的高层封装，适合优先承担用户意图；产品参考文档和本 skill 负责判断意图、风险、跨产品流程和复杂参数，CLI 帮助负责声明当前版本真正可调用的命令。
先按产品参考、意图表和 recipe 路由。用户意图可由可见 Shortcut 满足时，优先使用 dws <service> +<verb> ... --format json，不要手写等价的多步原子命令。只有脚本明确补足 Shortcut 未覆盖的复合交付物且其安全/完整性契约仍适用时才选择脚本。
公开内建 shortcut 同时进入 Runtime Schema。用 dws schema --cli-path "<service> +<verb>" --compact --format json 读取 Agent 选择、参数、跨参数约束和 risk/confirmation；只有参数映射、接口绑定或 provenance 审计才通过 --jq 精确读取 full leaf；dws shortcut list --service <service> --format json 只作为轻量批量发现入口。
真正组装参数前用叶子帮助 dws <service> +<verb> --help 核对当前 Cobra 接受的 flags。父级 dws <service> --help 只能发现子命令，不能替代叶子参数帮助。
shortcut catalog 中 confirmation=user_required 时，必须先获得用户确认，确认后才加 --yes；not_required 不额外确认。
如果 shortcut 不在 help / list 中，改用产品参考里的原子命令、脚本或标准流程；不要猜测未展示的 + 命令。
shortcut 失败时按“错误处理”流程先加 --verbose 复查；若仍失败，应记录具体输入、输出、trace / endpoint / tool 信息。
Shortcut 总览 下面只统计当前公开 catalog 中的 shortcut，不展开完整明细。已知意图先按产品 Skill、意图表或任务 reference 选唯一命令；参数/约束/安全不明时读一次 leaf 窄 Schema。Schema 不可用时才读一次已知 leaf Help；unknown flag 用同 leaf Help 修正一次；unknown command 不查 Help，先用错误的明确 suggestion，否则用已加载 Skill/reference 的明确兼容入口，仍无则报告漂移，不枚举全 Catalog。仅当现有路由和 reference 都无法定位低频能力时，才用 dws shortcut list --service <service> --format json 做最后回退；不要为已知意图加载完整产品 Catalog 或 root/parent Help。
多组织 / 多账号
dws profile list --format json 默认返回全部账号。自动化只使用每项稳定的 profile=corpId:userId；status/expiresAt/refreshExpAt 来自真实身份 Token，列表不触发刷新。输入支持 corpId:userId、corpId:userName、corpName:userId、corpName:userName，也兼容单独的 corpId、唯一 corpName 和本地 profile 名。名称只用于输入；重名时必须按报错候选改用 corpId:userId。
只传组织时使用该组织明确记录的 isOrgCurrent=true 账号。多账号组织没有默认账号时必须让用户指定账号；禁止选择第一项、最近登录或最近使用账号。
不传 --profile 使用全局 isCurrent=true 账号。primaryProfile/isPrimary 仅兼容输出，不参与选择；previousProfile 只用于 profile switch -。
跨组织读 / 搜：按 corpId 去重；每个组织使用唯一 isOrgCurrent=true 的 profile。组织存在多个账号且没有默认账号时先询问用户。写 / 发 / 删 / 撤回及持久切换前先确认目标组织和账号。
产品总览
意图判断决策树 用户提到"AI应用/创建应用/生成系统/做工具/管理后台/低代码/宜搭" → 产品参考以 dev.md 为准（勿猜 aiapp 等未在 dev.md 列出的命令，命令以 dws dev --help 实测为准）；应用创建/机器人建号与建联流程见该文「典型工作流」
用户提到"目标管理/Agoal/战略解码/经营合约或字段配置/计分卡/目标规则周期/个人目标/目标模板/周月报规则提交统计/按时/迟交/未提交/跟催" → agoal；只填写、提交或查询日报周报月报正文时才走 report
用户提到"法务/智能合同/合同台账/合同归档/合同项目/相对方/合同账款/按听记起草合同" → contract（合同审批实例的查询或处理走 oa；合同文件存储操作走 drive）
用户提到"找人/搜人/谁负责 XX/某事项的负责人/某项目的人/团队成员/上级/下级/按工号找人/按手机号找人" → aisearch（通用语义找人；若明确涉及人才池/绩效/职业历程/结构化高级条件，去 hrbrain）
用户提到"表格/多维表/AI表格/记录/数据/视图/图表/仪表盘/SQL/PostgreSQL/SELECT/JOIN/跨表关联查询" → aitable
用户提到"考勤/打卡/排班" → attendance
用户提到"日程/日历/会议室/约会/时间建议" → calendar
用户提到"群聊/建群/群成员/群管理/发消息/发图片消息/发文件消息/发 Markdown 消息/截图发钉钉/转发消息/引用回复/@我/特别关注消息/机器人发消息/Webhook/机器人群发/机器人单聊/通知" → chat
用户提到"通讯录/同事/部门/组织架构/子部门/部门多少人/离职员工/离职名单/离职花名册/花名册/基础员工档案(学历/家庭/银行卡/紧急联系人/合同)/角色/主管角色/管理员角色/财务/HR/特别关注/星标联系人/创建企业/企业账号/邀请员工/新员工入职" → contact（不含职业历程/绩效/人才池；那些去 hrbrain）
用户提到"开发/API/调用错误 文档" → devdoc
用户提到"未封装 OpenAPI/llms.txt/dws api/Raw API/API 逃生舱" → dws api（先查现有产品命令，再读官方 llms.txt）
用户提到"DING/紧急消息/电话提醒" → ding
用户提到"DingTalk Tag/DEAP 数字员工/创建发布数字员工/修改数字员工人设/响应模式/为 A2A 等场景安全登录数字员工 DWS/给数字员工挂 Skill 或 MCP/数字员工运行状态或 trace/落盘本地 Profile/接入 DSH" → dingtalk-tag，先读 dingtalk-tag-index.md
用户提到"钉钉文档/云文档/知识库/读写文档/块级编辑/文档评论/文档复制移动" → doc
用户提到"云盘/文件存储/文件上传下载/文件夹/互联网公开/分享链接密码/公开有效期" → drive
用户提到"人才池/储备干部池/员工档案元数据或批量模块数据/职业历程/绩效记录/员工标签/组织大脑/结构化人才搜索(高级条件表达式)" → hrbrain（区别于 aisearch 的通用语义找人与 contact 的基础通讯录档案）
用户提到"原生 HTML 文件/.html 文件/新建 HTML 页面/创建 HTML 文件/读取 HTML 原文/覆盖 HTML/局部替换 HTML" → html
用户提到"原生 Markdown 文件/.md 文件/读取 Markdown 原文/覆盖 Markdown/局部替换 Markdown/Markdown 评论" → markdown
用户提到"听记/AI听记/会议纪要/转写/摘要/思维导图/发言人/热词" → minutes
用户提到"邮箱/邮件/发邮件/收邮件/搜邮件/查邮件/邮件草稿/转发邮件/回复邮件/邮件附件/抄送" → mail
用户提到"审批/请假/报销/出差/加班/同意/拒绝/撤销审批" → oa
用户提到"PAT 授权/行为权限/scope 授权/批量授权/一次性授权/会话授权/永久授权/授权浏览器策略" → pat
用户提到"日志/日报/周报/日志统计/写日报/提交周报/发日志/填日志" → report
用户提到"在线电子表格/钉钉表格/axls/工作表/单元格读写/合并单元格/筛选视图/导出 xlsx" → sheet
用户提到"待办/TODO/任务提醒/循环待办" → todo
用户提到"创建知识库/知识库列表/搜索知识库空间/wiki/团队空间/知识库成员管理/我的文档个人空间" → wiki
用户提到"白板文件/独立白板/保存到白板/画布/OpenNodes/白板节点/连接线/整页重建白板" → whiteboard。用户要在文档中插入、定位或删除白板卡片 → doc whiteboard；只有已有承载文档 nodeId 和 partId 的内嵌白板图形内容读写才走 whiteboard。内嵌目标身份缺失时停止并补齐，禁止转成独立白板
用户提到"监听有人@我/监听单聊或群消息/监听所有单聊或群消息/监听某人发送的消息/监听消息已读/监听消息撤回/监听消息贴表情或表情回应/订阅个人 IM 事件/实时接收钉钉事件/监听并自动回复消息/驱动 Agent 处理消息" → event +listen-im；群成员加入/退出、群改名/解散或明确原始 EventKey/Filter DSL → event consume
用户提到"监听待我审批的任务/监听审批任务创建、完成或转交/监听审批单发起或终止/监听我发起的审批完成/监听审批实例完成/订阅 OA 事件/event consume user_oa_approval_" → event consume
用户提到"收到语音通话邀请时通知我/监听 VoIP 来电/订阅 user_voip_call_receive_invite" → event consume
用户提到"监听待办创建/更新/删除/监听指派给我的待办/订阅 Todo 事件/event consume user_todo_task_ " → event consume，按角色使用 --role-types
用户提到"互动卡片回调/监听卡片操作/订阅 user_card_action_triggered" → event consume user_card_action_triggered --flatten -f ndjson
普通消息、reaction、已读、撤回监听优先由一个 dws event +listen-im 进程表达目标；不同用户、不同群或不同过滤条件拆成独立进程。只有高级事件控制才生成 dws event consume <event_key> [event_key...] --flatten。
关键区分: aitable(数据表格) vs todo(待办任务)
关键区分: report(钉钉日志/日报周报) vs todo(待办任务)
关键区分: chat send-by-bot(机器人身份发消息) vs send-by-webhook(自定义机器人Webhook告警)
关键区分: doc(在线富文本文档/adoc) vs markdown(原生 .md 纯文本文件) vs html(原生 .html 文件读写) vs drive(通用文件存储与传输)
关键区分: contact(基础通讯录档案：学历/家庭/银行卡/紧急联系人/合同/部门角色) vs aisearch person(通用语义找人：谁负责/上级/下级/多维度模糊搜索) vs hrbrain(人才池/员工档案专项模块数据/职业历程/绩效/结构化高级人才搜索)
关键区分: oa tasks(审批 taskId，审批/拒绝用) vs oa list-pending(收件箱 processInstanceId，查看用)
关键区分: oa(查询或操作审批) vs event user_oa_approval_(当前用户审批事件长连接监听)
关键区分: todo(查询或操作待办) vs event user_todo_task_ (当前用户待办事件长连接监听)
危险操作确认 以下操作为不可逆或高影响操作，执行前必须先向用户展示操作摘要（操作类型 + 目标对象 + 影响范围）并获得明确同意 ，同意后才加 --yes 执行。
确认门禁的识别与重试协议 非交互环境（Agent/CI，stdin 非 TTY）下，写命令不带 --yes 时 CLI 不打印交互提示语 ，直接失败并输出结构化错误。识别方式：
--format json 输出（或 stderr）中 error.reason == "confirmation_required"，错误信息含「当前环境无法交互确认」 遇到 confirmation_required 时按以下协议处理：
不要当普通错误放弃 ：把命令、风险等级（write / high-risk-write）和关键参数展示给用户，明确告知这是写/高风险操作用户显式同意 → 在原始命令 末尾追加 --yes 重试（不改动任何业务参数）
用户拒绝 → 终止，不得改写参数绕过门禁
想先让用户 review 具体请求：加 --dry-run 重试——它不触发确认门禁 ，会输出完整调用预览（invocation.params），用户确认预览后再换 --yes 执行
看到 confirmation_required 就未经用户同意自动追加 --yes 静默重试（等于禁用门禁）
把 confirmation_required 当网络/权限错误处理或重试
用 echo yes | dws ... 等管道方式喂答案代替 --yes（管道答案技术上会被接受，但违背了让用户显式知悉的设计意图）
核心流程
URL 预检 ：输入含 alidocs.dingtalk.com URL 时，该域名下存在多种路径格式（/i/nodes/...、/i/p/...、/spreadsheetv2/...、/document/edit|preview?dentryKey=... 等），每种的处理流程不同。必须先读取 url-patterns.md 中的「alidocs URL 分流决策」 ，按其中规则识别 URL 类型后再选择对应产品。含 shanji.dingtalk.com URL 时直接路由到 minutes。URL 已识别后直接进入对应产品流程，无需后续步骤。意图分类：判断用户指令的核心动词/动作属于哪一类。
歧义追问：指令模糊或包含多个产品的关键字时，严禁猜测，主动向用户追问澄清意图。
选定产品：参考产品总览和意图判断决策树选定产品，按任务最小化读取对应产品参考文件后执行（已知高频意图直接用已给出的唯一命令，不预加载完整产品参考）。
命令发现（Schema 渐进查询 + --help 互为补充）
Schema 渐进查询（Agent 选命令首选） dws schema 内嵌当前二进制公开命令面的结构化契约。Agent 选择命令、读取参数映射/约束和安全语义时必须优先渐进查询 leaf Schema ；真正组装执行参数前，用 --help 确认当前 Cobra 接受的 flags：
本节同时适用于基础/原子命令与公开内建 + shortcut。用户自定义或未公开 shortcut 不进入发布 Schema；其是否可执行仍以当前 Cobra help 为准。
已知命令路径例外 ：当本 Skill、产品意图表或任务 reference 已经给出精确 CLI path 时，不要再查询产品级/分组级 Schema，也不要调用完整 Shortcut Catalog；可直接执行。只有参数、约束或安全语义不确定时才读取该命令的 leaf Schema，只有当前 Cobra flags 不确定时才补读 leaf Help。
稳定 command identity、主 CLI path 和 alias 由 leaf ContractFinal.Identity 与真实 Cobra tree 精确绑定。Agent 不应读取 Catalog 文件、native annotation 或其他生成 JSON 来重新推断命令；所有运行时查询都以当前二进制交付的 Schema 投影为准。
# 第 1 层：产品概览（~4.5KB，列出全部产品 + 工具数 + 用途摘要）
dws schema
# 第 2 层：产品级（列出该产品下全部工具的 cli_path + description + effect/risk）
dws schema calendar --compact
# 第 3 层：分组级（按命令分组列出工具摘要）
dws schema "calendar event" --compact
# 第 4 层：Agent leaf（参数契约：type/required/description/constraints/examples）
dws schema "calendar event create" --compact
# --all：导出所有工具的完整 leaf Schema，仅用于 CI / 审计 / 参数 baseline
dws schema --all --format json
--all 使用边界（强制）--all 会返回每个工具的完整参数、约束和安全语义，输出体积很大。仅在用户明确要求全量导出，或执行 CI、Catalog 审计、参数防丢 baseline 时使用。普通业务任务严禁使用 --all 做命令发现，也不要把全量结果直接注入 Agent 上下文；必须按“产品概览 → 产品/分组 → leaf”渐进查询。完整兼容性 baseline 必须使用未裁剪的 schema --all；schema --all --compact 会移除 provenance 和接口映射字段，不得作为完整 baseline。
同一个工具省略 --compact 的 full leaf 与 --all 条目是同一份 ToolSpec 契约；compact leaf 只做展示投影，不重新解析语义。Alias 查询不得根据 alias 重写或补猜参数。若同一视图观察到内容差异，应作为契约漂移报告，而不是选择其中一份继续执行。
--compact Agent 模式cli_path、canonical_path、description、effect、risk、confirmation、interface_mode、availability、interface_reason、parameters（含 type/required/description/default/enum）、constraints、examples、use_when、avoid_when；新增 full/audit 字段不会自动泄漏进 Agent 上下文。它有意不返回 interface_ref、参数 property/interface_type 和 provenance；检查这些映射事实时，用 full leaf 配合 --jq 精确投影。
--compact 是 Schema 展示能力。当前版本支持；若兼容旧二进制时收到 unknown_flag: --compact，仅去掉 --compact 重跑同一个 Schema 查询。不要因此判定 leaf 不存在，也不要改用 Schema 查询业务数据。
Schema 字段速查 // leaf 级输出（dws schema "calendar event create" --compact）
{
"cli_path": "calendar event create",
"canonical_path": "calendar.create_calendar_event",
"description": "创建新的日程...",
"effect": "write", // read | write | destructive
"risk": "medium", // low | medium | high
"confirmation": "not_required", // not_required | user_required
"interface_mode": "mcp", // mcp | local | composite
"availability": "available", // available | unavailable
"interface_reason": "",
"parameters": {
"title": { "type": "string", "required": true, "description": "..." },
"start": { "type": "string", "required": true, "format": "date-time" }
// ...
},
"constraints": { "require_together": [["recurrence-type", "recurrence-interval", "recurrence-range-type"]] },
"examples": ["dws calendar event create --title ..."]
}
confirmation=user_required → 必须先向用户确认再加 --yes；不要根据 effect 或 risk 的值自行重写最终 confirmation winneravailability=unavailable → 不执行该工具；向用户说明 interface_reason。interface_mode 只描述实现机制，不能覆盖 availabilityparameters.<flag>.required=true → Agent 应提供该参数；Cobra 是否硬拒绝以 --help/实际命令契约为准parameters.<flag>.cli_required=true → Cobra 将该 flag 标记为硬必填constraints.require_together → 列出的 flag 必须同时提供
Schema、Help 与业务数据的边界 Schema 与 Help 冲突是契约漂移 ，不得静默猜测或把两边字段随意拼接：
执行参数只使用 Cobra/Help 接受的 flags，并把漂移报告出来。
安全语义冲突时不能选择更宽松行为；先采用更保守的确认方式，无法确认安全执行方式时停止并报告。
leaf Schema 是已经按来源 precedence 解析后的契约；不要根据值的“严格程度”自行改写 winner。只有发现它与 Help/实际执行契约冲突时，才进入上述安全降级。
dws schema 只查询命令契约，不搜索钉钉文档或业务数据。完成命令发现后，必须继续执行真实命令，例如 dws doc read、dws drive search；不要把 Schema 查询结果当成业务查询结果。
Helper-only 与本地 Cobra 命令 dev.* 包含 helper-only 执行面，其中远端 helper 未进入 pinned metadata 时标记为 composite，不能伪装成 local。event list / event schema 读取内置目录和 payload 定义，属于 local；event consume / event status / event stop 同时编排远端个人订阅控制面与本地 bus/consume，属于 composite。实现来源不同，不改变统一查询边界：进入全局 dws schema 的命令须由 leaf ContractFinal.Identity 声明收集，并由同一 ToolSpec 投影到 leaf、产品/分组、--all 与 Catalog。不得把 Cobra 临时合成结果作为第二条 Schema 数据路径。
事件需要区分两种 Schema：dws event schema <event_key> --flatten 查询 Agent 要消费的顶层业务字段；dws schema "event consume" --compact 查询 CLI 命令参数。前者是真实业务命令，后者只读取最终内嵌 SchemaRegistry；不能相互替代。
source 表示最终命令 identity 的来源，不表示运行时 backing；helper/local/MCP 实现机制读取 interface_mode、availability 和 provenance，不要假定 dev.* 必然是 source=mcp:<server>，也不要假定本地命令必然是 source=cobra。
错误处理
先读取 JSON 错误的 retryable、retry_after_seconds、next_retry_at、hint 和 actions；只有明确 retryable=true 时才按服务端节奏做一次有界重试。缺少重试语义时加 --verbose 收集诊断后停止
仍然失败，报告完整错误信息给用户，禁止自行尝试替代方案
认证失败时，参考 global-reference.md 中的认证章节处理
各产品高频错误及排查流程见 error-codes.md
遇到 capability-limits.md 中列出的「已知不支持操作」时，直接告知用户不支持并建议在钉钉客户端操作 ，不要重试或变通
详细参考 (按需读取) Agent 使用 OpenNodes 带内容创建白板时，必须先执行 whiteboard render，展示 SVG 和渲染提示后停止，等待用户明确确认当前版本才能创建；修改后重新渲染和确认。不得跳过预览直接创建，最初的创建请求及创建后回读不能替代预览确认。详见白板入口的创建流程；空白创建、直接套用模板和已有白板更新不由此规则扩展。
Agent 更新已有白板内容（追加、修改、删除、清空）必须先执行 whiteboard +diff，展示差异和风险后停止，等待用户明确确认当前差异，再用同一 sourceDigest 执行 +update；diff 失败或有 blocker 时不得写入。不得换原子 update 绕过，render、dry-run 和写后回读不能替代 diff。详见白板入口的更新流程。更新只设一个用户确认点：先完成所需的 render 和必需的 +diff，再把视觉预览（如有）、差异与覆盖影响一起展示并一次确认；不要在 render 后先索要确认、获准后才补做 diff 再次询问。同一目标、revision、source 和模式已获确认后，直接提交；只有这些内容变化或出现未披露的实质风险才重新确认。