AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载本文以 Operit 仓库 docs/TODO/character_card_software_settings_20260805 系列文档为主线系统讲解 Operit 如何把角色卡Character Card的完整管理能力下沉到原生层并以Tools.SoftwareSettings的形式开放给脚本与 AI Agent 使用。读完本文你将掌握九个角色卡原生工具的名称、参数、返回值与字段边界理解 JavaScript 桥、TypeScript 声明与 Operit Editor 三者的同步契约并能直接编写脚本完成角色卡的列出、详情、创建、更新、删除、激活以及酒馆 JSON 导入导出。背景角色卡在 Operit 中的定位与旧实现的局限角色卡是 Operit 会话人格的核心载体承载角色的描述、开场白、聊天/语音附加内容、绑定的模型配置与记忆档案以及工具访问白名单等完整配置。在本次改造之前角色卡存在一个明显的断层底层管理器CharacterCardManager已经具备角色卡的读取、创建、更新、删除、激活以及酒馆 JSONTavern JSON导入导出能力但脚本侧只有Tools.Chat.listCharacterCards()一个只读方法其返回内容仅用于创建会话时的选卡缺少完整字段与管理操作Tools.SoftwareSettings与operit_editor均无法管理角色卡角色卡主要由设置 UI 消费。这意味着 AI Agent 或第三方脚本无法通过工具调用完成创建一张新卡、编辑人格设定、切换当前活跃卡、把卡片导出为酒馆 JSON这类操作管理能力被 UI 独占。本次改造的目标正是把CharacterCardManager的能力通过原生工具、JavaScript 桥与编辑器三层完整暴露出来。九个原生工具完整 API 契约改造的核心动作是在StandardSoftwareSettingsModifyTools中直接调用CharacterCardManager并由ToolRegistration注册对应原生工具同时新增结构化结果类型完整传递角色卡的配置字段与当前活跃角色卡 ID。完整的工具清单如下原生工具名语义关键参数返回内容list_character_cards_settings列出全部角色卡与活跃卡 ID无totalCount、activeCharacterCardId、cards[]get_character_card获取指定角色卡character_card_id单张卡片 activeCharacterCardIdcreate_character_card创建角色卡只接受可编辑字段name必填 可编辑字段created、card、activeCharacterCardId、changedFieldsupdate_character_card合并更新指定可编辑字段character_card_id 可编辑字段updated、card、activeCharacterCardId、changedFieldsdelete_character_card删除非默认角色卡character_card_iddeleted、characterCardId、activeCharacterCardIdset_active_character_card设置当前活跃角色卡character_card_idactiveCharacterCardIdclear_active_character_card清除活跃角色卡无activeCharacterCardId nullimport_character_card_from_tavern_json从酒馆 JSON 导入一张卡tavern_jsonimported、card、activeCharacterCardIdexport_character_card_to_tavern_json导出指定卡为酒馆 JSONcharacter_card_idcharacterCardId、tavernJson这九个工具的注册集中在 app/src/main/java/com/ai/assistance/operit/core/tools/ToolRegistration.kt每个工具都通过handler.registerTool注册executor统一从ToolGetter.getSoftwareSettingsModifyTools(context)获取执行器并在Dispatchers.IO上运行。例如create_character_card的描述生成器会动态拼出Create character card: nameget_character_card则拼出Get character card settings: id方便模型在工具调用时直接理解上下文。实现细节每个工具的执行器做了什么执行器实现位于 StandardSoftwareSettingsModifyTools.kt几个关键行为可以从源码确认列表listCharacterCards调用CharacterCardManager.getInstance(context).getAllCharacterCards()后逐张映射为CharacterCardResultItem同时通过observeActiveCharacterCardId().first()读取当前活跃卡 ID。映射后的条目包含id、name、description、characterSetting、openingStatement、otherContentChat、otherContentVoice、attachedTagIds、advancedCustomPrompt、marks、模型/记忆绑定字段、toolAccessConfig以及isDefault、createdAt、updatedAt。详情getCharacterCardcharacter_card_id缺失时返回Missing required parameter: character_card_id卡片不存在时抛出Character card not found: id。创建createCharacterCard以CharacterCard(id , name )为底稿要求name必填且不能为空白其余可编辑字段按需叠加随后由管理器分配 ID 并持久化。更新updateCharacterCard先按 ID 取出当前卡仅合并调用方传入的字段如果没有任何字段变更会直接报错At least one character card update field is required避免空操作。删除deleteCharacterCard默认卡default_character不可删除源码中对此有显式拦截The default character card cannot be deleted。导入/导出Tavern JSON分别委托CharacterCardManager.createCharacterCardFromTavernJson(tavernJson)与exportCharacterCardToTavernJson(id)失败路径会返回Result中的异常信息成功路径返回完整卡片或 JSON 字符串。字段边界哪些可写哪些由管理器维护SoftwareSettings负责角色卡配置本身Chat只在创建会话或发送消息时引用角色卡。更重要的是写入接口只接受可编辑字段角色卡 ID、创建时间、默认角色卡属性由CharacterCardManager维护调用方无法通过更新接口改变它们。这一点在 index.md 中被明确为接口边界。可编辑字段即CharacterCardWriteOptions定义于 examples/types/software_settings.d.ts字段类型说明namestring创建时必填更新时可选descriptionstring角色简介character_settingstring角色设定人格描述opening_statementstring开场白other_content_chatstring聊天附加内容other_content_voicestring语音附加内容advanced_custom_promptstring高级自定义提示词marksstring标记/备注attached_tag_idsstring \| string[]关联标签 ID支持字符串数组或其 JSON 字符串表示chat_model_binding_modeFOLLOW_GLOBAL \| FIXED_CONFIG会话模型绑定模式chat_model_config_idstring绑定的模型配置 ID空字符串清除绑定chat_model_indexnumber绑定模型在配置中的索引须大于等于 0memory_profile_binding_modeFOLLOW_GLOBAL \| FIXED_PROFILE记忆档案绑定模式memory_profile_idstring绑定的记忆档案 ID空字符串清除绑定tool_access_enabledboolean是否启用该卡的工具访问控制allowed_builtin_toolsstring \| string[]允许的内置工具白名单allowed_packagesstring \| string[]允许的沙箱包白名单allowed_skillsstring \| string[]允许的技能白名单allowed_mcp_serversstring \| string[]允许的 MCP 服务器白名单从 StandardSoftwareSettingsModifyTools.kt 的applyCharacterCardUpdates实现可以看到字段校验的细节布尔参数tool_access_enabled复用parseBooleanParameter接受1/true/yes/y/on与0/false/no/n/off的宽松写法字符串数组参数attached_tag_ids、allowed_*通过parseStringArrayParameter解析必须是合法 JSON 数组且每个元素为字符串解析后自动去重、剔除空项chat_model_binding_mode与memory_profile_binding_mode只接受各自枚举的两个取值其余值直接抛Invalid ... mode异常chat_model_index必须是整数且 0所有数组/绑定白名单在写入前会经过normalized()处理保证存储形态一致。原生层设计单一实现副作用不分散文档明确要求角色卡工具使用既有管理器确保主题、Waifu 设置、自定义表情、聊天绑定和提示词标签的副作用仍由单一实现处理。 这意味着工具层只做参数解析、校验与结果映射所有副作用如切换活跃卡时联动切换 Waifu 设置、头像、提示词标签、模型绑定刷新都收敛在CharacterCardManager内部。这一设计在 CharacterCardManager.kt 中可以得到印证DEFAULT_CHARACTER_CARD_ID default_character第 96 行createCharacterCard为非默认卡分配UUID.randomUUID()setActiveCharacterCard/clearActiveCharacterCard会同步处理活跃状态与关联的 Waifu、头像等衍生数据删除活跃卡后活跃状态会回落到默认卡。工具层绝不复制这套副作用逻辑。脚本层JavaScript 桥与调用方式原生工具通过 app/src/main/java/com/ai/assistance/operit/core/tools/javascript/JsTools.kt 暴露为Tools.SoftwareSettings的方法方法名与原生工具一一对应// 列出全部角色卡与活跃卡 ID Tools.SoftwareSettings.listCharacterCards(); // 获取指定角色卡 Tools.SoftwareSettings.getCharacterCard(characterCardId); // 创建角色卡options 中 name 必填 Tools.SoftwareSettings.createCharacterCard({ name: 新角色, description: ... }); // 合并更新第二个参数只传要改的字段 Tools.SoftwareSettings.updateCharacterCard(characterCardId, { marks: v2 }); // 删除非默认卡 Tools.SoftwareSettings.deleteCharacterCard(characterCardId); // 激活 / 清除活跃卡 Tools.SoftwareSettings.setActiveCharacterCard(characterCardId); Tools.SoftwareSettings.clearActiveCharacterCard(); // 酒馆 JSON 导入 / 导出 Tools.SoftwareSettings.importCharacterCardFromTavernJson(tavernJson); Tools.SoftwareSettings.exportCharacterCardToTavernJson(characterCardId);桥层实现为toolCall(get_character_card, { character_card_id: characterCardId })这类透传调用把 JS 参数原样映射为原生工具的parameters。值得注意的是会话工具Tools.Chat.listCharacterCards()对应list_character_cards继续保留会话选卡场景的既有调用方式不受影响这与 index.md 中继续保留Tools.Chat.listCharacterCards()的预期结果一致。TypeScript 声明严格类型约束类型声明位于 examples/types/software_settings.d.ts为输入输出提供严格类型两个绑定模式枚举CharacterCardChatModelBindingMode FOLLOW_GLOBAL | FIXED_CONFIG、CharacterCardMemoryProfileBindingMode FOLLOW_GLOBAL | FIXED_PROFILECharacterCardWriteOptions覆盖全部可编辑字段见上文字段表九个方法均返回带Promise的结构化结果类型CharacterCardsResultData、CharacterCardResultData、CharacterCardCreateResultData、CharacterCardUpdateResultData、CharacterCardDeleteResultData、CharacterCardActivationResultData、CharacterCardImportResultData、CharacterCardExportResultData。例如创建接口的签名是createCharacterCard(options: CharacterCardWriteOptions { name: string }): PromiseCharacterCardCreateResultData在类型层强制name必填更新接口则是updateCharacterCard(characterCardId: string, updates: CharacterCardWriteOptions)对应原生实现的合并语义。Operit Editor九个角色卡管理工具的注册脚本侧之外operit_editor也同步注册了九个角色卡管理工具形成包内可调用的管理能力。同步范围在 2_ScriptApiAndOperitEditor.md 中被明确为三个文件契约必须一致examples/operit_editor.ts编辑器源文件examples/operit_editor.js其 JavaScript 产物app/src/main/assets/packages/operit_editor.js内置包副本。editor 侧同样覆盖列卡、详情、创建、更新、删除、激活、清除活跃、导入、导出九个工具且元数据统一使用 JSON 字符串数组来表示数组参数如attached_tag_ids、allowed_builtin_tools等与原生parseStringArrayParameter的解析约定对齐。数组参数的两种写法约定文档特别强调数组参数支持 string array 及其 JSON 字符串表示editor 元数据统一使用 JSON 字符串数组。 也就是说在脚本与 editor 层同一个数组字段有两种等价写法// 写法一直接传字符串数组 Tools.SoftwareSettings.updateCharacterCard(id, { allowed_packages: [worldbook, deepsearching] }); // 写法二传 JSON 字符串editor 元数据统一采用此形态 Tools.SoftwareSettings.updateCharacterCard(id, { allowed_packages: [worldbook, deepsearching] });原生parseStringArrayParameter对二者统一处理JSON 数组逐元素校验为字符串、去空、去重后再持久化。源码复核与交付检查交付环节3_VerificationAndDelivery.md围绕五个检查项完成静态复核不执行编译、构建或测试命令原生工具注册名、软件设置执行器和 JavaScript 桥一一对应ToolRegistration 九个名字 ↔StandardSoftwareSettingsModifyTools九个方法 ↔ JsTools 九个桥方法TypeScript 参数和结果类型与原生字段一致operit_editor.ts的工具定义、参数校验和调用覆盖全部角色卡接口JavaScript 产物与应用内置副本同步examples/operit_editor.js与app/src/main/assets/packages/operit_editor.js哈希一致git diff --check无空白错误现有Tools.Chat.listCharacterCards()继续保留。复核确认了原生注册名、JavaScript 桥、TypeScript 声明和 editor 的接口数量与名称完全一致工具注册、JavaScript 桥、类型声明和 editor 入口四条链路闭环。小结从 UI 独占到工具开放本次改造把角色卡从UI 独占、脚本只读升级为原生工具 JavaScript 桥 TypeScript 声明 Operit Editor四层完整开放的配置管理接口原生层由StandardSoftwareSettingsModifyTools承载九个工具ToolRegistration注册CharacterCardManager作为唯一副作用实现脚本层以Tools.SoftwareSettings九个方法提供完整增删改查与激活/导入导出能力会话层Tools.Chat.listCharacterCards()保持兼容类型层用CharacterCardWriteOptions与九个结构化结果类型约束输入输出编辑器层同步注册九个工具三份产物契约一致。对开发者而言这意味着任何沙箱脚本、toolpkg 包或 AI Agent 都可以在运行期以结构化数据驱动角色卡全生命周期管理——从批量整理卡片、按规则切换活跃角色到跨设备以酒馆 JSON 迁移人格设定都不再需要依赖人工在设置 UI 中逐项操作。相关文档与代码可继续参阅 任务总览、原生实现 与 类型声明。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐Operit 角色卡全量管理接口落地实录SoftwareSettings 原生工具、JavaScript 桥与 Operit Editor 三端打通Operit 角色卡全量管理接口落地实录SoftwareSettings 原生工具、JavaScript 桥与 Operit Editor 三端打通 本指南围AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化独角数卡(dujiaoka)用户权限系统RBAC模型与多角色管理完整指南独角数卡 dujiaoka 用户权限系统RBAC模型与多角色管理完整指南 独角数卡 dujiaoka 作为开源站长自动化售货解决方案其用户权限系统采用了灵活后端电商laravel-permission 角色与权限实战指南从角色分配、角色侧批量管理到直接权限判定laravel permission 角色与权限实战指南从角色分配、角色侧批量管理到直接权限判定 本指南聚焦 spatie/laravel permissio后端认证鉴权创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
