dsh-d365-kit 0.34.4 → 0.34.5

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 Versioning: bug fixes bump the patch, new tools/capabilities bump the minor, changes to the config structure or renames bump the major.
 
+## 0.34.5
+
+An outside review (looking for users who hold two particular roles) turned up the same class of problem several times: when the tool was **wrong**, it did not fail — it quietly changed the question.
+
+- A wrong attribute name in `$filter` is no longer treated as a `$select` problem. Previously any `0x80060888` triggered a walk down `$select` → `$orderby` → no `$select` at all, so you could get a 200 whose columns were not the ones you asked for, or a retry loop that ended in an error unrelated to the cause. Now a column is dropped only when that name really is in `$select` and is absent from `$filter`/`$orderby`; otherwise it fails as `unknown-property` and says whether it is casing, a lookup (`_<field>_value`) or a missing cast. The degradation ladder (`$top`/`$orderby`/`$select`) now runs only when the service actually says a query parameter is unsupported.
+- A lookup in `select` silently came back as an empty column (`businessunitid` empty, the value only in `_businessunitid_value`). The column is now switched to `_businessunitid_value` with a note under the table; a column that genuinely does not exist is named — "`x` was not returned: that name cannot be selected (or its casing is wrong), this is not an empty field".
+- `d365_data sample` no longer sends its own `$top` (which defeated the paging probe and made `hasMore` always false), says "(more rows exist, the sample shows only the first few)" when there are, and no longer renders `@odata.etag` as a column header.
+- Every per-environment heading now carries "N requests / seconds", so a query slowed down by fallback retries is visible at a glance.
+- The definition endpoints (`EntityDefinitions` / `RelationshipDefinitions` / `GlobalOptionSetDefinitions`) no longer get a `$top` they are going to reject: one wasted request per query before, now a clean metadata read is a single request. Dropped columns are named too.
+- The `0x80060888` hint was rewritten: it used to promise that the tool would drop columns and retry, which cannot help when the name is in `$filter`.
+
 ## 0.34.4
 
 Publishing is now part of the repository: `.github/workflows/publish.yml` publishes to npm whenever the pushed `package.json` version is not on the registry yet.
@@ -13,7 +24,7 @@ Publishing is now part of the repository: `.github/workflows/publish.yml` publis
 - Authentication is opt-in: npm trusted publishing (OIDC, `id-token: write`, `--provenance`) through the `NPM_TRUSTED_PUBLISHING` variable, or a granular `NPM_TOKEN` secret; with neither configured the job prints a notice instead of failing;
 - The install docs no longer claim that pushing a tag is what publishes.
 - `0.34.2` never shipped: an earlier manual attempt had already put that exact version in the registry's stage queue, and publishing it again is refused with `E409 Cannot publish over previously staged version "0.34.2"`.
-- `0.34.3` was published by CI but only into that same stage queue: the trusted publisher allowed stage publishing but not direct publishing, and `npm publish` exits 0 when it stages. `0.34.4` is the first version that goes live on its own — turn on "Publish directly" under the trusted publisher's allowed actions.
+- `0.34.3` was published by CI but only into that same stage queue, because the trusted publisher allowed stage publishing but not direct publishing; `npm publish` exits 0 when it stages, so the run looked green. It went live later, when direct publishing was enabled. `0.34.4` is the first version published directly, with nobody approving it by hand.
 
 ## 0.34.1
 

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,17 @@
 
 版本语义：修 bug 升 patch，加工具/加能力升 minor，改配置结构或改名升 major。
 
+## 0.34.5
+
+一次外部复盘（查「同时有某两个角色的用户」）暴露的问题：工具在**答错**的时候没有报错，而是悄悄换了问题。
+
+- `$filter` 里写错属性名时不再被当成 `$select` 的问题：以前任何 `0x80060888` 都会去删 `$select` 的列、再删 `$orderby`、最后连整个 `$select` 都删掉，于是可能返回 200 但列不是你要的，或者反复重试最后报一个和原因无关的错。现在只有「这个名字确实在 `$select` 里、且没出现在 `$filter`/`$orderby` 里」才逐列剔除；否则直接报 `unknown-property`，并说明是大小写、lookup（`_<字段>_value`）还是 cast 的问题。降级阶梯（去 `$top`/`$orderby`/`$select`）只在服务端明确说「查询参数不被支持」时执行。
+- lookup 列放进 `select` 会静默变成空列（`businessunitid` 空、`_businessunitid_value` 才有值）。现在自动改显示 `_businessunitid_value` 并写一行说明；真不存在的列会点名「`x` 没有返回：这个名字不能 select（或大小写不对），不是记录里为空」。
+- `d365_data sample` 不再自己发 `$top`（那会让分页探测失效、`hasMore` 恒假），行数够了会写「（还有更多，样例只取前几条）」；默认列也不再拿 `@odata.etag` 当表头。
+- 每个环境的标题现在带「N 请求 / 秒数」，一眼看出这次查询是不是被降级重试拖慢了。
+- 定义端点（`EntityDefinitions` / `RelationshipDefinitions` / `GlobalOptionSetDefinitions`）不发 `$top`：以前每次都要先被拒一次再降级，白花一个请求（元数据查询从 2–3 个请求降到 1 个）；被去掉的列也会点名。
+- `0x80060888` 的 hint 重写：以前说「工具会逐列剔除并重试」，但 `$filter` 场景根本修不好。
+
 ## 0.34.4
 
 发布进了仓库：`.github/workflows/publish.yml` 会在推送的 `package.json` 版本还没上架 npm 时自动发布。
@@ -13,7 +24,7 @@
 - 认证是显式的：用 `NPM_TRUSTED_PUBLISHING` 变量开启 npm trusted publishing（OIDC、`id-token: write`、带 `--provenance`），或者配 `NPM_TOKEN` secret；两者都没有时只打一条 notice，不让 push 变红；
 - 安装文档不再说「推 tag 就会发布」。
 - `0.34.2` 没有发出来：更早一次手动发布已经把这个版本号留在了注册表的暂存队列里，再发同一个版本会被拒（`E409 Cannot publish over previously staged version "0.34.2"`）。
-- `0.34.3` 由 CI 发了，但也只进了那个暂存队列：trusted publisher 只允许 stage 发布、不允许直接发布，而「进暂存」时 `npm publish` 同样是退出码 0，看上去像成功了。`0.34.4` 是第一个无需人工批准就上线的版本 —— 前提是在 trusted publisher 的 Allowed actions 里勾上「Publish directly」。
+- `0.34.3` 由 CI 发了，但只进了那个暂存队列：trusted publisher 当时只允许 stage 发布、不允许直接发布，而「进暂存」时 `npm publish` 同样退出 0，看上去像成功了。后来打开直接发布后它才上线。`0.34.4` 是第一个直接发布、不需要人批的版本。
 
 ## 0.34.1
 

package/INSTALL.md

@@ -19,7 +19,7 @@ For the complete steps, see [docs/en/installation.md](docs/en/installation.md).
 ### Option 1: Install from npm (shortest, upgradeable)
 
 ```
-plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+plugin_manager install_bundle target="dsh-d365-kit@0.34.5"
 ```
 
 This needs the package to be published to the registry pnpm uses — public npm or an internal mirror. The name has no scope, so no scope mapping is required.
@@ -29,7 +29,7 @@ This needs the package to be published to the registry pnpm uses — public npm
 ### Option 2: Install from Git (no registry needed)
 
 ```
-plugin_manager install_bundle target="git+https://<your Git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your Git>/<group>/dsh-d365-kit.git#v0.34.5"
 ```
 
 ### Option 3: Install from a local directory

package/INSTALL.zh-CN.md

@@ -18,7 +18,7 @@
 ### 方式一：从 npm 装（最短，可升级）
 
 ```
-plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+plugin_manager install_bundle target="dsh-d365-kit@0.34.5"
 ```
 
 前提是包已经发到 pnpm 用的那个 registry——公网 npm 或公司内网镜像都行。包名没有 scope，不需要配 scope 映射。
@@ -28,7 +28,7 @@ plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
 ### 方式二：从 Git 装（不需要 registry）
 
 ```
-plugin_manager install_bundle target="git+https://<你的 Git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<你的 Git>/<group>/dsh-d365-kit.git#v0.34.5"
 ```
 
 ### 方式三：从本地目录装

package/README.md

@@ -116,10 +116,10 @@ Prerequisites: DSH desktop; network access to `*.dynamics.com`; a read-only appl
 
 ```bash
 # From npm (shortest, upgradeable; works once the package is published)
-plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+plugin_manager install_bundle target="dsh-d365-kit@0.34.5"
 
 # From Git (no registry needed, pin a tag)
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.5"
 
 # From a local directory (link: code changes take effect immediately)
 plugin_manager install_bundle target="D:\path\to\dsh-d365-kit"

package/README.zh-CN.md

@@ -116,10 +116,10 @@ DSH Web UI 的「设置 → D365 工具箱」，六个标签页：
 
 ```bash
 # 从 npm 安装（最短，可升级；包发布到 npm 或内网 registry 后可用）
-plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+plugin_manager install_bundle target="dsh-d365-kit@0.34.5"
 
 # 从 Git 安装（不需要 registry，可钉 tag）
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.5"
 
 # 或从本地目录安装（link，改代码立刻生效）
 plugin_manager install_bundle target="D:\path\to\dsh-d365-kit"

package/docs/en/installation.md

@@ -20,7 +20,7 @@ A read-only application user is enough; for the write capabilities, messages suc
 ### Option 1: install from npm (shortest)
 
 ```bash
-plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+plugin_manager install_bundle target="dsh-d365-kit@0.34.5"
 ```
 
 Works once the package is published to the registry pnpm is configured against — public npm or an internal mirror. The package has no scope, so no scope mapping is needed. To install a specific version pin it as `dsh-d365-kit@<version>`.
@@ -30,7 +30,7 @@ Works once the package is published to the registry pnpm is configured against
 ### Option 2: install from Git (no registry needed)
 
 ```bash
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.5"
 ```
 
 DSH pulls the package from git with pnpm. After installing, check:
@@ -128,7 +128,7 @@ If both return content, it works. The first `d365_sync` pulls the full metadata
 ```bash
 # installed from Git
 plugin_manager remove_bundle target=dsh-d365-kit
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.5"
 ```
 
 After changing the version number you must **remove first, then install**: link/pnpm returns `already-installed` when it believes the package exists, and does not replace the code.

package/docs/en/tools.md

@@ -108,7 +108,9 @@ Queries metadata by category. 20 resource types:
 
 A few real constraints:
 
-- The metadata endpoints (`EntityDefinitions`) **do not accept** `$orderby` and `$top`; the client falls back and retries step by step;
+- The definition endpoints (`EntityDefinitions`, `RelationshipDefinitions`, `GlobalOptionSetDefinitions`) **do not accept** `$top`; the tool simply does not send it for those paths (it used to pay one rejected request per query). `$orderby` is only dropped when the endpoint refuses it.
+- Degradation is limited to `$select`: a column the endpoint rejects is removed one at a time and named under the table ("the endpoint does not recognise these columns, dropped: …"). A name written in `$filter` / `$orderby` is **never** rewritten — that would change the question — it fails as `unknown-property` and says whether it is a casing, lookup or cast problem.
+- Every per-environment heading carries "N requests / seconds", so a query slowed down by fallback retries is visible at a glance.
 - Display names are multilingual, so compare across environments by **logical name**, not display name;
 - Entity set names can be customized; do not hard-code the plural form — use the `entities` resource or `d365_data`'s automatic resolution;
 - `workflows` / `business_rules` return the **definition row only** by default (`type eq 1`): Dataverse stores a second, same-named activation row (`type eq 2`, different `workflowid`) for every process, which otherwise looks like a duplicate and doubles the count. An explicit `filter` (e.g. `type eq 2`) replaces the default instead of ANDing with it, so it never collapses to an empty result.
@@ -274,6 +276,13 @@ Counting prefers `$apply=aggregate($count as count)` (unaffected by the 5,000 ca
 
 `query` distinguishes three outcomes in its heading: `共 N 行` (all N rows), `已列 N 条 / 共 M 条` (N of M shown), or `返回 N 行（可能还有更多）` (there may be more). **A GUID copied from another environment is a 404 when it is absent here**, and the `id` path reports `record-not-found` instead of handing back an empty table.
 
+Two things that are easy to misread, both stated in the digest:
+
+- **A lookup cannot be selected by its attribute name.** `select=businessunitid` comes back empty; the value lives in `_businessunitid_value`. The tool switches the column for you and prints "businessunitid is a lookup: the value is in _businessunitid_value …" under the table — read that line before concluding the field is empty.
+- **Every per-environment heading carries "N requests / seconds".** Four requests for one query usually means entity-set resolution + fetch + count; a much larger number means fallback retries did the extra work (look for the "columns dropped" note).
+
+`sample` says "(more rows exist, the sample shows only the first few)" so that "I looked at 5 rows" is never read as "there are 5 rows".
+
 Use it to learn "how many records still use this value" before changing an option set, deleting a field, or narrowing a filter.
 
 ---

package/docs/zh/installation.md

@@ -20,7 +20,7 @@
 ### 方式一：从 npm 安装（最短）
 
 ```bash
-plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
+plugin_manager install_bundle target="dsh-d365-kit@0.34.5"
 ```
 
 前提是包已经发到 pnpm 配置的 registry——公网 npm 或内网镜像都行。包名没有 scope，不需要配 scope 映射。要装指定版本就写 `dsh-d365-kit@<版本>`。
@@ -30,7 +30,7 @@ plugin_manager install_bundle target="dsh-d365-kit@0.34.4"
 ### 方式二：从 Git 安装（不需要 registry）
 
 ```bash
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.5"
 ```
 
 DSH 用 pnpm 从 git 拉包。装完确认：
@@ -128,7 +128,7 @@ d365_metadata resource=entities top=3
 ```bash
 # 从 Git 安装的
 plugin_manager remove_bundle target=dsh-d365-kit
-plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.4"
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.5"
 ```
 
 改版本号后必须**先 remove 再 install**：link/pnpm 认为包已存在时会返回 `already-installed`，不会替换代码。

package/docs/zh/tools.md

@@ -108,7 +108,9 @@
 
 几个真实约束：
 
-- 元数据端点（`EntityDefinitions`）**不接受** `$orderby` 与 `$top`，客户端会逐步降级重试；
+- 元数据定义端点（`EntityDefinitions` / `RelationshipDefinitions` / `GlobalOptionSetDefinitions`）**不接受** `$top`，工具对这类路径直接不发（以前每次都要先被拒一次，白花一个请求）；`$orderby` 被拒时才降级去掉。
+- 降级只发生在 `$select` 上：端点不认的列会被逐列去掉，并在表下点名「这些列该环境不认，已去掉：…」。名字写在 `$filter` / `$orderby` 里时**不会**被改写（那等于换一个问题）——直接报 `unknown-property`，并说明是大小写、lookup 还是 cast 的问题。
+- 每个环境的标题带「N 请求 / 秒数」，被降级重试拖慢时一眼能看出来。
 - 显示名有多语言，跨环境比较请用**逻辑名**，不要用显示名；
 - 实体集名可被自定义，不要硬编码复数形式，用 `entities` 资源或 `d365_data` 的自动解析；
 - `workflows` / `business_rules` 默认只取**定义行**（`type eq 1`）：Dataverse 给每个流程另存一条同名、不同 `workflowid` 的激活行（`type eq 2`），不过滤会看起来像重复、计数也会翻倍；显式传 `filter`（如 `type eq 2`）时默认过滤自动让位，不会 AND 成空集。
@@ -274,6 +276,13 @@ manifest 是区分「环境里没有」与「没采到」的唯一依据。全
 
 `query` 的标题会区分三种情况：`共 N 行`、`已列 N 条 / 共 M 条（未列全…）`、`返回 N 行（可能还有更多）`。**跨环境复制的 GUID 在目标环境不存在时是 404**，`id` 分支会明确报 `record-not-found`，而不是给一张空表。
 
+两个容易看错的地方，摘要会直接说：
+
+- **lookup 列不能按字段名 select**。`select=businessunitid` 拿回来是空列，值在 `_businessunitid_value`。工具会自动改显示 `_businessunitid_value`，并在表下写「businessunitid 是 lookup：值在 _businessunitid_value…」——所以看到空列时先读那行提示，不要当成「这一列没值」。
+- **每个环境的标题都带「N 请求 / X 秒」**。一次查询要 4 个请求，通常是「实体集解析 + 取数 + 计数」；如果数字明显偏大，说明被降级重试拖慢了（看表下的「这些列该环境不认」）。
+
+`sample` 会标「（还有更多，样例只取前几条）」，避免把「只看了 5 行」当成「一共 5 行」。
+
 用途：改选项集、删字段、收窄筛选条件之前，先知道「这个值还有多少条记录在用」。
 
 ---

package/lib/client.js

@@ -435,6 +435,35 @@ export class DataverseClient {
   }
 }
 
+/** `Could not find a property named 'x' on type '...'` — the name is the group. */
+const MISSING_PROPERTY = /property named '([^']+)'/
+
+/** True when `expression` names `name` as a whole word (not a substring). */
+function mentions(expression, name) {
+  if (!expression) return false
+  const escaped = String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(^|[^A-Za-z0-9_])${escaped}($|[^A-Za-z0-9_])`, 'i').test(String(expression))
+}
+
+/**
+ * Explain a rejected property name.
+ *
+ * The old behaviour was to treat every 0x80060888 as "some `$select` column is
+ * wrong" and keep narrowing the request. When the name actually came from the
+ * caller's `$filter`, that repair can never succeed: the tool spent two extra
+ * requests and then reported the original error, and — worse — dropping the
+ * whole `$select` could return a 200 whose columns are not the ones asked for.
+ */
+function unknownPropertyHint(name, params) {
+  if (mentions(params?.$filter, name)) {
+    return `名字 "${name}" 出现在 $filter 里：工具不会改写 filter（那等于换一个问题），改正后重试。`
+  }
+  if (mentions(params?.$orderby, name)) {
+    return `名字 "${name}" 出现在 $orderby 里：改正后重试。`
+  }
+  return `这个端点不认 "${name}"：元数据端点属性名大小写敏感；lookup 用 _<字段>_value，派生属性先 cast；也可能是这一列不在当前选择集里。`
+}
+
 /**
  * GET with progressive fallbacks for query options real deployments reject.
  *
@@ -442,8 +471,12 @@ export class DataverseClient {
  * endpoint or version: a metadata endpoint answers `$orderby` with
  * 0x80060888 "The query parameter ... is not supported", and a table may lack a
  * property this plugin asked for ("Could not find a property named 'modifiedon'
- * on type 'Microsoft.Dynamics.CRM.systemform'"). Each rejection narrows the
- * request — one field at a time — instead of failing the whole resource.
+ * on type 'Microsoft.Dynamics.CRM.systemform'").
+ *
+ * Narrowing is deliberately limited to the `$select` list: dropping a column
+ * the server rejects is harmless, while dropping `$orderby` or the whole
+ * `$select` changes the answer. A property that is not in `$select` — or that
+ * also appears in `$filter` — is reported as `unknown-property` immediately.
  * @returns `{ page, selectDropped, orderbyDropped, droppedFields }`.
  */
 export async function getPagedWithSelectFallback(client, path, params, limit, signal) {
@@ -457,36 +490,58 @@ export async function getPagedWithSelectFallback(client, path, params, limit, si
       if (error?.status !== 400) throw error
       const text = String(error.message ?? '')
 
-      const missing = /property named '([^']+)'/.exec(text)
-      if (missing && current.$select) {
-        const fields = current.$select.split(',').map((item) => item.trim()).filter(Boolean)
-        const kept = fields.filter((field) => field.toLowerCase() !== missing[1].toLowerCase())
-        if (kept.length && kept.length < fields.length) {
+      const missing = MISSING_PROPERTY.exec(text)
+      if (missing) {
+        const name = missing[1]
+        const fields = String(current.$select ?? '').split(',').map((item) => item.trim()).filter(Boolean)
+        const selected = fields.some((field) => field.toLowerCase() === name.toLowerCase())
+        // Only a column we chose to select can be dropped. A name the caller
+        // wrote in $filter/$orderby is their question, not our vocabulary.
+        if (!selected || mentions(current.$filter, name) || mentions(current.$orderby, name)) {
+          throw new D365Error(text, {
+            code: 'unknown-property',
+            status: 400,
+            body: error.body,
+            hint: unknownPropertyHint(name, current),
+          })
+        }
+        const kept = fields.filter((field) => field.toLowerCase() !== name.toLowerCase())
+        if (kept.length) {
           current.$select = kept.join(',')
-          dropped.droppedFields.push(missing[1])
+          dropped.droppedFields.push(name)
           continue
         }
+        // Every selected column was rejected: returning default columns would
+        // look like success with the wrong shape.
+        throw new D365Error(text, {
+          code: 'unknown-property',
+          status: 400,
+          body: error.body,
+          hint: unknownPropertyHint(name, current),
+        })
       }
 
       // "The query parameter '...' is not supported": the name is often
       // redacted before it reaches us, so narrow the request by dropping the
       // options in turn, cheapest first. `$top` is added inside getPaged, so
       // the check is on the marker, not on the params object.
-      if (/query parameter/i.test(text) && !dropped.topDropped) {
-        current.__noTop = true
-        delete current.$top
-        dropped.topDropped = true
-        continue
-      }
-      if (current.$orderby) {
-        delete current.$orderby
-        dropped.orderbyDropped = true
-        continue
-      }
-      if (current.$select) {
-        delete current.$select
-        dropped.selectDropped = true
-        continue
+      if (/query parameter/i.test(text)) {
+        if (!dropped.topDropped) {
+          current.__noTop = true
+          delete current.$top
+          dropped.topDropped = true
+          continue
+        }
+        if (current.$orderby) {
+          delete current.$orderby
+          dropped.orderbyDropped = true
+          continue
+        }
+        if (current.$select) {
+          delete current.$select
+          dropped.selectDropped = true
+          continue
+        }
       }
       throw error
     }

package/lib/error-codes.js

@@ -15,7 +15,7 @@ export const ERROR_CODES = {
   },
   '0x80060888': {
     summary: '请求里有一个这个端点不认识的属性名或查询参数',
-    hint: '元数据端点（EntityDefinitions / GlobalOptionSetDefinitions 等）不接受 $top、$orderby、$filter 的部分组合；派生属性（如 DefaultValue、Targets、Options）要先用 cast 到具体类型才能 select。工具已经会逐列剔除并重试，仍失败说明名字本身写错了。',
+    hint: '属性名大小写敏感：元数据端点（EntityDefinitions 等）要 LogicalName，实体表上要逻辑名小写（name、createdon）；lookup 列要写 _<字段>_value；派生属性（DefaultValue、Targets、Options）要先用 cast 指到具体类型。工具只会在 $select 里剔除同名的那一列——名字写在 $filter / $orderby 里时直接报 unknown-property（改写 filter 等于换一个问题）。只有「查询参数不被支持」时，工具才会逐项去掉 $top / $orderby / $select 重试。',
   },
   '0x80040216': {
     summary: '对象不存在：按这个名字或 id 找不到记录',

package/lib/tool-data.js

@@ -162,6 +162,47 @@ async function countRows(client, set, filter, signal) {
   })
 }
 
+/**
+ * Keep the columns the caller asked for even when the response disagrees.
+ *
+ * Selecting a lookup by its attribute name returns nothing — Dataverse exposes
+ * the value as `_<name>_value` — and an unselectable or misspelled column
+ * silently comes back absent. Both used to render as an empty cell with no
+ * explanation, which reads as "this record has no value".
+ * @returns `{ columns, notes }` — `notes` is empty when everything resolved.
+ */
+function reconcileColumns(columns, rows) {
+  const notes = []
+  if (!columns?.length || !rows.length) return { columns: columns ?? [], notes }
+  const present = new Set(Object.keys(rows[0]))
+  const resolved = []
+  for (const name of columns) {
+    if (present.has(name)) {
+      if (!resolved.includes(name)) resolved.push(name)
+      continue
+    }
+    const lookup = `_${name}_value`
+    if (present.has(lookup)) {
+      if (!resolved.includes(lookup)) resolved.push(lookup)
+      notes.push(`${name} 是 lookup：值在 ${lookup}，已改显示那一列（写入时用 ${name}@odata.bind）。`)
+      continue
+    }
+    if (!resolved.includes(name)) resolved.push(name)
+    notes.push(`${name} 没有返回：这个名字不能 select（或大小写不对），不是「记录里为空」。`)
+  }
+  return { columns: resolved, notes }
+}
+
+/** One-line cost tag: a retry-happy call should look expensive in the summary. */
+function costText(requests, started) {
+  const seconds = Math.max(0, Date.now() - started) / 1000
+  return `（${requests} 请求 / ${seconds.toFixed(1)}s）`
+}
+
+function notesText(notes) {
+  return notes?.length ? `\n注意：\n${notes.map((note) => `- ${note}`).join('\n')}` : ''
+}
+
 export function register(ctx, state) {
   return ctx.tools.register({
     ...definition,
@@ -180,6 +221,7 @@ export function register(ctx, state) {
       const artifact = { action, entity: args.entity, filter: args.filter, environments: {} }
 
       for (const env of envs) {
+        const started = Date.now()
         const client = makeClient(env, config)
         const { set, logical } = await resolveEntitySet(client, args.entity, exec?.signal)
         const filter = args.filter
@@ -187,7 +229,7 @@ export function register(ctx, state) {
         if (action === 'count') {
           const count = await countRows(client, set, filter, exec?.signal)
           artifact.environments[env.key] = { entitySet: set, count }
-          reports.push(`${env.key}：${logical} 共 ${count} 行${filter ? `（筛选：${filter}）` : ''}`)
+          reports.push(`${env.key}：${logical} 共 ${count} 行${filter ? `（筛选：${filter}）` : ''}${costText(client.counters.requests, started)}`)
           continue
         }
 
@@ -239,8 +281,10 @@ export function register(ctx, state) {
               throw new D365Error(`${env.key} 没有返回 ${logical}(${key})`, { code: 'record-not-found' })
             }
             artifact.environments[env.key] = { entitySet: set, id: key, rows: [row] }
-            const shown = columns ?? Object.keys(row).filter((name) => !name.startsWith('@')).slice(0, 8)
-            reports.push(`${env.key}：${logical}(${key})\n${formatTable([row], shown, { width: 40 })}`)
+            const requested = columns ?? Object.keys(row).filter((name) => !name.startsWith('@')).slice(0, 8)
+            const shown = reconcileColumns(requested, [row])
+            reports.push(`${env.key}：${logical}(${key})${costText(client.counters.requests, started)}\n`
+              + `${formatTable([row], shown.columns, { width: 40 })}${notesText(shown.notes)}`)
             continue
           }
           // Do not send `$top` here: `getPaged` asks for one row more than the
@@ -253,26 +297,33 @@ export function register(ctx, state) {
           const page = await client.getPaged(set, params, top, exec?.signal)
           const rows = page.records ?? []
           const total = page.hasMore ? await countRows(client, set, filter, exec?.signal).catch(() => undefined) : rows.length
-          const shown = columns ?? Object.keys(rows[0] ?? {}).filter((name) => !name.startsWith('@')).slice(0, 8)
+          const requested = columns ?? Object.keys(rows[0] ?? {}).filter((name) => !name.startsWith('@')).slice(0, 8)
+          const shown = reconcileColumns(requested, rows)
           artifact.environments[env.key] = { entitySet: set, params, total, rows }
           const head = total === undefined
             ? `${env.key}：${logical} 返回 ${rows.length} 行（可能还有更多）`
             : total === rows.length
               ? `${env.key}：${logical} 共 ${total} 行`
               : `${env.key}：已列 ${rows.length} 条 / 共 ${total} 条（未列全，加 filter 或调 top）`
-          reports.push(`${head}\n${formatTable(rows, shown, { width: 40 })}`)
+          reports.push(`${head}${costText(client.counters.requests, started)}\n`
+            + `${formatTable(rows, shown.columns, { width: 40 })}${notesText(shown.notes)}`)
           continue
         }
 
         const top = Number.isFinite(args.top) ? Math.max(1, Math.min(100, args.top)) : 5
-        const params = { $top: top }
+        const params = {}
         if (filter) params.$filter = filter
         if (args.select) params.$select = args.select
         const page = await client.getPaged(set, params, top, exec?.signal)
         const rows = page.records ?? []
-        const columns = args.select ? args.select.split(',').map((item) => item.trim()) : Object.keys(rows[0] ?? {}).slice(0, 5)
-        artifact.environments[env.key] = { entitySet: set, rows }
-        reports.push(`${env.key}：${logical} 样例 ${rows.length} 行\n${formatTable(rows, columns, { width: 32 })}`)
+        const requested = args.select
+          ? args.select.split(',').map((item) => item.trim()).filter(Boolean)
+          : Object.keys(rows[0] ?? {}).filter((name) => !name.startsWith('@')).slice(0, 5)
+        const shown = reconcileColumns(requested, rows)
+        artifact.environments[env.key] = { entitySet: set, rows, hasMore: page.hasMore }
+        const more = page.hasMore ? '（还有更多，样例只取前几条）' : ''
+        reports.push(`${env.key}：${logical} 样例 ${rows.length} 行${more}${costText(client.counters.requests, started)}\n`
+          + `${formatTable(rows, shown.columns, { width: 32 })}${notesText(shown.notes)}`)
       }
 
       const file = await writeArtifact(config, `data-${action}`, artifact)

package/lib/tool-metadata.js

@@ -210,6 +210,13 @@ function buildRequest(resource, args, config) {
 
   const keyed = keyedByName ?? keyedByAttribute
 
+  const path = keyed ?? def.path(args)
+  // The definition endpoints reject `$top` with 0x80060888 "The query
+  // parameter ... is not supported", and `getPaged` adds `$top` unless told not
+  // to — so without this every such query pays one wasted 400 before the
+  // fallback notices. Declaring it up front removes a whole round trip.
+  const rejectsTop = /^(entitydefinitions|relationshipdefinitions|globaloptionsetdefinitions)\b/i.test(path)
+
   const select = [def.select, args.select]
     .filter(Boolean)
     .join(',')
@@ -222,7 +229,7 @@ function buildRequest(resource, args, config) {
     : def.defaultTop ?? config.maxRecords
 
   return {
-    path: keyed ?? def.path(args),
+    path,
     keyed: Boolean(keyed),
     top,
     params: {
@@ -232,6 +239,7 @@ function buildRequest(resource, args, config) {
       $filter: keyed ? undefined : composeFilter(def, args),
       $orderby: keyed ? undefined : (args.orderby ?? def.orderby),
       $expand: keyed ? undefined : (args.expand ?? def.expand),
+      __noTop: !keyed && rejectsTop ? true : undefined,
     },
   }
 }
@@ -279,6 +287,7 @@ async function queryEnvironment(env, config, args, signal) {
   const client = makeClient(env, config)
   const started = Date.now()
   let selectDropped = false
+  let droppedFields = []
   let page
   if (request.keyed) {
     // Keyed metadata reads answer with a bare object (no `value` wrapper) and
@@ -305,6 +314,7 @@ async function queryEnvironment(env, config, args, signal) {
     const paged = await getPagedWithSelectFallback(client, request.path, request.params, request.top, signal)
     page = paged.page
     selectDropped = paged.selectDropped
+    droppedFields = paged.droppedFields ?? []
   }
   const rows = page.records.map((row) => flattenExpanded(flattenLabels(row)))
   // The organization table has no portable `version` column; take it from the
@@ -321,6 +331,7 @@ async function queryEnvironment(env, config, args, signal) {
     hasMore: page.hasMore,
     limit: request.top,
     selectDropped,
+    droppedFields,
     requests: client.counters.requests,
     elapsedMs: Date.now() - started,
     filter: request.params.$filter,
@@ -357,7 +368,8 @@ export function register(ctx, state) {
         const totalText = result.hasMore && typeof result.total === 'number'
           ? `已列 ${result.rows.length} 条 / 共 ${result.total >= 5000 ? '≥5000' : result.total} 条（未列全，加 filter 或 top 缩小）`
           : `${result.rows.length} 行${result.hasMore ? `（已达上限 ${result.limit}，还有更多；加 filter 或 top 缩小）` : ''}`
-        lines.push(`### ${result.env.key} — ${totalText}`)
+        const seconds = Math.max(0, result.elapsedMs ?? 0) / 1000
+        lines.push(`### ${result.env.key} — ${totalText}（${result.requests ?? 0} 请求 / ${seconds.toFixed(1)}s）`)
         if (!result.rows.length) {
           lines.push(args.name
             ? `该环境没有名为 ${args.name} 的${def?.summary ?? resource}（按名称直取返回 404）。`
@@ -366,7 +378,11 @@ export function register(ctx, state) {
         }
         const columns = displayColumns(resource, result.rows, args.select)
         lines.push(formatTable(result.rows, columns, { limit: INLINE_ROWS }))
-        if (result.selectDropped) lines.push('（该环境不接受部分 $select 列，已自动去掉后重试，故列数可能偏少）')
+        if (result.droppedFields?.length) {
+          lines.push(`（这些列该环境不认，已去掉：${result.droppedFields.join('、')}）`)
+        } else if (result.selectDropped) {
+          lines.push('（该环境不接受部分 $select 列，已自动去掉后重试，故列数可能偏少）')
+        }
       }
 
       const comparison = compareEnvironments(resource, results.map((result) => ({ env: result.env, rows: result.rows })))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-d365-kit",
-  "version": "0.34.4",
+  "version": "0.34.5",
   "type": "module",
   "description": "Dynamics 365 CE developer and deployment toolkit for DSH: metadata, layers, snapshots, migration risk, code checks, contract drift, environment health, plug-in traces, message invocation and business-record sync.",
   "license": "MIT",