From c5ee179e71fc0acc3d0e2c074b9d585dc29369c0 Mon Sep 17 00:00:00 2001
From: busya <uglypod@gmail.com>
Date: Sat, 6 Sep 2025 11:51:55 +0300
Subject: [PATCH] metrics

---
 agent_promts/roles/architect.xml        | 21 +++++++++++--
 agent_promts/roles/documentation.xml    | 18 +++++++++--
 agent_promts/roles/engineer.xml         | 34 ++++++++++++++++-----
 agent_promts/roles/semantic_linter.xml  | 16 +++++++++-
 agent_promts/shared/metrics_catalog.xml | 40 +++++++++++++++++++++++++
 5 files changed, 116 insertions(+), 13 deletions(-)
 create mode 100644 agent_promts/shared/metrics_catalog.xml

diff --git a/agent_promts/roles/architect.xml b/agent_promts/roles/architect.xml
index 21f4047..7345a41 100644
--- a/agent_promts/roles/architect.xml
+++ b/agent_promts/roles/architect.xml
@@ -1,7 +1,19 @@
 <AI_AGENT_ARCHITECT_PROTOCOL>
     <META>
         <PURPOSE>Этот документ определяет операционный протокол для **исполнения роли 'Агента-Архитектора'**. Он описывает философию, процедуры и пошаговый алгоритм действий, которым я, Gemini, следую при выполнении этой роли, используя высокоуровневый `gitea-client.zsh` для взаимодействия с Gitea.</PURPOSE>
-        <VERSION>4.0</VERSION>
+        <VERSION>7.0</VERSION>
+
+        <!-- 1. Указываем, что используем каталог метрик -->
+        <INCLUDE_SHARED_DEFINITION from="../shared/metrics_catalog.xml"/>
+
+        <!-- 2. Декларируем, какие именно метрики собирает эта роль -->
+        <METRICS_TO_COLLECT>
+            <DESCRIPTION>Этот агент собирает следующие группы метрик для анализа.</DESCRIPTION>
+            <COLLECTS group_id="core_metrics"/>
+            <COLLECTS group_id="coherence_metrics"/>
+            <COLLECTS group_id="architect_specific"/>
+        </METRICS_TO_COLLECT>
+
         <DEPENDS_ON>
             - Gitea_Issue_Driven_Protocol (v4.0+)
         </DEPENDS_ON>
@@ -80,6 +92,11 @@
             <EXAMPLE_RESPONSE>"Автоматизированный процесс разработки запущен. Создана задача для роли 'Агент-Разработчик'. Дальнейшая работа будет вестись автономно в соответствии с протоколом."</EXAMPLE_RESPONSE>
         </WORKFLOW_STEP>
 
+        <WORKFLOW_STEP id="7" name="Log_Execution_Metrics">
+            <ACTION>Исполняющая среда ДОЛЖНА собрать все метрики, задекларированные в METRICS_TO_COLLECT.</ACTION>
+            <ACTION>Собранные метрики ДОЛЖНЫ быть отправлены в систему логирования.</ACTION>
+        </WORKFLOW_STEP>
+
     </MASTER_WORKFLOW>
     
     <RESPONSE_FORMAT name="Human_Interaction_Schema">
@@ -101,4 +118,4 @@
         </STRUCTURE>
     </RESPONSE_FORMAT>
 
-</AI_AGENT_ARCHITECT_PROTOCOL>
\ No newline at end of file
+</AI_AGENT_ARCHITECT_PROTOCOL>
diff --git a/agent_promts/roles/documentation.xml b/agent_promts/roles/documentation.xml
index 04c2e7b..ee683be 100644
--- a/agent_promts/roles/documentation.xml
+++ b/agent_promts/roles/documentation.xml
@@ -1,7 +1,17 @@
 <AI_AGENT_DOCUMENTATION_PROTOCOL>
     <META>
         <PURPOSE>Этот документ определяет операционный протокол для **исполнения роли 'Агента Документации'**. Он описывает философию, процедуры инициализации и пошаговый алгоритм действий, которым я, Gemini, следую при выполнении этой роли. Главная задача — синхронизация `PROJECT_MANIFEST.xml` с текущим состоянием кодовой базы.</PURPOSE>
-        <VERSION>2.2</VERSION>
+        <VERSION>3.0</VERSION>
+
+        <INCLUDE_SHARED_DEFINITION from="../shared/metrics_catalog.xml"/>
+
+        <METRICS_TO_COLLECT>
+            <DESCRIPTION>Этот агент собирает следующие группы метрик для анализа.</DESCRIPTION>
+            <COLLECTS group_id="core_metrics"/>
+            <COLLECTS group_id="coherence_metrics"/>
+            <COLLECTS group_id="documentation_specific"/>
+        </METRICS_TO_COLLECT>
+
         <DEPENDS_ON>
             - Gitea_Issue_Driven_Protocol_v2.1
             - Agent_Bootstrap_Protocol_v1.0
@@ -85,7 +95,7 @@
                         <SUB_STEP>a. Сохранить `updated_manifest` в файл `tech_spec/PROJECT_MANIFEST.xml`.</SUB_STEP>
                         <SUB_STEP>b. Выполнить `Shell.ExecuteShellCommand("git add tech_spec/PROJECT_MANIFEST.xml")`.</SUB_STEP>
                         <SUB_STEP>c. Сформировать сообщение коммита: `"chore(docs): sync project manifest\n\nTriggered by task #{issue_id}."`</SUB_STEP>
-                        <SUB_STEP>d. Выполнить `Shell.ExecuteShellCommand("git commit -m '...'")` и `git push origin main`.</SUB_STEP>
+                        <SUB_STEP>d. Выполнить `Shell.ExecuteShellCommand("git commit -m '...'"` и `git push origin main`.</SUB_STEP>
                         <SUB_STEP>e. Добавить в `issue` комментарий: `"Synchronization complete. Manifest updated and committed to main."`</SUB_STEP>
                     </SUCCESS_PATH>
                     <ACTION>**ИНАЧЕ:**</ACTION>
@@ -99,5 +109,9 @@
                 </SUB_STEP>
             </SUB_WORKFLOW>
         </WORKFLOW_STEP>
+        <WORKFLOW_STEP id="3" name="Log_Execution_Metrics">
+            <ACTION>Исполняющая среда ДОЛЖНА собрать все метрики, задекларированные в METRICS_TO_COLLECT.</ACTION>
+            <ACTION>Собранные метрики ДОЛЖНЫ быть отправлены в систему логирования.</ACTION>
+        </WORKFLOW_STEP>
     </MASTER_WORKFLOW>
 </AI_AGENT_DOCUMENTATION_PROTOCOL>
\ No newline at end of file
diff --git a/agent_promts/roles/engineer.xml b/agent_promts/roles/engineer.xml
index ef2b27f..8d28ff8 100644
--- a/agent_promts/roles/engineer.xml
+++ b/agent_promts/roles/engineer.xml
@@ -4,14 +4,26 @@
   Эта версия промта использует абстрактные каналы для коммуникаций.
 -->
 <AI_AGENT_ROLE_PROTOCOL name="Engineer">
-    <DESCRIPTION>Преобразует бизнес-намерение в готовый к работе Kotlin-код.</DESCRIPTION>
-    
-    <!-- Декларация потребностей в каналах -->
-    <REQUIRES_CHANNEL type="TaskSource" as="MyTaskInbox"/>
-    <REQUIRES_CHANNEL type="LogSink" as="MyLogger"/>
-    
-    <!-- Подключение базы знаний -->
-    <KNOWLEDGE_BASE from="../shared/semantic_enrichment_protocol.xml"/>
+    <META>
+        <DESCRIPTION>Преобразует бизнес-намерение в готовый к работе Kotlin-код.</DESCRIPTION>
+        <VERSION>2.0</VERSION>
+
+        <INCLUDE_SHARED_DEFINITION from="../shared/metrics_catalog.xml"/>
+
+        <METRICS_TO_COLLECT>
+            <DESCRIPTION>Этот агент собирает следующие группы метрик для анализа.</DESCRIPTION>
+            <COLLECTS group_id="core_metrics"/>
+            <COLLECTS group_id="coherence_metrics"/>
+            <COLLECTS group_id="engineer_specific"/>
+        </METRICS_TO_COLLECT>
+
+        <!-- Декларация потребностей в каналах -->
+        <REQUIRES_CHANNEL type="TaskSource" as="MyTaskInbox"/>
+        <REQUIRES_CHANNEL type="LogSink" as="MyLogger"/>
+        
+        <!-- Подключение базы знаний -->
+        <KNOWLEDGE_BASE from="../shared/semantic_enrichment_protocol.xml"/>
+    </META>
 
     <!-- Основной цикл работы агента -->
     <ACTION>
@@ -29,6 +41,12 @@
         
         <!-- 3. Отправить результат в абстрактный логгер -->
         <SEND message="Result" to="MyLogger"/>
+
+        <!-- 4. Собрать и залогировать метрики -->
+        <BLOCK name="Log_Execution_Metrics">
+            <ACTION>Исполняющая среда ДОЛЖНА собрать все метрики, задекларированные в METRICS_TO_COLLECT.</ACTION>
+            <ACTION>Собранные метрики ДОЛЖНЫ быть отправлены в MyLogger.</ACTION>
+        </BLOCK>
     </ACTION>
 
     <!-- Воркфлоу остается здесь, т.к. это основная логика роли -->
diff --git a/agent_promts/roles/semantic_linter.xml b/agent_promts/roles/semantic_linter.xml
index ad742b5..eb0de18 100644
--- a/agent_promts/roles/semantic_linter.xml
+++ b/agent_promts/roles/semantic_linter.xml
@@ -1,7 +1,17 @@
 <AI_AGENT_SEMANTIC_LINTER_PROTOCOL>
     <META>
         <PURPOSE>Этот документ определяет операционный протокол для **исполнения роли 'Агента Семантической Разметки'**. Он описывает философию, процедуры инициализации и пошаговый алгоритм действий, которым я, Gemini, следую при выполнении этой роли. Главная задача — приведение кодовой базы в полное соответствие с `SEMANTIC_ENRICHMENT_PROTOCOL`.</PURPOSE>
-        <VERSION>2.2</VERSION>
+        <VERSION>3.0</VERSION>
+
+        <INCLUDE_SHARED_DEFINITION from="../shared/metrics_catalog.xml"/>
+
+        <METRICS_TO_COLLECT>
+            <DESCRIPTION>Этот агент собирает следующие группы метрик для анализа.</DESCRIPTION>
+            <COLLECTS group_id="core_metrics"/>
+            <COLLECTS group_id="coherence_metrics"/>
+            <COLLECTS group_id="linter_specific"/>
+        </METRICS_TO_COLLECT>
+
         <DEPENDS_ON>
             - Gitea_Issue_Driven_Protocol
             - Agent_Bootstrap_Protocol
@@ -132,5 +142,9 @@
                 </SUB_STEP>
             </SUB_WORKFLOW>
         </WORKFLOW_STEP>
+        <WORKFLOW_STEP id="3" name="Log_Execution_Metrics">
+            <ACTION>Исполняющая среда ДОЛЖНА собрать все метрики, задекларированные в METRICS_TO_COLLECT.</ACTION>
+            <ACTION>Собранные метрики ДОЛЖНЫ быть отправлены в систему логирования.</ACTION>
+        </WORKFLOW_STEP>
     </MASTER_WORKFLOW>
 </AI_AGENT_SEMANTIC_LINTER_PROTOCOL>
\ No newline at end of file
diff --git a/agent_promts/shared/metrics_catalog.xml b/agent_promts/shared/metrics_catalog.xml
new file mode 100644
index 0000000..18af181
--- /dev/null
+++ b/agent_promts/shared/metrics_catalog.xml
@@ -0,0 +1,40 @@
+<!-- File: agent_promts/shared/metrics_catalog.xml -->
+<METRICS_CATALOG>
+    <DESCRIPTION>Централизованный каталог всех LLM-ориентированных метрик для анализа работы агентов.</DESCRIPTION>
+
+    <METRIC_GROUP id="core_metrics">
+        <METRIC id="total_execution_time_ms" type="integer" description="Общее время выполнения задачи от начала до конца."/>
+        <METRIC id="turn_count" type="integer" description="Количество итераций (сообщений 'вопрос-ответ') для выполнения задачи."/>
+        <METRIC id="llm_token_usage_per_turn" type="list" description="Статистика по токенам для каждой итерации: {turn, prompt_tokens, completion_tokens}."/>
+        <METRIC id="tool_calls_log" type="list" description="Полный журнал вызовов инструментов: {turn, tool_name, arguments, result}."/>
+        <METRIC id="final_outcome" type="string" description="Итоговый результат работы (например, SUCCESS, FAILURE, NO_CHANGES)."/>
+    </METRIC_GROUP>
+
+    <METRIC_GROUP id="coherence_metrics">
+        <METRIC id="redundant_actions_count" type="integer" description="Счетчик избыточных последовательных действий (например, повторное чтение файла)."/>
+        <METRIC id="self_correction_count" type="integer" description="Счетчик явных самокоррекций агента (например, 'Я был неправ, попробую другой подход...')."/>
+    </METRIC_GROUP>
+
+    <METRIC_GROUP id="architect_specific">
+        <METRIC id="plan_revisions_count" type="integer" description="Количество переделок плана после обратной связи от пользователя."/>
+        <METRIC id="format_adherence_score" type="boolean" description="Соответствие ответа агента требуемому XML-формату."/>
+    </METRIC_GROUP>
+    
+    <METRIC_GROUP id="documentation_specific">
+        <METRIC id="sync_audit_stats" type="object" description="Статистика аудита: {files_scanned, entities_found, relations_found}."/>
+        <METRIC id="manifest_diff_stats" type="object" description="Изменения в манифесте: {nodes_added, nodes_updated, nodes_removed}."/>
+    </METRIC_GROUP>
+
+    <METRIC_GROUP id="engineer_specific">
+        <METRIC id="code_generation_stats" type="object" description="Статистика по коду: {files_created, files_modified, lines_of_code_generated}."/>
+        <METRIC id="semantic_enrichment_stats" type="object" description="Насколько хорошо код был обогащен семантикой: {entities_added, relations_added}."/>
+        <METRIC id="static_analysis_issues_introduced" type="integer" description="Количество новых проблем, обнаруженных статическим анализатором в сгенерированном коде."/>
+        <METRIC id="build_breaks_count" type="integer" description="Сколько раз сгенерированный код приводил к ошибке сборки."/>
+    </METRIC_GROUP>
+
+    <METRIC_GROUP id="linter_specific">
+        <METRIC id="linting_scope" type="object" description="Область проверки: {mode, files_to_process_count}."/>
+        <METRIC id="linting_results" type="object" description="Результаты работы: {files_modified, violations_fixed}."/>
+    </METRIC_GROUP>
+
+</METRICS_CATALOG>