dsh-github-flow 0.1.0 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH Contributor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,119 @@
+# DSH GitHub Flow (`dsh-github-flow`)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-github-flow"><img src="https://img.shields.io/npm/v/dsh-github-flow.svg?style=flat-square&color=0969da" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/dsh-github-flow"><img src="https://img.shields.io/npm/dm/dsh-github-flow.svg?style=flat-square&color=2ea043" alt="npm downloads" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
+  <a href="https://deepseek-harness.github.io/deepseek-harness/"><img src="https://img.shields.io/badge/Cordis-Compatible-8957e5.svg?style=flat-square" alt="Cordis" /></a>
+</p>
+
+<p align="center">
+  <b>Modern, native GitHub workflow integration plugin for DeepSeek Harness (DSH) powered by GitHub CLI (<code>gh</code>).</b><br>
+  Deeply connects local Git repository development with remote GitHub collaboration (PRs, Issues, Actions CI diagnosis, and code reviews), featuring Agent model tools, human slash commands, and dual native Web UI views.
+</p>
+
+<p align="center">
+  <b><a href="./README.md">简体中文</a></b> | <b>English</b>
+</p>
+
+---
+
+## 🌟 Key Features
+
+1. **Zero-Configuration Authentication**:
+   - Seamlessly reuses existing host credentials from `gh auth login` (OAuth tokens / system Keyrings) without exposing plain-text Personal Access Tokens (PATs) in DSH.
+2. **Deep Workspace Affinity (CWD Binding)**:
+   - Automatically scopes commands to the active session workspace. `gh` resolves the remote repository and current Git branch automatically, saving model tokens from redundant `owner/repo` arguments.
+3. **High Signal-to-Noise Ratio & Token Budget Protection**:
+   - Consolidates over 70+ scattered micro-tools into **5 focused domain tools**.
+   - Queries use `--json <fields>` projections by default; long diffs and failed CI logs are safely truncated (default 24KB) to protect the model's context window.
+4. **Dual Native Web UI Views**:
+   - **Global Cockpit** (`sidebar.panellist`, Order 20): Account-wide repository overview, local workspace matrix, and pending personal PRs/issues.
+   - **Right Sidebar Panel** (`sidebarRightTabs`, Order 40): Shows current repository status, PR list with CI check pills, and quick action buttons inside the session.
+5. **Standard Cordis Microkernel Compliance**:
+   - Exposes native `GitHubService` (`ctx.github`) for ecosystem extensibility;
+   - Strongly typed runtime validation via Schemastery (`Config`);
+   - Domain event broadcasting (`github/pr:create`, `github/issue:create`).
+
+---
+
+## 🚀 Installation
+
+Run in your DSH terminal to install directly from npm:
+
+```bash
+# Install to desktop profile
+dsh plugin --profile desktop add dsh-github-flow
+
+# Or install to web profile
+dsh plugin --profile web add dsh-github-flow
+```
+
+---
+
+## 🛠️ Agent Tools Reference
+
+| Tool Name | Actions | Typical Use Cases |
+|---|---|---|
+| `github_pr` | `list`, `view`, `create`, `diff`, `checks`, `review`, `merge` | Inspect PR details, verify CI checks, conduct code reviews, merge pull requests |
+| `github_issue` | `list`, `view`, `create`, `comment`, `close`, `reopen` | Search and view issues, create issues, add comments |
+| `github_run` | `list`, `view`, `log_failed`, `rerun`, `cancel` | Monitor Actions workflows; `log_failed` extracts failure logs for automatic fixes |
+| `github_repo` | `view`, `search_code`, `search_repos` | Query repository metadata, search cross-repo code |
+| `github_api` | Any GitHub REST / GraphQL endpoint | Universal escape hatch for custom queries (supports `--jq`) |
+
+---
+
+## 💬 Human Slash Commands
+
+In any DSH chat prompt:
+- `/gh status`: Check current GitHub CLI authentication status, granted scopes, and active repository;
+- `/gh help`: Display quick reference and help information.
+
+---
+
+## ⚙️ Configuration
+
+Customize options in your `cordis.patch.yml` or profile:
+
+```yaml
+- insert:
+    - id: github-flow
+      name: dsh-github-flow
+      config:
+        ghPath: 'gh'              # Custom path to gh binary
+        defaultTimeoutMs: 30000   # Timeout in milliseconds
+        maxOutputChars: 24000     # Maximum characters per output (Token guard)
+        cacheTtlMs: 15000         # Web overview cache time
+        defaultListLimit: 20      # Default page size
+```
+
+---
+
+## 🔌 Ecosystem Service Extension (Cordis Service)
+
+Other DSH plugins can consume GitHub CLI capabilities via dependency injection:
+
+```ts
+import type { Context } from '@deepseek-ai/cordis';
+
+export const inject = ['github'];
+
+export function apply(ctx: Context) {
+  // Directly invoke the underlying secure execution engine via ctx.github
+  const auth = await ctx.github.checkAuth();
+  const repo = await ctx.github.getRepoMetadata();
+}
+```
+
+---
+
+## 📚 Documentation
+
+- [npm Publishing & Maintenance Guide](./docs/npm-publish-guide.md)
+- [Architecture & Design Specifications](./docs/architecture.md)
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](./LICENSE).

package/README.md

@@ -1,7 +1,20 @@
 # DSH GitHub Flow (`dsh-github-flow`)
 
-基于 GitHub CLI (`gh`) 为 DeepSeek Harness (DSH) 打造的现代化原生集成插件。  
-深度打通本地 Git 仓库开发与远程 GitHub 协作（PR、Issue、Actions CI 诊断与代码审查），兼备 Agent 模型工具、人类 Slash 指令以及原生 Web UI 双重视图（主驾驶舱与右侧栏快捷面板）。
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-github-flow"><img src="https://img.shields.io/npm/v/dsh-github-flow.svg?style=flat-square&color=0969da" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/dsh-github-flow"><img src="https://img.shields.io/npm/dm/dsh-github-flow.svg?style=flat-square&color=2ea043" alt="npm downloads" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="license" /></a>
+  <a href="https://deepseek-harness.github.io/deepseek-harness/"><img src="https://img.shields.io/badge/Cordis-Compatible-8957e5.svg?style=flat-square" alt="Cordis" /></a>
+</p>
+
+<p align="center">
+  <b>基于 GitHub CLI (<code>gh</code>) 为 DeepSeek Harness (DSH) 打造的现代化原生工作流集成插件。</b><br>
+  深度打通本地 Git 仓库开发与远程 GitHub 协作（PR、Issue、Actions CI 诊断与代码审查），兼备 Agent 模型工具、人类 Slash 指令以及原生 Web UI 双重视图。
+</p>
+
+<p align="center">
+  <b>简体中文</b> | <b><a href="./README.en.md">English</a></b>
+</p>
 
 ---
 
@@ -10,12 +23,12 @@
 1. **零鉴权配置，开箱即用**：
    - 自动复用宿主机已通过 `gh auth login` 认证的登录凭据（OAuth Token / 系统 Keyring），无需在 DSH 中存储任何明文 GitHub PAT。
 2. **工作区目录深度亲和 (CWD 绑定)**：
-   - 自动继承当前会话所在的 Workspace 物理目录，`gh` 自动识别当前 Git 仓库与本地工作分支，无需 Agent 每次传参 `owner/repo`。
+   - 自动继承当前会话所在的 Workspace 物理目录，`gh` 自动识别当前 Git 仓库与本地工作分支，无需 Agent 每次显式传递 `owner/repo`。
 3. **高信噪比与 Token 防溢出治理**：
-   - 拒绝 70+ 个碎片化微型工具撑爆上下文，聚合为 **5 大领域核心 Tool**。
+   - 拒绝 70+ 个碎片化微型工具撑爆上下文，收敛聚合为 **5 大领域核心 Tool**。
    - 所有查询原生采用 `--json <fields>` 按需返回；对 `diff`、`log_failed` 设置安全截断保护（默认 24KB），防止模型上下文窗口溢出崩溃。
-4. **原生双重视图（驾驶舱与右侧栏）**：
-   - **全局驾驶舱**（主导航栏 `sidebar.panellist`，Order 20）：展示账号全局仓库、本地工作区矩阵、个人待办 PR 与 Issues；
+4. **原生 Web UI 双重视图**：
+   - **全局驾驶舱**（主导航栏 `sidebar.panellist`，Order 20）：透视账号全局仓库、本地工作区矩阵、个人待办 PR 与 Issues；
    - **右侧栏工作区面板**（`sidebarRightTabs`，Order 40）：在会话引导页与右侧抽屉常驻呈现当前仓库的 PR 列表、Checks 状态药丸与快捷操作。
 5. **符合 Cordis 官方微内核架构**：
    - 暴露原生 `GitHubService`（`ctx.github`），允许生态其他插件复用；
@@ -24,32 +37,16 @@
 
 ---
 
-## 📦 项目结构
-
-```text
-dsh-github-flow/
-├── package.json              # 模块定义、Cordis bundle 声明及 peerDependencies
-├── cordis.patch.yml          # DSH Profile 自动装配补丁（含默认配置项）
-├── tsconfig.json             # TypeScript 编译配置
-├── README.md                 # 插件说明文档
-├── icon.svg                  # 官方矢量微渐变包图标
-├── src/
-│   ├── index.ts              # Host 插件主入口：apply(ctx) 生命周期、服务挂载与 Config Schema
-│   ├── service.ts            # Cordis 原生 GitHubService 抽象
-│   ├── types.ts              # 数据结构、事件定义与接口类型
-│   ├── executor.ts           # 底层 gh 执行引擎（execFile 参数数组隔离、防注入、超时与截断）
-│   ├── commands/
-│   │   └── gh.ts             # 人类交互斜杠命令 (/gh status, /gh help)
-│   ├── api/
-│   │   └── routes.ts         # 面向 Web 视口的 Host HTTP 路由 (/api/github/*，受 effect 生命周期管理)
-│   ├── tools/                # Agent 模型工具集（规范化 defineTool DSL）
-│   │   ├── pr.ts             # github_pr: PR 查看、比对、Checks、评审与合并
-│   │   ├── issue.ts          # github_issue: Issue 检索、创建、追加评论、关闭
-│   │   ├── run.ts            # github_run: Actions CI 监控与 --log-failed 报错定位
-│   │   ├── repo.ts           # github_repo: 仓库元数据与跨仓库搜索
-│   │   └── api.ts            # github_api: 万能 REST/GraphQL 逃生门
-│   └── client.ts             # Client 页面扩展：注册右侧栏 tab 与主面板视口
-└── lib/                      # TypeScript 编译输出产物（双端 ESM）
+## 🚀 安装指南
+
+在 DSH 终端执行以下命令直接从 npm 安装：
+
+```bash
+# 安装到桌面端 Profile
+dsh plugin --profile desktop add dsh-github-flow
+
+# 或者安装到 Web Profile
+dsh plugin --profile web add dsh-github-flow
 ```
 
 ---
@@ -110,21 +107,13 @@ export function apply(ctx: Context) {
 
 ---
 
-## 🖥️ 页面安装与体验
-
-1. **依赖前提**：
-   宿主机已安装 GitHub CLI (`gh`) 并已登录：
-   ```bash
-   gh auth status
-   ```
-2. **在 DSH 中安装与挂载**：
-   通过 DSH Profile 配置加载本插件 bundle：
-   ```yaml
-   # cordis.patch.yml
-   - insert:
-       - id: github-flow
-         name: dsh-github-flow
-   ```
-3. **界面体验**：
-   - **右侧栏**：在右侧抽屉常驻呈现当前仓库的 PR、CI 状态药丸与快捷操作按钮；
-   - **主视口**：左侧导航栏点击 GitHub 图标进入全局驾驶舱。
+## 📚 开发与维护文档
+
+- [npm 发布与版本维护指南](./docs/npm-publish-guide.md)
+- [架构设计与技术规范](./docs/architecture.md)
+
+---
+
+## 📄 开源协议 (License)
+
+本项目基于 [MIT License](./LICENSE) 协议开源。

package/cordis.patch.yml

@@ -1,7 +1,3 @@
 - insert:
-    - id: github-flow
-      name: dsh-github-flow
-      config:
-        defaultTimeoutMs: 30000
-        maxOutputChars: 24000
-        cacheTtlMs: 15000
+    - id: github-flow-v3
+      name: 'D:/Desktop/AgentWork/DSHQuestion/dsh-github-flow/lib/main.js'

package/docs/architecture.md

@@ -0,0 +1,69 @@
+# DSH GitHub Flow 架构与设计规范 (Architecture & Specs)
+
+`dsh-github-flow` 是为 DeepSeek Harness (DSH) 打造的原生 GitHub 工作流集成插件，基于底层 Cordis 微内核架构与宿主机原生 GitHub CLI (`gh`) 构建。
+
+---
+
+## 1. 架构全景图
+
+```text
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                             DeepSeek Harness Host                           │
+│                                                                             │
+│  ┌────────────────────────┐                   ┌──────────────────────────┐  │
+│  │   Cordis Context (ctx) │                   │      PluginConfig        │  │
+│  │                        │                   │(Schemastery 运行时校验)   │  │
+│  └───────────┬────────────┘                   └─────────────┬────────────┘  │
+│              │                                              │               │
+│              ▼                                              ▼               │
+│     ┌──────────────────────────────────────────────────────────────┐        │
+│     │               GitHubService (ctx.github 原生服务)             │        │
+│     │   - checkAuth(cwd)      - getRepoMetadata(cwd)               │        │
+│     │   - run<T>(args, opts)  [execFile 数组隔离 + 24KB 智能截断]     │        │
+│     └──────┬───────────────────────┬────────────────────────┬──────┘        │
+│            │                       │                        │               │
+│            ▼                       ▼                        ▼               │
+│  ┌──────────────────┐    ┌──────────────────┐    ┌───────────────────────┐  │
+│  │  5 大 Agent 工具  │    │  人类 Slash 指令 │    │   Host HTTP WebServer │  │
+│  │  (defineTool DSL)│    │  /gh status|help │    │ (Effect Disposer 清理)│  │
+│  │  - pr            │    └──────────────────┘    │ - /api/github/overview│  │
+│  │  - issue         │                            │ - /api/github/action  │  │
+│  │  - run           │                            │ - /api/github/refresh │  │
+│  │  - repo          │                            └──────────┬────────────┘  │
+│  │  - api (逃生门)  │                                       │               │
+│  └──────────────────┘                                       │ HTTP API      │
+└─────────────────────────────────────────────────────────────┼───────────────┘
+                                                              │
+┌─────────────────────────────────────────────────────────────┼───────────────┐
+│                        DSH Web Client                       ▼               │
+│                                                                             │
+│   ┌──────────────────────────────────┐    ┌─────────────────────────────┐   │
+│   │       全局驾驶舱 (Main Slot)      │    │  右侧栏面板 (Right Sidebar)  │   │
+│   │   - 账号全局所有 GitHub 仓库      │    │  - 当前会话工作区关联仓库   │   │
+│   │   - 本地工作区矩阵透视           │    │  - PR 列表与 CI Checks 药丸 │   │
+│   │   - 个人待办 PRs & Issues        │    │  - 快速创建 PR / Issue      │   │
+│   └──────────────────────────────────┘    └─────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 核心设计原则
+
+### 2.1 零凭证侵入 (Zero-Credential Store)
+- 严禁在 DSH 内部配置或持久化存储任何 GitHub PAT 明文密钥；
+- 直接复用宿主机由 `gh auth login` 认证的安全凭证（系统 Keychain / Windows Credential Manager / 系统的加密存储）；
+- 天然支持多账号、企业 GitHub (GH Enterprise) 以及各种 OAuth 作用域。
+
+### 2.2 工作区 CWD 亲和 (Workspace Affinity)
+- 会话内的所有命令默认在当前 Agent 会话物理目录（`cwd`）执行；
+- `gh` 引擎自动逆向推导关联的远程仓库（识别 `origin` 或 `github` remote），免去大模型每次必须传递 `owner/repo` 的繁重上下文负担。
+
+### 2.3 上下文 Token 保护 (Token Budget Guard)
+- 所有的 `gh` 查询原生采用 `--json <fields>` 结构化投影；
+- 对长文本输出（如大型 PR 的完整 `diff`、CI 失败步骤日志）设置安全截断阈值（默认 24KB），保留头尾关键上下文并添加显式截断标记，杜绝撑爆模型上下文。
+
+### 2.4 Cordis 微内核标准规范
+- **硬依赖解耦**：顶层仅强依赖 `['tools']`，Web 服务与命令服务采用动态作用域注入，在纯终端 / Headless 模式下零卡死；
+- **生命周期 Effect 闭环**：所有 HTTP 路由与命令注册均持有 Disposer 清理函数，插件热重载或重新挂载时自动彻底注销，零内存泄漏；
+- **配置自校验**：基于 `@deepseek-ai/schemastery` 实现强类型声明与运行时校验。

package/docs/npm-publish-guide.md

@@ -0,0 +1,100 @@
+# npm 发布与 GitHub Release 自动化发版指南
+
+本文档详细记录 `dsh-github-flow` 插件在 npm 公共注册表（[https://www.npmjs.com/package/dsh-github-flow](https://www.npmjs.com/package/dsh-github-flow)）以及 GitHub Releases 上的发布流程、鉴权策略、版本规范，以及基于 **GitHub Actions 实现全自动构建、测试、推送 npm 与同步发布 GitHub Release** 的具体触发规则与安全机制。
+
+---
+
+## 1. GitHub Actions 自动化流水线架构与触发规则
+
+本项目已在 [`.github/workflows/npm-publish.yml`](../.github/workflows/npm-publish.yml) 中配置了工业级的自动化 CI/CD 发包流水线（`Release & Publish to npm`）。
+
+### 1.1 触发规则深度剖析 (Trigger Rules)
+
+流水线设计了 **两种触发模式**，兼顾了版本规范性与调试灵活性：
+
+| 触发模式 | 触发条件 | 语法定义 | 自动化执行内容 | 适用场景与安全保障 |
+| :--- | :--- | :--- | :--- | :--- |
+| **模式 A：Git Tag 语义化标签触发（推荐生产）** | 推送符合 `v*` 规则的版本标签 | `on.push.tags: ['v*.*.*', 'v*']` | **全套发布**：检出源码 ➔ 安装依赖 ➔ 全量构建 ➔ 校验产物 ➔ **带 Provenance 签名发布 npm** ➔ **自动创建并发布 GitHub Release（自动生成 Release Notes）** | **生产标准**：日常分支开发、合并 PR **不会**触发发包，彻底避免因版本号未变导致 npm 403 冲突；仅当打上发布标签时精准触发。 |
+| **模式 B：手动调度触发（Workflow Dispatch）** | GitHub 网页 Actions 面板手动点击 | `on.workflow_dispatch` | **按需执行**：支持勾选 `dry_run`（预演模式），在不实际发布到 npm 与 Release 的情况下完整跑通 build 与打包流水线。 | **排错与测试**：用于在合入代码后快速验证 CI 构建与 npm 打包能否顺利通过。 |
+
+#### 为什么不采用「代码 push 到 master 分支就自动发包」？
+1. **npm 版本的不可篡改性**：npm 绝对禁止覆盖已发布的相同版本号。若每次 git push master 均发包，一旦开发者忘记递增 `package.json` 中的 `version`，CI 必定直接报错失败；
+2. **发布意图明确**：通过 `git tag v0.1.1` 将代码快照、GitHub Release 与 npm 注册表版本三者完全对齐（1:1:1 映射），符合开源软件主流最佳实践。
+
+---
+
+### 1.2 GitHub 仓库密钥配置 (One-Time Setup)
+
+在自动化工作流执行前，只需在 GitHub 仓库中配置一次 npm Token：
+
+1. **获取 npm Granular Access Token**：
+   - 登录 npm 访问：[https://www.npmjs.com/settings/~/tokens/create](https://www.npmjs.com/settings/~/tokens/create)；
+   - 权限选择：**Packages and scopes** 勾选 `Read and write`；
+   - **关键勾选**：勾选 **`Bypass two-factor authentication (2FA) for publishing`**；
+   - 复制生成的 `npm_xxxxxxxxxxxx` 密匙。
+2. **存入 GitHub Secrets**：
+   - 打开 GitHub 仓库页面 ➔ 点击 **Settings** ➔ **Secrets and variables** ➔ **Actions**；
+   - 点击 **New repository secret**：
+     - **Name**：`NPM_TOKEN`
+     - **Secret**：粘贴你刚刚复制的 `npm_` Token；
+   - 点击 **Add secret** 保存。
+
+> 注：创建 GitHub Release 使用的是 GitHub 官方内置的 `secrets.GITHUB_TOKEN`，工作流中已声明 `permissions.contents: write`，无需额外配置任何第三方 Personal Access Token。
+
+---
+
+### 1.3 自动发布操作三步走 (发布新版本日常流程)
+
+配置好上述 Secret 后，日常发布新版本只需在本地终端运行：
+
+```bash
+# 第一步：递增版本号（自动修改 package.json 并生成对应 git commit 和 git tag）
+npm version patch   # 修补 Bug: 0.1.0 -> 0.1.1
+# 或者 npm version minor # 新增特性: 0.1.0 -> 0.2.0
+
+# 第二步：将代码与标签推送到 GitHub
+git push origin master --tags
+```
+
+**推送完成后**：
+- GitHub Actions 会在 5 秒内自动感知到 `v0.1.1` 标签被创建；
+- 启动 Ubuntu runner，全自动执行：
+  `检出代码 ➔ 安装 pnpm ➔ 安装依赖 ➔ pnpm run build (编译 + 清理) ➔ 产物完整性校验 ➔ 带 Provenance 签名发布到 npm ➔ 自动创建并发布对应 GitHub Release`；
+- 约 1 分钟后，npm 官网版本与 GitHub 仓库 Releases 页面同步更新！
+
+---
+
+## 2. 安全机制与 Provenance 产物溯源
+
+流水线中配置了 `permissions.id-token: write` 与 `--provenance` 参数：
+- **软件供应链安全**：通过 GitHub OIDC 向 npm 提供加密的签名凭据；
+- **官方认证徽章**：发布到 npm 后的包页面将自动挂上绿色的 **`Verified`** 徽章，向用户证明此版本由 GitHub Actions 在干净沙箱中从本开源仓库公开构建产出，杜绝后门与供应链投毒。
+
+---
+
+## 3. 本地手动备用发布流程 (Local Fallback)
+
+若遇到 GitHub Actions 宕机或需要紧急本地直发，可按以下流程：
+
+```bash
+# 1. 编译
+pnpm run build
+
+# 2. 本地绑定 Token
+npm config set //registry.npmjs.org/:_authToken=npm_你的Token
+
+# 3. 本地直接发布
+npm publish --access public
+```
+
+---
+
+## 4. 常见问题排查 (Troubleshooting)
+
+### Q1: GitHub Actions 报错 `npm error code E403: Forbidden - Two-factor authentication...`
+- **原因**：GitHub Secrets 中的 `NPM_TOKEN` 未勾选 `Bypass two-factor authentication (2FA) for publishing`。
+- **解法**：在 npm 重新生成勾选了 Bypass 2FA 的 Granular Access Token，并更新 GitHub 仓库里的 `NPM_TOKEN` Secret。
+
+### Q2: 报错 `403 You cannot publish over the previously published versions`
+- **原因**：当前打 tag 的代码版本在 `package.json` 中的 `version` 已经被发布过了。
+- **解法**：本地执行 `npm version patch` 递增版本号后再重新打 tag 推送。

package/lib/api/routes.d.ts

@@ -1,3 +1,2 @@
 import type { GhExecutor } from '../executor.js';
-import type { PluginConfig } from '../types.js';
-export declare function registerApiRoutes(ctx: any, executor: GhExecutor, config?: PluginConfig): void;
+export declare function registerApiRoutes(webServerService: any, executor: GhExecutor, workspaceRegistry?: any): void;