software-manual

name	software-manual
description	Generate interactive TiddlyWiki-style HTML software manuals with screenshots, API docs, and multi-level code examples. Use when creating user guides, software documentation, or API references. Triggers on "software manual", "user guide", "generate manual", "create docs".
allowed-tools	Task, AskUserQuestion, Read, Bash, Glob, Grep, Write, mcp__chrome__*

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

1. 主 Agent 编排，子 Agent 执行: 所有繁重计算委托给 universal-executor 子 Agent
2. Brief Returns: Agents return path + summary, not full content (avoid context overflow)
3. System Agents: 使用 cli-explore-agent (探索) 和 universal-executor (执行)
4. 成熟库内嵌: marked.js (MD 解析) + highlight.js (语法高亮)，无 CDN 依赖
5. Single-File HTML: TiddlyWiki-style interactive document with embedded resources
6. 动态标签: 根据实际章节自动生成导航标签

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)

1. Search: Full-text search with result highlighting
2. Collapse/Expand: Per-section collapsible content
3. Tag Navigation: Filter by category tags
4. Theme Toggle: Light/Dark mode with localStorage persistence
5. Single File: All CSS/JS/images embedded as Base64
6. Offline: Works without internet connection
7. 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	截图辅助