STDD 分析：分支感知的 spr update

STDD 分析：分支感知的 spr update 设计

Phase 1: Spec — 你的设计

核心思想：spr update iter 应自动处理分支切换和本地代码保护：

spr update <branch>
  │
  ├─ 保存现场
  │   ├─ 记录当前分支名
  │   └─ stash 未提交变更
  │
  ├─ 切换到目标分支
  │   └─ git checkout <branch>
  │
  ├─ git pull（已最新则跳过拉取，继续安装）
  │
  ├─ 安装/升级 skill
  │   └─ 同步到 Hermes skills 目录
  │
  └─ 恢复现场
      ├─ 切回原始分支
      ├─ pop stash
      └─ 报告结果

Phase 2: Verify — 场景覆盖

Phase 3: Refactor — 实现

直接在原有的 scripts/spr Python CLI 中增强 cmd_update()：

新增两个核心函数：

def save_git_state(repo_dir):
    """保存当前分支 + stash 未提交变更"""
    # 记录 branch name
    # git status --porcelain 判断是否 dirty
    # 如果 dirty → git stash push -m "spr-update-auto-stash-{ts}"
    # 返回 {branch, stashed, stash_msg}

def restore_git_state(repo_dir, state, error=False):
    """恢复 git 状态
    - error=True:  恢复分支，不 pop stash（留待手动处理）
    - error=False: 恢复分支 + pop stash
    """
    # git checkout original_branch
    # 如果成功且不是 error 路径 → git stash pop

cmd_update 改为 try/except/else 包装：

def cmd_update(args):
    ref = args[0] if args else None
    state = save_git_state(repo_dir)

    try:
        if ref:  update_from_ref(repo_dir, ref, v)
        else:    update_default(repo_dir, v)
    except BaseException:
        restore_git_state(repo_dir, state, error=True)
        raise
    else:
        restore_git_state(repo_dir, state, error=False)

错误处理策略

按你的要求：任何冲突 → 报错退出 → 用户看到错误信息 → 手动处理。

• git pull 冲突：pull 返回 non-zero → 脚本 sys.exit(1) → finally 恢复分支 → 错误消息输出到 stdout，AI 转发给用户
• stash pop 冲突：stash entry 保留不删 → 用户手动 git stash list / git stash drop
• 分支恢复失败：打印手动修复命令（git checkout {branch}），不自动重试

SKILL.md 对应更新

旧的 8 步 AI 流程（手动 git pull → 判断 → cp → commit）替换为 3 步：

Step 1 — skill_view(name='spr')
Step 2 — ~/skill-portfolio-report/scripts/spr update [branch]
Step 3 — 读取 CLI 输出并转发给用户

关键原则：AI 不做任何额外的 git 操作。所有 git 逻辑交给 CLI 脚本。

文件变更清单

• scripts/spr — +65 lines (save_git_state, restore_git_state, wrapper logic)
• SKILL.md — 简化 spr update 流程，删除 33 行旧 AI 步骤，新增 23 行委托式流程
• VERSION.json — 更新 commit_id 至 ff6a381

git 提交

• b5ed2f7 — feat: branch-aware spr update with stash/restore
• ff6a381 — docs: simplify spr update to CLI delegation