diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..6b31ada
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,31 @@
+## 概要
+
+<!-- 用 1-3 个要点说明本次 PR 做了什么 -->
+
+-
+
+## 变更文件
+
+| 文件 | 变更说明 |
+| ---- | -------- |
+|  |  |
+
+## 测试计划
+
+<!-- 每条对应一个可验证的场景，提交前自己打勾 -->
+
+- [ ]
+- [ ]
+
+## 关联 Issue
+
+<!-- 如有请填写，没有可删除本节 -->
+
+Closes #
+
+## Checklist
+
+- [ ] PR 标题遵循 Conventional Commits（`feat:`、`fix:`、`docs:` 等），且 type 选择正确
+- [ ] `./gradlew test` 本地通过
+- [ ] 涉及 webview：`cd webview && npm run build` 无报错
+- [ ] 无遗留 debug 日志和注释掉的代码
diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml
new file mode 100644
index 0000000..a947767
--- /dev/null
+++ b/.github/workflows/pr-title.yml
@@ -0,0 +1,15 @@
+name: PR Title Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+jobs:
+  validate-pr-title:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check PR title follows Conventional Commits
+        uses: ytanikin/pr-conventional-commits@1.4.0
+        with:
+          task_types: '["feat","fix","docs","test","ci","refactor","perf","chore"]'
+          add_label: 'false'
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..f511305
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,119 @@
+# Contributing to CodePlanGUI
+
+Thank you for your interest in contributing! Please read this guide before opening a PR or issue.
+
+---
+
+## Getting Started
+
+1. Fork the repository and clone your fork
+2. Create a branch from `master` with a descriptive name:
+   ```
+   feat/your-feature-name
+   fix/the-bug-description
+   ```
+3. Make your changes, then open a Pull Request
+
+### Build Requirements
+
+- IntelliJ IDEA 2023.1+
+- JDK 17 (Corretto 17 recommended — other versions may break the Kotlin compiler)
+- Node.js 18+ (for the webview frontend under `webview/`)
+
+### Build & Run
+
+```bash
+# Run plugin in a sandboxed IDE instance
+./gradlew runIde
+
+# Build the webview frontend
+cd webview && npm install && npm run build
+
+# Run all tests
+./gradlew test
+```
+
+---
+
+## Commit Message Convention
+
+This project follows [Conventional Commits](https://www.conventionalcommits.org/).
+
+```
+<type>(<scope>): <short description>
+```
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `refactor` | Code change that is not a fix or feature |
+| `test` | Adding or fixing tests |
+| `chore` | Build, CI, dependency updates |
+| `perf` | Performance improvement |
+| `ci` | CI/CD pipeline changes |
+
+**Scopes** (optional but encouraged): `execution`, `ui`, `webview`, `settings`, `chat`, `commit`
+
+**Examples:**
+```
+feat(execution): add cross-platform shell abstraction
+fix(ui): correct card collapse animation on resize
+docs: update setup instructions in README
+test(execution): add ShellPlatform unit tests for Windows
+```
+
+**Common mistake — wrong type:**
+
+`fix` means a bug fix only. If you add a new method, new UI, or new behavior, it's `feat` even if it's small. Using `fix` for a feature silently breaks automated changelog generation.
+
+```
+# Wrong — this adds new streaming behavior, not a bug fix
+fix: add async stream execution and log bridge
+
+# Correct
+feat(execution): add async stream execution with log bridge
+```
+
+**Breaking changes** — append `!` after the type and add a footer:
+```
+feat(settings)!: rename provider config fields
+
+BREAKING CHANGE: `apiUrl` is now `endpointUrl` in saved settings
+```
+
+---
+
+## Pull Request Guidelines
+
+Before opening a PR, run the pre-check script:
+
+```bash
+bash scripts/check-pr.sh
+```
+
+This runs Kotlin tests, webview build, and checks for debug logs. Fix any failures before submitting.
+
+- **One PR, one concern** — keep changes focused; unrelated fixes belong in separate PRs
+- **PR title must follow Conventional Commits** — the title becomes the squash commit message
+- **Fill in the PR template** — include a 变更文件 table and a 测试计划 checklist
+- **Link related issues** — use `Closes #123` in the PR description
+
+---
+
+## Code Style
+
+- Kotlin: follow [Kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html)
+- TypeScript (webview): `strict: true`, no `any` without a comment explaining why
+- No leftover debug logs or commented-out code in merged PRs
+
+---
+
+## Reporting Issues
+
+Please use the GitHub issue tracker. Include:
+- IDEA version and OS
+- Steps to reproduce
+- Expected vs actual behavior
+- Relevant log output (Help → Show Log in Explorer/Finder)
diff --git a/scripts/check-pr.sh b/scripts/check-pr.sh
new file mode 100755
index 0000000..eb3a4fb
--- /dev/null
+++ b/scripts/check-pr.sh
@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# Pre-PR check script — run this before opening a Pull Request
+# Usage: bash scripts/check-pr.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+
+ok()   { echo "  [PASS] $1"; PASS=$((PASS + 1)); }
+fail() { echo "  [FAIL] $1"; FAIL=$((FAIL + 1)); }
+info() { echo ""; echo "==> $1"; }
+
+# ── 1. Kotlin tests ──────────────────────────────────────────────────────────
+info "Running Kotlin tests (./gradlew test)..."
+if "$ROOT/gradlew" -p "$ROOT" test -q 2>&1; then
+  ok "Kotlin tests passed"
+else
+  fail "Kotlin tests FAILED — fix before opening PR"
+fi
+
+# ── 2. Webview build ─────────────────────────────────────────────────────────
+info "Building webview (npm run build)..."
+if [ -f "$ROOT/webview/package.json" ]; then
+  if (cd "$ROOT/webview" && npm run build --silent 2>&1); then
+    ok "Webview build passed"
+  else
+    fail "Webview build FAILED — fix before opening PR"
+  fi
+else
+  ok "No webview/package.json found — skipping webview build"
+fi
+
+# ── 3. Debug log check ───────────────────────────────────────────────────────
+info "Checking for leftover debug logs..."
+DEBUG_HITS=$(grep -rn \
+  --include="*.kt" --include="*.ts" --include="*.tsx" \
+  -e 'println(' -e 'System\.out\.print' -e 'console\.log(' \
+  "$ROOT/src" "$ROOT/webview/src" 2>/dev/null | \
+  grep -v '\.test\.' | grep -v 'spec\.' || true)
+
+if [ -z "$DEBUG_HITS" ]; then
+  ok "No leftover debug logs found"
+else
+  fail "Found possible debug logs — review before opening PR:"
+  echo "$DEBUG_HITS" | head -20 | sed 's/^/    /'
+fi
+
+# ── 4. PR title reminder ─────────────────────────────────────────────────────
+info "PR title reminder"
+echo "  Make sure your PR title follows Conventional Commits:"
+echo "    feat(<scope>): description"
+echo "    fix(<scope>): description"
+echo "    docs: description"
+echo ""
+echo "  Common mistake: using 'fix' for new features — use 'feat' instead."
+
+# ── Summary ──────────────────────────────────────────────────────────────────
+echo ""
+echo "────────────────────────────────────────"
+echo "  Results: ${PASS} passed, ${FAIL} failed"
+echo "────────────────────────────────────────"
+
+if [ "$FAIL" -gt 0 ]; then
+  echo "  Fix the failures above before opening your PR."
+  exit 1
+else
+  echo "  All checks passed. Ready to open PR!"
+  exit 0
+fi