From 5b1d6a942c12f3bab9c96b7a768db9c9a3cc7ddb Mon Sep 17 00:00:00 2001 From: jun Date: Wed, 26 Aug 2026 21:27:42 +0900 Subject: [PATCH 1/2] docs(codex): document the prompt-layer panel in eight locales New guide plus its sidebar entry. devlog 070 asked for English and four locales because astro.config.mjs declared four when it was written; the site now carries seven, so all seven ship rather than leaving three in a missing-translation state. --- .../080_wp8_stack_publication.md | 181 ++++++++++++++++++ docs-site/astro.config.mjs | 1 + .../content/docs/fr/guides/codex-prompt.md | 135 +++++++++++++ .../src/content/docs/guides/codex-prompt.md | 136 +++++++++++++ .../content/docs/ja/guides/codex-prompt.md | 135 +++++++++++++ .../content/docs/ko/guides/codex-prompt.md | 134 +++++++++++++ .../content/docs/ru/guides/codex-prompt.md | 134 +++++++++++++ .../content/docs/tr/guides/codex-prompt.md | 142 ++++++++++++++ .../content/docs/zh-cn/guides/codex-prompt.md | 122 ++++++++++++ .../content/docs/zh-tw/guides/codex-prompt.md | 122 ++++++++++++ 10 files changed, 1242 insertions(+) create mode 100644 devlog/_plan/260802_codex_set_prompt_composer/080_wp8_stack_publication.md create mode 100644 docs-site/src/content/docs/fr/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/ja/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/ko/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/ru/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/tr/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/zh-cn/guides/codex-prompt.md create mode 100644 docs-site/src/content/docs/zh-tw/guides/codex-prompt.md diff --git a/devlog/_plan/260802_codex_set_prompt_composer/080_wp8_stack_publication.md b/devlog/_plan/260802_codex_set_prompt_composer/080_wp8_stack_publication.md new file mode 100644 index 00000000000..8657d22951e --- /dev/null +++ b/devlog/_plan/260802_codex_set_prompt_composer/080_wp8_stack_publication.md @@ -0,0 +1,181 @@ +# 080 — WP8: publish the unit as a stacked pull-request chain + +Plan phase for the final work-phase of the unit. WP7's artifacts exist but are +uncommitted; nothing has ever been pushed. This document is the diff-level map +for turning 24 local commits into a reviewable remote stack. + +## State this plan starts from (measured, not remembered) + +``` +git rev-parse --abbrev-ref HEAD -> dev +git rev-list --count origin/dev..HEAD -> 0 (dev checkout carries no commits) +git rev-list --count HEAD..origin/dev -> 3 (local dev is behind) +codex/codex-set-prompt-composer -> 27b62a37f, 24 commits, NEVER pushed +merge-base(origin/dev, composer) -> 779b6090c (3 behind origin/dev 37e5dd5ec) +git status --short -> M docs-site/astro.config.mjs + 8 untracked guides +``` + +The consequence worth stating plainly: **there is no stack on the remote and +never was.** Earlier work-phases closed against local commits only. WP7's docs +were authored in the `dev` checkout, so they are not on the composer branch +either — `grep -c 'codexSet\.' gui/src/i18n/en.ts` returns 0 at this HEAD +because the GUI work lives on the other branch. + +## Scope boundary + +IN + +- Rebase the 24 composer commits onto `origin/dev` (37e5dd5ec). +- Commit WP7's docs (English guide + 7 locale copies + sidebar entry). +- Slice the chain into 5 dependency-ordered branches, push each, open 5 PRs. +- Add the PR screenshots the repository gate requires for GUI layers. +- Verify each layer's own tests at its own tip. + +OUT + +- Base-instruction replacement flow (deferred, flagged; needs its own unit). +- `docs-site/src/content/docs/reference/configuration/` toggle-key reference: + the five keys have no home there today (only `agents.md`, `providers.md`, + `routing.md`, `server.md` exist) and inventing one is a separate decision. +- Merging anything. Stacks land bottom-up by the maintainer. +- `git reset --hard`, force-push to `dev`, or any promotion to `main`. + +## Layer map (DEV-STACK-01: dependency order, never effort) + +Five layers, not seven. WP5/WP6 collapse into one authoring layer and +WP6b/WP6c into one real-text layer, because neither half is independently +mergeable: WP6's preset picker writes through WP5's custom-layer store, and +WP6c renumbers the stack WP6b introduced. + +| # | Branch | Commits | Thesis | GUI? | +|---|--------|---------|--------|------| +| 1 | `codex/prompt-layers-route` | 4b7bfdfce..ec1ac0a23 (3) | Serve prompt-layer state over `/api/codex-prompt` | no | +| 2 | `codex/prompt-layers-shell` | 04e3e7b15..a600254b1 (6) | Codex Auth becomes Codex Set; read the taxonomy | yes | +| 3 | `codex/prompt-layers-authoring` | 9c4eebb51..38e629401 (8) | Custom layers, drift repair, presets | yes | +| 4 | `codex/prompt-layers-realtext` | 4c3831d6e..27b62a37f (7) | Show the text Codex really sends; ordered stack | yes | +| 5 | `codex/prompt-layers-docs` | 1 new | Guide + 7 locales + sidebar | no | + +Base refs: L1 -> `dev`; L2 -> L1; L3 -> L2; L4 -> L3; L5 -> L4. + +Each layer's independent thesis, stated so a reviewer can check it: + +1. **L1** adds one route module and its tests. The GUI never calls it yet, so + merging L1 alone changes no user-visible behavior — it is a served endpoint + with route tests. Verifiable alone. +2. **L2** renames the page and renders all fifteen layers read-only. Depends on + L1 for its data; nothing above it is needed for it to be correct. +3. **L3** adds writes: custom layers, the linter, drift repair, presets. +4. **L4** replaces "Codex does not expose this" with the real probed text and + turns the flat list into a numbered assembly stack. +5. **L5** is documentation only, and sits on top because it documents L4's final + vocabulary (the numbered stack, the four absent-text reasons). + +## Execution steps + +### Step 1 — rebase onto current dev + +``` +git rebase --update-refs origin/dev codex/codex-set-prompt-composer +``` + +The three incoming commits (`c0533ce31`, `6bce1d1c8`, `37e5dd5ec`) touch the +web-search body-bounding path and cannot conflict with this unit's files. If a +conflict appears anyway, stop and report rather than resolving blind. + +### Step 2 — cut the layer branches + +``` +git branch codex/prompt-layers-route +git branch codex/prompt-layers-shell +git branch codex/prompt-layers-authoring +git branch codex/prompt-layers-realtext +``` + +Branch creation, not reset: no commit is discarded and the composer branch stays +as the record of the original chain. + +### Step 3 — WP7's commit, on top of L4 + +Switching to `codex/prompt-layers-realtext` carries the modified +`astro.config.mjs` and the 8 untracked guides across, because no commit in the +chain touches those paths. Then commit them and cut `codex/prompt-layers-docs`. + +Note the count honestly: `070` specifies English + four locales (ja, ko, ru, +zh-cn) because that is what `astro.config.mjs` declared when it was written. +The site now carries seven (fr, tr, zh-tw added), and all seven are present, so +the delivered set is wider than the plan asked for. That is an amendment to +`070`, recorded here rather than left as a silent discrepancy. + +### Step 4 — screenshots for the GUI gate + +`.github/scripts/pr-quality.cjs` is the real gate, and reading it corrected an +error in this plan's first draft. The gate does **not** arm on a `gui` text cue +in the title or body — `hasGuiCue` exists but is not what fires the failure. +The armed condition is the changed-file list (`pr-quality.cjs:527-534`): + +``` +(guiPathsChanged(changedFilePaths) || filesTruncated) && + !hasScreenshotEvidence(body) && !hasGuiOverride(...) + -> failures.push({ code: "missing_ui_screenshot" }) +``` + +`guiPathsChanged` (`:176-180`) is true when any changed path equals `gui` or +starts with `gui/`. So the gate is decided by the diff, not by wording, and +**avoiding the word "gui" in a PR body cannot dodge it.** + +Two consequences the first draft got wrong: + +1. **The screenshot must be in each GUI PR's own body.** `hasScreenshotEvidence` + reads only `body` (`:276-284`). Committing an image file into L2 gives + L3/L4 the *file*, but their gate still inspects their own description. Each of + L2/L3/L4 needs its own rendered `![...](...)` — inheritance buys nothing here. +2. **Committed asset or upload both work**, since evidence is any inline markdown + image, a reference image with a definition, or an `` outside a fence + (`stripNonRenderedRegions`, `:243-255`, strips fences BEFORE comments). A + plain link to an image is explicitly not evidence. + +Chosen approach: commit three assets under `docs-site/public/pr-screenshots/` +in the **L2** range (repository precedent: `1073-context-window-controls.jpg`), +then reference the raw.githubusercontent URL from each of the three GUI PR +bodies. One upload path, three descriptions. Screenshots are re-taken from the +live dashboard rather than trusted from stale `/tmp` timestamps. + +L1 and L5 change no `gui/` path, so the gate never arms for them. + +### Stacked bases are supported by the gate (verified) + +`enforce-pr-target.yml:535-556` paginates open PRs and sets `stackedBase` when +this PR's base ref equals another **open** PR's head in the same repo. +`pr-quality.cjs:497` then skips `wrong_base`, and `:505-508` skips the ancestry +heuristic too. A closed or missing parent falls back to `wrong_base`, which is +the cascade risk if a lower layer merges before an upper one is retargeted. + +### Step 5 — push and open + +Push with `--no-verify` (user-approved this session), `-u` on each branch. +PRs via `gh pr create --base `, each body filling all three +template sections plus the DEV-STACK-03 stack map with "you are here". + +## Accept criteria + +| # | Criterion | Evidence | +|---|-----------|----------| +| 1 | Every layer contains only its own diff | `git log --oneline ..` shows exactly the mapped commits | +| 2 | Chain rebased onto current dev | `git merge-base --is-ancestor origin/dev codex/prompt-layers-docs` exits 0 | +| 3 | Each layer's tests pass at its own tip | narrow `bun test` on that layer's own files | +| 4 | 5 PRs open with correct base refs | `gh pr list --json baseRefName,headRefName` shows the chain | +| 5 | GUI layers pass the screenshot gate | each GUI PR body renders a markdown image outside a fence | +| 6 | No repository-wide local test run | narrow `bun test ` invocations only | + +## Loop spec + +- Archetype: spec-satisfaction repair. The verifier is `gh pr list` plus + per-layer `bun test`; done is defined by the six criteria above. +- Verifier: git ancestry checks, narrow bun test, `gh pr view` per layer. +- Stop condition: five PRs open, correct bases, per-layer tests green. +- Write scope: this repository's `origin` refs, 5 new remote branches, 5 PRs. + No writes to `dev` or `main`. +- Escalation: a rebase conflict, a rejected push, or a gate failure needing a + maintainer label stops the phase and reports rather than working around it. +- Terminal outcomes: DONE when all six criteria hold; BLOCKED if the remote + refuses a push or CI requires maintainer action. diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index fb790ff7437..f80cf2e90f9 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -90,6 +90,7 @@ export default defineConfig({ { label: "Model Routing", translations: { fr: "Routage des modèles", ko: "모델 라우팅", "zh-CN": "模型路由", "zh-TW": "模型路由", ru: "Маршрутизация моделей", ja: "モデルルーティング", tr: "Model Yönlendirme" }, slug: "guides/model-routing" }, { label: "Codex Integration", translations: { fr: "Intégration de Codex", ko: "Codex 통합", "zh-CN": "Codex 集成", "zh-TW": "Codex 整合", ru: "Интеграция с Codex", ja: "Codex 連携", tr: "Codex Entegrasyonu" }, slug: "guides/codex-integration" }, { label: "Codex App Model Picker", translations: { fr: "Sélecteur de modèles de Codex App", ko: "Codex App 모델 선택기", "zh-CN": "Codex App 模型选择器", "zh-TW": "Codex App 模型選擇器", ru: "Выбор модели в Codex App", ja: "Codex App モデルピッカー", tr: "Codex App Model Seçici" }, slug: "guides/codex-app-models" }, + { label: "Codex Prompt Layers", translations: { fr: "Couches d'invite Codex", ko: "Codex 프롬프트 레이어", "zh-CN": "Codex 提示词层", "zh-TW": "Codex 提示詞層", ru: "Слои промпта Codex", ja: "Codex プロンプトレイヤー", tr: "Codex İstem Katmanları" }, slug: "guides/codex-prompt" }, { label: "Model Ordering", translations: { fr: "Ordre des modèles", ko: "모델 정렬에 관하여", "zh-CN": "模型排序", "zh-TW": "模型排序", ru: "Сортировка моделей", ja: "モデルの並び順", tr: "Model Sıralaması" }, slug: "guides/model-ordering" }, { label: "Combos", translations: { fr: "Combinaisons", ko: "콤보", "zh-CN": "组合", "zh-TW": "組合", ru: "Комбо", ja: "コンボ", tr: "Kombolar" }, slug: "guides/combos" }, { label: "Claude Code", translations: { fr: "Claude Code", ko: "Claude Code", "zh-CN": "Claude Code", "zh-TW": "Claude Code", ru: "Claude Code", ja: "Claude Code", tr: "Claude Code" }, slug: "guides/claude-code" }, diff --git a/docs-site/src/content/docs/fr/guides/codex-prompt.md b/docs-site/src/content/docs/fr/guides/codex-prompt.md new file mode 100644 index 00000000000..8b77bc00ff1 --- /dev/null +++ b/docs-site/src/content/docs/fr/guides/codex-prompt.md @@ -0,0 +1,135 @@ +--- +title: Couches de prompt Codex +description: Découvrez ce que Codex envoie réellement, désactivez les éléments inutiles et ajoutez vos propres instructions sous forme de couches. +--- + +Codex assemble son prompt à partir de plusieurs couches : ses propres instructions de base, +la documentation de votre projet, le contexte des autorisations et de l’environnement, les +compétences installées, et davantage. **Codex Set → Prompt** affiche cette pile, indique le coût +de chaque couche et permet de désactiver celles dont vous ne voulez pas. + +## Ce que montre la liste + +Chaque ligne indique sa position dans l’ordre d’assemblage, la clé de configuration qui la régit +lorsqu’il en existe une, et la taille de ce qui a réellement été envoyé. + +La numérotation des positions comporte des intervalles. C’est intentionnel : les nombres sont les +véritables indices d’assemblage, et deux d’entre eux figurent plus bas sous **Avis de transition**. +Renuméroter chaque groupe à partir de un afficherait un ordre que Codex n’utilise pas. + +### Cinq types de couches + +| Type | Ce que vous pouvez faire | +|---|---| +| Modifiable ici | Un véritable commutateur. Écrit une clé dans `config.toml`. | +| Contrôlé par une fonctionnalité | Réelle, mais modifiée dans les paramètres des fonctionnalités plutôt que sur cette page. | +| Toujours actif | Aucun commutateur de désactivation n’existe dans Codex. | +| Lors d'un changement | Annonce une transition et n’apparaît donc que lorsqu’un élément change. | +| Couche d’extension | Ne peut pas être répertoriée. Codex ne l’expose pas. | + +Une couche sans commutateur de désactivation n’en affiche aucun, au lieu d’en montrer un qui serait +désactivé. Un contrôle grisé laisserait entendre que la possibilité existe, mais qu’elle est +temporairement indisponible, ce qui n’est pas le cas. + +## Lire une couche + +Cliquez sur le nom d’une couche pour afficher le texte qu’elle envoie. La boîte de dialogue le lit +depuis `codex debug prompt-input` : il s’agit donc du contenu réel, et non d’une description. + +Il arrive qu’il n’y ait rien à afficher. La boîte de dialogue précise alors la raison : + +- **Le fichier existe, mais il est vide.** Votre fichier `~/.codex/AGENTS.md` ne contient aucun + octet ; la couche n’a donc rien à envoyer. La boîte de dialogue indique le chemin. +- **Elle n’a rien envoyé pendant le tour que nous avons lu.** Les couches ne sont renvoyées que + lorsqu’elles changent ; une couche inchangée est donc absente d’un échantillon unique. +- **Elle transite hors de la liste lisible.** Le prompt de base est envoyé dans un autre champ et + ne peut pas être affiché ici. +- **Le prompt n’a pas pu être lu.** La sonde a échoué sur cette machine. + +La lecture est effectuée depuis votre répertoire Codex global (`~/.codex`), et non depuis le +répertoire dans lequel le tableau de bord se trouve être lancé. + +## Couches personnalisées + +**+ Add layer** ajoute vos propres instructions à la fin. Les couches personnalisées sont +assemblées dans `developer_instructions`, qui est additif : Codex conserve ses propres instructions +et y ajoute les vôtres. + +:::note +Il ne s’agit délibérément pas de `model_instructions_file`. Cette clé REMPLACE le prompt de base au +lieu de le compléter ; relier **+** à cette clé supprimerait donc les propres instructions de Codex +dès le premier enregistrement d’une couche. +::: + +Les couches personnalisées sont numérotées entre elles, car elles sont réunies dans une seule +section dans cet ordre ; elles ne s’intercalent pas avec les couches intégrées. + +Réorganisez-les avec les flèches de la ligne, ou avec `Alt` + `Up` / `Alt` + `Down` depuis +n’importe quel emplacement de la ligne. L’ordre correspond à l’ordre de composition. + +### Préréglages + +**+ Add layer** propose cinq points de départ : sortie concise, planification avant modification, +explication du raisonnement, tests en premier et réponses en coréen. Chacun ouvre l’éditeur ordinaire +avec un contenu prérempli et entièrement modifiable : un préréglage est un point de départ, et ce que +vous enregistrez devient une couche personnalisée ordinaire. + +Les préréglages sont notre propre texte, rédigé pour condenser une approche et non pour copier le +prompt de quelqu’un. Chacun indique sa source. + +### Passer d’une couche à l’autre pendant la modification + +L’éditeur dispose de commandes précédent/suivant et d’un indicateur de position. Les modifications +non enregistrées sont conservées pendant vos déplacements ; vous pouvez ainsi comparer deux couches +en cours de modification, puis revenir sans perdre ce que vous avez saisi. + +### Avertissements de compatibilité + +L’éditeur avertit lorsqu’une couche contient une instruction qui ne fonctionnera pas telle quelle : +revendiquer une autre identité, nommer un outil défini par le registre, utiliser des espaces réservés +de modèle que rien ne développe ou énoncer des informations sur l’environnement que Codex génère +ultérieurement. + +Ces avertissements ne bloquent jamais l’enregistrement. Si vous souhaitez remplacer le comportement +de Codex, vous le pouvez ; l’avertissement permet simplement d’en faire une décision plutôt qu’un accident. + +## Instructions écrites en dehors d’opencodex + +Si `developer_instructions` existe déjà et n’a pas été écrit par opencodex, le panneau ne le +remplacera pas. Il propose à la place d’importer le texte comme une couche : vous voyez d’abord la +valeur existante, et rien n’est écrit avant votre confirmation. + +## En cas de désynchronisation + +Si les couches enregistrées et la valeur de `config.toml` divergent, le panneau le signale et +propose **Repair** au lieu de corriger le problème silencieusement. Deux des méthodes de réparation +réécrivent votre texte et restent donc intentionnelles. Lorsqu’un fichier de couche a disparu, la +réparation crée une sauvegarde avant toute modification. + +## Quand les modifications prennent effet + +Les modifications s’appliquent aux nouvelles sessions. Une session déjà en cours conserve les +paramètres de prompt avec lesquels elle a démarré. + +## Ce que cette page lit, et ce qu’elle ne lit pas + +opencodex lit un seul fichier de configuration : votre `config.toml`. Codex résout ses paramètres à +partir de plusieurs couches ; une valeur affichée ici correspond donc à ce que dit VOTRE fichier, +et pas nécessairement à ce que Codex calcule finalement. + +## Les clés que cette page écrit + +Elles se trouvent dans le `config.toml` de Codex, pas dans la configuration propre à opencodex. + +| Clé | Par défaut | Couche | +|---|---|---| +| `include_permissions_instructions` | `true` | Autorisations | +| `include_collaboration_mode_instructions` | `true` | Mode collaboration | +| `include_environment_context` | `true` | Contexte d'environnement | +| `include_apps_instructions` | `true` | Applications | +| `skills.include_instructions` | `true` | Compétences | +| `developer_instructions` | non défini | Vos couches personnalisées, jointes dans l'ordre | + +L'écriture se fait ligne par ligne : vos commentaires et votre mise en forme sont conservés, et une clé qu'opencodex ne connaît pas est laissée telle quelle plutôt que supprimée. + +Une clé absente est lue comme sa valeur par défaut, et non comme `false`. Le panneau affiche la valeur réellement présente dans votre fichier et indique lorsqu'une clé n'est pas définie. diff --git a/docs-site/src/content/docs/guides/codex-prompt.md b/docs-site/src/content/docs/guides/codex-prompt.md new file mode 100644 index 00000000000..c9706260a8d --- /dev/null +++ b/docs-site/src/content/docs/guides/codex-prompt.md @@ -0,0 +1,136 @@ +--- +title: Codex Prompt Layers +description: Read what Codex actually sends, switch off the parts you do not need, and append your own instructions as layers. +--- + +Codex assembles its prompt from layers: its own base instructions, your project +docs, permission and environment context, the skills you have installed, and +more. **Codex Set → Prompt** shows that stack, tells you what each layer costs, +and lets you switch off the parts you do not want. + +## What the list shows + +Each row carries its position in the assembly order, the config key that governs +it when there is one, and the size of what it actually sent. + +The positions have gaps. That is deliberate: the numbers are the real assembly +indices, and two of them are listed further down under **Transition notices**. +Renumbering each group from one would show an order Codex does not use. + +### Five kinds of layer + +| Kind | What you can do | +|---|---| +| Switchable here | A real switch. Writes a key in `config.toml`. | +| Configured under `[features]` | Real, but changed from the feature settings rather than this page. | +| Always on | No off-switch anywhere in Codex. | +| Fires on change | Announces a transition, so it appears only when something changes. | +| Extension layers | Cannot be listed. Codex does not expose them. | + +A layer with no off-switch shows no switch at all rather than a disabled one. A +greyed control would suggest the capability exists and is temporarily +unavailable, which is not the case. + +## Reading a layer + +Click a layer name to see the text it sends. The dialog reads it from +`codex debug prompt-input`, so it is the real thing rather than a description. + +Sometimes there is nothing to show, and the dialog says which reason applies: + +- **The file exists but is empty.** Your `~/.codex/AGENTS.md` is zero bytes, so + the layer has nothing to send. The dialog names the path. +- **It sent nothing on the turn we read.** Layers are only re-sent when they + change, so an unchanged layer is absent from a single sample. +- **It travels outside the readable list.** The base prompt is sent through a + different field and cannot be printed here. +- **The prompt could not be read.** The probe failed on this machine. + +The reading is taken from your global Codex home (`~/.codex`), not from whatever +directory the dashboard happens to be running in. + +## Custom layers + +**+ Add layer** appends your own instructions. Custom layers compose into +`developer_instructions`, which is additive — Codex keeps its own instructions +and yours are added to them. + +:::note +This is deliberately not `model_instructions_file`. That key REPLACES the base +prompt rather than adding to it, so wiring **+** to it would delete Codex's own +instructions the first time you saved a layer. +::: + +Custom layers are numbered among themselves because they are joined into one +section in that order — they do not interleave with the built-in layers. + +Reorder with the arrows on the row, or with `Alt` + `Up` / `Alt` + `Down` from +anywhere in the row. Order is composition order. + +### Presets + +**+ Add layer** offers five starting points: concise output, plan before editing, +explain reasoning, test first, and Korean replies. Each opens the ordinary editor +pre-filled and fully editable — a preset is a starting point, and what you save is +an ordinary custom layer. + +The presets are our own text, written to distil an approach rather than to copy +anyone's prompt. Each names its source. + +### Moving between layers while editing + +The editor has prev/next controls and a position indicator. Unsaved edits are kept +while you move, so you can compare two layers mid-edit and come back without +losing what you typed. + +### Compatibility warnings + +The editor warns when a layer says something that will not work as written — +claiming a different identity, naming a tool the registry defines, using template +placeholders nothing expands, or stating environment facts Codex generates later. + +These are warnings and never block a save. If you mean to override Codex, you can; +the warning only makes it a decision rather than an accident. + +## Instructions written outside opencodex + +If `developer_instructions` already exists and opencodex did not write it, the +panel will not overwrite it. Instead it offers to import the text as a layer: +you see the existing value first, and nothing is written until you confirm. + +## When something is out of sync + +If the saved layers and the value in `config.toml` disagree, the panel says so and +offers **Repair** rather than fixing it silently. Two of the repair paths rewrite +text you wrote, so they stay deliberate. Where a layer file has gone missing, the +repair writes a backup before it touches anything. + +## When changes take effect + +Changes apply to newly started sessions. A session already running keeps the +prompt settings it started with. + +## What this page reads, and what it does not + +opencodex reads one configuration file — your `config.toml`. Codex resolves its +settings from several layers, so a value here is what YOUR file says, not +necessarily what Codex finally computes. + +## The keys this page writes + +These live in your Codex `config.toml`, not in opencodex's own configuration. + +| Key | Default | Layer | +|---|---|---| +| `include_permissions_instructions` | `true` | Permissions | +| `include_collaboration_mode_instructions` | `true` | Collaboration mode | +| `include_environment_context` | `true` | Environment context | +| `include_apps_instructions` | `true` | Apps | +| `skills.include_instructions` | `true` | Skills | +| `developer_instructions` | unset | Your custom layers, joined in order | + +Writes are line edits: your comments and formatting survive, and a key opencodex +does not recognise is left alone rather than removed. + +An absent key reads as its default rather than as `false`. The panel shows the +value your file actually holds, and says when a key is not set. diff --git a/docs-site/src/content/docs/ja/guides/codex-prompt.md b/docs-site/src/content/docs/ja/guides/codex-prompt.md new file mode 100644 index 00000000000..955b5f2c55e --- /dev/null +++ b/docs-site/src/content/docs/ja/guides/codex-prompt.md @@ -0,0 +1,135 @@ +--- +title: Codex のプロンプトレイヤー +description: Codex が実際に送信する内容を確認し、不要な部分をオフにして、独自の指示をレイヤーとして追加できます。 +--- + +Codex は、独自の基本指示、プロジェクトのドキュメント、権限と環境のコンテキスト、 +インストール済みのスキルなど、複数のレイヤーからプロンプトを組み立てます。 +**Codex Set → Prompt** では、この構成、各レイヤーが占めるサイズを確認し、不要な部分を +オフにできます。 + +## リストに表示される内容 + +各行には、組み立て順での位置、該当する場合はそのレイヤーを制御する設定キー、 +実際に送信された内容のサイズが表示されます。 + +位置番号が連続していないのは意図的です。この番号は実際の組み立てインデックスであり、 +そのうち 2 つは下の **遷移通知** に表示されます。グループごとに 1 から番号を振り直すと、 +Codex が実際には使用しない順序を示すことになります。 + +### 5 種類のレイヤー + +| 種類 | できること | +|---|---| +| ここで切り替え可能 | 実際のスイッチです。`config.toml` にキーを書き込みます。 | +| 機能フラグ制御 | 実在するレイヤーですが、このページではなく機能設定で変更します。 | +| 常に有効 | Codex のどこにもオフにするスイッチはありません。 | +| 変更時に送信 | 遷移を通知するため、何かが変わったときだけ表示されます。 | +| 拡張レイヤー | リストには表示できません。Codex が公開していません。 | + +オフにするスイッチがないレイヤーには、無効なスイッチではなく、スイッチ自体が +表示されません。グレー表示のコントロールでは、機能は存在するものの一時的に +利用できないように見えますが、実際にはその機能が存在しないためです。 + +## レイヤーを読み取る + +レイヤー名をクリックすると、送信されるテキストを確認できます。ダイアログは +`codex debug prompt-input` から内容を読み取るため、説明ではなく実際の送信内容です。 + +表示する内容がない場合もあり、ダイアログに該当する理由が表示されます。 + +- **ファイルは存在しますが空です。** `~/.codex/AGENTS.md` が 0 バイトのため、 + レイヤーには送信する内容がありません。ダイアログにパスが表示されます。 +- **読み取ったターンでは何も送信されませんでした。** レイヤーは変更されたときだけ + 再送信されるため、変更のないレイヤーは 1 回分のサンプルには含まれません。 +- **読み取り可能なリストの外で送信されます。** 基本プロンプトは別のフィールドで + 送信されるため、ここには表示できません。 +- **プロンプトを読み取れませんでした。** このマシンで確認処理が失敗しました。 + +内容は、ダッシュボードがたまたま実行されているディレクトリではなく、グローバルな +Codex ホーム（`~/.codex`）から読み取られます。 + +## カスタムレイヤー + +**+ Add layer** を押すと、独自の指示が追加されます。カスタムレイヤーは +`developer_instructions` に組み込まれます。このキーは追加方式なので、Codex 独自の +指示は維持され、ユーザーの指示が加わります。 + +:::note +意図的に `model_instructions_file` は使用していません。このキーは基本プロンプトに +追加するのではなく、基本プロンプトを置き換えます。そのため、**+** をこのキーに +接続すると、レイヤーを初めて保存した時点で Codex 独自の指示が削除されます。 +::: + +カスタムレイヤーは、その順序で 1 つのセクションにまとめられるため、カスタムレイヤー +同士で番号が付けられます。組み込みレイヤーの間に挿入されることはありません。 + +行の矢印を使うか、行内のどこからでも `Alt` + `Up` / `Alt` + `Down` を押して +並べ替えられます。この順序が組み立て順です。 + +### プリセット + +**+ Add layer** には、簡潔な出力、編集前の計画、推論の説明、テスト優先、韓国語での +応答という 5 つの開始点があります。どれを選んでも通常のエディターが入力済みの +状態で開き、すべて編集できます。プリセットは開始点にすぎず、保存すると通常の +カスタムレイヤーになります。 + +プリセットは、他者のプロンプトをコピーせず、アプローチを簡潔にまとめるために +独自に作成したテキストです。それぞれに出典が記載されています。 + +### 編集中にレイヤー間を移動する + +エディターには前へ／次へコントロールと位置インジケーターがあります。移動中も未保存の +編集内容は保持されるため、編集中に 2 つのレイヤーを比較し、入力内容を失わずに +元のレイヤーへ戻れます。 + +### 互換性の警告 + +レイヤーの内容が記述どおりに動作しない場合、エディターに警告が表示されます。別の +アイデンティティを名乗る、レジストリが定義するツール名を挙げる、展開されない +テンプレートのプレースホルダーを使う、または Codex が後から生成する環境情報を +記述する場合が該当します。 + +これらは警告であり、保存を妨げることはありません。意図的に Codex を上書きするなら、 +そのまま実行できます。警告は、それが偶然ではなく意識的な判断になるよう促すだけです。 + +## opencodex の外部で記述された指示 + +`developer_instructions` がすでに存在し、opencodex が書き込んだ値でない場合、パネルは +上書きしません。代わりに、そのテキストをレイヤーとしてインポートする選択肢を +表示します。既存の値が先に表示され、確認するまでは何も書き込まれません。 + +## 同期していない場合 + +保存済みのレイヤーと `config.toml` の値が一致しない場合、パネルはその状態を通知し、 +自動で修正せず **Repair** を提示します。修復手順のうち 2 つはユーザーが書いた +テキストを書き換えるため、明示的な操作として残されています。レイヤーファイルが +見つからない場合、修復処理は変更前にバックアップを作成します。 + +## 変更が反映されるタイミング + +変更は新しく開始したセッションに適用されます。すでに実行中のセッションは、開始時の +プロンプト設定を維持します。 + +## このページが読み取るものと、読み取らないもの + +opencodex が読み取る設定ファイルは、ユーザーの `config.toml` 1 つだけです。Codex は +複数のレイヤーから設定を解決するため、ここに表示される値はユーザーのファイルに +書かれた値であり、Codex が最終的に算出する値とは限りません。 + +## このページが書き込むキー + +これらは Codex の `config.toml` にあり、opencodex 自体の設定ではありません。 + +| キー | 既定値 | レイヤー | +|---|---|---| +| `include_permissions_instructions` | `true` | 権限 | +| `include_collaboration_mode_instructions` | `true` | コラボレーションモード | +| `include_environment_context` | `true` | 環境コンテキスト | +| `include_apps_instructions` | `true` | アプリ | +| `skills.include_instructions` | `true` | スキル | +| `developer_instructions` | 未設定 | カスタムレイヤーを順に連結した内容 | + +書き込みは行単位の編集なので、コメントと書式はそのまま残り、opencodex が認識しないキーは削除せずそのままにします。 + +キーが無い場合は `false` ではなく既定値として読み取ります。パネルはファイルに実際に書かれている値を表示し、未設定であればそう伝えます。 diff --git a/docs-site/src/content/docs/ko/guides/codex-prompt.md b/docs-site/src/content/docs/ko/guides/codex-prompt.md new file mode 100644 index 00000000000..09544ebdb26 --- /dev/null +++ b/docs-site/src/content/docs/ko/guides/codex-prompt.md @@ -0,0 +1,134 @@ +--- +title: Codex 프롬프트 레이어 +description: Codex가 실제로 보내는 내용을 확인하고, 필요 없는 부분을 끄고, 직접 작성한 지침을 레이어로 추가하세요. +--- + +Codex는 자체 기본 지침, 프로젝트 문서, 권한 및 환경 컨텍스트, 설치된 스킬 등 +여러 레이어를 조합해 프롬프트를 만듭니다. **Codex Set → Prompt**에서는 이 구성을 +확인하고, 각 레이어가 차지하는 크기를 살펴보고, 원하지 않는 부분을 끌 수 있습니다. + +## 목록에 표시되는 정보 + +각 행에는 조합 순서에서의 위치, 해당하는 경우 이를 제어하는 설정 키, 실제로 보낸 +내용의 크기가 표시됩니다. + +위치 번호가 연속되지 않는 것은 의도된 동작입니다. 이 숫자는 실제 조합 인덱스이며, +그중 두 개는 아래의 **전환 알림**에 따로 나옵니다. 각 그룹의 번호를 1부터 다시 매기면 +Codex가 실제로 쓰지 않는 순서를 보여 주게 됩니다. + +### 다섯 가지 레이어 유형 + +| 유형 | 할 수 있는 작업 | +|---|---| +| 여기서 전환 가능 | 실제 스위치입니다. `config.toml`에 키를 기록합니다. | +| 기능 플래그 적용 | 실제 레이어이지만 이 페이지가 아닌 기능 설정에서 변경합니다. | +| 항상 켜짐 | Codex 어디에도 끄는 스위치가 없습니다. | +| 변경 시 전달 | 전환을 알리므로 무언가 바뀔 때만 나타납니다. | +| 확장 레이어 | 목록에 표시할 수 없습니다. Codex가 공개하지 않습니다. | + +끌 수 없는 레이어에는 비활성화된 스위치가 아니라 스위치 자체가 표시되지 않습니다. +회색으로 비활성화된 컨트롤은 기능이 있지만 일시적으로 쓸 수 없다는 인상을 주는데, +실제로는 그런 기능이 없기 때문입니다. + +## 레이어 내용 확인하기 + +레이어 이름을 클릭하면 전송되는 텍스트를 볼 수 있습니다. 대화 상자는 +`codex debug prompt-input`에서 내용을 읽으므로 설명문이 아닌 실제 전송 내용입니다. + +표시할 내용이 없을 때도 있으며, 대화 상자에 해당하는 이유가 나옵니다. + +- **파일은 있지만 비어 있습니다.** `~/.codex/AGENTS.md`가 0바이트라서 + 레이어에서 보낼 내용이 없습니다. 대화 상자에 경로가 표시됩니다. +- **확인한 턴에서는 아무것도 보내지 않았습니다.** 레이어는 변경될 때만 다시 + 전송되므로, 바뀌지 않은 레이어는 단일 샘플에 나타나지 않습니다. +- **읽을 수 있는 목록 밖에서 전달됩니다.** 기본 프롬프트는 다른 필드로 전송되므로 + 여기에는 출력할 수 없습니다. +- **프롬프트를 읽지 못했습니다.** 이 컴퓨터에서 확인 작업이 실패했습니다. + +내용은 대시보드가 실행 중인 디렉터리가 아니라 전역 Codex 홈(`~/.codex`)에서 +읽습니다. + +## 사용자 지정 레이어 + +**+ Add layer**를 누르면 직접 작성한 지침이 추가됩니다. 사용자 지정 레이어는 +`developer_instructions`에 합쳐집니다. 이 키는 내용을 덧붙이는 방식이므로 Codex의 +자체 지침은 유지되고 작성한 지침이 추가됩니다. + +:::note +의도적으로 `model_instructions_file`을 사용하지 않습니다. 이 키는 기본 프롬프트에 +내용을 추가하는 대신 기본 프롬프트를 대체합니다. 따라서 **+**를 이 키에 연결하면 +레이어를 처음 저장할 때 Codex의 자체 지침이 삭제됩니다. +::: + +사용자 지정 레이어는 그 순서대로 하나의 섹션에 합쳐지므로 사용자 지정 레이어끼리 +번호가 매겨집니다. 기본 제공 레이어 사이에 끼어들지는 않습니다. + +행의 화살표를 누르거나 행 안의 어느 위치에서든 `Alt` + `Up` / `Alt` + `Down`을 눌러 +순서를 바꿀 수 있습니다. 이 순서가 곧 조합 순서입니다. + +### 프리셋 + +**+ Add layer**에는 간결한 출력, 편집 전 계획, 추론 설명, 테스트 우선, 한국어 답변이라는 +다섯 가지 시작점이 있습니다. 어느 항목을 선택해도 일반 편집기가 미리 채워진 상태로 +열리며 모든 내용을 수정할 수 있습니다. 프리셋은 시작점일 뿐이며, 저장하면 일반 사용자 +지정 레이어가 됩니다. + +프리셋은 다른 사람의 프롬프트를 복사하지 않고 접근 방식을 간추려 직접 작성한 +텍스트입니다. 각 프리셋에는 출처가 표시됩니다. + +### 편집 중 레이어 사이 이동하기 + +편집기에는 이전/다음 컨트롤과 위치 표시기가 있습니다. 이동하는 동안 저장하지 않은 +편집 내용이 유지되므로, 편집 도중 두 레이어를 비교하고 돌아와도 입력한 내용이 +사라지지 않습니다. + +### 호환성 경고 + +레이어 내용이 작성된 그대로 작동하지 않을 때 편집기에 경고가 표시됩니다. 다른 +정체성을 내세우거나, 레지스트리에 정의된 도구 이름을 쓰거나, 아무것도 치환하지 않는 +템플릿 자리표시자를 사용하거나, Codex가 나중에 생성하는 환경 정보를 명시하는 경우가 +이에 해당합니다. + +이 경고는 저장을 막지 않습니다. 의도적으로 Codex 설정을 덮어쓰려는 경우 그대로 +진행할 수 있습니다. 경고는 실수가 아니라 의식적인 결정이 되도록 알려 줄 뿐입니다. + +## opencodex 밖에서 작성된 지침 + +`developer_instructions`가 이미 존재하고 opencodex가 작성한 값이 아니라면 패널은 이를 +덮어쓰지 않습니다. 대신 텍스트를 레이어로 가져오는 선택지를 제공합니다. 기존 값을 +먼저 보여 주며, 확인하기 전에는 아무것도 기록하지 않습니다. + +## 동기화가 맞지 않을 때 + +저장된 레이어와 `config.toml`의 값이 다르면 패널에서 이를 알리고 자동으로 수정하는 대신 +**Repair**를 제안합니다. 복구 경로 중 두 가지는 사용자가 작성한 텍스트를 다시 쓰므로 +명시적인 선택으로 남겨 둡니다. 레이어 파일이 사라진 경우에는 복구 작업이 변경 전에 +백업을 만듭니다. + +## 변경 사항이 적용되는 시점 + +변경 사항은 새로 시작한 세션에 적용됩니다. 이미 실행 중인 세션은 시작할 때의 +프롬프트 설정을 유지합니다. + +## 이 페이지가 읽는 것과 읽지 않는 것 + +opencodex가 읽는 설정 파일은 사용자의 `config.toml` 하나입니다. Codex는 여러 레이어에서 +설정을 결정하므로, 여기에 표시되는 값은 사용자의 파일에 적힌 값이며 Codex가 최종적으로 +계산한 값과 다를 수 있습니다. + +## 이 페이지가 쓰는 키 + +이 키들은 Codex의 `config.toml`에 있으며, opencodex 자체 설정이 아닙니다. + +| 키 | 기본값 | 레이어 | +|---|---|---| +| `include_permissions_instructions` | `true` | 권한 | +| `include_collaboration_mode_instructions` | `true` | 협업 모드 | +| `include_environment_context` | `true` | 환경 정보 | +| `include_apps_instructions` | `true` | 앱 | +| `skills.include_instructions` | `true` | 스킬 | +| `developer_instructions` | 미설정 | 커스텀 레이어를 순서대로 이어붙인 값 | + +쓰기는 줄 단위 편집이라 주석과 서식이 그대로 남고, opencodex가 모르는 키는 지우지 않고 그대로 둡니다. + +키가 없으면 `false`가 아니라 기본값으로 읽습니다. 패널은 파일에 실제로 적힌 값을 보여주고, 키가 설정되지 않은 경우 그렇다고 알려줍니다. diff --git a/docs-site/src/content/docs/ru/guides/codex-prompt.md b/docs-site/src/content/docs/ru/guides/codex-prompt.md new file mode 100644 index 00000000000..6e9b18b2a0b --- /dev/null +++ b/docs-site/src/content/docs/ru/guides/codex-prompt.md @@ -0,0 +1,134 @@ +--- +title: Слои промпта Codex +description: Узнайте, что на самом деле отправляет Codex, отключите ненужные части и добавьте собственные инструкции в виде слоёв. +--- + +Codex собирает свой промпт из слоёв: собственных базовых инструкций, документации +вашего проекта, контекста разрешений и среды, установленных навыков и других +компонентов. **Codex Set → Prompt** показывает этот стек, сообщает стоимость каждого слоя +и позволяет отключить ненужные части. + +## Что показывает список + +В каждой строке указаны её позиция в порядке сборки, управляющий ею ключ конфигурации, +если он существует, и размер фактически отправленного содержимого. + +В нумерации позиций есть пропуски. Это сделано намеренно: числа соответствуют реальным +индексам сборки, а два из них перечислены ниже в разделе **Уведомления о переходах**. +Если заново нумеровать каждую группу с единицы, получится порядок, который Codex не использует. + +### Пять видов слоёв + +| Вид | Что можно сделать | +|---|---| +| Переключается здесь | Настоящий переключатель. Записывает ключ в `config.toml`. | +| Управляется флагом функции | Реальный слой, но изменяется в настройках функций, а не на этой странице. | +| Всегда включён | В Codex нигде нет переключателя для его отключения. | +| При изменении | Сообщает о переходе, поэтому появляется только при изменении. | +| Слой расширения | Нельзя вывести в списке. Codex их не предоставляет. | + +У слоя без возможности отключения переключатель вообще не показывается, а не отображается +неактивным. Серый элемент управления создавал бы впечатление, что такая возможность существует, +но временно недоступна, хотя это не так. + +## Чтение слоя + +Нажмите на название слоя, чтобы увидеть отправляемый им текст. Диалоговое окно получает его +из `codex debug prompt-input`, поэтому показывает реальное содержимое, а не описание. + +Иногда показывать нечего, и диалоговое окно указывает причину: + +- **Файл существует, но пуст.** Ваш файл `~/.codex/AGENTS.md` имеет нулевой размер, поэтому + слою нечего отправлять. В диалоговом окне указан путь. +- **Он ничего не отправил в прочитанном нами ходе.** Слои отправляются повторно только при + изменении, поэтому неизменившийся слой отсутствует в отдельном образце. +- **Он передаётся вне доступного для чтения списка.** Базовый промпт отправляется через + другое поле и не может быть выведен здесь. +- **Не удалось прочитать промпт.** Проверка на этом компьютере завершилась с ошибкой. + +Данные считываются из вашего глобального домашнего каталога Codex (`~/.codex`), а не из каталога, +в котором в данный момент запущен дашборд. + +## Пользовательские слои + +**+ Add layer** добавляет в конец ваши собственные инструкции. Пользовательские слои объединяются +в `developer_instructions`, который работает аддитивно: Codex сохраняет свои инструкции и +добавляет к ним ваши. + +:::note +Это намеренно не `model_instructions_file`. Этот ключ ЗАМЕНЯЕТ базовый промпт, а не дополняет +его, поэтому привязка **+** к нему удалила бы собственные инструкции Codex при первом сохранении слоя. +::: + +Пользовательские слои нумеруются между собой, потому что объединяются в один раздел именно +в таком порядке — они не чередуются со встроенными слоями. + +Меняйте порядок стрелками в строке или сочетаниями `Alt` + `Up` / `Alt` + `Down` из любого +места строки. Это порядок объединения. + +### Предустановки + +**+ Add layer** предлагает пять отправных точек: краткий вывод, планирование до редактирования, +объяснение рассуждений, сначала тесты и ответы на корейском языке. Каждая открывается в обычном +редакторе с предварительно заполненным, полностью редактируемым текстом: предустановка — лишь +отправная точка, а сохранённый результат становится обычным пользовательским слоем. + +Предустановки содержат наш собственный текст, сформулированный для передачи сути подхода, а не +для копирования чьего-либо промпта. В каждой указан её источник. + +### Переход между слоями во время редактирования + +В редакторе есть элементы управления переходом назад и вперёд и индикатор позиции. Несохранённые +изменения сохраняются при переходах, поэтому можно сравнить два слоя во время редактирования и +вернуться назад, не потеряв введённый текст. + +### Предупреждения о совместимости + +Редактор предупреждает, если слой содержит инструкции, которые не будут работать в написанном +виде: заявляет другую идентичность, называет инструмент, определённый в реестре, использует +шаблонные заполнители, которые ничем не раскрываются, или указывает сведения о среде, которые +Codex создаёт позже. + +Это только предупреждения, они никогда не блокируют сохранение. Если вы намерены переопределить +Codex, это возможно; предупреждение лишь превращает случайность в осознанное решение. + +## Инструкции, записанные вне opencodex + +Если `developer_instructions` уже существует и был записан не opencodex, панель не станет его +перезаписывать. Вместо этого она предложит импортировать текст как слой: сначала вы увидите +существующее значение, и до подтверждения ничего не будет записано. + +## Когда данные рассинхронизированы + +Если сохранённые слои и значение в `config.toml` расходятся, панель сообщает об этом и предлагает +**Repair**, а не исправляет всё без уведомления. Два варианта исправления перезаписывают созданный +вами текст, поэтому требуют осознанного действия. Если файл слоя пропал, перед любыми изменениями +создаётся резервная копия. + +## Когда изменения вступают в силу + +Изменения применяются к новым сеансам. Уже запущенный сеанс сохраняет настройки промпта, +с которыми он был запущен. + +## Что читает эта страница, а что нет + +opencodex читает один файл конфигурации — ваш `config.toml`. Codex определяет настройки по +нескольким слоям, поэтому показанное здесь значение отражает содержимое ВАШЕГО файла, а не +обязательно итоговое значение, вычисленное Codex. + +## Ключи, которые пишет эта страница + +Они находятся в `config.toml` Codex, а не в собственной конфигурации opencodex. + +| Ключ | По умолчанию | Слой | +|---|---|---| +| `include_permissions_instructions` | `true` | Разрешения | +| `include_collaboration_mode_instructions` | `true` | Режим совместной работы | +| `include_environment_context` | `true` | Контекст окружения | +| `include_apps_instructions` | `true` | Приложения | +| `skills.include_instructions` | `true` | Навыки | +| `developer_instructions` | не задан | Пользовательские слои, объединённые по порядку | + +Запись выполняется построчно: ваши комментарии и форматирование сохраняются, а незнакомый opencodex ключ остаётся нетронутым, а не удаляется. + +Отсутствующий ключ читается как значение по умолчанию, а не как `false`. Панель показывает значение, которое действительно есть в файле, и сообщает, когда ключ не задан. diff --git a/docs-site/src/content/docs/tr/guides/codex-prompt.md b/docs-site/src/content/docs/tr/guides/codex-prompt.md new file mode 100644 index 00000000000..c842cef904d --- /dev/null +++ b/docs-site/src/content/docs/tr/guides/codex-prompt.md @@ -0,0 +1,142 @@ +--- +title: Codex İstem Katmanları +description: Codex'in gerçekte ne gönderdiğini görün, ihtiyacınız olmayan bölümleri kapatın ve kendi talimatlarınızı katmanlar olarak ekleyin. +--- + +Codex istemini katmanlardan oluşturur: kendi temel talimatları, proje +belgeleriniz, izin ve ortam bağlamı, yüklediğiniz beceriler ve daha fazlası. +**Codex Set → Prompt** bu yığını gösterir, her katmanın maliyetini belirtir ve +istemediğiniz bölümleri kapatmanıza olanak tanır. + +## Liste ne gösterir? + +Her satır, oluşturma sırasındaki konumunu, varsa onu yöneten yapılandırma +anahtarını ve gerçekte gönderilen içeriğin boyutunu içerir. + +Konumlar arasında boşluklar vardır. Bu bilinçli bir tercihtir: sayılar gerçek +oluşturma indeksleridir ve bunlardan ikisi aşağıda **Geçiş bildirimleri** altında +listelenir. Her grubu birden başlayarak yeniden numaralandırmak, Codex'in +kullanmadığı bir sıralamayı gösterirdi. + +### Beş katman türü + +| Tür | Yapabilecekleriniz | +|---|---| +| Buradan değiştirilebilir | Gerçek bir anahtar. `config.toml` içine bir anahtar yazar. | +| Özellik bayraklı | Gerçektir, ancak bu sayfa yerine `[features]` ayarlarından değiştirilir. | +| Her zaman açık | Codex'in hiçbir yerinde kapatma anahtarı yoktur. | +| Değişimde gönderilir | Bir geçişi bildirir, bu nedenle yalnızca bir şey değiştiğinde görünür. | +| Uzantı katmanı | Listelenemez. Codex bunları göstermez. | + +Kapatma anahtarı olmayan bir katman, devre dışı bırakılmış bir anahtar yerine +hiç anahtar göstermez. Soluk bir kontrol, bu özelliğin var olduğunu ancak geçici +olarak kullanılamadığını düşündürürdü; durum böyle değildir. + +## Bir katmanı okuma + +Gönderdiği metni görmek için katman adına tıklayın. İletişim kutusu bunu +`codex debug prompt-input` üzerinden okur; dolayısıyla bir açıklama değil, +gerçekte gönderilen metindir. + +Bazen gösterilecek bir şey olmaz ve iletişim kutusu hangi nedenin geçerli +olduğunu belirtir: + +- **Dosya var ancak boş.** `~/.codex/AGENTS.md` dosyanız sıfır bayttır, bu + nedenle katmanın gönderecek bir şeyi yoktur. İletişim kutusu yolu belirtir. +- **Okuduğumuz turda hiçbir şey göndermedi.** Katmanlar yalnızca değiştiklerinde + yeniden gönderilir, dolayısıyla değişmemiş bir katman tek bir örnekte yer almaz. +- **Okunabilir listenin dışında taşınır.** Temel istem farklı bir alan üzerinden + gönderilir ve burada yazdırılamaz. +- **İstem okunamadı.** İnceleme bu makinede başarısız oldu. + +Okuma, kontrol panelinin çalıştığı dizinden değil, genel Codex ana dizininizden +(`~/.codex`) alınır. + +## Özel katmanlar + +**+ Add layer** kendi talimatlarınızı sona ekler. Özel katmanlar +`developer_instructions` içinde birleştirilir ve bu eklemelidir — Codex kendi +talimatlarını korur, sizinkiler de bunlara eklenir. + +:::note +Bu, bilinçli olarak `model_instructions_file` değildir. Bu anahtar temel isteme +ekleme yapmak yerine onu DEĞİŞTİRİR; dolayısıyla **+** düğmesini buna bağlamak, +bir katmanı ilk kaydettiğinizde Codex'in kendi talimatlarını silerdi. +::: + +Özel katmanlar kendi aralarında numaralandırılır, çünkü bu sırayla tek bir +bölümde birleştirilirler; yerleşik katmanların arasına girmezler. + +Satırdaki oklarla veya satırın herhangi bir yerindeyken `Alt` + `Up` / `Alt` + +`Down` ile sıralamayı değiştirin. Sıra, birleştirme sırasıdır. + +### Ön ayarlar + +**+ Add layer** beş başlangıç noktası sunar: kısa çıktı, düzenlemeden önce plan, +gerekçeyi açıklama, önce test ve Korece yanıtlar. Her biri, önceden doldurulmuş +ve tamamen düzenlenebilir normal düzenleyiciyi açar — ön ayar bir başlangıç +noktasıdır ve kaydettiğiniz şey normal bir özel katmandır. + +Ön ayarlar, herhangi birinin istemini kopyalamak yerine bir yaklaşımı özlü +biçimde aktarmak için yazdığımız kendi metinlerimizdir. Her biri kaynağını belirtir. + +### Düzenleme sırasında katmanlar arasında geçiş + +Düzenleyicide önceki/sonraki kontrolleri ve bir konum göstergesi vardır. +Kaydedilmemiş düzenlemeler siz geçiş yaparken korunur; böylece düzenleme +sırasında iki katmanı karşılaştırabilir ve yazdıklarınızı kaybetmeden geri +dönebilirsiniz. + +### Uyumluluk uyarıları + +Düzenleyici, bir katman yazıldığı şekliyle çalışmayacak bir şey söylediğinde +uyarır: farklı bir kimlik iddia etmek, kayıt defterinin tanımladığı bir aracın +adını vermek, hiçbir şeyin genişletmediği şablon yer tutucuları kullanmak veya +Codex'in daha sonra oluşturduğu ortam bilgilerini belirtmek. + +Bunlar uyarıdır ve kaydetmeyi asla engellemez. Codex'i geçersiz kılmak +istiyorsanız bunu yapabilirsiniz; uyarı yalnızca bunun bir kaza değil, bilinçli +bir karar olmasını sağlar. + +## opencodex dışında yazılan talimatlar + +`developer_instructions` zaten varsa ve opencodex tarafından yazılmadıysa panel +bunun üzerine yazmaz. Bunun yerine metni bir katman olarak içe aktarmayı önerir: +önce mevcut değeri görürsünüz ve siz onaylayana kadar hiçbir şey yazılmaz. + +## Bir şeyler eşitlenmediğinde + +Kaydedilen katmanlar ile `config.toml` içindeki değer uyuşmazsa panel bunu +belirtir ve sessizce düzeltmek yerine **Repair** seçeneğini sunar. Onarım +yollarından ikisi yazdığınız metni yeniden yazar, bu nedenle işlem bilinçli +olarak başlatılmalıdır. Bir katman dosyası kaybolmuşsa onarım, herhangi bir şeye +dokunmadan önce bir yedek yazar. + +## Değişiklikler ne zaman etkili olur? + +Değişiklikler yeni başlatılan oturumlara uygulanır. Çalışmakta olan bir oturum, +başlangıçta kullandığı istem ayarlarını korur. + +## Bu sayfa neyi okur, neyi okumaz? + +opencodex tek bir yapılandırma dosyasını, yani `config.toml` dosyanızı okur. +Codex ayarlarını birkaç katmandan çözümler; dolayısıyla buradaki bir değer, +Codex'in sonunda hesapladığı değer olmak zorunda değil, SİZİN dosyanızda yazan +değerdir. + +## Bu sayfanın yazdığı anahtarlar + +Bunlar opencodex'in kendi yapılandırmasında değil, Codex'in `config.toml` dosyasında bulunur. + +| Anahtar | Varsayılan | Katman | +|---|---|---| +| `include_permissions_instructions` | `true` | İzinler | +| `include_collaboration_mode_instructions` | `true` | İş birliği modu | +| `include_environment_context` | `true` | Ortam bağlamı | +| `include_apps_instructions` | `true` | Uygulamalar | +| `skills.include_instructions` | `true` | Beceriler | +| `developer_instructions` | ayarlanmamış | Sırayla birleştirilen özel katmanlarınız | + +Yazma işlemi satır bazlıdır: yorumlarınız ve biçimlendirmeniz korunur, opencodex'in tanımadığı bir anahtar silinmek yerine olduğu gibi bırakılır. + +Bulunmayan bir anahtar `false` olarak değil, varsayılanı olarak okunur. Panel dosyanızda gerçekten bulunan değeri gösterir ve bir anahtar ayarlanmamışsa bunu belirtir. diff --git a/docs-site/src/content/docs/zh-cn/guides/codex-prompt.md b/docs-site/src/content/docs/zh-cn/guides/codex-prompt.md new file mode 100644 index 00000000000..7d6420149d1 --- /dev/null +++ b/docs-site/src/content/docs/zh-cn/guides/codex-prompt.md @@ -0,0 +1,122 @@ +--- +title: Codex 提示词层 +description: 查看 Codex 实际发送的内容，关闭不需要的部分，并以层的形式追加你自己的指令。 +--- + +Codex 会分层组装提示词：它自己的基础指令、你的项目文档、权限与环境上下文、 +你安装的技能，以及更多内容。**Codex Set → Prompt** 会显示这个层叠结构，告诉你 +每一层占用多少空间，并让你关闭不需要的部分。 + +## 列表显示什么 + +每一行都会显示它在组装顺序中的位置、控制它的配置键（如果有），以及它实际 +发送内容的大小。 + +位置编号之间会有空缺。这是有意为之：这些数字是真实的组装索引，其中两个会在 +下方的 **过渡通知** 中列出。如果把每组都从一开始重新编号，显示的就会是 Codex +实际并未使用的顺序。 + +### 五种层 + +| 类型 | 你可以做什么 | +|---|---| +| 可在此切换 | 一个真正的开关。会在 `config.toml` 中写入一个键。 | +| 功能开关控制 | 确实存在，但要从功能设置中更改，而不是在此页面。 | +| 始终启用 | Codex 中任何地方都没有关闭开关。 | +| 变更时发送 | 通知状态过渡，因此只有内容发生变化时才会出现。 | +| 扩展层 | 无法列出。Codex 不会公开它们。 | + +没有关闭开关的层根本不会显示开关，而不是显示一个禁用的开关。灰显控件会暗示 +这项能力存在、只是暂时不可用，但实际并非如此。 + +## 读取一层 + +点击层名称即可查看它发送的文本。对话框会从 `codex debug prompt-input` 读取内容， +所以显示的是真实内容，而不是描述。 + +有时没有内容可显示，对话框会说明具体原因： + +- **文件存在但为空。** 你的 `~/.codex/AGENTS.md` 是零字节，因此该层没有内容可发送。 + 对话框会显示路径。 +- **在我们读取的这一轮中，它没有发送任何内容。** 各层只有在发生变化时才会重新发送， + 所以未变化的层不会出现在单次样本中。 +- **它在可读列表之外传输。** 基础提示词通过另一个字段发送，无法在这里打印。 +- **无法读取提示词。** 此机器上的探测失败。 + +读取内容来自你的全局 Codex 主目录（`~/.codex`），而不是仪表板碰巧运行的目录。 + +## 自定义层 + +**+ Add layer** 会追加你自己的指令。自定义层会组合到 `developer_instructions` 中， +它采用追加方式——Codex 会保留自己的指令，并把你的指令添加进去。 + +:::note +这里特意不使用 `model_instructions_file`。该键会替换基础提示词，而不是追加内容， +所以如果把 **+** 接到它上面，第一次保存层时就会删除 Codex 自己的指令。 +::: + +自定义层会在它们自身之间编号，因为它们会按该顺序合并为一个区段——它们不会 +与内置层交错排列。 + +可以使用行上的箭头重新排序，也可以在行内任意位置按 `Alt` + `Up` / `Alt` + `Down`。 +顺序就是组合顺序。 + +### 预设 + +**+ Add layer** 提供五个起点：精简输出、编辑前规划、解释推理、先测试，以及使用韩语 +回复。每一个都会打开普通编辑器，预先填入内容且可完全编辑——预设只是起点，你保存的 +内容会成为普通的自定义层。 + +这些预设是我们自己的文本，旨在提炼一种方法，而不是复制任何人的提示词。每个预设都会 +注明来源。 + +### 编辑时在各层之间移动 + +编辑器提供上一层/下一层控件和位置指示器。移动时会保留未保存的编辑，因此你可以在编辑 +途中比较两层，再返回原处，而不会丢失已输入的内容。 + +### 兼容性警告 + +如果某一层包含无法按原文生效的内容，编辑器会发出警告——例如声称自己具有不同身份、 +指定注册表已定义的工具、使用不会被任何机制展开的模板占位符，或陈述 Codex 稍后才会 +生成的环境事实。 + +这些只是警告，绝不会阻止保存。如果你确实想覆盖 Codex，也可以这样做；警告只是让它成为 +一个有意的决定，而不是意外。 + +## 在 opencodex 外部写入的指令 + +如果 `developer_instructions` 已经存在，且不是由 opencodex 写入，面板不会覆盖它。 +面板会改为提供将文本导入为一层的选项：你会先看到现有值，在确认之前不会写入任何内容。 + +## 内容不同步时 + +如果已保存的层与 `config.toml` 中的值不一致，面板会说明情况并提供 **Repair**，而不会 +静默修复。两种修复路径会重写你写过的文本，因此这些操作始终需要明确执行。如果某个层文件 +已经丢失，修复功能会先写入备份，再进行任何修改。 + +## 更改何时生效 + +更改会应用于新启动的会话。已经运行的会话会继续使用启动时的提示词设置。 + +## 此页面读取什么，又不读取什么 + +opencodex 只读取一个配置文件——你的 `config.toml`。Codex 会从多个层解析设置，因此这里的值 +表示的是你的文件所写的内容，不一定是 Codex 最终计算出的值。 + +## 此页面写入的键 + +这些键位于 Codex 的 `config.toml` 中，而不是 opencodex 自身的配置。 + +| 键 | 默认值 | 层 | +|---|---|---| +| `include_permissions_instructions` | `true` | 权限 | +| `include_collaboration_mode_instructions` | `true` | 协作模式 | +| `include_environment_context` | `true` | 环境上下文 | +| `include_apps_instructions` | `true` | 应用 | +| `skills.include_instructions` | `true` | 技能 | +| `developer_instructions` | 未设置 | 按顺序连接的自定义层 | + +写入采用逐行编辑，你的注释和格式会保留；opencodex 无法识别的键会原样保留，而不会被删除。 + +缺失的键按默认值读取，而不是按 `false`。面板显示文件中实际存在的值，并在键未设置时说明这一点。 diff --git a/docs-site/src/content/docs/zh-tw/guides/codex-prompt.md b/docs-site/src/content/docs/zh-tw/guides/codex-prompt.md new file mode 100644 index 00000000000..21702cd0500 --- /dev/null +++ b/docs-site/src/content/docs/zh-tw/guides/codex-prompt.md @@ -0,0 +1,122 @@ +--- +title: Codex 提示詞層 +description: 查看 Codex 實際傳送的內容，關閉不需要的部分，並以層的形式附加你自己的指令。 +--- + +Codex 會分層組裝提示詞：它自己的基礎指令、你的專案文件、權限與環境脈絡、 +你安裝的技能，以及更多內容。**Codex Set → Prompt** 會顯示這個層疊結構，告訴你 +每一層占用多少空間，並讓你關閉不需要的部分。 + +## 清單顯示什麼 + +每一列都會顯示它在組裝順序中的位置、控制它的設定鍵（如果有），以及它實際 +傳送內容的大小。 + +位置編號之間會有空缺。這是刻意安排的：這些數字是真實的組裝索引，其中兩個會在 +下方的 **過渡通知** 中列出。如果把每組都從一開始重新編號，顯示的就會是 Codex +實際並未使用的順序。 + +### 五種層 + +| 類型 | 你可以做什麼 | +|---|---| +| 可在此切換 | 一個真正的開關。會在 `config.toml` 中寫入一個鍵。 | +| 功能開關控制 | 確實存在，但要從功能設定中變更，而不是在此頁面。 | +| 一律啟用 | Codex 中任何地方都沒有關閉開關。 | +| 變更時傳送 | 通知狀態過渡，因此只有內容發生變更時才會出現。 | +| 擴充層 | 無法列出。Codex 不會公開它們。 | + +沒有關閉開關的層完全不會顯示開關，而不是顯示一個停用的開關。灰顯控制項會暗示 +這項能力存在、只是暫時無法使用，但實際並非如此。 + +## 讀取一層 + +點擊層名稱即可查看它傳送的文字。對話框會從 `codex debug prompt-input` 讀取內容， +所以顯示的是真實內容，而不是描述。 + +有時沒有內容可顯示，對話框會說明具體原因： + +- **檔案存在但為空。** 你的 `~/.codex/AGENTS.md` 是零位元組，因此該層沒有內容可傳送。 + 對話框會顯示路徑。 +- **在我們讀取的這一輪中，它沒有傳送任何內容。** 各層只有在發生變更時才會重新傳送， + 所以未變更的層不會出現在單次樣本中。 +- **它在可讀清單之外傳輸。** 基礎提示詞透過另一個欄位傳送，無法在這裡列印。 +- **無法讀取提示詞。** 此機器上的探測失敗。 + +讀取內容來自你的全域 Codex 主目錄（`~/.codex`），而不是儀表板碰巧執行的目錄。 + +## 自訂層 + +**+ Add layer** 會附加你自己的指令。自訂層會組合到 `developer_instructions` 中， +它採用附加方式——Codex 會保留自己的指令，並把你的指令加進去。 + +:::note +這裡刻意不使用 `model_instructions_file`。該鍵會取代基礎提示詞，而不是附加內容， +所以如果把 **+** 接到它上面，第一次儲存層時就會刪除 Codex 自己的指令。 +::: + +自訂層會在它們自身之間編號，因為它們會按該順序合併為一個區段——它們不會 +與內建層交錯排列。 + +可以使用列上的箭頭重新排序，也可以在列內任意位置按 `Alt` + `Up` / `Alt` + `Down`。 +順序就是組合順序。 + +### 預設 + +**+ Add layer** 提供五個起點：精簡輸出、編輯前規劃、解釋推理、先測試，以及使用韓文 +回覆。每一個都會開啟一般編輯器，預先填入內容且可完全編輯——預設只是起點，你儲存的 +內容會成為一般的自訂層。 + +這些預設是我們自己的文字，旨在提煉一種方法，而不是複製任何人的提示詞。每個預設都會 +註明來源。 + +### 編輯時在各層之間移動 + +編輯器提供上一層/下一層控制項和位置指示器。移動時會保留未儲存的編輯，因此你可以在編輯 +途中比較兩層，再返回原處，而不會遺失已輸入的內容。 + +### 相容性警告 + +如果某一層包含無法按原文生效的內容，編輯器會發出警告——例如聲稱自己具有不同身分、 +指定註冊表已定義的工具、使用不會被任何機制展開的範本預留位置，或陳述 Codex 稍後才會 +產生的環境事實。 + +這些只是警告，絕不會阻止儲存。如果你確實想覆寫 Codex，也可以這樣做；警告只是讓它成為 +一個有意的決定，而不是意外。 + +## 在 opencodex 外部寫入的指令 + +如果 `developer_instructions` 已經存在，且不是由 opencodex 寫入，面板不會覆寫它。 +面板會改為提供將文字匯入為一層的選項：你會先看到現有值，在確認之前不會寫入任何內容。 + +## 內容不同步時 + +如果已儲存的層與 `config.toml` 中的值不一致，面板會說明情況並提供 **Repair**，而不會 +靜默修復。兩種修復路徑會重寫你寫過的文字，因此這些操作始終需要明確執行。如果某個層檔案 +已經遺失，修復功能會先寫入備份，再進行任何修改。 + +## 變更何時生效 + +變更會套用到新啟動的工作階段。已經執行的工作階段會繼續使用啟動時的提示詞設定。 + +## 此頁面讀取什麼，又不讀取什麼 + +opencodex 只讀取一個設定檔——你的 `config.toml`。Codex 會從多個層解析設定，因此這裡的值 +表示的是你的檔案所寫的內容，不一定是 Codex 最終計算出的值。 + +## 此頁面寫入的鍵 + +這些鍵位於 Codex 的 `config.toml` 中，而不是 opencodex 自身的設定。 + +| 鍵 | 預設值 | 層 | +|---|---|---| +| `include_permissions_instructions` | `true` | 權限 | +| `include_collaboration_mode_instructions` | `true` | 協作模式 | +| `include_environment_context` | `true` | 環境內容 | +| `include_apps_instructions` | `true` | 應用程式 | +| `skills.include_instructions` | `true` | 技能 | +| `developer_instructions` | 未設定 | 依序連接的自訂層 | + +寫入採用逐行編輯，你的註解與格式會保留；opencodex 無法辨識的鍵會原樣保留，而不會被刪除。 + +缺少的鍵會以預設值讀取，而不是 `false`。面板顯示檔案中實際存在的值，並在鍵未設定時說明這一點。 From bdf21ff32d252aaa287d523bdeb4522d4983444d Mon Sep 17 00:00:00 2001 From: jun Date: Wed, 26 Aug 2026 22:51:12 +0900 Subject: [PATCH 2/2] devlog(260802): record why local green missed three CI rounds The stack went up green on my machine and came back red three times, each time for the same reason: a layer that only builds on top of its successors. CustomLayerDialog called three i18n keys whose catalog entries lived a layer higher, so `tsc` failed at that tip and thirteen dependent jobs followed it down - invisible from the stack head, which is the only place I had been testing. Also records the two real user-facing bugs the round surfaced (the layer body that could only scroll sideways, and a failed probe reported as measured truth), and the findings that were NOT ours so a later reader does not chase pre-existing dev debt or a cancelled concurrency job. MSGEOF && git log --oneline -1 --- .../091_stack_gate_findings.md | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 devlog/_plan/260802_codex_set_prompt_composer/091_stack_gate_findings.md diff --git a/devlog/_plan/260802_codex_set_prompt_composer/091_stack_gate_findings.md b/devlog/_plan/260802_codex_set_prompt_composer/091_stack_gate_findings.md new file mode 100644 index 00000000000..ac95586538f --- /dev/null +++ b/devlog/_plan/260802_codex_set_prompt_composer/091_stack_gate_findings.md @@ -0,0 +1,104 @@ +# 090 — What the stack gate caught, and why local green was not enough + +Closing record for the publication phase. The five-layer stack went up green +on my machine and came back red from CI three rounds running. Every one of +those rounds found something real, and they were all the same shape. + +## The defect class: a layer that only builds on top of its successors + +`CustomLayerDialog` calls three i18n keys: + +``` +codexSet.custom.prevLayer +codexSet.custom.navPosition +codexSet.custom.nextLayer +``` + +The dialog landed in the **authoring** layer. The catalog entries landed one +layer higher, in **realtext**. Nothing locally noticed, because every local +check ran at the top of the chain where both halves exist. + +CI checks out each PR's own head. At the authoring tip `bun x tsc` failed with +three TS2345s — the keys are not in `TKey` yet — and the thirteen downstream +jobs that depend on a build all followed it down. Thirteen red checks, one +cause, and the cause was invisible from the place I was testing. + +The same shape produced three more failures: + +| Symptom | Fix landed in | Was defined in | +|---|---|---| +| TS2345 x3 on the nav keys | authoring | realtext | +| `fr`/`zh-TW` locale gate on `navPosition` | realtext | authoring (after the move) | +| `react-compiler` EffectSetState, `only-export-components` | authoring | shell (files originate there) | +| `input[role="switch"]` queries matching nothing | scattered | the layer that made it a `