diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..d8991d94
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for helping improve Claude Code Haha.
+
+For the full contributor guide, including local checks, live model baselines, quality-gate reports, and PR expectations, see:
+
+- Chinese: [docs/guide/contributing.md](docs/guide/contributing.md)
+- English: [docs/en/guide/contributing.md](docs/en/guide/contributing.md)
+
+Most contributors should run this before opening a PR:
+
+```bash
+bun install
+bun run quality:pr
+```
+
+If you run adapter or native checks on a fresh clone, install adapter dependencies too:
+
+```bash
+cd adapters
+bun install
+```
+
+If your change touches the desktop chat path, provider/runtime selection, CLI bridge, permissions, tools, file editing, or release packaging, also run a live baseline with your own local model provider:
+
+```bash
+bun run quality:providers
+bun run quality:gate --mode baseline --allow-live --provider-model <selector>:main
+```
+
+Quality reports are written under `artifacts/quality-runs/<timestamp>/`.
diff --git a/README.en.md b/README.en.md
index 21319330..48cc93ae 100644
--- a/README.en.md
+++ b/README.en.md
@@ -195,6 +195,7 @@ http://127.0.0.1:2024
 |------|------|
 | [Environment Variables](docs/en/guide/env-vars.md) | Full env var reference and configuration methods |
 | [Third-Party Models](docs/en/guide/third-party-models.md) | Using OpenAI / DeepSeek / Ollama and other non-Anthropic models |
+| [Contributing](docs/en/guide/contributing.md) | Local tests, live model baselines, PR gates, and release gates |
 | [Memory System](docs/memory/01-usage-guide.md) | Cross-session persistent memory usage and implementation |
 | [Multi-Agent System](docs/agent/01-usage-guide.md) | Agent orchestration, parallel tasks and Teams collaboration |
 | [Skills System](docs/skills/01-usage-guide.md) | Extensible capability plugins, custom workflows and conditional activation |
diff --git a/README.md b/README.md
index f136251a..a778d439 100644
--- a/README.md
+++ b/README.md
@@ -195,6 +195,7 @@ http://127.0.0.1:2024
 |------|------|
 | [环境变量](docs/guide/env-vars.md) | 完整环境变量参考和配置方式 |
 | [第三方模型](docs/guide/third-party-models.md) | 接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型 |
+| [贡献与质量门禁](docs/guide/contributing.md) | 本地测试、真实模型 baseline、PR 和 release 门禁 |
 | [记忆系统](docs/memory/01-usage-guide.md) | 跨会话持久化记忆的使用与实现 |
 | [多 Agent 系统](docs/agent/01-usage-guide.md) | 多代理编排、并行任务执行与 Teams 协作 |
 | [Skills 系统](docs/skills/01-usage-guide.md) | 可扩展能力插件、自定义工作流与条件激活 |
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index ca3639ff..66547160 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -24,6 +24,7 @@ const zhSidebar = [
       { text: '第三方模型', link: '/guide/third-party-models' },
       { text: '全局使用', link: '/guide/global-usage' },
       { text: '常见问题', link: '/guide/faq' },
+      { text: '贡献与质量门禁', link: '/guide/contributing' },
     ],
   },
   {
@@ -109,6 +110,7 @@ const enSidebar = [
       { text: 'Third-Party Models', link: '/en/guide/third-party-models' },
       { text: 'Global Usage', link: '/en/guide/global-usage' },
       { text: 'FAQ', link: '/en/guide/faq' },
+      { text: 'Contributing', link: '/en/guide/contributing' },
     ],
   },
   {
diff --git a/docs/en/guide/contributing.md b/docs/en/guide/contributing.md
new file mode 100644
index 00000000..4ef47fee
--- /dev/null
+++ b/docs/en/guide/contributing.md
@@ -0,0 +1,164 @@
+# Contributing and Local Quality Gates
+
+This guide explains how to install, develop, test, and run the local quality gates before opening a PR. The goal is to help maintainers and contributors answer one question before review: did this change break the core Coding Agent workflow?
+
+## Setup
+
+Install root dependencies with Bun:
+
+```bash
+bun install
+```
+
+If your change touches `desktop/`, also install desktop dependencies:
+
+```bash
+cd desktop
+bun install
+```
+
+If your change touches `adapters/`, or if you run `check:adapters` / `check:native`, install adapter dependencies:
+
+```bash
+cd adapters
+bun install
+```
+
+Do not commit local artifacts such as `artifacts/quality-runs/`, `node_modules/`, or `desktop/node_modules/`.
+
+## Required PR Gate
+
+Before opening a normal PR, run:
+
+```bash
+bun run quality:pr
+```
+
+This gate does not call real models, so every contributor can run it locally. It writes reports to:
+
+```text
+artifacts/quality-runs/<timestamp>/report.md
+artifacts/quality-runs/<timestamp>/report.json
+```
+
+Include the commands you ran and the report summary in your PR description.
+
+## Area-Specific Checks
+
+Run the checks that match the files you changed:
+
+```bash
+bun run check:server      # Server API, WebSocket, providers, sessions, and related tests
+bun run check:desktop     # Desktop lint, Vitest, and production build
+bun run check:adapters    # IM adapter tests
+bun run check:native      # Desktop sidecars and Tauri native checks
+bun run check:docs        # Docs build, using npm ci + docs:build
+```
+
+Focused tests are fine while developing, but run `bun run quality:pr` before sending the PR.
+
+## Live Model Baseline
+
+`quality:baseline` runs real Coding Agent tasks: it starts the local server, creates isolated fixtures, asks a model through chat to fix code, runs tests, and saves transcripts, diffs, verification logs, and a report.
+
+The default baseline command does not call real models:
+
+```bash
+bun run quality:baseline
+```
+
+To actually call models, pass `--allow-live` and choose a local provider.
+
+First list your local providers and copyable selectors:
+
+```bash
+bun run quality:providers
+```
+
+Example output:
+
+```text
+Saved providers:
+  MiniMax
+    selector: minimax
+    main: MiniMax-M2.7-highspeed
+      --provider-model minimax:main:minimax-main
+```
+
+Copy one of the listed values:
+
+```bash
+bun run quality:gate --mode baseline --allow-live --provider-model minimax:main:minimax-main
+```
+
+You can run multiple models in one pass:
+
+```bash
+bun run quality:gate --mode baseline --allow-live \
+  --provider-model codingplan:main:codingplan-main \
+  --provider-model minimax:main:minimax-main
+```
+
+Provider selectors come from the providers saved in your local Desktop Settings > Providers page. Contributors do not need the maintainer's provider UUIDs or vendor accounts. They can add their own provider locally, run `bun run quality:providers`, and choose their own model.
+
+## When To Run The Baseline
+
+Run the live baseline for changes touching:
+
+- Desktop chat, session resume, WebSocket, or the CLI bridge
+- Provider, model, or runtime selection
+- Permissions, tool calls, file edits, and task execution
+- agent-browser smoke, Computer Use, Skills, or MCP
+- Release preparation or broad cross-module refactors
+
+If you do not have model access, still run `bun run quality:pr` and state in the PR why the live baseline was not run.
+
+## Release Gate
+
+Before a release, run release mode:
+
+```bash
+bun run quality:gate --mode release --allow-live --provider-model <selector>:main
+```
+
+Release mode composes PR checks, baseline catalog validation, live baseline cases, desktop smoke, and native checks. Reports are written to `artifacts/quality-runs/<timestamp>/`.
+
+## PR Workflow
+
+1. Create a product branch such as `fix/session-reconnect` or `feat/provider-quality-gate`.
+2. Install dependencies and make the change.
+3. Add tests for behavior changes.
+4. Run focused checks for the affected area.
+5. Run `bun run quality:pr`.
+6. Run the live baseline for high-risk changes.
+7. In the PR description, include user impact, verification commands, report summary, and known risks.
+
+## FAQ
+
+### Can I run checks without a provider?
+
+Yes. Run the normal PR gate:
+
+```bash
+bun run quality:pr
+```
+
+Only the live baseline needs a real model. Add your provider in Desktop Settings > Providers, then run:
+
+```bash
+bun run quality:providers
+```
+
+### What if provider selectors conflict?
+
+If two provider names produce the same selector, `quality:providers` falls back to the provider ID. Copy the `--provider-model ...` value it prints.
+
+### What if a model ID contains a colon?
+
+Prefer role selectors:
+
+```bash
+--provider-model custom:haiku:custom-haiku
+```
+
+The runner resolves `haiku` to the real model ID from your local provider configuration.
diff --git a/docs/guide/contributing.md b/docs/guide/contributing.md
new file mode 100644
index 00000000..cd40ad2c
--- /dev/null
+++ b/docs/guide/contributing.md
@@ -0,0 +1,164 @@
+# 贡献指南与本地质量门禁
+
+这份文档说明贡献代码前应该如何在本地安装、开发、测试和运行质量门禁。目标是让维护者和贡献者都能在提交 PR 前回答一个问题：这次改动有没有破坏核心 Coding Agent 工作流。
+
+## 环境准备
+
+项目根目录使用 Bun：
+
+```bash
+bun install
+```
+
+如果改动涉及 `desktop/`，也安装桌面端依赖：
+
+```bash
+cd desktop
+bun install
+```
+
+如果改动涉及 `adapters/`，或者要运行 `check:adapters` / `check:native`，安装 adapter 依赖：
+
+```bash
+cd adapters
+bun install
+```
+
+不要提交本地运行产物，例如 `artifacts/quality-runs/`、`node_modules/`、`desktop/node_modules/`。
+
+## 普通 PR 必跑门禁
+
+普通贡献者在提交 PR 前至少运行：
+
+```bash
+bun run quality:pr
+```
+
+这个门禁不调用真实大模型，适合所有人本地运行。它会生成报告：
+
+```text
+artifacts/quality-runs/<timestamp>/report.md
+artifacts/quality-runs/<timestamp>/report.json
+```
+
+PR 描述里请贴出你实际运行的命令和 summary。
+
+## 按改动范围补充测试
+
+根据你改动的区域补充运行：
+
+```bash
+bun run check:server      # 服务端 API、WebSocket、provider、会话等测试
+bun run check:desktop     # 桌面端 lint、Vitest、生产构建
+bun run check:adapters    # IM adapter 测试
+bun run check:native      # 桌面 sidecar 与 Tauri native 检查
+bun run check:docs        # 文档构建，使用 npm ci + docs:build
+```
+
+如果只改了很窄的文件，也可以先跑对应的定向测试，但 PR 前仍应跑 `bun run quality:pr`。
+
+## 真实模型 Baseline
+
+`quality:baseline` 用来跑真实 Coding Agent 任务：启动本地服务端、创建隔离 fixture、让模型通过聊天修代码、跑测试，并保存 transcript、diff、verification log 和报告。
+
+默认命令不会调用真实模型：
+
+```bash
+bun run quality:baseline
+```
+
+要真正跑模型，必须显式加 `--allow-live` 并选择本机 provider。
+
+先列出本机可用 provider 和可复制参数：
+
+```bash
+bun run quality:providers
+```
+
+输出示例：
+
+```text
+Saved providers:
+  MiniMax
+    selector: minimax
+    main: MiniMax-M2.7-highspeed
+      --provider-model minimax:main:minimax-main
+```
+
+复制输出里的参数运行 baseline：
+
+```bash
+bun run quality:gate --mode baseline --allow-live --provider-model minimax:main:minimax-main
+```
+
+可以一次跑多个模型：
+
+```bash
+bun run quality:gate --mode baseline --allow-live \
+  --provider-model codingplan:main:codingplan-main \
+  --provider-model minimax:main:minimax-main
+```
+
+`provider` selector 来自桌面端「Settings > Providers」里保存的本机配置。别人 clone 代码后不需要知道你的 provider UUID，也不需要使用你的供应商；他们可以在自己的桌面端添加 provider 后运行 `bun run quality:providers` 选择自己的模型。
+
+## 什么时候必须跑 Baseline
+
+以下改动建议跑 live baseline：
+
+- 桌面聊天、会话恢复、WebSocket、CLI bridge
+- provider/model/runtime 选择
+- 权限、工具调用、文件编辑、任务执行
+- agent-browser smoke、Computer Use、Skills、MCP
+- release 前或风险较大的跨模块重构
+
+如果没有模型额度，至少运行 `bun run quality:pr`，并在 PR 里说明未跑 live baseline 的原因。
+
+## Release 门禁
+
+发版前使用 release 模式：
+
+```bash
+bun run quality:gate --mode release --allow-live --provider-model <selector>:main
+```
+
+release 模式会组合 PR checks、baseline catalog、live baseline、desktop smoke 和 native checks。发版报告同样写入 `artifacts/quality-runs/<timestamp>/`。
+
+## PR 提交流程
+
+1. 新建普通产品分支，例如 `fix/session-reconnect` 或 `feat/provider-quality-gate`。
+2. 安装依赖并完成改动。
+3. 为行为变化补测试。
+4. 运行相关定向测试。
+5. 运行 `bun run quality:pr`。
+6. 对高风险改动运行 live baseline。
+7. 在 PR 描述里写清楚用户影响、测试命令、报告 summary、已知风险。
+
+## 常见问题
+
+### 没有 provider 可以跑吗？
+
+可以跑普通门禁：
+
+```bash
+bun run quality:pr
+```
+
+只有 live baseline 需要真实模型。先在桌面端 Settings > Providers 添加自己的 provider，再运行：
+
+```bash
+bun run quality:providers
+```
+
+### provider selector 冲突怎么办？
+
+如果两个 provider 名称生成了相同 selector，`quality:providers` 会退回输出 provider ID。直接复制它给出的 `--provider-model ...` 即可。
+
+### 模型 ID 里带冒号怎么办？
+
+优先使用角色选择，例如：
+
+```bash
+--provider-model custom:haiku:custom-haiku
+```
+
+脚本会把 `haiku` 解析成本机 provider 配置里的真实模型 ID。