chore: bootstrap kbqa workspace

.env.example

@@ -0,0 +1,21 @@
+KBQA_DASHSCOPE_API_KEY=
+KBQA_DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
+KBQA_CHAT_MODEL=qwen3.5-flash
+KBQA_EMBEDDING_MODEL=text-embedding-v4
+KBQA_EMBEDDING_DIM=1024
+KBQA_DATABASE_URL=sqlite+aiosqlite:///./data/kbqa.sqlite3
+KBQA_MILVUS_URI=./data/milvus/kbqa.db
+KBQA_RAW_DATA_DIR=./data/raw
+KBQA_CHUNK_SIZE=500
+KBQA_CHUNK_OVERLAP=50
+KBQA_RETRIEVAL_TOP_K=5
+KBQA_MAX_RESEARCH_SEARCHES=3
+KBQA_MAX_SOURCES=8
+KBQA_HISTORY_MESSAGE_LIMIT=20
+KBQA_MAX_UPLOAD_MIB=20
+KBQA_CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173"]
+KBQA_RUN_LIVE_TESTS=0
+KBQA_LIVE_TEST_FILE=
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=
+LANGSMITH_PROJECT=kbqa-local

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -0,0 +1,55 @@
+# 智能体知识库问答系统
+
+本项目是本地单用户双 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。不得在输出、报告或截图中记录密钥。项目验收后建议轮换本地测试密钥。

backend/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "kbqa"
+version = "0.1.0"
+description = "Local dual-agent knowledge-base question answering system"
+readme = "../README.md"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+  "aiosqlite>=0.21,<1",
+  "alembic>=1.16,<2",
+  "fastapi>=0.116,<1",
+  "langchain>=1,<2",
+  "langchain-openai>=1,<2",
+  "langchain-text-splitters>=1,<2",
+  "pydantic-settings>=2.10,<3",
+  "pymilvus[milvus-lite]>=2.6,<3",
+  "pypdf>=5,<7",
+  "python-multipart>=0.0.20,<1",
+  "sqlalchemy[asyncio]>=2.0.41,<3",
+  "uvicorn[standard]>=0.35,<1",
+]
+
+[dependency-groups]
+dev = [
+  "httpx>=0.28,<1",
+  "pytest>=8,<10",
+  "pytest-asyncio>=1,<2",
+  "pytest-timeout>=2,<3",
+  "ruff>=0.12,<1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kbqa"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = ["live: requires real DashScope and LangSmith credentials"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100

backend/src/kbqa/__init__.py

@@ -0,0 +1,3 @@
+"""Local dual-agent knowledge-base question answering system."""
+
+__version__ = "0.1.0"