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），加上一个只读查询 CLI（tools/agent-env.cjs）。
第一部分：spawn 期打桩 ——cwdValid（src/main/hive.ts）
校验语义：与 spawn 完全一致的三条规则
ensureAgent()在注册代理时会对meta.cwd做校验，并把结果以cwdValid字段持久化到 registry 条目上，让 roster 能可靠地暴露每个 worker 的环境有效性。核心实现在private cwdValidity()（src/main/hive.ts），校验规则与真实 spawn 的行为完全一致：
| 输入情况 | valid | issue |
|---|---|---|
cwd 缺失（null/ 非字符串 / 空串） | false | missing |
相对路径（isAbsolute失败） | false | not-absolute |
| 绝对路径但 stat 成功且不是目录 | false | not-a-directory |
| 绝对路径但 stat 抛错（目录不存在） | false | missing-dir |
| 绝对路径且存在为目录 | true | null |
值得注意的两个防御细节：
~展开（defense-in-depth）：校验前先用expandTilde()展开 cwd。设计动机是：早期 registry 条目（在摄入期展开之前写入的）里的~/…会永远被判为not-absolute，导致代理永远无法 spawn。展开后再判，roster 报告的是"spawn 实际会用到的那个目录"的真相，而不是用户手打的字符串。- best-effort，绝不抛异常：stat 失败一律降级为 invalid，校验本身从不 throw，spawn 行为不受影响。
注册时的完整落盘流程
在 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 === true；an 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 | 权威 roster：cwd、cwdValid、sessionId、provider、role、status |
fleet.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，否则为0；registry 或 fleet 损坏时永不抛异常，降级为空结果。
字段清单
每条记录包含（tools/agent-env.cjs）：
- 身份：
id、name、provider（终端/CLI 引擎：claude / codex / crush 等）、role、isGod、archived； - 环境：
cwd、cwdValid、cwdIssue（not-absolute/missing-dir/not-a-directory/missing，有效时为null）； - 会话：
sessionId（非机密的claude --resume键，null表示从未启动过）、status、lastSeen； - 实时遥测（来自 fleet.json，未运行过的代理为
null）：breaker、lastTool、lastActiveSecAgo、inboxBacklog。
兼容新旧 registry 的双路径校验
这是实现里最值得讲的一点（tools/agent-env.cjs）：CLI 对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 用于新 spawn：
node tools/agent-env.cjs <peer-id> | grep cwd # -> 得到已知良好的目录把这条命令输出的绝对目录填入新代理的 cwd 即可，从源头杜绝"spawn 到不存在目录"这类静默失败。
数据存储：读什么、写什么
CLI只读取registry.json+fleet.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.json+fleet.json；不触碰 secret store、进程环境变量或任何密钥材料； - 永不打印文件内容、凭据或 API key；输出只有目录路径 + 非机密会话元数据；
sessionId是 resume UUID（registry.json 中本就明文存储），不是凭据。
这份安全边界在项目其他地方同样被贯彻：主进程的hive:agentDirectoryIPC（src/main/index.ts）以同样的"PII-free"原则合并 registry、实时 token、breaker、上下文占用等字段供语音读取层使用，注释同样声明"没有机密、env 或 API key 会离开主进程"。
生态位：谁在消费这些元数据
cwdValid与代理环境元数据在项目中有多个消费方，可作深入阅读入口：
- roster 侧：
AgentMeta接口声明了cwdValid?: boolean（src/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 与记忆。
小结
cwdValid+agent-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），仅供参考
