NemoClaw 维护者状态文件state.jsonSchema 全解析维护循环的持久化状态设计与实践【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw导读本文围绕 NemoClaw 仓库中维护者自动化 Skill 的核心持久化机制——.nemoclaw-maintainer/state.json状态文件——展开完整解读其 JSON Schema 的每个字段、取值约束与写入规范并结合 state.ts、triage.ts、hotspots.ts 等源码说明该文件如何在 triage、merge-gate、hotspot 检测与每日维护循环之间传递状态、排除项与历史记录。读完本文你将掌握这份状态文件的完整结构、每个字段的语义与边界条件以及如何在日常维护流程中正确读写它。状态文件的定位维护循环的“单一事实来源”NemoClaw 的维护者 Skill如nemoclaw-maintainer-day以一个可重复执行的维护循环为核心每天对面向发布的 PR 与 Issue 执行一次“检查版本进度 → 选择一个动作 → 执行 → 汇报进度”的完整流程见 SKILL.md。为了让循环在多次运行之间保持连续性——知道哪些 PR 被永久排除、上一次 triage 队列长什么样、当前正在处理什么工作——维护者工具链需要一个跨进程、跨运行持久化的状态文件。STATE-SCHEMA.md即 STATE-SCHEMA.md正是这份状态文件的事实性规格说明。其核心约定有三条存储位置状态存放在.nemoclaw-maintainer/state.json相对仓库根目录。Git 排除通过.git/info/exclude将.nemoclaw-maintainer/目录排除出版本控制避免本地维护状态污染提交历史。这一点在 state.ts 的ensureExclude()中得到落实——脚本会在init时检查.git/info/exclude是否已包含.nemoclaw-maintainer/条目没有则追加。自描述版本文件带有version字段便于未来 Schema 演进时进行迁移判断。完整 Schema 示例STATE-SCHEMA.md给出了状态文件的完整骨架这是所有字段的权威参考。完整 JSON 如下含默认值{ version: 1, repo: NVIDIA/NemoClaw, updatedAt: null, priorities: [ reduce_pr_backlog, reduce_security_risk, increase_test_coverage, cool_hot_files ], gates: { greenCi: true, noConflicts: true, noMajorCodeRabbit: true, testsForTouchedRiskyCode: true, autoApprove: true, autoPushSmallFixes: true, autoMerge: false }, excluded: { prs: {}, issues: {} }, queue: { generatedAt: null, topAction: null, items: [], nearMisses: [] }, hotspots: { generatedAt: null, files: [] }, activeWork: { kind: null, target: null, branch: null, goal: null, startedAt: null }, history: [] }这份示例与 state.ts 中defaultState()函数生成的默认状态完全一致说明文档与实现保持了同步你可以把它当作“初始化后的初始状态”。顶层字段逐一解读version与repoversionSchema 版本号当前为1。它标识状态文件的格式版本供读取方做兼容性判断。repo目标仓库标识默认NVIDIA/NemoClaw。triage 等脚本会用它拼装gh查询参数如gh api repos/${repo}/pulls详见 triage.ts。updatedAt最近一次状态写入的 ISO 时间戳。每次saveState()都会把它刷新为new Date().toISOString()见 state.ts用于判断状态的新鲜度。初始值为null表示尚未写入过。priorities维护工作的优先级数组默认包含四个枚举值体现了维护者循环的关注重心优先级键含义reduce_pr_backlog减少 PR 积压reduce_security_risk降低安全风险increase_test_coverage提升测试覆盖cool_hot_files为热点文件“降温”降低冲突与改动集中的文件热度从源码结构看这一数组主要作为维护者决策的参考优先级列表实际的动作选择则由 SKILL.md 中“Step 2: Pick One Action”的有序决策链approve → salvage → security → test gap → conflicts → sequencing驱动。gates合并闸门开关gates对象用一组布尔值描述维护循环的自主行为边界这是整个状态文件中约束性最强的部分字段默认值语义greenCitrue要求 CI 全绿noConflictstrue要求无合并冲突noMajorCodeRabbittrue要求无未解决的 major/critical CodeRabbit 问题testsForTouchedRiskyCodetrue要求触及的“风险代码”有测试覆盖autoApprovetrue允许自动批准当所有闸门通过时autoPushSmallFixestrue允许在贡献者分支上推送小修复autoMergefalse禁止自动合并其中两条需要特别注意gates.autoMerge必须保持为false。维护循环可以批准approve一个 PR但绝不能合并merge它。这与 SKILL.md 的“Never merge”约束以及 MERGE-GATE.md 中“Report that the PR can proceed to a separate merge decision. Never merge in this workflow”的说明完全一致——合并决定必须交给用户。gates.autoPushSmallFixes是“小修复推送到贡献者分支”的授权开关。SKILL.md 还补充了其前置条件必须在 CI 与定时自动化评审针对“同一个未变的最新 PR commit”稳定结束之后才允许推送。excluded排除清单excluded对象包含prs与issues两个映射用于记录被 triage 永久跳过直到用户手动移除的条目键必须是数字字符串number string如1234而不是数字。值必须是{ reason: ..., excludedAt: ISO }形式excludedAt为 ISO 时间戳。triage 在构建队列时会读取该清单并过滤const excludedPrs new Set(Object.keys(state?.excluded?.prs ?? {}).map(Number))随后classified.filter((item) !excludedPrs.has(item.number))见 triage.ts。注意excluded.issues字段在 state.ts 的类型定义中存在但exclude子命令目前只写入prs源码注释明确说明“triage only processes PRs”。queue最近一次 triage 输出queue缓存最近一次 triage 的结果用于跨运行对比避免每次循环都重复完整分析字段语义generatedAttriage 输出的生成时间ISOtopAction队列中排名第一的动作项items主队列条目merge-ready / review-readynearMisses“差一点就绪”的条目有明确的小修复路径该对象由state.ts set-queue子命令从 stdin 读取 triage 的 JSON 输出并写入见 state.tsitems取triageOutput.queuenearMisses取triageOutput.nearMissestopAction取queue[0]generatedAt优先使用 triage 输出自带的时间戳。triage 输出的完整字段含rank、bucket、score、nextAction、riskyFiles等可参见 triage.ts 的QueueItem接口。hotspots热点文件缓存hotspots缓存最近一次热点检测的结果用于识别最易引发合并冲突的文件字段语义generatedAt检测结果生成时间ISOfiles热点文件条目列表该对象由state.ts set-hotspots子命令写入同样从 stdin 读取热点检测脚本的 JSON 输出见 state.ts。热点检测算法见 hotspots.ts它综合30 天origin/main上的 git churn与开放 PR 的文件重叠数按mainTouchCount openPrCount * 3 (risky ? (mainTouchCount openPrCount) * 2 : 0)打分排序其中 PR 重叠权重 3 倍作为冲突代理指标、风险文件额外 2 倍加成最终输出前 25 个热点文件。检测到的热点会路由到 HOTSPOTS.md 对应的工作流处理。activeWork当前进行中的工作activeWork记录维护者“正在处理但尚未完成”的单项工作供中断恢复与交接使用字段语义kind工作类型如 approve、salvage、test 等target目标条目如 PR 编号branch涉及的分支goal目标描述startedAt开始时间ISO初始状态为全null。从源码结构看该字段主要服务于跨循环的上下文恢复——SKILL.md 中“Readstate.jsonto avoid repeated context”的说明即与此对应。history操作历史history是一个操作审计数组记录了每次循环完成的关键动作。每个条目的格式为{ at: ISO, item: PR#1234, action: approved|salvaged|blocked|sequenced, note: one line }约束条件at为 ISO 时间戳item标识目标条目约定为PR#1234形式action是四个枚举之一approved批准、salvaged修复抢救、blocked报告阻塞、sequenced排队序列化note为一行简要说明最多保留 50 条超出时删除最旧的条目。该上限在 state.ts 的cmdHistory()中有硬性实现if (state.history.length 50) state.history state.history.slice(-50)。历史记录的典型写入方式来自 SKILL.md 的 Step 4node --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/state.ts history action item note例如node --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/state.ts history approved PR#1234 all gates passed, approved状态文件读写工具state.ts 子命令速查仓库提供了配套的 TypeScript 状态管理脚本 state.ts所有子命令均以node --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/state.ts subcommand [args]形式调用。支持七个子命令子命令参数作用init无创建.nemoclaw-maintainer/state.json若不存在并确保.git/info/exclude包含.nemoclaw-maintainer/show无打印当前完整状态JSONexcludenumber reason将 PR 加入永久排除清单记录原因与排除时间unexcludenumber从排除清单移除条目同时清理prs与issueshistoryaction item note追加一条历史记录自动控制 50 条上限set-queuestdin 传 JSON从 triage 输出更新queueitems/nearMisses/topAction/generatedAtset-hotspotsstdin 传 JSON从热点检测输出更新hotspotsfiles/generatedAt实现细节值得注意set-queue与set-hotspots通过 stdin 读取 JSONreadFileSync(0, utf-8)解析失败会向 stderr 报错并以非零码退出见 state.ts因此用法是管道形式node --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/triage.ts | \ node --no-warnings .agents/skills/nemoclaw-maintainer-day/scripts/state.ts set-queue每次写入都会自动刷新updatedAt为当前 ISO 时间。exclude的reason参数支持空格args.slice(1).join( )因此“原因”中可以包含多词描述。状态文件在维护循环中的完整流转结合 SKILL.md 的流程状态文件贯穿维护循环的各个阶段Step 1 检查版本进度运行version-target.ts与version-progress.ts前者读取本地最新 semver tag 并 bump patch 得到目标版本同时扫描带旧版本标签的开放 PR/Issue 作为“stragglers”见 version-target.ts。Step 2 选择一个动作triage 依据excluded过滤已排除条目生成queue与nearMisses随后通过set-queue写入状态文件。Step 3 执行根据动作类型走 MERGE-GATE.md批准、SALVAGE-PR.md抢救等分工作流。批准前必须运行受信任的闸门检查器run-trusted-check-gates.sh——该检查器本身也被shared.ts的RISKY_PATTERNS列为风险文件改动它需要测试覆盖见 shared.ts。Step 4 汇报进度重新运行version-progress.ts展示更新并用state.ts history追加本次动作记录。若目标版本全部完成可建议进入nemoclaw-maintainer-eveningSkill。状态文件还服务于/loop集成场景/loop 10m /nemoclaw-maintainer-day会周期性触发维护循环此时“Readstate.jsonto avoid repeated context”成为避免重复上下文的关键手段——queue与hotspots的跨运行缓存正是为此设计。实践要点与边界条件永远不要打开autoMerge循环的最高权限是 approve合并是独立决策必须由用户执行。排除项是持久化的“硬过滤”被排除的 PR/Issue 会被 triage 无条件跳过只有用户主动unexclude才会重新进入队列。因此exclude时应提供清晰的原因。history 是审计线索每个动作都应留痕且保持 50 条以内的滚动窗口旧条目优先删除。queue与hotspots是“最近一次”快照它们只反映最近一次 triage/hotspot 运行跨运行对比时要注意generatedAt的时间差异避免用旧快照做新决策。风险代码的测试闸门testsForTouchedRiskyCode与shared.ts中的风险模式安装脚本、onboard 逻辑、blueprint、policy/credential/inference 相关路径等联动——触及风险文件的 PR 必须先有测试这是批准的前置条件之一。结语.nemoclaw-maintainer/state.json虽是一个小文件却是 NemoClaw 维护者自动化体系的地基它以gates划定自主边界以excluded表达人为干预以queue/hotspots缓存分析结果以activeWork支持中断恢复以history留下审计轨迹。理解这份 Schema就等于理解了维护循环“如何记住自己做过什么、正在做什么、以及被允许做什么”。在实现层面STATE-SCHEMA.md 与 state.ts 一一对应是阅读维护者工具链代码时最值得首先掌握的入口。【免费下载链接】NemoClawRun agents like Hermes, LangChain Deep Agents, and OpenClaw more securely inside NVIDIA OpenShell with managed inference项目地址: https://gitcode.com/gh_mirrors/ne/NemoClaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考