agent-tune-kit 2.3.0__tar.gz → 2.3.1__tar.gz

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Local Codex plugin for batch Agent evaluation and session trace tuning with evidence-backed issues, focused changes, verification and offline review.",
   "author": {
     "name": "hustyichi",

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.3.0
+Version: 2.3.1
 Summary: Local Codex plugin for iterative Agent tuning with guided Skills, reusable runner templates, versioned results, and static validation.
 Project-URL: Homepage, https://github.com/hustyichi/agent-tune-kit
 Project-URL: Repository, https://github.com/hustyichi/agent-tune-kit
@@ -53,10 +53,12 @@ atk install
 
 </details>
 
-Finish active ATK tasks before reinstalling, and open a new session afterward to load updates. If you have installation problems, run `atk status` and confirm the plugin is enabled in Codex. [Installation and cache notes](docs/skill-template-pack-usage.md#local-plugin-install-and-smoke)
+Finish active ATK tasks before reinstalling. `atk install` directly updates and verifies the Codex ATK cache, so no cache rebuild is needed afterward. Start a new session to replace instructions already read into a conversation; restart Codex if the skill list has not refreshed. If you have installation problems, run `atk status` and confirm the plugin is enabled in Codex. [Installation and cache notes](docs/skill-template-pack-usage.md#local-plugin-install-and-smoke)
 
 ## Evaluation-based tuning
 
+![Evaluation-based tuning architecture showing data preparation and Agent setup, batch evaluation, diagnosis, cross-round reporting, targeted tuning, and reruns.](docs/assets/agent_tune_kit_evaluation.png)
+
 Use a set of evaluation samples to find Agent failures and verify changes in later rounds. Prepare your Agent's entry point and a set of samples, preferably in CSV format. Five to twenty samples are enough to get started. Add expected answers, labels, or acceptance criteria where available.
 
 Open your Agent project in Codex and send the following `$atk-…` instructions in the conversation.
@@ -139,10 +141,10 @@ Each round saves results under `.atk/results/vN/` in your Agent project. Files a
 
 [More batch evaluation options and outputs](docs/skill-template-pack-usage.md#manual-22--26-loop)
 
-![Evaluation-based tuning workflow, from preparing data and connecting an Agent through evaluation, diagnosis, reporting, tuning, and rerunning the evaluation.](docs/assets/architecture.en.svg)
-
 ## Continuous tuning from session traces
 
+![Trace tuning architecture showing session capture, issue detection, root-cause diagnosis, targeted fixes, and verification.](docs/assets/agent_tune_kit_trace.png)
+
 Start with an existing session and use its execution trace to check whether the Agent completed the task. Save diagnoses, fixes, and verification results by issue. Get the native Session ID, its source, and access to the trace, then open the Agent project in Codex. You can start without an evaluation dataset or runner.
 
 Run `atk trace --help` to check whether your CLI supports trace tuning. If the command is unavailable, follow the local source installation steps above with a version that supports trace tuning, then open a new Codex session.
@@ -161,7 +163,9 @@ $atk-trace-detect Check whether session <session-id> completed its task correctl
 $atk-visualize-trace Open the execution lanes for session <session-id> and jump from issues to the relevant trace segments and evidence fields.
 ```
 
-Detection lists issues, evidence, and what it inspected. Use Trace IDs to locate evidence within the session. You can generate a preview once traces are archived. Review any retained content in the HTML before sharing it.
+Detection retains issues with serious impact, recurrence, direct relevance to your stated focus, or a concrete implementation improvement lead, and explains the retention reason, evidence and inspection scope. Implementation leads include code, configuration, tool contracts, Prompt and Skill; an unresolved cause can proceed to diagnosis. Minor observations with none of these reasons are not saved separately. No retained issues does not prove the session was correct.
+
+Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. You can generate a preview once traces are archived. Review any retained content in the HTML before sharing it.
 
 ### 3. Investigate, Fix, and Verify an Issue as Needed
 

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/README.en.md

@@ -39,10 +39,12 @@ atk install
 
 </details>
 
-Finish active ATK tasks before reinstalling, and open a new session afterward to load updates. If you have installation problems, run `atk status` and confirm the plugin is enabled in Codex. [Installation and cache notes](docs/skill-template-pack-usage.md#local-plugin-install-and-smoke)
+Finish active ATK tasks before reinstalling. `atk install` directly updates and verifies the Codex ATK cache, so no cache rebuild is needed afterward. Start a new session to replace instructions already read into a conversation; restart Codex if the skill list has not refreshed. If you have installation problems, run `atk status` and confirm the plugin is enabled in Codex. [Installation and cache notes](docs/skill-template-pack-usage.md#local-plugin-install-and-smoke)
 
 ## Evaluation-based tuning
 
+![Evaluation-based tuning architecture showing data preparation and Agent setup, batch evaluation, diagnosis, cross-round reporting, targeted tuning, and reruns.](docs/assets/agent_tune_kit_evaluation.png)
+
 Use a set of evaluation samples to find Agent failures and verify changes in later rounds. Prepare your Agent's entry point and a set of samples, preferably in CSV format. Five to twenty samples are enough to get started. Add expected answers, labels, or acceptance criteria where available.
 
 Open your Agent project in Codex and send the following `$atk-…` instructions in the conversation.
@@ -125,10 +127,10 @@ Each round saves results under `.atk/results/vN/` in your Agent project. Files a
 
 [More batch evaluation options and outputs](docs/skill-template-pack-usage.md#manual-22--26-loop)
 
-![Evaluation-based tuning workflow, from preparing data and connecting an Agent through evaluation, diagnosis, reporting, tuning, and rerunning the evaluation.](docs/assets/architecture.en.svg)
-
 ## Continuous tuning from session traces
 
+![Trace tuning architecture showing session capture, issue detection, root-cause diagnosis, targeted fixes, and verification.](docs/assets/agent_tune_kit_trace.png)
+
 Start with an existing session and use its execution trace to check whether the Agent completed the task. Save diagnoses, fixes, and verification results by issue. Get the native Session ID, its source, and access to the trace, then open the Agent project in Codex. You can start without an evaluation dataset or runner.
 
 Run `atk trace --help` to check whether your CLI supports trace tuning. If the command is unavailable, follow the local source installation steps above with a version that supports trace tuning, then open a new Codex session.
@@ -147,7 +149,9 @@ $atk-trace-detect Check whether session <session-id> completed its task correctl
 $atk-visualize-trace Open the execution lanes for session <session-id> and jump from issues to the relevant trace segments and evidence fields.
 ```
 
-Detection lists issues, evidence, and what it inspected. Use Trace IDs to locate evidence within the session. You can generate a preview once traces are archived. Review any retained content in the HTML before sharing it.
+Detection retains issues with serious impact, recurrence, direct relevance to your stated focus, or a concrete implementation improvement lead, and explains the retention reason, evidence and inspection scope. Implementation leads include code, configuration, tool contracts, Prompt and Skill; an unresolved cause can proceed to diagnosis. Minor observations with none of these reasons are not saved separately. No retained issues does not prove the session was correct.
+
+Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. You can generate a preview once traces are archived. Review any retained content in the HTML before sharing it.
 
 ### 3. Investigate, Fix, and Verify an Issue as Needed
 

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/README.md

@@ -39,10 +39,12 @@ atk install
 
 </details>
 
-重装前先结束正在运行的 ATK 任务，安装后新建会话以加载更新。遇到安装问题时，运行 `atk status` 检查安装，并在 Codex 中确认插件已启用。[安装与缓存说明](docs/skill-template-pack-usage.md#local-plugin-install-and-smoke)
+重装前先结束正在运行的 ATK 任务。`atk install` 会直接更新并校验 Codex 的 ATK 缓存，完成后无需等待缓存重建。已读入对话的旧指令仍需新建会话加载；技能列表未刷新时重启 Codex。遇到安装问题时，运行 `atk status` 检查安装，并在 Codex 中确认插件已启用。[安装与缓存说明](docs/skill-template-pack-usage.md#local-plugin-install-and-smoke)
 
 ## 评测调优
 
+![评测调优架构图，展示准备与接入、批量评测、判定与归因、报告与跨轮复核、定向优化及复测。](docs/assets/agent_tune_kit_evaluation.png)
+
 用一组评测样本找出 Agent 的问题，并用后续评测验证改动。准备 Agent 的入口和一组样本，推荐用 CSV，5 到 20 条即可开始。每条样本可附上期望答案、标签或可验收的行为标准。
 
 在 Codex 中打开 Agent 项目，在对话中发送下面的 `$atk-…` 指令。
@@ -125,10 +127,10 @@ $atk-report
 
 [更多批量评测运行选项和产物](docs/skill-template-pack-usage.md#manual-22--26-loop)
 
-![评测调优流程，从准备数据和接入 Agent 到评测、诊断、报告、调优和复测。](docs/assets/architecture.svg)
-
 ## 轨迹持续调优
 
+![轨迹调优架构图，展示会话采集、问题识别、根因诊断、定向修复和执行验证。](docs/assets/agent_tune_kit_trace.png)
+
 从一个已有会话出发，结合实际执行轨迹判断任务是否完成，再按问题保存诊断、修复和验证记录。准备原始 Session ID、来源和可读取的轨迹，直接在 Codex 中打开 Agent 项目开始。无需评测数据集或 runner。
 
 可用 `atk trace --help` 检查当前 CLI 是否支持轨迹调优。如果命令不可用，按上面的本地源码方式安装支持轨迹调优的版本，再新建 Codex 会话。
@@ -147,7 +149,9 @@ $atk-trace-detect 分析 <session-id> 的任务结果是否正确，列出问题
 $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关轨迹片段和证据字段。
 ```
 
-分析会列出问题、证据和检查范围。可用 Trace ID 定位会话内的证据。有归档轨迹即可生成预览，分享 HTML 前请核对其中留存的正文。
+分析保留影响严重、反复出现、与你明确关注点相关，或有具体实现改进线索的问题，并说明保留理由、证据和检查范围。实现线索包括代码、配置、工具契约、Prompt 和 Skill；根因尚未确定也可进入后续诊断。轻微且无上述保留理由的观察不单独记录，没有保留问题不代表会话完全正确。
+
+可用 Trace ID 定位会话内的证据，在问题详情中查看保留理由。有归档轨迹即可生成预览，分享 HTML 前请核对其中留存的正文。
 
 ### 3. 按问题调查、修复和验证（按需）
 

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/__init__.py

@@ -1,3 +1,3 @@
 """Agent Tune Kit package."""
 
-__version__ = "2.3.0"
+__version__ = "2.3.1"

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/installer.py

@@ -406,9 +406,8 @@ def cache_status(target: Path, cache: Path) -> tuple[bool, list[str]]:
     entries = sorted(cache.iterdir()) if cache.exists() else []
     entries = [entry for entry in entries if entry.name not in COPY_IGNORE_NAMES]
     if not entries:
-        return True, ["缓存尚未生成，等待 Codex 加载；尚未确认会话生效。"]
+        return False, ["ATK 缓存缺失；运行 atk install 修复。"]
     expected = payload_hashes(target)
-    version = current_manifest_version(target)
     ok = True
     lines: list[str] = []
     for entry in entries:
@@ -418,22 +417,57 @@ def cache_status(target: Path, cache: Path) -> tuple[bool, list[str]]:
         missing = sorted(expected.keys() - actual.keys())
         extra = sorted(actual.keys() - expected.keys())
         changed = sorted(key for key in expected.keys() & actual.keys() if expected[key] != actual[key])
-        version_ok = entry.name in (version, "local")
-        if not (missing or extra or changed) and version_ok:
+        if not (missing or extra or changed):
             lines.append(f"缓存与安装内容一致：{entry}")
             continue
         ok = False
         lines.append(f"缓存不一致：{entry}（修改 {len(changed)}，缺失 {len(missing)}，多余 {len(extra)}）")
-        if not version_ok:
-            lines.append(f"  缓存目录版本 {entry.name} 与安装版本 {version} 不同。")
         differences = [("修改", changed), ("缺失", missing), ("多余", extra)]
         details = [f"  {label}：{name}" for label, names in differences for name in names]
         lines.extend(details[:5])
     if not ok:
-        lines.append("运行 atk install 刷新缓存，然后重启 Codex 并新建会话。")
+        lines.append("运行 atk install 更新缓存；已读入的旧指令需新建会话，技能列表未刷新时重启 Codex。")
     return ok, lines
 
 
+def refresh_plugin_cache(target: Path, cache: Path, payload_source: PayloadSource) -> None:
+    entries = [entry for entry in cache.iterdir() if entry.name not in COPY_IGNORE_NAMES] if cache.exists() else []
+    for entry in entries:
+        if entry.is_symlink() or not entry.is_dir():
+            raise InstallError(f"unsafe plugin cache entry: {entry}")
+
+    cache.parent.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(prefix=f".{PLUGIN_NAME}-", dir=cache.parent))
+    staged, previous = work / "new", work / "previous"
+    try:
+        copy_payload_tree(payload_source, staged / "local")
+        # Keep paths already advertised to sessions readable with the new payload.
+        for entry in entries:
+            if entry.name != "local":
+                shutil.copytree(staged / "local", staged / entry.name)
+        valid, details = cache_status(target, staged)
+        if not valid:
+            raise InstallError("staged cache validation failed: " + "; ".join(details))
+
+        # shortcut: two renames leave a brief gap; use a platform directory exchange if live-read continuity is required.
+        if cache.exists():
+            os.replace(cache, previous)
+        try:
+            os.replace(staged, cache)
+        except BaseException:
+            if previous.exists():
+                try:
+                    os.replace(previous, cache)
+                except OSError as exc:
+                    raise InstallError(f"cache restore failed; previous cache preserved at {previous}: {exc}") from exc
+            raise
+        remove_path(previous)
+    finally:
+        # A failed restore must not delete the only surviving previous cache.
+        if not previous.exists():
+            remove_path(work)
+
+
 def collect_status(
     marketplace_path: Path, plugin_store: Path, payload_source: PayloadSource | None = None
 ) -> tuple[dict[str, bool], list[str]]:
@@ -561,7 +595,7 @@ def run_preview(args: argparse.Namespace) -> int:
         print("已有文件或注册与本次安装冲突；替换需要确认。")
     if args.smoke:
         smoke_check(marketplace_path, plugin_store, dry_run=True, payload_source=payload_source)
-    print(f"安装校验成功后将清理 ATK 缓存：{cache}")
+    print(f"安装校验成功后将更新 ATK 缓存：{cache}")
     print("未修改文件。运行 atk install 进行安装。")
     return 0
 
@@ -595,16 +629,16 @@ def run_install(args: argparse.Namespace) -> int:
         smoke_check(marketplace_path, plugin_store, dry_run=False, payload_source=payload_source)
 
     validate_manifest(target / ".codex-plugin" / "plugin.json")
-    # Invalidate only after a usable installation exists, including with --no-smoke.
+    # Publish only after a usable installation exists, including with --no-smoke.
     try:
         cache = plugin_cache_path(target, marketplace_path, payload_source)
-        remove_path(cache)
+        refresh_plugin_cache(target, cache, payload_source)
     except (InstallError, OSError) as exc:
         raise InstallError(f"plugin installed, but cache refresh failed: {cache}: {exc}") from exc
 
     print(f"已为 Codex 本地安装 Agent Tune Kit {payload_source.package_version}。")
-    print("ATK 缓存已清理或尚未生成；等待 Codex 重新加载。")
-    print("下一步：刷新 Codex /plugins，确认启用 Agent Tune Kit；重启 Codex 并新建会话。")
+    print("ATK 缓存已更新并校验，后续文件读取使用最新内容。")
+    print("下一步：确认 Codex /plugins 已启用 Agent Tune Kit；已读入的旧指令需新建会话，技能列表未刷新时重启 Codex。")
     return 0
 
 
@@ -691,7 +725,7 @@ def parse_args(argv: list[str]) -> argparse.Namespace:
     subparsers.add_parser(
         "preview", parents=[common], help="preview planned marketplace/plugin-store changes without writing"
     )
-    subparsers.add_parser("install", parents=[common], help="install, validate, then clear personal ATK caches")
+    subparsers.add_parser("install", parents=[common], help="install, validate, then replace personal ATK caches")
     subparsers.add_parser(
         "status", parents=[common], help="check local installation and compare cached plugin contents (read-only)"
     )

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/traces/query.py

@@ -10,12 +10,12 @@ from agent_tune_kit.errors import UserActionRequired
 from . import store
 
 
-def _milliseconds(value):
+def timestamp_ms(value):
+    """Parse epoch milliseconds, interpreting unzoned timestamps as machine-local time."""
     if isinstance(value, str):
         try:
             moment = datetime.fromisoformat(value)
-            if moment.utcoffset() is not None:
-                return round(moment.timestamp() * 1_000_000) / 1000
+            return round(moment.timestamp() * 1_000_000) / 1000
         except (ValueError, OSError, OverflowError):
             pass
     return None
@@ -180,17 +180,20 @@ def overview(session_dir, capture_id=None, offset=0, limit=100, trace_id=None):
     ordered = sorted(
         items,
         key=lambda item: (
-            _milliseconds(item.get("start_time")) is None,
-            _milliseconds(item.get("start_time")) if _milliseconds(item.get("start_time")) is not None else inf,
+            timestamp_ms(item.get("start_time")) is None,
+            timestamp_ms(item.get("start_time")) if timestamp_ms(item.get("start_time")) is not None else inf,
             str(item.get("trace_id") or ""),
             str(item.get("id") or ""),
         ),
     )
-    session_start = next((_milliseconds(item.get("start_time")) for item in ordered if _milliseconds(item.get("start_time")) is not None), None)
+    session_start = next(
+        (timestamp_ms(item.get("start_time")) for item in ordered if timestamp_ms(item.get("start_time")) is not None),
+        None,
+    )
 
     def row(item):
         summary = _summary(item)
-        at = _milliseconds(item.get("start_time"))
+        at = timestamp_ms(item.get("start_time"))
         summary["node_id"] = item.get("id")
         summary["parent_id"] = item.get("parent_id")
         summary["session_offset_ms"] = None if session_start is None or at is None else at - session_start

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/traces/records.py

@@ -138,6 +138,10 @@ def prepare_issue(session_dir, data, *, dry_run=False):
     data = copy.deepcopy(data)
     if not isinstance(data, dict):
         raise UserActionRequired("Issue data must be an object.")
+    if "selection_reason" in data and (
+        not isinstance(data["selection_reason"], str) or not data["selection_reason"].strip()
+    ):
+        raise UserActionRequired("Issue selection_reason must be a non-empty string when supplied.")
     issue_id = data.get("id", data.get("issue_id"))
     if issue_id is None:
         number = 1
@@ -215,6 +219,7 @@ def prepare_issue(session_dir, data, *, dry_run=False):
                     "updated_at",
                     "title",
                     "description",
+                    "selection_reason",
                     "evidence",
                     "segments",
                     "status",
@@ -331,6 +336,8 @@ def save_diagnosis(session_dir, issue_id, text, diagnosis_id=None):
         "segments": issue.get("segments", []),
         "created_at": now(),
     }
+    if "selection_reason" in issue:
+        snapshot["selection_reason"] = issue["selection_reason"]
     _refs(directory, issue["evidence"])
     for segment in snapshot["segments"]:
         _refs(directory, segment["evidence"])

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/traces/segments.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from datetime import datetime
 from math import inf
 
 from agent_tune_kit.errors import UserActionRequired
@@ -12,17 +11,6 @@ from . import query
 from .store import validate_ref
 
 
-def _milliseconds(value):
-    if isinstance(value, str):
-        try:
-            moment = datetime.fromisoformat(value)
-            if moment.utcoffset() is not None:
-                return round(moment.timestamp() * 1_000_000) / 1000
-        except (ValueError, OSError, OverflowError):
-            pass
-    return None
-
-
 def _node_pointer(pointer):
     if not isinstance(pointer, str) or not pointer:
         return "", ""
@@ -74,8 +62,8 @@ def _index_nodes(session_dir):
         if isinstance(identity, (str, int)):
             slot = (node.get("trace_id"), identity)
             by_identity[slot] = index if slot not in by_identity else None
-        at = _milliseconds(node.get("start_time"))
-        until = _milliseconds(node.get("end_time"))
+        at = query.timestamp_ms(node.get("start_time"))
+        until = query.timestamp_ms(node.get("end_time"))
         if until is None or at is None or until < at:
             until = at
         node["at"] = at
@@ -218,9 +206,7 @@ def resolve_segments(session_dir, segments, *, assign_ids=True):
                     raise UserActionRequired(f"Segment {offset} from is later than to.")
                 low, high = rank[start_i], rank[end_i]
                 covered = {
-                    i
-                    for i in order[low : high + 1]
-                    if nodes[i].get("trace_id") == nodes[start_i].get("trace_id")
+                    i for i in order[low : high + 1] if nodes[i].get("trace_id") == nodes[start_i].get("trace_id")
                 }
             else:
                 lo, hi = start_at, end_at

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/visualize/assets/trace/app.js

@@ -8,12 +8,16 @@
   const button = (text, action, className) => { const node = el("button", text, className); node.type = "button"; node.onclick = action; return node; };
   const pre = value => el("pre", pretty(value));
   const section = (title, value) => { const node = el("section", undefined, "detail-section"); node.append(el("h3", title)); if (value !== undefined) node.append(pre(value)); return node; };
+  const markdown = window.markdownit({html:false});
+  markdown.renderer.rules.image = (tokens, index) => markdown.utils.escapeHtml(tokens[index].content);
+  const sourceLinks = new Map(Object.entries(data.diagnosis_source_links).map(([href, target]) => [markdown.normalizeLink(href), target]));
   const options = (select, values, all) => { select.replaceChildren(); if (all !== undefined) { const item = el("option", all); item.value = ""; select.append(item); } for (const value of values) { const item = el("option", value); item.value = value; select.append(item); } };
   const references = value => { const result = []; const seen = new Set(); const walk = item => { if (Array.isArray(item)) item.forEach(walk); else if (item && typeof item === "object") { if (typeof item.path === "string" && typeof item.sha256 === "string") { const key = refKey(item); if (!seen.has(key)) { seen.add(key); result.push(item); } } else Object.values(item).forEach(walk); } }; walk(value); return result; };
   const RAIL_KEY = "atk-trace-rail-collapsed";
   let currentCapture = data.captures.at(-1) || null;
   let returnFocus = null, activeIssue = null, issueStage = "issue", drawerMode = null;
   let selectedNode = null, origin = null, issueTrigger = null;
+  let returnToDiagnosis = null;
   let investigation = null, scopeBefore = null, previewIssue = null, expandedFolds = new Set(), railFilter = null;
   const captureById = new Map(data.captures.map(c => [c.id, c]));
   const issueById = new Map(data.issues.map(item => [item.record.id, item]));
@@ -107,6 +111,7 @@
     $("drawer").hidden = true;
     drawerMode = null;
     activeIssue = null; origin = null;
+    returnToDiagnosis = null;
     if (restoreFocus && returnFocus?.isConnected) returnFocus.focus({preventScroll:true});
     else if (restoreFocus && investigation) $("fragment-fields").focus({preventScroll:true});
     else if (restoreFocus && issueTrigger) document.querySelector(`[data-issue-id="${CSS.escape(issueTrigger)}"]`)?.focus({preventScroll:true});
@@ -171,10 +176,8 @@
     const content = record.record || record.text;
     if (content !== undefined) {
       if (typeof content === "string") {
-        const body = el("div");
-        body.append(pre(content));
-        linkSegmentCites(body, content);
-        card.append(body);
+        card.firstElementChild.classList.add("diagnosis-path");
+        card.append(renderDiagnosis(content));
       } else {
         const summary = [];
         for (const key of ["status", "target_issues", "candidate_loaded"]) if (content[key] !== undefined) summary.push(`${key}: ${pretty(content[key])}`);
@@ -189,22 +192,114 @@
     appendReferences(card, record);
     return card;
   };
-  function linkSegmentCites(container, text) {
-    const matches = String(text || "").match(/ISSUE-\d+\/S\d+/g) || [];
-    if (!matches.length) return;
-    const box = el("p", undefined, "breadcrumb");
-    box.append(el("span", "片段引用：", "muted"));
-    for (const cite of [...new Set(matches)]) {
-      box.append(button(cite, () => {
-        const [issueId, seg] = cite.split("/");
-        const item = issueById.get(issueId);
-        if (!item) return;
-        startIssue(item, item.fragments.findIndex(part => part.id === seg));
-      }));
+  function appendDiagnoses(item) {
+    const container = $("drawer-content");
+    if (!item.diagnoses.length) {
+      container.append(el("p", "尚未记录诊断与修复／验证方案。", "empty"));
+      return;
+    }
+    for (const [index, diagnosis] of item.diagnoses.slice().reverse().entries()) {
+      const body = diagnosis.error ? el("p", diagnosis.error, "warning") : renderDiagnosis(diagnosis.text);
+      const headings = [...body.children].filter(node => node.tagName === "H2").map(node => node.textContent);
+      const structured = headings.join("|") === "异常描述|异常根因|最小修复方案"
+        || headings.join("|") === "Issue description|Root cause|Minimal fix";
+      if (index === 0 && structured) {
+        container.append(body);
+        continue;
+      }
+      if (index === 0) {
+        const description = section("异常描述");
+        description.append(el("p", item.record.description || item.record.title));
+        for (const [position, part] of item.fragments.entries()) {
+          const cite = button(part.id || `片段 ${position + 1}`, () => openDiagnosisSegment(item, position, cite), "diagnosis-cite");
+          description.append(cite);
+        }
+        container.append(description);
+      }
+      const details = el("details", undefined, "detail-section");
+      const name = diagnosis.reference.path.split("/").pop();
+      details.append(el("summary", `展开原诊断 · ${name}`), body);
+      container.append(details);
     }
-    container.prepend(box);
+  }
+  function renderDiagnosis(text) {
+    const body = el("div", undefined, "diagnosis-markdown");
+    const template = document.createElement("template");
+    template.innerHTML = markdown.render(text);
+    for (const link of template.content.querySelectorAll("a[href]")) {
+      const href = link.getAttribute("href");
+      const source = location.protocol === "file:" && sourceLinks.get(href);
+      if (source || /^https?:\/\//i.test(href)) {
+        if (source) link.setAttribute("href", source);
+        link.target = "_blank";
+        link.rel = "noopener noreferrer";
+      } else {
+        let path = href;
+        try { path = decodeURI(href); } catch { /* Keep malformed escape sequences as text. */ }
+        const locationText = el("code", path);
+        locationText.hidden = true;
+        const copy = button("复制路径", async () => {
+          try { await navigator.clipboard.writeText(path); copy.textContent = "已复制"; }
+          catch { locationText.hidden = false; }
+        });
+        link.replaceWith(...link.childNodes, " ", el("code", path.split("/").pop() || path), copy, locationText);
+      }
+    }
+    for (const table of template.content.querySelectorAll("table")) {
+      const scroll = el("div", undefined, "diagnosis-table");
+      scroll.tabIndex = 0;
+      scroll.setAttribute("aria-label", "诊断表格");
+      table.before(scroll);
+      scroll.append(table);
+    }
+    body.append(template.content);
+    const walker = document.createTreeWalker(body, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    while (walker.nextNode()) {
+      const node = walker.currentNode;
+      if (node.data.includes("ISSUE-") && !node.parentElement.closest("pre, a")) nodes.push(node);
+    }
+    for (const node of nodes) {
+      const parts = document.createDocumentFragment();
+      let offset = 0;
+      for (const match of node.data.matchAll(/\b(ISSUE-\d+)\/(S\d+)\b/g)) {
+        const item = issueById.get(match[1]);
+        const index = item?.fragments.findIndex(part => part.id === match[2]);
+        if (index === undefined || index < 0) continue;
+        const cite = button(match[0], () => openDiagnosisSegment(item, index, cite), "diagnosis-cite");
+        parts.append(node.data.slice(offset, match.index), cite);
+        offset = match.index + match[0].length;
+      }
+      if (offset) {
+        parts.append(node.data.slice(offset));
+        node.replaceWith(parts);
+      }
+    }
+    return body;
+  }
+  function openDiagnosisSegment(item, index, trigger) {
+    const drawerContent = $("drawer-content");
+    const sourceIssue = activeIssue, view = rememberView(), priorScope = scopeBefore;
+    const previous = investigation && {...investigation};
+    const top = drawerContent.scrollTop;
+    const citeIndex = [...drawerContent.querySelectorAll(".diagnosis-cite")].indexOf(trigger);
+    returnToDiagnosis = () => {
+      investigation = previous;
+      scopeBefore = priorScope;
+      restoreView(view);
+      showIssue(sourceIssue, "diagnoses");
+      const restored = drawerContent.querySelectorAll(".diagnosis-cite")[citeIndex];
+      const details = restored?.closest("details");
+      if (details) details.open = true;
+      drawerContent.scrollTop = top;
+      restored?.focus({preventScroll:true});
+    };
+    startIssue(item, index);
+    origin = null;
+    showFragmentEvidence();
   }
   const showIssue = (item, stage = "issue") => {
+    returnToDiagnosis = null;
     if (!activeIssue || activeIssue.record.id !== item.record.id) {
       origin = null;
       issueTrigger = item.record.id;
@@ -222,6 +317,11 @@
       const description = section("问题描述");
       description.append(el("p", issue.description || issue.title));
       $("drawer-content").append(description);
+      if (typeof issue.selection_reason === "string" && issue.selection_reason.trim()) {
+        const reason = section("保留理由");
+        reason.append(el("p", issue.selection_reason));
+        $("drawer-content").append(reason);
+      }
       const segments = issue.segments || [];
       if (segments.length) {
         const box = section("关联片段");
@@ -245,8 +345,7 @@
       return;
     }
     if (stage === "diagnoses") {
-      if (!item.diagnoses.length) $("drawer-content").append(el("p", "尚未记录诊断与修复／验证方案。", "empty"));
-      for (const diagnosis of item.diagnoses) $("drawer-content").append(recordCard(diagnosis.reference.path, diagnosis));
+      appendDiagnoses(item);
     } else if (stage === "changes") {
       if (!item.changes.length) $("drawer-content").append(el("p", "尚未记录实际修改。局部检查不代表 Agent 效果验证。", "empty"));
       for (const change of item.changes) $("drawer-content").append(recordCard(change.reference.path, change));
@@ -784,6 +883,7 @@
     const part = item.fragments[index];
     activeIssue = item; issueStage = "fragment"; issueTrigger = item.record.id;
     openDrawer(`${item.record.id} · ${part.id || `片段 ${index+1}`} 的证据`, "issue");
+    if (returnToDiagnosis) $("drawer-content").append(button("← 返回诊断", returnToDiagnosis));
     if (part.summary) $("drawer-content").append(el("p", part.summary, "muted"));
     function add(title, positions) {
       if (!positions?.length) return;
@@ -828,7 +928,7 @@
       box.append(note);
     }
     if (!filtered.length) {
-      box.append(el("p", data.issues.length ? "没有符合筛选条件的问题。" : data.session.detections.length ? "已保存检测记录，尚无已记录问题。" : "尚未进行异常识别。", "empty"));
+      box.append(el("p", data.issues.length ? "没有符合筛选条件的问题。" : data.session.detections.length ? "已保存检测记录，尚无保留问题；请查看检查范围与缺口。" : "尚未进行异常识别。", "empty"));
       return;
     }
     for (const item of filtered) {

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/visualize/assets/trace/page.html

@@ -78,6 +78,7 @@
   </aside>
   <script id="trace-data" type="application/json">__DATA__</script>
   <script>__LANES__</script>
+  <script>__MARKDOWN__</script>
   <script>__APP__</script>
 </body>
 </html>

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.1}/agent_tune_kit/visualize/assets/trace/styles.css

@@ -226,6 +226,19 @@ select:hover, .toolbar input:hover { border-color: #9baebb }
 .detail-section { background: white; padding: 12px; border: 1px solid var(--line); border-radius: 7px; margin-block: 10px }
 .detail-section h3 { margin-bottom: 6px }
 .detail-section button { font-size: 12px; margin: 2px }
+.detail-section .diagnosis-path { color: var(--muted); font-size: 12px; font-weight: 500 }
+.diagnosis-markdown { line-height: 1.65 }
+.diagnosis-markdown h1 { font-size: 19px; line-height: 1.4; margin: 12px 0 }
+.diagnosis-markdown h2 { font-size: 16px; margin: 20px 0 8px }
+.diagnosis-markdown p, .diagnosis-markdown ul, .diagnosis-markdown ol { margin: 8px 0 }
+.diagnosis-markdown ul, .diagnosis-markdown ol { padding-inline-start: 24px }
+.diagnosis-markdown li + li { margin-top: 6px }
+.diagnosis-markdown blockquote { margin: 10px 0; padding-inline-start: 12px; border-inline-start: 3px solid var(--line) }
+.diagnosis-table { overflow-x: auto; margin-block: 12px }
+.diagnosis-markdown table { border-collapse: collapse; width: 100%; font-size: 13px }
+.diagnosis-markdown th, .diagnosis-markdown td { border: 1px solid var(--line); padding: 6px 8px; vertical-align: top }
+.diagnosis-markdown th { background: var(--bg); text-align: start }
+.diagnosis-markdown .diagnosis-cite { padding: 1px 5px; color: var(--accent); font: inherit; font-size: .88em; white-space: nowrap }
 .evidence-link { display: block; width: 100%; text-align: left; white-space: normal; overflow-wrap: anywhere }
 .evidence-link strong, .evidence-link code { display: block }
 .evidence-link code, #evidence-field>code { font-size: 12px; color: var(--muted) }