dsh-github-flow 0.3.0 → 0.4.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,6 +13,11 @@ 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_help\` | 路由导航、官方语法速查与故障自愈 | 遇到不确定的操作、搜索语法或接口报错时查询用法与诊断配方 |
 
 💡 **使用准则**：优先调用高层语义工具（pr / issue / run / repo / release / secret）；当高层工具无法满足特殊接口需求时，再降级使用 \`github_api\`。
@@ -35,7 +40,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 +52,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'])\`
@@ -147,6 +156,61 @@ const KNOWLEDGE_BASE = {
   - 支持的 agent 值：claude-code / cursor / github-copilot / codex / gemini-cli 等。
 - **查看已安装**: \`github_skill(action: 'list')\`
 - ⚠️ 若报「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'])\`
+  - 过滤高频刷屏但无需关注的仓库活动。`,
     mapping: `### 🗺️ gh 命令 ↔ 插件工具映射总表
 
 #### 一、已覆盖域映射（语义化 action 精确对照）
@@ -210,20 +274,52 @@ const KNOWLEDGE_BASE = {
 **Skill（github_skill，4 action）**
 \`gh skill search/preview/install/list\` → \`github_skill(action:…)\`；install 需 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，账号维度聚合面板）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh status\` | \`github_status(action:'view')\` | 跨仓待办大盘与动态 |
+
 #### 二、归属提示（命令域与工具名不同构）
 
 - \`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\` |
@@ -233,7 +329,7 @@ const KNOWLEDGE_BASE = {
 | \`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 官方搜索语法：
@@ -286,6 +382,11 @@ export function createHelpTool(executor) {
                         'release',
                         'secret',
                         'skill',
+                        'label',
+                        'ruleset',
+                        'cache',
+                        'gist',
+                        'status',
                         '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 };

package/lib/tools/label.d.ts

@@ -0,0 +1,80 @@
+import type { GhExecutor } from '../executor.js';
+/**
+ * 校验并归一化 6 位十六进制颜色（去除前导 #）
+ */
+export declare function normalizeHexColor(rawColor?: string): string | undefined;
+export declare function createLabelTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            repo: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            new_name: {
+                type: string;
+                description: string;
+            };
+            color: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            force: {
+                type: string;
+                description: string;
+            };
+            source_repo: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            search: {
+                type: string;
+                description: string;
+            };
+            sort: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            order: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            confirm: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    output: {
+        schema: {
+            type: string;
+        };
+        render(args: any, value: any): {
+            type: string;
+            text: string;
+        }[];
+    };
+    execute(args: any, execContext: any): Promise<Record<string, any>>;
+};