Metadata-Version: 2.4
Name: tianlong-toolkit
Version: 0.3.0
Summary: 天龙工具箱 — Agent健康监控、安全约束与进化评估
Author: 天龙1号
License: MIT
Project-URL: Homepage, https://github.com/
Keywords: agent,monitoring,safety,ai-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 天龙工具箱 (Tianlong Toolkit)

> Agent 健康监控、安全约束与进化评估。从架构蓝图到可安装的 Python 工具箱。
>
> 版本: **v0.3.0** | 80 tests passing | 纯标准库

## 安装

```bash
pip install tianlong-toolkit
```

## 模块

### monitor — Agent 健康监控

8项内置检查，支持自定义检查器注册，支持单项目/多项目批量检查。

```bash
# 检查当前目录
tianlong-monitor

# 指定项目
tianlong-monitor -d /path/to/agent -o text

# JSON 输出
tianlong-monitor -d /path/to/agent -o json

# 批量检查多个项目
tianlong-monitor -m /project/a /project/b -o text
```

```python
from tianlong.monitor import run_all_checks, register_check, BaseCheck

# 运行所有检查
report = run_all_checks("/path/to/agent")
print(report.to_json())

# 自定义检查
@register_check
class MyCheck(BaseCheck):
    def run(self):
        return CheckResult(name="my-check", status="ok", message="一切正常")
```

### safety — SafetyGuard 安全约束引擎

5条红线规则 + 进化门控 + 退化检测 + 审计日志。支持 CLI 和 Python SDK。

```bash
# 安全检查
tianlong-safety check -a delete -t config.yaml

# 查看规则
tianlong-safety rules

# 从文件加载自定义规则
tianlong-safety check -a create -t note.md --rules my-rules.json

# 查看审计日志
tianlong-safety audit --limit 10
```

```python
from tianlong.safety import SafetyGuard, ChangeType, DEFAULT_RULES

guard = SafetyGuard(rules=DEFAULT_RULES)

# 安全检查
result = guard.check(action=ChangeType.DELETE, target="config.yaml")
if not result.allowed:
    print(f"⛔ 阻止: {result.reason}")

# 退化检测
guard.record_degradation("错误重复率", "同类错误出现3次")

# 导出审计日志
guard.save_audit_log("audit-log.json")
```

### judge — Agent-as-a-Judge 进化方向评估

5维评分（方向性/效率/鲁棒性/可复用性/成本风险），支持规则引擎和 LLM API 双模式。

```python
from tianlong.judge import RuleBasedJudge, Proposal

judge = RuleBasedJudge()

# 评估一个提案
proposal = Proposal(
    id="p001",
    summary="优化搜索流程",
    change_type="update",
    estimated_steps=3,
)
result = judge.evaluate(proposal)
print(f"综合分: {result.total_score}, 等级: {result.grade.value}")
print(f"通过: {result.passed()}")

# 使用预设模板快速评估
result = judge.evaluate_from_template("create_new_knowledge")
```

## 项目结构

```
tianlong/
├── __init__.py              # v0.3.0
├── monitor/                 # 健康监控模块
│   ├── checks.py            # 8项内置检查 + 注册表
│   ├── cli.py               # tianlong-monitor 命令
│   └── __main__.py          # python -m 入口
├── safety/                  # 安全约束模块
│   ├── types.py             # 类型定义
│   ├── rules.py             # 5条红线规则
│   ├── core.py              # SafetyGuard 引擎
│   ├── cli.py               # tianlong-safety 命令
│   └── __main__.py          # python -m 入口
└── judge/                   # 进化评估模块
    └── core.py              # JudgeEngine + 规则引擎实现
```

## 开发

```bash
git clone ...
cd tianlong-toolkit
pip install -e .
pytest tests/ -v
```
