- 默认截图后端是 MediaProjection;截图
AUTO不自动请求 Root、Shizuku 或无障碍。 - 手势注入后端
GestureBackend与截图后端正交;手势AUTO优先无障碍,仅当无障碍未连接且 Shizuku 已授权就绪 时用 Shizuku input,永不静默升 Root、不在 AUTO 路径弹 Shizuku 授权。 - 系统悬浮窗(
SYSTEM_ALERT_WINDOW)与无障碍服务不会由应用静默开启;须用户在系统设置中明确授予。应用内「显示悬浮窗」开关不能代替系统权限。 - 自动操作默认关闭;导入、备份和旧版本迁移不能静默开启。
- 自动操作需要当前免责声明版本;启用后在分析运行中按识别结果直接规划手势。
- MCP 默认关闭;启用后只监听 loopback;默认 免 Bearer(
requireAuth=false,同机免填 Header);开启鉴权时使用持久化authToken,仅用户主动「轮换 Token」时更换,不在每次服务启动轮换;默认每次写操作由手机确认。 - MCP 单工具策略
toolPolicies可强制确认 / 信任放行 / 禁用;外部摄入只能更严,不得把已禁用工具重新打开。 - 主题包是有大小限制的声明式 JSON,不加载脚本、字体或远程资源。
- 更新产物必须校验包名、版本、SHA-256、证书与签名清单。
- 截图帧、日志、MCP 令牌和 DataStore 配置不进入系统云备份。
- Root / Shizuku 命令分别读取 stdout/stderr,并限制输出、超时和图片尺寸。
必须同时满足(实现以 VisionRuntimeController / GestureArbiter 为准):
automation.enabled == truedisclaimerAcceptedVersion达到当前AppConfig.DISCLAIMER_VERSION- 视觉分析正在运行
- 有效手势后端可用并完成前台门控:
ACCESSIBILITY(及 AUTO 落在无障碍时):服务已连接,前台窗口可解析(事件 + 主动刷新)SHIZUKU/ROOT:shellinput注入;前台包由 dumpsys 探测(失败 fail-closed);input完成语义为命令 exit0,弱于dispatchGesture回执
- 可选包名门控:仅当用户开启
restrictPackages时,前台包须 ∈allowedPackages(默认不限制;外部摄入不得静默关闭限制或扩大列表) - 无障碍路径:前台窗口类名可用(空类名 fail-closed);shell 路径 class 可空,仅包名+时效
- 场景置信度、障碍置信度、稳定帧、动作速率与手势回执校验通过
- 切换
gestureBackend/ 其它安全边界 →cancelActions();外部摄入saferGestureBackend禁止升风险序(AUTO < 无障碍 < Shizuku < Root)
失败路径应 fail-closed:cancelActions() 取消在飞动作、清空队列、不注入手势。
运行页展示 lastAutomationDecision;决策日志 algo.decision 的 skip/dispatch 以 INFO 输出。
| 层 | 要求 |
|---|---|
| 网络 | 默认 IPv4 loopback 127.0.0.1;用户显式关闭 bindLocalhostOnly 后可绑 0.0.0.0(局域网)。导入不得静默开局域网。展示地址与绑定分离 |
| 认证 | 默认免鉴权;开启 requireAuth 时用持久化 authToken(恒时比较,Bearer 前缀大小写不敏感);不在每次启动轮换,仅设置页主动轮换 |
| Origin | 空 / 字面量 null 允许;非空时必须是本机回环标识 |
| 会话 | Mcp-Session-Id 仅内存;initialize 后即就绪;服务 stop/generation 推进后全部作废 |
| 权限 | 只读 / 每次确认 / 会话信任 / 完整访问 |
| 工具策略 | mcp.toolPolicies:DEFAULT / ALWAYS_ASK / ALLOW_WHEN_TRUSTED / DISABLED;禁用项不进 tools/list(策略读 current(),可含设置预览) |
| 服务绑定 | 前台服务启停/端口/鉴权/LAN 仅跟已保存配置(savedConfig);草稿不重启 socket。改 permissionLevel / toolPolicies 不重启服务(运行时读 current()) |
| 访问日志 | 进程内 ring(McpAccessLog,默认开);记 method/工具/状态/耗时/远端摘要;永不记 Bearer/参数体;可关 accessLogEnabled |
| 会话信任 | 绑定当前内存会话;不得把 TRUSTED_SESSION 当跨重启持久特权 |
| 失效会话 | 服务重启后旧 Mcp-Session-Id 对 tools/call 降级无会话继续;TRUSTED 仍须有效会话 |
| 完整访问 | 仅应用内权限,不能绕过系统录屏 / 悬浮窗 / 无障碍 / 安装界面 |
| 并发 | 连接数上限;超额 429 |
| 审批 | 超时/停止服务时默认拒绝,避免断连后仍执行写副作用 |
| 调试帧 | 需开发者选项与 MCP 显式允许;只暴露元数据或受控文件 |
| 日志/诊断 | get_logs / export_diagnostics 需开发者;内容脱敏,不含 Bearer/像素 |
| 设置导出 | MCP get_settings / app://settings/current 脱敏 authToken(***);用户备份导出仍可含 Token |
| 高风险写 | 开启自动操作、开启开发者、下载算法、改 MCP 权限/鉴权/工具策略:TRUSTED_SESSION 拒绝,需每次确认或 FULL_ACCESS |
| 局部补丁 | patch_settings 白名单路径,不得改 automation.enabled / MCP 鉴权令牌 / 自提权限级 |
| 外部摄入 | 不得静默关闭 requireAuth、改写/清空 authToken、自提权限级、开启 MCP 或放宽 toolPolicies |
AppLog为进程内 Logcat + 内存 ring buffer;不写外部存储、不上传。- 应用内
LogViewerScreen仅展示 ring buffer,支持筛选/复制/分享;不含系统 logcat 全量采集。 AlgorithmPipelineScreen仅展示进程内激活阶段与最近一帧摘要,不含检测框像素与密钥。- 诊断导出(设置 / 关于)含版本、机型、配置摘要与最近日志;不含 Bearer、签名密钥与调试帧像素。
- 日志路径对
Bearer …与常见token/secret/password键值做脱敏;MCP 连接串仅经用户显式「复制连接信息」进剪贴板,不得写入日志。 - 关闭开发者选项后,DEBUG/VERBOSE 不再进入 ring buffer。
- 系统「指针位置」开关写入
pointer_location(读 system/secure):可用户点选请求 Shizuku 授权(主线程);已授权后走ShellProcessSupport(绝对路径/system/bin/settings/cmd,首条成功即停,与 input 一致防 PATH 空);否则「修改系统设置」/ Root。以延迟回读为准。应用不得静默获得WRITE_SETTINGS、不得无用户手势就弹 Shizuku 授权或静默升 Root,也不得把该状态写入导入配置。
- 像素缓冲有明确租约与
close()生命周期。 - 分辨率变化使帧池 generation 失效,旧 lease 不得回池。
- 最大边与像素总数有上限(与 Native 一致:边 4096,像素 8_388_608)。
- Shizuku 后端仅在用户显式选择时启用;通过反射调用 Shizuku 进程 API 执行
screencap -p,失败 fail-closed。AUTO 路径永不探测 Shizuku。
- JSON / DataStore 有字节上限与字段校验。
- 自动化
allowedPackages与内置默认集合求交。 - 主题包拒绝未知可执行字段与超大 payload。
- 仅 HTTPS。
- 清单签名绑定本应用安装证书公钥;Debug 包不能伪装成生产更新源。
- 差分补丁回放校验后才可安装。
.hzzsalg使用独立 Ed25519 密钥,不得复用 APK keystore。- 包内仅声明式 JSON / 文本;拒绝可执行扩展名、符号链接、路径穿越与 Zip 炸弹。
- 目录
algorithms/{channel}.json最后发布;资产哈希不一致时拒绝覆盖。 - Secrets:
ALGORITHM_SIGNING_PRIVATE_KEY_B64、ALGORITHM_SIGNING_KEY_ID(与ANDROID_KEYSTORE_*分离)。 - 运行时只接受校验后的
AlgorithmRuntimeProfile;不得动态加载代码;失败回退内置;不得改写自动化门禁。 - 信任锚:
AlgorithmTrustAnchors.officialPublicKeyDerB64当前含hzzs-algorithm-official-1;列表为空时远端下载/安装 fail-closed。 - APK 捆绑包:
assets/algorithms/<id>/经BundledAlgorithmInstaller幂等预装,视为应用本体声明式参数,不经外装 Ed25519;不覆盖用户已安装同 id 包。 - 分析运行中切换算法只记 pending,由
AlgorithmCatalogController.setAnalysisRunning与激活协调器在安全点切换。 - 详见
docs/ALGORITHM_SYSTEM_V1.md。
禁止提交 keystore、密码、Token、未脱敏截图与用户隐私数据。详见 CONTRIBUTING.md。