phases-agents

English · Français

Локальный MCP-сервер, который детерминированно обнаруживает, проверяет и выбирает навыки. Только стандартная библиотека Python, без зависимостей времени выполнения.

Один сервер. Пять инструментов. Ничего не выполняется у вас за спиной.

Зачем

ИИ-агенты импровизируют. Задайте один и тот же вопрос дважды — и вы получите два разных плана. Для мозгового штурма это нормально, но для аудита и комплаенс-работы — неприемлемо.

phases-agents устраняет импровизацию. Он профилирует локальный проект, проверяет каталог навыков на соответствие строгому контракту и возвращает план, который можно воспроизвести. Одинаковая цель, одинаковый каталог, одинаковые параметры — одинаковое решение.

Принцип

configured root identifiers
→ bounded discovery
→ official validation
→ immutable registry
→ verified cache
→ detector profile
→ deterministic selection
→ MCP plan

Сервер выбирает и предоставляет. Вызывающая модель читает выбранные навыки и решает, что с ними делать, используя собственные инструменты. Сервер никогда не выполняет навык.

Архитектура

Нормативный контракт находится в core/SKILLS_CONTRACT.md (на французском).

Быстрый старт

Пример пакета поставляется в examples/skills/. Три шага дают реальный план.

git clone https://github.com/Cherridsaid/phases-agents && cd phases-agents

Создайте skills-roots.json, указывающий на корень примера:

{
  "config_version": "1.0",
  "roots": [
    { "id": "demo", "path": "/absolute/path/to/phases-agents/examples/skills" }
  ]
}

python server.py --skills-config /absolute/path/to/skills-roots.json

Сервер читает JSON-RPC построчно из стандартного ввода. Вызов phases_agents_plan для Python-проекта затем выбирает hello-python:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"phases_agents_plan",
 "arguments":{"root_ids":["demo"],"target":"/absolute/path/to/a/project",
 "today":"2026-08-27","plan_version":"B3",
 "client_capabilities":["filesystem_read","filesystem_search"]}}}

Сосуществуют два формата планов. "B3" обозначает версионированный формат, а не версию сервера; его официальная схема — core/PLAN_B3_SCHEMA.json. Используйте его для новой работы. Без plan_version устаревший формат возвращает плоский список шагов; он сохранён, чтобы не сломать существующих вызывающих клиентов, и будет объявлен устаревшим перед удалением. client_capabilities принимается только в B3, поскольку заявление о том, что умеет клиент, имеет смысл только в этом формате.

Подключение MCP-клиента

Claude Code (.mcp.json в корне вашего проекта):

{
  "mcpServers": {
    "phases-agents": {
      "command": "python",
      "args": [
        "/absolute/path/to/phases-agents/server.py",
        "--skills-config",
        "/absolute/path/to/skills-roots.json"
      ]
    }
  }
}

Codex использует ту же пару command/arguments в своём конфигурационном файле. Ни токен, ни переменная окружения не требуются.

MCP-инструменты

detect(target)
list_skills(root_ids, today)
get_skill(root_ids, today, skill_id)
plan(root_ids, target, today, constraints?)
plan(root_ids, target, today, plan_version, client_capabilities?)
refresh_skills(root_ids, today)

today внедряется, а не считывается с часов, поэтому каждый вызов воспроизводим. get_skill принимает идентификатор, а не путь, и его содержимое берётся из проверенного снимка. Абсолютные пути и обнаруженные секреты маскируются в публичном выводе. Любой закодированный JSON-RPC-ответ остаётся в пределах 1 MiB.

Первый вызов создаёт проверенный реестр. «Тёплые» вызовы проверяют метаданные, не перечитывая содержимое. refresh_skills принудительно пересобирает реестр.

Создание пакета навыка

Каждый пакет — это прямой дочерний элемент корня и содержит как минимум:

<root>/<skill-id>/SKILL.md
<root>/<skill-id>/phases.json

Самый быстрый способ начать — скопировать examples/skills/hello-python/ и переименовать идентификатор.

Метаданные SKILL.md

Разрешены пять ключей. Все необязательные, все проверяются при наличии.

Четырнадцать обязательных разделов

Каждый из них — заголовок Markdown (##) в любом порядке. Названия разделов — на французском, потому что они принадлежат контракту; содержимое вы можете писать на любом языке.

Loi centrale · Ce que ce skill fait · Ce que ce skill ne fait pas · Conditions d'activation · Conditions d'exclusion · Capacites necessaires · Interdictions · Methode d'audit · Contrat de preuve · Format de sortie · Conditions de blocage · Limites connues · Exemples d'entree · Exemple de sortie attendue

Поля phases.json

Все поля обязательны: schema_version, id, version, title, description, domain, project_types, platforms, activation, exclusions, requires_capabilities, optional_capabilities, forbidden_capabilities, execution_mode, human_approval, output_schema, rules_path, references_path, scripts_path, tests_path, files.

output_schema использует символическую форму core:SCHEMA_NAME.json.

Закрытые словари

project_types должен пересекаться с тем, что может выдать детектор: apk, python, skill_package, solana, web.

activation.any использует профильные факты: collects_personal_data, has_api, has_apk, has_authentication, has_database, has_ecommerce, has_eu_context, has_file_upload, has_javascript, has_python, has_rust, has_skill_packages, has_solana, has_source_code, has_typescript, has_web, uses_ai, uses_payments.

requires_capabilities, optional_capabilities и forbidden_capabilities используют: browser, dependency_installation, filesystem_read, filesystem_search, filesystem_write, human_question, shell, target_code_execution, web.

Предоставляемые возможности — это открытый словарь: каждый каталог называет то, что он даёт, и контролируется только форма (^[a-z][a-z0-9_]{0,63}$). Закрыты только клиентские возможности, потому что они описывают протокол, а не вашу предметную область.

Значение domain, равное legal, juridique, regulatory или compliance, запускает особый режим: каждая цитируемая норма должна содержать официальный источник, юрисдикцию и дату проверки.

Что схема описывает и о чём умалчивает

SKILL_MANIFEST_SCHEMA.json описывает форму phases.json: обязательные поля, типы, закрытые словари.

Движок схем намеренно минимален. Он применяет enum, minLength и minItems и больше ничего: ни pattern, ни if/then, ни oneOf. Схема, использующая эти ключевые слова, будет отвергнута сама.

Это важно: условные правила живут в validator.py, который остаётся источником истины. Пример — правило версии: provides_capabilities запрещено в манифесте 1.0 и обязательно в 1.1. Это правило применяется и тестируется, но его нельзя выразить в схеме. Не читайте required как весь контракт.

Пакет только с SKILL.md не проходит. Недопустимый пакет блокирует реестр, а не деградирует молча.

Идентичность

phases.json.id — это идентичность, и SKILL.md.name должен совпадать с ней. Директория должна иметь тот же ключ. Ключи нормализуются через NFKC, а затем casefold, поэтому гомоглифы не могут протащить вторую идентичность. Любое столкновение блокирует всю сборку; ни один пакет не выбирается произвольно.

Выбор

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

Единственный доказанный автоматический сигнал:

project_types ∩ profile.types

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

Пустой план явно допустим: он содержит NO_COMPATIBLE_SKILL.

План B3 классифицирует каждый установленный навык по категориям skills_selected, skills_not_applicable и skills_blocked; каждый навык появляется ровно один раз. skills_missing перечисляет возможности, для которых нет исполняемого провайдера, на основе только подтверждённых фактов. Пробел никогда не доказывает несоответствие — он говорит, что признанный необходимым аудит не покрыт.

Лимиты

• максимум 16 корней

• только один уровень вложенности

• максимум 1 000 пакетов

• 10 000 записей на корень

• SKILL.md ограничен 256 KiB

• один справочный материал ограничен 256 KiB, в сумме — 1 MiB

• снимки ограничены 16 MiB

• публичный результат ограничен 1 MiB

• 100 проблем на пакет

• отпечаток ограничен 100 000 узлов

Вызывающие клиенты могут только понижать эти лимиты, но никогда не повышать.

Рантайм-ограничения

• Python >=3.11

• нет сторонних зависимостей в рантайме

• нет неявного доступа к сети

• нет рантайм-оболочки

• целевой код не выполняется

• нет неявных часов

• нет телеметрии

• ни один навык не загружается

pytest — это только зависимость для разработки.

Тесты

python -m pytest -q

Ожидаемый результат:

729 passed, 2 skipped
0 failed

Нормативные тексты извлекаются с окончаниями строк LF, что закреплено в .gitattributes. Пара тестов символических ссылок Windows пропускается: для них требуется локальная привилегия Windows. Windows-джанкшены действительно тестируются.

Уровень доказательности

Валидатор подтверждает только одно:

STRUCTURALLY_VALIDATED

Он не проверяет реальную цель. TARGET_VERIFIED остаётся запрещённым в V1.

Безопасность

Загрузчик отвергает точки повторного анализа (reparse points). Чтения ограничены и локализованы. Вывод отсортирован и детерминирован.

Одно проектное решение заслуживает вашего внимания: detect и plan принимают путь target, который не ограничен настроенными корнями, поскольку смысл — профилировать произвольный проект. Запускайте этот сервер под учётной записью, чей охват вы принимаете, и подключайте его только к доверенному клиенту. Полная модель угроз описана в SECURITY.md.

Не-гарантии

• нет универсальной семантической релевантности

• ни один внешний навык не одобряется автоматически

• нет аудита содержимого скриптов

• нет подлинного доказательства реально подключённой цели

• нет полной атомарности Windows

• нет универсального распознавания HTML

• нет универсального обнаружения секретов

• нет гарантированного юридического соответствия

• нет маркетплейса, нет удалённых источников

Лицензия

Apache-2.0. Смотрите LICENSE и NOTICE.