From 531090768a8abff4492ed8e38c19bc7bbd2938fb Mon Sep 17 00:00:00 2001 From: Espressohan Date: Fri, 11 Sep 2026 20:32:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(skills):=20=E8=A1=A5=E5=85=A8=20update=20-?= =?UTF-8?q?-target-version=20=E7=94=A8=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `update --repair` 只修复当前安装，不会改变已安装的版本号；原文档未说明 跨版本升级必须显式传入 `--target-version `，容易让 Agent 在收到 「有新版可用」提示后误以为执行 `update --repair` 即已完成升级。 - `scripts/generate-contracts.mjs`：更新 shared 决策表与 `lifecycle.md` 模板， 补充 `--target-version` 示例、回滚说明，以及未传该参数时版本号不变的排查要点。 - 同步重新生成 `skills/hithink-finance-shared/` 与 `skills/manifest.json`。 验证：`npm run generate:contracts` 重跑后无额外差异；`npm run verify` 全绿。 --- hithink-finance-cli/scripts/generate-contracts.mjs | 10 +++++++--- .../skills/hithink-finance-shared/SKILL.md | 2 +- .../hithink-finance-shared/references/lifecycle.md | 8 ++++++-- hithink-finance-cli/skills/manifest.json | 4 ++-- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/hithink-finance-cli/scripts/generate-contracts.mjs b/hithink-finance-cli/scripts/generate-contracts.mjs index aa933bb..1c2c9e7 100644 --- a/hithink-finance-cli/scripts/generate-contracts.mjs +++ b/hithink-finance-cli/scripts/generate-contracts.mjs @@ -72,7 +72,7 @@ const domainConfigs = { ], [ '更新 CLI', - '`hithink-finance update --check --format json` 或 `hithink-finance update --repair --format json`', + '`hithink-finance update --check --format json` 确认目标版本后，用 `hithink-finance update --repair --target-version --format json` 升级', ], ['预览卸载', '`hithink-finance uninstall --plan --format json`'], ], @@ -486,12 +486,14 @@ hithink-finance version --format json hithink-finance doctor --format json hithink-finance update --check --format json hithink-finance update --repair --format json +hithink-finance update --repair --target-version --format json hithink-finance uninstall --plan --format json \`\`\` ## 参数选择策略 -- 先 \`update --check\`，只有用户确认修复/升级时再 \`update --repair\`。 +- 先 \`update --check\` 确认当前版本与目标版本；\`update --repair\` 只修复当前安装，不会改变已安装的版本。 +- 跨版本升级或安装指定版本必须显式加 \`--target-version \`，例如 \`hithink-finance update --repair --target-version 0.1.8 --format json\`；回滚同样传入目标旧版本。 - 卸载先 \`uninstall --plan\`，真实清理按计划和用户确认执行。 - Skills、更新和卸载的前台子进程响应 SIGINT/SIGTERM 并具有执行时限；Windows 使用 taskkill，POSIX 使用独立进程组，都会终止前台进程树；超时返回 \`CLI_CHILD_TIMEOUT\`，CLI 保留 130/143 信号退出码。 - 普通命令的 detached 更新检查由跨进程租约保护，同一状态目录最多一个刷新任务。 @@ -501,7 +503,9 @@ hithink-finance uninstall --plan --format json ## 常见错误 - 普通命令可能在完成后向 stderr 输出更新提示；不要把它混入业务数据。 -- 不要因为更新提示中断取数、翻页或导出流程；需要升级时先运行 \`update --check\`，获得用户确认后再 \`update --repair\`。 +- 不要因为更新提示中断取数、翻页或导出流程；需要升级时先运行 \`update --check\` 确认目标版本，获得用户确认后再运行 \`update --repair --target-version \`。 +- 只说「升级」而不传 \`--target-version\` 时，\`update --repair\` 会返回成功但版本号不变；不要据此认为升级已完成，应先比对 \`update --check\` 的 \`current_version\` 与 \`latest_version\`。 +- \`--target-version\` 只接受合法 SemVer 版本号；执行后仍须用 \`hithink-finance version --format json\` 复核实际生效版本。 `, 'skills-management.md': `# Skills 管理 diff --git a/hithink-finance-cli/skills/hithink-finance-shared/SKILL.md b/hithink-finance-cli/skills/hithink-finance-shared/SKILL.md index 8c75a08..b3a6a01 100644 --- a/hithink-finance-cli/skills/hithink-finance-shared/SKILL.md +++ b/hithink-finance-cli/skills/hithink-finance-shared/SKILL.md @@ -28,7 +28,7 @@ description: '用于 Agent 通过 hithink-finance CLI 做安装后自检、API K | 查看非敏感配置 | `hithink-finance config show --format json` | | 诊断运行环境 | `hithink-finance doctor --format json` | | 同步/修复配套 Skills | `hithink-finance skills status --format json` 或 `hithink-finance skills sync --format json` | -| 更新 CLI | `hithink-finance update --check --format json` 或 `hithink-finance update --repair --format json` | +| 更新 CLI | `hithink-finance update --check --format json` 确认目标版本后，用 `hithink-finance update --repair --target-version --format json` 升级 | | 预览卸载 | `hithink-finance uninstall --plan --format json` | ## References diff --git a/hithink-finance-cli/skills/hithink-finance-shared/references/lifecycle.md b/hithink-finance-cli/skills/hithink-finance-shared/references/lifecycle.md index ae44f78..87ae1eb 100644 --- a/hithink-finance-cli/skills/hithink-finance-shared/references/lifecycle.md +++ b/hithink-finance-cli/skills/hithink-finance-shared/references/lifecycle.md @@ -7,12 +7,14 @@ hithink-finance version --format json hithink-finance doctor --format json hithink-finance update --check --format json hithink-finance update --repair --format json +hithink-finance update --repair --target-version --format json hithink-finance uninstall --plan --format json ``` ## 参数选择策略 -- 先 `update --check`，只有用户确认修复/升级时再 `update --repair`。 +- 先 `update --check` 确认当前版本与目标版本；`update --repair` 只修复当前安装，不会改变已安装的版本。 +- 跨版本升级或安装指定版本必须显式加 `--target-version `，例如 `hithink-finance update --repair --target-version 0.1.8 --format json`；回滚同样传入目标旧版本。 - 卸载先 `uninstall --plan`，真实清理按计划和用户确认执行。 - Skills、更新和卸载的前台子进程响应 SIGINT/SIGTERM 并具有执行时限；Windows 使用 taskkill，POSIX 使用独立进程组，都会终止前台进程树；超时返回 `CLI_CHILD_TIMEOUT`，CLI 保留 130/143 信号退出码。 - 普通命令的 detached 更新检查由跨进程租约保护，同一状态目录最多一个刷新任务。 @@ -22,4 +24,6 @@ hithink-finance uninstall --plan --format json ## 常见错误 - 普通命令可能在完成后向 stderr 输出更新提示；不要把它混入业务数据。 -- 不要因为更新提示中断取数、翻页或导出流程；需要升级时先运行 `update --check`，获得用户确认后再 `update --repair`。 +- 不要因为更新提示中断取数、翻页或导出流程；需要升级时先运行 `update --check` 确认目标版本，获得用户确认后再运行 `update --repair --target-version `。 +- 只说「升级」而不传 `--target-version` 时，`update --repair` 会返回成功但版本号不变；不要据此认为升级已完成，应先比对 `update --check` 的 `current_version` 与 `latest_version`。 +- `--target-version` 只接受合法 SemVer 版本号；执行后仍须用 `hithink-finance version --format json` 复核实际生效版本。 diff --git a/hithink-finance-cli/skills/manifest.json b/hithink-finance-cli/skills/manifest.json index 1029ce2..bebad23 100644 --- a/hithink-finance-cli/skills/manifest.json +++ b/hithink-finance-cli/skills/manifest.json @@ -89,10 +89,10 @@ "hithink-finance-options/references/options-varieties.md": "18dd73168876e74e7741eb5710191f16815f8e40c20d5fc874fc3d435013de54", "hithink-finance-research/SKILL.md": "7f4ded9d172a2bb2578ac81266ef869521c7d753f2a021c7aa79fc6d0f92541c", "hithink-finance-research/references/research-workflow.md": "3f73f179339b21403e7f8f6bfd7fcb2649f06ffc6b6bccb428b18cb19929dad5", - "hithink-finance-shared/SKILL.md": "8b02e5c2a07d79d818fb5e2b41f6d83afcc39cfc671aba0d4ac87068710c36ab", + "hithink-finance-shared/SKILL.md": "ae3f214e0113ef30abe044c551f0133c8eb39d49b3902afd7db8d7a950beeac6", "hithink-finance-shared/references/auth-and-config.md": "200c37bae0ab696580055a29be6e39c6d9d003e418a425baafd3a07872bb4e11", "hithink-finance-shared/references/global-rules.md": "8beab5ddcb83c22165268989685c9e44c7489c934a380a388e77542a02dcedc7", - "hithink-finance-shared/references/lifecycle.md": "747049d179dcfb49fc9e9460f3bd794bfcf0b7fc5958e689b3a31fafde256c57", + "hithink-finance-shared/references/lifecycle.md": "f0e1fb154bb9eda7e59002d48810d3beaa2f9f041f370278d2f429aed5871019", "hithink-finance-shared/references/skills-management.md": "1872d129dd113922990e7b43c42e520bf1ff889d2b3cd06872935bd8e05f15c0", "hithink-finance-special-data/SKILL.md": "e949daf45eded1be23a0e4a2f6db9e10bc5a8ca6e8e188e89953140ca3d1e375", "hithink-finance-special-data/references/special-anomaly-list.md": "98f7bac44eb040ff80fd06185bd9ac811fdd7d46fa6c7695a32e808eda3bd2fd",