Doco

Forneça aos agentes de IA um espaço de trabalho de documentos compartilhado com IDs de bloco estáveis, gravações seguras contra conflitos, busca, Markdown e colaboração em tempo real.

GitHub

Experimente este MCPPatrocinado

Documentação

Doco

📖 中文版

O espaço de documentos onde humanos e agentes de IA escrevem juntos. Um editor colaborativo de rich text open-source que coloca seus dados de volta em suas mãos — e trata seus agentes de IA com o mesmo cuidado: endereçamento estável em nível de bloco, controle de concorrência otimista e um servidor MCP com 29 ferramentas, para que agentes leiam e escrevam em sua base de conhecimento com a mesma segurança de um editor humano cuidadoso.

Hospedado: doco.page — gratuito durante o beta
Conecte seu 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 · Documentação da API: doco.page/api-docs

Claude Code Plugin Marketplace

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

O marketplace inclui o servidor MCP do Doco e o protocolo operacional seguro de leitura → versão → escrita protegida. Os tokens permanecem na configuração local do Claude Code e nunca são incluídos no repositório do plugin.

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

Por que os agentes estão seguros aqui

Capacidade	O que significa
Endereçamento estável em nível de bloco	Cada parágrafo tem um id `block_<ULID>` — independente de posição, sobrevive a arrastar e recolher
Concorrência otimista	Leituras retornam uma versão `sha256`; escritas exigem `If-Match`; em 409 o agente relê, mescla, tenta novamente — sobrescritas cegas são impossíveis
Round-trip de Markdown	Exporte com `?annotate=anchors`; escreva o documento inteiro de volta e os ids de bloco são preservados
Coedição humano–agente	As escritas do agente fluem pelo mesmo documento Yjs — as alterações aparecem ao vivo no navegador
Transações e idempotência	Operações em lote são confirmadas atomicamente; `Idempotency-Key` torna as tentativas sem efeitos colaterais

Recursos

Experiência de Edição

Edição de rich text: títulos, listas, citações, listas de tarefas, blocos de código (com realce de sintaxe), tabelas, imagens, links, estilos de texto e muito mais
Comando de barra /: digite / para abrir a paleta de comandos com busca difusa — suporta abreviações pinyin para usuários chineses
Barra de ferramentas flutuante: aparece automaticamente ao selecionar texto, com todas as ações de formatação a dois centímetros do cursor
Arrastar e soltar blocos: passe o mouse na borda esquerda de qualquer parágrafo para revelar uma alça de arrasto — reorganize o conteúdo como blocos de montar
Seções recolhíveis: recolha seções nas quais não está trabalhando; o estado de recolhimento persiste entre sessões
Numeração automática de títulos: alternância com um clique — os títulos H1–H4 mantêm automaticamente a numeração hierárquica (1. 1.1 1.1.1)
Atalhos de teclado: ⌥↑/↓ move blocos, ⌘D duplica blocos, ⌘⌥1/2/3/0 alterna níveis de título

Texto para Diagrama

Escreva código-fonte Mermaid ou PlantUML diretamente no seu documento. Os diagramas são renderizados no local. Clique duas vezes para editar, visualização em tela cheia, pinça para zoom — sem mais ciclos de exportar-importar-substituir com o draw.io.

Mermaid: fluxogramas, diagramas de sequência, diagramas de classes, gráficos de Gantt, diagramas de estado e muito mais
PlantUML: diagramas de sequência, diagramas de classes, diagramas de casos de uso, diagramas de componentes e muito mais

Planilha

Um mecanismo de planilha completo embutido nos seus documentos:

Avaliação de fórmulas, formatação de células
Congelar painéis, classificar e filtrar
Mesclar / dividir células
Importação / exportação CSV

Use inline como um bloco de conteúdo ou abra como uma planilha independente em tela cheia.

Base de Conhecimento

Base de Conhecimento → Pastas (aninháveis) → Documentos — uma estrutura de três níveis
Arrastar e soltar para reordenar, renomear e mover na barra lateral
Exportação ZIP de toda a base preservando a hierarquia de pastas, com imagens incluídas
Transferência nativa sem perdas .doco.zip para um documento, pasta ou base de conhecimento inteira

Colaboração em Tempo Real

Construído sobre o algoritmo CRDT Yjs:

Sem botão de salvar — as alterações são sincronizadas automaticamente
Offline-first: o IndexedDB do navegador é o armazenamento principal; o servidor mantém um snapshot. Edite sem rede, mescle automaticamente ao reconectar
Troca de dispositivos sem interrupção: feche o laptop, pegue o celular, continue escrevendo

Importação / Exportação

Formato	Importação	Exportação
Pacote nativo Doco	✅ Documento / pasta / KB	✅ Documento / pasta / KB sem perdas
Markdown	✅ Colar / upload de arquivo	✅ Documento único e pacote KB
Word (DOCX)	✅	✅
PDF	✅	✅
HTML	✅	—
Conta Oficial WeChat	—	✅ (com pré-visualização de tema)
Imagens (no documento)	✅ (colar / arrastar e soltar)	✅ (incluídas no ZIP)

API · MCP · CLI

Três canais, um contrato:

API REST: especificação OpenAPI 3.1, autenticação Bearer Token, versionamento ETag, paginação por cursor, chaves de idempotência
Servidor MCP: doco mcp (incluído no doco-agent-cli) — 29 ferramentas além de recursos doco://
CLI doco: login / whoami / docs / blocks / edit / mcp, --json global, escritas internalizam ETag/If-Match

Transforme seus documentos em ativos programáveis — crie scripts para seus próprios backups, deixe um agente organizar sua base de conhecimento, envie documentos do seu fluxo de publicação para o seu blog. Página de documentação da API integrada, pronta para uso imediato.

Stack Tecnológico

Camada	Tecnologia
Framework Frontend	React 18 + Vite + TypeScript
CSS	Tailwind CSS v4
Editor	Tiptap v3 (ProseMirror)
Colaboração	Yjs (CRDT) + Hocuspocus
Diagramas	Mermaid + PlantUML
Backend	Node.js + Express + Hocuspocus Server
Banco de dados	better-sqlite3 (SQLite, modo WAL)
Componentes de UI	Radix UI, Lucide React, Tippy.js

Início Rápido

Pré-requisitos

Node.js >= 22
pnpm

Instalar e Executar

# 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

Abra http://localhost:5173 — ele se conectará automaticamente ao serviço WebSocket do backend.

Implantação com Docker (recomendado)

O pacote completo de auto-hospedagem inclui um frontend Caddy, backend de colaboração Node.js, armazenamento SQLite persistente, verificações de saúde e um proxy WebSocket de mesma origem. As imagens públicas suportam tanto linux/amd64 quanto 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

Abra http://localhost:8080 por padrão. Defina os valores de ALLOWED_ORIGINS, COOKIE_SECURE, Google OAuth e SMTP em .env.docker para o seu ambiente. Esses valores são injetados quando os contêineres iniciam e não são embutidos nas imagens. Os dados do aplicativo são armazenados no volume nomeado doco-data.

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

Para construir as mesmas imagens a partir do código-fonte:

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

Consulte o guia de implantação Docker para todas as opções de configuração, HTTPS, logs, backup, restauração e atualizações. Não execute docker compose down -v a menos que pretenda excluir o banco de dados e os anexos.

Build e Implantação Manuais

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

# Backend (production)
cd backend
npm start

Estrutura do Projeto

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 Independente

O núcleo do editor também é publicado como doco-text-editor. Ele contém toda a experiência de edição do Doco e estilos integrados, mas não depende da autenticação do Doco, APIs REST, serviços de colaboração ou IndexedDB. O aplicativo hospedeiro decide se o conteúdo vive na memória, no armazenamento do navegador, no seu próprio backend ou em um sistema externo como o 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')

O pacote inclui títulos, formatação inline, citações, listas ordenadas/não ordenadas/de tarefas, blocos de código, imagens, tabelas, callouts, Mermaid, renderização opcional de PlantUML e planilhas embutidas. Consulte src/editor/README.md para a API completa e notas de integração.

Uso Completo do Componente Editor 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>

Arquitetura de Colaboração

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)

O IndexedDB do navegador é o armazenamento principal; o snapshot do servidor é auxiliar. Se o snapshot do servidor for perdido, basta abrir o documento no navegador para repopulá-lo.
A edição offline funciona perfeitamente; as alterações são sincronizadas automaticamente quando a rede retorna.
Cursores colaborativos: suportados pelo framework, não habilitados por padrão.

Exportação em Markdown

Tanto documentos únicos quanto pacotes KB suportam exportação em Markdown, gerada dinamicamente a partir do YDoc no 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

Nós personalizados (Mermaid, PlantUML, Callout, etc.) têm regras de serialização correspondentes em backend/markdown.js. Ao adicionar novos nós personalizados, atualize o serializador do lado do servidor de acordo.

Transferência Doco Sem Perdas

Use Exportar Arquivo Doco no menu de um documento, pasta ou base de conhecimento. O .doco.zip resultante contém o estado Yjs original, hierarquia, configurações do documento, planilhas independentes e anexos. A importação sempre cria uma cópia com novos IDs de recursos e anexos, para que possa ser movida com segurança entre implantações Doco independentes sem colidir com dados existentes.

Use o botão de upload ao lado do título da base de conhecimento para importar uma base inteira. Para importar um pacote de documento ou pasta, escolha Importar Arquivo Doco no menu da base de conhecimento ou pasta de destino.

Licença

MIT