dsh-github-flow 0.6.0 → 0.7.1

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>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>.
+  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>19 core domain Agent tools (106 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,28 @@ dsh plugin --profile web add dsh-github-flow
 
 ## 🤖 Core Agent Tools: Equipping Agents with Native GitHub Powers
 
-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**.
+Consolidates scattered GitHub endpoints into **19 core domain tools (106 actions)**, 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**.
+
+### 0. `github_task`: Task-level Primitives (🆕 new in v0.7.0)
+> **Example Agent Prompts**:
+> - *"Review PR #12, focus on security"*
+> - *"Why did CI fail?"*
+> - *"What should the next version be? Draft the notes"*
+
+The 19 domain tools above are a **verb table** (list / view / diff / checks / review…), while users speak in **tasks**. `github_task` wraps the three most repeated journeys into **one call** and returns an already-trimmed, directly actionable envelope:
+
+```text
+summary (≤1.5KB) + facts (structured) + nextActions (concrete next steps) + cost (chars / gh calls / elapsed)
+```
+
+* **`review_pr`**: PR metadata + head SHA + changed-file diffs (trimmed by `budget_chars`) + CI tri-state + repository `AGENTS.md` review rules + existing line-comment count — in one shot.
+  * `focus: 'security' | 'correctness' | 'perf' | 'style'` only changes the wording of the conclusion, not what is fetched.
+  * **Read-only by default**; writing a review back requires `write: true, confirm: true` (the gate returns a confirmation payload first).
+* **`diagnose_ci`**: takes `run_id` or `pr_number` → locates failing jobs/steps → extracts failure-log anchors by framework → lists suspected files. When the log is truncated, `truncated.totalUnknown = true` — **do not conclude "that's all the failures"**.
+* **`prepare_release`**: commits since the last tag → Conventional Commits grouping → SemVer suggestion (breaking→major / feat→minor / else→patch) → release-notes draft + health check (clean tree / synced / CI green).
+  * **This primitive never tags, pushes, or creates a Release**: releasing is a human decision; it only prepares "which version, what notes" and puts ready-to-run commands in `nextActions`.
+
+> **Tier tip**: `toolsets: ['core']` is exactly "3 tasks instead of 15 domain tools" (`github_task` + `github_repo` + `github_help`, ~4,400 chars of schema — 84% smaller than full). Add `github_pr` / `github_run` explicitly when you need fine-grained control — primitives are shortcuts, not the only entrance.
 
 ### 1. `github_pr`: Pull Request Lifecycle & Automated Code Review
 > **Example Agent Prompts**:
@@ -90,15 +111,28 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
   * `create`: Auto-create PRs (supports draft mode & `--dry-run`, supports `attach_images` local uploads);
   * `edit`: 🆕 Edit PR title, body description, and metadata with image attachment support;
   * `comment`: 🆕 Post comments and reviews to pull requests with image attachment support;
-  * `checkout`: 🆕 Check out PR code to a local branch for sandboxed testing;
+  * `checkout`: 🆕 Check out PR code to a local branch so the Agent can run tests in the local workspace (requires a clean working tree; an existing branch is not reset unless `force: true` + `confirm: true` are passed);
   * `status`: 🆕 Inspect merge conflict status (`CLEAN` / `CONFLICT`) for the current branch's PR;
   * `review`: Submit code reviews (`APPROVE`, `REQUEST_CHANGES`, `COMMENT`);
+  * 🆕 **`review` + `comments` (line-level review comments, new in v0.7.0)**: `gh pr review` has no line-level flags, so this version adds a `comments` array backed by `POST /pulls/{n}/reviews`, posting multiple comments anchored to specific code lines in one request. **Without `comments` the behaviour is byte-for-byte identical to previous versions** (still `gh pr review`) — no write-back by default.
+
+    ```jsonc
+    // github_pr(action:'review', pr_number:12, review_decision:'COMMENT',
+    //            body:'summary', comments:[{ path:'src/a.ts', line:42, body:'needs a lock here' }])
+    // optional: side('LEFT'|'RIGHT', default RIGHT), start_line (multi-line), commit_id (pin to a SHA)
+    ```
+
+    Three boundaries: ① max **50** comments per review; ② `path`/`body` required and `line` must be a positive integer — validation reports **all** problems at once; ③ if a line is not on the commentable side of the diff (pure deletions, etc.) and GitHub returns **422**, the comments are **folded into the review body** (prefixed with `path:line`), retried once, and explicitly marked `degraded` — no content is lost.
+  * 🆕 **Severity prefixes `[P0]` / `[P1]` / `[P2]` (new in v0.7.0)**: review bodies and every line comment pass through severity normalization before submission — **existing prefixes are preserved, a missing one gets `[P2]`, and `[P0]`/`[P1]` are never downgraded**. The goal is to keep a pile of P2s from drowning out the P0; the plugin only adds labels, it never rewrites your judgement.
+  * 🆕 **Repository review rules from `AGENTS.md` (new in v0.7.0)**: `view` reads `AGENTS.md` from the workspace (repo root plus the nearest file in each changed file's directory, ≤8KB per file / ≤16KB total), extracts the `## Code Review Rules` section (falls back to the whole file when that heading is absent), returns it as `reviewRules`, and renders a "Repository review rules" section at the end of the Markdown output. **When no `AGENTS.md` exists the key is absent entirely** — "no rules" and "empty rules" stay distinguishable. Rules enter context only through tool output; nothing is injected into the system prompt.
+  * 🆕 **Review anchors & visible truncation (new in v0.7.0)**: `view` now returns `headRefOid` / `baseRefOid` / `changedFiles`, and the Markdown branch line renders as `feat/x@a1b2c3d` (branch names move, SHAs don't); when the `files` list hits gh's 100-item cap it says so explicitly ("only the first N / M listed").
   * `merge`: Merge pull requests (`squash` / `merge` / `rebase`, optional `delete_branch`; requires `confirm: true`);
   * `ready`: 🆕 Toggle Draft ↔ Ready (`undo: true` converts back to Draft — fully reversible);
   * `revert`: 🆕 Create a revert commit (generates a new revert PR on the remote; requires `confirm: true`);
   * `update_branch`: 🆕 Sync the latest base-branch commits into the PR branch — the self-healing action for "branch is out-of-date" CI gate failures;
   * `view_images`: 🆕 Download PR discussion screenshots (body + comments; `image_urls` targeting with budget-overflow resume list);
   * `attach_images` (param): 🆕 Upload local images/attachments to PRs (up to 50 files/batch, symmetric with view_images, requires gh ≥ 2.99).
+  * `body_file` (param): 🆕 PR and comment bodies can come straight from a local markdown file (`create` / `edit` / `comment` / `review`), mutually exclusive with `body`; relative paths resolve against the current workspace, the file must be valid UTF-8 (GBK/ANSI fails loudly), and bodies are capped at 65,536 characters — long bodies never enter the model context.
 
 ---
 
@@ -123,6 +157,7 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
   * `status`: 🆕 Retrieve a comprehensive dashboard of issues assigned to the active user;
   * `view_images`: 🆕 Download screenshot attachments from issue descriptions and comments into local image blocks;
   * `attach_images` (param): 🆕 Upload local file screenshots alongside issues (up to 50 local files/batch, requires gh ≥ 2.99).
+  * `body_file` (param): 🆕 Issue and comment bodies can come straight from a local markdown file, mutually exclusive with `body`; relative paths resolve against the current workspace, the file must be valid UTF-8, and bodies are capped at 65,536 characters.
 
 ---
 
@@ -136,6 +171,8 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
   * `list`: Query workflow runs by branch or status;
   * `view`: Inspect step breakdown and conclusion states;
   * `log_failed`: **🔥 Troubleshooting Swiss Army Knife**! Pinpoints exact failing jobs and steps, extracting only the critical failure lines;
+  * 🆕 **Framework-aware anchor extraction (new in v0.7.0)**: the whole log is no longer dumped at the model. Failure markers from common frameworks (pytest `FAILED`, node `AssertionError`, Go `panic:`, tsc `error TSxxxx`, `npm ERR!`, …) are used to slice the log into **failure blocks** (each with a start line and following context; adjacent markers are merged), then trimmed to a character budget; when blocks exceed the cap it states "N blocks omitted (M total)". **If no known anchor matches it falls back to the last 200 lines** and says why (failures are concluded at the end of a log; the head is mostly environment setup).
+  * For this, `log_failed`'s output budget is raised to **2MB chars / 8MB bytes** — otherwise the default 24K truncation happens *before* extraction and later failures never reach the context.
   * `rerun`: Re-trigger failed workflows with one click;
   * `cancel`: Cancel in-progress or queued runs;
   * `trigger`: Manually dispatch `workflow_dispatch` workflows with custom parameters;
@@ -176,6 +213,7 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
   * `list`: Query release history;
   * `view`: Inspect notes and asset manifests for a given tag;
   * `create`: Publish releases (supports `generate_notes`, drafts, prereleases, and asset attachments);
+  * `notes_file` (param): 🆕 Release notes can come straight from a local markdown file (replaces `notes`, maps to `--notes-file -`), mutually exclusive with `notes`; relative paths resolve against the current workspace, the file must be valid UTF-8 (release notes do not use the 65,536-character body cap — only the 4MB file-size guard applies);
   * `upload`: Attach build assets to an existing release (`clobber: true` requires `confirm: true`);
   * `download`: Download release artifacts with glob pattern filters;
   * `delete`: Delete releases (`cleanup_tag: true` deletes associated Git tag; requires `confirm: true`).
@@ -196,7 +234,9 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
 
 ---
 
-### 7. `github_skill`: Agent Skills Ecosystem Discovery & Local Installation
+### 7. `github_skill`: Agent Skills Ecosystem Discovery & Local Installation 🧪 Preview
+
+> 🧪 **Preview dependency**: built on `gh skill`, which is currently in public preview (`subject to change without notice`); the command surface may change with gh releases.
 > **Example Agent Prompts**:
 > - *"Search GitHub for open-source Agent skills related to 'markdown'."*
 > - *"Preview and install the code review skill from 'github/awesome-copilot' into this project."*
@@ -218,7 +258,7 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
 > - *"How do I debug 'authentication failed' errors from gh?"*
 
 * **Supported Actions**:
-  * `overview`: Complete toolbox navigation and summary table (18 core tools);
+  * `overview`: Complete toolbox navigation and summary table (19 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;
@@ -273,7 +313,7 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
 
 * **Supported Actions**:
   * `list`: Audit Actions caches with human-readable size formatting (KB/MB/GB), key prefix and ref filtering, and size/access sorting;
-  * `delete`: Precise 3-way cleanup (by `cache_id`, by `key`, or purge everything via `all: true`; purge is destructive and requires `confirm: true`, injects `--succeed-on-no-caches` for idempotency).
+  * `delete`: Precise 3-way cleanup (by `cache_id`, by `key`, or purge everything via `all: true`; **all three paths require `confirm: true`**; purge additionally injects `--succeed-on-no-caches` for idempotency).
 
 ---
 
@@ -300,24 +340,28 @@ Consolidates scattered GitHub endpoints into **18 core domain tools (104 actions
 
 * **Supported Actions**:
   * `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.
+  * `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 19 tools.
 
 ---
 
-### 15. `github_agent_task`: Cloud Coding Agent Session Governance
+### 15. `github_agent_task`: Cloud Coding Agent Session Governance 🧪 Preview
+
+> 🧪 **Preview dependency**: built on `gh agent-task`, which is currently in public preview (`subject to change without notice`); the command surface may change with gh releases.
 > **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`);
+  * `list`: List agent tasks (supports `-L/--limit`; `gh agent-task list` does not accept `-R/--repo`, which has no effect on this action);
   * `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
+### 16. `github_discussion`: Team Discussions & Open-Source RFC Loop 🧪 Preview
+
+> 🧪 **Preview dependency**: built on `gh discussion`, which is currently in public preview (`subject to change without notice`); the command surface may change with gh releases.
 > **Example Agent Prompts**:
 > - *"List open discussions in category 'Ideas' for this repository."*
 > - *"View discussion #101 body and comment thread."*
@@ -381,6 +425,7 @@ Click the **Octocat icon** in DSH's left navigation bar to open the full-screen
 * **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.
+* **⚡ Actions Run Online Detail**: Click any run card in the sidebar to inspect workflow / branch / commit / trigger event / duration plus the full job & step tree (per-step conclusion and timing, failed steps highlighted, first failed job expanded by default). On failure, pull an anchored log excerpt on demand (up to 3 failed jobs per click, 90s server-side batch budget, 100s client-side abort), while `GitHub ↗` still opens the complete log on GitHub.
 
 <p align="center">
   <img src="./docs/images/1.png" alt="GitHub Global Cockpit" width="100%" />
@@ -403,10 +448,11 @@ Located in the right drawer of every chat workspace, seamlessly bridging your lo
     * 15 commits displayed by default, with **infinite scroll loading** when scrolling to the bottom (with live `15 / 74` progress counter and click trigger);
     * 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;
+    * **File Diff Preview Modal**: Click a file stat row inside the commit detail, or any file in the uncommitted list, to open that file's Unified Diff in a modal (the whole patch is split per file on `diff --git` boundaries, renamed paths normalized, body lines starting with `---`/`+++` are not mistaken for file headers, oversized patches truncated on file boundaries); the modal stacks above the commit detail (Esc closes one layer at a time) and offers copy-source plus "Open in DSH";
   * **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)`)**: 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);
+  * **Actions Pipeline (`⚡ Actions (N)`)**: Real-time CI workflow status tracking with trigger event badges (`push`/`schedule`/`manual`/`PR`) and relative time; **click a card to open the in-app run detail** — job / step tree with failed steps highlighted (first failed job expanded), plus an on-demand anchored log excerpt (up to 3 failed jobs, 90s batch budget), while `GitHub ↗` still opens the full log on GitHub;
 * **⚙️ 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.
 
 <p align="center">
@@ -415,10 +461,10 @@ Located in the right drawer of every chat workspace, seamlessly bridging your lo
 
 ### 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);
+* **🚀 3-Minute Quickstart**: login check → workspace binding → first Agent instruction, plus a capability overview (19 tools / 106 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;
+* **🧰 19-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.
@@ -436,7 +482,7 @@ Click **`[⚙️ Settings]`** in the top right of the Cockpit (or the ⚙️ but
 * **Visual Cache Management**: Real-time snapshot size and timestamp visibility with one-click `[🗑️ Clear Cache]`.
 
 **🌐 Network Proxy Section** — route all plugin traffic through your proxy:
-* **Global Scope**: Once configured, the cockpit, right-sidebar panel, all 9 Agent tool invocations, and one-click upgrades route through the proxy;
+* **Global Scope**: Once configured, the cockpit, right-sidebar panel, all 19 Agent tool invocations, and one-click upgrades route through the proxy;
 * **Protocol Support**: `http://` / `https://` / `socks5://` / `socks5h://` (`socks5h` delegates DNS resolution to the proxy for stronger pollution resistance);
 * **`[🧪 Test Connectivity]`**: One-click latency probe against the GitHub API through the current proxy;
 * **Instant Effect**: Persisted to `~/.dsh/data/dsh-github-flow/proxy.json` (auto-restored on DSH restart) — no restart, no plugin reload;
@@ -530,8 +576,17 @@ Fine-tune options via DSH config:
     updateCheckIntervalMs: 86400000 # Update check interval in ms (default 24h)
     registryUrl: ''           # Custom npm registry (defaults to Update Source setting)
     proxyUrl: ''              # Default proxy URL (overridden by UI settings)
+    toolsets: ['core']        # Tool tier: unset/full = all 19; core=3 / ci=7 / maintain=8; bare tool names allowed
+    read_only: true           # Read-only tier: write actions pruned from the schema at registration; github_api not registered
 ```
 
+> `toolsets` controls **which tools get registered to the model**, not a runtime permission check: unset = all 19 resident (~27,000 chars of schema), `core` = 3 (~4,400 chars, **84% smaller**). A misspelled tier name logs a `console.warn` listing the available tiers instead of silently dropping every tool.
+> `read_only` is a hard semantic enforced in two layers: (1) write actions are removed from the argument `enum` at registration time (invisible at the schema layer); (2) **the execution entry rejects them again** — this plugin ships hand-rolled descriptors, so the host does not validate arguments on our behalf; a pruned action is refused before it ever reaches `gh`, even with `confirm: true`. `github_api` accepts any endpoint and method, so it cannot be degraded — it is simply not registered.
+> Boundary note: `github_help` output is **documentation**, so it still lists every capability (including write usage) in read-only mode. It is not an executable contract — what actually blocks writes is the two layers above.
+
+> Config is validated by a Schemastery schema: a wrong type (e.g. `maxOutputChars: '24000'` as a string) now **fails loudly** instead of silently falling back to the default.
+> `maxOutputChars` / `defaultTimeoutMs` / `defaultListLimit` are **volatile fields** — editing only these hot-commits the new values into the running instance without reloading the plugin; editing any other field (including `checkUpdate`) still triggers a plugin reload.
+
 ---
 
 ## 🔌 Cordis Ecosystem Service (`ctx.github`)
@@ -540,10 +595,13 @@ Exports a standard Cordis service `ctx.github` for other DSH plugins:
 
 ```typescript
 import type { Context } from '@deepseek-ai/cordis';
+// Optional but recommended: load the declaration merge shipped with this package
+// so `ctx.github` gets full types and autocompletion.
+import type {} from 'dsh-github-flow/host';
 
 export const inject = ['github'];
 
-export function apply(ctx: Context) {
+export async function apply(ctx: Context) {
   const auth = await ctx.github.checkAuth();
   const repo = await ctx.github.getRepoMetadata();
   const prs = await ctx.github.run(['pr', 'list', '--json', 'number,title']);
@@ -552,6 +610,35 @@ export function apply(ctx: Context) {
 
 ---
 
+## 🛠️ Local Development & Debugging
+
+When contributing or customizing the plugin locally, follow this workflow:
+
+### 1. Link Plugin to DSH (Directory Junction)
+By default, DSH profiles copy local `file:` dependencies as static snapshots and may ignore build lifecycle scripts. To achieve instant reflection of your builds, use a native Directory Junction (Windows):
+
+```powershell
+# Windows PowerShell
+New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-github-flow" -Target "D:\Desktop\AgentWork\DSHQuestion\dsh-github-flow" -Force
+```
+
+> ⚠️ **Notice**: Do not run `dsh plugin ... install/add` or `pnpm install` inside the profile directory, as pnpm will replace the Junction with a static snapshot.
+
+### 2. Applying Code Changes
+
+Once the Junction is established, you do not need to reinstall:
+
+1. **Build outputs**: Run in workspace root:
+   ```bash
+   pnpm run build
+   ```
+   > Outputs are compiled into `lib/`, immediately visible to DSH via the Junction.
+2. **Reload**:
+   - **Frontend UI & Styles** (`src/client.ts`, `src/ui/*`): Press **Ctrl + F5** in browser to hard refresh. **No DSH restart required**.
+   - **Backend Engine & API Routes** (`src/tools/*`, `src/api/*`, `src/executor.ts`, `src/main.ts`): **Restart DSH** to reload cached in-memory modules.
+
+---
+
 ## 📚 Documentation & Technical References
 
 - [npm Publishing & Automated CI Guide](./docs/npm-publish-guide.md)

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>18 大领域 Agent 核心工具（104 个 action，覆盖 PR 审查/Issue 任务/Actions 工作流与构建缓存治理/免 clone 读文件/分支规则集策略排障/代码片段 Gist/标签与全局待办大盘/密钥与变量管理/智能体任务会话/社区 Discussions 讨论/Projects v2 看板/云端 Codespaces/运行时遥测与自愈健康度）</b>、<b>人类 Slash 快捷指令</b>、<b>Web UI 全景工作台</b> 与 <b>一键自动跨平台无缝升级</b>。
+  原生复用宿主机 <code>gh</code> CLI 安全登录凭据，告别 Personal Access Token 泄露；深度打通本地 Git 工作区与云端仓库协作，兼具 <b>19 大领域 Agent 核心工具（106 个 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,28 @@ dsh plugin --profile web add dsh-github-flow
 
 ## 🤖 核心工具集 (Agent Tools)：给 Agent 装上 GitHub 的手和脚
 
-本插件精选聚合为 **18 大领域核心工具（104 个 action）**，官方命令语义化覆盖率高达 **87%（104/120）**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）**、**OAuth Scope 缺失单行自愈引导** 与 **零参数 CWD 智能绑定**。
+本插件精选聚合为 **19 大领域核心工具（106 个 action）**，拒绝几十个无用微型工具撑爆 Agent 上下文，原生搭载 **Token 防溢出保护（默认 24KB 智能二分截断）**、**高密度 Markdown 原生渲染（列表输出压缩 70%+ Token）**、**OAuth Scope 缺失单行自愈引导** 与 **零参数 CWD 智能绑定**。
+
+### 0. `github_task`：任务级原语（🆕 v0.7.0 新增）
+> **典型对话指令**：
+> - *"帮我审一下 PR #12，重点看安全问题"*
+> - *"CI 为什么挂了？"*
+> - *"下一个版本该发多少号？notes 写一下"*
+
+上面 18 个领域工具是一张**动词表**（list / view / diff / checks / review…），而用户说的是**任务**。`github_task` 把三件最常反复走的事各封装成**一次调用**，返回**已裁剪、可直接执行**的结论包：
+
+```text
+summary（结论，≤1.5KB） + facts（结构化事实） + nextActions（可执行下一步） + cost（字符数 / gh 调用数 / 耗时）
+```
+
+* **`review_pr`**：一次拿齐 PR 元数据 + head SHA + 变动文件 diff（按 `budget_chars` 裁剪）+ CI 三态 + 仓库 `AGENTS.md` 审查规则 + 既有行级评论数。
+  * `focus: 'security' | 'correctness' | 'perf' | 'style'` 只影响结论里的提示语，不改变取数。
+  * **默认只读**；要写回行级评注必须 `write: true, confirm: true`（闸门会先返回确认载荷）。
+* **`diagnose_ci`**：`run_id` 或 `pr_number` 二选一 → 定位失败 job/step → 按框架锚点萃取失败日志 → 汇总疑似相关文件。日志被截断时 `truncated.totalUnknown = true`，**不要据此判断「就这些失败」**。
+* **`prepare_release`**：读最近 tag 以来的提交 → 按 Conventional Commits 归类 → 推导 SemVer（breaking→major / feat→minor / 其余→patch）→ 生成 notes 草稿 + 发版体检（工作区干净 / 同步远端 / CI 绿）。
+  * **本原语不会打 tag、不会 push、不会创建 Release**：发版是人的决定，它只把「该发什么版本、notes 长什么样」准备好，并在 `nextActions` 里给出可直接执行的命令。
+
+> **档位建议**：`toolsets: ['core']` 就是「3 个任务替代 15 个领域工具」（`github_task` + `github_repo` + `github_help`，schema 仅约 4,400 字符，比全量省 84%）。需要细粒度控制时再显式挂 `github_pr` / `github_run`——原语是快捷方式，不是唯一入口。
 
 ### 1. `github_pr`：PR 全生命周期管理与自动化代码审查
 > **典型对话指令**：
@@ -90,15 +111,28 @@ dsh plugin --profile web add dsh-github-flow
   * `create`：一键自动创建 PR（支持 draft 草稿模式与 `--dry-run` 预演，支持 `attach_images` 上传本地附件）；
   * `edit`：🆕 编辑 PR 标题、描述与关联元数据，支持附加本地图片；
   * `comment`：🆕 向指定 PR 追加讨论评论与审查意见，支持附加本地图片；
-  * `checkout`：🆕 把 PR 代码检出到本地分支，Agent 可直接在沙箱跑测试验证改动；
+  * `checkout`：🆕 把 PR 代码检出到本地分支，Agent 可直接在本地工作区跑测试验证改动（检出前校验工作区干净度；默认不重置已有同名分支，需要重置须显式传 `force: true` + `confirm: true`）；
   * `status`：🆕 查看当前分支关联 PR 的合并冲突状态（`CLEAN` / `CONFLICT`）；
   * `review`：提交代码审查意见（`APPROVE`, `REQUEST_CHANGES`, `COMMENT`）；
+  * 🆕 **`review` + `comments`（行级评注写入，v0.7.0 新增）**：`gh pr review` 本身没有行级参数，本版本新增 `comments` 数组走 `POST /pulls/{n}/reviews`，一次提交多条挂在具体代码行上的评注。**不传 `comments` 时行为与旧版逐字节一致**（仍走 `gh pr review`），默认零写回。
+
+    ```jsonc
+    // github_pr(action:'review', pr_number:12, review_decision:'COMMENT',
+    //            body:'整体说明', comments:[{ path:'src/a.ts', line:42, body:'这里要加锁' }])
+    // 可选字段：side('LEFT'|'RIGHT'，默认 RIGHT)、start_line(多行评注)、commit_id(钉在指定 SHA)
+    ```
+
+    三条边界：① 单次最多 **50 条**；② `path`/`body` 必填、`line` 必须是正整数，校验不通过时**一次列出所有问题**而不是改一条试一次；③ 若某行不在 diff 的可评论侧（纯删除行等）导致 GitHub 返回 **422**，评注会**自动折叠进 review 正文**（带 `path:line` 前缀）重试一次并显式标记 `degraded`，内容不丢失。
+  * 🆕 **严重度前缀 `[P0]` / `[P1]` / `[P2]`（v0.7.0 新增）**：`review` 的正文与每条行级评注在提交前会统一过一遍严重度归一化——**已有前缀原样保留，缺失才补 `[P2]`，永不降级 `[P0]`/`[P1]`**。目的是让一堆 P2 别把 P0 淹没；插件只补标签，不改写你的判断。
+  * 🆕 **仓库审查规则注入（`AGENTS.md`，v0.7.0 新增）**：`view` 会读取工作区的 `AGENTS.md`（根目录 + 变更文件所在目录的就近文件，单文件 ≤8KB、合计 ≤16KB），把 `## Code Review Rules` 段（整文件没有该标题时退化为全文）作为 `reviewRules` 随结果返回，并在 Markdown 输出末尾渲染成「仓库审查规则」一节。**工作区没有 `AGENTS.md` 时输出不含该键**——「没有规则」与「规则为空」在结果里可区分。规则只经工具输出这一条通道进入上下文，不注入系统提示。
+  * 🆕 **审阅锚点与截断可见性（v0.7.0 新增）**：`view` 现在返回 `headRefOid` / `baseRefOid` / `changedFiles`，Markdown 的分支行渲染为 `feat/x@a1b2c3d`（分支名会移动，SHA 不会）；`files` 清单被 gh 的 100 条上限截断时会显式说明「仅列出前 N / M 个」。
   * `merge`：自动执行合并（支持 `squash` / `merge` / `rebase`，可指定 `delete_branch`；需 `confirm: true` 二次确认）；
   * `ready`：🆕 Draft ↔ Ready 切换（附 `undo: true` 可转回 Draft，完整可逆）；
   * `revert`：🆕 创建反向提交（远端生成新 revert PR，需 `confirm: true`）；
   * `update_branch`：🆕 将基准分支最新提交同步进 PR 分支——「分支落后需更新」CI 门禁失败的自愈动作；
   * `view_images`：🆕 下载 PR 讨论截图（正文+评论，支持 `image_urls` 精准提取与触顶续传清单）；
   * `attach_images`（参数）：🆕 上传本地图片/附件至 PR（单批上限 50 个本地文件，与 `view_images` 形成对称闭环，需 gh ≥ 2.99）。
+  * `body_file`（参数）：🆕 PR 正文/评论正文可直接来自本地 md 文件（`create` / `edit` / `comment` / `review` 均适用），与 `body` 二选一；相对路径按当前工作区解析，文件须为合法 UTF-8（GBK/ANSI 会明确报错），正文上限 65,536 字符——长正文不必读进上下文。
 
 ---
 
@@ -123,6 +157,7 @@ dsh plugin --profile web add dsh-github-flow
   * `status`：🆕 检索指派给当前登录用户的待办议题全景面板；
   * `view_images`：🆕 下载 Issue 报障截图（正文+评论全量识别并转为本地图片块，Agent 直接"看"截图）；落地目录 `~/.dsh/data/dsh-github-flow/images/`（内容寻址去重），**超 15MB 时按 mtime 自动 LRU 淘汰至 10MB 低水位**，并保护当前批次已写入的文件；测试可用 `DSH_IMAGE_DIR` 重定向该目录；
   * `attach_images`（参数）：🆕 支持本地文件/截图直接作为附件随 Issue 发布（单批上限 50 个文件，需 gh ≥ 2.99）。
+  * `body_file`（参数）：🆕 Issue 正文/评论正文可直接来自本地 md 文件，与 `body` 二选一；相对路径按当前工作区解析，文件须为合法 UTF-8，正文上限 65,536 字符，长正文不必读进上下文。
 
 ---
 
@@ -136,6 +171,8 @@ dsh plugin --profile web add dsh-github-flow
   * `list`：列出指定分支或状态的 CI 构建记录；
   * `view`：查看工作流运行详情与各步骤状态；
   * `log_failed`：**🔥 排障神器**！自动精准定位失败的 Job 与 Step，仅提取报错那几十行核心日志，告别人工翻几万行日志；
+    * 🆕 **按测试框架锚点萃取（v0.7.0 新增）**：不再把整段日志丢给模型。先按各框架的失败标记（pytest `FAILED`、node `AssertionError`、Go `panic:`、tsc `error TSxxxx`、`npm ERR!` 等）切出**失败块**（每块含起始行号与后续上下文，相邻标记自动合并），再按字符预算二次裁剪；块数超上限时显式写明「已省略 N 个失败块（共 M 个）」。**匹配不到已知锚点时回退尾部 200 行**并注明原因（失败结论在日志末尾，头部基本只有环境准备信息）。
+    * 为此 `log_failed` 的输出预算放宽到 **2MB 字符 / 8MB 字节**——否则默认 24K 截断会发生在萃取**之前**，后面的失败根本进不了上下文。
   * `rerun`：一键重新运行失败的构建；
   * `cancel`：取消正在排队或执行的构建；
   * `trigger`：手动触发 `workflow_dispatch` 工作流，支持自定义入参；
@@ -176,6 +213,7 @@ dsh plugin --profile web add dsh-github-flow
   * `list`：查看历史 Release 版本清单；
   * `view`：查看指定 Tag 的发布说明与附属构建资产清单；
   * `create`：创建新版本 Release（支持 `generate_notes` 自动从 commit 生成说明，支持 `draft` / `prerelease` / 预置资产上传）；
+  * `notes_file`（参数）：🆕 发版说明可直接来自本地 md 文件（替代 `notes`，映射 `--notes-file -`），与 `notes` 二选一；相对路径按当前工作区解析，文件须为合法 UTF-8（发版说明不套用正文的 65,536 字符上限，只有 4MB 文件字节护栏），长说明不必读进上下文；
   * `upload`：向已有 Release 追加上传本地资产（支持 `clobber: true` 覆盖上传，需 `confirm: true`）；
   * `download`：下载 Release 产物文件（支持 `pattern` glob 模式过滤）；
   * `delete`：删除 Release（支持 `cleanup_tag: true` 连同 Git Tag 一并清理，需 `confirm: true`）。
@@ -196,7 +234,10 @@ dsh plugin --profile web add dsh-github-flow
 
 ---
 
-### 7. `github_skill`：Agent Skills 生态发现与本地安装
+### 7. `github_skill`：Agent Skills 生态发现与本地安装 🧪 Preview
+
+> 🧪 **Preview 依赖**：底层是 `gh skill`，该命令当前为 public preview（`subject to change without notice`），命令面可能随 gh 升级变更。
+
 > **典型对话指令**：
 > - *"在 GitHub 开源社区检索关于 'markdown' 的 Agent Skills"*
 > - *"预览并安装 'github/awesome-copilot' 仓库里的代码审查 Skill 到当前项目"*
@@ -218,7 +259,7 @@ dsh plugin --profile web add dsh-github-flow
 > - *"调用 gh 命令报错 'authentication failed'，该怎么排查？"*
 
 * **支持操作 (`topic` / `gh_command`)**：
-  * `overview`：输出全景工具箱导航与核心职责速查（18 大工具矩阵全景）；
+  * `overview`：输出全景工具箱导航与核心职责速查（19 大工具矩阵全景）；
   * `mapping`：**官方命令映射总表**，精准指示任意 `gh <command>` 对应哪个插件工具，以及未覆盖域对应的 GitHub REST/GraphQL 端点；
   * `search_syntax`：日期区间、状态筛选与高级布尔搜索语法指南；
   * `troubleshooting`：常见错误自愈配方（认证失效、网络超时、SOCKS5 代理配置、权限不足等）；
@@ -273,7 +314,7 @@ dsh plugin --profile web add dsh-github-flow
 
 * **支持操作 (`action`)**：
   * `list`：盘点仓库 Actions 缓存占用，自动换算人性化体积（KB/MB/GB），支持 Key 前缀过滤、Git Ref 过滤与按大小/访问时间排序；
-  * `delete`：三态精准清理（按数字 `cache_id` 删除、按 `key` 删除、或通过 `all: true` 全量清空全部缓存；全量清空属批量破坏性操作，强制要求 `confirm: true`，底层注入 `--succeed-on-no-caches` 保证幂等执行）。
+  * `delete`：三态精准清理（按数字 `cache_id` 删除、按 `key` 删除、或通过 `all: true` 全量清空全部缓存；**三种方式均强制要求 `confirm: true`**，全量清空另注入 `--succeed-on-no-caches` 保证幂等执行）。
 
 ---
 
@@ -300,24 +341,30 @@ dsh plugin --profile web add dsh-github-flow
 
 * **支持操作 (`action`)**：
   * `view`：**账号维度跨仓一站式聚合大盘**（默认），汇总展示「指派给我的 Issue」、「指派给我的 PR」、「等待我评审的 PR (Review Requests)」、「提及我的消息 (Mentions)」以及「订阅仓库近期动态 (Repository Activity)」，无需绑定单仓即可一览全局工作台；支持 `-o` 组织过滤与 `-e` 排除噪音仓库；
-  * `health`：🆕 **工具链运行时健康度与降级率审计报表**：基于 Cordis `tools/result` 事件切面，实时审计全插件 18 大核心工具的调用总量、成功率、综合健康分（0~100 分）、API 降级率与智能自愈建议。
+  * `health`：🆕 **工具链运行时健康度与降级率审计报表**：基于 Cordis `tools/result` 事件切面，实时审计全插件 19 大核心工具的调用总量、成功率、综合健康分（0~100 分）、API 降级率与智能自愈建议。
 
 ---
 
-### 15. `github_agent_task`：云端编码智能体任务会话治理
+### 15. `github_agent_task`：云端编码智能体任务会话治理 🧪 Preview
+
+> 🧪 **Preview 依赖**：底层是 `gh agent-task`，该命令当前为 public preview（`subject to change without notice`），命令面可能随 gh 升级变更。
+
 > **典型对话指令**：
 > - *"查阅我名下所有的 GitHub Copilot 智能体任务会话列表"*
 > - *"检视任务 'e2fa49d2' 的执行状态，并抓取详细会话日志"*
 > - *"向云端 Agent 发起新任务：'重构网络通信模块以支持自动重试'，基于 develop 分支"*
 
 * **支持操作 (`action`)**：
-  * `list`：列出当前用户关联的智能体任务（支持 `-L/--limit` 与 `-R/--repo`）；
+  * `list`：列出当前用户关联的智能体任务（支持 `-L/--limit`；`gh agent-task list` 不支持 `-R/--repo`，该参数对本动作无效）；
   * `view`：查看任务详情与会话执行日志（支持 `--log`，强制校验 `task_id` 防交互挂起）；
   * `create`：向云端 Agent 派发新编码/重构任务（支持 `-b/--base` 指定基准分支，`-a/--custom-agent` 指定仓库智能体定义）。
 
 ---
 
-### 16. `github_discussion`：团队技术研讨与开源社区 RFC 闭环
+### 16. `github_discussion`：团队技术研讨与开源社区 RFC 闭环 🧪 Preview
+
+> 🧪 **Preview 依赖**：底层是 `gh discussion`，该命令当前为 public preview（`subject to change without notice`），命令面可能随 gh 升级变更。
+
 > **典型对话指令**：
 > - *"查看当前仓库分类为 'Ideas' 的开放讨论列表"*
 > - *"查看讨论 #101 的正文内容与回复楼层"*
@@ -379,6 +426,7 @@ dsh plugin --profile web add dsh-github-flow
 * **三维待办 Issue 矩阵**：智能划分「📥 用户提单（反馈到我名下仓库）」、「🎯 指派待办（分配给我）」与「✍️ 我发起的」，支持一键药丸过滤；
 * **🔀 PR 在线审阅工作台**：点击任意 PR，无需离开 DSH 即可查看作者与分支流向、CI/审查状态、Markdown 描述、评论时间线，以及变动文件列表与高保真 Unified Diff 对比（按文件内存切片，切换文件 0ms）；
 * **📝 Issue 在线查看弹窗**：点击任意 Issue 直接查看完整讨论——正文与评论均为 Markdown 渲染、长内容自动折叠、被 GitHub 折叠的垃圾评论显式标注、标签色块/指派人/里程碑/子议题进度/关联 PR 一目了然，评论时间线按时间顺序完整呈现；
+* **⚡ Actions Run 在线详情**：点击右侧栏 Actions 卡片即可查看本次运行的 workflow / 分支 / 提交 / 触发事件 / 耗时，以及完整 job / step 树（每步结论与耗时、失败步骤高亮、默认展开第一个失败 job）；失败时按需提取日志锚点片段（一次最多 3 个失败 job、服务端批次预算 90 秒、客户端 100 秒自动中止），右侧 `GitHub ↗` 保留完整日志直达；
 * **升级提示横幅**：检测到新版本时在顶部优雅滑出，提供一键自动升级与更新日志直达。
 
 <p align="center">
@@ -402,10 +450,11 @@ dsh plugin --profile web add dsh-github-flow
     * 默认展示 15 条，支持**向下滑动触底自动分页加载**（伴随 `15 / 74` 实时进度提示与点击后备）；
     * 右上角锚定最新发布 Release 徽章（`🏷️ v0.4.0`），悬停查看发布时间与预发布标示，点击直达；
     * **提交详情模态弹窗**：点击任意提交记录行，在右侧栏内局部居中弹出，内置上下滑动区域，完整展示 40 位 SHA、提交者姓名邮箱、日期、多行详细正文说明与文件变更统计（`--stat`），纯本地 0ms 秒开，支持按 `Esc` 或点击遮罩随时关闭；
+    * **文件 Diff 弹窗预览**：点击提交详情里的文件变更统计行，或未提交清单中的任意文件，均可弹出该文件的 Unified Diff（整包 patch 由前端按 `diff --git` 按文件切分、重命名路径自动归一、正文里的 `---`/`+++` 不会误判成文件头、超长补丁按文件边界截断），弹窗可叠加在提交详情之上（Esc 逐层关闭），支持复制原文与「在 DSH 中打开」源码；
   * **未提交清单 (`📁 未提交 (N)`)**：展示工作区未提交的文件清单，状态码色彩区分（`??` 新增、`M` 修改、`D` 删除、`R` 重命名）与变更总数；
   * **拉取请求 (`🔀 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）；
+  * **构建流水线 (`⚡ Actions (N)`)**：实时关注工作流 CI 状态，展示触发方式（`push`/`定时`/`手动`/`PR`）与相对时间；**点击卡片在线查看本次运行的 job / step 树与失败步骤**（失败步骤高亮、默认展开第一个失败 job），失败时可按需提取日志锚点片段（一次最多 3 个失败 job、批次预算 90 秒，不用切浏览器），右侧 `GitHub ↗` 保留完整日志直达，并给出可直接交给 Agent 的 `diagnose_ci` 诊断指引（嵌入 run_id）；
 * **⚙️ 完整设置入口**：右侧栏提供设置按钮，与主页复用同一设置弹窗（数据同步 / 网络代理 / 更新设置 / 关于 四分区完整可用），无需切回主页调整。
 
 <p align="center">
@@ -414,10 +463,10 @@ dsh plugin --profile web add dsh-github-flow
 
 ### 3. 使用指南大窗口 (Help & Playbook)
 点击驾驶舱右上角 **`[📖 使用指南]`**（或右侧栏的 ❓ 按钮）打开 920px 宽屏沉浸式手册，按 Esc 或点遮罩即可关闭。共 5 个分类：
-* **🚀 3分钟极速上手**：登录确认 → 绑定仓库 → 向 Agent 下指令的三步闭环，附能力总览（18 工具 / 103 业务动作 / 2 套工作台）；
+* **🚀 3分钟极速上手**：登录确认 → 绑定仓库 → 向 Agent 下指令的三步闭环，附能力总览（19 工具 / 106 业务动作 / 2 套工作台）；
 * **🤖 Agent 提示词实战**：7 大高频场景（建 PR、CI 排障、待办盘点、Diff 审查、看图定位、批量标签治理、RFC 研讨），每条配「📋 一键复制 Prompt」；
 * **🖥️ 两大界面操作图解**：主面板 4 标签与右侧栏 5 Tab 的逐项说明，以及两个弹窗的通用操作习惯；
-* **🧰 18 大工具速查**：按「日常研发 / 交付配置 / 生态协作 / 兜底元能力」四组列出全部工具与动作，附 `/gh` 指令速查；
+* **🧰 19 大工具速查**：按「日常研发 / 交付配置 / 生态协作 / 兜底元能力」四组列出全部工具与动作，附 `/gh` 指令速查；
 * **🔑 常见自愈排错**：登录、权限 Scope、24h 安全保护期、代理抖动、列表为空、为何需重启 DSH 共 6 条。
 
 > 同一套知识也通过 `github_help` 工具提供给 Agent——两侧口径由 phase33 测试强制对账，代码演进而文档没跟上会直接测试失败。
@@ -435,7 +484,7 @@ dsh plugin --profile web add dsh-github-flow
 * **本地缓存可视化管理**：透明查看本地快照体积与保存时间戳，支持一键 `[🗑️ 清空缓存]` 重置。
 
 **🌐 网络代理分区**——让插件全部外联流量走你的代理：
-* **全局生效范围**：设置后驾驶舱、右侧栏面板、9 大 Agent 工具调用与一键升级链路全部经代理访问；未启用时默认使用系统环境代理（`HTTPS_PROXY` 等）或直连；
+* **全局生效范围**：设置后驾驶舱、右侧栏面板、19 大 Agent 工具调用与一键升级链路全部经代理访问；未启用时默认使用系统环境代理（`HTTPS_PROXY` 等）或直连；
 * **协议支持**：`http://` / `https://` / `socks5://` / `socks5h://`（gh 与 npm 链路原生支持 SOCKS5；`socks5h` 会把域名解析也交给代理端，抗 DNS 污染更强；npm 版本探测走 Node fetch 暂不支持 SOCKS，将保持直连并在界面如实标注）；
 * **`[🧪 测试连通性]`**：一键探测经当前代理访问 GitHub API 的延迟；
 * **保存即生效**：写入 `~/.dsh/data/dsh-github-flow/proxy.json` 持久化（DSH 重启自动恢复），无需重启、不重载插件；
@@ -533,8 +582,18 @@ dsh plugin --profile web add dsh-github-flow
     updateCheckIntervalMs: 86400000 # 检查更新间隔（毫秒，默认 24 小时）
     registryUrl: ''           # 自定义私有 npm 镜像地址（留空走「更新设置」所选源，界面设置优先）
     proxyUrl: ''              # 代理地址预置默认值（如 'http://127.0.0.1:7890'；仅未在驾驶舱设置过时生效，界面设置优先）
+    toolsets: ['core']        # 工具档位：留空/full = 19 个全量；core=3 / ci=7 / maintain=8；也可混写工具名如 github_pr
+    read_only: true           # 只读档位：写 action 在注册期就从工具 schema 中剔除，github_api 整体不注册
 ```
 
+> `toolsets` 决定的不是「运行时允许什么」，而是**注册给模型的工具面本身**：不填 = 19 个工具全量常驻（约 27,000 字符 schema），`core` 只有 3 个（约 4,400 字符，**省 84%**）。填错档位名会 `console.warn` 打出可用档位清单，不会静默把工具清空。
+> `read_only` 是硬语义，两层生效：① 注册期把写 action 从参数 `enum` 里剪掉（模型在 schema 层看不到）；② **执行入口再拦一次**——本插件用的是手写 descriptor，宿主不会替我们做参数校验，所以被剪掉的 action 即使带着 `confirm: true` 也会在到达 `gh` 之前被拒绝并抛出「只读模式」。`github_api` 因端点与 method 均可任意而无法降级，只读模式下整体不注册。
+> 边界说明：`github_help` 的帮助文本是一份**文档**，只读模式下仍会列出全部能力（含写操作的用法），它不构成可执行的契约——真正拦住写操作的是上面那两层。
+
+
+> 配置由 Schemastery Schema 校验：类型写错（例如把 `maxOutputChars: '24000'` 写成字符串）会**直接报错**，不再静默回落到默认值。
+> `maxOutputChars` / `defaultTimeoutMs` / `defaultListLimit` 是**热更新字段**——改这几项时 loader 只把新值热提交进运行中的实例，不触发插件整体重载；改动其余字段（含 `checkUpdate`）仍会重载插件。
+
 ---
 
 ## 🔌 生态服务扩展 (Cordis Service)
@@ -543,10 +602,12 @@ dsh plugin --profile web add dsh-github-flow
 
 ```typescript
 import type { Context } from '@deepseek-ai/cordis';
+// 可选但推荐：加载本插件随包发布的声明合并，ctx.github 才有完整类型与自动补全
+import type {} from 'dsh-github-flow/host';
 
 export const inject = ['github'];
 
-export function apply(ctx: Context) {
+export async function apply(ctx: Context) {
   // 直接调用经过安全包装的底层执行引擎
   const auth = await ctx.github.checkAuth();
   const repo = await ctx.github.getRepoMetadata();
@@ -556,6 +617,35 @@ export function apply(ctx: Context) {
 
 ---
 
+## 🛠️ 本地开发与联调热重载 (Local Development)
+
+若需要基于源码进行二次开发或定制调试，请遵循以下联调规范：
+
+### 1. 链接工作区到 DSH 环境（创建目录联接）
+DSH 的 Profile 默认会将 `file:` 依赖打包拷贝为静态快照，且受 pnpm 构建安全策略拦截。为了让源码构建后**即时生效**，推荐使用原生目录联接（Junction）直通工作区：
+
+```powershell
+# Windows PowerShell（将 Profile 内部插件路径直连到本地开发仓库根目录）
+New-Item -ItemType Junction -Path "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-github-flow" -Target "D:\Desktop\AgentWork\DSHQuestion\dsh-github-flow" -Force
+```
+
+> ⚠️ **避坑说明**：建立联接后，**请勿在 Profile 目录下执行** `dsh plugin ... install/add` 或 `pnpm install`，以防包管理器抹除联接并退化为静态快照。
+
+### 2. 源码修改后的生效工作流
+
+修改 `src/` 源码后，无需重新挂载或拷贝文件：
+
+1. **编译产物**：在工作区根目录执行：
+   ```bash
+   pnpm run build
+   ```
+   > 产物自动编译并聚合至 `lib/`，Junction 会使宿主环境立即读取到最新文件。
+2. **触发刷新**：
+   - **前端界面与样式**（`src/client.ts`、`src/ui/*`）：直接在浏览器中按 **Ctrl + F5 强制刷新**页面即可预览最新视图，**无需重启 DSH 软件**。
+   - **后端引擎与接口路由**（`src/tools/*`、`src/api/*`、`src/executor.ts`、`src/main.ts`）：**重启 DSH 软件**以重载 Node.js 内存中的常驻模块。
+
+---
+
 ## 📚 相关开发文档
 
 - [npm 发布与自动化 CI 发版指南](./docs/npm-publish-guide.md)