jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-09-20 17:08:01 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
db207fd9b7a20ed81c6ba73bf4b7d125b16531dc
homeagent-sdk/tools/vscode-hmapdev/README.md
JianFeeeee fcb7490f63 feat(vscode): 插件工程调试扩展（plg.json 诊断 / SDK 版本 / 构建运行 / 内核日志跟随） 
插件的真实形态是「独立子进程 + 内核侧握手」，所以插件问题几乎都在 IDE 之外发生：
编不出来（多半是没声明用哪版 SDK，工具链拿了存储里的 current）、编出来起不来
（产物与内核协议绑定）、起来了行为不对（真因只在内核日志里）。这个扩展把这三件事
拉进 IDE。

- `tools/vscode-hmapdev`：TypeScript 扩展（零运行时依赖，仅 devDeps: typescript + @types/vscode）
  - **plg.json 诊断**：必需字段；`sdk` 必须是完整版本号（区间写法 `1.2` 报错并说明
    「patch 位恒为 .0」，与工具链 ResolveSDKForProject 同一套规矩）；声明的 SDK 未安装时
    直接给 `hmapdev sdk install vX.Y.Z`；
  - **状态栏**：`插件 · SDK <声明> · hmapdev <版本>`，工具链缺失/工程有错时变色，tooltip 列已装 SDK；
  - **命令**：build / build --target all / clean / debug（解释执行）/ 工具链版本 / SDK 列表-安装-切换 /
    跟随内核日志 / 停止跟随 / 刷新；
  - **任务**：同一批动作注册为 `hmapdev` 任务 + Go 问题匹配器（编译错误进 Problems）；
  - **内核日志跟随**：读 `<dataDir>/log` 最新 `homed_*.log`，按插件名过滤持续输出；
  - schema 校验 + plg.json 骨架片段。
- 诚实边界（写进 README）：**不是源码级调试器**——没有断点/单步，没有 DAP 会话；
  做的是构建、运行、看内核日志、清单校验。

验证：`tsc` 零错误；`node --test` 13/13（版本规则、诊断分级、SDK 列表解析、状态栏文本、
以及**反向核对抓到的真缺陷**：`hmapdev 未找到` 这类输出曾被解析成版本号 → 已要求版本
token 以数字开头，否则「工具链不在」会被显示成「工具链 <垃圾词>」并让 SDK 诊断失真）；
与真实工具链输出的集成核对 PASS（`hmapdev version` / `sdk list` 的真输出解析正确）。

README 同时补两节：plg.json 的 `sdk` 字段语义（含「为什么必须有」与「为什么拒区间写法」）、
本扩展的用法与边界。
2026-09-12 16:07:34 +08:00

4.2 KiB
Raw Blame History

hmapdev — HomeAgent 插件开发 VSCode 扩展

调试与构建 HomeAgent 插件工程的 IDE 支持：plg.json 校验、SDK 版本解析、构建/运行、内核日志跟随。

为什么需要它

插件的真实形态是「独立子进程 + 内核侧握手」，所以插件的三类问题几乎都在 IDE 之外发生：

  1. 编不出来 —— 最常见的原因不是代码，而是项目没声明要用哪版 SDK，工具链拿了存储里的 current（可能是陈旧的 v0.8.0），于是报一堆看不懂的 undefined: sdk.XXX；
  2. 编出来但起不来 —— 产物与内核协议绑定（协议版本 + 共享内存魔数），用错工具链编出来的 插件会在握手时被拒；
  3. 起来了但行为不对 —— 真因往往只在内核日志里（建链失败、崩溃重启、工具报错）。

本扩展把这三件事拉进 IDE：先把「用哪版 SDK」摆到明面上，再让构建/运行/看日志变成一条动作链。

功能

功能 说明
plg.json 诊断 必需字段；sdk 必须是完整版本号（区间写法 1.2 会报错并说明「patch 位恒为 .0」）；声明的 SDK 若未安装在本地存储，直接给出 hmapdev sdk install vX.Y.Z
状态栏 插件 · SDK <声明> · hmapdev <版本>；工具链缺失或工程有错时变红/黄，tooltip 列出已装 SDK
构建 / 清理 / 运行 hmapdev build、build --target all、clean、debug（解释执行，快速迭代）——在集成终端里跑，可 Ctrl-C
任务（Tasks） 同一批动作注册为 hmapdev 任务，可绑快捷键、串依赖；带 Go 问题匹配器，编译错误进 Problems 面板
跟随内核日志 读 <dataDir>/log 下最新的 homed_*.log，按插件名过滤后持续输出（真正的联调回路）
SDK 管理 查看工具链版本、列出/安装/切换 SDK 版本（走 QuickPick，不用记命令）
JSON 支持 plg.json 的 schema 校验 + 骨架片段

安装

cd tools/vscode-hmapdev
npm install
npm run compile

然后二选一：

  • 开发模式：在 VSCode 里打开本目录，按 F5（Extension Development Host），把插件工程目录作为工作区打开；
  • 安装到本机：npx @vscode/vsce package 生成 .vsix，再 code --install-extension hmapdev-vscode-0.1.0.vsix。

前提：hmapdev 在 PATH 上（或设置 hmapdev.path）。

配置

设置 默认 说明
hmapdev.path hmapdev 工具链可执行文件路径
hmapdev.kernelDataDir 空 内核数据目录（homed -data 的那个）；填了才能跟随内核日志
hmapdev.diagnoseSdk true 是否校验声明的 SDK 是否已安装（需要能执行 hmapdev）

用法（典型开发回路）

  1. 打开插件工程（含 plg.json）→ 状态栏出现 插件 · SDK <版本> · hmapdev <版本>；
  2. 若 sdk 报错（未声明 / 区间写法 / 未安装）→ 按提示执行 hmapdev: 安装 SDK 版本…，再 hmapdev: 刷新状态；
  3. hmapdev: 构建插件（或 构建（全部目标平台））→ 编译错误直接进 Problems；
  4. 快速验证行为：hmapdev: 运行插件（解释执行）；
  5. 与内核联调：设置 hmapdev.kernelDataDir → hmapdev: 跟随内核日志，只看本插件的行；
  6. 改代码 → 重复 3/5。装进内核时记得与内核同批替换（协议绑定的产物不支持滚动升级）。

诚实的边界

  • 这不是源码级调试器：没有断点/单步。插件的 Go 代码要么编译成产物在内核里跑、要么用 hmapdev debug（yaegi 解释执行）跑，两条路都不提供 DAP 调试会话。本扩展做的是 「构建 + 运行 + 看内核日志 + 清单校验」，这也是插件问题实际能被定位的方式。
  • Windows 目标：不支持（协议 2 的统一共享内存区未移植到 Windows，内核侧改走 WSL2）， 扩展只给提示，不假装能构建。
  • sdk 字段的语义：它声明的是本插件针对的 SDK 版本（= 接口线），不是内核版本。 SDK 版本跟随内核中版本、patch 位恒为 .0。