rekipedia 0.15.1 → 0.17.17

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 (4) hide show
  1. package/README.md +55 -341
  2. package/README.zh-CN.md +402 -0
  3. package/README.zh-TW.md +402 -0
  4. package/package.json +2 -2
package/README.md CHANGED
@@ -1,393 +1,110 @@
1
1
  # rekipedia
2
2
 
3
+ **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
4
+
3
5
  > Your AI tech lead — always available, always up to date.
4
6
 
5
- rekipedia scans any repository into a portable SQLite knowledge store and gives every developer on the team an LLM-powered tech lead they can ask anything: _"How does the auth flow work?", "What's the fastest way to add a new API endpoint?", "What broke the payment service last week?"_
7
+ rekipedia scans any repository into a portable SQLite knowledge store and gives every developer an LLM-powered tech lead they can ask anything.
6
8
 
7
- No hallucinations, no guessing — every answer is grounded in your actual codebase.
9
+ No hallucinations — every answer is grounded in your actual codebase.
8
10
 
9
- ### Key features
10
- - **Relationship confidence scoring**: every extracted relationship tagged as EXTRACTED/INFERRED/AMBIGUOUS with confidence score
11
- - **Design rationale extraction**: `# NOTE:`, `# HACK:`, `# WHY:` comments extracted as knowledge nodes
12
- - **God nodes**: highest-degree symbols surfaced in index.md and highlighted in the graph UI
13
- - **Interactive dependency graph**: `rekipedia serve` now includes a `/graph` route with D3.js force-directed visualization
14
- - **Git hooks**: `rekipedia hook install` triggers auto-rebuild on every commit
15
- - **Agentic wiki orchestration**: `PlannerAgent` designs the wiki structure dynamically based on your repo
16
- - **Page importance scoring**: planner assigns each page an importance score (0–100); nav sidebar sorts by priority
17
- - **DeepWiki-style sections**: pages grouped into logical sections (`getting-started`, `architecture`, `core-components`, etc.)
18
- - **Wiki sidebar categories**: `reki serve` sidebar groups pages by `section` field with collapsible headers
19
- - **Live search**: type in the sidebar search box to filter wiki pages by title or category instantly
20
- - **Refactor analysis**: `reki refactor` detects code smells (god class, circular deps, dead code, high coupling) with LLM-enriched suggestions — outputs `REFACTOR.md` + `refactor_report.json`
21
- - **Context slicing**: each page only receives the data it needs (~40–60% token reduction vs fixed-layout approach)
22
- - **Hybrid RAG Q&A**: FAISS-indexed code chunks + wiki pages give the LLM full codebase context when answering questions
23
- - **Embed provider choice**: `--embed-provider openai|ollama|azure|...` — any litellm-compatible embedding model
24
- - **Wiki export**: bundle to a single Markdown file, ZIP archive, or structured JSON (`rekipedia export`)
25
- - **Incremental updates**: only re-processes changed files after the first scan
26
- - **Grounded Q&A**: answers cite real file paths and line numbers — no hallucinations
27
- - **Codebase tree index** — every scan builds a hierarchical directory/file tree in SQLite, enabling structured navigation and future reasoning-based retrieval.
11
+ ---
28
12
 
29
13
  ## Quick start
30
14
 
31
- ### via npm / npx (no install required)
32
-
33
- ```bash
34
- npx rekipedia init .
35
- npx rekipedia scan .
36
- ```
37
-
38
- ### via uv / uvx (no install required)
39
-
40
15
  ```bash
41
- uvx rekipedia init .
42
- uvx rekipedia scan .
43
- ```
44
-
45
- ### Permanent install
46
-
47
- ```bash
48
- # Core (scan + serve + ask)
49
- pip install rekipedia
16
+ # No install required
17
+ npx rekipedia init . && npx rekipedia scan .
50
18
  # or
51
- uv tool install rekipedia
52
-
53
- # With RAG support (semantic embed + search — needs faiss-cpu + numpy ~100MB)
54
- pip install "rekipedia[rag]"
55
-
56
- # Homebrew (Go single binary — no Python needed)
57
- brew tap unrealandychan/tap
58
- brew install rekipedia
19
+ uvx rekipedia init . && uvx rekipedia scan .
59
20
  ```
60
21
 
61
- ---
62
-
63
- ## Python API
64
-
65
- Use rekipedia programmatically inside Jupyter notebooks, CI pipelines, or any Python application:
66
-
67
- ```python
68
- import rekipedia
69
-
70
- # Scan a local repo
71
- result = rekipedia.scan("/path/to/repo")
72
- print(result.page_count) # number of wiki pages generated
73
- print(result.symbol_count) # number of code symbols extracted
74
- print(result.token_count) # estimated token count of the wiki
75
-
76
- # Ask a question — grounded answer with file:line citations
77
- answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
78
- print(answer.text)
79
- for citation in answer.citations:
80
- print(f" {citation.file}:{citation.line}")
81
-
82
- # Async variants (Jupyter-friendly)
83
- result = await rekipedia.scan_async("/path/to/repo")
84
- answer = await rekipedia.ask_async("/path/to/repo", "What is the entry point?")
22
+ ```bash
23
+ # Permanent install
24
+ pip install rekipedia # core
25
+ pip install "rekipedia[rag]" # + semantic search (FAISS)
85
26
  ```
86
27
 
87
- **Return types:**
88
-
89
- | Type | Key fields |
90
- |---|---|
91
- | `ScanResult` | `page_count`, `symbol_count`, `token_count`, `wiki_pages`, `db_path`, `wiki_dir` |
92
- | `AskResult` | `text`, `citations: list[Citation]`, `model_used` |
93
- | `Citation` | `file`, `line`, `snippet` |
94
-
95
28
  ---
96
29
 
97
- ## Commands
30
+ ## Core commands
98
31
 
99
- | Command | Description |
32
+ | Command | What it does |
100
33
  |---|---|
101
- | `rekipedia init [REPO]` | Scaffold `.rekipedia/` with `config.yml` and update `.gitignore` |
102
- | `rekipedia scan [REPO]` | Full analysis — extracts symbols, synthesises wiki pages, exports JSON |
103
- | `rekipedia update [REPO]` | Incremental refresh — re-extracts only changed files, keeps the rest |
104
- | `rekipedia ask [QUESTION]` | Interactive Q&A REPL — streaming answers, Ctrl+C to quit |
105
- | `rekipedia serve [REPO]` | Start a local web UI to browse wiki pages and ask questions |
106
- | `rekipedia embed [REPO]` | Build (or rebuild) the FAISS semantic search index for hybrid RAG Q&A |
107
- | `rekipedia export [REPO]` | Bundle the wiki to a single file (`--format md\|zip\|json`) |
108
- | `rekipedia hook install/uninstall/status` | Manage git post-commit hook for auto wiki rebuild |
109
- | `rekipedia diff [A] [B]` | Compare two graph snapshots (defaults to last two) |
110
- | `rekipedia impact <file>` | Show blast-radius — all affected files, symbols, tests for a changed file |
111
- | `rekipedia search <query>` | Search symbols (`--all-repos` for cross-repo parallel search) |
112
- | `rekipedia export --format graphml\|cypher\|obsidian` | Export graph to GraphML / Neo4j Cypher / Obsidian wikilinks |
113
- | `rekipedia mcp` | Start JSON-RPC 2.0 MCP stdio server (6 tools for AI coding assistants) |
114
- | `rekipedia watch add\|start\|list\|remove` | Watch repos and auto-index on file change |
115
- | `rekipedia refactor [REPO]` | Detect code smells + generate `REFACTOR.md` and `refactor_report.json` (use `--no-llm` for static only) |
116
- | `rekipedia note add\|list\|remove\|edit\|import` | Manage persistent tech lead notes — injected into `reki ask` context automatically |
34
+ | `reki init .` | Scaffold config |
35
+ | `reki scan .` | Full analysis → wiki + knowledge store |
36
+ | `reki update .` | Incremental refresh (changed files only) |
37
+ | `reki serve .` | Local web UI — browse, search, ask AI |
38
+ | `reki ask` | Interactive Q&A REPL (streamed) |
39
+ | `reki embed .` | Build FAISS semantic index for hybrid RAG |
40
+ | `reki export .` | Bundle wiki → `--format md\|zip\|json\|html` |
41
+ | `reki diff` | Uncommitted-change impact analysis |
42
+ | `reki domain .` | Map codebase to business layers (API/Service/Data/UI) |
43
+ | `reki tour .` | Guided learning walkthrough by dependency depth |
44
+ | `reki onboard .` | Static onboarding guide for new developers |
45
+ | `reki review` | LLM PR review grounded in wiki context |
46
+ | `reki refactor .` | Detect code smells → `REFACTOR.md` |
47
+ | `reki watch .` | Auto-index on file change (OS watcher) |
48
+ | `reki hook install` | Git post-commit auto-rebuild |
49
+ | `reki mcp` | MCP stdio server for AI coding assistants |
117
50
 
118
51
  ---
119
52
 
120
53
  ## LLM configuration
121
54
 
122
- After running `rekipedia init`, edit `.rekipedia/config.yml`:
55
+ After `reki init`, edit `.rekipedia/config.yml`:
123
56
 
124
57
  ```yaml
125
- version: 1
126
- ignore:
127
- - .git
128
- - node_modules
129
- - __pycache__
130
- - .rekipedia
131
- languages:
132
- - python
133
- - typescript
134
58
  llm:
135
59
  model: ollama/llama4 # any litellm model string
136
- api_key: "" # or set REKIPEDIA_API_KEY env var
60
+ api_key: "" # or REKIPEDIA_API_KEY env var
137
61
  base_url: "" # for local / self-hosted endpoints
138
62
  temperature: 0.2
139
63
  ```
140
64
 
141
- ### Supported providers (via [litellm](https://docs.litellm.ai))
65
+ Supported providers: Ollama, OpenAI, Anthropic, Gemini, any OpenAI-compatible endpoint.
142
66
 
143
- | Provider | Example model string |
144
- |---|---|
145
- | Ollama (local, free) | `ollama/llama4` |
146
- | OpenAI | `gpt-5.5` |
147
- | Anthropic | `claude-opus-4-6` |
148
- | Google Gemini | `gemini/gemini-3.0-pro` |
149
- | Any OpenAI-compatible | set `base_url` in config |
150
-
151
- ### Runtime overrides (env vars)
152
-
153
- ```bash
154
- export REKIPEDIA_MODEL=gpt-5.5
155
- export REKIPEDIA_API_KEY=sk-...
156
- export REKIPEDIA_BASE_URL=https://my-proxy/v1
157
- export REKIPEDIA_SHARD_TOKEN_BUDGET=40000
158
- ```
159
-
160
- | Variable | Description |
161
- |---|---|
162
- | `REKIPEDIA_MODEL` | LLM model name to use |
163
- | `REKIPEDIA_API_KEY` | API key for the LLM provider |
164
- | `REKIPEDIA_BASE_URL` | Base URL for OpenAI-compatible endpoints |
165
- | `REKIPEDIA_SHARD_TOKEN_BUDGET` | Max tokens per shard group (default: 40000) |
166
- | `REKIPEDIA_AGENT_ASK` | Set to `1` to enable agentic ReAct ask loop (default: `0` — single-shot) |
167
- | `REKIPEDIA_ASK_MAX_ITER` | Max tool-call iterations for agentic ask (default: `5`) |
168
- | `REKIPEDIA_AGENT_PLANNER` | Set to `1` to enable tool-calling wiki planner (default: `0`) |
67
+ Key env vars: `REKIPEDIA_MODEL`, `REKIPEDIA_API_KEY`, `REKIPEDIA_BASE_URL`
169
68
 
170
69
  ---
171
70
 
172
- ## Output
173
-
174
- `rekipedia scan` writes everything to `.rekipedia/` inside your repo:
71
+ ## Output layout
175
72
 
176
73
  ```
177
74
  .rekipedia/
178
- ├── config.yml # your settings (committed)
179
- ├── store.db # SQLite knowledge store (git-ignored)
180
- ├── scan_meta.json # last scan metadata (model, timestamp, file count)
181
- ├── wiki/ # generated Markdown pages (3–15 pages, dynamically planned)
182
- │ ├── index.md
183
- │ ├── architecture-overview.md
184
- │ ├── repository-structure.md
185
- │ └── ... (pages vary by repo)
186
- ├── rag/ # RAG index (git-ignored)
187
- │ ├── index.faiss # FAISS flat L2 index
188
- │ └── chunks.json # source code chunks + metadata
189
- ├── diagrams/ # Mermaid diagram files
190
- │ ├── module-graph.md
191
- │ └── class-hierarchy.md
192
- └── exports/ # JSON exports
193
- ├── symbols.json
194
- ├── relationships.json
195
- └── manifest.json # run summary + metadata + page importance scores
75
+ ├── config.yml # settings (committed)
76
+ ├── store.db # SQLite knowledge store (git-ignored)
77
+ ├── wiki/ # generated Markdown pages
78
+ ├── rag/ # FAISS index + chunks (git-ignored)
79
+ ├── diagrams/ # Mermaid diagrams
80
+ └── exports/ # JSON exports + manifest
196
81
  ```
197
82
 
198
- Dynamically generates 3–15 wiki pages based on repo complexity (powered by PlannerAgent).
199
-
200
- The wiki structure is designed dynamically by `PlannerAgent` based on what's actually present in your repo:
201
-
202
- | Section | Example pages | When generated |
203
- |---|---|---|
204
- | Getting Started | index, installation, quick-start | Always |
205
- | Architecture | architecture-overview, data-flow, repository-structure | ≥3 modules |
206
- | Core Components | One page per major module | ≥2 modules |
207
- | API Reference | cli-reference, python-api, rest-api | CLI/HTTP handlers found |
208
- | Development | testing, contributing, ci-cd | Test files found |
209
- | Ecosystem | integrations, deployment | ≥3 external deps |
210
-
211
- ### Scan options
212
-
213
- ```bash
214
- # Use a specific LLM model
215
- rekipedia scan . --model gpt-5.5
216
-
217
- # Skip Docker (run extractors in-process)
218
- rekipedia scan . --no-docker
219
-
220
- # Write output to a custom directory
221
- rekipedia scan . --output-dir /tmp/wiki-output
222
-
223
- # Enable debug logging (litellm, HTTP, full tracebacks)
224
- rekipedia scan . --verbose
225
-
226
- # Auto-embed for RAG after scan
227
- rekipedia scan . --embed-model text-embedding-3-small --embed-provider openai
228
- ```
229
-
230
- ### RAG / semantic search
231
-
232
- `rekipedia ask` uses **hybrid retrieval** — wiki pages + FAISS-indexed code chunks — to answer questions with full codebase context.
233
-
234
- ```bash
235
- # Build or rebuild the FAISS index
236
- rekipedia embed .
237
-
238
- # Custom embedding model + provider
239
- rekipedia embed . --model text-embedding-3-small --provider openai
240
- rekipedia embed . --model nomic-embed-text --provider ollama
241
-
242
- # If your embed provider uses a DIFFERENT API key from your main LLM:
243
- rekipedia embed . --model text-embedding-3-small --provider openai
244
- # set embed_api_key in config.yml, or:
245
- export REKIPEDIA_EMBED_API_KEY=sk-your-openai-key
246
-
247
- # Or configure everything in .rekipedia/config.yml:
248
- # llm:
249
- # model: ollama/llama4 # main LLM (local)
250
- # embed_model: text-embedding-3-small
251
- # embed_provider: openai
252
- # embed_api_key: sk-xxx # separate key for embed provider
253
- # embed_base_url: "" # optional: custom endpoint
254
-
255
- # Env var overrides (all optional):
256
- export REKIPEDIA_EMBED_MODEL=nomic-embed-text
257
- export REKIPEDIA_EMBED_PROVIDER=ollama
258
- export REKIPEDIA_EMBED_API_KEY=sk-xxx
259
- export REKIPEDIA_EMBED_BASE_URL=https://my-proxy.example.com/v1
260
- ```
261
-
262
- The FAISS index is saved to `.rekipedia/rag/index.faiss` and chunked source code to `.rekipedia/rag/chunks.json`.
263
-
264
- ### Export the wiki
265
-
266
- ```bash
267
- # Single combined Markdown file (default)
268
- rekipedia export . --format md --output ./wiki-export.md
269
-
270
- # ZIP archive (one .md per page + manifest.json)
271
- rekipedia export . --format zip --output ./wiki.zip
272
-
273
- # Structured JSON (all pages + metadata)
274
- rekipedia export . --format json --output ./wiki.json
275
- ```
276
-
277
- ### Incremental update
278
-
279
- After the first scan, `rekipedia update` only re-processes files whose SHA-256 has changed. Unchanged symbols and relationships are carried forward from the previous run — the wiki is refreshed in seconds.
280
-
281
- ```bash
282
- rekipedia update . # auto-detect changed files
283
- rekipedia update . --no-docker # skip Docker
284
- ```
285
-
286
- If no previous scan is found, `update` automatically falls back to a full scan.
287
-
288
- ### Ask the wiki
289
-
290
- ```bash
291
- # Start interactive Q&A session (streams answers, Ctrl+C to quit)
292
- rekipedia ask
293
- rekipedia ask --repo ./my-project
294
- rekipedia ask --model gpt-4o
295
-
296
- # Single-shot mode (backward compat)
297
- rekipedia ask -q "How does the auth flow work?"
298
- ```
299
-
300
- Answers are grounded **entirely** in your wiki pages and symbol index — the LLM cannot hallucinate details that aren't in the scanned knowledge store. Answers are streamed token-by-token with a spinner while waiting.
301
-
302
- Not happy with a generated page? See **[docs/customizing.md](docs/customizing.md)** — you can pin pages, override prompts, change the writing style, or add your own pages that scans will never touch.
303
-
304
- ### Serve the wiki
305
-
306
- ```bash
307
- rekipedia serve . # opens browser at http://127.0.0.1:7070
308
- rekipedia serve . --port 8080 # custom port
309
- rekipedia serve . --no-browser # don't auto-open browser
310
- ```
311
-
312
- - Browse generated wiki pages in a dark-themed web UI
313
- - Ask questions with the same grounded Q&A (answers streamed via the web)
314
- - Q&A history stored in SQLite
315
-
316
- ---
317
-
318
- ## Prerequisites
319
-
320
- - **Python ≥ 3.11** (or `uv` which manages its own Python)
321
- - **Docker** — optional; used for isolated extraction. Falls back to in-process runner automatically if Docker is not available (`--no-docker` forces in-process mode)
322
-
323
- ---
324
-
325
- ## Using rekipedia with AI coding agents
326
-
327
- rekipedia ships a **Hermes agent skill** (`rekipedia-agent-skill.md`) that teaches AI assistants (Copilot, Claude Code, Codex) to use rekipedia as their codebase intelligence layer:
328
-
329
- 1. Copy `rekipedia-agent-skill.md` into your Hermes skills directory
330
- 2. Any agent with the skill loaded will automatically scan + query rekipedia before diving into source files
331
- 3. Dramatically reduces context window usage for large codebases
332
-
333
83
  ---
334
84
 
335
- ## Agentic Mode
336
-
337
- rekipedia supports an experimental agentic mode where LLM calls use tool-calling (ReAct) instead of single large context dumps.
338
-
339
- ### Agentic Ask
85
+ ## Python API
340
86
 
341
- Set `REKIPEDIA_AGENT_ASK=1` to enable:
87
+ ```python
88
+ import rekipedia
342
89
 
343
- ```bash
344
- REKIPEDIA_AGENT_ASK=1 reki ask "How does authentication work?"
90
+ result = rekipedia.scan("/path/to/repo")
91
+ answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
92
+ print(answer.text)
93
+ for c in answer.citations:
94
+ print(f" {c.file}:{c.line}")
345
95
  ```
346
96
 
347
- The LLM issues tool calls to retrieve information on demand:
348
- - `search_code(query)` — semantic search over source code
349
- - `get_symbol(name)` — look up symbol location and signature
350
- - `get_page(slug)` — fetch a wiki page on demand
351
- - `get_relationships(target)` — dependency graph for a symbol/file
352
- - `finish(answer)` — provide final answer
353
-
354
- Max iterations can be configured with `REKIPEDIA_ASK_MAX_ITER` (default: 5).
355
-
356
- ### Agentic Planner
97
+ Async variants: `rekipedia.scan_async()`, `rekipedia.ask_async()`
357
98
 
358
- Set `REKIPEDIA_AGENT_PLANNER=1` to enable tool-calling wiki structure planning:
359
-
360
- ```bash
361
- REKIPEDIA_AGENT_PLANNER=1 reki scan .
362
- ```
363
-
364
- The planner builds the wiki structure incrementally using tool calls instead of generating a single large JSON response.
99
+ ---
365
100
 
366
101
  ## Development
367
102
 
368
103
  ```bash
369
- # Install all deps
370
- make dev
371
-
372
- # Run tests
373
- make test
374
-
375
- # Lint
376
- make lint
377
-
378
- # Build wheel + npm tarball
379
- make build
380
- ```
381
-
382
- ### Release
383
-
384
- ```bash
385
- PYPI_TOKEN=*** NPM_TOKEN=*** make release
386
-
387
- # Full release: build + tag + push + PyPI + npm
388
- make release-all PYPI_TOKEN=*** NPM_TOKEN=***
389
- # With version bump
390
- make release-all PYPI_TOKEN=*** NPM_TOKEN=*** VERSION=0.5.0
104
+ make dev # install deps
105
+ make test # run tests
106
+ make lint # lint
107
+ make build # wheel + npm tarball
391
108
  ```
392
109
 
393
110
  ---
@@ -395,6 +112,3 @@ make release-all PYPI_TOKEN=*** NPM_TOKEN=*** VERSION=0.5.0
395
112
  ## License
396
113
 
397
114
  Proprietary and Confidential — Copyright © 2026 Eddie Chan. All Rights Reserved.
398
-
399
- Unauthorized copying, distribution, or modification of this software is strictly prohibited.
400
- See [LICENSE](LICENSE) for details.
package/README.zh-CN.md ADDED
@@ -0,0 +1,402 @@
1
+ # rekipedia
2
+
3
+ **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
4
+
5
+ > 您的 AI 技术负责人——随时在线，始终最新。
6
+
7
+ rekipedia 可扫描任意代码仓库，将其转化为便携的 SQLite 知识库，让团队中的每位开发者都拥有一个由 LLM 驱动的技术负责人，可以随时询问：_"认证流程是如何运作的？"、"添加一个新 API 端点最快的方式是什么？"、"上周是什么导致了支付服务故障？"_
8
+
9
+ 零幻觉，零猜测——每个答案都基于您的真实代码库。
10
+
11
+ ### 核心功能
12
+ - **关系置信度评分**：每个提取的关系均标记为 EXTRACTED/INFERRED/AMBIGUOUS，并附带置信度分数
13
+ - **设计意图提取**：`# NOTE:`、`# HACK:`、`# WHY:` 注释被提取为知识节点
14
+ - **God 节点**：度数最高的符号会在 index.md 中呈现，并在图形界面中高亮显示
15
+ - **交互式依赖关系图**：`rekipedia serve` 现已包含 `/graph` 路由，提供基于 D3.js 的力导向可视化
16
+ - **Git 钩子**：`rekipedia hook install` 可在每次提交时触发自动重建
17
+ - **智能 wiki 编排**：`PlannerAgent` 根据您的仓库动态设计 wiki 结构
18
+ - **页面重要性评分**：规划器为每个页面分配重要性分数（0–100），导航侧边栏按优先级排序
19
+ - **DeepWiki 风格分节**：页面按逻辑分节分组（`getting-started`、`architecture`、`core-components` 等）
20
+ - **Wiki 侧边栏分类**：`reki serve` 侧边栏按 `section` 字段分组，支持折叠标题
21
+ - **实时搜索**：在侧边栏搜索框中输入内容，可即时按标题或分类筛选 wiki 页面
22
+ - **重构分析**：`reki refactor` 检测代码异味（上帝类、循环依赖、死代码、高耦合），并提供 LLM 增强建议——输出 `REFACTOR.md` + `refactor_report.json`
23
+ - **上下文切片**：每个页面仅接收其所需的数据（相比固定布局方式减少约 40–60% 的 token 用量）
24
+ - **混合 RAG 问答**：FAISS 索引的代码块 + wiki 页面为 LLM 提供完整的代码库上下文以回答问题
25
+ - **嵌入模型提供商选择**：`--embed-provider openai|ollama|azure|...`——支持任何兼容 litellm 的嵌入模型
26
+ - **Wiki 导出**：打包为单个 Markdown 文件、ZIP 压缩包或结构化 JSON（`rekipedia export`）
27
+ - **增量更新**：首次扫描后仅重新处理已变更的文件
28
+ - **有据可查的问答**：答案引用真实的文件路径和行号——零幻觉
29
+ - **代码库树形索引**——每次扫描在 SQLite 中构建层级目录/文件树，支持结构化导航和未来基于推理的检索。
30
+
31
+ ## 快速开始
32
+
33
+ ### 通过 npm / npx（无需安装）
34
+
35
+ ```bash
36
+ npx rekipedia init .
37
+ npx rekipedia scan .
38
+ ```
39
+
40
+ ### 通过 uv / uvx（无需安装）
41
+
42
+ ```bash
43
+ uvx rekipedia init .
44
+ uvx rekipedia scan .
45
+ ```
46
+
47
+ ### 永久安装
48
+
49
+ ```bash
50
+ # Core (scan + serve + ask)
51
+ pip install rekipedia
52
+ # or
53
+ uv tool install rekipedia
54
+
55
+ # With RAG support (semantic embed + search — needs faiss-cpu + numpy ~100MB)
56
+ pip install "rekipedia[rag]"
57
+
58
+ # Homebrew (Go single binary — no Python needed)
59
+ brew tap unrealandychan/tap
60
+ brew install rekipedia
61
+ ```
62
+
63
+ ---
64
+
65
+ ## Python API
66
+
67
+ 在 Jupyter Notebook、CI 流水线或任意 Python 应用中以编程方式使用 rekipedia：
68
+
69
+ ```python
70
+ import rekipedia
71
+
72
+ # Scan a local repo
73
+ result = rekipedia.scan("/path/to/repo")
74
+ print(result.page_count) # number of wiki pages generated
75
+ print(result.symbol_count) # number of code symbols extracted
76
+ print(result.token_count) # estimated token count of the wiki
77
+
78
+ # Ask a question — grounded answer with file:line citations
79
+ answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
80
+ print(answer.text)
81
+ for citation in answer.citations:
82
+ print(f" {citation.file}:{citation.line}")
83
+
84
+ # Async variants (Jupyter-friendly)
85
+ result = await rekipedia.scan_async("/path/to/repo")
86
+ answer = await rekipedia.ask_async("/path/to/repo", "What is the entry point?")
87
+ ```
88
+
89
+ **返回类型：**
90
+
91
+ | Type | Key fields |
92
+ |---|---|
93
+ | `ScanResult` | `page_count`, `symbol_count`, `token_count`, `wiki_pages`, `db_path`, `wiki_dir` |
94
+ | `AskResult` | `text`, `citations: list[Citation]`, `model_used` |
95
+ | `Citation` | `file`, `line`, `snippet` |
96
+
97
+ ---
98
+
99
+ ## 命令
100
+
101
+ | Command | Description |
102
+ |---|---|
103
+ | `rekipedia init [REPO]` | Scaffold `.rekipedia/` with `config.yml` and update `.gitignore` |
104
+ | `rekipedia scan [REPO]` | Full analysis — extracts symbols, synthesises wiki pages, exports JSON |
105
+ | `rekipedia update [REPO]` | Incremental refresh — re-extracts only changed files, keeps the rest |
106
+ | `rekipedia ask [QUESTION]` | Interactive Q&A REPL — streaming answers, Ctrl+C to quit |
107
+ | `rekipedia serve [REPO]` | Start a local web UI to browse wiki pages and ask questions |
108
+ | `rekipedia embed [REPO]` | Build (or rebuild) the FAISS semantic search index for hybrid RAG Q&A |
109
+ | `rekipedia export [REPO]` | Bundle the wiki to a single file (`--format md\|zip\|json`) |
110
+ | `rekipedia hook install/uninstall/status` | Manage git post-commit hook for auto wiki rebuild |
111
+ | `rekipedia diff [A] [B]` | Compare two graph snapshots (defaults to last two) |
112
+ | `rekipedia impact <file>` | Show blast-radius — all affected files, symbols, tests for a changed file |
113
+ | `rekipedia search <query>` | Search symbols (`--all-repos` for cross-repo parallel search) |
114
+ | `rekipedia export --format graphml\|cypher\|obsidian` | Export graph to GraphML / Neo4j Cypher / Obsidian wikilinks |
115
+ | `rekipedia mcp` | Start JSON-RPC 2.0 MCP stdio server (6 tools for AI coding assistants) |
116
+ | `rekipedia watch add\|start\|list\|remove` | Watch repos and auto-index on file change |
117
+ | `rekipedia refactor [REPO]` | Detect code smells + generate `REFACTOR.md` and `refactor_report.json` (use `--no-llm` for static only) |
118
+ | `rekipedia note add\|list\|remove\|edit\|import` | Manage persistent tech lead notes — injected into `reki ask` context automatically |
119
+
120
+ ---
121
+
122
+ ## LLM 配置
123
+
124
+ 运行 `rekipedia init` 后，编辑 `.rekipedia/config.yml`：
125
+
126
+ ```yaml
127
+ version: 1
128
+ ignore:
129
+ - .git
130
+ - node_modules
131
+ - __pycache__
132
+ - .rekipedia
133
+ languages:
134
+ - python
135
+ - typescript
136
+ llm:
137
+ model: ollama/llama4 # any litellm model string
138
+ api_key: "" # or set REKIPEDIA_API_KEY env var
139
+ base_url: "" # for local / self-hosted endpoints
140
+ temperature: 0.2
141
+ ```
142
+
143
+ ### 支持的提供商（通过 [litellm](https://docs.litellm.ai)）
144
+
145
+ | Provider | Example model string |
146
+ |---|---|
147
+ | Ollama (local, free) | `ollama/llama4` |
148
+ | OpenAI | `gpt-5.5` |
149
+ | Anthropic | `claude-opus-4-6` |
150
+ | Google Gemini | `gemini/gemini-3.0-pro` |
151
+ | Any OpenAI-compatible | set `base_url` in config |
152
+
153
+ ### 运行时覆盖（环境变量）
154
+
155
+ ```bash
156
+ export REKIPEDIA_MODEL=gpt-5.5
157
+ export REKIPEDIA_API_KEY=***
158
+ export REKIPEDIA_BASE_URL=https://my-proxy/v1
159
+ export REKIPEDIA_SHARD_TOKEN_BUDGET=***
160
+ ```
161
+
162
+ | Variable | Description |
163
+ |---|---|
164
+ | `REKIPEDIA_MODEL` | LLM model name to use |
165
+ | `REKIPEDIA_API_KEY` | API key for the LLM provider |
166
+ | `REKIPEDIA_BASE_URL` | Base URL for OpenAI-compatible endpoints |
167
+ | `REKIPEDIA_SHARD_TOKEN_BUDGET` | Max tokens per shard group (default: 40000) |
168
+ | `REKIPEDIA_AGENT_ASK` | Set to `1` to enable agentic ReAct ask loop (default: `0` — single-shot) |
169
+ | `REKIPEDIA_ASK_MAX_ITER` | Max tool-call iterations for agentic ask (default: `5`) |
170
+ | `REKIPEDIA_AGENT_PLANNER` | Set to `1` to enable tool-calling wiki planner (default: `0`) |
171
+
172
+ ---
173
+
174
+ ## 输出
175
+
176
+ `rekipedia scan` 将所有内容写入仓库内的 `.rekipedia/` 目录：
177
+
178
+ ```
179
+ .rekipedia/
180
+ ├── config.yml # your settings (committed)
181
+ ├── store.db # SQLite knowledge store (git-ignored)
182
+ ├── scan_meta.json # last scan metadata (model, timestamp, file count)
183
+ ├── wiki/ # generated Markdown pages (3–15 pages, dynamically planned)
184
+ │ ├── index.md
185
+ │ ├── architecture-overview.md
186
+ │ ├── repository-structure.md
187
+ │ └── ... (pages vary by repo)
188
+ ├── rag/ # RAG index (git-ignored)
189
+ │ ├── index.faiss # FAISS flat L2 index
190
+ │ └── chunks.json # source code chunks + metadata
191
+ ├── diagrams/ # Mermaid diagram files
192
+ │ ├── module-graph.md
193
+ │ └── class-hierarchy.md
194
+ └── exports/ # JSON exports
195
+ ├── symbols.json
196
+ ├── relationships.json
197
+ └── manifest.json # run summary + metadata + page importance scores
198
+ ```
199
+
200
+ 根据仓库复杂度动态生成 3–15 个 wiki 页面（由 PlannerAgent 驱动）。
201
+
202
+ wiki 结构由 `PlannerAgent` 根据仓库实际内容动态设计：
203
+
204
+ | Section | Example pages | When generated |
205
+ |---|---|---|
206
+ | Getting Started | index, installation, quick-start | Always |
207
+ | Architecture | architecture-overview, data-flow, repository-structure | ≥3 modules |
208
+ | Core Components | One page per major module | ≥2 modules |
209
+ | API Reference | cli-reference, python-api, rest-api | CLI/HTTP handlers found |
210
+ | Development | testing, contributing, ci-cd | Test files found |
211
+ | Ecosystem | integrations, deployment | ≥3 external deps |
212
+
213
+ ### 扫描选项
214
+
215
+ ```bash
216
+ # Use a specific LLM model
217
+ rekipedia scan . --model gpt-5.5
218
+
219
+ # Skip Docker (run extractors in-process)
220
+ rekipedia scan . --no-docker
221
+
222
+ # Write output to a custom directory
223
+ rekipedia scan . --output-dir /tmp/wiki-output
224
+
225
+ # Enable debug logging (litellm, HTTP, full tracebacks)
226
+ rekipedia scan . --verbose
227
+
228
+ # Auto-embed for RAG after scan
229
+ rekipedia scan . --embed-model text-embedding-3-small --embed-provider openai
230
+ ```
231
+
232
+ ### RAG / 语义搜索
233
+
234
+ `rekipedia ask` 使用**混合检索**——wiki 页面 + FAISS 索引的代码块——在完整代码库上下文中回答问题。
235
+
236
+ ```bash
237
+ # Build or rebuild the FAISS index
238
+ rekipedia embed .
239
+
240
+ # Custom embedding model + provider
241
+ rekipedia embed . --model text-embedding-3-small --provider openai
242
+ rekipedia embed . --model nomic-embed-text --provider ollama
243
+
244
+ # If your embed provider uses a DIFFERENT API key from your main LLM:
245
+ rekipedia embed . --model text-embedding-3-small --provider openai
246
+ # set embed_api_key in config.yml, or:
247
+ export REKIPEDIA_EMBED_API_KEY=***
248
+
249
+ # Or configure everything in .rekipedia/config.yml:
250
+ # llm:
251
+ # model: ollama/llama4 # main LLM (local)
252
+ # embed_model: text-embedding-3-small
253
+ # embed_provider: openai
254
+ # embed_api_key: sk-xxx # separate key for embed provider
255
+ # embed_base_url: "" # optional: custom endpoint
256
+
257
+ # Env var overrides (all optional):
258
+ export REKIPEDIA_EMBED_MODEL=nomic-embed-text
259
+ export REKIPEDIA_EMBED_PROVIDER=ollama
260
+ export REKIPEDIA_EMBED_API_KEY=***
261
+ export REKIPEDIA_EMBED_BASE_URL=https://my-proxy.example.com/v1
262
+ ```
263
+
264
+ FAISS 索引保存至 `.rekipedia/rag/index.faiss`，分块后的源代码保存至 `.rekipedia/rag/chunks.json`。
265
+
266
+ ### 导出 wiki
267
+
268
+ ```bash
269
+ # Single combined Markdown file (default)
270
+ rekipedia export . --format md --output ./wiki-export.md
271
+
272
+ # ZIP archive (one .md per page + manifest.json)
273
+ rekipedia export . --format zip --output ./wiki.zip
274
+
275
+ # Structured JSON (all pages + metadata)
276
+ rekipedia export . --format json --output ./wiki.json
277
+ ```
278
+
279
+ ### 增量更新
280
+
281
+ 首次扫描后，`rekipedia update` 仅重新处理 SHA-256 已发生变化的文件。未变更的符号和关系将从上次运行中延续——wiki 可在数秒内完成刷新。
282
+
283
+ ```bash
284
+ rekipedia update . # auto-detect changed files
285
+ rekipedia update . --no-docker # skip Docker
286
+ ```
287
+
288
+ 若未找到之前的扫描记录，`update` 会自动回退至全量扫描。
289
+
290
+ ### 询问 wiki
291
+
292
+ ```bash
293
+ # Start interactive Q&A session (streams answers, Ctrl+C to quit)
294
+ rekipedia ask
295
+ rekipedia ask --repo ./my-project
296
+ rekipedia ask --model gpt-4o
297
+
298
+ # Single-shot mode (backward compat)
299
+ rekipedia ask -q "How does the auth flow work?"
300
+ ```
301
+
302
+ 答案**完全**基于您的 wiki 页面和符号索引——LLM 无法虚构扫描知识库中不存在的内容。答案以逐 token 流式方式输出，等待时显示进度指示器。
303
+
304
+ 对某个生成页面不满意？请参阅 **[docs/customizing.md](docs/customizing.md)**——您可以固定页面、覆盖提示词、更改写作风格，或添加扫描永不触碰的自定义页面。
305
+
306
+ ### 启动 wiki 服务
307
+
308
+ ```bash
309
+ rekipedia serve . # opens browser at http://127.0.0.1:7070
310
+ rekipedia serve . --port 8080 # custom port
311
+ rekipedia serve . --no-browser # don't auto-open browser
312
+ ```
313
+
314
+ - 在深色主题的 Web 界面中浏览生成的 wiki 页面
315
+ - 使用相同的有据可查问答功能提问（答案通过 Web 流式返回）
316
+ - 问答历史记录存储于 SQLite
317
+
318
+ ---
319
+
320
+ ## 前置要求
321
+
322
+ - **Python ≥ 3.11**（或使用 `uv`，它自行管理 Python 环境）
323
+ - **Docker**——可选；用于隔离提取。若 Docker 不可用，将自动回退至进程内运行模式（`--no-docker` 强制使用进程内模式）
324
+
325
+ ---
326
+
327
+ ## 与 AI 编程智能体配合使用
328
+
329
+ rekipedia 附带一个 **Hermes agent skill**（`rekipedia-agent-skill.md`），可教会 AI 助手（Copilot、Claude Code、Codex）将 rekipedia 作为其代码库智能层：
330
+
331
+ 1. 将 `rekipedia-agent-skill.md` 复制到您的 Hermes skills 目录
332
+ 2. 任何已加载该 skill 的智能体都将在深入源文件之前自动扫描并查询 rekipedia
333
+ 3. 显著降低大型代码库的上下文窗口用量
334
+
335
+ ---
336
+
337
+ ## 智能体模式
338
+
339
+ rekipedia 支持实验性智能体模式，其中 LLM 调用使用工具调用（ReAct）而非单次大上下文输入。
340
+
341
+ ### 智能体问答
342
+
343
+ 设置 `REKIPEDIA_AGENT_ASK=1` 以启用：
344
+
345
+ ```bash
346
+ REKIPEDIA_AGENT_ASK=1 reki ask "How does authentication work?"
347
+ ```
348
+
349
+ LLM 按需发出工具调用以检索信息：
350
+ - `search_code(query)` — 对源代码进行语义搜索
351
+ - `get_symbol(name)` — 查找符号位置和签名
352
+ - `get_page(slug)` — 按需获取 wiki 页面
353
+ - `get_relationships(target)` — 获取符号/文件的依赖关系图
354
+ - `finish(answer)` — 提供最终答案
355
+
356
+ 最大迭代次数可通过 `REKIPEDIA_ASK_MAX_ITER` 配置（默认值：5）。
357
+
358
+ ### 智能体规划器
359
+
360
+ 设置 `REKIPEDIA_AGENT_PLANNER=1` 以启用工具调用式 wiki 结构规划：
361
+
362
+ ```bash
363
+ REKIPEDIA_AGENT_PLANNER=1 reki scan .
364
+ ```
365
+
366
+ 规划器通过工具调用逐步构建 wiki 结构，而非生成单个大型 JSON 响应。
367
+
368
+ ## 开发
369
+
370
+ ```bash
371
+ # Install all deps
372
+ make dev
373
+
374
+ # Run tests
375
+ make test
376
+
377
+ # Lint
378
+ make lint
379
+
380
+ # Build wheel + npm tarball
381
+ make build
382
+ ```
383
+
384
+ ### 发布
385
+
386
+ ```bash
387
+ PYPI_TOKEN=*** NPM_TOKEN=*** make release
388
+
389
+ # Full release: build + tag + push + PyPI + npm
390
+ make release-all PYPI_TOKEN=*** NPM_TOKEN=***
391
+ # With version bump
392
+ make release-all PYPI_TOKEN=*** NPM_TOKEN=*** VERSION=0.5.0
393
+ ```
394
+
395
+ ---
396
+
397
+ ## 许可证
398
+
399
+ 专有且保密——版权所有 © 2026 Eddie Chan。保留所有权利。
400
+
401
+ 未经授权，严禁复制、分发或修改本软件。
402
+ 详情请参阅 [LICENSE](LICENSE)。
package/README.zh-TW.md ADDED
@@ -0,0 +1,402 @@
1
+ # rekipedia
2
+
3
+ **[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)**
4
+
5
+ > 您的 AI 技術領導——隨時待命，永遠最新。
6
+
7
+ rekipedia 能掃描任何程式碼庫，將其轉化為可攜式的 SQLite 知識庫，並為團隊中每位開發者提供一位由 LLM 驅動的技術領導，讓他們隨時提問：_「驗證流程是如何運作的？」、「新增 API 端點最快的方法是什麼？」、「上週付款服務是什麼出了問題？」_
8
+
9
+ 不會產生幻覺，不靠猜測——每個答案都紮根於您實際的程式碼庫。
10
+
11
+ ### 主要功能
12
+ - **關係可信度評分**：每個提取的關係都標記為 EXTRACTED/INFERRED/AMBIGUOUS，並附有可信度分數
13
+ - **設計原理提取**：`# NOTE:`、`# HACK:`、`# WHY:` 注釋會被提取為知識節點
14
+ - **核心節點（God nodes）**：連結度最高的符號會顯示於 index.md 並在圖表介面中高亮標示
15
+ - **互動式依賴關係圖**：`rekipedia serve` 現在包含一個使用 D3.js 力導向視覺化的 `/graph` 路由
16
+ - **Git hooks**：`rekipedia hook install` 會在每次提交時觸發自動重建
17
+ - **代理式 wiki 協作**：`PlannerAgent` 根據您的程式碼庫動態設計 wiki 結構
18
+ - **頁面重要性評分**：規劃器為每個頁面分配重要性分數（0–100）；導航側邊欄依優先級排序
19
+ - **DeepWiki 式章節**：頁面分組至邏輯章節（`getting-started`、`architecture`、`core-components` 等）
20
+ - **Wiki 側邊欄分類**：`reki serve` 側邊欄依 `section` 欄位將頁面分組，並支援可折疊標頭
21
+ - **即時搜尋**：在側邊欄搜尋框中輸入，即可立即按標題或分類篩選 wiki 頁面
22
+ - **重構分析**：`reki refactor` 偵測程式碼異味（神類、循環依賴、死碼、高耦合），並提供 LLM 增強的建議——輸出 `REFACTOR.md` + `refactor_report.json`
23
+ - **上下文切片**：每個頁面只接收其所需的資料（相較固定佈局方式減少約 40–60% 的 token 用量）
24
+ - **混合式 RAG 問答**：FAISS 索引的程式碼片段 + wiki 頁面，讓 LLM 在回答問題時擁有完整的程式碼庫上下文
25
+ - **嵌入提供者選擇**：`--embed-provider openai|ollama|azure|...`——支援任何 litellm 相容的嵌入模型
26
+ - **Wiki 匯出**：打包為單一 Markdown 檔案、ZIP 壓縮包或結構化 JSON（`rekipedia export`）
27
+ - **增量更新**：初次掃描後僅重新處理已變更的檔案
28
+ - **有依據的問答**：答案引用真實的檔案路徑和行號——不產生幻覺
29
+ - **程式碼庫樹狀索引**——每次掃描都會在 SQLite 中建立階層式目錄/檔案樹，支援結構化導航與未來基於推理的檢索。
30
+
31
+ ## 快速開始
32
+
33
+ ### 透過 npm / npx（無需安裝）
34
+
35
+ ```bash
36
+ npx rekipedia init .
37
+ npx rekipedia scan .
38
+ ```
39
+
40
+ ### 透過 uv / uvx（無需安裝）
41
+
42
+ ```bash
43
+ uvx rekipedia init .
44
+ uvx rekipedia scan .
45
+ ```
46
+
47
+ ### 永久安裝
48
+
49
+ ```bash
50
+ # Core (scan + serve + ask)
51
+ pip install rekipedia
52
+ # or
53
+ uv tool install rekipedia
54
+
55
+ # With RAG support (semantic embed + search — needs faiss-cpu + numpy ~100MB)
56
+ pip install "rekipedia[rag]"
57
+
58
+ # Homebrew (Go single binary — no Python needed)
59
+ brew tap unrealandychan/tap
60
+ brew install rekipedia
61
+ ```
62
+
63
+ ---
64
+
65
+ ## Python API
66
+
67
+ 在 Jupyter 筆記本、CI 流水線或任何 Python 應用程式中以程式化方式使用 rekipedia：
68
+
69
+ ```python
70
+ import rekipedia
71
+
72
+ # Scan a local repo
73
+ result = rekipedia.scan("/path/to/repo")
74
+ print(result.page_count) # number of wiki pages generated
75
+ print(result.symbol_count) # number of code symbols extracted
76
+ print(result.token_count) # estimated token count of the wiki
77
+
78
+ # Ask a question — grounded answer with file:line citations
79
+ answer = rekipedia.ask("/path/to/repo", "How does the auth flow work?")
80
+ print(answer.text)
81
+ for citation in answer.citations:
82
+ print(f" {citation.file}:{citation.line}")
83
+
84
+ # Async variants (Jupyter-friendly)
85
+ result = await rekipedia.scan_async("/path/to/repo")
86
+ answer = await rekipedia.ask_async("/path/to/repo", "What is the entry point?")
87
+ ```
88
+
89
+ **回傳型別：**
90
+
91
+ | Type | Key fields |
92
+ |---|---|
93
+ | `ScanResult` | `page_count`, `symbol_count`, `token_count`, `wiki_pages`, `db_path`, `wiki_dir` |
94
+ | `AskResult` | `text`, `citations: list[Citation]`, `model_used` |
95
+ | `Citation` | `file`, `line`, `snippet` |
96
+
97
+ ---
98
+
99
+ ## 指令
100
+
101
+ | Command | Description |
102
+ |---|---|
103
+ | `rekipedia init [REPO]` | Scaffold `.rekipedia/` with `config.yml` and update `.gitignore` |
104
+ | `rekipedia scan [REPO]` | Full analysis — extracts symbols, synthesises wiki pages, exports JSON |
105
+ | `rekipedia update [REPO]` | Incremental refresh — re-extracts only changed files, keeps the rest |
106
+ | `rekipedia ask [QUESTION]` | Interactive Q&A REPL — streaming answers, Ctrl+C to quit |
107
+ | `rekipedia serve [REPO]` | Start a local web UI to browse wiki pages and ask questions |
108
+ | `rekipedia embed [REPO]` | Build (or rebuild) the FAISS semantic search index for hybrid RAG Q&A |
109
+ | `rekipedia export [REPO]` | Bundle the wiki to a single file (`--format md\|zip\|json`) |
110
+ | `rekipedia hook install/uninstall/status` | Manage git post-commit hook for auto wiki rebuild |
111
+ | `rekipedia diff [A] [B]` | Compare two graph snapshots (defaults to last two) |
112
+ | `rekipedia impact <file>` | Show blast-radius — all affected files, symbols, tests for a changed file |
113
+ | `rekipedia search <query>` | Search symbols (`--all-repos` for cross-repo parallel search) |
114
+ | `rekipedia export --format graphml\|cypher\|obsidian` | Export graph to GraphML / Neo4j Cypher / Obsidian wikilinks |
115
+ | `rekipedia mcp` | Start JSON-RPC 2.0 MCP stdio server (6 tools for AI coding assistants) |
116
+ | `rekipedia watch add\|start\|list\|remove` | Watch repos and auto-index on file change |
117
+ | `rekipedia refactor [REPO]` | Detect code smells + generate `REFACTOR.md` and `refactor_report.json` (use `--no-llm` for static only) |
118
+ | `rekipedia note add\|list\|remove\|edit\|import` | Manage persistent tech lead notes — injected into `reki ask` context automatically |
119
+
120
+ ---
121
+
122
+ ## LLM 設定
123
+
124
+ 執行 `rekipedia init` 後，編輯 `.rekipedia/config.yml`：
125
+
126
+ ```yaml
127
+ version: 1
128
+ ignore:
129
+ - .git
130
+ - node_modules
131
+ - __pycache__
132
+ - .rekipedia
133
+ languages:
134
+ - python
135
+ - typescript
136
+ llm:
137
+ model: ollama/llama4 # any litellm model string
138
+ api_key: "" # or set REKIPEDIA_API_KEY env var
139
+ base_url: "" # for local / self-hosted endpoints
140
+ temperature: 0.2
141
+ ```
142
+
143
+ ### 支援的提供者（透過 [litellm](https://docs.litellm.ai)）
144
+
145
+ | Provider | Example model string |
146
+ |---|---|
147
+ | Ollama (local, free) | `ollama/llama4` |
148
+ | OpenAI | `gpt-5.5` |
149
+ | Anthropic | `claude-opus-4-6` |
150
+ | Google Gemini | `gemini/gemini-3.0-pro` |
151
+ | Any OpenAI-compatible | set `base_url` in config |
152
+
153
+ ### 執行時覆寫（環境變數）
154
+
155
+ ```bash
156
+ export REKIPEDIA_MODEL=gpt-5.5
157
+ export REKIPEDIA_API_KEY=***
158
+ export REKIPEDIA_BASE_URL=https://my-proxy/v1
159
+ export REKIPEDIA_SHARD_TOKEN_BUDGET=***
160
+ ```
161
+
162
+ | Variable | Description |
163
+ |---|---|
164
+ | `REKIPEDIA_MODEL` | LLM model name to use |
165
+ | `REKIPEDIA_API_KEY` | API key for the LLM provider |
166
+ | `REKIPEDIA_BASE_URL` | Base URL for OpenAI-compatible endpoints |
167
+ | `REKIPEDIA_SHARD_TOKEN_BUDGET` | Max tokens per shard group (default: 40000) |
168
+ | `REKIPEDIA_AGENT_ASK` | Set to `1` to enable agentic ReAct ask loop (default: `0` — single-shot) |
169
+ | `REKIPEDIA_ASK_MAX_ITER` | Max tool-call iterations for agentic ask (default: `5`) |
170
+ | `REKIPEDIA_AGENT_PLANNER` | Set to `1` to enable tool-calling wiki planner (default: `0`) |
171
+
172
+ ---
173
+
174
+ ## 輸出
175
+
176
+ `rekipedia scan` 會將所有內容寫入您程式碼庫內的 `.rekipedia/`：
177
+
178
+ ```
179
+ .rekipedia/
180
+ ├── config.yml # your settings (committed)
181
+ ├── store.db # SQLite knowledge store (git-ignored)
182
+ ├── scan_meta.json # last scan metadata (model, timestamp, file count)
183
+ ├── wiki/ # generated Markdown pages (3–15 pages, dynamically planned)
184
+ │ ├── index.md
185
+ │ ├── architecture-overview.md
186
+ │ ├── repository-structure.md
187
+ │ └── ... (pages vary by repo)
188
+ ├── rag/ # RAG index (git-ignored)
189
+ │ ├── index.faiss # FAISS flat L2 index
190
+ │ └── chunks.json # source code chunks + metadata
191
+ ├── diagrams/ # Mermaid diagram files
192
+ │ ├── module-graph.md
193
+ │ └── class-hierarchy.md
194
+ └── exports/ # JSON exports
195
+ ├── symbols.json
196
+ ├── relationships.json
197
+ └── manifest.json # run summary + metadata + page importance scores
198
+ ```
199
+
200
+ 根據程式碼庫複雜度動態生成 3–15 個 wiki 頁面（由 PlannerAgent 驅動）。
201
+
202
+ Wiki 結構由 `PlannerAgent` 根據您程式碼庫的實際內容動態設計：
203
+
204
+ | Section | Example pages | When generated |
205
+ |---|---|---|
206
+ | Getting Started | index, installation, quick-start | Always |
207
+ | Architecture | architecture-overview, data-flow, repository-structure | ≥3 modules |
208
+ | Core Components | One page per major module | ≥2 modules |
209
+ | API Reference | cli-reference, python-api, rest-api | CLI/HTTP handlers found |
210
+ | Development | testing, contributing, ci-cd | Test files found |
211
+ | Ecosystem | integrations, deployment | ≥3 external deps |
212
+
213
+ ### 掃描選項
214
+
215
+ ```bash
216
+ # Use a specific LLM model
217
+ rekipedia scan . --model gpt-5.5
218
+
219
+ # Skip Docker (run extractors in-process)
220
+ rekipedia scan . --no-docker
221
+
222
+ # Write output to a custom directory
223
+ rekipedia scan . --output-dir /tmp/wiki-output
224
+
225
+ # Enable debug logging (litellm, HTTP, full tracebacks)
226
+ rekipedia scan . --verbose
227
+
228
+ # Auto-embed for RAG after scan
229
+ rekipedia scan . --embed-model text-embedding-3-small --embed-provider openai
230
+ ```
231
+
232
+ ### RAG / 語義搜尋
233
+
234
+ `rekipedia ask` 使用**混合式檢索**——wiki 頁面 + FAISS 索引的程式碼片段——以完整的程式碼庫上下文回答問題。
235
+
236
+ ```bash
237
+ # Build or rebuild the FAISS index
238
+ rekipedia embed .
239
+
240
+ # Custom embedding model + provider
241
+ rekipedia embed . --model text-embedding-3-small --provider openai
242
+ rekipedia embed . --model nomic-embed-text --provider ollama
243
+
244
+ # If your embed provider uses a DIFFERENT API key from your main LLM:
245
+ rekipedia embed . --model text-embedding-3-small --provider openai
246
+ # set embed_api_key in config.yml, or:
247
+ export REKIPEDIA_EMBED_API_KEY=***
248
+
249
+ # Or configure everything in .rekipedia/config.yml:
250
+ # llm:
251
+ # model: ollama/llama4 # main LLM (local)
252
+ # embed_model: text-embedding-3-small
253
+ # embed_provider: openai
254
+ # embed_api_key: sk-xxx # separate key for embed provider
255
+ # embed_base_url: "" # optional: custom endpoint
256
+
257
+ # Env var overrides (all optional):
258
+ export REKIPEDIA_EMBED_MODEL=nomic-embed-text
259
+ export REKIPEDIA_EMBED_PROVIDER=ollama
260
+ export REKIPEDIA_EMBED_API_KEY=***
261
+ export REKIPEDIA_EMBED_BASE_URL=https://my-proxy.example.com/v1
262
+ ```
263
+
264
+ FAISS 索引儲存於 `.rekipedia/rag/index.faiss`，分塊的原始碼儲存於 `.rekipedia/rag/chunks.json`。
265
+
266
+ ### 匯出 wiki
267
+
268
+ ```bash
269
+ # Single combined Markdown file (default)
270
+ rekipedia export . --format md --output ./wiki-export.md
271
+
272
+ # ZIP archive (one .md per page + manifest.json)
273
+ rekipedia export . --format zip --output ./wiki.zip
274
+
275
+ # Structured JSON (all pages + metadata)
276
+ rekipedia export . --format json --output ./wiki.json
277
+ ```
278
+
279
+ ### 增量更新
280
+
281
+ 初次掃描後，`rekipedia update` 只會重新處理 SHA-256 已變更的檔案。未變更的符號和關係會從上次執行中延續——wiki 可在幾秒內完成更新。
282
+
283
+ ```bash
284
+ rekipedia update . # auto-detect changed files
285
+ rekipedia update . --no-docker # skip Docker
286
+ ```
287
+
288
+ 若找不到先前的掃描記錄，`update` 會自動回退至完整掃描。
289
+
290
+ ### 向 wiki 提問
291
+
292
+ ```bash
293
+ # Start interactive Q&A session (streams answers, Ctrl+C to quit)
294
+ rekipedia ask
295
+ rekipedia ask --repo ./my-project
296
+ rekipedia ask --model gpt-4o
297
+
298
+ # Single-shot mode (backward compat)
299
+ rekipedia ask -q "How does the auth flow work?"
300
+ ```
301
+
302
+ 答案**完全**以您的 wiki 頁面和符號索引為依據——LLM 無法捏造不存在於已掃描知識庫中的細節。答案以逐 token 串流方式輸出，等待時會顯示進度指示器。
303
+
304
+ 對某個生成頁面不滿意？請參閱 **[docs/customizing.md](docs/customizing.md)**——您可以釘選頁面、覆寫提示詞、更改寫作風格，或新增掃描時永遠不會觸及的自訂頁面。
305
+
306
+ ### 啟動 wiki 伺服器
307
+
308
+ ```bash
309
+ rekipedia serve . # opens browser at http://127.0.0.1:7070
310
+ rekipedia serve . --port 8080 # custom port
311
+ rekipedia serve . --no-browser # don't auto-open browser
312
+ ```
313
+
314
+ - 在深色主題的網頁介面中瀏覽生成的 wiki 頁面
315
+ - 使用相同的有依據問答功能提問（答案透過網頁串流）
316
+ - 問答歷史記錄儲存於 SQLite
317
+
318
+ ---
319
+
320
+ ## 環境需求
321
+
322
+ - **Python ≥ 3.11**（或使用 `uv`，它自行管理 Python 版本）
323
+ - **Docker**——可選；用於隔離式提取。若 Docker 不可用，會自動回退至行程內執行模式（`--no-docker` 強制使用行程內模式）
324
+
325
+ ---
326
+
327
+ ## 搭配 AI 程式碼代理使用 rekipedia
328
+
329
+ rekipedia 附帶一個 **Hermes agent skill**（`rekipedia-agent-skill.md`），可教導 AI 助理（Copilot、Claude Code、Codex）將 rekipedia 作為其程式碼庫智慧層：
330
+
331
+ 1. 將 `rekipedia-agent-skill.md` 複製到您的 Hermes skills 目錄
332
+ 2. 任何已載入該技能的代理，都會在深入原始碼檔案前自動掃描並查詢 rekipedia
333
+ 3. 大幅減少大型程式碼庫的上下文視窗用量
334
+
335
+ ---
336
+
337
+ ## 代理模式
338
+
339
+ rekipedia 支援實驗性的代理模式，其中 LLM 呼叫使用工具調用（ReAct）而非單次大型上下文傾倒。
340
+
341
+ ### 代理式提問
342
+
343
+ 設定 `REKIPEDIA_AGENT_ASK=1` 以啟用：
344
+
345
+ ```bash
346
+ REKIPEDIA_AGENT_ASK=1 reki ask "How does authentication work?"
347
+ ```
348
+
349
+ LLM 會發出工具調用以按需取得資訊：
350
+ - `search_code(query)` — 對原始碼進行語義搜尋
351
+ - `get_symbol(name)` — 查詢符號的位置和簽名
352
+ - `get_page(slug)` — 按需取得 wiki 頁面
353
+ - `get_relationships(target)` — 取得符號/檔案的依賴關係圖
354
+ - `finish(answer)` — 提供最終答案
355
+
356
+ 最大迭代次數可透過 `REKIPEDIA_ASK_MAX_ITER` 設定（預設值：5）。
357
+
358
+ ### 代理式規劃器
359
+
360
+ 設定 `REKIPEDIA_AGENT_PLANNER=1` 以啟用工具調用式 wiki 結構規劃：
361
+
362
+ ```bash
363
+ REKIPEDIA_AGENT_PLANNER=1 reki scan .
364
+ ```
365
+
366
+ 規劃器使用工具調用增量建構 wiki 結構，而非生成單一大型 JSON 回應。
367
+
368
+ ## 開發
369
+
370
+ ```bash
371
+ # Install all deps
372
+ make dev
373
+
374
+ # Run tests
375
+ make test
376
+
377
+ # Lint
378
+ make lint
379
+
380
+ # Build wheel + npm tarball
381
+ make build
382
+ ```
383
+
384
+ ### 發佈
385
+
386
+ ```bash
387
+ PYPI_TOKEN=*** NPM_TOKEN=*** make release
388
+
389
+ # Full release: build + tag + push + PyPI + npm
390
+ make release-all PYPI_TOKEN=*** NPM_TOKEN=***
391
+ # With version bump
392
+ make release-all PYPI_TOKEN=*** NPM_TOKEN=*** VERSION=0.5.0
393
+ ```
394
+
395
+ ---
396
+
397
+ ## 授權條款
398
+
399
+ 專有且機密——版權所有 © 2026 Eddie Chan。保留所有權利。
400
+
401
+ 嚴禁未經授權複製、散布或修改本軟體。
402
+ 詳情請參閱 [LICENSE](LICENSE)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rekipedia",
3
- "version": "0.15.1",
3
+ "version": "0.17.17",
4
4
  "description": "Agentic repo-to-wiki: scan any repository into a portable SQLite knowledge store with wiki pages, diagrams, and grounded Q&A.",
5
5
  "bin": {
6
6
  "rekipedia": "./bin/rekipedia.js"
@@ -27,4 +27,4 @@
27
27
  "bugs": {
28
28
  "url": "https://github.com/unrealandychan/rekipedia/issues"
29
29
  }
30
- }
30
+ }