Software Manual Skill
Generate comprehensive, interactive software manuals in TiddlyWiki-style single-file HTML format.
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐ │ Context-Optimized Architecture │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Phase 1: Requirements → manual-config.json │ │ ↓ │ │ Phase 2: Exploration → exploration-.json │ │ ↓ │ │ Phase 3: Parallel Agents → sections/section-.md │ │ ↓ (6 Agents) │ │ Phase 3.5: Consolidation → consolidation-summary.md │ │ ↓ │ │ Phase 4: Screenshot → screenshots/*.png │ │ Capture (via Chrome MCP) │ │ ↓ │ │ Phase 5: HTML Assembly → {name}-使用手册.html │ │ ↓ │ │ Phase 6: Refinement → iterations/ │ │ │ └─────────────────────────────────────────────────────────────────┘
Key Design Principles
-
主 Agent 编排，子 Agent 执行: 所有繁重计算委托给 universal-executor 子 Agent
-
Brief Returns: Agents return path + summary, not full content (avoid context overflow)
-
System Agents: 使用 cli-explore-agent (探索) 和 universal-executor (执行)
-
成熟库内嵌: marked.js (MD 解析) + highlight.js (语法高亮)，无 CDN 依赖
-
Single-File HTML: TiddlyWiki-style interactive document with embedded resources
-
动态标签: 根据实际章节自动生成导航标签
Execution Flow
┌─────────────────────────────────────────────────────────────────┐ │ Phase 1: Requirements Discovery (主 Agent) │ │ → AskUserQuestion: 收集软件类型、目标用户、文档范围 │ │ → Output: manual-config.json │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 2: Project Exploration (cli-explore-agent × N) │ │ → 并行探索: architecture, ui-routes, api-endpoints, config │ │ → Output: exploration-.json │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 2.5: API Extraction (extract_apis.py) │ │ → 自动提取: FastAPI/TypeDoc/pdoc │ │ → Output: api-docs/{backend,frontend,modules}/.md │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 3: Parallel Analysis (universal-executor × 6) │ │ → 6 个子 Agent 并行: overview, ui-guide, api-docs, config, │ │ troubleshooting, code-examples │ │ → Output: sections/section-.md │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 3.5: Consolidation (universal-executor) │ │ → 质量检查: 一致性、交叉引用、截图标记 │ │ → Output: consolidation-summary.md, screenshots-list.json │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 4: Screenshot Capture (universal-executor + Chrome MCP) │ │ → 批量截图: 调用 mcp__chrome__screenshot │ │ → Output: screenshots/.png + manifest.json │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 5: HTML Assembly (universal-executor) │ │ → 组装 HTML: MD→tiddlers, 嵌入 CSS/JS/图片 │ │ → Output: {name}-使用手册.html │ ├─────────────────────────────────────────────────────────────────┤ │ Phase 6: Iterative Refinement (主 Agent) │ │ → 预览 + 用户反馈 + 迭代修复 │ │ → Output: iterations/v*.html │ └─────────────────────────────────────────────────────────────────┘
Agent Configuration
Agent Role Output File Focus Areas
overview Product Manager section-overview.md Product intro, features, quick start
ui-guide UX Expert section-ui-guide.md UI operations, step-by-step guides
api-docs API Architect section-api-reference.md REST API, Frontend API
config DevOps Engineer section-configuration.md Env vars, deployment, settings
troubleshooting Support Engineer section-troubleshooting.md FAQs, error codes, solutions
code-examples Developer Advocate section-examples.md Beginner/Intermediate/Advanced examples
Agent Return Format
interface ManualAgentReturn { status: "completed" | "partial" | "failed"; output_file: string; summary: string; // Max 50 chars screenshots_needed: Array<{ id: string; // e.g., "ss-login-form" url: string; // Relative or absolute URL description: string; // "Login form interface" selector?: string; // CSS selector for partial screenshot wait_for?: string; // Element to wait for }>; cross_references: string[]; // Other sections referenced difficulty_level: "beginner" | "intermediate" | "advanced"; }
HTML Features (TiddlyWiki-style)
-
Search: Full-text search with result highlighting
-
Collapse/Expand: Per-section collapsible content
-
Tag Navigation: Filter by category tags
-
Theme Toggle: Light/Dark mode with localStorage persistence
-
Single File: All CSS/JS/images embedded as Base64
-
Offline: Works without internet connection
-
Print-friendly: Optimized print stylesheet
Directory Setup
// Generate timestamp directory name
const timestamp = new Date().toISOString().slice(0,19).replace(/[-:T]/g, '');
const dir = .workflow/.scratchpad/manual-${timestamp};
// Windows
Bash(mkdir "${dir}\\sections" && mkdir "${dir}\\screenshots" && mkdir "${dir}\\api-docs" && mkdir "${dir}\\iterations");
Output Structure
.workflow/.scratchpad/manual-{timestamp}/ ├── manual-config.json # Phase 1 ├── exploration/ # Phase 2 │ ├── exploration-architecture.json │ ├── exploration-ui-routes.json │ └── exploration-api-endpoints.json ├── sections/ # Phase 3 │ ├── section-overview.md │ ├── section-ui-guide.md │ ├── section-api-reference.md │ ├── section-configuration.md │ ├── section-troubleshooting.md │ └── section-examples.md ├── consolidation-summary.md # Phase 3.5 ├── api-docs/ # API documentation │ ├── frontend/ # TypeDoc output │ └── backend/ # Swagger/OpenAPI output ├── screenshots/ # Phase 4 │ ├── ss-*.png │ └── screenshots-manifest.json ├── iterations/ # Phase 6 │ ├── v1.html │ └── v2.html └── {软件名}-使用手册.html # Final Output
Reference Documents
Document Purpose
phases/01-requirements-discovery.md 用户配置收集
phases/02-project-exploration.md 项目类型检测
phases/02.5-api-extraction.md API 自动提取
phases/03-parallel-analysis.md 6 Agent 并行分析
phases/03.5-consolidation.md 整合与质量检查
phases/04-screenshot-capture.md Chrome MCP 截图
phases/05-html-assembly.md HTML 组装
phases/06-iterative-refinement.md 迭代优化
specs/quality-standards.md 质量标准
specs/writing-style.md 写作风格
templates/tiddlywiki-shell.html HTML 模板
templates/css/wiki-base.css 基础样式
templates/css/wiki-dark.css 暗色主题
scripts/bundle-libraries.md 库文件打包
scripts/api-extractor.md API 提取说明
scripts/extract_apis.py API 提取脚本
scripts/screenshot-helper.md 截图辅助