【免费下载链接】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点击查看免费下载本文以仓库内任务文档 odd/tasks/sdd-retirement-followups.md 为骨架围绕 gentle-ai 在 PR #4998、#5005 之后遗留的 9 项跟进事项F1–F9逐一讲解其根因、修复策略与对应源码实现。读完本文你将掌握 gentle-ai 在“SDD 组件退役Retirement”与原生 Review 机制落地过程中如何处理权限所有权证明、fail-closed 渲染、原子写入的权限位保留、卸载清理边界、install/sync 收敛、封闭测试与 Homebrew 无副作用执行等真实工程问题并可直接按任务文档中的 PR 切分A–E与检查清单复现验证流程。一、背景一次围绕“退役与收尾”的工程治理odd/tasks/sdd-retirement-followups.md是一份典型的工程收尾任务文档它记录了 gentle-ai 将旧有的 SDDStructured/Strategy-Driven Development由 v3.7.0 引入的sdd-orchestrator模块体系退役、全面转向 ODDOrganic-Driven Development与原生 Review 生命周期之后PR #4998 与 PR #5005 留下的全部已知粗糙边缘rough edges。文档目标非常明确Close every follow-up left by PR #4998 and PR #5005 so the next release ships without the known rough edges.任务文档2026-09-26 创建工作区来自origin/main的 6471b688e文档本身由 PR Afix/review-guidance-ownership持有把收尾工作组织为三块Scope授权范围F1–F9 共 9 项具体跟进事项Tasks任务T0 根因地图 T1–T5 分 PR 落地其中 T1 与 F4 已完成[x]T2–T5 待交付Checks / Delivery / Progress / Next step验证标准、交付策略stacked-to-main 的小独立 PR与进度记录。下文将以 F1–F9 为脉络逐一结合仓库源码展开。二、T0 根因地图九项跟进事项的定性结论在动工前T0 任务先对每一项做了根因定性这是整份文档的“罗盘”编号问题T0 根因结论F1Kilo 清理误删用户权限只允许删除“本次运行中按 managed 身份移除的 review 条目”或 legacy__managed_by标记对应的gentle-orchestrator.permission.task.review-*键绝不触碰用户自行配置的权限F2review 契约依赖 CLI-onlyinit()生产中唯一调用方是 CLI改为通过RoutingOptions传递 sourceF3orchestrator 渲染失败静默阻塞 routing 块实际行为已 fail-closed渲染失败即步骤失败并回滚非静默F4v3.7.0 遗留~/.kimi/sdd-orchestrator.mdv3.7.0 通过StrategyJinjaModules写入的是“占位符已展开”的渲染产物不可复现 → 无所有权证明main的KIMI.md已不再 include 它惰性/inert→ 保留在磁盘并记录说明F5固定0o644重写会放大私有文件权限约 76 处字面量权限调用点有意设置 mode 的包括 gga 运行时脚本 0755、claude adapter OAuth 0600、backup restore、opencodeplugin restoreF6卸载未移除 OpenCode/Kilo 托管 agent 条目卸载目前只移除 OpenCode 的agent.gentlemanshape 判定位于internal/cliuninstall 无法 import cliF7install 后首次 sync 重写 system-prompt 文件install 在 persona 之前运行 codegraph guidanceGentleman persona 重写 FileReplace 提示文件时丢弃 codegraph 段落sync 又把它加回F8Pi 测试读写真实~/.gentle-shellPI_CODING_AGENT_DIR绝对路径由 Gentle Shell 导出会覆盖 Pi adapter 中的 homeDirF9gentle-ai install触发 Homebrew 自动更新executeCommand继承环境变量代码中没有任何HOMEBREW_*设置这份根因地图的价值在于每一项收尾工作都不是“猜着修”而是先定位到具体调用链再决定“改代码 / 改结构 / 不改并记录”中的哪一种处置。F3、F4 最终结论都是“现状已可接受文档化即可”这正是工程收尾中最容易被忽略的决策类型。三、F1 / F6权限所有权证明Managed Shape驱动的清理边界F1 与 F6 共享同一个核心设计原则只有能证明“这份配置是 gentle-ai 自己写的”才允许在清理/卸载时删除它。3.1 F1Kilo 任务权限清理只认“managed 条目”F1 的场景是 Copilot 在 PR #5005 上指出的风险Kilo 清理逻辑只允许丢弃本次运行中按 gentle-ai-managed 身份移除的 review 条目的gentle-orchestrator.permission.task.review-*键或 legacy__managed_by移除永远不能删除用户配置的权限。实现位于 internal/components/uninstall/opencode_agents.go 的removeOpenCodeFamilyAgents遍历agent映射时先看__managed_by gentle-ai/sdd的 legacy 标记条目其中sdd-前缀的交给 settings 退休流程其余按opencodeagents.LegacyOwned决定删除或仅剥离标记对无标记条目分别用GentlemanShapegentleman条目与ShapeUninstallRole 识别出的角色做字节级 shape 比对匹配才删除随后处理agent.gentle-orchestrator.permission只删除“本次 removed 集合中出现过的 task 授权键”授权清空后如果只剩 install 写下的*: deny通配拒绝则一并删除question: allow只有installedQuestionShape能证明是 install 写的才删除证明不了的allow保留并向用户报告——例如输出 “Kept agent.gentle-orchestrator.permission.question allow ... gentle-ai cannot prove it wrote it”。Shape 判定函数集中在 internal/components/opencodeagents/agents.goLegacyOwnedv3.7.0 标记角色的所有权、UninstallRole当前运行时角色 已退役的 Kilo review 角色、GentlemanShapepersona 叠加层允许用户自选model/variant其余字段必须字节一致、Shape托管角色同样只容忍 model/variant 偏差。这套“可证明所有权才动手”的模式在 internal/components/uninstall/opencode_agents_test.go 中有矩阵化用例覆盖install shape、用户自建规则、用户委托目标、无委托授权等 4 种形态。3.2 F6卸载必须同时清掉 agent 条目与 orchestrator 任务权限T0 定位的根因是卸载逻辑internal/components/uninstall不能 importinternal/cli而 managed shape 判定当时长在 cli 里。F6 的修复方向T2PR B是卸载时移除 gentle-ai-managed 的 OpenCode/Kilo agent 条目仅 managed shape同步移除它们在gentle-orchestrator上的任务权限把 managed specs / shape 判定谓词下沉到cli 与 uninstall 都能引用的组件包即如今的internal/components/opencodeagents见上节。这正是仓库里已经形成的结构opencodeagents包以Spec名称、描述、权限表声明gentle-ai-explore、gentle-ai-verify、gentle-ai-worker、jd-judge-a/b、jd-fix-agent、review-*系列角色的标准形态卸载侧与安装侧共用同一套判定避免“安装写一种形状、卸载认另一种形状”的漂移。四、F2 / F3Review 契约注入与渲染的 fail-closed 语义4.1 F2把 review 契约从 CLIinit()改为显式注入F2 要求agentguidance.RenderOrchestrator的 review 契约来源不得依赖仅存在于 CLI 的init()应通过注入 / render 选项或依赖中立的 seam传递并保持显式的 fail-closed 行为。现在的实现位于 internal/components/agentguidance/orchestrator.goReviewContractSource定义为func(model.AgentID) (string, error)生产环境指向 reviewassets 的ReviewExecutionContractFor提供RenderOrchestratorWithSource(agent, source, capability)source 优先于包级 fallback包级SetReviewContractSource仅作为测试回退保留internal/components/agentguidance/export_test.go 注释明确installer 必须总是显式设置RoutingOptions.ReviewContract字段internal/components/agentguidance/inject.go让InjectRoutingWithOptions把契约一路传到 orchestrator 渲染。配套的 fail-closed 语义由ErrMissingReviewContract“review execution contract source is not configured”承载当运行时广告了原生 review 传输能力、却拿不到契约时reviewExecutionContract返回错误——因为“安装一个没有流程说明的 review 生命周期比拒绝安装更糟”源码注释原话。同时非 RDD 运行时绝不会被塞入 review 生命周期stripReceiptDrivenDevelopment会移除 Provider Defect Handoff 块、替换 Native Checking Contract 为 “(ODD only)” 变体并通过nonRDDLeakMarkers“RDD”、“receipt”、“native review”、“gentle-ai review” 等做渲染泄漏检测命中即渲染失败。4.2 F3渲染失败必须显式失败步骤而非静默阻塞 routing 块T0 结论是“现状已 fail-closed非静默”T1 的落地是把行为固定为显式错误。渲染管线中的关键路径InjectRoutingWithOptions先渲染 routingRenderRouting再渲染 orchestratorRenderOrchestratorWithSource任何一步出错都在写盘前返回错误源码注释“Render before resolving the delivery so an unsupported agent is rejected without having touched the filesystem”错误信息会点名 agent 与 remediation例如 “render orchestrator for %q: review contract source was not wired ... (set RoutingOptions.ReviewContract)”sync 侧由 pipeline 编排器以默认回滚策略执行整个计划失败步骤触发快照恢复——internal/cli/sdd_runtime_retirement_test.go 的TestSyncRollbackRestoresRetiredCodexAndKimiFiles正是注入一个sddRetirementFailingStep断言退役发生在失败前、且所有 removed/rewritten 文件被逐字节恢复。五、F4无所有权证明的遗留模块——“不改但要记录”F4 针对 v3.7.0 写入~/.kimi/sdd-orchestrator.md的遗留模块。T0 的推导链是v3.7.0 通过 Kimi adapter 的StrategyJinjaModulesinternal/agents/kimi/adapter.go把渲染后的提示词占位符已展开写入该文件因为是“展开后的产物”无法复现出可做 byte/hash 比对的 v3.7.0 渲染结果 → 无法证明所有权同时当前main的KIMI.md已不再 include 它inert继续留在磁盘无害。因此 F4 的最终处置是零代码改动 文档化文档任务行标为[x]“no code change (no ownership proof; inert). Documented”。这条决策本身值得注意清理不等于删除一切看起来像“旧物”的文件在所有权无法证明时保守保留并说明是比激进删除更安全的工程选择。相关行为在 internal/cli/sdd_runtime_retirement_test.go 中大量可见sync 会按 v3.7.0 资产releasedSDDAsset的kimi-sdd-orchestrator.md、kimi-KIMI.md退休掉能证明所有权的旧文件从KIMI.md移除{% include sdd-orchestrator.md ignore missing %}、删除.kimi/sdd-orchestrator.md等而用户自建 profile 则保留并列入ManualActions提示。六、F5原子写入必须保留既有权限位F5 是系统性systemic问题配置写入器用固定0o644重写既有文件会把用户收紧的私有文件如含凭据的 settings 文档放大权限。T0 统计约 76 处字面量权限调用点并区分出 4 类有意设置 mode 的调用gga 运行时脚本0755、claude adapter OAuth0600、backup restore、opencodeplugin restore。修复的核心在 internal/components/filemerge/writer.goWriteFileAtomic(path, content, perm)perm只在文件不存在时生效重写既有常规文件时保留其当前权限位ExistingFileMode兜底私有文件绝不会因为被重装/重同步而变宽WriteFileAtomicMode(path, content, perm)显式强制的 mode API用于“调用方完全拥有目标 mode”的场景可执行脚本、钉死固定 mode 的凭据文件、按记录 mode 重建的 restorecontent 未变也会落地 mode-only 修复ExistingFileMode(path, fallback)返回既有常规文件的权限位权限位为 0 的常规文件返回0600最窄但仍可回读的 mode确保绝不放大配套的RefuseLockedSettingsFile在动任何相关资产前拒绝 symlink、非常规文件与 mode 0000 的锁定 settings避免改写被故意锁定的文件。写入序列本身也是“元数据先行”的耐久性设计staged 文件Chmod→Sync→Close→Rename→ 从磁盘回读 digest 校验 →SyncDir。其中回读校验针对 Windows 上反病毒/索引器把 rename 变成静默 no-op 的形态#2319保证WriteResult.Changed描述的是磁盘现实而非写入意图。七、F7install 与 sync 的收敛——codegraph guidance 与 persona 的先后顺序F7 的表现为“install 之后的首次 sync 会重写多个运行时的 system-prompt 文件”。T0 根因是一个顺序问题install 在 persona 之前运行 codegraph guidanceGentleman persona 会重写 FileReplace 型提示文件并丢弃其中的 codegraph 段落sync 又按“codegraph 在 persona 之后”的顺序把该段落加回 → 两边产物不一致首次 sync 必然触发重写。从 internal/cli/sync.go 的步骤编排可以看到当前收敛方向codegraph 指导通过communitytool.RefreshCodeGraphGuidanceIfConfiguredinternal/components/communitytool/codegraph_guidance.go在 sync 计划中显式出现且代码注释多处强调组件写入顺序“selection order (persona last for full-gentleman)”、“persona 覆盖 FileReplace 代理的整个提示”。T4PR D的目标正是让 install 与 sync 顺序一致codegraph guidance 在 persona 之后并核验 hermes 与 codex 的config.toml路径使“install 一次、sync 无变化”成为可验证的收敛目标。八、F8Pi 测试的封闭化hermeticF8 指出部分 Go 测试在 HOME 未隔离时会真实读写~/.gentle-shell。根因是 Pi adapter 中PI_CODING_AGENT_DIR绝对路径由 Gentle Shell 导出会覆盖基于 homeDir 的配置路径。在 internal/agents/pi/adapter.go 中可以看到AgentConfigPath(homeDir)等路径解析对PI_CODING_AGENT_DIR敏感GlobalConfigDir/SystemPromptDir/SettingsPath/MCPConfigPath全部从配置根派生。因此 T5PR E的修复方向是在包级TestMain或共享 helper 中unset/overridePI_CODING_AGENT_DIR让 Pi 相关测试的读写落到临时 HOME而不是宿主用户的~/.gentle-shell。这与仓库中已有的internal/testenv/isolate.goXDG 隔离等封闭测试基础设施属于同一类实践测试必须描述它自己创建的沙箱而不是继承运行者机器的状态。九、F9Homebrew 调用的无副作用环境F9 的场景是gentle-ai install在 macOS 上调用brew install时触发了用户机器上非请求的 Homebrew 自动更新耗时且依赖网络。T0 根因executeCommand继承环境变量代码中没有任何HOMEBREW_*设置。修复在 internal/cli/run.go// homebrewNoSideEffectEnv 是 executeCommand 追加到 brew 调用的环境变量 // 使 gentle-ai 自己的 tap/install/reinstall 步骤绝不会作为无关安装的副作用 // 触发 Homebrew 缓慢且依赖网络的自动更新或安装后缓存清理。 var homebrewNoSideEffectEnv []string{ HOMEBREW_NO_AUTO_UPDATE1, HOMEBREW_NO_INSTALL_CLEANUP1, }commandEnv的规则非常克制仅当命令基名是brew含resolveBrewCommand解析出的绝对路径时注入显式的brew update/brew upgrade不加用户主动请求的更新路径由internal/update/upgrade自行负责见源码注释若环境里已存在同名变量不覆盖——用户显式覆盖永远优先internal/cli/command_env_test.go 断言了HOMEBREW_NO_AUTO_UPDATE0被保留的用例。这条原则与 F5 一脉相承工具的副作用必须最小化且不得覆盖用户已有的显式意图。十、任务切分、验证清单与交付策略文档最后一部分是工程执行层的信息同样值得完整保留Tasks 状态T1PR AF1/F2/F3已完成与 F4已文档化标为[x]T2PR BF6、T3PR CF5、T4PR DF7、T5PR EF8/F9待交付全部标注 “Route: delegated”委托执行。Checks验证标准每个包做隔离go test用env -i指定 HOME相对 base 做全量go test ./...跑 gofmtcheck、vet 与 cross-buildinstall 行为变化时在沙箱里跑 install/sync 矩阵。Delivery优先采用stacked-to-main 的小独立 PRA–E 各一个切片降低单个 PR 的评审与回滚成本Progress记录了 2026-09-26 三次推进文档创建 → T0 完成、切片 A–E 确定 → T1 完成、用户授权 A–E 交付、PR B writer 启动以及下一节点Next stepPR A 交付、PR B 进行中。这一节说明了一个可复用的收尾方法论把大型退役拆成“根因地图 → 独立 PR 切片 → 逐项验证 → 小步交付”每一步都有可核查的证据与明确的完成定义。十一、总结odd/tasks/sdd-retirement-followups.md表面上是 9 项待办实质上浓缩了 gentle-ai 在“退役旧机制、落地新机制”时的一套工程纪律所有权证明优先F1/F4/F6能证明 managed 身份才清理证明不了就保留并记录fail-closed 优先F2/F3渲染失败显式报错 回滚快照绝不静默降级最小副作用优先F5/F9重写保留权限位、brew 调用屏蔽自动更新、不覆盖用户显式环境可复现优先F7/F8install 与 sync 收敛一致测试隔离于宿主状态小步交付优先A–E 独立 PR 切片逐项验证后 stacked-to-main。这些结论均可在仓库源码中找到对应实现internal/components/filemerge/writer.goF5、internal/components/uninstall/opencode_agents.go与internal/components/opencodeagents/agents.goF1/F6、internal/components/agentguidance/orchestrator.go与inject.goF2/F3、internal/cli/run.goF9、internal/cli/sync.goF7、internal/agents/pi/adapter.goF8、internal/cli/sdd_runtime_retirement_test.goF4 相关退休与回滚验证。对需要在自己项目中做类似“退役 收尾”治理的读者而言这份任务文档及其源码落地是一份可以直接借鉴的路线图。赞分享【免费下载链接】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点击查看免费下载相关推荐gsd-core 清理失效生成标记从 ADR-0174 SDK 退役到 stale banner 修复的工程实践gsd core 清理失效生成标记从 ADR 0174 SDK 退役到 stale banner 修复的工程实践 本文围绕 gsd coreGet Shitpure_live EPG 导入事务、编码与下载收尾深度审计六项根因修复与源码级验证pure_live EPG 导入事务、编码与下载收尾深度审计六项根因修复与源码级验证 本文基于 pure_live 仓库 EPG_IMPORT_TRANSAC音视频直播移动开发rippled 事务处理变更的 Amendment 门控规范从 features.macro 注册到代码路径退役rippled 事务处理变更的 Amendment 门控规范从 features.macro 注册到代码路径退役 src/libxrpl/tx/AGENTS.区块链创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
