SuperAPI AI Directory
Partner中文AI newsFavorites
Skillslitho-document-skill

litho-document-skill

Writing & research

View repository

Updated 10-16 10:21

About this skill

Litho Document Skill (Pure Agent Version)

This Skill is thepure Agent parallel implementationof Litho (deepwiki-rs). It does not depend on any external binaries and fully autonomously completes the four-stage document generation pipeline through the Agent's tool-calling capabilities.

Target outputs：

  • 1.概述.md — C4 Context diagram + project overview + business value
  • 2.架构.md — C4 Container/Component diagram + architectural patterns + module responsibilities
  • 3.工作流.md — sequence diagrams + flowcharts + concurrency model + error handling
  • 4.Deep-Exploration/ — in-depth research documents for each domain module
  • 5.边界接口.md — inventory of external interfaces such as CLI/API/configuration
  • 6.数据库概览.md — ER diagram + table structures (conditionally triggered)

Four-stage pipeline overview

预处理 → 研究 → 编排 → 输出
 ↓        ↓       ↓       ↓
结构洞察   C1-C4   Markdown   文件持久化

Detailed execution guides for each stage are in references/ and are loaded by the Agent on demand. Only decision-level guidance is given below.

Stage 1: Preprocessing → Understand the project

Key decisions：

  • According toproject size, select a scanning strategy(see the quick paths below)
  • Establish a preprocessing report: project name, language, framework, core module list, README summary
  • The preprocessing report is thefoundational contextfor all subsequent stages, so it must be accurate

Quick paths(by project size):

Size Criteria Scanning strategy
Small <100 source files list_files Recursive + read_file all core files
Medium 100-500 source files list_files First-level directories only + read_file entry points + configuration + README + codebase_search semantic search
Large >500 source files Read only README + main configuration + entry files + view_file_outline core modules + grep_search precise search

Detailed steps are in references/phase1-preprocessing.md

Stage 2: Research → C4 multi-level analysis

Key decisions：

  • Execution order:C1 → C2 → [C3 in parallel](consistent with deepwiki-rs)
  • Domain modules must be fully covered：src/ : every subdirectory under it is identified as a candidate module, grouped using DDD (core domain/supporting domain/generic domain), and none may be omitted
  • Progressive depth control: analyze in tiers based on importance scores
  • Research outputs are written to the .litho-agent/ temporary directory for persistence (see the intermediate artifact strategy below)

Concurrent search: searches for Step 2.3 (architecture) + 2.4 (workflow) + 2.6 (boundaries) can be invoked concurrently; Step 2.5 (module depth) must come after 2.2 (domain modules)

Progressive depth：

importance Analysis depth Number of files read Mermaid diagrams
≥7 (core domain) In-depth analysis 5+ Complete flowchart + interaction tables
4-6 (supporting domain) Standard analysis 3 Simplified flowcharts
≤3 (generic domain) Brief description 1-2 No diagrams

Detailed steps are in references/phase2-research.md

Stage 3: Orchestration → Generate Markdown documents

Decision Points：

  • Generation Order: Boundary Interfaces → Overview → Module Depth (one by one) → Architecture → Workflow → Database (write those with fewer dependencies first)
  • Write Large Documents by Section: Architecture and Workflow are written in 2-3 passes (framework → supplementary sections)
  • Write Each Module Independently: Each Deep-Exploration document is written independently via write_to_file, and context is released immediately after writing
  • Code Reference Density: Each module has ≥3 file paths, ≥2 type names, and each row of the component table has a path column

⚠️ Narrative Writing Style (P0 Critical!)：

The generated documents must behuman-readable and friendly, rather than cold, PPT-style structured text. Core requirements:

  1. Each chapter must begin with a narrative summary: Use 2-4 sentences to first explain "what this chapter is about and why it matters"; do not immediately throw out tables or lists
  2. Tables and lists must be preceded and followed by interpretive paragraphs: Do not just provide structured data; explain "what this means and why it is designed this way"
  3. Design decisions must explain the "why": Do not only say "what was chosen"; also say "what was given up and why this choice was made"
  4. Use analogies and metaphors to build bridges of understanding: For example, compare Memory to a "delivery station", an Agent to a "worker", and a Pipeline to a "production line"
  5. Avoid cold stacking of headings: Chapter headings should naturally lead into the narrative, rather than ### 2.1 核心目标 → jumping directly to a list

For the detailed writing style guide and templates, see references/phase3-composition.md

Phase Four: Output → Verification and Delivery

Decision Points：

  • Mermaid diagram syntax validation (node IDs alphanumeric only, labels in double quotes, line breaks using <br/>）
  • Each document ends with a confidence score (1-10)
  • Generate an executive summary report (document list, number of modules covered, confidence table, items requiring manual review)

Database Document Trigger(triggered if any condition is met; otherwise write a minimal declaration file):

  • .sql/.sqlproj files | migrations//sql//db//database/ directories | ORM dependencies | DB configuration files

For the detailed verification checklist, see references/phase4-output.md

⚠️ Intermediate Artifact Persistence Strategy (Core!)

Problem

An Agent's single conversation context window is limited. As analysis deepens, earlier research results may be "forgotten" due to context pressure.

Solution

After completing each research step, persist key findingsto the .litho-agent/ temporary directory, rather than relying solely on the conversation context:

.litho-agent/
├── preprocessing.md        ← 预处理报告（阶段一产出）
├── c1-system-context.md    ← 系统上下文报告
├── c2-domain-modules.md    ← 领域模块报告
├── architecture.md         ← 架构研究报告
├── workflow.md             ← 工作流研究报告
├── boundary.md             ← 边界接口报告
├── database.md             ← 数据库报告（条件）
└── modules/                ← 各模块深度报告
    ├── llm.md
    ├── cache.md
    └── ...

How to Operate：

  • After completing each research Step → write_to_file write to the .litho-agent/ corresponding file
  • When the orchestration phase needs a certain report → read_file read from .litho-agent/ Read
  • After the final output is complete → delete the .litho-agent/ temporary directory (optionally keep it for review)

Key Advantages：

  • Under context pressure, early research data can be released and read again when needed
  • Research results are not lost; even with very long conversations, data integrity during the orchestration phase is guaranteed
  • Equivalent to the Memory scope mechanism of deepwiki-rs

Tool usage priority

  1. codebase_search — Semantic search (find code for "what to do")
  2. grep_search — Exact search (find specific symbols/class names/function names)
  3. view_file_outline — Quickly obtain file structure (without reading everything)
  4. read_file — Deep read of key files (entry points, core modules)
  5. list_files — Scan directory structure

Reference documentation (load on demand)

  • references/phase1-preprocessing.md — Detailed preprocessing steps + search strategy
  • references/phase2-research.md — Detailed guide for each Agent + output format
  • references/phase3-composition.md — Document templates + chapter-by-chapter strategy + code citation conventions
  • references/phase4-output.md — Mermaid verification checklist + confidence scoring template
  • references/doc-templates.md — Mermaid diagram syntax quick reference + type selection guide