@mcptoolshop/claude-synergy 1.0.1 → 1.1.0

package/README.md

@@ -65,7 +65,7 @@ claude-synergy/
 │   └── plugins-{official,community,knowledge-work}/  # Plugin marketplaces
 ├── synergies/               # 12 curated cross-product workflows
 ├── src/                     # TypeScript implementation
-├── test/                    # 382 tests (unit, integration, regression, smoke)
+├── test/                    # 508 tests (unit, integration, regression, smoke)
 ├── data/claude-synergy.db   # SQLite database (created by `hk init`)
 ├── schema.sql               # Tier 2a tables (products, releases, changes, entities, FTS5, …)
 ├── schema-vec.sql           # Tier 2b tables (chunks, chunks_vec, chunks_fts)
@@ -73,7 +73,7 @@ claude-synergy/
 └── URGENT_FINDINGS.md       # 23 actionable items surfaced from the corpus
 ```
 
-**Live numbers (as of v1.0.0):** 44 products / 1,186 release files / 6,042 changes / 1,225 entities / 12 synergies / 382 tests.
+**Live numbers (as of v1.1.0):** 44 products / 1,186 release files / 6,042 changes / 1,225 entities / 12 synergies / 508 tests / 11 MCP tools / 17 CLI commands.
 
 ---
 
@@ -84,13 +84,14 @@ claude-synergy/
 | **1 — bootstrap (markdown corpus)** | ✅ shipped | Study-swarm seeded 706 release files Jan→May 2026; extended to 1,186 by Tier 4d |
 | **2a — SQLite + FTS5 + CLI** | ✅ shipped | `hk` CLI; 15 subcommands; sub-300ms ingest |
 | **2b — sqlite-vec + Contextual Retrieval** | ✅ shipped | Provider-pluggable (none/structured/ollama/claude-haiku context × ollama/voyage embed × none/ollama-judge/voyage/cohere rerank) |
-| **3 — sync + MCP server** | ✅ shipped | `hk fetch / sync / seed-markers`; `claude-synergy-mcp` exposes 8 tools over stdio |
+| **3 — sync + MCP server** | ✅ shipped | `hk fetch / sync / seed-markers`; `claude-synergy-mcp` exposes 11 tools over stdio (8 at original Tier-3 ship, 3 added in v1.1) |
 | **4a — extend beyond Anthropic** | ✅ shipped | +15 MCP SDKs, Cursor (RSS), Aider (HISTORY.md), Continue.dev, Cody Enterprise (RSS filtered) |
 | **4b — HTML-scrape fetcher** | ✅ shipped | GitHub Copilot + VS Code Chat (Windsurf needs Playwright — v0.7) |
 | **4c — turndown HTML→markdown ingest** | ✅ shipped | HTML bodies (Copilot/VS Code/Cursor) now produce per-bullet rows for FTS5 + entity extraction |
 | **4d — Playwright + MCP registry + YAML config** | ✅ shipped | Windsurf via Playwright; Smithery + official MCP Registry as Tier-4 catalogs; products consolidated into `products.yaml` |
+| **5 — v1.1 windowed browsing + OpenAI embed** | ✅ shipped | `hk diff` / `hk breaking`, date bounds across all browsing commands, 3 new MCP tools (11 total), OpenAI embedding provider, configurable embedding dimension, `claude-code` auto-sync, generic `keep-a-changelog` parser |
 
-Roadmap for v0.8+: tracked in [URGENT_FINDINGS.md](URGENT_FINDINGS.md) and issues.
+Roadmap beyond v1.1: tracked in [URGENT_FINDINGS.md](URGENT_FINDINGS.md) and issues.
 
 ---
 
@@ -114,7 +115,7 @@ For dev without building, use `npx tsx src/cli.ts ...` directly. **pnpm 10 quirk
 
 ---
 
-## CLI surface — 15 commands
+## CLI surface — 17 commands
 
 ```
 # DB lifecycle
@@ -126,8 +127,12 @@ hk sync                              # combined fetch → ingest → embed (cron
 hk seed-markers                      # one-time setup after initial corpus
 
 # Search
-hk query "managed agents"            # FTS5 keyword search
-hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ optional --rerank)
+hk query "managed agents"            # FTS5 keyword search (+ --until <date>)
+hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ --rerank, --until)
+
+# Windowed change browsing
+hk diff [product] --since 7d         # what changed in a window, grouped by product+version
+hk breaking --since 30d              # filter-browse of breaking changes (no search term)
 
 # Entity lookups
 hk env-var CLAUDE_CODE_WORKFLOWS     # when introduced + history
@@ -136,7 +141,7 @@ hk model claude-opus-4-7             # model launch + mentions across products
 hk cve CVE-2025-66414                # CVE references in corpus
 
 # Browsing
-hk latest [--product X] [--limit N]  # recent releases
+hk latest [--product X] [--limit N]  # recent releases (+ --since <date>)
 hk products                          # list all 44 with counts
 hk top env_var                       # most-mentioned by entity type
                                      # (env_var, slash_command, cli_option,
@@ -144,6 +149,8 @@ hk top env_var                       # most-mentioned by entity type
                                      #  hook_event, setting_key)
 ```
 
+**New in v1.1:** `hk diff` and `hk breaking` answer "what changed lately?" without needing a search term. Date bounds are uniform: every browsing command takes `--since` and `--until` in `YYYY-MM-DD` (or full ISO 8601), or a relative form (`7d`, `2w`, `3m`, `1y`).
+
 ---
 
 ## Example workflows
@@ -186,11 +193,35 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 The query never says "env_scrub" — vec surfaces it by semantic similarity. Pure FTS5 misses it entirely.
 
+**What changed in claude-code this week:**
+```
+$ hk diff claude-code --since 7d
+claude-code@2.1.147  2026-05-21  (3 changes)
+  [added]     Added the `Workflow` tool for deterministic multi-agent orchestration.
+  [changed]   Slash commands now lazy-load until first invocation.
+  [fixed]     Race condition in MCP server discovery on Windows.
+
+claude-code@2.1.146  2026-05-19  (1 change)
+  [fixed]     Restored `--debug` flag accidentally removed in 2.1.144.
+```
+
+**Browse breaking changes across the corpus:**
+```
+$ hk breaking --since 30d --limit 5
+2026-05-15  claude-agent-sdk-python@0.2.82       Headless and SDK sessions now use Task tools by default.
+2026-05-14  claude-agent-sdk-typescript@0.3.142  Headless and SDK sessions now use Task tools by default.
+2026-05-08  anthropic-sdk-go@1.42.0              Removed deprecated `client.Beta()` namespace.
+2026-04-29  cursor@0.49.0                        MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
+2026-04-22  windsurf@1.10.0                      Removed `cascade.run` JSON-RPC method.
+```
+
+No search term needed — `hk breaking` is the answer to "did anything load-bearing change recently?"
+
 ---
 
 ## MCP server — give your agents access to this corpus
 
-`claude-synergy-mcp` exposes 8 tools over stdio. Wire into Claude Code (or any MCP host) via `~/.claude/.mcp.json` or your project's `.mcp.json`:
+`claude-synergy-mcp` exposes 11 tools over stdio. Wire into Claude Code (or any MCP host) via `~/.claude/.mcp.json` or your project's `.mcp.json`:
 
 ```json
 {
@@ -211,28 +242,33 @@ Tools exposed:
 
 | Tool | Purpose |
 |---|---|
-| `search` | Hybrid FTS5 + vec; optional rerank. Default mode for natural-language queries. |
+| `search` | Hybrid FTS5 + vec; optional rerank. Default mode for natural-language queries. (+ `until` date upper bound) |
 | `lookup_entity` | Exact entity history: env vars, slash commands, model IDs, CVEs, etc. |
-| `latest_releases` | Recent releases across products (or one) |
+| `latest_releases` | Recent releases across products (or one). (+ `since` date lower bound) |
 | `get_release` | Full content of one release |
 | `list_products` | Enumeration with counts + latest version |
 | `top_entities` | Most-mentioned entities by type |
-| `list_synergies` | Curated cross-product workflows |
+| `list_synergies` | Curated cross-product workflows. (+ optional `product` filter) |
 | `read_synergy` | Full text of one synergy file |
+| `get_changes_since` | **New.** Changes in a time window, grouped by product+version. Inputs: `since` (required), `until?`, `product?`, `kind?`, `limit?`. |
+| `search_breaking_changes` | **New.** Flat list of breaking changes — no search term needed. Inputs: `product?`, `since?`, `until?`, `limit?`. |
+| `compare_versions` | **New.** All changes between two versions of one product. Inputs: `product`, `from_version`, `to_version`. |
+
+The three new tools mirror `hk diff` / `hk breaking` and the version-comparison workflow that previously required scripting. See [handbook → MCP server](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/mcp-server/) for full input schemas.
 
 ---
 
-## Sources — 5 tiers, 6 fetcher strategies
+## Sources — 5 tiers, 7 fetcher strategies
 
 Full landscape in [SOURCES.md](SOURCES.md).
 
-- **Tier 1 (GitHub Releases)** — `gh api repos/<owner>/<repo>/releases` for 22 products including Anthropic SDKs (7 languages), Agent SDKs (2), ant CLI, claude-code-action, claude-code-security-review, and 15 MCP ecosystem SDKs
-- **Tier 2 (raw markdown)** — `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
+- **Tier 1 (GitHub Releases)** — `gh api repos/<owner>/<repo>/releases` for 23 products including Anthropic SDKs (7 languages), Agent SDKs (2), ant CLI, **claude-code** (now auto-synced via gh-releases as of v1.1 — previously manually seeded), claude-code-action, claude-code-security-review, and 15 MCP ecosystem SDKs
+- **Tier 2 (raw markdown)** — `Aider-AI/aider/HISTORY.md`. The generic `keep-a-changelog` parser (v1.1+) is also available for any product whose source is a CHANGELOG.md in Keep-a-Changelog format — configure via one entry in `products.yaml`.
 - **Tier 3 (HTML / RSS)** — `platform.claude.com/docs/release-notes`, `support.claude.com/articles/12138966`, `cursor.com/changelog/rss.xml`, `sourcegraph.com/changelog/featured.rss` (filtered), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`
 - **Tier 4 (catalog)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`
 - **Tier 5 (advisory)** — `@ClaudeCodeLog` X account; marckrenn changelog mirror
 
-Fetch strategies: `gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`. New product = one entry in `products.yaml`.
+Fetch strategies: `gh-releases | rss | raw-changelog | keep-a-changelog | html-scrape | catalog | playwright`. New product = one entry in `products.yaml`.
 
 ---
 
@@ -255,7 +291,7 @@ Full index in [synergies/INDEX.md](synergies/INDEX.md).
 Vitest suite covers unit / integration / regression / smoke tiers. **[test-spec-3.md](test-spec-3.md) is the current authority** as of v0.7.0; [test-spec.md](test-spec.md) (v1) and [test-spec-2.md](test-spec-2.md) (v2) remain in the repo as historical record of the design lineage.
 
 ```bash
-pnpm test               # unit + integration + regression (~16s, 382 tests)
+pnpm test               # unit + integration + regression (~18s, 508 tests)
 pnpm test:watch         # interactive
 pnpm test:coverage      # generate coverage/index.html (thresholds: 78/75/85/78)
 pnpm test:smoke         # opt-in full-corpus smoke (RUN_SMOKE=1)
@@ -265,9 +301,9 @@ Layout:
 
 | Dir | What it covers |
 |-----|----------------|
-| `test/unit/` | per-module — extract, ingest, query, db, embed, hybrid, fetch + every provider + fetch-rss/changelog/html + fetch-mcp-registry + fetch-playwright + products-config |
-| `test/integration/` | end-to-end — pipeline, sync, MCP server (stdio JSON-RPC), CLI |
-| `test/regression/` | §8.1–§8.18 — each protects against a real bug fixed during development |
+| `test/unit/` | per-module — extract, ingest, query (incl. `until` / browse / since / compare), db (incl. dim-config v3 migration), embed, hybrid, fetch + every provider (Ollama / Voyage / **OpenAI**) + fetch-rss/changelog (incl. **keep-a-changelog** parser)/html + fetch-mcp-registry + fetch-playwright + products-config + synergy ingest/query |
+| `test/integration/` | end-to-end — pipeline, sync, MCP server (stdio JSON-RPC, 11 tools), CLI (incl. `hk diff`, `hk breaking`) |
+| `test/regression/` | §8.1–§8.19 — each protects against a real bug fixed during development (§8.19: ghReleases early-exit pagination preserves in-window items) |
 | `test/smoke/` | opt-in full-corpus against real `products/` (1,143 files) |
 | `test/fixtures/` | 3 fake products + mock HTTP responses (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / Official MCP Registry) |
 | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -308,8 +344,22 @@ Sync is idempotent — safe to re-run after a partial failure. Already-fetched r
 
 `hk embed` calls an external embedding service:
 
-- **Ollama (default)** — ensure Ollama is running (`ollama serve`) and the embedding model is pulled (`ollama pull nomic-embed-text`).
-- **Voyage** — set `VOYAGE_API_KEY` in your environment. Check your API key at [dash.voyageai.com](https://dash.voyageai.com).
+- **Ollama (default, 768-dim)** — ensure Ollama is running (`ollama serve`) and the embedding model is pulled (`ollama pull nomic-embed-text`).
+- **Voyage (1024-dim)** — set `VOYAGE_API_KEY` in your environment. Check your API key at [dash.voyageai.com](https://dash.voyageai.com).
+- **OpenAI (1536-dim default, configurable)** — set `OPENAI_API_KEY`. Default model is `text-embedding-3-small`; override with `OPENAI_EMBED_MODEL` (e.g. `text-embedding-3-large` for 3072-dim). Use via `hk hybrid --embed openai` or `hk embed --embed openai`.
+
+**Embedding dimension mismatch on provider switch**
+
+Each provider produces vectors of a fixed dimension (Ollama 768, Voyage 1024, OpenAI 1536 by default — OpenAI supports configurable dim within the model's native size). The DB stores the active dimension in `schema_meta.embedding_dim`. Switching providers across different dimensions while chunks exist raises `EMBEDDING_DIM_MISMATCH` (`AppError`) rather than silently corrupting the vector table. To switch:
+
+```bash
+rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+hk init
+hk ingest
+hk embed --embed openai     # new provider, new dim, fresh chunks_vec
+```
+
+For OpenAI Matryoshka truncation (smaller-than-native dim), set `OPENAI_EMBED_MODEL` and pass the desired dim through `hk embed`'s provider construction — see the [handbook embedding section](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/cli-reference/#embedding-providers-and-dimensions) for details.
 
 **Schema version mismatch / corrupted database**
 

package/README.pt-BR.md

@@ -65,7 +65,7 @@ claude-synergy/
 │   └── plugins-{official,community,knowledge-work}/  # Plugin marketplaces
 ├── synergies/               # 12 curated cross-product workflows
 ├── src/                     # TypeScript implementation
-├── test/                    # 382 tests (unit, integration, regression, smoke)
+├── test/                    # 508 tests (unit, integration, regression, smoke)
 ├── data/claude-synergy.db   # SQLite database (created by `hk init`)
 ├── schema.sql               # Tier 2a tables (products, releases, changes, entities, FTS5, …)
 ├── schema-vec.sql           # Tier 2b tables (chunks, chunks_vec, chunks_fts)
@@ -73,7 +73,7 @@ claude-synergy/
 └── URGENT_FINDINGS.md       # 23 actionable items surfaced from the corpus
 ```
 
-**Números atualizados (a partir da versão 1.0.0):** 44 produtos / 1.186 arquivos de lançamento / 6.042 alterações / 1.225 entidades / 12 sinergias / 382 testes.
+**Números atuais (versão v1.1.0):** 44 produtos / 1.186 arquivos de lançamento / 6.042 alterações / 1.225 entidades / 12 sinergias / 508 testes / 11 ferramentas MCP / 17 comandos de linha de comando.
 
 ---
 
@@ -84,11 +84,12 @@ claude-synergy/
 | **1 — corpus em Markdown (base)** | ✅ implementado | O "Study-swarm" indexou 706 arquivos de lançamento de janeiro a maio de 2026; expandido para 1.186 na etapa 4. |
 | **2a — SQLite + FTS5 + CLI** | ✅ implementado | CLI `hk`; 15 subcomandos; ingestão em menos de 300ms. |
 | **2b — sqlite-vec + Recuperação Contextual** | ✅ implementado | Fornecedor plugável (nenhum/estruturado/ollama/claude-haiku contexto × ollama/voyage embed × nenhum/ollama-judge/voyage/cohere rerank). |
-| **3 — sincronização + servidor MCP** | ✅ implementado | `hk fetch / sync / seed-markers`; o `claude-synergy-mcp` expõe 8 ferramentas via stdio. |
+| **3 — sincronização + servidor MCP** | ✅ implementado | `hk fetch / sync / seed-markers`; `claude-synergy-mcp` expõe 11 ferramentas via stdio (8 na versão original Tier-3, 3 adicionadas na v1.1). |
 | **4a — expansão para além do Anthropic** | ✅ implementado | +15 SDKs MCP, Cursor (RSS), Aider (HISTORY.md), Continue.dev, Cody Enterprise (RSS filtrado). |
 | **4b — coletor de HTML** | ✅ implementado | GitHub Copilot + VS Code Chat (Windsurf precisa do Playwright — v0.7). |
 | **4c — ingestão de HTML para Markdown (turndown)** | ✅ implementado | Corpos de HTML (Copilot/VS Code/Cursor) agora geram linhas individuais para o FTS5 e extração de entidades. |
 | **4d — Playwright + registro MCP + configuração YAML** | ✅ implementado | Windsurf via Playwright; Smithery + registro oficial MCP como catálogos da etapa 4; produtos consolidados em `products.yaml`. |
+| **5 — Navegação com janelas (v1.1) + incorporação da OpenAI** | ✅ implementado | `hk diff` / `hk breaking`, limites de data em todos os comandos de navegação, 3 novas ferramentas MCP (total de 11), provedor de incorporação da OpenAI, dimensão de incorporação configurável, sincronização automática do `claude-code`, analisador genérico `keep-a-changelog`. |
 
 Roteiro para a versão 0.8+: acompanhado em [URGENT_FINDINGS.md](URGENT_FINDINGS.md) e nas issues.
 
@@ -126,8 +127,12 @@ hk sync                              # combined fetch → ingest → embed (cron
 hk seed-markers                      # one-time setup after initial corpus
 
 # Search
-hk query "managed agents"            # FTS5 keyword search
-hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ optional --rerank)
+hk query "managed agents"            # FTS5 keyword search (+ --until <date>)
+hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ --rerank, --until)
+
+# Windowed change browsing
+hk diff [product] --since 7d         # what changed in a window, grouped by product+version
+hk breaking --since 30d              # filter-browse of breaking changes (no search term)
 
 # Entity lookups
 hk env-var CLAUDE_CODE_WORKFLOWS     # when introduced + history
@@ -136,7 +141,7 @@ hk model claude-opus-4-7             # model launch + mentions across products
 hk cve CVE-2025-66414                # CVE references in corpus
 
 # Browsing
-hk latest [--product X] [--limit N]  # recent releases
+hk latest [--product X] [--limit N]  # recent releases (+ --since <date>)
 hk products                          # list all 44 with counts
 hk top env_var                       # most-mentioned by entity type
                                      # (env_var, slash_command, cli_option,
@@ -144,6 +149,8 @@ hk top env_var                       # most-mentioned by entity type
                                      #  hook_event, setting_key)
 ```
 
+**Novidades na v1.1:** `hk diff` e `hk breaking` respondem a "o que mudou recentemente?" sem a necessidade de um termo de pesquisa. Os limites de data são uniformes: todos os comandos de navegação aceitam `--since` e `--until` em formato `AAAA-MM-DD` (ou ISO 8601 completo), ou em formato relativo (`7d`, `2w`, `3m`, `1y`).
+
 ---
 
 ## Exemplos de fluxos de trabalho
@@ -186,6 +193,30 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 A consulta nunca menciona "env_scrub" — o sistema o identifica por similaridade semântica. O sistema de busca tradicional (FTS5) não o encontra.
 
+**O que mudou no claude-code esta semana:**
+```
+$ hk diff claude-code --since 7d
+claude-code@2.1.147  2026-05-21  (3 changes)
+  [added]     Added the `Workflow` tool for deterministic multi-agent orchestration.
+  [changed]   Slash commands now lazy-load until first invocation.
+  [fixed]     Race condition in MCP server discovery on Windows.
+
+claude-code@2.1.146  2026-05-19  (1 change)
+  [fixed]     Restored `--debug` flag accidentally removed in 2.1.144.
+```
+
+**Navegue pelas alterações significativas em todo o conjunto de dados:**
+```
+$ hk breaking --since 30d --limit 5
+2026-05-15  claude-agent-sdk-python@0.2.82       Headless and SDK sessions now use Task tools by default.
+2026-05-14  claude-agent-sdk-typescript@0.3.142  Headless and SDK sessions now use Task tools by default.
+2026-05-08  anthropic-sdk-go@1.42.0              Removed deprecated `client.Beta()` namespace.
+2026-04-29  cursor@0.49.0                        MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
+2026-04-22  windsurf@1.10.0                      Removed `cascade.run` JSON-RPC method.
+```
+
+Não é necessário um termo de pesquisa — `hk breaking` é a resposta para "alguma alteração importante ocorreu recentemente?".
+
 ---
 
 ## Servidor MCP — forneça acesso a este corpus para seus agentes
@@ -211,14 +242,19 @@ Ferramentas disponíveis:
 
 | Ferramenta | Propósito |
 |---|---|
-| `search` | FTS5 + busca vetorial; reclassificação opcional. Modo padrão para consultas em linguagem natural. |
+| `search` | FTS5 + vet híbrido; reclassificação opcional. Modo padrão para consultas em linguagem natural. (+ limite superior de data `until`) |
 | `lookup_entity` | Histórico completo de entidades: variáveis de ambiente, comandos, IDs de modelos, CVEs, etc. |
-| `latest_releases` | Lançamentos recentes em todos os produtos (ou em um). |
+| `latest_releases` | Lançamentos recentes em todos os produtos (ou em um). (+ limite inferior de data `since`) |
 | `get_release` | Conteúdo completo de um lançamento. |
 | `list_products` | Enumeração com contagens + versão mais recente. |
 | `top_entities` | Entidades mais mencionadas por tipo. |
-| `list_synergies` | Fluxos de trabalho entre produtos, selecionados. |
+| `list_synergies` | Fluxos de trabalho entre produtos. (+ filtro de produto opcional) |
 | `read_synergy` | Texto completo de um arquivo de sinergia. |
+| `get_changes_since` | **Novo.** Alterações em uma janela de tempo, agrupadas por produto+versão. Entradas: `since` (obrigatório), `until?`, `product?`, `kind?`, `limit?`. |
+| `search_breaking_changes` | **Novo.** Lista simples de alterações significativas — não é necessário um termo de pesquisa. Entradas: `product?`, `since?`, `until?`, `limit?`. |
+| `compare_versions` | **Novo.** Todas as alterações entre duas versões de um produto. Entradas: `product`, `from_version`, `to_version`. |
+
+As três novas ferramentas espelham `hk diff` / `hk breaking` e o fluxo de trabalho de comparação de versões que anteriormente exigia scripts. Consulte [manual → servidor MCP](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/mcp-server/) para obter os esquemas de entrada completos.
 
 ---
 
@@ -226,11 +262,11 @@ Ferramentas disponíveis:
 
 Visão geral completa em [SOURCES.md](SOURCES.md).
 
-- **Nível 1 (Lançamentos do GitHub)** — `gh api repos/<owner>/<repo>/releases` para 22 produtos, incluindo SDKs da Anthropic (7 linguagens), SDKs de Agentes (2), ant CLI, claude-code-action, claude-code-security-review e 15 SDKs do ecossistema MCP.
-- **Nível 2 (markdown bruto)** — `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
-- **Nível 3 (HTML / RSS)** — `platform.claude.com/docs/release-notes`, `support.claude.com/articles/12138966`, `cursor.com/changelog/rss.xml`, `sourcegraph.com/changelog/featured.rss` (filtrado), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`
-- **Nível 4 (catálogo)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`
-- **Nível 5 (consultoria)** — Conta X `@ClaudeCodeLog`; espelho de changelog do marckrenn.
+- **Nível 1 (Lançamentos do GitHub)** — `gh api repos/<owner>/<repo>/releases` para 23 produtos, incluindo SDKs da Anthropic (7 linguagens), SDKs de Agentes (2), ant CLI, **claude-code** (agora sincronizado automaticamente via gh-releases a partir da v1.1 — anteriormente, a sincronização era manual), claude-code-action, claude-code-security-review e 15 SDKs do ecossistema MCP.
+- **Nível 2 (markdown bruto)** — `Aider-AI/aider/HISTORY.md`. O analisador genérico `keep-a-changelog` (v1.1+) também está disponível para qualquer produto cujo código-fonte seja um arquivo CHANGELOG.md no formato Keep-a-Changelog — configure-o através de uma entrada em `products.yaml`.
+- **Nível 3 (HTML / RSS)** — `platform.claude.com/docs/release-notes`, `support.claude.com/articles/12138966`, `cursor.com/changelog/rss.xml`, `sourcegraph.com/changelog/featured.rss` (filtrado), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`.
+- **Nível 4 (catálogo)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`.
+- **Nível 5 (aconselhamento)** — Conta X `@ClaudeCodeLog`; espelho de changelog de marckrenn.
 
 Estratégias de busca: `gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`. Novo produto = uma entrada em `products.yaml`.
 
@@ -255,7 +291,7 @@ Estratégias de busca: `gh-releases | rss | raw-changelog | html-scrape | catalo
 O conjunto de testes Vitest cobre os níveis de unidade / integração / regressão / teste rápido. **[test-spec-3.md](test-spec-3.md) é a documentação atual** a partir da versão v0.7.0; [test-spec.md](test-spec.md) (v1) e [test-spec-2.md](test-spec-2.md) (v2) permanecem no repositório como registro histórico da linhagem do design.
 
 ```bash
-pnpm test               # unit + integration + regression (~16s, 382 tests)
+pnpm test               # unit + integration + regression (~18s, 508 tests)
 pnpm test:watch         # interactive
 pnpm test:coverage      # generate coverage/index.html (thresholds: 78/75/85/78)
 pnpm test:smoke         # opt-in full-corpus smoke (RUN_SMOKE=1)
@@ -265,9 +301,9 @@ Estrutura:
 
 | Diretório | O que ele cobre |
 |-----|----------------|
-| `test/unit/` | por módulo — extração, ingestão, consulta, banco de dados, incorporação, busca híbrida, busca + todos os provedores + busca-rss/changelog/html + busca-mcp-registry + busca-playwright + configuração de produtos. |
-| `test/integration/` | teste de ponta a ponta — pipeline, sincronização, servidor MCP (stdio JSON-RPC), CLI. |
-| `test/regression/` | §8.1–§8.18 — cada um protege contra um erro real corrigido durante o desenvolvimento. |
+| `test/unit/` | por módulo — extração, ingestão, consulta (incl. `until` / navegação / desde / comparação), banco de dados (incl. migração da configuração de dimensão v3), incorporação, híbrido, busca + todos os provedores (Ollama / Voyage / **OpenAI**) + busca-rss/changelog (incl. analisador **keep-a-changelog**)/html + busca-mcp-registry + busca-playwright + configuração de produtos + ingestão/consulta de sinergia. |
+| `test/integration/` | de ponta a ponta — pipeline, sincronização, servidor MCP (JSON-RPC stdio, 11 ferramentas), CLI (incl. `hk diff`, `hk breaking`). |
+| `test/regression/` | §8.1–§8.19 — cada um protege contra um bug real corrigido durante o desenvolvimento (§8.19: ghReleases preserva os itens dentro da janela durante a paginação inicial). |
 | `test/smoke/` | Teste completo com um conjunto de dados simulado, representando os arquivos reais do diretório `products/` (1.143 arquivos). |
 | `test/fixtures/` | 3 produtos simulados + respostas HTTP simuladas (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / Registro oficial do MCP). |
 | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -308,8 +344,22 @@ A sincronização é idempotente — é seguro executá-la novamente após uma f
 
 `hk embed` chama um serviço de incorporação externo:
 
-- **Ollama (padrão)** — certifique-se de que o Ollama está em execução (`ollama serve`) e que o modelo de incorporação foi baixado (`ollama pull nomic-embed-text`).
-- **Voyage** — defina `VOYAGE_API_KEY` no seu ambiente. Verifique sua chave de API em [dash.voyageai.com](https://dash.voyageai.com).
+- **Ollama (padrão, 768 dimensões)** — certifique-se de que o Ollama está em execução (`ollama serve`) e que o modelo de incorporação foi baixado (`ollama pull nomic-embed-text`).
+- **Voyage (1024 dimensões)** — defina a variável de ambiente `VOYAGE_API_KEY`. Verifique sua chave de API em [dash.voyageai.com](https://dash.voyageai.com).
+- **OpenAI (1536 dimensões por padrão, configurável)** — defina a variável `OPENAI_API_KEY`. O modelo padrão é `text-embedding-3-small`; você pode alterá-lo usando a variável `OPENAI_EMBED_MODEL` (por exemplo, `text-embedding-3-large` para 3072 dimensões). Use-o através de `hk hybrid --embed openai` ou `hk embed --embed openai`.
+
+**Incompatibilidade de dimensões de incorporação ao alternar de provedor**
+
+Cada provedor produz vetores de uma dimensão fixa (Ollama 768, Voyage 1024, OpenAI 1536 por padrão — o OpenAI suporta dimensões configuráveis dentro do tamanho nativo do modelo). O banco de dados armazena a dimensão ativa em `schema_meta.embedding_dim`. A alteração de provedores entre dimensões diferentes, enquanto existem fragmentos, gera um erro `EMBEDDING_DIM_MISMATCH` (um erro da aplicação) em vez de corromper silenciosamente a tabela de vetores. Para alterar:
+
+```bash
+rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+hk init
+hk ingest
+hk embed --embed openai     # new provider, new dim, fresh chunks_vec
+```
+
+Para a truncagem Matryoshka do OpenAI (dimensão menor que a nativa), defina a variável `OPENAI_EMBED_MODEL` e passe a dimensão desejada através da construção do provedor no comando `hk embed` — consulte a [seção de incorporação do manual](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/cli-reference/#embedding-providers-and-dimensions) para obter detalhes.
 
 **Incompatibilidade de versão do esquema / banco de dados corrompido**
 

package/README.zh.md

@@ -65,7 +65,7 @@ claude-synergy/
 │   └── plugins-{official,community,knowledge-work}/  # Plugin marketplaces
 ├── synergies/               # 12 curated cross-product workflows
 ├── src/                     # TypeScript implementation
-├── test/                    # 382 tests (unit, integration, regression, smoke)
+├── test/                    # 508 tests (unit, integration, regression, smoke)
 ├── data/claude-synergy.db   # SQLite database (created by `hk init`)
 ├── schema.sql               # Tier 2a tables (products, releases, changes, entities, FTS5, …)
 ├── schema-vec.sql           # Tier 2b tables (chunks, chunks_vec, chunks_fts)
@@ -73,7 +73,7 @@ claude-synergy/
 └── URGENT_FINDINGS.md       # 23 actionable items surfaced from the corpus
 ```
 
-**实时数据（截至 v1.0.0 版本）：** 44 个产品 / 1,186 个发布文件 / 6,042 次变更 / 1,225 个实体 / 12 个协同关系 / 382 个测试。
+**实时数据 (截至 v1.1.0 版本):** 44 个产品 / 1,186 个发布文件 / 6,042 个变更 / 1,225 个实体 / 12 个协同功能 / 508 个测试 / 11 个 MCP 工具 / 17 个 CLI 命令。
 
 ---
 
@@ -84,11 +84,12 @@ claude-synergy/
 | 1. -- bootstrap (Markdown 文档) | ✅ 已发货。 | “Study-swarm”项目在2026年1月至5月期间发布了706个文件，随后，在第四阶段的扩展中，该数量增加到1186个。 |
 | 2a - SQLite + FTS5 + 命令行界面。 | ✅ 已发货。 | `hk` 命令行工具；包含 15 个子命令；数据摄取速度低于 300 毫秒。 |
 | 2b — sqlite-vec + 上下文检索 | ✅ 已发货。 | 提供商接口（无/结构化/ollama/claude-haiku 上下文 × ollama/voyage 嵌入 × 无/ollama-judge/voyage/cohere 重新排序）。 |
-| 3. 同步 + MCP 服务器。 | ✅ 已发货。 | `hk fetch / sync / seed-markers`；`claude-synergy-mcp` 通过标准输入/输出接口提供了 8 个工具。 |
+| 3. 同步 + MCP 服务器。 | ✅ 已发货。 | `hk fetch / sync / seed-markers`；`claude-synergy-mcp` 通过标准输入 (stdio) 提供了 11 个工具 (最初的 Tier-3 版本有 8 个，v1.1 版本新增了 3 个)。 |
 | 4a — 扩展范围，超越 Anthropic 的范畴。 | ✅ 已发货。 | +15 个 MCP SDK，Cursor (RSS)，Aider (HISTORY.md)，Continue.dev，Cody Enterprise (已过滤的 RSS)。 |
 | 4b — HTML 网页抓取工具。 | ✅ 已发货。 | GitHub Copilot + VS Code 聊天功能 (Windsurf 需要 Playwright — v0.7) |
 | 4c - 将HTML内容转换为Markdown格式并导入。 | ✅ 已发货。 | HTML 代码块（在 Copilot、VS Code 或 Cursor 中）现在针对 FTS5 和实体提取功能，会生成每条要点对应的一行数据。 |
 | 4d — playwright + MCP 注册 + YAML 配置文件。 | ✅ 已发货。 | 使用 Playwright 进行网页抓取；Smithery + 官方 MCP 注册信息作为第四级目录；产品信息已整合到 `products.yaml` 文件中。 |
+| **5 — v1.1 版本：窗口浏览 + OpenAI 嵌入** | ✅ 已发货。 | `hk diff` / `hk breaking`，所有浏览命令都支持日期范围；3 个新的 MCP 工具 (总共 11 个)；OpenAI 嵌入提供程序；可配置的嵌入维度；`claude-code` 自动同步；通用的 `keep-a-changelog` 解析器。 |
 
 v0.8 及后续版本的开发计划，请参考 [URGENT_FINDINGS.md](URGENT_FINDINGS.md) 文件以及相关问题列表。
 
@@ -126,8 +127,12 @@ hk sync                              # combined fetch → ingest → embed (cron
 hk seed-markers                      # one-time setup after initial corpus
 
 # Search
-hk query "managed agents"            # FTS5 keyword search
-hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ optional --rerank)
+hk query "managed agents"            # FTS5 keyword search (+ --until <date>)
+hk hybrid "credential exfiltration"  # FTS5 + vec hybrid via RRF (+ --rerank, --until)
+
+# Windowed change browsing
+hk diff [product] --since 7d         # what changed in a window, grouped by product+version
+hk breaking --since 30d              # filter-browse of breaking changes (no search term)
 
 # Entity lookups
 hk env-var CLAUDE_CODE_WORKFLOWS     # when introduced + history
@@ -136,7 +141,7 @@ hk model claude-opus-4-7             # model launch + mentions across products
 hk cve CVE-2025-66414                # CVE references in corpus
 
 # Browsing
-hk latest [--product X] [--limit N]  # recent releases
+hk latest [--product X] [--limit N]  # recent releases (+ --since <date>)
 hk products                          # list all 44 with counts
 hk top env_var                       # most-mentioned by entity type
                                      # (env_var, slash_command, cli_option,
@@ -144,6 +149,8 @@ hk top env_var                       # most-mentioned by entity type
                                      #  hook_event, setting_key)
 ```
 
+**v1.1 版本的更新：** `hk diff` 和 `hk breaking` 命令可以在不指定搜索词的情况下回答“最近发生了哪些变化？”。日期范围统一：所有浏览命令都支持 `--since` 和 `--until` 参数，格式为 `YYYY-MM-DD` (或完整的 ISO 8601 格式)，或者相对时间格式 (例如 `7d`、`2w`、`3m`、`1y`)。
+
 ---
 
 ## 示例工作流程
@@ -186,6 +193,30 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 查询中永远不会出现 "env_scrub"，vec 通过语义相似性将其呈现出来。 纯 FTS5 完全无法识别它。
 
+**本周 claude-code 的变化：**
+```
+$ hk diff claude-code --since 7d
+claude-code@2.1.147  2026-05-21  (3 changes)
+  [added]     Added the `Workflow` tool for deterministic multi-agent orchestration.
+  [changed]   Slash commands now lazy-load until first invocation.
+  [fixed]     Race condition in MCP server discovery on Windows.
+
+claude-code@2.1.146  2026-05-19  (1 change)
+  [fixed]     Restored `--debug` flag accidentally removed in 2.1.144.
+```
+
+**浏览所有代码库中的重大变更：**
+```
+$ hk breaking --since 30d --limit 5
+2026-05-15  claude-agent-sdk-python@0.2.82       Headless and SDK sessions now use Task tools by default.
+2026-05-14  claude-agent-sdk-typescript@0.3.142  Headless and SDK sessions now use Task tools by default.
+2026-05-08  anthropic-sdk-go@1.42.0              Removed deprecated `client.Beta()` namespace.
+2026-04-29  cursor@0.49.0                        MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
+2026-04-22  windsurf@1.10.0                      Removed `cascade.run` JSON-RPC method.
+```
+
+无需搜索词 — `hk breaking` 命令可以回答“最近是否有任何关键部分发生了变化？”
+
 ---
 
 ## MCP 服务器 — 允许您的代理访问此语料库
@@ -211,14 +242,19 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 | 工具 | 用途 |
 |---|---|
-| `search` | 混合 FTS5 + vec；可选的重新排序。 默认模式用于自然语言查询。 |
+| `search` | 混合 FTS5 + vec；可选的重新排序。默认模式用于自然语言查询。（+ `until` 日期上限） |
 | `lookup_entity` | 精确的实体历史记录：环境变量、斜杠命令、模型 ID、CVE 等。 |
-| `latest_releases` | 产品（或单个产品）的最新发布版本 |
+| `latest_releases` | 产品 (或单个产品) 的最新发布版本。（+ `since` 日期下限） |
 | `get_release` | 单个发布版本的完整内容 |
 | `list_products` | 带有计数和最新版本的枚举 |
 | `top_entities` | 按类型提及最多的实体 |
-| `list_synergies` | 精心策划的跨产品工作流程 |
+| `list_synergies` | 精心设计的跨产品工作流程。（+ 可选的 `product` 过滤器） |
 | `read_synergy` | 单个协同文件（synergy file）的完整文本 |
+| `get_changes_since` | **新增。** 按时间窗口分组的产品 + 版本变更。输入：`since` (必需)、`until?`、`product?`、`kind?`、`limit?`。 |
+| `search_breaking_changes` | **新增。** 包含所有重大变更的列表，无需搜索词。输入：`product?`、`since?`、`until?`、`limit?`。 |
+| `compare_versions` | **新增。** 一个产品的所有版本之间的变更。输入：`product`、`from_version`、`to_version`。 |
+
+这三个新的工具模仿了 `hk diff` / `hk breaking` 命令，以及之前需要脚本才能实现的版本比较工作流程。有关完整的输入模式，请参阅 [手册 → MCP 服务器](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/mcp-server/)。
 
 ---
 
@@ -226,11 +262,11 @@ $ hk hybrid "credential exfiltration" --limit 3
 
 完整的详细信息请参阅 [SOURCES.md](SOURCES.md)。
 
-- **第一层级 (GitHub 发布):** `gh api repos/<owner>/<repo>/releases`，涵盖 22 个产品，包括 Anthropic SDK（7 种语言）、Agent SDK（2 个）、ant CLI、claude-code-action、claude-code-security-review 以及 15 个 MCP 生态系统 SDK。
-- **第二层级 (原始 markdown):** `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
-- **第三层级 (HTML / RSS):** `platform.claude.com/docs/release-notes`、`support.claude.com/articles/12138966`、`cursor.com/changelog/rss.xml`（已过滤）、`sourcegraph.com/changelog/featured.rss`、`github.blog/changelog/label/copilot/`、`code.visualstudio.com/updates/v1_NNN`
-- **第四层级 (目录):** `anthropics/skills`、`claude-plugins-{official,community}`、`knowledge-work-plugins`
-- **第五层级 (建议):** `@ClaudeCodeLog` X 账号；marckrenn 变更日志镜像
+- **Tier 1 (GitHub 发布):** `gh api repos/<owner>/<repo>/releases`，涵盖 23 个产品，包括 Anthropic SDK (7 种语言)、Agent SDK (2 个)、ant CLI、**claude-code** (现在通过 gh-releases 自动同步，v1.1 版本之前是手动同步)、claude-code-action、claude-code-security-review，以及 15 个 MCP 生态系统 SDK。
+- **Tier 2 (原始 Markdown):** `Aider-AI/aider/HISTORY.md`。通用的 `keep-a-changelog` 解析器 (v1.1 版本及更高版本) 也适用于任何其源代码为 `CHANGELOG.md` 且符合 Keep-a-Changelog 格式的产品，可以通过 `products.yaml` 文件中的一个条目进行配置。
+- **Tier 3 (HTML / RSS):** `platform.claude.com/docs/release-notes`、`support.claude.com/articles/12138966`、`cursor.com/changelog/rss.xml`、`sourcegraph.com/changelog/featured.rss` (已过滤)、`github.blog/changelog/label/copilot/`、`code.visualstudio.com/updates/v1_NNN`。
+- **Tier 4 (目录):** `anthropics/skills`、`claude-plugins-{official,community}`、`knowledge-work-plugins`。
+- **Tier 5 (建议):** `@ClaudeCodeLog` X 账号；marckrenn 的变更日志镜像。
 
 抓取策略：`gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`。 增加一个新产品，就在 `products.yaml` 文件中增加一条记录。
 
@@ -255,7 +291,7 @@ $ hk hybrid "credential exfiltration" --limit 3
 Vitest 测试套件覆盖单元测试、集成测试、回归测试和初步测试。 **[test-spec-3.md](test-spec-3.md) 是当前版本 (v0.7.0) 的权威文档**；[test-spec.md](test-spec.md) (v1) 和 [test-spec-2.md](test-spec-2.md) (v2) 仍然保存在代码库中，作为设计演进的历史记录。
 
 ```bash
-pnpm test               # unit + integration + regression (~16s, 382 tests)
+pnpm test               # unit + integration + regression (~18s, 508 tests)
 pnpm test:watch         # interactive
 pnpm test:coverage      # generate coverage/index.html (thresholds: 78/75/85/78)
 pnpm test:smoke         # opt-in full-corpus smoke (RUN_SMOKE=1)
@@ -265,9 +301,9 @@ pnpm test:smoke         # opt-in full-corpus smoke (RUN_SMOKE=1)
 
 | 目录 | 涵盖内容 |
 |-----|----------------|
-| `test/unit/` | 模块级别 — 提取、导入、查询、数据库、嵌入、混合、获取 + 所有提供商 + 获取 RSS/变更日志/HTML + 获取 MCP 注册表 + 获取 Playwright + 产品配置 |
-| `test/integration/` | 端到端 — 流水线、同步、MCP 服务器 (stdio JSON-RPC)、命令行界面 |
-| `test/regression/` | §8.1–§8.18 — 每个部分都用于防止开发过程中出现的实际错误。 |
+| `test/unit/` | 每个模块：提取、导入、查询 (包括 `until` / 浏览 / since / 比较)、数据库 (包括 dim-config v3 迁移)、嵌入、混合、导入 + 所有提供程序 (Ollama / Voyage / **OpenAI**) + 导入 RSS/变更日志 (包括 **keep-a-changelog** 解析器)/HTML + 导入 MCP 注册表 + 导入 Playwright + 产品配置 + 协同功能导入/查询。 |
+| `test/integration/` | 端到端：流水线、同步、MCP 服务器 (stdio JSON-RPC，11 个工具)、CLI (包括 `hk diff`、`hk breaking`)。 |
+| `test/regression/` | §8.1–§8.19 — 每个部分都旨在防止开发过程中出现的实际错误 (§8.19：ghReleases 的早期退出分页保留了窗口内的项目)。 |
 | `test/smoke/` | 可选的完整语料库，用于测试 `products/` 目录下的文件 (1143 个文件)。 |
 | `test/fixtures/` | 3 个模拟产品 + 模拟 HTTP 响应 (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / 官方 MCP 注册表) |
 | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -308,8 +344,22 @@ CI：`.github/workflows/test.yml` 在代码提交和拉取请求时运行 `pnpm
 
 `hk embed` 命令会调用外部嵌入服务：
 
-- **Ollama (默认)** — 确保 Ollama 正在运行 (`ollama serve`)，并且已下载嵌入模型 (`ollama pull nomic-embed-text`)。
-- **Voyage** — 在您的环境中设置 `VOYAGE_API_KEY`。 检查您的 API 密钥，请访问 [dash.voyageai.com](https://dash.voyageai.com)。
+- **Ollama (默认，768维)** — 确保 Ollama 正在运行 (`ollama serve`)，并且已下载嵌入模型 (`ollama pull nomic-embed-text`)。
+- **Voyage (1024维)** — 在您的环境中设置 `VOYAGE_API_KEY`。您可以在 [dash.voyageai.com](https://dash.voyageai.com) 上查看您的 API 密钥。
+- **OpenAI (默认 1536 维，可配置)** — 设置 `OPENAI_API_KEY`。默认模型是 `text-embedding-3-small`；可以使用 `OPENAI_EMBED_MODEL` 覆盖该设置（例如，使用 `text-embedding-3-large`，其维度为 3072）。通过 `hk hybrid --embed openai` 或 `hk embed --embed openai` 使用。
+
+**在切换提供商时，嵌入维度不匹配**
+
+每个提供商生成固定维度的向量（Ollama 默认 768 维，Voyage 默认 1024 维，OpenAI 默认 1536 维——OpenAI 支持在模型原生尺寸范围内配置维度）。数据库将当前使用的维度存储在 `schema_meta.embedding_dim` 中。在存在分块的情况下，在不同维度之间切换提供商，会引发 `EMBEDDING_DIM_MISMATCH` 错误（`AppError`），而不是静默地损坏向量表。要切换：
+
+```bash
+rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
+hk init
+hk ingest
+hk embed --embed openai     # new provider, new dim, fresh chunks_vec
+```
+
+对于 OpenAI Matryoshka 截断（小于原生维度的嵌入），请设置 `OPENAI_EMBED_MODEL`，并通过 `hk embed` 的提供商配置传递所需的维度。有关详细信息，请参阅 [手册中的嵌入部分](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/cli-reference/#embedding-providers-and-dimensions)。
 
 **模式版本不匹配/数据库损坏**