前言¶
DeepSeek Harness（DSH）采用模块化插件架构。在集成 pi-ai 模型时，认证流程通常需要 OAuth 支持。现有的基础集成仅注册协议和凭据记录，缺乏直观的交互界面和命令行管理手段。dsh-bundle-pi-ai-auth 插件为 pi-ai 提供者添加了 Model 设置页面的 Provider-card UI 控件，并保留 /auth-* 命令作为 fallback，用于管理 OAuth 能力、启用状态和登录状态。
核心功能¶
此插件在 DSH 的 Web 或 Desktop 端提供以下能力：
- Provider-card OAuth 控制：在 Models 设置页面，为每个支持 OAuth 的 pi-ai 提供者显示授权状态和操作按钮。
- Models settings UI 集成：提供 “Sign in” 和 “Sign out” 按钮。点击 Sign in 会启动提供者流程，打开系统浏览器并显示设备代码或后续问题。
- 命令行回退：提供一组
/auth-*命令，用于手动管理提供者。 - 状态管理：分离管理 OAuth 能力、启用状态和登录状态，不自动创建临时 token 环境变量。
- 凭据清理：登出操作仅删除本地凭据记录，不撤销远程授权。
安装与启用¶
安装前需确保环境满足依赖要求。此插件依赖 @deepseek-ai/dsh-llm-pi-ai，需要 DeepSeek Harness 0.1.7-rc.2 或兼容的 0.1.x 版本。此外，Web/Desktop 组合需包含 authorization、credentials、settings、llm-pi-ai、Remote gateway 和 Models settings UI 组件。
在 Web 端安装插件：
dsh plugin --profile web add github:dingyiliao/dsh-bundle-pi-ai-auth
安装后重启应用，在 Settings → Models 中添加提供者，然后使用提供者卡片上的 Sign in 操作。
典型用法¶
命令行操作¶
插件提供以下命令用于状态检查和操作：
- 列出状态：
/auth-list- 查看所有支持 OAuth 的提供者及其启用和登录状态。 - 添加并登录：
/auth-add [provider]- 添加提供者并立即登录。省略 provider 参数会触发选择提示。 - 登录已启用提供者：
/auth-login [provider]- 仅对已启用的提供者执行登录。 - 检查状态：
/auth-status [provider]- 检查特定提供者的详细状态。不指定 provider 时等同于/auth-list。 - 登出：
/auth-logout [provider]- 移除本地凭据但保留提供者启用状态。 - 移除提供者：
/auth-remove [provider]- 移除用户添加的提供者及其本地凭据。
UI 操作¶
在 Models 设置页面，找到支持 OAuth 的提供者卡片：
1. 点击 Sign in。系统会启动授权流程，弹出模态框显示设备代码或后续问题。
2. 在系统浏览器中完成登录后，凭证将保存至本地。
3. 点击 Sign out 可删除本地凭证。
适用场景与注意¶
- 依赖关系：此插件不实现 OAuth 协议，也不存储和刷新 token。它仅作为交互层，依赖
@deepseek-ai/dsh-llm-pi-ai处理底层逻辑。 - 手动启用：安装插件不会自动启用任何提供者。用户必须先在 Models 设置中添加提供者，然后才能进行登录。
- UI 限制：对于纯 OAuth 提供者，核心 Models UI 可能仍显示通用的 API Key 编辑器，因为此插件不通过 CSS 遮蔽核心 UI。
- 登出行为：登出仅移除本地记录，不会撤销远程的授权 grant。
- 依赖组件：必须安装包含
authorization、credentials、settings、llm-pi-ai、Remote gateway 和 Models settings UI 的完整 DSH 环境方可正常工作。 - 提供者冲突：如果提供者是由其他 bundle 的基础配置启用的，不能通过
/auth-remove移除，需更新该 bundle。
总结¶
dsh-bundle-pi-ai-auth 补全了 pi-ai 集成在 DSH 中的交互短板。它通过 UI 卡片和命令行工具，让开发者能够更方便地管理 OAuth 提供者的启用、登录和登出状态，而无需直接操作底层协议。
