Omi 插件旧单体Legacy Plugin Monolith的保留决策与迁移治理指南【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本篇技术指南以仓库内 plugins/LEGACY_MONOLITH.md 为核心讲解 OmiFriend插件系统中旧单体 API为何被保留、何时可以删除以及在其退役之前必须遵守的维护规则。读者将掌握plugins/main.py单体的构成与部署链路.github/workflows/gcp_plugins.yml→plugins/Dockerfile→uvicorn main:app、_multion等遗留集成的处置方式、plugins/models.py作为 SDK 兼容层的作用以及如何安全地推进插件服务从单体向独立omi-*-app/服务迁移。背景Omi 插件目录的三类共存形态plugins/目录并非单一应用而是三类事物的混合体这一点在 plugins/README.md 中有明确划分plugins/omi-plugin-sdk/共享 Python SDK当前仅为模型层持有 Omi webhook 负载模型Conversation、TranscriptSegment、ActionItem等plugins/omi-*-app/约 28 个独立服务每个目录都是自包含的 FastAPI 服务拥有自己的main.py、依赖清单与部署描述Dockerfile / Procfile / railway.toml彼此独立部署旧单体Legacy monolithplugins/main.pyplugins/Dockerfile即本指南的主题——一个all-in-one的插件 API 服务目前仅因仍存在 Cloud Run 部署目标而保留。LEGACY_MONOLITH.md正是围绕这第三类事物做出的工程决策记录在插件系统整体向独立服务迁移的过程中旧单体应当保留还是删除、保留期间如何约束演进。它不是一个如何使用插件的指南而是一份架构迁移期的代码治理契约。旧单体是什么plugins/main.py的构成单体的入口是 plugins/main.py它创建一个标题为OMI Plugins API的 FastAPI 应用并聚合挂载了如下路由器basic/下的conversation_created与mentor实时导师逻辑oauth/的conversation_createdzapier/的conversation_createdchatgpt/、subscription/、notifications/hey_omi、iq_rating/_multion/的multion_router——文档点名的最后一个遗留集成。此外main.py中还有一段被注释的ahda实时转写路由以及一段DEPRECATED注释记录了实时REALTIME插件不可行的历史结论每 3 秒运行一次 LLM、一天运行 10 小时的成本过高且未发现 killer 用例。这些注释与文档中的不要向单体添加新业务逻辑形成呼应——单体是冻结态不是演进态。从plugins/_multion/router.py可以看到这类遗留集成典型的耦合形态它直接读取环境变量MULTION_API_KEY默认值123、调用db.store_multion_user_id/db.get_multion_user_id存取用户映射、通过ChatGroq从对话转写中抽取书名再调用https://api.multion.ai/v1/web/browse执行购物车操作。它依赖根目录的db.py、models.py与templates/目录这正是单体的含义——多个集成共享同一个进程、同一套模板与同一份本地状态。为什么不能删除部署链路是硬性阻塞项LEGACY_MONOLITH.md明确指出删除被阻塞的原因.github/workflows/gcp_plugins.yml仍在构建plugins/Dockerfile而该 Dockerfile 从根plugins/包启动uvicorn main:app。这是一个部署即契约的典型场景只要 CI 里还有一个真实存在的部署目标指向它这个代码就不能删。仓库证据链如下.github/workflows/gcp_plugins.yml 是一个仅支持workflow_dispatch手动触发的部署工作流服务名为plugins、区域us-central1其中Build and Push Docker image步骤执行docker build ... -f plugins/Dockerfile .构建后推送至gcr.io/${{ vars.GCP_PROJECT_ID }}/plugins并部署到 Cloud Runplugins/Dockerfile 采用多阶段构建builder 阶段先复制plugins/requirements.txt与plugins/omi-plugin-sdk安装依赖运行阶段COPY plugins/ .后以CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8080]启动且固定监听 8080 端口Cloud Run 默认端口约定。注意COPY plugins/ .的含义它把整个plugins/目录作为工作区根main.py、models.py、db.py、templates/都位于导入路径的顶层——所以main.py中from _multion import router、from basic import conversation_created这类顶层导入才能生效。任何迁移都必须保持这个根包导入结构直到部署目标被替换或移除。Datadog 变体双 Dockerfile 必须对齐仓库同时保留了 plugins/Dockerfile.datadog它与主 Dockerfile 的差异在于基础镜像为官方python:3.11/python:3.11-slim而非 fork 版镜像通过COPY --fromgcr.io/datadoghq/serverless-init:1 /datadog-init /app/datadog-init注入 Datadog serverless init入口改为ENTRYPOINT [/app/datadog-init]命令为ddtrace-run uvicorn main:app --host 0.0.0.0 --port 8080。两套 Dockerfile 共享相同的main:app入口与 8080 端口约定。这解释了LEGACY_MONOLITH.md中最后一条规则——保持plugins/Dockerfile与plugins/Dockerfile.datadog与单体决策对齐任何针对单体的启动方式、目录结构或入口变更都必须同时作用到两个镜像否则观测Datadog 埋点与主部署会产生行为分叉。_mem0的删除先例什么是可以删的遗留代码文档记录了一个已经完成的删除案例plugins/_mem0是 100% 注释掉的示例代码已于 2026-09-03 删除部署目标只要求_multion它仍被挂载在main.py中。这一先例界定了删除的判定标准纯注释示例、无调用方、无部署依赖的代码可以直接清理而仍被main.py挂载、且部署目标仍存在的集成_multion则不能动。结合 plugins/PLUGIN_REFACTOR_AUDIT.md 的补充记录plugins/advanced/等引用也已被删除进一步印证了只有具备活跃部署证据的代码才值得保留的治理原则。plugins/models.pySDK 兼容层的职责LEGACY_MONOLITH.md的第二条规则是保持根目录plugins/models.py作为omi_plugin_sdk.models之上的兼容层。查看 plugins/models.py 可以看到它的实现方式从omi_plugin_sdk.models直接导入并再导出ActionItem、Conversation、ConversationPhoto、EndpointResponse、Event、ExternalIntegrationConversationSource、ExternalIntegrationCreateConversation、Geolocation、PluginResult、Structured、TranscriptSegment等 webhook 模型同时保留单体专属的RealtimePluginRequest、ProactiveNotificationContextFitlersResponse、ProactiveNotificationContextResponse、ProactiveNotificationResponse、ProactiveNotificationEndpointResponse等主动通知模型注意文档原拼写即为此。这种SDK 负责 canonical 模型、单体只保留自身专属类型的分层正是迁移期的关键解耦手段_multion、basic等遗留路由器继续from models import Conversation而底层实现已统一收口到 SDK不会出现多份漂移的Structured定义。SDK 侧模型定义见 plugins/omi-plugin-sdk/src/omi_plugin_sdk/models.py其中Structured、ActionItem、Event、TranscriptSegment、Conversation等模型均带有字段级Field(description...)文档构成了跨所有插件服务共享的契约面。SDK 的安装方式差异依赖装配在不同消费者中路径不同这是迁移时最容易踩坑的点PLUGIN_REFACTOR_AUDIT.md专门将其列为依赖风险旧单体通过 plugins/requirements.txt 以./omi-plugin-sdk相对路径安装Dockerfile 在pip install前先把 SDK 目录COPY进镜像独立omi-*-app/服务各自在自己的requirements.txt中以../omi-plugin-sdk安装要求构建发生在包含 SDK 兄弟目录的仓库 checkout 内。若某个服务被配置为隔离根目录不包含兄弟目录依赖安装就会失败——这是文档明确警告过的风险边界。退役前的四条维护规则LEGACY_MONOLITH.md给出了部署目标退役前的完整规则集这是全文最核心的实操内容规则含义与仓库对应不要向单体添加新的插件业务逻辑新插件应建成独立的omi-*-app/服务main.py中仅保留既有路由挂载DEPRECATED注释区不得复活保持根plugins/models.py作为omi_plugin_sdk.models的兼容层见 plugins/models.py 的再导出结构禁止在单体侧重新实现一套 webhook 模型不删除_multion除非先替换或移除 GCP plugins 部署目标删除顺序必须先解决 .github/workflows/gcp_plugins.yml 指向 plugins/Dockerfile 的构建与 Cloud Run 部署保持plugins/Dockerfile与plugins/Dockerfile.datadog与单体决策对齐两个镜像共享main:app入口与 8080 端口改动必须同步如何安全地退役单体可验证的推进路径基于仓库现有资产退役单体的合规顺序可以归纳为确认无新增业务涌入以 scripts/check_plugin_imports.py 这类导入/契约检查为参考确保所有独立服务在隔离根目录下也能构建其 OpenAPI 契约替换或移除部署目标在.github/workflows/gcp_plugins.yml中删除plugins服务的构建与 Cloud Run 部署步骤或将其指向已迁移完成的独立服务镜像这是解除删除阻塞的唯一硬条件迁移或下线_multion将plugins/_multion/router.py中的对话转写 → 提取书目 → 调用 MultiOn API逻辑迁入独立服务或在确认部署目标移除后整体下线对齐双 Dockerfile确认 plugins/Dockerfile.datadog 不再被任何观测链路依赖后再一并清理清理兼容层当所有消费者都改用omi_plugin_sdk.models后plugins/models.py的再导出层即可随单体一起移除。每一步都应以是否存在活跃部署证据为判定基准——这正是_mem0先例与PLUGIN_REFACTOR_AUDIT.md中未验证部署模式前不做破坏性迁移原则的一致体现。与整体插件重构的关系LEGACY_MONOLITH.md是插件系统重构issue #8559治理体系的一部分建议结合以下文档阅读plugins/PLUGIN_REFACTOR_AUDIT.md重构审计记录包含共享模型面Structured/ActionItem/Event从多份重复收敛为 SDK 单份实现、各部署目标的入口点与 SDK 依赖模式矩阵、以及 backend 镜像因只复制backend/目录而在 backend/models/structured.py 保留本地 fallback 兼容实现的原因plugins/README.md三类目录形态的权威总览以及独立服务不通过plugins/requirements.txt安装 SDK的约束说明。小结LEGACY_MONOLITH.md篇幅虽短却浓缩了一套完整的迁移期代码治理策略以 CI 部署链路为硬约束识别不可删的代码以活跃部署证据为基准判断可删的代码用 SDK 兼容层收敛模型契约用双 Dockerfile 对齐保证观测一致。对于任何正在经历单体 → 微服务重构的团队这份文档的规则集不添加新逻辑、保持兼容层、先替换部署目标再删代码、镜像对齐都是一份可直接借鉴的清单——在本仓库中它就是 Omi 插件系统从旧单体走向 28 个独立服务的过渡期宪法。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Omi 插件旧单体（Legacy Plugin Monolith）的保留决策与迁移治理指南
Omi 插件旧单体Legacy Plugin Monolith的保留决策与迁移治理指南【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend本篇技术指南以仓库内 plugins/LEGACY_MONOLITH.md 为核心讲解 OmiFriend插件系统中旧单体 API为何被保留、何时可以删除以及在其退役之前必须遵守的维护规则。读者将掌握plugins/main.py单体的构成与部署链路.github/workflows/gcp_plugins.yml→plugins/Dockerfile→uvicorn main:app、_multion等遗留集成的处置方式、plugins/models.py作为 SDK 兼容层的作用以及如何安全地推进插件服务从单体向独立omi-*-app/服务迁移。背景Omi 插件目录的三类共存形态plugins/目录并非单一应用而是三类事物的混合体这一点在 plugins/README.md 中有明确划分plugins/omi-plugin-sdk/共享 Python SDK当前仅为模型层持有 Omi webhook 负载模型Conversation、TranscriptSegment、ActionItem等plugins/omi-*-app/约 28 个独立服务每个目录都是自包含的 FastAPI 服务拥有自己的main.py、依赖清单与部署描述Dockerfile / Procfile / railway.toml彼此独立部署旧单体Legacy monolithplugins/main.pyplugins/Dockerfile即本指南的主题——一个all-in-one的插件 API 服务目前仅因仍存在 Cloud Run 部署目标而保留。LEGACY_MONOLITH.md正是围绕这第三类事物做出的工程决策记录在插件系统整体向独立服务迁移的过程中旧单体应当保留还是删除、保留期间如何约束演进。它不是一个如何使用插件的指南而是一份架构迁移期的代码治理契约。旧单体是什么plugins/main.py的构成单体的入口是 plugins/main.py它创建一个标题为OMI Plugins API的 FastAPI 应用并聚合挂载了如下路由器basic/下的conversation_created与mentor实时导师逻辑oauth/的conversation_createdzapier/的conversation_createdchatgpt/、subscription/、notifications/hey_omi、iq_rating/_multion/的multion_router——文档点名的最后一个遗留集成。此外main.py中还有一段被注释的ahda实时转写路由以及一段DEPRECATED注释记录了实时REALTIME插件不可行的历史结论每 3 秒运行一次 LLM、一天运行 10 小时的成本过高且未发现 killer 用例。这些注释与文档中的不要向单体添加新业务逻辑形成呼应——单体是冻结态不是演进态。从plugins/_multion/router.py可以看到这类遗留集成典型的耦合形态它直接读取环境变量MULTION_API_KEY默认值123、调用db.store_multion_user_id/db.get_multion_user_id存取用户映射、通过ChatGroq从对话转写中抽取书名再调用https://api.multion.ai/v1/web/browse执行购物车操作。它依赖根目录的db.py、models.py与templates/目录这正是单体的含义——多个集成共享同一个进程、同一套模板与同一份本地状态。为什么不能删除部署链路是硬性阻塞项LEGACY_MONOLITH.md明确指出删除被阻塞的原因.github/workflows/gcp_plugins.yml仍在构建plugins/Dockerfile而该 Dockerfile 从根plugins/包启动uvicorn main:app。这是一个部署即契约的典型场景只要 CI 里还有一个真实存在的部署目标指向它这个代码就不能删。仓库证据链如下.github/workflows/gcp_plugins.yml 是一个仅支持workflow_dispatch手动触发的部署工作流服务名为plugins、区域us-central1其中Build and Push Docker image步骤执行docker build ... -f plugins/Dockerfile .构建后推送至gcr.io/${{ vars.GCP_PROJECT_ID }}/plugins并部署到 Cloud Runplugins/Dockerfile 采用多阶段构建builder 阶段先复制plugins/requirements.txt与plugins/omi-plugin-sdk安装依赖运行阶段COPY plugins/ .后以CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8080]启动且固定监听 8080 端口Cloud Run 默认端口约定。注意COPY plugins/ .的含义它把整个plugins/目录作为工作区根main.py、models.py、db.py、templates/都位于导入路径的顶层——所以main.py中from _multion import router、from basic import conversation_created这类顶层导入才能生效。任何迁移都必须保持这个根包导入结构直到部署目标被替换或移除。Datadog 变体双 Dockerfile 必须对齐仓库同时保留了 plugins/Dockerfile.datadog它与主 Dockerfile 的差异在于基础镜像为官方python:3.11/python:3.11-slim而非 fork 版镜像通过COPY --fromgcr.io/datadoghq/serverless-init:1 /datadog-init /app/datadog-init注入 Datadog serverless init入口改为ENTRYPOINT [/app/datadog-init]命令为ddtrace-run uvicorn main:app --host 0.0.0.0 --port 8080。两套 Dockerfile 共享相同的main:app入口与 8080 端口约定。这解释了LEGACY_MONOLITH.md中最后一条规则——保持plugins/Dockerfile与plugins/Dockerfile.datadog与单体决策对齐任何针对单体的启动方式、目录结构或入口变更都必须同时作用到两个镜像否则观测Datadog 埋点与主部署会产生行为分叉。_mem0的删除先例什么是可以删的遗留代码文档记录了一个已经完成的删除案例plugins/_mem0是 100% 注释掉的示例代码已于 2026-09-03 删除部署目标只要求_multion它仍被挂载在main.py中。这一先例界定了删除的判定标准纯注释示例、无调用方、无部署依赖的代码可以直接清理而仍被main.py挂载、且部署目标仍存在的集成_multion则不能动。结合 plugins/PLUGIN_REFACTOR_AUDIT.md 的补充记录plugins/advanced/等引用也已被删除进一步印证了只有具备活跃部署证据的代码才值得保留的治理原则。plugins/models.pySDK 兼容层的职责LEGACY_MONOLITH.md的第二条规则是保持根目录plugins/models.py作为omi_plugin_sdk.models之上的兼容层。查看 plugins/models.py 可以看到它的实现方式从omi_plugin_sdk.models直接导入并再导出ActionItem、Conversation、ConversationPhoto、EndpointResponse、Event、ExternalIntegrationConversationSource、ExternalIntegrationCreateConversation、Geolocation、PluginResult、Structured、TranscriptSegment等 webhook 模型同时保留单体专属的RealtimePluginRequest、ProactiveNotificationContextFitlersResponse、ProactiveNotificationContextResponse、ProactiveNotificationResponse、ProactiveNotificationEndpointResponse等主动通知模型注意文档原拼写即为此。这种SDK 负责 canonical 模型、单体只保留自身专属类型的分层正是迁移期的关键解耦手段_multion、basic等遗留路由器继续from models import Conversation而底层实现已统一收口到 SDK不会出现多份漂移的Structured定义。SDK 侧模型定义见 plugins/omi-plugin-sdk/src/omi_plugin_sdk/models.py其中Structured、ActionItem、Event、TranscriptSegment、Conversation等模型均带有字段级Field(description...)文档构成了跨所有插件服务共享的契约面。SDK 的安装方式差异依赖装配在不同消费者中路径不同这是迁移时最容易踩坑的点PLUGIN_REFACTOR_AUDIT.md专门将其列为依赖风险旧单体通过 plugins/requirements.txt 以./omi-plugin-sdk相对路径安装Dockerfile 在pip install前先把 SDK 目录COPY进镜像独立omi-*-app/服务各自在自己的requirements.txt中以../omi-plugin-sdk安装要求构建发生在包含 SDK 兄弟目录的仓库 checkout 内。若某个服务被配置为隔离根目录不包含兄弟目录依赖安装就会失败——这是文档明确警告过的风险边界。退役前的四条维护规则LEGACY_MONOLITH.md给出了部署目标退役前的完整规则集这是全文最核心的实操内容规则含义与仓库对应不要向单体添加新的插件业务逻辑新插件应建成独立的omi-*-app/服务main.py中仅保留既有路由挂载DEPRECATED注释区不得复活保持根plugins/models.py作为omi_plugin_sdk.models的兼容层见 plugins/models.py 的再导出结构禁止在单体侧重新实现一套 webhook 模型不删除_multion除非先替换或移除 GCP plugins 部署目标删除顺序必须先解决 .github/workflows/gcp_plugins.yml 指向 plugins/Dockerfile 的构建与 Cloud Run 部署保持plugins/Dockerfile与plugins/Dockerfile.datadog与单体决策对齐两个镜像共享main:app入口与 8080 端口改动必须同步如何安全地退役单体可验证的推进路径基于仓库现有资产退役单体的合规顺序可以归纳为确认无新增业务涌入以 scripts/check_plugin_imports.py 这类导入/契约检查为参考确保所有独立服务在隔离根目录下也能构建其 OpenAPI 契约替换或移除部署目标在.github/workflows/gcp_plugins.yml中删除plugins服务的构建与 Cloud Run 部署步骤或将其指向已迁移完成的独立服务镜像这是解除删除阻塞的唯一硬条件迁移或下线_multion将plugins/_multion/router.py中的对话转写 → 提取书目 → 调用 MultiOn API逻辑迁入独立服务或在确认部署目标移除后整体下线对齐双 Dockerfile确认 plugins/Dockerfile.datadog 不再被任何观测链路依赖后再一并清理清理兼容层当所有消费者都改用omi_plugin_sdk.models后plugins/models.py的再导出层即可随单体一起移除。每一步都应以是否存在活跃部署证据为判定基准——这正是_mem0先例与PLUGIN_REFACTOR_AUDIT.md中未验证部署模式前不做破坏性迁移原则的一致体现。与整体插件重构的关系LEGACY_MONOLITH.md是插件系统重构issue #8559治理体系的一部分建议结合以下文档阅读plugins/PLUGIN_REFACTOR_AUDIT.md重构审计记录包含共享模型面Structured/ActionItem/Event从多份重复收敛为 SDK 单份实现、各部署目标的入口点与 SDK 依赖模式矩阵、以及 backend 镜像因只复制backend/目录而在 backend/models/structured.py 保留本地 fallback 兼容实现的原因plugins/README.md三类目录形态的权威总览以及独立服务不通过plugins/requirements.txt安装 SDK的约束说明。小结LEGACY_MONOLITH.md篇幅虽短却浓缩了一套完整的迁移期代码治理策略以 CI 部署链路为硬约束识别不可删的代码以活跃部署证据为基准判断可删的代码用 SDK 兼容层收敛模型契约用双 Dockerfile 对齐保证观测一致。对于任何正在经历单体 → 微服务重构的团队这份文档的规则集不添加新逻辑、保持兼容层、先替换部署目标再删代码、镜像对齐都是一份可直接借鉴的清单——在本仓库中它就是 Omi 插件系统从旧单体走向 28 个独立服务的过渡期宪法。【免费下载链接】FriendAI that sees your screen, listens to your conversations and tells you what to do项目地址: https://gitcode.com/GitHub_Trending/fr/Friend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考