ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Operit 角色卡软件设置管理接口:源码复核与交付全流程指南

Operit 角色卡软件设置管理接口:源码复核与交付全流程指南 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/系列文档为骨架完整还原角色卡配置管理接口从原生工具、JavaScript 桥、TypeScript 声明到 Operit Editor 包的全链路源码复核方法与交付标准。读者可据此掌握一套可复用的不改动任何编译构建的前提下通过纯源码检查验证跨层接口一致性的验收流程并深入理解 Operit 角色卡系统的字段边界与工具注册机制。任务背景脚本侧角色卡管理能力的补全在本次改造之前Operit 的角色卡能力存在明显的不对称原生侧CharacterCardManager早已支持角色卡的读取、创建、更新、删除、激活以及酒馆TavernJSON 的导入与导出详情可参考 1_NativeCharacterCardTools.md但脚本侧只有一个Tools.Chat.listCharacterCards()其返回内容仅用于会话选卡既缺少完整字段也没有任何管理操作Tools.SoftwareSettings与operit_editor均不能管理角色卡。因此本次任务的目标非常明确在Tools.SoftwareSettings上补齐角色卡的列表、详情、创建、更新、删除、激活与清除活跃状态接口并提供单张角色卡的酒馆 JSON 导入/导出接口同时通过 JavaScript 桥、TypeScript 声明和operit_editor三层暴露全部接口且继续保留Tools.Chat.listCharacterCards()让既有会话工具保持原有调用方式不变见 index.md。接口边界与职责划分改造遵循清晰的职责边界SoftwareSettings负责角色卡配置本身——所有读写、激活、导入导出操作都归属此处Chat只在创建会话或发送消息时引用角色卡不做配置管理写入接口只接受可编辑字段。角色卡 ID、创建时间以及默认角色卡属性由角色卡管理器维护调用方不能通过更新接口改变它们。复核检查项五查清单交付前的源码复核围绕五个检查项展开每一条都对应一个可验证的工程事实见 3_VerificationAndDelivery.md#检查项验证对象1原生工具注册名、软件设置执行器和 JavaScript 桥一一对应ToolRegistration.kt、StandardSoftwareSettingsModifyTools.kt、JsTools.kt2TypeScript 参数和结果类型与原生字段一致examples/types/software_settings.d.ts3operit_editor.ts的工具定义、参数校验和调用覆盖全部角色卡接口examples/operit_editor.ts4JavaScript 产物与应用内置副本同步examples/operit_editor.js与app/src/main/assets/packages/operit_editor.js5现有Tools.Chat.listCharacterCards()继续保留JsTools.kt中的 Chat 桥与ToolRegistration.kt中的list_character_cards检查项 1注册名—执行器—JS 桥三层一一对应角色卡管理共新增9 个原生工具在 ToolRegistration.kt 中通过handler.registerTool(...)逐一注册全部委托给StandardSoftwareSettingsModifyTools中对应的 suspend 方法并统一用runBlocking(Dispatchers.IO)执行。逐层映射关系如下原生工具注册名执行器方法StandardSoftwareSettingsModifyToolsJavaScript 桥方法JsTools.ktlist_character_cards_settingslistCharacterCards(tool)Tools.SoftwareSettings.listCharacterCards()get_character_cardgetCharacterCard(tool)Tools.SoftwareSettings.getCharacterCard(characterCardId)create_character_cardcreateCharacterCard(tool)Tools.SoftwareSettings.createCharacterCard(options)update_character_cardupdateCharacterCard(tool)Tools.SoftwareSettings.updateCharacterCard(characterCardId, updates)delete_character_carddeleteCharacterCard(tool)Tools.SoftwareSettings.deleteCharacterCard(characterCardId)set_active_character_cardsetActiveCharacterCard(tool)Tools.SoftwareSettings.setActiveCharacterCard(characterCardId)clear_active_character_cardclearActiveCharacterCard(tool)Tools.SoftwareSettings.clearActiveCharacterCard()import_character_card_from_tavern_jsonimportCharacterCardFromTavernJson(tool)Tools.SoftwareSettings.importCharacterCardFromTavernJson(tavernJson)export_character_card_to_tavern_jsonexportCharacterCardToTavernJson(tool)Tools.SoftwareSettings.exportCharacterCardToTavernJson(characterCardId)在 JsTools.kt 中每个桥方法内部都通过toolCall(原生注册名, params)发起到原生工具的执行同时第 1589 行附近的Tools.Chat.listCharacterCards依然映射到旧的list_character_cards工具保证会话侧调用方式不变。检查项 2TypeScript 声明与原生字段一致examples/types/software_settings.d.ts 为全部 9 个桥方法补充了严格的输入/输出类型输入侧定义了CharacterCardWriteOptions可编辑字段集合以及CharacterCardChatModelBindingMode FOLLOW_GLOBAL | FIXED_CONFIG、CharacterCardMemoryProfileBindingMode FOLLOW_GLOBAL | FIXED_PROFILE两个枚举输出侧引入了CharacterCardsResultData、CharacterCardResultData、CharacterCardCreateResultData、CharacterCardUpdateResultData、CharacterCardDeleteResultData、CharacterCardActivationResultData、CharacterCardImportResultData、CharacterCardExportResultData等结构化结果类型。这些类型名与原生 Kotlin 侧com.ai.assistance.operit.core.tools包下的CharacterCardResultData、CharacterCardResultItem、CharacterCardsResultData等一一对应见 StandardSoftwareSettingsModifyTools.kt 的 import 列表从而保证脚本端类型声明 ↔ 原生结果字段的一致性可静态核对。检查项 3operit_editor.ts全接口覆盖examples/operit_editor.ts 是编辑器的 TypeScript 源文件角色卡工具以元数据声明 实现函数 导出三段式组织工具元数据name/description/parameters定义约第 2014 行起list_character_cards无参数get_character_card、update_character_card、delete_character_card、set_active_character_card、export_character_card_to_tavern_json均要求必填character_card_idimport_character_card_from_tavern_json要求必填tavern_jsoncreate_character_card的name必填实现函数第 4165 行起定义了list_character_cards、get_character_card、create_character_card、update_character_card、delete_character_card、set_active_character_card、clear_active_character_card、import_character_card_from_tavern_json、export_character_card_to_tavern_json共 9 个函数内部做参数 trim 与缺失校验后调用Tools.SoftwareSettings.*并用统一的complete_character_card_error包装异常包导出文件末尾将 9 个函数挂到operitEditorPackage并exports.*导出供脚本包直接调用。检查项 4JavaScript 产物与应用内置副本同步角色卡工具的同步范围明确为三个文件且契约必须一致examples/operit_editor.ts—— 编辑器源文件examples/operit_editor.js—— 其 JavaScript 编译产物app/src/main/assets/packages/operit_editor.js—— 应用内置的包副本。本次交付记录确认examples/operit_editor.js与app/src/main/assets/packages/operit_editor.js的哈希一致即产物与应用内置副本完全同步同时git diff --check未报告空白错误说明提交内容干净、无尾随空格等格式污染。检查项 5Tools.Chat.listCharacterCards()保留作为向后兼容的硬性要求旧接口没有删除ToolRegistration.kt第 1738 行仍注册list_character_cards工具并委托chatManagerTool.listCharacterCards(tool)JsTools.kt第 1589 行仍将Tools.Chat.listCharacterCards映射到该工具。新增的list_character_cards_settings与旧list_character_cards是两个独立工具前者返回完整配置含活跃角色卡 ID后者维持会话选卡语义。执行限制与验证手段本次交付不运行编译、构建或测试命令验证完全基于静态手段包括四类源码检查阅读原生执行器、注册表、JS 桥源码核对方法名与参数接口映射审查逐个核对注册名 → 执行器 → 桥方法 → 类型声明 → editor 工具五层映射产物同步检查比对examples/operit_editor.js与内置副本的哈希Git diff 审查用git diff --check检查空白错误确保交付 diff 干净。这种无编译验证方式的可行性前提是接口数量与名称在五层之间完全一致而结构化结果类型在 Kotlin 与 TypeScript 两侧字段对齐——这两点恰恰是上面五查清单要证明的结论。源码纵深原生 API 契约与字段边界结构化结果类型9 个原生工具全部返回结构化结果数据而非裸字符串便于脚本端直接消费。各结果类型的关键字段如下结果类型关键字段CharacterCardsResultDatatotalCount、activeCharacterCardId、cardsCharacterCardResultDatacard、activeCharacterCardIdCharacterCardCreateResultDatacreated、card、activeCharacterCardId、changedFieldsCharacterCardUpdateResultDataupdated、card、activeCharacterCardId、changedFieldsCharacterCardDeleteResultDatadeleted、characterCardId、activeCharacterCardIdCharacterCardActivationResultDataactiveCharacterCardIdCharacterCardImportResultDataimported、card、activeCharacterCardIdCharacterCardExportResultDatacharacterCardId、tavernJson单张卡的完整字段由CharacterCardResultItem承载见 StandardSoftwareSettingsModifyTools.ktid、name、description、characterSetting、openingStatement、otherContentChat、otherContentVoice、attachedTagIds、advancedCustomPrompt、marks、chatModelBindingMode、chatModelConfigId、chatModelIndex、memoryProfileBindingMode、memoryProfileId、toolAccessConfig内含enabled与allowedBuiltinTools/allowedPackages/allowedSkills/allowedMcpServers四个白名单数组、isDefault、createdAt、updatedAt。可编辑字段与受保护字段applyCharacterCardUpdates第 1937 行起集中定义了写入接口可接受的字段集合并实现合并式更新仅修改传入字段未传字段保持原值同时记录changedFields供结果回显类别字段文本字段name创建必填、不可为空白、description、character_setting、opening_statement、other_content_chat、other_content_voice、advanced_custom_prompt、marks数组字段attached_tag_ids、allowed_builtin_tools、allowed_packages、allowed_skills、allowed_mcp_servers均要求 JSON 字符串数组模型绑定字段chat_model_binding_modeFOLLOW_GLOBAL/FIXED_CONFIG、chat_model_config_id、chat_model_index≥0 整数记忆绑定字段memory_profile_binding_modeFOLLOW_GLOBAL/FIXED_PROFILE、memory_profile_id工具白名单字段tool_access_enabled布尔、上述四个allowed_*数组与之相对的受保护字段——id、createdAt、isDefault——由 CharacterCardManager.kt 统一维护创建时若卡片非默认则由管理器生成UUID.randomUUID().toString()作为 ID第 416 行调用方无法通过更新接口修改这些字段。行为约束delete_character_card拒绝删除默认角色卡DEFAULT_CHARACTER_CARD_ID default_character删除它直接返回错误The default character card cannot be deleted第 1622-1629 行get、update、delete、set_active、export等操作前先通过requireCharacterCard校验卡片存在不存在即抛IllegalArgumentException(Character card not found: ...)Tavern JSON 导入导出复用CharacterCardManager既有转换逻辑createCharacterCardFromTavernJson/exportCharacterCardToTavernJson失败时以Result的 failure 分支透传错误所有 9 个工具共用既有管理器确保主题、Waifu 设置、自定义表情、聊天绑定和提示词标签的副作用仍由单一实现处理不会因新增脚本接口而引入第二套写入路径。交付结论复核确认原生注册名、JavaScript 桥、TypeScript 声明与 editor 的接口数量与名称完全一致examples/operit_editor.js与app/src/main/assets/packages/operit_editor.js产物同步git diff --check无空白错误Tools.Chat.listCharacterCards()完整保留。至此Operit 角色卡完成了配置管理能力的全链路打通原生层以StandardSoftwareSettingsModifyTools为执行器并通过ToolRegistration暴露 9 个工具脚本层以Tools.SoftwareSettings桥方法 software_settings.d.ts强类型声明承接编辑器层以operit_editor包向用户脚本提供同名的 9 个可调用函数。任何想要在脚本中管理角色卡的开发者都可以直接从Tools.SoftwareSettings.listCharacterCards()开始逐步熟悉完整的读写、激活与 Tavern JSON 交换能力。赞分享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 聊天角色卡 UUID 绑定回退从 characterCardId 恢复 characterCardName 的源码复核与交付指南Operit 聊天角色卡 UUID 绑定回退从 characterCardId 恢复 characterCardName 的源码复核与交付指南 本文以 OpeAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 原生角色卡管理工具SoftwareSettings 角色卡完整管理接口的实现与脚本接入指南Operit 原生角色卡管理工具SoftwareSettings 角色卡完整管理接口的实现与脚本接入指南 本文以 Operit 仓库 docs/TODO/chAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化Operit 角色卡脚本接口全解析Tools.SoftwareSettings 九大管理工具与 Operit Editor 的同步实现Operit 角色卡脚本接口全解析Tools.SoftwareSettings 九大管理工具与 Operit Editor 的同步实现 本文基于 OperitAI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆GUI 自动化创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表