Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
275 lines (196 loc) · 11.8 KB

CONTRIBUTING.md

File metadata and controls

275 lines (196 loc) · 11.8 KB
Raw

贡献指南（Contributing）

感谢你为「鉴微」（AI 技术追踪与深度解析知识库）贡献力量！本文档说明如何搭建本地环境、提交代码、撰写规范的提交信息与 PR，以及合并前必须通过的测试门禁。请在动手之前花几分钟通读一遍。

一句话约定：任何代码变更都必须 ① 通过本地 scripts/test.* 全流程；② 在 CHANGELOG.md 的 [Unreleased] 下补记。 CI 不绿、CHANGELOG 未更新的 PR 不予合并。

一、行为准则（Code of Conduct）

  • 对人友善、对事专业。技术讨论对事不对人，欢迎不同意见，但拒绝人身攻击、骚扰与歧视。
  • 提问、评审、回复保持耐心与建设性；明确指出问题，并尽量给出可执行的改进建议。
  • 尊重维护者与其他贡献者的时间：提交前自查、提供可复现信息、回应评审意见。

违反上述准则的行为，维护者有权关闭相关 Issue/PR 或限制参与。

二、环境准备

最常见、也是推荐的开发方式是 全栈跑在 Docker 里（前后端、Qdrant/PostgreSQL/Redis/MinIO 均由 compose 编排），本机只需 Docker 即可端到端开发与测试。

工具 版本 是否必需 说明
Docker Desktop（Windows）/ Docker Engine + Compose v2（ECS/Linux） 最新稳定版 必需 一键脚本依赖 docker compose v2
Git 任意近期版本 必需 .gitattributes 已锁定 LF，跨平台无需额外配置
Node.js 20.x 可选（本地跑前端 / E2E 时需要） 与 CI 一致；E2E 用 Playwright
Python 3.12 可选（在容器外本地跑后端 / 工具时需要） 后端 requires-python >=3.12

dev 环境默认 LLM_PROVIDER=mock：无需任何真实 API Key，全栈（资讯流 / 解析 / RAG / 搜索）即可返回确定性假数据端到端跑通，适合开发与自动化测试。配好真实 Key 后将 .env 的 LLM_PROVIDER 改为 domestic（通义/DeepSeek）/ anthropic / openai 即可。

三、本地快速开始

# 1. 克隆
git clone https://github.com/topbat/jianwei.git
cd jianwei

启动全栈（首次会自动从模板生成 .env）：

# Windows / Docker Desktop（在仓库根目录执行）
.\scripts\start.ps1 -Env dev
# 阿里云 ECS / Linux
bash scripts/start.sh --env dev

写入演示数据，然后访问站点：

.\scripts\seed.ps1            # Windows
bash scripts/seed.sh          # ECS / Linux
  • 浏览器打开 http://localhost
  • 演示账号：demo@jianwei.ai / Demo@2026（Pro 套餐），登录即见 15 条 AI 资讯 + 7 篇可语义搜索/RAG 的知识库文档。
  • dev 环境另有：Swagger http://localhost:8000/docs、MinIO 控制台 http://localhost:9001。

常用脚本（Windows 用 -Env，ECS 用 --env）：

操作 Windows ECS / Linux
启动 .\scripts\start.ps1 -Env dev bash scripts/start.sh --env dev
停止（保留数据卷） .\scripts\stop.ps1 -Env dev bash scripts/stop.sh --env dev
停止并清库 .\scripts\stop.ps1 -Env dev -Volumes bash scripts/stop.sh --env dev --volumes
查看日志 .\scripts\logs.ps1 [-Service api] bash scripts/logs.sh [--service api]
写入演示数据 .\scripts\seed.ps1 bash scripts/seed.sh
运行测试 .\scripts\test.ps1 bash scripts/test.sh

双环境：dev（HMR + 源码挂载 + mock 模型 + 端口暴露）与 master（生产：nginx/gunicorn + Caddy 自动 HTTPS + 收敛端口）。切换只需改 -Env dev|master / --env dev|master。

四、分支模型

分支 角色 说明
master 生产 受保护分支；push 即触发部署（deploy.yml）。不允许直接 push，只能经 PR 合并。
dev 集成 日常集成分支；功能/修复分支先合入此处，验证稳定后再推 master。
feature/* 个人功能分支 从 dev 切出，如 feature/rag-rerank。
fix/* 个人修复分支 从 dev（紧急线上问题可从 master）切出，如 fix/sse-auth-header。

工作流：从 dev 切 feature/* 或 fix/* → 开发并自测 → 提 PR 回 dev → 评审 + CI 通过后合并 → 适时由维护者将 dev 推进到 master 触发部署。

五、提交信息规范（Conventional Commits）

提交信息遵循 Conventional Commits，描述部分使用中文：

<type>(<scope>): <中文描述>

常用 type：

type 用途
feat 新功能
fix 修复缺陷
docs 仅文档变更
refactor 重构（不改变外部行为、非新增功能也非修复）
test 新增/修改测试
chore 构建、依赖、CI、脚本等杂项

scope 可选，建议用模块名定位改动范围，如 feed / analyze / rag / kb / auth / frontend / worker / ci。

示例：

feat(rag): 问答增加阈值防幻觉与行内 [n] 引用
fix(auth): 修复 SSE 请求未携带 Bearer 鉴权头导致 401
docs: 补充 dev/master 双环境切换说明
refactor(worker): 抽取常驻后台事件循环，避免异步客户端跨循环
test(security): 新增多租户越权访问用例
chore(ci): 升级 setup-node 到 v4

六、代码风格

后端（FastAPI + Celery，Python 3.12）

  • 使用 ruff 进行 lint/格式化（配置见 backend/pyproject.toml，line-length = 120，target-version = py312）。
  • 全量类型注解：函数签名、Pydantic v2 schema、SQLAlchemy 2 模型均需带类型。
  • 静态安全扫描 bandit 必须 High = 0（pyproject.toml 已配置 skips/exclude_dirs）。
# 在 api 容器内执行（或本地装好 ruff 后执行）
ruff check app
ruff format app

前端（Vue 3 + TS + Vite，「铜镜」设计语言）

  • TypeScript strict 模式（tsconfig.app.json 已开启 strict / noUnusedLocals / noUnusedParameters 等），不得用 any 绕过类型。
  • npm run build 必须通过——该命令先 vue-tsc -b 做类型检查再 vite build，CI 以此为门禁。
  • 沿用「铜镜」设计令牌与既有组件/composables，不要引入与设计体系冲突的样式。
cd frontend
npm ci
npm run build      # 类型检查 + 构建，必须零错误

七、测试要求

合并前 必须在本地跑通全流程测试，且 CI 必绿。测试编排脚本会按固定顺序执行，任一前置阶段不过即中断，不进入后续阶段：

.\scripts\test.ps1            # Windows：① 安全 → ② 性能(SLA 门禁) → ③ 功能 → ④ E2E + 截图
bash scripts/test.sh          # ECS / Linux：同上
阶段 内容 门禁
① 安全 bandit（静态）+ pip-audit（依赖 CVE）+ pytest -m security（鉴权 / 多租户隔离 / 越权 / 限流） bandit High = 0，安全用例全过
② 性能 tests/perf/run_perf.py 断言 SLA（语义搜索 < 1s、RAG 首 token < 3s、健康检查 P95） 不达标即中断，不进入功能测试
③ 功能 pytest -m functional（覆盖四大模块业务流）+ 覆盖率 全过
④ E2E + 截图 Playwright 跑通核心用户流程并截图到 tests/screenshots/ 全过

可用 -Stage security|perf|func|e2e（PowerShell）只跑单个阶段做局部调试。全过方可合并。 测试结论与截图汇总见 docs/test-report.md。

八、CHANGELOG 约定

本项目变更日志遵循 Keep a Changelog，版本遵循 语义化版本。

  • 每个 PR 都必须在 CHANGELOG.md 的 [Unreleased] 小节下补记本次变更，按类别归入 Added / Changed / Fixed / Removed / Security。
  • 条目用中文、简洁明确、说清「改了什么 / 为什么」。
  • 发布时由维护者将 [Unreleased] 内容归入对应版本号。

示例：

## [Unreleased]

### Added
- RAG 问答支持行内 [n] 引用并增加相似度阈值防幻觉。

### Fixed
- 修复 SSE 请求缺失鉴权头导致 401 的问题。

九、PR 流程与检查清单

  1. 从 dev 切出 feature/* 或 fix/* 分支。
  2. 完成开发，按上文规范提交（Conventional Commits + 中文描述）。
  3. 本地跑通 scripts/test.* 全流程；前端确保 npm run build 通过。
  4. 在 CHANGELOG.md 的 [Unreleased] 下补记。
  5. 向 dev 发起 PR，填写清晰的标题与说明（动机 / 改动点 / 影响范围 / 验证方式），关联相关 Issue（如 Closes #123）。
  6. 等待 CI（ci.yml：前端构建 + 后端安全/性能/功能测试）变绿，并响应评审意见。

提交 PR 前请逐项自查：

  • 分支从 dev 切出，命名符合 feature/* 或 fix/*。
  • 提交信息符合 Conventional Commits（中文描述）。
  • 本地 scripts/test.* 全流程通过（安全 → 性能 → 功能 → E2E）。
  • 前端 npm run build 通过（TS strict 零错误）；后端 ruff 通过、关键路径有类型注解。
  • 已在 CHANGELOG.md 的 [Unreleased] 下补记。
  • 涉及接口/行为变更时已同步更新相关文档（docs/openapi.yaml、docs/api-spec.md 等）。
  • 未提交 .env、密钥、构建产物或日志等不应入库的文件。
  • PR 说明清晰，已关联相关 Issue。

CI 通过、CHANGELOG 已更新、至少一名维护者 Approve，方可合并。

十、Issue 规范

提 Issue 前请先搜索是否已有重复条目。请按类型提供以下信息：

Bug 报告

  • 复现步骤（尽量最小化）；
  • 期望结果 vs 实际结果；
  • 环境信息：环境（dev/master）、操作系统、Docker / Node / Python 版本、LLM_PROVIDER；
  • 相关日志（scripts/logs.* 输出）、报错栈、截图。

功能建议

  • 要解决的问题与使用场景；
  • 期望的行为或方案；
  • 涉及的模块（资讯流「见微」/ GitHub 解剖「知著」/ 站点熔炼「重构」/ 知识库「鉴真」）。

请勿在 Issue 中粘贴任何真实密钥、令牌或个人敏感信息。

十一、目录结构速览

jianwei/
├─ docker-compose.yml            # base 编排（全服务、命名卷、healthcheck）
├─ docker-compose.dev.yml        # dev 覆盖（HMR / 源码挂载 / 端口暴露）
├─ docker-compose.prod.yml       # master 覆盖（ACR / 资源限制 / 收敛端口）
├─ .env.example / .env.dev.example / .env.prod.example
├─ CHANGELOG.md                  # 变更日志（每个 PR 必须补记 [Unreleased]）
├─ deploy/
│  ├─ Caddyfile / Caddyfile.dev  # 反代 + 自动 HTTPS + SSE 透传
│  └─ acr-push.sh                # 构建并推送阿里云 ACR
├─ scripts/                      # 一键脚本（.ps1 = Windows，.sh = ECS）
│  └─ start / stop / logs / test / seed
├─ backend/                      # FastAPI + Celery（单镜像多命令）
│  ├─ app/{api,worker,agents,rag,ingest,llm,models,schemas,core}
│  ├─ pyproject.toml             # ruff / pytest / bandit 配置
│  └─ tests/                     # 安全 / 性能(perf) / 功能 测试
├─ frontend/                     # Vue 3 + TS + Vite + Tailwind（「铜镜」设计语言）
│  └─ src/{api,components,composables,views,stores,design}
├─ tests/e2e/                    # Playwright 端到端 + 截图（→ tests/screenshots/）
├─ docs/                         # 详设 / OpenAPI / 成本测算 / 测试报告
└─ .github/workflows/            # ci.yml（构建+测试）、deploy.yml（部署）

再次感谢你的贡献！如有疑问，欢迎在 Issue 中讨论。