用 AI 生成模块（不需要会 C++）

[🕒 预计 20 分钟] | 难度：入门

不会写 C++ 也能给自己的 LingBuilder 加模块。现在有三种方式，按推荐顺序：方式一（推荐）一键生成——在 IDE 里用一句中文描述需求，内置 AI 自动完成规范注入、生成、解析、导入和校验；方式二手动复制粘贴——把规范复制给 ChatGPT、Claude、Cursor 等任意 AI，把回复粘回 IDE；方式三 AI Bridge MCP——让 Claude Code、Codex CLI 等外部 AI 通过 MCP 工具端到端完成生成、校验、打包、安装。无论哪种方式，最后都按 F5 编译成真实 C++ 运行。

本文的界面文案与结果均来自 LingBuilder 桌面版实测。

1. 这套流程解决什么

你只需要做	LingBuilder 负责
复制规范、描述需求、粘贴回复	解析文件、校验清单、写入工作区
点几次按钮	导出 `.lbmod`、预览确认、安装并启用
在中文代码里调用新命令	把中文命令确定性生成 C++ 调用并编译运行

模块的 C++ 桥接代码由 AI 生成、随模块包分发，你不需要读它，但必须让它存在——IDE 不接受只有中文补全、没有 C++ 映射的模块。

2. 开始之前

LingBuilder 桌面版已打开一个项目（解决方案资源管理器里有项目节点）。
已安装 Visual Studio Build Tools / MSVC 工具链，否则 F5 无法编译。
手边有一个可粘贴文本的 AI 对话窗口。

3. 方式一（推荐）：一键生成

打开 模块生态 → AI 生成模块，顶部绿色区域就是 一键生成（内置 AI 直接生成并导入）。
选择通道：系统 AI（在 AI 助手面板登录后自动使用你选择的模型）或 自定义 API（在 AI 助手面板「自定义 API」中配置 Base URL 与 Key，DeepSeek 等供应商可用）。
在需求框用中文描述模块，例如：
做一个字符串工具模块：提供取文本长度和文本替换两个中文命令，参数与返回值用文本型和整数型，带中文使用文档和示例。
点击 生成并导入到 module-build。IDE 会自动完成：把《AI 模块开发规范》连同需求发给 AI → 按「清单 → 其余文件 → 缺失补全」多阶段生成 → 解析 → 导入到 .lingbuilder/module-build/<模块 ID> → 严格校验。生成期间按钮显示「正在生成模块……」，全程约 1~3 分钟，中途不要取消。
成功后状态行提示「已导入 …，“模块包制作”和“校验模块”路径已自动填好」，直接跳到本文 第三步：校验模块 继续。校验出问题时会出现「把校验问题发回 AI 修正并重试」按钮；解析失败时 AI 原始回复会自动填入下方手动模式文本框，可检查后手动导入。

NOTE

系统 AI 通道按模型计费点数扣费；生成请求会自动关闭上游思考过程并使用更大的输出预算（16384 tokens），保证完整模块不被截断。

4. 方式二（手动）：把开发规范复制给 AI

点击左侧活动栏的模块（层叠方块图标，悬停提示「文本与函数模块」）打开 模块生态 面板；也可以从解决方案资源管理器项目节点下的模块组点 配置项目所使用模块 进入同一个面板。
展开 AI 生成模块 中的 手动模式：复制规范给任意外部 AI 卡片（标记 复制粘贴降级；一键生成不可用时的备选方案）。
点击 复制 AI 开发规范，按钮提示变为「已复制，粘贴给 AI 即可」。需要人工阅读时点 打开规范文档。
把规范整段粘贴给 AI，再补一句中文需求，例如：
做一个纯命令文本工具模块 ai.text.tools，提供 文本_统计字符数、文本_反转、文本_是否包含 三个中文命令。

AI 会按契约逐个文件输出（见下一步的识别规则）。

5. 方式二继续：粘贴 AI 回复并导入

把 AI 的完整回复粘贴到 粘贴 AI 回复内容 文本框。

文本框下方出现 已识别 N 个文件 和文件名列表，例如：

text

lingbuilder.module.json、include/text_tools_bridge.h、src/text_tools_bridge.cpp、
README.md、examples/最小示例.lcpp

点击 导入到 module-build。校验通过时显示绿色结果框：
text
```
已导入 AI 文本工具（ai.text.tools）到 .lingbuilder/module-build/ai.text.tools，共 5 个文件。导入后校验通过。
下一步：在上方“模块包制作”点击导出 .lbmod，然后安装启用。
```
面板顶部状态行同时提示：AI 模块已导入到 .lingbuilder/module-build/ai.text.tools；“模块包制作”和“校验模块”路径已自动填好。

NOTE

导入目录固定为 .lingbuilder/module-build/<模块 ID>，只接受包内相对路径。清单、文档、示例和声明文件全部校验通过后才会写入；失败不会留下部分文件。若该目录已存在，结果框会额外提示「目标目录原本已存在，本次覆盖了同名文件；旧目录中多余的文件不会被删除。」——多余文件不会自动清理，改名或换 ID 重新导入更稳妥。

如果解析区出现“复制 AI 模块解析诊断”，说明 AI 回复中有重复文件、路径不安全或无法识别的文件；修正前导入按钮会保持禁用。文件标题允许使用 ./ 前缀，但不能出现只差大小写的重复路径。

6. 第三步：校验模块

模块生态 → 模块开发者中心 →「③ 校验模块」 的 模块目录 已自动填好，点 校验模块：

text

模块校验通过：manifest v2、命令绑定、文档与平台 target 均符合规范，可以导出 .lbmod。

校验覆盖 manifest v2 字段、中文命令与 bindings.commands 是否成对、随包中文文档是否存在、平台 target 是否可用。

“③ 校验模块”和“导出 .lbmod”使用同一套严格门禁：命令必须有 binding，文档和示例必须真实存在且非空，模块至少要有一项可用贡献；任一环节失败都不会生成可分发模块包。

7. 第四步：导出 `.lbmod`

展开 模块包制作，模块目录 已自动填好；导出路径 需要自己填写（导入不会填这一格）：
text
```
.lingbuilder/module-packages/ai.text.tools.lbmod
```
点击 导出 .lbmod，状态行显示「模块包已导出。」

WARNING

两个路径各有约束：模块目录必须位于 .lingbuilder/module-build 下，导出文件必须位于 .lingbuilder/module-packages 下，且都写工作区相对路径。填错时状态行会给出中文提示，不会写出工作区外的文件。

8. 第五步：预览安装并启用

展开 安装 .lbmod，把 .lbmod 文件拖进拖放区；也可以填写 工作区相对路径（.lingbuilder/module-packages/…）或 本机绝对路径（桌面版会自动把外部包复制进工作区再校验）。
点击 预览安装，状态行显示「模块包预览通过，等待确认安装。」，并弹出 模块安装预览：
字段示例值
模块 AI 文本工具 (ai.text.tools)
版本 1.0.0
文件 5 个文件，4.7 KB
SHA256 3760d1ee…bc936fc6
升级否
安全检查检查通过，可以安装。
保持勾选 安装完成后加入当前项目，点击 确认安装。
安装结果出现在 本地模块 列表：
text
```
ai.text.tools · 1.0.0 · 能力 3 项
```
模块包路径输入框会自动清空。

字段	示例值
模块	AI 文本工具 (ai.text.tools)
版本	1.0.0
文件	5 个文件，4.7 KB
SHA256	3760d1ee…bc936fc6
升级	否
安全检查	检查通过，可以安装。

NOTE

安装永远经过预览确认，不会静默写入。点击模块行的接口可打开「模块公开信息」，其中「命令接口」列出 3 条中文命令及签名、「C++ 依赖」列出随包的 include/、src/ 文件、「文档」列出随模块分发的中文说明（如「使用说明 README.md」）。

9. 第六步：在中文代码里调用并 F5

模块启用后即可在中文代码里直接调用这些命令；不在任何启用模块里的中文命令会在生成 C++ 前被阻断诊断拦下，不会静默生成错误行为。在窗口事件里写：

text

类 MainWindow
    事件 创建完毕()
        调试输出(文本_统计字符数("你好世界"))
        调试输出(文本_反转("你好世界"))
        调试输出(文本_是否包含("你好世界", "世界"))
    结束
结束类

按 F5（工具栏「运行 F5 (编译并运行当前项目，快捷键是 F5)」）构建运行。实测结果：

构建目录 .lingbuilder-build/<项目>/Win32/Debug/modules/ai.text.tools/ 下出现模块的 include/text_tools_bridge.h 与 src/text_tools_bridge.cpp，与项目 main.cpp 一起编译。
生成 LingBuilderPreview.exe 并启动，错误列表 (0)，输出面板：
text
```
[调试输出] 4
[调试输出] 界世好你
[调试输出] 真
```

这三行分别对应三个中文命令的真实 C++ 实现，说明模块不是界面里的假条目，而是编进了可执行文件。

10. 导入被拒绝时的常见原因

红色结果框说明导入未成功，不会写入任何模块文件。按诊断逐条处理，通常做法是点击“复制错误详情”或“复制 AI 模块解析诊断”，把完整诊断原文回给 AI，让它重新输出对应文件：

诊断	含义	处理
未识别到任何文件。请确认 AI 回复中每个文件都使用“### 文件：相对路径”标题加代码块格式。	粘贴内容不符合输出契约	让 AI 按该格式重出；粘贴完整回复，不要只粘清单
文件 X 只有标题（…），没有找到代码块内容。	标题后缺少代码块（常被 AI 省略）	要求 AI 补全该文件正文
未识别到根目录 lingbuilder.module.json，无法确定模块 ID。	缺主清单	要求 AI 输出根目录 `lingbuilder.module.json`
命令 X 缺少 bindings.commands 映射：编辑器能补全，但无法生成 C++ 调用；请让 AI 补上同名 binding。	只有中文补全、没有 C++ 映射	让 AI 补 `bindings.commands`，不是补 `contributes.commands`
忽略无法识别的文件路径：…	出现绝对路径、盘符或 `..`	只允许包内相对路径

TIP

识别规则：### 文件：相对路径（也兼容 **文件：路径**、文件：路径 等常见写法）后面紧跟一个三反引号代码块，块内正文即为该文件内容。文件类型限制为源码与文本类扩展名（.json、.md、.h、.cpp、.lcpp、.ini 等）。

11. 边界与限制

单次导入上限：最多 200 个文件、单文件 1 MB、总量 10 MB。超出让 AI 拆分。
平台：当前生成与编译闭环面向 Windows + MSVC，纯源码模块声明 windows-msvc-win32 / windows-msvc-x64 target 即可。
文档强制：模块必须随包提供真实、非空、UTF-8 的中文文档，缺文档会被校验拦下。
设计器控件：涉及可视化控件的模块复杂度高得多，建议先做纯命令模块，确有需要再让 AI 贡献控件。
AI 只产出文本：写文件、装模块、编译都由本地确定性流程执行，可预览、可撤销、可复查。
AI Bridge MCP 路线：已配置 AI Bridge 连接中心的 Claude Code / Codex 等外部 AI 可以直接调用 lingbuilder.module.scaffold / writeFiles / validate / pack / installPreview / install 六个受控工具，端到端完成生成、校验、打包与安装；写操作受权限模式与审计日志约束，安装必须先预览并显式确认。

下一步

安装与管理模块：模块的启用、禁用、更新与卸载。
模块市场：从官方与市场源浏览安装模块。
依赖冲突检测：多模块版本与接口冲突排查。
窗口设计器：把命令绑定到控件事件上。

用 AI 生成模块（不需要会 C++） ​

1. 这套流程解决什么 ​

2. 开始之前 ​

3. 方式一（推荐）：一键生成 ​

4. 方式二（手动）：把开发规范复制给 AI ​

5. 方式二继续：粘贴 AI 回复并导入 ​

6. 第三步：校验模块 ​

7. 第四步：导出 .lbmod ​

8. 第五步：预览安装并启用 ​

9. 第六步：在中文代码里调用并 F5 ​

10. 导入被拒绝时的常见原因 ​

11. 边界与限制 ​

下一步 ​

用 AI 生成模块（不需要会 C++）

1. 这套流程解决什么

2. 开始之前

3. 方式一（推荐）：一键生成

4. 方式二（手动）：把开发规范复制给 AI

5. 方式二继续：粘贴 AI 回复并导入

6. 第三步：校验模块

7. 第四步：导出 `.lbmod`

8. 第五步：预览安装并启用

9. 第六步：在中文代码里调用并 F5

10. 导入被拒绝时的常见原因

11. 边界与限制

下一步