cgraphx 1.1.0 → 1.3.0

package/scripts/agent-eval/subagent-token-cost.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Measure real API token usage and $ cost from Claude Code subagent transcripts.
+
+Reads the `.output` JSONL file Claude Code writes per background subagent
+(the `output_file` returned by the Agent tool), sums the `usage` field on
+each assistant message, and applies Sonnet list pricing to get a cache-aware
+$ cost.
+
+Why this exists: tool-output chars (the easy thing to count by eye) is a
+poor proxy for real cost. The dominant cost driver in multi-turn sessions is
+`cache_read_input_tokens` — every turn re-sends the growing conversation as
+cached input, billed at ~10% of full input cost. A tool that returns tiny
+output but forces many turns (grep) is more expensive than a tool that
+returns rich output in few turns (codegraph_explore). chars hides this;
+`usage` + $ pricing exposes it.
+
+See docs/features/2026-07-01-calls-command/abac-comparison.md for the case
+study that motivated this script.
+
+Pricing (Sonnet, per million tokens):
+    input             $3.00
+    output            $15.00
+    cache_read        $0.30   (10% of input)
+    cache_creation    $3.75   (125% of input — first-time cache write)
+
+Usage:
+    python3 subagent-token-cost.py <agent-id> [<agent-id> ...]
+    python3 subagent-token-cost.py --dir <tasks-dir>   # all .output files
+
+The agent-id form looks up `<tasks-dir>/<agent-id>.output` under the standard
+session tasks directory. Pass `--dir` to point at a different directory
+(e.g. when comparing across sessions).
+
+Output: one line per arm with turns, tool_uses, input/output/cache_read/
+cache_write token counts, raw total, and $ cost. Sorted in input order.
+
+Notes:
+- This reads ONLY the `usage` field and tool_use block counts — never message
+  content. Safe to run on large transcripts; won't overflow your context.
+- For main-session cost (not subagent), use offload-eval-cost.mjs instead,
+  which reads the structured eval-runs format and uses Claude Code's own
+  authoritative costUSD accounting from the `result` event.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# Sonnet list pricing, per million tokens.
+PRICE_INPUT_PER_M = 3.00
+PRICE_OUTPUT_PER_M = 15.00
+PRICE_CACHE_READ_PER_M = 0.30
+PRICE_CACHE_WRITE_PER_M = 3.75
+
+
+def default_tasks_dir() -> Path:
+    """Best-effort default for this session's tasks dir."""
+    # Claude Code writes subagent .output files under a session-scoped tasks dir.
+    # The exact path varies; common locations:
+    candidates = [
+        Path('/private/tmp/claude-501'),
+        Path.home() / '.claude' / 'tasks',
+    ]
+    for c in candidates:
+        if c.exists():
+            # Find the most recently modified session dir
+            session_dirs = sorted(
+                c.glob('*-Users-*'), key=lambda p: p.stat().st_mtime, reverse=True
+            )
+            for sd in session_dirs:
+                tasks = sd / 'tasks'
+                if tasks.exists():
+                    return tasks
+    return Path('/private/tmp/claude-501/unknown-session/tasks')
+
+
+def measure_file(path: Path) -> dict | None:
+    if not path.exists():
+        return None
+    totals = {'input': 0, 'output': 0, 'cache_read': 0, 'cache_creation': 0}
+    assistant_turns = 0
+    tool_uses = 0
+    with path.open() as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            msg = obj.get('message') or {}
+            if msg.get('role') != 'assistant':
+                continue
+            usage = msg.get('usage') or {}
+            if not usage:
+                continue
+            assistant_turns += 1
+            totals['input'] += usage.get('input_tokens', 0) or 0
+            totals['output'] += usage.get('output_tokens', 0) or 0
+            totals['cache_read'] += usage.get('cache_read_input_tokens', 0) or 0
+            totals['cache_creation'] += usage.get('cache_creation_input_tokens', 0) or 0
+            content = msg.get('content') or []
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get('type') == 'tool_use':
+                        tool_uses += 1
+    cost = (
+        totals['input'] * PRICE_INPUT_PER_M
+        + totals['output'] * PRICE_OUTPUT_PER_M
+        + totals['cache_read'] * PRICE_CACHE_READ_PER_M
+        + totals['cache_creation'] * PRICE_CACHE_WRITE_PER_M
+    ) / 1_000_000
+    return {
+        'turns': assistant_turns,
+        'tool_uses': tool_uses,
+        'totals': totals,
+        'all_tokens': sum(totals.values()),
+        'cost_usd': cost,
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split('\n')[0])
+    ap.add_argument('agent_ids', nargs='*', help='subagent IDs to measure')
+    ap.add_argument(
+        '--dir',
+        help='tasks directory containing <id>.output files (default: auto-detect latest session)',
+    )
+    ap.add_argument(
+        '--label',
+        action='append',
+        default=[],
+        help='label for an agent, in the same order as agent_ids (repeatable)',
+    )
+    args = ap.parse_args()
+
+    tasks_dir = Path(args.dir) if args.dir else default_tasks_dir()
+
+    if not args.agent_ids:
+        # Measure every .output file in the tasks dir
+        files = sorted(tasks_dir.glob('*.output'))
+        if not files:
+            print(f'no .output files in {tasks_dir}', file=sys.stderr)
+            return 1
+        targets = [(f.stem, f) for f in files]
+    else:
+        targets = [(aid, tasks_dir / f'{aid}.output') for aid in args.agent_ids]
+
+    rows = []
+    for i, (label, path) in enumerate(targets):
+        if args.label and i < len(args.label):
+            label = args.label[i]
+        r = measure_file(path)
+        if r is None:
+            print(f'{label}: transcript not found at {path}', file=sys.stderr)
+            continue
+        r['label'] = label
+        rows.append(r)
+
+    if not rows:
+        return 1
+
+    header = (
+        f'{"Arm":<32} {"turns":>6} {"tools":>6} {"input":>10} {"output":>10} '
+        f'{"cache_r":>10} {"cache_w":>10} {"total_tok":>11} {"$ cost":>9}'
+    )
+    print(header)
+    print('-' * len(header))
+    for r in rows:
+        t = r['totals']
+        print(
+            f'{r["label"]:<32} {r["turns"]:>6} {r["tool_uses"]:>6} {t["input"]:>10,} '
+            f'{t["output"]:>10,} {t["cache_read"]:>10,} {t["cache_creation"]:>10,} '
+            f'{r["all_tokens"]:>11,} ${r["cost_usd"]:>8.4f}'
+        )
+
+    print()
+    print('Pricing: Sonnet list. input $3/M, output $15/M, cache_read $0.30/M, cache_write $3.75/M.')
+    print('total_tok = raw token sum (ignores cache discount). $ cost = cache-aware (what actually bills).')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/dist/.claude-template/skills/code-impact-docgen/template-business-html.md

@@ -1,242 +0,0 @@
-# Business 文档 HTML 模板
-
-适用于面向业务读者的 HTML 格式文档。
-
-生成前阅读此文件获取完整的 CSS 样式和章节结构参考。
-
-## 完整 HTML 结构
-
-```html
-<!DOCTYPE html>
-<html lang="zh-CN">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>{文档标题} — {项目名称}</title>
-  <style>
-    :root {
-      --bg: #ffffff;
-      --surface: #f8f9fa;
-      --text: #1d1d1f;
-      --text-secondary: #6e6e73;
-      --accent: #0071e3;
-      --accent-light: #e8f0fe;
-      --border: #d2d2d7;
-      --code-bg: #f5f5f7;
-      --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
-      --font-mono: "SF Mono", "Fira Code", "Cascadia Code", "Source Code Pro", monospace;
-      --max-width: 800px;
-    }
-
-    *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
-
-    body {
-      font-family: var(--font-sans);
-      font-size: 16px;
-      line-height: 1.7;
-      color: var(--text);
-      background: var(--bg);
-    }
-
-    .container {
-      max-width: var(--max-width);
-      margin: 0 auto;
-      padding: 2rem 1.5rem;
-    }
-
-    h1 {
-      font-size: 2rem;
-      font-weight: 700;
-      letter-spacing: -0.02em;
-      margin-bottom: 0.5em;
-      padding-bottom: 0.5em;
-      border-bottom: 2px solid var(--border);
-    }
-
-    .meta {
-      color: var(--text-secondary);
-      font-size: 0.875rem;
-      margin-bottom: 2em;
-    }
-
-    h2 {
-      font-size: 1.5rem;
-      font-weight: 600;
-      margin-top: 2.5em;
-      margin-bottom: 0.75em;
-      padding-bottom: 0.3em;
-      border-bottom: 1px solid var(--border);
-    }
-
-    h3 {
-      font-size: 1.2rem;
-      font-weight: 600;
-      margin-top: 1.5em;
-      margin-bottom: 0.5em;
-    }
-
-    p { margin-bottom: 1em; }
-
-    ul, ol {
-      margin-bottom: 1em;
-      padding-left: 1.5em;
-    }
-
-    li { margin-bottom: 0.3em; }
-
-    strong { font-weight: 600; }
-
-    code {
-      font-family: var(--font-mono);
-      background: var(--code-bg);
-      padding: 0.15em 0.4em;
-      border-radius: 4px;
-      font-size: 0.9em;
-    }
-
-    pre {
-      background: var(--code-bg);
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      padding: 1em;
-      margin-bottom: 1em;
-      overflow-x: auto;
-    }
-
-    pre code {
-      background: none;
-      padding: 0;
-      font-size: 0.875em;
-    }
-
-    table {
-      width: 100%;
-      border-collapse: collapse;
-      margin-bottom: 1em;
-      font-size: 0.95em;
-    }
-
-    th, td {
-      padding: 0.6em 1em;
-      text-align: left;
-      border-bottom: 1px solid var(--border);
-    }
-
-    thead th {
-      font-weight: 600;
-      color: var(--accent);
-      background: var(--surface);
-    }
-
-    tbody tr:nth-child(even) { background: var(--surface); }
-
-    .toc {
-      background: var(--surface);
-      border: 1px solid var(--border);
-      border-radius: 8px;
-      padding: 1em 1.5em;
-      margin-bottom: 2em;
-    }
-
-    .toc h3 {
-      margin-top: 0;
-      margin-bottom: 0.5em;
-      font-size: 1rem;
-    }
-
-    .toc ul { list-style: none; padding-left: 0; }
-    .toc li { margin-bottom: 0.25em; }
-    .toc a { color: var(--accent); text-decoration: none; }
-    .toc a:hover { text-decoration: underline; }
-    .toc ul ul { padding-left: 1.5em; margin-top: 0.25em; }
-
-    .callout {
-      background: var(--accent-light);
-      border-left: 4px solid var(--accent);
-      padding: 0.75em 1em;
-      border-radius: 0 8px 8px 0;
-      margin-bottom: 1em;
-    }
-
-    @media print {
-      body { font-size: 12pt; }
-      .container { max-width: 100%; padding: 0; }
-      .toc { break-after: page; }
-      h2 { break-after: avoid; }
-    }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <h1>{文档标题}</h1>
-    <p class="meta">生成日期：YYYY-MM-DD | 主题范围：{范围描述}</p>
-
-    <nav class="toc">
-      <h3>目录</h3>
-      <ul>
-        <li><a href="#背景与目标">背景与目标</a></li>
-        <li><a href="#核心能力">核心能力</a></li>
-        <li><a href="#业务流程">业务流程</a></li>
-        <li><a href="#关键决策">关键决策</a></li>
-        <li><a href="#现状与展望">现状与展望</a></li>
-      </ul>
-    </nav>
-
-    <article>
-      <section id="背景与目标">
-        <h2>背景与目标</h2>
-        <p>说明项目或系统的定位、目标和解决的问题。</p>
-      </section>
-
-      <section id="核心能力">
-        <h2>核心能力</h2>
-        <p>描述系统提供的主要能力和价值。</p>
-      </section>
-
-      <section id="业务流程">
-        <h2>业务流程</h2>
-        <p>说明核心业务流程和操作步骤。</p>
-      </section>
-
-      <section id="关键决策">
-        <h2>关键决策</h2>
-        <p>列出重要的技术和业务决策及其理由。</p>
-      </section>
-
-      <section id="现状与展望">
-        <h2>现状与展望</h2>
-        <p>说明当前状态和未来方向。</p>
-      </section>
-    </article>
-  </div>
-</body>
-</html>
-```
-
-## Business HTML 章节内容指南
-
-每个章节应按照以下指引从 AI 知识文档中提取、转换和改写内容。
-
-| 章节 | 内容来源 | 改写方向 |
-|------|------------------------|----------|
-| 背景与目标 | Summary 文本 | 从"为什么分析"转为"项目/系统的目标和定位" |
-| 核心能力 | Summary 文本 | 从"发现"转为"能力描述"，面向非技术读者 |
-| 业务流程 | Read 文件原文（该章节 cgraphx 不提取） | 从"操作步骤"转为"业务流程说明"，去除技术细节 |
-| 关键决策 | Read 文件原文（该章节 cgraphx 不提取） | 从"决策记录"转为"决策解释"，说明决策的业务原因 |
-| 价值与影响 | Read 文件原文（该章节 cgraphx 不提取） | 从"对未来变更的影响"转为"对业务的价值和影响" |
-| 现状与展望 | Read 文件原文（该章节 cgraphx 不提取） | 从"发现和后续"转为"当前状态和未来规划" |
-| 风险与注意事项 | Read 文件原文（该章节 cgraphx 不提取） | 从"故障排除"转为"风险提示和应对措施" |
-| 常见问题 | Read 文件原文（该章节 cgraphx 不提取） | 从"分析记录"转为"Q&A 格式" |
-| 术语表 | 各文本字段中的术语 | 提取关键术语，给出简洁的业务定义 |
-| 相关资源 | — | 列出相关的代码文件（相对路径）或外部文档 |
-
-## HTML 格式要点
-
-- 所有 CSS 内联在 `<style>` 标签中，不引用外部样式表
-- `<title>` 包含文档标题和项目名称
-- 使用 `<nav class="toc">` 作为目录容器
-- 每个章节使用 `<section id="章节锚点">` 包裹
-- 章节锚点使用中文 ID（如 `id="背景与目标"`）
-- 重要提示或注意事项使用 `<div class="callout">` 样式
-- 代码示例使用 `<pre><code>` 标签
-- 表格使用 `<thead>` + `<tbody>` 结构

package/dist/.claude-template/skills/code-impact-docgen/template-business-md.md

@@ -1,107 +0,0 @@
-# Business 文档 Markdown 模板
-
-适用于面向业务读者的 Markdown 格式文档。
-
-## 文档结构
-
-```markdown
-# {文档标题}
-
-> 生成日期：YYYY-MM-DD | 主题范围：{范围描述}
-
-## 目录
-
-- [背景与目标](#背景与目标)
-- [核心能力](#核心能力)
-- [业务流程](#业务流程)
-- [关键决策](#关键决策)
-- [现状与展望](#现状与展望)
-
-## 背景与目标
-
-说明项目/系统的定位、目标和解决的问题。
-
-## 核心能力
-
-描述系统提供的主要能力和价值。
-
-## 业务流程
-
-说明核心业务流程和操作步骤。
-
-## 关键决策
-
-列出重要的技术和业务决策及其理由。
-
-## 现状与展望
-
-说明当前状态和未来方向。
-```
-
-## 可选章节（按需插入）
-
-```markdown
-## 用户场景
-
-描述典型使用场景。
-
-## 价值与影响
-
-说明对业务的价值和影响。
-
-## 风险与注意事项
-
-列出已知风险和应对措施。
-
-## 常见问题
-
-**Q: 问题一？**
-
-A: 回答。
-
-**Q: 问题二？**
-
-A: 回答。
-
-## 术语表
-
-| 术语 | 定义 |
-|------|------|
-| 术语 A | 简洁的业务定义 |
-| 术语 B | 简洁的业务定义 |
-
-## 相关资源
-
-- [相关文档](相对路径)
-- [外部链接](URL)
-```
-
-## Business Markdown 章节内容指南
-
-| 章节 | 内容来源 | 改写方向 |
-|------|------------------------|----------|
-| 背景与目标 | Summary 文本 | 从"为什么分析"转为"项目/系统的目标和定位" |
-| 核心能力 | Summary 文本 | 从"发现"转为"能力描述"，面向非技术读者 |
-| 业务流程 | Read 文件原文（该章节 cgraphx 不提取） | 从"操作步骤"转为"业务流程说明"，去除技术细节 |
-| 关键决策 | Read 文件原文（该章节 cgraphx 不提取） | 从"决策记录"转为"决策解释"，说明决策的业务原因 |
-| 价值与影响 | Read 文件原文（该章节 cgraphx 不提取） | 从"对未来变更的影响"转为"对业务的价值和影响" |
-| 现状与展望 | Read 文件原文（该章节 cgraphx 不提取） | 从"发现和后续"转为"当前状态和未来规划" |
-| 风险与注意事项 | Read 文件原文（该章节 cgraphx 不提取） | 从"故障排除"转为"风险提示和应对措施" |
-| 常见问题 | Read 文件原文（该章节 cgraphx 不提取） | 从"分析记录"转为"Q&A 格式" |
-| 术语表 | 各文本字段中的术语 | 提取关键术语，给出简洁的业务定义 |
-| 相关资源 | — | 列出相关的代码文件（相对路径）或外部文档 |
-
-## 格式规则
-
-- 不使用 YAML frontmatter
-- 文档标题使用单个 `#`
-- 章节使用 `##`
-- 子章节使用 `###`
-- 列表使用 `-` 或数字编号
-- 代码块使用三个反引号，标注语言
-- 表格使用标准 Markdown 表格
-- 强调使用 `**加粗**`
-- 技术术语用反引号包裹
-- 段落之间空一行
-- 每个章节以 `##` 标题开始，标题后空一行再写内容
-- 目录使用锚点链接，链接文本与章节标题一致