diff --git a/.commitlintrc.json b/.commitlintrc.json new file mode 100644 index 0000000..e448880 --- /dev/null +++ b/.commitlintrc.json @@ -0,0 +1,28 @@ +{ + "extends": ["@commitlint/config-conventional"], + "rules": { + "type-enum": [ + 2, + "always", + [ + "feat", + "fix", + "docs", + "style", + "refactor", + "perf", + "test", + "build", + "ci", + "chore", + "ui", + "revert" + ] + ], + "subject-case": [0], + "subject-full-stop": [0], + "header-max-length": [1, "always", 100], + "body-max-line-length": [0], + "footer-max-line-length": [0] + } +} diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index e4b7d56..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -name: Bug report -about: 上报一些bug -title: "[BUG]" -labels: bug -assignees: JefferyHcool - ---- - ---- -name: 🐛 Bug 反馈 -about: 提交一个 Bug 报告，帮助我们改进 -title: "[Bug] " -labels: bug -assignees: '' ---- - -**版本说明** - -请说明的你的版本号 - -**部署方式** - -使用的是什么方式部署（代码环境部署，docker部署，桌面端，在线预览） - -**描述问题** -清晰、简明地描述你遇到的问题是什么。 - -**复现步骤** -复现该问题的步骤： - -1. 进入页面 '...' -2. 点击 '...' -3. 滚动到 '...' -4. 出现错误 - -**预期行为** -清晰、简明地描述你本来预期发生的行为。 - -**截图** -如果适用，请添加截图以帮助说明问题。 - -**桌面端（请补充以下信息）** - - - 操作系统：例如 Windows / macOS / Ubuntu - - 浏览器：例如 Chrome、Safari - -**其他补充信息** -请补充任何其他相关信息。 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..d86736e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,93 @@ +name: 🐛 Bug 报告 +description: 报告一个可复现的问题 +title: "[Bug] " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + 感谢反馈。请尽量提供完整的复现路径与日志，便于排查。 + ⚠️ **不要**贴 API key、SESSDATA、密钥等敏感信息。 + - type: dropdown + id: workspace + attributes: + label: 受影响的工作区 + multiple: true + options: + - 后端 (backend/) + - Web 前端 (BillNote_frontend/) + - 浏览器插件 (BillNote_extension/) + - Tauri 桌面端 + - 文档 / 其他 + validations: + required: true + - type: input + id: version + attributes: + label: 版本 + description: BiliNote 版本号（README 顶部，例如 v2.1.0） + placeholder: v2.1.0 + validations: + required: true + - type: dropdown + id: deploy + attributes: + label: 部署方式 + options: + - 源码运行 + - Docker (docker-compose.yml) + - Docker GPU (docker-compose.gpu.yml) + - 桌面端安装包 (Tauri Release) + - 其他 + validations: + required: true + - type: textarea + id: repro + attributes: + label: 复现步骤 + description: 一步步说明如何触发问题 + placeholder: | + 1. 打开 ... + 2. 点击 ... + 3. 看到 ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: 期望行为 + validations: + required: true + - type: textarea + id: actual + attributes: + label: 实际行为 + description: 含错误信息、截图、录屏均可 + validations: + required: true + - type: textarea + id: env + attributes: + label: 运行环境 + description: 操作系统、Python 版本、Node 版本、浏览器（如适用） + placeholder: | + - OS: macOS 14.5 / Windows 11 / Ubuntu 22.04 + - Python: 3.11.6 + - Node: 20.18.0 + - Browser: Chrome 124（如涉及插件/前端） + - GPU: 无 / NVIDIA 4070（如涉及 fast-whisper / video understanding） + - type: textarea + id: logs + attributes: + label: 日志 / 堆栈 + description: 后端 console、前端 DevTools、扩展 background 页都可以贴 + render: text + - type: checkboxes + id: pre-checks + attributes: + label: 提交前自查 + options: + - label: 我已搜索过 [Issues](https://github.com/JefferyHcool/BiliNote/issues?q=)，确认不是重复问题 + required: true + - label: 我提供的日志中**不**包含 API key、cookie、SESSDATA 等敏感信息 + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..7f8703e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: 📖 文档与常见问题 + url: https://docs.bilinote.app/ + about: 安装与配置遇到问题，先看一下文档 + - name: 💬 提问 / 讨论 + url: https://github.com/JefferyHcool/BiliNote/discussions + about: 用法咨询、想法征集请发到 Discussions（不是 bug 才用 Issues） diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..94c76ba --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,40 @@ +name: ✨ 功能建议 +description: 提议新功能或改进 +title: "[Feature] " +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: 想解决什么问题？ + description: 描述你遇到的实际场景或痛点。 + validations: + required: true + - type: textarea + id: proposal + attributes: + label: 建议方案 + description: 期望的功能或交互。可附草图 / 示例。 + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: 备选方案 + description: 你考虑过哪些其他做法？为什么没采用？ + - type: dropdown + id: workspace + attributes: + label: 涉及的工作区 + multiple: true + options: + - 后端 (backend/) + - Web 前端 (BillNote_frontend/) + - 浏览器插件 (BillNote_extension/) + - Tauri 桌面端 + - 不确定 + - type: textarea + id: extra + attributes: + label: 其他补充 + description: 关联 issue、参考资料、产品截图等 diff --git a/.github/ISSUE_TEMPLATE/新增功能建议.md b/.github/ISSUE_TEMPLATE/新增功能建议.md deleted file mode 100644 index bdaeb29..0000000 --- a/.github/ISSUE_TEMPLATE/新增功能建议.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: 新增功能建议 -about: 一些新的功能建议 -title: "[FEATHURE]" -labels: enhancement -assignees: JefferyHcool - ---- - ---- -name: ✨ 功能请求 -about: 提出一个新的功能建议 -title: "[Feature] " -labels: enhancement -assignees: '' - ---- - -**这个功能请求是否与某个问题相关？请描述** -清晰简要地描述问题是什么。例如：每次遇到 [...] 都让我感到很沮丧。 - -**描述你希望实现的解决方案** -清晰简要地描述你希望发生的事情。 - -**描述你考虑过的备选方案** -清晰简要地描述你考虑过的其他解决方案或功能。 - -**其他补充信息** -请在此添加关于功能请求的其他上下文或截图。 diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..0110ac7 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,39 @@ + + +## 改动概述 + + + +## 为什么 + + + +## 做了什么 + + + +## 测试方式 + +- [ ] `pnpm typecheck && pnpm build`（前端 / 插件）通过 +- [ ] `python -m py_compile <文件>` 或本地 backend 启动验证（后端）通过 +- [ ] 手动验证步骤： + + +## 回归风险 + + + +## Checklist + +- [ ] 分支命名遵循 [CONTRIBUTING.md §3](../CONTRIBUTING.md#3-分支命名)（`feature/*` / `fix/*` / `release/*` / `hotfix/*`） +- [ ] base 分支正确（常规改动 → `develop`；线上紧急 → `master`；发版 → 见 §4.3） +- [ ] Commit message 遵循 `type(scope): subject` 格式（[CONTRIBUTING.md §5.1](../CONTRIBUTING.md#51-commit-message-格式)） +- [ ] 已自测核心流程 +- [ ] 已更新相关文档（`README.md` / `CHANGELOG.md` / `CLAUDE.md` / 模块 README，如适用） +- [ ] 未夹带 secrets / `.env` / 大型二进制 +- [ ] 单 PR 不跨多个工作区做无关改动 diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml new file mode 100644 index 0000000..8ae2aa6 --- /dev/null +++ b/.github/workflows/commitlint.yml @@ -0,0 +1,32 @@ +name: Commit Lint + +on: + pull_request: + types: [opened, synchronize, reopened, edited] + push: + branches: + - develop + - master + +permissions: + contents: read + pull-requests: read + +jobs: + commitlint: + name: Lint commit messages + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Run commitlint + uses: wagoid/commitlint-github-action@v6 + with: + configFile: .commitlintrc.json + # PR 上检查 base..head 之间所有 commit；push 上只校验最新 commit + firstParent: false + failOnWarnings: false + helpURL: https://github.com/JefferyHcool/BiliNote/blob/develop/CONTRIBUTING.md#5-提交规范 diff --git a/.github/workflows/release-extension.yml b/.github/workflows/release-extension.yml new file mode 100644 index 0000000..2bab3bc --- /dev/null +++ b/.github/workflows/release-extension.yml @@ -0,0 +1,115 @@ +name: Release Extension + +# 在 v* tag push 时触发，构建插件并把产物挂到对应 GitHub Release。 +# 商店上传仍走人工（详见 RELEASING.md）；如果将来配齐了商店 API secrets， +# 把本文件末尾注释的 publish-* job 解开就是自动发布。 + +on: + push: + tags: + - 'v*' + +permissions: + contents: write + +jobs: + build: + name: Build & attach to release + runs-on: ubuntu-latest + defaults: + run: + working-directory: BillNote_extension + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup pnpm + uses: pnpm/action-setup@v3 + with: + version: 9 + + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: pnpm + cache-dependency-path: BillNote_extension/pnpm-lock.yaml + + - name: Install + run: pnpm install --frozen-lockfile + + - name: Build + run: pnpm build + + - name: Pack zip (Chrome / Edge upload format) + run: pnpm pack:zip + + - name: Pack xpi (Firefox Add-ons) + run: pnpm pack:xpi + + - name: Pack crx (self-host sideload) + # crx 需要稳定 key.pem 才能保持插件 ID 不变；CI 没有就跳过，不阻塞主流程。 + # 想生成稳定 crx：把 key 存到 secret EXTENSION_CRX_KEY，下面解开几行。 + run: | + # if [ -n "${{ secrets.EXTENSION_CRX_KEY }}" ]; then + # echo "${{ secrets.EXTENSION_CRX_KEY }}" > key.pem + # pnpm pack:crx + # else + pnpm pack:crx || true + # fi + continue-on-error: true + + - name: Rename artifacts with version suffix + run: | + VERSION="${GITHUB_REF#refs/tags/v}" + [ -f extension.zip ] && mv extension.zip "bilinote-extension-${VERSION}.zip" + [ -f extension.xpi ] && mv extension.xpi "bilinote-extension-${VERSION}.xpi" + [ -f extension.crx ] && mv extension.crx "bilinote-extension-${VERSION}.crx" + ls -la *.zip *.xpi *.crx 2>/dev/null || true + + - name: Attach to GitHub Release + uses: softprops/action-gh-release@v2 + with: + files: | + BillNote_extension/bilinote-extension-*.zip + BillNote_extension/bilinote-extension-*.xpi + BillNote_extension/bilinote-extension-*.crx + fail_on_unmatched_files: false + generate_release_notes: false + +# ---------- 商店自动发布（默认禁用，配齐 secrets 后可启用） ---------- +# +# publish-chrome: +# needs: build +# runs-on: ubuntu-latest +# steps: +# - uses: actions/download-artifact@v4 +# - uses: mnao305/chrome-extension-upload@v5 +# with: +# file-path: BillNote_extension/bilinote-extension-${{ github.ref_name }}.zip +# extension-id: ${{ secrets.CHROME_EXTENSION_ID }} +# client-id: ${{ secrets.CHROME_CLIENT_ID }} +# client-secret: ${{ secrets.CHROME_CLIENT_SECRET }} +# refresh-token: ${{ secrets.CHROME_REFRESH_TOKEN }} +# +# publish-edge: +# needs: build +# runs-on: ubuntu-latest +# steps: +# - uses: wdzeng/edge-addon@v2 +# with: +# product-id: ${{ secrets.EDGE_PRODUCT_ID }} +# zip-path: BillNote_extension/bilinote-extension-${{ github.ref_name }}.zip +# client-id: ${{ secrets.EDGE_CLIENT_ID }} +# api-key: ${{ secrets.EDGE_API_KEY }} +# +# publish-firefox: +# needs: build +# runs-on: ubuntu-latest +# steps: +# - uses: trmcnvn/firefox-addon@v3 +# with: +# uuid: ${{ secrets.FIREFOX_ADDON_UUID }} +# xpi: BillNote_extension/bilinote-extension-${{ github.ref_name }}.xpi +# api-key: ${{ secrets.FIREFOX_API_KEY }} +# api-secret: ${{ secrets.FIREFOX_API_SECRET }} diff --git a/BillNote_frontend/src/assets/wechat.png b/BillNote_frontend/src/assets/wechat.png new file mode 100644 index 0000000..44639cc Binary files /dev/null and b/BillNote_frontend/src/assets/wechat.png differ diff --git a/BillNote_frontend/src/pages/SettingPage/about.tsx b/BillNote_frontend/src/pages/SettingPage/about.tsx index c4c1ce0..203e5aa 100644 --- a/BillNote_frontend/src/pages/SettingPage/about.tsx +++ b/BillNote_frontend/src/pages/SettingPage/about.tsx @@ -5,6 +5,7 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs' import { Github, Star, ExternalLink, Download } from 'lucide-react' import { ScrollArea } from '@/components/ui/scroll-area.tsx' import logo from '@/assets/icon.svg' +import wechatQr from '@/assets/wechat.png' export default function AboutPage() { const images = [ @@ -197,14 +198,10 @@ export default function AboutPage() {

联系和加入社区

-
-

BiliNote 交流 QQ 群

-

785367111

-

BiliNote 交流微信群

- + BiliNote 交流微信群
diff --git a/CHANGELOG.md b/CHANGELOG.md index 3082c1c..ecb0a24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,29 @@ 本项目所有重要变更记录于此。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [2.1.1] - 2026-05-07 + +工程化与文档收尾，无运行时行为变化。 + +### Added + +- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — 贡献指南，落地简化 Git Flow（master + develop + 短生命周期分支）+ 提交规范 + 合并规范 +- [`RELEASING.md`](./RELEASING.md) — 发版手册（Release Manager 视角），含 release/* 流程 + 各商店人工上传步骤 + 自动发布所需 secrets +- `.github/ISSUE_TEMPLATE/{config,bug_report,feature_request}.yml` — 表单形式的 issue 模板，按工作区分类 +- `.github/pull_request_template.md` — PR 模板，把 CONTRIBUTING §5.2 落成 checklist +- `.commitlintrc.json` + `.github/workflows/commitlint.yml` — commitlint CI（PR + push develop/master 时校验，自定义 type 白名单，兼容中文 subject） +- `.github/workflows/release-extension.yml` — `v*` tag push 时自动构建插件 .zip / .xpi / .crx 并挂到对应 GitHub Release（商店自动发布以注释形式预留） + +### Changed + +- 关于页二维码改为 `import @/assets/wechat.png`，不再依赖腾讯云 COS CDN，更新只需替换文件 + 跑构建 +- 群聊 QR 替换为最新版本（`doc/wechat.png` + `BillNote_frontend/src/assets/wechat.png`） + +### Removed + +- 关于页 QQ 群联系方式（号 785367111，已不再活跃维护） +- 旧版 `.md` 格式 issue 模板（被新 yml 表单模板取代） + ## [2.1.0] - 2026-05-07 本次发布的主线是**浏览器插件**和 **B 站字幕优先链路**。配合一些后端 / 前端体验修复。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5085696 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,340 @@ +# 贡献指南 + +欢迎为 BiliNote 贡献代码。本文档约定分支管理、提交规范、合并流程。新贡献者请通读一遍后再开 PR。 + +> 关联文档 +> - [README.md](./README.md)：项目概览、快速开始 +> - [CLAUDE.md](./CLAUDE.md)：仓库结构 + 各 workspace 开发命令 +> - [CHANGELOG.md](./CHANGELOG.md)：版本变更记录 +> - [RELEASING.md](./RELEASING.md)：发版执行手册（Release Manager 视角） + +--- + +## 1. 仓库结构与工作区 + +本仓库为多工作区单体仓： + +| 路径 | 内容 | 主要命令 | +|---|---|---| +| `backend/` | Python 3.11 + FastAPI | `pip install -r requirements.txt && python main.py` | +| `BillNote_frontend/` | React 19 + Vite | `pnpm install && pnpm dev` | +| `BillNote_extension/` | Vue 3 + Vite + WebExtension MV3 | `pnpm install && pnpm dev` | + +详细结构与开发命令见 [CLAUDE.md](./CLAUDE.md)。提交时**单 PR 不要跨多个工作区做无关改动**，便于评审与回滚。 + +--- + +## 2. 分支模型 + +采用简化 Git Flow：稳定主干 `master` + 长期开发集成 `develop` + 短生命周期业务分支。 + +| 分支类型 | 命名 | 长期保留 | 创建来源 | 合并去向 | 用途 | +|---|---|---|---|---|---| +| 生产主干 | `master` | ✅ | 仓库默认分支 | — | 始终保持可发布状态；只接收 `release/*` 与 `hotfix/*` 合入 | +| 开发主干 | `develop` | ✅ | `master` | `release/*` 回灌后 | 日常需求集成；常规开发都从这里起 | +| 功能分支 | `feature/*` | ❌ | `develop` | `develop` | 新功能 / 需求开发 | +| 修复分支 | `fix/*` | ❌ | `develop` | `develop` | 开发期间发现的缺陷修复（非线上问题） | +| 发布分支 | `release/*` | ❌ | `develop` | `master` + `develop` | 版本冻结、回归、发版准备 | +| 热修复 | `hotfix/*` | ❌ | `master` | `master` + `develop` | 线上紧急问题 | + +### 基本原则 + +- `master` 只保存**已发布代码**，不接受日常开发提交。 +- `develop` 是**唯一**长期开发集成分支。 +- 所有业务开发**必须**用短生命周期分支，禁止长期占用个人开发分支。 +- 一个分支只承载一个需求或一类明确的修复事项。 + +--- + +## 3. 分支命名 + +### 命名格式 + +``` +feature/-<事项> +fix/-<事项> +release/<版本号> +hotfix/-<事项> +``` + +`` 优先用代码 scope（与 commit message scope 对齐，见 §5），常用： + +- `extension` — 浏览器插件（`BillNote_extension/`） +- `frontend` — Web 前端（`BillNote_frontend/`） +- `backend` — Python 后端（`backend/`） +- `bilibili` / `youtube` / `douyin` / `kuaishou` — 平台特定改动 +- `transcriber` — 音频转写 +- `gpt` / `chat` — LLM / RAG +- `docker` / `ci` — 构建与发布 +- `docs` — 文档 + +### 命名示例 + +```bash +# 功能开发 +feature/extension-side-panel +feature/youtube-subtitle-innertube +feature/backend-rag-chat + +# 开发期修复 +fix/extension-task-status-unwrap +fix/bilibili-cookie-injection +fix/mlx-whisper-repo-id + +# 发版 +release/2.1.0 +release/2.2.0 + +# 线上热修 +hotfix/backend-cors-regex +hotfix/frontend-provider-switch +``` + +### 命名要求 + +- 全小写字母 / 数字 / 中划线 +- `<事项>` 要表达**具体行为**，避免 `test` / `update` / `temp` / `wip` 这类无意义名 +- `release/<版本号>` 必须与实际 tag 一致（如 `release/2.1.0` ↔ `v2.1.0`） + +--- + +## 4. 标准协作流程 + +### 4.1 日常需求开发 + +```bash +git checkout develop +git pull origin develop +git checkout -b feature/-<事项> + +# … 开发 + 自测 + commit … + +git push -u origin feature/-<事项> +# 在 GitHub 上发起 PR：base = develop，compare = 你的分支 +``` + +合并通过且 PR closed 后，**删除本地与远端分支**： + +```bash +git branch -d feature/-<事项> +git push origin --delete feature/-<事项> +``` + +### 4.2 开发期缺陷修复 + +提测或联调中发现问题时，从 `develop` 切 `fix/*`。**不要在原 `feature/*` 上长期叠加零散修复**。 + +适用场景： +- 已合入 `develop` 后被测试打回的问题 +- 多个功能集成后暴露的兼容性问题 +- 非线上环境问题 + +### 4.3 版本发布 + +```bash +# 1. 从 develop 切 release +git checkout develop && git pull origin develop +git checkout -b release/<版本号> + +# 2. 在 release 分支上：更新 README 版本号、写 CHANGELOG.md、必要的小修 +git commit -am "docs: <版本号> CHANGELOG + README 版本" +git push -u origin release/<版本号> + +# 3. 进入冻结期，PR base=master 合并；同时 PR base=develop 回灌 +# 4. master 上打 tag +git checkout master && git pull +git tag -a v<版本号> -m "BiliNote v<版本号>" && git push origin v<版本号> + +# 5. release 分支已合入两边，删除 +git push origin --delete release/<版本号> +``` + +要点： +- **冻结期内 `release/*` 不再合入新需求**，只允许修复发布缺陷。 +- 发版窗口期内的新需求继续基于 `develop` 开发，**不进入当前 `release/*`**。 +- 发布完成后必须把 `release/*` 同步回 `develop`，避免漏修。 + +### 4.4 线上紧急修复 + +```bash +git checkout master && git pull +git checkout -b hotfix/-<事项> +# … 修 + commit … +# PR base=master，合入后立刻打 patch tag（如 v2.1.1）发版 +# 同一改动同时 PR base=develop 回灌 +``` + +要点： +- `hotfix/*` 仅处理**线上阻断性 / 高优先级**缺陷。 +- 非紧急问题不得绕过 `develop` 直接走热修流程。 +- 若当前存在 `release/*` 即将发布，需评估是否同步到对应 release，避免修复丢失。 + +--- + +## 5. 提交规范 + +### 5.1 Commit message 格式 + +> CI 已接入 [commitlint](https://commitlint.js.org)（[`.commitlintrc.json`](./.commitlintrc.json) + [`.github/workflows/commitlint.yml`](./.github/workflows/commitlint.yml)）。 +> PR 上所有 commit 都会被校验，type 不在白名单时合并按钮会被卡。 + +``` +type(scope): subject +``` + +例： + +``` +feat(extension): 侧边栏接入思维导图（markmap）与 RAG 问答 +fix(bilibili): 修正字幕优先链路在未登录态下的回退 +docs(contributing): 新增贡献指南 +chore(ci): 优化 docker 构建缓存 +``` + +#### type + +| type | 说明 | +|---|---| +| `feat` | 新功能 | +| `fix` | 缺陷修复 | +| `docs` | 文档变更 | +| `style` | 代码风格调整（不影响行为） | +| `refactor` | 重构（非 feat / 非 fix） | +| `perf` | 性能优化 | +| `test` | 测试增删 | +| `build` | 构建系统 / 依赖变更 | +| `ci` | CI 配置变更 | +| `chore` | 杂项（不归入以上类别） | +| `ui` | 界面 / 交互层调整（仓库内既有用法） | +| `revert` | 回滚 | + +#### scope + +与 §3 的分支 scope 保持一致：`extension` / `frontend` / `backend` / `bilibili` / `youtube` / `douyin` / `kuaishou` / `transcriber` / `gpt` / `chat` / `docker` / `ci` / `docs` 等。 + +#### subject + +- 用中文或英文都可以，**保持一种风格**。 +- 用现在时陈述（"新增 X" / "修复 Y" / "Add X" / "Fix Y"）。 +- 首字母不大写，结尾不加句号。 +- 单行控制在 72 字符以内；如需详细说明，正文与标题之间空一行。 + +### 5.2 PR 标题与正文 + +- **PR 标题**沿用 commit message 格式，描述本次 PR 的总体改动。 +- **PR 正文**应包含： + - 改动的"为什么"（背景 / issue / 用户场景） + - 改动的"做了什么"（关键文件、关键决策） + - **测试方式**（如何验证、覆盖了哪些 case） + - **回归风险**与影响面 + - 是否需要后端 / 前端 / 配置同步部署 + +--- + +## 6. 合并规范 + +### 6.1 合并前要求 + +- 合并前必须**先同步**目标分支最新代码（`git pull --rebase` 或在 PR 上点 "Update branch"）。 +- 合并前必须完成**自测**，确保核心流程可用。 +- 后端改动需 `python -m py_compile` 至少通过；前端 / 插件改动需 `pnpm typecheck && pnpm build` 通过。 +- **冲突由分支负责人解决**，不得留给评审人或发版人员。 + +### 6.2 评审 + +- 默认通过 PR 合并，**不允许**绕过 PR 直接 push 到 `master` 或 `develop`。 +- 评审人至少关注：业务影响、回归风险、是否夹带无关改动、目录归属是否合理。 +- 修文档 / 改注释这种小变更允许 1 人评审通过；改业务逻辑 / 协议 / 共享模块至少 2 人评审。 + +### 6.3 合并方式 + +- `feature/*` / `fix/*` 合入 `develop`：推荐 **Squash and merge**，保持 develop 历史线性。 +- `release/*` 合入 `master` 与回灌 `develop`：使用 **Merge commit (--no-ff)**，保留发版结构。 +- `hotfix/*` 同上 release。 + +### 6.4 合并后 + +- 短期分支合并完成后**必须删除**（远端 + 本地）。 +- 已完成的分支不得继续承接新需求；如需后续迭代请重新基于最新目标分支开新分支。 + +--- + +## 7. Git 钩子注意事项 + +`BillNote_extension/` 早期使用 `simple-git-hooks` 的 `postinstall`，会在仓库根目录 `.git/hooks/pre-commit` 注入 `pnpm lint-staged`，但仓库根没有 `package.json`，导致**任何 commit 都被钩子卡死**。**已在 v2.1.0 起移除**该 postinstall 配置。 + +如果你机器上还残留旧版本装下来的 hook： + +```bash +# 一次性清理 +rm .git/hooks/pre-commit + +# 或临时绕过本次 commit +SKIP_SIMPLE_GIT_HOOKS=1 git commit -m "..." +``` + +--- + +## 8. 版本号与 CHANGELOG + +- 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)：`MAJOR.MINOR.PATCH` + - `MAJOR`：破坏性 API 变更或重大重构 + - `MINOR`：新增特性、向后兼容 + - `PATCH`：bug 修复、向后兼容 +- 每次发版**必须更新 [CHANGELOG.md](./CHANGELOG.md)**，按 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 格式分类（Added / Changed / Fixed / Removed / Security / Internal）。 +- 发版同时更新 `README.md` 顶部的版本号与"v\<版本号\> 新增"摘要段。 +- `master` 上打 tag 形如 `vX.Y.Z`，注释中包含本次发布主线 + 引用 `CHANGELOG.md`。 + +--- + +## 9. 禁止事项 + +- ❌ 直接在 `master` 上开发、提交、修复普通问题 +- ❌ 新增长期 `dev-*` / `wip-*` / `<姓名>-dev` 个人分支作为日常协作分支 +- ❌ 一个分支同时承载多个需求 / 多个缺陷 / 跨版本内容 +- ❌ 未评审、未自测、未通过基础校验直接合并 +- ❌ `release/*` 冻结后继续混入新需求 +- ❌ `hotfix/*` 只合入 `master` 而不回灌 `develop` +- ❌ 提交 / 仓库内包含密钥、API key、`.env` 等敏感文件 +- ❌ 提交 `node_modules/` / `dist/` / `extension/dist/` / `__pycache__/` / 大型二进制（参考各级 `.gitignore`） + +--- + +## 10. 历史分支迁移 + +仓库历史上存在多条已合并但未删除的分支（见 `git branch -a`）。即日起： + +- 不再创建 `dev-*` / `<姓名>-*` 个人分支 +- 已合入主干的旧分支，由发版人统一清理 +- 未完成需求应尽快迁移到符合 §3 命名规范的新分支 + +--- + +## 11. 推荐流程图 + +```text +master ← hotfix/* (线上紧急修复) + ↑ ↑ + │ │ +release/* ← develop ← feature/* (功能开发) + │ ↑ + └───────────┘ + fix/* (开发期修复) + 回灌 +``` + +--- + +## 12. 执行口径速查 + +| 场景 | 流程 | +|---|---| +| 新功能 | `develop` → `feature/*` → `develop` | +| 提测后发现问题 | `develop` → `fix/*` → `develop` | +| 版本发布 | `develop` → `release/*` → `master` + `develop`；打 tag | +| 线上紧急故障 | `master` → `hotfix/*` → `master` + `develop`；打 patch tag | +| 发版期内新需求 | 基于 `develop` 开 `feature/*`，**不**进入当前 `release/*` | + +--- + +如有改进建议，欢迎开 PR 修订本文档（`docs(contributing): ...`）。 diff --git a/README.md b/README.md index 742a429..595f7b8 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@

BiliNote Banner

-

BiliNote v2.1.0

+

BiliNote v2.1.1

AI 视频笔记生成工具 让 AI 为你的视频做笔记

@@ -53,6 +53,13 @@ BiliNote 是一个开源的 AI 视频笔记助手，支持通过哔哩哔哩、Y - 笔记顶部视频封面 Banner 展示 - 工作区和生成历史面板支持折叠/展开 +### v2.1.1 修订 + +- 工程化与文档收尾：CONTRIBUTING.md / RELEASING.md / issue + PR 模板 / commitlint CI / 插件发版工作流 +- 关于页群聊二维码：换成最新版，改为 import 本地资源，不再依赖 CDN +- 关于页移除 QQ 群入口（仅保留微信群） +- 详见 [CHANGELOG.md](./CHANGELOG.md) + ### v2.1.0 新增 - 浏览器插件（Chrome / Edge / Firefox MV3）—— 工具栏 popup、视频页悬浮按钮、右键菜单、侧边栏（Markdown / 思维导图 / AI 问答）四件套 diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..8a46202 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,158 @@ +# 发版手册（Release Manager） + +本文档面向**发版执行者**，覆盖从 `develop` 切发版到产物上架商店的完整步骤。日常分支与提交规范见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 + +--- + +## 流程总览 + +``` +develop ──→ release/X.Y.Z ──→ PR ─→ master ──→ 打 tag vX.Y.Z + │ │ │ + └──→ PR 回灌 ──→ develop └──→ CI 自动构建插件产物 + 挂到 GitHub Release + ↓ + 人工上传商店（Chrome/Edge/Firefox） +``` + +--- + +## 1. 切发布分支 + +```bash +git checkout develop && git pull origin develop +git checkout -b release/X.Y.Z +``` + +版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)：`MAJOR.MINOR.PATCH`。 + +## 2. 写 CHANGELOG，更新版本号 + +在 `release/X.Y.Z` 上： + +- 编辑 [`CHANGELOG.md`](./CHANGELOG.md)，新增 `## [X.Y.Z] - YYYY-MM-DD` 段，按 Keep a Changelog 分类（Added / Changed / Fixed / Removed / Security / Internal） +- 编辑 [`README.md`](./README.md) 顶部标题中的版本号 + 新增"vX.Y.Z 新增"摘要段 +- 重大变更也同步更新 [`CLAUDE.md`](./CLAUDE.md) + +```bash +git commit -am "docs: vX.Y.Z CHANGELOG + README 版本" +git push -u origin release/X.Y.Z +``` + +## 3. 合并到 master + 回灌 develop + +在 GitHub 上发起两个 PR： + +| PR | base | 合并方式 | +|---|---|---| +| `release/X.Y.Z` → `master` | `master` | **Merge commit (--no-ff)** | +| `release/X.Y.Z` → `develop` | `develop` | **Merge commit (--no-ff)** | + +`master` 分支保护要求 review 通过。回灌 `develop` 是为了把发版冻结期内的小修同步回来。 + +## 4. 打 tag + +```bash +git checkout master && git pull origin master +git tag -a vX.Y.Z -m "BiliNote vX.Y.Z + +主线： +- ... + +详见 CHANGELOG.md" +git push origin vX.Y.Z +``` + +push tag **会自动触发 [`.github/workflows/release-extension.yml`](.github/workflows/release-extension.yml)**：构建插件并把 `.zip` / `.xpi` / `.crx` 挂到对应 GitHub Release。 + +## 5. 创建 GitHub Release（如果还没有） + +CI 默认会创建 / 更新 `vX.Y.Z` 对应的 Release。如果你想自己写 release notes： + +1. 打开 https://github.com/JefferyHcool/BiliNote/releases/new +2. Tag: 选 `vX.Y.Z` +3. Title: `vX.Y.Z` +4. Body: 直接贴 [`CHANGELOG.md`](./CHANGELOG.md) 的对应段 +5. CI 跑完后 Release 页面会自动出现 `bilinote-extension-X.Y.Z.zip` / `.xpi` / `.crx` + +## 6. 上传到各商店（人工） + +商店审核普遍 1-3 个工作日。建议**先上 Chrome → Edge → Firefox**（Edge 接受同一份 zip）。 + +### Chrome Web Store + +1. https://chrome.google.com/webstore/devconsole +2. 选 BiliNote → 左侧 **Package** → **Upload new package** +3. 上传 `bilinote-extension-X.Y.Z.zip` +4. 检查 listing（描述 / 图标 / 截图无变化可保持），点 **Submit for review** + +### Microsoft Edge Add-ons + +1. https://partner.microsoft.com/dashboard/microsoftedge +2. 选 BiliNote → **New submission** +3. 上传同一份 `.zip`（Edge Add-ons 与 Chrome 完全兼容 MV3） +4. 提交审核 + +### Firefox Add-ons (AMO) + +1. https://addons.mozilla.org/developers/ +2. 选 BiliNote → **Upload New Version** +3. 上传 `bilinote-extension-X.Y.Z.xpi` +4. 选择"在 AMO 公开"或"自托管" +5. 提交审核 + +### 桌面端 (Tauri) + +仓库已有 GitHub Actions 在 `v*` tag 时构建桌面端安装包并自动挂到 GitHub Release，无需额外操作。 + +## 7. 清理 + +```bash +# release 分支已合到 master 与 develop，删掉 +git push origin --delete release/X.Y.Z +git branch -d release/X.Y.Z +``` + +--- + +## 自动发布到商店（可选） + +`.github/workflows/release-extension.yml` 末尾有三段商店自动发布的 job 注释。要启用： + +1. 在 https://github.com/JefferyHcool/BiliNote/settings/secrets/actions 加 secrets： + +| 商店 | 需要的 secret | +|---|---| +| Chrome | `CHROME_EXTENSION_ID`、`CHROME_CLIENT_ID`、`CHROME_CLIENT_SECRET`、`CHROME_REFRESH_TOKEN` | +| Edge | `EDGE_PRODUCT_ID`、`EDGE_CLIENT_ID`、`EDGE_API_KEY` | +| Firefox | `FIREFOX_ADDON_UUID`、`FIREFOX_API_KEY`、`FIREFOX_API_SECRET` | + +2. 解开 workflow 文件末尾的 `publish-chrome` / `publish-edge` / `publish-firefox` job 注释。 +3. 推 tag 时即自动发布。 + +> Chrome 各 secret 的获取方式：[chrome-webstore-upload-cli 文档](https://github.com/fregante/chrome-webstore-upload-cli/blob/main/How%20to%20generate%20Google%20API%20keys.md) +> Edge：[Edge Add-ons API](https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/api/using-addons-api) +> Firefox：https://addons.mozilla.org/en-US/developers/addon/api/key/ + +--- + +## 紧急 hotfix 发版 + +线上紧急问题不走 `release/*`，走 `hotfix/*`： + +```bash +git checkout master && git pull +git checkout -b hotfix/-<事项> +# … 修复 ... +# PR base=master 合入；同时 PR base=develop 回灌 +``` + +合入 master 后通常打 patch tag（如 `v2.1.1`），CI 流程同上。 + +--- + +## 历史发布快查 + +| Version | Date | Tag | +|---|---|---| +| 2.1.0 | 2026-05-07 | [`v2.1.0`](https://github.com/JefferyHcool/BiliNote/releases/tag/v2.1.0) | +| 2.0.0 | (上游 web 端 v2.0.0) | [`v2.0.0`](https://github.com/JefferyHcool/BiliNote/releases/tag/v2.0.0) | diff --git a/doc/wechat.png b/doc/wechat.png index f88ccf1..44639cc 100644 Binary files a/doc/wechat.png and b/doc/wechat.png differ