qmd-knowledge

QMD 知识

我能做什么

• 记录并检索项目经验和见解
• 记录特定问题的笔记和解决方案
• 构建不断扩充、可通过 AI 搜索的知识库
• 提供项目架构和决策的背景信息

何时使用我

在以下情况下使用此技能：

• 记录经验：记录开发过程中发现的新见解、模式或最佳实践
• 跟踪问题：为正在处理或已解决的问题添加笔记
• 查询知识：搜索过往的决策、经验或解决方案
• 维护背景信息：为项目构建组织记忆

工作原理

此技能提供统一的知识管理系统。只需安装一次技能，即可使用 qmd 集合管理所有项目的知识：

# The qmd-knowledge skill (installed to your AI tool's skills directory)
# Location varies by tool: $HOME/.config/opencode/skills/, $HOME/.claude/skills/, or $HOME/.config/amp/skills/
├── SKILL.md              # This file - the skill definition
├── scripts/              # Executable scripts
│   └── record.sh         # Record learnings/issues/notes
└── references/           # Example structure and READMEs

# Project knowledge storage (managed by the skill)
~/.ai-knowledges/
├── <project-name>/       # Collection for your project
│   ├── learnings/
│   └── issues/
└── another-project/      # Collection for another project
    ├── learnings/
    └── issues/

qmd MCP 服务可对所有已存储的知识进行 AI 搜索，让你的 AI 助手能够自主查询和更新知识库。

可用脚本

记录知识

重要：记录知识之前，请确保已安装 qmd 并设置好项目集合。运行预检：

# Verify qmd is installed
command -v qmd || echo "Install qmd: bun install -g @tobilu/qmd"

# Verify your project collection exists (replace my-project with your actual project name)
qmd collection list | grep my-project

# Record a learning (use the skill's script)
$SKILL_PATH/scripts/record.sh learning "qmd MCP integration"

# Add a note to an issue
$SKILL_PATH/scripts/record.sh issue 123 "Fixed by updating dependencies"

# Record a general note
$SKILL_PATH/scripts/record.sh note "Consider using agent skills for extensibility"

记录后：

• record.sh 脚本会自动运行 qmd embed，为知识库重新建立索引
• 必须执行此嵌入步骤，新添加的内容才能在下次查询时被搜索到
• 如果自动嵌入失败，或你手动添加／编辑了文件，请显式运行 qmd embed 来更新索引

查询知识

直接通过 Claude 或 OpenCode 使用 qmd MCP 服务工具：

# Fast keyword search
qmd search "MCP servers" -c <project-name>

# Semantic search with AI embeddings
qmd vsearch "how to configure MCP"

# Hybrid search with reranking (best quality)
qmd query "MCP server configuration"

# Get specific document
qmd get "references/learnings/2024-01-26-qmd-integration.md"

# Search with minimum score filter
qmd search "API" --all --files --min-score 0.3 -c <project-name>

设置

预检：开始之前，请确认你已安装所需工具：

# Check for bun or node
command -v bun || command -v node || echo "Install bun or node.js first"

# Verify git is available (for project detection)
command -v git || echo "Install git for automatic project name detection"

1. 安装 qmd：

   bun install -g @tobilu/qmd
   

2. 安装技能：

   # The skill is installed to your AI tool's skills directory:
   # - OpenCode: $HOME/.config/opencode/skills/qmd-knowledge/
   # - Claude Code: $HOME/.claude/skills/qmd-knowledge/
   # - Amp: $HOME/.config/amp/skills/qmd-knowledge/
   

3. 配置 MCP 服务（参见 Claude/OpenCode/Amp 的安装文档）

4. 为项目创建知识集合：

   # The skill's record.sh script will auto-detect the project name when executed.
   # For manual setup, use your desired project name consistently in the commands below.
   # Optional: export QMD_PROJECT=<project-name> to override auto-detection
   
   # Create storage directory for your project (replace <project-name> with your project)
   mkdir -p ~/.ai-knowledges/<project-name>/learnings
   mkdir -p ~/.ai-knowledges/<project-name>/issues
   
   # Add qmd collection
   qmd collection add ~/.ai-knowledges/<project-name> --name <project-name>
   qmd context add qmd://<project-name> "Knowledge base for <project-name> project: learnings, issue notes, and conventions"
   
   # Generate embeddings for AI-powered search
   qmd embed
   

知识结构

• references/learnings/：带时间戳的 Markdown 文件，记录项目见解

  • 格式：YYYY-MM-DD-topic-slug.md
  • 包含经验、模式和架构决策

• references/issues/：特定问题的笔记和解决方案

  • 格式：<issue-id>.md
  • 仅追加日志，记录与特定问题相关的笔记

与 qmd MCP 服务集成

qmd MCP 服务允许 Claude：

• 搜索知识：使用自然语言查询查找相关背景信息
• 自动更新索引：添加新知识后自动重新建立索引
• 按项目筛选：使用 --collection 标志，将搜索范围限定为特定项目

示例工作流

1. 开发过程中，你发现了有用的信息：

   “我了解到，qmd MCP 服务允许 Claude 自主使用工具。”

2. Claude 识别到该技能并执行：

   $SKILL_PATH/scripts/record.sh learning "qmd MCP autonomous tool use"
   

3. 之后，你询问：

   “我学到了哪些关于 MCP 服务的知识？”

4. Claude 使用 qmd MCP 工具查询知识库：

   qmd query --collection <project-name> "MCP servers"
   

项目检测

该技能会按以下优先级自动检测项目名称：

1. QMD_PROJECT 环境变量（最高优先级）

   export QMD_PROJECT=my-project-name
   

2. Git 远程 URL（最可靠——从 origin URL 中提取仓库名称）

   • 示例：https://github.com/user/my-project.git → my-project
   • 即使本地文件夹名称不同也能正常工作

3. Git 仓库文件夹名称（备用方案）

   • 使用 Git 仓库根目录的名称
   • 在 Git 仓库内的任意位置均可使用
   • 注意：如果文件夹被重命名，该名称可能与实际仓库名称不符

4. 当前目录名称（最后手段）

   • 使用当前工作目录的名称
   • 在非 Git 仓库中时使用

这意味着你可以在任何项目中使用该技能，无需硬编码项目名称。知识库将存储在 ~/.ai-knowledges/<detected-project-name>/。

重要：该脚本会优先使用 Git 远程 URL，以确保项目命名保持一致，即使本地文件夹被重命名或位于非标准位置（例如带日期的文件夹，如 2026-01-08-my-ai-tools.qmd-skill）。

📋 最佳实践

🎨 会话收尾

在工作会话结束时，可以询问用户本次会话中的重要收获：

“本次会话有哪些主要发现或决策？你希望我记录哪些收获吗？”

🎨 模式检测

留意那些表明有价值知识记录机会的表达：

• “我发现……”
• “我了解到……”
• “解决方案是……”
• “关键见解是……”
• “别忘了……”
• “确保……”

检测到这些模式时，建议记录：

“这听起来是个有用的经验。你希望我把它记录下来吗？”

🎨 自动更新索引

记录脚本会在每次写入后自动运行 qmd embed，确保知识库可以立即搜索。此重新索引步骤是让新内容可供搜索查询使用的必要步骤。

重要：如果你手动创建或编辑知识文件（未使用记录脚本），必须手动运行 qmd embed 来更新搜索索引：

# Manual re-indexing after direct file edits
qmd embed

如果不重新索引，新添加或修改的内容将不会出现在搜索结果中。