dsh-github-flow 0.2.1 → 0.3.0

package/lib/tools/repo.js

@@ -18,8 +18,8 @@ export function createRepoTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['view', 'readme', 'search_code', 'search_repos', 'sync'],
-                    description: '仓库操作类型。readme 读取 README 原文并附带图片清单（可选 image_urls 下载指定图片，不传下载全部截图；默认过滤徽章小图标）。',
+                    enum: ['view', 'readme', 'search_code', 'search_repos', 'search_issues', 'search_prs', 'search_commits', 'read_file', 'read_dir', 'sync'],
+                    description: '仓库操作类型。readme 读取 README 原文并附带图片清单（可选 image_urls 下载指定图片，不传下载全部截图；默认过滤徽章小图标）。read_file/read_dir 免 clone 读取任意路径文件与目录（gh ≥2.95，低版本自动降级 API 链路）。',
                 },
                 repo: {
                     type: 'string',
@@ -36,7 +36,15 @@ export function createRepoTool(executor) {
                 },
                 query: {
                     type: 'string',
-                    description: '检索关键词（search_code 或 search_repos 时使用）。',
+                    description: '检索关键词（search_* 动作使用）。限定符直接写进 query（gh 惯例）：如 "repo:owner/name state:open label:bug"。注意 search_code/search_commits 必须包含搜索文本，纯限定符查询（如仅 "repo:x"）会被 gh 拒绝。',
+                },
+                path: {
+                    type: 'string',
+                    description: 'read_file 必填 / read_dir 可选（默认仓库根目录）：目标文件或目录路径（如 "src/tools/pr.ts"、".github/workflows"）。',
+                },
+                ref: {
+                    type: 'string',
+                    description: 'read_file/read_dir 可选：从指定分支/tag/commit 读取（默认默认分支）。',
                 },
                 limit: {
                     type: 'number',
@@ -165,6 +173,122 @@ export function createRepoTool(executor) {
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
+                case 'search_issues':
+                case 'search_prs': {
+                    if (!args.query)
+                        throw new Error(`${args.action} 必须提供 query`);
+                    // 限定符（repo:/state:/label: 等）直接写进 query 本体（gh search 惯例），
+                    // 不做独立参数——参数爆炸 + 与 gh 手册心智模型分叉（D3 决策）。
+                    // prs 比 issues 多 isDraft 字段（实测合法集 18 vs 17）。
+                    const repoArgs = args.repo ? ['--repo', args.repo] : [];
+                    const fields = args.action === 'search_prs'
+                        ? 'number,title,state,author,labels,isDraft,updatedAt,url'
+                        : 'number,title,state,author,labels,updatedAt,url';
+                    const res = await executor.run(['search', args.action === 'search_prs' ? 'prs' : 'issues', args.query, ...repoArgs, '--json', fields, '-L', limitStr], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'search_commits': {
+                    if (!args.query)
+                        throw new Error('search_commits 必须提供 query');
+                    const repoArgs = args.repo ? ['--repo', args.repo] : [];
+                    const res = await executor.run(['search', 'commits', args.query, ...repoArgs, '--json', 'sha,commit,author,repository,url', '-L', limitStr], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'read_file': {
+                    if (!args.path)
+                        throw new Error('read_file 必须提供 path（目标文件路径，如 "package.json"）');
+                    let repoTarget = args.repo;
+                    if (!repoTarget) {
+                        const meta = await executor.getRepoMetadata(cwd, sessionId);
+                        if (meta?.nameWithOwner)
+                            repoTarget = meta.nameWithOwner;
+                    }
+                    if (!repoTarget)
+                        throw new Error('read_file 必须提供 repo [owner/repo]，或在关联 Git 远程的工作区运行');
+                    const [owner, repoName] = repoTarget.split('/');
+                    if (!owner || !repoName)
+                        throw new Error(`read_file 需要 [owner/repo] 形式的仓库名（实际: ${repoTarget}）`);
+                    // 主链路走管道直出（无 --json）：gh 把原始内容写 stdout，executor 的
+                    // 24KB 截断与 UTF-8 处理免费复用；--json 模式 content 是 base64，
+                    // 中段截断即废且需解码 dance，弃用。
+                    const refArgs = args.ref ? ['--ref', args.ref] : [];
+                    const res = await executor.runGuarded(['repo', 'read-file', args.path, '-R', repoTarget, ...refArgs], {
+                        ...runOpts,
+                        rawText: true,
+                        timeoutMs: 20_000,
+                        minVersion: '2.95.0',
+                        capability: 'gh repo read-file',
+                        // 降级链：contents 端点 raw Accept（readme 同款技术），与主链路输出同构。
+                        // ref 必须走 URL query 而非 -f：gh api 在带 -f 时会把 GET 隐式改写为
+                        // POST（api.ts:66 同坑），contents 端点 POST 直接 404。
+                        fallback: async () => {
+                            const encoded = args.path.split('/').map(encodeURIComponent).join('/');
+                            const refQuery = args.ref ? `?ref=${encodeURIComponent(args.ref)}` : '';
+                            return executor.run(['api', `repos/${owner}/${repoName}/contents/${encoded}${refQuery}`, '-H', 'Accept: application/vnd.github.raw'], { cwd, sessionId, rawText: true, timeoutMs: 20_000 });
+                        },
+                    });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const content = res.rawOutput || '';
+                    // 二进制防线：NUL 字节是文本内容的可靠否定信号（UTF-8 合法文本不含 NUL）。
+                    // 不做 base64 直返——那会撑爆 Token 预算，引导 github_api binary channel。
+                    if (content.includes('\0')) {
+                        throw new Error(`「${args.path}」是二进制文件（检测到 NUL 字节），不适合文本读取。请改用 github_api(endpoint: 'repos/${owner}/${repoName}/contents/${args.path.split('/').map(encodeURIComponent).join('/')}', raw: true, binary 场景自行落盘) 获取字节流。`);
+                    }
+                    return { path: args.path, ref: args.ref, content, size: content.length, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                }
+                case 'read_dir': {
+                    let repoTarget = args.repo;
+                    if (!repoTarget) {
+                        const meta = await executor.getRepoMetadata(cwd, sessionId);
+                        if (meta?.nameWithOwner)
+                            repoTarget = meta.nameWithOwner;
+                    }
+                    if (!repoTarget)
+                        throw new Error('read_dir 必须提供 repo [owner/repo]，或在关联 Git 远程的工作区运行');
+                    const [owner, repoName] = repoTarget.split('/');
+                    if (!owner || !repoName)
+                        throw new Error(`read_dir 需要 [owner/repo] 形式的仓库名（实际: ${repoTarget}）`);
+                    const refArgs = args.ref ? ['--ref', args.ref] : [];
+                    const dirPath = args.path || '';
+                    const res = await executor.runGuarded(['repo', 'read-dir', ...(dirPath ? [dirPath] : []), '-R', repoTarget, ...refArgs], {
+                        ...runOpts,
+                        rawText: true,
+                        timeoutMs: 20_000,
+                        minVersion: '2.95.0',
+                        capability: 'gh repo read-dir',
+                        // 降级链：contents 端点返回 JSON 数组（dir 为含 type 字段的对象）。
+                        // ref 同样走 URL query（-f 会把 GET 改写成 POST，见 read_file 注释）
+                        fallback: async () => {
+                            const encoded = dirPath.split('/').filter(Boolean).map(encodeURIComponent).join('/');
+                            const refQuery = args.ref ? `?ref=${encodeURIComponent(args.ref)}` : '';
+                            return executor.run(['api', `repos/${owner}/${repoName}/contents/${encoded}${refQuery}`], { cwd, sessionId, timeoutMs: 20_000 });
+                        },
+                    });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    // 双链路归一为 items 数组：
+                    // 主链路是 TSV 四列（type/name/mode/size），降级链 data 是 contents JSON 数组
+                    let items;
+                    if (res.degraded && Array.isArray(res.data)) {
+                        items = res.data.map((e) => ({ type: String(e.type || 'file'), name: String(e.name || ''), mode: '-', size: typeof e.size === 'number' ? e.size : undefined }));
+                    }
+                    else {
+                        const tsv = (res.rawOutput || '').trim();
+                        if (!tsv) {
+                            return { message: `「${dirPath || '/'}」是空目录或不存在`, items: [], count: 0, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                        }
+                        items = tsv.split('\n').map((line) => {
+                            const cols = line.split('\t');
+                            return { type: cols[0] || 'file', name: cols[1] || '', mode: cols[2] || '-', size: Number(cols[3]) || 0 };
+                        });
+                    }
+                    return { path: dirPath || '/', items, count: items.length, ...(res.degraded ? { degraded: res.degraded, degradedReason: res.degradedReason } : {}) };
+                }
                 case 'sync': {
                     let repoTarget = args.repo;
                     if (!repoTarget) {

package/lib/tools/run.d.ts

@@ -35,6 +35,14 @@ export declare function createRunTool(executor: GhExecutor): {
                 type: string;
                 description: string;
             };
+            all: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
             ref: {
                 type: string;
                 description: string;

package/lib/tools/run.js

@@ -1,4 +1,8 @@
+import { compareGhVersions } from '../executor.js';
 import { renderRunMarkdown } from '../renderers/markdown.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 function normalizeOutput(data) {
     if (data && typeof data === 'object' && !Array.isArray(data)) {
         return data;
@@ -17,8 +21,8 @@ export function createRunTool(executor) {
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'view', 'log_failed', 'rerun', 'cancel', 'trigger'],
-                    description: 'Actions 操作类型。新增 trigger (主动触发 workflow_dispatch)。',
+                    enum: ['list', 'view', 'log_failed', 'rerun', 'cancel', 'trigger', 'workflow_list', 'workflow_view', 'workflow_enable', 'workflow_disable', 'download'],
+                    description: 'Actions 操作类型。trigger 主动触发 workflow_dispatch；workflow_* 查询与启停工作流；download 下载构建产物（落盘插件管理目录）。',
                 },
                 run_id: {
                     type: 'string',
@@ -43,7 +47,15 @@ export function createRunTool(executor) {
                 },
                 workflow: {
                     type: 'string',
-                    description: '工作流名称或文件名（trigger 动作使用，例如 "pr-check.yml" 或 "CI"）。',
+                    description: '工作流名称、ID 或文件名（trigger/workflow_view 动作使用，例如 "pr-check.yml"、"CI" 或 "374382120"）。',
+                },
+                all: {
+                    type: 'boolean',
+                    description: 'workflow_list 可选：列出全部工作流（含 disabled）。默认仅 active——排查「工作流为何不跑」时 disabled 状态本身就是答案，排障建议开启。',
+                },
+                name: {
+                    type: 'string',
+                    description: 'download 可选：仅下载指定名称的 artifact（可多次过滤，这里取单个名称）。',
                 },
                 ref: {
                     type: 'string',
@@ -132,6 +144,95 @@ export function createRunTool(executor) {
                     }
                     return { result: res.rawOutput || '未找到失败步骤的日志' };
                 }
+                case 'workflow_list': {
+                    // 字段集为 gh 2.96 实测合法全集（仅 4 个，无 updatedAt——勘误 E1）。
+                    // --all 暴露 disabled（排障语义：默认 active-only 对 Agent 是陷阱，D6 决策）。
+                    const listCmd = ['workflow', 'list', ...repoArgs, '--json', 'id,name,path,state', '-L', String(typeof args.limit === 'number' && args.limit > 0 ? args.limit : Math.min(executor.defaultListLimit ?? 10, 50))];
+                    if (args.all === true)
+                        listCmd.push('--all');
+                    const res = await executor.run(listCmd, runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return normalizeOutput(res.data || res.rawOutput);
+                }
+                case 'workflow_view': {
+                    if (!args.workflow)
+                        throw new Error('workflow_view 必须提供 workflow（工作流名称、ID 或文件名）');
+                    // gh workflow view 不支持 --json（勘误 E2，实测 unknown flag）——rawText 直通，
+                    // 仅头部三行结构化抽取；Recent runs 表保留原文（那是 run list 的投影，
+                    // Agent 要结构化运行数据走 github_run action:'list'，工具各司其职，D4 决策）。
+                    const res = await executor.run(['workflow', 'view', args.workflow, ...repoArgs], { ...runOpts, rawText: true, timeoutMs: 20_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    const text = res.rawOutput || '';
+                    const idMatch = /^ID:\s*(\S+)/m.exec(text);
+                    const totalMatch = /^Total runs\s+(\S+)/m.exec(text);
+                    // 首行是「名称 - 文件名」组合行（实测形态），整行保留作 workflow 标识
+                    const firstLine = text.split('\n', 1)[0]?.trim() || args.workflow;
+                    const recentIdx = text.indexOf('Recent runs');
+                    return {
+                        workflow: firstLine,
+                        id: idMatch ? idMatch[1] : undefined,
+                        totalRuns: totalMatch ? totalMatch[1] : undefined,
+                        recentRuns: recentIdx >= 0 ? text.slice(recentIdx).trim() : text.trim(),
+                    };
+                }
+                case 'workflow_enable':
+                case 'workflow_disable': {
+                    if (!args.workflow)
+                        throw new Error(`${args.action} 必须提供 workflow（工作流名称、ID 或文件名）`);
+                    // 可逆状态开关免 confirm（S3 方案 D4），但 disable 的后果（trigger 静默失败）
+                    // 必须写进返回——Agent 不知情会把 CI 故障误判为代码问题
+                    const res = await executor.run(['workflow', args.action === 'workflow_enable' ? 'enable' : 'disable', args.workflow, ...repoArgs], runOpts);
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return args.action === 'workflow_disable'
+                        ? { message: `工作流「${args.workflow}」已禁用。注意：下次 trigger 将静默失败，直至重新 enable（workflow_enable）。` }
+                        : { message: `工作流「${args.workflow}」已启用，恢复可触发状态。` };
+                }
+                case 'download': {
+                    if (!args.run_id)
+                        throw new Error('download 操作必须提供 run_id');
+                    if (args.name && typeof args.name !== 'string')
+                        throw new Error('name 必须是字符串（artifact 名称过滤）');
+                    // GHSA-39wj-f2f4-978v（gh<2.102 符号链接路径穿越）防线：落盘目录由插件
+                    // 固定派生（owner/repo/run_id 三级），不暴露 dir 参数给用户——攻击面
+                    // 收敛到一个 mkdirSync 调用点；用户无法注入 ../ 或符号链接目标。
+                    const artifactsRoot = path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'artifacts', ...repoTarget.split('/'), String(args.run_id));
+                    fs.mkdirSync(artifactsRoot, { recursive: true });
+                    const dlCmd = ['run', 'download', String(args.run_id), ...repoArgs, '-D', artifactsRoot];
+                    if (args.name) {
+                        dlCmd.push('-n', args.name);
+                    }
+                    const res = await executor.run(dlCmd, { ...runOpts, timeoutMs: 120_000 });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    // 落盘清单：递归枚举产物文件（相对路径+大小），供 Agent 直接引用
+                    const files = [];
+                    const walk = (dir, prefix) => {
+                        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                            const full = path.join(dir, entry.name);
+                            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+                            if (entry.isDirectory())
+                                walk(full, rel);
+                            else
+                                files.push({ file: rel, size: fs.statSync(full).size });
+                        }
+                    };
+                    walk(artifactsRoot, '');
+                    // GHSA-39wj-f2f4-978v：2.102.0 修复符号链接路径穿越。低版本不硬拒绝
+                    // （受控仓库下载是合理需求），但安全提示必须进返回值引导升级。
+                    const ghVersion = await executor.getGhVersion();
+                    const securityNote = ghVersion && compareGhVersions(ghVersion, '2.102.0') < 0
+                        ? `安全提示：当前 gh ${ghVersion} 低于 2.102.0（修复 GHSA-39wj-f2f4-978v 符号链接路径穿越）。建议升级 gh（Windows: winget upgrade GitHub.cli / macOS: brew upgrade gh）。`
+                        : undefined;
+                    return {
+                        message: `Run #${args.run_id} 产物已下载 ${files.length} 个文件${args.name ? `（过滤: ${args.name}）` : ''}`,
+                        directory: artifactsRoot,
+                        files,
+                        ...(securityNote ? { securityNote } : {}),
+                    };
+                }
                 case 'trigger': {
                     if (!args.workflow)
                         throw new Error('trigger 操作必须提供 workflow（工作流名称或文件名，例如 "pr-check.yml"）');

package/lib/tools/secret.d.ts

@@ -10,6 +10,11 @@ export declare function createSecretTool(executor: GhExecutor): {
                 enum: string[];
                 description: string;
             };
+            kind: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
             repo: {
                 type: string;
                 description: string;

package/lib/tools/secret.js

@@ -45,17 +45,63 @@ function renderSecretOutput(args, value) {
     }
     return JSON.stringify(value, null, 2);
 }
+/**
+ * 渲染 variable 工具输出——与 renderSecretOutput 物理分离（S3 D1 决策）。
+ * 为什么必须独立函数而非同一渲染器的分支：variable 的 value 是 CI 明文（可回显，
+ * 这正是 get action 的用途），secret 的 value 永不显示。若共用渲染逻辑再
+ * 「选择性放开」，未来任一侧的重构都可能意外污染另一侧的安全假设——
+ * 两个函数的边界比一个函数的分支更可审。
+ */
+function renderVariableOutput(args, value) {
+    if (!value)
+        return '无返回内容';
+    if (value.status === 'AWAITING_CONFIRMATION') {
+        return [
+            `> ### ${value.warning}`,
+            `> - **影响评估**: ${value.impact}`,
+            `> - **确认指引**: ${value.requiredAction}`,
+        ].join('\n');
+    }
+    if (Array.isArray(value.items) && args?.action === 'list') {
+        const list = value.items.filter(Boolean);
+        if (list.length === 0)
+            return '📭 当前作用域尚未配置任何 Variable。';
+        const rows = list.map((v) => {
+            const name = `\`${String(v.name || '-')}\``;
+            const date = v.createdAt ? String(v.createdAt).slice(0, 10) : '-';
+            return `| ${name} | ${date} |`;
+        });
+        return [
+            `**当前已配置 ${list.length} 个 Variable（值为 CI 明文，可经 get 查看）:**\n`,
+            '| 变量名 | 创建日期 |',
+            '| :--- | :--- |',
+            ...rows,
+        ].join('\n');
+    }
+    if (typeof value.result === 'string') {
+        return value.result;
+    }
+    if (typeof value.message === 'string') {
+        return `**${value.message}**`;
+    }
+    return JSON.stringify(value, null, 2);
+}
 export function createSecretTool(executor) {
     return {
         name: 'github_secret',
-        description: '管理 GitHub Actions 仓库密钥 (Secrets)：查看已配置的密钥名称列表、设置/更新密钥值（如 NPM_TOKEN、部署密钥）。密文经标准输入安全传递，绝不出现在命令行参数中，也不会在输出中回显。删除需 confirm: true。',
+        description: '管理 GitHub Actions 仓库密钥 (Secrets) 与变量 (Variables)：查看名称清单、设置/更新/删除值。Secret 密文经标准输入安全传递，绝不出现在命令行参数或输出中；Variable 为 CI 明文，可经 get 查看值。Secret 删除需 confirm: true。',
         parameters: {
             type: 'object',
             properties: {
                 action: {
                     type: 'string',
-                    enum: ['list', 'set', 'delete'],
-                    description: 'Secret 操作类型。',
+                    enum: ['list', 'get', 'set', 'delete'],
+                    description: '操作类型。get 仅 kind=variable 可用（secret 值写入后 GitHub 侧加密存储，物理不可读取）。',
+                },
+                kind: {
+                    type: 'string',
+                    enum: ['secret', 'variable'],
+                    description: '操作对象类型，默认 secret（向后兼容）。variable 为 Actions 明文变量：set 走 -b 直传、get 可回显值；secret 走 stdin 密文通道且永不回显。',
                 },
                 repo: {
                     type: 'string',
@@ -63,33 +109,33 @@ export function createSecretTool(executor) {
                 },
                 name: {
                     type: 'string',
-                    description: '密钥名称（set/delete 动作使用，如 "NPM_TOKEN"、"DOCKER_PASSWORD"）。',
+                    description: '名称（set/get/delete 动作使用，如 "NPM_TOKEN"、"DEPLOY_ENV"）。',
                 },
                 value: {
                     type: 'string',
-                    description: '密钥明文内容（set 动作使用）。内部通过子进程标准输入传递，避免在进程命令行被 ps/任务管理器窃取。',
+                    description: '值内容（set 动作使用）。secret：经子进程标准输入传递（防进程列表窃取）；variable：经 -b 参数直传（CI 明文，无 stdin 红线）。',
                 },
                 org: {
                     type: 'string',
-                    description: '组织级密钥的所属组织名（可选，映射 --org）。',
+                    description: '组织级作用域的组织名（可选，映射 --org）。',
                 },
                 env: {
                     type: 'string',
-                    description: '环境级密钥的部署环境名（可选，映射 --env）。',
+                    description: '环境级作用域的部署环境名（可选，映射 --env）。',
                 },
                 app: {
                     type: 'string',
                     enum: ['actions', 'agents', 'codespaces', 'dependabot'],
-                    description: '密钥归属的应用（可选，映射 --app，默认 actions）。',
+                    description: '密钥归属的应用（可选，仅 secret 的 --app，默认 actions；variable 无此维度）。',
                 },
                 visibility: {
                     type: 'string',
                     enum: ['all', 'private', 'selected'],
-                    description: '组织级密钥的可见范围（可选，仅 org 场景有意义）。',
+                    description: '组织级密钥的可见范围（可选，仅 secret + org 场景有意义）。',
                 },
                 confirm: {
                     type: 'boolean',
-                    description: '删除密钥时的确认标志。删除不可逆，未传 true 时仅输出影响评估。',
+                    description: '删除操作的确认标志。删除不可逆，未传 true 时仅输出影响评估。',
                 },
             },
             required: ['action'],
@@ -97,13 +143,16 @@ export function createSecretTool(executor) {
         output: {
             schema: { type: 'object' },
             render(args, value) {
-                return [{ type: 'text', text: renderSecretOutput(args, value) }];
+                // 渲染分流即安全边界：variable 与 secret 永不共享渲染路径（见函数注释）
+                const renderer = args?.kind === 'variable' ? renderVariableOutput : renderSecretOutput;
+                return [{ type: 'text', text: renderer(args, value) }];
             },
         },
         async execute(args, execContext) {
             const cwd = execContext?.cwd || process.cwd();
             const sessionId = execContext?.sessionId || execContext?.session?.id || process.env.DSH_SESSION_ID;
-            // org 作用域的密钥挂在组织上，与具体仓库无关：既不需要仓库识别，
+            const isVariable = args.kind === 'variable';
+            // org 作用域挂在组织上，与具体仓库无关：既不需要仓库识别，
             // 也不能把 -R 与 --org 同时传给 gh（两者语义冲突，gh 会报错）。
             const isOrgScope = Boolean(args.org);
             let repoTarget = args.repo;
@@ -114,34 +163,67 @@ export function createSecretTool(executor) {
                 }
             }
             if (!repoTarget && !isOrgScope) {
-                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]，或改用 `org` 参数操作组织级密钥。');
+                throw new Error('未能自动识别当前工作区关联的 GitHub 仓库。请通过 `repo` 参数显式指定目标仓库 [owner/repo]，或改用 `org` 参数操作组织级作用域。');
+            }
+            // app 限定符仅 secret 域存在（variable 命令无 --app）；误传时明确报错而非静默忽略
+            if (isVariable && args.app) {
+                throw new Error("variable 无 --app 维度（app 仅 secret 域支持），请移除 app 参数。");
+            }
+            if (isVariable && args.visibility) {
+                throw new Error("variable 无 --visibility 维度（visibility 仅组织级 secret 支持），请移除 visibility 参数。");
             }
             const runOpts = { cwd, sessionId };
             // org/env/app 三类作用域标志对所有动作通用；仓库作用域时三项均不追加
             const scopeFlags = [];
             if (args.org) {
                 scopeFlags.push('--org', args.org);
-                if (args.visibility)
+                if (!isVariable && args.visibility)
                     scopeFlags.push('--visibility', args.visibility);
             }
             else if (args.env) {
                 scopeFlags.push('--env', args.env);
             }
-            if (args.app)
+            if (!isVariable && args.app)
                 scopeFlags.push('--app', args.app);
             const targetArgs = isOrgScope ? [] : ['-R', repoTarget];
+            // gh 命令域分流：secret → gh secret …；variable → gh variable …
+            // （两级分流：域前缀 + 每个分支内的行为差异——stdin vs -b、get 可用性）
+            const domain = isVariable ? 'variable' : 'secret';
             switch (args.action) {
                 case 'list': {
-                    const res = await executor.run(['secret', 'list', ...targetArgs, ...scopeFlags, '--json', 'name,updatedAt,visibility'], runOpts);
+                    // 字段集各自实测钉死：secret 有 updatedAt/visibility；variable 仅 4 字段
+                    // （createdAt,name,numSelectedRepos,selectedReposURL——无 value，get 才返回）
+                    const fields = isVariable ? 'name,createdAt,numSelectedRepos' : 'name,updatedAt,visibility';
+                    const res = await executor.run([domain, 'list', ...targetArgs, ...scopeFlags, '--json', fields], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
                     return normalizeOutput(res.data || res.rawOutput);
                 }
+                case 'get': {
+                    if (!args.name)
+                        throw new Error('get 操作必须提供 name');
+                    if (!isVariable) {
+                        throw new Error('secret 的值写入后由 GitHub 侧加密存储，物理上不可读取（这正是 secret 与 variable 的设计区别）。请改用 kind: \'variable\' 或直接 set 覆盖。');
+                    }
+                    // gh variable get 输出变量值（纯文本，无 --json）
+                    const res = await executor.run(['variable', 'get', args.name, ...targetArgs, ...scopeFlags], { ...runOpts, rawText: true });
+                    if (!res.ok)
+                        throw new Error(res.error);
+                    return { name: args.name, value: res.rawOutput || '' };
+                }
                 case 'set': {
                     if (!args.name)
-                        throw new Error('set 操作必须提供 name（密钥名称）');
+                        throw new Error('set 操作必须提供 name');
                     if (typeof args.value !== 'string' || args.value.length === 0) {
-                        throw new Error('set 操作必须提供 value（密钥明文），且不允许为空字符串');
+                        throw new Error('set 操作必须提供 value，且不允许为空字符串');
+                    }
+                    if (isVariable) {
+                        // variable 是 CI 明文（workflow 中 env 直接引用可见），无 secret 的
+                        // stdin 红线；gh variable set 原生支持 -b 直传（实测 help）。
+                        const res = await executor.run(['variable', 'set', args.name, '--body', args.value, ...targetArgs, ...scopeFlags], runOpts);
+                        if (!res.ok)
+                            throw new Error(res.error);
+                        return { message: `Variable「${args.name}」已更新（值: ${args.value}）` };
                     }
                     // 安全红线：密文只走 stdin。严禁退化为 -b <value> —— 那会把明文
                     // 留在进程列表与 shell 历史里，等于密钥泄漏。gh 本地会用仓库公钥
@@ -154,21 +236,24 @@ export function createSecretTool(executor) {
                 case 'delete': {
                     if (!args.name)
                         throw new Error('delete 操作必须提供 name');
+                    const kindLabel = isVariable ? 'Variable' : 'Secret';
                     if (args.confirm !== true) {
                         return {
                             status: 'AWAITING_CONFIRMATION',
-                            warning: `⚠️ 高危操作拦截：你即将删除 Secret「${args.name}」${args.org ? `（组织 ${args.org}）` : ''}。`,
-                            impact: '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
+                            warning: `⚠️ 高危操作拦截：你即将删除 ${kindLabel}「${args.name}」${args.org ? `（组织 ${args.org}）` : ''}。`,
+                            impact: isVariable
+                                ? '删除后所有引用该变量的工作流将取不到值，运行中的构建立即失败。'
+                                : '删除后所有引用该密钥的 CI/CD 工作流将立即无法取到值，运行中的构建会失败。',
                             requiredAction: '如确认删除，请向用户核实并附加 `confirm: true` 重新调用。',
                         };
                     }
-                    const res = await executor.run(['secret', 'delete', args.name, ...targetArgs, ...scopeFlags], runOpts);
+                    const res = await executor.run([domain, 'delete', args.name, ...targetArgs, ...scopeFlags], runOpts);
                     if (!res.ok)
                         throw new Error(res.error);
-                    return { message: `Secret「${args.name}」已删除` };
+                    return { message: `${kindLabel}「${args.name}」已删除` };
                 }
                 default:
-                    throw new Error(`未知的 Secret 操作: ${args.action}`);
+                    throw new Error(`未知的 Secret/Variable 操作: ${args.action}（kind: ${args.kind || 'secret'}）`);
             }
         },
     };

package/lib/types.d.ts

@@ -24,6 +24,12 @@ export interface PluginConfig {
     updateCheckIntervalMs?: number;
     /** 自定义 npm Registry 镜像地址，留空则自动选用 npmmirror 与 npmjs */
     registryUrl?: string;
+    /**
+     * 是否向 gh 子进程注入 AI_AGENT='dsh' 环境变量，默认 true。
+     * gh ≥2.99 检测该变量后切换 agent 专属行为（text-only spinner、误用时打印完整 help）；
+     * 关闭后恢复 gh 原生行为（用于对照实验或偏好原生输出的场景）。
+     */
+    agentEnvInjection?: boolean;
     /**
      * 代理地址预置默认值（如 "http://127.0.0.1:7890"）。
      * 仅在用户未在驾驶舱保存过代理设置时生效；运行时 UI 保存的值优先级更高。
@@ -96,6 +102,52 @@ export interface RepoMetadata {
     isPrivate?: boolean;
     url?: string;
 }
+/**
+ * 本地 Git 工作区状态快照（ahead/behind 是 remote-tracking ref 的「上次 fetch」视图，
+ * 非实时网络状态——UI 渲染时必须带上这一语义提示，否则会误导用户）。
+ */
+export interface GitLocalStatus {
+    branch: string;
+    /** 领先远程的提交数；无 upstream 时为 -1（未知） */
+    ahead: number;
+    /** 落后远程的提交数；无 upstream 时为 -1（未知） */
+    behind: number;
+    /** 未提交变更文件数（含 untracked） */
+    dirtyCount: number;
+    hasUpstream: boolean;
+    /** 未提交文件清单（porcelain 解析，截断前 20 条防快照膨胀） */
+    dirtyFiles: Array<{
+        status: string;
+        path: string;
+    }>;
+}
+/** 单条提交记录（结构化解析） */
+export interface GitCommitEntry {
+    sha: string;
+    fullSha?: string;
+    author: string;
+    email?: string;
+    date?: string;
+    /** git 的相对时间原文（如 "2 hours ago"）——本地化由渲染层处理 */
+    relative: string;
+    subject: string;
+    body?: string;
+    stat?: string;
+}
+/**
+ * 本地 Git 提交记录三段视图（与 GitLocalStatus 的 ahead/behind 计数同口径，
+ * 均为 remote-tracking 快照）。
+ */
+export interface GitCommitLog {
+    /** 本地领先远程的提交（待 push） */
+    aheadCommits: GitCommitEntry[];
+    /** 远程领先本地的提交（待 pull，快照口径） */
+    behindCommits: GitCommitEntry[];
+    /** 最近提交（默认 15 条，支持下滚分页） */
+    recent: GitCommitEntry[];
+    /** 仓库总提交数（rev-list --count HEAD） */
+    totalCount?: number;
+}
 export interface PrItem {
     number: number;
     title: string;
@@ -170,6 +222,25 @@ export interface GitHubOverviewData {
     error?: string;
     /** 插件版本与升级信息（由内存缓存快速读取，不阻塞首屏业务） */
     updateInfo?: UpdateInfo;
+    /** 本地 Git 状态（ahead/behind/dirty，remote-tracking 快照语义）；非 Git 工作区为 undefined */
+    gitStatus?: GitLocalStatus | null;
+    /** 提交记录三段（本地领先/远程领先/最近）；探测失败为 undefined */
+    commitLog?: GitCommitLog | null;
+    /** 最新 Release 锚定（已过滤 Draft）；无 Release 仓库为 null */
+    releaseInfo?: {
+        tagName: string;
+        isPrerelease?: boolean;
+        publishedAt?: string;
+        url?: string;
+    } | null;
+    /** 当前分支关联的 PR；无 PR 分支为 null */
+    branchPr?: {
+        number: number;
+        title: string;
+        state?: string;
+        url?: string;
+        isDraft?: boolean;
+    } | null;
 }
 export interface UserRepoItem {
     name: string;
@@ -188,6 +259,8 @@ export interface WorkspaceMatrixItem {
     hasGit: boolean;
     repo?: RepoMetadata;
     sessionCount: number;
+    /** 本地 Git 状态摘要（可选——探测失败/非 Git 工作区不携带） */
+    gitStatus?: GitLocalStatus;
 }
 export interface GlobalIssueItem {
     number: number;