Doco

📖 中文版

Der Dokumentationsraum, in dem Menschen und KI-Agenten gemeinsam schreiben. Ein Open-Source-Rich-Text- Kollaborationseditor, der Ihre Daten zurück in Ihre Hände legt – und Ihre KI-Agenten mit derselben Sorgfalt behandelt: blockweise stabile Adressierung, optimistische Nebenläufigkeitskontrolle und ein MCP-Server mit 29 Tools, sodass Agenten Ihre Wissensdatenbank so sicher lesen und schreiben wie ein sorgfältiger menschlicher Redakteur.

• Gehostet: doco.page – während der Beta kostenlos

• Agent verbinden: 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-Dokumentation: doco.page/api-docs

Warum Agenten hier sicher sind

Related MCP server: session-coord-mcp

Funktionen

Bearbeitungserlebnis

• Rich-Text-Bearbeitung: Überschriften, Listen, Blockzitate, Aufgabenlisten, Codeblöcke (Syntaxhervorhebung), Tabellen, Bilder, Links, Textformatierung und mehr

• /-Slash-Befehl: Tippen Sie /, um die Befehlspalette mit Fuzzy-Suche zu öffnen – unterstützt Pinyin-Abkürzungen für chinesische Benutzer

• Schwebende Symbolleiste: erscheint automatisch bei Textauswahl, alle Formatierungsaktionen innerhalb von zwei Zentimetern um Ihren Cursor

• Block-Ziehen-und-Ablegen: Fahren Sie mit der Maus über den linken Rand eines Absatzes, um einen Ziehgriff anzuzeigen – ordnen Sie Inhalte wie Bausteine neu an

• Einklappbare Abschnitte: Klappen Sie Abschnitte weg, an denen Sie nicht arbeiten; der Einklappzustand bleibt über Sitzungen hinweg erhalten

• Automatische Überschriftennummerierung: Ein-Klick-Umschaltung – H1–H4-Überschriften pflegen automatisch eine hierarchische Nummerierung (1. 1.1 1.1.1)

• Tastaturkürzel: ⌥↑/↓ verschiebt Blöcke, ⌘D dupliziert Blöcke, ⌘⌥1/2/3/0 wechselt die Überschriftenebene

Text-zu-Diagramm

Schreiben Sie Mermaid- oder PlantUML-Quellcode direkt in Ihr Dokument. Diagramme werden an Ort und Stelle gerendert. Doppelklick zum Bearbeiten, Vollbildansicht, Pinch-to-Zoom – keine Export-Import-Ersetzungszyklen mehr mit draw.io.

• Mermaid: Flussdiagramme, Sequenzdiagramme, Klassendiagramme, Gantt-Diagramme, Zustandsdiagramme und mehr

• PlantUML: Sequenzdiagramme, Klassendiagramme, Anwendungsfalldiagramme, Komponentendiagramme und mehr

Tabellenkalkulation

Eine vollständige Tabellenkalkulations-Engine, eingebettet in Ihre Dokumente:

• Formelauswertung, Zellformatierung

• Fixierte Zeilen/Spalten, Sortieren & Filtern

• Zellen zusammenführen / teilen

• CSV-Import / -Export

Verwenden Sie sie inline als Inhaltsblock oder blenden Sie sie als eigenständige Vollbild-Tabellenkalkulation aus.

Wissensdatenbank

• Wissensdatenbank → Ordner (verschachtelbar) → Dokumente – eine dreistufige Struktur

• Ziehen-und-Ablegen-Neuordnung, Umbenennen und Verschieben in der Seitenleiste

• Ganze-Wissensdatenbank-ZIP-Export unter Beibehaltung der Ordnerhierarchie, mit gebündelten Bildern

• Verlustfreier nativer .doco.zip-Transfer für ein Dokument, einen Ordner oder eine ganze Wissensdatenbank

Echtzeit-Zusammenarbeit

Basiert auf dem Yjs-CRDT-Algorithmus:

• Kein Speichern-Button – Änderungen werden automatisch synchronisiert

• Offline-first: Browser-IndexedDB ist der primäre Speicher; der Server hält eine Momentaufnahme. Bearbeiten Sie ohne Netzwerk, automatisches Zusammenführen bei Wiederverbindung

• Nahtloser Gerätewechsel: Laptop zuklappen, Handy aufnehmen, weiterschreiben

Import / Export

API · MCP · CLI

Drei Kanäle, ein Vertrag:

• REST-API: OpenAPI-3.1-Spezifikation, Bearer-Token-Authentifizierung, ETag-Versionierung, Cursor-Paginierung, Idempotenzschlüssel

• MCP-Server: doco mcp (in doco-agent-cli enthalten) – 29 Tools plus doco://-Ressourcen

• doco-CLI: login / whoami / docs / blocks / edit / mcp, globales --json, Schreibvorgänge internalisieren ETag/If-Match

Verwandeln Sie Ihre Dokumente in programmierbare Assets – scripten Sie Ihre eigenen Backups, lassen Sie einen Agenten Ihre Wissensdatenbank organisieren, leiten Sie Dokumente aus Ihrem Publishing-Workflow an Ihren Blog weiter. Integrierte API- Dokumentationsseite, sofort einsatzbereit.

Technologie-Stack

Schnellstart

Voraussetzungen

• Node.js >= 18

• pnpm

Installation & Ausführung

# 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

Öffnen Sie http://localhost:5173 – es verbindet sich automatisch mit dem Backend-WebSocket-Dienst.

Docker-Bereitstellung (empfohlen)

Das vollständige Self-Hosted-Paket enthält ein Caddy-Frontend, Node.js-Kollaborations-Backend, persistenten SQLite-Speicher, Health Checks und einen Same-Origin-WebSocket-Proxy. Die öffentlichen Images unterstützen sowohl linux/amd64 als auch 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

Öffnen Sie standardmäßig http://localhost:8080. Setzen Sie ALLOWED_ORIGINS, COOKIE_SECURE, Google-OAuth- und SMTP-Werte in .env.docker für Ihre Umgebung. Diese Werte werden beim Start der Container injiziert und sind nicht in die Images eingebacken. Anwendungsdaten werden im benannten Volume doco-data gespeichert.

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

Um dieselben Images stattdessen aus dem Quellcode zu erstellen:

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

Siehe den Docker-Bereitstellungsleitfaden für alle Konfigurationsoptionen, HTTPS, Protokolle, Backup, Wiederherstellung und Upgrades. Führen Sie docker compose down -v nicht aus, es sei denn, Sie beabsichtigen, die Datenbank und Anhänge zu löschen.

Manueller Build & Bereitstellung

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

# Backend (production)
cd backend
npm start

Projektstruktur

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

Eigenständige Frontend-Komponente

Der Editor-Kern ist auch als doco-text-editor veröffentlicht. Er enthält das vollständige Doco-Bearbeitungserlebnis und integrierte Stile, hat aber keine Abhängigkeit von Doco-Authentifizierung, REST-APIs, Kollaborationsdiensten oder IndexedDB. Die Host-Anwendung entscheidet, ob Inhalte im Speicher, im Browser-Speicher, im eigenen Backend oder in einem externen System wie ClickUp liegen.

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')

Das Paket enthält Überschriften, Inline-Formatierung, Blockzitate, geordnete/ungeordnete/Aufgabenlisten, Codeblöcke, Bilder, Tabellen, Callouts, Mermaid, optionales PlantUML-Rendering und eingebettete Tabellenkalkulationen. Siehe src/editor/README.md für die vollständige API und Integrationshinweise.

Verwendung der vollständigen Doco-Editor-Komponente

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>

Kollaborationsarchitektur

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)

• Die Browser-IndexedDB ist der primäre Speicher; die Server-Momentaufnahme ist Hilfsmittel. Wenn die Server-Momentaufnahme verloren geht, öffnen Sie einfach das Dokument im Browser, um es neu zu befüllen.

• Offline-Bearbeitung funktioniert nahtlos; Änderungen werden automatisch synchronisiert, wenn das Netzwerk zurückkehrt.

• Kollaborative Cursor: vom Framework unterstützt, standardmäßig nicht aktiviert.

Markdown-Export

Sowohl einzelne Dokumente als auch Wissensdatenbank-Bundles unterstützen den Markdown-Export, der serverseitig on-the-fly aus YDoc generiert wird:

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

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

Benutzerdefinierte Knoten (Mermaid, PlantUML, Callout usw.) haben entsprechende Serialisierungsregeln in backend/markdown.js. Wenn Sie neue benutzerdefinierte Knoten hinzufügen, aktualisieren Sie den serverseitigen Serialisierer entsprechend.

Verlustfreier Doco-Transfer

Verwenden Sie Doco-Datei exportieren in einem Dokument-, Ordner- oder Wissensdatenbank-Menü. Die resultierende .doco.zip enthält den ursprünglichen Yjs-Zustand, die Hierarchie, Dokumenteinstellungen, eigenständige Tabellenkalkulationen und Anhänge. Der Import erstellt immer eine Kopie mit neuen Ressourcen- und Anhangs-IDs, sodass sie sicher zwischen unabhängigen Doco-Bereitstellungen verschoben werden kann, ohne mit vorhandenen Daten zu kollidieren.

Verwenden Sie die Upload-Schaltfläche neben der Wissensdatenbank-Überschrift, um eine ganze Wissensdatenbank zu importieren. Um ein Dokument- oder Ordnerpaket zu importieren, wählen Sie Doco-Datei importieren aus dem Menü der Ziel-Wissensdatenbank oder des Ziel-Ordners.

Lizenz

MIT