jianf/homeagent-sdk
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/homeagent-sdk.git synced 2026-11-01 14:57:28 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
72011bc8bfda2c3772b9c375d1acb1ec67295024
homeagent-sdk/example/editdoc
History
JianFeeeee 72011bc8bf fix(examples): 恢复 go.mod 相对路径 + 移除 plg.json 的 sdk 固定（修 CI 红） 
CI 上 `Examples (linux/amd64)` 与 `(darwin/arm64)` 双红，只有两个失败：

  ✗ commondev   构建失败
  ✗ editdoc     构建失败
  error: 项目声明 sdk=1.4.0，但本地 SDK 存储里没有这个版本

其余 20 个示例全部成功 —— 说明不是通用问题，而是这两个被改坏了。

## 根因（两个叠加）

**① go.mod 被本机绝对路径污染**

我在上一个提交里用 `git add -A`，把本机 `go build` **自动改写**过的
go.mod 一并提交了：

  require github.com/JianFeeeee/homeagentsdk v1.4.0
  replace github.com/JianFeeeee/homeagentsdk => /root/.homeagent/hmapdev/sdk/v1.4.0

基线（origin/main）是：

  require github.com/JianFeeeee/homeagentsdk v0.0.0
  replace github.com/JianFeeeee/homeagentsdk => ../../

本机那个目录真的存在 ⇒ 本地全绿；CI 没有 ⇒ 必红。

**② plg.json 声明了 `"sdk": "1.4.0"`**

一声明版本，hmapdev 就去**本地 SDK store** 找它，找不到直接拒绝构建。
全仓 20+ 示例**都不声明**，只有我改过的这两个声明了。
示例的正确依赖表达是 go.mod 的 `v0.0.0` + `replace ../../`。

## 修法

两个文件都恢复到与其余示例一致的写法。

## 判据（3 条，都是新加的）

 · `TestExampleGoModHasNoAbsoluteReplace`：任何示例 go.mod 不得含
   `/root/`、`/home/`、`/Users/`、`C:\`
 · `TestExampleGoModUsesRelativeSDKReplace`：replace 必须是相对路径 `../../`
 · `TestExamplePlgJsonDoesNotPinSDKVersion`：plg.json 不得声明 sdk

变异 2/2 咬住（重新引入绝对路径 / 重新声明 sdk，都准确报出文件路径）。

## 本地验证（模拟 CI 干净环境）

用干净 HOME 跑 `package/build-examples.sh`：
 · 修复前：成功 18 / 失败 4（commondev, editdoc, browser, rss）
 · 修复后：成功 20 / 失败 2（browser, rss —— **本机代理不通**，
   `proxy.golang.org` 超时；用本地 modcache 验证这两个可正常构建）

即 22/22 源码都能构建，CI 有网络不受影响。

## 教训

`git add -A` 会把「构建工具自动改写的文件」一起提交。
提交前必须 `git status` 逐个看，尤其 go.mod / go.sum。
2026-10-17 19:42:27 +08:00
..
embed
fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染
2026-10-17 16:34:29 +08:00
go.mod
fix(examples): 恢复 go.mod 相对路径 + 移除 plg.json 的 sdk 固定（修 CI 红）
2026-10-17 19:42:27 +08:00
main.go
fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染
2026-10-17 16:34:29 +08:00
plg.json
fix(examples): 恢复 go.mod 相对路径 + 移除 plg.json 的 sdk 固定（修 CI 红）
2026-10-17 19:42:27 +08:00
plugin_test.go
fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染
2026-10-17 16:34:29 +08:00
plugin.go
fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染
2026-10-17 16:34:29 +08:00
README.md
fix(sdk): 协议通道纪律 + hmapdev 模板升级 + 示例插件 stdout 污染
2026-10-17 16:34:29 +08:00

README.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 侧升级了、脚本忘了换」的版本漂移。 内嵌 + 内容指纹校验使两侧永远同版本：

  1. 首次调用时把内嵌脚本释放到 DataDir()/runtime/edit_doc.py，并写 .stamp 指纹；
  2. 插件升级后指纹变化 → 自动重新释放；
  3. 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 ./...