Сценарий 13 ищет использования, группирует кандидатов миграции, оценивает влияние на места вызова и предлагает порядок работ. Результат — план миграции для отдельной задачи реализации; исходные файлы сохраняются без изменений.
Когда применять
Используйте сценарий для широкой, но конкретной миграции: переименования публичного символа, замены API или изменения сигнатуры во множестве мест. Укажите исходный и целевой символы, компонент, правило совместимости и ревизию.
Для ограниченного изменения с сохранением поведения подходит сценарий 05. Если затронуто несколько репозиториев, сначала выполните сценарий 10.
Предварительные условия и область
Подготовьте окружение Python и локальную конфигурацию по руководству CLI и программному интерфейсу. Проверьте доступность сервисов графа и настройте LLM для подготовки плана. Согласуйте область миграции с владельцем перед реализацией.
Привяжите запрос к принятой задаче реализации и текущей ревизии исходников. Определите исключения, сгенерированный код, требования публичной совместимости, владельцев и максимальный размер этапа.
При недоступном CPG workflow может использовать резервный список целей, извлечённый из запроса. Список уточняет область; надёжный радиус влияния подтверждается актуальным CPG.
Запуск типизированного сценария
Сохраните пример в файл Python в настроенном окружении. Замените проект, namespace, задачу, ссылки на свидетельства и пути на принятую область. Вместо условных имён символов укажите реальные исходный и целевой символы.
from src.digital_employees.runtime.scenarios import (
RoleBoundScenarioInvocationRequest,
invoke_role_bound_scenario_request,
)
request = RoleBoundScenarioInvocationRequest(
query="Переименуй LegacyClient в ServiceClient в ограниченном компоненте.",
employee_id="codegraph_developer",
scenario_id="scenario_13",
event_type="implementation_start",
context={
"project_key": "codegraph",
"namespace": "default",
"task_id": "<task-id>",
"source_refs": ["<revision-ref>", "<compatibility-contract-ref>"],
"file_paths": ["<bounded-source-path>"],
},
)
result = invoke_role_bound_scenario_request(request)
if result.get("error"):
raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])
При неоднозначном запросе сценарий возвращает уточняющий вопрос. Укажите одну пару исходного и целевого символов, затем повторите анализ. Резервную цель из запроса подтвердите с владельцем компонента перед созданием задачи реализации.
Как читать результат
Проверьте метаданные определения цели, найденные функции, категории мест вызова, свидетельства и предложенный порядок. Подтвердите каждое значимое использование в привязанной ревизии и сохраните свидетельство вызова вместе с планом.
Проверьте metadata.refactoring_target_resolution: прежде всего needs_clarification, выбранную цель и её происхождение. При needs_clarification уточните входные данные и повторите запрос. Для резервных кандидатов подтвердите использования по CPG и исходникам. Проверяйте result.get("error") вместе с ответом.
Проверьте выбранную цель
Для запроса из примера фрагмент metadata.refactoring_target_resolution содержит:
{
"operation_intent": "rename",
"target_symbol": "LegacyClient",
"destination_symbol": "ServiceClient",
"needs_clarification": false,
"clarification_reason": null,
"resolution_source": "user_input"
}
Сопоставьте target_symbol с исходным символом, а destination_symbol — с новым именем. Значение needs_clarification=false означает, что обработчик определил направление переименования. Далее workflow ищет использования выбранной цели и формирует план.
Запрос Переименуй LegacyClient и ServiceClient оставляет направление открытым. Обработчик возвращает уточнение:
{
"candidate_symbols": [
"LegacyClient",
"ServiceClient"
],
"needs_clarification": true,
"clarification_reason": "ambiguous_rename_target",
"clarification_question": "Уточните целевой символ и ожидаемый результат для: LegacyClient, ServiceClient."
}
Повторите запрос как Переименуй LegacyClient в ServiceClient в ограниченном компоненте.. После ответа проверьте выбранную пару и найденные использования в CPG.
Оба фрагмента показывают этап определения цели. Найденные места вызова и план миграции зависят от исходников и графа вашего проекта.
Категории simple, signature change и complex группируют изменения по эвристической оценке сложности. Для каждой группы проверьте совместимость и тесты, затем согласуйте этап реализации.
Управляемое изменение после планирования
Для каждой одобренной группы создайте отдельный этап с точной областью. Минимальные элементы контроля:
approval— разрешение ответственного человека на конкретный этап;tests— RED/GREEN-покрытие контракта и регрессий;rollback— привязанная к ревизии процедура восстановления;- профильные свидетельства архитектуры, AppSec, QA, документации и трассируемости.
Примените и проверьте один этап перед расширением миграции. Выполнение переименования подтверждается проверкой изменённых файлов и тестами.
Ошибки и восстановление
- Запрошено уточнение: укажите одну пару исходного и целевого символов и ограниченный компонент.
- CPG недоступен: пометьте резервный ответ как предварительный и восстановите привязанное к ревизии свидетельство CPG.
- Найдены неожиданные места вызова: остановите этап, обновите область и тесты, затем запросите новое одобрение.
- После этапа возникла регрессия: выполните записанный откат и сохраните свидетельство сбоя до перепланирования.