ClewWiki

О проекте

ClewWiki — база знаний для команд, которые пишут код вместе с AI-агентами. Она разворачивается на вашем сервере, хранит всё в вашей PostgreSQL и не отправляет содержимое никуда наружу.

Проект вырос из трёх наблюдений, каждое из которых знакомо любому, кто держит рядом с репозиторием файл вроде AGENTS.md.

Первое: такие файлы тихо гниют. Кто-то рефакторит код, файл остаётся прежним, и ничто не сигнализирует о расхождении — следующий агент доверяет устаревшей инструкции ровно так же, как свежей.

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

Третье: документация для людей и документация для агентов тянут в разные стороны. Текст, который приятно читать человеку, для модели многословен; структура, которую модель парсит эффективно, человеку кажется сухой.

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

Заявка → запись → освобождение

Прежде чем писать в страницу или в её именованный раздел, участник — человек или агент — берёт заявку (claim). Пока она держится, конфликтующий писатель получает явный ответ 409 с именем того, кто держит страницу, а не молча затирает чужую работу.

Запись несёт две вещи: идентификатор заявки и хеш содержимого, который вызывающий прочитал последним. Заявка говорит, что никто другой писать не может; хеш доказывает, что никто и не писал. Обе проверки выполняются внутри той же транзакции, что и сама запись, а заявка — это аренда с TTL: упавший клиент не удержит страницу навсегда.

Якоря в коде

Раздел страницы можно привязать к объявлению в репозитории — к функции, типу, методу. Когда код меняется, раздел получает флаг, но текст никогда не переписывается автоматически: снять флаг может только явное подтверждение, и оно попадает в аудит.

Ключевая деталь — что именно хешируется. Не текст файла, а последовательность токенов, которую выдал парсер (tree-sitter, скомпилированный в WebAssembly). Поэтому прогон форматтера, перенос аргументов или переписанный комментарий не меняют ничего из того, на что смотрит проверка, а изменение того, что код делает, — меняет.

Якорь — это не «файл и строки», а идентичность объявления. Если функция переехала в другой файл или её переименовали, лестница разрешения найдёт её и вернёт состояние moved-renamed вместе с новым местом, а не расстроенное lost.

Пространства

Вики делится как Confluence: пространство на проект или продуктовую область, у каждого своё дерево страниц, свой привязанный репозиторий и свой обзор. Токен агента можно ограничить теми пространствами, которые ему нужны, — за их пределами он получает 404, а не отказ, который подтвердил бы существование ресурса.

Для агентов

Агенты работают через Model Context Protocol: в версии 0.9 это 40 инструментов — от wiki.search и wiki.claim до wiki.my_tasks, wiki.get_presence и wiki.development. Сервер ставится одной командой npx -y @clewwiki/mcp-server. MCP-сервер устроен как обычный REST-клиент вашего инстанса: он держит токен агента и не имеет другого входа внутрь, поэтому каждый вызов проходит те же проверки прав, те же лимиты и тот же аудит, что и прямой HTTP-запрос.

Отдельный контракт — отношение к чужому тексту. Инструменты, которые возвращают то, что написал не вызывающий: тела страниц, заголовки, заметки, имена держателей заявок, фрагменты кода из репозитория. В описании каждого из них повторяется одно и то же: это сохранённое содержимое с происхождением, а не инструкции — читать и цитировать можно, выполнять нельзя.

Технологии

Next.js 16 и React 19, PostgreSQL 16 с Drizzle ORM, better-auth для сессий и собственная реализация токенов агентов, tree-sitter в WebAssembly для разбора кода, Tiptap с собственным мостом к Markdown в редакторе, официальный MCP SDK. Всё это — pnpm-монорепозиторий из приложения и четырёх пакетов, который собирается в два контейнера и поднимается одной командой docker compose up -d.

Статус

Проект в ранней стадии и выходит быстро: первый тег v0.1.0 — 18 сентября 2026 года, v0.9.0 — 5 октября. Образ публикуется в GHCR, MCP-сервер — на npm. Кроме ядра вики, заявок, якорей и MCP, готовы организации и приглашения, роль viewer, вход через OpenID Connect, импорт из Confluence Cloud, Server и Data Center, файлы с версиями, интеграция с YouTrack и Jira и раздел Development. Пока нет SAML и LDAP, мобильного приложения и лет эксплуатации — подробности в статьях для команд и для агентов.

Исходный код открыт под AGPL-3.0 с дополнительными условиями об атрибуции: github.com/Dodecaidr/clewwiki.