desktop/src-tauri/crates/core/src/adapters/framework.rs
第 1 条注释，第 1 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1
//! 适配器框架：discover → detect → scan → map → capability 统一接口，第 2 条注释，第 2 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:2
//! 以及把扫描结果接入 M1 `commit_batch` 管线的运行器（V12：重复扫描不增量）。第 3 条注释，第 3 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:3
//!（空行）第 4 条注释，第 4 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:4
//! 规则要点：第 5 条注释，第 5 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:5
//! - discover：候选路径 + 环境覆盖 + 手工根，有界枚举，不全盘扫描；第 6 条注释，第 6 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:6
//! - detect：文件 magic/记录类型/schema 指纹 + Agent 目录版本注册表分派；第 7 条注释，第 7 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:7
//! 未知/缺失版本默认尝试该 Agent 最新内置解析器并带兼容标记（V17/V30），第 8 条注释，第 8 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:8
//! 已确认不兼容的版本与未知格式 fail closed 返回受限；第 9 条注释，第 9 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:9
//! - scan：增量游标读取（JSONL 游标 = 文件身份 + generation + 完整行字节偏移 + 解析上下文）；第 10 条注释，第 10 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:10
//! - capability：每源字段能力声明，供未来数据源页使用；第 11 条注释，第 11 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:11
//! - 诊断只存字段名/错误码/位置，不复制原始内容。第 12 条注释，第 25 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:25
/// 单源每轮墙钟超时初值（architecture.md：30 秒）。第 13 条注释，第 27 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:27
/// 发现阶段的文件/目录上界（有界探测）。第 14 条注释，第 31 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:31
/// detect 入口的瞬态 IO 错误判定：杀软/产品进程短暂持锁第 15 条注释，第 32 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:32
/// （Windows 共享违例 → PermissionDenied）、超时、枚举后文件被清理。第 16 条注释，第 33 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:33
/// 瞬态错误必须 Pending 下轮重探，不能固化为扫描失败或 UnknownFormat。第 17 条注释，第 45 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:45
/// detect 文件头读取助手：`Ok(None)` = 瞬态不可读（调用方返回 Pending）；第 18 条注释，第 46 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:46
/// 硬错误上抛 CoreError。第 19 条注释，第 63 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:63
/// 发现上下文。环境变量以显式 map 传入，便于测试且不依赖真实进程环境。第 20 条注释，第 71 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:71
/// 候选根的来源依据。第 21 条注释，第 75 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:75
/// 环境变量覆盖（值是变量名，不是内容）。第 22 条注释，第 77 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:77
/// 平台默认用户目录。第 23 条注释，第 79 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:79
/// 用户手工添加的根。第 24 条注释，第 83 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:83
/// 一个有界枚举后的候选根。第 25 条注释，第 91 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:91
/// 格式探测结果（architecture.md 未知版本兼容约定）：第 26 条注释，第 92 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:92
/// - Supported：Agent 身份与输入类型已确认。已知版本按注册表映射分派（KnownVersion）；第 27 条注释，第 93 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:93
/// 未知/缺失版本默认选择该 Agent 最新内置解析器（LatestFallback），结果须带兼容标记。第 28 条注释，第 94 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:94
/// UnsupportedVersion：已确认版本不兼容，例如固定源码中的格式不同；不尝试回退。第 29 条注释，第 95 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:95
/// - UnknownFormat：Agent 身份或格式无法确认，fail closed；不得返回“成功 0 条”（V17）。第 30 条注释，第 100 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:100
/// 来源原始版本；版本字段缺失时为 None（仍可 LatestFallback）。第 31 条注释，第 112 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:112
/// 文件尚无可判定内容（如新建空文件）：下轮重探。第 32 条注释，第 116 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:116
/// 单项能力可用性。第 33 条注释，第 125 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:125
/// 结构化能力声明（发现/探测/映射/增量/去重/完整性/维护/定时/限制）。第 34 条注释，第 134 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:134
/// 字段能力：token/缓存读/缓存写/逐次请求/模型/时间/费用/延迟。第 35 条注释，第 145 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:145
/// 逐文件扫描目标。第 36 条注释，第 149 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:149
/// 规范化后的文件路径（只进本地库，不进对外输出）。第 37 条注释，第 151 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:151
/// source_files.file_id（规范化路径字符串）。第 38 条注释，第 153 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:153
/// source_files.file_identity / checkpoint scope_key（跨改名稳定）。第 39 条注释，第 155 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:155
/// 探测到的当前文件状态。第 40 条注释，第 157 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:157
/// 按文件续读规则确定的 generation；重扫时已使用新值。第 41 条注释，第 159 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:159
/// 本次是否从头重扫（替换/截断/重建）。第 42 条注释，第 163 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:163
/// 已存储的扫描状态（游标 + 解析上下文）。第 43 条注释，第 170 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:170
/// 扫描限制。第 44 条注释，第 176 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:176
/// 逐文件扫描状态。第 45 条注释，第 179 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:179
/// 读到当前文件尾。第 46 条注释，第 181 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:181
/// 达到读取上限或超时，游标停在完整行边界，下轮继续。第 47 条注释，第 183 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:183
/// 某行超过单行上限：受限，游标停在该行起点，允许受控重试。第 48 条注释，第 185 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:185
/// 空文件等待内容。第 49 条注释，第 200 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:200
/// 快照比较结果，仅含选定的数值字段，不含消息正文。第 50 条注释，第 203 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:203
/// 系列标签（如 "session_cumulative_snapshot"），不含 ID/路径。第 51 条注释，第 205 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:205
/// 逐次明细的 total_tokens 合计。第 52 条注释，第 207 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:207
/// 最终累计快照值。第 53 条注释，第 209 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:209
/// 按已核验规则排除的边界记录合计（如 compaction 携带记录）。第 54 条注释，第 211 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:211
/// 差值为 detail_sum - (snapshot_final + carried_sum)。第 55 条注释，第 213 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:213
/// 比较结果为 matched、mismatch 或 no_snapshot。第 56 条注释，第 217 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:217
/// 一次扫描的产出。第 57 条注释，第 229 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:229
/// 源文件健康（active / degraded）。第 58 条注释，第 233 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:233
/// 适配器统一接口。第 59 条注释，第 236 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:236
/// 统计归属的 Agent 名（事件 agent 字段）。第 60 条注释，第 238 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:238
/// 有界发现：候选路径 + 环境覆盖 + 手工根；不全盘扫描。第 61 条注释，第 240 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:240
/// 仅文件访问不依赖发现顺序时，才启用轮换读取。第 62 条注释，第 244 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:244
/// 由候选根得到稳定的本机实例 ID。第 63 条注释，第 246 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:246
/// 探测文件标记、记录类型和 schema；按各 Agent 注册表选择版本读取器。第 64 条注释，第 248 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:248
/// 增量扫描一个已支持的文件。第 65 条注释，第 256 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:256
/// 重新检查已消费且字节未变化的文件，同时保留游标上下文中的单调修订。第 66 条注释，第 257 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:257
/// 默认继续跳过；快照适配器可用于一次性的统计/健康规则修正。第 67 条注释，第 261 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:261
/// 按逐记录检查更新文件级兼容状态，与事件和游标一起提交。第 68 条注释，第 265 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:265
/// 结构化能力声明。第 69 条注释，第 268 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:268
/// 仅明确核对过的解析修正可使用完整旧摘要的哈希。第 70 条注释，第 269 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:269
/// 来源修订必须相同；其他字段变化仍按冲突处理。第 71 条注释，第 277 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:277
/// 已核对的归档可替代本根目录的文件扫描。第 72 条注释，第 278 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:278
/// 保留可见错误，不悄然叠加第二种数据格式的用量。第 73 条注释，第 289 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:289
/// 规范化路径字符串（统一分隔符并去除 Windows verbatim 前缀；仅用于本地身份）。第 74 条注释，第 296 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:296
/// 有界目录枚举：深度受限、不跟随符号链接、文件数/目录数有上限。第 75 条注释，第 343 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:343
/// 按已保存的访问记录轮换有限文件集，优先读取尚未访问的文件。第 76 条注释，第 344 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:344
/// 访问时间相同则保留适配器的发现顺序，仅已提交的文件行第 77 条注释，第 345 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:345
/// 计为已访问，因此事务回滚后的读取仍保留下一轮的位置。第 78 条注释，第 373 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:373
/// source_instances 注册输入。enabled 等用户设置在冲突更新时保留。第 79 条注释，第 374 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:374
/// origin_host_id：本机核验采集传入本地主机 ID；None 表示未区分（legacy_unknown）。第 80 条注释，第 375 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:375
/// 已属于其他主机的来源不被覆盖；legacy_unknown 来源可被本机核验采集认领第 81 条注释，第 376 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:376
/// （文件就在本机且 locality 已核验 = 可证明映射，data-contract.md#provenance）。第 82 条注释，第 390 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:390
/// 来源归属主机（M1a）；None → legacy_unknown 命名空间。第 83 条注释，第 394 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:394
/// 迁移前的历史来源命名空间（v4 前未记录主机身份）。第 84 条注释，第 473 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:473
/// source_files 行（注册与改名/替换探测用）。第 85 条注释，第 486 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:486
/// 探测结论（JSON）：原始版本、所选格式/parser、选择依据、兼容状态（v3 列）。第 86 条注释，第 553 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:553
/// 按文件身份查找（改名探测：内容流身份稳定，路径可变）。第 87 条注释，第 616 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:616
/// 读取检查点（游标 + 解析上下文）。第 88 条注释，第 640 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:640
/// 由 source_files 行构造 StoredFileState，供文件续读检查使用。第 89 条注释，第 653 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:653
/// 一次源采集运行的配置。第 90 条注释，第 660 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:660
/// 运行/批次 ID 前缀；实际 ID 追加实例序号。第 91 条注释，第 662 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:662
/// 采集归属的本机来源主机 ID（M1a）；None 表示未区分（legacy_unknown）。第 92 条注释，第 663 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:663
/// 由应用层经 `Storage::ensure_local_host` 取得后传入。第 93 条注释，第 667 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:667
/// 逐文件运行报告。第 94 条注释，第 679 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:679
/// 逐实例运行报告。第 95 条注释，第 692 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:692
/// 运行一个适配器：发现 → 逐文件探测/扫描 → 单事务提交（V12 语义）。第 96 条注释，第 693 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:693
/// 返回逐实例报告；单文件失败不中断其他文件，实例提交失败标 failed。第 97 条注释，第 703 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:703
/// 实例过滤（逐源定时：自定义计划的来源只按自身节奏触发，第 98 条注释，第 704 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:704
/// 全局刷新排除它们；到期刷新只包含到期实例）。第 99 条注释，第 707 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:707
/// 仅这些实例参与（None = 不限）。第 100 条注释，第 709 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:709
/// 这些实例跳过（None = 不排除）。第 101 条注释，第 729 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:729
/// 带实例过滤的运行（run_adapter_scan 的过滤版；逐源定时接线用）。第 102 条注释，第 730 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:730
/// 读取前检查 source_instances.enabled，所有触发方式均遵循该设置：第 103 条注释，第 731 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:731
/// Interval、Startup、Manual 和 FixedTime 仅读取已启用的本地来源。第 104 条注释，第 732 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:732
/// 保持 set_source_enabled 的行为，实例停用后不再读取。第 105 条注释，第 733 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:733
/// 停用集加载失败时本适配器 fail-closed（宁可不扫，不越权读取）。第 106 条注释，第 787 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:787
/// 解析来源文件时不持有写入锁；元数据处理和提交使用该锁。第 107 条注释，第 859 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:859
/// 两个来源实例可并行解析，共用现有写入器；结果保留请求和根目录顺序。第 108 条注释，第 954 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:954
// 工作线程 panic 可能留下运行中的任务；由 Storage 的常规恢复处理。第 109 条注释，第 1007 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1007
/// 元数据处理和提交共用现有写入器；来源解析不持有写入锁。第 110 条注释，第 1029 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1029
// 根去重（环境覆盖/默认/手工可能指向同一目录；Windows 大小写别名先归一）。第 111 条注释，第 1058 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1058
// 归档适配器使用空文件列表，自行完成格式探测。第 112 条注释，第 1137 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1137
// 本次未执行扫描；不能把合并请求报告为已成功完成。第 113 条注释，第 1187 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1187
// 准备失败和取消均应结束本次运行，第 114 条注释，第 1188 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1188
// 与归档失败一致，避免留下运行中的任务。第 115 条注释，第 1372 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1372
// 无任何文件变化时跳过提交（无变化扫描不推进修订号）。第 116 条注释，第 1390 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1390
// 原生汇总与事件、游标一起提交；任一失败均可完整重放。第 117 条注释，第 1467 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1467
/// 注册单个文件、检查续读状态，按需探测后增量读取并收集批次结果。第 118 条注释，第 1468 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1468
/// 返回（文件报告， 是否发生了实际读取）。第 119 条注释，第 1509 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1509
// 注册/改名探测：路径未命中时按身份命中（同一内容流改名不算新文件）。第 120 条注释，第 1544 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1544
// 文件字节已全部读取且续读状态连续时，跳过未变化文件。第 121 条注释，第 1566 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1566
// 首次或重扫时重新探测格式；已确认不兼容的版本与未知格式 fail closed（V17），第 122 条注释，第 1567 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1567
// 未知/缺失版本按该 Agent 注册表选择最新内置解析器并带兼容标记。第 123 条注释，第 1705 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1705
// 文件错误隔离不能把取消或其他控制性停止判为数据错误。第 124 条注释，第 1733 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1733
// 未知版本兼容尝试（V30）：无事件或独立有效累计行且带结构诊断 ⇒ 不兼容。第 125 条注释，第 1734 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1734
// Duplicate/OverlapUnknown 对账快照不能替代有效的用量记录，如缺少逐次记录的旧 Codex。第 126 条注释，第 1735 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1735
// 保留旧结果、不提交事件/游标/聚合；下轮解析器更新或显式重扫可重新尝试。第 127 条注释，第 1832 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1832
/// source_files.format_status（v3）的探测 JSON，仅含选定元数据，不含正文。第 128 条注释，第 1859 行
desktop/src-tauri/crates/core/src/adapters/framework.rs:1859
/// 文件内容流身份：创建时间 + 首采样指纹（追加稳定，不依赖路径）。