@hupan56/wlkj 3.0.0 → 3.1.2

package/templates/qoder/scripts/{task → domain/task}/task_lifecycle.py

@@ -1,596 +1,606 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""task_lifecycle.py - task 生命周期层 (v3.0 f6 从 task.py 拆出)"""
-# v3.0 路径自举
-import os as _o, sys as _s, argparse
-from pathlib import Path
-from datetime import datetime
-_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
-if _cp not in _s.path: _s.path.insert(0, _cp)
-from bootstrap import setup; setup()
-
-import os, sys, json, shutil
-from datetime import datetime
-from pathlib import Path
-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,
-    modify_task_json, assert_can_modify_task,
-)
-from common.atomicio import atomic_write_json, safe_read_json, atomic_write_text
-
-
-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 状态 (锁内 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)
-        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()
-    # 先只读解析活跃任务 (resolve_active_task 不删指针), 做 ACL 校验;
-    # 校验通过后才 clear_active_task。否则 ACL 失败时指针已丢、status 没改,
-    # 用户必须重新 start 才能恢复活跃任务 (误触/会话被他人接手时尤其痛)。
-    active = resolve_active_task(repo_root)
-    current = active.task_path
-
-    if not current:
-        print("No current task set")
-        return 0
-
-    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
-
-    # ACL 通过, 现在才安全地清除活跃任务指针
-    cleared = clear_active_task(repo_root)
-    print(f"Cleared current task (was: {cleared.task_path})")
-    print(f"Source: {cleared.source}")
-
-    # 锁内 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 = _finish_ctx["stage_ts"].get("started")
-            if started:
-                try:
-                    from datetime import datetime as _dt
-                    t_start = _dt.fromisoformat(started)
-                    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, _finish_ctx["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)
-
-    # 🧩 测试交接画像 (可选增强): finish 后在任务目录生成 test-handoff.md,
-    # 列出涉及的页面/按钮/接口, 供测试人员照着写用例。失败绝不阻塞任务完成。
-    try:
-        _generate_test_handoff(task_dir, repo_root)
-    except Exception as e:
-        print("[测试交接画像] 跳过 (不阻塞): " + str(e)[:80])
-
-    # 埋点: 任务完成反馈给 learning 引擎
-    if _finish_ctx:
-        try:
-            from learn import record_feedback
-            record_feedback('task_completed', {
-                'task': task_dir.name,
-                'assignee': _finish_ctx.get('assignee', '?'),
-                'hours': _finish_ctx.get('now_iso'),
-            })
-        except Exception:
-            pass  # 埋点失败不阻塞任务完成
-
-    return 0
-
-
-def _extract_keywords(task_dir: Path) -> list:
-    """从任务目录名 + task.json 标题 + PRD 正文提取业务关键词。
-    返回去重的关键词列表 (用于 page_probe 查页面画像)。
-    """
-    kws = []
-    # 1. 任务目录名: 06-11-智能排班-环卫行业 → 智能排班, 环卫行业
-    dirname = task_dir.name
-    # 去掉日期前缀 (MM-DD- 或 MM-DD-)
-    parts = dirname.split('-')
-    # 找到第一个非纯数字段开始
-    biz_parts = []
-    started = False
-    for p in parts:
-        if not started:
-            if p.isdigit() and len(p) <= 2:
-                continue  # 跳过 MM, DD
-            started = True
-        if p.strip():
-            biz_parts.append(p.strip())
-    if biz_parts:
-        kws.append(''.join(biz_parts))  # 整体: 智能排班环卫行业
-        if len(biz_parts) > 1:
-            kws.extend(biz_parts)  # 分开: 智能排班, 环卫行业
-
-    # 2. task.json 的 title 字段
-    title = ''
-    try:
-        tj = task_dir / FILE_TASK_JSON
-        if tj.is_file():
-            data = load_task_json(task_dir) or {}
-            title = data.get('title', '')
-            if title and title not in kws:
-                kws.append(title)
-    except Exception:
-        pass
-
-    # 2.5 从标题/目录名里切出短业务词 (保险异常筛选 → 保险, 异常, 筛选)
-    # page_probe 用 LIKE 查 vue 路径, 短词命中率更高
-    import re
-    cn_chunks = re.findall(r'[\u4e00-\u9fa5]+', (dirname + title))
-    short_words = set()
-    for chunk in cn_chunks:
-        # 2-4 字的连续子串都是有意义的业务词候选
-        if 2 <= len(chunk) <= 4:
-            short_words.add(chunk)
-        elif len(chunk) > 4:
-            # 长词切前4字、后4字、中间4字 (覆盖"智能排班系统"→智能排班/排班系统)
-            short_words.add(chunk[:4])
-            short_words.add(chunk[-4:])
-    # 去太泛的词
-    generic = {'功能', '系统', '管理', '模块', '页面', '需求', '设计', '实现',
-               '新增', '修改', '查询', '删除', '操作', '记录', '列表', '详情'}
-    for w in short_words:
-        if w not in generic and w not in kws:
-            kws.append(w)
-
-    # 3. PRD 正文里的业务关键词 (从标题和需求段落粗提)
-    try:
-        prd = task_dir / 'prd.md'
-        if prd.is_file():
-            content = prd.read_text(encoding='utf-8', errors='ignore')
-            import re
-            # 提取中文词组 (2-6 字连续中文)
-            cn_words = re.findall(r'[\u4e00-\u9fa5]{2,6}', content)
-            # 去停用词 + 高频词
-            stop = {'功能', '需求', '系统', '页面', '数据', '支持', '可以',
-                    '进行', '操作', '显示', '一个', '这个', '实现', '业务',
-                    '测试', '使用', '如果', '需要', '必须', '以及', '界面'}
-            from collections import Counter
-            freq = Counter(w for w in cn_words if w not in stop)
-            for w, _ in freq.most_common(5):
-                if w not in kws and len(w) >= 2:
-                    kws.append(w)
-    except Exception:
-        pass
-
-    # 去重保序, 过滤太短的
-    seen = set()
-    result = []
-    for k in kws:
-        if k and len(k) >= 2 and k not in seen:
-            seen.add(k)
-            result.append(k)
-    return result[:6]  # 最多 6 个, 避免查太多
-
-
-def _generate_test_handoff(task_dir: Path, repo_root) -> None:
-    """finish 后生成 test-handoff.md (开发→测试交接画像)。
-    从任务关键词查页面按钮+接口画像, 写入任务目录。无图谱/无匹配则跳过。
-    """
-    try:
-        import page_probe
-    except ImportError:
-        sys.path.insert(0, str(repo_root / '.qoder' / 'scripts'))
-        import page_probe
-
-    kws = _extract_keywords(task_dir)
-    if not kws:
-        print("[测试交接画像] 跳过: 任务无明确业务关键词")
-        return
-
-    # 用每个关键词查画像, 合并结果
-    all_pages = []
-    seen_vue = set()
-    used_kws = []
-    for kw in kws:
-        profile = page_probe.build_page_profile(keyword=kw, repo_root=str(repo_root))
-        if not profile.get('ok'):
-            continue
-        for pg in profile['pages']:
-            if pg['vue_file'] in seen_vue:
-                continue
-            seen_vue.add(pg['vue_file'])
-            all_pages.append(pg)
-        used_kws.append(kw)
-        if len(all_pages) >= 12:  # 够多了, 停止查更多关键词
-            break
-
-    handoff_path = task_dir / 'test-handoff.md'
-    if not all_pages:
-        # 没匹配到页面: 写一个提示性 handoff (让测试知道开发想覆盖什么)
-        lines = [
-            '# 测试交接: %s' % task_dir.name,
-            '',
-            '> 任务完成于 %s' % datetime.now().strftime('%Y-%m-%d %H:%M'),
-            '> 业务关键词: %s' % ', '.join(kws),
-            '',
-            '## ⚠️ 未能自动生成页面画像',
-            '',
-            '知识图谱里没有匹配这些关键词的页面按钮记录。可能原因:',
-            '- 功能是全新的, 代码还没被知识图谱索引',
-            '- 关键词与代码里的命名不一致',
-            '',
-            '**测试建议:** 手动确认涉及的页面, 或用 `autotest.py page --kw <准确关键词>` 重试。',
-        ]
-        handoff_path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
-        print("[测试交接画像] %s (无匹配页面, 已写提示)" % handoff_path.name)
-        return
-
-    # 渲染完整画像
-    total_btns = sum(len(pg['buttons']) for pg in all_pages)
-    lines = [
-        '# 测试交接: %s' % task_dir.name,
-        '',
-        '> 任务完成于 %s' % datetime.now().strftime('%Y-%m-%d %H:%M'),
-        '> 业务关键词: %s' % ', '.join(used_kws),
-        '> 共 %d 个页面, %d 个交互点' % (len(all_pages), total_btns),
-        '',
-        '> 💡 测试人员照此写用例, 不用自己找页面按钮。每行"按钮→接口"就是一个用例的核心断言点。',
-        '> 未解析到接口的按钮 (deferred/unresolved) 需现场点击确认实际调用。',
-        '',
-    ]
-
-    # 复用 page_probe 的渲染, 但按页面输出
-    fake_profile = {'ok': True, 'pages': all_pages, 'stats': page_probe._trace_stats(str(repo_root))}
-    lines.append(page_probe.render_profile_md(fake_profile))
-
-    lines.append('')
-    lines.append('---')
-    lines.append('')
-    lines.append('## 测试用例生成')
-    lines.append('拿到这份画像后, 直接说:')
-    lines.append('- "测一下 %s" → 走 /wl-test quick 自动生成用例' % (used_kws[0] if used_kws else '这个功能'))
-    lines.append('- 或 `/wl-test browser %s` → 按任务 PRD 生成回归用例' % task_dir.name)
-    lines.append('- 也可 `autotest.py page --kw <更精确的关键词>` 单独查某页画像')
-
-    handoff_path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
-    print("[测试交接画像] 已生成 %s (%d 页面, %d 交互点)"
-          % (handoff_path.name, len(all_pages), total_btns))
-
-
-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
-# =============================================================================
-
-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)
-
-    # 清理孤儿依赖: 其它任务可能引用了本任务 (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
-
-
-# =============================================================================
-# 命令: list
-# =============================================================================
-
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""task_lifecycle.py - task 生命周期层 (v3.0 f6 从 task.py 拆出)"""
+# v3.0 路径自举
+import os as _o, sys as _s, argparse
+from pathlib import Path
+from datetime import datetime
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'foundation')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+from foundation.core.paths import get_repo_root
+
+import os, sys, json, shutil
+from datetime import datetime
+from pathlib import Path
+from foundation.core.paths import (
+    DIR_TASKS, DIR_ARCHIVE, FILE_TASK_JSON,
+    get_repo_root, get_developer, get_tasks_dir,
+)
+from foundation.integrations.active_task import (
+    clear_active_task, resolve_active_task, resolve_context_key, set_active_task,
+)
+from foundation.data.task_utils import (
+    resolve_task_dir, run_task_hooks, load_task_json, write_task_json,
+    modify_task_json, assert_can_modify_task,
+)
+from foundation.io.atomicio import atomic_write_json, safe_read_json, atomic_write_text
+from task_relations import _generate_slug
+
+
+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,
+        # 关联需求 (PRD↔Task 串联键, 用于可用性指标 F1 闭环率; 旧 task.json 无此字段, 读时默认 None)
+        "req_id": getattr(args, 'req_id', None),
+        "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 状态 (锁内 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)
+        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()
+    # 先只读解析活跃任务 (resolve_active_task 不删指针), 做 ACL 校验;
+    # 校验通过后才 clear_active_task。否则 ACL 失败时指针已丢、status 没改,
+    # 用户必须重新 start 才能恢复活跃任务 (误触/会话被他人接手时尤其痛)。
+    active = resolve_active_task(repo_root)
+    current = active.task_path
+
+    if not current:
+        print("No current task set")
+        return 0
+
+    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
+
+    # ACL 通过, 现在才安全地清除活跃任务指针
+    cleared = clear_active_task(repo_root)
+    print(f"Cleared current task (was: {cleared.task_path})")
+    print(f"Source: {cleared.source}")
+
+    # 锁内 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", "?")
+            # 算真实周期耗时 (小时): started -> completed, 供埋点用
+            started = stage_ts.get("started")
+            _finish_ctx["cycle_hours"] = None
+            if started:
+                try:
+                    t_start = datetime.fromisoformat(started)
+                    t_end = datetime.fromisoformat(now_iso)
+                    _finish_ctx["cycle_hours"] = round(
+                        (t_end - t_start).total_seconds() / 3600, 2)
+                except (ValueError, TypeError):
+                    pass
+    modify_task_json(task_dir, _finish_mutator)
+
+    # D2: 飞书通知 (任务完成) —— 在锁外, 用 mutator 捕获的值
+    if _finish_ctx:
+        try:
+            from foundation.integrations.feishu import notify_task_finished
+            notify_task_finished(task_dir.name, _finish_ctx["assignee"], _finish_ctx.get("cycle_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)
+
+    # 🧩 测试交接画像 (可选增强): finish 后在任务目录生成 test-handoff.md,
+    # 列出涉及的页面/按钮/接口, 供测试人员照着写用例。失败绝不阻塞任务完成。
+    try:
+        _generate_test_handoff(task_dir, repo_root)
+    except Exception as e:
+        print("[测试交接画像] 跳过 (不阻塞): " + str(e)[:80])
+
+    # 埋点: 任务完成反馈给 learning 引擎 (含真实周期耗时, 供可用性指标)
+    if _finish_ctx:
+        try:
+            # learn.py 在 domain/learning/, bootstrap 只注入一层子目录, 这里补上
+            _learn_dir = os.path.join(os.path.dirname(os.path.dirname(__file__)), 'learning')
+            if _learn_dir not in sys.path:
+                sys.path.insert(0, _learn_dir)
+            from learn import record_feedback
+            record_feedback('task_completed', {
+                'task': task_dir.name,
+                'assignee': _finish_ctx.get('assignee', '?'),
+                # cycle_hours = started->completed 的真实小时数 (None=未start直接finish)
+                'cycle_hours': _finish_ctx.get('cycle_hours'),
+            })
+        except Exception:
+            pass  # 埋点失败不阻塞任务完成
+
+    return 0
+
+
+def _extract_keywords(task_dir: Path) -> list:
+    """从任务目录名 + task.json 标题 + PRD 正文提取业务关键词。
+    返回去重的关键词列表 (用于 page_probe 查页面画像)。
+    """
+    kws = []
+    # 1. 任务目录名: 06-11-智能排班-环卫行业 → 智能排班, 环卫行业
+    dirname = task_dir.name
+    # 去掉日期前缀 (MM-DD- 或 MM-DD-)
+    parts = dirname.split('-')
+    # 找到第一个非纯数字段开始
+    biz_parts = []
+    started = False
+    for p in parts:
+        if not started:
+            if p.isdigit() and len(p) <= 2:
+                continue  # 跳过 MM, DD
+            started = True
+        if p.strip():
+            biz_parts.append(p.strip())
+    if biz_parts:
+        kws.append(''.join(biz_parts))  # 整体: 智能排班环卫行业
+        if len(biz_parts) > 1:
+            kws.extend(biz_parts)  # 分开: 智能排班, 环卫行业
+
+    # 2. task.json 的 title 字段
+    title = ''
+    try:
+        tj = task_dir / FILE_TASK_JSON
+        if tj.is_file():
+            data = load_task_json(task_dir) or {}
+            title = data.get('title', '')
+            if title and title not in kws:
+                kws.append(title)
+    except Exception:
+        pass
+
+    # 2.5 从标题/目录名里切出短业务词 (保险异常筛选 → 保险, 异常, 筛选)
+    # page_probe 用 LIKE 查 vue 路径, 短词命中率更高
+    import re
+    cn_chunks = re.findall(r'[\u4e00-\u9fa5]+', (dirname + title))
+    short_words = set()
+    for chunk in cn_chunks:
+        # 2-4 字的连续子串都是有意义的业务词候选
+        if 2 <= len(chunk) <= 4:
+            short_words.add(chunk)
+        elif len(chunk) > 4:
+            # 长词切前4字、后4字、中间4字 (覆盖"智能排班系统"→智能排班/排班系统)
+            short_words.add(chunk[:4])
+            short_words.add(chunk[-4:])
+    # 去太泛的词
+    generic = {'功能', '系统', '管理', '模块', '页面', '需求', '设计', '实现',
+               '新增', '修改', '查询', '删除', '操作', '记录', '列表', '详情'}
+    for w in short_words:
+        if w not in generic and w not in kws:
+            kws.append(w)
+
+    # 3. PRD 正文里的业务关键词 (从标题和需求段落粗提)
+    try:
+        prd = task_dir / 'prd.md'
+        if prd.is_file():
+            content = prd.read_text(encoding='utf-8', errors='ignore')
+            import re
+            # 提取中文词组 (2-6 字连续中文)
+            cn_words = re.findall(r'[\u4e00-\u9fa5]{2,6}', content)
+            # 去停用词 + 高频词
+            stop = {'功能', '需求', '系统', '页面', '数据', '支持', '可以',
+                    '进行', '操作', '显示', '一个', '这个', '实现', '业务',
+                    '测试', '使用', '如果', '需要', '必须', '以及', '界面'}
+            from collections import Counter
+            freq = Counter(w for w in cn_words if w not in stop)
+            for w, _ in freq.most_common(5):
+                if w not in kws and len(w) >= 2:
+                    kws.append(w)
+    except Exception:
+        pass
+
+    # 去重保序, 过滤太短的
+    seen = set()
+    result = []
+    for k in kws:
+        if k and len(k) >= 2 and k not in seen:
+            seen.add(k)
+            result.append(k)
+    return result[:6]  # 最多 6 个, 避免查太多
+
+
+def _generate_test_handoff(task_dir: Path, repo_root) -> None:
+    """finish 后生成 test-handoff.md (开发→测试交接画像)。
+    从任务关键词查页面按钮+接口画像, 写入任务目录。无图谱/无匹配则跳过。
+    """
+    try:
+        import page_probe
+    except ImportError:
+        sys.path.insert(0, str(repo_root / '.qoder' / 'scripts'))
+        import page_probe
+
+    kws = _extract_keywords(task_dir)
+    if not kws:
+        print("[测试交接画像] 跳过: 任务无明确业务关键词")
+        return
+
+    # 用每个关键词查画像, 合并结果
+    all_pages = []
+    seen_vue = set()
+    used_kws = []
+    for kw in kws:
+        profile = page_probe.build_page_profile(keyword=kw, repo_root=str(repo_root))
+        if not profile.get('ok'):
+            continue
+        for pg in profile['pages']:
+            if pg['vue_file'] in seen_vue:
+                continue
+            seen_vue.add(pg['vue_file'])
+            all_pages.append(pg)
+        used_kws.append(kw)
+        if len(all_pages) >= 12:  # 够多了, 停止查更多关键词
+            break
+
+    handoff_path = task_dir / 'test-handoff.md'
+    if not all_pages:
+        # 没匹配到页面: 写一个提示性 handoff (让测试知道开发想覆盖什么)
+        lines = [
+            '# 测试交接: %s' % task_dir.name,
+            '',
+            '> 任务完成于 %s' % datetime.now().strftime('%Y-%m-%d %H:%M'),
+            '> 业务关键词: %s' % ', '.join(kws),
+            '',
+            '## ⚠️ 未能自动生成页面画像',
+            '',
+            '知识图谱里没有匹配这些关键词的页面按钮记录。可能原因:',
+            '- 功能是全新的, 代码还没被知识图谱索引',
+            '- 关键词与代码里的命名不一致',
+            '',
+            '**测试建议:** 手动确认涉及的页面, 或用 `autotest.py page --kw <准确关键词>` 重试。',
+        ]
+        handoff_path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+        print("[测试交接画像] %s (无匹配页面, 已写提示)" % handoff_path.name)
+        return
+
+    # 渲染完整画像
+    total_btns = sum(len(pg['buttons']) for pg in all_pages)
+    lines = [
+        '# 测试交接: %s' % task_dir.name,
+        '',
+        '> 任务完成于 %s' % datetime.now().strftime('%Y-%m-%d %H:%M'),
+        '> 业务关键词: %s' % ', '.join(used_kws),
+        '> 共 %d 个页面, %d 个交互点' % (len(all_pages), total_btns),
+        '',
+        '> 💡 测试人员照此写用例, 不用自己找页面按钮。每行"按钮→接口"就是一个用例的核心断言点。',
+        '> 未解析到接口的按钮 (deferred/unresolved) 需现场点击确认实际调用。',
+        '',
+    ]
+
+    # 复用 page_probe 的渲染, 但按页面输出
+    fake_profile = {'ok': True, 'pages': all_pages, 'stats': page_probe._trace_stats(str(repo_root))}
+    lines.append(page_probe.render_profile_md(fake_profile))
+
+    lines.append('')
+    lines.append('---')
+    lines.append('')
+    lines.append('## 测试用例生成')
+    lines.append('拿到这份画像后, 直接说:')
+    lines.append('- "测一下 %s" → 走 /wl-test quick 自动生成用例' % (used_kws[0] if used_kws else '这个功能'))
+    lines.append('- 或 `/wl-test browser %s` → 按任务 PRD 生成回归用例' % task_dir.name)
+    lines.append('- 也可 `autotest.py page --kw <更精确的关键词>` 单独查某页画像')
+
+    handoff_path.write_text('\n'.join(lines) + '\n', encoding='utf-8')
+    print("[测试交接画像] 已生成 %s (%d 页面, %d 交互点)"
+          % (handoff_path.name, len(all_pages), total_btns))
+
+
+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
+# =============================================================================
+
+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)
+
+    # 清理孤儿依赖: 其它任务可能引用了本任务 (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
+
+
+# =============================================================================
+# 命令: list
+# =============================================================================
+