Введение для агента
Вы — LLM-агент, только что добавленный в репозиторий, использующий folio-assistant. Эта страница поможет вам сориентироваться: что перед вами находится, с чего начать и где искать нужную информацию.
Архитектура навыков, ролей и возможностей описана в документе Навыки и роли. Данная страница представляет собой практическое руководство.
- 1. Определите, в каком репозитории вы находитесь
- 2. Ваши первые пять минут
- 3. Найдите подходящий навык — не импровизируйте
- 4. Объектная модель контента, кратко
- 5. Две связи зависимостей — не смешивайте их
- 6. Отслеживайте работу в beans, а не в голове
- 7. Файлы QA и оси
- 8. Отправка работы
- 9. Где искать информацию
- 10. Привычки, которые уберегут вас от проблем
1. Определите, в каком репозитории вы находитесь
Существует два вида репозиториев, и перепутать их — самая частая ошибка на начальном этапе.
| folio-assistant (платформа) | Фолио (репозиторий контента) | |
|---|---|---|
| Содержит | навыки, схемы, пайплайн, MCP-сервер | саму статью / руководство / IG |
Имеет content/<paper>/ | нет — только content/pipeline/ | да |
| Вы редактируете здесь, чтобы | изменить работу процесса создания контента | изменить то, какой контент создается |
ls content/ # pipeline/ only ⇒ platform; paper dirs ⇒ folio
folio-assistant не содержит контента. Если вы собираетесь добавить в него предметный материал — главу, константу, список ключевых слов главы — вы находитесь не в том репозитории, либо то, что вы пишете, должно быть данными, предоставляемыми фолио. См. §7.
2. Ваши первые пять минут
beans prime && beans list # the work-plan — see §6
scripts/session-start-coord-sweep.sh # CLI-independent equivalent
bun run src/index.ts --check-deps # what this environment can do
Флаг --check-deps важнее, чем кажется. Многие проверки деградируют до n/a,
а не завершаются сбоем при отсутствии какого-либо инструмента (нет инструментария Lean,
нет Atlas, нет LaTeX). Значение n/a не означает успешное прохождение. Если вы
сообщаете, что «все чисто», не зная, что именно было пропущено, вы выдаете отсутствие
данных за результат.
3. Найдите подходящий навык — не импровизируйте
Навыки — это основная единица работы. Прежде чем создавать процедуру вручную, проверьте, существует ли уже готовая.
| Где | Что это дает |
|---|---|
skills/folio-core/ | не зависит от контента: координация, наблюдатели, QA, рендеринг, библиография |
folio-assistant-sci/skills/content/folio-paper-adapter/ | статьи: Lean, LaTeX, доказательства, симуляторы |
smart-base/skills/content/authoring-who-smart-guidelines/ | WHO SMART DAK / IG |
| Справочник по схемам навыков | сгенерированный контракт ввода/вывода для каждого навыка |
| Инструкции по навыкам | сгенерированные полные тексты инструкций |
| Навыки и роли | композиция навыков, ролей и возможностей |
Оба каталога reference/ являются сгенерированными — никогда не редактируйте
их вручную. Перегенерируйте их с помощью bun run scripts/gen-schema-docs.ts и
bun run scripts/gen-skill-docs.ts.
4. Объектная модель контента, кратко
Блок контента представляет собой тройку с общим корневым именем:
<block>.ts manifest — label, kind, uses[], lean.ref, cites[]
<block>.md the narrative a reader actually reads
<block>.lean the formalisation (when the kind requires one)
<block>.qa.json QA sidecar — audit results, per criterion
Манифест .ts — единственный источник истины для структуры. Статус
формализации определяется во время сборки и никогда не хранится в манифесте.
5. Две связи зависимостей — не смешивайте их
Это постоянно сбивает агентов с толку.
uses[]носит редакционный характер. «Что читатель должен был прочесть, чтобы понять этот блок?» Создается автором — поддерживается агентом или человеком.- Формальный граф вычисляется автоматически на основе
lean.refи никогда не пишется вручную.
Они закономерно расходятся в обоих направлениях: доказательство вызывает леммы simp,
о которых читателю не нужно знать; теорема мотивируется примером, на который она
формально никогда не ссылается.
Никогда не заполняйте uses[] из Lean. Это разрушает сигнал, на основе которого
рассчитывается любая метрика упорядочивания. Для анализа влияния («что сломается, если это
изменится?») используйте объединение:
bun run content/pipeline/content-graph.ts content/<paper>
Аудит правильности использования uses[] — отдельный навык:
uses-editorial-review, плюс механическая ось QA uses.
6. Отслеживайте работу в beans, а не в голове
beans — это единственный механизм задач — как локальный для сессии, так и
межагентский. Каталог beans/ фиксируется в репозитории, поэтому план сохраняется при
возобновлении работы в чистом контейнере.
beans list
beans create "<title>"
beans update <id> --status in-progress # CLAIM before you work
Резервируйте (claim) задачу перед началом работы, чтобы две сессии не взяли один и тот
же элемент, и никогда не закрывайте и не удаляйте bean другого агента. Не создавайте
параллельное хранилище задач. Не используйте beans create для массовых машинно-генерируемых
очередей (*.qa.json, файлы свидетельств) — они остаются в виде массового JSON.
Полные правила работы: skills/sdlc/sdlc-core/todo-manager.md,
skills/sdlc/sdlc-core/bean-coordination.md.
7. Файлы QA и оси
Каждый блок может сопровождаться файлом <block>.qa.json, фиксирующим по каждому
критерию найденное рецензентом — script, agent или human. Записи содержат
хеши исходных файлов на момент аудита, поэтому при редактировании блока запись
становится устаревшей (stale) и требует повторной проверки.
Критерии сгруппированы по осям (proof, voice, detangler,
uses, canonical, compute, bibliography, …). Запуск проверки:
bun run content/pipeline/qa-sweep.ts --axis uses content/<paper>
bun run content/pipeline/qa-staleness.ts content/<paper>
Некоторые критерии имеют automated: true (решение принимает скрипт), а некоторые —
automated: false (решение должен принимать агент или человек). Второй тип
требует реальных затрат шагов диалога — см. semantic-cone.ts для ограничения их области
только тем, на что они действительно могут повлиять.
Опциональные для фолио оси. Ось, кодирующая специфику предметной области фолио, регистрируется только в том случае, если фолио явно ее подключает:
// <name>.config.json
{ "qaAxes": ["q-usage"] }
Аналогично, специфичные для фолио данные должны находиться в фолио, а не на платформе —
например, content/<paper>/topic-keywords.json управляет проверкой
detangler-topic-coherence, и при его отсутствии средство проверки сообщает n/a.
8. Отправка работы
/prepare-merge [base]
Запускает общий сценарий плюс проверки для конкретного типа контента (paper → content_validate / qa_sweep / proof_status / latex_preflight / lean_build), затем выполняет push. Слияние (merge) при этом не выполняется.
Отслеживание связанного PR коллеги: /watch <pr|branch>.
9. Где искать информацию
| Вопрос | Ответ |
|---|---|
| Команды проекта, соглашения | AGENTS.md (общий источник истины для агентов) |
| Что делает навык | skills/**/ или сгенерированные тексты инструкций |
| Типизированный контракт навыка | Справочник по схемам навыков |
| Что означает критерий QA | content/pipeline/qa-criteria-registry.ts — описания служат спецификацией |
| Схема блока | schemas/types.ts |
| Схема файла QA | schemas/block-qa.ts |
| Что умеет данное окружение | .claude/skills/capabilities/*.json, --check-deps |
| План развития инструментов Lean | Предложение по инструментам Lean |
10. Привычки, которые уберегут вас от проблем
n/aне означает успешное прохождение. Указывайте, что именно было пропущено и почему.- Резервируйте bean перед длительной работой. Параллельно могут выполняться другие задачи.
- Не прописывайте имя статьи жестко в коде. В фолио их может быть несколько; определяйте
через
findPapers()/soleFolioPaper()изcontent/pipeline/repo-root.ts. - Не пишите контент в репозиторий платформы. Если упоминается глава, константа или терминологический словарь — это данные фолио.
- Перегенерируйте, а не редактируйте вручную все, что находится в каталоге
docs/reference/. - Прочтите описание критерия перед тем, как реагировать на замечание. В нем указаны критичность, назначение и то, что явно не считается нарушением.