尧图网页设计 
【免费下载链接】firstmateTalk to one agent. Ship with a crew.项目地址https://gitcode.com/gh_mirrors/fi/firstmate点击查看免费下载本文解析 Firstmate 内置的原生 W3Ctraceparent传播能力它如何在每次 spawn 时为任务解析唯一的 trace carrier、以TRACEPARENT环境变量注入代理 pane、并原样记录到任务元数据使外部观测者能以一条任务一条 trace的粒度关联该任务运行的一切。读完本文你将掌握该能力的配置方式config/trace-context与FM_TRACE_CONTEXT、会话级启用边界、root 与 recovery 语义、远程 Secondmate 路由的跨主机载体传递以及支撑它的完整验证证据链。能力定位默认关闭、源码自有、厂商中立Firstmate 的持久化运行工件已经能让下游观测者推导出逻辑任务身份与生命周期唯一无法在启动后重建的源码级信息是在启动前注入代理环境、并以同一身份记录在任务元数据中的任务级 trace id。该特性只补上这一条载体缝隙carrier seam不引入任何 collector、存储、UI 或厂商耦合。它的核心行为是启用时每次 spawn 为任务解析一个 W3Ctraceparent载体——任务首次 spawn 时铸成全新根relaunch 时从元数据原样复用——然后以00-32 位 hex trace id-16 位 hex span id-2 位 hex flags形式构成载体新根使用随机 id通过与GOTMPDIR相同的spawn_send_text_line通道在启动前立即注入 pane shell 的环境变量TRACEPARENT将完全相同的值记录为state/id.meta中的traceparent字段。因为注入的载体与记录的载体是同一个字符串观测者读取元数据即可精确重建子代理实际收到的身份。该特性自身不产生任何 SDK span。需要特别注意一个命名约定TRACEPARENT环境变量是 Firstmate 自有的约定承载 W3C 格式的 traceparent 值。W3C Trace Context 标准化的对象是traceparentHTTP 头而非环境变量OpenTelemetry SDK 也不会自动从环境读取它因此下游观测者或埋点必须显式读取该环境值或traceparent元数据字段。覆盖范围与注入位置载体注入位于无条件的启动前导出位点pre-launch export site因此覆盖 ship 与 scout spawn 的claude、codex、opencode、pi、pi-signed、grok、kimi、cursor、gemini、muse、rovo、agy、devin全部适配器以及 Secondmate spawn 中除故意仅限 crewmate 的gemini、muse、rovo、agy、devin之外的同一批适配器——与GOTMPDIR现有覆盖完全一致且无需任何 trace 专属的launch_template()行为。在 bin/fm-spawn.sh 的解析逻辑中可以看到这一位点的具体实现fm_trace_context_session_effective读取冻结的会话决策on时调用fm_trace_context_resolve解析单一载体off时载体为空。随后在 bin/fm-spawn.sh非空载体通过spawn_send_text_line $T export TRACEPARENT$SPAWN_TRACEPARENT在启动命令之前送达 pane并在成功后由spawn_record_traceparent原子写入元数据。若启用config/launch-env-allowlist的env -i环境边界TRACEPARENT也会被纳入透传的固定运营层见 bin/fm-spawn.sh。后端覆盖方面ship 与 scout 的 spawn 在所有后端tmux、herdr、zellij、orca、cmux上都会到达该位点Secondmate 只在接受 Secondmate spawn 的后端tmux、herdr、zellij上到达因为 bin/fm-spawn.sh 会在orca与cmux上拒绝 Secondmate。配置presence 文件与环境变量覆盖配置 schema 由 docs/configuration.mdTrace context propagation 一节定义config/trace-contexthome 配置目录下的可选本地存在性标记文件gitignored存在即启用默认关闭的原生 W3C trace-context 传播。FM_TRACE_CONTEXT环境变量覆盖文件。1/on/true/yes启用任何其他非空值禁用unset 或空值则让位于文件空等同未设置的约定行为。这个优先级映射在 bin/fm-trace-context-lib.sh 的fm_trace_context_enabled中非空FM_TRACE_CONTEXT先小写归一后匹配1|on|true|yes命中即启用否则禁用无覆盖时以config/trace-context文件存在与否决定。tests/fm-trace-context-lib.test.sh验证了该优先级——FM_TRACE_CONTEXT覆盖文件、unset 或空时回退文件。会话级启用边界一次解析、全程冻结启用状态是home 会话级的而非逐次读取。每次加锁的bin/fm-session-start.sh运行恰好解析一次该 home 的config/trace-context与FM_TRACE_CONTEXT得到会话级有效状态。在 bin/fm-session-start.sh只有取得锁的完整 session start 才调用fm_trace_context_session_start写入有效状态锁被拒绝的只读 start 保持其不变。有效状态的发布是原子化的通过同目录临时文件mktemp $effective_file.tmp.XXXXXX写入再mv -f原子替换到state/.trace-context-effective记录绑定当前会话锁记录lock_pid value两字段因此失败的发布无法重新激活上一会话遗留的陈旧on记录——这正是 bin/fm-trace-context-lib.sh 中fm_trace_context_session_start的设计每个 spawn 通过fm_trace_context_session_effective只读该冻结的on/off决策记录中的锁 pid 与当前锁一致、值为on、无多余字段时输出on否则一律off见 bin/fm-trace-context-lib.sh。缺失、陈旧、不可读、无效或发布失败的有效状态安全地默认off。此后对配置或环境的任何修改都被忽略直到该 home 开启新会话。因此要跨整个 fleet 变更设置必须手动做一次全量 fleet 重启让每个 home 开启新会话并冻结新决策Firstmate 不监控设置漂移、不检测不匹配、不拒绝启动、也不会自动停止或重启任何 home。Root 与 Recovery任务即 trace 边界整套规则的目的是每条任务一条 trace绝不合并无关任务也绝不为同一任务铸造第二个身份。Root铸根任务 meta 中没有有效记录载体时spawn 铸造全新 trace id、全新 span id 和 sampled 标记01开启一条新 trace——每条任务一条。spawn 进程自身的环境TRACEPARENT永不被采纳那是该进程启动时收到的代理身份持久 Secondmate 会终生保留它同时路由大量无关任务若采纳它每个 Secondmate 路由的所有任务都会被串成一条不断增长的 trace。这正是 bin/fm-trace-context-lib.sh 头注释所强调的环境只是它自己启动时收到的身份绝不是新任务的父级。Recovery恢复任务 meta 中已记录的有效traceparent被原样复用字节级一致含 flags因此 relaunch 或恢复的任务跨重启保持单一稳定身份而不是另起第二条 trace损坏的记录值则重新铸根而非传播这是再铸根不是省略。因为环境TRACEPARENT永不被读取supervisor 恰好运行在什么环境下——Secondmate 的启动期载体、或操作员 shell 残留的TRACEPARENT——都无法泄漏进新任务身份。关闭传播则是有意的 trace 边界被禁用的 home 即使任务 meta 已有有效traceparent也不会给新启动或 relaunch 的代理注入任何载体真实的禁用 relaunch 会重生成不含traceparent的任务 meta因此后续启用 relaunch 会铸造新 trace 而非恢复边界前的身份。复用已存活的远程端点不算 relaunch会保留该代理已持有的载体。远程 Secondmate 路由载体跨主机传递远程路由上的 Secondmate 永远不会到达父进程本地的导出位点父进程将启动交给配置的主机由该主机运行自己的bin/fm-spawn.sh。但身份仍归父进程所有——父 home 持有观测者读取的任务元数据。因此父进程基于该任务自己的 meta在自身的冻结决策下解析载体——relaunch 原样复用、否则全新铸根、永不采纳父进程环境的TRACEPARENT通过--traceparent参数见 bin/fm-spawn.sh交给远程主机远程主机在同一个无条件导出位点导出它并把端点实际持有的载体返回父进程父进程记录该返回值——这样已存活、未被 relaunch 的远程端点报告的是代理真正收到的身份而非父进程单方面打算给的身份见 bin/fm-spawn.sh。远程主机在载体能到达任何 pane 之前必须按严格 W3C 值校验它--traceparent只对--secondmatespawn 有效ship spawn 上直接拒绝shell 元字符值、全零 trace id、空值均被拒绝bin/fm-spawn.sh。被禁用的父进程不传递任何载体远程启动与未追踪时逐字节一致。若端点已存活不发生新启动或注入但父进程仍记录端点报告的任何载体——即使父进程当前决策为off也不能让元数据否认运行中代理的真实身份。启用决策与本地路径一样随行传递远程 home 将config/trace-context作为声明的可继承材料FM_INHERITABLE_CONFIGtrace-context见 bin/fm-spawn.sh继承新 Secondmate 进程则收到父进程冻结的FM_TRACE_CONTEXTon|off快照。Secondmate 传播传递启用决策绝不传递 trace 身份primary 启动 Secondmate本地或远程时把config/trace-context传播进 Secondmate home并把 primary 会话的冻结决策作为非空的FM_TRACE_CONTEXTon|off启动覆盖传入。在 bin/fm-spawn.sh该值被归一化为字面on/off而非原始字符串目的是让 primary 上的FM_TRACE_CONTEXT覆盖真正抵达 Secondmate 自己的 worker——否则仅靠拷贝的配置文件off无法禁用、on也无法启用跨启动边界的行为。该快照与载体解析复用的是同一个冻结决策因此注入载体与快照必然一致。Secondmate 在自己 home 会话启动时解析该继承覆盖。该标志是会话级启用而非持久配置因此在启动收敛点冻结决策随之移交之处传递且不受对已运行 home 的 live 收敛影响本地与远程路由一致。关键界限传播的是启用决策绝不是 trace 身份。启用状态下启动的 Secondmate 从 primary 收到自己的任务载体——即 Secondmate 代理自身的身份Secondmate 自己被 relaunch 时原样复用——它 spawn 的每个 worker 则各自铸根自己的任务级 trace。禁用状态下启动的 Secondmate 即使 home 里存在config/trace-context其 worker 也保持未追踪。重复 Secondmate 启动在 trace-context 继承之前即被拒绝因此重复启动预检不会改动 Secondmate home。采样语义新根固定01新根将 W3C trace flags 设为01sampled这是有意且源码自有的选择opt-in 且默认关闭启用该能力的 home 就是在请求其 spawn 被追踪若铸成未采样00根多数下游 parent-based sampler 会丢弃该 trace id让主动 opt-in 的操作员什么都拿不到。记录载体原样保留 flagsrecovery 逐字节复用任务记录载体包括 flags因此任务的采样决策跨重启稳定Firstmate 只在铸根时选择 flag而铸根是新建载体的唯一途径。成本与隐私后果01记录的是采样决策符合规范的 parent-based sampler 会尊重它——但它本身不保证任何 collector 存储 spanFirstmate 也不产出自己的 span只在载体上设置 flag。启用该能力并把采样感知埋点指向它的操作员应预期大致每条任务一条 trace被记录具体基数与保留期取决于埋点的配置。想要未采样根或头部采样的操作员需自行在下游处理或等待未来显式作用域的选项Firstmate 不内嵌 sampler。安全边界默认关闭、暴露受限、故障独立、仅元数据默认关闭无config/trace-context且无FM_TRACE_CONTEXT时全新 spawn 或真实 relaunch 不注入任何东西、也不写traceparent行生成的 meta 与启动环境不变。复用已存活的远程端点会记录端点报告的任何载体但不会注入新载体。加锁的会话启动只做一次配置文件检查、每个 spawn 多 source 一个库并读取冻结有效状态文件因此进程并非字面逐字节一致但代理、观测者与任务 meta 能看到的任何东西都没有差异。暴露范围Firstmate 铸造的根使用随机 id不读取 prompt、路径、任务文案、凭证或任意环境键因此 Firstmate 永不在载体中originate敏感数据。注入的每个载体要么是这种铸根、要么是同一任务此前记录载体的原样复用环境TRACEPARENT永不读取调用方可控字节无法进入新载体。暴露被限定在定宽载体本身——它无法携带tracestate、OTEL_*凭证变量或任意环境键也没有可配置或任意的命令只有固定本地的od/tr用于熵。故障独立铸根是一条小型本地熵管道——通过 PATH 解析的固定本地od与tr从/dev/urandom读取少量字节bin/fm-trace-context-lib.sh无配置的 provider 命令、无网络、无 watchdog。正常开销很小但od/tr是外部进程因此没有硬性延迟保证——不是可保证可忽略的上界。任何返回的熵或自校验失败都会为该 spawn 省略载体且不中止源工作损坏的记录载体是再铸根而非省略。启动前载体导出失败时Firstmate 省略traceparent元数据声明并照常启动任务后端报告失败 trace 输入无法清除时Firstmate 拒绝追加启动命令绝不冒险带着未知的部分载体启动导出后记录载体失败时Firstmate 在启动命令中unset TRACEPARENT并照常启动任务子代理绝不会收到元数据中不存在的身份。仅元数据值只存在于易失的 pane shell 与state/id.meta中teardown 照旧移除状态因此没有新的持久化表面也没有 schema 迁移。与 OpenTelemetry 及后续演进的关系Firstmate 不学习任何关于 OpenTelemetry、exporter、collector、存储或 UI 的知识。它只发出标准 W3C 载体并记录同一身份下游观测者拥有其余一切并能从 home 会话的冻结决策或traceparent字段发现活跃传播。原生生命周期事件发射、额外稳定 ID、intake 元数据与任何内嵌 OTLP 都被刻意推迟直到运行中的观测者展示出派生工件无法覆盖的具体保真度缺口。验证证据三套可重复测试bin/fm-trace-context-lib.sh 的头注释拥有精确机制的所有权而 docs/verification/trace-context.md 记录了可重复的测试证据。当前行为与原理的权威说明在 docs/trace-context.md配置 schema 在 docs/configuration.mdTrace context propagation。从仓库根目录运行三套 trace-context 套件每套每个断言打印一行ok - ...$ bash tests/fm-trace-context-lib.test.sh | tail -1 # fm-trace-context-lib.test.sh: all assertions passed $ bash tests/fm-trace-context-spawn.test.sh | tail -1 # all fm-trace-context-spawn tests passed $ bash tests/fm-remote-secondmate-trace-context.test.sh | tail -1 ALL TESTS PASSED单元套件26 个断言同目录的 tests/fm-trace-context-lib.test.sh26 断言是纯函数测试无后端、无真实 spawn覆盖校验合法值接受畸形、错误长度、大写、全零、ff版本、shell 元字符值均拒绝。测试用的合法样本是00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01tests/fm-trace-context-lib.test.sh非法样本包括命令替换形状的值$(touch ...)验证其作为惰性数据被拒绝且永不被执行铸根每次 mint 都是互不相同的 sampled 根且无父级采纳输入——flags 恒为01、trace id 非全零、长度与字符集精确恢复复用路径记录载体胜过环境载体环境永不读取默认关闭省略不注入、不写traceparent启用优先级FM_TRACE_CONTEXT覆盖config/trace-contextunset 或空回退文件归一化的 home 会话状态、只读旧记录的原子替换、发布失败后的陈旧会话拒绝、缺失或无效状态默认 offSecondmate home 会话边界后者文件状态优先与任务级 trace 边界同一持久环境TRACEPARENT根下连续两次 resolve 得到两条互异 trace且两者都不采纳环境根强制熵失败安全省略与铸根定形校验。spawn 路径集成套件12 个断言tests/fm-trace-context-spawn.test.sh12 断言对环境FM_TRACE_CONTEXT密闭hermetic用假 tmux pane 和真实隔离 git worktree 端到端驱动 bin/fm-spawn.sh覆盖启用时解析出的唯一载体以traceparent记录在 meta且仅当完全相同的TRACEPARENTexport 在启动字面量之前发送禁用时两者均不写不送GOTMPDIR照常载体投递失败时不留下traceparent声明源任务仍启动不安全的投递部分输入无法清除在追加启动命令前停止meta 追加失败时从启动任务中移除载体但不中止它重复 Secondmate 预检保持继承的 trace 配置不变relaunch 原样复用记录载体spawn 忽略之后的配置与环境编辑以冻结的 home 会话决策为准。任务级边界回归精确建模了被评审的 Secondmate 场景同一 home 顺序 spawn 两个无关任务而同一固定TRACEPARENT常驻 spawn 环境持久 Secondmate 的启动期载体两任务记录并注入的合法载体 trace id 互不相同、也与环境载体不同第一任务 relaunch 则对 meta 记录与注入 export 原样复用其原始载体。另有两条断言驱动真实的两级 primary → Secondmate → worker 链用 primary 注入 Secondmate 的精确环境连跑两次bin/fm-spawn.sh双向证明 primary 的有效覆盖治理嵌套 worker环境开且无配置文件时嵌套 worker 保持启用且铸根自己的任务级 trace与 Secondmate 的载体互异环境关且文件存在时嵌套 worker 保持禁用——即使config/trace-context已被拷贝进 Secondmate home。最后一条断言驱动文件决定路径FM_TRACE_CONTEXTunset证明 Secondmate 记录/注入的载体与其收到的FM_TRACE_CONTEXTon|off快照永远出自同一次冻结决策载体绝不会与相反的启用状态配对。该套件不触碰任何真实 harness 或 live fleet。tests/fm-session-start.test.sh 额外证明只有持锁的会话启动会写入有效状态锁被拒绝的只读启动保持其不变。远程路由套件6 个断言tests/fm-remote-secondmate-trace-context.test.sh6 断言覆盖永不抵达本地导出位点的 Secondmate 路径驱动真实链路——父进程的bin/fm-spawn.sh、bin/fm-on.sh、真实远程入口、bin/fm-remote-secondmate-control.sh与远程主机自己的bin/fm-spawn.sh——经确定性 SSH 边界、以有状态假 Herdr CLI 作为后端远程 Secondmate 始终运行的后端远程 pane 收到的载体从其 pane 自身日志读回禁用父进程不记录traceparent、远程 pane 收不到 export、远程 home 不继承启用标志、交付快照为FM_TRACE_CONTEXToff而GOTMPDIR照常送达启用父进程记录载体、远程端点自身记录、导出的 pane 值三者为同一合法载体在GOTMPDIR之后、启动命令之前发送FM_TRACE_CONTEXTon与继承标志一并交付relaunch 在父记录与 pane export 中均原样保留该载体第二条远程路由在持有固定环境TRACEPARENT的环境中解析铸根出的 trace id 与那条环境载体及第一条路由均不同远程接收方把config/trace-context当作普通声明的可继承材料接受却拒绝config/secondmate-harnessprimary 刻意不传播的文件携带父载体到远程主机的投递参数在 ship spawn、shell 元字符值、全零 trace id 与空值上均被拒绝——因此只有 Secondmate 启动时的严格 W3C 载体能到达 pane export。最后一个单一的 live 后端端到端人工检查——真实 spawn 确认 pane 在启动行之前收到TRACEPARENTexport、teardown 后无残留——是受边界约束的人工步骤此处推迟因为 live 代理 spawn 会扰动运行中的 fleet。这正是该能力源码证据完备、live 证据按需人工执行的验证哲学三套自动化套件不触碰真实 fleet却足以锁定行为契约。赞分享【免费下载链接】firstmateTalk to one agent. Ship with a crew.项目地址https://gitcode.com/gh_mirrors/fi/firstmate点击查看免费下载相关推荐OpenTelemetry Go分布式追踪原理解析Span、Context与传播机制OpenTelemetry Go分布式追踪原理解析Span、Context与传播机制 1. 分布式追踪核心痛点与解决方案 在微服务架构中一个请求往往需要经过可观测性Next.js 分布式追踪实战基于 Highlight 的 W3C Trace Context 全链路接入与源码解析Next.js 分布式追踪实战基于 Highlight 的 W3C Trace Context 全链路接入与源码解析 本篇指南围绕 Next.js 应用中分布可观测性后端ggplot2图表字体优化指南hrbrthemes字体系统全面详解ggplot2图表字体优化指南hrbrthemes字体系统全面详解 hrbrthemes是一个专注于ggplot2图表字体优化的R语言主题系统它通过精心设计UI库/组件数据分析上一篇YimMenu完整指南免费GTA5增强工具与安全防护系统下一篇Konsta UI入门指南5分钟快速搭建移动端应用界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Firstmate 原生 W3C Trace-Context 传播：任务级分布式追踪的默认关闭缝合机制
【免费下载链接】firstmateTalk to one agent. Ship with a crew.项目地址https://gitcode.com/gh_mirrors/fi/firstmate点击查看免费下载本文解析 Firstmate 内置的原生 W3Ctraceparent传播能力它如何在每次 spawn 时为任务解析唯一的 trace carrier、以TRACEPARENT环境变量注入代理 pane、并原样记录到任务元数据使外部观测者能以一条任务一条 trace的粒度关联该任务运行的一切。读完本文你将掌握该能力的配置方式config/trace-context与FM_TRACE_CONTEXT、会话级启用边界、root 与 recovery 语义、远程 Secondmate 路由的跨主机载体传递以及支撑它的完整验证证据链。能力定位默认关闭、源码自有、厂商中立Firstmate 的持久化运行工件已经能让下游观测者推导出逻辑任务身份与生命周期唯一无法在启动后重建的源码级信息是在启动前注入代理环境、并以同一身份记录在任务元数据中的任务级 trace id。该特性只补上这一条载体缝隙carrier seam不引入任何 collector、存储、UI 或厂商耦合。它的核心行为是启用时每次 spawn 为任务解析一个 W3Ctraceparent载体——任务首次 spawn 时铸成全新根relaunch 时从元数据原样复用——然后以00-32 位 hex trace id-16 位 hex span id-2 位 hex flags形式构成载体新根使用随机 id通过与GOTMPDIR相同的spawn_send_text_line通道在启动前立即注入 pane shell 的环境变量TRACEPARENT将完全相同的值记录为state/id.meta中的traceparent字段。因为注入的载体与记录的载体是同一个字符串观测者读取元数据即可精确重建子代理实际收到的身份。该特性自身不产生任何 SDK span。需要特别注意一个命名约定TRACEPARENT环境变量是 Firstmate 自有的约定承载 W3C 格式的 traceparent 值。W3C Trace Context 标准化的对象是traceparentHTTP 头而非环境变量OpenTelemetry SDK 也不会自动从环境读取它因此下游观测者或埋点必须显式读取该环境值或traceparent元数据字段。覆盖范围与注入位置载体注入位于无条件的启动前导出位点pre-launch export site因此覆盖 ship 与 scout spawn 的claude、codex、opencode、pi、pi-signed、grok、kimi、cursor、gemini、muse、rovo、agy、devin全部适配器以及 Secondmate spawn 中除故意仅限 crewmate 的gemini、muse、rovo、agy、devin之外的同一批适配器——与GOTMPDIR现有覆盖完全一致且无需任何 trace 专属的launch_template()行为。在 bin/fm-spawn.sh 的解析逻辑中可以看到这一位点的具体实现fm_trace_context_session_effective读取冻结的会话决策on时调用fm_trace_context_resolve解析单一载体off时载体为空。随后在 bin/fm-spawn.sh非空载体通过spawn_send_text_line $T export TRACEPARENT$SPAWN_TRACEPARENT在启动命令之前送达 pane并在成功后由spawn_record_traceparent原子写入元数据。若启用config/launch-env-allowlist的env -i环境边界TRACEPARENT也会被纳入透传的固定运营层见 bin/fm-spawn.sh。后端覆盖方面ship 与 scout 的 spawn 在所有后端tmux、herdr、zellij、orca、cmux上都会到达该位点Secondmate 只在接受 Secondmate spawn 的后端tmux、herdr、zellij上到达因为 bin/fm-spawn.sh 会在orca与cmux上拒绝 Secondmate。配置presence 文件与环境变量覆盖配置 schema 由 docs/configuration.mdTrace context propagation 一节定义config/trace-contexthome 配置目录下的可选本地存在性标记文件gitignored存在即启用默认关闭的原生 W3C trace-context 传播。FM_TRACE_CONTEXT环境变量覆盖文件。1/on/true/yes启用任何其他非空值禁用unset 或空值则让位于文件空等同未设置的约定行为。这个优先级映射在 bin/fm-trace-context-lib.sh 的fm_trace_context_enabled中非空FM_TRACE_CONTEXT先小写归一后匹配1|on|true|yes命中即启用否则禁用无覆盖时以config/trace-context文件存在与否决定。tests/fm-trace-context-lib.test.sh验证了该优先级——FM_TRACE_CONTEXT覆盖文件、unset 或空时回退文件。会话级启用边界一次解析、全程冻结启用状态是home 会话级的而非逐次读取。每次加锁的bin/fm-session-start.sh运行恰好解析一次该 home 的config/trace-context与FM_TRACE_CONTEXT得到会话级有效状态。在 bin/fm-session-start.sh只有取得锁的完整 session start 才调用fm_trace_context_session_start写入有效状态锁被拒绝的只读 start 保持其不变。有效状态的发布是原子化的通过同目录临时文件mktemp $effective_file.tmp.XXXXXX写入再mv -f原子替换到state/.trace-context-effective记录绑定当前会话锁记录lock_pid value两字段因此失败的发布无法重新激活上一会话遗留的陈旧on记录——这正是 bin/fm-trace-context-lib.sh 中fm_trace_context_session_start的设计每个 spawn 通过fm_trace_context_session_effective只读该冻结的on/off决策记录中的锁 pid 与当前锁一致、值为on、无多余字段时输出on否则一律off见 bin/fm-trace-context-lib.sh。缺失、陈旧、不可读、无效或发布失败的有效状态安全地默认off。此后对配置或环境的任何修改都被忽略直到该 home 开启新会话。因此要跨整个 fleet 变更设置必须手动做一次全量 fleet 重启让每个 home 开启新会话并冻结新决策Firstmate 不监控设置漂移、不检测不匹配、不拒绝启动、也不会自动停止或重启任何 home。Root 与 Recovery任务即 trace 边界整套规则的目的是每条任务一条 trace绝不合并无关任务也绝不为同一任务铸造第二个身份。Root铸根任务 meta 中没有有效记录载体时spawn 铸造全新 trace id、全新 span id 和 sampled 标记01开启一条新 trace——每条任务一条。spawn 进程自身的环境TRACEPARENT永不被采纳那是该进程启动时收到的代理身份持久 Secondmate 会终生保留它同时路由大量无关任务若采纳它每个 Secondmate 路由的所有任务都会被串成一条不断增长的 trace。这正是 bin/fm-trace-context-lib.sh 头注释所强调的环境只是它自己启动时收到的身份绝不是新任务的父级。Recovery恢复任务 meta 中已记录的有效traceparent被原样复用字节级一致含 flags因此 relaunch 或恢复的任务跨重启保持单一稳定身份而不是另起第二条 trace损坏的记录值则重新铸根而非传播这是再铸根不是省略。因为环境TRACEPARENT永不被读取supervisor 恰好运行在什么环境下——Secondmate 的启动期载体、或操作员 shell 残留的TRACEPARENT——都无法泄漏进新任务身份。关闭传播则是有意的 trace 边界被禁用的 home 即使任务 meta 已有有效traceparent也不会给新启动或 relaunch 的代理注入任何载体真实的禁用 relaunch 会重生成不含traceparent的任务 meta因此后续启用 relaunch 会铸造新 trace 而非恢复边界前的身份。复用已存活的远程端点不算 relaunch会保留该代理已持有的载体。远程 Secondmate 路由载体跨主机传递远程路由上的 Secondmate 永远不会到达父进程本地的导出位点父进程将启动交给配置的主机由该主机运行自己的bin/fm-spawn.sh。但身份仍归父进程所有——父 home 持有观测者读取的任务元数据。因此父进程基于该任务自己的 meta在自身的冻结决策下解析载体——relaunch 原样复用、否则全新铸根、永不采纳父进程环境的TRACEPARENT通过--traceparent参数见 bin/fm-spawn.sh交给远程主机远程主机在同一个无条件导出位点导出它并把端点实际持有的载体返回父进程父进程记录该返回值——这样已存活、未被 relaunch 的远程端点报告的是代理真正收到的身份而非父进程单方面打算给的身份见 bin/fm-spawn.sh。远程主机在载体能到达任何 pane 之前必须按严格 W3C 值校验它--traceparent只对--secondmatespawn 有效ship spawn 上直接拒绝shell 元字符值、全零 trace id、空值均被拒绝bin/fm-spawn.sh。被禁用的父进程不传递任何载体远程启动与未追踪时逐字节一致。若端点已存活不发生新启动或注入但父进程仍记录端点报告的任何载体——即使父进程当前决策为off也不能让元数据否认运行中代理的真实身份。启用决策与本地路径一样随行传递远程 home 将config/trace-context作为声明的可继承材料FM_INHERITABLE_CONFIGtrace-context见 bin/fm-spawn.sh继承新 Secondmate 进程则收到父进程冻结的FM_TRACE_CONTEXTon|off快照。Secondmate 传播传递启用决策绝不传递 trace 身份primary 启动 Secondmate本地或远程时把config/trace-context传播进 Secondmate home并把 primary 会话的冻结决策作为非空的FM_TRACE_CONTEXTon|off启动覆盖传入。在 bin/fm-spawn.sh该值被归一化为字面on/off而非原始字符串目的是让 primary 上的FM_TRACE_CONTEXT覆盖真正抵达 Secondmate 自己的 worker——否则仅靠拷贝的配置文件off无法禁用、on也无法启用跨启动边界的行为。该快照与载体解析复用的是同一个冻结决策因此注入载体与快照必然一致。Secondmate 在自己 home 会话启动时解析该继承覆盖。该标志是会话级启用而非持久配置因此在启动收敛点冻结决策随之移交之处传递且不受对已运行 home 的 live 收敛影响本地与远程路由一致。关键界限传播的是启用决策绝不是 trace 身份。启用状态下启动的 Secondmate 从 primary 收到自己的任务载体——即 Secondmate 代理自身的身份Secondmate 自己被 relaunch 时原样复用——它 spawn 的每个 worker 则各自铸根自己的任务级 trace。禁用状态下启动的 Secondmate 即使 home 里存在config/trace-context其 worker 也保持未追踪。重复 Secondmate 启动在 trace-context 继承之前即被拒绝因此重复启动预检不会改动 Secondmate home。采样语义新根固定01新根将 W3C trace flags 设为01sampled这是有意且源码自有的选择opt-in 且默认关闭启用该能力的 home 就是在请求其 spawn 被追踪若铸成未采样00根多数下游 parent-based sampler 会丢弃该 trace id让主动 opt-in 的操作员什么都拿不到。记录载体原样保留 flagsrecovery 逐字节复用任务记录载体包括 flags因此任务的采样决策跨重启稳定Firstmate 只在铸根时选择 flag而铸根是新建载体的唯一途径。成本与隐私后果01记录的是采样决策符合规范的 parent-based sampler 会尊重它——但它本身不保证任何 collector 存储 spanFirstmate 也不产出自己的 span只在载体上设置 flag。启用该能力并把采样感知埋点指向它的操作员应预期大致每条任务一条 trace被记录具体基数与保留期取决于埋点的配置。想要未采样根或头部采样的操作员需自行在下游处理或等待未来显式作用域的选项Firstmate 不内嵌 sampler。安全边界默认关闭、暴露受限、故障独立、仅元数据默认关闭无config/trace-context且无FM_TRACE_CONTEXT时全新 spawn 或真实 relaunch 不注入任何东西、也不写traceparent行生成的 meta 与启动环境不变。复用已存活的远程端点会记录端点报告的任何载体但不会注入新载体。加锁的会话启动只做一次配置文件检查、每个 spawn 多 source 一个库并读取冻结有效状态文件因此进程并非字面逐字节一致但代理、观测者与任务 meta 能看到的任何东西都没有差异。暴露范围Firstmate 铸造的根使用随机 id不读取 prompt、路径、任务文案、凭证或任意环境键因此 Firstmate 永不在载体中originate敏感数据。注入的每个载体要么是这种铸根、要么是同一任务此前记录载体的原样复用环境TRACEPARENT永不读取调用方可控字节无法进入新载体。暴露被限定在定宽载体本身——它无法携带tracestate、OTEL_*凭证变量或任意环境键也没有可配置或任意的命令只有固定本地的od/tr用于熵。故障独立铸根是一条小型本地熵管道——通过 PATH 解析的固定本地od与tr从/dev/urandom读取少量字节bin/fm-trace-context-lib.sh无配置的 provider 命令、无网络、无 watchdog。正常开销很小但od/tr是外部进程因此没有硬性延迟保证——不是可保证可忽略的上界。任何返回的熵或自校验失败都会为该 spawn 省略载体且不中止源工作损坏的记录载体是再铸根而非省略。启动前载体导出失败时Firstmate 省略traceparent元数据声明并照常启动任务后端报告失败 trace 输入无法清除时Firstmate 拒绝追加启动命令绝不冒险带着未知的部分载体启动导出后记录载体失败时Firstmate 在启动命令中unset TRACEPARENT并照常启动任务子代理绝不会收到元数据中不存在的身份。仅元数据值只存在于易失的 pane shell 与state/id.meta中teardown 照旧移除状态因此没有新的持久化表面也没有 schema 迁移。与 OpenTelemetry 及后续演进的关系Firstmate 不学习任何关于 OpenTelemetry、exporter、collector、存储或 UI 的知识。它只发出标准 W3C 载体并记录同一身份下游观测者拥有其余一切并能从 home 会话的冻结决策或traceparent字段发现活跃传播。原生生命周期事件发射、额外稳定 ID、intake 元数据与任何内嵌 OTLP 都被刻意推迟直到运行中的观测者展示出派生工件无法覆盖的具体保真度缺口。验证证据三套可重复测试bin/fm-trace-context-lib.sh 的头注释拥有精确机制的所有权而 docs/verification/trace-context.md 记录了可重复的测试证据。当前行为与原理的权威说明在 docs/trace-context.md配置 schema 在 docs/configuration.mdTrace context propagation。从仓库根目录运行三套 trace-context 套件每套每个断言打印一行ok - ...$ bash tests/fm-trace-context-lib.test.sh | tail -1 # fm-trace-context-lib.test.sh: all assertions passed $ bash tests/fm-trace-context-spawn.test.sh | tail -1 # all fm-trace-context-spawn tests passed $ bash tests/fm-remote-secondmate-trace-context.test.sh | tail -1 ALL TESTS PASSED单元套件26 个断言同目录的 tests/fm-trace-context-lib.test.sh26 断言是纯函数测试无后端、无真实 spawn覆盖校验合法值接受畸形、错误长度、大写、全零、ff版本、shell 元字符值均拒绝。测试用的合法样本是00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01tests/fm-trace-context-lib.test.sh非法样本包括命令替换形状的值$(touch ...)验证其作为惰性数据被拒绝且永不被执行铸根每次 mint 都是互不相同的 sampled 根且无父级采纳输入——flags 恒为01、trace id 非全零、长度与字符集精确恢复复用路径记录载体胜过环境载体环境永不读取默认关闭省略不注入、不写traceparent启用优先级FM_TRACE_CONTEXT覆盖config/trace-contextunset 或空回退文件归一化的 home 会话状态、只读旧记录的原子替换、发布失败后的陈旧会话拒绝、缺失或无效状态默认 offSecondmate home 会话边界后者文件状态优先与任务级 trace 边界同一持久环境TRACEPARENT根下连续两次 resolve 得到两条互异 trace且两者都不采纳环境根强制熵失败安全省略与铸根定形校验。spawn 路径集成套件12 个断言tests/fm-trace-context-spawn.test.sh12 断言对环境FM_TRACE_CONTEXT密闭hermetic用假 tmux pane 和真实隔离 git worktree 端到端驱动 bin/fm-spawn.sh覆盖启用时解析出的唯一载体以traceparent记录在 meta且仅当完全相同的TRACEPARENTexport 在启动字面量之前发送禁用时两者均不写不送GOTMPDIR照常载体投递失败时不留下traceparent声明源任务仍启动不安全的投递部分输入无法清除在追加启动命令前停止meta 追加失败时从启动任务中移除载体但不中止它重复 Secondmate 预检保持继承的 trace 配置不变relaunch 原样复用记录载体spawn 忽略之后的配置与环境编辑以冻结的 home 会话决策为准。任务级边界回归精确建模了被评审的 Secondmate 场景同一 home 顺序 spawn 两个无关任务而同一固定TRACEPARENT常驻 spawn 环境持久 Secondmate 的启动期载体两任务记录并注入的合法载体 trace id 互不相同、也与环境载体不同第一任务 relaunch 则对 meta 记录与注入 export 原样复用其原始载体。另有两条断言驱动真实的两级 primary → Secondmate → worker 链用 primary 注入 Secondmate 的精确环境连跑两次bin/fm-spawn.sh双向证明 primary 的有效覆盖治理嵌套 worker环境开且无配置文件时嵌套 worker 保持启用且铸根自己的任务级 trace与 Secondmate 的载体互异环境关且文件存在时嵌套 worker 保持禁用——即使config/trace-context已被拷贝进 Secondmate home。最后一条断言驱动文件决定路径FM_TRACE_CONTEXTunset证明 Secondmate 记录/注入的载体与其收到的FM_TRACE_CONTEXTon|off快照永远出自同一次冻结决策载体绝不会与相反的启用状态配对。该套件不触碰任何真实 harness 或 live fleet。tests/fm-session-start.test.sh 额外证明只有持锁的会话启动会写入有效状态锁被拒绝的只读启动保持其不变。远程路由套件6 个断言tests/fm-remote-secondmate-trace-context.test.sh6 断言覆盖永不抵达本地导出位点的 Secondmate 路径驱动真实链路——父进程的bin/fm-spawn.sh、bin/fm-on.sh、真实远程入口、bin/fm-remote-secondmate-control.sh与远程主机自己的bin/fm-spawn.sh——经确定性 SSH 边界、以有状态假 Herdr CLI 作为后端远程 Secondmate 始终运行的后端远程 pane 收到的载体从其 pane 自身日志读回禁用父进程不记录traceparent、远程 pane 收不到 export、远程 home 不继承启用标志、交付快照为FM_TRACE_CONTEXToff而GOTMPDIR照常送达启用父进程记录载体、远程端点自身记录、导出的 pane 值三者为同一合法载体在GOTMPDIR之后、启动命令之前发送FM_TRACE_CONTEXTon与继承标志一并交付relaunch 在父记录与 pane export 中均原样保留该载体第二条远程路由在持有固定环境TRACEPARENT的环境中解析铸根出的 trace id 与那条环境载体及第一条路由均不同远程接收方把config/trace-context当作普通声明的可继承材料接受却拒绝config/secondmate-harnessprimary 刻意不传播的文件携带父载体到远程主机的投递参数在 ship spawn、shell 元字符值、全零 trace id 与空值上均被拒绝——因此只有 Secondmate 启动时的严格 W3C 载体能到达 pane export。最后一个单一的 live 后端端到端人工检查——真实 spawn 确认 pane 在启动行之前收到TRACEPARENTexport、teardown 后无残留——是受边界约束的人工步骤此处推迟因为 live 代理 spawn 会扰动运行中的 fleet。这正是该能力源码证据完备、live 证据按需人工执行的验证哲学三套自动化套件不触碰真实 fleet却足以锁定行为契约。赞分享【免费下载链接】firstmateTalk to one agent. Ship with a crew.项目地址https://gitcode.com/gh_mirrors/fi/firstmate点击查看免费下载相关推荐OpenTelemetry Go分布式追踪原理解析Span、Context与传播机制OpenTelemetry Go分布式追踪原理解析Span、Context与传播机制 1. 分布式追踪核心痛点与解决方案 在微服务架构中一个请求往往需要经过可观测性Next.js 分布式追踪实战基于 Highlight 的 W3C Trace Context 全链路接入与源码解析Next.js 分布式追踪实战基于 Highlight 的 W3C Trace Context 全链路接入与源码解析 本篇指南围绕 Next.js 应用中分布可观测性后端ggplot2图表字体优化指南hrbrthemes字体系统全面详解ggplot2图表字体优化指南hrbrthemes字体系统全面详解 hrbrthemes是一个专注于ggplot2图表字体优化的R语言主题系统它通过精心设计UI库/组件数据分析上一篇YimMenu完整指南免费GTA5增强工具与安全防护系统下一篇Konsta UI入门指南5分钟快速搭建移动端应用界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考