Title: 🤖 AI 编程 Canonical: https://microi.net/doc/v8-engine/ai-apiengine.html Page-Modified: 2026-10-25T20:05:03.000Z Source: published HTML document body; page revision is not a capability verification date. # 🤖 AI 编程 在线 + 本地双模式 AI 编程，让 AI 充分了解你的 V8 API 与数据库结构 平台仓库：GitHub (https://github.com/itdos/microi.net) / Gitee (https://gitee.com/ITdos/microi.net) NUGET 官方快照数据NuGet 官方包下载统计统计覆盖 ITdos 名下公开包，采集计划为每 3 小时一次，请结合下方采集时间查看。页面初始显示构建快照，联网成功后更新为最近成功快照。1385万+累计下载13,851,606官网构建快照采集于 2026/10/27 GMT+8 00:00 (https://www.nuget.org/profiles/ITdos) 48 个公开包 · 本次官网构建时读取的快照下载量包含重复还原与 CI，不等于独立用户、付费客户或市场排名；NuGet 官方各索引异步更新，数值可能短时不同。 在线 AI 默认不需要向量数据库 平台已内置“大模型关键词扩展 + 权限感知 Schema/Skill 搜索 + 准确字段回读”。未开启 mic_ai.EnableVectorDatabase 时，不安装 Ollama、nomic-embed-text 和 Qdrant 也可使用 NL2SQL、NL2V8 与在线 AI 数据分析；默认模式部署更轻、启动更快、Schema 更新更及时。只有确有高度模糊语义召回需求时，才建议把向量数据库作为增强通道启用。 ## 📌 推荐提示词 吾码插件和 CLI 会为支持的 AI 宿主生成默认读取规则，让用户直接描述需求也能进入完整交付流程。但安装 CLI、连通 MCP，不等于宿主已经加载全部 Skills，更不能保证任意模型 100% 遵循。正式开发推荐使用下面的明确读取版提示词，保留自动识别，同时让读取结果可核对。 AI开发推荐提示词 请使用 MCP【连接名】，完整开发【需求描述】，需求文档为【路径，可选】。 开工前完整读取 microi.skills/workspace-conventions/SKILL.md、microi.skills/microi-system-delivery/SKILL.md 及其必读参考 microi.skills/microi-system-delivery/references/progressive-01-标准工作流.md，逐项执行 Skills 默认交付要求 1–10：原 1–8 项、第 9 项“基于界面引擎的业务统计、老板经营和领导管理报表”、第 10 项“先创建完整菜单骨架，再逐项验收并切换真实功能”，并按任务读取相关 Skills。 先报告实际读取的文件和 1–10 项交付计划；文件缺失时先完成吾码 AI 工作区初始化，不得凭摘要声称已读。收尾逐项提供实现位置、验收证据和未完成项。 允许在指定开发租户创建/更新需求内资源和验收数据，并完成业务与截图验收。 将连接名和需求替换为实际内容即可；当前项目已绑定连接或仅有一个已登录连接时，连 MCP 名称也可以省略，例如“帮我开发一个进销存系统，需求见附件”。验收地址、账号可沿用已配置连接，也可另行提供。只读分析和局部修改会按实际范围执行，默认路由不会自动扩张为整套系统重建。 以上提示词覆盖以下 1–10 项：1–8 对应原交付清单，9、10 分别对应报表和菜单先行要求。完整正文保留在完整系统开发 Skill (https://github.com/itdos/microi.net/blob/master/microi.skills/microi-system-delivery/SKILL.md)链接的必读交付清单与增补要求 (https://github.com/itdos/microi.net/blob/master/microi.skills/microi-system-delivery/references/progressive-01-%E6%A0%87%E5%87%86%E5%B7%A5%E4%BD%9C%E6%B5%81.md)中： 条目 | Skills 默认执行的要求 | 1 | 深度分析需求，在需求文件同目录持续维护详细 Markdown 文档 | 2 | 盘点、复用、幂等建模；补齐业务资源、索引、关系、账号和每张业务表约 100 条以上验收数据 | 3 | 自主推进；Schema → Manifest → plan → dryRun → 授权生成 → validate | 4 | 表单 80%、子表 75%/70% 并逐级递减；数据日志/评论/版本、业务域菜单、看板及合理栅格 | 5 | 完整 Key/中文 Label 数据源，禁止空下拉；状态/分类模板与跨端回显一致 | 6 | 折叠分组默认展开；大表/多子表合理使用表单 Tabs，类别/状态使用模块 PageTabs | 7 | 每个模块的标题、副标题和动态业务指标；列宽、角标、复合列去重与移动卡片动态区域 | 8 | 持续真实业务与截图验收，修复报错，并清理本次 AI 创建的临时浏览器和进程 | 9 | 基于界面引擎交付业务统计、老板经营和领导管理报表，具备真实数据、明确口径、筛选、权限和对账验收 | 10 | 需求分析后先创建完整菜单骨架；未完成的叶菜单展示共享开发中页面，逐项验收后切换为真实功能 | 前端“开发工具连接”弹窗在“连接 AI 工具”右侧提供“AI开发推荐提示词”Tab，可查看并一键复制同一份提示词。完成连接后，将提示词中的连接名、需求和文档路径替换为实际内容再发给 AI。 使用前通过吾码插件或 microi ai init --workspace "<工作区绝对路径>" --json 初始化/更新工作区，并用 microi doctor 检查连接和规则。5.9.4 及以前单独的 microi mcp init 只配置连接；本次 5.9.6 起会联动生成 Skills 和宿主规则。用户自定义或已跟踪的入口仍按保护规则保留，需要核对实际文件及版本，不能静默覆盖。宿主未读取规则、不能访问本地文件或模型忽略指令时，需要根据实际限制恢复，明确写出 Skill 名称也不是 100% 执行保证。 AI 开工说明应列出实际读取的基础规范、总控、完整清单和本次专项 Skills，并将 1–10 项映射到交付计划。收尾逐项提供实现与验收证据，不能把这张摘要表当成完整规范。只读分析和局部修改仍按实际范围执行；生产数据和客户部署服从明确授权范围。 ### 先看菜单，再逐步交付 需求分析和已有资源盘点完成后，先显示业务域、功能及报表的完整菜单树。菜单骨架使用独立的 Manifest 预演和生成，不提前绑定尚不存在的业务表或页面。面向用户的新叶菜单使用各自独立的菜单地址，绑定吾码框架共享页面 ComponentPath=/ai-engine/developing、OpenType=Component、IsMicroiService=0。页面自动显示当前菜单名称，填满内容区，并提供持续动画和减少动态效果选项；不显示虚构的开发百分比。隐藏子表等授权载体继续保留原本的绑定方式。 每项功能先对候选真实页面预验收，再保留同一菜单 Id、地址、层级、排序和权限，切换到真实组件、界面引擎或微服务路由，刷新菜单与旧页面缓存后，从原入口完成最终验收。切换失败时恢复该菜单此前记录的正确绑定或开发中页面，并列为未完成。开发中页面只是过程提示，不能当作交付成果。已有正常功能不回退为占位页；目标框架尚未包含该组件时，应先完成前端升级或说明版本限制，不能创建打不开的菜单。 --- ## 🎬 视频演示：AI本地编程环境搭建 快速在本地搭建AI编程环境 - 录制: Microi吾码-AI本地编程环境搭建 - 日期: 2026-06-08 05:50:29 - 录制文件：https://meeting.tencent.com/crm/lvDYAP1D09 (https://meeting.tencent.com/crm/lvDYAP1D09) --- ## 🎬 视频演示：AI快速搭建进销存系统 利用 AI + Microi吾码低代码平台，在约 20 分钟内从零搭建一套完整的进销存系统（含建表、菜单、接口引擎、表单事件）。 - 录制: Microi吾码-AI快速搭建进销存系统 - 日期: 2026-04-20 03:42:04 - 录制文件：https://meeting.tencent.com/crm/NLLyRZ4n83 (https://meeting.tencent.com/crm/NLLyRZ4n83) --- ## 🎯 为什么说 Microi吾码做到了真正的 AI + 低代码？ Microi吾码把 AI 生成业务模型、编写业务逻辑、调用平台能力和交付验收放在同一条开发链路中： V8 接口引擎 = 标准 JavaScript 后端代码，AI 最擅长的就是写代码。 - 接口引擎使用 JavaScript，AI 可以生成业务逻辑，再通过参数校验、远端回读和测试确认正确性 - 将数据库表结构、字段含义、菜单关系一键喂给 AI，AI 就能精准理解你的业务数据 - 在线 AI 编程：浏览器中用 DeepSeek / ChatGPT / Kimi 等工具写代码，复制粘贴到平台 - 本地 AI 编程：VS Code 插件或 @microi.net/cli 自动注入 Skills、Schema 与 MCP；可选择编辑器内调试，也可由 Codex/Claude/Trae 在纯终端完成交付 - 从 V8 代码中调用 AI 大模型：在接口引擎里直接请求 DeepSeek 等接口，实现 ReAct 模式 如果要复用吾码已经封装的模型路由、会话、License、租户身份与中转计量，不要在每个页面重新保存供应商密钥。前端和后端 V8 均可直接使用第一等 V8.AI.Chat/ChatStream/NL2SQL，外部 Agent 使用专用 microi_chat MCP Tool；身份、租户、Endpoint 和 ApiKey 由可信宿主控制。GET/POST、Token 鉴权、SSE 打字机示例与服务器 License/中转 ApiKey 的区别见 AI 引擎与 Microi.AI 中转站 (https://microi.net/doc/system-engine/ai-engine.html)。 博主某 MES 项目：500+ 张表，大量接口引擎均由 AI 生成。 ### 相比传统定制代码 + AI，为什么更省 Token、更快？ 质量和准确性始终优先于节省 token。吾码通过短入口、按任务读取 Skills、精确查询当前租户结构和减少重复传输降低开销；完整系统仍执行原八项及菜单/报表增补，小修改仍分析目标与关联依赖、检查当前版本并真实回读。信息不足时扩大读取，不以摘要、缓存或硬预算替代必要事实。 CLI 与 VS Code 共用生成入口，详细知识以责任 Skills 为准；生成块升级保留块外用户规则，用户修改过的块和未知历史内容不会被自动覆盖。定制前端、游戏、算法、硬件按实际需要复用 SDK、脚手架和协议能力，并保留对应真实验收。工具参数及完整性、Manifest 引用和计量方法见 MCP Server (https://microi.net/doc/v8-engine/mcp-server.html#%E7%B2%BE%E7%A1%AE%E8%AF%BB%E5%8F%96%E4%B8%8E%E5%AE%8C%E6%95%B4%E6%80%A7)。外部 Codex/IDE 的模型历史与供应商缓存仍由宿主管理。 AI 能不能提高效率，不只取决于模型本身，更取决于模型要生成多少代码、每轮需要理解多少上下文，以及生成结果能否直接进入可验证的运行环境。 对比维度 | 传统定制代码 + AI | Microi吾码 + AI | 交付起点 | 从技术选型、项目骨架和通用基础设施开始 | 表单、模块、接口、工作流、权限、SaaS、报表、消息等 30+ 引擎开箱即用 | AI 生成范围 | 数据访问、权限、CRUD、流程、页面、缓存和部署胶水代码都可能重复生成 | AI 主要生成业务模型、Manifest、V8 业务逻辑和必要的前端扩展 | 上下文与 Token | 反复携带框架说明、数据库 DDL、接口规范和大量历史代码 | Skills、V8 类型提示、实时 Schema、业务蓝图和 MCP 按需提供结构化事实 | 开发速度 | 生成后还要补基础能力、编译、联调和搭建部署链路 | 规划、dry-run、确认写入、远程执行、调试、回读和测试形成闭环 | 稳定性 | 每个项目拥有不同的通用代码与集成实现，回归面随代码量扩大 | AI 只修改较小的业务增量，成熟引擎继续承担权限、事务、租户和分布式边界 | 持续维护 | 新需求需要重新理解并修改整套定制工程 | 元数据、业务逻辑与平台底座边界清晰，可持续升级并保留项目扩展 | 复用收益与验证范围 30+ 引擎承担通用能力，AI 聚焦业务增量；V8 业务逻辑保存到服务器后生效，无需为每次业务脚本修改重新编译平台。 复用可以减少生成与联调通用代码的工作。本站历史材料中的“10 倍+”属于特定场景的收益表述，不能视为统一验收结论。模型 Token、费用、交付时间与工具传输字节必须分别测量；下面给出已可重复运行的载荷基准及端到端评测方法。 实际结果取决于需求、模型、上下文、熟练度、定制深度和验收范围。算法、特殊硬件协议和平台尚未覆盖的能力仍需专用工程扩展；未公开完整实验记录时，不据此推导普遍工期或费用倍数。 ### 可复现的 MCP 载荷基准 2026-10-25 对公开源码中的确定性夹具执行复测，比较 Manifest 全文传输与引用传输。 两条路径均保留 4 次工具调用、2 次验收调用，资源动作与验收契约哈希一致，错误数为 0。 测试使用内存客户端，不连接生产服务；这验证的是请求和响应序列化后的 UTF-8 字节量。 场景 | 全文总字节 | 引用总字节 | 引用相对全文 | 适用选择 | 完整系统建模 | 27,432 | 15,923 | 减少 41.95% | 引用减少重复传输 | 局部接口修改 | 2,343 | 3,248 | 增加 38.63% | 小载荷直接传全文 | 微服务菜单配置 | 3,174 | 3,822 | 增加 20.42% | 小载荷直接传全文 | 复测入口：基准源码（Gitee (https://gitee.com/ITdos/microi.net/blob/7bdaf49a691dde8ff43313176adc9dc3f993888d/microi.mcp/src/manifest-efficiency-benchmark.ts) / GitHub (https://github.com/itdos/microi.net/blob/f9fc6145c726dcceb925efdb955b6dc128d481e6/microi.mcp/src/manifest-efficiency-benchmark.ts)）、 验收测试（Gitee (https://gitee.com/ITdos/microi.net/blob/7bdaf49a691dde8ff43313176adc9dc3f993888d/microi.mcp/src/manifest-efficiency-benchmark.test.ts) / GitHub (https://github.com/itdos/microi.net/blob/f9fc6145c726dcceb925efdb955b6dc128d481e6/microi.mcp/src/manifest-efficiency-benchmark.test.ts)）、 固定场景（Gitee (https://gitee.com/ITdos/microi.net/blob/7bdaf49a691dde8ff43313176adc9dc3f993888d/microi.mcp/src/manifest-context-fixtures.ts) / GitHub (https://github.com/itdos/microi.net/blob/f9fc6145c726dcceb925efdb955b6dc128d481e6/microi.mcp/src/manifest-context-fixtures.ts)）。两组固定提交中的这三个文件已逐一核对，Git blob 内容相同；仓库整体历史不据此视为相同。 复测提交为 7bdaf49a691dde8ff43313176adc9dc3f993888d，Node.js 为 v20.20.1。 该次基准源码 SHA-256 为 5c89f409206f7dfe027d368a1ca79f978ad19b44ebbf4fcaf9be4fc76f6a57f8； 后续版本可能改变字节数，复测时记录实际提交号、源码哈希及 Node.js 版本。 在源码仓库的 microi.mcp 目录安装锁定依赖后运行： bash ``` npm ci node --max-old-space-size=512 --import tsx src/manifest-efficiency-benchmark.ts node --max-old-space-size=512 --import tsx --test --test-concurrency=1 src/manifest-efficiency-benchmark.test.ts ``` 该结果不是模型 Token、订阅费用、真实数据库性能或端到端开发速度的测量。 小任务的引用封装有额外成本，因此选择策略必须按实际载荷和质量结果决定。 ### 如何验证端到端 AI 开发收益 选取完整业务系统、既有业务局部修改、定制微服务三类任务，在相同模型、推理配置、 需求、初始数据与验收条件下进行成对测试。每类至少重复 3 次，保留全部失败和修复过程， 报告中位数、范围及成功率，不只选最好一次。 记录项 | 需要保存的证据 | 环境与输入 | 模型及推理配置、代码提交号、平台/CLI/应用包版本、需求与数据哈希、缓存条件 | Token 与费用 | 供应商返回的输入、缓存输入、输出及可用推理用量；包含子代理和重试，缺失记为未知 | 时间与交付 | 从需求输入到验收通过的总时长、人工介入、工具轮数、修改文件和生成代码量 | 正确性 | 数据关系、角色/租户权限、参数校验、事务回滚、幂等、异常与存量兼容断言 | 用户体验 | 登录、主要业务闭环、桌面/移动、明暗主题、网络错误和截图复核 | 结论边界 | 通过/失败任务数、未覆盖功能、外部依赖、数据清理与复测命令 | 同一模型下的 Token 总量之比和同口径验收时长之比分别计算，不能用字符数、传输字节、 功能数量或一个演示视频替代。该方法供第三方复测，未执行的实验不填写预期成绩。 ### 可复现的结构化任务实测 源码目录 microi.benchmarks/ai-quality/ 提供独立协议、固定合成任务、运行器和测试，使用 Node.js 20.20 或更新版本，无第三方依赖。运行 node microi.benchmarks/ai-quality/run.mjs plan MODEL_ID 先检查计划，node --test microi.benchmarks/ai-quality/run.test.mjs 验证工具。 当前协议 1.1.0 在相同模型下，比较无平台上下文与固定平台上下文两种条件，覆盖查询计划、身份边界、事务计划三个 JSON 任务。单轮最多 6 次、每次请求最多 1024 输出 token、120 秒、零重试；真实调用只走官方中转入口，平台 ApiKey 从标准输入传入。MiniMax-M3 两组均固定 reasoning_split:true 与 thinking:{type:'disabled'}；其它模型不照搬专属参数。模型支持与账户授权需先核对；供应商是否遵守上限以实际回执为准，取消不撤销已经发生的用量。 产物记录任务/工具源码哈希、实际返回模型、输入输出哈希、完成态、首文本/总耗时、供应商 usage、逐项正确性和全部失败。用量缺失记未知，缓存/推理用量只抄录供应商返回值，未核验价格时不计算费用。模拟服务只用于运行器回归测试，必须标为 harness-test，不能充当 real-provider 成绩。 2026-10-26 首次按协议 1.0.0 执行 6 次真实调用，0 次通过：5 次流未完整、1 次截断，6 次均未通过 JSON 校验；供应商报告合计 4,693 Token。随后诊断发现默认思考文本与上游结束帧兼容问题。原失败记录保留在公开运行方法与脱敏结果 (https://gitee.com/ITdos/microi.net/tree/master/microi.benchmarks/ai-quality)（GitHub (https://github.com/itdos/microi.net/tree/master/microi.benchmarks/ai-quality)），没有改写旧成绩。 在两个官方 API 均观察到 8.7.1 后，按协议 1.1.0 固定参数执行新一轮 6 次：六次流和 JSON 均完整，计划验收共 4/6；无上下文组 1/3、固定平台上下文组 3/3。供应商输入 1,750、输出 329、总计 2,079 Token，与六条新增账本和累计用量增量一致。两项未通过分别涉及无上下文组的身份/租户边界和提交计划；未执行模型计划，不是实际业务越权或事务事故。固定上下文组总用量为 1,089，无上下文组为 990，不能据此声称节省 Token。该批改变了思考设置，新旧批次不能用于推导效率提升倍数；单轮三任务也不代表稳定成功率或完整系统交付率。 这组探索任务不建库、不执行模型代码、不验收界面，不能推出端到端开发效率、稳定成功率或外部总评分。完整系统评测仍须按上一节执行真实业务与权限验收；强结论需提前固定重复次数、缓存条件与失败处理规则，保留全部记录。 ### 流式完成态与内容留存边界 本轮源码为普通聊天和 NL2V8 增加兼容的取消入口：HTTP 断连信号联结模型超时后传入 SDK，关键词扩词也接收取消；旧二参数 API 保留。Core、AI 和 API 需配套交付，旧 AI 模块的兼容回退不能视为已具备此能力。数据库和可选向量查询仍按原有超时执行，查询前后检查取消，不能承诺这些查询即时停止。 DataAppend.CompletionStatus 返回 Completed、Cancelled、TimedOut、Truncated、Filtered、Incomplete 或 Failed。仅正常结束且非空输出返回 Code=1；部分文本保留供用户核对。SSE 的 done 表示传输结束，不能当作业务成功。普通聊天空流不再隐式追加第二次模型请求；取消不能回滚已执行工具或撤销供应商费用。 新增中转计量记录只保存用量与关联信息，兼容字段 PromptPreview/Question/Answer 写入空字符串，用量接口不返回历史正文预览。原有会话历史与历史账本不会自动删除。普通聊天/NL2V8 诊断与异常响应已按各自源码路径去除正文；其它分支、历史记录及供应商留存仍需分别核查。流式 UsageSource=Provider 仅表示供应商实际用量，缺失记为 Unavailable；旧计量估算另标 RelayUsageSource=Estimated。上述为源码行为，正式可用需对应版本发布与运行读回，不能用本地测试替代上线证明。 这种模式带来的不只是速度： - 更省 Token：实时 Schema 和 Skills 代替重复粘贴文档，AI 聚焦当前业务差异； - 更快交付：常见企业能力直接复用，保存或显式推送后即可远程执行和回读； - 更稳定、更成熟：平台自 2014 年持续演进，通用能力不由每个项目临时生成； - 开箱即用：权限、多租户、表单、工作流、报表、缓存、消息、部署与多端能力已经形成产品； - 仍可深度扩展：低代码覆盖通用部分，V8、Vue、C#、HTTP 和微服务承接真正需要定制的部分。 --- ## 💻 本地 AI 编程（VS Code 插件 + microi.net/cli） Microi吾码提供同一套 AI 开发能力的两个入口：VS Code 插件负责资源树、Diff、远程执行和逐行调试；@microi.net/cli 负责无需 IDE 的连接、登录、AI/MCP 初始化、代码拉取、差异检查和显式推送。两者共用工作区配置、Token、Skills、MCP 和同步基线，完整功能与命令以 AI 开发工具文档 (https://microi.net/doc/v8-engine/microi-agent.html) 为准。 ### 工作原理 text ``` 安装 VS Code 插件 npm install -g @microi.net/cli ↓ ↓ 可视化添加服务器并登录 microi init --pull └──────────────┬───────────────────────┘ ↓ AI 指令 + Skills + V8 typings + MCP ↓ 实时 Schema / 业务蓝图 / V8 源码 / 在线应用上下文 ↓ AI 规划 → dry-run → 确认写入 → 远端回读 → 测试 ↓ VS Code 可视化调试，或 CLI/Codex 纯终端交付 ``` 初始化只建立知识与工具连接，不等于无条件修改远端。普通文件保存只标记本地变化；必须执行插件“推送当前文件”或 CLI microi push ，并通过冲突预检后才会写入数据库。 ### 安装一种入口 - VS Code：在扩展市场搜索 Microi吾码，适合可视化编辑、Diff 与调试。 - 纯命令行：执行 npm install -g @microi.net/cli，再进入工作区运行 microi init --pull。 首次生成 MCP 配置后应新开 AI 对话，已打开的 Codex/Claude/Trae 会话通常不会热加载新工具。 ### 初始化、拉取与知识注入 插件用户执行 Microi: 初始化AI配置，需要本地源码时再点击服务器节点的“拉取此服务器代码”。CLI 用户执行： bash ``` microi init --pull ``` 两种入口都会完成以下工作： 步骤 | 内容 | ① 拉取接口引擎 | 所有 ApiEngineKey.js 保存到本地目录 | ② 拉取 V8 事件 | 所有表单 V8 事件 .js 保存到本地目录 | ③ 拉取数据库结构 | 表名、字段名、类型、说明、菜单树一并拉取 | ④ 自动生成知识库 | AGENTS.md / CLAUDE.md / Copilot/Cursor 指令 / microi.skills/ / V8 typings | ⑤ 配置 MCP | 幂等写入 VS Code、Cursor、Trae、Claude Code 与 Codex 配置，保留其它 MCP | 知识库生成后，你在 VS Code 中打开任意 .js 文件，AI 助手已经了解： - V8 引擎完整 API（不需要你手动告诉 AI 怎么用 V8.FormEngine.GetTableData） - 你的数据库表结构（AI 知道你的表叫什么，字段叫什么，业务含义是什么） - _Where 条件用法（AI 能自动写出正确的查询条件） ### 写代码 → 执行 → 调试，全闭环 操作 | 方式 | AI 辅助写代码 | Copilot 自动补全，或在 Copilot Chat / Claude Code 输入需求 | 远程执行 | 右键 → Microi: 远程执行当前接口引擎（弹出参数输入框） | 逐行调试 | 右键 → Microi: 远程逐行调试，支持断点 / Step Over / 变量观察 | 推送保存 | 保存只更新本地状态；显式执行插件推送或 microi push，并先检查冲突 | 所有右下角的信息、警告和错误通知都会同步保存在 VS Code 的【输出 → Microi 吾码】中，包括微服务构建/推送、代码拉取/同步、登录和远程执行结果。日志时间使用运行 VS Code 电脑的本地时区；带按钮的通知还会记录用户最终选择，通知消失后仍可继续追查。后台身份维护使用静默状态探测，服务器临时不可达不会反复产生无内容的 GetStatus Error:；用户主动操作失败时则会保留错误码、地址和端口等诊断明细。 [V8 引擎本地 AI 编程连接配置: https://file.microi.net/upload/img/V8%E5%BC%95%E6%93%8E%E6%9C%AC%E5%9C%B0AI%E7%BC%96%E7%A8%8B%E8%BF%9E%E6%8E%A5%E9%85%8D%E7%BD%AE.png] [V8 引擎本地 AI 编程运行调试: https://file.microi.net/upload/img/V8%E5%BC%95%E6%93%8E%E6%9C%AC%E5%9C%B0AI%E7%BC%96%E7%A8%8B%E8%BF%90%E8%A1%8C%E8%B0%83%E8%AF%95.png] ### 单独更新 AI 知识库 数据库结构发生变化后，无需重新拉取全部代码，单独执行： ``` Microi: 拉取数据库结构到AI知识库 ``` CLI 用户可执行 microi pull --scope schema。两种方式都会更新当前 OsClient 的结构快照，让 AI 感知最新表结构。 ### 效率对比 开发模式 | 准备上下文 | 写代码 | 执行调试 | 推送部署 | 传统手写 | 无 | 手写 | 打开浏览器平台 | 浏览器平台 | 在线 AI 编程 | 手动上传文档 + db.json | AI + 复制粘贴 | 浏览器平台 | 浏览器平台 | VS Code 插件 | 自动注入 Skills/MCP，按需拉取 | AI + 可视化编辑器 | 执行与逐行调试 | 显式推送并检查冲突 | microi.net/cli | microi init --pull | Codex/Claude/Trae/终端 | AI 通过 MCP 执行并回读 | microi push 显式推送 | --- ## 🧩 AI Skills 集成指南 Skills 是一系列结构化指令文件（SKILL.md），告诉 AI 工具在特定场景下应该如何编写代码。每个 Skill 覆盖一个开发场景，包含完整的 API 用法、代码模板和安全规范。 ### 什么是 Microi Skills Microi Skills 是一组 AI 编程最佳实践文件，内置于平台源码中，让 GitHub Copilot、Cursor、Claude Code 等 AI 工具在编写 Microi 平台代码时，自动遵循正确的 API 用法和安全规范。 - 平台源码：GitHub (https://github.com/itdos/microi.net) / Gitee (https://gitee.com/ITdos/microi.net) - Skills 目录：GitHub (https://github.com/itdos/microi.net/tree/master/microi.skills) / Gitee (https://gitee.com/ITdos/microi.net/tree/master/microi.skills) 没有 Skills 时： AI 可能写出不规范的代码（拼接 SQL、缺少权限校验、参数未验证等）。 有 Skills 时： AI 自动参考 Skill 文件，生成符合平台最佳实践的代码（参数化查询、权限校验、规范的返回格式等）。 Skills 不是“可选提示” 凡是平台新增了授权、租户隔离、上传配额、私有文件、Token 续签、SSRF/CORS 或分布式执行规则，都必须同步写入官方文档、相关 Skill、VS Code 类型/知识库和平台 AI 内嵌资源。否则平台用户和 AI 都无法正确使用这些能力。发布前必须校验源码 Skills、插件 dist、VSIX、空工作区初始化产物和 AI 内嵌镜像的一致性。 ### 平台内置 AI 的 Skill 镜像 后端 Microi.AI 会把官方仓库中的完整 Skills 清单作为嵌入资源，供当前 NL2V8EngineService 建立检索知识库，覆盖 V8、前端事件、FormEngine HTTP、文件/租户安全、系统引擎、页面/打印、UniApp、MCP 交付与测试验收；普通 Chat/ChatStream 当前不会自动注入这套完整 corpus。嵌入资源必须从 microi.skills/*/SKILL.md 机械同步，禁止长期维护另一份手工简化版；新增、删除或修改 Skill 时，源码目录、嵌入资源、项目资源清单和向量文档清单必须一起校验。公共镜像不得包含客户名称、真实 OsClient、客户域名、项目路径或定制业务枚举。 知识库 collection 名包含当前嵌入文档的 SHA-256 版本片段。新旧服务节点滚动发布时分别使用自己的版本化 collection，通过确定性 point id 幂等写入；初始化不会删除其它节点仍在使用的旧 collection。旧版本 collection 应在旧节点全部退出后由运维按保留策略清理，而不是在应用启动时抢占式删除。 ### 完整 Skills 目录 当前官方 Skills 持续随平台版本增加，以 microi.skills/README.md（GitHub (https://github.com/itdos/microi.net/blob/master/microi.skills/README.md) / Gitee (https://gitee.com/ITdos/microi.net/blob/master/microi.skills/README.md)）的实时清单为准，主要覆盖： - 后端 V8：CRUD、SQL、表单事件、缓存、HTTP、MongoDB、MQ/MQTT、工作流、接口配置、SaaS、图片、文件、导入导出、调试、安全和爬虫； - 前端 V8：字段/表单/列表事件、模板、菜单按钮、FormEngine HTTP； - 平台引擎：界面、打印、数据源、任务、搜索、报表、翻译、AI、应用商城、数据库结构、表单布局、左右树表和 Microi.UI； - AI 零代码交付：业务蓝图、MCP 系统交付、前端 SDK、UniApp、移动质量、数据源映射、Playwright、性能测试、生产只读巡检和工作区规范。 完整且随版本维护的清单以源码中的 microi.skills/README.md（GitHub (https://github.com/itdos/microi.net/blob/master/microi.skills/README.md) / Gitee (https://gitee.com/ITdos/microi.net/blob/master/microi.skills/README.md)）为准，不要在 AI 提示词里长期复制一份静态子集。 ### 快速集成 #### 第 1 步：使用 VS Code 插件或 CLI 生成 AI 指令（推荐） 任选一种入口：安装 Microi 吾码 VS Code 插件 (https://marketplace.visualstudio.com/items?itemName=Microi.v8-engine) 并执行“初始化AI配置”，或安装 @microi.net/cli 后执行 microi init --pull。两者都会安装完整 Skills，并为 Codex、GitHub Copilot、Claude Code、Cursor、Trae 等生成对应项目指令。升级时按清单与哈希做差异更新，保留用户自行修改的 Skill。 无法使用插件时，再从源码手工获取： bash ``` # 方式一：从 GitHub 克隆整个平台源码（含 Skills） git clone https://github.com/itdos/microi.net.git # 国内网络也可使用 Gitee 镜像：git clone https://gitee.com/ITdos/microi.net.git # 方式二：从 GitHub 仅克隆 Skills（通过 sparse-checkout） git clone --no-checkout https://github.com/itdos/microi.net.git # 国内网络也可使用 Gitee 镜像：git clone --no-checkout https://gitee.com/ITdos/microi.net.git cd microi.net git sparse-checkout set microi.skills git checkout master ``` 将 microi.skills 文件夹放到工作区根目录。不要把全部 Skill 全文拼接成一个超长提示词；AI 应按任务类型读取相关 SKILL.md。 #### 第 2 步：配置 AI 工具 --- GitHub Copilot（VS Code） 推荐方式 安装 Microi 吾码 VS Code 插件 (https://marketplace.visualstudio.com/items?itemName=Microi.v8-engine)，插件会自动生成 .github/copilot-instructions.md 并引用所有 Skills，无需手动配置。 手动配置方式： 在项目根目录 .github/copilot-instructions.md 末尾追加： markdown ``` ## V8 引擎编码最佳实践 编写 V8 引擎代码时，参考以下 Skill 文件： - microi.skills/v8-crud-api/SKILL.md — 增删改查 - microi.skills/v8-table-event/SKILL.md — 表单事件 - microi.skills/v8-sql-query/SKILL.md — SQL 查询 - microi.skills/v8-http-integration/SKILL.md — HTTP 集成 - microi.skills/v8-cache-pattern/SKILL.md — Redis 缓存 - microi.skills/v8-security/SKILL.md — 安全规范 - microi.skills/page-engine/SKILL.md — 界面引擎 - microi.skills/print-engine/SKILL.md — 打印引擎 ``` 也可以在对话中按需引用： ``` @workspace 参考 microi.skills/v8-crud-api/SKILL.md 帮我写一个用户管理的接口引擎 ``` --- Cursor 方式 A：在 .cursor/rules/ 目录中添加规则文件（推荐） 创建 .cursor/rules/microi-skills.mdc： yaml ``` --- description: Microi V8 引擎代码编写最佳实践 globs: ["microi-v8-engine/**/*.js"] --- 编写 V8 引擎代码时，参考以下 Skill 文件获取 API 用法和最佳实践： - @microi.skills/v8-crud-api/SKILL.md - @microi.skills/v8-table-event/SKILL.md - @microi.skills/v8-sql-query/SKILL.md - @microi.skills/v8-http-integration/SKILL.md - @microi.skills/v8-cache-pattern/SKILL.md - @microi.skills/v8-security/SKILL.md ``` 方式 B：在 .cursorrules 中只写路由说明 在规则中要求 AI 按任务类型读取对应 microi.skills/*/SKILL.md；不要把全部 Skills 拼接成一个巨型 .cursorrules，否则会增加上下文噪声，也无法可靠升级用户未修改的文件。 --- Claude Code 在项目根目录 CLAUDE.md 中追加： markdown ``` ## V8 引擎编码 Skills 编写 V8 引擎代码时，参阅以下文件： - microi.skills/v8-crud-api/SKILL.md - microi.skills/v8-table-event/SKILL.md - microi.skills/v8-sql-query/SKILL.md - microi.skills/v8-http-integration/SKILL.md - microi.skills/v8-cache-pattern/SKILL.md - microi.skills/v8-security/SKILL.md ``` ### 使用效果 配置 Skills 后，AI 代码生成质量会显著提升： ❌ 没有 Skills： ``` 你：帮我写一个分页查询用户列表的接口引擎 AI：（可能拼接 SQL、没有权限校验、返回格式不规范） ``` ✅ 有 Skills： ``` 你：帮我写一个分页查询用户列表的接口引擎 AI：（参考 v8-crud-api Skill） ✅ 使用 V8.FormEngine.GetTableData + _Where 参数化查询 ✅ 包含分页参数校验 ✅ 使用 V8.CurrentUser 做权限校验 ✅ 规范的 DosResult 返回格式 ``` ### 自定义 Skills 你可以为自己的业务场景创建自定义 Skill 文件： - 在 microi.skills/ 下创建新目录，如 my-business/ - 创建 SKILL.md 文件，参考现有 Skill 的格式编写 - 在 AI 配置文件中添加引用路径 SKILL.md 基本格式： markdown ``` # Skill 标题 你正在开发 Microi 吾码平台的 xxx 功能。 ## 核心规则 - 规则1 - 规则2 ## 代码模板 （代码示例） ## 常见错误 - ❌ 错误写法 - ✅ 正确写法 ``` --- ## 🔌 AI MCP 集成指南 MCP（Model Context Protocol）是 Anthropic 制定的开放协议，让 AI 工具以标准化方式连接外部系统。Microi MCP Server（GitHub (https://github.com/itdos/microi.net) / Gitee (https://gitee.com/ITdos/microi.net)）让 AI 工具直接连接 Microi 吾码平台，实时查询数据库结构、读取引擎代码、远程执行引擎。 完整工具分类、安装方式、写入确认与回读规则参见 MCP Server 专题 (https://microi.net/doc/v8-engine/mcp-server.html)。 当前实现边界 外部客户端通过 MCP Host/Agent Loop 调用工具。平台普通 Chat/ChatStream 使用服务端会话上下文和固定核心规范 Prompt，不检索完整知识库；NL2SQL 默认使用当前租户 Schema 关键词检索与准确字段回读；NL2V8 默认使用 Skill 镜像与当前租户 Schema 关键词检索。只有 mic_ai.EnableVectorDatabase=1 时，两条检索链路才增加向量融合，向量服务异常回退到关键词结果。平台在线低代码建模模式另由 OnlineMcpAgent 建立当前用户与租户绑定的同版 MCP 会话，注册工具并执行工具循环；进入及调用前重新校验管理员权限，写入状态与实际回读分别记录。普通对话不会因此自动执行工具，仅在 Prompt 中写“使用 MCP”也不能作为执行证据。 NL2SQL 当前由服务端生成不可被 JSON 伪造的授权上下文：白名单仅包含当前租户非受保护业务表；普通角色的 AI 角色策略还会与缓存的 FormEngine 列表读取权限取交集，关键词候选和可选向量候选都会在进入 Prompt 前再次过滤。执行层要求精确非空白名单，逐个校验每个 FROM/JOIN 表，拒绝注释、多语句、CTE、UNION、写操作和危险函数，并按数据库施加 MaxRows + 1 行限制与 30 秒超时。 这仍是词法安全门禁而不是 SQL AST；模型生成的动态值当前不会自动改写为数据库参数，通用 NL2SQL 也不会执行菜单 SqlWhere/SqlJoin 行级范围。带行级范围的表对普通角色失败关闭；部门、本人或关联记录范围查询必须通过经过审核、显式参数化并记录审计的业务 ApiEngine，不能把“拥有菜单读取权限”描述成“NL2SQL 已继承行级权限”。 平台在线 AI 若在后续版本增加 Tool/Agent Loop，应复用后端现有授权服务并继承当前用户和租户身份；禁止使用平台超级管理员 Token 自调用 MCP 绕过权限。模型提出工具调用后，服务端仍需校验参数、确认写操作、限制循环次数/时长/结果大小、记录审计并回读验证。 ### 什么是 Microi MCP Microi MCP Server 让 Codex、GitHub Copilot、Cursor、Trae、Claude Code 等外部 AI 客户端在明确权限和确认规则下读取或操作 Microi 平台——无需手工复制表结构和 V8 文档，AI 可以实时获取当前租户事实并在写后回读。 ### 提供的 AI 能力（代表） 领域 | 代表能力 | 写入保护 | 状态与事实发现 | 当前服务器/OsClient、实时 Schema、菜单、角色、接口、事件、应用和业务蓝图 | 只读 | 全系统建模 | Manifest Schema、规划、dry-run、表/字段/菜单/权限/数据源/任务生成与系统验证 | 真实生成需确认 | V8 与接口引擎 | 列表、源码读取、创建、保存、运行、表单/字段/模块/流程 V8 | 保存前校验，写后回读 | 页面、打印与工作流 | Page Engine、打印模板、流程拓扑、条件路线和节点代码 | 先校验再保存 | 在线 AI 应用 | 发现 Web/UniApp/MicroService、读取源码、创建、同步和发布 | 分阶段确认与版本回读 | 测试与运维 | E2E 上下文、验收、文件、Redis、MongoDB 日志 | 高风险操作显式确认 | 完整工具清单以当前 MCP 的 tools/list 为准；Codex 大工具集场景还可通过 microi_codex 的 list_tools / describe_tool 发现原始工具。 ### 前置条件 - 已部署 Microi 吾码后端服务 - 已安装支持 MCP 的 AI 客户端（Codex / GitHub Copilot / Cursor / Trae / Claude Code 任一） ### 推荐方式：VS Code 插件或 CLI（无需手工部署 MCP） 大多数用户无需手动配置 MCP 安装 Microi 吾码 VS Code 插件 (https://marketplace.visualstudio.com/items?itemName=Microi.v8-engine)，或安装 @microi.net/cli 后运行 microi init --pull。VSIX 与 CLI npm 包都内置 MCP Server 和 Skills，普通用户无需克隆或构建 microi.mcp。 两种入口都会： - 幂等生成 .vscode/mcp.json、.cursor/mcp.json、.trae/mcp.json、.mcp.json 和 Codex config.toml，保留用户已有 MCP； - 使用工作区 Token 文件，CLI 不落盘保存密码，插件密码保存在 VS Code SecretStorage； - 注入 AGENTS.md、CLAUDE.md、Copilot/Cursor 指令、V8 typings 和完整 Skills； - 提供真实诊断或 microi doctor，区分“配置存在”与“MCP 当前可调用”。 流程： 安装一种入口 → 添加服务器并登录 → 初始化 AI/MCP → 新开 AI 对话 → 按需拉取代码。 以下手工配置只适用于 MCP 源码开发者或需要自建远程 SSE 的团队；普通 CLI 用户不需要执行。 ### 手动配置：本地 stdio 模式 AI 工具在每次启动时自动拉起 MCP Server 进程。 #### 安装 bash ``` # MCP Server 源码内置于平台仓库 microi.mcp 目录 git clone https://github.com/itdos/microi.net.git # 国内网络也可使用 Gitee 镜像：git clone https://gitee.com/ITdos/microi.net.git cd microi.net/microi.mcp npm install npm run build ``` #### GitHub Copilot（VS Code） 在项目 .vscode/mcp.json 中添加： json ``` { "servers": { "microi": { "type": "stdio", "command": "node", "args": ["/path/to/microi.mcp/dist/index.js"], "env": { "MICROI_API_URL": "https://你的API地址", "MICROI_USERNAME": "账号", "MICROI_PASSWORD": "密码", "MICROI_OS_CLIENT": "" } } } } ``` #### Cursor 在项目根目录创建 .cursor/mcp.json： json ``` { "mcpServers": { "microi": { "command": "node", "args": ["/path/to/microi.mcp/dist/index.js"], "env": { "MICROI_API_URL": "https://你的API地址", "MICROI_USERNAME": "账号", "MICROI_PASSWORD": "密码", "MICROI_OS_CLIENT": "" } } } } ``` #### Claude Code (CLI) bash ``` claude mcp add microi -- \ env MICROI_API_URL=https://你的API地址 \ env MICROI_USERNAME=账号 \ env MICROI_PASSWORD=密码 \ node /path/to/microi.mcp/dist/index.js ``` 安全提示 配置文件包含敏感信息，请将 .vscode/mcp.json 和 .cursor/mcp.json 加入 .gitignore，避免提交到 Git。 ### 远程 SSE 模式（团队 / 生产推荐） 将 MCP Server 部署为 Docker 容器，所有人连同一个 SSE 地址。 #### Docker 部署 bash ``` cd microi.mcp cp .env.example .env # 编辑 .env 填入后端地址和管理员账号 docker compose up -d ``` #### Nginx 反向代理 推荐挂载到已有 API 域名下： nginx ``` # MCP SSE 端点 location /mcp/sse { proxy_pass http://127.0.0.1:3000/sse; proxy_http_version 1.1; proxy_set_header Connection ''; proxy_buffering off; proxy_cache off; proxy_read_timeout 86400s; } # MCP 消息端点 location /mcp/messages { proxy_pass http://127.0.0.1:3000/messages; proxy_http_version 1.1; } # MCP 健康检查 location /mcp/health { proxy_pass http://127.0.0.1:3000/health; } ``` #### 验证部署 bash ``` curl https://api.example.com/mcp/health # 应返回 {"status":"ok","server":"microi-mcp-server","version":"1.0.0"} ``` #### AI 工具连接 SSE GitHub Copilot（.vscode/mcp.json）： json ``` { "servers": { "microi": { "url": "https://api.example.com/mcp/sse", "headers": { "X-Microi-Username": "账号", "X-Microi-Password": "密码", "X-Microi-OsClient": "" } } } } ``` Cursor（.cursor/mcp.json）： json ``` { "mcpServers": { "microi": { "url": "https://api.example.com/mcp/sse", "headers": { "X-Microi-Username": "账号", "X-Microi-Password": "密码", "X-Microi-OsClient": "" } } } } ``` ### 环境变量 变量 | 必填 | 说明 | 示例 | MICROI_API_URL | ✅ | Microi 后端 API 地址 | https://api.microi.net | MICROI_USERNAME | ※ | 登录账号（无 Token 时必填） | admin | MICROI_PASSWORD | ※ | 登录密码（无 Token 时必填） | password | MICROI_OS_CLIENT | 否 | 应用标识（多租户场景） | myApp | MICROI_TOKEN | ※ | 直接传 Token（优先于账号密码） | Bearer xxx | ### 使用场景示例 在支持 MCP Host 的外部 AI 客户端中配置 MCP 后，可以直接在对话中操作平台： ``` 你：查看当前数据库有哪些表 AI：（调用 microi_get_db_schema）当前数据库共 42 张表... 你：帮我创建一个查询订单列表的接口引擎 AI：（调用 microi_get_db_schema 了解表结构 → 生成代码 → 调用 microi_create_engine 创建引擎） 接口引擎已创建，Key 为 get-order-list... 你：执行一下看看结果 AI：（调用 microi_run_engine）返回了 20 条订单数据... ``` --- ## 📌 四种 AI 能力对比 方案 | 提供的能力 | 适用场景 | AI 开发工具（VS Code + CLI） | 连接登录、Skills/typings、MCP、实时 Schema、V8 同步；插件补充资源树/Diff/断点调试，CLI 支持无 IDE 工作流 | 外部 AI 日常开发与完整交付 | MCP Server | 为具备 MCP Host 的客户端提供实时查询、保存和执行工具 | AI 受控操作平台 | Skills | 具体场景的编码最佳实践和代码模板 | 编码规范，深度指导 | 平台在线 AI | 普通会话上下文、NL2SQL Schema 双模式检索、NL2V8 Skill + Schema 双模式检索；低代码建模模式接入受控 MCP | NL2SQL/NL2V8 默认关键词检索、可选向量融合；低代码建模由可信宿主以当前用户权限调用同版 MCP | 推荐组合 外部开发场景由 VS Code 插件或 CLI 建立工作区，Skills 提供规范，MCP 提供最新事实和受控执行；平台在线 AI 在 NL2SQL/NL2V8 等明确入口默认使用大模型关键词扩展与权限感知 Schema/Skill 检索，只有管理员显式开启向量数据库后才增加向量召回。MCP 是工具协议，关键词/向量索引都是检索手段，三者不能互相替代。 平台源码（含 Skills、MCP）：GitHub (https://github.com/itdos/microi.net) / Gitee (https://gitee.com/ITdos/microi.net) ## 📌 Codex 接入 Microi 的要点 Codex 的帐号、订阅、安装和网络要求应以其当前官方说明为准，本页不维护容易过期的注册、支付、地区或代理教程。Microi 侧只需要完成以下步骤： - 在准备作为项目工作区的目录安装并运行 @microi.net/cli： bash ``` npm install -g @microi.net/cli microi init --pull ``` - 运行 microi doctor，确认 Profile、Token、Skills、工作区指令与 Codex MCP 配置均正常。 - 关闭当前 Codex 对话并新开一个对话；已打开的会话通常不会热加载新增 MCP。 - 先让 Codex 调用 microi_get_status 核对 API Server、OsClient 和登录身份，再使用本页推荐提示词。 - 代理地址属于用户本机环境，不要把固定端口、地区规则、帐号、密码或 Token 写进项目文档和仓库。 如果 Codex 能看到 MCP 配置却不能调用工具，先运行 microi doctor；仍失败时，在 VS Code 插件中执行 Microi MCP: 诊断 MCP 可调用性，区分配置错误、Node 启动失败、Token 失效和服务器不可达。