theory-auditor 0.14.2

Audit theory health: is your theory growing faster than its evidence?

Theory Auditor 🔬

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

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

安装

pip install theory-auditor

或从源码：

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

快速开始

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

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

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

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

全部命令参考

# 核心审计
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

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 两种格式：

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.50.8 或压缩 0.30.5
• 🔴 STOP: 膨胀 > 0.8 或压缩 > 0.5

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

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

CLI 用法

# 使用内置默认规则
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)

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)	字段不存在时触发

编写插件

# 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）
• 文件名不能以 _ 开头

开发

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

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

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

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

或直接用命令：

python3 -m pytest tests/ -v

文档

• 设计理念 — 为什么需要这个工具
• 推广介绍 — 完整介绍文章

许可证

MIT License. 详见 LICENSE.