Doco

📖 中文版

El espacio documental donde humanos y agentes de IA escriben juntos. Un editor colaborativo de texto enriquecido de código abierto que devuelve tus datos a tus manos — y trata a tus agentes de IA con el mismo cuidado: direccionamiento estable a nivel de bloque, control de concurrencia optimista y un servidor MCP con 29 herramientas, para que los agentes lean y escriban en tu base de conocimiento con la misma seguridad que un editor humano cuidadoso.

• Alojado: doco.page — gratis durante la beta

• Conecta tu agente: 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 · Documentación de la API: doco.page/api-docs

Por qué los agentes están seguros aquí

Related MCP server: session-coord-mcp

Características

Experiencia de edición

• Edición de texto enriquecido: encabezados, listas, citas en bloque, listas de tareas, bloques de código (resaltado de sintaxis), tablas, imágenes, enlaces, estilos de texto y más

• Comando de barra /: escribe / para abrir la paleta de comandos con búsqueda difusa — admite abreviaturas de pinyin para usuarios chinos

• Barra de herramientas flotante: aparece automáticamente al seleccionar texto, con todas las acciones de formato a menos de dos centímetros del cursor

• Arrastrar y soltar bloques: pasa el cursor sobre el borde izquierdo de cualquier párrafo para revelar un asa de arrastre — reordena el contenido como bloques de construcción

• Secciones plegables: pliega las secciones en las que no estás trabajando; el estado de plegado se conserva entre sesiones

• Numeración automática de encabezados: activable con un clic — los encabezados H1–H4 mantienen automáticamente una numeración jerárquica (1. 1.1 1.1.1)

• Atajos de teclado: ⌥↑/↓ mueve bloques, ⌘D duplica bloques, ⌘⌥1/2/3/0 cambia el nivel de encabezado

Texto a diagrama

Escribe código fuente de Mermaid o PlantUML directamente en tu documento. Los diagramas se renderizan en su lugar. Doble clic para editar, vista a pantalla completa, pellizco para hacer zoom — sin más ciclos de exportar-importar-reemplazar con draw.io.

• Mermaid: diagramas de flujo, diagramas de secuencia, diagramas de clases, diagramas de Gantt, diagramas de estado y más

• PlantUML: diagramas de secuencia, diagramas de clases, diagramas de casos de uso, diagramas de componentes y más

Hoja de cálculo

Un motor de hoja de cálculo completo integrado en tus documentos:

• Evaluación de fórmulas, formato de celdas

• Paneles congelados, ordenar y filtrar

• Combinar / dividir celdas

• Importación / exportación CSV

Úsala en línea como bloque de contenido, o sácala como hoja de cálculo independiente a pantalla completa.

Base de conocimiento

• Base de conocimiento → Carpetas (anidables) → Documentos — una estructura de tres niveles

• Reordenar, renombrar y mover con arrastrar y soltar en la barra lateral

• Exportación ZIP de toda la base de conocimiento que conserva la jerarquía de carpetas, con imágenes incluidas

• Transferencia nativa sin pérdida .doco.zip para un documento, carpeta o base de conocimiento completa

Colaboración en tiempo real

Construido sobre el algoritmo CRDT Yjs:

• Sin botón de guardar — los cambios se sincronizan automáticamente

• Offline-first: el IndexedDB del navegador es el almacén principal; el servidor guarda una instantánea. Edita sin red, fusión automática al reconectar

• Cambio de dispositivo sin fricción: cierra el portátil, coge el móvil, sigue escribiendo

Importación / Exportación

API · MCP · CLI

Tres canales, un contrato:

• API REST: especificación OpenAPI 3.1, autenticación con Bearer Token, versionado ETag, paginación con cursor, claves de idempotencia

• Servidor MCP: doco mcp (incluido en doco-agent-cli) — 29 herramientas más recursos doco://

• CLI de Doco: login / whoami / docs / blocks / edit / mcp, --json global, las escrituras internalizan ETag/If-Match

Convierte tus documentos en activos programables — automatiza tus propias copias de seguridad, deja que un agente organice tu base de conocimiento, envía documentos de tu flujo de publicación a tu blog. Página de documentación de API integrada, lista para usar.

Pila tecnológica

Inicio rápido

Requisitos previos

• Node.js >= 18

• pnpm

Instalación y ejecución

# 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

Abre http://localhost:5173 — se conectará automáticamente al servicio WebSocket del backend.

Despliegue con Docker (recomendado)

El paquete completo de autoalojamiento incluye un frontend Caddy, un backend de colaboración Node.js, almacenamiento SQLite persistente, comprobaciones de salud y un proxy WebSocket de mismo origen. Las imágenes públicas admiten tanto linux/amd64 como 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

Abre http://localhost:8080 por defecto. Configura ALLOWED_ORIGINS, COOKIE_SECURE, Google OAuth y SMTP en .env.docker para tu entorno. Estos valores se inyectan al arrancar los contenedores y no están incrustados en las imágenes. Los datos de la aplicación se guardan en el volumen con nombre doco-data.

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

Para construir las mismas imágenes desde el código fuente en su lugar:

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

Consulta la guía de despliegue con Docker para todas las opciones de configuración, HTTPS, registros, copias de seguridad, restauración y actualizaciones. No ejecutes docker compose down -v a menos que quieras eliminar la base de datos y los archivos adjuntos.

Compilación y despliegue manual

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

# Backend (production)
cd backend
npm start

Estructura del proyecto

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

Componente frontend independiente

El núcleo del editor también se publica como doco-text-editor. Contiene la experiencia completa de edición de Doco y estilos integrados, pero no depende de la autenticación de Doco, las API REST, los servicios de colaboración ni IndexedDB. La aplicación anfitriona decide si el contenido vive en memoria, en el almacenamiento del navegador, en su propio backend o en un sistema externo como 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')

El paquete incluye encabezados, formato en línea, citas en bloque, listas ordenadas/no ordenadas/de tareas, bloques de código, imágenes, tablas, llamadas, Mermaid, renderizado opcional de PlantUML y hojas de cálculo integradas. Consulta src/editor/README.md para la API completa y las notas de integración.

Uso completo del componente editor de 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>

Arquitectura de colaboración

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)

• El IndexedDB del navegador es el almacén principal; la instantánea del servidor es auxiliar. Si se pierde la instantánea del servidor, simplemente abre el documento en el navegador para repoblarla.

• La edición offline funciona sin problemas; los cambios se sincronizan automáticamente cuando vuelve la red.

• Cursores colaborativos: soportados por el framework, no activados por defecto.

Exportación a Markdown

Tanto los documentos individuales como los paquetes de base admiten exportación a Markdown, generada sobre la marcha desde YDoc en el servidor:

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

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

Los nodos personalizados (Mermaid, PlantUML, Callout, etc.) tienen reglas de serialización correspondientes en backend/markdown.js. Al añadir nuevos nodos personalizados, actualiza el serializador del servidor en consecuencia.

Transferencia Doco sin pérdida

Usa Exportar archivo Doco en el menú de un documento, carpeta o base de conocimiento. El .doco.zip resultante contiene el estado Yjs original, la jerarquía, la configuración del documento, las hojas de cálculo independientes y los archivos adjuntos. La importación siempre crea una copia con nuevos ids de recursos y archivos adjuntos, por lo que puede moverse con seguridad entre despliegues de Doco independientes sin colisionar con datos existentes.

Usa el botón de subida junto al encabezado de la base de conocimiento para importar una base completa. Para importar un paquete de documento o carpeta, elige Importar archivo Doco desde el menú de la base de conocimiento o carpeta de destino.

Licencia

MIT