Doco

📖 中文版

Пространство документов, где люди и ИИ-агенты пишут вместе. Открытый редактор форматированного текста для совместной работы, который возвращает ваши данные под ваш контроль — и так же бережно относится к вашим ИИ-агентам: стабильная адресация на уровне блоков, оптимистичное управление конкурентностью и MCP-сервер с 29 инструментами, чтобы агенты читали и писали в вашу базу знаний так же безопасно, как аккуратный редактор-человек.

• Размещение: doco.page — бесплатно в период беты

• Подключите агента: claude mcp add doco -- npx -y --package doco-agent-cli doco mcp

• CLI: npm i -g doco-agent-cli && doco login

• npm: doco-agent-cli · Документация API: doco.page/api-docs

Почему агентам здесь безопасно

Related MCP server: session-coord-mcp

Возможности

Возможности редактирования

• Форматированный текст: заголовки, списки, цитаты, списки задач, блоки кода (подсветка синтаксиса), таблицы, изображения, ссылки, стили текста и другое

• Слеш-команда /: введите /, чтобы открыть палитру команд с нечётким поиском — поддерживает пиньинь-сокращения для китайских пользователей

• Плавающая панель инструментов: автоматически появляется при выделении текста, все действия по форматированию в двух сантиметрах от курсора

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

• Сворачиваемые секции: сворачивайте секции, с которыми не работаете; состояние сворачивания сохраняется между сеансами

• Автоматическая нумерация заголовков: переключение в один клик — заголовки H1–H4 автоматически поддерживают иерархическую нумерацию (1. 1.1 1.1.1)

• Горячие клавиши: ⌥↑/↓ — перемещение блоков, ⌘D — дублирование блоков, ⌘⌥1/2/3/0 — переключение уровней заголовков

Текст в диаграмму

Пишите исходный код Mermaid или PlantUML прямо в документе. Диаграммы отображаются на месте. Двойной клик для редактирования, полноэкранный режим, масштабирование щипком — больше никаких циклов «экспорт—импорт—замена» с draw.io.

• Mermaid: блок-схемы, диаграммы последовательности, диаграммы классов, диаграммы Ганта, диаграммы состояний и другие

• PlantUML: диаграммы последовательности, диаграммы классов, диаграммы вариантов использования, диаграммы компонентов и другие

Электронные таблицы

Полноценный табличный движок, встроенный в ваши документы:

• Вычисление формул, форматирование ячеек

• Закрепление областей, сортировка и фильтрация

• Объединение / разделение ячеек

• Импорт / экспорт CSV

Используйте её как встроенный блок контента или выносите в отдельную полноэкранную таблицу.

База знаний

• База знаний → Папки (вложенные) → Документы — трёхуровневая структура

• Перетаскивание для изменения порядка, переименование и перемещение на боковой панели

• Экспорт всей базы знаний в ZIP с сохранением иерархии папок и включёнными изображениями

• Перенос без потерь в нативном .doco.zip для документа, папки или всей базы знаний

Совместная работа в реальном времени

Построено на алгоритме CRDT Yjs:

• Нет кнопки сохранения — изменения синхронизируются автоматически

• Офлайн в первую очередь: IndexedDB браузера — основное хранилище; на сервере хранится снимок. Редактируйте без сети, изменения автоматически объединятся при восстановлении соединения

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

Импорт / экспорт

API · MCP · CLI

Три канала, один контракт:

• REST API: спецификация OpenAPI 3.1, аутентификация по Bearer Token, версионирование через ETag, пагинация по курсору, ключи идемпотентности

• MCP-сервер: doco mcp (поставляется внутри doco-agent-cli) — 29 инструментов плюс ресурсы doco://

• doco CLI: login / whoami / docs / blocks / edit / mcp, глобальный --json, при записи автоматически учитывает ETag/If-Match

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

Технологический стек

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

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

• Node.js >= 18

• pnpm

Установка и запуск

# Install frontend dependencies
pnpm install

# Install backend dependencies
cd backend && npm install && cd ..

# Start the frontend dev server (Vite, default :5173)
pnpm run dev

# In another terminal, start the backend (Express + WebSocket, default :8000)
cd backend
npm run dev

Откройте http://localhost:5173 — страница автоматически подключится к WebSocket-сервису бэкенда.

Развёртывание в Docker (рекомендуется)

Полный комплект для самостоятельного размещения включает фронтенд Caddy, бэкенд совместной работы Node.js, постоянное хранилище SQLite, проверки работоспособности и WebSocket-прокси с тем же origin. Публичные образы поддерживают linux/amd64 и linux/arm64.

git clone https://github.com/songofhawk/doco.git
cd doco
cp .env.docker.example .env.docker

# Review .env.docker first, then start with prebuilt Docker Hub images
docker compose --env-file .env.docker up -d

# Verify the deployment
docker compose --env-file .env.docker ps
curl --fail http://localhost:8080/healthz

По умолчанию откройте http://localhost:8080. Задайте значения ALLOWED_ORIGINS, COOKIE_SECURE, Google OAuth и SMTP в файле .env.docker для вашего окружения. Эти значения внедряются при запуске контейнеров и не включаются в образы. Данные приложения хранятся в именованном томе doco-data.

Docker Hub: songofhawkg/doco-frontend · songofhawkg/doco-backend

Чтобы собрать те же образы из исходного кода:

docker compose --env-file .env.docker up -d --build

Все параметры конфигурации, HTTPS, журналы, резервное копирование, восстановление и обновления см. в руководстве по развёртыванию Docker. Не запускайте docker compose down -v, если вы не планируете удалять базу данных и вложения.

Ручная сборка и развёртывание

# Frontend build
pnpm run build          # output → dist/
pnpm run deploy         # deploy to Cloudflare Pages

# Backend (production)
cd backend
npm start

Структура проекта

doco/
├── src/
│   ├── main.tsx                      # App entry point
│   ├── App.tsx                       # Root component, routing, import/export
│   ├── components/
│   │   └── Sidebar.tsx               # KB sidebar (document tree)
│   └── editor/                       # Editor module
│       ├── index.ts                  # Entry, exports DocoEditor component
│       ├── DocoEditor.tsx            # Editor core (Yjs/Hocuspocus init, extension registration)
│       ├── types.ts                  # DocoEditor Props/Ref type definitions
│       └── components/
│           ├── BubbleMenu.tsx        # Selection floating toolbar
│           ├── BlockHandle.tsx       # Block drag handle
│           ├── SlashCommand.ts       # / command palette
│           ├── CommandList.tsx       # Command palette UI
│           ├── suggestions.ts        # Command menu data
│           ├── CollapseExtension.ts  # Block collapse extension
│           ├── DocSettings.tsx       # Document settings (heading numbering, background)
│           ├── MermaidBlock.ts       # Mermaid node definition
│           ├── MermaidComponent.tsx  # Mermaid renderer
│           ├── PlantUMLBlock.ts      # PlantUML node definition
│           ├── PlantUMLComponent.tsx # PlantUML renderer
│           ├── CalloutBlock.ts       # Callout block definition
│           ├── CalloutComponent.tsx  # Callout renderer
│           ├── SpreadsheetBlock.ts   # Spreadsheet node definition
│           ├── SpreadsheetComponent.tsx  # Spreadsheet renderer
│           ├── spreadsheetEngine.ts  # Spreadsheet calculation engine
│           ├── WeChatExportDialog.tsx # WeChat Official Account export
│           ├── KeyboardShortcuts.ts  # Keyboard shortcuts
│           ├── TableOfContents.tsx   # Table of contents
│           ├── CodeBlockComponent.tsx # Code block (highlight + copy)
│           └── ImageComponent.tsx    # Image renderer
├── backend/
│   ├── server.js                     # Entry: Express + Hocuspocus + export routes
│   ├── database.js                   # better-sqlite3 init & schema
│   ├── api.js                        # KB / folder / document REST API
│   ├── auth.js                       # Auth (OAuth + Email + API Token)
│   ├── markdown.js                   # YDoc → Markdown server-side export
│   ├── permissions.js                # Permission management
│   ├── quota.js                      # Quota management
│   ├── openapi.js                    # OpenAPI spec definition
│   └── tests/                        # Backend tests
└── docs/                             # Design docs & proposals

Автономный фронтенд-компонент

Ядро редактора также публикуется как doco-text-editor. Оно включает все возможности редактирования Doco и встроенные стили, но не зависит от аутентификации Doco, REST API, сервисов совместной работы или IndexedDB. Хост-приложение решает, где будет храниться контент: в памяти, в хранилище браузера, в собственном бэкенде или во внешней системе, такой как ClickUp.

npm install doco-text-editor

import { useRef } from 'react'
import {
  DocoTextEditor,
  type DocoTextEditorRef,
} from 'doco-text-editor'
import 'doco-text-editor/style.css'

const editorRef = useRef<DocoTextEditorRef>(null)

<DocoTextEditor
  ref={editorRef}
  defaultValue="# Browser-only draft"
  format="markdown"
  onChange={({ steps }) => {
    // Only the ProseMirror steps changed by this transaction.
    queueIncrementalChanges(steps)
  }}
/>

// Read the complete document only when needed.
const json = editorRef.current?.getContent('tiptap-json')
const markdown = editorRef.current?.getContent('markdown')
const html = editorRef.current?.getContent('html')
const text = editorRef.current?.getContent('text')

Пакет включает заголовки, встроенное форматирование, цитаты, упорядоченные/неупорядоченные списки и списки задач, блоки кода, изображения, таблицы, выноски, Mermaid, опциональный рендеринг PlantUML и встроенные электронные таблицы. Полное API и примечания по интеграции см. в src/editor/README.md.

Полное использование компонента редактора Doco

import { DocoEditor } from './editor'
import type { DocoEditorRef } from './editor/types'

const editorRef = useRef<DocoEditorRef>(null)

<DocoEditor
  ref={editorRef}
  docId="doc-001"
  userId="user-001"
  collaboration={{
    websocketUrl: 'ws://localhost:8000',
  }}
  onTitleChange={(docId, title) => console.log('Title changed:', title)}
  placeholder="Start writing…"
/>

{/* Call export methods via ref */}
<button onClick={() => editorRef.current?.exportMarkdown()}>Export MD</button>

Архитектура совместной работы

Browser IndexedDB (y-indexeddb)  ← local primary store
       ↕
Browser Y.Doc  ← @hocuspocus/provider (WebSocket)
       ↕  Yjs binary delta messages
Server @hocuspocus/server  →  SQLite ydoc_state (one merged snapshot per doc)

• IndexedDB браузера — основное хранилище; снимок на сервере — вспомогательный. Если серверный снимок утерян, просто откройте документ в браузере, чтобы восстановить его.

• Офлайн-редактирование работает безупречно; при восстановлении сети изменения синхронизируются автоматически.

• Совместные курсоры: поддерживаются фреймворком, по умолчанию не включены.

Экспорт в Markdown

И отдельные документы, и пакеты базы знаний поддерживают экспорт в Markdown, формируемый на лету из YDoc на сервере:

# Single document export
curl http://localhost:8000/api/docs/{id}/export.md

# KB ZIP bundle
curl http://localhost:8000/api/kb/{id}/export.zip

Кастомные узлы (Mermaid, PlantUML, Callout и т. д.) имеют соответствующие правила сериализации в backend/markdown.js. При добавлении новых кастомных узлов обновите серверный сериализатор.

Передача Doco без потерь

Используйте пункт Экспорт файла Doco в меню документа, папки или базы знаний. Результирующий .doco.zip содержит исходное состояние Yjs, иерархию, настройки документов, отдельные электронные таблицы и вложения. Импорт всегда создаёт копию с новыми идентификаторами ресурсов и вложений, поэтому её можно безопасно переносить между независимыми развёртываниями Doco без конфликтов с существующими данными.

Чтобы импортировать целую базу знаний, используйте кнопку загрузки рядом с заголовком базы знаний. Чтобы импортировать пакет документа или папки, выберите Импорт файла Doco в меню целевой базы знаний или папки.

Лицензия

MIT