LuatOS
LuatOS 是面向合宙 LuatOS 开发者的编辑器工具集，重点提供 Lua 项目的自动化编程、构建、设备下载、运行检测和问题修复闭环。它以独立的 LUATOS 工作台运行，可安装到 Visual Studio Code、Trae / Trae CN 和 Qoder。
能做什么
自动化编程与调试闭环
LuatOS 会结合当前项目、源码、SOC 固件信息、设备串口和运行日志理解任务，并按需调用受控工具完成工作：
- 检查项目结构、luatos.json、固件和设备状态；
- 读取相关源码、构建文件和官方 LuatOS 文档；
- 生成或修改代码，并通过 VS Code 原生 Diff 审核；
- 使用 LuaTools 兼容构建器生成脚本镜像；
- 根据项目和固件状态选择首次完整下载或后续脚本下载；
- 复位设备并采集串口启动日志；
- 根据日志、源码和官方资料判断运行结果；
- 如果发现明确问题，提出修复补丁，审核通过后继续构建、下载和验证。
下载、复位、日志采集和代码写入都由编辑器本地执行。模型只能调用已注册的受控工具；结构化进程使用参数数组和 shell:false，Git 使用类型化操作。Auto 可按任务注册本机目录，凭据和安全配置仍保留本地审批。
文档问答与 Lua 编程
- 查询官方 Docs Chat、API、型号规格、固件差异和官方示例；
- 生成 Lua/LuatOS 代码，检查 API、参数、模块和适用平台；
- 自动带入当前项目摘要和编辑器上下文；也可直接拖拽或粘贴多个文件、文件夹作为附件；
- 支持 Markdown 回答、引用、工具状态和可展开的调试输出；
- 以 LuatOS 为重点，同时可处理当前可信目录中的 C/C++、Python、TypeScript、构建脚本、测试、文档和普通文本；二进制与 Git 内部文件不会通过补丁工具修改。
项目与资源管理
- 自动识别包含 luatos.json、user/ 和 core/ 或 firmware/ 的项目；
- 新建项目保存到工作目录的 userprojs/，并保持 LuaTools 兼容；
- 导入和导出 .luatos 项目包；
- 浏览、搜索、下载、校验和删除官方固件、默认扩展库、资料、驱动和工具；
- 自动管理最新可用的 Windows x64、Linux x64/arm64 和 macOS x64/arm64 luatos-cli；
- 不要求安装 LuaTools 程序，但可以和 LuaTools 共用同一个工作目录。
多会话与协作
- 会话历史按工作区保存在本机；
- 不同会话可以绑定不同项目、SOC、设备和串口，并发执行；
- Plan 用于只读分析和生成实施计划；
- Auto 用于按任务执行代码、项目或设备操作；
- 复杂任务显示一张可展开的执行活动卡、模型返回的 reasoning、Skill/MCP 轨迹和协作分析状态；
- 支持请求审批、替我审批、完全访问权限三种审批方式。
安装
从扩展发布页下载 VSIX，在 Visual Studio Code、Trae / Trae CN 或 Qoder 中选择“从 VSIX 安装”，安装后重载窗口。
打开方式：
- 点击 Activity Bar 中的 LuatOS 图标；
- 点击右侧辅助栏的 LUATOS；
- 在命令面板执行 LuatOS: Open Workbench；
- 打开 Lua 文件时，也可以点击编辑器右上角的 LuatOS 图标。
如果宿主不支持辅助栏，命令会自动在编辑器标签页打开同一个工作台。
首次使用
1. 登录 IoT 账号
在线问答和 Agent 服务需要先登录。
- 打开 LUATOS 工作台；
- 点击右上角齿轮进入设置；
- 在“账号”区域点击“登录 IoT 账号”；
- 浏览器会打开官方 IoT 登录页面；
- 完成登录并允许当前编辑器打开回调 URI；
- 返回编辑器，确认账号状态显示为“已登录”。
登录由官方网页完成，扩展不会保存账号密码，只在当前 IDE 的 SecretStorage 中保存登录凭据。VS Code、Trae 和 Qoder 的登录状态相互独立，首次使用每个宿主时都需要登录。
如果回调后仍显示未登录，请先重载窗口，再重新发起登录；若仍失败，退出账号后重新登录。将 VS Code 的
--user-data-dir、缓存目录或扩展目录迁移到其他盘符不会改变回调地址，扩展会使用当前宿主的 URI Scheme
和扩展全局存储；如果回调被另一个 profile 接收，也会通过短期加密交接完成登录。请确保迁移后的用户数据目录和
扩展全局存储目录可写，并在多个 VS Code 实例同时运行时关闭旧实例后重试。
服务连接与会话归属
需要本地项目、工具或设备能力的任务会请求 LuatOS Agent Gateway。扩展使用 OpenAI-compatible
/v1/chat/completions 接口；每次请求携带当前 IoT 用户 ID、应用 ID 和本地会话 ID，用于服务端认证、
用量统计与可选的账户会话记录。完整项目状态、设备配置、审批记录、附件、工具结果和调试日志仍保存在本机，
不会由服务器普通消息记录覆盖。纯官方文档问答继续使用独立的 Docs Chat 会话。
2. 设置工作目录
工作目录用于保存项目、资源、日志和 CLI。它可以是已有 LuaTools 目录，也可以是一个普通目录。
- 打开设置；
- 进入“工作目录与资源”；
- 点击“选择目录”；
- 选择 LuaTools 根目录，或选择其上级目录；
- 插件会扫描所选目录及最多两级子目录；
- 发现候选目录后确认使用；没有候选时可创建兼容目录。
判断依据是目录结构和工具文件，不依赖目录名称。插件会识别 Luatools*.exe、userprojs/、projexp/、project/、config/、resource/ 等结构。建议选择已有的 LuaTools 工作目录，例如 D:/LuaTools，但目录名称不是必要条件。
兼容目录通常包含：
_temp/
config/
log/
project/
projexp/
resource/
userprojs/
未设置工作目录时，普通文档问答和代码分析仍可使用；项目导入导出、资源下载、构建、串口、设备下载和日志调试会被禁用。
3. 准备资源和项目
设置好工作目录后：
- 进入“资源管理”；
- 点击“刷新清单”；
- 按分类搜索并下载需要的 SOC 固件或默认扩展库；
- 等待资源校验完成；
- 在“LuatOS 项目”中刷新项目，打开已有项目或创建新项目。
资源下载不依赖 LuaTools 程序。在 Windows x64、Linux x64/arm64 和 macOS x64/arm64 上首次执行 CLI 相关操作时，插件会从官方资源清单下载并校验最新版 luatos-cli。官方 1.10.0 包中的 Linux/macOS CLI 当前属于测试支持，实际设备连接仍需在对应平台验证驱动与权限。
4. 选择项目、芯片和串口
进入会话后，在输入框上方选择：
- 项目：当前会话使用的 LuatOS 项目；
- 芯片：项目 luatos.json 和 SOC 文件解析出的型号；
- 串口：点击串口控件时刷新设备列表，再选择当前设备。
EC7xx 等 USB 虚拟串口在完整固件下载后可能重新枚举为新的 COM 端口。此时重新点击串口控件选择新端口，不要继续使用旧端口。
5. Linux 和 macOS 的设备访问权限
Linux 同时为 USB 串口节点和原生 USB/libusb 节点分配权限。插件在 CLI 启动前检查已选择串口的已知节点；串口无权限时，会经用户确认后调用系统 Polkit 原生密码对话框，复检成功后继续原操作。若 CLI 已启动后才报告 LIBUSB_ERROR_ACCESS、EACCES 等原生 USB 错误，扩展会从 sysfs 识别 /dev/bus/usb/*/* 原生 USB/BootROM 节点并申请对应精确 VID:PID 的权限，但不会自动重复下载、复位或日志操作，避免部分执行后的重复写入；用户需手动重试。命令面板的 LuatOS: 申请 Linux 串口/USB 设备访问权限 会列出 luatos-cli 已发现的串口和从 sysfs 发现的原生 USB/BootROM 设备，也支持手动输入 VID:PID。扩展只会创建精确匹配所选 VID:PID 的 /etc/udev/rules.d/70-luatos-VID-PID.rules，删除同 VID:PID 的旧 99-luatos 规则；规则保留 TAG+="uaccess"，并仅为通过 Polkit 验证的当前编辑器用户设置节点所有权兜底，所以非活动桌面 seat 也不依赖 dialout 组。当前节点未重新枚举时会明确要求重新插拔，不会把规则已写入误报为可访问；下载连续 15 秒没有可见 CLI 输出时会显示等待设备响应。扩展不会读取、记录或保存密码。USB BootROM 重新枚举为不同 VID:PID 时，需对新标识再申请一次。Flatpak 和 strict Snap 会清楚提示宿主限制；deb、rpm、AppImage 和 classic Snap 受支持。没有 pkexec 或 Polkit 授权代理的系统会清楚报错，不会回退为 sudo 启动编辑器。
macOS 不存在 Linux 的 dialout/udev/Polkit 配置，因此没有可由扩展通过管理员密码安装的同类规则。普通桌面版 VS Code、Trae 或 Qoder 可以通过 BSD 设备节点访问串口；优先选择 CLI 列出的 /dev/cu.*，而不是 /dev/tty.*。如果失败，检查 USB 转串口驱动、端口是否被终端或其他 IDE 占用；如果日志出现 0xe00002c5 或“exclusive access”，这是驱动/进程独占而非 Linux 组权限。若使用沙箱化宿主，串口/USB 访问必须由宿主提供 com.apple.security.device.serial 和 USB entitlement，扩展不能自行申请或绕过。
对话与执行模式
Auto
Auto 是默认执行模式。Agent 会根据用户任务和工具结果决定是否需要读取文件、修改代码、构建、下载或采集日志，不会因为普通“生成代码”请求而自动刷机。
可以直接输入：
检查当前项目，修复启动错误，并下载到设备验证运行结果
或：
下载当前项目并检测启动是否成功，发现问题后给出修复方案
如果任务涉及设备，Agent 会先检查项目、SOC、CLI 和串口，再根据结果选择合适的下载与日志步骤。
Plan
Plan 只进行读取、检索和分析，不修改文件、不构建、不下载、不复位设备，也不采集串口日志。
适合输入：
分析这个项目的启动流程，列出可能受影响的文件和验证步骤
生成有效实施计划后，会显示“开始实现计划”。点击后会切换到 Auto，并把计划作为隐藏上下文交给 Agent 执行。
审批方式
- 请求审批：每次工具调用、补丁应用和设备操作都需要确认；
- 替我审批：普通文件读取、修改、构建、测试、代码生成，以及用户明确要求的本机 Git、下载和调试可连续执行。读取凭据、修改安全/环境文件、Shell、外部 MCP action、Skill 脚本、远端或破坏性 Git、网络与未明确要求的设备操作会请求确认；
- 完全访问权限：当前任务内自动允许当前会话可用的 Auto 工具，任务结束、失败、取消或切换权限后失效。凭据和破坏性 Git 操作仍需要当前任务明确提出。
审批卡提供“同意一次”“同意并记住”“拒绝”。记住的授权只在当前会话有效，并绑定当前项目、芯片、串口、目录或 MCP 工具范围；凭据和破坏性 Git 操作不可记住。
自动下载与运行检测
当任务明确要求下载、烧录、运行验证或调试时，Agent 可以执行完整流程：
- 检查项目和固件是否匹配；
- 首次部署或判断 core 不匹配时下载 core 和脚本；
- 已完成匹配部署后优先下载脚本；
- 生成 LuaTools 兼容的扁平脚本镜像；
- 执行脚本或完整固件下载；
- 等待 USB 串口重新枚举；
- 复位并采集启动日志；
- 将日志、源码和官方资料交给 Agent 分析；
- 根据诊断结果提出补丁并在审核后重试。
对话中的调试卡只显示当前活动状态和可展开日志摘要，完整 CLI 输出会保存到工作目录的 log/agent/ 目录。下载命令成功只代表写入完成，Agent 还需要根据启动日志判断程序是否真正运行。
项目文件与 .luatos
项目根目录需要包含：
- luatos.json；
- user/；
- core/<core 文件> 或 firmware/<core 文件>。
lib/ 是可选目录。活动项目由当前编辑器和工作区自动识别，不根据文件夹名称猜测。
导入和导出入口位于设置中的“LuatOS 项目”：
- 导入：选择 .luatos 压缩包，插件会验证结构后导入到 userprojs/；
- 导出：生成到 projexp/，不覆盖已有历史包；
- Windows 下会同步生成 LuaTools 可识别的项目索引文件。
Skill 与 MCP
设置中的“Skill 管理”和“MCP 管理”用于 LuatOS 独立加载：
- 扫描工作区、用户目录和宿主公开的 Skill/MCP 配置；
- 每轮先按任务、附件与项目状态选择最小能力集；匹配的 Skill 会先加载，再按其说明执行；
context: fork Skill 在只读子 Agent 中分析，主 Agent只接收结论；disable-model-invocation 和 user-invocable 会真实影响选择方式；- MCP 不再把全部工具塞入模型上下文，只注入本轮相关工具；遗漏时可按需搜索已启用服务；
- Plan 只使用只读本地与 MCP 能力；MCP action 和 Skill 脚本仍遵守审批策略；
- 不修改 Copilot、Trae 或 Qoder 自身的配置和运行状态。
当 Skill 覆盖任务时，Agent会优先遵循该 Skill；只有 Skill 缺失、加载失败或明确未覆盖某一步时，才会记录原因并回退到通用进程或 Shell。运行卡会显示实际匹配的 Skill、MCP、工具和模型返回的 reasoning；reasoning 是模型网关返回的可见文本，不代表模型未输出的内部状态。
平台限制
- Windows x64 桌面宿主：支持完整的项目、资源、CLI、串口、下载和日志闭环；
- Linux x64/arm64、macOS x64/arm64 桌面宿主：支持官方 luatos-cli 1.10.0 的本机 CLI、串口、下载、复位和日志操作；Linux/macOS CLI 目前为官方测试支持；
- SSH、WSL 和远程工作区：支持远程项目与代码操作，不访问本机串口，也不提供下载、复位和本机日志工具。
常见问题
没有看到 LUATOS
重载窗口后从命令面板执行 LuatOS: Open Workbench。如果 Activity Bar 图标位于 … 菜单中，可在 Activity Bar 的自定义菜单中将 LuatOS 固定。
资源一直加载
确认工作目录有效，点击“刷新清单”后等待官方清单完成；网络不可用时，插件会尝试使用本地缓存。资源管理页支持按资源、版本和状态查询。
下载失败或设备无日志
确认使用受支持架构的本机宿主，项目、SOC 和串口选择正确，设备节点访问权限和驱动需要正确配置。EC7xx 完整下载后要重新选择重新枚举的端口。
修改没有直接写入
这是默认安全行为。请在 Diff 中审核并应用补丁；如果审批模式要求确认，需要先点击“同意一次”或“同意并记住”。
隐私与安全
- 登录凭据保存在当前编辑器的 SecretStorage；
- 本机绝对路径、账号密码和串口凭据不会发送给模型；
- 服务端不能下发任意命令、任意路径或任意串口；
- 写文件、下载、复位和日志操作受本地项目边界和审批策略限制。
