[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-76050":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":9,"languages":9,"totalLinesOfCode":9,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":14,"starSnapshotCount":14,"syncStatus":12,"lastSyncTime":25,"discoverSource":26},76050,"loom","husu\u002Floom","husu","一个写接口文档的AI Agent。支持使用Vibe coding 的方式，编写接口文档，同时自带友好的文档查看工具与接口Mock工具",null,940,33,2,6,0,1,869,8.59,false,"main",true,[],"2026-06-12 02:03:39","# Loom\n\n**简体中文** | [English](README.en.md)\n\n\u003Cdiv align=\"center\">\n\n基于 AI 的 JSON Schema 文档生成器，集成 TUI 交互、Web 浏览器与 Mock 服务\n\n[![Node.js](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FNode.js-≥18.0.0-green)](https:\u002F\u002Fnodejs.org\u002F)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.9-blue)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n\n\u003C\u002Fdiv>\n\n## ✨ 特性\n\n- **🤖 AI 驱动的 Schema 生成** —— 通过 TUI 聊天界面与大模型（DeepSeek、OpenAI）对话生成和更新 JSON Schema API 文档\n- **🧩 实体（Entity）建模** —— 在 `docs\u002Fentities` 中维护可复用的实体 Schema，通过 `x-entity-ref` 在接口 Schema 中引用\n- **📚 现代 Web 浏览器** —— 基于 React 的 SPA，用于浏览模块、接口和实体，支持交互式 Schema 渲染\n- **⚡ Mock 服务** —— 基于 JSON Schema 动态生成贴近真实的 Mock 数据\n- **🖥️ TUI 内服务控制** —— 直接在 TUI 中启动\u002F停止\u002F重启 Mock 与 Web Viewer（`\u002Fmock`、`\u002Fview`）\n- **🗂️ Manifest 索引** —— 内置 `loom manifest rebuild` 命令重建依赖\u002F索引一致性\n- **⬆️ 自动升级提示** —— 启动时检查 npm 上的新版本，确认后可自动升级\n- **🔧 TypeScript 优先** —— 完整类型定义，现代化的 TypeScript 架构\n\n## 📦 安装\n\n### 环境要求\n- Node.js ≥ 18.0.0\n- npm 或 yarn\n- DeepSeek API Key（必需）\n\n### 全局安装\n```bash\nnpm install -g loom\n# 或\nyarn global add loom\n```\n\n### 本地开发\n```bash\ngit clone \u003Crepository-url>\ncd loom\nnpm install\nnpm run build:all\n```\n\n## ⚙️ 配置\n\n### 配置文件\nLoom 使用一份全局配置文件（不依赖 `.env`）。\n\n默认全局配置路径：\n- macOS\u002FLinux: `~\u002F.loom\u002Fconfig.json`\n- Windows: `%APPDATA%\u002Floom\u002Fconfig.json`\n\n可选覆盖：\n- `LOOM_CONFIG=\u002Fcustom\u002Fpath\u002Fconfig.json`\n\n首次运行 `loom chat` 时，会以交互向导的形式引导你创建\u002F更新该全局配置文件。\n\n聊天首次引导的默认值：\n- `provider`：`deepseek`\n- `model`：`deepseek-chat`\n- `baseURL`：`https:\u002F\u002Fapi.deepseek.com\u002Fv1`\n- `apiKey`：必填，需由用户输入\n\n你也可以手动创建全局配置：\n```json\n{\n  \"outDir\": \"docs\",\n  \"llm\": {\n    \"provider\": \"deepseek\",\n    \"model\": \"deepseek-chat\",\n    \"baseURL\": \"https:\u002F\u002Fapi.deepseek.com\u002Fv1\",\n    \"apiKey\": \"your_deepseek_api_key\",\n    \"temperature\": 0.7,\n    \"maxTokens\": 2000\n  },\n  \"serve\": {\n    \"port\": 3000,\n    \"host\": \"0.0.0.0\"\n  },\n  \"mock\": {\n    \"port\": 3001,\n    \"host\": \"0.0.0.0\"\n  }\n}\n```\n\n`docs\u002F` 目录仍保留在各项目目录中（通过 `--dir` 指定），不会被移动到全局存储。\n\n## 🚀 快速开始\n\n### 1. 生成 API 文档\n```bash\n# 启动交互式 TUI 来生成 JSON Schema\nloom chat\n\n# 或指定项目目录\nloom chat --dir .\u002Fmy-api-project\n```\n\n在 `loom chat` 中，你也可以控制本地服务：\n- `\u002Fmock`、`\u002Fmock stop`、`\u002Fmock restart [port]`\n- `\u002Fview`、`\u002Fview stop`、`\u002Fview restart [port]`\n\n### 2. 浏览文档\n```bash\n# 启动 Web 文档浏览器\nloom view\n\n# 或指定端口\nloom view --port 8080\n```\n\n### 3. 启动 Mock 服务\n```bash\n# 启动 Mock API 服务\nloom mock\n\n# 或指定端口\nloom mock --port 8081\n```\n\n### 4. 组合服务（推荐）\n```bash\n# 在同一端口同时启动 Viewer 和 Mock 服务\nloom serve\n\n# 访问入口：\n# - Web Viewer: http:\u002F\u002Flocalhost:3000\n# - Mock API:   http:\u002F\u002Flocalhost:3000\u002Fmock\u002F...\n```\n\n### 5. 升级 Loom\n```bash\n# 手动触发升级\nloom upgrade\n```\n\n> 执行其它命令时，Loom 也会检查 npm 是否有新版本。  \n> 发现新版本时，确认即可自动升级。\n\n## 📖 使用指南\n\n### `loom chat`\n通过 AI 对话生成 JSON Schema 文档的交互式终端 UI。\n\n```bash\nloom chat [options]\n\nOptions:\n  -d, --dir \u003Cpath>    目标项目目录（默认：当前目录）\n  -h, --help          显示帮助\n```\n\n**典型流程：**\n1. 运行 `loom chat`\n2. 用自然语言描述你的 API 接口\n3. AI 生成结构合理的 JSON Schema\n4. Schema 文件被保存到 `docs\u002F` 目录（可配置）\n\n**内置聊天命令：**\n- 输入提示：`Enter` 发送，`Shift+Enter`\u002F`Alt+Enter` 换行，`↑`\u002F`↓` 浏览历史记录（跨会话持久化），`Tab` 自动补全命令\n- `\u002Fhelp` —— 显示命令帮助\n- `\u002Freset` —— 重置对话历史\n- `\u002Flist` —— 列出已生成的 Schema 文件\n- `\u002Fmock`、`\u002Fmock stop`、`\u002Fmock restart [port]` —— 管理 Mock 服务\n- `\u002Fview`、`\u002Fview stop`、`\u002Fview restart [port]` —— 管理 Web Viewer\n- `\u002Fscan \u003Cdir>` —— 通过 LLM 从源码中识别 API；`\u002Fscan resume`、`\u002Fscan reset` 管理断点\n- `\u002Fabort` —— 中止当前请求\n- `\u002Fexit` —— 退出 Loom\n\n### `loom view`\n基于 React SPA 的现代化 Web 文档浏览器。\n\n```bash\nloom view [options]\n\nOptions:\n  -p, --port \u003Cnumber>  端口号（默认：3000）\n  -d, --dir \u003Cpath>     目标项目目录（默认：当前目录）\n  -h, --help           显示帮助\n```\n\n**特性：**\n- 📁 按模块浏览，显示接口数量\n- 🧩 浏览 `docs\u002Fentities` 中的实体\n- 🔍 在模块与接口范围内实时搜索\n- 📊 类 Swagger 的 Schema 表格视图，覆盖所有请求\u002F响应区段（query、path、headers、body）\n- 🔗 渲染接口请求\u002F响应时自动解析 `x-entity-ref`\n- 🎨 简洁的响应式 UI，深色侧边栏\n- 🔗 支持接口的直链访问\n\n### `loom mock`\n基于 JSON Schema 动态生成数据的 Mock API 服务。\n\n```bash\nloom mock [options]\n\nOptions:\n  -p, --port \u003Cnumber>  端口号（默认：3001）\n  -d, --dir \u003Cpath>     目标项目目录（默认：当前目录）\n  -h, --help           显示帮助\n```\n\n**特性：**\n- 🚀 自动从 JSON Schema 文件注册路由\n- 🎲 基于 mock-json-schema 智能生成 Mock 数据\n- 📡 支持所有 HTTP 方法（GET、POST、PUT、DELETE、PATCH）\n- 🔧 可配置响应状态码与 Schema\n\n### `loom serve`\n组合服务，同时运行 Web Viewer 与 Mock 服务。\n\n```bash\nloom serve [options]\n\nOptions:\n  -p, --port \u003Cnumber>  端口号（默认：3000）\n  -d, --dir \u003Cpath>     目标项目目录（默认：当前目录）\n  -h, --help           显示帮助\n```\n\n**URL 结构：**\n- `http:\u002F\u002Flocalhost:3000\u002F` —— Web 文档浏览器\n- `http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fdocs` —— 文档 API\n- `http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fschemas` —— Schema 文件 API\n- `http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fentities` —— 实体文件 API\n- `http:\u002F\u002Flocalhost:3000\u002Fmock\u002F...` —— Mock API 路由\n\n### `loom manifest rebuild`\n重建文档清单索引文件 `.loom-manifest.json`，确保依赖\u002F索引一致。\n\n```bash\nloom manifest rebuild [options]\n\nOptions:\n  -d, --dir \u003Cpath>  目标项目目录（默认：当前目录）\n  -h, --help        显示帮助\n```\n\n### `loom upgrade`\n将 loom 升级到 npm 上的最新版本。\n\n```bash\nloom upgrade\n```\n\n## 📝 JSON Schema 格式\n\nLoom 使用一套为 API 文档优化的自定义 JSON Schema 格式：\n\n```json\n{\n  \"$schema\": \"http:\u002F\u002Fjson-schema.org\u002Fdraft-07\u002Fschema#\",\n  \"title\": \"Authentication API\",\n  \"description\": \"User authentication endpoints\",\n  \"version\": \"1.0.0\",\n  \"endpoints\": [\n    {\n      \"path\": \"\u002Fapi\u002Fauth\u002Flogin\",\n      \"method\": \"POST\",\n      \"summary\": \"User login\",\n      \"description\": \"Authenticate user with credentials\",\n      \"tags\": [\"auth\"],\n      \"request\": {\n        \"headers\": {\n          \"Content-Type\": { \"type\": \"string\", \"enum\": [\"application\u002Fjson\"] }\n        },\n        \"body\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"username\": { \"type\": \"string\" },\n            \"password\": { \"type\": \"string\" }\n          },\n          \"required\": [\"username\", \"password\"]\n        }\n      },\n      \"response\": {\n        \"200\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"token\": { \"type\": \"string\" },\n            \"user\": { \"type\": \"object\" }\n          }\n        },\n        \"400\": {\n          \"type\": \"object\",\n          \"properties\": {\n            \"error\": { \"type\": \"string\" }\n          }\n        }\n      }\n    }\n  ]\n}\n```\n\n### Schema 结构说明\n- **title**：API 模块标题\n- **description**：模块描述\n- **endpoints**：API 接口定义数组\n- **endpoint.path**：URL 路径（支持路径参数）\n- **endpoint.method**：HTTP 方法（GET、POST、PUT、DELETE、PATCH）\n- **endpoint.request**：可选的请求 Schema（headers、params、query、body）\n- **endpoint.response**：按状态码索引的响应 Schema\n\n## 🧩 实体（Entity）Schema 与引用\n\nLoom 支持以下位置的可复用实体 Schema：\n\n```text\ndocs\u002Fentities\u002F*.entity.schema.json\n```\n\n实体文件示例：\n\n```json\n{\n  \"$schema\": \"http:\u002F\u002Fjson-schema.org\u002Fdraft-07\u002Fschema#\",\n  \"title\": \"User\",\n  \"description\": \"Reusable user entity\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"id\": { \"type\": \"integer\" },\n    \"name\": { \"type\": \"string\" },\n    \"email\": { \"type\": \"string\", \"format\": \"email\" }\n  },\n  \"required\": [\"id\", \"name\", \"email\"]\n}\n```\n\n在接口 Schema 中通过 `x-entity-ref` 引用实体：\n\n```json\n{\n  \"user\": {\n    \"x-entity-ref\": {\n      \"entity\": \"User\",\n      \"pick\": [\"id\", \"name\", \"email\"]\n    }\n  }\n}\n```\n\n支持的形式：\n- 字符串形式：`\"x-entity-ref\": \"User\"`\n- 对象形式：`\"x-entity-ref\": { \"entity\": \"User\", \"pick\": [\"id\", \"name\"] }`\n\n\n\n\n## 📋 更新日志\n\n### v0.3.0\n- **Added**：`\u002Fscan` 与 `\u002Fscan resume` 新增 `--lang zh|en` 参数。Phase 3（generate-entity）和 Phase 4（generate-endpoint）按所选语言输出 `description` 与 `summary` 文本。默认 `zh`；可通过 `~\u002F.loom\u002Fconfig.json` 中的 `scan.language` 全局覆盖，或在执行命令时使用该参数\n- **Changed**：`\u002Fscan` 的 LLM 缓存对 Phase 3\u002F4 改为按语言区分（键末尾追加 `:zh` 或 `:en`），Phase 1\u002F2 仍跨语言共享。切换语言只会失效真正会变的那一半\n- **Changed**：缓存的阶段标识符改名以匹配扫描流程的编号（`phase1` extract-endpoints、`phase2` extract-entities、`phase3` generate-entity、`phase4` generate-endpoint）。升级自动迁移：旧版本的 Phase 1\u002F2 记录继续命中；Phase 3\u002F4 记录会在下次扫描时重新生成\n- **Removed**：去掉全局 `CACHE_VERSION` 一刀切清空机制。缓存失效改由 source-hash + 每条记录的形状校验驱动。如有 prompt 重大变更，用户可手动 `rm \u003CoutDir>\u002F.loom-scan-cache.json` 清空\n- **Fixed**：Phase 4 当 LLM 漏掉 `summary` 时，不再回退到英文 `brief`，而是退化为 `\u003CMETHOD> \u003Cpath>`，避免一句英文混在中文文档里\n\n### v0.2.0\n- **Added**：`\u002Fscan \u003Cdir>` —— 多语言、LLM 驱动的源码 API 识别。识别框架、用 glob 收紧文件范围、提取接口标识（Phase 1）、识别并生成实体 Schema（Phase 1.5），然后按路由前缀生成单文件 Schema（Phase 2，通过 `x-entity-ref` 引用实体）\n- **Added**：`\u002Fscan resume` 和 `\u002Fscan reset` —— 基于断点继续被中断的扫描，或丢弃已保存的断点\n- **Added**：`\u002Fscan` 的 LLM 输出缓存，按文件内容哈希索引（`\u003CoutDir>\u002F.loom-scan-cache.json`）；增量扫描会跳过未变更的文件，可节省 25 分钟以上。可使用 `--no-cache` 强制调用 LLM\n- **Added**：`loom chat` 的输入历史持久化在全局 `~\u002F.loom\u002Fhistory.jsonl`（上限 100 条），上下方向键跨会话浏览\n- **Added**：斜杠命令 Tab 自动补全 —— bash 风格的公共前缀补全，候选列表内联展示\n- **Added**：集中式的斜杠命令注册表（`src\u002Ftui\u002Fcommands.ts`），让 Header 面板、`\u002Fhelp` 文案与自动补全列表共享一份数据源\n- **Added**：静默使用埋点 —— 每次 CLI 调用上报一次 `{ userToken, action: \"used\" }`。UUID 持久化于 `~\u002F.loom\u002Finstall-id`，离线时落到 `~\u002F.loom\u002Ftelemetry-outbox.jsonl`\n- **Added**：每次扫描的诊断日志 `\u003CoutDir>\u002F.loom-scan.log`，以及来自 `scan-failures.ts` 的原始响应快照，便于排查 LLM 问题\n- **Improved**：Phase 2 改为发送 handler 片段而非整文件，降低 token 消耗\n- **Improved**：`\u002Fscan` 容忍推理模型的输出格式（例如 DeepSeek-R1 在同一响应中先输出 `\u003Cthink>` 再给出最终 JSON）\n- **Improved**：LLM 客户端将 `APIConnectionError` 与 SDK 内部 abort 归为可重试的 timeout\n- **Fixed**：对已经扫描完成的断点执行 `\u002Fscan resume`，现在会提示 \"scan already complete\" 而不是默默重跑 analyze\n- **Fixed**：实体的可空性改用 `required[]` 表达，而不是 `type` 联合\n- **Fixed**：在 `doneCount` 自增过程中保留 group 冲突策略\n- **Fixed**：abort 时保留扫描子阶段，`\u002Fscan resume` 能从正确步骤继续\n- **Fixed**：聊天启动时的命令列表与 `\u002Fhelp` 同步（现在包含 `\u002Fscan` 与 `\u002Fabort`）\n- **Removed**：禁用了 `\u002Finit` 命令；若项目里存在 `requirement.md`，仍会作为 agent 上下文加载\n\n### v0.1.6\n- **Added**：每个接口都有 Mock view \u002F Mock edit 页面，可从模块列表进入\n- **Added**：手写的 Mock 响应以同名 sidecar 文件 `\u003Cname>.mock.json` 存储（每个接口同时只有一个生效 override）\n- **Added**：Mock 服务会使用 override 的 HTTP 状态码响应（例如保存 400 的 mock 后，`\u002Fmock\u002F\u003Cpath>` 会真的返回 HTTP 400）\n- **Added**：Mock view\u002Fedit 中的状态码切换器，并标记哪些状态码已经存在 override\n- **Added**：Mock view 提供 cURL 示例区块，基于接口的 `request` schema 生成（path、query、headers、body 全部填充示例值）\n- **Added**：Mock body 内支持 Mock.js 表达式（`@cname`、`@integer(1,100)`、`'list|1-5': [...]` 等）—— 模板原样存储，每次请求时再展开\n- **Removed**：接口详情页内嵌的 \"Mock Testing\" 区块（已由独立的 Mock 页面替代）\n\n### v0.1.4\n- **Fixed**：Web Viewer 中 GET 接口的 query 参数、path 参数和 headers 现在能正确显示\n- **Improved**：所有请求\u002F响应区段统一使用类 Swagger 的表格视图（SchemaTableViewer），含类型标签、约束、展开\u002F折叠\n- **Fixed**：启动 Web Viewer（`loom view`）或组合服务（`loom serve`）时的 `setNotFoundHandler` 重复注册错误\n- **Removed**：移除与 React 19 不兼容的 `@stoplight\u002Fjson-schema-viewer` 依赖\n\n\n\n\n## 🙏 致谢\n\n- [DeepSeek](https:\u002F\u002Fwww.deepseek.com\u002F) —— 提供 AI 能力\n- [Fastify](https:\u002F\u002Ffastify.io\u002F) —— 高性能 Web 服务\n- [React](https:\u002F\u002Freactjs.org\u002F) —— UI 组件\n- [mock-json-schema](https:\u002F\u002Fgithub.com\u002Fanttiviljami\u002Fmock-json-schema) —— Mock 数据生成\n- [Ink](https:\u002F\u002Fgithub.com\u002Fvadimdemedes\u002Fink) —— 终端 UI\n\n## 📞 支持\n\n- **提问**：欢迎在 Issues 或 Discussions 中提出\n\n---\n\n\u003Cdiv align=\"center\">\nMade with ❤️ by the Loom team\n\u003C\u002Fdiv>\n","Loom 是一个基于 AI 的 JSON Schema 文档生成工具，支持通过 TUI 交互界面与大模型对话生成和更新接口文档。其核心功能包括AI驱动的Schema生成、实体建模、现代Web浏览器浏览模块和接口、动态Mock服务以及TUI内服务控制等。它适合需要高效编写和维护API文档的开发团队使用，特别是在微服务架构或快速迭代开发场景中。采用TypeScript构建，确保了代码质量和可维护性，并且提供了自动升级提示等便利功能。","2026-06-11 03:54:19","CREATED_QUERY"]