Архитектура

  1. Обзор
  2. Разделение ответственности — текущее и будущее состояние
  3. Структура репозитория
  4. Сервер MCP
  5. Адаптеры контента
  6. Навыки и пакеты навыков
  7. Объектная модель контента
  8. Управление доступом — ODRL, проверка перед каждой задачей
  9. Прайминг плана работы (между харнессами)
  10. Развертывание

Обзор

Правила, стоящие за этой страницей. Архитектура описывает форму; Навыки определяют решения. Адаптеры относительно профилей — content-profiles. Куда относится новый узел до его создания — placement. Структура репозитория и каждый вид графа — directory-conventions. Формирование и верификация поверхности MCP — mcp-assembly и mcp-contract. При разногласиях между этой страницей и Навыком приоритет имеет Навык.

folio-assistant — это MCP-сервер с подключаемым уровнем адаптеров контента, системой навыков, типизированной объектной моделью контента, RBAC и стратегией развертывания. Контент, с которым он работает, находится в отдельном репозитории — платформа не зависит от контента.

flowchart TD
    subgraph Harness["LLM-харнесс · Claude Code / Antigravity / Gemini"]
      LLM["Агент"]
    end
    LLM <-->|MCP stdio/http| Server["FolioServer · src/server.ts"]
    Server --> Tools["Основные инструменты<br/>check-deps · skill-fetch · preview · preferences · work_plan_prime"]
    Server --> Adapter{"Адаптер контента"}
    Adapter --> Paper["адаптер paper<br/>lean · validate · render"]
    Adapter --> Future["другие адаптеры …"]
    Server --> RBAC["Доступ · src/core/rbac.ts + access.ts → ODRL policies/"]
    Server --> Git["Помощник Git · src/core/git.ts"]
    Server --> Feedback["Хранилище отзывов · src/core/feedback.ts"]
    Tools --> Skills["Пакеты навыков<br/>schemas/skills/*"]
    Paper --> Model["Объектная модель контента<br/>schemas/types.ts · constraints.ts · builders.ts"]

Разделение ответственности — текущее и будущее состояние

Сегодня этот репозиторий представляет собой репозиторий инструментов (Tool repo) и репозиторий контента (Content repo) в одном рабочем каталоге. Задача #223 планирует разделение на пять компонуемых инстансов folio-assistant. Дочерние страницы раскрывают эту тему:

страницана какой вопрос отвечает
Таксономия репозиториевКакие виды репозиториев существуют — Tool, Test, Content, Consumer — и что может содержать каждый из них
Текущее состояниеЧто фактически находится в этом репозитории сегодня (в измеренном виде) и где происходит смешение
Будущее состояниеПять целевых репозиториев и то, какой каталог в какой из них попадает
План миграцииФазы 0/I/II/III, контрольные точки (gates) и то, что пока остается нерешенным
Минимальный cat-harnessЧто сохраняется в харнессе, если применить тест на «несамодокументируемость»
Инстансы харнессаЧем ЯВЛЯЕТСЯ инстанс — схемы, визуализации, инструменты; четыре каталога; рендеринг по умолчанию

Может показаться, что два последних пункта противоречат друг другу: минимальный вариант говорит, что харнесс не создает ничего, на что смотрел бы человек, а страница об инстансах утверждает, что инстанс выполняет рендеринг по умолчанию. На самом деле противоречия нет: требование представляет собой повышающуюся планку, где bootstrap освобожден от визуализатора и взамен обязан предоставлять собственные .json/.jsonld, а cat-harness является тем уровнем, на котором начинает применяться все остальное. См. С чего начинается требование.

В остальной части этой страницы описывается архитектура в ее текущем виде.

Структура репозитория

ПутьЧто здесь находится
src/Сервер MCP (server.ts), точка входа (index.ts), ядро (git, rbac, cache, feedback, logging) и основные инструменты (tools/)
adapters/Адаптеры контента — paper/ (Lean + LaTeX) и отдельный mcp-server/
schemas/Объектная модель контента (types.ts, constraints.ts, builders.ts) и схемы JSON для каждого навыка (schemas/skills/*)
skills/Пакеты навыков (content-lifecycle, authoring-math, authoring-who-smart-guidelines) с их Docker-манифестами
content/Инструменты пайплайна контента (валидаторы, QA, вспомогательные скрипты рендеринга) — но не сам контент
ui/, viewer/, home_page/Веб-интерфейс, интерактивный просмотрщик и пример сайта Pages
deploy/Развертывание (Caddy, docker-compose, провижининг, OAuth)
docs/Этот сайт документации
.github/CI-воркфлоу и скрипты (сборка, публикация, QA, документация)
.claude/skills/Локальные навыки агента + хуки возможностей

Сервер MCP

FolioServer (src/server.ts) регистрирует основные инструменты, затем запрашивает у активного адаптера контента регистрацию его собственных инструментов. Он поддерживает два типа транспорта — --stdio (то, что запускают харнессы) и --http (общий долгоживущий инстанс). Вызовы инструментов логируются с замером времени выполнения.

Адаптеры контента

Адаптер контента инкапсулирует все, что специфично для конкретного типа: какие артефакты существуют, как их валидировать, как их собирать/рендерить и какие дополнительные инструменты MCP регистрировать. Адаптер document (adapters/document/) служит основой для текстовых (прозаических) фолио; адаптер paper (adapters/paper/) расширяет его и предоставляет инструменты жизненного цикла Lean (lean_setup/build/check/status), валидацию и рендеринг (paper_render_pdf/html, formula_render). Для новых типов контента добавляется новый адаптер — см. Добавление типа контента.

Навыки и пакеты навыков

Навык — это задокументированная, ограниченная схемой единица работы (например, lean-formalization). Навыки группируются в пакеты, которые объявляют свои зависимости Docker/среды выполнения через package-manifest.json. LLM обнаруживает навыки с помощью skill_list и загружает инструкции с помощью skill_fetch. Полный список навыков и ролей — а также то, как они компонуются с LLM (RBAC, возможности, требования), — находится на странице Навыки и роли; контракт входных/выходных данных каждого навыка опубликован в Справочнике схем навыков.

Объектная модель контента

Для статей контент представляет собой дерево типизированных блоков, валидируемых во время выполнения с помощью Zod:

  • schemas/types.ts — Block, Section, Chapter, Paper и виды блоков
  • schemas/constraints.ts — схемы Zod и правила ограничений
  • schemas/builders.ts — валидируемые конструкторы (definition(), theorem(), …)

Они задокументированы в сгенерированном Справочнике по TypeScript API.

Управление доступом — ODRL, проверка перед каждой задачей

Существует единая система разрешений, и это W3C ODRL 2.2 (issue #1180): действия в skills/permissions/permissions.json, права в policies/*.jsonld, оцениваемые с помощью permits() / decide() в schemas/odrl.ts. К ней обращаются два вызывающих компонента:

  • Исполнитель BPMN перед каждой задачей и решением (src/workflow/authorize.ts): аутентифицирован ли субъект, подходит ли он для роли данной дорожки, разрешено ли ему выполнять здесь perform-task и имеет ли он право работать с контентом? На сегодняшний день носит рекомендательный характер: deny или несоответствие роли приводят к отказу, а unknown фиксируется в журнале.
  • HTTP-маршруты через src/core/rbac.ts: каждый маршрут указывает действие, которое он выполняет (content-authoring, review-comments, adjudication), а сессии шлюза аутентификации (auth-gateway) объявляются субъектами, чьи права заданы в policies/http-gateway.jsonld. Здесь unknown приводит к отказу.

Вплоть до issue #1207 (2026-09-23) файл rbac.ts представлял собой отдельную иерархическую лестницу viewer < collaborator < owner, а исполнитель ничего не проверял. Данный регламент закреплен в навыке task-authorization.

Прайминг плана работы (между харнессами)

План работы хранится в beans и предоставляется тремя способами, благодаря чему любой харнесс получает идентичный прайминг:

  1. AGENTS.md — статический регламент, нативно считываемый каждым агентом.
  2. Хук SessionStart — каждый харнесс запускает общий скрипт прайминга scripts/session-start-coord-sweep.sh.
  3. MCP-инструмент work_plan_prime — динамический прайминг в реальном времени для любого агента, подключенного к MCP.

Полное описание кросс-агентной архитектуры см. в docs/folio-assistant-migration.md.

Развертывание

deploy/ содержит шаблон обратного прокси Caddy, docker-compose.yml, скрипт провижининга, настройку Google OAuth и скрипт самообновления для запуска общего HTTP-инстанса. Docker-манифесты пакетов навыков объединяют зависимости apt/pip/npm в единый образ для каждого активного набора пакетов.

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev