本地开发

SAG 是一个前后端分离的仓库。日常开发通常在两个终端分别运行 FastAPI 与 Next.js；桌面开发再由 Electron 复用这两个服务。

环境要求

• Python 3.11+
• Node.js 20+
• npm 10+
• 推荐使用 uv 管理 API 环境

启动 API

cd apps/api
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
uvicorn sag_api.main:app --reload

API 默认运行在 http://localhost:8000，OpenAPI 位于 /docs。

启动 Web

cd apps/web
npm install
npm run dev

Web 默认运行在 http://localhost:3000。浏览器访问的 API 地址来自构建期变量 NEXT_PUBLIC_API_BASE。

常用检查

cd apps/api
ruff check .

cd apps/web
npm run i18n:check
npm run typecheck
npm run build

前端包含中英文消息文件，新增界面文案时应同步两种语言并通过 i18n 检查。

调试文档任务

导入问题通常跨越 parser、job 与 engine 三层。建议按这个顺序定位：

1. 查看 DocumentOut.status、progress 与 error。
2. 使用 /api/v1/jobs/{job_id} 确认任务是否重试或暂停。
3. 检查 API 日志中的解析器与引擎异常。
4. 确认 LLM、Embedding 和 MinerU 配置是否分别可用。

桌面开发

先安装 apps/web、apps/api 和 apps/desktop 的依赖，再运行：

cd apps/desktop
npm run dev

开发脚本会复用已经运行的 3000 与 8000 服务；若由脚本创建，退出 Electron 时会一并结束。

桌面发布必须在目标操作系统原生构建，因为 PyInstaller sidecar 包含平台和 CPU 架构相关依赖。详细发布约束见仓库中的 apps/desktop/README.md。

贡献前

保持改动聚焦并运行受影响模块的检查。架构变更应继续遵守“应用只通过 sag_api/sag/ 访问知识引擎”的依赖规则。