ted-mosby

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ted Mosby - Architecture Wiki Generator

Ted Mosby - 架构维基文档生成器

Generate comprehensive architectural documentation for any codebase with source code traceability (file:line references).

为任意代码库生成具备源代码可追溯性（文件:行号引用）的全面架构文档。

Overview

概述

Ted Mosby creates architectural wikis that help developers understand codebases. Every concept links directly to source code, so you can navigate from documentation to implementation.

Output includes:

Architecture overview with Mermaid diagrams
Module documentation with source traceability
Data flow documentation
Getting started guides
Interactive static site with search, keyboard nav, dark mode

Ted Mosby 生成的架构维基文档可帮助开发者理解代码库。每个概念都直接链接到源代码，让你可以从文档导航到实现细节。

输出内容包括：

带有 Mermaid 图的架构概述
具备源代码可追溯性的模块文档
数据流文档
快速入门指南
支持搜索、键盘导航和深色模式的交互式静态站点

When to Use This Skill

适用场景

Use this skill when the user wants to:

Document a codebase or project architecture
Generate a wiki or documentation site
Create architecture diagrams with source references
Understand and document how a project is structured
Produce navigable documentation with file:line traceability

Trigger phrases:

"Generate docs for this project"
"Create architecture documentation"
"Document this codebase"
"Make a wiki for this repo"
"Help me understand this project's structure"

当用户需要以下服务时，可使用此技能：

记录代码库或项目架构
生成维基或文档站点
创建带有源代码引用的架构图
理解并记录项目的结构
生成带有文件:行号可追溯性的可导航文档

触发短语：

"为这个项目生成文档"
"创建架构文档"
"记录这个代码库"
"为这个仓库制作维基"
"帮我理解这个项目的结构"

Prerequisites

前提条件

Required

必需项

Node.js >= 18.0.0
Anthropic API key (
```
ANTHROPIC_API_KEY
```
environment variable)

Node.js >= 18.0.0
Anthropic API 密钥（需设置
```
ANTHROPIC_API_KEY
```
环境变量）

Check Prerequisites

检查前提条件

bash

undefined

bash

undefined

Verify Node.js version

验证 Node.js 版本

node --version # Should be >= 18.0.0

node --version # 版本需 >= 18.0.0

Verify API key is set

验证 API 密钥是否已设置

echo $ANTHROPIC_API_KEY # Should show your key

undefined

echo $ANTHROPIC_API_KEY # 应显示你的密钥

undefined

Install Ted Mosby

安装 Ted Mosby

bash

npm install -g ted-mosby

bash

npm install -g ted-mosby

Quick Start Commands

快速启动命令

Basic Wiki Generation

基础维基文档生成

bash

undefined

bash

undefined

Generate wiki for current directory

为当前目录生成维基文档

ted-mosby generate -r .

Generate wiki for a specific project

为指定项目生成维基文档

ted-mosby generate -r ./my-project

Generate wiki for a GitHub repository

为 GitHub 仓库生成维基文档

ted-mosby generate -r https://github.com/user/repo

undefined

ted-mosby generate -r https://github.com/user/repo

undefined

With Interactive Site

生成带交互式站点的文档

bash

undefined

bash

undefined

Generate wiki + interactive static site

生成维基文档 + 交互式静态站点

ted-mosby generate -r ./my-project --site

Custom title and theme

自定义标题和主题

ted-mosby generate -r ./my-project --site --site-title "My Project Docs" --theme dark

Generate site only (if wiki already exists)

仅生成站点（若维基文档已存在）

ted-mosby generate -r ./my-project --site-only

undefined

ted-mosby generate -r ./my-project --site-only

undefined

Other Useful Options

其他实用选项

bash

undefined

bash

undefined

Focus on specific subdirectory

聚焦特定子目录

ted-mosby generate -r ./my-project -p src/core

Custom output directory

自定义输出目录

ted-mosby generate -r ./my-project -o ./docs/architecture

Verbose output (see agent progress)

详细输出（查看 Agent 运行进度）

ted-mosby generate -r ./my-project -v

Estimate time/cost before running (dry run)

运行前估算时间/成本（试运行）

ted-mosby generate -r ./my-project -e

undefined

ted-mosby generate -r ./my-project -e

undefined

Workflow

工作流程

Step 1: Gather Requirements

步骤 1：确认需求

Before running Ted Mosby, clarify with the user:

Target path - What directory or repo to document?
Output location - Where should the wiki go? (default:
```
./wiki
```
)
Site generation - Do they want an interactive static site?
Focus area - Any specific subdirectory to focus on?
Theme preference - Light, dark, or auto?

运行 Ted Mosby 前，需与用户确认：

目标路径 - 要记录的目录或仓库是什么？
输出位置 - 维基文档应保存到哪里？（默认：
```
./wiki
```
）
站点生成 - 是否需要交互式静态站点？
聚焦区域 - 是否有需要重点关注的子目录？
主题偏好 - 亮色、暗色或自动适配？

Step 2: Pre-flight Checks

步骤 2：预检查

Verify the environment is ready:

bash

undefined

验证环境是否就绪：

bash

undefined

Check Node.js version

检查 Node.js 版本

node --version

Verify ted-mosby is installed

验证 ted-mosby 是否已安装

which ted-mosby || echo "Run: npm install -g ted-mosby"

which ted-mosby || echo "运行: npm install -g ted-mosby"

Check API key

检查 API 密钥

[ -z "$ANTHROPIC_API_KEY" ] && echo "Set ANTHROPIC_API_KEY environment variable"

undefined

[ -z "$ANTHROPIC_API_KEY" ] && echo "设置 ANTHROPIC_API_KEY 环境变量"

undefined

Step 3: Run Generation

步骤 3：运行生成命令

Choose the appropriate command based on user needs:

User Wants	Command
Basic wiki only	`ted-mosby generate -r ./project`
Wiki + interactive site	`ted-mosby generate -r ./project --site`
Site with custom title	`ted-mosby generate -r ./project --site --site-title "Docs"`
Dark theme site	`ted-mosby generate -r ./project --site --theme dark`
Focus on subdirectory	`ted-mosby generate -r ./project -p src/core`
Large codebase	`ted-mosby generate -r ./project --max-chunks 5000`
Quick iteration	`ted-mosby generate -r ./project --skip-index`

根据用户需求选择合适的命令：

用户需求	命令
仅基础维基文档	`ted-mosby generate -r ./project`
维基文档 + 交互式站点	`ted-mosby generate -r ./project --site`
带自定义标题的站点	`ted-mosby generate -r ./project --site --site-title "Docs"`
暗色主题站点	`ted-mosby generate -r ./project --site --theme dark`
聚焦子目录	`ted-mosby generate -r ./project -p src/core`
大型代码库	`ted-mosby generate -r ./project --max-chunks 5000`
快速迭代	`ted-mosby generate -r ./project --skip-index`

Step 4: Review Output

步骤 4：检查输出

After generation completes:

Wiki location:
```
./wiki/README.md
```
(or custom output dir)
Site location:
```
./wiki/site/index.html
```
(if
```
--site
```
used)
Open site: Open
```
index.html
```
in browser

生成完成后：

维基文档位置：
```
./wiki/README.md
```
（或自定义输出目录）
站点位置：
```
./wiki/site/index.html
```
（若使用
```
--site
```
参数）
打开站点：在浏览器中打开
```
index.html
```

Step 5: Fix Issues (if needed)

步骤 5：修复问题（如有需要）

If there are broken links or missing pages:

bash

undefined

若存在链接失效或页面缺失的情况：

bash

undefined

Check for and generate missing pages

检查并生成缺失的页面

ted-mosby continue -r ./my-project -o ./wiki

Verify only (don't generate)

仅验证（不生成内容）

ted-mosby continue -r ./my-project -o ./wiki --verify-only

undefined

ted-mosby continue -r ./my-project -o ./wiki --verify-only

undefined

Output Structure

输出结构

wiki/
├── README.md                    # Navigation entry point
├── architecture/
│   ├── overview.md              # System architecture + Mermaid diagrams
│   └── data-flow.md             # Data flow documentation
├── components/
│   └── {module}/
│       └── index.md             # Per-module documentation
├── guides/
│   └── getting-started.md       # Quick start guide
├── glossary.md                  # Concept index
└── site/                        # (with --site flag)
    ├── index.html               # Interactive site entry
    ├── styles.css
    └── scripts.js

wiki/
├── README.md                    # 导航入口
├── architecture/
│   ├── overview.md              # 系统架构 + Mermaid 图
│   └── data-flow.md             # 数据流文档
├── components/
│   └── {module}/
│       └── index.md             # 模块专属文档
├── guides/
│   └── getting-started.md       # 快速入门指南
├── glossary.md                  # 概念索引
└── site/                        # （使用 --site 参数时生成）
    ├── index.html               # 交互式站点入口
    ├── styles.css
    └── scripts.js

Source Traceability

源代码可追溯性

Every architectural concept includes clickable source references:

markdown

undefined

每个架构概念都包含可点击的源代码引用：

markdown

undefined

Authentication Flow

认证流程

The authentication system uses JWT tokens for stateless auth.

Source:

src/auth/jwt-provider.ts:23-67


This allows developers to navigate directly from documentation to implementation.

认证系统使用 JWT 令牌实现无状态认证。

源代码：

src/auth/jwt-provider.ts:23-67


这让开发者可以直接从文档导航到实现代码。

Interactive Site Features

交互式站点特性

When

--site

is used, the generated site includes:

Feature	Description
Full-text search	Instant search across all pages (Cmd/Ctrl+K)
Keyboard navigation	Arrow keys, vim-style (j/k/h/l)
Dark/light mode	Respects system preference or manual toggle
Table of contents	Auto-generated from headings
Mobile responsive	Works on all devices
Offline capable	No server required
Mermaid diagrams	Rendered automatically

使用

--site

参数时，生成的站点包含以下特性：

特性	描述
全文搜索	跨所有页面的即时搜索（Cmd/Ctrl+K）
键盘导航	支持方向键、Vim 风格快捷键（j/k/h/l）
明暗模式切换	适配系统偏好或手动切换
目录	根据标题自动生成
移动端适配	支持所有设备
离线可用	无需服务器支持
Mermaid 图渲染	自动渲染 Mermaid 图

Command Reference

命令参考

generate

- Create wiki documentation

generate

- 创建维基文档

Option	Description	Default
`-r, --repo <path/url>`	Repository path or GitHub URL (required)	-
`-o, --output <dir>`	Output directory for wiki	`./wiki`
`-p, --path <path>`	Focus on specific directory	-
`-s, --site`	Generate interactive static site	-
`--site-only`	Generate site only (skip wiki)	-
`--site-title <title>`	Custom site title	Project name
`--theme <theme>`	Site theme: light, dark, auto	`auto`
`-v, --verbose`	Show detailed progress	-
`-e, --estimate`	Estimate time/cost (dry run)	-
`--max-chunks <n>`	Limit indexed chunks (for large repos)	unlimited
`--skip-index`	Use cached embeddings index	-
`--direct-api`	Use Anthropic API directly	-
`-m, --model <model>`	Claude model to use	`claude-sonnet-4-20250514`
`--max-turns <n>`	Limit agent iterations	200

选项	描述	默认值
`-r, --repo <path/url>`	仓库路径或 GitHub URL（必填）	-
`-o, --output <dir>`	维基文档输出目录	`./wiki`
`-p, --path <path>`	聚焦特定目录	-
`-s, --site`	生成交互式静态站点	-
`--site-only`	仅生成站点（跳过维基文档）	-
`--site-title <title>`	自定义站点标题	项目名称
`--theme <theme>`	站点主题：light, dark, auto	`auto`
`-v, --verbose`	显示详细运行进度	-
`-e, --estimate`	估算时间/成本（试运行）	-
`--max-chunks <n>`	限制索引块数量（针对大型仓库）	无限制
`--skip-index`	使用缓存的嵌入索引	-
`--direct-api`	直接使用 Anthropic API	-
`-m, --model <model>`	使用的 Claude 模型	`claude-sonnet-4-20250514`
`--max-turns <n>`	限制 Agent 迭代次数	200

continue

- Resume/fix wiki generation

continue

- 恢复/修复维基文档生成

Option	Description	Default
`-r, --repo <path>`	Repository path (required)	-
`-o, --output <dir>`	Wiki output directory	`./wiki`
`--verify-only`	Only check, don't generate	-
`--skip-index`	Use cached embeddings index	-
`-v, --verbose`	Show detailed progress	-

选项	描述	默认值
`-r, --repo <path>`	仓库路径（必填）	-
`-o, --output <dir>`	维基文档输出目录	`./wiki`
`--verify-only`	仅检查，不生成内容	-
`--skip-index`	使用缓存的嵌入索引	-
`-v, --verbose`	显示详细运行进度	-

Large Codebase Options

大型代码库适配选项

For repositories with 10,000+ files:

bash

undefined

针对包含 10,000+ 文件的仓库：

bash

undefined

Limit indexed chunks (reduces memory usage)

限制索引块数量（减少内存占用）

ted-mosby generate -r ./large-project --max-chunks 5000

Reduce search results per query

减少每次查询的搜索结果数量

ted-mosby generate -r ./large-project --max-results 5

Batched processing (for very large repos)

批量处理（针对超大型仓库）

ted-mosby generate -r ./large-project --batch-size 3000

undefined

ted-mosby generate -r ./large-project --batch-size 3000

undefined

Typical Runtime

典型运行时间

Codebase Size	Approximate Time
Small (<50 files)	1-2 minutes
Medium (50-200 files)	2-5 minutes
Large (200+ files)	5-10 minutes

Use

--estimate

to get a cost/time estimate before running.

代码库规模	大致运行时间
小型（<50 个文件）	1-2 分钟
中型（50-200 个文件）	2-5 分钟
大型（200+ 个文件）	5-10 分钟

可使用

--estimate

参数在运行前获取成本/时间估算。

Troubleshooting

故障排除

"Credit balance is too low" error

"信用余额不足" 错误

Use direct API mode:

bash

ted-mosby generate -r ./my-project --direct-api

使用直接 API 模式：

bash

ted-mosby generate -r ./my-project --direct-api

Out of memory on large repos

大型仓库内存不足

Limit indexed chunks:

bash

ted-mosby generate -r ./large-project --max-chunks 5000 --batch-size 3000

限制索引块数量：

bash

ted-mosby generate -r ./large-project --max-chunks 5000 --batch-size 3000

Slow re-runs during development

开发期间重新运行速度慢

Skip re-indexing:

bash

ted-mosby generate -r ./my-project --skip-index

跳过重新索引：

bash

ted-mosby generate -r ./my-project --skip-index

Missing pages / broken links

页面缺失 / 链接失效

Use the continue command:

bash

ted-mosby continue -r ./my-project -o ./wiki

使用 continue 命令：

bash

ted-mosby continue -r ./my-project -o ./wiki

Example Conversation

对话示例

User: "Can you document this project's architecture?"

Assistant: I'll use Ted Mosby to generate architectural documentation for your project.

First, let me verify the prerequisites are in place, then generate the wiki with an interactive site:

bash

undefined

用户： "你能记录这个项目的架构吗？"

助手： 我将使用 Ted Mosby 为你的项目生成架构文档。

首先，我会验证前提条件是否满足，然后生成带交互式站点的维基文档：

bash

undefined

Generate wiki with interactive site

生成带交互式站点的维基文档

ted-mosby generate -r . --site --site-title "Project Architecture"


This will create:
- `wiki/README.md` - Main navigation
- `wiki/architecture/overview.md` - Architecture diagrams
- `wiki/site/index.html` - Interactive documentation site

ted-mosby generate -r . --site --site-title "Project Architecture"


这将创建：
- `wiki/README.md` - 主导航页
- `wiki/architecture/overview.md` - 架构图文档
- `wiki/site/index.html` - 交互式文档站点