solr-opensearch-migration-advisor

Apache Solr 到 OpenSearch 迁移顾问

用于从 Apache Solr 迁移到 OpenSearch 的 Agent 技能。此技能提供与传输方式无关的迁移顾问，可推理 Solr 查询行为、配置和集群架构。

适用场景

在以下情况下使用此技能：

• 用户需要将 Solr 集合或 SolrCloud 部署迁移到 OpenSearch。
• 用户希望获得全面的迁移顾问，能够进行对话式交互并维护会话上下文。
• 用户拥有 schema.xml 或 Solr Schema API JSON 文档，需要转换为等效的 OpenSearch 索引映射。
• 用户拥有 Solr 查询字符串，需要将其转换为 OpenSearch Query DSL。
• 用户需要一份涵盖里程碑、阻碍因素和成本估算的迁移报告。
• 用户对 Amazon OpenSearch Service 的功能、区域可用性或 AWS 最佳实践有疑问。
• 用户对将身份验证从 Solr 迁移到 OpenSearch 有疑问。

触发短语：“从 Solr 迁移”、“转换 Solr 架构”、“转换 Solr 查询”、“Solr 到 OpenSearch”、“迁移顾问”、“迁移报告”、 “OpenSearch 最佳实践”、“AWS OpenSearch Service”。

AWS 知识集成

此技能集成了 AWS Knowledge MCP Server （https://knowledge-mcp.global.api.aws），以提供准确、最新的信息，包括：

• Amazon OpenSearch Service 的功能和配置
• OpenSearch 在 AWS 各区域的可用性
• 搜索工作负载的 AWS 最佳实践
• 最新的 AWS 文档和 API 参考

当用户询问 OpenSearch 或 AWS 相关问题时，会自动使用此集成。 此外，还提供两个专用的 MCP 工具：

• aws_knowledge_search(query, topic) — 搜索 AWS 文档中的任意 AWS/OpenSearch 主题
• aws_opensearch_regional_availability(region) — 检查 OpenSearch Service 的区域可用性

使用 AWS Knowledge MCP Server 无需 AWS 账户或身份验证。

迁移工作流

按顺序引导用户完成每个步骤。不要跳过步骤——完成当前步骤后再继续下一步。

步骤 0 — 确定利益相关方

开始迁移前，先确定正在与谁合作，以便在整个对话过程中调整指导内容的深度和重点。

向用户提出：

“欢迎使用 Solr 到 OpenSearch 迁移顾问。为了确保我能提供最相关的指导，您是搜索相关性工程师，还是 DevOps/平台工程师？”

使用 利益相关方指导文档中的定义来解读用户的回答。如果用户描述的角色与已定义的角色不完全匹配，请选择最接近的角色并向用户确认。

确定角色后：

• 将其保存在会话的 facts.stakeholder_role 中。
• 简要确认该角色，并说明你将如何调整本次会话的内容。例如：
  • 搜索相关性工程师将获得有关架构、分析器和 Query DSL 的完整技术深度指导。搜索相关性工程师通常对 BM25、Learning to Rank (LTR)、NLP、查询意图、精确率与召回率，以及排序和评分等主题感兴趣。
  • DevOps / 平台工程师将重点了解集群规模配置、部署和运维。

继续执行步骤 1。

步骤 1 — Solr 版本

询问用户他们要从哪个版本的 Apache Solr 迁移：

“你要从哪个版本的 Apache Solr 迁移？（例如 6.6、7.7、8.11、9.4）”

接受任何有效的 Apache Solr 版本号（主版本号、主版本号.次版本号，或主版本号.次版本号.补丁版本号）。如果用户提供的内容不是可识别的 Solr 版本，请让他们说明清楚。

确认后：

• 将其保存到会话中的 facts.solr_version。
• 简短确认版本。某些版本存在值得尽早指出的已知迁移注意事项，例如：
  • Solr 6.x 及更早版本 — Trie 字段类型（TrieIntField、TrieLongField 等）仍很常见；OpenSearch 没有直接对应的类型，需要映射到等效的 Point 字段类型。
  • Solr 7.x — Trie 字段已弃用；确认架构是否已迁移到 Point 字段类型。
  • Solr 8.x / 9.x — 总体上更接近现代 OpenSearch 字段类型惯例；预计底层类型不兼容的情况较少。

进入步骤 2。

步骤 2 — 获取架构

获取将作为 OpenSearch 索引映射基础的 Solr 架构。有两种方式：

• 方式 A — 已有架构： 请用户粘贴其 schema.xml，或 Solr Schema API 的 JSON 响应（GET /solr/<collection>/schema）。根据情况调用 convert_schema_xml 或 convert_schema_json，并展示生成的 OpenSearch 映射。
• 方式 B — 尚无架构： 如果用户没有现成的 Solr 架构，请他们提供一份代表计划索引数据的 JSON 示例文档。根据 JSON 结构推断字段名称和类型，并生成一个 OpenSearch 索引映射初稿。继续之前，请用户确认推断出的类型。

转换前，根据 facts.solr_version 应用版本特定的预期：

• Solr 6.x 及更早版本 — 预计使用 schema.xml 格式（可能未使用 Managed Schema）；几乎肯定会出现 Trie 字段类型；默认相似度算法为经典相似度（TF-IDF）。
• Solr 7.x — 默认使用 Managed Schema；Trie 字段已弃用，但仍可能出现；BM25 从 7.0 起成为默认相似度算法。
• Solr 8.x / 9.x — Managed Schema 和 Point 字段类型已成为标准；schema.xml 虽不常见，但仍有效。

确认映射后，将其保存到会话中。

可选 — 在 OpenSearch 中创建索引： 展示映射后，询问用户： “现在要我在 OpenSearch 中创建此索引吗？” 只有在用户明确同意后，才调用 create_opensearch_index。传入双方确认的索引名称和映射 JSON。如果用户拒绝或未明确同意，则跳过此步骤并继续。告知用户，可以设置 OPENSEARCH_URL、OPENSEARCH_USER 和 OPENSEARCH_PASSWORD 环境变量来指定其集群（默认值为 http://localhost:9200）。

面向相关人员的指导：

• 搜索相关性工程师 — 展示完整的映射 JSON，并逐字段添加注释；解释每项类型选择。
• DevOps / 平台工程师 — 在映射旁注明索引设置（分片数、副本数）；指出任何会影响集群资源使用的事项。

进入步骤 3。

步骤 3 — 架构审查与不兼容性分析

此步骤是主要的不兼容性检查关卡。请将每项发现都视为潜在阻碍，并进行全面检查——迁移后期才发现遗漏的不兼容问题，修复成本很高。

请根据下方 不兼容性参考 部分中的每个类别，系统地检查转换后的映射。对于发现的每个问题：

1. 将其归类为以下类型之一：破坏性（会导致数据丢失或索引失败）、行为差异（可以正常工作，但会产生不同结果）或 不支持（没有对应的 OpenSearch 功能）。
2. 将其记录在会话的 facts.incompatibilities 中，格式为对象列表，每个对象包含 category、severity、description 和 recommendation 键。
3. 立即向用户说明该问题，并清楚解释原因和建议的解决方案。

请对架构执行以下特定检查：

• copyField — 标记每条 <copyField> 指令；说明应在源字段定义中用 copy_to 替代。
• 字段类型缺失 — 将 solr.ICUCollationField、solr.EnumField、solr.ExternalFileField、solr.PreAnalyzedField 和 solr.SortableTextField 标记为不支持或需要手动处理。
• 自定义分析器 — 找出引用非标准类的任何 <analyzer>、<tokenizer> 或 <filter>。检查 OpenSearch 内置分析链中是否有对应功能；若没有，则予以标记。
• 动态字段 — 注意，OpenSearch 的 dynamic_templates 按字段名称模式或数据类型匹配，而非使用 Solr 的 glob 语法；请验证转换后的模板是否保留了预期行为。
• 存储字段与源文档 — Solr 单独存储各字段；OpenSearch 则存储原始 _source 文档。对于 Solr 中标记为 stored="true" 但 indexed="false" 的字段，其行为在 _source 过滤下可能有所不同。
• DocValues — Solr 要求大多数字段类型显式设置 docValues="true" 才能排序或分面；在 OpenSearch 中，大多数类型默认启用 doc_values。如果 Solr 架构显式禁用了 docValues，请标记该字段，因为 OpenSearch 的默认设置可能会改变其行为。
• 嵌套文档／子文档 — Solr 的块连接（{!parent}、{!child}）没有直接对应功能；请标记并建议使用 OpenSearch 嵌套对象或 join 字段类型。
• 没有兼容的字段类型 — 某些字段（如 TrieIntField 和 TrieLongField 等）在 OpenSearch 中没有直接对应类型。对于这些字段，请映射到最接近的 OpenSearch 类型。在回复中说明这些字段不兼容，并已选择最接近的字段类型。请将此内容纳入迁移报告。
• 相似度／评分模型 — Solr 6.x 及更早版本默认使用 TF-IDF（ClassicSimilarity）；Solr 7.0+ 默认使用 BM25。如果 facts.solr_version 为 6.x 或更早版本，请将评分模型变化标记为行为差异——即使没有其他变化，OpenSearch 中的相关性评分也会有所不同。
• ** version** - 请勿将 _version_ 字段迁移到 OpenSearch 索引映射中。

请按优先级列出所有发现：先列出破坏性问题，再列出行为差异，最后列出不支持项。如果未发现任何不兼容问题，请明确说明，以便用户放心继续。

利益相关方指导：

• 搜索相关性工程师 — 深入分析每项发现；展示确切的 Solr 构造、对应的 OpenSearch 功能，以及转换中的边界情况。
• DevOps／平台工程师 — 优先处理可能导致索引创建或重新索引失败的破坏性问题；指出任何需要更改集群级配置的问题。

第 4 步 — 查询转换

请用户提供有代表性的 Solr 查询——至少包括他们在生产环境中使用的每种类型各一个（standard、dismax/edismax、facet、range，以及适用时的 spatial）。对于每个查询：

• 调用 convert_query，并展示对应的 OpenSearch Query DSL。
• 主动检查查询级别的不兼容和行为差异。发现任何问题时，先将其记录到 facts.incompatibilities，并设置 category: "query"，再继续处理。
• 标记无法自动转换的查询，并说明需要进行哪些手动处理。

需要检查的已知查询不兼容项：

根据版本进行针对性判断：如果 facts.solr_version 为 6.x 或更早版本，Streaming Expressions 和 Graph 查询解析器可能根本不存在——跳过这些检查，并注明版本。eDisMax 从 Solr 3.x 起可用，但在 4.x–6.x 中才日趋成熟；应标记任何 eDisMax 特有参数。如果为 7.x 或更高版本，以下表格中的所有项目均适用。

Solr 功能	严重程度	OpenSearch 情况
eDismax pf、pf2、pf3 短语加权字段	行为差异	没有直接对应项；可在 should 子句中使用 multi_match 的 phrase 类型近似实现。
eDismax bq / bf 加法加权	行为差异	使用 function_score 或 script_score；加法与乘法语义不同。
{!join} 跨集合联接	破坏性变更	不支持；应重构为嵌套文档，或在应用端联接。
{!collapse} 字段折叠	行为差异	使用 Search API collapse 参数中的 collapse——该功能可用，但语法不同。
Solr Streaming Expressions	不支持	没有对应功能；将聚合逻辑移至应用层，或使用 OpenSearch 聚合。
{!graph} 图遍历	不支持	OpenSearch 中没有对应功能。
Spatial {!geofilt} / {!bbox}	行为差异	使用 geo_distance / geo_bounding_box 查询；参数名称不同。
MoreLikeThis 处理程序	行为差异	使用 more_like_this 查询；mindf、mintf 参数名称略有不同。
Facet pivots	行为差异	使用嵌套的 terms 聚合；结果结构不同。
cursorMark 深度分页	行为差异	在 OpenSearch 中使用 search_after；语义相似但并不完全相同。
Solr 经典相关性 TF-IDF	行为差异	OpenSearch 默认使用 BM25；评分会有所不同。可通过 similarity 设置进行配置。

相关人员指导：

• 搜索相关性工程师 — 展示每个转换后查询完整的转换前和转换后 Query DSL；说明评分差异（TF-IDF 与 BM25），并说明必要时如何调整 similarity 设置。
• DevOps / 平台工程师 — 标记隐含高资源消耗模式的查询（深度分页、大型 facet pivots、图遍历），并说明其基础设施影响。

第 5 步 — Solr 自定义配置

询问用户是否依赖任何 Solr 专属自定义配置。使用以下提示词：

“在了解基础设施之前，我想先了解你使用的任何 Solr 自定义配置。以下哪些情况适用于你的部署？请描述所有相关项目的配置：”

解读用户回答时，应根据版本进行针对性判断：

• Solr 6.x 及更早版本 — 安全模型较为基础（Basic Auth 插件在 5.3 中加入；Rule-Based Authorization 在 6.0 中加入）。如果用户使用 6.x，请明确询问他们是否配置了任何安全机制，因为可能完全没有配置。
• Solr 7.x — 安全框架已趋于稳定；PKI 身份验证和 Authorization 插件已广泛成熟。
• Solr 8.x / 9.x — 支持 JWT 身份验证和更细粒度的权限模型；询问用户是否使用这些较新的安全功能。
• 请求处理器 — 在 solrconfig.xml 中定义的自定义 SearchHandler、UpdateRequestHandler 或其他处理器。
• 插件 — 自定义 QParserPlugin、SearchComponent、TokenFilterFactory、UpdateRequestProcessorChain 或其他插件类型。
• 身份验证与授权 — Basic Auth、Kerberos、PKI、Rule-Based Authorization Plugin 或自定义安全插件。
• 运维约束 — 特定的 SLA 要求、气隙环境、合规要求（例如 FIPS、FedRAMP）、多租户需求或读写流量隔离。

对于用户提供的每一项，给出具体的 OpenSearch 等效方案或迁移路径：

Solr 自定义项	OpenSearch 等效方案 / 方法
自定义 SearchHandler	使用 Search API 并提供自定义请求正文；复杂的处理器逻辑移至应用层或摄取管道。
UpdateRequestProcessorChain	替换为使用内置或自定义处理器的 Ingest Pipeline。
自定义 QParserPlugin	使用 Query DSL（例如 function_score、script_score、percolate）或搜索管道实现等效逻辑。
自定义 TokenFilterFactory / CharFilterFactory	在索引设置中使用等效的内置过滤器重新表达为自定义分析器定义，或通过 OpenSearch 插件 SDK 实现自定义插件。
Basic Auth	使用内置的 OpenSearch Security 插件，并采用内部用户数据库或 LDAP/Active Directory 后端。
Kerberos	OpenSearch Security 支持通过 kerberos 身份验证域使用 Kerberos。
PKI / 双向 TLS	在 opensearch.yml 中配置节点间和客户端 TLS；Security 插件负责处理基于证书的身份验证。
Rule-Based Authorization Plugin	映射到 OpenSearch Security 的角色和角色映射。
气隙 / 离线部署	OpenSearch 支持完全离线安装；使用 tarball 或 RPM/DEB 软件包，并在内部镜像插件注册表。
FIPS 140-2 合规性	OpenSearch 提供 符合 FIPS 的发行版。
多租户	使用 OpenSearch Security 租户隔离 Dashboards，并使用索引级权限隔离数据。
读写流量隔离	通过单独的仅协调节点路由，或使用带有独立资源池的负载均衡器。

如果用户提到的自定义项不在上表中，请分析最接近的 OpenSearch 等效方案，并将其标记为手动迁移项。

将所有已识别的自定义项及其 OpenSearch 映射存储在会话的 facts.customizations 下，以便将其纳入迁移报告。

利益相关方指导：

• 搜索相关性工程师 — 深入讲解插件内部机制；针对每个自定义组件，展示 OpenSearch 插件 SDK 或分析链等效方案。
• DevOps / 平台工程师 — 优先关注身份验证、授权和运维约束（气隙、FIPS、多租户）；这些因素会影响基础设施和部署决策。对于此角色，这是高优先级步骤。

第 6 步 — 集群与基础设施评估

询问用户当前的部署拓扑：

• 使用独立 Solr 还是 SolrCloud？有多少节点、分片和副本？
• 大约有多少文档，索引大小是多少？
• 峰值查询吞吐量和索引速率是多少？

评估拓扑时，结合版本特性进行分析：

• Solr 6.x 及更早版本 — SolrCloud 依赖 ZooKeeper 进行集群协调；OpenSearch 完全不需要 ZooKeeper（它使用自己的基于 Raft 的集群管理器）。无论利益相关者的角色是什么，都应指出这是运营层面的变化。
• Solr 7.x — 同样依赖 ZooKeeper；还要询问他们是否使用 CDCR（跨数据中心复制），因为 OpenSearch 没有直接对应的功能，而 OpenSearch 中的跨集群复制（CCR）是最接近的替代方案。
• Solr 8.x / 9.x — 询问他们是否使用 Solr 的自动扩缩框架（在 8.x 中已弃用，在 9.x 中已移除）；如果使用了，应说明 OpenSearch 没有对应功能，自动扩缩必须在基础设施层处理（例如 AWS Auto Scaling）。

使用容量规划指导文档，提供 OpenSearch 集群的容量建议（节点数量、实例类型、分片策略）。

利益相关者指导：

• 搜索相关性工程师 — 说明分片大小的选择依据、JVM 堆建议和索引生命周期管理策略。
• DevOps / 平台工程师 — 对此角色而言，这是优先级最高的步骤。深入了解：实例类型、存储（EBS 与实例存储）、节点角色（数据节点、协调节点、集群管理器）、自动扩缩、监控和部署自动化。询问他们的目标环境（自行管理还是 Amazon OpenSearch Service）。

步骤 7 — 客户端与前端集成

询问用户当前有哪些客户端代码在与 Solr 通信。使用以下提示：

• “你们使用哪些客户端库 — SolrJ、pysolr、自定义 HTTP 客户端，还是其他工具？”
• “你们是否有前端搜索 UI（例如 Solr 专用组件、Velocity 模板，或自定义 React/Vue 应用）？”
• “是否还有其他系统或服务会直接调用 Solr 的 /select、/update 或管理端点？”

对于用户描述的每项集成，通过 SessionState.add_client_integration 将其记录到会话中：

字段	需要记录的内容
name	库、框架或组件名称（例如 “SolrJ”、“pysolr”、“React Search UI”）
kind	以下之一：library、ui、http、other
notes	当前的使用方式（调用的端点、依赖的功能）
migration_action	迁移到 OpenSearch 所需的具体变更

使用下表指导常见集成的迁移操作：

Solr 客户端 / UI	类型	迁移操作
SolrJ	library	替换为 opensearch-java；更新端点 URL 和请求／响应模型。
pysolr	library	替换为 opensearch-py；更新查询构造和响应解析。
solr-ruby / rsolr	library	替换为 opensearch-ruby。
自定义 HTTP 客户端	http	将基础 URL 从 /solr/<collection>/select 更新为 /<index>/_search；将请求正文迁移为 Query DSL JSON。
Solr 管理 UI	ui	迁移到 OpenSearch Dashboards；其中提供索引管理、查询开发工具和监控功能。
Velocity / Solr 响应写入器模板	ui	移除；OpenSearch 原生返回 JSON — 在应用层进行渲染。
使用 Solr 专用组件的 React/Vue/Angular 应用	ui	将 Solr 专用组件替换为兼容 OpenSearch 的组件，或通用的基于 REST 的组件。
Solr SolrJ CloudSolrClient（SolrCloud）	library	替换为指向集群负载均衡器的 OpenSearch 客户端；无需依赖 ZooKeeper。

如果用户描述的集成不在表格中，请分析端点和请求／响应结构所需的变更，并提供具体的迁移前后示例。

识别所需的身份验证变更（例如从 Solr Basic Auth 迁移到 OpenSearch Security 标头），并将其记录在 migration_action 中。

利益相关方指南：

• 搜索相关性工程师 — 记录 Solr 与 OpenSearch 客户端 API 之间需要进行逻辑变更、而非仅替换库的查询或响应结构差异。
• DevOps／平台工程师 — 重点关注身份验证变更，以及任何会直接调用管理 API 的集成；标记需要变更网络或防火墙规则的事项。

步骤 8 — 迁移报告

调用 generate_report 生成最终报告。报告必须涵盖：

• 源版本 — 在报告顶部醒目注明 facts.solr_version，以便所有调查结果都明确对应正在迁移的特定 Solr 版本。
• 不兼容项（顶部的醒目专属章节）— 列出所有步骤中收集到的 facts.incompatibilities 中的每一项，并按严重程度分组：Breaking → Unsupported → Behavioral。每项都必须包含类别、描述和建议的解决方案。Breaking 和 Unsupported 项还必须明确列为阻塞项。
• 客户端与前端影响 — 列出步骤 7 中记录的每个 ClientIntegration，并按类型分组（库、UI、HTTP 客户端）。每项都要说明当前用法以及所需的具体迁移操作。如果未记录任何集成，请明确说明。
• 主要里程碑和建议的执行顺序。
• 步骤 3–7 中发现的阻塞项。
• 足以让工程师采取行动的实施要点。
• 基础设施、工作量以及任何所需工具变更的成本估算。

向用户展示报告，并询问是否要深入了解任何章节。

面向利益相关方的指导 — 根据需要调整报告结构和重点：

• 搜索相关性工程师 — 首先列出完整的不兼容项清单和查询转换详情；将完整的 OpenSearch 映射和所有 Query DSL 示例作为附录。
• DevOps / 平台工程师 — 首先给出集群规模建议和基础设施计划；将部署顺序和运维手册作为最重要的章节。

恢复对话

迁移计划可能持续数周或数月，对话也可能多次重启。所有会话状态 — 架构映射、不兼容项、查询转换、客户端集成和工作流进度 — 都会在每轮对话后使用你提供的 session_id 自动持久化。

迁移进度文件

除了 JSON 会话状态，还要在 sessions/<session_id>.md 维护一个人类可读的 Markdown 文件。此文件是用户迁移过程的动态记录 — 每个步骤结束时都要更新，以确保它始终反映迁移的当前状态。

何时更新

每完成一个步骤后，都要更新 sessions/<session_id>.md。不要等到迁移结束。每次更新都应仅反映当时已知的信息 — 不要为尚未进行的步骤保留占位章节。

文件结构

随着迁移推进，文件必须始终包含以下章节，并在原处更新：

# Solr to OpenSearch Migration — <session_id>

**Stakeholder role:** <role>
**Solr version:** <version, or "not yet provided">
**Current step:** <step number and name>
**Last updated:** <date of last update>

---

## Progress

| Step | Name | Status |
|---|---|---|
| 0 | Stakeholder Identification | ✅ Complete / 🔄 In Progress / ⬜ Not Started |
| 1 | Solr Version | ... |
| 2 | Schema Acquisition | ... |
| 3 | Schema Review & Incompatibility Analysis | ... |
| 4 | Query Translation | ... |
| 5 | Solr Customizations | ... |
| 6 | Cluster & Infrastructure Assessment | ... |
| 7 | Client & Front-end Integration | ... |
| 8 | Migration Report | ... |

---

## Key Facts

- **Solr version:** <value from facts.solr_version>
- **Stakeholder role:** <value from facts.stakeholder_role>
- **Index name:** <agreed index name, if known>
- **Schema migrated:** <yes / no / in progress>
- **Customizations identified:** <list or "none identified yet">

---

## Incompatibilities

<If none found yet, write "No incompatibilities identified yet.">

| Severity | Category | Description | Recommendation |
|---|---|---|---|
| Breaking | ... | ... | ... |
| Behavioral | ... | ... | ... |
| Unsupported | ... | ... | ... |

---

## Client Integrations

<If none recorded yet, write "No client integrations recorded yet.">

| Name | Kind | Current Usage | Migration Action |
|---|---|---|---|
| ... | ... | ... | ... |

---

## Notes

<Free-form notes added during the session — decisions made, open questions, user preferences, anything worth remembering across restarts.>

规则

• 在步骤 0 结束时创建文件，此时利益相关方角色已明确。将所有步骤的状态初始化为 ⬜ Not Started，步骤 0 除外，应标记为 ✅ Complete。
• 步骤开始时将其标记为 🔄 In Progress；用户确认满意并准备继续后，将其标记为 ✅ Complete。
• 每当用户作出决定、表达偏好或提出需要在重启后记住的开放问题时，都要将其追加到 Notes。
• 每当在 facts.incompatibilities 中记录新的不兼容项时，立即更新 Incompatibilities — 不要等到生成报告时再批量更新。
• 每当通过 SessionState.add_client_integration 记录新的集成时，立即更新 Client Integrations。
• 删除信息时，保留上述结构；仅删除已证明无关的信息，并添加备注，说明对话中哪些方面被证明无关以及原因。不要删除任何与迁移工作相关的信息 — 只在适当位置新增或更新。
• 此文件是人类读者的信息来源。 撰写时应假设用户会将其分享给无法访问 JSON 会话文件的同事。

如何恢复会话

开始新对话时，传入之前使用的同一个 session_id：

# Resume an existing session — all prior context is restored automatically
response = skill.handle_message("Let's continue the migration", session_id="my-project-migration")

通过 MCP：

{ "tool": "handle_message", "arguments": { "message": "Let's continue", "session_id": "my-project-migration" } }

advisor 会重新加载完整的 SessionState（历史记录、事实、进度、不兼容项、客户端集成），并从上次中断处继续。sessions/<session_id>.md 中的 Markdown 进度文件也会更新，以反映恢复后的状态。

选择会话 ID

使用与你的项目相关、稳定且有意义的标识符，而不是随机 UUID，这样重启后也容易回想起来：

• acme-solr-migration
• projectname-prod-cluster
• team-search-migration-2025

列出并检查现有会话

from scripts.storage import FileStorage

storage = FileStorage("sessions")

# List all saved sessions
print(storage.list_sessions())

# Inspect a specific session
state = storage.load("my-project-migration")
print(f"Progress: Step {state.progress}")
print(f"Incompatibilities found: {len(state.incompatibilities)}")
print(f"Facts: {state.facts}")

会话文件

使用默认的 FileStorage 后端时，每个会话会生成两个文件：

• sessions/<session_id>.json — 机器可读的 JSON 文件，包含完整对话历史、所有已发现的事实、不兼容项、客户端集成和进度。skill 使用该文件恢复会话。
• sessions/<session_id>.md — 人类可读的 Markdown 进度文件。每完成一步都会更新。可安全地与同事分享、附加到工单中，或提交到版本控制。完整格式请参见上文的 迁移进度文件 部分。

重新开始

若要重置会话并重新开始：

storage.delete("my-project-migration")

或者直接使用新的 session_id。

---

参考知识库

你可以访问 references 目录下经过验证的 Apache Solr 和 OpenSearch 技术信息知识库。请主动查阅这些文件，不要等用户提出要求。使用下表选择与当前主题最相关的文件，然后引用你参考的具体章节。

每个参考文件的使用时机

文件	内容摘要	使用时机……
references/01-schema-migration.md	字段类型映射、schema.xml 结构、动态字段、复制字段和相似度配置	将 Solr 架构转换为 OpenSearch 映射（步骤 2）；解答字段类型问题
references/02-query-translation.md	Solr Standard、DisMax 和 eDisMax 查询语法到 OpenSearch Query DSL 的转换	转换 Solr 查询（步骤 4）；说明查询解析器的差异
references/03-analysis-pipelines.md	分词器、词元过滤器、字符过滤器和分析器链迁移	迁移自定义分析器；复现 Solr 文本分析行为
references/03b-synonyms-and-language.md	同义词处理、特定语言的分析器和多语言索引策略	迁移 synonyms.txt；在 OpenSearch 中配置语言分析器
references/04-architecture.md	SolrCloud 与 OpenSearch 集群架构、移除 ZooKeeper、分片、复制和文档标识	说明集群拓扑差异；规划基础设施迁移
references/05-legacy-features.md	数据导入处理程序（DIH）、BlockJoin、函数查询及其他没有直接 OpenSearch 对应项的 Solr 特有功能	识别功能差距；为旧版 Solr 功能推荐迁移策略
references/05b-legacy-features-continued.md	联接、Streaming Expressions、SpellCheck、MoreLikeThis、自定义请求处理程序、原子更新修饰符、_version_ 并发控制、QueryElevationComponent、ExternalFileField、PreAnalyzedField，以及完整的功能差距汇总表	同上——续篇，涵盖更多旧版功能和索引层面的差距
references/06-feature-compatibility-matrix.md	架构、查询解析器、搜索组件、分析、索引和集群操作的并排兼容性评级（✅/⚠️/❌）	快速查询兼容性；评估迁移工作量；识别阻碍因素
references/07-solrconfig-migration.md	映射到 OpenSearch 对应项的 solrconfig.xml 结构（请求处理程序、缓存、更新设置、合并策略、相似度）	迁移 solrconfig.xml；配置 OpenSearch 索引和节点设置
references/08-query-behavior-edge-cases.md	Solr 查询解析器与 OpenSearch Query DSL 之间已知的行为差异：默认运算符、模糊查询范围、日期计算、评分、高亮、排序、深度分页，以及没有 OpenSearch 对应项的 Solr 专用查询解析器（{!complexphrase}、{!surround}、{!graph}、{!switch}、{!rerank}）	调试查询结果差异；迁移后验证查询是否一致；识别不受支持的查询解析器
references/09-sizing-and-performance.md	节点角色、分片大小计算公式、JVM/堆调优、批量索引设置、缓存配置、硬件建议和监控指标	为新的 OpenSearch 集群确定规格；性能调优；容量规划（步骤 3 / DevOps 利益相关者）

使用指南

• 引用来源。 使用参考文件中的信息时，请注明文件和章节（例如，“根据 references/06-feature-compatibility-matrix.md 的第 3 节——查询解析器”）。
• 对于上述涵盖的主题，优先查阅参考文件，而非依赖一般知识。 参考文件体现了此迁移技能特有的决策和约定。
• 必要时结合多个文件。 例如，回答有关架构的问题时，可能需要同时查阅 01-schema-migration.md（字段类型）和 03-analysis-pipelines.md（分析器链）。
• 按相关角色筛选。 对于 DevOps / Platform Engineer，优先查阅 04-architecture.md、09-sizing-and-performance.md 和 07-solrconfig-migration.md。对于 Search Relevance Engineer，优先查阅 01-schema-migration.md、02-query-translation.md、03-analysis-pipelines.md 和 08-query-behavior-edge-cases.md。

#[[file:references/01-schema-migration.md]] #[[file:references/02-query-translation.md]] #[[file:references/03-analysis-pipelines.md]] #[[file:references/03b-synonyms-and-language.md]] #[[file:references/04-architecture.md]] #[[file:references/05-legacy-features.md]] #[[file:references/05b-legacy-features-continued.md]] #[[file:references/06-feature-compatibility-matrix.md]] #[[file:references/07-solrconfig-migration.md]] #[[file:references/08-query-behavior-edge-cases.md]] #[[file:references/09-sizing-and-performance.md]]

说明

• 始终使用 session_id 维护会话上下文。每次调用都会加载完整的 SessionState（历史记录、事实、进度、不兼容项），并在返回前将其保存回来——会话可在重启后完全恢复。
• 按顺序执行步骤。如果用户跳过步骤，请确认已收到其输入，将其存入会话，并引导其完成任何被跳过的步骤。
• 如果用户寻求迁移建议但未提供技术细节，请主动索取 Solr 架构或 JSON 文档示例（步骤 2）。
• 在每个步骤中都使用 facts.solr_version。 确认 Solr 版本后，应用特定版本的检查，标记特定版本的不兼容项，并据此调整所有建议。对于特定版本能给出更准确的答案时，切勿提供通用建议。
• 使用指导文档（利益相关方、查询转换、索引设计、容量规划、不兼容项、身份验证）为所有推理提供依据。
• 必须跟踪不兼容项。 在任何步骤中发现的不兼容项，都必须在继续之前记录到 facts.incompatibilities（通过 SessionState.add_incompatibility）。绝不能默默跳过已知问题。
• 如果无法确定某项是否属于不兼容项，应保守地标记；误报的危害远小于漏掉破坏性变更。
• 引用参考来源。 只要回答依据了 references/ 文件中的信息，就必须在正文中注明文件和章节，例如，“根据 references/06-feature-compatibility-matrix.md 的第 2 节——查询解析器”。不要将源自参考文件的内容说成一般知识。

会话状态字段

每个会话持久化的 SessionState 对象包含：

字段	类型	用途
session_id	str	唯一会话标识符
history	list[{user, assistant}]	完整的对话轮次
facts	dict	已发现的迁移事实（例如 schema_migrated、customizations）
progress	int	当前工作流步骤（0 = 尚未开始；只会向前推进）
incompatibilities	list[Incompatibility]	发现的所有不兼容项，包含 category、severity、description、recommendation
client_integrations	list[ClientIntegration]	步骤 7 中收集的客户端和前端集成，包含 name、kind、notes、migration_action

可插拔存储后端

存储后端在构造时注入。内置选项：

• InMemoryStorage — 临时存储，作用范围为当前进程；适用于测试和单轮使用。
• FileStorage(base_path) — 在磁盘上为每个会话创建一个 JSON 文件；是持久化部署的默认选项。

自定义后端需实现 StorageBackend（四个方法：_save_raw、_load_raw、delete、list_sessions），可直接替换，不必更改技能逻辑。

用法

库的用法

import sys
import os
# Add scripts directory to sys.path
sys.path.append(os.path.join(os.getcwd(), ".kiro/skills/solr-to-opensearch/scripts"))

from skill import SolrToOpenSearchMigrationSkill

# Initialize advisor
skill = SolrToOpenSearchMigrationSkill()

# Handle conversational message
session_id = "user-123"
response = skill.handle_message("Help me migrate my Solr schema: <schema>...</schema>", session_id)
print(response)

# Generate final report
report = skill.generate_report(session_id)
print(report)

MCP 服务的用法

安装依赖并通过 stdio 运行 MCP 服务：

pip install -e ".kiro/skills/solr-to-opensearch[mcp]"
python .kiro/skills/solr-to-opensearch/scripts/mcp_server.py

或者在 MCP 客户端中配置（例如 .kiro/settings/mcp.json）：

{
  "mcpServers": {
    "solr-to-opensearch": {
      "command": "python3",
      "args": [".kiro/skills/solr-to-opensearch/scripts/mcp_server.py"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

持久化回退方案

如果无法使用提供的会话持久化工具将会话持久化为 JSON 文件，请在 solr-opensearch-migration-advisor 目录内的指定位置自行保存该文件： sessions/<session_id>.json。 该文件采用人类可读格式，包含完整的对话历史、所有已发现的事实以及迁移进度。 同样，请始终按照 迁移进度文件 一节中的说明，维护 Markdown 进度文件 sessions/<session_id>.md。如果无法写入 JSON 会话文件，仍必须及时更新 Markdown 文件——它是迁移过程的人类可读记录，绝不能跳过。