mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-10-31 06:17:25 +00:00
db58f66d83
## 1. 文件操作必须走 files 插件（用户明确要求） 旧 skill 写着「如果你已经有 run_shell / bash 之类的能力，优先用那个 —— 它更直接」， 与「文件操作必须走 files_*」相悖。改为： - 所有已知内容的读写一律 files_read/files_write/files_edit/files_edit_line； - 不用 cat/echo/sed/tee/重定向代替（shell 拼长文本会被引号转义吃掉， 且重定向会截断原文件，而本插件是原子写 + 写前留档）； - 唯一例外：文件是命令的副产物（go build -o、git clone、日志重定向）。 cmd-tools skill 同步补一条：文件读写不要用 shell 代替。 ## 2. 三个新 skill 对齐 ai_image 等既有规范 - 结构统一为：什么时候用 / 先拉起插件（plugin_start 代码块）/ 工具表 / 用完可释放（plugin_stop）/ 注意 / 「plugin_stop vs plugin_disable」对照表； - 修正上一版的错误：把 `plugin_enable` 写成拉起方式 —— 那是**持久**解禁， 会改开机行为；按需拉起应使用 `plugin_start name=<插件>`。 - files skill 保持 auto_start=false（与「大部分插件不需要自启」一致）， 但把「怎么拉起」写清楚。 ## 3. cmd_run 描述补充能力边界 「经完整 bash 执行，支持管道、分号、&&、命令替换、heredoc、重定向； 不支持交互（vim/ssh/top 用 terminal_create）」。 验证：四工程 hmapdev 构建通过；本机重装后 skills_registered=1； 问 agent 写文件时它先 plugin_start 再 files_write/files_read，未用 shell 代替。
files · 沙箱文件操作
读写与编辑文件，全部操作限制在沙箱目录内。
工具
| 工具 | 说明 |
|---|---|
files_read |
读文件内容，支持 offset / limit 读大文件 |
files_write |
写文件，自动创建父目录 |
files_edit |
按精确字符串替换改文件 |
files_ls |
列目录（目录名带 / 后缀） |
files_edit 用 edits[] 传多组替换，每组 {old, new}：
- 每个
old必须在原文件中恰好出现一次 —— 不唯一会报错，避免改错地方。 - 所有替换都针对原内容匹配，不要在同一个
edits里写相互重叠的改动。
配置项
| 键 | 默认 | 说明 |
|---|---|---|
dir |
空 | 允许访问的根目录。留空用默认沙箱（主数据目录下的 files_sandbox）。不建议设为 / |
沙箱实现
路径校验不止一次，是两道：
- 规范化后判断：
filepath.Abs+filepath.Clean，再用withinSandbox检查结果是否在根目录之下（/作为特例放行）。 - 解析符号链接后再判断：
filepath.EvalSymlinks求出真实路径，再查一次沙箱。
第 2 步是关键：只做第 1 步的话，沙箱内一个指向外部的软链接就能绕过限制
（.../sandbox/link -> /etc）。报错文案也区分了这两种情况
（path outside sandbox vs path escapes sandbox via symlink）。
对不存在的路径（write 会用到），求真实路径时只对已存在的部分做 EvalSymlinks，
其余保留为未创建的尾部。
构建
hmapdev build