【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载Shadow evaluation影子评估是 Gentle-AI 在 Receipt-Driven DevelopmentRDD收据驱动开发根简化迁移中的 Wave 1 机制它把目标七值关系模型internal/reviewtransaction下的 shadow 代数以只读观测者身份旁路接入真实的 review 生命周期决策在不干预、不阻塞任何现有行为的前提下逐调用点测量目标模型与现状是否达成一致。本文以 docs/architecture/rdd-shadow-evaluation.md 为骨架结合仓库源码与 golden 差分矩阵完整说明它的启用方式、stderr 观测行格式、内部实现、只读保证、回滚边界与分歧报告流程并给出当前仓库中该机制已推进到的实现状态。一、Shadow evaluation 是什么观测者绝不是裁判Shadow evaluation 的核心定位只有一句话它观测永不干预。文档用一张 Do / Never do 表把它与真实的 review 决策路径严格隔离职责内容它做什么解析一个真实存在的CandidateIdentity计算对应的ShadowRelation对 authority 图健康度进行分类并把结果仅记录在内存中、仅属于当次进程它绝不做什么不阻塞、不延迟、不修改真实的 consent 提示、review-context 结果、回执或 authority 变更不授权、不拒绝、不阻塞、不路由普通交付与 SDD 归档一个关键的工程承诺是shadow 内部的任何失败都会被吞掉并记录为 advisory 证据永远不可能作为 live 路径错误浮出水面。这意味着即便影子模型本身出现 bug它也不会有能力影响用户的真实 review 生命周期——这是影子机制能够安全地并行于生产路径的前提。从仓库源码看这一只读承诺不是口头约定而是由 AST 级别的守卫测试强制执行的见 shadow_readonly_guard_test.go禁止任何生产shadow_*.go文件声明或调用带*CompactState指针接收者的方法compact.go中CompleteReview/Invalidate/BeginCorrection一族方法都会变更 review 状态禁止引用Store或CompactStore类型——影子代数直接接收 candidate identity、snapshot 和 receipt从不持有可变存储句柄禁止调用任何已知文件系统写原语os.WriteFile、os.Create、os.OpenFile、os.MkdirAll、os.Remove、os.Rename、os.Symlink、os.Chmod、os.Truncate等见测试文件中的shadowWritePrimitives清单允许Git 只读命令rev-parse、diff、cat-file乃至merge-tree --write-tree——按设计的威胁矩阵这些命令对 authority 而言是只读的后者只写 content object、不写 ref而 PR 关系代数恰恰需要它们。该守卫既对合成样例做单元测试TestShadowReadOnlyGuardCatchesMutationShapes覆盖干净只读源码声明*CompactState指针接收者引用Store类型调用文件系统写原语等正反用例也对真实生产 shadow 文件做 AST 扫描。二、快速路径怎么开、在哪看、出问题怎么办文档给出的操作路径非常简短适合本地调查时快速上手保持GENTLE_AI_RDD_SHADOW不设置。这是默认值也是日常使用的唯一受支持设置——shadow evaluation 关闭零 shadow 代码运行。本地调查时显式开启在运行 review-context hookpost-apply、pre-commit、pre-push、pre-pr、release或gentle-ai review start/status之前设置GENTLE_AI_RDD_SHADOW1。盯 stderr绝不是 stdout每次被观测调用stderr 上恰好出现一行gentle-ai.rdd-shadow/v1。发现意外分歧就上报详见下文报告分歧一节。一个值得强调的细节行只输出到stderr绝不写入 stdout。这是刻意设计——stdout 属于正常的命令输出面观测性证据不能污染任何可能被脚本或下游工具解析的标准输出通道。回滚边界开关本身就是 Wave 1 的撤销按钮把未设置即关闭做成默认值等于给 Wave 1 装了一个物理回滚开关。文档明确声明取消设置GENTLE_AI_RDD_SHADOW后每一个 live review 生命周期结果都与完全不包含 shadow 代码的构建字节级一致。这一性质由三组测试背书TestShadowObservationSwitchIsRollbackBoundaryGateByteIdentical——覆盖post-apply、pre-commit、release三个调用点TestNativePrePRGateShadowOnOffByteIdenticalForCompatibleBaseAdvance——覆盖pre-prhook唯一一个 shadow 评估会做额外 Git 工作的调用点TestNativePrePRGateWithShadowDisabledDerivesBaseAdvanceZeroTimes——单独证明默认关闭时pre-pr的 base advance 推导零次运行即 shadow 关闭状态下没有额外 Git 成本。这三条测试共同构成了迁移的安全网任何时刻发现影子模型与现状分歧不可解释回退到默认关闭状态即可完整回到旧行为不需要回滚代码。三、stderr 观测行逐字段解读开启后每个被观测调用点恰好写一行到 stderr格式如下原样取自文档gentle-ai.rdd-shadow/v1 gateGateKind live_resultGateResult has_relationbool shadow_relationShadowRelation no_live_counterpartbool authority_healthhealthy|repairable|blocked errquoted string, empty when none逐字段含义与取值范围字段取值/语义gateGateKind只命名触发观测的 review-context hookpost-apply/pre-commit/pre-push/pre-pr/release。源码中定义于 receipt.goGatePostApply…GateRelease。文档特别强调它是 hook 名绝不是交付门。live_resultGateResultlive 端该调用点的真实结果如allow/scope-changed/invalidated/escalated同一定义于 receipt.go。has_relation该调用点是否拿到了可比较的冻结回执。false意味着该调用点没有可供对照的历史回执典型如start——它没有更早的收据可比此时 authority 健康度仍然记录但绝不从缺失的证据中编造关系。shadow_relation影子模型计算出的七值关系见下一节。no_live_counterpart当shadow_relation为ambiguous或unknown时为true——这类关系在结构上就没有与之对应的 live 决策可比。authority_healthhealthy/repairable/blockedauthority 图健康度分类。它复用设计文档 rdd-root-simplification-design.md 中 Derived categories 表的 Authority health 封闭词汇把已知可处置与未知损坏区分开。err引号包裹的字符串无错误时为空。shadow 内部失败在此被吞掉并呈现为 advisory 证据。该行只包含关系/健康度枚举值绝不包含候选内容——因此可以放心复制到 issue 中而不会泄露仓库内容。四、七值 ShadowRelation 词汇表与 live 分类器的对照影子模型使用一套七值封闭关系词汇。源码定义在 candidate_relation.goShadowRelation即CandidateRelation的类型别名关系值含义exact候选与策略身份完全匹配compatible_base_advance按deriveBaseAdvanceCompatibilityprepr.go 第 73 行的七项条件证明的兼容 base 前进provable_contractionlive 候选是被审内容的确定性子集且所有 admitted finding 都不引用被排除路径changed任一候选组件不同需要新的候选 authorityunrelated没有任何候选谱系管辖该内容ambiguous多个 authority 同等适用需显式选择unknown证据无法证明任何既有关系fail closed文档特别解释了这七值与 live 端五值分类器之间的词汇缺口影子模型独有的unrelated值在 live 端没有对应桶这正是差分矩阵中已解释分歧的一大来源——详见下一节。影子模型计算关系的输入是规范化后的CandidateIdentity其五个字段repository_id、base_tree、candidate_tree、changed_paths_modes_digest、policy_hash定义于 candidate_identity.go与设计文档中CandidateIdentity的规范完全一致。changed_paths_modes_digest同时覆盖变更路径与 Git 文件模式新旧因此仅模式变更也能被度量为一个独立的发散类别policy_hash在调用方没有 live policy hash 时保持unknown——绝不编造。五、差分矩阵40 行覆盖全部预期分歧影子评估自己的退出证据是一张 golden 差分矩阵位于 testdata/shadow-differential-matrix.golden由TestShadowMatrixCoveringArrayGolden生成并冻结。这张 40 行覆盖数组4 个 selector 变体 × 10 行的统计口径见设计文档 rdd-root-simplification-design.md 的 Migration waves 表Wave 1 行判定类别行数说明agreement一致16changed、compatible-base-advance、exact、provable-contraction四个关系的对照一致explained divergence已解释分歧12两类Amendment B 无输入降级、影子独有unrelated值的词汇缺口no-live-decision无 live 决策8shadow 为ambiguous/unknown结构上无 live 决策可比no-shadow-decision无影子决策4影子身份解析在计算关系之前就失败如 Git revision 无法解析、selector 歧义unexplained divergence未解释分歧0在exact/compatible_base_advance/provable_contraction上为零——干净的退出标准矩阵中每行都给出selector、shadow_relation、live_relation、verdict已解释分歧行还带explained: true和具体reason。以两个最典型的已解释分歧为例Amendment B 无输入降级changed-amendment-b-degradation行影子模型在该模式下没有 admitted-finding 证据因此把provable_contractionfail-closed 为changed而 live 端没有这种降级概念对完全相同的路径子集仍报provable-contraction。这是文档化的词汇差design.md Decision 5不是伪造的一致。unrelated词汇缺口unrelated-vs-live-changed-scope/unrelated-vs-live-unsafe行shadow 的unrelated在 live 五值分类器中没有对应桶不存在管辖该内容的冻结 authority 可比该行记录为已解释分歧绝不吸收进 no-live-decisionlive 端对同一候选独立报changed-scope或unsafe。矩阵还覆盖了no-shadow-decision的成因细节例如stagedselector 同时提供了base_ref与ledger_ids——这种歧义由shadowSelectorAmbiguityReason在 selector 层检出shadowRelate甚至不会运行。六、报告一个观测到的分歧如果一条 stderr 行显示出矩阵之外的分歧即不属于上面两类已解释分歧按文档流程处理原样复制那条gentle-ai.rdd-shadow/v1行它不含候选内容只有关系/健康度枚举值。在该仓库的 issue 跟踪系统中提交附上行内容、产生它的 gate 或命令、以及它是否可复现。理解它的规划含义exact、compatible_base_advance或provable_contraction上出现未解释分歧按设计会阻止 Wave 2 入场见设计文档 Migration waves 的依赖边界——上报正是让这个规划边界得以执行的方式同时它不会阻塞普通交付或 SDD 归档。换句话说分歧报告不是报障而是迁移节奏的一部分Wave 1 的目标就是在任何目标模型内容成为规范之前把分歧表测量到零未解释项。七、与 Wave 1 迁移门的关系及演进现状Shadow evaluation 是 rdd-root-simplification-design.md 中迁移波次的第 1 波Wave 1 Shadow algebra。设计文档的 Migration waves 表明确Wave 1 范围只读 candidate resolver、关系代数、图分类器回滚边界禁用 shadow evaluation即不设置GENTLE_AI_RDD_SHADOW退出证据差分矩阵覆盖所有 selector、base、contraction、ambiguity、unknown 情形且在exact/compatible_base_advance/provable_contraction上零未解释分歧——达到干净的退出标准后才允许进入 Wave 2leaf disposition。各波次是依赖边界而非大 PR每一波必须先证明退出证据下一波才能启动历史 authority 绝不原地翻译。当前仓库中的演进状态从源码结构可以确认shadow 相关的生产代码并非一直停留在 Wave 1 的观测形态。candidate_identity.go的包注释表明原shadow_identity.go影子候选身份解析在Wave 3 Slice 1被提升出影子门直接服务于 live 的ReviewCore而shadow_observer.go与shadow_authority_health.go两个生产 shadow 文件在Wave 7 S2a退役。伴随它们的 glob-扫描测试一并退役否则会因找不到生产 shadow 文件而失败但 AST 扫描器本身被保留并复用candidate_readonly_guard_test.go针对 live 保留文件和derived_observation_write_guard_test.go的shadowCallExprName辅助函数都在继续使用同一套只读检查逻辑。也就是说影子必须只读的机制保障延续到了被提升为 live 的代码上而不是随 Wave 1 一起消亡——这正是 Wave 1 观测价值的兑现方式。八、下一步与阅读指引影子评估本身不承诺交付任何东西它只负责回答目标模型与现状是否一致。下一站是设计文档docs/architecture/rdd-root-simplification-design.md——目标架构全貌包括迁移波次表、七值关系代数、compatible_base_advance的七项证明条件Amendment A、provable_contraction的降级规则Amendment B以及新谱系共存时的证据隔离Amendment C。仓库内可供继续深挖的关键证据文件差分矩阵internal/reviewtransaction/testdata/shadow-differential-matrix.golden关系词汇表internal/reviewtransaction/candidate_relation.go规范候选身份internal/reviewtransaction/candidate_identity.go只读 AST 守卫internal/reviewtransaction/shadow_readonly_guard_test.gogate 词汇与回执模型internal/reviewtransaction/receipt.gocompatible_base_advance规范语义来源internal/reviewtransaction/prepr.go一句话收束全文在让目标模型成为规范之前先用一个可随时关闭、永不写盘、只输出到 stderr 的影子来测量它——这就是 Gentle-AI 为高风险架构迁移准备的第一道、也是最重要的一道保险。赞分享【免费下载链接】gentle-aiGentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.项目地址https://gitcode.com/gh_mirrors/ge/gentle-ai点击查看免费下载相关推荐gentle-ai-bench以“摩擦”为单位度量 gentle-ai 评审生命周期回归的基准测试工具gentle ai bench以“摩擦”为单位度量 gentle ai 评审生命周期回归的基准测试工具 本文介绍 gentle ai 仓库中自带的独立基准测试SkyWalking AI Evaluation 模块实战基于 OpenAI 兼容评测模型自动评估 GenAI Span 质量SkyWalking AI Evaluation 模块实战基于 OpenAI 兼容评测模型自动评估 GenAI Span 质量 本文介绍 SkyWalking可观测性APM链路追踪指标监控日志分析微服务5分钟掌握OpenKore仙境传说RO免费自动化工具的终极指南5分钟掌握OpenKore仙境传说RO免费自动化工具的终极指南 OpenKore是一款功能强大的免费开源自动化工具专为《仙境传说》Ragnarok Onl游戏开发上一篇开源项目 copy-text-to-clipboard 常见问题解决方案下一篇从硬件到虚拟LDD-LinuxDeviceDrivers网络设备驱动实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
