| 操作 | 数据源 |
|------|--------|
|
|
|
### 13.5 混合搜索（Hybrid Search）
**场景**：用户想搜 "Project X"（全文）且 "Status=Todo"（元数据）。
**实现逻辑**：
**命令示例**：
**时间筛选参数说明**：
| 参数 | 对应字段 | 说明 |
|------|----------|------|
|
|
|
|
|
|
**示例**：
### 13.6 批量操作与异步机制
针对 10,000+ 文件规模的操作优化：
**SQLite 事务批量写入**：
**Textual 异步 Workers**：
**进度反馈**：
- 操作耗时 > 500ms 时，TUI 底部状态栏显示 Spinner
- 批量操作（如 Refile 多个文件）显示进度条
---
## 14. 成功标准
1. 快速捕获到 Inbox 并高效处理
2. Johnny.Decimal 编号清晰组织（支持短 ID 和模糊匹配）
3. Git 完整审计追踪（Conventional Commits）
4. k9s 风格 TUI（列表/日历/时间线/图谱视图 + 命令面板）
5. CORE 工作流：捕获 → 组织 → 回顾 → 执行
6. 本地 Hook 优先 + GitHub Actions 远程通知
7. 仅 Markdown，仓库精简（`syn media` 处理附件）
8. Namespace 支持项目级配置
9. 10,000 资源列表 < 500ms（SQLite 索引 + 批量事务）
10. 多端同步无痛（自动 rebase + 智能字段合并）
11. Refile 时链接自动更新，永不断裂
12. 中文全文搜索精准（jieba 应用层分词）
13. 会话状态持久化，随时恢复上下文
---
## 15. 边缘情况处理
| 场景 | 处理方案 |
|------|----------|
| title 修改 | 文件名同步更新（包含 title），但链接仅使用 ID，不受影响 |
| Refile 链接断裂 | 自动全局搜索替换旧 ID → 新 ID（见 5.5） |
| 脏工作区 Refile | 拒绝操作，TUI 提供快捷 Commit/Stash 选项（见 5.5） |
| Refile 中途失败 | 前置检查确保工作区干净后，失败可安全回滚（见 5.5） |
| 短 ID 歧义 | CLI 报错列出候选项，TUI 弹窗二选一（见 3.2） |
| 并发编辑 | watchdog 实时监听 + Hash 检测（见 7.6） |
| watchdog 自激 | Git 操作期间暂停监听（SuspensionContext），避免误报（见 7.6） |
| 多端同步 | 启动 `pull --rebase`，退出 `push`，智能字段合并（见 7.4-7.5） |
| 索引损坏 |
| 大文件 |
| 耗时操作 | Textual @work 异步执行，底部显示进度（见 13.6） |
| 中文搜索噪音 | 停用词过滤 + 标点清理，减小索引体积（见 13.2） |
---
## 16. 范围外（初始版本）
**优先级低，预留设计的功能**：
- **§8 媒体管理**：初始版本仅支持外部链接，`syn media` 命令预留
- **§10 知识图谱**：初始版本不实现，预留
- **§11 邮件集成**：初始版本仅支持手动创建，API 集成预留
**明确排除的功能**：
- 完整 LLM GraphRAG（仅预留接口）
- 实时协作（多人同时编辑）
- Web/移动端
- 邮件 API 自动集成
- 自定义 FTS5 分词器（使用应用层分词替代）
---
## 附录 A：术语表
|------|--------|
|
syn list, syn search (Frontmatter) | SQLite ||
syn search --content (全文) | Ripgrep → 再查 SQLite 补充元数据 ||
syn show, syn edit | 实际 Markdown 文件 |### 13.5 混合搜索（Hybrid Search）
**场景**：用户想搜 "Project X"（全文）且 "Status=Todo"（元数据）。
**实现逻辑**：
1. Ripgrep 搜索全文 → 返回匹配文件路径列表
2. 用路径列表查询 SQLite → 过滤 Status=Todo
3. 返回最终结果（带完整元数据）
**命令示例**：
# 混合搜索：全文包含 "kubernetes" 且状态为 todo
syn search "kubernetes" --status todo
# 混合搜索：全文包含 "设计" 且标签包含 urgent
syn search "设计" --tag urgent
# 纯元数据搜索（due-before 基于 due 字段）
syn search --type task --priority high --due-before 2024-01-15
**时间筛选参数说明**：
| 参数 | 对应字段 | 说明 |
|------|----------|------|
|
--due-before | due | 截止日期早于指定日期的任务 ||
--due-after | due | 截止日期晚于指定日期的任务 ||
--created-before | created | 创建时间早于指定日期 ||
--created-after | created | 创建时间晚于指定日期 ||
--modified-before | modified | 修改时间早于指定日期 ||
--modified-after | modified | 修改时间晚于指定日期 |**示例**：
# 查找本周内到期的任务
syn search --type task --due-after monday --due-before sunday
# 查找过去 7 天修改过的笔记
syn search --type note --modified-after "7 days ago"
### 13.6 批量操作与异步机制
针对 10,000+ 文件规模的操作优化：
**SQLite 事务批量写入**：
# ❌ 错误：单条插入 1000 次 ≈ 5秒
for item in items:
cursor.execute("INSERT INTO resources ...", item)
conn.commit()
# ✅ 正确：事务批量插入 1000 次 ≈ 0.05秒
cursor.execute("BEGIN TRANSACTION")
for item in items:
cursor.execute("INSERT INTO resources ...", item)
cursor.execute("COMMIT")
**Textual 异步 Workers**：
from textual import work
class SynapseApp(App):
@work(exclusive=True)
async def action_batch_update_tags(self, ids: list, add_tag: str):
"""耗时操作放入后台线程，不阻塞 UI"""
self.notify("正在批量更新标签...")
# 执行文件 IO 和 DB 更新
await processor.batch_add_tag(ids, add_tag)
self.notify(f"✓ 已更新 {len(ids)} 个资源")
self.refresh_list()
**进度反馈**：
- 操作耗时 > 500ms 时，TUI 底部状态栏显示 Spinner
- 批量操作（如 Refile 多个文件）显示进度条
---
## 14. 成功标准
1. 快速捕获到 Inbox 并高效处理
2. Johnny.Decimal 编号清晰组织（支持短 ID 和模糊匹配）
3. Git 完整审计追踪（Conventional Commits）
4. k9s 风格 TUI（列表/日历/时间线/图谱视图 + 命令面板）
5. CORE 工作流：捕获 → 组织 → 回顾 → 执行
6. 本地 Hook 优先 + GitHub Actions 远程通知
7. 仅 Markdown，仓库精简（`syn media` 处理附件）
8. Namespace 支持项目级配置
9. 10,000 资源列表 < 500ms（SQLite 索引 + 批量事务）
10. 多端同步无痛（自动 rebase + 智能字段合并）
11. Refile 时链接自动更新，永不断裂
12. 中文全文搜索精准（jieba 应用层分词）
13. 会话状态持久化，随时恢复上下文
---
## 15. 边缘情况处理
| 场景 | 处理方案 |
|------|----------|
| title 修改 | 文件名同步更新（包含 title），但链接仅使用 ID，不受影响 |
| Refile 链接断裂 | 自动全局搜索替换旧 ID → 新 ID（见 5.5） |
| 脏工作区 Refile | 拒绝操作，TUI 提供快捷 Commit/Stash 选项（见 5.5） |
| Refile 中途失败 | 前置检查确保工作区干净后，失败可安全回滚（见 5.5） |
| 短 ID 歧义 | CLI 报错列出候选项，TUI 弹窗二选一（见 3.2） |
| 并发编辑 | watchdog 实时监听 + Hash 检测（见 7.6） |
| watchdog 自激 | Git 操作期间暂停监听（SuspensionContext），避免误报（见 7.6） |
| 多端同步 | 启动 `pull --rebase`，退出 `push`，智能字段合并（见 7.4-7.5） |
| 索引损坏 |
syn index rebuild 重建 || 大文件 |
.gitignore 排除，`syn media` 上传到外部存储 || 耗时操作 | Textual @work 异步执行，底部显示进度（见 13.6） |
| 中文搜索噪音 | 停用词过滤 + 标点清理，减小索引体积（见 13.2） |
---
## 16. 范围外（初始版本）
**优先级低，预留设计的功能**：
- **§8 媒体管理**：初始版本仅支持外部链接，`syn media` 命令预留
- **§10 知识图谱**：初始版本不实现，预留
syn graph 接口- **§11 邮件集成**：初始版本仅支持手动创建，API 集成预留
**明确排除的功能**：
- 完整 LLM GraphRAG（仅预留接口）
- 实时协作（多人同时编辑）
- Web/移动端
- 邮件 API 自动集成
- 自定义 FTS5 分词器（使用应用层分词替代）
---
## 附录 A：术语表
