Knowledge Miner
3499764081hly-collab/knowledge-miner
Converta conversas de IA em conhecimento estruturado e reutilizável
Ver no GitHubServidor MCP local que extrai conversas de agentes IA (Claude Code, Hermes) e as transforma em uma base de conhecimento estruturada e reutilizável. Captura correções de bugs, novas soluções, padrões de trabalho e boas práticas em formato JSON otimizado para leitura por agentes.
Instalação
npx convez-ai 3499764081hly-collab/knowledge-miner1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consolidar aprendizados de múltiplas sessões com agentes IA em uma base de conhecimento centralizada
- Rastrear correções de bugs e soluções para reutilizar em novos projetos
- Sincronizar conhecimento capturado com documentação em Feishu/Lark
Veredito

Ferramenta especializada para quem trabalha intensivamente com agentes IA e precisa preservar conhecimento gerado nessas interações. Exige familiaridade com Python, variáveis de ambiente e estruturas JSON, mas oferece ganhos significativos em reutilização de insights entre sessões.
README
A tradução para o português deste README ainda está na fila.
knowledge-miner
从 AI agent 聊天记录中沉淀个人知识库的本地 MCP 工具。
当前项目面向 /Users/Zhuanz1/Desktop/AI-Knowledge-Base/knowledge-base.json,把 Claude Code / Hermes 等 agent 会话里的踩坑、修复、思考方式和工作流沉淀为可被后续 agent 读取的结构化知识。
如果不是这台机器,请把示例中的 /Users/Zhuanz1/Desktop/knowledge-miner 和 /Users/Zhuanz1/Desktop/AI-Knowledge-Base/knowledge-base.json 替换为你自己的项目路径和知识库路径。
当前能力
- 读取 Claude Code 项目会话:默认目录
~/.claude/projects - 读取 Hermes 会话:默认目录
~/.hermes/sessions - 输出到本地 JSON 知识库
- 兼容
AI-Knowledge-Base的外层分类:bug修复、新功能、最佳实践、行业动态 - 写入时保留未知顶层字段、自定义分类和已有条目的自定义字段
- 在
agent_knowledge中保存更适合 agent 读取的内部结构 - dry-run 会显示解析诊断,包括坏行、坏消息、文件错误和时间过滤数量
- 按消息时间过滤近期内容,避免老会话中的新消息被整段跳过
- 写入前自动备份已有知识库文件
- 默认预览不写入,真实写入必须显式确认
- 配置加载会校验数据源、分析粒度、内容优先级、布尔环境变量和输出路径
- 提供 MCP Server:知识沉淀、知识读取、飞书授权引导、飞书文档配置和统计工具
Cursor、Windsurf 专用日志解析和定时任务是后续扩展方向,目前不是已完成能力。
本地开发安装
要求:
- Python 3.10 或更高版本;macOS 系统自带 Python 3.9 不能直接安装本项目
- 如需飞书云文档同步,需先让
lark-cli在 PATH 中可用,建议使用 Node 版@larksuite/cli
在项目目录安装:
cd /Users/Zhuanz1/Desktop/knowledge-miner
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"
检查版本:
.venv/bin/python --version
command -v lark-cli
lark-cli --version
本机当前可直接使用:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner --help
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner doctor
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner doctor --mcp-smoke
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner doctor --acceptance
CLI 使用
默认只预览,不写入:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner mine --source claude --days 7
确认写入:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner mine --source claude --days 7 --yes
显式 dry-run:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner mine --source claude --days 7 --dry-run
读取知识库:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner read --section pitfalls
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner read --format json
查看统计:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner stats
检查本地环境:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner doctor
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner doctor --mcp-smoke
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner doctor --acceptance
doctor --acceptance 会用临时 Hermes 会话和临时知识库路径跑完整 stdio MCP 流程:列工具、默认预览不写入、confirm_write=true 后写入、再读取统计。它不会修改真实的 /Users/Zhuanz1/Desktop/AI-Knowledge-Base/knowledge-base.json。
MCP Server 接入
优先直接生成本机 MCP 配置片段:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner config --mcp-json
本机建议用 venv 里的绝对路径,避免 Claude/Codex 启动时找不到命令:
{
"mcpServers": {
"knowledge-miner": {
"command": "/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner",
"args": ["mcp-server"],
"env": {
"KM_DATA_SOURCES": "claude,hermes",
"KM_OUTPUT_PATH": "/Users/Zhuanz1/Desktop/AI-Knowledge-Base/knowledge-base.json",
"KM_FEISHU_ENABLED": "true",
"KM_FEISHU_DOC_URL": "https://your-domain.feishu.cn/wiki/your-wiki-token"
}
}
}
}
通用模板:
{
"mcpServers": {
"knowledge-miner": {
"command": "/ABSOLUTE/PATH/TO/knowledge-miner/.venv/bin/knowledge-miner",
"args": ["mcp-server"],
"env": {
"KM_DATA_SOURCES": "claude,hermes",
"KM_OUTPUT_PATH": "/ABSOLUTE/PATH/TO/knowledge-base.json"
}
}
}
}
如果已经全局安装,也可以使用:
{
"mcpServers": {
"knowledge-miner": {
"command": "knowledge-miner",
"args": ["mcp-server"]
}
}
}
飞书云文档授权
飞书云文档同步依赖用户本机的 lark-cli。公开使用时,每个用户都授权自己的飞书账号,并配置自己的知识库文档 URL;仓库不会内置作者的飞书文档。
注意:lark-cli 是外部 CLI,不是本项目的 Python 依赖;请先按飞书 / Lark CLI 的安装方式安装,并确认 lark-cli --version 至少为 1.0.51。
如果 agent 已接入本 MCP,可以直接走 MCP 工具授权,不需要用户手动记命令:
- agent 调用
feishu_auth_status检查当前本机授权和文档配置。 - agent 调用
start_feishu_auth。 - 如果用户本机还没有初始化过
lark-cli,MCP 会先返回飞书 CLI 配置 URL 和二维码图片路径;agent 展示给用户,用户完成配置后,agent 再次调用start_feishu_auth。 - MCP 返回飞书用户授权 URL 和本地二维码图片路径,agent 把 URL 或二维码展示给用户。
- 用户在浏览器中完成飞书授权。
- agent 调用
complete_feishu_auth完成本机lark-cli授权落地。 - agent 调用
set_feishu_doc预览用户自己的飞书文档 URL;确认无误后,再带confirm_write: true保存配置。
首次配置时,start_feishu_auth 返回内容会包含类似:
配置 URL:
https://open.feishu.cn/page/cli?...
二维码图片:
/Users/you/.knowledge-miner/feishu-setup-qr.png
完成配置后再次调用 start_feishu_auth,返回内容会包含类似:
授权 URL:
https://passport.feishu.cn/...
二维码图片:
/Users/you/.knowledge-miner/feishu-auth-qr.png
如果想手动完成授权,也可以直接使用 lark-cli:
lark-cli auth status
lark-cli auth login --scope "docx:document:readonly docx:document:write_only wiki:node:read wiki:space:read offline_access"
授权成功并配置文档后,MCP 才能通过 record_knowledge 把内容写入用户自己的飞书云文档。未传 confirm_write: true 时,set_feishu_doc 和 record_knowledge 都只返回预览,不会修改配置或写入文档。
MCP 工具
| 工具 | 功能 | 关键参数 |
|---|---|---|
mine_knowledge | 从会话中提取知识并预览或写入知识库 | days, source, dry_run, confirm_write |
get_knowledge | 读取已沉淀的知识 | section |
record_knowledge | 让任意 agent 主动提交一条知识;确认后写入本地知识库,并可同步飞书云文档 | record_type, title, summary, target, confirm_write |
feishu_auth_status | 检查本机 lark-cli 授权状态和当前飞书文档配置 | 无 |
start_feishu_auth | 发起飞书授权,返回授权 URL 和二维码图片路径 | scopes |
complete_feishu_auth | 用户完成网页授权后,完成本机授权落地 | device_code |
set_feishu_doc | 配置当前用户自己的飞书知识库文档 URL;默认只预览 | doc_url, dry_run, confirm_write |
get_stats | 查看知识库统计 | 无 |
mine_knowledge 默认不写入。真实写入必须传:
{
"source": "claude",
"days": 7,
"confirm_write": true
}
只预览:
{
"source": "claude",
"days": 7,
"dry_run": true
}
主动提交一条知识。默认也只预览:
{
"record_type": "pitfall",
"title": "写入外部文档前必须 dry-run",
"summary": "涉及飞书云文档或本地知识库写入时,默认不应直接修改。",
"solution": "先 preview,用户确认后再传 confirm_write=true。",
"subcategory": "配置类",
"source_agent": "claude-code",
"target": "all"
}
确认写入本地和飞书:
{
"record_type": "pitfall",
"title": "写入外部文档前必须 dry-run",
"summary": "涉及飞书云文档或本地知识库写入时,默认不应直接修改。",
"solution": "先 preview,用户确认后再传 confirm_write=true。",
"subcategory": "配置类",
"source_agent": "claude-code",
"target": "all",
"confirm_write": true
}
配置文件
配置文件路径:
~/.knowledge-miner/config.json
MCP 配置中的 KM_* 环境变量会覆盖这个配置文件,适合在不同 agent 中指定不同数据源或输出路径。
配置加载会拒绝未知字段和非法值,例如未知数据源、空 data-sources、非法 analysis-granularity、非法 content-priority、布尔环境变量拼写错误,或 output-path 指向目录。
生成配置:
/Users/Zhuanz1/Desktop/knowledge-miner/.venv/bin/knowledge-miner config --init
示例:
{
"data-sources": ["claude", "hermes"],
"claude-projects-dir": "~/.claude/projects",
"hermes-sessions-dir": "~/.hermes/sessions",
"output-path": "/Users/Zhuanz1/Desktop/AI-Knowledge-Base/knowledge-base.json",
"feishu-enabled": false,
"feishu-doc-url": "https://my.feishu.cn/wiki/...",
"analysis-granularity": "global",
"content-priority": ["pitfalls", "thinking_patterns", "workflows", "communication_style"],
"cron-enabled": false,
"cron-schedule": "0 23 * * *"
}
隐私与安全
knowledge-miner 会读取本机 AI agent 会话目录,例如 ~/.claude/projects 和 ~/.hermes/sessions。这些会话可能包含 API key、客户信息、文件路径、错误日志或业务细节。
默认安全行为:
- CLI
mine默认只预览,不写入;真实写入必须加--yes - MCP
mine_knowledge默认只预览,不写入;真实写入必须传confirm_write: true - MCP
record_knowledge默认只预览,不写入;真实写入本地或飞书也必须传confirm_write: true - MCP
set_feishu_doc默认只预览,不修改本地配置;保存用户自己的飞书文档必须传confirm_write: true - 接入前可运行
knowledge-miner doctor --mcp-smoke验证 stdio MCP 握手和工具列表 - 接入前可运行
knowledge-miner doctor --acceptance用临时数据验证 MCP 端到端写入链路 - 写入已有知识库前会先生成
.bak备份文件 - 写入会做保守合并,尽量保留用户自定义字段和分类
- 如果现有知识库 JSON 损坏,会先生成
.corrupt.bak,然后拒绝覆盖 - MCP 参数会做运行时校验,字符串
"false"不会被当成确认写入
建议流程:
- 先运行
knowledge-miner doctor - 再运行
knowledge-miner doctor --mcp-smoke和knowledge-miner doctor --acceptance - 先运行
knowledge-miner mine --source claude --days 7看 dry-run 预览 - 确认预览内容没有敏感信息后,再用
--yes或 MCPconfirm_write: true写入 - 如需公开分享知识库,请先人工检查并脱敏
环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
KM_DATA_SOURCES | 数据源,逗号分隔 | claude,hermes |
KM_CLAUDE_DIR | Claude Code 项目目录 | ~/.claude/projects |
KM_HERMES_DIR | Hermes 会话目录 | ~/.hermes/sessions |
KM_OUTPUT_PATH | 知识库输出路径 | 优先使用 ~/Desktop/AI-Knowledge-Base/knowledge-base.json |
KM_FEISHU_ENABLED | 是否启用飞书配置字段 | false |
KM_FEISHU_DOC_URL | 飞书云文档 / Wiki 知识库大纲 URL | 空 |
KM_GRANULARITY | 分析粒度配置字段 | global |
KM_PRIORITY | 内容优先级,逗号分隔 | pitfalls,thinking_patterns,workflows,communication_style |
KM_CRON_ENABLED | 是否启用定时配置字段 | false |
KM_CRON_SCHEDULE | 定时配置字段 | 0 23 * * * |
输出结构
写入 /Users/Zhuanz1/Desktop/AI-Knowledge-Base/knowledge-base.json 时会保留外层知识库结构:
{
"version": "2.0",
"categories": {
"bug修复": [],
"新功能": [],
"最佳实践": [],
"行业动态": []
},
"agent_knowledge": {
"metadata": {},
"pitfalls": {"items": []},
"thinking_patterns": {"items": []},
"workflows": {"items": []},
"communication_style": {}
}
}
get_knowledge 会优先返回 agent_knowledge 视图,便于 agent 直接读取。
验收命令
cd /Users/Zhuanz1/Desktop/knowledge-miner
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests
.venv/bin/knowledge-miner doctor
.venv/bin/knowledge-miner doctor --mcp-smoke
.venv/bin/knowledge-miner mine --source claude --days 7
最后一条命令未加 --yes 时应只输出预览,并且不修改真实知识库文件。