Перейти к основному содержимому

Задачи: обзор

Что это​

Задачи — это операционный журнал работы (task ledger), отдельный от канонических знаний. В нём вы фиксируете, что нужно сделать: заголовок, описание, приоритет, зависимости и текущее состояние. Раздел «Задачи» в интерфейсе показывает журнал в виде доски, а из терминала с ним работают команды группы task.

Ключевое архитектурное решение (ADR-015): активность по задачам живёт в собственном append-only журнале с отдельным атомарным указателем CURRENT в ops/task-ledger/. Прогресс задач никогда не меняет указатель знаний ledger/CURRENT. Так объём и «шум» рабочих задач не приводит к пересчёту и переинвалидации канонических поколений знаний.

Чем задачи отличаются от знаний​

  • Знания — это проверенное каноническое содержание (сырьё → нормализация → предложение → валидация → промоушен → леджер знаний → материализованный Markdown + индексы). Оно меняется только через операции знаний.
  • Задачи — это оперативная координация. Каждая задача содержится в отдельном объекте, адресуемом по содержимому (content-addressed), а её история — это неизменяемая цепочка событий. Задачи не публикуют и не редактируют знания.

Оба журнала местные (local-first) и работают только на петле обратной связи 127.0.0.1.

Как это устроено​

  • Неизменяемая история. Каждое создание задачи или смена состояния добавляет новое событие и новое поколение доски. Прошлые объекты, события и поколения не переписываются — их можно только дополнить новыми.
  • Идемпотентность. Каждая команда несёт ключ идемпотентности. Повтор той же команды с тем же ключом возвращает прежний результат как no_op, а не создаёт дубль. Тот же ключ, использованный для другой команды, отклоняется как конфликт (см. src/raytsystem/tasking.py).
  • Защита от гонок. Команды принимают ожидаемый идентификатор поколения (expected_generation_id). Если доска изменилась, запись падает с конфликтом поколений — вы перечитываете доску и повторяете действие.

Когда использовать​

  • Ведите список работ по проекту, не смешивая его с каноническими знаниями.
  • Отслеживайте прогресс через явные состояния (см. жизненный цикл задачи).
  • Просматривайте текущую доску в UI или запрашивайте её из CLI для скриптов и проверок.

Пример​

Прочитать доску (только чтение, ничего не меняет):

uv run raytsystem task list --json

Создать задачу в операционном журнале:

uv run raytsystem task create "Проверить свежесть индекса" --idempotency-key task-2026-07-12-a

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

task list возвращает снимок текущего поколения доски со списком задач и идентификатором поколения. task create возвращает результат команды: новую задачу, идентификатор события и идентификатор нового поколения.

Ограничения и безопасность​

  • Задачи не дают агентам права выполнять код: назначение цифровых сотрудников и managed workspaces находятся за флагами и по умолчанию отключены (см. назначения и workspaces).
  • HTTP-слой никогда не принимает путь файловой системы, cwd или команду; UI работает с типизированными идентификаторами.
  • Полезная нагрузка задачи проходит проверку чувствительности (secret-scan) и отклоняется, если содержит секреты.

Связанные страницы​

Источники истины​

  • src/raytsystem/tasking.py
  • ops/decisions/ADR-015-local-web-control-plane-and-task-ledger.md
  • src/raytsystem/cli.py