English · Русский

Уроборос

Показывает, как код исполнялся на самом деле: какие функции звались, с какими доводами, что вернули и что бросили.

Инструмент дописывает в исходник запись о вызовах. Программа запускается как обычно, и каждый вызов оставляет две строки JSON — на входе и на выходе.

Языки: Python, JavaScript/TypeScript, C, C++, Elixir, Go, Java, C#. Схема записи у всех одна.

Четыре шага

Поставить:

uv tool install git+https://github.com/digitable-lol/ouroboros

Дописать запись о вызовах:

ouroboros wrap-file stats.py

{"ok": true, "path": "stats.py", "language": "python", "functions_wrapped": 3, "runtime_header": "ouroboros_runtime.py"}

Запустить как обычно:

python3 stats.py

Прочитать:

ouroboros trace debug.info --outcome raised

    {
      "index": 5,
      "started": "2026-08-28T23:39:45.166",
      "call_id": "ef71eb89-6727-4cdf-a3b7-2ea54cff81e3",
      "name": "average",
      "args": "[]",
      "kwargs": "",
      "outcome_kind": "raised",
      "outcome": "ZeroDivisionError: division by zero",
      "duration": 3e-06,
      "cpu": null,
      "thread": "2864987.129949101195776"
    }

args: "[]" — вот чего нет в отслеживании стека. Стек говорит, где сломалось; запись говорит, с чем позвали.

Полностью, с исходником и выводом каждого шага, — в README хранилища.

Что лежит в `debug.info`

Только дописываемый файл, по одному объекту JSON в строке. Две строки на вызов, связанные общим id:

{"p":"in","t":"2026-08-28T23:39:45.166","id":"e668ee33-…","ci":-1,"th":"2864987.129949101195776","fn":"average","a":"[12, 30, 18]","k":""}
{"p":"out","id":"e668ee33-…","fn":"average","r":"20.0","d":2e-06}

Отсюда самый дешёвый ответ на вопрос «где висит»: строка входа без парной строки выхода — вызов вошёл и не вернулся. Полный разбор ключей.

Страницы

страница	о чём
Установка	uv, Homebrew, asdf, из исходников, подключение сервера MCP
Начало работы	все команды, порядок работы, на чём спотыкаются
Прологировать чужой код	по шагам: что делать, что видишь, как читать
Чтобы ИИ понимал, как код исполняется	сервер MCP и его 17 инструментов
Обычная разработка	молчащая программа, регрессия, чего не стоит делать
Языки	восемь языков, чем они отличаются в записи
Замеры	что каждый язык записывает, чего это стоит, как повторить
Границы	чего инструмент не делает — самая важная страница
В чём смысл	зачем нужен и какую работу снимает
Как это выглядит	записи, сводка, настройка — целиком
Справочник средств MCP	все 17 средств, снятые живым разговором с сервером

Если читать только одно

Читайте Границы.

Записи фиксируют, как код себя вёл, а не как он должен себя вести.

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

Состояние

В хранилище лежит рабочий инструмент, а не только его описание: пакет ouroboros-logger 0.6.1, командная строка на 17 команд, сервер MCP на 17 средств, 1257 проверок. Всё, что показано на страницах, — вывод настоящих прогонов на обычной машине с Linux; выводы всех восьми языков сняты по отдельности, и их можно снять заново одной командой — Замеры.

Установка проверена целиком, а не «по виду правильно»: uv tool install, brew install digitable-lol/tap/ouroboros вместе с brew test, asdf plugin add вместе с asdf install — и после каждой поставленный инструмент обмазывал файл, запускал его и читал записи.

Что известно сломанным: обмазка — правка исходника, а не наблюдение со стороны, и она умеет менять поведение программы, а не только время её работы. Проверенные случаи, то, что уже починено, и то, что остаётся как есть осознанно, собраны в Границах. Числа к ним — в Замерах.

Хранилище целиком: digitable-lol/ouroboros.