5.9 KiB
5.9 KiB
Axiom MCP Tools Evaluation Report
Общее резюме (Executive Summary)
В ходе тестирования поверхности Axiom MCP-инструментов были проверены основные категории: Query/Search, Semantic Health & Audit, AST/Semantic Patching, Workspace Management и Validation/Command execution. Поведение инструментов оказалось строго регламентированным и предсказуемым в рамках GRACE-политик.
Самые сильные стороны:
- Validation Friction & Recovery Simplicity: Наличие
simulate_patch_toolи строгое использование preview-режимов для мутаций, а также возможность автоматического отката (rollback_workspace_change_tool) делают систему крайне устойчивой к ошибкам. - Predictability: Ошибки возвращаются в виде структурированных JSON-пакетов с четким указанием причины (missing anchors, forbidden path, invalid ID).
Самые проблемные места (Ограничения):
- Understandability / Mental-Model Shift: Высокий порог входа из-за строгих требований GRACE (сложность контрактов от 1 до 5 уровня, обязательные якоря
[DEF]...[/DEF]). Привычные паттерны (shell writes) заблокированы. - Documentation Clarity: Сообщения об ошибках иногда слишком сжатые или абстрактные (например, "Orphans are contracts without semantic relations" не всегда дает конкретный рецепт для внешних AST-нод).
Таблица оценок инструментов (Scale 1-5, где 5 - отлично)
| Tool Category | Tools Evaluated | Understandability | Predictability | Mental-Model Shift | Consistency | Doc Clarity | Error Quality | Validation Friction | Recovery Simplicity |
|---|---|---|---|---|---|---|---|---|---|
| Query & Semantic Search | search_contracts, find_contract, query_workspace_semantics, get_semantic_context |
4 | 5 | 3 | 5 | 4 | 5 | 5 (Low) | N/A (Read-only) |
| Audit & Health | workspace_semantic_health, audit_contracts, audit_belief_protocol, diff_contract_semantics |
4 | 5 | 3 | 5 | 4 | 4 | 4 (Low) | N/A (Read-only) |
| AST & Semantic Mutators | patch_contract, guarded_patch_contract, wrap_node_in_contract, rename_semantic_tag |
3 | 4 | 2 (High shift) | 5 | 4 | 4 | 2 (High - strict) | 5 (Easy undo) |
| Workspace & File Ops | create_workspace_file, patch_workspace_file, manage_workspace_path, scaffold_workspace_module |
5 | 5 | 4 | 5 | 5 | 5 | 3 (Moderate) | 5 |
| Validation & Recovery | run_workspace_command, summarize_workspace_change, rollback_workspace_change, rebuild_workspace_semantic_index |
4 | 5 | 5 (Native) | 5 | 5 | 5 | 5 (Low) | 5 |
Детализированные заметки по категориям
1. Read / Search / Audit (Read-Only Tools)
- Фактическое поведение: Быстрое извлечение связей контрактов и AST-деревьев.
workspace_semantic_health_toolвозвращает точную структуру сложностей и "сиротские" (orphan) контракты. - Ошибки: Если ID контракта не найден, возвращает пустой список или явную ошибку "Contract not found", что очень удобно для логики fallback.
- Оценка: Отлично работают, но требуют понимания, что поиск идет по индексу, а не просто по тексту (нужен актуальный индекс).
2. Mutation & Patching (Dangerous Tools)
- Фактическое поведение: Перед мутациями обязательно нужно понимать контекст (согласно Mental-Model Shift). Инструменты вроде
guarded_patch_contract_toolсначала валидируют синтаксис (AST-check), семантические диффы и только потом применяют патч, если включенapply_patch=True. - Строгость валидации: Крайне высокая. Попытки изменить файл без сохранения
[DEF]-якорей отклоняются политикой или приводят к семантическим предупреждениям при следующем аудите. - Recovery: Любая успешная мутация записывается в checkpoint (
.axiom/checkpoints). Отмена черезrollback_workspace_change_toolпроисходит атомарно.
3. Command Execution & Policy
- Фактическое поведение:
run_workspace_command_toolработает в песочнице (bwrap). Запись вне.axiom/tempуспешно пресекается политикой (Read-Only shell). - Ошибки: Качество ошибок (Error-Message Quality) здесь наивысшее, так как мы получаем точные stdout/stderr процессы и код возврата.
Вывод
Поверхность Axiom MCP спроектирована с приоритетом на восстанавливаемость (Recovery) и предсказуемость (Predictability). Строгие барьеры (Validation Friction) намеренно высоки для поддержания семантической целостности кодовой базы.