Doco

Proporciona a los agentes de IA un espacio de trabajo documental compartido con IDs de bloque estables, escrituras seguras ante conflictos, búsqueda, Markdown y colaboración en tiempo real.

GitHub

Prueba este MCPPatrocinado

Documentación

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 API: doco.page/api-docs

Mercado de plugins de Claude Code

/plugin marketplace add songofhawk/doco
/plugin install doco@doco

El mercado incluye el servidor MCP de Doco y el protocolo operativo seguro de lectura → versión → escritura protegida. Los tokens permanecen en la configuración local de Claude Code y nunca se incluyen en el repositorio de plugins.

Doco editor showing a live block-level Agent update in an English demo document

Por qué los agentes están seguros aquí

Capacidad	Qué significa
Direccionamiento estable a nivel de bloque	Cada párrafo tiene un id `block_<ULID>` — independiente de la posición, sobrevive a arrastres y plegados
Concurrencia optimista	Las lecturas devuelven una versión `sha256`; las escrituras requieren `If-Match`; ante un 409 el agente relee, fusiona y reintenta — las sobrescrituras ciegas son imposibles
Round-trip de Markdown	Exporta con `?annotate=anchors`; escribe el documento completo de vuelta y los ids de bloque se conservan
Coedición humano-agente	Las escrituras del agente fluyen por el mismo documento Yjs — los cambios aparecen en vivo en el navegador
Transacciones e idempotencia	Las operaciones por lotes se confirman atómicamente; `Idempotency-Key` hace que los reintentos no tengan efectos secundarios

Características

Experiencia de edición

Edición de texto enriquecido: encabezados, listas, citas, 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 pinyin para usuarios chinos
Barra de herramientas flotante: aparece automáticamente al seleccionar texto, con todas las acciones de formato a dos centímetros de tu cursor
Arrastrar y soltar bloques: pasa el cursor sobre el borde izquierdo de cualquier párrafo para revelar un controlador de arrastre — reorganiza el contenido como bloques de construcción
Secciones plegables: pliega las secciones en las que no estás trabajando; el estado de plegado persiste 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 los niveles de encabezado

Texto a diagrama

Escribe código fuente de Mermaid o PlantUML directamente en tu documento. Los diagramas se renderizan en el 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 estados 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 .doco.zip sin pérdidas para un documento, carpeta o base de conocimiento completa

Colaboración en tiempo real

Construido sobre el algoritmo CRDT de 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, fusiona automáticamente al reconectarte
Cambio de dispositivo sin fricción: cierra tu portátil, toma tu teléfono, sigue escribiendo

Importación / Exportación

Formato	Importar	Exportar
Paquete nativo de Doco	✅ Documento / carpeta / KB	✅ Documento / carpeta / KB sin pérdidas
Markdown	✅ Pegar / subir archivo	✅ Documento único y paquete KB
Word (DOCX)	✅	✅
PDF	✅	✅
HTML	✅	—
Cuenta oficial de WeChat	—	✅ (con vista previa de tema)
Imágenes (en documento)	✅ (pegar / arrastrar y soltar)	✅ (incluidas en ZIP)

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, canaliza documentos desde tu flujo de publicación a tu blog. Página de documentación de API integrada, lista para usar desde el primer momento.

Pila tecnológica

Capa	Tecnología
Framework frontend	React 18 + Vite + TypeScript
CSS	Tailwind CSS v4
Editor	Tiptap v3 (ProseMirror)
Colaboración	Yjs (CRDT) + Hocuspocus
Diagramas	Mermaid + PlantUML
Backend	Node.js + Express + Hocuspocus Server
Base de datos	better-sqlite3 (SQLite, modo WAL)
Componentes de interfaz	Radix UI, Lucide React, Tippy.js

Inicio rápido

Requisitos previos

Node.js >= 22
pnpm

Instalar y ejecutar

# 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, 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, OAuth de Google y los valores SMTP en .env.docker para tu entorno. Estos valores se inyectan al iniciar los contenedores y no están integrados en las imágenes. Los datos de la aplicación se almacenan en el volumen nombrado doco-data.

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

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

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 tengas la intención de eliminar la base de datos y los archivos adjuntos.

Compilación y despliegue manuales

# 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, 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 la instantánea del servidor se pierde, simplemente abre el documento en el navegador para repoblarla.
La edición sin conexión funciona sin problemas; los cambios se sincronizan automáticamente cuando la red vuelve.
Cursores colaborativos: compatibles con el framework, no habilitados por defecto.

Exportación a Markdown

Tanto los documentos individuales como los paquetes KB admiten exportación a Markdown, generada sobre la marcha desde el 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 de Doco sin pérdidas

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 independientes de Doco sin colisionar con datos existentes.

Usa el botón de subida junto al encabezado de la base de conocimiento para importar una base de conocimiento 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