run-cherries-experiments

运行 Cherries 实验

使用此技能进行 Cherries 实验并保存记录。依赖某条命令前，请先阅读 Cherries 检出版本中的 docs/README.md；已安装的版本可能尚未包含文档中介绍的所有功能。

仓库边界

请在单独的实验超级项目中工作，例如：

phace-exp/
  cherries.toml  pyproject.toml  uv.lock
  libs/apple/  libs/melon/       # Git submodules
  exp/YYYY/mm/dd/study/
    src/  configs/  fixtures/  docs/  analysis/

将编写的研究源代码、配置、报告、精选测试夹具和子模块 Git 链接保存在 Git 中。仅对精选且可供审查的资源使用 LFS。生成的输入、输出、日志、网格和检查点应存放在 Cherries 存储中，绝不能放入 Apple 或 Melon 仓库，也绝不能使用宽泛的 LFS 模式。

请使用已配置的本地数据卷，而非 /tmp：

# cherries.local.toml (normally Git ignored)
[collection]
storage = "/data/cherries/phace-exp"

显式初始化新集合：

cherries --project-dir . --storage /data/cherries/phace-exp init \
  --collection-id "<collection-uuid>"

请读取项目设置以确定本地存储和归档目标；不要假定某台机器专用的路径或已发布的实验 Git 引用。 使用 --storage 覆盖本地存储。通过 --remote main 进行远程归档／同步，需要显式配置 archive.main.path。 本地记录器目前支持 Linux 和 Python 3.12 或更高版本。

封存每日实验

运行普通 Python 或 uv run python；不涉及引导、重新启动、守护进程、手动保存或自动 Git 提交。

from liblaf import cherries


class Config(cherries.BaseConfig):
    mesh: str = "sha256:<full-digest>"  # raw source declaration
    steps: int = 200


def main(cfg: Config) -> None:
    mesh = cherries.input(cfg.mesh, name="mesh.vtu")
    result = cherries.output("solution.txt")
    cherries.temp("solver-cache")
    result.write_text(f"{mesh.name}: {cfg.steps}\n")
    cherries.log_metric("steps", cfg.steps)


if __name__ == "__main__":
    cherries.main(main)

保持模块作用域无副作用。不要在 main 之外读取数据、实例化求解器／GPU 上下文、创建随机实验状态、解析实时输入，或调用 Cherries 资产、指标、参数或步骤辅助函数。配置默认值必须是原始字符串或路径；辅助函数需要活动运行。像运行普通 Python 程序一样调用它，并保留原始参数：

uv run python exp/2026/10/05/mouthopen/src/10-run.py --steps 200

BaseConfig 接受 kebab-case 标志；帮助信息和无效配置会在记录开始前退出。仅在确实需要 Comet 可观测性时设置 CHERRIES_COMET=1；默认情况下此功能处于禁用状态，且不会加载其 SDK。

请在 main 返回前完成异步原生操作以及所有工作文件夹写入。Cherries 会等待新建的 Python 管理线程（包括守护线程），但无法加入或跟踪外部原生线程。原生清理线程不会阻碍封存；请显式同步原生库或 GPU 工作。

input() 接受本地路径、完整的 sha256: 文件 ID、sha256-tree: 包 ID，或 run:<record-id>/<logical-path>。它会验证数据，并在 inputs/ 下暂存独立副本，记录选定的生产者，并在读取前登记溯源关系。传入 source_run=<record-id> 可限定摘要的来源。 output() 声明 outputs/ 下的必需路径；log_output() 将现有的外部输出复制到该路径。temp() 返回一个可丢弃的 scratch/ 路径。

在 main 期间，绝不要修改暂存输入：检测到此类修改时，会留下未完成的工作，并抛出异常，而不是进行封存。非有限科学指标值会保留为 NaN、Infinity 或 -Infinity 字符串，供审查。

Cherries 会捕获入口源代码、HEAD、二进制差异、选定的未跟踪源代码、运行时证据、参数、输入绑定、日志、指标和已声明的输出。它会在普通导入之后、main 边界处进行捕获，因此请确保记录的源代码保持稳定，但绝不要声称 replay_verified。请确保引用的 Git 基础版本仍可用。运行成功后会封存规范化的 SHA-256 对象和一条小型不可变记录。如果缺少已声明的输出或发生记录错误，则会保留工作暂存区。执行失败时会记录诊断信息，并且可能仅丢弃没有依赖或保留项的未封存本地负载。

实验过程文档

在实验期间自动维护实验笔记。这是一项持续有效的工作流要求；不要等到收到单独的“编写文档”指令才开始。开始会话时，先阅读研究的 RUN.md 和相关运行记忆，再提出工作方案。延续既有决策、失败的方法、不确定之处，以及当前计划背后的原因。

在运行被封存前，将其问题、协议和讨论记录在研究的 RUN.md 中。对于已保存的运行，在 exp/YYYY/mm/dd/study/docs/runs/<RUN-ID>.md 维护一份可编辑的 Markdown 文档。在 phace-exp 中，使用 templates/run-memory.md 初始化该文档；用实际证据替换模板提示。记录准确的运行 ID、命令／配置、输入和输出引用、观察结果、当前解读、决策、未决问题、后续步骤，以及有意义变更的简短日期记录。只保留相关章节。

在实质性讨论、新结果、决策、纠正或方向变更后，以及最终回复或会话交接前，更新笔记。保留测量所得的事实；若结论发生变化，应说明并标记已被取代的解读。总结有用的推理，而不是照搬聊天内容。若执行失败且未保存运行，则在研究笔记中记录诊断信息。

将每个已更改的文档版本附加到本地保存的运行：

uv run cherries note <RUN-ID> --file exp/YYYY/mm/dd/study/docs/runs/<RUN-ID>.md
uv run cherries --json show <RUN-ID>

完整的 Markdown 会作为仅追加的注释保留。show 会包含 projection.notes；最新一条 value 以 # Run memory: 开头的记录就是已保存的记忆，较早的版本仍可访问。若本地文档丢失，可从中恢复。如果并发会话留下了不同版本，请阅读两者，并将其中的证据和未决问题整合到新版本中。调用 note 前，应与最近保存的记忆进行比较，未发生变化的文档无需提交。CLI 每次调用都会追加一个修订版本；它不会抑制重复内容。

这些普通记忆不会创建依赖记录或保留限制，因此记笔记不会影响手动丢弃资格。保持原始封存的 RUN.md 和回执不变。明确的比较、图表或会议输出应使用下文的分析工作流，并保护其源运行。不要因为获准维护文档，就推断会自动执行 Git 提交或远程发布。

检查记录并归档

将全局选项放在命令之前。若输出将作为脚本的输入，请使用 --json。

cherries --storage /data/cherries/phace-exp --json browse --quality unreviewed
cherries --storage /data/cherries/phace-exp browse --failed
cherries --storage /data/cherries/phace-exp browse --label mouthopen
cherries --storage /data/cherries/phace-exp browse --asset sha256:<digest>
cherries --storage /data/cherries/phace-exp browse --search mouthopen
cherries --storage /data/cherries/phace-exp browse --used-in weekly/2026-10-05
cherries --storage /data/cherries/phace-exp show <record-id>
cherries --storage /data/cherries/phace-exp read <record-id> RUN.md
cherries --storage /data/cherries/phace-exp path <record-id> outputs/solution.txt
cherries --storage /data/cherries/phace-exp --json path <record-id> legacy/data/example.vtu
cherries --storage /data/cherries/phace-exp path --release <lease-id>
cherries --storage /data/cherries/phace-exp archive <record-id> --remote /archive/cherries --evict
cherries --storage /data/cherries/phace-exp restore <record-id> --remote /archive/cherries

browse 使用最新的审查质量；--used-in 包含指定的分析及其直接来源父项。--search 会匹配名称、类型、旧版来源和迁移后的旧版来源。 path 会实体化已声明的文件或目录及所需的 .series 伴随文件，并创建持久的读取租约。所选记录必须声明 sha256-tree；它会还原完整拓扑结构，包括已声明的空目录。restore 会在临时还原持有期内验证完整记录，然后创建本地还原的常驻视图。

伴随文件包的主路径会返回一个文件，其伴随文件位于同一目录下。 树输入使用其记录的暂存路径，包括已声明的空目录。

JSON 格式的 path 结果包含租约 ID；检查结束时，请释放该确切 ID。这同样适用于已迁移的原始路径，例如 legacy/data/example.vtu。

对于后续 Python 工作，请使用可关闭的读取器持有对象：

with cherries.open_run("<record-id>") as saved:
    result = saved.path("outputs/solution.txt")

传入 workspace=Path("analysis/compare")，可将来源附加到现有的分析工作区持有对象。无论采用哪种模式，都应关闭访问器或使用上下文管理器：即使工作区已关闭，其临时读取器持有对象仍会保护正在进行的读取。工作区自身的持有对象会一直保留，直到执行 cherries analysis close。

cherries rerun <id> --prepare-only --workspace replay/<id> 会根据已保存的 Git HEAD、二进制差异、选定的未跟踪来源、捕获的入口点和输入映射，重建一个全新的工作区。它要求本地存在已捕获的 Git 基础版本，并且实验收据保持来源稳定。若不使用 --prepare-only，它会通过 uv run 执行该工作区（存在 uv.lock 时会使用 --locked）。它会创建一次新尝试；只有在科学检查确认后，replay_verified 才会变为 true。使用 cherries rerun --close <workspace> 关闭已准备好的工作区。

归档仅在前台运行。它会验证每个本地对象、发布完整闭包、回读并验证字节，最后发布远程 commit.json。本地目录远程具有原子文件系统边界。通用 rclone 远程需要 --coordinated，该选项表示收集操作的发布者已通过真实的外部机制进行串行化；请勿使用标记文件锁或过期所有者接管机制。使用 cherries sync --remote REMOTE [--coordinated] 传输仅追加的元数据。Sync 会写入绑定 SHA 的控制元数据、事件，最后写入不含载荷的检查点标记。导入检查点时，只会合并选定的收据元数据及其必需的祖先关系图；这不能证明远程载荷可用。选定的还原和导入只会安装该血缘的事件，包括已在本地的祖先记录的更新。安装前仍会验证所有绑定到检查点的事件证明。全局元数据同步仍保留其面向整个集合的范围。browse --failed 中的失败尝试属于本地诊断信息，绝不会发布或导入。

--evict 仅在验证后释放符合条件的已实体化本地视图。其他常驻记录、活动任务、读取器／分析持有对象以及 --keep-local 都会阻止此操作。--important 保护的是逻辑保留，而非本地视图。只要有任何常驻本地记录需要共享的树对象，该树对象就会保留其完整成员闭包。

即使后续源端本地注释失败，归档仍可能已提交。此时，archive 会在成功退出状态下返回已验证的位置和一条 warnings 条目；--evict 会跳过该记录并报告 eviction_skipped。请保留返回的提交证据和本地字节。远程发布错误仍会导致命令失败；绝不能根据本地注释失败来推断远程发布结果。

审查与轻量分析

成功运行的初始状态为 unreviewed。审查具有主观性，与执行或科学验证相互独立。标签和审查会追加元数据事件；它们不会更改不可变回执或 CAS 对象，而且 bad 绝不会自动丢弃成功的运行。

cherries review <id> --quality good --note "Useful comparison"
cherries label add <id> mouthopen promising
cherries label remove <id> promising
cherries mark <id> --important
cherries mark <id> --keep-local
cherries note <id> --file findings.md
cherries link <id> --git <commit>
cherries analysis new analysis/compare --source <id>
cherries analysis save analysis/compare --output out/figure.png --used-in weekly/2026-10-05
cherries analysis close analysis/compare

后续工作请使用当前开发环境、ParaView 或其他交互式工具。将选定的源添加到分析中；分析打开时，其工作区会保留这些源。保存 RUN.md、analysis.json、src/，以及仅显式指定的 out/... 输出。在封存记录中，RUN.md 和 analysis.json 保留原名，工作区中的 src/... 会存储为 source/...，选定的 out/... 文件会存储为 outputs/...。检索时请使用这些保存路径，包括已有的分析记录；例如，cherries read <analysis-id> source/compare.py 和 cherries path <analysis-id> outputs/figure.png。 在有用时，保存 ParaView 设置和显示的资产引用。已保存的分析是轻量级从属记录，可保护每个源；但不保证严格重放求解器。备注和 Git 链接是只追加事件，并会与其他元数据同步。

旧版导入是具有不完整溯源信息的附加式不可变记录。可以搜索其旧版源/名称，但它们不是源稳定的实验、可重放记录，也不授权进行维护。

本地单机维护需要暂停回执和已保存的计划：

cherries maintenance pause
cherries discard <id> --plan
cherries discard --apply <plan-path>
cherries prune --plan
cherries prune --apply <plan-path>
cherries maintenance resume <pause-token>

暂停会冻结引用创建；如存在活动/待处理工作、旧版溯源信息或外部参与者，则会安全失败。计划绑定到本地暂停回执和清单。这不授权远程或分布式删除；切勿用 rclone 清理替代它，也不要移除存在从属项的记录。已退役的子项仍会阻止其父项。只要任何驻留的本地记录仍需要共享树对象，清理时就会保护该对象的完整依赖闭包。

证据与报告

报告实际记录 ID、命令、记录/清单证据、生成的资产路径以及观测到的指标。应区分执行回执、验证结果、主观审查和重放声明。封存成功前，不要将工作文件夹称为已保存记录；没有经过验证的回执和迁移负责人的确认，不要将迁移描述为已完成。