Pindoc

License MCP

Командная память с привязкой к коду для разработки с помощью AI. Агенты создают долговечные записи; люди проверяют, обсуждают и направляют их.

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

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

Зачем это нужно

Сеансы программирования с AI продуктивны, но контекст команды все равно теряется:

путь отладки исчезает вместе с сеансом терминала,
одно и то же решение приходится объяснять каждому новому агенту,
полезная аналитика остается в чате одного оператора, вместо того чтобы стать общим знанием команды,
дублирующиеся документы накапливаются в вики, трекерах задач, PR и сообщениях коммитов,
в реальных проектах человек, обнаруживший проблему, не всегда может сразу изменить код; структурированные доказательства помогают команде обсудить и принять решение.

Pindoc превращает работу агентов, которую стоит сохранить, в доступную для поиска командную память с привязкой к коду. Следующий участник команды или AI-агент может спросить Pindoc о том, что важно, прежде чем вносить изменения.

Что отличает Pindoc

Слой коллективной памяти: артефакты пишутся для товарищей по команде и будущих агентов, а не как личные сводки чатов.
Поверхность записи только для агентов: интерфейс чтения (Reader UI) предназначен для чтения и проверки; долговечные записи создаются агентами.
Рабочий процесс на базе MCP: такие инструменты, как pindoc.context_for_task, pindoc.artifact.propose и pindoc.task.queue, регулируют поведение агента, а не просто выступают в роли тонкого CRUD API.
Типизированные артефакты: Decision (Решение), Analysis (Анализ), Debug (Отладка), Flow (Поток), Task (Задача), TC, Glossary (Глоссарий) и типы доменных пакетов.
Память с привязкой к коду: артефакты могут указывать на коммиты, файлы, диапазоны строк, ресурсы, URL-адреса и связанные артефакты.
Создано для сохранения ценных данных: Pindoc избегает хранения «сырых» архивов чатов и сохраняет только решения, аналитику, пути отладки, верификацию и контекст задач, имеющие ценность в будущем.
Демон для нескольких проектов: одна конечная точка /mcp может обслуживать несколько проектов; каждый вызов инструмента содержит project_slug.
Приоритет самостоятельного хостинга: Docker Compose запускает Postgres, pgvector, демон Pindoc и SPA-интерфейс для чтения.

Публичная демо-версия

Публичная демо-версия только для чтения находится в планах и не является частью этого релиза с открытым исходным кодом. До ее выхода README, docs/ и клон для самостоятельного хостинга являются основным доказательством. Операторы, желающие оценить Pindoc от начала до конца, могут запустить docker compose up -d --build и изучить свои собственные артефакты.

План последующей демо-версии находится в Public Demo Plan на случай, если потребуется размещенный экземпляр.

Быстрый старт

Предварительные требования:

Docker 27+
Рекомендуется 2 ядра CPU и 4 ГБ оперативной памяти для локального использования или небольших команд
Рекомендуется 5 ГБ свободного места на диске для образов Docker, данных Postgres и кэша эмбеддингов; 2 ГБ — минимум для свежего клона
Исходящий HTTPS при первом запуске, чтобы модель EmbeddingGemma и среда выполнения могли быть кэшированы
Go 1.25+ только для разработки на хосте
Node 20.15+ и pnpm 10+ только для веб-разработки вне Docker

Путь Docker по умолчанию включает семантический поиск через встроенный провайдер EmbeddingGemma Q4 ONNX, поэтому дополнительный контейнер для эмбеддингов не требуется. См. System Requirements для минимальных и рекомендуемых профилей развертывания.

git clone https://github.com/var-gg/pindoc.git
cd pindoc
docker compose up -d --build

Откройте Reader:

http://localhost:5830/

На новом экземпляре / перенаправляет на мастер настройки первого проекта. Чтобы открыть этот мастер напрямую:

http://localhost:5830/projects/new?welcome=1

Подключение MCP-клиента

Демон Docker предоставляет одну конечную точку MCP на уровне учетной записи:

{
  "mcpServers": {
    "pindoc": {
      "type": "http",
      "url": "http://127.0.0.1:5830/mcp"
    }
  }
}

Область проекта не закодирована в URL. Агенты передают project_slug при вызове инструментов, относящихся к проекту. Рабочие области, созданные с помощью pindoc.harness.install, сохраняют этот slug в метаданных PINDOC.md.

Типичные рабочие процессы

Попросите агента начать работу с контекстом проекта:

Use Pindoc context before editing. Find the current project, inspect assigned
Tasks, then implement the next acceptance item.

Типичный цикл MCP:

pindoc.workspace.detect
pindoc.task.queue
pindoc.context_for_task
работа с кодом или документацией
pindoc.artifact.propose
обновление состояния принятия и закрытия задачи

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

Путь Docker по умолчанию предназначен для одного пользователя и только для локального доступа:

Переменная	По умолчанию	Назначение
`PINDOC_DAEMON_PORT`	`5830`	Порт хоста, используемый Docker Compose.
`PINDOC_PROJECT`	`pindoc`	Проект по умолчанию для чтения без указания области/конфигурации.
`PINDOC_PUBLIC_BASE_URL`	`http://127.0.0.1:${PINDOC_DAEMON_PORT}`	Публичный базовый URL, используемый в сгенерированных ссылках и метаданных OAuth.
`PINDOC_BIND_ADDR`	`127.0.0.1:5830`	Настройки безопасности. Значения, отличные от локальных, требуют IdP или явного разрешения публичного доступа без аутентификации.
`PINDOC_AUTH_PROVIDERS`	пусто	Провайдеры идентификации, включенные для внешних запросов. Текущий провайдер: `github`.
`PINDOC_ALLOW_PUBLIC_UNAUTHENTICATED`	`false`	Явное разрешение для внешнего доступа без IdP. Используйте только за доверенной сетью/обратным прокси.
`PINDOC_FORCE_OAUTH_LOCAL`	`false`	Флаг разработки, который направляет локальные вызовы `/mcp` через OAuth bearer auth для локального QA.

Не открывайте записывающий демон в публичный интернет без провайдера идентификации. Для публичной демо-версии только для чтения заблокируйте /mcp и изменяющие HTTP-маршруты на обратном прокси; см. SECURITY.md и docs/22-public-demo.md.

Для записываемого публичного или кросс-устройственного экземпляра следуйте docs/oauth-setup.md. Там описана настройка GitHub OAuth App, правило обратного вызова ${PINDOC_PUBLIC_BASE_URL}/auth/github/callback, регистрация MCP-клиента во время выполнения и локальное QA OAuth с помощью PINDOC_FORCE_OAUTH_LOCAL.

Разработка

# Run Go tests. Integration tests that need Postgres are skipped unless
# PINDOC_TEST_DATABASE_URL is set.
go test ./...

# Web checks.
cd web
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test:unit
pnpm build

# Full image build.
docker build -t pindoc-server:local .

Чтобы протестировать путь OAuth bearer локально, оставаясь подключенным через 127.0.0.1, установите PINDOC_FORCE_OAUTH_LOCAL=true; демон выдаст предупреждение при загрузке и потребует Bearer-токены для локальных вызовов /mcp.

На хостах Windows без локальной цепочки инструментов C запускайте тесты Go через Docker:

docker run --rm -v "${PWD}:/work" -w /work golang:1.25 go test ./...

Документация

Статус

Pindoc находится в стадии активного внутреннего использования. Реализованы путь локального хостинга, интерфейс Reader, модель проектов/областей, поток предложений артефактов, очередь задач, история изменений, сводки и реальный путь провайдера эмбеддингов. Публичный запуск OSS сосредоточен на надежности первого запуска, демо-версии только для чтения, CI, документации по безопасности и более четком позиционировании для совместной работы.

Лицензия

Apache License 2.0. См. LICENSE.

pindoc