cx-viewer 1.0.2 → 1.0.4

package/concepts/uk/Teammate.md

@@ -1,26 +1,26 @@
 # Teammate
 
-## Визначення
+## Definition
 
-Teammate — це колаборативний agent у режимі команди Claude Code Agent Team. Коли головний agent створює команду через `TeamCreate` і генерує teammate за допомогою інструменту `Agent`, кожен teammate працює як незалежний процес agent із власним контекстним вікном та набором інструментів, спілкуючись з членами команди через `SendMessage`.
+A Teammate is a collaborative agent in Codex Agent Team mode. The main agent discovers the available multi-agent tools through `tool_search`; when those tools are available, each teammate runs as an independent agent process with its own context window and toolset.
 
-## Відмінності від SubAgent
+## Differences from SubAgent
 
-| Характеристика | Teammate | SubAgent |
-|------|----------|----------|
-| Життєвий цикл | Існує постійно, може отримувати кілька повідомлень | Одноразове завдання, знищується після завершення |
-| Спосіб комунікації | Двонаправлені повідомлення через SendMessage | Односпрямований виклик батько→дитина, повернення результату |
-| Контекст | Незалежний повний контекст, зберігається між раундами | Ізольований контекст завдання |
-| Модель співпраці | Командна співпраця, можуть спілкуватися між собою | Ієрархічна структура, взаємодія лише з батьківським agent |
-| Тип завдань | Складні багатокрокові завдання | Одиничні завдання: пошук, дослідження тощо |
+| Feature | Teammate | SubAgent |
+|---------|----------|----------|
+| Lifecycle | Persistent, can receive multiple messages | One-off task, destroyed upon completion |
+| Communication | Team messaging through the available multi-agent toolset | Parent→child unidirectional call, returns result |
+| Context | Independent full context, retained across turns | Isolated task context |
+| Collaboration | Team collaboration, can communicate with each other | Hierarchical structure, only interacts with parent agent |
+| Task Type | Complex multi-step tasks | Single tasks such as search and exploration |
 
-## Поведінка
+## Behavior
 
-- Створюється головним agent (team lead) через інструмент `Agent` з призначенням `team_name`
-- Спільний список завдань через `TaskList` / `TaskGet` / `TaskUpdate`
-- Після кожного раунду виконання переходить у стан idle, очікуючи нове повідомлення для активації
-- Може бути коректно завершений через `shutdown_request`
+- Created by the main agent (team lead) through available multi-agent tooling and assigned a team identity
+- Shares task state through the available multi-agent task/status tools
+- Enters idle state after each turn, waiting to be woken by a new message
+- Can be gracefully terminated via `shutdown_request`
 
-## Опис панелі статистики
+## Stats Panel Description
 
-Панель статистики Teammate відображає кількість API-викликів кожного teammate. Стовпець `Name` містить ім'я teammate (наприклад, `reviewer-security`, `reviewer-pipeline`), стовпець `Кількість` — загальну кількість API-запитів, згенерованих цим teammate.
+The Teammate stats panel displays the number of API calls for each teammate. The `Name` column shows the teammate's name (e.g., `reviewer-security`, `reviewer-pipeline`), and the `Count` column shows the total number of API requests generated by that teammate.

package/concepts/uk/ToolsFirst.md

@@ -1,77 +1,71 @@
-# Чому Tools відображаються першими?
+# Why Are Tools Listed First?
 
-На панелі Context у cc-viewer **Tools з'являються перед System Prompt та Messages**. Такий порядок точно відображає **послідовність префікса KV-Cache в Anthropic API**.
+In CX Viewer's Context panel, **Tools appear before Instructions and Input**. For Codex, this is a diagnostic layout: tool definitions are a large, high-impact part of the request shape, so they are shown first before the instructions and conversation context they constrain.
 
-## Послідовність префікса KV-Cache
+## Request Context Layout
 
-Коли Anthropic API будує KV-Cache, він об'єднує контекст у префікс у такому **фіксованому порядку**:
+Codex traffic can arrive from OpenAI Responses API calls, Codex app-server events, or SDK stream events. CX Viewer normalizes those sources into a consistent context view:
 
 ```
 ┌─────────────────────────────────────────────────┐
-│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
-│ 2. System Prompt                                 │
-│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+│ 1. Tools (JSON Schema definitions)               │  ← Capability surface
+│ 2. Instructions                                  │
+│ 3. Input (conversation history + current turn)   │
 └─────────────────────────────────────────────────┘
 ```
 
-Це означає, що **Tools розміщені перед System Prompt на самому початку префікса кешу**.
+This does not claim a provider-specific serialization order. It gives you a stable way to inspect what capabilities were available before reading instructions and input history.
 
-## Чому Tools мають більшу вагу в кеші, ніж System?
+## Why Tools Often Matter Most
 
-При зіставленні префіксів KV-Cache **більш раннє розташування контенту є більш критичним** — будь-яка зміна скасовує все, що йде після:
+Tool definitions are often the largest static part of an agent request. A small UI toggle can add, remove, or reshape many tool schemas, which changes model behavior and request size.
 
-1. **Зіставлення префіксів починається з початку**: KV-Cache порівнює поточний запит із кешованим префіксом token за token від початку. Щойно виявляється розбіжність, весь наступний контент стає недійсним.
+1. **Capability changes are semantic changes**: Adding or removing a tool changes what the agent is allowed to do, not just the token count.
 
-2. **Зміна Tools = весь кеш скасовано**: Оскільки Tools стоять першими, будь-яка зміна у визначеннях інструментів (навіть додавання або видалення одного MCP tool) **ламає префікс з самого початку**, роблячи недійсними весь кешований System Prompt та Messages.
+2. **Tool schemas can dominate request size**: MCP and dynamic tools often have detailed JSON Schemas with descriptions, enums, and nested parameters.
 
-3. **Зміна System = кеш Messages скасовано**: System Prompt розташований посередині, тому його зміни скасовують лише наступну частину Messages.
+4. **Input appends are usually cheaper to inspect**: Normal conversation turns mostly add new user input and the previous assistant/tool results, while tool and instruction changes tend to be rarer and more important.
 
-4. **Зміна Messages = впливає тільки на хвіст**: Messages знаходяться в кінці, тому додавання нових повідомлень скасовує лише невеликий кінцевий сегмент — кеш Tools та System залишається незайманим.
+## Practical Impact
 
-## Практичний вплив
+| Change Type | Cache Impact | Typical Scenario |
+|-------------|-------------|-----------------|
+| Tool added/removed | Request shape changes | MCP server connect/disconnect, plugin toggle |
+| Instructions change | Instructions and policy changed | `AGENTS.md` edit, developer instruction update |
+| New input appended | Normal turn growth | User input, assistant reply, tool result |
 
-| Тип зміни | Вплив на кеш | Типовий сценарій |
-|-----------|-------------|-----------------|
-| Tool додано/видалено | **Повне скасування** | Підключення/відключення MCP server, увімкнення/вимкнення плагіна IDE |
-| Зміна System Prompt | Втрата кешу Messages | Редагування CLAUDE.md, ін'єкція system reminder |
-| Додано нове повідомлення | Лише хвостове збільшення | Звичайний хід розмови (найпоширеніший, найдешевший) |
+## Why Are Tool Definitions Placed Before the "Brain"?
 
-Саме тому `tools_change` у [CacheRebuild](CacheRebuild.md) зазвичай є найдорожчою причиною перебудови — вона ламає ланцюг префіксів з самого початку.
+From a diagnostic perspective, putting Tools first is useful because tool definitions describe the agent's available actions before you inspect the instructions that ask the agent to act.
 
-## Чому визначення інструментів розміщуються перед "мозком"?
+Before taking action, a person needs to perceive what limbs and tools are available. An infant doesn't first understand the rules of the world (Instructions), then learn to reach and grab — they first sense that they have hands and feet, then gradually understand rules through interaction with the environment. Similarly, an LLM needs to know what tools it can call (read files, write code, search, execute commands) before receiving task instructions, so it can accurately assess "what can I do" and "how should I do it" when processing the instructions.
 
-З точки зору кешування, розміщення Tools на першому місці — це технічний факт. Але з точки зору когнітивного дизайну цей порядок також логічний — **Tools — це руки і ноги, System Prompt — це мозок**.
+If reversed — first telling the model "your task is to refactor this module", then telling it "you have shell_command, apply_patch, and tool_search" — the model would lack critical capability boundary information when understanding the task, potentially producing unrealistic plans or overlooking available approaches.
 
-Перед тим як діяти, людина повинна усвідомити, які кінцівки та інструменти їй доступні. Немовля не спочатку розуміє правила світу (System), а потім вчиться хапати — воно спочатку відчуває, що має руки і ноги, а потім поступово розуміє правила через взаємодію з навколишнім середовищем. Аналогічно, LLM повинна знати, які інструменти може викликати (читання файлів, написання коду, пошук, виконання команд) до отримання інструкцій завдання (System Prompt), щоб точно оцінити "що я можу зробити" і "як мені це зробити" при обробці інструкцій.
+**Know what cards you hold before deciding how to play.** This is the cognitive logic behind Tools preceding Instructions.
 
-Якби порядок був зворотним — спочатку сказати моделі "твоє завдання — рефакторити цей модуль", потім "у тебе є інструменти Read, Edit, Bash" — моделі бракувало б критичної інформації про межі своїх можливостей при розумінні завдання, що могло б призвести до нереалістичних планів або пропуску доступних підходів.
+## Why Are MCP Tools Also in This Position?
 
-**Дізнайся, які карти на руках, перш ніж вирішувати, як грати.** Це когнітивна логіка розміщення Tools перед System.
+MCP (Model Context Protocol) tools, like built-in tools, are placed at the very front of the Tools area. Understanding MCP's position in the context helps evaluate its real benefits and costs.
 
-## Чому інструменти MCP теж знаходяться на цій позиції?
+### MCP Advantages
 
-Інструменти MCP (Model Context Protocol), як і вбудовані інструменти, розміщуються на самому початку області Tools. Розуміння позиції MCP в контексті допомагає оцінити його реальні переваги та витрати.
+- **Capability extension**: MCP lets models access external services (database queries, API calls, IDE operations, browser control, etc.), breaking beyond built-in tool boundaries
+- **Open ecosystem**: Anyone can implement an MCP server; the model gains new capabilities without retraining
+- **On-demand loading**: MCP servers can be selectively connected/disconnected based on task scenario, flexibly composing tool sets
 
-### Переваги MCP
+### MCP Costs
+- **Prefix bloat**: MCP tool Schemas are typically larger than built-in tools (containing detailed parameter descriptions, enums, etc.). Many MCP tools significantly increase the Tools area's token count, squeezing the context space available for Input
+- **Latency overhead**: MCP tool calls require cross-process communication (JSON-RPC over stdio/SSE), an order of magnitude slower than built-in function calls
+- **Stability risk**: MCP servers are external processes that may crash, timeout, or return unexpected formats, requiring additional error handling
 
-- **Розширення можливостей**: MCP дозволяє моделям звертатися до зовнішніх сервісів (запити до баз даних, API-виклики, операції IDE, керування браузером тощо), виходячи за межі вбудованих інструментів
-- **Відкрита екосистема**: Будь-хто може реалізувати MCP-сервер; модель отримує нові можливості без перенавчання
-- **Завантаження на вимогу**: MCP-сервери можна підключати/відключати вибірково залежно від завдання, гнучко складаючи набори інструментів
+### Practical Recommendations
 
-### Витрати MCP
+| Scenario | Recommendation |
+|----------|---------------|
+| Long conversations, high-frequency interaction | Minimize MCP tool count to keep requests smaller and easier to inspect |
+| Short tasks, one-off operations | Use MCP tools freely; overhead is usually limited |
+| Frequently adding/removing MCP servers | Each change reshapes the request; consider fixing the tool set |
+| Oversized Tool Schemas | Trim descriptions and enums to reduce prefix token footprint |
 
-- **Вбивця кешу**: JSON Schema кожного MCP-інструменту конкатенується на самий початок префіксу KV-Cache. Додавання або видалення одного MCP-інструменту = **весь кеш інвалідується з самого початку**. Часте підключення/відключення MCP-серверів різко знижує відсоток влучань у кеш
-- **Роздування префіксу**: Schemas MCP-інструментів зазвичай більші за вбудовані (детальні описи параметрів, перерахування тощо). Велика кількість MCP-інструментів значно збільшує кількість токенів в області Tools, скорочуючи простір контексту для Messages
-- **Накладні витрати на затримку**: Виклики MCP-інструментів потребують міжпроцесної комунікації (JSON-RPC через stdio/SSE), на порядок повільніше за виклики вбудованих функцій
-- **Ризик стабільності**: MCP-сервери — це зовнішні процеси, які можуть аварійно завершитись, спричинити таймаут або повернути неочікуваний формат, потребуючи додаткової обробки помилок
-
-### Практичні рекомендації
-
-| Сценарій | Рекомендація |
-|----------|-------------|
-| Довгі розмови, часта взаємодія | Мінімізувати кількість MCP-інструментів для захисту стабільності префіксу кешу |
-| Короткі завдання, разові операції | Вільно використовувати MCP-інструменти; вплив на кеш обмежений |
-| Часте додавання/видалення MCP-серверів | Кожна зміна викликає повну перебудову кешу; розглянути фіксацію набору інструментів |
-| Занадто великі Tool Schemas | Скоротити описи та enum для зменшення витрат токенів префіксу |
-
-У панелі Context cc-viewer інструменти MCP відображаються поряд із вбудованими інструментами в області Tools, даючи наочне уявлення про розмір Schema кожного інструменту та його внесок у префікс кешу.
+In CX Viewer's Context panel, MCP tools are displayed alongside built-in and dynamic tools in the Tools area, giving you a clear view of each tool's Schema size and contribution to request shape.

package/concepts/uk/TranslateContextPollution.md

@@ -2,7 +2,7 @@
 
 ## Передумови
 
-CC-Viewer містить вбудовану функцію перекладу (`POST /api/translate`), що працює на основі Anthropic Messages API. У ранній реалізації запити на переклад повторно використовували кешовані облікові дані автентифікації із сесії Claude Code — включаючи заголовки `x-api-key` та `authorization`. Це спричинило непомітну, але серйозну проблему: результати перекладу часто повертали нерелевантний вміст.
+CC-Viewer містить вбудовану функцію перекладу (`POST /api/translate`), що працює на основі Anthropic Messages API. У ранній реалізації запити на переклад повторно використовували кешовані облікові дані автентифікації із сесії Codex — включаючи заголовки `x-api-key` та `authorization`. Це спричинило непомітну, але серйозну проблему: результати перекладу часто повертали нерелевантний вміст.
 
 ## Кореневе причина
 
@@ -13,24 +13,24 @@ Anthropic API підтримує два методи автентифікаці
 | Метод | Заголовок | Типове джерело | Характеристики |
 |-------|-----------|----------------|----------------|
 | API-ключ | `x-api-key: sk-ant-...` | Змінна середовища / Console | Без стану, кожен запит незалежний |
-| OAuth-токен | `authorization: Bearer sessionToken` | Вхід за підпискою Claude Code | Прив'язаний до сесії, сервер підтримує асоціацію контексту |
+| OAuth-токен | `authorization: Bearer sessionToken` | Вхід за підпискою Codex | Прив'язаний до сесії, сервер підтримує асоціацію контексту |
 
 Ключова різниця: **API-ключі не зберігають стан** — кожен запит повністю незалежний; тоді як **OAuth-токени сесії зберігають стан** — сервер Anthropic асоціює запити з однаковим токеном з одним і тим самим контекстом сесії.
 
 ### Ланцюг забруднення
 
-Коли Claude Code використовує OAuth-вхід за підпискою, потік автентифікації виглядає так:
+Коли Codex використовує OAuth-вхід за підпискою, потік автентифікації виглядає так:
 
 ```
-Основна розмова Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+Основна розмова Codex ──(authorization: Bearer sessionToken)──→ Anthropic API
                                                                         ↑
 Запит перекладу CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
 ```
 
-Оскільки запити на переклад повторно використовували той самий токен сесії, сервер Anthropic може асоціювати запити на переклад із контекстом основної розмови Claude Code. Це призводить до:
+Оскільки запити на переклад повторно використовували той самий токен сесії, сервер Anthropic може асоціювати запити на переклад із контекстом основної розмови Codex. Це призводить до:
 
-1. **Результати перекладу під впливом контексту основної розмови**: Системний промпт запиту на переклад — «ви перекладач», але серверний контекст все ще містить історію розмов Claude Code, що потенційно може впливати на модель
-2. **Основна розмова порушується запитами на переклад**: Вміст запитів на переклад (фрагменти тексту UI) може бути впроваджений у контекст основної розмови, спричиняючи відхилення у відповідях Claude Code
+1. **Результати перекладу під впливом контексту основної розмови**: Системний промпт запиту на переклад — «ви перекладач», але серверний контекст все ще містить історію розмов Codex, що потенційно може впливати на модель
+2. **Основна розмова порушується запитами на переклад**: Вміст запитів на переклад (фрагменти тексту UI) може бути впроваджений у контекст основної розмови, спричиняючи відхилення у відповідях Codex
 3. **Непередбачувана поведінка**: Оскільки забруднення контексту — це поведінка на стороні сервера, клієнт не може її виявити або контролювати
 
 ## Отримані уроки
@@ -41,6 +41,6 @@ Anthropic API підтримує два методи автентифікаці
 ## Посилання
 
 - [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
-- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Codex Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
 - [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
-- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)
+- [Codex Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)

package/concepts/uk/UltraPlan.md

@@ -1,55 +1,55 @@
-# UltraPlan — Найкраща Машина Бажань
+# UltraPlan — The Ultimate Wishing Machine
 
-## Що таке UltraPlan
+## What is UltraPlan
 
-UltraPlan — це **локалізована реалізація** нативної команди `/ultraplan` Claude Code від cc-viewer. Він дозволяє використовувати повні можливості `/ultraplan` у вашому локальному середовищі **без необхідності запуску офіційного віддаленого сервісу Claude**, спрямовуючи Claude Code на виконання складних завдань планування та реалізації з використанням **мультиагентної співпраці**.
+UltraPlan is CX Viewer's **localized planning workflow** for Codex. It guides Codex through complex planning and implementation tasks using **multi-agent collaboration**.
 
-Порівняно зі звичайним режимом Plan або Agent Team, UltraPlan може:
-- Автоматично оцінювати складність завдання та обирати оптимальну стратегію планування
-- Розгортати кілька паралельних агентів для дослідження кодової бази з різних вимірів
-- Залучати зовнішні дослідження (webSearch) для отримання найкращих галузевих практик
-- Автоматично формувати команду Code Review після виконання плану для ревью коду
-- Створювати повний замкнений цикл **План → Виконання → Ревью → Виправлення**
+Compared to regular Plan mode or Agent Team, UltraPlan can:
+- Automatically assess task complexity and select the optimal planning strategy
+- Deploy multiple parallel agents to explore the codebase from different dimensions
+- Incorporate external research (`web_search`) for industry best practices
+- Automatically assemble a Code Review Team after plan execution for code review
+- Form a complete **Plan → Execute → Review → Fix** closed loop
 
 ---
 
-## Важливі зауваження
+## Important Notes
 
-### 1. UltraPlan не всемогутній
-UltraPlan — це потужніша машина бажань, але це не означає, що кожне бажання може бути здійснене. Він потужніший за Plan та Agent Team, але не може безпосередньо «заробити вам гроші». Враховуйте розумну гранулярність завдань — розбивайте великі цілі на виконувані завдання середнього розміру замість того, щоб намагатися досягти всього за один раз.
+### 1. UltraPlan Is Not Omnipotent
+UltraPlan is a more powerful wishing machine, but that doesn't mean every wish can be fulfilled. It's more powerful than Plan and Agent Team, but it can't directly "make you money." Consider reasonable task granularity — break large goals into executable medium-sized tasks rather than trying to accomplish everything in one shot.
 
-### 2. Наразі найефективніший для програмних проєктів
-Шаблони та робочі процеси UltraPlan глибоко оптимізовані для програмних проєктів. Інші сценарії (документація, аналіз даних тощо) можна спробувати, але, можливо, варто зачекати на адаптації в майбутніх версіях.
+### 2. Currently Most Effective for Programming Projects
+UltraPlan's templates and workflows are deeply optimized for programming projects. Other scenarios (documentation, data analysis, etc.) can be attempted, but you may want to wait for future version adaptations.
 
-### 3. Час виконання та вимоги до контекстного вікна
-- Успішний запуск UltraPlan зазвичай займає **30 хвилин або більше**
-- Вимагає, щоб MainAgent мав велике контекстне вікно (рекомендується модель Opus з контекстом 1M)
-- Якщо у вас лише модель на 200K, **обов'язково виконайте `/clear` контексту перед запуском**
-- Команда `/compact` Claude Code працює погано при недостатньому контекстному вікні — не допускайте вичерпання простору
-- Підтримання достатнього простору контексту є критично важливою передумовою для успішного виконання UltraPlan
+### 3. Execution Time and Context Window Requirements
+- A successful UltraPlan run typically takes **30 minutes or more**
+- Requires MainAgent to have a large enough context window for multi-agent findings and review output
+- If your active model has a smaller context window, **make sure to `/clear` context before running**
+- Compaction is less reliable when the context window is already nearly full — avoid running out of space
+- Maintaining sufficient context space is a critical prerequisite for successful UltraPlan execution
 
-Якщо у вас є запитання чи пропозиції щодо локалізованого UltraPlan, не соромтеся відкривати [Issues на GitHub](https://github.com/anthropics/claude-code/issues) для обговорення та співпраці.
+If you have any questions or suggestions about the localized UltraPlan workflow, open an issue in the CX Viewer project to discuss and collaborate.
 
 ---
 
-## Як це працює
+## How It Works
 
-UltraPlan пропонує два режими роботи:
+UltraPlan offers two operating modes:
 
-### Автоматичний режим
-Автоматично аналізує складність завдання (оцінка 4-12) та направляє до різних стратегій:
+### Auto Mode
+Automatically analyzes task complexity (score 4-12) and routes to different strategies:
 
-| Маршрут | Оцінка | Стратегія |
-|---------|--------|-----------|
-| Маршрут A | 4-6 | Легке планування з прямим дослідженням коду |
-| Маршрут B | 7-9 | Планування зі структурними діаграмами (Mermaid / ASCII) |
-| Маршрут C | 10-12 | Мультиагентне дослідження + замкнений цикл ревью |
+| Route | Score | Strategy |
+|-------|-------|----------|
+| Route A | 4-6 | Lightweight planning with direct code exploration |
+| Route B | 7-9 | Planning with structural diagrams (Mermaid / ASCII) |
+| Route C | 10-12 | Multi-agent exploration + review closed loop |
 
-### Примусовий режим
-Безпосередньо активує повний мультиагентний робочий процес Маршруту C:
-1. Розгортання до 5 паралельних агентів для одночасного дослідження кодової бази (архітектура, ідентифікація файлів, оцінка ризиків тощо)
-2. Опціональне розгортання дослідницького агента для вивчення галузевих рішень через webSearch
-3. Синтез усіх результатів агентів у детальний план реалізації
-4. Розгортання агента-рев'юера для ретельної перевірки плану з кількох точок зору
-5. Виконання плану після затвердження
-6. Автоматичне формування команди Code Review для перевірки якості коду після реалізації
+### Forced Mode
+Directly activates the full Route C multi-agent workflow:
+1. Deploy up to 5 parallel agents to explore the codebase simultaneously (architecture, file identification, risk assessment, etc.)
+2. Optionally deploy a research agent to investigate industry solutions via `web_search`
+3. Synthesize all agent findings into a detailed implementation plan
+4. Deploy a review agent to scrutinize the plan from multiple perspectives
+5. Execute the plan once approved
+6. Automatically assemble a Code Review Team to validate code quality after implementation

package/concepts/zh/BodyDiffJSON.md

@@ -2,7 +2,7 @@
 
 ## 背景
 
-Codex 的 MainAgent 采用全量上下文发送机制——每次请求都会携带完整的对话历史、system prompt、工具定义等内容。这意味着随着对话推进，请求体会越来越庞大，直接查看原始 Body 很难快速定位"这一轮到底新增了什么"。
+Codex 的 MainAgent 采用全量上下文发送机制。对于 OpenAI Responses API，每次请求都会携带完整的 `input`、`instructions`、工具定义等内容。这意味着随着对话推进，请求体会越来越庞大，直接查看原始 Body 很难快速定位"这一轮到底新增了什么"。
 
 Body Diff JSON 正是为了解决这个问题：它自动对比前后两个 MainAgent 请求的 body，提炼出增量部分，让你一眼看清本次请求实际新增的内容。
 
@@ -14,15 +14,15 @@ Body Diff JSON 正是为了解决这个问题：它自动对比前后两个 Main
    - 新增的字段：直接展示
    - 删除的字段：不显示（通常不影响理解）
    - 变更的字段：展示当前值
-   - `messages` 数组特殊处理：只展示新增的消息（因为正常对话是追加模式，前缀消息不变）
+   - `input` 数组特殊处理：只展示新增的输入项（因为正常对话是追加模式，前缀 input 不变）
 4. **请求体缩小检测**：如果当前请求体比上一个更小，说明发生了上下文截断或会话重置，此时会显示提示信息而非 diff
 
 ## 典型场景
 
 在一轮正常对话中，Body Diff JSON 通常只包含：
-- `messages`：新增的 1~2 条消息（用户的输入 + 上一轮助手的回复）
+- `input`：新增的 1~2 个输入项（用户的输入 + 上一轮助手的回复）
 
-如果你看到 diff 中出现了 `system`、`tools`、`model` 等字段的变更，说明本轮请求发生了配置变化，这往往也是缓存重建的原因。
+如果你看到 diff 中出现了 `instructions`、`tools`、`model` 等字段的变更，说明本轮请求发生了配置变化，这往往也是缓存重建的原因。
 
 ## 使用方式
 

package/concepts/zh/BodyFields.md

@@ -1,42 +1,39 @@
 # Request Body 字段说明
 
-Claude API `/v1/messages` 请求体的顶层字段说明。
+CX-Viewer 归一化后的 Codex 请求体字段说明。原始来源可能是 OpenAI Responses API、Codex app-server 通知或 Codex SDK 事件，CX-Viewer 会映射为统一的 viewer 结构。
 
 ## 字段列表
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| **model** | string | 使用的模型名称，如 `claude-opus-4-6`、`claude-sonnet-4-6` |
-| **messages** | array | 对话消息历史。每条消息包含 `role`（user/assistant）和 `content`（文本、图片、tool_use、tool_result 等 block 数组） |
-| **system** | array | System prompt。包含 Codex 的核心指令、工具使用说明、环境信息、CLAUDE.md 内容等。带 `cache_control` 的块会被 prompt caching |
-| **tools** | array | 可用工具定义列表。每个工具包含 `name`、`description` 和 `input_schema`（JSON Schema）。MainAgent 通常有 20+ 工具，SubAgent 只有少量 |
-| **metadata** | object | 请求元数据，通常包含 `user_id` 用于标识用户 |
+| **model** | string | Codex 选择的模型名称，例如 `gpt-*` 模型 |
+| **input** | string/array | OpenAI Responses API 的输入内容。Codex 通常使用数组形式，携带用户输入、助手历史、工具结果等上下文项 |
+| **instructions** | string/array | OpenAI Responses API 的指令内容。可能包含 Codex 核心指令、工具使用说明、环境信息和 `AGENTS.md` 项目指令 |
+| **tools** | array | 可用工具定义或精简工具描述。MainAgent 通常比 SubAgent 拥有更完整的工具集合 |
+| **metadata** | object | 请求元数据，例如 `thread_id`、`turn_id`、`cwd`、SDK/app-server 来源，以及 subAgent 的父线程信息 |
 | **max_tokens** | number | 模型单次回复的最大 token 数，如 `16000`、`64000` |
-| **thinking** | object | 扩展思考配置。`type: "enabled"` 开启思考模式，`budget_tokens` 控制思考 token 上限 |
-| **context_management** | object | 上下文管理配置。`truncation: "auto"` 允许 Codex 自动截断过长的消息历史 |
-| **output_config** | object | 输出配置，如 `format` 设置 |
-| **stream** | boolean | 是否启用流式响应。Codex 始终使用 `true` |
+| **reasoning_effort** | string | Codex 上报的推理强度 |
+| **reasoning_summary** | string | Codex 上报的推理摘要模式 |
+| **approval_policy** | string | 本轮 Codex 审批策略 |
+| **sandbox_policy** | object/string | 本轮沙箱策略（如果来源协议提供） |
+| **stream** | boolean | OpenAI Responses API 请求是否流式；app-server/SDK 条目会按流式 turn 归一化 |
 
-## messages 结构
+## input 结构
 
-每条消息的 `content` 是一个 block 数组，常见类型：
+`input` 为数组时，每个输入项通常包含 `role` 和 `content`。`content` 可以是 block 数组，常见类型：
 
 - **text**: 普通文本内容
 - **tool_use**: 模型调用工具（含 `name`、`input`）
 - **tool_result**: 工具执行结果（含 `tool_use_id`、`content`）
-- **image**: 图片内容（base64 或 URL）
+- **image/input_image/local_image**: 图片内容或本地图片引用
 - **thinking**: 模型的思考过程（扩展思考模式）
 
-## system 结构
+## instructions 结构
 
-system prompt 数组中通常包含：
+`instructions` 通常包含：
 
 1. **核心 agent 指令**（"You are Codex..."）
 2. **工具使用规范**
-3. **CLAUDE.md 内容**（项目级指令）
+3. **AGENTS.md 内容**（项目级指令）
 4. **技能提示**（skills reminder）
 5. **环境信息**（OS、shell、git 状态等）— 事实上 Codex 非常依赖 git。如果项目存在 git 仓库，Codex 能展现出对项目更好的理解能力，包括可以拉取远端的变更和 commit 记录来辅助分析
-
-带 `cache_control: { type: "ephemeral" }` 标记的块会被 Anthropic API 缓存 5 分钟，命中缓存时以 `cache_read_input_tokens` 计费（远低于 `input_tokens`）。
-
-> **注意**：对于 Codex 这类特殊客户端，Anthropic 服务端实际上并不完全依赖请求中的 `cache_control` 属性来决定缓存行为。服务端会对特定字段（如 system prompt、tools 定义）自动执行缓存策略，即使请求中未显式携带 `cache_control` 标记。因此，当你在请求体中没有看到该属性时不必疑惑——服务端已在幕后完成了缓存操作，只是未将此信息暴露给客户端。这是 Codex 与 Anthropic API 之间的一种默契。

package/concepts/zh/GlobalSettings.md

@@ -17,7 +17,7 @@
 | 配置项 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
-| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Codex 的 reasoning/thinking 块 |
 | 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
 | 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
 
@@ -75,20 +75,20 @@
 | 变量名 | 说明 |
 |--------|------|
 | `CXVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
-| `CXV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+| `CXV_EDITOR_PORT` | 服务端口，供 cxv-editor 文件编辑桥接 |
 
 ### 外部变量（读取）
 
 | 变量名 | 说明 |
 |--------|------|
-| `OPENAI_BASE_URL` | 自定义 Anthropic API 地址 |
+| `OPENAI_BASE_URL` | 自定义 OpenAI 兼容 API 地址 |
 | `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
 | `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
 
 ## 五、CLI 命令参数
 
 ```
-ccv [选项] [claude 参数...]
+cxv [选项] [codex 参数...]
 ```
 
 ### CX-Viewer 专有选项
@@ -100,49 +100,50 @@ ccv [选项] [claude 参数...]
 | `--help` / `-h` / `help` | 显示帮助信息 |
 | `--version` / `-v` | 显示版本号 |
 | `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
-| `--d` | `--dangerously-skip-permissions` 简写 |
-| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
-| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+| `--d` | `--dangerously-bypass-approvals-and-sandbox` 简写 |
+| `--ad` | 兼容旧配置的 CXV 侧 bypass 开关 |
+| `run` | 通过 CXV 包装运行命令（`cxv run -- codex ...`） |
 
-### Claude 透传参数（常用）
+### Codex 透传参数（常用）
 
 | 参数 | 说明 |
 |------|------|
-| `-c` / `--continue` | 继续上一次会话 |
-| `-r` / `--resume` | 恢复指定会话 |
-| `-p` / `--print` | 非交互式输出 |
+| `continue` | 恢复上一次会话（`codex resume --last`） |
+| `resume [session-id]` | 恢复指定会话 |
+| `exec [prompt]` | 非交互式 Codex 执行 |
 | `--model` | 指定模型 |
-| `--permission-mode` | 权限模式 |
-| `--system-prompt` | 自定义系统提示词 |
-| `--max-budget-usd` | 最大预算 |
+| `--search` | 启用实时搜索模式 |
+| `-C` / `--cd` | 指定工作目录 |
+| `--sandbox` | 指定沙箱模式 |
+| `--ask-for-approval` | 指定审批策略 |
 
 ## 六、Hook 配置
 
-CX-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+CX-Viewer 的 Codex 集成主要走本地 wrapper/proxy 路径。Hook bridge 只使用当前 Codex 工具名。
 
-### 1. AskUserQuestion 桥接
-- **匹配器**: `"AskUserQuestion"`
+### 1. request_user_input 桥接
+- **匹配器**: `"request_user_input"`
 - **命令**: `node <安装目录>/lib/ask-bridge.js`
-- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+- **作用**: 在 bridge 路径启用时，将工具/用户审批转发到 Web UI
 
 ### 2. 权限审批桥接
 - **匹配器**: `""` (空 = 匹配所有工具)
 - **命令**: `node <安装目录>/lib/perm-bridge.js`
-- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+- **作用**: `shell_command`、`apply_patch`、`web_search`、`image_generation` 等会变更文件或访问外部资源的工具需要 Web UI 审批，其余自动放行
 
 ## 七、Shell 集成
 
-CX-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+CX-Viewer 在 logger 模式下可向 `~/.zshrc`（或 `.bashrc`）注入 `codex()` 包装函数：
 
 ```bash
 # >>> CX-Viewer Auto-Inject >>>
-claude() { ... }
+codex() { ... }
 # <<< CX-Viewer Auto-Inject <<<
 ```
 
-所有 `claude` 命令自动通过 CX-Viewer 代理，实现日志捕获和 Web UI 功能。
+交互式 `codex` 命令会通过 CX-Viewer 实现日志捕获和 Web UI 功能；`codex --help`、`codex auth` 等 passthrough 命令仍直接执行。
 
-卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+卸载：`cxv --uninstall` 或手动删除标记之间的内容。
 
 ## 八、代理配置（Proxy Profile）
 
@@ -224,9 +225,6 @@ claude() { ... }
 
 | 键 | 说明 |
 |-----|------|
-| `cxv_cacheExpireAt` | 缓存倒计时到期时间 |
-| `cxv_cacheType` | 缓存类型标签 |
-| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
-| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
-| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cxv_viewMode` | 当前响应式视图模式覆盖 |
+| `cxv_fileExplorerOpen` | 文件浏览器面板开关 |
 | `cx-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/zh/MainAgent.md

@@ -2,22 +2,22 @@
 
 ## 定义
 
-MainAgent 是 Codex 在非 agent team 状态下的主干请求链路。每一次用户与 Codex 的交互，都会产生一系列 API 请求，其中 MainAgent 请求构成了核心对话链路——它们携带完整的 system prompt、工具定义和消息历史。
+MainAgent 是 Codex 在非 agent team 状态下的主干请求链路。每一次用户与 Codex 的交互，都会产生一系列 API 请求，其中 MainAgent 请求构成了核心对话链路。对于 OpenAI Responses API，MainAgent 会携带完整的 `instructions`、`tools` 和 `input`。
 
 ## 识别方式
 
 在 cx-viewer 中，MainAgent 通过 `req.mainAgent === true` 标识，由 `interceptor.js` 在请求捕获时自动标记。
 
 判定条件（满足全部）：
-- 请求体包含 `system` 字段（system prompt）
+- 请求体包含 `instructions` 字段
+- 请求体包含 `input` 数组
 - 请求体包含 `tools` 数组（工具定义）
-- system prompt 中包含 "Codex" 特征文本
+- `instructions` 中包含 "Codex" 特征文本
 
 ## 与 SubAgent 的区别
 
 | 特征 | MainAgent | SubAgent |
 |------|-----------|----------|
-| system prompt | 完整的 Codex 主 prompt | 精简的任务专用 prompt |
+| instructions | 完整的 Codex 主指令 | 精简的任务专用指令 |
 | tools 数组 | 包含全部可用工具 | 通常只包含任务所需的少量工具 |
-| 消息历史 | 累积完整对话上下文 | 仅包含子任务相关消息 |
-| 缓存行为 | 有 prompt caching（5 分钟 TTL） | 通常无缓存或缓存较小 |
+| input | 累积完整对话上下文 | 仅包含子任务相关输入 |