Coze Studio 机器人内容审核基础包 coze-studio/bot-audit-base 实战指南AuditErrorMessage 组件与审核 Hook 的接入与底层解析【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studiocoze-studio/bot-audit-base 是 Coze Studiocoze-studio前端 monorepo 中面向“Bot 内容审核bot content auditing”场景的基础能力包负责提供审核失败提示 UI 组件与审核功能集成的 TypeScript 类型契约。本文以该包的 README 为核心骨架结合其 组件源码、类型定义、底层 IDL 数据结构与同仓库的 bot-audit-adapter 适配包完整讲解安装接入、组件与 Hook 的用法、API 契约以及审核数据的真实字段结构帮助你快速在 Agent IDE 中集成“内容过审不通过”的前端处理链路。包定位为“Bot 内容过审”而生的基础能力在 Coze Studio 的 Agent IDE 中用户创建的 Bot 在发布前后需要经过内容审核audit审核对象包括 Bot 名称、描述、Prompt、开场白、背景图、Agent 子单元等。当审核不通过时前端需要统一、一致地向用户呈现错误信息并给出可跳转的文档链接。bot-audit-base正是为此提供的最底层基础包其职责边界非常清晰项目概述AuditErrorMessage 组件一个预置样式的 React 组件用于展示审核失败消息并支持自定义文档链接类型定义为 Bot 审核 Hook 与审核函数提供完整的 TypeScript 契约UseBotInfoAuditorHook、BotInfoAuditFunc国际化支持错误消息通过coze-arch/i18n的I18n.t读取翻译文案天然支持多语言Storybook 集成组件文档与测试环境README 中列出的开发脚本之一。从包结构上看它被设计为只做“地基”UI 组件 类型契约不包含具体审核业务逻辑具体审核逻辑由同仓库的coze-studio/bot-audit-adapter见 其源码在上层提供默认实现从而形成“base 定义契约、adapter 提供实现、业务组件消费”的清晰分层。安装与工程接入monorepo 工作区依赖该包位于 Coze Studio 的 monorepo由 rush.json 管理内因此在 package.json 中声明的包名为coze-studio/bot-audit-base版本号为0.0.1。安装时应当使用 workspace 协议与仓库内其他工作区包保持版本联动{ dependencies: { coze-studio/bot-audit-base: workspace:* } }添加依赖后在仓库根目录执行rush updaterush update会基于 rush.json 中的工作区定义解析workspace:*引用并生成各包锁文件使 monorepo 内包之间的依赖关系始终指向仓库内的最新源码。需要说明的是该包将 React 声明为 peer 依赖package.jsonreact 18.2.0、react-dom 18.2.0因此宿主应用需要自行提供 React 18.2 运行时。AuditErrorMessage 组件审核失败提示的标准出口基本用法AuditErrorMessage是包的核心 UI 产物从包入口 src/index.ts 导出。最简用法如下import { AuditErrorMessage } from coze-studio/bot-audit-base; function MyComponent() { return ( AuditErrorMessage link/docs/custom-guidelines / ); }组件只接收一个可选 proplink用于指定审核失败时展示的文档链接地址当不传时默认指向/docs/guides/content_principles。源码实现剖析组件的完整实现位于 components/audit-error-message/index.tsx其核心逻辑非常精简import React from react; import { I18n } from coze-arch/i18n; import styles from ./index.module.less; export function AuditErrorMessage({ link /docs/guides/content_principles, }: { link?: string; }) { return ( div className{styles[error-message]} {I18n.t(audit_unsuccess_general_type, { link: ( a relnoreferrer noopener href{link} target_blank className{styles.link} {I18n.t(audit_unsuccess_general_type_url)} /a ), })} /div ); }几个值得注意的实现细节i18n 注入整段错误消息通过I18n.t(audit_unsuccess_general_type, ...)渲染翻译模板中注入了一个a链接元素作为参数链接的展示文案同样来自I18n.t(audit_unsuccess_general_type_url)。这意味着“审核不通过”的文案和“查看指南”的链接文字都完全由 i18n 资源驱动便于多语言扩展无需改动组件本身。安全属性链接设置了target_blank并在rel中声明noreferrer noopener避免新窗口打开时泄露来源信息或产生反向 tabnabbing 风险。样式约定组件样式来自 index.module.less错误消息使用醒目的红色rgb(255, 68, 30)并左对齐apply text-left链接文字使用品牌蓝紫色#4d53e8保证“错误提示 可点击指引”的视觉层级。真实业务消费示例在 Agent IDE 中该组件已被实际业务接入。以 chat-background-config-contentBot 背景图配置为例使用处 L184-L188{auditNotPass ? ( div classNamepb-6 coz-bg-max px-6 AuditErrorMessage / /div ) : null}背景图上传组件通过onAuditCheck(notPass)回调L144-L147接收机审结果当auditNotPass为真时在页面底部渲染AuditErrorMessage /——这里直接使用默认文档链接无需额外传参。这一模式展示了该组件作为“审核失败统一出口”的典型用法业务组件只负责根据审核结果控制显隐文案与链接由基础包统一负责。类型契约审核 Hook 与审核函数包还输出了两个核心 TypeScript 类型定义见 interfaces/index.ts并从 src/index.ts 对外导出。UseBotInfoAuditorHook审核 Hook 的接口契约约定一个自定义 Hook 应返回如下结构export declare type UseBotInfoAuditorHook () { check: (params: BotAuditInfo) PromiseBotInfoAuditData; pass: boolean; setPass: React.DispatchReact.SetStateActionboolean; reset: () void; };返回值类型职责check(params: BotAuditInfo) PromiseBotInfoAuditData执行审核检查入参为 Bot 审核信息返回审核结果数据passboolean当前审核是否通过的布尔状态setPassReact.DispatchReact.SetStateActionboolean审核状态的标准 React setState 设置器reset() void重置审核状态到初始值BotInfoAuditFunc审核函数的独立类型export declare type BotInfoAuditFunc ( params: BotAuditInfo, ) PromiseBotInfoAuditData;即输入BotAuditInfoBot 审核信息输出一个解析为BotInfoAuditData审核结果数据的 Promise。该类型既可以独立存在也可以被check复用。两个类型均依赖coze-arch/bot-api/playground_api中定义的BotAuditInfo与BotInfoAuditData结构详见下文“底层数据结构”。一个完整的 Hook 实现示例README 给出了实现这些契约的示例import type { UseBotInfoAuditorHook, BotInfoAuditFunc } from coze-studio/bot-audit-base; // Example hook implementation const useBotAuditor: UseBotInfoAuditorHook () { const [pass, setPass] useState(false); const check: BotInfoAuditFunc async (params) { // Your audit logic here const result await performAudit(params); setPass(result.success); return result; }; const reset () setPass(false); return { check, pass, setPass, reset }; };同仓库的默认适配实现基础包只定义契约不提供业务实现实际的默认实现位于上层适配包coze-studio/bot-audit-adapter的 use-bot-audit/index.tsconst defaultPassState true; export const botInfoAudit: BotInfoAuditFunc ( _: BotAuditInfo, ): PromiseBotInfoAuditData Promise.resolve({}); export const useBotInfoAuditor: UseBotInfoAuditorHook () { const [pass, setPass] useState(defaultPassState); return { check: (_: BotAuditInfo) Promise.resolve({}), pass, setPass, reset: () { setPass(defaultPassState); }, }; };注意这里的默认策略初始pass状态为true默认放行check与botInfoAudit目前为占位实现返回空对象{}。这说明适配包为业务方提供了一套“先能跑起来”的骨架真实的机审调用可以由业务方替换check实现例如调用下文介绍的BotInfoAudit接口或在后续版本中由服务端审计回调驱动。同时adapter 还从 其入口 重新导出了AuditErrorMessage业务方可以直接从coze-studio/bot-audit-adapter一次性引入组件与 Hook。底层数据结构BotAuditInfo 与 BotInfoAuditData 全字段解析UseBotInfoAuditorHook与BotInfoAuditFunc的类型参数来自coze-arch/bot-api/playground_api。该模块的生成代码位于 playground_api/namespaces/playground.ts以下字段均为源码确认BotAuditInfo 定义 L1429-L1460。BotAuditInfoBot 审核入参字段类型说明bot_namestring?Bot 名称bot_descstring?Bot 描述bot_icon_uristring?Bot 图像 URLbot_promptstring?Bot Promptbot_opening_textstring?Bot 开场白文案bot_opening_questionsArraystring?Bot 开场白预置问题bot_preset_taskstring?Bot 定时任务bot_suggest_promptstring?Bot/Agent 用户问题建议 Promptvariable_listArrayVariable?Bot 变量task_listArraybot_task_common.TaskInfo?Bot triggerjump_config_promptstring?Agent 回溯配置 Promptbackground_imagesstring?背景图数据update_agentsArrayAgentInfoApi?Agent 数据过审background_images_structbot_common.BackgroundImageInfo?背景图结构化数据update_agents_structArraybot_common.Agent?Agent 结构化数据过审可见审核覆盖面很广既包括名称、描述、Prompt、开场白等文本信息也包括变量、定时任务、背景图与 Agent 子单元的结构化数据。字段同时提供_struct结构化版本与原始版本方便审核服务按需取用。BotInfoAuditData机审结果定义 L1563-L1568字段类型说明check_not_passboolean?true表示机审校验不通过not_pass_reasonArraystring?机审校验不通过原因的 starlingKey 列表not_pass_reason返回的是starlingKey 列表而非最终文案——前端需要将 key 交给 i18n 翻译层渲染为具体语言文案。这与AuditErrorMessage内部使用I18n.t的设计一脉相承审核链路中所有面向用户的文案都走国际化资源。配套请求/响应与回调结构围绕上述数据结构生成的 playground_api/index.ts 中定义了真实 RPC 方法BotInfoAudit 方法 L432-L451BotInfoAuditPOST /api/playground_api/audit/bot_info请求体为BotInfoAuditRequestbot_id、bot_audit_info、可选space_id、可选bot_mode返回BotInfoAuditResponsedata?: BotInfoAuditData。另有BotInfoCheckRequest / BotInfoCheckResponse同文件 L1583-L1592可用于提交前的信息校验。审核回调侧存在BotAuditCallbackRequest含PublishID、BotID、CommitVersion、Source: BotAuditCallbackSource、AuditResult与BotAuditRecord记录AuditScenes、AuditStatus、AuditResult等见 L1462-L1470从源码结构可以推断机审/人工审核结果会以回调callback形式回写审核记录前端通过轮询或推送感知状态变化后再调用check/展示AuditErrorMessage。开发与测试脚本、目录结构与工程规范可用脚本README 中列出了npm run dev启动 Storybook 开发服务器、npm run build、npm run lint、npm run test。对照当前 package.json实际声明的脚本为buildexit 0当前为占位实现避免构建阻塞linteslint ./ --cachetestvitest --run --passWithNoTeststest:covnpm run test -- --coverage基于 Vitest 覆盖率因此测试可直接执行npm run test或rushx test配合 vitest.config.ts 使用工程 lint 规范来自coze-arch/eslint-config与coze-arch/stylelint-config。项目结构src/ ├── components/ │ └── audit-error-message/ # AuditErrorMessage 组件含 .tsx 与 .module.less ├── interfaces/ # TypeScript 类型定义UseBotInfoAuditorHook / BotInfoAuditFunc └── index.ts # 主入口导出文件补充说明src/typings.d.ts通过/// reference typescoze-arch/bot-typings /引入全局类型声明包的main字段直接指向src/index.tspackage.json即 monorepo 内直接消费 TypeScript 源码无需预构建。依赖关系一览根据 package.json该包的核心依赖为依赖用途coze-arch/bot-apiBot API 类型与接口BotAuditInfo、BotInfoAuditData的来源coze-arch/i18n国际化工具I18n.t渲染审核失败文案classnamesCSS 类名工具声明于依赖中供后续样式扩展使用开发期还依赖coze-arch/bot-typings、coze-arch/ts-config、coze-arch/vitest-config、testing-library/react等测试与工程化工具链。总结一条清晰的“审核前端链路”综合本文内容Coze Studio 中一次完整的 Bot 内容审核前端链路可以概括为采集业务表单收集BotAuditInfo中的名称、描述、Prompt、背景图、Agent 等字段提交通过BotInfoAuditPOST /api/playground_api/audit/bot_info或BotInfoCheck发起机审得到BotInfoAuditDatacheck_not_passnot_pass_reasonstarlingKey 列表状态管理UseBotInfoAuditorHook契约管理pass状态check执行审核、setPass更新结果、reset复原bot-audit-base只定义契约bot-audit-adapter提供可替换的默认实现提示审核不通过时渲染AuditErrorMessage /统一展示红色错误文案与指向内容规范的文档链接文案与链接全部支持 i18n 与自定义。对于希望在 Agent IDE 或自己的 Bot 配置面板中接入内容审核的开发者接入路径非常清晰安装coze-studio/bot-audit-base获得组件与类型契约参考bot-audit-adapter实现自己的审核 Hook并在业务组件中按chat-background-config-content的模式根据pass/check_not_pass控制AuditErrorMessage的显隐即可。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考