feat: implement semantic search functionality and enhance model management in CLI

Author: suemor233

README.en.md

@@ -78,8 +78,37 @@ marchen status <name> [--json]            # View artifact status and workflow su
 marchen instructions <name> <artifact>    # Get artifact creation instructions (JSON)
 marchen archive <name> [--summary <text>] # Archive change and write to changelog
 marchen update                            # Update skill/command files to latest version
+marchen search <query> [--rebuild]        # Search archived change history
 ```
 
+## Semantic Search
+
+MarchenSpec includes local-model-based semantic search for retrieving relevant design decisions and change records from your archive history.
+
+```bash
+marchen search "user auth"                # Semantic search across archives
+marchen search "refactor" -n 10           # Specify result count
+marchen search "auth" --min-score 0.5     # Set minimum score threshold
+marchen search "auth" --rebuild           # Rebuild index before searching
+```
+
+Required models (~2GB) are downloaded automatically on first use. If models are not installed, it falls back to BM25 keyword search.
+
+Semantic search requires SQLite:
+
+```bash
+# macOS
+brew install sqlite
+
+# Debian/Ubuntu
+sudo apt install sqlite3 libsqlite3-dev
+
+# RHEL/Fedora
+sudo dnf install sqlite sqlite-devel
+```
+
+The explore and apply skills also leverage search to automatically retrieve relevant history as context during workflows.
+
 ## Updating
 
 After upgrading marchen-spec, run update to sync skill files:

README.md

@@ -78,8 +78,37 @@ marchen status <name> [--json]            # 查看 artifact 状态和工作流
 marchen instructions <name> <artifact>    # 获取 artifact 创建指令（JSON）
 marchen archive <name> [--summary <text>] # 归档变更并写入 changelog
 marchen update                            # 更新 skill/command 文件到最新版本
+marchen search <query> [--rebuild]        # 搜索归档变更历史
 ```
 
+## 语义搜索
+
+MarchenSpec 内置基于本地模型的语义搜索，可以从归档历史中检索相关的设计决策和变更记录。
+
+```bash
+marchen search "用户认证"              # 语义搜索归档历史
+marchen search "重构" -n 10            # 指定结果数量
+marchen search "认证" --min-score 0.5  # 设置最低分数阈值
+marchen search "认证" --rebuild        # 重建索引后搜索
+```
+
+首次使用时会自动下载所需模型（约 2GB）。如果模型未安装，自动降级为 BM25 关键词搜索。
+
+语义搜索依赖 SQLite：
+
+```bash
+# macOS
+brew install sqlite
+
+# Debian/Ubuntu
+sudo apt install sqlite3 libsqlite3-dev
+
+# RHEL/Fedora
+sudo dnf install sqlite sqlite-devel
+```
+
+explore 和 apply skill 也会利用搜索能力，在工作流中自动检索相关历史作为上下文。
+
 ## 更新
 
 升级 marchen-spec 后，运行 update 同步 skill 文件：

apps/cli/src/commands/init.ts

@@ -2,7 +2,7 @@ import type { ModelDownloadProgress } from '@marchen-spec/core'
 import type { Command } from 'commander'
 import * as p from '@clack/prompts'
 import { AGENT_PROVIDERS } from '@marchen-spec/config'
-import { ModelManager } from '@marchen-spec/core'
+import { ModelManager, SearchManager } from '@marchen-spec/core'
 import { createContext } from '../utils/context.js'
 
 /** 模型类型显示名称 */
@@ -99,31 +99,41 @@ export function registerInitCommand(program: Command): void {
         .join(', ')
       p.log.success(`已为 ${names} 生成 skills 文件`)
 
-      // 询问是否下载搜索模型
-      const modelManager = new ModelManager()
-      const hasModels = await modelManager.hasLocalModels()
+      // 检测搜索环境
+      const search = new SearchManager(workspace)
+      const qmdAvailable = await search.isAvailable()
 
-      if (hasModels) {
-        p.log.info('语义搜索已就绪')
+      if (!qmdAvailable) {
+        p.log.warn(
+          '语义搜索不可用（缺少 SQLite 依赖），使用基础关键词搜索',
+        )
+        p.log.info('安装 SQLite 后可通过 marchen search 启用语义搜索')
       } else {
-        const downloadModels = await p.confirm({
-          message: '是否启用语义搜索？（需要下载约 2GB 模型）',
-          initialValue: false,
-        })
+        const modelManager = new ModelManager()
+        const hasModels = await modelManager.hasLocalModels()
 
-        if (!p.isCancel(downloadModels) && downloadModels) {
-          const spinner = p.spinner()
-          spinner.start('下载搜索模型...')
-          await modelManager.ensureModels({
-            onProgress: (prog) => {
-              spinner.message(formatModelProgress(prog))
-            },
-          })
-          spinner.stop('语义搜索已启用')
+        if (hasModels) {
+          p.log.info('语义搜索已就绪')
         } else {
-          p.log.info(
-            '使用基础关键词搜索，后续可通过 marchen search --rebuild 启用语义搜索',
-          )
+          const downloadModels = await p.confirm({
+            message: '是否启用语义搜索？（需要下载约 2GB 模型）',
+            initialValue: false,
+          })
+
+          if (!p.isCancel(downloadModels) && downloadModels) {
+            const spinner = p.spinner()
+            spinner.start('下载搜索模型...')
+            await modelManager.ensureModels({
+              onProgress: (prog) => {
+                spinner.message(formatModelProgress(prog))
+              },
+            })
+            spinner.stop('语义搜索已启用')
+          } else {
+            p.log.info(
+              '使用基础关键词搜索，后续可通过 marchen search --rebuild 启用语义搜索',
+            )
+          }
         }
       }
 

apps/cli/src/commands/search.ts

@@ -79,6 +79,7 @@ export function registerSearchCommand(program: Command): void {
             onModelProgress: (prog) => {
               spinner?.message(formatModelProgress(prog))
             },
+            downloadIfMissing: false,
           })
           spinner?.stop('搜索引擎就绪')
 

marchen/archive/2026-04-29-fix-search-model-download/.metadata.yaml

@@ -0,0 +1,5 @@
+name: fix-search-model-download
+schema: lite
+createdAt: '2026-04-29T09:06:58.929Z'
+status: archived
+archivedAt: '2026-04-29T09:16:44.742Z'

marchen/archive/2026-04-29-fix-search-model-download/tasks.md

@@ -0,0 +1,15 @@
+## 背景
+
+`marchen search` 命令始终向 `SearchManager.prepare()` 传递 `onModelProgress` 回调，导致即使用户没有安装本地模型也会触发模型下载。`prepare()` 的设计意图是"有回调 = 要下载"，但 CLI 只是想展示进度，不一定要下载。
+
+方案：给 `PrepareOptions` 增加 `downloadIfMissing` 选项（默认 false），解耦"展示进度"和"触发下载"两个语义。CLI search 命令默认不下载，只有显式场景才触发下载。
+
+## 1. core 层：扩展 PrepareOptions
+
+- [x] 1.1 `PrepareOptions` 增加 `downloadIfMissing?: boolean` 字段
+- [x] 1.2 重写 `prepare()` 分支逻辑：downloadIfMissing=true 时下载，否则仅本地有模型才加载
+
+## 2. CLI 层：适配调用方
+
+- [x] 2.1 search 命令传 `downloadIfMissing: false`
+- [x] 2.2 确认其他调用点（如 archive 中的 indexChange）无需改动

marchen/changelog.md

@@ -32,3 +32,4 @@
 - 2026-04-24: [integrate-qmd-search](./archive/2026-04-24-integrate-qmd-search/) — 集成 qmd 语义搜索，新增 SearchManager 和 marchen search 命令，archive 时自动索引
 - 2026-04-26: [add-qmd-model-source](./archive/2026-04-26-add-qmd-model-source/) — 支持从自定义CDN下载qmd模型，新增ModelManager管理模型生命周期，SearchManager分离prepare阶段并展示下载进度
 - 2026-04-26: [integrate-search-skills](./archive/2026-04-26-integrate-search-skills/) — 搜索自动降级BM25关键词模式，init增加模型下载选项，explore和apply模板集成语义搜索
+- 2026-04-29: [fix-search-model-download](./archive/2026-04-29-fix-search-model-download/) — search命令增加downloadIfMissing选项，无本地模型时不触发下载，自动降级BM25搜索

marchen/changes/fix-init-search-check/.metadata.yaml

@@ -0,0 +1,4 @@
+name: fix-init-search-check
+schema: lite
+createdAt: '2026-04-29T09:38:25.753Z'
+status: open

marchen/changes/fix-init-search-check/tasks.md

@@ -0,0 +1,10 @@
+## 背景
+
+`marchen init` 的模型下载询问没有先检测 qmd SDK 是否可用。如果用户没装 SQLite 依赖，qmd import 会失败，但 init 仍然会询问是否下载 2GB 模型——下了也用不了。
+
+方案：在询问模型下载前，先用 `SearchManager.isAvailable()` 检测 qmd 能否加载。不可用时直接提示缺少依赖，跳过模型下载询问。
+
+## 1. init 命令增加 qmd 可用性检测
+
+- [x] 1.1 在模型下载逻辑前，用 `SearchManager.isAvailable()` 检测 qmd SDK
+- [x] 1.2 qmd 不可用时提示缺少依赖并跳过模型下载询问，可用时保持现有流程

packages/core/src/search-manager.ts

@@ -27,6 +27,8 @@ export interface SearchOptions {
 export interface PrepareOptions {
   /** 模型下载进度回调 */
   readonly onModelProgress?: (progress: ModelDownloadProgress) => void
+  /** 本地无模型时是否触发下载，默认 false（降级为 BM25） */
+  readonly downloadIfMissing?: boolean
 }
 
 /**
@@ -67,14 +69,14 @@ export class SearchManager {
     const { ModelManager } = await import('./model-manager.js')
     const modelManager = new ModelManager()
 
-    if (options?.onModelProgress) {
-      const paths = await modelManager.ensureModels({
-        onProgress: options.onModelProgress,
-      })
-      modelManager.applyEnv(paths)
-      this.modelsReady = true
-    } else if (await modelManager.hasLocalModels()) {
-      const paths = await modelManager.ensureModels()
+    const shouldLoad =
+      options?.downloadIfMissing || (await modelManager.hasLocalModels())
+
+    if (shouldLoad) {
+      const ensureOpts = options?.onModelProgress
+        ? { onProgress: options.onModelProgress }
+        : undefined
+      const paths = await modelManager.ensureModels(ensureOpts)
       modelManager.applyEnv(paths)
       this.modelsReady = true
     }