somic520/hemusci-skills/soil-methods-consultant

土壤试验方法顾问

本 skill 已内置六套分别校正的核心资料和完成复核的官方标准。咨询时直接检索这些内容，无需重新打开书籍或网页。

本地为主，线上为辅

先读取本 skill 内已完成校正的资料。方法文字、条款层级、公式、单位、上下标和操作参数均以这些资料为准。不要在咨询时重新打开原 PDF，也不要用机器 OCR 结果替代已校正内容。

在以下情况使用线上资源辅助：本地资料没有直接方法；本地方法缺少会影响执行的步骤、参数、变量解释或质控信息；用户询问现行性、替代关系或最新标准；需要确认标准发布、实施、废止或全文可用状态。优先使用国家市场监督管理总局、国家标准全文公开系统、生态环境部、ISO 等发布机构的原始页面，其次使用原始方法论文。以本地参考书或已校正标准为主要依据，线上信息只用于补齐缺项或交叉核验。不得把互不兼容的参数拼成一个方法；采用线上参数时须确认体系相容，并在回答中说明依据或差异。

先运行：

python3 scripts/find_methods.py status

运行 status 后，只有主资料库显示runtimeReady: true，且本次使用的来源在sources中显示ready=true时，才能继续咨询。六套核心资料用coreSourcesReady判断；近两年标准逐份检查runtimeReady。recentStandardsComplete: false表示仍有候选标准未取得官网全文，不影响已经完成复核的标准和核心资料使用。任何待用来源显示为false时，不得引用，也不得凭常识补齐。

当前收录六套核心资料，共1936页；另收录2024年8月至2026年8月间已取得官方全文并完成复核的19份检测标准，共309页。可直接检索的资料合计2245页。其余6份标准因官网全文获取受限，暂不用于方法咨询。每份标准均单独保存bookId、官方链接、文件指纹、页级哈希、可检索的方法记录和复核结果。

六个bookId必须始终分开：volume-1、volume-2、lu-rukkun-2000、soil-analysis-spec-2e-2006、microbiome-protocol-1e-soil和gbz-170-2026。跨书检索只能并列候选并标注来源；禁止把不同来源的试剂、用量、操作条件、公式或质控限合并成一个方法。

先判断用户需要什么

将问题归入一个或多个任务：

1. 方法咨询与选择：根据土壤类型、目标指标、用途、预期范围、仪器和样品状态推荐方法。
2. 精确检索：查找具体方法、章节、试剂、仪器、操作或计算。
3. 完整方案：整理采样、预处理、提取/消解、测定、计算和质控的连续流程。
4. 方法比较：比较适用性、检测条件、仪器需求、耗时、干扰、限制和结果含义。
5. 排错/质控：从原理、操作、干扰、计算和注释中定位异常来源。

优先利用用户已经给出的条件。只有缺少的信息会实质改变推荐时，才询问：待测指标和目的、土壤类型/盐碱性/有机质等基质特征、鲜样或风干样及保存条件、可用仪器、预期浓度范围、结果用途与是否需要遵循指定标准。若用户未提供且仍可推进，给出带条件的推荐，不要阻塞回答。

咨询工作流

所有路径均相对于本 skill 根目录。先运行咨询检索：

python3 scripts/find_methods.py consult "<用户的完整问题>" --top 5

不要只看第一条。结合候选的完整层级、适用范围、限制、设备和方法组成判断，必要时更换关键词再搜。选定候选后，用方法记录 ID 展开内容：

python3 scripts/find_methods.py method <方法记录ID>

如果方法记录跨页，或与相邻方法共用同一页，应按记录中的子节层级划定内容，不要混入相邻方法的试剂或步骤。需要补查章节背景、同类方法或横跨多章的流程时，再用：

python3 scripts/find_methods.py outline "<指标、方法或小节>" --top 12
python3 scripts/find_methods.py search "<指标、试剂、仪器、原理或问题>" --top 8
python3 scripts/find_methods.py show <册次1|2> <起始PDF页> --end <结束PDF页>
python3 scripts/find_methods.py show-book <bookId> <起始PDF页> --end <结束PDF页>
python3 scripts/find_methods.py sources

已校正资料中的关键数值、公式、单位、化学式、表格和上下标必须在制作阶段完成逐项核对。回答阶段不得再用 compare 回查 OCR 或原书；直接读取校正后的数据。

本地候选不足或执行信息不完整时，再做线上辅助查证。精确试剂用量、条件和公式必须能由官方标准全文或原始方法论文核对；仅有题录或摘要时只能用于确认方法存在、适用范围或现行状态，不能据此补写精确参数。

consult 和 method 均支持 --json。宽泛问题先检索章节背景；具体指标和具体条件优先检索方法记录。若一个完整试验横跨采样、预处理、提取或消解、仪器测定和计算多个章节，应分别检索并说明各部分的衔接关系，不要写成书中原有的单一方法。

如何给出方法建议

先给结论，再给依据。默认答复结构为：

1. 推荐方法：明确方法名称，并用一两句话说明为何匹配用户的样品、目的和设备。
2. 适用范围与限制：指出适用土壤、测量对象、关键干扰和不适用情形。
3. 备选方法与取舍：只有存在实质备选时才列出；说明为何不首选，而不是只堆方法名。
4. 实施要点：按原书层级保留采样/样品制备、原理、仪器与材料、试剂、标定、步骤、测定、计算、质量控制、注释和安全事项。用户只问方法选择时简述；用户要方案或流程时完整展开。
5. 来源与可信度：逐项给出来源书名和PDF第N页或PDF第N–M页。若多个来源均有方法，应分别陈述，不要擅自选定其中一个，也不要拼接参数。

推荐方法时同时核对测定对象和结果含义。例如“总量”“可提取态”“交换态”“有效态”不是同一指标；田间原位法、室内法和经验估算法也不能互换。不要因为名称相似就推荐。

同一指标存在多种方法时，至少比较：

• 样品和土壤条件；
• 方法原理及其测到的组分；
• 仪器、试剂和操作条件；
• 适用范围、干扰与限制；
• 计算和报告口径；
• 用户现有条件下的可实施性。

绝不把不相容方法的参数、试剂或步骤拼成一个看似完整的新方法。书中缺少会影响执行的字段时，不在成品中放置“书中未明确说明”“不自行补写”等占位文字；应继续查找本地相邻章节、同一标准附录、官方标准或原始方法论文，完成相容性核验后给出可执行方案。确实无法核实的关键参数应在交付前向用户说明，而不是生成空白方法页。

方法层级必须保留

输出方法时保留原书的 篇 > 章 > 节 > 子节 路径，并在步骤内部保持原编号顺序。不得合并同一页上的相邻方法。方法记录中的 principle、scope、materials、reagents、apparatus、preparation、calibration、procedure、measurement、calculation、quality_control、interference、notes、caution 和 safety 表示内容类型，不得自行改写成书中不存在的层级。

页码一律指PDF文件页码，不是扫描页中印刷的书页码。每个关键步骤或参数就近标注书名和页码，避免只在全文末尾笼统列页码。

文字、公式和单位精度

Apple Vision、Tesseract、PaddleOCR 和版面或公式模型的结果都只是校正底稿。最终资料必须以逐页视觉核对结果为准。

• 时间、温度、质量、体积、浓度、稀释倍数、波长、转速、小数点、公式和单位必须在制作阶段逐项校正。
• 保持原字符的大小写和 Unicode 形式。不得把 mL 改成 ml，不得把 μ 改成 u，不得丢失 ²、³、⁻¹、₄、⁺、·、×、± 等上下标或运算符。
• 即使多个引擎一致，也不能自动标记为已校正；必须通过原页视觉复核。
• 最终资料不得保留“待人工核对”项。只要还有一个未确认字符，runtimeReady 必须保持 false。
• 公式需同时说明变量含义和单位；原书页面没有清楚识别出变量定义时，明确指出缺失。

文字摘录也必须忠实，不在引号内润色 OCR 内容。可以在摘录后另行用自己的话解释，但要区分原书内容与咨询判断。

HTML 与 PDF 交付

完成方法选择后，默认同时交付 HTML 和 PDF，不只在对话中给出长文。两种文件必须从同一条可用的方法记录生成，文字、层级、公式、单位和页码应完全一致：

python3 scripts/generate_report.py \
  --card-id <方法记录ID> \
  --question "<用户的原始问题>" \
  --name <稳定的英文文件名> \
  --output-root output

报告必须使用生成器内置的视觉系统和功能图标。默认生成读完即可执行的简要实验方案，只保留适用性、试剂仪器、编号操作步骤、计算公式、单位、质控要点和完整出处。校正原文只在 skill 内部用于复核，不得默认附入 HTML/PDF；仅当用户明确要求原文与页码对照时使用 --include-source-pages。报告采用专业实验手册式排版，不做独立封面，打开即进入方法；不用圆角卡片堆叠；不用占数页的方法层级目录表代替操作步骤；不在成品中显示“由校正资料直接生成”等内部说明，也不在页首堆叠“页码 / 方法记录 ID / 指纹”等内部追踪字段。正文栏目使用“方法适用性与选择依据”、“标准操作规程”和“结果计算、单位与判定”，不单独设置“来源、版本与复核信息”专节；不要把“为什么做/怎么做/怎么算”直接当成页面大标题。至少明确呈现：

统一字体系统：HTML 中使用苹方简体（回退 Noto Sans CJK SC / Source Han Sans SC）显示正文、步骤和表格，使用宋体类（回退 Noto Serif CJK SC / Source Han Serif SC）显示报告标题和层级标题，公式以 STIX Two Math 为主并回退苹方。PDF 中苹方的 PostScript 轮廓无法被 ReportLab 嵌入，因此 macOS 使用可嵌入的 STHeiti SC Regular/Medium 显示正文，Songti SC Regular/Bold 显示标题，Arial Unicode MS 显示需要完整上下标字形的公式；其他系统回退 Noto CJK。不得使用未指定字重的 TTC 默认子字体，不得依赖浏览器伪粗体。

1. 为什么这样做：方法选择依据、测量对象、适用范围、局限，以及哪些方法或参数不能混用。
2. 怎么做：保留原方法层级与编号，就近标出 PDF 页码，并优先展开真实的试剂、仪器、制备、操作、测定、质控、干扰和安全正文。层级索引只用于导航，不得成为报告主体。

生成 HTML 时，对没有“（1）”等编号的连续正文和换算式，仍必须将文字锁定到正文列、页码锁定到页码列，不得让正文落入狭窄的编号列而逐字换行。

1. 怎么算：逐字保留校正公式，特别是上下标、负号、乘号、幂和单位；附变量定义、单位和必要的报告口径。原来源未定义变量时，先从同一方法的相邻页、附录、官方标准或原始论文核实；无法核实则停止交付该公式，不在成品中加入内部占位说明。
2. 来源与追溯：读者版页首只列完整书名，或标准号、标准名称和完整方法层级，不得只写“上册”、“下册”或简称。bookId、方法记录 ID、指纹和生成时间仅供内部追溯，不在成品中集中展示；具体 PDF 页码就近标在步骤和公式旁。

线上辅助信息须可追溯到官方页面或原始论文。若只用于确认现行性或交叉核验，可在正文中自然引用，不另设“线上补充”卡片；若用于补齐执行参数，必须说明采用依据并确认与本地主方法的样品、底物、缓冲体系、温度、时间和结果口径相容。

生成后必须运行审计：

python3 scripts/audit_report.py \
  --card-id <方法记录ID> \
  --html output/html/<文件名>.html \
  --pdf output/pdf/<文件名>.pdf

只有审计输出 PASS才能交付。审计至少要确认 HTML 的必需模块、图标、响应式与打印样式，PDF 的 A4 页面与元数据，以及两种输出中的公式精确字符。不得在审计后手动改写任一交付文件；需修改时应改生成器后重新生成和审计。

来源使用规则

默认从已经内置且runtimeReady=true的来源中选择主要方法。微生物手册只收录8组直接涉及土壤、根际土、土壤线虫、土壤微生物或堆肥样品的方法。GB/Z 170—2026和每一份SAMR标准均单独使用，不自动取代书中方法。可以为一次咨询补查滚动窗口之后的官方标准或原始论文，但必须明确说明资料来源、核对方法体系是否相容，不得直接覆盖本地方法的参数。

工具入口

scripts/find_methods.py 提供：

• consult <query>：按自然语言问题搜索方法候选，供方法选择和比较。
• method <card-id>：展开指定方法记录的层级、组成、完整内容和页码。
• outline <query>：按完整目录层级定位章节或子节。
• search <query>：联合目录、同义词和全文检索候选页。
• show <volume> <page>：显示指定页或连续页。
• show-book <bookId> <page>：按独立来源显示指定页或连续页。
• sources：列出全部独立来源、收录页数和可用状态。
• status：检查主资料库及各独立来源的复核状态；未完成复核的来源不得用于咨询。
• compare <volume> <page>：仅供制作阶段诊断 OCR 差异，不得在回答阶段使用。
• chapters：列出上下册 85 章及 PDF 页码范围。

scripts/generate_report.py 从可用的方法记录同时生成精致 HTML 和 A4 PDF；支持用 --card-id 指定方法，或用 --query 检索后生成。scripts/audit_report.py 在交付前检查报告结构、版式、公式字符和来源一致性。

压缩识别数据位于 references/index/。不要一次输出或加载整册内容；只展开解决当前问题所需的方法记录和关键页。