Munder Difflin 代理环境元数据查询：`agent-env.cjs` 与 `cwdValid` 落地指南

Munder Difflin 代理环境元数据查询agent-env.cjs与cwdValid落地指南【免费下载链接】munder-difflinA local multi-agent harness that works with your existing Claude Code, Codex subscriptions, allows you to run an office of agents项目地址: https://gitcode.com/GitHub_Trending/mu/munder-difflin本指南讲解 munder-difflin 这套本地多代理multi-agent协调系统中每个代理在哪里运行这一问题它以 tools/AGENT-ENV.md 为设计文档通过 spawn 期的cwdValid校验src/main/hive.ts与无依赖 CLI tools/agent-env.cjs 两个部分组成一套文档化、非敏感的代理环境元数据查询方案。读完本文你将掌握如何用node tools/agent-env.cjs查询任一 hive 代理的工作目录、会话标识与实时遥测理解cwdValid的校验语义并能用一条命令安全地完成在某个同伴旁边重新拉起一个代理respawn的实战操作。背景为什么需要可靠的代理工作目录munder-difflin 的 roster花名册已经能暴露每个代理的 token 消耗、成本、熔断器breaker与状态但它并不提供可靠且经过校验的每个代理在哪里运行视图。这个问题在以下场景中会直接变成事故在某个同伴peer旁边重新拉起一个 worker需要的是一个已知良好的绝对路径 cwd如果 cwd 是像ClaudeTerminalHarness这样的非绝对片段spawn 会落到一个不存在的目录上进程直接启动失败这些数据其实早已存在于registry.json/fleet.json中但没有任何东西去校验它也没有一个干净的出口把它暴露出来。于是设计文档给出了答案两块互补的机制——spawn 期打桩校验写入cwdValid加上一个只读查询 CLItools/agent-env.cjs。第一部分spawn 期打桩 ——cwdValidsrc/main/hive.ts校验语义与 spawn 完全一致的三条规则ensureAgent()在注册代理时会对meta.cwd做校验并把结果以cwdValid字段持久化到 registry 条目上让 roster 能可靠地暴露每个 worker 的环境有效性。核心实现在private cwdValidity()src/main/hive.ts校验规则与真实 spawn 的行为完全一致输入情况validissuecwd 缺失null/ 非字符串 / 空串falsemissing相对路径isAbsolute失败falsenot-absolute绝对路径但 stat 成功且不是目录falsenot-a-directory绝对路径但 stat 抛错目录不存在falsemissing-dir绝对路径且存在为目录truenull值得注意的两个防御细节~展开defense-in-depth校验前先用expandTilde()展开 cwd。设计动机是早期 registry 条目在摄入期展开之前写入的里的~/…会永远被判为not-absolute导致代理永远无法 spawn。展开后再判roster 报告的是spawn 实际会用到的那个目录的真相而不是用户手打的字符串。best-effort绝不抛异常stat 失败一律降级为 invalid校验本身从不 throwspawn 行为不受影响。注册时的完整落盘流程在 ensureAgent() 中校验结果被合入 registry 的 upsert先把 prior 条目 spread 进来再合并保留sessionId等 spawn meta 不携带的字段保证--resume重启不会开新会话线写入cwdValid: cwd.valid并把archived清掉、lastSeen更新校验通过时不写任何额外日志只有 cwd 无效罕见情况才追加一条cwd_invalid活动日志src/main/hive.ts绝不会每条 spawn 都打一行因此不会刷屏。cwd 摄入的唯一入口在 spawn 核心spawnAgentCore()src/main/index.ts是所有 spawn 必经的单一入口pty:spawnIPC 与 god 触发的临时 worker watcher 都会经过它它在此处把用户输入的~/dev/foo展开成绝对路径后再进入 hive 供给这就是 registry 里永远是绝对 cwd cwdValid: true的根本保证。该展开值还会回传给调用方让 renderer 记录到同一个绝对路径。测试如何锁定这条保证test/hive-cwd.test.cjs 用三个用例锁定了这条不变量a ~/… cwd is expanded before it reaches the registry注册cwd: ~后registry 中必须是os.homedir()的解析结果且path.isAbsolute(cwd) true、cwdValid truean absolute cwd is unchanged绝对路径原样落库cwdValidity repairs a ~ left in an older registry老 registry 里的~读取时判为 valid但~/definitely-not-here-xyz仍判 invalid——展开不能掩盖真正缺失的目录相对路径relative/path依然判错不会被悄悄解析。第二部分查询助手 —— tools/agent-env.cjs设计目标无依赖、只读、非敏感这是一个dependency-free零第三方依赖的 Node CLI只用fs与path两个内置模块从任意目录都能运行。它读取 hive 的权威状态为每个代理输出一条干净、非敏感的记录。数据源只有两个、且都是只读源码头注释 tools/agent-env.cjs 明确声明无打桩、无日志刷屏文件提供内容registry.json权威 rostercwd、cwdValid、sessionId、provider、role、statusfleet.json实时遥测breaker、lastTool、lastActiveSecAgo、inboxBacklog完整命令参考node tools/agent-env.cjs # 表格仅活跃非 archived代理 node tools/agent-env.cjs --all # 表格包含已归档代理 node tools/agent-env.cjs agent-id # 单个代理pretty JSON node tools/agent-env.cjs --json [--all] # JSON 数组输出到 stdout node tools/agent-env.cjs --snapshot # 同时写入 hive/shared/agent-env.json node tools/agent-env.cjs --hive dir # 覆盖 hive 根目录hive 定位顺序--hive dir优先其次读$HIVE_ROOT环境变量tools/agent-env.cjs。退出码约定找不到指定代理 / 定位不到 hive 时返回2否则为0registry 或 fleet 损坏时永不抛异常降级为空结果。字段清单每条记录包含tools/agent-env.cjs身份id、name、provider终端/CLI 引擎claude / codex / crush 等、role、isGod、archived环境cwd、cwdValid、cwdIssuenot-absolute/missing-dir/not-a-directory/missing有效时为null会话sessionId非机密的claude --resume键null表示从未启动过、status、lastSeen实时遥测来自 fleet.json未运行过的代理为nullbreaker、lastTool、lastActiveSecAgo、inboxBacklog。兼容新旧 registry 的双路径校验这是实现里最值得讲的一点tools/agent-env.cjsCLI 对cwdValid采取优先信任 harness 持久化标志否则回退到活体路径检查的策略——const valid typeof a.cwdValid boolean ? a.cwdValid : cs.valid;cwdState()在 CLI 侧以与 spawn 相同的方式重新做一遍路径判定绝对 存在且为目录。这意味着新 registry 直接读落库标志老 registry没有cwdValid字段也能得到同样的正确结论CLI 对两类数据源都成立。归档过滤也有讲究指定--all或显式给出agent-id时不过滤 archived保证已归档代理其终端已关、但工作目录与记忆仍在依然可查询。实战respawn 配方设计文档给出的核心场景——复制一个同伴的有效cwd 用于新 spawnnode tools/agent-env.cjs peer-id | grep cwd # - 得到已知良好的目录把这条命令输出的绝对目录填入新代理的 cwd 即可从源头杜绝spawn 到不存在目录这类静默失败。数据存储读什么、写什么CLI只读取registry.jsonfleet.json两者已在磁盘上不引入任何热路径写入。唯一的写动作来自--snapshot在hive/shared/agent-env.json写入一份静态、可再生成的快照orchestrator编排器可以直接读取这份文件而不必自己解析 registry快照头部带generatedBy: tools/agent-env.cjs与ts时间戳便于追溯。此外cwdValid只会在ensureAgent()的 registry upsert 时落盘属于低频写与 snapshot 一样不会造成日志或 IO 噪音。安全边界非敏感输出CLI 的安全承诺tools/agent-env.cjs只读registry.jsonfleet.json不触碰 secret store、进程环境变量或任何密钥材料永不打印文件内容、凭据或 API key输出只有目录路径 非机密会话元数据sessionId是 resume UUIDregistry.json 中本就明文存储不是凭据。这份安全边界在项目其他地方同样被贯彻主进程的hive:agentDirectoryIPCsrc/main/index.ts以同样的PII-free原则合并 registry、实时 token、breaker、上下文占用等字段供语音读取层使用注释同样声明没有机密、env 或 API key 会离开主进程。生态位谁在消费这些元数据cwdValid与代理环境元数据在项目中有多个消费方可作深入阅读入口roster 侧AgentMeta接口声明了cwdValid?: booleansrc/preload/index.ts渲染层据此在界面展示语音读取层Realtime 的get_agent_detail工具src/renderer/src/realtime/tools.ts会把 cwd 念给用户并在cwdValid false时明确补一句该目录无效在那里 spawn 会失败主进程目录快照hive:agentDirectory将cwdValid、sessionId、breaker、contextPct等合并进每个代理的非敏感目录src/main/index.ts并刻意包含 archived 代理与 live-only 的 fleet.json 心跳不同使编排器能与未活跃代理对话、仍能触达其 cwd 与记忆。小结cwdValidagent-env.cjs构成了 munder-difflin 中代理运行环境这一横切面的最小闭环spawn 期在源头校验并持久化src/main/hive.ts查询期用无依赖 CLI 输出非敏感元数据tools/agent-env.cjs测试锁定绝对 cwd ~展开 不掩盖真实缺失的不变量test/hive-cwd.test.cjs设计动机与边界则在 tools/AGENT-ENV.md 中完整记载。对于需要编排、重启或复制同伴环境的运维场景记住三件事即可cwd 必须绝对、目录必须存在、--snapshot可以把权威视图落成 orchestrator 可直接消费的静态文件。【免费下载链接】munder-difflinA local multi-agent harness that works with your existing Claude Code, Codex subscriptions, allows you to run an office of agents项目地址: https://gitcode.com/GitHub_Trending/mu/munder-difflin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考