【免费下载链接】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 通过 OpenCode 原生的task权限background: true驱动后台子代理执行替代了早期的background-agents.ts插件方案。本文从安装/同步偏好、auto|on|off解析优先级、托管启动器机制、内嵌使用策略到源码实现逐层展开帮助你准确配置并安全使用 OpenCode 后台执行能力。读完本文你将掌握如何用gentle-ai install/gentle-ai sync控制该特性理解进程本地、非持久、无文件系统隔离等边界并知道何时该让任务回到前台。一、背景从 legacy 插件到原生子代理Gentle AI 为 OpenCode 提供的后台执行能力走的是 OpenCode 自身的原生通道通过task工具的background: true字段把子代理调度到后台。这与早期基于background-agents.ts插件的方案有本质区别——后者是外部注入的插件机制而前者直接使用 OpenCode 内建能力。当前仓库默认不安装 legacybackground-agents.ts插件且后台执行是可选的、独立的它不依赖 ODDOrganic-Driven Development模型配置开启或关闭后台子代理都不会影响模型选择与评审角色配置见 docs/opencode-profiles.md。二、执行偏好auto / on / offinstall与sync两个命令接受完全相同的偏好值取值仅有三种auto、on、off。典型用法gentle-ai install --agent opencode --opencode-background-subagentson gentle-ai sync --agent opencode --opencode-background-subagentsoff同时也可以通过环境变量表达偏好export GENTLE_AI_OPENCODE_BACKGROUND_SUBAGENTSauto|on|off解析优先级当多种来源同时存在时偏好按以下顺序决定CLI flag 最高--opencode-background-subagents...显式传入时直接胜出非空环境变量次之GENTLE_AI_OPENCODE_BACKGROUND_SUBAGENTS存在且值非空时生效Gentle AI state 中此前的 managed 选择即上次持久化保存的 on/off 选择默认值auto。这一解析逻辑的源码实现在 internal/cli/opencode_background.go 的ResolveOpenCodeBackground中它分别解析 CLI 值、环境变量与持久化 prior 状态再按CLI set env set非空 prior on/off auto的 switch 分支收敛出最终结果。值得注意的细节是显式auto与环境变量形式的auto不会自行创建 managed 选择它只会在已有 prior on/off 时继承该选择当既无 prior 又无显式设置时非交互调用按off前台处理。交互式安装器在没有先前或显式设置时可能会询问一次偏好取消安装则不会保存任何新偏好避免用户被半途写入状态。类型定义与合法性校验见 internal/model/types.goOpenCodeBackgroundIntent取值auto|on|offParseOpenCodeBackgroundIntent会拒绝任何其他值并给出明确的错误信息。三、托管启动器机制当偏好解析结果为on且 OpenCode 运行时具备后台能力时Gentle AI 会在~/.gentle-ai/bin/下写入仅属于自身的启动器文件平台启动器路径POSIXLinux/macOS/WSL~/.gentle-ai/bin/opencodeWindows~/.gentle-ai/bin/opencode.cmd与~/.gentle-ai/bin/opencode.ps1启动器的核心行为是仅在环境变量尚未定义时设置OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTStrue。也就是说如果你显式导出OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTSfalse启动器不会覆盖它执行会保持在前台。这一非覆盖语义在 internal/opencode/background.go 的三个平台实现中一目了然POSIX 脚本使用if [ -z ${OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTSx} ]判断Windows cmd 使用if not definedPowerShell 使用Test-Path Env:。激活前置检查能力解析与版本门槛Gentle AI 并非无脑写入启动器。在写入前ResolveCapability 会执行一次类型化能力判定ready | unsupported | unknown先解析出真实的 OpenCode 目标路径排除~/.gentle-ai/bin自身避免循环见ResolveTarget运行opencode --version通过ParseVersionOutput提取语义化版本与MinimumBackgroundVersion1.15.11比较低于该版本判定为unsupported不写入启动器、保持前台执行版本达标才判定为ready并标记需要重启。激活过程本身是可回滚的事务ActivationPlan准备阶段快照既有启动器内容与权限写入失败会Rollback恢复原状同时只在启动器内含gentle-ai:managed-opencode-launcher/v1所有权标记时才在停用时移除拒绝删除用户自有的同名文件见 internal/opencode/background.go。重启要求激活成功后必须重启 OpenCode让后台子代理环境变量被继承若 shell 的 PATH 尚未刷新还需重启 shell。这在能力解析结果中会附带明确的RestartGuidance见 internal/opencode/background.go。四、不会继承托管环境的会话托管启动器只对经由它启动的会话生效。以下三种启动方式不会继承托管启动器环境会回退到前台执行opencode serveopencode attachOpenCode DesktopGentle AI 不会改写这些会话的配置见 docs/opencode-profiles.md。这也意味着如果后台执行对你的工作流是刚需请务必通过托管后的opencode命令PATH 中的~/.gentle-ai/bin/opencode启动会话。五、后台任务的边界与限制后台子代理是进程本地process-local且非持久non-durable的重启 OpenCode 即丢失全部后台任务Gentle AI 不会做任何恢复承诺。此外它不提供文件系统隔离。因此官方使用建议非常明确后台执行只适合相互独立的只读工作如独立探索、审计、审查禁止用于依赖型任务或同一工作区内的并行写入者。六、内嵌策略什么能后台、什么必须前台开启该特性时Gentle AI 会在受管 orchestrator prompt 中注入一段以 marker 包裹的策略文本全文见 internal/assets/opencode/background-subagents.md核心约束如下允许后台仅限独立的、只读的探索、审计、审查工作父级可继续不重叠的工作并发上限父级同时运行的后台任务不超过2 个通知纪律只接收完成通知不得轮询、sleep、运行状态检查、主动读取完成状态必须前台需要结果后才能继续下一步的场景——用户决策、SDD apply 或其他写入者、依赖性的 verify 证据、归档、正式的 RDD/4R lens、refuter、fix validator、Judgment Day actors、以及所有依赖阶段禁止重复与重叠不重复发起或重复工作不重叠文件或主题绝不在同一 worktree 中运行并行写入者能力降级若 Task 工具 schema 中缺少background字段或该能力被禁用/未知则省略background并在前台运行任务。策略的注入与移除由 ApplyOpenCodeBackgroundPolicy 完成它只在受管的 OpenCode settings 中定位受管 orchestrator agent 的prompt通过!-- gentle-ai:opencode-background-subagents --与!-- /gentle-ai:opencode-background-subagents --两个 marker 进行幂等的增删且只改动 prompt、保留用户其余所有设置mustBackgroundOverlay仅序列化 prompt 字段做 JSON 合并。off时移除策略块缺失 agent 时不会仅为承载后台策略而凭空创建 agent。七、模型选择与评审角色后台子代理偏好只解决是否允许后台执行这一执行维度不涉及模型选择与评审角色。相关配置请使用 TUI 的Configure Models屏幕完成详见 docs/usage.md#model-assignment。八、验证与测试仓库中该特性的行为由多层测试锁定internal/cli/opencode_background_test.go覆盖偏好解析优先级cli outranks environment and prior等用例、非法取值拒绝如maybe、启动器写入/移除与策略 marker 存在性断言internal/opencode/background_test.go覆盖版本解析、能力判定、启动器内容与所有权标记、回滚语义internal/components/agentguidance/opencode_background_test.go覆盖 prompt 策略的注入、移除与 marker 校验损坏 marker 会报错拒绝写入。如果你想在不动真实环境的前提下预览激活计划可使用--dry-run见 internal/cli/install.go 帮助文本它只输出计划而不做任何文件变更。九、快速决策清单场景推荐配置希望后台子代理执行独立只读审查gentle-ai install --agent opencode --opencode-background-subagentson明确关闭后台、全部前台执行gentle-ai sync --agent opencode --opencode-background-subagentsoff跟随此前选择、由状态决定不传 flag不设环境变量默认auto全局临时强制关闭export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTSfalse后启动托管 opencodeOpenCode 版本低于 1.15.11能力判定unsupported自动保持前台无需手动干预整体而言Gentle AI 对 OpenCode 后台子代理的管理遵循最小侵入原则只写属于自己的启动器、只改受管 prompt、显式false一律尊重、非持久任务不做恢复承诺。把后台能力严格限定在独立只读工作上是使用该特性最稳妥的姿势。赞分享【免费下载链接】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 心智模型AI 编程 Agent 生态配置器的架构边界与工作流Gentle AI 心智模型AI 编程 Agent 生态配置器的架构边界与工作流 Gentle AI 是一个面向 AI 编程 Agent 的生态配置器它负责Gentle-AI 与 Kiro IDE 集成指南原生子代理、SDD 执行模型与 Split-Root 配置布局Gentle AI 与 Kiro IDE 集成指南原生子代理、SDD 执行模型与 Split Root 配置布局 导读 本文以 Gentle AI 官方文档Gentle-AI 接口全景CLI、TUI 与 MCP 配置边界的源码级解析Gentle AI 接口全景CLI、TUI 与 MCP 配置边界的源码级解析 Gentle AI 是一个为 Claude Code、Cursor、OpenCo上一篇408备考我用一份历年真题考频表砍掉了三成无效复习下一篇GetQzonehistory三步完成QQ空间历史说说完整备份的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
