dsh-d365-kit 0.0.0-stage → 0.34.3

package/README.md

@@ -1,3 +1,336 @@
-# Temporary Holding Version
+# dsh-d365-kit (D365 Toolkit)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** | [简体中文](README.zh-CN.md)
+
+A **development and deployment assistant** for Dynamics 365 CE / Dataverse, installed as a [DeepSeek Harness](https://github.com/deepseek-ai) bundle.
+It turns a real D365 organization into something an agent can query directly: metadata, solution layers, snapshot diffs, references, migration risk, the impact of code changes, and controlled writes.
+
+> Nineteen tools, one settings page. Read-only by default: tick a capability and it may do exactly that — even metadata reads are a tick of "Read metadata", on by default.
+
+```
+You: which forms and views still use the contoso_customertier field on account in DEV?
+agent: 17 forms, 64 views (62 columns / 50 filters), 0 business processes …
+```
+
+---
+
+## What problem it solves
+
+Most day-to-day friction in D365 projects is not "can't write code", it is **information asymmetry between environments**:
+
+| Problem | How this plugin answers |
+| --- | --- |
+| If I ship this solution to SIT, will it override another solution's customizations? | `d365_migrate` checks layers component by component, listing the solutions that will be shadowed, the components that are missing, and the option values that will be lost |
+| Why is the same form different in two environments? | `d365_layers` tells you who overrode it, `d365_diff` gives you the field-level differences |
+| Will deleting this field break something? | `d365_refs` reverse-looks-up forms / views / processes / plugin steps, `d365_data` shows how many records still use it |
+| Will this MR run once deployed to UAT? | `d365_code_check` maps JS to web resources and forms, and C# to assemblies/types/steps/images |
+| Upstream changed a plugin — has downstream caught up? | `d365_contract` treats upstream registrations as a contract and compares them item by item downstream, with waivers and trends |
+| Can we deploy right now? | `d365_health` shows suspended imports/publishes and failed jobs; the pre-flight check before writes uses the same data |
+| Need to add a field / option value / view column? | `d365_write` produces a plan → a human confirms in the conversation → only then does it write, with a queryable audit trail afterwards |
+
+---
+
+## Feature overview
+
+### Connectivity and environments
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_envs` | Environment inventory, whether credentials are complete; with `check: true` it actually connects once |
+| `d365_configure` | Add, edit or remove environments (URL, tenant, ClientId, secret), test connectivity |
+| `d365_health` | Suspended/failed background jobs, in-progress import publishes, recently installed solutions |
+
+### Metadata and solution layers
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_metadata` | 19 resource kinds: entities, attributes, relationships, forms, views, workflows, business rules, plugins, web resources, solutions, components, Custom APIs, sitemaps, option sets |
+| `d365_layers` | `msdyn_componentlayer`: which solutions have overridden a component, who is on top, and which layer is currently active |
+
+### Snapshots and diff
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_sync` | Pulls an environment's metadata into a local snapshot, recording "complete / truncated / failed" per resource |
+| `d365_diff` | Field-level differences between two snapshots (added, removed, modified), with noise filtering and a stale-snapshot warning |
+
+### Impact and data
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_refs` | Reverse lookup: field → forms/views/processes; web resource → forms and events; assembly → types and steps |
+| `d365_data` | Business records: count / group by / sample (requires `data.read`) |
+| `d365_data_write` | Create or update one business record, executed after confirmation in the conversation (requires `data.write`) |
+| `d365_data_sync` | Mirror records between environments (keeps GUIDs, resolves lookups, reports conflicts), or update one field on a list of records |
+
+### Writes
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_write` | Add/update/delete option values, add/update/delete fields, rename a table, add or remove system view columns; `plan-*` only produces a plan, `execute` requires manual confirmation |
+
+### Migration and checks
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_migrate` | Solution migration risk assessment: layer shadowing, missing components, lost option values, version and managed state |
+| `d365_contract` | Contract matrix and drift: assemblies, plugin types, steps, form libraries, handlers, sitemaps, option values; with waivers and trends |
+| `d365_code_check` | Reads a GitLab MR, maps JS/C# changes onto the target environment and reports blocker / warning / manual confirmation |
+
+### Diagnostics
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_trace` | Plug-in trace logs: what ran, what threw, grouped by signature; credentials in the message block are masked (requires `data.read`) |
+| `d365_invoke` | Call one Dataverse message and see the real status and body; GET functions need `data.read`, POST actions need `message.invoke` plus a confirmation each time |
+| `d365_flows` | Power Automate cloud flows (`workflow` rows with `category = 5`): catalog, one flow's trigger/actions/connectors, and which flows touch a given table |
+
+### Operations
+
+| Tool | Purpose |
+| --- | --- |
+| `d365_reports` | Local artifacts and disk usage, cleanup per retention policy (dry run by default), snapshot compaction |
+
+---
+
+## Settings page
+
+"Settings → D365 Toolkit" in the DSH Web UI, six tabs:
+
+| Tab | Contents |
+| --- | --- |
+| Environments | Environment inventory, test connection, default environment |
+| Permissions | Tick capabilities per environment (read business data / write kinds), default solution for changes, copy to other environments |
+| Plans | Pending write plans, recent change records and publish results (re-publishable) |
+| Data | File count / size / retention policy per artifact kind, dry run and cleanup, snapshot compaction |
+| GitLab | Repository URL, default project, read-only token (`read_api`) |
+| General | Snapshots to keep, default row limit, request timeout |
+
+The UI language follows DSH (Chinese / English). The environment inventory and `d365_configure` go through the same storage code, so what the UI shows and what the agent sees always match.
+
+---
+
+## Installation
+
+Prerequisites: DSH desktop; network access to `*.dynamics.com`; a read-only application user (ClientId + secret).
+
+```bash
+# From npm (shortest, upgradeable; works once the package is published)
+plugin_manager install_bundle target="dsh-d365-kit@0.34.3"
+
+# From Git (no registry needed, pin a tag)
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.3"
+
+# From a local directory (link: code changes take effect immediately)
+plugin_manager install_bundle target="D:\path\to\dsh-d365-kit"
+```
+
+`dsh-d365-kit@<version>` is resolved from the **npm registry**; a GitHub repository alone is reachable through the `git+https://` form (that is how the second command works today). `.github/workflows/publish.yml` publishes to npm **on every push to `main` whose `package.json` version is not on the registry yet** — bump the version, push, and npm gets it; push without a bump and the job exits green without doing anything. A `v*` tag is optional and only acts as a consistency check (it must equal the version in `package.json`).
+
+Publishing needs one of two credentials, and the workflow stays a no-op until one exists:
+
+| Auth | What to configure | Secret on disk |
+| --- | --- | --- |
+| Trusted publishing (recommended) | repo variable `NPM_TRUSTED_PUBLISHING = true`, plus a trusted publisher on npmjs.com pointing at this repo and workflow file | none |
+| Granular token | repo secret `NPM_TOKEN` (needs "Bypass two-factor authentication" to publish) | a token you must rotate |
+
+Trusted publishing is the one to prefer: the token path is exactly the thing that leaks into logs and chat transcripts.
+
+After installing, **restart DSH once** so the web client loads the settings page code into its module graph.
+
+Then: Settings → D365 Toolkit → Environments → Add environment (key, URL, tenant, ClientId, secret) → Test connection → Save.
+Read-only by default; to read business records, tick "Read business data" under "Permissions".
+
+For full steps, credential resolution order, upgrade and uninstall, see [docs/en/installation.md](docs/en/installation.md).
+
+---
+
+## Typical usage
+
+### 1. Assess a solution before deploying
+
+```
+What are the risks of shipping this solution to SIT and UAT?
+
+d365_migrate action=assess source=dev solution=ContosoBase targets=["sit","uat"]
+```
+
+The report answers: does the target already have this solution, is the source version higher, whose layers will sit on top of each component (listing the shadowed solutions), and will option sets lose values. It lands in `.d365/reports/migration-*.md`.
+
+### 2. Can this field be deleted
+
+```
+Who else still uses account.contoso_customertier? Also check how many records carry a value.
+
+d365_refs   kind=field entity=account attribute=contoso_customertier
+d365_data   action=group entity=account field=contoso_customertier
+```
+
+### 3. Why two environments differ
+
+```
+d365_sync environments=["dev","sit"]
+d365_diff base=dev head=sit resources=["forms","views","attributes"]
+d365_layers component=Account componentType=SystemForm
+```
+
+### 4. Check whether an MR can ship to UAT
+
+```
+d365_code_check mergeRequest="https://gitlab.example.com/contoso/powerapps/-/merge_requests/7759/diffs" targets=["uat"]
+```
+
+JS changes are mapped to web resources and forms, checking whether the fields they read are on the form and whether deleted functions are still referenced by a handler;
+C# changes are checked against assembly version, plugin types, steps, step images and filtering attributes. Anything that cannot be decided statically goes into the "manual confirmation" list.
+
+### 5. Add 36 tax ID option values (the full write flow)
+
+```
+d365_write action=plan-add-options environment=dev optionSet=contoso_taxcategoryos labels=["AD3|Andorra: Tax Register Number", ...]
+
+(the agent returns the plan and the operation list)
+Run mw04aul6-1ci6aa
+```
+
+The second step pops a confirmation card in the conversation; nothing is written until you click "Approve and execute". After writing, only the affected option set is published — the whole organization is not recalculated.
+
+### 6. Upstream plugins changed — what is downstream missing
+
+```
+d365_contract action=drift source=dev targets=["sit","uat"] forms=true
+```
+
+For more phrasings you can copy straight into a conversation, see [examples/prompts.en.md](examples/prompts.en.md) and [docs/en/scenarios.md](docs/en/scenarios.md).
+
+---
+
+## Permission model
+
+By default **read-only**. Capabilities are granted per environment and live in `write.environments` of `d365.config.json`; the settings page renders one block per environment, separated by a rule:
+
+```json
+{
+  "write": {
+    "capabilityVersion": 2,
+    "environments": {
+      "dev": ["metadata.read", "data.read", "optionValue.add", "attribute.add"],
+      "sit": ["metadata.read", "data.read"]
+    },
+    "solutionUniqueName": "ContosoBase"
+  }
+}
+```
+
+An environment with no entry has never been configured and gets only `metadata.read`; an empty array revokes everything.
+
+| Capability | Operation | Effect |
+| --- | --- | --- |
+| `metadata.read` | metadata `GET` | Read tables / fields / forms / views / plugins / layers (on by default) |
+| `data.read` | business-data `GET` | Read business records; without it the records in tables are unreadable |
+| `data.write` | `POST` / `PATCH` | Create or update business records (no delete) |
+| `optionValue.add` | `InsertOptionValue` | Add an option value (global or attribute-local) |
+| `optionValue.updateLabel` | `UpdateOptionValue` | Change an option label |
+| `optionValue.delete` | `DeleteOptionValue` | Permanently delete an option value (high risk) |
+| `attribute.add` | `CreateAttribute` | Add a field |
+| `attribute.update` | `UpdateAttribute` | Change a field's display name / description / required level |
+| `attribute.delete` | `DeleteAttribute` | Permanently delete a field and its data (high risk) |
+| `entity.update` | `UpdateEntity` | Change a table's display name and description |
+| `view.columns` | `UpdateSavedQuery` | Add or remove system view columns |
+| `layer.remove` | `RemoveActiveCustomizations` | Remove a component's top-most unmanaged layer (high risk) |
+
+Writes take two steps: `plan-*` generates a plan read-only → a human confirms in the conversation (or the settings page) → `execute`. Before execution it checks whether the environment is importing/publishing and refuses if it is busy; every execution is recorded item by item in `.d365/changes/`, plans move through `pending → running → done/failed`, and a re-run does not submit twice.
+
+The decision lives in one place, `lib/client.js`: metadata requests need `metadata.read`, every other `GET` is blocked as business data unless `data.read` is granted, and writes additionally need `data.write`. All of it happens before the token is fetched, so a new tool cannot bypass these gates.
+
+See [docs/en/permissions.md](docs/en/permissions.md) for details.
+
+---
+
+## Local artifacts
+
+```
+<workspace>/
+  d365.config.json          # environment inventory and tool parameters (can be committed)
+  d365.secrets.json         # client secret (plaintext — do not commit)
+  .d365/
+    snapshots/<env>/<id>/   # metadata snapshots + manifest
+    diffs/                  # diff reports
+    reports/                # migration, contract, code check, historical trends
+    query/                  # query evidence, data write audit
+    pending-writes/         # pending plans
+    changes/                # executed changes and publish results
+    waivers.json            # contract waivers
+```
+
+`.d365/` ships its own `.gitignore` (contents `*`). Default retention: snapshots 2 files/30 days, reports 50/90, diff 20/30, query 100/7, changes 200/180; cleanup runs automatically after artifacts are written, and `waivers.json` plus pending plans are never cleaned up.
+
+---
+
+## Documentation
+
+| Document | Contents |
+| --- | --- |
+| [docs/en/installation.md](docs/en/installation.md) | Installation, first-time setup, credentials, upgrade, uninstall |
+| [docs/en/tools.md](docs/en/tools.md) | Parameters, return values and examples for the 19 tools |
+| [docs/en/scenarios.md](docs/en/scenarios.md) | Complete walkthroughs for 8 real scenarios |
+| [docs/en/permissions.md](docs/en/permissions.md) | Capability table, write flow, pre-flight check, safety boundary |
+| [docs/en/checks.md](docs/en/checks.md) | Rules and confidence levels for migration assessment, contract drift and code checks |
+| [docs/en/troubleshooting.md](docs/en/troubleshooting.md) | Common error codes and troubleshooting |
+| [skills/d365-troubleshooting/SKILL.md](skills/d365-troubleshooting/SKILL.md) | Agent skill: how to work a plug-in failure from trace to reproduction (registered by the plugin, no copy needed) |
+| [docs/en/architecture.md](docs/en/architecture.md) | Module layout, data flow, how to add a tool |
+| [CHANGELOG.md](CHANGELOG.md) | Version history |
+
+---
+
+## Known limitations
+
+- Does not collect Ribbon or Power Automate cloud flows.
+- `attributes` is requested per entity, so with many entities the request count equals the entity count; use `entities` to narrow the scope.
+- Metadata tables mostly have no incremental cursor, so every sync is a full pull; a delta is only possible by "running it a second time, then diffing".
+- `d365_layers` relies on the `msdyn_componentlayer` virtual table: you must supply both the component id and the type; a name alone returns 0 rows.
+- Component types 36 / 50 / 70 (report and chart kinds) have no matching name in the layer table, so only their existence is checked.
+- Layer order is determined by **import time**, not version number: whoever imported later is on top.
+- `secureconfiguration` always reads back empty through the Web API, so plugin secure config can only be confirmed manually.
+- Contract drift reads live data (not snapshots) and takes tens of seconds to a few minutes on a large environment.
+
+---
+
+## Development
+
+```
+index.js              # Host entry: registers the 19 tools, mounts the settings page routes
+client.js             # settings page (six tabs, no build step)
+lib/
+  client.js           # Dataverse Web API client (retry, paging, permission gate)
+  auth.js             # Entra ID client credentials flow + token cache
+  config.js           # config loading and normalization
+  resources.js        # query definitions for the 19 metadata resource kinds
+  write-actions.js    # planner / executor for all write operations
+  contract.js         # contract matrix and drift rules
+  migrate.js          # migration assessment
+  code-check.js       # MR check (JS)
+  csharp-check.js     # MR check (C#)
+  refs.js             # reverse index
+  retention.js        # retention policy and disk cleanup
+  ...
+```
+
+Zero runtime dependencies: only Node's built-in `fetch` / `fs` / `path`. After changes, validate each file with `node --check`; host-side changes take effect only after reloading the plugin (`plugin_manager set_plugin enabled=false` then `true`), client code needs a page refresh.
+
+Conventions for a new tool: `parameters` and `output.schema` both use standard JSON Schema; return "summary + file path" and write the body to a file; after registering, add it to the disposers in `index.js`.
+
+---
+
+## Status
+
+An internal tool, evolving with project needs. Version semantics: bug fixes bump patch, new tools/capabilities bump minor, config structure changes bump major.
+
+Environment configuration and secrets are not shipped with the package; each machine fills in `d365.config.json` and `d365.secrets.json` itself.
+
+---
+
+## License
+
+[MIT](LICENSE) © 2026 iTanzhao
+
+Use it, change it, ship it — keep the copyright notice. No warranty, no trademark rights.

package/README.zh-CN.md

@@ -0,0 +1,336 @@
+# dsh-d365-kit（D365 工具箱）
+
+**[English](README.md)** | 简体中文
+
+Dynamics 365 CE / Dataverse 的**开发与部署助手**，作为 [DeepSeek Harness](https://github.com/deepseek-ai) 的 bundle 安装。
+它把一个真实的 D365 组织变成 agent 能直接查的东西：元数据、解决方案层、快照差异、引用关系、迁移风险、代码改动的影响面，以及受控的写入。
+
+> 十九个工具、一个设置页。默认只读：勾选什么就只做什么，元数据也由「读取元数据」这一项控制（默认开启）。
+
+```
+你：DEV 的 account 上 contoso_customertier 这个字段，现在还有哪些表单和视图在用它？
+agent：表单 17 张、视图 64 个（列 62 / 筛选 50）、业务流程 0 个 …
+```
+
+---
+
+## 它解决什么问题
+
+D365 项目的日常摩擦，大多不是"不会写代码"，而是**环境之间的信息不对称**：
+
+| 问题 | 这个插件怎么答 |
+| --- | --- |
+| 这个解决方案发到 SIT，会不会把别的解决方案的定制压掉？ | `d365_migrate` 逐组件查层，列出会被遮蔽的解决方案、缺失的组件、会丢的选项值 |
+| 为什么两个环境的同一张表单不一样？ | `d365_layers` 告诉你是谁覆盖了它，`d365_diff` 给出字段级差异 |
+| 删这个字段会不会出事？ | `d365_refs` 反查表单 / 视图 / 流程 / 插件步骤，`d365_data` 看还有多少条记录在用 |
+| 这个 MR 发布到 UAT 能跑起来吗？ | `d365_code_check` 把 JS 映射到 Web 资源与表单、把 C# 映射到程序集/类型/步骤/镜像 |
+| 上游改了插件，下游跟上了吗？ | `d365_contract` 把上游注册当契约，逐条比对下游，带豁免与趋势 |
+| 现在能发布吗？ | `d365_health` 看挂起的导入/发布与失败作业，写入前的预检查用的是同一份数据 |
+| 补一个字段 / 选项值 / 视图列？ | `d365_write` 生成计划 → 人在对话里确认 → 才写入，事后可查审计 |
+
+---
+
+## 功能一览
+
+### 连接与环境
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_envs` | 环境清单、凭据是否齐全；`check: true` 时真实连一次 |
+| `d365_configure` | 增删改环境（URL、租户、ClientId、密钥）、测连通性 |
+| `d365_health` | 挂起/失败的后台作业、正在进行的导入发布、最近安装的解决方案 |
+
+### 元数据与解决方案层
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_metadata` | 19 类资源：实体、字段、关系、表单、视图、工作流、业务规则、插件、Web 资源、解决方案、组件、Custom API、站点地图、选项集 |
+| `d365_layers` | `msdyn_componentlayer`：某组件被哪些解决方案覆盖过、谁在最上层、当前生效的是哪一层 |
+
+### 快照与对比
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_sync` | 把环境的元数据拉成本地快照，逐资源记录「完整 / 被截断 / 失败」 |
+| `d365_diff` | 两份快照的字段级差异（新增、删除、修改），带噪声过滤与快照过期提示 |
+
+### 影响面与数据
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_refs` | 反查：字段 → 表单/视图/流程；Web 资源 → 表单与事件；程序集 → 类型与步骤 |
+| `d365_data` | 业务记录 count / group by / sample（需授权 `data.read`） |
+| `d365_data_write` | 新建或修改一条业务记录，对话确认后执行（需 `data.write`） |
+| `d365_data_sync` | 环境之间镜像记录（保持 GUID、解析 lookup、报告冲突），或按 id 清单批量改一个字段 |
+
+### 写入
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_write` | 选项集增/改/删值、新增/改/删字段、改表显示名、增删系统视图列；`plan-*` 只出计划，`execute` 必须人工确认 |
+
+### 迁移与检查
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_migrate` | 解决方案迁移风险评估：层遮蔽、组件缺失、选项值丢失、版本与受管状态 |
+| `d365_contract` | 契约矩阵与漂移：程序集、插件类型、步骤、表单库、Handler、站点地图、选项值；带豁免与趋势 |
+| `d365_code_check` | 读 GitLab MR，JS/C# 改动 → 目标环境核对，输出阻断 / 警告 / 人工确认 |
+
+### 排查
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_trace` | 插件跟踪日志：谁跑了、抛了什么、按签名归并；messageblock 里的凭据会屏蔽（需 `data.read`） |
+| `d365_invoke` | 真正调一次 Dataverse 消息，看状态码与响应体；GET function 需 `data.read`，POST action 需 `message.invoke` 且每次确认 |
+| `d365_flows` | Power Automate 云流（`workflow` 表 `category = 5`）：目录、单条流程的触发器/动作/连接器、哪些流程会碰某张表 |
+
+### 运维
+
+| 工具 | 用途 |
+| --- | --- |
+| `d365_reports` | 本机产物与占用、按保留策略清理（默认预演）、压缩快照 |
+
+---
+
+## 设置页
+
+DSH Web UI 的「设置 → D365 工具箱」，六个标签页：
+
+| 标签 | 内容 |
+| --- | --- |
+| 环境 | 环境清单、测试连接、默认环境 |
+| 权限 | 按环境勾选能力（读业务数据 / 写入类）、变更默认解决方案、复制到其它环境 |
+| 计划 | 待确认的写入计划、最近的变更记录与发布结果（可重新发布） |
+| 数据 | 每类产物的文件数 / 体积 / 保留策略，预演并清理，压缩快照 |
+| GitLab | 仓库地址、默认项目、只读令牌（`read_api`） |
+| 常规 | 快照保留份数、默认行数上限、请求超时 |
+
+界面语言跟随 DSH（中文 / English）。环境清单与 `d365_configure` 走同一份存储代码，界面和 agent 看到的一定一致。
+
+---
+
+## 安装
+
+前置：DSH 桌面版；机器能访问 `*.dynamics.com`；一个只读应用用户（ClientId + 密钥）。
+
+```bash
+# 从 npm 安装（最短，可升级；包发布到 npm 或内网 registry 后可用）
+plugin_manager install_bundle target="dsh-d365-kit@0.34.3"
+
+# 从 Git 安装（不需要 registry，可钉 tag）
+plugin_manager install_bundle target="git+https://<your-git>/<group>/dsh-d365-kit.git#v0.34.3"
+
+# 或从本地目录安装（link，改代码立刻生效）
+plugin_manager install_bundle target="D:\path\to\dsh-d365-kit"
+```
+
+`dsh-d365-kit@<版本>` 是从 **npm registry** 解析的；只发到 GitHub 时，用第二条的 `git+https://` 形式装。`.github/workflows/publish.yml` 会在**每次推 `main` 且 `package.json` 里的版本还没上架时**发布到 npm —— 改版本号、推送，npm 就有了；没改版本号再推，任务绿着退出、什么都不做。`v*` tag 可选，只用来做一致性校验（必须等于 `package.json` 的版本）。
+
+发布需要下面两种凭据之一，两种都没配时工作流是空转的：
+
+| 认证方式 | 要配什么 | 磁盘上的密钥 |
+| --- | --- | --- |
+| Trusted publishing（推荐） | 仓库变量 `NPM_TRUSTED_PUBLISHING = true`，再在 npmjs.com 上把 trusted publisher 指到本仓库和这个 workflow 文件 | 无 |
+| Granular token | 仓库 secret `NPM_TOKEN`（要能发布必须勾「Bypass two-factor authentication」） | 一个你需要轮换的 token |
+
+优先用 trusted publishing：token 那条路正是会漏进日志和聊天记录的东西。
+
+装完**重启一次 DSH**，Web 客户端才会把设置页代码加载进模块图。
+
+然后：设置 → D365 工具箱 → 环境 → 添加环境（key、URL、租户、ClientId、密钥）→ 测试连接 → 保存。
+默认只读；要读业务记录，去「权限」勾「读取业务数据」。
+
+完整步骤、凭据解析顺序、升级与卸载见 [docs/installation.md](docs/zh/installation.md)。
+
+---
+
+## 典型用法
+
+### 1. 发布前评估一个解决方案
+
+```
+这个解决方案发到 SIT 和 UAT 有什么风险？
+
+d365_migrate action=assess source=dev solution=ContosoBase targets=["sit","uat"]
+```
+
+报告回答：目标有没有这个解决方案、源版本是不是更高、每个组件的层会被谁压住（列出被遮蔽的解决方案）、选项集会不会丢值。落在 `.d365/reports/migration-*.md`。
+
+### 2. 这个字段能删吗
+
+```
+account.contoso_customertier 还有谁在用？顺便看下还有多少条记录带着值。
+
+d365_refs   kind=field entity=account attribute=contoso_customertier
+d365_data   action=group entity=account field=contoso_customertier
+```
+
+### 3. 两个环境为什么不一样
+
+```
+d365_sync environments=["dev","sit"]
+d365_diff base=dev head=sit resources=["forms","views","attributes"]
+d365_layers component=Account componentType=SystemForm
+```
+
+### 4. 检查一个 MR 能不能发到 UAT
+
+```
+d365_code_check mergeRequest="https://gitlab.example.com/contoso/powerapps/-/merge_requests/7759/diffs" targets=["uat"]
+```
+
+JS 改动会映射到 Web 资源与表单，检查读取的字段是否在表单上、删除的函数是否仍被 Handler 引用；
+C# 改动会核对程序集版本、插件类型、步骤、step 镜像与过滤属性。静态判不了的进「人工确认」清单。
+
+### 5. 补 36 个税号选项（写入全流程）
+
+```
+d365_write action=plan-add-options environment=dev optionSet=contoso_taxcategoryos labels=["AD3|Andorra: Tax Register Number", ...]
+
+（agent 返回计划与操作列表）
+执行 mw04aul6-1ci6aa
+```
+
+第二步会在对话里弹确认卡片，点「批准执行」才写入；写入后只发布受影响的那个选项集，不重算整个组织。
+
+### 6. 上游插件改了，下游还缺什么
+
+```
+d365_contract action=drift source=dev targets=["sit","uat"] forms=true
+```
+
+更多可直接复制的说法见 [examples/prompts.md](examples/prompts.zh-CN.md) 与 [docs/scenarios.md](docs/zh/scenarios.md)。
+
+---
+
+## 权限模型
+
+默认**只读**。能力按环境授权，存在 `d365.config.json` 的 `write.environments`；设置页里每个环境单独一块，用分隔线隔开：
+
+```json
+{
+  "write": {
+    "capabilityVersion": 2,
+    "environments": {
+      "dev": ["metadata.read", "data.read", "optionValue.add", "attribute.add"],
+      "sit": ["metadata.read", "data.read"]
+    },
+    "solutionUniqueName": "ContosoBase"
+  }
+}
+```
+
+环境没有条目 = 还没配过，默认只开 `metadata.read`；条目是空数组 = 全关。
+
+| 能力 | 对应操作 | 作用 |
+| --- | --- | --- |
+| `metadata.read` | 元数据 `GET` | 读表 / 字段 / 表单 / 视图 / 插件 / 层（默认开启） |
+| `data.read` | 业务数据 `GET` | 读业务记录；不授权时读不到表里的记录 |
+| `data.write` | `POST` / `PATCH` | 新建或修改业务记录（不含删除） |
+| `optionValue.add` | `InsertOptionValue` | 新增选项值（全局或字段本地） |
+| `optionValue.updateLabel` | `UpdateOptionValue` | 改选项标签 |
+| `optionValue.delete` | `DeleteOptionValue` | 永久删除选项值（高危） |
+| `attribute.add` | `CreateAttribute` | 新增字段 |
+| `attribute.update` | `UpdateAttribute` | 改字段显示名 / 描述 / 必填级别 |
+| `attribute.delete` | `DeleteAttribute` | 永久删除字段及其数据（高危） |
+| `entity.update` | `UpdateEntity` | 改表显示名与描述 |
+| `view.columns` | `UpdateSavedQuery` | 增删系统视图的列 |
+| `layer.remove` | `RemoveActiveCustomizations` | 移除组件最上面的未受管自定义层（高危） |
+
+写入是两步：`plan-*` 只读生成计划 → 人在对话（或设置页）确认后 `execute`。执行前会查环境是否正在导入/发布，忙则拒绝；每次执行逐条记进 `.d365/changes/`，计划有 `pending → running → done/failed` 状态，重跑不会重复提交。
+
+判定收在 `lib/client.js` 一处：先看是不是元数据请求（要 `metadata.read`），其余 `GET` 一律按业务数据拦截（要 `data.read`），非 `GET` 的写还要 `data.write`。拦截发生在取令牌之前，新增工具绕不过这三道闸。
+
+详见 [docs/permissions.md](docs/zh/permissions.md)。
+
+---
+
+## 本地产物
+
+```
+<工作区>/
+  d365.config.json          # 环境清单与工具参数（可进 Git）
+  d365.secrets.json         # 客户端密钥（明文，别提交）
+  .d365/
+    snapshots/<env>/<id>/   # 元数据快照 + manifest
+    diffs/                  # 对比报告
+    reports/                # 迁移、契约、代码检查、历史趋势
+    query/                  # 查询留证、数据写入审计
+    pending-writes/         # 待确认计划
+    changes/                # 已执行的变更与发布结果
+    waivers.json            # 契约豁免
+```
+
+`.d365/` 自带 `.gitignore`（内容 `*`）。保留策略默认：快照 2 份/30 天、报告 50/90、diff 20/30、query 100/7、changes 200/180，写产物后自动清理，`waivers.json` 与待确认计划永不清理。
+
+---
+
+## 文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [docs/installation.md](docs/zh/installation.md) | 安装、首次配置、凭据、升级、卸载 |
+| [docs/tools.md](docs/zh/tools.md) | 19 个工具的参数、返回与示例 |
+| [docs/scenarios.md](docs/zh/scenarios.md) | 8 个真实场景的完整走法 |
+| [docs/permissions.md](docs/zh/permissions.md) | 能力表、写入流程、预检查、安全边界 |
+| [docs/checks.md](docs/zh/checks.md) | 迁移评估、契约漂移、代码检查的规则与置信度 |
+| [docs/troubleshooting.md](docs/zh/troubleshooting.md) | 常见错误码与排查 |
+| [skills/d365-troubleshooting/SKILL.md](skills/d365-troubleshooting/SKILL.md) | Agent skill：从跟踪日志到复现调用的排查流程（插件自己注册，不用复制） |
+| [docs/architecture.md](docs/zh/architecture.md) | 模块结构、数据流、如何加一个工具 |
+| [CHANGELOG.md](CHANGELOG.zh-CN.md) | 版本记录 |
+
+---
+
+## 已知边界
+
+- 不采 Ribbon 与 Power Automate 云流。
+- `attributes` 按实体逐个请求，实体多时请求量等于实体数；用 `entities` 缩小范围。
+- 元数据表基本没有增量游标，每次同步都是全量；增量只能「跑第二次然后 diff」。
+- `d365_layers` 依赖 `msdyn_componentlayer` 虚拟表：必须同时给组件 id 与类型，只给名字返回 0 行。
+- 组件类型 36 / 50 / 70（报表、图表类）在层表里没有对应名称，只做存在性检查。
+- 层叠顺序由**导入时间**决定，与版本号无关：谁后导入谁在上。
+- `secureconfiguration` 经 Web API 读回恒为空，插件 secure config 只能人工确认。
+- 契约漂移读实时数据（不是快照），环境大时一次几十秒到几分钟。
+
+---
+
+## 开发
+
+```
+index.js              # Host 入口：注册 19 个工具、挂设置页路由
+client.js             # 设置页（六个标签，无构建步骤）
+lib/
+  client.js           # Dataverse Web API 客户端（重试、分页、权限闸）
+  auth.js             # Entra ID 客户端凭据流 + 令牌缓存
+  config.js           # 配置加载与归一化
+  resources.js        # 19 类元数据资源的查询定义
+  write-actions.js    # 全部写操作的 planner / executor
+  contract.js         # 契约矩阵与漂移规则
+  migrate.js          # 迁移评估
+  code-check.js       # MR 检查（JS）
+  csharp-check.js     # MR 检查（C#）
+  refs.js             # 反向索引
+  retention.js        # 保留策略与磁盘清理
+  ...
+```
+
+零运行时依赖：只用 Node 内置的 `fetch` / `fs` / `path`。改完用 `node --check` 逐个文件验证；Host 侧改动需要重载插件才会生效（`plugin_manager set_plugin enabled=false` 再 `true`），客户端代码需要刷新页面。
+
+新增工具的约定：`parameters` 与 `output.schema` 都写标准 JSON Schema；返回「摘要 + 文件路径」，正文落文件；注册后加入 `index.js` 的 disposers。
+
+---
+
+## 状态
+
+内部工具，按项目需要演进。版本语义：修 bug 升 patch，加工具/加能力升 minor，改配置结构升 major。
+
+不随包提供环境配置与密钥；`d365.config.json` 与 `d365.secrets.json` 由每台机器自己填。
+
+---
+
+## 许可证
+
+[MIT](LICENSE) © 2026 iTanzhao
+
+可以随意使用、修改、分发，保留版权声明即可。不提供担保，也不授予商标使用权。