@hupan56/wlkj 2.2.1 → 2.2.3

package/bin/cli.js

@@ -337,6 +337,8 @@ function doHelp() {
   console.log("=== 环境安装 (什么都没装时先跑这个) ===");
   console.log("  npx @hupan56/wlkj install-env       检测+自动装 Node/Python/git");
   console.log("  npx @hupan56/wlkj install-env --check  只检测不装");
+  console.log("  npx @hupan56/wlkj install-env --location D:\\wldev  指定安装目录");
+  console.log("  npx @hupan56/wlkj add-path D:\\wldev\\nodejs  把目录加到系统 PATH");
   console.log("");
   console.log("=== 一键安装 (装好环境后) ===");
   console.log("  npx @hupan56/wlkj init [你的名字]    安装完整引擎 + 自动初始化");
@@ -364,9 +366,20 @@ function doHelp() {
   console.log("");
 }
 
-function doInstallEnv(checkOnly = false) {
+function doInstallEnv(checkOnly = false, location = null) {
   const { execSync } = require("child_process");
+  const isWin = process.platform === "win32";
+  const isMac = process.platform === "darwin";
+
+  // 解析 --location（CLI 入口已提取，这里兜底）
   console.log("\n=== 环境检测 ===\n");
+  if (location) {
+    console.log(`  安装位置: ${location}${isWin ? "" : " (仅 Windows winget 支持指定目录)"}`);
+    // Windows: 预建目录
+    if (isWin) {
+      try { fs.mkdirSync(location, { recursive: true }); } catch { /* */ }
+    }
+  }
 
   // 检测函数
   function check(cmd) {
@@ -377,15 +390,25 @@ function doInstallEnv(checkOnly = false) {
     try { execSync(`where ${cmd}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" }); return true; }
     catch { try { execSync(`which ${cmd}`, { encoding: "utf-8", timeout: 3000, stdio: "pipe" }); return true; } catch { return false; } }
   }
+  // Windows: 把目录加到用户 PATH（幂等，已存在不重复加）
+  function addToPathWin(dir) {
+    if (!isWin) return false;
+    try {
+      // 用 setx 会截断超长 PATH，改用 PowerShell 读 User PATH 追加
+      const ps = `powershell -NoProfile -Command "$p=[Environment]::GetEnvironmentVariable('Path','User'); if($p -notlike '*{dir}*'){[Environment]::SetEnvironmentVariable('Path',$p.TrimEnd(';')+';{dir}','User')}"`.replace(/{dir}/g, dir.replace(/\\/g, "\\\\"));
+      execSync(ps, { stdio: "pipe", timeout: 15000 });
+      return true;
+    } catch (e) { console.log(`  [WARN] 加 PATH 失败（可手动加）: ${dir}`); return false; }
+  }
   function install(name, wingetId, brewPkg) {
     if (checkOnly) return false;
-    const isWin = process.platform === "win32";
-    const isMac = process.platform === "darwin";
     try {
       if (isWin && has("winget")) {
         console.log(`  用 winget 装 ${name}...`);
-        execSync(`winget install --id ${wingetId} -e --source winget --accept-source-agreements --accept-package-agreements`,
-          { stdio: "inherit", timeout: 300000 });
+        // winget --location 不一定被安装包尊重，但先传上
+        let cmd = `winget install --id ${wingetId} -e --source winget --accept-source-agreements --accept-package-agreements`;
+        if (location) cmd += ` --location "${location}"`;
+        execSync(cmd, { stdio: "inherit", timeout: 300000 });
         return true;
       } else if (isMac && has("brew")) {
         console.log(`  用 brew 装 ${name}...`);
@@ -435,6 +458,20 @@ function doInstallEnv(checkOnly = false) {
     else { need.push("git (手动: https://git-scm.com, 可选)"); }
   }
 
+  // --location 模式: 提示用户验证安装位置 + 手动加 PATH
+  // （winget 的 --location 对 Node/Python 不一定生效，需用户确认）
+  if (location && isWin) {
+    console.log(`\n--- 安装位置确认 ---`);
+    console.log(`  你指定了: ${location}`);
+    console.log(`  注意: winget 的 --location 对 Node.js/Python 不一定生效`);
+    console.log(`        (取决于安装包是否支持自定义路径)`);
+    console.log(`  请检查实际装到哪了:`);
+    console.log(`    重新打开终端后跑: node --version  python --version  git --version`);
+    console.log(`  如果某软件没进 PATH, 手动把它加进去:`);
+    console.log(`    设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → Path → 新建`);
+    console.log(`    或用命令: npx @hupan56/wlkj add-path "D:\\wldev\\nodejs"`);
+  }
+
   console.log("\n=== 结果 ===");
   if (need.length === 0) {
     console.log("  环境就绪! 下一步: npx @hupan56/wlkj init");
@@ -445,13 +482,46 @@ function doInstallEnv(checkOnly = false) {
   }
 }
 
+// add-path: 把目录加到 Windows 用户 PATH（幂等）
+function doAddPath(dir) {
+  if (!dir) { console.log("用法: npx @hupan56/wlkj add-path <目录>"); return; }
+  if (process.platform !== "win32") {
+    console.log("add-path 仅支持 Windows。Mac/Linux 请手动加到 ~/.zshrc 或 ~/.bashrc");
+    return;
+  }
+  const abs = path.resolve(dir);
+  if (!fs.existsSync(abs)) {
+    console.log(`[警告] 目录不存在: ${abs}（仍会加到 PATH）`);
+  }
+  try {
+    const ps = `powershell -NoProfile -Command "$p=[Environment]::GetEnvironmentVariable('Path','User'); if($p -notlike '*${abs.replace(/\\/g,"\\\\")}*'){[Environment]::SetEnvironmentVariable('Path',$p.TrimEnd(';')+';${abs.replace(/\\/g,"\\\\")}','User'); Write-Output 'ADDED'} else { Write-Output 'EXISTS' }"`;
+    const out = execSync(ps, { encoding: "utf-8", timeout: 15000 }).trim();
+    console.log(`  ${out === "ADDED" ? "已加入" : "已存在(无需重复加)"}: ${abs}`);
+    console.log(`  ⚠ 需要重新打开终端才生效`);
+  } catch (e) {
+    console.log(`  失败: ${(e.message || "").slice(0, 100)}`);
+    console.log(`  手动加: 设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → Path → 新建 → ${abs}`);
+  }
+}
+
 const [,, cmd, ...rest] = process.argv;
 const mapped = rest.map(a => a === "-p" ? "--priority" : a);
 
 switch (cmd) {
   case "init": doInit(rest[0]); break;
   case "update": case "upgrade": doUpdate(); break;
-  case "install-env": doInstallEnv(rest[0] === "--check"); break;
+  case "install-env": {
+    const checkOnly = rest.includes("--check");
+    // 提取 --location <dir> 或 --location=<dir>
+    let loc = null;
+    const li = rest.indexOf("--location");
+    if (li !== -1 && rest[li + 1]) loc = rest[li + 1];
+    const eq = rest.find(a => a.startsWith("--location="));
+    if (eq) loc = eq.slice("--location=".length);
+    doInstallEnv(checkOnly, loc);
+    break;
+  }
+  case "add-path": doAddPath(rest[0]); break;
   case "task": process.stdout.write(py("task.py", mapped)); break;
   case "status": doStatus(); break;
   case "session": process.stdout.write(py("add_session.py", rest)); break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hupan56/wlkj",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "AI Product R&D Workflow - PRD/Prototype/Search/Task/Report",
   "bin": {
     "wlkj": "bin/cli.js"

package/templates/qoder/scripts/common/reqid.py

@@ -131,33 +131,46 @@ def validate_req_ids(prd_paths: List[str], repo_root: Union[str, Path]) -> None:
       (b) NNN 不能超过当前计数器 (防跳号/未来号; 但允许 NNN == 已分配的号,
           因为可能是修改已有 PRD)
       (c) 同一批无重复 ID
+      (d) 与全仓库已存在的 REQ 文件无撞号 (跨人离线分叉检测)
 
     注意: 允许 NNN <= 计数器, 因为可能是更新已有 PRD (合法)。
-    撞号只在"同一批出现两个相同 ID"或"NNN 超过计数器"时报错。
+    撞号在"同一批出现两个相同 ID"、"NNN 超过计数器"、或"与全库已有同号文件冲突"时报错。
+    例外: 同号但文件名完全相同 (修改自己已 push 的 PRD) 视为合法更新。
     """
     seen = {}
     errors = []
+    # 全库已有 REQ-ID (用于跨人撞号检测)
+    existing = scan_existing_req_ids(repo_root)
+
     for p in prd_paths:
         parsed = parse_req_id(p)
         if not parsed:
             errors.append("%s: 文件名无 REQ-{YYYY}-{NNN}" % os.path.basename(p))
             continue
         year, n = parsed
-        # 同批重复检测
         key = (year, n)
+        basename = os.path.basename(p)
+        # 同批重复检测
         if key in seen:
             errors.append(
                 "撞号: %s 和 %s 都是 REQ-%d-%03d"
-                % (os.path.basename(seen[key]), os.path.basename(p), year, n)
+                % (os.path.basename(seen[key]), basename, year, n)
             )
         else:
             seen[key] = p
+        # 跨人/全库撞号检测: 该号已存在于仓库, 且不是同一个文件 (允许修改自己的)
+        if key in existing and os.path.basename(existing[key]) != basename:
+            errors.append(
+                "撞号: %s 与仓库已有的 %s 都是 REQ-%d-%03d "
+                "(两人离线各建了同号 PRD? 请改其中一个的编号)"
+                % (basename, os.path.basename(existing[key]), year, n)
+            )
         # 超界检测 (NNN 不能超过计数器, 防止跳号)
         max_n = current_counter(str(year), repo_root)
         if max_n > 0 and n > max_n:
             errors.append(
                 "%s: REQ-%d-%03d 超过计数器最大值 %d (跳号?)"
-                % (os.path.basename(p), year, n, max_n)
+                % (basename, year, n, max_n)
             )
     if errors:
         raise ReqIdError("[gate] 拒绝: REQ-ID 校验失败:\n  " + "\n  ".join(errors))
@@ -216,3 +229,41 @@ def migrate_from_existing(repo_root: Optional[Union[str, Path]] = None) -> dict:
         return counter
     finally:
         lock.release()
+
+
+def scan_existing_req_ids(repo_root: Optional[Union[str, Path]] = None) -> dict:
+    """扫描全仓库已存在的 REQ-{YYYY}-{NNN} 文件, 返回 {(year, n): filepath} 字典。
+
+    用于 push 门禁时的跨人撞号检测: 两个成员离线各建了 REQ-005,
+    单看各自批次不重复, 但全库已有该号 → 撞号。
+    """
+    if repo_root is None:
+        repo_root = Path(get_repo_root())
+    else:
+        repo_root = Path(repo_root)
+
+    scan_dirs = [
+        repo_root / "data" / "docs" / "prd",
+        repo_root / "workspace" / "specs" / "prd",
+    ]
+    members_dir = repo_root / "workspace" / "members"
+    if members_dir.is_dir():
+        for m in members_dir.iterdir():
+            d = m / "drafts"
+            if d.is_dir():
+                scan_dirs.append(d)
+
+    existing = {}
+    for d in scan_dirs:
+        if not d.is_dir():
+            continue
+        try:
+            for f in d.iterdir():
+                if not f.is_file() or not f.name.lower().endswith(".md"):
+                    continue
+                parsed = parse_req_id(f.name)
+                if parsed:
+                    existing[parsed] = str(f)
+        except OSError:
+            continue
+    return existing

package/templates/qoder/scripts/common/task_utils.py

@@ -147,6 +147,52 @@ def write_task_json(task_dir: Path, data: dict) -> bool:
         return False
 
 
+def modify_task_json(task_dir: Path, mutator, timeout: float = 15.0):
+    """在文件锁内 load → mutator(data) → write, 保证并发 read-modify-write 原子。
+
+    解决两个成员同时改同一任务 (一个改 status, 一个改 due) 的丢更新问题。
+    锁是每任务粒度 (task_dir/.task.lock), 不同任务互不阻塞。
+
+    Args:
+        task_dir: 任务目录。
+        mutator: 接收 data dict, 就地修改它 (返回值忽略)。
+        timeout: 获取锁的等待秒数。
+
+    Returns:
+        成功 (修改并写入) 返回 True; 加载失败返回 False。
+    """
+    try:
+        from .filelock import FileLock, LockTimeoutError
+    except ImportError:
+        # filelock 不可用 → 降级为无锁 (保留旧行为, 不阻塞功能)
+        data = load_task_json(task_dir)
+        if data is None:
+            return False
+        mutator(data)
+        return write_task_json(task_dir, data)
+
+    lock_path = task_dir / ".task.lock"
+    lock = FileLock(str(lock_path), timeout=timeout, stale_seconds=300)
+    try:
+        lock.acquire()
+    except LockTimeoutError as e:
+        print(f"Warning: task lock busy ({task_dir.name}): {e}", file=sys.stderr)
+        # 降级: 不阻塞, 直接写 (好过完全失败)
+        data = load_task_json(task_dir)
+        if data is None:
+            return False
+        mutator(data)
+        return write_task_json(task_dir, data)
+    try:
+        data = load_task_json(task_dir)
+        if data is None:
+            return False
+        mutator(data)
+        return write_task_json(task_dir, data)
+    finally:
+        lock.release()
+
+
 # =============================================================================
 # ACL: 任务操作权限校验 (零信任)
 # =============================================================================

package/templates/qoder/scripts/syncgate.py

@@ -324,7 +324,10 @@ def run_gates(
     except GateFailure as e:
         return False, str(e)
     except Exception as e:
-        # ReqIdError 等也包装成 GateFailure 风格
-        if 'REQ-ID' in str(e) or '撞号' in str(e):
-            return False, str(e)
-        raise
+        # ReqIdError / AtomicIOError 等也包装成 GateFailure 风格, 不让原始
+        # traceback 冒泡到产品经理眼前
+        msg = str(e)
+        if 'REQ-ID' in msg or '撞号' in msg or 'REQ' in msg:
+            return False, msg
+        # 其他意外异常: 返回友好错误而非崩溃栈
+        return False, '[gate] 门禁检查遇到意外错误 (非门禁失败, 请重试或检查环境): ' + msg[:200]

package/templates/qoder/scripts/task.py

@@ -57,6 +57,7 @@ from common.task_utils import (
     run_task_hooks,
     load_task_json,
     write_task_json,
+    modify_task_json,
     assert_can_modify_task,
 )
 
@@ -222,18 +223,17 @@ def cmd_start(args: argparse.Namespace) -> int:
         print(f"Current task set to: {task_dir}")
         print(f"Source: {active.source}")
 
-        # 更新 task.json 状态
-        task_data = load_task_json(full_path)
-        if task_data and task_data.get("status") == "planning":
-            now_iso = datetime.now().isoformat()
-            task_data["status"] = "in_progress"
-            task_data["updated_at"] = now_iso
-            # B3: 记录阶段时间戳
-            stage_ts = task_data.get("stage_ts") or {}
-            stage_ts["started"] = now_iso
-            task_data["stage_ts"] = stage_ts
-            write_task_json(full_path, task_data)
-            print("Status: planning -> in_progress")
+        # 更新 task.json 状态 (锁内 load-modify-write, 防并发丢更新)
+        def _start_mutator(data):
+            if data.get("status") == "planning":
+                now_iso = datetime.now().isoformat()
+                data["status"] = "in_progress"
+                data["updated_at"] = now_iso
+                stage_ts = data.get("stage_ts") or {}
+                stage_ts["started"] = now_iso
+                data["stage_ts"] = stage_ts
+                print("Status: planning -> in_progress")
+        modify_task_json(full_path, _start_mutator)
 
         # 运行 after_start 钩子
         run_task_hooks("after_start", full_path / FILE_TASK_JSON, repo_root)
@@ -293,33 +293,37 @@ def cmd_finish(args: argparse.Namespace) -> int:
         # 已清了 active 指针, 但不改 status —— 让用户重新 start 再由正确的人 finish
         return 4  # authz_denied
 
-    task_data = load_task_json(task_dir)
-    if task_data and task_data.get("status") != "completed":
-        now_iso = datetime.now().isoformat()
-        task_data["status"] = "completed"
-        task_data["updated_at"] = now_iso
-        # B3: 记录完成时间戳
-        stage_ts = task_data.get("stage_ts") or {}
-        stage_ts["completed"] = now_iso
-        task_data["stage_ts"] = stage_ts
-        write_task_json(task_dir, task_data)
-        print("Status: -> completed")
-
-        # D2: 飞书通知 (任务完成)
+    # 锁内 load-modify-write, 防并发丢更新; 副作用 (飞书) 在锁外做
+    _finish_ctx = {}
+    def _finish_mutator(data):
+        if data.get("status") != "completed":
+            now_iso = datetime.now().isoformat()
+            data["status"] = "completed"
+            data["updated_at"] = now_iso
+            stage_ts = data.get("stage_ts") or {}
+            stage_ts["completed"] = now_iso
+            data["stage_ts"] = stage_ts
+            print("Status: -> completed")
+            _finish_ctx["now_iso"] = now_iso
+            _finish_ctx["stage_ts"] = stage_ts
+            _finish_ctx["assignee"] = data.get("assignee", "?")
+    modify_task_json(task_dir, _finish_mutator)
+
+    # D2: 飞书通知 (任务完成) —— 在锁外, 用 mutator 捕获的值
+    if _finish_ctx:
         try:
             from common.feishu import notify_task_finished
-            # 算用时
             hours = None
-            started = stage_ts.get("started")
+            started = _finish_ctx["stage_ts"].get("started")
             if started:
                 try:
                     from datetime import datetime as _dt
                     t_start = _dt.fromisoformat(started)
-                    t_end = _dt.fromisoformat(now_iso)
+                    t_end = _dt.fromisoformat(_finish_ctx["now_iso"])
                     hours = (t_end - t_start).total_seconds() / 3600
                 except (ValueError, TypeError):
                     pass
-            notify_task_finished(task_dir.name, task_data.get("assignee", "?"), hours)
+            notify_task_finished(task_dir.name, _finish_ctx["assignee"], hours)
         except Exception:
             pass  # 飞书失败不阻塞任务完成
 
@@ -330,6 +334,44 @@ def cmd_finish(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cleanup_orphaned_refs(archived_task_name: str, repo_root) -> int:
+    """归档任务后, 清理其它任务中对它的引用 (blocked_by/blocks/children/parent)。
+
+    不清理 → 僵尸任务永远 blocked, resolve_task_dir 找不到引用对象。
+    返回清理的引用数。
+    """
+    tasks_dir = get_tasks_dir(repo_root)
+    if not tasks_dir.is_dir():
+        return 0
+    cleaned = 0
+    for task_subdir in tasks_dir.iterdir():
+        if not task_subdir.is_dir() or task_subdir.name == archived_task_name:
+            continue
+        task_json = task_subdir / FILE_TASK_JSON
+        if not task_json.is_file():
+            continue
+        changed = False
+
+        def _purge_refs(data):
+            nonlocal changed
+            for field in ("blocked_by", "blocks", "children"):
+                lst = data.get(field)
+                if isinstance(lst, list) and archived_task_name in lst:
+                    data[field] = [x for x in lst if x != archived_task_name]
+                    changed = True
+            # parent 是单值字段
+            if data.get("parent") == archived_task_name:
+                data["parent"] = None
+                changed = True
+            if changed:
+                data["updated_at"] = datetime.now().isoformat()
+
+        modify_task_json(task_subdir, _purge_refs)
+        if changed:
+            cleaned += 1
+    return cleaned
+
+
 # =============================================================================
 # 命令: archive
 # =============================================================================
@@ -379,12 +421,18 @@ def cmd_archive(args: argparse.Namespace) -> int:
     # 运行 after_archive 钩子
     run_task_hooks("after_archive", dest / FILE_TASK_JSON, repo_root)
 
+    # 清理孤儿依赖: 其它任务可能引用了本任务 (blocked_by/blocks/children/parent),
+    # 归档后这些引用变成死链 → 僵尸任务永远 blocked。扫描并移除。
+    cleaned = _cleanup_orphaned_refs(full_path.name, repo_root)
+
     # 清除可能指向此任务的会话
     active = resolve_active_task(repo_root)
     if active.task_path and task_input in active.task_path:
         clear_active_task(repo_root)
 
     print(f"Task archived: {full_path.name} -> archive/{year_month}/{full_path.name}")
+    if cleaned:
+        print(f"  (已清理 {cleaned} 个其它任务中对它的依赖引用)")
     return 0
 
 
@@ -634,13 +682,12 @@ def cmd_set_due(args: argparse.Namespace) -> int:
     except PermissionError as e:
         print(str(e), file=sys.stderr)
         return 4
-    task_data = load_task_json(full_path)
-    if not task_data:
+    def _set_due_mutator(data):
+        data["due_date"] = args.due_date
+        data["updated_at"] = datetime.now().isoformat()
+    if not modify_task_json(full_path, _set_due_mutator):
         print("Error: Missing task.json", file=sys.stderr)
         return 1
-    task_data["due_date"] = args.due_date
-    task_data["updated_at"] = datetime.now().isoformat()
-    write_task_json(full_path, task_data)
     print(f"Set due_date: {args.due_date} ({full_path.name})")
     return 0
 
@@ -672,29 +719,32 @@ def cmd_block(args: argparse.Namespace) -> int:
               file=sys.stderr)
         return 1
 
-    # 更新 task.blocked_by
+    # 检查是否已存在依赖关系 (先读, 幂等)
     task_data = load_task_json(task_dir)
     if not task_data:
         print("Error: Missing task.json", file=sys.stderr)
         return 1
-    blocked_by = task_data.get("blocked_by") or []
-    if blocker_dir.name in blocked_by:
+    if blocker_dir.name in (task_data.get("blocked_by") or []):
         print(f"Already blocked by {blocker_dir.name}")
         return 0
-    blocked_by.append(blocker_dir.name)
-    task_data["blocked_by"] = blocked_by
-    task_data["updated_at"] = datetime.now().isoformat()
-    write_task_json(task_dir, task_data)
 
-    # 反向更新 blocker.blocks
-    blocker_data = load_task_json(blocker_dir)
-    if blocker_data:
-        blocks = blocker_data.get("blocks") or []
+    # 锁内更新 task.blocked_by
+    def _block_mutator(data):
+        blocked_by = data.get("blocked_by") or []
+        if blocker_dir.name not in blocked_by:
+            blocked_by.append(blocker_dir.name)
+            data["blocked_by"] = blocked_by
+            data["updated_at"] = datetime.now().isoformat()
+    modify_task_json(task_dir, _block_mutator)
+
+    # 锁内反向更新 blocker.blocks
+    def _block_reverse_mutator(data):
+        blocks = data.get("blocks") or []
         if task_dir.name not in blocks:
             blocks.append(task_dir.name)
-            blocker_data["blocks"] = blocks
-            blocker_data["updated_at"] = datetime.now().isoformat()
-            write_task_json(blocker_dir, blocker_data)
+            data["blocks"] = blocks
+            data["updated_at"] = datetime.now().isoformat()
+    modify_task_json(blocker_dir, _block_reverse_mutator)
 
     print(f"{task_dir.name} now blocked by {blocker_dir.name}")
     return 0
@@ -713,21 +763,25 @@ def cmd_unblock(args: argparse.Namespace) -> int:
             return 4
 
     removed = False
-    # 从 task.blocked_by 删
-    task_data = load_task_json(task_dir) if task_dir.is_dir() else None
-    if task_data and blocker_dir.name in (task_data.get("blocked_by") or []):
-        task_data["blocked_by"] = [x for x in task_data["blocked_by"] if x != blocker_dir.name]
-        task_data["updated_at"] = datetime.now().isoformat()
-        write_task_json(task_dir, task_data)
-        removed = True
-
-    # 从 blocker.blocks 删
-    blocker_data = load_task_json(blocker_dir) if blocker_dir.is_dir() else None
-    if blocker_data and task_dir.name in (blocker_data.get("blocks") or []):
-        blocker_data["blocks"] = [x for x in blocker_data["blocks"] if x != task_dir.name]
-        blocker_data["updated_at"] = datetime.now().isoformat()
-        write_task_json(blocker_dir, blocker_data)
-        removed = True
+    # 锁内从 task.blocked_by 删
+    if task_dir.is_dir():
+        def _unblock_mutator(data):
+            nonlocal removed
+            if blocker_dir.name in (data.get("blocked_by") or []):
+                data["blocked_by"] = [x for x in (data.get("blocked_by") or []) if x != blocker_dir.name]
+                data["updated_at"] = datetime.now().isoformat()
+                removed = True
+        modify_task_json(task_dir, _unblock_mutator)
+
+    # 锁内从 blocker.blocks 删
+    if blocker_dir.is_dir():
+        def _unblock_reverse_mutator(data):
+            nonlocal removed
+            if task_dir.name in (data.get("blocks") or []):
+                data["blocks"] = [x for x in (data.get("blocks") or []) if x != task_dir.name]
+                data["updated_at"] = datetime.now().isoformat()
+                removed = True
+        modify_task_json(blocker_dir, _unblock_reverse_mutator)
 
     if removed:
         print(f"Removed block: {task_dir.name} no longer blocked by {blocker_dir.name}")

package/templates/qoder/scripts/team_sync.py

@@ -136,9 +136,20 @@ def _notify_prd_publications(staged_files):
 
 def report_conflict(stderr):
     """rebase 冲突: 中止并输出结构化标记, 由会话中的 AI 接手解决"""
-    git('rebase', '--abort')
+    if rebase_in_progress():
+        r = git('rebase', '--abort')
+        if r.returncode != 0:
+            print('WARNING: rebase --abort 失败 (rc={}): {}'.format(r.returncode, (r.stderr or '').strip()[:120]))
+            print('仓库可能处于半 rebase 状态。AI 请手动跑: git rebase --abort')
     print('SYNC_CONFLICT: 自动同步遇到冲突, 已安全回退 (本地产出未丢失)。')
-    print('AI 请执行: git pull --rebase origin {} 并解决冲突后 git push。'.format(current_branch()))
+    branch = current_branch()
+    print('AI 请按以下步骤解决冲突:')
+    print('  1. git status                              # 看哪些文件冲突')
+    print('  2. git pull --rebase origin {}             # 重新拉取'.format(branch))
+    print('  3. 编辑冲突文件 (<<<<<<< 标记处), 保留双方改动')
+    print('  4. git add <解决后的文件>                  # 标记已解决')
+    print('  5. git rebase --continue                   # 继续 rebase')
+    print('  6. git push                                # 推送')
     print('冲突详情: ' + stderr.strip()[:300])
     return 3
 
@@ -309,7 +320,10 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
         if not passed:
             print(reason)
             # 撤销 staging (用户修完再来)
-            git('reset', 'HEAD', '--')
+            rr = git('reset', 'HEAD', '--')
+            if rr.returncode != 0:
+                print('WARNING: 门禁失败后 git reset 失败, staged 文件可能仍暂存!')
+                print('  请手动跑: git reset HEAD --')
             return 1
 
     # 4. commit
@@ -347,7 +361,13 @@ def _do_push_locked(message, dev, skip_eval, skip_secret):
         if r.returncode != 0:
             if 'CONFLICT' in (r.stdout + r.stderr) or rebase_in_progress():
                 return report_conflict(r.stderr or r.stdout)
+            # 非冲突的 pull 失败 (网络/auth/fetch 拒绝): 不往下 push (仓库可能处于
+            # 半 rebase 状态), 重试本循环
             print('Pull failed (attempt {}): {}'.format(attempt, (r.stderr or r.stdout).strip()[:150]))
+            if rebase_in_progress():
+                # 兜底: 万一 pull 留下了未完成的 rebase, abort 掉防仓库损坏
+                git('rebase', '--abort')
+            continue
 
         r = git('push', 'origin', branch)
         if r.returncode == 0: