@sakanano-moe/agenthelm 6.11.0-rc.2 → 6.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -31,7 +31,23 @@ from typing import Any
31
31
  from i18n_agent_pack import _, N_ # noqa: E402
32
32
 
33
33
  MARKETPLACE = "agenthelm"
34
- CLI = "npx @sakanano-moe/agenthelm"
34
+ NPX = "npx @sakanano-moe/agenthelm"
35
+
36
+
37
+ def cli_command(root: Path | None = None) -> str:
38
+ """The command printed in hints. A stable runtime keeps the plain ``npx`` form, which resolves to npm's
39
+ ``latest``. A pre-release runtime (``6.11.0-rc.2``) pins ``@<that version>``: an untagged npx would fetch the
40
+ older stable release, and ``@next`` may already point at a newer candidate. The npm package version equals the
41
+ suite version (release.yml sets it from the tag), so the pinned command runs exactly this runtime's code."""
42
+ try:
43
+ import agenthelm_runtime # noqa: PLC0415 - shipped next to this file
44
+ label = agenthelm_runtime.running_label(root if root is not None else Path(__file__).resolve().parents[3])
45
+ except Exception: # noqa: BLE001 - a hint must never break the command
46
+ return NPX
47
+ return f"{NPX}@{label}" if label and "-" in label else NPX
48
+
49
+
50
+ CLI = cli_command()
35
51
  DEFAULT_LATEST_URLS = (
36
52
  "https://agenthelm.sakanano.moe/latest.json",
37
53
  "https://raw.githubusercontent.com/lc4t/agenthelm/main/latest.json",
@@ -382,6 +398,38 @@ def declared_marketplaces(env: Env, project: Path | None) -> list[dict]:
382
398
  return found
383
399
 
384
400
 
401
+ def market_sync_problem(env: Env, declared: list[dict]) -> dict | None:
402
+ """Why Claude Code cannot update right now: ``settings.json`` declares the agenthelm market, but the market Claude
403
+ Code has registered (``plugins/known_marketplaces.json``) is missing or came from another source / ref. Claude Code
404
+ only registers a declared market at start-up, so the update fails with "Marketplace 'agenthelm' not found" until it
405
+ restarts. None: no declaration, or both agree. Unverified against a real client: the record layout is assumed."""
406
+ if not declared:
407
+ return None
408
+ path = env.claude_dir / "plugins" / "known_marketplaces.json"
409
+ wanted = declared_source_text(declared[0]["source"])
410
+ registered = None
411
+ try:
412
+ record = read_json(path).get(MARKETPLACE)
413
+ registered = declared_source_text(record["source"]) if isinstance(record, dict) and "source" in record else None
414
+ code = None if registered is not None and all(
415
+ registered == declared_source_text(item["source"]) for item in declared) else (
416
+ "not-registered" if registered is None else "source-differs")
417
+ except FileNotFoundError:
418
+ code = "not-registered"
419
+ except (OSError, ValueError, AttributeError):
420
+ code = "unreadable"
421
+ if code is None:
422
+ return None
423
+ if code == "source-differs":
424
+ wanted = next(declared_source_text(item["source"]) for item in declared
425
+ if declared_source_text(item["source"]) != registered)
426
+ reason = {"not-registered": _("Claude Code 还没有登记 agenthelm 市场({0} 里没有它),而 settings.json 已声明 {1}").format(path, wanted),
427
+ "unreadable": _("读不到 Claude Code 的已登记市场({0} 无法解析),而 settings.json 已声明 {1}").format(path, wanted),
428
+ "source-differs": _("settings.json 声明的市场是 {0},Claude Code 已登记的是 {1}").format(wanted, registered)}[code]
429
+ return {"status": "blocked", "reason_code": code, "reason": reason, "declared": wanted, "registered": registered,
430
+ "next": _("重启 Claude Code 让它按 settings.json 登记市场;或手动执行:claude plugin marketplace add {0}").format(wanted)}
431
+
432
+
385
433
  def migrations_between(latest: dict, plugin: str, current: str, target: str) -> list[dict]:
386
434
  """The steps from ``current`` to ``target``; when two entries end at the same version (a span kept for the
387
435
  release gate and the single steps inside it) the narrower one, with the newer ``from``, is shown."""
@@ -457,6 +505,24 @@ def declared_source_text(source: Any) -> str:
457
505
  return f"{target}#{ref}" if ref and kind in {"github", "git", "url"} else str(target)
458
506
 
459
507
 
508
+ def release_tag(latest: dict) -> str | None:
509
+ """The tag of the release ``latest`` describes (None: latest.json carries no release block)."""
510
+ release = latest.get("release")
511
+ tag = release.get("tag") if isinstance(release, dict) else None
512
+ return str(tag) if tag else None
513
+
514
+
515
+ def market_pin(latest: dict, declared: list[dict]) -> dict | None:
516
+ """A declaration of the agenthelm repository pinned to a ref, with whether that ref is the release ``latest`` describes."""
517
+ tag = release_tag(latest)
518
+ for item in declared:
519
+ source = item["source"]
520
+ if isinstance(source, dict) and source.get("ref") and not market_conflict(latest, [{**item, "source": {k: v for k, v in source.items() if k != "ref"}}]):
521
+ return {"scope": item["scope"], "file": item["file"], "ref": source["ref"], "target": tag,
522
+ "at_target": bool(tag) and source["ref"] == tag}
523
+ return None
524
+
525
+
460
526
  def market_conflict(latest: dict, declared: list[dict]) -> dict | None:
461
527
  """Claude Code refuses ``marketplace add`` for a name whose declared source differs (issue #31 comment, measured on
462
528
  macOS): flag a declaration that points elsewhere, or that pins a ref (a later `marketplace add` without it is refused)."""
@@ -474,6 +540,8 @@ def market_conflict(latest: dict, declared: list[dict]) -> dict | None:
474
540
  if not same:
475
541
  return {**item, "reason": "points-elsewhere", "declared": declared_source_text(source), "ref": source.get("ref")}
476
542
  if source.get("ref"):
543
+ if release_tag(latest) == source.get("ref"):
544
+ continue # pinned to the very release being checked: nothing to resolve
477
545
  return {**item, "reason": "pinned", "declared": declared_source_text(source), "ref": source.get("ref")}
478
546
  return None
479
547
 
@@ -492,7 +560,8 @@ def _origin_text(record: dict) -> str:
492
560
  return f"{text} {extra}" if extra else text
493
561
 
494
562
 
495
- def diagnose_client(client: str, latest: dict, findings: list[dict], others: list[dict], conflict: dict | None) -> dict:
563
+ def diagnose_client(client: str, latest: dict, findings: list[dict], others: list[dict], conflict: dict | None,
564
+ pin: dict | None = None) -> dict:
496
565
  names = sorted(latest.get("plugins", {}))
497
566
  legacy = [item for item in findings if item["client"] == "legacy"] if client in {"claude", "codex"} else []
498
567
  records = [_install_record(item) for item in findings if item["client"] == client]
@@ -533,8 +602,11 @@ def diagnose_client(client: str, latest: dict, findings: list[dict], others: lis
533
602
  "conflicts": [{"plugin": c["plugin"], "versions_differ": c["versions_differ"],
534
603
  "effective": None} for c in clashes],
535
604
  "market_conflict": {k: conflict[k] for k in ("scope", "file", "reason", "declared", "ref")} if conflict else None,
536
- "untouched": [{"plugin": item["plugin"], "path": item["path"], "origin": item["origin"]} for item in dev]}
605
+ "untouched": [{"plugin": item["plugin"], "path": item["path"], "origin": item["origin"]} for item in dev],
606
+ "market_pin": pin}
537
607
  diag.update(_advice(diag, client))
608
+ if pin and pin["at_target"]:
609
+ diag["summary"] += _("settings 把 agenthelm 市场固定在目标版本 {0},无需改动。").format(pin["ref"])
538
610
  return diag
539
611
 
540
612
 
@@ -612,6 +684,7 @@ def install_state(env: Env, latest: dict, findings: list[dict], others: list[dic
612
684
  """Per selected client: none / partial / marketplace(current|behind|ahead) / dev / legacy / mixed / market-conflict."""
613
685
  detected = set(detect_clients(env))
614
686
  conflict = market_conflict(latest, declared)
687
+ pin = market_pin(latest, declared)
615
688
  result: dict = {"clients": {}, "unconfirmed": [
616
689
  "claude marketplace add on a same-named marketplace beyond the measured declared-source mismatch",
617
690
  "claude --plugin-dir leaves no record in installed_plugins.json",
@@ -624,7 +697,8 @@ def install_state(env: Env, latest: dict, findings: list[dict], others: list[dic
624
697
  scoped = [item for item in findings
625
698
  if item["client"] != "legacy" or legacy_owner(env, item) in {client, None}]
626
699
  result["clients"][client] = diagnose_client(client, latest, scoped, others,
627
- conflict if client == "claude" else None)
700
+ conflict if client == "claude" else None,
701
+ pin if client == "claude" else None)
628
702
  return result
629
703
 
630
704
 
@@ -856,13 +930,13 @@ def local_only_plan(env: Env, project: Path | None, **options: Any) -> dict:
856
930
 
857
931
  # ---------------------------------------------------------------- report
858
932
 
859
- def baseline_less_differences(env: Env, project: Path | None) -> int:
860
- """How many project files differ from the template with no baseline in the content lock (check's content-differs findings)."""
933
+ def baseline_less_differences(env: Env, project: Path | None) -> list[str]:
934
+ """Project files that differ from the template with no baseline in the content lock (check's content-differs findings)."""
861
935
  try:
862
936
  report = scaffold_report(env, project)
863
937
  except Exception: # noqa: BLE001 - a hint only; never let it break update
864
- return 0
865
- return sum(1 for item in (report or {}).get("findings", []) if item.get("kind") == "content-differs")
938
+ return []
939
+ return [item["path"] for item in (report or {}).get("findings", []) if item.get("kind") == "content-differs" and item.get("path")]
866
940
 
867
941
 
868
942
  def scaffold_fingerprint(env: Env, scaffold: dict | None) -> dict | None:
@@ -919,7 +993,7 @@ def unused_client_hints(env: Env, plugins: list[dict], ignored: list[str]) -> li
919
993
 
920
994
  def run_check(env: Env, project: Path | None, *, latest_source: str | None = None, offline: bool = False,
921
995
  max_age: int = CACHE_TTL_SECONDS, hook_mode: bool = False, reprompt: bool = False,
922
- clients: list[str] | None = None) -> dict:
996
+ clients: list[str] | None = None, source: Path | None = None) -> dict:
923
997
  latest, origin = load_latest(
924
998
  env, latest_source, offline=offline, max_age=max_age,
925
999
  timeout=HOOK_FETCH_TIMEOUT_SECONDS if hook_mode else FETCH_TIMEOUT_SECONDS, backoff=hook_mode,
@@ -940,8 +1014,21 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
940
1014
  local_attention = sum(1 for item in machine["findings"] if item.get("attention"))
941
1015
  scaffold_active = len(scaffold["findings"]) if scaffold else 0
942
1016
  # 只有“需要处理”的脚手架发现(level must)参与 up_to_date、--strict 与会话开始提示;旧版 agents-init 没有分级时按可选处理。
943
- scaffold_required = sum(1 for item in (scaffold["findings"] if scaffold else []) if item.get("level") == "must")
1017
+ scaffold_numbers = scaffold_counts(scaffold)
1018
+ scaffold_required = scaffold_numbers["required"]
944
1019
  behind = [item for item in plugins if item["status"] == "behind"]
1020
+ # Cursor is installed from a release tarball: when update would find none (no tag / digest, no --source) the user
1021
+ # cannot clear the finding, so it is listed as unavailable instead of counted as behind. Same decision as update.
1022
+ unavailable: list[dict] = []
1023
+ for item in plugins:
1024
+ item["unavailable"] = None
1025
+ if any(item["client"] == "cursor" for item in behind):
1026
+ reason = cursor_unavailable(latest, source, timeout=HOOK_FETCH_TIMEOUT_SECONDS if hook_mode else FETCH_TIMEOUT_SECONDS)
1027
+ for item in behind:
1028
+ if reason and item["client"] == "cursor":
1029
+ item["unavailable"] = reason
1030
+ unavailable = [item for item in behind if item.get("unavailable")]
1031
+ behind = [item for item in behind if not item.get("unavailable")]
945
1032
  # With --client, a legacy entry stays listed (it is a migration risk) but counts toward up_to_date only when its
946
1033
  # path says it belongs to a selected client; an entry whose owner cannot be told is listed and not counted.
947
1034
  for item in plugins:
@@ -950,7 +1037,8 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
950
1037
  legacy = [item for item in plugins if item["client"] == "legacy"
951
1038
  and (not selection["explicit"] or item["owner"] in selection["active"])]
952
1039
  legacy_unattributed = sum(1 for item in plugins if item["client"] == "legacy") - len(legacy)
953
- by_client = {name: {"behind": sum(1 for item in plugins if item["client"] == name and item["status"] == "behind"),
1040
+ by_client = {name: {"behind": sum(1 for item in behind if item["client"] == name),
1041
+ "unavailable": sum(1 for item in unavailable if item["client"] == name),
954
1042
  "total": sum(1 for item in plugins if item["client"] == name)}
955
1043
  for name in selection["active"] if any(item["client"] == name for item in plugins)}
956
1044
  content_updates = [item for item in content if item["status"] in {"update-available", "conflict"}]
@@ -977,11 +1065,13 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
977
1065
  "summary": {
978
1066
  "scaffold_findings": scaffold_active,
979
1067
  "scaffold_required": scaffold_required,
980
- "scaffold_optional": sum(1 for item in (scaffold["findings"] if scaffold else []) if item.get("level", "suggest") == "suggest"),
981
- "scaffold_info": sum(1 for item in (scaffold["findings"] if scaffold else []) if item.get("level") == "info"),
1068
+ "scaffold_optional": scaffold_numbers["optional"],
1069
+ "scaffold_info": scaffold_numbers["info"],
1070
+ "profile_notes": scaffold_numbers["profile_notes"],
982
1071
  "scaffold_skipped": len(scaffold["skipped"]) if scaffold else 0,
983
1072
  "local_only_attention": local_attention,
984
1073
  "plugins_behind": len(behind),
1074
+ "plugins_unavailable": len(unavailable),
985
1075
  "by_client": by_client,
986
1076
  "breaking": any(item["breaking"] for item in behind),
987
1077
  "content_updates": len(content_updates),
@@ -997,12 +1087,44 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
997
1087
  }
998
1088
 
999
1089
 
1000
- UPDATE_HINTS = {
1001
- "claude": "claude plugin marketplace update agenthelm && claude plugin update {plugin}@agenthelm",
1002
- "codex": "codex plugin marketplace upgrade agenthelm",
1003
- "cursor": f"{CLI} update",
1004
- "legacy": f"{CLI} migrate --install",
1005
- }
1090
+ def update_hint(client: str | None) -> str | None:
1091
+ """The command that updates a client's plugins; built when asked so it follows the current ``CLI``."""
1092
+ return {
1093
+ "claude": "claude plugin marketplace update agenthelm && claude plugin update {plugin}@agenthelm",
1094
+ "codex": "codex plugin marketplace upgrade agenthelm",
1095
+ "cursor": f"{CLI} update",
1096
+ "legacy": f"{CLI} migrate --install",
1097
+ }.get(client or "")
1098
+
1099
+
1100
+ def _client_state(name: str, item: dict) -> str:
1101
+ if item["behind"]:
1102
+ text = _("{0}:{1} 个可更新").format(CLIENT_NAMES[name], item["behind"])
1103
+ elif item.get("unavailable"):
1104
+ return _("{0}:{1} 个不可用,需 --source 本地源").format(CLIENT_NAMES[name], item["unavailable"])
1105
+ else:
1106
+ return _("{0}:已是最新").format(CLIENT_NAMES[name])
1107
+ if item.get("unavailable"):
1108
+ text += _(",另有 {0} 个不可用(需 --source 本地源)").format(item["unavailable"])
1109
+ return text
1110
+
1111
+
1112
+ def profile_note_counts(scaffold: dict) -> tuple[int, int]:
1113
+ """(conflicting values, undeclared fields): the two kinds of Profile information shown as ``[脚手架·信息]`` lines."""
1114
+ return (len(scaffold.get("profile_conflicts") or []), int((scaffold.get("profile_extras") or {}).get("total") or 0))
1115
+
1116
+
1117
+ def scaffold_counts(scaffold: dict | None) -> dict[str, int]:
1118
+ """The one place that counts scaffold items; ``summary`` (JSON) and the text both read it.
1119
+ ``info`` is everything the text prints as 脚手架·信息: info-level findings plus the Profile notes."""
1120
+ if not scaffold:
1121
+ return {"required": 0, "optional": 0, "info": 0, "profile_notes": 0}
1122
+ findings = scaffold.get("findings") or []
1123
+ notes = sum(profile_note_counts(scaffold))
1124
+ return {"required": sum(1 for item in findings if item.get("level") == "must"),
1125
+ "optional": sum(1 for item in findings if item.get("level", "suggest") == "suggest"),
1126
+ "info": sum(1 for item in findings if item.get("level") == "info") + notes,
1127
+ "profile_notes": notes}
1006
1128
 
1007
1129
 
1008
1130
  def one_line(report: dict) -> str | None:
@@ -1014,9 +1136,7 @@ def one_line(report: dict) -> str | None:
1014
1136
  text = _("{0} 个插件可更新").format(summary['plugins_behind']) + (_("(含不兼容变更)") if summary["breaking"] else "")
1015
1137
  per_client = summary.get("by_client") or {}
1016
1138
  if per_client:
1017
- text += _("(") + _(";").join(
1018
- (_("{0}:{1} 个可更新").format(CLIENT_NAMES[name], item["behind"]) if item["behind"]
1019
- else _("{0}:已是最新").format(CLIENT_NAMES[name])) for name, item in per_client.items()) + _(")")
1139
+ text += _("(") + _(";").join(_client_state(name, item) for name, item in per_client.items()) + _(")")
1020
1140
  parts.append(text)
1021
1141
  if summary["content_updates"]:
1022
1142
  parts.append(_("{0} 个模板/样例包可更新").format(summary['content_updates'])
@@ -1039,7 +1159,7 @@ def render_profile_notes(scaffold: dict, show_extras: bool) -> list[str]:
1039
1159
  lines = []
1040
1160
  for item in scaffold.get("profile_conflicts") or []:
1041
1161
  lines.append(_(" [脚手架·信息] {0}").format(item["message"]))
1042
- summary = scaffold.get("profile_extras") or {}
1162
+ summary = dict(scaffold.get("profile_extras") or {}, total=profile_note_counts(scaffold)[1])
1043
1163
  if not summary.get("total"):
1044
1164
  return lines
1045
1165
  parts = [_("项目自有 {0}").format(summary["own"])]
@@ -1177,6 +1297,7 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1177
1297
  lines += render_install_state(report.get("install_state") or {})
1178
1298
  if not report["plugins"]:
1179
1299
  lines.append(_("未发现已安装的 agenthelm 插件。"))
1300
+ shown_breaking: dict[tuple[str, str], str] = {} # (plugin, target version) -> client whose line carries the notes
1180
1301
  for item in report["plugins"]:
1181
1302
  label = {"behind": _("可更新"), "current": _("最新"), "ahead": _("高于云端"), "unknown": _("版本未知"),
1182
1303
  "legacy": _("旧方式安装,待迁移"), "dev": _("开发版/本地安装,不会被 update / migrate 改动")}[item["status"]]
@@ -1186,6 +1307,8 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1186
1307
  if item["status"] == "dev":
1187
1308
  lines.append(_(" [{0}] {1} {2} {3}({4})").format(item['client'], item['plugin'], item.get('version'), label, item['path']))
1188
1309
  continue
1310
+ if item.get("unavailable"):
1311
+ label = _("不可用(需 --source 本地源,不计入“可更新”)")
1189
1312
  line = f" [{item['client']}] {item['plugin']} {item.get('version')} → {item.get('latest')} {label}"
1190
1313
  if item["status"] == "behind":
1191
1314
  kinds = {"code": _("代码"), "content": _("仅模板/样例"), "both": _("代码与模板")}
@@ -1195,10 +1318,18 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1195
1318
  line += _("(含不兼容变更)")
1196
1319
  for step in item["steps"]:
1197
1320
  if step.get("breaking"):
1321
+ key = (item["plugin"], str(step["to"]))
1322
+ if key in shown_breaking: # same plugin, same step: print the notes once, on the first client
1323
+ line += _("\n {0} 不兼容:同上(见 {1})").format(step['to'], shown_breaking[key])
1324
+ continue
1325
+ shown_breaking[key] = item["client"]
1198
1326
  line += _("\n {0} 不兼容:{1}").format(step['to'], step.get('summary'))
1199
1327
  line += "".join(f"\n - {action}" for action in step.get("actions") or [])
1200
- hint = UPDATE_HINTS.get(item["client"])
1201
- if hint:
1328
+ hint = update_hint(item["client"])
1329
+ if item.get("unavailable"):
1330
+ line += _("\n {0}\n 有本地仓库时:{1} update --source <本地仓库>;不使用 Cursor 时:{1} config ignore-client cursor --apply").format(
1331
+ item["unavailable"], CLI)
1332
+ elif hint:
1202
1333
  line += _("\n 更新:{0}").format(hint.format(plugin=item['plugin']))
1203
1334
  lines.append(line)
1204
1335
  for item in report["content"]:
@@ -1224,7 +1355,7 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1224
1355
  lines.append(_("运行 `{0} install` 预览安装。").format(CLI))
1225
1356
  else:
1226
1357
  if any(item["status"] == "legacy" for item in report["plugins"]):
1227
- lines.append(_("旧方式安装可用 `{0}` 预览迁移。").format(UPDATE_HINTS['legacy']))
1358
+ lines.append(_("旧方式安装可用 `{0}` 预览迁移。").format(update_hint('legacy')))
1228
1359
  if report["summary"].get("legacy_other_clients"):
1229
1360
  lines.append(_("其中 {0} 个旧方式安装不属于所选客户端(或无法判断归属),已列出但未计入“是否最新”。").format(
1230
1361
  report["summary"]["legacy_other_clients"]))
@@ -1376,7 +1507,7 @@ def _plugin_versions(latest: dict) -> dict:
1376
1507
  return {name: item.get("version") for name, item in latest.get("plugins", {}).items()}
1377
1508
 
1378
1509
 
1379
- def github_release(latest: dict) -> dict:
1510
+ def github_release(latest: dict, timeout: float = FETCH_TIMEOUT_SECONDS) -> dict:
1380
1511
  """Release details straight from GitHub, used when latest.json came from the raw fallback.
1381
1512
 
1382
1513
  Accepted only when that tag ships exactly the plugin versions ``latest`` lists,
@@ -1384,13 +1515,31 @@ def github_release(latest: dict) -> dict:
1384
1515
  """
1385
1516
  try:
1386
1517
  slug = github_slug(latest)
1387
- release = _fetch_json(f"https://github.com/{slug}/releases/latest/download/release.json")
1388
- tagged = _fetch_json(f"https://raw.githubusercontent.com/{slug}/{release['tag']}/latest.json")
1518
+ release = _fetch_json(f"https://github.com/{slug}/releases/latest/download/release.json", timeout)
1519
+ tagged = _fetch_json(f"https://raw.githubusercontent.com/{slug}/{release['tag']}/latest.json", timeout)
1389
1520
  except (OSError, ValueError, KeyError, TypeError, CheckError, urllib.error.URLError):
1390
1521
  return {}
1391
1522
  return release if _plugin_versions(tagged) == _plugin_versions(latest) else {}
1392
1523
 
1393
1524
 
1525
+ def release_problem(release: dict) -> str | None:
1526
+ """Why the release cannot be downloaded (None when it can). The one rule behind Cursor's “unavailable”:
1527
+ ``update`` / ``install`` raise it as :class:`Unavailable`, ``check`` uses it to keep Cursor out of the “behind” count."""
1528
+ if release.get("tag") and release.get("tarball_sha256"):
1529
+ return None
1530
+ return _("云端 latest.json 没有发布 tag 与摘要;请用 --source 指定本地仓库")
1531
+
1532
+
1533
+ def cursor_unavailable(latest: dict, source: Path | None = None, *, timeout: float = FETCH_TIMEOUT_SECONDS) -> str | None:
1534
+ """Why Cursor cannot be updated on this run (None when it can): the same decision :func:`release_source` makes.
1535
+
1536
+ A local ``--source`` is always usable (it is validated when the update runs); otherwise the release needs a tag
1537
+ and a digest, from latest.json or, failing that, from GitHub."""
1538
+ if source is not None:
1539
+ return None
1540
+ return release_problem(latest.get("release") or github_release(latest, timeout))
1541
+
1542
+
1394
1543
  def release_source(latest: dict, workdir: Path, source: Path | None = None) -> Path:
1395
1544
  """A directory with plugins/<name>: a local checkout, or the tagged release tarball."""
1396
1545
  if source is not None:
@@ -1400,8 +1549,9 @@ def release_source(latest: dict, workdir: Path, source: Path | None = None) -> P
1400
1549
  return root
1401
1550
  release = latest.get("release") or github_release(latest)
1402
1551
  tag, digest = release.get("tag"), release.get("tarball_sha256")
1403
- if not tag or not digest:
1404
- raise Unavailable(_("云端 latest.json 没有发布 tag 与摘要;请用 --source 指定本地仓库"))
1552
+ problem = release_problem(release)
1553
+ if problem:
1554
+ raise Unavailable(problem)
1405
1555
  url = release.get("tarball_url") or f"https://github.com/{github_slug(latest)}/releases/download/{tag}/agenthelm-{tag}.tar.gz"
1406
1556
  archive = workdir / "release.tar.gz"
1407
1557
  request = urllib.request.Request(url, headers={"User-Agent": "agenthelm"})
@@ -1445,6 +1595,9 @@ class Step:
1445
1595
  skipped: str | None = None
1446
1596
  note: str | None = None
1447
1597
  untouched: bool = False # an install the tool recognises but leaves alone (development / local)
1598
+ pinned: str | None = None # the ref Claude's marketplace declaration is pinned to (updates only follow it)
1599
+ blocker: str | None = None # machine-readable cause of ``blocked`` that the user has to resolve (not a missing CLI)
1600
+ next: str | None = None
1448
1601
 
1449
1602
  def view(self) -> dict:
1450
1603
  data = {"kind": self.kind, "client": self.client, "description": self.description}
@@ -1452,6 +1605,9 @@ class Step:
1452
1605
  data["command"] = " ".join(self.command)
1453
1606
  if self.blocked:
1454
1607
  data["blocked"] = self.blocked
1608
+ if self.blocker:
1609
+ data["blocker"] = self.blocker
1610
+ data["next"] = self.next
1455
1611
  if self.skipped:
1456
1612
  data["skipped"] = self.skipped
1457
1613
  if self.note:
@@ -1575,6 +1731,26 @@ def cursor_step(latest: dict, plugins: list[str], source: Path | None, home: Pat
1575
1731
  targets={plugin: latest.get("plugins", {}).get(plugin, {}).get("version") for plugin in plugins}, note=note)
1576
1732
 
1577
1733
 
1734
+ def claude_market_sync(env: Env, report: dict, project: Path | None, only: str | None) -> dict | None:
1735
+ """A1: the market problem that would make Claude's update steps fail, found before anything runs."""
1736
+ if only not in (None, "plugins") or not any(item["status"] == "behind" and item["client"] == "claude"
1737
+ for item in report["plugins"]):
1738
+ return None
1739
+ return market_sync_problem(env, declared_marketplaces(env, project))
1740
+
1741
+
1742
+ def codex_pin_advice(latest: dict) -> str:
1743
+ """A9: pin Codex's agenthelm marketplace to the release. ``--ref`` and ``owner/repo@ref`` are in the Codex plugin docs
1744
+ (developers.openai.com/codex/plugins/build); whether ``add`` replaces an existing same-named market is unconfirmed."""
1745
+ try:
1746
+ slug = github_slug(latest)
1747
+ except CheckError:
1748
+ return _("固定 Codex 市场的方法见 INSTALL.md 第 4 节")
1749
+ tag = release_tag(latest) or "<tag>"
1750
+ return _("codex plugin marketplace add {0} --ref {1}(若提示该市场已存在,先 codex plugin marketplace remove {2};"
1751
+ "移除对已装插件的影响未确认);详见 INSTALL.md 第 4 节").format(slug, tag, MARKETPLACE)
1752
+
1753
+
1578
1754
  def update_steps(env: Env, report: dict, project: Path | None, source: Path | None, home: Path,
1579
1755
  accept: list[str], keep: list[str], recovery_dir: Path | None,
1580
1756
  only: str | None, *, content_flags: list[str] | None = None) -> list[Step]:
@@ -1585,13 +1761,27 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
1585
1761
  claude = sorted({item["plugin"] for item in behind if item["client"] == "claude"})
1586
1762
  if claude:
1587
1763
  command, blocked = _cli(env, "claude", "plugin", "marketplace", "update", MARKETPLACE)
1588
- steps.append(Step("update", "claude", _("刷新 Claude Code 的 agenthelm 市场"), command, blocked=blocked))
1764
+ pin = ((report.get("install_state") or {}).get("clients", {}).get("claude") or {}).get("market_conflict")
1765
+ pinned = str(pin["ref"]) if pin and pin.get("reason") == "pinned" and pin.get("ref") else None
1766
+ note = None
1767
+ if pinned:
1768
+ newest = max((entry["latest"] for entry in behind if entry["client"] == "claude" and entry.get("latest")),
1769
+ key=lambda text: version_key(text) or (0,), default="?")
1770
+ note = _("提示:Claude 的 settings 把 agenthelm 市场固定在 {0},更新只会跟随这个 ref,版本可能不会变(最新版本 {1})。"
1771
+ "要让它跟随新版本:把 settings.json 里 agenthelm 市场声明的 ref 改成目标 tag,或去掉 ref 跟随 main(agenthelm 不会替你改 settings.json)。"
1772
+ ).format(pinned, newest)
1773
+ if release_tag(latest):
1774
+ note += _("目标 tag:{0}。").format(release_tag(latest))
1775
+ sync = report.get("market_sync")
1776
+ block = dict(blocked=sync["reason"], blocker="market-not-synced", next=sync["next"]) if sync else {}
1777
+ steps.append(Step("update", "claude", _("刷新 Claude Code 的 agenthelm 市场"), command, **{"blocked": blocked, **block},
1778
+ note=note, pinned=pinned))
1589
1779
  for item in [entry for entry in behind if entry["client"] == "claude"]:
1590
1780
  extra = ["--scope", item["scope"]] if item.get("scope") and item["scope"] != "user" else []
1591
1781
  command, blocked = _cli(env, "claude", "plugin", "update", f"{item['plugin']}@{MARKETPLACE}", *extra)
1592
1782
  steps.append(Step("update", "claude", _("Claude Code 更新 {0} → {1}").format(item['plugin'], item['latest']),
1593
- command, blocked=blocked, verify=[item["plugin"]],
1594
- targets={item["plugin"]: item["latest"]}, scope=item.get("scope")))
1783
+ command, verify=[item["plugin"]], **{"blocked": blocked, **block},
1784
+ targets={item["plugin"]: item["latest"]}, scope=item.get("scope"), pinned=pinned))
1595
1785
  codex = [item for item in behind if item["client"] == "codex"]
1596
1786
  if codex:
1597
1787
  command, blocked = _cli(env, "codex", "plugin", "marketplace", "upgrade", MARKETPLACE)
@@ -1605,8 +1795,11 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
1605
1795
  if only in (None, "plugins"):
1606
1796
  steps += untouched_steps(env, set(latest.get("plugins", {})), list((report.get("install_state") or {}).get("clients", {})))
1607
1797
  if only in (None, "content") and project is not None:
1798
+ # 用户点名了文件(--merge / --diff / --keep …)时,即使内容锁的版本已是最新(例如先 --keep 过,锁已升到新版)
1799
+ # 也要把这些文件交给 refresh 处理;否则 --keep 之后再 --merge 只会得到“没有需要更新的内容”。
1800
+ named = bool(accept or keep or content_flags)
1608
1801
  for item in report["content"]:
1609
- if item.get("status") not in {"update-available", "conflict"}:
1802
+ if item.get("status") not in {"update-available", "conflict"} and not (named and item.get("status") in {"current", "unknown"}):
1610
1803
  continue
1611
1804
  steps.append(content_step(env, item, report, project, accept, keep, recovery_dir, content_flags=content_flags))
1612
1805
  return steps
@@ -1617,7 +1810,8 @@ def content_step(env: Env, item: dict, report: dict, project: Path, accept: list
1617
1810
  if item["plugin"] != "agents-init":
1618
1811
  return Step("content", None, _("{0}:没有可用的刷新工具").format(item['pack']), blocked="unsupported")
1619
1812
  stale = any(entry["plugin"] == "agents-init" and entry["status"] == "behind" for entry in report["plugins"])
1620
- description = _("重新渲染 {0} {1} → {2}").format(item['pack'], item['version'], item['latest'])
1813
+ description = _("重新渲染 {0} {1} → {2}").format(item['pack'], item['version'], item['latest']) \
1814
+ if item.get("status") in {"update-available", "conflict"} else _("按当前模板处理指定的文件:{0} {1}").format(item['pack'], item['version'])
1621
1815
 
1622
1816
  def run(apply: bool, _recovery_root: Path | None) -> dict:
1623
1817
  installed = installed_plugins(env, {"agents-init"})
@@ -1701,6 +1895,9 @@ def verify_step(step: Step, record: dict, before: dict, after: dict) -> None:
1701
1895
  record["reason"] = _("命令成功,但读不到该客户端里这个插件的版本,无法确认是否生效")
1702
1896
  elif all(entry["target"] and entry["after"] == entry["target"] for entry in unchanged):
1703
1897
  record["reason"] = _("已经是目标版本")
1898
+ elif step.pinned:
1899
+ record["reason"] = _("Claude 的 settings 把 agenthelm 市场固定在 {0},更新只会跟随这个 ref,所以版本没变;"
1900
+ "把声明里的 ref 改成目标 tag,或去掉 ref 跟随 main。").format(step.pinned)
1704
1901
  else:
1705
1902
  record["reason"] = _(UNCHANGED_REASONS.get(step.client or "", N_("版本没有变化,原因未知")))
1706
1903
 
@@ -1773,9 +1970,11 @@ def execute_steps(steps: list[Step], *, apply: bool, recovery_root: Path | None,
1773
1970
  CLIENT_ORDER = {name: index for index, name in enumerate(CLIENT_KEYS)}
1774
1971
 
1775
1972
 
1776
- def step_outcome_ok(results: list[dict]) -> bool:
1777
- """False when a step failed, ran without effect, or still waits for a choice."""
1778
- return not any(r["status"] in {"failed", "unchanged"} or r.get("needs_choice") for r in results)
1973
+ def step_outcome_ok(results: list[dict], *, blockers: bool = False) -> bool:
1974
+ """False when a step failed, ran without effect, or still waits for a choice (``blockers``: or is held back by
1975
+ a cause the user has to resolve, e.g. Claude Code has not registered the declared market yet)."""
1976
+ return not any(r["status"] in {"failed", "unchanged"} or r.get("needs_choice")
1977
+ or (blockers and r["status"] == "blocked" and r.get("blocker")) for r in results)
1779
1978
 
1780
1979
 
1781
1980
  def outcome_summary(results: list[dict]) -> dict:
@@ -1797,7 +1996,10 @@ def outcome_summary(results: list[dict]) -> dict:
1797
1996
  entry["status"] = status
1798
1997
  if status in {"unavailable"} and record.get("error"):
1799
1998
  entry["reason"] = record["error"]
1800
- return {"ok": step_outcome_ok(results), "clients": clients}
1999
+ if status == "blocked" and record.get("blocker"):
2000
+ entry["blocker"] = record["blocker"]
2001
+ entry["reason"] = record["blocked"]
2002
+ return {"ok": step_outcome_ok(results, blockers=True), "clients": clients}
1801
2003
 
1802
2004
 
1803
2005
  def render_outcome(results: list[dict]) -> list[str]:
@@ -1815,7 +2017,7 @@ def render_outcome(results: list[dict]) -> list[str]:
1815
2017
  if entry["not_run"]:
1816
2018
  text += _(";其后 {0} 步没有执行").format(entry["not_run"])
1817
2019
  lines.append(text)
1818
- bad = [names.get(n, n) for n, e in ordered if e["status"] in {"failed", "unchanged"}]
2020
+ bad = [names.get(n, n) for n, e in ordered if e["status"] in {"failed", "unchanged"} or e.get("blocker")]
1819
2021
  good = [names.get(n, n) for n, e in ordered if e["status"] == "ok"]
1820
2022
  if bad:
1821
2023
  lines.append(_("整体:没有全部成功——{0} 需要处理;{1}").format(
@@ -2050,6 +2252,7 @@ def parser() -> argparse.ArgumentParser:
2050
2252
  check.add_argument("--offline", action="store_true", help=_("只用缓存,不联网"))
2051
2253
  refresh(check)
2052
2254
  client_filter(check)
2255
+ check.add_argument("--source", type=Path, help=_("Cursor 更新用的本地仓库:给出后 Cursor 按可更新计(与 update --source 一致)"))
2053
2256
  check.add_argument("--hook", action="store_true", help=_("会话开始时静默调用:有更新才输出一行"))
2054
2257
  check.add_argument("--hook-format", choices=("text", "claude-hook"), default="text")
2055
2258
  check.add_argument("--strict", action="store_true", help=_("有可更新项或必须处理的脚手架差异时退出码为 1(CI 用;可选与信息性的差异不算)"))
@@ -2124,6 +2327,25 @@ def parser() -> argparse.ArgumentParser:
2124
2327
  return result
2125
2328
 
2126
2329
 
2330
+ # 内容刷新的状态词与处置词(JSON 字段值保持英文标识;agents-init、project-orchestrator 各带同样的词表)。
2331
+ CONTENT_STATE_LABELS = {"unchanged": N_("与新模板相同"), "clean": N_("没改过"), "modified": N_("你改过"), "missing": N_("目前不存在"),
2332
+ "local-only": N_("只有你的改动"), "kept-by-decision": N_("已决定保留"), "symlink": N_("符号链接")}
2333
+ CONTENT_ACTION_LABELS = {"keep": N_("保持原样"), "replace": N_("替换"), "create": N_("新建"), "skip": N_("不新建"), "blocked": N_("阻塞"),
2334
+ "merge": N_("三方合并"), "append": N_("追加区块")}
2335
+
2336
+
2337
+ def content_state_label(state: str) -> str:
2338
+ return _(CONTENT_STATE_LABELS[state]) if state in CONTENT_STATE_LABELS else state
2339
+
2340
+
2341
+ def content_action_label(action: str) -> str:
2342
+ return _(CONTENT_ACTION_LABELS[action]) if action in CONTENT_ACTION_LABELS else action
2343
+
2344
+
2345
+ def _pad(text: str, width: int = 10) -> str:
2346
+ return text + " " * max(width - sum(2 if ord(char) > 0x2E7F else 1 for char in text), 0)
2347
+
2348
+
2127
2349
  def _print_steps(results: list[dict], apply: bool) -> None:
2128
2350
  labels = {"preview": _("预览"), "applied": _("完成"), "blocked": _("阻塞"), "failed": _("失败"),
2129
2351
  "unchanged": _("完成,无变化"), "skipped": _("跳过"), "unavailable": _("不可用"), "not_run": _("未执行")}
@@ -2135,6 +2357,8 @@ def _print_steps(results: list[dict], apply: bool) -> None:
2135
2357
  line += f"\n {record['note']}"
2136
2358
  if record.get("blocked"):
2137
2359
  line += f"\n {record['blocked']}"
2360
+ if record.get("blocker") and record.get("next"):
2361
+ line += _("\n 下一步:{0}").format(record["next"])
2138
2362
  if record.get("skipped"):
2139
2363
  line += f"\n {record['skipped']}"
2140
2364
  if record["status"] in {"failed", "unavailable"}:
@@ -2162,15 +2386,18 @@ def _print_steps(results: list[dict], apply: bool) -> None:
2162
2386
  line += _("\n {0}仍是 {1}(目标 {2})").format(prefix, change["after"] or _("(读不到)"), change.get("target") or "?")
2163
2387
  if record["status"] == "unchanged":
2164
2388
  line += _("\n 原因:{0}").format(record["reason"])
2389
+ if record.get("next"):
2390
+ line += _("\n 下一步:{0}").format(record["next"])
2165
2391
  result = record.get("result")
2166
2392
  if isinstance(result, dict) and result.get("mode") == "refresh":
2167
- for item in result.get("files", []):
2168
- line += f"\n {item['action']:8} {item['path']} [{item['state']}]"
2393
+ diffs = result.get("diffs") or {}
2394
+ for item in [] if diffs else result.get("files", []): # --diff 只输出差异,不再重复完整预览
2395
+ line += f"\n {_pad(content_action_label(item['action']))}{item['path']} [{content_state_label(item['state'])}]"
2169
2396
  for note in item.get("note", []):
2170
2397
  line += f"\n {note}"
2171
- for path, diff in (result.get("diffs") or {}).items():
2398
+ for path, diff in diffs.items():
2172
2399
  line += "\n" + (diff.rstrip("\n") if diff else _("({0} 与新模板没有差异)").format(path))
2173
- if result.get("hint"):
2400
+ if result.get("hint") and not diffs:
2174
2401
  line += "\n" + "\n".join(f" {hint}" for hint in result["hint"].splitlines())
2175
2402
  print(line)
2176
2403
  if apply and results:
@@ -2339,7 +2566,7 @@ def main(argv: list[str] | None = None) -> int:
2339
2566
  if args.command == "check":
2340
2567
  report = run_check(env, project, latest_source=args.latest, offline=args.offline,
2341
2568
  max_age=0 if args.refresh else CACHE_TTL_SECONDS, reprompt=args.reprompt,
2342
- clients=args.client)
2569
+ clients=args.client, source=args.source)
2343
2570
  report.pop("_latest")
2344
2571
  if args.fingerprint or args.explain:
2345
2572
  return print_fingerprint(env, report, args, project)
@@ -2381,12 +2608,16 @@ def main(argv: list[str] | None = None) -> int:
2381
2608
  flags = [value for flag, paths in (("--append", args.append), ("--confirm-discard", args.confirm_discard),
2382
2609
  ("--diff", args.diff), ("--merge", args.merge), ("--pick", args.pick))
2383
2610
  for path in paths for value in (flag, path)]
2611
+ report["market_sync"] = claude_market_sync(env, report, project, args.only)
2384
2612
  steps = update_steps(env, report, project, args.source, home, args.accept, args.keep,
2385
2613
  recovery, args.only, content_flags=flags)
2386
2614
  results = execute_steps(steps, apply=args.apply, recovery_root=None,
2387
2615
  child_env=env.child_environment(), env=env)
2388
- payload = {"ok": step_outcome_ok(results), "applied": args.apply, "latest": origin,
2389
- "steps": results, "summary": report["summary"]}
2616
+ for record in results: # Codex "no change": say how to pin its marketplace
2617
+ if record["status"] == "unchanged" and record.get("client") == "codex":
2618
+ record["next"] = codex_pin_advice(latest)
2619
+ payload = {"ok": step_outcome_ok(results, blockers=args.apply), "applied": args.apply, "latest": origin,
2620
+ "steps": results, "summary": report["summary"], "market_sync": report["market_sync"]}
2390
2621
  backups = [record["result"] for record in results
2391
2622
  if isinstance(record.get("result"), dict) and record["result"].get("recovery")]
2392
2623
  if args.apply and backups:
@@ -2399,14 +2630,14 @@ def main(argv: list[str] | None = None) -> int:
2399
2630
  payload["ok"] = False
2400
2631
  payload["message"] = _("项目内容没有检查:{0}。修复或移走这个文件后重试;没有改动任何文件。").format(content_errors[0]["error"])
2401
2632
  elif chosen and args.only != "plugins": # 用户点名了文件,却没有任何待更新内容:不能装作处理过
2402
- payload["message"] = _("没有需要更新的内容,--accept / --keep / --append / --diff / --merge 指定的文件没有被处理(项目内容已是最新,或项目没有内容锁);没有改动任何文件。"
2633
+ payload["message"] = _("项目没有内容锁(或内容锁里没有可刷新的内容包),--accept / --keep / --append / --diff / --merge 指定的文件没有被处理;没有改动任何文件。"
2403
2634
  "没有内容锁的项目用 {0} fix update-content。").format(CLI)
2404
2635
  else:
2405
2636
  payload["message"] = _("没有需要更新的内容。")
2406
- differing = baseline_less_differences(env, project) if args.only != "plugins" else 0
2637
+ differing = baseline_less_differences(env, project) if args.only != "plugins" else []
2407
2638
  if differing: # check lists them (no baseline in the lock); update has nothing to render for them
2408
2639
  payload["message"] += _("有 {0} 项无基线差异(内容与模板不同,内容锁里没有基线),"
2409
- "请用 {1} fix update-content(或 update --only content --keep/--append/--accept …)逐个处理。").format(differing, CLI)
2640
+ "请用 {1} fix update-content(或 update --only content --keep {2})逐个处理。").format(len(differing), CLI, differing[0])
2410
2641
  else: # migrate
2411
2642
  names = set(latest.get("plugins", {}))
2412
2643
  artifacts = legacy_artifacts(env, names)