jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-21 09:28:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add example plugins (ai_image, calendar, music, rss, weather), fix .gitignore, move gengskill to tools/

Browse Source
This commit is contained in:
root
2026-07-21 12:45:17 +08:00
parent 75ae2b4692
commit 52dc22f86f
54 changed files with 13650 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

514
tools/gengskill/docs/ANNOTATIONS.md Normal file
View File

@ -0,0 +1,514 @@
# 🏷️ Geng Skill 代码注释规范与架构说明
> 本文档提供完整的代码注释体系、模块间关系、接口规范，供开发者和 AI Agent 使用。
---
## 1. 项目架构总览
```
┌──────────────────────────────┐
│ geng_assess.py │
│ (综合评估引擎 / 主入口) │
└──────────────┬───────────────┘
│
┌───────────┬───────────┼───────────┬───────────┐
▼ ▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐
│last_digit │ │ benford │ │ grim │ │fixed_rel │ │decimal_cons │
│_test.py │ │_test.py │ │_test.py │ │_test.py │ │_test.py │
│ │ │ │ │ │ │ │ │ │
│末位数字检测│ │本福特定律 │ │均值一致性 │ │固定关系检测│ │小数位一致性 │
└────────────┘ └────────────┘ └────────────┘ └────────────┘ └──────────────┘
│ │
│ ┌────────────────┐ │
└───────────▶│image_duplicate │◀─────────────┘
│_test.py │
│图像重复检测 │
└────────────────┘
```
---
## 2. 模块接口规范 (API Contract)
### 2.1 通用接口模式
每个检测模块都遵循统一的函数签名模式：
```python
def <module_name>_test(
values: List[str | float], # 输入数据
**kwargs # 模块特定参数
) -> Dict[str, Any]: # 标准化输出
"""
[模块名称] — [一句话描述]
Parameters
----------
values : list
待检测数据。字符串形式传入以保留原始精度。
**kwargs : dict
模块特定参数（详见各模块文档）
Returns
-------
dict
标准化输出，必含字段：
- test_name : str — 模块名称（中英文）
- status : str — "completed" | "insufficient_data" | "error"
- risk_level : str — "low" | "medium" | "medium-high" | "high"
- risk_score : float — 0-100 风险评分
- interpretation : str — 中文可读解释
"""
```
### 2.2 各模块特定接口
#### Module 1: `last_digit_test()`
```python
def last_digit_test(
values: List[str],
method: str = 'all_digits' # 'all_digits' | 'decimal_last'
) -> Dict:
"""
末位数字检测
特定输出字段:
- digit_distribution : Dict[str, int] — 0-9 各数字出现次数
- chi_square : float — 卡方统计量
- p_value : float — p值
- most_frequent_digit : int — 出现最多的数字
- most_frequent_proportion : float — 最高频率
- uniformity_deviation : float — 偏离均匀度 (0-1)
"""
```
#### Module 2: `benford_test()`
```python
def benford_test(
values: List[str],
order: int = 1 # 1=首位, 2=前两位
) -> Dict:
"""
本福特定律检测
前提条件: 数据应跨越至少1个数量级
特定输出字段:
- distribution : Dict[str, Dict] — 各位数字观测/期望频率
- mean_absolute_deviation : float — MAD (Nigrini 判定标准)
- conformity : str — 'close'|'acceptable'|'marginal'|'nonconforming'
- conformity_cn : str — 中文符合性判定
"""
```
#### Module 3: `grim_test_single()` / `grim_test_batch()`
```python
def grim_test_single(
mean: str, # 报告的平均值（字符串保留精度）
n: int, # 样本量
decimals: int = 2, # 报告的小数位数
scale_min: int = None, # 量表下限
scale_max: int = None # 量表上限
) -> Dict:
"""
GRIM 单项测试
特定输出字段:
- consistent : bool — 是否通过一致性检验
- computed_sum : float — 计算的总和 (mean × n)
- nearest_valid_mean : str — 最近的合法均值
- difference : float — 与最近合法均值的差距
"""
def grim_test_batch(
items: List[Dict] # 批量项目列表
) -> Dict:
"""
GRIM 批量测试
items 格式: [{"mean": "3.47", "n": 25, "decimals": 2, "label": "Table 1"}, ...]
特定输出字段:
- total_items : int
- inconsistent_items : int
- inconsistency_rate : float
- details : List[Dict] — 每项的详细结果
"""
```
#### Module 4: `fixed_relation_test()`
```python
def fixed_relation_test(
col1: List[float], # 第一列数据
col2: List[float], # 第二列数据
col1_name: str = 'A', # 列名标签
col2_name: str = 'B' # 列名标签
) -> Dict:
"""
固定关系检测 — ⭐ 核心模块（耿同学最常用的方法）
检测内容:
1. 固定差值 (col2 - col1 = 常数?)
2. 固定比值 (col2 / col1 = 常数?)
3. 完美线性关系 (R² → 1.0?)
4. 小数模式一致性
特定输出字段:
- detections : Dict — 各子检测结果
- fixed_difference : {is_fixed, is_exact, mean_difference, std_difference}
- fixed_ratio : {is_fixed, is_exact, mean_ratio, std_ratio}
- linear_relationship : {r_squared, slope, intercept, is_suspicious}
- decimal_pattern : {match_rate, is_suspicious}
- n_suspicious_patterns : int
"""
```
#### Module 5: `decimal_consistency_test()`
```python
def decimal_consistency_test(
values: List[str] # 保留原始字符串精度
) -> Dict:
"""
小数位一致性检测
特定输出字段:
- decimal_places_analysis : Dict — 小数位数分布
- decimal_repetition : Dict — 小数模式重复度
- position_digit_analysis : Dict — 各位数字分布检验
- autocorrelation : float — 小数部分自相关
- risk_factors : List[str] — 触发的风险因子
"""
```
#### Module 6: `find_duplicates()`
```python
def find_duplicates(
image_dir: str, # 图片目录
threshold: float = 0.85, # 相似度阈值
extensions: List[str] = None # 图片格式
) -> Dict:
"""
图像重复检测
依赖: Pillow, scikit-image (可选, 用于SSIM)
特定输出字段:
- n_images_scanned : int
- n_duplicate_pairs : int
- duplicates : List[Dict] — 每对疑似重复图片
- file_1, file_2 : str
- avg_hash_similarity : float
- diff_hash_similarity : float
- combined_similarity : float
- rotation_check : Dict — 旋转/翻转匹配结果
- ssim : float (如果 scikit-image 可用)
"""
```
---
## 3. 代码注释规范
### 3.1 文件头注释模板
每个 Python 文件必须包含以下格式的文件头：
```python
#!/usr/bin/env python3
"""
[模块名称中文] ([Module Name English])
{'='*len(module_name)}
原理：[一段话描述检测原理]
方法：[具体使用的统计方法]
参考：[关键参考文献，一行一条]
致敬"耿同学讲故事" — 用数据说话，让造假无所遁形。
"""
```
### 3.2 函数注释规范 (NumPy Style)
```python
def function_name(param1, param2, param3=default):
"""
[一句话功能描述]
[详细说明段落，解释为什么需要这个函数、在什么场景下使用]
Parameters
----------
param1 : type
参数说明
param2 : type
参数说明
param3 : type, optional
参数说明（默认值：default）
Returns
-------
return_type
返回值说明
Raises
------
ValueError
何时抛出此异常
Examples
--------
>>> result = function_name([1, 2, 3])
>>> print(result['risk_score'])
15.3
Notes
-----
[重要注意事项、使用限制、已知问题]
References
----------
[1] Author (Year). Title. Journal. DOI.
"""
```
### 3.3 行内注释规范
```python
# ✅ 好的注释 — 解释"为什么"
# 本福特定律只适用于跨数量级的数据，pH值（0-14）不适用
if value_range < 10:
return skip_benford()
# ❌ 差的注释 — 重复代码
# 计算平均值
mean = sum(values) / len(values)
# ✅ 好的注释 — 标注算法来源
# MAD 阈值参考 Nigrini (2012), Table 7.1
# Close conformity: MAD < 0.006
MAD_THRESHOLD_CLOSE = 0.006
```
---
## 4. 错误处理与边界条件
### 4.1 标准错误返回
```python
# 数据不足
if len(values) < MIN_REQUIRED:
return {
'status': 'insufficient_data',
'message': f'数据量不足（仅{len(values)}个），需要至少{MIN_REQUIRED}个',
'n_valid': len(values)
}
# 输入格式错误
if not valid_input:
return {
'status': 'error',
'message': f'无效输入: {error_detail}'
}
```
### 4.2 边界条件处理
| 场景 | 处理方式 |
|------|----------|
| 全部值为0 | 跳过本福特检测（返回 status='not_applicable'） |
| 无小数部分 | 跳过小数位检测 |
| 仅1列数值 | 跳过固定关系检测 |
| 图片目录为空 | 返回 insufficient_data |
| 极端离群值 | 不剔除，但在 notes 中标注 |
| NaN/无效值 | 静默跳过，在 n_valid 中反映 |
---
## 5. 风险评分算法详解
### 5.1 单模块评分
```python
"""
风险评分映射逻辑（以末位数字检测为例）：
p >= 0.05 → risk_score = 40 * (1 - p) ∈ [0, ~38] → "low"
0.01 <= p < 0.05 → risk_score = 40 + ... ∈ [40, 60] → "medium"
0.001 <= p < 0.01 → risk_score = 60 + ... ∈ [60, 80] → "medium-high"
p < 0.001 → risk_score = 80 + ... ∈ [80, 100] → "high"
设计考量：
- 不直接使用 1-p 作为分数（会导致 p=0.04 和 p=0.06 差距过小）
- 分段线性映射，确保跨越统计显著性阈值时有明显跳变
- 上限 100 永远不精确达到（留有余地表示"不确定性"）
"""
```
### 5.2 综合评分算法
```python
"""
综合评分 = 0.6 × max(各模块分数) + 0.4 × mean(各模块分数)
设计理由：
- 加权最大值确保"只要有一个模块高度异常，综合分就不会太低"
- 加权平均确保"如果多个模块都略有异常，综合分会累积上升"
- 0.6/0.4 比例经验性确定，偏向保守（避免漏检重于避免误报）
特殊规则：
- 如果固定关系检测发现 is_exact=True，直接 risk_score = max(score, 90)
- 如果图像检测发现 similarity > 0.98，直接 risk_score = max(score, 90)
"""
```
---
## 6. 测试用例规范
### 6.1 单元测试结构
```python
# tests/test_modules.py
"""
测试策略：
1. 已知正常数据 → 应返回 low risk
2. 已知造假数据 → 应返回 high risk
3. 边界条件 → 应优雅处理
4. 回归测试 → 固定输入，固定输出
"""
def test_last_digit_uniform_data():
"""均匀分布数据应返回低风险"""
import random
random.seed(42)
values = [str(random.uniform(1, 100)) for _ in range(100)]
result = last_digit_test(values)
assert result['risk_level'] == 'low'
assert result['risk_score'] < 30
def test_fixed_relation_exact_ratio():
"""精确固定比值应返回极高风险"""
col1 = [1.23, 2.34, 3.45, 4.56, 5.67]
col2 = [2.46, 4.68, 6.90, 9.12, 11.34] # 精确 ×2
result = fixed_relation_test(col1, col2)
assert result['risk_level'] == 'high'
assert result['risk_score'] >= 85
def test_grim_consistent():
"""合法均值应通过 GRIM"""
# n=20, 整数数据, mean=3.40 → sum=68 ✓
result = grim_test_single('3.40', 20, decimals=2)
assert result['consistent'] == True
def test_grim_inconsistent():
"""非法均值应失败"""
# n=20, 整数数据, mean=3.47 → sum=69.4 ✗
result = grim_test_single('3.47', 20, decimals=2)
assert result['consistent'] == False
```
---
## 7. AI Agent 集成注释
### 7.1 Prompt Engineering 标注
每个模块的 docstring 设计为可被 AI Agent 直接解析：
```python
"""
[AGENT_INSTRUCTION]
当用户要求检测数据造假时，按以下优先级选择模块：
1. 如果用户提供了两组"应该独立"的数据 → fixed_relation_test()
2. 如果数据跨越多个数量级 → benford_test()
3. 如果数据含小数 → decimal_consistency_test() + last_digit_test()
4. 如果用户提供了均值和样本量 → grim_test_single()
5. 如果有图片文件 → find_duplicates()
6. 一键全检 → geng_assess.py
[AGENT_OUTPUT_FORMAT]
向用户展示结果时，使用以下格式：
- 先给出综合评分和风险等级（一句话）
- 然后列出关键发现（使用 emoji 标注严重度）
- 最后给出建议行动（编号列表）
- 始终附上免责声明
"""
```
### 7.2 Tool Definition 标注
```python
"""
[TOOL_DEFINITION]
name: geng_fraud_detection
description: |
基于统计学原理检测学术论文数据是否存在造假迹象。
支持末位数字检测、本福特定律、GRIM测试、固定关系检测、
小数位一致性检测和图像重复检测。
灵感来源于2026年"耿同学讲故事"的技术流打假方法论。
input_schema:
type: object
properties:
data:
type: array
description: 数据行列表，或 CSV 文件路径
domain:
type: string
enum: [biomedical, chemistry, physics, social_science, clinical, general]
modules:
type: array
items:
type: string
enum: [last_digit, benford, grim, fixed_relation, decimal, image]
description: 指定运行哪些模块（默认全部）
output_schema:
type: object
properties:
overall_risk_score: {type: number, min: 0, max: 100}
overall_risk_level: {type: string}
findings: {type: array, items: {type: string}}
recommendations: {type: array, items: {type: string}}
"""
```
---
## 8. 性能与限制
### 8.1 时间复杂度
| 模块 | 时间复杂度 | 1000行数据耗时 |
|------|-----------|---------------|
| last_digit_test | O(n) | <10ms |
| benford_test | O(n) | <10ms |
| grim_test_batch | O(k) per item | <1ms/item |
| fixed_relation_test | O(n) per pair | <10ms |
| decimal_consistency_test | O(n) | <20ms |
| image_duplicate_test | O(m²) m=图片数 | ~1s/100张 |
| geng_assess (综合) | O(n × c²) c=列数 | <500ms |
### 8.2 已知限制
| 限制 | 影响 | 缓解方案 |
|------|------|----------|
| 数据量<30时统计效力低 | 本福特检测可能不准 | 自动标注 "统计效力有限" |
| 不支持时间序列自相关 | 遗漏趋势数据伪造 | v1.1 计划增加 |
| 固定关系仅检测两列 | 三列以上复杂关系漏检 | 通过两两组合覆盖 |
| 图像检测仅用全局特征 | 局部篡改可能漏检 | v1.2 计划增加分块检测 |
| 无法检测"高明造假" | 统计上完美的伪造数据 | 无银弹，需多维度交叉 |
---
*Geng Skill v1.0.0 — 代码注释与架构标准化文档*

294
tools/gengskill/docs/DATA_SOURCES.md Normal file
View File

@ -0,0 +1,294 @@
# 📚 数据来源与参考文献标准化文档
> Geng Skill v1.0.0 — 学术数据打假检测工具
---
## 1. 方法论来源
### 1.1 直接灵感来源
| 来源 | 描述 | 时间 |
|------|------|------|
| **耿同学讲故事** (B站/抖音科普博主) | 吉林大学生物学硕士、北航博士五年级退学。2026年4月起连续举报多所985高校教授论文造假，核心方法：末位数字集中度检测、固定差值/比例关系检测、AI图片查重 | 2026-04 至今 |
| **澎湃新闻评论** | 《学术打假需要"耿同学"，更需要长效机制建设》— 详述耿同学方法论 | 2026-05-16 |
| **虎嗅网** | 《我Skill化了耿同学的"学术打假方法论"，致敬》— 方法论结构化梳理 | 2026-05-08 |
### 1.2 耿同学核心方法总结
```
┌────────────────────────────────────────────────────────────────┐
│ 耿同学打假方法论（从公开报道中提取） │
├────────────────────────────────────────────────────────────────┤
│ 1. 末位数字集中度 — 某些数字出现频率异常高 │
│ 2. 两列数据间固定差值/比例 — 不同组数据存在恒定数学关系 │
│ 3. 小数点后位数高度一致 — 编造数据的小数位呈现不自然规律 │
│ 4. AI图片查重 — 同一图片在不同实验条件下重复使用 │
│ 5. 从PDF/Source Data/图片/表格多维度扒取证据 │
│ 6. 卡方检验等统计学方法验证异常的显著性 │
└────────────────────────────────────────────────────────────────┘
```
---
## 2. 统计学理论基础
### 2.1 本福特定律 (Benford's Law)
| 字段 | 内容 |
|------|------|
| **原始论文** | Benford, F. (1938). The law of anomalous numbers. *Proceedings of the American Philosophical Society*, 78(4), 551-572. |
| **数学表述** | P(d) = log₁₀(1 + 1/d), d ∈ {1,2,...,9} |
| **适用条件** | 数据跨越多个数量级（至少1个）；数据量≥100为佳 |
| **不适用场景** | 范围有限的数据（百分比、pH值）；人为截断的数据 |
| **权威教材** | Nigrini, M.J. (2012). *Benford's Law: Applications for Forensic Accounting, Auditing, and Fraud Detection*. Wiley. ISBN: 978-1118152850 |
| **审计应用** | 美国注册欺诈审查师协会(ACFE)推荐用于财务审计 |
| **学术验证** | Diekmann, A. (2007). Not the first digit! Using Benford's law to detect fraudulent scientific data. *Journal of Applied Statistics*, 34(3), 321-329. |
### 2.2 GRIM 测试 (Granularity-Related Inconsistency of Means)
| 字段 | 内容 |
|------|------|
| **原始论文** | Brown, N.J.L., & Heathers, J.A.J. (2017). The GRIM Test: A Simple Technique Detects Numerous Anomalies in the Reporting of Results in Psychology. *Social Psychological and Personality Science*, 8(4), 363-369. DOI: 10.1177/1948550616673876 |
| **数学原理** | 对于整数取值数据，样本量为n时，合法均值只能是 k/n 形式（k为整数） |
| **适用条件** | 离散整数取值数据（李克特量表、计数数据） |
| **扩展** | SPRITE (Sample Parameter Reconstruction via Iterative TEchniques) — 更完整的数据重构验证 |
| **参考** | Heathers, J.A.J., et al. (2018). SPRITE: A Response to Anaya's Critique. DOI: 10.31234/osf.io/qfk7d |
### 2.3 末位数字均匀分布检验
| 字段 | 内容 |
|------|------|
| **理论基础** | 连续测量数据在足够精度下，末位数字应服从离散均匀分布 U(0,9) |
| **检验方法** | 皮尔逊卡方检验 (Pearson's chi-squared test), df=9 |
| **参考文献** | Mosimann, J.E., et al. (2002). Terminal digits and the examination of questioned data. *Accountability in Research*, 9(2), 75-92. |
| **典型案例** | Hill, T.P. (1998). The first digit phenomenon. *American Scientist*, 86, 358-363. |
### 2.4 图像重复检测
| 字段 | 内容 |
|------|------|
| **里程碑论文** | Bik, E.M., Casadevall, A., & Fang, F.C. (2016). The prevalence of inappropriate image duplication in biomedical research publications. *mBio*, 7(3), e00809-16. DOI: 10.1128/mBio.00809-16 |
| **发现** | 分析20,621篇论文，3.8%存在图片问题 |
| **技术方法** | 感知哈希(pHash)、差异哈希(dHash)、结构相似性(SSIM) |
| **工具参考** | ImageTwin, Proofig, STM Integrity Hub |
### 2.5 数据一致性综合检验
| 字段 | 内容 |
|------|------|
| **中文权威** | 余菁, 邬加佳, 孙慧兰等 (2021). 科技论文数据造假的核查策略和统计学方法验证. *中国科技期刊研究*, 32(6), 770-776. DOI: 10.11946/cjstp.202012221043 |
| **方法体系** | t检验、F检验、卡方检验、生存分析一致性 |
| **国际标准** | COPE (Committee on Publication Ethics) Guidelines on Research Data |
---
## 3. 检测模块与理论对应关系
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 模块名称 │ 理论基础 │ 统计方法 │ 适用领域 │
├─────────────────────────────────────────────────────────────────────────────┤
│ Last Digit Test │ 末位均匀分布 │ χ² 检验 │ 全领域 │
│ Benford's Law Test │ 本福特定律 │ χ² + MAD │ 跨数量级 │
│ GRIM Test │ 离散粒度一致性 │ 整除验证 │ 社科/量表 │
│ Fixed Relation Test │ 独立性原理 │ 比值/回归 │ 全领域(核心) │
│ Decimal Consistency │ 随机性原理 │ 自相关+χ² │ 全领域 │
│ Image Duplication │ 唯一性原理 │ 哈希+SSIM │ 生物医学 │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 4. 已验证的真实案例
### 4.1 耿同学举报案例（2026年，已被机构确认）
| 案例 | 机构 | 期刊 | 问题类型 | 结果 |
|------|------|------|----------|------|
| 王平团队 | 同济大学生科院 | *Nature* | 系统性数据造假（固定数学关系、图片重复） | ✅ 确认，院长免职，第一作者解聘 |
| 陈佺团队 | 南开大学生科院 | *Nature* 子刊 | 数据异常 | 🔄 调查中 |
| 上海大学案例 | 上海大学 | — | 数据异常 | 🔄 调查中 |
| 中山大学案例 | 中山大学 | — | 数据异常 | 🔄 调查中 |
### 4.2 国际经典案例
| 案例 | 方法 | 年份 |
|------|------|------|
| Diederik Stapel (社会心理学) | GRIM + 统计不一致性 | 2011 |
| Paolo Macchiarini (再生医学) | 图像重复 + 数据伪造 | 2016 |
| Hwang Woo-suk (干细胞) | 图像篡改检测 | 2005 |
| Jan Hendrik Schön (物理) | 数据重复模式 | 2002 |
---
## 5. 数据标准与输入规范
### 5.1 CSV 输入格式标准
```
编码: UTF-8 (支持 UTF-8-BOM)
分隔符: 逗号 (默认), 可配置为 TAB/分号
表头: 必须有列名作为第一行
数值: 支持整数、小数、科学计数法
缺失值: 空字符串 (跳过处理)
```
**标准示例：**
```csv
sample_id,group,value,measurement,timepoint
1,control,2.34,12.5,0
2,control,3.12,15.8,0
3,treatment,4.68,25.0,24
```
### 5.2 GRIM 批量输入 JSON 格式
```json
[
{
"label": "Table 1, Row 1",
"mean": "3.47",
"n": 25,
"decimals": 2,
"scale_min": 1,
"scale_max": 5
},
{
"label": "Table 1, Row 2",
"mean": "4.12",
"n": 30,
"decimals": 2,
"scale_min": 1,
"scale_max": 5
}
]
```
### 5.3 图像输入规范
```
支持格式: PNG, JPG, JPEG, TIF, TIFF, BMP, GIF
最小尺寸: 32×32 像素
推荐: 原始分辨率（不要人为缩放）
组织方式: 所有待比较图片放在同一目录下
```
---
## 6. 输出标准化
### 6.1 JSON 输出 Schema
所有模块遵循统一输出结构：
```json
{
"$schema": "geng-skill-output-v1",
"test_name": "string — 模块名称（中英双语）",
"status": "enum: completed | insufficient_data | error",
"n_values": "integer — 有效数据点数",
"risk_level": "enum: low | medium | medium-high | high",
"risk_score": "number 0-100 — 风险评分",
"p_value": "number — 统计检验p值（如适用）",
"interpretation": "string — 中文可读解释（含emoji状态标识）",
"...": "模块特定字段"
}
```
### 6.2 风险评分映射标准
| p-value 范围 | 风险等级 | 评分范围 | 颜色代码 | 建议动作 |
|-------------|----------|----------|----------|----------|
| p > 0.05 | low | 0-25 | 🟢 #00C853 | 无需干预 |
| 0.01 < p ≤ 0.05 | medium | 26-50 | 🟡 #FFD600 | 人工复核 |
| 0.001 < p ≤ 0.01 | medium-high | 51-75 | 🟠 #FF6D00 | 深入调查 |
| p ≤ 0.001 | high | 76-100 | 🔴 #D50000 | 正式举报 |
### 6.3 Markdown 报告标准
综合报告遵循以下结构：
```markdown
# 📋 Geng 学术数据打假检测报告
## 📊 综合评估结果（表格）
## 📝 结论（一段话）
## 💡 建议（编号列表）
## 🔬 各模块检测详情
### Module N: 模块名称
## ⚠️ 重要声明
```
---
## 7. 学术伦理与法律合规
### 7.1 合规框架
| 标准/规范 | 发布机构 | 相关性 |
|-----------|----------|--------|
| COPE Retraction Guidelines | 出版伦理委员会 | 论文撤稿/更正流程 |
| 科研诚信案件调查处理规则 | 中国科技部 (2019) | 国内学术不端处理 |
| ORI Research Integrity Guidelines | 美国研究诚信办公室 | 国际标准 |
| Singapore Statement | 全球科研诚信大会 | 负责任研究行为 |
### 7.2 使用伦理准则
1. **比例原则** — 检测强度应与嫌疑程度成正比
2. **无罪推定** — 异常 ≠ 造假，需完整证据链
3. **保密义务** — 未经确认的检测结果不应公开传播
4. **正式渠道** — 确认后应通过机构/期刊正式途径举报
5. **避免伤害** — 不应基于工具结果对个人进行网络攻击
### 7.3 免责声明
```
本工具仅提供统计学层面的异常筛查功能，输出结果为"疑点线索"而非
"造假定论"。使用者应当理解：
- 统计异常可能有合理解释（仪器精度、数据处理等）
- 本工具不具备法律效力
- 最终判定需要领域专家、原始数据核查和正式调查程序
- 使用者需自行承担因不当使用造成的后果
```
---
## 8. 版本与更新日志
### v1.0.0 (2026-05-20)
- 初始发布
- 6个核心检测模块
- 综合评估引擎
- 多平台使用指南
- 标准化输出格式
### 路线图
| 版本 | 计划功能 |
|------|----------|
| v1.1 | 增加 SPRITE 测试、生存数据一致性检验 |
| v1.2 | 支持 Excel 直接输入、PDF 表格自动提取 |
| v1.3 | Web UI 界面、RESTful API |
| v2.0 | AI 增强检测（LLM 辅助判断上下文合理性） |
---
## 9. 引用本工具
如果在学术工作中使用了本工具，请引用：
```bibtex
@software{geng_skill_2026,
title = {Geng Skill: Academic Data Fraud Detection Toolkit},
author = {Contributors},
year = {2026},
url = {https://github.com/YOUR_USERNAME/geng-skill},
version = {1.0.0},
note = {Inspired by the methodology of "Geng Tongxue" (耿同学讲故事)}
}
```
---
*Geng Skill — 让学术回归诚信，让数据说出真相。*

258
tools/gengskill/docs/EXAMPLE_WALKTHROUGH.md Normal file
View File

@ -0,0 +1,258 @@
# 🧪 完整示例：从数据到报告的端到端演示
> 本文档通过一个完整的假数据检测案例，演示 Geng Skill 的全部使用流程。
---
## 场景设定
假设你在审阅一篇生物医学论文，论文声称：
> "我们分别对小鼠进行了 Control、Treatment A、Treatment B 三组实验处理，
> 测量了各组的蛋白表达水平（相对定量）。结果显示 Treatment A 和 Treatment B
> 均显著提高了蛋白表达水平。"
论文提供了以下数据（摘自 Supplementary Table 1）：
```csv
sample_id,control_group,treatment_a,treatment_b,measurement
1,2.34,4.68,7.02,12.5
2,3.12,6.24,9.36,15.8
3,1.87,3.74,5.61,8.9
4,4.56,9.12,13.68,22.1
5,2.98,5.96,8.94,14.3
6,3.45,6.90,10.35,17.2
7,1.23,2.46,3.69,6.8
8,5.67,11.34,17.01,28.4
9,2.01,4.02,6.03,10.1
10,3.89,7.78,11.67,19.5
11,4.12,8.24,12.36,20.8
12,1.56,3.12,4.68,7.9
13,2.78,5.56,8.34,13.6
14,3.34,6.68,10.02,16.7
15,4.90,9.80,14.70,24.5
16,1.45,2.90,4.35,7.2
17,2.67,5.34,8.01,13.1
18,3.56,7.12,10.68,17.8
19,4.23,8.46,12.69,21.2
20,1.89,3.78,5.67,9.4
```
---
## 步骤 1：初步目视检查
一位细心的审稿人可能注意到：
- Treatment A 的数值似乎都是 Control 的两倍
- Treatment B 的数值似乎都是 Control 的三倍
但仅凭目测无法确认。让我们用 Geng Skill 做系统化检测。
---
## 步骤 2：运行检测
### 2.1 命令行一键检测
```bash
cd geng-skill/scripts
python3 geng_assess.py \
--input ../examples/fake_data_demo.csv \
--domain biomedical \
--output ../report/
```
### 2.2 Python API 方式
```python
import sys
sys.path.insert(0, 'scripts')
from last_digit_test import last_digit_test
from fixed_relation_test import fixed_relation_test
import csv
# 加载数据
with open('examples/fake_data_demo.csv') as f:
rows = list(csv.DictReader(f))
control = [float(r['control_group']) for r in rows]
treat_a = [float(r['treatment_a']) for r in rows]
treat_b = [float(r['treatment_b']) for r in rows]
# 运行固定关系检测
result = fixed_relation_test(control, treat_a, 'Control', 'Treatment A')
print(f"风险评分: {result['risk_score']}/100")
print(f"解释: {result['interpretation']}")
```
---
## 步骤 3：检测结果详解
### Module 1: 末位数字检测
```
┌────────────────────────────────────────────────────────────────┐
│ 检测列: control_group │
│ 末位数字分布: {0:0, 1:1, 2:2, 3:2, 4:2, 5:2, 6:3, 7:3, 8:2, 9:3} │
│ χ² = 4.00, p = 0.9114 │
│ 结果: ✅ 正常 — 末位数字分布与均匀分布无显著差异 │
│ 风险评分: 3.5/100 │
└────────────────────────────────────────────────────────────────┘
```
**解读**：造假者在编造 Control 组数据时，末位数字分布还算随机。这说明末位数字检测并非万能——它无法检测"有一定水平"的造假。
```
┌────────────────────────────────────────────────────────────────┐
│ 检测列: treatment_a │
│ χ² = 21.00, p = 0.0127 │
│ 结果: ⚠️ 异常 — 末位数字分布存在偏离 │
│ 风险评分: 47.5/100 │
└────────────────────────────────────────────────────────────────┘
```
**解读**：Treatment A 的末位数字分布出现异常。这是因为 Control × 2 导致了末位数字的非均匀映射（如原数 .34 × 2 = .68，原数 .56 × 2 = .12）。
---
### Module 4: 固定关系检测 ⭐（核心发现）
```
┌────────────────────────────────────────────────────────────────┐
│ 检测对: Control vs Treatment A │
│ │
│ 固定比值检测: │
│ mean_ratio = 2.000000 │
│ std_ratio = 0.000000 │
│ → 🔴 完美固定比值！所有数据点 Treatment_A = Control × 2 │
│ │
│ 线性关系检测: │
│ R² = 1.0000000000 │
│ slope = 2.0000 │
│ intercept = 0.000000 │
│ → 🔴 完美线性关系，零残差 │
│ │
│ 风险评分: 95/100 — 极高风险 │
└────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ 检测对: Control vs Treatment B │
│ │
│ 固定比值检测: │
│ mean_ratio = 3.000000 │
│ std_ratio = 0.000000 │
│ → 🔴 完美固定比值！所有数据点 Treatment_B = Control × 3 │
│ │
│ 风险评分: 95/100 — 极高风险 │
└────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ 检测对: Treatment A vs Treatment B │
│ │
│ 固定比值检测: │
│ mean_ratio = 1.500000 │
│ std_ratio = 0.000000 │
│ → 🔴 完美固定比值！Treatment_B = Treatment_A × 1.5 │
│ │
│ 风险评分: 95/100 — 极高风险 │
└────────────────────────────────────────────────────────────────┘
```
**解读**：这是最致命的发现。三组"独立实验"数据之间存在精确的整数倍关系：
- Treatment A = Control × 2.000（精确到小数点后所有位）
- Treatment B = Control × 3.000（精确到小数点后所有位）
- Treatment B = Treatment A × 1.500（精确到小数点后所有位）
**在真实生物实验中，这种完美的整数倍关系概率趋近于零。** 即使药物真的将蛋白表达提高了2倍，每个样本的响应也会有生物学变异（个体差异、实验误差等），绝不可能所有20个样本都精确地是2.000倍。
---
### 综合评估
```
╔══════════════════════════════════════════════════════════════════╗
║ 📋 综合评估结果 ║
╠══════════════════════════════════════════════════════════════════╣
║ ║
║ 🔴 综合风险评分: 92/100 — 极高风险 ║
║ ║
║ 核心证据: ║
║ • 三组"独立实验"数据存在精确整数倍关系（×2, ×3, ×1.5） ║
║ • R² = 1.0，残差为零 ║
║ • Treatment A 末位数字分布异常（p = 0.013） ║
║ ║
║ 结论: 数据极大概率为从单一数据源（Control组）通过简单 ║
║ 乘法运算生成，而非独立实验获得。 ║
║ ║
╚══════════════════════════════════════════════════════════════════╝
```
---
## 步骤 4：与正常数据对比
对 `real_data_demo.csv`（模拟的正常实验数据）运行同样的检测：
```
检测结果:
• 末位数字: ✅ 所有列 p > 0.05
• 本福特定律: ✅ 符合
• 固定关系: ✅ 无固定比值/差值（ratio_std > 1.5）
• 小数位一致性: ✅ 模式多样
综合风险评分: 8/100 — 🟢 低风险
```
---
## 步骤 5：生成正式报告
运行完成后，`report/` 目录包含：
```
report/
├── geng_assessment_report.json # 机器可读完整报告
└── geng_assessment_report.md # 人类可读 Markdown 报告
```
报告可直接用于：
- 向期刊提交 Letter of Concern
- 向机构科研诚信办公室提供技术证据
- 审稿意见中引用具体检测结果
---
## 关键教训
| 教训 | 说明 |
|------|------|
| **单一检测不足以定论** | 末位数字检测对 Control 组未报警，但固定关系检测精准命中 |
| **多模块交叉验证更可靠** | 末位异常 + 固定比值 + 完美线性 = 综合证据链 |
| **异常不等于造假** | 需要排除合理解释（如数据预处理中的标准化操作） |
| **上下文很重要** | 同样的"固定比值"在"原始数据 vs 标准化后数据"场景中是正常的 |
| **工具是辅助，人是决策者** | 最终判断需要领域专家结合实验设计做出 |
---
## 对审稿人/研究者的实用建议
### 何时应该怀疑数据？
1. ✋ 不同实验组数据太"干净"——没有离群值、没有异常
2. ✋ 多组数据的 error bar 高度一致
3. ✋ 不同条件下的重复次数完全一致
4. ✋ 数据点"太完美"地落在预期曲线上
5. ✋ 补充材料中的原始数据与正文图表不匹配
### 何时应该运行 Geng Skill？
1. 📊 审阅高利害关系的论文（顶刊/基金/职称）
2. 📊 收到学术不端举报后需要技术验证
3. 📊 对自己团队数据做"造假预防"自查
4. 📊 期刊编辑部建立投稿数据审查流程
---
*Geng Skill v1.0.0 — 完整示例演示*

654
tools/gengskill/docs/USAGE_GUIDE.md Normal file
View File

@ -0,0 +1,654 @@
# 📖 Geng Skill 多平台使用指南
> 本文档详细说明 Geng Skill 在各主流 AI 编程助手和开发环境中的使用方法。
---
## 目录
1. [通用命令行使用](#1-通用命令行使用)
2. [在 Claude (Anthropic) 中使用](#2-在-claude-anthropic-中使用)
3. [在 Cursor 中使用](#3-在-cursor-中使用)
4. [在 ChatGPT / GPT-4 中使用](#4-在-chatgpt--gpt-4-中使用)
5. [在 OpenAI Codex / API 中使用](#5-在-openai-codex--api-中使用)
6. [在 GitHub Copilot 中使用](#6-在-github-copilot-中使用)
7. [在 Jupyter Notebook 中使用](#7-在-jupyter-notebook-中使用)
8. [作为 Python 库导入使用](#8-作为-python-库导入使用)
9. [CI/CD 自动化集成](#9-cicd-自动化集成)
---
## 1. 通用命令行使用
### 1.1 安装
```bash
# 克隆仓库
git clone https://github.com/YOUR_USERNAME/geng-skill.git
cd geng-skill
# 安装依赖
pip install -r requirements.txt
```
### 1.2 一键综合检测
```bash
cd scripts
python3 geng_assess.py \
--input ../examples/fake_data_demo.csv \
--domain biomedical \
--output ../report/
```
**参数说明：**
| 参数 | 必填 | 说明 | 可选值 |
|------|------|------|--------|
| `--input` / `-i` | ✅ | 输入 CSV 文件路径 | 任意 .csv 文件 |
| `--domain` | ❌ | 研究领域（影响检测策略） | `biomedical`, `chemistry`, `physics`, `social_science`, `clinical`, `general` |
| `--output` / `-o` | ❌ | 输出报告目录 | 默认 `./report` |
| `--delimiter` / `-d` | ❌ | CSV 分隔符 | 默认 `,` |
### 1.3 单项检测
```bash
# 末位数字检测
python3 last_digit_test.py -i data.csv -c "column_name" -o result.json
# 本福特定律检测
python3 benford_test.py -i data.csv -c "measurement" -o result.json
# GRIM 测试（单个均值）
python3 grim_test.py --mean 3.47 --n 25 --scale "1-5" --decimals 2
# GRIM 测试（批量，从 JSON）
python3 grim_test.py -i batch_means.json -o grim_results.json
# 固定关系检测
python3 fixed_relation_test.py -i data.csv --col1 "group_a" --col2 "group_b"
# 小数位一致性检测
python3 decimal_consistency_test.py -i data.csv -c "value"
# 图像重复检测
python3 image_duplicate_test.py -i ./figures/ -t 0.85
```
### 1.4 输出格式
所有模块输出标准 JSON 格式，包含以下统一字段：
```json
{
"test_name": "检测模块名称（中英文）",
"status": "completed | insufficient_data | error",
"risk_level": "low | medium | medium-high | high",
"risk_score": 0-100,
"interpretation": "中文可读解释",
"...": "模块特定字段"
}
```
---
## 2. 在 Claude (Anthropic) 中使用
### 2.1 Claude Web / Claude Pro
**方法 A：直接粘贴数据让 Claude 分析**
```
我有以下实验数据，请用"耿同学"的方法帮我检查是否存在数据造假迹象：
sample,control,treatment_a,treatment_b
1,2.34,4.68,7.02
2,3.12,6.24,9.36
3,1.87,3.74,5.61
...
请检查：
1. 末位数字分布是否均匀
2. 各组数据之间是否存在固定比值或差值关系
3. 小数位模式是否异常
```
**方法 B：上传 CSV 文件让 Claude 用代码分析**
```
请帮我运行学术数据打假检测。我上传的 CSV 文件包含论文中的实验数据。
请用以下方法逐一检测：
- Last Digit Test（末位数字检测）
- Benford's Law Test（本福特定律检测）
- Fixed Relationship Detection（固定关系检测）
- Decimal Consistency Test（小数位一致性检测）
最后给出综合风险评分和建议。
```
### 2.2 Claude API (Artifacts / Tool Use)
```python
import anthropic
client = anthropic.Anthropic()
# 将 Geng Skill 的 SKILL.md 作为 system prompt
with open('SKILL.md', 'r') as f:
skill_doc = f.read()
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=4096,
system=f"你是学术数据打假助手。请严格按照以下 Skill 文档执行检测：\n\n{skill_doc}",
messages=[{
"role": "user",
"content": "请对以下数据执行完整的 Geng 打假检测...[数据]"
}]
)
```
### 2.3 Claude MCP (Model Context Protocol)
将 Geng Skill 注册为 MCP Server：
```json
// claude_desktop_config.json
{
"mcpServers": {
"geng-skill": {
"command": "python3",
"args": ["/path/to/geng-skill/scripts/mcp_server.py"],
"env": {}
}
}
}
```
---
## 3. 在 Cursor 中使用
### 3.1 作为 Cursor Rules 使用
在项目根目录创建 `.cursor/rules/geng-skill.mdc`：
```markdown
---
description: 学术数据打假检测工具
globs: ["*.csv", "*.xlsx", "data/**"]
alwaysApply: false
---
# Geng Skill — 学术数据打假检测
当用户要求检测数据是否造假时，按以下步骤执行：
1. 确认数据格式（CSV/Excel/直接粘贴）
2. 识别数值列
3. 对每个数值列执行：
- 末位数字检测（卡方检验 vs 均匀分布）
- 本福特定律检测（适用于跨数量级数据）
- 小数位一致性检测
4. 对数值列两两执行：
- 固定关系检测（差值/比值/线性）
5. 综合评分（0-100）并给出建议
核心原则：自然数据具有随机性，人为编造的数据会呈现不自然的规律性。
```
### 3.2 在 Cursor Chat 中使用
```
@geng-skill 请检测这份数据文件 data/experiment_results.csv 是否存在造假迹象
重点关注：
- 不同实验组之间是否有固定数学关系
- 末位数字分布是否正常
- 小数位模式是否异常
```
### 3.3 Cursor Composer 自动化
在 Cursor Composer 中直接引用脚本：
```
请运行 geng-skill/scripts/geng_assess.py 对 data/paper_results.csv 进行检测，
领域设为 biomedical，输出到 report/ 目录。
然后帮我解读报告中的关键发现。
```
---
## 4. 在 ChatGPT / GPT-4 中使用
### 4.1 ChatGPT Web (Code Interpreter / Advanced Data Analysis)
**步骤：**
1. 上传 CSV 数据文件
2. 同时上传 `scripts/` 目录下的 Python 脚本
3. 提示词：
```
我上传了一组学术论文数据和几个检测脚本。请按照以下步骤执行学术数据打假检测：
1. 先读取 CSV 数据，识别所有数值列
2. 对每个数值列运行 last_digit_test.py 中的 last_digit_test() 函数
3. 对适用的列运行 benford_test.py 中的 benford_test() 函数
4. 对所有数值列对运行 fixed_relation_test.py 中的 fixed_relation_test() 函数
5. 对每个数值列运行 decimal_consistency_test.py 中的 decimal_consistency_test() 函数
最后综合所有结果，给出：
- 综合风险评分（0-100）
- 关键发现（哪些数据可疑，为什么）
- 建议行动
```
### 4.2 GPT-4 API + Function Calling
```python
import openai
import json
# 定义 Geng Skill 工具
tools = [
{
"type": "function",
"function": {
"name": "geng_last_digit_test",
"description": "检测数据末位数字是否偏离均匀分布。自然数据末位应均匀分布，造假数据往往集中在某些数字。",
"parameters": {
"type": "object",
"properties": {
"values": {
"type": "array",
"items": {"type": "string"},
"description": "待检测的数值列表（字符串形式保留精度）"
},
"method": {
"type": "string",
"enum": ["all_digits", "decimal_last"],
"description": "检测方法"
}
},
"required": ["values"]
}
}
},
{
"type": "function",
"function": {
"name": "geng_fixed_relation_test",
"description": "检测两组数据间是否存在固定差值、比值或完美线性关系。独立实验数据不应有精确数学关系。",
"parameters": {
"type": "object",
"properties": {
"col1": {"type": "array", "items": {"type": "number"}, "description": "第一列数据"},
"col2": {"type": "array", "items": {"type": "number"}, "description": "第二列数据"},
"col1_name": {"type": "string"},
"col2_name": {"type": "string"}
},
"required": ["col1", "col2"]
}
}
},
{
"type": "function",
"function": {
"name": "geng_benford_test",
"description": "检测数据首位数字是否符合本福特定律。适用于跨多个数量级的自然数据。",
"parameters": {
"type": "object",
"properties": {
"values": {"type": "array", "items": {"type": "string"}, "description": "数值列表"}
},
"required": ["values"]
}
}
}
]
# 调用 GPT-4 带工具
response = openai.chat.completions.create(
model="gpt-4",
messages=[
{"role": "system", "content": "你是学术数据打假助手，使用 Geng Skill 检测论文数据。"},
{"role": "user", "content": "请检测以下数据..."}
],
tools=tools,
tool_choice="auto"
)
```
### 4.3 Custom GPT (GPTs Store)
创建自定义 GPT，在 Instructions 中粘贴完整的 `SKILL.md` 内容，并上传所有脚本文件作为 Knowledge。
**GPT 名称建议**: "学术数据卫士 — Geng Fraud Detector"
**Instructions 要点**：
```
你是基于"耿同学"方法论的学术数据打假检测 GPT。
当用户上传数据或粘贴数据时，自动执行以下检测流程...
```
---
## 5. 在 OpenAI Codex / API 中使用
### 5.1 Codex CLI
```bash
# 安装 Codex CLI
npm install -g @openai/codex
# 使用 Geng Skill 检测数据
codex "请对 data.csv 文件运行学术数据打假检测：\
1. 读取所有数值列 \
2. 检测末位数字分布 \
3. 检测列间固定关系 \
4. 给出风险评分" \
--file data.csv \
--file scripts/last_digit_test.py \
--file scripts/fixed_relation_test.py
```
### 5.2 Codex 作为自动化 Agent
```python
# codex_geng_agent.py
"""
将 Geng Skill 封装为 Codex Agent 可调用的工具链
"""
import subprocess
import json
def run_geng_assessment(csv_path, domain="general"):
"""调用 Geng 综合评估引擎"""
result = subprocess.run(
["python3", "scripts/geng_assess.py",
"--input", csv_path,
"--domain", domain,
"--output", "./report/"],
capture_output=True, text=True
)
# 读取报告
with open("./report/geng_assessment_report.json", "r") as f:
report = json.load(f)
return report
```
---
## 6. 在 GitHub Copilot 中使用
### 6.1 Copilot Chat in VS Code
在 VS Code 中打开数据文件，然后使用 Copilot Chat：
```
@workspace /explain 请分析 data.csv 中的数据是否存在学术造假迹象，
使用 geng-skill/scripts/ 中的检测模块
```
### 6.2 Copilot in Terminal
```bash
# GitHub Copilot CLI
gh copilot suggest "run geng academic fraud detection on experiment_data.csv"
```
### 6.3 作为 GitHub Action
```yaml
# .github/workflows/geng-check.yml
name: Academic Data Integrity Check
on:
pull_request:
paths:
- 'data/**/*.csv'
jobs:
geng-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.10'
- name: Install dependencies
run: pip install -r geng-skill/requirements.txt
- name: Run Geng Assessment
run: |
cd geng-skill/scripts
for csv_file in $(find ../../data -name "*.csv"); do
echo "🔍 Checking: $csv_file"
python3 geng_assess.py -i "$csv_file" -o ../../report/
done
- name: Upload Report
uses: actions/upload-artifact@v4
with:
name: geng-report
path: report/
```
---
## 7. 在 Jupyter Notebook 中使用
```python
# Cell 1: 安装与导入
!pip install numpy scipy Pillow scikit-image -q
import sys
sys.path.insert(0, '../scripts')
from last_digit_test import last_digit_test
from benford_test import benford_test
from fixed_relation_test import fixed_relation_test
from decimal_consistency_test import decimal_consistency_test
from grim_test import grim_test_single, grim_test_batch
import pandas as pd
import json
# Cell 2: 加载数据
df = pd.read_csv('../examples/fake_data_demo.csv')
print(f"数据形状: {df.shape}")
df.head()
# Cell 3: 末位数字检测
result = last_digit_test(df['control_group'].astype(str).tolist())
print(json.dumps(result, ensure_ascii=False, indent=2))
# Cell 4: 固定关系检测
result = fixed_relation_test(
df['control_group'].tolist(),
df['treatment_a'].tolist(),
'control_group', 'treatment_a'
)
print(f"🎯 风险评分: {result['risk_score']}/100")
print(f"📝 {result['interpretation']}")
# Cell 5: 可视化
import matplotlib.pyplot as plt
import numpy as np
fig, axes = plt.subplots(1, 3, figsize=(15, 4))
# 散点图：展示固定比值关系
axes[0].scatter(df['control_group'], df['treatment_a'], c='red', alpha=0.7)
axes[0].set_xlabel('Control Group')
axes[0].set_ylabel('Treatment A')
axes[0].set_title('⚠️ 完美 2x 关系')
axes[0].plot([0, 6], [0, 12], 'k--', alpha=0.3)
# 末位数字分布
from collections import Counter
digits = [int(str(v)[-1]) for v in df['control_group'].astype(str)]
counts = Counter(digits)
axes[1].bar(range(10), [counts.get(i, 0) for i in range(10)])
axes[1].axhline(y=len(digits)/10, color='r', linestyle='--', label='期望值')
axes[1].set_xlabel('末位数字')
axes[1].set_ylabel('频次')
axes[1].set_title('末位数字分布')
axes[1].legend()
# 比值分布
ratios = df['treatment_a'] / df['control_group']
axes[2].hist(ratios, bins=20, edgecolor='black')
axes[2].set_xlabel('Treatment_A / Control')
axes[2].set_ylabel('频次')
axes[2].set_title(f'⚠️ 比值全部 = {ratios.mean():.1f}')
plt.tight_layout()
plt.savefig('../report/detection_visualization.png', dpi=150)
plt.show()
```
---
## 8. 作为 Python 库导入使用
### 8.1 基础用法
```python
import sys
sys.path.insert(0, '/path/to/geng-skill/scripts')
from last_digit_test import last_digit_test
from benford_test import benford_test
from fixed_relation_test import fixed_relation_test
from decimal_consistency_test import decimal_consistency_test
from grim_test import grim_test_single
# 单列检测
values = ['2.34', '3.12', '1.87', '4.56', '2.98']
result = last_digit_test(values)
print(f"风险评分: {result['risk_score']}")
# 两列关系检测
col_a = [2.34, 3.12, 1.87, 4.56, 2.98]
col_b = [4.68, 6.24, 3.74, 9.12, 5.96]
result = fixed_relation_test(col_a, col_b, 'GroupA', 'GroupB')
print(f"风险等级: {result['risk_level']}")
# GRIM 测试
result = grim_test_single(mean='3.47', n=25, decimals=2, scale_min=1, scale_max=5)
print(f"一致性: {result['consistent']}")
```
### 8.2 批量处理多篇论文
```python
import os
import glob
import json
from geng_assess import run_assessment
# 批量检测目录下所有 CSV
csv_files = glob.glob('/path/to/papers/*/data.csv')
results = []
for csv_path in csv_files:
paper_name = os.path.basename(os.path.dirname(csv_path))
report = run_assessment(csv_path, domain='biomedical')
results.append({
'paper': paper_name,
'score': report['summary']['overall_risk_score'],
'level': report['summary']['overall_risk_level']
})
print(f" {paper_name}: {report['summary']['overall_risk_level_cn']}")
# 排序输出高风险论文
results.sort(key=lambda x: x['score'], reverse=True)
print("\n🔴 高风险论文：")
for r in results:
if r['score'] >= 50:
print(f" [{r['score']:.0f}] {r['paper']}")
```
---
## 9. CI/CD 自动化集成
### 9.1 Pre-commit Hook
```yaml
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: geng-data-check
name: Geng Academic Data Check
entry: python3 geng-skill/scripts/geng_assess.py
language: python
files: '\.csv$'
args: ['--input']
```
### 9.2 Docker 容器化
```dockerfile
# Dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY scripts/ ./scripts/
COPY SKILL.md .
ENTRYPOINT ["python3", "scripts/geng_assess.py"]
CMD ["--help"]
```
```bash
# 构建与运行
docker build -t geng-skill .
docker run -v $(pwd)/data:/data geng-skill -i /data/paper.csv -o /data/report/
```
---
## 常见问题
### Q: 数据量有什么要求？
| 检测模块 | 最小数据量 | 推荐数据量 |
|----------|-----------|-----------|
| 末位数字检测 | 10 | 50+ |
| 本福特定律 | 30 | 100+ |
| GRIM 测试 | 1（单项） | N/A |
| 固定关系检测 | 5对 | 20+ 对 |
| 小数位一致性 | 5 | 30+ |
| 图像重复 | 2张 | 10+ 张 |
### Q: 支持什么输入格式？
- ✅ CSV（默认逗号分隔，可指定其他分隔符）
- ✅ 直接传入数值列表（Python API）
- ✅ JSON（GRIM 批量测试）
- ✅ 图片目录（PNG/JPG/TIF/BMP）
- ❌ Excel（需先转 CSV）
- ❌ PDF（需先提取数据表格）
### Q: 如何降低误报率？
1. 确认数据范围是否适合该检测（如本福特需跨数量级）
2. 多模块交叉验证，不要仅凭单一结果下结论
3. 考虑合理解释：仪器精度限制、数据预处理步骤等
4. 结果需领域专家复核
---
*Geng Skill v1.0.0 — 致敬"耿同学讲故事"*