mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 14:27:30 +00:00
0111ac3a7a
## 核心缺陷：插件往 stdout 打日志 = 污染 JSON-RPC 协议通道
子进程插件与内核用 stdout 传 NDJSON 帧，stderr 才是日志通道。
脚手架模板（及 4 个示例插件）用 `fmt.Printf` 打日志 ⇒ 内核收到非 JSON 文本：
[proc] weather 收到非法 JSON 帧（21 字节）: invalid character 'i'
**生产实测 1038 条**（huawei_smarthome 720 / weather 113 / rss 103 / calendar 102）。
后果不只是日志噪音：那一行日志被**丢弃**，插件看起来"没启动"。
修法：
- hmapdev 模板 `fmt.Printf` → `log.Printf`（9 处）
- 示例插件 4 个 14 处：ai_image(2) calendar(5) rss(4) weather(3)
+ 补 "log" import
- 内核侧（主仓）同步让报错可定位：内容摘要 + 可能原因 + 修法
判别法：`package main` = 子进程（协议通道，禁用 stdout 打日志）；
普通库包 = 进程内插件（编译进内核，写真实终端，**不是**缺陷）——
`internal/plugins/cli` 的 `fmt.Println` 属后者。
## hmapdev
- `cmd_build.go` +136：平台产物精确匹配（`--target` 是**append** 语义，
原脚本 `ls dist/*.hmap | head -1` 会按字典序抓到 amd64，
**导致 arm64 包里装的是 x86-64 二进制**，且退出码 0、校验和通过）
- `cmd_init.go` +46：脚手架 stdio 纪律
- `templates/proc_main.go.tmpl`：补齐 mgrStop/mgrStart/mgrIsRuntimeStopped
三态能力（插件管理器运行态停启）
- `templates/plg.json.tmpl` 删除（合并进 cmd_init）
## 判据
- `scaffold_stdout_test.go`（3 条）：扫模板生成的代码不得写 stdout。
★ 判据自身先假红过一次：**模板的注释里就写了 `fmt.Printf`** ⇒
必须 `stripTemplateComments()` 之后才判
- `example_stdout_test.go`（2 条）：扫全部 20 个子进程示例插件，
报错给**文件:行号**；变异咬住并给出准确行号
- `package_examples_test.go`（2 条）：**执行真实打包脚本**
（第一版测的是 hmapdev 而不是脚本 ⇒ 变异不咬）
- `cmd_build` / `cmd_init` 新判据
## 其他
- sdk/settings.go +15（三态能力透传）
- `docs/versions.md` +§示例插件协议通道纪律（含生产 1038 条实测表格）
- `skills/homeagent-plugin-dev/SKILL.md` +§协议通道纪律（正误代码对比）
editdoc · 全能办公
对 .docx / .xlsx / .pptx / .xls / .csv / .md / .txt 做新建、读取、编辑、转换。
版本：v2.0.0（全能办公）。较 v1.0.0 新增
read_document、create_document、create_from_template、convert_document、office_check五个工具；edit_document的名字与全部 v1 参数保持不变，老调用不会破。
工具
| 工具 | 作用 |
|---|---|
read_document |
读为结构化 JSON（docx 段落+表格+页眉页脚 / xlsx 逐表逐格含公式与计算值 / pptx 逐页 / xls / csv / md / txt），大文件可 offset/limit 分段 |
create_document |
从零新建。docx 支持 Markdown 正文；xlsx 支持多表（表名+表头+行）；pptx 用 ## 分页 |
create_from_template |
复制模板再套用替换 |
edit_document |
编辑既有文件（v1 八参数 + 查找替换/正则大小写/第 N 处/表格与单元格/图片/样式/幻灯片/dry_run） |
convert_document |
格式转换（docx↔md/pdf、xlsx↔csv 等，借助 soffice / pandoc） |
office_check |
自检：依赖库可用性与版本、外部工具、格式×能力矩阵 |
配置项
| 键 | 默认 | 说明 |
|---|---|---|
script_path |
空 | edit_doc.py 的绝对路径。留空即推荐值 —— 用内嵌脚本；仅当该文件含 v2 协议标记时才被采用，否则自动忽略并回退内嵌 |
venv_python |
空 | 执行脚本的 Python 解释器（需装 python-docx / openpyxl / python-pptx）。必须配置 |
timeout_sec |
60 | 单次调用超时；大文件或格式转换（soffice 首次启动慢）建议调到 180 |
工作原理
Go 侧只做参数编排与结构化返回，全部业务逻辑在 Python 脚本 edit_doc.py 里。
脚本是内嵌的（//go:embed embed/edit_doc.py），原因：hmapdev 打包器只把
plugin.json + plugin.bin 放进 .hmap，不打包任何资源文件。若让脚本单独
存在于 plugin_data/，就会出现「Go 侧升级了、脚本忘了换」的版本漂移。
内嵌 + 内容指纹校验使两侧永远同版本：
- 首次调用时把内嵌脚本释放到
DataDir()/runtime/edit_doc.py，并写.stamp指纹； - 插件升级后指纹变化 → 自动重新释放；
script_path显式指向的文件仅当含EDITDOC_PROTOCOL = "v2"标记时才被采用 （便于运维临时覆盖调试）；否则忽略并在返回体里带script_path_ignored，让降级可见。
业务脚本只有一份：embed/edit_doc.py。不要再添加同名的顶层副本 ——
它不会被 embed，改了不生效，而两份同名文件是典型的漂移源（见
TestOnlyOneBusinessScript）。
依赖
Python 侧：python-docx、openpyxl、python-pptx（.xls 另需 xlrd）。
外部工具（可选，转换能力用）：soffice（LibreOffice）、pandoc。
用 office_check 随时查看本机实际可用的能力矩阵。
构建
hmapdev build
测试
go test ./...