feat: ✨ Atlas Search/变更流增强与文档完善

[joesdu]

📝 描述 (Description)

• 新增 AutoEmbeddingFieldAttribute，支持 Atlas 自动嵌入字段（Voyage AI 模型，零代码生成向量）
• MongoSearchIndexAttribute 增加 StoredSource，支持原文档存储
• VectorFieldAttribute 支持自动量化（Scalar/Binary）、HNSW 图参数
• 新增 EVectorQuantization 枚举，索引定义生成逻辑同步增强
• 启动时自动对齐/更新索引定义，避免误判反复重建
• 变更流支持 ResumeTokenPersistInterval 节流，提升高并发场景性能，持久化逻辑更健壮
• 文档/示例同步完善，补充新特性说明与最佳实践
• IndexDefinition 实现 IEquatable，注释中英文补全

🔗 相关问题 (Related Issues)

• Closes #
• Fixes #

🏷️ 变更类型 (Type of Change)

• 🐛 错误修复 (Bug fix) (non-breaking change which fixes an issue)
• ✨ 新功能 (New feature) (non-breaking change which adds functionality)
• 💥 破坏性变更 (Breaking change) (fix or feature that would cause existing functionality to not work as expected)
• 📚 文档更新 (Documentation update)
• 🔧 重构 (Refactor) (no functional changes)
• 🧪 测试 (Tests) (adding or updating tests)
• 🛠️ 构建/CI 变更 (Build/CI changes)
• 🎨 样式变更 (Style changes) (formatting, etc.)
• 🚀 性能改进 (Performance improvements)
• 🔒 安全改进 (Security improvements)

✅ 检查清单 (Checklist)

• 我的代码遵循项目的编码标准 (My code follows the project's coding standards)
• 我已经对自己的代码进行了自我审查 (I have performed a self-review of my own code)
• 我已经在难以理解的区域注释了我的代码 (I have commented my code, particularly in hard-to-understand areas)
• 我已经对文档进行了相应的更改 (I have made corresponding changes to the documentation)
• 我的更改不会产生新的警告或错误 (My changes generate no new warnings or errors)
• 我已经添加了证明我的修复有效或我的功能工作的测试 (I have added tests that prove my fix is effective or that my
  feature works)
• 新增和现有的单元测试在本地通过我的更改 (New and existing unit tests pass locally with my changes)
• 任何依赖变更都已合并并发布到下游模块 (Any dependent changes have been merged and published in downstream modules)

🧪 测试 (Testing)

• 单元测试 (Unit tests)
• 集成测试 (Integration tests)
• 手动测试 (Manual testing)
• 其他 (请指定) (Other (please specify)):

📸 截图 (如果适用) (Screenshots (if applicable))

🔍 附加说明 (Additional Notes)

[Copilot]

Pull request overview

EN

Summary

• Enhances EasilyNET.Mongo Atlas Search/Vector Search index definition generation (auto-embedding, stored source, vector quantization/HNSW options) and improves change stream resiliency/performance via resume-token persistence throttling, with accompanying docs updates.

Key issues

• CollectAutoEmbeddingFields does not validate the annotated property type is string, which can generate an invalid index definition and fail index creation/update at startup.
• New HNSW tuning options accept negative values silently (treated like 0), making misconfiguration harder to detect.

Suggested changes

• Add an explicit prop.PropertyType == typeof(string) validation for AutoEmbeddingFieldAttribute mappings.
• Validate MaxEdges / NumEdgeCandidates are >= 0 and throw on negative values.

中文

总结

• 本 PR 增强 EasilyNET.Mongo 的 Atlas Search/Vector Search 索引定义生成能力（自动嵌入、StoredSource、量化/HNSW 参数），并通过 ResumeToken 持久化节流提升变更流在高并发场景下的性能与健壮性，同时完善文档示例。

主要问题

• CollectAutoEmbeddingFields 未校验属性类型是否为 string，一旦误标注到非字符串字段，将生成非法索引定义并导致启动期索引创建/更新失败。
• HNSW 参数新增后对负数输入会静默忽略（等价 0），不利于及时发现配置错误。

修改建议

• 为自动嵌入字段增加 string 类型校验并给出明确异常信息。
• 对 MaxEdges / NumEdgeCandidates 增加 >= 0 校验，负数直接抛异常。

Changes:

• Add AutoEmbeddingFieldAttribute, StoredSource, vector quantization + HNSW options in index definition generation.
• Add index definition drift reconciliation using server latestDefinition subset-satisfaction comparison.
• Add change-stream resume token persistence throttling (ResumeTokenPersistInterval) and switch to StartAfter resume semantics; update docs accordingly.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/EasilyNET.Mongo/SearchIndex/SearchIndexManager.cs	Adds subset-based definition satisfaction comparison to avoid unnecessary rebuilds and support drift detection.
src/EasilyNET.Mongo/SearchIndex/SearchIndexDefinitionFactory.cs	Generates new index definition fields: storedSource, quantization, HNSW options, and auto-embedding mappings.
src/EasilyNET.Mongo/SearchIndex/SearchIndexBackgroundService.cs	Reconciles index definition drift on startup and triggers updates when needed.
src/EasilyNET.Mongo/README.md	Updates usage docs/examples for StoredSource, quantization, auto-embedding, and change stream throttling semantics.
src/EasilyNET.Mongo/Options/ChangeStreamHandlerOptions.cs	Introduces ResumeTokenPersistInterval option with bilingual XML docs.
src/EasilyNET.Mongo/Indexing/IndexDefinition.cs	Implements IEquatable, adds Equals(object) and GetHashCode().
src/EasilyNET.Mongo/ChangeStreams/MongoChangeStreamHandler.cs	Adds throttled resume-token persistence and switches to StartAfter; flushes pending token on shutdown/error.
src/EasilyNET.Mongo.Core/README.md	Documents EVectorQuantization, HNSW parameters, and AutoEmbeddingFieldAttribute usage.
src/EasilyNET.Mongo.Core/Enums/EVectorQuantization.cs	Adds quantization enum with bilingual docs.
src/EasilyNET.Mongo.Core/Attributes/VectorFieldAttribute.cs	Extends vector field attribute with quantization and HNSW tuning options.
src/EasilyNET.Mongo.Core/Attributes/MongoSearchIndexAttribute.cs	Adds StoredSource flag with bilingual docs.
src/EasilyNET.Mongo.Core/Attributes/AutoEmbeddingFieldAttribute.cs	Adds new attribute for Atlas automated embedding with bilingual docs and examples.
.gitignore	Ignores .omc files.