# Contributing to FluxDown

感谢你有意为 FluxDown 做贡献！/ Thank you for your interest in contributing to FluxDown!

## 开发流程 / Development Workflow

1. Fork 本仓库并从 `main` 创建分支，PR 也提交到 `main`（`main` 是开发分支；`stable` 是稳定分支，只由维护者从 `main` 合并前进，请勿直接对其提 PR）。
   Fork the repository and branch off `main`, then target `main` with your PR (`main` is the development branch; `stable` is the stable branch that maintainers advance from `main` — do not open PRs against it).
2. 遵循仓库根目录 `AGENTS.md` 中的代码风格与规范（Rust: `cargo fmt --check && cargo clippy -- -D warnings`；Dart: `flutter analyze`）。
   Follow the code style and conventions in `AGENTS.md` at the repository root (Rust: `cargo fmt --check && cargo clippy -- -D warnings`; Dart: `flutter analyze`).
3. 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)（Release Notes 由 git-cliff 自动生成）。
   Write commit messages following [Conventional Commits](https://www.conventionalcommits.org/) — release notes are generated by git-cliff.
4. 提交 PR 前确保相关 crate 的测试通过（例如 `cargo test -p fluxdown_engine`）。
   Make sure the tests for the affected crates pass before opening a PR (e.g. `cargo test -p fluxdown_engine`).

## 自动审查与合并 / Automated Review & Merge

PR 由维护机器人 [@ZerxLabBot](https://github.com/ZerxLabBot) 自动审查：新开或从草稿转为可审查时审查一次；之后推送新提交**不会**自动重审，修改完成后在 PR 下评论 `@ZerxLabBot review` 即可请求复审（同一 PR 15 分钟内一次、每天最多 5 次）。
PRs are reviewed automatically by [@ZerxLabBot](https://github.com/ZerxLabBot): once when opened or marked ready for review. New pushes do **not** trigger another review — comment `@ZerxLabBot review` on the PR when you are ready (at most once per 15 minutes and 5 times per day per PR).

不涉及 UI、改动规模适中且 CI 全绿的 PR，在审查与独立复核都通过后会进入短暂的等待期，然后自动合并；涉及界面、构建 / 发布流程、依赖或 CI 覆盖不到的平台代码时，交由维护者人工审查。勾选 PR 侧栏的 “Allow edits by maintainers” 后，与 `main` 的合并冲突可由机器人代为解决。
Non-UI PRs of moderate size with green CI are merged automatically after the review and an independent second check pass, following a short waiting period. Changes touching the UI, build/release tooling, dependencies, or platform code that CI cannot build go to a maintainer. Enabling “Allow edits by maintainers” lets the bot resolve merge conflicts with `main` for you.

## GPUI 桌面开发 / GPUI Desktop Development

```bash
cargo desktop-dev
cargo desktop-dev --build-only
```

首次启动先构建 UI、agent 和 daemon，全部成功后才打开 UI。重复执行时优先唤起已有 UI，不再构建或创建第二个窗口进程；多个启动命令并发执行时会串行处理构建。`--build-only` 只构建，不启动或唤起任何窗口。
The first launch builds the UI, agent and daemon before opening the UI. Repeated invocations activate the existing UI without rebuilding or creating another UI process; concurrent development builds are serialized. `--build-only` neither launches nor activates a window.

UI、agent 和 daemon 按各自数据目录保持单实例；已有后台服务直接复用，不会被开发命令强制结束。托盘由 agent 承载（开发构建带 `--features fluxdown_agent/desktop`）：开启「关闭时最小化到托盘」且托盘可用时，关闭窗口只退出 UI，下载与队列在后台继续；菜单「退出」/ ⌘Q 或托盘「退出」会完全退出（agent 先停止 daemon）。UI 与后台服务分属独立进程组，终端 Ctrl+C 只结束前台进程，不能当作整套服务停止操作。
UI, agent and daemon enforce one instance per respective data directory. Existing services are reused, never forcibly terminated by this command. The tray lives in the agent (development builds use `--features fluxdown_agent/desktop`): with "Minimize to Tray on Close" on and a tray available, closing the window only exits the UI while downloads and queues keep running; the Quit menu item, ⌘Q or the tray's Exit performs a full quit (the agent stops the daemon first). The UI and background services run in separate process groups, so terminal Ctrl+C only ends the foreground process and is not a full-stack shutdown.

修改运行中的代码后，需先退出对应旧进程，再重新执行命令；重新编译不会热替换已有 UI 或后台服务。Windows 不允许覆盖正在运行的二进制，构建前应先退出对应进程。使用同一引擎数据目录的 Flutter 版必须先退出。自定义 `FLUXDOWN_AGENT_BIN` / `FLUXDOWN_DAEMON_BIN` 仍优先于同目录二进制。
After editing running code, exit the affected processes before launching again; rebuilding does not hot-replace an existing UI or service. On Windows, exit affected processes before rebuilding their executables. Quit Flutter first if it uses the same engine data directory. `FLUXDOWN_AGENT_BIN` / `FLUXDOWN_DAEMON_BIN` overrides still take precedence over sibling executables.


## 反馈问题 / Reporting Issues

请通过 [GitHub Issues](https://github.com/zerx-lab/FluxDown/issues) 或官网 [反馈页面](https://fluxdown.zerx.dev/feedback) 提交问题。
Please report problems via [GitHub Issues](https://github.com/zerx-lab/FluxDown/issues) or the [feedback page](https://fluxdown.zerx.dev/feedback) on the official site.

## 文档贡献 / Documentation Contributions

FluxDown 官网文档（<https://fluxdown.zerx.dev/docs/>）与源码同仓库维护，欢迎通过 Pull Request 贡献或翻译。
The FluxDown documentation site (<https://fluxdown.zerx.dev/docs/>) is maintained in this repository — contributions and translations via Pull Request are welcome.

### 快速编辑 / Quick Edit

每篇文档页面都有"编辑此页"链接，点击后直接跳转到 GitHub 网页编辑器（指向 `main` 分支，无写权限时会自动引导 Fork），改完直接提交 PR 即可，不需要本地克隆仓库。
Every documentation page has an "Edit this page" link that opens the GitHub web editor on the `main` branch (auto-forks if you lack write access) — edit and submit a PR, no local clone required.

### 目录结构 / Directory Layout

文档源文件位于 `website-v2/src/content/docs/{en,zh}/`，按语言分目录，子目录与文件名一一对应（`website/` 是 `/v1` 旧站存档，不再接收文档改动）：
Documentation source files live under `website-v2/src/content/docs/{en,zh}/`, one directory per language, with matching subdirectory/filename structure across languages (`website/` is the archived `/v1` site and no longer accepts doc changes):

```text
website-v2/src/content/docs/
├── en/
│   ├── getting-started/installation.md
│   └── ...
└── zh/
    ├── getting-started/installation.md
    └── ...
```

### Frontmatter 字段 / Frontmatter Fields

每篇文档文件头部为 YAML frontmatter：
Each file starts with a YAML frontmatter block:

| 字段 / Field | 必填 / Required | 说明 / Description |
| --- | --- | --- |
| `title` | 是 / Yes | 页面标题 / Page title |
| `description` | 否 / No | 用于 SEO meta description / Used for the SEO meta description |
| `section` | 是 / Yes | 所属分区（`getting-started`\|`protocols`\|`browser-extension`\|`headless-server`\|`api`\|`contributing`）/ One of the fixed section enum values |
| `order` | 否 / No | 侧边栏排序，数字越小越靠前，默认 999 / Sidebar ordering, lower sorts first, defaults to 999 |
| `sourceHash` | 否，仅 zh 译文 / No, zh translations only | 对应 en 原文内容的哈希，用于检测译文是否过期，详见下文"翻译流程" / Hash of the corresponding en source content, used to detect stale translations — see "Translation Workflow" below |

### 翻译流程 / Translation Workflow

1. 在 `zh/` 下创建与 `en/` 对应路径同名的文件（每篇英文页面的"新建翻译"深链会自动引导到正确目录）。
   Create a file under `zh/` at the same relative path as its `en/` counterpart (the "New translation" deep link on each English page opens the correct target directory automatically).
2. 翻译完成后，在 `website-v2/` 目录下运行 `npm run docs:hash <zh 文件相对路径>`，自动写入 frontmatter 中的 `sourceHash` 字段。
   After translating, run `npm run docs:hash <path to the zh file>` from the `website-v2/` directory to write the `sourceHash` frontmatter field automatically.
3. 无法本地运行脚本也没关系（例如仅使用网页编辑器）：在 PR 描述中说明留空，并勾选 "Allow edits from maintainers"，维护者会在合并前后补上。
   Can't run the script locally (e.g. web-editor-only contributions)? That's fine — note it in the PR description and enable "Allow edits from maintainers"; a maintainer will fill it in around merge time.
4. 之后 en 原文更新导致 `sourceHash` 不再匹配时，zh 页面会自动显示"译文可能已过期"提示，但页面仍正常展示，不影响访问。
   When the en source later changes and `sourceHash` no longer matches, the zh page automatically shows a "translation may be outdated" banner — the page still renders normally.

### 审核规则 / Review Rules

- 每个 PR 只改动一篇文档页面，便于审核；夹带的无关改动会被要求拆分。
  Each PR should touch exactly one documentation page to keep review focused; unrelated changes will be asked to be split out.
- 至少 1 位维护者 review 通过后才会合并，**不设自动合并**。
  At least one maintainer review is required before merge — **PRs are never auto-merged**.
- 中英文允许异步更新：zh 译文落后于 en 原文是正常状态（缺失译文会展示英文原文 + 未翻译提示，不会 404）。
  Chinese and English content may update asynchronously — it's normal for zh translations to lag behind en (a missing translation falls back to the English content with an "untranslated" banner instead of a 404).
- 首次贡献者触发的 Actions 工作流需要维护者手动批准后才会运行。
  Workflow runs triggered by first-time contributors require manual maintainer approval before they run.

提交 PR 时可选择 "docs" 模板（`.github/PULL_REQUEST_TEMPLATE/docs.md`），源码仓库地址：<https://github.com/zerx-lab/FluxDown>。
When opening a PR you can pick the "docs" template (`.github/PULL_REQUEST_TEMPLATE/docs.md`). Source repository: <https://github.com/zerx-lab/FluxDown>.