h
husu/loom
一个写接口文档的AI Agent。支持使用Vibe coding 的方式，编写接口文档，同时自带友好的文档查看工具与接口Mock工具
创建于 2026/5/15更新于 今天
README
由 Gemini 翻译整理
Loom
简体中文 | English
基于 AI 的 JSON Schema 文档生成器，集成 TUI 交互、Web 浏览器与 Mock 服务
✨ 特性
- 🤖 AI 驱动的 Schema 生成 —— 通过 TUI 聊天界面与大模型（DeepSeek、OpenAI）对话生成和更新 JSON Schema API 文档
- 🧩 实体（Entity）建模 —— 在
docs/entities中维护可复用的实体 Schema，通过x-entity-ref在接口 Schema 中引用 - 📚 现代 Web 浏览器 —— 基于 React 的 SPA，用于浏览模块、接口和实体，支持交互式 Schema 渲染
- ⚡ Mock 服务 —— 基于 JSON Schema 动态生成贴近真实的 Mock 数据
- 🖥️ TUI 内服务控制 —— 直接在 TUI 中启动/停止/重启 Mock 与 Web Viewer（
/mock、/view） - 🗂️ Manifest 索引 —— 内置
loom manifest rebuild命令重建依赖/索引一致性 - ⬆️ 自动升级提示 —— 启动时检查 npm 上的新版本，确认后可自动升级
- 🔧 TypeScript 优先 —— 完整类型定义，现代化的 TypeScript 架构
📦 安装
环境要求
- Node.js ≥ 18.0.0
- npm 或 yarn
- DeepSeek API Key（必需）
全局安装
npm install -g @vegamo/loom
# 或
yarn global add @vegamo/loom
⚙️ 配置
配置文件
默认全局配置路径：
- macOS/Linux:
~/.loom/config.json - Windows:
%APPDATA%/loom/config.json
首次运行 loom chat 时，会以交互向导的形式引导你创建/更新该全局配置文件。
聊天首次引导的默认值：
provider：deepseekmodel：deepseek-chatbaseURL：https://api.deepseek.com/v1apiKey：必填，需由用户输入
你也可以手动创建全局配置：
{
"outDir": "docs",
"llm": {
"provider": "deepseek",
"model": "deepseek-chat",
"baseURL": "https://api.deepseek.com/v1",
"apiKey": "your_deepseek_api_key",
"temperature": 0.7,
"maxTokens": 2000
},
"serve": {
"port": 3000,
"host": "0.0.0.0"
},
"mock": {
"port": 3001,
"host": "0.0.0.0"
}
}
docs/ 目录仍保留在各项目目录中（通过 --dir 指定），不会被移动到全局存储。
🚀 快速开始
1. 生成 API 文档
# 启动交互式 TUI 来生成 JSON Schema
loom chat
# 或指定项目目录
loom chat --dir ./my-api-project
在 loom chat 中，你也可以控制本地服务：
/mock、/mock stop、/mock restart [port]/view、/view stop、/view restart [port]
2. 浏览文档
# 启动 Web 文档浏览器
loom view
# 或指定端口
loom view --port 8080
3. 启动 Mock 服务
# 启动 Mock API 服务
loom mock
# 或指定端口
loom mock --port 8081
4. 组合服务（推荐）
# 在同一端口同时启动 Viewer 和 Mock 服务
loom serve
# 访问入口：
# - Web Viewer: http://localhost:3000
# - Mock API: http://localhost:3000/mock/...
5. 升级 Loom
# 手动触发升级
loom upgrade
执行其它命令时，Loom 也会检查 npm 是否有新版本。
发现新版本时，确认即可自动升级。
📖 使用指南
loom chat
通过 AI 对话生成 JSON Schema 文档的交互式终端 UI。
loom chat [options]
Options:
-d, --dir 目标项目目录（默认：当前目录）
-h, --help 显示帮助
典型流程：
- 运行
loom chat - 用自然语言描述你的 API 接口
- AI 生成结构合理的 JSON Schema
- Schema 文件被保存到
docs/目录（可配置）
内置聊天命令：
- 输入提示：
Enter发送，Shift+Enter/Alt+Enter换行，↑/↓浏览历史记录（跨会话持久化），Tab自动补全命令 /help—— 显示命令帮助/reset—— 重置对话历史/list—— 列出已生成的 Schema 文件/mock、/mock stop、/mock restart [port]—— 管理 Mock 服务/view、/view stop、/view restart [port]—— 管理 Web Viewer/scan—— 通过 LLM 从源码中识别 API；/scan resume、/scan reset管理断点/abort—— 中止当前请求/exit—— 退出 Loom
loom view
基于 React SPA 的现代化 Web 文档浏览器。
loom view [options]
Options:
-p, --port 端口号（默认：3000）
-d, --dir 目标项目目录（默认：当前目录）
-h, --help 显示帮助
特性：
- 📁 按模块浏览，显示接口数量
- 🧩 浏览
docs/entities中的实体 - 🔍 在模块与接口范围内实时搜索
- 📊 类 Swagger 的 Schema 表格视图，覆盖所有请求/响应区段（query、path、headers、body）
- 🔗 渲染接口请求/响应时自动解析
x-entity-ref - 🎨 简洁的响应式 UI，深色侧边栏
- 🔗 支持接口的直链访问
loom mock
基于 JSON Schema 动态生成数据的 Mock API 服务。
loom mock [options]
Options:
-p, --port 端口号（默认：3001）
-d, --dir 目标项目目录（默认：当前目录）
-h, --help 显示帮助
特性：
- 🚀 自动从 JSON Schema 文件注册路由
- 🎲 基于 mock-json-schema 智能生成 Mock 数据
- 📡 支持所有 HTTP 方法（GET、POST、PUT、DELETE、PATCH）
- 🔧 可配置响应状态码与 Schema
loom serve
组合服务，同时运行 Web Viewer 与 Mock 服务。
loom serve [options]
Options:
-p, --port 端口号（默认：3000）
-d, --dir 目标项目目录（默认：当前目录）
-h, --help 显示帮助
URL 结构：
http://localhost:3000/—— Web 文档浏览器http://localhost:3000/api/docs—— 文档 APIhttp://localhost:3000/api/schemas—— Schema 文件 APIhttp://localhost:3000/api/entities—— 实体文件 APIhttp://localhost:3000/mock/...—— Mock API 路由
loom manifest rebuild
重建文档清单索引文件 .loom-manifest.json，确保依赖/索引一致。
loom manifest rebuild [options]
Options:
-d, --dir 目标项目目录（默认：当前目录）
-h, --help 显示帮助
loom upgrade
将 loom 升级到 npm 上的最新版本。
loom upgrade
📝 JSON Schema 格式
Loom 使用一套为 API 文档优化的自定义 JSON Schema 格式：
{
"$schema": "http://json-