Tool Updater

Tool Updater

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown

Checks for and applies Homebrew updates tobeads(bd) anddolt.

gt is rebuilt separately by therebuild-gtplugin (it builds from source, not Homebrew).

Run

cd /Users/jeremy/gt/plugins/tool-updater && bash run.sh

但当插件目录下存在 `run.sh` 时，执行形态会发生质变：扫描器在加载插件时检测 `run.sh` 并将 `HasRunScript` 置为 true（[internal/plugin/scanner.go](https://link.gitcode.com/i/101adc806b69ab319dceda7d65b4b6cb) 的 `loadPlugin`），此时 `FormatMailBody` 生成的不是「解释 Markdown 指令」的任务，而是「**精确执行脚本、禁止自行改写实现**」的指令（见 [internal/plugin/types.go](https://link.gitcode.com/i/09f015c6333454c75f165b316c271b70)）：

Execute the following plugin script: cd <插件目录> && bash run.sh Run this command EXACTLY. Do NOT interpret the plugin.md instructions. Do NOT write your own implementation. Just run the script and report the output.

即：**有 run.sh 时脚本是唯一事实来源**，Markdown 正文退化为说明文档；没有 run.sh 时 dog 才逐条解释执行正文指令。`tool-updater` 正是典型的「脚本执行型」插件，核心逻辑全部封装在 [plugins/tool-updater/run.sh](https://link.gitcode.com/i/a34b996fc7d908282416c23498a8d6f5)。 ## 三、run.sh：一次完整的升级巡检流水线 `run.sh` 以 `set -euo pipefail` 启动（任何未处理错误立即退出），将目标工具收敛到数组并依次完成四步： ```bash #!/usr/bin/env bash set -euo pipefail TOOLS=(beads dolt) log() { echo "[tool-updater] $*"; }

3.1 刷新 Homebrew 索引

log "Running brew update..." HOMEBREW_NO_AUTO_UPDATE=1 brew update 2>&1 | tail -3 || true

设置HOMEBREW_NO_AUTO_UPDATE=1防止后续每个brew命令再次隐式更新（避免拖慢脚本），索引更新失败用|| true容忍——即使索引刷新失败，仍可基于本地已知信息检查 outdated。

3.2 检查过期工具

for TOOL in "${TOOLS[@]}"; do if brew outdated --quiet "$TOOL" 2>/dev/null | grep -q "$TOOL"; then OLD_VER=$(brew info --json "$TOOL" 2>/dev/null | python3 -c "import json,sys; d=json.load(sys.stdin)[0]; print(d['installed'][0]['version'])" 2>/dev/null || echo "?") OUTDATED+=("$TOOL@$OLD_VER") log " $TOOL: update available (installed: $OLD_VER)" else log " $TOOL: up to date" fi done

对每个工具：brew outdated --quiet命中则记录到OUTDATED数组（格式工具@旧版本），并用brew info --json+ Python 解析当前已安装版本号，便于日志与回执展示。若全部最新则提前收尾：

if [[ ${#OUTDATED[@]} -eq 0 ]]; then log "All tools current. Nothing to do." gt plugin record-run --plugin tool-updater --result success \ --title "tool-updater: all tools current (beads=$(bd version ...), dolt=$(dolt version ...)" >/dev/null 2>&1 || true exit 0 fi

3.3 逐个升级

for entry in "${OUTDATED[@]}"; do TOOL="${entry%%@*}" if HOMEBREW_NO_AUTO_UPDATE=1 brew upgrade "$TOOL" 2>&1; then NEW_VER=$(brew info --json "$TOOL" 2>/dev/null | python3 -c "...") UPGRADED+=("$entry→$NEW_VER") else FAILED+=("$TOOL") fi done

升级成功则记录旧版本→新版本；失败则记入FAILED，但不中断循环——一个工具失败不应阻止另一个工具升级。

3.4 记录回执与失败升级

SUMMARY="tool-updater: upgraded=${UPGRADED[*]:-none} failed=${FAILED[*]:-none}" RESULT="success" [[ ${#FAILED[@]} -gt 0 ]] && RESULT="warning" gt plugin record-run --plugin tool-updater --result "$RESULT" \ --title "$SUMMARY" >/dev/null 2>&1 || true if [[ ${#FAILED[@]} -gt 0 ]]; then gt escalate "tool-updater: ${#FAILED[@]} tool(s) failed to upgrade: ${FAILED[*]}" \ -s medium \ --reason "Homebrew upgrade failed for: ${FAILED[*]}" 2>/dev/null || true fi

• gt plugin record-run写入运行回执：--result为success或warning（部分失败）。回执落地为一条type:plugin-run标签的 ephemeral bead，创建后立即关闭，供gt plugin history与 cooldown 门控查询使用（见 internal/plugin/recording.go 的RecordRun，以及 internal/cmd/plugin.go 的runPluginRecordRun）。注意--result在命令行层面可接受任意字符串，底层RunResult常量只定义success/failure/skipped三种（internal/plugin/recording.go），脚本中的warning属自定义取值，查询时以标签原样解析。
• gt escalate：仅当存在失败工具时触发，-s medium与 frontmatter 的severity = "medium"呼应，--reason携带失败明细，确保维护事件进入升级通道而不仅是日志。

四、在 Gas Town 运行时中的角色：谁在执行这个插件

tool-updater的职责边界与调度路径可以总结为：

1. 发现：gt plugin list会从 town 级~/gt/plugins/与各 rig 级<rig>/plugins/扫描插件目录，rig 级同名插件覆盖 town 级（internal/plugin/scanner.go 的DiscoverAll）。本仓库中插件以 plugins/tool-updater/ 形式随源仓库分发。
2. 同步部署：通过gt plugin sync可将仓库中的plugins/同步到运行时的 town 级插件目录（gt plugin sync --source ./plugins --dry-run可先预览差异，--clean可清理源中不存在的插件，实现见 internal/plugin/sync.go 与 internal/cmd/plugin.go 的runPluginSync）。
3. 调度：插件在 Deacon 巡逻周期中被评估，cooldown 门控（168h）确保每周只执行一次；dispatch 时 dog 依据FormatMailBody生成的指令执行bash run.sh（调用点在 internal/daemon/handler.go）。
4. 手动触发与审计：gt plugin run tool-updater（门控关闭时加--force）可随时手动执行；gt plugin show tool-updater查看详情；gt plugin history tool-updater查看运行历史（默认最近 10 条，--json输出结构化数据，--limit调整条数）。

五、从 tool-updater 学到的插件最佳实践

对照tool-updater与同目录下其他维护型插件（如 plugins/rebuild-gt/、plugins/dolt-backup/），可以提炼出 Gas Town 维护型插件的通用范式：

1. 单一职责 + 工具边界清晰：Homebrew 工具归tool-updater，源码构建归rebuild-gt，互不重叠，避免重复升级与冲突。
2. 幂等与无害失败：无更新时记录success并提前退出；部分失败不中断整体流程，且record-run、escalate均带|| true容错——记录动作本身失败不影响主流程。
3. 门控代替 cron：用cooldown + 168h表达「每周一次」，无需系统 crontab，门控状态天然持久化在账本中。
4. 脚本可执行、正文可解释：run.sh承载确定性逻辑，plugin.md正文说明意图；运行回执始终落账，配合notify_on_failure与severity让失败可追溯、可升级。
5. 运行回执驱动审计：每次执行都通过gt plugin record-run写入plugin:<name>、result:<outcome>、category:maintenance等标签，使gt plugin history与每日摘要（digest = true）成为维护活动的审计轨迹。

六、动手验证：从仓库运行与查看效果

本仓库为只读源码形态，以下命令需在已部署 Gas Town 工作区（含 Homebrew 安装的bd/dolt）中执行：

# 1) 查看插件是否被发现及其门控/执行配置 gt plugin show tool-updater # 2) 查看运行历史（最近 5 条，JSON 便于脚本处理） gt plugin history tool-updater --limit 5 --json # 3) 手动触发（若 168h 冷却未过会被拦截，加 --force 强制） gt plugin run tool-updater # 4) 若插件尚未部署，从本仓库同步（先 dry-run 预览差异） gt plugin sync --source ./plugins --dry-run

【免费下载链接】gastownGas Town - multi-agent workspace manager项目地址: https://gitcode.com/GitHub_Trending/ga/gastown