# 智能体知识库问答系统

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

## 环境要求

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

## 本地配置

复制 `.env.example` 为 `.env` 并填写本地密钥。`.env`、`1.md`、`test.txt`
均被 Git 忽略。LangSmith 会接收 Agent 输入、工具结果和运行轨迹。

## 后端

```bash
uv sync --project backend --all-groups
uv run --project backend alembic -c backend/alembic.ini upgrade head
uv run --project backend uvicorn kbqa.main:app --app-dir backend/src --port 8000
```

## 前端

```bash
npm --prefix web install
npm --prefix web run dev
```

## 普通验证

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

```bash
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` 才执行真实模型测试：

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

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