slivingdoc

Тестовое покрытие: 83.7% 😍👌

Возможности

• Семантика, подобная Git: slivingdoc использует терминологию, которую знаем мы (и агенты), разработанную для простоты использования

• Автоматическое разрешение конфликтов: фиксируйте изменения без страха, доверяя, что все конфликты должны быть разрешены перед принятием

• Высокоскоростная обработка: решение концептуально довольно простое, что позволяет достичь очень высокой масштабируемости и параллелизма

• Включай и работай: настройте хранилище, укажите на него и начинайте синхронизировать заметки!

docs/slivingdoc-v1.md — это полный принятый контракт, лежащий в основе этих гарантий.

Related MCP server: Cellar

Начало работы

Добавьте его в свою агентскую обвязку:

{
  "mcpServers": {
    "slivingdoc": {
      "command": "npx",
      "args": [
        "-y",
        "slivingdoc",
        "serve",
        "--bucket",
        "my-notes",
        "--workspace-root",
        "/srv/notes"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "<your-access-key-id>",
        "AWS_SECRET_ACCESS_KEY": "<your-secret-access-key>",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Хранилище должно существовать, а учетные данные берутся из стандартной цепочки AWS. Нет аккаунта S3? examples/seaweedfs/ запускает локальный контейнер SeaweedFS с пошаговым руководством. Вы также можете загрузить нативный бинарник напрямую из релиза GitHub (slivingdoc-v<semver>-<os>-<arch>) и запустить его на месте.

Поддерживаемые платформы: Linux (amd64, 32-битный ARMv7, arm64), macOS (amd64, arm64) и Windows (amd64). 32-битный артефакт Linux ARM поддерживает Raspberry Pi OS armhf.

Как это работает

Сервер предоставляет два инструмента MCP через stdio:

notes_pull записывает текущий блокнот в ваш каталог. notes_commit публикует ваши изменения и включает параллельные неконфликтующие изменения. Между вызовами протокол отсутствует — агенты редактируют файлы с помощью уже имеющихся у них инструментов, а люди могут писать в том же каталоге любым редактором. Следующая фиксация также перенесет их изменения.

Люди также могут выполнять обе операции напрямую, без хоста MCP. Относительный путь разрешается относительно рабочего каталога:

slivingdoc pull notes
# edit UTF-8 text files under notes/
slivingdoc commit notes -m "meeting summary"

При успехе выводится унифицированный отчет о результате: статус OK, принятая удаленная генерация, количество вставок и удалений по файлам, а также итоговый блок. Ошибка домена завершается с ненулевым кодом и выводит откровенный отчет: категория ошибки, вердикт о повторяемости и каждый конфликтующий файл с диапазонами строк. Цвет отображается только на реальном терминале и отключается любым непустым NO_COLOR.

Часть с git

Если позволить всем агентам писать одновременно, это сработает, но они столкнутся с состояниями гонки. Поэтому slivingdoc имеет встроенный git через libgit2, который эффективно делает:

1. git pull

2. (потенциальное разрешение конфликтов локально)

3. git add .

4. git commit -m "<сообщение агента>"

5. git push

6. (потенциальное разрешение конфликтов локально)

Все эти операции git выполняются локально в частном зеркале каталога заметок, оставляя "оптимизированную" последовательность git. Это работает благодаря двум компромиссам: во-первых, локальный каталог заметок может быть изменен при notes_pull, приоритет отдается удаленному состоянию, оставляя маркеры конфликтов. Во-вторых, система работает только с текстом (чистый UTF-8).

Конфигурация

serve, pull и commit читают одни и те же флаги и переменные окружения. --bucket обязателен. Наиболее распространенные флаги:

slivingdoc serve -h выводит полную справку, а docs/running.md охватывает все, что нужно оператору: все флаги, точные разрешения S3, журналирование (LOG_LEVEL в stderr), правила блокнота, восстановление после конфликтов и хранение контрольных точек. Модуль Terraform в terraform/ подготавливает хранилище и пользователя IAM с минимальными привилегиями для одного блокнота.

Разработка

• AGENTS.md — руководство для разработчика и агента: карта пакетов, потоки операций, соглашения и шлюзы контроля качества.

• docs/slivingdoc-v1.md — принятый архитектурный контракт.

• docs/build.md — нативная сборка, от закрепленного исходного кода libgit2 до проверки зависимостей.

• docs/testing.md — команды тестирования, уровни тестирования и правило "без живого AWS".

• docs/releasing.md — артефакты релиза, доверенная публикация npm и make release.

make qa #lint plus the full Go and npm test suites

Лицензия

MIT — см. LICENSE. Уведомления третьих сторон для статически связанной libgit2 находятся в NOTICE.

Не аффилировано с Пэрис Хилтон.