4.9 KiB
Agent Note: 产品 subagent 命名实例
Status: implemented
English | 中文
问题
Profile 可以用多个配置项挂载同一个 Cordis 插件包，但 Codex 与 Claude Code 产品提供方此前会把每个配置项都注册到一个固定产品名称下。因此，第二个配置项会在其支持时使用的独立模型、权限模式、环境或进程释放设置可用前因名称重复而失败。根据这些设置隐式派生名称会建立第二套身份规则，而在工具调用期间选择提供方会让模型输入决定部署权限。
现有 subagent 注册表已经拥有提供方名称唯一性、可逆注册、生命周期事件和由持有方拥有的已发布运行。现有 dsh-tool-subagent 配置也已经把一个提供方名称绑定到一个模型可见工具名称。产品提供方只需公开缺失的 Profile 所有身份，无需增加另一套注册表或选择协议。
决策
每个产品提供方 Config 都拥有非空的 providerName；默认值仍分别为 codex 与 claude-code。插件配置项加载时会固定解析后的名称，并把它作为 Provider 对象的 name；注册、查找、生命周期事件、运行日志和 HMR（热模块替换）移除因此使用同一个值。每个已挂载配置项保留自己的 permissionMode、env、disposeGraceMs 和运行资源。Claude Code 配置项还会保留可选的非空 model；显式值为该实例的每次 query 固定，省略时仍以原生设置为权威。
当每个配置项使用不同的 providerName 时，Profile 可以挂载多个 Codex 或 Claude Code 配置项。每个 dsh-tool-subagent 配置项继续用已有的 provider 字段绑定这个准确名称，并公开独立配置的 toolName。工具调用不携带提供方选择器、别名或权限输入。重复提供方名称沿用现有 DUPLICATE_PROVIDER 路径失败，而且不会替换第一个注册项。
移除一个提供方配置项会阻止新的启动，并且只移除绑定到该名称的工具。该实例已经发布的运行仍由其持有方拥有，并会独立结算或 dispose（资源释放）。兄弟实例继续保持注册，并保留各自支持时配置的模型、环境、原生权限模式、取消控制器、产品进程和清理宽限期。
所有权与生命周期
| 事实或操作 | 责任方 | 结果 |
|---|---|---|
| 提供方实例名称 | 产品提供方 Config | 每个已挂载配置项拥有一个不可变注册名称；省略时使用现有默认值 |
| 名称唯一性与生命周期事件 | ctx.subagents |
重复注册失败；资源释放只移除匹配名称 |
| 模型可见工具名称与绑定 | dsh-tool-subagent Config |
一个静态工具解析一个已配置的提供方名称 |
| 支持时的模型、权限、环境与进程清理 | 一个提供方实例 | 并发运行与兄弟实例不共享部署配置或运行资源 |
验证
两个产品包测试都会固定默认与自定义名称、空名称拒绝、重复注册回滚、实际名称诊断、使用不同权限模式、环境与清理宽限期的两个并发实例、取消隔离，以及移除一个实例后其已发布运行仍然有效。Claude Code 还会固定空模型拒绝、省略模型继承、两个显式模型，以及通过真实 SDK／CLI fixture 证明逐 query 精确隔离。公共 Loader 组合会为每个产品挂载两个配置项与两个不同工具，而且不启动任一产品；无密钥 ACP 快照固定最终四工具组合，并证明没有动态提供方或模型参数。
考虑过的替代方案
根据产品或权限模式派生名称。 隐式后缀会让部署设置变化同时改变身份，而且等价配置项之间仍可能冲突。Profile 会显式提供身份。
让工具调用选择提供方。 这会让模型输入选择权限与环境实例。独立工具配置项会让授权与公开范围保持静态配置。
建立产品实例目录或别名注册表。 现有 subagent 注册表已经拥有名称、唯一性、查找、事件和资源释放。另一套目录没有独立消费方，只会复制状态。
自动重命名重复配置项。 静默添加后缀会让工具绑定与生命周期诊断依赖加载顺序。重复名称继续快速失败。
结果
Profile 可以公开多个由不同原生权限模式与环境支持的 Codex 与 Claude Code 工具，Claude Code 实例还可分别固定模型，而现有配置仍会解析为 codex 与 claude-code。提供方名称与工具名称继续是彼此独立的配置事实，因此修改其中一项时必须同时更新引用它的绑定。
本设计不增加运行时改名、模型可见的提供方或模型选择器、自动生成的工具名称、持久实例目录、共享进程池、模型发现、fallback 或兼容别名。正确的多实例配置要求提供方名称与工具名称都保持唯一；重复工具名称的等待问题仍是独立限制。