dsh-agentone

Readme

# dsh-agentone

AgentOne 平台集成插件（dsh web 版 / 桌面版通用）。安装后让独立 dsh 接入公司
AgentOne 平台：飞书登录、平台模型、SkillHub 技能、套餐申请、dsh 插件管理、
lark-cli / ccpg-cli 状态探测。

## 能力总览（M1–M4 已全部交付）

- **飞书登录（M1）**：设备登录流（一次性授权码），凭据保存在本机
  `$DSH_HOME/agentone/credentials.json`（0600）。access 令牌临期自动轮换
  （single-flight），refresh 失效自动回到未登录态。
- **平台模型（M2）**：登录后自动把 dsh 的 llm provider 指向 AgentOne
  OpenAI 兼容代理（`/api/plugin/v1`），模型密钥不下发到本机；对话经平台
  走 TokenHub 按用户计量。平台 403 的 `plan_required` 错误码原样透传，
  前端据此引导申请套餐（不依赖中文文案匹配）。
- **SkillHub 技能（M3）**：套餐技能自动装齐（启动/登录时，且常驻期间
  套餐生效、套餐新配技能时由前端触发器与手动「同步套餐技能」按钮补装）；
  技能市场搜索、手动安装/卸载，装/卸载后技能列表即时刷新（失效 45s
  status 缓存）；已装技能平台侧对比 latest 版本/指纹，有更新时展示
  「v旧 → v新」并支持一键升级（覆盖式重装，原子替换旧目录）；技能包
  zip 走平台代理下载（穿越清洗 + 原子落盘）。
- **SkillHub 连接配置（M3+）**：登录后自动从平台拉取 registry 与用户级
  个人 token，写入 `$DSH_HOME/agentone/skillhub.env`（0600，含
  `SKILLHUB_BASE_URL`/`SKILLHUB_TOKEN`/`CLAWHUB_REGISTRY`/`CLAWHUB_TOKEN`
  四个与平台托管容器同名的变量），本机有 clawhub CLI 时同步写入登录态；
  登出时全部清理。会话内使用：`source $DSH_HOME/agentone/skillhub.env`。
- **套餐申请（M3+）**：状态页「套餐」tab 展示当前套餐/审批中/可申请列表，
  一键提交申请；审批通过后前端轮询检测到 active 自动同步模型。
- **dsh 插件管理（M3+）**：列出镜像内置与用户自装插件（版本/升级/激活态），
  内置插件缺失时启动自动重装（自身也在常驻保证清单内，防误删导致平台集成
  失效）；desktop 受管 pnpm 通道操作串行排队，宿主并发锁占用时自动退避
  重试（不把「another desktop pnpm operation is already running」抛给用户）；
  自身随平台镜像升级（列表中不提供按钮）。
- **CLI 探测、安装与授权（M4）**：`lark-cli` / `ccpg-cli` 安装与授权态三态探测；
  未安装时「安装」一键自助安装（lark 走 `npm install -g @larksuite/cli@latest`，
  ccpg 走公司 `auto-install.sh`，口径与平台 cli-deployd 一致）；
  已装未授权时「去授权」发起官方 Device Flow（授权链接 + ASCII 二维码 +
  验证码 + 自动轮询确认，设备码仅存插件进程内存）；
  lark-cli 首装未 `config init` 时探测为「未配置」，「初始化应用」一键驱动
  官方 `config init --new`（长驻子进程 + 验证链接/二维码 + 终态轮询，成功后
  自动衔接设备流授权；关闭弹窗即终止子进程）。平台托管实例不提供自助初始化
  ——容器内 HERMES_HOME 上下文下 config init 会拒绝执行，应用配置由 Hub 经
  cli-deployd 统一下发。
- **全局中文回复默认**：插件启动时在 `$DSH_HOME/AGENTS.md` 注入受标记
  管理的「默认始终使用中文回复」指令块（dsh 官方 agent-instructions 机制，
  每个会话基线加载，project 级指令优先）；幂等不重复注入，用户已有语言
  偏好或删除标记块后不再介入（本机只做一次决策，记录于
  `$DSH_HOME/agentone/language-default.json`）。
- **首启引导**：dsh 首次启动弹出飞书登录引导（order -50，早于官方
  「添加 API Key」），登录一次即跳过官方密钥引导；暗色主题适配。

所有平台请求统一走 `lib/http.js`（默认 10s 超时、技能包下载 60s），
平台挂起时快速失败并给出中文提示，不会吊死状态页轮询。

## 安装

```bash
dsh plugin --profile web add dsh-agentone
```

平台托管镜像集成：`docker/dsh/Dockerfile.default` 默认插件块（见
`plugins/README.md` 全流程）。

## 使用

打开 dsh web 的 `/agentone/` 页面（或 dsh 设置 → AgentOne）→「飞书登录」→
浏览器完成平台飞书 OAuth → 自动跳回并显示已登录账号。授权完成页会等待
模型配置就绪后自动关闭；配置失败时展示原因并提供「重试同步」。

登录成功后插件自动完成模型配置（也可点「重新同步模型」手动触发）：

- `$DSH_HOME/settings.yaml` 写入 `llm-pi-ai.providers.platform`（指向平台
  `/api/plugin/v1` 代理）与 `agent-default-model`，dsh 模型选择器出现
  「平台模型」；模型列表按系列聚簇 + 系列内版本降序写入（插件侧按平台
  `sort_models_by_version` 同一规则兜底重排，旧版平台返回的上游原序也能得到
  稳定顺序，默认模型仍取平台下发的 `default_model`）；
- `$DSH_HOME/.credentials.yaml` 写入 `refs.AGENTONE_API_KEY`（0600），内容
  是 30 天插件令牌而非真实模型密钥——密钥不出平台，TokenHub 按用户计量；
- 只覆盖 `platform` 命名空间，用户自己配置的其它 provider 原样保留；
- 同步失败（如平台侧 AirRouter 瞬时不可达）不阻断登录/启动，原因记录在
  状态页「同步状态」；状态页轮询发现残留错误时按指数退避（1min 起、
  封顶 30min、最多 30 次）自动重试，平台恢复后无需重启 dsh 即自愈；
- 「退出登录」（页头按钮）会吊销平台令牌、移除凭据引用与 platform
  provider（其它 provider 的默认模型设置不受影响）；凭据文件损坏时也能
  正常退出（坏文件移开为 `credentials.json.corrupt`）。

登录流（与平台 `app/api/plugin_auth.py` 契约）：

```
插件页 ──POST /agentone/api/login──▶ 本插件后端
       ◀─ {login_url} ──
浏览器 ──login_url──▶ 平台飞书 OAuth ──▶ /api/auth/plugin/landing
       landing(JS, Bearer) ──POST /api/auth/plugin/grant──▶ {redirect_url(一次性 code)}
浏览器 ──redirect_url──▶ 本插件 /agentone/callback?code
       插件后端 ──POST /api/auth/plugin/exchange──▶ {access_token}
       （存本机 0600，state 比对防 CSRF）
```

所有写操作接口仅接受 `Content-Type: application/json` 的请求，阻止跨站
表单伪造 JSON POST。

## 配置（dsh settings）

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `platformUrl` | `https://ccpg.one.agentone.work` | AgentOne 平台地址（本地开发用 profile `cordis.patch.yml` 覆盖为 `http://127.0.0.1:8558`） |
| `storeDir` | `$DSH_HOME/agentone` | 凭据目录 |

密钥类值一律不进 settings，仅落 `credentials.json`（0600）。

## 模块结构

```
lib/
  index.js   路由与业务编排（登录/状态/技能/套餐/插件/CLI）
  page.js    状态页与授权完成页的 HTML/CSS/JS 模板（纯静态）
  http.js    平台请求统一通道（超时、错误码透传）
  auth.js    登录流、令牌轮换/吊销、能力面/套餐 API
  language.js 全局中文回复默认（$DSH_HOME/AGENTS.md 受标记管理注入）
  model.js   平台模型 → settings.yaml / .credentials.yaml
  skill.js   技能下载/解包/卸载（zip 穿越清洗、原子落盘）
  store.js   凭据持久化（0600；损坏自动移开）
  proc.js    dsh/pnpm CLI 转发与 lark-cli/ccpg-cli 探测
  qrcode.mjs 授权 URL 的二维码 SVG（vendor qrcode-generator，MIT；lark/ccpg 通用）
  client.js  dsh 浏览器端 bundle（设置菜单 iframe + 首启引导 + 设置导航 workbench 图标换肤）
```

## 开发

```bash
# 本地路径安装调试（无需发包）
dsh plugin --profile web add /path/to/plugins/dsh/dsh-agentone
```

无构建步骤（纯 ESM JS）；运行时 peer 依赖 `@deepseek-ai/cordis` /
`@deepseek-ai/schemastery` 由 dsh host 提供。测试：`npm install && node --test`
（YAML 合并/登出清理语义、路由冒烟、凭据容错、令牌轮换等）。