TokenKnows

TokenKnows

Convierte sesiones de codificación con IA en conocimiento vivo: informes semanales, ADRs, revisiones de incidentes, libros, habilidades de agentes y un grafo de conocimiento.

English | 简体中文

---

¿Qué es TokenKnows?

Pasas horas programando en pareja con Claude Code, Codex y Cursor. Las decisiones, las cacerías de errores y las compensaciones de diseño de esas sesiones se evaporan en el momento en que se cierra la terminal. TokenKnows las captura automáticamente y las destila en activos de conocimiento estructurados y vinculados a evidencia:

captura (6 recolectores) → destila (pipeline LLM de 5 etapas) → activos (7 tipos de documentos) → revisión / redacción / publicación

• 📡 Captura todo — Claude Code, Codex, Cursor, VS Code, PRs/commits/issues de GitHub y documentos locales, todo mediante observadores de archivos locales y sondeos de API. Sin webhooks, sin túneles.
• 📝 Siete tipos de activos — informes semanales, diseños técnicos, ADRs, revisiones de incidentes, libros de formato largo, habilidades de agentes reutilizables (SKILL.md) y un grafo de conocimiento de entidades.
• 🔗 Vinculado a evidencia — cada párrafo se remonta al PR / conversación / commit original, clasificado por cosine × trust × recency en ≥2 fuentes.
• 🔒 Local primero, cero salida de datos por defecto — una puerta de salida LLM de tres capas (instancia ∧ proyecto ∧ tarea) con registro de auditoría completo. Combínalo con Ollama y ejecuta todo el pipeline con cero claves en la nube.

Demo

Workbench	Página de documento
Panel de evidencia	Recibo de publicación + diff de versión

▶ Recorrido completo: engineering_handoff/walkthrough.mp4 (5 min, narración en chino + subtítulos)

Las 12 pantallas

1 Workbench	2 Panel de eventos	3 Lista de documentos	4 Página de documento
5 Panel de evidencia	6 Diálogo de regeneración	7 Revisión	8 Redacción
9 Diálogo de publicación	10 Recibo de publicación + diff	11 Salida LLM	12 Administración

Instalar el plugin

Requisito previo: el backend de TokenKnows en http://localhost:8001 y la interfaz web en http://localhost:5173 (consulta Inicio rápido), además de uv (el plugin extrae el servidor MCP de PyPI mediante uvx). Todas las variables de entorno del plugin tienen valores locales predeterminados funcionales: exporta TOKENKNOWS_API_BASE / TOKENKNOWS_API_TOKEN / TOKENKNOWS_DEFAULT_PROJECT / TOKENKNOWS_WEB_BASE solo para configuraciones no predeterminadas. Regístrate o inicia sesión en la interfaz web y crea un token de API en Configuración del proyecto → MCP 接入 cuando tu backend requiera autenticación.

Plataforma	Cómo
Claude Code	/plugin marketplace add johnnywuj81/tokenknows → /plugin install tokenknows@tokenknows — recorrido completo en tokenknows-plugin/README.md (inicio rápido de 5 minutos)
Codex	codex plugin marketplace add johnnywuj81/tokenknows → codex plugin add tokenknows@tokenknows (carga habilidades, comandos y el servidor MCP; alternativa de clon local en codex-plugin/README.md)
Cursor	Agrega el bloque MCP de tokenknows a ~/.cursor/mcp.json (ejemplo de configuración uvx en code/tokenknows-mcp/README.md)
VS Code	Descarga el .vsix desde Releases → code --install-extension tokenknows-vscode-*.vsix

El plugin le da a tu herramienta de IA herramientas MCP (submit_session_events, distill_document, list_assets, get_asset, get_asset_chapters, search_entity) además de comandos de barra como /tokenknows:weekly y /tokenknows:adr.

Inicio rápido

# 1. (Optional but recommended) Ollama — fully local inference, zero cloud keys
ollama serve &
ollama pull minimax-m2:cloud          # or gpt-oss:20b, qwen2.5, ...

# 2. Backend (FastAPI + SQLite persistence + 3-layer LLM egress gate)
cd code/tokenknows-api
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
cp .env.local.example .env.local      # defaults to Ollama; edit to add cloud providers
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8001

# 3. Frontend (React 19 + Vite)
cd code/tokenknows-web
npm install
npm run dev
# open http://localhost:5173 — talks to the real backend (mocks are opt-in via ?msw=1)

# (Optional) seed demo data
./engineering_handoff/demo-seed.sh

Soporte de plataformas: macOS — experiencia completa (los recolectores se inician automáticamente mediante launchd). Linux — backend, frontend y recolectores se ejecutan manualmente (python3 plugins/<x>/sync.py --watch); los scripts de launchd no aplican. Windows — no probado; se recomienda WSL2.

Recolectores de datos

Todo local — sin ngrok, sin webhooks públicos. En macOS se reinician ante fallos y al reiniciar el sistema (launchd).

Recolector	Fuente	Modo
claude-code	~/.claude/projects/*.jsonl	Sondeo de 30s, offsets incrementales
codex	~/.codex/sessions/**/rollout-*.jsonl	Sondeo de 30s, offsets incrementales
cursor	state.vscdb de Cursor (SQLite de solo lectura)	Sondeo de 60s
github	API REST de GitHub · PRs / issues / commits	Sondeo de 5min (token gh auth)
vscode	Extensión de VS Code onDidSaveTextDocument	Almacenado en búfer, vaciado de 10s
local-docs	~/Documents .md .txt .pdf (watchdog)	Tiempo real, rebote de 2s

./scripts/launchd/install.sh          # macOS: install all 5 Python collectors as LaunchAgents
launchctl list | grep com.tokenknows
tail -f ~/Library/Logs/tokenknows/*.log

Cada evento lleva una puntuación de confianza (0.6 × source_authority + 0.4 × extraction_confidence); la etapa de evidencia clasifica las citas por 0.6 × cosine + 0.25 × trust + 0.15 × recency y exige ≥2 fuentes distintas.

Arquitectura

Los recolectores alimentan un almacén de eventos (SQLite). Un pipeline de cinco etapas (recolectar → esquema → contenido → evidencia → evaluar) convierte los eventos en activos. La puerta de enlace LLM unifica cuatro proveedores (Anthropic / OpenAI / MiniMax / Ollama) con enrutamiento por tarea y cadenas de respaldo — y rechaza cualquier llamada en la nube a menos que los tres interruptores de salida estén activados.

CI

Flujo de trabajo	Ejecutor	Disparador
ci.yml	ubuntu-latest (alojado en GitHub)	push a main + cada PR
ci-macos.yml	macOS ARM64 autoalojado	el mantenedor hace push a main únicamente — nunca ejecuta código de PRs externos

Privacidad y local primero

• Cero salida de datos por defecto — las llamadas LLM en la nube requieren que los interruptores de instancia y proyecto y tarea estén todos activados
• Trae tus propias claves; el registro de auditoría nunca sale de tu máquina
• Interruptor de apagado con un clic que deja la instancia en modo totalmente fuera de línea

Detalles: PRD §6.7 residencia de datos y control de salida (chino).

Documentación

Tema	Documento
Requisitos del producto, recorridos de usuario	PRD (zh)
Diseño técnico, API, esquema	TDD (zh)
Arquitectura macro e hitos	Architecture (zh)
Decisiones de ingeniería por pantalla	TaskTechDesign (zh)
Maquetas de UI a nivel de píxel	mockups/ — ábrelas en un navegador

La mayoría de los documentos detallados están en chino (el idioma de trabajo del proyecto). Los comentarios de código también son predominantemente en chino; los issues y PRs en inglés o chino son bienvenidos.

Comunidad

CONTRIBUTING · Roadmap · Código de conducta · Política de seguridad · Issues

Licencia

MIT © 2026 johnnywuj81