开发说明 ​

设备控制扩展的开发目标，是把“服务端会话编排”和“本地节点执行”分开。

推荐的职责划分如下：

• Ai 模块：负责智能体、会话、审批、工作流与消息
• AiDesktop 模块：负责节点注册、会话绑定、动作下发、结果回传
• dux-ai-node：负责在本地设备执行真实动作

模块边界 ​

服务端 ​

服务端主要负责：

• 设备注册与状态管理
• 节点能力定义
• 会话与节点绑定
• 动作风险分级
• 审批流程
• 结果存储与消息展示

节点端 ​

节点端主要负责：

• 长连接保持
• 本地浏览器、文件、终端、截图等动作执行
• 本地日志记录
• 结果与产物回传

当前动作模型 ​

当前节点动作采用统一入口，底层按 action 分发执行。例如：

• browser.launch
• browser.goto
• browser.read
• file.list
• file.stat
• file.read_text
• file.open
• terminal.exec
• screen.capture
• system.info

这种模型的好处是：

• 服务端工具层保持统一
• 风险控制可以在动作级别做
• 后续新增能力时不需要重新设计整套协议

风险控制建议 ​

建议继续遵循下面的规则：

• 默认能力视为安全
• 只有明确标记为高风险的动作才进入审批
• 风险判断放在动作元数据里，不在 Ai 模块写桌面专用分支

典型做法是：

• system.info、file.list、browser.read：安全
• terminal.exec：危险，需要审批

Linux 节点建议 ​

Linux 节点建议按 daemon/headless 模式运行，适合：

• 服务器
• CI 节点
• 自动化工作机
• 内网 Linux 主机

推荐做法：

• 使用 systemd 管理服务
• 配置目录、数据目录、日志目录通过环境变量覆盖
• 通过安装脚本自动安装 Chromium 与运行时依赖

版本与发布建议 ​

当前建议的发布策略：

• macOS：x86_64 与 arm64
• Windows：x86_64
• Linux：x86_64 与 arm64

GitHub Actions 应分别产出对应架构包，避免用户误装错误架构。

文档扩展建议 ​

如果后续继续扩展节点能力，建议文档也按“扩展”维度拆分，而不是全部堆在使用章节里。

例如后续可以继续新增：

• 办公文档控制
• 代码仓库控制
• 服务器运维控制
• 自定义节点能力

每个扩展单独维护：

• 简介
• 安装
• 使用教程
• 开发说明

这样结构会比单纯堆在 usage 或 dev 目录下更清晰。