dsh-github-flow 0.4.0 → 0.6.0

package/lib/tools/help.js

@@ -12,15 +12,22 @@ const KNOWLEDGE_BASE = {
 | \`github_api\` | 原生 GitHub REST/GraphQL 逃生门 | 调用任意端点、获取原始文件字节 (raw)、支持自动翻页 (paginate) |
 | \`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_skill\` | 跨 Agent 开源 Skills 生态发现与维护 | 检索/预览/安装 GitHub 上的 Agent Skills（gh preview 特性）；\`publish\` 规范自检与发布、\`update\` 检查并同步更新已安装技能 |
 | \`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\`。
+📊 **规模口径**：18 个工具 / 103 个业务 action（不含 \`github_help\` 的 21 个查询主题与 \`github_api\` 的 4 个 HTTP method——它们不是业务动作）。
+💬 **人类指令**：聊天框支持 \`/gh status\`（大盘看板）、\`/gh upgrade\`（一键升级插件）、\`/gh help\`（快捷帮助）。
+🖥️ **可视化工作台**：最左侧 Octocat 图标打开全景驾驶舱（4 标签：本地工作区 / 我的仓库 / Pull Requests / 待办 Issues）；每个会话右侧栏有 5 个 Tab（Git / 未提交 / PR / Issues / Actions）。点击任一 PR 或 Issue 卡片可在线查看详情与评论，无需跳浏览器。
 🗺️ **命令对照**：不确定某 gh 命令对应哪个工具？\`github_help(topic: 'mapping')\` 查询完整映射表（含未覆盖域的 API 引导）。`,
     pr: `### 🔀 github_pr 详细操作指南
 
@@ -42,7 +49,9 @@ const KNOWLEDGE_BASE = {
 - **分支落后自愈**: \`github_pr(action: 'update_branch', pr_number: 123)\`
   - 将基准分支最新提交同步进 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 对称闭环。`,
+  - 需 gh ≥ 2.99；支持 create/edit/comment 动作，单批上限 50 个文件，禁止网络 URL，与 view_images 对称闭环。
+- **追加评论与编辑**: \`github_pr(action: 'comment', pr_number: 123, body: 'LGTM'); github_pr(action: 'edit', pr_number: 123, body: '更新后的描述')\`
+  - 两者同样支持 \`attach_images\` 附件通道。`,
     issue: `### 🎯 github_issue 详细操作指南
 
 - **筛选 Issue**: \`github_issue(action: 'list', state: 'open' | 'closed' | 'all', labels: ['bug'], assignees: ['octocat'], limit: 20)\`
@@ -155,7 +164,17 @@ const KNOWLEDGE_BASE = {
   - install 会写本地磁盘，必须 \`confirm: true\`；scope 默认 project（当前 git 仓库）。
   - 支持的 agent 值：claude-code / cursor / github-copilot / codex / gemini-cli 等。
 - **查看已安装**: \`github_skill(action: 'list')\`
-- ⚠️ 若报「unknown command」，说明宿主机 gh 版本过低，需升级到 2.9x 以上。`,
+- **规范自检与发布**:
+  - \`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 以上。
+
+- **检查并同步更新已安装技能**:
+  - \`github_skill(action: 'update')\` —— **默认 dry-run**，只检查哪些技能有新版本，零副作用。
+  - \`github_skill(action: 'update', dry_run: false)\` —— 真正执行同步更新。
+  - \`github_skill(action: 'update', all: true)\` —— 更新全部已安装技能（否则只处理 \`skill_names\` 指定项）。
+  - \`github_skill(action: 'update', skill_names: ['code-review', 'devops'])\` —— 定向更新指定技能。`,
     label: `### 🏷️ github_label 详细操作指南
 
 - **查看标签列表**: \`github_label(action: 'list', limit: 30, search: 'bug')\`
@@ -210,15 +229,61 @@ const KNOWLEDGE_BASE = {
 - **限定组织**: \`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 精确对照）
 
-**PR（github_pr，13 action）**
+**PR（github_pr，15 action）**
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
-| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作 |
+| \`gh pr list/view/create/diff/edit/comment\` | \`github_pr(action:'list'/'view'/'create'/'diff'/'edit'/'comment')\` | 高频基础操作；edit/comment 支持 attach_images |
+| （PR 图片查看，gh 无对应命令） | \`github_pr(action:'view_images', pr_number:n)\` | 插件独有：正文+评论图片下载并转为可读图像块 |
 | \`gh pr close\` | 暂无专用 action——用 \`github_pr(action:'edit')\` 或 \`github_api(endpoint:'repos/{o}/{r}/pulls/{n}', method:'PATCH', fields:{state:'closed'})\` | 插件侧未覆盖 |
 | \`gh pr checks\` | \`github_pr(action:'checks', pr_number:n)\` | CI 状态药丸 |
 | \`gh pr review\` | \`github_pr(action:'review', review_decision:'APPROVE'…)\` | |
@@ -233,6 +298,7 @@ const KNOWLEDGE_BASE = {
 | gh 命令 | 插件调用 | 备注 |
 | :--- | :--- | :--- |
 | \`gh issue list/view/create/comment/close/reopen/edit\` | \`github_issue(action:…)\` | 基础操作 |
+| （Issue 图片查看，gh 无对应命令） | \`github_issue(action:'view_images', issue_number:n)\` | 插件独有：报障截图转图像块 |
 | \`gh issue develop\` | \`github_issue(action:'develop', branch_name:…)\` | 关联开发分支 |
 | \`gh issue delete\` | \`github_issue(action:'delete', confirm:true)\` | 物理删除（非 close） |
 | \`gh issue transfer\` | \`github_issue(action:'transfer', target_repo:…, confirm:true)\` | 跨仓库迁移 |
@@ -271,8 +337,11 @@ 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，6 action）**
+| gh 命令 | 插件调用 | 备注 |
+| :--- | :--- | :--- |
+| \`gh skill search/preview/install/list/publish\` | \`github_skill(action:…)\` | install 需 confirm（写磁盘）；publish 默认 dry-run 安全自检，正式发布需 tag 与 confirm |
+| \`gh skill update\` | \`github_skill(action:'update')\` | 默认 dry-run 检查；\`all:true\` 或 \`skill_names\` 定向；\`dry_run:false\` 才真正更新 |
 
 **Label（github_label，5 action）**
 | gh 命令 | 插件调用 | 备注 |
@@ -304,10 +373,45 @@ const KNOWLEDGE_BASE = {
 | \`gh gist edit\` | \`github_gist(action:'edit', gist_id:…)\` | 描述与文件修改 |
 | \`gh gist delete\` | \`github_gist(action:'delete', gist_id:…, confirm:true)\` | 物理删除，需 confirm |
 
-**Status（github_status，账号维度聚合面板）**
+**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 |
 
 #### 二、归属提示（命令域与工具名不同构）
 
@@ -320,14 +424,10 @@ const KNOWLEDGE_BASE = {
 
 | gh 域 | 用途 | 推荐 REST 端点 |
 | :--- | :--- | :--- |
-| \`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/pulls')\`（原有 \`repos/{o}/{r}/labels\` 端点已由原生 \`github_label\` 工具接管）`,
     search_syntax: `### 🔍 GitHub 官方高级检索语法速查手册
@@ -361,7 +461,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 {
@@ -387,6 +498,10 @@ export function createHelpTool(executor) {
                         'cache',
                         'gist',
                         'status',
+                        'agent_task',
+                        'discussion',
+                        'project',
+                        'codespace',
                         'mapping',
                         'search_syntax',
                         'troubleshooting',

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

@@ -37,6 +37,33 @@ export declare function sniffImageMime(buf: Buffer): string | null;
 /** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
 export declare const IMG_MAX_BYTES: number;
 export declare const IMG_DIR_MAX_BYTES: number;
+export declare const IMG_DIR_LOW_WATERMARK: number;
+/**
+ * 图片落盘目录（按内容寻址命名，重复下载天然去重）。
+ *
+ * 为什么支持 DSH_IMAGE_DIR 覆盖：目录里有 LRU 淘汰，按 mtime 删最旧文件。
+ * 若测试把 13MB 假数据写进真实用户目录，淘汰就会优先命中用户更早下载的
+ * 真图（用户图 mtime 更老，排序更靠前），造成静默数据丢失。
+ * 测试必须能把目录重定向到临时区——这与 upgrade-manager 的 DSH_CLI_BIN /
+ * DSH_PROFILE_DIR 覆盖是同一套思路。
+ */
+export declare function imageStoreDir(): string;
+/** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
+export declare function imageDirSize(dir: string): number;
+export interface LruEvictionResult {
+    freedBytes: number;
+    evictedCount: number;
+    evictedFiles: string[];
+}
+/**
+ * LRU 图片缓存淘汰：当目录空间不足以容纳新图片时，按最后修改时间（mtime）淘汰最旧的历史文件。
+ *
+ * 护栏纪律：
+ * 1. 保护当前批次已写入的文件（protectFiles）：避免同一批次内前一张图被后一张图立即顶替；
+ * 2. 仅淘汰历史文件：按 mtime 升序排列（最旧优先），逐一清理直到目录大小降至目标低水位；
+ * 3. 容错防御：单文件删除失败（如文件被锁定）静默跳过继续尝试下一个，绝不崩溃中断。
+ */
+export declare function evictLruImages(dir: string, neededBytes: number, protectFiles?: Set<string>, maxDirBytes?: number, targetBytes?: number): LruEvictionResult;
 export interface DownloadedImage {
     file: string;
     mimeType: string;

package/lib/tools/image-utils.js

@@ -132,12 +132,24 @@ export function sniffImageMime(buf) {
 /** 图片下载护栏：按真实资源消耗计算——单图字节与目录总量，无张数截断 */
 export const IMG_MAX_BYTES = 5 * 1024 * 1024; // 单图 5MB
 export const IMG_DIR_MAX_BYTES = 15 * 1024 * 1024; // 图片缓存目录总量 15MB
-/** 图片落盘目录（按内容寻址命名，重复下载天然去重） */
-function imageStoreDir() {
+export const IMG_DIR_LOW_WATERMARK = 10 * 1024 * 1024; // LRU 淘汰低水位目标 10MB
+/**
+ * 图片落盘目录（按内容寻址命名，重复下载天然去重）。
+ *
+ * 为什么支持 DSH_IMAGE_DIR 覆盖：目录里有 LRU 淘汰，按 mtime 删最旧文件。
+ * 若测试把 13MB 假数据写进真实用户目录，淘汰就会优先命中用户更早下载的
+ * 真图（用户图 mtime 更老，排序更靠前），造成静默数据丢失。
+ * 测试必须能把目录重定向到临时区——这与 upgrade-manager 的 DSH_CLI_BIN /
+ * DSH_PROFILE_DIR 覆盖是同一套思路。
+ */
+export function imageStoreDir() {
+    const override = (process.env.DSH_IMAGE_DIR || '').trim();
+    if (override)
+        return path.resolve(override);
     return path.join(os.homedir(), '.dsh', 'data', 'dsh-github-flow', 'images');
 }
 /** 粗略统计图片目录现有总量（遍历一次，文件数有护栏上限不会失控） */
-function imageDirSize(dir) {
+export function imageDirSize(dir) {
     let total = 0;
     try {
         for (const f of fs.readdirSync(dir)) {
@@ -150,6 +162,57 @@ function imageDirSize(dir) {
     catch { }
     return total;
 }
+/**
+ * LRU 图片缓存淘汰：当目录空间不足以容纳新图片时，按最后修改时间（mtime）淘汰最旧的历史文件。
+ *
+ * 护栏纪律：
+ * 1. 保护当前批次已写入的文件（protectFiles）：避免同一批次内前一张图被后一张图立即顶替；
+ * 2. 仅淘汰历史文件：按 mtime 升序排列（最旧优先），逐一清理直到目录大小降至目标低水位；
+ * 3. 容错防御：单文件删除失败（如文件被锁定）静默跳过继续尝试下一个，绝不崩溃中断。
+ */
+export function evictLruImages(dir, neededBytes, protectFiles = new Set(), maxDirBytes = IMG_DIR_MAX_BYTES, targetBytes = IMG_DIR_LOW_WATERMARK) {
+    const result = { freedBytes: 0, evictedCount: 0, evictedFiles: [] };
+    if (!fs.existsSync(dir))
+        return result;
+    let currentSize = imageDirSize(dir);
+    if (currentSize + neededBytes <= maxDirBytes) {
+        return result;
+    }
+    const candidates = [];
+    try {
+        const entries = fs.readdirSync(dir);
+        for (const name of entries) {
+            const fullPath = path.join(dir, name);
+            if (protectFiles.has(fullPath))
+                continue;
+            try {
+                const stat = fs.statSync(fullPath);
+                if (stat.isFile()) {
+                    candidates.push({ path: fullPath, size: stat.size, mtime: stat.mtimeMs });
+                }
+            }
+            catch { }
+        }
+    }
+    catch {
+        return result;
+    }
+    candidates.sort((a, b) => a.mtime - b.mtime);
+    for (const item of candidates) {
+        if (currentSize + neededBytes <= maxDirBytes && currentSize <= targetBytes) {
+            break;
+        }
+        try {
+            fs.unlinkSync(item.path);
+            currentSize -= item.size;
+            result.freedBytes += item.size;
+            result.evictedCount++;
+            result.evictedFiles.push(item.path);
+        }
+        catch { }
+    }
+    return result;
+}
 /**
  * 交集过滤：把调用方请求的 URL 硬约束在正文实际提取的合法清单内。
  * 为什么必须交集而非直接信任传入：image_urls 来自模型生成参数，存在幻觉或
@@ -190,6 +253,7 @@ export async function downloadImages(urls, run) {
     const images = [];
     const failures = [];
     const remaining = [];
+    const currentBatchFiles = new Set();
     let budgetExhausted = false;
     // 无张数截断：字节护栏按真实资源消耗逐张判定。触顶后仍继续遍历——
     // 剩余 URL 全部收进 remaining 供 Agent 分批续传，而非静默丢弃。
@@ -213,6 +277,11 @@ export async function downloadImages(urls, run) {
             failures.push(`${url.slice(-24)}: 内容不是图片（魔数校验失败）`);
             continue;
         }
+        // 空间护栏检查：若超出目录上限，优先触发 LRU 淘汰历史文件以腾出预算
+        if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
+            const { freedBytes } = evictLruImages(dir, buf.length, currentBatchFiles);
+            dirSize = Math.max(0, dirSize - freedBytes);
+        }
         if (dirSize + buf.length > IMG_DIR_MAX_BYTES) {
             budgetExhausted = true;
             remaining.push(url);
@@ -222,6 +291,7 @@ export async function downloadImages(urls, run) {
         const ext = mime.includes('svg') ? 'svg' : mime.split('/')[1].replace('jpeg', 'jpg');
         const file = path.join(dir, `${crypto.createHash('sha256').update(buf).digest('hex').slice(0, 16)}.${ext}`);
         fs.writeFileSync(file, buf);
+        currentBatchFiles.add(file);
         // 累计已写入量：下张图的总量护栏判定必须基于最新值（否则多图可突破上限）
         dirSize += buf.length;
         images.push({ file, mimeType: mime, url, bytes: buf.length });

package/lib/tools/project.d.ts

@@ -0,0 +1,80 @@
+import type { GhExecutor } from '../executor.js';
+/**
+ * 检测错误信息是否属于 Scope 权限不足，并返回标准自愈对象
+ */
+export declare function checkScopeRequired(errorMsg: string, scope: string, command: string, tool: string): {
+    status: string;
+    scope: string;
+    command: string;
+    tool: string;
+} | null;
+export declare function createProjectTool(executor: GhExecutor): {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            owner: {
+                type: string;
+                description: string;
+            };
+            project_number: {
+                type: string;
+                description: string;
+            };
+            item_id: {
+                type: string;
+                description: string;
+            };
+            url: {
+                type: string;
+                description: string;
+            };
+            title: {
+                type: string;
+                description: string;
+            };
+            body: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            closed: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: 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> | {
+        status: string;
+        scope: string;
+        command: string;
+        tool: string;
+    }>;
+};