@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.ja.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
- Anthropic社および関連するAI開発ツールに関する変更履歴をローカルで検索可能なミラーとして提供します。さらに、複数の製品を組み合わせたワークフローを説明する**Synergy（連携）**レイヤーも搭載しており、これにより、ハネス（制御環境）内のLLMエージェントが、ハネスが何ができるかを理解できるようになります。
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
+ Anthropic社および関連するAI開発ツールに関する変更履歴をローカルで検索可能なミラーとして提供します。さらに、複数の製品を組み合わせたワークフローを説明する**Synergy（連携）**レイヤーも搭載しており、これにより、ハネス（制御環境）内のLLMエージェントが、ハネスが何ができるかを理解できるようになります。
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
  **単一のFTS（Full-Text Search）クエリで、個々の変更履歴ではCVE（Common Vulnerabilities and Exposures：共通脆弱性情報）として特定されなかった、複数のSDKにまたがるセキュリティ修正をまとめて表示できます。** これが最も効果的なデモです。すべての変更履歴を並べて比較することで、パターンが見えてきます。
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 — ブートストラップ（Markdownコーパス）** | ✅ リリース済み | Study-swarmが706のリリースファイルを2026年1月から5月までに収集し、Tier 4で1,186に拡張。 |
83
85
  | **2a — SQLite + FTS5 + CLI** | ✅ リリース済み | `hk` CLI; 15のサブコマンド; 300ms未満のインジェスト速度 |
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つのツールをstdio経由で公開 |
87
+ | **3 — 同期 + MCPサーバー** | ✅ リリース済み | `hk fetch / sync / seed-markers`; `claude-synergy-mcp`は、標準入出力経由で11のツールを提供します（v1.1で追加された3つを含む、元々のTier-3で提供されていた8つに加え）。 |
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 Chat（WindsurfはPlaywrightが必要 — v0.7） |
88
90
  | **4c — turndown HTML→Markdownインジェスト** | ✅ リリース済み | HTMLの本文（Copilot/VS Code/Cursor）が、FTS5とエンティティ抽出のための、行ごとのリストを生成 |
89
91
  | **4d — Playwright + MCPレジストリ + YAML設定** | ✅ リリース済み | WindsurfはPlaywright経由; Smitheryと公式MCPレジストリをTier-4カタログとして使用; 製品は`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)およびissueで追跡中。
92
95
 
@@ -94,7 +97,7 @@ v0.8以降のロードマップ：[URGENT_FINDINGS.md](URGENT_FINDINGS.md)およ
94
97
 
95
98
  ## セキュリティとデータモデル
96
99
 
97
- このツールはローカルで実行されます。 **アクセスするデータ:** 派生したSQLiteデータベースと、Markdown形式のリリースファイル。これらはすべて再作成可能です。 **ネットワーク:** `hk fetch`または`hk sync`（GitHub API、RSSフィード、変更ログページ、MCPレジストリ）を実行する場合、またはリモートプロバイダー（Voyage、Cohere）を使用する`hk embed`を実行する場合にのみ、HTTPS通信を行います。 **機密情報:** 環境変数から`GITHUB_TOKEN`、`VOYAGE_API_KEY`、`COHERE_API_KEY`、`ANTHROPIC_API_KEY`を読み込みます。これらの情報はログに記録されず、ディスクに保存もされません。 **テレメトリー機能はありません。** 報告に関するポリシーは[SECURITY.md](SECURITY.md)を参照してください。
100
+ このツールはローカルで動作します。**アクセスするデータ：** 派生したSQLiteデータベースと、マークダウン形式のリリースファイル。これらはすべて再作成可能です。**ネットワーク：** `hk fetch` または `hk sync` コマンド（GitHub API、RSSフィード、変更履歴ページ、MCPレジストリ）、またはリモートプロバイダー（Voyage、Cohere）を使用する `hk embed` コマンドを実行する場合にのみ、HTTPS経由で外部サーバーと通信します。**機密情報：** `GITHUB_TOKEN`、`VOYAGE_API_KEY`、`COHERE_API_KEY`、`ANTHROPIC_API_KEY` を環境変数から読み込みます。これらの情報はログに記録されることも、ディスクに保存されることもありません。**テレメトリー機能はありません。** セキュリティに関するポリシーについては、[SECURITY.md](SECURITY.md) を参照してください。
98
101
 
99
102
  ---
100
103
 
@@ -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」という文字列を含みません。代わりに、意味的な類似性に基づいて表示されます。従来の完全一致検索では、該当する情報を見つけることができません。
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 @@ GitHub Copilotの`.vscode/mcp.json`ファイルでは、`mcpServers`ではなく
209
242
 
210
243
  | ツール | 目的 |
211
244
  |---|---|
212
- | `search` | ハイブリッドFTS5 + ベクトル検索；オプションで再ランキング。自然言語クエリのデフォルトモード。 |
245
+ | `search` | ハイブリッドFTS5 + ベクトル; オプションで再ランキング。自然言語クエリのデフォルトモード。（`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` | 特定のシナジーファイルの内容全体。 |
253
+ | `get_changes_since` | **新規。** 製品とバージョンごとにグループ化された、時間範囲内の変更点。入力：`since`（必須）、`until?`、`product?`、`kind?`、`limit?`。 |
254
+ | `search_breaking_changes` | **新規。** 検索語句不要の、変更点のフラットリスト。入力：`product?`、`since?`、`until?`、`limit?`。 |
255
+ | `compare_versions` | **新規。** 単一の製品の2つのバージョン間のすべての変更点。入力：`product`、`from_version`、`to_version`。 |
256
+
257
+ これらの3つの新しいツールは、`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 @@ GitHub Copilotの`.vscode/mcp.json`ファイルでは、`mcpServers`ではなく
224
262
 
225
263
  データソースの詳細については、[SOURCES.md](SOURCES.md)を参照してください。
226
264
 
227
- - **レベル1 (GitHub Releases)**：`gh api repos/<owner>/<repo>/releases`。Anthropic SDK（7言語）、Agent SDK（2）、ant CLI、claude-code-action、claude-code-security-review、および15のMCPエコシステムSDKを含む、22の製品。
228
- - **レベル2 (raw markdown)**：`anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
229
- - **レベル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`
230
- - **レベル4 (catalog)**：`anthropics/skills`、`claude-plugins-{official,community}`、`knowledge-work-plugins`
231
- - **レベル5 (advisory)**：`@ClaudeCodeLog`のXアカウント、marckrennの変更履歴ミラー
265
+ - **Tier 1 (GitHub Releases):** `gh api repos/<owner>/<repo>/releases`。Anthropic SDK（7言語）、Agent SDK（2）、ant CLI、**claude-code**（v1.1以降はgh-releasesで自動同期 — 以前は手動で初期化）、claude-code-action、claude-code-security-review、および15のMCPエコシステムSDKを含む、23製品。
266
+ - **Tier 2 (raw markdown):** `Aider-AI/aider/HISTORY.md`。汎用的な`keep-a-changelog`パーサー（v1.1以降）は、ソースコードがKeep-a-Changelog形式のCHANGELOG.mdファイルである製品にも利用可能です。`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 (catalog):** `anthropics/skills`、`claude-plugins-{official,community}`、`knowledge-work-plugins`
269
+ - **Tier 5 (advisory):** `@ClaudeCodeLog`のXアカウント; marckrennの変更ログミラー
232
270
 
233
271
  取得戦略：`gh-releases`、`rss`、`raw-changelog`、`html-scrape`、`catalog`、`playwright`。新しい製品ごとに、`products.yaml`に1つのエントリを追加します。
234
272
 
@@ -253,7 +291,7 @@ GitHub Copilotの`.vscode/mcp.json`ファイルでは、`mcpServers`ではなく
253
291
  Vitestスイートは、ユニットテスト、統合テスト、回帰テスト、および初期動作確認（smoke）の各レベルをカバーします。**[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/` | モジュールごと：抽出、取り込み、検索、データベース、埋め込み、ハイブリッド検索、取得（すべてのプロバイダー、fetch-rss/changelog/html、fetch-mcp-registry、fetch-playwright、製品構成） |
267
- | `test/integration/` | エンドツーエンド：パイプライン、同期、MCPサーバー（stdio JSON-RPC）、CLI |
268
- | `test/regression/` | §8.1–§8.18：それぞれが、開発中に修正された実際のバグに対する保護を提供します。 |
304
+ | `test/unit/` | モジュールごと — 抽出、取り込み、クエリ（`until` / 閲覧 / `since` / 比較を含む）、データベース（次元設定v3移行を含む）、埋め込み、ハイブリッド、取り込み + すべてのプロバイダー（Ollama / Voyage / **OpenAI**）+ RSS/変更ログの取り込み（**keep-a-changelog**パーサーを含む）/HTML + MCPレジストリの取り込み + Playwrightの取り込み + 製品設定 + 連携の取り込み/クエリ |
305
+ | `test/integration/` | エンドツーエンド — パイプライン、同期、MCPサーバー（標準入出力JSON-RPC、11のツール）、CLI（`hk diff`、`hk breaking`を含む） |
306
+ | `test/regression/` | §8.1–§8.19 — それぞれが、開発中に修正された実際のバグに対する対策。（§8.19：ghReleasesの早期終了ページネーションは、指定範囲内のアイテムを保持します） |
269
307
  | `test/smoke/` | 実際の`products/`ディレクトリ（1,143個のファイル）に対するフルコーパスのテスト。 |
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 test:coverage`をpushおよびプ
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` を設定します。APIキーは [dash.voyageai.com](https://dash.voyageai.com) で確認できます。
349
+ - **OpenAI (デフォルト1536次元、設定可能)**：`OPENAI_API_KEY` を設定します。デフォルトのモデルは `text-embedding-3-small` です。`OPENAI_EMBED_MODEL` で別のモデルを指定できます（例：3072次元の `text-embedding-3-large`）。`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
 
package/README.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
- A local, queryable mirror of every Anthropic + adjacent AI dev tool changelog — plus a curated **Synergy** layer describing cross-product workflows — so the LLM agent inside the harness knows what the harness can do.
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
+ A local, queryable mirror of every Anthropic + adjacent AI dev tool changelog — plus a curated **Synergy** layer describing cross-product workflows — so the LLM agent inside the harness knows what the harness can do.
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
@@ -64,7 +65,7 @@ claude-synergy/
64
65
  │ └── plugins-{official,community,knowledge-work}/ # Plugin marketplaces
65
66
  ├── synergies/ # 12 curated cross-product workflows
66
67
  ├── src/ # TypeScript implementation
67
- ├── test/ # 382 tests (unit, integration, regression, smoke)
68
+ ├── test/ # 508 tests (unit, integration, regression, smoke)
68
69
  ├── data/claude-synergy.db # SQLite database (created by `hk init`)
69
70
  ├── schema.sql # Tier 2a tables (products, releases, changes, entities, FTS5, …)
70
71
  ├── schema-vec.sql # Tier 2b tables (chunks, chunks_vec, chunks_fts)
@@ -72,7 +73,7 @@ claude-synergy/
72
73
  └── URGENT_FINDINGS.md # 23 actionable items surfaced from the corpus
73
74
  ```
74
75
 
75
- **Live numbers (as of v1.0.0):** 44 products / 1,186 release files / 6,042 changes / 1,225 entities / 12 synergies / 382 tests.
76
+ **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.
76
77
 
77
78
  ---
78
79
 
@@ -83,13 +84,14 @@ claude-synergy/
83
84
  | **1 — bootstrap (markdown corpus)** | ✅ shipped | Study-swarm seeded 706 release files Jan→May 2026; extended to 1,186 by Tier 4d |
84
85
  | **2a — SQLite + FTS5 + CLI** | ✅ shipped | `hk` CLI; 15 subcommands; sub-300ms ingest |
85
86
  | **2b — sqlite-vec + Contextual Retrieval** | ✅ shipped | Provider-pluggable (none/structured/ollama/claude-haiku context × ollama/voyage embed × none/ollama-judge/voyage/cohere rerank) |
86
- | **3 — sync + MCP server** | ✅ shipped | `hk fetch / sync / seed-markers`; `claude-synergy-mcp` exposes 8 tools over stdio |
87
+ | **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) |
87
88
  | **4a — extend beyond Anthropic** | ✅ shipped | +15 MCP SDKs, Cursor (RSS), Aider (HISTORY.md), Continue.dev, Cody Enterprise (RSS filtered) |
88
89
  | **4b — HTML-scrape fetcher** | ✅ shipped | GitHub Copilot + VS Code Chat (Windsurf needs Playwright — v0.7) |
89
90
  | **4c — turndown HTML→markdown ingest** | ✅ shipped | HTML bodies (Copilot/VS Code/Cursor) now produce per-bullet rows for FTS5 + entity extraction |
90
91
  | **4d — Playwright + MCP registry + YAML config** | ✅ shipped | Windsurf via Playwright; Smithery + official MCP Registry as Tier-4 catalogs; products consolidated into `products.yaml` |
92
+ | **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 |
91
93
 
92
- Roadmap for v0.8+: tracked in [URGENT_FINDINGS.md](URGENT_FINDINGS.md) and issues.
94
+ Roadmap beyond v1.1: tracked in [URGENT_FINDINGS.md](URGENT_FINDINGS.md) and issues.
93
95
 
94
96
  ---
95
97
 
@@ -113,7 +115,7 @@ For dev without building, use `npx tsx src/cli.ts ...` directly. **pnpm 10 quirk
113
115
 
114
116
  ---
115
117
 
116
- ## CLI surface — 15 commands
118
+ ## CLI surface — 17 commands
117
119
 
118
120
  ```
119
121
  # DB lifecycle
@@ -125,8 +127,12 @@ hk sync # combined fetch → ingest → embed (cron
125
127
  hk seed-markers # one-time setup after initial corpus
126
128
 
127
129
  # Search
128
- hk query "managed agents" # FTS5 keyword search
129
- 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)
130
136
 
131
137
  # Entity lookups
132
138
  hk env-var CLAUDE_CODE_WORKFLOWS # when introduced + history
@@ -135,7 +141,7 @@ hk model claude-opus-4-7 # model launch + mentions across products
135
141
  hk cve CVE-2025-66414 # CVE references in corpus
136
142
 
137
143
  # Browsing
138
- hk latest [--product X] [--limit N] # recent releases
144
+ hk latest [--product X] [--limit N] # recent releases (+ --since <date>)
139
145
  hk products # list all 44 with counts
140
146
  hk top env_var # most-mentioned by entity type
141
147
  # (env_var, slash_command, cli_option,
@@ -143,6 +149,8 @@ hk top env_var # most-mentioned by entity type
143
149
  # hook_event, setting_key)
144
150
  ```
145
151
 
152
+ **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`).
153
+
146
154
  ---
147
155
 
148
156
  ## Example workflows
@@ -185,11 +193,35 @@ $ hk hybrid "credential exfiltration" --limit 3
185
193
 
186
194
  The query never says "env_scrub" — vec surfaces it by semantic similarity. Pure FTS5 misses it entirely.
187
195
 
196
+ **What changed in claude-code this week:**
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
+ **Browse breaking changes across the corpus:**
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
+ No search term needed — `hk breaking` is the answer to "did anything load-bearing change recently?"
219
+
188
220
  ---
189
221
 
190
222
  ## MCP server — give your agents access to this corpus
191
223
 
192
- `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`:
224
+ `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`:
193
225
 
194
226
  ```json
195
227
  {
@@ -210,28 +242,33 @@ Tools exposed:
210
242
 
211
243
  | Tool | Purpose |
212
244
  |---|---|
213
- | `search` | Hybrid FTS5 + vec; optional rerank. Default mode for natural-language queries. |
245
+ | `search` | Hybrid FTS5 + vec; optional rerank. Default mode for natural-language queries. (+ `until` date upper bound) |
214
246
  | `lookup_entity` | Exact entity history: env vars, slash commands, model IDs, CVEs, etc. |
215
- | `latest_releases` | Recent releases across products (or one) |
247
+ | `latest_releases` | Recent releases across products (or one). (+ `since` date lower bound) |
216
248
  | `get_release` | Full content of one release |
217
249
  | `list_products` | Enumeration with counts + latest version |
218
250
  | `top_entities` | Most-mentioned entities by type |
219
- | `list_synergies` | Curated cross-product workflows |
251
+ | `list_synergies` | Curated cross-product workflows. (+ optional `product` filter) |
220
252
  | `read_synergy` | Full text of one synergy file |
253
+ | `get_changes_since` | **New.** Changes in a time window, grouped by product+version. Inputs: `since` (required), `until?`, `product?`, `kind?`, `limit?`. |
254
+ | `search_breaking_changes` | **New.** Flat list of breaking changes — no search term needed. Inputs: `product?`, `since?`, `until?`, `limit?`. |
255
+ | `compare_versions` | **New.** All changes between two versions of one product. Inputs: `product`, `from_version`, `to_version`. |
256
+
257
+ 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.
221
258
 
222
259
  ---
223
260
 
224
- ## Sources — 5 tiers, 6 fetcher strategies
261
+ ## Sources — 5 tiers, 7 fetcher strategies
225
262
 
226
263
  Full landscape in [SOURCES.md](SOURCES.md).
227
264
 
228
- - **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
229
- - **Tier 2 (raw markdown)** — `anthropics/claude-code/CHANGELOG.md` + `Aider-AI/aider/HISTORY.md`
265
+ - **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
266
+ - **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`.
230
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` (filtered), `github.blog/changelog/label/copilot/`, `code.visualstudio.com/updates/v1_NNN`
231
268
  - **Tier 4 (catalog)** — `anthropics/skills`, `claude-plugins-{official,community}`, `knowledge-work-plugins`
232
269
  - **Tier 5 (advisory)** — `@ClaudeCodeLog` X account; marckrenn changelog mirror
233
270
 
234
- Fetch strategies: `gh-releases | rss | raw-changelog | html-scrape | catalog | playwright`. New product = one entry in `products.yaml`.
271
+ Fetch strategies: `gh-releases | rss | raw-changelog | keep-a-changelog | html-scrape | catalog | playwright`. New product = one entry in `products.yaml`.
235
272
 
236
273
  ---
237
274
 
@@ -254,7 +291,7 @@ Full index in [synergies/INDEX.md](synergies/INDEX.md).
254
291
  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.
255
292
 
256
293
  ```bash
257
- pnpm test # unit + integration + regression (~16s, 382 tests)
294
+ pnpm test # unit + integration + regression (~18s, 508 tests)
258
295
  pnpm test:watch # interactive
259
296
  pnpm test:coverage # generate coverage/index.html (thresholds: 78/75/85/78)
260
297
  pnpm test:smoke # opt-in full-corpus smoke (RUN_SMOKE=1)
@@ -264,9 +301,9 @@ Layout:
264
301
 
265
302
  | Dir | What it covers |
266
303
  |-----|----------------|
267
- | `test/unit/` | per-module — extract, ingest, query, db, embed, hybrid, fetch + every provider + fetch-rss/changelog/html + fetch-mcp-registry + fetch-playwright + products-config |
268
- | `test/integration/` | end-to-end — pipeline, sync, MCP server (stdio JSON-RPC), CLI |
269
- | `test/regression/` | §8.1–§8.18 — each protects against a real bug fixed during development |
304
+ | `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 |
305
+ | `test/integration/` | end-to-end — pipeline, sync, MCP server (stdio JSON-RPC, 11 tools), CLI (incl. `hk diff`, `hk breaking`) |
306
+ | `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) |
270
307
  | `test/smoke/` | opt-in full-corpus against real `products/` (1,143 files) |
271
308
  | `test/fixtures/` | 3 fake products + mock HTTP responses (RSS / GH / Voyage / Cohere / Ollama / Anthropic / Smithery / Official MCP Registry) |
272
309
  | `test/helpers/` | `temp-db.ts`, `fetch-mock.ts`, `mcp-client.ts`, `seed-corpus.ts`, `golden-vectors.ts`, `playwright-mock.ts`, `yaml-fixtures.ts` |
@@ -307,8 +344,22 @@ Sync is idempotent — safe to re-run after a partial failure. Already-fetched r
307
344
 
308
345
  `hk embed` calls an external embedding service:
309
346
 
310
- - **Ollama (default)** — ensure Ollama is running (`ollama serve`) and the embedding model is pulled (`ollama pull nomic-embed-text`).
311
- - **Voyage** — set `VOYAGE_API_KEY` in your environment. Check your API key at [dash.voyageai.com](https://dash.voyageai.com).
347
+ - **Ollama (default, 768-dim)** — ensure Ollama is running (`ollama serve`) and the embedding model is pulled (`ollama pull nomic-embed-text`).
348
+ - **Voyage (1024-dim)** — set `VOYAGE_API_KEY` in your environment. Check your API key at [dash.voyageai.com](https://dash.voyageai.com).
349
+ - **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`.
350
+
351
+ **Embedding dimension mismatch on provider switch**
352
+
353
+ 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:
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
+ 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.
312
363
 
313
364
  **Schema version mismatch / corrupted database**
314
365