audit-ml-pipeline

审计 ML Pipeline

对每个实验的 skore 报告进行易于阅读的叙述。# %% 文件是供人阅读的笔记本，不会执行。materialize.py 会在一次运行中写入摘要和 HTML 查看器。对 skore Project 进行只读操作。

面向用户的文案

详情：setup-workspace references/human_facing_prose.md。
审计 Markdown 和 # 注释描述的是这份报告的发现，而不是 skills 框架、CLI 或生成输出的命令。问题、回复和结束叙述使用相同的数据科学语言，而不使用 skill id、G-* 名称或封装 CLI。末尾的定位符 token 保留为索引字符串。不要在 audit/<stem>.py 中放入 API 教程、版本下限或定位符示例。`` 是站点标记。
编写提示应保留在此 skill 中。style 仅用于 ruff。

后续步骤指引

来源	审计后续步骤
model-ml-pipeline（实现循环）	→ 返回。此审计执行可能已生成笔记本。调用方会在 record-outcome 之前运行 python -m skore_skills loop notebooks --stem <stem>，将其作为新鲜度检查，然后构建站点并运行 git end-turn --stage implement。
用户自由文本（“audit 02”“re-audit 04”）	→ 展示指标，然后自行完成收尾（参见 § 回合结束）
重新运行现有实验	→ 重新执行现有审计文件；如果指标发生变化，则展示差异

实现循环会在 evaluate 之后、record-outcome 之前调度审计。摘要包含检查摘要和指标摘要。G-AUDIT-FINDING 是根据该摘要派生的独立规范化发现。manage-ml-backlog record-outcome 会使用这两者，且不会再次调度审计。

文件位置 — 可视化图示

路径	持久性	写入者	内容
audit/<NN>_<short_name>.py	持久（在 git 中）	此 skill，每个实验一次	仅包含裸表达式的单元格。事实来源。Agent 不会执行此文件。站点笔记本是此文件的输出为空的版本
scratch/audit/<stem>/audit.md	临时（已被 git 忽略）	materialize.py	检查项展示和指标数据框的 repr。audit finding 会解析此文件
scratch/results/<stem>/materialize.py	临时（已被 git 忽略）	Evaluate，来自 evaluate-ml-pipeline/templates/materialize.py	唯一调用 skore.evaluate 和 project.put 的文件。写入 report.html、report.txt、id.txt、checks.html、metrics.html 和 Method 查看器
scratch/results/<stem>/report.html report.txt locator.txt id.txt pipeline.svg pipeline/	临时（已被 git 忽略）	Evaluate materialize.py，随后 Agent 根据 id.txt 写入 locator.txt	完整报告查看器、文本回退、定位符、DataOp 图和报告
scratch/audit/<stem>/materialize.py	临时（已被 git 忽略）	此 skill，根据 templates/materialize.py 生成	重新打开报告。写入检查项、指标、audit.md 和额外查看器，以及 accessors.txt
scratch/audit/<stem>/accessors.txt	临时（已被 git 忽略）	materialize.py	help() 树。额外报告视图标签来自此处的 Displays 组，而不是笔记本
scratch/results/<stem>/checks.html metrics.html 及额外的 <slug>.html / .png	临时（已被 git 忽略）	materialize.py	站点在 ## Results 下嵌入的逐项查看器。摘要已包含文本，因此这里不会额外写入 .txt
执行摘要	从 CLI 输出或摘要路径捕获	CLI	流式输出或写入的摘要 — Agent 会直接读取

记忆要点： audit/ 是源文件（在 git 中）；scratch/audit/ 和 stdout 是输出。绝不要将 audit/<stem>.py 复制到 scratch/audit/ 下。materialize.py 是被 git 忽略的 Agent 脚本。绝不要提交 scratch/audit/ 下的任何内容。

只读约定

核心规则。以下「停止条件」中的第一条会说明这一点。

audit/<stem>.py 中允许的操作：

• skore.Project(...) — 打开此实验写入的项目。
• project.summarize() — 列出 (key, id) 对。
• project.get(id) — 按 id 加载指定报告。
• 所有 report.* 访问器。
• 从 <pkg> 导入内容（只读检查）。

audit/<stem>.py 中禁止的操作：

• skore.evaluate(...) — 会在相同的 key 下创建重复报告，并污染 summarize() 的结果。
• project.put(...) — 同上。
• 写入快照（使用 write_text 写入 HTML、locator.txt、report.txt），以及在 audit/<stem>.py 中使用 help() 循环。这些操作应放在 scratch/audit/<stem>/materialize.py 中，该文件可以写入 scratch/results/<stem>/ 和 accessors.txt。
• 写入 data/、reports/ 或 src/<pkg>/。审计笔记本是查看器。
• 对加载的 report 进行在单元格运行结束后仍然保留的修改（例如猴子补丁修改 skore 符号）。

运行器会将每个单元格的源代码、最后一个表达式的 repr 和标准输出写入摘要。禁止的调用会显示在摘要中（例如在后续 summarize() 单元格中显示为 put 行，或显示为 **error:** 部分）。此约定是可见的，而非隐形的。

同级只读使用方（输出形式不同，遵循相同规范）：scratch/<ts>_*.py 探查脚本。review-ml-experiment 会将摘要作为文本读取，不会打开 Project。有关使用方规则，请参阅 evaluate-ml-pipeline § 停止条件。

停止条件 — 请先阅读

• 设置仍在待处理。 首先运行 python -m skore_skills status。如果 status.setup.pending 不为空，且 status.skills.setup-ml-project 为 true，则加载 setup-ml-project 并停止。不要启动此技能。待其返回后再继续。本轮不要再次加载它。如果未安装此技能，用一行列出待处理事项，然后停止。不要臆造 git init、脚手架或 env init。如果 status.setup.env 或 status.setup.workspace 为 declined，用一行说明后停止。若 git 或 editable 被拒绝，则不再询问；继续。
• 没有报告 → 停止。 四项配对是硬性要求：运行 python -m skore_skills design consent --stem <stem>（ask / stop → 不要审计），并确保有 experiments/NN_*.py、smoke pytest 已通过，以及 Project 中该键下的报告。如果缺少报告，说明情况并停止。不要运行 skore.evaluate / project.put。转交给 evaluate-ml-pipeline 或 model-ml-pipeline。直接请求“审计 02”也使用同一门槛。
• 对 skore Project 只读。 参见 § 只读约定。审计文件中绝不要调用 skore.evaluate(...) 或 project.put(...)。
• project.get(...) 按 id 而非 key 查询。 对于 hub 模式，从 project.put() 打印的 URL 中读取 id：https://…/<workspace>/<project>/<type-plural>/<N> → id 为 skore:report:<type-singular>:<N>（URL 段为复数；id 使用单数——去掉末尾的 s，例如 cross-validations → cross-validation、estimators → estimator）。在审计文件中硬编码 REPORT_ID——无需遍历 summarize()。对于本地模式，从 project.summarize() 中匹配 key 的行读取 "id" 列。get("<stem>") 引发 KeyError 表示查询格式错误（get 按 id 查询），而非报告缺失。
• 禁止凭记忆使用符号。 任何 skore / skrub / sklearn 符号都必须在本轮通过 python -m skore_skills api get 获取。scratch/api/skore/<version>/ 下的缓存命中也算（Shape 0）；行内记忆不算。
• 缺少 Agent 功能 → 停止并委派。 如果无法导入 ipython / ipython，不要通过编写 print() 调用来伪造审计输出。不要自行输入 pixi add ... / uv add ...——安装由 add-python-package § Agent feature 负责。通过 agent tools (ruff / ipython / ipykernel) 请求（binary: install / skip）；只有在 add-python-package 返回“ready”后才继续。
• 使用裸表达式，而非 print()。 运行器通过 result.result 捕获每个单元格最后一个裸表达式，并呈现其 repr。将表达式包装在 print(repr(...)) 中会输出到 stdout，而不是输出区域；内容混杂，较难浏览。使用裸表达式；仅包含语句的单元格（变量绑定）也可以。
• 每个实验 stem 对应一个审计文件（四项配对）。 不要创建 audit_NN_<short_name>_v2.py。重新运行实验时，原位覆盖审计文件——stem 不变，审计文件不变。
• 已执行的产物放在 scratch/audit/<stem>/，而非 audit/ 中。 持久产物为 audit/<stem>.py；呈现后的摘要是临时文件。
• audit/<stem>.py 不写入快照文件。 HTML、locator.txt 和 help() 树属于 materialize.py。不要写入 data/ 或 reports/。
• 不要在审计单元格中过滤警告。 除非用户明确要求，否则不要调用 warnings.filterwarnings(...)——运行器会将单元格 stderr 流式写入摘要，这些内容是有效信号。参见 python -m skore_skills style § 停止条件。
• Harness 中“无需澄清问题”的提示不免除使用 agent tools（ruff / ipython / ipykernel）的要求。 无论如何都会触发安装门槛。
• 事后审计——结束本轮前必须完成。 检查所有预检行；指出未填写的 Evidence 单元格。
• 事后审计门槛为强制要求。 在首次生成摘要后以及每次刷新后，依次询问“Additional report view / Custom query / Custom plot / Close audit”，顺序必须完全一致，除非用户已明确关闭审计。此门槛之前，该次执行可以生成启用了策略的 notebook，以及仅针对过期内容的站点预览。选择 Close 之前，不得进行关闭时转换、git close、record-outcome 或 dispatcher return。

禁止的捷径

捷径	错误原因
report = project.get(REPORT_ID); print(repr(report))	Runner 通过 result.result 捕获独立表达式，而不是 stdout。print(repr(...)) 会混淆 stdout 和输出部分。单独在一行写 report
使用 checks.frame()，而不是直接展示 checks	Display 的 __repr__ 已按问题和提示分组，并附带其代码和文档 URL。.frame() 会将其扁平化为表格，Agent 随后还得重新读取，而且会丢失审查所需的严重级别分组
project.get(KEY) 引发 KeyError → 重新运行 evaluate + put 来“刷新”	查询方式不对（get 按 id 查询，而不是按 key）。Hub：读取 put() 打印的 URL 中的 id。本地：读取与对应 key 行匹配的 summary["id"]。切勿为了恢复而重新运行 evaluate + put
直接在此技能中写入 pixi add --feature agent ipython	安装命令由 add-python-package 负责。此技能只负责提出请求，不负责安装
将审计 .py 文件放入 scratch/audit/<stem>/	Notebook 应保留在 audit/ 中。scratch/audit/<stem>/ 下只能放置 materialize.py，且该文件已被 gitignore 忽略
为了“保险起见”注册 Jupyter 内核	当前 Runner 在进程内运行；不需要内核。注册会创建一个孤立的 kernelspec
添加会修改 data/ 或 reports/ 的修正单元格	审计文件为只读。状态变更应放在 scratch/<ts>_*.py 探测脚本或实验脚本中
未先读取 experiments/<stem>.py，就在 audit/<stem>.py 中替换 <SKORE_PROJECT_INIT>	审计必须打开同一个 Project。本轮务必读取 experiments/<stem>.py，并逐字节复制 Project 初始化代码块（格式调整除外）
Hub 模式：在 skore.Project(...) 之后调用 skore.login(mode="hub")	Project(...) 构造函数会在初始化时进行身份验证；若未先调用 login，就会失败。顺序固定：先 login，再 Project
实现循环审计 → 先写 scratch 探测脚本来“再次核对指标”	审计本身就是指标提取步骤。针对指标编写 scratch 探测脚本正是此调度流程要取代的反模式
在 audit/<stem>.py 中使用 write_text 或运行 help() 循环	Notebook 是供人查看的视图。将 templates/materialize.py 复制到 scratch/audit/<stem>/materialize.py，以生成 HTML、定位器文件和 accessors.txt

预检 — 在写入或执行任何审计文件之前输出

Pre-flight (audit-ml-pipeline):
- [ ] Experiment stem confirmed: <NN_short_name>
      Evidence: journal/NN_<short_name>.md exists AND state is approved
                | "n/a — user invoked re-audit on existing stem"
- [ ] Four-way pairing complete:
        journal/NN_<short_name>.md       — design note (state approved or done)
        experiments/NN_<short_name>.py   — script
        tests/smoke/test_NN_<short_name>.py — smoke test (passing)
        audit/NN_<short_name>.py         — about to be written / refreshed
      Evidence: ls / Glob on each path
- [ ] Report present in skore Project under key=<NN_short_name>
      Evidence: project.summarize() this turn; row with
                key == "<NN_short_name>" appears.
                "Run finished, put() landed" is NOT sufficient.
- [ ] Agent feature available:
        run `ipython -c "print(0)"` and `ipython --version`
        through the project's composed dev environment
      Evidence: tool output of each
                | JOURNAL.md Status `agent feature: installed`
                Missing → STOP, delegate to add-python-package agent tools (ruff / ipython / ipykernel)
- [ ] API CLI consulted for skore symbols used:
      Project, summarize, get, report.checks.summarize, report.metrics.summarize
      Evidence: Read scratch/api/skore/<version>/<topic>.md (this turn)
                | Write the same (this turn)
                | "n/a — cache hit, file already on disk + Read this turn"
- [ ] Template copy + substitution decided:
        <pkg> → package name from src/<pkg>/
        <NN>_<short_name> → experiment stem
        <SKORE_PROJECT_INIT> → literal block copied from experiments/<stem>.py
      Evidence: Read experiments/<stem>.py this turn for the Project init block;
                Read templates/audit.py this turn before Write audit/<stem>.py
- [ ] Read-only contract acknowledged: audit file contains
      summarize / get / report.* only — no evaluate, no put
      Evidence: explicit grep / Read confirmation of the drafted file
- [ ] Execution command shape confirmed:
        python scratch/audit/<stem>/materialize.py
        notebooks true: notebook fill audit/<stem>.py [--html]
      Evidence: command emitted in the response before running
- [ ] G-AUDIT-FINDING derived from the executed digest
      Evidence: issue/tip counts + ordered codes + optional metric
                context | explicit clean-checks value
- [ ] Post-audit gate answered: additional view | query | plot | close
- [ ] Pre-flight re-emitted with evidence before final message.
      Evidence: this checklist appears in the end-of-turn summary.

执行前

在满足四方配对、报告查询、Agent 功能和 API 检查要求后，立即在写入或运行 audit/<stem>.py 之前输出 1–3 句自然语言。说明这是本地只读报告物化，而不是重新训练：它会打开持久化的 Skore 报告，呈现检查 / 指标 / 可用视图，并将摘要写入 scratch/audit/<stem>/，同时将 HTML 查看器写入 scratch/results/<stem>/。写明与策略匹配的确切执行命令。

根据事实描述成本：报告加载和所请求视图的呈现，而不是模型拟合或完整交叉验证。除非已获得实测时长，否则应说明耗时取决于报告大小和所选视图，不要臆造分钟数。初次审计时输出一次此预览；只有当 Additional report view / Custom query / Custom plot 实质性改变工作内容时才刷新。运行会在现有的审计后关卡处暂停，然后结束。

关于报告含义的问题属于大模型叙述工作，需基于摘要进行解读。若某项检查触发，请阅读其文档 URL 并遵循该页面的建议。此类问题不调用 evaluate 或 put。若任何强制关卡尚未通过，可预览可能进行的审计，但不要写入或执行审计文件。

审计文件约定 — 概览

审计文件采用 jupytext 百分号格式（# %%）。文件名：audit/NN_<short_name>.py——其 stem 必须与实验完全一致。模板：templates/audit.py。

替换项

占位符	替换为
<pkg>	可导入的包名（来自 src/<pkg>/）
<NN>_<short_name>	实验名称主体（例如 02_target_transform）
<SKORE_PROJECT_INIT>	完整的 Project 初始化代码块（包括 hub 模式下任何前置的 skore.login(...) 调用），从 experiments/<stem>.py 原样复制，字节完全一致
<project-name>	experiments/<stem>.py 中的 name= 参数（请读取，不要自行编造）
<hub-workspace>	仅限 hub 模式。从 experiments/<stem>.py 中的 workspace= 参数复制
<REPORT_LOCATOR>	由 evaluate 传递的标准化 put 后定位符。如果缺失，则根据所选 id 和下方的后端规则推导；绝不要猜测 URL

<SKORE_PROJECT_INIT> 和 <project-name> 是最容易出错的替换项：审计必须打开与实验写入位置相同的 Project。务必在本轮读取 experiments/<stem>.py，提取原样的初始化代码块；绝不要仅凭对 skore mode: 决策的记忆重新构造。

单元格顺序（每个单元格的作用）

简要概述；含具体示例的完整结构说明 → references/cell_anatomy.md。

1. 模块文档字符串（Markdown 单元格） — 说明此文件的用途，以及只读规则。
2. 导入（代码单元格） — import skore、from <pkg> import ...。
3. 打开 Project（裸表达式单元格） — project = skore.Project(...)；然后单独写一行 project。
4. 列出报告 — summary = project.summarize()；然后写 summary。
5. 加载报告 — 根据 project.put() 打印的 URL 设置 REPORT_ID（hub："skore:report:<type-singular>:<N>" — URL 路径段为复数，id 使用单数，例如 cross-validations → cross-validation、estimators → estimator；local 和 mlflow：读取 summary["id"] 中匹配行的值），然后执行 report = project.get(REPORT_ID)，最后一个表达式写 report。不要在此单元格中写入 HTML 或 locator.txt。 materialize.py 会处理这些内容（使用 api get 确认 _repr_html_）。
6. 已持久化的报告 — 替换为 evaluate 中的确切标准化定位符。直接审计时，使用选定的 REPORT_ID 和 policy.skore_mode：local 链接使用 ../reports/；Hub 使用准确保存的 put URL（或明确标注的 Project 链接）； MLflow 使用生成的 run URL，或记录 tracking URI + experiment id + run id。如果没有权威定位符， 写 n/a — backend did not expose a locator。不要调用 put、检查私有存储或捏造前端 URL。
7. 检查项摘要 — checks = report.checks.summarize()，然后将 checks 作为最后一个表达式。materialize.py 会写入 checks.html。其 repr 会按严重程度对遍历结果分组；每一行 issue / tip 都以文档 URL 结尾。阅读该页面并应用其中的建议（自定义 CSTM* 检查项可能没有建议）。
8. 指标摘要 — metrics = report.metrics.summarize().frame(verbose_name=True, flat_index=False)， 然后将 metrics 作为最后一个表达式。materialize.py 会根据该 frame 写入 metrics.html。该 frame 是唯一的指标表。不要在设计说明中再次粘贴其值。
9. 可用的报告访问器 — 不是笔记本单元格。将 templates/materialize.py 复制到 scratch/audit/<stem>/materialize.py 并运行。它会对 report.metrics、report.checks 以及任何存在的其他命名空间（inspection、data 等）调用 help()，并将树写入 accessors.txt。help() 会打印其树并返回 None。 跳过不存在的命名空间。此处不要调用绘图访问器。不要将循环放入 audit/<stem>.py。

这是核心模板。将 checks 保留为裸 Display：编辑器会渲染 _repr_html_，运行器会记录 repr，而 .frame() 会丢弃严重程度分组。指标应使用上述 frame，而不是该 Display，也不要再建第二张 Markdown 表。只有在用户选择 Additional report view 后，才追加额外的 Display 单元格。详情：→ references/cell_anatomy.md。

摘要是评审的权威来源

review-ml-experiment 会读取渲染后的摘要 scratch/audit/<stem>/audit.md，并以此作为唯一事实来源，来编写 journal/ideas/<stem>-<slug>.md 和 journal/JOURNAL.md 中的一行 Ideas。该技能会将摘要作为文本读取，依次检查 ## Checks summary 中的 Issues: 和 Tips:，不会重新打开 Project、调用 report.*，也不会编写 scratch/<ts>_*.py 探查脚本来提取指标。 manage-ml-backlog 随后会对这些文件进行分类。晋升的想法会离开 Ideas 表，成为 Backlog 行。

此约定范围有限：持久化报告定位器 + 检查 + 指标摘要。评审不得遍历其他 Display 标题。 不要 将 ROC / 混淆矩阵 / 重要性单元格放入核心模板。Close-audit 额外内容之后，这些单元格使用各自的 ## <title> 标题。如果用户明确要求绘制 accessors.txt 未列出的自定义图形，则在编写单元格之前加载 plot-ml-figure（如果已安装）；切勿替换 skore Display。保存为 PNG（或 HTML），并让图形保持可见；切勿在审计笔记本中调用 plt.close。

G-AUDIT-FINDING

每次成功执行审计后，运行 python -m skore_skills audit finding --stem <stem>（或传入摘要路径）。粘贴 JSON finding，逐字照录。不要改写代码、计数或指标子句。摘要缺失时 → JSON finding 为 n/a — audit digest unavailable。

额外的 Display 单元格不会改变 G-AUDIT-FINDING（重新运行命令；它仍只读取检查 + 指标）。

逐字照录 G-AUDIT-FINDING，并附上摘要和通过 python -m skore_skills loop locator --stem <stem> 获取的 G-REPORT-LOCATOR。manage-ml-backlog 会将 finding 写入设计说明的 Status 区块。每次添加视图、查询或绘图后都要重新计算，因为摘要会被覆盖。

继续审计

初始摘要生成后以及每次成功刷新后，除非用户已表示要关闭，否则按以下确切顺序使用 AskUserQuestion 提出一个单选问题。不推荐或预选任何选项。

门控上下文。 提问前，用 2–4 行说明答案授权执行什么操作，以及依据哪些事实——从本轮摘要中原样引用（刚读取的检查项和指标、accessors.txt 中的 Display 名称）——并说明每个选项的作用。文件链接可以补充上下文，但不能代替上下文。

标签	约定
其他报告视图	菜单标签必须与本轮 help() 树中 scratch/audit/<stem>/accessors.txt 的 Displays 组下的名称完全一致。使用 python -m skore_skills api get 确认所选名称。列表取决于任务——回归报告没有 roc。树中未列出的内容一律省略；绝不显示记忆中的 Display 名称。编辑前先提出一个单选问题。
自定义查询	等待用户针对已加载报告提出一个具体的只读问题。仅在 audit/<stem>.py 和 materialize 的 <CALL> 块中追加回答问题所需的最少 accessor 单元格。若树中的名称能够回答问题，优先使用该名称。
自定义图表	仅当树中没有适用于此图表的 Display 时才使用。只有当 status.skills.plot-ml-figure 为 true 时才加载 plot-ml-figure；否则用一行说明跳过，并返回此门控问题。将只读图表追加到两个文件中。materialize.py 会将图保存到 scratch/results/<stem>/。
关闭审计	继续执行现有的已分派或直接关闭流程。

“其他报告视图”/“自定义查询”/“自定义图表”都会编辑同一个持久化文件 audit/<stem>.py，位于 ## Core audit complete 之后，并编辑 materialize.py 的 <CALL> 块。编辑后：运行 style，重新运行一次 materialize.py；启用 notebook 时运行 notebook fill；仅根据检查项和指标，使用 python -m skore_skills audit finding --stem <stem> 重新生成 G-AUDIT-FINDING；站点策略为 true 时运行 site build --if-stale，然后再次显示同一个门控问题。在关闭审计之前，不要运行关闭时的 loop notebooks，不要运行 git end-turn、record-outcome，也不要返回分派器。审计保持只读：不得调用 evaluate、put，也不得修改工作区数据。

额外的 Display 单元格

Slug = accessors.txt 中 Displays 下列出的 accessor 名称。不要凭对文档的记忆编造 slug。

1. Markdown 单元格 ## <human title>——不得使用 ## Checks summary 或 ## Metrics summary。
2. 代码单元格：调用 accessor；对返回的 Display 使用 api get 确认 _repr_html_。最后一个表达式必须是裸 Display。
3. 仅在 materialize.py 中将该 accessor 追加到 EXTRA。存在 _repr_html_() 时，将其写入 scratch/results/<stem>/<slug>.html。仅当不存在时，才保存 <slug>.png，以便站点仍能嵌入图表。重新运行 materialize.py。
4. 失败或不适用的 accessor 留在 scratch/ 探查结果中。不要为它们添加 Results 子章节。

manage-ml-backlog 会将每个额外的 <slug> 查看器（report、checks、metrics 除外）转换为一个 ### Results 标题，并根据生成该查看器的摘要单元格概述其内容。

执行约定 — 单次执行

首次针对某个 stem 执行前，运行 python -m skore_skills review consent --stem <stem>。

• stop — 指明缺失的 report.html 并停止。
• audit — 编写 audit/<stem>.py 并执行一次。 检查结果是否已与报告一起存储；本次读取会使用这些结果。
• proceed — 摘要已存在。除非用户明确要求重新审计，否则不要执行。重新审计会重复一次与策略匹配的执行。

将 templates/materialize.py 复制到 scratch/audit/<stem>/materialize.py， 替换 Project init、报告 id 和 locator，然后使用 env verify 中的 composed-dev Python 运行一次。该次运行会写入 HTML 查看器、accessors.txt 和 audit.md。不要对审计文件运行 cells run，也不要对它运行 notebook convert。 当 policy.notebooks 为 true 时，运行：

python -m skore_skills notebook fill audit/<stem>.py [--html]

仅当 site 也为 true 时才添加 --html。Fill 会写入不含输出的 notebook，且不会写入摘要。当 notebooks 为 null 或 false 时，不要更改策略，也不要 fill。然后运行：

python -m skore_skills audit finding --stem <stem>

notebook 不包含 materialize 写入的内容。如果 site 策略为 true 且已安装 export-ml-site，则在 materialize 之后、该门控之前运行 python -m skore_skills site build --if-stale。如果运行了构建，请说明网站已更新，并逐字粘贴该输出中的 file:// 行。不要提及设计说明 markdown 或 html/<stem>.html。

逐字粘贴 JSON finding。阅读 audit.md；不要从 notebook 推导内容。

已执行的 notebook

当 notebook 策略为 true 时，上述 notebook fill 会负责直接和分发路径上的无输出 notebook。调用方运行 python -m skore_skills loop notebooks --stem <stem>，并遵守 convert：通过 fill，而非通过内核执行。仅提及 notebook fill 并不算完成。当前源指纹会使该门控跳过；源发生变化时则会再次 fill，作为安全保障。

直接结束时，在 record-outcome 之前运行 § End of turn 中的 notebook 门控。审计没有自己的页面。如果该文件存在，site build 会在设计说明的 ## Notebooks 部分中、评估 notebook 之后嵌入 audit/<stem>.nb.html。不要添加 ``。标记不会创建查看器，而缺少 .nb.html 则会将其省略。

重新执行语义

• 重新运行实验（在同一 key 下覆盖 put()） → 重新执行匹配的审计文件。manage-ml-backlog § 4 会在每次 record-outcome 时触发此操作。
• 编辑审计文件的源代码（添加指标 accessor）→ 重新执行。摘要可重新生成。
• scratch/audit/<stem>/ 会在每次执行时被覆盖。没有 版本历史；源 .py + git 历史就是审计轨迹。

四方 stem 配对规则

将 setup-workspace 的配对规则从三个制品扩展为 四个：

journal/NN_<short_name>.md           — design note
experiments/NN_<short_name>.py       — script
tests/smoke/test_NN_<short_name>.py  — smoke test
audit/NN_<short_name>.py             — audit  ← this skill

stem 相同，一对一。当实验在 journal/JOURNAL.md 中显示为 done 时，四个制品都已存在。

分发路径

调用来源

调用方	时机
review-ml-experiment	review consent 为 audit 时，在 idea 文件之前
model-ml-pipeline	不加载此技能；它会加载 review-ml-experiment
evaluate-ml-pipeline	独立 evaluate 可在结束前运行审计
用户自由文本	“audit experiment 02”、“show me what 03”、“re-audit 04”——直接解析

调用

被调用方	原因
python -m skore_skills audit finding	审计执行后。原样粘贴 JSON finding
python -m skore_skills loop locator	从 locator.txt 或审计文件中获取 G-REPORT-LOCATOR
python -m skore_skills loop artifacts	直接审计收尾：在笔记本检查关卡前执行 record
python -m skore_skills loop notebooks	在 record-outcome 前执行。遵循 convert；skip 会继续
add-python-package	缺少 ipython 时
manage-ml-backlog（record-outcome 模式）	直接自由文本审计的回合结束时——移交摘要，以便写入 History 行和设计说明的 Status 块
python -m skore_skills style	编写或编辑 audit/<stem>.py 后——打包的 ruff.toml 为 audit/** 设置了逐文件忽略项。仅运行 Ruff；不会重写注释。不要在审计文件中编写工作流／流程说明

回合结束

已分派（本回合执行了 model-ml-pipeline、evaluate-ml-pipeline 或 manage-ml-backlog），在 Close audit 之后：运行 python -m skore_skills audit finding --stem <stem> 和 python -m skore_skills loop locator --stem <stem>。将摘要、JSON finding、JSON locator 以及可选的标题返回给调用方。停止。不要运行 record-outcome、收尾时的 loop notebooks、另一次站点构建、git end-turn，也不要在此处进行分流。上文的实时执行/预览不会重复。当调用方是 model-ml-pipeline 或 evaluate-ml-pipeline 时，告知它运行 python -m skore_skills loop notebooks --stem <stem>，并在 record-outcome 前遵循 convert 执行 notebook fill。即使结果为 skip，这道关卡也会继续。record 指的是 loop artifacts，不是笔记本关卡。之后运行 site build，以及该调用方的 git end-turn（model 使用 --stage implement，evaluate 使用 --stage evaluate）。列出 fill 命令不等于完成收尾。仅填充审计文件并不能完成该收尾。不要把直接审计的收尾流程粘贴成分派方将要执行的预览。

**直接自由文本审计，在 Close audit 之后：**此技能负责收尾。不要在 Close audit 之前启动。先运行 python -m skore_skills loop artifacts --stem <stem>（预期结果为 record）。record 是该命令的操作，不是笔记本关卡。然后按以下顺序执行。不要调整顺序。 loop notebooks 仅在结果为 skip 时继续。

1. python -m skore_skills loop notebooks --stem <stem>。以 JSON action 为准。action 为 convert 时，不要运行 record-outcome、site build 或 git end-turn。 not_evaluated 不会触发转换。
2. 结果为 convert 时，对每个 experiments/ 或 audit/ 源文件运行 notebook fill，当 html 为 true 时加上 --html。不要对这些文件运行 notebook convert。fill 不会执行 put。只有当编写当前产物的那次运行之后，该人工调用发生变化时，才先重新运行对应的 materialize.py。重复步骤 1，直到 action 为 skip。缺少 jupytext / nbformat → 用一行说明跳过并注明 add-python-package；不要让审计失败，也不要运行 pixi add。
3. 仅当 status.skills.manage-ml-backlog 为 true 时，以 record-outcome mode 加载 manage-ml-backlog，并提供摘要、G-AUDIT-FINDING 和该 locator。缺少该技能 → 用一行说明跳过；不要在此处写入 History。该模式会记录并返回；不会重新分派此技能。smoke 未通过时，绝不要标记为 done。
4. 仅当 policy.site 为 true 且已安装 export-ml-site 时运行 site build： python -m skore_skills site build --if-stale。如果报错提示需要 mkdocs-material，为 Agent 加载 add-python-package 以安装 mkdocs-material，然后再构建一次。不要运行 pixi add / uv add。说明构建错误；不要让审计失败。
5. 面向用户的收尾。根据 Checks + Metrics 撰写 2–6 句话。不要编造指标，也不要粘贴摘要。步骤 4 成功时，说明网站已更新，并逐字粘贴该输出中的 file:// 行。不要提及 html/<stem>.html 或 journal/<stem>.md。未构建站点时，不要声称网站已更新，也不要提及 markdown。接着逐字粘贴步骤 2 的 JSON locator（本地环境：还要附上绝对路径 reports/），然后附上 G-AUDIT-FINDING。索引字符串，不要写叙述。 分派的审计不会生成此消息。
6. python -m skore_skills git end-turn --stage evaluate。该审计会继续 evaluate 阶段；没有 audit 阶段。如果 JSON action 为 invoke，仅当 status.skills.persist-ml-git 为 true 时加载 persist-ml-git，然后停止；该技能会返回分流。如果缺少 persist，注明待处理的 staged 路径并停止。否则，仅当 status.skills.triage-ml-task 为 true 时加载 triage-ml-task；否则停止。此技能中不要运行 git commit。

故障模式与恢复

快速查阅；详细恢复步骤见 references/failure_modes.md。

症状	原因	修复方法
project.get(key) 引发 KeyError / TypeError	按 key 而非 id 查找；本地模式与 Hub 模式的结构不同	→ references/failure_modes.md § "project.get(key) raises"
ModuleNotFoundError: No module named 'IPython'	未安装 Agent 功能	委派给 add-python-package；此处绝不要运行 pip install
单元格渲染为 <Display object at 0x…>	skore 版本太旧，无法为 Display 提供文本表示	仅在该单元格添加 .frame()；其余部分保持原样
report.* 访问器引发 AttributeError	凭记忆使用了符号；skore 版本有变	→ references/failure_modes.md § "AttributeError"
RuntimeError: No report under key=...	put() 写入了另一个 Project	→ references/failure_modes.md § "wrong Project"
源代码未变，但不同运行的报告有所不同	步骤不确定 / 数据切片不同	这不是此处的 bug；告知用户
Hub 模式：skore.login() 身份验证错误	Token 已过期 / 首次登录	→ references/failure_modes.md § "skore.login fails"
Hub 模式：TypeError: workspace 关键字参数错误	Hub 形式中残留了本地模式的关键字参数	→ references/failure_modes.md § "TypeError workspace"
Hub 模式：put() 后 summarize() 中缺少报告	Hub 工作区错误，或没有读取权限	→ references/failure_modes.md § "report missing"

此技能不做什么

• 打开或写入 skore Project 的报告（evaluate-ml-pipeline）。
• 安装 ipython（由 add-python-package 负责）。
• 写入 journal/ideas/ 文件或 Ideas 行 （两者均由 review-ml-experiment 负责）。
• 直接写入或编辑 journal/NN_*.md 或 journal/JOURNAL.md。在回合结束时， 改为分派 manage-ml-backlog 的 record-outcome 模式——该技能负责所有日志写入。
• 运行 pytest / 冒烟测试（smoke-test-ml-pipeline）。
• 渲染提交或 PR。
• 决定哪些指标重要——单元格按任务填写， 但对哪些内容重要的判断权属于用户，并记在设计说明中。

配套技能

技能	关系
manage-ml-backlog	下游的 record-outcome 消费方；绝不会从 record-outcome 模式分派审计
review-ml-experiment	循环调用方。将摘要解析为文本，并为每个候选项写入一个想法文件和一行 Ideas。绝不打开 Project
evaluate-ml-pipeline	生产方。实验文件保存调用；materialize.py 是唯一的运行入口
setup-workspace	工作区布局；四路文件名主干配对
add-python-package	Agent 功能安装（Agent 工具（ruff / ipython / ipykernel））。此技能提出请求；该技能负责安装
python -m skore_skills api get	查询 skore 符号，包括 help 和额外的 Display 方法。优先使用缓存命中
plot-ml-figure	仅当 accessors.txt 中没有 Display 时，才启用自定义绘图门控
python -m skore_skills style	写入/编辑 audit/<stem>.py 后运行 ruff
choose-python-library / python -m skore_skills env stack	Agent 工具（ipython、ipykernel）属于 agent 功能

模板和资源

• templates/audit.py — 每个实验的审计文件骨架。复制
  • 替换；不要凭记忆重写。仅使用裸显示。
• templates/materialize.py — 唯一的审计运行入口。复制到 scratch/audit/<stem>/materialize.py。生成 HTML 查看器、accessors.txt 和 audit.md。

需要软件包？

缺少导入项时，如果 status.skills.add-python-package 为 true，则加载 add-python-package。该技能负责 env add 和未托管请求。此处不要运行 env add。 如果未安装该技能，则指出软件包名称并停止。

参考资料（按需加载）

• references/cell_anatomy.md — 具体的单元格示例（正确／错误的形状）、核心序列、为什么检查保持为裸 Display，以及指标使用 frame(verbose_name=True, flat_index=False)；额外的 Display 快照约定、裸表达式规则。
• references/runner_internals.md — 剩余的运行器内部细节（IPython、Agg）。优先查看 --help 或包文档字符串。
• references/failure_modes.md — § 故障模式中每种症状的详细恢复方法。