人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载openJiuwen agent-core 的openjiuwen/agent_evolving/checkpointing模块承载了 Agent 自演进Self Evolution链路中的两大持久化职责Trainer 训练状态 checkpoint供训练断点续训与Skill 经验的EvolutionStore供在线经验沉淀与复用。二者同处一个目录却不共享数据模型或恢复协议。本文将围绕该模块的 AGENTS.md / CLAUDE.md 设计约定结合源码逐层拆解其数据模型、目录布局、事务语义、投影机制、归档与分享安全边界并给出对应的测试验证路径帮助你掌握在 agent-core 中安全地保存、恢复、归档与分享演进状态的方法。模块地图一个目录、两套体系从源码目录结构看checkpointing是一组职责清晰的协作文件见 openjiuwen/agent_evolving/checkpointing文件职责manager.pycheckpoint 保存策略、operator snapshot 与恢复编排state.pyEvolveCheckpoint持久化状态模型store_file.pycheckpoint 的 JSON 文件 save/loadevolution_store.pySkill 目录解析、IO facade、semantic lock 与公共持久化入口store_records.pyevolutions.jsonrecord 事务、合并、评分和 simplify 写操作store_projection.pySKILL.md索引、经验详情和脚本索引的派生投影store_archive.pySkill 创建以及底层 archive、clear、list 辅助skill_package.py安全打包/解包与 pristine Skill 分享types.pyEvolutionRecord、EvolutionPatch、EvolutionLog与 usage stats模块对外暴露的公共门面定义在 checkpointing/init.py导出EvolveCheckpoint、FileCheckpointStore、EvolutionStore、CheckpointManager与DefaultCheckpointManager。整个模块的顶层入口也被 agent_evolving/init.py 二次导出供上层 Trainer、在线演进服务统一使用。理解这个模块的关键前提是checkpoint 是训练过程的暂停点面向Trainer与可演进 operator 的状态快照EvolutionStore 是经验的持久化仓库面向 Skill 目录的读写与投影。二者只是恰好同处一个目录绝不能在数据模型或恢复协议上互相借用。Trainer Checkpoint断点续训的完整状态持久化状态模型EvolveCheckpoint定义在 state.py是一个纯 dataclass包含以下字段versioncheckpoint 格式版本DefaultCheckpointManager默认v1run_id一次训练运行的全局标识step训练进度形如{epoch: ..., batch: ...}best历史最优指标形如{best_score: ...}seed随机种子可为Noneoperators_state{operator_id: state}字典保存所有可演进 operator 的内部状态updater_stateupdater如优化器的状态供恢复时继续迭代searcher_state搜索器状态当前默认为空字典last_metrics最近一次评估指标快照。设计约定要求新增字段时save/load、默认值、版本兼容和 resume 测试必须成对更新恢复以持久化 checkpoint 为准不从日志或当前 operator 偶然状态猜测进度。保存策略与快照/恢复编排DefaultCheckpointManagermanager.py实现了三种可组合的保存时机参数默认值说明run_id自动生成 UUID训练运行标识checkpoint_versionv1checkpoint 格式版本号save_every_n_epochs1每 N 个 epoch 保存一次最小值被钳制为 1max(int(...), 1)save_on_improveTrue验证指标提升时立即保存should_save(epoch..., improved...)的判定逻辑是save_on_improve开启且本轮改进则保存否则按epoch % save_every_n_epochs 0周期保存。build_checkpoint()通过agent.get_operators()遍历所有 operator调用op.get_state()生成operators_state并从progress上摘取 epoch/batch/best_score/seed 等进度字段restore()则将operators_state逐一通过op.load_state(state)写回 agent并返回{start_epoch, best_score, run_id}供 Trainer 恢复进度——这样restore不与具体的 Progress 类型强耦合见manager.py中restore的注释与返回值设计。DefaultCheckpointManager还内置了一套pending change 管理add_pending/get_pending/commit_pending/discard_pending用于在线演进场景下按operator_id分组暂存待落库的变更其中commit_pending只清空内存队列并返回 record 数量不负责写盘真正的持久化由调用方通过store.append_record()完成源码注释明确声明了这一点。JSON 文件存储FileCheckpointStorestore_file.py是一个最小可用的本地 JSON checkpoint 存储不依赖 core checkpointer避免污染核心生命周期语义可在任何环境运行便于调试与审计save_checkpoint(ckpt, filenamelatest.json)先通过_to_json_compatible递归地把 Pydantic 模型model_dump()、dataclassasdict()、list/tuple/dict 转换为 JSON 兼容类型再以ensure_asciiFalse, indent2写入load_checkpoint(path)反序列化回EvolveCheckpointload_state_dict(path)是面向推理侧的单点 API直接取出operators_state字典配合op.load_state(state[operator_id])使用模拟深度学习风格的 inference loader。与 Trainer 的集成方式Traineropenjiuwen/agent_evolving/trainer/trainer.py是 checkpoint 的主要消费方构造时传checkpoint_dir为None则禁用 checkpoint、resume_from、checkpoint_every_n_epochs、checkpoint_on_improve未显式传checkpoint_manager时默认构造DefaultCheckpointManager_resume_if_needed()读取resume_from指向的 checkpoint调用manager.restore()恢复 operator 状态与进度并把updater_state交给updater.load_state()_save_checkpoint_if_needed()按should_save决策build_checkpoint()后写入latest.json。FileCheckpointStore的路径与序列化格式属于兼容边界——变更前必须检查公开文档与已有文件的读取AGENTS.md 明确标注。单测 tests/unit_tests/agent_evolving/checkpointing/test_manager.py 和 test_store_file.py 覆盖了默认/自定义初始化、改进保存、周期保存、operator 状态快照与恢复、缺失 operator 跳过、无get_operators的 agent 容错等场景。EvolutionStoreSkill 经验的事实源与目录布局EvolutionStore是 Skill 经验的公共持久化入口其目录布局约定如下skills-root/skill/ ├── SKILL.md # 原始 Skill 自动 Evolution Index block ├── evolutions.json # 经验事实源 ├── evolution/*.md # 自动生成的 narrative detail ├── evolution/scripts/_index.md # 自动生成的脚本索引 ├── evolution/scripts/* # 持久化脚本资产 └── archive/ # 配对历史版本三条核心纪律源码在 evolution_store.py 中逐条落实路径解析统一走EvolutionStore调用方不要自行拼接 skill、projection 或 archive 路径所有读写方法read_file_text/write_file_text都会先经_validate_file_path校验——目标路径必须resolve()后落在配置的skills_base_dir之内否则抛出TOOLCHAIN_EVOLVING_SKILL_STORE_EXECUTION_ERROR。保留SysOperationIO 边界EvolutionStore可挂载sys_operation对应openjiuwen.core.sys_operation有挂载时所有文件读写走sys_operation.fs().read_file / write_file不绕过宿主文件系统能力或安全校验未挂载时回退到pathlib直接读写测试test_read_file_text_with_sys_operation等覆盖了这两种路径。普通 Skill 与 team Skill 共用 store通过subject_kindskill/team-skill/swarm-skill见 protocols.py区分查找、创建、读写和 archive 必须传递同一 kind不能复制 team-only 持久化实现。同名普通 Skill 与 swarm Skill 的evolutions.json相互隔离这在测试test_kind_aware_resolution_keeps_same_name_skill_logs_separate中有完整验证。初始化与 base dir 解析EvolutionStore(skills_base_dir)接受单个字符串或字符串列表_parse_base_dirs把,规范化为;后切分_normalize_base_dirs会对每个目录做expanduser().resolve()并去重空列表会直接抛ValueError(skills_base_dir is empty)。list_skill_names()只列非_前缀的目录并去重skill_exists/skill_definition_exists后者要求存在SKILL.md提供存在性判断。resolve_skill_dir(name, createTrue)会调用_is_safe_skill_destination确保新建目标严格位于某个 base dir 内部拒绝..、绝对路径与指向 base 之外的符号链接目标。数据模型一次演进经验如何被描述与落盘types.py 定义了四个核心类型EvolutionPatch一次生成的演进变更包含section、action、content、targetdescription/body/script以及可选的skip_reason、merge_target、script_filename、script_language、script_purpose、keywords、summary。__post_init__会校验action必须属于VALID_PATCH_ACTIONS {append, merge, replace, skip}section必须属于VALID_SECTIONSInstructions/Examples/Troubleshooting/Scripts/Collaboration/Roles/Constraints/Workflow见 protocols.pyskip动作跳过 section 校验。EvolutionRecord一条已存储的演进经验字段为idev_uuid4 前 8 位十六进制、source、timestampUTC ISO 格式、context、change: EvolutionPatch、applied默认False、score默认0.6、usage_stats与可选skill_version、summary。is_pending即not applied。EvolutionLog一个 Skill 的全部演进条目的持久化容器字段为skill_id、version默认1.0.0、updated_at、entriespending_entries返回所有未应用记录。UsageStats经验使用统计字段为times_presented、times_used、times_positive、times_negative、last_presented_at、last_evaluated_at。to_dict/from_dict保证了 JSON 序列化与向后兼容如summary字段缺失时恢复为None旧版 JSON 仍可读取——见测试test_record_summary_serializes_and_old_json_remains_compatible。Record 事务与投影单一事实源 派生输出evolutions.json是单一事实源SKILL.md中的 Evolution Index、evolution/*.md与脚本索引都是派生输出文件头标注为 generated 的内容不能直接编辑。append 完整事务append_recordevolution_store.py在skill semantic lock内完成完整事务底层由StoreRecordsHelper.append_record_transactionalstore_records.py实现在进入锁后先记录evolutions.json旧内容并快照所有 projection 文件evolution/下全部文件与SKILL.md的字节内容若change.target EvolutionTarget.SCRIPT先persist_script把脚本源码写入evolution/scripts/filename并将 record 的 content 替换为引用描述Script: filename / Language / Purpose语言到扩展名映射见_LANG_TO_EXTpython→py、javascript→js、typescript→ts、shell/bash→sh加载旧 log_append_or_merge_record若带merge_target则按 record ID 替换旧条目否则追加save_evolution_log以临时文件 replace的原子替换方式写盘_write_file_text_atomic随后 readback 校验 JSON 一致不一致即抛错重新渲染投影render_evolution_markdown。任一步失败都会整体回滚恢复旧 log 文件、恢复SKILL.md与所有 projection 文件、清理新增的脚本文件与空目录且回滚后保持调用方传入的 record 原始内容不变测试test_append_record_rolls_back_log_on_failure、test_append_record_rolls_back_script_file_and_keeps_payload、test_append_record_rolls_back_projection_on_failure逐一验证。这就是 AGENTS.md 强调的不要拆开这条事务边界。semantic lock 与并发安全同一 skill 的 read-modify-write 必须保留 semantic lockEvolutionStore._get_skill_lock(name)用dict.setdefault(skill_name, asyncio.Lock())按 skill 名缓存asyncio.Lock避免 TOCTOU 竞态两个协程同时判断 key 不存在并各自创建新锁。仅靠文件级 atomic replace不能防止两个协程基于同一旧版本互相覆盖。测试test_concurrent_append_record_no_data_loss用asyncio.gather并发 append 10 条记录断言最终恰好 10 条test_skill_lock_isolation验证不同 skill 的写入互不阻塞。merge、delete、refine、mark-applied 与 score 更新这些写操作也必须从EvolutionStorefacade 进入 semantic lockmerge_records、delete_records、mark_records_applied、update_record_scores、update_record_content均以async with self._get_skill_lock(name)包裹影响投影内容的操作append、merge、delete、mark-applied、update-record-content写 log 后调用render_evolution_markdown重新渲染仅更新 score/usage statsupdate_record_scores只写事实源不重渲染score/usage stats 更新必须保留未被选中的 record按 record ID 精确写入update_record_scores只对updates中出现的 ID 修改score与usage_stats返回更新条数merge 语义MergeRecordsRequest(name, primary_id, remove_ids, new_content, new_score, subject_kind)主记录缺失时返回None合并后的分数默认取主记录 被合并记录的最大值max(all_scores)显式传new_score则优先合并与 update content 都会清空summary测试test_merge_and_update_clear_stale_summary经验是否呈现和如何评价由experience/决定store 不推断业务使用只忠实落盘。投影渲染规则StoreProjectionHelperstore_projection.py负责三类派生输出分区详情文件evolution/section_lowercase.md按 section 聚合非 script 记录每条约以a id{record.id}/a锚点开头标题为### [{id}] {summary}尾部附*Source: {source} | {timestamp}*与 applied 标记脚本索引evolution/scripts/_index.mdMarkdown 表格列出File / Language / Purpose / SourceSKILL.md的 Evolution Index block!-- evolution-index-start -- ... !-- evolution-index-end --幂等替换——旧 block 被整个替换新 block 包含总经验数、### Experience IndexSummary/Type/Score/Detail 表格按 section→score→timestamp 排序与### Script Assets表格以及指向evolution/*.md#record_id的相对锚点链接。当某 skill 的所有记录都被删除/清空时clear_rendered_outputs会清理全部投影文件并移除SKILL.md中的旧 index block测试test_delete_or_clear_last_record_removes_stale_projection_outputs验证。投影还提供面向 LLM 的格式化助手format_desc_experience_text默认最多 5 条高分段 pending description 经验、format_body_experience_text、list_pending_summary无经验时返回当前所有 Skill 暂无演进信息。。当单个 skill 的evolutions.json记录数达到 30_TOTAL_WARNING_THRESHOLD时append_record会打印警告建议执行/evolve_simplify做精简。Archive、rebuild 与 sharing配对生命周期与安全分享配对归档由 experience 层统一协调完整配对生命周期由experience/archive.py的EvolutionArchiveService在 store facade 之上协调见 experience/archive.pycheckpointing helper 与 experience service不能各自生成不兼容的版本号。EvolutionArchiveService提供archive_current_pair把当前SKILL.md与evolutions.json以同一版本号成对归档到archive/缺失的evolutions.json会先补一个空 log保证每个归档版本都是完整可回滚目标写两侧任一侧失败会清理已写文件list_pairs只返回 SKILL 归档与 evolutions 归档成对存在的版本按版本号倒序rollback_to_pair先归档当前状态再把归档对写回SKILL.md与evolutions.json随后重新生成 projectionrender_evolution_markdown绝不把历史派生文件当事实源直接复制回来成功回滚后消费掉该归档对并可pruneprune(keep_latest)裁剪多余的旧配对返回删除数量。约束要点archive 是同一版本的SKILL.md evolutions.json完整配对创建、恢复、裁剪不能留下只能恢复一半的版本rebuild 只有在配对归档成功后才能清空当前经验记录archive 失败时保留当前状态对应clear_evolutions需在归档完成后才被调用。StoreArchiveHelperstore_archive.py提供底层辅助create_skill拒绝非法名、路径穿越与已存在 skill默认生成带name/descriptionfrontmatter 的SKILL.md并初始化空 log、archive_skill_body、archive_evolutions文件名带 UTC 时间戳后缀YYYYMMDDTHHMMSS、clear_evolutions、list_archives按文件名倒序。分享包只带 pristine 内容skill_package.py实现安全打包/解包打包pack_skill_directorytar-gzip 整个 Skill 目录但排除evolution、archive、__pycache__、.git目录与evolutions.json以及所有点文件pack_skill_for_sharing还先把SKILL.md中的 Evolution Index block 剥掉read_pristine_skill_content用正则!-- evolution-index-start --...!-- evolution-index-end --移除保证分享出去的是作者原始内容而非本地渲染的索引skill_id管理new_skill_id()生成sk_uuid4 前 12 位ensure_skill_id_in_content在缺失时把skill_id注入 frontmatter解包安全unpack_skill_package优先使用 Python 3.12 的tarfile.data_filter旧解释器回退到_safe_extract_tar逐成员校验拒绝绝对路径、含..段的路径、符号链接/硬链接逃逸到解包根目录之外的目标对称链接目标基于链接自身目录解析硬链接基于归档根解析install_skill_package还会用^[a-zA-Z0-9_-]$校验 skill 名拒绝目录已存在或目标被符号链接指向 base 之外的安装。这些安全约束在 tests/unit_tests/agent_evolving/checkpointing/test_skill_package_safety.py 中有一组针对性测试父目录穿越、绝对路径成员、路径中间含..、逃逸符号链接、绝对符号链接目标、逃逸硬链接全部被拒同时合法包与相对链接目标被放行。修改与测试每次变更的验收标准AGENTS.md 对修改与测试给出了明确要求Trainer checkpoint运行对应 manager/store/resume 测试即 tests/unit_tests/agent_evolving/checkpointing/test_manager.py、test_store_file.py 等EvolutionStore运行uv run pytest tests/unit_tests/agent_evolving/checkpointing -qrecord 或 projection 变化必须覆盖 append、merge、delete、score、脚本、写失败回滚和索引幂等对应 test_evolution_store.py 中TestEvolutionStoreLogCRUD、TestEvolutionStoreRenderMarkdown、TestEvolutionStoreRecordMaintenance、TestEvolutionStoreConcurrentSafety等测试类archive 变化必须覆盖配对、裁剪、rollback 与失败保留当前状态在experience/archive对应测试中覆盖。总结openjiuwen/agent_evolving/checkpointing以两套体系、一个目录的方式为 openJiuwen agent-core 的自演进链路提供了可靠的地基Trainer Checkpoint保证训练进程可暂停、可恢复、可审计EvolutionStore保证 Skill 经验以evolutions.json为单一事实源通过 semantic lock 与原子写 回滚的事务语义支撑在线高并发演进通过投影机制把经验实时反射回SKILL.md通过配对归档与安全打包实现可回滚的生命周期管理和安全的跨用户分享。对于需要扩展该模块的开发者只要守住路径统一走 facade、事务不拆、投影不直接编辑、归档必须成对、解包必须拒绝越界这几条约定就能在不破坏兼容边界的前提下安全地迭代演进能力。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core 演进 checkpointing 全解析Trainer 状态快照与 Skill 经验 EvolutionStoreopenJiuwen agent core 演进 checkpointing 全解析Trainer 状态快照与 Skill 经验 EvolutionStore人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen Agent 自演进训练检查点与经验存储指南checkpointing 模块核心机制详解openJiuwen Agent 自演进训练检查点与经验存储指南checkpointing 模块核心机制详解 导读 本文围绕 openJiuwen agent人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 的 Redis 检查点Checkpointer扩展Agent/工作流状态持久化与恢复实战指南openJiuwen agent core 的 Redis 检查点Checkpointer扩展Agent/工作流状态持久化与恢复实战指南 导读 本指南聚焦人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇用AI斗地主轻松上分DouZero_For_HappyDouDiZhu零基础实战指南下一篇Ralph for Claude Code集成监控tmux面板管理技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
