qgraphflow 0.0.6 → 0.0.7

package/docs/readme/README.ru.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# QGraphFlow
+<h1><picture><source media="(prefers-color-scheme: dark)" srcset="../images/brand/qgraphflow-lockup-dark.svg"><img src="../images/brand/qgraphflow-lockup-light.svg" alt="QGraphFlow" height="64"></picture></h1>
 
 ### Превратите сложный код в диаграммы для исследования.
 
@@ -10,17 +10,25 @@
 
 [English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
 
-[Онлайн-демо](https://supermax92.github.io/qgraphflow/) · [Установка для клиентов](#установка) · [Сообщить о проблеме](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
+[Онлайн-демо](https://supermax92.github.io/qgraphflow/) · [Первые шаги](#первые-шаги) · [Установка для клиентов](#установка) · [Сообщить о проблеме](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
 
 </div>
 
-![Архитектура, последовательность и ER-диаграмма примера agent-desk, по 1,5 секунды на вид](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ru.hero.gif)
-
-*Девять типов: архитектура, блок-схема, последовательность, ER, развёртывание, классы, состояния, варианты использования и поток данных.*
+*Поддерживаются одиннадцать типов диаграмм: архитектура возможностей платформы, архитектура инженерных слоёв, архитектура связей компонентов, блок-схема, последовательность, ER, развёртывание, классы, состояния, варианты использования и поток данных.*
 
 QGraphFlow создаёт интерактивные диаграммы программных систем из кода, схем данных, конфигурации и требований. Основания связей можно проверить, а результат — передать как автономный HTML.
 
-**Чем отличается:** девять типов диаграмм в одном навыке, источник для каждой связи, автоматическая раскладка, редактирование прямо на странице и никаких сетевых запросов ни от скриптов плагина, ни от самого Viewer.
+**Чем отличается:** одиннадцать типов диаграмм в одном навыке, тип доказательства для каждой связи и строка кода за каждой связью, подтверждённой кодом, автоматическая раскладка, редактирование прямо на странице и никаких сетевых запросов ни от скриптов плагина, ни от самого Viewer.
+
+![Интерактивная демонстрация нескольких видов Jeepay: архитектура связей компонентов, последовательность и ER](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
+
+На примере реального исходного кода Jeepay переключайтесь между архитектурой связей компонентов, диаграммой последовательности и ER, изучая компоненты и связи вызовов. [Посмотреть GIF в исходном размере](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
+
+**Демонстрация сложной диаграммы последовательности**
+
+![Пошаговое рисование сложной диаграммы последовательности: участники, линии жизни, сообщения, полосы активации и вложенные комбинированные фрагменты](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
+
+Вымышленный сценарий электронной торговли содержит 9 участников, 29 сообщений и 6 комбинированных фрагментов: повторные попытки резервирования, вложенные ветви, параллельную обработку, компенсацию сбоев и асинхронные обратные вызовы. Анимация постепенно показывает готовую диаграмму, раскрывая её структуру и детали. [Посмотреть GIF в исходном размере](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
 
 ```bash
 npx skills add supermax92/qgraphflow
@@ -30,21 +38,67 @@ npx skills add supermax92/qgraphflow
 
 - **Исследование:** поиск, масштабирование и перемещение холста; назначение компонентов, входящие и исходящие связи.
 
-  ![Исследование: поиск refund, переход к узлу «Инструменты заказов», отдаление до оркестратора выше и базы заказов с отслеживанием доставки ниже, затем перемещение холста](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ru.explore.gif)
-
 - **Проверка:** файлы, строки, символы и явно обозначенная неопределённость в узлах и связях.
 
-  ![Проверка: карточка с src/gateway/chat-gateway.js:5-19, панель деталей с символом и фактами, затем связь POST /chat с пометкой inference](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ru.verify.gif)
-
 - **Редактирование:** разблокировка расположения, изменение текста и перемещение элементов; сброс при необходимости.
 
-  ![Редактирование: разблокировка расположения, переименование «Провайдер LLM» в «LLM-шлюз», перетаскивание узла вместе со связями, затем сброс](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ru.edit.gif)
-
 - **Обмен:** автономный HTML или экспорт всей диаграммы в SVG / PNG.
 
-  ![Обмен: открытие автономного HTML, экспорт PNG из меню «Ещё», затем сам экспортированный файл](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ru.share.gif)
+Основанный на реальном коде [корпус Jeepay](../../examples/jeepay) содержит все одиннадцать видов, используемых CI и онлайн-демонстрацией.
+
+## Первые шаги
+
+После установки откройте свой рабочий проект в клиенте и выберите навык `q-flow`. Примеры используют `/q-flow` в Claude Code; в Codex используйте пункт `$q-flow` или `$qgraphflow:q-flow`, который действительно предлагает ваш клиент. Ещё не установили? Сначала прочитайте раздел [Установка](#установка).
+
+### 1. Пустой ввод: Не знаете, с чего начать
+
+Вызовите навык без дополнительных требований:
+
+```text
+/q-flow
+```
+
+Навык поможет выбрать часть для анализа и вопрос, на который должна ответить диаграмма. Рисование начнётся, когда необходимая информация будет ясна.
+
+### 2. Вопрос о возможностях: Узнать, что можно нарисовать
+
+```text
+/q-flow Какие типы диаграмм ты можешь рисовать? На какие вопросы отвечает каждый тип? Я только что принял проект; сначала расскажи о своих возможностях и предложи, с чего начать.
+```
+
+Сначала узнайте назначение одиннадцати типов диаграмм, затем решите, что изучать: структуру проекта, порядок вызовов, связи данных или что-то другое.
+
+### 3. Неопределённый ввод: Есть только общая цель
+
+```text
+/q-flow Помоги нарисовать этот проект. Я хочу как можно быстрее его понять.
+```
+
+Не нужно заранее указывать тип диаграммы. Навык определит подходящий вид по проекту и вашей цели и задаст вопросы, если необходимой информации не хватает.
+
+### 4. Точный ввод: Задать границы и запросить детали рисунка
+
+Замените названия и шаги ниже процессами, которые действительно есть в вашем проекте:
+
+```text
+/q-flow Проанализируй создание заказа в текущем проекте и создай диаграмму последовательности на китайском языке.
+Включи точку входа запроса, расчёт цены, резервирование запасов, авторизацию платежа и сохранение заказа.
+Сохрани синхронные вызовы, асинхронные сообщения, парные возвраты, полосы активации, условные ветви, повторные попытки и компенсацию сбоев, которые действительно есть в исходниках. Не опускай детали ради краткости.
+Укажи исходные файлы и номера строк компонентов и вызовов и сохрани результат в docs/qgraphflow/order-sequence/.
+```
+
+Чётко задайте предмет, вопрос, уровень детализации и место вывода, чтобы начать сразу. Диаграмма сохраняет только факты, подтверждённые доказательствами.
+
+### 5. Дальнейшее уточнение: Раскрыть часть предыдущей диаграммы
+
+После получения результата продолжите в том же разговоре:
+
+```text
+/q-flow Раскрой резервирование запасов из предыдущей диаграммы последовательности отдельной блок-схемой на китайском языке.
+Покажи все ветви проверки запасов, успешного резервирования, повторяемых сбоев, предела повторных попыток и освобождения запасов. Следуй исходному коду и не добавляй отсутствующих в нём шагов.
+```
 
-Верхняя анимация показывает архитектуру, последовательность и ER-диаграмму по 1,5 секунды (цикл 4,5 секунды); четыре анимации возможностей длятся 6,5–8,5 секунды. Все они записаны в собранном из исходников Viewer на [примере agent-desk](../../examples/showcase/agent-desk) — вымышленный бизнес, настоящий код — с русским текстом диаграмм и интерфейса. Они размещены как [ассеты релиза showcase-v2](https://github.com/supermax92/qgraphflow/releases/tag/showcase-v2) и не входят ни в историю Git, ни в пакет плагина, поэтому для просмотра нужна сеть; сгенерированный HTML диаграммы работает автономно.
+Сначала рассмотрите целое, затем углубитесь в один шаг. Можно также запросить дополнительные детали существующей диаграммы или проверить её связи.
 
 ## Установка
 
@@ -62,9 +116,18 @@ npx skills add supermax92/qgraphflow
 
 ### 1. Скачайте плагин
 
-Скачайте [qgraphflow-0.0.6.zip](https://github.com/supermax92/qgraphflow/releases/download/v0.0.6/qgraphflow-0.0.6.zip) и распакуйте в отдельный каталог, сохранив скрытые файлы.
+Получите плагин с npmjs.com — без учётной записи, входа и токена. Создайте отдельный каталог вне своего рабочего проекта:
+
+```bash
+mkdir qgraphflow-install
+cd qgraphflow-install
+npm install qgraphflow --ignore-scripts
+cd node_modules/qgraphflow
+```
+
+Теперь вы в корневом каталоге плагина. **Загрузка через npm не устанавливает плагин в клиент автоматически** — перейдите к шагу 2. Пакет также даёт команду `qgraphflow`, которая используется в разделе [Синхронизация диаграмм с кодом](#синхронизация-диаграмм-с-кодом).
 
-Все команды ниже выполняйте из **корневого каталога распакованного плагина, содержащего `skills/`**.
+Все команды ниже выполняйте из **корневого каталога плагина, содержащего `skills/`**.
 
 ### 2. Установите в свой клиент
 
@@ -81,17 +144,8 @@ codex plugin add qgraphflow@supermax92
 
 #### Claude Code
 
-Установите напрямую с GitHub без скачивания ZIP:
-
 ```bash
-claude plugin marketplace add supermax92/qgraphflow
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-Или из корня распакованного плагина:
-
-```bash
-claude plugin marketplace add .
+claude plugin marketplace add ./
 claude plugin install qgraphflow@supermax92 --scope user
 ```
 
@@ -107,9 +161,9 @@ qodercli plugins install .
 
 #### Qoder Desktop
 
-**Рекомендуется:** Откройте **Settings → Plugins → Marketplace**, найдите **代码图谱可视化** или **qgraphflow** и установите плагин. Начните новый сеанс и выберите `q-flow`. Скачивать ZIP или собирать исходный код не требуется.
+**Рекомендуется:** Откройте **Settings → Plugins → Marketplace**, найдите **QGraphFlow** или **代码图谱可视化** и установите плагин. Начните новый сеанс и выберите `q-flow`.
 
-Для локальной установки выполните шаг 1, затем откройте **Settings → Plugins → Custom → Import** и импортируйте весь корневой каталог распакованного плагина. Начните новый сеанс и выберите `q-flow`.
+Для локальной установки выполните шаг 1, затем откройте **Settings → Plugins → Custom → Import** и импортируйте весь корневой каталог плагина. Начните новый сеанс и выберите `q-flow`.
 
 #### Cursor
 
@@ -123,27 +177,11 @@ qodercli plugins install .
 
 ### 3. Начните работу
 
-Откройте свой проект в клиенте, начните новую сессию и выберите навык. Опишите задачу по примерам в разделе [Быстрый старт](#быстрый-старт) ниже. Откройте полученный HTML в браузере.
-
-<details>
-<summary>Другой способ установки: npm</summary>
-
-Вместо ZIP можно получить плагин с npmjs.com — без учётной записи, входа и токена. Создайте отдельный каталог вне своего рабочего проекта:
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-Теперь вы в корневом каталоге плагина. Продолжите установку для своего клиента по шагам выше. **Загрузка через npm не устанавливает плагин в клиент автоматически.** Пакет также даёт команду `qgraphflow`, которая используется в разделе [Синхронизация диаграмм с кодом](#синхронизация-диаграмм-с-кодом).
-
-</details>
+Откройте свой рабочий проект в клиенте, начните новую сессию и выберите навык. Опишите требования по примерам в разделе [Первые шаги](#первые-шаги). После генерации откройте выходной HTML в браузере.
 
 Хотите собрать самостоятельно? См. [инструкции по сборке из исходников](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally).
 
-## Быстрый старт
+## Быстрое использование
 
 Примеры используют `$qgraphflow:q-flow` в Codex. Если клиент показывает `$q-flow`, выберите этот пункт. Для других клиентов используйте способ вызова навыка, указанный выше.
 
@@ -158,7 +196,7 @@ $qgraphflow:q-flow
 ### Пример 1: Понять архитектуру проекта
 
 ```text
-$qgraphflow:q-flow Проанализируй текущий проект и создай диаграмму архитектуры на русском языке: обязанности модулей, зависимости и границы системы.
+$qgraphflow:q-flow Проанализируй текущий проект и создай диаграмму архитектуры на китайском языке: обязанности модулей, зависимости и границы системы.
 ```
 
 Подходит для первого знакомства с общей структурой проекта.
@@ -166,13 +204,13 @@ $qgraphflow:q-flow Проанализируй текущий проект и с
 ### Пример 2: Проследить бизнес-процесс
 
 ```text
-$qgraphflow:q-flow Проанализируй создание заказа и создай диаграмму последовательности на русском языке: расчёт цены, резерв запасов, оплата и сохранение заказа, включая ветки сбоев.
+$qgraphflow:q-flow Проанализируй создание заказа и создай диаграмму последовательности на китайском языке: расчёт цены, резерв запасов, оплата и сохранение заказа, включая ветки сбоев.
 ```
 
 Замените создание заказа и его шаги реальным процессом проекта. Продолжите в том же разговоре:
 
 ```text
-$qgraphflow:q-flow Подробно раскрой резерв запасов из предыдущей диаграммы отдельной блок-схемой на русском языке с обработкой успеха и сбоев.
+$qgraphflow:q-flow Подробно раскрой резерв запасов из предыдущей диаграммы отдельной блок-схемой на китайском языке с обработкой успеха и сбоев.
 ```
 
 По умолчанию результаты находятся в `docs/qgraphflow/`. Откройте `index.html` для исследования, редактирования и экспорта; `graph.json` хранит данные графа. Каждый вид также записывается как SVG (`diagram.svg`, а для нескольких видов — `diagram-<n>-<type>.svg`), который можно встроить как изображение в README, pull request или вики.
@@ -180,26 +218,23 @@ $qgraphflow:q-flow Подробно раскрой резерв запасов
 После правок на странице команда **Ещё → Сохранить изменения** в Chrome или Edge перезаписывает страницу, `graph.json` и SVG на месте, когда вы один раз выберете каталог диаграммы. Другие браузеры сохраняют только `graph.json`: положите его в этот каталог и пересоздайте страницу и SVG командой `npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force`.
 
 <details>
-<summary>Запустить торговый пример с девятью видами вручную</summary>
+<summary>Запустить пример Jeepay с одиннадцатью видами на основе исходного кода</summary>
 
-Команды ниже запускают пример из репозитория. Для использования установленного плагина клонировать репозиторий не нужно. Подготовьте Node.js 22 или новее:
+Выберите локальную копию исходников Jeepay для проверки доказательств:
 
 ```bash
-git clone https://github.com/supermax92/qgraphflow.git
-cd qgraphflow
-node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.ru.graph.json
-node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.ru.graph.json output/ecommerce-ru
+export JEEPAY_REPO_ROOT="<local Jeepay repository root>"
+node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
+node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
 ```
 
-Откройте `output/ecommerce-ru/index.html` в браузере; девять SVG лежат рядом. Переключайтесь через **Типы диаграмм** в верхней панели: сохранённые тексты и позиции сохраняются для каждого вида. **Ещё → Сохранить изменения** сохраняет все виды, как описано выше. Те же страницы есть в [онлайн-демо](https://supermax92.github.io/qgraphflow/).
-
-Готовому Viewer не нужны дополнительные зависимости, ключ API или серверная служба. Сбор оснований и создание графов с помощью ИИ используют модельный сервис выбранного клиента.
+Откройте `output/jeepay/index.html`; одиннадцать SVG находятся в том же каталоге. Версия исходников и процедура обновления описаны в [README корпуса](../../examples/jeepay).
 
 </details>
 
 ## Синхронизация диаграмм с кодом
 
-Диаграмма, созданная с указанием корня репозитория, запоминает, где определён каждый компонент. Проверка с `--repo-root` завершается ошибкой, если записанного файла больше нет, диапазон строк не помещается в файл или записанный символ ушёл из своих строк; в сообщении указано, в каких строках символ находится теперь. Добавьте эту задачу в CI — ей не нужны сборка, вход или токен:
+Диаграмма, созданная с указанием корня репозитория, запоминает, где определён каждый компонент, и строку за каждой связью, подтверждённой кодом (вызов, внешний ключ). Проверка с `--repo-root` завершается ошибкой, если записанного файла больше нет, диапазон строк не помещается в файл или записанный символ ушёл из своих строк; в сообщении указано, в каких строках символ находится теперь. Добавьте эту задачу в CI — ей не нужны сборка, вход или токен:
 
 ```yaml
 name: Diagrams
@@ -227,19 +262,21 @@ $qgraphflow:q-flow CI сообщает, что диаграмма docs/qgraphflo
 
 Навык переносит якоря, символ которых встречается в файле один раз, исправляет только якоря с оставшимися ошибками и пересоздаёт страницу и SVG, сохраняя ваши позиции и тексты. Заново диаграмму он не рисует.
 
-## На какие вопросы отвечают девять видов
+## На какие вопросы отвечает каждый из одиннадцати типов диаграмм
 
 | Вид · PNG | Главный вопрос | Область примера |
 | --- | --- | --- |
-| Архитектура | Какие зоны ответственности взаимодействуют? | Каналы, покупка, цены, риски, запасы, оплата, заказы, события и доставка |
-| Блок-схема | Где процесс ветвится и сходится? | Нехватка запасов, отказ по риску, компенсация оплаты и успешная фиксация |
-| Последовательность | Каков порядок вызовов и ответов? | Успешная покупка и асинхронный OrderPaid |
-| ER | Как связаны основные данные? | Корзина, заказы, позиции, платежи, резервы и посылки |
-| Развёртывание | Где работают и как соединены единицы исполнения? | Периметр, Kubernetes, данные, платежи и логистические сети |
-| Классы | Как зависят объекты домена и контракты? | Сервис покупки, Order и четыре порта |
-| Состояния | Какие события и условия продвигают заказ? | Оплата, доставка, отмена, возврат денег и закрытие |
-| Варианты использования | Что может каждый участник? | Покупатель, продавец, склад и поддержка |
-| Поток данных | Как данные преобразуются и сохраняются? | Корзина, решения, события, склад и подтверждения доставки |
+| Архитектура возможностей платформы | Какие возможности есть у платформы? | Зоны возможностей и матрицы |
+| Архитектура инженерных слоёв | Как организован код проекта? | Инженерные слои и общая поддержка |
+| Архитектура связей компонентов | Какие границы ответственности взаимодействуют в системе? | Каналы, оркестрация транзакций, цены, риски, запасы, платежи, заказы, события и исполнение заказов |
+| Блок-схема | Как ветвится и сходится каждая точка решения? | Нехватка запасов, отказ по риску, компенсация сбоя оплаты и успешная фиксация |
+| Последовательность | В каком порядке запрос выполняет вызовы и получает возвраты? | Основной путь успешной покупки и асинхронный OrderPaid |
+| ER | Как связаны основные данные? | Корзина, заказы, позиции, платежи, резервы запасов и посылки |
+| Развёртывание | Где размещены единицы исполнения и как они соединены? | Периметр, Kubernetes, сервисы данных, платежи и складские/логистические сети |
+| Классы | Как зависят объекты домена и контракты кода? | Прикладной сервис Checkout, Order и четыре порта |
+| Состояния | Какие события и охранные условия продвигают заказ? | Оплата, исполнение, отмена, возврат денег и закрытие |
+| Варианты использования | Какие возможности есть у каждого участника? | Покупатель, продавец, склад и поддержка клиентов |
+| Поток данных | Через какие преобразования и хранилища проходят данные? | Корзина, решения по транзакциям, события заказов, склад/логистика и подтверждения доставки |
 
 Это концептуальная демонстрация QGraphFlow, а не модель конкретного торгового репозитория. Пример `graph.json` не выдумывает пути к коду и обозначает основания связей как `inference`. Диаграммы реальных проектов требуют прослеживаемых исходников, DDL, конфигурации, тестов и согласованных требований.
 
@@ -253,10 +290,22 @@ node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
 
 Нужны Node.js 22 или новее, npm, tar, zip и unzip. В сообщении о проблеме приложите минимальный граф без конфиденциальных данных, версии клиента и браузера и шаги воспроизведения.
 
-Справочная документация (на английском): [Источники оснований](../../skills/q-flow/references/evidence-sources.md) · [Формат графов](../../skills/q-flow/references/graph-schema.md) · [Уточнение запроса](../../skills/q-flow/references/guided-intake.md) · [Разработка Viewer](../../skills/q-flow/references/viewer-development.md) · [Композиция диаграмм](../../skills/q-flow/references/visual-contract.md)
+Справочная документация (на английском): [Источники оснований](../../skills/q-flow/references/evidence-sources.md) · [Формат графов](../../skills/q-flow/references/graph-schema.md) · [Уточнение запроса](../../skills/q-flow/references/guided-intake.md) · [Разработка и приёмка Viewer](../../skills/q-flow/references/viewer-development.md) · [Композиция диаграмм](../../skills/q-flow/references/visual-contract.md)
 
 ## Лицензия и принадлежность
 
 [MIT](../../LICENSE) · [Уведомления третьих сторон](../../THIRD_PARTY_NOTICES.md)
 
-QGraphFlow — независимый проект под лицензией MIT. Сценарии в этом документе являются концептуальными и не представляют производственную архитектуру какой-либо компании; связь, спонсорство или одобрение не подразумеваются.
+QGraphFlow — независимый проект под лицензией MIT. Сценарии в этом документе являются концептуальными примерами и не представляют производственную архитектуру какой-либо реальной компании.
+
+## Обзоры архитектуры
+
+Архитектура теперь включает связи компонентов, возможности платформы и инженерные слои. Опишите предмет и вопрос; навык выберет шаблон. Запрошенные коллекции могут содержать несколько архитектурных видов с независимыми правками.
+
+```text
+$qgraphflow:q-flow Проанализируй возможности платформы и способы бизнес-интеграции текущего проекта и создай обзор возможностей платформы на китайском языке.
+$qgraphflow:q-flow Проанализируй организацию текущего проекта и слои компонентов и создай китайские обзоры всего проекта и среза одного компонента.
+$qgraphflow:q-flow Создай обзор возможностей платформы этого проекта на английском языке и покажи, как интегрируются прикладные модули.
+```
+
+См. [examples/jeepay](../../examples/jeepay) для архитектурных видов платформы, инженерной организации и связей компонентов на основе реального кода. Разблокируйте обзор, чтобы менять порядок карточек в слое или редактировать текст. Сохранение удерживает все виды; сброс восстанавливает только текущий.

package/docs/readme/README.zh-CN.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# QGraphFlow
+<h1><picture><source media="(prefers-color-scheme: dark)" srcset="../images/brand/qgraphflow-lockup-dark.svg"><img src="../images/brand/qgraphflow-lockup-light.svg" alt="QGraphFlow" height="64"></picture></h1>
 
 ### 把复杂代码，变成可以探索的图。
 
@@ -10,17 +10,25 @@
 
 [English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
 
-[在线演示](https://supermax92.github.io/qgraphflow/) · [客户端安装](#安装指南) · [反馈问题](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
+[在线演示](https://supermax92.github.io/qgraphflow/) · [快速入门](#快速入门) · [客户端安装](#安装指南) · [反馈问题](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
 
 </div>
 
-![agent-desk 示例的架构图、时序图与 ER 图，每类 1.5 秒](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.zh-CN.hero.gif)
-
-*支持九类图：【架构图、流程图、时序图、ER 图、部署图、类图、状态图、用例图、数据流图】*
+*支持十一类图：【平台能力架构图、工程分层架构图、组件关系架构图、流程图、时序图、ER 图、部署图、类图、状态图、用例图、数据流图】*
 
 QGraphFlow 从源码、数据结构、配置和需求生成交互式软件图，让关系有据可查，并将结果交付为可分享的离线 HTML。
 
-**差异在哪：** 一个技能覆盖九类图，每条关系都标明出处，自动布局，能直接在页面里编辑，插件脚本和 Viewer 本身不发任何网络请求。
+**差异在哪：** 一个技能覆盖十一类图，每条关系都标明证据类别，有代码支撑的关系还记录对应的源码行，自动布局，能直接在页面里编辑，插件脚本和 Viewer 本身不发任何网络请求。
+
+![Jeepay 多视图交互演示：组件关系架构图、时序图与 ER 图](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.zh-CN.hero.gif)
+
+以 Jeepay 真实源码为例，在组件关系架构图、时序图与 ER 图之间切换，探索组件与调用关系。[查看原尺寸 GIF](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.zh-CN.hero.gif)
+
+**复杂时序图展示**
+
+![复杂时序图逐步绘制：参与者、生命线、消息、激活条与嵌套组合片段](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.zh-CN.sequence-drawing.gif)
+
+虚构电商场景包含 9 个参与者、29 条消息和 6 个组合片段，覆盖库存重试、嵌套分支、并行处理、失败补偿与异步回调。动画逐步呈现已生成的图形，展示复杂时序图的结构与细节。[查看原尺寸 GIF](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.zh-CN.sequence-drawing.gif)
 
 ```bash
 npx skills add supermax92/qgraphflow
@@ -30,21 +38,67 @@ npx skills add supermax92/qgraphflow
 
 - **探索：** 搜索定位、缩放和平移画布，查看组件职责与上下游关系。
 
-  ![探索：搜索 refund 定位到订单工具集，拉远查看上游的智能体编排器与下游的订单库、物流查询平台，再平移画布](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.zh-CN.explore.gif)
-
 - **核验：** 从节点或连线查看详情，核对源码文件、行号、符号和明确标注的不确定性。
 
-  ![核验：速览卡显示 src/gateway/chat-gateway.js:5-19，详情栏显示符号与证据事实，再查看标为 inference 的 POST /chat 连线](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.zh-CN.verify.gif)
-
 - **编辑：** 解锁后修改文字、移动元素；不满意时一键重置。
 
-  ![编辑：解除布局锁定，把 LLM 服务商改名为 LLM 网关，拖动节点带动连线，最后一键重置](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.zh-CN.edit.gif)
-
 - **分享：** 打开离线 HTML，或将完整图导出为 SVG / PNG。
 
-  ![分享：打开离线 HTML，从「更多」导出 PNG，最后展示导出的文件本身](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.zh-CN.share.gif)
+The real-source [Jeepay corpus](../../examples/jeepay) contains all eleven views used by CI and the live demo.
+
+## 快速入门
 
-顶部动图依次展示架构图、时序图与 ER 图，每类 1.5 秒，完整循环 4.5 秒；下方四张能力动图各 6.5–8.5 秒。全部动图用源码构建的 Viewer 录制自 [agent-desk 示例](../../examples/showcase/agent-desk)（虚构业务、真实代码），图中文字与界面均为中文。它们作为 [showcase-v2 Release 附件](https://github.com/supermax92/qgraphflow/releases/tag/showcase-v2)托管，不进入 Git 历史与插件包，查看需要联网；生成的图形 HTML 本身可离线使用。
+安装后，在客户端打开你的业务项目，选择 `q-flow` 技能。以下以 Claude Code 的 `/q-flow` 为例；Codex 中使用客户端实际提供的 `$q-flow` 或 `$qgraphflow:q-flow` 入口。还未安装？先看[安装指南](#安装指南)。
+
+### 1. 空白输入：不知道从哪里开始
+
+只调用技能，不附加需求：
+
+```text
+/q-flow
+```
+
+技能会引导你选择要分析的部分，以及希望图回答的问题；必要信息明确后开始绘图。
+
+### 2. 询问能力：先了解能画什么
+
+```text
+/q-flow 你能绘制哪些类型的图？每类图适合回答什么问题？我刚接手一个项目，请先介绍能力并建议一个起点。
+```
+
+先了解十一类图的用途，再决定看项目结构、调用顺序、数据关系还是其他内容。
+
+### 3. 模糊输入：只有一个大致目标
+
+```text
+/q-flow 帮我画一下这个项目，我想尽快看懂它。
+```
+
+不用先指定图类型。技能会根据项目和你的目标确定合适的视图，缺少必要信息时再追问。
+
+### 4. 精准输入：明确范围并要求绘制细节
+
+将下面的业务名称和步骤替换成项目中实际存在的流程：
+
+```text
+/q-flow 分析当前项目的订单创建流程，生成中文时序图。
+覆盖请求入口、价格计算、库存预占、支付授权和订单落库。
+保留源码中实际存在的同步调用、异步消息、成对返回、激活条、条件分支、重试和失败补偿，不要为了简洁省略细节。
+标明组件与调用的源码文件和行号，将结果保存到 docs/qgraphflow/order-sequence/。
+```
+
+把对象、问题、详细程度和输出位置说清楚，就能直接开始；图中只保留有证据支持的事实。
+
+### 5. 继续细化：展开上一张图的局部
+
+在生成结果后，于同一对话中继续：
+
+```text
+/q-flow 展开上一张时序图中的库存预占步骤，单独生成中文流程图。
+完整展示库存校验、预占成功、可重试失败、重试上限和释放库存的分支，以源码为准，不添加代码中没有的步骤。
+```
+
+先看整体，再深入一个步骤；也可以继续要求补充已有图的细节或核验其中的关系。
 
 ## 安装指南
 
@@ -62,9 +116,18 @@ npx skills add supermax92/qgraphflow
 
 ### 1. 下载插件
 
-下载 [qgraphflow-0.0.6.zip](https://github.com/supermax92/qgraphflow/releases/download/v0.0.6/qgraphflow-0.0.6.zip)，解压到独立目录，保留隐藏文件。
+从 npmjs.com 获取插件，无需账号、登录或令牌。在业务项目之外创建独立目录：
+
+```bash
+mkdir qgraphflow-install
+cd qgraphflow-install
+npm install qgraphflow --ignore-scripts
+cd node_modules/qgraphflow
+```
+
+此时已进入插件根目录。**npm 下载不会自动完成客户端安装**，请继续第 2 步。这个包还提供 `qgraphflow` 命令，[让图和代码保持同步](#让图和代码保持同步)一节会用到。
 
-以下终端命令均在**解压后包含 `skills/` 的插件根目录**执行。
+以下终端命令均在**包含 `skills/` 的插件根目录**执行。
 
 ### 2. 选择客户端安装
 
@@ -81,17 +144,8 @@ codex plugin add qgraphflow@supermax92
 
 #### Claude Code
 
-直接从 GitHub 安装，无需下载 ZIP：
-
 ```bash
-claude plugin marketplace add supermax92/qgraphflow
-claude plugin install qgraphflow@supermax92 --scope user
-```
-
-或在解压后的插件根目录执行：
-
-```bash
-claude plugin marketplace add .
+claude plugin marketplace add ./
 claude plugin install qgraphflow@supermax92 --scope user
 ```
 
@@ -107,9 +161,9 @@ qodercli plugins install .
 
 #### Qoder Desktop
 
-**推荐：**打开 **Settings → Plugins → Marketplace**，搜索 **代码图谱可视化** 或 **qgraphflow**，安装插件。新建会话，选择 `q-flow`。无需下载 ZIP 或构建源码。
+**推荐：**打开 **Settings → Plugins → Marketplace**，搜索 **QGraphFlow** 或 **代码图谱可视化**，安装插件。新建会话，选择 `q-flow`。
 
-如需本地安装，先完成第 1 步，再打开 **Settings → Plugins → Custom → Import**，导入解压后的完整插件根目录。新建会话，选择 `q-flow`。
+如需本地安装，先完成第 1 步，再打开 **Settings → Plugins → Custom → Import**，导入完整的插件根目录。新建会话，选择 `q-flow`。
 
 #### Cursor
 
@@ -123,23 +177,7 @@ qodercli plugins install .
 
 ### 3. 开始使用
 
-在客户端打开你的业务项目，新建会话并选择技能，按下方[快速使用](#快速使用)中的示例描述需求。生成后，用浏览器打开输出的 HTML。
-
-<details>
-<summary>其他安装方式：npm</summary>
-
-不使用 ZIP 时，也可以从 npmjs.com 获取插件，无需账号、登录或令牌。在业务项目之外创建独立目录：
-
-```bash
-mkdir qgraphflow-install
-cd qgraphflow-install
-npm install qgraphflow --ignore-scripts
-cd node_modules/qgraphflow
-```
-
-此时已进入插件根目录，继续执行上面的客户端安装步骤。**npm 下载不会自动完成客户端安装。** 这个包还提供 `qgraphflow` 命令，[让图和代码保持同步](#让图和代码保持同步)一节会用到。
-
-</details>
+在客户端打开你的业务项目，新建会话并选择技能，按[快速入门](#快速入门)中的示例描述需求。生成后，用浏览器打开输出的 HTML。
 
 需要自行构建？参见[源码构建说明](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally)。
 
@@ -180,28 +218,23 @@ $qgraphflow:q-flow 展开上一张图中的库存预占步骤，单独生成中
 在页面里编辑后，用 Chrome 或 Edge 执行「更多 → 保存修改」并选一次图所在的文件夹，即可原地重写页面、`graph.json` 和 SVG。其他浏览器只能保存 `graph.json`：把它放回该文件夹，再用 `npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force` 重新生成页面和 SVG。
 
 <details>
-<summary>手动运行示例：复杂电商九类图</summary>
-
-以下命令仅用于运行仓库自带示例，使用已安装的插件无需克隆本仓库。
+<summary>Run the eleven-view Jeepay source example</summary>
 
-准备 Node.js 22 及以上版本，克隆仓库并执行：
+Select your Jeepay source checkout to verify the evidence:
 
 ```bash
-git clone https://github.com/supermax92/qgraphflow.git
-cd qgraphflow
-node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.zh-CN.graph.json
-node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.zh-CN.graph.json output/ecommerce-zh-CN
+export JEEPAY_REPO_ROOT="<local Jeepay repository root>"
+node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
+node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
 ```
 
-用浏览器打开 `output/ecommerce-zh-CN/index.html`，九个 SVG 就在同一目录。在顶部工具栏的「图类型」菜单切换视图，切换图类型会保留各图已保存的文字和位置。「更多 → 保存修改」按上文所述保存全部视图。同样的页面也在[在线演示](https://supermax92.github.io/qgraphflow/)里。
-
-使用预构建 Viewer 生成页面，无需安装依赖、API Key 或后端服务。让 AI 取证并编写图数据时，使用所选客户端的模型服务。
+Open `output/jeepay/index.html`; its eleven SVGs are in the same directory. See the [corpus README](../../examples/jeepay) for the source revision and refresh procedure.
 
 </details>
 
 ## 让图和代码保持同步
 
-带仓库根目录生成的图会记下每个组件定义在哪里。用 `--repo-root` 校验时，记录的文件不在了、行号超出文件，或记录的符号离开了原来的行范围，校验都会失败，并在错误里写出这个符号现在所在的行。把下面这个任务加进 CI，不需要构建、登录或令牌：
+带仓库根目录生成的图会记下每个组件定义在哪里，以及每条有代码支撑的关系所在的那一行（调用、外键等）。用 `--repo-root` 校验时，记录的文件不在了、行号超出文件，或记录的符号离开了原来的行范围，校验都会失败，并在错误里写出这个符号现在所在的行。把下面这个任务加进 CI，不需要构建、登录或令牌：
 
 ```yaml
 name: Diagrams
@@ -229,11 +262,13 @@ $qgraphflow:q-flow CI 提示 docs/qgraphflow/order-sequence 的图过时了，
 
 技能会把在文件里只找到一处的符号重新定位，只修改仍然报错的锚点，再保留你调整过的位置和文字，重新生成页面和 SVG；不会重画整张图。
 
-## 九类图各自回答什么
+## 十一类图各自回答什么
 
 | 视图 · PNG | 主要问题 | 本示例范围 |
 | --- | --- | --- |
-| 架构图 | 系统由哪些责任边界协作？ | 渠道、交易编排、价格、风控、库存、支付、订单、事件与履约 |
+| 平台能力架构图 | 平台具备哪些能力？ | 能力分区与矩阵 |
+| 工程分层架构图 | 工程代码怎样组织？ | 工程层级与共享支撑 |
+| 组件关系架构图 | 系统由哪些责任边界协作？ | 渠道、交易编排、价格、风控、库存、支付、订单、事件与履约 |
 | 流程图 | 每个决策点如何分支和收敛？ | 缺货、风控拒绝、支付失败补偿与成功提交 |
 | 时序图 | 一次请求按什么顺序调用和返回？ | 成功结算主链及异步 OrderPaid |
 | ER 图 | 核心数据如何关联？ | 购物车、订单、明细、支付、库存预占和包裹 |
@@ -262,3 +297,15 @@ node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
 [MIT](../../LICENSE) · [第三方声明](../../THIRD_PARTY_NOTICES.md)
 
 QGraphFlow 是采用 MIT 许可证的独立项目。本文场景为概念示例，不代表任何真实公司的生产架构。
+
+## Architecture overviews / 架构总览
+
+Architecture now includes component relations, platform capabilities and engineering layers. Describe the subject and question; the skill chooses the template. Requested collections can contain multiple architecture views with independent edits.
+
+```text
+$qgraphflow:q-flow 分析当前项目的平台能力和业务接入方式，生成中文平台能力总览。
+$qgraphflow:q-flow 分析当前工程组织和组件分层，生成工程整体与一个组件剖面的中文总览。
+$qgraphflow:q-flow Generate an English platform capability overview of this project and show how application modules integrate.
+```
+
+See [examples/jeepay](../../examples/jeepay) for real-source platform, engineering and component relationship architecture views. Unlock an overview to reorder cards within a layer or edit text. Save keeps all views; reset restores only the current one.