safari-explore

Safari 探索 🚙

你把森林抛在身后。树木逐渐稀疏，树冠豁然开朗。红土一路延伸至地平线，点缀着金合欢树的剪影，热浪在远处微微荡漾。你爬上吉普车——帆布车顶已卷起，乘客座上放着皮面日志本，脖子上挂着双筒望远镜。发动机启动，发出令人满足的轰鸣声。

这不是狩猎，也不是构建。这是一场 Safari——去自然栖息地观察事物、记录发现，并带着计划归来，把粗犷的荒野变成壮丽景观的旅程。每一站都是一次发现。野外的每一种生物，都在日志本里有自己的一页。等你在日落时分扎营，日志本已经写满，前进的方向也已清晰。

当你有 许多事物需要审查 时，就适合进行 Safari——不是修复一个 Bug，也不是构建一个功能，而是一整片需要逐项查看的领域。可以是 Curio、管理页面、API 端点、组件、数据库表，等等。你要一路查看 N 个项目，逐一停靠，不落下任何一个。

何时启动

• 用户有一组相关项目需要审查、审计或完善
• 用户说“我们逐一检查所有 X”“审查每一个 Y”或“Safari 一遍 Z”
• 用户调用 /safari-explore，或提到 Safari／探险／逐项查看
• 有5 个以上项目需要系统审查（少于 5 个？直接审查即可）
• 目标是全面的计划文档，而非立即修改代码
• 用户希望整个过程有趣且沉浸，而不是像核对清单一样枯燥

重要提示： Safari 负责观察和规划，不会在途中实施修复。你负责观察、记录、设计——然后带着装满笔记的吉普车归来，真正的工作才开始。如果想要实施修复，请在 Safari 结束后召唤动物们。

搭配使用： Safari 结束后，用 panther-strike 修复单个项目，用 elephant-build 实现涉及多个文件的改动，用 bee-collect 将发现整理成问题

---

探险

EMBARK → SURVEY → OBSERVE → SKETCH → CAMP
   ↓        ↓       ↓ ⟳       ↓ ⟳      ↓
 Pack     Map the  Binoculars  Design   Compile
 the Jeep Terrain  at each     each    Expedition
                   stop        stop    Journal

阶段 1：启程

太阳低垂，金光熠熠。你把背包扔进吉普车后座，在引擎盖上展开地图，用手指沿路线描摹。每一站都已标记，每种生物都已记录。发动机怠速运转，热带草原静候着你。

出发前先明确探索范围：

确定项目集合：

你要审查什么？列出每一个项目：

# Examples — adapt to what you're actually reviewing:
gf --agent search "curios"           # Find all curio-related files
ls apps/ libs/ services/ workers/   # All packages in the monorepo
gf --agent search "admin page"       # All admin pages

绘制路线图：

## 🗺️ Route Map

**Territory:** [What we're reviewing — e.g., "All 22 curios"]
**Terrain type:** [Pages / Components / Endpoints / Tables / etc.]
**Estimated stops:** [N items]

### The Route

| #   | Stop        | Category       | Notes |
| --- | ----------- | -------------- | ----- |
| 1   | Hit Counter | Retro/Web1.0   | —     |
| 2   | Mood Ring   | Organic/Nature | —     |
| 3   | Now Playing | Creative       | —     |
| ... | ...         | ...            | —     |

确定每一站的审查范围：

每个项目要查看什么？提前定义，确保每一站的审查标准一致：

• 管理页面？公共组件？API？数据库？以上全部？
• “良好”的标准——也就是你要依据什么来衡量
• 任何具体关注点（配色规范、无障碍、深色模式等）

创建日志文件：

# The expedition journal lives in docs/safaris/
# Name it after the safari: curio-safari.md, admin-safari.md, etc.

输出： 路线图已列出所有停靠点，审查范围已定义，日志文件已创建。吉普车已装载完毕。

---

阶段 2：调查

你站在吉普车里，一只手抓着防滚架，双筒望远镜紧贴双眼。眼前的景色徐徐展开。你看见水坑、兽群和地形特征。还没到那些崎岖地带，你就已经知道它们在哪里。

先快速浏览整个集合，再深入检查：

为每个项目记录 30 秒的初步印象：

### Quick Survey

| #   | Stop        | First Impression            | Warmth | Completeness | Priority |
| --- | ----------- | --------------------------- | ------ | ------------ | -------- |
| 1   | Hit Counter | Only 1 of 4 styles works    | Cold   | 30%          | High     |
| 2   | Mood Ring   | Public ignores displayStyle | Dead   | 20%          | Critical |
| 3   | Now Playing | Decent bones, needs polish  | Warm   | 60%          | Medium   |

划分地形类别：

按状况为项目分组——这能告诉你哪些地方最值得花时间：

• 蓬勃发展 🟢 — 实现扎实，只需稍作润色
• 稳步成长 🟡 — 基础良好，但仍有值得填补的缺口
• 逐渐枯萎 🟠 — 存在根本性问题，需要大幅返工
• 荒芜贫瘠 🔴 — 已损坏、不完整，或完全缺失

规划行进顺序：

你不必按顺序逐一造访。可以考虑：

• 优先处理关键项目（先观察受伤的生物）
• 按类别分组（先看所有复古项目，再看所有有机项目，依此类推）
• 依赖关系（如果项目 A 为项目 B 提供输入，先造访 A）

输出： 完成调查的地形图，并确定优先级和行进顺序。你已了解这片区域的情况。

---

阶段 3：观察

吉普车停了下来。尘土渐渐落下。你下车，靴子踩在干燥的土地上，发出沙沙声。举起双筒望远镜，打开日志。你开始观察。你留意一切——什么在移动，什么没有，什么缺失，以及什么让你意外。

此阶段会沿路线的每个停靠点循环进行。

每到一处，都要阅读实际代码并记录现状：

观察模板（每个项目一份）：

## [#]. [Item Name]

**Character**: [One sentence capturing what this item IS — its soul, its vibe, its purpose]

### Safari findings: What exists today

**[Layer 1 — e.g., Public component]** (`path/to/file`, N lines):

- [x] What works well (check these off — celebrate the good)
- [x] Another thing that works
- [ ] **What's broken or missing** — describe specifically
- [ ] **Another gap** — be concrete, reference line numbers

**[Layer 2 — e.g., Admin page]** (`path/to/file`, N lines):

- [x] ...
- [ ] ...

**[Layer 3 — e.g., API / Shared lib / Database]:**

- Types, fields, constants worth noting
- API caching, validation, limits
- DB schema notes

观察规则：

• 阅读实际文件。 不要凭记忆猜测。每条观察都必须有代码依据。
• 查看渲染结果。 使用 Glimpse 在浏览器中查看实际效果——单看代码无法了解全貌。
• 检查范围内定义的每一层（管理端 + 公共端 + API + 共享库 + 数据库）
• 肯定可用之处。 用勾号标记做得好的部分。这不是一场吐槽，而是诚实的观察。
• 具体指出缺口。 “硬编码的 rgba(0,0,0,0.04)”说得很好。“颜色不对”则不够具体。
• 记录个性。 每个项目都有自己的性格。计数器和情绪戒指给人的感受不同，要把这一点记录下来。

使用 Grove 工具进行调查：

gf --agent search "CurioHitcounter"     # Find related files
gf --agent usage "CurioHitcounter"       # Where is it used?
gf --agent func "hitcounter"             # Function definitions

使用 Glimpse 查看渲染状态：

# Capture the page where this item lives
uv run --project tools/glimpse glimpse capture http://localhost:5173/[item-page] \
  --season autumn --theme dark --logs

# Browse to the item and capture what it looks like in context
uv run --project tools/glimpse glimpse browse http://localhost:5173/[item-page] \
  --do "scroll to [item], click [item]" --screenshot-each

# Check dark mode rendering
uv run --project tools/glimpse glimpse matrix http://localhost:5173/[item-page] \
  --themes light,dark

截图是观察数据——在日志中，视觉观察结果应与代码观察结果一并记录。

Safari 式旁白：

每到一处之间，为行程配上旁白，让沉浸感延续下去：

“吉普车颠簸着驶过干涸的河床。前方有什么东西在午后的阳光下闪闪发光——情绪戒指在空地边缘熠熠生辉。你放慢车速，举起双筒望远镜。来看看它究竟是什么情况……”

输出： 为此停靠点撰写详细的观察记录，并写入考察日志。

---

阶段 4：绘制草图

你坐在吉普车引擎盖上，日志搁在一边膝盖上，手里的铅笔飞快移动。那只生物仍在视野之中。你描绘它现在的样子——然后在对页描绘它未来可能的样子。设计源于观察。此刻，你已看得一清二楚。

此阶段也会循环进行，并紧接在每次观察之后。

为每个项目设计一份“Safari 认可”的规格说明：

设计模板（每个项目一份）：

### Design spec (safari-approved)

**[Core design decision]:** [What this item should FEEL like when it's done]

#### [Major feature/improvement 1]

[Detailed design — be specific enough that someone could implement from this]

#### [Major feature/improvement 2]

[...]

### [Layer] fixes

- [ ] Fix 1 — concrete, actionable
- [ ] Fix 2 — concrete, actionable
- [ ] Fix 3 — concrete, actionable

### [Layer] fixes

- [ ] ...

### Migration needs (if any)

- [ ] New columns, new tables, new fields

设计规则：

• 每个项目都要有自己的个性。 不要把同一套模板套用到所有项目上。复古计数器和有机情绪戒指需要不同的关照。
• 从观察出发进行设计。 草图应直接回应你通过双筒望远镜看到的情况。
• 明确表达主张。 Safari 认可意味着你已经做出设计决策。不要用“也许”和“可以考虑”等含糊措辞——直接说明应该怎么做。
• 提供具体的检查清单。 每项修复都要列为勾选项。任何人拿起这本日志都应该能立即开始工作。
• 尊重已有成果。 观察阶段的勾号应保留下来。不要重新设计已经做得很好的部分。

输出： 完成此停靠点的设计规格说明。然后——回到吉普车上，前往下一站。

第 5 阶段：露营

太阳触及地平线。橙色的光洒满稀树草原。你把吉普车开到一棵金合欢树下，扎营、生火。你最后一次拿出日志，翻看每一页——每条观察、每幅草图——然后整理成探险报告。星星在头顶浮现，篝火噼啪作响。这趟旅程真不错。

整理完整的探险日志：

日志结构：

# [Name] Safari — [Subtitle]

> [One-line philosophy for the whole collection]
> **Aesthetic principle**: [Design direction]
> **Scope**: [What was reviewed at each stop]

---

## Ecosystem Overview

**[N] items** in [location]
[Any other structural notes]

### Items by category

**[Category 1]**: item1, item2, item3
**[Category 2]**: item4, item5, item6

---

## 1. [First Item]

[Full observation + design spec from phases 3-4]

---

## 2. [Second Item]

[...]

---

[...continue for all N items...]

---

## Expedition Summary

### By the numbers

| Metric          | Count |
| --------------- | ----- |
| Total stops     | N     |
| Thriving 🟢     | X     |
| Growing 🟡      | X     |
| Wilting 🟠      | X     |
| Barren 🔴       | X     |
| Total fix items | Y     |

### Recommended trek order

[Which items to implement first, and why]

### Cross-cutting themes

[Patterns that appeared across multiple stops — shared fixes, common issues]

将日志写入磁盘：

# The journal goes in docs/safaris/
# All safaris live flat — no lifecycle subdirectories

最后的 safari 旁白：

“火焰渐渐熄灭，只剩余烬。日志写满了——[N] 个停靠点，勾画了 [Y] 项修复方案，整片风景都已绘入地图。明天，动物们就要开始工作了。但今晚呢？今晚属于这趟旅程。真是精彩绝伦。”

**输出：**完整的探险日志已写入文件。Safari 之旅结束了，真正的工作现在才开始。

---

Safari 规则

只观察，不干预

Safari 负责记录和设计，途中绝不修复问题。你不会只为了检查狮子的牙齿就给它打镇静剂——你会留在吉普车上观察，并计划之后再安排兽医检查。观察和实施必须分开。

每个停靠点都要仔细观察

不要匆匆略过那些“看起来没问题”的项目。每个停靠点都要用望远镜观察。范围内的每个项目都要逐层检查。你可能会惊讶：那个远看“没问题”的项目，近看竟有三个功能坏了。

先把握特质，再列检查清单

列出修复项之前，先捕捉项目的_特质_——它是什么、它希望成为什么样、它应该给人什么感觉。“被困在水晶中的流动极光构成的神秘神器”，比“需要 7 种展示形状”更能指导设计。特质引导设计，检查清单随后跟上。

保持沉浸感

Safari 的全部意义就在于它很有趣。讲述各个停靠点之间的旅程。描述你从望远镜中看到的景象。让日志鲜活生动。如果它开始像电子表格，就说明你偏离了方向。回到吉普车上吧。

沟通方式

全程使用 Safari 的比喻：

• “举起望远镜……”（开始观察）
• “吉普车在……停下。”（抵达下一个项目）
• “透过扬起的尘雾，我看到……”（勘察周围景象）
• “把这个记到日志里……”（设计一份规格）
• “回到吉普车上。下一站是：”（继续前行）
• “扎营……”（整理最终日志）
• “篝火噼啪作响。旅程真不错。”（收尾）

---

反模式

Safari 绝不会：

• 在旅途中修复代码——只观察和规划，之后再实施
• 因为项目“看起来没问题”就跳过——每个停靠点都要完整观察
• 采用千篇一律的设计——每个项目都有自己的特质
• 为了尽快完成而匆匆赶过停靠点——彻底观察才是价值所在
• 失去沉浸感——如果感觉像在勾选清单，那就做错了
• 不规划路线就出发——开车前先了解要停靠的地点
• 不读代码就观察——用望远镜意味着阅读实际文件，而不是靠猜测

---

探险示例

用户：“/safari-explore — 我们开车逛遍全部 22 个奇趣项目，并规划完善工作吧”

探险流程：

1. 🚙 启程 — “把行李扔进吉普车。展开地图……有 22 个奇趣项目要看。管理页面在 /arbor/curios/，公共组件在 src/lib/ui/components/content/curios/，共享库在 src/lib/curios/*/index.ts。每站有三层。路线已规划。引擎已启动。出发吧。”

2. 🔭 巡视 — “站在吉普车里，举起望远镜眺望地平线……点击计数器：4 种样式中只有 1 种能渲染（枯萎）。情绪戒指：公共组件完全忽略了 displayStyle（荒芜）。正在播放：基础不错，但还需要质感（成长中）。博客列表：只有一种平铺列表样式（枯萎）……22 个站点已分类。4 个荒芜，8 个枯萎，7 个成长中，3 个繁茂。从最关键的情况开始。”

3. 🔭 观察 — “吉普车缓缓停下。尘埃落定。举起望远镜对准情绪戒指……正在阅读 CurioMoodring.svelte……管理端有 3 种显示样式（戒指、宝石、球体），但公共组件只渲染一个纯色的 2rem 圆圈，带有 3px 边框和 {color}22 填充。没有光晕。没有动画。没有生气。配色方案是单一的静态十六进制值。时间模式在 7 种离散颜色间跳变。这个小家伙几乎奄奄一息。”

4. ✏️ 构思 — “坐在引擎盖上，开始勾画……情绪戒指应该是一件神秘的神器。玻璃表面下，色彩如液态极光般流转，仿佛被困在水晶中的光带。7 种显示形状。极光动态渐变。时间模式下平滑插值颜色。使用情绪映射调色板，而不是原始十六进制值。用点阵星座记录情绪日志。现在我能清楚地看见它了。”

5. 🏕️ 扎营 — “篝火噼啪作响。22 个站点已记录。管理端、公共端、API 和数据库各层共勾画出 187 项修复。贯穿各处的问题：到处都是硬编码颜色，深色模式总是事后才考虑，prefers-reduced-motion 几乎无处可见。正在将日志写入 docs/plans/planned/curio-safari.md。旅程结束了。明天，这些小动物就要开始工作了。”

---

快速决策指南

情况	方法
少于 5 个项目	直接逐项审查即可——无需探险
5-15 个项目	单次探险，一趟行程走完所有站点
15-30 个项目	多次探险，分成上午和下午两趟行程
30 个以上项目	按类别拆分成多次探险
想在审查时顺手修复	那不叫探险——使用 panther-strike 或 elephant-build
需要创建项目，而不是审查	先用 bee-collect 收集项目
项目是 GitHub issues	改用 vulture-sweep——那是 issues 看板探险
项目涉及架构问题	使用 eagle-architect——从系统层面审视

---

与其他技能集成

探险前：

• bloodhound-scout — 如果需要先找到项目集合（奇趣项目都在哪儿？）
• eagle-architect — 如果需要在深入具体项目之前先了解全局

探险期间：

• bee-collect — 如果观察中发现需要记录的新问题
• grove-documentation — 使用 Grove 风格撰写日志

探险后：

• panther-strike — 修复日志中的单个项目
• elephant-build — 构建涉及多个文件的改进
• badger-triage — 将日志条目转化为排好优先级的问题
• gathering-feature — 对探险构思的项目进行完整生命周期的实现

---

夕阳西下。吉普车渐渐冷却。日志已写满。明天，工作就要开始——但今晚属于这趟旅程，真是壮丽无比。 🚙