From 7e8ed389ff1eb8ae6be96b6b9a95b06092d3ed0f Mon Sep 17 00:00:00 2001 From: huangyong <13701062894@139.com> Date: Sun, 21 Jun 2026 16:41:34 +0800 Subject: [PATCH 1/2] feat: add Engineer Mode with 8 interactive elements and Source File Map Add comprehensive Engineer Mode for technical due diligence: - 8 new interactive elements: ADR Cards, Critical Path Trace, Trade-off Matrix, Scenario Judge, Integration Blueprint, Source File Map, Risk Indicators, Verdict Callout - Source File Map with framework/functional binary classification and recommended reading order - Code block style shifted to Code-Engineering Commentary translation blocks - Updated content philosophy and gotchas documentation - New CSS styles for all engineer-mode components - JavaScript interactions for Source File Map filtering and expansion --- SKILL.md | 171 +++++- references/content-philosophy.md | 66 ++ references/gotchas.md | 31 + references/interactive-elements.md | 666 ++++++++++++++++++++ references/main.js | 51 ++ references/styles.css | 933 +++++++++++++++++++++++++++++ 6 files changed, 1915 insertions(+), 3 deletions(-) diff --git a/SKILL.md b/SKILL.md index aedeb5b..baca5a8 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,11 +1,28 @@ --- name: codebase-to-course -description: "Turn any codebase into a beautiful, interactive single-page HTML course that teaches how the code works to non-technical people. Use this skill whenever someone wants to create an interactive course, tutorial, or educational walkthrough from a codebase or project. Also trigger when users mention 'turn this into a course,' 'explain this codebase interactively,' 'teach this code,' 'interactive tutorial from code,' 'codebase walkthrough,' 'learn from this codebase,' or 'make a course from this project.' This skill produces a stunning, self-contained HTML file with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations." +version: 2.0.0 +description: "Turn any codebase into a beautiful, interactive HTML guide. Two modes: 'beginner mode' for non-technical people, 'engineer mode' for developers doing technical due diligence — architecture decisions, critical paths, limitations, and integration analysis." +description_zh: "将任意代码库转化为精美的交互式 HTML 指南。两种模式：'入门模式'面向非技术人员，'工程师模式'面向开发者做技术选型——架构决策、关键路径、局限分析、集成评估。" +category: education --- # Codebase-to-Course -Transform any codebase into a stunning, interactive course. The output is a **directory** containing a pre-built `styles.css`, `main.js`, per-module HTML files, and an assembled `index.html` — open it directly in the browser with no setup required (only external dependency: Google Fonts CDN). The course teaches how the code works through scroll-based modules, animated visualizations, embedded quizzes, and plain-English translations of code. +Transform any codebase into a stunning, interactive guide. Supports **two modes** that produce fundamentally different outputs: + +- **Beginner Mode** (default) — Teaches non-technical people how the code works, using metaphors, plain-language explanations, and interactive visualizations. +- **Engineer Mode** — Deep technical analysis for developers doing due diligence on an open-source project. Focuses on architecture decisions, critical code paths, limitations, performance characteristics, and integration patterns. + +The output is a **directory** containing a pre-built `styles.css`, `main.js`, per-module HTML files, and an assembled `index.html` — open it directly in the browser with no setup required (only external dependency: Google Fonts CDN). + +## Mode Detection + +When the skill is triggered, determine which mode to use: + +- **Engineer Mode triggers:** User mentions "engineer mode", "工程师模式", "technical analysis", "技术分析", "deep dive", "深度分析", "code review", "for developers", "面向开发者", "技术选型", "evaluation", "评估", "架构分析", "architecture analysis", or explicitly says they are a developer/engineer evaluating the project. +- **Beginner Mode triggers:** User mentions "course", "课程", "tutorial", "教程", "explain simply", "简单解释", "for beginners", "入门", or does NOT specify a mode (default). + +If ambiguous, ask the user: "这个分析是面向工程师做技术选型（工程师模式），还是面向非技术人员理解代码（入门模式）？" ## First-Run Welcome @@ -22,7 +39,17 @@ When the skill is first triggered and the user hasn't specified a codebase yet, If the user provides a GitHub link, clone the repo first (`git clone /tmp/`) before starting the analysis. If they say "this codebase" or similar, use the current working directory. -## Who This Is For +**For Engineer Mode**, adjust the welcome message: + +> **我可以对任意开源项目做深度技术分析——帮你在引入项目之前看清它的架构、能力边界和集成可能性。** +> +> 给我一个项目： +> - **本地路径** — 如 "分析 ./my-project" +> - **GitHub 链接** — 如 "深度分析 https://github.com/user/repo" +> +> 我会逐行阅读核心代码，生成一份交互式技术分析报告，包含架构决策分析、关键代码路径追踪、性能与局限性评估、以及与其他项目的集成方案。 + +## Who This Is For (Beginner Mode) The target learner is a **"vibe coder"** — someone who builds software by instructing AI coding tools in natural language, without a traditional CS education. They may have built this project themselves (without looking at the code), or they may have found an interesting open-source project on GitHub and want to understand how it's built. Either way, they don't yet understand what's happening under the hood. @@ -50,6 +77,144 @@ The directory-based output is intentional: separating CSS/JS from content means --- +## Engineer Mode — 技术选型深度分析 + +When the user triggers Engineer Mode, **everything changes** — the audience, the curriculum, the interactive elements, the tone, and the analytical depth. Engineer Mode is NOT a "harder version" of Beginner Mode; it's a completely different product. + +### Who This Is For (Engineer Mode) + +The target reader is a **professional software engineer** evaluating whether to adopt an open-source project. They have: +- Solid CS fundamentals (data structures, design patterns, distributed systems) +- Experience with similar tools/frameworks in the same category +- The ability to read code — they don't need metaphors for basic concepts + +**What they need to answer:** +1. **"这个项目的设计决策合理吗？"** — Are the architectural choices sound? What were the alternatives? What trade-offs were made and why? +2. **"关键路径是怎么实现的？"** — Trace the most important code paths line by line. Which 50 lines of code carry 80% of the complexity? +3. **"它在我的场景下能工作吗？"** — What are the performance characteristics, limitations, and failure modes? What configurations matter? +4. **"它能和我的技术栈集成吗？"** — What are the integration points, extension mechanisms, and API contracts? How does it combine with other projects? +5. **"和竞品比，选它还是选别的？"** — Where does it excel, where does it fall short, and what decision framework should guide the choice? + +**Tone:** Senior engineer writing a technical due diligence report. Precise, honest, occasionally critical. No cheerleading — if something is a weakness, say so clearly. No hand-holding on basic concepts (don't explain what an API is). But DO explain project-specific conventions and domain-specific terms. + +### Engineer Mode Curriculum Structure + +Structure as **5-7 modules**, following the engineer's decision journey: + +| Module Position | Purpose | Key Question It Answers | +|---|---|---| +| 1 | **架构全景与技术栈** | "What is this project, what's the tech stack, and why was it built this way?" High-level architecture with explicit design philosophy. **Must include a Source File Map** — annotated directory tree classifying every key source file as framework or functional. | +| 2 | **关键路径深度追踪** | "When a complex request comes in, what EXACTLY happens?" Trace 1-2 core operations through every layer, with line-level code references. | +| 3 | **核心设计决策** | "What are the 3-5 most important architectural decisions?" For each: the problem, the chosen approach, alternatives considered, and trade-offs. | +| 4 | **性能特征与局限** | "Where does it break? What are the bottlenecks?" Honest assessment of performance, scalability, edge cases, and known limitations. | +| 5 | **扩展与定制** | "How do I extend it?" Plugin systems, hooks, configuration, subclassing patterns. Show the extension API with real examples. | +| 6 | **集成蓝图** | "How does it combine with other projects?" Concrete integration patterns, API contracts, data format compatibility. | +| 7 | **选型决策** | "Should I use this?" Comparison matrix vs alternatives, scenario-based recommendations, final verdict. | + +This is a **framework, not a template**. Adapt modules to the project's nature — a CLI tool might skip Module 6, a framework might emphasize Module 5, a library might expand Module 7. + +### Engineer Mode — Phase 1: Deep Analysis + +Beyond the standard codebase analysis, Engineer Mode requires **deeper extraction:** + +**Additional analysis requirements:** +- **Architecture Decision Records**: For each major design choice, extract: the problem it solves, the chosen approach, 2-3 alternatives that were NOT chosen, and why. Look for comments, ADR files, or infer from code structure. +- **Critical Path Code**: Identify and extract the 3-5 most important code paths (the ones that handle the core operations). Include exact file paths and line numbers. These become the "deep trace" screens. +- **Performance-relevant Code**: Find configuration parameters that affect performance (batch sizes, timeouts, concurrency limits, buffer sizes). Extract the code that implements throttling, caching, batching. +- **Extension Points**: Catalog all extension mechanisms — plugin interfaces, abstract base classes meant for subclassing, hook functions, event systems, configuration-driven behavior. +- **Failure Modes**: Search for error handling patterns, retry logic, fallback mechanisms, known issues (from comments, TODOs, issue references). +- **Integration Surface**: Map all external interfaces — REST APIs, SDK methods, data formats, protocol support, webhook systems. +- **Source File Classification**: For every key directory and file in the project, classify it as **framework** (structural/architectural — the skeleton that everything else hangs on) or **functional** (feature-specific — implements a particular capability). Extract file paths, sizes (LOC), and a one-line description of each. This becomes the Source File Map in Module 1. + +**Comparative context**: Read the project's README comparison section (if any), check if it mentions competitors, and note its self-positioning. + +### Engineer Mode — Module Design Principles + +- **Code is the evidence.** Every claim ("this project handles X well") must be backed by a specific code snippet with file path and line numbers. No hand-waving. +- **Show the alternatives.** For every major design decision, mention what could have been done differently and why it wasn't. This is what separates analysis from documentation. +- **Be honest about weaknesses.** Every project has them. Engineers trust analyses that acknowledge limitations. Use `callout-warning` for known issues. +- **Quantify when possible.** "Handles 10K documents/hour on a single GPU" beats "handles documents quickly." Extract benchmarks, performance tests, or compute estimates from the code. +- **Integration is actionable.** Don't just describe APIs — show concrete integration code examples (how to connect Project A's output to Project B's input). + +### Engineer Mode — Mandatory Interactive Elements + +**These elements are REQUIRED in every Engineer Mode guide (in addition to the standard set):** + +- **Architecture Decision Cards (ADR Cards)** — at least 3 across the guide. Each card shows: the problem, the chosen solution, 2-3 alternatives, the trade-off analysis, and the key code that implements it. +- **Critical Path Traces** — at least 2 across the guide. Step-by-step code walkthroughs of the most important operations, with engineering commentary explaining WHY each step exists, not just WHAT it does. +- **Trade-off Matrix** — at least 1 across the guide. A comparison table evaluating different approaches/configurations across multiple dimensions (performance, complexity, memory, accuracy). +- **Scenario Judge** — at least 1 across the guide. Present 3-4 real-world scenarios and evaluate the project's suitability for each, with honest pros/cons. +- **Integration Blueprint** — at least 1 across the guide (if the project has integration points). Show how data flows between this project and other systems, with code examples. +- **Source File Map** — exactly 1, placed in Module 1. An annotated directory tree that classifies every key source file/directory as "framework" (skeleton/architectural) or "functional" (feature implementation). This helps developers quickly orient themselves in the codebase — knowing which files to read first for architecture understanding vs which to read for feature implementation. + +**Standard elements still required:** Data Flow Animation, Quizzes (focused on engineering judgment), Code blocks (with engineering commentary, not plain-language translation), Glossary Tooltips (only for project-specific or domain-specific terms, not basic CS). + +### Engineer Mode — Code Block Style + +Instead of the Beginner Mode "Code ↔ Plain English" translation, Engineer Mode uses **Code ↔ Engineering Commentary:** + +- **Left panel**: Real code from the codebase (exact, unmodified) +- **Right panel**: Engineering analysis — WHY this code is written this way, what design pattern it implements, what trade-off it makes, what could go wrong, what alternative approaches exist. + +The right panel assumes the reader CAN read code. It adds value by providing context, analysis, and judgment that the code alone doesn't convey. + +**HTML pattern:** Use `translation-block` with the label changed from "PLAIN ENGLISH" to "工程分析" / "ENGINEERING ANALYSIS". + +### Engineer Mode — Quiz Design + +Quizzes test **engineering judgment**, not factual recall: + +**Good quiz questions:** +- "Your service needs to process 100K documents/hour. Based on the architecture, which configuration would you choose?" +- "The team wants to add a custom document parser. Based on the extension system, what's the correct approach?" +- "You've noticed search results are missing relevant documents. Based on the retrieval pipeline, where would you look first?" +- "Project A outputs format X, Project B expects format Y. What's the most reliable bridge?" + +### Engineer Mode — Design Differences + +- **More code per screen** — Allow larger code blocks (15-25 lines) when the analysis requires it. +- **Comparison tables** — Engineers think in trade-offs. Use tables to compare approaches, configurations, and alternatives. +- **"Verdict" callouts** — At the end of each module: "This approach is [strong/adequate/weak] for [scenario] because [reason]." +- **Risk indicators** — Use colored badges: 🟢 Low Risk, 🟡 Medium Risk, 🔴 High Risk for identified limitations and failure modes. + +### Engineer Mode — Source File Map + +Every Engineer Mode guide **must include a Source File Map** in Module 1 (架构全景). This is an annotated directory tree that classifies each key source file/directory into one of two categories: + +- **框架性文件 (Framework)** — The skeleton. Abstract base classes, interfaces, configuration systems, plugin loaders, middleware, routing, dependency injection, lifecycle management. These files define HOW the project is structured. Reading them gives you the architecture. Examples: `base.py`, `registry.py`, `settings.py`, `__init__.py` (with imports), `pipeline.py` (base class), `factory.py`. + +- **功能性文件 (Functional)** — The flesh. Concrete implementations of specific features, specific parsers, specific models, specific API endpoints. These files define WHAT the project does. Reading them gives you the capabilities. Examples: `pdf_parser.py`, `ocr_model.py`, `openai_llm.py`, `chunk_app.py`, `table_recognizer.py`. + +**Classification rules:** +- A file that defines abstract interfaces → Framework +- A file that implements a specific feature against those interfaces → Functional +- A file that wires things together (factory, registry, config loader) → Framework +- A file that contains business logic for one use case → Functional +- Entry points (`main.py`, `app.py`, `cli.py`) → Framework (they define the startup architecture) +- Test files → Functional (they test specific features), but skip listing individual tests +- Config/Schema files → Framework (they define the configuration contract) + +**What to show:** +- Top 30-50 most important files/directories (don't list every file — focus on the ones a developer would actually need to read) +- For each: file path, role tag (框架/功能), one-line description, approximate LOC +- Group by directory, with directory-level summaries +- Highlight the "start here" files — the 3-5 files a developer should read first to understand the architecture +- Use the existing `file-tree` visual element, enhanced with role badges + +**Why this matters:** Developers approaching a new codebase don't start from architecture diagrams — they start from the file listing. A Source File Map bridges the gap: "I see 500 files, but which 5 should I read first to understand how this works?" Without it, the analysis feels abstract ("看山不见山" — seeing the mountain but not understanding its composition). + +### Engineer Mode — Module 7: Selection Decision Framework + +If the guide includes a comparison/selection module (Module 7), it should contain: + +1. **Capability Matrix** — Feature-by-feature comparison with 2-3 alternatives in the same category. +2. **Scenario Recommendations** — "If your use case is X, choose this project. If Y, consider alternative Z instead." +3. **Integration Map** — If analyzing multiple related projects, show how they can be combined and which combinations make sense. +4. **Migration Path** — If the engineer is currently using a different tool, what does migration look like? +5. **Final Verdict** — A clear, opinionated recommendation with caveats. + +--- + ## The Process ### Phase 1: Codebase Analysis diff --git a/references/content-philosophy.md b/references/content-philosophy.md index 79fae1a..41d36f2 100644 --- a/references/content-philosophy.md +++ b/references/content-philosophy.md @@ -87,3 +87,69 @@ The goal of learning is practical application — being able to *do something* w **How many quizzes:** One per module, placed at the end after the learner has seen all the content. 3-5 questions per quiz. Each question should make the learner pause and *think*, not just pick the obvious answer. **Deciding what concepts are worth quizzing:** Quiz the things that would actually help someone in practice — architecture understanding ("where does this logic live and why?"), debugging intuition ("what would cause this symptom?"), and decision-making ("what's the tradeoff here?"). If a concept won't help someone debug a problem, steer an AI assistant, or make an architectural decision, it's not worth quizzing. + +--- + +## Engineer Mode — Content Philosophy + +When writing Engineer Mode content, the core principles shift. The audience is a professional engineer, and the goal is to provide actionable technical intelligence, not to teach fundamentals. + +### Code as Evidence, Not Illustration + +In Beginner Mode, code snippets illustrate concepts. In Engineer Mode, **every claim must be backed by code**. If you write "the retrieval pipeline uses hybrid search," show the exact function that implements it with file path and line numbers. No hand-waving. The engineer reading this will open the file to verify — make sure they find exactly what you described. + +**Critical: Use original code exactly as-is.** Never modify, simplify, or trim code. But unlike Beginner Mode (5-10 lines), Engineer Mode allows **15-25 lines** when the analysis requires it. The reader can read code — don't waste their time with artificially shortened snippets that lose context. + +### Engineering Commentary, Not Plain English + +Replace "Code ↔ Plain English" with **Code ↔ Engineering Commentary**. The right panel assumes the reader CAN read code. It adds value by answering: +- **WHY** is this code written this way? What design pattern? What trade-off? +- **What could go wrong?** Edge cases, failure modes, performance implications. +- **What are the alternatives?** How else could this have been done? Why wasn't it? +- **What's the history?** Git blame patterns, version evolution, deprecation risks. + +### Show the Alternatives + +For every major design decision, mention what could have been done differently and why it wasn't. This is what separates analysis from documentation. Use ADR Cards to structure this comparison: problem → chosen approach → 2-3 alternatives → trade-off analysis. + +**Critical: Alternatives must be genuine.** Don't create strawman alternatives to make the chosen approach look good. Engineers will see through this instantly and lose trust in the entire analysis. + +### Be Honest About Weaknesses + +Every project has limitations. Engineers trust analyses that acknowledge them. Use `callout-warning` for known issues. Use risk indicators (🔴 High / 🟡 Medium / 🟢 Low) for failure modes. Be specific: + +- **BAD**: "Performance may vary depending on the use case." +- **GOOD**: "Single-node deployment caps at ~50 QPS for hybrid retrieval. Beyond this threshold, P99 latency exceeds 2 seconds. See `src/search/hybrid_searcher.py:142` for the bottleneck in the reranking stage." + +### Quantify When Possible + +"Handles documents quickly" is useless. "Parses a 50-page PDF in ~8 seconds on a single T4 GPU, with DeepDoc consuming ~3.2 GB VRAM" is actionable. Extract benchmark results, configuration defaults, resource requirements from the code. If no benchmarks exist in the codebase, estimate from the algorithm complexity and model sizes. + +### Integration is Actionable + +Don't just describe APIs — show **concrete integration code**. "Project A outputs format X, here's 10 lines of code that bridge it to Project B's input format Y." Engineers evaluating integration potential need to see the data format compatibility, the API contract, and the edge cases — not just a diagram. + +### Verdict Every Module + +At the end of each module, provide a clear, opinionated verdict callout. "This architecture is strong for X because Y. It is weak for Z because W. If your use case is V, consider alternative Q." Never hedge with "it depends" without saying what it depends ON. + +### Less Glossary, More Domain Terms + +In Engineer Mode, don't tooltip basic CS concepts (API, DOM, async). DO tooltip: +- **Project-specific terms** (e.g., "DeepDoc" in RAGFlow, "middle_json" in MinerU) +- **Domain-specific concepts** the engineer may not know (e.g., "NMS threshold" in document OCR, "HyDE" in retrieval) +- **Configuration parameters** with performance implications + +### Engineer Mode Quiz Design + +Quizzes test **engineering judgment**, not factual recall: + +**Good quiz questions:** +- "Your service needs to process 100K documents/hour. Based on the architecture, which configuration would you choose?" +- "You've noticed search results are missing relevant documents. Based on the retrieval pipeline, where would you look first?" +- "The team wants to add a custom document parser. Based on the extension system, what's the correct approach?" + +**What NOT to quiz:** +- API names or function signatures (they can look at the code) +- Basic CS concepts (they already know) +- File paths (nobody memorizes these) diff --git a/references/gotchas.md b/references/gotchas.md index e69c1fc..249089b 100644 --- a/references/gotchas.md +++ b/references/gotchas.md @@ -30,3 +30,34 @@ Trying to write all modules in one pass causes later modules to be thin and rush ### Missing Interactive Elements A module with only text and code blocks, no interactivity. Every module needs at least one of: quiz, data flow animation, group chat, architecture diagram, drag-and-drop. These aren't decorations — they're how non-technical learners actually process information. + +--- + +## Engineer Mode — Additional Gotchas + +### Strawman Alternatives in ADR Cards +Presenting obviously inferior alternatives to make the chosen approach look brilliant. Engineers will spot this instantly and lose trust in the entire analysis. **Fix:** Every alternative must be a genuine option that a reasonable team might have chosen. Show the real trade-offs — sometimes the alternative is better in specific dimensions. + +### Vague Performance Claims +Writing "handles large workloads efficiently" or "good performance" without specifics. Engineers need numbers. **Fix:** Extract actual configuration defaults, benchmark results, batch sizes, and resource requirements from the code. If the codebase has no benchmarks, estimate from algorithm complexity, model sizes, and configuration parameters. Include file paths and line numbers for every performance-relevant setting. + +### Cheerleading Without Criticism +Only highlighting strengths while ignoring or downplaying weaknesses. This is the #1 trust-killer for Engineer Mode content. **Fix:** Every module must include at least one `callout-warning` or risk indicator for a genuine limitation. If you can't find any weaknesses, you haven't looked deep enough. + +### Missing Code References +Making architectural claims without pointing to the specific code that implements them. **Fix:** Every claim about architecture, performance, or design must be accompanied by at least one code snippet with exact file path and line numbers. No hand-waving. + +### Over-Tooltipping Basic Concepts +In Engineer Mode, tooltiping terms like "API", "async", "middleware", or "callback" insults the reader's intelligence and clutters the page. **Fix:** Only tooltip project-specific terms, domain-specific jargon, and configuration parameters. Assume the reader has solid CS fundamentals. + +### Non-Actionable Integration Sections +Describing integration points abstractly ("Project A can work with Project B via their REST API") without showing actual code. **Fix:** Every integration description must include a concrete code example showing how to bridge the two systems. Include data format conversions, API calls, and error handling. + +### Missing Verdicts +Ending a module without a clear, opinionated recommendation. Engineers read these analyses to make decisions — if every section ends with "it depends," they learn nothing. **Fix:** Every module must end with a verdict callout that gives a clear recommendation for specific scenarios. + +### Scenario Judge Without Honesty +Marking every scenario as "excellent fit" because the analysis is supposed to be positive. **Fix:** Include at least one "not recommended" scenario per guide. Suggest alternative tools or combination approaches. This honesty builds trust and is genuinely useful for the engineer. + +### Trade-off Matrix Without Real Trade-offs +Creating comparison tables where one approach wins on every dimension. **Fix:** Every approach in a trade-off matrix should win on at least one dimension. If an approach loses on every dimension, it shouldn't be in the comparison — or you haven't analyzed it fairly. diff --git a/references/interactive-elements.md b/references/interactive-elements.md index 62ef616..3d50365 100644 --- a/references/interactive-elements.md +++ b/references/interactive-elements.md @@ -22,6 +22,14 @@ Implementation patterns for every interactive element type used in courses. Pick 15. [Visual File Tree](#visual-file-tree) 16. [Icon-Label Rows](#icon-label-rows) 17. [Numbered Step Cards](#numbered-step-cards) +18. [ADR Cards (Engineer Mode)](#adr-cards-engineer-mode) +19. [Trade-off Matrix (Engineer Mode)](#trade-off-matrix-engineer-mode) +20. [Scenario Judge (Engineer Mode)](#scenario-judge-engineer-mode) +21. [Integration Blueprint (Engineer Mode)](#integration-blueprint-engineer-mode) +22. [Risk Indicators (Engineer Mode)](#risk-indicators-engineer-mode) +23. [Verdict Callout (Engineer Mode)](#verdict-callout-engineer-mode) +24. [Critical Path Trace (Engineer Mode)](#critical-path-trace-engineer-mode) +25. [Source File Map (Engineer Mode)](#source-file-map-engineer-mode) --- @@ -943,3 +951,661 @@ For sequences that would otherwise be a numbered paragraph list. Visual, scannab } .step-body p { margin: var(--space-1) 0 0; color: var(--color-text-secondary); font-size: var(--text-sm); } ``` + +--- + +## Engineer Mode Interactive Elements + +The following elements are **exclusive to Engineer Mode** and are required in every Engineer Mode guide. They replace or supplement the Beginner Mode elements to serve the professional engineer audience. + +--- + +## ADR Cards (Engineer Mode) + +Architecture Decision Record cards — the most important Engineer Mode element. Each card presents one major design decision: the problem, the chosen solution, alternatives that were NOT chosen, and the trade-off analysis. + +**Wiring:** `main.js` auto-initializes every `.adr-card` on page load. Clicking the card toggles the expanded analysis section. Use `data-adr-id` for unique identification. + +**HTML:** +```html +
+
+ ADR #1 +

使用 Pipeline 模式统一处理多种文档格式

+

将不同格式的文档解析统一为 pipeline 抽象，而不是为每种格式写独立处理逻辑。

+ +
+ +
+``` + +**Rules:** +- At least 3 ADR cards across the entire guide +- Each card must reference specific code with file path and line numbers +- Alternatives must be genuine — don't create strawman alternatives to make the chosen approach look good +- The trade-off table must be honest — if the chosen approach has weaknesses, show them +- Use Chinese or English depending on the guide's language + +--- + +## Trade-off Matrix (Engineer Mode) + +A structured comparison table evaluating different approaches, configurations, or tools across multiple dimensions. Engineers think in trade-offs — this element makes the trade-off space explicit. + +**HTML:** +```html +
+

方案对比：文档解析策略

+

不同解析策略在准确率、速度、资源消耗上的权衡

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
维度传统 Pipeline
多模型组合		VLM 解析
视觉语言模型		混合模式
规则 + 模型
解析准确率高（结构化文档）高（复杂排版）中高
处理速度快（~2s/页）慢（~15s/页）中（~5s/页）
GPU 内存2-4 GB16-24 GB8-12 GB
适用场景标准 PDF、扫描件复杂排版、多语言混排需要精确表格提取
+
+
+ 结论：对于大多数场景，传统 Pipeline 是性价比最高的选择。VLM 适合准确率优先且 GPU 资源充足的场景。混合模式是过渡方案。 +
+
+``` + +**Rules:** +- At least 1 per guide +- Always include a "verdict" row or section at the bottom with a clear recommendation +- Use color coding: `tradeoff-good` (green), `tradeoff-mid` (amber), `tradeoff-bad` (red) +- Dimensions should cover: performance, resource usage, complexity, accuracy, maintainability +- Data must come from actual code analysis (batch sizes, config defaults, benchmark results) + +--- + +## Scenario Judge (Engineer Mode) + +Present 3-4 real-world scenarios and evaluate the project's suitability for each. This helps engineers quickly determine if the project fits their use case. + +**Wiring:** `main.js` auto-initializes. Clicking a scenario card expands the detailed analysis. Use `onclick="toggleScenario(this)"`. + +**HTML:** +```html +
+

场景适配评估

+

评估此项目在典型使用场景下的适用度

+ +
+
+ 非常适合 +

企业内部知识库：处理 PDF/Word 文档，支持全文检索

+ ▾ +
+ +
+ +
+
+ 需要评估 +

实时聊天机器人：需要 <500ms 响应的客服场景

+ ▾ +
+ +
+ +
+
+ 不推荐 +

多模态文档处理：视频/音频转文本并建索引

+ ▾ +
+ +
+
+``` + +**Rules:** +- At least 1 per guide +- Include a mix: 1-2 "excellent fit", 1 "needs evaluation", 1 "not recommended" +- For "not recommended" scenarios, always suggest an alternative or combination approach +- Be specific about configurations and gotchas — don't just say "it works" or "it doesn't" + +--- + +## Integration Blueprint (Engineer Mode) + +Shows how data flows between this project and other systems. Includes concrete code examples for common integration patterns. + +**HTML:** +```html +
+

集成蓝图：与 LlamaIndex 组合使用

+

将本项目的文档解析能力与 LlamaIndex 的索引和查询能力结合

+ +
+
+
📄
+ 原始文档 +
+
→
+
+
⚙️
+ 本项目解析器 + PDF → 结构化 JSON +
+
→
+
+
🔗
+ 格式转换 + JSON → LlamaIndex Document +
+
→
+
+
🔍
+ LlamaIndex + VectorStoreIndex + 查询 +
+
+ +
+

桥接代码示例

+
+
+ INTEGRATION CODE + 

+from project import DocumentParser
+from llama_index.core import Document
+
+parser = DocumentParser(backend="pipeline")
+result = parser.parse("report.pdf")
+
+# 转换为本项目输出格式 → LlamaIndex Document
+documents = [
+    Document(
+        text=block.text,
+        metadata={"source": block.page_num}
+    )
+    for block in result.blocks
+    if block.type != BlockType.IMAGE
+]
+
+
+
+ 工程分析 +
+

直接使用项目 API 而非 CLI 调用——减少进程间通信开销

+

backend 参数可选 pipeline/vlm/hybrid，根据场景选择

+

解析结果为结构化的 block 列表，每个 block 有类型和位置信息

+

过滤掉 IMAGE 类型——LlamaIndex 的文本索引不处理图片，需要单独处理多模态

+

metadata 保留页码信息，方便后续引用溯源

+
+
+
+
+ +
+

兼容性注意事项

+
+ ⚠️ +

两个项目的 Python 版本要求可能冲突——本项目要求 3.10+，部分 LlamaIndex 集成包要求 3.9。建议使用 venv 隔离。

+
+
+ ℹ️ +

本项目输出的中间 JSON 格式可以通过 to_llamaindex() 工具函数直接转换（需安装 project[llamaindex] extra）。

+
+
+
+``` + +**Rules:** +- At least 1 per guide (if the project has integration points) +- Show REAL code, not pseudocode — the integration example must be runnable +- Include compatibility notes, version conflicts, and gotchas +- The flow diagram at the top gives the big picture; the code below makes it actionable + +--- + +## Risk Indicators (Engineer Mode) + +Colored badges that indicate the severity of identified risks, limitations, or failure modes. Use inline within text or in dedicated risk assessment sections. + +**HTML — inline usage:** +```html +

单节点部署时最大并发查询数约 50 QPS 🟡 中等风险，超过此阈值检索延迟显著上升。

+``` + +**HTML — risk assessment panel:** +```html +
+

风险评估

+
+
+ 🔴 高风险 +
+ 表格识别准确率 +

复杂嵌套表格的识别准确率约 70-80%，在生产环境中可能需要人工后处理。src/deepdoc/table_recognizer.py:156 中的 NMS 阈值硬编码为 0.3，无法通过配置调整。

+
+
+
+ 🟡 中等风险 +
+ Go 服务依赖 +

API 服务层用 Go 实现，Python 核心通过 gRPC 通信。这意味着调试需要同时理解两种语言的工具链，且 gRPC 序列化增加了约 5ms 的延迟。

+
+
+
+ 🟢 低风险 +
+ 模型版本锁定 +

ONNX 模型与特定版本绑定，升级需要重新验证。但有版本管理机制，且模型更新频率低（每季度一次）。

+
+
+
+
+``` + +**Rules:** +- Use throughout the guide wherever limitations or risks are mentioned +- 🔴 High Risk: Will cause production issues, requires mitigation strategy +- 🟡 Medium Risk: May cause issues in specific scenarios, has workarounds +- 🟢 Low Risk: Minor inconvenience, unlikely to cause production problems +- Always explain WHY the risk exists with a specific code reference + +--- + +## Verdict Callout (Engineer Mode) + +Summary judgment at the end of each module. Concise, opinionated, and actionable. + +**HTML:** +```html +
+
⚖️
+
+ 模块结论 +

Pipeline 架构设计合理且有前瞻性。统一接口 + 后端可插拔的模式在当前规模下是正确选择。唯一的结构性风险是 Pipeline 阶段之间耦合较紧——中间阶段的数据格式变更会影响所有下游阶段。

+
+ 建议：如果你需要自定义处理阶段，优先通过配置参数而非修改源码来实现。参考 pipeline_config.yaml 中的 stage_options。 +
+
+
+``` + +**Variants:** +- `verdict-positive`: green left border, for strong design decisions +- `verdict-mixed`: amber left border, for adequate but imperfect decisions +- `verdict-negative`: red left border, for weak or problematic design choices + +**Rules:** +- One verdict callout at the end of each module +- Must be opinionated — don't hedge with "it depends" +- Must include a concrete, actionable recommendation +- Reference specific code or configuration + +--- + +## Critical Path Trace (Engineer Mode) + +Step-by-step code walkthrough of the most important operations. Unlike Beginner Mode's flow animations, this shows actual code with engineering commentary explaining WHY each step exists. + +**HTML:** +```html +
+

关键路径：PDF 文档解析全流程

+

追踪一份 PDF 从上传到生成结构化文档的完整代码路径

+ +
+
+
+ 1 + api/upload.py:34-42 +
+
+
+
+ CODE + 

+async def upload_document(file: UploadFile):
+    content = await file.read()
+    doc_hash = hashlib.md5(content).hexdigest()
+    if cache.exists(doc_hash):
+        return cache.get(doc_hash)
+    task = parse_queue.enqueue(content, file.filename)
+    return {"task_id": task.id, "status": "queued"}
+
+
+
+ 工程分析 +
+

入口即异步——使用 async 避免阻塞事件循环，这对于同时处理多个上传请求至关重要

+

MD5 哈希做去重——相同文件不会重复解析，这对知识库场景是重要的优化。但注意：MD5 不适合安全场景，这里仅用于缓存键

+

入队而非同步处理——解析是 CPU/GPU 密集型任务，通过队列异步处理，API 立即返回 task_id。这是正确的设计——解析可能需要数十秒

+
+
+
+
+
+ +
+
+ 2 + parser/worker.py:78-95 +
+
+
+
+ CODE + 

+def process_task(task: ParseTask):
+    backend = select_backend(task.filename)
+    pipeline = PipelineFactory.create(backend)
+    result = pipeline.execute(task.content)
+    cache.store(task.doc_hash, result)
+    return result
+
+
+
+ 工程分析 +
+

后端自动选择——根据文件扩展名选择最合适的解析后端。这个决策是隐式的，调用方无需关心

+

工厂模式创建 Pipeline——PipelineFactory 封装了复杂的依赖注入逻辑。这增加了代码可读性，但让调试时需要多跳一层

+

结果缓存到持久化存储——与入口的 MD5 检查形成闭环

+
+
+
+
+
+
+
+``` + +**Rules:** +- At least 2 critical path traces per guide +- Each step must include real code from the codebase with exact file path and line numbers +- Engineering commentary explains WHY, not WHAT — assume the reader can read code +- Focus on the 3-5 most important code paths in the entire project +- Highlight design patterns, potential issues, and non-obvious decisions + +--- + +## Source File Map (Engineer Mode) + +An annotated directory tree that classifies each key source file/directory as **framework** (骨架/框架性) or **functional** (功能/功能性). This is the most important orienting element for developers — it answers "which files should I read first to understand how this project works?" + +**Wiring:** `main.js` auto-initializes every `.source-file-map` on page load. Directory nodes are expandable/collapsible via `onclick="toggleSfmDir(this)"`. Role filter buttons toggle visibility. + +**HTML:** +```html +
+
+

源码文件地图

+

项目核心源码分类：框架性 文件定义架构骨架，功能性 文件实现具体能力

+
+ + + + +
+
+ +
+
+ 47 + 核心文件 +
+
+ 12 + 框架文件 +
+
+ 35 + 功能文件 +
+
+ ~18K + 核心代码行 +
+
+ +
+ +
+
+ ▾ + rag/ + 框架 + RAG 核心框架层——定义检索增强的骨架 +
+
+ +
+ 📄 + settings.py + 框架 + ~280 LOC + 全局配置单例，定义所有可调参数 +
+ + +
+ 📄 + naive.py + 功能 + ~420 LOC + 通用文档分块实现，14 种模板策略 +
+ + +
+ 🚀 + __init__.py + 框架 + ~45 LOC + 模块入口，定义公开 API 和导入链 +
+ + +
+
+ ▸ + app/ + 功能 + 各文档类型的具体解析器实现 +
+ +
+
+
+ + +
+
+ ▸ + deepdoc/ + 框架 + 文档理解引擎——OCR、布局分析、表格识别的统一接口 +
+ +
+
+ +
+
+ 框架 + 定义项目骨架——抽象接口、配置系统、插件加载、生命周期管理。读这些文件理解架构。 +
+
+ 功能 + 实现具体能力——特定解析器、特定模型、特定 API。读这些文件理解功能边界。 +
+
+ 🚀 入口 + 程序启动点——main.py、cli.py、app.py。从这里开始追踪代码执行路径。 +
+
+ +
+

推荐阅读顺序

+
+
+ 1 + rag/settings.py + 先看全局配置，理解所有可调参数的默认值 +
+
+ 2 + deepdoc/vision/__init__.py + 理解模型层的抽象接口设计 +
+
+ 3 + rag/svr/task_executor.py + 核心执行引擎——文档解析的主循环在这里 +
+
+
+
+``` + +**Rules:** +- Exactly 1 Source File Map per guide, placed in Module 1 (架构全景) +- List the top 30-50 most important files/directories — not every file +- Every file/directory must be classified as framework or functional +- Include a "reading order" section: the 3-5 files a developer should read first to understand the architecture +- Use real file paths from the codebase (verify they exist) +- Approximate LOC counts are fine (don't need exact counts) +- Group files by their parent directory, with directory-level summaries +- The filter buttons (全部/仅框架/仅功能/入口文件) must work — this helps engineers focus on what they care about diff --git a/references/main.js b/references/main.js index 7150a69..1f47438 100644 --- a/references/main.js +++ b/references/main.js @@ -15,6 +15,10 @@ * - Architecture diagram * - "Spot the bug" challenge * - Layer toggle + * + * Engineer Mode engines: + * - ADR card toggle + * - Scenario Judge toggle */ (function () { 'use strict'; @@ -495,4 +499,51 @@ btn.classList.add('active'); }; + /* ── ADR CARD TOGGLE (Engineer Mode) ──────────────────────── */ + window.toggleADR = function (btn) { + const card = btn.closest('.adr-card'); + if (!card) return; + const body = $('.adr-body', card); + if (!body) return; + const isHidden = body.style.display === 'none' || body.style.display === ''; + body.style.display = isHidden ? 'block' : 'none'; + btn.textContent = isHidden ? '收起分析 ▴' : '展开分析 ▾'; + }; + + /* ── SCENARIO JUDGE TOGGLE (Engineer Mode) ─────────────────── */ + window.toggleScenario = function (headerEl) { + const card = headerEl.closest('.sj-card'); + if (!card) return; + const body = $('.sj-card-body', card); + if (!body) return; + const isHidden = body.style.display === 'none' || body.style.display === ''; + body.style.display = isHidden ? 'block' : 'none'; + card.classList.toggle('expanded', isHidden); + }; + + /* ── SOURCE FILE MAP (Engineer Mode) ───────────────────────── */ + window.toggleSfmDir = function (headerEl) { + const dir = headerEl.closest('.sfm-dir'); + if (!dir) return; + const children = $('.sfm-dir-children', dir); + if (!children) return; + const arrow = $('.sfm-arrow', headerEl); + const isHidden = children.style.display === 'none'; + children.style.display = isHidden ? 'block' : 'none'; + dir.classList.toggle('open', isHidden); + if (arrow) arrow.textContent = isHidden ? '▾' : '▸'; + }; + + window.filterSfm = function (btn, role) { + const map = btn.closest('.source-file-map'); + if (!map) return; + $$('.sfm-filter', map).forEach(f => f.classList.remove('active')); + btn.classList.add('active'); + if (role === 'all') { + map.removeAttribute('data-filter'); + } else { + map.setAttribute('data-filter', role); + } + }; + })(); diff --git a/references/styles.css b/references/styles.css index 544669c..70c8808 100644 --- a/references/styles.css +++ b/references/styles.css @@ -1193,3 +1193,936 @@ p:last-child { margin-bottom: 0; } 80% { opacity: 1; } to { left: var(--packet-to-x); top: var(--packet-to-y); opacity: 0; } } + +/* ============================================================= + ENGINEER MODE — ADDITIONAL STYLES + These styles support the Engineer Mode interactive elements. + They use the same design tokens as the base system. + ============================================================= */ + +/* ── ADR CARDS ──────────────────────────────────────────────── */ +.adr-card { + background: var(--color-surface); + border-radius: var(--radius-lg); + box-shadow: var(--shadow-md); + margin: var(--space-8) 0; + overflow: hidden; + border-left: 4px solid var(--color-accent); +} +.adr-header { + padding: var(--space-6); +} +.adr-badge { + display: inline-block; + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--color-accent); + background: var(--color-accent-light); + padding: var(--space-1) var(--space-3); + border-radius: var(--radius-sm); + margin-bottom: var(--space-3); +} +.adr-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-2); + line-height: var(--leading-snug); +} +.adr-summary { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-4); +} +.adr-toggle { + background: none; + border: 1px solid var(--color-border); + border-radius: var(--radius-sm); + padding: var(--space-2) var(--space-4); + font-family: var(--font-body); + font-size: var(--text-sm); + color: var(--color-accent); + cursor: pointer; + transition: all var(--duration-fast); +} +.adr-toggle:hover { + background: var(--color-accent-light); + border-color: var(--color-accent-muted); +} +.adr-body { + border-top: 1px solid var(--color-border-light); + padding: var(--space-6); +} +.adr-section { + margin-bottom: var(--space-6); +} +.adr-section:last-child { margin-bottom: 0; } +.adr-section-title { + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--color-text-muted); + margin-bottom: var(--space-3); +} +.adr-section p { + font-size: var(--text-sm); + color: var(--color-text-secondary); +} +.adr-code-ref { + background: var(--color-bg-warm); + border-radius: var(--radius-sm); + padding: var(--space-3) var(--space-4); + margin-top: var(--space-3); +} +.adr-file-ref { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #CBA6F7; + padding: var(--space-1) var(--space-2); + border-radius: 4px; +} +.adr-code-note { + font-size: var(--text-xs); + color: var(--color-text-muted); + margin-top: var(--space-2); +} +.adr-alternatives { + display: flex; + flex-direction: column; + gap: var(--space-3); +} +.adr-alt { + background: var(--color-bg-warm); + border-radius: var(--radius-sm); + padding: var(--space-4); + border-left: 3px solid var(--color-border); +} +.adr-alt-name { + display: block; + font-weight: 700; + font-size: var(--text-sm); + margin-bottom: var(--space-1); +} +.adr-alt-desc { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-2); +} +.adr-alt-verdict { + font-size: var(--text-xs); + font-weight: 600; + color: var(--color-text-muted); +} +.adr-tradeoff-table { + width: 100%; + border-collapse: collapse; + font-size: var(--text-sm); + margin-top: var(--space-3); +} +.adr-tradeoff-table th { + background: var(--color-bg-warm); + padding: var(--space-2) var(--space-3); + text-align: left; + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.05em; + border-bottom: 2px solid var(--color-border); +} +.adr-tradeoff-table td { + padding: var(--space-2) var(--space-3); + border-bottom: 1px solid var(--color-border-light); +} +.adr-good { color: var(--color-success); font-weight: 600; } +.adr-mid { color: var(--color-info); font-weight: 600; } +.adr-bad { color: var(--color-error); font-weight: 600; } + +/* ── TRADE-OFF MATRIX ───────────────────────────────────────── */ +.tradeoff-matrix { + background: var(--color-surface); + border-radius: var(--radius-lg); + padding: var(--space-8); + box-shadow: var(--shadow-md); + margin: var(--space-8) 0; +} +.tradeoff-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-2); +} +.tradeoff-desc { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-6); +} +.tradeoff-table-wrap { + overflow-x: auto; + -webkit-overflow-scrolling: touch; + margin: 0 calc(var(--space-4) * -1); + padding: 0 var(--space-4); +} +.tradeoff-table { + width: 100%; + border-collapse: collapse; + font-size: var(--text-sm); + min-width: 600px; +} +.tradeoff-table th { + background: var(--color-bg-code); + color: #CDD6F4; + padding: var(--space-3) var(--space-4); + text-align: center; + font-weight: 600; + font-size: var(--text-sm); +} +.tradeoff-table th:first-child { + text-align: left; + border-radius: var(--radius-sm) 0 0 0; +} +.tradeoff-table th:last-child { + border-radius: 0 var(--radius-sm) 0 0; +} +.tradeoff-sub { + display: block; + font-size: var(--text-xs); + font-weight: 400; + color: #9399B2; + margin-top: var(--space-1); +} +.tradeoff-table td { + padding: var(--space-3) var(--space-4); + border-bottom: 1px solid var(--color-border-light); + text-align: center; +} +.tradeoff-table td:first-child { + text-align: left; +} +.tradeoff-dim { + font-weight: 700; + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.05em; + white-space: nowrap; +} +.tradeoff-good { color: var(--color-success); font-weight: 600; } +.tradeoff-mid { color: var(--color-info); font-weight: 600; } +.tradeoff-bad { color: var(--color-error); font-weight: 600; } +.tradeoff-verdict { + margin-top: var(--space-6); + padding: var(--space-4); + background: var(--color-accent-light); + border-radius: var(--radius-sm); + font-size: var(--text-sm); + color: var(--color-text-secondary); + border-left: 3px solid var(--color-accent); +} + +/* ── SCENARIO JUDGE ─────────────────────────────────────────── */ +.scenario-judge { + margin: var(--space-8) 0; +} +.sj-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-2); +} +.sj-desc { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-6); +} +.sj-card { + background: var(--color-surface); + border-radius: var(--radius-md); + box-shadow: var(--shadow-sm); + margin-bottom: var(--space-3); + overflow: hidden; + border-left: 4px solid var(--color-border); + transition: border-color var(--duration-fast); +} +.sj-card[data-verdict="excellent"] { border-left-color: var(--color-success); } +.sj-card[data-verdict="caution"] { border-left-color: var(--color-info); } +.sj-card[data-verdict="poor"] { border-left-color: var(--color-error); } + +.sj-card-header { + display: flex; + align-items: center; + gap: var(--space-3); + padding: var(--space-4) var(--space-5); + cursor: pointer; + transition: background var(--duration-fast); +} +.sj-card-header:hover { background: var(--color-bg-warm); } +.sj-verdict { + font-family: var(--font-mono); + font-size: var(--text-xs); + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.05em; + padding: var(--space-1) var(--space-3); + border-radius: var(--radius-sm); + white-space: nowrap; + flex-shrink: 0; +} +.sj-excellent { background: var(--color-success-light); color: var(--color-success); } +.sj-caution { background: var(--color-info-light); color: var(--color-info); } +.sj-poor { background: var(--color-error-light); color: var(--color-error); } +.sj-scenario { + font-size: var(--text-sm); + font-weight: 600; + flex: 1; +} +.sj-toggle { + color: var(--color-text-muted); + font-size: var(--text-sm); + flex-shrink: 0; + transition: transform var(--duration-fast); +} +.sj-card.expanded .sj-toggle { transform: rotate(180deg); } + +.sj-card-body { + border-top: 1px solid var(--color-border-light); + padding: var(--space-5); +} +.sj-pros-cons { + display: grid; + grid-template-columns: 1fr 1fr; + gap: var(--space-4); + margin-bottom: var(--space-4); +} +.sj-pros h5, .sj-cons h5 { + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.1em; + margin-bottom: var(--space-2); +} +.sj-pros h5 { color: var(--color-success); } +.sj-cons h5 { color: var(--color-error); } +.sj-pros ul, .sj-cons ul { + list-style: none; + padding: 0; +} +.sj-pros li, .sj-cons li { + font-size: var(--text-sm); + color: var(--color-text-secondary); + padding: var(--space-1) 0; + padding-left: var(--space-4); + position: relative; +} +.sj-pros li::before { content: '+'; position: absolute; left: 0; color: var(--color-success); font-weight: 700; } +.sj-cons li::before { content: '!'; position: absolute; left: 2px; color: var(--color-error); font-weight: 700; } +.sj-config-tips { + background: var(--color-bg-warm); + border-radius: var(--radius-sm); + padding: var(--space-3) var(--space-4); + font-size: var(--text-sm); + color: var(--color-text-secondary); +} +.sj-config-tips code { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #A6E3A1; + padding: var(--space-1) var(--space-2); + border-radius: 4px; +} +.sj-reason { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-3); +} +.sj-alternative { + font-size: var(--text-sm); + color: var(--color-text-secondary); +} + +/* ── INTEGRATION BLUEPRINT ──────────────────────────────────── */ +.integration-blueprint { + background: var(--color-surface); + border-radius: var(--radius-lg); + padding: var(--space-8); + box-shadow: var(--shadow-md); + margin: var(--space-8) 0; +} +.ib-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-2); +} +.ib-desc { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-6); +} +.ib-flow { + display: flex; + align-items: center; + justify-content: center; + gap: var(--space-3); + flex-wrap: wrap; + margin-bottom: var(--space-8); + padding: var(--space-6) var(--space-4); + background: var(--color-bg-warm); + border-radius: var(--radius-md); +} +.ib-node { + display: flex; + flex-direction: column; + align-items: center; + gap: var(--space-2); + padding: var(--space-4); + border-radius: var(--radius-md); + background: var(--color-surface); + border: 2px solid var(--color-border); + min-width: 100px; + transition: border-color var(--duration-fast); +} +.ib-node:hover { border-color: var(--color-accent); } +.ib-node-this { border-color: var(--color-accent); background: var(--color-accent-light); } +.ib-node-icon { font-size: 1.5rem; } +.ib-node-label { + font-family: var(--font-display); + font-size: var(--text-sm); + font-weight: 600; +} +.ib-node-detail { + font-family: var(--font-mono); + font-size: var(--text-xs); + color: var(--color-text-muted); +} +.ib-arrow { + font-size: var(--text-xl); + color: var(--color-text-muted); + flex-shrink: 0; +} +.ib-code-section { + margin-top: var(--space-6); +} +.ib-code-title { + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--color-text-muted); + margin-bottom: var(--space-4); +} +.ib-compat-notes { + margin-top: var(--space-6); +} +.ib-compat-notes h4 { + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--color-text-muted); + margin-bottom: var(--space-3); +} +.ib-note { + display: flex; + align-items: flex-start; + gap: var(--space-3); + padding: var(--space-3) var(--space-4); + border-radius: var(--radius-sm); + margin-bottom: var(--space-2); + font-size: var(--text-sm); +} +.ib-note p { margin: 0; color: var(--color-text-secondary); } +.ib-note code { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #CBA6F7; + padding: 1px var(--space-2); + border-radius: 4px; +} +.ib-note-icon { flex-shrink: 0; } +.ib-note-warn { background: var(--color-error-light); } +.ib-note-info { background: var(--color-info-light); } + +/* ── RISK INDICATORS ────────────────────────────────────────── */ +.risk-badge { + display: inline-flex; + align-items: center; + font-family: var(--font-mono); + font-size: var(--text-xs); + font-weight: 700; + padding: var(--space-1) var(--space-3); + border-radius: var(--radius-sm); + white-space: nowrap; + vertical-align: middle; +} +.risk-high { background: var(--color-error-light); color: var(--color-error); } +.risk-medium { background: #FFF3E0; color: #E65100; } +.risk-low { background: var(--color-success-light); color: var(--color-success); } + +.risk-panel { + background: var(--color-surface); + border-radius: var(--radius-lg); + padding: var(--space-8); + box-shadow: var(--shadow-md); + margin: var(--space-8) 0; +} +.risk-panel-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-6); +} +.risk-items { + display: flex; + flex-direction: column; + gap: var(--space-4); +} +.risk-item { + display: flex; + align-items: flex-start; + gap: var(--space-4); + padding: var(--space-4); + background: var(--color-bg-warm); + border-radius: var(--radius-md); +} +.risk-item .risk-badge { flex-shrink: 0; margin-top: 2px; } +.risk-content strong { + display: block; + font-size: var(--text-sm); + font-weight: 700; + margin-bottom: var(--space-2); +} +.risk-content p { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin: 0; +} +.risk-content code { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #CBA6F7; + padding: 1px var(--space-2); + border-radius: 4px; +} + +/* ── VERDICT CALLOUT ────────────────────────────────────────── */ +.verdict-callout { + display: flex; + gap: var(--space-4); + padding: var(--space-6); + border-radius: var(--radius-md); + margin: var(--space-8) 0; + background: var(--color-surface); + border-left: 4px solid var(--color-accent); + box-shadow: var(--shadow-md); +} +.verdict-callout.verdict-positive { border-left-color: var(--color-success); } +.verdict-callout.verdict-mixed { border-left-color: var(--color-info); } +.verdict-callout.verdict-negative { border-left-color: var(--color-error); } + +.verdict-icon { + font-size: 1.5rem; + flex-shrink: 0; + margin-top: 2px; +} +.verdict-label { + display: inline-block; + font-family: var(--font-mono); + font-size: var(--text-xs); + text-transform: uppercase; + letter-spacing: 0.1em; + color: var(--color-text-muted); + margin-bottom: var(--space-2); +} +.verdict-text { + font-size: var(--text-sm); + color: var(--color-text); + line-height: var(--leading-normal); + margin-bottom: var(--space-3); +} +.verdict-strong { color: var(--color-accent); } +.verdict-positive .verdict-strong { color: var(--color-success); } +.verdict-mixed .verdict-strong { color: var(--color-info); } +.verdict-negative .verdict-strong { color: var(--color-error); } +.verdict-action { + font-size: var(--text-sm); + color: var(--color-text-secondary); + padding: var(--space-3); + background: var(--color-bg-warm); + border-radius: var(--radius-sm); +} +.verdict-action code { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #CBA6F7; + padding: 1px var(--space-2); + border-radius: 4px; +} + +/* ── CRITICAL PATH TRACE ────────────────────────────────────── */ +.critical-path { + margin: var(--space-8) 0; +} +.cp-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-2); +} +.cp-desc { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-6); +} +.cp-steps { + position: relative; + padding-left: var(--space-8); +} +.cp-steps::before { + content: ''; + position: absolute; + left: 16px; + top: 0; + bottom: 0; + width: 2px; + background: var(--color-border); +} +.cp-step { + position: relative; + margin-bottom: var(--space-8); +} +.cp-step:last-child { margin-bottom: 0; } +.cp-step-marker { + position: absolute; + left: calc(var(--space-8) * -1); + display: flex; + flex-direction: column; + align-items: center; + gap: var(--space-2); +} +.cp-step-num { + width: 34px; + height: 34px; + border-radius: 50%; + background: var(--color-accent); + color: white; + font-family: var(--font-display); + font-weight: 700; + font-size: var(--text-sm); + display: flex; + align-items: center; + justify-content: center; + position: relative; + z-index: 1; +} +.cp-step-file { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #CBA6F7; + padding: var(--space-1) var(--space-2); + border-radius: 4px; + white-space: nowrap; + writing-mode: vertical-rl; + text-orientation: mixed; + max-height: 120px; + overflow: hidden; +} +.cp-step-content { + padding-top: var(--space-2); +} + +/* ── SOURCE FILE MAP (Engineer Mode) ─────────────────────────── */ +.source-file-map { + background: var(--color-surface); + border-radius: var(--radius-lg); + padding: var(--space-8); + box-shadow: var(--shadow-md); + margin: var(--space-8) 0; +} +.sfm-header { margin-bottom: var(--space-6); } +.sfm-title { + font-family: var(--font-display); + font-size: var(--text-xl); + font-weight: 700; + margin-bottom: var(--space-2); +} +.sfm-desc { + font-size: var(--text-sm); + color: var(--color-text-secondary); + margin-bottom: var(--space-4); +} +.sfm-badge { + display: inline-block; + font-family: var(--font-mono); + font-size: var(--text-xs); + font-weight: 700; + padding: 1px var(--space-2); + border-radius: 4px; + vertical-align: middle; +} +.sfm-badge.sfm-framework { background: var(--color-accent-light); color: var(--color-accent); } +.sfm-badge.sfm-functional { background: #FFF3E0; color: #E65100; } + +.sfm-filters { + display: flex; + gap: var(--space-2); + flex-wrap: wrap; +} +.sfm-filter { + padding: var(--space-1) var(--space-3); + border-radius: var(--radius-sm); + border: 1px solid var(--color-border); + background: var(--color-surface); + font-family: var(--font-body); + font-size: var(--text-xs); + cursor: pointer; + transition: all var(--duration-fast); +} +.sfm-filter:hover { border-color: var(--color-accent-muted); } +.sfm-filter.active { + background: var(--color-accent); + color: white; + border-color: var(--color-accent); +} + +.sfm-stats { + display: flex; + gap: var(--space-4); + margin-bottom: var(--space-6); + flex-wrap: wrap; +} +.sfm-stat { + background: var(--color-bg-warm); + border-radius: var(--radius-sm); + padding: var(--space-3) var(--space-4); + text-align: center; + flex: 1; + min-width: 80px; +} +.sfm-stat-num { + display: block; + font-family: var(--font-display); + font-size: var(--text-2xl); + font-weight: 700; + color: var(--color-accent); +} +.sfm-stat-label { + display: block; + font-size: var(--text-xs); + color: var(--color-text-muted); + margin-top: var(--space-1); +} + +.sfm-tree { + font-family: var(--font-mono); + font-size: var(--text-sm); + border: 1px solid var(--color-border-light); + border-radius: var(--radius-md); + overflow: hidden; +} + +/* Directory (expandable) */ +.sfm-dir { border-bottom: 1px solid var(--color-border-light); } +.sfm-dir:last-child { border-bottom: none; } +.sfm-dir-header { + display: flex; + align-items: center; + gap: var(--space-2); + padding: var(--space-3) var(--space-4); + cursor: pointer; + transition: background var(--duration-fast); + background: var(--color-bg-warm); +} +.sfm-dir-header:hover { background: var(--color-accent-light); } +.sfm-arrow { + color: var(--color-text-muted); + font-size: var(--text-xs); + flex-shrink: 0; + width: 1em; + text-align: center; + transition: transform var(--duration-fast); +} +.sfm-dir.open > .sfm-dir-header > .sfm-arrow { transform: rotate(0deg); } +.sfm-dir-name { + font-weight: 700; + color: var(--color-accent); +} +.sfm-dir-desc { + font-family: var(--font-body); + font-size: var(--text-xs); + color: var(--color-text-muted); + margin-left: auto; + flex-shrink: 1; + text-align: right; + max-width: 50%; +} +.sfm-dir-children { + padding-left: var(--space-6); + border-top: 1px solid var(--color-border-light); +} + +/* Files */ +.sfm-file { + display: flex; + align-items: center; + gap: var(--space-2); + padding: var(--space-2) var(--space-4); + border-bottom: 1px solid var(--color-border-light); + transition: background var(--duration-fast); +} +.sfm-file:last-child { border-bottom: none; } +.sfm-file:hover { background: rgba(42, 123, 155, 0.04); } +.sfm-file.sfm-entry { background: rgba(42, 123, 155, 0.06); } +.sfm-file-icon { flex-shrink: 0; font-size: var(--text-sm); } +.sfm-file-name { + font-weight: 600; + color: var(--color-text); + white-space: nowrap; +} +.sfm-file-loc { + font-size: var(--text-xs); + color: var(--color-text-muted); + white-space: nowrap; + flex-shrink: 0; +} +.sfm-file-desc { + font-family: var(--font-body); + font-size: var(--text-xs); + color: var(--color-text-secondary); + margin-left: auto; + flex-shrink: 1; + text-align: right; + max-width: 40%; +} + +/* Role badges */ +.sfm-role { + display: inline-block; + font-family: var(--font-mono); + font-size: 10px; + font-weight: 700; + padding: 0 var(--space-2); + border-radius: 3px; + white-space: nowrap; + flex-shrink: 0; + line-height: 1.6; +} +.sfm-role.sfm-framework { + background: var(--color-accent-light); + color: var(--color-accent); +} +.sfm-role.sfm-functional { + background: #FFF3E0; + color: #E65100; +} + +/* Legend */ +.sfm-legend { + margin-top: var(--space-6); + display: flex; + flex-direction: column; + gap: var(--space-3); +} +.sfm-legend-item { + display: flex; + align-items: center; + gap: var(--space-3); + font-size: var(--text-sm); + color: var(--color-text-secondary); +} + +/* Reading order */ +.sfm-reading-order { + margin-top: var(--space-6); + padding: var(--space-5); + background: var(--color-accent-light); + border-radius: var(--radius-md); + border-left: 3px solid var(--color-accent); +} +.sfm-reading-title { + font-family: var(--font-display); + font-size: var(--text-base); + font-weight: 700; + margin-bottom: var(--space-4); +} +.sfm-reading-steps { + display: flex; + flex-direction: column; + gap: var(--space-3); +} +.sfm-reading-step { + display: flex; + align-items: center; + gap: var(--space-3); + font-size: var(--text-sm); +} +.sfm-reading-num { + width: 24px; + height: 24px; + border-radius: 50%; + background: var(--color-accent); + color: white; + font-family: var(--font-display); + font-weight: 700; + font-size: var(--text-xs); + display: flex; + align-items: center; + justify-content: center; + flex-shrink: 0; +} +.sfm-reading-step code { + font-family: var(--font-mono); + font-size: var(--text-xs); + background: var(--color-bg-code); + color: #CBA6F7; + padding: 1px var(--space-2); + border-radius: 4px; + white-space: nowrap; +} +.sfm-reading-reason { + color: var(--color-text-secondary); + font-size: var(--text-xs); +} + +/* Filter state: hide non-matching */ +.source-file-map[data-filter="framework"] .sfm-file[data-role="functional"], +.source-file-map[data-filter="framework"] .sfm-dir[data-role="functional"], +.source-file-map[data-filter="functional"] .sfm-file[data-role="framework"], +.source-file-map[data-filter="functional"] .sfm-dir[data-role="framework"], +.source-file-map[data-filter="functional"] .sfm-file[data-role="entry"], +.source-file-map[data-filter="entry"] .sfm-file:not([data-role="entry"]), +.source-file-map[data-filter="entry"] .sfm-dir:not([data-role="entry"]) { + display: none; +} + +/* ── ENGINEER MODE RESPONSIVE ───────────────────────────────── */ +@media (max-width: 768px) { + .adr-card { margin: var(--space-6) 0; } + .tradeoff-matrix { padding: var(--space-6); } + .sj-pros-cons { grid-template-columns: 1fr; } + .ib-flow { flex-direction: column; } + .ib-arrow { transform: rotate(90deg); } + .ib-node { min-width: unset; width: 100%; } + .cp-step-marker { flex-direction: row; } + .cp-step-file { + writing-mode: horizontal-tb; + max-height: unset; + } + .verdict-callout { flex-direction: column; } + .source-file-map { padding: var(--space-6); } + .sfm-stats { gap: var(--space-2); } + .sfm-stat { min-width: 60px; padding: var(--space-2); } + .sfm-stat-num { font-size: var(--text-lg); } + .sfm-dir-desc { display: none; } + .sfm-file-desc { max-width: 50%; } + .sfm-file { flex-wrap: wrap; } + .sfm-reading-step { flex-wrap: wrap; } +} From 02e9f94fa017a1450af1370567cc56a8270e45aa Mon Sep 17 00:00:00 2001 From: huangyong <13701062894@139.com> Date: Sun, 21 Jun 2026 16:55:48 +0800 Subject: [PATCH 2/2] docs: add Qwen3.7-Max credit to README --- README.md | 92 +++++++++++++++++++++++------- README.zh-CN.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 219 insertions(+), 20 deletions(-) create mode 100644 README.zh-CN.md diff --git a/README.md b/README.md index acc3149..a1ecd16 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,18 @@ # Codebase to Course -A Claude Code skill that turns any codebase into a beautiful, interactive single-page HTML course. +**[中文文档](README.zh-CN.md)** -Point it at a repo. Get back a stunning, self-contained course that teaches how the code works — with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations. +A Claude Code skill that turns any codebase into a beautiful, interactive single-page HTML course. Two modes for two very different audiences. -## Who is this for? +Point it at a repo. Get back a stunning, self-contained course — with scroll-based navigation, animated visualizations, embedded quizzes, and code-with-plain-English side-by-side translations. Or, if you're a professional engineer evaluating a project for adoption, get a technical due diligence report with architecture decision analysis, critical path traces, risk assessments, and competitive comparisons. -**"Vibe coders"** — people who build software by instructing AI coding tools in natural language, without a traditional CS education. +## Two modes -You've built something (or found something cool on GitHub). It works. But you don't really understand *how* it works under the hood. This skill generates a course that teaches you — not by lecturing, but by tracing what happens when you actually use the app. +### Beginner Mode — for vibe coders + +**Audience:** People who build software by instructing AI coding tools in natural language, without a traditional CS education. + +You've built something (or found something cool on GitHub). It works. But you don't really understand *how* it works under the hood. This mode generates a course that teaches you — not by lecturing, but by tracing what happens when you actually use the app. **Your goals are practical, not academic:** - Steer AI coding tools better (make smarter architectural decisions) @@ -18,25 +22,42 @@ You've built something (or found something cool on GitHub). It works. But you do You're not trying to become a software engineer. You want coding as a superpower. +### Engineer Mode — for technical due diligence + +**Audience:** Professional software engineers evaluating whether to adopt an open-source project into their production stack. + +You don't need metaphors. You need to know: *Are the design decisions sound? What are the critical paths? Will it work in my scenario? Can it integrate with my stack? How does it compare to alternatives?* + +Engineer Mode produces a fundamentally different output — a technical due diligence report with: + +- **ADR Cards** — Architecture Decision Records analyzing each key design choice (problem, selected approach, rejected alternatives, trade-off table) +- **Critical Path Traces** — Step-by-step walkthroughs of the most important code execution paths, with engineering commentary referencing exact file names and line numbers +- **Trade-off Matrices** — Color-coded comparison tables evaluating different approaches across multiple dimensions +- **Scenario Judge** — Interactive cards that assess whether the project is a good fit for specific use cases +- **Integration Blueprint** — Complete, copy-pasteable bridge code showing how to integrate with real-world tech stacks +- **Source File Map** — Annotated directory tree classifying each key file as "framework" (skeleton/architectural) or "functional" (concrete implementation), with a recommended 3-5 file reading order +- **Risk Indicators** — Categorized risk items with severity levels (high/medium/low) +- **Verdict Callout** — Each module ends with a clear engineering verdict + ## What the course looks like The output is a **single HTML file** — no dependencies, no setup, works offline. It includes: - **Scroll-based modules** with progress tracking and keyboard navigation -- **Code ↔ Plain English translations** — real code on the left, what it means on the right +- **Code ↔ Plain English translations** (Beginner) or **Code ↔ Engineering Commentary** (Engineer) — real code on one side, what it means or why it matters on the other + Code translation block -- **Animated visualizations** — data flow animations, group chat between components, architecture diagrams +- **Animated visualizations** — data flow animations, group chat between components, architecture diagrams (Beginner Mode) Animated data flow - **Interactive quizzes** that test *application* not memorization ("You want to add favorites — which files change?") Interactive quiz -- **Glossary tooltips** — hover any technical term for a plain-English definition +- **Glossary tooltips** — hover any technical term for a plain-English definition (Beginner Mode) Glossary tooltip - -- **Warm, distinctive design** — not the typical purple-gradient AI look +- **Warm, distinctive design** — not the typical purple-gradient AI look. Five accent palettes available (vermillion, coral, teal, amber, forest). ## How to use @@ -44,15 +65,21 @@ The output is a **single HTML file** — no dependencies, no setup, works offlin 1. Copy the `codebase-to-course` folder into `~/.claude/skills/` 2. Open any project in Claude Code -3. Say: *"Turn this codebase into an interactive course"* +3. Say one of: + +**For Beginner Mode:** +- *"Turn this codebase into an interactive course"* +- *"Explain this codebase interactively"* +- *"Make a course from this project"* +- *"Teach me how this code works"* -### Trigger phrases +**For Engineer Mode:** +- *"Turn this codebase into an engineer mode report"* +- *"Analyze this codebase for technical due diligence"* +- *"I need an engineering assessment of this project"* +- *"Should we adopt this library? Generate a report"* -- "Turn this into a course" -- "Explain this codebase interactively" -- "Make a course from this project" -- "Teach me how this code works" -- "Interactive tutorial from this code" +The mode is auto-detected from your prompt, or you can specify explicitly. ## Design philosophy @@ -80,13 +107,38 @@ Code snippets are exact copies from the real codebase — never modified or simp ``` codebase-to-course/ -├── SKILL.md # Main skill instructions +├── SKILL.md # Main skill instructions (both modes) └── references/ + ├── _base.html # HTML template shell + ├── _footer.html # Shared footer with navigation logic + ├── styles.css # All styles (both modes + engineer elements) + ├── main.js # Interactive logic (quizzes, file map, etc.) + ├── build.sh # Shell script to assemble single HTML file ├── design-system.md # CSS tokens, typography, colors, layout - └── interactive-elements.md # Quiz, animation, and visualization patterns + ├── interactive-elements.md # All 25 interactive element patterns + ├── content-philosophy.md # Content writing philosophy per mode + ├── gotchas.md # Common mistakes and how to avoid them + └── module-brief-template.md # Template for Phase 2.5 planning checkpoint ``` +## Changelog + +### v2.0.0 — Engineer Mode (2025) + +- Added **Engineer Mode**: a completely separate product targeting professional engineers doing technical due diligence +- 8 new interactive element types: ADR Cards, Critical Path Traces, Trade-off Matrix, Scenario Judge, Integration Blueprint, Source File Map, Risk Indicators, Verdict Callout +- **Source File Map**: annotated directory tree classifying 30-50 key files as "framework" (骨架/框架性) vs "functional" (功能/功能性), with recommended reading order +- Code block style shifted from "Code ↔ Plain English" to "Code ↔ Engineering Commentary" for engineer mode +- Added `content-philosophy.md` and `gotchas.md` as separate reference files +- Added Phase 2.5 planning checkpoint for complex codebases +- Forked Phase 3 into sequential (simple) and parallel (complex) build paths +- Updated skill structure to include HTML template, CSS, JS, and build script + +### v1.0.0 — Initial release + +- Beginner Mode with scroll-based navigation, animated visualizations, interactive quizzes, and glossary tooltips +- Single-file HTML output with no dependencies --- -Built by [Zara](https://x.com/zarazhangrui) with Claude Code. +Built by [Zara](https://x.com/zarazhangrui) with Claude Code. Engineer Mode and Chinese documentation added by [fogdragon](https://github.com/fogdragon) by Qwen3.7-Max. diff --git a/README.zh-CN.md b/README.zh-CN.md new file mode 100644 index 0000000..8fec18c --- /dev/null +++ b/README.zh-CN.md @@ -0,0 +1,147 @@ +# Codebase to Course + +**[English](README.md)** + +一个 Claude Code 技能，可以将任意代码库转化为精美的、交互式单页 HTML 课程。提供两种模式，面向两类截然不同的受众。 + +指向一个仓库，得到一个精美的、自包含的课程——支持滚动导航、动画可视化、嵌入式测验，以及代码与自然语言的逐段对照翻译。或者，如果你是一位正在评估是否引入某个开源项目的专业工程师，你会得到一份技术尽调报告——包含架构决策分析、关键路径追踪、风险评估和竞品对比。 + +## 两种模式 + +### 入门模式（Beginner Mode）——面向 Vibe Coder + +**受众：** 通过自然语言指挥 AI 编码工具构建软件、但没有传统计算机科班背景的人。 + +你已经做出了一个东西（或在 GitHub 上发现了一个很酷的项目）。它能跑。但你并不真正理解它*底层*是怎么工作的。这个模式会生成一个课程来教你——不是通过说教，而是通过追踪你实际使用这个应用时发生的事情。 + +**你的目标是实用性的，不是学术性的：** +- 更好地驾驭 AI 编码工具（做出更明智的架构决策） +- 发现 AI 什么时候在胡说（捕捉幻觉、识别坏模式） +- 在 AI 卡住时能 debug（打破 bug 循环） +- 和工程师交流时不会一头雾水 + +你不是想成为软件工程师。你想把编码变成你的超能力。 + +### 工程师模式（Engineer Mode）——面向技术尽调 + +**受众：** 正在评估是否将某个开源项目引入生产环境的专业软件工程师。 + +你不需要隐喻。你需要知道：*设计决策合理吗？关键路径是怎么实现的？在我的场景下能工作吗？能和我的技术栈集成吗？和竞品比怎么样？* + +工程师模式产出的是一个完全不同的产品——一份技术尽调报告，包含： + +- **ADR 卡片（架构决策记录）** ——分析每个关键设计决策的完整上下文（问题背景、选定方案、被放弃的备选方案、权衡分析表格） +- **关键路径追踪** ——逐步展示最重要的代码执行路径，附带工程分析注释，精确到文件名和行号 +- **权衡矩阵** ——颜色编码的比较表格，在多个维度上评估不同方案的优劣 +- **场景判断器** ——交互式卡片，评估项目是否适合特定的使用场景 +- **集成蓝图** ——完整的、可直接复制的桥接代码，展示如何与真实技术栈集成 +- **源文件地图** ——带注释的目录树，将 30-50 个关键文件分类为"框架性"（骨架/架构）或"功能性"（具体实现），并推荐 3-5 个文件的首读顺序 +- **风险指标** ——按严重程度（高/中/低）分类的风险项 +- **裁决标注** ——每个模块以一个清晰的工程判断结尾 + +## 课程长什么样 + +输出是一个**单一 HTML 文件**——无依赖、无需配置、离线可用。包含： + +- **滚动式模块导航**，带进度追踪和键盘快捷键 +- **代码 ↔ 自然语言翻译**（入门模式）或 **代码 ↔ 工程分析**（工程师模式）——一侧是真实代码，另一侧是含义解读或工程意义分析 + +代码翻译块 + +- **动画可视化** ——数据流动画、组件间群聊对话、架构图（入门模式） + +数据流动画 + +- **交互式测验**——测试的是*应用能力*而非记忆（"你要添加收藏功能——哪些文件需要改？"） + +交互式测验 + +- **术语提示** ——鼠标悬停在任何技术术语上即可获得通俗解释（入门模式） + +术语提示 + +- **温暖、独特的设计** ——不是那种典型的紫色渐变 AI 风格。提供五种主题色（朱红、珊瑚、青绿、琥珀、森林绿）。 + +## 如何使用 + +### 作为 Claude Code 技能 + +1. 将 `codebase-to-course` 文件夹复制到 `~/.claude/skills/` +2. 在 Claude Code 中打开任意项目 +3. 说出以下触发语之一： + +**入门模式：** +- *"把这个代码库变成一个交互式课程"* +- *"交互式地解释这个代码库"* +- *"用这个项目做一个课程"* +- *"教我这段代码是怎么工作的"* + +**工程师模式：** +- *"用工程师模式分析这个代码库"* +- *"对这个项目做技术尽调"* +- *"生成一份工程评估报告"* +- *"我们该不该引入这个库？生成分析报告"* + +模式会从你的提示语中自动检测，也可以显式指定。 + +## 设计理念 + +### 先做，后理解 + +这颠覆了传统计算机教育。老方法：背概念好几年 → 终于做点东西 → 最后才明白为什么（大多数人在第三步之前就放弃了）。新方法：**先做出来 → 体验它能工作 → 现在理解它是怎么工作的。** + +### 展示，而非告知 + +每个页面至少 50% 是视觉内容。每个文字块最多 2-3 句话。如果某个东西可以做成图表、动画或交互元素——它就不应该是一个段落。 + +### 测验考的是做，而非知道 + +不是考 "API 的全称是什么？"，而是："用户反馈切换页面后数据是旧的。你会先看哪里？"测验考的是你能不能*用*学到的东西解决新问题。 + +### 不复用隐喻 + +每个概念都有一个适合*那个特定想法*的隐喻。数据库是一个带卡片目录的图书馆。认证是一个检查身份证的门卫。API 限流是一个有容量限制的夜店。同一个隐喻不会用两次。 + +### 只用原始代码 + +代码片段是从真实代码库中原样复制的——从不修改或简化。学习者应该能打开实际文件，看到和他们学习时一样的代码。 + +## 技能结构 + +``` +codebase-to-course/ +├── SKILL.md # 主技能指令（两种模式） +└── references/ + ├── _base.html # HTML 模板外壳 + ├── _footer.html # 共享页脚和导航逻辑 + ├── styles.css # 所有样式（两种模式 + 工程师元素） + ├── main.js # 交互逻辑（测验、文件地图等） + ├── build.sh # 组装单一 HTML 文件的 Shell 脚本 + ├── design-system.md # CSS 令牌、字体、颜色、布局 + ├── interactive-elements.md # 全部 25 种交互元素模式 + ├── content-philosophy.md # 各模式的内容写作哲学 + ├── gotchas.md # 常见错误及避免方法 + └── module-brief-template.md # Phase 2.5 规划检查点模板 +``` + +## 更新日志 + +### v2.0.0 — 工程师模式（2025） + +- 新增**工程师模式**：一个完全不同的产品，面向做技术尽调的专业工程师 +- 8 种新交互元素：ADR 卡片、关键路径追踪、权衡矩阵、场景判断器、集成蓝图、源文件地图、风险指标、裁决标注 +- **源文件地图**：带注释的目录树，将 30-50 个关键文件分为"框架性"（骨架/架构）和"功能性"（具体实现），并推荐首读顺序 +- 工程师模式的代码块风格从"代码 ↔ 自然语言"改为"代码 ↔ 工程分析" +- 新增 `content-philosophy.md` 和 `gotchas.md` 作为独立参考文件 +- 新增 Phase 2.5 规划检查点，用于复杂代码库 +- Phase 3 拆分为顺序构建（简单项目）和并行构建（复杂项目）两条路径 +- 技能结构更新，包含 HTML 模板、CSS、JS 和构建脚本 + +### v1.0.0 — 初始版本 + +- 入门模式，支持滚动导航、动画可视化、交互式测验和术语提示 +- 单一 HTML 文件输出，无依赖 + +--- + +原版由 [Zara](https://x.com/zarazhangrui) 使用 Claude Code 构建。工程师模式和中文文档由 [fogdragon](https://github.com/fogdragon) by Qwen3.7-Max 添加。