@mcptoolshop/claude-synergy 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/CHANGELOG.md +51 -0
  2. package/CONTRIBUTING.md +5 -4
  3. package/README.es.md +78 -26
  4. package/README.fr.md +77 -25
  5. package/README.hi.md +78 -26
  6. package/README.it.md +75 -23
  7. package/README.ja.md +78 -26
  8. package/README.md +78 -27
  9. package/README.pt-BR.md +77 -25
  10. package/README.zh.md +77 -25
  11. package/dist/chunk-H3466JDH.js +1564 -0
  12. package/dist/{chunk-HCIZPSW4.js → chunk-HZEQG3WT.js} +281 -1
  13. package/dist/cli.js +279 -457
  14. package/dist/ingest-Z45YH7OX.js +8 -0
  15. package/dist/mcp-server.js +252 -17
  16. package/package.json +1 -1
  17. package/products.yaml +12 -6
  18. package/schema-vec.sql +9 -5
  19. package/dist/chunk-YFGUTT22.js +0 -754
  20. package/dist/ingest-3LJNQWS7.js +0 -6
package/README.pt-BR.md CHANGED
@@ -4,14 +4,15 @@
4
4
 
5
5
  <p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-synergy/readme.png" alt="Claude Synergy" width="400"></p>
6
6
 
7
- Um espelho local e pesquisável de todos os registros de alterações do Anthropic e de outras ferramentas de desenvolvimento de IA, além de uma camada de **Sinergia** que descreve fluxos de trabalho entre diferentes produtos, para que o agente LLM dentro do sistema saiba o que o sistema pode fazer.
8
-
9
7
  <p align="center">
10
-
11
- [![tests](https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml/badge.svg)](https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@mcptoolshop/claude-synergy)](https://www.npmjs.com/package/@mcptoolshop/claude-synergy) [![license](https://img.shields.io/badge/license-MIT-blue)](#license) [![landing page](https://img.shields.io/badge/landing%20page-live-brightgreen)](https://mcp-tool-shop-org.github.io/claude-synergy/)
12
-
8
+ <a href="https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml"><img src="https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml/badge.svg" alt="tests"></a>
9
+ <a href="https://www.npmjs.com/package/@mcptoolshop/claude-synergy"><img src="https://img.shields.io/npm/v/@mcptoolshop/claude-synergy" alt="npm"></a>
10
+ <a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
11
+ <a href="https://mcp-tool-shop-org.github.io/claude-synergy/"><img src="https://img.shields.io/badge/landing%20page-live-brightgreen" alt="landing page"></a>
13
12
  </p>
14
13
 
14
+ Um espelho local e pesquisável de todos os registros de alterações do Anthropic e de outras ferramentas de desenvolvimento de IA, além de uma camada de **Sinergia** que descreve fluxos de trabalho entre diferentes produtos, para que o agente LLM dentro do sistema saiba o que o sistema pode fazer.
15
+
15
16
  ```bash
16
17
  $ hk query redact
17
18
  2026-05-11 anthropic-cli@1.7.1 [changed] redact api-key headers in debug logs
@@ -22,6 +23,7 @@ $ hk query redact
22
23
  4 results
23
24
  ```
24
25
 
26
+
25
27
  **Uma única consulta FTS (Full-Text Search) revela uma correção de segurança coordenada entre diferentes SDKs que não foi identificada como uma vulnerabilidade (CVE) em nenhum registro de alterações individual.** Esse é o exemplo mais impactante: padrões emergem quando todos os registros de alterações são exibidos lado a lado.
26
28
 
27
29
  Repositório: [github.com/mcp-tool-shop-org/claude-synergy](https://github.com/mcp-tool-shop-org/claude-synergy)
@@ -63,7 +65,7 @@ claude-synergy/
63
65
  │ └── plugins-{official,community,knowledge-work}/ # Plugin marketplaces
64
66
  ├── synergies/ # 12 curated cross-product workflows
65
67
  ├── src/ # TypeScript implementation
66
- ├── test/ # 382 tests (unit, integration, regression, smoke)
68
+ ├── test/ # 508 tests (unit, integration, regression, smoke)
67
69
  ├── data/claude-synergy.db # SQLite database (created by `hk init`)
68
70
  ├── schema.sql # Tier 2a tables (products, releases, changes, entities, FTS5, …)
69
71
  ├── schema-vec.sql # Tier 2b tables (chunks, chunks_vec, chunks_fts)
@@ -71,7 +73,7 @@ claude-synergy/
71
73
  └── URGENT_FINDINGS.md # 23 actionable items surfaced from the corpus
72
74
  ```
73
75
 
74
- **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.
76
+ **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.
75
77
 
76
78
  ---
77
79
 
@@ -82,11 +84,12 @@ claude-synergy/
82
84
  | **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. |
83
85
  | **2a — SQLite + FTS5 + CLI** | ✅ implementado | CLI `hk`; 15 subcomandos; ingestão em menos de 300ms. |
84
86
  | **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). |
85
- | **3 — sincronização + servidor MCP** | ✅ implementado | `hk fetch / sync / seed-markers`; o `claude-synergy-mcp` expõe 8 ferramentas via stdio. |
87
+ | **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). |
86
88
  | **4a — expansão para além do Anthropic** | ✅ implementado | +15 SDKs MCP, Cursor (RSS), Aider (HISTORY.md), Continue.dev, Cody Enterprise (RSS filtrado). |
87
89
  | **4b — coletor de HTML** | ✅ implementado | GitHub Copilot + VS Code Chat (Windsurf precisa do Playwright — v0.7). |
88
90
  | **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. |
89
91
  | **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`. |
92
+ | **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`. |
90
93
 
91
94
  Roteiro para a versão 0.8+: acompanhado em [URGENT_FINDINGS.md](URGENT_FINDINGS.md) e nas issues.
92
95
 
@@ -124,8 +127,12 @@ hk sync # combined fetch → ingest → embed (cron
124
127
  hk seed-markers # one-time setup after initial corpus
125
128
 
126
129
  # Search
127
- hk query "managed agents" # FTS5 keyword search
128
- hk hybrid "credential exfiltration" # FTS5 + vec hybrid via RRF (+ optional --rerank)
130
+ hk query "managed agents" # FTS5 keyword search (+ --until <date>)
131
+ hk hybrid "credential exfiltration" # FTS5 + vec hybrid via RRF (+ --rerank, --until)
132
+
133
+ # Windowed change browsing
134
+ hk diff [product] --since 7d # what changed in a window, grouped by product+version
135
+ hk breaking --since 30d # filter-browse of breaking changes (no search term)
129
136
 
130
137
  # Entity lookups
131
138
  hk env-var CLAUDE_CODE_WORKFLOWS # when introduced + history
@@ -134,7 +141,7 @@ hk model claude-opus-4-7 # model launch + mentions across products
134
141
  hk cve CVE-2025-66414 # CVE references in corpus
135
142
 
136
143
  # Browsing
137
- hk latest [--product X] [--limit N] # recent releases
144
+ hk latest [--product X] [--limit N] # recent releases (+ --since <date>)
138
145
  hk products # list all 44 with counts
139
146
  hk top env_var # most-mentioned by entity type
140
147
  # (env_var, slash_command, cli_option,
@@ -142,6 +149,8 @@ hk top env_var # most-mentioned by entity type
142
149
  # hook_event, setting_key)
143
150
  ```
144
151
 
152
+ **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`).
153
+
145
154
  ---
146
155
 
147
156
  ## Exemplos de fluxos de trabalho
@@ -184,6 +193,30 @@ $ hk hybrid "credential exfiltration" --limit 3
184
193
 
185
194
  A consulta nunca menciona "env_scrub" — o sistema o identifica por similaridade semântica. O sistema de busca tradicional (FTS5) não o encontra.
186
195
 
196
+ **O que mudou no claude-code esta semana:**
197
+ ```
198
+ $ hk diff claude-code --since 7d
199
+ claude-code@2.1.147 2026-05-21 (3 changes)
200
+ [added] Added the `Workflow` tool for deterministic multi-agent orchestration.
201
+ [changed] Slash commands now lazy-load until first invocation.
202
+ [fixed] Race condition in MCP server discovery on Windows.
203
+
204
+ claude-code@2.1.146 2026-05-19 (1 change)
205
+ [fixed] Restored `--debug` flag accidentally removed in 2.1.144.
206
+ ```
207
+
208
+ **Navegue pelas alterações significativas em todo o conjunto de dados:**
209
+ ```
210
+ $ hk breaking --since 30d --limit 5
211
+ 2026-05-15 claude-agent-sdk-python@0.2.82 Headless and SDK sessions now use Task tools by default.
212
+ 2026-05-14 claude-agent-sdk-typescript@0.3.142 Headless and SDK sessions now use Task tools by default.
213
+ 2026-05-08 anthropic-sdk-go@1.42.0 Removed deprecated `client.Beta()` namespace.
214
+ 2026-04-29 cursor@0.49.0 MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
215
+ 2026-04-22 windsurf@1.10.0 Removed `cascade.run` JSON-RPC method.
216
+ ```
217
+
218
+ Não é necessário um termo de pesquisa — `hk breaking` é a resposta para "alguma alteração importante ocorreu recentemente?".
219
+
187
220
  ---
188
221
 
189
222
  ## Servidor MCP — forneça acesso a este corpus para seus agentes
@@ -209,14 +242,19 @@ Ferramentas disponíveis:
209
242
 
210
243
  | Ferramenta | Propósito |
211
244
  |---|---|
212
- | `search` | FTS5 + busca vetorial; reclassificação opcional. Modo padrão para consultas em linguagem natural. |
245
+ | `search` | FTS5 + vet híbrido; reclassificação opcional. Modo padrão para consultas em linguagem natural. (+ limite superior de data `until`) |
213
246
  | `lookup_entity` | Histórico completo de entidades: variáveis de ambiente, comandos, IDs de modelos, CVEs, etc. |
214
- | `latest_releases` | Lançamentos recentes em todos os produtos (ou em um). |
247
+ | `latest_releases` | Lançamentos recentes em todos os produtos (ou em um). (+ limite inferior de data `since`) |
215
248
  | `get_release` | Conteúdo completo de um lançamento. |
216
249
  | `list_products` | Enumeração com contagens + versão mais recente. |
217
250
  | `top_entities` | Entidades mais mencionadas por tipo. |
218
- | `list_synergies` | Fluxos de trabalho entre produtos, selecionados. |
251
+ | `list_synergies` | Fluxos de trabalho entre produtos. (+ filtro de produto opcional) |
219
252
  | `read_synergy` | Texto completo de um arquivo de sinergia. |
253
+ | `get_changes_since` | **Novo.** Alterações em uma janela de tempo, agrupadas por produto+versão. Entradas: `since` (obrigatório), `until?`, `product?`, `kind?`, `limit?`. |
254
+ | `search_breaking_changes` | **Novo.** Lista simples de alterações significativas — não é necessário um termo de pesquisa. Entradas: `product?`, `since?`, `until?`, `limit?`. |
255
+ | `compare_versions` | **Novo.** Todas as alterações entre duas versões de um produto. Entradas: `product`, `from_version`, `to_version`. |
256
+
257
+ 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.
220
258
 
221
259
  ---
222
260
 
@@ -224,11 +262,11 @@ Ferramentas disponíveis:
224
262
 
225
263
  Visão geral completa em [SOURCES.md](SOURCES.md).
226
264
 
227
- - **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.
228
- - **Nível 2 (markdown bruto)** — `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
229
- - **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`
230
- - **Nível 4 (catálogo)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`
231
- - **Nível 5 (consultoria)** — Conta X `@ClaudeCodeLog`; espelho de changelog do marckrenn.
265
+ - **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.
266
+ - **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`.
267
+ - **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`.
268
+ - **Nível 4 (catálogo)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`.
269
+ - **Nível 5 (aconselhamento)** — Conta X `@ClaudeCodeLog`; espelho de changelog de marckrenn.
232
270
 
233
271
  Estratégias de busca: `gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`. Novo produto = uma entrada em `products.yaml`.
234
272
 
@@ -253,7 +291,7 @@ Estratégias de busca: `gh-releases | rss | raw-changelog | html-scrape | catalo
253
291
  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.
254
292
 
255
293
  ```bash
256
- pnpm test # unit + integration + regression (~16s, 382 tests)
294
+ pnpm test # unit + integration + regression (~18s, 508 tests)
257
295
  pnpm test:watch # interactive
258
296
  pnpm test:coverage # generate coverage/index.html (thresholds: 78/75/85/78)
259
297
  pnpm test:smoke # opt-in full-corpus smoke (RUN_SMOKE=1)
@@ -263,9 +301,9 @@ Estrutura:
263
301
 
264
302
  | Diretório | O que ele cobre |
265
303
  |-----|----------------|
266
- | `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. |
267
- | `test/integration/` | teste de ponta a ponta — pipeline, sincronização, servidor MCP (stdio JSON-RPC), CLI. |
268
- | `test/regression/` | §8.1–§8.18 — cada um protege contra um erro real corrigido durante o desenvolvimento. |
304
+ | `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. |
305
+ | `test/integration/` | de ponta a ponta — pipeline, sincronização, servidor MCP (JSON-RPC stdio, 11 ferramentas), CLI (incl. `hk diff`, `hk breaking`). |
306
+ | `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). |
269
307
  | `test/smoke/` | Teste completo com um conjunto de dados simulado, representando os arquivos reais do diretório `products/` (1.143 arquivos). |
270
308
  | `test/fixtures/` | 3 produtos simulados + respostas HTTP simuladas (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / Registro oficial do MCP). |
271
309
  | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -306,8 +344,22 @@ A sincronização é idempotente — é seguro executá-la novamente após uma f
306
344
 
307
345
  `hk embed` chama um serviço de incorporação externo:
308
346
 
309
- - **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`).
310
- - **Voyage** — defina `VOYAGE_API_KEY` no seu ambiente. Verifique sua chave de API em [dash.voyageai.com](https://dash.voyageai.com).
347
+ - **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`).
348
+ - **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).
349
+ - **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`.
350
+
351
+ **Incompatibilidade de dimensões de incorporação ao alternar de provedor**
352
+
353
+ 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:
354
+
355
+ ```bash
356
+ rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
357
+ hk init
358
+ hk ingest
359
+ hk embed --embed openai # new provider, new dim, fresh chunks_vec
360
+ ```
361
+
362
+ 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.
311
363
 
312
364
  **Incompatibilidade de versão do esquema / banco de dados corrompido**
313
365
 
package/README.zh.md CHANGED
@@ -4,13 +4,14 @@
4
4
 
5
5
  <p align="center"><img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/claude-synergy/readme.png" alt="Claude Synergy" width="400"></p>
6
6
 
7
- 一个本地、可查询的镜像，记录了 Anthropic 及其相关人工智能开发工具的所有更新日志，此外，还提供一个精心策划的“协同”层，描述了跨产品的工作流程，以便嵌入在系统中的大型语言模型（LLM）代理能够了解该系统的功能。
8
-
9
7
  <p align="center">
8
+ <a href="https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml"><img src="https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml/badge.svg" alt="tests"></a>
9
+ <a href="https://www.npmjs.com/package/@mcptoolshop/claude-synergy"><img src="https://img.shields.io/npm/v/@mcptoolshop/claude-synergy" alt="npm"></a>
10
+ <a href="#license"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
11
+ <a href="https://mcp-tool-shop-org.github.io/claude-synergy/"><img src="https://img.shields.io/badge/landing%20page-live-brightgreen" alt="landing page"></a>
12
+ </p>
10
13
 
11
- [![测试](https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml/badge.svg)](https://github.com/mcp-tool-shop-org/claude-synergy/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@mcptoolshop/claude-synergy)](https://www.npmjs.com/package/@mcptoolshop/claude-synergy) [![许可证](https://img.shields.io/badge/license-MIT-blue)](#license) [![着陆页](https://img.shields.io/badge/landing%20page-live-brightgreen)](https://mcp-tool-shop-org.github.io/claude-synergy/)
12
-
13
- 请提供需要翻译的英文文本。
14
+ 一个本地、可查询的镜像，记录了 Anthropic 及其相关人工智能开发工具的所有更新日志，此外，还提供一个精心策划的“协同”层，描述了跨产品的工作流程，以便嵌入在系统中的大型语言模型（LLM）代理能够了解该系统的功能。
14
15
 
15
16
  ```bash
16
17
  $ hk query redact
@@ -22,6 +23,7 @@ $ hk query redact
22
23
  4 results
23
24
  ```
24
25
 
26
+
25
27
  **通过一次完整的FTS查询，我们发现了一个跨SDK的安全修复方案，但单个版本的更新日志中并未将其标记为CVE漏洞。** 这就是最直观的演示：当所有更新日志并排比较时，隐藏的模式就会显现出来。
26
28
 
27
29
  代码仓库：[github.com/mcp-tool-shop-org/claude-synergy](https://github.com/mcp-tool-shop-org/claude-synergy)
@@ -63,7 +65,7 @@ claude-synergy/
63
65
  │ └── plugins-{official,community,knowledge-work}/ # Plugin marketplaces
64
66
  ├── synergies/ # 12 curated cross-product workflows
65
67
  ├── src/ # TypeScript implementation
66
- ├── test/ # 382 tests (unit, integration, regression, smoke)
68
+ ├── test/ # 508 tests (unit, integration, regression, smoke)
67
69
  ├── data/claude-synergy.db # SQLite database (created by `hk init`)
68
70
  ├── schema.sql # Tier 2a tables (products, releases, changes, entities, FTS5, …)
69
71
  ├── schema-vec.sql # Tier 2b tables (chunks, chunks_vec, chunks_fts)
@@ -71,7 +73,7 @@ claude-synergy/
71
73
  └── URGENT_FINDINGS.md # 23 actionable items surfaced from the corpus
72
74
  ```
73
75
 
74
- **实时数据（截至 v1.0.0 版本）：** 44 个产品 / 1,186 个发布文件 / 6,042 次变更 / 1,225 个实体 / 12 个协同关系 / 382 个测试。
76
+ **实时数据 (截至 v1.1.0 版本):** 44 个产品 / 1,186 个发布文件 / 6,042 个变更 / 1,225 个实体 / 12 个协同功能 / 508 个测试 / 11 个 MCP 工具 / 17 个 CLI 命令。
75
77
 
76
78
  ---
77
79
 
@@ -82,11 +84,12 @@ claude-synergy/
82
84
  | 1. -- bootstrap (Markdown 文档) | ✅ 已发货。 | “Study-swarm”项目在2026年1月至5月期间发布了706个文件，随后，在第四阶段的扩展中，该数量增加到1186个。 |
83
85
  | 2a - SQLite + FTS5 + 命令行界面。 | ✅ 已发货。 | `hk` 命令行工具；包含 15 个子命令；数据摄取速度低于 300 毫秒。 |
84
86
  | 2b — sqlite-vec + 上下文检索 | ✅ 已发货。 | 提供商接口（无/结构化/ollama/claude-haiku 上下文 × ollama/voyage 嵌入 × 无/ollama-judge/voyage/cohere 重新排序）。 |
85
- | 3. 同步 + MCP 服务器。 | ✅ 已发货。 | `hk fetch / sync / seed-markers`；`claude-synergy-mcp` 通过标准输入/输出接口提供了 8 个工具。 |
87
+ | 3. 同步 + MCP 服务器。 | ✅ 已发货。 | `hk fetch / sync / seed-markers`；`claude-synergy-mcp` 通过标准输入 (stdio) 提供了 11 个工具 (最初的 Tier-3 版本有 8 个，v1.1 版本新增了 3 个)。 |
86
88
  | 4a — 扩展范围，超越 Anthropic 的范畴。 | ✅ 已发货。 | +15 个 MCP SDK，Cursor (RSS)，Aider (HISTORY.md)，Continue.dev，Cody Enterprise (已过滤的 RSS)。 |
87
89
  | 4b — HTML 网页抓取工具。 | ✅ 已发货。 | GitHub Copilot + VS Code 聊天功能 (Windsurf 需要 Playwright — v0.7) |
88
90
  | 4c - 将HTML内容转换为Markdown格式并导入。 | ✅ 已发货。 | HTML 代码块（在 Copilot、VS Code 或 Cursor 中）现在针对 FTS5 和实体提取功能，会生成每条要点对应的一行数据。 |
89
91
  | 4d — playwright + MCP 注册 + YAML 配置文件。 | ✅ 已发货。 | 使用 Playwright 进行网页抓取；Smithery + 官方 MCP 注册信息作为第四级目录；产品信息已整合到 `products.yaml` 文件中。 |
92
+ | **5 — v1.1 版本：窗口浏览 + OpenAI 嵌入** | ✅ 已发货。 | `hk diff` / `hk breaking`，所有浏览命令都支持日期范围；3 个新的 MCP 工具 (总共 11 个)；OpenAI 嵌入提供程序；可配置的嵌入维度；`claude-code` 自动同步；通用的 `keep-a-changelog` 解析器。 |
90
93
 
91
94
  v0.8 及后续版本的开发计划，请参考 [URGENT_FINDINGS.md](URGENT_FINDINGS.md) 文件以及相关问题列表。
92
95
 
@@ -124,8 +127,12 @@ hk sync # combined fetch → ingest → embed (cron
124
127
  hk seed-markers # one-time setup after initial corpus
125
128
 
126
129
  # Search
127
- hk query "managed agents" # FTS5 keyword search
128
- hk hybrid "credential exfiltration" # FTS5 + vec hybrid via RRF (+ optional --rerank)
130
+ hk query "managed agents" # FTS5 keyword search (+ --until <date>)
131
+ hk hybrid "credential exfiltration" # FTS5 + vec hybrid via RRF (+ --rerank, --until)
132
+
133
+ # Windowed change browsing
134
+ hk diff [product] --since 7d # what changed in a window, grouped by product+version
135
+ hk breaking --since 30d # filter-browse of breaking changes (no search term)
129
136
 
130
137
  # Entity lookups
131
138
  hk env-var CLAUDE_CODE_WORKFLOWS # when introduced + history
@@ -134,7 +141,7 @@ hk model claude-opus-4-7 # model launch + mentions across products
134
141
  hk cve CVE-2025-66414 # CVE references in corpus
135
142
 
136
143
  # Browsing
137
- hk latest [--product X] [--limit N] # recent releases
144
+ hk latest [--product X] [--limit N] # recent releases (+ --since <date>)
138
145
  hk products # list all 44 with counts
139
146
  hk top env_var # most-mentioned by entity type
140
147
  # (env_var, slash_command, cli_option,
@@ -142,6 +149,8 @@ hk top env_var # most-mentioned by entity type
142
149
  # hook_event, setting_key)
143
150
  ```
144
151
 
152
+ **v1.1 版本的更新：** `hk diff` 和 `hk breaking` 命令可以在不指定搜索词的情况下回答“最近发生了哪些变化？”。日期范围统一：所有浏览命令都支持 `--since` 和 `--until` 参数，格式为 `YYYY-MM-DD` (或完整的 ISO 8601 格式)，或者相对时间格式 (例如 `7d`、`2w`、`3m`、`1y`)。
153
+
145
154
  ---
146
155
 
147
156
  ## 示例工作流程
@@ -184,6 +193,30 @@ $ hk hybrid "credential exfiltration" --limit 3
184
193
 
185
194
  查询中永远不会出现 "env_scrub"，vec 通过语义相似性将其呈现出来。 纯 FTS5 完全无法识别它。
186
195
 
196
+ **本周 claude-code 的变化：**
197
+ ```
198
+ $ hk diff claude-code --since 7d
199
+ claude-code@2.1.147 2026-05-21 (3 changes)
200
+ [added] Added the `Workflow` tool for deterministic multi-agent orchestration.
201
+ [changed] Slash commands now lazy-load until first invocation.
202
+ [fixed] Race condition in MCP server discovery on Windows.
203
+
204
+ claude-code@2.1.146 2026-05-19 (1 change)
205
+ [fixed] Restored `--debug` flag accidentally removed in 2.1.144.
206
+ ```
207
+
208
+ **浏览所有代码库中的重大变更：**
209
+ ```
210
+ $ hk breaking --since 30d --limit 5
211
+ 2026-05-15 claude-agent-sdk-python@0.2.82 Headless and SDK sessions now use Task tools by default.
212
+ 2026-05-14 claude-agent-sdk-typescript@0.3.142 Headless and SDK sessions now use Task tools by default.
213
+ 2026-05-08 anthropic-sdk-go@1.42.0 Removed deprecated `client.Beta()` namespace.
214
+ 2026-04-29 cursor@0.49.0 MCP server config moved from `cursor.json` to `.cursor/mcp.json`.
215
+ 2026-04-22 windsurf@1.10.0 Removed `cascade.run` JSON-RPC method.
216
+ ```
217
+
218
+ 无需搜索词 — `hk breaking` 命令可以回答“最近是否有任何关键部分发生了变化？”
219
+
187
220
  ---
188
221
 
189
222
  ## MCP 服务器 — 允许您的代理访问此语料库
@@ -209,14 +242,19 @@ $ hk hybrid "credential exfiltration" --limit 3
209
242
 
210
243
  | 工具 | 用途 |
211
244
  |---|---|
212
- | `search` | 混合 FTS5 + vec；可选的重新排序。 默认模式用于自然语言查询。 |
245
+ | `search` | 混合 FTS5 + vec；可选的重新排序。默认模式用于自然语言查询。（+ `until` 日期上限） |
213
246
  | `lookup_entity` | 精确的实体历史记录：环境变量、斜杠命令、模型 ID、CVE 等。 |
214
- | `latest_releases` | 产品（或单个产品）的最新发布版本 |
247
+ | `latest_releases` | 产品 (或单个产品) 的最新发布版本。（+ `since` 日期下限） |
215
248
  | `get_release` | 单个发布版本的完整内容 |
216
249
  | `list_products` | 带有计数和最新版本的枚举 |
217
250
  | `top_entities` | 按类型提及最多的实体 |
218
- | `list_synergies` | 精心策划的跨产品工作流程 |
251
+ | `list_synergies` | 精心设计的跨产品工作流程。（+ 可选的 `product` 过滤器） |
219
252
  | `read_synergy` | 单个协同文件（synergy file）的完整文本 |
253
+ | `get_changes_since` | **新增。** 按时间窗口分组的产品 + 版本变更。输入：`since` (必需)、`until?`、`product?`、`kind?`、`limit?`。 |
254
+ | `search_breaking_changes` | **新增。** 包含所有重大变更的列表，无需搜索词。输入：`product?`、`since?`、`until?`、`limit?`。 |
255
+ | `compare_versions` | **新增。** 一个产品的所有版本之间的变更。输入：`product`、`from_version`、`to_version`。 |
256
+
257
+ 这三个新的工具模仿了 `hk diff` / `hk breaking` 命令，以及之前需要脚本才能实现的版本比较工作流程。有关完整的输入模式，请参阅 [手册 → MCP 服务器](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/mcp-server/)。
220
258
 
221
259
  ---
222
260
 
@@ -224,11 +262,11 @@ $ hk hybrid "credential exfiltration" --limit 3
224
262
 
225
263
  完整的详细信息请参阅 [SOURCES.md](SOURCES.md)。
226
264
 
227
- - **第一层级 (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。
228
- - **第二层级 (原始 markdown):** `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
229
- - **第三层级 (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`
230
- - **第四层级 (目录):** `anthropics/skills`、`claude-plugins-{official,community}`、`knowledge-work-plugins`
231
- - **第五层级 (建议):** `@ClaudeCodeLog` X 账号；marckrenn 变更日志镜像
265
+ - **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。
266
+ - **Tier 2 (原始 Markdown):** `Aider-AI/aider/HISTORY.md`。通用的 `keep-a-changelog` 解析器 (v1.1 版本及更高版本) 也适用于任何其源代码为 `CHANGELOG.md` 且符合 Keep-a-Changelog 格式的产品，可以通过 `products.yaml` 文件中的一个条目进行配置。
267
+ - **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`。
268
+ - **Tier 4 (目录):** `anthropics/skills`、`claude-plugins-{official,community}`、`knowledge-work-plugins`。
269
+ - **Tier 5 (建议):** `@ClaudeCodeLog` X 账号；marckrenn 的变更日志镜像。
232
270
 
233
271
  抓取策略：`gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`。 增加一个新产品，就在 `products.yaml` 文件中增加一条记录。
234
272
 
@@ -253,7 +291,7 @@ $ hk hybrid "credential exfiltration" --limit 3
253
291
  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) 仍然保存在代码库中，作为设计演进的历史记录。
254
292
 
255
293
  ```bash
256
- pnpm test # unit + integration + regression (~16s, 382 tests)
294
+ pnpm test # unit + integration + regression (~18s, 508 tests)
257
295
  pnpm test:watch # interactive
258
296
  pnpm test:coverage # generate coverage/index.html (thresholds: 78/75/85/78)
259
297
  pnpm test:smoke # opt-in full-corpus smoke (RUN_SMOKE=1)
@@ -263,9 +301,9 @@ pnpm test:smoke # opt-in full-corpus smoke (RUN_SMOKE=1)
263
301
 
264
302
  | 目录 | 涵盖内容 |
265
303
  |-----|----------------|
266
- | `test/unit/` | 模块级别 — 提取、导入、查询、数据库、嵌入、混合、获取 + 所有提供商 + 获取 RSS/变更日志/HTML + 获取 MCP 注册表 + 获取 Playwright + 产品配置 |
267
- | `test/integration/` | 端到端 — 流水线、同步、MCP 服务器 (stdio JSON-RPC)、命令行界面 |
268
- | `test/regression/` | §8.1–§8.18 — 每个部分都用于防止开发过程中出现的实际错误。 |
304
+ | `test/unit/` | 每个模块：提取、导入、查询 (包括 `until` / 浏览 / since / 比较)、数据库 (包括 dim-config v3 迁移)、嵌入、混合、导入 + 所有提供程序 (Ollama / Voyage / **OpenAI**) + 导入 RSS/变更日志 (包括 **keep-a-changelog** 解析器)/HTML + 导入 MCP 注册表 + 导入 Playwright + 产品配置 + 协同功能导入/查询。 |
305
+ | `test/integration/` | 端到端：流水线、同步、MCP 服务器 (stdio JSON-RPC，11 个工具)、CLI (包括 `hk diff`、`hk breaking`)。 |
306
+ | `test/regression/` | §8.1–§8.19 — 每个部分都旨在防止开发过程中出现的实际错误 (§8.19：ghReleases 的早期退出分页保留了窗口内的项目)。 |
269
307
  | `test/smoke/` | 可选的完整语料库，用于测试 `products/` 目录下的文件 (1143 个文件)。 |
270
308
  | `test/fixtures/` | 3 个模拟产品 + 模拟 HTTP 响应 (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / 官方 MCP 注册表) |
271
309
  | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -306,8 +344,22 @@ CI：`.github/workflows/test.yml` 在代码提交和拉取请求时运行 `pnpm
306
344
 
307
345
  `hk embed` 命令会调用外部嵌入服务：
308
346
 
309
- - **Ollama (默认)** — 确保 Ollama 正在运行 (`ollama serve`)，并且已下载嵌入模型 (`ollama pull nomic-embed-text`)。
310
- - **Voyage** — 在您的环境中设置 `VOYAGE_API_KEY`。 检查您的 API 密钥，请访问 [dash.voyageai.com](https://dash.voyageai.com)。
347
+ - **Ollama (默认，768维)** — 确保 Ollama 正在运行 (`ollama serve`)，并且已下载嵌入模型 (`ollama pull nomic-embed-text`)。
348
+ - **Voyage (1024维)** — 在您的环境中设置 `VOYAGE_API_KEY`。您可以在 [dash.voyageai.com](https://dash.voyageai.com) 上查看您的 API 密钥。
349
+ - **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` 使用。
350
+
351
+ **在切换提供商时，嵌入维度不匹配**
352
+
353
+ 每个提供商生成固定维度的向量（Ollama 默认 768 维，Voyage 默认 1024 维，OpenAI 默认 1536 维——OpenAI 支持在模型原生尺寸范围内配置维度）。数据库将当前使用的维度存储在 `schema_meta.embedding_dim` 中。在存在分块的情况下，在不同维度之间切换提供商，会引发 `EMBEDDING_DIM_MISMATCH` 错误（`AppError`），而不是静默地损坏向量表。要切换：
354
+
355
+ ```bash
356
+ rm data/claude-synergy.db data/claude-synergy.db-wal data/claude-synergy.db-shm
357
+ hk init
358
+ hk ingest
359
+ hk embed --embed openai # new provider, new dim, fresh chunks_vec
360
+ ```
361
+
362
+ 对于 OpenAI Matryoshka 截断（小于原生维度的嵌入），请设置 `OPENAI_EMBED_MODEL`，并通过 `hk embed` 的提供商配置传递所需的维度。有关详细信息，请参阅 [手册中的嵌入部分](https://mcp-tool-shop-org.github.io/claude-synergy/handbook/cli-reference/#embedding-providers-and-dimensions)。
311
363
 
312
364
  **模式版本不匹配/数据库损坏**
313
365