Harden public package installation and release validation

docs/INSTALL.md

@@ -1,114 +1,84 @@
-# Install Netx Ops on DeepSeek Harness
+# 安装 Netx Ops
 
-## What `dsh plugin add` gives you
+## 桌面版
 
-One install wires **all of**:
+打开 Harness 的插件管理页面，选择“添加插件”，填入：
 
-| Piece | How you use it |
-|-------|----------------|
-| Host tools | Capability groups **ops / topology / biz-monitor**. Each group targets Netx Ops, selected other presets, or all presets; tools and skills share the policy. A master switch revokes all Netx publication. Defaults: ops+bizMonitor in Netx Ops, all public off. |
-| Companion plugins | **dsh-im-ops** + **dsh-ops-cron** — add as **direct** profile deps in the same command (DSH/pnpm blocks `github:` as transitive deps) |
-| Plugins card | Settings → Plugins → **Netx Ops** (URL / API lang / thinking+reply language / token / capability groups) |
-| Agent preset + skills | Settings → Agent presets → **Netx Ops**. Host composes from **this host's** shipped **standard** + Netx Ops overlays (no preset inheritance). DSH ≥0.2 (Desktop **and** web) uses declarative `@deepseek-ai/dsh-agent-preset` rows synced into that profile's `cordis.patch.yml` (from `@deepseek-ai/dsh-web-app/presets/standard.patch.yml`). A directory under `~/.dsh/.agent-presets/netxops` is still written for older hosts, but 0.2 no longer lists it. Restart Desktop / `dsh web` once after upgrade. Playbooks follow the same group toggles |
-
-You do **not** run `link-preset.ps1` for normal use. That script is only a manual fallback.
-
-## Still required outside the npm package
-
-1. **netx API** reachable (default `http://127.0.0.1:8890`) — the data plane.
-2. **API token** with scopes matching the tools you use (`alarms:read`, `ne:read`, `ne:exec`, `biz-monitor:read`, `sql:query`, …).
-
-No local Python / `netx_mcp` install is required for DSH. (OpenClaw and other MCP hosts can still use `python -m netx_mcp` separately for NMS/CLI — **not** for biz-monitor; that is netxops host tools only.)
-
-## Clone / `pnpm install`（仓库源码）
-
-`@deepseek-ai/*` 由 **DSH Host profile** 提供，**不**声明为可从公共 registry 安装的依赖。仓库根目录 `pnpm install` 只会装公开包（如 `fflate`）。完整运行请用上面的 `dsh plugin add`，不要指望裸 clone 能从 npm 拉齐 Harness 内部包。
-
-## Desktop 本地开发（`link:` 路径安装）
-
-Desktop「添加插件」填本地目录时，会写成 `link:D:/…/netxops`。Node 从**工作区真实路径**解析 `@deepseek-ai/*`，不会走到 Desktop profile 的 `node_modules`，于是 Host 行报 `Cannot find package '@deepseek-ai/schemastery'`，插件页显示 **netxops 未运行**（预设行可能仍正常）。
-
-装完本地路径后在仓库根执行一次（把 Host 的 `@deepseek-ai/*` peer junction 进本仓库 `node_modules`）：
-
-```powershell
-bun run link:peers
-# 或 PowerShell: .\scripts\link-dsh-peers.ps1
+```text
+github:hansjone/netxops
 ```
 
-脚本优先从 `~/.dsh/profiles/node_modules` 选择一整套 peers；该目录不完整时才考虑 profile 的完整依赖集。不要单独替换某个内部包版本，混链可能使 Config 或服务上下文不兼容。
+也可填入发布包 `dsh-netxops-<版本>.tgz` 的绝对路径。面向普通用户推荐使用明确版本的发布包：安装时无需 GitHub 访问、Bun、Python、源码目录或编译步骤。不要将开发者电脑上的目录路径作为公共安装地址。
 
-然后**重启 Desktop**（或在插件页关掉再启用 dsh-netxops）。症状对照：
+安装完成后重启桌面版一次，使预设配置加载。
 
-| 现象 | 原因 |
-|------|------|
-| `Cannot find package '@deepseek-ai/schemastery'` / **netxops 未运行** | 未跑 `link:peers` |
-| **web boot: dsh-netxops failed** | 检查具体加载错误；若 peers 混链，重跑 `bun run link:peers` 后重启 |
-| `pending (waiting for service: settingsScope)` → 会话无 `netx__*` / 无 `netx-ops` | 旧客户端仍硬/软等待已删除的 `settingsScope`（DSH 0.2）；用 **≥0.1.55** 的 tgz 重装并完全重启 Desktop，勿用脏的 `link:` / 混锁 `.modules.yaml` |
-| Desktop 卡在 **Loading plugins…** / 设置页无 Netx Ops | 旧客户端 `immediately: true` 或同步 `inject(['configForms'])`；用 **≥0.1.55**（`immediately: false` + deferred poll） |
-| 无 live connection，预设内无 `netx__*` | 检查 Host 插件是否启用及其加载错误。缺少 Host 时现在停止发布，不再通过预设入口自动补回被关闭的插件。 |
+## Web 版
 
-改 Host/Client 后照常 `bun run bundle`，一般不用重装；换机器或清过本仓库 `node_modules` 才需再 `link:peers`。
-
-备选：`npm pack` 后在 Desktop「添加插件」填 **`.tgz` 绝对路径**（复制进 profile，不走 `link:`，也就不用 link peers）。
-
-当前实现：第三方运行时依赖（含 `fflate`）已打进 `lib/`；六个 agent-tools 入口为自包含包。Host 启动即发布实际策略，凭据软注入并异步补齐。缺少 Host 连接桥接时，预设入口保持关闭。
-
-插件卡使用 `settings.section` 和官方 `settings.plugin.item`，配合 deferred `configForms`。能力组支持指定其他预设、全预设公开及总开关。详情见 [工具发布与 UI 修复说明](PUBLICATION-REVIEW.zh.md)。
-
-## Install
-
-```powershell
-dsh plugin --profile web add `
-  github:hansjone/netxops `
-  github:hansjone/dsh-im-ops `
-  github:hansjone/dsh-ops-cron
-# or from DeepSeekHarness source:
-# pnpm dsh plugin --profile web add github:hansjone/netxops github:hansjone/dsh-im-ops github:hansjone/dsh-ops-cron
-dsh web   # or: pnpm dsh web
+```sh
+dsh plugin --profile web add github:hansjone/netxops
+dsh web
 ```
 
-One command, three **direct** profile bundles. Do **not** nest IM/cron under netxops — profile pnpm enables `blockExoticSubdeps`, so `github:` subdependencies fail with `ERR_PNPM_EXOTIC_SUBDEP`. If pnpm blocks a git `prepare` script, allowlist the printed package keys under `allowBuilds` in the profile’s `pnpm-workspace.yaml`, then re-run.
-
-1. **Settings → Plugins → Netx Ops** → API URL (+ token if the field is enabled).  
-   Token fallback: `scripts/set-netx-token.ps1` / `.sh`.  
-   Optional: enable **关键告警推送** so this DSH dials `ws(s)://<apiUrl>/v1/integrations/dsh-alarm/ws`. Choose **投递到 DSH 会话** and/or **投递到 WhatsApp / IM**. For IM, install `dsh-im-ops`, create a delivery target, then paste `imBotId` / `imTargetId`. The card header shows live WSS status.  
-   Optional: **导出全部会话** downloads `dsh-sessions-<host>-<utc>.zip` via `GET /api/netxops.sessions.export` (browser download; works for cloud Hosts).  
-   Capability groups: **ops + biz-monitor** default on in Netx Ops only. Use **指定其他预设** for selective publication or **对所有预设公开** for Host-wide publication. The master switch revokes all Netx tools and skills while keeping selections. These toggles auto-save and affect the next model request without a restart.
-   Optional: **知识库** — set package root (MANIFEST v1.0); default mounts `_skills/kb-*` into Netx Ops; optional public. See [KNOWLEDGE_BASE.md](KNOWLEDGE_BASE.md).
-2. Restart after install/upgrade so the bundle patch layers apply. Open Settings → **Agent presets** → **Netx Ops** should appear.
-   The Netx Ops preset is **standard + netxops tools/persona** (shell, search, plan, todo, web, workflows, … plus `netx__*`). Re-activate (or restart the Host) so `$DSH_HOME/.agent-presets/netxops` is recomposed from the current Harness `standard` preset.
-3. **New session → preset Netx Ops** → ask e.g. Critical Top / single-host alarms / 「能否登录」.
-
-## Key-alarm push
-
-- **netx** (fixed IP) hosts the subscribe hub and fans out matched key alerts.
-- **netxops** (each DSH) reuses the same URL/token, connects outbound, and delivers into a DSH session and/or IM via `ctx.dshIm.send`.
-- Live status is exposed on the Plugins card via Connection RPC (`/netxops` → `alarm-push.status`); no curl required for day-to-day checks.
-- WhatsApp / `dsh-im` is **optional** for the DSH session path; required only when IM delivery is checked.
-
-## Export all sessions (HQ pickup)
-
-- **Where:** Settings → Plugins → **Netx Ops** → **导出全部会话**.
-- **What:** browser downloads one ZIP — `manifest.json` plus `sessions/<id>/session.jsonl` from this Host’s `sessionPersistence`.
-- **Why:** each edge / cloud harness keeps its own sessions; Ops downloads from the Web UI and ships archives to HQ.
-- **Limits:** needs a JSONL (raw-artifact) persistence backend; SQLite backends refuse export.
-
-## Verify
-
-1. Plugins card **Netx Ops** visible.
-2. With key-alarm push on: card badge shows **Connected** (or reconnecting / auth failed with detail).
-3. Agent presets → Custom → **Netx Ops**.
-4. Tools include `netx__queryNmsAlarms` / `netx__execManagedNe` / `netx__findTopologyPaths` (**ops** → skill `netx-ops`). Cutover analysis: `netx__getBizMonitorContext` … (**bizMonitor** → `netx-biz-monitor`). Native canvas tools need **topology** (`netx-topology`); advanced dual-unit/orbit/polish requires the separate topology MCP.
-5. Export section shows a session count; **下载 ZIP** starts a browser download.
-6. Optional knowledge-base badge shows operator/country/version when `kbRoot` + MANIFEST are valid.
-
-See [TOOL_MAP.md](TOOL_MAP.md) and [KNOWLEDGE_BASE.md](KNOWLEDGE_BASE.md).
-
-## Path / local checkout (developers)
+使用已经下载的发布包，例如：
 
 ```powershell
-dsh plugin --profile web add D:\path\to\netxops
-powershell -File .\scripts\link-dsh-peers.ps1   # only for path/link: installs
+dsh plugin --profile web add "D:\Downloads\dsh-netxops-0.1.70.tgz"
+dsh web
 ```
 
-See [examples/local-debug/README.md](../examples/local-debug/README.md).
+按实际位置替换包路径；已有 Web Host 需重启一次。两种安装方式均使用包内预编译 JS，不会在用户电脑上运行安装编译脚本。Desktop 与 Web 是不同的 Host profile，需要分别安装和配置。
+
+## 首次配置
+
+1. 设置 → 插件 → **Netx Ops**，填写 Netx API 地址和 API token。
+2. 为运维、拓扑、业务监控和知识库选择发布范围：Netx Ops、指定预设或全部预设。
+3. 新建会话，选择 **Netx Ops**，或选择已经获得 Netx 能力的其他预设。
+
+默认仅向 Netx Ops 发布运维与业务监控能力；拓扑与全预设公开默认关闭。未配置知识库时不会发布知识库能力。关闭总开关会撤销插件管理的工具和技能，同时保留各组选择。
+
+能力开关与预设选择自动保存，下一次模型请求使用新策略。API 地址、token、模型语言、告警配置和手工输入的知识库路径使用保存/丢弃；有草稿修改时操作栏才显示。通过目录选择器选择知识库路径会自动保存。
+
+Netx API 服务与对应权限的 token 是调用工具的前提；安装插件本身不需要连接 Netx 服务。默认地址为 `http://127.0.0.1:8890`，远程 Host 应配置从该 Host 可访问的地址。Harness 内部依赖与 React 由 Harness 提供，不需要从 npm 单独安装。
+
+## 可选功能
+
+**告警推送到 Harness 会话**直接使用 Netx URL/token，无需 IM 插件。只有选择 IM 投递时才需要单独安装并配置 `dsh-im-ops`；定时能力按需安装 `dsh-ops-cron`：
+
+```sh
+dsh plugin --profile web add github:hansjone/dsh-im-ops
+dsh plugin --profile web add github:hansjone/dsh-ops-cron
+```
+
+两个 companion 插件不是 Netx Ops 的默认安装项或运行依赖。需要时作为 profile 的直接依赖安装，不要写入 Netx Ops 的嵌套 `github:` 依赖。
+
+**知识库**：选择包含 MANIFEST 的知识库根目录，并设置发布范围。详见 [知识库说明](KNOWLEDGE_BASE.md)。
+
+**会话导出**：设置页可下载此 Host 的持久化会话 ZIP，需要 JSONL 持久化后端。导出不是安装条件。
+
+## 安装与启动排查
+
+- **下载 GitHub 包失败**：检查网络与 GitHub 可达性，或改用已经下载的版本 `.tgz`。更换 npm 镜像无法修复 GitHub 本身的连接失败。
+- **提示缺少 `@deepseek-ai/*`**：先确认 Harness 本身可以启动。公共发布包无需额外安装内部包；只有开发用 `link:` 路径安装才需要下面的 peer 链接步骤。
+- **插件激活失败**：从插件管理页展开具体 Host 加载错误。升级后分别完整重启 Desktop/Web，确认两者装入的是同一目标版本。0.1.70 包含 volatile 配置兼容与全新 profile 的 YAML 修复。
+- **Netx Ops 预设未出现**：检查 Host 是否启用、日志是否有 standard 模板读取或预设写入错误，然后重启对应 Host。预设从当前 Host 的 standard 组合生成。用户自建同名预设与修改过的文件会保留；请按日志处理冲突。
+- **设置页仍在等待连接**：确认 Host 插件已激活，刷新页面或重启升级后的 Host；持续失败时同时提供 Host 加载日志与插件版本。
+- **工具不可用**：确认总开关、对应能力组和当前预设的发布范围，再检查 API 地址、服务连通性和 token 权限。
+
+安装器只更新当前 profile，保留其他 profile、用户配置、用户预设和无法确认未修改的文件。若发现不支持的 profile 文档结构，会保留原文件并记录错误，避免写入损坏的配置。
+
+## 本地源码开发
+
+普通用户无需执行本节。源码 `link:` 安装时，Node 会从工作区真实路径解析依赖，因此需要将当前 Harness 的一套完整 peers 链接到工作区：
+
+```powershell
+pnpm install --frozen-lockfile --ignore-scripts
+bun run bundle
+dsh plugin --profile desktop add D:\path\to\netxops
+node scripts/link-dsh-peers.mjs --profile desktop
+```
+
+Web 开发将 profile 改为 `web`。脚本优先选择该 profile 的完整依赖集，再选择共享 Host 依赖；不会混用不同 profile 的内部包。Shell 与 PowerShell 包装脚本使用同一实现。
+
+手工预设安装仅用于排查，可在源码仓库运行 `node scripts/install-preset.mjs --profile web`。它使用正式安装器的组合、保留与 profile 更新规则，不会先删除已有预设。普通安装由 Host 自动完成，公开包不包含开发脚本。
+
+详见 [发布流程](RELEASING.md) 和 [工具发布与 UI 修复记录](PUBLICATION-REVIEW.zh.md)。

docs/PUBLICATION-REVIEW.zh.md

@@ -92,7 +92,7 @@ bun test
 
 回归覆盖目标预设隔离、Host 继承去重、总开关、旧分组入口、注册回滚、异步取消、卸载、快速切换、保存失败重试、空目标、双 profile 与安装文件保留。定向发布集成测试使用本机真实 Cordis 和 dsh-scope 服务上下文。
 
-最终检查：Host/Client 构建成功；严格类型检查通过；133 项测试通过；打包清单检查通过。发布文件清单排除了本机 `.npmrc` 和私有调试控制脚本。
+此前 UI 修复检查：Host/Client 构建成功；严格类型检查通过；133 项测试通过；打包清单检查通过。发布文件清单排除了本机 `.npmrc` 和私有调试控制脚本。
 
 新增启动回归使用本机官方 Schemastery/Cosmokit 的当前源码作为 schema peer，加载已构建的 Host JS；本机安装的旧 `lib` 不支持 volatile 引用，因此单独测试 `Config({})` 无法覆盖新版桌面行为。测试覆盖旧 profile 的缺省字段、新版和旧版配置、开关为 false、保留引用的更新、即时撤销，以及真实 Cordis 中的激活、所属实例事件和无错误卸载。该集成测试使用隔离目录与工具/skill 服务，不连接 Netx 生产服务。
 
@@ -101,3 +101,17 @@ bun test
 ![新版发布 UI，模拟 Host 数据](assets/publication-preview.jpg)
 
 实际桌面设置卡片已核对；Web 界面、当前与新会话的定向能力目录，以及配置好的 Netx API token 权限仍需在相应环境验证。高级拓扑 MCP、IM 投递和生产 Netx 服务连通性不包含在本次离线验证中。
+
+## 0.1.70 公开安装与发布检查
+
+发现并修复 Harness 默认 profile 的“注释 + 空列表 `[]`”安装问题：旧实现直接追加预设 block，产生无效 YAML，重启时可能无法加载。现在保留注释与用户条目，转换空列表后再追加；覆盖 BOM、CRLF、文档边界、重装幂等、带引号的用户预设 ID，以及自定义 profile。profile 配置通过同目录临时文件替换，写入前再次核对已有内容。
+
+公开包仅包含八个预编译入口、预设覆盖文件、分组技能、图标、中英文插件元信息和文档，排除源码、测试、开发脚本、本机配置与开发机生成的 standard 快照。公开安装使用包内技能，避免错误读取相邻 `netx` 包的目录。没有安装编译钩子、第三方运行时依赖或隐式 IM/cron 安装。
+
+源码锁文件与公开开发依赖声明已对齐，工作区禁用自动安装 Harness peers；默认构建不再读取开发机的 standard 模板。手工预设安装脚本统一复用正式安装器，去掉先删除预设的行为；不同系统的 peer 链接脚本统一选择同一 Host 的完整依赖集。
+
+新增发布检查核对真实构建输入、预编译输出哈希、导出、客户端注册、声明式 bundle、运行依赖、技能及展示元信息。修改源码但漏构建、修改输出或遗漏文件会阻止发布。`release:pack` 使用与安装测试相同的 npm 打包器，生成 `.tgz` 和 SHA256 校验文件。
+
+本机验证：全新临时源码目录从公共 registry 安装锁定的开发依赖后，可在没有 Harness peers/本机 standard 的情况下完成构建与发布检查；实际 npm 包在中文与空格路径中离线安装成功，没有拉取私有 Harness 包或 React。安装后的独立副本使用真实 Harness peers 激活，挂载 15 个运维工具及包内技能，全部 Host/工具入口可导入，卸载后无残留。测试不更改真实 profile、凭据或生产设备。
+
+当前完整回归为 **137 项通过、0 项失败**；严格类型检查与发布检查通过。Windows/macOS/Linux 的独立构建与离线安装检查已加入 GitHub Actions，跨平台结果以该提交对应的 CI 为准。公开发布流程见 [RELEASING.md](RELEASING.md)。

docs/RELEASING.md

@@ -0,0 +1,46 @@
+# Public release checklist
+
+The public package ships precompiled JS, preset overlays, skills, metadata and user documentation. It has no install/prepare/prepack build hook and no third-party runtime dependencies. Optional peer packages are supplied by Harness. Publish a tested tarball rather than asking users to build or link the repository.
+
+## Prepare the source
+
+Use Node.js 22, pnpm 11.7 and Bun >=1.3.13. Update `package.json.version`, synchronize canonical skills if changed, then run:
+
+```sh
+pnpm install --frozen-lockfile --ignore-scripts
+bun run bundle
+bun run release:check
+bun run test:release
+```
+
+The workspace disables automatic peer installation so a fresh source checkout does not fetch private Harness packages. `bundle` does not generate a preset from a developer's local Host: the installed plugin composes it from the user's running standard preset. `gen:preset-patch` is an explicit local debugging command and its generated snapshot is excluded from the public package.
+
+The build records source inputs and output hashes in `.release-build.json`. Commit this file and all eight `lib/*.js` exports with source changes. `release:check` fails when outputs are missing, modified or stale, or when a package resource or runtime contract is incomplete. New exports must also be included in `files` and package tests.
+
+## Check Harness behavior
+
+For full integration and type checks, first start a locally installed Harness and link one coherent runtime:
+
+```sh
+node scripts/link-dsh-peers.mjs --profile desktop
+bun run typecheck
+bun test test tests
+```
+
+Use `web` when testing the Web runtime. Full tests include the current official volatile Schema implementation, real Cordis scopes, publication changes, UI settings transport, preset preservation and fresh commented profile patches.
+
+`test:release` creates the actual npm tarball and installs it offline into a temporary profile with spaces and Chinese characters. Lifecycle scripts are allowed in this test, proving normal installation needs no build. It verifies all exports, client registration, bundled skills and metadata, and excludes source, tests, local config and developer scripts. When Harness is installed locally, it also activates that installed copy using actual Host peers and verifies tool/skill mounting and clean unload. The fixture never edits the user's profile or credentials and never calls a Netx production API.
+
+CI runs package checks, builds and offline installation on Windows, macOS and Linux. CI without Harness checks package installation and client registration; Host activation is covered by the local integration suite. Wait for the platform jobs to pass before publishing.
+
+## Create and distribute
+
+```sh
+bun run release:pack
+```
+
+This verifies the build, uses the same npm packer as the installation tests, and creates `dsh-netxops-<version>.tgz` plus a `.sha256` checksum. Install this exact file into a separate Desktop/Web profile before announcing a release. Check the plugin version, settings card, Netx Ops preset, tool availability and revocation. Test API connectivity with an appropriate test service/token, plus any optional IM delivery configuration that the release changes.
+
+Upload the verified tarball to the version's GitHub Release or publish it to npm as a separate maintainer action. `prepublishOnly` protects publishing from the source tree; `npm publish <tarball>` must use the tarball already checked above. Do not publish merely because a local directory boots successfully.
+
+Public install instructions should use that version's tarball or a fixed repository tag. Keep companion IM/cron plugins optional. A local filesystem path, an absolute developer directory and peer junctions are development aids, not public distribution dependencies.