即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载云端仿真Cloud Simulation是 WuKongIM 项目用于在临时云环境中对多节点集群进行真实负载验证与性能诊断的自动化体系。本文将围绕 ADR-0023 中确立的核心契约展开一个分析工作流Analysis Workflow只有在诊断结果为healthy时才成功其余所有结构化解毒结论product_defect、infrastructure_interrupted、scenario_invalid、insufficient_evidence以及云厂商确认的released都判定工作流失败——即使 Codex 正常退出、甚至 Draft PR 已经创建也不例外。读完本文你将掌握这套裁决驱动状态的设计动机、五类裁决与严重度/根因范围的合法组合矩阵、诊断结果 JSON Schema 的完整字段语义以及它在analyze.sh、wkclouddiagnosis与 GitHub Actions 中的落地实现。为什么让诊断裁决而不是命令退出码决定工作流状态在常见的自动化流水线里一个任务的成败通常由进程退出码决定Codex 正常返回 0工作流就绿了。ADR-0023 明确推翻了这种直觉其核心论断是An Analysis Workflow succeeds only for ahealthyDiagnosis Result.也就是说命令的成功completed与诊断的健康healthy是两回事。Codex 完成分析、把结果写成 JSON这只是诊断命令完成而这份结果是否意味着产品健康取决于结构化的裁决字段verdict。这正是后续 ADR-0037 所继承的原则A valid identity-matched Diagnosis Result is a completed command regardless of verdict; only the structured verdict establishes health——有效的诊断结果是命令完成的标志但只有结构化裁决才能确立健康状态。这一设计解决了一个真实的工程问题失败的类型决定了后续动作的合法性。如果负载结果异常是因为产品代码缺陷那么可以进入仓库修复流程如果是因为云基础设施被抢占或负载生成器饱和那么把锅甩给产品代码并提交修复 PR 就是错误的。诊断裁决必须先分类、再决策把这次跑得对不对和该不该修代码彻底解耦。从源码看这一原则在 internal/usecase/cloudsim/types.go 的 Run 生命周期状态机中也有对应运行结束之后并不直接进入成功态而是进入analysis_grace负载停止但仍允许实时诊断或infrastructure_interrupted基础设施意外终止最终由released提供商库存证明资源已不存在收尾。诊断裁决正是在analysis_grace阶段产生并决定工作流去向。五类诊断裁决唯一成功路径与四类失败路径ADR-0023 定义了完整的裁决词汇表随后在 internal/usecase/cloudanalysis/diagnosis.go 中以DiagnosisVerdict常量实现裁决值含义工作流结果是否可触发代码修复healthy负载完成且无缺陷信号成功否product_defect证据表明失败归因于仓库代码失败是需高置信度 回归测试路径infrastructure_interrupted云基础设施使运行失效失败否scenario_invalid声明的负载未被按预期施加失败否insufficient_evidence实时证据不足以支撑归因失败否released提供商确认云厂商库存证明资源已销毁失败分析在 Codex 运行前终止否关键点在于released不是 Codex 分析出来的裁决而是提供商预检preflight阶段的终态证据。当 Run Locator 仍存在、但云厂商库存已确认为空时分析工作流直接终止根本不会启动 Codex——ADR-0037 对此的描述是 Provider-confirmed release prints a terminal notice and exits successfully before Codex runs提供商确认已释放时在 Codex 运行前打印终态通知并成功退出。这种失败但命令成功退出的组合是刻意的released场景下本地进程无需再发起任何清理请求资源已被确认销毁它以 0 退出码正常结束但工作流状态由released裁决决定为失败因为此时根本没有可分析的实时数据任何诊断都无从谈起。裁决与分类字段的合法组合源码级校验矩阵单看 verdict 还不够ADR-0023 要求工作流 Job Summary 呈现唯一一个裁决 置信度 支撑观测 受影响时间范围 修复链接。为了保证诊断结果自洽、可被程序化判定internal/usecase/cloudanalysis/diagnosis.go 的Validate()方法把裁决与其他分类字段绑成了严格矩阵裁决severityroot_cause_scoperemediation_eligibility.eligible其他硬约束healthy必须是none必须是none必须为 false必须存在workload_inspect且completetrue、statecompleted、statuspassedproduct_defect非nonelow/medium/high/critical必须是product可为 true唯一可修复的裁决eligibletrue 时必须同时满足 repository_attributable、testable、proposed_regression_coverage 非空且 cloud_revalidation_requiredtrueinfrastructure_interrupted非none必须是infrastructure必须为 false—scenario_invalid非none必须是scenario必须为 false—insufficient_evidence必须是none必须是unknown必须为 false允许无完整观测、无支撑信号这套矩阵在 diagnosis_test.go 中被大量单测覆盖例如TestDecodeDiagnosisResultRejectsContradictoryClassificationAndIncompleteEvidence验证了verdictproduct_defect 但 root_cause_scopeinfrastructure会被拒绝TestDecodeDiagnosisResultRequiresCompleteWorkloadForHealthy验证了 healthy 裁决必须附带有 passed 状态的完整 workload 观测。值得注意的还有可修复性的收紧规则diagnosis.go 中Validate()的对应分支if d.RemediationEligibility.Eligible (d.Verdict ! VerdictProductDefect || d.RootCauseScope ! RootCauseProduct || !d.RemediationEligibility.RepositoryAttributable || !d.RemediationEligibility.Testable || len(d.ProposedRegressionCoverage) 0) { return invalid(remediation eligibility) } if d.RemediationEligibility.Eligible !d.CloudRevalidationRequired { return invalid(eligible remediation requires cloud revalidation) }即只有product_defect且根因归属product、仓库可归因、可测试、附带了回归覆盖提案、并要求云上复验才允许进入修复流程。基础设施中断与场景无效的裁决即使很严重也永远不可修复——ADR-0011 明确指出Analysis Skill 不得把 spot 抢占本身当作 WuKongIM 缺陷或提议代码修复的理由。诊断结果 JSON Schema完整字段与取值边界诊断结果以 JSON 形式在工作流之间交接。仓库在 .github/cloud-sim/diagnosis.schema.json 维护了一份严格的 JSON Schemadraft 2020-12additionalProperties: false全部 15 个顶层字段必填。核心字段的约束如下schema固定为wukongim/cloud-simulation-diagnosis/v1run_identityrun_id1~128 字符、source_sha严格 40 位十六进制、scenario_digestsha256: 64 位十六进制三者把结果绑定到一次不可变部署analyzed_windowstart/end均为 RFC3339 UTC 时间戳end不得早于startverdict五选一枚举见上文矩阵severitynone/low/medium/high/critical健康与证据不足必须为none因果类裁决必须非noneconfidence0~1 之间的浮点数且不允许 NaN 或无穷大root_cause_scopenone/product/infrastructure/scenario/unknown必须与裁决匹配summary1~2000 字符的紧凑非敏感摘要observation_references最多 32 条每条含tool/node/observed_at/window/complete以及可空枚举statein_progress/completed/null和statuspassed/failed/null。workload_inspect工具有特殊生命周期约束completetrue时必须是statecompleted且statuspassed|failedcompletefalse时只能是in_progress或 null其他工具一律 nullsupporting_signals / contradictory_signals / unresolved_signals各最多 24 条、每条 1~500 字符的紧凑事实remediation_eligibilityeligible/reason/repository_attributable/testable四字段proposed_regression_coverage最多 12 条建议回归测试cloud_revalidation_required布尔值eligibletrue 时必须为 true。诊断结果的 Go 侧解析入口是DecodeDiagnosisResultinternal/usecase/cloudanalysis/diagnosis.go它在 JSON 解码之外还叠加了多项防御结果体上限 256 KiB、DisallowUnknownFields、拒绝尾部多余数据、所有枚举与文本长度校验以及上述分类矩阵校验。命令行封装wkclouddiagnosis validate FILE位于 cmd/wkclouddiagnosis/main.goanalyze.sh在把结果交给下游前会调用它做最终把关。实战analyze.sh 如何把裁决落到工作流状态运行前的 released 预检Codex 尚未启动即已终局analyze.shscripts/cloud-sim/analyze.sh是整个本地分析编排的入口。它通过 GitHub Actions 工作流 .github/workflows/cloud-sim-analyze.yml 执行inspect、prepare、close三种会话操作。其中inspect阶段的核心是preflight用wkcloudsim preflight --locator把 Run Locator 与当前云厂商库存比对结果只有两种——live精确匹配的资源仍存在或released定位器有效但库存为空对应 internal/usecase/cloudsim/types.go 的PreflightState常量。在 cloud-sim-analyze.yml 的 Materialize 阶段如果预检状态是released会话会被写成statereleased消息为已由云厂商确认自动销毁当前没有可分析的实时数据分析已终止同时把provider.resources置为[]。脚本侧analyze.sh随后以 jq 校验.state released and .provider.state released and .provider.resources []确认后直接publish_result released不再解析 Go 工具链、不再启动 Codex——这就是 ADR-0023 所述released run terminates before Codex的落地形态。诊断提示词把裁决矩阵写进 Codex 的硬约束只有预检为live才会继续准备加密会话、下载精确源码 SHA、检出分离工作树并最终以受控的 Codex 权限画像启动诊断。在 analyze.sh 的 prompt 中裁决矩阵被直接写进提示词作为不可违背的语义约束healthy uses severitynone and root_cause_scopenone; insufficient_evidence uses severitynone and root_cause_scopeunknown; product_defect, infrastructure_interrupted, and scenario_invalid use a non-none severity and the matching product, infrastructure, or scenario root_cause_scope. Only product_defect may be remediation-eligible.同时analyze.sh给 Codex 只开放了白名单内的只读 MCP 工具集run_inspect、workload_inspect、cluster_snapshot、metrics_query_range、logs_search、logs_context、diagnostics_query、task_audits_query、trace_start、trace_query、profile_capture、profile_top、profile_list、config_read_redacted这些工具的输入校验与响应上限由 internal/usecase/cloudanalysis/service.go 的Service层把关——例如ensureLive()会在任何实时观测前再次校验 Run Identity 与库存已释放则返回ErrRunReleased直接失败关闭。诊断后的双重验证身份绑定 语义校验Codex 退出后脚本并不直接信任输出。它先做一次 jq 规范化补齐可空字段、把非 workload 观测的 state/status 置 null随后关闭分析访问窗口无条件清理在检出工作树内运行go run ./cmd/wkclouddiagnosis validateanalyze.sh 第 934-942 行复用DecodeDiagnosisResult的全部语义校验用 jq 校验run_identity.run_id、source_sha、scenario_digest与加密会话中保留的身份完全一致任何不一致都fail。通过验证后才publish_result diagnosed输出最终裁决。整个流程对裁决决定状态的落地是Codex 的 0 退出码只代表诊断完成工作流的成败由验证后的 verdict 字段决定。相邻设计饱和、抢占与容量告警如何归属裁决ADR-0023 的裁决体系并不是孤立的它与多个相邻 ADR 构成一致的分层归因规则ADR-0011停止于计划外 spot 抢占任何非计划的抢占把运行归类为infrastructure_interrupted不同物理节点集的结果绝不混合Analysis Skill 不得把抢占当作产品缺陷。对应 docs/adr/0011-stop-on-unplanned-spot-interruption.md。ADR-0024保护结果免受负载发生器饱和影响simulator 持续 CPU 70%、内存 80%、或源端口/队列/发送器饱和时归因为insufficient_evidence无法把责任归于产品而 WuKongIM 节点的高利用率仍是合法诊断对象。对应 docs/adr/0024-protect-results-from-load-generator-saturation.md。ADR-0046把资源饱和报告为容量警告自动化 chat-lifecycle 流程把持续声明的 CPU/内存/队列/负载饱和当作infrastructure_capacity证据功能正确的运行可以passed_with_capacity_warning结束延迟在有充足硬件余量时仍是产品失败模糊归因仍是insufficient_evidence。这一词汇表在 internal/bench/chatlifecycle/verdict.go 中体现为VerdictPassedWithCapacityWarning、VerdictCauseInfrastructureCapacity等常量。对应 docs/adr/0046-report-resource-saturation-as-a-capacity-warning.md。ADR-0029交接 schema 校验后的诊断结果诊断 Job 输出的正是本文所述的 Schema 校验结果只保留紧凑观测引用而非原始日志/指标序列结果仅保留一天作为工作流内交接无效结果统一降级为insufficient_evidence。对应 docs/adr/0029-handoff-a-schema-validated-diagnosis-result.md。ADR-0030约束每次分析访问窗口每次诊断有 45 分钟硬超时网络访问窗口最多开 50 分钟非续期 Analysis Token 在签发后 45 分钟或租约到期前 5 分钟取早者失效正常完成、失败、取消、超时都执行无条件清理调度清扫器作为第二层。对应 docs/adr/0030-bound-each-analysis-access-window.md。从这些 ADR 可以清晰看到一条主线裁决的目的不是评分而是建立可审计的归因边界——基础设施问题、负载问题、证据不足与产品缺陷必须严格分家避免把云环境的偶发因素变成对 WuKongIM 产品代码的误判。演进与现状ADR-0023 的后续继承需要注意ADR-0023 的状态标记为superseded已被替代其后续版本是 ADR-0037Run Codex locally with an encrypted Analysis Session。替代的核心是执行形态的升级云上不再存储或执行 OpenAI API Key / Codexauth.json改为本地 Codex CLI 通过 ChatGPT 订阅认证GitHub 侧的 Analysis Session Workflow 只充当云身份代理交换短期 run-scoped 令牌、RSA-OAEP SHA-256 加密、仅放行请求方 /32。但裁决驱动状态的语义被完整继承——ADR-0037 明确写道A valid identity-matched Diagnosis Result is a completed command regardless of verdict; only the structured verdict establishes health. Session preflight, timeout, invalid schema, and identity mismatch failures remain nonzero exits.也就是说有效的身份匹配诊断结果无论裁决如何都算命令完成只有结构化裁决确立健康而会话预检失败、超时、schema 无效、身份不匹配仍然是非零退出。ADR-0023 的裁决矩阵healthy 成功、其余失败、仅 product_defect 可修复、released 在 Codex 前终止在本地执行模型中依旧生效且失败不抑制清理——诊断或可选修复失败不会阻止资源清理而提供商确认已释放的运行则不再重复发起清理请求。结语把健康写成可校验的结构化契约ADR-0023 留给 WuKongIM 云仿真体系最重要的遗产是把运行健康从一个模糊的主观判断转变成完全由结构化字段决定、可被 Schema 与 Go 代码双重校验、可被工作流自动判定的契约。这套设计让自动化诊断具备了三个关键性质可判定性工作流状态不再依赖 Codex 的退出码或人眼阅读而是由verdictseverityroot_cause_scoperemediation_eligibility的组合矩阵唯一决定可审计性每个裁决都必须携带置信度、受影响时间窗口、支撑/矛盾/未决信号与观测引用杜绝裸结论可归因性基础设施、场景、证据不足与产品缺陷严格分离只有高置信度、仓库可归因、有回归测试路径的产品缺陷才允许进入修复流程且修复仍需云上复验。对于任何希望让 AI 诊断结果真正驱动 CI/CD 状态、又不想被误判拖入错误修复的工程团队这套裁决驱动工作流状态的契约都是一个值得直接借鉴的范本先分类再决策命令完成不等于健康健康必须能写成一份可校验的结构化 JSON。赞分享即时通讯后端【免费下载链接】WuKongIMMore than just IM 不只是即时通讯(IM)项目地址https://gitcode.com/gh_mirrors/wu/WuKongIM点击查看免费下载相关推荐WuKongIM 云仿真诊断架构解析Analysis MCP 与 Analysis Skill 的职责分离设计WuKongIM 云仿真诊断架构解析Analysis MCP 与 Analysis Skill 的职责分离设计 云仿真压测Cloud Simulation即时通讯后端vscode-clangd完全指南提升C/C开发效率的终极VSCode扩展vscode clangd完全指南提升C/C开发效率的终极VSCode扩展 vscode clangd是一款专为Visual Studio Code打造的开发工具代码编辑器WuKongIM 云仿真信任边界仅从可信 main 修订发起有成本的工作流WuKongIM 云仿真信任边界仅从可信 main 修订发起有成本的工作流 本文以 WuKongIM 仓库中的架构决策记录 ADR 0020Simulate即时通讯后端上一篇TypeSpec typespec/openapi3 Emitter 完整使用指南配置选项详解与源码级原理剖析下一篇深入解析 YouTube.js 的 GuideDownloadsEntry内测版下载导航项解析器实现与实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考