Skip to content

docs(skills): 补全 update --target-version 用法 - #71

Closed
Espressohan wants to merge 1 commit into
HiThink-Tech:mainfrom
Espressohan:docs/update-target-version
Closed

Espressohan wants to merge 1 commit into
HiThink-Tech:mainfrom
Espressohan:docs/update-target-version

Conversation

@Espressohan

Copy link
Copy Markdown

问题

hithink-finance-shared 的 lifecycle.md(以及 shared SKILL.md 的快速决策表)把更新流程写成:

先 update --check,只有用户确认修复/升级时再 update --repair。

实测 update --repair 只修复当前安装,不会改变已安装的版本号。在提示有新版可用时按文档执行,命令会返回 {"ok":true,"command":"update","data":{"version":"<当前版本>","repaired":true}}——成功但版本不变;跨版本升级必须显式传 --target-version <version>:

# 0.1.7 环境下
$ hithink-finance update --repair --format json
{"ok":true,"command":"update","data":{"version":"0.1.7","repaired":true}, ...}   # 版本未变

$ hithink-finance update --repair --target-version 0.1.8 --format json
{"ok":true,"command":"update","data":{"version":"0.1.8","repaired":true}, ...}   # 升级成功

--target-version 在 update --help 中存在,但两个 skill 文档都没有提到它,Agent 容易把「已确认升级」误报为完成。

改动

只改生成源,并按仓库约定重新生成派生产物:

文件 说明
hithink-finance-cli/scripts/generate-contracts.mjs 更新 shared 决策表条目与 sharedReferenceFiles['lifecycle.md'] 模板
hithink-finance-cli/skills/hithink-finance-shared/references/lifecycle.md 重新生成
hithink-finance-cli/skills/hithink-finance-shared/SKILL.md 重新生成
hithink-finance-cli/skills/manifest.json 重新生成(上述两个文件的 sha256 更新)

具体补充内容:--target-version 命令示例、回滚说明、以及「只写升级而未传 --target-version 时版本号不变,应比对 update --check 的 current_version / latest_version」的排查要点。

验证

cd hithink-finance-cli
npm ci
npm run generate:contracts   # 重跑后 git diff 无额外变化,仅上述 4 个文件
npm run verify               # format:check + lint + typecheck + build + vitest 全绿
  • npm run generate:contracts 重跑后改动集不变,确认生成源与产物同步;
  • skills/manifest.json 109 个条目的 sha256 与磁盘文件逐一复核一致;
  • npm run verify 通过:54 个测试文件、178 个测试。

`update --repair` 只修复当前安装,不会改变已安装的版本号;原文档未说明
跨版本升级必须显式传入 `--target-version <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-Tech

Copy link
Copy Markdown
Owner

审查意见(P1):本 PR 修正了 Skill 文档,但实际更新提示仍在 hithink-finance-cli/src/infrastructure/updater/check.ts 中建议用户执行 hithink-finance update --repair。而 update.ts 在未提供 --target-version 时会安装 metadata.version,不会升级到检测到的最新版本。因此终端仍会持续给出会“成功但版本不变”的错误指引。

请同时更新该提示(使用检测到的 latestVersion,或明确要求先取得并传入目标版本),并增加覆盖该提示内容的测试;否则这次文档修复不能完整解决用户实际接收到的错误操作路径。

@HiThink-Tech

Copy link
Copy Markdown
Owner

感谢反馈。我们已确认:update --repair 在未指定 --target-version 时只会修复当前安装,不会升级到检测到的最新版本;现有 Skill 文档和运行时更新提示容易让 Agent 或用户误判升级已经完成。

修复方案会统一 CLI 行为说明与用户提示:保留 update --repair 默认修复当前版本的语义;跨版本升级时显式携带检测到的 latestVersion;同时补充运行时提示测试,确保文档、提示和实际行为一致。该修复将在下一个版本更新时一并交付。

考虑到本次需要由维护方连同 CLI 提示和测试统一修复,我们先关闭此 PR,不合并当前提交。再次感谢你提供完整的复现、修复方向和验证结果。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants