前言¶
在 DSHA（DeepSeek Harness 安卓端）里，通知、震动、剪贴板、读屏、传感器、定位、手电等设备能力，通过本地桥 http://127.0.0.1:3090 暴露给容器内的 agent。接口能调通，并不表示此刻就能用：同一端点可能因开关未开、系统未授权、App 前后台时机不对，或桥/无障碍真的异常而失败，且修法各不相同。若 agent 把几种失败混为一谈，往往会无效重试，浪费 token 却得不到可用能力。
下面介绍社区插件 dsha-capability-map（维护者 Liaoyun666）。它把「这台设备此刻的能力边界」做成可横向对比的实测表，并在结论里区分 DISABLED、NO_PERMISSION、时机类跳过与真实异常，明确哪些情况重试无效。
这是什么¶
DSHA 设备能力地图（npm 包名 dsha-capability-map，版本 1.0.0，MIT）面向在 DSHA 安卓 arm64 容器里跑 agent 的场景：用 14 项探测对桥端能力做体检，输出分组表格或结构化 JSON，并支持两次结果 diff。插件零运行时依赖，判定逻辑与 CLI 共用 lib/probes.js。
目录页：https://www.skillhub.cn/plugins/Liaoyun666/dsha-capability-map
源码：https://github.com/Liaoyun666/dsha-capability-map
SkillHub 分类含 admin-security；包清单里还标注 diagnostics、android。DeepSeek Harness 生态以「一切皆插件」组织，SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
三种 agent 工具¶
dsha_capability_map— 跑 14 项探测，输出分组表与一句「下一步」建议（例如去 DSHA → 设置 → 设备能力勾选，或去系统设置授权）。dsha_capability_json— 同样 14 项，schemaVersion: 1的稳定 JSON，便于报告、脚本或日后对比。dsha_capability_diff— 对比两次 JSON/体检结果，列出状态或设备信息变化。
失败原因如何区分¶
插件按 DSHA 桥返回的错误码映射状态，而不是靠文案猜测。README 归纳的典型对应关系如下：
| 你看到的 | 真实原因 | 该做什么 | 重试有用吗 |
|---|---|---|---|
DISABLED |
用户在 DSHA 设置里未开启该能力 | DSHA → 设置 → 设备能力勾选 | 否 |
NO_PERMISSION |
Android 系统权限未授予 | 系统设置中为 DSHA 授权 | 否 |
FOREGROUND_SKIP / APP_BACKGROUND |
App 前后台时机不对 | 调整 DSHA 前后台后再测 | 是 |
[ERR] 无障碍服务未连接 等 |
App/桥侧异常 | 排查 DSHA 侧问题 | 视情况 |
对 DISABLED 等情形，fix 文案中会写明「重试无效，必须先开开关」，以减少 agent 无效重试。
14 项探测（分组与端点）¶
探测按 meta、device、sensor、screen、actuator、ui 分组排版；工具参数 only 可按分组或单项收窄。
| 分组 | 探测项 | 端点 | 副作用 |
|---|---|---|---|
| meta | 桥版本 | /app/version |
|
| meta | 设备信息 | /app/device |
|
| meta | 插件加载状态 | /app/plugins |
|
| device | 应用清单（取 3 条） | /app/apps |
|
| device | 读设备文件（列 Download） | /app/readfile |
|
| device | 读剪贴板 | /app/clip |
需前台 |
| sensor | 传感器清单 | /app/sensors |
|
| sensor | 环境光 | /app/sensor?name=light |
|
| sensor | 定位（fresh=0） |
/app/location |
|
| screen | 读屏（无障碍节点树） | /app/ui/dump |
|
| actuator | 手电（只关不开） | /app/torch?on=0 |
有 |
| actuator | 震动（1 毫秒） | /app/vibrate?ms=1 |
有 |
| ui | App 内提示 | /app/toast |
有 |
| ui | 通知栏 | /app/notify |
有；前台可能被跳过 |
手电、震动、通知、toast 四项默认不执行（避免体检误触设备）；需显式开启副作用探测。手电探测始终发送 on=0，即使用户本已开灯也不会保持常亮不管。
桥不可达时，CLI 会将整批 BRIDGE_DOWN 收敛为一句说明（例如不在 App 内或 App 被回收时重试亦无效）。
安装与启用¶
在 DSH/DSHA 环境中任选其一安装（以 README 原文为准）：
dsha-plugin install Liaoyun666/dsha-capability-map
或：
dsh plugin add Liaoyun666/dsha-capability-map
装完后新开一个会话即可使用三个工具。兼容声明：dsh >= 0.1.5-rc.1，node >= 20。装到桌面端不会崩溃，但工具会如实提示读不到桥凭据、本插件仅在 DSHA 中有诊断意义。
插件以当前 dsh 进程权限运行，安装前建议自行查看 GitHub 仓库 源码与 MIT 许可证。
典型用法¶
会话内工具¶
体检（默认不跑副作用项）： 调用 dsha_capability_map。可选参数：
| 参数 | 默认 | 说明 |
|---|---|---|
includeSideEffects |
false |
是否实际触发手电/震动/通知/提示 |
only |
全部 | 仅查指定探测或分组：meta device sensor screen actuator ui |
verbose |
false |
通过项也输出明细与耗时 |
存档： 调用 dsha_capability_json，得到带 verdict、headline、counts、probes 等字段的 JSON。
对比： 在换机、升级 DSHA 或改设置后，用 dsha_capability_diff 对比两次结果，例如「环境光 disabled → ok」「定位 no-permission → ok」。
命令行（同套探测逻辑）¶
在插件目录或已安装环境中，可用 node tools/cli.js 做同样排查：
node tools/cli.js # 人读表格
node tools/cli.js --all # 含手电/震动/通知
node tools/cli.js --json # 机器可读
node tools/cli.js --out snap.json # 存档
node tools/cli.js --only sensor # 只看传感器
node tools/cli.js --list # 列出 14 项
node tools/cli.js --diff old.json new.json
退出码：0 全部可用（或副作用项被跳过）、1 有不可用或异常、2 参数或桥问题；CI 可用退出码作门禁。
桥地址与凭据：环境变量 DSHA_BRIDGE_URL（默认 http://127.0.0.1:3090）、DSHA_BRIDGE_TOKEN；缺省从 /root/.dsh/.bridge_token 或 /root/.dsh/.bridge_headers 读取。
适用场景与注意¶
适合谁： 在 DSHA 上开发或运维 agent、需要先确认「这台手机现在哪些设备能力真的可用」再写 prompt 或编排工具链时；换机、改 DSHA 设置或升级后做 before/after 对比时。
姊妹插件（README 相关链接）： dsha-native-tools 提供 16 个设备能力工具（本插件偏诊断，彼插件偏调用）；dsh-android-portability 做插件包在安卓 arm64 上的静态可移植性检查。
注意： 探测对桥串行发请求，避免并发挤占 App 内单服务。不确定状态（如 DISMISSED、USER_NO_ANSWER、RESULT_UNKNOWN）会归入「不确定」，不硬判成功或失败。
结尾¶
dsha-capability-map 用一条体检命令回答「agent 在这台安卓上到底能用哪些 DSHA 能力」，并把没开开关、没给权限、时机不对和真异常分开写清，减少无效重试。需要安装或细节时，见 SkillHub 目录页与 GitHub README。
