cd portal
pnpm install
pnpm run dev        # 本地预览 http://localhost:5173
pnpm run build      # 构建静态站点 → .vitepress/dist

cd server
npm install
npm run api         # REST API → http://localhost:8787

# 检索示例
curl "http://localhost:8787/api/search?q=U8%20登录失败&top_k=5"
curl "http://localhost:8787/api/stats"

cd server
npm run mcp         # stdio MCP Server

{ "mcpServers": { "kb": { "command": "node", "args": ["<仓库路径>/server/src/mcp.mjs"] } } }

cd scripts
python3 query.py "客户提问的问题描述"      # 全文检索 Top-5
python3 query.py --keyword "WebView2"    # 关键词检索
python3 query.py --id FX-20221130-059    # 精确获取

cd ai/..  # 仓库根目录
pip install -r requirements-ai.txt
cp .env.example .env                      # 填写 LLM/Embedding Key
python3 scripts/build_vectors.py          # 构建向量索引（全量约几分钟）
python3 ai/api.py --port 8800             # 启动 RAG 服务

# 客服问答（带引用）
curl -X POST http://localhost:8800/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"U8 登录失败"}'

# LLM 清洗分类打标（产出建议标签，供审核回写）
python3 scripts/llm_tag.py --limit 50

<script>window.KBWidgetConfig = { apiBase: "http://localhost:8800" }</script>
<script src="/kb-widget.js" defer></script>

python3 admin/server.py --port 8900   # 需先在 .env 配置 KB_ADMIN_TOKEN
# 浏览器打开 http://localhost:8900/admin/

python scripts/bot_xiaofu.py --mode both        # Windows；默认进程守护（supervisor 守护 worker，断线自动重连）
# 或统一用 启动kb服务.bat 一键拉起 API/门户/机器人

# 1. 从钉钉同步最新数据
bash scripts/sync_from_dingtalk.sh

# 2. 重建索引
python3 scripts/build_index.py

# 3. 重建向量索引（RAG 检索用，同步后必跑；后台入库会自动增量）
python3 scripts/build_vectors.py

# 4. 重新生成门户页面
cd portal && node scripts/generate.mjs

# 5. 构建并提交
cd portal && pnpm run build
cd .. && git add -A && git commit -m "同步最新知识" && git push

kb/
├── raw/                    # 原始采集数据（只读）
├── knowledge/              # 清洗后知识库（entries + docs + tags + index + markdown + ai/）
├── scripts/                # 采集/清洗/索引/查询/打标脚本
│   ├── llm_tag.py          # LLM 清洗分类打标（v2，产建议标签）
│   └── build_vectors.py    # 向量索引构建（v2）
├── ai/                     # AI 能力（v2，Python，多服务商）
│   ├── llm.py              # LLM 客户端（OpenAI 兼容）
│   ├── embeddings.py       # Embedding 客户端
│   ├── vector_index.py     # 条目向量检索（numpy 余弦，增量构建）
│   ├── doc_index.py        # 文档切块向量检索（文档库专用）
│   ├── lexical.py          # 词法检索（移植 core.mjs 逻辑）
│   ├── rag.py              # 混合检索（条目词法/向量 + 文档词法/向量四路 RRF）+ RAG 问答编排
│   └── api.py              # RAG REST 服务（:8800）
├── admin/                  # 知识管理后台（v2，:8900）
│   ├── parse_docs.py       # 格式解析（txt/md/csv/docx/pptx/pdf/xlsx）
│   ├── doclib.py           # 文档库：上传归档 → 切块 → 向量化
│   ├── taglib.py           # 自伸缩标签词表 + 大模型标注（条目/文档/切片）
│   ├── drafts.py           # 草稿存取（上传 → LLM 打标 → 人工审核）
│   ├── ingest.py           # 上传 + LLM 结构化打标
│   ├── import_entry.py     # 审核入库 + 重建索引/向量
│   └── static/             # 后台单页前端（index.html + admin.js）
├── widget/                 # 官网客服 Widget（v2，任意页面引入）
├── config/                 # ai.json 多服务商配置（不含 Key）
├── portal/                 # VitePress Web 门户
│   ├── scripts/generate.mjs  # 知识条目 → 门户页面生成器
│   └── docs/                 # 生成的站点页面
├── server/                 # API 服务（REST + MCP）
│   └── src/
│       ├── core.mjs        # 检索核心（共享）
│       ├── api.mjs         # REST API
│       └── mcp.mjs         # MCP Server
├── docs/                   # 使用文档（机器人集成、RAG 部署、后台指南等）
└── .github/workflows/      # CI 部署