Reasonix Task Catalog 深度解析跨项目任务投影的 SQLite 索引、对账与重建机制【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-ReasonixReasonix 以.reasonix/tasks下的权威 FileStore 为唯一数据源将跨项目任务投影保存到cache root/task-catalog/v1.sqlite形成可丢弃、可重建的 SQLite 任务目录。本文基于 docs/TASK_CATALOG.zh-CN.md 展开结合internal/taskcatalog源码与 CLI 实现讲解 Task Catalog 的架构定位、增量索引与对账流程、分页查询协议、故障降级策略及运维命令帮助读者理解并正确使用 Reasonix 的任务目录能力。一、Task Catalog 是什么可丢弃投影而非权威数据Reasonix 的 Task Catalog 是一份跨项目任务投影cross-project task projection。它将多个项目根目录下权威的任务快照snapshot与事件日志event log汇聚到一个 SQLite 数据库中供 Desktop Task Center 等消费方做分页查询与展示。理解 Task Catalog 的第一原则是权威数据与投影数据的严格分离权威数据任务 snapshot、事件 JSONL、idempotency 文件、文件锁、version CAS 和 lease全部保存在各项目.reasonix/tasks目录下的 FileStore 中投影数据cache root/task-catalog/v1.sqlite仅是这些权威数据的只读派生视图绝不越权SQLite 投影绝不参与stop、cancel、requeue、open-session等操作的控制权判断。所有任务控制行为仍以 FileStore 权威状态为准见 docs/TASK_CATALOG.zh-CN.md 第 3-5 行。这一设计在源码层面有明确印证。internal/taskcatalog/catalog.go的包注释直接声明该包维护的是权威taskmonitor.FileStore的可丢弃投影disposable projectionCatalog结构体同时持有db *sql.DB与store *taskmonitor.FileStore前者负责投影读写后者负责读取权威数据catalog.go。ObservedStore()方法则返回一个被包装的 FileStore——它只在任务提交之后、per-task 文件锁释放后向目录发送非阻塞的 snapshot/event 变更提示任务保存本身绝不等待目录的 SQLite I/Ocatalog.go。设计要点投影可以随时删除、重建、损坏但任务的真实状态、并发控制与操作许可永远由 FileStore 的 snapshot、idempotency、lock、CAS、lease 决定。Task Catalog 只是一个读缓存这正是它被称为可丢弃的原因。二、存储布局v1.sqlite与 Schema 结构Task Catalog 的数据库路径由DefaultPath()计算func DefaultPath() string { cache : strings.TrimSpace(config.CacheDir()) if cache { return } return filepath.Join(cache, task-catalog, v1.sqlite) }catalog.go当 cache 目录不可用返回空串时Open会退化为内存投影in-memory projection保证目录能力在无缓存环境下依然可用catalog.go。数据库通过internal/projectiondb打开最多保持 4 个并发连接。Schema v1 共五张核心表catalog.go表名作用主键task_state单行版本号表revision每次写入递增id1单行约束task_projects已注册项目root、label、扫描代数scan_generation、扫描游标、索引状态project_keytask_snapshots任务快照投影含完整snapshot_jsonBLOB 与冗余查询列(project_key, task_id)task_event_sources事件 JSONL 文件的索引游标offset、size、fingerprint(project_key, task_id)task_events已索引事件行冗余 state/runtime_state 与原始event_jsonBLOB(project_key, task_id, sequence)配套索引覆盖了三种典型查询路径idx_task_project_page (project_key, updated_at DESC, task_id)按项目分页idx_task_state_page (state, updated_at DESC, project_key, task_id)按状态过滤分页idx_task_session (session_id, updated_at DESC, task_id)按会话分页idx_task_events_page (project_key, task_id, sequence)事件顺序读取。task_snapshots与task_projects之间建立了FOREIGN KEY ... ON DELETE CASCADE项目删除时快照级联清理。快照行中冗余保存state、runtime_state、runtime_lease_until、version、error_code、snapshot_fingerprint等查询/校验列原始 JSON 完整存于snapshot_json BLOB页面渲染时反序列化后调用ReconcileRuntime校正运行时状态catalog.go、catalog.go。三、Project Keycanonical root 的完整 SHA-256跨项目查询的前提是项目标识的确定性。Task Catalog 使用规范化后的项目根目录的完整 SHA-256作为project_keyfunc ProjectKey(root string) string { root filepath.Clean(strings.TrimSpace(root)) if abs, err : filepath.Abs(root); err nil { root abs } sum : sha256.Sum256([]byte(root)) return hex.EncodeToString(sum[:]) }catalog.go要点ProjectKey对传入 root 先filepath.Clean再去空白、再转绝对路径保证同一目录的不同书写形式如./proj与/abs/proj得到同一个 key。每次 action 都会先解析 key再由 control service 重读权威 snapshot 做决策docs/TASK_CATALOG.zh-CN.md 第 12-13 行确保投影中的快照只用于展示不用于控制判断。四、增量索引与对账机制Task Catalog 的索引策略是快照主动、事件惰性并配合后台对账保证一致性。4.1 有界批次优先索引快照ObservedFileStore只在 per-task 锁释放后发送非阻塞的SnapshotChanged/EventsChanged提示shared.go。Catalog 收到提示后将请求投递到容量 1024 的queue通道catalog.go队列满时退化为dirtyProjects脏标记 dirtyWake唤醒防止阻塞任务保存路径工作协程worker从队列取出请求indexSnapshot读取权威 snapshot 并 upsert 到task_snapshots每次写入使 revision 1catalog.go。4.2 事件日志惰性索引event log 是惰性的仅在任务展开、事件查询或追加新事件时才索引docs/TASK_CATALOG.zh-CN.md 第 8 行。indexEvents的核心是byte offset fingerprint 断点续传通过task_event_sources记录上次索引的indexed_offset、文件size与fingerprintsize:modtime若文件 shrink、fingerprint 变化或记录缺失则判定为 reset从 offset 0 重读并重建事件行catalog.go正常追加时调用store.ReadEventTail只读新增尾部INSERT OR REPLACE写回并推进 checkpoint。4.3 后台对账ReconcileProjectworker 每分钟把已注册项目标记为脏catalog.go随后执行ReconcileProject全量对账获取 per-project 锁project_lock.go读取权威任务列表scan_generation1标记为scanning逐个 upsert 快照带当前 generation标记本轮未见到的任务为missing并写入missing_since时间戳超过missingGrace30 秒宽限期的缺失任务级联删除其事件与事件源再删除快照本身catalog.go事务内将项目置为ready并 bump revision。过期 lease 只在读取时对账不回写投影——读取侧通过ReconcileRuntime(time.Now())在渲染时校正运行时状态绝不让目录反向污染权威数据catalog.go。五、分页查询协议Page / EventPage 与游标5.1 任务分页PageListPage接受PageRequest{ProjectKeys, SessionID, States, Query, Cursor, Limit}返回Page{Items, NextCursor, Revision, Partial, StaleCursor, Status}catalog.go。Limit 约束默认DefaultLimit50上限MaxLimit200catalog.go游标Base64(RawURLEncoding) 编码的{Revision, Updated, Project, Task}四元组catalog.go一致性保证游标携带读取时的 revision若翻页时 revision 已变化返回StaleCursortrue客户端应重新发起首屏查询过滤组合项目 keys、session_id、state 列表、自由文本 query匹配 task_id/session_id/error_code大小写不敏感可任意叠加部分性标志Partialtrue表示仍有项目处于pending未索引完成返回的页面可能不完整。排序规则为updated_at DESC, project_key, task_id翻页采用 keyset 条件推进保证大数据量下分页稳定。5.2 事件分页EventPageListEventPage(projectKey, taskID, after, limit)按sequence顺序读取事件读取前先触发一次惰性indexEvents若索引失败返回Partialtrue但不中断查询NextSequence返回下一次续读的起始序号供增量拉取使用catalog.go。六、故障降级与坏数据处理Task Catalog 的核心承诺是投影损坏绝不拖垮任务控制。坏 snapshot 或坏 event line只降级单个任务ListPage反序列化失败的行直接跳过continue不中断整页catalog.go事件行 JSON 解析失败同样跳过未索引完成的项目表现为Pending 0与Partialtrue查询仍可返回已完成项目的部分结果Status结构体提供State/Mode/Path/Revision/Indexed/Total/Pending/Failed/LastError完整诊断信息catalog.gorefresh在每次写入后重算统计catalog.go。七、运维命令doctor 与 reindexTask Catalog 提供两条 CLI 命令docs/TASK_CATALOG.zh-CN.md 第 16-19 行reasonix doctor catalogs [--json] reasonix catalogs reindex tasks [--project PATH ...] [--json]7.1 诊断reasonix doctor catalogsdoctorCatalogsCommanddoctor.go对会话目录及所有已注册的投影目录执行只读检查2 秒超时保护。文本输出示例Reasonix disposable catalogs sessions ok schema1 size... pathcache/session-catalog/v1.sqlite tasks ok schema1 size... pathcache/task-catalog/v1.sqlite每行展示name / state / schema / size / path--json输出结构化的catalogInspection数组含Info.Integrity等字段适合脚本与监控集成。7.2 重建reasonix catalogs reindex tasksreindexTaskCatalogcatalogs_tasks.go执行完整重建--project PATH可重复传入限定参与重建的项目根目录未指定--project时默认从会话目录的目标集合中收集全部有 workspace root 的项目底层taskcatalog.Rebuild先把权威 snapshot 重放到校验过的兄弟数据库projectiondb.Rebuild全部成功后原子替换发布失败则保留原库rebuild.go——即重建只替换可丢弃投影绝不触碰权威数据重建期间共享目录sharedManager进入rebuilding状态新注册请求进入 pending 队列重建完成后统一补注册shared.go事件日志在重建后仍保持惰性任务展开时再索引。因此Catalog 损坏或未完成索引不会禁用任务控制reindex只是把可丢弃的投影换新。八、与 Desktop Task Center 的配合Desktop Task Center 是 Task Catalog 的主要消费方支持对当前会话、当前项目、全部已注册项目三种范围分页docs/TASK_CATALOG.zh-CN.md 第 12 行前端发起带ProjectKeys的分页请求每次 action 先解析 canonical project key由 control service重读权威 snapshot判断任务真实状态再决定 stop/cancel/requeue 等操作目录只负责展示什么FileStore 负责能否操作。这种展示层投影 控制层权威的双轨架构保证了即使目录处于pending、损坏或正在重建任务的停止、取消、恢复与会话打开等关键操作也永远可用。结语Task Catalog 是 Reasonix prefix-cache 稳定性工程哲学在任务管理维度的体现以 SQLite 投影换取跨项目查询体验以可丢弃、可重建、坏行只降级单任务的边界守住任务控制的安全底线。理解其投影绝不影响控制、快照主动索引、事件惰性续传、reindex 原子替换四个设计原则即可放心地在脚本、监控与桌面 UI 中消费这一能力。延伸阅读本文所有结论均可在仓库源码中验证建议进一步阅读 internal/taskcatalog/catalog.go、internal/taskcatalog/rebuild.go、internal/taskcatalog/shared.go、internal/taskcatalog/catalog_test.go、internal/cli/catalogs_tasks.go 与 internal/cli/doctor.go 获取第一手实现细节。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Reasonix Task Catalog 深度解析：跨项目任务投影的 SQLite 索引、对账与重建机制
Reasonix Task Catalog 深度解析跨项目任务投影的 SQLite 索引、对账与重建机制【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-ReasonixReasonix 以.reasonix/tasks下的权威 FileStore 为唯一数据源将跨项目任务投影保存到cache root/task-catalog/v1.sqlite形成可丢弃、可重建的 SQLite 任务目录。本文基于 docs/TASK_CATALOG.zh-CN.md 展开结合internal/taskcatalog源码与 CLI 实现讲解 Task Catalog 的架构定位、增量索引与对账流程、分页查询协议、故障降级策略及运维命令帮助读者理解并正确使用 Reasonix 的任务目录能力。一、Task Catalog 是什么可丢弃投影而非权威数据Reasonix 的 Task Catalog 是一份跨项目任务投影cross-project task projection。它将多个项目根目录下权威的任务快照snapshot与事件日志event log汇聚到一个 SQLite 数据库中供 Desktop Task Center 等消费方做分页查询与展示。理解 Task Catalog 的第一原则是权威数据与投影数据的严格分离权威数据任务 snapshot、事件 JSONL、idempotency 文件、文件锁、version CAS 和 lease全部保存在各项目.reasonix/tasks目录下的 FileStore 中投影数据cache root/task-catalog/v1.sqlite仅是这些权威数据的只读派生视图绝不越权SQLite 投影绝不参与stop、cancel、requeue、open-session等操作的控制权判断。所有任务控制行为仍以 FileStore 权威状态为准见 docs/TASK_CATALOG.zh-CN.md 第 3-5 行。这一设计在源码层面有明确印证。internal/taskcatalog/catalog.go的包注释直接声明该包维护的是权威taskmonitor.FileStore的可丢弃投影disposable projectionCatalog结构体同时持有db *sql.DB与store *taskmonitor.FileStore前者负责投影读写后者负责读取权威数据catalog.go。ObservedStore()方法则返回一个被包装的 FileStore——它只在任务提交之后、per-task 文件锁释放后向目录发送非阻塞的 snapshot/event 变更提示任务保存本身绝不等待目录的 SQLite I/Ocatalog.go。设计要点投影可以随时删除、重建、损坏但任务的真实状态、并发控制与操作许可永远由 FileStore 的 snapshot、idempotency、lock、CAS、lease 决定。Task Catalog 只是一个读缓存这正是它被称为可丢弃的原因。二、存储布局v1.sqlite与 Schema 结构Task Catalog 的数据库路径由DefaultPath()计算func DefaultPath() string { cache : strings.TrimSpace(config.CacheDir()) if cache { return } return filepath.Join(cache, task-catalog, v1.sqlite) }catalog.go当 cache 目录不可用返回空串时Open会退化为内存投影in-memory projection保证目录能力在无缓存环境下依然可用catalog.go。数据库通过internal/projectiondb打开最多保持 4 个并发连接。Schema v1 共五张核心表catalog.go表名作用主键task_state单行版本号表revision每次写入递增id1单行约束task_projects已注册项目root、label、扫描代数scan_generation、扫描游标、索引状态project_keytask_snapshots任务快照投影含完整snapshot_jsonBLOB 与冗余查询列(project_key, task_id)task_event_sources事件 JSONL 文件的索引游标offset、size、fingerprint(project_key, task_id)task_events已索引事件行冗余 state/runtime_state 与原始event_jsonBLOB(project_key, task_id, sequence)配套索引覆盖了三种典型查询路径idx_task_project_page (project_key, updated_at DESC, task_id)按项目分页idx_task_state_page (state, updated_at DESC, project_key, task_id)按状态过滤分页idx_task_session (session_id, updated_at DESC, task_id)按会话分页idx_task_events_page (project_key, task_id, sequence)事件顺序读取。task_snapshots与task_projects之间建立了FOREIGN KEY ... ON DELETE CASCADE项目删除时快照级联清理。快照行中冗余保存state、runtime_state、runtime_lease_until、version、error_code、snapshot_fingerprint等查询/校验列原始 JSON 完整存于snapshot_json BLOB页面渲染时反序列化后调用ReconcileRuntime校正运行时状态catalog.go、catalog.go。三、Project Keycanonical root 的完整 SHA-256跨项目查询的前提是项目标识的确定性。Task Catalog 使用规范化后的项目根目录的完整 SHA-256作为project_keyfunc ProjectKey(root string) string { root filepath.Clean(strings.TrimSpace(root)) if abs, err : filepath.Abs(root); err nil { root abs } sum : sha256.Sum256([]byte(root)) return hex.EncodeToString(sum[:]) }catalog.go要点ProjectKey对传入 root 先filepath.Clean再去空白、再转绝对路径保证同一目录的不同书写形式如./proj与/abs/proj得到同一个 key。每次 action 都会先解析 key再由 control service 重读权威 snapshot 做决策docs/TASK_CATALOG.zh-CN.md 第 12-13 行确保投影中的快照只用于展示不用于控制判断。四、增量索引与对账机制Task Catalog 的索引策略是快照主动、事件惰性并配合后台对账保证一致性。4.1 有界批次优先索引快照ObservedFileStore只在 per-task 锁释放后发送非阻塞的SnapshotChanged/EventsChanged提示shared.go。Catalog 收到提示后将请求投递到容量 1024 的queue通道catalog.go队列满时退化为dirtyProjects脏标记 dirtyWake唤醒防止阻塞任务保存路径工作协程worker从队列取出请求indexSnapshot读取权威 snapshot 并 upsert 到task_snapshots每次写入使 revision 1catalog.go。4.2 事件日志惰性索引event log 是惰性的仅在任务展开、事件查询或追加新事件时才索引docs/TASK_CATALOG.zh-CN.md 第 8 行。indexEvents的核心是byte offset fingerprint 断点续传通过task_event_sources记录上次索引的indexed_offset、文件size与fingerprintsize:modtime若文件 shrink、fingerprint 变化或记录缺失则判定为 reset从 offset 0 重读并重建事件行catalog.go正常追加时调用store.ReadEventTail只读新增尾部INSERT OR REPLACE写回并推进 checkpoint。4.3 后台对账ReconcileProjectworker 每分钟把已注册项目标记为脏catalog.go随后执行ReconcileProject全量对账获取 per-project 锁project_lock.go读取权威任务列表scan_generation1标记为scanning逐个 upsert 快照带当前 generation标记本轮未见到的任务为missing并写入missing_since时间戳超过missingGrace30 秒宽限期的缺失任务级联删除其事件与事件源再删除快照本身catalog.go事务内将项目置为ready并 bump revision。过期 lease 只在读取时对账不回写投影——读取侧通过ReconcileRuntime(time.Now())在渲染时校正运行时状态绝不让目录反向污染权威数据catalog.go。五、分页查询协议Page / EventPage 与游标5.1 任务分页PageListPage接受PageRequest{ProjectKeys, SessionID, States, Query, Cursor, Limit}返回Page{Items, NextCursor, Revision, Partial, StaleCursor, Status}catalog.go。Limit 约束默认DefaultLimit50上限MaxLimit200catalog.go游标Base64(RawURLEncoding) 编码的{Revision, Updated, Project, Task}四元组catalog.go一致性保证游标携带读取时的 revision若翻页时 revision 已变化返回StaleCursortrue客户端应重新发起首屏查询过滤组合项目 keys、session_id、state 列表、自由文本 query匹配 task_id/session_id/error_code大小写不敏感可任意叠加部分性标志Partialtrue表示仍有项目处于pending未索引完成返回的页面可能不完整。排序规则为updated_at DESC, project_key, task_id翻页采用 keyset 条件推进保证大数据量下分页稳定。5.2 事件分页EventPageListEventPage(projectKey, taskID, after, limit)按sequence顺序读取事件读取前先触发一次惰性indexEvents若索引失败返回Partialtrue但不中断查询NextSequence返回下一次续读的起始序号供增量拉取使用catalog.go。六、故障降级与坏数据处理Task Catalog 的核心承诺是投影损坏绝不拖垮任务控制。坏 snapshot 或坏 event line只降级单个任务ListPage反序列化失败的行直接跳过continue不中断整页catalog.go事件行 JSON 解析失败同样跳过未索引完成的项目表现为Pending 0与Partialtrue查询仍可返回已完成项目的部分结果Status结构体提供State/Mode/Path/Revision/Indexed/Total/Pending/Failed/LastError完整诊断信息catalog.gorefresh在每次写入后重算统计catalog.go。七、运维命令doctor 与 reindexTask Catalog 提供两条 CLI 命令docs/TASK_CATALOG.zh-CN.md 第 16-19 行reasonix doctor catalogs [--json] reasonix catalogs reindex tasks [--project PATH ...] [--json]7.1 诊断reasonix doctor catalogsdoctorCatalogsCommanddoctor.go对会话目录及所有已注册的投影目录执行只读检查2 秒超时保护。文本输出示例Reasonix disposable catalogs sessions ok schema1 size... pathcache/session-catalog/v1.sqlite tasks ok schema1 size... pathcache/task-catalog/v1.sqlite每行展示name / state / schema / size / path--json输出结构化的catalogInspection数组含Info.Integrity等字段适合脚本与监控集成。7.2 重建reasonix catalogs reindex tasksreindexTaskCatalogcatalogs_tasks.go执行完整重建--project PATH可重复传入限定参与重建的项目根目录未指定--project时默认从会话目录的目标集合中收集全部有 workspace root 的项目底层taskcatalog.Rebuild先把权威 snapshot 重放到校验过的兄弟数据库projectiondb.Rebuild全部成功后原子替换发布失败则保留原库rebuild.go——即重建只替换可丢弃投影绝不触碰权威数据重建期间共享目录sharedManager进入rebuilding状态新注册请求进入 pending 队列重建完成后统一补注册shared.go事件日志在重建后仍保持惰性任务展开时再索引。因此Catalog 损坏或未完成索引不会禁用任务控制reindex只是把可丢弃的投影换新。八、与 Desktop Task Center 的配合Desktop Task Center 是 Task Catalog 的主要消费方支持对当前会话、当前项目、全部已注册项目三种范围分页docs/TASK_CATALOG.zh-CN.md 第 12 行前端发起带ProjectKeys的分页请求每次 action 先解析 canonical project key由 control service重读权威 snapshot判断任务真实状态再决定 stop/cancel/requeue 等操作目录只负责展示什么FileStore 负责能否操作。这种展示层投影 控制层权威的双轨架构保证了即使目录处于pending、损坏或正在重建任务的停止、取消、恢复与会话打开等关键操作也永远可用。结语Task Catalog 是 Reasonix prefix-cache 稳定性工程哲学在任务管理维度的体现以 SQLite 投影换取跨项目查询体验以可丢弃、可重建、坏行只降级单任务的边界守住任务控制的安全底线。理解其投影绝不影响控制、快照主动索引、事件惰性续传、reindex 原子替换四个设计原则即可放心地在脚本、监控与桌面 UI 中消费这一能力。延伸阅读本文所有结论均可在仓库源码中验证建议进一步阅读 internal/taskcatalog/catalog.go、internal/taskcatalog/rebuild.go、internal/taskcatalog/shared.go、internal/taskcatalog/catalog_test.go、internal/cli/catalogs_tasks.go 与 internal/cli/doctor.go 获取第一手实现细节。【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考