用途:把现有 FinFocus 插件项目升级到更新的 finfocus-spec SDK 版本。finfocus plugin upgrade 命令负责无需判断的编辑,本技能处理其余需要人工迁移的部分,按 references/ 中每个“跳”(hop)一份迁移指南进行。跳以需要插件作者行动的发布为界,不等于次要版本,例如补丁版 v0.5.7 就改了处理器签名。
规则:编辑前先展示计划并获批准;从干净工作树新建分支,不自行 stash 或丢弃用户改动;只改指南或编译错误要求改的内容,不改定价计算逻辑、不启用可选功能、不重排格式、不改 vendor/;不得为通过而删除或跳过失败测试;用户未要求则不提交。
用法:在插件仓库根目录运行 finfocus plugin upgrade --dry-run --output json;若该命令不存在说明 finfocus 过旧,需提示用户更新。命令不联网,默认目标为当前 finfocus 构建所用的 finfocus-spec 版本。读取 JSON 中的 plan.current、plan.target、plan.up_to_date、plan.required_go、plan.hops[]、plan.warnings[]。向用户展示版本变化、各跳的人工步骤和警告,询问是否继续及是否在较早跳停止(--to)。
随后新建分支:git switch -c upgrade-finfocus-spec-<target>,执行 finfocus plugin upgrade 与 go mod tidy。命令拒绝脏工作树或非 Git 目录,仅当用户明确接受才用 --allow-dirty。--to 只接受该 finfocus 构建已知的发布。go.mod 指向目标后各跳的构建错误会同时出现,按由旧到新读取 references/<guide> 完成人工步骤,每跳后运行 go build ./... && go vet ./...,无法归因的错误查 finfocus-spec 发布说明,仍不清楚则停止报告而非猜测。
验证:运行 go build、go vet、go test,以及项目自带 lint(如 make lint 或 golangci-lint run)。用临时 home 做冒烟测试:export FINFOCUS_HOME="$(mktemp -d)",构建插件到 $FINFOCUS_HOME/plugins/<name>/0.0.0-upgrade/,再运行 finfocus plugin list --output json,读取 JSON 而非退出码:specVersion 须等于目标,notes 须不存在。finfocus plugin validate 不启动插件,不算冒烟测试;若插件启动需要凭据,报告冒烟测试已跳过及原因。
报告:说明迁移的版本、改动文件、各跳人工步骤、验证结果和未决事项,保留分支供审查。限制:不编造定价或可选功能改动;单次 --to 范围有限;引导文件覆盖 v0.5.7 至 v0.7.2 若干跳。