dsh-agy-provider

dsh plugin --profile web add dsh-agy-provider

dsh-agy-provider

[简体中文](README.md) · [English](README.en.md)

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

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

项目状态

0.10.0 已完成开发，正在发布到 npm。 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 完成真实像素回答、同会话追问、失败格式和清理验证；它仍不是无条件的生产级图片能力。

工作方式

~~~text

用户 / 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 和稳定错误事件。

0.6.0 已实现

1. 文本 Provider 与进程边界

• 将 DSH system prompt/messages 确定性序列化为 AGY Prompt。
• 将 step_update.text_delta 和 result.response 映射为 DSH 文本流。
• 支持超时、取消、退出码、解析错误、输出上限和进程树清理。
• 日志只保留 request/session/usage/事件计数等白名单字段；失败时可追加启动阶段、稳定错误码、输出行号/长度和短哈希，不记录 Prompt、响应正文、stderr 原文、凭据或完整本机路径。

2. Session、模型和 reasoning effort

• 默认 sessionMode: full：每轮发送完整 DSH 历史，行为最容易审计。
• 可选 sessionMode: resume：使用 AGY conversation_id 发送增量消息；恢复失败会降级为完整历史。
• 同一 DSH Session 串行，不同 Session 可以并发。
• 默认通过 agy models 做 quota-free 动态发现，支持 TTL、single-flight、缓存和静态 fallback。
• 请求级 reasoningEffort 支持 low、medium、high，以独立 --effort 参数传给 AGY；未指定时不设置隐式值。

3. 工具所有权与权限边界

项目明确只允许一个工具执行者：

• 程序化 Provider 默认 toolPolicy: reject，收到 DSH tool schema 时返回 UNSUPPORTED_TOOLS。
• 已发布的 0.6.1 DSH bundle 默认使用 toolPolicy: agy-owned；0.7.0 开发分支已切换为 toolPolicy: dsh-owned，DSH schema 经过 bounded contract 交给 AGY 生成调用，实际执行仍由 DSH ToolRuntime 完成。
• 发生权限请求时返回 PERMISSION_REQUIRED 并终止请求，不自动批准，不使用 --dangerously-skip-permissions。

4. Agent capability presets 与读写能力

随包提供三档 Agent 模板：

preset · 已允许能力 · 默认行为

tool-free · 纯文本推理 · 不访问工作区

read-only · find_by_name、grep_search、view_file、list_dir · 只读工作区

workspace-write · 上述只读工具 + multi_replace_file_content、replace_file_content、write_to_file · 仅显式工作区内写入

workspace-write 已经实现，但必须同时配置一个存在且非文件系统根目录的 workspaceRoot。它不包含 shell、网络、浏览器、MCP、subagent 或权限跳过。

项目不会把未验证的 glob 工具名写进公开契约。需要文件搜索时使用 AGY 已验证的 find_by_name、grep_search 和 list_dir。

模板安装默认只预览，不写入文件：

~~~powershell

npx dsh-agy-provider agents list

npx dsh-agy-provider agents install read-only --dir "$HOME/.gemini/config/agents"

npx dsh-agy-provider agents install read-only --dir "$HOME/.gemini/config/agents" --apply

~~~

已有模板默认拒绝覆盖；需要保留旧文件时显式增加 --backup。

5. Doctor v3 与安全诊断（0.7.0）

发布包提供 profile-aware doctor：

~~~powershell

npx dsh-agy-provider doctor --profile web --json

~~~

0.7.0 源码中的 doctor 输出 profileSchemaVersion: 3，审计 provider、model、Agent、retry、purpose route、workspace、image、DSH context probe 状态和 DSH-owned bridge capability。它会区分 dump timeout、非零退出和解析失败，并对 agy-owned 输出 deprecated warning；profile doctor 只读，不把静态 dump 伪装成 live Session。

运行时 API diagnoseDshContext() 会只返回 session/workspace/sandbox/permission/approval 的可用性、allowlisted 权限模式和稳定 issue code，例如 DSH_SESSION_UNKNOWN、DSH_WORKSPACE_MISMATCH，不会返回路径、Session ID、Prompt 或工具参数。telemetry 只保留 permissionPreset、sandboxMode、approvalPolicy、toolSchemaCount、toolCallCount 和 bridge outcome。

doctor 只执行 agy --version、agy agents、agy models 和 DSH config dump，不发送模型 Prompt，不执行工具，quotaUsed 固定为 false。

6. 图片输入实验边界

imageInput: experimental 已支持：

• 通过可选 DSH AttachmentStore 读取图片。
• 对 PNG/JPEG/WebP/GIF 做 MIME、字节数和数量限制。
• 每个请求使用随机临时 staging 目录，并在成功、失败和取消时清理。
• 图片请求强制使用独立 dsh-agy-image-view Agent，并且只允许 view_file 读取本次请求精确暂存的图片路径。
• 图片请求使用 one-shot；AGY 的内部 view_file 生命周期只在上述窄白名单内放行，DSH 工具仍由 DSH ToolRuntime 所有。

开启 imageInput: experimental 后 listModels() 返回文本+图片输入能力；关闭时仍为纯文本。未知 custom Agent 不会获得图片读取权限。

7. 质量门禁

• npm run verify：typecheck、158 个测试和 pack dry-run。
• npm run benchmark：Parser、serializer、limiter 的无额度基线。
• npm run smoke:dsh:self-contained：隔离 DSH Web/headless plugin-add、doctor 和 Mock response。
• GitHub Actions：Provider Node.js 20/22/24 × Windows/Ubuntu/macOS，DSH 原生 Node 22/24 × Windows/Ubuntu/macOS，并包含 self-contained smoke。
• 公共 CI、doctor、benchmark 和 Mock smoke 均不调用真实 AGY 模型。

当前能力矩阵

能力 · 当前状态 · 默认值

DSH 文本对话 · 已实现 · 开启（profile bundle）

AGY 额度/认证 · 已实现 · 由本机 AGY 管理

动态模型发现 · 已实现 · modelDiscovery: auto

reasoning effort · 已实现 · low/medium/high 不设隐式值，DSH 独

…(truncated)