# Piaoquan Visual Project

> Use when 用户要用画板、流程图、架构图、调用图、数据流或少文字的方式讲清票圈项目需求、产品方案、推荐/算法方案、数据方案、技术实现、评审材料或项目复盘；即使用户只说“把这个项目讲直观一点”“给老板看”“画一下业务和实现链路”，也必须使用本 Skill。票圈 PRD 同时使用 piaoquan-feishu-prd，由后者控制文档结构和飞书写入；简单问答、单点代码或 SQL 修改、纯文本润色、与票圈无关的通用可视化不使用本 Skill。

- Skill: `jayyang999/piaoquan-visual-project` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jayyang999/piaoquan-visual-project`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jayyang999/piaoquan-visual-project/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-visual-project

---


# 票圈项目可视化沟通

把已经确认的项目事实压缩成少量、可顺着讲述的视觉结构，让老板、产品、算法、数据和工程能快速看到同一条主线。视觉的价值是降低理解成本，不是把正文搬进节点，也不是用图掩盖尚未确认的事实。

## 职责边界与协作

- 本 Skill 负责视觉叙事、图型选择、内容取舍和可读性验收，不负责替代完整 PRD、技术文档、SQL 或数据报告。
- 票圈 PRD 同时使用当前已安装的 `piaoquan-feishu-prd`。本 Skill 生成视觉结构，PRD Skill 决定九章结构、草稿确认和飞书写入边界；两者冲突时，以 PRD Skill 的文档与写入安全规则为准。
- 需要查看、创建或修改真实飞书画板时，使用当前已安装的 `lark-whiteboard`，并遵守它的预览、渲染检查、身份、权限和写入流程。本 Skill 本身不把“生成源码”视为“画板已写入”。
- 涉及 MaxCompute SQL 时，继续使用 `piaoquan-maxcompute-sql` 锁定来源表、字段、粒度、分区和口径；视觉只解释链路，不替代 SQL 验证。
- 用户只要求讨论或起草时，先在对话中给出可审阅的视觉草稿；没有明确外部写入授权时，不更新飞书或其他外部载体。

## 工作流

### 1. 锁定要讲清楚的事实

从用户材料、当前文件和已验证结果中提取：

- 业务问题或原理，以及至少一个能代表问题的具体 Case；
- 目标受众和这次沟通要促成的判断；
- 范围、边界、角色、触发条件、主链路和兜底；
- 产品、推荐/算法、数据、工程之间的接入点和调用关系；
- 预期结果及能证明结果的验收方式。

区分已确认事实、可由证据直接推导的关系和未知信息。缺口会改变主链路、触发规则、系统边界或验收结果时，只问一个当前最关键的问题；否则明确省略未知内容，不编造节点填满画板。

用户已经把 Case 限定在某个状态时，直接从该状态开始，不为了图形对称擅自补出相反状态及其去向。不要把“用于兜底”“希望降低影响”等设计意图写成“保证可用”“避免阻断”“提升效果”等已经得到验证的结果。

保持输入材料的时序动词和触发粒度：材料说“产生行为后切换”，就从行为事件直接连到切换动作；不得自行加入“再次进入”“刷新后”“下一次请求”“次日”“重试”等新的时间点或触发事件。材料没有说明切换发生在当前请求还是后续请求时，将这一点标为待确认，不选择其中一种画成事实。

### 2. 先建立叙事，再选择图型

默认按以下顺序组织信息，但只保留当前项目真正需要的部分：

```text
问题 / 真实 Case
  → 谁在什么条件下触发
  → 业务主链路如何运行
  → 系统、数据和模型如何接入
  → 得到什么结果，边界和兜底是什么
  → 如何验收
```

选择能讲清当前决策的最小视图：

| 需要回答的问题 | 首选表达 |
|---|---|
| 问题发生在哪里，方案改变了什么 | Before / After 或问题到方案的流程图 |
| 多角色如何协作，业务如何流转 | 泳道图或分阶段流程图 |
| 什么条件触发、如何分支和兜底 | 决策树、状态图或简短伪代码 |
| 客户端、服务、模型、表和任务如何调用 | 时序图、调用树或架构/数据流图 |
| 文件、模块或职责如何调整 | 浅层目录树或结构 Diff |
| 阶段如何推进、每期交付什么 | 路线图或时间线 |
| 多指标、实验组或漏斗如何比较 | 有明确口径的图表；不把相关性画成因果关系 |
| Mermaid 难以表达的复杂布局或交互 | 聚焦的 SVG/HTML；保留可编辑源文件并做渲染检查 |

一张图能讲清时不要拆成多张；一张图需要同时承担不同阅读顺序时，拆成“业务主画板 + 工程接入图”，通常不超过两张核心图。

### 3. 形成分层画板

**主画板**面向方向对齐，优先展示：

- 问题或 Case；
- 目标和核心方案；
- 主链路、关键触发与兜底；
- 结果和方案边界。

**工程接入图**只在多系统、多任务或多数据源的接入关系会影响实现判断时增加，展示：

- 调用发起方与被调用方；
- 输入、输出和关键状态；
- 在线与离线边界；
- 失败或降级路径；
- 责任归属和接入位置。

字段清单、SQL、公式、权重、接口参数、完整埋点、异常枚举和验收用例不放进主画板；它们进入正文、表格或附录。若某个字段或指标决定分支含义，只在节点中使用业务名称，不展开计算细节。

### 4. 控制视觉密度

- 用真实业务名称和动作描述节点，避免“模块一”“数据处理”“智能优化”等空泛标签。
- 节点优先写成“动作 → 结果”或“条件 → 去向”，不用整段解释文字。
- 只保留影响理解、决策、接入或验收的角色、状态、调用和边界。
- 用布局表达主次和顺序；颜色只承担少量稳定语义，并同时配合文字或形状，不能只靠颜色区分。
- 主路径应能从一个具体 Case 顺着箭头走到结果；回路、跨线和双向箭头会破坏阅读时，重新分层或拆图。
- 每条成功、失败和兜底路径都应落到输入材料已经定义的用户可见结果或下游入口，不能停在“内容池”“原召回”“降级服务”等中间资源上。
- 不补画输入材料没有定义的对称分支、前置状态或系统能力；确实影响理解时，把它列为待确认项，而不是放入已确定链路。
- Mermaid 能清楚表达时优先 Mermaid，以便评审修改和飞书画板复用；不要为了视觉效果把简单逻辑升级成难维护的 SVG/HTML。

## 输出合同

除非上层 Skill 规定了固定结构，按以下顺序交付：

1. 直接给出一张主视觉，不用长篇前言；
2. 图已足够清楚时不复述节点；只有需要帮助决策时，补充零到三条短结论，限于图中没有表达的关键判断、方案边界或待确认点。若删除某条结论不会损失新信息，就删除它；不要用“启动、切换、兜底”或“业务主链路、算法接入点、失败降级”等标签逐项复述节点；
3. 只有实现或验收需要时，再给工程接入图或细节附录；
4. 明确哪些关系已由材料确认，哪些仍需业务、数据或工程负责人确认。

票圈 PRD 中，把主画板放在“三、产品方案”，用它概括“问题/目标 → 核心思路 → 主链路/模块 → 结果与边界”。具体 Case 可在“一、背景”展开，触发、调用、字段、埋点和验收细节放在“四、需求详情”。为保证当前 PRD 安全追加链路可渲染，默认输出 Mermaid `flowchart`；只有用户明确要求其他格式，且实际飞书画板工作流能够验证时才改变格式。

用户只要求画板时，不自动扩写完整 PRD。用户要求完整方案时，图旁文字只补充图中不适合承载的事实，不逐节点复述。

## 画板验收

交付前逐项检查：

- **30 秒主旨：** 只看标题、主路径和终点，能否说出项目解决什么问题、怎么解决、结果是什么？
- **Case 可走通：** 至少一个真实 Case 能否从触发沿主路径走到结果或兜底？
- **边界可判断：** 读者能否区分业务判断、算法/数据处理和工程动作，并找到接入位置？
- **事实不越界：** 是否没有虚构指标、字段、负责人、因果关系、时间表或系统能力？
- **视觉不超载：** 是否删除了正文式节点、重复说明、无关支路和仅为装饰的元素？
- **最终效果：** 若生成 SVG/HTML 或写入飞书，是否实际预览并检查文字溢出、遮挡、断线、顺序和移动端/窄宽度可读性？
- **交付状态准确：** 只生成源码、图片或本地文件时，不得声称真实飞书画板已经更新。

达到这些标准后停止，不继续增加图表或装饰。