@hupan56/wlkj 2.0.0

package/templates/qoder/scripts/task.py

@@ -0,0 +1,954 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+QODER Pipeline - 任务生命周期管理
+
+完整的任务 CRUD 和生命周期管理:
+- create: 创建任务 (含 task.json, prd.md 模板, implement.jsonl, check.jsonl)
+- start: 开始任务 (设置活跃任务, 状态 planning -> in_progress)
+- current: 查看当前活跃任务
+- finish: 完成任务 (清除活跃任务)
+- archive: 归档任务 (移动到 archive/ 目录)
+- list: 列出活跃/归档任务
+- add-subtask / remove-subtask: 父子任务关联
+
+参考: Trellis 的 task.py 设计
+
+Usage:
+    python task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3]
+    python task.py start <name>
+    python task.py current [--source]
+    python task.py finish
+    python task.py archive <name>
+    python task.py list [--mine] [--status <s>]
+    python task.py add-subtask <parent> <child>
+    python task.py remove-subtask <parent> <child>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# 将 scripts 目录加入路径
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from common.paths import (
+    DIR_TASKS,
+    DIR_ARCHIVE,
+    FILE_TASK_JSON,
+    get_repo_root,
+    get_developer,
+    get_tasks_dir,
+)
+from common.active_task import (
+    clear_active_task,
+    resolve_active_task,
+    resolve_context_key,
+    set_active_task,
+)
+from common.task_utils import (
+    resolve_task_dir,
+    run_task_hooks,
+    load_task_json,
+    write_task_json,
+    assert_can_modify_task,
+)
+
+
+# =============================================================================
+# 命令: create
+# =============================================================================
+
+def cmd_create(args: argparse.Namespace) -> int:
+    """创建新任务。
+
+    创建:
+        - .qoder/tasks/<slug>/ 目录
+        - task.json (元数据)
+        - prd.md (空模板)
+        - implement.jsonl (实现上下文, 空文件)
+        - check.jsonl (检查上下文, 空文件)
+    """
+    repo_root = get_repo_root()
+    title = args.title
+    slug = args.slug or _generate_slug(title)
+    assignee = args.assignee or get_developer(repo_root)
+    priority = args.priority or "P2"
+
+    # 生成日期前缀: MM-DD
+    date_prefix = datetime.now().strftime("%m-%d")
+    task_dir_name = f"{date_prefix}-{slug}"
+
+    tasks_dir = get_tasks_dir(repo_root)
+    task_dir = tasks_dir / task_dir_name
+
+    # 撞名处理: 同日同名 (两个 PM 都建"登录优化") 自动加 creator 后缀, 不阻塞
+    if task_dir.exists():
+        creator_tag = (assignee or "x")[:8]
+        # 加 creator 短标记; 仍撞则加 -2/-3
+        candidate = f"{date_prefix}-{slug}-{creator_tag}"
+        n = 2
+        while (tasks_dir / candidate).exists():
+            candidate = f"{date_prefix}-{slug}-{creator_tag}-{n}"
+            n += 1
+            if n > 99:  # 防御性上限
+                print(f"Error: Task name collision exhausted: {slug}", file=sys.stderr)
+                return 1
+        task_dir_name = candidate
+        task_dir = tasks_dir / task_dir_name
+        print(f"Note: 同名任务已存在, 自动加后缀: {task_dir_name}")
+
+    # 创建目录
+    task_dir.mkdir(parents=True, exist_ok=True)
+
+    # 创建 task.json
+    now_iso = datetime.now().isoformat()
+    task_data = {
+        "title": title,
+        "slug": slug,
+        "status": "planning",
+        "priority": priority,
+        "assignee": assignee,
+        "creator": assignee,
+        "created_at": now_iso,
+        "updated_at": now_iso,
+        "branch": None,
+        "base_branch": None,
+        "scope": None,
+        "parent": None,
+        "children": [],
+        "tags": [],
+        # B1 能力增强字段 (向后兼容: 旧 task.json 不含这些, 读时取默认值)
+        "due_date": None,          # 截止日期 YYYY-MM-DD (可选)
+        "start_date": None,        # 开始日期 YYYY-MM-DD (可选)
+        "estimate_hours": None,    # 预估工时 (可选)
+        "blocked_by": [],          # 依赖的任务 (数组, 自动维护反向 blocks)
+        "blocks": [],              # 被哪些任务依赖 (自动维护)
+        # B3 阶段时间戳 (周期时间分析用)
+        "stage_ts": {
+            "created": now_iso,
+            "started": None,       # cmd_start 时填
+            "completed": None,     # cmd_finish 时填
+        },
+    }
+    write_task_json(task_dir, task_data)
+
+    # 创建 prd.md 模板
+    prd_file = task_dir / "prd.md"
+    prd_content = f"""# PRD: {title}
+
+> Status: planning
+> Assignee: {assignee or 'unassigned'}
+> Priority: {priority}
+> Created: {datetime.now().strftime("%Y-%m-%d %H:%M")}
+
+---
+
+## Background
+
+<!-- Describe the business context -->
+
+## Requirements
+
+<!-- List functional requirements -->
+
+## Acceptance Criteria
+
+<!-- Define testable acceptance criteria -->
+
+## Notes
+
+<!-- Additional notes -->
+"""
+    prd_file.write_text(prd_content, encoding="utf-8")
+
+    # 创建空的 JSONL 上下文文件
+    (task_dir / "implement.jsonl").write_text("", encoding="utf-8")
+    (task_dir / "check.jsonl").write_text("", encoding="utf-8")
+
+    print(f"Task created: {task_dir_name}")
+    print(f"  Title: {title}")
+    print(f"  Assignee: {assignee or 'unassigned'}")
+    print(f"  Priority: {priority}")
+    print(f"  Path: workspace/tasks/{task_dir_name}")
+
+    # 运行 after_create 钩子
+    run_task_hooks("after_create", task_dir / FILE_TASK_JSON, repo_root)
+
+    return 0
+
+
+# =============================================================================
+# 命令: start
+# =============================================================================
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """设置活跃任务, 状态改为 in_progress。"""
+    repo_root = get_repo_root()
+    task_input = args.dir
+
+    if not task_input:
+        print("Error: task directory or name required", file=sys.stderr)
+        return 1
+
+    full_path = resolve_task_dir(task_input, repo_root)
+
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {task_input}", file=sys.stderr)
+        return 1
+
+    # 零信任 ACL: 只有 creator/assignee/admin 能 start
+    try:
+        assert_can_modify_task(full_path, "start", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4  # authz_denied
+
+    # 转为相对路径
+    try:
+        task_dir = full_path.relative_to(repo_root).as_posix()
+    except ValueError:
+        task_dir = str(full_path)
+
+    # 设置活跃任务
+    active = set_active_task(task_dir, repo_root)
+    if active:
+        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")
+
+        # 运行 after_start 钩子
+        run_task_hooks("after_start", full_path / FILE_TASK_JSON, repo_root)
+        return 0
+    else:
+        print("Error: Failed to set current task", file=sys.stderr)
+        return 1
+
+
+# =============================================================================
+# 命令: current
+# =============================================================================
+
+def cmd_current(args: argparse.Namespace) -> int:
+    """显示当前活跃任务。"""
+    repo_root = get_repo_root()
+    active = resolve_active_task(repo_root)
+
+    if args.source:
+        print(f"Current task: {active.task_path or '(none)'}")
+        print(f"Source: {active.source}")
+        return 0 if active.task_path else 1
+
+    if active.task_path:
+        print(active.task_path)
+        return 0
+
+    print("No active task", file=sys.stderr)
+    return 1
+
+
+# =============================================================================
+# 命令: finish
+# =============================================================================
+
+def cmd_finish(args: argparse.Namespace) -> int:
+    """完成当前任务 (状态改为 completed, 清除活跃任务指针)。"""
+    repo_root = get_repo_root()
+    active = clear_active_task(repo_root)
+    current = active.task_path
+
+    if not current:
+        print("No current task set")
+        return 0
+
+    print(f"Cleared current task (was: {current})")
+    print(f"Source: {active.source}")
+
+    # 更新 task.json 状态为 completed
+    task_dir = repo_root / current
+
+    # 零信任 ACL: 只有 creator/assignee/admin 能 finish
+    try:
+        assert_can_modify_task(task_dir, "finish", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        # 已清了 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: 飞书通知 (任务完成)
+        try:
+            from common.feishu import notify_task_finished
+            # 算用时
+            hours = None
+            started = stage_ts.get("started")
+            if started:
+                try:
+                    from datetime import datetime as _dt
+                    t_start = _dt.fromisoformat(started)
+                    t_end = _dt.fromisoformat(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)
+        except Exception:
+            pass  # 飞书失败不阻塞任务完成
+
+    task_json_path = task_dir / FILE_TASK_JSON
+    if task_json_path.is_file():
+        run_task_hooks("after_finish", task_json_path, repo_root)
+
+    return 0
+
+
+# =============================================================================
+# 命令: archive
+# =============================================================================
+
+def cmd_archive(args: argparse.Namespace) -> int:
+    """归档任务 (移动到 archive/ 目录)。事务化: 先 move 成功再改 status。"""
+    repo_root = get_repo_root()
+    task_input = args.dir
+
+    full_path = resolve_task_dir(task_input, repo_root)
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {task_input}", file=sys.stderr)
+        return 1
+
+    # 零信任 ACL: 只有 creator/assignee/admin 能 archive
+    try:
+        assert_can_modify_task(full_path, "archive", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4  # authz_denied
+
+    # 准备 archive 目标
+    year_month = datetime.now().strftime("%Y-%m")
+    archive_dir = repo_root / ".qoder" / "archive" / year_month
+    archive_dir.mkdir(parents=True, exist_ok=True)
+
+    dest = archive_dir / full_path.name
+    if dest.exists():
+        print(f"Error: Archive destination exists: {dest}", file=sys.stderr)
+        return 1
+
+    # 事务化: 先 move (失败则原任务完好无损), 成功后再改 status
+    try:
+        shutil.move(str(full_path), str(dest))
+    except (OSError, IOError) as e:
+        print(f"Error: Failed to archive (move failed, 原任务未动): {e}", file=sys.stderr)
+        return 1
+
+    # move 成功后在目标位置改 status (失败不影响归档, 仅 status 不更新)
+    task_data = load_task_json(dest)
+    if task_data:
+        task_data["status"] = "completed"
+        task_data["archived_at"] = datetime.now().isoformat()
+        task_data["updated_at"] = task_data["archived_at"]
+        write_task_json(dest, task_data)
+
+    # 运行 after_archive 钩子
+    run_task_hooks("after_archive", dest / FILE_TASK_JSON, 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}")
+    return 0
+
+
+# =============================================================================
+# 命令: list
+# =============================================================================
+
+def cmd_list(args: argparse.Namespace) -> int:
+    """列出活跃任务。支持 --mine / --status / --ready / --blocked 过滤。"""
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    developer = get_developer(repo_root)
+    active = resolve_active_task(repo_root)
+
+    filter_mine = args.mine
+    filter_status = args.status
+    filter_ready = getattr(args, "ready", False)
+    filter_blocked = getattr(args, "blocked", False)
+
+    if not tasks_dir.is_dir():
+        print("No tasks directory found")
+        return 0
+
+    # 预加载所有任务 (用于 --ready/--blocked 判断依赖是否完成)
+    all_tasks = {}
+    for d in sorted(tasks_dir.iterdir()):
+        if d.is_dir():
+            data = load_task_json(d)
+            if data:
+                all_tasks[d.name] = data
+
+    def is_dep_completed(dep_name: str) -> bool:
+        dep = all_tasks.get(dep_name)
+        return bool(dep and dep.get("status") == "completed")
+
+    tasks = []
+    for name, task_data in all_tasks.items():
+        d = tasks_dir / name
+
+        # 过滤: --mine
+        if filter_mine and developer not in (
+            task_data.get("assignee"), task_data.get("creator")
+        ):
+            continue
+        if filter_status and task_data.get("status") != filter_status:
+            continue
+
+        # --ready: 未完成 且 所有 blocked_by 已完成
+        if filter_ready:
+            if task_data.get("status") == "completed":
+                continue
+            blocked_by = task_data.get("blocked_by") or []
+            if any(not is_dep_completed(dep) for dep in blocked_by):
+                continue
+
+        # --blocked: 有未完成的 blocked_by
+        if filter_blocked:
+            blocked_by = task_data.get("blocked_by") or []
+            open_blocks = [dep for dep in blocked_by if not is_dep_completed(dep)]
+            if not open_blocks:
+                continue
+
+        tasks.append((name, task_data))
+
+    if not tasks:
+        print("No tasks found" + (
+            " (no tasks ready to start)" if filter_ready else
+            " (no blocked tasks)" if filter_blocked else ""
+        ))
+        return 0
+
+    print(f"Tasks ({len(tasks)}):")
+    for name, data in tasks:
+        is_current = active.task_path and name in active.task_path
+        marker = " *" if is_current else "  "
+        assignee = data.get("assignee", "?")
+        status = data.get("status", "?")
+        priority = data.get("priority", "?")
+        title = data.get("title", name)
+        extras = []
+        due = data.get("due_date")
+        if due:
+            extras.append(f"due:{due}")
+        blocked_by = data.get("blocked_by") or []
+        open_blocks = [dep for dep in blocked_by if not is_dep_completed(dep)]
+        if open_blocks:
+            extras.append(f"blocked:{','.join(open_blocks)}")
+        extra_str = f" [{', '.join(extras)}]" if extras else ""
+        print(f"{marker} [{priority}] [{status}] {name} ({assignee}) - {title}{extra_str}")
+
+    return 0
+
+
+# =============================================================================
+# 命令: show
+# =============================================================================
+
+def cmd_show(args: argparse.Namespace) -> int:
+    """显示任务详情。"""
+    repo_root = get_repo_root()
+    full_path = resolve_task_dir(args.dir, repo_root)
+
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {args.dir}", file=sys.stderr)
+        return 1
+
+    task_data = load_task_json(full_path)
+    if not task_data:
+        print(f"Error: Missing task.json in {full_path.name}", file=sys.stderr)
+        return 1
+
+    print(f"Task: {full_path.name}")
+    for key in ("title", "status", "priority", "rice", "assignee", "creator",
+                "created_at", "updated_at", "parent", "tags",
+                "due_date", "start_date", "estimate_hours"):
+        val = task_data.get(key)
+        if val not in (None, [], ""):
+            print(f"  {key}: {val}")
+    children = task_data.get("children") or []
+    if children:
+        print(f"  children: {', '.join(children)}")
+    blocked_by = task_data.get("blocked_by") or []
+    if blocked_by:
+        print(f"  blocked_by: {', '.join(blocked_by)}")
+    blocks = task_data.get("blocks") or []
+    if blocks:
+        print(f"  blocks: {', '.join(blocks)}")
+    stage_ts = task_data.get("stage_ts") or {}
+    if any(stage_ts.values()):
+        print(f"  stage_ts: {stage_ts}")
+    prd_file = full_path / "prd.md"
+    if prd_file.is_file():
+        print(f"  prd: workspace/tasks/{full_path.name}/prd.md")
+    return 0
+
+
+# =============================================================================
+# 命令: add-subtask / remove-subtask
+# =============================================================================
+
+def cmd_add_subtask(args: argparse.Namespace) -> int:
+    """添加子任务关联。"""
+    repo_root = get_repo_root()
+    parent_dir = resolve_task_dir(args.parent, repo_root)
+    child_dir = resolve_task_dir(args.child, repo_root)
+
+    if not parent_dir.is_dir():
+        print(f"Error: Parent task not found: {args.parent}", file=sys.stderr)
+        return 1
+    if not child_dir.is_dir():
+        print(f"Error: Child task not found: {args.child}", file=sys.stderr)
+        return 1
+
+    # 零信任 ACL: 只有 parent 的 creator/assignee/admin 能加子任务
+    try:
+        assert_can_modify_task(parent_dir, "add-subtask", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+
+    parent_data = load_task_json(parent_dir)
+    child_data = load_task_json(child_dir)
+
+    if not parent_data or not child_data:
+        print("Error: Missing task.json", file=sys.stderr)
+        return 1
+
+    child_name = child_dir.name
+    children = parent_data.get("children", [])
+    if child_name not in children:
+        children.append(child_name)
+        parent_data["children"] = children
+        parent_data["updated_at"] = datetime.now().isoformat()
+        write_task_json(parent_dir, parent_data)
+
+    # 子任务记录父任务
+    child_data["parent"] = parent_dir.name
+    child_data["updated_at"] = datetime.now().isoformat()
+    write_task_json(child_dir, child_data)
+
+    print(f"Subtask added: {parent_dir.name} -> {child_dir.name}")
+    return 0
+
+
+def cmd_remove_subtask(args: argparse.Namespace) -> int:
+    """移除子任务关联。"""
+    repo_root = get_repo_root()
+    parent_dir = resolve_task_dir(args.parent, repo_root)
+    child_dir = resolve_task_dir(args.child, repo_root)
+
+    # 零信任 ACL
+    if parent_dir.is_dir():
+        try:
+            assert_can_modify_task(parent_dir, "remove-subtask", repo_root)
+        except PermissionError as e:
+            print(str(e), file=sys.stderr)
+            return 4
+
+    parent_data = load_task_json(parent_dir)
+    child_data = load_task_json(child_dir)
+
+    if parent_data:
+        children = parent_data.get("children", [])
+        if child_dir.name in children:
+            children.remove(child_dir.name)
+            parent_data["children"] = children
+            parent_data["updated_at"] = datetime.now().isoformat()
+            write_task_json(parent_dir, parent_data)
+
+    if child_data:
+        child_data["parent"] = None
+        child_data["updated_at"] = datetime.now().isoformat()
+        write_task_json(child_dir, child_data)
+
+    print(f"Subtask removed: {parent_dir.name} -x- {child_dir.name}")
+    return 0
+
+
+# =============================================================================
+# 工具函数
+# =============================================================================
+
+def _generate_slug(title: str) -> str:
+    """从标题生成 URL-safe slug。"""
+    # 简单处理: 小写, 空格转连字符, 只保留字母数字和连字符
+    slug = title.lower().strip()
+    slug = "".join(c if c.isalnum() or c in " -_" else "" for c in slug)
+    slug = slug.replace(" ", "-").replace("_", "-")
+    slug = "-".join(part for part in slug.split("-") if part)
+    return slug[:50] if slug else "untitled"
+
+
+# =============================================================================
+# 命令: set-due / block / unblock / gantt (B2 能力增强)
+# =============================================================================
+
+def cmd_set_due(args: argparse.Namespace) -> int:
+    """设置任务截止日期。用法: task.py set-due <task> <YYYY-MM-DD>"""
+    repo_root = get_repo_root()
+    full_path = resolve_task_dir(args.task, repo_root)
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {args.task}", file=sys.stderr)
+        return 1
+    # ACL
+    try:
+        assert_can_modify_task(full_path, "set-due", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+    task_data = load_task_json(full_path)
+    if not task_data:
+        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
+
+
+def cmd_block(args: argparse.Namespace) -> int:
+    """标记任务被另一任务阻塞。自动维护反向 blocks 关系。
+    用法: task.py block <task> <blocked-by-task>
+    语义: <task> 被 <blocked-by-task> 阻塞 (要等它完成)。
+    """
+    repo_root = get_repo_root()
+    task_dir = resolve_task_dir(args.task, repo_root)
+    blocker_dir = resolve_task_dir(args.blocker, repo_root)
+    if not task_dir.is_dir():
+        print(f"Error: Task not found: {args.task}", file=sys.stderr)
+        return 1
+    if not blocker_dir.is_dir():
+        print(f"Error: Blocker task not found: {args.blocker}", file=sys.stderr)
+        return 1
+    # ACL: 只有 task 的 owner 能加依赖
+    try:
+        assert_can_modify_task(task_dir, "block", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+
+    # 检测循环依赖
+    if _would_create_cycle(task_dir.name, blocker_dir.name, repo_root):
+        print(f"Error: 循环依赖检测到 ({blocker_dir.name} 已直接/间接依赖 {task_dir.name})",
+              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:
+        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 []
+        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)
+
+    print(f"{task_dir.name} now blocked by {blocker_dir.name}")
+    return 0
+
+
+def cmd_unblock(args: argparse.Namespace) -> int:
+    """移除阻塞关系。用法: task.py unblock <task> <blocked-by-task>"""
+    repo_root = get_repo_root()
+    task_dir = resolve_task_dir(args.task, repo_root)
+    blocker_dir = resolve_task_dir(args.blocker, repo_root)
+    if task_dir.is_dir():
+        try:
+            assert_can_modify_task(task_dir, "unblock", repo_root)
+        except PermissionError as e:
+            print(str(e), file=sys.stderr)
+            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
+
+    if removed:
+        print(f"Removed block: {task_dir.name} no longer blocked by {blocker_dir.name}")
+    else:
+        print(f"No such block relationship found")
+    return 0
+
+
+def _would_create_cycle(task_name: str, blocker_name: str, repo_root) -> bool:
+    """检测添加 task←blocker 后是否会形成循环依赖。
+    即: blocker 是否(直接/间接)已经依赖 task?
+    """
+    if task_name == blocker_name:
+        return True
+    # BFS: 从 blocker 出发, 沿 blocked_by 走, 看能否回到 task
+    visited = set()
+    queue = [blocker_name]
+    tasks_dir = get_tasks_dir(repo_root)
+    while queue:
+        current = queue.pop(0)
+        if current in visited:
+            continue
+        visited.add(current)
+        if current == task_name:
+            return True
+        cur_dir = tasks_dir / current
+        data = load_task_json(cur_dir) if cur_dir.is_dir() else None
+        if data:
+            for dep in (data.get("blocked_by") or []):
+                if dep not in visited:
+                    queue.append(dep)
+    return False
+
+
+def _is_task_ready(task_data: dict) -> bool:
+    """任务是否"可立即开始": 未完成 且 无未完成的 blocked_by。"""
+    if task_data.get("status") == "completed":
+        return False
+    blocked_by = task_data.get("blocked_by") or []
+    # blocked_by 为空 = 可开始 (这里简化: 不深入查依赖是否完成, 由调用方保证)
+    return len(blocked_by) == 0
+
+
+def cmd_gantt(args: argparse.Namespace) -> int:
+    """渲染 markdown 甘特图 (按 start_date/due_date 排期)。
+    用法: task.py gantt [--weeks 4]
+    """
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    if not tasks_dir.is_dir():
+        print("No tasks directory")
+        return 0
+
+    from datetime import date, timedelta
+    today = date.today()
+    weeks = args.weeks if hasattr(args, "weeks") else 4
+    end = today + timedelta(weeks=weeks)
+
+    # 收集有日期的任务
+    items = []
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir():
+            continue
+        data = load_task_json(d)
+        if not data:
+            continue
+        due = data.get("due_date")
+        start = data.get("start_date")
+        if not due and not start:
+            continue
+        items.append({
+            "name": d.name,
+            "title": data.get("title", d.name),
+            "start": start,
+            "due": due,
+            "status": data.get("status", "?"),
+            "assignee": data.get("assignee", "?"),
+        })
+
+    if not items:
+        print("No tasks with dates. 用 'task.py set-due <task> <YYYY-MM-DD>' 添加截止日期。")
+        return 0
+
+    # 按开始/截止日期排序
+    items.sort(key=lambda x: (x.get("start") or x.get("due") or "9999"))
+
+    print(f"# 任务排期 ({today} ~ {end})\n")
+    print("| 任务 | 负责人 | 开始 | 截止 | 状态 |")
+    print("|------|--------|------|------|------|")
+    for it in items:
+        start = it.get("start") or "-"
+        due = it.get("due") or "-"
+        # 标记逾期
+        if it.get("due") and it["status"] != "completed":
+            try:
+                due_date = date.fromisoformat(it["due"])
+                if due_date < today:
+                    due = f"⚠️ {due} (逾期)"
+            except ValueError:
+                pass
+        print(f"| {it['name']} | {it['assignee']} | {start} | {due} | {it['status']} |")
+
+    # 简单时间轴 (ASCII)
+    print(f"\n## 时间轴 ({weeks} 周)\n")
+    print("```")
+    for it in items:
+        start_s = it.get("start") or it.get("due")
+        if not start_s:
+            continue
+        try:
+            start_d = date.fromisoformat(start_s) if it.get("start") else today
+        except ValueError:
+            start_d = today
+        due_s = it.get("due")
+        try:
+            due_d = date.fromisoformat(due_s) if due_s else start_d + timedelta(days=7)
+        except ValueError:
+            due_d = start_d + timedelta(days=7)
+        # 计算相对今天的偏移
+        start_off = max(0, (start_d - today).days)
+        due_off = min(weeks * 7, (due_d - today).days)
+        if due_off < 0:
+            bar = "[逾期]" + "=" * 5
+        else:
+            bar = " " * (start_off // 2) + "[" + "=" * max(1, (due_off - start_off) // 2) + "]"
+        print(f"{it['name'][:20]:20} {bar}")
+    print("```")
+    return 0
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+def main() -> int:
+    """CLI 入口。"""
+    parser = argparse.ArgumentParser(description="QODER Task Management")
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # create
+    p_create = subparsers.add_parser("create", help="Create a new task")
+    p_create.add_argument("title", help="Task title")
+    p_create.add_argument("--slug", help="URL-safe slug (auto-generated if omitted)")
+    p_create.add_argument("--assignee", help="Assignee (defaults to current developer)")
+    p_create.add_argument("--priority", choices=["P0", "P1", "P2", "P3"], default="P2")
+    p_create.set_defaults(func=cmd_create)
+
+    # start
+    p_start = subparsers.add_parser("start", help="Start a task")
+    p_start.add_argument("dir", help="Task directory or name")
+    p_start.set_defaults(func=cmd_start)
+
+    # current
+    p_current = subparsers.add_parser("current", help="Show current task")
+    p_current.add_argument("--source", action="store_true", help="Show source info")
+    p_current.set_defaults(func=cmd_current)
+
+    # finish
+    p_finish = subparsers.add_parser("finish", help="Finish current task")
+    p_finish.set_defaults(func=cmd_finish)
+
+    # archive
+    p_archive = subparsers.add_parser("archive", help="Archive a task")
+    p_archive.add_argument("dir", help="Task directory or name")
+    p_archive.set_defaults(func=cmd_archive)
+
+    # list
+    p_list = subparsers.add_parser("list", help="List tasks")
+    p_list.add_argument("--mine", action="store_true", help="Only my tasks (assignee or creator)")
+    p_list.add_argument("--status", help="Filter by status")
+    p_list.add_argument("--ready", action="store_true", help="只显示可立即开始的 (无未完成依赖)")
+    p_list.add_argument("--blocked", action="store_true", help="只显示被阻塞的任务")
+    p_list.set_defaults(func=cmd_list)
+
+    # show
+    p_show = subparsers.add_parser("show", help="Show task details")
+    p_show.add_argument("dir", help="Task directory or name")
+    p_show.set_defaults(func=cmd_show)
+
+    # add-subtask
+    p_addsub = subparsers.add_parser("add-subtask", help="Add subtask")
+    p_addsub.add_argument("parent", help="Parent task")
+    p_addsub.add_argument("child", help="Child task")
+    p_addsub.set_defaults(func=cmd_add_subtask)
+
+    # remove-subtask
+    p_remsub = subparsers.add_parser("remove-subtask", help="Remove subtask")
+    p_remsub.add_argument("parent", help="Parent task")
+    p_remsub.add_argument("child", help="Child task")
+    p_remsub.set_defaults(func=cmd_remove_subtask)
+
+    # set-due (B2)
+    p_due = subparsers.add_parser("set-due", help="Set due date (YYYY-MM-DD)")
+    p_due.add_argument("task", help="Task name")
+    p_due.add_argument("due_date", help="Due date YYYY-MM-DD")
+    p_due.set_defaults(func=cmd_set_due)
+
+    # block (B2)
+    p_block = subparsers.add_parser("block", help="Mark task blocked by another")
+    p_block.add_argument("task", help="Task that is blocked")
+    p_block.add_argument("blocker", help="Task that blocks it (must finish first)")
+    p_block.set_defaults(func=cmd_block)
+
+    # unblock (B2)
+    p_unblock = subparsers.add_parser("unblock", help="Remove block relationship")
+    p_unblock.add_argument("task", help="Task")
+    p_unblock.add_argument("blocker", help="Blocker task")
+    p_unblock.set_defaults(func=cmd_unblock)
+
+    # gantt (B2)
+    p_gantt = subparsers.add_parser("gantt", help="Render markdown Gantt chart")
+    p_gantt.add_argument("--weeks", type=int, default=4, help="Number of weeks to show")
+    p_gantt.set_defaults(func=cmd_gantt)
+
+    args = parser.parse_args()
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 1
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())