乐享桌面文档同步盘点

问题

本地文档会散落在 Desktop、Documents、Downloads 和项目目录里，而腾讯乐享空间里也可能保留对应版本。若直接按文件名同步，很容易把同名旧稿当新版本覆盖；只看文件数量或“最近更新”又不能判断正文是否真的变了。要回答“哪些本地文档需要重新上传、哪些只留在本机、哪些两边都改过”，必须先有安全的只读盘点。

工作方式

• 连接优先：任何读取本地文件、列举乐享空间或生成报告前，先检查 Lexiang MCP 连接和 whoami。连接不可用时立即停止，只返回固定提示，不继续扫描。
• 元数据驱动增量比对：本地默认扫描用户主目录下可读文档，排除缓存、隐藏目录、应用包、依赖和系统路径；外部盘通过 --root 指定。先比较 size、mtime_ns 和 device:inode，未变化文件不重读；元数据变化才计算 SHA-256，.md 还比较归一化 front matter 与正文哈希。
• 树形遍历乐享：以空间遍历构建清单，记录完整路径、entry_id、file_id、size、updated_at、version 和真实 HTTPS URL，避免逐文件搜索。快照与状态分别写入 lexiang-tree.json 和 state.json，只存路径、键、哈希、ID 和时间戳，不存 token 或正文。
• 保守匹配与双向判断：只有缺少已确认映射的文件才跑匹配器。两侧都可读且 checksum/内容一致才标记为已验证；任一侧不可读时明确记录“内容不可读取，未进行正文比对”，不给相似度分数。AI 不计算语义相似度，只参与正文差异和总结。
• 严格 HTML 报告：生成前先完成连接、清单、树遍历、哈希/正文比对和 AI review。报告用真实链接，本地文档提供 file:// 入口和复制路径，乐享文档使用清单中的真实 URL；地址缺失时不伪造。两张业务表必须是 HTML 表格：表一展示“本地更新了、乐享未更新”，用 scripts/extract_local_document.py 和乐享 entry_describe_ai_parse_content 读取完整内容后再比较，正文新增、改动、删除才算更新；表二展示“本地有、乐享没有”，只做快速元数据判断，不调 AI、不读正文、不计算相似度。

边界与注意点

• 只支持 Tencent Yunzhi/Lexiang；发现阶段严格只读，候选匹配不授权上传、覆盖、移动或删除。
• 文件名重合只能缩小候选范围，不能当作内容一致；无法枚举的空间应标注为 excluded，不能偷偷替换成搜索结果。
• 不生成 Markdown/Word 报告，聊天中只返回 HTML 路径和状态；Agent 生成的文档不单独分类，按同样规则进入两张表。