智能体知识库问答系统

本项目是本地单用户双 Agent 知识库问答系统。权威需求见 docs/superpowers/specs/2026-07-13-kbqa-system-design.md；原始 architecture.md 仅作为历史参考，不作为实现依据。

环境要求

• Python 3.12，由 uv 管理
• Node.js 与 npm
• 单进程 Uvicorn；禁止配置多个 worker

本地配置

.env 是唯一运行配置来源，所有变量均为必填项；程序不提供运行参数默认值。复制 .env.example 为 .env，阅读每项中文注释并填写真实值。必须从项目根目录执行下列 命令，否则相对路径和 .env 文件位置会改变。.env、1.md、test.txt 均被 Git 忽略。 LangSmith 会接收 Agent 输入、工具结果和运行轨迹。

首次运行前建立本地数据目录：

mkdir -p data/raw data/milvus

后端

cd "$(git rev-parse --show-toplevel)"
uv sync --project backend --all-groups
mkdir -p data/raw data/milvus
uv run --project backend alembic -c backend/alembic.ini upgrade head
uv run --project backend uvicorn kbqa.main:app --app-dir backend/src --host 127.0.0.1 --port 8000

--port 必须与 web/vite.config.ts 中 /api 代理目标的端口一致。仓库默认示例为 8000；若你本地将代理改为 8003，后端也必须使用 --port 8003。

前端

cd "$(git rev-parse --show-toplevel)"
npm --prefix web install
npm --prefix web run dev -- --host 127.0.0.1

普通验证

普通验证不会调用 Chat 或 Embedding 模型：

uv run --project backend ruff format --check backend/src backend/tests
uv run --project backend ruff check backend/src backend/tests
uv run --project backend pytest backend/tests/unit backend/tests/integration -v
npm --prefix web run lint
npm --prefix web run test -- --run
npm --prefix web run build

真实调用验证

只有显式设置 KBQA_RUN_LIVE_TESTS=1 才执行真实模型测试：

KBQA_RUN_LIVE_TESTS=1 uv run --project backend pytest backend/tests/live -v -s

真实测试通过 HTTP 调用实际 Uvicorn 服务，并调用真实 DashScope Chat、Embedding 和 LangSmith。不得在输出、报告或截图中记录密钥。项目验收后建议轮换本地测试密钥。