博客

基于 IDEA Community 二次开发 LuaAgent IDE 的设计思路

如何复用开源 IntelliJ IDEA Community 代码基座，保持产品 fork 足够薄，把 LuaAgent 的语言智能、运行时连接和安全边界放进受控插件与 Runtime Bridge。

发布： 2026-06-24 分类：工具链

LuaAgent IDE 不应该只是一个换皮编辑器。LuaAgent 开发同时涉及 Lua 代码、Agent manifest、运行时能力、Topic 事件、记忆契约和验证结果。这个形态很适合基于 IntelliJ IDEA Community 二次开发：IDE 产品 fork 保持足够薄，把语言能力放进插件，把运行时执行放进明确的 Runtime Bridge，而不是让编辑器本身变成另一个脚本宿主。

JetBrains 将 IntelliJ 开源仓库描述为 JetBrains IDE 代码库的开源部分，也是 IntelliJ Platform 开发的基础。这意味着我们在写 LuaAgent 专属能力之前，已经拥有成熟编辑器、项目模型、索引系统、VCS 集成、Run Configuration 框架和扩展点模型。

基于 IDEA Community 的 LuaAgent IDE 架构图，包含薄产品 fork、LuaAgent 语言插件、Runtime Bridge、Eva-CLI Runtime 和项目契约文件。 — 产品 fork 应该保持薄。绝大多数 LuaAgent 行为应放在插件和一条很小的 Runtime Bridge 里。

薄 fork，强插件

第一个架构决策是把产品归属和语言归属拆开。IDEA Community fork 负责品牌、内置插件、默认设置、项目模板、更新通道和分发包形态。LuaAgent 插件负责文件类型、语法、PSI、引用、检查、补全、结构视图、运行配置和运行时面板。

这个拆分很关键，因为维护 IDE 平台 fork 的成本很高。每一处产品级改动都要承受上游平台变化。插件可以更快演进，可以独立测试，也更容易遵守 IntelliJ Platform 的扩展点模型。

层级	负责	应避免
IDEA Community fork	品牌、默认插件、产品元数据、内置模板、分发包形态。	把 LuaAgent 语义直接写进平台代码。
LuaAgent 插件	语言模型、编辑器智能、检查、运行配置、工具窗口。	原始进程执行、密钥访问、绕过 IDE API 的文件系统修改。
Runtime Bridge	发给 Eva-CLI 的类型化请求、诊断、dry run、能力索引快照、测试结果。	从编辑器直接下发 shell 片段绕过策略。
Eva-CLI Runtime	策略、权限、Agent 执行、EventBus、Adapter、记忆、审计、回滚。	IDE UI 状态或只存在于编辑器里的假设。

语言能力从 PSI 开始

IntelliJ 的语言功能由平台通用服务和语言专属组件组合而成。对 LuaAgent 来说，最小语言面不只是 Lua 语法，还包括 Agent 声明、manifest 字段、capability 名称、Topic 名称、记忆作用域声明、tool schema 引用和运行时约束。

插件应该围绕稳定程序结构定义 LuaAgent 文件：lexer、parser、PSI 元素、必要时的 stub index、引用与 resolve、inspection、quick fix 和 completion contributor。JetBrains 的 Custom Language Support 文档给出的路径也正是这条线：parser 与 PSI 实现、lexer 定义、语法高亮、导航、补全、检查和重构钩子。

LuaAgent project model
  .eva/agent.yaml          -> Agent 身份、权限、runtime gates
  agents/*.lua             -> Agent 行为和 host API 调用
  capabilities/*.schema    -> tool 输入/输出契约
  topics/*.topic           -> EventBus topic 声明
  tests/*.scenario         -> dry-run 与 harness 场景

务实的第一版可以支持现有 Lua 文件加 LuaAgent sidecar 文件。随后 IDE 再增加跨文件解析能力：agent:emit("runtime.task.started") 能跳转到 Topic 声明，host.call("memory.query") 能跳转到 capability 契约，manifest 权限缺失会在运行时拒绝之前就显示警告。

Runtime Bridge 是安全边界

IDE 不应该成为 Agent 执行的权威。它应该向 Runtime 请求事实和受控动作：列出可用能力、校验 manifest、运行 dry-run 场景、请求诊断、启动受监督的 Agent 会话，或打开审计记录。Eva-CLI 仍然负责策略、权限、密钥、Adapter、EventBus 投递、记忆和回滚。

LuaAgent IDE 开发闭环图，展示从编辑和 PSI 分析，到运行时校验、受监督 dry run、审计结果和 quick fix 的流程。 — IDE 反馈闭环应该足够快，但运行时权威必须留在编辑器进程之外。

Bridge 可以刻意做小。本地 Eva-CLI 进程暴露带版本的协议，提供 runtime.capabilities.snapshot、agent.manifest.validate、agent.scenario.dryRun、event.topic.resolve 和 audit.trace.open 这类类型化方法。IDE 插件把响应转成编辑器诊断、gutter action、运行结果和导航目标。

第一个可用版本应该包含什么

MVP 应优先服务日常 Agent 设计工作，而不是追求平台新奇功能。第一版应该能打开 LuaAgent workspace，识别 Agent manifest，索引 capabilities 和 Topics，高亮不安全 host API 调用，补全 capability 与事件名，运行受监督 dry run，并把 Runtime 诊断内联展示出来。

创建带品牌的 IDEA Community 分发包，内置 LuaAgent 插件，并裁剪不必要的默认插件。
为 .eva/agent.yaml、Agent Lua 文件、Topic 声明、schema 文件和 scenario 测试实现文件类型与项目模型发现。
为 LuaAgent 层实现 lexer、parser、PSI、引用、补全、导航、结构视图、检查和 quick fix。
增加 Runtime Bridge，通过类型化请求调用 Eva-CLI，不能执行编辑器随意拼出的命令。
增加 manifest 校验、scenario dry run、受监督本地 Agent 会话和打开审计 trace 的运行配置。
用插件测试、fixture 项目、parser golden file 和 bridge contract test 固化行为。

让上游变动可承受

LuaAgent IDE 长期能否维护，取决于产品 fork 里需要携带多少改动。凡是能通过扩展点实现的能力，都不要改平台内部。品牌和分发变更要隔离。LuaAgent 插件才是主要产品面。Runtime Bridge 是契约，不是绕过架构边界的捷径。