dsh-harness-push 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [1.0.1] - 2026-10-22
+
+### 修复
+
+- **智能体不再能自行执行审查**：此前 agent 在「推送 / 提交 / 发布」任务里会反复自动调用审查，既不弹窗也不让用户选择审查内容——一个用户看不见、也管不了的安全步骤等于没有。现在工具 `review` **只登记待确认请求**，面板轮询到后打开与人工点击完全相同的审查弹窗，用户勾选审查项后才执行；已有待确认请求时返回 `already_pending`，从机制上阻止反复请求。弹窗会标注「Agent 请求」，关闭或开始后自动清理请求。
+- **语言构成条改用 GitHub 官方配色**：此前按段序取色（第 1 段品牌色、第 2 段成功色…），所以第一段总显示为黑色，其余颜色也没有含义。现在按语言名查 GitHub linguist 官方色：JavaScript `#F1E05A`、TypeScript `#3178C6`、Python `#3572A5`、HTML `#E34C26`、CSS `#563D7C`、Go `#00ADD8`、Rust `#DEA584`、Vue `#41B883` 等；未知语言按名称散列出色相，稳定且互不同色。
+
+### 测试
+
+- 新增 `verify-review-gate.mjs`（22 项），锁死「审查必须经用户确认」与「按语言名配色」两处行为
+
+## [1.0.0] - 2026-10-22
+
+首个公开发布版本。
+
+> 发布包名为 **`dsh-harness-push`**；GitHub 仓库名为 `dsh-push`。
+> npm 上的 `dsh-push` 已被另一个用途无关的插件占用，因此发布包改了名，
+> 插件内部标识（工具名、路由、界面入口）保持不变。
+
+### 新增
+
+- **设置页 Push**：多账号卡片（头像 / 昵称 / 权限范围）、下拉切换与移除、跳转账号主页
+- **账号录入**：Personal Access Token 与 Device Flow 设备码两种方式
+- **账号概览**：最近一年贡献热力图、未读通知（可标记已读并跳转）
+- **仓库管理弹窗**：概览指标、分支、设置、发布（含附件上传与删除）、协作者、Webhook、危险操作区
+- **左侧栏仓库面板**：搜索、私有/公开分段、分页、新建与删除仓库
+- **列表 / 卡片双视图**：卡片分大小两档且默认卡片；底部语言占比条形图；star / fork / issue 横排指标；简介独立滚动区
+- **工作区侧边栏**：状态、提交、推送、拉取、抓取、撤回（soft/mixed/hard）、分支、标签、stash、改动分组、提交图
+- **推送目标选择**：搜索 GitHub 仓库或使用本地远端，并按分支记忆上次目标
+- **推送前 Agent 审查**：内置 8 项审查规则（4 类）、自定义提示词与预设存档、模型与思考强度可选、规则扫描 + 模型审查双层
+- **审查可与待推送提交对齐**：工作区干净时自动改为审查即将推送的提交，并在结果中标注 `scope`
+- **模型工具 `github_link`**：`status` / `log` / `push` / `pull` / `commit` / `repos` / `accounts` / `create_repo` / `release` / `review`
+- **诊断端点** `GET /api/push/diagnostics`：报告模型工具注册状态，便于排查「智能体看不到工具」
+- **契约守卫测试**：客户端调用的每条路由都必须出现在 `CONTRACT.md` 中，且文档中的每条路由都必须真实存在
+
+### 修复
+
+- **git 推送认证方案错误**：git 智能 HTTP 使用 HTTP Basic 认证，此前发送 `Bearer` 导致端点返回 401、git 转而索要密码，推送始终失败。已改为 `Authorization: Basic base64(x-access-token:<token>)`
+- **凭据暴露在进程命令行**：认证信息曾作为 `-c` 参数进入 git 子进程 argv，本机其他账号可读取进程命令行。现改为通过 `GIT_CONFIG_*` **环境变量**注入，argv 中不再出现任何凭据
+- **模型工具从未注册成功**：输出 schema 使用了 `type: [...]` 与 `anyOf`，超出宿主支持的 schema 子集，注册抛错且被静默吞掉。已收敛到子集内表达，并新增失败记录与诊断端点
+- **审查结果无法回传给模型**：findings 中的 `undefined` 字段使结果不是无损 JSON，工具调用被拒。现改为逐字段投影，缺失值转 `null`
+- **侧边栏打开即崩**：审查弹窗与 `useState` 曾被插入条件分支内部，正常仓库路径下 `reviewResult` 未定义。已移至组件顶部
+- **删除仓库永远失败**：注释里一个转义的 `\n` 把 `body:` 属性整行吞进注释，删除请求因此没有请求体，两个入口都返回参数错误。已修复
+- **设置页点击仓库卡片抛异常**：卡片调用了 `SettingsSection` 从未传入的 `onOpenManage`，而卡片正是默认视图，首次点击即报错。已改为使用组件自身的 `setManageRepo`
+- **暂存按钮文案误导**：按钮显示「暂存 / 取消暂存」，实际只切换「是否包含在本次提交」。已改为「包含 / 排除」
+- **附件操作反馈不可见**：上传/删除成功后设置了提示状态却从未渲染。已显示
+- **设置页语言条恒为空**：只有完整仓库页预取了语言数据，设置页卡片从未预取。已补上
+- **卡片语言条显示为纯黑**：内联 `var()` 背景无法解析时回退为首色（黑），改为由样式表按 `data-tone` 上色
+- **卡片指标样式错乱**：`.dsh-push-stat` 与仓库概览页的方框指标类名冲突，继承了边框与内边距。已拆分为独立的 `dsh-push-metric`
+- **卡片简介挤压指标**：简介改为固定高度滚动区，指标行固定在滚动区之外，卡片高度固定以保证网格对齐
+- **错误信息脱敏遗漏**：脱敏正则只匹配 `Bearer`，切换到 Basic 后凭据可能泄漏；PEM 私钥块也未覆盖。现对任意认证方案与私钥块生效
+- **`mutate()` 丢失审查预设**：状态写入用显式字段清单构造草稿，漏掉 `reviewPresets` 导致保存后读不到。已补齐并有回归测试
+- **发布路径泄漏**：README 安装示例含开发者本机绝对路径与用户名，已替换为占位符
+- **`state.json` BOM 导致账号丢失**：读取前剥离 UTF-8 BOM
+- **删除仓库误报成功**：404 曾被视为删除成功，现先探测仓库是否仍可读，并强制显式确认
+- **契约漂移**：`/repos/languages`、`/releases/asset`、`/releases/asset/delete`、`/local/push/target/forget`、`RemoteRepo.forks` 等实现早已存在但未写入契约，已补齐。
+
+### 安全
+
+- Token 仅存于 `%DSH_HOME%\push\state.json`：POSIX 以 `0600` 写入，Windows 追加 `icacls` 限制为当前用户；不进入 HTTP 响应、日志、git 回显或工具结果
+- 推送凭据通过子进程环境注入，**既不写入 `.git/config`，也不出现在命令行**
+- 规则扫描命中的密钥原文永不外泄；PEM 私钥块与占位符分别处理（后者不误报）
+
+### 测试
+
+- 11 组测试套件 + 路由可达性审计，覆盖客户端源断言、仓库卡片、工具契约、错误映射、推送记忆、删除语义、审查规则与范围、审查预设持久化、契约一致性、可达性

package/CONTRACT.md

@@ -0,0 +1,506 @@
+# dsh-push 内部契约（Host ⇄ Client）
+
+本文件是 Host 与 Client 两半共享的唯一契约。任何一方改动都必须先改这里。
+
+## 0. 通用约定
+
+- HTTP 前缀：`/api/push`
+- 所有响应为 JSON，统一信封：
+  - 成功：`{ "ok": true, "data": <payload> }`
+  - 失败：`{ "ok": false, "error": { "code": "<CODE>", "message": "<人类可读中文>" , "status"?: <github http status> } }`
+- 非 GET 请求必须带请求头 `x-dsh-plugin: push`（CSRF 约定），缺失返回 403 `FORBIDDEN`。
+- 客户端只通过 `fetch` 调这些路由，`credentials: 'same-origin'`，不要另起 RPC。
+- 所有时间戳为 ISO 8601 字符串；所有 id 为字符串。
+- 错误码常量（Host 与 Client 都要用）：`FORBIDDEN`、`BAD_REQUEST`、`NOT_FOUND`、`NO_ACCOUNT`、`UNAUTHORIZED`(token 失效)、`RATE_LIMITED`、`NETWORK`、`GIT_MISSING`、`GIT_FAILED`、`NOT_A_REPO`、`CONFLICT`、`INTERNAL`。
+
+## 1. 账号（多账号登录/切换）
+
+账号对象 `Account`：
+```ts
+{
+  id: string,            // 本地稳定 id（login 的小写）
+  login: string,
+  name: string | null,
+  avatarUrl: string | null,
+  htmlUrl: string | null,
+  tokenKind: 'pat' | 'oauth',   // 录入方式
+  scopes: string[],             // 来自 x-oauth-scopes 响应头（无则 []）
+  addedAt: string,
+  lastUsedAt: string | null
+}
+```
+
+`GET /state` →
+```ts
+{
+  accounts: Account[],
+  activeAccountId: string | null,
+  settings: {
+    oauthClientId: string,     // 空串表示未配置设备码登录
+    defaultRemote: string,     // 默认 'origin'
+    showPrivate: boolean,
+    gitPath: string            // 空串表示用 PATH 里的 git
+  },
+  gitAvailable: boolean,
+  gitVersion: string | null
+}
+```
+
+- `POST /accounts/token` body `{ token: string, label?: string }` → `{ accounts, activeAccountId }`
+  - Host 用该 token 调 `GET /user` 校验；失败返回 `UNAUTHORIZED`。
+  - 同一 login 再次提交 = 覆盖 token（不新建）。
+- `POST /accounts/device/start` body `{}` →
+  `{ verificationUri: string, userCode: string, deviceCode: string, expiresIn: number, interval: number }`
+  - 未配置 `oauthClientId` 时返回 `BAD_REQUEST`。
+- `POST /accounts/device/poll` body `{ deviceCode: string }` →
+  `{ status: 'pending' | 'slow_down' | 'done', accounts?, activeAccountId? }`
+- `POST /accounts/activate` body `{ accountId: string }` → `{ activeAccountId }`
+- `POST /accounts/remove` body `{ accountId: string }` → `{ accounts, activeAccountId }`
+- `POST /settings` body `Partial<settings>` → `{ settings }`
+
+## 2. 仓库（远端）
+
+远端仓库对象 `RemoteRepo`：
+```ts
+{
+  id: string, owner: string, name: string, fullName: string,
+  private: boolean, fork: boolean, archived: boolean,
+  defaultBranch: string, description: string | null,
+  updatedAt: string, pushedAt: string | null,
+  htmlUrl: string, cloneUrl: string, sshUrl: string,
+  permissions: { admin: boolean, push: boolean, pull: boolean } | null,
+  language: string | null, stars: number, openIssues: number,
+  ownerAvatar: string | null
+}
+```
+
+- `GET /repos?page=1&q=&affiliation=owner,collaborator,organization_member&sort=updated` →
+  `{ items: RemoteRepo[], page: number, hasMore: boolean, total?: number }`
+  - `q` 非空时走 `GET /search/repositories?q=<q>`（`user:<login>` 前缀 + 关键词），结果同样映射为 `RemoteRepo`。
+- `GET /repos/detail?owner=&name=` → `{ repo: RemoteRepo, branches: Branch[] }`
+  其中 `Branch = { name: string, sha: string, protected: boolean }`
+- `POST /repos/create` body `{ name, private=true, description='', autoInit=false }` → `{ repo: RemoteRepo }`
+- `POST /repos/delete` body `{ owner, name }` → `{ deleted: true }`（需 `delete_repo` scope，否则 `UNAUTHORIZED` 并给中文提示）
+- `GET /releases?owner=&repo=` → `{ items: Release[] }`
+- `POST /releases` body `{ owner, repo, tagName, name?, body?, target?, draft=false, prerelease=false }` → `{ release: Release }`
+
+`Release = { id: string, tagName: string, name: string | null, draft: boolean, prerelease: boolean, createdAt: string, htmlUrl: string }`
+
+只读的账号活动（`login` 省略时用当前账号）：
+
+- `GET /contributions?login=&days=365` → 贡献日历（走 GraphQL `contributionsCollection`）
+```ts
+{
+  total: number, days: { date: 'YYYY-MM-DD', count: number, weekday: 0-6 }[],  // 按 date 升序，Client 直接画格子
+  weeks: number, restricted: number, login: string, from: string, to: string
+}
+```
+  - 令牌缺 `read:user` 时**不报错**，返回 `{ unavailable: true, reason: 'SCOPE', message: '贡献图需要令牌具备 read:user 权限；当前令牌没有该权限。' }` 且 `ok:true`，面板渲染行内提示即可。真正的网络失败仍是 `NETWORK`。
+- `GET /notifications?all=false&limit=30` → `{ items: Notification[], unreadCount: number }`（`unreadCount` 为当前页未读数）
+```ts
+Notification = {
+  id: string, title: string, type: string,   // 'Issue' | 'PullRequest' | 'Release' | 'Discussion' | 'Commit' | ...
+  repo: string,                              // 'owner/name'
+  reason: string,                            // 'review_requested' | 'mention' | 'subscribed' | ...
+  unread: boolean, updatedAt: string,
+  url: string                                // 网页地址，由 subject.url 的 API 地址换算
+}
+```
+  - `url` 换算：`pulls/{n}`→`/pull/{n}`、`issues/{n}`→`/issues/{n}`、`commits/{sha}`→`/commit/{sha}`、`discussions/{n}`→`/discussions/{n}`、`releases/{n}`→`/releases`，其它一律 `https://github.com/{repo}`。
+- `POST /notifications/read` body `{ id }` → `{ read: true }`（`PATCH /notifications/threads/{id}`；205 无响应体也算成功）
+
+## 3. 本地仓库（Git）
+
+- `GET /local/status?path=<绝对路径>` →
+```ts
+{
+  isRepo: boolean,
+  root: string | null,             // rev-parse --show-toplevel
+  gitDir: string | null,
+  branch: string | null,           // 分离 HEAD 时为 null
+  detachedHead: boolean,
+  upstream: string | null,         // 如 'origin/main'
+  ahead: number, behind: number,
+  remotes: { name: string, url: string }[],
+  githubRemote: { name: string, owner: string, repo: string, url: string } | null,
+  head: { sha: string, shortSha: string, subject: string, author: string, date: string } | null,
+  dirty: { changed: number, staged: number, untracked: number, conflicted: number },
+  files: { path: string, index: string, worktree: string, staged: boolean, untracked: boolean, conflicted: boolean }[],
+  tags: string[],
+  branches: string[],
+  stashes: { index: number, message: string }[]
+}
+```
+- `GET /local/log?path=&limit=60&ref=` →
+  `{ commits: Commit[], hasMore: boolean }`
+```ts
+Commit = {
+  sha: string, shortSha: string, parents: string[], author: string, authorEmail: string,
+  date: string, subject: string, refs: string[],   // 装饰引用，如 ['HEAD -> main','origin/main','tag: v1']
+  lane: number                                     // Host 计算好的图列（0..N），Client 直接画
+}
+```
+- `GET /local/diff?path=&file=&staged=true|false` → `{ file: string, patch: string }`（`git diff` 原文，可能很长；Host 截断到 200_000 字符并给 `truncated: true`）
+- `GET /local/commit?path=&sha=` → `{ sha, subject, body, author, date, files: { path, additions, deletions }[] , patch: string }`
+- `GET /local/remotes?path=` → `{ remotes }`
+
+写操作（全部 POST，body 都带 `path`）：
+
+| 路由 | body | 说明 |
+|---|---|---|
+| `/local/init` | `{ path, name?, owner?, private?, remoteName='origin', createRemote=false }` | `git init` + 可选在 GitHub 建仓 + `remote add` + 首次 `git add -A`（不自动提交） |
+| `/local/remote` | `{ path, name='origin', url }` | 增改远端；url 为 GitHub 时顺便解析 owner/repo |
+| `/local/fetch` | `{ path, remote='origin', prune=false }` | |
+| `/local/pull` | `{ path, remote='origin', branch?, rebase=false }` | |
+| `/local/push` | `{ path, remote='origin', branch?, force=false, setUpstream=true, tags=false }` | 一键推送 |
+| `/local/commit` | `{ path, message, all=true, files?: string[] }` | `all` 时 `git add -A` 后提交 |
+| `/local/checkout` | `{ path, ref, create=false }` | ref 可为分支/sha/tag |
+| `/local/branch` | `{ path, name, from?, checkout=true }` | 新建分支 |
+| `/local/branch/delete` | `{ path, name, force=false }` | |
+| `/local/merge` | `{ path, ref }` | |
+| `/local/reset` | `{ path, ref='HEAD', mode='mixed' }` | 撤回：soft/mixed/hard |
+| `/local/revert` | `{ path, sha }` | |
+| `/local/revert-commit` | `{ path, sha }` | `git revert --no-edit <sha>` |
+| `/local/tag` | `{ path, name, ref='HEAD', push=false, remote='origin' }` | |
+| `/local/stash` | `{ path, message?, includeUntracked=true }` | |
+| `/local/stash/pop` | `{ path, index=0 }` | |
+| `/local/restore` | `{ path, files: string[], staged=false }` | 丢弃工作区改动 |
+| `/local/discard-all` | `{ path }` | 危险操作，`git reset --hard` + 清 untracked |
+
+所有写操作返回 `{ ok:true, data: { output: string } }`，`output` 为 git 的 stdout+stderr 合并（截断 20_000 字符）。失败返回 `GIT_FAILED` 并带原始输出。
+
+## 3b. 推送目标（远端仓库选择 + 按分支记忆）
+
+推送目标不再依赖全局 `defaultRemote`。分三层：
+
+1. **远端（git remote）**：本地已有的 remote name，例如 `origin`、`fork`。
+2. **目标 GitHub 仓库**：一个远端可以指向任意仓库；用户想推到「另一个 GitHub 仓库」时，本地可能还没有对应 remote。
+3. **记忆**：`(仓库根, 分支)` → 上次成功推送的目标，下次默认选中。
+
+- `GET /push/targets?path=` → 选择器用的候选集合
+```ts
+{
+  remotes: { name: string, url: string, owner: string | null, repo: string | null }[],
+  memory: { remote: string, owner: string, repo: string, ref: string, at: string } | null,  // 当前分支的记忆
+  branch: string | null,
+  repoRoot: string | null
+}
+```
+  - `memory` 是**当前分支**上次成功推送的目标；没有则 `null`。
+
+- `GET /push/remotes?q=&page=1` → 在已登录账号的 GitHub 仓库中检索（供「下拉选择」与「键入搜索」两种 UI）
+```ts
+{
+  items: { fullName: string, owner: string, name: string, private: boolean,
+           defaultBranch: string, cloneUrl: string, sshUrl: string, htmlUrl: string }[],
+  page: number, hasMore: boolean
+}
+```
+  - `q` 为空时按最近更新列出；非空时匹配 `owner/name` 与描述。
+
+- `POST /local/push` **新增可选字段**：
+```ts
+{
+  path, branch?, force?, setUpstream?, tags?,
+  remote?: string,                            // 已有 remote 名（二选一）
+  target?: { owner: string, repo: string },   // 直接指定 GitHub 仓库（二选一）
+  remember?: boolean                          // 默认 true；成功后写入记忆
+}
+```
+  - 传 `target` 且本地没有对应 remote 时，**不得污染用户 .git/config**：若已有 remote 指向同一仓库则复用；否则以远端 URL 形式推送（`git push <url> <ref>`），令牌沿用现有 `http.extraheader` 机制，绝不落盘。
+  - 成功后按 `(repoRoot, branch)` 记录 `{ remote, owner, repo, ref, at }`；`branch` 省略时取当前分支。
+
+- `GET /push/memory?path=` → `{ entries: { branch, remote, owner, repo, ref, at }[] }`（全部分支，调试用）
+
+记忆持久化：状态文档新增 `pushMemory` 表，键 `<repoRoot>|<branch>`。路径需规范化（统一分隔符、盘符小写），避免同一仓库因写法不同丢记忆。
+
+### `/local/push` 的版本来源
+
+`POST /local/push` 的 body 除 `branch` / `force` / `remote` / `target` 外，还接受：
+
+```ts
+{
+  source?: string   // 要推送的 ref：分支名、标签名或 40 位 sha
+}
+```
+
+- 省略时等于 `branch`（推当前分支）
+- 指定 sha 或标签时，Host 构造 `<source>:refs/heads/<branch>` 形式的 refspec，
+  因此「推送某个指定版本」不会悄悄退化成推送当前分支
+- 目标分支缺失时先返回 `BAD_REQUEST`，不会发起任何网络请求
+
+
+## 3c. 仓库管理（弹窗所需的聚合能力）
+
+`GET /repos/manage?owner=&name=` →
+```ts
+{
+  repo: RemoteRepo,
+  branches: { name: string, sha: string, protected: boolean }[],
+  topics: string[],
+  stats: { stars: number, forks: number, watchers: number, openIssues: number, openPRs: number,
+           sizeKb: number, language: string | null, license: string | null,
+           createdAt: string, updatedAt: string, pushedAt: string | null },
+  releases: Release[],
+  collaborators: { login: string, avatarUrl: string | null, role: string }[] | null,
+  webhooks: { id: string, url: string, events: string[], active: boolean }[] | null,
+  warnings: string[],
+  can: { admin: boolean, push: boolean, delete: boolean }
+}
+```
+  - 任一子项失败**不得**让整体失败：该字段返回 `null`，并在 `warnings` 写中文原因（如缺 `admin:repo_hook` 读不到 webhook）。
+
+写操作（全部 POST，失败给中文原因）：
+
+| 路由 | body | 说明 |
+|---|---|---|
+| `/repos/update` | `{ owner, name, description?, homepage?, private?, archived?, topics?, defaultBranch? }` | 改元信息 |
+| `/repos/branch/rename` | `{ owner, name, from, to }` | 重命名分支 |
+| `/repos/branch/delete` | `{ owner, name, branch }` | 删除远端分支 |
+| `/repos/branch/protect` | `{ owner, name, branch, protected }` | 保护/取消保护（需 admin） |
+| `/repos/release/delete` | `{ owner, name, id }` | 删除发布 |
+| `/repos/release/update` | `{ owner, name, id, name?, body?, draft?, prerelease? }` | 编辑发布 |
+| `/repos/collaborator/add` | `{ owner, name, user, permission }` | 添加协作者（需 admin） |
+| `/repos/collaborator/remove` | `{ owner, name, user }` | 移除协作者 |
+| `/repos/rename` | `{ owner, name, newName }` | 重命名仓库（危险，需 `confirm: true`） |
+| `/repos/transfer` | `{ owner, name, newOwner }` | 转移仓库（危险，需 `confirm: true`） |
+
+`/repos/rename`、`/repos/transfer` 与既有 `/repos/delete` 一律要求 `confirm: true`，否则返回 `CONFLICT` 并附中文说明。
+
+## 3d. 推送前审查（Agent Review）
+
+在推送前让模型检查「这次要推的内容」，把风险在离开本机之前拦下来。审查复用宿主已注册的
+`llm` 服务，不自行发起 HTTP，因此走同一个 provider、同一套凭据与重试策略。
+
+### 预设与自定义提示词
+
+- `GET /review/presets` →
+```ts
+{
+  builtin: ReviewPreset[],   // Host 内置，只读
+  custom: ReviewPreset[],    // 用户存档
+  categories: { id: string, label: string }[]
+}
+```
+```ts
+ReviewPreset = {
+  id: string,
+  category: string,          // 'secrets' | 'privacy' | 'integrity' | 'quality' | 'custom'
+  title: string,
+  description: string,       // 一句话说明它查什么
+  prompt: string,            // 发给模型的指令
+  builtin: boolean,
+  createdAt?: string,
+  updatedAt?: string
+}
+```
+  内置分类至少包含：**敏感信息**（令牌、私钥、密码、身份证/手机号/邮箱、内网地址、
+  设备与用户名痕迹）、**隐私**（个人姓名、绝对路径中的用户名、机器名）、
+  **完整性**（空实现、调试残留、被删除的测试、冲突标记、未跟踪依赖）、
+  **质量**（明显 bug、错误处理缺失、硬编码配置）。
+
+- `POST /review/presets` body `{ title, description?, prompt, category? }` → `{ preset: ReviewPreset }`
+  存档一条自定义提示词；`title` 与 `prompt` 必填且非空。
+- `POST /review/presets/delete` body `{ id }` → `{ deleted: true }`
+  只能删自定义预设；删内置返回 `CONFLICT`。
+
+### 审查请求闸门（agent 不得自行审查）
+
+智能体**不能**直接执行审查。它只能登记一个待确认请求，由界面弹出与人工点击
+相同的审查弹窗，用户选择审查项后才真正开跑。原因：审查是安全步骤，用户必须
+看得见、能决定审查什么；早期允许直接执行时，agent 会在「推送」任务里反复自动
+审查而不提示用户。
+
+- `GET /review/pending?path=` → `{ pending: { id, path, presetIds, customPrompt, source, createdAt } | null }`
+  - 客户端轮询它；非空即打开审查弹窗，并用 `presetIds` 预选、`customPrompt` 预填
+  - 同一时刻只保留**一个**待确认请求
+
+- `POST /review/pending/clear` body：`{ id?: string }` → `{ cleared: boolean }`
+  - 用户开始审查或关闭弹窗时调用；`id` 不匹配则不清理（避免误清掉新请求）
+
+工具 `review` 的行为：
+
+```ts
+{ reviewRequest: {
+    status: 'awaiting_user' | 'already_pending',
+    message: string,   // 给模型看的说明：等用户确认，不要重复调用
+    pending: object | null
+} }
+```
+
+- **不再返回 findings**：结果由界面在用户确认后产生
+- 已有待确认请求时返回 `already_pending`，这是阻止 agent 反复请求的机制
+
+
+### 审查执行
+
+- `POST /review/run` body：
+```ts
+{
+  path: string,                       // 仓库绝对路径
+  presetIds?: string[],               // 选中的内置/自定义预设
+  customPrompt?: string,              // 本次临时输入的额外指令（可空）
+  provider?: string, model?: string,  // 省略时用宿主默认模型
+  reasoningEffort?: string,           // 省略时用该模型默认档
+  staged?: boolean,                   // true 只审已暂存；false 审全部未推送改动
+  includeFiles?: string[],            // 限定文件；省略=按下面规则自动选
+  maxFiles?: number                   // 默认 60
+}
+```
+  → `{ reviewId, model, effort, files, findings, summary, usage }`
+
+```ts
+{
+  reviewId: string,
+  model: { provider: string, model: string, label: string } | null,
+  effort: string | null,
+  scope: 'working' | 'outgoing',   // 审的是工作区改动还是待推送提交
+  outgoingCommits: number,         // scope=outgoing 时的提交数，否则 0
+  truncated: boolean,              // 改动过多、有内容未送审
+  degraded: boolean,               // 模型未参与、只跑了规则扫描
+  files: { path: string, additions: number, deletions: number, skipped?: string }[],
+  findings: {
+    severity: 'blocker' | 'high' | 'medium' | 'low' | 'info',
+    category: string,
+    title: string,
+    detail: string,
+    file?: string,
+    line?: number,
+    suggestion?: string
+  }[],
+  summary: string,
+  usage?: { inputTokens: number, outputTokens: number }
+}
+```
+
+规则：
+
+1. **只审将要推送的差异**。默认取 `HEAD` 与工作区的差异（含未跟踪文件，逐个读取内容）；
+   `staged: true` 时只取 `--cached`。单文件内容超过 200 KB 或二进制时标记 `skipped`。
+2. **工作区没有改动时，改审待推送提交**。推送前的常态是工作区干净、提交已就绪，
+   此时若只读工作区就会返回「无改动」并零发现——对安全功能而言这是最糟的静默漏报。
+   回退规则：有 upstream 时以 `merge-base(upstream, HEAD)` 为基准；无 upstream 时以
+   `refs/remotes/origin/<branch>` 为基准；两者都不存在（分支首次推送）时以空树
+   `4b825dc642cb6eb9a060e54bf8d69288fbee4904` 为基准。结果中的 `scope` 字段标明
+   本次审查的是哪一类（`working` / `outgoing`），`outgoingCommits` 给出待推送提交数。
+3. **模式规则先行**（不花钱）：Host 先用正则扫一遍已知密钥形态
+   （`ghp_[A-Za-z0-9]{36}`、`github_pat_`、`sk-`、`AKIA[0-9A-Z]{16}`、私钥块、
+   `xox[baprs]-`、Bearer 长串、以及 `password` / `token` / `api_key` 等键名后跟长字面量的硬编码密码），命中即产出 `blocker` 级 finding。
+   这样即使模型不可用，最危险的一类问题也有答案。
+4. **模型审查**：把选中预设的 prompt + 自定义提示词拼成一次 `llm` 调用，
+   要求模型只输出 JSON（`{findings:[],summary:""}`）。解析失败时降级：
+   把模型原文放进 `summary` 且 `findings` 为模式规则的结果，不报错。
+5. 令牌等秘密**永不写进 findings**：命中时只保留位置与类型（如 `ghp_…（已隐藏）`）。
+6. **模型不可用**（未注册 provider、鉴权失败、网络错误）：返回
+   `{ ok:true, data:{ ..., model: null, findings: <模式规则结果>, summary: '<中文说明>' } }`，
+   并在 `degraded: true` 标注；绝不因审查失败阻塞推送。
+
+### 模型与强度候选
+
+- `GET /review/models` → `{ providers: { id, name, models: { id, name, efforts: { id, name }[], defaultEffort }[] }[], default: { provider, model } | null }`
+  由 Host 侧 `llm` 服务枚举；宿主没有 `llm` 时返回空数组与 `default: null`，
+  界面据此显示「宿主未提供模型配置」。
+
+## 3e. 仓库信息与发布附件
+
+客户端用到的、与仓库展示和发布相关的能力。
+
+### 语言构成
+
+- `GET /repos/languages?owner=&name=`
+  → `{ items: { name: string, bytes: number, percent: number }[], warning?: string }`
+  - 按字节降序；`percent` 保留一位小数，由 Host 计算，客户端只渲染
+  - 仓库不可见或无语言数据时返回 `{ items: [] }`，**不报错**（卡片只是不画条形图）
+
+### 发布附件
+
+- `POST /releases/asset` body：
+```ts
+{
+  owner: string, name: string, releaseId: string,
+  fileName: string,
+  contentType?: string,
+  base64: string        // 文件内容；上限 200 MB，超出返回 BAD_REQUEST
+}
+```
+  → `{ asset: { id, name, size, downloadUrl } }`
+  - 附件上传走 `uploads.github.com`（不是 `api.github.com`），URL 由 `API_BASE` 推导
+
+- `POST /releases/asset/delete` body：`{ owner, name, assetId }` → `{ deleted: true }`
+  - 404 也视为已删除（幂等）
+
+### 修改发布
+
+- `POST /repos/release/update` body：
+```ts
+{
+  owner: string,
+  name: string,         // 仓库名
+  id: string,           // 发布 id
+  releaseName?: string, // 发布标题（不要用 name，那是仓库名）
+  body?: string,
+  draft?: boolean,
+  prerelease?: boolean
+}
+```
+
+> `name` 专指仓库名。发布标题必须用 `releaseName`——早期两者共用 `name`，
+> 对象字面量里重复的键让仓库名被标题覆盖，保存已有发布必然 404。
+
+
+### 发布对象
+
+`Release` 额外携带附件列表，供界面展示与删除：
+```ts
+assets: { id: string, name: string, size: number, downloadUrl: string }[]
+```
+
+### 仓库字段补充
+
+`RemoteRepo` 除 `fork: boolean` 外还带计数 `forks: number`（列表与卡片展示用）。
+
+### 推送记忆
+
+- `POST /local/push/target/forget` body：`{ path, branch? }` → `{ forgotten: true }`
+  - 清除该分支（或全部）的推送目标记忆
+
+### 诊断
+
+- `GET /diagnostics` → `{ toolsService, tool: { name, attempted, registered, visible, inSchemas, error } }`
+  - 回答「智能体为什么看不到 `github_link`」。注册失败会被记录下来而不是只写日志。
+
+
+## 4. Agent 工具（可选但要对齐）
+
+Host 另注册一个工具 `github_link`，`action` 参数取值与上表一致（`status`、`log`、`push`、`pull`、`commit`、`repos`、`accounts`）。它调用同一份 Host 服务方法，不另写逻辑。
+
+## 5. 客户端职责
+
+- `settings.section`：`{ name:'settings.section', id:'push', order:22, label:()=>'GitHub' }`
+  页面内容：
+  1. 账号列表（头像、login、当前标记、切换、移除）+ 添加账号（PAT 输入 / 设备码流程）
+  2. 连接设置（oauthClientId、gitPath、defaultRemote、showPrivate）
+  3. 仓库列表（搜索、私有过滤、分页"加载更多"、点进详情看分支）
+- `sidebar.panellist`：`{ name:'sidebar.panellist', id:'push', order:2, label:()=>'GitHub' }` + `main` key `push` 的整页：仓库浏览 + 新建仓库 + 删除。
+- `ctx.betterSidebar?.registerTab(...)`：id `push`，标题「GitHub 链接」，单实例，组件按当前会话 `scope.cwd` 显示该工作区的本地版本状态、分支、ahead/behind、文件改动、Git 图（最近 60 条，带 lane 连线）、以及提交/推送/拉取/撤回/切分支/打标签/暂存等操作。**这是"工作区侧边栏入口"。**
+- 所有可见文案中文；颜色只用 `--dsw-alias-*` 主题 token；不要渐变、不要 emoji 图标，用内联 SVG。
+
+## 6. 文件归属（避免写冲突）
+
+- `dsh-push/index.js`、`dsh-push/src/host/**` → host-dev
+- `dsh-push/client.js`、`dsh-push/client.css` → client-dev
+- `dsh-push/package.json`、`cordis.patch.yml`、`locale/**`、`icon.svg`、`README.md` → lead
+
+### 动作清单
+
+```text
+status · log · push · pull · commit · repos · accounts
+create_repo · release · review
+```
+
+- `push` / `release` 都接受 `owner` + `repo` 指定目标仓库，因此智能体无需预先配置远端
+- `review` **不执行审查**，只登记待确认请求并返回 `reviewRequest`；用户确认后由界面调用 `reviewRun`
+- 工具结果必须是**无损 JSON**：findings 的缺失字段一律投影为 `null`，不能留 `undefined`
+- schema 只能用宿主支持的子集（`type` / `oneOf` / `properties` / `required` /
+  `additionalProperties` / `items` / `enum` / `const`）；`type: [...]` 与 `anyOf`
+  会让整个注册失败，工具从此对模型不可见

package/LICENSE

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