diff --git a/docs-site/src/content/docs/fr/guides/sub-agent-surface.md b/docs-site/src/content/docs/fr/guides/sub-agent-surface.md index 87c11ebcec..960bf2684b 100644 --- a/docs-site/src/content/docs/fr/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/fr/guides/sub-agent-surface.md @@ -64,10 +64,16 @@ conversationnelle. Les continuations avec état utilisant `previous_response_id` à l’identique figure dans ce préfixe. Lorsque les directives changent, le protocole de l’outil principal reste en première position et les nouvelles directives sont insérées avant l’entrée conversationnelle actuelle. -Ce sont des instructions destinées à l'agent principal, et non à un routeur de génération côté proxy. Sur la v2, un fork avec historique complet -hérite du modèle parent et rejette les remplacements de modèle ou d'effort. Le guidage indique donc à Codex de -utilisez `fork_turns: "none"` (ou un compte de tour partiel positif tel que `"3"`) lorsque vous dépassez `model` ou -`reasoning_effort`, et de rendre le message de tâche autonome. +Ce sont des instructions destinées à l'agent principal, et non à un routeur de génération côté proxy. L'indication d'usage v2 propre à Codex +indique à l'agent qu'un fork avec historique complet (`fork_turns` omis ou `"all"`) hérite du modèle et de l'effort de raisonnement du parent, +et qu'il ne doit donc pas y joindre de remplacements. Le guidage indique donc à Codex d'utiliser `fork_turns: "none"` (ou un compte de tour +partiel positif tel que `"3"`) lorsqu'il transmet `model` ou `reasoning_effort`, et de rendre le message de tâche autonome. + +Traitez cela comme une convention au niveau du prompt plutôt que comme un rejet strict à l'exécution. Codex rejetait autrefois `agent_type`, +`model` et `reasoning_effort` sur un fork v2 à historique complet ([openai/codex#20077](https://github.com/openai/codex/issues/20077)), mais +[#37252](https://github.com/openai/codex/pull/37252) a supprimé cette vérification, et le gestionnaire de spawn v2 actuel applique les +remplacements de modèle quel que soit le mode de fork. Suivre la convention reste néanmoins la voie fiable, car l'agent est invité à éviter les +remplacements sur un fork complet. Le texte personnalisé de `injectionPrompt` peut utiliser les quatre espaces réservés suivants : @@ -227,8 +233,15 @@ l’agent principal décide toujours s’il doit déléguer. ### Pourquoi mon enfant v2 a-t-il utilisé le modèle parent ? -Un fork v2 à historique complet hérite du modèle parent. Utilisez un spawn qui définit `fork_turns` sur `"none"` ou -un décompte partiel positif avant de passer un dépassement de modèle ou d'effort. +Les agents générés héritent du modèle parent dès que `model` est omis, et c'est le comportement par défaut pour tous les modes de fork, pas une +conséquence propre au fork avec historique complet. L'indication d'usage v2 intégrée à Codex demande en outre à l'agent de ne pas joindre de +remplacements sur un fork à historique complet, de sorte qu'il peut délibérément laisser `model` non défini. Transmettez un `model` explicite +sur un spawn qui définit `fork_turns` sur `"none"` ou un décompte partiel positif. + +Si le champ `model` est totalement absent du schéma de l'outil, la cause est son exposition et non le mode de fork : vérifiez +`features.multi_agent_v2.expose_spawn_agent_model_overrides` dans Codex (activé par défaut), et consultez +[openai/codex#31814](https://github.com/openai/codex/issues/31814) pour les parents ChatGPT natifs dont le schéma de collaboration est figé par +le backend. ### Pourquoi un modèle configuré manque-t-il dans la liste v2 ? diff --git a/docs-site/src/content/docs/guides/sub-agent-surface.md b/docs-site/src/content/docs/guides/sub-agent-surface.md index 4a56c810bd..dd00572c65 100644 --- a/docs-site/src/content/docs/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/guides/sub-agent-surface.md @@ -63,11 +63,19 @@ tagged item in their trusted replay prefix. Other generated guidance is reused w developer item exists in that prefix. When guidance changes, leading tool protocol stays first and the replacement is inserted before current conversational input. -These are instructions to the main agent, not a proxy-side spawn router. On v2, a full-history fork -inherits the parent model and rejects model or effort overrides. Guidance therefore tells Codex to -use `fork_turns: "none"` (or a positive partial turn count such as `"3"`) when passing `model` or +These are instructions to the main agent, not a proxy-side spawn router. Codex's own v2 usage hint +tells the agent that full-history forks (`fork_turns` omitted or `"all"`) inherit the parent model +and reasoning effort and should not carry overrides. Guidance therefore tells Codex to use +`fork_turns: "none"` (or a positive partial turn count such as `"3"`) when passing `model` or `reasoning_effort`, and to make the task message self-contained. +Treat that as a prompt-level convention rather than a hard rejection. Codex once rejected +`agent_type`, `model`, and `reasoning_effort` on a full-history v2 fork +([openai/codex#20077](https://github.com/openai/codex/issues/20077)), but +[#37252](https://github.com/openai/codex/pull/37252) removed that check, and the current v2 spawn +handler applies model overrides regardless of fork mode. Following the convention is still the +reliable path, because the agent is prompted to avoid overrides on a full fork. + Custom `injectionPrompt` text can use all four placeholders: | Placeholder | Replaced with | @@ -219,8 +227,16 @@ main agent still decides whether to delegate. ### Why did my v2 child use the parent model? -A full-history v2 fork inherits the parent model. Use a spawn that sets `fork_turns` to `"none"` or -a positive partial count before passing a model or effort override. +Spawned agents inherit the parent model whenever `model` is omitted, and that is the default for +every fork mode — not something a full-history fork causes on its own. Codex's built-in v2 usage +hint also tells the agent not to carry overrides on a full-history fork, so it may leave `model` +unset by design. Pass an explicit `model` on a spawn that sets `fork_turns` to `"none"` or a +positive partial count. + +If `model` is missing from the tool schema altogether, the cause is exposure rather than fork mode: +check Codex's `features.multi_agent_v2.expose_spawn_agent_model_overrides` (default on), and see +[openai/codex#31814](https://github.com/openai/codex/issues/31814) for ChatGPT-native parents whose +collaboration schema is fixed by the backend. ### Why is a configured model missing from the v2 roster? diff --git a/docs-site/src/content/docs/ja/guides/sub-agent-surface.md b/docs-site/src/content/docs/ja/guides/sub-agent-surface.md index 7a9ac7aa12..8bb211d909 100644 --- a/docs-site/src/content/docs/ja/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/ja/guides/sub-agent-surface.md @@ -43,7 +43,9 @@ v2 ロスターの場合、適格性には 3 つの状態があります。`"v2" `multiAgentGuidanceEnabled` はデフォルトでオンになっており、両方のサーフェスで opencodex が作成したガイダンスのマスター スイッチです。これをオフにすると、v2 指定ブロックと v1 プロアクティブ テキストの両方が抑制されます。 -これらはメイン エージェントに対する指示であり、プロキシ側のスポーン ルーターに対する指示ではありません。 v2 では、全履歴フォークは親モデルを継承し、モデルまたはエフォートのオーバーライドを拒否します。したがって、ガイダンスでは、`model` または `reasoning_effort` を渡すときに `fork_turns: "none"` (または `"3"` などの正の部分ターン カウント) を使用し、タスク メッセージを自己完結型にするように Codex に指示します。 +これらはメイン エージェントに対する指示であり、プロキシ側のスポーン ルーターに対する指示ではありません。Codex 自身の v2 usage hint は、全履歴フォーク (`fork_turns` の省略または `"all"`) が親モデルと推論エフォートを継承するため、オーバーライドを一緒に渡さないようエージェントに指示します。したがって、ガイダンスでは、`model` または `reasoning_effort` を渡すときに `fork_turns: "none"` (または `"3"` などの正の部分ターン カウント) を使用し、タスク メッセージを自己完結型にするように Codex に指示します。 + +これはランタイムが強制する拒否ではなく、プロンプト レベルの規約として扱ってください。かつて Codex は全履歴 v2 フォークで `agent_type`、`model`、`reasoning_effort` を実際に拒否していましたが ([openai/codex#20077](https://github.com/openai/codex/issues/20077))、[#37252](https://github.com/openai/codex/pull/37252) でそのチェックが削除され、現在の v2 spawn ハンドラーはフォーク モードに関係なくモデル オーバーライドを適用します。それでもこの規約に従うのが確実です。エージェントは全履歴フォークでオーバーライドを避けるようプロンプトで指示されているためです。 カスタム `injectionPrompt` テキストでは、次の 4 つのプレースホルダーすべてを使用できます。 @@ -155,7 +157,9 @@ curl -X PUT http://localhost:10100/api/injection-model \ ### v2 の子が親モデルを使用したのはなぜですか? -フルヒストリーの v2 フォークは親モデルを継承します。モデルまたはエフォートオーバーライドを渡す前に、`fork_turns` を `"none"` に設定するスポーン、または正の部分カウントを使用します。 +`model` を省略するとサブエージェントは親モデルを継承します。これはフォーク モードに関係のない既定の動作であり、全履歴フォークが単独で引き起こすものではありません。さらに Codex 内蔵の v2 usage hint は全履歴フォークでオーバーライドを渡さないよう指示するため、エージェントが意図的に `model` を未設定のままにする場合があります。`fork_turns` を `"none"` または正の部分カウントに設定したスポーンで `model` を明示的に渡してください。 + +`model` フィールドがツール スキーマに存在しない場合、原因はフォーク モードではなく公開設定です。Codex の `features.multi_agent_v2.expose_spawn_agent_model_overrides` (既定は有効) を確認し、バックエンドが collaboration スキーマを固定する ChatGPT ネイティブ親については [openai/codex#31814](https://github.com/openai/codex/issues/31814) を参照してください。 ### 設定したモデルが v2 ロスターにないのはなぜですか? diff --git a/docs-site/src/content/docs/ko/guides/sub-agent-surface.md b/docs-site/src/content/docs/ko/guides/sub-agent-surface.md index 6b8f0064a0..b46dc4c2f2 100644 --- a/docs-site/src/content/docs/ko/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/ko/guides/sub-agent-surface.md @@ -43,7 +43,9 @@ v2 로스터의 경우 적합성은 세 가지 상태로 나뉩니다. `"v2"`로 `multiAgentGuidanceEnabled`는 기본적으로 켜져 있으며, opencodex가 작성한 가이드에 대한 전역 스위치입니다. 이 값을 끄면 v2 지정 블록과 v1의 능동적 안내 문구가 모두 사라집니다. -이 값들은 메인 에이전트에 대한 지시이며, 프록시 쪽 스폰 라우터가 아닙니다. v2에서는 전체 히스토리 fork가 부모 모델을 상속하고 모델 또는 추론 강도 오버라이드를 거부합니다. 그래서 가이드는 `model` 또는 `reasoning_effort`를 넘길 때 `fork_turns: "none"`(또는 `"3"` 같은 양수 부분 turn 수)을 사용하고, 작업 메시지를 자체 완결형으로 만들라고 안내합니다. +이 값들은 메인 에이전트에 대한 지시이며, 프록시 쪽 스폰 라우터가 아닙니다. Codex 자체의 v2 usage hint는 전체 히스토리 fork(`fork_turns` 생략 또는 `"all"`)가 부모 모델과 추론 강도를 상속하므로 오버라이드를 함께 넘기지 말라고 에이전트에 지시합니다. 그래서 가이드는 `model` 또는 `reasoning_effort`를 넘길 때 `fork_turns: "none"`(또는 `"3"` 같은 양수 부분 turn 수)을 사용하고, 작업 메시지를 자체 완결형으로 만들라고 안내합니다. + +이는 런타임이 강제하는 거부가 아니라 프롬프트 수준의 관례입니다. 과거 Codex는 전체 히스토리 v2 fork에서 `agent_type`, `model`, `reasoning_effort`를 실제로 거부했지만([openai/codex#20077](https://github.com/openai/codex/issues/20077)), [#37252](https://github.com/openai/codex/pull/37252)에서 그 검사가 제거되어 현재 v2 spawn 핸들러는 fork 모드와 무관하게 모델 오버라이드를 적용합니다. 그래도 이 관례를 따르는 편이 안전한데, 에이전트가 전체 fork에서 오버라이드를 피하도록 프롬프트로 지시받기 때문입니다. 사용자 정의 `injectionPrompt`에는 다음 네 개의 플레이스홀더를 모두 쓸 수 있습니다. @@ -153,7 +155,9 @@ curl -X PUT http://localhost:10100/api/injection-model \ ### v2 자식이 왜 부모 모델을 썼나요? -전체 히스토리 v2 fork는 부모 모델을 상속합니다. `fork_turns`를 `"none"` 또는 양수의 부분 turn 수로 설정한 spawn을 사용한 뒤 모델이나 추론 강도 오버라이드를 넘기세요. +`model`을 생략하면 서브에이전트는 부모 모델을 상속하며, 이는 fork 모드와 무관한 기본 동작입니다. 전체 히스토리 fork 자체가 원인이 아닙니다. 또한 Codex 내장 v2 usage hint가 전체 히스토리 fork에서는 오버라이드를 넘기지 말라고 지시하므로, 에이전트가 의도적으로 `model`을 비워 둘 수 있습니다. `fork_turns`를 `"none"` 또는 양수의 부분 turn 수로 설정한 spawn에 `model`을 명시해서 넘기세요. + +`model` 필드가 도구 스키마에 아예 보이지 않는다면 원인은 fork 모드가 아니라 노출 설정입니다. Codex의 `features.multi_agent_v2.expose_spawn_agent_model_overrides`(기본 켜짐)를 확인하고, 백엔드가 collaboration 스키마를 고정하는 ChatGPT 네이티브 부모의 경우 [openai/codex#31814](https://github.com/openai/codex/issues/31814)를 참고하세요. ### 왜 설정한 모델이 v2 로스터에서 빠지나요? diff --git a/docs-site/src/content/docs/ru/guides/sub-agent-surface.md b/docs-site/src/content/docs/ru/guides/sub-agent-surface.md index 8b6e7d504e..98c881f2f9 100644 --- a/docs-site/src/content/docs/ru/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/ru/guides/sub-agent-surface.md @@ -58,10 +58,18 @@ TUI-сессии. guidance-сообщений, которые opencodex пишет сам, на обеих поверхностях. Если выключить его, подавляются и блок v2 designation, и proactive text для v1. -Это инструкции для основного агента, а не proxy-side spawn router. На v2 полный форк истории -унаследует модель родителя и отвергнет model- или effort-override. Поэтому guidance просит Codex -использовать `fork_turns: "none"` (или положительное частичное число ходов, например `"3"`) при -передаче `model` или `reasoning_effort`, а сообщение задачи делать самодостаточным. +Это инструкции для основного агента, а не proxy-side spawn router. Собственная v2 usage hint Codex +сообщает агенту, что полный форк истории (`fork_turns` опущен или `"all"`) наследует модель и +reasoning effort родителя, поэтому передавать override вместе с ним не следует. Поэтому guidance +просит Codex использовать `fork_turns: "none"` (или положительное частичное число ходов, например +`"3"`) при передаче `model` или `reasoning_effort`, а сообщение задачи делать самодостаточным. + +Считайте это соглашением на уровне промпта, а не жёстким отказом во время выполнения. Раньше Codex +действительно отвергал `agent_type`, `model` и `reasoning_effort` на полном форке истории v2 +([openai/codex#20077](https://github.com/openai/codex/issues/20077)), но +[#37252](https://github.com/openai/codex/pull/37252) удалил эту проверку, и текущий обработчик v2 +spawn применяет override модели независимо от режима форка. Следовать соглашению всё же надёжнее: +агенту предписано избегать override на полном форке. Пользовательский `injectionPrompt` может использовать все четыре placeholder'а: @@ -207,9 +215,16 @@ curl -X PUT http://localhost:10100/api/injection-model \ ### Почему мой child v2 использовал модель родителя? -Полный форк истории на v2 наследует модель родителя. Используйте spawn, который задаёт -`fork_turns` как `"none"` или положительное частичное число ходов, прежде чем передавать -model- или effort-override. +Порождённые агенты наследуют модель родителя всякий раз, когда `model` опущен, и это поведение по +умолчанию для любого режима форка, а не следствие полного форка истории. Кроме того, встроенная v2 +usage hint Codex предписывает агенту не передавать override на полном форке истории, поэтому он +может намеренно оставить `model` незаданным. Передайте явный `model` в spawn, который задаёт +`fork_turns` как `"none"` или положительное частичное число ходов. + +Если поля `model` вообще нет в схеме инструмента, причина в его публикации, а не в режиме форка: +проверьте `features.multi_agent_v2.expose_spawn_agent_model_overrides` в Codex (по умолчанию +включено), а для ChatGPT-native родителей, чья схема collaboration фиксируется бэкендом, см. +[openai/codex#31814](https://github.com/openai/codex/issues/31814). ### Почему настроенная модель не попала в ростер v2? diff --git a/docs-site/src/content/docs/tr/guides/sub-agent-surface.md b/docs-site/src/content/docs/tr/guides/sub-agent-surface.md index 04e6859e15..df232b4a46 100644 --- a/docs-site/src/content/docs/tr/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/tr/guides/sub-agent-surface.md @@ -72,11 +72,21 @@ Rehberlik değiştiğinde öndeki araç protokolü ilk sırada kalır ve değiş geçerli konuşma girdisinden önce eklenir. Bunlar ana ajana verilen talimatlardır, proxy tarafında bir spawn yönlendiricisi -değildir. v2'de tam geçmişli bir çatal üst modeli devralır ve model veya çaba -geçersiz kılmalarını reddeder. Bu nedenle rehberlik, `model` veya -`reasoning_effort` iletirken Codex'e `fork_turns: "none"` (veya `"3"` gibi -pozitif bir kısmi tur sayısı) kullanmasını ve görev mesajını bağımsız hale -getirmesini söyler. +değildir. Codex'in kendi v2 kullanım ipucu, tam geçmişli çatalların +(`fork_turns` atlanmış ya da `"all"`) üst modeli ve akıl yürütme çabasını +devraldığını, bu nedenle geçersiz kılma taşımaması gerektiğini ajana söyler. Bu +nedenle rehberlik, `model` veya `reasoning_effort` iletirken Codex'e +`fork_turns: "none"` (veya `"3"` gibi pozitif bir kısmi tur sayısı) +kullanmasını ve görev mesajını bağımsız hale getirmesini söyler. + +Bunu çalışma zamanında sert bir ret değil, istem düzeyinde bir uzlaşım olarak +değerlendirin. Codex bir zamanlar tam geçmişli v2 çatallarında `agent_type`, +`model` ve `reasoning_effort` değerlerini gerçekten reddediyordu +([openai/codex#20077](https://github.com/openai/codex/issues/20077)), ancak +[#37252](https://github.com/openai/codex/pull/37252) bu denetimi kaldırdı ve +geçerli v2 spawn işleyicisi çatal moduna bakmaksızın model geçersiz kılmalarını +uygular. Yine de bu uzlaşıma uymak güvenilir yoldur; çünkü ajana tam çatalda +geçersiz kılmalardan kaçınması istem yoluyla söylenmiştir. Özel `injectionPrompt` metni dört yer tutucunun tümünü kullanabilir: @@ -252,9 +262,19 @@ yetkilendirmeyeceğine kendisi karar verir. ### v2 çocuğum neden üst modeli kullandı? -Tam geçmişli bir v2 çatalı üst modeli devralır. Bir model veya çaba geçersiz -kılmasını iletmeden önce `fork_turns` değerini `"none"` veya pozitif bir kısmi -sayıya ayarlayan bir spawn kullanın. +`model` atlandığı her durumda üretilen ajanlar üst modeli devralır; bu, tüm +çatal modları için varsayılan davranıştır ve tek başına tam geçmişli çatalın yol +açtığı bir sonuç değildir. Ayrıca Codex'in yerleşik v2 kullanım ipucu, tam +geçmişli çatalda geçersiz kılma taşınmamasını söyler; bu nedenle ajan `model` +alanını bilinçli olarak boş bırakabilir. `fork_turns` değerini `"none"` veya +pozitif bir kısmi sayıya ayarlayan bir spawn üzerinde açık bir `model` iletin. + +`model` alanı araç şemasında hiç görünmüyorsa neden çatal modu değil, alanın +açığa çıkarılmasıdır: Codex'te +`features.multi_agent_v2.expose_spawn_agent_model_overrides` ayarını (varsayılan +açık) denetleyin ve collaboration şeması arka uç tarafından sabitlenen +ChatGPT-yerel üst ajanlar için +[openai/codex#31814](https://github.com/openai/codex/issues/31814) sayfasına bakın. ### Yapılandırılmış bir model neden v2 kadrosunda eksik? @@ -315,5 +335,3 @@ sabitler. Model bağlam sınırı alt ajan modundan bağımsızdır. Modeller sayfasında yapılandırın; yerel OpenAI modelleri gerçek bağlam pencerelerini korur. - - diff --git a/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md b/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md index 3882d15c9a..e26d4ec8ef 100644 --- a/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/zh-cn/guides/sub-agent-surface.md @@ -43,7 +43,9 @@ Dashboard 上的 **Sub-agent delegation** 控件管理三个相关设置： `multiAgentGuidanceEnabled` 默认开启，是 opencodex 编写的指引在两个界面上的总开关。关闭它会同时抑制 v2 的 designation block 和 v1 的 proactive 文本。 -这些是发给主代理的指令，不是 proxy 侧的 spawn 路由器。对于 v2，全历史 fork 会继承父模型，并拒绝模型或 effort 覆盖。因此，指引会要求 Codex 在传递 `model` 或 `reasoning_effort` 时使用 `fork_turns: "none"`（或者像 `"3"` 这样正向的部分 turn 数），并让任务消息保持自包含。 +这些是发给主代理的指令，不是 proxy 侧的 spawn 路由器。Codex 自身的 v2 usage hint 会告诉代理：全历史 fork（省略 `fork_turns` 或设为 `"all"`）继承父模型和推理 effort，因此不应同时传入覆盖。所以指引会要求 Codex 在传递 `model` 或 `reasoning_effort` 时使用 `fork_turns: "none"`（或者像 `"3"` 这样正向的部分 turn 数），并让任务消息保持自包含。 + +请把它当作提示词层面的约定，而不是运行时的硬性拒绝。Codex 过去确实会在全历史 v2 fork 上拒绝 `agent_type`、`model` 和 `reasoning_effort`（[openai/codex#20077](https://github.com/openai/codex/issues/20077)），但 [#37252](https://github.com/openai/codex/pull/37252) 移除了该检查，当前的 v2 spawn 处理器无论 fork 模式如何都会应用模型覆盖。不过遵循该约定仍然更可靠，因为代理已被提示在全量 fork 上避免使用覆盖。 自定义 `injectionPrompt` 文本可以使用全部四个占位符： @@ -153,7 +155,9 @@ curl -X PUT http://localhost:10100/api/injection-model \ ### 为什么我的 v2 子级使用了父模型？ -全历史 v2 fork 会继承父模型。在传入模型或 effort 覆盖之前，请使用把 `fork_turns` 设为 `"none"` 或正向部分 turn 数的 spawn。 +只要省略 `model`，子代理就会继承父模型；这是所有 fork 模式下的默认行为，并非全历史 fork 单独造成的。此外，Codex 内置的 v2 usage hint 也会要求代理不要在全历史 fork 上传入覆盖，因此代理可能有意不设置 `model`。请在把 `fork_turns` 设为 `"none"` 或正向部分 turn 数的 spawn 上显式传入 `model`。 + +如果工具 schema 中根本没有 `model` 字段，原因是暴露设置而非 fork 模式：请检查 Codex 的 `features.multi_agent_v2.expose_spawn_agent_model_overrides`（默认开启）；对于 collaboration schema 由后端固定的 ChatGPT 原生父代理，参见 [openai/codex#31814](https://github.com/openai/codex/issues/31814)。 ### 为什么配置的模型没有出现在 v2 roster 中？ diff --git a/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md index 7cdb8fb49d..6bb5cecf23 100644 --- a/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md +++ b/docs-site/src/content/docs/zh-tw/guides/sub-agent-surface.md @@ -6,7 +6,7 @@ description: 全域控制 Codex 在所有模型上生成和管理子代理的方 opencodex 允許你為目錄中的所有模型選擇多代理協作介面。儀表板和 Models 頁面中的 **Sub-agent** 開關會全域控制這一設定。 :::note -在 v2 介面（`multi_agent_v2`）上，子代理**預設**繼承父會話的模型：`fork_turns` 預設為 `all`，而全量歷史 fork 會拒絕覆蓋。自 v2.7.2 起，opencodex 注入的指引會教模型如何打破繼承 —— 將 `fork_turns` 設為 `"none"`（或如 `"3"` 的部分 fork）的 `spawn_agent` 呼叫可以傳入 `model` / `reasoning_effort` 引數；即使公開的工具 schema 中看不到這些引數，Codex 執行環境也會解析並應用。已知傳輸限制：當**原生**父代理 spawn 一個路由到**非原生** provider 的子代理時，Codex 用戶端可能只以後端加密的 `encrypted_content` 傳送 `NEW_TASK` 載荷（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。opencodex 不會把這種無法讀取的任務轉發給外部 provider：直接路由會回傳 HTTP 400 和錯誤碼 `unreadable_encrypted_agent_task`；組合路由則會跳過無法解密的目標，並在存在可用目標時選擇規範的原生 ChatGPT 目標。恢復方法：異構 provider 委派改用 v1、選擇原生 ChatGPT 子代理，或將任務重新作為明文 v2 `agent_message` 內容傳送。另有預設停用的實驗性 `agentTaskRecovery`；它會增加 ChatGPT 配額用量與延遲，且依賴非公開後端行為。 +在 v2 介面（`multi_agent_v2`）上，子代理**預設**繼承父會話的模型：`fork_turns` 預設為 `all`，且 Codex 的 v2 使用提示會要求不要在全量歷史 fork 上傳入覆蓋。自 v2.7.2 起，opencodex 注入的指引會教模型如何打破繼承 —— 將 `fork_turns` 設為 `"none"`（或如 `"3"` 的部分 fork）的 `spawn_agent` 呼叫可以傳入 `model` / `reasoning_effort` 引數；即使公開的工具 schema 中看不到這些引數，Codex 執行環境也會解析並應用。已知傳輸限制：當**原生**父代理 spawn 一個路由到**非原生** provider 的子代理時，Codex 用戶端可能只以後端加密的 `encrypted_content` 傳送 `NEW_TASK` 載荷（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。opencodex 不會把這種無法讀取的任務轉發給外部 provider：直接路由會回傳 HTTP 400 和錯誤碼 `unreadable_encrypted_agent_task`；組合路由則會跳過無法解密的目標，並在存在可用目標時選擇規範的原生 ChatGPT 目標。恢復方法：異構 provider 委派改用 v1、選擇原生 ChatGPT 子代理，或將任務重新作為明文 v2 `agent_message` 內容傳送。另有預設停用的實驗性 `agentTaskRecovery`；它會增加 ChatGPT 配額用量與延遲，且依賴非公開後端行為。 ::: ## What sub-agents are @@ -21,7 +21,7 @@ opencodex 允許你為目錄中的所有模型選擇多代理協作介面。儀 | --- | --- | --- | | **v1** | `multi_agent_v1` | 使用經典的名稱空間代理工具，以及 `send_input` / `close_agent` / `resume_agent`。`spawn_agent` 的模型覆蓋可以在其他模型上生成子代理。 | | **base**（預設） | 上游固定值 | 恢復上游模型的固定值：gpt-5.6-sol 和 gpt-5.6-terra 使用 v2，gpt-5.6-luna 使用 v1；未固定的模型遵循 Codex 的 `multi_agent_v2` 功能開關。生成行為取決於該模型最終使用的介面。 | -| **v2** | `multi_agent_v2` | 使用扁平的 `spawn_agent` 工具、併發會話，以及 `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`。全量歷史 fork 時子代理繼承父模型；`fork_turns: "none"`（或部分 fork）時接受 `model` / `reasoning_effort` 覆蓋。如果原生→路由子代理只收到後端加密的任務內容，外部路由會回傳 `unreadable_encrypted_agent_task`；混合組合會優先選擇可解密的原生目標（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。 | +| **v2** | `multi_agent_v2` | 使用扁平的 `spawn_agent` 工具、併發會話，以及 `send_message` / `followup_task` / `wait_agent` / `interrupt_agent`。省略 `model` 時子代理繼承父模型；提示慣例是在傳入 `model` / `reasoning_effort` 覆蓋時使用 `fork_turns: "none"`（或部分 fork）。如果原生→路由子代理只收到後端加密的任務內容，外部路由會回傳 `unreadable_encrypted_agent_task`；混合組合會優先選擇可解密的原生目標（[#92](https://github.com/lidge-jun/opencodex/issues/92)）。 | ## 運作原理 @@ -44,9 +44,15 @@ opencodex 允許你為目錄中的所有模型選擇多代理協作介面。儀 `multiAgentGuidanceEnabled` 預設開啟，是 opencodex 撰寫的指引在兩個介面上的主開關。關閉它會同時 抑制 v2 指定區塊與 v1 主動文字。 -這些是給主代理的指示，不是 proxy 端的 spawn 路由器。在 v2 上，全量歷史 fork 會繼承父模型並拒絕 -模型或 effort 覆蓋。因此指引會告訴 Codex 在傳遞 `model` 或 `reasoning_effort` 時使用 -`fork_turns: "none"`（或正數的部分回合數，例如 `"3"`），並讓任務訊息自足。 +這些是給主代理的指示，不是 proxy 端的 spawn 路由器。Codex 自身的 v2 usage hint 會告訴代理：全量歷史 +fork（省略 `fork_turns` 或設為 `"all"`）繼承父模型與推理 effort，因此不應同時傳入覆蓋。所以指引會告訴 +Codex 在傳遞 `model` 或 `reasoning_effort` 時使用 `fork_turns: "none"`（或正數的部分回合數，例如 +`"3"`），並讓任務訊息自足。 + +請把它視為提示詞層級的慣例，而非執行期的硬性拒絕。Codex 過去確實會在全量歷史 v2 fork 上拒絕 +`agent_type`、`model` 與 `reasoning_effort`（[openai/codex#20077](https://github.com/openai/codex/issues/20077)）， +但 [#37252](https://github.com/openai/codex/pull/37252) 移除了該檢查，目前的 v2 spawn 處理器無論 fork +模式為何都會套用模型覆蓋。不過遵循該慣例仍然較可靠，因為代理已被提示在全量 fork 上避免使用覆蓋。 自訂 `injectionPrompt` 文字可以使用全部四個佔位符： @@ -174,8 +180,13 @@ curl -X PUT http://localhost:10100/api/injection-model \ ### 為什麼我的 v2 子代理使用了父模型？ -全量歷史 v2 fork 會繼承父模型。請在傳遞模型或 effort 覆蓋之前，使用把 `fork_turns` 設為 `"none"` -或正數部分計數的 spawn。 +只要省略 `model`，子代理就會繼承父模型；這是所有 fork 模式下的預設行為，並非全量歷史 fork 單獨造成 +的。此外，Codex 內建的 v2 usage hint 也會要求代理不要在全量歷史 fork 上傳入覆蓋，因此代理可能刻意不 +設定 `model`。請在把 `fork_turns` 設為 `"none"` 或正數部分計數的 spawn 上明確傳入 `model`。 + +如果工具 schema 中根本沒有 `model` 欄位，原因是公開設定而非 fork 模式：請檢查 Codex 的 +`features.multi_agent_v2.expose_spawn_agent_model_overrides`（預設開啟）；至於 collaboration schema 由 +後端固定的 ChatGPT 原生父代理，請參見 [openai/codex#31814](https://github.com/openai/codex/issues/31814)。 ### 為什麼設定的模型沒有出現在 v2 名冊中？