homegraph 1.5.2 → 1.5.4

package/CHANGELOG.md

@@ -0,0 +1,156 @@
+# Changelog
+
+All notable changes to HomeGraph are documented here. Each entry also ships as
+a [GitCode Release](https://gitcode.com/ProgramAnalysis/homegraph) tagged
+`vX.Y.Z`, which is where most people will look.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+
+## [1.5.4] - 2026-08-19
+
+### Breaking Changes
+
+- Require Node.js **22+** (`engines: >=22`). Node 18–21 are no longer supported; the CLI hard-exits below major 22. Dependencies that were pinned for Node 18 are restored: `commander@^14`, `@clack/prompts@^1.7`, optional `better-sqlite3@^12`. Use `npm run test:node-matrix` (nvm) to exercise majors 22–25 locally.
+
+### New Features
+
+- Docs hub at `docs/README.md` plus a short `docs/RELEASE.md` for publishing [`homegraph`](https://www.npmjs.com/package/homegraph) (Actions), GitCode releases, and mirror checks — without duplicating DEVELOPMENT SDD.
+- Explore better matches common survey shapes (data-source, Event→handler, multi-Type deps, resource/preview, NAPI) with honest **Partial** vs **ANSWER NOW**, so agents get anchors without fake-complete dumps that trigger Grep storms.
+- Startup MCP instructions are a shorter locator playbook: how to write `query`, when to stop after explore, and when to Skip — without long low-salience essays.
+- Repeated or near-duplicate `homegraph_explore` bags are guarded so agents do not spin on the same keyword paraphrase.
+- New `homegraph addon` command group installs and manages pluggable addons (`init`, `install`, `list`, `remove`, `enable`, `disable`, `update`) from npm packages or local paths. Addons extend `homegraph spec mine` with external requirement context — e.g. map commit messages to Jira tickets and inject the fetched details into the spec-generation prompt — without HomeGraph knowing any ticket format. Enrichment runs per commit cluster with per-addon timeouts and failure isolation, so a broken addon never blocks spec generation.
+- `homegraph addon` version policy: re-installing a registered addon refuses **downgrades** (`remove` first), upgrades preserve the previous version and **restore it when the new one fails validation**, and `update --latest` forces the newest published version (registry packages only — local-path installs have no dist-tag). Applies to npm packages and local-path installs alike.
+
+### Fixes
+
+- `homegraph_arkui_migrate` no longer materializes every `class`/`struct` to find `@Observed` types: it walks scope state-var `observed-ref` edges and scoped files only, so large Harmony repos stop timing out on migrate snapshots.
+- Explore default is **universal mid-lean**: **Anchors** (`symbol` → `file:line`) first, ≤2 spine digests (~12K ceiling, ~3K/file), Relationships off. Partial **Next anchor** ranks domain Manager inventory by query-token overlap + CJK→ASCII domain stems (digests prefer that file) — e.g. 通知订阅 → SubscribeManager over screenlock StateManager, 备份 → Extension over EventManager; when inventory + digest are enough, explore **soft-closes** with matching **Coarse locate — ANSWER** header+footer (no Partial/ANSWER contradiction). Session fuse: ≤2 explores; after Partial, follow-ups must name the Next anchor (no novel-Type bypass); callers/callees refused; ≤1 `homegraph_node`. A second Partial appends a hard stop footer. Qualified `Type.member` callers no longer fall back to every bare `member`. ArkTS: synthesize `commonEventManager` publish↔subscribe (literal event) and `taskpool.execute`→named worker. Skip: chained layout literals (`.width('…')`) and pure C-API “which callback” catalogs. Set `HOMEGRAPH_EXPLORE_FULL_SOURCE=1` for the prior body-heavy dump. Cross-Type “如何驱动 / 状态变化” questions no longer collapse into compact hard-ANSWER-NOW; `homegraph_callers` steers Type-wide inventory instead of per-method fan-out.
+- ArkTS indexing no longer `realpathSync`s every ArkAnalyzer path on the hot path: the project root is canonicalized once per batch, then relative paths are string-stripped (with a cached realpath fallback when prefixes disagree) — restoring Storing speed on large Harmony repos while keeping macOS `/var`↔`/private/var` and symlink-root correctness.
+- Multi-term locator bags (e.g. `item` + `service`) are no longer misrouted into light-mechanism just because `service` is a generic noun, so corroboration / full explore ranking can still surface the matching backend file.
+- Renamed the language-verification guide (was `SEARCH_QUALITY_LOOP.md`) and archived settled design notes under `docs/design/archive/` so the docs tree is easier to navigate.
+
+## [1.5.3] - 2026-08-11
+
+### New Features
+
+- Ported selected post-1.5.0 CodeGraph fixes (through upstream `c6aaa20`): incremental **sync rebind** so long-lived indexes stop drifting from a fresh rebuild (`HOMEGRAPH_NO_REBIND=1` to opt out); **explore session dedup** so a follow-up `homegraph_explore` points at source already returned instead of re-sending it (`HOMEGRAPH_EXPLORE_DEDUP=0` to opt out); **stale-slice guards** so node/explore never serve a wrong body when a file changed on disk after the last sync; **WAL self-heal** on open when a killed session left an oversized write-ahead log (`homegraph status` reports WAL size); and explore **ranking/budget fairness** (generated-file banners, top-level `test/`/`spec/` demotion, ambient `.d.ts` down-rank, fair per-file budgets, long-function windows, note-first truncation).
+- ArkTS ↔ C/C++ NAPI bridging recognizes more registration styles (camelCase `napi_property_descriptor` rows, `napi_define_class` / `napi_define_sendable_class`, `DECLARE_NAPI_*` macros, `napi_create_function`, and `.c` `NAPI_MODULE` modules), not only photos-style `Class_method` names, so `homegraph_explore` can follow calls through `lib*.so` into native wrappers (and a conservative same-file `NapiFoo` → `Foo` hop when safe). ArkTS extraction also emits call refs for camelCase methods on `lib*.so` imports (e.g. `multimodalinput.getTidByName`), not only `Class_method` names.
+- `homegraph_arkui_migrate` returns a one-shot ArkUI migrate / state-semantics snapshot (component decorators, state fields + decorator args, data-passage types, Provide/Consume/Storage key channels, `@Observed` classes) for a component name or `.ets` path — so agents need not stitch those facts with explore.
+- MCP can limit which graphs answer queries via `--sources both|project|sdk|none` on `homegraph serve mcp` (or `HOMEGRAPH_SOURCES`; CLI wins). Default remains **both** (project index + OHOS SDK API db when bound). Use `project` / `sdk` for eval arms; `none` leaves tools registered but returns guidance. Different sources use separate daemon sockets so arms do not share state. `homegraph status` / `homegraph_status` report the active mode.
+
+- Node.js **18+** is supported again (`engines: >=18.0.0`), and **Node 25+** is no longer hard-blocked. Tree-sitter WASM Zone OOM on Node ≥22 (including 25+) continues to be mitigated by the `--liftoff-only` relaunch. Prefer Node 22.5+ for built-in `node:sqlite`. Optional `better-sqlite3` is pinned to 11.x so Node 18 can still use a native WAL backend when the addon builds; otherwise SQLite falls back to wasm. CLI prompts use `@clack/prompts@1.0.0` (avoids Node 20+ `util.styleText`). Use `npm run test:node-matrix` (nvm) to exercise majors 18–25 locally.
+- MCP tools now **short-circuit unsuitable question shapes** (topic file-lists, concept/existence/UI-behavior compares without named symbols, SDK/`@kit` feature catalogs): `homegraph_explore` / `homegraph_search` return a short **Skip HomeGraph** note instead of a large graph dump, and tell the agent not to retry. Startup instructions list these skip shapes (shape-driven, not corpus-specific), clarify that in-repo `@kit` **usages** are explore-first (opposite of SDK catalogs), and prefer **lean tools** (`callers` / `node` before a full explore).
+- In-repo `@kit`/`@ohos` **usage** questions no longer get misclassified as `Type.member` (dotted module paths), so explore returns the usage inventory instead of falling through. Compact explore for `Type.member` expands callers on the **member** across packages and surfaces text use sites, so UI-marking questions need fewer Grep/Read follow-ups.
+- `@kit.X的foo` named-export focus is extracted structurally so usage inventories list only matching import sites (full list, ANSWER NOW) instead of dumping every import from a popular kit module. Light mechanism explore seeds distinctive-token imports first (skips SDK stubs) so how-wired answers cover real convert/parse entry files without a Grep/Read loop.
+- Hover/悬停 questions without a named Type soft-skip (including agent-rewritten bags), named UI controls with hover/click go through compact explore (not light-mechanism), `Type.member` compact prefers the member owned by the named Type, and generic NL nouns (`dialog`/`application`/…) no longer inflate focused-anchor counts.
+- Hover/悬停 without a named Type now returns an **onHover / Hover\*** handler inventory (soft-skip→Grep was losing accuracy). Named Page/Component overviews (`ThemeHome`, UI children / navigation) render the full component body in compact explore instead of a bare-id callers stub + self-reference noise.
+- `Type.member` compact explore now **prioritizes the defining package** when scanning text call sites (large monorepos no longer miss nearby `Type.member` filters), surfaces those sites + their source, and tells the agent not to follow up with Grep/`homegraph_callers`.
+- Multi-Type UI composition bags (`*Page` + `*Dialog`, embed/preview/load) stay on **compact explore**: framework decorator names (`@CustomDialog`) are ignored as anchors, co-located Types rank first, and a short Flow no longer kicks the bag into a full related-file dump.
+- Cross-cutting **usage inventories** now own more shapes before Grep: named Type declaration/id sites, `.member` / DrawContext-style API hunts, ALL_CAPS constant scenarios, field/mutex co-use, and path-module NAPI/export or inter-deps. Named Type **state/lifecycle** questions keep a full-body compact path instead of a thin callers stub.
+- Compact explore is leaner for Page/Component surfaces and `Type.member`: prefer `build`/`aboutToAppear` digests (+imports) over whole-struct dumps, tighter char caps, trail-only neighbors for surface questions, and a harder **ANSWER NOW / do not Read-search-again** footer so agents stop stacking a second HomeGraph call.
+- Page/Dialog surface digests now emit **per-method** chunks (`build` / `PageMap` / preview helpers) plus a short **UI/nav inventory**, instead of one aboutToAppear→build window that always trimmed before the answer. Bare type names with no subtypes no longer return an empty inheritance **ANSWER NOW** (that blocked definition/visibility follows like `IntGrid`). C++ subtype lists prefer **public** inheritance. Empty `homegraph_callers` falls back to compact body + use sites for callback-style symbols.
+- API-usage inventories recognize English agent rewrites (`API usages` / `call methods in the project`), expand `Telephony`→`@ohos.telephony`, prefer project files over `.d.ts` stubs, and skip the compact-on-`usages` dead end. UI surface inventories add **Image/preview load** cues; `homegraph_callers` appends include/import lines at call sites for visibility questions; Manager **data-source** answers no longer prepend unrelated badge import floods.
+- Shape routing (agent-rewrite resilient): system-setting **howto** stays a lean `@ohos`/System call inventory (not a light-mechanism dump of every `language` import); **declaration/id/binding** surveys recognize English rewrites; **return-value consumers** become member callers (not create→get flow); PascalCase API bags drop `call`/`radio` noise; compact seeds prefer in-repo defs over SDK `.d.ts`; named-Type **NAPI expose** works without a path segment. Startup instructions call out `.drawModifier` / Kit-deps / return-value / declaration shapes.
+- Step/download→parse→install questions ("会走到哪些代码") route to **light mechanism**, not a domain file-list. Manager **data-source** inventories always keep same-file `@ohos`/`@kit` imports; API usage lists include one-line snippets so Telephony-style usage answers need fewer Grep/Read follow-ups.
+- MCP startup instructions now put **how/mechanism/wiring first**: call `homegraph_explore` immediately with the question or domain keywords (no Grep-first, no parallel Grep). Skip shapes stay listed second. Domain-term extraction keeps mixed ASCII tokens like `xml` so light-mechanism explore can seed without PascalCase names.
+- `homegraph_explore` no longer lets rewritten mechanism bags like `xml parse` collapse into a **compact `parse`-method dump** (that missed `convertxml` and forced Grep/Read). Light-mechanism runs before compact; generic verbs (`parse`/`load`/…) are not local-detail anchors or import-inventory filters, so Import sites follow distinctive tokens like `xml` instead of every `Parse*` notification helper.
+- `homegraph_explore` mechanism / "how is it implemented" answers stay compact (~12K ceiling, light-mechanism ~10K) and end with **ANSWER NOW — do not node/Read the same symbols**, so agents stop stacking a second explore + node + Read that used to inflate session tokens.
+
+### Breaking Changes
+
+- Standalone installers (`install.sh` / `install.ps1`) and self-contained platform bundles are retired. Install and upgrade with `npm i -g homegraph`; `homegraph upgrade` on a leftover bundle install refuses and points you at npm. `homegraph uninstall` still removes leftover bundle artifacts.
+- Anonymous usage telemetry is removed. HomeGraph no longer records or sends usage stats; `homegraph telemetry` and the installer share-stats prompt are gone. `DO_NOT_TRACK=1` still disables the background update check.
+
+### Fixes
+
+- SQLite no longer picks built-in `node:sqlite` when that Node build lacks **FTS5** (seen on Node 23.x). Selection probes FTS5 and falls through to `better-sqlite3` / wasm so `init` and indexing work again. Off-thread WAL checkpoint workers now open with the **same** backend as the main connection, so a native primary is not checkpointed via a mismatched `node:sqlite` handle.
+- `homegraph serve mcp --path <repo>` again honors `--path`. A nested Commander subcommand had been dropping it, so the shared daemon keyed off the process cwd instead of the project — MCP prewarm looked timed out and agents attached to the wrong index.
+- Explore inventories stop **wrong-tool fallthrough** that raised tokens and hurt accuracy: declaration-site surveys no longer become include-path "API usage" dumps; return-value consumers prefer the `通过/via` member (with text call-site fallback) instead of SDK `.d.ts` bodies; circular/`*common` module-dep questions get a lean cycle survey; `Type::method` and enum `Type.MEMBER` route as named anchors. Startup instructions match these shapes.
+- Field **new/delete** lifetime questions (`m_eglCore` …) route to a field usage inventory instead of seeding unrelated `new`/`delete` methods; `lib*.so` is not treated as a member access; GLES/EGL **thread** questions take light-mechanism (EGLCore/PluginRender); Type + listed methods (Set/Test/Fill) stay on that type's caller inventory; conditional `Export` fail wiring skips `logInfo` fan-out; API usage lists prefer call-site snippets over imports.
+- Field/mutex co-use inventories **seed scan files from co-named methods** when the field has no FTS hit (avoids a 20k dump); path-module **NAPI export** surveys replace domain file floods; module **cycle** surveys require two named leaf `*common` modules (not a shared parent path); named `.d.ts` wraps get import/call inventories; assigned-flag impact and Toggle state-sync stay on compact explore.
+- Wrong-route fixes that cut token↑ / accuracy↓: kit **extra-deps** and caller+**visibility** no longer lose to light-mechanism; Type + co-named PascalCase methods (`CanPlace`/`Place` ↔ owner Type) stay compact instead of a 13k mechanism dump; constants/fields prefer explore over Grep-first; kit surveys surface `oh-package` dep lines; listed-method caller inventories include a unique-file summary; flag/UI-cluster compact budgets are leaner.
+- Explore **route mutual-exclusion** hardened so inventory/member surveys cannot steal Type×method interaction, Export-fail wiring, or Release↔destructor compares; Manager **状态来源** goes to data-source inventory; repo-wide literal/`text` import hunts defer to Grep (never light); light-mechanism output capped leaner; system-language / hover / kit-deps prefer explore-first. Regression corpus lives under `test/explore-routing/` (`npm run test:explore-routing`; set `HOMEGRAPH_PROBE_ROOT` for live size checks).
+- Light-mechanism **XML howto** seeds `convertxml` / `XmlParseUtil` and caps import/source size so explore stays lean enough that agents need not stack Grep/Read.
+
+## [1.5.2] - 2026-08-05
+
+### New Features
+
+- MCP **`homegraph_diff_impact`**: pass a unified `diff` (or explicit `hunks`) to get a code-review evidence pack — only symbols whose spans intersect changed **new-side** lines, plus capped callers, impact summary, ArkUI/ViewTree UI edges, and optional Commit4Spec links (`includeSpecs`). Does not dump every symbol in touched files.
+- HarmonyOS / ArkTS `init`/`index` now builds the OHOS API db from a **local DevEco/OpenHarmony SDK** (via `OHOS_SDK_HOME` / `DEVECO_SDK_HOME` / `HOMEGRAPH_OHOS_SDK` or common install paths) into `~/.homegraph/api/` instead of downloading an npm package. Missing SDK still only warns — project indexing continues.
+
+### Fixes
+
+- MCP tools now treat recoverable bad arguments (missing/empty required fields, wrong types, oversize strings) as **success-shaped guidance with a retry example**, not `isError` — so agents fix the call instead of abandoning HomeGraph for the session. Tool descriptions and required-parameter docs were tightened to match. Security refusals and real faults still use `isError`.
+
+
+## [1.5.1] - 2026-07-30
+
+### Fixes
+
+- Large HarmonyOS / ArkTS projects no longer get killed mid-index with "Main thread unresponsive" while ArkAnalyzer is still building the Scene. That work is native and can block the event loop for well over a minute between modules on a big multi-module tree; the safety watchdog now pauses for the Scene build and arms again afterward, so a healthy index finishes without needing `HOMEGRAPH_NO_WATCHDOG` or a raised timeout. A genuinely stuck process outside that span is still caught as before.
+
+
+## [1.5.0] - 2026-07-27
+
+### New Features
+
+- Indexing and sync are substantially faster on large projects (ported from upstream CodeGraph 1.5.0 performance work, HomeGraph naming kept): adaptive watcher debounce with scoped path sync, WAL checkpoint deferral + valve, parallel reference resolution with memory-aware worker pools, fresh-DB store-writer offload, resolution memos / empty synthesis short-circuits, and batch-loop de-quadratic cleanup. Kill switches: `HOMEGRAPH_NO_WAL_DEFER`, `HOMEGRAPH_NO_FAST_INIT`, `HOMEGRAPH_NO_PARALLEL_RESOLVE`, `HOMEGRAPH_NO_STORE_WORKER`, `HOMEGRAPH_RESOLVE_WORKERS`, `HOMEGRAPH_WAL_VALVE_MB`.
+- Field-name explore/search queries (`profileInfo billingMethod` …) now surface the methods/files that define those fields instead of missing them (#1196).
+- ArkTS modular call graphs stay RTA-sparse under a memory budget: each Harmony module gets **intra-module RTA only** for normal calls (CFG same-module stitching is off — that was the ~150k `direct` flood past unlimited RTA). Cross-module edges come from RTA with an exact signature map. A CFG bridge recovers `%unk` invokes when HomeGraph can still read a name from the call site: short `Lib.use(...)` / `const x = Lib.use(...)` text, PascalCase invoke base, `UnclearReferenceType` class names (`b: Base` → `Base.foo`), or imported free functions (`getOpaque()`), always gated by import + unique indexed target and fan-out blocklists. No unresolved name-match call seeds. Deps stay at SIGNATURES; scene aggregator RTA stays skipped. Name-matcher gates remain: no bare exact/fuzzy, Strategy 1 same-file-or-import, same-file `instantiates`, ArkUI IR / stdlib seed drops.
+- Large HarmonyOS (multi-module) ArkTS projects index via ArkAnalyzer `analyseByModule` — each newly loaded module is the baseline for symbols + ViewTree + RTA, with cross-module edges resolved against still-resident deps or previously indexed `signature→nodeId` maps (so B→A still links after A is unloaded). When a dependency was already evicted, ViewTree stubs that still carry class/method signatures are linked through those maps (instead of dropping the edge). Unresolved stub signatures that still say `@%unk/... ComponentName` also fall back to the already-indexed component by class name (and the parent file's import when the name is ambiguous), so parent→child ViewTree edges survive type-inference gaps. Custom-view IR (`View.create`) is still emitted for imported PascalCase calls in `build`/`@Builder` even when the callee module was already unloaded (previously those became plain `staticinvoke` with no stitchable signature). ForEach / LazyForEach / Repeat item builders still expand when FunctionType was lost under eviction, as long as the local is an anonymous UI lambda (`%AM…` / `*$build`) — plain temp names are ignored so unrelated methods are not attached. Same-file children (e.g. `Item` inside `ForEach`) resolve even when the name is ambiguous project-wide, and a single bad ViewTree signature no longer aborts the rest of that class's child-component edges. Process RSS target is 4GB: V8 heap defaults to `--max-old-space-size=3584` (override `HOMEGRAPH_MAX_OLD_SPACE_MB`); Scene `memoryLimitMB` defaults to heap−256MB (override `HOMEGRAPH_ARKTS_MEMORY_LIMIT_MB`). Projects without `build-profile.json5` keep the previous full-Scene path.
+- HarmonyOS multi-module ArkTS sync can now re-index **only dirty modules** (via ArkAnalyzer `analyseByModule` target IDs) instead of rebuilding every PROJECT module when a `.ets` file changes. Unchanged modules stay in the graph; cross-file edges into the dirty module are re-bound. `build-profile.json5` / root `oh-package.json5` edits, or sources outside every module, still force a full ArkTS batch.
+- HomeGraph's MCP startup instructions and tool descriptions now lead with a **closed set of when to call** (in-repo structure, callers/callees, named-symbol wiring, Type.member usage, click→handler flows, in-repo `@kit` usages). Everything outside that set defaults to Read/Grep — no exhaustive "don't call for X/Y/Z" list.
+- `homegraph_explore` no longer treats property/event names like `isExpired` / `onClick` as **import-inventory** queries (that returned useless dependency lists and forced Grep). Named `Type.member` / UI-control+event questions take a **compact path**: definition + caller/callee trail + a few source windows.
+- `homegraph_explore` now keeps **local one-symbol / contract questions compact** (definition-focused windows, ~9K cap) and trims meta sections on no-flow answers — avoiding the previous ~24K related-file dump that often still led to extra grep/read.
+
+### Fixes
+
+- HarmonyOS / ArkTS indexing no longer walks `build/` (and other default-ignored dirs) when collecting `.ets` files for the Scene batch. That mismatch used to leave extra generated files in the index so non-git `homegraph status` reported Pending Removed right after a fresh `init`.
+- ArkTS Scene builds now run **in-process by default** (including large Windows repos). The isolated child + stack-size retry ladder is opt-in via `HOMEGRAPH_ARKTS_ISOLATED=1`, so `init`/`index` no longer burn minutes on failed isolated retries before users can get a working index.
+- SQLite picks a backend in order: built-in **`node:sqlite`** (Node 22.5+, real WAL), then **better-sqlite3**, then **node-sqlite3-wasm** as last resort so library hosts on older Node still work. `homegraph status` reports `node-sqlite`, `native`, or `wasm`. Override with `HOMEGRAPH_SQLITE_BACKEND`.
+- Type / caller inventory only fires on **real survey intent** (子类 / callers / methods…call). Bare PascalCase callbacks like `OnSurfaceChangedCB` no longer get classified as empty type-inventory (that skipped compact and dumped a 15K full explore). Long NL explore anchors are capped and path/verb noise (`cpp`, `calls`, `render`…) is dropped so neighbor fan-out cannot balloon tokens.
+- Caller surveys that also ask how a **second named type becomes visible/used** (definition visible / include / 定义可见) no longer stop at path-only caller inventory — they take compact explore (callers + bodies) so the agent does not Read/Grep to finish the answer.
+- PascalCase SDK module questions ("which methods does the project use on X") now take an **API usage inventory** instead of an empty class→callers list that fell through to "No relevant code found".
+- Bare-name `homegraph_search` / compact explore no longer fan out every callee neighbor into a multi-file dump (that ballooned token cost when agents search a single symbol). Caller-shaped answers stay on callers + the definition body.
+- On large indexes where catch-up sync is deferred for memory, the staleness banner no longer tells the agent to abandon homegraph and Read whole files for structural caller/def questions.
+- `homegraph_callers` / `homegraph_callees` / `homegraph_impact` no longer resolve an ambiguous name to the top FTS hit when no exact symbol matches — that could return callees of an unrelated function and force Grep/Read to recover.
+- `homegraph_callees` and compact explore call trails prefer **same-package** targets when those exist, so cross-package logger name collisions (`logError` / `logInfo`) do not drown the real upstream/downstream.
+- Type-name and method-caller questions answer from a **type surface inventory** first (subtypes + method→caller lists) when intent is clear. Inventory still runs before compact on explore/search.
+- `homegraph_explore` inheritance / subtype questions (子类, `subclass`, `extends Type`) no longer miss the compact survey because of a regex that matched only `subclasses` (not `subclass`), and no longer first FTS-search the words `extends`/`subclass` as import symbols — which previously fell through to a full explore and pushed large-index RSS into multi-GB.
+- HomeGraph tool calls no longer die as empty MCP client timeouts (~60s `-32001`) on large projects. Heavy tools (`explore` / impact) run on the worker pool with a soft deadline (default 15s, clamped ≤20s). Soft-timeout / tool-deadline callbacks return **static** success-shaped Partial guidance only — they never touch the DB or FTS on the transport thread (any sync work there can freeze the reply flush). Light tools (`search` / `node` / callers) stay on the already-warm main connection.
+- Compact explore for named members now adds **text usage sites** when the graph has no caller edges (common for static `Type.member(...)` reads) — a bounded scan of nearby indexed files — so agents do not need a Grep round-trip for those names.
+- Named-symbol explore/search answers on the warm main connection **before** the worker pool, so compact member questions are not lost to cold-worker / wedged-daemon empty MCP timeouts. Soft deadline default is **15s** (clamped ≤20s); the stdio↔daemon proxy also returns success-shaped Partial if the daemon does not answer in time.
+- ArkTS (HarmonyOS) indexing no longer requires a separate `arkanalyzer` install after `npm install -g homegraph`. The published bundle now ships the dependency automatically.
+- **DevEco Code:** `homegraph install` now writes the global MCP config to `~/.config/deveco` on every platform, including Windows. Earlier versions put it under `%APPDATA%\deveco`, which DevEco Code never reads — so a global install could look successful while DevEco saw no MCP server. Re-run `homegraph install --target=deveco --location=global` to fix an existing setup; stale entries under the old location are cleaned up automatically.
+
+
+## [1.4.1] - 2026-07-10
+
+### New Features
+
+- The MCP server now notices when a newer HomeGraph release exists and tells you — a long-running server used to drift behind releases silently until something broke. On startup it checks the latest release in the background (never blocking, at most once a day, cached across all servers on the machine) and surfaces a one-line "update available — run `homegraph upgrade`" notice in the server log, in the instructions your agent sees on connect, and in `homegraph_status`. Nothing updates by itself, and being offline just means no notice. Opt out with `HOMEGRAPH_NO_UPDATE_CHECK=1`; `DO_NOT_TRACK=1` disables it too. (#1243)
+
+### Fixes
+
+- `homegraph upgrade` on a Windows npm install actually runs npm again — modern Node refuses to launch `npm.cmd` directly, so the upgrade failed with a spawn error before doing anything. npm is now invoked the way a terminal would run it. (#1238)
+- `homegraph uninstall` now actually uninstalls HomeGraph. It used to remove only the agent configurations and leave every installed binary behind, so `homegraph` still ran afterward — especially confusing when both an npm global install and a standalone install were present and removing one still left the other answering on PATH. Uninstall now finds every install on the machine (the standalone bundle, the npm global package, the launcher link) and removes them all, after showing you exactly what it found and asking first (`--yes` skips the prompt). Machine-level settings like your telemetry choice are preserved, a source checkout is never touched, and the new `--keep-cli` flag restores the old configs-only behavior. (#1071)
+- `homegraph_explore` no longer lets ordinary English words in a natural-language question hijack the ranking when they happen to match a code symbol's name. A question like "how does the upgrade flow check the latest version" used to treat "check" as a symbol the agent asked for by name, rank that unrelated definition's file first, and crowd the files the question is actually about out of the answer entirely. Precisely written symbol names (camelCase, PascalCase, snake_case, qualified names) still get top billing exactly as before, as do plain-word symbol bags whose words belong together in the same file.
+- PHP method calls made through a class property — `$this->dep->method()`, the dominant call shape in constructor-injection codebases (Symfony, Laravel) — now resolve to the method on the property's declared type, so callers and impact analysis see production call sites instead of reporting a DI-heavy method as uncalled or test-only. Promoted constructor parameters, typed properties, classic constructor assignment (including multi-line signatures), and typed setter injection all count; interface-typed properties resolve to the interface method, and inherited methods resolve through the type hierarchy. Only property-shaped declarations are consulted — a same-named local variable or parameter elsewhere can never mistype the property — and a property whose type can't be recovered statically stays unlinked rather than guessed. Thanks @w0lan. (#1220)
+- `homegraph upgrade` now also refreshes what previous versions installed into your agents — the HomeGraph section in CLAUDE.md / AGENTS.md / GEMINI.md and the MCP entry — so upgrading no longer leaves agents following instructions written for tools that have since been renamed or removed. Refresh-only: agents you never configured are not touched, and your permission and hook choices are preserved. Also available manually as `homegraph install --refresh`, and skippable with `HOMEGRAPH_NO_INSTALL_REFRESH=1`. (#1238)
+- `homegraph upgrade` on an npm install now upgrades through npm again instead of quietly creating a second copy that never wins the PATH race — previously `homegraph --version` kept reporting the old version forever, no matter how many times you upgraded. (#1238)
+- After every upgrade, HomeGraph now checks that the `homegraph` command your terminal resolves actually serves the freshly installed version — confirming you don't need a new terminal, or telling you exactly which stale install is shadowing the new one. (#1071)
+- The safety watchdog no longer kills a healthy index on severely degraded storage. It used to judge liveness purely by the event loop, so one long database write on a struggling disk looked identical to a hung process and could get a valid, in-progress index terminated. During `homegraph index`/`homegraph init` the watchdog now also checks whether the index files on disk are advancing before it acts: slow-but-progressing work is left alone (bounded by a hard cap), while a genuinely hung process is still killed exactly as fast as before. (#1231)
+- Incremental sync now picks up cross-file relationships that only become resolvable after an edit — for example, when a file gains an export that another, unchanged file was already importing or calling. Previously the reference in the unchanged file was never revisited, so callers, impact, and flow results silently omitted the new edge (while status reported a clean index) until a full re-index. References that can't be resolved yet are now remembered and automatically retried whenever a change introduces a symbol that could satisfy them — this also covers a class gaining a new method that other files already call. Thanks @loadcosmos for the report with a minimal reproduction. (#1240)
+- The reverse case is fixed too: when an edit removes or moves a symbol (or deletes its file), callers in unchanged files now re-resolve during the same sync — rebinding to the symbol's new home when it moved, or waiting to reconnect automatically when it comes back — instead of silently losing their relationship until a full re-index. (#1240)
+
+[1.5.4]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.4
+[1.5.3]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.3
+[1.5.2]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.2
+[1.5.1]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.1
+[1.5.0]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.5.0
+[1.4.1]: https://gitcode.com/ProgramAnalysis/homegraph/tags/v1.4.1

package/README.md

@@ -4,7 +4,7 @@
 
 在开源知识图谱能力之上，**HomeGraph 新增了对 ArkTS（HarmonyOS）的支持**，通过 [arkanalyzer](https://www.npmjs.com/package/arkanalyzer) 解析 `.ets` / `.ts` 工程中的符号、调用关系与模块结构。
 
-数据全部保存在本机 `.homegraph/` 目录，不上传云端。
+项目索引保存在工程根目录的 `.homegraph/` 中，不上传云端。
 
 [![npm version](https://img.shields.io/npm/v/homegraph.svg)](https://www.npmjs.com/package/homegraph)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -15,7 +15,7 @@
 
 ### 1. 安装 CLI
 
-需要 **Node.js 20+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5），否则 `better-sqlite3`，再不行回退 `node-sqlite3-wasm`。
+需要 **Node.js 22+**（推荐 22.5+ 或 24）。SQLite 优先用内置 `node:sqlite`（≥22.5），否则 `better-sqlite3`（12.x），再不行回退 `node-sqlite3-wasm`。
 
 ```bash
 npm install -g homegraph
@@ -149,6 +149,7 @@ homegraph impact <符号>         # 修改该符号的影响范围
 homegraph affected [files...]  # 根据变更文件查找受影响的测试（支持 --stdin）
 homegraph spec build           # 从已有 .spec 目录（或用户指定目录）构建Spec知识图谱（Commit4Spec）
 homegraph spec mine            # 从 Git 历史挖掘设计Spec文档（AST 分析 + LLM 聚类生成）
+homegraph addon ...            # 管理 用户自定义插件（init/install/list/remove/enable/disable/update）
 homegraph spec match <文本>     # 全文搜索相似历史Spec
 homegraph spec find <文件>      # 查找与指定文件关联的Spec
 homegraph spec trace <符号>     # 追溯代码符号关联的Spec
@@ -156,7 +157,10 @@ 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 自动拉起）
+homegraph serve mcp             # 启动 MCP 服务（一般由 Agent 自动拉起；兼容 serve --mcp）
+# 可选：限制查询用的图 — both(默认)|project|sdk|none
+# homegraph serve mcp --sources sdk
+# 或 HOMEGRAPH_SOURCES=project
 ```
 
 `explore` / `node` 等命令与同名 MCP 工具共享同一套输出，适合没有 MCP 的子 Agent 或脚本直接调用。
@@ -171,6 +175,8 @@ Agent 侧工具名前缀为 `homegraph_`。
 
 **跨项目查询：** 所有工具均支持可选参数 `projectPath`（绝对路径），用于在 monorepo 中查询子项目，或当 MCP 服务器根目录没有索引时指定目标项目。
 
+**图谱数据源（`--sources` / `HOMEGRAPH_SOURCES`）：** 控制 MCP 查询是否使用工程索引、OHOS SDK API 库，或两者。取值 `both`（默认）| `project` | `sdk` | `none`。CLI 优先于环境变量。评测示例：`homegraph serve mcp --path <app> --sources sdk`。`homegraph_status` 会打印当前模式。
+
 | 工具 | 用途 |
 |------|------|
 | `homegraph_explore` | **主工具**：一次调用返回相关符号的完整源码、调用路径与影响范围；支持自然语言问题或符号/文件名列表 |
@@ -178,8 +184,10 @@ Agent 侧工具名前缀为 `homegraph_`。
 | `homegraph_node` | 读取单个符号或整个文件的源码（带行号）及调用关系；可替代 Read 读文件 |
 | `homegraph_callers` / `homegraph_callees` | 查看调用方 / 被调用方 |
 | `homegraph_impact` | 变更影响分析（重构前使用） |
+| `homegraph_diff_impact` | 传入 unified diff（或 hunks），返回与变更行相交的符号及调用/影响证据包（代码审查用） |
+| `homegraph_arkui_migrate` | 一次返回 ArkUI 组件迁移/状态语义快照（装饰器、状态字段、Provide/Consume 等） |
 | `homegraph_files` | 已索引的文件树（支持 glob 过滤、按语言分组） |
-| `homegraph_status` | 索引健康状态（调试用） |
+| `homegraph_status` | 索引健康状态（调试用；含 WAL 大小等） |
 | `homegraph_spec_match` | 将新需求描述与 Commit4Spec 知识图谱做全文匹配，返回相似历史Spec及关联提交与代码片段 |
 | `homegraph_spec_find` | 根据文件路径反向查找关联的Spec |
 | `homegraph_spec_trace` | 根据代码符号追溯回关联的Spec |
@@ -190,7 +198,31 @@ Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `
 
 **路径 1：`spec build`（已有Spec导入）**
 
-从项目已有的 `.spec` 目录（或用户指定目录）读取Spec文档，解析其中的 Git 引用和变更片段，直接构建知识图谱节点与关系。
+从项目已有的 `.spec` 目录（或用户指定目录）读取 Spec 文档，通过内置的启发式规则将 Git 提交与 Spec 文档配对，解析配对提交的变更片段，直接构建知识图谱节点与关系。
+
+默认规则与文档发现逻辑可通过 `.homegraph/commit4spec/configs.json` 的 `discovery` 与 `commitScope` 段进行用户自定义
+
+```json
+{
+  //Spec 文档发现：
+  // {specId}.md 平铺文件，或 {specId}/ 目录下按 `primaryDocCandidates` 顺序取第一个存在的主文档；
+  // 目录内匹配 `supplementaryGlobs` 的补充 `.md`文档标题并入 Spec 子标题。
+  "discovery": {
+    "primaryDocCandidates": ["plan.md", "README.md", "spec.md", "design.md", "{spec_dir_name}.md", "spec-{spec_dir_name}.md",],
+    "supplementaryGlobs": ["logic/**/*.md", "design/**/*.md"]
+  },
+  //commit-spec匹配：
+  // 优先从 commit message 的第一行提取 conventional-commit scope（如 `feat(spec03): ...`），归一化后若能在磁盘上找到对应 spec 则直接采用、不回退正文；
+  // 若第一行 scope 对应的 spec 在磁盘上不存在（或第一行完全未命中 scope）且配置了 `bodyRegex`，则回退从正文/footer 提取 spec 引用（如 `Spec: spec03` trailer）；
+  // `bodyRegex` 为可选配置，未配置时仅用标题通道；
+  // 默认提取后归一化（`normalize`）：剥 `review/` 前缀 → 转小写 → `spec3` 补零为 `spec03`。
+  "commitScope": {
+    "scopeRegex": "^(?:feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\\((?:review\\/)?(spec\\d+)\\)",
+    "bodyRegex": "^Spec:\\s*(spec\\d+)\\s*$",
+    "normalize": { "stripPrefixes": ["review/"], "lowercase": true, "padSpecNumber": true }
+  }
+}
+```
 
 **路径 2：`spec mine`（Spec逆向挖掘）**
 
@@ -198,7 +230,9 @@ Commit4Spec 提供两条互补路径将设计Spec与 Git 历史关联，存入 `
 
 支持增量模式（`meta.json` 记录已处理范围）、commit过滤和聚类输出模式（`--skip-llm`）。
 
-`spec mine`逆向挖掘和`spec evolve process`演化更新涉及到模型访问，优先选择用户本地已有的Agent平台（Claude Code >> Codex >> 用户配置LLM），若未安装Claude Code或Codex，则需用户自主配置模型服务，编辑配置文件`.homegraph/commit4spec/configs.json`
+`spec mine`逆向挖掘和`spec evolve process`演化更新涉及到模型访问，优先选择用户本地已有的Agent平台（Claude Code >> Codex >> DevEco Code >> 用户配置LLM），可用环境变量 `HOMEGRAPH_SPEC_AGENT` 强制指定（取值 `claude-code`、`codex`、`deveco-code`，`none` 表示禁用）。
+
+若未安装Claude Code、Codex或DevEco Code，则需用户自主配置模型服务，编辑配置文件`.homegraph/commit4spec/configs.json`
 
 ```json
 // All available options (fields marked * are required):
@@ -223,6 +257,25 @@ homegraph spec find src/auth.ts   # 哪些Spec涉及该文件
 homegraph spec trace UserService  # 追溯符号关联的设计Spec
 ```
 
+**Addons（插件扩展）：**
+
+`homegraph addon` 管理可插拔扩展包，为 `spec mine` 注入外部需求上下文（如 Jira 工单详情），无需 HomeGraph 认识任何工单格式：
+
+```bash
+homegraph addon init my-jira       # 生成 addon 脚手架（内置示例）
+homegraph addon install ./my-jira  # 安装并登记（记录具体版本号）
+homegraph addon list               # 查看已登记的 addon 及状态
+homegraph addon update my-jira     # 更新（默认按记录 range 内最新；--latest 强制 @latest，仅 registry 包）
+homegraph addon disable my-jira    # 停用（保留安装）
+homegraph addon remove my-jira     # 注销（--purge 同时删除文件）
+```
+
+Addon 实现 `enrich` 钩子：HomeGraph 按 commit 簇传入其已有的 commit 数据（hash / 消息 / 作者 / 时间戳），addon 返回带去重键的需求补充文本，HomeGraph 去重后渲染进生成 prompt 的 `## Supplement` 段。
+
+（可选） `buildPrompt` 钩子：用于整体接管 prompt 组装——HomeGraph 传入簇数据、已去重的补充文本、输出模板与字符预算（软约定），由 addon 自行组装完整 prompt，第一个提供该钩子的 addon 生效，调用失败自动回退到默认组装。
+
+每个 addon 独立超时（15s）且失败不影响生成；包需在 package.json 声明 `"homegraph": { "addon": true, "api": 1 }`；登记表存于 `.homegraph/addons.json`，仅显式登记且启用的 addon 才会被加载。
+
 ---
 
 ## 支持的语言
@@ -241,7 +294,7 @@ TypeScript / JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C / C++
 
 ## 从源码构建
 
-适用于开发或二次修改：
+适用于开发或二次修改。协作约定（Spec、Commit、PR）见 [DEVELOPMENT.md](./DEVELOPMENT.md)；文档目录见 [docs/README.md](./docs/README.md)；发包见 [docs/RELEASE.md](./docs/RELEASE.md)；本地 CLI/MCP 见 [docs/local-dev-guide.md](./docs/local-dev-guide.md)。
 
 ```bash
 git clone <your-repo-url>
@@ -271,7 +324,7 @@ npm run cli
     "homegraph": {
       "type": "stdio",
       "command": "homegraph",
-      "args": ["serve", "--mcp"]
+      "args": ["serve", "mcp"]
     }
   }
 }
@@ -287,14 +340,14 @@ Cursor 等项目级配置写入 `./.cursor/mcp.json`，格式相同。推荐使
 |------|------|
 | 上游 | 持续同步 colbymchenry 开源知识图谱项目 main 分支 |
 | 包名 / CLI | `homegraph`（npm：`npm install -g homegraph`） |
-| 数据目录 | `.homegraph/` |
+| 数据目录 | 工程根目录 `.homegraph/` |
 | 主要差异 | 新增 **ArkTS** 语言支持与相关索引逻辑 |
 
 ---
 
 ## 环境要求
 
-- Node.js **20+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → better-sqlite3 → wasm）
+- Node.js **22+**（推荐 22.5+ 或 24；SQLite：`node:sqlite` → better-sqlite3 12.x → wasm）
 - 首次索引时会对项目源码做 AST 解析，大型仓库首次 `init -i` 可能需要数分钟
 - WSL2 下若项目位于 Windows 盘符（`/mnt/c` 等）且 MCP 连接不稳定，可设置 `HOMEGRAPH_NO_DAEMON=1` 跳过共享后台服务，每个会话独立运行
 

package/dist/addons/dynamic-import.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Dynamic ESM import for CJS builds.
+ *
+ * tsc compiles `import()` to `require()` under `module: commonjs`, which
+ * fails for ESM-only addon packages. `new Function` bypasses the transform
+ * and works in the production CLI (plain CJS Node). Some host contexts
+ * (e.g. vitest worker realms) have no dynamic-import callback on
+ * Function-created globals — tests mock this module with a plain
+ * module-scope `import()`, which works there.
+ *
+ * @module addons/dynamic-import
+ */
+/**
+ * Import an ESM module by specifier. For addons the specifier is an
+ * absolute `file://` URL of the resolved entry point.
+ */
+export declare function importESM(specifier: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=dynamic-import.d.ts.map

package/dist/addons/dynamic-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.d.ts","sourceRoot":"","sources":["../../src/addons/dynamic-import.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE7E"}

package/dist/addons/dynamic-import.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Dynamic ESM import for CJS builds.
+ *
+ * tsc compiles `import()` to `require()` under `module: commonjs`, which
+ * fails for ESM-only addon packages. `new Function` bypasses the transform
+ * and works in the production CLI (plain CJS Node). Some host contexts
+ * (e.g. vitest worker realms) have no dynamic-import callback on
+ * Function-created globals — tests mock this module with a plain
+ * module-scope `import()`, which works there.
+ *
+ * @module addons/dynamic-import
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importESM = importESM;
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const importViaFunction = new Function('specifier', 'return import(specifier)');
+/**
+ * Import an ESM module by specifier. For addons the specifier is an
+ * absolute `file://` URL of the resolved entry point.
+ */
+function importESM(specifier) {
+    return importViaFunction(specifier);
+}
+//# sourceMappingURL=dynamic-import.js.map

package/dist/addons/dynamic-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-import.js","sourceRoot":"","sources":["../../src/addons/dynamic-import.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAWH,8BAEC;AAXD,8DAA8D;AAC9D,MAAM,iBAAiB,GAAG,IAAI,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAEzC,CAAC;AAEtC;;;GAGG;AACH,SAAgB,SAAS,CAAC,SAAiB;IACzC,OAAO,iBAAiB,CAAC,SAAS,CAAC,CAAC;AACtC,CAAC"}

package/dist/addons/init-template.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Addon scaffold generator (`homegraph addon init`).
+ *
+ * Produces a publishable npm package skeleton with the `homegraph` marker,
+ * an `enrich` stub, and a worked Jira example (parse ticket refs → fetch
+ * details → return supplements).
+ *
+ * @module addons/init-template
+ */
+/**
+ * Create the addon scaffold in `parentDir/<name>`. Returns the paths of the
+ * files created (absolute). Throws when the target directory already exists.
+ */
+export declare function createAddonScaffold(name: string, parentDir: string, lang: 'js' | 'ts'): string[];
+//# sourceMappingURL=init-template.d.ts.map

package/dist/addons/init-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-template.d.ts","sourceRoot":"","sources":["../../src/addons/init-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4OH;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,IAAI,GAAG,IAAI,GAChB,MAAM,EAAE,CA2BV"}