@vegamo/loom
Advanced tools
简体中文 | English
基于 AI 的 JSON Schema 文档生成器，集成 TUI 交互、Web 浏览器与 Mock 服务
docs/entities 中维护可复用的实体 Schema，通过 x-entity-ref 在接口 Schema 中引用/mock、/view）loom manifest rebuild 命令重建依赖/索引一致性loom plans/purchase/publish，也支持 loom chat 内 /plans、/purchase、/publishnpm install -g @vegamo/loom
# 或
yarn global add @vegamo/loom
默认全局配置路径：
~/.loom/config.json%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 指定），不会被移动到全局存储。
# 启动交互式 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]# 启动 Web 文档浏览器
loom view
# 或指定端口
loom view --port 8080
# 启动 Mock API 服务
loom mock
# 或指定端口
loom mock --port 8081
# 在同一端口同时启动 Viewer 和 Mock 服务
loom serve
# 访问入口：
# - Web Viewer: http://localhost:3000
# - Mock API: http://localhost:3000/mock/...
# 外层 CLI 用法
loom plans
loom purchase basic_annual
loom publish
# 或进入 Loom TUI 后使用斜杠命令
loom chat
/plans
/purchase basic_annual
/publish
首次执行 loom plans / loom purchase / loom publish，或在 TUI 内执行 /plans / /purchase / /publish 时，Loom 会自动生成并保存发布 token：
~/.loom/auth.json
默认发布服务地址是：
https://loom-server.vegamo.cn
这个地址内置在 Loom CLI 中；~/.loom/auth.json 只保存用户身份 token。
用户不需要手动执行 token 初始化命令。发布时，Loom 会在当前项目根目录写入项目级配置：
.loom/project.json
该文件保存稳定的 projectSlug、名称、描述和可见性。后续即使项目目录改名，loom publish 或 /publish 仍会继续发布到同一个服务端项目。
如果当前 token 没有 active pro，也没有可用 basic slot，loom publish 和 /publish 会停止上传并提示执行 loom plans / /plans 或购买命令。
# 手动触发升级
loom upgrade
执行其它命令时，Loom 也会检查 npm 是否有新版本。
发现新版本时，确认即可自动升级。
loom chat通过 AI 对话生成 JSON Schema 文档的交互式终端 UI。
loom chat [options]
Options:
-d, --dir <path> 目标项目目录（默认：当前目录）
-h, --help 显示帮助
典型流程：
loom chatdocs/ 目录（可配置）内置聊天命令：
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 <dir> —— 通过 LLM 从源码中识别 API；/scan resume、/scan reset 管理断点/abort —— 中止当前请求/exit —— 退出 Loomloom view基于 React SPA 的现代化 Web 文档浏览器。
loom view [options]
Options:
-p, --port <number> 端口号（默认：3000）
-d, --dir <path> 目标项目目录（默认：当前目录）
-h, --help 显示帮助
特性：
docs/entities 中的实体x-entity-refloom mock基于 JSON Schema 动态生成数据的 Mock API 服务。
loom mock [options]
Options:
-p, --port <number> 端口号（默认：3001）
-d, --dir <path> 目标项目目录（默认：当前目录）
-h, --help 显示帮助
特性：
loom serve组合服务，同时运行 Web Viewer 与 Mock 服务。
loom serve [options]
Options:
-p, --port <number> 端口号（默认：3000）
-d, --dir <path> 目标项目目录（默认：当前目录）
-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 路由发布相关能力同时支持外层 CLI 和 loom chat 内斜杠命令。
loom plans / /plans查看可购买套餐和当前发布权益。该命令会自动生成本地发布 token，并调用服务端查询当前 pro、slot 和项目状态。
loom plans
/plans
loom purchase / /purchase为当前自动生成的发布 token 购买或续费套餐。
loom purchase <basic_annual|pro_annual>
/purchase <basic_annual|pro_annual>
命令会创建支付订单、在 TUI 中显示二维码，并在支付后轮询确认结果。支付成功后即可执行 loom publish 或 /publish。
loom publish / /publish发布当前项目的 docs/ 文档包到 loom-server。项目不存在时，服务端会尝试创建项目；如果没有可用权益，命令会提示先购买。
loom publish
/publish
项目身份由当前 token 和 projectSlug 共同确定。CLI 会把项目级发布配置写入 .loom/project.json：
{
"projectSlug": "my-api",
"name": "My API",
"description": "",
"visibility": "public"
}
后续发布默认复用该文件中的 projectSlug；如需切换到新项目，需要调整 .loom/project.json 中的项目配置。
loom manifest rebuild重建文档清单索引文件 .loom-manifest.json，确保依赖/索引一致。
loom manifest rebuild [options]
Options:
-d, --dir <path> 目标项目目录（默认：当前目录）
-h, --help 显示帮助
loom upgrade将 loom 升级到 npm 上的最新版本。
loom upgrade
Loom 使用一套为 API 文档优化的自定义 JSON Schema 格式：
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Authentication API",
"description": "User authentication endpoints",
"version": "1.0.0",
"endpoints": [
{
"path": "/api/auth/login",
"method": "POST",
"summary": "User login",
"description": "Authenticate user with credentials",
"tags": ["auth"],
"request": {
"headers": {
"Content-Type": { "type": "string", "enum": ["application/json"] }
},
"body": {
"type": "object",
"properties": {
"username": { "type": "string" },
"password": { "type": "string" }
},
"required": ["username", "password"]
}
},
"response": {
"200": {
"type": "object",
"properties": {
"token": { "type": "string" },
"user": { "type": "object" }
}
},
"400": {
"type": "object",
"properties": {
"error": { "type": "string" }
}
}
}
}
]
}
Loom 支持以下位置的可复用实体 Schema：
docs/entities/*.entity.schema.json
实体文件示例：
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "User",
"description": "Reusable user entity",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string", "format": "email" }
},
"required": ["id", "name", "email"]
}
在接口 Schema 中通过 x-entity-ref 引用实体：
{
"user": {
"x-entity-ref": {
"entity": "User",
"pick": ["id", "name", "email"]
}
}
}
支持的形式：
"x-entity-ref": "User""x-entity-ref": { "entity": "User", "pick": ["id", "name"] }loom/
├── src/
│ ├── agents/ # 支持工具调用的 AI Agent 系统
│ │ ├── core/ # Agent 核心逻辑
│ │ └── memory/ # 对话记忆管理
│ ├── llm/ # LLM 客户端（DeepSeek、OpenAI）
│ │ ├── client.ts # 流式 LLM 客户端
│ │ └── config.ts # LLM 配置
│ ├── tools/ # Agent 工具系统
│ │ ├── schema-gen.ts # Schema 生成工具
│ │ ├── schema-validate.ts # Schema 校验工具
│ │ ├── file-ops.ts # Schema 文件操作工具
│ │ ├── entity-file-ops.ts # 实体文件操作工具
│ │ └── entity-workflow.ts # 实体影响/同步/校验工具
│ ├── tui/ # 终端 UI（聊天界面）
│ │ ├── app.tsx # TUI 主应用
│ │ └── components/ # TUI 的 React 组件
│ ├── view/ # Web 文档浏览器
│ │ ├── server.ts # Fastify Web 服务
│ │ ├── routes/ # API 路由
│ │ ├── frontend/ # React SPA 前端
│ │ └── public/ # 静态资源
│ ├── mocks/ # Mock 服务
│ │ ├── server.ts # Mock 服务实现
│ │ ├── router.ts # 动态路由注册
│ │ └── generator.ts # Mock 数据生成
│ ├── shared/ # 共享工具
│ │ ├── config.ts # 配置加载器
│ │ ├── entity-utils.ts # 实体读写/引用工具
│ │ ├── manifest-utils.ts # 清单索引构建器
│ │ ├── schema-entity-resolver.ts # 给 Viewer API 用的 x-entity-ref 解析器
│ │ ├── types.ts # TypeScript 类型定义
│ │ └── logger.ts # 日志工具
│ ├── serve.ts # Viewer + Mock 组合服务
│ └── index.ts # CLI 入口
├── docs/ # 生成的 Schema 文件
├── scripts/ # 构建脚本
├── dist/ # 编译输出
└── package.json
# 构建 TypeScript 后端
npm run build
# 构建 React 前端
npm run build:view
# 同时构建（推荐）
npm run build:all
# 启动 TypeScript 开发模式
npm run dev
# 前端开发的 watch 模式
npm run dev:view
src/llm/config.ts 与 src/llm/client.tssrc/tools/ 下，并在 src/agents/core/agent.ts 中注册src/view/frontend/components/src/view/routes/ 或 src/mocks/router.ts维护者发布新版本到 npm 的步骤：
# 登录 npm（仅首次）
npm login
# 视需要更新版本号
npm version patch # 或 minor、major
# 构建并打包
npm run build:all
# 发布到 npm
npm publish
# 或先用 dry-run 预演
npm publish --dry-run
包内容包括：
dist/）loom）打包相关配置：
prepack 脚本确保打包前会重新构建.npmignore 排除源码与开发期产物loom plans 和 TUI 内 /plans，同时展示可购买套餐和当前 token 的 pro/slot/项目状态.loom/project.json，loom publish / /publish 首次确定 projectSlug 后自动落盘，目录改名后仍发布到同一个项目loom token / loom token show 流程；首次执行发布命令或埋点时自动生成 loom_live_ token 并保存到 ~/.loom/auth.jsonloom publish / /publish 发布前检查权益；没有 active pro 或可用 basic slot 时停止上传并提示执行 plans / purchaseuserToken 改为复用发布 token，方便关联使用、购买和发布行为/scan 生成 endpoint response 时，不再把 CommonResult / Result / ApiResponse 等通用响应壳整体作为 response 引用，避免把真实 data payload 抹成泛型 objectdata 字段显示不完整的问题；对于有实际返回体的接口，data 应生成具体 schema 或具体实体引用，无 payload 的成功响应则标记为可空/可选/scan 与 /scan resume 新增 --lang zh|en 参数。Phase 3（generate-entity）和 Phase 4（generate-endpoint）按所选语言输出 description 与 summary 文本。默认 zh；可通过 ~/.loom/config.json 中的 scan.language 全局覆盖，或在执行命令时使用该参数/scan 的 LLM 缓存对 Phase 3/4 改为按语言区分（键末尾追加 :zh 或 :en），Phase 1/2 仍跨语言共享。切换语言只会失效真正会变的那一半phase1 extract-endpoints、phase2 extract-entities、phase3 generate-entity、phase4 generate-endpoint）。升级自动迁移：旧版本的 Phase 1/2 记录继续命中；Phase 3/4 记录会在下次扫描时重新生成CACHE_VERSION 一刀切清空机制。缓存失效改由 source-hash + 每条记录的形状校验驱动。如有 prompt 重大变更，用户可手动 rm <outDir>/.loom-scan-cache.json 清空summary 时，不再回退到英文 brief，而是退化为 <METHOD> <path>，避免一句英文混在中文文档里/scan <dir> —— 多语言、LLM 驱动的源码 API 识别。识别框架、用 glob 收紧文件范围、提取接口标识（Phase 1）、识别并生成实体 Schema（Phase 1.5），然后按路由前缀生成单文件 Schema（Phase 2，通过 x-entity-ref 引用实体）/scan resume 和 /scan reset —— 基于断点继续被中断的扫描，或丢弃已保存的断点/scan 的 LLM 输出缓存，按文件内容哈希索引（<outDir>/.loom-scan-cache.json）；增量扫描会跳过未变更的文件，可节省 25 分钟以上。可使用 --no-cache 强制调用 LLMloom chat 的输入历史持久化在全局 ~/.loom/history.jsonl（上限 100 条），上下方向键跨会话浏览src/tui/commands.ts），让 Header 面板、/help 文案与自动补全列表共享一份数据源{ userToken, action: "used" }。userToken 复用自动生成的发布 token，持久化于 ~/.loom/auth.json，离线时落到 ~/.loom/telemetry-outbox.jsonl<outDir>/.loom-scan.log，以及来自 scan-failures.ts 的原始响应快照，便于排查 LLM 问题/scan 容忍推理模型的输出格式（例如 DeepSeek-R1 在同一响应中先输出 <think> 再给出最终 JSON）APIConnectionError 与 SDK 内部 abort 归为可重试的 timeout/scan resume，现在会提示 "scan already complete" 而不是默默重跑 analyzerequired[] 表达，而不是 type 联合doneCount 自增过程中保留 group 冲突策略/scan resume 能从正确步骤继续/help 同步（现在包含 /scan 与 /abort）/init 命令；若项目里存在 requirement.md，仍会作为 agent 上下文加载<name>.mock.json 存储（每个接口同时只有一个生效 override）/mock/<path> 会真的返回 HTTP 400）request schema 生成（path、query、headers、body 全部填充示例值）@cname、@integer(1,100)、'list|1-5': [...] 等）—— 模板原样存储，每次请求时再展开loom view）或组合服务（loom serve）时的 setNotFoundHandler 重复注册错误@stoplight/json-schema-viewer 依赖欢迎贡献！流程如下：
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-feature本项目采用 ISC 协议 —— 详见 LICENSE。
FAQs
AI-powered JSON Schema document generator with TUI, web viewer and mock server
The npm package @vegamo/loom receives a total of 6 weekly downloads. As such, @vegamo/loom popularity was classified as not popular.
We found that @vegamo/loom demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.
Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.
Research
/Security News
Benign-looking npm packages split malicious functionality across a dependency chain that deploys a cross-platform RAT targeting Alibaba developers.