内容
# 🗺️ 项目流程图
[Claude Code](https://claude.com/claude-code) 的一项**技能**，它可以读取任何代码库的全部内容，并将其转换为**彩色、基于角色的用户流程图** — 可以是实时 **FigJam** 看板（通过 Figma MCP）或自包含的 **Markdown 文件**，其中流程图以 Mermaid 图表绘制。
将 Claude 指向一个仓库，说 *"映射用户流程"*，即可获得工具实际工作的可视化展示：登录/会话门户、每个角色一个泳道、核心端到端生命周期和实体状态机 — 带有占位符/尚未构建的路径，清晰地标记为虚线，以便**已构建 vs 预期**一目了然。
> 适用于任何项目：Web 应用、后台管理、SaaS、API+UI。
---
## ✨ 您将获得
自动选择两种输出模式：
| 模式 | 何时 | 输出 |
|------|------|--------|
| **FigJam 看板** *(首选)* | Figma MCP 已设置 | 实时、可编辑的 FigJam 图表，位于您的 Figma 账户中，附带声明 URL |
| **Markdown 文件** *(备用)* | Figma MCP **未**设置 | 单个 `PROJECT-FLOW-MAP.md`，包含 `mermaid` 图表，可在 GitHub、GitLab、VS Code、Obsidian 和 Notion 中渲染 |
两者使用相同的分析、相同的泳道结构和相同的颜色调色板 — 因此您不会因为尚未连接 Figma 而受阻。
查看 [`examples/EXAMPLE-FLOW-MAP.md`](examples/EXAMPLE-FLOW-MAP.md)，了解 Markdown 输出的示例（在 GitHub 上查看以查看图表渲染）。
---
## 📦 要求
- **[Claude Code](https://claude.com/claude-code)**（CLI、桌面版或 IDE 扩展）。技能位于 `~/.claude/skills/`。
- **（可选）Figma MCP** — 仅在需要实时 FigJam 看板时需要。没有它，技能会自动生成 Markdown 流程图。参见 [设置 Figma MCP](#-optional-设置-figma-mcp)。
您**不需要**Figma 账户即可使用此技能 — Markdown 模式下只需要 Claude Code。
---
## 🚀 安装
技能只是一个包含 `SKILL.md` 的文件夹。将其安装到您的 Claude Code 技能目录中一次，它就可以在每个项目中使用。
### 选项 A — 一行安装（macOS / Linux）
```bash
git clone https://github.com/lmohamed95/claude-project-flow-map.git
cd claude-project-flow-map
./install.sh
```
### 选项 B — 手动复制
```bash
git clone https://github.com/lmohamed95/claude-project-flow-map.git
cp -r claude-project-flow-map/project-flow-map ~/.claude/skills/
```
### 选项 C — 按项目（与仓库/团队共享）
将技能提交到项目中，以便克隆它的人都能使用：
```bash
mkdir -p .claude/skills
cp -r /path/to/claude-project-flow-map/project-flow-map .claude/skills/
```
**验证是否安装成功：** 启动 Claude Code 并运行 `/project-flow-map` — 它应该出现在技能列表中。
---
## 💡 用法
在您想要映射的仓库中，用自然语言直接询问。以下任何一个命令都可以触发技能：
- `映射用户流程`
- `/project-flow-map`
- `创建应用工作流程图`
- `项目流程图`
- `按角色绘制用户旅程图`
**接下来会发生什么：**
1. **分析** — Claude 读取您的路由、导航、身份验证、角色/权限、域模型和每个模块的成熟度，以构建一个事实模型，并首先为您提供一个简短的书面摘要。
2. **确认范围** — 它会询问一次（带有合理的默认值），是按**角色**、**单个端到端流程**还是**按模块**来构建地图。
3. **生成** —
- 如果 **Figma MCP 已设置** → FigJam 看板 + 声明 URL。
- 如果 **未设置** → `PROJECT-FLOW-MAP.md` 在您的仓库中，您可以在 VS Code 中预览（`Cmd/Ctrl+Shift+V`）或推送到 GitHub。
4. **呈现** — 区域摘要、颜色键和诚实的注意事项（哪些流程是真实的 vs 占位符，哪些角色权限是强制的 vs 仅预期）。
### 阅读地图
| 颜色 | 含义 |
|-------|---------|
| 🔵 蓝色 | 入口/会话 |
| 🟡 黄色菱形 | 决策点 |
| 🟣🟠🔵🟢 | 每个角色一种颜色 |
| 🔴 红色 | 核心生命周期（主要旅程） |
| ⬜ 灰色 | 实体状态机 |
| ⬛ 虚线 | 占位符/目标 — **尚未构建** |
---
## 🎨 （可选）设置 Figma MCP
仅在需要实时、可编辑的 **FigJam** 看板而非 Markdown 时需要。
该技能使用 Figma 的官方 MCP 服务器。将它作为连接器添加到 Claude 中：
- **Claude Code / claude.ai：** 在您的 MCP/连接器设置中添加 **Figma** 连接器并授权，然后在 Claude Code 中确认 `/mcp`。
- **CLI：** `claude mcp add` 并按照提示为 Figma 服务器授权，然后通过 `/mcp` 授权。
连接后，重新运行技能，它将自动生成 FigJam 看板。参见 Figma 文档了解当前的 MCP 设置步骤：<https://help.figma.com/hc/en-us/articles/32132100833559>.
> **没有 Figma？没问题。** 直接跳过此步骤 — 技能会检测到缺少的 MCP 并改为编写 Markdown 流程图。
---
## 🧠 它是如何工作的（底层）
整个技能是一个单独的 [`SKILL.md`](project-flow-map/SKILL.md) — 一个带有 YAML 前置信息的 Markdown 文件，Claude Code 按需加载。它定义了四个阶段（分析 → 确认范围 → 生成 → 呈现）和一套严格的 Mermaid 约定和颜色调色板，以便图表始终保持一致且易读。
所有内容都基于您的实际代码 — 技能被明确告知永远不要发明模块或角色，并且要将它不确定的任何内容标记为虚线的“计划”节点。
---
## ❓ 故障排除
- **`/project-flow-map` 不显示** — 确保文件夹位于 `~/.claude/skills/project-flow-map/SKILL.md`（不要嵌套更深），并重启 Claude Code。
- **Mermaid 图表显示为代码，而不是图片** — 您正在使用不支持 Mermaid 的渲染器。GitHub、VS Code 预览、Obsidian 和 Notion 都可以渲染它；纯文本编辑器则不行。
- **FigJam 生成失败** — 几乎总是 Mermaid 语法问题（未引用的标签、 stray `end` 或表情符号）。技能的约定避免了这些；如果仍然失败，相同的图表将作为 Markdown 交付。
---
## 🤝 分享和贡献
此仓库*是*可分享的软件包 — 发送链接给朋友并指向 [安装](#-installation) 部分。问题和拉取请求欢迎：Mermaid 约定改进、更多颜色调色板或新区域模板。
## 📄 许可证
[MIT](LICENSE) — 随意使用，无担保。
