convez.ai
MCP ServerAutomaçãoAvançado
3499764081hly-collab

Knowledge Miner

3499764081hly-collab/knowledge-miner

Converta conversas de IA em conhecimento estruturado e reutilizável

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-miner

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 工具授权,不需要用户手动记命令:

  1. agent 调用 feishu_auth_status 检查当前本机授权和文档配置。
  2. agent 调用 start_feishu_auth。
  3. 如果用户本机还没有初始化过 lark-cli,MCP 会先返回飞书 CLI 配置 URL 和二维码图片路径;agent 展示给用户,用户完成配置后,agent 再次调用 start_feishu_auth。
  4. MCP 返回飞书用户授权 URL 和本地二维码图片路径,agent 把 URL 或二维码展示给用户。
  5. 用户在浏览器中完成飞书授权。
  6. agent 调用 complete_feishu_auth 完成本机 lark-cli 授权落地。
  7. 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" 不会被当成确认写入

建议流程:

  1. 先运行 knowledge-miner doctor
  2. 再运行 knowledge-miner doctor --mcp-smoke 和 knowledge-miner doctor --acceptance
  3. 先运行 knowledge-miner mine --source claude --days 7 看 dry-run 预览
  4. 确认预览内容没有敏感信息后,再用 --yes 或 MCP confirm_write: true 写入
  5. 如需公开分享知识库,请先人工检查并脱敏

环境变量

变量说明默认值
KM_DATA_SOURCES数据源,逗号分隔claude,hermes
KM_CLAUDE_DIRClaude Code 项目目录~/.claude/projects
KM_HERMES_DIRHermes 会话目录~/.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 时应只输出预览,并且不修改真实知识库文件。

Ver o original no GitHub

Bom para

Relacionados