---
name: guide-inject-ui
description: dsh-git-push 注入与界面：注入内容与开关、侧边栏三选项卡配置项、账号卡与仓库列表读取时机、预览页。处理注入与界面类请求时加载。
whenToUse: 要弄清插件往系统提示词/上下文注入了什么、开关怎么影响、侧边栏配置项含义、账号与仓库列表何时刷新、预览页怎么看时。
updated: 2026-10-02
generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
---

# 注入与界面（guide-inject-ui）

> 一句话定位：插件往 AI 看到的提示词/上下文里注入什么、侧边栏每个开关什么意思、这些数据从哪读、预览页怎么接真实后端。

## 一、规则（场景 → 必须做的）

| 场景 | 必须做的 |
|---|---|
| 判断「AI 为什么看得到/看不到插件功能」 | 先看总开关「注入系统提示词/上下文」；它同时门控两条通道（系统提示词 + 上下文），关掉后两条都不注入 |
| 确认某个注入段是否生效 | 按生效条件逐项核对，不能只看总开关：要求清单段还要「提交前自动审计」+「↳ 注入开发者要求清单」同时开 |
| 改插件配置/开关 | 只改插件私有 `config.json`（侧边栏保存即写它）；不要写公共 `settings.yaml` |
| 刷新账号信息 / 本地仓库列表 | 只在三种时机读取；不轮询、不监听索引文件，页面切 tab 不会刷新 |
| 改了前端界面代码 | 先用 dsh-useful-tools 的 `preview` 工具（`action=gen`）重生成预览页再看，否则看的是旧界面 |

## 二、怎么做 / 命令 / 实例

### 2.1 两条通道、四个段

| 通道 | 段名 | 顺序 | 注入内容 | 生效条件 |
|---|---|---|---|---|
| 系统提示词 | `dsh-git-push-usage` | 990 | 10 个工具各做什么、参数要点、凭据由插件托管、调用纪律 | 注入总开关 |
| 系统提示词 | `dsh-git-push-readme-check` | 991 | 提交前必须核对仓库 README（功能表/版本记录/用法） | 注入总开关 |
| 系统提示词 | `dsh-git-push-requirements` | 992 | 开发者特殊要求清单正文（逐条编号） | 注入总开关 + 提交前自动审计 + ↳ 注入开发者要求清单 |
| 上下文 | 环境注入（`【dsh-git-push 环境注入】`） | — | cwd、项目 git 根、skills 总入口、工作区根 + 子目录、工具实测路径 | 注入总开关；每个 agent 首次 step 注入一次 |

- 系统提示词三段**每步**都带；环境段体积小，只**每个 agent 首次 step 注入一次**（作为一条 user 消息追加）。
- 功能用法段正文可用 `config.json` 的 `injectUsageText`（字符串，或数组按行拼接）覆盖默认文本。

### 2.2 环境段实际注入长这样（目录级，只给路径不给正文）

```
【dsh-git-push 环境注入】
- 当前工作目录 cwd：<会话工作区>
- 运行主机：<主机名>（<本机IP> / 多网卡全列）
- 项目实际目录（git 根）：<git 顶层>
- skills 目录：<项目根>/skills（存在：true/false）
- 工作区根目录：<工作区根>
- 工作区子目录：assets / docs / lib / scripts / skills / test
- 工具：git=/… / node=/… / python3=/… / curl=/…（实测探测结果）
```

- skills 段**只给总入口一行**（路径 + 是否存在），不列 skill 文件清单、不注入 skill 正文。
- 工作区子目录跳过 `.git` / `node_modules` / `dist` / `build` 与隐藏目录。
- 工具路径由 `which`（Windows 走 `where`）实测，结果同时落盘配置目录的 `tools.json`；探测失败降级为静态清单，注入不中断。
- 主机名探测异常时「运行主机」行整行省略，注入不中断。

### 2.3 关闭开关的行为

| 操作 | 结果 |
|---|---|
| 关掉「注入系统提示词/上下文」 | 四个段全部返回空串（段仍注册、内容为空）；AI 看不到功能用法与环境目录，但插件工具照常可用 |
| 关掉「提交前自动审计」 | 要求清单段不注入（子开关勾选保留、该行置灰） |
| 再打开总开关 | 清掉环境注入缓存，下一轮装配即按新状态生效，无需重启实例 |

### 2.4 侧边栏设置（设置 → 侧边栏 → Git 提交推送，三选项卡）

**选项卡一：账号信息**

| 区块 | 内容与行为 |
|---|---|
| 账号卡片 | 渐变面板 + GitHub 图标 + 状态徽标：已连接 / 检测中 / 未连接；下方是后端生成的凭据块 |
| 凭据块 | Token 行尾带 API 配额剩余（如 `（配额剩余5000/h）`，查 GitHub 配额接口不消耗配额；打开页面自动刷新，后端 60s 缓存）；Token 与 SSH 可以是不同账号，不同账号时提示「推送走 SSH 通道」 |
| `⟳ 重新检测` | 在线校验 token/SSH 后写 `account-status.json`，再离线读回 |
| 仓库管理卡片 | 本地 / 云端 两子选项卡 |

- **本地**：默认扫描根 = DSH 家根（动态推导）；可手填路径或用 📂 目录选择器；输入框路径与扫描路径都记住（刷新后恢复）。列表显示 路径 / 分支 · 远端子状态 / 未提交数 / 最近提交 + 索引登记；只显示登录同作者的仓库；有远端且「有未推送提交」（领先数 >0 或状态未知）即可点 `push`（工作树脏不影响），点击后行内绿/红反馈。`扫描` = 独立进程后台离线扫描，每登记一个仓库就追加进列表（不整页重读），扫描中按钮禁用。
- **云端**：`加载仓库列表` 用 token 拉账号名下全部仓库（按最近更新），显示 名称 / 私有·公开 / 默认分支 / 最近更新；行尾 `clone` 弹目录选择器选目标目录后克隆（走 Git Data API，服务端后台跑、进度轮询、刷新后自动接回）。克隆设置：单文件上限（默认 10 MB，0=不限）、并发数（默认 6，1~16）。

**选项卡二：审计**

| 配置项 | 默认值 | 含义 |
|---|---|---|
| 提交前自动审计 | 关 | 开启后 `git_commit_push` 提交前自动跑静态检查 + 10 维度评分，有 blocker 拦截提交 |
| 审计扫描范围 | diff | 单击切换：diff（只审本次变动）/ full（全量） |
| ↳ 注入开发者要求清单到系统提示词 | 关 | 勾选即生效（不必等门禁拦截再回读清单）；审计关闭时置灰、勾选保留 |
| 注入系统提示词/上下文 | 开 | 注入总开关，同时门控系统提示词三段与上下文环境段 |
| 代码禁用户沟通词 | 开 | comment 规则包启停；注释/文档出现沟通残留措辞 → blocker 拦截提交 |
| 全量扫描文件上限 | 3000 | 0=不限；超限按「变动文件优先」截断，弱机防卡死 |
| 审计权重（10 维度） | 合计 100 | 改即写回权重覆盖 JSON，保存后下次审计生效 |
| 规则包列表 | — | ↑↓ 调次序（后加载覆盖先加载）；单击整行启用/禁用（启用=绿底、禁用=红底）；三列数字是该包内拦截级/警告级/提示级的规则条数；nodejs/private 安全红线不可禁用 |

**选项卡三：设置**

| 配置项 | 说明 |
|---|---|
| GitHub token | `ghp_` / `github_pat_` 开头；保存写 `config.json`（0600），不回传明文、页面不留存 |
| SSH 公钥 | `ssh-ed25519` / `ssh-rsa` 整行，与 token 同份配置、互不覆盖 |
| SSH 邮箱 + 一键生成并复制 | 按邮箱生成密钥对（私钥不出本机，公钥整行回填并复制） |
| 推送通道 | ssh（默认，只走 SSH 私钥）/ token（先走 Git Data API，失败回落 SSH）/ auto（先 ssh 再回落 token）；远端分叉时不静默回落 |
| 推送门禁 | 默认关；开启后 push 必须显式带 `pushConfirmed: true`，否则拦截（commit 不受影响） |
| 自动推送(✅任务完成) | 默认关；开启后 AI 回复含触发文本即自动 commit+push（复用审计门禁，不裸提交） |
| 自动推送触发文本 | 默认 `✅任务完成`，可写正则如 `✅(任务完成|已解答)` |
| 自动推送范围 | session（默认，仅会话 cwd 所在仓库）/ all（workspace 全部有变更仓库） |

### 2.5 账号信息卡 / 本地仓库列表：读取时机

只在三种时机读取；读取一律纯离线读 json（秒级），联网只在需要时单独触发：

| 时机 | 账号信息 | 本地仓库列表 |
|---|---|---|
| 插件启动（侧边栏加载） | 离线读 `account-status.json` | 离线读 `dsh-repo-index.jsonl` |
| 云端 push 完成后 | 离线读（push 时已在线更新 json） | 离线读（push 时已重建索引） |
| 手动刷新 | `重新检测` = 在线校验写 json，再离线读回 | `扫描` = 独立进程后台离线扫描，逐条追加 |

登录判定为「或」：SSH 或 token 任一有效即视为已登录，用户名取有效者。


### 2.7 配置持久化位置

设置项以插件配置 schema 为单一事实源；持久化真源是**插件私有目录**（`$DSH_HOME/git-push/`，无 `DSH_HOME` 时回退 `~/.dsh/git-push/`），**不写公共 settings.yaml**：

| 文件 | 内容 |
|---|---|
| `config.json` | 全部设置与凭据真源（0600）：开关、扫描范围、文件上限、权重覆盖、规则包顺序、推送通道/门禁、自动推送、`githubToken`、`sshPub`，以及可选的 `injectUsageText` |
| `account-status.json` | 账号快照：登录名、是否登录、token/SSH 各自有效性与校验时间 |
| `dsh-repo-index.jsonl` | 仓库索引：本地/云端仓库的归属、可见性、路径、默认分支、领先/落后等（自动生成，请勿手改） |
| `scan-live.json` | 本地扫描进度：`version` / 已发现仓库 / 是否完成 |
| `tools.json` | 工具探测结果（工具名 → 本机实测路径） |
| `settings-ui.log` | 侧边栏每次保存设置的追加日志（凭据值打码） |
| `requirements.json` | 开发者要求清单外挂覆盖（存在则优先于插件内置清单） |
| `id_rsa` 等 | SSH 私钥文件（token/公钥在 config.json，私钥仍是文件） |

## 三、边界与坑

- 关掉注入总开关后段仍注册、只是内容为空——不要用「段存在」判断注入是否生效。
- 环境段走上下文注入、不在系统提示词里；只注入目录/路径级信息，不注入 skill 正文、不列 skill 文件清单（正文交给 AI 按需读）。
- 「注入全部 skill 正文」「注入仓库索引全文」两个开关已移除，不提供全量正文注入档位。
- 环境注入是**每个 agent 首次 step 一次**，不是每步；缓存按会话工作目录分别缓存。
- 设置不写公共 settings.yaml：经反代访问时前端设置持久化会退化成内存（刷新即丢），且多实例共享配置目录会抢同一把写锁——插件配置自管到私有 `config.json`。
- 账号信息与仓库列表不轮询、不监听索引文件；页面内切 tab 不会反复刷新。
- 本地列表默认只显示登录同作者的仓库；无登录态时不过滤。
- 预览页默认接真实后端；`?mock=1` 是假数据，只用于离线看样式，不能用来验证真实数据流。
- 预览端口默认 30999，被别的项目占用时用 `--port` 错开；改了前端代码必须重新生成预览页，否则看的是旧界面。

## 四、配套 skill

- `skills/guide/guide-commit-push.md` —— 提交推送门禁、工具参数与返回字段
- `skills/guide/guide-audit.md` —— 审计规则、10 维度评分与豁免机制
- `skills/guide/guide-clone-repos.md` —— 克隆与仓库索引联动
- `skills/guide/guide-slash-completion.md` —— 用户输入框斜杠命令
- `skills/guide/guide-cli-scripts.md` —— 命令行与随插件脚本
- `skills/dsh-git-push.md` —— 插件总览与快速上手
