Metadata-Version: 2.4
Name: theory-auditor
Version: 0.14.2
Summary: Audit theory health: is your theory growing faster than its evidence?
Author-email: Chronos Lab <chronoslab@agent.qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sandmark78/theory-auditor
Project-URL: Issues, https://github.com/sandmark78/theory-auditor/issues
Keywords: science,research,audit,theory,falsifiability,reproducibility
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Dynamic: license-file

# Theory Auditor 🔬

**你的理论增长速度是否超过了证据增长速度？**

一个用于审计研究项目健康状态的 Python 工具。核心原则：**任何理论都必须比自己的证据增长得更慢。**

## 安装

```bash
pip install theory-auditor
```

或从源码：

```bash
git clone https://github.com/sandmark78/theory-auditor.git
cd theory-auditor
pip install -e .
```

## 快速开始

```bash
# 审计单个项目
theory-auditor audit project.json

# 简短摘要（5行）
theory-auditor summary project.yaml

# 仅检查五条协议
theory-auditor check project.json

# 对比多个项目（支持JSON+YAML混合）
theory-auditor compare examples/
```

## 全部命令参考

```bash
# 核心审计
theory-auditor audit project.json          # 完整审计报告
theory-auditor audit project.yaml --stdin  # 从 stdin 读取
theory-auditor summary project.json        # 5行摘要
theory-auditor check project.json          # 仅五条协议检查

# 对比与批量
theory-auditor compare examples/           # 对比目录下所有项目
theory-auditor batch examples/             # 批量审计+认证
theory-auditor batch examples/ -r          # 递归子目录

# 膨胀检测与认证
theory-auditor detect project.json         # AI辅助膨胀检测
theory-auditor certify project.json        # 理论认证评估

# 分析工具
theory-auditor diff report1.json report2.json  # 对比两份报告
theory-auditor coverage project.json           # 审计覆盖率
theory-auditor trend --db audit_store.db       # 趋势分析
theory-auditor rules project.json --default    # 自定义规则检查
theory-auditor rules --validate rules.yaml     # 验证规则文件

# CI/CD 集成
theory-auditor ci project.json --inflation-threshold 0.5  # 门禁模式
theory-auditor ci project.json -f junit                   # JUnit XML 输出
theory-auditor precommit install                          # Git hook

# 输出与可视化
theory-auditor export project.json -f markdown  # 导出 Markdown/CSV
theory-auditor dashboard project.json           # HTML 仪表盘
theory-auditor badge project.json               # SVG 状态徽章

# 项目管理
theory-auditor init                    # 初始化项目配置
theory-auditor serve                   # 启动 Web API 服务器
theory-auditor watch project.json      # 持续审计模式

# 通用选项
theory-auditor --version               # 显示版本
theory-auditor --lang en audit ...     # 英文输出
```

## Python API

```python
from theory_auditor import TheoryAuditor
import json

with open("project.json") as f:
    data = json.load(f)

auditor = TheoryAuditor(data)
report = auditor.audit()

print(report["recommended_action"])  # CONTINUE / AUDIT / STOP
print(report["health_indicators"])
```

## 项目文件格式

支持 JSON 和 YAML 两种格式：

```yaml
project_name: "My Theory"
start_date: "2020-01-01"
current_date: "2026-07-09"
parameters:
  - name: "param_name"
    provenance: "来源（第一性原理/经验拟合/推导）"
    physical_meaning: "物理含义"
    dependencies: []
    added_date: "2020-01-01"
    deleted_date: null
hypotheses:
  - name: "假设名"
    kill_test: "什么证据能杀死它"
    status: "active"
evidence_count: 100
formula_count: 20
start_formula_count: 5
```

## 五条审计协议

| 协议 | 内容 | 为什么重要 |
|------|------|-----------|
| P1 Kill Test | 每个假设必须有死亡条件 | 无证伪=非科学 |
| P2 Provenance | 每个参数必须有来源 | 无来源=ad hoc |
| P3 Deletion | 删除比例 > 20% | 删除即进步 |
| P4 Archive | 失败路线必须归档 | 防止换名复活 |
| P5 No Resurrection | 禁止无新证据复活 | 防止僵尸理论 |

## 健康指标

- **理论膨胀指数** = 理论增长速度 / 证据增长速度（越低越好）
- **删除比例** = 已删除参数 / 总参数（>20% 为健康）
- **Compression Ratio** = (当前公式 - 初始公式) / 初始公式

## 推荐行动

- 🟢 **CONTINUE**: 膨胀 < 0.5 且压缩 < 0.3
- 🟡 **AUDIT**: 膨胀 0.5~0.8 或压缩 0.3~0.5
- 🔴 **STOP**: 膨胀 > 0.8 或压缩 > 0.5

## 自定义规则引擎 (v0.10.0+)

支持 YAML/JSON 定义自定义审计规则，以及 Python 插件扩展。

### CLI 用法

```bash
# 使用内置默认规则
theory-auditor rules project.json --default

# 使用自定义规则文件
theory-auditor rules project.json --rules-file my_rules.yaml

# 加载插件目录
theory-auditor rules project.json --plugin-dir ./plugins/

# JSON 输出
theory-auditor rules project.json --default -f json
```

### 规则文件格式 (YAML)

```yaml
rules:
  - id: R001
    name: 规则名称
    description: 规则描述
    severity: warning    # info / warning / error / critical
    condition: "metrics.evidence_ratio < 2.0"
    action: warn         # warn / block / info
    tags: [evidence]
```

### 支持的条件表达式

| 表达式 | 含义 |
|--------|------|
| `field.path < N` | 字段值小于阈值时触发 |
| `field.path > N` | 字段值大于阈值时触发 |
| `field.path == N` | 字段值等于阈值时触发 |
| `field.path != N` | 字段值不等于阈值时触发 |
| `exists(field.path)` | 字段存在时触发 |
| `not_exists(field.path)` | 字段不存在时触发 |

### 编写插件

```python
# plugins/my_plugin.py
from theory_auditor.rules import RuleResult, RuleStatus, Severity

class MyPlugin:
    def check(self, audit_data):
        # 你的检查逻辑
        return RuleResult(
            rule_id='MY_001',
            rule_name='我的检查',
            status=RuleStatus.PASSED,
            severity=Severity.INFO,
            message='检查通过',
            execution_time_ms=0.1
        )
    
    def metadata(self):
        return {'id': 'MY_001', 'name': 'My Plugin', 'version': '1.0'}
```

插件要求：
- 实现 `check(audit_data) -> RuleResult` 方法
- 实现 `metadata() -> dict` 方法（必须包含 `id` 和 `name`）
- 文件名不能以 `_` 开头

## 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
make test              # 快速测试
make test-verbose      # 详细输出

# 代码质量
make lint              # 代码检查（需安装 flake8）
make format            # 代码格式化（需安装 black）

# 构建发布
make build             # 构建分发包
make clean             # 清理临时文件
```

或直接用命令：

```bash
python3 -m pytest tests/ -v
```

## 文档

- [设计理念](DESIGN.md) — 为什么需要这个工具
- [推广介绍](PROMOTION.md) — 完整介绍文章

## 许可证

MIT License. 详见 [LICENSE](LICENSE).
