feat: add qmd

Author: suemor233

.gitignore

@@ -7,3 +7,4 @@ coverage
 repomix-output.xml
 .worktrees
 .claude/worktrees
+.search/

apps/cli/src/commands/search.ts

@@ -0,0 +1,84 @@
+import type { Command } from 'commander'
+import * as p from '@clack/prompts'
+import { SearchManager, Workspace } from '@marchen-spec/core'
+import pc from 'picocolors'
+import { handleError } from '../utils/error.js'
+
+/**
+ * 注册 search 命令
+ *
+ * 语义搜索归档变更历史
+ *
+ * @param program - Commander 程序实例
+ */
+export function registerSearchCommand(program: Command): void {
+  program
+    .command('search <query>')
+    .description('语义搜索归档变更历史')
+    .option('-n, --limit <number>', '结果数量', '5')
+    .option('--min-score <number>', '最低分数阈值', '0.3')
+    .option('--json', '输出 JSON 格式')
+    .option('--rebuild', '重建索引后搜索')
+    .action(
+      async (
+        query: string,
+        options: {
+          limit?: string
+          minScore?: string
+          json?: boolean
+          rebuild?: boolean
+        },
+      ) => {
+        try {
+          const workspace = new Workspace()
+          const search = new SearchManager(workspace)
+
+          if (!(await search.isAvailable())) {
+            p.log.error('搜索功能不可用（qmd 加载失败）')
+            process.exit(1)
+          }
+
+          if (options.rebuild) {
+            if (!options.json) p.log.info('正在重建索引...')
+            await search.index()
+            if (!options.json) p.log.success('索引重建完成')
+          }
+
+          const results = await search.search(query, {
+            limit: Number(options.limit),
+            minScore: Number(options.minScore),
+          })
+
+          if (options.json) {
+            console.log(JSON.stringify(results, null, 2))
+            await search.close()
+            return
+          }
+
+          if (results.length === 0) {
+            p.log.info('未找到匹配结果')
+            await search.close()
+            return
+          }
+
+          for (const r of results) {
+            const score = Math.round(r.score * 100)
+            const scoreColor =
+              score >= 70
+                ? pc.green(`${score}%`)
+                : score >= 40
+                  ? pc.yellow(`${score}%`)
+                  : pc.dim(`${score}%`)
+            p.log.info(`${pc.bold(r.path)}  ${scoreColor}`)
+            if (r.snippet) {
+              p.log.message(pc.dim(r.snippet.slice(0, 200)))
+            }
+          }
+
+          await search.close()
+        } catch (error) {
+          handleError(error)
+        }
+      },
+    )
+}

apps/cli/src/program.ts

@@ -5,6 +5,7 @@ import { registerInitCommand } from './commands/init.js'
 import { registerInstructionsCommand } from './commands/instructions.js'
 import { registerListCommand } from './commands/list.js'
 import { registerNewCommand } from './commands/new.js'
+import { registerSearchCommand } from './commands/search.js'
 import { registerStatusCommand } from './commands/status.js'
 import { registerUpdateCommand } from './commands/update.js'
 
@@ -29,6 +30,7 @@ export function buildCliProgram(): Command {
   registerInstructionsCommand(program)
   registerListCommand(program)
   registerNewCommand(program)
+  registerSearchCommand(program)
   registerStatusCommand(program)
   registerUpdateCommand(program)
 

apps/cli/tsdown.config.ts

@@ -4,6 +4,7 @@ export default defineConfig({
   entry: ['./src/index.ts'],
   deps: {
     alwaysBundle: [/^@marchen-spec\//],
+    neverBundle: ['@tobilu/qmd', 'node-llama-cpp'],
   },
   platform: 'node',
   format: ['esm'],

marchen/changes/integrate-qmd-search/.metadata.yaml

@@ -0,0 +1,4 @@
+name: integrate-qmd-search
+schema: full
+createdAt: '2026-04-23T14:05:05.210Z'
+status: open

marchen/changes/integrate-qmd-search/design.md

@@ -0,0 +1,85 @@
+## 背景
+
+MarchenSpec 的 archive 目录包含 30 个归档变更、132 个 markdown 文件、5400 行内容。当前 AI 获取历史的方式是 `cat changelog.md`（30 行摘要）或 `grep`（关键词匹配，无语义理解）。
+
+qmd 是一个本地搜索引擎，提供 BM25 + 向量搜索 + LLM rerank 三级流水线，有 Node.js SDK 可直接 import。
+
+## 目标与非目标
+
+**目标：**
+- `marchen search` 命令提供语义搜索能力
+- archive 时自动更新索引，用户无感知
+- qmd 加载失败时优雅降级，不影响现有功能
+- explore skill 自动利用搜索获取历史上下文
+
+**非目标：**
+- 不搜索代码库本身（只搜 archive 里的 markdown）
+- 不做跨项目搜索
+- 不自建 embedding/向量搜索（复用 qmd）
+- 不强制所有平台都能用搜索（native binding 编译失败时降级）
+
+## 决策
+
+### 决策 1：qmd 作为 dependency 而非 optional/peer
+
+qmd 放在 `@marchen-spec/core` 的 `dependencies` 中，`npm install` 时一起安装。
+
+**理由**：用户不需要额外安装步骤。native binding 编译失败的情况通过 dynamic import + try/catch 处理，不影响其他功能。
+
+**替代方案**：optionalDependencies 或 peerDependencies——需要用户手动安装，体验差。
+
+### 决策 2：SearchManager 放在 core 包
+
+SearchManager 作为 core 包的新类，和 Workspace/ChangeManager 同级。不新建 `@marchen-spec/search` 包。
+
+**理由**：搜索是 archive 的延伸能力，属于核心业务逻辑。新建包会增加 monorepo 复杂度，且 SearchManager 需要访问 Workspace 的路径信息。
+
+### 决策 3：SQLite 数据库存放在 `marchen/.search/`
+
+qmd 的 index.sqlite 存放在 `marchen/.search/index.sqlite`，加入 `.gitignore`。
+
+**理由**：索引是本地生成的衍生数据，不应提交到 git。放在 `marchen/` 下而非全局目录，保持项目自包含。
+
+### 决策 4：tsdown external 处理 native 依赖
+
+CLI 的 tsdown 构建配置中，将 `@tobilu/qmd` 和 `node-llama-cpp` 标记为 external。
+
+**理由**：native binding（.node 文件）不能被 bundler 打包。external 后这些依赖在运行时从 node_modules 加载。
+
+### 决策 5：archive 索引失败静默处理
+
+`ChangeManager.archive()` 中的索引更新用 try/catch 包裹，失败时不抛出异常。
+
+**理由**：归档是核心操作，搜索索引是增强功能。索引失败不应阻断归档流程。用户可以通过 `marchen search --rebuild` 手动重建。
+
+### 决策 6：context 在 init 时自动配置
+
+`workspace.initialize()` 时自动为 qmd store 添加 context 描述，帮助搜索理解文档结构。
+
+**理由**：qmd 的 context 功能能显著提升搜索质量（在搜索结果中返回上下文描述）。用户不需要手动配置。
+
+## 风险与权衡
+
+### 风险 1：node-llama-cpp 编译失败
+
+node-llama-cpp 依赖 C++ 编译。某些系统（缺少编译工具链、不支持的 CPU 架构）可能编译失败。
+
+**缓解**：dynamic import + isAvailable() 检测。编译失败时搜索功能不可用，但 CLI 其他功能正常。
+
+### 风险 2：安装体积增大
+
+qmd + node-llama-cpp 会增加 npm install 的体积和时间。
+
+**缓解**：模型不在 install 时下载（懒加载），npm 包本身增加约 50-80MB（主要是 node-llama-cpp 的预编译 binary）。
+
+### 风险 3：首次搜索/归档延迟
+
+首次使用搜索功能时需要下载 embedding 模型（~300MB），首次混合搜索还需要 reranker（~640MB）和 query expansion（~1.1GB）。
+
+**缓解**：模型下载只发生一次，之后缓存在 `~/.cache/qmd/models/`。CLI 可以显示下载进度提示。
+
+### 风险 4：macOS 需要 Homebrew SQLite
+
+qmd 依赖 SQLite 扩展支持，macOS 系统自带的 SQLite 不够。
+
+**缓解**：在安装文档中说明 `brew install sqlite` 前置要求。

marchen/changes/integrate-qmd-search/proposal.md

@@ -0,0 +1,38 @@
+## 动机
+
+每次新对话开始，AI 对项目历史一无所知。archive 里有完整的设计决策、动机、规格，但 AI 无法高效检索。changelog.md 只有 30 行摘要，grep 只能做关键词匹配——用中文"异常处理"搜不到英文命名的 `error-handling` 变更。
+
+需要语义搜索能力，让 AI 在 explore/propose/apply 阶段能自动关联历史决策。
+
+## 变更内容
+
+集成 [qmd](https://github.com/tobi/qmd) 作为内置依赖，提供本地语义搜索能力：
+
+- 新增 `SearchManager` 类封装 qmd SDK，提供搜索和索引接口
+- `marchen archive` 时自动更新搜索索引
+- 新增 `marchen search` CLI 命令
+- 更新 explore skill 模板，在检查上下文阶段自动调用搜索
+- qmd 加载失败时优雅降级，不影响现有功能
+
+qmd 使用 BM25 + 向量搜索 + LLM rerank 三级流水线，模型首次使用时自动下载并缓存到 `~/.cache/qmd/models/`。
+
+## 能力
+
+### 新增能力
+
+- `search-manager`: SearchManager 类——封装 qmd SDK，提供 isAvailable/search/index/indexChange 接口，dynamic import + 优雅降级
+- `search-command`: marchen search CLI 命令——支持 --json/--limit/--min-score/--rebuild 选项
+- `archive-indexing`: archive 时自动索引——archive() 末尾调用 SearchManager 增量更新索引
+- `skill-search-integration`: skill 模板搜索集成——explore skill 在检查上下文阶段自动调用 marchen search
+
+### 修改能力
+
+（无）
+
+## 影响范围
+
+- `packages/core` — 新增 SearchManager 类，Workspace 加 searchDbPath，ChangeManager.archive() 加索引 hook
+- `apps/cli` — 新增 search 命令，tsdown external 配置
+- `packages/config` — explore skill 模板更新
+- 根目录 `.gitignore` — 加 `marchen/.search/`
+- 依赖 — core 和 cli 加 `@tobilu/qmd`

marchen/changes/integrate-qmd-search/specs/archive-indexing/spec.md

@@ -0,0 +1,38 @@
+## archive-indexing
+
+archive 操作完成后自动更新搜索索引，保持索引与 archive 内容同步。
+
+### 需求: archive() SHALL 在归档后更新搜索索引
+
+#### 场景: 正常更新索引
+
+- WHEN ChangeManager.archive() 成功完成文件移动和 changelog 写入
+- AND SearchManager.isAvailable() 返回 true
+- THEN 调用 SearchManager.indexChange() 更新索引
+- AND 归档结果正常返回
+
+#### 场景: 索引更新失败不影响归档
+
+- WHEN ChangeManager.archive() 成功完成文件移动和 changelog 写入
+- AND SearchManager.indexChange() 抛出异常
+- THEN 异常被捕获，不向上传播
+- AND 归档结果正常返回
+
+#### 场景: qmd 不可用时跳过索引
+
+- WHEN ChangeManager.archive() 执行
+- AND SearchManager.isAvailable() 返回 false
+- THEN 跳过索引更新
+- AND 归档流程正常完成
+
+### 需求: Workspace SHALL 提供搜索索引路径
+
+#### 场景: searchDbPath 指向 .search 目录
+
+- WHEN Workspace 实例化
+- THEN searchDbPath 为 `<specDir>/.search/index.sqlite`
+
+#### 场景: init 时创建 .search 目录
+
+- WHEN workspace.initialize() 执行
+- THEN 创建 `<specDir>/.search/` 目录

marchen/changes/integrate-qmd-search/specs/search-command/spec.md

@@ -0,0 +1,45 @@
+## search-command
+
+新增 `marchen search` CLI 命令，支持语义搜索归档变更历史。
+
+### 需求: CLI SHALL 注册 search 命令
+
+#### 场景: 基本搜索
+
+- WHEN 用户执行 `marchen search "异常处理"`
+- THEN 调用 SearchManager.search() 执行语义搜索
+- AND 在终端格式化输出结果（路径、分数、摘要片段）
+
+#### 场景: qmd 不可用时提示
+
+- WHEN 用户执行 `marchen search "query"`
+- AND SearchManager.isAvailable() 返回 false
+- THEN 输出错误提示"搜索功能不可用"
+- AND 退出码非零
+
+### 需求: search 命令 SHALL 支持 --json 输出
+
+#### 场景: JSON 格式输出
+
+- WHEN 用户执行 `marchen search "query" --json`
+- THEN 输出 JSON 数组，每项包含 path、score、snippet、title
+
+### 需求: search 命令 SHALL 支持结果过滤选项
+
+#### 场景: 限制结果数量
+
+- WHEN 用户执行 `marchen search "query" -n 10`
+- THEN 最多返回 10 条结果
+
+#### 场景: 最低分数过滤
+
+- WHEN 用户执行 `marchen search "query" --min-score 0.4`
+- THEN 只返回 score >= 0.4 的结果
+
+### 需求: search 命令 SHALL 支持索引重建
+
+#### 场景: 重建索引
+
+- WHEN 用户执行 `marchen search --rebuild "query"`
+- THEN 先调用 SearchManager.index() 全量重建索引
+- AND 然后执行搜索

marchen/changes/integrate-qmd-search/specs/search-manager/spec.md

@@ -0,0 +1,59 @@
+## search-manager
+
+SearchManager 类封装 qmd SDK，提供语义搜索和索引管理接口。通过 dynamic import 加载 qmd，加载失败时优雅降级。
+
+### 需求: SearchManager SHALL 通过 dynamic import 懒加载 qmd
+
+#### 场景: qmd 可用时正常初始化
+
+- WHEN SearchManager.isAvailable() 被调用
+- AND `@tobilu/qmd` 可以被 import
+- THEN 返回 `true`
+- AND 后续 search/index 调用正常工作
+
+#### 场景: qmd 不可用时优雅降级
+
+- WHEN SearchManager.isAvailable() 被调用
+- AND `@tobilu/qmd` import 失败（native binding 编译失败等）
+- THEN 返回 `false`
+- AND 不抛出异常
+
+### 需求: SearchManager SHALL 提供语义搜索接口
+
+#### 场景: 搜索返回结构化结果
+
+- WHEN search(query, options) 被调用
+- THEN 返回结果数组，每项包含 path、score、snippet、title
+- AND 结果按 score 降序排列
+- AND 默认返回 5 条，可通过 options.limit 调整
+- AND 可通过 options.minScore 过滤低分结果
+
+### 需求: SearchManager SHALL 懒初始化 qmd store
+
+#### 场景: store 在首次调用时创建
+
+- WHEN search() 或 index() 首次被调用
+- THEN 创建 qmd store，dbPath 为 workspace.searchDbPath
+- AND collection 指向 workspace.archiveDir，pattern 为 `**/*.md`
+- AND 后续调用复用同一个 store 实例
+
+### 需求: SearchManager SHALL 提供索引管理接口
+
+#### 场景: 全量索引
+
+- WHEN index() 被调用
+- THEN 扫描 archive 目录所有 .md 文件
+- AND 生成向量 embedding
+
+#### 场景: 增量索引
+
+- WHEN indexChange() 被调用
+- THEN 更新索引并为新文档生成 embedding
+
+### 需求: SearchManager SHALL 提供资源释放接口
+
+#### 场景: 关闭 store
+
+- WHEN close() 被调用
+- THEN 释放 qmd store 资源
+- AND 后续调用需要重新初始化