llm-in-text/AGENTS.md

仓库指南

语言约定

项目文档、日志、错误提示以及对外返回的文字信息统一使用 中文。前端 UI 默认展示中文，若需多语言支持请在相应模块实现。

项目结构 & 模块组织

backend/          # FastAPI 后端（Python）
    ├─ main.py    # API 入口
    ├─ llm.py    # LLM 包装工具
    ├─ prompt.py # Prompt 构建辅助
    └─ tests/    # pytest 测试套件
public/           # 前端静态资源
src/              # 前端源码（Vite + React）
dist/             # 构建产出（生成文件）

生产代码主要位于 backend/（Python）和 src/（JS/TS）。测试文件与被测模块并置。

构建、测试、开发命令

命令	说明
npm install	安装前端依赖
npm run dev	启动 Vite 开发服务器
uvicorn backend.main:app --reload	本地运行 FastAPI 服务
pytest	运行 Python 测试套件
npm run build	生成生产环境构建产物至 dist/

编码风格 & 命名约定

• Python：使用 4 空格缩进，snake_case 命名函数/变量，PascalCase 命名类。提交前请使用 ruff/black 格式化。
• JavaScript/TypeScript：使用 2 空格缩进，camelCase 命名变量/函数，PascalCase 命名 React 组件。使用 eslint 与 prettier 检查。
• 文件名采用全小写加短横线，例如 my-module.py、my-component.tsx。

测试指南

• 后端使用 pytest，测试文件放在对应模块目录下，命名为 test_<module>.py。
• 目标覆盖率 ≥ 80%（pytest --cov=backend）。
• 在虚拟环境中运行：pip install -r backend/requirements.txt && pytest。

提交 & Pull Request 规范

• 提交信息遵循 Conventional Commits：feat: 新功能、fix: 修复、docs: 文档、refactor: 重构等。
• PR 必须包含：
  • 与提交信息匹配的标题。
  • 关联的 Issue（如 Fixes #123）。
  • UI 变更或 API 示例的截图/示例。
  • 所有 CI 检查（代码检查、测试、类型检查）均通过。

安全 & 配置建议

• 敏感信息请放入 .env 并确保已在 .gitignore 中。
• 按照 backend/main.py 中的实现，对上传文件的大小和类型进行校验，防止滥用。
• 定期审计依赖安全（npm audit、pip-audit）。

---

以上指南旨在保持贡献一致性并维护代码库健康，欢迎通过 Pull Request 提出改进。