@hupan56/wlkj 3.1.25 → 3.1.26

package/templates/qoder/scripts/foundation/data/task_utils.py

@@ -1,428 +1,428 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-QODER Pipeline - 任务工具函数
-
-提供:
-- resolve_task_dir: 解析任务目录 (支持名称/相对路径/绝对路径)
-- run_task_hooks: 运行任务生命周期钩子
-- load_task_json: 加载 task.json
-- write_task_json: 写入 task.json
-
-参考: Trellis 的 common/task_utils.py 设计
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-from foundation.core.paths import DIR_TASKS, FILE_TASK_JSON, get_repo_root, get_tasks_dir
-
-# 原子写 (解决半写损坏)
-try:
-    from foundation.io.atomicio import atomic_write_json
-except ImportError:
-    def atomic_write_json(path, data, indent=2, ensure_ascii=False, sort_keys=True):
-        import json as _j
-        Path(path).write_text(_j.dumps(data, indent=indent, ensure_ascii=ensure_ascii,
-                                        sort_keys=sort_keys) + "\n", encoding="utf-8")
-
-# 安全读 (区分缺失/损坏, 损坏备份 .corrupt) — 与 atomic_write_json 同源
-try:
-    from foundation.io.atomicio import safe_read_json, AtomicIOError
-except ImportError:
-    # 兜底: 退化回旧的裸读 (损坏静默返回 None, 不备份)
-    def safe_read_json(path, default=None, required=False, backup_corrupt=True):
-        if not os.path.isfile(path):
-            return default
-        try:
-            return json.loads(Path(path).read_text(encoding="utf-8"))
-        except (ValueError, json.JSONDecodeError, OSError, IOError):
-            return default
-
-    class AtomicIOError(Exception):
-        """兜底类型 (仅当 atomicio 不可用时定义, 不会真正抛出)。"""
-
-
-# =============================================================================
-# 任务目录解析
-# =============================================================================
-
-def resolve_task_dir(task_input: str, repo_root: Path | None = None) -> Path:
-    """解析任务目录路径。
-
-    支持三种输入:
-    1. 纯名称/全名: "my-task" / "06-10-my-task" -> workspace/tasks/<name>
-    2. 相对路径: "workspace/tasks/06-10-my-task" -> 完整路径
-    3. 绝对路径: 直接使用
-
-    安全变更 (零信任): 不再做模糊子串匹配 (旧版 "a" 可能匹配到他人的
-    "06-10-alpha" 导致误操作)。现在要求精确名或唯一前缀。
-
-    Args:
-        task_input: 任务标识 (名称或路径)。
-        repo_root: 项目根目录, 默认自动检测。
-
-    Returns:
-        任务目录的绝对路径。
-
-    Raises:
-        FileNotFoundError: 找不到任务。
-        ValueError: 名称歧义 (多个候选)。
-    """
-    if repo_root is None:
-        repo_root = get_repo_root()
-
-    input_path = Path(task_input)
-
-    # 已经是绝对路径且存在
-    if input_path.is_absolute() and input_path.is_dir():
-        return input_path.resolve()
-
-    # 相对路径
-    full_from_root = (repo_root / task_input).resolve()
-    if full_from_root.is_dir():
-        return full_from_root
-
-    # 纯名称: 在 tasks 目录下精确匹配
-    tasks_dir = get_tasks_dir(repo_root)
-    direct_match = tasks_dir / task_input
-    if direct_match.is_dir():
-        return direct_match.resolve()
-
-    # 精确匹配失败 —— 查唯一前缀匹配 (不允许歧义)
-    if tasks_dir.is_dir():
-        candidates = [
-            d for d in tasks_dir.iterdir()
-            if d.is_dir() and (
-                d.name == task_input or           # 全名精确
-                d.name.endswith("-" + task_input) or  # "06-10-my-task".endswith("-my-task")
-                d.name.startswith(task_input + "-")   # "06-10".startswith("06-10-...")
-            )
-        ]
-        if len(candidates) == 1:
-            return candidates[0].resolve()
-        if len(candidates) > 1:
-            names = ", ".join(d.name for d in candidates[:5])
-            raise ValueError(
-                "任务名 '%s' 歧义, 匹配到 %d 个: %s。请用完整任务名。"
-                % (task_input, len(candidates), names)
-            )
-
-    # 不存在 —— 返回原始路径 (调用方决定怎么报错)
-    return tasks_dir / task_input
-
-
-# =============================================================================
-# 任务 JSON 读写
-# =============================================================================
-
-def load_task_json(task_dir: Path) -> dict | None:
-    """加载 task.json 文件。
-
-    Args:
-        task_dir: 任务目录路径。
-
-    Returns:
-        解析后的 dict, 文件不存在或解析失败返回 None。
-
-    健壮性 (v3.1.2): 改走 safe_read_json —— JSON 损坏时备份为
-    task.json.corrupt.<ts> 并 stderr 告警, 而非静默吞成 None (与"文件
-    缺失"无法区分 → 数据丢失无恢复路径)。调用方行为不变 (仍返回 None)。
-    """
-    task_json = task_dir / FILE_TASK_JSON
-    try:
-        # safe_read_json: 缺失返回 default(None); 损坏备份 .corrupt 后抛 AtomicIOError。
-        # 复用文件顶部已 import 的 atomicio (相对导入, 与 atomic_write_json 同源)。
-        return safe_read_json(str(task_json), default=None)
-    except AtomicIOError as e:
-        # 损坏已备份, 告警但保持向后兼容 (返回 None, 调用方按"无任务"处理)
-        print('Warning: %s' % e, file=sys.stderr)
-        return None
-    except (OSError, IOError):
-        return None
-
-
-def write_task_json(task_dir: Path, data: dict) -> bool:
-    """原子写入 task.json 文件 (temp + os.replace, 写失败原文件不变)。
-
-    Args:
-        task_dir: 任务目录路径。
-        data: 要写入的数据。
-
-    Returns:
-        成功返回 True。
-    """
-    task_json = task_dir / FILE_TASK_JSON
-    try:
-        # 原子写: sort_keys=False 保留插入顺序 (task.json 字段顺序有意义)
-        atomic_write_json(
-            str(task_json), data,
-            indent=2, ensure_ascii=False, sort_keys=False,
-        )
-        return True
-    except (OSError, IOError) as e:
-        print(f"Warning: Failed to write task.json: {e}", file=sys.stderr)
-        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 foundation.io.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)
-
-    # 锁竞争超时: 退避重试一次。绝不降级为无锁写 —— modify_task_json 存在的意义
-    # 就是防并发 read-modify-write 丢更新, 两个并发方都超时降级 = 必然丢一个的更新。
-    acquired = False
-    for attempt in range(2):
-        try:
-            lock.acquire()
-            acquired = True
-            break
-        except LockTimeoutError as e:
-            if attempt == 0:
-                # 第一次超时: 短暂退避后重试 (锁持有方通常很快释放)
-                import time as _time
-                _time.sleep(0.5)
-                continue
-            # 重试仍超时: 明确失败, 不写 (宁可这次改不了, 也不丢更新)
-            print(f"ERROR: task lock busy after retry ({task_dir.name}): {e}", file=sys.stderr)
-            print(f"  另一个进程正在修改此任务, 请稍后重试。改动未生效 (未丢数据)。", file=sys.stderr)
-            return False
-    if not acquired:
-        return False
-
-    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: 任务操作权限校验 (零信任)
-# =============================================================================
-
-def assert_can_modify_task(
-    task_dir: Path,
-    action: str,
-    repo_root: Path | None = None,
-) -> str:
-    """校验当前开发者是否有权修改该任务。
-
-    零信任 ACL: 只有 creator / assignee / admin 角色能修改。
-    其他人 start/finish/archive 别人的任务会被拒绝。
-
-    Args:
-        task_dir: 任务目录。
-        action: 动作名 (start/finish/archive/add-subtask/remove-subtask)。
-        repo_root: 项目根。
-
-    Returns:
-        当前开发者名 (校验通过)。
-
-    Raises:
-        PermissionError: 无权操作。
-    """
-    if repo_root is None:
-        repo_root = get_repo_root()
-    repo_root = Path(repo_root)  # 统一为 Path
-
-    # 读当前开发者
-    try:
-        from foundation.core.paths import get_developer
-    except ImportError:
-        from paths import get_developer  # type: ignore
-    dev = get_developer(repo_root)
-    if not dev:
-        raise PermissionError(
-            "[authz] 拒绝 %s: 未设置开发者身份。先 /wl-init。" % action
-        )
-
-    task = load_task_json(task_dir)
-    if not task:
-        # 任务不存在 —— 让上层处理, 这里放行 (创建场景)
-        return dev
-
-    creator = (task.get("creator") or "").strip()
-    assignee = (task.get("assignee") or "").strip()
-    authorized = {creator, assignee}
-    authorized.discard("")
-
-    # admin 角色可操作任意任务
-    try:
-        from foundation.identity.identity import get_member
-        m = get_member(dev, repo_root)
-        if m and m.get("role") == "admin":
-            return dev
-    except Exception:
-        pass  # identity 模块不可用则退化为只看 creator/assignee
-
-    if dev not in authorized:
-        raise PermissionError(
-            "[authz] 拒绝 %s 任务 '%s': 当前开发者 '%s' 不是 creator(%s)/assignee(%s)。"
-            "只有任务负责人或 admin 可操作。"
-            % (action, task_dir.name, dev, creator or "?", assignee or "?")
-        )
-    return dev
-
-
-# =============================================================================
-# 生命周期钩子
-# =============================================================================
-
-def run_task_hooks(
-    hook_name: str,
-    task_json_path: Path,
-    repo_root: Path | None = None,
-) -> None:
-    """运行任务生命周期钩子。
-
-    从 config.yaml 读取钩子配置并执行。
-
-    Args:
-        hook_name: 钩子名称 (after_create/after_start/after_finish/after_archive)。
-        task_json_path: task.json 的路径。
-        repo_root: 项目根目录, 默认自动检测。
-    """
-    if repo_root is None:
-        repo_root = get_repo_root()
-
-    config_path = repo_root / ".qoder" / "config.yaml"
-    if not config_path.is_file():
-        return
-
-    # 简单的 YAML 解析 (不依赖 PyYAML)
-    try:
-        import yaml
-        with open(config_path, "r", encoding="utf-8") as f:
-            config = yaml.safe_load(f)
-    except ImportError:
-        # 没有 PyYAML, 用简单解析
-        config = _simple_yaml_parse(config_path)
-    except Exception as e:
-        # config.yaml 语法错误等: 不阻塞任务操作, 只是跳过 hooks
-        # (用户可能手编 config.yaml 引入了语法错误, 不该让整个任务系统崩溃)
-        print(f"Warning: .qoder/config.yaml 解析失败, 跳过 hooks ({type(e).__name__})", file=sys.stderr)
-        return
-
-    if not config:
-        return
-
-    hooks = config.get("hooks", {})
-    commands = hooks.get(hook_name, [])
-    if not commands:
-        return
-
-    env = os.environ.copy()
-    env["TASK_JSON_PATH"] = str(task_json_path)
-
-    for cmd in commands:
-        try:
-            print(f"  Running hook [{hook_name}]: {cmd}")
-            result = subprocess.run(
-                cmd,
-                shell=True,
-                cwd=str(repo_root),
-                env=env,
-                capture_output=True,
-                text=True,
-                timeout=30,
-            )
-            if result.returncode != 0:
-                print(f"  Warning: Hook returned non-zero: {result.stderr}", file=sys.stderr)
-        except subprocess.TimeoutExpired:
-            print(f"  Warning: Hook timed out: {cmd}", file=sys.stderr)
-        except Exception as e:
-            print(f"  Warning: Hook error: {e}", file=sys.stderr)
-
-
-def _simple_yaml_parse(path: Path) -> dict:
-    """简单的 YAML 解析器 (不依赖外部库)。
-
-    只支持两级嵌套和列表。
-
-    Args:
-        path: YAML 文件路径。
-
-    Returns:
-        解析后的 dict。
-    """
-    result = {}
-    current_key = None
-    current_list = None
-
-    try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except (OSError, IOError):
-        return result
-
-    for line in lines:
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-
-        indent = len(line) - len(line.lstrip())
-
-        if indent == 0 and ":" in stripped and not stripped.startswith("-"):
-            # 顶层 key
-            if current_key and current_list is not None:
-                result[current_key] = current_list
-            key, _, value = stripped.partition(":")
-            current_key = key.strip()
-            current_list = None
-            if value.strip():
-                result[current_key] = value.strip()
-                current_key = None
-
-        elif indent > 0 and stripped.startswith("- "):
-            # 列表项
-            if current_list is None:
-                current_list = []
-            item = stripped[2:].strip().strip("'\"")
-            current_list.append(item)
-
-        elif indent > 0 and ":" in stripped and current_key:
-            # 子键值对
-            if current_list is not None:
-                result[current_key] = current_list
-                current_list = None
-            key, _, value = stripped.partition(":")
-            if isinstance(result.get(current_key), dict):
-                result[current_key][key.strip()] = value.strip().strip("'\"")
-            else:
-                result[current_key] = {key.strip(): value.strip().strip("'\"")}
-
-    if current_key and current_list is not None:
-        result[current_key] = current_list
-
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+QODER Pipeline - 任务工具函数
+
+提供:
+- resolve_task_dir: 解析任务目录 (支持名称/相对路径/绝对路径)
+- run_task_hooks: 运行任务生命周期钩子
+- load_task_json: 加载 task.json
+- write_task_json: 写入 task.json
+
+参考:  common/task_utils.py 设计
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from foundation.core.paths import DIR_TASKS, FILE_TASK_JSON, get_repo_root, get_tasks_dir
+
+# 原子写 (解决半写损坏)
+try:
+    from foundation.io.atomicio import atomic_write_json
+except ImportError:
+    def atomic_write_json(path, data, indent=2, ensure_ascii=False, sort_keys=True):
+        import json as _j
+        Path(path).write_text(_j.dumps(data, indent=indent, ensure_ascii=ensure_ascii,
+                                        sort_keys=sort_keys) + "\n", encoding="utf-8")
+
+# 安全读 (区分缺失/损坏, 损坏备份 .corrupt) — 与 atomic_write_json 同源
+try:
+    from foundation.io.atomicio import safe_read_json, AtomicIOError
+except ImportError:
+    # 兜底: 退化回旧的裸读 (损坏静默返回 None, 不备份)
+    def safe_read_json(path, default=None, required=False, backup_corrupt=True):
+        if not os.path.isfile(path):
+            return default
+        try:
+            return json.loads(Path(path).read_text(encoding="utf-8"))
+        except (ValueError, json.JSONDecodeError, OSError, IOError):
+            return default
+
+    class AtomicIOError(Exception):
+        """兜底类型 (仅当 atomicio 不可用时定义, 不会真正抛出)。"""
+
+
+# =============================================================================
+# 任务目录解析
+# =============================================================================
+
+def resolve_task_dir(task_input: str, repo_root: Path | None = None) -> Path:
+    """解析任务目录路径。
+
+    支持三种输入:
+    1. 纯名称/全名: "my-task" / "06-10-my-task" -> workspace/tasks/<name>
+    2. 相对路径: "workspace/tasks/06-10-my-task" -> 完整路径
+    3. 绝对路径: 直接使用
+
+    安全变更 (零信任): 不再做模糊子串匹配 (旧版 "a" 可能匹配到他人的
+    "06-10-alpha" 导致误操作)。现在要求精确名或唯一前缀。
+
+    Args:
+        task_input: 任务标识 (名称或路径)。
+        repo_root: 项目根目录, 默认自动检测。
+
+    Returns:
+        任务目录的绝对路径。
+
+    Raises:
+        FileNotFoundError: 找不到任务。
+        ValueError: 名称歧义 (多个候选)。
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    input_path = Path(task_input)
+
+    # 已经是绝对路径且存在
+    if input_path.is_absolute() and input_path.is_dir():
+        return input_path.resolve()
+
+    # 相对路径
+    full_from_root = (repo_root / task_input).resolve()
+    if full_from_root.is_dir():
+        return full_from_root
+
+    # 纯名称: 在 tasks 目录下精确匹配
+    tasks_dir = get_tasks_dir(repo_root)
+    direct_match = tasks_dir / task_input
+    if direct_match.is_dir():
+        return direct_match.resolve()
+
+    # 精确匹配失败 —— 查唯一前缀匹配 (不允许歧义)
+    if tasks_dir.is_dir():
+        candidates = [
+            d for d in tasks_dir.iterdir()
+            if d.is_dir() and (
+                d.name == task_input or           # 全名精确
+                d.name.endswith("-" + task_input) or  # "06-10-my-task".endswith("-my-task")
+                d.name.startswith(task_input + "-")   # "06-10".startswith("06-10-...")
+            )
+        ]
+        if len(candidates) == 1:
+            return candidates[0].resolve()
+        if len(candidates) > 1:
+            names = ", ".join(d.name for d in candidates[:5])
+            raise ValueError(
+                "任务名 '%s' 歧义, 匹配到 %d 个: %s。请用完整任务名。"
+                % (task_input, len(candidates), names)
+            )
+
+    # 不存在 —— 返回原始路径 (调用方决定怎么报错)
+    return tasks_dir / task_input
+
+
+# =============================================================================
+# 任务 JSON 读写
+# =============================================================================
+
+def load_task_json(task_dir: Path) -> dict | None:
+    """加载 task.json 文件。
+
+    Args:
+        task_dir: 任务目录路径。
+
+    Returns:
+        解析后的 dict, 文件不存在或解析失败返回 None。
+
+    健壮性 (v3.1.2): 改走 safe_read_json —— JSON 损坏时备份为
+    task.json.corrupt.<ts> 并 stderr 告警, 而非静默吞成 None (与"文件
+    缺失"无法区分 → 数据丢失无恢复路径)。调用方行为不变 (仍返回 None)。
+    """
+    task_json = task_dir / FILE_TASK_JSON
+    try:
+        # safe_read_json: 缺失返回 default(None); 损坏备份 .corrupt 后抛 AtomicIOError。
+        # 复用文件顶部已 import 的 atomicio (相对导入, 与 atomic_write_json 同源)。
+        return safe_read_json(str(task_json), default=None)
+    except AtomicIOError as e:
+        # 损坏已备份, 告警但保持向后兼容 (返回 None, 调用方按"无任务"处理)
+        print('Warning: %s' % e, file=sys.stderr)
+        return None
+    except (OSError, IOError):
+        return None
+
+
+def write_task_json(task_dir: Path, data: dict) -> bool:
+    """原子写入 task.json 文件 (temp + os.replace, 写失败原文件不变)。
+
+    Args:
+        task_dir: 任务目录路径。
+        data: 要写入的数据。
+
+    Returns:
+        成功返回 True。
+    """
+    task_json = task_dir / FILE_TASK_JSON
+    try:
+        # 原子写: sort_keys=False 保留插入顺序 (task.json 字段顺序有意义)
+        atomic_write_json(
+            str(task_json), data,
+            indent=2, ensure_ascii=False, sort_keys=False,
+        )
+        return True
+    except (OSError, IOError) as e:
+        print(f"Warning: Failed to write task.json: {e}", file=sys.stderr)
+        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 foundation.io.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)
+
+    # 锁竞争超时: 退避重试一次。绝不降级为无锁写 —— modify_task_json 存在的意义
+    # 就是防并发 read-modify-write 丢更新, 两个并发方都超时降级 = 必然丢一个的更新。
+    acquired = False
+    for attempt in range(2):
+        try:
+            lock.acquire()
+            acquired = True
+            break
+        except LockTimeoutError as e:
+            if attempt == 0:
+                # 第一次超时: 短暂退避后重试 (锁持有方通常很快释放)
+                import time as _time
+                _time.sleep(0.5)
+                continue
+            # 重试仍超时: 明确失败, 不写 (宁可这次改不了, 也不丢更新)
+            print(f"ERROR: task lock busy after retry ({task_dir.name}): {e}", file=sys.stderr)
+            print(f"  另一个进程正在修改此任务, 请稍后重试。改动未生效 (未丢数据)。", file=sys.stderr)
+            return False
+    if not acquired:
+        return False
+
+    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: 任务操作权限校验 (零信任)
+# =============================================================================
+
+def assert_can_modify_task(
+    task_dir: Path,
+    action: str,
+    repo_root: Path | None = None,
+) -> str:
+    """校验当前开发者是否有权修改该任务。
+
+    零信任 ACL: 只有 creator / assignee / admin 角色能修改。
+    其他人 start/finish/archive 别人的任务会被拒绝。
+
+    Args:
+        task_dir: 任务目录。
+        action: 动作名 (start/finish/archive/add-subtask/remove-subtask)。
+        repo_root: 项目根。
+
+    Returns:
+        当前开发者名 (校验通过)。
+
+    Raises:
+        PermissionError: 无权操作。
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    repo_root = Path(repo_root)  # 统一为 Path
+
+    # 读当前开发者
+    try:
+        from foundation.core.paths import get_developer
+    except ImportError:
+        from paths import get_developer  # type: ignore
+    dev = get_developer(repo_root)
+    if not dev:
+        raise PermissionError(
+            "[authz] 拒绝 %s: 未设置开发者身份。先 /wl-init。" % action
+        )
+
+    task = load_task_json(task_dir)
+    if not task:
+        # 任务不存在 —— 让上层处理, 这里放行 (创建场景)
+        return dev
+
+    creator = (task.get("creator") or "").strip()
+    assignee = (task.get("assignee") or "").strip()
+    authorized = {creator, assignee}
+    authorized.discard("")
+
+    # admin 角色可操作任意任务
+    try:
+        from foundation.identity.identity import get_member
+        m = get_member(dev, repo_root)
+        if m and m.get("role") == "admin":
+            return dev
+    except Exception:
+        pass  # identity 模块不可用则退化为只看 creator/assignee
+
+    if dev not in authorized:
+        raise PermissionError(
+            "[authz] 拒绝 %s 任务 '%s': 当前开发者 '%s' 不是 creator(%s)/assignee(%s)。"
+            "只有任务负责人或 admin 可操作。"
+            % (action, task_dir.name, dev, creator or "?", assignee or "?")
+        )
+    return dev
+
+
+# =============================================================================
+# 生命周期钩子
+# =============================================================================
+
+def run_task_hooks(
+    hook_name: str,
+    task_json_path: Path,
+    repo_root: Path | None = None,
+) -> None:
+    """运行任务生命周期钩子。
+
+    从 config.yaml 读取钩子配置并执行。
+
+    Args:
+        hook_name: 钩子名称 (after_create/after_start/after_finish/after_archive)。
+        task_json_path: task.json 的路径。
+        repo_root: 项目根目录, 默认自动检测。
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    config_path = repo_root / ".qoder" / "config.yaml"
+    if not config_path.is_file():
+        return
+
+    # 简单的 YAML 解析 (不依赖 PyYAML)
+    try:
+        import yaml
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = yaml.safe_load(f)
+    except ImportError:
+        # 没有 PyYAML, 用简单解析
+        config = _simple_yaml_parse(config_path)
+    except Exception as e:
+        # config.yaml 语法错误等: 不阻塞任务操作, 只是跳过 hooks
+        # (用户可能手编 config.yaml 引入了语法错误, 不该让整个任务系统崩溃)
+        print(f"Warning: .qoder/config.yaml 解析失败, 跳过 hooks ({type(e).__name__})", file=sys.stderr)
+        return
+
+    if not config:
+        return
+
+    hooks = config.get("hooks", {})
+    commands = hooks.get(hook_name, [])
+    if not commands:
+        return
+
+    env = os.environ.copy()
+    env["TASK_JSON_PATH"] = str(task_json_path)
+
+    for cmd in commands:
+        try:
+            print(f"  Running hook [{hook_name}]: {cmd}")
+            result = subprocess.run(
+                cmd,
+                shell=True,
+                cwd=str(repo_root),
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+            if result.returncode != 0:
+                print(f"  Warning: Hook returned non-zero: {result.stderr}", file=sys.stderr)
+        except subprocess.TimeoutExpired:
+            print(f"  Warning: Hook timed out: {cmd}", file=sys.stderr)
+        except Exception as e:
+            print(f"  Warning: Hook error: {e}", file=sys.stderr)
+
+
+def _simple_yaml_parse(path: Path) -> dict:
+    """简单的 YAML 解析器 (不依赖外部库)。
+
+    只支持两级嵌套和列表。
+
+    Args:
+        path: YAML 文件路径。
+
+    Returns:
+        解析后的 dict。
+    """
+    result = {}
+    current_key = None
+    current_list = None
+
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, IOError):
+        return result
+
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        if indent == 0 and ":" in stripped and not stripped.startswith("-"):
+            # 顶层 key
+            if current_key and current_list is not None:
+                result[current_key] = current_list
+            key, _, value = stripped.partition(":")
+            current_key = key.strip()
+            current_list = None
+            if value.strip():
+                result[current_key] = value.strip()
+                current_key = None
+
+        elif indent > 0 and stripped.startswith("- "):
+            # 列表项
+            if current_list is None:
+                current_list = []
+            item = stripped[2:].strip().strip("'\"")
+            current_list.append(item)
+
+        elif indent > 0 and ":" in stripped and current_key:
+            # 子键值对
+            if current_list is not None:
+                result[current_key] = current_list
+                current_list = None
+            key, _, value = stripped.partition(":")
+            if isinstance(result.get(current_key), dict):
+                result[current_key][key.strip()] = value.strip().strip("'\"")
+            else:
+                result[current_key] = {key.strip(): value.strip().strip("'\"")}
+
+    if current_key and current_list is not None:
+        result[current_key] = current_list
+
     return result