Coze Loop prompt-components 前端组件包解析：从 Prompt 编辑器到模型配置面板的完整实战指南

• 人工智能
• 大模型
• AI Agent
• 提示工程
• AI 评测
• 可观测性
• 后端
• 前端

导读

@cozeloop/prompt-components是 Coze Loop（下一代 AI Agent 优化平台）前端 monorepo 中面向 Prompt 场景的公共组件包，集中提供了 Prompt 编辑、版本管理、模型选择与参数配置、Schema 编辑、Mermaid 图表渲染等能力。本文将以该包的 README 为骨架，结合仓库源码逐层剖析其安装方式、全部导出 API 的用法、底层编辑器扩展原理与多模态变量机制，帮助你在自己的 Agent 工程中直接复用这套经过生产验证的 Prompt 开发组件。

包定位与整体概览

该包属于 Coze Loop 前端frontend/packages/loop-components/目录下的组件家族，package.json中描述为"Prompt common components for cozeloop"，main入口直接指向./src/index.ts，即组件源码即发布产物。从 index.ts 的导出清单可以看出，它的核心能力被明确划分为两大 Feature：

• Editor：以 CodeMirror 6 生态（@codemirror/*、@coze-editor/editor）为基础构建的 Prompt 富编辑体系，包括基础编辑器、Diff 对比编辑器、JSON/纯文本/Schema 编辑器；
• Prompt：围绕 Prompt 全生命周期管理的业务组件，包括消息编辑、创建/复制/编辑弹窗、版本选择、模型配置等。

在依赖层面，它大量复用 monorepo 内部的 workspace 包（@cozeloop/api-schema、@cozeloop/components、@cozeloop/i18n-adapter、@coze-arch/bot-md-box-adapter等），并依赖mermaid、shiki、ahooks、immer等通用第三方库，可见该包承担着"Prompt 业务组件聚合层"的职责。

安装与集成：基于 Rush 的 monorepo 工作流

README 中给出的安装方式是标准的 Rush monorepo 流程。在任意消费方包的package.json中声明依赖：

{ "dependencies": { "@cozeloop/prompt-components": "workspace:*" } }

随后执行安装与链接：

rush update

workspace:*协议表示直接链接到本仓库的本地包，无需发布到 npm registry，改动源码即可即时生效。从 rush.json 与frontend/config/rush/下的配置文件可以确认，该仓库使用 Rush + pnpm 管理多包仓库，因此跨包依赖统一通过rush update解析。

关于使用方式，README 给出了导入占位，结合 index.ts 的实际导出，典型用法如下：

import { PromptBasicEditor, PromptEditor, PromptDiffEditor, PopoverModelConfigEditor, BasicModelConfigEditor, ModelSelectWithObject, DevLayout, PromptCreate, PromptVersionSelect, SchemaEditor, getPlaceholderErrorContent, } from '@cozeloop/prompt-components';

核心组件 API 逐个击破

README 的 API Reference 列出了 10 个主要导出，本文结合源码逐一展开其真实 Props 与适用场景。

PromptBasicEditor：Prompt 富文本编辑底座

PromptBasicEditor位于 src/basic-editor/index.tsx，是一个forwardRef组件，基于@coze-editor/editor的EditorProvider+Renderer构建，并使用preset-prompt预设。它支持以下 Props：

通过ref可以拿到PromptBasicEditorRef命令式 API：

interface PromptBasicEditorRef { setEditorValue: (value?: string) => void; // 程序化设置内容 insertText?: (text: string) => void; // 在光标处插入文本 getEditor?: () => EditorAPI | null; // 获取底层编辑器实例 }

内部实现上，insertText会先取当前选区（editor.getSelection()）再调用editor.replaceText；setEditorValue则直接调用底层setValue。组件还内置了一个 CodeMirror 主题，将行号槽背景置为透明、滚动区左右留白，并通过Prec.high注册Tab键行为：光标处插入四个空格（insertFourSpaces），选中文本时回退到indentWithTab。

PromptEditor：面向对话消息的编辑容器

PromptEditor在 src/prompt-editor/index.tsx 中，是对PromptBasicEditor的再封装，服务于"对话消息"这一业务模型。其核心类型PromptMessage<R>是消息结构（role泛型化，默认Role），关键 Props 包括：

• message?: PromptMessage<R>：当前消息（含role、content、parts、key/id等）；
• messageTypeList/onMessageTypeChange：消息角色（system/user/assistant…）切换，由 message-type-select.tsx 渲染为菜单按钮；
• placeholderRoleValue：占位变量角色值（默认Role.Placeholder），当message.role等于该值时，编辑器退化为一个带格式校验的单行输入框（maxLength为VARIABLE_MAX_LEN，即 50），用于输入占位变量名；
• disabled/isDrag：禁用或拖拽态（均转为只读）；
• dragBtnHidden/leftActionBtns/rightActionBtns/hideActionWrap：头部工具栏定制；
• isFullscreen：全屏样式；
• modalVariableEnable/modalVariableBtnHidden：多模态变量能力开关与按钮显隐。

内容变化时，组件调用splitMultimodalContent将文本拆分为ContentPart[]（文本与多模态变量），通过onMessageChange回传。若占位变量内容非法（空、格式不对、与已有变量重名），会通过getPlaceholderErrorContent计算错误文案并展示在容器底部。

PromptDiffEditor：Prompt 版本对比视图

PromptDiffEditor（src/basic-editor/diff.tsx）基于 CodeMirror Merge 视图实现左右分栏对比：

• oldValue/newValue：旧、新版本内容；
• editorAble：右侧（新版本）是否可编辑，可编辑时onChange生效；
• autoScrollToBottom：挂载后滚动到文档末尾。

Merge 配置中collapseUnchanged折叠未变化区域（margin: 3, minSize: 4），diffConfig.scanLimit: 3000限制 diff 扫描范围。左右两侧通过cunstomFacet（见 custom-facet.tsx，一个取最后一个值的 CodeMirrorFacet）注入各自标识，并内置 diff 主题：右侧变更行为绿色高亮rgba(34,184,24,0.3)，左侧删除为红色rgba(238,68,51,0.3)。ref暴露goToPreviousChunk/goToNextChunk用于在差异块间跳转。

模型配置编辑器：Popover 与内嵌两种形态

README 列出的PopoverModelConfigEditor、PopoverModelConfigEditorQuery、BasicModelConfigEditor、ModelSelectWithObject共同构成了"模型选择 + 参数配置"能力，全部位于src/model-config-editor-community/目录（社区开源版）。

• PopoverModelConfigEditor（popover-model-config-editor.tsx）：Popover 弹出式面板，宽 496px。Props 支持models、value（ModelConfigWithName）、disabled、defaultActiveFirstModel（无 value 时默认选中第一个模型并回填配置）、scenario（使用场景）、onChange/onModelChange、renderDisplayContent（自定义触发器展示内容）。面板内是ModelSelectWithObject+ModelConfigFormCommunity表单，表单值变化即通过onValueChange实时onChange。
• PopoverModelConfigEditorQuery：在 Popover 版之上封装数据查询，通过useModelList(spaceID, scenario)获取模型列表后注入models，消费方无需关心数据来源。
• BasicModelConfigEditor（basic-model-config-editor.tsx）：内嵌（非弹层）表单形态，Props 与 Popover 版基本一致，额外支持extra追加自定义表单节点，适合放在页面主体中使用。
• ModelSelectWithObject（src/model-select/index.tsx）：以整个Model对象作为选择值（onChangeWithObject），支持按模型系列（series.name）分组展示，组标题形如{系列名} | {厂商}；未分组时展示showTick勾选态，并提供基于模型名称的本地过滤。

参数配置表单（model-config-form-community.tsx）根据模型的param_config.param_schemas动态渲染滑块或开关，覆盖max_tokens、temperature、top_p、top_k、frequency_penalty、presence_penalty、json_mode等参数，其中max_tokens的默认上限由 consts/index.ts 中的DEFAULT_MAX_TOKENS = 4096兜底；temperature、top_p步进 0.01，top_k步进 1。默认值来源于 utils.ts 的getDefaultModelConfig，它读取param_schemas中的default_value并转换为ModelConfigWithName（含model_name、model_id及各项参数）。

PromptCreate 与 PromptVersionSelect：Prompt 生命周期管理

• PromptCreate（src/prompt-create/index.tsx）：新建/编辑/复制 Prompt 的 Modal。通过isEdit/isCopy切换三种形态，底层调用StonePromptApi.CreatePrompt/UpdatePrompt/ClonePrompt，并上报prompt_create埋点事件。表单含prompt_key（正则^[a-zA-Z][a-zA-Z0-9_.]*$，最长 100，编辑态禁用）、prompt_name（允许中文/字母/数字及_.-，但不能以_.-开头）、prompt_description（最长 500）。复制时自动追加_copy后缀（超过 95 字符则不加）。
• PromptVersionSelect（src/prompt-version-select/index.tsx）：Prompt 版本下拉选择，配合 use-version-list.ts 使用useInfiniteScroll分页加载StonePromptApi.ListCommit（每页 10 条），支持滚动加载更多与刷新按钮，并把提交人信息从users中关联映射到每个版本上。

DevLayout 与工具函数

• DevLayout（src/dev-layout/index.tsx）：开发者布局容器，40px 高的顶栏（title+actionBtns）+ 内容区，用于快速搭建调试页面。
• getPlaceholderErrorContent（src/utils/prompt.ts）：占位变量校验，依次检查非空、格式（^[A-Za-z][A-Za-z0-9_]*$）、与普通变量重名，返回对应的 i18n 错误文案或空串。
• 同文件还导出了splitMultimodalContent、multimodalPartsToContent、getMultimodalVariableText，用于在text与<multimodal-variable>xxx</multimodal-variable>标签片段之间双向转换。

源码级原理：PromptBasicEditor 的扩展体系

PromptBasicEditor的能力密度来自src/basic-editor/extensions/下的一组 CodeMirror 扩展，它们通过@coze-editor/editor的useInjector/astDecorator机制注入。

变量插入：输入{{唤起浮层

extensions/variable.tsx 是变量体验的核心：

• 监听文档变更，当输入恰好是{}且其前一个字符为{（即敲出{{）时，构造Mention触发上下文；
• 浮层使用PositionMirror跟随光标位置，展示variables列表（最多 200px 滚动区），支持鼠标点击插入；
• 插入时根据模板类型生成不同语法：Go Template 为{{.name}}，否则为{{name}}；
• 浮层打开期间会临时禁用编辑器的ArrowUp/ArrowDown/Enter快捷键，并在document上监听方向键与回车实现上/下选择、回车插入（usePopoverNavigation）。

语法高亮与变量校验

• Jinja 高亮（extensions/jinja.tsx）：基于 AST 装饰器区分JinjaStatement、JinjaStringLiteral、JinjaComment、JinjaExpression、JinjaKeyword等节点，分别着色：表达式绿色（#00A136）、关键字粉色（#D1009D）、注释灰色半透明。完整 Jinja2 高亮仅在isJinja2Template时开启。
• Go Template / Jinja2 完整高亮（extensions/go-template.ts）：使用shiki+codemirror-shiki构建高亮核心，动态加载go-syntax、jinja语言与one-light主题（createOnigurumaEngine）。
• 变量校验（extensions/validation.ts）：解析{{ }}中的内容，普通模板校验变量名必须匹配^[a-zA-Z][\w]{0,49}$；Jinja/Go 模板下则通过parseJinjaVariable先剥离.属性访问（text.a→text）与[0]数组索引（text[0]→text）再匹配已注册变量。合法变量标绿，非法标灰。
• Markdown 高亮（extensions/markdown.tsx）：对ATXHeading（标题）、Emphasis（斜体）、StrongEmphasis（粗体）、ListMark/QuoteMark（列表/引用符）做装饰，标题青蓝加粗、引用符紫色。
• 语言支持（extensions/language-support.tsx）：注入preset-prompt的languageSupport（Markdown + Jinja 混合语法解析）。

搜索、快捷键与占位

• 搜索面板（extensions/search/index.ts）：canSearch开启后注册原生搜索扩展，自定义SearchPanel，并额外绑定Ctrl-g跳转到指定行。
• 智能按键（extensions/keymap.ts）：实现了三个StateCommand——insertFourSpaces（Tab 插入两空格，选中时放行默认缩进）、insertNewlineContinueMarkup（回车自动延续 Markdown 列表/引用标记，并处理有序列表自动重编号renumberList、空行退出标记、引用块延续）、deleteMarkupBackward（退格逐层删除列表/引用标记）。PromptBasicEditor与PromptDiffEditor均通过 index.ts 对外导出这三个命令，方便其他编辑器复用。
• 占位提示：通过Placeholder渲染linePlaceholder（默认 i18n 文案"请输入内容，格式为变量"）。

多模态变量：Widget 级渲染

Prompt 中多模态变量以<multimodal-variable>name</multimodal-variable>文本标签存储，在编辑器中则渲染为可视化 Widget（widgets/modal-variable/widget.tsx）：

• 继承 CodeMirror 的WidgetType，toDOM时通过renderDom将 React 组件挂载到编辑器 DOM 中；
• 展示变量名、删除按钮（只读时隐藏），支持disabled与 Tooltip 提示"当前模型不支持多模态"；
• 通过eq/getEqKey实现增量更新，destroy时卸载 React 根节点。

配套的 widgets/modal-variable/index.tsx 负责补全：在PromptEditor头部点击"添加多模态变量"按钮（modal-variable.svg 图标）弹出 Popconfirm 表单，变量名需匹配^[a-zA-Z][\w]{0,49}$（不允许换行、不允许与已有变量重名、最长 50 字符），确认后以<multimodal-variable>...</multimodal-variable>文本插入光标处。

周边能力：Code 编辑器、Schema 与 Mermaid

• Code 编辑器（src/code-editor/）：基于preset-code的CodeEditor渲染器，注册json（使用mixLanguages解决插值括号干扰高亮）与shell语言，及coze-light/coze-dark两套主题；BaseJsonEditor在 json-editor.tsx 中实现，通过 transformer 将{{...}}插值替换为null后再做 JSON 校验与格式化（formatJson，tabSize 2）。各尺寸选项（minHeight、maxHeight、editerHeight、borderRadius、padding、lineHeight）均映射为 CodeMirror 主题。
• SchemaEditor（src/schema-editor/index.tsx）：按language在BaseJsonEditor与BaseRawTextEditor间切换，固定 500px 高、圆角边框容器，readOnly时降低透明度。
• MermaidDiagram（src/mermaid-diagram/index.tsx）：懒加载mermaid渲染图表，内置base主题配色；ref暴露zoomIn/zoomOut/fit/exportImg（导出 SVG 图片），渲染失败时回退到上次成功的图表。

工程化与开发约定

该包在 package.json 中声明了完整的工程化配置：

• 技术栈：TypeScript + React 18 + CodeMirror 6，测试使用 Vitest（vitest.config.mts），代码质量由 ESLint 把关；
• 脚本：rushx lint（ESLint 缓存模式）、test/test:cov（当前仓库中为占位空实现）；
• 国际化：文案统一通过@cozeloop/i18n-adapter的I18n.t获取，如prompt_please_input_content_variable_format、insert_variable、parameter_config等 key；
• 类型约定：Int64 = string | number等公共类型位于 src/model-types.ts，其中ModelConfig定义了temperature、max_tokens、top_k、top_p、json_mode、presence_penalty、frequency_penalty、provider_model_id、thinking（budget_tokens）等完整参数结构；
• 许可：Apache-2.0（源码文件头部均带 SPDX 声明）。

总结

@cozeloop/prompt-components是 Coze Loop 前端中 Prompt 编辑与配置能力的集中承载者：以 CodeMirror 6 为底座构建了支持变量插入、Jinja/Go Template/Markdown 高亮、非法变量校验、多模态 Widget、Diff 对比的编辑器体系，并以表单组件补齐了模型选择、参数配置、Prompt 创建/复制/版本管理。在 Coze Loop 的 AI Agent 开发、调试与评测全生命周期中，它既是 Prompt 编写的"前端入口"，也是可独立复用的开源组件集——你可以直接通过rush update接入自己的业务页面，也可以按需抽取其中的扩展与工具函数进行二次定制。

• 人工智能
• 大模型
• AI Agent
• 提示工程
• AI 评测
• 可观测性
• 后端
• 前端