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

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

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

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

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

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

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

Поддерживаемая Python-поверхность — 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/project_suite/import_commands.py",
            "tests/unit/cli/test_import_commands.py",
        ],
    },
)

result = invoke_role_bound_scenario_request(request)

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

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

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

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

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

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

Не публикуйте число обработчиков, классов, правил или поддерживаемых элементов, если это не поддерживаемый публичный контракт и дрейф не контролируется тестом.

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

Сценарий возвращает анализ и основу для черновика. Редактирование, коммит, публикация и одобрение документации выполняет отдельная линия документации в рамках task carrier.

Если политика отклоняет пару сотрудника и сценария, используйте ответственную политику codegraph_docs для scenario_03, а не устаревший псевдоним. Если свидетельство устарело или отсутствует, оставьте утверждение неизвестным и запросите точечную проверку исходника или живого интерфейса.

Поддерживаемые источники контракта

Публичные типизированные экспорты: src/digital_employees/runtime/scenarios/__init__.py
Вызов и обязательный контекст: src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py
Политика сотрудника документации: src/digital_employees/runtime/scenarios/employee_scenario_invocation.py

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