nodeagent

2 Commits

Include renames

Author SHA1 Message Date

Author	SHA1	Message	Date
jkooe	c8aba83589	fix(control): control.ps1 的 `$scheme:` 被当 drive 引用 → 整个脚本不可用（真机踩到） ## 现象（Parallels Win11 ARM 真机） `control.ps1 -Action stop/start/status` 一律报：所在位置 control.ps1:100 字符: 36 + Write-Host " 协议 : $scheme://0.0.0.0:$Port" 变量引用无效。':' 后面的变量名称字符无效。 ## 根因 PowerShell 把 `$scheme:` 解析为 drive 引用（如 `env:`），而 `scheme` 不是 drive → 语法错误。且这是解析期错误 → 整个脚本无法运行（不是只有那一行），stop/start/status 三个子命令全废。修法：写成 `${scheme}://`（用花括号界定变量名）。 ## 改动 - `scripts/control.ps1:100`：`$scheme://` → `${scheme}://`，并加注释说明为什么必须用花括号（注释里刻意不写危险字面量 —— 否则会被新守卫命中，这点在验证时真踩到了） - 新增守卫（`tests/unit/security-hardening.test.mjs`）：扫全部 `.ps1/.psm1`，禁止 `$ident:` 形式（白名单 `env`/`nuget`/`psitem`/`PSScriptRoot`） ## 验证 - 守卫 9/9 绿；全量单测 274 绿；ps1-encoding 保持通过（BOM 未被破坏） - 注入故障实测：把 `${scheme}` 回退成 `$scheme:` → 守卫立即红（失败数 1）→ 恢复后绿（按项目纪律：没验证过会红的守卫等于没有） - 全仓重扫同类模式：仅此 1 处	2026-10-11 00:05:42 +08:00
jkooe	cedc46d090	feat(v20): 版本纪律 + 发版自动化（对齐「做好版本功能 + GitHub 同步资产」） ## 一、版本功能（防新旧混用） 1. 单一版本源 + 构建注入：根 package.json 的 version、git sha、构建时间经 esbuild `--define` 注入 agent；`system.info.build` 新增 `version/commit/built_at`（原有 `hash` 指纹不变）。开发态用 typeof 探测（未注入也不崩）。 2. 握手携带版本：`auth_ok` 新增可选字段 `agent_version` / `build` / `protocol`（只增不减 → 旧控制端忽略即可）。 3. 能力级兼容比对：新增纯函数 `capabilityDiff(local, remote)` —— - `missingOnRemote`：本地有远端没有 → 远端较旧，提示更新被控端 - `unknownLocally`：远端有本地没有 → 本控制端较旧（不影响既有功能）控制端不比版本号而比能力集合：版本号可能相同而内容不同，能力集合不会骗人。 4. CLI 体检：`nodeagent info` / `connect` 直接显示被控端版本与能力对齐情况，把"调用时才炸"变成一句人话提示。 ## 二、发版自动化（GitHub 资产同步） `pnpm release <x.y.z\|patch\|minor\|major>`：前置检查（干净/在 main/与远端同步）→ 改 7 个 package.json → 构建+打包 → 生成资产 → 提交打标签推送 → `gh release create` 上传。 - 资产：`agent.mjs`（自更新载荷）、`nodeagent-win-x64.zip`（人工安装包）、 `latest.json`（version/commit/能力数 + 两个资产的 url 与 sha256）、`SHA256SUMS` - `--dry-run` 无副作用演练；`--no-publish` 只到本地标签 - 能力数从 dist 动态取（避免写死漂移）；刻意排除 `.github/`（缺 workflow 权限推不了） ## 三、兼容性契约文档新增 `docs/VERSIONING.md`：semver 各位的含义、只增不改六条硬规则、升级顺序建议（先被控端：新被控端向后兼容旧 CLI）、两条更新路径、发版流程、排查手册。 ## 验证 - 单测 147 → 149（新增 capabilityDiff 用例：远端过旧 / 本机过旧 / 完全一致 / 真实清单自比无差异） - e2e 28 全绿；`node scripts/release.mjs 1.0.0 --dry-run` 演练通过且工作区无副作用	2026-10-04 23:54:51 +08:00

c8aba83589

fix(control): control.ps1 的 $scheme: 被当 drive 引用 → 整个脚本不可用（真机踩到）

## 现象（Parallels Win11 ARM 真机）
`control.ps1 -Action stop/start/status` 一律报：
  所在位置 control.ps1:100 字符: 36
  +  Write-Host "  协议     : $scheme://0.0.0.0:$Port"
  变量引用无效。':' 后面的变量名称字符无效。

## 根因
PowerShell 把 `$scheme:` 解析为 **drive 引用**（如 `env:`），而 `scheme` 不是 drive → 语法错误。
且这是**解析期**错误 → **整个脚本无法运行**（不是只有那一行），stop/start/status 三个子命令全废。
修法：写成 `${scheme}://`（用花括号界定变量名）。

## 改动
- `scripts/control.ps1:100`：`$scheme://` → `${scheme}://`，并加注释说明为什么必须用花括号
  （注释里刻意**不写**危险字面量 —— 否则会被新守卫命中，这点在验证时真踩到了）
- 新增守卫（`tests/unit/security-hardening.test.mjs`）：扫全部 `.ps1/.psm1`，
  禁止 `$ident:` 形式（白名单 `env`/`nuget`/`psitem`/`PSScriptRoot`）

## 验证
- 守卫 **9/9 绿**；全量单测 **274 绿**；ps1-encoding 保持通过（BOM 未被破坏）
- **注入故障实测**：把 `${scheme}` 回退成 `$scheme:` → 守卫**立即红**（失败数 1）→ 恢复后绿
  （按项目纪律：没验证过会红的守卫等于没有）
- 全仓重扫同类模式：**仅此 1 处**

2026-10-11 00:05:42 +08:00

jkooe

cedc46d090

feat(v20): 版本纪律 + 发版自动化（对齐「做好版本功能 + GitHub 同步资产」）

## 一、版本功能（防新旧混用）
1. **单一版本源 + 构建注入**：根 package.json 的 version、git sha、构建时间经 esbuild
   `--define` 注入 agent；`system.info.build` 新增 `version/commit/built_at`（原有 `hash` 指纹不变）。
   开发态用 typeof 探测（未注入也不崩）。
2. **握手携带版本**：`auth_ok` 新增可选字段 `agent_version` / `build` / `protocol`（只增不减 → 旧控制端忽略即可）。
3. **能力级兼容比对**：新增纯函数 `capabilityDiff(local, remote)` ——
   - `missingOnRemote`：本地有远端没有 → **远端较旧**，提示更新被控端
   - `unknownLocally`：远端有本地没有 → **本控制端较旧**（不影响既有功能）
   控制端不比版本号而比**能力集合**：版本号可能相同而内容不同，能力集合不会骗人。
4. **CLI 体检**：`nodeagent info` / `connect` 直接显示被控端版本与能力对齐情况，
   把"调用时才炸"变成一句人话提示。

## 二、发版自动化（GitHub 资产同步）
`pnpm release <x.y.z|patch|minor|major>`：前置检查（干净/在 main/与远端同步）→ 改 7 个 package.json
→ 构建+打包 → 生成资产 → 提交打标签推送 → `gh release create` 上传。
- 资产：`agent.mjs`（**自更新载荷**）、`nodeagent-win-x64.zip`（人工安装包）、
  `latest.json`（version/commit/能力数 + 两个资产的 url 与 sha256）、`SHA256SUMS`
- `--dry-run` 无副作用演练；`--no-publish` 只到本地标签
- 能力数从 dist 动态取（避免写死漂移）；刻意排除 `.github/`（缺 workflow 权限推不了）

## 三、兼容性契约文档
新增 `docs/VERSIONING.md`：semver 各位的含义、**只增不改**六条硬规则、
升级顺序建议（**先被控端**：新被控端向后兼容旧 CLI）、两条更新路径、发版流程、排查手册。

## 验证
- 单测 147 → **149**（新增 capabilityDiff 用例：远端过旧 / 本机过旧 / 完全一致 / 真实清单自比无差异）
- e2e 28 全绿；`node scripts/release.mjs 1.0.0 --dry-run` 演练通过且工作区无副作用

2026-10-04 23:54:51 +08:00