homegraph 1.4.1 → 1.5.0

package/README.md

@@ -15,7 +15,7 @@
 
 ### 1. 安装 CLI
 
-需要 **Node.js 22.5+**（推荐 22 LTS 或 24）。HomeGraph 使用 Node 内置的 `node:sqlite`，22.5 以下无法运行。
+需要 **Node.js 20+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5），否则 `better-sqlite3`，再不行回退 `node-sqlite3-wasm`。
 
 ```bash
 npm install -g homegraph
@@ -147,9 +147,15 @@ homegraph callers <符号>        # 谁调用了它
 homegraph callees <符号>        # 它调用了谁
 homegraph impact <符号>         # 修改该符号的影响范围
 homegraph affected [files...]  # 根据变更文件查找受影响的测试（支持 --stdin）
-homegraph spec mine            # 从 Git 历史挖掘规格知识图谱（Commit4Spec）
-homegraph spec match <文本>     # 搜索相似历史规格
-homegraph spec evolve install  # 安装 post-commit 钩子，提交后自动演化规格
+homegraph spec build           # 从已有 .spec 目录（或用户指定目录）构建Spec知识图谱（Commit4Spec）
+homegraph spec mine            # 从 Git 历史挖掘设计Spec文档（AST 分析 + LLM 聚类生成）
+homegraph spec match <文本>     # 全文搜索相似历史Spec
+homegraph spec find <文件>      # 查找与指定文件关联的Spec
+homegraph spec trace <符号>     # 追溯代码符号关联的Spec
+homegraph spec stats           # 查看Spec知识图谱状态
+homegraph spec evolve install  # 安装 post-commit 钩子（默认累计 3 次提交后触发演进）
+homegraph spec evolve uninstall# 移除 post-commit 钩子
+homegraph spec evolve process  # 手动触发一次Spec演化
 homegraph serve --mcp           # 启动 MCP 服务（一般由 Agent 自动拉起）
 ```
 
@@ -174,16 +180,47 @@ Agent 侧工具名前缀为 `homegraph_`。
 | `homegraph_impact` | 变更影响分析（重构前使用） |
 | `homegraph_files` | 已索引的文件树（支持 glob 过滤、按语言分组） |
 | `homegraph_status` | 索引健康状态（调试用） |
-| `homegraph_spec_match` | 将新需求描述与 Commit4Spec 规格知识图谱做全文匹配，返回相似历史规格及关联提交与代码片段 |
+| `homegraph_spec_match` | 将新需求描述与 Commit4Spec 知识图谱做全文匹配，返回相似历史Spec及关联提交与代码片段 |
+| `homegraph_spec_find` | 根据文件路径反向查找关联的Spec |
+| `homegraph_spec_trace` | 根据代码符号追溯回关联的Spec |
 
-### Commit4Spec（规格知识图谱）
+### Commit4Spec（Spec知识图谱）
 
-`homegraph_spec_match` 与 `homegraph spec` 子命令基于 Commit4Spec：从 Git 历史中的 `.spec` 目录反向挖掘规格、提交与代码片段，存入 `.homegraph/commit4spec/commit4spec.db`。典型流程：
+Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `.homegraph/commit4spec/commit4spec.db`：
+
+**路径 1：`spec build`（已有Spec导入）**
+
+从项目已有的 `.spec` 目录（或用户指定目录）读取Spec文档，解析其中的 Git 引用和变更片段，直接构建知识图谱节点与关系。
+
+**路径 2：`spec mine`（Spec逆向挖掘）**
+
+从 Git 历史中自动提取设计Spec，基于模型生成对应 `.spec` 文档，进而构建知识图谱节点与关系。
+
+支持增量模式（`meta.json` 记录已处理范围）、commit过滤和聚类输出模式（`--skip-llm`）。
+
+`spec mine`逆向挖掘和`spec evolve process`演化更新涉及到模型访问，优先选择用户本地已有的Agent平台（Claude Code >> Codex >> 用户配置LLM），若未安装Claude Code或Codex，则需用户自主配置模型服务，编辑配置文件`.homegraph/commit4spec/configs.json`
+
+```json
+// All available options (fields marked * are required):
+{
+  "llm": {
+    "provider":     "openai",          // * "openai" or "anthropic"
+    "apiKey":       "sk-...",          // * API key string (plain text)
+    "apiKeyEnv":   "OPENAI_API_KEY",   //   or read from env var (takes precedence)
+    "model":        "gpt-4o",          // * model name (e.g. gpt-4o, claude-3-5-sonnet)
+    "baseUrl":      "https://...",     //   custom endpoint (proxies / local models)
+    "temperature":  0.2,               //   creativity control (default: 0.2)
+    "maxTokens":    20000              //   max output tokens (default: 20000)
+  }
+}
+```
+
+**查询与分析：**
 
 ```bash
-homegraph spec mine              # 首次挖掘
-homegraph spec match "用户登录"   # CLI 侧搜索（与 MCP spec_match 相同能力）
-homegraph spec evolve install    # 可选：每次 commit 后自动更新规格图谱
+homegraph spec match "用户登录"    # CLI/MCP 全文搜索
+homegraph spec find src/auth.ts   # 哪些Spec涉及该文件
+homegraph spec trace UserService  # 追溯符号关联的设计Spec
 ```
 
 ---
@@ -257,7 +294,7 @@ Cursor 等项目级配置写入 `./.cursor/mcp.json`，格式相同。推荐使
 
 ## 环境要求
 
-- Node.js **22.5+**（推荐 22 LTS 或 24；使用 Node 内置 `node:sqlite`）
+- Node.js **20+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → better-sqlite3 → wasm）
 - 首次索引时会对项目源码做 AST 解析，大型仓库首次 `init -i` 可能需要数分钟
 - WSL2 下若项目位于 Windows 盘符（`/mnt/c` 等）且 MCP 连接不稳定，可设置 `HOMEGRAPH_NO_DAEMON=1` 跳过共享后台服务，每个会话独立运行