darkings/dsh-agy-provider

dsh-agy-provider

简体中文 · English

把本机已经登录的 AGY CLI 暴露为 DSH 的模型 Provider。

它的核心用途是：让 DSH 继续使用 AGY 账号中的模型和额度，同时保留 DSH 的对话、Session、Web/headless 运行方式。Provider 不直接调用 Google Gemini API，也不保存 OAuth 凭据；认证和模型选择由本机 agy 负责，工具执行由 DSH ToolRuntime 负责。

项目状态

0.10.0 已发布到 npm，latest=0.10.0。 0.10.0 在 0.9.0 的设置面板、工作区无感化和模型/推理强度分离基础上，加入 optimized full 上下文预算、确定性工具结果淘汰、脱敏诊断和 Windows 无控制台 launcher；默认仍为 sessionMode: full。

0.7.0 / 0.8.0 已合并：v0.7.0 → b94fa32（latest=0.7.0 已发布）、v0.8.0 → b7c9a45 已合入主线。0.7.0 起 dsh-owned 为 bundle 默认（DSH Session/ToolRuntime/sandbox/approval 接管项目与权限）。

0.10.0 的公开能力重点是：

• 上下文与工具安全：DSH-owned structured prompt 固定 56 KiB fail-closed 上限，超限返回 AGY_INPUT_TOO_LARGE；压缩后可恢复，工具结果按整段淘汰，避免历史前缀漂移。

• 性能与观测：稳定前缀、canonical tool schema、step usage 口径和 fingerprint 诊断提升缓存资格与可观测性；不把后端 cacheRead 命中率当作保证。

• DSH 设置面板：Config 全量 zh-CN/en i18n（schemastery .i18n），registerConfigurableProviders(settingsNs dsh-agy-provider) + registerModelDiscovery，模型为多选勾选列表，推理强度为独立下拉。

• 工作区无感：dsh-owned 下废弃 workspaceRoot（.deprecated()，面板隐藏，resolveAgyAgentRuntime 强制 undefined），工具请求走 DSH Session header.cwd + workspaceRegistry + sandboxPolicy 自动校验；纯文本无需 workspace，工具无 workspace 时返回 DSH_WORKSPACE_MISMATCH 可操作错误。

• 模型与推理强度分离：gemini-3.7-flash 为 base，reasoningEffort: low|medium|high 独立选择；listModels 仅返回 base 并带 reasoning.efforts，旧 -high/-medium/-low 后缀自动兼容并 DEPRECATED_MODEL_EFFORT_SUFFIX 警告。

• 模型可见性：visibleModels: string[] 空=全部，非空仅显示勾选的 base，未勾选显式请求仍兼容。

• 保持 0.7.0 的 DSH-owned 工具桥、Agent presets、doctor v5（profileSchemaVersion: 4）、零重试、quota-free 诊断与跨平台门禁；imageInput: experimental 已打通受限多模态闭环。

图片输入为受限 experimental bridge：开启后公开 inputModalities: ['text', 'image']，通过独立 dsh-agy-image-view Agent 读取临时暂存图片。已在 DSH Desktop 完成真实像素回答、同会话追问、失败格式和清理验证；它仍不是无条件的生产级图片能力。

工作方式

用户 / DSH Web / DSH headless
              │
              ▼
      dsh-agy-provider
      ├─ DSH LlmAdapter
      ├─ Prompt / Stream 映射
      ├─ Session / Conversation 映射
      ├─ Model discovery / retry / telemetry
      └─ Agent 与 workspace 安全边界
              │
              ▼
      agy --output-format stream-json
              │
              ▼
      AGY 账号额度、模型和 Agent 工具

Provider 使用 spawn(executable, args) 启动 AGY，不经过 shell 拼接命令。AGY 输出按行增量解析，再转换为 DSH 的文本、usage、finish 和稳定错误事件。

当前能力矩阵

安装与使用

前置条件

• Node.js >=20。
• 已安装并登录本机 AGY CLI，且 agy 可以在 PATH 中找到。
• 使用 DSH profile 安装插件时，确保 pnpm 在 PATH 中，因为 DSH plugin manager 会转发到 pnpm。

安装到 DSH profile

普通 npm install 只安装 Node.js 包，不会把 Provider 写入 DSH profile。DSH Web/headless 应使用原生 plugin manager：

npx @deepseek-ai/dsh plugin --profile web add dsh-agy-provider@0.10.0
npx @deepseek-ai/dsh plugin --profile headless add dsh-agy-provider@0.10.0

0.9.0 bundle 默认（cordis.patch.yml）相当于：

enabled: true
provider: agy
model: gemini-3.1-pro
agent: deepseek-proxy
toolPolicy: dsh-owned
sessionMode: full
imageInput: off

直接使用库的 Config({}) 仍保持 enabled: false、toolPolicy: reject，不会因 import 而修改 profile；BundleConfig 为显式 enabled: true / dsh-owned。

Agent preset 配置

只读配置（dsh-owned 无需 workspaceRoot）：

agentPreset: read-only
toolPolicy: dsh-owned
# 无需 workspaceRoot，打开文件夹的 DSH Session 即项目

工作区写入（dsh-owned 仍无需手配目录，权限由 DSH 切换）：

agentPreset: workspace-write
toolPolicy: dsh-owned
# dsh-owned 下 workspaceRoot 已废弃，DSH 的 workspace-write / danger-full-access 决定可写边界

legacy agy-owned 如需显式目录（不推荐）：

agentPreset: workspace-write
toolPolicy: agy-owned
workspaceRoot: C:\work\my-project

写入能力由 DSH 权限 preset 与 sandbox 强制执行，Provider 不绕过。

配置示例（0.9.0 推荐）

enabled: true
provider: agy
agent: deepseek-proxy
model: gemini-3.7-flash            # base 名称，推理强度在 DSH 会话中选 low/medium/high
visibleModels:                      # 设置面板勾选要显示的模型，空=全部
  - gemini-3.7-flash
  - gemini-3.1-pro
models:
  - id: gemini-3.7-flash
    name: Gemini 3.7 Flash
  - id: gemini-3.1-pro
    name: Gemini 3.1 Pro
toolPolicy: dsh-owned
transport: one-shot                 # 或 persistent（opt-in，一 Session 一 worker）
sessionMode: full
modelDiscovery: auto
retryPolicy:
  maxRetries: 5
  retryableCodes: [EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, TRANSPORT]
imageInput: off

兼容：旧 model: gemini-3.7-flash-high 仍可解析为 base + high 并 warning，建议改为 base + 会话级 reasoningEffort。

重试默认遵循 DSH normal 策略：首次请求失败后最多重试 5 次；TIMEOUT 会进入重试，最终总计最多 6 次 AGY 请求。可通过 retryPolicy 在 settings.yaml 中收窄次数和错误码白名单。

诊断与开发

不消耗模型额度的诊断：

npm run diagnose -- --json
npx dsh-agy-provider doctor --profile web --json
npx dsh-agy-provider agents list

本地开发：

npm ci
npm run verify
npm run benchmark
npm run smoke:dsh:self-contained

需要真实 AGY 的实验不会自动运行。0.9.0 多模态闭环已在用户授权额度下完成；后续仍不应在无明确授权时重复消耗真实模型额度。

未来规划

未来版本会继续以“可验证、可回退、额度可控”为前提，重点包括：

0.7.0：由 DSH 控制项目、权限与工具（已实现）

• DSH-owned tool bridge 已完成：AGY 只产生经过本地严格校验的 DSH tool call，文件、shell、网络和 MCP 统一由 DSH ToolRuntime 执行。
• V7-M4 权限矩阵、V7-M5 doctor v3/allowlisted telemetry/安全回归、V7-M6 packed artifact/Web/headless/跨平台发布门禁均已完成。
• 直接采用 DSH Session 的项目 cwd，以及 read-only、workspace-write、danger-full-access 权限选择，不在插件内复制第二套开关。
• 保持 sandbox、approval、MCP 凭据和实际副作用位于 DSH；Provider 不传 --dangerously-skip-permissions。
• 详细范围、安全门禁、额度预算和里程碑见 0.7.0 开发计划。

0.8.0：Persistent transport 与 DSH next 兼容（已实现）

• 以 AGY 1.1.15 正式 stream-json 输入协议为基础，一 Session 一 worker 的 persistent transport 已做成稳定 opt-in；默认仍 one-shot（transport: persistent 显式启用）。
• 同时验证 DSH rc.7 stable 与 rc.8 next 隔离 lane，不以升级 next 为代价破坏现有用户；warm-turn 实测 79% 改善，145/145 通过。
• 图片 modality 作为 0.9.0 受限 experimental 能力交付，Desktop 像素回答、追问、失败格式与清理均已验证。
• 详细范围、go/no-go、额度预算和发布门禁见 0.8.0 开发计划。

0.9.0：设置面板 + 工作区无感 + 模型平权（已实现）

• DSH 设置面板：Config i18n（zh-CN/en）+ registerConfigurableProviders + registerModelDiscovery，visibleModels 多选与 base + reasoningEffort 分离。
• 工作区无感：dsh-owned 废弃 workspaceRoot，项目目录由 DSH Session 自动接管，纯文本无需 workspace。
• 完整 7 层测试（L1 单元 160+ / L2 集成 / L3 自包含 / L4 权限矩阵 / L5 设置面板 / L6 跨平台 / L7 真实抽样）与 doctor v5（profileSchemaVersion 4）。
• 详细范围与发布门禁见 0.9.0 开发计划 与 0.9.0 迁移说明。

后续版本：图片与工具体验加固

• 继续加固 DSH Web AttachmentStore → AGY 像素答案路径的性能、更多格式与跨平台证据。
• 继续完善 workspace-write 的冲突处理、备份、回滚和 tool-call 展示体验。
• 不会因为工具目录中存在 write 就绕过 DSH 权限；实际写入始终服从会话 permission preset 和项目边界。

后续版本：传输与成本优化

• 0.8.0 的持久 transport 已在真实 AGY 协议、串线、崩溃恢复、进程清理和 token 成本闸门上证明收益（V8-M4 go），0.9.0 保持 opt-in。
• 继续完善 purpose-aware 的 compaction/session-title 路由、usage 可观测性与 transport: persistent 的默认策略评估。
• 保持公共 CI、doctor、解析器和 Mock smoke 的零额度原则。

明确不支持的能力

• 直接调用 Gemini API 或在插件内管理 OAuth/refresh token。
• DSH 与 AGY 的双重工具执行 loop。
• 未验证的 glob、shell、网络、MCP、subagent 或自动权限批准。
• 默认写入用户工作区。
• 无限制生产级 image modality、temperature、stop、maxTokens 和未经验证的 reasoning-delta 输出。
• 未经成本和可靠性验证的生产级 persistent stream transport。

项目结构

dsh-agy-provider/
├─ src/
│  ├─ provider/       # DSH Adapter、配置、序列化、图片 bridge
│  ├─ agy/            # 子进程、argv、stream-json、模型发现、脱敏（含 persistent-transport）
│  ├─ session/        # DSH Session 与 AGY Conversation 映射
│  ├─ doctor.ts       # profile-aware doctor v5 (profileSchemaVersion 4)
│  ├─ dsh/context.ts  # DSH Session/workspace/sandbox/approval 无感校验
│  └─ agent-*.ts      # preset、安装器和 agents CLI
├─ agents/            # tool-free/read-only/workspace-write 模板
├─ scripts/           # verify、benchmark、diagnose、DSH smoke
├─ tests/             # L1 单元 + L2 集成（visibleModels/归一化/i18n）
├─ docs/
├─ cordis.patch.yml
└─ package.json

文档

• 安装文档（0.9.0 工作区无感与 visibleModels）
• 0.9.0 迁移说明（模型 base+effort / 可见性 / 废弃 workspaceRoot）
• 0.9.0 开发计划（设置面板/工作区/模型平权/7层测试）
• 0.9.0 发布检查清单（L1~L7 门禁）
• 工具能力矩阵
• 兼容性矩阵
• DSH Provider 契约
• 0.8.0 / 0.7.0 开发计划与迁移说明（历史）
• CHANGELOG
• 性能基线

License

MIT