Сценарий 03: документация по проверенным исходникам

Сценарий помогает подготовить инструкцию по текущим исходникам. Укажите цель читателя, команду или процесс, который нужно описать, принятую задачу и нужные файлы. Считайте ответ черновиком: проверьте каждое утверждение и пример перед публикацией.

Что определить до вызова

Сначала зафиксируйте:

читателя и решение или задачу, которую должна поддержать страница;
точный API, CLI, MCP, UI, параметр конфигурации или процесс в области работы;
принятый идентификатор задачи;
актуальные ссылки на исходники и тесты;
факты, которые остаются неизвестными или требуют живой проверки;
целевую локаль и границу между публичным и внутренним содержанием.

Если задача звучит как «описать систему», сузьте её до одного пользовательского результата. Широкие запросы обычно порождают повторяющиеся архитектурные обзоры вместо рабочей инструкции.

Типизированный вызов

Пример предназначен для разработчика интеграции из исходного репозитория CodeGraph. Установите зависимости по разделу подготовки руководства CLI и настройте runtime по руководству программного вызова. Подготовьте CPG для нужной ревизии проекта по разделу «Подготовка проекта». Вызов получает контекст проекта и передаёт запрос настроенному LLM-провайдеру. Для работы нужны зарегистрированный проект с доступными исходниками, актуальный CPG и принятая задача. Перед отправкой закрытого кода провайдеру согласуйте это с владельцем исходника. Сохраните код как documentation_request.py в корне репозитория и запустите python documentation_request.py после того, как замените значения контекста данными своей задачи. Укажите namespace, связанный с задачей; default приведён только как пример.

Создайте запрос с помощью класса RoleBoundScenarioInvocationRequest и передайте его функции invoke_role_bound_scenario_request:

from src.digital_employees.runtime.scenarios import (
    RoleBoundScenarioInvocationRequest,
    invoke_role_bound_scenario_request,
)

request = RoleBoundScenarioInvocationRequest(
    query="Подготовь пользовательскую инструкцию для текущей команды импорта и её ошибок.",
    employee_id="codegraph_docs",
    scenario_id="scenario_03",
    event_type="docs_memory_sync_start",
    context={
        "project_key": "codegraph",
        "namespace": "default",
        "task_id": "<task-id>",
        "source_refs": [
            "src/cli/core_commands/import_commands.py",
            "tests/unit/cli/test_import_commands.py",
        ],
    },
)

result = invoke_role_bound_scenario_request(request)
if result.get("error"):
    raise RuntimeError(result["error"])
print(result.get("scenario_id"))
print(result.get("answer") or "")

Замените пример source_refs файлами и тестами своей задачи. Контракт требует непустых значений для project_key, namespace и task_id. Если значения нет, вызов возвращает ошибку role_bound_scenario_contract_missing.

При успешном вызове программа сначала печатает scenario_03, затем текст ответа. Проверьте error и поле metadata.role_bound_scenario_invocation, которое связывает ответ с ролевым вызовом. Затем сопоставьте команды, параметры и действия при ошибках с указанными исходниками и исполняемой справкой. Если CodeGraph не находит указанный исходник, проверьте привязку проекта и ревизию CPG. Обновите данные проекта, затем запросите исходник повторно.

Как превратить результат в полезную страницу

Убедитесь, что возвращён scenario_id со значением scenario_03 и присутствует свидетельство ролевого вызова.
Проверьте каждое важное утверждение по текущему исходному коду или исполняемой справке. Если старый документ расходится с поведением, приоритет у поведения.
Начните с результата читателя и кратчайшей успешной процедуры.
Опишите предварительные условия, права, побочные эффекты, выходные данные, ошибки и восстановление.
Проверьте команды и примеры новой страницы по текущим исходникам и результатам выполнения. Укажите, какие проверки выполнены, а какие ещё предстоят.
Запустите профильный валидатор, проверку ссылок и каталога, а также сборку сайта для изменённых страниц.

Ожидаемые свидетельства

Проверяемый результат должен содержать:

принятую задачу и локаль;
поддерживаемые ссылки на исходники и тесты;
команды или запросы из текущего интерфейса;
явные неизвестные и поведение в ухудшенном режиме;
команду валидации и её результат;
ссылки на глубокие справочные материалы вместо копирования внутренних перечней реализации.

Для метрик укажите поддерживаемую версию и источник каждого значения. Добавьте проверку, которая обнаружит изменение после обновления продукта.

Границы и восстановление

Сценарий возвращает анализ и основу для черновика. После проверки отредактируйте страницу, сохраните её в репозитории и подготовьте к публикации в рамках принятой задачи.

В примере указаны employee_id="codegraph_docs" и scenario_id="scenario_03". Если данных проекта не хватает, отметьте утверждение как неизвестное и запросите конкретный исходник или проверку живого интерфейса.

Связанные материалы

Полный контракт запроса и ошибки описаны в руководстве по программному вызову.