lucio911/Geotechnical-Research-Skills

岩土工程研究技能

validate-skills

面向有证据支撑、力学感知、定量可辩护的岩土工程研究推理 Agent 技能。

状态：v0.5.0 引文完整性核心（功能完备 PR）。本版本在 v0.4 定量核心的基础上，新增了参考文献身份验证、引文到论断的保真度审计、稿件/参考文献一致性检查、确定性的面向 CSL 的参考文献格式化，以及全参考文献列表的参考文献取证。该套件仍然与具体软件无关。

本项目为何存在

通用学术 Agent 可以生成流畅的文字，却会遗漏岩土工程研究中至关重要的科学失效模式：

- 将参数变化包装为科学新颖性；
- 未控制密度、饱和度、应力历史、排水条件、加载序列或尺度效应；
- 将重复循环或时间点计为独立重复；
- 原始数据被覆盖或排除标准未记录；
- 忽略传感器漂移、就位、饱和、同步或派生变量定义；
- 将 p 值视为工程重要性；
- 将 R² 视为模型充分性；
- 拟合参数不可辨识；
- 将针对拟合数据的校准改称为验证；
- 归一化变量的参考状态悄然改变；
- 将有量纲量直接放入指数/对数函数而未归一化；
- 有效应力、总应力、符号、度/弧度、kPa/MPa、mm/m 或百分比/小数歧义；
- 将等值线图视为定量证明；
- 在缺乏判别性证据的情况下将关联提升为机制或因果关系；
- 结论超出所测试的材料、应力路径、几何、尺度或加载范围。

规范链条现为：

问题 -> 空白 -> 假设 -> 实验/方法 -> 数据 -> 质量控制 -> 分析/校准 -> 结果 -> 力学 -> 论断 -> 图 -> 论文 -> 对抗性评审

范围边界

本仓库有意保持与具体软件无关。它可以对数值研究设计与验证进行推理，但不试图成为 Abaqus、PLAXIS、FLAC3D、OpenSees、MATLAB、Python、R 或电子表格的副驾驶。

无论证据来自室内试验、现场监测、数值分析、解析推导、概率分析还是文献，Research-Core 都应保持科学有效性。

v0.5 技能地图

| 技能 | 包 | 角色 |
|---|---|---|
| geotech-router | core | 路由到最小可辩护工作流 |
| geotech-project-ledger | core | 维护项目事实与来源 |
| geotech-evidence-ledger | evidence-core | 构建/审计类型化证据图 |
| geotech-literature-review | evidence-core | 面向证据的文献综合与矛盾映射 |
| geotech-paper-spine | evidence-core | 主要/支撑/边界主张架构与图表角色 |
| geotech-reference-verifier | citation-core | 验证存在性、身份、元数据漂移、标识符不匹配、重复及疑似伪造 |
| geotech-citation-fidelity | citation-core | 审计每条引用实例是否支持手稿中的确切主张（F0–F5） |
| geotech-bibliography-audit | citation-core | 检测悬空/孤立引用、重复作品/DOI 及 citekey 不一致 |
| geotech-reference-format | citation-core | 以确定性期刊/CSL 样式渲染经验证的规范元数据 |
| geotech-paper-reader | research-core | 可审计的岩土工程论文卡片 |
| geotech-gap-novelty | research-core | 压力测试真正的创新性，而非参数创新性 |
| geotech-theory-derivation | research-core | 理论/模型推导与状态变量审计 |
| geotech-result-to-claim | research-core | 控制证据到主张的强度 |
| geotech-pre-submission-reviewer | research-core | 对抗性多角色评审 |
| geotech-experiment-design | quantitative-core | 假设驱动的试验设计、对照、重复、混杂、尺度效应 |
| geotech-data-qc | quantitative-core | 原始数据溯源、传感器/表格 QC、排除与预处理审计 |
| geotech-statistics | quantitative-core | 试验单元、重复测量、不确定性、效应量与推断 |
| geotech-parameter-calibration | quantitative-core | 可识别性、目标函数、模型比较与独立验证 |
| geotech-unit-dimension-audit | quantitative-core | 单位、量纲、归一化、符号/应力约定与参考状态 |
| geotech-numerical-planner | methods | 求解器无关的数值研究/验证规划 |
| geotech-scientific-figure | communication | 证据驱动的科学图表架构 |

v0.5 中的变更

引用完整性现已成为独立的证据层

v0.5 将五个绝不应被合并的问题分开：

existence != identity != metadata != citation fidelity != formatting

- geotech-reference-verifier 验证参考文献是否存在，以及持久标识符是否解析到与手稿中所声称的同一作品。
- geotech-citation-fidelity 引入 CIT-### 引用实例及 F0–F5 支持等级。
- geotech-bibliography-audit 检查手稿/正文与参考文献之间的结构一致性。
- geotech-reference-format 保持元数据不可变，并将渲染委托给确定性的 CSL/参考文献处理器。

高风险记录，如 IDENTIFIER_MISMATCH、SUSPECTED_COMPOSITE 和 SUSPECTED_FABRICATION，绝不会被静默删除。

geotech-reference-verifier 包含一个可执行的在线解析器：

python skills/geotech-reference-verifier/scripts/resolve_reference.py \
--record reference-record.json \
--email researcher@example.org \
--use-openalex
它使用 Crossref/DataCite 公开元数据以及可选的 OpenAlex 交叉核对，但将检索与确定性身份评分分开。API 失败或无命中结果仍为 UNRESOLVED，绝不会自动成为伪造证据。

对于整篇参考文献的取证：

python skills/geotech-reference-verifier/scripts/audit_references.py references.bib \
--email researcher@example.org \
--use-openalex \
--output-json reference-integrity-report.json \
--output-md reference-integrity-report.md

批量审计使用有状态的 BibTeX 解析器、按参考文献缓存的解析结果、重复 DOI 检测、保守的近似重复标题筛查、撤稿标记，以及聚合的关键/人工复核操作。UNRESOLVED 和 AMBIGUOUS 仍为复核状态，而非自动的伪造发现。使用 --fail-on-critical 作为提交前/CI 门禁。

参见 docs/citation-integrity-core.md 和 examples/citation-integrity-workflow.md。

v0.4 定量核心保留

1. 实验设计变为主张区分设计

geotech-experiment-design 不从测试用例数量出发。它从以下内容出发：

claim -> primary hypothesis -> credible alternative -> controlled contrast -> observable -> decision rule

它明确审计材料状态、有效/总应力、排水、加载序列、模型尺度、仪器边界、真重复、伪重复以及测量分辨率。

2. 数据质量成为溯源的一部分

geotech-data-qc 使用不可变链条：

raw -> processed -> analysis-ready

每一次排除和转换都必须被记录。循环测试获得专门检查，涵盖就位、幅值/均值漂移、循环分段、不完整循环、相位/同步误差以及首循环参考定义。

包含一个轻量级结构检查器：

python skills/geotech-data-qc/scripts/audit_csv.py data.csv --time-column time

通过它并不能确立传感器或科学有效性。

3. 统计学现在从实验单元开始

geotech-statistics 强制区分试件与重复观测。一个试件进行 100 次循环并不是 n = 100 个独立试件。

推断阶梯为：

description -> uncertainty -> contrast -> association -> prediction -> mechanism

统计显著性与工程显著性分开报告。

4. 校准现在具有可识别性与泄漏门禁

geotech-parameter-calibration 要求：

- 明确的参数含义、单位、边界和敏感性；
- 目标函数定义；
- 在相关情况下进行重复起点/敏感性/参数相关性检查；
- 残差诊断；
- 简化模型与完整模型比较；
- 在提出预测性主张时进行独立验证；
- 校准/验证案例无重叠。
对于诸如 G/G0 = F(rp, Br)（其中 Br = h(rp)）的模型，该技能明确检验信息重叠，以及额外状态变量是否能改进独立预测。

审计校准清单：

python skills/geotech-parameter-calibration/scripts/audit_calibration_manifest.py \
skills/geotech-parameter-calibration/assets/calibration-manifest.example.json

5. 单位/量纲控制成为一等关卡

geotech-unit-dimension-audit 检查方程、表格、图表和参数定义。它特别防范：

- 带有量纲的 c x 的 exp(-c x)；
- Pa/kPa/MPa 和 N/kN 漂移；
- mm/m 以及小数/百分比应变漂移；
- 密度与重度；
- 有效应力与总应力；
- 度/弧度歧义；
- 参考状态未定义的归一化变量；
- 拟合常数在被称作无量纲的同时悄然携带单位。

审计变量登记表：

python skills/geotech-unit-dimension-audit/scripts/check_variable_register.py \
skills/geotech-unit-dimension-audit/assets/variable-register.example.json

截至 v0.5 的证据图扩展

v0.3 使用了诸如 MTH -> DAT -> RES -> CLM 的核心链条。v0.4 增加了显式的定量对象：

- QC-### — 数据质量评估；
- ANA-### — 统计/校准/定量分析；
- PAR-### — 参数集。

推荐的实验链条：

MTH -> DAT -> QC
|      |
v      v
ANA  RES
|
+----> PAR
|
+---- parameterizes-+

RES(validation) -> CLM

v0.5 还引入了 CIT-### 引用实例节点和 cited_as 边。引用到主张的边可以携带 fidelity_grade: F0–F5，与证据强度 E0–E5 分开。

示例：

python skills/geotech-evidence-ledger/scripts/validate_evidence_graph.py \
skills/geotech-evidence-ledger/assets/quantitative-evidence-graph.example.json

推荐的项目状态

.geotech/
├── project_truth.md
├── research_questions.md
├── literature_matrix.md
├── reference_verification.json
├── citation_map.json
├── experiment_register.md
├── method_register.md
├── parameter_register.md
├── variable_unit_register.json
├── qc_register.md
├── analysis_register.md
├── result_ledger.md
├── evidence_graph.json
├── manuscript_spine.md
├── figure_map.md
├── review_matrix.md
└── decision_log.md

推荐路线

实验研究

geotech-experiment-design -> geotech-data-qc -> geotech-unit-dimension-audit -> geotech-statistics / geotech-parameter-calibration -> geotech-result-to-claim -> geotech-evidence-ledger -> geotech-paper-spine

退化/本构模型开发

geotech-gap-novelty -> geotech-unit-dimension-audit -> geotech-theory-derivation -> geotech-parameter-calibration -> geotech-statistics -> geotech-result-to-claim -> geotech-evidence-ledger

现有数据集审计
geotech-data-qc -> geotech-unit-dimension-audit -> geotech-statistics -> geotech-result-to-claim

文献与新颖性

geotech-literature-review -> geotech-paper-reader -> geotech-gap-novelty -> geotech-evidence-ledger

参考文献与引用审计

geotech-bibliography-audit -> geotech-reference-verifier -> geotech-citation-fidelity -> geotech-reference-format -> geotech-evidence-ledger

仓库中编码的研究规则

1. 绝不伪造引用、标准、数据、方程、输出或验证证据。
2. 将实测值、推导值、标定值、假定值和引用值保留为不同的来源类别。
3. 保留单位、符号约定、应力度量、排水条件、材料状态、荷载路径和尺度。
4. 来自同一单元的重复观测不会因为数量众多而成为独立重复验证。
5. 不要从单一相关趋势推断机制。
6. 除非提取出可复现的度量指标，否则等值线图只是定性的。
7. 标定不是独立验证。
8. 统计显著性不是工程显著性。
9. 额外参数必须在物理上是必要的、可辨识的，或能改进独立预测。
10. 指数/对数函数的自变量必须是无量纲的。
11. 结论不得超出证据图中最强支持路径的范围。
12. 参考文献必须既真实，又适合其被引用处的确切论断。
13. NOT FOUND 不是伪造的证据；未解决或高风险的记录在删除或替换前需要明确审查。

本地验证

python scripts/validate_repo.py

当前发布门禁覆盖 21 项技能、所有先前的 v0.2–v0.4 研究/定量检查、Citation Integrity Core 检查、Evidence Graph 冒烟测试、标定/数据/单位负向测试、单参考文献解析器回归测试，以及全参考文献目录取证回归测试。

仓库布局

Geotechnical-Research-Skills/
├── README.md
├── CHANGELOG.md
├── registry.yaml
├── docs/
├── examples/
├── scripts/
├── tests/
└── skills/

贡献规则

仅当新技能引入了一项独特的科学推理能力或一个可复用的完整性门禁时，才应添加该技能。不要仅仅因为某个软件包流行就添加一个求解器封装。