@winspan/claude-forge 8.35.0 → 8.37.0

package/dist/intelligence/execution-doc-builder.js

@@ -22,6 +22,70 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { logger } from '../core/utils/logger.js';
+// ── 中文化映射（仅用于正文展示；frontmatter 仍使用英文 key 维持机器可读契约） ─────
+/** TaskType → 中文标签（展示格式：`中文（英文）`） */
+export const TASK_TYPE_CN = {
+    build_system: '搭建系统',
+    add_feature: '新增功能',
+    refactor: '重构代码',
+    migrate: '迁移代码',
+    fix_bug: '修复 Bug',
+    analyze_requirement: '需求分析',
+    design_architecture: '架构设计',
+    design_api: 'API 设计',
+    design_schema: 'Schema 设计',
+    write_code: '编写代码',
+    write_test: '编写测试',
+    review: '代码评审',
+    audit_security: '安全审计',
+    optimize_perf: '性能优化',
+    write_spec: '规范文档',
+    review_doc: '文档评审',
+    create_pr: '创建 PR',
+    explain: '代码解释',
+    setup_project: '项目初始化',
+    cleanup_code: '代码清理',
+    upgrade_dependency: '依赖升级',
+    improve_coverage: '提升覆盖率',
+    check_quality: '代码质量检查',
+    research: '技术调研',
+    investigate: '问题排查',
+    compare_solutions: '方案对比',
+    write_doc: '文档编写',
+    analyze_codebase: '代码库分析',
+    multi_domain: '跨领域任务',
+    other: '其他任务',
+};
+/** Complexity → 中文标签 */
+export const COMPLEXITY_CN = {
+    simple: '简单',
+    moderate: '中等',
+    complex: '复杂',
+};
+/** ActionVerb → 中文标签（V2 字段，留作未来字段使用） */
+export const ACTION_VERB_CN = {
+    investigate: '排查',
+    fix: '修复',
+    create: '创建',
+    modify: '修改',
+    delete: '删除',
+    verify: '验证',
+    explain: '解释',
+    setup: '配置',
+    migrate: '迁移',
+    research: '调研',
+};
+/** routed_to_type → 显示标签（仅做首字母大写 + 中文兜底） */
+const ROUTED_TO_TYPE_CN = {
+    agent: 'Agent',
+    skill: 'Skill',
+    none: '未路由',
+};
+/**
+ * 从 `by-route/<routeId>/(overview|agent-*|skill-*).md` 返回索引的相对路径。
+ * `executions/by-route/<routeId>/x.md` → `executions/index.md` = `../../index.md`。
+ */
+const BACK_TO_INDEX_LINK = '> [← 返回索引](../../index.md)';
 const DEFAULT_AI_TIMEOUT_MS = 15_000;
 const MAX_AI_SUMMARY_CHARS = 600;
 const MAX_TIMELINE_ROWS = 30;
@@ -159,6 +223,7 @@ export class ExecutionDocBuilder {
             events: postUseEvents,
         });
         const errorCount = toolEvents.filter(t => t.success === 0).length;
+        // Frontmatter 保持英文：机器读取契约（不要改成中文 key）
         const frontmatter = [
             '---',
             'type: agent_execution',
@@ -173,20 +238,24 @@ export class ExecutionDocBuilder {
             '---',
         ].join('\n');
         const promptPreview = this.truncate(route.prompt, 100);
+        const taskTypeDisplay = this.taskTypeLabel(taskType);
+        const complexityDisplay = this.complexityLabel(complexity);
         const body = [
             `# Agent 执行 · ${agentName}`,
             '',
+            BACK_TO_INDEX_LINK,
+            '',
             `> 路由追踪 · [Web 查看](http://localhost:3721/trace?id=${shortId})`,
             '',
             '## 一、概览',
             '',
             '| 项 | 值 |',
             '|---|---|',
-            `| User Prompt | ${this.mdEscape(promptPreview)} |`,
-            `| 路由决策 | ${taskType} + ${complexity} → ${agentName} |`,
-            `| 遵守判定 | ${verdict.label} |`,
-            `| 耗时 | ${this.formatDuration(durationMs)} |`,
-            `| 工具调用 | ${toolCountsLine || '(无)'} |`,
+            `| 用户问题 | ${this.mdEscape(promptPreview)} |`,
+            `| 路由决策 | ${taskTypeDisplay} + ${complexityDisplay} → ${agentName} |`,
+            `| 是否遵守 | ${verdict.label} |`,
+            `| 耗时 | ${this.formatDurationHuman(durationMs)} |`,
+            `| 工具调用 | ${toolCountsLine || '（无）'} |`,
             '',
             '## 二、时间线',
             '',
@@ -196,7 +265,7 @@ export class ExecutionDocBuilder {
             '',
             '## 三、输入参数',
             '',
-            '### Original Prompt',
+            '### 原始 Prompt',
             '',
             '```',
             route.prompt,
@@ -212,7 +281,7 @@ export class ExecutionDocBuilder {
             fileChanges.length > 0
                 ? fileChanges
                     .slice(0, MAX_FILE_CHANGES)
-                    .map(f => `- ${f.action} \`${f.path}\``)
+                    .map(f => `- ${this.fileActionLabel(f.action)} \`${f.path}\``)
                     .join('\n')
                 : '_无文件改动_',
             '',
@@ -230,8 +299,8 @@ export class ExecutionDocBuilder {
             '| 项 | 值 |',
             '|---|---|',
             `| 工具事件数 | ${toolEvents.length} |`,
-            `| 错误 | ${errorCount} |`,
-            `| Skill 调用 | ${skillInvocations.length} |`,
+            `| 错误次数 | ${errorCount} |`,
+            `| Skill 调用次数 | ${skillInvocations.length} |`,
             '',
         ].join('\n');
         return `${frontmatter}\n\n${body}`;
@@ -239,6 +308,7 @@ export class ExecutionDocBuilder {
     // ── Skill execution rendering ─────────────────────────────────────────
     renderSkillExecution(inv, route) {
         const invokedAt = new Date(inv.timestamp).toISOString();
+        // Frontmatter 保持英文：机器读取契约
         const frontmatter = [
             '---',
             'type: skill_execution',
@@ -255,6 +325,8 @@ export class ExecutionDocBuilder {
         const body = [
             `# Skill 调用 · ${inv.skill_id}`,
             '',
+            BACK_TO_INDEX_LINK,
+            '',
             '## 一、调用上下文',
             '',
             '| 项 | 值 |',
@@ -263,8 +335,8 @@ export class ExecutionDocBuilder {
             `| 调用类型 | ${this.skillInvocationTypeLabel(inv.invocation_type)} |`,
             `| 发起者 | ${inv.agent_id ? `\`${inv.agent_id}\`` : '主 Claude'} |`,
             `| 嵌套深度 | ${inv.depth} |`,
-            `| 调用时间 | ${invokedAt} |`,
-            `| 执行结果 | ${inv.success === 1 ? '成功' : '失败'} |`,
+            `| 调用时间 | ${this.formatDateTimeHuman(invokedAt)} |`,
+            `| 执行结果 | ${inv.success === 1 ? '✅ 成功' : '❌ 失败'} |`,
             inv.error ? `| 错误信息 | ${this.mdEscape(inv.error)} |` : '',
             '',
             '## 二、Skill 内容概要',
@@ -282,8 +354,8 @@ export class ExecutionDocBuilder {
             '',
             '| 项 | 值 |',
             '|---|---|',
-            `| Invocation ID | \`${inv.id}\` |`,
-            `| Session ID | \`${inv.session_id}\` |`,
+            `| 调用 ID | \`${inv.id}\` |`,
+            `| 会话 ID | \`${inv.session_id}\` |`,
             `| 时间戳 | ${inv.timestamp} |`,
             '',
         ]
@@ -303,6 +375,8 @@ export class ExecutionDocBuilder {
         const completedAt = route.completed_ts
             ? new Date(route.completed_ts).toISOString()
             : '';
+        // Frontmatter 保持英文：机器读取契约
+        // prompt 字段供 index 生成器读取（避免它再去解析 body 表格）
         const frontmatter = [
             '---',
             'type: route_overview',
@@ -312,9 +386,10 @@ export class ExecutionDocBuilder {
             `completed_at: ${completedAt}`,
             `routed_to: ${route.routed_to_name ?? 'none'}`,
             `verdict: ${verdict.key}`,
+            `prompt: ${this.frontmatterValue(route.prompt)}`,
             '---',
         ].join('\n');
-        // Build execution chain tree
+        // 执行链路树
         const treeLines = [];
         treeLines.push(`[Router] ${taskType} + ${complexity}`);
         if (route.routed_to_name) {
@@ -325,22 +400,27 @@ export class ExecutionDocBuilder {
                 treeLines.push(`${prefix} [Skill] ${inv.skill_id} (${status})`);
             });
         }
+        const taskTypeDisplay = this.taskTypeLabel(taskType);
+        const complexityDisplay = this.complexityLabel(complexity);
+        const routedToDisplay = this.routedToLabel(route.routed_to_type ?? null, route.routed_to_name ?? null);
         const body = [
             `# 路由概览 · ${shortId}`,
             '',
+            BACK_TO_INDEX_LINK,
+            '',
             `> [Web 查看](http://localhost:3721/trace?id=${shortId})`,
             '',
             '## 一、路由决策',
             '',
             '| 项 | 值 |',
             '|---|---|',
-            `| Prompt | ${this.mdEscape(this.truncate(route.prompt, 80))} |`,
-            `| 任务类型 | ${taskType} |`,
-            `| 复杂度 | ${complexity} |`,
-            `| 路由目标 | ${route.routed_to_type ?? 'none'} → ${route.routed_to_name ?? 'N/A'} |`,
-            `| 遵守判定 | ${verdict.label} |`,
-            `| 分类耗时 | ${route.classification_ms ?? '-'}ms |`,
-            `| 执行耗时 | ${this.formatDuration(route.total_execution_ms ?? null)} |`,
+            `| 用户问题 | ${this.mdEscape(this.truncate(route.prompt, 80))} |`,
+            `| 任务类型 | ${taskTypeDisplay} |`,
+            `| 复杂度 | ${complexityDisplay} |`,
+            `| 路由目标 | ${routedToDisplay} |`,
+            `| 是否遵守 | ${verdict.label} |`,
+            `| 分类耗时 | ${this.formatDurationHuman(route.classification_ms ?? null)} |`,
+            `| 执行耗时 | ${this.formatDurationHuman(route.total_execution_ms ?? null)} |`,
             '',
             '## 二、执行链路',
             '',
@@ -355,43 +435,288 @@ export class ExecutionDocBuilder {
                 : '_无 Agent 文档_',
             ...skillInvocations.map((inv, idx) => {
                 const seq = String(idx + 1).padStart(2, '0');
-                return `- [Skill: ${inv.skill_id}](./skill-${this.slug(inv.skill_id)}-${seq}.md)`;
+                return `- [Skill：${inv.skill_id}](./skill-${this.slug(inv.skill_id)}-${seq}.md)`;
             }),
             '',
             '## 四、相关文档',
             '',
-            '- [全局索引](../index.md)',
+            '- [全局索引](../../index.md)',
             '',
         ].join('\n');
         return `${frontmatter}\n\n${body}`;
     }
     // ── Index generation ──────────────────────────────────────────────────
+    /**
+     * 重写 index.md（人类友好视图）+ index-raw.md（原始技术视图）。
+     *
+     * 主索引为倒序：最新的执行排在最上面，列包含：
+     *   - 倒序编号（# 列：最新条目数字最大，等于总数）
+     *   - 时间（今天 HH:MM / 昨天 HH:MM / MM-DD HH:MM / YYYY-MM-DD HH:MM）
+     *   - 任务描述（来自 overview.md frontmatter.prompt 或 body 中的 Prompt 行，截 40 字符）
+     *   - 执行者（聚合 agent-*.md 文件名：单个/× N/最多列两个 +N）
+     *   - 状态（基于 verdict 字段映射的中文标签）
+     *   - 详情链接（相对路径）
+     *
+     * 容错策略：缺少 overview.md / frontmatter 解析失败 → 显示占位符，不中断生成。
+     */
     updateIndex(baseDir) {
         const byRouteDir = path.join(baseDir, 'by-route');
         if (!fs.existsSync(byRouteDir))
             return;
-        const routeDirs = fs
+        const dirNames = fs
             .readdirSync(byRouteDir, { withFileTypes: true })
             .filter(d => d.isDirectory())
-            .map(d => d.name)
-            .sort();
+            .map(d => d.name);
+        // 收集每条记录的元数据
+        const entries = dirNames.map(d => this.collectIndexEntry(byRouteDir, d));
+        // 按 started_at 降序（最新在前）
+        entries.sort((a, b) => b.startedAtMs - a.startedAtMs);
+        const now = Date.now();
+        const indexMd = this.renderIndexMd(entries, now);
+        fs.writeFileSync(path.join(baseDir, 'index.md'), indexMd, 'utf-8');
+        const rawIndexMd = this.renderRawIndexMd(entries, now);
+        fs.writeFileSync(path.join(baseDir, 'index-raw.md'), rawIndexMd, 'utf-8');
+    }
+    /** 从单个 routeId 目录收集索引所需的元数据 */
+    collectIndexEntry(byRouteDir, dirName) {
+        const dirPath = path.join(byRouteDir, dirName);
+        let files = [];
+        try {
+            files = fs.readdirSync(dirPath);
+        }
+        catch {
+            files = [];
+        }
+        // agent-<slug>.md → 提取 <slug> 作为执行者标识
+        const agents = files
+            .filter(f => f.startsWith('agent-') && f.endsWith('.md'))
+            .map(f => f.slice('agent-'.length, -'.md'.length));
+        let prompt = '';
+        let verdict = '';
+        let startedAtMs = this.fallbackStartedAtFromDirName(dirName);
+        let hasOverview = false;
+        const overviewPath = path.join(dirPath, 'overview.md');
+        if (fs.existsSync(overviewPath)) {
+            hasOverview = true;
+            try {
+                const content = fs.readFileSync(overviewPath, 'utf-8');
+                const fm = this.parseFrontmatter(content);
+                const startedAt = fm.started_at;
+                if (startedAt) {
+                    const parsed = Date.parse(startedAt);
+                    if (!Number.isNaN(parsed))
+                        startedAtMs = parsed;
+                }
+                verdict = fm.verdict ?? '';
+                // 优先用 frontmatter 中的 prompt（Agent B 可能后续加入）
+                if (fm.prompt) {
+                    prompt = fm.prompt;
+                }
+                else {
+                    prompt = this.extractPromptFromBody(content);
+                }
+            }
+            catch (err) {
+                logger.debug(`[ExecutionDoc] parse overview failed for ${dirName}: ${err}`);
+            }
+        }
+        return { dirName, startedAtMs, prompt, verdict, agents, files, hasOverview };
+    }
+    /** 兜底：当 overview.md 缺失时，从目录名 `<uuid>:<unix_ms>` 中解析时间 */
+    fallbackStartedAtFromDirName(dirName) {
+        const parts = dirName.split(':');
+        if (parts.length >= 2) {
+            const tail = parts[parts.length - 1];
+            const ts = parseInt(tail, 10);
+            if (!Number.isNaN(ts) && ts > 0)
+                return ts;
+        }
+        return 0;
+    }
+    /** 简化版 YAML frontmatter 解析（key: value 单行格式） */
+    parseFrontmatter(content) {
+        const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        if (!m)
+            return {};
+        const result = {};
+        for (const line of m[1].split(/\r?\n/)) {
+            const idx = line.indexOf(':');
+            if (idx === -1)
+                continue;
+            const key = line.slice(0, idx).trim();
+            const value = line.slice(idx + 1).trim();
+            if (key)
+                result[key] = value;
+        }
+        return result;
+    }
+    /** 当 frontmatter 没有 prompt 时，从 body 的 "| Prompt | ... |" 行兜底提取 */
+    extractPromptFromBody(content) {
+        const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+        const match = body.match(/^\|\s*Prompt\s*\|\s*([^|]*?)\s*\|/m);
+        return match ? match[1].trim() : '';
+    }
+    /** 渲染主索引（人类友好视图） */
+    renderIndexMd(entries, nowMs) {
         const lines = [
-            '# Execution Documents Index',
+            '# 执行记录',
             '',
-            `> 生成时间: ${new Date().toISOString()}`,
+            `> 生成时间: ${this.formatGenerationTime(nowMs)}  ·  共 ${entries.length} 次任务执行`,
             '',
-            `共 ${routeDirs.length} 个路由执行记录。`,
+        ];
+        if (entries.length === 0) {
+            lines.push('_暂无执行记录_', '');
+            return lines.join('\n');
+        }
+        lines.push('| # | 时间 | 任务描述 | 执行者 | 状态 | 详情 |', '|---|---|---|---|---|---|');
+        entries.forEach((e, idx) => {
+            const seq = entries.length - idx; // 倒序编号，最新对应总数
+            const time = this.formatIndexTime(e.startedAtMs, nowMs);
+            const desc = this.truncatePromptForIndex(e.prompt, 40);
+            const agents = this.formatAgentList(e.agents);
+            const status = this.mapVerdictToStatus(e.verdict, e.hasOverview);
+            const link = `[打开](by-route/${encodeURI(e.dirName)}/)`;
+            lines.push(`| ${seq} | ${time} | ${this.mdEscape(desc)} | ${this.mdEscape(agents)} | ${status} | ${link} |`);
+        });
+        lines.push('', '> 提示：原始技术视图（routeId + 文件列表）见 [index-raw.md](./index-raw.md)', '');
+        return lines.join('\n');
+    }
+    /** 渲染原始技术视图（保留 routeId + 文件列表，供系统/Agent 使用） */
+    renderRawIndexMd(entries, nowMs) {
+        const lines = [
+            '# Execution Documents Index (Raw)',
+            '',
+            `> 生成时间: ${new Date(nowMs).toISOString()}`,
+            '',
+            `共 ${entries.length} 个路由执行记录（按 started_at 降序）。`,
             '',
-            '| # | Route ID | 文件 |',
-            '|---|---|---|',
+            '| # | Route ID | 开始时间 | 文件 |',
+            '|---|---|---|---|',
         ];
-        routeDirs.forEach((dir, idx) => {
-            const files = fs.readdirSync(path.join(byRouteDir, dir));
-            const fileList = files.map(f => `\`${f}\``).join(', ');
-            lines.push(`| ${idx + 1} | \`${dir}\` | ${fileList} |`);
+        entries.forEach((e, idx) => {
+            const seq = entries.length - idx;
+            const fileList = e.files.map(f => `\`${f}\``).join(', ') || '(空)';
+            const startedAt = e.startedAtMs > 0 ? new Date(e.startedAtMs).toISOString() : '-';
+            lines.push(`| ${seq} | \`${e.dirName}\` | ${startedAt} | ${fileList} |`);
         });
         lines.push('');
-        fs.writeFileSync(path.join(baseDir, 'index.md'), lines.join('\n'), 'utf-8');
+        return lines.join('\n');
+    }
+    /** 索引头部生成时间：YYYY-MM-DD HH:MM */
+    formatGenerationTime(ms) {
+        const d = new Date(ms);
+        return (`${d.getFullYear()}-${this.pad2(d.getMonth() + 1)}-${this.pad2(d.getDate())} ` +
+            `${this.pad2(d.getHours())}:${this.pad2(d.getMinutes())}`);
+    }
+    /** 列表中的时间格式：今天/昨天/本年/跨年四档 */
+    formatIndexTime(startedAtMs, nowMs) {
+        if (startedAtMs <= 0)
+            return '—';
+        const d = new Date(startedAtMs);
+        const now = new Date(nowMs);
+        const sameYMD = (a, b) => a.getFullYear() === b.getFullYear() &&
+            a.getMonth() === b.getMonth() &&
+            a.getDate() === b.getDate();
+        if (sameYMD(d, now)) {
+            return `${this.pad2(d.getHours())}:${this.pad2(d.getMinutes())}`;
+        }
+        const yesterday = new Date(now.getTime());
+        yesterday.setDate(yesterday.getDate() - 1);
+        if (sameYMD(d, yesterday)) {
+            return `昨天 ${this.pad2(d.getHours())}:${this.pad2(d.getMinutes())}`;
+        }
+        if (d.getFullYear() === now.getFullYear()) {
+            return (`${this.pad2(d.getMonth() + 1)}-${this.pad2(d.getDate())} ` +
+                `${this.pad2(d.getHours())}:${this.pad2(d.getMinutes())}`);
+        }
+        return (`${d.getFullYear()}-${this.pad2(d.getMonth() + 1)}-${this.pad2(d.getDate())} ` +
+            `${this.pad2(d.getHours())}:${this.pad2(d.getMinutes())}`);
+    }
+    pad2(n) {
+        return n.toString().padStart(2, '0');
+    }
+    /**
+     * 任务描述清洗与截断。
+     * - 剥离系统消息标签（<task-notification>, <system-reminder>, <local-command-*>）
+     *   只保留标签内的实际任务内容；如果整段都是系统消息则降级到 "[系统通知]"
+     * - 移除常见 markdown 噪声（[Image #N] 等）
+     * - 多行/多空白归一为单空格
+     * - 超过 maxLen 字符（基于 JS 字符串 length，对中文 1:1）→ 尾加 "..."
+     * - 空字符串 → "—"
+     */
+    truncatePromptForIndex(text, maxLen) {
+        if (!text)
+            return '—';
+        let cleaned = text;
+        // 1. 识别系统消息：若整段以 <task-notification> 等系统标签开头，
+        //    标记为系统通知（这些不是真实用户输入，而是后台任务完成回调等）
+        const isSystemMessage = /^\s*<(task-notification|system-reminder|local-command-stdout|local-command-stderr)\b/i.test(cleaned);
+        if (isSystemMessage) {
+            // 尝试从 <summary> 或 <result> 标签提取人类可读摘要
+            const summaryMatch = cleaned.match(/<summary>([\s\S]*?)<\/summary>/i);
+            if (summaryMatch && summaryMatch[1].trim()) {
+                cleaned = `[系统] ${summaryMatch[1].trim()}`;
+            }
+            else {
+                return '[系统通知]';
+            }
+        }
+        // 2. 剥离 XML/HTML 风格标签内容（保留文本）
+        cleaned = cleaned.replace(/<[^>]+>/g, ' ');
+        // 3. 移除图片标记和空白归一
+        cleaned = cleaned
+            .replace(/\[Image\s*#?\d+\]/gi, '')
+            .replace(/\r?\n+/g, ' ')
+            .replace(/\s+/g, ' ')
+            .trim();
+        if (!cleaned)
+            return '—';
+        if (cleaned.length <= maxLen)
+            return cleaned;
+        return cleaned.slice(0, maxLen) + '...';
+    }
+    /**
+     * 执行者列表格式化：
+     *   - 0 个 → "—"
+     *   - 1 个 → "name"
+     *   - 多个同名（理论上文件名不会重复，但兼容） → "name × N"
+     *   - 2 个不同 → "a, b"
+     *   - 多于 2 个不同 → "a, b, +N"
+     */
+    formatAgentList(agents) {
+        if (agents.length === 0)
+            return '—';
+        const counts = new Map();
+        for (const a of agents) {
+            counts.set(a, (counts.get(a) ?? 0) + 1);
+        }
+        const entries = [...counts.entries()];
+        const render = ([name, c]) => c > 1 ? `${name} × ${c}` : name;
+        if (entries.length === 1)
+            return render(entries[0]);
+        if (entries.length <= 2)
+            return entries.map(render).join(', ');
+        const head = entries.slice(0, 2).map(render).join(', ');
+        const rest = entries.length - 2;
+        return `${head}, +${rest}`;
+    }
+    /** verdict → 状态展示标签 */
+    mapVerdictToStatus(verdict, hasOverview) {
+        if (!hasOverview)
+            return '❓ 未知';
+        switch (verdict) {
+            case 'obeyed':
+            case 'not_applicable':
+                return '✅ 已完成';
+            case 'disobeyed':
+                return '⚠️ 未遵守';
+            case 'timeout':
+                return '⏱️ 超时';
+            case 'pending':
+                return '🔄 进行中';
+            default:
+                return verdict ? `❓ ${verdict}` : '❓ 未知';
+        }
     }
     // ── AI summary ────────────────────────────────────────────────────────
     async tryGenerateSummary(ctx) {
@@ -482,7 +807,7 @@ export class ExecutionDocBuilder {
             return '_无子任务调用_';
         const header = '| # | Skill ID | 类型 | 结果 | 时间 |\n|---|---|---|---|---|';
         const rows = invocations.map((inv, idx) => {
-            const status = inv.success === 1 ? 'OK' : 'FAIL';
+            const status = inv.success === 1 ? '✅ 成功' : '❌ 失败';
             const time = this.formatTime(new Date(inv.timestamp).toISOString());
             const typeLabel = this.skillInvocationTypeLabel(inv.invocation_type);
             return `| ${idx + 1} | \`${inv.skill_id}\` | ${typeLabel} | ${status} | ${time} |`;
@@ -508,14 +833,14 @@ export class ExecutionDocBuilder {
     }
     verdictLabel(route) {
         if (!route.routed_to_name)
-            return { key: 'not_applicable', label: '不适用' };
+            return { key: 'not_applicable', label: '— 不适用' };
         if (route.obeyed === 1)
-            return { key: 'obeyed', label: '已遵守' };
+            return { key: 'obeyed', label: '✅ 已遵守' };
         if (route.obeyed === 0)
-            return { key: 'disobeyed', label: '未遵守' };
+            return { key: 'disobeyed', label: '❌ 未遵守' };
         if (route.completion_reason === 'timeout')
-            return { key: 'timeout', label: '超时' };
-        return { key: 'pending', label: '待判定' };
+            return { key: 'timeout', label: '⏱️ 超时' };
+        return { key: 'pending', label: '🔄 待判定' };
     }
     countTools(events) {
         const counts = new Map();
@@ -543,6 +868,98 @@ export class ExecutionDocBuilder {
             return `${(ms / 1000).toFixed(1)}s`;
         return `${(ms / 60_000).toFixed(1)}min`;
     }
+    /**
+     * 人性化耗时：
+     *   - null/<=0          → "—"
+     *   - < 1s              → "<1 秒"
+     *   - < 60s             → "X.X 秒"（一位小数，整秒去掉 .0）
+     *   - < 60min           → "X 分 Y 秒"（整分钟省略秒部分）
+     *   - >= 60min          → "X 小时 Y 分"
+     */
+    formatDurationHuman(ms) {
+        if (ms === null || ms <= 0)
+            return '—';
+        if (ms < 1000)
+            return '<1 秒';
+        if (ms < 60_000) {
+            const secs = ms / 1000;
+            const rounded = Math.round(secs * 10) / 10;
+            const display = Number.isInteger(rounded)
+                ? rounded.toFixed(0)
+                : rounded.toFixed(1);
+            return `${display} 秒`;
+        }
+        if (ms < 3_600_000) {
+            const totalSec = Math.round(ms / 1000);
+            const mins = Math.floor(totalSec / 60);
+            const secs = totalSec % 60;
+            return secs === 0 ? `${mins} 分钟` : `${mins} 分 ${secs} 秒`;
+        }
+        const totalMin = Math.round(ms / 60_000);
+        const hours = Math.floor(totalMin / 60);
+        const mins = totalMin % 60;
+        return mins === 0 ? `${hours} 小时` : `${hours} 小时 ${mins} 分`;
+    }
+    /** TaskType 显示：`中文（英文）`，未知值原样返回。 */
+    taskTypeLabel(taskType) {
+        const cn = TASK_TYPE_CN[taskType];
+        return cn ? `${cn}（${taskType}）` : taskType;
+    }
+    /** Complexity 显示：`中文（英文）`，未知值原样返回。 */
+    complexityLabel(complexity) {
+        const cn = COMPLEXITY_CN[complexity];
+        return cn ? `${cn}（${complexity}）` : complexity;
+    }
+    /** 路由目标：`Agent → name` / `Skill → name` / `未路由`。 */
+    routedToLabel(type, name) {
+        if (!name)
+            return ROUTED_TO_TYPE_CN.none;
+        if (type === 'agent' || type === 'skill') {
+            return `${ROUTED_TO_TYPE_CN[type]} → ${name}`;
+        }
+        return name;
+    }
+    /** 文件改动动作：英文 → 中文动词。 */
+    fileActionLabel(action) {
+        if (action === 'Edit')
+            return '修改';
+        if (action === 'Write')
+            return '写入';
+        return action;
+    }
+    /**
+     * 人性化日期时间：`YYYY-MM-DD HH:mm:ss`（本地时区）
+     * 失败时回退到原值。
+     */
+    formatDateTimeHuman(isoOrTs) {
+        try {
+            const d = new Date(isoOrTs);
+            if (Number.isNaN(d.getTime()))
+                return isoOrTs;
+            const pad = (n) => n.toString().padStart(2, '0');
+            return (`${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ` +
+                `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`);
+        }
+        catch {
+            return isoOrTs;
+        }
+    }
+    /**
+     * YAML frontmatter 单行字符串值（无引号，依赖 parseFrontmatter 的 indexOf(':') 切分）：
+     *  - 去除换行 / 多余空白（避免破坏行结构）
+     *  - 去除前导 `---`（避免与 frontmatter 终止符歧义）
+     *  - 不加引号 —— Agent A 的 parseFrontmatter 不做反引号处理
+     *
+     * 注意：若 prompt 很长，索引层会再做截断展示。
+     */
+    frontmatterValue(text) {
+        const sanitized = text
+            .replace(/\r?\n+/g, ' ')
+            .replace(/\s+/g, ' ')
+            .replace(/^-{3,}/, '')
+            .trim();
+        return sanitized;
+    }
     formatTime(isoOrTs) {
         try {
             const d = new Date(isoOrTs);