{PROJECT_NAME} 学习指南

# Project Learning Page > Project Learning Page Generator Skill - Skill: `saltro/project-learning-page` (Agent Skill) - Install (CLI): `npx skillmds@latest add saltro/project-learning-page` - Raw SKILL.md: https://api.skillmd.com/api/skills/saltro/project-learning-page/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Saltro (https://skillmd.com/u/saltro) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/saltro/project-learning-page --- # Project Learning Page Generator Skill ## 概述本 Skill 定义了一套标准化流程，用于分析任意软件项目并生成一个交互式 HTML 学习页面。通过亮色主题、代码高亮、知识测验和响应式设计，帮助用户（或你自己）快速理解项目架构和核心机制。 --- ## 使用场景 - 快速上手一个新的开源项目或内部仓库 - 为团队沉淀项目知识库 - 作为 Code Review 或技术分享的辅助材料 - 学习优秀项目的架构设计模式 --- ## 执行流程 ### Phase 1: 项目分析 1. **扫描项目结构** - 使用 `ls` / `find` 查看顶层目录和关键子目录 - 识别项目类型（Python/Node/Go 等）和框架 2. **阅读核心文件** - 入口文件（`main.py`, `index.js`, `main.go` 等） - 配置文件（了解依赖和运行方式） - 核心模块（按职责分层阅读：编排层 → 业务层 → 工具层） - 提示词/模板文件（如果有 Agent 系统） 3. **提取关键概念** - 架构模式（ReAct, State Machine, DAG 等） - 核心数据结构 - 关键算法或决策逻辑 - 模块间的调用关系 ### Phase 2: 内容设计将分析结果组织为以下标准章节（根据项目类型灵活调整）： | 章节 | 内容 | 可选交互 | |------|------|----------| | 项目概览 | 项目背景、设计目标、核心特性 | 特性卡片网格 | | 项目结构 | 文件树 + 职责说明 | 可折叠目录 | | 架构设计 | 分层架构图、数据流图 | 流程图/表格 | | 核心模块 A | 关键代码 + 详细注释 | 代码高亮 | | 核心模块 B | ... | ... | | 状态/数据流 | 状态管理、数据传递 | 状态转换图 | | 工具/基础设施 | 外部依赖、工具封装 | 工具卡片 | | 知识测验 | 8-10 道选择题 | 点击交互 + 解析 | ### Phase 3: HTML 生成 #### 技术栈 - **单文件 HTML**：所有 CSS/JS 内联，无需构建工具 - **highlight.js**：代码语法高亮（GitHub 亮色主题） - **纯 CSS 响应式**：Flexbox + Grid + Media Query - **原生 JavaScript**：无框架依赖 #### 样式规范（亮色主题） ```css :root { --bg-primary: #ffffff; --bg-secondary: #f6f8fa; --text-primary: #1f2328; --text-secondary: #656d76; --accent-blue: #0969da; --accent-green: #1a7f37; --accent-purple: #8250df; --accent-orange: #cf4b00; --accent-red: #cf222e; --border-color: #d0d7de; } ``` #### 布局结构 ``` ┌─────────────────────────────────────┐ │ Navbar (fixed, 56px) │ ├──────────┬──────────────────────────┤ │ │ │ │ Sidebar │ Main Content │ │ (260px) │ (max-width: 900px) │ │ fixed │ │ │ │ │ └──────────┴──────────────────────────┘ ``` #### 响应式断点 - **Desktop (>1024px)**: 完整侧边栏 + 顶部导航 - **Tablet (640-1024px)**: 侧边栏变抽屉（汉堡菜单触发） - **Mobile (<640px)**: 单列布局，卡片全宽，字体缩小 #### 交互组件 1. **侧边栏导航** - 点击切换内容区块 - 当前项高亮（蓝色左边框 + 背景色） - 移动端：汉堡按钮触发抽屉 + 遮罩层 2. **代码块** - `

`
   - highlight.js 自动高亮
   - 添加行内注释（HTML 实现）

3. **测验系统**
   - `data-answer` 标记正确答案
   - 点击后禁用选项，显示对错 + 解析
   - CSS 过渡动画

4. **流程图**
   - 纯 CSS 实现（flex 布局 + 箭头符号）
   - 不同节点类型不同颜色

### Phase 4: 部署与访问

```bash
# 使用 npx serve 启动静态服务器
npx serve -l tcp://0.0.0.0:8888 

# 获取访问链接
# 1. 获取本机 IP
curl -s http://169.254.169.254/latest/meta-data/local-ipv4  # 云服务器
curl -s ifconfig.me  # 公网 IP（如有）

# 2. 构造链接
# http://:8888/
```

---

## 代码模板

### 最小可复用 HTML 骨架

```html



    
    
    {PROJECT_NAME} 学习指南
    
    
    
    


    ...
    
        ...
        
            ...
            ...
        
    
    


```

---

## 批量输出策略

当 HTML 内容较多时，采用分块生成策略：

1. **先写骨架**：HTML 框架 + CSS + JS 交互逻辑
2. **分批填充内容**：
   - Batch 1: 概览 + 架构 + 项目结构
   - Batch 2: 核心模块代码分析
   - Batch 3: 状态/数据流 + 工具系统
   - Batch 4: 测验题目 + 最终检查
3. **每次追加**：使用 `cat >> file.html` 或编辑工具追加到 `` 之前

---

## 质量检查清单

- [ ] 所有代码片段有语法高亮
- [ ] 关键代码有中文注释说明
- [ ] 测验题目覆盖核心概念
- [ ] 移动端侧边栏可正常展开/收起
- [ ] 内容区块切换流畅
- [ ] 无外部依赖（除 highlight.js CDN）
- [ ] 亮色主题，对比度足够