luxus0946/dsh-uuyc

description: "用于 deepseek-harness 的 UU 远程（uuyc-cli）Windows 远程控制插件：设备管理与远程终端执行"
kind: "package"

dsh-uuyc — UU 远程 Windows 控制插件

通过网易 UU 远程的 uuyc-cli 控制远程 Windows 机器：列出 / 连接 / 断开设备，并在远程终端中运行命令。本插件仅在本地启动 uuyc-cli.exe 并解析其输出；身份验证与网络连接由已登录的 UU 远程桌面客户端处理。

平台限制：uuyc-cli 的 term 远程终端仅支持 Windows 被控端。对于远程 Linux 服务器，请使用 harness 原生的 SSH 后端，而非本插件。

安装（作为 DSH bundle）

用一条命令将其安装到你自己的 DSH profile 中：

dsh plugin --profile  add github:luxus0946/dsh-uuyc

过程如下：DSH 克隆本仓库，并根据 cordis.patch.yml 将 uuyc 插件挂载到 profile 中。不会执行任何构建步骤 —— 编译后的 lib/ 已提交到仓库，正是为了让源码安装不会失败（见下方前置条件）。

前置条件 —— 匹配的 DSH 宿主。 本插件依赖宿主提供的 peer 依赖：它需要一个提供 @deepseek-ai/dsh-tools@^0.1.6-alpha.2、@deepseek-ai/dsh-brand@^0.1.6-alpha.2、@deepseek-ai/cordis@^4.0.2 和 @deepseek-ai/schemastery@^3.18.2 的 harness。这两个 DeepSeek 包未发布在公共 npm registry 上（仅发布了 0.0.1-rc.1），因此本插件只能在提供这些包的 harness 构建中加载 —— 即 harness 源码检出或内部构建。仅有公共 dsh 的用户无法使用它。

仅限 Windows：cordis.patch.yml 设置了 disabled: !!js process.platform !== 'win32'，因此非 Windows 宿主会自动跳过本插件（uuyc term 仅支持 Windows 被控端）。

其他分发方式

- npm：pnpm publish（已配置 prepublishOnly 先构建 lib/），然后 dsh plugin add @deepseek-ai/dsh-uuyc。
- tarball：pnpm pack 生成 dsh-uuyc-.tgz，然后 dsh plugin add ./dsh-uuyc-.tgz。

开发：本地构建与端到端测试

pnpm build          # tsdown: src/.ts → single lib/index.js (ESM) + lib/index.d.ts
pnpm typecheck      # tsc --noEmit (requires the @deepseek-ai/ peers; see note)

pnpm install 无法自行获取这些 peer 依赖 —— @deepseek-ai/dsh-tools 和 dsh-brand 不在公共 registry 上。在运行 typecheck 之前，请将 node_modules/@deepseek-ai/ 指向本地 harness（或使用 workspace 安装）。pnpm build 不需要它们：这些 peer 被标记为 external，因此只有 typecheck 依赖它们的类型声明。

针对真实设备的端到端测试（已安装并登录 UU 远程，被控设备在线）：

pnpm build
UUY_CLI=D:/uu/GameViewer/bin/uuyc-cli.exe UUY_DEVICE= node scripts/e2e-real.mjs

功能
模型可见的工具 uuyc_terminal，由 action 分发：

| action | 描述 |
|---|---|
| list_devices | 列出账户下的设备（名称 / 设备 ID / 在线状态） |
| connect | 连接到设备（需要设备 ID；名称会自动解析） |
| disconnect | 断开连接（需要 ID —— 绝不会意外断开所有连接） |
| exec | 一次性会话：打开 → 运行命令 → 关闭，返回 stdout / 退出码 |
| open_session | 打开一个有状态会话，返回 session_id（空闲时自动回收） |
| run_in_session | 在指定会话中运行一条命令 |
| kill_session | 关闭指定会话 |
| list_sessions | 列出某设备的 uuyc 终端会话 |

前置条件（重要）

- UU 远程桌面客户端必须正在运行并已登录，否则 exec/connect 等会返回退出码 2，本插件会给出明确提示。
- uuyc-cli.exe 不在固定位置：在作者机器上是 D:\uu\GameViewer\bin\uuyc-cli.exe；文档中还记录过 D:\Netease\GameViewer\bin\uuyc-cli.exe，默认安装路径是 C:\Program Files\NetEase\GameViewer\bin\uuyc-cli.exe。将 cliPath 留空，插件会按顺序探测候选列表；如果都不存在，请在 cordis.yml 中显式设置。
- ⚠️ 无原生文件传输：uuyc-cli 的命令面（version/user/device/cloudpc/echo/term/lterm/input-diag）没有文件传输子命令。网上看到的 --upload/--pycode 标志属于上层 uu.py 封装，且 base64 换行不可靠。请通过 UU 远程的 GUI 传输文件，而不是本工具。

配置（cordis.yml / profile patch）

- id: uuyc
name: '@deepseek-ai/dsh-uuyc'
disabled: !!js process.platform !== 'win32'   # enable only on Windows host
config:
cliPath: ''                  # empty → auto-detect via PATH (where), running GameViewer.exe, then known install dirs
defaultShell: powershell      # powershell | cmd
execTimeoutMs: 120000
controlTimeoutMs: 15000
sessionIdleTtlMs: 600000
password: ''                 # optional: unlock password for locked devices, sent as first stdin line
handshakeRetries: 1          # auto retry on handshake failure (total attempts = 1 + retries)
handshakeBackoffMs: 1500     # backoff base (ms); nth retry waits backoffMs * n

工作流加固（内置）

- CLI 自动发现 —— 当 cliPath 为空时，插件按顺序探测：显式配置 → PATH 上的 where uuyc-cli.exe → 正在运行的 GameViewer.exe 进程旁边的 bin\uuyc-cli.exe → 一组已知安装目录（D:\uu、D:\Netease、C:\Program Files\NetEase、……）。通常你永远不需要设置 cliPath。
- 设备列表缓存 + 模糊匹配 —— device list 结果缓存 60 秒；target 接受设备名称或 ID，大小写不敏感匹配，并支持子串模糊匹配。如果模糊匹配命中多个设备，插件会列出候选设备，而不是猜测。
- 握手自动重试 — 在 handshakeUnavailable 时，插件会退避并重试，最多 handshakeRetries 次（握手失败通常是暂时性的——受控端没有活动终端，或 P2P 链路刚刚重启）。
- Shell 自动回退 — 如果默认的 powershell 一直握手失败，插件会在 cmd 上重试一次；如果 cmd 触发 terminal_bridge_unavailable，则回退到受支持的 powershell。

故障排查：锁屏 / 握手失败

- 锁屏：当受控端锁屏时，term 会交互式地询问解锁密码。两种方案：(1) 先在远程端解锁屏幕；(2) 在配置中设置 password，插件会将其作为第一行 stdin 发送。如果两者都没有，uuyc 会在 PTY 上等待密码，插件会超时（不会崩溃，可重试）——这是预期的优雅失败。
- 终端握手失败（“受控端版本过低” / “Start peer connection failed”）：意味着受控端没有活动终端会话，或两端 UU 版本不匹配。请让用户在远程 Windows 上打开一个 UU 终端窗口（P2P 重启后稍等片刻），然后重试。插件会同时扫描 stdout 和 stderr 中的这些关键词，返回 handshakeUnavailable，并（默认）自动退避重试一次，而不是一直挂起直到超时。
- terminal_bridge_unavailable：所选 shell 不受远程终端桥支持——最常见于请求 shell: cmd 时。插件会自动回退到 powershell。如果你确实需要 cmd，请确认受控端确实支持它。
- ⚠️ password 会出现在 cordis.yml 和对话日志中；提醒用户使用后更改它。

架构

- src/uuyc.ts — uuyc-cli 封装：健康检查、设备列表解析、连接/断开、退出码映射。
- src/session.ts — term 交互式会话驱动：哨兵检测、输出清理（ANSI / 回显剥离）、退出码解析。
- src/index.ts — 插件入口：注册 uuyc_terminal 工具，维护有状态会话表，连接取消信号和空闲回收。
- cordis.patch.yml — bundle 挂载声明，由宿主在运行 dsh plugin add 时应用。

已知限制和待办工作

- term 是会话式 PTY：没有原生的“运行一条命令并返回”语义。session.ts 使用哨兵 __UUYCDONE____ 来分割输出并剥离回显行；交互式提示符 / 回显 / 编码因 shell 和区域设置而异，必须在真实硬件上调优（尤其是 UuycTerminal.wrap 的哨兵写入）。
- 依赖 UU 远程桌面客户端：当客户端未运行 / 未登录时，所有命令返回退出码 2；插件只能报告和引导，无法绕过。
- 不支持 Linux：uuyc term 仅支持 Windows 被控端；Linux 终端服务器不在范围内（见上文平台限制）。
- 不带 ID 的 disconnect 是全局操作：底层语义存在风险；本插件强制要求带 ID 以避免此问题，但必须在文档和测试中持续覆盖。
- 无原生文件传输：CLI 没有文件传输子命令；请使用 UU 远程的 GUI（见前置条件）。
- 锁屏密码是可选的：password 配置仅在设备锁屏时需要；未锁屏的设备留空即可；发送逻辑是“stdin 第一行”，应在锁屏的真机上验证一次。
- 端到端测试已在真机上完成：listDevices + execOnce（powershell / 原生命令）在设备 便携 上通过；完整类型检查通过；握手失败 / 锁屏密码注入仍需在锁屏真机上验证。

dsh-uuyc — UU 远程远程 Windows 控制插件（中文）

通过 网易 UU 远程 的 uuyc-cli 控制远程 Windows 设备：列出/连接/断开设备，并在远程终端执行命令。本插件只负责本地调起 uuyc-cli.exe 并解析其结果，认证与网络由已登录的 UU 远程主客户端承担。

平台限制：uuyc-cli 的 term 远程终端仅支持 Windows 被控端。远程 Linux 服务器请使用 harness 原生 SSH 后端，不要走本插件。

安装（作为 DSH 组合包 / bundle）

直接用一行命令装进自己的 DSH profile：

dsh plugin --profile  add github:luxus0946/dsh-uuyc

安装过程：DSH 从 GitHub 拉取本仓库，按 cordis.patch.yml 把 uuyc 插件挂载进 profile。不再执行任何构建——编译产物 lib/ 已随仓库提交，这样源安装就不会失败（前置条件见下）。

前置条件：宿主版本需匹配。 本插件消费宿主提供的 peer，要求宿主提供 @deepseek-ai/dsh-tools@^0.1.6-alpha.2、@deepseek-ai/dsh-brand@^0.1.6-alpha.2、@deepseek-ai/cordis@^4.0.2、@deepseek-ai/schemastery@^3.18.2。其中 dsh-tools / dsh-brand 未发布到公共 npm（公共源上只有 0.0.1-rc.1），因此本插件只能在提供这些包的 harness 构建内加载 —— 即 harness 源码检出或内部构建版本；仅有公共 dsh 的外部用户无法使用。

仅 Windows 生效：cordis.patch.yml 里 disabled: !!js process.platform !== 'win32'，非 Windows 主控端会自动跳过本插件（uuyc term 只支持 Windows 被控端）。

其它分发方式

- 发到 npm：pnpm publish（已配置 prepublishOnly 会先构建 lib/），之后 dsh plugin add @deepseek-ai/dsh-uuyc。
- 交付 tar 包：pnpm pack 生成 dsh-uuyc-.tgz，再 dsh plugin add ./dsh-uuyc-.tgz。

开发者：本地构建与联调

pnpm build          # tsdown：src/.ts → 单文件 lib/index.js（ESM）+ lib/index.d.ts
pnpm typecheck      # tsc --noEmit 类型检查（需要 @deepseek-ai/ peer，见下方说明）

pnpm install 无法自行拉取这些 peer —— @deepseek-ai/dsh-tools 与 dsh-brand 未发布到公共 npm。跑 typecheck 前请把 node_modules/@deepseek-ai/ 指向本地 harness（或改用 workspace 安装）。pnpm build 不需要它们：peer 被标记为 external，只有 typecheck 依赖它们的类型声明。

端到端真机联调（需本机装好并登录 UU 远程、被控端在线）：

pnpm build
UUY_CLI=D:/uu/GameViewer/bin/uuyc-cli.exe UUY_DEVICE= node scripts/e2e-real.mjs

功能

模型可见工具 uuyc_terminal，按 action 分发：

| action | 说明 |
|---|---|
| list_devices | 列出账号下设备（名称 / 设备 ID / 在线状态） |
| connect | 连接设备（需设备 ID；名称会自动解析） |
| disconnect | 断开设备（强制带 ID，绝不误断全部） |
| exec | 一次性会话：开会话 → 执行命令 → 关闭，返回 stdout / exit code |
| open_session | 开启有状态会话，返回 session_id（空闲自动回收） |
| run_in_session | 在指定会话中执行一条命令 |
| kill_session | 关闭指定会话 |
| list_sessions | 列出某设备的 uuyc 终端会话 |

运行前提（重要）

- UU 远程主客户端必须已运行并登录，否则 exec/connect 等返回退出码 2，本插件会给出明确指引。
- uuyc-cli.exe 不在固定位置：本机实测为 D:\uu\GameViewer\bin\uuyc-cli.exe，文档也曾记录 D:\Netease\GameViewer\bin\uuyc-cli.exe，默认安装在 C:\Program Files\Netease\GameViewer\bin\uuyc-cli.exe。配置 cliPath 留空即可，插件会按这份候选清单依次查找第一个存在的路径；若都不存在再在 cordis.yml 显式指定。
- ⚠️ 无原生文件传输：uuyc-cli 的命令面（version/user/device/cloudpc/echo/term/lterm/input-diag）不包含任何文件传输子命令，网上流传的 --upload/--pycode 都是上层 uu.py 封装的参数，且 base64 折行不可靠。传文件请走 UU 远程客户端的 GUI 互传，不要尝试用本工具传文件。

配置（cordis.yml / profile patch）

- id: uuyc
name: '@deepseek-ai/dsh-uuyc'
disabled: !!js process.platform !== 'win32'   # 仅 Windows 主控端启用
config:
cliPath: ''                  # 留空→依次探测 PATH(where)、运行中的 GameViewer.exe 同目录、常见安装目录
defaultShell: powershell      # powershell | cmd
execTimeoutMs: 120000
controlTimeoutMs: 15000
sessionIdleTtlMs: 600000
password: ''                 # 可选：被锁屏设备的解锁密码，作为 stdin 首行发送
handshakeRetries: 1          # 握手失败时自动重试次数（总尝试 = 1 + 该值）
handshakeBackoffMs: 1500     # 退避基数（毫秒），第 n 次重试等待 backoffMs * n

内置的工作流加固

- CLI 路径自动发现：cliPath 留空时，插件按序探测：显式配置 → PATH 上的 where uuyc-cli.exe → 正在运行的 GameViewer.exe 同目录 bin\uuyc-cli.exe → 一堆常见安装目录（D:\uu、D:\Netease、C:\Program Files\NetEase 等）。多数情况下无需手动配置 cliPath。
- 设备列表缓存 + 模糊匹配：device list 结果缓存 60s；target 接受设备名或设备 ID，大小写不敏感，并支持子串模糊匹配。若模糊匹配命中多台设备，插件会列出候选清单而非盲目猜测。
- 握手自动重试：命中 handshakeUnavailable 时，插件按退避策略重试最多 handshakeRetries 次（握手失败多为瞬态——被控端无活跃终端，或 P2P 刚重启）。
- Shell 自动回退：若默认 powershell 持续握手失败，插件会用 cmd 回退重试一次；若 cmd 触发 terminal_bridge_unavailable，则回退到受支持的 powershell。

被锁屏 / 握手失败的排错

- 锁屏：被控端锁屏时 term 会交互式索要解锁密码。两种方式：(1) 先在远端解锁屏幕；(2) 在配置里填 password，插件会把密码作为 stdin 首行发送。若既未解锁也未配 password，uuyc 会在 PTY 上一直等密码，本插件表现为执行超时（不崩溃，可重试）——这是预期的优雅失败。
- 终端握手失败（"被控端版本过低" / "Start peer connection failed"）：说明被控端当前没有活跃终端会话，或两端 UU 版本不匹配。让用户在远程 Windows 上打开一个 UU 终端窗口（P2P 刚重启则稍等片刻），再重试即可。插件会扫描 stdout + stderr 中的这些关键词，命中即返回 handshakeUnavailable，并（默认）按退避自动重试一次，无需等到超时。
- terminal_bridge_unavailable：所选 shell 不被远程终端桥支持——多见于显式指定 shell: cmd。插件会自动回退到 powershell；若确实需要 cmd，请先确认被控端确实支持。
- ⚠️ password 会出现在 cordis.yml 与对话记录里，使用后应提醒用户修改密码。

架构位置

- src/uuyc.ts — uuyc-cli 封装：健康检查、设备列表解析、连接/断开、退出码映射。
- src/session.ts — term 交互式会话驱动：哨兵串检测、输出清洗（ANSI/回显剥离）、退出码解析。
- src/index.ts — 插件入口：注册 uuyc_terminal 工具、维护有状态会话表、接入取消信号与空闲回收。
- cordis.patch.yml — 组合包挂载声明，dsh plugin add 时由宿主应用。

已知限制与待办工作

- term 为会话式 PTY：没有原生"执行一条命令并返回"语义。session.ts 用哨兵串 __UUYCDONE____ 切分输出并剥离回显行；交互式终端的提示符/回显/编码因 shell 与区域而异，必须在真机上调优（尤其 UuycTerminal.wrap 的哨兵写法）。
- 依赖 UU 远程主程序：主程序未运行/未登录时全部命令退出码 2，插件只能报错指引，无法绕过。
- Linux 不支持：uuyc term 仅支持 Windows 被控端，Linux 服务器终端不在本插件范围（见上方平台限制）。
- disconnect 无 ID 即全局：底层语义风险，本插件已强制带 ID 规避，但需在文档与测试中持续显式覆盖。
- 无原生文件传输：CLI 无文件传输子命令，传文件请走 UU 客户端 GUI 互传（见运行前提）。
- 锁屏密码为可选特性：password 配置项仅在被锁屏设备需要，未锁屏设备留空即可；发送逻辑为“作为 stdin 首行”，需在真机（锁屏态）验证一次。
- 已做端到端真机联调：在设备便携上跑通 listDevices + execOnce（powershell / 原生命令），全量 typecheck 通过；握手失败/锁屏密码注入需在锁屏真机进一步验证。