@hupan56/wlkj 2.7.12 → 3.1.2

package/templates/qoder/scripts/validation/metrics/usability_score.py

@@ -0,0 +1,750 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# v3.0 路径自举: 引导到 common/bootstrap, 统一 sys.path 逻辑
+import os as _o, sys as _s
+_f = _o.path.abspath(__file__)
+for _ in range(10):
+    _f = _o.path.dirname(_f)
+    _cp = _o.path.join(_f, 'foundation')
+    if _o.path.isfile(_o.path.join(_cp, 'bootstrap.py')):
+        break
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+
+"""
+usability_score.py — QODER 工作流可用性评测 (采纳优先 + 流程辅助)
+
+回答: 这套工作流对真实团队, 到底好不好用、用不用得起来?
+指标定义见 data/docs/constitution/workflow-usability-metrics.md
+
+读现有真实数据 (零外部依赖, 纯函数):
+  - data/learning/eval-history.jsonl   PRD 质量评测历史 (自动)
+  - workspace/members/*/journal/feedback.jsonl   事件流 (rule_violation/task_completed/...)
+  - workspace/members/*/journal/learning.yaml   计数汇总
+  - data/docs/prd/*.md   已发布需求文档 (绕过率/采纳率)
+  - workspace/tasks/*/task.json   任务 (周期/孤岛)
+  - 复用 validation/eval/transcript_timing.py   迭代轮/工具调用 (有则读)
+
+诚实标注: 能算的算; 算不了的标 NEEDS_INSTRUMENTATION + 软估算; 绝不编造好看的数。
+
+用法:
+  python usability_score.py             # 人读 (终端表格)
+  python usability_score.py --json      # 机器读 (供 wl-status 拉)
+  python usability_score.py --days 14   # 评测最近 N 天 (默认 7)
+"""
+import argparse
+import json
+import os
+import re
+import sys
+from datetime import datetime, timedelta
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except (AttributeError, TypeError, OSError):
+    pass
+
+from foundation.core.paths import get_repo_root
+
+REPO = get_repo_root()
+EVAL_HISTORY = REPO / 'data' / 'learning' / 'eval-history.jsonl'
+PRD_DIR = REPO / 'data' / 'docs' / 'prd'
+MEMBERS_DIR = REPO / 'workspace' / 'members'
+TASKS_DIR = REPO / 'workspace' / 'tasks'
+
+REQ_RE = re.compile(r'REQ-\d{2,4}(?:-\d{2,4})?', re.IGNORECASE)
+REQ_FILENAME_RE = re.compile(r'REQ[-_]\d', re.IGNORECASE)
+
+
+# ── 数据加载 (纯函数, 失败返回空, 绝不崩) ─────────────────────────────
+def _read_jsonl(path):
+    """读 jsonl, 每行一条; 坏行跳过。返回 list[dict]。"""
+    if not path.is_file():
+        return []
+    out = []
+    with open(path, encoding='utf-8', errors='replace') as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except (ValueError, TypeError):
+                continue
+    return out
+
+
+def _collect_feedback():
+    """收集所有人的 feedback.jsonl, 合并成 list, 附 dev 来源。"""
+    events = []
+    if not MEMBERS_DIR.is_dir():
+        return events
+    for dev_dir in MEMBERS_DIR.iterdir():
+        fb = dev_dir / 'journal' / 'feedback.jsonl'
+        if not fb.is_file():
+            continue
+        for row in _read_jsonl(fb):
+            row.setdefault('dev', dev_dir.name)
+            events.append(row)
+    return events
+
+
+def _collect_learning_yaml():
+    """汇总所有人的 learning.yaml 计数。返回 dict[stat->sum]。"""
+    totals = {}
+    if not MEMBERS_DIR.is_dir():
+        return totals
+    for dev_dir in MEMBERS_DIR.iterdir():
+        yml = dev_dir / 'journal' / 'learning.yaml'
+        if not yml.is_file():
+            continue
+        try:
+            import yaml
+            data = yaml.safe_load(yml.read_text(encoding='utf-8')) or {}
+        except Exception:
+            continue
+        if isinstance(data, dict):
+            for k, v in data.items():
+                if isinstance(v, (int, float)):
+                    totals[k] = totals.get(k, 0) + v
+    return totals
+
+
+def _collect_tasks():
+    """读所有 task.json。返回 list[dict]。"""
+    tasks = []
+    if not TASKS_DIR.is_dir():
+        return tasks
+    for td in TASKS_DIR.iterdir():
+        tj = td / 'task.json'
+        if not tj.is_file():
+            continue
+        try:
+            tasks.append(json.loads(tj.read_text(encoding='utf-8')))
+        except Exception:
+            continue
+    return tasks
+
+
+def _published_prd_files():
+    """data/docs/prd 下 .md 需求文档 (排除模板/培训材料)。返回 list[Path]。"""
+    if not PRD_DIR.is_dir():
+        return []
+    md = []
+    for p in PRD_DIR.rglob('*.md'):
+        md.append(p)
+    return md
+
+
+# ── 时间过滤 ───────────────────────────────────────────────────────────
+def _within(ts_str, days):
+    """ts_str (ISO) 是否在最近 N 天内。解析失败返回 False。"""
+    if not ts_str:
+        return False
+    try:
+        t = datetime.fromisoformat(str(ts_str).split('.')[0].replace('Z', ''))
+    except (ValueError, TypeError):
+        return False
+    return t >= datetime.now() - timedelta(days=days)
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# 指标计算 —— 每个 return dict 带 {value, unit, level(绿/黄/红/-), auto, note}
+# ═══════════════════════════════════════════════════════════════════════
+
+def _level(value, green, yellow_max):
+    """阈值判定: value>=green 绿; >=yellow_max 黄; 否则红。
+    green/yellow_max 是「达标边界」, value 越高越好。"""
+    if value is None:
+        return '-'
+    if value >= green:
+        return 'green'
+    if value >= yellow_max:
+        return 'yellow'
+    return 'red'
+
+
+def _level_low(value, green_max, yellow_max):
+    """反向阈值: value 越低越好。value<=green_max 绿; <=yellow_max 黄; 否则红。"""
+    if value is None:
+        return '-'
+    if value <= green_max:
+        return 'green'
+    if value <= yellow_max:
+        return 'yellow'
+    return 'red'
+
+
+# ── 采纳 (U 系列) ──────────────────────────────────────────────────────
+
+def m_u2_first_pass_rate():
+    """U2 一次过审率: 首轮 eval 即 passed 的 PRD 占比。🟢自动"""
+    rows = _read_jsonl(EVAL_HISTORY)
+    if not rows:
+        return _empty('U2', '一次过审率', auto='auto')
+    by_prd = {}
+    for r in rows:
+        prd = r.get('prd')
+        if not prd:
+            continue
+        t = r.get('time', '')
+        cur = by_prd.get(prd)
+        if cur is None or (t and t < cur[0]):
+            by_prd[prd] = (t, r)
+    if not by_prd:
+        return _empty('U2', '一次过审率', auto='auto')
+    first_passed = sum(1 for (t, row) in by_prd.values() if row.get('passed'))
+    rate = 100.0 * first_passed / len(by_prd)
+    return {
+        'id': 'U2', 'name': '一次过审率',
+        'value': round(rate, 1), 'unit': '%', 'level': _level(rate, 60, 30),
+        'auto': 'auto', 'note': '%d/%d 个 PRD 首轮即过门禁' % (first_passed, len(by_prd)),
+        'data': {'passed_first': first_passed, 'total': len(by_prd)},
+    }
+
+
+def m_u3_rework_rounds():
+    """U3 返工率: 单 PRD 平均 eval 次数 - 1。🟢自动"""
+    rows = _read_jsonl(EVAL_HISTORY)
+    if not rows:
+        return _empty('U3', '返工轮数', auto='auto')
+    by_prd = {}
+    for r in rows:
+        prd = r.get('prd')
+        if prd:
+            by_prd.setdefault(prd, []).append(r)
+    if not by_prd:
+        return _empty('U3', '返工轮数', auto='auto')
+    total_evals = sum(len(v) for v in by_prd.values())
+    avg_rounds = total_evals / len(by_prd) - 1.0  # 减首轮
+    avg_rounds = max(avg_rounds, 0.0)
+    return {
+        'id': 'U3', 'name': '返工轮数',
+        'value': round(avg_rounds, 2), 'unit': '轮', 'level': _level_low(avg_rounds, 1.0, 2.0),
+        'auto': 'auto',
+        'note': '单 PRD 被打回后重做的平均轮数 (总eval %d / PRD %d - 1)' % (total_evals, len(by_prd)),
+        'data': {'total_evals': total_evals, 'prd_count': len(by_prd)},
+    }
+
+
+def m_u4_rule_violation_rate(learning_counts):
+    """U4 规则违反率: rule_violation / prds_generated。🟢自动"""
+    events = _collect_feedback()
+    violations = sum(1 for e in events if e.get('event') == 'rule_violation')
+    prds = learning_counts.get('prds_generated', 0)
+    if prds == 0:
+        return _empty('U4', '规则违反率', auto='auto')
+    rate = 100.0 * violations / prds
+    return {
+        'id': 'U4', 'name': '规则违反率',
+        'value': round(rate, 1), 'unit': '%', 'level': _level_low(rate, 10, 25),
+        'auto': 'auto', 'note': '关键规则(如 ask_platform_first)违反 %d 次 / %d PRD' % (violations, prds),
+        'data': {'violations': violations, 'prds': prds},
+    }
+
+
+def m_u1_adoption_rate(eval_rows):
+    """U1 流程采纳率: 带REQ且经eval的 / 全部prd文档。🟡半自动"""
+    md_files = _published_prd_files()
+    if not md_files:
+        return _empty('U1', '流程采纳率', auto='semi')
+    evald_prds = set(r.get('prd', '') for r in eval_rows if r.get('prd'))
+    # 看文档名里带 REQ 的(工作流产出的命名特征), 且 eval 过
+    req_files = [f for f in md_files if REQ_FILENAME_RE.search(f.name)]
+    req_and_evald = [f for f in req_files if any(f.name == e or e in f.name for e in evald_prds)]
+    rate = 100.0 * len(req_and_evald) / len(md_files) if md_files else 0
+    return {
+        'id': 'U1', 'name': '流程采纳率',
+        'value': round(rate, 1), 'unit': '%', 'level': _level(rate, 70, 40),
+        'auto': 'semi',
+        'note': 'REQ文档且经eval %d / 全部prd文档 %d (含培训/模板材料, 需人工核对)' % (len(req_and_evald), len(md_files)),
+        'data': {'workflow_prds': len(req_and_evald), 'total_docs': len(md_files)},
+    }
+
+
+def m_u5_bypass_rate(eval_rows):
+    """U5 绕过率: 进了prd目录但没eval记录的REQ文档占比。🟡半自动"""
+    md_files = _published_prd_files()
+    if not md_files:
+        return _empty('U5', '绕过率', auto='semi')
+    evald_prds = set(r.get('prd', '') for r in eval_rows if r.get('prd'))
+    req_files = [f for f in md_files if REQ_FILENAME_RE.search(f.name)]
+    if not req_files:
+        # 没有任何 REQ 命名文档 = 全是手写 (强信号: 工作流完全没用起来)
+        return {
+            'id': 'U5', 'name': '绕过率',
+            'value': None, 'unit': '%', 'level': 'red',
+            'auto': 'semi',
+            'note': 'data/docs/prd 下无 REQ 命名文档 (%d 个 .md 均为手写) → 工作流产出 0' % len(md_files),
+            'data': {'bypassed': len(md_files), 'req_docs': 0,
+                     'manual_docs': len(md_files)},
+        }
+    bypassed = [f for f in req_files if not any(f.name == e or e in f.name for e in evald_prds)]
+    rate = 100.0 * len(bypassed) / len(req_files)
+    return {
+        'id': 'U5', 'name': '绕过率',
+        'value': round(rate, 1), 'unit': '%', 'level': _level_low(rate, 15, 40),
+        'auto': 'semi',
+        'note': 'REQ文档未经eval直接提交 %d / REQ文档 %d' % (len(bypassed), len(req_files)),
+        'data': {'bypassed': len(bypassed), 'req_docs': len(req_files)},
+    }
+
+
+def m_u6_activity(days):
+    """U6 活跃度: 近N天去重dev数 + 命令分布。🟢自动"""
+    events = _collect_feedback()
+    recent = [e for e in events if _within(e.get('ts', ''), days)]
+    devs = set(e.get('dev') for e in recent if e.get('dev'))
+    # 命令分布: 从 task_completed/commit_done/prd_* 等事件名粗估
+    cmd_dist = {}
+    for e in recent:
+        ev = e.get('event', '')
+        if ev in ('prd_accepted', 'prd_rejected', 'task_completed', 'commit_done',
+                  'review_done', 'design_import'):
+            cmd_dist[ev] = cmd_dist.get(ev, 0) + 1
+    distinct_cmds = len(cmd_dist)
+    n_devs = len(devs)
+    # 绿: >=2人 且 覆盖>=4命令; 黄: 1人或<4; 红: 0人
+    if n_devs == 0:
+        level = 'red'
+    elif n_devs >= 2 and distinct_cmds >= 4:
+        level = 'green'
+    else:
+        level = 'yellow'
+    return {
+        'id': 'U6', 'name': '活跃度',
+        'value': n_devs, 'unit': '人/%d天' % days, 'level': level,
+        'auto': 'auto', 'note': '近%d天 %d 人活跃, 覆盖 %d 类命令事件' % (days, n_devs, distinct_cmds),
+        'data': {'devs': sorted(devs), 'cmd_distribution': cmd_dist},
+    }
+
+
+# ── 流程 (F 系列) ──────────────────────────────────────────────────────
+
+def m_f1_closure_rate(tasks):
+    """F1 端到端闭环率: PRD→Task→Commit 三跳齐全。🔴待埋点(软估算)"""
+    has_req_id = sum(1 for t in tasks if t.get('req_id'))
+    # 软估算: 有 stage_ts.completed 的 task 视为"走到了task"
+    completed_tasks = [t for t in tasks if (t.get('stage_ts') or {}).get('completed')]
+    learning = _collect_learning_yaml()
+    commits = learning.get('commits_done', 0)
+    # 软: 完成的task里"可能"对应了commit (无关联键, 只能上下界估)
+    return {
+        'id': 'F1', 'name': '端到端闭环率',
+        'value': None, 'unit': '%', 'level': '-',
+        'auto': 'instrumentation_needed',
+        'note': 'NEEDS_INSTRUMENTATION: task.json 无 req_id, commit_done 无 task 引用, 无法精确串联',
+        'data': {
+            'soft_estimate': '完成task %d 个, commit %d 次 (无关联键, 仅计数)' % (len(completed_tasks), commits),
+            'tasks_with_req_id': has_req_id,
+            'completed_tasks': len(completed_tasks),
+            'commits': commits,
+            'fix': 'task.json 加 req_id 字段 + commit_done 加 task 引用后自动升级为准',
+        },
+    }
+
+
+def m_f2_funnel(learning_counts):
+    """F2 转化漏斗: 各级事件留存。🔴待埋点(review/design没埋)"""
+    def _get(*keys):
+        for k in keys:
+            if k in learning_counts:
+                return learning_counts[k]
+        return 0
+    funnel = {
+        'PRD产出': _get('prds_generated'),
+        'PRD打回(负向)': _get('rejections'),
+        '设计录入': _get('designs_imported'),   # 注册了但从未埋点 → 恒0
+        'PRD评审': _get('reviews_done'),         # 注册了但从未埋点 → 恒0
+        '任务完成': _get('tasks_completed'),
+        '代码提交': _get('commits_done'),
+    }
+    needs_fix = (funnel['设计录入'] == 0 and funnel['PRD产出'] > 0)
+    return {
+        'id': 'F2', 'name': '转化漏斗',
+        'value': None, 'unit': '级', 'level': 'yellow' if needs_fix else '-',
+        'auto': 'instrumentation_needed' if needs_fix else 'auto',
+        'note': '设计录入/PRD评审 = 0 (events.py 注册但从未埋点)' if needs_fix else '各级留存计数',
+        'data': funnel,
+    }
+
+
+def m_f3_command_efficiency(days):
+    """F3 单命令效率: 迭代轮/工具调用 vs 基线。🟢自动(复用transcript_timing)"""
+    summary = None
+    try:
+        # 尝试复用 transcript_timing (QoderWork transcript)
+        sys.path.insert(0, str(REPO / '.qoder' / 'scripts' / 'validation' / 'eval'))
+        from transcript_timing import analyze as _analyze  # noqa
+        # 找 transcript 目录
+        sess_dir = Path.home() / '.qoderwork' / 'logs' / 'sessions'
+        if sess_dir.is_dir():
+            jsonls = list(sess_dir.rglob('*.jsonl'))[-20:]  # 最近20个
+            agg_turns, agg_tools, agg_cmds = [], [], {}
+            for jf in jsonls:
+                try:
+                    res = _analyze(str(jf))
+                    for t in res.get('turns', []):
+                        if _within(t.get('submitted_ts'), days):
+                            agg_turns.append(t.get('num_turns') or 1)
+                            agg_tools.append(t.get('tool_calls') or 0)
+                            cmd = t.get('command', '')
+                            if cmd:
+                                agg_cmds[cmd] = agg_cmds.get(cmd, 0) + 1
+                except Exception:
+                    continue
+            if agg_turns:
+                summary = {
+                    'avg_rounds': round(sum(agg_turns) / len(agg_turns), 2),
+                    'avg_tool_calls': round(sum(agg_tools) / len(agg_tools), 2),
+                    'cmd_count': len(agg_cmds),
+                    'baseline': 'prd-quick = 1轮/0工具',
+                    'top_commands': dict(sorted(agg_cmds.items(), key=lambda x: -x[1])[:5]),
+                }
+    except Exception:
+        summary = None
+    if not summary:
+        return {
+            'id': 'F3', 'name': '单命令效率',
+            'value': None, 'unit': '', 'level': '-',
+            'auto': 'auto',
+            'note': '无 QoderWork transcript 可读 (非 QoderWork 环境, 或无近期会话); 用 /wl-status 查看',
+            'data': {},
+        }
+    level = _level_low(summary['avg_rounds'], 2, 4)
+    return {
+        'id': 'F3', 'name': '单命令效率',
+        'value': summary['avg_rounds'], 'unit': '轮(平均)', 'level': level,
+        'auto': 'auto', 'note': '平均迭代 %s 轮 / 工具 %s 次 (基线 prd-quick=1轮/0工具)'
+              % (summary['avg_rounds'], summary['avg_tool_calls']),
+        'data': summary,
+    }
+
+
+def m_f4_breakpoints(tasks):
+    """F4 流程断点: rule_violation高频 + PRD孤岛。🟢自动"""
+    events = _collect_feedback()
+    violations = [e for e in events if e.get('event') == 'rule_violation']
+    by_rule = {}
+    for e in violations:
+        rule = (e.get('data') or {}).get('rule', 'unknown')
+        by_rule.setdefault(rule, []).append(e)
+    top_rules = {r: len(v) for r, v in sorted(by_rule.items(), key=lambda x: -len(x[1]))[:3]}
+    # PRD 孤岛: task 创建后无 started 的中位数天数
+    orphan_days = []
+    for t in tasks:
+        st = t.get('stage_ts') or {}
+        created = st.get('created')
+        if created and not st.get('started'):
+            try:
+                c = datetime.fromisoformat(created.split('.')[0])
+                age = (datetime.now() - c).days
+                orphan_days.append(age)
+            except (ValueError, TypeError):
+                continue
+    med_orphan = sorted(orphan_days)[len(orphan_days) // 2] if orphan_days else 0
+    level = _level_low(med_orphan, 3, 7) if orphan_days else 'green'
+    return {
+        'id': 'F4', 'name': '流程断点',
+        'value': med_orphan, 'unit': '天(PRD孤岛中位)', 'level': level,
+        'auto': 'auto', 'note': '规则违反 %d 次; PRD孤岛(task建后未启动) %d 个, 中位 %d 天'
+              % (len(violations), len(orphan_days), med_orphan),
+        'data': {'top_violated_rules': top_rules, 'orphan_task_count': len(orphan_days),
+                 'orphan_median_days': med_orphan},
+    }
+
+
+def _empty(mid, name, auto='auto'):
+    return {'id': mid, 'name': name, 'value': None, 'unit': '', 'level': '-',
+            'auto': auto, 'note': '暂无数据', 'data': {}}
+
+
+# ═══════════════════════════════════════════════════════════════════════
+# 主流程
+# ═══════════════════════════════════════════════════════════════════════
+
+def compute_all(days=7):
+    """计算全部指标, 返回 {meta, adoption[], flow[], score}。"""
+    eval_rows = _read_jsonl(EVAL_HISTORY)
+    learning_counts = _collect_learning_yaml()
+    tasks = _collect_tasks()
+
+    adoption = [
+        m_u1_adoption_rate(eval_rows),
+        m_u2_first_pass_rate(),
+        m_u3_rework_rounds(),
+        m_u4_rule_violation_rate(learning_counts),
+        m_u5_bypass_rate(eval_rows),
+        m_u6_activity(days),
+    ]
+    flow = [
+        m_f1_closure_rate(tasks),
+        m_f2_funnel(learning_counts),
+        m_f3_command_efficiency(days),
+        m_f4_breakpoints(tasks),
+    ]
+
+    # 综合采纳分: 只取有 value 的自动指标, 按达标率算 0-100
+    scored = []
+    for m in adoption:
+        if m.get('value') is not None and m.get('level') in ('green', 'yellow', 'red'):
+            scored.append(1.0 if m['level'] == 'green' else (0.5 if m['level'] == 'yellow' else 0.0))
+    adoption_score = round(100.0 * sum(scored) / len(scored), 1) if scored else None
+
+    return {
+        'meta': {
+            'generated_at': datetime.now().isoformat(timespec='seconds'),
+            'window_days': days,
+            'repo': os.path.basename(str(REPO)),
+            'eval_history_rows': len(eval_rows),
+            'feedback_events': len(_collect_feedback()),
+            'tasks': len(tasks),
+            'data_sources': {
+                'eval_history': str(EVAL_HISTORY.relative_to(REPO)) if EVAL_HISTORY.is_file() else '(缺失)',
+                'feedback': 'workspace/members/*/journal/feedback.jsonl',
+                'learning': 'workspace/members/*/journal/learning.yaml',
+            },
+        },
+        'adoption': adoption,
+        'flow': flow,
+        'adoption_score': adoption_score,
+        'adoption_score_note': ('采纳综合分 = 各自动指标达标率' if scored else
+                                '采纳分暂无法计算(无有效自动指标数据)'),
+    }
+
+
+_LEVEL_ICON = {'green': '🟢', 'yellow': '🟡', 'red': '🔴', '-': '⬜'}
+_AUTO_TAG = {'auto': '自动', 'semi': '半自动', 'instrumentation_needed': '待埋点'}
+
+
+def render_human(result):
+    """终端人读表格。"""
+    m = result['meta']
+    print('=' * 64)
+    print('QODER 工作流可用性评测')
+    print('=' * 64)
+    print('窗口: 近 %d 天 | 数据: eval-history %d 行, feedback %d 条, tasks %d 个'
+          % (m['window_days'], m['eval_history_rows'], m['feedback_events'], m['tasks']))
+
+    if result.get('adoption_score') is not None:
+        sc = result['adoption_score']
+        lvl = '🟢 健康' if sc >= 70 else ('🟡 需关注' if sc >= 40 else '🔴 未用起来')
+        print('\n>>> 采纳综合分: %.0f / 100  %s' % (sc, lvl))
+
+    print('\n── 维度一: 采纳 (主) ── 用不用得起来 ──')
+    _print_metrics(result['adoption'])
+
+    print('\n── 维度二: 流程 (辅) ── 链路顺不顺 ──')
+    _print_metrics(result['flow'])
+
+    print('\n' + '-' * 64)
+    print('指标定义: data/docs/constitution/workflow-usability-metrics.md')
+    print('详解参数: python usability_score.py --help')
+
+
+def _print_metrics(metrics):
+    for x in metrics:
+        icon = _LEVEL_ICON.get(x.get('level', '-'), '⬜')
+        tag = _AUTO_TAG.get(x.get('auto', 'auto'), '?')
+        val = x.get('value')
+        valstr = ('%s %s' % (val, x.get('unit', ''))) if val is not None else '—'
+        print('  %s %s [%s] %-12s %s' % (icon, x['id'], tag, x['name'], valstr))
+        if x.get('note'):
+            print('       %s' % x['note'])
+
+
+def render_html(result):
+    """生成自包含 HTML 看板 (绿黄红仪表盘 + 指标条形)。
+
+    吸收宿主 Skills 动态 UI 能力: CLI 用户落盘看, QoderWork 用户走 present.widget 嵌入对话。
+    零外部依赖 (内联 CSS + SVG, 不引 CDN), 照 prototype-generator 的自包含 HTML 范式。
+    用 .format() 避开 CSS 里 % 字符与 % 格式化的歧义。
+    """
+    m = result['meta']
+    score = result.get('adoption_score')
+    score_lvl = 'green' if (score or 0) >= 70 else ('yellow' if (score or 0) >= 40 else 'red')
+
+    def _bar(metric):
+        lvl = metric.get('level', '-')
+        colors = {'green': '#52c41a', 'yellow': '#faad14', 'red': '#ff4d4f', '-': '#d9d9d9'}
+        c = colors.get(lvl, '#d9d9d9')
+        val = metric.get('value')
+        valstr = ('{} {}'.format(val, metric.get('unit', ''))) if val is not None else '—'
+        auto = _AUTO_TAG.get(metric.get('auto', 'auto'), '?')
+        icon = _LEVEL_ICON.get(lvl, '⬜')
+        note = (metric.get('note') or '').replace('<', '&lt;').replace('>', '&gt;')
+        return (
+            '        <div class="metric" style="border-left:4px solid {c}">\n'
+            '          <div class="m-head"><span class="ico">{icon}</span> <b>{mid} {name}</b>\n'
+            '            <span class="tag">{val}</span><span class="auto">{auto}</span></div>\n'
+            '          <div class="m-val">{val}</div>\n'
+            '          <div class="m-note">{note}</div>\n'
+            '        </div>').format(
+            c=c, icon=icon, mid=metric.get('id', ''), name=metric.get('name', ''),
+            val=valstr, auto=auto, note=note)
+
+    adoption_bars = '\n'.join(_bar(x) for x in result.get('adoption', [])) or '<div class="metric">无数据</div>'
+    flow_bars = '\n'.join(_bar(x) for x in result.get('flow', [])) or '<div class="metric">无数据</div>'
+
+    # 采纳分仪表盘 (SVG 圆环)
+    pct = int(score) if score is not None else 0
+    ring_color = {'green': '#52c41a', 'yellow': '#faad14', 'red': '#ff4d4f'}.get(score_lvl, '#d9d9d9')
+    circumference = 2 * 3.14159 * 52
+    dash = circumference * pct / 100.0
+    verdict = {'green': '🟢 健康，用得起来', 'yellow': '🟡 需关注',
+               'red': '🔴 未用起来'}.get(score_lvl, '— 无数据')
+
+    template = '''<!DOCTYPE html>
+<html lang="zh-CN"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>QODER 工作流可用性看板</title>
+<style>
+  *{{box-sizing:border-box;margin:0;padding:0}}
+  body{{font-family:-apple-system,"PingFang SC","Microsoft YaHei",sans-serif;
+       background:#f5f7fa;color:#333;padding:20px;max-width:980px;margin:0 auto}}
+  h1{{font-size:20px;margin-bottom:4px}}
+  .meta{{color:#888;font-size:13px;margin-bottom:18px}}
+  .score-wrap{{display:flex;align-items:center;gap:20px;background:#fff;
+              border-radius:12px;padding:18px 24px;margin-bottom:20px;box-shadow:0 1px 3px rgba(0,0,0,.08)}}
+  .gauge{{width:130px;height:130px;flex-shrink:0}}
+  .score-txt b{{font-size:30px;color:{ring_color}}}
+  .score-txt .verdict{{display:block;font-size:14px;color:#666;margin-top:2px}}
+  h2{{font-size:15px;color:#666;margin:18px 0 10px;border-bottom:1px solid #eee;padding-bottom:6px}}
+  .metric{{background:#fff;border-radius:8px;padding:10px 14px;margin-bottom:8px;
+          box-shadow:0 1px 2px rgba(0,0,0,.04)}}
+  .m-head{{display:flex;align-items:center;gap:8px;font-size:14px;flex-wrap:wrap}}
+  .m-head b{{min-width:130px}}
+  .m-val{{font-size:18px;font-weight:600;margin:2px 0}}
+  .m-note{{font-size:12px;color:#888;line-height:1.5}}
+  .tag{{margin-left:auto;background:#f0f0f0;border-radius:4px;padding:1px 8px;font-size:12px}}
+  .auto{{background:#e6f7ff;color:#1890ff;border-radius:4px;padding:1px 6px;font-size:11px}}
+  .ico{{font-size:16px}}
+  .legend{{font-size:12px;color:#999;margin-top:14px}}
+</style></head><body>
+  <h1>QODER 工作流可用性看板</h1>
+  <div class="meta">窗口近 {days} 天 · eval-history {ev} 行 · feedback {fb} 条 · tasks {tk} 个 · 生成于 {ts}</div>
+  <div class="score-wrap">
+    <svg class="gauge" viewBox="0 0 120 120">
+      <circle cx="60" cy="60" r="52" fill="none" stroke="#f0f0f0" stroke-width="10"/>
+      <circle cx="60" cy="60" r="52" fill="none" stroke="{ring_color}" stroke-width="10"
+              stroke-dasharray="{dash} {rest}" stroke-linecap="round"
+              transform="rotate(-90 60 60)"/>
+      <text x="60" y="68" text-anchor="middle" font-size="28" font-weight="bold" fill="{ring_color}">{pct}</text>
+    </svg>
+    <div class="score-txt">
+      <b>{score} / 100</b>
+      <span class="verdict">{verdict} — 回答"工作流用不用得起来"</span>
+    </div>
+  </div>
+  <h2>维度一：采纳（主）— 用不用得起来</h2>
+{adoption}
+  <h2>维度二：流程（辅）— 链路顺不顺</h2>
+{flow}
+  <div class="legend">指标定义：data/docs/constitution/workflow-usability-metrics.md ·
+    🟢达标 🟡需关注 🔴不达标 ⬜无数据 · [自动/半自动/待埋点]标注数据可信度</div>
+</body></html>'''
+    return template.format(
+        ring_color=ring_color,
+        days=m['window_days'], ev=m['eval_history_rows'], fb=m['feedback_events'],
+        tk=m['tasks'], ts=m['generated_at'],
+        dash='%.1f' % dash, rest='%.1f' % (circumference - dash),
+        pct=pct, score=(score if score is not None else '—'), verdict=verdict,
+        adoption=adoption_bars, flow=flow_bars,
+    )
+
+
+
+def sink_to_patterns(result):
+    """把红灯/黄灯项沉淀到 data/learning/patterns/usability-patterns.md (进 git 团队共享)。
+
+    吸收宿主 Knowledge Engine 能力的落地出口: wiki/card 是宿主自动生成会被覆盖,
+    patterns 是唯一可写且团队共享的载体。每次评测把不达标项 append, 让指标驱动知识沉淀。
+    幂等: 同一天同一指标只记一条(带重复计数), 避免无限膨胀。失败绝不阻塞评测。
+    """
+    patterns_path = REPO / 'data' / 'learning' / 'patterns' / 'usability-patterns.md'
+    try:
+        today = datetime.now().strftime('%Y-%m-%d')
+        issues = []
+        for m in result.get('adoption', []) + result.get('flow', []):
+            lvl = m.get('level')
+            if lvl in ('red', 'yellow') and m.get('value') is not None:
+                valstr = '%s %s' % (m['value'], m.get('unit', ''))
+                issues.append('  - [%s] %s %s = %s — %s' % (
+                    today, m['id'], lvl.upper(), valstr,
+                    (m.get('note') or '')[:120]))
+
+        if not issues:
+            return  # 全绿/无数据, 不打扰
+
+        # 幂等: 同日已记则跳过(看文件里是否已有今天的记录块)
+        try:
+            content = patterns_path.read_text(encoding='utf-8')
+        except Exception:
+            content = ''
+        marker = '## %s 评测红灯' % today
+        if marker in content:
+            return  # 今天已沉淀过
+
+        lines = ['', marker, '(采纳综合分: %s)' % result.get('adoption_score', '—'), ''] + issues
+        with open(patterns_path, 'a', encoding='utf-8') as f:
+            f.write('\n'.join(lines) + '\n')
+    except Exception:
+        pass  # 沉淀失败绝不阻塞评测
+
+
+def main():
+    parser = argparse.ArgumentParser(description='QODER 工作流可用性评测')
+    parser.add_argument('--days', type=int, default=7, help='评测窗口天数 (默认 7)')
+    parser.add_argument('--json', action='store_true', help='JSON 输出 (供 wl-status)')
+    parser.add_argument('--html', action='store_true',
+                        help='输出自包含 HTML 看板 (CLI 落盘 / QoderWork 嵌入对话)')
+    parser.add_argument('--no-sink', action='store_true', help='不把红灯沉淀到 usability-patterns.md')
+    args = parser.parse_args()
+
+    result = compute_all(days=args.days)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif args.html:
+        html = render_html(result)
+        # QoderWork 优先嵌入对话流; 不可达则落盘 (双轨)
+        sinked = False
+        try:
+            scripts_dir = str(REPO / '.qoder' / 'scripts')
+            if scripts_dir not in sys.path:
+                sys.path.insert(0, scripts_dir)
+            from capability.registry import resolve
+            cap = resolve()
+            if cap.present.available:
+                sinked = cap.present.widget(html)
+        except Exception:
+            pass
+        if not sinked:
+            # 降级: 落盘到当前 dev 的 journal
+            out = REPO / 'workspace' / 'members' / (os.environ.get('QODER_DEV', '') or 'shared') / 'journal'
+            try:
+                # 读真实 dev
+                dev_file = REPO / '.qoder' / '.developer'
+                if dev_file.is_file():
+                    for line in dev_file.read_text(encoding='utf-8').splitlines():
+                        if 'name=' in line:
+                            out = REPO / 'workspace' / 'members' / line.split('name=', 1)[1].strip().split()[0] / 'journal'
+                            break
+                out.mkdir(parents=True, exist_ok=True)
+                fp = out / ('dashboard-%s.html' % datetime.now().strftime('%Y%m%d-%H%M%S'))
+                fp.write_text(html, encoding='utf-8')
+                print('[HTML 看板] 已落盘: %s' % fp)
+            except Exception as e:
+                print(html)  # 最终兜底: 直接 stdout
+    else:
+        render_human(result)
+    # 红灯沉淀到团队 patterns (人读模式默认开, --json/--html/--no-sink 关)
+    if not args.json and not args.html and not args.no_sink:
+        sink_to_patterns(result)
+
+
+NL_HDR = '\n'
+
+
+if __name__ == '__main__':
+    main()