# Piaoquan Feishu Prd

> Use when 用户针对票圈业务要求撰写、整理、补充或追加产品、推荐、数据 PRD，针对票圈业务提到需求文档或飞书 PRD，或给出飞书链接要求形成票圈需求；这些情况必须使用本 Skill。纯阅读、摘要或评论，技术方案、复盘或周报，以及与票圈无关的通用行业 PRD 不使用本 Skill。

- Skill: `jayyang999/piaoquan-feishu-prd` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add jayyang999/piaoquan-feishu-prd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jayyang999/piaoquan-feishu-prd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: JayYang999 (https://skillmd.com/u/jayyang999)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jayyang999/piaoquan-feishu-prd

---


# 票圈飞书 PRD

把用户已确认的业务事实组织成可评审的票圈 PRD，并且只在获得明确授权后追加到用户指定的现有飞书文档。严格分离“起草”与“写入”，因为一个可读的文档链接不等于写入授权，用户对草稿的反馈也不等于允许修改外部文档。

## 必读与飞书路由

- 开始任何起草前，完整阅读 [references/prd-template.md](references/prd-template.md)，并以其九个一级标题、章节规则和排版规则为唯一模板。
- 当方案包含多个角色、模块、阶段、触发分支、调用关系或需要画板对齐方向时，同时使用当前已安装的 `piaoquan-visual-project`。由它负责视觉叙事、图型选择和可读性验收；本 Skill 继续负责九章结构、事实边界、草稿确认和飞书写入安全。简单到短段落即可说明的方案不强制触发可视化。
- 使用当前已安装的 `lark-doc` Skill 作为飞书正文访问和更新入口，并由该 Skill 决定实际的资源位置，不硬编码安装路径或版本路径。
- 分阶段加载飞书指南：只读阶段只读 `lark-doc` 要求的 `lark-shared` 和 fetch 指南；只有用户已对当前完整草稿给出明确写入授权后，才读 `lark-doc` 要求的 XML、style、update 和 update-workflow 指南。当前已安装的 `lark-doc` 对如何读取这些资源拥有最终决定权。
- 写前权限验证显式路由到当前已安装的 `lark-drive` Skill，并按它的当前要求读取 `lark-shared` 和原生 API schema 指南。只当目标是 `/wiki/` 或目标类型/token 存在歧义时，才加载 Wiki inspect/token-routing 指南；对无歧义的 `/docx/` 不加载该指南。不猜测资源路径或 API 参数。
- 所有飞书操作都使用用户身份 `--as user`，不得改用应用身份规避身份或权限问题。

## 不可突破的边界

- 永远不创建飞书文档；只能写入用户精确指定的现有文档链接。
- 永远不覆盖、替换、删除或移动现有内容；只能在文档末尾追加。这一限制用于保留原文和降低误修改风险。
- 在同时满足以下三项前不得写入：完整草稿已向用户展示；用户已明确确认写入；用户已给出精确的现有目标文档链接。
- `看看`、`先写一版`、`继续完善` 以及对草稿的修改意见都不是写入授权。必须等待如“确认追加到这个链接”这样明确、针对当前完整草稿的指示。
- 不得编造事实、指标、数据、规则、负责人、时间表、结论或依赖关系。不确定内容要么向用户确认，要么保持空白，不得用“合理假设”填充。

## 阶段一：读取与补齐事实

1. 读取用户提供的材料、SQL、查询结果、旧稿和链接。此时对链接只做只读访问，不得因为用户提供链接就执行写入。
2. 区分已确认事实、可由材料直接推导的表达与尚未知信息。重点检查“一、背景”、“三、产品方案”和“四、需求详情”所需的目标、问题、具体 Case、范围、边界、触发条件、处理规则、调用关系与可验收结果。
3. 只在缺口会实质影响上述章节时提问，每次只问一个当前最关键的问题。用户已经回答过的信息不得重复询问。
4. 补齐“变更记录”所必需的时间、版本号、变更人；缺哪一项就只问那一项。未提供变更原因时留空，不因此阻塞起草。
5. 起草前处理“二、需求分析”：用户未表明是否需要时，先问是否需要；用户已表明时不重复询问。如果需要，先利用已有上下文；只在分析类型或证据来源仍不清楚时，再次只问一个关键问题。如果不需要，保留该一级标题且标题下完全留空。

## 阶段二：起草与确认

1. 按下列顺序生成且只生成九个 Markdown 一级标题：

   ```markdown
   # 变更记录
   # 一、背景
   # 二、需求分析
   # 三、产品方案
   # 四、需求详情
   # 五、数据交付结果
   # 六、指标分析
   # 七、问题记录
   # 八、需求排期
   ```

2. PRD 标题或文档名是正文之外的元数据，不得将它变成第十个一级标题。不得创建“产品验收”标题；验收标准放入“四、需求详情”。
3. 集中写好“一、背景”、“三、产品方案”和“四、需求详情”。“二、需求分析”只写用户选定且有证据支撑的分析；用户不需要时完全留空。
4. 首稿的“五、数据交付结果”、“六、指标分析”、“七、问题记录”和“八、需求排期”只保留一级标题；标题下不得有段落、表格、占位符、“暂无”或其他任何内容。
5. 使用简洁、不跳级的标题层级。二级、三级标题只用于内容足以独立展开、需要导航定位的分节；像“本期范围”“方案边界”这类下方只有几行短内容的局部标签，改用 `**本期范围：**`、`**方案边界：**` 等加粗文字，不得使用二级或三级标题。只有真实行列关系才使用表格。公式必须是有效 LaTeX，不得把伪代码冒充公式。
6. 将“三、产品方案”写成面向老板对齐方向的方案概览。需要可视化时，按 `piaoquan-visual-project` 先建立“问题或 Case → 触发 → 业务主链路 → 结果与边界”的视觉叙事，再选择能讲清当前决策的最小视图；为保证本 Skill 的飞书追加链路可渲染，默认用一张 Mermaid `flowchart` 作为主画板。只有多系统接入关系会实质影响工程判断时，才增加一张工程接入图，并在“四、需求详情”解释调用和责任边界。主画板只承载产品方向和关键关系，不放公式、指标计算、字段、接口、埋点、参数、完整异常枚举或验收用例；这些细节分别留在“二、需求分析”或“四、需求详情”。方案简单到一个短段落即可说明时不强制画板。其他章节仅在条件、分支、兜底、异常或时序用图能实质提高清晰度时使用流程图。
7. 将完整草稿显示给用户审阅，然后停止。只有在用户看到当前完整版本后明确确认写入，才能进入下一阶段。

## 阶段三：安全追加到现有文档

1. 用户未给出精确目标时，只向用户索要一个现有飞书文档链接；不得代为挑选文档，也不得创建新文档。
2. 在任何写入前执行 `lark-cli auth status --json --verify`，记录当前活跃用户的 `userName`、`openId`、`tokenStatus` 和 `verified`。必须确认 token 状态有效且 `verified == true`，并将 `userName`/`openId` 与用户意图中的账号匹配：如果用户已指明账号，不匹配就停止；如果用户尚未指明，展示当前 `userName` 和 `openId`，每次只问一个问题，并在写入前取得其对使用该账号的明确确认。身份不匹配、token 无效或校验未通过都立即停止。
3. 按当前 `lark-drive` Skill 的要求先用 `lark-cli schema drive.permission.members.auth --format json` 查看 schema，再以用户身份检查编辑权限：
   - 对 `/docx/` URL，从 URL 路径精确提取 token，执行 `lark-cli drive permission.members auth --as user --token "<token>" --type docx --action edit --format json`。
   - 对 `/wiki/` URL，先按 `lark-drive` 的 inspect/token-routing 流程确认对象和 canonical Wiki node token，再执行 `lark-cli drive permission.members auth --as user --token "<canonical_wiki_node_token>" --type wiki --action edit --format json`。
   - 必须确认返回中 `auth_result == true`。可读、scope 存在或可 fetch 都不能推断拥有编辑权限，不得用试写探测权限。
4. 修改前的最终预读快照必须始终按 `lark-doc` fetch 指南以 XML `detail=full` 读取目标，不得把 with-ids 作为替代路径。校验文档标题、可读性和目标一致性，并保存此次最终快照的 `revision_id`、重复性判断证据与原文最后一个顶层 block ID。如原文为空，明确记录这一状态。
5. 如果已有同主题或高度相似的 PRD，向用户展示重复证据并暂停，等用户确认仍要追加。
6. 将获批的 Markdown 草稿转为飞书 XML：
   - Markdown H1、H2、H3 分别转为 `<h1>...</h1>`、`<h2>...</h2>`、`<h3>...</h3>`。
   - 表格转为 `lark-doc-xml` 支持的表格 XML。
   - 公式转为 `<latex>...</latex>`。
   - Mermaid 转为 `<whiteboard type="mermaid">...</whiteboard>`。
   - 普通段落、列表、粗体、链接和行内代码严格按当前已加载的 `lark-doc` XML 指南转换，不自创标签或属性。
   - 对每个生成的 XML 文本节点恰好转义一次：明确包括标题、段落或列表项、表格单元格、`<latex>` 内容和 Mermaid 内容。将其中原始的 `&`、`<`、`>` 分别转义为 `&amp;`、`&lt;`、`&gt;`；不遗漏也不对已转义文本二次转义。
   - 不输出 `<title>`，因为追加不得修改现有文档标题。
   - “五、数据交付结果”至“八、需求排期”只生成 `<h1>`，不得在标题后生成空 `<p>` 或任何占位块。
7. 先在内存或安全临时输入中准备完整 XML，再启动一个能接收标准输入的进程，将 XML 精确流入一次，然后关闭标准输入以提交。不得以看到空 EOF 的非交互命令调用 `--content -`。执行下列精确安全操作：

   ```bash
   lark-cli docs +update --as user --doc "<目标链接>" --command append --doc-format xml --revision-id <预读 revision_id> --content -
   ```

8. 明确禁止 `create`、`overwrite`、`str_replace`、`block_replace` 和 `block_move_after`；也不得用其他命令达成替换、移动或非末尾写入。
9. 检查命令结果中 `ok`、`data.result` 和 `warnings`。任何可能已改变文档状态的响应，包括 `success`、`partial_success` 或存在 `warnings`，都必须继续执行只读 XML `detail=full` 边界回读以诊断实际结果；不得因为结果尚不可验收就阻断该只读诊断。只有 `ok == true`、`data.result == success`、没有未解决的 `warnings`，且阶段四全部验证通过，才具备完成验收资格。
10. 如果出现 revision conflict，重新以 XML `detail=full` 读取当前文档，基于完整细节重建重复性判断、原文末尾边界与新 `revision_id` 证据，然后停止等待用户对新状态重新明确确认。不得盲目重试或沿用旧确认。
11. 出现 `partial_success` 或 `warnings` 时，绝对不得再次追加整篇 PRD。使用上一步的只读 XML `detail=full` 边界诊断判定实际差异：只有当诊断能证明缺失内容是从某个完整 block 起直至 PRD 结尾的单一连续尾部，且追加该尾部仍会保持精确的九章结构时，才可以自动追加修复该尾部一次。修复前重新预读并使用新 `revision_id`，修复后再做 XML `detail=full` 边界回读。任何中间标题、表格、公式或流程图缺失，或者部分状态无法确定，都必须停止并报告；不得把中间片段追加到文档末尾。该 `partial_success`/警告分支不得宣称完成，即使已执行上述安全尾部修复。

## 阶段四：回读验收

1. 写后验收只接受 XML `detail=full` 回读，不得把 with-ids 作为验收路径。如果原文非空，按 `lark-doc` fetch 指南从写前保存的原文最后一个顶层 block 开始，以 XML `detail=full` 回读到文档末尾。如果原文为空，对整份文档执行 XML `detail=full` 回读。两种情况都不得依赖更新响应中的 `new_blocks` 作为内容完整性证据。
2. 验证原边界 block 内容和位置未变，其后恰好只追加了一组 PRD；该组包含精确九个一级标题且顺序正确，没有“产品验收”，“二、需求分析”符合用户选择，“五、数据交付结果”至“八、需求排期”标题下依然完全留空。
3. 验证表格、LaTeX 和 Mermaid 画板已渲染为相应组件，而不是明文标记或代码。
4. 把写入时的 revision lock 与从原有最后 block 开始的边界回读共同作为保留原文的证据，验证原有内容仍在新增 PRD 之前且未被替换、移动或截断。
5. 只有全部检查通过后才声明写入完成；否则报告精确差异和已停止的动作。

## 后续补写第五至第八章

可以根据用户后续材料起草这四章，但本 Skill 的追加式流程无法把内容插入既有标题下。默认交付草稿由用户手工粘贴；如果用户要求 Agent 写入原章节，说明这需要一个明确确认的、不属于本 Skill 追加流程的独立定向编辑任务。不得默认追加重复标题、“补充章节”或附录。

## 错误与停止条件

- 链接无效、身份不符、无读权限、无写权限或目标无法唯一确认：立即停止，报告具体问题，不尝试其他文档。
- 用户要求创建新文档：拒绝创建，并请其提供现有文档的精确链接。
- 用户未明确确认写入：始终停留在草稿状态，不调用写入命令。
- 用户要求覆盖、替换、移动或在原章节中插入：说明本 Skill 仅允许末尾追加，退出当前写入流程；如果用户仍需要，必须将其重新确认为一个独立的定向编辑任务。