Densho

O que Densho faz?

Densho é uma base de conhecimento auto-hospedada. Um workspace contém espaços, cada espaço contém uma árvore de páginas, e cada página é um documento colaborativo ao vivo que as pessoas podem estar editando no mesmo momento que você.

Você o acessa através do servidor MCP que o usuário conectou. Seu acesso é exatamente o mesmo que o deles: uma ferramenta que retorna nada geralmente significa que aquele espaço não é deles para ler, não que o workspace está vazio.

A regra única sobre escrita

update_page substitui o corpo inteiro. Não é uma anexação. Escrever sem ler primeiro destrói tudo o que estava lá.

Instâncias recentes aplicam isso: substituir conteúdo requer expectedVersion, o token que get_page retorna. Se a página mudou desde que você a leu, ou o id está errado, a escrita é recusada em vez de ser aplicada silenciosamente. Leia, mescle, escreva:

1. get_page fornece { version, title, content }
2. construa o novo corpo completo a partir desse conteúdo
3. update_page com content e expectedVersion: <version>

Se retornar dizendo que a página mudou, releia e refaça a mesclagem. Nunca tente novamente com a versão antiga e nunca ignore a proteção descartando conteúdo que você não leu.

Instâncias antigas não possuem esse token: get_page retorna um documento Markdown com o título anexado como um # H1, que o corpo não contém. Alimentar isso diretamente de volta para update_page escreve o título no corpo e a página então o exibe duas vezes. Remova esse primeiro título antes de escrever e tome o mesmo cuidado com o resto: nada lá impede uma escrita ruim, então leia a página imediatamente antes de escrevê-la e mantenha tudo o que você não está deliberadamente alterando.

Antes de tocar em qualquer coisa

• Pesquise antes de criar. search_pages primeiro. Uma wiki morre de duplicatas, e a página que você está prestes a escrever frequentemente existe sob outro título.
• Chame get_markdown_reference uma vez por sessão antes de criar qualquer corpo de página. Ela retorna o dialeto exato que esta instância renderiza, da própria instância, então nunca está desatualizada. Não adivinhe a sintaxe pela memória e não assuma Markdown no estilo GitHub. Se a ferramenta não for oferecida, a instância é anterior a ela: siga as restrições em "O que não funcionará" abaixo e aponte o usuário para Guia > Editor > "Markdown in and out" no próprio workspace para a sintaxe completa.
• Prefira comentar em vez de editar em uma página que você não foi solicitado a alterar. add_comment coloca sua observação ao lado do texto e notifica o autor, o que é a ação educada no trabalho de outra pessoa.
• Encontre onde uma página pertence com list_pages antes de criar uma. Uma wiki é uma árvore, e uma página colocada na raiz de um espaço é uma página que ninguém encontra. Passe parentPageId.
• Escreva no idioma das páginas ao seu redor, não no seu padrão. Um workspace geralmente é escrito em um único idioma, e uma página em outro parece uma intrusa.

As ferramentas

Leitura. list_spaces (os espaços aos quais o usuário pertence), list_pages (a árvore de páginas de um espaço como uma lista plana com pais), search_pages (texto completo, opcionalmente com escopo em um espaço, no máximo 20 correspondências e sem paginação, então refine a consulta em vez de considerar a lista como a verdade absoluta), get_page (título e corpo como Markdown, mais o token de versão), list_comments (threads e seu estado de resolução).

Escrita. create_page (em um espaço, opcionalmente sob um pai, opcionalmente com um corpo), update_page (título e/ou corpo completo), add_comment (uma nova thread, ou uma resposta com parentCommentId), resolve_comment.

As páginas também são expostas como recursos densho://page/{id}, então um cliente pode anexar uma diretamente.

Nem toda instância oferece todas elas. Ferramentas de escrita só existem se o usuário concedeu acesso de escrita ao autorizar, e uma instância antiga pode não ter a listagem de comentários, a ferramenta de resolução e a referência Markdown. Trabalhe com o que o cliente realmente mostra a você e diga isso em vez de descrever uma edição que você não pode realizar.

Escrevendo uma página que as pessoas lerão

Estruture-a como documentação, não como uma resposta de chat. Títulos que digam sobre o que é a seção, parágrafos curtos e listas onde o conteúdo é uma lista.

• Use :::info, :::warning e os outros callouts para o que genuinamente interrompe o leitor. Três callouts seguidos são lidos como nenhum.
• Use :::toggle para detalhes que a maioria dos leitores pula, não para esconder a resposta.
• Use :::subpages para um índice de páginas filhas em vez de uma lista escrita à mão de links, que fica desatualizada no dia em que alguém adiciona uma página.
• Prefira uma tabela a um parágrafo enumerando pares de coisas.

Tudo o que o editor suporta passa pelo Markdown, então o que você escreve é o que a pessoa vê, e o que eles exportam mais tarde. A passagem normaliza conforme avança: $$maths$$ retorna em três linhas, blocos ganham linhas em branco entre eles. Ler de volta algo com formato ligeiramente diferente do que você enviou é normal e não é sinal de que algo falhou.

O que não funcionará

• Tags HTML puras são escapadas e exibidas como texto. Um bloco ```htmlrender é a maneira de renderizar HTML, e ele deve ser autocontido: sem rede, sem ativos externos.
• Callouts do GitHub (> [!NOTE]) não fazem parte do dialeto: os colchetes são escapados e o leitor vê \[!NOTE\] dentro de uma citação simples. Use um callout.
• Notas de rodapé são piores do que inúteis aqui. text[^1] com sua definição [^1]: note resulta em [^1](note), um link que não aponta para nada. Escreva o comentário inline ou em um callout.
• Uma cerca ```math não renderiza. Matemática em bloco é $$ ... $$.
• Você não pode enviar nada. Não há ferramenta de arquivo ou imagem, então nunca escreva uma imagem Markdown apontando para um caminho local ou um arquivo que você afirma ter adicionado. Uma imagem já na página continua funcionando: deixe seu link intocado quando você reescrever o corpo.
• Nunca invente identificadores de chip. Menções, links de página e blocos sincronizados codificam IDs reais ([@Nome](mention:<userId>), [rótulo](page:<pageId>), ![[synced-blocks/...]]). Um ID inventado renderiza como um chip morto. Use um ID real que você obteve de uma ferramenta ou escreva um link simples.

Coisas que têm consequências para a equipe

• Uma página editada através de você aparece instantaneamente no editor de qualquer pessoa que a tenha aberta, sob o cursor delas. Reescrever uma página longa enquanto alguém trabalha nela é perturbador, mesmo quando é tecnicamente seguro.
• Editar uma página marcada como Verificada a envia de volta para "Pronto para verificar", o que coloca trabalho na mesa de um administrador. Diga isso quando fizer.
• Comentários notificam as pessoas. Não abra uma thread para algo que você pode consertar de passagem, e não resolva uma thread que você não abordou.

Relatando

Dê ao usuário o título da página e onde ela está, não IDs brutos. Diga claramente o que você alterou: uma substituição completa do corpo merece ser nomeada como tal, e se você mesclou seu texto em uma página existente, diga o que você manteve.