knowledge-services
Publica conocimiento aprobado en Kwipu/Graphiti mediante adaptadores, routing cerrado y outbox recuperable. Lectura externa solo opt-in; no promueve candidatos. Úsala cuando el usuario diga "sincroniza el conocimiento con Kwipu", "publica docs/knowledge en el grafo", "exporta approved a Kwipu", "por qué Kwipu no ve esta entrada", "añade un backend de knowledge-services", o al activar la capacidad `kwipu` desde `/setup`.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-15
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- knowledge-services
- description
- Publica conocimiento aprobado en Kwipu/Graphiti mediante adaptadores, routing cerrado y outbox recuperable. Lectura externa solo opt-in; no promueve candidatos. Úsala cuando el usuario diga "sincroniza el conocimiento con Kwipu", "publica docs/knowledge en el grafo", "exporta approved a Kwipu", "por qué Kwipu no ve esta entrada", "añade un backend de knowledge-services", o al activar la capacidad `kwipu` desde `/setup`.
02 资源文件 48
- 脚本backends/__init__.py4.8 KB
- 脚本backends/graphiti_model.py20.7 KB
- 脚本backends/graphiti_provenance.py6.6 KB
- 脚本backends/graphiti_providers.py4.1 KB
- 脚本backends/graphiti_publication.py29.5 KB
- 脚本backends/graphiti_rebuild.py23.4 KB
- 脚本backends/graphiti_scope.py3.4 KB
- 脚本backends/graphiti.py162.0 KB
- 脚本backends/markdown_export.py92.2 KB
- 参考文档backends/README.md22.8 KB
- 参考文档references/kwipu-adapter.md27.7 KB
- 参考文档references/project-integration.md2.4 KB
- 脚本scripts/_mcp_fake.py10.1 KB
- 脚本scripts/fixtures/graphiti/graphiti-manifest-history.json1.7 KB
- 脚本scripts/fixtures/graphiti/graphiti-mcp-get-status-2026-09-18.json410 B
- 脚本scripts/fixtures/graphiti/graphiti-mcp-history-window.json6.7 KB
- 脚本scripts/fixtures/graphiti/graphiti-mcp-initialize-2026-09-18.json3.2 KB
- 脚本scripts/fixtures/graphiti/graphiti-mcp-tools-list-2026-09-18.json50.5 KB
- 脚本scripts/fixtures/graphiti/graphiti-mcp-validation-error.json335 B
- 脚本scripts/fixtures/graphiti/graphiti-native-provenance.json13.5 KB
- 脚本scripts/fixtures/kwipu-graph-snapshot-2026-09-18.json1.2 KB
- 脚本scripts/fixtures/kwipu-health-2026-09-18.json393 B
- 脚本scripts/fixtures/kwipu-query-2026-09-18.json1.8 KB
- 脚本scripts/knowledge-sync.py32.5 KB
- 脚本scripts/kwipu-project-add.py30.2 KB
- 脚本scripts/test_backend_graphiti.py193.1 KB
- 脚本scripts/test_backend_markdown_export.py56.1 KB
- 脚本scripts/test_backend_markdown_http.py14.7 KB
- 脚本scripts/test_backend_markdown_read.py27.4 KB
- 脚本scripts/test_backend_verification.py4.6 KB
- 脚本scripts/test_backends_init.py2.4 KB
- 脚本scripts/test_graphiti_client_results.py2.0 KB
- 脚本scripts/test_graphiti_control.py3.0 KB
- 脚本scripts/test_graphiti_history.py6.2 KB
- 脚本scripts/test_graphiti_native_provenance.py12.5 KB
- 脚本scripts/test_graphiti_observation.py6.2 KB
- 脚本scripts/test_graphiti_publication.py11.4 KB
- 脚本scripts/test_graphiti_rebuild.py18.7 KB
- 脚本scripts/test_graphiti_recovery.py3.6 KB
- 脚本scripts/test_graphiti_retirement.py7.6 KB
- 脚本scripts/test_graphiti_scope.py9.2 KB
- 脚本scripts/test_graphiti_succession.py9.5 KB
- 脚本scripts/test_graphiti_transitions.py9.5 KB
- 脚本scripts/test_knowledge_sync_replay.py6.8 KB
- 脚本scripts/test_knowledge_sync.py38.5 KB
- 脚本scripts/test_kwipu_metadata.py6.8 KB
- 脚本scripts/test_kwipu_project_add.py41.4 KB
- 脚本scripts/test_manifest_publication.py6.1 KB
03 SKILL.md 正文
knowledge-services — de approved/ a un backend externo, sin acoplar el plugin a ninguno
Alcance y activación
Publica docs/knowledge/approved/ a backends externos (Kwipu y Graphiti) por config de proyecto (taxonomy.json). knowledge-sync.py --backend <id> [--dry-run|--check|--rebuild] carga el adaptador por type, aplica routing antes de construir entradas (fail-closed) y usa outbox.py para staging/dead-letter; un fallo de apply() puede dejar una publicación parcial recuperable, sin rollback global. Kwipu (markdown-export) genera un Markdown por entrada con frontmatter del Knowledge Gate y manifest.json; verify nombra el reindexado sin ejecutarlo. La lectura documental opcional usa knowledge-find.py --intent, con backend, read.enabled e intent habilitados; devuelve fuentes vinculadas y respuesta no verificada.
docs/knowledge/approved/ es el origen Markdown canónico, curado por knowledge-curator.
Su versionado en Git depende de la política del proyecto; la memoria propia de este repositorio
está excluida de Git. La recuperación local consulta tanto este corpus como ADR/GOT/LES legados.
Esta skill lo proyecta hacia fuera mediante los adaptadores Kwipu y Graphiti; otros backends
pueden declarar su propio type sin cambiar el núcleo (knowledge-sync.py). Instalar la skill
no habilita ni configura ningún servicio externo.
Módulo y puerto opcionales
Esta skill pertenece a memory-integrations, fuera del perfil core. Curación y
recuperación local conservan sus dueños en el shared kit y no la requieren.
Para usar un proveedor desde el workflow común, lee
Integración de proyecto: bindings del propósito
knowledge, backend exacto, autorización, routing y recibos existentes. Instalar el
módulo, declarar el binding y verificar una operación son estados diferentes.
Cuándo NO usarla
- Para curar o aprobar conocimiento: productores proponen por
agent-kits/shared/knowledge-curation.py;knowledge-curatorjuzga,curator-gate.pyvalida sin persistir y el servicio aplica con SHA original/motivo/metadatos. Esta skill sólo leeapproved/, nunca escribe ahí ni aprueba por sync. - Para consultar conocimiento: usa
agent-kits/shared/knowledge-find.py. Su router por--intentpuede consultar Graphiti en modoreado Kwipu mediante lectura documental opt-in. El router exige autorización explícita y conserva el respaldo local con su motivo. Leereferences/kwipu-adapter.mdsolo al configurar o depurar la lectura documental. - Para reindexar Kwipu de verdad (
build_view, reiniciar contenedores): esta skill nombra el remedio (verify), nunca lo ejecuta — es responsabilidad del stack externo (CA-16). - Sin
taxonomy.jsonconbackends.<id>.enabled: true, no hay nada que sincronizar:/doctorreporta la capacidad como desactivada, y eso es correcto, no un error.
Piezas
| Fichero | Qué es |
|---|---|
scripts/knowledge-sync.py |
Único punto de entrada; nunca menciona un backend concreto. |
scripts/kwipu-project-add.py |
Alta del proyecto en <stack>/kwipu/config/projects.yaml (/setup 5-sexies, C-07): solo añade un bloque marcado, con vista previa + sha256, confirmación (--apply --esperado) y copia .bak-<AAAAMMDDTHHMMSSZ>. Exit 0 ok/no-op · 1 E/S o fichero cambiado · 2 uso · 3 forma no reconocida (imprime el bloque) · 4 conflicto. Contrato en references/kwipu-adapter.md. |
backends/__init__.py |
Carga y valida el adaptador por type (backends/README.md: contrato completo de las 6 funciones). |
backends/markdown_export.py |
Adaptador Kwipu (type: "markdown-export"): CA-17/CA-16, ver references/kwipu-adapter.md. |
backends/graphiti.py + backends/graphiti_providers.py |
Adaptador Graphiti (type: "graphiti", ADR-018): cliente MCP, mode: off/shadow/read (default shadow), rebuild/revoke; los proveedores orientan la extracción del servidor — ver backends/README.md. |
agent-kits/shared/knowledge-find.py |
Recuperación local y router por --intent: lectura externa autorizada o fallback local con motivo; lee backends/README.md al configurar esa lectura. |
agent-kits/shared/knowledge-schema.py |
Taxonomía del proyecto (taxonomy.json), fail-closed; --setup-id-prefix propone/valida/guarda el id_prefix y avisa al renombrar con conocimiento ya exportado (CA-14/CA-15). Aviso de grupo ajeno de Graphiti: knowledge-sync.py --avisos-grupo [--consultar-servidor]. |
agent-kits/shared/knowledge-curation.py + agent-kits/shared/knowledge-curation-rules.py |
Dueños de persistencia y validación reutilizable en la fase anterior a sync; propose/apply/recover no se invocan para publicar ni sustituyen juicio del Curator. Referencias del bundle compartido, no un segundo gate. |
agent-kits/shared/knowledge-index.py |
Índice de approved/. |
agent-kits/shared/knowledge-local.py + knowledge-taxonomy-local.py |
Lectores compartidos sin red: corpus aprobado y reglas locales de taxonomía. |
agent-kits/shared/knowledge-view.py |
Snapshot acotado y consulta local compartidos por CLI/panel; validación aprobada pura sobre textos ya leídos, sin caché o backends. |
agent-kits/shared/knowledge-read-context.py + agent-kits/shared/local-read.py |
Autorización canónica y lectura estable acotada para el opt-in documental; dependencias del bundle portable. |
agent-kits/shared/outbox.py |
Staging/dead-letter reutilizado (CA-15), nunca reimplementado aquí. |
agent-kits/shared/capabilities.py |
Registro de capacidades opcionales (/setup, /doctor, T-09). |
Uso
Plugin instalable (regla 5 de docs/CONVENTIONS.md): localiza el script en runtime con el
patrón de seis raíces, nunca una ruta relativa fija.
R="${CLAUDE_PLUGIN_ROOT}"; M=agent-kits/shared/ledger-lint.py; [ -f "$R/$M" ] || R="$(for r in "$PWD"/.{claude,codex,opencode} ~/.{claude,codex}/plugins/cache/daycry ~/.{claude,codex,config/opencode}; do find "$r" -maxdepth 5 -path "*/$M" ! -path "$r/jobs/*" ! -path "$r/worktrees/*" 2>/dev/null | sort -V | tail -1 | grep . && break; done)"; R="${R%/$M}"; KSSKILL="${R:+$R/skills/knowledge-services/scripts/knowledge-sync.py}"
python3 "$KSSKILL" --backend kwipu --root . --check
python3 "$KSSKILL" --backend kwipu --root . --dry-run
python3 "$KSSKILL" --backend kwipu --root .
python3 "$KSSKILL" --backend kwipu --root . --rebuild
python3 "$KSSKILL" --backend kwipu --root . --outbox-status
--check:health()+verify(), no toca la publicación ni la outbox.exit 0solo siestado == "sano"yverify().ok.verify()tiene TRES veredictos (estado:ok·incompleto·desfase):incompleto(la ventana de lectura no alcanzó el grafo) NO esok, se imprime con suno_verificadoy suaviso, y sale ≠ 0.--dry-run: calculaplan()y lo imprime; nunca llama aapply()ni drena la outbox.- (ninguno): primero DRENA la outbox propia — reintenta cualquier envelope PENDIENTE de este
mismo backend cuyo backoff ya venció (
_drenar_outbox_propia, aplica susopsde forma idempotente; si vuelve a fallar, incrementaintentosde verdad y escala adead-letteral llegar aMAX_INTENTOS) — y LUEGO haceplan()+apply()reales del sync fresco, con staging/dead-letter deoutbox.py. Un envelope de OTRO backend que bloquee el reclamo se cede conoutbox.ceder_paso()sin tocar su presupuesto de reintentos. Un fallo deapply()en el sync fresco reencola con backoff (nunca dead-letter directo por un solo fallo); la proyección puede quedar parcialmente actualizada; el diario del adaptador conserva el objetivo pendiente. --rebuild:rebuild(entries, cfg)sobre TODAS las entradas ya enrutadas para ese backend (equivale aplan(entries, cfg, force=True)+apply, fuerzaupserten todo).--outbox-status: imprimeoutbox.estado()de la cola de este backend y sale — no publica ni drena nada. Es el diagnóstico de referencia cuando una corrida sospecha que hay envelopes atascados.
Añadir un backend nuevo: un fichero backends/<type>.py con las 6 funciones — ver
backends/README.md para el contrato exacto y references/kwipu-adapter.md para el ejemplo real
(Kwipu) con sus derivaciones documentadas (frontmatter CA-17, mapeo de salud, algoritmo de
verify).
Guardrails
- Fail-closed por routing: una categoría sin
routingdeclarado, orouting.<id>: false, jamás llega al adaptador — ni siquiera para "solo probar". - Recuperación por diario:
apply()de Markdown publica fichero a fichero con un diario (manifest.pending.json→ publica →manifest.json, verreferences/kwipu-adapter.md); nunca borra ni mueve ficheros ajenos a los que el propio manifiesto controla. Un fallo va primero a reencolado con backoff (outbox.py) y solo escala adead-letteral agotar los reintentos — no se repite el apply fresco dentro de la misma corrida, sí en la siguiente. El drenaje precede al plan fresco para reconciliar el destino con el canon actual. El lote no es atómico; archivos ya publicados o revocados no se revierten. El manifiesto final reintenta sólo rechazos Windows 5/32/33, hasta cuatro intentos y conservando las identidades observadas. verifynombra, no ejecuta (CA-16): el reindexado real es del stack, nunca de este plugin.- Lectura opt-in separada de publicar: backend habilitado,
read.enabled: truee intent declarado comotrue. Canon, routing, filtros y manifiesto preceden a la red/inferencia. El snapshot debe vincular todos los chunks antes de consultar; incoherencias vuelven a local. - Respuesta generada sin autoridad:
source_nodesidentifica fuentes recuperadas, no citas por afirmación. El lector no aprueba ni ejecuta instrucciones de esa respuesta. - Local sin Docker: panel y hooks mantienen lectura local; no consultan ni arrancan servicios.
- Validación no es aprobación/persistencia: gate e índice verifican contrato/forma; Curator
decide y
apply_decisionpersiste ligado al SHA. Design/revisión/QA/Gold/repetición no aprueban memoria nueva. Legado conserva bytes/estados/autoridad sin migración ni reaprobación automática; conflicto/alto impacto exige resolución humana trazada, no fecha/score. - Límites de la capa de curación: cerrojo cooperativo, etiquetas de actor no autenticadas, publicación/retirada/recibo separados; sin atomicidad multiarchivo ni sandbox universal. POSIX sincroniza directorios; el helper Windows no lo hace. La implementación y su revisión/QA no acreditan aceptación nativa o supervivencia a corte eléctrico. Esta skill no añade esos permisos.
- Una sola excepción a «no toca el stack» (enmienda de ADR-018 / PAT-001, diseño O1):
kwipu-project-add.pypuede AÑADIR un bloque aprojects.yaml, nunca modificar ni borrar;build_viewy el reinicio de contenedores solo se imprimen. - Sin dependencias externas: todo el código de esta skill es stdlib puro.
Los errores tipados de Graphiti se rechazan incluso con isError: false.
Los episodios nuevos se confirman con el UUID asignado por el servidor. Sucesión y
retirada tienen marcadores por versión; las relaciones documentales son el camino
predeterminado. Lee publicación y recuperación
al operar Graphiti. La aceptación integral de recuperación, reconstrucción e historial
sigue pendiente; la base local y el opt-in conservan sus contratos.
Qué NO hace
- No decide taxonomía ni categorías (eso es
taxonomy.json, por proyecto). - No aprueba ni rechaza conocimiento (eso es
knowledge-curator). - No registra el backend en Kwipu/Graphiti por su cuenta (nada de "auto-discovery" de red); el alta en
projects.yamlla lanza/setupcon confirmación del usuario y solo añade.
04 同仓库更多 Skills
tax
Guía fiscal duplicada
tax
Guía fiscal
demo-skill
Skill de ejemplo <script>alert(1)</script>.
voice-profile
Extrae un perfil de voz a partir de muestras autorizadas, con procedencia, rasgos observables y diferencias por canal. Úsala cuando el usuario diga "extrae mi estilo", "crea mi perfil de voz" o "analiza cómo escribo".
unit-tests
Pirámide de pruebas y gate de cobertura oficial, global o sobre ficheros cambiados. Sin herramienta avisa, no inventa porcentajes. No sustituye a TDD ni a E2E. Úsala cuando el usuario diga "sube la cobertura de tests", "qué % de cobertura tenemos", "pon un gate de cobertura", "pirámide de pruebas", "cuántos tests unitarios faltan", o cuando `dev.json` traiga `tests.coberturaMinima`.
training-data-services
Captura casos fuera de Git con esquema validado y ensambla datasets solo con Gold aprobado por humanos. Opt-in; el plugin no decide métricas, no marca Gold ni entrena. Úsala cuando el usuario diga "guarda este intento como caso", "captura casos para entrenar un modelo local", "valida el esquema del caso", "prepara un dataset con los casos aprobados", "activa training-data-services", o al activar la capacidad `training` desde `/setup`.