sync-docs

/sync-docs — 项目文档同步

把当前 git 仓库的最近变更同步到对应 Obsidian 项目的 activeContext.md，并刷新 首页.md 的项目活跃状态。

执行流程

1. 解析 vault 路径

按优先级取：

1. 命令参数 $ARGUMENTS（如 /sync-docs ~/Documents/MyVault）

2. 环境变量 $OBSIDIAN_VAULT_PATH

3. 都没有 → 报错并提示用户配置：

   未找到 Obsidian vault。请：
   - 在 ~/.claude/settings.json 的 env 里设置 OBSIDIAN_VAULT_PATH，或
   - 直接传参：/sync-docs <vault 路径>
   

   不要随便猜默认路径。

2. 匹配当前项目

git rev-parse --show-toplevel    # CODE_ROOT

读取 $VAULT_PATH/CLAUDE.md，解析"项目 ↔ 代码仓库映射"表（markdown 表格），找到 代码路径 列等于 CODE_ROOT（或 CODE_ROOT 是其前缀展开）的那一行，取出 Obsidian 路径（形如 项目/<name>/）。

匹配不到就用 AskUserQuestion 让用户从已存在的项目列表里选，或者提示用 /add-project 先注册。

3. 收集最近一次提交

git log -1 --format="%h|%s|%ai|%an"
git diff HEAD~1 --name-only

如果是首次提交（没有 HEAD~1），用 git show --name-only HEAD 取文件列表。

4. 检测架构变更

把变更文件名跟以下模式做匹配（语言无关，覆盖大多数项目）：

• *.proto *_proto.*
• **/architecture/* **/arch/*
• **/middleware/*
• 项目根的 Makefile Dockerfile go.mod package.json pyproject.toml Cargo.toml pom.xml
• **/SKILL.md .claude/skills/**
• config*.yaml config*.yml

命中任何一个就标记 arch_changed=true。

5. 更新 Obsidian activeContext.md

打开 $VAULT_PATH/<obsidian_project_path>/activeContext.md，在 ## 最近改了什么（最近 1-2 次会话） 区域顶部插入一行：

- <YYYY-MM-DD> `<short_sha>` <commit_message>

规则：

• 该区域只保留最新 5 条，更早的删掉
• 如果最新 sha 已存在，跳过（防重复）
• 如果区域不存在，提示用户文件结构异常，让其检查模板

6. 更新首页项目活跃状态

打开 $VAULT_PATH/首页.md，找到"项目列表"表格里 obsidian 路径匹配当前项目的那一行，把"状态"列更新为：

进行中（YYYY-MM-DD）

只动这一个 cell，不要改其他列。如果该列原本是「维护中」「已暂停」等用户手填状态，跳过更新（人工设置优先）—— 仅当原值是「进行中」或为空时才覆盖。

7. 检查 CLAUDE.md 是否有需要迁移的旧结构

v0.5 以后，"最近变更"由 activeContext.md 承载，CLAUDE.md 不再有此段。

• 如果 $CODE_ROOT/CLAUDE.md 仍包含 ## 最近变更 段 → 输出提醒：

  ⚠️ 检测到旧版 CLAUDE.md 结构（含"最近变更"段）。
     建议用 /update-memory 迁移到 v0.5 新骨架，将"最近变更"移到 activeContext.md。
     本次 /sync-docs 仍会更新该段，但后续请迁移。
  

  并继续向旧 ## 最近变更 写入（向下兼容，防已有文件断更）
• 如果没有 ## 最近变更 段（已是 v0.5 结构）→ 跳过，什么都不写

8. 刷新 CLAUDE.md 的"Obsidian 文档地图"段