dsh-gitnexus-plus 0.1.5 → 0.1.6

package/README-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) · **简体中文**
 
-**当前版本：0.1.5** · [npm](https://www.npmjs.com/package/dsh-gitnexus-plus) ·
+**当前版本：0.1.6** · [npm](https://www.npmjs.com/package/dsh-gitnexus-plus) ·
 [问题反馈](https://github.com/Moowningstar/gitnexus-plus/issues)
 
 [插件做什么](#插件做什么) · [安装](#安装) · [遇到问题怎么解决](#遇到问题怎么解决) ·
@@ -16,9 +16,11 @@
 ## 插件做什么
 
 - **刷新门禁（Tier 0）**：在给出刷新按钮之前，用工作区文件与索引记录的 sha256（`.gitnexus/gitnexus.json` 的 `fileHashes`）比对，报告真正变化的内容：改 / 增 / 删，以及被索引策略排除的文件。工作区没变时毫秒级给出结论、**不启动分析器**，按钮直接说明"无需刷新"，而不是让你等一次几分钟的重建。只有比对**锚定在索引记录的提交**上时才会说"已是最新"；索引没记录提交时会退化为工作区与 `HEAD` 比较，并明确说"无法确认"，而不是冒充新鲜。
-- **图视图**：把索引里的社区画在 canvas 上，跨社区关系按权重聚合；点社区看成员符号及它们之间的关系，点符号在文件查看器里定位到行。节点与边预算由宿主限制，并明确写出省略了多少。
+- **图视图**：把索引里的社区画在 canvas 上，跨社区关系按权重聚合；点社区看成员符号及它们之间的关系，点符号在文件查看器里定位到行。节点与边预算由宿主限制，并明确写出省略了多少。社区之外的符号可用**符号视图**切换查看：它是按文件顺序截断的全仓库符号投影，结构全貌仍看社区视图。卡片总览是 **3D**：同一批社区放到 Z 轴、按社区着色、标注代表文件，并支持最短路径高亮；双击社区进入成员符号；**展开**是居中弹窗而不是全屏。卡片滚动到视口附近才发起图请求。
+- **刷新建议**：陈旧度判断同时给出 `无需刷新` / `增量刷新` / `重新分析` / `全量重建` / `初始化索引` / `无法判断`。没有提交基线时不会把“工作区没改”说成可增量刷新；`--skip-git` 索引会明确建议重新分析。
 - **索引覆盖**：列出被 `gitnexus analyze` 跳过的超大文件，给出大小、语言占比，以及生成物/压缩文件的判断信号。
 - **索引新鲜度**：索引提交与 `HEAD` 对比，分为 `current` / `behind` / `diverged` / `unknown`，并给出未提交变更数。
+- **版本一致性**：把索引记录的 `runnerIdentity.cliVersion` 与当前 CLI 对比；不一致时给出警告，而不是默认索引与查询路径一致。
 - **图构成**：节点、边、社区、流程、embedding、边/节点比。
 - **Git 活跃度 × 索引**：最近提交、作者、分支、改动最多的文件，每个文件给出 **已索引 / 设计上排除 / 索引缺失** 三方判断；另有活动 × 索引交叉表、相对索引提交的基线审查（索引未记录提交时用活动窗口起点并明确标注）、7/14/30 天提交时间线，以及点击文件行查看该文件自己的时间线。
 - **语言分布**：按字节拆分“能解析进图的语言 / 只识别格式的语言 / 其他”；GitNexus 不在时用内置扩展名映射，并标为 `builtin`，不冒充已解析。
@@ -189,7 +191,7 @@ $env:GITNEXUS_MEMORY='off'; $env:NODE_OPTIONS='--max-old-space-size=8192'; `
 
 - 覆盖与搜索是只读的；维护是单独确认的写操作，不会自动触发。
 - 刷新门禁比对的是索引记录过的文件内容哈希。它看不到分析器因自身原因必须重跑的情况（schema 升级、新的分析特性）；**仍然刷新** 就是为这种情况留的。
-- 图视图画的是社区，不是全部符号：总览是社区图，下钻最多显示一个社区的节点预算那么多成员。两者都会标注是否截断。
+- 社区图不画全部符号：总览是社区图，下钻最多显示一个社区的节点预算那么多成员；符号视图是全仓库符号的有界截断投影，按文件顺序取前 N 个，不能当成完整图。两者都会标注是否截断。
 - 只报告 GitNexus 索引的事实，不重写解析器，不重新实现图数据库。
 - 搜索的 graph 模式是名称/路径匹配，不搜正文；text 模式才按行匹配，且有上限。
 - 源码回退只覆盖索引清单里的文件，新文件需先刷新索引。

package/README.md

@@ -2,7 +2,7 @@
 
 **English** · [简体中文](README-CN.md)
 
-**Current release: [0.1.5](https://github.com/Moowningstar/gitnexus-plus/releases/tag/v0.1.5)** ·
+**Current release: [0.1.6](https://github.com/Moowningstar/gitnexus-plus/releases/tag/v0.1.6)** ·
 [npm](https://www.npmjs.com/package/dsh-gitnexus-plus) ·
 [Issues](https://github.com/Moowningstar/gitnexus-plus/issues)
 
@@ -29,11 +29,27 @@ It does not fork GitNexus, rewrite its parser, or bundle/redistribute it. `gitne
 - **Graph view** — the index's communities drawn on a canvas, with aggregated
   cross-community edges; click a community to see its member symbols and the relations
   among them, click a symbol to open its file at the line. Node and edge budgets are
-  applied by the host, and the view states what it left out.
+  applied by the host, and the view states what it left out. A **Symbol view** button
+  switches to a bounded all-symbol projection when a symbol outside the current
+  communities matters; it is explicitly truncated by file order, and the community view
+  remains the structural overview. The community overview is a
+  **3D** view in the card: it puts the same communities on a Z axis with per-community
+  colours, representative member files and shortest-path highlighting, so a dense core
+  can be rotated apart instead of settling into a flat hairball. Single click selects a
+  community; double-click opens its member symbols. **Expand** opens a centered
+dialog with the same projection and a community sidebar, not a full-screen mode. The
+  card defers its fetch until it is scrolled near the viewport.
+- **Refresh advice** — the staleness verdict also recommends one of `none` /
+  `incremental` / `reanalyze` / `rebuild` / `init` / `unknown`, so a worktree-only
+  comparison never reads as "safe to incrementally refresh" and a `--skip-git` index is
+  told to re-analyze instead of being offered an impossible incremental run.
 - **Index coverage** — lists the oversized files `gitnexus analyze` skipped, with size,
   language share, and generated/minified signals.
 - **Index freshness** — indexed commit vs `HEAD`, classified `current` / `behind` /
   `diverged` / `unknown`, plus the uncommitted-change count.
+- **Version consistency** — compares the GitNexus CLI that wrote the index
+  (`runnerIdentity.cliVersion`) with the CLI installed now. A mismatch is reported as a
+  warning, not silently rendered as if the index and the query path agreed.
 - **Graph composition** — nodes, edges, communities, processes, embeddings, edges per node.
 - **Git activity × index** — recent commits, authors, branches and most-changed files,
   each file marked **indexed**, **excluded by design**, or **missing from the index**.
@@ -151,6 +167,12 @@ npm run check
 npm test
 ```
 
+`npm test` builds and runs the engine, plugin and client suites. The suite no longer
+depends on a developer's `D:` drive: the format test builds a disposable repository, and
+the real-repository smoke test defaults to this checkout (or `GITNEXUS_SMOKE_REPO`) and
+skips when it has no index. `.github/workflows/ci.yml` runs `npm ci`, `npm run check` and
+`npm test` on Windows and Ubuntu with Node 22 and 24.
+
 Search has two modes:
 
 - **graph** — the normal path. The host does not load native `lbug`; it starts
@@ -265,9 +287,14 @@ the related features puts that use under it.**
 - The refresh gate compares content hashes of the files the index recorded. It cannot
   see a change the analyzer would make for its own reasons (a schema upgrade, a new
   feature mode); **仍然刷新** exists for exactly that case.
-- The graph view draws communities, not every symbol: the overview is the community
-  graph, and a drill-down shows at most the configured node budget of one community's
-  members. Both say when they are truncated.
+- The graph view draws communities by default, not every symbol: the overview is the
+  community graph, and a drill-down shows at most the configured node budget of one
+  community's members. The **Symbol view** is a bounded all-symbol projection ordered by
+  file and explicitly truncated, not a claim of completeness. Both say when they are
+  truncated.
+- The 3D overview draws community nodes only; member symbols remain in the 2D drill-down.
+  It is the card's default community view, not a separate full-screen mode, so the sidebar
+  stays the one place the graph lives.
 - The plugin reports facts about a GitNexus index; it does not rewrite the parser or
   reimplement the graph database.
 - Graph search matches names/paths, not bodies; the text fallback matches lines and is