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

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "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.1 → agent_tune_kit-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.3.1
+Version: 2.3.3
 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
@@ -165,21 +165,28 @@ $atk-visualize-trace Open the execution lanes for session <session-id> and jump
 
 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.
+The capture, detect, diagnose, optimize and verify Skills generate or update `.atk/traces/<session_id>/preview.html` at stage end without opening a browser. Use `$atk-visualize-trace` when you want to open it; refresh an already open page after the file changes. Initialization has no session trace and does not generate an empty page.
 
-### 3. Investigate, Fix, and Verify an Issue as Needed
+These stages also refresh the project dashboard `.atk/traces/index.html`, which shows issues and actual progress across all sessions by session or by issue category and links back to each session page. To open it, send `$atk-visualize-trace Open the trace dashboard`. Issues recorded before categories existed show as uncategorized until their session is analyzed again.
+
+Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. Review any retained content in the HTML before sharing it.
+
+### 3. Investigate a Session or Specific Issues, Then Fix and Verify as Needed
 
 ```text
+$atk-trace-diagnose Investigate session <session-id> and propose repair and verification plans.
 $atk-trace-diagnose Investigate ISSUE-001 in session <session-id> and propose a repair and verification plan.
 $atk-trace-optimize Implement the selected plan for ISSUE-001 in session <session-id>.
 $atk-trace-verify Verify the candidate for ISSUE-001 in session <session-id> and check relevant behavior that should still work.
 ```
 
-Start with diagnosis when you already have a specific issue and session evidence. Each verification records a conclusion per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the outcome is `inconclusive`. As new issues surface, work through them individually or start another analysis with a new session trace.
+Without specified issues, diagnosis reviews all available session traces and works through existing and newly found anomalies, prioritizing causes directly related to project code, configuration, tool contracts, Prompt or Skill. Findings established as unrelated to the existing implementation may be skipped with an explanation. Findings with uncertain relevance remain open for investigation. Specified issues or concrete symptoms limit the investigation scope. You can start directly with diagnosis without a separate detection invocation.
+
+Diagnoses and verification conclusions are saved per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the verification outcome is `inconclusive`. Investigation results identify unread ranges and evidence gaps. As new issues surface, work through them individually or start another analysis with a new session trace.
 
 ### Where to Find Trace Outputs
 
-Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps.
+Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps. The project dashboard `index.html` and the category list `categories.json` sit directly under `.atk/traces/`.
 
 | File or directory | What it shows |
 | --- | --- |
@@ -188,3 +195,7 @@ Each session archive is stored under `.atk/traces/<session_id>/` in your Agent p
 | `issues/<issue-id>/` | Issue evidence, diagnoses, and changes. Each verification's `result.json` records its status, conclusion, and evidence references |
 
 [Trace tuning guide for source configuration, supported formats, and archive layout](docs/trace-tuning.md)
+
+[Multi-project attribution and filtering proposal (not yet implemented, Chinese)](docs/trace-project-attribution-design.md)
+
+Use `atk trace project` to register workspace projects and submodules. Issues can have multiple root-cause projects, filterable in the dashboard and session issue list. Repair details describe modification locations.

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

@@ -151,21 +151,28 @@ $atk-visualize-trace Open the execution lanes for session <session-id> and jump
 
 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.
+The capture, detect, diagnose, optimize and verify Skills generate or update `.atk/traces/<session_id>/preview.html` at stage end without opening a browser. Use `$atk-visualize-trace` when you want to open it; refresh an already open page after the file changes. Initialization has no session trace and does not generate an empty page.
 
-### 3. Investigate, Fix, and Verify an Issue as Needed
+These stages also refresh the project dashboard `.atk/traces/index.html`, which shows issues and actual progress across all sessions by session or by issue category and links back to each session page. To open it, send `$atk-visualize-trace Open the trace dashboard`. Issues recorded before categories existed show as uncategorized until their session is analyzed again.
+
+Use Trace IDs to locate evidence within the session and open issue details to read the retention reason. Review any retained content in the HTML before sharing it.
+
+### 3. Investigate a Session or Specific Issues, Then Fix and Verify as Needed
 
 ```text
+$atk-trace-diagnose Investigate session <session-id> and propose repair and verification plans.
 $atk-trace-diagnose Investigate ISSUE-001 in session <session-id> and propose a repair and verification plan.
 $atk-trace-optimize Implement the selected plan for ISSUE-001 in session <session-id>.
 $atk-trace-verify Verify the candidate for ISSUE-001 in session <session-id> and check relevant behavior that should still work.
 ```
 
-Start with diagnosis when you already have a specific issue and session evidence. Each verification records a conclusion per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the outcome is `inconclusive`. As new issues surface, work through them individually or start another analysis with a new session trace.
+Without specified issues, diagnosis reviews all available session traces and works through existing and newly found anomalies, prioritizing causes directly related to project code, configuration, tool contracts, Prompt or Skill. Findings established as unrelated to the existing implementation may be skipped with an explanation. Findings with uncertain relevance remain open for investigation. Specified issues or concrete symptoms limit the investigation scope. You can start directly with diagnosis without a separate detection invocation.
+
+Diagnoses and verification conclusions are saved per issue. If the evidence cannot establish which candidate loaded or whether key verification conditions were met, the verification outcome is `inconclusive`. Investigation results identify unread ranges and evidence gaps. As new issues surface, work through them individually or start another analysis with a new session trace.
 
 ### Where to Find Trace Outputs
 
-Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps.
+Each session archive is stored under `.atk/traces/<session_id>/` in your Agent project. Files appear as you run the corresponding steps. The project dashboard `index.html` and the category list `categories.json` sit directly under `.atk/traces/`.
 
 | File or directory | What it shows |
 | --- | --- |
@@ -174,3 +181,7 @@ Each session archive is stored under `.atk/traces/<session_id>/` in your Agent p
 | `issues/<issue-id>/` | Issue evidence, diagnoses, and changes. Each verification's `result.json` records its status, conclusion, and evidence references |
 
 [Trace tuning guide for source configuration, supported formats, and archive layout](docs/trace-tuning.md)
+
+[Multi-project attribution and filtering proposal (not yet implemented, Chinese)](docs/trace-project-attribution-design.md)
+
+Use `atk trace project` to register workspace projects and submodules. Issues can have multiple root-cause projects, filterable in the dashboard and session issue list. Repair details describe modification locations.

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

@@ -151,21 +151,28 @@ $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关
 
 分析保留影响严重、反复出现、与你明确关注点相关，或有具体实现改进线索的问题，并说明保留理由、证据和检查范围。实现线索包括代码、配置、工具契约、Prompt 和 Skill；根因尚未确定也可进入后续诊断。轻微且无上述保留理由的观察不单独记录，没有保留问题不代表会话完全正确。
 
-可用 Trace ID 定位会话内的证据，在问题详情中查看保留理由。有归档轨迹即可生成预览，分享 HTML 前请核对其中留存的正文。
+采集、分析、诊断、修复和验证 Skill 在阶段结束后默认生成或更新 `.atk/traces/<session_id>/preview.html`，不自动打开浏览器。需要打开时使用 `$atk-visualize-trace`；已打开的页面在文件更新后需刷新。初始化没有会话轨迹，不生成空页面。
 
-### 3. 按问题调查、修复和验证（按需）
+这些阶段同时刷新项目大盘 `.atk/traces/index.html`，按会话或异常分类查看全部会话的问题和实际进度，并可跳回各会话页。需要打开时发送 `$atk-visualize-trace 打开轨迹大盘`。早于分类功能的问题显示为“未分类”，对应会话重新分析时补上。
+
+可用 Trace ID 定位会话内的证据，在问题详情中查看保留理由。分享 HTML 前请核对其中留存的正文。
+
+### 3. 调查会话或指定问题，按需修复和验证
 
 ```text
+$atk-trace-diagnose 调查 <session-id>，给出修复和验证方案。
 $atk-trace-diagnose 调查 <session-id> 的 ISSUE-001，给出修复和验证方案。
 $atk-trace-optimize 实施 <session-id> 的 ISSUE-001 已选定的方案。
 $atk-trace-verify 验证 <session-id> 的 ISSUE-001 对应候选，并检查相关正常行为。
 ```
 
-已有明确问题和会话证据时，可以从调查开始。每次验证按问题保存结论。证据不足以确认实际加载的候选或关键验证条件时，效果记为 `inconclusive`（无法判断）。后续发现新的问题，可继续按问题处理，或用新会话的轨迹开始下一次分析。
+未指定异常时，调查默认检查会话中可用的全部轨迹，逐项处理已记录和新发现的异常，优先定位与项目代码、配置、工具契约、Prompt 或 Skill 直接相关的原因。证据确认与现有实现无关的异常可以忽略，并说明理由。关联尚不明确的异常保留待查。指定异常或具体症状时，按指定范围调查。可以直接从调查开始，无需先单独执行检测。
+
+诊断和验证结论分别按问题保存。证据不足以确认实际加载的候选或关键验证条件时，验证效果记为 `inconclusive`（无法判断）。调查结果会说明未检查的范围和证据缺口。后续发现新的问题，可继续按问题处理，或用新会话的轨迹开始下一次分析。
 
 ### 查看轨迹产物
 
-会话归档保存在 Agent 项目的 `.atk/traces/<session_id>/` 下，文件随对应步骤生成。
+会话归档保存在 Agent 项目的 `.atk/traces/<session_id>/` 下，文件随对应步骤生成。项目大盘 `index.html` 和分类表 `categories.json` 位于 `.atk/traces/` 根目录。
 
 | 文件或目录 | 用途 |
 | --- | --- |
@@ -174,3 +181,7 @@ $atk-trace-verify 验证 <session-id> 的 ISSUE-001 对应候选，并检查相
 | `issues/<issue-id>/` | 查看问题证据、诊断和改动。各次验证的 `result.json` 记录验证状态、结论和证据引用 |
 
 [轨迹调优指南，包含来源配置、支持格式和归档结构](docs/trace-tuning.md)
+
+[多工程关联与项目筛选方案（待实现）](docs/trace-project-attribution-design.md)
+
+支持通过 `atk trace project` 登记工作区及子模块；诊断可记录多个根因项目，大盘与会话问题栏按根因项目筛选。修改位置在修复详情中说明。

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

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

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.3}/agent_tune_kit/cli/trace.py

@@ -3,7 +3,7 @@
 import json
 from pathlib import Path
 
-from agent_tune_kit.traces import records, store
+from agent_tune_kit.traces import categories, records, store
 from agent_tune_kit.traces.capture import fetch_session, import_session
 from agent_tune_kit.traces.query import overview, search, show
 
@@ -34,6 +34,19 @@ def register(subparsers):
     init.add_argument("--config", help="non-secret configuration JSON file")
     init.add_argument("--project-file", help="project context Markdown file")
     init.add_argument("--json", action="store_true")
+    project = actions.add_parser("project", help="discover, list or update workspace projects")
+    project.add_argument("--project-root", default=".")
+    mode = project.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--discover", action="store_true")
+    mode.add_argument("--list", action="store_true")
+    mode.add_argument("--data")
+    project.add_argument("--json", action="store_true")
+    category = actions.add_parser("category", help="list or update the project issue category vocabulary")
+    category.add_argument("--project-root", default=".")
+    mode = category.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--list", action="store_true", help="list categories with per-session issue counts")
+    mode.add_argument("--data", help="category JSON; revising the vocabulary requires its current revision")
+    category.add_argument("--json", action="store_true")
     for action in [
         "migrate",
         "fetch",
@@ -94,12 +107,25 @@ def register(subparsers):
             parser.add_argument("--issue-id", required=True)
             parser.add_argument("--file", required=True, help="root cause and repair/verification plan Markdown")
             parser.add_argument("--diagnosis-id")
+            parser.add_argument("--expected-revision", type=int)
 
 
 def execute(args):
+    if args.action == "project":
+        from agent_tune_kit.traces.projects import discover_projects, load_projects, save_project
+
+        if args.discover:
+            return discover_projects(args.project_root)
+        if args.list:
+            return load_projects(store.trace_root(args.project_root))
+        return save_project(args.project_root, read_json(args.data))
     if args.action == "init":
         text = Path(args.project_file).read_text(encoding="utf-8") if args.project_file else None
         return store.init_workspace(args.project_root, config=read_json(args.config), project_text=text)
+    if args.action == "category":
+        if args.list:
+            return categories.list_categories(args.project_root)
+        return categories.save_category(args.project_root, read_json(args.data))
     source = read_json(args.source)
     if args.action == "migrate":
         from agent_tune_kit.traces.migrate import migrate
@@ -152,6 +178,7 @@ def execute(args):
             args.issue_id,
             Path(args.file).read_text(encoding="utf-8"),
             diagnosis_id=args.diagnosis_id,
+            expected_revision=args.expected_revision,
         )
     data = read_json(args.data)
     if args.action == "issue":

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.3}/agent_tune_kit/cli/visualize.py

@@ -4,6 +4,7 @@ import sys
 from agent_tune_kit.errors import UserActionRequired
 from agent_tune_kit.visualize import generate_dataset, generate_failures
 from agent_tune_kit.visualize.trace import generate_trace
+from agent_tune_kit.visualize.traces import generate_traces
 
 from .output import emit
 from .trace import add_session_options, read_json
@@ -17,6 +18,8 @@ def add_options(parser, kind):
         parser.add_argument("--json", action="store_true")
     if kind == "dataset":
         parser.add_argument("--dataset-path", default=".atk/datasets/dataset.csv")
+    elif kind == "traces":
+        parser.add_argument("--project-root", default=".")
     elif kind == "trace":
         add_session_options(parser)
         parser.add_argument("--output-path")
@@ -31,14 +34,17 @@ def register(subparsers):
     commands = subparsers.add_parser("visualize", help="generate offline review pages").add_subparsers(
         dest="action", required=True
     )
-    for kind in ["dataset", "failures", "trace"]:
-        add_options(commands.add_parser(kind), kind)
+    helps = {"traces": "generate the project dashboard of every archived trace session"}
+    for kind in ["dataset", "failures", "trace", "traces"]:
+        add_options(commands.add_parser(kind, help=helps.get(kind)), kind)
 
 
 def execute(args):
     options = dict(overwrite=args.overwrite, open_browser=args.open_browser)
     if args.action == "dataset":
         return generate_dataset(args.dataset_path, **options)
+    if args.action == "traces":
+        return generate_traces(args.project_root, **options)
     if args.action == "trace":
         return generate_trace(
             args.project_root,

{agent_tune_kit-2.3.1 → agent_tune_kit-2.3.3}/agent_tune_kit/traces/archive.py

@@ -18,7 +18,9 @@ def component(value):
     if not isinstance(value, str) or not value.strip():
         raise UserActionRequired("An explicit nonempty native ID is required.")
     name = quote(value, safe="")
-    if name.startswith(".") or name.casefold() in {"project.md", "config.json", "_export_summary"}:
+    # Names of the files that live beside session directories at the archive root.
+    reserved = {"project.md", "config.json", "categories.json", "projects.json", "index.html", "_export_summary"}
+    if name.startswith(".") or name.casefold() in reserved:
         name = "%" + format(ord(name[0]), "02X") + name[1:]
     if len(name) > 200:
         name = name[:150] + "~" + hashlib.sha256(value.encode()).hexdigest()

agent_tune_kit-2.3.3/agent_tune_kit/traces/categories.py

@@ -0,0 +1,173 @@
+"""Project-level issue category vocabulary.
+
+The host decides which category fits an issue; this module only keeps the vocabulary consistent. Entries are never
+deleted, so issues that reference a category stay displayable after it is deprecated.
+"""
+
+import re
+from pathlib import Path
+
+from agent_tune_kit.errors import UserActionRequired
+from agent_tune_kit.results.evidence import now, safe_path, write_manifest
+
+from .store import ensure_workspace, read_json, session_write_lock, trace_root
+
+FILENAME = "categories.json"
+CATEGORY_ID = re.compile(r"[a-z0-9]+(?:-[a-z0-9]+)*")
+MAX_ID = 64
+
+
+def _path(root):
+    return safe_path(Path(root), FILENAME)
+
+
+def _check_catalog(value):
+    if (
+        value.get("schema_version") != 1
+        or not isinstance(value.get("revision"), int)
+        or isinstance(value.get("revision"), bool)
+        or not isinstance(value.get("categories"), list)
+    ):
+        raise UserActionRequired("Invalid Trace category vocabulary.")
+    seen = set()
+    for item in value["categories"]:
+        if (
+            not isinstance(item, dict)
+            or not isinstance(item.get("id"), str)
+            or not CATEGORY_ID.fullmatch(item["id"])
+            or item["id"] in seen
+            or any(not isinstance(item.get(key), str) or not item[key].strip() for key in ("name", "definition"))
+            or not isinstance(item.get("deprecated"), bool)
+        ):
+            raise UserActionRequired("Invalid Trace category entry.")
+        seen.add(item["id"])
+    return value
+
+
+def load_catalog(root):
+    """Read the vocabulary from a traces root; a missing file is an empty vocabulary."""
+    path = _path(root)
+    if not path.exists():
+        return {"schema_version": 1, "revision": 0, "categories": []}
+    return _check_catalog(read_json(path))
+
+
+def category_map(root):
+    """Return ``{id: entry}`` for display, tolerating a damaged file so one bad record cannot hide sessions."""
+    try:
+        return {item["id"]: item for item in load_catalog(root)["categories"]}
+    except UserActionRequired:
+        return {}
+
+
+def check_issue_category(root, category, previous=None):
+    """Validate an issue category against the vocabulary; an unchanged deprecated value stays valid."""
+    if not isinstance(category, str) or not category:
+        raise UserActionRequired("Issue category must be a category ID from the project vocabulary.")
+    entry = next((item for item in load_catalog(root)["categories"] if item["id"] == category), None)
+    if entry is None:
+        raise UserActionRequired(
+            f"Unknown issue category {category!r}; list the vocabulary with `atk trace category --list` first."
+        )
+    if entry["deprecated"] and category != previous:
+        raise UserActionRequired(f"Issue category {category!r} is deprecated; choose a current category.")
+    return category
+
+
+def save_category(project_root, data):
+    """Add or revise one category. Supplying ``revision`` is required once the vocabulary exists."""
+    if not isinstance(data, dict):
+        raise UserActionRequired("Category data must be an object.")
+    unknown = set(data) - {"id", "name", "definition", "deprecated", "revision", "expected_revision"}
+    if unknown:
+        raise UserActionRequired(f"Unsupported category fields: {', '.join(sorted(unknown))}.")
+    category_id = data.get("id")
+    if not isinstance(category_id, str) or not CATEGORY_ID.fullmatch(category_id) or len(category_id) > MAX_ID:
+        raise UserActionRequired("Category id must be lowercase kebab-case (letters, digits and single hyphens).")
+    expected = data.get("revision", data.get("expected_revision"))
+    if expected is not None and (not isinstance(expected, int) or isinstance(expected, bool)):
+        raise UserActionRequired("Category revision must be an integer.")
+    # The vocabulary lives in the private archive, so it gets the same Git ignore rule as captured sessions.
+    root, _ = ensure_workspace(project_root)
+    with session_write_lock(root):
+        catalog = load_catalog(root)
+        if expected is None and catalog["revision"] == 0:
+            expected = 0
+        if expected != catalog["revision"]:
+            raise UserActionRequired(
+                f"Stale or missing category revision; current vocabulary revision is {catalog['revision']}."
+            )
+        entries = catalog["categories"]
+        existing = next((item for item in entries if item["id"] == category_id), None)
+        stamp = now()
+        if existing is None:
+            for key in ("name", "definition"):
+                if not isinstance(data.get(key), str) or not data[key].strip():
+                    raise UserActionRequired(f"A new category needs a nonempty {key}.")
+            if data.get("deprecated") not in (None, False):
+                raise UserActionRequired("A new category cannot start deprecated.")
+            entry = {
+                "id": category_id,
+                "name": data["name"].strip(),
+                "definition": data["definition"].strip(),
+                "deprecated": False,
+                "created_at": stamp,
+                "updated_at": stamp,
+            }
+            entries.append(entry)
+        else:
+            entry = existing
+            for key in ("name", "definition"):
+                if key in data:
+                    if not isinstance(data[key], str) or not data[key].strip():
+                        raise UserActionRequired(f"Category {key} must be a nonempty string.")
+                    entry[key] = data[key].strip()
+            if "deprecated" in data:
+                if not isinstance(data["deprecated"], bool):
+                    raise UserActionRequired("Category deprecated must be true or false.")
+                entry["deprecated"] = data["deprecated"]
+            entry["updated_at"] = stamp
+        catalog["revision"] += 1
+        write_manifest(_path(root), catalog)
+    return {**entry, "vocabulary_revision": catalog["revision"], "created": existing is None}
+
+
+def list_categories(project_root):
+    """Return the vocabulary with how many issues in each session reference every category."""
+    from . import records
+
+    root = trace_root(project_root)
+    catalog = load_catalog(root)
+    usage = {item["id"]: {} for item in catalog["categories"]}
+    uncategorized = 0
+    warnings = []
+    sessions = sorted(child for child in root.iterdir() if child.is_dir()) if root.exists() else []
+    for session_dir in sessions:
+        if not (session_dir / "session.json").is_file() or session_dir.is_symlink():
+            continue
+        issue_root = session_dir / "issues"
+        for issue_file in sorted(issue_root.glob("*/issue.json")) if issue_root.is_dir() else []:
+            try:
+                issue = records.load_issue(session_dir, issue_file.parent.name)
+            except UserActionRequired as exc:
+                warnings.append({"session": session_dir.name, "issue_id": issue_file.parent.name, "error": str(exc)})
+                continue
+            category = issue.get("category")
+            if category is None:
+                uncategorized += 1
+            elif category in usage:
+                usage[category][session_dir.name] = usage[category].get(session_dir.name, 0) + 1
+    return {
+        "revision": catalog["revision"],
+        "categories": [
+            {
+                **item,
+                "sessions": len(usage[item["id"]]),
+                "issues": sum(usage[item["id"]].values()),
+                "by_session": usage[item["id"]],
+            }
+            for item in catalog["categories"]
+        ],
+        "uncategorized_issues": uncategorized,
+        "warnings": warnings,
+    }

agent_tune_kit-2.3.3/agent_tune_kit/traces/progress.py

@@ -0,0 +1,95 @@
+"""Actual issue progress derived from saved records.
+
+The declared issue ``status`` is not a progress signal; only ``excluded`` is honored so that withdrawn issues do not
+stay in the backlog. Everything else comes from diagnoses, changes and verification records. The functions here do no
+I/O so the session preview and the project dashboard report the same result.
+"""
+
+from datetime import datetime
+
+# Workflow order: unfinished work first, closed outcomes last. Keys double as CSS class names.
+PROGRESS = (
+    ("pending", "待诊断"),
+    ("diagnosed", "已诊断"),
+    ("changing", "修复中"),
+    ("awaiting", "待验证"),
+    ("verifying", "验证中"),
+    ("fail", "验证失败"),
+    ("inconclusive", "无法判断"),
+    ("pass", "验证通过"),
+    ("excluded", "已排除"),
+)
+LABELS = dict(PROGRESS)
+ORDER = {key: index for index, (key, _) in enumerate(PROGRESS)}
+
+
+def parse_instant(value):
+    """Return epoch seconds for an ISO timestamp, or None when it is missing, malformed or has no timezone."""
+    try:
+        stamp = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        if stamp.tzinfo is not None:
+            return stamp.timestamp()
+    except (TypeError, ValueError, AttributeError, OverflowError, OSError):
+        pass
+    return None
+
+
+def instant(record):
+    """Return the creation instant in seconds, or infinity when it is missing or has no timezone."""
+    when = parse_instant(record.get("created_at")) if isinstance(record, dict) else None
+    return float("inf") if when is None else when
+
+
+def _recency(record):
+    """Sort key where the newest known instant is largest; records with unknown time never count as newest."""
+    when = instant(record)
+    known = when != float("inf")
+    return known, when if known else 0.0, str(record.get("id", ""))
+
+
+def _result(key):
+    return {"key": key, "label": LABELS[key]}
+
+
+# Verification states whose per-issue conclusions count as an effect outcome. Failed, blocked and interrupted attempts
+# stay visible on the session page but never replace an earlier finished outcome.
+FINISHED = {"completed", "partial"}
+
+
+def issue_progress(issue, changes):
+    """Return ``{key, label}`` for one issue.
+
+    ``changes`` pairs every change linked to the issue (including a shared change owned by another issue) with all
+    verification records of that change; an entry that could not be read is passed as ``None``. The newest completed
+    or running change decides the stage, because an older verified attempt says nothing about a newer one. Within that
+    change the newest finished verification gives the outcome. An unreadable verification might be the newest one, so
+    the outcome is then unknown rather than an older result.
+    """
+    if issue.get("status") == "excluded":
+        return _result("excluded")
+    active = [(change, items) for change, items in changes if change.get("status") in {"completed", "running"}]
+    if active:
+        change, verifications = max(active, key=lambda pair: _recency(pair[0]))
+        if change["status"] == "running":
+            return _result("changing")
+        if any(not isinstance(item, dict) for item in verifications):
+            return _result("inconclusive")
+        finished = [item for item in verifications if item.get("status") in FINISHED]
+        if finished:
+            latest = max(finished, key=_recency)
+            conclusions = latest.get("conclusions")
+            conclusion = conclusions.get(issue.get("id")) if isinstance(conclusions, dict) else None
+            outcome = conclusion.get("outcome") if isinstance(conclusion, dict) else None
+            return _result(outcome if outcome in {"pass", "fail"} else "inconclusive")
+        if any(item.get("status") == "running" for item in verifications):
+            return _result("verifying")
+        return _result("awaiting")
+    return _result("diagnosed" if issue.get("diagnoses") else "pending")
+
+
+def summarize(keys):
+    """Count progress keys in workflow order, omitting nothing so callers can render stable legends."""
+    counts = dict.fromkeys(LABELS, 0)
+    for key in keys:
+        counts[key] += 1
+    return counts