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

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-tune-kit",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-tune-kit
-Version: 2.3.0
+Version: 2.3.2
 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,13 @@ $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.
+
+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.
+
+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, Fix, and Verify an Issue as Needed
 
@@ -175,7 +183,7 @@ Start with diagnosis when you already have a specific issue and session evidence
 
 ### 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 |
 | --- | --- |

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.2}/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,13 @@ $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.
+
+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.
+
+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, Fix, and Verify an Issue as Needed
 
@@ -161,7 +169,7 @@ Start with diagnosis when you already have a specific issue and session evidence
 
 ### 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 |
 | --- | --- |

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.2}/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,13 @@ $atk-trace-detect 分析 <session-id> 的任务结果是否正确，列出问题
 $atk-visualize-trace 打开 <session-id> 的执行泳道，从问题跳到相关轨迹片段和证据字段。
 ```
 
-分析会列出问题、证据和检查范围。可用 Trace ID 定位会话内的证据。有归档轨迹即可生成预览，分享 HTML 前请核对其中留存的正文。
+分析保留影响严重、反复出现、与你明确关注点相关，或有具体实现改进线索的问题，并说明保留理由、证据和检查范围。实现线索包括代码、配置、工具契约、Prompt 和 Skill；根因尚未确定也可进入后续诊断。轻微且无上述保留理由的观察不单独记录，没有保留问题不代表会话完全正确。
+
+采集、分析、诊断、修复和验证 Skill 在阶段结束后默认生成或更新 `.atk/traces/<session_id>/preview.html`，不自动打开浏览器。需要打开时使用 `$atk-visualize-trace`；已打开的页面在文件更新后需刷新。初始化没有会话轨迹，不生成空页面。
+
+这些阶段同时刷新项目大盘 `.atk/traces/index.html`，按会话或异常分类查看全部会话的问题和实际进度，并可跳回各会话页。需要打开时发送 `$atk-visualize-trace 打开轨迹大盘`。早于分类功能的问题显示为“未分类”，对应会话重新分析时补上。
+
+可用 Trace ID 定位会话内的证据，在问题详情中查看保留理由。分享 HTML 前请核对其中留存的正文。
 
 ### 3. 按问题调查、修复和验证（按需）
 
@@ -161,7 +169,7 @@ $atk-trace-verify 验证 <session-id> 的 ISSUE-001 对应候选，并检查相
 
 ### 查看轨迹产物
 
-会话归档保存在 Agent 项目的 `.atk/traces/<session_id>/` 下，文件随对应步骤生成。
+会话归档保存在 Agent 项目的 `.atk/traces/<session_id>/` 下，文件随对应步骤生成。项目大盘 `index.html` 和分类表 `categories.json` 位于 `.atk/traces/` 根目录。
 
 | 文件或目录 | 用途 |
 | --- | --- |

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

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

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.2}/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,12 @@ 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")
+    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",
@@ -100,6 +106,10 @@ def execute(args):
     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

{agent_tune_kit-2.3.0 → agent_tune_kit-2.3.2}/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.0 → agent_tune_kit-2.3.2}/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.2}/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", "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.2/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.2/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