@bndynet/ragbox 0.1.0

package/README.zh-CN.md

@@ -0,0 +1,774 @@
+# RAGbox 中文文档
+
+`ragbox` 可以让你从命令行、HTTP 服务或 Node.js 应用里直接询问 Markdown/MDX 文档。
+
+它会把文档目录变成本地可查询索引，适合产品文档、API 指南、运维 runbook、内部手册和 monorepo 多包文档。基础流程不需要部署向量数据库。
+
+适合这些场景：
+
+- 对本地 docs 目录提问
+- 查看一次回答用了哪些文档和章节
+- 文档变化时持续刷新索引
+- 通过 HTTP 把文档问答接进内部 backend
+- 在本地、CI 和容器里使用同一套索引/查询流程
+
+## 快速开始
+
+默认路径按“开箱即用”设计：安装 `ragbox`，让它在当前项目里准备 PageIndex，然后直接索引和提问。
+
+```bash
+# 安装 CLI
+npm install -g @bndynet/ragbox
+
+# 克隆 PageIndex 到 ./.ragbox/PageIndex，创建 Python venv，
+# 安装 PageIndex 依赖，并写入 ragbox.config.json
+ragbox setup pageindex
+```
+
+继续下一步前，先编辑 `ragbox.config.json`：填好模型配置，并把 `docs.rootDir` / `docs.outputDir` 改成你的文档目录和索引目录。
+
+```json
+{
+  "version": 1,
+  "pageIndex": {
+    "cli": "./.ragbox/PageIndex/run_pageindex.py",
+    "python": "./.ragbox/pageindex-venv/bin/python"
+  },
+  "llm": {
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini",
+    "apiKey": "sk-..."
+  },
+  "docs": {
+    "rootDir": "./docs",
+    "outputDir": "./.ragbox-index"
+  }
+}
+```
+
+如果有多个文档目录，改用 [项目配置](#项目配置) 里的 `sources` 映射。然后索引和提问：
+
+```bash
+# 基于配置里的 docs/source 生成本地索引
+ragbox index
+
+# 提问
+ragbox query "怎么配置认证？"
+
+# 可选：文档变化时持续刷新索引
+ragbox watch --jsonl
+```
+
+如果想用一个前台进程同时负责索引、watch 和 query HTTP API，使用 `start`：
+
+```bash
+ragbox start
+```
+
+需要临时覆盖配置时，仍然可以显式传路径：
+
+```bash
+ragbox index ./docs --output-dir ./.ragbox-index
+ragbox query ./.ragbox-index "怎么配置认证？"
+```
+
+如果不想把凭证写进 JSON，同样也支持通过环境变量或命令参数传入模型配置：
+
+```bash
+export OPENAI_API_KEY=sk-...
+export OPENAI_BASE_URL=https://api.openai.com/v1
+
+ragbox index ./docs \
+  --output-dir ./.ragbox-index \
+  --model gpt-4o-mini
+
+ragbox query ./.ragbox-index "怎么配置认证？" \
+  --api-key sk-... \
+  --base-url https://api.openai.com/v1 \
+  --model gpt-4o-mini
+```
+
+## Setup 做了什么
+
+`ragbox setup pageindex` 会帮你准备本地 PageIndex 依赖：
+
+- 克隆 PageIndex 到 `./.ragbox/PageIndex`
+- 创建 `./.ragbox/pageindex-venv`
+- 安装 PageIndex Python 依赖
+- 把 `pageIndex.cli` 和 `pageIndex.python` 写入 `ragbox.config.json`
+- 把 `.ragbox/` 加入 `.gitignore`
+
+如果你已经有 PageIndex checkout，可以使用 `ragbox setup pageindex --dir ../PageIndex --skip-install`，或手动设置 `PAGEINDEX_CLI`。
+
+## 前置条件
+
+默认 setup 需要：
+
+- Node.js 18 或更新版本
+- Git，用于克隆 PageIndex
+- 带 `venv` 和 `pip` 的 Python 3，用于安装 PageIndex 依赖
+- 一个包含 `.md` 或 `.mdx` 的文档目录
+- 一个兼容 OpenAI `/chat/completions` 的模型服务
+- 模型服务 API key
+
+## 常见使用方式
+
+| 目标 | 使用方式 |
+| --- | --- |
+| 从零开始 | `npm install -g @bndynet/ragbox`，然后 `ragbox setup pageindex` |
+| 先在一个 docs 目录试用 | `ragbox index ./docs --output-dir ./.ragbox-index`，然后 `ragbox query ./.ragbox-index "..."` |
+| 不想每次重复路径 | 使用 `ragbox setup pageindex` 写入的 `ragbox.config.json`，或运行 `ragbox init` |
+| 多个文档目录一起查询 | 配置 `sources`，分别跑 `ragbox index --source <name>`，再用 `ragbox query --all-sources "..."` |
+| 调试回答质量 | `ragbox query --trace --json "..."` 或 `ragbox trace query "..."` |
+| 检查索引是否可用 | `ragbox status ./.ragbox-index` |
+| 诊断本地配置问题 | `ragbox doctor` |
+| 编辑文档时自动更新索引 | `ragbox watch ./docs --output-dir ./.ragbox-index --jsonl` |
+| 跑完整本地服务流程 | `ragbox start --auth-token <token>` |
+| 只服务一个已经生成好的索引 | `ragbox serve ./.ragbox-index --auth-token <token>` |
+
+## 项目配置
+
+`ragbox setup pageindex` 会为默认本地 setup 创建或更新 `ragbox.config.json`。补上模型凭证后，典型配置如下：
+
+```json
+{
+  "version": 1,
+  "pageIndex": {
+    "cli": "./.ragbox/PageIndex/run_pageindex.py",
+    "python": "./.ragbox/pageindex-venv/bin/python"
+  },
+  "llm": {
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini",
+    "apiKey": "sk-..."
+  },
+  "docs": {
+    "rootDir": "./docs",
+    "outputDir": "./.ragbox-index"
+  }
+}
+```
+
+如果你只想创建配置、不安装 PageIndex，也可以运行：
+
+```bash
+ragbox init
+ragbox init --docs-dir ./content --output-dir ./.idx
+```
+
+配置文件中的相对路径会按配置文件所在目录解析。Server 端部署可以把 `baseUrl`、`model` 和 `apiKey` 一起放在私有 `ragbox.config.json`，或按环境拆成 `ragbox.config.prod.json`。如果配置文件会提交到仓库或共享给他人，就不要写真实 `apiKey`，改用环境变量或 secret manager。
+
+只有一个文档源时，用顶层 `docs` 就够了，不需要传 `--source`。项目里确实有多个命名文档源时，再使用可选的 `sources` 映射。
+
+之后命令会自动使用配置里的 docs：
+
+```bash
+ragbox index
+ragbox query "怎么配置认证？"
+ragbox watch --jsonl
+ragbox start
+ragbox --config ./ragbox.config.json index
+```
+
+如果有多个文档目录，在 `sources` 里给每个目录起一个名字。这个模式适合 monorepo、产品文档加 API 文档、多个 app/package 各自有 docs 的项目：
+
+```json
+{
+  "version": 1,
+  "pageIndex": {
+    "cli": "./.ragbox/PageIndex/run_pageindex.py",
+    "python": "./.ragbox/pageindex-venv/bin/python"
+  },
+  "llm": {
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini",
+    "apiKey": "sk-..."
+  },
+  "sources": {
+    "ragbox": {
+      "rootDir": "./ragbox",
+      "outputDir": "./.ragbox-index/ragbox",
+      "include": ["**/*.md", "**/*.mdx"]
+    },
+    "icharts": {
+      "rootDir": "./icharts",
+      "outputDir": "./.ragbox-index/icharts",
+      "include": ["**/*.md", "**/*.mdx"]
+    }
+  }
+}
+```
+
+这个多 source 目录结构的可运行示例在 `./examples/ragbox.config.json`。
+
+命名 source 分别索引，query 时可以全局查，也可以限定 source：
+
+```bash
+ragbox index --source ragbox
+ragbox index --source icharts
+
+ragbox query "ragbox start 是做什么的？"
+ragbox query --source ragbox "query trace 是怎么工作的？"
+ragbox query --source ragbox,icharts "这些项目如何处理运行时流程？"
+ragbox query --all-sources "当前示例有哪些文档主题？"
+ragbox start --all-sources
+```
+
+配置了多个 source 时，`ragbox query "..."` 默认查询全部 source。`--all-sources` 是同样行为的显式写法；要缩小范围时再用 `--source`。
+
+也可以按环境拆配置文件：
+
+```bash
+ragbox --config prod index
+ragbox --config ./ragbox.config.prod.json query "怎么部署？"
+```
+
+## 配置
+
+Server 端使用时，建议把稳定配置集中写在 `ragbox.config.json`：PageIndex 路径、docs 路径、LLM `baseUrl`、`model`，以及私有配置文件里的 `apiKey`。环境变量和命令参数仍然支持，适合覆盖配置、接 secret manager，或临时运行。
+
+配置解析优先级为：命令行参数、`ragbox.config.json`、环境变量、默认值。
+
+| 配置 | 环境变量 | 命令参数 | 用于 | 默认值 |
+| --- | --- | --- | --- | --- |
+| PageIndex 脚本 | `PAGEINDEX_CLI` | `ragbox setup pageindex` 写入配置 | `index`, `watch` | 索引时必填 |
+| Python 可执行文件 | `PAGEINDEX_PYTHON` | `--pageindex-python` | `index`, `watch` | `python3` |
+| 输出目录 | `RAGBOX_OUTPUT_DIR` | `--output-dir` | `index`, `watch` | `<folder>/.pageindex` |
+| 并发数 | `PAGEINDEX_CONCURRENCY` | `--concurrency` | `index`, `watch` | `1` |
+| API Base URL | `OPENAI_BASE_URL` | `--base-url` | `index`, `watch`, `query` | `https://api.openai.com/v1` |
+| API Key | `OPENAI_API_KEY` | `--api-key` | `index`, `watch`, `query` | query 必填，PageIndex 通常也需要 |
+| 模型 | `PAGEINDEX_MODEL`, `LLM_MODEL` | `--model` | `index`, `watch`, `query` | `gpt-4o-mini` |
+| Serve host | `RAGBOX_SERVE_HOST` | `--host` | `serve` | `127.0.0.1` |
+| Serve port | `RAGBOX_SERVE_PORT` | `--port` | `serve` | `8787` |
+| Serve token | `RAGBOX_SERVE_TOKEN` | `--auth-token` | `serve` | 无 |
+| Watch debounce | `RAGBOX_WATCH_DEBOUNCE_MS` | `--debounce-ms` | `watch` | `500` |
+| Watch 重试次数 | `RAGBOX_WATCH_RETRY_ATTEMPTS` | `--retry-attempts` | `watch` | `0` |
+| Watch 重试延迟 | `RAGBOX_WATCH_RETRY_DELAY_MS` | `--retry-delay-ms` | `watch` | `1000` |
+| Watch 锁文件 | `RAGBOX_WATCH_LOCK_FILE` | `--lock-file` | `watch` | 无 |
+| Watch staging | `RAGBOX_WATCH_STAGING` | `--staging` | `watch` | 关闭 |
+| Watch staging 输出目录 | `RAGBOX_WATCH_STAGING_OUTPUT_DIR` | `--staging-output-dir` | `watch` | `<outputDir>.staging` |
+| Watch health 文件 | `RAGBOX_WATCH_HEALTH_FILE` | `--health-file` | `watch` | 无 |
+| Watch webhook | `RAGBOX_WATCH_WEBHOOK_URL` | `--webhook` | `watch` | 无 |
+
+私有 server 配置可以把 `llm.apiKey` 写进 JSON，让部署自包含。配置文件会提交、共享或交给平台 secret 管理时，不要在 JSON 里写真实 key，改用 `OPENAI_API_KEY`。`--api-key` 适合本地测试，但可能出现在 shell history 或进程列表里。
+
+## 命令说明
+
+这一节是命令参考。如果你是第一次使用，建议先看 [快速开始](#快速开始) 和 [常见使用方式](#常见使用方式)。
+
+### `ragbox setup pageindex`
+
+把 PageIndex 克隆到 `./.ragbox/PageIndex`，创建 `./.ragbox/pageindex-venv`，安装 PageIndex Python 依赖，更新 `ragbox.config.json`，并把 `.ragbox/` 加入 `.gitignore`。
+
+```bash
+ragbox setup pageindex
+ragbox setup pageindex --ref v0.1.0
+ragbox setup pageindex --skip-install
+ragbox setup pageindex --dir ../PageIndex --no-write-config
+```
+
+自动化场景可以使用 `--json`。如果项目用其它方式管理本地生成工具，可以使用 `--no-gitignore`。
+
+### `ragbox init`
+
+只创建 `ragbox.config.json`，不安装 PageIndex。适合你想手动编辑路径，或自己管理 PageIndex 的场景。
+
+```bash
+ragbox init
+ragbox init --docs-dir ./content --output-dir ./.idx
+ragbox init --output ./configs/ragbox.config.json --force
+```
+
+### `ragbox index <folder>`
+
+为 Markdown/MDX 文档目录生成或更新本地索引。使用 `query` 或 `serve` 前需要先执行它。
+
+```bash
+ragbox index ./docs
+ragbox index ./docs --output-dir ./.ragbox-index
+ragbox index ./docs --output-dir ./.ragbox-index --json
+ragbox index ./docs --output-dir /var/lib/ragbox/docs-index --concurrency 2
+ragbox index ./docs --pageindex-python /opt/venvs/pageindex/bin/python
+ragbox index ./docs --base-url https://api.openai.com/v1 --model gpt-4o-mini
+```
+
+它会扫描 `**/*.md` 和 `**/*.mdx`，计算文件 hash，只重新索引新增、修改、之前失败的文件，并跳过未变化的 ready 文件。
+
+如果有文档索引失败，普通输出会继续把统计信息写到 stdout，并把失败文档路径和 PageIndex 错误写到 stderr。
+
+使用 `--json` 可以输出带版本号的机器可读结果，包含输出路径、统计信息和失败文档明细：
+
+```json
+{
+  "version": 1,
+  "command": "index",
+  "rootDir": "/repo/docs",
+  "outputDir": "/repo/.ragbox-index",
+  "manifestPath": "/repo/.ragbox-index/manifest.json",
+  "rootTreePath": "/repo/.ragbox-index/root-tree.json",
+  "generatedAt": "2026-01-01T00:00:00.000Z",
+  "counts": {
+    "total": 12,
+    "ready": 12,
+    "failed": 0,
+    "added": 12,
+    "modified": 0,
+    "retryFailed": 0,
+    "unchanged": 0,
+    "deleted": 0
+  },
+  "failures": []
+}
+```
+
+### `ragbox inspect [target]`
+
+查看索引里有哪些文档、每篇文档的状态和统计信息。适合确认“到底索引进去了什么”。
+
+```bash
+ragbox inspect ./.ragbox-index
+ragbox inspect --source ragbox
+ragbox inspect --all-sources --json
+```
+
+### `ragbox status [target]`
+
+检查索引是否已经可以 query。适合 CI、部署脚本和 smoke check。
+
+```bash
+ragbox status ./.ragbox-index
+ragbox status --all-sources
+ragbox status --json
+```
+
+### `ragbox doctor [target]`
+
+检查本地配置、PageIndex CLI 路径、LLM 设置、API key 是否存在，以及索引是否有效。这个命令不会发起网络请求。
+
+```bash
+ragbox doctor
+ragbox doctor --source ragbox --json
+ragbox doctor --all-sources
+```
+
+### `ragbox query [target] <question>`
+
+基于 docs 目录或已有索引目录回答问题。如果传 docs 目录，目录下需要有默认的 `.pageindex` 索引。
+
+```bash
+ragbox query ./docs "怎么配置认证？"
+ragbox query ./.ragbox-index "部署步骤是什么？"
+ragbox query ./docs/.pageindex "怎么配置认证？"
+ragbox query ./.ragbox-index "怎么配置认证？" --model gpt-4o-mini --api-key sk-...
+ragbox query ./.ragbox-index "怎么配置认证？" --json
+ragbox query ./.ragbox-index "怎么配置认证？" --trace
+ragbox trace query ./.ragbox-index "怎么配置认证？"
+ragbox query "部署步骤是什么？"
+ragbox query --source ragbox,icharts "这些项目如何处理运行时流程？"
+ragbox query --all-sources "部署步骤是什么？"
+```
+
+这里建议使用和索引时相同的 `--base-url`，通常是 OpenAI-compatible 根地址，例如 `https://api.openai.com/v1`。如果某些代理只能提供完整接口地址，`query` 也兼容完整的 `/chat/completions` URL。
+
+显式传 target 时，第一个参数可以是：
+
+- docs 目录，里面有 `.pageindex/manifest.json` 和 `.pageindex/root-tree.json`
+- 索引输出目录，里面有：
+
+```text
+manifest.json
+root-tree.json
+indexes/
+```
+
+查询流程：
+
+1. 读取 `manifest.json` 和 `root-tree.json`
+2. 让 LLM 从文档树中选择相关文档
+3. 读取相关文档的 PageIndex JSON
+4. 去掉节点里的 `text` 字段，只让 LLM 基于结构选择相关节点
+5. 回到完整 JSON 中取出选中节点的 `text`
+6. 把这些文本拼成上下文，让 LLM 生成最终答案
+
+对多个配置 source，`ragbox query "..."` 默认查询全部 source。可以用 `--source` 传逗号分隔的名字来缩小范围，也可以用 `--all-sources` 显式表达全局查询。多源 query 会对每个 source 执行正常的结构化查询流程，然后让 LLM 基于各 source 选出的片段融合成一个最终回答。来源引用会加上 source 前缀，例如 `ragbox:start-command.md#n1`。
+
+使用 `--json` 可以输出带版本号的结果契约。单 source query 返回 `QueryResult`；多 source query 返回融合后的 `answer`、每个 source 的 `results`、带 source 前缀的 `sources`、`warnings` 和 `timingsMs`。
+
+单 source `QueryResult` 字段：
+
+- `answer`：最终回答文本
+- `contextBytes` 和 `contextTokens`：最终 answer context 的大小；tokens 为估算值
+- `selectedDocuments`：从 `root-tree.json` 中选中的文档，包含 `selectionReason`，必要时包含 `skipReason`
+- `selectedNodes`：每篇文档中选中的 PageIndex 节点，包含 `selectionReason`、可选 `skipReason` 和 `textBytes`
+- `sources`：最终回答使用的来源引用和节点文本
+- `warnings`：不可用文档、缺失节点或空上下文等提醒
+- `timingsMs`：解析、选择和生成回答的耗时
+- `trace`：只有使用 `--trace` 或 `ragbox trace query` 时才会出现，包含文档/节点选择阶段的 LLM 原始响应、prompt/response 字节数、context 大小和非致命失败记录
+
+致命 query 错误会带上失败阶段，例如 `Query failed during select-documents: ...`。
+
+### `ragbox start [folder]`
+
+运行完整本地服务流程：先生成初始索引，再持续 watch 文档变化，同时启动 HTTP query API。
+
+```bash
+ragbox start
+ragbox start --auth-token dev-token
+ragbox start --host 127.0.0.1 --port 8787 --jsonl
+ragbox start --source ragbox
+ragbox start --all-sources
+ragbox start ./docs --output-dir ./.ragbox-index
+```
+
+当你已经通过 `ragbox setup pageindex` 准备好默认本地配置，并希望用一个前台进程跑本地开发、内网服务或容器时，优先使用 `start`。它会等初始索引完成后再启动 HTTP `serve`，之后每次 watch 成功更新索引，都会刷新 serve 里的索引快照。
+
+配置了多个 source 时，`ragbox start` 默认启动全部 source。可以用 `--source ragbox,icharts` 限定范围，也可以用 `--all-sources` 显式表达全局启动。
+
+`start` 不会创建或修改 `ragbox.config.json`；默认本地 setup 先运行 `ragbox setup pageindex`，如果你想自己管理 PageIndex，再用 `ragbox init` 手动配置。
+
+### `ragbox serve [target]`
+
+启动一个前台 HTTP 服务，供外部系统通过 REST API 查询文档。使用前先通过 `ragbox index` 生成索引，或者用 `ragbox watch` 持续刷新索引。
+
+```bash
+ragbox serve ./.ragbox-index \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --auth-token dev-token
+```
+
+多 source 项目可以直接基于配置文件启动：
+
+```bash
+ragbox serve --config ./ragbox.config.json --host 0.0.0.0 --port 8787
+```
+
+Public HTTP contract：
+
+- `GET /`：公开服务入口，返回 health 摘要和 endpoint 列表。
+- `GET /health`：公开 readiness endpoint，适合 load balancer、Kubernetes、systemd 和 smoke check。所有已知索引都可 query 时返回 200，否则返回 503。
+- `GET /indexes`：返回当前服务端缓存的索引校验快照。配置 token 后需要 `Authorization: Bearer <token>`。
+- `POST /query`：基于单个 target、选定 source 或全部 source 回答问题。配置 token 后需要鉴权。
+- `POST /reload`：重新读取 config/source target，并刷新服务端索引校验快照。配置 token 后需要鉴权。
+
+单索引请求：
+
+```bash
+curl http://127.0.0.1:8787/
+curl http://127.0.0.1:8787/health
+
+curl -H "Authorization: Bearer dev-token" \
+  http://127.0.0.1:8787/indexes
+
+curl -X POST http://127.0.0.1:8787/query \
+  -H "Authorization: Bearer dev-token" \
+  -H "Content-Type: application/json" \
+  -d '{"question":"怎么配置认证？","trace":true}'
+```
+
+多 source 请求：
+
+```bash
+curl -X POST http://localhost:8787/query \
+  -H "Content-Type: application/json" \
+  -d '{"source":"ragbox","question":"ragbox start 是做什么的？"}'
+
+curl -X POST http://localhost:8787/query \
+  -H "Content-Type: application/json" \
+  -d '{"source":["ragbox","icharts"],"question":"这些项目如何处理运行时流程？"}'
+
+curl -X POST http://localhost:8787/query \
+  -H "Content-Type: application/json" \
+  -d '{"allSources":true,"question":"当前示例有哪些文档主题？"}'
+
+curl -X POST http://localhost:8787/reload
+```
+
+`serve` 首版面向本地服务、内网服务、container sidecar 和 docs backend。不要把 `.ragbox-index` 作为静态目录直接暴露，因为里面可能包含源文档正文。浏览器 widget 不应该直接携带 ragbox token；建议先请求自己的 backend，由 backend 负责用户登录、限流和审计，再转发给 `ragbox serve`。生产环境建议绑定 localhost 或内网地址，并配置 `--auth-token` 或 `RAGBOX_SERVE_TOKEN`。
+
+### `ragbox watch <folder>`
+
+先执行一次索引，然后监听文档变化并增量更新。
+
+```bash
+ragbox watch ./docs
+ragbox watch ./docs --output-dir ./.ragbox-index
+ragbox watch ./docs --output-dir /var/lib/ragbox/docs-index --concurrency 2
+ragbox watch ./docs --base-url https://api.openai.com/v1 --model gpt-4o-mini
+ragbox watch ./docs --output-dir ./.ragbox-index --jsonl
+ragbox watch ./docs \
+  --output-dir /var/lib/ragbox/docs-index \
+  --staging \
+  --retry-attempts 3 \
+  --retry-delay-ms 2000 \
+  --lock-file /var/run/ragbox/docs.lock \
+  --health-file /var/run/ragbox/docs-health.json \
+  --jsonl
+```
+
+`watch` 监听 `.md` 和 `.mdx` 文件的新增、修改、删除。它会忽略 `node_modules`、`.git`、`.pageindex`、`dist`、`build`，以及位于文档目录内的自定义输出目录。
+
+使用 `--jsonl` 可以为集成场景输出带版本号的 JSON Lines 事件流。事件包括 `watch-start`、`watch-lock-acquired`、`watch-file-event`、`watch-index-start`、`watch-index-retry`、`watch-index-partial-failure`、`watch-output-promoted`、`watch-index-done`、`watch-index-failed`、`watch-health`、`watch-webhook-failed`、`watch-lock-released`、`watch-stop` 和 `index-progress`。
+
+生产化 watch 选项：
+
+- `--retry-attempts` 和 `--retry-delay-ms` 会重试抛错的索引运行，以及仍然留下 failed document 的运行。
+- `--lock-file` 会在 watch 运行期间创建排他锁文件。第二个 watcher 如果发现锁已存在，会直接退出。
+- `--staging` 会先索引到 staging 目录，只有在零 failed document 的干净运行后才 promote 到 active output。默认 staging 目录是 `<outputDir>.staging`；为了基于 rename 切换，建议和 `outputDir` 放在同一文件系统。
+- `--health-file` 会写 readiness JSON，包含 `status`、`ok`、`pid`、`lastSuccessAt`、`lastFailureAt` 和最新统计。
+- `--webhook` 会把每个 watch 事件作为 JSON POST 出去。Webhook 投递失败会报告为 `watch-webhook-failed` 事件，不会中断 watch。
+- `--debounce-ms` 控制文件变化后等待多久再重新索引。
+
+`ragbox watch` 有意以前台进程运行，这更适合 systemd service 或 container。建议使用 supervisor/container 的 restart policy，而不是在 CLI 里自行 fork daemon。
+
+## 输出目录
+
+默认输出：
+
+```text
+docs/.pageindex/
+  manifest.json
+  root-tree.json
+  indexes/
+    <stable-doc-id>.pageindex.json
+  state/
+    file-state.json
+```
+
+自定义输出：
+
+```bash
+ragbox index ./docs --output-dir ./.ragbox-index
+ragbox query ./.ragbox-index "..."
+```
+
+输出目录可能包含源文档正文和元数据。如果文档是私有的，不要把输出目录公开暴露。
+
+## 生产使用建议
+
+常见方式：
+
+- 一个前台进程要同时负责索引、watch 和 serve 时，直接运行 `ragbox start`
+- 部署时执行 `ragbox index`，再通过 `ragbox serve` 或 SDK 查询完成后的索引目录
+- 文档会独立变化时，把 `ragbox watch` 作为后台服务运行
+
+建议：
+
+- 长期运行 `watch` 时，优先使用 `--jsonl`、`--lock-file`、`--health-file`、`--retry-attempts` 和 `--staging`
+- 把输出目录放在源码目录外，例如 `/var/lib/ragbox/docs-index`
+- 多副本应用需要读取同一份完整索引，可以挂载只读卷或随部署产物分发
+- API key 可以放私有 server 配置、环境变量或 secret manager；不要提交真实 key
+- 当 `serve` 不只绑定 localhost 时，使用 `RAGBOX_SERVE_TOKEN` 或 `--auth-token`
+- 先用 `--concurrency 1`，确认 PageIndex 和模型服务限流后再提高
+- 如果要求零停机更新，可以先索引到 staging 目录，成功后再切换读目录
+
+私有 server 配置示例：
+
+```json
+{
+  "version": 1,
+  "pageIndex": {
+    "cli": "/opt/PageIndex/run_pageindex.py",
+    "python": "/opt/pageindex-venv/bin/python"
+  },
+  "llm": {
+    "baseUrl": "https://api.openai.com/v1",
+    "model": "gpt-4o-mini",
+    "apiKey": "sk-..."
+  },
+  "docs": {
+    "rootDir": "/srv/app/docs",
+    "outputDir": "/var/lib/ragbox/docs-index"
+  }
+}
+```
+
+```bash
+ragbox --config ./ragbox.config.prod.json index --concurrency 2
+ragbox --config ./ragbox.config.prod.json query "怎么配置认证？"
+```
+
+### 后台运行
+
+`ragbox start` 有意以前台进程运行。Server 部署时，建议交给进程管理器托管，这样关闭终端、SSH 断开或进程崩溃后都能继续运行或自动重启。
+
+临时测试可以用 `nohup`：
+
+```bash
+nohup ragbox --config ./ragbox.config.prod.json start > ragbox.log 2>&1 &
+```
+
+Linux server 推荐用 `systemd`：
+
+```ini
+[Unit]
+Description=ragbox service
+After=network.target
+
+[Service]
+WorkingDirectory=/srv/ragbox
+ExecStart=/usr/local/bin/ragbox --config ./ragbox.config.prod.json start
+Restart=always
+RestartSec=5
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl enable ragbox
+sudo systemctl start ragbox
+sudo systemctl status ragbox
+```
+
+如果使用 Node 生态，也可以用 `pm2`：
+
+```bash
+pm2 start "ragbox --config ./ragbox.config.prod.json start" --name ragbox
+pm2 save
+pm2 startup
+```
+
+容器部署时，让 `ragbox start` 保持为前台命令，然后使用平台的 restart policy，例如 Docker `--restart unless-stopped` 或 Kubernetes `restartPolicy`。
+
+## 在 Node.js 中使用 ragbox
+
+当你的 Node.js 服务需要创建索引、查询文档、校验索引，或以编程方式启动 `serve` 时，可以使用 SDK。
+
+```js
+const {
+  createIndex,
+  inspectIndex,
+  queryIndex,
+  startServe,
+  validateIndex,
+  watchIndex
+} = require("@bndynet/ragbox");
+
+await createIndex("/srv/app/docs", {
+  configPath: "./ragbox.config.json",
+  outputDir: "/var/lib/ragbox/docs-index",
+  pageIndexCli: "/opt/PageIndex/run_pageindex.py"
+});
+
+const result = await queryIndex(
+  "/var/lib/ragbox/docs-index",
+  "怎么配置认证？"
+);
+
+console.log(result.answer);
+console.log(result.sources);
+
+const validation = await validateIndex("/var/lib/ragbox/docs-index");
+console.log(validation.ok);
+
+const server = await startServe({
+  target: "/var/lib/ragbox/docs-index",
+  port: 8787,
+  authToken: process.env.RAGBOX_SERVE_TOKEN
+});
+console.log(server.url);
+await server.close();
+
+const inspect = await inspectIndex("/var/lib/ragbox/docs-index");
+console.log(inspect.counts);
+
+const watcher = await watchIndex("/srv/app/docs", {
+  outputDir: "/var/lib/ragbox/docs-index",
+  pageIndexCli: "/opt/PageIndex/run_pageindex.py",
+  onEvent: (event) => console.log(event)
+});
+await watcher.ready;
+await watcher.close();
+```
+
+自定义 LLM client：
+
+```js
+const { queryIndex, startServe } = require("@bndynet/ragbox");
+
+const llmClient = {
+  async chatCompletion(request) {
+    // request.messages, request.model, request.temperature
+    return await callYourModelGateway(request);
+  }
+};
+
+const result = await queryIndex(
+  "/var/lib/ragbox/docs-index",
+  "怎么配置认证？",
+  {
+    llmClient,
+    model: "internal-docs-model"
+  }
+);
+
+const server = await startServe({
+  target: "/var/lib/ragbox/docs-index",
+  llmClient,
+  model: "internal-docs-model",
+  port: 8787
+});
+```
+
+`llmClient` 是一个只用于 SDK 的薄 provider 边界，负责 query 阶段的直接 chat completion。它适合接本地模型、内部模型网关、重试、超时、日志和测试 mock。`ragbox` 不会从配置文件动态加载 provider 插件；CLI 仍然使用 flags、config 和环境变量里的 OpenAI-compatible 设置。
+
+包根入口导出稳定的产品化 SDK API。底层工具仍保留在 `advanced` namespace，适合更定制的集成：
+
+```js
+const { advanced } = require("@bndynet/ragbox");
+
+const location = await advanced.resolveQueryIndexLocation("/var/lib/ragbox/docs-index");
+```
+
+## 查询时发生了什么
+
+简单说，`ragbox` 会保留文档结构，而不是一开始就把所有内容切成匿名 chunk：
+
+- 每个 `.md`/`.mdx` 文件会生成一棵结构化 PageIndex 树
+- 文档目录会生成一份索引清单
+- 查询时先选择可能相关的文档，再选择文档里的相关章节
+- 最终回答只基于选中的章节正文生成
+
+所以 `--trace` 能告诉你选了哪些文档和节点。基础流程也因此不需要部署向量数据库。
+
+## 与传统 Vector DB RAG 的对比
+
+传统 Vector RAG 通常会切 chunk、做 embedding，再按向量相似度召回。`ragbox` 则优先保留源文档层级，并让 LLM 基于这棵结构树做选择。
+
+| 维度 | Vector DB RAG | `ragbox` |
+| --- | --- | --- |
+| 索引单位 | 文本 chunk | Markdown/MDX 文件和 PageIndex 节点 |
+| 检索信号 | 向量相似度 | LLM 基于文档树和节点树选择 |
+| 存储 | 向量数据库加文档存储 | 输出目录下的本地 JSON 文件 |
+| 上下文形态 | 扁平 chunk 列表 | 带文件路径和 node id 的结构化节点 |
+| 优势 | 大规模模糊召回快 | 保留文档层级，引用来源更清晰 |
+| 取舍 | 需要 embedding 和索引基础设施 | 依赖 PageIndex 质量和 LLM 选择效果 |
+
+两种方式也可以组合：先用向量检索做大范围候选召回，再用 PageIndex 树做结构化过滤、上下文组织和引用生成。
+
+## 常见问题
+
+- `PAGEINDEX_CLI is required to run PageIndex`：运行 `ragbox setup pageindex`，或设置 `PAGEINDEX_CLI=/path/to/run_pageindex.py`
+- `OPENAI_API_KEY is required for query`：在私有 `ragbox.config.json` 里添加 `llm.apiKey`，或设置 `OPENAI_API_KEY`，也可以临时传 `--api-key`
+- `Expected a docs folder... or a ragbox output directory`：`query` 的第一个参数可以传带 `.pageindex/` 的 docs 目录，也可以直接传索引输出目录
+- `PageIndex completed but no generated JSON result was found`：默认情况下，ragbox 会读取 PageIndex 写到 `results/` 里的 JSON。如果你使用的自定义 wrapper 只支持显式输出路径，把 `PAGEINDEX_OUTPUT_ARG` 或 `pageIndex.outputArg` 设置成它的输出路径参数名。
+
+## 限制
+
+- 需要你本地已经安装并配置 PageIndex；`ragbox setup pageindex` 可以准备默认的本地 checkout 和虚拟环境
+- 查询质量依赖 PageIndex JSON 结构和所使用的 LLM
+- 当前基础流程是树结构选择，不是向量检索
+
+## 贡献者开发
+
+```bash
+npm install
+npm run build
+npm run ragbox -- --help
+```
+
+### Examples
+
+可运行的本地 fixture 和 smoke-test 命令都放在 [`examples/README.md`](./examples/README.md)。需要用真实 PageIndex 和 LLM 配置验证 index、query、多 source 或 `start` 服务循环时，看那里即可。