【免费下载链接】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 中 RDDReceipt-Driven Development凭单驱动开发审查机制从失控到收敛的全过程为什么一个人做决策、Agent 执行的流程仍然会被 Agent 带偏社区测试如何逼出比内部审计更有效的缺陷以及作者如何用一套可复现的摩擦基准friction benchmark取代了我说它更好的争论。读完本文你将掌握 RDD 的设计模型与命令行开关、bench/基准工具的核心指标与运行方式以及贯穿整个项目的工程纪律——如果你告诉别人怎么做就要确保它真的有效。一、RDD 是什么一句话版本与它的工作方式RDD 的核心思想用一句话概括就是当你改动重要内容时在它发布之前有人审查它。仅此而已。难点从来不在于这个想法本身而在于它绝不能碍事。一个强迫你为了改一个逗号走完整套仪式流程的系统三天之内就会被卸载而一个在你触碰认证逻辑时一言不发的系统则一文不值。Gentle-AI 的设计目标是让审查干预力度与风险匹配而不是与改动规模匹配。从 技术架构文档 docs/architecture/organic-rdd.md 可以确认当前的实际行为审查机制看的是你改了什么而不是改了多少编辑 README→ 什么都不问。零仪式。写了一千行文档→ 仍然什么都不问。规模不影响风险判定。改了两行登录代码→ 四名审查者。这是因为 RDD 的模型建立在三条边界之上organic-rdd.mdReview follows work审查跟随工作候选变更先于审查存在父进程只通过原生 STATUS 对当前工作树做 preflight。Native owns review mechanics原生代码拥有审查机制Go 端负责风险判定、冻结工作树、lens审查透镜、provider 绑定、准入、反驳、一次有界修正、仓库证据与定向验证。Humans own delivery人类拥有交付审查批准永不提交、永不推送、永不开 PR、永不复写仓库策略。一点仪式感都不想要关掉它gentle-ai review mode disable执行完就真的关了。不是关了但仍然挡在你路上——是真的关了。想做什么就做什么重新开启时工具会告诉你它将重新验证那些从未被审查过的内容。这个kill switch的实现位于 internal/cli/review_mode.go 与 internal/reviewtransaction/rdd_mode.go从源码可以看到它的完整语义开关属于用户默认开启opt-out未设置任何来源时status报告effective: on, source: default且不会持久化任何用户偏好。显式的全局global或克隆级clone关闭总是生效。任何 off 都赢克隆级覆盖只能关闭仓库永远不能强制开启审查ErrRDDModeRepositoryForcedOn明确拒绝仓库强制开启。克隆级关闭不会被其他克隆继承。只读状态永不写状态status是严格只读的从不创建用户状态或仓库状态。自动化永远不会自动切换模式RunReviewMode只接受enable | disable | status三个操作模式切换永远是用户动作。重新开启 RDD 会重新验证当前候选而不是恢复陈旧的义务——这一点在后面的kill switch 漏洞章节还会再次出现。完整的生命周期状态机在 organic-rdd.md 中以 mermaid 图呈现这套架构的核心交付原则是审查完成是对已完成交易的证据而不是交付授权。提交、推送、PR、发布和归档始终由普通仓库策略与其自身显式授权管辖。二、没人讲的那部分第一版为什么失败2.1 失败的原因不是你想的那个RDD 的第一个版本是用 Codex GPT 5.6 ultra 模式构建的产出的东西极其庞大——而且不是需要做的东西。某个模型失控了是这件事的简单版本但不是真实版本。真相是审计文档是作者自己写的。Agent 写它但背后每一行都是人事实、推理、架构。每个关键决策都是坐下来思考过的人做的。这正是作者教所有人工作的方式——你指挥Agent 执行人领导。作者没有跳过这一步他做了。但 Agent 还是构建了别的东西。它读了那份审计文档看到其中提到企业级需求就推断出需要 HTTP 支持、远程执行和一套面向大型团队的基础设施。没人要求过这些。它从一个讲其他事情的文档里推导出了需求然后把一切都构建了出来——完整、自洽、做工精良。然后这一切都得被拆除。移除一个庞大而精良的东西比移除一个坏掉的东西更难因为它看起来是能用的。这一个错误消耗了三个月的 Codex 重置额度。2.2 为什么会发生没有任何东西把 Agent 约束在决策上不是因为思考被跳过了而是没有东西约束 Agent 遵守思考。作者当时用的是大公司的方式收集上下文交给模型信任返回的结果。他没有用自己的工具。这就是这个项目存在的全部论证而作者花了三次重置才具体学到好的决策不会在与 Agent 接触后幸存除非有东西强制执行它们。陈述架构的文档是一份建议而一个急于帮忙的 Agent 会把建议读作出发点。带有明确契约的阶段phases with explicit contracts、每条通道只有一个写入者one writer per lane、先验证再断言verify before asserting、以及一条现有测试变红就停下并上报的规则——这些不是建议。架构从来不是问题。缺少让架构具有约束力的东西才是问题。从源码与测试看这一纪律已经沉淀为可执行机制bench/的每个 journey 都会先声明自己的审查前置条件reviewOptedIn或reviewUntouched并在运行前整体校验语料validateCorpus仓库还保留了go vet、go test等强制通道。而在开发纪律层面先验证再断言最典型地体现在 journeys_edge.go 所描述的**自证夹具self-proving fixtures**上——每个夹具都必须先从 git 里把边界条件读回来自证成立否则整个 journey 失败杜绝夹具设错了却通过了的虚假绿灯。2.3 第二次运行同一模型同一决策不同的结果第二次运行使用的是同一类模型、同一个人、同样的决策。唯一改变的是决策现在由带明确契约的阶段、单写入者通道、先验证再断言以及**现有失败测试绝不能被编辑——停下并上报**这条规则来强制执行。仅仅最后一条规则就抓住了九个错误前提。九次Agent 正准备修复某个东西一个旧测试变红了而事实证明测试是对的诊断是错的。两天全力工作之后作者还在周限额的 66%。差别不在于模型在于方法。三、社区发现了什么内部审计找不到的缺陷这部分是作者最看重的部分。他发布了一个预发布版本然后人们用很好的方式把它弄坏了。以下是原文档中逐条记录的社区报告每条都可以在今天的仓库中找到对应修复或固化部分已固化为bench/中的 journey报告者发现后续固化Wladimirfn、Denver2828、MarsSall、Freedom2828四个角度报告同一个失败看似 Windows 缺陷实则是被审查的提交已经被发布后的路径Denver2828 独立诊断补丁与作者逐行一致测试指南 Flow 9已发布提交保持普通交付bench journeyj06-pre-push-after-publicationElCaaarnal手敲一个 flag 命中已宣布修复的问题——作者修的是工具不再打印错误形式而不是解析器接受它changelog 过度宣称测试指南 Flow 13不支持的 flag 组合给出类型化拒绝ardelperal一个命令成功退出但本应失败——bash 管道中$?返回管道中最后一条命令的状态而不是二进制的测试指南How to measure properly章节固化用重定向而非管道取退出码Blue-XL故意伪造的授权被接受并存入审计记录像真的一样。比没有字段更糟缺失的授权是诚实的缺失错误的授权是谎言审查准入路径的 fail-closed 原则AlbertGC13Windows 上区分了实测过的与只在代码里读过的并明确声明自己不声称什么发现 Git 权限拒绝被转化成一条不可能被遵循的建议Windows 克隆级路径安全修复reviewModeUnsafePathError给出可执行修复命令而非泛泛建议edwinsaavedran四个 macOS 缺陷因 CI 从不在 Darwin 上运行而逃逸每个都附链接测试指南 Flow 20–23macOS 专属流程macOS 缺陷已修复并在真机上验证Matere413自家 Agent 产出的审查结果被自家准入拒绝因为两份文档对所需形状说法不一测试指南 Flow 11STATUS 转换严格按返回执行Andivelikill switch 最难用例审查关闭但旧批准回执还在 store 里。曾以authority_corrupted失败作者修复后报告状态但不伪造批准测试指南 Flow 2 benchj07-disabled-with-stale-receiptsdecode2不是 bug是死锁已通过验证并持有已批准审查的更正候选仍无法完成补救——因为完成需要一个不同后继创建后继需要失效前驱健康已批准项拒绝失效三条规则各自成立却闭合成环他对着当前 head 而非旧 tag 复现并逐边写出环测试指南 Flow 14已关闭审查不阻塞新工作danielxxomg用kill -9杀死review start后检查 store 是否干净、锁是否泄漏、是否损坏——恢复了。这个用例不在作者自己的语料里损坏 store 修复路径AndySabina在 WSL2 上跨刷新跑了两次指南两次都发布被测二进制的 SHA-256第二轮没发现时说出来并什么都没开。干净的静默报告与缺陷等值且稀有得多测试纪律文化frankirova全部八个流程通过后声明了没有覆盖的东西注意到下载的资产比分支落后两个 commit 并推理其影响报告必须声明范围ftorga对 tag 与 live head 重新做行为优先验证发现两个仍可复现的缺口每个都链接到之前验证过的具体注释预发布验证流程MarcosArispe、dnlrsls、GinoL221 等一个刷新接一个刷新持续测试持续社区回归网原文档给出的总结值得原样引用这些发现没有一个来自内部审计。它们来自正在使用工具的人。四、审计哪些有效哪些无效4.1 有效的审计机械审计有效的审计是从代码推导出来的而不是来自一份需要有人记得更新的清单。第一个遍历语法树寻找那些命名了命令的错误消息然后检查该命令及其 flag 真的存在。它发现了指向不存在之物的消息。第二个拒绝没人调用的新函数。当作者移除 Codex 清理逻辑时它告诉作者十五个函数已经死了——一整个只为那个功能存在的解析器。作者按这份证据删掉了它们。这个守卫才八小时大就找到了它的第一个真实缺陷。4.2 无效的审计验证被发射而非可用无效的审计验证了某物被发射但从不验证它可用。最完美的案例有一条消息告诉你要离开这个状态运行这个命令。有测试。测试验证消息被发射、逐字精确。全绿。从来没有人运行过消息里提到的那个命令。作者运行时它不工作。他带着绿色测试覆盖率把人们送进死胡同长达数月。这就是统治其他一切的那条规则的来源一条消息只有在运行它所命名的命令确实能解除阻塞时才可以命名该命令。命名一条死路比什么都不命名更糟。这条规则如今已完全机制化bench/classify.go中的HasRunnableCommand会逐行扫描产品输出的字节检查其中是否包含字面可运行的gentle-ai verb …命令——且gentle-ai review validate --gate gate这类带占位符的模板不算可运行因为它还需要用户填值。而DeadExecuteTransitions更进一步对每一次观察无论是否阻塞检查execute转换只要发现一个命名了操作却没携带可运行命令的转换就直接让 journey失败而不是把它移到某个桶里——因为桶可以争论而失败与退出码不能靠教会某个调用点接受坏形状来满足。五、摩擦基准不再争论改为测量到了一定时候作者不再争论它是不是更好了而是测量它。工具统计你多久卡住一次更重要的是你怎么卡住的In band带内—— 它拦住你并告诉你要运行什么Out of band带外—— 它拦住你但什么都没告诉你Dead end死路—— 它拦住你而你再无计可施它不测量速度。速度取决于 provider 和当天的心情摩擦才是你自己的。而且它真的随仓库发布它在bench/中驱动真实二进制而非 mock你可以指向自己的构建cd bench go run . run --binary $(command -v gentle-ai)这是刻意的。一个我发布而你无法复现的数字是对我诚实度的断言一个你自己能跑出来的数字才是证据。5.1 七维度指标与块分类器bench/README.md详细定义了七个摩擦维度全部由 bench/metrics.go 中的同一个 accumulator 聚合run与analyze共用#维度计数什么如何计算1human_prompts流程会停下问人类的次数非 TTY 运行统计 consent-skipped 的 stderr 通知出现次数2manual_tokens需要手工组装授权的步骤argv 携带非空--maintainer-authorization的调用3commands_to_completion从开始到终态的产品调用数journey 发出的每个产品调用4blocks每个非零退出或拒绝分五个桶见分类器5recovery_round_trips阻塞与流程恢复之间消耗的命令数从阻塞命令到第一个非阻塞命令6model_runs流程所需的审查者/lens 调用含重跑driven 模式实测observed 模式为 proxy7human_surface_bytes面向人类叙述的字节数stderr 总字节数另有信息性字段git_subprocessesGIT_TRACE 计数刻意不计入七维度。分类器是承重墙且刻意机械化给定相同字节永远返回相同分类in_band / out_of_band的分裂不会在两个运行或两个审查者之间漂移成观点。它位于 bench/classify.go 的单个函数Classify中并按序判定流程无额外命令继续 →self_recovered发射文本含可运行gentle-ai verb …→in_bandstdout JSON 信封携带非空next_action/recovery_operation/collect.capture_operation→in_band语料声明拒绝正确且引用的下一动作文本确实出现在发射字节中 →by_designjourney 语料声明无续接 →dead_end否则 →out_of_bandby_design是刻意最贵的声明它需要一个封闭词汇表中的形状operator-knowledge/world-action/human-authority外加一段产品自身 next-action 文本的引文分类器会验证这段引文真的在输出字节里。dead_end与by_design是同一问题的相反答案一个步骤同时声明两者会让整个 run 拒绝启动。5.2 两种模式与诚实契约rundriven驱动这个固定语料要花这个二进制多少钱可复现、可在二进制间比较。recordanalyzeobserved一个真实 Agent 这个会话实际经历了什么对单个 Agent、单个会话诚实。compare拒绝比较 driven 与 observed 的结果——它们测量不同总体表格会毫无意义。当二进制的 CLI 表面缺失时journey 先探测verb --help不计入计数缺失表面记录为unsupported并排除在总计之外——unsupported从不渲染为 0因为这个版本做不到不能被加总成这个版本需要零。run对失败 journeyfail-closed任何 journey 报告failedrun 就非零退出社区 issue #1883 发现旧行为会吞掉退出码让 CI 在什么都没测时看到成功。基准还公开声明自己不测量什么墙钟时间由 provider 主导、不可比、真实模型 tokenprovider 相关、不可复现、昂贵、单一复合摩擦分数加权和可以在dead_end和out_of_band上升时变好塌缩维度会恰好隐藏最该关心的回归。bench/README.md中还有一份完整的诚实契约逐条列出已知缺口——包括 observed 模式下model_runs是 proxy、human_prompts从不计数真实提问、by_design是唯一可以被 gamed 的数字等。5.3 首测与语料的成长第一次测量六个阻塞每一个都是 out of band。然后语料本身成了问题十四个 journey 全部取自测试指南只测量了测试者已经走过的路径。二十二个新 journey走向了那些路径从未到过的地方裸仓库、链接工作树、半途而废的 merge、零字节文件、审查中途翻转的开关。最新一次全部三十六个零死路。十五个 in band三个 out of band两个按设计声明为正确by design。作者强调阻塞总数没有变。这正是要点而且花了一段时间才看清——工具并没有比之前更少地拦住你。它拦你的次数完全一样只是现在它告诉你怎么出去。测量还教会了作者两件关于测量本身的事。第一次修复后运行的数字与之前逐字节相同——因为构建静默失败他测量的是旧二进制。第二次更糟分析器把 kill switch正常工作计成了工具造成的摩擦——因为一个把交付交还给普通策略的门仍然报告allowed: false。它自己都说明白了什么都没被拦住。一个奉承你的仪器毫无用处一个以错误罪名给你定罪的东西更糟。一位测试者比工具自己说得更好它正确传达了状态但没有提出续接命令。六、循环测量、修复、重建、再测量有了基准之后显然的下一步是停止阅读它、开始跑它测量修复它发现的重建再测量。一直循环到数字不再变动。这个小主意有一个锋利的边缘循环只有在允许你发现仪器本身错了时才能工作。一个只能修复产品的循环会愉快地收敛到一个谎言上。第一轮很整洁两个阻塞命名了维护者而操作者本可独自清除它们——在这两种情况下正确的原因已经躺在 JSON 里为机器计算并发布却在人类读取的那行上被丢弃了。另外两个经证实是正确地拒绝价值与修复等同因为现在它被白纸黑字写下了为什么。语料增长到三十六个后第二轮发现了作者独自不会找到的那一个kill switch 没有阻止任何东西被写入。关闭审查review start拒绝正确。运行review finalize返回成功状态 approved磁盘上出现终态回执。一个审查在审查被关闭的情况下被批准了。原因几乎可笑。授权函数是对的。它有两个模式一个用于开始、一个用于推进而推进那个在源码中被注释为Disabled mode rejects it禁用模式拒绝它——却没有被任何地方调用。一个生产调用者总是传另一个模式。这个守卫被写出来、被推理过、被注释过却从未被接上线路——这正是它的单元测试一直愉快通过的原因。而它不仅仅是整洁问题因为承诺是重新开启审查会重新验证一切从未被审查过的东西。在开关关闭期间铸造的回执能存活过重新开启且没有任何东西重新验证它。第三轮作者打破了自己的测量用错误的包路径构建二进制构建失败没有阻止后续运行基准测量了前一个二进制。破绽是总计与上一轮逐字节相同。真实变更后不动的数字不是安慰是症状。第四轮在同一分支第三次发现同一缺陷具体原因被计算、发布到机器信封、又在人类路径上被丢弃。三个不同地点相隔数月。第二次就不再是 bug第三次它是一个形状现在被写成一种形状。这一轮还抓到一个比 bug 更尴尬的东西一个升级后的审查告诉操作者运行review.status。它看起来像命令。它是内部路由名输入它什么都不做。更糟的是作者第一次修复时正准备把它翻译成真实命令——而做这项工作的 Agent 证明了真实命令在那里同样解决不了任何问题。它描述状态它不移动状态。命名一个运行了却无济于事的命令比什么都不命名更昂贵因为现在人信任它。循环仍在运行。那不是未能收敛那是一个循环在诚实状态下应有的样子。七、作者自己犯的错因为如果要诚实就得整个儿地诚实写了指南步骤却不运行它们。三次。测试者照着做不工作并上报失败。新规则由此而来命名一个续接之前先执行它。把发现改成了文档补丁。三个不同的测试者无法完成一个流程。作者没把这当作数据而是把配方写进了指南。维护者指出这样做摧毁了测量并掩盖了缺陷。作者回退了。真正的缺陷是工具有一个命令正好发射了所需之物却没有路径通向它。在 Agent 正在写入时未经阅读 diff 就暂存文件。作者卷走了别人 154 行半成品推了一个无法编译的分支。有棘轮、守卫和测试要求命令工作——它们都保护不了你免于一次仓促的git add。追了一个属于自己的测量错误的缺陷。作者把命令输出写进了被测的仓库内部这添加了一个文件、改变了状态系统正确地拒绝了。丢了一个小时。但有好事发生那次拒绝同样什么都没解释所以作者修了它现在它在指南里被记录为一个陷阱。这条不要把输出写进被测仓库的规则如今已成为 docs/testing/organic-rdd-testing-guide.md 中测量章节的第一条警告。八、落到哪里成果清单四个 macOS 缺陷在真实硬件上关闭并验证而非合成 profile。Windows 首次实现自我更新测试指南 Flow 25/26 曾标注从未在真实 Windows 上运行这正是它们作为公开流程存在的原因。Codex 曾经在同步后以损坏状态启动现在完全不碰它的配置文件——用同步前后相同的 inode 号验证意味着它根本没被打开写而不只是相同字节被写回。kill switch 现在是真正的 kill switch。其余事项保持开放写在技术文档里——一份诚实的缺失清单胜过一次声称一切都完成了的发布。九、学到了什么八条教训好的决策不会在与 Agent 接触后幸存除非有东西强制执行它们。作者指挥了审计、推理和架构Agent 还是构建了没人要的东西。指挥得好是必要的但不充分。这个差距就是这个工具存在的全部理由——作者花了三个月重置额度才发现自己需要自己的工具。一个验证某物被发射的测试并不验证它可用。这个区分解释了这一分支上几乎每个缺陷。一个没人调用的守卫不是守卫。kill switch 有一个被写好、被文档化、被推理过、精确拒绝它该拒绝之物的守卫却什么都没接。它的每个单元测试都通过。从未被触及的正确代码与从未被写出的代码无法区分而且它更危险因为它读起来像覆盖率。先让仪器对准自己。基准花了一轮把 kill switch 正常工作计成工具摩擦又花了一轮测量一个作者没构建成功的二进制。两次数字看起来都合理。一个你无法审计的测量只是带小数点的观点。仍然被文档化的死代码是谎言。有一个函数安装依赖。没人调用它。文档说工具会安装依赖。一个 Linux 用户读到它并期待它工作。过度工程化比 bug 更难移除。Bug 是可见的。一套没人要、却构建精良且自洽的架构会为自己辩护。社区发现审计发现不了的东西。这几天最有价值的四份报告来自在自己的机器、自己的仓库、自己奇怪配置下使用工具的人。没有内部审计会发现它们因为审计寻找的是你已经知道要找的东西。压倒一切的规则如果你告诉别人怎么做确保它有效。十、深入阅读仓库内的配套资源docs/architecture/organic-rdd.md——本故事的技术另一半原子交易生命周期、preflight/START、跨仓库根连续性、审查与终结FINALIZE、信息性门与交付边界、完整 mermaid 生命周期图。docs/testing/organic-rdd-testing-guide.md——社区测试指南Flow 1–19 通用、Flow 20–23 macOS 专属、Flow 24–26 等待真实机器、Flow 27–33 无法在临时目录构建的环境网络挂载、只读文件系统、磁盘写满、大小写不敏感卷、杀毒软件、长路径、时钟回拨以及How to measure properly的六条环境陷阱。bench/README.md——摩擦基准的完整规格七维度、块分类器、两种模式、opt-in 轴damaged-store与real-world、诚实契约十三条、当前构建的实测数字与跨版本对比示例。bench/classify.go——分类器的承重实现IsBlock、IsUnsupported、Classify、HasRunnableCommand、DeadExecuteTransitions。bench/main.go 与 bench/metrics.go——四个命令run/record/analyze/compare的入口与七维度聚合器。internal/cli/review_mode.go——用户级 kill switch 的 CLI 投影、consent 会话、--consent relay/granted/declined协商语义。internal/reviewtransaction/rdd_mode.go——开关的底层语义ResolveRDDMode、AuthorizeRDDOperation、克隆级 off-only 覆盖与 compare-and-set 代际、disabled/unmanaged交付投影。bench/AGENT-PROMPT.md——record模式开箱即用的 Agent 提示词三条让测量有价值的规则Agent 不得读源码、卡住就是发现、每条命令加CI1。如果你把整条线串起来读——先是这段修复实录再是架构文档再是测试指南与基准——你得到的不只是一套审查机制而是一套可运行的、自我纠错的工程方法让决策有约束力让每条消息可执行让每个数字可复现。赞分享【免费下载链接】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 仓库中自带的独立基准测试gbrain 摩擦协议Friction Protocol用 gbrain friction 构建可复现的 Agent 反馈闭环gbrain 摩擦协议Friction Protocol用 gbrain friction 构建可复现的 Agent 反馈闭环 本篇技术指南围绕 gbra人工智能RAGAgent 记忆MCP 服务知识管理Gopeed HTTP 下载中文文件名乱码1 条 5 级解码链 1 个 UTF-8 校验门3 步定位Gopeed HTTP 下载中文文件名乱码1 条 5 级解码链 1 个 UTF 8 校验门3 步定位 Gopeed 是一款支持 HTTP、BitTorr网络CLI后端上一篇三步解除Android应用截图限制Enable Screenshot完整使用指南下一篇KubeVela command Trait 实战指南精确覆盖 Pod 容器 Command 与 Args创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考