LogicFlow AI 编程支持指南：让 AI Agent 直接读取随包发布的本地文档

LogicFlow AI 编程支持指南：让 AI Agent 直接读取随包发布的本地文档

【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架，支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow

从@logicflow/core@2.2.2开始，LogicFlow 把完整的教程与 API 文档随 npm 包一起发布，并通过安装后的 postinstall 提示引导你把一段标准提示词复制给 AI Agent。本指南面向使用 AI 编程工具（如 Claude Code、Cursor 等）接入 LogicFlow 的开发者，读完你将掌握：提示词在什么时机复制、Agent 如何定位本地文档、文档与提示词在仓库中的生成机制与底层实现，以及如何让 Agent 优先采用官方能力而不是从零重写。

为什么要把文档随 npm 包一起发布

传统的做法是让 AI Agent 凭借“通用经验”来实现流程图编辑功能——这往往会导致 Agent 用自己熟悉的另一套 API 或自造一套封装来写 LogicFlow 代码，与官方推荐用法脱节。LogicFlow 的解法参考了 Next.js 的模式：把文档放进 npm 包，让 AI 工具在用户项目本地就能读取到权威、准确的官方文档，而不是依赖可能过时或错误的训练数据。

在仓库的 AI 文档集成设计 中记录了这一思路：Next.js 16.2 起为 AI 开发而设计，安装后会在node_modules/next/dist/docs/附带完整文档，AI 工具通过项目根目录的AGENTS.md找到文档入口。LogicFlow 的场景差异在于，用户通常不是通过脚手架创建项目，而是直接在现有项目中安装依赖，因此采用了postinstall 输出 prompt 引导的方式：用户安装@logicflow/core后，终端直接打印一段可复制的规则，粘贴给 AI Agent 即可。

什么时候复制给 Agent

建议在以下时机把提示词复制给你的 AI Agent：

1. 首次安装@logicflow/core之后——让 Agent 一开始就建立“先查本地文档”的认知；
2. 升级@logicflow/core之后——新版本文档可能与旧版有差异，需要刷新 Agent 的知识；
3. 准备让 Agent 实现 LogicFlow 相关功能之前——例如创建画布、自定义节点、接入插件或做自动布局之前。

如果 Agent 手里已经是旧提示词，但仍然没有按官方插件或布局能力实现功能，也可以重新复制最新的提示词。仓库根目录 README.md 的「AI 编程支持」章节与随包发布的提示词内容保持同步，错过安装输出时也可以从这里找回。

Agent 需要知道什么：三个包的分工

LogicFlow 主要由三个 npm 包组成，Agent 需要先理解它们各自的职责，才能在实现功能时选择正确的依赖：

这些包的使用文档全部发布在node_modules/@logicflow/core/dist/docs/中，其中@logicflow/extension和@logicflow/layout的文档主要位于tutorial/extension/目录下。之所以把三个包的文档统一放进 core 包，是为了让 AI 一次性获取完整知识：即使项目没有安装 extension，Agent 也能据此告知“如需 MiniMap 请安装@logicflow/extension”。

复制给 Agent 的提示词

将下面整段内容复制给你的 AI Agent（含 BEGIN/END 标记，便于一次选中完整复制）：

<!-- BEGIN:logicflow-agent-rules --> # LogicFlow Agent Rules LogicFlow documentation is available at: - `node_modules/@logicflow/core/dist/docs/` Package roles: - `@logicflow/core`: core graph editor runtime, including canvas, nodes, edges, models, events, rendering, themes, and basic interactions. - `@logicflow/extension`: official plugins for common product features. - `@logicflow/layout`: official layout plugins for automatic graph layout. The docs for `@logicflow/extension` and `@logicflow/layout` are included under: - `node_modules/@logicflow/core/dist/docs/tutorial/extension/` Before implementing any LogicFlow feature, check the local docs first to see whether LogicFlow already provides a built-in, extension, or layout capability. If it does, prefer the documented official capability instead of reimplementing it from scratch. If an official package is needed but not installed, ask the user before installing it. <!-- END:logicflow-agent-rules -->

这段规则的核心是一条能力优先原则：在实现任何 LogicFlow 功能之前，先查阅本地文档，确认官方是否已提供内置、插件或布局能力；如果已有官方能力，优先使用文档化的官方方案，而不是从零重写。同时，如果确实需要官方包但项目尚未安装，先询问用户再安装，避免 Agent 擅自引入依赖。

底层实现一：文档是如何进入 npm 包的

文档进入 npm 包依赖仓库根目录的build:docs脚本，其实现位于 copy-ai-docs.js。该脚本做的事情非常直接：

• 清理并重建目标目录packages/core/dist/docs/；
• 将sites/docs/docs/tutorial/复制到packages/core/dist/docs/tutorial/；
• 将sites/docs/docs/api/复制到packages/core/dist/docs/api/；
• 在文档根目录生成index.md作为入口索引；
• 输出复制统计（含 markdown 文件总数）。

文档来源与目标位置的映射关系如下（来自 AI 文档集成设计）：

不复制的内容包括article/（面向读者的技术文章）和release/（版本发布说明），确保打进 npm 包的只有对 Agent 最有价值的教程与 API 参考。复制时保留中英文两个版本（.zh.md+.en.md）以及原有的 frontmatter 等格式。

发布流程中，文档构建被编排进整体命令链（见根 package.json）：

pnpm build # 构建代码（lib、es、dist） pnpm build:docs # 复制文档到 packages/core/dist/docs/ pnpm changeset version pnpm publish:only # 发布到 npm（包含 dist/docs/）

其中build:all组合了测试、构建、UMD 打包与build:docs，而仓库根目录的prepare脚本在安装依赖时也会触发build:all，保证本地开发环境同样具备最新文档。安装后的最终效果是用户项目中呈现如下结构（发布后）：

node_modules/@logicflow/core/ ├── dist/ │ ├── index.min.js # UMD 构建 │ ├── docs/ # AI 文档 │ │ ├── tutorial/ │ │ │ ├── basic/ # 基础：节点、边、事件、主题等 │ │ │ ├── advanced/ # 进阶：键盘、拖拽、React/Vue 集成等 │ │ │ └── extension/ # 插件：MiniMap、Group、Menu 等 │ │ └── api/ │ │ ├── detail/ │ │ ├── model/ │ │ └── theme/ │ └── ... ├── es/ # ESM 构建 ├── lib/ # CJS 构建

在 packages/core/package.json 中可以看到files字段已包含dist、es、lib和scripts，确保构建产物、文档与 postinstall 脚本都能随包发布。

底层实现二：postinstall 提示的三段式输出

安装@logicflow/core时，由postinstall脚本（入口见 packages/core/package.json）负责在终端打印提示，其实现位于 postinstall-ai-prompt.js。该脚本最初将提醒文案与可复制正文混在同一段字符串里，用户复制时容易把提醒句也带进去。后续的 postinstall 提醒设计 将其重构为自上而下的三段结构：

1. 提醒区：中英文各一句说明“请将下方规则复制给 AI Agent”，并提示错过输出时可到仓库 README 的 AI 编程章节找回；此区域不出现在复制标记内；
2. 分割线：单独一行整行重复同一字符（如─）；
3. 可复制区：仅输出<!-- BEGIN:logicflow-agent-rules -->到<!-- END:logicflow-agent-rules -->之间的内容（含两行 marker），便于从 BEGIN 拖到 END 一次复制。

分割线长度遵循 Node CLI 惯例：读取process.stdout.columns，为正整数则使用，否则回退到固定默认值 80；同时对超宽终端用Math.min(columns, 120)设上限（见 postinstall-ai-prompt.js 的实现）。

提醒区的样式设计刻意不引入任何新依赖（不采用 boxen、chalk 等），只使用广泛支持的 ANSI SGR 序列——加粗（\x1b[1m）+ 黄底黑字（\x1b[43m\x1b[30m），行尾\x1b[0m复位。是否启用 ANSI 由shouldUseAnsi()判定，需同时满足以下条件（见 postinstall-ai-prompt.js）：

• process.stdout.isTTY === true（终端交互环境）；
• process.env.NO_COLOR未设置（遵守社区 NO_COLOR 约定）；
• process.env.TERM !== 'dumb'；
• 若处于 CI 环境（process.env.CI === 'true'）且未设置FORCE_COLOR，则禁用 ANSI，避免污染 CI 日志。

不满足条件时，整个提醒区不带任何转义序列，降级为纯文本，但三段式结构保持不变。设计约束是packages/core/package.json不得新增任何仅服务于 postinstall 的运行时依赖——@logicflow/core的依赖列表保持精简（lodash-es、classnames、mobx、preact 等，见 packages/core/package.json）。

多包策略：为什么只有 core 有 postinstall

文档与提示词的多包策略（见 AI 文档集成设计）可总结如下：

这样设计的原因很明确：extension 和 layout 的文档统一放在 core 包中，AI 一次即可获取完整知识；用户安装 core 后，即使没有安装 extension，Agent 也能提示“如需 MiniMap 请安装@logicflow/extension”。仓库 sites/docs/docs/tutorial/extension/ 下对应着 20 个官方插件与布局主题的中英文文档（group、dynamic-group、minimap、menu、snapshot、pool、layout、bpmn-element、dnd-panel 等），这些都是 Agent 应当优先参考的官方能力清单。

使用建议与后续阅读

• 将提示词交给 Agent 后，可以让它先列出node_modules/@logicflow/core/dist/docs/中与当前需求相关的文档，再据此给出实现方案；
• 若 Agent 给出的方案绕过了官方插件或布局能力，用最新提示词重新引导一次；
• 在 CI 或无 TTY 环境中安装包时，postinstall 仍会正常打印三段式结构（无 ANSI 颜色），不会因转义序列污染日志；
• 升级 core 包后记得重新同步提示词，让 Agent 使用与当前版本匹配的文档。

接下来可以按需阅读配套文档：

• 第一次接入 LogicFlow：阅读 快速上手
• 需要插件或布局能力：阅读 插件简介
• 需要精确 API 参数：阅读 API 导览

【免费下载链接】LogicFlowA flow chart editing framework focus on business customization. 专注于业务自定义的流程图编辑框架，支持实现脑图、ER图、UML、工作流等各种图编辑场景。项目地址: https://gitcode.com/GitHub_Trending/lo/LogicFlow