TokenKnows — distill AI coding sessions into weekly reports, ADRs and a knowledge graph

TokenKnows

将 AI 编码会话提炼为持续更新的知识——周报、ADR、事件复盘、书籍、Agent 技能和知识图谱。

English | 简体中文

---

TokenKnows 是什么？

你花数小时与 Claude Code、Codex 和 Cursor 结对编程。终端一关闭，这些会话中的决策、问题排查和设计权衡就随之消失。TokenKnows 会自动捕获这些内容，并将其提炼为结构化且关联证据的知识资产：

捕获（6 个采集器）→ 提炼（5 阶段大模型流水线）→ 资产（7 种文档类型）→ 审核 / 脱敏 / 发布

• 📡 全面捕获——通过本地文件监视器和 API 轮询，捕获 Claude Code、Codex、Cursor、VS Code、GitHub PR、提交、议题及本地文档。无需 Webhook 或隧道。
• 📝 七种资产类型——周报、技术设计、ADR、事件复盘、长篇书籍、可复用的 Agent 技能（SKILL.md）以及实体知识图谱。
• 🔗 关联证据——每个段落都可追溯到原始 PR / 对话 / 提交，并基于不少于 2 个来源，按 cosine × trust × recency 排序。
• 🔒 本地优先，默认零外传——三层大模型外传控制门（实例 ∧ 项目 ∧ 任务），并提供完整审计日志。搭配 Ollama，即可在无需任何云端密钥的情况下运行整个流水线。

Demo

Workbench	Document page
Evidence drawer	Publish receipt + version diff

▶ Full walkthrough: engineering_handoff/walkthrough.mp4 (5 min, Chinese narration + subtitles)

All 12 screens

1 Workbench	2 Event drawer	3 Document list	4 Document page
5 Evidence drawer	6 Regenerate dialog	7 Review	8 Redaction
9 Publish dialog	10 Publish receipt + diff	11 LLM egress	12 Admin

安装插件

前置条件：TokenKnows 后端运行于 http://localhost:8001，且 Web UI 运行于 http://localhost:5173（参见快速开始），以及 uv（插件通过 uvx 从 PyPI 获取 MCP 服务）。所有插件环境变量都有可用的本地默认值——仅在非默认配置下导出 TOKENKNOWS_API_BASE / TOKENKNOWS_API_TOKEN / TOKENKNOWS_DEFAULT_PROJECT / TOKENKNOWS_WEB_BASE。在 Web UI 中注册/登录，并在 Project Settings → MCP 接入 下创建 API 令牌（如果后端要求身份验证）。

平台	操作方法
Claude Code	/plugin marketplace add johnnywuj81/tokenknows → /plugin install tokenknows@tokenknows — 完整操作指南见 tokenknows-plugin/README.md（5 分钟快速入门）
Codex	codex plugin marketplace add johnnywuj81/tokenknows → codex plugin add tokenknows@tokenknows（加载技能、命令和 MCP 服务；本地克隆替代方案见 codex-plugin/README.md）
Cursor	将 tokenknows MCP 配置块添加到 ~/.cursor/mcp.json（uvx 配置示例见 code/tokenknows-mcp/README.md）
VS Code	从 Releases 下载 .vsix → code --install-extension tokenknows-vscode-*.vsix

该插件为你的 AI 工具提供 MCP 工具（submit_session_events、distill_document、list_assets、get_asset、get_asset_chapters、search_entity）以及 /tokenknows:weekly 和 /tokenknows:adr 等斜杠命令。

快速开始

# 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

平台支持：macOS — 完整体验（通过 launchd 自动启动采集器）。Linux — 后端、前端和采集器均需手动运行（python3 plugins/<x>/sync.py --watch）；launchd 脚本不适用。Windows — 未经测试；建议使用 WSL2。

数据采集器

全部在本地运行——无需 ngrok 或公共 Webhook。在 macOS 上，发生崩溃或重启后会自动恢复运行（launchd）。

采集器	来源	模式
claude-code	~/.claude/projects/*.jsonl	每 30 秒轮询，增量偏移量
codex	~/.codex/sessions/**/rollout-*.jsonl	每 30 秒轮询，增量偏移量
cursor	Cursor 的 state.vscdb（只读 SQLite）	每 60 秒轮询
github	GitHub REST API · PR / issue / commit	每 5 分钟轮询（gh auth 令牌）
vscode	VS Code 扩展 onDidSaveTextDocument	缓冲，10 秒刷新
local-docs	~/Documents 中的 .md .txt .pdf（watchdog）	实时，2 秒防抖

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

每个事件都带有可信度分数（0.6 × source_authority + 0.4 × extraction_confidence）；证据阶段按 0.6 × cosine + 0.25 × trust + 0.15 × recency 为引文排序，并要求至少有 2 个不同来源。

架构

采集器将数据送入事件存储（SQLite）。五阶段流水线（collect → outline → content → evidence → assess）将事件转化为资产。LLM Gateway 统一接入四个提供方（Anthropic / OpenAI / MiniMax / Ollama），支持按任务路由和回退链——只有三个外发开关全部开启时，才允许进行任何云端调用。

CI

工作流	运行器	触发条件
ci.yml	ubuntu-latest（GitHub 托管）	推送到 main + 每个 PR
ci-macos.yml	自托管 macOS ARM64	仅维护者推送到 main 时运行——绝不运行外部 PR 代码

隐私与本地优先

• 默认不向外发送数据——云端 LLM 调用要求实例、项目和任务开关全部开启
• 自带密钥；审计日志绝不会离开你的设备
• 一键关闭开关，可将实例切换至完全离线模式

详情：PRD §6.7 数据驻留与外发控制（中文）。

文档

主题	文档
产品需求、用户旅程	PRD（中文）
技术设计、API、架构	TDD（中文）
宏观架构与里程碑	Architecture（中文）
各屏幕的工程决策	TaskTechDesign（中文）
像素级 UI 模型图	mockups/ — 在浏览器中打开

大多数深入的文档都使用中文（项目的工作语言）。代码注释也主要使用中文；欢迎使用英文或中文提交问题和 PR。

社区

贡献指南 · 路线图 · 行为准则 · 安全政策 · 问题

许可证

MIT © 2026 johnnywuj81