dsh-github-flow 0.4.0 → 0.6.0

package/README.en.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <b>Give DeepSeek Harness Agents native hands and feet to operate GitHub, crafting an immersive collaboration cockpit for developers.</b><br>
-  Natively reuses host <code>gh</code> CLI login credentials to eliminate Personal Access Token (PAT) leaks; deeply bridges local Git workspaces with remote GitHub collaboration, equipped with <b>14 core domain Agent tools (85+ actions covering PR review/Issue tracking/Actions workflow & cache governance/clone-free file reads/branch ruleset policy diagnosis/Gist snippets/labels & global status dashboards/secrets & variables)</b>, <b>human slash commands</b>, <b>Web UI visual cockpits</b>, and <b>cross-platform one-click seamless upgrades</b>.
+  Natively reuses host <code>gh</code> CLI login credentials to eliminate Personal Access Token (PAT) leaks; deeply bridges local Git workspaces with remote GitHub collaboration, equipped with <b>18 core domain Agent tools (104 actions covering PR review/Issue tracking/Actions workflow & cache governance/clone-free file reads/branch ruleset policy diagnosis/Gist snippets/labels & global status dashboards/secrets & variables/agent tasks/discussions/projects v2/codespaces/runtime telemetry)</b>, <b>human slash commands</b>, <b>Web UI visual cockpits</b>, and <b>cross-platform one-click seamless upgrades</b>.
 </p>
 
 <p align="center">
@@ -73,7 +73,7 @@ dsh plugin --profile web add dsh-github-flow
 
 ## 🤖 Core Agent Tools: Equipping Agents with Native GitHub Powers
 
-Consolidates scattered GitHub endpoints into **14 core domain tools (85+ actions)**, featuring **Token Budget Protection (default 24KB intelligent truncation)**, **High-density Native Markdown Rendering (70%+ list output token reduction)** and **Zero-argument CWD auto-binding**.
+Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions)** with an official command coverage of **87% (104/120)**, featuring **Token Budget Protection (default 24KB intelligent truncation)**, **High-density Native Markdown Rendering (70%+ list output token reduction)**, **OAuth Scope self-healing guidance**, and **Zero-argument CWD auto-binding**.
 
 ### 1. `github_pr`: Pull Request Lifecycle & Automated Code Review
 > **Example Agent Prompts**:
@@ -205,7 +205,9 @@ Consolidates scattered GitHub endpoints into **14 core domain tools (85+ actions
   * `search`: Discover compliant Agent skills across open-source GitHub repositories;
   * `preview`: Preview `SKILL.md` rule instructions without installing;
   * `install`: Install skills locally (`scope: 'project'` or `'user'`; requires `confirm: true`);
-  * `list`: Inspect installed skills in the current environment.
+  * `list`: Inspect installed skills in the current environment;
+  * `publish`: 🆕 **Skill Compliance Validation & Publishing Loop**: Safe `--dry-run` inspection against agentskills.io specifications, `--fix` metadata stripping, and release publishing with required `tag` and `confirm: true`;
+  * `update`: 🆕 **Batch Inspection & Sync Updates**: Safe `--dry-run` check comparing local and remote tree SHAs, with `--all` batch synchronization.
 
 ---
 
@@ -216,11 +218,11 @@ Consolidates scattered GitHub endpoints into **14 core domain tools (85+ actions
 > - *"How do I debug 'authentication failed' errors from gh?"*
 
 * **Supported Actions**:
-  * `overview`: Complete toolbox navigation and summary table (14 core tools);
+  * `overview`: Complete toolbox navigation and summary table (18 core tools);
   * `mapping`: **Official gh Command ↔ Tool Action Mapping Table**, detailing exact tool calls and REST/GraphQL fallback routes;
   * `search_syntax`: Date ranges, qualifiers, and boolean query syntax;
   * `troubleshooting`: Self-healing recipes for authentication loss, timeouts, SOCKS5 proxy configs, and permissions;
-  * Domain guides: In-depth usage guides for `pr`, `issue`, `run`, `repo`, `release`, `secret`, `skill`, `label`, `ruleset`, `cache`, `gist`, and `status`;
+  * Domain guides: In-depth usage guides for `pr`, `issue`, `run`, `repo`, `release`, `secret`, `skill`, `label`, `ruleset`, `cache`, `gist`, `status`, `agent_task`, `discussion`, `project`, and `codespace`;
   * `gh_command`: Direct pass-through lookup of official gh manual entries (e.g. `gh_command: 'ruleset'`).
 
 ---
@@ -290,13 +292,78 @@ Consolidates scattered GitHub endpoints into **14 core domain tools (85+ actions
 
 ---
 
-### 14. `github_status`: Cross-Repository Todo & Activity Dashboard
+### 14. `github_status`: Cross-Repository Todo & Runtime Health Dashboard
 > **Example Agent Prompts**:
 > - *"What tasks and pull requests need my attention on GitHub today?"*
 > - *"Check recent @mentions and activity across all repositories I follow."*
+> - *"Audit the runtime health score and degradation rate report of our GitHub tools."*
 
 * **Supported Actions**:
-  * `view`: **Account-level global status cockpit**, aggregating Assigned Issues, Assigned PRs, Review Requests, Mentions, and Repository Activity across all subscribed repositories without needing repository context; supports `-o` org filtering and `-e` noise repository exclusion.
+  * `view`: **Account-level global status cockpit** (default), aggregating Assigned Issues, Assigned PRs, Review Requests, Mentions, and Repository Activity across all subscribed repositories without needing repository context; supports `-o` org filtering and `-e` noise repository exclusion;
+  * `health`: 🆕 **Toolchain Runtime Health & Degradation Audit Report**: Powered by Cordis `tools/result` event telemetry, audits total calls, success rates, comprehensive health score (0-100), API degradation rates, and actionable self-healing upgrade suggestions across all 18 tools.
+
+---
+
+### 15. `github_agent_task`: Cloud Coding Agent Session Governance
+> **Example Agent Prompts**:
+> - *"List all GitHub Copilot Coding Agent task sessions assigned under my account."*
+> - *"View task 'e2fa49d2' details and fetch its execution logs."*
+> - *"Dispatch a task to the cloud Agent: 'Refactor network layer with retry support', based on branch develop."*
+
+* **Supported Actions**:
+  * `list`: List agent tasks (supports `-L/--limit` and `-R/--repo`);
+  * `view`: View task session details and logs (supports `--log`, strictly requires `task_id` to prevent TTY hangs);
+  * `create`: Create and dispatch a cloud agent coding task (supports `-b/--base` and `-a/--custom-agent`).
+
+---
+
+### 16. `github_discussion`: Team Discussions & Open-Source RFC Loop
+> **Example Agent Prompts**:
+> - *"List open discussions in category 'Ideas' for this repository."*
+> - *"View discussion #101 body and comment thread."*
+> - *"Start a discussion under 'RFC': 'Proposal on telemetry observability'."*
+> - *"Post a reply comment to discussion #101."*
+
+* **Supported Actions**:
+  * `list`: Query discussions (supports `-c/--category`, `-s/--state`, `--labels`, and `-S/--search`);
+  * `view`: Read discussion body and replies (supports `--comments`, requires `discussion_number`);
+  * `create`: Start a discussion (requires `category`, `title`, and `body`);
+  * `edit`: Update discussion title or body;
+  * `comment`: Post a comment reply to an existing discussion.
+
+---
+
+### 17. `github_project`: Projects v2 Board & Item Planning
+> **Example Agent Prompts**:
+> - *"List all Projects v2 boards under my account."*
+> - *"View items in project board #1 with filter query 'is:open'."*
+> - *"Add Issue 'https://github.com/owner/repo/issues/10' to project board #1."*
+> - *"Create a draft issue item in project #1 titled 'Review unit test coverage'."*
+
+* **Supported Actions**:
+  * `list`: List user or organization projects (default `owner: '@me'`, natively handles `--format json`);
+  * `view`: Inspect project metadata, visibility, description, and README;
+  * `item-list`: Inspect board items (supports Projects query filter syntax `--query`, e.g., `is:open assignee:@me`);
+  * `item-add`: Associate existing Issue/PR URLs to a project board;
+  * `item-create`: Create draft issue items;
+  * `item-delete`: Remove items from board (guarded by required `confirm: true`);
+  * 🔑 **Scope Self-Healing**: Automatically renders a single-line self-healing command card (`gh auth refresh -s read:project`) when permissions are missing.
+
+---
+
+### 18. `github_codespace`: Cloud Remote Development Environment (MVP)
+> **Example Agent Prompts**:
+> - *"Check which cloud Codespace environments are currently running."*
+> - *"Inspect instance specs and idle timeout for 'fuzzy-spoon-69vj'."*
+> - *"Stop 'fuzzy-spoon-69vj' to avoid billable core-hour consumption."*
+> - *"Permanently delete an unused temporary Codespace."*
+
+* **Supported Actions**:
+  * `list`: List Codespaces under current user or organization;
+  * `view`: Inspect environment specs, DevContainer path, and status (requires `codespace` name);
+  * `stop`: Stop running instances to halt billing immediately;
+  * `delete`: Safely delete instances (requires `confirm: true`, passes `-f` for non-interactive execution);
+  * 🔑 **Scope Self-Healing**: Automatically renders a single-line self-healing command card (`gh auth refresh -h github.com -s codespace`) when missing required scopes.
 
 ---
 
@@ -311,7 +378,9 @@ Click the **Octocat icon** in DSH's left navigation bar to open the full-screen
 * **Account-Wide Overview**: Live view of all cloud repositories, default branches, and star counts;
 * **Local Workspace Matrix**: Automatically detects open projects and bridges local directories with remote repos;
 * **3D Issue Governance Matrix**: Categorizes issues into *"📥 User Reported"*, *"🎯 Assigned to Me"*, and *"✍️ Created by Me"* with responsive pill filters;
-* **Update Notification Banner**: Smoothly glides down when an update is available with one-click automated upgrade.
+* **Update Notification Banner**: Smoothly glides down when an update is available with one-click automated upgrade;
+* **🔀 PR Review Workbench**: Click any PR to review author, branch flow, CI/review status, Markdown description, comment timeline, and the changed-file list with high-fidelity unified diffs — all without leaving DSH (diffs are sliced per file in memory, so switching files is instant);
+* **📝 Issue Online Viewer**: Click any Issue to read the full discussion — body and comments rendered as Markdown, long content collapsed, GitHub-hidden (SPAM) comments explicitly flagged, with label chips, assignees, milestone, sub-issue progress, and linked PRs.
 
 <p align="center">
   <img src="./docs/images/1.png" alt="GitHub Global Cockpit" width="100%" />
@@ -335,8 +404,8 @@ Located in the right drawer of every chat workspace, seamlessly bridging your lo
     * Latest Release badge (`🏷️ v0.4.0`) anchored in the top right with hover details and direct release link;
     * **Commit Detail Modal**: Click any commit row to open a clean modal dialog centered within the right sidebar, featuring smooth vertical scrolling, full 40-char SHA, author email, date, multi-line commit message body, and file diff stat table (`--stat`), pure local 0ms instant display;
   * **Uncommitted Changes (`📁 Uncommitted (N)`)**: Full-width list of uncommitted files with color-coded status codes (`??` untracked, `M` modified, `D` deleted, `R` renamed) and change counts;
-  * **Pull Requests (`🔀 PR (N)`)**: Open PR inspection with 3-state CI check rollup (`✅ CI Passed` / `❌ CI Failed` / `⏳ CI Pending`), merge conflict detection, review decisions (`✔ Approved` / `✋ Changes Requested` / `👀 Review Required`), Draft pills, and humanized relative timestamps;
-  * **Workspace Issues (`📋 Issues (N)`)**: Direct issue task review with assignees, labels, and category pills;
+  * **Pull Requests (`🔀 PR (N)`)**: Shows **all** PRs (merged/closed included, default "All"), with status pills `All / 🟢 Open / 🟣 Merged / ⚪ Closed` showing per-state counts; 3-state CI rollup (`✅ CI Passed` / `❌ CI Failed` / `⏳ CI Pending`), merge conflict detection, review decisions (`✔ Approved` / `✋ Changes Requested` / `👀 Review Required`), Draft pills, and humanized timestamps; **click a card to open the in-app PR review workbench**, while `GitHub ↗` still jumps to the browser;
+  * **Workspace Issues (`📋 Issues (N)`)**: Shows **all** issues (closed included, default "All"), with status pills `All / 🟢 Open / ⚪ Closed`; **click a card to open the in-app Issue viewer** (Markdown body / comment timeline / labels & milestone, Esc to close), while `GitHub ↗` still jumps to the browser;
   * **Actions Pipeline (`⚡ Actions (N)`)**: Real-time CI workflow status tracking with trigger event badges (`push`/`schedule`/`manual`/`PR`), relative time, and self-healing diagnostic notes for failed runs (embedding `run_id` for Agent one-click log inspection);
 * **⚙️ Full Settings Access**: Dedicated settings button reusing the same settings modal as the cockpit (all four sections: Sync / Proxy / Update Source / About) — no need to switch back to the main page.
 
@@ -344,7 +413,17 @@ Located in the right drawer of every chat workspace, seamlessly bridging your lo
   <img src="./docs/images/2.png" alt="Session Right Sidebar Panel" width="100%" />
 </p>
 
-### 3. Settings Center (Settings Modal)
+### 3. Help & Playbook Modal
+Click **`[📖 Help]`** in the top right of the Cockpit (or the ❓ button in the right sidebar) to open the 920px immersive manual; press Esc or click the backdrop to close. Five sections:
+* **🚀 3-Minute Quickstart**: login check → workspace binding → first Agent instruction, plus a capability overview (18 tools / 103 business actions / 2 workbenches);
+* **🤖 Agent Prompt Playbook**: 7 high-frequency scenarios (open a PR, CI triage, daily standup, diff review, screenshot triage, bulk label governance, RFC discussion), each with one-click prompt copy;
+* **🖥️ UI Walkthrough**: per-tab documentation for the 4-tab Cockpit and the 5-tab right sidebar, plus shared modal interaction habits;
+* **🧰 18-Tool Reference**: all tools and actions grouped into daily development / delivery & config / ecosystem & collaboration / escape hatches, with a `/gh` command cheat sheet;
+* **🔑 Troubleshooting**: login, missing scopes, the 24h supply-chain protection window, proxy flapping, empty lists, and why a DSH restart is needed.
+
+> The same knowledge is exposed to Agents via the `github_help` tool — both sides are asserted against the source tree by phase33, so docs drifting from code fails the test suite.
+
+### 4. Settings Center (Settings Modal)
 Click **`[⚙️ Settings]`** in the top right of the Cockpit (or the ⚙️ button in the right sidebar) to open the sectioned settings modal:
 
 **🔄 Data Sync Section** — tune data fetching rhythm and perception sensitivity:
@@ -426,7 +505,7 @@ Initial Mount (0ms) ──────────> Instantly render local persi
 
 Enter in any DSH chat window:
 
-* `/gh status`: Diagnostics for GitHub CLI auth status, scopes, active workspace repository, and plugin version;
+* `/gh status`: Diagnostics for GitHub CLI auth status, scopes, active workspace repository, plugin version, and **runtime toolchain telemetry (health score & degradation rates)**;
 * `/gh upgrade`: Check the latest npm release and output platform-tailored upgrade instructions (macOS / Windows / Linux);
 * `/gh help`: View help documentation and example Agent dialogue recipes.
 

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   <b>让 DeepSeek Harness Agent 拥有操作 GitHub 的原生手和脚，为人机协作打造沉浸式 GitHub 工作台。</b><br>
-  原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>14 大领域 Agent 核心工具（85+ action，覆盖 PR 审查/Issue 任务/Actions 工作流与构建缓存治理/免 clone 读文件/分支规则集策略排障/代码片段 Gist/标签与全局待办大盘/密钥与变量管理）</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
+  原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>18 大领域 Agent 核心工具（104 个 action，覆盖 PR 审查/Issue 任务/Actions 工作流与构建缓存治理/免 clone 读文件/分支规则集策略排障/代码片段 Gist/标签与全局待办大盘/密钥与变量管理/智能体任务会话/社区 Discussions 讨论/Projects v2 看板/云端 Codespaces/运行时遥测与自愈健康度）</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
 </p>
 
 <p align="center">
@@ -73,7 +73,7 @@ dsh plugin --profile web add dsh-github-flow
 
 ## 🤖 核心工具集 (Agent Tools)：给 Agent 装上 GitHub 的手和脚
 
-本插件精选聚合为 **14 大领域核心工具（85+ action）**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）** 与 **零参数 CWD 智能绑定**。
+本插件精选聚合为 **18 大领域核心工具（104 个 action）**，官方命令语义化覆盖率高达 **87%（104/120）**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）**、**OAuth Scope 缺失单行自愈引导** 与 **零参数 CWD 智能绑定**。
 
 ### 1. `github_pr`：PR 全生命周期管理与自动化代码审查
 > **典型对话指令**：
@@ -121,7 +121,7 @@ dsh plugin --profile web add dsh-github-flow
   * `pin` / `unpin`：🆕 仓库 Issue 置顶状态管理；
   * `lock` / `unlock`：🆕 锁定讨论区，支持 4 种官方合法理由（`off_topic` / `resolved` / `spam` / `too_heated`）；
   * `status`：🆕 检索指派给当前登录用户的待办议题全景面板；
-  * `view_images`：🆕 下载 Issue 报障截图（正文+评论全量识别并转为本地图片块，Agent 直接"看"截图）；
+  * `view_images`：🆕 下载 Issue 报障截图（正文+评论全量识别并转为本地图片块，Agent 直接"看"截图）；落地目录 `~/.dsh/data/dsh-github-flow/images/`（内容寻址去重），**超 15MB 时按 mtime 自动 LRU 淘汰至 10MB 低水位**，并保护当前批次已写入的文件；测试可用 `DSH_IMAGE_DIR` 重定向该目录；
   * `attach_images`（参数）：🆕 支持本地文件/截图直接作为附件随 Issue 发布（单批上限 50 个文件，需 gh ≥ 2.99）。
 
 ---
@@ -205,7 +205,9 @@ dsh plugin --profile web add dsh-github-flow
   * `search`：跨 GitHub 开源仓库检索符合规范的 Agent Skills；
   * `preview`：免安装直接在线预览指定 Skill 的 `SKILL.md` 规则与行为指令；
   * `install`：一键安装指定 Skill 至本地环境（支持 `scope: 'project'` 或 `'user'`，需 `confirm: true`）；
-  * `list`：查看当前环境已安装的 Skills 清单。
+  * `list`：查看当前环境已安装的 Skills 清单；
+  * `publish`：🆕 **Agent 技能自检与发布闭环**：默认 `--dry-run` 模式进行 agentskills.io 规范体检，支持 `--fix` 自动剔除安装残留元数据，正式发版强制要求指定版本 `tag` 并附带 `confirm: true` 自动创建 GitHub Release；
+  * `update`：🆕 **批量检查与同步更新**：默认 `--dry-run` 只读比对本地与远端 SHA 差异，支持 `--all` 批量同步更新已安装技能。
 
 ---
 
@@ -216,11 +218,11 @@ dsh plugin --profile web add dsh-github-flow
 > - *"调用 gh 命令报错 'authentication failed'，该怎么排查？"*
 
 * **支持操作 (`topic` / `gh_command`)**：
-  * `overview`：输出全景工具箱导航与核心职责速查（14 大工具矩阵全景）；
+  * `overview`：输出全景工具箱导航与核心职责速查（18 大工具矩阵全景）；
   * `mapping`：**官方命令映射总表**，精准指示任意 `gh <command>` 对应哪个插件工具，以及未覆盖域对应的 GitHub REST/GraphQL 端点；
   * `search_syntax`：日期区间、状态筛选与高级布尔搜索语法指南；
   * `troubleshooting`：常见错误自愈配方（认证失效、网络超时、SOCKS5 代理配置、权限不足等）；
-  * 领域速查：`pr` / `issue` / `run` / `repo` / `release` / `secret` / `skill` / `label` / `ruleset` / `cache` / `gist` / `status` 专项高阶用法；
+  * 领域速查：`pr` / `issue` / `run` / `repo` / `release` / `secret` / `skill` / `label` / `ruleset` / `cache` / `gist` / `status` / `agent_task` / `discussion` / `project` / `codespace` 专项高阶用法；
   * `gh_command`：直接透传查询官方原生手册（如 `gh_command: 'ruleset'`）。
 
 ---
@@ -290,13 +292,78 @@ dsh plugin --profile web add dsh-github-flow
 
 ---
 
-### 14. `github_status`：跨仓库待办与动态全局大盘
+### 14. `github_status`：跨仓库待办与运行时健康度大盘
 > **典型对话指令**：
 > - *"帮我看看今天在 GitHub 上有哪些需要我处理的事情？"*
 > - *"查看当前账号在所有订阅仓库中的最新动态与 @提及"*
+> - *"查看当前工具链的运行健康度与 API 降级率报表"*
 
 * **支持操作 (`action`)**：
-  * `view`：**账号维度跨仓一站式聚合大盘**，汇总展示「指派给我的 Issue」、「指派给我的 PR」、「等待我评审的 PR (Review Requests)」、「提及我的消息 (Mentions)」以及「订阅仓库近期动态 (Repository Activity)」，无需绑定单仓即可一览全局工作台；支持 `-o` 组织过滤与 `-e` 排除噪音仓库。
+  * `view`：**账号维度跨仓一站式聚合大盘**（默认），汇总展示「指派给我的 Issue」、「指派给我的 PR」、「等待我评审的 PR (Review Requests)」、「提及我的消息 (Mentions)」以及「订阅仓库近期动态 (Repository Activity)」，无需绑定单仓即可一览全局工作台；支持 `-o` 组织过滤与 `-e` 排除噪音仓库；
+  * `health`：🆕 **工具链运行时健康度与降级率审计报表**：基于 Cordis `tools/result` 事件切面，实时审计全插件 18 大核心工具的调用总量、成功率、综合健康分（0~100 分）、API 降级率与智能自愈建议。
+
+---
+
+### 15. `github_agent_task`：云端编码智能体任务会话治理
+> **典型对话指令**：
+> - *"查阅我名下所有的 GitHub Copilot 智能体任务会话列表"*
+> - *"检视任务 'e2fa49d2' 的执行状态，并抓取详细会话日志"*
+> - *"向云端 Agent 发起新任务：'重构网络通信模块以支持自动重试'，基于 develop 分支"*
+
+* **支持操作 (`action`)**：
+  * `list`：列出当前用户关联的智能体任务（支持 `-L/--limit` 与 `-R/--repo`）；
+  * `view`：查看任务详情与会话执行日志（支持 `--log`，强制校验 `task_id` 防交互挂起）；
+  * `create`：向云端 Agent 派发新编码/重构任务（支持 `-b/--base` 指定基准分支，`-a/--custom-agent` 指定仓库智能体定义）。
+
+---
+
+### 16. `github_discussion`：团队技术研讨与开源社区 RFC 闭环
+> **典型对话指令**：
+> - *"查看当前仓库分类为 'Ideas' 的开放讨论列表"*
+> - *"查看讨论 #101 的正文内容与回复楼层"*
+> - *"在 'RFC' 分类下发起新讨论：'关于接入自动化遥测系统的提案'"*
+> - *"向讨论 #101 发表回复评论"*
+
+* **支持操作 (`action`)**：
+  * `list`：查阅 Discussions 列表（支持 `-c/--category`、`-s/--state`、`--labels` 与 `-S/--search` 过滤）；
+  * `view`：查看讨论正文与多楼层评论（支持 `--comments`，强制校验 `discussion_number`）；
+  * `create`：发起新讨论（`category`、`title`、`body` 三项必填，缺少给出友好指引）；
+  * `edit`：编辑现有讨论的标题或正文；
+  * `comment`：向指定讨论追加发表评论回复。
+
+---
+
+### 17. `github_project`：Projects v2 项目看板与任务规划
+> **典型对话指令**：
+> - *"列出我名下的所有 Projects v2 项目看板"*
+> - *"查看项目 #1 看板中的所有任务条目，筛选 open 状态"*
+> - *"将 Issue 'https://github.com/owner/repo/issues/10' 添加到项目 #1 看板中"*
+> - *"在项目 #1 看板中创建一个草稿条目：'完成单元测试覆盖'"*
+
+* **支持操作 (`action`)**：
+  * `list`：查看用户或组织的项目列表（默认 `owner: '@me'`，底层自动适配 `--format json` 勘误）；
+  * `view`：查看项目元数据、可见性、描述与 README；
+  * `item-list`：查看看板条目（支持 Projects 过滤查询语法 `--query`，如 `is:open assignee:@me`）；
+  * `item-add`：关联已有 Issue/PR URL 进看板；
+  * `item-create`：在项目中创建草稿条目（Draft Issue）；
+  * `item-delete`：从看板移除条目（强制 `confirm: true` 拦截）；
+  * 🔑 **权限自愈**：检测到缺少 `read:project` 权限时自动输出单行自愈授权卡片（`gh auth refresh -s read:project`）。
+
+---
+
+### 18. `github_codespace`：云端远程开发环境管控 (MVP)
+> **典型对话指令**：
+> - *"查看我当前有哪些运行中的 Codespace 云端开发机？"*
+> - *"检视实例 'fuzzy-spoon-69vj' 的机器规格与空闲停机策略"*
+> - *"把开发机 'fuzzy-spoon-69vj' 关机停止运行，防止扣除核时费用"*
+> - *"销毁已经用完的临时 Codespace 实例"*
+
+* **支持操作 (`action`)**：
+  * `list`：列出当前用户或组织名下的 Codespace 环境（展示状态、机器规格与上次使用时间）；
+  * `view`：检视环境详细配置与 DevContainer 路径（强制校验 `codespace` 名称防交互挂起）；
+  * `stop`：发送停机指令，立即停止计算资源计费；
+  * `delete`：安全销毁实例（物理销毁不可逆，强制 `confirm: true` 拦截，底层传 `-f` 保证无交互幂等删除）；
+  * 🔑 **权限自愈**：检测到缺少 `codespace` 权限时自动输出单行自愈授权卡片（`gh auth refresh -h github.com -s codespace`）。
 
 ---
 
@@ -310,6 +377,8 @@ dsh plugin --profile web add dsh-github-flow
 * **账号全景概览**：实时透视名下所有 GitHub 仓库、默认分支与 Star 状态；
 * **本地工作区联动矩阵**：自动探测本机所有打开的项目，显示当前工作区与远程 GitHub 仓库的关联状态；
 * **三维待办 Issue 矩阵**：智能划分「📥 用户提单（反馈到我名下仓库）」、「🎯 指派待办（分配给我）」与「✍️ 我发起的」，支持一键药丸过滤；
+* **🔀 PR 在线审阅工作台**：点击任意 PR，无需离开 DSH 即可查看作者与分支流向、CI/审查状态、Markdown 描述、评论时间线，以及变动文件列表与高保真 Unified Diff 对比（按文件内存切片，切换文件 0ms）；
+* **📝 Issue 在线查看弹窗**：点击任意 Issue 直接查看完整讨论——正文与评论均为 Markdown 渲染、长内容自动折叠、被 GitHub 折叠的垃圾评论显式标注、标签色块/指派人/里程碑/子议题进度/关联 PR 一目了然，评论时间线按时间顺序完整呈现；
 * **升级提示横幅**：检测到新版本时在顶部优雅滑出，提供一键自动升级与更新日志直达。
 
 <p align="center">
@@ -334,8 +403,8 @@ dsh plugin --profile web add dsh-github-flow
     * 右上角锚定最新发布 Release 徽章（`🏷️ v0.4.0`），悬停查看发布时间与预发布标示，点击直达；
     * **提交详情模态弹窗**：点击任意提交记录行，在右侧栏内局部居中弹出，内置上下滑动区域，完整展示 40 位 SHA、提交者姓名邮箱、日期、多行详细正文说明与文件变更统计（`--stat`），纯本地 0ms 秒开，支持按 `Esc` 或点击遮罩随时关闭；
   * **未提交清单 (`📁 未提交 (N)`)**：展示工作区未提交的文件清单，状态码色彩区分（`??` 新增、`M` 修改、`D` 删除、`R` 重命名）与变更总数；
-  * **拉取请求 (`🔀 PR (N)`)**：展示当前开放 PR，带有三态 CI 门禁（`✅ CI 通过` / `❌ CI 失败` / `⏳ CI 运行中`）、冲突检测、审核判定（`✔ 已批准` / `✋ 需修改` / `👀 待审查`）、Draft 草稿标示与人性化相对时间；
-  * **仓库议题 (`📋 Issues (N)`)**：直接在侧边栏审查待办任务，支持指派者、标签与多维状态药丸；
+  * **拉取请求 (`🔀 PR (N)`)**：展示**全部** PR（含已合并/已关闭，默认「全部」），顶部状态胶囊 `全部 / 🟢 Open / 🟣 Merged / ⚪ Closed` 一键筛选并显示各档计数；带三态 CI 门禁（`✅ CI 通过` / `❌ CI 失败` / `⏳ CI 运行中`）、冲突检测、审核判定（`✔ 已批准` / `✋ 需修改` / `👀 待审查`）、Draft 草稿标示与人性化相对时间；**点击卡片在线唤起 PR 审阅工作台（描述 / 评论 / 文件 Diff）**，右侧 `GitHub ↗` 保留浏览器直达；
+  * **仓库议题 (`📋 Issues (N)`)**：展示**全部** Issue（含已关闭，默认「全部」），顶部状态胶囊 `全部 / 🟢 Open / ⚪ Closed` 一键筛选并显示各档计数；支持指派者、标签与多维状态药丸；**点击卡片在线查看 Issue 详情（Markdown 正文 / 评论时间线 / 标签与里程碑，Esc 关闭）**，右侧 `GitHub ↗` 保留浏览器直达；
   * **构建流水线 (`⚡ Actions (N)`)**：实时关注工作流 CI 状态，展示触发方式（`push`/`定时`/`手动`/`PR`）、相对时间与失败构建的 Agent 自愈诊断指引（嵌入 run_id）；
 * **⚙️ 完整设置入口**：右侧栏提供设置按钮，与主页复用同一设置弹窗（数据同步 / 网络代理 / 更新设置 / 关于 四分区完整可用），无需切回主页调整。
 
@@ -343,7 +412,17 @@ dsh plugin --profile web add dsh-github-flow
   <img src="./docs/images/2.png" alt="右侧栏工作区面板" width="100%" />
 </p>
 
-### 3. 设置中心 (Settings Modal)
+### 3. 使用指南大窗口 (Help & Playbook)
+点击驾驶舱右上角 **`[📖 使用指南]`**（或右侧栏的 ❓ 按钮）打开 920px 宽屏沉浸式手册，按 Esc 或点遮罩即可关闭。共 5 个分类：
+* **🚀 3分钟极速上手**：登录确认 → 绑定仓库 → 向 Agent 下指令的三步闭环，附能力总览（18 工具 / 103 业务动作 / 2 套工作台）；
+* **🤖 Agent 提示词实战**：7 大高频场景（建 PR、CI 排障、待办盘点、Diff 审查、看图定位、批量标签治理、RFC 研讨），每条配「📋 一键复制 Prompt」；
+* **🖥️ 两大界面操作图解**：主面板 4 标签与右侧栏 5 Tab 的逐项说明，以及两个弹窗的通用操作习惯；
+* **🧰 18 大工具速查**：按「日常研发 / 交付配置 / 生态协作 / 兜底元能力」四组列出全部工具与动作，附 `/gh` 指令速查；
+* **🔑 常见自愈排错**：登录、权限 Scope、24h 安全保护期、代理抖动、列表为空、为何需重启 DSH 共 6 条。
+
+> 同一套知识也通过 `github_help` 工具提供给 Agent——两侧口径由 phase33 测试强制对账，代码演进而文档没跟上会直接测试失败。
+
+### 4. 设置中心 (Settings Modal)
 点击全景驾驶舱右上角 **`[⚙️ 设置]`**（或右侧栏的 ⚙️ 按钮）打开分区式设置弹窗，左侧分区导航、右侧内容独立滚动（窄屏自动折叠为横向页签）：
 
 **🔄 数据同步分区**——调优数据拉取节奏与感知灵敏度：
@@ -429,7 +508,7 @@ dsh plugin --profile web add dsh-github-flow
 
 在 DSH 任意聊天窗口输入：
 
-* `/gh status`：一键诊断当前 GitHub CLI 账号认证状态、作用域、当前工作区关联仓库及插件版本；
+* `/gh status`：一键诊断当前 GitHub CLI 账号认证状态、作用域、当前工作区关联仓库、插件版本与**工具链运行时可观测性（健康分与 API 降级率）**；
 * `/gh upgrade`：主动检测 npm 最新版本，自适应输出当前操作系统（macOS / Windows / Linux）的最佳升级指引；
 * `/gh help`：查看帮助说明与 Agent 典型对话范例。
 

package/docs/UPGRADE-NOTES.md

@@ -10,8 +10,8 @@
 
 | # | 文件 | 位置 | 当前值 | 说明 |
 |---|---|---|---|---|
-| 1 | [package.json](../package.json) | 第 3 行 `"version": "0.4.0"` | `0.4.0` | npm 发布版本、CI 取版来源 |
-| 2 | [src/version.ts](../src/version.ts) | 第 9 行 `CURRENT_PLUGIN_VERSION = '0.4.0'` | `'0.4.0'` | 运行时版本比较基准（假横幅的教训来源） |
+| 1 | [package.json](../package.json) | 第 3 行 `"version": "0.6.0"` | `0.6.0` | npm 发布版本、CI 取版来源 |
+| 2 | [src/version.ts](../src/version.ts) | 第 9 行 `CURRENT_PLUGIN_VERSION = '0.6.0'` | `'0.6.0'` | 运行时版本比较基准（假横幅的教训来源） |
 
 **两处必须同值**。`pnpm run build` 会硬校验（[scripts/build.mjs](../scripts/build.mjs) 的
 `assertVersionConsistency`），不一致直接构建失败——但不要依赖拦截，发版前手动核对。
@@ -41,31 +41,28 @@
 | # | 机制 | 说明 |
 |---|---|---|
 | 9 | CI 取版（.github/workflows/npm-publish.yml:62） | `VERSION=$(node -p "require('./package.json').version")`——从 package.json 读，无硬编码 |
-| 10 | Git tag | `git tag v0.4.0` 手动打，值必须 = package.json 版本（tag 与 package.json 不一致时：CI 发布的 npm 版本以 package.json 为准，GitHub Release 标题以 tag 为准，出现两者错位） |
+| 10 | Git tag | `git tag v0.6.0` 手动打，值必须 = package.json 版本（tag 与 package.json 不一致时：CI 发布的 npm 版本以 package.json 为准，GitHub Release 标题以 tag 为准，出现两者错位） |
 
 ## 五、发版完整流程（含版本修改）
 
 ```powershell
 # 1. 改版本（两处同值）
-#    package.json  → "version": "0.4.0"
-#    src/version.ts → CURRENT_PLUGIN_VERSION = '0.4.0'
+#    package.json  → "version": "0.6.0"
+#    src/version.ts → CURRENT_PLUGIN_VERSION = '0.6.0'
 
 # 2. 文档已用占位符（npm-publish-guide 示例、README 安装命令），发版无需改文档版本号
 
 # 3. 构建（版本一致性校验在此拦截漏改）+ 全量测试
 pnpm run build
-pnpm test    # 16 阶段全绿
+pnpm test    # 全量测试全绿
 
 # 4. 本机 e2e（必须先重启 DSH 桌面进程——Node 模块缓存，软链重建不注入运行中进程）
-#    重启后验证：GET /api/github/check-update 的 currentVersion = 0.4.0
+#    重启后验证：GET /api/github/check-update 的 currentVersion = 0.6.0
 
 # 5. 提交 + 打 tag + 推送（tag 值 = package.json 版本）
 git add -A
-git commit -m "chore(release): v0.4.0"
-git tag v0.4.0
-git push origin master --tags
-#    CI（npm-publish.yml）自动：构建→发布 npm→创建 GitHub Release
-git tag v0.3.0
+git commit -m "chore(release): v0.6.0"
+git tag v0.6.0
 git push origin master --tags
 #    CI（npm-publish.yml）自动：构建→发布 npm→创建 GitHub Release
 

package/docs/architecture.md

@@ -35,7 +35,7 @@
 │            │                       │                        │               │
 │            ▼                       ▼                        ▼               │
 │  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────────┐  │
-│  │  14 大 Agent 工具 │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
+│  │  18 大 Agent 工具 │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
 │  │  (defineTool DSL)│    │  /gh status      │    │ (Effect Disposer 清理)│  │
 │  │  - pr (+attach)  │    │  /gh upgrade     │    │ - /api/github/overview│  │
 │  │  - issue (+attach│    │  /gh help        │    │ - /api/github/action  │  │
@@ -44,25 +44,37 @@
 │  │  - api (逃生门)  │  (workflow_enable/disable │  │ - /branch-switch      │  │
 │  │  - release       │   启停·list/view·download) │ - /api/github/git-    │  │
 │  │  - secret & var  │                            │   watch (定向监听)    │  │
-│  │  - skill         │  (search 三域=issues/prs/ │ - /check-update (并行)│  │
+│  │  - skill (+pub/up│  (search 三域=issues/prs/ │ - /check-update (并行)│  │
 │  │  - label (CRUD/cl│   commits; read_file/dir)  │ - /upgrade (一键自动) │  │
 │  │  - ruleset(check)│                            │ - /update-settings    │  │
 │  │  - cache (治理)  │                            │ - /proxy (全局代理)   │  │
 │  │  - gist (分享)   │                            │ - /auth (轻量探针)    │  │
-│  │  - status (大盘) │                            └──────────┬────────────┘  │
-│  │  - help (元指南) │                                       │               │
-│  └────────┬─────────┘                                       ▼               │
-│           │                                      ┌───────────────────────┐  │
-│           │                                      │ git-watcher (独立服务)│  │
-│           ▼                                      │ - .git/HEAD & index   │  │
-│  ┌──────────────────────────────────┐            │ - 800ms 防抖/35s 超时 │  │
-│  │ Markdown 渲染引擎 (renderers/)   │            └───────────────────────┘  │
-│  │ - common.ts: 单元格清洗/通用徽章 │                                       │
-│  │ - 11领域模块: pr/issue/run/repo/ │                                       │
-│  │   release/skill/label/ruleset/   │                                       │
-│  │   cache/gist/status 独立渲染     │                                       │
-│  │ - 统一门面出口 markdown.ts 兼容  │                                       │
-│  └──────────────────────────────────┘                                       │
+│  │  - status (健康) │                            │ - /issue-detail (Issue│  │
+│  │  - agent_task    │                            │   在线详情与评论)     │  │
+│  │  - discussion    │                            │ - /pr-detail (PR 审阅)│  │
+│  │  - project (v2)  │                            └──────────┬────────────┘  │
+│  │  - codespace(MVP)│                        ┌───────────────────────────┐  │
+│  │  - help (元指南) │                        │ git-watcher (独立服务)    │  │
+│  └────────┬─────────┘                        │ - .git/HEAD & index       │  │
+│           │                                  │ - 800ms 防抖/35s 超时     │  │
+│           │                                  └───────────────────────────┘  │
+│           ▼                                                 │               │
+│  ┌──────────────────────────────────┐                       │               │
+│  │ Markdown 渲染引擎 (renderers/)   │                       │               │
+│  │ - common.ts: 单元格清洗/通用徽章 │                       │               │
+│  │ - 15领域模块: pr/issue/run/repo/ │                       │               │
+│  │   release/skill/label/ruleset/   │                       │               │
+│  │   cache/gist/status/agent-task/  │                       │               │
+│  │   discussion/project/codespace   │                       │               │
+│  │ - 统一门面出口 markdown.ts 兼容  │                       │               │
+│  └──────────────────────────────────┘                       │               │
+│           │                                                 │               │
+│           ▼                                                 ▼               │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │ 遥测审计系统 (src/telemetry.ts ➔ Cordis tools/result 事件切面)        │  │
+│  │ - TelemetryRingBuffer (固定 200 条无锁环形队列，常驻内存 <200KB)      │  │
+│  │ - 实时计算 API 降级率 (Degradation Rate) 与工具链健康分 (0-100 分)     │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────┬───────────────┘
                                                               │
 ┌─────────────────────────────────────────────────────────────┼───────────────┐
@@ -75,7 +87,7 @@
 │   │  · icons.ts (Octocat, Git 官方菱形分支矢量组件, 插件徽标)           │   │
 │   │  · storage.ts (LocalStorage SWR 状态机与偏好存储)                   │   │
 │   │  · components/ (分支下拉/认证引导/升级通知/离线横幅/状态胶囊)       │   │
-│   │  · modals/ (Commit 详情弹窗 / 4分区全局设置弹窗)                    │   │
+│   │  · modals/ (Commit 详情弹窗 / PR 审阅工作台 / Issue 在线查看 / 全局设置弹窗)  │   │
 │   │  · panels/ (首页全景大面板 workspace-panel.ts)                      │   │
 │   │                                                                     │   │
 │   │ 核心组装入口 (src/client.ts, ~1,260 行高内聚):                      │   │
@@ -103,14 +115,14 @@
 
 ### 2.3 上下文 Token 保护与防御性输出包装 (Token Budget Guard)
 - 所有的 `gh` 查询原生采用 `--json <fields>` 结构化投影；
-- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），采用码点安全切割与二分查找字节截断（`src/executor/process-utils.ts`），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；
-- 列表与详情输出经独立 Markdown 渲染引擎（`src/renderers/` 7 大领域模块）转化为高密度表格与卡片（带状态徽章、可点击超链接与竖线转义防护），实测 20 条 PR 列表输出压缩 70%+ Token；
+- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），采用码点安全切割与二分查找字节截断（`src/executor/process-utils.ts`），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文；**程序化消费的大载荷可按调用点显式放宽**（PR diff 与 Issue 详情放宽至 2MB 字符 / 8MB 字节），因为这两类数据只在服务端切片后渲染，不进入模型上下文；**且一旦真的被截断必须显式失败**——截断会让 `JSON.parse` 被跳过、`data` 变 `undefined`，静默降级会渲染出「元数据全空 + 零评论」的假详情；
+- 列表与详情输出经独立 Markdown 渲染引擎（`src/renderers/` 15 大领域模块 + `common.ts` + `markdown.ts` 门面）转化为高密度表格与卡片（带状态徽章、可点击超链接与竖线转义防护），实测 20 条 PR 列表输出压缩 70%+ Token；
 - 所有 Agent 工具的输出统一经过归一化，列表自动打包为 `{ items, count }`，标量打包为 `{ result }`，100% 严丝合缝契合 DSH 工具网关模式约束；
 - **gh 版本守卫降级链（runGuarded）**：preview 命令与新特性按 `minVersion` 门槛路由——版本达标直通主命令、不足走 `fallback` 降级链路（结果携带 `degraded/degradedReason` 结构化标注，**降级不是静默的**，渲染层对 degraded 结果显式追加链路说明）、无降级时报错附平台升级指引；版本探测自身失败 fail-open 直通（守卫是路由优化不是安全边界）。版本比较采用数值分段（`src/executor/version-utils.ts`，杜绝 `'2.96.0' > '2.100.0'` 字典序陷阱），探测结果 30s TTL 缓存且只缓存成功值；
 - **AI_AGENT 识别信号注入**：每次 gh 子进程启动注入 `AI_AGENT=dsh`（gh detect.go 最高优先级通用信号）——gh ≥2.99 自动切换 text-only spinner、≥2.100 命令误用时打印完整 help（模型可据此自我纠正）、telemetry 归因到 dsh；旧版 gh 忽略该变量零副作用。经 `agentEnvInjection` 配置开关（默认开启）可恢复 gh 原生行为。
 
 ### 2.3.1 高危操作确认与敏感值安全通道 (Safety Confirmation & Secret stdin Channel)
-- 不可逆写操作（`merge` / `close` / `issue delete`（物理删除）/ `issue transfer`（跨仓库迁移）/ `pr revert`（远端创建反向 PR）/ `release delete` / clobber 覆盖上传 / `secret delete` / `skill install` / `label delete`（物理删除且解绑）/ `cache delete all`（全量清空缓存）/ `gist delete`（代码片段永久删除））强制要求 `confirm: true` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
+- 不可逆写操作（`merge` / `close` / `issue delete`（物理删除）/ `issue transfer`（跨仓库迁移）/ `pr revert`（远端创建反向 PR）/ `release delete` / clobber 覆盖上传 / `secret delete` / `skill install` / `skill publish`（创建 Release）/ `label delete`（物理删除且解绑）/ `cache delete all`（全量清空缓存）/ `gist delete`（代码片段永久删除）/ `codespace delete`（销毁开发机）/ `project item-delete`（移除看板条目））强制要求 `confirm: true` 显式参数，未确认时仅返回影响评估卡片，不产生任何远端或本地副作用；
 - 密钥明文仅经子进程标准输入传递（`spawnWithStdin` 通道：`spawn` + `stdin.end(data)` 半关闭写入），全程不出现在命令行参数、进程列表与工具输出中；渲染层对 secret 输出采用独立实现，从结构上隔离「绝不渲染 value 字段」这条安全红线。
 
 ### 2.3.2 产物落盘纪律 (Artifact Download Discipline)
@@ -132,9 +144,9 @@
 - [src/executor/platform-guide.ts](../src/executor/platform-guide.ts)：跨平台 CLI 安装引导与升级命令文本生成。
 
 ### 3.2 渲染层领域化细分 (`src/renderers/`)
-- [src/renderers/markdown.ts](../src/renderers/markdown.ts)（瘦身至 14 行）：门面出口，统一聚合导出全部领域子模块；
+- [src/renderers/markdown.ts](../src/renderers/markdown.ts)：门面出口，统一聚合 Re-export 全部领域子模块；
 - [src/renderers/common.ts](../src/renderers/common.ts)：表格单元格字符净化、各类状态药丸 Emoji 徽章、API 降级透明注解；
-- `pr.ts` / `issue.ts` / `run.ts` / `repo.ts` / `release.ts` / `skill.ts`：6 大领域独立渲染格式化，避免跨工具改动合并冲突。
+- 15 大领域独立渲染模块：`pr.ts` / `issue.ts` / `run.ts` / `repo.ts` / `release.ts` / `skill.ts` / `label.ts` / `ruleset.ts` / `cache.ts` / `gist.ts` / `status.ts` / `agent-task.ts` / `discussion.ts` / `project.ts` / `codespace.ts`，彻底实现高内聚低耦合，避免跨工具改动冲突。
 
 ### 3.3 本地 Git 元数据监听服务 (`src/git-watcher.ts`)
 - 独立底层服务模块，彻底剥离路由控制器内部的物理文件系统监听与定时器杂糅；
@@ -143,22 +155,24 @@
 
 ### 3.4 前端客户端解耦与自包含 Bundle 机制 (`src/ui/` + `src/client.ts`)
 - **源码物理剥离**：
-  - [src/client.ts](../src/client.ts)（由 5,290 行直降至 **1,263 行，瘦身 76%**）：仅保留右侧栏核心协同 `renderGithubRepoView` 与 `GithubRightbarBody` 及插件入口；
-  - 12 个独立子模块下沉至 [src/ui/](../src/ui/) 目录（样式 1,295 行、全景大面板 732 行、设置弹窗 561 行、业务卡片 60~290 行）；
+  - [src/client.ts](../src/client.ts)（当前约 2,400 行）：保留右侧栏核心协同 `renderGithubRepoView` 与 `GithubRightbarBody` 及插件入口；新增 UI 优先下沉到 `src/ui/`，不在入口文件里堆叠；
+  - **18 个独立子模块**下沉至 [src/ui/](../src/ui/) 目录：样式 2,506 行、全景大面板 932 行、PR 审阅弹窗 817 行、Issue 查看弹窗 565 行、设置弹窗 552 行、使用指南 408 行，其余卡片类组件 60~300 行；
 - **命名空间防护**：
   - 严禁在与 `package.json` 的 `exports["./client"]` 同级创建名为 `client/` 的目录，统一命名为 `src/ui/` 与编译产物 `lib/ui/`，彻底杜绝模块解析器产生“同名文件 vs 目录”的歧义报错；
 - **自包含 Bundle 聚合器 (`scripts/build.mjs`)**：
   - 构建脚本按严格拓扑顺序将 `lib/ui/` 子模块内联注入 `lib/client.js` 的 `window.__ModuleLoader__.load` 闭包中，移除 `export` 关键字；
-  - 保证 `GithubRightbarBody` 位于 `GithubWorkspacePanel` 之前（满足切片测试断言）；
-  - 对嵌入的 1,290 行纯 CSS 实施紧凑压缩，消除空行与多余注释，使编译产物从 5,282 行减至 4,008 行；
+  - **顺序即依赖**：`markdown-lite → pr-modal → issue-modal → …` 不可随意重排（`issue-modal` 复用了 `pr-modal` 的 `CollapsibleBody`）；`workspace-panel` 置于后置列表，保证 `GithubRightbarBody` 位于 `GithubWorkspacePanel` 之前；
+  - 对嵌入的约 2,500 行纯 CSS 实施紧凑压缩；压缩后强制校验「无注释定界符残留 / 无行首 `*` 悬空段 / 花括号配平」，任一项不过直接构建失败——非法 CSS 会被浏览器**静默丢弃整条规则**，只表现为「样式莫名不生效」，极难排查；
 - **React Hook 时序安全防线**：
-  - 组件内引用的 `useRef`（如 `containerRef`）必须在组件声明最前列初始化，严禁跨行下置引发变量提升 `undefined`；所有的 Ref 访问点必须配备 `containerRef && containerRef.current` 守卫，杜绝运行时渲染崩溃。
+  - 全部 Hook（含 `useEffect`）必须位于任何 early return 之前，否则「参数由空变有值」时两次渲染的 Hook 数量不一致，触发 `Rendered fewer hooks than expected` 崩溃；
+  - `renderGithubRepoView` 这类每次渲染都重新执行的普通函数内**禁止**调用 Hook，状态必须住在有 Hook 的组件体内再传参；
+  - 组件内引用的 `useRef`（如 `containerRef`）必须在组件声明最前列初始化，严禁跨行下置引发变量提升 `undefined`；所有的 Ref 访问点必须配备 `containerRef && containerRef.current` 守卫。
 
 ---
 
 ## 4. 自动化测试体系 (Test Suite)
 
-项目配备了 13 个独立阶段的全量自动化回归测试套件（`test/run-all.mjs`），覆盖 **562 项全量自动化测试断言**：
+项目配备了 **33 个独立阶段的全量自动化回归测试套件（`test/run-all.mjs`）**，覆盖 **1784 项全量自动化测试断言**：
 - `phase1`：Issue / Run / PR / Repo / Help 命令装配与确认门禁；
 - `phase2`：Native Markdown 渲染与 Token 压缩率实测（>60% 降幅）；
 - `phase3`：Release 资产交付、Secret 密文管道与 Skills 检索；
@@ -171,4 +185,24 @@
 - `phase10`：版本守卫降级链（runGuarded）、AI_AGENT 注入与命令白名单；
 - `phase11`：右侧栏五 Tab 响应式互斥、Git 提交记录与滑动分页；
 - `phase12`：工作区物理所有权隔离、SWR 离线快照防抹杀与安全分支切换；
-- `phase13`：云端定时自动同步生命周期、三选一互斥设置模型与右侧栏独占本地 git-watch 监听。
+- `phase13`：云端定时自动同步生命周期、三选一互斥设置模型与右侧栏独占本地 git-watch 监听；
+- `phase14`：github_label（标签体系CRUD与克隆）与 github_ruleset（保护策略排障）；
+- `phase15`：github_cache（构建缓存治理）与 github_gist（代码片段与排障留痕）；
+- `phase16`：github_status（全局待办大盘）与 attach_images（图片附件上传通道）；
+- `phase17`：github_skill publish（agentskills.io 规范自检、--fix 修复与发布闭环）；
+- `phase18`：github_agent_task（云端编码智能体会话）与 github_discussion（社区讨论与RFC）；
+- `phase19`：github_project（Projects v2 看板）、github_codespace（云端开发机）与 skill update；
+- `phase20`：TelemetryRingBuffer、Cordis tools/result 事件总线运行时遥测、降级率统计与健康度看板；
+- `phase21`：未提交数据滚动分页、文件级 Diff 二级下钻与 DSH 原生打开文件联动；
+- `phase22`：remote 配置指纹与缓存失效契约（parseRemoteUrls 段扫描、指纹对书写顺序/命名免疫、worktree `.git` 指针解析、TtlCache 指纹命中与保守失效）；
+- `phase23`：离线身份解析对齐 git 规则（branch.<当前分支>.remote → origin → 首个三级回落、`.` 特殊值、六种 URL 形态、worktree HEAD/config 分居、旧「取第一个 github.com」正则移除断言）；
+- `phase24`：仓库拓扑与权限字段（isFork / parent 拼接 / viewerPermission 五档白名单）、远程布局四分类（github-only / mixed / no-github / no-remote）与混合布局的顺序免疫选择、默认分支从 refs/remotes/<remote>/HEAD 符号引用动态推断；
+- `phase25`：右侧栏仓库徽章可视化（resolveRepoBadges 纯函数：fork 徽章与血缘行、READ/TRIAGE 只读徽章、可写与未知权限零徽章、parent.url 协议白名单防 javascript:/data: 注入）、bundle 内联断言与「零新增网络往返」静态约束；
+- `phase26`：写操作权限自愈（GraphQL 权限错误补入确定性分类、permissionRemedy 按 Triage/Write/Admin 三档给出可操作指引并拼入 error 供模型自愈、限流 403 不误判、非权限错误零噪音、前端快捷按钮保持可用的防回退断言）；
+- `phase27`：关联仓库自由切换（getAssociatedRepos 双 remote / Fork+Parent 纯本地多仓推导、RepoSelectorDropdown 下拉组件、setDefaultRepo 官方 set-default 对齐与防注入白名单、Fork 血缘行一键双向快捷切换）；
+- `phase28`：PR 在线审阅工作台与主面板标签页解耦（splitUnifiedDiff 按文件切片索引、core.quotePath 八进制转义还原、含 ` b/` 路径的等值分割判定、删除文件路径回退、getPrDetail 参数白名单与 diff 阈值放宽不被截断、响应体不回传 fullDiff 防膨胀、**行级审查评论独立 API 通道 + original_line 回退 + 失败降级**、/api/github/pr-detail 路由真实调用与 405/400/500 错误路径、**action/branch-switch 请求体 256KB 上限与 413 行为验证**、主面板 mywork 拆为 prs/issues 四标签页、React Hooks 顺序静态防回退）；
+- `phase29`：数据可见性与 PR 弹窗交互（PR/Issue 查询移除 `--state=open` 硬过滤并补齐 state 字段、clampFilePaneWidth 纯函数边界与容器极窄保下限、文件区布局偏好 localStorage 往返与脏数据回退、分隔条拖拽 document 级监听与卸载兜底清理、折叠双恢复入口、**PR 标题行与 GitHub 跳转按钮同行（min-width:0 + flex-shrink:0 防长标题挤出）**、空态区分「筛选为空」与「账号无记录」）；
+- `phase30`：PR 弹窗 Markdown 渲染与滚动适配（markdown-lite 零依赖解析器：标题/粗斜体/行内码/围栏代码块/列表/引用/分隔线/任务列表；链接协议白名单拒绝 javascript:/data:/vbscript:/协议相对；HTML 标签降级为纯文本；estimateContentLines 折叠阈值估算；卡片 flex:0 0 auto 修复「长内容无法滚动」；CollapsibleBody 提升到模块顶层避免内联组件导致展开状态被重置）。
+- `phase31`：Issue 在线查看工作台（getIssueDetail 参数白名单含小数/负数拒绝、**2MB 字符阈值防长讨论被截断成假空详情**、老版本 gh `Unknown JSON field` 的 BASE 字段降级链与 fieldsDegraded 标记、非字段类失败不重试、截断与解析缺失显式失败并给出浏览器直达链接、state/author/labels/milestone/subIssuesSummary/closedByPullRequestsReferences 归一化、SPAM 隐藏评论标记保留、图片清单正文+评论合并去重、/api/github/issue-detail 路由 200/400/405/500 全路径、action 通道 issue_detail 对称可用、主面板与右侧栏 Issue 卡片改点击进弹窗 + 同行 GitHub ↗ 外跳 stopPropagation + 卡片禁内联 flex 布局、onSelectIssue 追加在形参末尾、React Hooks 顺序与 bundle 三模块拓扑顺序防回退）。
+- `phase32`：右侧栏 PR/Issue 状态筛选（**单仓库查询显式 `--state all`**，修复「只显示已打开」根因——gh 默认 state 就是 open，数据在到达浏览器前已被过滤；条数上限 10→20 并抽成 RIGHTBAR_LIST_LIMIT 常量，依据 `gh pr list` 按 number 降序而非 updatedAt，取 10 条时非 OPEN 仅剩 5 条；触顶下发 prsTruncated/issuesTruncated 并渲染提示；PR 四档 all/open/merged/closed 与 Issue 三档 all/open/closed 胶囊复用既有样式类、计数先于过滤保证数字反映全量；偏好按 cwd 隔离存储、非法值与脏 JSON 归一回退、大写输入归一；空态区分「仓库无记录」与「筛选无结果」并给切换引导；Hook 位置（不可落在 renderGithubRepoView 内）、切仓库对齐只依赖 cwd、**作用域键无碰撞（/a/b 与 /a_b 不得压成同一个键）**、卡片布局纪律防回退）。
+- `phase33`：使用指南内容与代码事实对账（help-modal 从 4 Tab 扩到 5 Tab，新增「18 大工具速查」；**工具数量对 src/main.ts 的 ctx.tools.register 数量、action 总数对 src/tools 的 enum 累计、Tab 名称对 TAB_DEFS 与 workspace-panel 逐个核对**，代码演进而指南没跟上即失败；覆盖 PR/Issue 在线弹窗、状态筛选三档、Markdown 渲染、仓库切换器、提交详情、Diff 下钻、view_images 等近期能力；FAQ 扩至 6 条含「列表为空但网页有记录」与「为何需重启 DSH」；**防编造断言：指南中每条 `gh auth refresh -s <scope>` 必须能在源码找到出处**；**github_help 知识库同步对账：mapping 表声明的每组 action 数逐个对 src/tools 的 enum 长度、每个业务 action 必须在知识库有落点、规模口径统一为「18 工具 / 103 业务 action」（排除 help 的 21 查询主题与 api 的 4 HTTP method），Agent 侧知识库与 UI 侧使用指南必须同口径**）。