dingtalk-prd-publisher

Use when publishing a local PRD Markdown file to DingTalk Docs or Drive with version-history preflight and read-back, or when validating an approved Product Delivery Package through its fail-closed dr

SKILL.md

GitHub

钉钉 PRD 发布器(dingtalk-prd-publisher)

中文速查

  • 中文名:钉钉 PRD 发布器 / PRD 证据截图发布
  • 分类:产品交付 / PRD 发布
  • 你可以这样叫我:把这个 PRD 发到钉钉文档、PRD 里有 Look up 地址,截图后插进去再上传钉钉、把本地 PRD 发布到指定钉钉目录
  • 适合:本地 Markdown PRD、关联 mock / Look up / HTML 预览、截图证据、默认钉钉 PRD 锚点目录或用户指定目录发布。
  • 不适合:从零写 PRD、评审 PRD 内容、创建钉钉表格/AI 表格、删除或覆盖已有钉钉文档。

Overview

这个 Skill 把“本地 PRD → 版本记录校验 → 发布版清理 → 关联页面截图 → 插图后的 PRD copy → 最新 HTML 前置附件 → 钉钉文档/钉盘发布 → 版本记录与正文回读 → 浏览器可见性验证”固化成可重复流程。默认保护源文件:不覆盖原 PRD。用户没有指定钉钉目标时,默认在“智能体需求文档”锚点下创建一篇需求专属二级文档并写入 PRD,避免每次重复粘贴目录地址。

PRD 版本由 prd-architect 维护。本 Skill 只校验和回读,不自行创建、递增或改写版本号;版本缺失或修改记录不具体时,在首个 DingTalk 调用前失败并退回 PRD 修订。

对 Product Delivery Package,必须使用显式 --manifest mode。它只消费 product-delivery-manifest.yaml 中通过确定性 validator 校验的 content / HTML / screenshot allowlist 和目标,不执行 sibling discovery,也不接受 CLI 改写 title、target 或 artifact。当前 Agent Runtime 只允许 Package 完整 dry-run;非 dry-run 必须 fail closed 为 authorization_required。Legacy direct mode 保持兼容,但不能替代 Package approval、payload fingerprint 或状态记录。

真实钉钉操作必须加载并遵守 dws Skill;浏览器截图问题需要加载 playwright Skill排查。DingTalk 写入以本地 dws --help/schema 为准,不猜命令或 flag。

Required Inputs

优先从用户消息或本地文件发现,不足时最多问 3 个问题:

  • PRD Markdown 路径。
  • PRD 顶部版本记录:标题后的首个 H2 为 版本记录,包含 版本 / 日期 / 修改内容,最新版本置顶,最旧记录为 V1.0 / 首次创建。已有 PRD 的内容迭代应先由 prd-architect 增加版本记录;单纯发布重试不增加版本。
  • Product Delivery Package:Manifest 路径、prd-architect 的 canonical validator 路径,以及 Human approval 绑定的 publish_payload_fingerprint。这三项均不可由 Publisher 自行推断。
  • 钉钉目标:默认可省略;省略时使用默认父节点 https://alidocs.dingtalk.com/i/nodes/MNDoBb60VLrdedxLSrZmae9N8lemrZQ3?utm_scene=team_space(智能体需求文档),并在其下直接创建需求专属二级文档。需要覆盖时传 --parent <alidocs node URL/nodeId>、--folder <folder URL/nodeId> 或 --workspace <workspaceId>。
  • 发布方式:默认 doc 在线文档;需要保留原文件时用 file 上传。
  • 源文件策略:默认生成 enriched copy;只有用户明确要求才覆盖源 PRD。
  • HTML 策略:在线文档模式默认选择 enriched PRD 同目录修改时间最新的 .html / .htm,作为正文第一个附件块;用 --html <file> 明确指定,用 --no-html 关闭。显式路径不存在时必须在创建钉钉文档前失败。
  • 截图策略:默认用 Playwright 抓真实截图;网络或登录态受限时先报告 blocker,不伪造截图。
  • 发布版清理策略:默认从钉钉正文移除 待确认事项、关联产物、文档信息里的 关联 mock 本地路径、失败图和本地-only 链接;只有用户明确要求保留草稿信息时才关闭。

Workflow

Product Delivery Package 先走独立分支:

<skill>/scripts/publish-prd \
  --manifest "<PACKAGE>/product-delivery-manifest.yaml" \
  --validator "<prd-architect>/scripts/validate_product_delivery_manifest.py" \
  --expected-payload-fingerprint "<HUMAN_APPROVED_SHA256>" \
  --actor-identity "<PUBLISHER_RUN_ID>" \
  --dry-run
  • Dry-run 必须完成 Manifest、Package verdict、publish approval、payload fingerprint、artifact 路径/hash 和 allowlist 校验,且 dws 调用数为 0。
  • 当前 Agent Runtime 没有 Agent 无法伪造的一次性 host approval capability,因此去掉 --dry-run 必须返回 authorization_required,且不得调用 dws 或改写 Manifest。
  • CLI 参数、环境变量、普通 receipt/nonce 文件、Manifest 中的 Human approval 和调用方提供的 previous Manifest 都不是可信 host capability。
  • 不得回退到 Legacy direct mode 绕过 Package 边界。Legacy real publish 只用于用户明确选择的非 Package 直发流程。

以下步骤用于 Legacy direct mode 和 Package 上游的 enriched copy 准备:

  1. Validate PRD version history.
    • 使用 prd-architect/scripts/check_prd_version_history.py 校验版本表存在、位于正文顶部、版本与日期格式有效、最新记录置顶、V1.0 来源存在且修改内容具体。
    • 校验必须发生在 dws auth status 和任何远端调用之前;失败时不创建文档、不上传附件、不改 Manifest。
    • Publisher 不根据文件更新时间猜测新版本,也不把“更新 PRD”补成修改说明。
  2. Inspect source PRD.
    • 确认文件存在、是 Markdown、源 PRD 不会被覆盖。
    • 识别 Look up、lookup、mock、原型、预览、关联产物、.html、URL 或本地 HTML 路径。
    • 相对路径按 PRD 所在目录解析。
  3. Dry-run lookup discovery.
python3 <skill>/scripts/enrich_prd_with_screenshots.py "<PRD.md>" --dry-run --json
  1. Capture screenshots and create enriched copy.
python3 <skill>/scripts/enrich_prd_with_screenshots.py "<PRD.md>" --json

默认输出:

  • <PRD stem>.dingtalk.enriched.md
  • <PRD stem>.dingtalk-assets/*.png
  • enriched copy 默认是钉钉发布版:移除 待确认事项、关联产物 和文档信息里的本地 mock 行;源 PRD 不覆盖。
  1. Review placement.
    • 同一链接多处出现时只截图一次。
    • 优先把截图插到对应功能模块、页面状态或交互章节;不要优先放到 关联产物、文档信息表或本地 mock 索引。
    • 图片块带 <!-- dingtalk-prd-screenshot: ... --> marker,方便发布后定位。
  2. Pre-publish lint.
    • 版本记录表必须保留在 enriched copy 标题后的首个 H2;清理本地链接时不得删除、移动或重写版本历史。
    • 发布前检查 enriched copy 不应残留 待确认事项、关联产物、关联 mock、本地 .html、本地 .png、dingtalk-assets、file://、localhost 等正文入口。HTML 通过附件块发布,不依赖正文里的本地路径。
    • 如果这些内容是用户明确要求保留的草稿材料,先说明会影响钉钉正文阅读,再继续。
  3. Publish with dws wrapper.

Default path when the user does not provide a DingTalk target:

<skill>/scripts/publish-prd "<ENRICHED.md>" --name "<PRD title>" --read-back

This resolves the default parent anchor. For the default ALIDOC/adoc anchor, it creates the DingTalk Doc directly as a second-level child; ordinary folder targets keep the optional per-run-folder behavior. In online-doc mode, the wrapper then inserts the newest sibling HTML at document index 0 before read-back.

显式指定原型或关闭自动附件:

<skill>/scripts/publish-prd "<ENRICHED.md>" --html "<APPROVED.html>" --name "<PRD title>" --read-back
<skill>/scripts/publish-prd "<ENRICHED.md>" --no-html --name "<PRD title>" --read-back
<skill>/scripts/publish-prd "<ENRICHED.md>" --folder "<DINGTALK_FOLDER_URL>" --name "<PRD title>" --read-back

或上传源文件:

<skill>/scripts/publish-prd "<ENRICHED.md>" --mode file --folder "<DINGTALK_FOLDER_URL>"
  1. Verify DingTalk result.
    • publish-prd --read-back 后检查关键标题、版本表、最新版本行、截图 marker 或图片附件是否存在;线上最新版本行必须与本地源 PRD 一致。
    • 如果选中了 HTML,检查 dws doc media insert 返回 success=true 且 index=0;再用 block list 和浏览器确认 HTML 附件确实位于正文第一个块,可打开或下载。
    • 如果本地 Markdown 图片没有在钉钉正文渲染,不要报告完成;改走 dws doc media insert,用 dws doc block list --content-format jsonml 找到 marker/caption 附近 block,再把截图文件插到对应 block 后。
    • 所有 PRD 发布到钉钉后,都必须打开 docUrl 做浏览器可见性验证;检查首屏、关键模块图片、底部是否无不需要章节、页内搜索敏感残留词是否为 0。
    • 最终返回 docUrl / nodeId、enriched PRD 路径、截图路径和验证结果。

DingTalk Rules

  • Package mode 只接受 canonical validator 输出的 allowlist;禁止自动发现最新 sibling HTML,禁止上传未列入 Manifest 的文件。
  • Package mode 的 file 只上传正文文件,因此 HTML / screenshot allowlist 必须为空;需要媒体交付时必须使用 doc,不能批准后静默漏发。
  • Package mode 在任何 dws 调用前校验独立 Reviewer 的 ready verdict、content / artifacts / publish 三项检查、Human approval 和精确 payload fingerprint;失败时不得改写 Manifest。
  • 当前 Agent Runtime 的 Package mode 即使通过上述 preflight,也只能完成 dry-run;真实写入必须返回 authorization_required,调用数和 Manifest 变更数都为 0。
  • 只有未来可信宿主注入 Agent 无法生成、一次性且绑定 payload 的 approval capability 后,才可启用 validator 已定义的 publish event、read-back 和恢复状态机;本版本不实现该宿主能力。
  • 在登录检查前先运行版本历史校验;缺失版本表、版本顺序错误或空泛修改说明必须保持 dws 调用数为 0。
  • 写钉钉前先确认 dws auth status --format json 已登录。
  • 命令输出必须用 --format json;不确定命令时先跑 dws <cmd> --help。
  • doc create 用于在线文档;drive upload 用于上传文件。
  • 在线文档默认自动附带同目录最新 HTML;选择顺序是 --html 显式文件优先,其次同目录修改时间最新的 .html / .htm。不要递归扫描上级目录或整个项目,避免上传无关原型。
  • HTML 必须在 doc create 成功后用 dws doc media insert --index 0 插入,并在普通正文 read-back 前完成。--dry-run 只报告选中文件,不上传;--mode file 不存在正文块,不自动附加 HTML。
  • 默认父节点是 https://alidocs.dingtalk.com/i/nodes/MNDoBb60VLrdedxLSrZmae9N8lemrZQ3?utm_scene=team_space(智能体需求文档)。先用 dws doc info --node <url> --format json 探测;如果它是可挂子文档的 ALIDOC/adoc 节点,直接使用返回的 nodeId 作为 doc create --folder,创建需求专属二级文档;不要尝试在该节点下创建文件夹。普通文档文件夹仍按原有规则处理。
  • 默认 ALIDOC/adoc 父节点下直接创建一篇二级 PRD 文档,不额外创建文件夹。普通目录目标需要隔离每次发布时,运行文件夹命名为 <PRD title> <YYYYMMDD-HHMM>;用户给 --folder 时默认直接发布到该目录,明确要求再建子目录时加 --create-run-folder。
  • 用户自然语言给一个钉钉链接并说“建到下面 / 放到下面 / 创建到这个目录下”时,按 --parent <url> 处理:ALIDOC/adoc 锚点下直接创建二级文档,普通目录按运行文件夹规则处理;只有用户明确说“直接放到这个目录”时才按 --folder <url> 直接发布。
  • 可用 DINGTALK_PRD_DEFAULT_PARENT 临时覆盖默认父节点,用 --run-folder-name 固定本次发布文件夹名,用 --no-create-run-folder 禁止自动建目录。
  • --folder 只传文档文件夹 nodeId / alidocs 文件夹 URL;不要传纯数字 dentryId、drive parent-id 或 spaceId。
  • 大内容或真实发布后必须回读校验。success=true 不等于内容完整。
  • 所有 PRD 发布后必须浏览器打开验证可见性;dws read-back 只能证明服务端内容存在,不能替代真实页面图片和排版检查。
  • 没有明确目标目录时,不再默认发到根目录;使用默认父节点创建需求专属二级文档。若用户要求禁用默认父节点且又没有目标,必须先 --dry-run 并追问。
  • 删除、覆盖已有文档、改权限等不属于本 Skill 默认范围;需要另行确认并切换到对应 dws 文档流程。

Resource Guide

  • scripts/enrich_prd_with_screenshots.py:发现 PRD lookup/mock/HTML 链接,Playwright 截图,默认清理本地-only 发布污染,生成 enriched Markdown copy。
  • scripts/publish-prd:封装 dws doc create / dws drive upload;Legacy direct mode 支持真实直发和 sibling HTML,显式 Package mode 在当前 Agent Runtime 只做 allowlist dry-run,非 dry-run fail closed。
  • skills/prd-architect/scripts/check_prd_version_history.py:版本历史唯一校验器;Publisher 只消费其结果,不维护第二套版本生成逻辑。可用 PRD_VERSION_HISTORY_VALIDATOR 指向等价的已验证路径。
  • scripts/test_enrich_prd_with_screenshots.py:本地回归测试,覆盖重复 mock 链接去重、语义章节优先插图和发布版清理。
  • scripts/test_publish_prd.py:本地回归测试,覆盖默认 ALIDOC/adoc 父节点下直接创建二级文档,以及普通 --folder 的直接发布和可选子目录行为。
  • references/prd-image-placement-rules.md:截图识别、去重、插入位置和 marker 规则。
  • references/dingtalk-publish-workflow.md:钉钉发布、图片正文插入和验证流程。
  • references/provenance.md:原型脚本来源、创建记录和维护边界。

Output Contract

完成后输出:

  • Source PRD:原始文件路径。
  • Enriched PRD:生成的 enriched copy 路径。
  • Screenshots:每张截图对应的源链接、截图文件、插入章节。
  • HTML attachment:选中的 HTML 路径、选择方式(显式 / 最新同目录)、附件文件名、插入索引与验证结果;没有候选或主动关闭时明确说明。
  • DingTalk publish:目标 folder/workspace、创建方式、nodeId / docUrl。
  • PRD version:本地最新版本、版本表预检结果,以及线上回读的最新版本是否一致。
  • Verification:dry-run / screenshot / dws read-back / media insert / browser visibility 结果。
  • Package mode:Manifest 路径、input / payload fingerprint、三项 Package verdict、dry-run 结果;请求真实写入时返回 authorization_required,不生成 attempt 或远端状态。
  • Remaining gaps:登录态、图片未渲染、目标目录不明确或权限失败等。

Definition Of Done

  • 已发现 PRD 内所有候选 Look up/mock/HTML/URL 目标,或明确说明未发现。
  • 发布前版本记录通过校验;失败路径发生在首个 DingTalk 调用前,Publisher 没有自行补版本。
  • 已生成 enriched copy;源 PRD 未被静默覆盖。
  • 在线文档模式已显式选择 HTML、自动选择最新同目录 HTML,或确认没有候选 / 用户已关闭;选中时附件位于正文第一个块。
  • 截图文件存在且与目标链接一一对应;失败时报告具体 URL 和错误。
  • 真实发布前目标 folder/workspace 明确,或用户确认默认位置。
  • 未指定目标时已使用默认父节点创建需求专属二级文档,或明确说明该步骤因权限/类型受阻。
  • 发布后已 read-back;关键标题和截图/附件存在性已验证。
  • 在线文档回读已确认版本表存在,且最新版本、日期和修改内容与本地源 PRD 一致。
  • 如果钉钉正文图片未渲染,已用 doc media insert 补齐或把该问题列为未完成 blocker。
  • 已用浏览器打开钉钉 docUrl 做可见性验证;确认关键模块图片可见、没有失败图、底部没有 待确认事项 / 关联产物 / 本地 mock 链接等不应发布内容。若登录态或权限阻止浏览器验证,必须作为未完成 blocker 报告。
  • Package mode dry-run 已由 canonical validator 确认 current verdict、Human approval、payload fingerprint、allowlist 路径/hash,且 dws 调用数和 Manifest 变更数均为 0。
  • Package mode 非 dry-run 在首个 dws 调用和 Manifest 写入前返回 authorization_required;没有把 CLI/env/receipt/Manifest 自声明当作可信宿主授权,也没有回退到 Legacy direct mode。

Evaluation

Smoke prompts:

  • 把 /path/PRD.md 发布到这个钉钉目录,里面的 mock 页面先截图插进去。
  • 这个 PRD 里有 Look up 地址,打开截图,放回对应章节,然后发钉钉文档。
  • 先 dry-run 看看会抓哪些截图,不要发布。
  • 把这个 PRD 发到默认钉钉目录,每次自动新建一个文件夹。
  • 把这个 PRD 发到钉钉,上传后打开浏览器检查图片和底部模块。
  • 把这个已有 V1.2 版本记录的 PRD 更新到钉钉,确认线上最新版本行与本地一致。

Non-trigger prompts:

  • 帮我写一个 PRD。(用 PRD 起草 Skill)
  • 帮我评审这个 PRD。(用 PRD 评审 Skill)
  • 上传一个普通 PDF 到钉盘。(直接用 dws drive)

Regression checks:

  • 缺失版本记录、版本不按最新置顶、没有 V1.0 / 首次创建 或修改内容只有“更新 PRD”时,必须在首个 dws 调用前失败。
  • 发布回读必须比对本地与线上最新版本行;只存在 版本记录 标题但最新版本内容不一致不能报告完成。
  • 发布重试、媒体重试和 read-back 重试不创建新版本行。
  • EVAL-B2-05:失效 approval 或 payload fingerprint 必须使 dws 调用数为 0,Manifest 不变。
  • EVAL-B2-06:通过 Package preflight 后尝试真实写入仍返回 authorization_required,dws 调用数为 0,Manifest 不变。
  • EVAL-B2-07:Package dry-run 完整校验 verdict、approval、payload、路径/hash 和 allowlist,dws 调用数为 0,Manifest 不变。
  • EVAL-B2-08:路径 traversal 或 CLI target override 在任何副作用前失败,且不改 review / approval 分区。
  • Package file mode 带非空 HTML / screenshot allowlist 时必须在首个 dws 调用前失败。
  • 同一 mock 链接同时出现在文档信息表、功能模块和“关联产物”时,只截图一次,并优先插到功能模块。
  • enriched copy 默认去掉 待确认事项、关联产物 和文档信息表里的本地 关联 mock 行。
  • 相对 HTML 路径必须按 PRD 目录解析,而不是当前 shell 目录。
  • --dry-run 不创建截图、不写 enriched copy、不发布钉钉。
  • --html 必须覆盖自动发现;没有显式参数时只在 PRD 同目录选择修改时间最新的 .html / .htm;--no-html、无候选和 --mode file 不调用 doc media insert。
  • HTML 附件必须使用 doc media insert --index 0,插入成功后再执行 PRD read-back;不能把“正文已移除本地 HTML 路径”误报为“HTML 已交付”。
  • 未指定目标目录时必须使用默认父节点创建需求专属二级文档,不得静默发布到根目录。
  • 显式传 --folder 时默认不额外创建子目录;加 --create-run-folder 才在该 folder 下再建本次发布目录。
  • 真实发布后必须执行浏览器可见性验证,不能只以 dws doc read 成功作为完成。

Catalog Notes

  • Category: product delivery / PRD operations.
  • Status: active.
  • Public boundary: the adapter is public, but credentials, target node IDs, unpublished PRDs, screenshots, customer data, and real publish evidence must remain local unless explicitly approved for disclosure.