**TUI 交互**：

13:31 · Dec 21, 2025 · Sun

**TUI 交互**：


┌─────────────────────────────────────────────────────────┐
│ ⚠️  Refile 需要干净的工作区                              │
├─────────────────────────────────────────────────────────┤
│ 检测到以下未提交的修改：                                 │
│   M  10/001/10.001.0005-note-学习笔记.md               │
│   M  20/001/20.001.0003-task-开发任务.md               │
│                                                         │
│ 请先提交或暂存这些修改：                                 │
│   [C] 快速提交 (commit -m 'WIP')                        │
│   [S] 暂存 (git stash)                                  │
│   [Q] 取消 Refile                                       │
└─────────────────────────────────────────────────────────┘

**行为**：
- Refile 前**必须检查**工作区状态
- 脏工作区时拒绝操作，提示用户先提交/暂存
- TUI 提供快捷操作：一键 Commit WIP 或 Stash
- 绝不丢失用户的其他修改

**更新的引用类型**：

| 引用形式 | 示例 | 搜索方式 | 更新方式 |
|----------|------|----------|----------|
| Wiki-style 链接 | [[10.001.0001]] | Ripgrep | 字符串替换 |
| Frontmatter related | related: ["10.001.0001"] | SQLite 索引 | 解析 YAML，更新数组 |

设计原则：精确引用更新，避免误改

⚠️ **不进行盲目的全文替换**：只更新明确的引用语法，不替换正文中的裸 ID 字符串。


---
related: ["10.001.0001"]  # ← YAML 数组，精确更新 ✓
---

# 设计说明

参考 [[10.001.0001]] 的架构思路...     # ← Wiki-style 链接，更新 ✓
任务 10.001.0001 定义了核心接口...      # ← 裸 ID，不更新 ✗（可能是历史描述）

为什么不替换裸 ID？
- 裸 ID 可能出现在非引用上下文：`"历史记录显示 10.001.0001 已于 2023 年完成"`
- 格式说明文本：`"ID 格式为 10.001.0001，其中 10 表示 Area..."`
- 盲目替换会导致语义错误和数据损坏
- 用户若需更新裸 ID，可通过 --dry-run 预览后手动处理

为什么 related 字段仍需 SQLite？

related 是 YAML 数组格式，直接全文替换可能破坏 YAML 结构：


# 原始
related: ["10.001.0001", "10.002.0003"]

# Ripgrep 替换后可能出现的问题（如果替换逻辑不够精确）
related: ["20.001.0005", "10.002.0003"]  # ✓ 正确
related: ["20.001.0005", "20.001.0005"]  # ✗ 如果 10.002.0003 也被误改

**SQLite 方案确保**：
- 查询精确定位到 related 字段
- 解析 JSON 数组后，只替换匹配的元素
- 重新序列化，保证 YAML 格式正确

**Refile 预览模式**：

为避免意外修改，支持 --dry-run 预览变更：


syn inbox move 00.000.0001 --to work-project --dry-run

# 输出预览：
Will refile: 00.000.0001 → 20.001.0003
Source file:
  R  inbox/00.000.0001-unprocessed-xxx.md → work-project/20/001/20.001.0003-task-xxx.md
     - Frontmatter: jd_number: "00.000.0001" → "20.001.0003"

References to update (2 files):
  M  personal/10/001/10.001.0005-note-设计笔记.md
     - Line 5: related: ["00.000.0001"] → ["20.001.0003"]
     - Line 12: [[00.000.0001]] → [[20.001.0003]]
  M  personal/10/002/10.002.0001-task-开发任务.md
     - Line 15: [[00.000.0001]] → [[20.001.0003]]

Skipped (bare IDs not updated):
  -  personal/10/003/10.003.0001-note-历史记录.md
     - Line 8: "任务 00.000.0001 已于 2023 年完成"（裸 ID，需手动处理）

Proceed? [y/N]

> **注意**：预览中的 "Skipped" 部分提示用户哪些裸 ID 不会被自动更新，用户可根据需要手动处理。

---

## 6. 工作流与回顾

### 6.1 回顾类型

| 类型 | 触发 | 内容 |
|------|------|------|
| 每日 | syn review daily | 今日到期、今日会议、昨日未完成 |
| 每周 | syn review weekly | 本周完成、下周计划、项目进度 |
| Inbox | syn inbox process | 处理未分类项目 |

### 6.2 智能提醒

- 任务接近截止日期时高亮显示
- 资源长期未访问时在回顾中提示
- 阻塞任务链识别和提示

---

## 7. 存储与版本控制

### 7.1 Markdown 格式

**文件命名**：`{Area}.{Category}-{resource-type}-{title}.md`

**Frontmatter 示例**：


---
jd_number: "10.001.0015"
type: task
namespace: work-project
title: "完成项目设计"
status: in-progress
priority: high
due: 2024-01-15
created: 2024-01-01T10:00:00Z
modified: 2024-01-05T14:30:00Z
tags: [design, urgent]
related: ["10.001.0012", "10.002.0003"]
---

### 7.2 文件约束

- 仅允许 .md 文件
- 禁止图片、视频、音频等二进制文件
- 必须使用外部链接引用媒体资源
- .gitignore 配置忽略常见二进制格式

### 7.3 Git 集成

- 自动提交：所有 CRUD 操作
- commit 格式：Conventional Commits
- 支持多远程仓库
- 支持 SSH/HTTPS 认证

### 7.4 Git 同步策略

| 时机 | 动作 |
|------|------|
| syn 启动 | git pull --rebase |
| CRUD 操作 | git add + git commit |
| syn 退出 / syn sync | git push |

### 7.5 智能冲突合并

**问题**：多端同步时，`modified` 时间戳经常冲突。

**方案**：自定义 Git merge driver + 细粒度字段策略


# .gitattributes
*.md merge=synapse-frontmatter


# .git/config 或全局配置
[merge "synapse-frontmatter"]
    name = Synapse Frontmatter Merge
    driver = syn merge-driver %O %A %B %P