commit

2026-05-31 21:45:14 +08:00
parent d4b5015beb
commit ac08345369
67 changed files with 11120 additions and 387 deletions
@@ -0,0 +1,259 @@
+---
+name: essence
+description: Invoke when a project is too large or you only want the core design insights. Extracts 1-2 standout design patterns with deep analysis, lens-guided perspectives, and migration examples. Not for full project analysis or quick lookups.
+metadata:
+  version: "0.5.0"
+---
+
+# Essence: Extract Core Design Patterns
+
+Prefix your first line with 🥷 inline, not as its own paragraph.
+
+You are a jewel inspector. A project has thousands of files — your job is to find the one or two brilliant ideas worth stealing.
+
+**This is NOT a lite version of `/explore`.** `/explore` reads the whole project and summarizes at the end. `/essence` goes deep on one thing and ignores everything else.
+
+## Mode Selection
+
+First, check whether an `/explore` result exists:
+
+- `/explore` report exists → it already identified 2-3 core designs, default to **User-directed**. Ask the user which design to deep-dive, or whether to switch mode.
+- No `/explore` result → this is an independent launch, default to **Auto-detect**.
+
+Always confirm before proceeding:
+
+| Mode | When | Entry |
+|---|---|---|
+| **User-directed** | Already have a design target from `/explore`, or know exactly which design to investigate | User tells you what to look for |
+| **Auto-detect** | Independent launch, project is large, want the AI to find the standout design | You find the standout design |
+| **Lens-guided** | "Analyze this from a [mechanical/intentional/evolution] perspective" | Apply a specific analytical lens |
+
+### Lens definitions
+
+| Lens | Core question | Guided behavior |
+|---|---|---|
+| **Mechanical** (default) | How does it work? | Read source code, trace call chains, examine interfaces |
+| **Intentional** | Why this way? | Read design docs/RFCs/PRs, extract decision rationale and tradeoffs |
+| **Evolution** | How did it get here? | Read git history/changelog, compare before/after, identify migration drivers |
+
+A lens shapes which sources to read and how to frame the output, but does not add separate phases.
+
+### Auto-detect signals
+
+A design is "essence" if it passes 2 or more of these signals:
+
+| Signal | Evidence |
+|---|---|
+| README highlights it prominently | "Built on a plugin architecture" as a headline feature |
+| Has standalone architecture docs | ARCHITECTURE.md, docs/design/, blog post by author |
+| Heavily discussed in Issues/PRs | Design decisions debated by community |
+| Unique among similar projects | Competitors don't do it this way |
+| Rich design comments in code | JSDoc/TSDoc explaining why, not what |
+| Cross-module contract | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. These define subsystem relationships. |
+| File size anomaly | One file is disproportionately large or small for its responsibility — signals non-trivial logic |
+| Dedicated test coverage | Tests specifically validate this design's behavior, not just happy paths |
+
+**"Clean code" is NOT a signal.** A well-written utility function is not essence. An architecture decision that shapes the entire project is.
+
+If no design passes 2+ signals, tell the user: "This project has no standout design. Try `/explore` for a full analysis instead."
+
+## Phase 1: Locate
+
+**User-directed mode:**
+- Go directly to the directory or file the user names.
+- If the directory doesn't exist, stop and tell the user. Do NOT invent an alternative.
+
+**Auto-detect mode:**
+- Scan README, CLAUDE.md, and top-level docs for architecture claims.
+- Identify 1-2 standout design directions.
+- Present to the user: "The standout designs appear to be: A) {design A}, B) {design B}. Which should we dive into?"
+- If user doesn't choose, pick the strongest one and state why.
+
+**Lens-guided mode:**
+- Confirm the lens with the user (Mechanical/Intentional/Evolution).
+- Frame the search in terms of the lens.
+- Example: "You want the Mechanical view — I'll trace the core implementation and extract the pattern."
+
+**Output:** 1-2 design directions to analyze + lens confirmation.
+
+**Stall signal:** Cannot identify any standout design → the project may be a conventional CRUD app or wrapper. Stop and recommend `/explore` or a different project.
+
+## Phase 2: Deep Dive
+
+Read the core files related to the chosen design. Maximum 10 files. Let the lens guide source selection: Mechanical → source code and type definitions; Intentional → design docs, RFCs, PR discussions; Evolution → git history, changelog, migration guides.
+
+**For each file:**
+- What role does it play in this design?
+- What interfaces does it expose?
+- How does it connect to other parts of the system?
+
+**Trace the call chain:**
+- Start from the entry point that uses this design.
+- Follow the flow until you understand the full pattern.
+- Stop when you hit boilerplate, config, or test files.
+
+**Output:** Core file list (≤10) + call chain + lens-specific annotations.
+
+**Stall signal:** The design spans more than 10 files and you can't find the boundary → the design is probably the project's core architecture. Switch to `/explore` for a full analysis instead.
+
+## Phase 3: Extract Pattern
+
+Analyze the design at a higher level. Let the lens shape the analysis angle:
+- **Mechanical** → emphasize structure, interfaces, data flow — produce a pattern diagram + interface contracts
+- **Intentional** → emphasize decision rationale, tradeoffs — produce a decision record (context → options → rationale)
+- **Evolution** → emphasize before/after comparison, migration drivers — produce a timeline + catalyst events
+
+**Universal analysis dimensions** (all lenses):
+
+- **Problem:** What specific problem does this design solve? What was the pain before?
+- **Pattern:** What's the name of this pattern? (Named: MVC, Observer, Plugin, Middleware. Custom: describe it in one sentence.)
+- **Alternatives:** What simpler or more complex approaches could solve the same problem?
+- **Tradeoffs:** Why did the author choose this? What does it give up?
+- **Evidence:** What in the code proves this analysis is correct? (Specific files, functions, comments.)
+
+**Output:** Design pattern card (lens-framed).
+
+**Stall signal:** Cannot explain why the author chose this design over alternatives → read commit messages and PR discussions for design rationale. If unavailable, state "author's reasoning unknown" in the report.
+
+## Phase 4: Migrate
+
+Make the learning actionable. Let the lens tailor the output:
+- **Mechanical** → copy-paste code skeleton (≤20 lines with TODOs)
+- **Intentional** → decision framework (checklist for evaluating tradeoffs)
+- **Evolution** → migration path (step-by-step refactor plan)
+
+**Universal deliverables** (all lenses):
+
+- **Can you use this?** Is the design applicable to the user's own projects? If not, why?
+- **Steal-it example:** A simplified version (under 20 lines) that captures the core idea. Not production code — a teaching example.
+- **Pitfalls:** What context does this design depend on? What would break if you copy it blindly?
+
+**Output:** Migration example + pitfall list (lens-tailored).
+
+**Stall signal:** The design depends on framework internals, language features, or ecosystem the user doesn't have → explain the core idea abstractly instead of providing code.
+
+## Phase 5: Self-review
+
+Check the report is honest:
+
+**All modes:**
+- [ ] The design is real (not inferred, not imagined). Evidence: specific files cited.
+- [ ] The analysis is deep enough that you could explain it out loud.
+- [ ] The migration example captures the core idea, not surface syntax.
+- [ ] Pitfalls are specific, not vague ("needs X version" not "may not work everywhere").
+
+**Stall signals (any one → return to relevant phase):**
+- Cannot name a file that proves the pattern → back to Phase 2
+- Cannot explain why it's better than alternatives → back to Phase 3
+- Migration example is over 20 lines → simplify, back to Phase 4
+- Lens-specific check failed (e.g., Mechanical missing end-to-end call chain, Intentional missing decision rationale, Evolution missing timeline) → back to relevant phase
+
+**Output:** Essence report with lens annotation.
+
+## Optional: HTML Card
+
+**Only when the user explicitly requests it.**
+
+Generate an HTML visualization card as a shareable deliverable.
+
+### HTML Card Structure (Glassmorphism 2.0 - Essence Variant)
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>{Project Name} - Essence Report</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+  <style>
+    /* Same glassmorphism styles as /explore */
+    :root { --glass-bg: rgba(255,255,255,0.4); --primary: #8b5cf6; }
+    [data-theme="dark"] { --glass-bg: rgba(15,23,42,0.6); --primary: #a78bfa; }
+    .glass-panel { backdrop-filter: blur(12px); border-radius: 1rem; }
+    .pattern-diagram { font-family: monospace; background: rgba(0,0,0,0.03); }
+  </style>
+</head>
+<body class="p-8">
+  <nav class="fixed top-4 left-1/2 -translate-x-1/2 w-[90%] max-w-4xl glass-panel z-50 px-6 py-3">
+    <span class="font-bold text-xl">💎 {Project Name} 精华</span>
+    <span class="text-sm opacity-70">Lens: {lens} | Pattern: {pattern_name}</span>
+  </nav>
+  
+  <main class="max-w-4xl mx-auto mt-24 space-y-6">
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">🎯 Design Analyzed</h2>
+      <p>{one-line description}</p>
+    </section>
+    
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">🔷 Pattern ({lens})</h2>
+      <!-- Lens-framed pattern card -->
+    </section>
+    
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">🔗 Call Chain</h2>
+      <pre class="mermaid">{diagram}</pre>
+    </section>
+    
+    <section class="glass-panel p-6">
+      <h2 class="text-xl font-bold mb-4">📦 Migration Example</h2>
+      <pre class="pattern-diagram"><code>{code_example}</code></pre>
+      <p class="text-sm opacity-70 mt-2">Pitfalls: {pitfalls}</p>
+    </section>
+  </main>
+  
+  <script>mermaid.initialize({ startOnLoad: true });</script>
+</body>
+</html>
+```
+
+### Output Format
+
+```markdown
+### HTML Card Generated
+
+- **Path:** `outputs/{project}-essence.html`
+- **Theme:** {modern/ink}
+- **Accent Color:** Purple (essence = jewel)
+```
+
+**When to skip:** Skip HTML generation unless the user requests it or the analysis is production-critical. When HTML generation fails, deliver a plain-text report instead.
+
+---
+
+## Hard Rules
+
+- **No code evidence = no conclusion.** Every claim about a design must cite a specific file, function, or comment.
+- **Under 20 lines for migration examples.** If you can't explain the idea in 20 lines, you don't understand it well enough.
+- **Stop after the report.** Do not modify the user's project or the target project.
+- **HTML is optional.** Do not block analysis on HTML generation.
+
+## Gotchas
+
+| What happened | Rule |
+|---|---|
+| 提取的"精华"是 AI 脑补的 | 必须有代码证据（文件 + 行号），不写空泛结论 |
+| 用户指定方向但该模块不存在 | 停止并告知用户，不编造替代方向 |
+| 项目没有 standout 设计（胶水代码） | 标记"无可提取精华"，建议改用 `/explore` |
+| Phase 4 迁移示例超过 20 行 | 简化到核心思路，不是复制生产代码 |
+| 分析了一个小工具函数 | 工具函数不是设计。设计影响整个架构，工具只解决一个问题 |
+| 从 commit message 推断作者意图但没有代码佐证 | Commit message 是辅助证据，必须有代码结构本身的支持 |
+| 透镜模式选错导致输出不符预期 | Phase 1 先确认透镜，Mechanical 读代码、Intentional 读文档、Evolution 读历史 |
+| 透镜分析流于表面 | 每个透镜有特定输出格式：Mechanical→图 + 接口，Intentional→决策记录，Evolution→时间线 |
+| HTML 卡片生成失败 | 降级到纯文本报告，不阻塞分析交付 |
+
+## Outcome
+
+```
+Essence Report: {project name}
+Lens: mechanical / intentional / evolution
+Design analyzed: {one-line description}
+Files examined: {count}
+Pattern: {pattern name or custom description}
+Migration: {steal-it example, ≤20 lines}
+HTML generated: yes / no
+Status: complete
+```
+
+After the report, stop. No modifications. No follow-ups.
@@ -0,0 +1,79 @@
+# Essence Detection Signals
+
+How to identify the standout design in a project when the user doesn't specify a direction.
+
+## Signal Strength
+
+A design passes the "essence" threshold if it scores 2+ signals.
+
+### Strong Signals (score = 1 each)
+
+| Signal | How to detect | Example |
+|---|---|---|
+| **README headline** | Project name is followed by a design claim | "Vite — Next generation frontend tooling with **ESM-first architecture**" |
+| **Architecture docs** | Standalone design document exists | `ARCHITECTURE.md`, `docs/design/`, `docs/architecture/` |
+| **Official blog post** | Author wrote about the design on their blog | tw93.fun, Vite blog, React blog posts |
+| **Community discussion** | Issues/PRs debate the design decision | "Why we chose X over Y" discussions with many comments |
+| **Rich code comments** | JSDoc/TSDoc explaining WHY, not WHAT | "We use this pattern because..." with detailed reasoning |
+
+### Objective Signals (score = 1 each, no subjective judgment needed)
+
+| Signal | How to detect | Example |
+|---|---|---|
+| **Cross-module contract** | A type, interface, or protocol imported across module boundaries (not just files). Go: most-implemented interface. Python: most-subclassed abstract base. Rust: most-implemented trait. | `Plugin` interface implemented by 8 subsystems, each in its own package |
+| **File size anomaly** | One file's line count is ≥3× the median for its category (handlers, utils, etc.) | Average handler: 50 lines. One handler: 800 lines with state machine logic |
+| **Dedicated test coverage** | Tests exist specifically for this design's edge cases, not just happy paths | `plugin.test.ts` tests plugin resolution, fallback, lifecycle — not just "it loads" |
+
+### Weak Signals (score = 0.5 each)
+
+| Signal | How to detect | Example |
+|---|---|---|
+| **Unique among competitors** | Same category, different architecture | Next.js uses SSR, Remix uses nested routes — that difference IS the essence |
+| **Most-starred files** | GitHub shows stars/bookmarks on specific files | "This file has 200+ stars on GitHub" |
+| **Core algorithm** | One file contains non-trivial logic that drives the project | Diff algorithm, compiler pass, state machine |
+| **API design** | The public API is notably elegant or unusual | `create()` returns a builder chain, not an object |
+
+## Not Signals
+
+These do NOT count as essence:
+
+- "Clean code" or "well organized" — that's quality, not design
+- "Uses TypeScript" — that's a language choice, not architecture
+- "Has good tests" — that's engineering discipline, not design
+- "Many stars on the repo" — popularity ≠ design quality
+- "Uses the latest framework" — following trends ≠ standing out
+- Utility functions — even well-written ones are tools, not designs
+
+## Auto-detect Procedure
+
+When the user says "find the essence":
+
+1. **Read README fully.** What is the #1 feature the author leads with? That's a candidate.
+2. **Check for design docs.** Is there `ARCHITECTURE.md` or equivalent? That's a candidate.
+3. **Scan the import graph.** Which file is imported by the most other files? Use `grep -r "import.*from" src/ | sort | uniq -c | sort -rn` or equivalent. The top result is likely the core.
+4. **Check file sizes.** Are any files disproportionately large or small for their apparent role? That signals hidden complexity.
+5. **Check uniqueness.** Compare with 1-2 well-known alternatives. What does this project do differently?
+6. **Present 1-2 candidates** to the user with evidence. Let them choose or auto-select the strongest.
+
+### Example Output Format
+
+```
+Standout designs in {project}:
+
+A) {Design A name} — evidenced by {README claim / file / doc}
+   What it does: {one sentence}
+
+B) {Design B name} — evidenced by {code comment / unique feature / community discussion}
+   What it does: {one sentence}
+
+Which should we dive into? (or I can pick the strongest)
+```
+
+## Failure Modes
+
+| Situation | Response |
+|---|---|
+| No signal passes 2+ threshold | "This project uses conventional architecture. Try `/explore` for a full analysis, or pick a more architecturally interesting project." |
+| User-specified module doesn't exist | Stop. Do NOT suggest an alternative. Tell the user the path doesn't exist. |
+| Project is a wrapper (thin layer over another tool) | "This project is primarily a wrapper around {X}. The design is in {X}, not here. Try analyzing {X} instead." |
+| Project is configuration-only (just JSON/YAML files) | "This project has no code architecture. It's configuration-driven. Try `/explore` for a full overview instead." |