diff --git a/.editorconfig b/.editorconfig
index 3026ff88..c3bba3c4 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -27,6 +27,15 @@ indent_size = 2
 indent_style = space
 indent_size = 4
 
+# Go 由 gofmt 统一格式化：缩进恒用 tab（非空格），此处仅约定 tab 的显示宽度为 4。
+[*.go]
+indent_style = tab
+tab_width = 4
+
+[go.mod]
+indent_style = tab
+tab_width = 4
+
 [{Makefile,makefile,GNUmakefile,*.mk}]
 indent_style = tab
 tab_width = 4
diff --git a/.github/workflows/ci-cli.yml b/.github/workflows/ci-cli.yml
new file mode 100644
index 00000000..2e03888d
--- /dev/null
+++ b/.github/workflows/ci-cli.yml
@@ -0,0 +1,46 @@
+name: CLI
+
+# meebox CLI（cli/，独立 Go module）的门禁，与 Node/Nx 的 CI 分开：
+# 路径过滤只能加在 workflow 的 on 层（不能按 job 过滤），故独立成一条流水线——仅当 cli/ 变更时才跑，
+# 既隔离 Go 工具链、又省 CI 分钟。发布期的交叉编译 / 出包见 release.yml 的 cli job。
+on:
+  push:
+    branches: [master]
+    paths:
+      - 'cli/**'
+      - '.github/workflows/ci-cli.yml'
+  pull_request:
+    paths:
+      - 'cli/**'
+      - '.github/workflows/ci-cli.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  cli:
+    name: Vet + Test + Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: cli
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: cli/go.mod
+          cache-dependency-path: cli/go.sum
+
+      - name: go vet
+        run: go vet ./...
+
+      - name: go test
+        run: go test ./...
+
+      - name: go build
+        run: go build ./...
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 0529500b..b708155a 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -27,7 +27,7 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  build:
+  gui:
     strategy:
       fail-fast: false
       matrix:
@@ -137,3 +137,72 @@ jobs:
           make_latest: ${{ !contains(github.ref_name, '-') }}
           # 正文 = RELEASE_NOTES（安装 / 首次打开 / 校验和）+ 注入的本版 CHANGELOG 段
           body_path: RELEASE_BODY.md
+
+  # meebox CLI（cli/，独立 Go module）：纯 Go、无 CGO → 单 runner 交叉编译全平台。出四平台压缩包 +
+  # 校验和，随桌面安装包挂到同一个 GitHub Release（不打进安装包，是独立可分发物）。仅 tag 触发上传；
+  # workflow_dispatch 仍构建做编译冒烟、不上传。本 job 不设 Release 正文（由 build job 注入），仅追加产物。
+  cli:
+    name: CLI (${{ matrix.goos }}/${{ matrix.goarch }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { goos: windows, goarch: amd64, ext: '.exe', archive: zip }
+          - { goos: darwin, goarch: arm64, ext: '', archive: zip }
+          - { goos: linux, goarch: amd64, ext: '', archive: tar.gz }
+          - { goos: linux, goarch: arm64, ext: '', archive: tar.gz }
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: cli/go.mod
+          cache-dependency-path: cli/go.sum
+
+      - name: 交叉编译 meebox CLI
+        shell: bash
+        working-directory: cli
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: '0'
+        run: |
+          # 版本与 app 同源：取自 apps/desktop/package.json（app 运行期版本的唯一真相源），
+          # 而非独立依赖 git tag——发布前置已校验 tag == 该版本，故二者一致但只有一个来源。
+          VERSION="$(node -p "require('$GITHUB_WORKSPACE/apps/desktop/package.json').version")"
+          mkdir -p dist
+          go build -trimpath \
+            -ldflags "-s -w -X github.com/huhamhire/code-meeseeks/cli/cmd.version=${VERSION}" \
+            -o "dist/meebox${{ matrix.ext }}" .
+
+      - name: 打包压缩包 + 校验和
+        if: startsWith(github.ref, 'refs/tags/')
+        shell: bash
+        working-directory: cli/dist
+        run: |
+          VERSION="$(node -p "require('$GITHUB_WORKSPACE/apps/desktop/package.json').version")"  # 与 app 同源
+          BIN="meebox${{ matrix.ext }}"
+          ARCHIVE="meebox-cli-${VERSION}-${{ matrix.goos }}-${{ matrix.goarch }}"
+          # Bundle LICENSE + README + SKILL.md so the archive is a drop-in agent skill
+          # directory (unzip into a skills dir → SKILL.md beside the binary it drives).
+          cp ../../LICENSE ../README.md ../SKILL.md .
+          FILES=("${BIN}" LICENSE README.md SKILL.md)
+          if [ "${{ matrix.archive }}" = "zip" ]; then
+            zip -q "${ARCHIVE}.zip" "${FILES[@]}"
+          else
+            tar -czf "${ARCHIVE}.tar.gz" "${FILES[@]}"
+          fi
+          for f in "${ARCHIVE}".zip "${ARCHIVE}".tar.gz; do
+            [ -e "$f" ] && sha256sum "$f" > "$f.sha256"
+          done
+
+      - name: 上传到 Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v2
+        with:
+          # 本 matrix 项仅产出自身的压缩包 + .sha256（fresh runner）；不设 body_path 以免覆盖 build job 注入的正文
+          files: cli/dist/meebox-cli-*
+          fail_on_unmatched_files: true
+          prerelease: ${{ contains(github.ref_name, '-') }}
+          make_latest: ${{ !contains(github.ref_name, '-') }}
diff --git a/AGENTS.md b/AGENTS.md
index db4339ea..12f6e5d4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,25 +4,26 @@
 
 ## 仓库结构
 
-Electron 桌面应用 + npm workspaces + Nx 单仓多包。关键路径（`apps/desktop` 是主战场）：
+Electron 桌面应用（npm workspaces + Nx 单仓多包）外加一个独立 Go CLI 子工程。关键路径（`apps/desktop` 是主战场）：
 
 ```
-apps/desktop/
+apps/desktop/              # Electron 应用（唯一有 build/dist 的项目）
 ├── src/
-│   ├── main/              # 主进程：index.ts(启动/单例锁) · ipc.ts(IPC handlers) · adapters.ts · utils/
+│   ├── main/              # 主进程：业务与 IO 唯一所在（启动/单例锁 · IPC handlers · 平台适配 · 服务层：pr · agent 编排 · 本地 API）
 │   ├── preload/           # contextBridge 暴露泛型 invoke()
-│   └── renderer/src/      # React 渲染层（components/ 等）
-├── scripts/               # assemble-pragent-runtime.mjs · pragent-shim/(shim) · pragent-runtime.json
-├── build-resources/       # after-pack.cjs(ad-hoc 签名) · entitlements.mac.plist
-├── electron-builder.yml
-└── vendor/pragent/        # 嵌入式运行时（gitignored，由 prepare:pragent 生成）
+│   └── renderer/src/      # React 渲染层（UI / 交互）
+├── scripts/               # 嵌入式 pr-agent 运行时组装 + monkeypatch shim
+├── build-resources/       # electron-builder 打包资源（签名钩子 · entitlements）
+└── vendor/pragent/        # 嵌入式运行时（gitignored，prepare:pragent 生成）
 
-packages/<name>/src/index.ts  # 各库入口；shared 还含 ipc.ts(IPC 契约) · config.ts · poller-contract.ts
+packages/<name>/           # 内部库 @meebox/*（各 src/index.ts 为入口）；shared 含共享类型 + IPC 契约
+cli/                       # 独立 Go module：跨平台 CLI meebox（命令树 + HTTP client；经本地 API 集成，不入 npm/Nx）
 ```
 
 - `apps/desktop` —— Electron 应用（main + preload + renderer/React）。唯一有 `build`/`dist` 的项目。
 - `packages/*` —— 内部库（`@meebox/*`），按职责拆分；其中 `shared` 含共享类型与 IPC 契约。
-- `docs/arch/` 各模块设计文档（首选入口）；`docs/ROADMAP.md` 路线图；`tools/` 杂项脚本。
+- `cli/` —— 独立分发的 Go 命令行工具 `meebox`（外部集成用，不属 npm/Nx；详见下「CLI 工程（cli/）」段）。
+- `docs/arch/` 各模块设计文档（首选入口）；`docs/guide/` 使用说明；`docs/ROADMAP.md` 路线图；`tools/` 杂项脚本。
 
 **命名约定**：代码内部统一用中性代号 `meebox`（npm 作用域 `@meebox/*`）；对外品牌名 `Code Meeseeks`；用户数据目录 `~/.code-meeseeks/`。`pr-agent` 为第三方依赖，不在重命名范围内。
 
@@ -67,17 +68,22 @@ npm --prefix apps/desktop run prepare:pragent    # 对齐嵌入式 pr-agent 运
 
 ## 发布流程
 
-发版从 `dev` 汇入 `master` 后，在 `master` 打 `v*` tag 触发 [release.yml](.github/workflows/release.yml)（出 Windows / macOS 安装包 + GitHub Release）。**打 tag 前必须在同一批改动里完成三步前置，且随发版改动一并经 `dev` → `master`**——漏任一步 CI 不报错（仅 `::warning::`）但会产出错误的 Release：
+发版：`dev` 汇入 `master` → 在 `master` 打 `v*` tag 触发 [release.yml](.github/workflows/release.yml)（出 Windows / macOS 安装包 + CLI 二进制 + GitHub Release）。
 
-1. **版本号** —— 把 [apps/desktop/package.json](apps/desktop/package.json) 的 `version` 改成目标版本（去 `v` 前缀，预发布带后缀，如 `0.5.0-alpha.1`）。electron-builder 的 `artifactName: code-meeseeks-${version}-...` 直接取此值——不改则安装包文件名缺 `-alpha.N`、与 tag 不符。改完跑一次 `npm install` 同步 lockfile。
-2. **CHANGELOG** —— 把 [CHANGELOG.md](CHANGELOG.md) 的 `## [Unreleased]` 改名为 `## [<版本>] - <YYYY-MM-DD>`，并在文件底部补 `[<版本>]: …/compare/…` 链接引用（仿现有行）。**发布即移除 Unreleased、不再另起空段**——`## [Unreleased]` 仅**开发期**存在以累积变更，发布时被改名消费掉；下一笔开发期 changelog 改动时再新建一个 `## [Unreleased]`（见「版本号规则」的 `-dev` 开发态）。release.yml 按 `## [<版本>]` 字面抽段注入 Release 正文的「版本变更」区——缺这段则正文回退、无任何变更说明。**若本次是正式版（无 `-` 后缀）、且其内容来自此前的 alpha/预发布**：此时开发期通常无独立 Unreleased（内容已在预发布段），直接把该预发布段改名为正式版段、删去对应的 `[<x>-alpha.N]:` 链接引用即可（内容并入正式版段，不再保留空壳 stub）；尚无对应正式版的其它预发布段保留。
-3. **校对** —— 确认 `## [<版本>]` 段已覆盖自上版本以来合入 `dev` 的全部要点（新增 / 变更 / 修复）。
+⚠️ **打 tag 前必须在同一批改动里完成三步前置（版本号 / CHANGELOG / 校对），随发版一并经 `dev` → `master`**——漏任一步 CI 不报错（仅 `::warning::`）但会产出错误的 Release。**完整前置清单、`-dev` 版本号规则、CHANGELOG 撰写风格见 [打包与发布](docs/development/packaging-release.md)**。tag 名须等于 package.json 版本（`v<版本>`）；名含 `-` 的预发布 tag 自动标 prerelease、不抢占 Latest。
 
-tag 名与 package.json 版本必须一致（`v<版本>`）。预发布 tag（名含 `-`，如 `-alpha.N`）由 release.yml 自动标 prerelease 且不抢占 Latest。
+## CLI 工程（cli/）
 
-**版本号规则**：每次正式发版后，`dev` 立即把 [apps/desktop/package.json](apps/desktop/package.json) 切到**下一版的 `-dev` 预发布号**（如发完 `0.6.0` 即切 `0.7.0-dev`，并 `npm install` 同步 lockfile），标记开发态、与正式版区分。`-dev` 仅作开发标记——**不打 tag、不发版**；发版时按上面三步前置把它改成目标号（预发布 `0.7.0-alpha.N` 或正式 `0.7.0`）。`-dev` 是合法 semver（`0.6.0` < `0.7.0-dev` < `0.7.0`），不影响更新检测（[update-check.ts](apps/desktop/src/main/utils/update-check.ts) 用 `semver.gt` 比对、不用 range，故无「预发布不满足范围」陷阱）与构建。
+`cli/` 是独立分发的跨平台命令行客户端 `meebox`（供外部 agent / 脚本经[本地 API 服务](docs/arch/04-integration/01-service-api.md)集成）。设计见 [docs/arch/04-integration/02-cli.md](docs/arch/04-integration/02-cli.md)，用法见 [docs/guide/06-cli.md](docs/guide/06-cli.md)。
 
-**CHANGELOG 撰写风格**（面向用户、求简）：① 版本引言 `>` 区直接进入「本版重点」、要点用**无序列表**排版，不堆成长句，**不写「首个 / 第 N 个正式版」之类的版本序数引言**；② 新增 按**功能场景**分类、用缩进的二级列表表达，每个小点一句话点到即止；③ 重构类任务**前后端合并**为一条总结、不展开实现细节；④ 修复 **不写「怎么修的」机制**，每条一句话只述修复的现象/影响；⑤ 通篇不写 IPC 通道名、函数名、文件路径、字段名等实现细节，优先突出新增特性与改良；⑥ **安装 / 升级注意事项**（版本引言里的 ⚠️ 警示，如先卸载旧版、per-machine 提权等）属安全关键信息，**保留完整、不参与精简**——这些会随 release.yml 注入 GitHub Release 正文，删减会让用户漏看升级风险；⑦ **分段标题用中文 + emoji**：`### ✨ 新增 / ♻️ 变更 / 🔧 修复 / 🗑️ 移除 / 🔒 安全`（对应 Keep a Changelog 的 Added / Changed / Deprecated / Removed / Fixed / Security）。外部贡献者的 PR 习惯性致谢（仿 `(#65，感谢 @user)`）。
+- **独立 Go module，不入 npm/Nx**：自带 `cli/go.mod`（纯 Go、无 CGO），非 workspace 成员、不进 Nx——根 `lint/typecheck/test/build` 不覆盖它，CLI 自成一套。
+- **本地命令**（在 `cli/`）：`go vet ./...` → `go test ./...` → `go build ./...`，改完 CLI 三步过了再收尾。`go.sum` 入库（锁校验和）；构建产物（`bin/` / `meebox` 等）已 gitignore（见 `cli/.gitignore`）。
+- **CI 分两条**：PR 门禁 [ci-cli.yml](.github/workflows/ci-cli.yml)（路径过滤 `cli/**`，跑 vet/test/build，与 Node 的 ci.yml 分开）；发布产出在 [release.yml](.github/workflows/release.yml) 的 `cli` job（`v*` tag 触发，交叉编译 Windows / macOS / Linux×2，出压缩包挂同一 Release；Windows / macOS 用 `.zip`、Linux 用 `.tar.gz`）。版本**取自 `apps/desktop/package.json`（与 app 同源，即 app 运行期版本的唯一真相源）**经 `-ldflags -X …/cmd.version` 注入——不独立依赖 git tag（发布前置已校验 tag == 该版本）。
+- **压缩包即 skill 目录**：CLI 压缩包除二进制外一并打包 `LICENSE` + `cli/README.md` + `cli/SKILL.md`（frontmatter `name: meebox`）——解压投放到 agent 的 skills 目录即得可用 skill（面向 agent 交付的主形态）。
+- **写边界**：CLI 做浏览 + **评审写动作**——approve / needswork（远端评审决断）与 comment（发评论），经服务端专用端点（复用 GUI 同源 controller）。仍**不开放**：merge（合并）与 pr-agent 变更类工具（publish 等，`instruct` 只读白名单 describe/review/ask/improve 在 CLI 与服务端双重把关）。新增命令先确认对应 API 端点已存在；放开新写端点须评估远端副作用。CLI 不得绕过 API 直连应用内部。
+- **契约同步**：CLI 与服务端唯一耦合是 HTTP/JSON 线协议。当前手写 Go 结构对齐契约，契约增长后转 OpenAPI / Schema 代码生成。默认输出 YAML（人类向、保序）、`--output json` 供机器（亦保序）；PR 列表返回精简投影、PR 标识对外为 `id`、PR 关联命令用 `--pr <id>`。连接配置走 flag / 环境变量（`MEEBOX_API_URL` / `MEEBOX_TOKEN`）/ `~/.code-meeseeks/cli.yaml`，**不读 GUI 的 `config.yaml`**（避免越权触达连接层机密）；代理遵循标准 `HTTP(S)_PROXY` / `NO_PROXY`。
+- **领域归类**：CLI / API / GUI 都是同一 service 层之上的薄前端，命令树与端点应**镜像业务领域**。新增 CLI 命令 / API 端点按语义归位——PR 相关入 `pr`、评审 Agent 入 `agent`；与具体 PR / Agent 无关的**系统性 / 会话级**操作（whoami / version 等）置于**根层级**，不套领域组。归属看**语义而非是否 PR 维度**（如 `categories` / `refresh` 无 `--pr` 仍属 `pr`——它们服务于 PR 列表）。完整理由见 [CLI 设计](docs/arch/04-integration/02-cli.md)。
+- **文档对齐**：CLI 改动（命令树 / 写边界 / 输出契约 / 连接配置）须同步三类文档，缺一即漂移——① **arch 设计**：[docs/arch/04-integration/02-cli.md](docs/arch/04-integration/02-cli.md)（命令树与边界），涉及 API 端点再改 [01-service-api.md](docs/arch/04-integration/01-service-api.md)（端点表）；② **guide 用法**：[docs/guide/06-cli.md](docs/guide/06-cli.md)；③ **skill 交付**：`cli/SKILL.md` + `cli/README.md`（随压缩包投放为 agent skill 的主形态）。新增 / 改命令务必三类齐更。
 
 ## 约定
 
@@ -96,7 +102,11 @@ tag 名与 package.json 版本必须一致（`v<版本>`）。预发布 tag（
 
 ## 国际化 (i18n)
 
-GUI 文本走 **react-i18next**（key 为中立标识符，`zh-CN` / `en-US` / `ja-JP` / `de-DE` 为**对等译文集**，无源/译层级；UI 语言由 `config.language` 经 `resolveLanguage` 决定，空则按 OS 回落英语）。**默认 / 兜底语言取 `en-US`**（国际化标准：缺 key 回退英文而非中文）：渲染层 en-US 静态打包进入口 + 其余懒加载、`fallbackLng: 'en-US'`，主进程各持一份 locale、同样兜底 en-US。设计、key 命名、翻译规范见 [docs/arch/03-gui/04-i18n](docs/arch/03-gui/04-i18n.md)。三条易踩的：①新增文本须在**各语言 locale 都加**并保持**递归字典序**（日语复数同中文仅 `_other`、德语同英语需 `_one`/`_other`）；②i18next **只有 `count`** 触发复数，普通计数插值要换别的变量名；③**不要开 `nonExplicitSupportedLngs`**——它把 `zh-CN` 按基码 `zh` 查找、与按 `zh-CN` 注册的 bundle 错位 → 整页裸 key。
+GUI 文本走 **react-i18next**（key 为中立标识符，`zh-CN` / `en-US` / `ja-JP` / `de-DE` 为**对等译文集**；**默认 / 兜底 `en-US`**，缺 key 回退英文）。设计、key 命名、翻译规范见 [docs/arch/03-gui/04-i18n](docs/arch/03-gui/04-i18n.md)。三条易踩（详见该篇）：
+
+1. 新增文本各语言 locale 都加且保持**递归字典序**；
+2. 复数只认 `count`（普通计数插值换别名）；
+3. 勿开 `nonExplicitSupportedLngs`（按基码 `zh` 错位 → 整页裸 key）。
 
 ## 文档约定
 
@@ -107,14 +117,12 @@ GUI 文本走 **react-i18next**（key 为中立标识符，`zh-CN` / `en-US` / `
 
 ## 工程维护坑
 
-- **新增内部 `@meebox/*` 包必做两步登记**（漏则报 `Cannot find module …/src/<x>.js`）：内部包源码是 `.ts`、相对 import 带 `.js` 扩展（NodeNext 约定），Node 运行期不能直接读。新建一个被 desktop 主/preload 引用的内部包后，除 `npm install`（建 workspace 软链）外，**必须**：① 在 `apps/desktop/package.json` 依赖加 `"@meebox/<name>": "*"`；② 在 [apps/desktop/electron.vite.config.ts](apps/desktop/electron.vite.config.ts) 的 `internalPackages` 数组加该名——让 electron-vite 把它 **bundle**（转译 TS、解析 `.js`→`.ts`）而非 externalize。漏 ② 时 Node 把它当外部包按 `main: src/index.ts` 加载，撞到 `export … from './x.js'` 而文件是 `.ts` → 运行期崩。
-- **嵌入式 pr-agent 运行时**（见 [docs/arch/02-agent/03-pragent-runtime](docs/arch/02-agent/05-pragent-runtime.md)）：`apps/desktop/scripts/assemble-pragent-runtime.mjs` 按 `pragent-runtime.json` 把可重定位 CPython + pinned pr-agent 装到 `apps/desktop/vendor/pragent/`（gitignored）。
-- **monkeypatch shim** `apps/desktop/scripts/pragent-shim/`（薄加载器 `sitecustomize.py` + 领域拆分包 `meebox_pragent_shim/`：`patches/` 各 patch + `cli/` 本地 CLI provider + `runtime.py`/`usage.py`。对 pr-agent 的无侵入补丁）：
-  - 改了它，跑一次 `npm --prefix apps/desktop run prepare:pragent` 即重新同步进 vendor（幂等跳过分支也会同步 shim），**无需 `--force` 全量重建**。
-  - 受版本守卫：`meebox_pragent_shim/runtime.py` 的 `_EXPECTED_PRAGENT_VERSION` 必须等于 `pragent-runtime.json` 的 `prAgent.version`（assemble 构建期强校验，运行期不符则跳过补丁 + stderr WARNING）。升级 pr-agent 要同步两处并重新验证。
-  - **拆分铁律**：各 patch 对 `pr_agent` 的 import 一律放在 patch 函数体内（惰性）；模块顶层只 import 同包内的 runtime/usage 等，**绝不在顶层 import pr_agent**（否则 sitecustomize 阶段即 eager 加载，拖慢每次 python 启动）。
-  - 调试：`MEEBOX_SHIM_DEBUG=1` 让 shim 打 stderr 调试。
+- **新增内部 `@meebox/*` 包必做两步登记**（漏则报 `Cannot find module …/src/<x>.js`）：内部包源码是 `.ts`、相对 import 带 `.js` 扩展（NodeNext 约定），Node 运行期不能直接读。新建一个被 desktop 主/preload 引用的内部包后，除 `npm install`（建 workspace 软链）外**必须**：
+  1. 在 `apps/desktop/package.json` 依赖加 `"@meebox/<name>": "*"`；
+  2. 在 [apps/desktop/electron.vite.config.ts](apps/desktop/electron.vite.config.ts) 的 `internalPackages` 数组加该名——让 electron-vite 把它 **bundle**（转译 TS、解析 `.js`→`.ts`）而非 externalize。
+
+  漏第 2 步时 Node 把它当外部包按 `main: src/index.ts` 加载，撞到 `export … from './x.js'` 而文件是 `.ts` → 运行期崩。
+- **pr-agent 运行时 / shim**：嵌入式 CPython + pinned pr-agent 由 `assemble-pragent-runtime.mjs` 装到 `vendor/pragent`（gitignored）；对 pr-agent 的无侵入补丁在 `scripts/pragent-shim/`。机制与铁律（惰性 import 拆分 · 版本守卫 · 改后跑 `prepare:pragent` 同步 · 调试 `MEEBOX_SHIM_DEBUG=1`）见 [02-agent/05-pragent-runtime](docs/arch/02-agent/05-pragent-runtime.md)。弱网 pip 超时加 `PIP_DEFAULT_TIMEOUT=120`。
 - **二进制资源走 Git LFS**（`*.png/.ico/.icns` 等）：本地没装 git-lfs 时拿到的是指针文件，electron-builder 转图标会崩 → `brew install git-lfs && git lfs pull`。
 - **dev 起不来**：若 `npm run dev` 报 `electron does not provide an export named …`，是环境里有 `ELECTRON_RUN_AS_NODE=1`（VSCode 扩展宿主会注入）→ `unset ELECTRON_RUN_AS_NODE` 再跑。
 - **grep 个别文件无输出**：如 `repo-mirror-manager.ts` 被 `file` 判为 `data`（含非 UTF-8 字节），普通 grep 静默 → 用 `grep -a`。
-- **prepare:pragent 网络**：pip 默认 15s 超时，弱网下加 `PIP_DEFAULT_TIMEOUT=120` 或配国内镜像（`~/.config/pip/pip.conf`）。
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e9fac538..250ad45b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,38 @@
 本项目所有重要变更记录于此。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.9.0-alpha.1] - 2026-07-02
+
+> 本版重点：
+>
+> - **外部集成与 CLI**：开启本机 API 把 PR 浏览与评审 Agent 操作开放给外部集成，并提供跨平台命令行工具 `meebox`
+
+### ✨ 新增
+
+- **外部集成 · 本地 API 服务**：设置新增「集成」分区，可开启一个本机 API 服务，将 PR 浏览与评审 Agent 操作以接口形式开放给外部 agent / 工具 / 脚本集成。
+  - 默认关闭；开启即强制访问令牌鉴权，令牌可一键生成 / 显示 / 复制 / 重新生成。
+  - 监听地址可自定义：默认仅本机可达，按需可开放到局域网（开放时给出安全提示）。
+  - 开放浏览（当前身份 / PR 列表 / 详情 / diff / 动态 / 提交 / 评审人）、评审 Agent（状态 / 历史 / 自动评审 / 指令 / 对话 / 中断）与评审写动作（通过 / 需修改 / 发评论）；不开放合并与变更类 Agent 工具（publish 等）。
+- **外部集成 · 命令行工具 `meebox`**：随发布提供 Windows / macOS / Linux 跨平台命令行客户端，经本地 API 服务浏览 PR、操作评审 Agent 并执行评审写动作（approve / needswork / comment），便于脚本与外部 agent 集成。PR 列表精简且支持分页；PR 关联命令用 `--pr <id>`；连接信息须显式提供（flag / 环境变量 / cli.yaml），不读 GUI 主配置。
+- **PR 列表发现分类未读圆点**：某发现分类（待我评审 / 我创建 等）下有新的待处理 PR 时，在该分类标签后加未读圆点，一眼看出哪类有新进展；圆点始终基于活跃 PR，即便当前处于「已关闭」视图也正确反映活跃分类的未读。
+- **「我创建的」PR 通知**：针对本人创建的 PR 新增三类系统通知——收到他人新评论、被评审标记「需修改」、出现合并冲突；通知分区提供独立开关、默认开启。
+- **命令回显气泡**：在评审 Agent 面板直接发起 `/review`、`/describe`、`/improve`、`/ask` 等命令时，命令即时以用户气泡回显在其结果卡片之上，贴合对话习惯；编排 / AutoPilot 派发的子任务不回显，避免与编排会话的用户消息重复。
+- **按提交发起评审 Agent**：在 Diff 视图将变更范围切到某个提交后，评审 Agent 面板直接键入的 `/describe`、`/review`、`/improve`、`/ask`（含自然语言提问）会自动限定在该提交自身改动（`parent..sha`）而非 PR 全量；输入栏以范围 chip 标示当前提交，chip 选中态源自视图选择，点击可临时禁用（不删除、切到别的提交自动复位），与 Diff 选区 chip 交互一致。同一时刻仅一个 scope 生效：选中 Diff 行时以选区为准、暂挂提交范围，取消选区后自动还原。运行中与完成的评审结果卡均展示所限定提交的范围徽标。一键自动评审仍作用于 PR 全量。
+
+### ♻️ 变更
+
+- 评审 Agent 的 `/ask`（本机 agentic CLI 提供方）注入代码检索指引：引导以只读搜索定向查符号 / 只读所需行段替代整文件通读与全仓扫描，在保留读真实文件深度的同时，降低探索轮次与 token 消耗。
+- 「追问数量」上限现同时约束自由对话 Agent（会话即委派）的自动 `/ask`：此前该上限仅作用于评审微流程的条件追问，自由规划循环仅受「Agent 最大步数」约束、可连续多次 `/ask`（每次均为一次成本较高的 agentic 探索）；现自由对话中的 `/ask` 亦按「追问数量」封顶（始终生效，与「自动追问」开关无关），避免探索成本失控。
+- 状态栏不再常态显示 pr-agent 版本号（减少常态噪声），仅在其不可用时保留告警提示；版本号改在设置「关于」页的运行环境信息中展示。
+- 「我创建的」分类下的「待处理」筛选并入存在合并冲突的 PR：作者视角下有冲突的 PR 需其跟进解决（即便评审已通过），故一并计入待处理。
+- PR 列表的状态二级筛选改为宽度自适应胶囊：一行容得下即不换行，容纳不下时换行并按每行项数均分撑满整行，消除换行后右侧留白参差。
+- 评审 Agent 派生的临时工作树内部分支不再使用固定的品牌化名称，改为与 PR 关联的 `pr-<localId>/head`、`pr-<localId>/base`（分层命名贴合平台 PR 引用惯例）：消除产出中可辨识的固定行为特征，同时保证该内部分支名不会漏入对外发布的评审内容。
+
+### 🔧 修复
+
+- 修复 PR 列表分组标题背景色、Windows 窗口右上角控制按钮此前不随主题（编辑器配色主题）变化的问题；现二者均跟随当前主题派生配色，深浅 / 主题切换实时生效。
+- 修复点开带「@我 / 回复我」未读计数的 PR 后，标题处的未读计数 chip 不立即消除、需等下一轮轮询才清零的问题：标为已读时同步乐观清零该计数（此前仅清未读圆点，遗漏了计数 chip）。
+
 ## [0.8.0] - 2026-06-30
 
 > 本版重点：
@@ -371,6 +403,7 @@
 
 许可证：[Apache-2.0](LICENSE)。打包内含第三方组件（pr-agent、Electron 等），各按其许可证分发，见 [NOTICE](NOTICE)。
 
+[0.9.0-alpha.1]: https://github.com/huhamhire/code-meeseeks/compare/v0.8.0...v0.9.0-alpha.1
 [0.8.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/huhamhire/code-meeseeks/compare/v0.5.0...v0.6.0
diff --git a/README.md b/README.md
index e364c86a..d878cffd 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,13 @@ Code Meeseeks（内部开发代号 `meebox`）是命令行工具 [pr-agent](http
 
 - **多 LLM Provider** —— OpenAI / openai-compatible / DeepSeek / Anthropic / 通义千问 / 火山方舟等（本地 Ollama 经 openai-compatible 的 `/v1` 接入）；也可通过本机已授权的本地 CLI 工具（如 claude / codex）调用第三方模型。
 - **个性化规则** —— 每位 Reviewer 维护自己的规则目录（markdown + frontmatter，支持子目录递归组织），按项目 / 仓库 / 目标分支命中；命中的多条规则按 Ruleset 分段一并注入评审，`priority` 控制排序。
-- **运行参数可调** —— 评审任务并发、输入上下文长度、Agent 策略（自动追问开关、代码建议数量）均可在设置页调整。
+- **运行参数可调** —— 评审任务并发、输入上下文长度、Agent 策略（自动追问开关、追问 / 代码建议数量）均可在设置页调整。
+
+#### 🔌 外部集成与 CLI
+
+- **可供外部 Agent 集成** —— PR 评审能力经本机 HTTP 接口 + 跨平台 CLI 对外开放，让本机 agentic 工具（如 claude / codex）、脚本、CI 把 PR 发现 / 浏览 / 评审 Agent 操作纳入自动化流程。
+- **本地 API 服务** —— 可选开启一个本机 API，将 PR 发现 / 浏览 / diff / 评审 Agent 操作 / 评审写动作以语言无关的 HTTP 契约开放出来；默认仅本机可达、强制访问令牌鉴权，不开放合并与变更类工具。
+- **跨平台命令行工具 `meebox`** —— 随发布提供 Windows / macOS / Linux 客户端，经本地 API 浏览 PR、驱动评审 Agent 并执行评审写动作（approve / needswork / comment）；`meebox login` 一次存好凭据即可免传参，**压缩包即 agent skill 目录、可直接投放到 agent 的 skills 目录**。用法见 **[CLI 命令行工具](docs/guide/06-cli.md)**。
 
 #### 🎨 界面与体验
 
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 976d3a59..8158b1d2 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@meebox/desktop",
-  "version": "0.8.0",
+  "version": "0.9.0-alpha.1",
   "private": true,
   "description": "meebox Electron desktop app",
   "author": {
diff --git a/apps/desktop/src/main/bootstrap/window-manager.ts b/apps/desktop/src/main/bootstrap/window-manager.ts
index 75671fa2..1d6d2210 100644
--- a/apps/desktop/src/main/bootstrap/window-manager.ts
+++ b/apps/desktop/src/main/bootstrap/window-manager.ts
@@ -24,10 +24,31 @@ const TITLE_BAR_OVERLAY = {
   dark: { color: '#1e1e1e', symbolColor: '#cccccc' },
   light: { color: '#f8f8f8', symbolColor: '#1f1f20' },
 };
-/** 按当前有效主题取窗控按钮配色（含高度，供建窗与 setTitleBarOverlay 共用）。 */
-function overlayOptions(): { color: string; symbolColor: string; height: number } {
-  const c = nativeTheme.shouldUseDarkColors ? TITLE_BAR_OVERLAY.dark : TITLE_BAR_OVERLAY.light;
-  return { ...c, height: 36 };
+// 渲染层派生的窗控配色（跟随具体主题的 --bg-app/--text-primary，hex）；null 时按 nativeTheme 深浅取通用色兜底。
+let overlayColors: { color: string; symbolColor: string } | null = null;
+/** 通用深/浅窗控配色（无渲染层派生色时的兜底，按 nativeTheme 有效深浅）。 */
+function genericOverlayColors(): { color: string; symbolColor: string } {
+  return nativeTheme.shouldUseDarkColors ? TITLE_BAR_OVERLAY.dark : TITLE_BAR_OVERLAY.light;
+}
+/** 当前窗控 overlay（渲染层派生色优先，否则通用色）+ 高度（与 .app-titlebar 一致 36px）。 */
+function currentOverlay(): { color: string; symbolColor: string; height: number } {
+  return { ...(overlayColors ?? genericOverlayColors()), height: 36 };
+}
+/**
+ * 由渲染层在主题应用后经 IPC 调用：把当前主题派生的窗控配色（color=--bg-app、symbolColor=--text-primary）
+ * 设给所有窗口；传 null 回退通用深/浅色。使窗控按钮与具体主题的标题栏底色精确同色，而非仅通用深/浅。
+ */
+export function setWindowControlColors(colors: { color: string; symbolColor: string } | null): void {
+  overlayColors = colors;
+  if (process.platform === 'darwin') return; // macOS 无 titleBarOverlay
+  for (const win of BrowserWindow.getAllWindows()) {
+    if (win.isDestroyed()) continue;
+    try {
+      win.setTitleBarOverlay(currentOverlay());
+    } catch {
+      /* 平台不支持 setTitleBarOverlay → 忽略 */
+    }
+  }
 }
 
 /**
@@ -89,7 +110,7 @@ export class WindowManager {
       titleBarStyle: 'hidden',
       ...(process.platform === 'darwin'
         ? { trafficLightPosition: { x: 12, y: 11 } }
-        : { titleBarOverlay: overlayOptions() }),
+        : { titleBarOverlay: currentOverlay() }),
       // dev 下显式给窗口图标；打包态窗口/任务栏图标走 exe 内嵌（electron-builder），故仅 dev 设置。
       icon: app.isPackaged
         ? undefined
@@ -149,13 +170,14 @@ export class WindowManager {
       );
     });
 
-    // 全局主题切换（config:setEditorAppearance 据主题改 nativeTheme.themeSource）或 'auto' 主题下 OS
-    // 深浅变化时，nativeTheme 发 'updated'：重置 Windows 窗控按钮配色跟随主题（macOS 无 titleBarOverlay，不注册）。
+    // 'auto' 主题下 OS 深浅变化时 nativeTheme 发 'updated'：按当前 overlay（渲染层派生色优先，否则通用色）
+    // 重置窗控配色兜底（macOS 无 titleBarOverlay，不注册）。具体主题的精确配色由渲染层经 setWindowControlColors
+    // 主动推送（见 useGlobalTheme），此处仅在渲染层未推送时按 nativeTheme 深浅回退。
     if (process.platform !== 'darwin') {
       const onThemeUpdated = (): void => {
         if (win.isDestroyed()) return;
         try {
-          win.setTitleBarOverlay(overlayOptions());
+          win.setTitleBarOverlay(currentOverlay());
         } catch {
           /* 平台不支持 setTitleBarOverlay → 忽略 */
         }
diff --git a/apps/desktop/src/main/controllers/agent.ts b/apps/desktop/src/main/controllers/agent.ts
index c0a0ed71..0cf24d49 100644
--- a/apps/desktop/src/main/controllers/agent.ts
+++ b/apps/desktop/src/main/controllers/agent.ts
@@ -142,6 +142,7 @@ export const runPragent: IpcController<'pragent:run'> = async (_event, req) => {
     'user',
     req.referencedContext,
     req.referencedFinding,
+    req.scope,
   );
 };
 
diff --git a/apps/desktop/src/main/controllers/app.ts b/apps/desktop/src/main/controllers/app.ts
index 59938dab..7ef49dc9 100644
--- a/apps/desktop/src/main/controllers/app.ts
+++ b/apps/desktop/src/main/controllers/app.ts
@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { app, BrowserWindow, dialog, shell } from 'electron';
 import type { Logger } from 'pino';
+import { setWindowControlColors as applyWindowControlColors } from '../bootstrap/window-manager.js';
 import { buildAppInfo, buildConnectionSummaries } from '../services/app.js';
 import { getContext } from '../services/context.js';
 import { applyBadgeCount } from '../services/notifications.js';
@@ -25,6 +26,13 @@ export const readAppInfo: IpcController<'app:info'> = () => buildAppInfo(getCont
  */
 export const readAppPaths: IpcController<'app:paths'> = () => getContext().bootstrap.paths;
 
+/**
+ * 渲染层在主题应用后推送窗控按钮配色（跟随具体主题的 --bg-app/--text-primary）；null 回退通用深/浅。
+ */
+export const setWindowControlColors: IpcController<'window:setControlColors'> = (_event, req) => {
+  applyWindowControlColors(req);
+};
+
 /**
  * pr-agent 探测状态（是否就绪）。
  */
diff --git a/apps/desktop/src/main/controllers/config.ts b/apps/desktop/src/main/controllers/config.ts
index fd400a97..5d555803 100644
--- a/apps/desktop/src/main/controllers/config.ts
+++ b/apps/desktop/src/main/controllers/config.ts
@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 import { nativeTheme } from 'electron';
 import { editorThemeNativeSource } from '@meebox/shared';
 import { writeConfig } from '@meebox/config';
@@ -187,6 +188,31 @@ export const testConnection: IpcController<'config:testConnection'> = async (_ev
   }
 };
 
+/**
+ * 写本地 API 服务监听配置（开关 / host / port / token）；内存同步后热重建监听器（停旧起新）。
+ * token 由请求体携带（设置页保存当前值）；单独「重新生成 token」走 generateServiceToken。
+ */
+export const setService: IpcController<'config:setService'> = async (_event, req) => {
+  const { bootstrap, logger, reconfigureApiServer } = getContext();
+  const next = { ...bootstrap.config, service: req.service };
+  await writeConfig(bootstrap.paths.configFile, next);
+  bootstrap.config.service = req.service;
+  await reconfigureApiServer();
+  logger.info(
+    { enabled: req.service.enabled, host: req.service.host, port: req.service.port },
+    'service listener config updated (hot-reloaded)',
+  );
+};
+
+/**
+ * 生成一枚高强度随机 bearer token（32 字节 → base64url，43 字符，字符集 [A-Za-z0-9-_]，URL / 请求头安全）
+ * 并返回，**不落盘**——由前端置入设置草稿，随底栏「保存」经 config:setService 生效；不保存则丢弃
+ * （与 host / port 同为草稿制）。
+ */
+export const generateServiceToken: IpcController<'config:generateServiceToken'> = () => {
+  return { token: randomBytes(32).toString('base64url') };
+};
+
 /**
  * 配置过程中把连接 + LLM 草稿写盘防丢失，但不更新内存 config、不 reconfigure（不生效）。
  */
diff --git a/apps/desktop/src/main/i18n/locales/de-DE.json b/apps/desktop/src/main/i18n/locales/de-DE.json
index 13c6cb02..c1d260e2 100644
--- a/apps/desktop/src/main/i18n/locales/de-DE.json
+++ b/apps/desktop/src/main/i18n/locales/de-DE.json
@@ -21,6 +21,18 @@
     }
   },
   "notifications": {
+    "authoredComment": {
+      "body": "#{{id}} {{title}}",
+      "title": "Neuer Kommentar zu deinem PR"
+    },
+    "authoredConflict": {
+      "body": "#{{id}} {{title}}",
+      "title": "Dein PR hat einen Merge-Konflikt"
+    },
+    "authoredNeedsWork": {
+      "body": "#{{id}} {{title}}",
+      "title": "Dein PR wurde als überarbeitungsbedürftig markiert"
+    },
     "mention": {
       "body": "#{{id}} {{title}}",
       "title": "Du wurdest erwähnt"
diff --git a/apps/desktop/src/main/i18n/locales/en-US.json b/apps/desktop/src/main/i18n/locales/en-US.json
index 98f5cfbb..4c682615 100644
--- a/apps/desktop/src/main/i18n/locales/en-US.json
+++ b/apps/desktop/src/main/i18n/locales/en-US.json
@@ -21,6 +21,18 @@
     }
   },
   "notifications": {
+    "authoredComment": {
+      "body": "#{{id}} {{title}}",
+      "title": "New comment on your PR"
+    },
+    "authoredConflict": {
+      "body": "#{{id}} {{title}}",
+      "title": "Your PR has a merge conflict"
+    },
+    "authoredNeedsWork": {
+      "body": "#{{id}} {{title}}",
+      "title": "Your PR was marked needs-work"
+    },
     "mention": {
       "body": "#{{id}} {{title}}",
       "title": "You were mentioned"
diff --git a/apps/desktop/src/main/i18n/locales/ja-JP.json b/apps/desktop/src/main/i18n/locales/ja-JP.json
index 5a9caca4..f6c867ff 100644
--- a/apps/desktop/src/main/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/main/i18n/locales/ja-JP.json
@@ -20,6 +20,18 @@
     }
   },
   "notifications": {
+    "authoredComment": {
+      "body": "#{{id}} {{title}}",
+      "title": "あなたの PR に新しいコメント"
+    },
+    "authoredConflict": {
+      "body": "#{{id}} {{title}}",
+      "title": "あなたの PR にマージ競合が発生"
+    },
+    "authoredNeedsWork": {
+      "body": "#{{id}} {{title}}",
+      "title": "あなたの PR が要修正に設定されました"
+    },
     "mention": {
       "body": "#{{id}} {{title}}",
       "title": "あなたへのメンションがあります"
diff --git a/apps/desktop/src/main/i18n/locales/zh-CN.json b/apps/desktop/src/main/i18n/locales/zh-CN.json
index 09308a59..dc1c905f 100644
--- a/apps/desktop/src/main/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/main/i18n/locales/zh-CN.json
@@ -20,6 +20,18 @@
     }
   },
   "notifications": {
+    "authoredComment": {
+      "body": "#{{id}} {{title}}",
+      "title": "你的 PR 有新评论"
+    },
+    "authoredConflict": {
+      "body": "#{{id}} {{title}}",
+      "title": "你的 PR 出现合并冲突"
+    },
+    "authoredNeedsWork": {
+      "body": "#{{id}} {{title}}",
+      "title": "你的 PR 被标记需修改"
+    },
     "mention": {
       "body": "#{{id}} {{title}}",
       "title": "有人提到了你"
diff --git a/apps/desktop/src/main/index.ts b/apps/desktop/src/main/index.ts
index cbb9c078..4d140825 100644
--- a/apps/desktop/src/main/index.ts
+++ b/apps/desktop/src/main/index.ts
@@ -21,6 +21,7 @@ import {
 } from './bootstrap/index.js';
 import { initMainI18n } from './i18n/index.js';
 import { registerIpcHandlers } from './ipc.js';
+import { ApiServer } from './services/api-server/index.js';
 import { readConnectionStates } from './utils/connection-state.js';
 
 // 进程（模块加载）起点：用于度量到主窗口首帧（ready-to-show）的启动耗时。
@@ -53,6 +54,8 @@ class App {
   private conns!: ConnectionRuntimeController;
   private windowManager!: WindowManager;
   private ipcControl?: IpcControl;
+  /** 本地 API 服务监听器（默认关闭；按 config.service 决定是否 listen）。 */
+  private apiServer?: ApiServer;
   private quitCleanupDone = false;
 
   constructor(private readonly startMs: number) {}
@@ -210,7 +213,15 @@ class App {
       connectionRuntime: this.conns.runtime,
       reconfigureConnections: () => this.conns.reconfigure(),
       repoMirror: this.repoMirror,
+      // 惰性引用：ApiServer 在 registerIpcHandlers 之后才构造（其请求处理依赖此刻才安装的
+      // ControllerContext 单例）；闭包在 config:setService 调用时才取最新实例。
+      reconfigureApiServer: () => this.apiServer?.reconfigure() ?? Promise.resolve(),
     });
+
+    // 本地 API 服务监听器：ControllerContext 已由 registerIpcHandlers 安装，可安全处理请求。
+    // 按 config.service 决定是否实际 listen（默认关闭）；监听失败为非致命（内部已兜底记录）。
+    this.apiServer = new ApiServer({ bootstrap: this.bootstrap, logger: this.logger });
+    await this.apiServer.start();
   }
 
   /**
@@ -293,6 +304,8 @@ class App {
     // 不清理会留孤儿进程锁住安装目录 → 升级时 NSIS 报「应用无法关闭」。
     app.on('before-quit', (event) => {
       if (this.poller) this.poller.stop();
+      // 停本地 API 监听（停止接收新连接）；fire-and-forget，关闭很快、不阻塞退出。
+      void this.apiServer?.stop();
       if (this.quitCleanupDone) return;
       const aborted = this.ipcControl?.abortAllActiveRuns() ?? 0;
       if (aborted === 0) return; // 无进行中 run，直接退出
diff --git a/apps/desktop/src/main/ipc.ts b/apps/desktop/src/main/ipc.ts
index c86338f1..25cb790a 100644
--- a/apps/desktop/src/main/ipc.ts
+++ b/apps/desktop/src/main/ipc.ts
@@ -44,6 +44,7 @@ export function registerIpcHandlers(deps: RegisterDeps): {
   ipcMain.handle('app:paths', app.readAppPaths); // 关键目录路径（config / agent / 日志）
   ipcMain.handle('app:prAgentStatus', app.readPrAgentStatus); // pr-agent 探测状态（是否就绪）
   ipcMain.handle('log:write', app.writeRendererLog); // 渲染层日志回传落盘
+  ipcMain.handle('window:setControlColors', app.setWindowControlColors); // 渲染层推送主题派生窗控配色
   ipcMain.handle('app:connections', app.listConnections); // 当前活动连接摘要（Header / 状态栏）
   ipcMain.handle('app:userAvatar', app.getUserAvatar); // 用户头像（内存 + 磁盘两级缓存）
   ipcMain.handle('app:openConfigFile', app.openConfigFile); // 打开 config.yaml
@@ -114,6 +115,8 @@ export function registerIpcHandlers(deps: RegisterDeps): {
   ipcMain.handle('config:autosaveDraft', config.autosaveDraft); // 连接 / LLM 草稿存盘（不生效）
   ipcMain.handle('config:setPoller', config.setPoller); // 设轮询间隔（热替换定时器）
   ipcMain.handle('config:setMaxConcurrency', config.setMaxConcurrency); // 设评审并发数（热替换队列上限）
+  ipcMain.handle('config:setService', config.setService); // 设本地 API 服务监听（热重建监听器）
+  ipcMain.handle('config:generateServiceToken', config.generateServiceToken); // 重新生成 API bearer token
 
   /*
    * Agent 交互
diff --git a/apps/desktop/src/main/services/agent/flows/planning.ts b/apps/desktop/src/main/services/agent/flows/planning.ts
index 82c77b21..da8ded62 100644
--- a/apps/desktop/src/main/services/agent/flows/planning.ts
+++ b/apps/desktop/src/main/services/agent/flows/planning.ts
@@ -84,6 +84,9 @@ export async function runPlanningForPr(
     matchedRuleInstructions: combineRuleInstructions(matchedRules),
     language: getMainLanguage(),
     maxSteps: agentCfg.max_steps,
+    // /ask 预算：自由规划里连续 /ask 各为一次 agentic 探索、成本高，按配置「追问数量」封顶（与「自动追问」
+    // 开关无关——开关仅约束评审微流程；此处始终生效，遵循配置的追问数量上限）。
+    maxFollowupAsks: agentCfg.strategy.max_followup_asks,
     signal,
     onStep: (sessionId, step) => runtime.emitStep(pr, sessionId, step),
     // 中途输入转向：planner 每轮取出排队消息时在此落盘进会话 + 广播刷新（即时显示为用户气泡），
diff --git a/apps/desktop/src/main/services/agent/planning.ts b/apps/desktop/src/main/services/agent/planning.ts
index 510e7aff..1a241dd4 100644
--- a/apps/desktop/src/main/services/agent/planning.ts
+++ b/apps/desktop/src/main/services/agent/planning.ts
@@ -85,6 +85,8 @@ export interface PlanningDeps {
   matchedRuleInstructions?: string | null;
   language: string;
   maxSteps: number;
+  /** 本会话 /ask 数量上限（配置「追问数量」max_followup_asks）：连续 agentic 探索成本高，按此封顶。 */
+  maxFollowupAsks: number;
   /** 用户选中的代码引用（隐式上下文）：注入规划 LLM 当轮提示，不进持久化用户消息。 */
   referencedContext?: string;
   signal?: AbortSignal;
@@ -155,6 +157,7 @@ export async function runPlanning(
         history,
         referencedContext: deps.referencedContext,
         maxSteps: deps.maxSteps,
+        maxFollowupAsks: deps.maxFollowupAsks,
       },
     );
 
diff --git a/apps/desktop/src/main/services/api-server/compat.ts b/apps/desktop/src/main/services/api-server/compat.ts
new file mode 100644
index 00000000..25c91428
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/compat.ts
@@ -0,0 +1,36 @@
+import { coerce as semverCoerce, lt as semverLt, valid as semverValid } from 'semver';
+
+/**
+ * CLI ↔ server 兼容性门控（见 docs/arch/04-integration/01-service-api.md）。
+ *
+ * CLI 每个请求带上自身版本头，服务端据集中管理的**最低可兼容版本**统一拦截过旧的 CLI——对所有 API 调用
+ * 一视同仁，不做按端点的差异化兼容。默认宽松：缺版本头（旧 CLI / 非 CLI 客户端）或版本不可解析（如本地
+ * `dev` 构建）均放行，保证既有 CLI 默认可用；仅当版本头**可解析且低于下限**时才门控。
+ *
+ * **按版本线（major.minor.patch）比对，忽略预发布后缀**：CLI 与 app 同源发版，预发布构建（如
+ * `0.9.0-alpha.1`）与其正式版属同一版本线、共享同一线协议。semver 里预发布**低于**其正式版
+ * （`0.9.0-alpha.1` < `0.9.0`），若直接比对会把与下限同线的预发布 CLI 误判为过旧（下限 `0.9.0` 时连
+ * `0.9.0-alpha.1` 都被拦）。故先把版本 coerce 到 `major.minor.patch` 再比——下限是版本线粒度的
+ * 破坏性变更闸门，不区分同线内的预发布序号。
+ */
+
+/** CLI 在此请求头声明自身版本（Node 会小写化头名）。与 CLI 端手写常量对齐（无代码级共享）。 */
+export const CLI_VERSION_HEADER = 'x-meebox-cli-version';
+
+/**
+ * 服务端可兼容的最低 CLI 版本。破坏性线协议变更时上调此值，即门控掉更旧的 CLI。
+ * 取当前 CLI 首发版本为下限（此前无更旧的已发布 CLI），默认不拦截任何在用版本。
+ */
+export const MIN_CLI_VERSION = '0.9.0';
+
+/** 请求携带的 CLI 版本是否过旧（应拦截）。缺头 / 不可解析 → false（放行）。 */
+export function isClientTooOld(rawHeader: string | string[] | undefined): boolean {
+  const raw = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+  if (!raw) return false;
+  const v = semverValid(raw.trim());
+  if (!v) return false; // 不可解析（dev 等）→ 放行
+  // 剥离预发布后缀，按版本线（major.minor.patch）比对，使同线预发布不低于下限（见文件头注释）。
+  const line = semverCoerce(v);
+  if (!line) return false;
+  return semverLt(line, MIN_CLI_VERSION);
+}
diff --git a/apps/desktop/src/main/services/api-server/http.ts b/apps/desktop/src/main/services/api-server/http.ts
new file mode 100644
index 00000000..c40737bb
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/http.ts
@@ -0,0 +1,84 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { AppError, ERROR_CODES, type AppErrorMeta, type ErrorCode } from '@meebox/shared';
+
+/**
+ * 本地 API 的 HTTP 工具：统一响应封套（{ ok, data } / { ok:false, error }）、请求体读取、
+ * 错误 → HTTP 状态码映射。见 docs/arch/04-integration/01-service-api.md。
+ */
+
+const MAX_BODY_BYTES = 1024 * 1024; // 1 MiB 请求体上限
+
+/** API 层错误（鉴权 / 路由 / 校验 / 写禁止等）：自带 HTTP 状态码与错误码。 */
+export class HttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: ErrorCode,
+    readonly meta?: AppErrorMeta,
+  ) {
+    super(code);
+    this.name = 'HttpError';
+  }
+}
+
+function writeJson(res: ServerResponse, status: number, payload: unknown): void {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(body);
+}
+
+/** 成功响应：200 + { ok:true, data }。 */
+export function sendOk(res: ServerResponse, data: unknown): void {
+  writeJson(res, 200, { ok: true, data: data ?? null });
+}
+
+/** 失败响应：按错误映射状态码 + { ok:false, error:{ code, meta } }；返回所选状态码 / 码供日志。 */
+export function sendError(res: ServerResponse, err: unknown): { status: number; code: string } {
+  const mapped = mapError(err);
+  writeJson(res, mapped.status, {
+    ok: false,
+    error: { code: mapped.code, ...(mapped.meta ? { meta: mapped.meta } : {}) },
+  });
+  return { status: mapped.status, code: mapped.code };
+}
+
+function mapError(err: unknown): { status: number; code: ErrorCode; meta?: AppErrorMeta } {
+  if (err instanceof HttpError) return { status: err.status, code: err.code, meta: err.meta };
+  if (err instanceof AppError) return { status: statusForAppCode(err.code), code: err.code, meta: err.meta };
+  return { status: 500, code: ERROR_CODES.SV_UNCLASSIFIED };
+}
+
+/** 把控制器抛出的 AppError 业务码映射到合适的 HTTP 状态码（未覆盖者归 500）。 */
+function statusForAppCode(code: ErrorCode): number {
+  switch (code) {
+    case ERROR_CODES.PR_NOT_FOUND:
+      return 404;
+    case ERROR_CODES.PR_FORBIDDEN:
+      return 403;
+    case ERROR_CODES.PR_URL_INVALID:
+    case ERROR_CODES.AG_ASK_NEEDS_QUESTION:
+      return 400;
+    case ERROR_CODES.PR_NO_ACTIVE_CONNECTION:
+      return 409;
+    case ERROR_CODES.AG_PR_AGENT_NOT_READY:
+      return 503;
+    default:
+      return 500;
+  }
+}
+
+/** 读取并解析 JSON 请求体（空体 → undefined）；超限 413、非法 JSON 400，均归一为 SV 错误码。 */
+export async function readJsonBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for await (const chunk of req) {
+    total += (chunk as Buffer).length;
+    if (total > MAX_BODY_BYTES) throw new HttpError(413, ERROR_CODES.SV_BAD_REQUEST, { reason: 'body too large' });
+    chunks.push(chunk as Buffer);
+  }
+  if (total === 0) return undefined;
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    throw new HttpError(400, ERROR_CODES.SV_BAD_REQUEST, { reason: 'invalid json' });
+  }
+}
diff --git a/apps/desktop/src/main/services/api-server/index.ts b/apps/desktop/src/main/services/api-server/index.ts
new file mode 100644
index 00000000..fe586550
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/index.ts
@@ -0,0 +1 @@
+export { ApiServer, type ApiServerDeps } from './server.js';
diff --git a/apps/desktop/src/main/services/api-server/routes/agent.ts b/apps/desktop/src/main/services/api-server/routes/agent.ts
new file mode 100644
index 00000000..dcfb8848
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/routes/agent.ts
@@ -0,0 +1,85 @@
+import { ERROR_CODES, type ReviewRunTool } from '@meebox/shared';
+import * as agentCtl from '../../../controllers/agent.js';
+import { HttpError } from '../http.js';
+import { toPrAgentRuns } from '../views.js';
+import { NO_EVENT, seg, type Route, type RouteHandler } from './shared.js';
+
+/**
+ * 评审 Agent 领域端点：状态 / 会话（浏览），auto review / 指令 / 聊天 / 中断（写入型，复用既有 run 队列），
+ * 以及按 run 的发现与取消。Agent `instruct` **仅只读工具**，变更类工具（publish 等）在 API 层硬拒绝。
+ */
+
+/** API 仅允许的只读 Agent 指令（与工具注册表 isRun 只读族一致；写工具不在此列）。 */
+const READ_ONLY_TOOLS: ReadonlySet<ReviewRunTool> = new Set([
+  'describe',
+  'review',
+  'ask',
+  'improve',
+]);
+
+const agentStatus: RouteHandler = ({ params }) =>
+  agentCtl.getSession(NO_EVENT, { localId: params.id });
+
+const agentHistory: RouteHandler = ({ params }) =>
+  agentCtl.getConversation(NO_EVENT, { localId: params.id });
+
+const agentReview: RouteHandler = ({ params }) => agentCtl.runReview(NO_EVENT, { localId: params.id });
+
+/** 发送只读 Agent 指令（describe / review / ask / improve）；写工具硬拒绝（403），无二次确认。 */
+const agentInstruct: RouteHandler = ({ params, body }) => {
+  const b = (body ?? {}) as { command?: string; args?: string };
+  const command = (b.command ?? '').replace(/^\//, '') as ReviewRunTool;
+  if (!READ_ONLY_TOOLS.has(command)) {
+    throw new HttpError(403, ERROR_CODES.SV_WRITE_NOT_ALLOWED, { command: b.command ?? '' });
+  }
+  if (command === 'ask' && !b.args?.trim()) {
+    throw new HttpError(400, ERROR_CODES.SV_BAD_REQUEST, { reason: 'ask requires args' });
+  }
+  return agentCtl.runPragent(NO_EVENT, { localId: params.id, tool: command, question: b.args });
+};
+
+/** 发送自然语言聊天（可触发 Agent 任务）：运行中入队、否则起一轮自由规划兜底。 */
+const agentChat: RouteHandler = ({ params, body }) => {
+  const b = (body ?? {}) as { message?: string };
+  if (!b.message?.trim()) {
+    throw new HttpError(400, ERROR_CODES.SV_BAD_REQUEST, { reason: 'message required' });
+  }
+  return agentCtl.enqueueMessage(NO_EVENT, { localId: params.id, message: b.message });
+};
+
+/** 中断该 PR 正在运行的 Agent（思考 / 执行任意阶段即时停）。PR 级停，非按单个工具 run。 */
+const agentStop: RouteHandler = ({ params }) =>
+  agentCtl.stopAgent(NO_EVENT, { localId: params.id });
+
+/** 该 PR 在运行队列里的 pr-agent runs（active + waiting），供按 run 取消前的发现。 */
+const agentRuns: RouteHandler = async ({ params }) => {
+  const snapshot = await agentCtl.getQueue(NO_EVENT, undefined);
+  return toPrAgentRuns(snapshot, params.id);
+};
+
+/** 取消该 PR 的某个 pr-agent run（active SIGKILL / waiting 出队）。先校验 run 归属该 PR。 */
+const agentRunCancel: RouteHandler = async ({ params }) => {
+  const snapshot = await agentCtl.getQueue(NO_EVENT, undefined);
+  const belongs = [...snapshot.active, ...snapshot.waiting].some(
+    (r) => r.runId === params.runId && r.prLocalId === params.id,
+  );
+  if (!belongs) {
+    throw new HttpError(404, ERROR_CODES.SV_NOT_FOUND, { runId: params.runId, localId: params.id });
+  }
+  return agentCtl.cancelPragent(NO_EVENT, { runId: params.runId });
+};
+
+export const agentRoutes: Route[] = [
+  { method: 'GET', segments: seg('/api/v1/prs/:id/agent'), handler: agentStatus },
+  { method: 'GET', segments: seg('/api/v1/prs/:id/agent/conversation'), handler: agentHistory },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/agent/review'), handler: agentReview },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/agent/instruct'), handler: agentInstruct },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/agent/chat'), handler: agentChat },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/agent/stop'), handler: agentStop },
+  { method: 'GET', segments: seg('/api/v1/prs/:id/agent/runs'), handler: agentRuns },
+  {
+    method: 'POST',
+    segments: seg('/api/v1/prs/:id/agent/runs/:runId/cancel'),
+    handler: agentRunCancel,
+  },
+];
diff --git a/apps/desktop/src/main/services/api-server/routes/index.ts b/apps/desktop/src/main/services/api-server/routes/index.ts
new file mode 100644
index 00000000..45293411
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/routes/index.ts
@@ -0,0 +1,36 @@
+import { agentRoutes } from './agent.js';
+import { prRoutes } from './pr.js';
+import { seg, type Route } from './shared.js';
+import { systemRoutes } from './system.js';
+
+/**
+ * 本地 API 的路由**聚合注册 + 匹配**。各业务领域的处理器分置于同目录的 system / pr / agent 模块
+ * （均复用 IPC controller 同源逻辑）；本文件只做注册与路径匹配，不含业务逻辑。
+ * 端点全表与写边界见 docs/arch/04-integration/01-service-api.md。
+ */
+export const routes: Route[] = [...systemRoutes, ...prRoutes, ...agentRoutes];
+
+export type { Route, RouteContext, RouteHandler } from './shared.js';
+
+/** 按方法 + 路径匹配路由，提取 `:param` 路径参数；无匹配返回 null。 */
+export function matchRoute(
+  method: string,
+  pathname: string,
+): { route: Route; params: Record<string, string> } | null {
+  const parts = seg(pathname);
+  for (const route of routes) {
+    if (route.method !== method || route.segments.length !== parts.length) continue;
+    const params: Record<string, string> = {};
+    let ok = true;
+    for (let i = 0; i < route.segments.length; i++) {
+      const s = route.segments[i];
+      if (s.startsWith(':')) params[s.slice(1)] = decodeURIComponent(parts[i]);
+      else if (s !== parts[i]) {
+        ok = false;
+        break;
+      }
+    }
+    if (ok) return { route, params };
+  }
+  return null;
+}
diff --git a/apps/desktop/src/main/services/api-server/routes/pr.ts b/apps/desktop/src/main/services/api-server/routes/pr.ts
new file mode 100644
index 00000000..60666364
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/routes/pr.ts
@@ -0,0 +1,116 @@
+import type { DiffSide } from '@meebox/ipc';
+import {
+  ERROR_CODES,
+  PR_SECONDARY_FILTERS,
+  filterPullRequests,
+  type PrDiscoveryFilter,
+  type PrSecondaryFilter,
+} from '@meebox/shared';
+import * as prCtl from '../../../controllers/pr.js';
+import { getContext } from '../../context.js';
+import { HttpError } from '../http.js';
+import { toPrListItem } from '../views.js';
+import { NO_EVENT, seg, type Route, type RouteHandler } from './shared.js';
+
+/**
+ * PR 领域端点：列表 / 详情 / diff / 动态 / 提交 / 评审人（浏览），刷新（refresh）与分类词表（categories），
+ * 以及评审写动作（approve / needswork / comment，真实远端写，复用 GUI 同源 controller）。
+ * 仍**不**暴露 merge（合并）。写边界见 docs/arch/04-integration/01-service-api.md。
+ */
+
+/** 列表分页默认页大小（`limit` 缺省 / 非法 / ≤0 时取此值）。 */
+const DEFAULT_LIMIT = 100;
+
+/** 当前启用平台下可用的分类标签：`categories`（平台发现分类）+ `statuses`（状态 / 合并态筛选）。 */
+const categories: RouteHandler = () => {
+  const ctx = getContext();
+  const activeId = ctx.bootstrap.config.active_connection_id;
+  const built = activeId
+    ? ctx.connectionRuntime.adapters.find((a) => a.connectionId === activeId)
+    : undefined;
+  const caps = built?.adapter.connection.capabilities();
+  const categoryList: PrDiscoveryFilter[] = caps?.discoveryFilters
+    ? [...caps.discoveryFilters]
+    : ['review-requested'];
+  return {
+    platform: built?.adapter.kind ?? null,
+    categories: categoryList,
+    statuses: [...PR_SECONDARY_FILTERS],
+  };
+};
+
+/**
+ * 触发一次立即轮询刷新（等价 GUI 的手动刷新 / 窗口聚焦刷新）：拉取所有连接的最新 PR、落本地，
+ * 返回本轮计数汇总（fetched / changed / added / removed / errors）。复用 GUI 同源 poller.tick
+ * （`prs:refresh`）。无远端写副作用（纯读远端 + 落本地），列为安全的开放动作。
+ */
+const refresh: RouteHandler = () => prCtl.refreshPrs(NO_EVENT, undefined);
+
+/**
+ * PR 列表：`category`（一级发现分类）+ `status`（二级状态 / 合并态）过滤 + `q` 检索 +
+ * `skip`/`limit` 分页（默认 limit 100）。过滤语义复用 @meebox/shared 的纯谓词（与渲染层侧栏同源）；
+ * 返回**精简列表投影**（{@link toPrListItem}，去 description 明细、人员仅 slug），此处仅解析参数 + 委派。
+ */
+const listPrs: RouteHandler = async ({ query }) => {
+  const all = await prCtl.listPrs(NO_EVENT, undefined);
+  const filtered = filterPullRequests(all, {
+    primary: (query.get('category') as PrDiscoveryFilter) || undefined,
+    secondary: (query.get('status') as PrSecondaryFilter) || undefined,
+    query: query.get('q') ?? undefined,
+  });
+  const skip = Math.max(0, Number.parseInt(query.get('skip') ?? '', 10) || 0);
+  const limitRaw = Number.parseInt(query.get('limit') ?? '', 10);
+  const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? limitRaw : DEFAULT_LIMIT;
+  return filtered.slice(skip, skip + limit).map(toPrListItem);
+};
+
+const showPr: RouteHandler = ({ params }) => getContext().pr.findPrOrThrow(params.id);
+
+const reviewers: RouteHandler = async ({ params }) =>
+  (await getContext().pr.findPrOrThrow(params.id)).reviewers;
+
+/** 无 path → 变更文件列表；带 path → 取该文件某一侧（默认 head）内容。 */
+const diff: RouteHandler = ({ params, query }) => {
+  const path = query.get('path');
+  if (path) {
+    const side: DiffSide = query.get('side') === 'base' ? 'base' : 'head';
+    return prCtl.getFileContent(NO_EVENT, { localId: params.id, side, path });
+  }
+  return prCtl.listChangedFiles(NO_EVENT, { localId: params.id });
+};
+
+const activity: RouteHandler = ({ params }) =>
+  prCtl.listActivity(NO_EVENT, { localId: params.id });
+
+const commits: RouteHandler = ({ params }) => prCtl.listCommits(NO_EVENT, { localId: params.id });
+
+/** 评审决断「通过」：先写远端评审状态、再落本地（复用 GUI 同源 setPrStatus）。 */
+const approve: RouteHandler = ({ params }) =>
+  prCtl.setPrStatus(NO_EVENT, { localId: params.id, status: 'approved' });
+
+/** 评审决断「需修改」：先写远端评审状态、再落本地。 */
+const needswork: RouteHandler = ({ params }) =>
+  prCtl.setPrStatus(NO_EVENT, { localId: params.id, status: 'needs_work' });
+
+/** 发一条顶层（不锚文件）评论到远端 PR。body.body 为评论正文，空则 400。 */
+const comment: RouteHandler = ({ params, body }) => {
+  const b = (body ?? {}) as { body?: string };
+  if (!b.body?.trim()) {
+    throw new HttpError(400, ERROR_CODES.SV_BAD_REQUEST, { reason: 'comment body required' });
+  }
+  return prCtl.createComment(NO_EVENT, { localId: params.id, body: b.body });
+};
+
+export const prRoutes: Route[] = [
+  { method: 'GET', segments: seg('/api/v1/categories'), handler: categories },
+  { method: 'POST', segments: seg('/api/v1/refresh'), handler: refresh },
+  { method: 'GET', segments: seg('/api/v1/prs'), handler: listPrs },
+  { method: 'GET', segments: seg('/api/v1/prs/:id'), handler: showPr },
+  { method: 'GET', segments: seg('/api/v1/prs/:id/diff'), handler: diff },
+  { method: 'GET', segments: seg('/api/v1/prs/:id/activity'), handler: activity },
+  { method: 'GET', segments: seg('/api/v1/prs/:id/commits'), handler: commits },
+  { method: 'GET', segments: seg('/api/v1/prs/:id/reviewers'), handler: reviewers },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/approve'), handler: approve },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/needswork'), handler: needswork },
+  { method: 'POST', segments: seg('/api/v1/prs/:id/comment'), handler: comment },
+];
diff --git a/apps/desktop/src/main/services/api-server/routes/shared.ts b/apps/desktop/src/main/services/api-server/routes/shared.ts
new file mode 100644
index 00000000..0e9c27a7
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/routes/shared.ts
@@ -0,0 +1,30 @@
+import type { IpcMainInvokeEvent } from 'electron';
+
+/**
+ * 路由框架原语，供同目录各业务领域模块（system / pr / agent）与聚合器（index）共用。
+ * 各域处理器**复用 IPC controller 同源逻辑**——controller 形态为 `(event, req)` 且这些路径不触碰
+ * event，故以 {@link NO_EVENT} 占位调用，避免在 HTTP 侧另起一套实现。
+ */
+
+/** 单条路由处理器的入参：路径参数 / 查询串 / 已解析 body。 */
+export interface RouteContext {
+  params: Record<string, string>;
+  query: URLSearchParams;
+  body: unknown;
+}
+
+export type RouteHandler = (rc: RouteContext) => Promise<unknown> | unknown;
+
+export interface Route {
+  method: 'GET' | 'POST';
+  segments: string[];
+  handler: RouteHandler;
+}
+
+/** 把 `/api/v1/prs/:id` 切成非空段数组（注册与匹配共用）。 */
+export function seg(path: string): string[] {
+  return path.split('/').filter(Boolean);
+}
+
+/** controller 形参 event 在被复用的只读 / 队列路径中均未使用，占位即可。 */
+export const NO_EVENT = undefined as unknown as IpcMainInvokeEvent;
diff --git a/apps/desktop/src/main/services/api-server/routes/system.ts b/apps/desktop/src/main/services/api-server/routes/system.ts
new file mode 100644
index 00000000..3296fe1d
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/routes/system.ts
@@ -0,0 +1,39 @@
+import { buildAppInfo } from '../../app.js';
+import { getContext } from '../../context.js';
+import { seg, type Route, type RouteHandler } from './shared.js';
+
+/**
+ * 系统性 / 会话级端点：与具体 PR / Agent 无关的工具层信息——身份（whoami）与版本（version）。
+ * 对应 CLI 的根层级系统性命令。
+ */
+
+/**
+ * 当前身份与集成平台：活动连接的 PAT 所属用户（name / displayName / slug）+ 平台种类 +
+ * 连接显示名。无活动连接时各项为 null。刻意收窄——不带 capabilities（那是 GUI 降级用的大对象）。
+ */
+const whoami: RouteHandler = () => {
+  const ctx = getContext();
+  const activeId = ctx.bootstrap.config.active_connection_id;
+  const built = activeId
+    ? ctx.connectionRuntime.adapters.find((a) => a.connectionId === activeId)
+    : undefined;
+  if (!activeId || !built) {
+    return { platform: null, connectionId: null, displayName: null, user: null };
+  }
+  const conn = ctx.bootstrap.config.connections.find((c) => c.id === activeId);
+  const user = built.adapter.connection.getCurrentUser();
+  return {
+    platform: built.adapter.kind,
+    connectionId: activeId,
+    displayName: conn?.display_name ?? activeId,
+    user: user ? { name: user.name, displayName: user.displayName, slug: user.slug ?? null } : null,
+  };
+};
+
+/** 服务端（桌面应用）版本，供 CLI `version` 同时展示客户端 + 服务端版本。 */
+const version: RouteHandler = () => ({ version: buildAppInfo(getContext().bootstrap).appVersion });
+
+export const systemRoutes: Route[] = [
+  { method: 'GET', segments: seg('/api/v1/whoami'), handler: whoami },
+  { method: 'GET', segments: seg('/api/v1/version'), handler: version },
+];
diff --git a/apps/desktop/src/main/services/api-server/server.ts b/apps/desktop/src/main/services/api-server/server.ts
new file mode 100644
index 00000000..2437611f
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/server.ts
@@ -0,0 +1,125 @@
+import { timingSafeEqual } from 'node:crypto';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { BootstrapResult } from '@meebox/config';
+import { ERROR_CODES } from '@meebox/shared';
+import type { Logger } from 'pino';
+import { CLI_VERSION_HEADER, MIN_CLI_VERSION, isClientTooOld } from './compat.js';
+import { HttpError, readJsonBody, sendError, sendOk } from './http.js';
+import { matchRoute } from './routes/index.js';
+
+/**
+ * 本地 API 服务监听器（见 docs/arch/04-integration/01-service-api.md）。
+ *
+ * 主进程内置 HTTP listener，作为渲染层 IPC 之外的「第二前端」：复用同一 ControllerContext 与 service 层，
+ * 把只读 PR / Agent 能力暴露给外部 CLI / 工具。默认关闭；开启即强制 bearer token 鉴权。生命周期由 main 装配：
+ * start（按 config 决定是否 listen）/ stop（退出时优雅关闭）/ reconfigure（配置变更停旧起新）。
+ */
+export interface ApiServerDeps {
+  bootstrap: BootstrapResult;
+  logger: Logger;
+}
+
+export class ApiServer {
+  private server?: Server;
+
+  constructor(private readonly deps: ApiServerDeps) {}
+
+  /** 实时读内存 service 配置（token 变更无需重建即生效）。 */
+  private get cfg() {
+    return this.deps.bootstrap.config.service;
+  }
+
+  /** 按配置启动监听（未启用 / token 为空则不启动）。监听失败为非致命：记录后不抛，不拖垮应用启动。 */
+  async start(): Promise<void> {
+    if (this.server) return;
+    const cfg = this.cfg;
+    if (!cfg.enabled) return;
+    if (!cfg.token) {
+      this.deps.logger.warn('api server enabled but token is empty; not starting');
+      return;
+    }
+    const server = createServer((req, res) => {
+      void this.handle(req, res);
+    });
+    this.server = server;
+    await new Promise<void>((resolve, reject) => {
+      const onError = (err: Error): void => {
+        this.server = undefined;
+        reject(err);
+      };
+      server.once('error', onError);
+      server.listen(cfg.port, cfg.host, () => {
+        server.off('error', onError);
+        server.on('error', (err) => this.deps.logger.error({ err }, 'api server runtime error'));
+        this.deps.logger.info({ host: cfg.host, port: cfg.port }, 'local API server listening');
+        resolve();
+      });
+    }).catch((err: unknown) => {
+      this.deps.logger.error({ err, port: cfg.port }, 'local API server failed to listen (non-fatal)');
+    });
+  }
+
+  /** 优雅关闭：停止接收新连接、放行 in-flight 后落定。 */
+  async stop(): Promise<void> {
+    const server = this.server;
+    if (!server) return;
+    this.server = undefined;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    this.deps.logger.info('local API server stopped');
+  }
+
+  /** 配置（开关 / host / port）变更：停旧起新。 */
+  async reconfigure(): Promise<void> {
+    await this.stop();
+    await this.start();
+  }
+
+  /** 常数时间比对 bearer token；缺 token 配置 / 非 Bearer 头 / 长度不符均判失败。 */
+  private authorized(req: IncomingMessage): boolean {
+    const token = this.cfg.token;
+    if (!token) return false;
+    const header = req.headers['authorization'];
+    if (typeof header !== 'string' || !header.startsWith('Bearer ')) return false;
+    const provided = Buffer.from(header.slice('Bearer '.length));
+    const expected = Buffer.from(token);
+    if (provided.length !== expected.length) return false;
+    return timingSafeEqual(provided, expected);
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const started = Date.now();
+    const method = req.method ?? 'GET';
+    const rawUrl = req.url ?? '/';
+    const qIdx = rawUrl.indexOf('?');
+    const pathname = qIdx >= 0 ? rawUrl.slice(0, qIdx) : rawUrl;
+    const search = qIdx >= 0 ? rawUrl.slice(qIdx + 1) : '';
+
+    let outcome: { status: number; code?: string };
+    try {
+      if (!this.authorized(req)) throw new HttpError(401, ERROR_CODES.SV_UNAUTHORIZED);
+      // 兼容性门控：对所有 API 调用统一拦截过旧的 CLI（缺版本头 / 不可解析 → 放行）。
+      if (isClientTooOld(req.headers[CLI_VERSION_HEADER])) {
+        throw new HttpError(426, ERROR_CODES.SV_CLIENT_TOO_OLD, {
+          minVersion: MIN_CLI_VERSION,
+          clientVersion: String(req.headers[CLI_VERSION_HEADER] ?? ''),
+        });
+      }
+      const matched = matchRoute(method, pathname);
+      if (!matched) throw new HttpError(404, ERROR_CODES.SV_NOT_FOUND);
+      const body = method === 'POST' ? await readJsonBody(req) : undefined;
+      const data = await matched.route.handler({
+        params: matched.params,
+        query: new URLSearchParams(search),
+        body,
+      });
+      sendOk(res, data);
+      outcome = { status: 200 };
+    } catch (err) {
+      outcome = sendError(res, err);
+    }
+    this.deps.logger.debug(
+      { method, path: pathname, status: outcome.status, code: outcome.code, ms: Date.now() - started },
+      'api request',
+    );
+  }
+}
diff --git a/apps/desktop/src/main/services/api-server/views.ts b/apps/desktop/src/main/services/api-server/views.ts
new file mode 100644
index 00000000..4f9677e3
--- /dev/null
+++ b/apps/desktop/src/main/services/api-server/views.ts
@@ -0,0 +1,104 @@
+import type { PragentRunInfo } from '@meebox/ipc';
+import type {
+  LocalPrStatus,
+  PlatformKind,
+  PrDiscoveryFilter,
+  ReviewRunTool,
+  ReviewerStatus,
+  StoredPullRequest,
+} from '@meebox/shared';
+
+/**
+ * PR 列表视图项：`GET /prs` 对外暴露的**精简投影**。这是「请求接口视图层的树结构约束方法」——
+ * 单一投影函数 {@link toPrListItem} 定义列表返回的字段集合与次序，避免直接把整条
+ * StoredPullRequest（含 description 明细、完整人员对象等）泄给列表消费方。
+ *
+ * 收窄原则：
+ * - 只给标识与概览，**去掉 description 明细**（详情走 `GET /prs/{id}`）；
+ * - **人员信息只留 slug**（reviewer 另带 status）；头像 / 展示名等留给详情；
+ * - **字段顺序即输出顺序**：id / title / author / createdAt 优先，再给其余概览字段。
+ */
+export interface PrListItem {
+  /** PR 的本地稳定标识（== StoredPullRequest.localId）；写操作与详情端点均按此定位。 */
+  id: string;
+  title: string;
+  /** 作者 slug（缺失时回退 name）；不含展示名 / 头像。 */
+  author: string;
+  createdAt: string;
+  /** 本人评审决断（pending / approved / needs_work）。 */
+  status: LocalPrStatus;
+  state: 'open' | 'merged' | 'declined';
+  draft: boolean;
+  platform: PlatformKind;
+  /** `projectKey/repoSlug`。 */
+  repo: string;
+  /** 远端平台 PR 编号。 */
+  remoteId: string;
+  updatedAt: string;
+  hasConflict: boolean;
+  /** 远端判定可直接合并（== mergeStatus.canMerge）。 */
+  mergeable: boolean;
+  /** 命中的发现分类（一级 category）。 */
+  categories: PrDiscoveryFilter[];
+  /** 评审人：仅 slug + status。 */
+  reviewers: Array<{ slug: string; status: ReviewerStatus }>;
+  unread: boolean;
+  unreadMentionCount: number;
+}
+
+/**
+ * 某 PR 在运行队列里的一个 pr-agent run 视图项：`GET /prs/{id}/agent/runs` 的投影。用于让调用方
+ * 发现可取消的 run（runId + tool + 运行 / 排队态），配合 `…/runs/{runId}/cancel` 做按 run 取消。
+ */
+export interface PrAgentRunItem {
+  runId: string;
+  tool: ReviewRunTool;
+  /** active = 正在执行；waiting = 排队中。 */
+  state: 'active' | 'waiting';
+  /** 开始执行时间（ISO）；waiting 为 null。 */
+  startedAt: string | null;
+  enqueuedAt: string;
+  question?: string;
+}
+
+/** 从队列快照筛出属于该 PR 的 run（active 在前、waiting 在后），投影为精简项。 */
+export function toPrAgentRuns(
+  queue: { active: PragentRunInfo[]; waiting: PragentRunInfo[] },
+  prId: string,
+): PrAgentRunItem[] {
+  const pick = (r: PragentRunInfo, state: 'active' | 'waiting'): PrAgentRunItem => ({
+    runId: r.runId,
+    tool: r.tool,
+    state,
+    startedAt: r.startedAt,
+    enqueuedAt: r.enqueuedAt,
+    ...(r.question ? { question: r.question } : {}),
+  });
+  return [
+    ...queue.active.filter((r) => r.prLocalId === prId).map((r) => pick(r, 'active')),
+    ...queue.waiting.filter((r) => r.prLocalId === prId).map((r) => pick(r, 'waiting')),
+  ];
+}
+
+/** 把存储态 PR 投影为列表视图项。对象字面量的键序即 JSON 输出顺序（CLI 视图层据此渲染）。 */
+export function toPrListItem(pr: StoredPullRequest): PrListItem {
+  return {
+    id: pr.localId,
+    title: pr.title,
+    author: pr.author.slug ?? pr.author.name,
+    createdAt: pr.createdAt,
+    status: pr.localStatus,
+    state: pr.state,
+    draft: pr.draft,
+    platform: pr.platform,
+    repo: `${pr.repo.projectKey}/${pr.repo.repoSlug}`,
+    remoteId: pr.remoteId,
+    updatedAt: pr.updatedAt,
+    hasConflict: pr.hasConflict,
+    mergeable: pr.mergeStatus?.canMerge === true,
+    categories: pr.discoveryFilters,
+    reviewers: pr.reviewers.map((r) => ({ slug: r.slug ?? r.name, status: r.status })),
+    unread: pr.unread ?? false,
+    unreadMentionCount: pr.unreadMentionCount ?? 0,
+  };
+}
diff --git a/apps/desktop/src/main/services/context.ts b/apps/desktop/src/main/services/context.ts
index 8bc627a5..90b3c9e9 100644
--- a/apps/desktop/src/main/services/context.ts
+++ b/apps/desktop/src/main/services/context.ts
@@ -31,6 +31,8 @@ export interface RegisterDeps {
   /** 重建 adapters/poller 使连接变更热生效（config:setConnections 写盘后调用） */
   reconfigureConnections: () => Promise<void>;
   repoMirror: RepoMirrorManager;
+  /** 重建本地 API 监听器使 service 配置（开关 / host / port）变更热生效（config:setService 写盘后调用）。 */
+  reconfigureApiServer: () => Promise<void>;
 }
 
 /**
diff --git a/apps/desktop/src/main/services/notifications.ts b/apps/desktop/src/main/services/notifications.ts
index c40c9902..09e999da 100644
--- a/apps/desktop/src/main/services/notifications.ts
+++ b/apps/desktop/src/main/services/notifications.ts
@@ -19,11 +19,14 @@ import { ensureAvatarFile, type AvatarFileDeps } from './avatar.js';
 /** 一轮最多单独弹的通知条数（各带定位）；超出部分折叠为一条「查看更多」提示，避免涌入时的通知风暴。 */
 const INDIVIDUAL_LIMIT = 5;
 
-/** 通知事件类型 → i18n 文案分组名（new_pr 的 key 为 newPr，其余同名）。 */
+/** 通知事件类型 → i18n 文案分组名（new_pr 的 key 为 newPr，authored_* 转驼峰，其余同名）。 */
 const I18N_GROUP: Record<PollNotificationEvent['kind'], string> = {
   new_pr: 'newPr',
   mention: 'mention',
   reply: 'reply',
+  authored_comment: 'authoredComment',
+  authored_needs_work: 'authoredNeedsWork',
+  authored_conflict: 'authoredConflict',
 };
 
 /** 类型 emoji（Windows toast 单图标槽给了头像，故类型用 emoji 在标题前标记）。 */
@@ -31,6 +34,9 @@ const TYPE_EMOJI: Record<PollNotificationEvent['kind'], string> = {
   new_pr: '🔀',
   mention: '💬',
   reply: '↩️',
+  authored_comment: '💬',
+  authored_needs_work: '📝',
+  authored_conflict: '⚠️',
 };
 
 /** 点击通知：唤起并聚焦主窗口（最小化则先还原）。 */
@@ -138,6 +144,9 @@ export async function showPollNotifications(
     new_pr: cfg.new_pr,
     reply: cfg.reply,
     mention: cfg.mention,
+    authored_comment: cfg.authored_comment,
+    authored_needs_work: cfg.authored_needs_work,
+    authored_conflict: cfg.authored_conflict,
   };
   const filtered = events.filter((e) => allow[e.kind]);
   if (filtered.length === 0) return;
diff --git a/apps/desktop/src/main/services/pr-agent/run-executor.ts b/apps/desktop/src/main/services/pr-agent/run-executor.ts
index 774ec5ca..15ed6636 100644
--- a/apps/desktop/src/main/services/pr-agent/run-executor.ts
+++ b/apps/desktop/src/main/services/pr-agent/run-executor.ts
@@ -87,7 +87,7 @@ export class RunExecutor {
       return updated ?? { ...run, ...patch };
     };
 
-    const wt = await this.prepareWorkspace(pr);
+    const wt = await this.prepareWorkspace(pr, req.scope);
     try {
       const { env, extraArgs, askLangSuffix } = await this.buildInvocation(
         req,
@@ -254,6 +254,10 @@ export class RunExecutor {
       model: activeLlmForRecord?.model || undefined,
       // 复评引用前向链：随 run 落盘，UI 据此在 /ask 卡上展示「复评自…」徽标 + 裁决动作。
       referencedFinding: req.tool === 'ask' ? req.referencedFinding : undefined,
+      // 触发来源随 run 落盘：user 来源的 run 由 ChatPane 补命令回显气泡；agent 子 run 不回显。
+      origin: item.priority,
+      // 单 commit 评审范围随 run 落盘：结果卡据此展示范围徽标。
+      scope: req.scope,
     });
     // 把入队时 startedAt=null 的 info 升级为 active 形态 + 广播（经调度层）。
     item.info = { ...item.info, startedAt: run.startedAt };
@@ -265,16 +269,25 @@ export class RunExecutor {
     return run;
   }
 
-  /** 阶段②：同步镜像 + 按固定 merge-base 物化 worktree（与 UI diff 同源，评审基于 PR 自分叉的改动）。 */
-  private async prepareWorkspace(pr: QueueItem['pr']) {
+  /**
+   * 阶段②：同步镜像 + 物化 worktree（与 UI diff 同源，评审基于 PR 自分叉的改动）。
+   * 缺省按固定 merge-base 定界 PR 全量（head=PR 源 sha，base=merge-base）；传入单 commit 范围（scope）时
+   * 改按该 commit 自身改动定界（head=scope.sha，base=scope.parent），pr-agent 只见 parent..sha 的 diff。
+   */
+  private async prepareWorkspace(pr: QueueItem['pr'], scope?: QueueItem['req']['scope']) {
     const { repoMirror, pr: prService } = this.ctx;
     const repoId = prService.repoIdentityFor(pr);
     // 走 ensureMirrorReadyForPr（而非裸 syncMirror）：与 UI diff 同源，且复用其自愈——源分支被删 / 强推后
-    // 按平台精确 fetch PR 头引用补齐 head sha，否则 materializeWorktree 建 meebox/head 会因对象缺失失败。
+    // 按平台精确 fetch PR 头引用补齐 head sha，否则 materializeWorktree 建 head 分支会因对象缺失失败。
     await prService.ensureMirrorReadyForPr(pr);
+    if (scope) {
+      // 单 commit 范围：head=目标 commit，base=其父 commit → LOCAL__TARGET_BRANCH 指向 parent，
+      // pr-agent 只见该 commit 自身改动。parent 是 head 的祖先、随镜像同步而在，无需另取。
+      return repoMirror.materializeWorktree(repoId, scope.sha, scope.parent, pr.localId);
+    }
     // pr-agent 的 LOCAL__TARGET_BRANCH 用固定 merge-base，而非 targetRef.sha 漂移后混入别的 PR 的两点对比。
     const diffBase = await prService.resolveDiffBaseSha(pr);
-    return repoMirror.materializeWorktree(repoId, pr.sourceRef.sha, diffBase);
+    return repoMirror.materializeWorktree(repoId, pr.sourceRef.sha, diffBase, pr.localId);
   }
 
   /**
@@ -361,6 +374,10 @@ export class RunExecutor {
       // /ask 代码建议数量软约束（与 /review /improve 共用同一设置）。
       maxCodeSuggestions:
         req.tool === 'ask' ? bootstrap.config.agent.strategy.max_code_suggestions : undefined,
+      // /ask 代码检索指引：仅 CLI 提供方（子进程 cwd 落在完整 worktree、可用文件工具）注入，引导定向检索
+      // （内置只读搜索 / grep 查符号 · 只读所需行段）替代整文件通读，降低 agentic 探索成本。刻意只用只读工具集
+      // （headless default 模式下非只读工具会中止会话，故不诱导 rg）。API 提供方无文件访问、不注入。
+      worktreeRetrieval: req.tool === 'ask' && activeLlm?.provider === 'cli',
     });
     // /ask 的 pr_questions prompt **不渲染 extra_instructions**（与 describe/review/improve 不同），
     // 经 env 注入对 /ask 是死字段。故 /ask 的指令改为拼进「问题」（user turn，见下方 askQuestion），
diff --git a/apps/desktop/src/main/services/pr-agent/run-queue.ts b/apps/desktop/src/main/services/pr-agent/run-queue.ts
index a8f02562..44a3164c 100644
--- a/apps/desktop/src/main/services/pr-agent/run-queue.ts
+++ b/apps/desktop/src/main/services/pr-agent/run-queue.ts
@@ -25,6 +25,7 @@ export interface QueueItem {
     question?: string;
     referencedContext?: string;
     referencedFinding?: ReviewRun['referencedFinding'];
+    scope?: ReviewRun['scope'];
   };
   pr: StoredPullRequest;
   resolve: (run: ReviewRun) => void;
@@ -76,9 +77,12 @@ export class RunQueue {
     priority: RunPriority = 'user',
     referencedContext?: string,
     referencedFinding?: ReviewRun['referencedFinding'],
+    scope?: ReviewRun['scope'],
   ): Promise<ReviewRun> {
     const { logger } = this.ctx;
-    if (tool !== 'ask') {
+    // dedup 仅约束「PR 全量」的同工具重复；/ask 每次问题不同、单 commit 范围（scope）是定向动作，均放行
+    // （允许全量 review 之外再对某 commit 单独 review，互不视作重复）。
+    if (tool !== 'ask' && !scope) {
       const sameTask = (q: QueueItem): boolean =>
         q.info.prLocalId === pr.localId && q.info.tool === tool;
       if ([...this.active.values()].some(sameTask) || this.waiting.some(sameTask)) {
@@ -96,6 +100,8 @@ export class RunQueue {
           prNumber: pr.remoteId,
           tool,
           question: tool === 'ask' ? question : undefined,
+          origin: priority,
+          scope,
           enqueuedAt: new Date().toISOString(),
           startedAt: null,
         },
@@ -107,6 +113,8 @@ export class RunQueue {
           question,
           referencedContext: tool === 'ask' ? referencedContext : undefined,
           referencedFinding: tool === 'ask' ? referencedFinding : undefined,
+          // 单 commit 范围对所有工具生效（不限 ask）：executor 据此物化 parent..sha 的 worktree。
+          scope,
         },
         pr,
         priority,
diff --git a/apps/desktop/src/main/services/pr-service.ts b/apps/desktop/src/main/services/pr-service.ts
index 8a2f2913..b1b35c53 100644
--- a/apps/desktop/src/main/services/pr-service.ts
+++ b/apps/desktop/src/main/services/pr-service.ts
@@ -8,7 +8,12 @@ import {
   writeDiffBaseCache,
 } from '@meebox/poller';
 import type { RepoIdentity, RepoMirrorManager } from '@meebox/repo-mirror';
-import { pullRequestHeadRefspec, type StoredPullRequest } from '@meebox/shared';
+import {
+  AppError,
+  ERROR_CODES,
+  pullRequestHeadRefspec,
+  type StoredPullRequest,
+} from '@meebox/shared';
 import type { PlatformAdapter } from '@meebox/platform-core';
 import type { JsonFileStateStore } from '@meebox/state-store';
 import type { ConnectionRuntime } from '../adapters.js';
@@ -53,7 +58,7 @@ export class PrService {
     if (pr) return pr;
     const archived = await readPrMeta(this.deps.archiveStore, localId);
     if (archived) return archived.pr;
-    throw new Error(`PR not found in local state: ${localId}`);
+    throw new AppError(ERROR_CODES.PR_NOT_FOUND, { localId }, `PR not found in local state: ${localId}`);
   }
 
   /**
diff --git a/apps/desktop/src/renderer/src/App.tsx b/apps/desktop/src/renderer/src/App.tsx
index 3ca14390..cc230b0b 100644
--- a/apps/desktop/src/renderer/src/App.tsx
+++ b/apps/desktop/src/renderer/src/App.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
+import type { ReviewRunCommitScope } from '@meebox/shared';
 import { invoke } from './api';
 import { ChatPane } from './components/features/chat';
 import { MainPane } from './components/layout/MainPane';
@@ -81,6 +82,12 @@ export default function App() {
   }, []);
   // PR 状态筛选（待处理 / 全部 / 冲突 / 可合并等）：提升到 App 以便命令面板亦可驱动、折叠侧栏不丢选择。
   const [statusFilter, setStatusFilter] = useState<FilterKey>('pending');
+  // 当前 Diff 视图选中的单 commit 范围（DiffView 上报）：作为聊天区命令的隐式范围（见 ChatPane）。
+  // 按 sha 去重，避免 DiffView 每次 render 传新对象引发的重渲染回环。
+  const [viewCommitScope, setViewCommitScope] = useState<ReviewRunCommitScope | null>(null);
+  const handleViewCommitScope = useCallback((s: ReviewRunCommitScope | null) => {
+    setViewCommitScope((prev) => (prev?.sha === s?.sha ? prev : s));
+  }, []);
   // PR 导航 / 范围领域（发现分类 / 活跃·归档切换 / 归档懒加载 / 按 URL 打开 / 定位跳转 / 通知点击导航 +
   // 跨组件 Diff·Tab 跳转意图）——领域逻辑归 usePrNavigation；选中态 / 已读仍由 usePullRequests 拥有。
   const {
@@ -203,6 +210,7 @@ export default function App() {
         {!sidebarCollapsed && (
           <Sidebar
             prs={displayedPrs}
+            activePrs={prs}
             selectedId={selectedId}
             onSelect={(pr) => {
               setSelectedId(pr.localId);
@@ -240,6 +248,7 @@ export default function App() {
               onRequestDiffNav={(target) => setPendingDiffNav(target)}
               pendingTab={pendingTab}
               onPendingTabConsumed={() => setPendingTab(null)}
+              onViewCommitScopeChange={handleViewCommitScope}
             />
           ) : (
             <PrEmpty hasConnections={boot.config.connections.length > 0} />
@@ -262,6 +271,7 @@ export default function App() {
           currentLlmModel={
             boot.config.llm.profiles.find((p) => p.id === boot.config.llm.active_id)?.model ?? null
           }
+          viewCommitScope={viewCommitScope}
         />
       </div>
       <StatusBar
diff --git a/apps/desktop/src/renderer/src/components/common/Modal.tsx b/apps/desktop/src/renderer/src/components/common/Modal.tsx
index a09ce85d..5819e5ff 100644
--- a/apps/desktop/src/renderer/src/components/common/Modal.tsx
+++ b/apps/desktop/src/renderer/src/components/common/Modal.tsx
@@ -28,6 +28,8 @@ interface ModalProps {
   titleId?: string;
   /** header 右侧关闭按钮样式：图标按钮 / 文案按钮（不传则无） */
   headerClose?: 'icon' | 'text';
+  /** header 右侧、关闭键左侧的自定义动作（如「打开目录」按钮）；与关闭键同组右对齐。 */
+  headerActions?: ReactNode;
   /** modal-body 追加类名（如 confirm-body） */
   bodyClassName?: string;
   /** 底部 footer 区内容（作为 modal-body 的兄弟渲染）；不传则无 footer 区 */
@@ -54,6 +56,7 @@ export function Modal({
   title,
   titleId,
   headerClose,
+  headerActions,
   bodyClassName,
   footer,
   footerClassName = 'modal-footer-bar',
@@ -86,21 +89,26 @@ export function Modal({
         {title !== undefined && (
           <div className="modal-header">
             <h3 id={titleId}>{title}</h3>
-            {headerClose === 'icon' && (
-              <button
-                className="icon-btn modal-close"
-                type="button"
-                onClick={onClose}
-                aria-label={t('common.close')}
-                title={t('common.close')}
-              >
-                <CloseIcon />
-              </button>
-            )}
-            {headerClose === 'text' && (
-              <button className="btn" type="button" onClick={onClose}>
-                {t('common.close')}
-              </button>
+            {(headerActions !== undefined || headerClose) && (
+              <div className="modal-header-right">
+                {headerActions}
+                {headerClose === 'icon' && (
+                  <button
+                    className="icon-btn modal-close"
+                    type="button"
+                    onClick={onClose}
+                    aria-label={t('common.close')}
+                    title={t('common.close')}
+                  >
+                    <CloseIcon />
+                  </button>
+                )}
+                {headerClose === 'text' && (
+                  <button className="btn" type="button" onClick={onClose}>
+                    {t('common.close')}
+                  </button>
+                )}
+              </div>
             )}
           </div>
         )}
diff --git a/apps/desktop/src/renderer/src/components/common/icons.tsx b/apps/desktop/src/renderer/src/components/common/icons.tsx
index f4ce5c7e..7fa94b40 100644
--- a/apps/desktop/src/renderer/src/components/common/icons.tsx
+++ b/apps/desktop/src/renderer/src/components/common/icons.tsx
@@ -256,6 +256,15 @@ export function ShareIcon({ size = 14 }: IconProps) {
   );
 }
 
+/** 拼图块（extension / plugin）：集成 / 扩展 的通用隐喻。设置「集成」分区导航用。 */
+export function PuzzleIcon({ size = 14 }: IconProps) {
+  return (
+    <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <path d="M20.5 11H19V7c0-1.1-.9-2-2-2h-4V3.5C13 2.12 11.88 1 10.5 1S8 2.12 8 3.5V5H4c-1.1 0-1.99.9-1.99 2v3.8H3.5c1.49 0 2.7 1.21 2.7 2.7s-1.21 2.7-2.7 2.7H2V19c0 1.1.9 2 2 2h3.8v-1.5c0-1.49 1.21-2.7 2.7-2.7 1.49 0 2.7 1.21 2.7 2.7V21H17c1.1 0 2-.9 2-2v-4h1.5c1.38 0 2.5-1.12 2.5-2.5S21.88 11 20.5 11z" />
+    </svg>
+  );
+}
+
 /** 评论：带文字行的对话气泡。finding 卡「编辑成评论草稿」动作用（与 ChatIcon 区分：内含文字行）。 */
 export function CommentIcon({ size = 14 }: IconProps) {
   return (
diff --git a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
index 55a88dd7..31b6c4c3 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/ChatPane.tsx
@@ -5,6 +5,7 @@ import type {
   LocalPrStatus,
   PrAgentStatus,
   ReviewRun,
+  ReviewRunCommitScope,
   StoredPullRequest,
 } from '@meebox/shared';
 import { ChatIcon, TrashIcon, ConfirmModal, PaneLoading } from '../../common';
@@ -70,6 +71,12 @@ interface ChatPaneProps {
   llmConfigured?: boolean;
   /** 打开设置面板（LLM 未配置提示里的「去设置」按钮用） */
   onOpenSettings?: () => void;
+  /**
+   * 当前 Diff 视图选中的单 commit 范围（无 / root commit 为 null）：作为本 PR 聊天区命令的**隐式范围**——
+   * 直接键入的 /describe /review /improve /ask 自动限定在该 commit（输入栏显示可撤销范围 chip）。撤销该 chip
+   * 后本会话不再随视图范围（直到切换到别的 commit）。auto review 微流程不受此影响、恒作用于 PR 全量。
+   */
+  viewCommitScope?: ReviewRunCommitScope | null;
 }
 
 /**
@@ -94,6 +101,7 @@ export function ChatPane({
   currentLlmModel,
   llmConfigured = true,
   onOpenSettings,
+  viewCommitScope,
 }: ChatPaneProps) {
   const { t } = useTranslation();
   const startResize = (e: React.MouseEvent): void => {
@@ -139,10 +147,18 @@ export function ChatPane({
 
   // 复评引用态：点 finding「引用」→ 仅挂到输入栏（chip）；不自动填写问题，用户自行输入。发送时携带该引用。
   const [refFinding, setRefFinding] = useState<{ finding: Finding; run: ReviewRun } | null>(null);
-  // PR 切换清掉引用态，避免跨 PR 残留。
+  // 「脱离视图范围」态：用户 ✕ 掉范围 chip 后，本会话命令不再随 Diff 视图选中的 commit（直到切到别的 commit
+  // 或切 PR 才复位）。默认跟随视图范围。
+  const [scopeDetached, setScopeDetached] = useState(false);
+  // PR 切换清掉引用态、复位脱离态，避免跨 PR 残留。
   useEffect(() => {
     setRefFinding(null);
+    setScopeDetached(false);
   }, [prLocalId]);
+  // 切到别的 commit（或清空视图范围）时复位脱离态：新选中的 commit 重新作为隐式范围生效。
+  useEffect(() => {
+    setScopeDetached(false);
+  }, [viewCommitScope?.sha]);
   const onReferenceFinding = (finding: Finding, run: ReviewRun): void => {
     setRefFinding({ finding, run });
   };
@@ -153,6 +169,11 @@ export function ChatPane({
   const referencedContext =
     diffSelection && !selectionIgnored ? formatReferencedContext(diffSelection) : undefined;
 
+  // 本 PR 聊天区命令的生效范围：跟随 Diff 视图选中的 commit，除非用户已脱离（scopeDetached）。
+  // 同一时刻只允许一个 scope 生效——存在 Diff 选区时以选区为准（更细粒度），commit 范围暂挂起、其 chip
+  // 亦隐藏（见 commitScopeChip），取消选区后自动还原。
+  const effectiveScope = diffSelection || scopeDetached ? null : (viewCommitScope ?? null);
+
   // 会话态 + 生命周期（切 PR 重载 / 流式步骤 / 分页 / 自动滚动）
   const session = useChatSession(prLocalId, myActiveIds);
 
@@ -199,6 +220,12 @@ export function ChatPane({
     setRefFinding(null);
   };
 
+  // 发送一条限定在当前视图 commit 的 /ask：把生效范围随问题带下去（限定 parent..sha 的 diff）。
+  const sendScopedAsk = (q: string): void => {
+    if (!effectiveScope) return;
+    void actions.handleRun('ask', q, undefined, undefined, effectiveScope);
+  };
+
   // 历史时间线归并 + 「思考中」实时计时锚点
   const { timeline, thinkingSince } = useChatTimeline({
     visibleRuns,
@@ -352,6 +379,7 @@ export function ChatPane({
                 tool={entry.active.tool}
                 runId={entry.active.runId}
                 question={entry.active.question}
+                scope={entry.active.scope}
                 lines={linesByRunId.get(entry.active.runId) ?? []}
                 startedAt={new Date(entry.active.startedAt ?? entry.active.enqueuedAt).getTime()}
                 model={currentLlmModel ?? null}
@@ -403,13 +431,29 @@ export function ChatPane({
             sendReferencedAsk(q ?? '');
             return;
           }
-          void actions.handleRun(tool, q, tool === 'ask' ? referencedContext : undefined);
+          if (tool === 'ask' && effectiveScope) {
+            sendScopedAsk(q ?? '');
+            return;
+          }
+          // describe/review/improve 亦跟随视图 commit 范围（effectiveScope）；无范围时为 PR 全量。
+          void actions.handleRun(
+            tool,
+            q,
+            tool === 'ask' ? referencedContext : undefined,
+            undefined,
+            tool === 'ask' ? undefined : (effectiveScope ?? undefined),
+          );
         }}
         onAgentAsk={(q) => {
           if (refFinding) {
             sendReferencedAsk(q);
             return;
           }
+          // 视图选中某 commit 时，自然语言提问也走该 commit 范围的 /ask（限定该 commit 的 diff）。
+          if (effectiveScope) {
+            sendScopedAsk(q);
+            return;
+          }
           void actions.handleAgentAsk(q, referencedContext);
         }}
         onCancel={hasMyActive || agentRunningHere ? actions.handleStopAll : undefined}
@@ -436,6 +480,21 @@ export function ChatPane({
               }
             : null
         }
+        // 单 commit 范围 chip：视图选中某 commit 时显示（选中态源自视图）；点击切换启用/禁用——
+        // 禁用（scopeDetached）时命令回到 PR 全量、chip 置灰，切到别的 commit 或切 PR 复位为启用。
+        // 同一时刻只允许一个 scope：存在 Diff 选区时让位于选区 chip（隐藏本 chip），取消选区后自动还原。
+        commitScopeChip={
+          viewCommitScope && !diffSelection
+            ? {
+                // 仅展示短 hash，不带主题（避免 chip 内容过长）；主题在 Diff 视图与结果卡徽标已可见。
+                label: viewCommitScope.abbreviatedSha,
+                disabled: scopeDetached,
+                onToggle: () => {
+                  setScopeDetached((d) => !d);
+                },
+              }
+            : null
+        }
       />
 
       {showRulePreview && matchedRules.length > 0 && (
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx
index 0f560450..a2e15fd5 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/ChatInputBar.tsx
@@ -5,7 +5,14 @@ import type {
   ReviewRunTool,
   StoredPullRequest,
 } from '@meebox/shared';
-import { AutoReviewIcon, EyeOffIcon, FileTreeIcon, SendIcon, StopIcon } from '../../../common';
+import {
+  AutoReviewIcon,
+  CommitIcon,
+  EyeOffIcon,
+  FileTreeIcon,
+  SendIcon,
+  StopIcon,
+} from '../../../common';
 import { useChatInput } from '../hooks/useChatInput';
 import { useTextareaAutosizeDrag } from '../hooks/useTextareaAutosizeDrag';
 
@@ -48,6 +55,11 @@ interface ChatInputBarProps {
   onToggleSelection: () => void;
   /** 复评引用 chip：引用了某条 finding 时展示「复评 <file:line>」+ 清除；null = 不渲染。 */
   referenceChip?: { label: string; onClear: () => void } | null;
+  /**
+   * 单 commit 范围 chip：跟随 Diff 视图选中的 commit 展示「短 SHA · 主题」。存在选中即显示，点击**切换启用/禁用**
+   * （禁用不删除 chip，本会话命令回到 PR 全量；禁用态置灰 + eye-slash）——选中态源自视图，可手动禁用。
+   */
+  commitScopeChip?: { label: string; disabled: boolean; onToggle: () => void } | null;
 }
 
 /**
@@ -74,6 +86,7 @@ export function ChatInputBar({
   selectionIgnored,
   onToggleSelection,
   referenceChip,
+  commitScopeChip,
 }: ChatInputBarProps) {
   const { t } = useTranslation();
   const {
@@ -268,6 +281,26 @@ export function ChatInputBar({
               </span>
             </>
           )}
+          {/* 单 commit 范围 chip：跟随视图选中的 commit 展示「短 SHA · 主题」。点击切换启用/禁用（不删除）——
+              启用时命令限定在该 commit（parent..sha），禁用则回到 PR 全量、置灰 + eye-slash。 */}
+          {commitScopeChip && (
+            <>
+              <span className="chat-cmd-divider" aria-hidden="true" />
+              <button
+                type="button"
+                className={`chat-selection-chip${commitScopeChip.disabled ? ' ignored' : ''}`}
+                onClick={commitScopeChip.onToggle}
+                title={
+                  commitScopeChip.disabled
+                    ? t('chatPane.scopeDisabledTitle')
+                    : t('chatPane.scopeActiveTitle')
+                }
+              >
+                {commitScopeChip.disabled ? <EyeOffIcon /> : <CommitIcon size={14} />}
+                <span>{commitScopeChip.label}</span>
+              </button>
+            </>
+          )}
         </div>
         {/* 队列模型下 send 永远在 (新提交进队列)；本 PR active 时 stop 紧贴 send 左侧。
             包到一个 group 里避免 input-row 的 space-between 把 stop 推到中央 */}
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/RulePreviewModal.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/RulePreviewModal.tsx
index 75337498..aa1d63c8 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/RulePreviewModal.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/RulePreviewModal.tsx
@@ -3,8 +3,9 @@ import { useTranslation } from 'react-i18next';
 import ReactMarkdown from 'react-markdown';
 import remarkBreaks from 'remark-breaks';
 import remarkGfm from 'remark-gfm';
-import { Modal, mermaidComponents } from '../../../common';
+import { FolderIcon, Modal, mermaidComponents } from '../../../common';
 import { REMOTE_REHYPE_PLUGINS } from '../../../../lib/markdown';
+import { invoke } from '../../../../api';
 import type { MatchedRules } from '../types';
 
 /**
@@ -27,9 +28,20 @@ export function RulePreviewModal({
       title={
         multi
           ? t('chatPane.rulePreviewTitleMulti', { n: rules.length })
-          : t('chatPane.rulePreviewTitle', { id: rules[0]?.id ?? '' })
+          : t('chatPane.rulePreviewTitle')
       }
       headerClose="text"
+      headerActions={
+        <button
+          type="button"
+          className="btn btn-icon"
+          onClick={() => void invoke('app:openAgentDir', undefined)}
+          title={t('chatPane.ruleOpenAgentDir')}
+          aria-label={t('chatPane.ruleOpenAgentDir')}
+        >
+          <FolderIcon />
+        </button>
+      }
       ariaLabel={t('chatPane.rulePreviewAria')}
     >
       {rules.map((rule, i) => (
@@ -41,10 +53,13 @@ export function RulePreviewModal({
           )}
           <div className="modal-kv">
             <div className="modal-kv-key">{t('chatPane.ruleFilePath')}</div>
-            <div className="modal-kv-val">{rule.filePath}</div>
-            <div className="modal-kv-key">priority</div>
+            {/* 相对 Agent 目录展示（`rules/<id>`），避免暴露冗长的机器绝对路径；打开目录按钮在标题栏统一提供。 */}
+            <div className="modal-kv-val">
+              <code>rules/{rule.id}</code>
+            </div>
+            <div className="modal-kv-key">{t('chatPane.rulePriority')}</div>
             <div className="modal-kv-val">{rule.priority}</div>
-            <div className="modal-kv-key">tools</div>
+            <div className="modal-kv-key">{t('chatPane.ruleTools')}</div>
             <div className="modal-kv-val">{rule.tools.join(', ')}</div>
           </div>
           <div className="markdown" style={{ marginTop: 12 }}>
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx
index 2bc1f90c..4e62bd39 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/RunResultView.tsx
@@ -1,7 +1,7 @@
 import { useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import type { Finding, FindingClosure, ReviewDraft, ReviewRun } from '@meebox/shared';
-import { RepeatIcon, RetryIcon, ShareIcon, TrashIcon } from '../../../common';
+import { CommitIcon, RepeatIcon, RetryIcon, ShareIcon, TrashIcon } from '../../../common';
 import { orderFindings } from '../utils/findings';
 import { formatStartTime, runStatusLabel } from '../utils/format';
 import { extractTokenUsage, type TokenUsage } from '../utils/tokens';
@@ -30,6 +30,17 @@ function RunMeta({ run, onDelete }: { run: ReviewRun; onDelete: () => void }) {
       <span className={`chat-chip chat-run-status chat-run-status-${run.status}`}>
         {runStatusLabel(run.status, t)}
       </span>
+      {/* 单 commit 评审范围徽标：本次 run 限定在某 commit 自身改动（parent..sha）时展示短 SHA；
+          全量 PR 范围（无 scope）不渲染。 */}
+      {run.scope && (
+        <span
+          className="chat-chip chat-chip-quiet chat-chip-neutral chat-run-scope"
+          title={t('chatPane.scopeCommitTitle', { subject: run.scope.subject })}
+        >
+          <CommitIcon size={12} />
+          {run.scope.abbreviatedSha}
+        </span>
+      )}
       {/* 模型 chip 取代运行时策略 chip — strategy 是部署细节用户不
           关心，model 是真正影响 review 质量的变量 */}
       {run.model && (
diff --git a/apps/desktop/src/renderer/src/components/features/chat/components/RunningView.tsx b/apps/desktop/src/renderer/src/components/features/chat/components/RunningView.tsx
index eb07e442..087de70b 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/components/RunningView.tsx
+++ b/apps/desktop/src/renderer/src/components/features/chat/components/RunningView.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import type { ReviewRunTool } from '@meebox/shared';
+import type { ReviewRunCommitScope, ReviewRunTool } from '@meebox/shared';
+import { CommitIcon } from '../../../common';
 import { formatElapsed, formatStartTime, inferPhase, runStatusLabel } from '../utils/format';
 import { AnsiPre, AskQuestion, Spinner } from './shared';
 
@@ -8,6 +9,7 @@ export function RunningView({
   tool,
   runId,
   question,
+  scope,
   lines,
   startedAt,
   model,
@@ -16,6 +18,8 @@ export function RunningView({
   runId: string;
   /** /ask 的提问：执行中也直接展示（与排队 / 完成态一致；问题在派发时已生成）。 */
   question?: string;
+  /** 单 commit 评审范围（parent..sha）；限定在某 commit 时展示范围徽标，与完成态卡片一致。 */
+  scope?: ReviewRunCommitScope;
   lines: ReadonlyArray<string>;
   startedAt: number;
   /** 当前 active LLM profile.model — 跟 RunMeta 同源放在 chip 行，让 running
@@ -52,6 +56,16 @@ export function RunningView({
           <Spinner />
           {runStatusLabel('running', t)}
         </span>
+        {/* 单 commit 范围徽标：与完成态 RunMeta 一致，让运行中也能看到本次限定的提交。 */}
+        {scope && (
+          <span
+            className="chat-chip chat-chip-quiet chat-chip-neutral chat-run-scope"
+            title={t('chatPane.scopeCommitTitle', { subject: scope.subject })}
+          >
+            <CommitIcon size={12} />
+            {scope.abbreviatedSha}
+          </span>
+        )}
         {model && (
           <span
             className="chat-chip chat-chip-quiet chat-chip-neutral chat-run-model"
diff --git a/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatActions.ts b/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatActions.ts
index 9717128b..42bac0ea 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatActions.ts
+++ b/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatActions.ts
@@ -55,6 +55,7 @@ export interface ChatActions {
     question?: string,
     referencedContext?: string,
     referencedFinding?: ReviewRun['referencedFinding'],
+    scope?: ReviewRun['scope'],
   ) => Promise<void>;
   handleAgentReview: () => Promise<void>;
   handleAgentAsk: (question: string, referencedContext?: string) => Promise<void>;
@@ -115,12 +116,14 @@ export function useChatActions(params: UseChatActionsParams): ChatActions {
     question?: string,
     referencedContext?: string,
     referencedFinding?: ReviewRun['referencedFinding'],
+    scope?: ReviewRun['scope'],
   ): Promise<void> => {
     if (!pr || !prAgent.available || !llmConfigured) return;
     // 去重（即时反馈）：同一 PR 同一工具已在执行 / 排队 → 阻止重复触发（main 端亦有
-    // 权威校验兜底）。/ask 每次问题不同，不限制。
+    // 权威校验兜底）。/ask 每次问题不同、单 commit 范围（scope）是定向动作，均不限制（与后端 dedup 同口径）。
     if (
       tool !== 'ask' &&
+      !scope &&
       (myActiveRuns.some((r) => r.tool === tool) || myWaiting.some((w) => w.tool === tool))
     ) {
       setError(t('chatPane.duplicateRun', { tool }));
@@ -134,6 +137,7 @@ export function useChatActions(params: UseChatActionsParams): ChatActions {
         question,
         referencedContext,
         referencedFinding,
+        scope,
       });
     } catch (e) {
       setError(e instanceof Error ? e.message : String(e));
@@ -267,7 +271,8 @@ export function useChatActions(params: UseChatActionsParams): ChatActions {
     if (agentRunningHere && prLocalId) void invoke('agent:stop', { localId: prLocalId });
   };
   const handleRetry = (run: ReviewRun): void => {
-    void handleRun(run.tool, run.question);
+    // 重试沿用原 run 的单 commit 范围（若有），保证复跑仍限定同一 commit。
+    void handleRun(run.tool, run.question, undefined, undefined, run.scope);
   };
 
   /**
diff --git a/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatTimeline.ts b/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatTimeline.ts
index ff9a8121..7c63da19 100644
--- a/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatTimeline.ts
+++ b/apps/desktop/src/renderer/src/components/features/chat/hooks/useChatTimeline.ts
@@ -17,6 +17,18 @@ function ms(iso: string | null | undefined): number {
   return Number.isFinite(n) ? n : 0;
 }
 
+/**
+ * 用户直接发起的斜杠命令的回显文案：/ask 显示问题正文（更贴近对话；空问题回退 `/ask`），
+ * describe/review/improve 显示 `/工具名`。仅用于命令回显气泡，不做 i18n（就是用户键入的命令）。
+ */
+function echoContent(tool: string, question: string | undefined): string {
+  if (tool === 'ask') {
+    const q = question?.trim();
+    if (q) return q;
+  }
+  return `/${tool}`;
+}
+
 /**
  * 历史时间线 + 实时「思考中」计时锚点。
  *
@@ -70,7 +82,30 @@ export function useChatTimeline(params: {
       sortTime: ms(m.at),
       message: m as AgentMessage | null,
     }));
-    return [...runEntries, ...activeEntries, ...stepEntries, ...msgEntries].sort(
+    // 命令回显气泡：仅对**用户直接发起**（origin==='user'）的 run 补一条 user 消息，紧贴其卡片之上
+    // （sortTime 取起跑时刻 -1ms）。编排 / AutoPilot 子 run（origin==='agent'）不回显——其用户输入已由
+    // 编排会话的用户消息承载。历史 run 无 origin（undefined）→ 不回显。active 与完成态同一 runId 互斥，
+    // key 统一为 `echo-<runId>`，运行中→完成的切换平滑不重挂。
+    const echoOf = (
+      runId: string,
+      tool: string,
+      question: string | undefined,
+      anchorMs: number,
+    ) => ({
+      ...base,
+      key: `echo-${runId}`,
+      sortTime: anchorMs - 1,
+      message: { role: 'user', content: echoContent(tool, question), at: '' } as AgentMessage,
+    });
+    const echoEntries = [
+      ...visibleRuns
+        .filter((r) => r.origin === 'user')
+        .map((r) => echoOf(r.id, r.tool, r.question, ms(r.startedAt))),
+      ...myActiveRuns
+        .filter((a) => a.origin === 'user')
+        .map((a) => echoOf(a.runId, a.tool, a.question, ms(a.startedAt ?? a.enqueuedAt))),
+    ];
+    return [...runEntries, ...activeEntries, ...stepEntries, ...msgEntries, ...echoEntries].sort(
       (a, b) => a.sortTime - b.sortTime,
     );
   }, [visibleRuns, myActiveRuns, agentSteps, messages]);
diff --git a/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx b/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx
index 99ea3800..e230efd0 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/PrPanel.tsx
@@ -5,6 +5,7 @@ import type {
   PlatformCapabilities,
   PrCommentAnchor,
   PrCommit,
+  ReviewRunCommitScope,
   StoredPullRequest,
 } from '@meebox/shared';
 import { invoke } from '../../../api';
@@ -47,6 +48,8 @@ export interface PrPanelProps {
   /** 外部请求切到指定标签（如通知点击 summary 评论 → 'activity'）；消费后经 onPendingTabConsumed 清空。 */
   pendingTab?: PrTab | null;
   onPendingTabConsumed?: () => void;
+  /** Diff 视图当前查看的单 commit 范围变化上报（→ App → ChatPane 隐式范围）；全部变更 / root commit 为 null。 */
+  onViewCommitScopeChange?: (scope: ReviewRunCommitScope | null) => void;
 }
 
 /**
@@ -68,6 +71,7 @@ export function PrPanel({
   onRequestDiffNav,
   pendingTab,
   onPendingTabConsumed,
+  onViewCommitScopeChange,
 }: PrPanelProps) {
   const { t } = useTranslation();
   const [tab, setTab] = useState<PrTab>('diff');
@@ -211,6 +215,7 @@ export function PrPanel({
               onNavConsumed={onDiffNavConsumed}
               pendingCommitView={pendingCommitView}
               onCommitViewConsumed={() => setPendingCommitView(null)}
+              onViewCommitScopeChange={onViewCommitScopeChange}
             />
           </Suspense>
         </KeepAliveTab>
diff --git a/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts b/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
index b68ed20e..d8a158b8 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
+++ b/apps/desktop/src/renderer/src/components/features/pr/hooks/usePullRequests.ts
@@ -35,12 +35,19 @@ export function usePullRequests({ notifyError }: { notifyError: (msg: string) =>
     }
   }, [refreshing, reloadPrs]);
 
-  // 标记 PR 已读：用户打开 PR 时调用。先乐观清掉本地未读圆点（即时反馈），再持久化已读水位——
+  // 标记 PR 已读：用户打开 PR 时调用。先乐观清掉本地未读标志（即时反馈），再持久化已读水位——
   // 下一轮 poll 不会因旧事件把它标回。每次选中都发 IPC：打开 PR 非高频，且推进已读水位本就是对的；
   // 不靠 setState 更新器的副作用判断「是否未读」——更新器在渲染阶段才跑，同步读其副作用拿不到结果。
+  // 未读标志有两处：`unread` 圆点与 `unreadMentionCount`「@我/回复我」计数 chip（二者在标题槽位互斥、
+  // 计数优先）。两者都要乐观清零 —— 否则计数 chip 会残留到下一轮 poll 重算 lastReadAt 才消失，
+  // 表现为「点开 PR 后未读计数不消除」（与后端 markPrRead 落盘的 unread:false / unreadMentionCount:0 对齐）。
   const markRead = useCallback(async (localId: string): Promise<void> => {
     setPrs((prev) =>
-      prev.map((p) => (p.localId === localId && p.unread ? { ...p, unread: false } : p)),
+      prev.map((p) =>
+        p.localId === localId && (p.unread || (p.unreadMentionCount ?? 0) > 0)
+          ? { ...p, unread: false, unreadMentionCount: 0 }
+          : p,
+      ),
     );
     try {
       await invoke('prs:markRead', { localId });
diff --git a/apps/desktop/src/renderer/src/components/features/pr/statusbar/PrsCountChip.tsx b/apps/desktop/src/renderer/src/components/features/pr/statusbar/PrsCountChip.tsx
index 563d6731..cf68d2ff 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/statusbar/PrsCountChip.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/statusbar/PrsCountChip.tsx
@@ -6,7 +6,6 @@ export function PrsCountChip({ count }: { count: number }) {
   const { t } = useTranslation();
   return (
     <StatusChip
-      tone="ok"
       className="statusbar-chip-prs"
       title={t('statusBar.pendingPrsCount', { n: count })}
       ariaLabel={`PRs ${String(count)}`}
diff --git a/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/DiffView.tsx b/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/DiffView.tsx
index 259405a8..76d12d84 100644
--- a/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/DiffView.tsx
+++ b/apps/desktop/src/renderer/src/components/features/pr/tabs/diff/DiffView.tsx
@@ -4,7 +4,11 @@ import '../../../../../lib/monaco-setup';
 import { useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { type editor as MonacoEditor } from 'monaco-editor';
-import type { PlatformCapabilities, StoredPullRequest } from '@meebox/shared';
+import type {
+  PlatformCapabilities,
+  ReviewRunCommitScope,
+  StoredPullRequest,
+} from '@meebox/shared';
 import { useDraftsForPr } from '../../../../../stores/drafts-store';
 import { ErrorBoundary, PaneLoading, FileTreeIcon, SearchIcon } from '../../../../common';
 import { DiffSearchPanel } from './DiffSearchPanel';
@@ -63,6 +67,11 @@ interface DiffViewProps {
    */
   pendingCommitView?: PendingCommitView | null;
   onCommitViewConsumed?: () => void;
+  /**
+   * 当前变更范围切到 / 离开单 commit 时上报（commit 有父 → 传该 commit 范围，全部变更 / root commit → null）。
+   * 上层（App）据此把「正在查看的 commit」作为聊天区命令的隐式范围（见 ChatPane viewCommitScope）。
+   */
+  onViewCommitScopeChange?: (scope: ReviewRunCommitScope | null) => void;
 }
 
 /**
@@ -81,6 +90,7 @@ export function DiffView({
   onNavConsumed,
   pendingCommitView,
   onCommitViewConsumed,
+  onViewCommitScopeChange,
 }: DiffViewProps) {
   // 评论换行策略：GitHub/Bitbucket hard-break（单 \n → <br>）；GitLab CommonMark 软换行。
   // 能力位缺省（旧数据/无连接）回退 true，保持既有行为。
@@ -101,6 +111,21 @@ export function DiffView({
     pendingCommitView,
     onCommitViewConsumed,
   );
+  // 把「正在查看的单 commit」上报给上层，作为聊天区命令的隐式范围。commit 有父才可 parent..sha 定界；
+  // 全部变更 / root commit（无父）上报 null。
+  useEffect(() => {
+    if (!onViewCommitScopeChange) return;
+    onViewCommitScopeChange(
+      scope.kind === 'commit' && scope.parent
+        ? {
+            sha: scope.sha,
+            parent: scope.parent,
+            abbreviatedSha: scope.abbreviatedSha,
+            subject: scope.subject,
+          }
+        : null,
+    );
+  }, [scope, onViewCommitScopeChange]);
   const { files, filesError, retryFiles, selectedKey, setSelectedKey, selected, loadedKey } =
     useChangedFiles(pr, range, viewKey);
   // 合并会冲突的文件路径集合（仅 pr.hasConflict 时实拉），文件树据此标三角警示。
diff --git a/apps/desktop/src/renderer/src/components/features/settings/SettingsModal.tsx b/apps/desktop/src/renderer/src/components/features/settings/SettingsModal.tsx
index 9dbfc857..e52a22a9 100644
--- a/apps/desktop/src/renderer/src/components/features/settings/SettingsModal.tsx
+++ b/apps/desktop/src/renderer/src/components/features/settings/SettingsModal.tsx
@@ -7,6 +7,7 @@ import {
   CpuIcon,
   GlobeIcon,
   Modal,
+  PuzzleIcon,
   QuestionIcon,
   RobotIcon,
   SettingsIcon,
@@ -26,6 +27,7 @@ import { LlmContextSection } from './sections/LlmContextSection';
 import { ConcurrencySection } from './sections/ConcurrencySection';
 import { AgentStrategySection } from './sections/AgentStrategySection';
 import { ProxySection } from './sections/ProxySection';
+import { ServiceSection } from './sections/ServiceSection';
 import { AgentDirSection } from './sections/AgentDirSection';
 import { WorkDirSection } from './sections/WorkDirSection';
 import { CacheDirSection } from './sections/CacheDirSection';
@@ -38,6 +40,7 @@ export type SettingsCategory =
   | 'model'
   | 'agent'
   | 'notifications'
+  | 'integration'
   | 'about';
 
 /**
@@ -54,6 +57,7 @@ const SETTINGS_CATEGORIES: ReadonlyArray<{
   { id: 'model', labelKey: 'settings.catModel', Icon: CpuIcon },
   { id: 'agent', labelKey: 'settings.catAgent', Icon: RobotIcon },
   { id: 'notifications', labelKey: 'settings.catNotifications', Icon: BellIcon },
+  { id: 'integration', labelKey: 'settings.catIntegration', Icon: PuzzleIcon },
   { id: 'about', labelKey: 'settings.catAbout', Icon: QuestionIcon },
 ];
 
@@ -129,6 +133,8 @@ export function SettingsModal({
       <Modal
         size="lg"
         onClose={onClose}
+        // 有未保存草稿时点背景误关会丢配置：设置页禁用背景点击关闭，仅右上角关闭键（或保存成功）退出。
+        closeOnBackdrop={false}
         title={t('settings.title')}
         headerClose="icon"
         bodyClassName="settings-modal-body"
@@ -252,6 +258,13 @@ export function SettingsModal({
             {category === 'notifications' && (
               <NotificationSection value={s.notifications} onChange={s.setNotifications} />
             )}
+            {category === 'integration' && (
+              <ServiceSection
+                value={s.service}
+                onChange={s.setService}
+                onRegenerateToken={() => void s.regenerateServiceToken()}
+              />
+            )}
             {category === 'about' && (
               <>
                 <WorkDirSection paths={paths} />
diff --git a/apps/desktop/src/renderer/src/components/features/settings/hooks/useSettingsDraft.ts b/apps/desktop/src/renderer/src/components/features/settings/hooks/useSettingsDraft.ts
index 4c3467a9..32d8e1f4 100644
--- a/apps/desktop/src/renderer/src/components/features/settings/hooks/useSettingsDraft.ts
+++ b/apps/desktop/src/renderer/src/components/features/settings/hooks/useSettingsDraft.ts
@@ -63,6 +63,9 @@ export function useSettingsDraft({
   // 代理在独立模态框里编辑：null=关闭，非 null=正在编辑的草稿；保存回 proxy，底栏「保存」才写盘。
   const [proxyEditor, setProxyEditor] = useState<Config['proxy'] | null>(null);
 
+  // 本地 API 服务监听（开关 / host / port 随整体保存；token 经 generateServiceToken 立即写盘）。
+  const [service, setServiceState] = useState<Config['service']>(config.service);
+
   // 连接：多条可配置 + 单选启用；编辑只改本地 state，整体保存才写盘 + 热重建
   const [connections, setConnections] = useState<Config['connections']>(config.connections);
   const [activeConnId, setActiveConnId] = useState<string>(config.active_connection_id);
@@ -83,6 +86,7 @@ export function useSettingsDraft({
     llm: config.llm,
     proxy: config.proxy,
     notifications: config.notifications,
+    service: config.service,
     connections: config.connections,
     activeConnId: config.active_connection_id,
   }));
@@ -243,6 +247,21 @@ export function useSettingsDraft({
     setNotificationsState(next);
     setSaved(false);
   };
+  const setService = (next: Config['service']): void => {
+    setServiceState(next);
+    setSaved(false);
+  };
+  // token 重新生成只更新草稿并标脏（不落盘、不同步基线）：与 host / port 一致走草稿制，随底栏「保存」
+  // 经 config:setService 生效；不保存则丢弃、保留原 token。functional update 避开与开关切换的竞态。
+  const regenerateServiceToken = async (): Promise<void> => {
+    try {
+      const { token } = await invoke('config:generateServiceToken', undefined);
+      setServiceState((prev) => ({ ...prev, token }));
+      setSaved(false);
+    } catch (e) {
+      setSaveError(e instanceof Error ? e.message : String(e));
+    }
+  };
   const setAgentDir = (v: string): void => {
     setAgentDirInput(v);
     setSaved(false);
@@ -291,6 +310,7 @@ export function useSettingsDraft({
   const proxyChanged = JSON.stringify(proxy) !== JSON.stringify(base.proxy);
   const notificationsChanged =
     JSON.stringify(notifications) !== JSON.stringify(base.notifications);
+  const serviceChanged = JSON.stringify(service) !== JSON.stringify(base.service);
   const connectionsChanged =
     activeConnId !== base.activeConnId ||
     JSON.stringify(connections) !== JSON.stringify(base.connections);
@@ -302,6 +322,7 @@ export function useSettingsDraft({
     llmChanged ||
     proxyChanged ||
     notificationsChanged ||
+    serviceChanged ||
     connectionsChanged;
 
   const saveAll = async (): Promise<void> => {
@@ -344,6 +365,17 @@ export function useSettingsDraft({
       if (notificationsChanged) {
         await invoke('config:setNotifications', { notifications });
       }
+      if (serviceChanged) {
+        const host = service.host.trim();
+        // 简单合法性校验：非空、无空白 / 协议 / 斜杠（端口单列）；放过 IPv4 / 主机名 / 0.0.0.0 / ::1。
+        if (!host || !/^[A-Za-z0-9.:-]+$/.test(host)) {
+          throw new Error(t('settings.serviceHostInvalidError'));
+        }
+        if (!Number.isInteger(service.port) || service.port < 1 || service.port > 65535) {
+          throw new Error(t('settings.servicePortRangeError'));
+        }
+        await invoke('config:setService', { service: { ...service, host } });
+      }
       if (connectionsChanged) {
         await invoke('config:setConnections', { connections, active_connection_id: activeConnId });
         await onConnectionsChange?.();
@@ -365,6 +397,7 @@ export function useSettingsDraft({
         llm,
         proxy,
         notifications,
+        service,
         connections,
         activeConnId,
       });
@@ -410,6 +443,10 @@ export function useSettingsDraft({
     // 通知
     notifications,
     setNotifications,
+    // 本地 API 服务监听
+    service,
+    setService,
+    regenerateServiceToken,
     // 轮询 / 并发 / 目录
     pollerInput,
     setPoller,
diff --git a/apps/desktop/src/renderer/src/components/features/settings/sections/NotificationSection.tsx b/apps/desktop/src/renderer/src/components/features/settings/sections/NotificationSection.tsx
index 12f3274d..02cd1c9e 100644
--- a/apps/desktop/src/renderer/src/components/features/settings/sections/NotificationSection.tsx
+++ b/apps/desktop/src/renderer/src/components/features/settings/sections/NotificationSection.tsx
@@ -7,9 +7,10 @@ import { invoke } from '../../../../api';
 const IS_MAC = navigator.platform.toLowerCase().includes('mac');
 
 /**
- * 通知分区：总开关 + 分类型系统通知（新 PR / 评论回复 / 评论 @）。总开关关闭时下属各项禁用（灰显但保留各自
- * 值）。系统通知受 OS 权限约束——用户在系统设置关闭后应用静默降级，此处仅控制应用侧意图。macOS dock「待回应」
- * 计数角标随总开关默认启用、无独立开关，故此处不列。
+ * 通知分区：总开关 + 分类型系统通知——面向评审的（新 PR / 评论回复 / 评论 @）与面向「我创建的」PR 的
+ * （新评论 / 被标记需修改 / 出现冲突）。总开关关闭时下属各项禁用（灰显但保留各自值）。系统通知受 OS 权限
+ * 约束——用户在系统设置关闭后应用静默降级，此处仅控制应用侧意图。macOS dock「待回应」计数角标随总开关默认
+ * 启用、无独立开关，故此处不列。
  */
 export function NotificationSection({
   value,
@@ -73,6 +74,52 @@ export function NotificationSection({
             ariaLabel={t('settings.notifyMentionLabel')}
           />
         </li>
+        <li className="settings-sublist-row">
+          <div className="settings-sublist-text">
+            <span className="settings-sublist-label">{t('settings.notifyAuthoredCommentLabel')}</span>
+            <span className="muted settings-sublist-desc">
+              {t('settings.notifyAuthoredCommentHint')}
+            </span>
+          </div>
+          <Switch
+            checked={value.authored_comment}
+            disabled={!on}
+            onChange={(v) => set({ authored_comment: v })}
+            ariaLabel={t('settings.notifyAuthoredCommentLabel')}
+          />
+        </li>
+        <li className="settings-sublist-row">
+          <div className="settings-sublist-text">
+            <span className="settings-sublist-label">
+              {t('settings.notifyAuthoredNeedsWorkLabel')}
+            </span>
+            <span className="muted settings-sublist-desc">
+              {t('settings.notifyAuthoredNeedsWorkHint')}
+            </span>
+          </div>
+          <Switch
+            checked={value.authored_needs_work}
+            disabled={!on}
+            onChange={(v) => set({ authored_needs_work: v })}
+            ariaLabel={t('settings.notifyAuthoredNeedsWorkLabel')}
+          />
+        </li>
+        <li className="settings-sublist-row">
+          <div className="settings-sublist-text">
+            <span className="settings-sublist-label">
+              {t('settings.notifyAuthoredConflictLabel')}
+            </span>
+            <span className="muted settings-sublist-desc">
+              {t('settings.notifyAuthoredConflictHint')}
+            </span>
+          </div>
+          <Switch
+            checked={value.authored_conflict}
+            disabled={!on}
+            onChange={(v) => set({ authored_conflict: v })}
+            ariaLabel={t('settings.notifyAuthoredConflictLabel')}
+          />
+        </li>
       </ul>
       {IS_MAC && (
         // macOS 授权引导：系统层未授权时通知会被静默丢弃，应用无法代为开启 → 提供按钮跳转系统设置由用户开启。
diff --git a/apps/desktop/src/renderer/src/components/features/settings/sections/RuntimeSection.tsx b/apps/desktop/src/renderer/src/components/features/settings/sections/RuntimeSection.tsx
index 27cf0970..2620a002 100644
--- a/apps/desktop/src/renderer/src/components/features/settings/sections/RuntimeSection.tsx
+++ b/apps/desktop/src/renderer/src/components/features/settings/sections/RuntimeSection.tsx
@@ -1,6 +1,6 @@
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import type { AppInfo } from '@meebox/shared';
+import type { AppInfo, PrAgentStatus } from '@meebox/shared';
 import { CheckGlyphIcon, CopyIcon, GitHubMarkIcon, IssueIcon, TagIcon } from '../../../common';
 import { invoke } from '../../../../api';
 import { UpdateCheckButton } from '../elements/UpdateCheckButton';
@@ -9,6 +9,21 @@ export function RuntimeSection({ info, updateEnabled }: { info: AppInfo; updateE
   const { t } = useTranslation();
   // 复制后短暂切到「打勾 + 已复制」绿色态作反馈（无 toast 体系，按钮内联反馈）。
   const [copied, setCopied] = useState(false);
+  // pr-agent 运行时状态：从状态栏弱化下沉到此处按需展示，打开关于页时拉取。
+  const [prAgent, setPrAgent] = useState<PrAgentStatus | null>(null);
+  useEffect(() => {
+    void invoke('app:prAgentStatus', undefined)
+      .then(setPrAgent)
+      .catch(() => setPrAgent(null));
+  }, []);
+  // 仅展示版本号（不显示 embedded/local-cli 运行策略——对用户无意义）：embedded 的 version 形如
+  // `pr-agent 0.36.0` → 取 `0.36.0`；local-cli 为 help 首行 → 截到首个空白前。
+  const prAgentVer = prAgent?.available
+    ? prAgent.strategy === 'embedded'
+      ? prAgent.version.replace(/^pr-agent\s+/, '')
+      : prAgent.version.split(/\s+/)[0] || prAgent.version
+    : null;
+  const prAgentText = prAgent ? (prAgentVer ?? t('statusBar.prAgentUnavailable')) : '…';
 
   // 操作系统：平台代号 + 系统版本合并展示（如「darwin 15.5」）。
   const osText = `${info.platform} ${info.osVersion}`.trim();
@@ -20,6 +35,7 @@ export function RuntimeSection({ info, updateEnabled }: { info: AppInfo; updateE
     `Node: ${info.nodeVersion}`,
     `${t('settings.operatingSystem')}: ${osText}`,
     `${t('settings.architecture')}: ${info.arch}`,
+    `PR-Agent: ${prAgentText}`,
   ].join('\n');
 
   const copyInfo = (): void => {
@@ -56,6 +72,8 @@ export function RuntimeSection({ info, updateEnabled }: { info: AppInfo; updateE
         <div className="modal-kv-val">{osText}</div>
         <div className="modal-kv-key">{t('settings.architecture')}</div>
         <div className="modal-kv-val">{info.arch}</div>
+        <div className="modal-kv-key">PR-Agent</div>
+        <div className="modal-kv-val">{prAgentText}</div>
       </div>
       <div className="settings-actions" style={{ marginTop: 10, alignItems: 'center' }}>
         <UpdateCheckButton enabled={updateEnabled} />
diff --git a/apps/desktop/src/renderer/src/components/features/settings/sections/ServiceSection.tsx b/apps/desktop/src/renderer/src/components/features/settings/sections/ServiceSection.tsx
new file mode 100644
index 00000000..057f8f8a
--- /dev/null
+++ b/apps/desktop/src/renderer/src/components/features/settings/sections/ServiceSection.tsx
@@ -0,0 +1,161 @@
+import { useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import type { Config } from '@meebox/shared';
+import { CopyIcon, EyeIcon, EyeOffIcon, Switch, SyncIcon } from '../../../common';
+
+/**
+ * 本地 API 服务监听分区：总开关（分区头）+ 缩进「功能列表」逐行展示监听地址 / 访问令牌（行首圆点 +
+ * 标签 + 说明，右侧控件），与「策略」「通知」等分区风格统一。地址为 http://<host>:<port> 组合，token
+ * 可显示 / 复制 / 重新生成；任何开关状态下均可编辑。启用且无 token 时自动生成；非 loopback 绑定给安全
+ * 警示。监听地址 / 端口 / token 均为**草稿制**——随底栏「保存」经 config:setService 生效，不保存则丢弃。
+ */
+export function ServiceSection({
+  value,
+  onChange,
+  onRegenerateToken,
+}: {
+  value: Config['service'];
+  onChange: (next: Config['service']) => void;
+  /** 立即重新生成 token（写盘 + 即时生效）；启用且无 token 时也由此自动补一枚。 */
+  onRegenerateToken: () => void;
+}) {
+  const { t } = useTranslation();
+  const [revealed, setRevealed] = useState(false);
+  const [copied, setCopied] = useState(false);
+  const on = value.enabled;
+  // 暴露判定：非 loopback 绑定（0.0.0.0 / 局域网 IP 等）即视为可被同网段访问，给安全警示。
+  const host = value.host.trim();
+  const exposed = host !== '' && !['127.0.0.1', 'localhost', '::1'].includes(host);
+
+  const set = (patch: Partial<Config['service']>): void => onChange({ ...value, ...patch });
+
+  // 监听地址组与令牌组共用同一固定宽度，使两行右侧控件左右边缘对齐；组内输入框自适应填充剩余。
+  const CONTROL_W = 320;
+
+  const handleEnabled = (v: boolean): void => {
+    if (v && !value.token) onRegenerateToken(); // 启用且无 token → 自动生成一枚
+    set({ enabled: v });
+  };
+
+  const copyToken = async (): Promise<void> => {
+    if (!value.token) return;
+    try {
+      await navigator.clipboard.writeText(value.token);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      /* 复制失败静默 */
+    }
+  };
+
+  return (
+    <section className="modal-section">
+      <div className="modal-section-head">
+        <div className="modal-section-head-title">
+          <h4>{t('settings.serviceTitle')}</h4>
+        </div>
+        <Switch checked={on} onChange={handleEnabled} ariaLabel={t('settings.serviceEnableLabel')} />
+      </div>
+      <p className="muted" style={{ margin: '0 0 8px' }}>
+        {t('settings.serviceHint')}
+      </p>
+
+      <ul className="settings-sublist">
+        <li className="settings-sublist-row">
+          <div className="settings-sublist-text">
+            <span className="settings-sublist-label">{t('settings.serviceHostLabel')}</span>
+            <span className="muted settings-sublist-desc">{t('settings.serviceHostHint')}</span>
+          </div>
+          <div
+            style={{ display: 'flex', alignItems: 'center', gap: 4, flexShrink: 0, width: CONTROL_W }}
+          >
+            <span className="muted">http://</span>
+            <input
+              type="text"
+              className="settings-input"
+              style={{ flex: 1, minWidth: 0 }}
+              value={value.host}
+              onChange={(e) => set({ host: e.target.value })}
+              placeholder="127.0.0.1"
+              spellCheck={false}
+            />
+            <span className="muted">:</span>
+            <input
+              type="number"
+              className="settings-input"
+              style={{ flex: '0 0 auto', width: 72 }}
+              min={1}
+              max={65535}
+              value={value.port}
+              onChange={(e) => set({ port: Number.parseInt(e.target.value, 10) || 0 })}
+            />
+          </div>
+        </li>
+        <li className="settings-sublist-row">
+          <div className="settings-sublist-text">
+            <span className="settings-sublist-label">{t('settings.serviceTokenLabel')}</span>
+            <span className="muted settings-sublist-desc">{t('settings.serviceTokenDesc')}</span>
+          </div>
+          <div
+            style={{ display: 'flex', alignItems: 'center', gap: 8, flexShrink: 0, width: CONTROL_W }}
+          >
+            <input
+              type="text"
+              className="settings-input"
+              style={{ flex: 1, minWidth: 0 }}
+              readOnly
+              value={
+                value.token
+                  ? revealed
+                    ? value.token
+                    : '•'.repeat(Math.min(32, value.token.length))
+                  : ''
+              }
+              placeholder={t('settings.serviceTokenPlaceholder')}
+            />
+            <button
+              type="button"
+              className="btn btn-icon"
+              disabled={!value.token}
+              onClick={() => setRevealed((r) => !r)}
+              title={t(revealed ? 'settings.serviceTokenHide' : 'settings.serviceTokenReveal')}
+              aria-label={t(revealed ? 'settings.serviceTokenHide' : 'settings.serviceTokenReveal')}
+            >
+              {revealed ? <EyeOffIcon /> : <EyeIcon />}
+            </button>
+            <button
+              type="button"
+              className="btn btn-icon"
+              disabled={!value.token}
+              onClick={() => void copyToken()}
+              title={t('settings.serviceTokenCopy')}
+              aria-label={t('settings.serviceTokenCopy')}
+            >
+              <CopyIcon />
+            </button>
+            <button
+              type="button"
+              className="btn btn-icon"
+              onClick={onRegenerateToken}
+              title={t('settings.serviceTokenRegenerate')}
+              aria-label={t('settings.serviceTokenRegenerate')}
+            >
+              <SyncIcon />
+            </button>
+          </div>
+        </li>
+      </ul>
+
+      {exposed && (
+        <p className="error-text" style={{ margin: '8px 0 0' }}>
+          {t('settings.serviceExposeWarning')}
+        </p>
+      )}
+      {copied && (
+        <p className="muted" style={{ margin: '8px 0 0' }}>
+          {t('settings.serviceTokenCopied')}
+        </p>
+      )}
+    </section>
+  );
+}
diff --git a/apps/desktop/src/renderer/src/components/layout/Sidebar.tsx b/apps/desktop/src/renderer/src/components/layout/Sidebar.tsx
index ada47140..0b5e9071 100644
--- a/apps/desktop/src/renderer/src/components/layout/Sidebar.tsx
+++ b/apps/desktop/src/renderer/src/components/layout/Sidebar.tsx
@@ -1,24 +1,33 @@
 import { useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
-import type {
-  AgentRecommendationVerdict,
-  LocalPrStatus,
-  PrDiscoveryFilter,
-  StoredPullRequest,
+import {
+  matchesDiscoveryFilter,
+  matchesPrQuery,
+  matchesSecondaryFilter,
+  type AgentRecommendationVerdict,
+  type PrDiscoveryFilter,
+  type PrSecondaryFilter,
+  type StoredPullRequest,
 } from '@meebox/shared';
 import { invoke, subscribe } from '../../api';
 import { useChatRunStore } from '../../stores/chat-run-store';
 import { HistoryIcon, PaneLoading } from '../common';
 import { PrItem } from '../features/pr';
 
-// 'conflict' / 'mergeable' 是按远端 merge 状态跨 localStatus 横切的筛选；'all' 不限定
-export type FilterKey = 'all' | LocalPrStatus | 'conflict' | 'mergeable';
+// 二级筛选键复用 @meebox/shared 的 PrSecondaryFilter（与本地 API 同源）：
+// 'conflict' / 'mergeable' 按远端 merge 状态跨 localStatus 横切；'all' 不限定。
+export type FilterKey = PrSecondaryFilter;
 
 /** PR 列表范围：进行中（活跃，按发现分类 + 状态细分）/ 已关闭（归档冷存储，扁平只读浏览）。 */
 export type SidebarScope = 'active' | 'archived';
 
 interface SidebarProps {
   prs: StoredPullRequest[];
+  /**
+   * 活跃范围 PR（始终传入，与当前 scope 无关）：供一级发现分类标签的未读圆点计算——即便处在
+   * 「已关闭」视图，标签仍反映活跃分类的未读。缺省回退到 prs。
+   */
+  activePrs?: StoredPullRequest[];
   selectedId: string | null;
   onSelect: (pr: StoredPullRequest) => void;
   width: number;
@@ -74,6 +83,7 @@ interface PrGroup {
 
 export function Sidebar({
   prs,
+  activePrs,
   selectedId,
   onSelect,
   width,
@@ -206,13 +216,24 @@ export function Sidebar({
   // GitHub 发现分类：按 PR 上的 discoveryFilters 标记本地过滤（poller 已把四类都抓回来缓存），
   // 切标签纯本地、瞬时、零远端请求。非 GitHub（discoveryFilter 未设）时用全量。
   const scopedPrs = useMemo(
-    () =>
-      !isArchived && discoveryFilter
-        ? prs.filter((p) => p.discoveryFilters?.includes(discoveryFilter))
-        : prs,
+    () => prs.filter((p) => matchesDiscoveryFilter(p, !isArchived ? discoveryFilter : undefined)),
     [prs, discoveryFilter, isArchived],
   );
 
+  // 未读圆点始终基于**活跃** PR（缺省回退 prs）：即便当前在「已关闭」视图，一级标签仍反映活跃分类的未读。
+  const unreadSourcePrs = activePrs ?? prs;
+  // 各一级发现分类下是否有未读 PR → 在标签文字后加未读圆点，提示该分类有新的待处理。
+  const unreadFilters = useMemo(() => {
+    const s = new Set<PrDiscoveryFilter>();
+    for (const p of unreadSourcePrs) {
+      if (!p.unread) continue;
+      for (const f of p.discoveryFilters ?? []) s.add(f);
+    }
+    return s;
+  }, [unreadSourcePrs]);
+  // 无发现分类平台的单一「进行中」锚点：任一活动 PR 未读即标圆点。
+  const anyUnread = useMemo(() => unreadSourcePrs.some((p) => p.unread), [unreadSourcePrs]);
+
   const counts = useMemo(() => {
     const out: Record<FilterKey, number> = {
       all: scopedPrs.length,
@@ -227,35 +248,22 @@ export function Sidebar({
       if (p.hasConflict) out.conflict += 1;
       if (p.mergeStatus?.canMerge) out.mergeable += 1;
     }
+    // 「我创建的」下「待处理」并入冲突 PR（作者需跟进），复用同源谓词重算、避免与冲突计数重复叠加。
+    if (!isArchived && discoveryFilter === 'created') {
+      out.pending = scopedPrs.filter((p) => matchesSecondaryFilter(p, 'pending', 'created')).length;
+    }
     return out;
-  }, [scopedPrs]);
+  }, [scopedPrs, isArchived, discoveryFilter]);
 
   const filtered = useMemo(() => {
-    const q = query.trim().toLowerCase();
-    // 已关闭范围强制「全部」（不应用状态筛选）；进行中范围按当前状态筛选。
+    // 已关闭范围强制「全部」（不应用状态筛选）；进行中范围按当前状态筛选。过滤 / 检索语义复用
+    // @meebox/shared 纯谓词（与本地 API 同源），并传入一级发现分类以启用分类相关的语义细化。
     const effFilter: FilterKey = isArchived ? 'all' : filter;
-    return scopedPrs.filter((p) => {
-      if (effFilter === 'conflict') {
-        if (!p.hasConflict) return false;
-      } else if (effFilter === 'mergeable') {
-        if (!p.mergeStatus?.canMerge) return false;
-      } else if (effFilter !== 'all' && p.localStatus !== effFilter) {
-        return false;
-      }
-      if (!q) return true;
-      const hay = [
-        p.title,
-        p.repo.projectKey,
-        p.repo.repoSlug,
-        p.author.displayName,
-        p.author.name,
-        p.remoteId,
-      ]
-        .join(' ')
-        .toLowerCase();
-      return hay.includes(q);
-    });
-  }, [scopedPrs, query, filter, isArchived]);
+    const effPrimary = !isArchived ? discoveryFilter : undefined;
+    return scopedPrs.filter(
+      (p) => matchesSecondaryFilter(p, effFilter, effPrimary) && matchesPrQuery(p, query),
+    );
+  }, [scopedPrs, query, filter, isArchived, discoveryFilter]);
 
   const groups = useMemo<PrGroup[]>(() => {
     const m = new Map<string, StoredPullRequest[]>();
@@ -309,6 +317,9 @@ export function Sidebar({
                 type="button"
               >
                 {t(DISCOVERY_LABEL_KEYS[f])}
+                {unreadFilters.has(f) && (
+                  <span className="sidebar-discovery-tab-dot" aria-label="unread" />
+                )}
               </button>
             ))
           ) : (
@@ -320,6 +331,7 @@ export function Sidebar({
               type="button"
             >
               {t('sidebar.scopeActive')}
+              {anyUnread && <span className="sidebar-discovery-tab-dot" aria-label="unread" />}
             </button>
           )}
         </div>
diff --git a/apps/desktop/src/renderer/src/components/layout/StatusBar.tsx b/apps/desktop/src/renderer/src/components/layout/StatusBar.tsx
index 15b10dd3..db8ade7a 100644
--- a/apps/desktop/src/renderer/src/components/layout/StatusBar.tsx
+++ b/apps/desktop/src/renderer/src/components/layout/StatusBar.tsx
@@ -39,22 +39,13 @@ interface StatusBarProps {
   onToggleAutopilot: () => void;
 }
 
-/** pr-agent 运行时 chip：只显示版本（可用）/「不可用」（错误态），属应用运行时级，留在 layout。 */
+/**
+ * pr-agent 运行时 chip：仅在**不可用**（错误态）时显示红色「不可用」告警（可操作信息）。可用时的版本
+ * 号已从状态栏弱化下沉到「关于」页展示（见 RuntimeSection），此处不再渲染，减少常态噪声。
+ */
 function PrAgentRuntimeChip({ status }: { status: PrAgentStatus }) {
   const { t } = useTranslation();
-  if (status.available) {
-    // chip 只显示 pr-agent 版本，不显示 strategy（embedded/local-cli 对用户无意义）；
-    // embedded → `pr-agent 0.36.0` → 取 `0.36.0`；local-cli → help 首行截到首个空白前。
-    const ver =
-      status.strategy === 'embedded'
-        ? status.version.replace(/^pr-agent\s+/, '')
-        : status.version.split(/\s+/)[0] || status.version;
-    return (
-      <StatusChip tone="ok" title={`${status.strategy} · ${status.version}`}>
-        {t('statusBar.prAgentVersion', { ver })}
-      </StatusChip>
-    );
-  }
+  if (status.available) return null;
   return (
     <StatusChip tone="err" title={status.attempts.map((a) => a.error).join('\n')}>
       {t('statusBar.prAgentUnavailable')}
diff --git a/apps/desktop/src/renderer/src/hooks/useTheme.ts b/apps/desktop/src/renderer/src/hooks/useTheme.ts
index 0db3fad4..fab2ee6b 100644
--- a/apps/desktop/src/renderer/src/hooks/useTheme.ts
+++ b/apps/desktop/src/renderer/src/hooks/useTheme.ts
@@ -9,6 +9,14 @@ import {
 } from '../theme';
 import { applyChromeFromEditorTheme } from '../theme/editor-chrome-sync';
 import { setEditorAppearance, useEditorAppearance } from '../stores/editor-appearance-store';
+import { invoke } from '../api';
+
+/** 主题应用后把派生的窗控配色（Windows titleBarOverlay）推给主进程；null 回退通用深/浅。失败静默。 */
+function syncWindowControls(colors: { color: string; symbolColor: string } | null): void {
+  void invoke('window:setControlColors', colors).catch(() => {
+    /* 平台不支持 / 主进程未就绪 → 忽略 */
+  });
+}
 
 /**
  * 全局主题生效：主题变化时把它反推浅 / 深写到 documentElement.data-theme（驱动语义色板）+ 派生结构性
@@ -23,10 +31,10 @@ export function useGlobalTheme(): void {
   useEffect(() => {
     applyGlobalTheme(editorTheme);
     persistEditorTheme(editorTheme);
-    applyChromeFromEditorTheme(editorTheme, resolveGlobalTheme(editorTheme));
-    // 'auto' 主题：OS 深浅切换时重写 data-theme（watch 内部已做）并重派生 chrome
+    syncWindowControls(applyChromeFromEditorTheme(editorTheme, resolveGlobalTheme(editorTheme)));
+    // 'auto' 主题：OS 深浅切换时重写 data-theme（watch 内部已做）并重派生 chrome + 同步窗控配色
     return watchSystemThemeForAuto(editorTheme, () => {
-      applyChromeFromEditorTheme(editorTheme, resolveGlobalTheme(editorTheme));
+      syncWindowControls(applyChromeFromEditorTheme(editorTheme, resolveGlobalTheme(editorTheme)));
     });
   }, [editorTheme]);
 }
diff --git a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
index f5fe935f..dc0b2c82 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/de-DE.json
@@ -138,12 +138,18 @@
     "ruleChipLabel": "Regel",
     "ruleChipTitle": "Klicken, um den Regelinhalt anzuzeigen",
     "ruleFilePath": "Dateipfad",
+    "ruleOpenAgentDir": "Agent-Verzeichnis öffnen",
     "rulePreviewAria": "Regelvorschau",
-    "rulePreviewTitle": "Regel: {{id}}",
+    "rulePreviewTitle": "Regeldetails",
     "rulePreviewTitleMulti": "Übereinstimmende Regeln ({{n}})",
+    "rulePriority": "Priorität",
+    "ruleTools": "Tools",
     "runCancelled": "Abgebrochen",
     "runFailed": "Ausführung fehlgeschlagen",
     "runFailedReason": "Ausführung fehlgeschlagen ({{reason}})",
+    "scopeActiveTitle": "Auf diesen Commit beschränkt – zum Deaktivieren klicken",
+    "scopeCommitTitle": "Auf Commit beschränkt: {{subject}}",
+    "scopeDisabledTitle": "Commit-Bereich deaktiviert – zum Aktivieren klicken",
     "scoreTitle": "Wichtigkeitsbewertung von pr-agent, 1-10",
     "scrollUpForOlder": "Nach oben scrollen, um ältere Verläufe zu laden…",
     "sectionAskAnalysis": "Analyse",
@@ -715,6 +721,7 @@
     "catAgent": "Agent",
     "catConnection": "Verbindung",
     "catGeneral": "Allgemein",
+    "catIntegration": "Integration",
     "catModel": "Modell",
     "catNotifications": "Benachrichtigungen",
     "checkFailed": "Prüfung fehlgeschlagen: {{error}}",
@@ -765,11 +772,17 @@
     "llmTitle": "LLM-Modelle",
     "maxCodeSuggestionsHint": "Max. Code-Vorschläge pro /review, /improve oder /ask.",
     "maxCodeSuggestionsLabel": "Code-Vorschläge",
-    "maxFollowupAsksHint": "Maximale Anzahl bedingter Rückfragen pro Review, wenn die automatische Rückfrage aktiv ist.",
+    "maxFollowupAsksHint": "Max. Anzahl an /ask-Rückfragen – gilt für bedingte Review-Rückfragen (bei aktiver automatischer Rückfrage) und für die automatischen /ask-Aufrufe des freien Agenten.",
     "maxFollowupAsksLabel": "Rückfragen",
     "notificationsEnableLabel": "Benachrichtigungen aktivieren",
     "notificationsHint": "Werde benachrichtigt, wenn es neue Pull Requests oder an dich gerichtete Kommentare gibt. Ob Systembenachrichtigungen erscheinen, hängt von den Benachrichtigungseinstellungen deines Betriebssystems ab.",
     "notificationsTitle": "Benachrichtigungen",
+    "notifyAuthoredCommentHint": "Benachrichtigen, wenn jemand einen von dir erstellten PR kommentiert",
+    "notifyAuthoredCommentLabel": "Neuer Kommentar zu meinem PR",
+    "notifyAuthoredConflictHint": "Benachrichtigen, wenn ein von dir erstellter PR einen Merge-Konflikt bekommt",
+    "notifyAuthoredConflictLabel": "Konflikt in meinem PR",
+    "notifyAuthoredNeedsWorkHint": "Benachrichtigen, wenn ein Reviewer einen von dir erstellten PR als überarbeitungsbedürftig markiert",
+    "notifyAuthoredNeedsWorkLabel": "Mein PR überarbeitungsbedürftig",
     "notifyMacPermissionHint": "macOS steuert die Benachrichtigungsberechtigung auf Systemebene. Falls keine Benachrichtigungen erscheinen, erlaube Benachrichtigungen für diese App in den Systemeinstellungen.",
     "notifyMentionHint": "Benachrichtigen, wenn dich jemand in einem Kommentar mit @ erwähnt",
     "notifyMentionLabel": "Kommentar-Erwähnungen",
@@ -817,6 +830,22 @@
     "runtimeTitle": "Laufzeitumgebung",
     "saved": "Gespeichert",
     "saving": "Speichere…",
+    "serviceEnableLabel": "Lokalen API-Dienst aktivieren",
+    "serviceExposeWarning": "Das Lauschen auf 0.0.0.0 macht die API im lokalen Netzwerk zugänglich; der Token ist der einzige Schutz – halten Sie ihn geheim und nutzen Sie eine Firewall.",
+    "serviceHint": "Stellt eine lokale HTTP-API für die Integration externer Tools / CLI bereit. Standardmäßig aus; verwendet Token-Authentifizierung.",
+    "serviceHostHint": "Auf 0.0.0.0 setzen, um Zugriff aus dem lokalen Netzwerk zu erlauben.",
+    "serviceHostInvalidError": "Ungültige Lausch-Adresse (nur IP oder Hostname; ohne Schema, Leerzeichen oder Port).",
+    "serviceHostLabel": "Lausch-Adresse",
+    "servicePortRangeError": "Der Port muss eine ganze Zahl zwischen 1 und 65535 sein.",
+    "serviceTitle": "Lokaler API-Dienst",
+    "serviceTokenCopied": "Kopiert",
+    "serviceTokenCopy": "Token kopieren",
+    "serviceTokenDesc": "Auth-Token für externen Zugriff.",
+    "serviceTokenHide": "Token verbergen",
+    "serviceTokenLabel": "Token",
+    "serviceTokenPlaceholder": "Noch kein Token generiert",
+    "serviceTokenRegenerate": "Neu generieren",
+    "serviceTokenReveal": "Token anzeigen",
     "setActiveLlmAria": "Als aktiv festlegen",
     "show": "Anzeigen",
     "starOnGithub": "Auf GitHub favorisieren",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/en-US.json b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
index e508951c..e8b378c6 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/en-US.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/en-US.json
@@ -138,12 +138,18 @@
     "ruleChipLabel": "Rule",
     "ruleChipTitle": "Click to view rule content",
     "ruleFilePath": "File path",
+    "ruleOpenAgentDir": "Open agent directory",
     "rulePreviewAria": "Rule preview",
-    "rulePreviewTitle": "Rule: {{id}}",
+    "rulePreviewTitle": "Rule details",
     "rulePreviewTitleMulti": "Matched rules ({{n}})",
+    "rulePriority": "Priority",
+    "ruleTools": "Tools",
     "runCancelled": "Cancelled",
     "runFailed": "Run failed",
     "runFailedReason": "Run failed ({{reason}})",
+    "scopeActiveTitle": "Scoped to this commit — click to disable",
+    "scopeCommitTitle": "Scoped to commit: {{subject}}",
+    "scopeDisabledTitle": "Commit scope disabled — click to enable",
     "scoreTitle": "Importance score from pr-agent, 1-10",
     "scrollUpForOlder": "Scroll up to load earlier history…",
     "sectionAskAnalysis": "Analysis",
@@ -715,6 +721,7 @@
     "catAgent": "Agent",
     "catConnection": "Connection",
     "catGeneral": "General",
+    "catIntegration": "Integration",
     "catModel": "Model",
     "catNotifications": "Notifications",
     "checkFailed": "Check failed: {{error}}",
@@ -765,11 +772,17 @@
     "llmTitle": "LLM Models",
     "maxCodeSuggestionsHint": "Max code suggestions per /review, /improve, or /ask.",
     "maxCodeSuggestionsLabel": "Code suggestions",
-    "maxFollowupAsksHint": "Maximum conditional follow-up questions per review when auto follow-up is on.",
+    "maxFollowupAsksHint": "Max follow-up /ask calls — applies to conditional review follow-ups (when auto follow-up is on) and to the free-form agent's automatic /ask calls.",
     "maxFollowupAsksLabel": "Follow-up questions",
     "notificationsEnableLabel": "Enable notifications",
     "notificationsHint": "Get notified when there are new pull requests or comments addressed to you. System notifications follow your OS notification settings.",
     "notificationsTitle": "Notifications",
+    "notifyAuthoredCommentHint": "Notify when someone comments on a PR you created",
+    "notifyAuthoredCommentLabel": "New comment on my PR",
+    "notifyAuthoredConflictHint": "Notify when a PR you created develops a merge conflict",
+    "notifyAuthoredConflictLabel": "My PR conflict",
+    "notifyAuthoredNeedsWorkHint": "Notify when a reviewer marks a PR you created as needs-work",
+    "notifyAuthoredNeedsWorkLabel": "My PR needs-work",
     "notifyMacPermissionHint": "macOS controls notification permission at the system level. If you don't see notifications, open System Settings and allow notifications for this app.",
     "notifyMentionHint": "Notify when someone @-mentions you in a comment",
     "notifyMentionLabel": "Comment mentions",
@@ -817,6 +830,22 @@
     "runtimeTitle": "Runtime",
     "saved": "Saved",
     "saving": "Saving…",
+    "serviceEnableLabel": "Enable local API service",
+    "serviceExposeWarning": "Listening on 0.0.0.0 exposes the API to your local network; the token is the only safeguard—keep it secret and use a firewall.",
+    "serviceHint": "Expose a local HTTP API for external tools / CLI integration. Off by default; uses token authentication.",
+    "serviceHostHint": "Set to 0.0.0.0 to allow access from your local network.",
+    "serviceHostInvalidError": "Invalid listen address (IP or hostname only; no scheme, spaces, or port).",
+    "serviceHostLabel": "Listen address",
+    "servicePortRangeError": "Port must be an integer between 1 and 65535.",
+    "serviceTitle": "Local API service",
+    "serviceTokenCopied": "Copied",
+    "serviceTokenCopy": "Copy token",
+    "serviceTokenDesc": "Auth token for external access.",
+    "serviceTokenHide": "Hide token",
+    "serviceTokenLabel": "Token",
+    "serviceTokenPlaceholder": "No token generated yet",
+    "serviceTokenRegenerate": "Regenerate",
+    "serviceTokenReveal": "Show token",
     "setActiveLlmAria": "Set as active",
     "show": "Show",
     "starOnGithub": "Star on GitHub",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
index 546aa837..dcefaaef 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/ja-JP.json
@@ -138,12 +138,18 @@
     "ruleChipLabel": "ルール",
     "ruleChipTitle": "クリックしてルール本文を表示",
     "ruleFilePath": "ファイルパス",
+    "ruleOpenAgentDir": "Agent ディレクトリを開く",
     "rulePreviewAria": "ルールのプレビュー",
-    "rulePreviewTitle": "ルール: {{id}}",
+    "rulePreviewTitle": "ルール詳細",
     "rulePreviewTitleMulti": "一致したルール（{{n}} 件）",
+    "rulePriority": "優先度",
+    "ruleTools": "ツール",
     "runCancelled": "キャンセル済み",
     "runFailed": "実行に失敗しました",
     "runFailedReason": "実行に失敗しました ({{reason}})",
+    "scopeActiveTitle": "このコミットに限定中（クリックで無効化）",
+    "scopeCommitTitle": "コミットに限定: {{subject}}",
+    "scopeDisabledTitle": "コミット範囲は無効（クリックで有効化）",
     "scoreTitle": "pr-agent による重要度スコア 1-10",
     "scrollUpForOlder": "上にスクロールして過去の履歴を読み込み…",
     "sectionAskAnalysis": "分析",
@@ -698,6 +704,7 @@
     "catAgent": "エージェント",
     "catConnection": "接続",
     "catGeneral": "一般",
+    "catIntegration": "連携",
     "catModel": "モデル",
     "catNotifications": "通知",
     "checkFailed": "チェックに失敗しました：{{error}}",
@@ -748,11 +755,17 @@
     "llmTitle": "LLM モデル",
     "maxCodeSuggestionsHint": "/review・/improve・/ask が一度に生成するコード提案数の上限。",
     "maxCodeSuggestionsLabel": "コード提案数",
-    "maxFollowupAsksHint": "自動追問が有効なとき、1 回のレビューで行う条件付き追問の数の上限。",
+    "maxFollowupAsksHint": "追問 /ask の数の上限：レビューの条件付き追問（自動追問が有効なとき）と、自由対話エージェントの自動 /ask の両方に適用。",
     "maxFollowupAsksLabel": "追問の数",
     "notificationsEnableLabel": "通知を有効化",
     "notificationsHint": "新しい PR やあなた宛てのコメントがあると通知します。システム通知が表示されるかは OS の通知設定に従います。",
     "notificationsTitle": "通知",
+    "notifyAuthoredCommentHint": "自分が作成した PR に他の人がコメントしたときに通知",
+    "notifyAuthoredCommentLabel": "自分の PR への新規コメント",
+    "notifyAuthoredConflictHint": "自分が作成した PR にマージ競合が発生したときに通知",
+    "notifyAuthoredConflictLabel": "自分の PR の競合",
+    "notifyAuthoredNeedsWorkHint": "自分が作成した PR がレビュアーに要修正と設定されたときに通知",
+    "notifyAuthoredNeedsWorkLabel": "自分の PR の要修正",
     "notifyMacPermissionHint": "macOS は通知の許可をシステムレベルで管理します。通知が表示されない場合は、システム設定でこのアプリの通知を許可してください。",
     "notifyMentionHint": "コメントであなたが @ メンションされたときに通知",
     "notifyMentionLabel": "コメントのメンション",
@@ -800,6 +813,22 @@
     "runtimeTitle": "実行環境",
     "saved": "保存しました",
     "saving": "保存中…",
+    "serviceEnableLabel": "ローカル API サービスを有効化",
+    "serviceExposeWarning": "0.0.0.0 でのリッスンは API を LAN に公開します。トークンが唯一の防御策です——秘匿し、ファイアウォールを併用してください。",
+    "serviceHint": "外部ツール / CLI 連携用のローカル HTTP API を公開します。既定は無効。トークン認証を使用します。",
+    "serviceHostHint": "0.0.0.0 に設定すると LAN から接続可能。",
+    "serviceHostInvalidError": "リッスンアドレスの形式が不正です（IP / ホスト名のみ。プロトコル・空白・ポートは不可）。",
+    "serviceHostLabel": "リッスンアドレス",
+    "servicePortRangeError": "ポートは 1〜65535 の整数で指定してください。",
+    "serviceTitle": "ローカル API サービス",
+    "serviceTokenCopied": "コピーしました",
+    "serviceTokenCopy": "トークンをコピー",
+    "serviceTokenDesc": "外部アクセス用の認証トークン。",
+    "serviceTokenHide": "トークンを隠す",
+    "serviceTokenLabel": "トークン",
+    "serviceTokenPlaceholder": "トークン未生成",
+    "serviceTokenRegenerate": "再生成",
+    "serviceTokenReveal": "トークンを表示",
     "setActiveLlmAria": "アクティブに設定",
     "show": "表示",
     "starOnGithub": "GitHub でスター",
diff --git a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
index d7ae37e0..2b7e955b 100644
--- a/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
+++ b/apps/desktop/src/renderer/src/i18n/locales/zh-CN.json
@@ -138,12 +138,18 @@
     "ruleChipLabel": "规则",
     "ruleChipTitle": "点击查看规则正文",
     "ruleFilePath": "文件路径",
+    "ruleOpenAgentDir": "打开 Agent 目录",
     "rulePreviewAria": "规则预览",
-    "rulePreviewTitle": "规则: {{id}}",
+    "rulePreviewTitle": "规则详情",
     "rulePreviewTitleMulti": "命中规则（{{n}} 条）",
+    "rulePriority": "优先级",
+    "ruleTools": "工具",
     "runCancelled": "已取消",
     "runFailed": "run 失败",
     "runFailedReason": "run 失败 ({{reason}})",
+    "scopeActiveTitle": "已限定在此提交，点击临时禁用",
+    "scopeCommitTitle": "限定在提交：{{subject}}",
+    "scopeDisabledTitle": "提交范围已禁用，点击启用",
     "scoreTitle": "pr-agent 给出的重要度评分 1-10",
     "scrollUpForOlder": "向上滚动加载更早历史…",
     "sectionAskAnalysis": "分析解读",
@@ -698,6 +704,7 @@
     "catAgent": "智能体",
     "catConnection": "连接",
     "catGeneral": "常规",
+    "catIntegration": "集成",
     "catModel": "模型",
     "catNotifications": "通知",
     "checkFailed": "检查失败：{{error}}",
@@ -748,11 +755,17 @@
     "llmTitle": "LLM 模型",
     "maxCodeSuggestionsHint": "单次 /review、/improve、/ask 生成的代码建议数量上限。",
     "maxCodeSuggestionsLabel": "代码建议数量",
-    "maxFollowupAsksHint": "自动追问启用时，单次评审条件性追问的数量上限。",
+    "maxFollowupAsksHint": "追问 /ask 数量上限：评审条件性追问（需开启自动追问）与自由对话 Agent 的自动 /ask 均受此约束。",
     "maxFollowupAsksLabel": "追问数量",
     "notificationsEnableLabel": "启用通知",
     "notificationsHint": "在有新的 PR 或与你相关的评论时收到提醒。系统通知是否弹出取决于操作系统的通知设置。",
     "notificationsTitle": "通知",
+    "notifyAuthoredCommentHint": "我创建的 PR 收到他人新评论时提醒",
+    "notifyAuthoredCommentLabel": "我的 PR 新评论",
+    "notifyAuthoredConflictHint": "我创建的 PR 出现合并冲突时提醒",
+    "notifyAuthoredConflictLabel": "我的 PR 冲突",
+    "notifyAuthoredNeedsWorkHint": "我创建的 PR 被评审标记「需修改」时提醒",
+    "notifyAuthoredNeedsWorkLabel": "我的 PR 需修改",
     "notifyMacPermissionHint": "macOS 在系统层管控通知权限。若收不到通知，请在系统设置中为本应用开启通知。",
     "notifyMentionHint": "评论中有人 @ 你时提醒",
     "notifyMentionLabel": "评论提及",
@@ -800,6 +813,22 @@
     "runtimeTitle": "运行环境",
     "saved": "已保存",
     "saving": "保存中…",
+    "serviceEnableLabel": "启用本地 API 服务",
+    "serviceExposeWarning": "监听 0.0.0.0 会把 API 暴露到局域网，token 是唯一防线——请确保 token 保密并配合防火墙。",
+    "serviceHint": "对外提供本地 HTTP API，供外部工具 / CLI 集成。默认关闭，使用 token 鉴权。",
+    "serviceHostHint": "配置为 0.0.0.0 可被本机局域网访问。",
+    "serviceHostInvalidError": "监听地址格式不合法（仅允许 IP / 主机名，不含协议、空格或端口）。",
+    "serviceHostLabel": "监听地址",
+    "servicePortRangeError": "端口需为 1–65535 之间的整数。",
+    "serviceTitle": "本地 API 服务",
+    "serviceTokenCopied": "已复制",
+    "serviceTokenCopy": "复制 token",
+    "serviceTokenDesc": "外部访问的鉴权令牌。",
+    "serviceTokenHide": "隐藏 token",
+    "serviceTokenLabel": "访问令牌",
+    "serviceTokenPlaceholder": "尚未生成 token",
+    "serviceTokenRegenerate": "重新生成",
+    "serviceTokenReveal": "显示 token",
     "setActiveLlmAria": "设为活跃",
     "show": "显示",
     "starOnGithub": "GitHub 上 Star",
diff --git a/apps/desktop/src/renderer/src/styles/base.scss b/apps/desktop/src/renderer/src/styles/base.scss
index b191aa16..6b6cf0bf 100644
--- a/apps/desktop/src/renderer/src/styles/base.scss
+++ b/apps/desktop/src/renderer/src/styles/base.scss
@@ -157,6 +157,25 @@ textarea {
   }
 }
 
+// 文本型按钮：无底 / 无边框的链接态动作（工具栏里的轻量操作，如「全选 / 取消全选」），
+// 强调蓝、hover 加下划线；不占按钮实底，读作行内链接。
+.btn-link {
+  background: none;
+  border: none;
+  padding: 0;
+  color: $color-accent;
+  font: inherit;
+  cursor: pointer;
+
+  &:hover:not(:disabled) {
+    text-decoration: underline;
+  }
+  &:disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
 .count-pill {
   background: $bg-white-fade;
   padding: 0 $space-3;
diff --git a/apps/desktop/src/renderer/src/styles/common/modal.scss b/apps/desktop/src/renderer/src/styles/common/modal.scss
index e9f7a2e5..f9c0d6f1 100644
--- a/apps/desktop/src/renderer/src/styles/common/modal.scss
+++ b/apps/desktop/src/renderer/src/styles/common/modal.scss
@@ -40,6 +40,14 @@
   }
 }
 
+// header 右侧组：自定义动作（headerActions）+ 关闭键，右对齐并排。
+// align-items: stretch 让图标动作按钮拉伸到与关闭键等高（图标内容比文字矮，否则会短一截）。
+.modal-header-right {
+  display: flex;
+  align-items: stretch;
+  gap: $space-3;
+}
+
 // 右上角关闭按钮：方形 X 图标（免国际化），复用 .icon-btn 的透明无边框，
 // 这里只调方形 padding + hover 浅底
 .modal-close {
diff --git a/apps/desktop/src/renderer/src/styles/features/chat/pane.scss b/apps/desktop/src/renderer/src/styles/features/chat/pane.scss
index 96ecbd6b..248e6d50 100644
--- a/apps/desktop/src/renderer/src/styles/features/chat/pane.scss
+++ b/apps/desktop/src/renderer/src/styles/features/chat/pane.scss
@@ -257,18 +257,21 @@
   gap: $space-4;
 }
 // stop + send 包在一个 group 里，让 space-between 只对"/ 按钮 vs 这一组"生效，
-// stop 跟 send 之间用 group 自己的 gap 控制贴近距离
+// stop 跟 send 之间用 group 自己的 gap 控制贴近距离。发送区不参与压缩：窄宽度时挤压的是左侧 chip 而非发送键。
 .chat-pane-send-group {
   display: inline-flex;
   align-items: center;
   gap: $space-2;
+  flex-shrink: 0;
 }
 
-// 命令触发器组：`/` 命令按钮 + 自动评审图标按钮，左对齐成一组（两者间距略放宽）
+// 命令触发器组：`/` 命令按钮 + 自动评审图标按钮，左对齐成一组（两者间距略放宽）。
+// min-width:0 允许本组在窄宽度下收窄（由内部可伸缩的范围 / 选区 chip 让位、省略号截断），不推挤右侧发送区。
 .chat-cmd-group {
   display: inline-flex;
   align-items: center;
   gap: $space-3;
+  min-width: 0;
 }
 
 // 命令触发器：单 `/` 按钮 + 弹出菜单 (替代之前 3 个并列按钮)
@@ -331,6 +334,8 @@
   align-items: center;
   gap: $space-2;
   max-width: 180px;
+  // 窄宽度时自身收窄（span 省略号截断），把空间让给右侧发送区，而非撑破布局。
+  min-width: 0;
   padding: $space-2 $space-2;
   background: transparent;
   border: none;
diff --git a/apps/desktop/src/renderer/src/styles/features/chat/run.scss b/apps/desktop/src/renderer/src/styles/features/chat/run.scss
index 19524484..19fad80b 100644
--- a/apps/desktop/src/renderer/src/styles/features/chat/run.scss
+++ b/apps/desktop/src/renderer/src/styles/features/chat/run.scss
@@ -157,6 +157,13 @@
   align-items: center;
   gap: 3px;
 }
+// 单 commit 范围徽标：提交图标 + 短 SHA，图标与 SHA 对齐（等宽字体）
+.chat-run-scope {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-family: $font-mono;
+}
 // 输入 / 输出各自一组（箭头 + 数字[+ 缓存]）：独立 hover 提示的悬浮目标，内部行内对齐
 .chat-token-grp {
   display: inline-flex;
diff --git a/apps/desktop/src/renderer/src/styles/features/pr/statusbar.scss b/apps/desktop/src/renderer/src/styles/features/pr/statusbar.scss
index 3d66c9c1..11ea1700 100644
--- a/apps/desktop/src/renderer/src/styles/features/pr/statusbar.scss
+++ b/apps/desktop/src/renderer/src/styles/features/pr/statusbar.scss
@@ -5,8 +5,10 @@
 @use '../../tokens' as *;
 @use '../../mixins' as *;
 
-// PR 数 chip：图标 + 数字横排（gap / svg 基线由 .statusbar-chip 统一）
+// PR 数 chip：图标 + 数字横排（gap / svg 基线由 .statusbar-chip 统一）。用与 pr-agent 活动 /
+// repo sync 同一蓝调（chip-tone accent），与主题强调色一致。
 .statusbar-chip-prs {
+  @include chip-tone(accent);
   font-variant-numeric: tabular-nums;
 }
 
diff --git a/apps/desktop/src/renderer/src/styles/layout/sidebar.scss b/apps/desktop/src/renderer/src/styles/layout/sidebar.scss
index fa02c819..0776a879 100644
--- a/apps/desktop/src/renderer/src/styles/layout/sidebar.scss
+++ b/apps/desktop/src/renderer/src/styles/layout/sidebar.scss
@@ -45,6 +45,14 @@
 
 .sidebar-filters {
   flex-wrap: wrap;
+
+  // 胶囊宽度自适应：basis 取内容宽（auto）→ 一行挤得下就用一行；容纳不下时按内容宽换行（窄侧栏下
+  // 自然落为每行两个）。flex-grow 让每行按项数均分撑满整行，消除定宽按钮换行后右侧留白参差。
+  // 内容居中，读作对称胶囊。
+  .btn {
+    flex: 1 1 auto;
+    justify-content: center;
+  }
 }
 
 .sidebar-search {
@@ -142,6 +150,17 @@
   }
 }
 
+// 一级发现分类标签的未读圆点：该分类下有未读 PR 时，跟在标签文字后（复用 PR 项未读点的亮蓝）。
+.sidebar-discovery-tab-dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  margin-left: $space-2;
+  border-radius: 50%;
+  background: $color-info;
+  flex: 0 0 auto;
+}
+
 .sidebar-list {
   flex: 1;
   overflow-y: auto;
diff --git a/apps/desktop/src/renderer/src/theme/editor-chrome-sync.ts b/apps/desktop/src/renderer/src/theme/editor-chrome-sync.ts
index 16a48553..e47007f0 100644
--- a/apps/desktop/src/renderer/src/theme/editor-chrome-sync.ts
+++ b/apps/desktop/src/renderer/src/theme/editor-chrome-sync.ts
@@ -30,6 +30,7 @@ const OVERRIDDEN_VARS = [
   '--border-default-fade',
   '--border-muted',
   '--bg-selected',
+  '--bg-group-header',
 ] as const;
 
 interface Rgb {
@@ -73,6 +74,12 @@ function toRgbString({ r, g, b, a }: Rgb): string {
   return a >= 1 ? `rgb(${r}, ${g}, ${b})` : `rgb(${r} ${g} ${b} / ${a.toFixed(3)})`;
 }
 
+/** 转 #rrggbb（忽略 alpha）；供 Windows titleBarOverlay 用（其 color 取 hex）。 */
+function toHex({ r, g, b }: Rgb): string {
+  const h = (v: number): string => v.toString(16).padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}`;
+}
+
 /** 相对亮度（WCAG）。 */
 function luminance({ r, g, b }: Rgb): number {
   const ch = (v: number): number => {
@@ -117,7 +124,10 @@ function clearChromeOverrides(): void {
  * 把当前全局主题的 base 色派生为 GUI chrome 的结构性 token，写到 documentElement（覆盖 _theme.scss）。
  * 取不到色 / 缺 bg·fg 时清空覆盖、回退语义色板（仍随 data-theme 浅 / 深正常显示）。
  */
-export function applyChromeFromEditorTheme(editorThemeId: string, resolvedGuiTheme: 'light' | 'dark'): void {
+export function applyChromeFromEditorTheme(
+  editorThemeId: string,
+  resolvedGuiTheme: 'light' | 'dark',
+): { color: string; symbolColor: string } | null {
   // 'auto' 跟随解析主题 → 取默认 2026 主题（dark-2026 / light-2026）的 base 色
   const effectiveId =
     editorThemeId === 'auto' ? (resolvedGuiTheme === 'dark' ? 'dark-2026' : 'light-2026') : editorThemeId;
@@ -127,7 +137,7 @@ export function applyChromeFromEditorTheme(editorThemeId: string, resolvedGuiThe
   if (!bg || !fg) {
     clearChromeOverrides();
     console.warn('[chrome-sync] no usable bg/fg for theme, fell back to semantic palette:', effectiveId);
-    return;
+    return null;
   }
   const isDark = luminance(bg) < 0.5;
   const edge = isDark ? WHITE : BLACK; // 提升层（背景越「浮」越靠该边）/ 边框混合方向
@@ -147,6 +157,8 @@ export function applyChromeFromEditorTheme(editorThemeId: string, resolvedGuiThe
   const borderDefault = mix(fg, bg, 0.8);
   const borderMuted = mix(fg, bg, 0.88);
   const borderFade = { ...borderDefault, a: 0.5 };
+  // 分组头：向黑轻微下沉（比 bg-app 略暗的「凹陷」标题带，hover 走 --bg-panel 上浮），随主题派生。
+  const bgGroupHeader = mix(bg, BLACK, 0.12);
 
   const set = (name: string, c: Rgb): void => document.documentElement.style.setProperty(name, toRgbString(c));
   set('--bg-app', bg);
@@ -164,6 +176,7 @@ export function applyChromeFromEditorTheme(editorThemeId: string, resolvedGuiThe
   set('--border-muted', borderMuted);
   set('--border-default-fade', borderFade);
   set('--bg-selected', sel);
+  set('--bg-group-header', bgGroupHeader);
 
   // 可读性体检：muted 文字 / 弱边框对背景的对比度（AA 正文≥4.5、次要文本/非文本≥3）
   const mutedCr = contrastRatio(textMuted, bg);
@@ -171,4 +184,6 @@ export function applyChromeFromEditorTheme(editorThemeId: string, resolvedGuiThe
   console.info(
     `[chrome-sync] "${effectiveId}" (${isDark ? 'dark' : 'light'}) → muted/bg contrast ${mutedCr.toFixed(2)} (AA≥4.5), border/bg ${borderCr.toFixed(2)} (≥3)`,
   );
+  // 窗控按钮同色：把主题 base 背景 / 前景（hex）交回主进程更新 Windows titleBarOverlay（见 useGlobalTheme）。
+  return { color: toHex(bg), symbolColor: toHex(fg) };
 }
diff --git a/cli/.gitignore b/cli/.gitignore
new file mode 100644
index 00000000..65330843
--- /dev/null
+++ b/cli/.gitignore
@@ -0,0 +1,14 @@
+# Build output
+/bin/
+/dist/
+/meebox
+/meebox.exe
+
+# Test binaries (go test -c), coverage / profiling output
+*.test
+*.out
+*.prof
+
+# Go workspace files (local dev only)
+go.work
+go.work.sum
diff --git a/cli/README.md b/cli/README.md
new file mode 100644
index 00000000..30230b45
--- /dev/null
+++ b/cli/README.md
@@ -0,0 +1,108 @@
+# meebox CLI
+
+A standalone, cross-platform command-line client for **Code Meeseeks**. It is a
+thin client over the desktop app's local HTTP API — see the design docs:
+
+- [Service listener & local API](../docs/arch/04-integration/01-service-api.md)
+- [CLI tool](../docs/arch/04-integration/02-cli.md)
+- Usage guide: [docs/guide/06-cli.md](../docs/guide/06-cli.md)
+
+It provides PR browsing plus review write actions (approve / needs-work / comment);
+merging and the agent's publish/mutating tools are intentionally not exposed.
+
+`meebox` is also shipped as a drop-in agent **skill** — each release archive bundles
+[`SKILL.md`](SKILL.md) beside the binary, so unzipping it into an agent's skills
+directory yields a working skill. `SKILL.md` is also embedded in the binary: if you have
+only the binary, `meebox skill > SKILL.md` reconstructs the doc (a fallback for rebuilding
+the skill directory without the archive).
+
+## Install
+
+macOS / Linux one-liner — downloads the latest release, verifies its SHA-256, installs `meebox` to PATH:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/huhamhire/code-meeseeks/main/tools/cli/install.sh | bash
+```
+
+`MEEBOX_VERSION` / `MEEBOX_BIN_DIR` env vars (or `--version` / `--bin-dir` flags) override the release
+and install dir. Windows: download the `.zip` from Releases. No separate `SKILL.md` needed — it is
+embedded in the binary (`meebox skill` prints it).
+
+## Build & run
+
+This is an independent Go module (`go.mod`), not part of the npm/Nx workspace.
+
+```bash
+cd cli
+go build -o bin/meebox .      # or: go install .
+go vet ./...
+go test ./...
+```
+
+Cross-compile (matches the release matrix):
+
+```bash
+GOOS=windows GOARCH=amd64 go build -o dist/meebox.exe .
+GOOS=darwin  GOARCH=arm64 go build -o dist/meebox .
+GOOS=linux   GOARCH=amd64 go build -o dist/meebox .
+GOOS=linux   GOARCH=arm64 go build -o dist/meebox .
+```
+
+## Connection
+
+The CLI resolves the API base URL and bearer token in this order (highest first):
+
+1. flags — `--api-url`, `--token`
+2. env — `MEEBOX_API_URL`, `MEEBOX_TOKEN`
+3. CLI config — `~/.code-meeseeks/cli.yaml` (`api_url`, `token`)
+
+Connection details must be provided explicitly; the CLI does **not** read the app's
+`~/.code-meeseeks/config.yaml` (which holds connection-layer secrets). The API URL
+defaults to `http://127.0.0.1:18765` when unset.
+
+`meebox login --token <token> [--server <url>]` persists the token (and optional server
+URL) to `cli.yaml` so later commands need no flags/env — the write counterpart to the
+`cli.yaml` read above:
+
+```bash
+meebox login --token <token>                        # default server http://127.0.0.1:18765
+meebox login --token <token> --server http://host:18765
+```
+
+## Commands
+
+Root-level `whoami` / `version` need no PR. Two domains — `pr` (also holds `categories`
+and `refresh`) and `agent` — carry PR-scoped commands via the required `--pr <id>` flag
+(`id` comes from `pr list`):
+
+```text
+meebox login --token <token> [--server <url>]   # save credentials to cli.yaml
+meebox whoami
+meebox version                          # CLI (client) + app (server) versions
+meebox skill                            # print the embedded agent usage doc (SKILL.md)
+meebox pr categories
+meebox pr refresh                       # trigger one immediate poll for the latest PRs
+meebox pr list [--category <filter>] [--status <key>] [--query <text>] [--skip N] [--limit N]
+meebox pr show     --pr <id>
+meebox pr diff     --pr <id> [--file <path>] [--side base|head]
+meebox pr activity --pr <id>
+meebox pr commits  --pr <id>
+meebox pr reviewers --pr <id>
+meebox pr approve  --pr <id>            # real remote review decision
+meebox pr needswork --pr <id>           # real remote review decision
+meebox pr comment  --pr <id> <message>  # real remote comment
+meebox agent status   --pr <id>
+meebox agent history  --pr <id>
+meebox agent review   --pr <id>
+meebox agent instruct --pr <id> <command> [args...]   # read-only: describe|review|ask|improve
+meebox agent chat     --pr <id> <message>
+meebox agent stop     --pr <id>                         # stop the whole PR agent
+meebox agent run list --pr <id>
+meebox agent run cancel --pr <id> --run <runId>         # cancel one pr-agent run
+```
+
+Global flags: `--api-url`, `--token`, `--output yaml|json`, `--quiet`.
+
+Output defaults to **YAML** (human-friendly, k8s `-o yaml` style); pass
+`--output json` for the machine-readable form used by third-party integrations.
+Both preserve the server's field order (no per-command formatting).
diff --git a/cli/SKILL.md b/cli/SKILL.md
new file mode 100644
index 00000000..bd0d8916
--- /dev/null
+++ b/cli/SKILL.md
@@ -0,0 +1,79 @@
+---
+name: meebox
+description: Review and act on pull requests through the Code Meeseeks "meebox" CLI — list and inspect PRs, run the AI review agent, and record review outcomes (approve / needs-work / comment). Use when the user wants to triage, review, or act on pull requests via a running Code Meeseeks desktop app.
+---
+
+# meebox — pull-request review over the local API
+
+`meebox` is a thin cross-platform CLI over a running **Code Meeseeks** desktop app's
+local HTTP API. Use it to browse pull requests, drive the review agent, and record
+review outcomes. Output defaults to YAML; pass `--output json` when parsing results.
+
+## Prerequisites
+
+- The Code Meeseeks desktop app is running with the local API service **enabled**
+  (Settings → Integration).
+- The `meebox` binary is available — it ships in this skill directory; put it on `PATH`
+  or invoke it by path (`./meebox`).
+- Connection is configured (below). Verify with `meebox whoami`.
+
+## Connect
+
+Provide the API base URL + token explicitly — the CLI never reads the app's `config.yaml`.
+Easiest is `meebox login` (persists to `~/.code-meeseeks/cli.yaml`); or use env vars:
+
+```bash
+meebox login --token <token>                     # save token (default server http://127.0.0.1:18765)
+meebox login --token <token> --server http://host:18765   # remote server
+# — or, instead of login —
+export MEEBOX_API_URL=http://127.0.0.1:18765     # default port; override for remote hosts
+export MEEBOX_TOKEN=<token>                       # from Settings → Integration
+
+meebox whoami                                     # confirm the resolved user + platform
+meebox --output json pr list | jq '.[].id'        # JSON for scripting
+```
+
+## Command map
+
+Root-level `meebox whoami` and `meebox version` need no PR. The rest split into two domains —
+`pr` and `agent`; PR-scoped subcommands take the **required `--pr <id>`** flag (`id` from `pr list`),
+while `pr categories` / `pr refresh` / `pr list` are collection-level (no `--pr`).
+
+**Browse / inspect — `pr`**
+- `meebox pr categories` — the active platform's `categories` / `statuses` filter vocabulary for `pr list`.
+- `meebox pr refresh` — trigger one immediate poll for the latest PRs (same as the app's manual refresh); returns change counts (fetched / changed / added / removed / errors). Run before `pr list` for fresh data.
+- `meebox pr list [--category review-requested|created|assigned|mentioned] [--status pending|approved|needs_work|conflict|mergeable] [--query <text>] [--skip N] [--limit N]` — paginated (default limit 100), slim fields (id / title / author / createdAt first).
+- `meebox pr show --pr <id>` — full detail incl. description.
+- `meebox pr diff --pr <id> [--file <path> --side base|head]` — changed files, or one file's content.
+- `meebox pr activity --pr <id>` · `meebox pr commits --pr <id>` · `meebox pr reviewers --pr <id>`.
+
+**Review agent — `agent`**
+- `meebox agent review --pr <id>` — run the auto-review micro-flow (describe→review→[ask]→summary).
+- `meebox agent status --pr <id>` · `meebox agent history --pr <id>` — progress + conversation.
+- `meebox agent instruct --pr <id> <describe|review|ask|improve> [text]` — one read-only tool call.
+- `meebox agent chat --pr <id> <message>` — natural-language message (may trigger tasks).
+- `meebox agent run list --pr <id>` · `meebox agent run cancel --pr <id> --run <runId>` — inspect / cancel a single agent run.
+- `meebox agent stop --pr <id>` — stop the whole agent for the PR.
+
+**Record outcomes — `pr` (real remote writes)**
+- `meebox pr approve --pr <id>` · `meebox pr needswork --pr <id>` — post a review decision.
+- `meebox pr comment --pr <id> <message>` — post a top-level comment.
+
+Root-level (no PR):
+- `meebox login --token <token> [--server <url>]` — save credentials to `cli.yaml` (default server is loopback); later commands need no flags/env.
+- `meebox whoami` — current user + platform + connection (confirm your token resolves).
+- `meebox version` — CLI (client) + app (server) versions; client-only when the server is unreachable.
+- `meebox skill` — print this doc (SKILL.md is embedded in the binary), so usage is retrievable even without the file.
+
+## Typical loop
+
+1. `meebox --output json pr list --status pending` → choose a PR `id`.
+2. `meebox pr show --pr <id>` and/or `meebox agent review --pr <id>`; poll `meebox agent status --pr <id>`.
+3. Inspect changes: `meebox pr diff --pr <id>`.
+4. Record the outcome: `meebox pr approve --pr <id>` / `meebox pr needswork --pr <id>` / `meebox pr comment --pr <id> "…"`.
+
+## Boundaries
+
+- **Not available**: merging PRs, and the agent's publish / mutating tools — `instruct` accepts
+  only the read-only tools `describe` / `review` / `ask` / `improve`.
+- Exit codes: `0` ok · `2` auth failure · `3` not found · `1` other; errors print to stderr with the API error code.
diff --git a/cli/cmd/agent.go b/cli/cmd/agent.go
new file mode 100644
index 00000000..97a8207b
--- /dev/null
+++ b/cli/cmd/agent.go
@@ -0,0 +1,219 @@
+package cmd
+
+import (
+	"fmt"
+	"net/url"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// readOnlyInstructions is the set of agent instructions the CLI may send via
+// `pr agent instruct`. These are the read-only pr-agent tools; write review actions
+// have dedicated commands (`pr approve` / `pr needswork` / `pr comment`) and are not
+// routed through instruct. The server independently enforces the same whitelist.
+var readOnlyInstructions = map[string]bool{
+	"describe": true,
+	"review":   true,
+	"ask":      true,
+	"improve":  true,
+}
+
+// newAgentCmd builds the top-level `agent` command group: review-agent operations, all
+// PR-scoped (each requires `--pr <id>`). A sibling of `pr` rather than nested under it —
+// the uniform --pr flag already carries the PR id, so nesting would only repeat `pr`.
+func newAgentCmd() *cobra.Command {
+	a := &cobra.Command{
+		Use:   "agent",
+		Short: "Operate the review agent on a PR",
+	}
+	a.AddCommand(
+		newAgentStatusCmd(),
+		newAgentHistoryCmd(),
+		newAgentReviewCmd(),
+		newAgentInstructCmd(),
+		newAgentChatCmd(),
+		newAgentStopCmd(),
+		newAgentRunCmd(),
+	)
+	return a
+}
+
+// newAgentRunCmd builds the `pr agent run` subgroup: inspect / cancel individual pr-agent
+// tool-call runs in the queue — finer-grained than the PR-level `agent stop`.
+func newAgentRunCmd() *cobra.Command {
+	r := &cobra.Command{
+		Use:   "run",
+		Short: "Inspect or cancel individual pr-agent runs",
+	}
+	r.AddCommand(newAgentRunListCmd(), newAgentRunCancelCmd())
+	return r
+}
+
+// newAgentRunListCmd builds `agent run list --pr <id>`: the PR's active + waiting
+// pr-agent runs (runId / tool / state), the source of run ids to cancel
+// (GET /prs/{id}/agent/runs).
+func newAgentRunListCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List the PR's active and queued pr-agent runs",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr) + "/agent/runs")
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newAgentRunCancelCmd builds `agent run cancel --pr <id> --run <runId>`: cancels one
+// pr-agent run (active SIGKILL / waiting dequeue) (POST /prs/{id}/agent/runs/{runId}/cancel).
+// Unlike `agent stop` (halts the whole PR agent), this targets a single tool-call run.
+func newAgentRunCancelCmd() *cobra.Command {
+	var pr, run string
+	cmd := &cobra.Command{
+		Use:   "cancel",
+		Short: "Cancel one pr-agent run by id (see `run list`)",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return postAndRender(
+				"/api/v1/prs/"+url.PathEscape(pr)+"/agent/runs/"+url.PathEscape(run)+"/cancel", nil)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	cmd.Flags().StringVar(&run, "run", "", "run id to cancel (from `pr agent run list`)")
+	_ = cmd.MarkFlagRequired("run")
+	return cmd
+}
+
+// newAgentStatusCmd builds `agent status --pr <id>`: the agent's current run state
+// snapshot (GET /prs/{id}/agent).
+func newAgentStatusCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "status",
+		Short: "Show the agent's current execution status",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr) + "/agent")
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newAgentHistoryCmd builds `agent history --pr <id>`: the multi-turn conversation
+// history (GET /prs/{id}/agent/conversation).
+func newAgentHistoryCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "history",
+		Short: "Show the agent conversation history",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr) + "/agent/conversation")
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newAgentReviewCmd builds `agent review --pr <id>`: kicks off the review micro-flow
+// (describe→review→ask→summary) (POST /prs/{id}/agent/review).
+func newAgentReviewCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "review",
+		Short: "Run auto review on a PR",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			c, err := resolveClient()
+			if err != nil {
+				return err
+			}
+			data, err := c.Post("/api/v1/prs/"+url.PathEscape(pr)+"/agent/review", nil)
+			if err != nil {
+				return err
+			}
+			return renderData(data)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newAgentInstructCmd builds `agent instruct --pr <id> <command> [args...]`: sends a
+// single read-only pr-agent instruction (POST /prs/{id}/agent/instruct). Write tools are
+// rejected up front (and again by the server).
+func newAgentInstructCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "instruct <command> [args...]",
+		Short: "Send a read-only agent instruction (describe|review|ask|improve)",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			instruction := strings.TrimPrefix(args[0], "/")
+			if !readOnlyInstructions[instruction] {
+				return fmt.Errorf("instruction %q is not a read-only command; use `pr approve` / `pr needswork` / `pr comment` for write actions", args[0])
+			}
+			c, err := resolveClient()
+			if err != nil {
+				return err
+			}
+			body := map[string]any{"command": instruction}
+			if len(args) > 1 {
+				body["args"] = strings.Join(args[1:], " ")
+			}
+			data, err := c.Post("/api/v1/prs/"+url.PathEscape(pr)+"/agent/instruct", body)
+			if err != nil {
+				return err
+			}
+			return renderData(data)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newAgentChatCmd builds `agent chat --pr <id> <message>`: sends a natural-language
+// message that may trigger agent tasks (POST /prs/{id}/agent/chat).
+func newAgentChatCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "chat <message>",
+		Short: "Send a natural-language chat message (may trigger agent tasks)",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			c, err := resolveClient()
+			if err != nil {
+				return err
+			}
+			body := map[string]any{"message": strings.Join(args, " ")}
+			data, err := c.Post("/api/v1/prs/"+url.PathEscape(pr)+"/agent/chat", body)
+			if err != nil {
+				return err
+			}
+			return renderData(data)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newAgentStopCmd builds `agent stop --pr <id>`: interrupts the PR's running agent in
+// any phase (thinking / executing) (POST /prs/{id}/agent/stop). PR-level stop — it halts
+// the whole agent for that PR, not one specific tool run.
+func newAgentStopCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "stop",
+		Short: "Stop the PR's running agent (interrupts any in-progress phase)",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return postAndRender("/api/v1/prs/"+url.PathEscape(pr)+"/agent/stop", nil)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
diff --git a/cli/cmd/categories.go b/cli/cmd/categories.go
new file mode 100644
index 00000000..680e1449
--- /dev/null
+++ b/cli/cmd/categories.go
@@ -0,0 +1,17 @@
+package cmd
+
+import "github.com/spf13/cobra"
+
+// newCategoriesCmd builds `meebox pr categories`: lists the enabled platform's available
+// filter labels — `categories` (discovery) and `statuses` (review/merge) (GET /categories).
+// Lives under `pr` because it is the filter vocabulary for `pr list` (--category / --status).
+func newCategoriesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "categories",
+		Short: "List available PR classification labels for the enabled platforms",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/categories")
+		},
+	}
+}
diff --git a/cli/cmd/integration_test.go b/cli/cmd/integration_test.go
new file mode 100644
index 00000000..9def1eb6
--- /dev/null
+++ b/cli/cmd/integration_test.go
@@ -0,0 +1,405 @@
+package cmd
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/render"
+)
+
+// capturedReq records what the mock server received, for request-shape assertions.
+type capturedReq struct {
+	called bool
+	method string
+	path   string
+	query  string
+	auth   string
+	body   string
+}
+
+// mockServer stands in for the local API: it records the request and returns the
+// documented envelope ({ok:true,data} on 2xx, {ok:false,error} on >=400).
+func mockServer(rec *capturedReq, status int, dataJSON string) *httptest.Server {
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		rec.called = true
+		rec.method = r.Method
+		rec.path = r.URL.Path
+		rec.query = r.URL.RawQuery
+		rec.auth = r.Header.Get("Authorization")
+		rec.body = string(body)
+
+		w.Header().Set("Content-Type", "application/json")
+		code := status
+		if code == 0 {
+			code = http.StatusOK
+		}
+		w.WriteHeader(code)
+		if code >= 400 {
+			_, _ = io.WriteString(w, `{"ok":false,"error":{"code":"ESV0001"}}`)
+			return
+		}
+		_, _ = io.WriteString(w, `{"ok":true,"data":`+dataJSON+`}`)
+	}))
+}
+
+// testSkillDoc stands in for the embedded SKILL.md (main injects the real one at build).
+const testSkillDoc = "# meebox (test skill doc)\n"
+
+// runCmd runs the root command with captured output, returning stdout + the error
+// (Execute()'s os.Exit wrapper is bypassed so tests can assert on the error).
+func runCmd(args ...string) (string, error) {
+	var buf bytes.Buffer
+	origOut, origErr := render.Stdout, render.Stderr
+	render.Stdout, render.Stderr = &buf, io.Discard
+	defer func() { render.Stdout, render.Stderr = origOut, origErr }()
+
+	root := newRootCmd(testSkillDoc)
+	root.SetArgs(args)
+	err := root.Execute()
+	return buf.String(), err
+}
+
+// base flags force explicit connection settings so tests are hermetic (no env /
+// local config auto-discovery interference).
+func base(srvURL string, rest ...string) []string {
+	return append([]string{"--api-url", srvURL, "--token", "tk"}, rest...)
+}
+
+func TestCategories(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"platform":"github","categories":["review-requested"],"statuses":["all"]}`)
+	defer srv.Close()
+
+	out, err := runCmd(base(srv.URL, "pr", "categories")...)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodGet || rec.path != "/api/v1/categories" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	if rec.auth != "Bearer tk" {
+		t.Errorf("wrong auth header: %q", rec.auth)
+	}
+	if !strings.Contains(out, "platform: github") {
+		t.Errorf("output missing rendered field: %q", out)
+	}
+}
+
+func TestWhoami(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"platform":"github","user":{"slug":"alice"}}`)
+	defer srv.Close()
+
+	out, err := runCmd(base(srv.URL, "whoami")...)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodGet || rec.path != "/api/v1/whoami" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	if !strings.Contains(out, "platform: github") {
+		t.Errorf("output missing rendered field: %q", out)
+	}
+}
+
+func TestPrRefreshPost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"fetched":3,"changed":1,"added":1,"removed":0,"errors":0}`)
+	defer srv.Close()
+
+	out, err := runCmd(base(srv.URL, "pr", "refresh")...)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/refresh" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	if !strings.Contains(out, "added: 1") {
+		t.Errorf("output missing rendered field: %q", out)
+	}
+}
+
+func TestVersion(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"version":"9.9.9"}`)
+	defer srv.Close()
+
+	out, err := runCmd(base(srv.URL, "version")...)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodGet || rec.path != "/api/v1/version" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	// Both client (build-time "dev" in tests) and server versions render.
+	if !strings.Contains(out, "client:") || !strings.Contains(out, "server: 9.9.9") {
+		t.Errorf("version output missing client/server: %q", out)
+	}
+}
+
+func TestLoginWritesConfig(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+	t.Setenv("USERPROFILE", dir)
+	t.Setenv("MEEBOX_API_URL", "")
+	t.Setenv("MEEBOX_TOKEN", "")
+
+	if _, err := runCmd("login", "--token", "tok123", "--server", "http://saved:9"); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data, err := os.ReadFile(filepath.Join(dir, ".code-meeseeks", "cli.yaml"))
+	if err != nil {
+		t.Fatalf("cli.yaml not written: %v", err)
+	}
+	if !strings.Contains(string(data), "tok123") || !strings.Contains(string(data), "http://saved:9") {
+		t.Errorf("cli.yaml missing token/server: %q", string(data))
+	}
+}
+
+func TestSkillPrintsEmbeddedDoc(t *testing.T) {
+	out, err := runCmd("skill")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if out != testSkillDoc {
+		t.Errorf("skill output = %q, want embedded doc %q", out, testSkillDoc)
+	}
+}
+
+func TestPrListFilters(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `[]`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "pr", "list", "--category", "created", "--status", "approved", "--query", "foo", "--skip", "5", "--limit", "20")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.path != "/api/v1/prs" {
+		t.Errorf("wrong path: %s", rec.path)
+	}
+	for _, want := range []string{"category=created", "status=approved", "q=foo", "skip=5", "limit=20"} {
+		if !strings.Contains(rec.query, want) {
+			t.Errorf("query %q missing %q", rec.query, want)
+		}
+	}
+}
+
+func TestPrShow(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"localId":"abc123","title":"t"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "pr", "show", "--pr", "abc123")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodGet || rec.path != "/api/v1/prs/abc123" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestPrDiffFile(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"binary":false,"content":"x"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "pr", "diff", "--pr", "abc123", "--file", "src/a.go", "--side", "head")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.path != "/api/v1/prs/abc123/diff" {
+		t.Errorf("wrong path: %s", rec.path)
+	}
+	for _, want := range []string{"path=src", "side=head"} {
+		if !strings.Contains(rec.query, want) {
+			t.Errorf("query %q missing %q", rec.query, want)
+		}
+	}
+}
+
+func TestAgentReviewPost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"status":"succeeded"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "agent", "review", "--pr", "abc123")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/agent/review" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestAgentInstructBody(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"status":"queued"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "agent", "instruct", "--pr", "abc123", "describe", "extra", "ctx")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/agent/instruct" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	if !strings.Contains(rec.body, "describe") || !strings.Contains(rec.body, "extra ctx") {
+		t.Errorf("body missing command/args: %q", rec.body)
+	}
+}
+
+func TestAgentInstructWriteToolRejected(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `null`)
+	defer srv.Close()
+
+	_, err := runCmd(base(srv.URL, "agent", "instruct", "--pr", "abc123", "approve")...)
+	if err == nil {
+		t.Fatal("expected write tool to be rejected")
+	}
+	if rec.called {
+		t.Error("server must not be called for a rejected write tool")
+	}
+}
+
+func TestAgentChatPost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"queued":true}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "agent", "chat", "--pr", "abc123", "hello", "world")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/agent/chat" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	if !strings.Contains(rec.body, "hello world") {
+		t.Errorf("body missing message: %q", rec.body)
+	}
+}
+
+func TestPrApprovePost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"localStatus":"approved"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "pr", "approve", "--pr", "abc123")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/approve" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestPrNeedsworkPost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"localStatus":"needs_work"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "pr", "needswork", "--pr", "abc123")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/needswork" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestPrCommentPost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"remoteId":"c1"}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "pr", "comment", "--pr", "abc123", "please", "fix")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/comment" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+	if !strings.Contains(rec.body, "please fix") {
+		t.Errorf("body missing comment text: %q", rec.body)
+	}
+}
+
+func TestAgentStopPost(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"ok":true}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "agent", "stop", "--pr", "abc123")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/agent/stop" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestAgentRunList(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `[{"runId":"r1","tool":"review","state":"active"}]`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "agent", "run", "list", "--pr", "abc123")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodGet || rec.path != "/api/v1/prs/abc123/agent/runs" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestAgentRunCancel(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"ok":true}`)
+	defer srv.Close()
+
+	if _, err := runCmd(base(srv.URL, "agent", "run", "cancel", "--pr", "abc123", "--run", "r1")...); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if rec.method != http.MethodPost || rec.path != "/api/v1/prs/abc123/agent/runs/r1/cancel" {
+		t.Errorf("wrong request: %s %s", rec.method, rec.path)
+	}
+}
+
+func TestAuthFailureExitCode(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 401, "")
+	defer srv.Close()
+
+	_, err := runCmd(base(srv.URL, "pr", "categories")...)
+	if err == nil {
+		t.Fatal("expected auth error")
+	}
+	if got := render.ExitCodeFor(err); got != render.ExitAuth {
+		t.Errorf("auth failure exit code = %d, want %d", got, render.ExitAuth)
+	}
+}
+
+func TestNotFoundExitCode(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 404, "")
+	defer srv.Close()
+
+	_, err := runCmd(base(srv.URL, "pr", "show", "--pr", "missing")...)
+	if err == nil {
+		t.Fatal("expected not-found error")
+	}
+	if got := render.ExitCodeFor(err); got != render.ExitNotFound {
+		t.Errorf("not-found exit code = %d, want %d", got, render.ExitNotFound)
+	}
+}
+
+func TestOutputJSON(t *testing.T) {
+	var rec capturedReq
+	srv := mockServer(&rec, 200, `{"platform":"github"}`)
+	defer srv.Close()
+
+	out, err := runCmd(base(srv.URL, "--output", "json", "pr", "categories")...)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(out, `"platform": "github"`) {
+		t.Errorf("json output not indented JSON: %q", out)
+	}
+}
diff --git a/cli/cmd/login.go b/cli/cmd/login.go
new file mode 100644
index 00000000..38b6820b
--- /dev/null
+++ b/cli/cmd/login.go
@@ -0,0 +1,40 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/render"
+	"github.com/huhamhire/code-meeseeks/cli/internal/settings"
+	"github.com/spf13/cobra"
+)
+
+// newLoginCmd builds `meebox login --token <token> [--server <url>]`: persists the API token
+// (and optional server URL, default loopback) to ~/.code-meeseeks/cli.yaml so later commands
+// need no `--token` / env each time. Completes CLI config management — the CLI could read
+// cli.yaml but had no way to write it. Purely local: it saves credentials, it does not verify
+// them against the server (run `meebox whoami` afterwards to confirm they resolve).
+func newLoginCmd() *cobra.Command {
+	var token, server string
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Save the API token (and optional server URL) to ~/.code-meeseeks/cli.yaml",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			if server == "" {
+				server = settings.DefaultAPIURL()
+			}
+			path, err := settings.Save(settings.Settings{APIURL: server, Token: token})
+			if err != nil {
+				return err
+			}
+			if !gflags.quiet {
+				fmt.Fprintf(render.Stdout, "Saved credentials for %s to %s\n", server, path)
+			}
+			return nil
+		},
+	}
+	cmd.Flags().StringVar(&token, "token", "", "API bearer token (from Settings → Integration)")
+	cmd.Flags().StringVar(&server, "server", "", "API base URL (default "+settings.DefaultAPIURL()+")")
+	_ = cmd.MarkFlagRequired("token")
+	return cmd
+}
diff --git a/cli/cmd/pr.go b/cli/cmd/pr.go
new file mode 100644
index 00000000..bbd12154
--- /dev/null
+++ b/cli/cmd/pr.go
@@ -0,0 +1,232 @@
+package cmd
+
+import (
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+// prIDFlag registers the required `--pr <id>` flag (the `id` field from `pr list`)
+// on cmd and binds it to target. Making the PR id an explicit named flag (rather than
+// a positional arg) keeps every PR-scoped command's invocation self-describing.
+func prIDFlag(cmd *cobra.Command, target *string) {
+	cmd.Flags().StringVar(target, "pr", "", "PR id (the `id` field from `pr list`)")
+	_ = cmd.MarkFlagRequired("pr")
+}
+
+// newPrCmd builds the `pr` command group: direct PR-entity operations — browsing plus
+// review write actions (approve / needswork / comment). The review agent is its own
+// top-level `agent` group (see newAgentCmd), not nested here: since every command is
+// PR-scoped via --pr, nesting agent under pr would only add a redundant `pr` segment.
+func newPrCmd() *cobra.Command {
+	pr := &cobra.Command{
+		Use:   "pr",
+		Short: "Browse and act on pull requests",
+	}
+	pr.AddCommand(
+		newCategoriesCmd(),
+		newRefreshCmd(),
+		newPrListCmd(),
+		newPrShowCmd(),
+		newPrDiffCmd(),
+		newPrActivityCmd(),
+		newPrCommitsCmd(),
+		newPrReviewersCmd(),
+		newPrApproveCmd(),
+		newPrNeedsworkCmd(),
+		newPrCommentCmd(),
+	)
+	return pr
+}
+
+// newPrListCmd builds `pr list`: the paginated, filtered PR list (GET /prs). Returns
+// the slim list projection (id / title / author / createdAt first); category/status
+// map to the discovery + review/merge filters, skip/limit drive pagination.
+func newPrListCmd() *cobra.Command {
+	var category, status, query string
+	var skip, limit int
+	cmd := &cobra.Command{
+		Use:   "list",
+		Short: "List PRs with category / status filters and skip+limit pagination",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			c, err := resolveClient()
+			if err != nil {
+				return err
+			}
+			q := url.Values{}
+			if category != "" {
+				q.Set("category", category)
+			}
+			if status != "" {
+				q.Set("status", status)
+			}
+			if query != "" {
+				q.Set("q", query)
+			}
+			if skip > 0 {
+				q.Set("skip", strconv.Itoa(skip))
+			}
+			if limit > 0 {
+				q.Set("limit", strconv.Itoa(limit))
+			}
+			data, err := c.Get("/api/v1/prs", q)
+			if err != nil {
+				return err
+			}
+			return renderData(data)
+		},
+	}
+	f := cmd.Flags()
+	f.StringVar(&category, "category", "", "discovery category (review-requested|created|assigned|mentioned)")
+	f.StringVar(&status, "status", "", "status filter (pending|approved|needs_work|conflict|mergeable)")
+	f.StringVar(&query, "query", "", "search text (title / repo / author / number)")
+	f.IntVar(&skip, "skip", 0, "skip the first N results (pagination offset)")
+	f.IntVar(&limit, "limit", 0, "max results to return (default 100 when unset)")
+	return cmd
+}
+
+// newPrShowCmd builds `pr show --pr <id>`: the full PR detail incl. description (GET /prs/{id}).
+func newPrShowCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "show",
+		Short: "Show PR description detail",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr))
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newPrDiffCmd builds `pr diff --pr <id>`: the changed-file list, or (with --file) one
+// file's content on the given --side (GET /prs/{id}/diff[?path=&side=]).
+func newPrDiffCmd() *cobra.Command {
+	var pr, file, side string
+	cmd := &cobra.Command{
+		Use:   "diff",
+		Short: "List changed files, or fetch one file's content with --file",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			c, err := resolveClient()
+			if err != nil {
+				return err
+			}
+			q := url.Values{}
+			if file != "" {
+				q.Set("path", file)
+			}
+			if side != "" {
+				q.Set("side", side)
+			}
+			data, err := c.Get("/api/v1/prs/"+url.PathEscape(pr)+"/diff", q)
+			if err != nil {
+				return err
+			}
+			return renderData(data)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	cmd.Flags().StringVar(&file, "file", "", "fetch this file's content instead of the changed-file list")
+	cmd.Flags().StringVar(&side, "side", "", "file side when --file is set: base|head")
+	return cmd
+}
+
+// newPrActivityCmd builds `pr activity --pr <id>`: the merged activity timeline
+// (comments / commits / review decisions) (GET /prs/{id}/activity).
+func newPrActivityCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "activity",
+		Short: "Show the PR activity timeline (comments / commits / review decisions)",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr) + "/activity")
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newPrCommitsCmd builds `pr commits --pr <id>`: the PR's own commits (GET /prs/{id}/commits).
+func newPrCommitsCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "commits",
+		Short: "List the PR commits",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr) + "/commits")
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newPrReviewersCmd builds `pr reviewers --pr <id>`: reviewer approval status (GET /prs/{id}/reviewers).
+func newPrReviewersCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "reviewers",
+		Short: "Show reviewer approval status",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/prs/" + url.PathEscape(pr) + "/reviewers")
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newPrApproveCmd builds `pr approve --pr <id>`: records an Approve review decision on
+// the platform, i.e. a real remote write (POST /prs/{id}/approve).
+func newPrApproveCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "approve",
+		Short: "Approve the PR (posts a real review decision to the platform)",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return postAndRender("/api/v1/prs/"+url.PathEscape(pr)+"/approve", nil)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newPrNeedsworkCmd builds `pr needswork --pr <id>`: records a Needs-Work review decision
+// on the platform, i.e. a real remote write (POST /prs/{id}/needswork).
+func newPrNeedsworkCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "needswork",
+		Short: "Mark the PR as needs-work (posts a real review decision to the platform)",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return postAndRender("/api/v1/prs/"+url.PathEscape(pr)+"/needswork", nil)
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
+
+// newPrCommentCmd builds `pr comment --pr <id> <message...>`: posts a top-level comment
+// to the PR on the platform (POST /prs/{id}/comment).
+func newPrCommentCmd() *cobra.Command {
+	var pr string
+	cmd := &cobra.Command{
+		Use:   "comment <message>",
+		Short: "Post a top-level comment on the PR",
+		Args:  cobra.MinimumNArgs(1),
+		RunE: func(_ *cobra.Command, args []string) error {
+			return postAndRender("/api/v1/prs/"+url.PathEscape(pr)+"/comment",
+				map[string]any{"body": strings.Join(args, " ")})
+		},
+	}
+	prIDFlag(cmd, &pr)
+	return cmd
+}
diff --git a/cli/cmd/refresh.go b/cli/cmd/refresh.go
new file mode 100644
index 00000000..14020ece
--- /dev/null
+++ b/cli/cmd/refresh.go
@@ -0,0 +1,18 @@
+package cmd
+
+import "github.com/spf13/cobra"
+
+// newRefreshCmd builds `meebox pr refresh`: trigger one immediate poll across all connections
+// (the same action as the GUI's manual refresh), fetching the latest PRs into local state and
+// returning a summary of what changed (POST /refresh). Returns counts:
+// fetched / changed / added / removed / errors. Global — not PR-scoped, so no --pr flag.
+func newRefreshCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "refresh",
+		Short: "Trigger an immediate poll for the latest PRs",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return postAndRender("/api/v1/refresh", nil)
+		},
+	}
+}
diff --git a/cli/cmd/root.go b/cli/cmd/root.go
new file mode 100644
index 00000000..8996ef2f
--- /dev/null
+++ b/cli/cmd/root.go
@@ -0,0 +1,109 @@
+// Package cmd defines the meebox command tree built on cobra.
+package cmd
+
+import (
+	"encoding/json"
+	"os"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/apiclient"
+	"github.com/huhamhire/code-meeseeks/cli/internal/render"
+	"github.com/huhamhire/code-meeseeks/cli/internal/settings"
+	"github.com/spf13/cobra"
+)
+
+// version is overridden at build time via -ldflags; "dev" for local builds.
+var version = "dev"
+
+type globalFlags struct {
+	apiURL string
+	token  string
+	output string
+	quiet  bool
+}
+
+var gflags globalFlags
+
+func newRootCmd(skillDoc string) *cobra.Command {
+	root := &cobra.Command{
+		Use:           "meebox",
+		Short:         "Code Meeseeks CLI — integrate PR review capabilities over the local API",
+		SilenceUsage:  true,
+		SilenceErrors: true,
+		Version:       version,
+	}
+	pf := root.PersistentFlags()
+	pf.StringVar(&gflags.apiURL, "api-url", "", "API base URL (overrides "+settings.EnvAPIURL+" and cli.yaml)")
+	pf.StringVar(&gflags.token, "token", "", "bearer token (overrides "+settings.EnvToken+" and cli.yaml)")
+	pf.StringVar(&gflags.output, "output", "yaml", "output format: yaml|json")
+	pf.BoolVar(&gflags.quiet, "quiet", false, "suppress non-essential output")
+
+	root.AddCommand(
+		newLoginCmd(),
+		newWhoamiCmd(),
+		newVersionCmd(),
+		newSkillCmd(skillDoc),
+		newPrCmd(),
+		newAgentCmd(),
+	)
+	return root
+}
+
+// Execute runs the root command, printing errors to stderr and mapping them
+// to process exit codes per docs/arch/04-integration/02-cli.md. skillDoc is the
+// SKILL.md embedded into the binary (see main), surfaced by `meebox skill`.
+func Execute(skillDoc string) {
+	if err := newRootCmd(skillDoc).Execute(); err != nil {
+		render.Errorln(err)
+		os.Exit(render.ExitCodeFor(err))
+	}
+}
+
+// resolveClient builds an API client from the resolved connection settings.
+func resolveClient() (*apiclient.Client, error) {
+	s, err := settings.Resolve(settings.Overrides{
+		APIURL: gflags.apiURL,
+		Token:  gflags.token,
+	})
+	if err != nil {
+		return nil, err
+	}
+	return apiclient.New(s.APIURL, s.Token, version), nil
+}
+
+func outputMode() render.Mode {
+	if gflags.output == "json" {
+		return render.ModeJSON
+	}
+	return render.ModeYAML
+}
+
+func renderData(data json.RawMessage) error {
+	return render.Output(outputMode(), data)
+}
+
+// getAndRender is the common GET-then-render path used by read-only commands.
+func getAndRender(path string) error {
+	c, err := resolveClient()
+	if err != nil {
+		return err
+	}
+	data, err := c.Get(path, nil)
+	if err != nil {
+		return err
+	}
+	return renderData(data)
+}
+
+// postAndRender is the common POST-then-render path used by action commands
+// (agent triggers, review write actions). body may be nil for parameterless POSTs.
+func postAndRender(path string, body any) error {
+	c, err := resolveClient()
+	if err != nil {
+		return err
+	}
+	data, err := c.Post(path, body)
+	if err != nil {
+		return err
+	}
+	return renderData(data)
+}
diff --git a/cli/cmd/skill.go b/cli/cmd/skill.go
new file mode 100644
index 00000000..d388361c
--- /dev/null
+++ b/cli/cmd/skill.go
@@ -0,0 +1,27 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/render"
+	"github.com/spf13/cobra"
+)
+
+// newSkillCmd builds `meebox skill`: prints the agent-facing usage doc (SKILL.md) embedded
+// into the binary at build time. Lets the binary self-document even when detached from its
+// release archive (self-introspection), and keeps the emitted doc in lock-step with the
+// shipped SKILL.md. doc is injected from main; empty only in bare unit-test builds.
+func newSkillCmd(doc string) *cobra.Command {
+	return &cobra.Command{
+		Use:   "skill",
+		Short: "Print the embedded agent usage doc (SKILL.md)",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			if doc == "" {
+				return fmt.Errorf("skill doc not embedded in this build")
+			}
+			fmt.Fprint(render.Stdout, doc)
+			return nil
+		},
+	}
+}
diff --git a/cli/cmd/version.go b/cli/cmd/version.go
new file mode 100644
index 00000000..55f55333
--- /dev/null
+++ b/cli/cmd/version.go
@@ -0,0 +1,57 @@
+package cmd
+
+import (
+	"encoding/json"
+	"fmt"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/render"
+	"github.com/spf13/cobra"
+)
+
+// newVersionCmd builds `meebox version`: prints the CLI (client) version and, when
+// the local API is reachable, the desktop app (server) version — mirroring `docker version`.
+// The client version always renders; if the server can't be reached its field is null and a
+// warning goes to stderr, but the exit stays 0 so the client version is usable offline.
+// (The root `--version` flag remains the quick client-only path.)
+func newVersionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "Show the CLI (client) and app (server) versions",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			out := struct {
+				Client string  `json:"client"`
+				Server *string `json:"server"`
+			}{Client: version}
+			if sv, err := fetchServerVersion(); err != nil {
+				render.Errorln(fmt.Errorf("server version unavailable: %w", err))
+			} else {
+				out.Server = &sv
+			}
+			raw, err := json.Marshal(out)
+			if err != nil {
+				return err
+			}
+			return renderData(raw)
+		},
+	}
+}
+
+// fetchServerVersion asks the local API for the desktop app version (GET /version).
+func fetchServerVersion() (string, error) {
+	c, err := resolveClient()
+	if err != nil {
+		return "", err
+	}
+	data, err := c.Get("/api/v1/version", nil)
+	if err != nil {
+		return "", err
+	}
+	var sv struct {
+		Version string `json:"version"`
+	}
+	if err := json.Unmarshal(data, &sv); err != nil {
+		return "", err
+	}
+	return sv.Version, nil
+}
diff --git a/cli/cmd/whoami.go b/cli/cmd/whoami.go
new file mode 100644
index 00000000..2342c0e2
--- /dev/null
+++ b/cli/cmd/whoami.go
@@ -0,0 +1,17 @@
+package cmd
+
+import "github.com/spf13/cobra"
+
+// newWhoamiCmd builds `meebox whoami`: the current authenticated user (from the active
+// connection's PAT) plus the integrated platform and connection display name (GET /whoami).
+// Handy first call to confirm the token resolves to the expected account / platform.
+func newWhoamiCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "whoami",
+		Short: "Show the current user identity and integrated platform",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return getAndRender("/api/v1/whoami")
+		},
+	}
+}
diff --git a/cli/go.mod b/cli/go.mod
new file mode 100644
index 00000000..31a8aa5e
--- /dev/null
+++ b/cli/go.mod
@@ -0,0 +1,13 @@
+module github.com/huhamhire/code-meeseeks/cli
+
+go 1.24
+
+require (
+	github.com/spf13/cobra v1.8.1
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.5 // indirect
+)
diff --git a/cli/go.sum b/cli/go.sum
new file mode 100644
index 00000000..a01295bb
--- /dev/null
+++ b/cli/go.sum
@@ -0,0 +1,12 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
+github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
+github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
+github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/cli/internal/apiclient/client.go b/cli/internal/apiclient/client.go
new file mode 100644
index 00000000..fdf66160
--- /dev/null
+++ b/cli/internal/apiclient/client.go
@@ -0,0 +1,157 @@
+// Package apiclient is a thin HTTP client for the Code Meeseeks local API.
+// It speaks the response envelope documented in
+// docs/arch/04-integration/01-service-api.md: { ok, data } on success and
+// { ok:false, error:{ code, meta } } on failure.
+package apiclient
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// CLIVersionHeader announces the CLI version so the server can gate incompatible
+// (too-old) clients. Kept in sync with the server-side constant by convention.
+const CLIVersionHeader = "X-Meebox-CLI-Version"
+
+// CodeClientTooOld is the server error code (ESV0005) returned when this CLI is older
+// than the server's minimum supported version. Kept in sync with the shared registry.
+const CodeClientTooOld = "ESV0005"
+
+// Client talks to the local API with a bearer token.
+type Client struct {
+	baseURL string
+	token   string
+	version string
+	http    *http.Client
+}
+
+// New builds a client for the given base URL, bearer token, and CLI version (sent as a
+// header for server-side compatibility gating; empty is fine and simply omits the header).
+func New(baseURL, token, version string) *Client {
+	return &Client{
+		baseURL: strings.TrimRight(baseURL, "/"),
+		token:   token,
+		version: version,
+		http:    &http.Client{Timeout: 60 * time.Second},
+	}
+}
+
+// APIError is the structured error decoded from a { ok:false, error } envelope
+// (or a bare non-2xx status when the body is not an envelope).
+type APIError struct {
+	Status int
+	Code   string
+	Meta   map[string]any
+}
+
+func (e *APIError) Error() string {
+	if e.Code == CodeClientTooOld {
+		got := metaString(e.Meta, "clientVersion")
+		min := metaString(e.Meta, "minVersion")
+		return fmt.Sprintf(
+			"incompatible CLI: this meebox (%s) is older than the app requires (minimum %s); "+
+				"upgrade the CLI — re-run the install script or download the latest release",
+			orUnknown(got), orUnknown(min))
+	}
+	if e.Code != "" {
+		return fmt.Sprintf("API error %s (HTTP %d)", e.Code, e.Status)
+	}
+	return fmt.Sprintf("API error (HTTP %d)", e.Status)
+}
+
+func metaString(m map[string]any, key string) string {
+	if v, ok := m[key].(string); ok {
+		return v
+	}
+	return ""
+}
+
+func orUnknown(s string) string {
+	if s == "" {
+		return "unknown"
+	}
+	return s
+}
+
+type envelope struct {
+	OK    bool            `json:"ok"`
+	Data  json.RawMessage `json:"data"`
+	Error *struct {
+		Code string         `json:"code"`
+		Meta map[string]any `json:"meta"`
+	} `json:"error"`
+}
+
+// Get issues an authenticated GET and returns the raw data payload.
+func (c *Client) Get(path string, query url.Values) (json.RawMessage, error) {
+	u := c.baseURL + path
+	if len(query) > 0 {
+		u += "?" + query.Encode()
+	}
+	req, err := http.NewRequest(http.MethodGet, u, nil)
+	if err != nil {
+		return nil, err
+	}
+	return c.do(req)
+}
+
+// Post issues an authenticated POST with a JSON body and returns the raw data
+// payload. A nil body sends no request entity.
+func (c *Client) Post(path string, body any) (json.RawMessage, error) {
+	var reader io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return nil, err
+		}
+		reader = bytes.NewReader(b)
+	}
+	req, err := http.NewRequest(http.MethodPost, c.baseURL+path, reader)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	return c.do(req)
+}
+
+func (c *Client) do(req *http.Request) (json.RawMessage, error) {
+	req.Header.Set("Authorization", "Bearer "+c.token)
+	req.Header.Set("Accept", "application/json")
+	if c.version != "" {
+		req.Header.Set(CLIVersionHeader, c.version)
+	}
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	raw, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+
+	var env envelope
+	if len(raw) > 0 {
+		if err := json.Unmarshal(raw, &env); err != nil {
+			// Body is not an API envelope (e.g. a proxy error page) — surface status.
+			return nil, &APIError{Status: resp.StatusCode}
+		}
+	}
+	if resp.StatusCode >= 400 || !env.OK {
+		ae := &APIError{Status: resp.StatusCode}
+		if env.Error != nil {
+			ae.Code = env.Error.Code
+			ae.Meta = env.Error.Meta
+		}
+		return nil, ae
+	}
+	return env.Data, nil
+}
diff --git a/cli/internal/apiclient/client_test.go b/cli/internal/apiclient/client_test.go
new file mode 100644
index 00000000..2aa9980c
--- /dev/null
+++ b/cli/internal/apiclient/client_test.go
@@ -0,0 +1,68 @@
+package apiclient
+
+import (
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestSendsCLIVersionHeader(t *testing.T) {
+	var got string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = r.Header.Get(CLIVersionHeader)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"ok":true,"data":null}`)
+	}))
+	defer srv.Close()
+
+	if _, err := New(srv.URL, "tk", "1.2.3").Get("/api/v1/whoami", nil); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "1.2.3" {
+		t.Errorf("%s header = %q, want %q", CLIVersionHeader, got, "1.2.3")
+	}
+}
+
+func TestNoVersionHeaderWhenEmpty(t *testing.T) {
+	seen := true
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, seen = r.Header[http.CanonicalHeaderKey(CLIVersionHeader)]
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = io.WriteString(w, `{"ok":true,"data":null}`)
+	}))
+	defer srv.Close()
+
+	if _, err := New(srv.URL, "tk", "").Get("/api/v1/whoami", nil); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if seen {
+		t.Errorf("version header should be omitted when version is empty")
+	}
+}
+
+func TestClientTooOldMessage(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusUpgradeRequired) // 426
+		_, _ = io.WriteString(w, `{"ok":false,"error":{"code":"ESV0005","meta":{"minVersion":"0.9.0","clientVersion":"0.1.0"}}}`)
+	}))
+	defer srv.Close()
+
+	_, err := New(srv.URL, "tk", "0.1.0").Get("/api/v1/whoami", nil)
+	if err == nil {
+		t.Fatal("expected an error for a too-old client")
+	}
+	var ae *APIError
+	if !errors.As(err, &ae) || ae.Code != CodeClientTooOld {
+		t.Fatalf("expected APIError with code %s, got %v", CodeClientTooOld, err)
+	}
+	msg := err.Error()
+	// The message must name both versions and steer the user to upgrade.
+	if !strings.Contains(msg, "0.9.0") || !strings.Contains(msg, "0.1.0") ||
+		!strings.Contains(strings.ToLower(msg), "upgrade") {
+		t.Errorf("compat message lacks versions/guidance: %q", msg)
+	}
+}
diff --git a/cli/internal/render/render.go b/cli/internal/render/render.go
new file mode 100644
index 00000000..4ede5095
--- /dev/null
+++ b/cli/internal/render/render.go
@@ -0,0 +1,192 @@
+// Package render handles CLI output formatting (text vs JSON) and the mapping
+// of errors to process exit codes per docs/arch/04-integration/02-cli.md.
+package render
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/apiclient"
+	"github.com/huhamhire/code-meeseeks/cli/internal/settings"
+	"gopkg.in/yaml.v3"
+)
+
+// Stdout / Stderr are the sinks for rendered output and errors. They default to
+// the process streams and are overridable in tests to capture output.
+var (
+	Stdout io.Writer = os.Stdout
+	Stderr io.Writer = os.Stderr
+)
+
+// Mode selects the output format.
+type Mode int
+
+const (
+	// ModeYAML renders responses as YAML — the default, human-friendly view
+	// (k8s `-o yaml` style): structured yet readable, and derived generically
+	// from any response without per-command formatters.
+	ModeYAML Mode = iota
+	// ModeJSON renders responses as JSON — the stable machine contract for
+	// third-party agents / tooling.
+	ModeJSON
+)
+
+// Process exit codes.
+const (
+	ExitOK       = 0
+	ExitGeneric  = 1
+	ExitAuth     = 2
+	ExitNotFound = 3
+)
+
+// Output writes API data to stdout per the selected mode: YAML (default,
+// human-friendly) or JSON (machine contract). Both are generic transforms of
+// the response data — no per-command formatting.
+func Output(mode Mode, data json.RawMessage) error {
+	if mode == ModeJSON {
+		return writeJSON(data)
+	}
+	return writeYAML(data)
+}
+
+func writeJSON(data json.RawMessage) error {
+	if len(data) == 0 {
+		fmt.Fprintln(Stdout, "null")
+		return nil
+	}
+	// Indent the raw bytes rather than unmarshal→marshal: json.Indent preserves the
+	// server's object key order (the view-layer field order), which decoding into a
+	// Go map would lose.
+	var buf bytes.Buffer
+	if err := json.Indent(&buf, data, "", "  "); err != nil {
+		fmt.Fprintln(Stdout, string(data))
+		return nil
+	}
+	buf.WriteByte('\n')
+	_, err := Stdout.Write(buf.Bytes())
+	return err
+}
+
+func writeYAML(data json.RawMessage) error {
+	if len(data) == 0 {
+		fmt.Fprintln(Stdout, "null")
+		return nil
+	}
+	// Build the YAML tree from the JSON token stream so object key order is preserved
+	// (a Go map would sort keys and drop the server's intended field order).
+	node, err := jsonToYAMLNode(data)
+	if err != nil {
+		// Not decodable as JSON — fall back to the raw payload.
+		fmt.Fprintln(Stdout, string(data))
+		return nil
+	}
+	out, err := yaml.Marshal(node)
+	if err != nil {
+		return err
+	}
+	_, err = Stdout.Write(out)
+	return err
+}
+
+// jsonToYAMLNode decodes JSON into a *yaml.Node tree, preserving object key order
+// (unlike decoding into map[string]any, which loses insertion order).
+func jsonToYAMLNode(data []byte) (*yaml.Node, error) {
+	dec := json.NewDecoder(bytes.NewReader(data))
+	dec.UseNumber()
+	return buildYAMLValue(dec)
+}
+
+func buildYAMLValue(dec *json.Decoder) (*yaml.Node, error) {
+	tok, err := dec.Token()
+	if err != nil {
+		return nil, err
+	}
+	if delim, ok := tok.(json.Delim); ok {
+		switch delim {
+		case '{':
+			m := &yaml.Node{Kind: yaml.MappingNode, Tag: "!!map"}
+			for dec.More() {
+				keyTok, err := dec.Token()
+				if err != nil {
+					return nil, err
+				}
+				key, _ := keyTok.(string)
+				val, err := buildYAMLValue(dec)
+				if err != nil {
+					return nil, err
+				}
+				m.Content = append(m.Content,
+					&yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: key}, val)
+			}
+			if _, err := dec.Token(); err != nil { // consume '}'
+				return nil, err
+			}
+			return m, nil
+		case '[':
+			s := &yaml.Node{Kind: yaml.SequenceNode, Tag: "!!seq"}
+			for dec.More() {
+				val, err := buildYAMLValue(dec)
+				if err != nil {
+					return nil, err
+				}
+				s.Content = append(s.Content, val)
+			}
+			if _, err := dec.Token(); err != nil { // consume ']'
+				return nil, err
+			}
+			return s, nil
+		}
+	}
+	return scalarYAMLNode(tok), nil
+}
+
+func scalarYAMLNode(tok json.Token) *yaml.Node {
+	switch t := tok.(type) {
+	case string:
+		return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!str", Value: t}
+	case json.Number:
+		tag := "!!int"
+		if strings.ContainsAny(t.String(), ".eE") {
+			tag = "!!float"
+		}
+		return &yaml.Node{Kind: yaml.ScalarNode, Tag: tag, Value: t.String()}
+	case bool:
+		v := "false"
+		if t {
+			v = "true"
+		}
+		return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!bool", Value: v}
+	default: // nil
+		return &yaml.Node{Kind: yaml.ScalarNode, Tag: "!!null", Value: "null"}
+	}
+}
+
+// Errorln prints an error to stderr.
+func Errorln(err error) {
+	fmt.Fprintln(Stderr, "error:", err)
+}
+
+// ExitCodeFor maps an error to a process exit code.
+func ExitCodeFor(err error) int {
+	if err == nil {
+		return ExitOK
+	}
+	if errors.Is(err, settings.ErrNoToken) {
+		return ExitAuth
+	}
+	var ae *apiclient.APIError
+	if errors.As(err, &ae) {
+		switch {
+		case ae.Status == 401 || ae.Status == 403:
+			return ExitAuth
+		case ae.Status == 404:
+			return ExitNotFound
+		}
+	}
+	return ExitGeneric
+}
diff --git a/cli/internal/render/render_test.go b/cli/internal/render/render_test.go
new file mode 100644
index 00000000..226414ab
--- /dev/null
+++ b/cli/internal/render/render_test.go
@@ -0,0 +1,119 @@
+package render
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/huhamhire/code-meeseeks/cli/internal/apiclient"
+	"github.com/huhamhire/code-meeseeks/cli/internal/settings"
+)
+
+func TestExitCodeFor(t *testing.T) {
+	cases := []struct {
+		name string
+		err  error
+		want int
+	}{
+		{"nil", nil, ExitOK},
+		{"no token", settings.ErrNoToken, ExitAuth},
+		{"401 unauthorized", &apiclient.APIError{Status: 401}, ExitAuth},
+		{"403 forbidden", &apiclient.APIError{Status: 403}, ExitAuth},
+		{"404 not found", &apiclient.APIError{Status: 404}, ExitNotFound},
+		{"500 server", &apiclient.APIError{Status: 500}, ExitGeneric},
+		{"generic", errors.New("boom"), ExitGeneric},
+	}
+	for _, c := range cases {
+		if got := ExitCodeFor(c.err); got != c.want {
+			t.Errorf("%s: got %d, want %d", c.name, got, c.want)
+		}
+	}
+}
+
+func TestOutputYAMLAndJSON(t *testing.T) {
+	orig := Stdout
+	defer func() { Stdout = orig }()
+	var buf bytes.Buffer
+	Stdout = &buf
+
+	data := json.RawMessage(`{"platform":"github","primary":["review-requested"]}`)
+
+	// YAML (default, human-friendly)
+	buf.Reset()
+	if err := Output(ModeYAML, data); err != nil {
+		t.Fatalf("yaml output: %v", err)
+	}
+	if got := buf.String(); !strings.Contains(got, "platform: github") {
+		t.Errorf("yaml output missing key: %q", got)
+	}
+
+	// JSON (machine contract) — must be valid, re-parseable JSON
+	buf.Reset()
+	if err := Output(ModeJSON, data); err != nil {
+		t.Fatalf("json output: %v", err)
+	}
+	var v map[string]any
+	if err := json.Unmarshal(buf.Bytes(), &v); err != nil {
+		t.Fatalf("json output not valid JSON: %v (%q)", err, buf.String())
+	}
+	if v["platform"] != "github" {
+		t.Errorf("json output wrong platform: %v", v["platform"])
+	}
+}
+
+// TestOutputPreservesKeyOrder locks in that both renderers keep the server's object
+// key order (the view-layer field order) rather than sorting keys alphabetically.
+func TestOutputPreservesKeyOrder(t *testing.T) {
+	orig := Stdout
+	defer func() { Stdout = orig }()
+	var buf bytes.Buffer
+	Stdout = &buf
+
+	// Keys deliberately out of alphabetical order; also exercises int / bool / array scalars.
+	data := json.RawMessage(
+		`{"id":"abc","title":"fix","author":"alice","createdAt":"2026-01-01",` +
+			`"unreadMentionCount":0,"mergeable":true,"categories":["created"]}`)
+
+	assertKeyOrder := func(mode Mode, keys []string) {
+		buf.Reset()
+		if err := Output(mode, data); err != nil {
+			t.Fatalf("output: %v", err)
+		}
+		s := buf.String()
+		last := -1
+		for _, k := range keys {
+			idx := strings.Index(s, k)
+			if idx < 0 {
+				t.Fatalf("missing %q in %q", k, s)
+			}
+			if idx < last {
+				t.Fatalf("key %q out of order in %q", k, s)
+			}
+			last = idx
+		}
+	}
+	assertKeyOrder(ModeYAML, []string{"id:", "title:", "author:", "createdAt:"})
+	assertKeyOrder(ModeJSON, []string{`"id"`, `"title"`, `"author"`, `"createdAt"`})
+
+	// int / bool scalars render unquoted (not as strings)
+	buf.Reset()
+	_ = Output(ModeYAML, data)
+	if y := buf.String(); !strings.Contains(y, "unreadMentionCount: 0") || !strings.Contains(y, "mergeable: true") {
+		t.Errorf("scalar typing lost in yaml: %q", y)
+	}
+}
+
+func TestOutputEmptyData(t *testing.T) {
+	orig := Stdout
+	defer func() { Stdout = orig }()
+	var buf bytes.Buffer
+	Stdout = &buf
+	if err := Output(ModeYAML, nil); err != nil {
+		t.Fatal(err)
+	}
+	if strings.TrimSpace(buf.String()) != "null" {
+		t.Errorf("empty data should print null, got %q", buf.String())
+	}
+}
diff --git a/cli/internal/settings/settings.go b/cli/internal/settings/settings.go
new file mode 100644
index 00000000..2b2d5b26
--- /dev/null
+++ b/cli/internal/settings/settings.go
@@ -0,0 +1,146 @@
+// Package settings resolves the API base URL and bearer token used by the CLI,
+// following the precedence documented in docs/arch/04-integration/02-cli.md:
+// flag > env > CLI config file (~/.code-meeseeks/cli.yaml).
+//
+// The CLI deliberately does NOT read the GUI's config.yaml: that file holds
+// connection-layer secrets (platform tokens etc.), and silently sourcing the
+// service token from it would let the CLI reach into credentials it has no
+// business touching. Connection details must be provided explicitly.
+package settings
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"gopkg.in/yaml.v3"
+)
+
+// Environment variable names for connection settings.
+const (
+	EnvAPIURL = "MEEBOX_API_URL"
+	EnvToken  = "MEEBOX_TOKEN"
+)
+
+const (
+	defaultHost = "127.0.0.1"
+	defaultPort = 18765
+)
+
+// Overrides carries the highest-precedence values, typically from CLI flags.
+type Overrides struct {
+	APIURL string
+	Token  string
+}
+
+// Settings is the resolved connection configuration.
+type Settings struct {
+	APIURL string
+	Token  string
+}
+
+// ErrNoToken indicates no bearer token could be resolved from any source.
+var ErrNoToken = errors.New("no API token: pass --token, set " + EnvToken +
+	", or add `token` to ~/.code-meeseeks/cli.yaml")
+
+// Resolve applies the documented precedence (lowest first, overwritten by
+// higher sources) and returns the final connection settings.
+func Resolve(ov Overrides) (Settings, error) {
+	var s Settings
+
+	// 3) lowest precedence: CLI config file.
+	if cfg, ok := loadCLIConfig(); ok {
+		if cfg.APIURL != "" {
+			s.APIURL = cfg.APIURL
+		}
+		if cfg.Token != "" {
+			s.Token = cfg.Token
+		}
+	}
+	// 2) environment.
+	if v := os.Getenv(EnvAPIURL); v != "" {
+		s.APIURL = v
+	}
+	if v := os.Getenv(EnvToken); v != "" {
+		s.Token = v
+	}
+	// 1) highest precedence: flags.
+	if ov.APIURL != "" {
+		s.APIURL = ov.APIURL
+	}
+	if ov.Token != "" {
+		s.Token = ov.Token
+	}
+
+	if s.APIURL == "" {
+		s.APIURL = DefaultAPIURL()
+	}
+	if s.Token == "" {
+		return Settings{}, ErrNoToken
+	}
+	return s, nil
+}
+
+// DefaultAPIURL is the loopback API base URL used when none is provided.
+func DefaultAPIURL() string {
+	return fmt.Sprintf("http://%s:%d", defaultHost, defaultPort)
+}
+
+// Save writes the connection settings to ~/.code-meeseeks/cli.yaml (creating the directory
+// if needed) with owner-only file permissions, since the token is a secret. It overwrites
+// any existing CLI config. Returns the path written. This is the write counterpart to the
+// cli.yaml read in Resolve — the CLI's `login` command uses it to persist credentials.
+func Save(s Settings) (string, error) {
+	home, ok := appHome()
+	if !ok {
+		return "", errors.New("cannot resolve home directory")
+	}
+	if err := os.MkdirAll(home, 0o700); err != nil {
+		return "", err
+	}
+	path := filepath.Join(home, "cli.yaml")
+	data, err := yaml.Marshal(cliConfig{APIURL: s.APIURL, Token: s.Token})
+	if err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(path, data, 0o600); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+// appHome returns the app's fixed data directory (~/.code-meeseeks), shared by the GUI
+// and CLI. The CLI's own config (cli.yaml) lives here; the GUI's config.yaml also lives
+// here but the CLI never reads it (see package doc).
+func appHome() (string, bool) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", false
+	}
+	return filepath.Join(home, ".code-meeseeks"), true
+}
+
+// cliConfig is the CLI's own optional config file.
+type cliConfig struct {
+	APIURL string `yaml:"api_url"`
+	Token  string `yaml:"token"`
+}
+
+// loadCLIConfig reads the CLI config at ~/.code-meeseeks/cli.yaml — co-located with the
+// GUI config but a separate file, isolating CLI settings from the GUI's config.yaml.
+func loadCLIConfig() (cliConfig, bool) {
+	home, ok := appHome()
+	if !ok {
+		return cliConfig{}, false
+	}
+	data, err := os.ReadFile(filepath.Join(home, "cli.yaml"))
+	if err != nil {
+		return cliConfig{}, false
+	}
+	var cfg cliConfig
+	if err := yaml.Unmarshal(data, &cfg); err != nil {
+		return cliConfig{}, false
+	}
+	return cfg, true
+}
diff --git a/cli/internal/settings/settings_test.go b/cli/internal/settings/settings_test.go
new file mode 100644
index 00000000..0fb70e3a
--- /dev/null
+++ b/cli/internal/settings/settings_test.go
@@ -0,0 +1,75 @@
+package settings
+
+import (
+	"errors"
+	"testing"
+)
+
+// isolateHome points HOME / USERPROFILE at an empty temp dir so os.UserHomeDir
+// resolves there — keeping Resolve's CLI config lookup (~/.code-meeseeks/cli.yaml)
+// from reading the developer's real file and making these tests non-hermetic.
+func isolateHome(t *testing.T) {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+	t.Setenv("USERPROFILE", dir)
+}
+
+func TestResolveFlagsWinOverEnv(t *testing.T) {
+	isolateHome(t)
+	t.Setenv(EnvAPIURL, "http://env:1")
+	t.Setenv(EnvToken, "env-token")
+
+	got, err := Resolve(Overrides{APIURL: "http://flag:2", Token: "flag-token"})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got.APIURL != "http://flag:2" || got.Token != "flag-token" {
+		t.Fatalf("flags should win, got %+v", got)
+	}
+}
+
+func TestResolveDefaultsURLWhenOnlyTokenGiven(t *testing.T) {
+	isolateHome(t)
+	t.Setenv(EnvAPIURL, "")
+	t.Setenv(EnvToken, "env-token")
+
+	got, err := Resolve(Overrides{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got.Token != "env-token" {
+		t.Fatalf("expected env token, got %q", got.Token)
+	}
+	if got.APIURL == "" {
+		t.Fatalf("expected a default API URL")
+	}
+}
+
+func TestResolveNoTokenErrors(t *testing.T) {
+	isolateHome(t)
+	t.Setenv(EnvAPIURL, "http://x:1")
+	t.Setenv(EnvToken, "")
+
+	if _, err := Resolve(Overrides{}); !errors.Is(err, ErrNoToken) {
+		t.Fatalf("expected ErrNoToken, got %v", err)
+	}
+}
+
+func TestSaveThenResolveRoundTrips(t *testing.T) {
+	isolateHome(t)
+	t.Setenv(EnvAPIURL, "")
+	t.Setenv(EnvToken, "")
+
+	if _, err := Save(Settings{APIURL: "http://saved:9", Token: "saved-token"}); err != nil {
+		t.Fatalf("save failed: %v", err)
+	}
+	// With no flags/env, Resolve must read back exactly what Save wrote.
+	got, err := Resolve(Overrides{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got.APIURL != "http://saved:9" || got.Token != "saved-token" {
+		t.Fatalf("round-trip mismatch, got %+v", got)
+	}
+}
diff --git a/cli/main.go b/cli/main.go
new file mode 100644
index 00000000..3e6130bf
--- /dev/null
+++ b/cli/main.go
@@ -0,0 +1,25 @@
+// Command meebox is the CLI client for the Code Meeseeks local API.
+//
+// It is a thin client over the desktop app's local HTTP API (see
+// docs/arch/04-integration). All exposed capabilities are read-only;
+// write operations (commenting, approving, publishing) are intentionally
+// not provided — integrators implement those against the platform directly.
+package main
+
+import (
+	_ "embed"
+
+	"github.com/huhamhire/code-meeseeks/cli/cmd"
+)
+
+// skillDoc is SKILL.md embedded at build time so the binary can self-document its agent
+// usage (`meebox skill`) even when detached from its release archive. Embedding keeps the
+// emitted doc in lock-step with the shipped SKILL.md. The embed must live in this root
+// package because SKILL.md sits at the module root (go:embed cannot reach parent dirs).
+//
+//go:embed SKILL.md
+var skillDoc string
+
+func main() {
+	cmd.Execute(skillDoc)
+}
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 88774b95..31e28935 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -78,7 +78,8 @@
 ### 进行中 / 待办 ⏭️
 
 - [ ] **可观测性扩展**：规则命中率、模型对比（token 用量已做）。
-- [ ] **外部集成扩展与 CLI**：下个版本方向——扩展与外部系统 / 工具的集成，并提供 CLI 能力。
+- [ ] **外部集成扩展与 CLI**：下个版本（0.9.0）方向——主进程内置本地 API + 独立 CLI，使外部 agent / 工具
+  可集成应用能力（设计见 [服务监听与本地 API](arch/04-integration/01-service-api.md) · [CLI 工具](arch/04-integration/02-cli.md)）。
 
 ---
 
diff --git a/docs/arch/00-overview.md b/docs/arch/00-overview.md
index d0d3d83a..17a41090 100644
--- a/docs/arch/00-overview.md
+++ b/docs/arch/00-overview.md
@@ -62,6 +62,9 @@ flowchart TB
   - [命令面板](03-gui/02-command-palette.md) —— 渲染层标题栏入口 + 分域命令注册表
   - [消息通知](03-gui/03-notifications.md) —— `poller` 事件投影 + 主进程系统通知 / dock 角标
   - [国际化](03-gui/04-i18n.md) —— react-i18next + 主 / 渲染双运行时 locale
+- **`04-integration/`** —— 外部集成扩展与 CLI
+  - [服务监听与本地 API](04-integration/01-service-api.md) —— 主进程内置 HTTP API（IPC 之外的第二前端）
+  - [CLI 工具](04-integration/02-cli.md) —— Go 独立二进制，经本地 API 消费应用能力
 - **`99-core/`** —— 基础设施
   - [状态存储与数据模型](99-core/01-state-storage.md) —— `state-store` + `poller` 的 pr-state
   - [配置与凭据](99-core/02-config-and-secrets.md) —— `config` + 设置页
diff --git a/docs/arch/01-platform/02-repo-mirror.md b/docs/arch/01-platform/02-repo-mirror.md
index 78ad228a..15041a24 100644
--- a/docs/arch/01-platform/02-repo-mirror.md
+++ b/docs/arch/01-platform/02-repo-mirror.md
@@ -18,7 +18,8 @@
 - **全局串行 sync 队列**：任意时刻只有一个仓库在 clone/fetch——多个调用方（切 PR / 定时）共用同一队列，
   不并发打远端、不抢 git 带宽，进度更稳；同一仓库的并发请求复用同一 in-flight Promise。读操作不走队列。
 - **worktree 物化**：从本地 bare **`git clone --local --no-checkout`** 派生独立 repo（同盘 objects 走 hardlink，
-  磁盘 ~0、跨 mount 边界也成立），再建两个内部分支 `meebox/head` / `meebox/base` 指向 PR 的 head/base sha。
+  磁盘 ~0、跨 mount 边界也成立），再建两个内部分支 `pr-<localId>/head` / `pr-<localId>/base` 指向 PR 的 head/base sha
+  （localId = 每-PR 稳定主键，与 PR 关联便于追溯、不带工具品牌前缀；无 localId 时回退随机 nonce）。
   pr-agent 的 LocalGitProvider 在这个 worktree 上算 diff（见 [pr-agent 运行时](../02-agent/05-pragent-runtime.md)）。
 - **Diff 不 checkout 文件**：展示 diff 只需按 sha 读 blob（`git show <sha>:<path>`）+ 改动文件列表，
   不把文件 checkout 到磁盘，省 IO。Monaco 侧按文件懒加载，二进制/超大文件跳过。
diff --git a/docs/arch/02-agent/06-tool-token-cost.md b/docs/arch/02-agent/06-tool-token-cost.md
new file mode 100644
index 00000000..819902b9
--- /dev/null
+++ b/docs/arch/02-agent/06-tool-token-cost.md
@@ -0,0 +1,80 @@
+# 工具 token 成本与上下文分层
+
+## 职责与边界
+
+聚焦 pr-agent 各工具（`/describe` `/review` `/improve` `/ask`）与自由对话 Agent 的**上下文来源与 token
+成本模型**：上下文分几层、成本在哪一层放量、以何种手段收敛而不牺牲评审深度。运行时机制（调用桥 / 嵌入式
+Python / monkeypatch / token 采集）见 [pr-agent 集成与运行时](05-pragent-runtime.md)；会话 Agent 化与规划循环见
+[会话 Agent 化](02-session.md)；worktree 物化见 [仓库镜像](../01-platform/02-repo-mirror.md)。
+
+结论先行：成本放量集中在「本机 agentic CLI 提供方下的 `/ask`」与「自由对话 Agent 的规划循环」——前者一次
+探索可跨多轮读文件，后者可连发多次这样的 `/ask`。**不存在「diff-only 的盲评审」**：pr-agent 默认已把变更的
+近端上下文（所在函数 / 类、周边行、整份新文件、best-practices）注入 prompt。
+
+## 三层上下文模型
+
+评审上下文并非「diff vs 全仓」二选一，而是三层递进：
+
+| 层 | 上下文 | 成本 | 本仓何处使用 |
+|----|--------|------|-------------|
+| 1 · 裸 diff | 仅 `+/-` 行 | 极低 | 无（不单独使用） |
+| 2 · **展开 diff（pr-agent 默认）** | diff + 动态上下文补到**所在函数 / 类** + hunk 周边行 + 整份新文件 + best-practices | **有界、确定**（受 `MAX_MODEL_TOKENS` 约束） | `/review` `/describe` `/improve`，以及 `/ask` 的基座 |
+| 3 · agentic 探索 | 按需读任意文件、跟调用链、跨文件核对 | **无界**（轮次 × 累计上下文，近平方增长） | 仅 `/ask` + CLI 提供方（下发 worktree cwd）；自由对话 Agent 可跨步多次触发 |
+
+第 2 层是 pr-agent 对「裸 diff 不足以评审」的既定答案：以确定成本纳入变更的近端爆炸半径，而非放 agent 自由
+探索。pr-agent 默认即开（[configuration.toml](../../../apps/desktop/vendor/pragent/python/Lib/site-packages/pr_agent/settings/configuration.toml)：
+`allow_dynamic_context=true`、`patch_extra_lines_before=5`/`_after=1`、`max_extra_lines_before_dynamic_context=10`、
+`best_practices` 等），本应用未覆盖这些默认，故 `/review` 天然享有第 2 层上下文——缺的是**远端**上下文（别处
+文件的调用方、跨模块契约、数个文件外的不变量）。
+
+第 3 层只在 CLI-`/ask`：`buildInvocation` 仅当 `tool==='ask' && provider==='cli'` 时下发 `MEEBOX_CLI_WORKDIR`，让
+agentic CLI 在 worktree 里读文件、多轮迭代。此时 CLI **仍先拿到 pr-agent 渲染的展开 diff**（见 pr_questions 模板
+的 `The PR Git Diff`）——它不是「只有问题、从零翻找」，而是「已有第 2 层、再探第 3 层」。
+
+## 成本驱动
+
+- **CLI-`/ask` 的 agentic 探索（第 3 层）**：worktree 可读、无轮次上限，倾向整文件通读 / 全仓扫描；每轮携带
+  不断增长的对话 + 工具结果重传，近平方增长。CLI 模式下 `MAX_MODEL_TOKENS` 被忽略（CLI 自管上下文窗口），
+  无应用侧输入上限。
+- **自由对话 Agent 的规划循环**：仅受「Agent 最大步数」`max_steps`（默认 8）约束，可跨多步连发 `/ask`，每次都是
+  一次第 3 层探索——若不另加约束，成本随步数叠加而失控。
+
+第 2 层（含 API 提供方的 `/ask`、所有 review/describe/improve）是单轮、受 token 预算硬约束的确定成本。
+
+## 优化措施
+
+目标：让第 2 层足够充分（廉价、确定），让第 3 层的**必要**探索更高效、**数量**受控——而非砍掉探索降级评审。
+
+### 已实现
+
+- **CLI-`/ask` 只读代码检索指引**：`buildExtraInstructions` 的 `worktreeRetrievalDirective`（仅 CLI 提供方注入）
+  引导以 diff 为改动真源、**定向搜符号 · 只读所需行段**替代整文件通读与全仓扫描，够用即止。刻意只用**只读**
+  工具集——headless（无 TTY）下 claude default 权限模式对内置只读工具（Read/Grep、以及 `grep`·`git log/show`
+  等只读 Bash 命令）静默放行、无授权摩擦，但对非只读工具（写、以及 `rg` 等不在内置只读白名单的命令）不是
+  拒绝而是**直接中止会话**，故明确「用 `grep` 不用 `rg`」、禁止改动类命令。只依赖「内置只读工具静默放行」这一
+  跨版本稳定语义，不加 `--allowedTools`/`--permission-mode` 等依赖具体 claude 版本的启动参数。
+- **自由对话 Agent 的 `/ask` 预算**：规划循环按配置「追问数量」`max_followup_asks` 对本会话 `/ask` 计数封顶，
+  达上限即在红线校验处拒绝新的 `/ask` 并回喂（促模型据现有上下文收尾或改用只读工具）；`describe/review/improve`
+  不受此约束、`max_steps` 不变。**count-only**：始终按配置的追问数量生效，与「自动追问」开关无关（开关仅约束
+  评审微流程的条件追问）。评审微流程侧的条件追问（judge 步）与本预算共用同一配置值。
+
+### 已否决
+
+- **给 CLI-`/ask` 前置注入统一 diff**：CLI-`/ask` 的 prompt 已由 pr_questions 模板携带 pr-agent 的展开 diff（第 2
+  层），再注入一份只是重复上下文、徒增 prompt，且不减少第 3 层探索（探索是为拿 diff 之外的远端上下文）。
+
+### 待评估（暂缓）
+
+- **codegraph 作为检索工具**：把「盲读」换成「定向查（定义 / 调用方 / 影响面）」，收敛第 3 层浪费。**仅适用于
+  有工具循环的 agentic 路径（`/ask`）**：作为 MCP server 挂给 headless CLI。`/review` 是单轮工具、无工具循环，
+  codegraph 对它只能是 **orchestrator 侧预注入**（组 prompt 时选取远端上下文拼进第 2 层），而非「传给 review 的
+  工具」。成本：worktree 每次物化即临时，需每次建图或改对长驻镜像增量维护并保鲜；claude 支持 MCP、codex 不支持
+  外部 MCP 注入。宜在既有措施仍不足时再上。
+- **单次 `/ask` 的 agentic 轮次上限**（claude `--max-turns`）：作安全兜底、非成本主手段；依赖具体 CLI 版本对该
+  旗标的支持，暂不引入。
+
+## 关联
+
+- [pr-agent 集成与运行时](05-pragent-runtime.md)：调用桥 / 嵌入式运行时 / monkeypatch / token 采集 / env 注入。
+- [会话 Agent 化](02-session.md)：规划循环（ReAct）、步数上限、过程留存。
+- [仓库镜像](../01-platform/02-repo-mirror.md)：worktree 物化与三点 diff 口径。
diff --git a/docs/arch/03-gui/03-notifications.md b/docs/arch/03-gui/03-notifications.md
index 1850cd94..1b490f61 100644
--- a/docs/arch/03-gui/03-notifications.md
+++ b/docs/arch/03-gui/03-notifications.md
@@ -4,7 +4,7 @@
 
 ## 范围
 
-- **系统通知（toast）**：Windows + macOS 原生通知，按事件类型（新 PR / 评论回复 / 评论 @）分别开关。
+- **系统通知（toast）**：Windows + macOS 原生通知，按事件类型分别开关——面向评审的（新 PR / 评论回复 / 评论 @）与面向「我创建的」PR 的（新评论 / 被标记需修改 / 出现冲突）。
 - **macOS dock 角标**：dock 图标上显示「@我 / 回复我」待回应总数。
 - 不纳入常驻状态栏 / Windows 任务栏 overlay 与闪烁（成本偏重，收益有限）。
 
@@ -12,10 +12,15 @@
 
 ### 1. 系统通知：poll 事件投影 → 主进程 toast
 
-- **投影（poller）**：`pollOnce` 在常规扫描中顺带产出本轮「值得提醒」事件 `PollNotificationEvent[]`（`kind: new_pr | mention | reply` + PR 标识/标题 + 条数），经 `onNotify` 回调交主进程。复用既有评论拉取，按下文「评论跟踪触发」决定何时扫。
+- **投影（poller）**：`pollOnce` 在常规扫描中顺带产出本轮「值得提醒」事件 `PollNotificationEvent[]`（`kind: new_pr | mention | reply | authored_comment | authored_needs_work | authored_conflict` + PR 标识/标题 + 条数），经 `onNotify` 回调交主进程。复用既有评论拉取，按下文「评论跟踪触发」决定何时扫。
   - **新 PR**：`isAdded` 的 PR。
   - **@ / 回复**：评论扫描用 [`collectMentionsToMe`](../../../packages/poller/src/unread.ts)（按「父评论作者是我=reply / 正文 @我=mention」分类，每条命中带评论作者），取**晚于历史游标 `lastMentionAt`** 的命中、按类型聚合条数。
-  - 事件还带 `repo` / `connectionId` / `actor`（发起人：new_pr=PR 作者，mention/reply=该类最新一条命中的评论作者），供富样式通知用。
+  - **「我创建的」PR（作者为本人，`pr.author` == 当前用户）**——仅对这类 PR 额外产出：
+    - `authored_comment`：他人新评论（用 [`collectCommentsFromOthers`](../../../packages/poller/src/unread.ts) 收全部非本人评论，取晚于独立游标 `lastCommentAt` 的；自己的评论不计，故不会因自评误报）。
+    - `authored_needs_work`：新出现的「需修改」评审人（本轮在 needsWork、上一轮 `needsWorkReviewers` 不在）。
+    - `authored_conflict`：合并冲突 `hasConflict` false→true。
+    - 三者的「上一轮快照」（`lastCommentAt` / `needsWorkReviewers` / `hasConflict`）存于索引条目；快照字段缺失（升级前旧索引）时按基线只播种、不补发。
+  - 事件还带 `repo` / `connectionId` / `actor`（发起人：new_pr=PR 作者，mention/reply/authored_comment=该类最新一条命中的评论作者，authored_needs_work=新标记需修改的评审人，authored_conflict=PR 作者）。
 - **防风暴**：仅在**已有基线**（本轮之前索引非空）时产出事件——首启 / 清库后的首轮只建基线、不弹通知；新发现 PR 的历史评论不投影为 mention/reply（`prev` 不存在则跳过）。
 - **仅「待处理」**：事件只对 `localStatus === 'pending'` 的 PR 产出（投影处 `notifiable = hadBaseline && localStatus === 'pending'` 门控）——已 approve / 标记 needs_work 的 PR 不再打扰。「待处理」天然覆盖「待我评审」（未决断）与「我创建的」（作者非评审人 → 恒 pending）两类。
 - **点击定位**：mention/reply 事件带 `comment`（最新一条命中评论的 `remoteId` + `anchor`），供点击跳转。
@@ -60,7 +65,8 @@
 | 字段 | 含义 |
 | --- | --- |
 | `enabled` | 总开关；关闭后既不弹系统通知也不亮 dock 角标 |
-| `new_pr` / `reply` / `mention` | 分类型系统通知开关 |
+| `new_pr` / `reply` / `mention` | 面向评审的分类型系统通知开关 |
+| `authored_comment` / `authored_needs_work` / `authored_conflict` | 面向「我创建的」PR 的分类型开关（新评论 / 被标记需修改 / 出现冲突）；默认开 |
 
 macOS dock「待回应」计数角标随总开关默认启用，无独立配置项。
 
diff --git a/docs/arch/04-integration/01-service-api.md b/docs/arch/04-integration/01-service-api.md
new file mode 100644
index 00000000..d0d0cafa
--- /dev/null
+++ b/docs/arch/04-integration/01-service-api.md
@@ -0,0 +1,177 @@
+# 服务监听与本地 API
+
+## 职责与边界
+
+在主进程内提供一个**本地 HTTP API**，把应用既有的 PR 发现 / 浏览 / Agent 操作能力，以语言无关的
+线协议暴露给**外部 agent / 工具 / 脚本**（经 [CLI](02-cli.md) 或直接 HTTP 调用）。是继渲染层 IPC
+之后的**第二个前端**——同一套主进程 service 层，换一层入站协议。
+
+负责：服务监听开关与生命周期、bearer token 鉴权、请求路由与响应封装、把内部能力映射成稳定的 HTTP 契约。
+
+开放的**写操作**限定为评审动作：approve / needswork（远端评审决断）与顶层 comment（发评论），复用
+GUI 同源 controller（见下「写边界」）。另有 `POST …/refresh` 触发一次本地轮询刷新——虽用 POST，但
+**无远端写副作用**（纯读远端 + 落本地），不属评审写动作范畴，与合并 / 变更类工具的禁令无关。
+
+**不负责**：
+
+- **合并与 pr-agent 变更类工具** —— merge（合并 PR）、pr-agent 的 publish 等变更工具不开放；有此需求由
+  调用方自行用平台 API 实现（见下「写边界」）。
+- **多用户 / 远端服务形态** —— 仍是单用户本地应用，API 只是本机（或可选局域网）的入站通道，不引入账户体系。
+- 业务逻辑本身 —— 复用 IPC controller 同源的 service 层，不在 HTTP 侧另起一套实现。
+
+## 核心设计
+
+### 默认关闭、强制鉴权
+
+- **默认不启用**：`config.yaml` 新增 `service` 段，`enabled` 默认 `false`。不开启则主进程不监听任何端口，
+  对外零暴露面。
+- **强制 bearer token**：开启监听即要求 token——所有请求须带 `Authorization: Bearer <token>`，缺失 / 不匹配
+  直接拒绝（401 + 错误码）。**没有「关闭鉴权」选项**。开关首次打开时若 token 为空则**自动生成**一枚高强度
+  随机 token（`crypto.randomBytes` → base64url / hex），保证「启用」与「有 token」原子绑定。
+- **比对用常数时间**：token 校验走常数时间比较，避免计时侧信道。
+- **token 落盘策略同既有凭据**：token 明文存 `config.yaml`（与平台 token / LLM key / 代理密码一致，经
+  `SecretStore` 抽象读写、绝不进日志 / 异常栈），属已知风险、文件权限收紧。将来切 keychain 时随既有凭据一并迁移。
+
+### 监听地址与端口
+
+- **默认仅 loopback**：`host` 默认 `127.0.0.1`，只本机可达。这是绝大多数「本机外部 agent 集成」场景的安全默认。
+- **可选 `0.0.0.0`**：允许配置为监听所有网卡（供同网段的远端 agent / CI 节点接入）。这是**显式高风险选项**——
+  设置页与文档须给安全警示（token 即唯一防线、建议配合防火墙 / 反代）。绑 `0.0.0.0` 时 token 强度与保密尤为关键。
+- **固定安全默认端口**：默认 `18765`（可在配置中改）。取 10000+ 既避开拥挤的 8xxx 开发 / 系统服务段
+  （3000 / 5173 / 8000 / 8080 / 8888 等），又稳落在**临时端口范围（ephemeral，Windows 49152+ / Linux 32768+）
+  之下**——固定监听端口若落进临时段可能与系统瞬时出站 socket 抢占，`18765` 处于已注册端口段、无此风险。
+  端口被占用导致监听失败时，记录错误并以非致命方式提示（不阻塞应用启动）。
+
+### HTTP 实现：最小依赖
+
+- 用 Node 内置 `http` 起服务 + **极简手写路由**（按 method + path 模式匹配），**不引入 express 等重型框架**——
+  与项目「优先复用、最小依赖」一致，端点数量有限、无需框架。
+- 统一中间环节：JSON body 解析（带最大 body 上限）、请求超时、鉴权校验、错误 → 响应封装、访问日志
+  （记 method / path / status / 耗时，**不记** token 与敏感 body）。
+
+### 路由复用 service 层
+
+- HTTP route handler 经与 IPC controller **同一个进程级 `ControllerContext`**（`getContext()`）取用 service
+  （`ctx.pr` / `ctx.orchestrator` / `ctx.poller` / `ctx.connectionRuntime` 等），**不重复业务逻辑**。
+- 原则：核心能力沉在 service 层，IPC 与 HTTP 各自只做**薄封装 + 协议适配**。新增 API 端点前，先确保对应能力
+  在 service 层有可复用方法（必要时把 controller 内联逻辑下沉到 service）。
+- **路由按领域分模块**：HTTP 路由处理器按业务领域（系统性 / PR / Agent）分置于独立模块，聚合层只做**注册与路径
+  匹配**、不含业务逻辑——与 [CLI](02-cli.md) 命令树的领域划分对称，新增端点归入对应域、便于定位与扩展。
+
+### CLI 版本兼容门控
+
+服务端对**所有 API 调用**统一做 CLI 版本门控（不按端点差异化）：
+
+- CLI 每个请求带版本头 `X-Meebox-CLI-Version: <version>` 声明自身版本（取自与 app 同源的版本，见 [CLI](02-cli.md)）。
+- 服务端集中管理**最低可兼容 CLI 版本**，请求中间件比对：版本头**可解析且低于下限** → 拦截，返回
+  `426 Upgrade Required` + 错误码 `SV_CLIENT_TOO_OLD`（meta 带 `minVersion` / `clientVersion`）。
+- **默认宽松**：缺版本头（旧 CLI / 非 CLI 客户端）或版本不可解析（如本地 `dev` 构建）→ 放行，保证既有 CLI
+  默认可用；破坏性线协议变更时上调最低版本即门控掉更旧的 CLI。
+- **按版本线比对、忽略预发布后缀**：比对前把版本 coerce 到 `major.minor.patch`。CLI 与 app 同源发版，预发布
+  构建（如 `0.9.0-alpha.1`）与其正式版同属一条版本线、共享同一线协议；semver 中预发布低于其正式版，若不忽略
+  后缀会把与下限同线的预发布 CLI 误判为过旧（下限 `0.9.0` 时连 `0.9.0-alpha.1` 都会被拦）。下限即版本线粒度
+  的破坏性变更闸门，不区分同线内的预发布序号。
+- CLI 收到该错误码即输出明确的「CLI 过旧、请升级」提示（含双方版本），不裸报 HTTP 错误。
+
+### 写边界（放开评审动作，拒绝合并与变更类 Agent 工具）
+
+- 开放的写操作**限定评审动作**：`POST …/approve`·`…/needswork`（远端评审决断，复用 `prs:setLocalStatus`——
+  先写远端评审状态、再落本地）与 `POST …/comment`（发顶层评论，复用 `comments:create`）。均为真实远端写。
+- Agent 指令（`…/agent/instruct`）**仍限只读工具**（`/describe`·`/review`·`/ask`·`/improve`）；变更类工具
+  （`/publish` 等，见工具注册表 `kind: 'mutating'`）**在 API 层即被硬拒绝**——与 Agent 自身 grant 授权闸
+  **相互独立**：即便某 PR 的 AutoPilot grants 授予了写权限，经 API 的 instruct 仍不得触发写工具。评审写动作
+  改走上面的 approve / needswork / comment 专用端点，不经 instruct。
+- **不开放合并（merge）**：对远端影响大且不可逆，暂不纳入 API。
+- **无二次确认**：API 无交互确认通道；已开放的写端点直接执行（调用方自负授权），需交互确认的动作（如合并）
+  干脆不开放。
+
+### 生命周期与热生效
+
+- **启动时机**：在主进程完成连接 / IPC 初始化（`ControllerContext` 就绪）之后、轮询启动前后启动监听器；
+  仅当 `service.enabled` 为真才实际 `listen`。
+- **优雅关闭**：应用退出（`before-quit`）时关闭监听、停止接收新连接、放行 in-flight 请求后退出。
+- **热生效**：`enabled` / `host` / `port` / token 变更 → 写盘 + 内存同步 + **停旧监听起新监听**（端口 / 地址变更
+  必然重建；token 变更即时生效，旧 token 立刻失效）。与既有「保存即热生效」一致，无需重启应用。
+
+### 并发与资源
+
+- 只读 `GET` 端点可并发处理。
+- Agent 写入型动作（触发 review / 指令 / 聊天）**复用既有 run 队列与 Orchestrator 的单工作者 + 并发上限**，
+  不绕过调度——API 触发与 GUI 触发在同一队列里排队，互不抢占语义保持一致。
+
+## 数据 / 接口契约
+
+### 配置（`config.yaml` 顶层 `service`）
+
+```yaml
+service:
+  enabled: false        # 总开关；默认关 = 不监听、零暴露面
+  host: 127.0.0.1        # 监听地址；可设 0.0.0.0（高风险，需安全警示）
+  port: 18765            # 固定安全默认端口（10000+，避开 8xxx 拥挤段且低于临时端口范围），可改
+  token: ''              # bearer token；启用且为空时自动生成；明文落盘（同既有凭据策略）
+```
+
+### 鉴权
+
+- 请求头：`Authorization: Bearer <token>`；缺失 / 不匹配 → `401` + 错误码。
+- token 经 `SecretStore` 读写，响应 / 日志中不回显。
+
+### 统一响应封套
+
+```jsonc
+// 成功
+{ "ok": true, "data": <T> }
+// 失败（复用 AppError 的 code + 可序列化 meta；前端 / CLI 按码本地化）
+{ "ok": false, "error": { "code": "ESV0001", "meta": { /* ... */ } } }
+```
+
+- HTTP 状态码与语义对齐：`400` 校验失败 / `401` 未授权 / `403` 写工具被拒（未开放的写操作）/ `404` 资源不存在 /
+  `409` 冲突 / `426` CLI 版本过旧 / `500` 内部错误。
+- 新增 **`SV`（service）错误码领域**（`E`+`SV`+四位，见 [错误码规范](../99-core/04-error-codes.md)）：
+  如 token 无效、写操作被拒、监听未就绪等；与既有 `AG`/`PR`/`NT` 等领域并列。
+
+### 端点（`/api/v1`，逐条对应 [CLI](02-cli.md) 命令）
+
+读端点用 `GET`、写端点用 `POST`。列表返回**精简投影**，其余读端点返回同源结构。
+
+| Method & Path | 用途 | 复用的内部能力 |
+| --- | --- | --- |
+| `GET /api/v1/whoami` | 当前身份：活动连接 PAT 所属用户（`name`/`displayName`/`slug`）+ 集成平台 + 连接显示名；无活动连接各项 null | 连接摘要（当前用户 + 平台） |
+| `GET /api/v1/categories` | 当前启用平台下可用的分类标签：`categories`（`PrDiscoveryFilter`）+ `statuses`（状态 / 合并态筛选），按平台能力裁剪 | 平台能力位 + 列表筛选语义 |
+| `POST /api/v1/refresh` | 触发一次立即轮询刷新（拉取所有连接的最新 PR、落本地），返回本轮计数汇总（`PollResult`：fetched / changed / added / removed / errors）；等价 GUI 手动刷新，无远端写副作用 | `poller.tick`（`prs:refresh` 同源） |
+| `GET /api/v1/version` | 服务端（桌面应用）版本（`{ version }`），供 CLI `version` 命令同时展示客户端 + 服务端版本 | `buildAppInfo().appVersion`（`app:info` 同源） |
+| `GET /api/v1/prs` | PR 列表（**精简投影** `PrListItem`：字段序 id/title/author/createdAt 优先，去 description、人员仅 slug）；query：`category`（一级）/`status`（二级）/`q`（检索）/`skip`+`limit`（分页，默认 limit 100） | `prs:list` + 列表筛选谓词 + 视图投影 |
+| `GET /api/v1/prs/{id}` | 描述详情（完整 `StoredPullRequest`：标题 / 描述 / 作者 / 分支 / 时间 / 状态 / 合并态） | `StoredPullRequest` |
+| `GET /api/v1/prs/{id}/diff` | 变更文件列表；带 `?path=&side=base\|head` 时取单文件内容 | `diff:listChangedFiles` / `diff:getFileContent` 同源 |
+| `GET /api/v1/prs/{id}/activity` | 动态（评论 / 提交更新 / 评审决断归并的时间线） | `diff:listActivity` 同源 |
+| `GET /api/v1/prs/{id}/commits` | 提交列表（`PrCommit[]`） | `diff:listCommits` 同源 |
+| `GET /api/v1/prs/{id}/reviewers` | 评审人审批状态（`Reviewer[]`，含各人 `status`） | `StoredPullRequest.reviewers` |
+| `GET /api/v1/prs/{id}/agent` | Agent 当前执行状态（`AgentSession`：status / 进度 / 总结 / 建议） | `agent:getSession` 同源 |
+| `GET /api/v1/prs/{id}/agent/conversation` | 历史会话（`AgentMessage[]`） | `agent:getConversation` 同源 |
+| `POST /api/v1/prs/{id}/agent/review` | 执行 auto review（固定评审微流程 describe→review→[追问]→总结） | `agent:run` 同源 |
+| `POST /api/v1/prs/{id}/agent/instruct` | 发送 Agent 指令（**仅只读工具**：describe / review / ask / improve；写工具硬拒绝） | 只读工具派发（复用 run 队列） |
+| `POST /api/v1/prs/{id}/agent/chat` | 发送自然语言聊天（可触发 Agent 规划与任务执行） | `agent:ask` / `agent:enqueueMessage` 同源 |
+| `POST /api/v1/prs/{id}/agent/stop` | 中断该 PR 运行中的 Agent（思考 / 执行任意阶段即时停；PR 级，非按单个 run） | `agent:stop` 同源 |
+| `POST /api/v1/prs/{id}/approve` | 评审决断「通过」（写远端评审状态 + 落本地） | `prs:setLocalStatus` 同源 |
+| `POST /api/v1/prs/{id}/needswork` | 评审决断「需修改」（写远端评审状态 + 落本地） | `prs:setLocalStatus` 同源 |
+| `POST /api/v1/prs/{id}/comment` | 发一条顶层评论（body 为正文，空则 400） | `comments:create` 同源 |
+
+- `{id}` 即 PR 的 `localId`——跨平台稳定 PR 标识（内部哈希，非平台 `remoteId`）；列表投影里对外命名为 `id`，所有 PR 维度端点以它定位。
+- 过程步骤（transcript）暂不在初版 API 内开放，作为将来扩展位（见下）。
+
+### 新增 IPC（设置页驱动）
+
+- `config:setService`：写 `service` 段 → 写盘 + 内存同步 + 重建监听器（热生效）。
+- `config:generateServiceToken`：重新生成 token → 写盘 + 即时失效旧 token，返回新 token 供 UI 展示 / 复制。
+
+## 扩展与注意事项
+
+- **加新端点先下沉 service**：HTTP 与 IPC 必须共用 service 方法，避免逻辑分叉；端点是 service 能力的薄投影。
+- **写边界是硬约束**：评审写动作仅经 approve / needswork / comment 专用端点；Agent `instruct` 的只读工具
+  白名单在 API 层强校验、独立于 Agent grant 闸——新增 Agent 工具时同步确认其 `kind` 与是否纳入 instruct
+  白名单，默认排除一切 `mutating`。放开新的写端点须显式评估远端副作用（合并等高影响动作暂不开放）。
+- **`0.0.0.0` 安全警示不可省**：设置页与使用文档须明确暴露范围与风险；token 是唯一防线。
+- **端口冲突**：监听失败以非致命方式提示，不拖垮应用启动；提示用户改端口。
+- **进度推送是将来扩展位**：初版以「轮询 `GET .../agent` 拉状态」为主；如需实时进度，可在同一监听器上加
+  SSE / WebSocket 推送 Agent step 事件（复用现有 `agent:stepProgress` 广播），不改既有 REST 契约。
+- **契约稳定性**：`/api/v1` 前缀预留版本演进位；响应封套与错误码领域一旦发布需保持兼容（CLI 与第三方依赖它）。
diff --git a/docs/arch/04-integration/02-cli.md b/docs/arch/04-integration/02-cli.md
new file mode 100644
index 00000000..fbf5b5aa
--- /dev/null
+++ b/docs/arch/04-integration/02-cli.md
@@ -0,0 +1,162 @@
+# CLI 工具（meebox）
+
+## 职责与边界
+
+提供一个**独立分发的跨平台命令行客户端**，经[本地 API](01-service-api.md) 消费应用能力，供外部
+agent / 脚本 / CI 把 meebox 的 PR 发现、浏览与 Agent 操作纳入自动化流程。命令名 **`meebox`**。
+
+负责：把 API 端点封装成顺手的命令树、解析连接 / 鉴权配置、按人 / 机两种消费方式输出（文本 / JSON）、
+约定退出码。提供浏览与**评审写动作**（approve / needswork / comment）——与服务端写边界一致。
+
+**不负责**：
+
+- 业务逻辑 —— CLI 是 API 的瘦客户端，不内置任何评审 / 平台逻辑。
+- **合并与变更类 Agent 工具**（merge / publish 等）—— 不提供对应命令；API 本就不开放（见 [服务端写边界](01-service-api.md)）。
+- 桌面应用本体 —— CLI **不内嵌进安装包**，是独立可分发物（见下「分发」）。
+
+## 核心设计
+
+### 技术栈与仓库形态决策（Go 评估）
+
+CLI 优先技术栈定为 **Go**，并就「是否内嵌当前项目」给出结论——**该问题分两层，结论不同**：
+
+1. **是否打进 Electron 安装包：否。** CLI 面向外部自动化、经 HTTP 与应用通信，无需随桌面包分发；打进去
+   只会无谓增大安装体积。二者是**相互独立的可分发物**。
+2. **源码是否放进本仓库（monorepo）：是，但作为独立的顶层 `cli/` 目录、自带 `go.mod`，不纳入 npm
+   workspaces / Nx。** Go 有独立的模块系统与构建缓存，与 npm/Nx 的工程模型不兼容；强行包成 Nx project
+   （run-commands 壳）徒增复杂、且让 Go 工具链成为全仓开发的前置。CLI 与主工程的**唯一耦合是 HTTP/JSON
+   线协议**（语言无关），无代码级共享，故「同仓、独立构建」最自然。
+
+**为什么 Go 适合做这个 CLI**：静态链接小体积二进制、`GOOS`/`GOARCH` 一条命令交叉编译出全平台、启动快、
+无运行时依赖——正是分发型 CLI 的理想形态。相较把 Node/TS 用 pkg / SEA 打包（产物数十 MB、交叉编译脆弱、
+冷启动慢），Go 在分发体验上明显占优。
+
+**代价与应对——类型契约同步**：Go 端无法编译期复用 `shared` 的 TS 类型。
+
+- **初期**：API 端点少而稳，**手写 Go struct 对齐文档契约**即可（成本低）。
+- **将来**：若契约增长，引入 OpenAPI / JSON Schema 作单一事实源，生成 TS 侧校验 + Go 侧 client，
+  消除手工漂移。
+
+### 连接与鉴权
+
+CLI 需 API base URL + token。来源优先级（高 → 低）：
+
+1. 命令行 flag：`--api-url` / `--token`；
+2. 环境变量：`MEEBOX_API_URL` / `MEEBOX_TOKEN`；
+3. CLI 自身配置文件 `~/.code-meeseeks/cli.yaml`（与 GUI 的 `config.yaml` 同目录、独立文件，隔离二者配置）。
+
+连接信息须**显式提供**（flag / 环境变量 / `cli.yaml` 三者之一），token 缺失即报鉴权错误。`meebox login
+--token <token> [--server <url>]` 把 token（与可选 server，默认 loopback）写入 `cli.yaml`，免去后续每次传参——
+它是 CLI 唯一的配置**写入**命令，与 `cli.yaml` 的读取（上述优先级）配对，使配置管理自洽。
+
+**不读取 GUI 主配置**：CLI 刻意**不**读应用主配置 `~/.code-meeseeks/config.yaml`。该文件承载连接层机密
+（各代码平台的访问令牌等），若从中静默取服务令牌，等于让 CLI 触达其本不应接触的凭据——属预期外的越权访问，
+故移除此前的「本机自动发现」设计。环境变量 `MEEBOX_TOKEN` 是本机免逐次传参的推荐方式（配合 shell / CI 环境注入）。
+
+### 命令结构
+
+```text
+meebox [全局 flag] <组> <命令> [参数]
+
+全局 flag：--api-url · --token · --output (yaml|json) · --quiet
+```
+
+命令分两类——**根层级系统性命令** 与 **两个领域组**：
+
+- **系统性命令（根层级）** —— `login`（保存凭据到 `cli.yaml`）、`whoami`（身份）、`version`（客户端 +
+  服务端版本）、`skill`（打印内嵌的 SKILL.md）：与具体 PR / Agent 无关的工具 / 会话层操作，直接置于根层级、
+  不套领域组（符合 `kubectl version` / `gh auth` 等惯例）。
+- **`pr`** —— PR 相关操作：浏览 + 评审写动作，并含 `categories`（`pr list` 的筛选词表）与 `refresh`
+  （触发一次拉取、刷新 PR 列表）。
+- **`agent`** —— 评审 Agent 操作。
+
+`pr` / `agent` 下的 PR 维度子命令用**必填 flag `--pr <id>`** 传 PR 标识（`id` 由 `pr list` 输出获得）——
+agent **不嵌进 `pr`**（避免 `pr agent … --pr` 里 `pr` 重复），与 `pr` 平级；根层级系统性命令与
+`pr categories` / `pr refresh` / `pr list` 非 PR 维度，无需 `--pr`。
+
+| 命令 | 用途 | 对应 API |
+| --- | --- | --- |
+| `meebox login --token <token> [--server <url>]` | 保存 token（与可选 server，默认 loopback）到 `cli.yaml`，供后续命令免传参 | —（本地写，无 API） |
+| `meebox whoami` | 当前身份（用户 + 平台 + 连接名） | `GET /whoami` |
+| `meebox version` | 客户端（CLI）+ 服务端（应用）版本；服务端不可达时仅客户端、退出码仍 0 | `GET /version` |
+| `meebox skill` | 打印构建时 `go:embed` 内嵌的 agent 使用说明（SKILL.md） | —（本地，无 API） |
+| `meebox pr categories` | 列当前启用平台的分类标签（`categories` 一级 + `statuses` 二级）——`pr list` 的筛选词表 | `GET /categories` |
+| `meebox pr refresh` | 触发一次立即轮询刷新（拉取最新 PR、落本地），返回本轮计数汇总（fetched / changed / added / removed / errors）；等价 GUI 手动刷新 | `POST /refresh` |
+| `meebox pr list [--category <一级>] [--status <二级>] [--query <检索>] [--skip N] [--limit N]` | PR 列表（精简投影 + 分页，默认 limit 100） | `GET /prs` |
+| `meebox pr show --pr <id>` | 描述详情 | `GET /prs/{id}` |
+| `meebox pr diff --pr <id> [--file <path>] [--side base\|head]` | 无 `--file` 列变更文件；有则取该文件内容 | `GET /prs/{id}/diff` |
+| `meebox pr activity --pr <id>` | 动态（时间线） | `GET /prs/{id}/activity` |
+| `meebox pr commits --pr <id>` | 提交列表 | `GET /prs/{id}/commits` |
+| `meebox pr reviewers --pr <id>` | 评审人审批状态 | `GET /prs/{id}/reviewers` |
+| `meebox pr approve --pr <id>` | 评审决断「通过」（真实远端写） | `POST /prs/{id}/approve` |
+| `meebox pr needswork --pr <id>` | 评审决断「需修改」（真实远端写） | `POST /prs/{id}/needswork` |
+| `meebox pr comment --pr <id> <message>` | 发一条顶层评论（真实远端写） | `POST /prs/{id}/comment` |
+| `meebox agent status --pr <id>` | Agent 当前执行状态 | `GET /prs/{id}/agent` |
+| `meebox agent history --pr <id>` | 历史会话 | `GET /prs/{id}/agent/conversation` |
+| `meebox agent review --pr <id>` | 执行 auto review | `POST /prs/{id}/agent/review` |
+| `meebox agent instruct --pr <id> <command> [args]` | 发送 Agent 指令（仅只读：describe / review / ask / improve） | `POST /prs/{id}/agent/instruct` |
+| `meebox agent chat --pr <id> <message>` | 自然语言聊天（可触发任务执行） | `POST /prs/{id}/agent/chat` |
+| `meebox agent stop --pr <id>` | 中断该 PR 运行中的 Agent（PR 级） | `POST /prs/{id}/agent/stop` |
+| `meebox agent run list --pr <id>` | 该 PR 运行队列中的 pr-agent runs（active + waiting） | `GET /prs/{id}/agent/runs` |
+| `meebox agent run cancel --pr <id> --run <runId>` | 按 run 取消一个 pr-agent 工具调用 | `POST /prs/{id}/agent/runs/{runId}/cancel` |
+
+- `<id>` 为 PR 的 `localId`（列表投影里对外命名为 `id`，由 `pr list` 输出获得）。
+- 评审写动作走 `pr approve` / `pr needswork` / `pr comment` 专用命令；变更类工具（publish 等）不在 `instruct`
+  白名单内，传入即被服务端拒绝（CLI 亦前置友好报错）。merge（合并）不提供。
+- 中断粒度：`agent stop` 停整个 PR 的 Agent；`agent run cancel` 只取消指定的单个 pr-agent run。
+
+### 输出与退出码
+
+- **`--output yaml`（默认）**：把响应渲染为 YAML（类 k8s `-o yaml`）——结构化又可读，便于人交互式查看。
+  与 JSON 一样是对响应数据的**通用转换**，不做逐命令表格 / formatter（省去手写 struct 的契约同步负担）。
+- **`--output json`**：原样输出 API `data`，供外部 agent / 脚本机器消费。agent 传参无门槛，故默认面向人优化（YAML）、
+  机器集成显式取 `json`；两者字段形状同源、皆稳定。
+- **退出码约定**：`0` 成功；非 0 表错误并按类别区分（如 `2` 鉴权失败、`3` 资源不存在、`1` 通用错误）；
+  错误信息打 `stderr`，携带服务端返回的错误码（`ESV*` 等），便于脚本分支处理。
+
+### 实现选型
+
+- Go + 命令树库（如 cobra）+ 标准 `net/http` client，**最小依赖**。
+- 错误码 / 响应封套与服务端契约一一对齐（见 [服务端契约](01-service-api.md)）。
+
+## 数据 / 接口契约
+
+- **配置来源优先级**：flag > env（`MEEBOX_API_URL` / `MEEBOX_TOKEN`）> CLI 配置文件
+  （`~/.code-meeseeks/cli.yaml`）。连接信息须显式提供；CLI 不读 GUI 主配置 `config.yaml`（含连接层机密）。
+- **输出模式**：`yaml`（默认，人，类 k8s `-o yaml`）/ `json`（机，输出 API `data`）；均为响应数据的通用转换。
+- **退出码**：`0` 成功 / `1` 通用 / `2` 鉴权 / `3` not found（按需扩展）。
+- **二进制与压缩包命名**：`meebox-cli-<version>-<os>-<arch>.<ext>`（Windows / macOS 用 `.zip`、Linux 用 `.tar.gz`），
+  附 `.sha256` 校验和。`<version>` 取自 `apps/desktop/package.json`（与 app 同源，唯一真相源），发布前置校验其与 `v*` tag 一致。
+- **压缩包内容 = 可直接投放的 skill 目录**：除二进制外一并打包 `LICENSE` + `README.md` + `SKILL.md`。解压到
+  agent 的 skills 目录即得一个可用 skill——`SKILL.md`（frontmatter `name: meebox`）教 agent 用法，紧邻其驱动
+  的二进制。这是 CLI「面向 agent 交付」的主形态。
+- **二进制自述（`go:embed`）**：同一份 `SKILL.md` 经 `go:embed` 于构建期内嵌进二进制，`meebox skill` 打印之。
+  即便二进制脱离压缩包（如 `go install` 或裸放 `PATH`）也能自述用法，且内嵌内容与随包 `SKILL.md` 构建期一致。
+  刻意**不做** `--manifest` 之类的 function-calling JSON——skill 的消费形态是 markdown，非工具 schema 注入；
+  真有此需求应从命令树生成、而非另手维护一份 JSON。
+
+## 分发与 CI
+
+- **覆盖平台**：Windows x64、macOS arm64、Linux x64 / arm64。
+- **随主工程一起发布**：发布流程的 **Go 构建 job**（`actions/setup-go` + `GOOS`/`GOARCH` 交叉编译矩阵）产出
+  四平台压缩包（含二进制 + `LICENSE` + `README.md` + `SKILL.md`）+ 校验和，与桌面安装包一并上传到**同一个
+  GitHub Release**（由现有 `v*` tag 触发，见 [发布流程](../../../AGENTS.md)）。
+- 版本号**取自 `apps/desktop/package.json`（与 app 同源）**，经 `-ldflags` 注入 `cmd.version`——不独立依赖 git tag（发布前置校验 tag 与之一致），确保 CLI 与服务端 API 契约版本可对应。
+- **一键安装脚本（macOS / Linux）**：`tools/cli/install.sh` 经 `curl … | bash` 一条命令完成安装——探测系统 /
+  架构 → 取匹配的 Release 压缩包 → 校验 SHA-256 → 解出 `meebox` 装入 `PATH`（默认 `/usr/local/bin`，不可写回退
+  `~/.local/bin`；`MEEBOX_VERSION` / `MEEBOX_BIN_DIR` 可覆盖）。刻意**不落地 `SKILL.md`**（已内嵌、`meebox skill`
+  可导出）。Windows 不在脚本覆盖内，走手动下载。
+
+## 扩展与注意事项
+
+- **写边界与服务端一致**：仅提供评审写动作（approve / needswork / comment）；合并与变更类 Agent 工具不提供。
+  新增命令前先确认对应 API 端点已存在，写端点须与服务端写边界对齐。
+- **加新命令先加端点**：CLI 不得绕过 API 直连应用内部；能力缺口先在[服务端](01-service-api.md)补端点。
+- **不触碰 GUI 机密**：CLI 不读应用主配置 `~/.code-meeseeks/config.yaml`（含各平台访问令牌等连接层机密）；服务令牌须经 flag / 环境变量 / `cli.yaml` 显式提供，避免越权触达预期外凭据。
+- **契约漂移防护**：初期手写 struct 务必随服务端契约同步更新；契约增长后转 OpenAPI / Schema 代码生成。
+- **版本兼容门控**：CLI 每次请求带 `X-Meebox-CLI-Version` 头声明自身版本（与 app 同源）；服务端据集中管理的
+  最低可兼容版本统一门控，CLI 收到 `SV_CLIENT_TOO_OLD`（HTTP 426）即输出「过旧、请升级」提示。见
+  [服务端契约](01-service-api.md) 的「CLI 版本兼容门控」。
+- **JSON 优先稳定**：`--output json` 是自动化主路径，其字段形状视为对外契约，演进需保持兼容。
+- **代理走环境变量**：HTTP client 用 Go `net/http` 默认 transport，天然遵循标准 `HTTP(S)_PROXY` /
+  `NO_PROXY`；loopback（`127.0.0.1` / `localhost`）默认直连不走代理——无需自实现代理逻辑。
diff --git a/docs/arch/README.md b/docs/arch/README.md
index 85b05123..080c35fe 100644
--- a/docs/arch/README.md
+++ b/docs/arch/README.md
@@ -41,12 +41,16 @@ docs/arch/
 │   ├── 02-session.md                 会话 Agent 化（输入路由 / 规划循环 / 过程留存 / 交互控制）
 │   ├── 03-autopilot.md               AutoPilot 与调度（自动预评审 / 准入闸 / 批量判定 / 微流程 / 优先级队列）
 │   ├── 04-rules.md                   规则系统（frontmatter / 匹配优先级；正文存 `<agent.dir>/rules/`）
-│   └── 05-pragent-runtime.md         pr-agent 集成与运行时（bridge / 嵌入式 Python / sitecustomize / token usage）
+│   ├── 05-pragent-runtime.md         pr-agent 集成与运行时（bridge / 嵌入式 Python / sitecustomize / token usage）
+│   └── 06-tool-token-cost.md         工具 token 成本与上下文分层（三层上下文模型 / 成本放量根因 / 只读检索指引 · /ask 预算 · codegraph 评估）
 ├── 03-gui/                         GUI 与交互
 │   ├── 01-ui-interaction.md          渲染层布局 / 面板 / 跨 PR 保活 / 交互约定
 │   ├── 02-command-palette.md         命令面板（标题栏入口 / 两级选择 / 按语言搜索 / 注册表 + 分域）
 │   ├── 03-notifications.md           消息通知（poll 事件投影 / 系统通知 toast / macOS dock 角标 / OS 权限降级）
 │   └── 04-i18n.md                    国际化（react-i18next / 双运行时 / key 命名 / 翻译规范 / 模板翻译）
+├── 04-integration/                 外部集成扩展与 CLI
+│   ├── 01-service-api.md             服务监听与本地 API（loopback 默认 / 强制 token / 读+评审写边界 / 路由复用 service）
+│   └── 02-cli.md                     CLI 工具（Go 独立二进制 / 命令树 / 显式连接配置 / 跨平台分发）
 └── 99-core/                        基础设施
     ├── 01-state-storage.md           状态存储与数据模型（StateStore / per-PR 目录 / 存储模型 + 业务生命周期）
     ├── 02-config-and-secrets.md      配置与凭据（config.yaml / SecretStore / 设置页 / 首启向导）
diff --git a/docs/development/packaging-release.md b/docs/development/packaging-release.md
index 9a8b64bd..092ce693 100644
--- a/docs/development/packaging-release.md
+++ b/docs/development/packaging-release.md
@@ -42,3 +42,26 @@
   或提供 Homebrew Cask。
 - **升级公证**：见上；同时 mac 段需加回 hardenedRuntime + entitlements + notarize（entitlements 已备好
   `disable-library-validation` 让嵌入式 python 在 hardened runtime 下能加载第三方 dylib）。
+
+## 发布前置清单（打 tag 前必做）
+
+在**同一批改动**里完成，随发版经 `dev` → `master`——漏任一步 CI 不报错（仅 `::warning::`）但会产出错误的 Release：
+
+1. **版本号** —— 把 [apps/desktop/package.json](../../apps/desktop/package.json) 的 `version` 改成目标版本（去 `v` 前缀，预发布带后缀如 `0.5.0-alpha.1`）。electron-builder 的 `artifactName: code-meeseeks-${version}-...` 直取此值——不改则安装包文件名与 tag 不符。改完 `npm install` 同步 lockfile。
+2. **CHANGELOG** —— 把 [CHANGELOG.md](../../CHANGELOG.md) 的 `## [Unreleased]` 改名为 `## [<版本>] - <YYYY-MM-DD>`，并在文件底部补 `[<版本>]: …/compare/…` 链接引用。**发布即消费掉 Unreleased、不留空段**；下一笔开发期 changelog 改动时再新建。release.yml 按 `## [<版本>]` 字面抽段注入 Release 正文——缺段则正文回退、无变更说明。**若正式版内容来自此前的 alpha/预发布**：开发期通常无独立 Unreleased（内容已在预发布段），直接把该预发布段改名为正式版段、删去对应 `[<x>-alpha.N]:` 链接引用（内容并入正式版段，不留空壳 stub）；尚无对应正式版的其它预发布段保留。
+3. **校对** —— 确认 `## [<版本>]` 段已覆盖自上版本以来合入 `dev` 的全部要点（新增 / 变更 / 修复）。
+
+tag 名与 package.json 版本必须一致（`v<版本>`）。名含 `-` 的预发布 tag（如 `-alpha.N`）由 release.yml 自动标 prerelease 且不抢占 Latest。
+
+**版本号规则（`-dev`）**：每次正式发版后，`dev` 立即把 [apps/desktop/package.json](../../apps/desktop/package.json) 切到**下一版的 `-dev` 预发布号**（如发完 `0.6.0` 即切 `0.7.0-dev`，`npm install` 同步 lockfile），标记开发态。`-dev` 仅作开发标记——**不打 tag、不发版**；发版时按上面改成目标号（`0.7.0-alpha.N` 或 `0.7.0`）。`-dev` 是合法 semver（`0.6.0` < `0.7.0-dev` < `0.7.0`），不影响更新检测（[update-check.ts](../../apps/desktop/src/main/utils/update-check.ts) 用 `semver.gt` 比对、不用 range）与构建。
+
+## CHANGELOG 撰写风格（面向用户、求简）
+
+- 版本引言 `>` 区直接进入「本版重点」、要点用**无序列表**排版，不堆成长句，**不写「首个 / 第 N 个正式版」之类的版本序数引言**；
+- 新增 按**功能场景**分类、用缩进的二级列表表达，每个小点一句话点到即止；
+- 重构类任务**前后端合并**为一条总结、不展开实现细节；
+- 修复 **不写「怎么修的」机制**，每条一句话只述修复的现象/影响；
+- 通篇不写 IPC 通道名、函数名、文件路径、字段名等实现细节，优先突出新增特性与改良；
+- **安装 / 升级注意事项**（版本引言里的 ⚠️ 警示，如先卸载旧版、per-machine 提权等）属安全关键信息，**保留完整、不参与精简**——这些会随 release.yml 注入 GitHub Release 正文，删减会让用户漏看升级风险；
+- **分段标题用中文 + emoji**：`### ✨ 新增 / ♻️ 变更 / 🔧 修复 / 🗑️ 移除 / 🔒 安全`（对应 Keep a Changelog 的 Added / Changed / Deprecated / Removed / Fixed / Security）；
+- 外部贡献者的 PR 习惯性致谢（仿 `(#65，感谢 @user)`）。
diff --git a/docs/guide/04-config-reference.md b/docs/guide/04-config-reference.md
index 37a0350d..8d906856 100644
--- a/docs/guide/04-config-reference.md
+++ b/docs/guide/04-config-reference.md
@@ -3,13 +3,18 @@
 所有配置集中在唯一的配置文件 **`~/.code-meeseeks/config.yaml`**（YAML 格式）。日常使用通过应用内 **设置** 页与首启向导可视化编辑即可，无需手动改文件；本篇是完整的结构与字段参考，供批量配置、高级参数调整、问题排查时查阅。
 
 - **编辑方式**：设置页保存即写盘并热更新；设置页「用系统关联程序打开 config.yaml」可直接编辑文件。
-- **生效时机**：连接 / LLM / 代理等改动保存后即时重建生效；个别高级参数（如并发数、缓存目录）需重启应用。
+- **生效时机**：连接 / LLM / 代理 / 语言 / 并发数等改动保存后即时重建生效；个别高级参数（如 `workspace.repos_dir`）需重启应用。
 - **凭据说明**：访问令牌、API Key、代理密码以**明文**保存在本文件中（与配置结构隔离但不加密）。请按最小权限申请凭据、妥善保护本文件，泄露后及时吊销。
 
 ## 完整示例
 
 ```yaml
-language: zh-CN
+language: ''            # 空 = 按系统语言自动、回落英语；或显式 zh-CN / en-US / ja-JP / de-DE
+
+appearance:
+  editor_theme: auto
+  editor_font_family: ''
+  editor_font_size: 14
 
 workspace:
   repos_dir: ~/.code-meeseeks/repos
@@ -42,6 +47,24 @@ pr_agent:
   strategy: auto
   max_concurrency: 2
 
+notifications:
+  enabled: true
+  new_pr: true
+  reply: true
+  mention: true
+  authored_comment: true
+  authored_needs_work: true
+  authored_conflict: true
+
+service:
+  enabled: false
+  host: 127.0.0.1
+  port: 18765
+  token: ''
+
+update:
+  check_enabled: true
+
 connections:
   - id: my-bitbucket
     kind: bitbucket-server
@@ -80,16 +103,30 @@ llm:
 
 | 字段 | 类型 | 默认 | 说明 |
 | --- | --- | --- | --- |
-| `language` | string | `zh-CN` | pr-agent 生成评审内容使用的自然语言（ISO locale，如 `zh-CN` / `en-US`）。设置页暂不暴露，需手改。 |
+| `language` | string | `''`（自动） | 界面与 pr-agent 生成内容使用的语言（ISO locale，如 `zh-CN` / `en-US` / `ja-JP` / `de-DE`）。**默认空 = 自动**：按系统偏好语言匹配，无合适项回落英语。设置页可切换（热生效）。 |
+| `appearance` | object | — | 界面与编辑器外观（主题 / 字体），见下。 |
 | `workspace` | object | — | 工作目录设置，见下。 |
 | `agent` | object | — | 高阶 Agent 与 AutoPilot 设置（Agent 目录、个性化规则均归于此），见下。 |
 | `poller` | object | — | PR 轮询设置，见下。 |
 | `proxy` | object | — | 出站网络代理设置，见下（详见 [网络代理配置](03-proxy.md)）。 |
 | `pr_agent` | object | — | pr-agent 运行时设置，见下。 |
+| `notifications` | object | — | 系统通知与 dock 角标设置，见下。 |
+| `service` | object | — | 本地 API 服务（CLI / 外部集成入口）设置，见下（详见 [CLI 命令行工具](06-cli.md)）。 |
+| `update` | object | — | 版本更新检测设置，见下。 |
 | `connections` | array | `[]` | 代码平台连接列表，见下（详见 [代码平台配置](01-code-platform.md)）。 |
 | `active_connection_id` | string | `''` | 当前启用的连接 `id`，见下。 |
 | `llm` | object | — | LLM 预设设置，见下（详见 [LLM 配置](02-llm.md)）。 |
 
+## `appearance` — 外观
+
+界面与编辑器的纯前端展示项（主进程仅据主题设原生窗口明暗）。均在设置页可视化调整、即时生效。
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `editor_theme` | enum | `auto` | 全局主题（Monaco 编辑器与整个界面共用）：`auto` 跟随系统深 / 浅色，其余为内置 / 第三方主题 id。 |
+| `editor_font_family` | string | `''` | 编辑器等宽字体族（CSS font-family，可逗号分隔多候选）。留空 = 内置 mono 字体栈。 |
+| `editor_font_size` | integer | `14` | 编辑器字号（px），限合理范围。 |
+
 ## `workspace` — 工作目录
 
 | 字段 | 类型 | 默认 | 说明 |
@@ -98,7 +135,7 @@ llm:
 
 ## `agent` — 高阶 Agent 与 AutoPilot
 
-高阶 Agent 把自然语言请求转成自主规划 + 多工具编排（设计见 [docs/arch/02-agent/01-agent.md](../arch/06-agent.md)）。**Agent 目录** `<agent.dir>/` 是 Agent 的完整人格与知识来源，其固定布局为：
+高阶 Agent 把自然语言请求转成自主规划 + 多工具编排（设计见 [docs/arch/02-agent/01-agent.md](../arch/02-agent/01-agent.md)）。**Agent 目录** `<agent.dir>/` 是 Agent 的完整人格与知识来源，其固定布局为：
 
 ```
 <agent.dir>/
@@ -167,6 +204,37 @@ Agent **无独立启用开关**——配置了 LLM 且 pr-agent 就绪即可用
 | `strategy` | enum | `auto` | 运行时策略：`auto` 优先随包内嵌运行时、缺失则回退系统 `pr-agent` CLI；亦可显式 `embedded` / `local-cli` 强制。 |
 | `max_concurrency` | integer | `2` | 评审任务并发数，`1`–`8`。设置页「AI」分区可调（热生效，无需重启），亦可手改本文件，详见 [LLM 配置 · 进阶：评审并发数](02-llm.md#进阶评审并发数)。 |
 
+## `notifications` — 消息通知
+
+系统通知（toast）与 macOS dock「待回应」角标开关。`enabled` 为总开关（关闭后既不弹通知也不亮角标）；其余各项按事件类型分别控制系统通知——`new_pr` / `reply` / `mention` 面向「待我评审」等场景，`authored_*` 面向「我创建的」PR。系统通知受 OS 权限约束，用户在系统设置关闭后应用静默降级。设置页可调，即时生效。
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | 通知总开关；关闭后不弹系统通知、不亮 dock 角标。 |
+| `new_pr` | boolean | `true` | 出现新的待我评审 PR 时弹通知。 |
+| `reply` | boolean | `true` | 收到评论回复时弹通知。 |
+| `mention` | boolean | `true` | 评论中被 @ 提及时弹通知。 |
+| `authored_comment` | boolean | `true` | 我创建的 PR 收到他人新评论时弹通知。 |
+| `authored_needs_work` | boolean | `true` | 我创建的 PR 被评审标记「需修改」时弹通知。 |
+| `authored_conflict` | boolean | `true` | 我创建的 PR 出现合并冲突时弹通知。 |
+
+## `service` — 本地 API 服务
+
+本机 HTTP API 服务监听配置，供 `meebox` CLI 与外部脚本 / agent 访问应用能力（详见 [CLI 命令行工具](06-cli.md)）。默认关闭、零暴露面；开启即**强制** bearer token 鉴权。设置页「集成」分区可视化开关、查看 / 复制 / 重新生成令牌，即时生效（开关 / 地址 / 端口变更停旧起新，token 变更下次请求生效）。
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `false` | 服务总开关。关闭 = 不监听、无暴露面。 |
+| `host` | string | `127.0.0.1` | 监听地址。默认仅本机可达；设 `0.0.0.0` 暴露到局域网（高风险，此时令牌是唯一防线）。 |
+| `port` | integer | `18765` | 监听端口，`1`–`65535`。 |
+| `token` | string | `''` | 访问令牌（bearer）。首次开启自动生成；设置页可重新生成（旧令牌即时失效）。以明文保存。 |
+
+## `update` — 版本更新检测
+
+| 字段 | 类型 | 默认 | 说明 |
+| --- | --- | --- | --- |
+| `check_enabled` | boolean | `true` | 启动时（及设置页手动触发）查 GitHub Releases 最新稳定版并与当前版本比对，有新版仅**提示**去下载（不自动下载 / 安装）。设为 `false` 关闭检测——此开关仅经手改本文件调整（设置页展示更新状态、不提供开关）。 |
+
 ## `connections` — 代码平台连接
 
 `connections` 是数组，每个元素是一条连接。`kind` 决定平台类型与字段形态。
diff --git a/docs/guide/05-rules.md b/docs/guide/05-rules.md
index 744d4f39..85afee45 100644
--- a/docs/guide/05-rules.md
+++ b/docs/guide/05-rules.md
@@ -107,4 +107,4 @@ applies_to:
 - **单文件解析失败不影响整体**：某个文件 frontmatter YAML 写坏 / 字段类型不对，应用会跳过该文件并继续加载其余规则。
 - **当前命中提示**：选中 PR 后，chat 面板会显示本次命中的规则条数，点击可预览全部命中规则（按 Ruleset 分段列出），便于确认本次评审受哪些规则约束。
 
-> 设计与实现细节见架构文档 [docs/arch/02-agent/04-rules.md](../arch/07-rules.md)。
+> 设计与实现细节见架构文档 [docs/arch/02-agent/04-rules.md](../arch/02-agent/04-rules.md)。
diff --git a/docs/guide/06-cli.md b/docs/guide/06-cli.md
new file mode 100644
index 00000000..f83704a5
--- /dev/null
+++ b/docs/guide/06-cli.md
@@ -0,0 +1,161 @@
+# CLI 命令行工具（meebox）
+
+`meebox` 是随发布提供的跨平台命令行工具，经本机的「本地 API 服务」访问应用能力，便于把 PR 浏览与
+评审 Agent 操作接入脚本、CI 或外部 agent。命令行提供**浏览与评审操作**，含评审决断（approve / needswork）
+与发评论；不含合并（merge）等高影响写操作。
+
+## 1. 开启本地 API 服务
+
+CLI 依赖应用内的本地 API 服务，默认关闭，需先在 **设置 → 集成** 开启：
+
+- 打开「本地 API 服务」开关（首次开启会自动生成一枚访问令牌）。
+- **监听地址**：默认 `http://127.0.0.1:18765`（仅本机可达）。如需被同网段的其他机器 / CI 访问，可把
+  host 改为 `0.0.0.0` 或本机局域网 IP——此时**令牌是唯一防线**，请妥善保密并配合防火墙。
+- **访问令牌**：可显示 / 复制 / 重新生成；重新生成后旧令牌立即失效。
+
+## 2. 获取 CLI
+
+**macOS / Linux 一键安装**——自动下载最新版、校验 SHA-256、装到 `PATH`：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/huhamhire/code-meeseeks/main/tools/cli/install.sh | bash
+```
+
+脚本自动探测系统 / 架构并拉取匹配的 Release 压缩包，把 `meebox` 装到 `/usr/local/bin`（不可写则回退
+`~/.local/bin`）。可用环境变量 `MEEBOX_VERSION`（装指定版本）、`MEEBOX_BIN_DIR`（指定安装目录）调整。
+无需单独安装 `SKILL.md`——它已内嵌进二进制（`meebox skill` 可打印）。
+
+**手动下载**（Windows，或不便用脚本时）：从 [GitHub Release](https://github.com/huhamhire/code-meeseeks/releases)
+下载对应平台压缩包（`meebox-cli-<版本>-<系统>-<架构>.zip` / `.tar.gz`），解压后把 `meebox` 放到 `PATH`。
+
+覆盖平台：Windows x64、macOS arm64、Linux x64 / arm64。压缩包内含 `meebox` 二进制、`LICENSE`、`README.md`
+与 `SKILL.md`（作为 agent skill 投放见 [第 6 节](#6-作为-agent-skill-集成)）。
+
+## 3. 连接方式
+
+`meebox` 按以下优先级解析 API 地址与令牌（高 → 低）：
+
+1. 命令行参数：`--api-url` / `--token`
+2. 环境变量：`MEEBOX_API_URL` / `MEEBOX_TOKEN`
+3. CLI 配置文件：`~/.code-meeseeks/cli.yaml`（字段 `api_url` / `token`）
+
+连接信息须**显式提供**其一。令牌在设置页「集成」分区查看 / 复制。最省事的方式是用 `meebox login` 存一次令牌
+（写入 `cli.yaml`），之后所有命令免传参：
+
+```bash
+meebox login --token <令牌>            # 默认连本机 http://127.0.0.1:18765
+meebox login --token <令牌> --server http://<主机>:18765   # 指定远端服务
+meebox pr list                          # 后续命令直接用已存的凭据
+```
+
+或用环境变量（适合 CI / shell 注入）：
+
+```bash
+export MEEBOX_API_URL=http://127.0.0.1:18765
+export MEEBOX_TOKEN=<令牌>
+meebox pr list
+```
+
+远端访问（服务监听 `0.0.0.0`）同样显式提供地址与令牌：
+
+```bash
+meebox --api-url http://<主机>:18765 --token <令牌> pr list
+```
+
+> CLI **不读取** GUI 主配置 `~/.code-meeseeks/config.yaml`：该文件含代码平台访问令牌等连接层机密，
+> 不从中取服务令牌，避免越权触达预期外的凭据。API 地址默认 `http://127.0.0.1:18765`（未显式指定时）。
+
+## 4. 命令
+
+```text
+meebox [全局参数] <组> <命令> [参数]
+```
+
+根层级的系统性命令 `whoami` / `version` 与具体 PR 无关；其余命令分 `pr`（PR 操作，含 `categories` 筛选词表
+与 `refresh` 刷新）与 `agent`（评审 Agent 操作）两个领域组，其 PR 维度子命令用**必填参数 `--pr <id>`** 指定
+PR（`id` 由 `meebox pr list` 输出获得）。
+
+| 命令 | 用途 |
+| --- | --- |
+| `meebox login --token <令牌> [--server <地址>]` | 保存令牌（与可选服务地址）到 `cli.yaml`，后续命令免传参 |
+| `meebox whoami` | 当前登录身份与集成平台（用户 + 平台 + 连接名） |
+| `meebox version` | 客户端（CLI）+ 服务端（应用）版本；未连接服务端时仅显示客户端版本 |
+| `meebox skill` | 打印内嵌的使用说明（SKILL.md），便于二进制脱离压缩包时自述用法 |
+| `meebox pr categories` | 列出当前平台可用的分类标签（一级发现分类 + 二级状态 / 合并态筛选）——`pr list` 的筛选词表 |
+| `meebox pr refresh` | 触发一次立即刷新（拉取最新 PR），返回本轮变化计数（新增 / 变更 / 移除等）；等同 GUI 里的手动刷新 |
+| `meebox pr list [--category <一级>] [--status <二级>] [--query <检索>] [--skip N] [--limit N]` | PR 列表（精简字段 + 分页，默认 limit 100） |
+| `meebox pr show --pr <id>` | PR 描述详情 |
+| `meebox pr diff --pr <id> [--file <路径>] [--side base\|head]` | 无 `--file` 列变更文件；有则取该文件内容 |
+| `meebox pr activity --pr <id>` | 活动时间线（评论 / 提交 / 评审决断） |
+| `meebox pr commits --pr <id>` | 提交列表 |
+| `meebox pr reviewers --pr <id>` | 评审人审批状态 |
+| `meebox pr approve --pr <id>` | 将 PR 标记为「通过」（发送真实评审决断到平台） |
+| `meebox pr needswork --pr <id>` | 将 PR 标记为「需修改」（发送真实评审决断到平台） |
+| `meebox pr comment --pr <id> <消息>` | 发一条顶层评论到平台 |
+| `meebox agent status --pr <id>` | 评审 Agent 当前执行状态 |
+| `meebox agent history --pr <id>` | 历史会话 |
+| `meebox agent review --pr <id>` | 执行一次自动评审 |
+| `meebox agent instruct --pr <id> <指令> [参数]` | 发送评审指令（`describe` / `review` / `ask` / `improve`） |
+| `meebox agent chat --pr <id> <消息>` | 发送自然语言消息（可触发 Agent 任务） |
+| `meebox agent stop --pr <id>` | 中断该 PR 运行中的评审 Agent（整体停） |
+| `meebox agent run list --pr <id>` | 列出该 PR 运行中 / 排队中的 pr-agent runs |
+| `meebox agent run cancel --pr <id> --run <runId>` | 按 run id 取消单个 pr-agent 工具调用 |
+
+其中 `<id>` 为 PR 的本地标识（列表里的 `id` 字段），由 `meebox pr list` 输出获得。
+
+## 5. 输出格式
+
+全局参数 `--output`：
+
+- **`yaml`（默认）**：结构化又易读（类 kubectl `-o yaml`），适合人在终端查看。
+- **`json`**：适合脚本 / 外部 agent 机器解析。
+
+```bash
+meebox pr list --output json | jq '.[].title'
+```
+
+**退出码**：`0` 成功；非 0 表错误（`2` 鉴权失败、`3` 资源不存在、`1` 其他）；错误信息打到 `stderr`。
+
+## 6. 作为 Agent Skill 集成
+
+`meebox` 的主要交付形态是**可直接投放的 agent skill**：发布压缩包除二进制外一并含 `SKILL.md` /
+`README.md` / `LICENSE`，整个解压目录即是一个可用 skill。
+
+- **投放即用**：把解压目录放进 agent 的 skills 目录（如 `~/.claude/skills/meebox/`）。`SKILL.md`
+  （frontmatter `name: meebox`）向 agent 说明命令树、连接方式与写边界，紧邻其驱动的二进制。
+- **二进制自述**：同一份 `SKILL.md` 于构建期经 `go:embed` 内嵌进二进制，`meebox skill` 可打印之——
+  二进制即便脱离压缩包（如单独放入 `PATH`）也能取回用法，且内容与随包文档构建期一致。
+- **仅有二进制的 fallback**：若手头只有 `meebox` 二进制（缺压缩包 / `SKILL.md` 文件），用 `meebox skill`
+  即可从二进制导出说明、就地重建 skill 目录，无需另找原始文件：
+
+  ```bash
+  mkdir -p ~/.claude/skills/meebox
+  cp "$(command -v meebox)" ~/.claude/skills/meebox/      # 二进制放入 skill 目录
+  meebox skill > ~/.claude/skills/meebox/SKILL.md          # 从内嵌副本导出说明
+  ```
+
+  导出的内容与该二进制同源，天然匹配当前版本。
+- **集成流程**：读 `SKILL.md` 了解能力 → `meebox login` 存一次凭据 → 以 `meebox pr list` / `pr show` /
+  `agent review` 等浏览与驱动评审 → 用 `meebox pr approve` / `needswork` / `comment` 记录结论；机器消费统一
+  取 `--output json`（其字段形状为稳定契约）。
+- **边界内建**：仅开放浏览 + 评审写动作，不含合并与变更类工具（详见下「注意事项」），agent 集成天然不会触发
+  高影响远端操作。
+- **框架无关的接入**：`SKILL.md` 的自动发现是 Claude Code 的 skill 约定，并非跨框架标准。其它 agent / 脚本
+  无需依赖该约定即可集成——直接以 shell 调用 `meebox`、用 `meebox skill` 或 `--help` 取用法、`--output json`
+  取结构化结果。真正可移植的接口是「命令行 + JSON」，`SKILL.md` 自动发现只是 Claude 生态的锦上添花。
+
+## 网络代理
+
+`meebox` 遵循标准的 HTTP 代理环境变量（`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`，大小写均可），无需额外配置：
+
+- 访问**本机**服务（`127.0.0.1` / `localhost`）自动直连、不走代理。
+- 访问**远端**服务（如经 `0.0.0.0` 暴露的机器）时，若设了 `HTTP_PROXY` 则经其出网；可用 `NO_PROXY` 排除特定主机。
+
+## 注意事项
+
+- **写能力范围**：CLI 提供评审写动作——`pr approve` / `pr needswork`（发送真实评审决断）与 `pr comment`
+  （发顶层评论）；但**不提供合并（merge）与变更类 Agent 工具（publish 等）**，有此需求请自行对接代码平台。
+- **令牌安全**：服务令牌在 GUI 的 `~/.code-meeseeks/config.yaml` 明文存储；若写入 CLI 的 `~/.code-meeseeks/cli.yaml`
+  同为明文。监听 `0.0.0.0` 暴露到局域网时尤需保密，并及时通过「重新生成」吊销泄露的令牌。
+- **版本兼容**：若 `meebox` 版本低于应用要求的下限，任意命令都会收到「CLI 过旧、请升级」提示（含双方版本）；
+  按上文「获取 CLI」重装最新版即可。CLI 与应用版本同源发布，正常同步升级不会遇到。
diff --git a/docs/guide/README.md b/docs/guide/README.md
index 1b4afb27..445da964 100644
--- a/docs/guide/README.md
+++ b/docs/guide/README.md
@@ -14,6 +14,7 @@ Code Meeseeks 是本地运行的 PR 评审客户端：连上你的代码平台 
 | [03 · 网络代理配置](03-proxy.md) | 内网 / 受限网络下统一走 HTTP 代理出网 |
 | [04 · 配置文件参考](04-config-reference.md) | `config.yaml` 完整结构与各配置项功能说明（含高级参数） |
 | [05 · 自定义评审规则](05-rules.md) | 编写规则 `.md` 文件：frontmatter 命中条件 + 正文注入 AI 的评审指令 |
+| [06 · CLI 命令行工具](06-cli.md) | 开启本地 API 服务 + 用 `meebox` 命令行浏览 PR / 操作评审 Agent（供脚本 / 外部 agent 集成） |
 
 ## 通用须知
 
diff --git a/package-lock.json b/package-lock.json
index 16fad818..a54716d8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -32,7 +32,7 @@
     },
     "apps/desktop": {
       "name": "@meebox/desktop",
-      "version": "0.8.0",
+      "version": "0.9.0-alpha.1",
       "dependencies": {
         "@iconify-json/material-icon-theme": "^1.2.66",
         "@iconify/react": "^5.2.1",
diff --git a/packages/agent/src/planner.ts b/packages/agent/src/planner.ts
index a9b8fdda..c9b74ef9 100644
--- a/packages/agent/src/planner.ts
+++ b/packages/agent/src/planner.ts
@@ -76,6 +76,11 @@ export interface PlanningInput {
   referencedContext?: string;
   /** 步数上限（默认 8）。 */
   maxSteps?: number;
+  /**
+   * 本会话 /ask 数量上限（遵循配置的「追问数量」max_followup_asks，默认 2）：连续 /ask 各为一次 agentic
+   * 探索、成本高，按此封顶；与「自动追问」开关无关（开关仅约束评审微流程）。
+   */
+  maxFollowupAsks?: number;
 }
 
 export interface PlanningResult {
@@ -126,7 +131,19 @@ export async function runPlanningAgent(
   // 既往多轮对话注入规划上下文（按预算裁剪），让 Agent 跨轮记住交流；仅供规划 LLM 参考，
   // 绝不透传给 pr-agent 工具。
   const convo = buildConversationContext(input.history ?? []);
-  const ctx: PlanStepCtx = { deps, input, rec, system, convo, labels, history, memories, plan: [] };
+  const ctx: PlanStepCtx = {
+    deps,
+    input,
+    rec,
+    system,
+    convo,
+    labels,
+    history,
+    memories,
+    plan: [],
+    maxAsks: input.maxFollowupAsks ?? 2,
+    asksUsed: 0,
+  };
 
   // 规划是单步循环：重复跑 plan-cycle 直至收尾 / 暂停 / 步数上限。
   for (let i = 0; i < maxSteps; i++) {
diff --git a/packages/agent/src/steps/planning/plan-cycle-step.ts b/packages/agent/src/steps/planning/plan-cycle-step.ts
index ca88088e..bd496d81 100644
--- a/packages/agent/src/steps/planning/plan-cycle-step.ts
+++ b/packages/agent/src/steps/planning/plan-cycle-step.ts
@@ -87,14 +87,13 @@ export class PlanCycleStep extends Step<PlanStepCtx, PlanCycleOutcome> {
           .map((tl) => (typeof tl === 'string' ? { tool: tl } : { tool: tl.tool ?? '', question: tl.question }))
       : [{ tool: action.tool ?? '', question: action.question }];
 
-    // 红线硬校验逐个把关：未授权 / 未知即拒并回喂；允许的留待并行执行。
+    // 红线硬校验逐个把关：未授权 / 未知即拒并回喂；/ask 另按配置的追问上限封顶（连续 agentic 探索成本高）；
+    // 允许的留待并行执行。
+    const isAsk = (tool: string): boolean => tool.replace(/^\//, '') === 'ask';
     const allowed: Array<{ tool: string; question?: string }> = [];
+    let asksAccepted = 0;
     for (const c of requested) {
-      try {
-        assertToolAllowed(c.tool, input.toolCatalog);
-        allowed.push(c);
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+      const reject = async (msg: string): Promise<void> => {
         await rec.record({
           kind: 'judge',
           thought: action.thought,
@@ -102,7 +101,22 @@ export class PlanCycleStep extends Step<PlanStepCtx, PlanCycleOutcome> {
           result: `${labels.rejectedPrefix}${msg}`,
         });
         history.push(`Refused ${c.tool}: ${msg}`);
+      };
+      try {
+        assertToolAllowed(c.tool, input.toolCatalog);
+      } catch (err) {
+        await reject(err instanceof Error ? err.message : String(err));
+        continue;
+      }
+      // /ask 预算：达上限即拒并回喂，促使模型据现有上下文收尾或改用只读工具（本会话累计计数，跨轮生效）。
+      if (isAsk(c.tool) && ctx.asksUsed + asksAccepted >= ctx.maxAsks) {
+        await reject(
+          `Follow-up /ask budget exhausted (${ctx.maxAsks}). Do not call /ask again — answer with the context you already have, or use read-only file tools.`,
+        );
+        continue;
       }
+      allowed.push(c);
+      if (isAsk(c.tool)) asksAccepted++;
     }
     if (!allowed.length) return { kind: 'continue' }; // 全被拒 → 回喂后下一轮重选
 
@@ -122,6 +136,8 @@ export class PlanCycleStep extends Step<PlanStepCtx, PlanCycleOutcome> {
       rec.track(res.usage);
       history.push(`Called ${c.tool}${c.question ? ` ("${c.question}")` : ''} → ${clamp(res.text, 600)}`);
     }
+    // 累加本轮已发起的 /ask 计数（跨轮生效，达 maxAsks 后新的 /ask 会被上面的预算闸拒绝）。
+    ctx.asksUsed += asksAccepted;
     return { kind: 'continue' };
   }
 }
diff --git a/packages/agent/src/steps/planning/shared.ts b/packages/agent/src/steps/planning/shared.ts
index fb6caf6a..8bd09ce4 100644
--- a/packages/agent/src/steps/planning/shared.ts
+++ b/packages/agent/src/steps/planning/shared.ts
@@ -138,6 +138,13 @@ export interface PlanStepCtx {
   memories: AgentMemoryNotes;
   /** 当前计划（todo），逐轮回喂提示；模型给出 plan 即更新（重排 / 勾选 / 增删）。 */
   plan: AgentTodoItem[];
+  /**
+   * 本会话 /ask 数量上限（遵循配置的「追问数量」max_followup_asks）：自由规划里连续 /ask（各为一次
+   * agentic 探索）成本高，按此封顶——与「自动追问」开关无关（开关仅约束评审微流程）。
+   */
+  maxAsks: number;
+  /** 本会话已发起的 /ask 计数，逐轮累加；达 maxAsks 后拒绝新的 /ask 并回喂促收尾。 */
+  asksUsed: number;
 }
 
 /** plan-cycle 的产出：继续下一轮 / 收尾（带 final + 可选建议）/ 用户暂停。 */
diff --git a/packages/agent/tests/planner.test.ts b/packages/agent/tests/planner.test.ts
index 22894548..8d69aeed 100644
--- a/packages/agent/tests/planner.test.ts
+++ b/packages/agent/tests/planner.test.ts
@@ -67,6 +67,26 @@ describe('runPlanningAgent', () => {
     expect(r.finalText).toBe('done');
   });
 
+  it('caps /ask calls at maxFollowupAsks (refuses over-budget asks, keeps other tools)', async () => {
+    const { deps, toolCalls } = makeDeps([
+      '{"thought":"ask 1","tool":"/ask","question":"q1"}',
+      '{"thought":"ask 2","tool":"/ask","question":"q2"}',
+      '{"thought":"ask 3 (over budget)","tool":"/ask","question":"q3"}',
+      '{"thought":"fall back to review","tool":"/review"}',
+      '{"final":"answer"}',
+    ]);
+    const r = await runPlanningAgent(deps, {
+      context,
+      pr,
+      toolCatalog: catalog,
+      userRequest: 'explore deeply',
+      maxFollowupAsks: 2,
+    });
+    // 前两次 /ask 执行；第三次超预算被拒（不进 runTool）；/review 不受 /ask 预算约束仍可执行。
+    expect(toolCalls.map((c) => c.tool)).toEqual(['/ask', '/ask', '/review']);
+    expect(r.finalText).toBe('answer');
+  });
+
   it('runs allowed tools and refuses disallowed ones within the same multi-tool turn', async () => {
     const { deps, toolCalls } = makeDeps([
       '{"tools":["/review","/approve"]}',
diff --git a/packages/ipc/src/agent.ts b/packages/ipc/src/agent.ts
index 9c6c1f89..568aee5c 100644
--- a/packages/ipc/src/agent.ts
+++ b/packages/ipc/src/agent.ts
@@ -4,6 +4,7 @@ import type {
   AgentSession,
   AgentStep,
   ReviewRun,
+  ReviewRunCommitScope,
   ReviewRunTool,
 } from '@meebox/shared';
 import type { PragentRunInfo } from './common.js';
@@ -93,6 +94,8 @@ export interface AgentChannels {
      * EXTRA_INSTRUCTIONS 注入，不进入问题位置参数（故不污染回答 echo / 会话气泡）。
      * referencedFinding：复评引用——本次 /ask 是对先前 review/improve 某条 finding 的复评（前向链，
      * 落到 ReviewRun.referencedFinding），驱动复评模式提示词 + 结果卡的裁决动作。仅 tool='ask' 生效。
+     * scope：单 commit 评审范围（parent..sha）——由 Diff 视图提交选择器发起，把本次 run 的 diff 限定在
+     * 该 commit 自身改动而非 PR 全量。对 describe/review/ask/improve 均生效；缺省 = PR 全量范围。
      */
     request: {
       localId: string;
@@ -100,6 +103,7 @@ export interface AgentChannels {
       question?: string;
       referencedContext?: string;
       referencedFinding?: ReviewRun['referencedFinding'];
+      scope?: ReviewRunCommitScope;
     };
     response: ReviewRun;
   };
diff --git a/packages/ipc/src/app.ts b/packages/ipc/src/app.ts
index fcb5ae83..cbb0aff3 100644
--- a/packages/ipc/src/app.ts
+++ b/packages/ipc/src/app.ts
@@ -55,6 +55,14 @@ export interface AppChannels {
     request: { defaultPath?: string; title: string };
     response: { path: string | null };
   };
+  /**
+   * 由渲染层在主题应用后推送当前主题派生的窗控按钮配色（Windows titleBarOverlay：color=--bg-app、
+   * symbolColor=--text-primary），使系统窗控按钮与具体主题的标题栏底色精确同色；null 回退通用深 / 浅色。
+   */
+  'window:setControlColors': {
+    request: { color: string; symbolColor: string } | null;
+    response: void;
+  };
   /** 各连接的 ping 后缓存：当前用户 + display_name，Header 用 */
   'app:connections': { request: void; response: ConnectionSummary[] };
   /**
diff --git a/packages/ipc/src/common.ts b/packages/ipc/src/common.ts
index a94e0bdb..31cc47cf 100644
--- a/packages/ipc/src/common.ts
+++ b/packages/ipc/src/common.ts
@@ -1,6 +1,8 @@
 import type {
   PlatformCapabilities,
   PlatformUser,
+  ReviewRunCommitScope,
+  ReviewRunOrigin,
   ReviewRunTool,
 } from '@meebox/shared';
 
@@ -56,6 +58,10 @@ export interface PragentRunInfo {
   prNumber: string;
   tool: ReviewRunTool;
   question?: string;
+  /** 触发来源：user（手动发起）/ agent（编排派发）。ChatPane 据此为 user 来源的运行中 run 补命令回显气泡。 */
+  origin: ReviewRunOrigin;
+  /** 单 commit 评审范围（parent..sha）；限定在某 commit 时填，运行中卡片据此展示范围徽标。缺省 = PR 全量。 */
+  scope?: ReviewRunCommitScope;
   /** 入队时间，ISO */
   enqueuedAt: string;
   /** 开始执行时间，ISO；waiting 状态为 null */
diff --git a/packages/ipc/src/config.ts b/packages/ipc/src/config.ts
index 2834f3f5..93e6ea1c 100644
--- a/packages/ipc/src/config.ts
+++ b/packages/ipc/src/config.ts
@@ -60,6 +60,13 @@ export interface ConfigChannels {
     request: { base_url: string; token: string; kind?: PlatformKind };
     response: PingResult;
   };
+  /**
+   * 写入本地 API 服务监听配置（开关 / host / port / token）到 config.yaml，并**热重建**监听器
+   * （开关 / 地址 / 端口变更停旧起新；token 变更下次请求即生效）。见 docs/arch/04-integration/01-service-api.md。
+   */
+  'config:setService': { request: { service: Config['service'] }; response: void };
+  /** 重新生成 bearer token 并写盘（旧 token 即时失效），返回新 token 供设置页展示 / 复制。 */
+  'config:generateServiceToken': { request: void; response: { token: string } };
   /**
    * 配置过程中自动把连接 + LLM 草稿写入 config.yaml（防丢失），但**不应用到运行时**
    * （不 reconfigure adapter/poller、不更新内存 config）——重启或点底栏「保存」才生效。
diff --git a/packages/poller/src/parse-output.ts b/packages/poller/src/parse-output.ts
index a5392ca1..864befc8 100644
--- a/packages/poller/src/parse-output.ts
+++ b/packages/poller/src/parse-output.ts
@@ -111,14 +111,14 @@ function normalizeTitle(t: string): string {
   return t.replace(/[*_]+/g, '').trim();
 }
 
-/** 我们 materializeWorktree 临时建的内部分支名，pr-agent 把它当 PR 标识漏出来 */
-const INTERNAL_BRANCH_RE = /meebox\/(head|base)/i;
+/** 我们 materializeWorktree 临时建的内部分支名（`pr-<localId>/head|base`），pr-agent 把它当 PR 标识漏出来 */
+const INTERNAL_BRANCH_RE = /pr-[\w-]+\/(head|base)\b/i;
 
 /**
  * 剥 body 首尾的"噪音行"：连续 markdown HR (`---` / `***` / `___`)、空行、
- * 整行就是 `meebox/head|base` 的内部分支名 leak。pr-agent 在段落间用 `---`
+ * 整行就是 `pr-<localId>/head|base` 的内部分支名 leak。pr-agent 在段落间用 `---`
  * 分隔，splitMarkdownSections 切完后这条 HR 会黏在上一个 section 的 body 末尾；
- * 类似地 meebox/head 这种 PR identifier leak 也可能停在 body 首或尾。
+ * 类似地 pr-<localId>/head 这种 PR identifier leak 也可能停在 body 首或尾。
  * 全部在 parser 层清掉，下游 / 渲染 / 胶囊拆分都不用关心。
  */
 function trimNoise(body: string): string {
@@ -178,7 +178,7 @@ function mapSectionKey(displayTitle: string): PrDocSectionKey | undefined {
 /**
  * 噪音段落，直接从 findings 里剔除：
  * - `user description`：纯粹回显用户已写的 PR 描述，UI 上已有 PrInfoView 显示
- * - title 含 `meebox/head|base`：我们临时建的分支名，pr-agent 把它当 PR 标识
+ * - title 含 `pr-<localId>/head|base`：我们临时建的分支名，pr-agent 把它当 PR 标识
  *   作为各级 heading leak 出来（含 emoji / 修饰也照样匹配，子串就行）
  * - 空 title + 经 trimNoise 后空 body：纯分支名 leak 的独立 section
  * - /ask 工具下的 `question` / `questions` 段：UI 上方 chat-user-msg 已展示用户提问，
@@ -210,7 +210,7 @@ function shouldSkipSection(sec: Section, tool: ReviewRunTool): boolean {
     if (kind === 'question') return true;
     if (kind === 'answer' && !trimNoise(sec.body).trim()) return true;
   }
-  // title 含内部分支名 (e.g., "meebox/head" / "meebox/head 🔍" / "## meebox/head")
+  // title 含内部分支名 (e.g., "pr-<id>/head" / "pr-<id>/head 🔍" / "## pr-<id>/base")
   if (INTERNAL_BRANCH_RE.test(t)) return true;
   // trimNoise 把首尾的 HR / 分支名 leak 剥掉后，body 空 = 整段都是噪音
   const cleanedBody = trimNoise(sec.body).trim();
diff --git a/packages/poller/src/poller.ts b/packages/poller/src/poller.ts
index f2afb418..74c5afaa 100644
--- a/packages/poller/src/poller.ts
+++ b/packages/poller/src/poller.ts
@@ -11,7 +11,7 @@ import type {
 import type { PlatformAdapter } from '@meebox/platform-core';
 import { relocateTree, type StateStore } from '@meebox/state-store';
 import { prHashId } from './pr-hash-id.js';
-import { collectMentionsToMe } from './unread.js';
+import { collectCommentsFromOthers, collectMentionsToMe } from './unread.js';
 import {
   MENTION_ATS_CAP,
   PURGE_GRACE_MS,
@@ -333,6 +333,44 @@ export class Poller {
             });
           }
 
+          // 「我创建的」PR（作者为本人）通知：被标记需修改 / 出现冲突。仅在已有基线 + 已知 PR（prev）时探测；
+          // 各自的上一轮快照字段缺失（升级前旧索引）时按「基线」处理——只在下方索引写入处播种、不补发历史事件。
+          const authoredByMe = !!me && pr.author.name === me.name;
+          const needsWorkReviewers = pr.reviewers
+            .filter((r) => r.status === 'needsWork')
+            .map((r) => r.name);
+          if (authoredByMe && hadBaseline && prev) {
+            // 新出现的「需修改」评审人（本轮在 needsWork、上一轮不在）→ authored_needs_work。
+            const prevNW = prev.needsWorkReviewers;
+            if (prevNW !== undefined) {
+              const fresh = needsWorkReviewers.filter((n) => !prevNW.includes(n));
+              if (fresh.length > 0) {
+                const reviewer = pr.reviewers.find((r) => r.name === fresh[0]) ?? pr.author;
+                notifyEvents.push({
+                  kind: 'authored_needs_work',
+                  localId,
+                  connectionId,
+                  remoteId: pr.remoteId,
+                  title: pr.title,
+                  repo: pr.repo,
+                  actor: reviewer,
+                });
+              }
+            }
+            // 合并冲突 false→true → authored_conflict（无具体发起人，actor 取 PR 作者本人）。
+            if (prev.hasConflict === false && pr.hasConflict === true) {
+              notifyEvents.push({
+                kind: 'authored_conflict',
+                localId,
+                connectionId,
+                remoteId: pr.remoteId,
+                title: pr.title,
+                repo: pr.repo,
+                actor: pr.author,
+              });
+            }
+          }
+
           // 复活：上一轮处于归档态（数据已搬入 archived/）→ 先把整树搬回活跃存储，再写 meta，
           // 让 runs / 评论 / 已读水位等历史与新 meta 同处活跃目录（搬回先于 writePrMeta，避免 split）。
           if (prev?.archivedAt) {
@@ -372,6 +410,7 @@ export class Poller {
             : true;
           let lastMentionAt = prev?.lastMentionAt;
           let mentionAts = prev?.mentionAts;
+          let lastCommentAt = prev?.lastCommentAt;
           if (notifiable && me && shouldScanComments) {
             try {
               const comments = await adapter.comments.listPullRequestComments(
@@ -417,6 +456,40 @@ export class Poller {
                   project('mention');
                 }
               }
+              // 「我创建的」PR：他人新评论（不限是否 @我 / 回复我，自己的评论不计）→ authored_comment。
+              // 独立游标 lastCommentAt：晚于它的他人评论计为新；游标缺失（升级前）时仅播种、不补发历史评论。
+              if (authoredByMe) {
+                const others = collectCommentsFromOthers(comments, me);
+                if (others.length) {
+                  const newest = others.reduce((a, b) =>
+                    Date.parse(b.at) > Date.parse(a.at) ? b : a,
+                  );
+                  const prevCursor = prev?.lastCommentAt;
+                  if (prevCursor !== undefined) {
+                    const sinceMs = Date.parse(prevCursor);
+                    const fresh = others.filter((o) => Date.parse(o.at) > sinceMs);
+                    if (fresh.length > 0) {
+                      const latest = fresh.reduce((a, b) =>
+                        Date.parse(b.at) > Date.parse(a.at) ? b : a,
+                      );
+                      notifyEvents.push({
+                        kind: 'authored_comment',
+                        localId,
+                        connectionId,
+                        remoteId: pr.remoteId,
+                        title: pr.title,
+                        repo: pr.repo,
+                        actor: latest.author,
+                        count: fresh.length,
+                        comment: { remoteId: latest.commentRemoteId, anchor: latest.anchor },
+                      });
+                    }
+                  }
+                  if (!lastCommentAt || Date.parse(newest.at) > Date.parse(lastCommentAt)) {
+                    lastCommentAt = newest.at;
+                  }
+                }
+              }
             } catch (err) {
               this.opts.logger.warn(
                 { err, connectionId, localId },
@@ -435,6 +508,9 @@ export class Poller {
             archivedAt: null,
             lastMentionAt,
             mentionAts,
+            hasConflict: pr.hasConflict,
+            needsWorkReviewers,
+            lastCommentAt,
           });
         }
       } catch (err) {
diff --git a/packages/poller/src/pr-state.ts b/packages/poller/src/pr-state.ts
index a17460ac..382d2925 100644
--- a/packages/poller/src/pr-state.ts
+++ b/packages/poller/src/pr-state.ts
@@ -42,6 +42,16 @@ export interface PrIndexEntry {
    * 并存、互不替代。同 `lastMentionAt` 由 poll 独占维护，与已读水位解耦。
    */
   mentionAts?: string[];
+  /**
+   * 「我创建的」PR 通知用的上一轮快照（poll 独占维护）。仅当 PR 作者为本人时才据此产出 authored_* 通知；
+   * 字段缺失（升级前的旧索引）时对应事件按「基线」处理——只播种、不补发，避免升级后一次性涌入历史事件。
+   */
+  /** 上一轮的合并冲突态（== PullRequest.hasConflict）；用于探测 false→true 的新增冲突。 */
+  hasConflict?: boolean;
+  /** 上一轮处于「需修改」状态的评审人 name 列表；用于探测新出现的 needs-work 评审人。 */
+  needsWorkReviewers?: string[];
+  /** 上一轮已知的最新「他人评论」createdAt（ISO）游标；晚于它的他人评论计为新评论。 */
+  lastCommentAt?: string;
 }
 
 /** mentionAts 保留上限：仅留最近 10 条。未读计数据此封顶，UI 满额显示「10+」。 */
diff --git a/packages/poller/src/runs.ts b/packages/poller/src/runs.ts
index 2b155344..eaa81bfc 100644
--- a/packages/poller/src/runs.ts
+++ b/packages/poller/src/runs.ts
@@ -54,6 +54,10 @@ export interface StartReviewRunInput {
   model?: string;
   /** 复评引用：本次 /ask 是对某条 finding 的复评时，记下被引用的源 finding（前向链）。 */
   referencedFinding?: ReviewRun['referencedFinding'];
+  /** 触发来源：user（手动）/ agent（编排派发）。用于 ChatPane 命令回显气泡；缺省不回显。 */
+  origin?: ReviewRun['origin'];
+  /** 单 commit 评审范围（parent..sha）；缺省 = PR 全量范围。落盘供结果卡展示范围徽标。 */
+  scope?: ReviewRun['scope'];
 }
 
 /** 写入初始 running 状态；调用方在 pr-agent 调用前必须先 start。 */
@@ -72,6 +76,8 @@ export async function startReviewRun(
     strategy: input.strategy,
     model: input.model,
     referencedFinding: input.referencedFinding,
+    origin: input.origin,
+    scope: input.scope,
     status: 'running',
     startedAt: at.toISOString(),
   };
diff --git a/packages/poller/src/unread.ts b/packages/poller/src/unread.ts
index f6fa0dbf..de1fded2 100644
--- a/packages/poller/src/unread.ts
+++ b/packages/poller/src/unread.ts
@@ -76,6 +76,46 @@ export function collectMentionsToMe(
   return hits;
 }
 
+/** 评论树里一条**他人**评论（不限是否 @我 / 回复我）：时间 + 作者 + 定位。用于「我创建的」PR 的新评论通知。 */
+export interface CommentHit {
+  at: string;
+  author: PlatformUser;
+  commentRemoteId: string;
+  anchor: PrCommentAnchor | null;
+}
+
+/**
+ * 评论树里**所有他人评论**（作者非当前用户）的命中，深度优先、自然到达顺序（未排序）。与
+ * {@link collectMentionsToMe} 不同：不筛 @我 / 回复我，收全部他人评论——供「我创建的」PR 的「收到新评论」通知
+ * 用（作者本人的评论不计，故不会因自己评论而误报）。
+ */
+export function collectCommentsFromOthers(
+  comments: readonly PrComment[],
+  me: PlatformUser,
+): CommentHit[] {
+  const handles = [me.name, me.slug].filter((x): x is string => !!x);
+  const lowered = new Set(handles.map((h) => h.toLowerCase()));
+  const isMe = (u: PlatformUser): boolean =>
+    lowered.has(u.name.toLowerCase()) || (u.slug ? lowered.has(u.slug.toLowerCase()) : false);
+
+  const hits: CommentHit[] = [];
+  const walk = (list: readonly PrComment[]): void => {
+    for (const c of list) {
+      if (!isMe(c.author)) {
+        hits.push({
+          at: c.createdAt,
+          author: c.author,
+          commentRemoteId: c.remoteId,
+          anchor: c.anchor,
+        });
+      }
+      if (c.replies?.length) walk(c.replies);
+    }
+  };
+  walk(comments);
+  return hits;
+}
+
 /**
  * 评论树里所有「@我 / 回复我」他人评论的 createdAt（ISO）列表。基于 {@link collectMentionsToMe}。
  */
diff --git a/packages/poller/tests/poller.test.ts b/packages/poller/tests/poller.test.ts
index 36cb5548..73204470 100644
--- a/packages/poller/tests/poller.test.ts
+++ b/packages/poller/tests/poller.test.ts
@@ -170,6 +170,13 @@ function makePr(id: string, updatedAt: string, title = `PR ${id}`): PullRequest
   };
 }
 
+/** 「我创建的」PR：作者即当前用户（默认 alice）。用于 authored_* 通知测试。 */
+function makeAuthoredPr(id: string, updatedAt: string, author = 'alice'): PullRequest {
+  const pr = makePr(id, updatedAt);
+  pr.author = { name: author, displayName: author };
+  return pr;
+}
+
 let tmpDir: string;
 let store: JsonFileStateStore;
 // 归档冷存储：与 store 物理分离（store 根 = tmpDir，archived 根 = tmpDir/archived）。
@@ -1027,4 +1034,118 @@ describe('Poller onNotify (system notification projection)', () => {
     expect(adapter.commentCalls).toBe(1); // 未变化 → 未扫
     expect(events.length).toBe(eventsLen); // 无新事件
   });
+
+  it('authored PR: fires authored_needs_work when a reviewer newly marks needs-work', async () => {
+    const adapter = new FakeAdapter([makeAuthoredPr('1', '2026-05-28T01:00:00.000Z')]);
+    adapter.seedUser('alice');
+    const events: PollNotificationEvent[] = [];
+    let now = new Date('2026-06-01T00:00:00.000Z');
+    const poller = new Poller({
+      connections: [{ connectionId: 'bb1', adapter }],
+      stateStore: store,
+      archiveStore,
+      intervalSeconds: 60,
+      logger: noopLogger,
+      now: () => now,
+      onNotify: (e) => events.push(...e),
+    });
+
+    await poller.tick(); // 基线：无 needsWork 评审人
+    expect(events).toEqual([]);
+
+    now = new Date('2026-06-02T00:00:00.000Z');
+    const changed = makeAuthoredPr('1', '2026-05-29T01:00:00.000Z');
+    changed.reviewers = [{ name: 'bob', displayName: 'Bob', status: 'needsWork' as const }];
+    adapter.setPrs([changed]);
+    await poller.tick();
+
+    const e = events.find((x) => x.kind === 'authored_needs_work');
+    expect(e).toBeDefined();
+    expect(e!.remoteId).toBe('1');
+    expect(e!.actor.name).toBe('bob'); // 标记需修改的评审人
+  });
+
+  it('authored PR: fires authored_conflict on a false→true merge-conflict transition', async () => {
+    const adapter = new FakeAdapter([makeAuthoredPr('1', '2026-05-28T01:00:00.000Z')]);
+    adapter.seedUser('alice');
+    const events: PollNotificationEvent[] = [];
+    let now = new Date('2026-06-01T00:00:00.000Z');
+    const poller = new Poller({
+      connections: [{ connectionId: 'bb1', adapter }],
+      stateStore: store,
+      archiveStore,
+      intervalSeconds: 60,
+      logger: noopLogger,
+      now: () => now,
+      onNotify: (e) => events.push(...e),
+    });
+
+    await poller.tick(); // 基线：无冲突
+    expect(events).toEqual([]);
+
+    now = new Date('2026-06-02T00:00:00.000Z');
+    const conflicted = makeAuthoredPr('1', '2026-05-29T01:00:00.000Z');
+    conflicted.hasConflict = true;
+    conflicted.mergeStatus = { canMerge: false, conflicted: true, vetoes: [] };
+    adapter.setPrs([conflicted]);
+    await poller.tick();
+
+    const e = events.find((x) => x.kind === 'authored_conflict');
+    expect(e).toBeDefined();
+    expect(e!.remoteId).toBe('1');
+  });
+
+  it('authored PR: seeds the comment cursor silently, then fires authored_comment on a later new comment', async () => {
+    const adapter = new FakeAdapter([makeAuthoredPr('1', '2026-05-28T01:00:00.000Z')]);
+    adapter.seedUser('alice');
+    const events: PollNotificationEvent[] = [];
+    let now = new Date('2026-06-01T00:00:00.000Z');
+    const poller = new Poller({
+      connections: [{ connectionId: 'bb1', adapter }],
+      stateStore: store,
+      archiveStore,
+      intervalSeconds: 60,
+      logger: noopLogger,
+      now: () => now,
+      onNotify: (e) => events.push(...e),
+    });
+
+    await poller.tick(); // 基线：首轮不 notifiable、不扫评论
+
+    // 第二轮：出现一条他人评论 → 仅播种游标、不补发历史评论。
+    now = new Date('2026-06-02T00:00:00.000Z');
+    adapter.setPrs([makeAuthoredPr('1', '2026-05-29T01:00:00.000Z')]);
+    adapter.seedComments([
+      makeComment({
+        author: { name: 'bob', displayName: 'Bob' },
+        body: 'looks good',
+        createdAt: '2026-06-02T00:00:00.000Z',
+      }),
+    ]);
+    await poller.tick();
+    expect(events.some((e) => e.kind === 'authored_comment')).toBe(false);
+
+    // 第三轮：又来一条更晚的他人评论（晚于游标）→ 触发 authored_comment。
+    now = new Date('2026-06-03T00:00:00.000Z');
+    adapter.setPrs([makeAuthoredPr('1', '2026-05-30T01:00:00.000Z')]);
+    adapter.seedComments([
+      makeComment({
+        author: { name: 'bob', displayName: 'Bob' },
+        body: 'looks good',
+        createdAt: '2026-06-02T00:00:00.000Z',
+      }),
+      makeComment({
+        author: { name: 'bob', displayName: 'Bob' },
+        body: 'one more thing',
+        createdAt: '2026-06-03T00:00:00.000Z',
+      }),
+    ]);
+    await poller.tick();
+
+    const e = events.find((x) => x.kind === 'authored_comment');
+    expect(e).toBeDefined();
+    expect(e!.remoteId).toBe('1');
+    expect(e!.count).toBe(1);
+    expect(e!.actor.name).toBe('bob');
+  });
 });
diff --git a/packages/pr-agent-bridge/src/bridge.ts b/packages/pr-agent-bridge/src/bridge.ts
index 1332a906..df4bc78a 100644
--- a/packages/pr-agent-bridge/src/bridge.ts
+++ b/packages/pr-agent-bridge/src/bridge.ts
@@ -94,7 +94,7 @@ export class LocalCliBridge extends BaseBridge {
       // LocalGitProvider(target_branch_name)，**--pr_url 在 local 模式下就是
       // target branch 的名字**，不是 PR URL 或路径。仓库根靠容器 cwd 自己走 .git
       // 父目录查找定位，跟 --pr_url 无关。
-      // 所以这里把 opts.targetBranch (= materializeWorktree 建好的 meebox/base)
+      // 所以这里把 opts.targetBranch (= materializeWorktree 建好的 pr-<localId>/base)
       // 直接填到 --pr_url 槽位。
       return {
         cmd: 'pr-agent',
diff --git a/packages/pr-agent-bridge/src/prompts.ts b/packages/pr-agent-bridge/src/prompts.ts
index 0a7edc7a..73dacfe4 100644
--- a/packages/pr-agent-bridge/src/prompts.ts
+++ b/packages/pr-agent-bridge/src/prompts.ts
@@ -179,6 +179,28 @@ function referencedAskDirective(tool: ReviewRunTool, hasReferencedFinding: boole
   ].join('\n');
 }
 
+/**
+ * /ask 代码检索指引（仅 CLI 提供方：子进程 cwd 落在完整 worktree、具备文件工具时注入）。引导 agentic CLI 以
+ * **定向检索**（内置只读搜索 / `grep` 查符号 · 只读所需行段）替代整文件通读与全仓扫描，压掉冷启动探索的浪费性
+ * token，同时保留读真实文件的深度。刻意只用**只读**工具集：headless（无 TTY）下 default 权限模式对非只读工具
+ * （写 / `rg` 等不在内置只读白名单的命令）不是拒绝而是**直接中止会话**，故不得诱导 `rg` 等命令。API 提供方无
+ * 文件访问、不注入（enabled=false）。
+ */
+function worktreeRetrievalDirective(tool: ReviewRunTool, enabled: boolean): string {
+  if (tool !== 'ask' || !enabled) return '';
+  return [
+    'CODE RETRIEVAL: the full repository worktree is your working directory. Answer efficiently',
+    'using your READ-ONLY file tools — do NOT read whole files or scan the whole repo:',
+    '- Treat the PR diff above as the source of truth for what changed.',
+    '- Locate the specific symbols, definitions, and call sites you need with your built-in file',
+    '  search (or the `grep` command); then read only the narrow file ranges the question requires.',
+    '- Do NOT run commands that modify files or the system, and avoid non-read-only shell tools',
+    '  (e.g. use `grep`, not `rg`); a read-only search plus a targeted read is enough.',
+    '- Stop once you have enough context to answer; avoid speculative browsing.',
+    'If you have no file tools, just answer from the diff and context above.',
+  ].join('\n');
+}
+
 /**
  * 组装注入 pr-agent 的 EXTRA_INSTRUCTIONS：按序拼接 语言指示 / anchor marker / 结构化分段 / 复评裁决 /
  * 排版 / PR 上下文 / 命中规则，空段跳过；全空返回 undefined（调用方据此决定是否设 env）。
@@ -197,12 +219,15 @@ export function buildExtraInstructions(input: {
   referencedFinding?: boolean;
   /** 代码建议数量上限（2~8）：/ask 的 <suggestions> 软约束（仅 /ask 用到）。空则不封顶。 */
   maxCodeSuggestions?: number;
+  /** 是否注入 /ask 代码检索指引（仅 CLI 提供方：子进程可在完整 worktree 里用 shell/文件工具时为真）。 */
+  worktreeRetrieval?: boolean;
 }): string | undefined {
   const parts = [
     languageDirectiveFor(input.language),
     anchorMarkerDirective(input.tool),
     structuredAskDirective(input.tool, input.maxCodeSuggestions),
     referencedAskDirective(input.tool, !!input.referencedFinding),
+    worktreeRetrievalDirective(input.tool, !!input.worktreeRetrieval),
     reviewLayoutDirective(input.tool),
     input.prContext,
     input.referencedContext ?? '',
diff --git a/packages/pr-agent-bridge/tests/bridge.test.ts b/packages/pr-agent-bridge/tests/bridge.test.ts
index 3134f220..52faedf0 100644
--- a/packages/pr-agent-bridge/tests/bridge.test.ts
+++ b/packages/pr-agent-bridge/tests/bridge.test.ts
@@ -92,10 +92,10 @@ describe('LocalCliBridge', () => {
     await bridge.review({
       prUrl: 'https://x/pr/1', // 本地模式下 prUrl 不会被用到
       cwd: '/tmp/wt/abc',
-      targetBranch: 'meebox/base',
+      targetBranch: 'pr-abc123/base',
       env: { OPENAI_KEY: 'sk' },
     });
-    expect(calls[0]!.args).toEqual(['--pr_url', 'meebox/base', 'review']);
+    expect(calls[0]!.args).toEqual(['--pr_url', 'pr-abc123/base', 'review']);
     expect(calls[0]!.opts.cwd).toBe('/tmp/wt/abc');
     expect(calls[0]!.opts.env).toEqual({
       OPENAI_KEY: 'sk',
@@ -126,7 +126,7 @@ describe('EmbeddedRuntimeBridge', () => {
     await bridge.review({
       prUrl: 'unused',
       cwd: '/tmp/wt/abc',
-      targetBranch: 'meebox/base',
+      targetBranch: 'pr-abc123/base',
       env: { OPENAI__KEY: 'sk' },
     });
     expect(calls[0]!.cmd).toBe(PY);
@@ -134,7 +134,7 @@ describe('EmbeddedRuntimeBridge', () => {
       '-m',
       'pr_agent.cli',
       '--pr_url',
-      'meebox/base',
+      'pr-abc123/base',
       'review',
     ]);
     expect(calls[0]!.opts.cwd).toBe('/tmp/wt/abc');
diff --git a/packages/repo-mirror/src/repo-mirror-manager.ts b/packages/repo-mirror/src/repo-mirror-manager.ts
index 087a6a22..c252b53c 100644
--- a/packages/repo-mirror/src/repo-mirror-manager.ts
+++ b/packages/repo-mirror/src/repo-mirror-manager.ts
@@ -318,15 +318,17 @@ export class RepoMirrorManager {
   }
 
   /**
-   * 从 bare mirror 派生一个**自含**的临时工作树，HEAD 在命名分支 `meebox/head`
-   * 上指向 headSha；可选再建个 `meebox/base` 指向 baseSha。
+   * 从 bare mirror 派生一个**自含**的临时工作树，HEAD 在命名分支 `pr-<localId>/head`
+   * 上指向 headSha；可选再建个 `pr-<localId>/base` 指向 baseSha。
    *
    * 为什么需要这样：pr-agent 社区版 `LocalGitProvider.__init__` 做两件强约束的事：
    *   - `self.head_branch_name = self.repo.head.ref.name` —— HEAD 必须在命名分支
    *     上（不能 detached），否则 GitPython 抛 TypeError
    *   - `LOCAL__TARGET_BRANCH` 必须是 `self.repo.heads` 里存在的**分支名**
    *     （不接受 sha），否则 `branches[target_name]` KeyError
-   * 我们用 `meebox/<head|base>` 这种带前缀的临时分支名避开跟仓库真实分支的冲突。
+   * 分支名用 `pr-<localId>/<head|base>`（localId = 每-PR 稳定主键）：与 PR 关联便于追溯，
+   * 又避开跟仓库真实分支的冲突；不带工具品牌前缀，不留固定可辨识特征。未提供 localId
+   * （包级直调）时回退到本次随机 nonce，保持每次不同。
    *
    * 为什么不用 `git worktree add`：worktree 的 `.git` 是个 file，内容是
    *   `gitdir: <bare-host-path>/worktrees/<name>`
@@ -339,7 +341,7 @@ export class RepoMirrorManager {
    * refspec 不拉它，否则 PR 源分支被删 / 强推后 checkout 会失败)。
    *
    * 返回 `{ path, headBranchName, targetBranchName?, cleanup }`：
-   *   - `headBranchName`：HEAD 当前在的分支名（恒为 `meebox/head`），调用方一般
+   *   - `headBranchName`：HEAD 当前在的分支名（`pr-<localId>/head`），调用方一般
    *     用不上但留作接口对称
    *   - `targetBranchName`：baseSha 传了才有，pr-agent `LOCAL__TARGET_BRANCH` 填它
    *   - `cleanup()`：清理临时目录
@@ -350,21 +352,26 @@ export class RepoMirrorManager {
     repo: RepoIdentity,
     headSha: string,
     baseSha?: string,
+    prLocalId?: string,
   ): Promise<{
     path: string;
     headBranchName: string;
     targetBranchName?: string;
     cleanup: () => Promise<void>;
   }> {
-    const HEAD_BRANCH = 'meebox/head';
-    const BASE_BRANCH = 'meebox/base';
-
     const mirrorPath = this.mirrorPath(repo);
     const wtRoot = path.join(this.opts.reposDir, repo.host, repo.projectKey, repo.repoSlug, 'wt');
     await fs.mkdir(wtRoot, { recursive: true });
     const nonce = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
     const wtPath = path.join(wtRoot, `${headSha.slice(0, 12)}-${nonce}`);
 
+    // 分支名与 PR 关联（localId = 每-PR 稳定主键）便于追溯，不带工具品牌前缀；无 localId
+    // （包级直调）时回退到本次随机 nonce。用 `<ns>/head`、`<ns>/base` 分层命名（贴合平台
+    // PR ref 惯例如 refs/pull/N/head）；不单独建裸 `<ns>` 分支，故无 git dir/file ref 冲突。
+    const branchNs = prLocalId ? `pr-${prLocalId}` : `pr-${nonce}`;
+    const HEAD_BRANCH = `${branchNs}/head`;
+    const BASE_BRANCH = `${branchNs}/base`;
+
     // --local + 默认 hardlinks：同盘 inode 共享，无 alternates 文件 (避免跨 mount 断链)
     // --no-checkout：先不落文件，等分支建好再 checkout
     await simpleGit(wtRoot).clone(mirrorPath, wtPath, ['--local', '--no-checkout']);
diff --git a/packages/repo-mirror/tests/repo-mirror-manager.test.ts b/packages/repo-mirror/tests/repo-mirror-manager.test.ts
index 8126ade0..554fab1c 100644
--- a/packages/repo-mirror/tests/repo-mirror-manager.test.ts
+++ b/packages/repo-mirror/tests/repo-mirror-manager.test.ts
@@ -414,12 +414,12 @@ describe('RepoMirrorManager diff/content', () => {
 });
 
 describe('RepoMirrorManager.materializeWorktree', () => {
-  it('从 bare mirror 派生 self-contained worktree, HEAD 在 meebox/head 命名分支上', async () => {
+  it('从 bare mirror 派生 self-contained worktree, HEAD 在 pr-<localId>/head 命名分支上', async () => {
     const mgr = makeManager();
     await mgr.syncMirror(repo);
     const headSha = (await simpleGit(upstreamPath).revparse(['HEAD'])).trim();
 
-    const wt = await mgr.materializeWorktree(repo, headSha);
+    const wt = await mgr.materializeWorktree(repo, headSha, undefined, 'pr01hash');
     try {
       // worktree 路径在 <reposDir>/<host>/<project>/<repo>/wt/ 下
       expect(wt.path.startsWith(path.join(reposDir, 'bb.example.com', 'FX', 'fx-help', 'wt'))).toBe(
@@ -431,13 +431,13 @@ describe('RepoMirrorManager.materializeWorktree', () => {
       // README.md (upstream 初始 commit 的文件) 应该被 checkout 到工作树
       const readme = await fs.readFile(path.join(wt.path, 'README.md'), 'utf8');
       expect(readme).toBe('hello');
-      // HEAD 必须在命名分支 meebox/head 上 (pr-agent 要求，不能 detached)
+      // HEAD 必须在命名分支 pr-<localId>/head 上 (pr-agent 要求，不能 detached)
       const headRef = (await simpleGit(wt.path).raw(['symbolic-ref', 'HEAD'])).trim();
-      expect(headRef).toBe('refs/heads/meebox/head');
-      expect(wt.headBranchName).toBe('meebox/head');
+      expect(headRef).toBe('refs/heads/pr-pr01hash/head');
+      expect(wt.headBranchName).toBe('pr-pr01hash/head');
       // 该分支应该指向 headSha
       const branchSha = (
-        await simpleGit(wt.path).revparse(['refs/heads/meebox/head'])
+        await simpleGit(wt.path).revparse(['refs/heads/pr-pr01hash/head'])
       ).trim();
       expect(branchSha).toBe(headSha);
       // 没传 baseSha → 没有 target branch
@@ -447,7 +447,7 @@ describe('RepoMirrorManager.materializeWorktree', () => {
     }
   });
 
-  it('baseSha 传入后建 meebox/base 分支，targetBranchName 返回该名字', async () => {
+  it('baseSha 传入后建 pr-<localId>/base 分支，targetBranchName 返回该名字', async () => {
     const mgr = makeManager();
     await mgr.syncMirror(repo);
     // upstream 加一个新 commit；用初始 commit 当 base，新 commit 当 head
@@ -459,16 +459,16 @@ describe('RepoMirrorManager.materializeWorktree', () => {
     const headSha = (await upstreamGit.revparse(['HEAD'])).trim();
     await mgr.syncMirror(repo); // fetch new ref into mirror
 
-    const wt = await mgr.materializeWorktree(repo, headSha, baseSha);
+    const wt = await mgr.materializeWorktree(repo, headSha, baseSha, 'pr01hash');
     try {
-      expect(wt.targetBranchName).toBe('meebox/base');
+      expect(wt.targetBranchName).toBe('pr-pr01hash/base');
       const baseBranchSha = (
-        await simpleGit(wt.path).revparse(['refs/heads/meebox/base'])
+        await simpleGit(wt.path).revparse(['refs/heads/pr-pr01hash/base'])
       ).trim();
       expect(baseBranchSha).toBe(baseSha);
-      // head 仍在 meebox/head
+      // head 仍在 pr-<localId>/head
       const headBranchSha = (
-        await simpleGit(wt.path).revparse(['refs/heads/meebox/head'])
+        await simpleGit(wt.path).revparse(['refs/heads/pr-pr01hash/head'])
       ).trim();
       expect(headBranchSha).toBe(headSha);
     } finally {
diff --git a/packages/shared/package.json b/packages/shared/package.json
index bd68cf72..67a90044 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -11,11 +11,13 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src --max-warnings=0"
+    "test": "vitest run",
+    "lint": "eslint src tests --max-warnings=0"
   },
   "nx": {
     "targets": {
       "typecheck": { "cache": true },
+      "test": { "cache": true },
       "lint": { "cache": true }
     }
   }
diff --git a/packages/shared/src/config.ts b/packages/shared/src/config.ts
index 7eeb1e26..2bb368e9 100644
--- a/packages/shared/src/config.ts
+++ b/packages/shared/src/config.ts
@@ -157,6 +157,20 @@ export const ProxySchema = z.object({
 });
 export type ProxyConfig = z.infer<typeof ProxySchema>;
 
+/**
+ * 本地 API 服务监听（见 docs/arch/04-integration/01-service-api.md）。默认关闭、零暴露面；开启即**强制**
+ * bearer token 鉴权（token 为空时由主进程在启用时自动生成）。`host` 默认仅 loopback（127.0.0.1），可设
+ * `0.0.0.0` 暴露到局域网——高风险、需安全警示。`port` 固定安全默认 18765（10000+，避开常见开发端口且低于
+ * 临时端口范围）。token 明文落盘（同既有凭据策略，经 SecretStore 抽象、绝不进日志）。
+ */
+export const ServiceSchema = z.object({
+  enabled: z.boolean().default(false),
+  host: z.string().default('127.0.0.1'),
+  port: z.number().int().min(1).max(65535).default(18765),
+  token: z.string().default(''),
+});
+export type ServiceConfig = z.infer<typeof ServiceSchema>;
+
 /**
  * LLM 上下文长度（token）：裁剪输入内容的全局上限，透传 pr-agent `CONFIG__MAX_MODEL_TOKENS` /
  * `CONFIG__CUSTOM_MODEL_MAX_TOKENS`。默认 128000（与现代主流模型上下文匹配）；**对本地 CLI 模式
@@ -279,10 +293,13 @@ export const ConfigSchema = z.object({
       check_enabled: z.boolean().default(true),
     })
     .default({}),
+  /** 本地 API 服务监听（默认关闭）。见上 {@link ServiceSchema}。 */
+  service: ServiceSchema.default({}),
   /**
    * 消息通知（见 docs/arch/03-gui/03-notifications.md）。enabled 为总开关；关闭后既不弹系统通知也不亮 dock 角标。
-   * new_pr / reply / mention 按事件类型分别控制系统通知（toast）是否弹出。macOS dock「待回应」计数角标无独立
-   * 开关——随总开关默认启用。系统通知受 OS 权限约束——用户在系统设置关闭后应用静默降级。
+   * 其余各项按事件类型分别控制系统通知（toast）是否弹出：new_pr / reply / mention 面向「待我评审」等场景；
+   * authored_* 面向「我创建的」PR（作者为本人）——新评论 / 被标记需修改 / 出现冲突。macOS dock「待回应」计数
+   * 角标无独立开关——随总开关默认启用。系统通知受 OS 权限约束——用户在系统设置关闭后应用静默降级。
    */
   notifications: z
     .object({
@@ -293,6 +310,12 @@ export const ConfigSchema = z.object({
       reply: z.boolean().default(true),
       /** 评论中被 @ 提及时弹系统通知 */
       mention: z.boolean().default(true),
+      /** 我创建的 PR 收到他人新评论时弹系统通知 */
+      authored_comment: z.boolean().default(true),
+      /** 我创建的 PR 被评审标记「需修改」时弹系统通知 */
+      authored_needs_work: z.boolean().default(true),
+      /** 我创建的 PR 出现合并冲突时弹系统通知 */
+      authored_conflict: z.boolean().default(true),
     })
     .default({}),
   /**
diff --git a/packages/shared/src/error-code.ts b/packages/shared/src/error-code.ts
index 52a5e9df..4496a9c9 100644
--- a/packages/shared/src/error-code.ts
+++ b/packages/shared/src/error-code.ts
@@ -4,7 +4,7 @@
  */
 
 /** 领域标签（两字母大写）。新增领域追加在末尾。 */
-export type ErrorDomain = 'AG' | 'UI' | 'CF' | 'NT' | 'PR';
+export type ErrorDomain = 'AG' | 'UI' | 'CF' | 'NT' | 'PR' | 'SV';
 
 /**
  * 错误码注册表（唯一真相源）：`E` + 两字母领域 + 四位数字。新增码在此登记，并在渲染层各 locale 补
@@ -45,6 +45,23 @@ export const ERROR_CODES = {
   PR_FORBIDDEN: 'EPR0006',
   /** 没有活动连接，无法按链接打开 PR。 */
   PR_NO_ACTIVE_CONNECTION: 'EPR0007',
+  /**
+   * 本地 API 服务（service listener）域错误码。**经 HTTP 返回给外部 CLI / 客户端**，不经渲染层 i18n
+   * （故暂不在 renderer locale 登记；如未来在 GUI 展示再补 `errors.<CODE>`，formatBackendError 已有兜底）。
+   * 见 docs/arch/04-integration/01-service-api.md。
+   */
+  /** 未分类服务错误（兜底）。 */
+  SV_UNCLASSIFIED: 'ESV0000',
+  /** 鉴权失败：缺失 / 不匹配 bearer token（→ HTTP 401）。 */
+  SV_UNAUTHORIZED: 'ESV0001',
+  /** 写操作不经本地 API 开放（→ HTTP 403）。 */
+  SV_WRITE_NOT_ALLOWED: 'ESV0002',
+  /** 路由 / 资源不存在（→ HTTP 404）。 */
+  SV_NOT_FOUND: 'ESV0003',
+  /** 请求体校验失败（→ HTTP 400）。 */
+  SV_BAD_REQUEST: 'ESV0004',
+  /** CLI 版本低于服务端可兼容下限（→ HTTP 426；meta.minVersion 最低要求、meta.clientVersion 实际版本）。 */
+  SV_CLIENT_TOO_OLD: 'ESV0005',
 } as const;
 
 /** 已登记的错误码字面量联合（抛错时只能用注册过的码，防笔误）。 */
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 91f4350e..794b0664 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -7,6 +7,7 @@ export * from './language.js';
 export * from './platform.js';
 export * from './poller-contract.js';
 export * from './pr-agent-status.js';
+export * from './pr-filter.js';
 export * from './sync-progress.js';
 export * from './theme.js';
 export * from './tool-registry.js';
diff --git a/packages/shared/src/poller-contract.ts b/packages/shared/src/poller-contract.ts
index 76806d18..3b66d8ea 100644
--- a/packages/shared/src/poller-contract.ts
+++ b/packages/shared/src/poller-contract.ts
@@ -255,6 +255,25 @@ export interface TokenUsage {
   turns?: number;
 }
 
+/** pr-agent run 触发来源：user（用户手动发起）/ agent（编排 / AutoPilot 派发）。 */
+export type ReviewRunOrigin = 'user' | 'agent';
+
+/**
+ * 单 commit 评审范围：把一次 run 的 diff 限定在某个 commit 自身的改动（`parent..sha`），
+ * 而非 PR 全量。由 Diff 视图的提交选择器发起，落盘到 ReviewRun 供结果卡展示范围徽标。
+ * 无父 commit（root）无法单 commit 定界，不提供该范围。
+ */
+export interface ReviewRunCommitScope {
+  /** 目标 commit 完整 SHA（worktree head）。 */
+  sha: string;
+  /** 目标 commit 首个父 commit SHA（worktree base；单 commit diff = parent..sha）。 */
+  parent: string;
+  /** 展示用短 SHA。 */
+  abbreviatedSha: string;
+  /** 展示用 commit 主题（首行 message）。 */
+  subject: string;
+}
+
 export interface ReviewRun {
   /** yyyymmdd-HHmmss-ms 时序 id，便于按文件名倒序列出 */
   id: string;
@@ -269,6 +288,17 @@ export interface ReviewRun {
   tool: ReviewRunTool;
   /** /ask 工具的问题内容；其他 tool 不填。UI 把它当用户发言渲染在 run 卡片之上 */
   question?: string;
+  /**
+   * 触发来源：user（用户在 ChatPane 直接发起的斜杠命令）/ agent（编排 / AutoPilot 派发的子 run）。
+   * ChatPane 据此为 user 来源的 run 在其卡片之上补一条命令回显气泡（对话习惯）；agent 子 run 不回显
+   * （其用户输入已由编排会话的用户消息承载，避免重复冒泡）。历史 run 无此字段（undefined），不回显。
+   */
+  origin?: ReviewRunOrigin;
+  /**
+   * 单 commit 评审范围：本次 run 限定在该 commit 自身改动（`parent..sha`）而非 PR 全量时填。
+   * 缺省 = PR 全量范围。结果卡据此展示范围徽标。
+   */
+  scope?: ReviewRunCommitScope;
   /** 探测时拿到的 pr-agent 版本（CLI 首行 / 嵌入式查出的 pr-agent 版本） */
   prAgentVersion: string;
   strategy: PrAgentStrategy;
@@ -401,12 +431,24 @@ export interface PollResult {
   errors: number;
 }
 
-/** 系统通知事件类型：新 PR / 被 @ / 被回复（与设置页三个开关一一对应）。 */
-export type PollNotificationKind = 'new_pr' | 'mention' | 'reply';
+/**
+ * 系统通知事件类型（与设置页开关一一对应）：
+ * - `new_pr` / `mention` / `reply`：面向「待我评审」等——新 PR / 被 @ / 被回复。
+ * - `authored_comment` / `authored_needs_work` / `authored_conflict`：面向「我创建的」PR（作者为本人）——
+ *   收到他人新评论 / 被评审标记需修改 / 出现合并冲突。
+ */
+export type PollNotificationKind =
+  | 'new_pr'
+  | 'mention'
+  | 'reply'
+  | 'authored_comment'
+  | 'authored_needs_work'
+  | 'authored_conflict';
 
 /**
  * Poll 本轮新发生的「值得提醒」事件，由 poller 经 onNotify 投影给主进程（用于弹系统通知）。仅在**已有基线**
- * （非首轮 / PR 此前已知）时产出，避免首启 / 批量涌入时通知风暴；mention/reply 仅当评论时间晚于历史游标才计。
+ * （非首轮 / PR 此前已知）时产出，避免首启 / 批量涌入时通知风暴；带游标的事件（mention/reply/authored_comment）
+ * 仅当评论时间晚于历史游标才计；authored_needs_work / authored_conflict 仅在对应状态发生新迁移时才产出。
  */
 export interface PollNotificationEvent {
   kind: PollNotificationKind;
@@ -420,13 +462,16 @@ export interface PollNotificationEvent {
   title: string;
   /** PR 所在仓库，用于通知正文展示「项目 / 仓库」 */
   repo: RepoRef;
-  /** 发起人：new_pr=PR 作者；mention/reply=触发本轮该类事件的最新一条评论作者。用于通知头像。 */
+  /**
+   * 发起人（通知头像）：new_pr=PR 作者；mention/reply/authored_comment=触发本轮该类事件的最新一条评论作者；
+   * authored_needs_work=新标记需修改的评审人；authored_conflict=PR 作者（无具体发起人）。
+   */
   actor: PlatformUser;
-  /** mention / reply：本轮新增条数；new_pr 省略 */
+  /** mention / reply / authored_comment：本轮新增条数；其余省略 */
   count?: number;
   /**
-   * mention / reply：触发事件的最新一条评论的定位信息（通知点击跳转用）。`anchor` 非空=inline 评论（可跳 diff 行），
-   * 为 null=summary 评论（打开「活动」对话标签）。new_pr 无此字段。
+   * 触发事件的最新一条评论的定位信息（通知点击跳转用）。`anchor` 非空=inline 评论（可跳 diff 行），
+   * 为 null=summary 评论（打开「活动」对话标签）。仅 mention / reply / authored_comment 带此字段。
    */
   comment?: { remoteId: string; anchor: PrCommentAnchor | null };
 }
diff --git a/packages/shared/src/pr-filter.ts b/packages/shared/src/pr-filter.ts
new file mode 100644
index 00000000..1074a7c9
--- /dev/null
+++ b/packages/shared/src/pr-filter.ts
@@ -0,0 +1,91 @@
+import type { LocalPrStatus, StoredPullRequest } from './poller-contract.js';
+import type { PrDiscoveryFilter } from './platform.js';
+
+/**
+ * PR 列表筛选与检索的**纯谓词**（单一真相源）。渲染层侧栏与本地 API 的 PR 列表端点共用同一套语义，
+ * 避免两处各写一份过滤逻辑而漂移。仅做无副作用的判定 / 过滤，不含 UI（计数、可见性、分组属各自表现层）。
+ *
+ * 二级筛选 `PrSecondaryFilter`：`'all'` 不限定；`LocalPrStatus`（本人评审决断 pending/approved/needs_work）
+ * 按 `localStatus` 匹配；`'conflict'` / `'mergeable'` 是跨 localStatus 横切的远端合并态筛选。
+ */
+export type PrSecondaryFilter = 'all' | LocalPrStatus | 'conflict' | 'mergeable';
+
+/** 二级筛选全集（与 {@link PrSecondaryFilter} 同步；本地 API 的分类标签据此列出）。 */
+export const PR_SECONDARY_FILTERS: readonly PrSecondaryFilter[] = [
+  'all',
+  'pending',
+  'approved',
+  'needs_work',
+  'conflict',
+  'mergeable',
+];
+
+/** 一级（平台发现分类）匹配：未指定一级 = 不限定；否则按 PR 携带的 discoveryFilters 命中判定。 */
+export function matchesDiscoveryFilter(
+  pr: StoredPullRequest,
+  primary?: PrDiscoveryFilter,
+): boolean {
+  return !primary || (pr.discoveryFilters?.includes(primary) ?? false);
+}
+
+/**
+ * 二级筛选匹配（状态 / 合并态）。`primary` 为当前一级发现分类（可空），用于分类相关的语义细化：
+ * 「我创建的」（`created`）下「待处理」= 需作者跟进 —— 除本人评审决断 pending 外，还并入存在合并冲突的
+ * PR（作者需解决冲突方能推进，即便评审已通过）。
+ */
+export function matchesSecondaryFilter(
+  pr: StoredPullRequest,
+  secondary: PrSecondaryFilter,
+  primary?: PrDiscoveryFilter,
+): boolean {
+  switch (secondary) {
+    case 'all':
+      return true;
+    case 'conflict':
+      return pr.hasConflict === true;
+    case 'mergeable':
+      return pr.mergeStatus?.canMerge === true;
+    case 'pending':
+      if (primary === 'created') return pr.localStatus === 'pending' || pr.hasConflict === true;
+      return pr.localStatus === 'pending';
+    default:
+      return pr.localStatus === secondary;
+  }
+}
+
+/** 检索匹配：空查询恒真；否则在 标题 / 仓库 / 作者 / 编号 拼成的串里做大小写无关子串匹配。 */
+export function matchesPrQuery(pr: StoredPullRequest, query: string): boolean {
+  const q = query.trim().toLowerCase();
+  if (!q) return true;
+  return [
+    pr.title,
+    pr.repo.projectKey,
+    pr.repo.repoSlug,
+    pr.author.displayName,
+    pr.author.name,
+    pr.remoteId,
+  ]
+    .join(' ')
+    .toLowerCase()
+    .includes(q);
+}
+
+/** 筛选条件（各项可省，省略即不限定）。 */
+export interface PrFilterCriteria {
+  primary?: PrDiscoveryFilter;
+  secondary?: PrSecondaryFilter;
+  query?: string;
+}
+
+/** 按 一级 + 二级 + 检索 顺序过滤 PR 列表。 */
+export function filterPullRequests(
+  prs: StoredPullRequest[],
+  criteria: PrFilterCriteria,
+): StoredPullRequest[] {
+  return prs.filter(
+    (p) =>
+      matchesDiscoveryFilter(p, criteria.primary) &&
+      matchesSecondaryFilter(p, criteria.secondary ?? 'all', criteria.primary) &&
+      matchesPrQuery(p, criteria.query ?? ''),
+  );
+}
diff --git a/packages/shared/tests/pr-filter.test.ts b/packages/shared/tests/pr-filter.test.ts
new file mode 100644
index 00000000..beadc579
--- /dev/null
+++ b/packages/shared/tests/pr-filter.test.ts
@@ -0,0 +1,199 @@
+import { describe, expect, it } from 'vitest';
+import type { StoredPullRequest } from '../src/poller-contract.js';
+import {
+  PR_SECONDARY_FILTERS,
+  filterPullRequests,
+  matchesDiscoveryFilter,
+  matchesPrQuery,
+  matchesSecondaryFilter,
+} from '../src/pr-filter.js';
+
+/** 最小 StoredPullRequest 构造：只填谓词用到的字段，其余以 double-cast 略过。 */
+function mkPr(over: Partial<StoredPullRequest>): StoredPullRequest {
+  return {
+    title: 'Fix login bug',
+    repo: { projectKey: 'PROJ', repoSlug: 'web-app' },
+    author: { displayName: 'Alice Zhang', name: 'alice' },
+    remoteId: '42',
+    localStatus: 'pending',
+    hasConflict: false,
+    mergeStatus: { canMerge: false, conflicted: false, vetoes: [] },
+    discoveryFilters: ['review-requested'],
+    ...over,
+  } as unknown as StoredPullRequest;
+}
+
+describe('matchesDiscoveryFilter', () => {
+  it('无一级 = 不限定，恒真', () => {
+    expect(matchesDiscoveryFilter(mkPr({ discoveryFilters: [] }), undefined)).toBe(true);
+  });
+  it('命中 discoveryFilters 为真', () => {
+    expect(
+      matchesDiscoveryFilter(mkPr({ discoveryFilters: ['review-requested', 'created'] }), 'created'),
+    ).toBe(true);
+  });
+  it('未命中为假', () => {
+    expect(matchesDiscoveryFilter(mkPr({ discoveryFilters: ['review-requested'] }), 'assigned')).toBe(
+      false,
+    );
+  });
+  it('PR 无 discoveryFilters 且指定了一级 → 假', () => {
+    expect(matchesDiscoveryFilter(mkPr({ discoveryFilters: undefined }), 'review-requested')).toBe(
+      false,
+    );
+  });
+});
+
+describe('matchesSecondaryFilter', () => {
+  it("'all' 恒真", () => {
+    expect(matchesSecondaryFilter(mkPr({ localStatus: 'needs_work' }), 'all')).toBe(true);
+  });
+  it('按 localStatus 匹配', () => {
+    expect(matchesSecondaryFilter(mkPr({ localStatus: 'approved' }), 'approved')).toBe(true);
+    expect(matchesSecondaryFilter(mkPr({ localStatus: 'pending' }), 'approved')).toBe(false);
+  });
+  it("'conflict' 看 hasConflict", () => {
+    expect(matchesSecondaryFilter(mkPr({ hasConflict: true }), 'conflict')).toBe(true);
+    expect(matchesSecondaryFilter(mkPr({ hasConflict: false }), 'conflict')).toBe(false);
+  });
+  it("'mergeable' 看 mergeStatus.canMerge", () => {
+    expect(
+      matchesSecondaryFilter(
+        mkPr({ mergeStatus: { canMerge: true, conflicted: false, vetoes: [] } }),
+        'mergeable',
+      ),
+    ).toBe(true);
+    expect(
+      matchesSecondaryFilter(
+        mkPr({ mergeStatus: { canMerge: false, conflicted: false, vetoes: [] } }),
+        'mergeable',
+      ),
+    ).toBe(false);
+  });
+  it("'pending' 默认按 localStatus，不含冲突", () => {
+    expect(matchesSecondaryFilter(mkPr({ localStatus: 'pending' }), 'pending')).toBe(true);
+    expect(
+      matchesSecondaryFilter(mkPr({ localStatus: 'approved', hasConflict: true }), 'pending'),
+    ).toBe(false);
+  });
+  it("'created' 分类下 'pending' 并入冲突 PR（作者需跟进）", () => {
+    // 评审已通过但存在冲突 → created 下计入待处理
+    expect(
+      matchesSecondaryFilter(
+        mkPr({ localStatus: 'approved', hasConflict: true }),
+        'pending',
+        'created',
+      ),
+    ).toBe(true);
+    // 无冲突且非 pending → 仍不计入
+    expect(
+      matchesSecondaryFilter(
+        mkPr({ localStatus: 'approved', hasConflict: false }),
+        'pending',
+        'created',
+      ),
+    ).toBe(false);
+    // localStatus pending 本就计入
+    expect(
+      matchesSecondaryFilter(
+        mkPr({ localStatus: 'pending', hasConflict: false }),
+        'pending',
+        'created',
+      ),
+    ).toBe(true);
+  });
+});
+
+describe('matchesPrQuery', () => {
+  const pr = mkPr({
+    title: 'Fix login bug',
+    repo: { projectKey: 'PROJ', repoSlug: 'web-app' },
+    author: { displayName: 'Alice Zhang', name: 'alice' } as StoredPullRequest['author'],
+    remoteId: '42',
+  });
+  it('空查询恒真', () => {
+    expect(matchesPrQuery(pr, '')).toBe(true);
+    expect(matchesPrQuery(pr, '   ')).toBe(true);
+  });
+  it('大小写无关匹配标题 / 仓库 / 作者 / 编号', () => {
+    expect(matchesPrQuery(pr, 'LOGIN')).toBe(true); // 标题
+    expect(matchesPrQuery(pr, 'web-app')).toBe(true); // repoSlug
+    expect(matchesPrQuery(pr, 'proj')).toBe(true); // projectKey
+    expect(matchesPrQuery(pr, 'alice')).toBe(true); // author.name
+    expect(matchesPrQuery(pr, 'Alice Zhang')).toBe(true); // author.displayName
+    expect(matchesPrQuery(pr, '42')).toBe(true); // remoteId
+  });
+  it('未命中为假', () => {
+    expect(matchesPrQuery(pr, 'nonexistent')).toBe(false);
+  });
+});
+
+describe('filterPullRequests', () => {
+  const prs = [
+    mkPr({
+      remoteId: '1',
+      title: 'alpha',
+      localStatus: 'pending',
+      discoveryFilters: ['review-requested'],
+    }),
+    mkPr({
+      remoteId: '2',
+      title: 'beta',
+      localStatus: 'approved',
+      discoveryFilters: ['created'],
+    }),
+    mkPr({
+      remoteId: '3',
+      title: 'gamma',
+      localStatus: 'approved',
+      discoveryFilters: ['review-requested'],
+      hasConflict: true,
+    }),
+  ];
+
+  it('空条件返回全部', () => {
+    expect(filterPullRequests(prs, {})).toHaveLength(3);
+  });
+  it('一级过滤', () => {
+    const out = filterPullRequests(prs, { primary: 'review-requested' });
+    expect(out.map((p) => p.remoteId)).toEqual(['1', '3']);
+  });
+  it('一级 + 二级 AND', () => {
+    const out = filterPullRequests(prs, { primary: 'review-requested', secondary: 'approved' });
+    expect(out.map((p) => p.remoteId)).toEqual(['3']);
+  });
+  it('二级 + 检索 AND', () => {
+    const out = filterPullRequests(prs, { secondary: 'approved', query: 'beta' });
+    expect(out.map((p) => p.remoteId)).toEqual(['2']);
+  });
+  it('conflict 横切筛选', () => {
+    expect(filterPullRequests(prs, { secondary: 'conflict' }).map((p) => p.remoteId)).toEqual(['3']);
+  });
+  it("'created' + 'pending' 并入冲突的已通过 PR", () => {
+    const createdPrs = [
+      mkPr({ remoteId: '10', localStatus: 'pending', discoveryFilters: ['created'] }),
+      mkPr({
+        remoteId: '11',
+        localStatus: 'approved',
+        hasConflict: true,
+        discoveryFilters: ['created'],
+      }),
+      mkPr({ remoteId: '12', localStatus: 'approved', discoveryFilters: ['created'] }),
+    ];
+    const out = filterPullRequests(createdPrs, { primary: 'created', secondary: 'pending' });
+    expect(out.map((p) => p.remoteId)).toEqual(['10', '11']);
+  });
+});
+
+describe('PR_SECONDARY_FILTERS', () => {
+  it('含全部二级筛选键', () => {
+    expect(PR_SECONDARY_FILTERS).toEqual([
+      'all',
+      'pending',
+      'approved',
+      'needs_work',
+      'conflict',
+      'mergeable',
+    ]);
+  });
+});
diff --git a/tools/cli/install.sh b/tools/cli/install.sh
new file mode 100755
index 00000000..e0add30b
--- /dev/null
+++ b/tools/cli/install.sh
@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+#
+# One-line installer for the meebox CLI on macOS / Linux.
+#
+#   curl -fsSL https://raw.githubusercontent.com/huhamhire/code-meeseeks/main/tools/cli/install.sh | bash
+#
+# Detects OS/arch, downloads the matching release archive from GitHub, verifies its
+# SHA-256, and installs the `meebox` binary onto PATH. SKILL.md is NOT installed — it is
+# embedded in the binary and printable via `meebox skill` (regenerate on demand if needed).
+#
+# Options (env vars or flags):
+#   MEEBOX_VERSION / --version <v>    install a specific release (e.g. v0.9.0); default: latest
+#   MEEBOX_BIN_DIR / --bin-dir <dir>  install target; default: /usr/local/bin if writable, else ~/.local/bin
+#
+# Windows is not covered by this script — download the .zip from the Releases page.
+set -euo pipefail
+
+REPO="huhamhire/code-meeseeks"
+BIN_NAME="meebox"
+
+VERSION="${MEEBOX_VERSION:-}"
+BIN_DIR="${MEEBOX_BIN_DIR:-}"
+
+err() { printf 'error: %s\n' "$*" >&2; exit 1; }
+info() { printf '%s\n' "$*"; }
+
+usage() {
+  # Print the header comment block (skip the shebang; stop at the first non-comment line).
+  awk 'NR==1 { next } /^#/ { sub(/^# ?/, ""); print; next } { exit }' "$0"
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --version) VERSION="${2:-}"; shift 2 ;;
+    --version=*) VERSION="${1#*=}"; shift ;;
+    --bin-dir) BIN_DIR="${2:-}"; shift 2 ;;
+    --bin-dir=*) BIN_DIR="${1#*=}"; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) err "unknown argument: $1 (see --help)" ;;
+  esac
+done
+
+need() { command -v "$1" >/dev/null 2>&1 || err "required tool not found: $1"; }
+need curl
+
+# --- detect OS / arch ---------------------------------------------------------
+os="$(uname -s)"
+case "$os" in
+  Linux) goos=linux ;;
+  Darwin) goos=darwin ;;
+  *) err "unsupported OS: $os (this installer supports Linux and macOS; on Windows download the .zip from Releases)" ;;
+esac
+
+arch="$(uname -m)"
+case "$arch" in
+  x86_64 | amd64) goarch=amd64 ;;
+  aarch64 | arm64) goarch=arm64 ;;
+  *) err "unsupported architecture: $arch" ;;
+esac
+
+# Only darwin/arm64 (Apple Silicon) is published; Linux ships amd64 + arm64.
+if [ "$goos" = darwin ] && [ "$goarch" != arm64 ]; then
+  err "no prebuilt macOS binary for $goarch — only Apple Silicon (arm64) is published"
+fi
+
+# macOS archives are .zip, Linux archives are .tar.gz (matches the release workflow).
+if [ "$goos" = linux ]; then ext="tar.gz"; else ext="zip"; fi
+if [ "$ext" = zip ]; then need unzip; else need tar; fi
+
+# --- resolve release tag ------------------------------------------------------
+if [ -z "$VERSION" ]; then
+  info "Resolving latest release..."
+  tag="$(curl -fsSL "https://api.github.com/repos/${REPO}/releases/latest" |
+    grep -o '"tag_name"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"\([^"]*\)"$/\1/')"
+  [ -n "$tag" ] || err "could not resolve the latest release tag"
+else
+  case "$VERSION" in v*) tag="$VERSION" ;; *) tag="v$VERSION" ;; esac
+fi
+version="${tag#v}"
+
+archive="${BIN_NAME}-cli-${version}-${goos}-${goarch}.${ext}"
+url="https://github.com/${REPO}/releases/download/${tag}/${archive}"
+
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+# --- download + verify --------------------------------------------------------
+info "Downloading ${archive} (${tag})..."
+curl -fSL --proto '=https' "$url" -o "$tmp/$archive" || err "download failed: $url"
+
+if curl -fsSL --proto '=https' "${url}.sha256" -o "$tmp/$archive.sha256" 2>/dev/null; then
+  info "Verifying checksum..."
+  want="$(awk '{print $1}' "$tmp/$archive.sha256")"
+  if command -v sha256sum >/dev/null 2>&1; then
+    got="$(sha256sum "$tmp/$archive" | awk '{print $1}')"
+  elif command -v shasum >/dev/null 2>&1; then
+    got="$(shasum -a 256 "$tmp/$archive" | awk '{print $1}')"
+  else
+    got=""
+    info "warning: no sha256 tool available; skipping verification"
+  fi
+  [ -z "$got" ] || [ "$want" = "$got" ] || err "checksum mismatch for $archive"
+else
+  info "warning: checksum file not found; skipping verification"
+fi
+
+# --- extract ------------------------------------------------------------------
+info "Extracting..."
+mkdir -p "$tmp/extract"
+if [ "$ext" = zip ]; then
+  unzip -q -o "$tmp/$archive" -d "$tmp/extract"
+else
+  tar -xzf "$tmp/$archive" -C "$tmp/extract"
+fi
+[ -f "$tmp/extract/$BIN_NAME" ] || err "binary '$BIN_NAME' not found in $archive"
+
+# --- install ------------------------------------------------------------------
+if [ -z "$BIN_DIR" ]; then
+  if [ -d /usr/local/bin ] && [ -w /usr/local/bin ]; then
+    BIN_DIR="/usr/local/bin"
+  else
+    BIN_DIR="$HOME/.local/bin"
+  fi
+fi
+mkdir -p "$BIN_DIR"
+install_path="$BIN_DIR/$BIN_NAME"
+mv -f "$tmp/extract/$BIN_NAME" "$install_path"
+chmod +x "$install_path"
+
+info "Installed ${BIN_NAME} ${version} to ${install_path}"
+case ":$PATH:" in
+  *":$BIN_DIR:"*) : ;;
+  *) info "note: ${BIN_DIR} is not on your PATH — add it, e.g.: export PATH=\"${BIN_DIR}:\$PATH\"" ;;
+esac
+info ""
+info "Next: ${BIN_NAME} login --token <token>    # then e.g. ${BIN_NAME} pr list"
+info "Tip:  ${BIN_NAME} skill                     # print the embedded agent usage doc"