# Panova

> Analyze a codebase or PRD from a product manager's perspective and generate an interactive business anatomy report. Use this skill proactively whenever someone wants to understand what a product does, how it works, or what happens if something changes — even if they don't use the word "分析". Triggers include: "分析产品", "产品拆解", "业务梳理", "panova", "帮我理解这个产品", "产品架构分析", "这个项目是干什么的", "帮我梳理一下业务", "新人入职想了解", "这个系统怎么用", "帮我看看这个代码库", "business analysis", "product anatomy", "explain this product", "what does this system do". Also trigger when a PM or non-technical person asks about business logic, user flows, or impact analysis of a codebase.

- Skill: `oil-oil/panova` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add oil-oil/panova`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oil-oil/panova/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: oil-oil (https://skillmd.com/u/oil-oil)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oil-oil/panova

---


# Panova — 产品业务拆解

从代码库或 PRD 中提取业务全貌，生成一份交互式报告。

**目标读者：** 产品经理和新加入的团队成员。他们需要快速理解"这个产品做什么、改了什么会影响谁"，不需要看代码细节。

---

## 首次触发

第一次进入时，简短确认即可：

> 我来帮你拆解这个产品的业务全貌，生成一份可交互的报告。默认读当前代码库做全量分析。
>
> 如果你只想看某个模块（比如"只看支付"），或者有 PRD 文档想让我读，告诉我就行。否则我直接开始。

等用户回复后再开始。如果用户说"开始"、"好的"或类似表述，直接用当前工作目录做全量分析。

---

## 分析流程（3 个阶段）

### 阶段 1：深度阅读

根据用户选择的来源，逐层阅读：

**代码库模式：**
- 先读 README、CLAUDE.md、package.json（或对应语言的项目配置），搞清楚项目是干什么的
- 读路由/入口文件，画出系统有哪些用户可触达的功能
- 读数据模型（数据库 schema、类型定义、ORM 模型），提取核心实体和状态流转
- 读业务逻辑层（service、controller、hook），理解实体之间的关系和流转规则
- 读外部集成（API 调用、第三方 SDK），标记系统边界
- 读 UI 层（组件、页面、样式），提取交互模式

**PRD 模式：**
- 读取指定目录下所有文档
- 按上述相同维度提取信息

**这个阶段的目标是在脑子里"用一遍"这个产品：**
- 这个产品给谁用？解决什么问题？
- 用户从打开产品到完成核心任务，经过哪些步骤？每一步看到什么、做什么？
- 每一步背后，系统在做什么？涉及哪些实体和规则？
- 哪些地方可能出错？出错了用户看到什么？
- 改了某个规则，用户体验的哪些环节会跟着变？

**什么时候可以停止阅读：** 当你能用 3-5 句话向 PM 描述"用户从头到尾走一遍是什么体验"时，阅读阶段就够了。不需要读完每一个文件——抓住主线，补充关键分支即可。

### 阶段 2：写报告

读完 `~/.claude/skills/panova/BLOCKS.md` 了解可用的块语法，然后用扩展 Markdown 格式写报告。

**核心原则：跟着用户走，不要按系统分类。**

报告的主体是一段完整的用户旅程。概念、规则、影响链、异常场景都嵌在旅程里，在它们自然出现的位置讲解——而不是先讲完故事再分门别类列出来。

只有那些 PM 需要独立做决策的东西（比如定价模型、角色配比）才单独成章节。

**怎么切分旅程：** 找到产品的"主线任务"（用户从进来到达成核心目标的路径），按时间顺序拆成 4-6 个阶段。每个阶段对应用户的一个关键动作或一次等待。比如：打开 → 配置 → 等待 → 操作 → 结果 → 下一轮。如果产品有多条平行主线（比如买家和卖家），选最核心的一条作为主线，其他在相关位置提及。

报告结构（根据项目实际情况调整）：

```
1. 一句话定位 + 指标卡片
2. 谁在用（用户画像、使用场景）
3. 跟着用户走一遍（报告主体，占 60-70% 篇幅）
   └ 按用户旅程的阶段组织，每个阶段包含：
     - 用户做了什么、看到什么（用 :::demo 画出关键界面示意）
     - 背后发生了什么（用 :::mermaid 或 :::sequence 画流程）
     - 这一步涉及的业务规则（用 :::callout 高亮）
     - 如果出错了会怎样（异常场景）
     - 改了这里会牵动什么（用 :::impact 内联）
4. 关键决策点（只提炼 PM 需要独立决策的概念）
5. 外部依赖
6. 交互设计规范（如果项目有 UI 层且有 10+ 个页面或组件，读 INTERACTION-GUIDE.md 了解提炼方法；前端薄的项目跳过）
7. 附录：术语对照表
```

### 阶段 3：输出报告

**第一步：分批写入 Markdown 文件**

报告内容通常较长，**不要试图一次性生成全部内容**——这是卡住的主要原因。按以下顺序分批写入：

1. **先创建文件，写入报告头部**（h1、指标卡片、用户画像章节）
2. **逐段追加**：每完成旅程中的一个阶段，立即用 Edit 工具追加到文件末尾，不要等全部写完再保存
3. **最后追加**收尾章节（关键决策点、外部依赖、术语表）

具体做法：
- 用 Write 工具创建文件并写入前 1-2 个章节
- 后续每个章节用 Edit 工具追加（在文件末尾 append）
- 每次追加后可以告诉用户进度，例如："已完成旅程第 2 阶段，继续写第 3 阶段..."

**为什么要分批：** 单次生成超长内容容易触发超时或中途截断，分批写入可以确保每段内容都安全落盘，即使中途出错也不会丢失已完成的部分。

**第二步：调用构建脚本生成 HTML**
- 运行：`bash ~/.claude/skills/panova/build.sh ./panova-report.md ./panova-report.html`
- 脚本会自动验证生成的 HTML（JS 语法检查、危险模式扫描）
- **如果构建失败：** 看错误信息。常见问题：markdown 中包含未转义的反引号或 `${`，demo 块中包含 `</script>`。修正 markdown 后重新构建
- **注意：** 生成的报告需要联网才能正常显示（依赖 CDN 加载 markdown-it 和 mermaid）

输出后告诉用户：
> 报告已生成：`./panova-report.html`，用浏览器打开就行。
> 如果你对某个部分有疑问，直接问我，我可以结合代码给你解释。

---

## 写作规范

### 报告标题格式

h1 用 `产品名 — 一句话定位` 格式（如 `Wolfcha — AI 狼人杀`）。不要加"产品拆解"、"业务分析"之类后缀。h1 会被自动设为浏览器 tab 标题。

### 核心心法：让 PM 身临其境

写报告的时候，想象你在给一个 PM 做产品演示。不是念 PPT，是打开产品，一步一步操作给他看，边操作边讲：

- "你点这个按钮"——PM 能想象自己在操作
- "然后等 5 秒"——PM 知道这里有等待
- "如果网断了，这里会卡住"——PM 知道风险在哪
- "这个规则改了的话，那边也会变"——PM 知道牵连在哪

### 用 demo 块画界面示意

每当描述"用户看到什么"时，用 `:::demo` 画一个简化的界面示意。不需要像素级还原，但要让 PM 脑子里有画面。

好的 demo：用简单的 HTML/CSS 画出关键元素的布局和状态，用颜色和文字标注含义。
不好的 demo：只有文字描述没有视觉，或者画得太复杂反而分散注意力。

### 语气和句式

- 用"你"称呼读者，像在跟同事口头讲解
- 每句话只说一件事
- 减少形容词，直接说是什么、做什么
- 技术概念翻译成业务语言。"存储在 Redis" → "临时缓存，重启会清空"
- 技术细节用 `:::tooltip` 补充，不混在正文里

### 概念怎么写

概念不用单独列成"词典章节"。在旅程中第一次遇到时，用 1-2 句话解释清楚，用 `[链接](tip:详细解释)` 提供更多信息。

只有当一个概念满足以下条件时，才值得单独成卡片放在"关键决策点"章节：
- PM 可能需要就这个概念做独立决策（比如定价策略、角色配比、权限模型）
- 这个概念有复杂的状态流转，嵌在旅程里讲不清楚
- 改了这个概念会产生广泛的连锁反应

单独成卡片时的格式：

```markdown
### 概念名

一句话说清楚它是什么。

**怎么产生：** 谁在什么情况下创建它。

**状态变化：** 有哪些状态，什么触发切换。（没有明确状态则省略）

**影响范围：** 改了它，哪些地方跟着变。
```

### 影响链怎么写

影响链不单独堆在报告末尾。在旅程中讲到某个规则或功能时，紧跟着写它的影响链。每条影响链说的是"对用户或业务有什么影响"，不是"需要改哪个文件"。

### 异常场景怎么写

每个核心流程至少标注 1-2 个主要异常场景。格式简单直接：

> **如果网断了：** 游戏卡在当前阶段，刷新页面后从最近的检查点恢复。

---

## 报告交互特性

报告 HTML 自动提供这些交互，AI 不需要手动实现：

- **侧边导航 + 搜索**：自动从 h2/h3 生成，支持关键词过滤
- **概念卡片**：h3 级别的概念（带"怎么产生"/"影响范围"的）自动包裹成卡片
- **概念网格**：所有概念卡片自动生成网格概览
- **关联概念 Popover**：`[概念名](#anchor)` 链接悬停时弹出简介
- **折叠块**：`:::tooltip` 默认折叠，`:::impact` 第一个展开其余折叠
- **Demo 块**：`:::demo` 内的 HTML 渲染在沙箱 iframe 中，自动适配高度
- **移动端**：900px 以下有悬浮导航按钮

---

## 块语法参考

所有可用的扩展 Markdown 块语法定义在 `~/.claude/skills/panova/BLOCKS.md`。写报告前先读一遍。

---

## 报告生成后

生成报告后进入问答模式。用户可能会问：
- "如果我想加一个 XX 功能，需要动哪些地方？"
- "为什么 XX 要这么设计？"
- "如果我把 XX 的规则从 A 改成 B，会影响到谁？"

回答时结合代码给出具体引用，保持同样的写作规范——面向 PM，用业务语言解释。