LuatOS 是面向合宙 LuatOS 开发者的编辑器工具集，重点提供 Lua 项目的自动化编程、构建、设备下载、运行检测和问题修复闭环。它以独立的 LUATOS 工作台运行，可安装到 Visual Studio Code、Trae / Trae CN 和 Qoder。

能做什么

自动化编程与调试闭环

LuatOS 会结合当前项目、源码、SOC 固件信息、设备串口和运行日志理解任务，并按需调用受控工具完成工作：

检查项目结构、luatos.json、固件和设备状态；
读取相关源码、构建文件和官方 LuatOS 文档；
生成或修改代码，并通过 VS Code 原生 Diff 审核；
使用 LuaTools 兼容构建器生成脚本镜像；
根据项目和固件状态选择首次完整下载或后续脚本下载；
复位设备并采集串口启动日志；
根据日志、源码和官方资料判断运行结果；
如果发现明确问题，提出修复补丁，审核通过后继续构建、下载和验证。

下载、复位、日志采集和代码写入都由编辑器本地执行。模型只能调用已注册的受控工具；结构化进程使用参数数组和 shell:false，Git 使用类型化操作，工作区外目录必须逐次授权。

文档问答与 Lua 编程

查询官方 Docs Chat、API、型号规格、固件差异和官方示例；
生成 Lua/LuatOS 代码，检查 API、参数、模块和适用平台；
读取当前项目上下文，也可以通过 + 主动附加 Lua 或配置文件；
支持 Markdown 回答、引用、工具状态和可展开的调试输出；
以 LuatOS 为重点，同时可处理当前可信目录中的 C/C++、Python、TypeScript、构建脚本、测试、文档和普通文本；二进制与 Git 内部文件不会通过补丁工具修改。

项目与资源管理

自动识别包含 luatos.json、user/ 和 core/ 或 firmware/ 的项目；
新建项目保存到工作目录的 userprojs/，并保持 LuaTools 兼容；
导入和导出 .luatos 项目包；
浏览、搜索、下载、校验和删除官方固件、默认扩展库、资料、驱动和工具；
自动管理最新可用的 Windows x64 luatos-cli；
不要求安装 LuaTools 程序，但可以和 LuaTools 共用同一个工作目录。

多会话与协作

会话历史按工作区保存在本机；
不同会话可以绑定不同项目、SOC、设备和串口，并发执行；
Plan 用于只读分析和生成实施计划；
Auto 用于按任务执行代码、项目或设备操作；
复杂任务显示一张可展开的执行活动卡和协作分析状态；
支持请求审批、替我审批、完全访问权限三种审批方式。

安装

从扩展发布页下载 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 实例同时运行时关闭旧实例后重试。

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 上首次执行 CLI 相关操作时，插件会从官方资源清单下载并校验最新版 luatos-cli。

4. 选择项目、芯片和串口

进入会话后，在输入框上方选择：

项目：当前会话使用的 LuatOS 项目；
芯片：项目 luatos.json 和 SOC 文件解析出的型号；
串口：点击串口控件时刷新设备列表，再选择当前设备。

EC7xx 等 USB 虚拟串口在完整固件下载后可能重新枚举为新的 COM 端口。此时重新点击串口控件选择新端口，不要继续使用旧端口。

对话与执行模式

Auto

Auto 是默认执行模式。Agent 会根据用户任务和工具结果决定是否需要读取文件、修改代码、构建、下载或采集日志，不会因为普通“生成代码”请求而自动刷机。

可以直接输入：

检查当前项目，修复启动错误，并下载到设备验证运行结果

或：

下载当前项目并检测启动是否成功，发现问题后给出修复方案

如果任务涉及设备，Agent 会先检查项目、SOC、CLI 和串口，再根据结果选择合适的下载与日志步骤。

Plan

Plan 只进行读取、检索和分析，不修改文件、不构建、不下载、不复位设备，也不采集串口日志。

适合输入：

分析这个项目的启动流程，列出可能受影响的文件和验证步骤

生成有效实施计划后，会显示“开始实现计划”。点击后会切换到 Auto，并把计划作为隐藏上下文交给 Agent 执行。

审批方式

请求审批：每次工具调用、补丁应用和设备操作都需要确认；
替我审批：可信目录中的读取、搜索、普通文本修改、构建、测试和代码生成会自动执行；删除、大型或关键配置补丁、Shell、外部 MCP/Skill、远端 Git、未授权目录和敏感文件会请求确认。用户明确要求的本机 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 配置；
可启用、禁用、测试和管理自定义来源；
Plan 只加载只读工具；
敏感 MCP action 仍遵守审批策略；
不修改 Copilot、Trae 或 Qoder 自身的配置和运行状态。

平台限制

Windows x64 桌面宿主：支持完整的项目、资源、CLI、串口、下载和日志闭环；
macOS / Linux：支持问答、Lua 代码、项目、资源和 Skill/MCP，当前不提供本机硬件 CLI；
SSH、WSL 和远程工作区：支持远程项目与代码操作，不访问本机串口，也不提供下载、复位和本机日志工具。

常见问题

没有看到 LUATOS

重载窗口后从命令面板执行 LuatOS: Open Workbench。如果 Activity Bar 图标位于 … 菜单中，可在 Activity Bar 的自定义菜单中将 LuatOS 固定。

资源一直加载

确认工作目录有效，点击“刷新清单”后等待官方清单完成；网络不可用时，插件会尝试使用本地缓存。资源管理页支持按资源、版本和状态查询。

下载失败或设备无日志

确认使用 Windows x64 本机宿主，项目、SOC 和串口选择正确，设备没有被其他串口工具占用。EC7xx 完整下载后要重新选择重新枚举的 COM 端口。

修改没有直接写入

这是默认安全行为。请在 Diff 中审核并应用补丁；如果审批模式要求确认，需要先点击“同意一次”或“同意并记住”。

隐私与安全

登录凭据保存在当前编辑器的 SecretStorage；
本机绝对路径、账号密码和串口凭据不会发送给模型；
服务端不能下发任意命令、任意路径或任意串口；
写文件、下载、复位和日志操作受本地项目边界和审批策略限制。

LuatOS