前言¶
DeepSeek Harness（DSH）里，主会话可以把具体编码任务交给子智能体：子进程在父工作区里改文件、跑命令，父会话只拿回最终结论，不把子进程的工具调用和 stderr 灌进对话。官方已有 Codex 子智能体（subagent_codex），社区也有 Cursor 等类似形态。若你希望主模型调用 Google 官方 Gemini CLI 完成同类「一次性委托」，就需要把 Gemini 接到 DSH 的子智能体接缝（ctx.subagents）上。
dsh-subagent-gemini 由社区维护者 PipeDream941 开发，分类为工作流插件。它在 DSH 中注册全局工具 subagent_gemini，通过官方 ACP 子智能体后端拉起 gemini --acp，形态与 subagent_codex、cursor_code 一致。README 写明：暂未发布到 npm / DSH 插件市场；Gemini CLI 目前尚未提供 Gemini 4，若要用 Gemini 4 应安装 dsh-subagent-antigravity。插件与 Google 无隶属关系，仅驱动其官方 CLI。
这是什么¶
一句话：在 DSH 父会话中增加 subagent_gemini 委托工具，每次调用在新进程中启动 Gemini CLI（ACP 模式），子智能体自行使用 CLI 内置能力（文件编辑、Shell、搜索、MCP 等），结束后只向父会话返回最终答复或安全失败诊断。
维护者与仓库：PipeDream941 / dsh-subagent-gemini。社区目录页：skillhub.cn 插件条目（与 DeepSeek / 幻方无官方从属；生态理念是「一切皆插件」）。
工作方式¶
主会话调用 subagent_gemini({ description, prompt }) 后，链路大致如下：
父会话（DeepSeek 模型）
│ subagent_gemini
▼
DSH 子智能体接缝（本插件注册 provider: gemini）
▼
@deepseek-ai/dsh-subagent-acp（官方 ACP 后端：拉起进程、握手、权限自动应答、清理）
▼
gemini --acp --skip-trust（独立进程，父进程 cwd）
▼
最终答复 → 父会话
设计要点（与 README 一致）：
- 新进程、新会话：每次委托拉起新的
gemini --acp； - 只回最终答案：子智能体思考、工具调用、stderr 不进入父对话；
- 一次一任务：不支持在同一次运行里追问或续聊（续聊用原生
subagent/fork后端）； - 安全诊断：失败时返回固定阶段/类别信息，不泄露 stderr、路径或凭据。
本插件负责 Gemini 相关部分：定位可执行文件、校验配置、加载时检测凭据并给出可操作提示；进程生命周期与 ACP 协议由 DSH 官方后端处理。
环境与依赖¶
| 依赖 | 要求 |
|---|---|
| DeepSeek Harness | 0.2.1-rc.2 系列（提供 ctx.subagents 与 ACP 子智能体后端） |
| Node.js | ^22.19.0 或 >=24 |
| Google Gemini CLI | 支持 --acp 的构建（0.60+，建议最新） |
| Gemini 凭据 | 推荐 Gemini Developer API key，或 Vertex AI / Code Assist 相关环境变量 |
安装 CLI 并确认版本：
npm install -g @google/gemini-cli
gemini --version
安装与启用¶
发布前 README 仍给出市场与命令行两种方式；市场收录待维护者完成端到端验证后开放（需用户自备 API key 验证）。
从 DSH 插件市场（推荐，发布后）： 搜索 dsh-subagent-gemini，安装并启用。
从命令行：
dsh plugin --profile desktop add dsh-subagent-gemini
在该 profile 的 package.json 里把包加入 dsh.profile.bundles，重启或等待 profile 重新组合：
"dsh": {
"profile": {
"bundles": ["…", "dsh-subagent-gemini"]
}
}
启用后，智能体在下一次请求时可见全局工具 subagent_gemini。安装插件前请自行查看仓库源码与 MIT 许可证；子进程以当前 DSH 进程权限在工作区执行，与 permission 配置相关（见下文）。
凭据配置¶
Gemini CLI 需要独立凭据。个人 Gemini Code Assist 的浏览器 OAuth 已不再可用；应使用 API key。
- 在 Google AI Studio 创建 key；
- 写入 Gemini CLI 默认读取位置（插件不要求单独配置 key）：
printf 'GEMINI_API_KEY=your-key\n' > ~/.gemini/.env
chmod 600 ~/.gemini/.env
也可用环境变量：GEMINI_API_KEY（Developer API）；或 GOOGLE_GENAI_USE_VERTEXAI=true 配合 GOOGLE_API_KEY；或 GOOGLE_GENAI_USE_GCA=true（Code Assist 许可）。若需向子进程显式传入变量，使用插件 env 配置。插件不读取、记录或返回密钥内容。
典型用法¶
主模型像调用其他委托工具一样传入 自包含 的 prompt（子智能体看不到父会话历史）：
{
"name": "subagent_gemini",
"arguments": {
"description": "Fix login timeout",
"prompt": "In the workspace, find the login request timeout and raise it from 5s to 15s, run the related tests, and reply only with what you changed and the test result."
}
}
description：子智能体列表中显示的短任务名（约 3–5 个词）；prompt：须包含路径、约束与验收标准。
运行结束后父会话收到完成通知与 Gemini 的最终答复，或安全失败诊断。
配置项¶
在 profile patch 中覆盖 subagent-gemini 的 config：
| 字段 | 默认 | 含义 |
|---|---|---|
providerName |
gemini |
在 ctx.subagents 上注册的名称，同一 profile 内须唯一 |
command |
空（自动探测） | gemini 可执行文件路径；空则从 PATH 及常见路径查找 |
args |
['--acp', '--skip-trust'] |
CLI 参数；--acp 始终保留 |
model |
空（CLI 默认） | 如 gemini-2.5-flash，会作为 --model 传入 |
permission |
allow |
子进程权限询问：allow 自动批准编辑/Shell；reject 只读 |
env |
{} |
在脱敏后的父环境上叠加的环境变量 |
disposeEofGraceMs |
6000 |
stdin EOF 后等待子进程刷盘的毫秒数 |
disposeGraceMs |
3000 |
失败观察与 SIGTERM→SIGKILL 的宽限 |
示例：固定模型且子智能体只读：
- id: subagent-gemini
config:
model: gemini-2.5-flash
permission: reject
适用场景与注意¶
适合： 已在 DSH 0.2.1-rc.2 上使用子智能体委托、本机已装 Gemini CLI，且希望主会话用 Gemini 模型 + CLI 工具链 完成单次编码任务（修 bug、改配置、跑测试并汇总结果）的团队或个人。
注意：
permission: allow时子智能体可在工作区无人值守改文件、跑命令；仅在可信工作区使用，事后用git diff审查。--skip-trust避免交互式信任提示阻塞委托。- 需要 Gemini 4 时不要用本插件指望 CLI 提供，应改用 dsh-subagent-antigravity。
- 常见故障：找不到
gemini（安装 CLI 或设置command）；缺 API key（配置~/.gemini/.env）；仍用已废弃 OAuth；网络或代理问题（可在env中设HTTPS_PROXY）。
结尾¶
dsh-subagent-gemini 把 Google Gemini CLI 以 ACP 子智能体形式接入 DSH，与 Codex/Cursor 子智能体同一套「新进程、只回结论、一次一任务」模型；发布前需自行安装 bundle 并配置 API key。目录与文档：SkillHub 插件页、GitHub 仓库。
