{"id":50689516,"url":"https://github.com/sing1ee/docs-qa-api","last_synced_at":"2026-06-09T01:34:19.658Z","repository":{"id":342548744,"uuid":"1173157839","full_name":"sing1ee/docs-qa-api","owner":"sing1ee","description":"LLM-powered codebase Q\u0026A agent with interactive TUI — index your project and ask questions via CLI or HTTP API","archived":false,"fork":false,"pushed_at":"2026-03-06T10:53:44.000Z","size":56,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T14:48:57.734Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://openclawagent.net/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sing1ee.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-05T04:11:10.000Z","updated_at":"2026-03-06T10:53:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sing1ee/docs-qa-api","commit_stats":null,"previous_names":["sing1ee/docs-qa-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sing1ee/docs-qa-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing1ee%2Fdocs-qa-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing1ee%2Fdocs-qa-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing1ee%2Fdocs-qa-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing1ee%2Fdocs-qa-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sing1ee","download_url":"https://codeload.github.com/sing1ee/docs-qa-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sing1ee%2Fdocs-qa-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34088013,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T01:34:18.523Z","updated_at":"2026-06-09T01:34:19.653Z","avatar_url":"https://github.com/sing1ee.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# docs-qa-api\n\n\n基于 LLM 的代码库问答 API。启动时自动构建代码库索引（目录结构 + TS 导出符号 + 文档摘要），通过多轮 tool calling 搜索代码和文档，SSE 流式返回答案。\n\n---\n\n## 前置要求\n\n- **Node.js** 18+（推荐 20+）\n- 代码库路径（`DOCS_DIR`）需存在且可读\n- 任选其一：**Gemini API Key** 或 **OpenRouter API Key**\n\n---\n\n## 安装\n\n```bash\ngit clone \u003crepo-url\u003e\ncd docs-qa-api\npnpm install\n```\n\n---\n\n## 配置\n\n通过环境变量配置。**启动时会自动加载项目根目录的 `.env` 文件**，也可在命令行传入（命令行会覆盖 `.env` 中的同名字段）。\n\n### 环境变量一览\n\n| 变量 | 必填 | 说明 |\n|------|------|------|\n| `DOCS_DIR` | **是** | 要建立索引的代码库根目录（绝对或相对路径） |\n| `GEMINI_API_KEY` | Gemini 时必填 | [Google AI Studio](https://aistudio.google.com/apikey) 获取 |\n| `OPENROUTER_API_KEY` | OpenRouter 时必填 | [OpenRouter](https://openrouter.ai/keys) 获取 |\n| `LLM_PROVIDER` | 否 | `gemini`（默认）或 `openrouter` |\n| `LLM_MODEL` | 否 | 模型名；Gemini 默认 `gemini-3.1-flash-lite-preview`，OpenRouter 默认 `google/gemini-3.1-flash-lite-preview` |\n| `PORT` | 否 | 服务端口，默认 `3000` |\n| `API_KEY` | 否 | 若设置，则所有 API 请求需携带 `Authorization: Bearer \u003cAPI_KEY\u003e` |\n\n### 配置示例\n\n**方式一：命令行（适合临时跑）**\n\n```bash\nexport DOCS_DIR=/path/to/your/project\nexport GEMINI_API_KEY=your_gemini_key\n# 然后运行\npnpm run dev\n```\n\n**方式二：`.env` 文件（推荐，不提交到 git）**\n\n在项目根目录创建 `.env`，启动时会自动加载：\n\n```env\n# 代码库路径（必填）\nDOCS_DIR=/path/to/your/project\n\n# Gemini（二选一）\nGEMINI_API_KEY=your_gemini_key\n\n# 或 OpenRouter\n# LLM_PROVIDER=openrouter\n# OPENROUTER_API_KEY=your_openrouter_key\n# LLM_MODEL=google/gemini-3.1-flash-lite-preview\n\n# 可选\nPORT=3000\nLLM_MODEL=gemini-3.1-flash-lite-preview\n```\n\n配置好后直接执行 `pnpm run dev` 即可。\n\n---\n\n## 运行\n\n### 开发 / 本地运行\n\n```bash\n# 使用 Gemini（默认）\nDOCS_DIR=/path/to/your/project GEMINI_API_KEY=xxx pnpm run dev\n\n# 使用 OpenRouter\nDOCS_DIR=/path/to/your/project \\\n  LLM_PROVIDER=openrouter \\\n  OPENROUTER_API_KEY=xxx \\\n  LLM_MODEL=google/gemini-3.1-flash-lite-preview \\\n  pnpm run dev\n```\n\n或直接用 `tsx`（无需预编译）：\n\n```bash\nDOCS_DIR=/path/to/your/project GEMINI_API_KEY=xxx pnpm exec tsx src/server.ts\n```\n\n启动后会：\n\n1. 扫描 `DOCS_DIR` 并构建索引（目录树 + TS/JS 导出符号 + MD 摘要）\n2. 打印索引大小并监听端口（默认 3000）\n3. 可访问 `http://localhost:3000/health` 做健康检查\n\n### 指定端口\n\n```bash\nPORT=8080 DOCS_DIR=... GEMINI_API_KEY=... pnpm run dev\n```\n\n### 常见问题\n\n| 现象 | 可能原因 |\n|------|----------|\n| `Error: DOCS_DIR environment variable is required` | 未设置 `DOCS_DIR` |\n| `GEMINI_API_KEY is required` | 使用默认 provider 但未设置 Gemini Key |\n| `OPENROUTER_API_KEY is required` | `LLM_PROVIDER=openrouter` 但未设置 OpenRouter Key |\n| 启动后请求超时/无响应 | 检查 API Key 是否有效、网络是否可访问对应 API |\n\n---\n\n## API\n\n### POST /api/ask\n\nSSE 流式返回回答。\n\n**请求体：**\n\n```json\n{ \"question\": \"认证中间件是怎么实现的？\" }\n```\n\n**SSE 事件：**\n\n| event | data | 说明 |\n|-------|------|------|\n| `delta` | `{\"content\": \"...\"}` | 文本增量 |\n| `tool_call` | `{\"name\": \"grep\", \"args\": {...}}` | 工具调用 |\n| `tool_result` | `{\"name\": \"grep\", \"preview\": \"...\"}` | 工具结果摘要 |\n| `done` | `{}` | 结束 |\n| `error` | `{\"message\": \"...\"}` | 错误 |\n\n**示例：**\n\n```bash\ncurl -N -X POST http://localhost:4000/api/ask \\\n  -H 'Content-Type: application/json' \\\n  -H 'Authorization: Bearer your_api_key' \\\n  -d '{\"question\": \"Openclaw 的 gateway 如何配置语义搜索呢\"}'\n\ncurl -N --noproxy '*' -X POST https://api.openclawagent.net/api/ask \\\n  -H 'Content-Type: application/json' \\\n  -H 'Authorization: Bearer your_api_key' \\\n  -d '{\"question\": \"Openclaw 的 gateway 如何配置语义搜索呢\"}'\n```\n\n### GET /health\n\n健康检查，返回 `{\"status\":\"ok\"}`。\n\n---\n\n## 工作原理\n\n```\n启动 → 扫描 DOCS_DIR → 构建索引（目录树 + 文件摘要）\n                              ↓\n用户提问 → [LLM + 索引] 规划搜索 → grep/read_file → 结果不足？→ 继续搜索\n                                                        ↓ 足够\n                                                   流式回答（引用代码和文件路径）\n```\n\n**索引内容：**\n\n- TS/JS 文件：提取所有 `export` 的函数、类、接口、类型、常量\n- MD 文件：提取标题和前几行摘要\n- 目录树：完整文件结构\n\n**工具：**\n\n- `grep` — 关键词/正则搜索，返回匹配行（限 50 条）\n- `read_file` — 读取文件内容，支持行范围\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsing1ee%2Fdocs-qa-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsing1ee%2Fdocs-qa-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsing1ee%2Fdocs-qa-api/lists"}