DenshoApp/densho-skill

Densho

Densho es una base de conocimiento autoalojada. Un espacio de trabajo contiene espacios, cada espacio contiene un árbol de páginas, y cada página es un documento colaborativo en vivo que otras personas pueden estar editando al mismo tiempo que tú.

Accedes a través del servidor MCP que el usuario ha conectado. Tu acceso es exactamente el suyo: una herramienta que no devuelve nada normalmente significa que ese espacio no es de su lectura, no que el espacio de trabajo esté vacío.

La única regla sobre escritura

update_page reemplaza el cuerpo completo. No es una operación de añadir. Escribir sin leer primero destruye todo lo que había.

Las instancias recientes lo aplican: reemplazar contenido requiere expectedVersion, el token que devuelve get_page. Si la página cambió desde que la leíste, o el id es incorrecto, la escritura se rechaza en lugar de aplicarse silenciosamente. Lee, fusiona, escribe:

1. get_page te da { version, title, content }
2. Construye el cuerpo completo nuevo a partir de ese contenido
3. update_page con content y expectedVersion: <version>

Si devuelve que la página cambió, vuelve a leer y rehace la fusión. Nunca reintentes con la versión anterior, y nunca evites la protección eliminando contenido que no leíste.

Las instancias antiguas no tienen ese token: get_page devuelve un documento Markdown con el título antepuesto como un # H1, que el cuerpo no contiene. Devolver eso directamente a update_page escribe el título en el cuerpo y la página lo muestra dos veces. Elimina ese primer encabezado antes de escribir, y ten el mismo cuidado con el resto: nada allí impide una escritura incorrecta, así que lee la página justo antes de escribirla y conserva todo lo que no estás modificando deliberadamente.

Antes de tocar nada

• Busca antes de crear. search_pages primero. Una wiki muere de duplicados, y la página que estás a punto de escribir a menudo existe bajo otro título.
• Llama a get_markdown_reference una vez por sesión antes de redactar el cuerpo de cualquier página. Devuelve el dialecto exacto que esta instancia renderiza, desde la propia instancia, por lo que nunca está desactualizado. No adivines la sintaxis de memoria ni asumas Markdown al estilo GitHub. Si la herramienta no se ofrece, la instancia es anterior a ella: ciñete a las restricciones bajo "Qué no funcionará" más abajo, y señala al usuario a Guía > Editor > "Markdown dentro y fuera" en su propio espacio de trabajo para la sintaxis completa.
• Prefiere comentar sobre editar en una página que no te pidieron cambiar. add_comment coloca tu observación junto al texto y notifica al autor, que es el gesto cortés en el trabajo de otros.
• Encuentra dónde pertenece una página con list_pages antes de crearla. Una wiki es un árbol, y una página colocada en la raíz de un espacio es una página que nadie encuentra. Pasa parentPageId.
• Escribe en el idioma de las páginas que te rodean, no en tu idioma predeterminado. Un espacio de trabajo a menudo está escrito en un solo idioma, y una página en otro idioma se lee como un intruso.

Las herramientas

Lectura. list_spaces (los espacios a los que pertenece el usuario), list_pages (el árbol de páginas de un espacio como lista plana con padres), search_pages (texto completo, opcionalmente limitado a un espacio, máximo 20 resultados y sin paginación, así que refina la consulta en lugar de tomar la lista como la verdad completa), get_page (título y cuerpo como Markdown, más el token de versión), list_comments (hilos y su estado de resolución).

Escritura. create_page (en un espacio, opcionalmente bajo un padre, opcionalmente con un cuerpo), update_page (título y/o cuerpo completo), add_comment (un nuevo hilo, o una respuesta con parentCommentId), resolve_comment.

Las páginas también se exponen como recursos densho://page/{id}, para que un cliente pueda adjuntar una directamente.

No todas las instancias ofrecen todas ellas. Las herramientas de escritura solo existen si el usuario otorgó acceso de escritura al autorizar, y una instancia antigua puede carecer de la lista de comentarios, la herramienta de resolución y la referencia de Markdown. Trabaja con lo que el cliente realmente te muestra, y dilo en lugar de describir una edición que no puedes realizar.

Escribir una página que la gente leerá

Estructúrala como documentación, no como una respuesta de chat. Encabezados que digan de qué trata la sección, párrafos cortos y listas donde el contenido sea una lista.

• Usa :::info, :::warning y los otros avisos para lo que realmente interrumpe al lector. Tres avisos seguidos se leen como ninguno.
• Usa :::toggle para detalles que la mayoría de los lectores omiten, no para ocultar la respuesta.
• Usa :::subpages para un índice de páginas hijas en lugar de una lista escrita a mano de enlaces, que queda desactualizada el día que alguien añade una página.
• Prefiere una tabla a un párrafo que enumera pares de cosas.

Todo lo que el editor soporta hace un recorrido de ida y vuelta a través de Markdown, por lo que lo que escribes es lo que la persona ve, y lo que luego exporta. El recorrido normaliza a medida que avanza: $$maths$$ vuelve en tres líneas, los bloques ganan líneas en blanco entre ellos. Leer algo con una forma ligeramente diferente de lo que enviaste es normal y no es señal de que algo haya fallado.

Qué no funcionará

• Las etiquetas HTML sin procesar se escapan y se muestran como texto. Un bloque con ```htmlrender es la forma de renderizar HTML, y debe ser autocontenido: sin red, sin recursos externos.
• Los avisos de GitHub (> [!NOTE]) no forman parte del dialecto: los corchetes se escapan y el lector ve \[!NOTE\] dentro de una cita simple. Usa un aviso.
• Las notas al pie son peores que inútiles aquí. text[^1] con su definición [^1]: note sale como [^1](note), un enlace que no apunta a nada. Escribe la acotación en línea o en un aviso.
• Un bloque ```math no renderiza. Las matemáticas en bloque son $$ ... $$.
• No puedes subir nada. No hay herramienta de archivos o imágenes, así que nunca escribas una imagen Markdown que apunte a una ruta local o un archivo que afirmas haber añadido. Una imagen ya en la página sigue funcionando: deja su enlace intacto cuando reescribas el cuerpo.
• Nunca inventes identificadores de chip. Las menciones, enlaces a páginas y bloques sincronizados codifican ids reales ([@Nombre](mention:<userId>), [etiqueta](page:<pageId>), ![[synced-blocks/...]]). Un id inventado se renderiza como un chip muerto. Usa un id real que obtuviste de una herramienta, o escribe un enlace simple.

Cosas que tienen consecuencias para el equipo

• Una página editada a través tuyo aparece al instante en el editor de cualquiera que la tenga abierta, bajo su cursor. Reescribir una página larga mientras alguien trabaja en ella es disruptivo incluso cuando es técnicamente seguro.
• Editar una página marcada como Verificada la envía de vuelta a "Listo para verificar", lo que pone trabajo en el plato de un administrador. Dilo cuando lo hagas.
• Los comentarios notifican a las personas. No abras un hilo para algo que puedas arreglar de paso, y no resuelvas un hilo que no abordaste.

Informar al usuario

Dale al usuario el título de la página y dónde vive, no ids sin procesar. Di claramente lo que cambiaste: un reemplazo completo del cuerpo merece nombrarse como tal, y si fusionaste tu texto en una página existente, di lo que conservaste.