agentguard-tool 1.0.5__py3-none-any.whl

agentguard_tool-1.0.5.dist-info/METADATA

@@ -0,0 +1,328 @@
+Metadata-Version: 2.4
+Name: agentguard-tool
+Version: 1.0.5
+Summary: AI-native quality gate for agent-generated code — scan, audit, auto-fix, trend
+Author: Hermes Labs
+License: MIT License
+        
+        Copyright (c) 2026 Hermes Labs
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/weijinsheng123456/agentguard
+Project-URL: Issues, https://github.com/weijinsheng123456/agentguard/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: ruff>=0.4.0
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://img.shields.io/badge/AgentGuard-1.0.0-8A2BE2?style=for-the-badge&logo=python&logoColor=white" width="300" alt="AgentGuard">
+</p>
+
+<p align="center">
+  <em>AI-native quality gate for agent-generated code.</em>
+  <br>
+  Scan · Audit · Auto-fix · Track trends
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#commands">Commands</a> •
+  <a href="#demo">Demo</a> •
+  <a href="#rules">Rules</a> •
+  <a href="#write-custom-rules">Custom Rules</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/weijinsheng123456/agentguard/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/weijinsheng123456/agentguard/ci.yml?branch=main&label=CI&logo=github&color=success" alt="CI">
+  </a>
+  <a href="https://pypi.org/project/agentguard/">
+    <img src="https://img.shields.io/pypi/v/agentguard?label=PyPI&logo=pypi&color=blue" alt="PyPI">
+  </a>
+  <a href="LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
+  </a>
+  <a href="https://github.com/weijinsheng123456/agentguard/stargazers">
+    <img src="https://img.shields.io/github/stars/weijinsheng123456/agentguard?style=social" alt="Stars">
+  </a>
+  <a href="https://www.python.org/">
+    <img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue?logo=python" alt="Python">
+  </a>
+  <a href="https://github.com/weijinsheng123456/agentguard/blob/main/CHANGELOG.md">
+    <img src="https://img.shields.io/badge/version-1.0.0-8A2BE2" alt="Version">
+  </a>
+</p>
+
+---
+
+# 🚀 Install in 3 seconds
+
+```bash
+pip install agentguard-tool
+cd your-project
+gate run
+```
+
+Done. AgentGuard scans your code, detects AI-specific issues (hardcoded secrets, unsafe APIs, hallucinations), auto-fixes what it can, and tracks quality trends over time.
+
+---
+
+## Why AgentGuard?
+
+Traditional linters like SonarQube and CodeQL were built for **human-written code**. AI agents write code differently — they hallucinate module names, leave placeholder comments, generate giant functions, and introduce patterns that human linters miss.
+
+**AgentGuard is built for the age of AI-generated code.**
+
+It understands the patterns, pitfalls, and security risks specific to code written by LLMs. It runs as a CI-ready CLI, a pre-commit hook, or a daily cron.
+
+---
+
+## Features
+
+### 🔍 AI-Specific Detection (3 rules)
+| Rule | Severity | What It Finds |
+|------|----------|---------------|
+| `unsafe_api` | 🚫 BLOCKER | `eval()`, `exec()`, `os.system()`, `subprocess(shell=True)`, `pickle.loads()` |
+| `secret_leak` | 🚫 BLOCKER | Hardcoded API keys, tokens, passwords in source code |
+| `ai_hallucination` | ℹ️ INFO | AI placeholder comments, suspicious module names, giant auto-generated functions |
+
+### 📊 Agent Behavior Audit
+Reads agent trace data and produces a daily report:
+- Tool call frequency & ranking
+- Error rate & anomaly detection
+- Token consumption & cost estimates
+- Model usage distribution
+
+### 📈 Trend Dashboard
+Text-based trend chart with zero external dependencies:
+```
+━━━ 📈 Quality Trend (Last 14 days) ━━━
+  05/08 ████████████████   0 issues  ✅
+  05/09 ████████████░░░░   3 issues  ⚠️
+  05/10 ████████████████   0 issues  ✅
+```
+Data persists in SQLite. View anytime with `gate trend`.
+
+### 🔧 Auto-Fix Pipeline
+Automatically fixes what it can, backed up and git-committed:
+- Unused imports (`F401`) and variables (`F841`)
+- Bare `except:` → `except Exception:`
+- Hardcoded paths → `$HOME` references
+- Ruff-safe auto-fixes
+
+### 🧩 Plugin Rule Architecture
+Rules are Python classes. Adding a new rule = one file, one class, one decorator.
+```python
+@register_rule
+class MyRule(Rule):
+    name = "my_rule"
+    severity = Severity.BLOCKER
+
+    def diagnose(self, filepath: str) -> list[Issue]:
+        # Your detection logic here
+        ...
+```
+
+---
+
+## Quick Start
+
+```bash
+# 🎯 Scan your project
+pip install agentguard-tool
+cd your-project
+gate run
+
+# 🔍 Quick check (staged files only)
+gate run --quick
+
+# 📊 Agent behavior audit
+gate audit
+
+# 📈 View quality trends
+gate trend
+
+# 🔧 Install pre-commit hooks
+gate install
+```
+
+### Run from source
+```bash
+git clone https://github.com/weijinsheng123456/agentguard.git
+cd agentguard
+python gate.py run
+```
+
+---
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `gate run` | Full scan + auto-fix + commit + audit |
+| `gate run --quick` | Pre-commit check (staged files only) |
+| `gate run --fixme` | Auto-fix staged files |
+| `gate audit` | Agent behavior audit only |
+| `gate trend [N]` | Show last N days of quality trends |
+| `gate install` | Install pre-commit hooks & cron |
+| `gate version` | Show version |
+
+---
+
+## Rules
+
+### Built-in Rules (8 total)
+
+**Code Quality (ported from ruff):**
+| Rule | Code | Severity | Auto-fix |
+|------|------|----------|:--------:|
+| `syntax_check` | `SYNTAX` | BLOCKER | ❌ |
+| `ruff_blocker` | `F821`, `E999` | BLOCKER | ❌ |
+| `ruff_fixable` | `F401`, `F841`, `E711`, `E712` | FIXABLE | ✅ |
+| `bare_except` | `E722` | FIXABLE | ✅ |
+| `hardcoded_paths` | `HARDCODE` | FIXABLE | ✅ |
+
+**AI-Specific:**
+| Rule | Code | Severity | Auto-fix |
+|------|------|----------|:--------:|
+| `unsafe_api` | `UNSAFE_*` | BLOCKER | ❌ |
+| `secret_leak` | `LEAK_SECRET` | BLOCKER | ❌ |
+| `ai_hallucination` | `AI_*` | INFO | ❌ |
+
+---
+
+## Write Custom Rules
+
+Create a new `.py` file in `qg/rules/`:
+
+```python
+from qg.models import Issue, Severity
+from qg.rules.base import Rule, register_rule
+
+@register_rule
+class MyCustomRule(Rule):
+    name = "my_custom_rule"
+    severity = Severity.FIXABLE
+    description = "Detects something specific"
+
+    def should_check(self, filepath: str) -> bool:
+        return filepath.endswith(".py")
+
+    def diagnose(self, filepath: str) -> list[Issue]:
+        issues = []
+        # Your detection logic...
+        return issues
+
+    def fix(self, filepath: str, issue: Issue) -> bool:
+        # Your fix logic...
+        return True
+```
+
+Rules support two modes:
+- **`Rule`** — per-file scanning (for AST analysis, regex)
+- **`BatchRule`** — directory-level scanning (for ruff, 10-50x faster)
+
+---
+
+## Configuration
+
+```yaml
+scan_dirs:
+  - "~/my-project/src"
+  - "~/my-project/scripts"
+
+ignore_patterns:
+  - "*__pycache__*"
+  - "*/tests/*"
+
+severity:
+  blocker_codes: ["F821", "E999", "SYNTAX"]
+  auto_fix_codes: ["F401", "F841", "E711", "E712", "E722", "HARDCODE"]
+
+report:
+  to_wechat: true
+```
+
+---
+
+## Architecture
+
+```
+gate.py (CLI entry)
+└── qg/
+    ├── scanner.py      # File discovery
+    ├── engine.py       # Diagnostic engine (rule dispatching)
+    ├── fixer.py        # Auto-fix engine
+    ├── verifier.py     # Post-fix verification
+    ├── committer.py    # Git commit automation
+    ├── reporter.py     # Report generation (console + log)
+    ├── auditor.py      # Agent behavior audit
+    ├── dashboard.py    # Trend tracking (SQLite)
+    ├── models.py       # Data models
+    ├── config.py       # Configuration loader
+    └── rules/          # Plugin rules (hot-pluggable)
+        ├── base.py     # Rule + BatchRule base classes
+        ├── syntax_check.py
+        ├── ruff_blocker.py     (BatchRule)
+        ├── ruff_fixable.py     (BatchRule)
+        ├── bare_except.py
+        ├── hardcoded_paths.py
+        ├── unsafe_api.py
+        ├── secret_leak.py
+        └── ai_hallucination.py
+```
+
+---
+
+## Roadmap
+
+- [x] Phase 1: Python rewrite + plugin architecture
+- [x] Phase 2: AI-specific rules + agent audit + trend dashboard
+- [x] Phase 3: Open-source release + CI integration
+- [ ] Phase 4: Security rules (OWASP Top 10 for AI code)
+- [ ] Phase 5: GitHub Actions native action
+- [ ] Phase 6: VS Code extension
+
+---
+
+## License
+
+MIT License — see [LICENSE](LICENSE)
+
+---
+
+<p align="center">
+  Built for the age of AI-generated code.
+  <br>
+  <sub>Because code quality doesn't matter less when AI writes it — it matters more.</sub>
+</p>

agentguard_tool-1.0.5.dist-info/RECORD

@@ -0,0 +1,29 @@
+agentguard_tool-1.0.5.dist-info/licenses/LICENSE,sha256=GIXKl73dGwSbkQSE6HUMPgfwT0peiuDGFIrz4gfJ8xs,1068
+qg/__init__.py,sha256=Oh2451fZ3-TKpURfnm-bTk16TqYM0j2XByVAIHaSFIY,77
+qg/__main__.py,sha256=dvvjl6aIzE7EJt70fcQufvRFSxczegdOfqtLt7lqwAU,504
+qg/auditor.py,sha256=Un0KXuywsdVxb0_G5CRweiqP75i-MNKaGnT0SHzo9K8,6766
+qg/committer.py,sha256=JtbDjfGSAZcj92A2vduc_raOwGbTfoRT3e_b48Ci_9k,3263
+qg/config.py,sha256=tMjzMa_rWlGLTM1Su-dfaSCrdN6BaBOIzlQhdve5-4o,4341
+qg/dashboard.py,sha256=eY6BNnfNEdb0p9Ywe6nJf3sfamqRtHPs0UHztBKjXnQ,4444
+qg/engine.py,sha256=vnbQTQ6ZVqUnC9nMO4iqYel6_eumyacI2HUNfq20Y_4,3764
+qg/fixer.py,sha256=h7BqSZbF1NyMJaKCLCgtegp1jL6mGJQKubmEkHF47Q0,4056
+qg/main.py,sha256=6ukGt0Y7MZ9LCnnxG1mV9hmaaKEuhqIAx0bh6mWq2ow,11790
+qg/models.py,sha256=SY106zvZu2o1yeY8xWmpuXt4Hgf_-UjzVtkiCBm9D4g,2293
+qg/reporter.py,sha256=SbXEVmz1y7AO89yCM5FZxeU5NQirVeEF4ILO60fDUaM,2735
+qg/scanner.py,sha256=LubqmTfmw5Ue7usOV_g7660yqhRNrmpWw9588JkgzWc,3895
+qg/verifier.py,sha256=iKZmDGv1UvR5XL2kHdNHqfztm9foF8Qomgpo9tvr_SE,1270
+qg/rules/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+qg/rules/ai_hallucination.py,sha256=pktdUUIFcvaTYtxHBqWYbJzasY231Bkn_kNRp8fAg_Y,4061
+qg/rules/bare_except.py,sha256=I66hUtLgst-qAqOwGFrs_FzyPhSMLMJC8Ca6T_mJ2vI,1609
+qg/rules/base.py,sha256=wiYKlyilJOEcAB0mEvTlBRtUHPcdoMTLN_xV9cfpm2I,2735
+qg/rules/hardcoded_paths.py,sha256=oSKfwPVkQnBRFB--y2Hj2pLw6lNSc2bjlSDZOXr30tY,1918
+qg/rules/ruff_blocker.py,sha256=194YmO9X5Obmscejtlui1yOR_rd8Ji3fsyVwK_oJDs8,1831
+qg/rules/ruff_fixable.py,sha256=XMvtFksiEP3a8_s9RoM0HnZJFb2uoPIxVimcHYxjXuk,2065
+qg/rules/secret_leak.py,sha256=6yf_AMXjEkL41op7jIpkMefD4UkGAiBjZwFGY3j4p7U,5129
+qg/rules/syntax_check.py,sha256=t8HJ8r623OY3xnYCnEnX8zMrrw0e9mB96jaXv73GAhc,1067
+qg/rules/unsafe_api.py,sha256=SQuIz509fqhDwd8j2l2BE1fnZdEFqPPogaUba9yHTNI,5280
+agentguard_tool-1.0.5.dist-info/METADATA,sha256=zDVFy6jEVrVnZWDqEepg7w4ZBJlym2WGB2tEQJ99Je8,10407
+agentguard_tool-1.0.5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+agentguard_tool-1.0.5.dist-info/entry_points.txt,sha256=wnBggB3me9QkignAXJILXFLX_DIEk77n7hewzupIsas,72
+agentguard_tool-1.0.5.dist-info/top_level.txt,sha256=EDXMbpxZjlpG6jxQHmoE9k_doivDOELRIHH8jo19gZk,3
+agentguard_tool-1.0.5.dist-info/RECORD,,

agentguard_tool-1.0.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentguard_tool-1.0.5.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agentguard = qg.__main__:main
+gate = qg.__main__:main

agentguard_tool-1.0.5.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hermes Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentguard_tool-1.0.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+qg

qg/__init__.py

@@ -0,0 +1 @@
+"""qg 包 — AgentGuard: AI-native quality gate for agent-generated code"""

qg/__main__.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""AgentGuard CLI entry point.
+
+Install: pip install agentguard
+Usage:   gate run    gate audit    gate trend
+"""
+
+import sys
+from pathlib import Path
+
+# When installed via pip, this isn't needed. When run from source, add to path.
+if not any(p.endswith("agentguard") for p in sys.path):
+    pkg_dir = Path(__file__).resolve().parent.parent
+    if (pkg_dir / "qg").exists():
+        sys.path.insert(0, str(pkg_dir))
+
+from qg.main import main
+
+if __name__ == "__main__":
+    main()

qg/auditor.py

@@ -0,0 +1,190 @@
+"""Agent行为审计模块。
+
+从 agent_traces 表读取数据，分析：
+- 工具调用频率与分布
+- 错误率与异常模式
+- Token消耗与成本估算
+- 异常行为检测（连续失败、循环调用）
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sqlite3
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+DB_PATH = Path(
+    os.environ.get("QG_TRACE_DB", os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
+) / "state.db"
+
+
+def _get_conn() -> Optional[sqlite3.Connection]:
+    """获取数据库连接"""
+    if not DB_PATH.exists():
+        logger.warning(f"state.db 不存在: {DB_PATH}")
+        return None
+    try:
+        conn = sqlite3.connect(str(DB_PATH))
+        conn.row_factory = sqlite3.Row
+        return conn
+    except sqlite3.Error as e:
+        logger.warning(f"连接 state.db 失败: {e}")
+        return None
+
+
+def _table_exists(conn: sqlite3.Connection, table: str) -> bool:
+    """检查表是否存在"""
+    try:
+        cursor = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+            (table,)
+        )
+        return cursor.fetchone() is not None
+    except sqlite3.Error:
+        return False
+
+
+def audit_agent(days: int = 7) -> dict:
+    """执行Agent行为审计，返回结构化报告"""
+    conn = _get_conn()
+    if conn is None:
+        return {"error": "state.db 不可用"}
+
+    if not _table_exists(conn, "agent_traces"):
+        return {"error": "agent_traces 表不存在（未启用追踪）"}
+
+    report: dict = {}
+
+    # 1. 整体统计
+    cursor = conn.execute("SELECT COUNT(*) as cnt FROM agent_traces")
+    total = cursor.fetchone()["cnt"]
+    report["total_events"] = total
+
+    # 2. 按事件类型分布
+    cursor = conn.execute(
+        "SELECT event_type, COUNT(*) as cnt FROM agent_traces GROUP BY event_type ORDER BY cnt DESC"
+    )
+    report["event_distribution"] = {row["event_type"]: row["cnt"] for row in cursor.fetchall()}
+
+    # 3. 按模型分布（api_call）
+    cursor = conn.execute(
+        "SELECT model, COUNT(*) as cnt FROM agent_traces WHERE event_type='api_call' AND model IS NOT NULL GROUP BY model ORDER BY cnt DESC LIMIT 10"
+    )
+    report["model_usage"] = {row["model"]: row["cnt"] for row in cursor.fetchall()}
+
+    # 4. 工具调用排行
+    cursor = conn.execute(
+        "SELECT tool_name, COUNT(*) as cnt FROM agent_traces WHERE event_type='tool_call' AND tool_name IS NOT NULL GROUP BY tool_name ORDER BY cnt DESC LIMIT 15"
+    )
+    report["tool_ranking"] = {row["tool_name"]: row["cnt"] for row in cursor.fetchall()}
+
+    # 5. 错误统计
+    cursor = conn.execute(
+        "SELECT status, COUNT(*) as cnt FROM agent_traces WHERE status != 'success' AND status IS NOT NULL GROUP BY status"
+    )
+    errors = {row["status"]: row["cnt"] for row in cursor.fetchall()}
+    cursor = conn.execute("SELECT COUNT(*) as cnt FROM agent_traces WHERE status != 'success' OR status IS NULL")
+    total_errors = cursor.fetchone()["cnt"]
+    report["errors"] = errors
+    report["total_errors"] = total_errors
+    report["error_rate"] = round(total_errors / total * 100, 2) if total > 0 else 0
+
+    # 6. Token消耗汇总
+    cursor = conn.execute(
+        "SELECT model, SUM(token_count) as total_tokens FROM agent_traces WHERE event_type='api_call' AND token_count IS NOT NULL GROUP BY model ORDER BY total_tokens DESC"
+    )
+    token_data = {row["model"]: row["total_tokens"] for row in cursor.fetchall()}
+    report["token_consumption"] = token_data
+    report["total_tokens"] = sum(token_data.values()) if token_data else 0
+
+    # 7. 成本估算（粗略：按模型均价）
+    COST_PER_1K = {
+        "deepseek-v4-flash": 0.00015,
+        "deepseek-v4-pro": 0.002,
+        "gpt-4o": 0.0025,
+        "gpt-4o-mini": 0.00015,
+        "claude-sonnet-4": 0.003,
+        "claude-haiku-3.5": 0.00025,
+    }
+    estimated_cost = 0.0
+    for model, tokens in token_data.items():
+        rate = 0.0005  # 默认
+        for key, val in COST_PER_1K.items():
+            if key in model.lower():
+                rate = val
+                break
+        estimated_cost += (tokens / 1000) * rate
+    report["estimated_cost_usd"] = round(estimated_cost, 4)
+
+    # 8. 每日活跃度（近7天）
+    report["daily_activity"] = {}
+    for i in range(days - 1, -1, -1):
+        day = (datetime.now() - timedelta(days=i)).strftime("%m/%d")
+        cursor = conn.execute(
+            "SELECT COUNT(*) as cnt FROM agent_traces WHERE timestamp LIKE ?",
+            (f"{day}%",)
+        )
+        report["daily_activity"][day] = cursor.fetchone()["cnt"]
+
+    # 9. 异常检测：连续同工具失败
+    cursor = conn.execute(
+        "SELECT session_id, tool_name, COUNT(*) as cnt FROM agent_traces WHERE event_type='tool_call' AND status != 'success' AND tool_name IS NOT NULL GROUP BY session_id, tool_name HAVING cnt >= 3 ORDER BY cnt DESC LIMIT 5"
+    )
+    anomalies = cursor.fetchall()
+    report["anomalies"] = [dict(a) for a in anomalies] if anomalies else []
+
+    conn.close()
+    return report
+
+
+def format_audit_report(report: dict) -> list[str]:
+    """将审计报告格式化为可读文本"""
+    if "error" in report:
+        return [f"⚠️ Agent审计不可用: {report['error']}"]
+
+    lines = []
+    lines.append("━━━ 📊 Agent行为审计 ━━━")
+
+    # 概览
+    lines.append(f"总事件: {report.get('total_events', 0)} 次")
+    dist = report.get("event_distribution", {})
+    parts = [f"{k}={v}" for k, v in sorted(dist.items(), key=lambda x: -x[1])]
+    lines.append(f"分布: {' | '.join(parts[:5])}")
+
+    # 错误率
+    err_rate = report.get("error_rate", 0)
+    err_total = report.get("total_errors", 0)
+    if err_rate > 0:
+        lines.append(f"错误: {err_total} 次 ({err_rate}%) ⚠️")
+    else:
+        lines.append("错误: 0 次 ✅")
+
+    # Token & 成本
+    tokens = report.get("total_tokens", 0)
+    cost = report.get("estimated_cost_usd", 0)
+    lines.append(f"Token: {tokens:,} | 成本: ~${cost:.4f}")
+
+    # 工具调用排行（Top 5）
+    tools = report.get("tool_ranking", {})
+    if tools:
+        top5 = list(tools.items())[:5]
+        lines.append(f"工具Top5: {' → '.join(f'{n}({c})' for n, c in top5)}")
+
+    # 模型使用
+    models = report.get("model_usage", {})
+    if models:
+        model_str = " | ".join(f"{m}: {c}" for m, c in list(models.items())[:3])
+        lines.append(f"模型: {model_str}")
+
+    # 异常
+    anomalies = report.get("anomalies", [])
+    if anomalies:
+        for a in anomalies:
+            lines.append(f"⚠️ 异常: session {a['session_id'][:12]}... {a['tool_name']} 失败 {a['cnt']} 次")
+
+    return lines