dsh-github-flow 0.3.0 → 0.5.0

package/lib/tools/gist.js

@@ -0,0 +1,190 @@
+import { renderGistMarkdown, parseGistListOutput } from '../renderers/markdown.js';
+export function createGistTool(executor) {
+    return {
+        name: 'github_gist',
+        description: '管理 GitHub Gist 代码片段与诊断留痕：查看 Gist 列表、检视代码正文 (view)、通过文本内容或本地文件创建新 Gist (create，默认安全 secret 模式)、编辑以及安全删除。删除操作不可逆，需 confirm: true。',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['list', 'view', 'create', 'edit', 'delete'],
+                    description: 'Gist 操作类型。list 查看列表、view 查看正文、create 新建、edit 修改、delete 物理删除（需 confirm）。',
+                },
+                gist_id: {
+                    type: 'string',
+                    description: 'Gist 唯一 ID 或完整 URL（view, edit, delete 动作必需，例如 "5b0e0062eb8e9654adad7bb1d81cc75f"）。',
+                },
+                filename: {
+                    type: 'string',
+                    description: '文件名（view 动作指定查看文件、create 动作命名单文件、edit 动作指定编辑文件；默认 "snippet.txt"）。',
+                },
+                files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '本地文件路径列表（create 动作上传多文件时使用）。',
+                },
+                content: {
+                    type: 'string',
+                    description: '代码片段或文本正文内容（create 动作直接传正文时使用，通过 stdin 安全管道传入）。',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Gist 描述摘要或用途备注（create, edit 动作可选）。',
+                },
+                public: {
+                    type: 'boolean',
+                    description: '是否公开创建为 Public Gist（create 动作可选，默认 false 即 Secret 弱保密模式）。',
+                },
+                filter: {
+                    type: 'string',
+                    description: '按正则表达式过滤检索描述或文件内容（list 动作可选）。',
+                },
+                limit: {
+                    type: 'number',
+                    description: '返回 Gist 数量上限（list 动作使用，默认 10）。',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: '高危破坏性操作确认标志（delete 动作必需）。未传 true 时输出影响评估报告并拦截。',
+                },
+            },
+            required: ['action'],
+        },
+        output: {
+            schema: { type: 'object' },
+            render(args, value) {
+                return [{ type: 'text', text: renderGistMarkdown(args, value) }];
+            },
+        },
+        async execute(args, execContext) {
+            const cwd = execContext?.cwd || process.cwd();
+            const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
+            const runOpts = { cwd, sessionId, rawText: true };
+            switch (args.action) {
+                case 'list': {
+                    const listCmd = ['gist', 'list'];
+                    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 10;
+                    listCmd.push('-L', String(limit));
+                    if (args.public === true) {
+                        listCmd.push('--public');
+                    }
+                    else if (args.public === false) {
+                        listCmd.push('--secret');
+                    }
+                    if (args.filter) {
+                        listCmd.push('--filter', String(args.filter));
+                    }
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const items = parseGistListOutput(res.rawOutput || '');
+                    return { items, count: items.length, rawText: res.rawOutput || '' };
+                }
+                case 'view': {
+                    if (!args.gist_id) {
+                        throw new Error('查看 Gist 时 `gist_id` 参数为必填项（可提供 Gist 数字字母 ID 或完整 URL）。');
+                    }
+                    const viewCmd = ['gist', 'view', String(args.gist_id), '-r'];
+                    if (args.filename) {
+                        viewCmd.push('-f', String(args.filename));
+                    }
+                    const res = await executor.run(viewCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        gist_id: String(args.gist_id),
+                        filename: args.filename,
+                        content: res.rawOutput || '',
+                    };
+                }
+                case 'create': {
+                    if (!args.content && (!args.files || !Array.isArray(args.files) || args.files.length === 0)) {
+                        throw new Error('创建 Gist 时必须提供 `content`（代码片段文本）或 `files`（本地文件路径数组）。');
+                    }
+                    const createCmd = ['gist', 'create'];
+                    let stdinData;
+                    if (args.content) {
+                        createCmd.push('-');
+                        const fn = args.filename ? String(args.filename).trim() : 'snippet.txt';
+                        createCmd.push('-f', fn);
+                        stdinData = String(args.content);
+                    }
+                    else if (args.files) {
+                        for (const f of args.files) {
+                            createCmd.push(String(f));
+                        }
+                    }
+                    if (args.public === true) {
+                        createCmd.push('--public');
+                    }
+                    if (args.description) {
+                        createCmd.push('-d', String(args.description));
+                    }
+                    const res = await executor.run(createCmd, { ...runOpts, stdin: stdinData });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const rawUrl = (res.rawOutput || '').trim();
+                    const urlMatch = rawUrl.match(/gist\.github\.com\/([^/]+\/)?([0-9a-fA-F]+)/i);
+                    const gistId = urlMatch ? urlMatch[2] : rawUrl;
+                    return {
+                        success: true,
+                        url: rawUrl,
+                        gist_id: gistId,
+                        public: args.public === true,
+                        description: args.description,
+                        message: `✅ 成功创建 Gist: ${rawUrl}`,
+                    };
+                }
+                case 'edit': {
+                    if (!args.gist_id) {
+                        throw new Error('编辑 Gist 时 `gist_id` 参数为必填项。');
+                    }
+                    const editCmd = ['gist', 'edit', String(args.gist_id)];
+                    if (args.description) {
+                        editCmd.push('-d', String(args.description));
+                    }
+                    if (args.filename) {
+                        editCmd.push('-f', String(args.filename));
+                    }
+                    const res = await executor.run(editCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        gist_id: String(args.gist_id),
+                        message: `✅ 成功更新 Gist "${args.gist_id}"`,
+                        detail: res.rawOutput || '',
+                    };
+                }
+                case 'delete': {
+                    if (!args.gist_id) {
+                        throw new Error('删除 Gist 时 `gist_id` 参数为必填项。');
+                    }
+                    if (args.confirm !== true) {
+                        return {
+                            status: 'AWAITING_CONFIRMATION',
+                            action: 'delete',
+                            gist_id: String(args.gist_id),
+                            warning: `⚠️ 高危破坏性操作：即将永久删除 Gist 代码片段 "${args.gist_id}"`,
+                            impact: `删除 Gist 为物理删除，无法通过 GitHub API 恢复，所有引用该 Gist URL 的外部链接将失效并返回 404。`,
+                            requiredAction: `如确认彻底删除，请在参数中附加 \`confirm: true\` 重新调用。示例：\`github_gist(action: 'delete', gist_id: '${args.gist_id}', confirm: true)\``,
+                        };
+                    }
+                    const delCmd = ['gist', 'delete', String(args.gist_id), '--yes'];
+                    const res = await executor.run(delCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return {
+                        success: true,
+                        gist_id: String(args.gist_id),
+                        message: `🗑️ 成功删除 Gist 代码片段 "${args.gist_id}"`,
+                        detail: res.rawOutput || '',
+                    };
+                }
+                default:
+                    throw new Error(`不支持的 gist 操作: "${args.action}"。可选值: list, view, create, edit, delete。`);
+            }
+        },
+    };
+}

package/lib/tools/help.js

@@ -13,9 +13,19 @@ const KNOWLEDGE_BASE = {
 | \`github_release\` | 版本发布与构建资产交付 | 查看发版历史、自动生成 Release Notes、上传 .tgz 等构建产物 |
 | \`github_secret\` | CI/CD 密钥与变量管理 | 查看 NPM_TOKEN 等密钥清单、经 stdin 安全写入密文、删除密钥；kind:'variable' 管理明文变量（set/get/delete） |
 | \`github_skill\` | 跨 Agent 开源 Skills 生态发现 | 检索/预览/安装 GitHub 上的 Agent Skills (gh preview 特性) |
+| \`github_label\` | 标签体系管理与跨仓库克隆 | 查看标签列表、创建/编辑标签、从源仓库一键 clone 标签体系、删除标签（需 confirm） |
+| \`github_ruleset\` | 分支保护规则与策略诊断 | 检查分支适用的合并策略规则 (check)、查看规则集列表与详情，权威回答“PR 为何无法合并” |
+| \`github_cache\` | Actions 构建缓存盘点与安全清理 | 查看缓存列表与体积占用、按 ID/Key 删除指定缓存、全量清空缓存（需 confirm） |
+| \`github_gist\` | 代码片段与调试日志分享治理 | 查看 Gist 列表与代码正文、创建 Secret/Public 代码片段、编辑与物理删除（需 confirm） |
+| \`github_status\` | 跨仓库待办与动态聚合看板 | 账号维度汇总指派给我的 Issue/PR、等待评审、被 @提及 以及订阅仓库近期动态 |
+| \`github_agent_task\` | 云端智能体编码任务会话治理 | 查阅已分派任务列表、检视任务状态与会话日志、向云端 Agent 发起新编码重构任务 |
+| \`github_discussion\` | 团队技术讨论与开源社区 RFC 闭环 | 浏览讨论列表、检视正文与评论楼层、发起新讨论、编辑正文与追加回复 |
+| \`github_project\` | Projects v2 项目看板与任务规划 | 查阅项目列表/详情、浏览看板条目 (Items)、添加 Issue/PR 到看板、创建草稿任务与删除条目 |
+| \`github_codespace\` | 云端远程开发环境管控 (MVP) | 查阅运行中实例、检视机器规格配置、停机防计费 (stop)、安全销毁环境 (delete，需 confirm) |
 | \`github_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
 💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
+💬 **人类指令**：聊天框支持 \`/gh status\`（大盘看板）、\`/gh upgrade\`（一键升级插件）、\`/gh help\`（快捷帮助）。
 🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     pr: `### 🔀 github_pr 详细操作指南
 
@@ -35,7 +45,9 @@ const KNOWLEDGE_BASE = {
 - **反向提交**: \`github_pr(action: 'revert', pr_number: 123, confirm: true)\`
   - 在远端创建反向提交与新 PR（非本地操作），需 confirm。
 - **分支落后自愈**: \`github_pr(action: 'update_branch', pr_number: 123)\`
-  - 将基准分支最新提交同步进 PR 分支，解决「分支落后需更新」的 CI 门禁失败。`,
+  - 将基准分支最新提交同步进 PR 分支，解决「分支落后需更新」的 CI 门禁失败。
+- **上传本地附件/图片**: \`github_pr(action: 'create', title: 'UI 重构', body: '对比图如下', attach_images: ['./before.png', './after.png'])\`
+  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个文件，禁止网络 URL，与 view_images 对称闭环。`,
     issue: `### 🎯 github_issue 详细操作指南
 
 - **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
@@ -45,6 +57,8 @@ const KNOWLEDGE_BASE = {
   - 经 gh api 下载正文+评论图片到本地（~/.dsh/data/dsh-github-flow/images/，内容寻址去重），以图片内容块返回，Agent 可直接查看用户报障截图；魔数校验 + 字节护栏（单图 5MB、目录 15MB）。
   - **按 URL 精准获取**: 附加 \`image_urls: ['<view 返回清单中的 URL>']\` 只下载指定图片（可单张可批量）；传入 URL 必须在清单内（防任意下载）。
   - 触达目录上限时返回 \`remaining\` 结构化清单，直接作为下一批 image_urls 续传即可。
+- **上传本地附件/图片**: \`github_issue(action: 'comment', issue_number: 42, body: '复现证据', attach_images: ['./bug.png'])\`
+  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个本地文件（绝对路径或工作区相对路径，禁止网络 URL）。
 - **关联开发分支**: \`github_issue(action: 'develop', issue_number: 42, branch_name: 'fix-login-bug')\`
   - 自动在远端和本地创建带有官方关联关系的开发分支并切换过去，实现“读需求 -> 开分支写代码”的无缝衔接。
 - **编辑 Issue**: \`github_issue(action: 'edit', issue_number: 42, title: '新标题', add_labels: ['p1'], remove_labels: ['triage'])\`
@@ -146,7 +160,111 @@ const KNOWLEDGE_BASE = {
   - install 会写本地磁盘，必须 \`confirm: true\`；scope 默认 project（当前 git 仓库）。
   - 支持的 agent 值：claude-code / cursor / github-copilot / codex / gemini-cli 等。
 - **查看已安装**: \`github_skill(action: 'list')\`
+- **规范自检与发布**:
+  - \`github_skill(action: 'publish')\` —— 默认 \`--dry-run\` 模式，对本地技能目录进行 agentskills.io 合规性检查（命名规范、目录匹配、必需 frontmatter 字段等），零副作用安全自检。
+  - \`github_skill(action: 'publish', fix: true)\` —— 自动清洗并剥离残留的安装元数据（\`metadata.github-*\`），修改本地文件但不发布。
+  - \`github_skill(action: 'publish', tag: 'v1.0.0', dry_run: false, confirm: true)\` —— 正式发布，强制要求指定 \`tag\` 并附带 \`confirm: true\`（防无头挂起与误发布），自动创建 GitHub Release。
 - ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+    label: `### 🏷️ github_label 详细操作指南
+
+- **查看标签列表**: \`github_label(action: 'list', limit: 30, search: 'bug')\`
+  - 支持按名称或描述模糊检索，支持 \`sort: 'created' | 'name'\` 与 \`order: 'asc' | 'desc'\`。
+- **创建标签**: \`github_label(action: 'create', name: 'priority/p0', color: 'd73a4a', description: '最高优先级缺陷')\`
+  - 颜色自动去除前导 \`#\` 并校验 6 位十六进制；已存在时可附加 \`force: true\` 强制覆盖更新。
+- **编辑标签**: \`github_label(action: 'edit', name: 'old-name', new_name: 'new-name', color: '0075ca')\`
+  - 支持修改描述、色值以及重命名标签（\`new_name\`）。
+- **删除标签**: \`github_label(action: 'delete', name: 'deprecated', confirm: true)\`
+  - 高危破坏性操作：会导致所有关联 Issue/PR 自动解绑该标记，必须显式附加 \`confirm: true\`；底层自动传 \`--yes\` 杜绝无头交互挂起。
+- **跨仓库克隆标签**: \`github_label(action: 'clone', source_repo: 'cli/cli', force: true)\`
+  - 将源仓库的标准标签体系一键同步到当前仓库（或指定的 \`repo\`），新仓库初始化刚需。`,
+    ruleset: `### 🛡️ github_ruleset 详细操作指南
+
+- **检查分支合并策略约束**: \`github_ruleset(action: 'check', branch: 'master')\`
+  - **PR 无法合并的策略视角权威答案**：输出指定分支匹配到的全部硬性规则约束（必审人数、指定 CI、禁止 force push 等）。
+  - 若无规则约束，输出排障引导，建议联动 \`github_pr(action: 'checks')\` 检查 CI 执行状态。
+  - 检查默认分支可附加 \`default_branch: true\`。
+- **查看规则集列表**: \`github_ruleset(action: 'list', limit: 30)\`
+  - 默认包含上级组织继承规则；附加 \`no_parents: true\` 仅查看仓库自身规则集；支持 \`org: 'org-name'\` 查看组织级规则集（需 \`admin:org\` 权限）。
+- **查看规则集详情**: \`github_ruleset(action: 'view', ruleset_id: '4898070')\`
+  - 查看具体 Ruleset 详细配置规则与适用范围，\`ruleset_id\` 必填。`,
+    cache: `### ⚡ github_cache 详细操作指南
+
+- **查看缓存列表与体积**: \`github_cache(action: 'list', limit: 30, sort: 'size_in_bytes', order: 'desc')\`
+  - 返回仓库 Actions 构建缓存清单、占用体积（自动换算为 KB/MB/GB）、关联 Git Ref 以及最后访问时间。
+  - 可附加 \`key: 'npm-cache'\` 过滤特定前缀，或通过 \`ref: 'refs/heads/main'\` 限定分支。
+- **精准删除单条缓存**:
+  - 按数字 ID 删除: \`github_cache(action: 'delete', cache_id: '12345678')\`
+  - 按 Key 键名删除: \`github_cache(action: 'delete', key: 'Linux-npm-18-abcd1234')\`
+- **全量清空仓库缓存**:
+  \`github_cache(action: 'delete', all: true, confirm: true)\`
+  - 批量破坏性操作：会导致后续流水线构建重新拉取依赖，必须显式附加 \`confirm: true\`；底层自动注入 \`--succeed-on-no-caches\` 保证幂等执行。`,
+    gist: `### 📝 github_gist 详细操作指南
+
+- **查看我的 Gist 列表**: \`github_gist(action: 'list', limit: 10)\`
+  - 默认查看全部；可附加 \`public: true\` 仅看公开、\`public: false\` 仅看私密；支持 \`filter: 'regex'\` 正则过滤。
+- **检视代码片段正文**: \`github_gist(action: 'view', gist_id: '5b0e0062eb8e9654adad7bb1d81cc75f')\`
+  - 直接输出原始代码正文，\`gist_id\` 必填（防交互挂起）；可选 \`filename: 'main.py'\` 限定文件。
+- **创建 Gist 代码片段**:
+  - 直接传文本内容: \`github_gist(action: 'create', content: 'console.log("hello");', filename: 'demo.ts', description: '排错测试片段')\`
+  - 传本地文件列表: \`github_gist(action: 'create', files: ['./build.log', './error.txt'], description: 'CI 失败排错日志')\`
+  - 默认创建 Secret Gist（Unlisted 弱保密，拥有链接者可访问）；若要公开需显式附加 \`public: true\`。
+  - ⚠️ **安全须知**: 切勿将敏感凭据、API Token 存入 Gist。
+- **编辑 Gist**: \`github_gist(action: 'edit', gist_id: '...', description: '新描述', filename: 'patch.diff')\`
+- **删除 Gist**: \`github_gist(action: 'delete', gist_id: '...', confirm: true)\`
+  - 物理删除不可逆，必须显式附加 \`confirm: true\`；底层自动注入 \`--yes\` 杜绝交互式卡死。`,
+    status: `### 🧭 github_status 详细操作指南
+
+- **查看个人待办与动态大盘**: \`github_status()\` 或 \`github_status(action: 'view')\`
+  - 账号维度一站式汇总：指派给我的 Issues、指派给我的 PR、等待我评审的 PR、近期 @提及 以及订阅仓库最新动态。
+- **限定组织**: \`github_status(org: 'my-org')\`
+  - 仅汇报指定组织内部的待办事项与动态。
+- **排除噪音仓库**: \`github_status(exclude: ['owner/noisy-repo'])\`
+  - 过滤高频刷屏但无需关注的仓库活动。
+- **查看工具链运行时健康度**: \`github_status(action: 'health')\`
+  - 审计当前会话 18 大工具矩阵的综合健康分、API 降级率、安全防线拦截频次与针对性自愈建议。`,
+    agent_task: `### 🤖 github_agent_task 智能体任务指南
+
+管理与调度 GitHub Copilot Coding Agent 云端智能体会话：
+- **查看任务列表**: \`github_agent_task(action: 'list', limit: 30)\`
+  - 账号全局任务全景列表（注：上游 gh CLI 原生不接收 -R/--repo 限制，默认列出当前用户所有活跃会话）。
+- **检视任务会话与日志**: \`github_agent_task(action: 'view', task_id: 'e2fa49d2-...', log: true)\`
+  - 必须提供 \`task_id\`（支持 Session ID、PR 编号或 URL），支持 \`repo: 'owner/repo'\`，附加 \`log: true\` 可完整拉取任务执行过程日志。
+- **派发新编码任务**: \`github_agent_task(action: 'create', prompt: '为用户模块补全单元测试', base_branch: 'main', repo: 'owner/repo')\`
+  - 支持附加 \`custom_agent: 'my-agent'\` 指定仓库预设的智能体定义，支持 \`repo\` 定向派发。`,
+    discussion: `### 💬 github_discussion 讨论区操作指南
+
+基于 GitHub CLI 的 \`gh discussion\` preview 特性，支持团队架构探讨、RFC 与社区互动：
+- **查看讨论列表**: \`github_discussion(action: 'list', category: 'General', state: 'open', limit: 30)\`
+  - 支持按 \`category\`（分类）、\`state\`（open/closed/all）、\`labels\` 以及 \`search\`（关键词）过滤；状态自动结构化映射为 OPEN / CLOSED / ANSWERED。
+- **检视讨论正文与回复楼层**: \`github_discussion(action: 'view', discussion_number: 123, comments: true)\`
+- **发起新讨论**: \`github_discussion(action: 'create', title: 'RFC: 架构演进方案', category: 'Ideas', body: '详细方案...')\`
+  - \`title\`、\`category\` 与 \`body\` 均为必填项。
+- **编辑讨论**: \`github_discussion(action: 'edit', discussion_number: 123, title: '新标题', body: '修正后的正文')\`
+- **发表讨论回复**: \`github_discussion(action: 'comment', discussion_number: 123, body: '赞同该方案！')\`
+- 💡 **提示**：若报错「discussions disabled」，说明目标仓库未在 GitHub 仓库「Settings -> General -> Features」中启用 Discussions 社区功能。`,
+    project: `### 📋 github_project 项目看板与规划指南
+
+基于 GitHub Projects v2，支持项目看板与任务全生命周期管理：
+- **查看项目列表**: \`github_project(action: 'list', owner: '@me', closed: false)\`
+  - 缺省 owner 为 \`@me\`（当前用户），可指定组织或用户名称。
+- **查看项目详情**: \`github_project(action: 'view', project_number: 1)\`
+- **浏览看板条目 (Items)**: \`github_project(action: 'item-list', project_number: 1, query: 'is:open')\`
+- **添加现有 Issue/PR 到看板**: \`github_project(action: 'item-add', project_number: 1, url: 'https://github.com/owner/repo/issues/10')\`
+- **创建草稿条目**: \`github_project(action: 'item-create', project_number: 1, title: '待调研技术方案', body: '方案说明...')\`
+- **删除看板条目**: \`github_project(action: 'item-delete', item_id: 'PVTI_...', confirm: true)\`
+  - 必须附加 \`confirm: true\`；仅解除条目与看板的关联，不删除 Issue/PR 原型。
+- 🔑 若报缺少权限，在终端执行单行自愈授权命令：\`gh auth refresh -s read:project\``,
+    codespace: `### ☁️ github_codespace 云端开发环境指南
+
+管理 GitHub Codespaces 云端远程工作区（精选高频实用 MVP）：
+- **查看云端环境列表**: \`github_codespace(action: 'list', limit: 30)\`
+- **检视实例配置与状态**: \`github_codespace(action: 'view', codespace: 'fuzzy-spoon-69vj')\`
+  - 必须显式提供 \`codespace\` 名称，杜绝交互式挂起。
+- **停止运行环境 (防计费)**: \`github_codespace(action: 'stop', codespace: 'fuzzy-spoon-69vj')\`
+  - 立即向云端实例发送停机信号，防止持续扣除计算核时配额。
+- **安全销毁实例**: \`github_codespace(action: 'delete', codespace: 'fuzzy-spoon-69vj', confirm: true)\`
+  - 物理销毁不可逆，必须附加 \`confirm: true\`。
+- 🔑 若报缺少权限，在终端执行单行自愈授权命令：\`gh auth refresh -h github.com -s codespace\``,
     mapping: `### 🗺️ gh 命令 ↔ 插件工具映射总表
 
 #### 一、已覆盖域映射（语义化 action 精确对照）
@@ -207,33 +325,96 @@ const KNOWLEDGE_BASE = {
 | \`gh variable list/set/get/delete\` | \`github_secret(action:…, kind:'variable')\` | CI 明文：-b 直传、get 可回显 |
 | （gh secret get 不存在） | — | GitHub 侧加密存储，物理不可读取 |
 
-**Skill（github_skill，4 action）**
-\`gh skill search/preview/install/list\` → \`github_skill(action:…)\`；install 需 confirm（写磁盘）。
+**Skill（github_skill，5 action）**
+\`gh skill search/preview/install/list/publish\` → \`github_skill(action:…)\`；install 需 confirm（写磁盘）；publish 默认 dry-run 安全自检，正式发布需 tag 与 confirm。
+
+**Label（github_label，5 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh label list\` | \`github_label(action:'list')\` | 支持搜索与排序 |
+| \`gh label create\` | \`github_label(action:'create', name:…, color:…)\` | 颜色十六进制校验 |
+| \`gh label edit\` | \`github_label(action:'edit', name:…, new_name:…)\` | 支持重命名 |
+| \`gh label delete\` | \`github_label(action:'delete', name:…, confirm:true)\` | 高危解绑，需 confirm |
+| \`gh label clone\` | \`github_label(action:'clone', source_repo:…)\` | 跨仓库一键克隆 |
+
+**Ruleset（github_ruleset，3 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh ruleset check\` | \`github_ruleset(action:'check', branch:…)\` | PR 策略排障核心 |
+| \`gh ruleset list\` | \`github_ruleset(action:'list')\` | 规则集概览 |
+| \`gh ruleset view\` | \`github_ruleset(action:'view', ruleset_id:…)\` | 规则详情，ID 必填 |
+
+**Cache（github_cache，2 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh cache list\` | \`github_cache(action:'list')\` | 缓存盘点与过滤 |
+| \`gh cache delete\` | \`github_cache(action:'delete', cache_id:…)\` | all:true 需 confirm |
+
+**Gist（github_gist，5 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh gist list/view\` | \`github_gist(action:'list'/'view')\` | 代码正文检视 |
+| \`gh gist create\` | \`github_gist(action:'create', content:…)\` | 默认 secret 弱保密 |
+| \`gh gist edit\` | \`github_gist(action:'edit', gist_id:…)\` | 描述与文件修改 |
+| \`gh gist delete\` | \`github_gist(action:'delete', gist_id:…, confirm:true)\` | 物理删除，需 confirm |
+
+**Status（github_status，2 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh status\` | \`github_status(action:'view')\` | 跨仓待办大盘与动态 |
+| — | \`github_status(action:'health')\` | 工具链健康度与降级率审计 |
+
+**Agent Task（github_agent_task，3 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh agent-task list\` | \`github_agent_task(action:'list')\` | 智能体编码任务列表 |
+| \`gh agent-task view\` | \`github_agent_task(action:'view', task_id:…)\` | 任务状态与日志，ID 必填 |
+| \`gh agent-task create\` | \`github_agent_task(action:'create', prompt:…)\` | 向云端 Agent 派发任务 |
+
+**Discussion（github_discussion，5 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh discussion list\` | \`github_discussion(action:'list')\` | 社区与团队讨论列表 |
+| \`gh discussion view\` | \`github_discussion(action:'view', discussion_number:…)\` | 讨论正文与回复楼层 |
+| \`gh discussion create\` | \`github_discussion(action:'create', title:…, category:…, body:…)\` | 发起新讨论，三项必填 |
+| \`gh discussion edit\` | \`github_discussion(action:'edit', discussion_number:…)\` | 修改讨论标题或正文 |
+| \`gh discussion comment\` | \`github_discussion(action:'comment', discussion_number:…, body:…)\` | 追加讨论评论 |
+
+**Project（github_project，6 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh project list\` | \`github_project(action:'list')\` | 项目看板列表，默认 @me |
+| \`gh project view\` | \`github_project(action:'view', project_number:…)\` | 项目元数据与描述 |
+| \`gh project item-list\` | \`github_project(action:'item-list', project_number:…)\` | 任务条目看板 |
+| \`gh project item-add\` | \`github_project(action:'item-add', project_number:…, url:…)\` | 关联 Issue/PR 到看板 |
+| \`gh project item-create\` | \`github_project(action:'item-create', project_number:…, title:…)\` | 创建草稿条目 |
+| \`gh project item-delete\` | \`github_project(action:'item-delete', item_id:…, confirm:true)\` | 移除条目，需 confirm |
+
+**Codespace（github_codespace，4 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh codespace list\` | \`github_codespace(action:'list')\` | 云端开发环境列表 |
+| \`gh codespace view\` | \`github_codespace(action:'view', codespace:…)\` | 实例详情，名称必填 |
+| \`gh codespace stop\` | \`github_codespace(action:'stop', codespace:…)\` | 关机防计费 |
+| \`gh codespace delete\` | \`github_codespace(action:'delete', codespace:…, confirm:true)\` | 销毁实例，需 confirm |
 
 #### 二、归属提示（命令域与工具名不同构）
 
 - \`gh workflow …\` / \`gh search …\` / \`gh variable …\` 分别归 **github_run / github_repo / github_secret**（不是独立工具）
 - \`gh api\` 的等价物是 \`github_api\`（全端点逃生门，支持 raw/paginate/jq）
 - 图片查看：\`github_issue\`/\`github_pr\` 的 \`view_images\`、\`github_repo\` 的 \`readme\` + image_urls（插件独有能力，gh 无对应命令）
+- 附件上传：\`github_issue\`/\`github_pr\` 的 \`attach_images\` 映射 gh ≥2.99 原生可重复 \`--attach\` flag（支持 create/edit/comment）
 
 #### 三、未覆盖域引导（经 github_api 调用）
 
 | gh 域 | 用途 | 推荐 REST 端点 |
 | :--- | :--- | :--- |
-| \`gh label\` | 标签管理 | \`repos/{o}/{r}/labels\` |
-| \`gh cache\` | Actions 缓存 | \`repos/{o}/{r}/actions/caches\` |
-| \`gh gist\` | 代码片段 | \`gists\` |
-| \`gh ruleset\` | 分支保护规则 | \`repos/{o}/{r}/rulesets\` |
-| \`gh project\` | Projects v2 | \`graphql\`（Projects API 仅 GraphQL） |
-| \`gh discussion\` | 讨论 | \`graphql\`（需仓库开启 discussions） |
-| \`gh codespace\` | 云端开发环境 | \`user/codespaces\` |
 | \`gh org\` | 组织信息 | \`orgs/{org}\` |
 | \`gh auth/config/extension/alias\` | 本机配置类 | 多数无需 API（本机文件/命令） |
 | \`gh browse\` | 打开浏览器 | 直接给用户 URL 即可 |
 | \`gh attestation/gpg-key/ssh-key\` | 签名与密钥 | \`repos/{o}/{r}/attestations\` 等 |
-| \`gh agent-task\` | Copilot 会话 | \`graphql\`（需 Copilot 授权） |
 
-> 用法示例：\`github_api(endpoint: 'repos/owner/repo/labels', method: 'POST', fields: { name: 'bug', color: 'ff0000' })\``,
+> 用法示例：\`github_api(endpoint: 'repos/owner/repo/pulls')\`（原有 \`repos/{o}/{r}/labels\` 端点已由原生 \`github_label\` 工具接管）`,
     search_syntax: `### 🔍 GitHub 官方高级检索语法速查手册
 
 在 \`github_repo\`、\`github_api\` 或搜索场景中，请严格遵守 GitHub 官方搜索语法：
@@ -265,7 +446,18 @@ const KNOWLEDGE_BASE = {
    - *解法*：宿主机尚未安装 gh。Windows 运行 \`winget install GitHub.cli\`，macOS 运行 \`brew install gh\`，然后执行 \`gh auth login\` 登录。
  5. **报 \`unknown command "skill" for "gh"\`**:
     - *原因*：\`gh skill\` 是 GitHub CLI 2.9x 引入的 preview 特性，宿主机版本过低。
-    - *解法*：升级 gh（Windows: \`winget upgrade GitHub.cli\`；macOS: \`brew upgrade gh\`）后重试；升级前可改用 \`github_api\` 检索 \`SKILL.md\` 文件路径作为替代。`
+    - *解法*：升级 gh（Windows: \`winget upgrade GitHub.cli\`；macOS: \`brew upgrade gh\`）后重试；升级前可改用 \`github_api\` 检索 \`SKILL.md\` 文件路径作为替代。
+ 6. **报 \`the token ... needs the '<scope>' scope\` (缺少权限)**:
+    - *原因*：GitHub Token 缺少对应操作的最小 Scope 权限（如 Codespaces 需要 \`codespace\` 权限，Projects v2 需要 \`read:project\` 权限）。
+    - *解法*：在系统终端执行单行自愈命令完成授权刷新（无需重启插件，即刻生效）：
+      - Codespace: \`gh auth refresh -h github.com -s codespace\`
+      - Project: \`gh auth refresh -s read:project\`
+ 7. **报 \`the '...' repository has discussions disabled\`**:
+    - *原因*：目标 GitHub 仓库未开启 Discussions 社区功能。
+    - *解法*：需管理员前往 GitHub 网页端 \`Settings -> General -> Features\` 勾选开启 \`Discussions\`。
+ 8. **操作被拦截提示 \`Awaiting confirmation\`**:
+    - *原因*：对于高危破坏性操作（如合并 PR、删除分支、物理删除 Issue、清空构建缓存、删除密钥、销毁 Codespace），插件设置了强制安全确认防线，未确认时绝对不触发底层 CLI。
+    - *解法*：审阅影响评估报告后，在参数中显式传入 \`confirm: true\` 即可放行。`
 };
 export function createHelpTool(executor) {
     return {
@@ -286,6 +478,15 @@ export function createHelpTool(executor) {
                         'release',
                         'secret',
                         'skill',
+                        'label',
+                        'ruleset',
+                        'cache',
+                        'gist',
+                        'status',
+                        'agent_task',
+                        'discussion',
+                        'project',
+                        'codespace',
                         'mapping',
                         'search_syntax',
                         'troubleshooting',

package/lib/tools/image-utils.d.ts

@@ -77,3 +77,11 @@ export declare function downloadImages(urls: string[], run: (url: string) => Pro
 }>): Promise<ImageBatchResult>;
 /** render 的 image 内容块构造（text 块由调用方自行拼）：仅双合法字段才产出块 */
 export declare function buildImageBlocks(value: any): any[];
+/**
+ * 校验并解析本地附件路径列表（Issue/PR --attach 专用）。
+ * - 仅接受本地绝对路径或工作区相对路径
+ * - 严格拒绝 URL（HTTP/HTTPS）
+ * - 单批限制最多 50 个文件（GitHub 限制）
+ * - 校验本地文件物理存在性
+ */
+export declare function validateAttachPaths(attachImages: unknown, cwd: string): string[];

package/lib/tools/image-utils.js

@@ -245,3 +245,37 @@ export function buildImageBlocks(value) {
     }
     return blocks;
 }
+/**
+ * 校验并解析本地附件路径列表（Issue/PR --attach 专用）。
+ * - 仅接受本地绝对路径或工作区相对路径
+ * - 严格拒绝 URL（HTTP/HTTPS）
+ * - 单批限制最多 50 个文件（GitHub 限制）
+ * - 校验本地文件物理存在性
+ */
+export function validateAttachPaths(attachImages, cwd) {
+    if (!attachImages)
+        return [];
+    if (!Array.isArray(attachImages)) {
+        throw new Error('`attach_images` 必须为本地文件路径数组（string[]）。');
+    }
+    if (attachImages.length > 50) {
+        throw new Error(`单次上传附件数量超出 GitHub 限制（单批上限 50 个文件），当前提供: ${attachImages.length} 个。`);
+    }
+    const resolvedPaths = [];
+    for (const item of attachImages) {
+        if (typeof item !== 'string' || !item.trim()) {
+            throw new Error('`attach_images` 数组中的文件路径不能为空。');
+        }
+        const trimmed = item.trim();
+        // 严格禁止 URL
+        if (/^https?:\/\//i.test(trimmed)) {
+            throw new Error(`\`attach_images\` 仅支持本地文件路径上传，不支持网络 URL: "${trimmed}"。\n若需引用网络图片，请直接在正文/评论中使用 Markdown 语法 \`![说明](URL)\`，或先将其下载至本地再上传。`);
+        }
+        const absPath = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+        if (!fs.existsSync(absPath)) {
+            throw new Error(`指定的附件文件不存在: "${absPath}"（输入路径: "${trimmed}"）。`);
+        }
+        resolvedPaths.push(absPath);
+    }
+    return resolvedPaths;
+}

package/lib/tools/issue.d.ts

@@ -1,5 +1,5 @@
 import type { GhExecutor } from '../executor.js';
-export { extractImageUrls as extractIssueImageUrls } from './image-utils.js';
+export { extractImageUrls as extractIssueImageUrls, validateAttachPaths } from './image-utils.js';
 export declare function createIssueTool(executor: GhExecutor): {
     name: string;
     description: string;
@@ -88,6 +88,13 @@ export declare function createIssueTool(executor: GhExecutor): {
                 };
                 description: string;
             };
+            attach_images: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
         required: string[];
     };

package/lib/tools/issue.js

@@ -1,5 +1,6 @@
+import { compareGhVersions } from '../executor.js';
 import { renderIssueMarkdown } from '../renderers/markdown.js';
-import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls } from './image-utils.js';
+import { extractImageUrls, downloadImages, buildImageBlocks, filterRequestedUrls, validateAttachPaths } from './image-utils.js';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -9,8 +10,8 @@ function normalizeOutput(data) {
     }
     return { result: data !== undefined && data !== null ? data : '' };
 }
-// 共享图片工具链的同名再导出：phase8 测试直接 import 本模块，保持路径稳定
-export { extractImageUrls as extractIssueImageUrls } from './image-utils.js';
+// 共享图片工具链的同名再导出：保持路径与单测稳定
+export { extractImageUrls as extractIssueImageUrls, validateAttachPaths } from './image-utils.js';
 export function createIssueTool(executor) {
     return {
         name: 'github_issue',
@@ -90,6 +91,11 @@ export function createIssueTool(executor) {
                     items: { type: 'string' },
                     description: 'view_images 可选：仅下载指定 URL 的图片（从 view 返回的 images 清单中选取，不在清单内的会被拒绝）。留空下载全部（正文+评论）。',
                 },
+                attach_images: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: '本地图片/附件路径列表（create, edit, comment 动作使用，需 gh ≥ 2.99；禁止 URL，单批上限 50 个）。',
+                },
             },
             required: ['action'],
         },
@@ -116,6 +122,18 @@ export function createIssueTool(executor) {
             }
             const repoArgs = ['-R', repoTarget];
             const runOpts = { cwd, sessionId };
+            const appendAttachFlags = async (cmd, attachImages) => {
+                const attachPaths = validateAttachPaths(attachImages, cwd);
+                if (attachPaths.length > 0) {
+                    const version = await executor.getGhVersion();
+                    if (version && compareGhVersions(version, '2.99.0') < 0) {
+                        throw new Error(`附件上传能力 (\`--attach\`) 需要 GitHub CLI 版本 ≥ 2.99.0，当前版本为: ${version}。\n请升级 gh（Windows: \`winget upgrade GitHub.cli\`，macOS: \`brew upgrade gh\`）后再试。`);
+                    }
+                    for (const p of attachPaths) {
+                        cmd.push('--attach', p);
+                    }
+                }
+            };
             switch (args.action) {
                 case 'list': {
                     const listCmd = ['issue', 'list', ...repoArgs, '--json', 'number,title,state,author,labels,updatedAt,url'];
@@ -216,6 +234,7 @@ export function createIssueTool(executor) {
                     if (args.assignees && Array.isArray(args.assignees) && args.assignees.length > 0) {
                         cmd.push('--assignee', args.assignees.join(','));
                     }
+                    await appendAttachFlags(cmd, args.attach_images);
                     const res = await executor.run(cmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
@@ -237,6 +256,7 @@ export function createIssueTool(executor) {
                         for (const l of args.remove_labels)
                             editCmd.push('--remove-label', l);
                     }
+                    await appendAttachFlags(editCmd, args.attach_images);
                     const res = await executor.run(editCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
@@ -257,7 +277,9 @@ export function createIssueTool(executor) {
                 case 'comment': {
                     if (!args.issue_number || !args.body)
                         throw new Error('comment 必须提供 issue_number 和 body');
-                    const res = await executor.run(['issue', 'comment', String(args.issue_number), ...repoArgs, '--body', args.body], runOpts);
+                    const commentCmd = ['issue', 'comment', String(args.issue_number), ...repoArgs, '--body', args.body];
+                    await appendAttachFlags(commentCmd, args.attach_images);
+                    const res = await executor.run(commentCmd, runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return { message: '评论发布成功', output: res.rawOutput };