@sakanano-moe/agenthelm 6.11.0 → 6.12.0-rc.1

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.
Files changed (31) hide show
  1. package/package.json +1 -1
  2. package/runtime/index.json +6 -6
  3. package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
  4. package/runtime/plugins/agent-pack/plugin.json +1 -1
  5. package/runtime/plugins/agent-pack/references/capability-config.md +11 -1
  6. package/runtime/plugins/agent-pack/runtime/agent_pack_codex_mcp.py +161 -0
  7. package/runtime/plugins/agent-pack/runtime/agent_pack_config.py +232 -53
  8. package/runtime/plugins/agent-pack/runtime/agenthelm.py +171 -23
  9. package/runtime/plugins/agent-pack/runtime/agenthelm_runtime.py +1 -1
  10. package/runtime/plugins/agent-pack/runtime/locale/en.json +13 -1
  11. package/runtime/plugins/agent-pack/runtime/mcp_server.py +5 -1
  12. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  13. package/runtime/plugins/agents-init/content.json +2 -2
  14. package/runtime/plugins/agents-init/plugin.json +1 -1
  15. package/runtime/plugins/agents-init/skills/agents-init/AGENT.template.md +169 -0
  16. package/runtime/plugins/agents-init/skills/agents-init/scripts/adopt.py +9 -1
  17. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +74 -20
  18. package/runtime/plugins/agents-init/skills/agents-init/scripts/locale/en.json +7 -2
  19. package/runtime/plugins/agents-init/skills/agents-init/scripts/scaffold.py +5 -2
  20. package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
  21. package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
  22. package/runtime/plugins/opinion-manager/plugin.json +1 -1
  23. package/runtime/plugins/opinion-manager/runtime/constants.py +3 -0
  24. package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
  25. package/runtime/plugins/project-orchestrator/plugin.json +1 -1
  26. package/runtime/plugins/project-orchestrator/references/case-workspaces.md +4 -0
  27. package/runtime/plugins/project-orchestrator/runtime/case.py +20 -2
  28. package/runtime/plugins/project-orchestrator/runtime/locale/en.json +5 -1
  29. package/runtime/plugins/project-orchestrator/runtime/memory.py +25 -8
  30. package/runtime/plugins/project-orchestrator/runtime/project_cli.py +4 -2
  31. package/runtime/plugins/project-orchestrator/runtime/project_maintain.py +6 -1
@@ -28,7 +28,7 @@ from dataclasses import dataclass, field
28
28
  from datetime import UTC, datetime
29
29
  from pathlib import Path
30
30
  from typing import Any
31
- from i18n_agent_pack import _, N_ # noqa: E402
31
+ from i18n_agent_pack import _, N_, resolve_language # noqa: E402
32
32
 
33
33
  MARKETPLACE = "agenthelm"
34
34
  NPX = "npx @sakanano-moe/agenthelm"
@@ -664,6 +664,8 @@ def _advice(diag: dict, client: str) -> dict:
664
664
  if conflict["reason"] == "pinned":
665
665
  summary = _("{0} 的 settings 把 agenthelm 市场固定在 {1}({2}):不带它的 marketplace add 会被拒绝,update 也只会跟随这个 ref。").format(
666
666
  name, conflict["ref"], conflict["file"])
667
+ if not (diag.get("market_pin") or {}).get("target"):
668
+ summary += _("目标版本未知:latest.json 没有 release.tag,无法判断这个 ref 是否已经是目标版本。")
667
669
  else:
668
670
  summary = _("{0} 的 settings 声明 agenthelm 市场指向 {1}({2}),与 agenthelm 默认来源不同:用默认来源 marketplace add 会被拒绝。").format(
669
671
  name, conflict["declared"], conflict["file"])
@@ -738,10 +740,10 @@ def content_findings(project: Path, latest: dict) -> list[dict]:
738
740
  return findings
739
741
 
740
742
 
741
- def locate_companion(name: str, installed: list[dict]) -> Path | None:
743
+ def locate_companion(name: str, installed: list[dict], *, excluded: set[Path] | None = None) -> Path | None:
742
744
  """The newest copy of a companion plugin: next to this one or in any client install."""
743
745
  candidates = [PLUGIN_ROOT.parent / name, *(Path(item["path"]) for item in installed if item["plugin"] == name)]
744
- candidates = [path for path in candidates if (path / "plugin.json").is_file()]
746
+ candidates = [path for path in candidates if path not in (excluded or set()) and (path / "plugin.json").is_file()]
745
747
  return max(candidates, key=lambda path: version_key(_manifest_version(path) or "") or (0,)) if candidates else None
746
748
 
747
749
 
@@ -991,6 +993,40 @@ def unused_client_hints(env: Env, plugins: list[dict], ignored: list[str]) -> li
991
993
  return hints
992
994
 
993
995
 
996
+ def capability_findings(env: Env, project: Path | None, clients: list[str] | None = None) -> list[dict]:
997
+ """Local, read-only discovery; never requires latest.json or network access."""
998
+ if project is None:
999
+ return []
1000
+ import agent_pack_config as capabilities
1001
+ try:
1002
+ inventory = capabilities.inventory_project(project)
1003
+ if not inventory.skills and not inventory.mcps:
1004
+ return []
1005
+ selected = active_clients(env, clients)
1006
+ disabled = read_json(env.config_file).get("capability_check_ignored_clients", []) if env.config_file.is_file() else []
1007
+ reports = []
1008
+ for client in selected:
1009
+ if client in disabled:
1010
+ continue
1011
+ try:
1012
+ report = capabilities.client_drift(project, client, env.home)
1013
+ except capabilities.AgentPackError:
1014
+ # Invalid portable config is explained by doctor, with no values in the notice.
1015
+ report = {"client": client, "in_sync": False}
1016
+ if not report["in_sync"]:
1017
+ reports.append(report)
1018
+ return reports
1019
+ except (OSError, ValueError, capabilities.AgentPackError):
1020
+ return []
1021
+
1022
+
1023
+ def capability_notice(reports: list[dict]) -> str | None:
1024
+ if not reports:
1025
+ return None
1026
+ clients = _("、").join(CLIENT_NAMES[item["client"]] for item in reports)
1027
+ return _("项目声明的 MCP / Skill 与本机 {0} 不一致;运行 agent-pack doctor --client <客户端> 查看详情。").format(clients)
1028
+
1029
+
994
1030
  def run_check(env: Env, project: Path | None, *, latest_source: str | None = None, offline: bool = False,
995
1031
  max_age: int = CACHE_TTL_SECONDS, hook_mode: bool = False, reprompt: bool = False,
996
1032
  clients: list[str] | None = None, source: Path | None = None) -> dict:
@@ -1023,7 +1059,15 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
1023
1059
  for item in plugins:
1024
1060
  item["unavailable"] = None
1025
1061
  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)
1062
+ # Keep the resolved release for the update preview/apply as well: otherwise
1063
+ # GitHub's latest release may move between the check and the download.
1064
+ if source is None and not latest.get("release"):
1065
+ release = github_release(latest, timeout=HOOK_FETCH_TIMEOUT_SECONDS if hook_mode else FETCH_TIMEOUT_SECONDS)
1066
+ if release:
1067
+ latest["release"] = release
1068
+ reason = release_problem(release)
1069
+ else:
1070
+ reason = cursor_unavailable(latest, source, timeout=HOOK_FETCH_TIMEOUT_SECONDS if hook_mode else FETCH_TIMEOUT_SECONDS)
1027
1071
  for item in behind:
1028
1072
  if reason and item["client"] == "cursor":
1029
1073
  item["unavailable"] = reason
@@ -1044,6 +1088,7 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
1044
1088
  content_updates = [item for item in content if item["status"] in {"update-available", "conflict"}]
1045
1089
  content_errors = [item for item in content if item["status"] == "error"] # 内容锁无法解析:无法判断,不能当作“已是最新”
1046
1090
  opinion_updates = [item for item in opinion if item["status"] == "update-available"]
1091
+ capabilities = capability_findings(env, project, clients)
1047
1092
  settings = user_settings_module()
1048
1093
  language = settings.report_section(env.variables, settings.read_settings(env.config_file)[0], scaffold)
1049
1094
  return {
@@ -1062,6 +1107,7 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
1062
1107
  "scaffold": scaffold,
1063
1108
  "machine": machine,
1064
1109
  "language": language,
1110
+ "capabilities": capabilities,
1065
1111
  "summary": {
1066
1112
  "scaffold_findings": scaffold_active,
1067
1113
  "scaffold_required": scaffold_required,
@@ -1250,13 +1296,27 @@ def render_scaffold(report: dict, show_skipped: bool, details: bool = False, sho
1250
1296
  return lines
1251
1297
 
1252
1298
 
1253
- def render_machine(report: dict) -> list[str]:
1299
+ def render_machine(report: dict, *, details: bool = False) -> list[str]:
1254
1300
  lines = []
1255
- for item in report.get("machine", {}).get("findings", []):
1301
+ findings = report.get("machine", {}).get("findings", [])
1302
+ head = next((item for item in findings if item["id"] == "local:sync-folder"), None)
1303
+ local = [item for item in findings if item["id"].startswith("local:real:")]
1304
+ if head and local and not details:
1305
+ lines.append(_(" [本机] {0},连同 {1} 个本机专属目录:{2}\n 处理:agenthelm local-only check(逐项信息:check --details)").format(
1306
+ head["title"], len(local), _("、").join(f"{item['id'].split(':', 2)[-1]} (ID {item['id']})" for item in local)))
1307
+ findings = [item for item in findings if item is not head and item not in local]
1308
+ for item in findings:
1256
1309
  lines.append(_(" [本机] {0}:{1}\n 影响:{2}\n 处理:{3}\n ID {4}(只记在这台机器上;fix --skip {5} --reason …)").format(item['title'], item['reason'], item['impact'], item['next'], item['id'], item['id']))
1257
1310
  return lines
1258
1311
 
1259
1312
 
1313
+ def migration_language_note(entries: list[dict]) -> str | None:
1314
+ """Historical release declarations are source data; warn when English notes are unavailable."""
1315
+ if resolve_language() == "en" and any(re.search(r"[\u4e00-\u9fff]", str(item.get("summary", ""))) for item in entries):
1316
+ return _("迁移说明目前仅有中文;界面语言不改变历史发布声明。")
1317
+ return None
1318
+
1319
+
1260
1320
  def render_install_state(state: dict) -> list[str]:
1261
1321
  """The install-state diagnosis at the head of ``check``: a conclusion first, then the next command and its reach."""
1262
1322
  clients = state.get("clients") or {}
@@ -1285,6 +1345,9 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1285
1345
  lines = []
1286
1346
  origin = report["latest"]["source"]
1287
1347
  lines.append(origin_line(origin))
1348
+ note = migration_language_note([step for item in report["plugins"] for step in item.get("steps", []) if step.get("breaking")])
1349
+ if note:
1350
+ lines.append(note)
1288
1351
  clients = report.get("clients") or {}
1289
1352
  if clients.get("selected"):
1290
1353
  lines.append(_("只处理所选客户端:{0}").format(_("、").join(CLIENT_NAMES[name] for name in clients["selected"])))
@@ -1294,6 +1357,9 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1294
1357
  if show_skipped:
1295
1358
  for item in shown:
1296
1359
  lines.append(_(" {0} {1} → {2}(未检查)").format(item["plugin"], item.get("version"), item.get("latest")))
1360
+ notice = capability_notice(report.get("capabilities") or [])
1361
+ if notice:
1362
+ lines.append(notice)
1297
1363
  lines += render_install_state(report.get("install_state") or {})
1298
1364
  if not report["plugins"]:
1299
1365
  lines.append(_("未发现已安装的 agenthelm 插件。"))
@@ -1349,7 +1415,7 @@ def render_text(report: dict, *, show_skipped: bool = False, details: bool = Fal
1349
1415
  elif item["status"] in {"error", "unknown"}:
1350
1416
  lines.append(f" [Opinion] {item.get('error')}")
1351
1417
  lines += render_scaffold(report, show_skipped, details, show_extras)
1352
- lines += render_machine(report)
1418
+ lines += render_machine(report, details=details)
1353
1419
  lines += [_(" [语言] {0}").format(hint) for hint in (report.get("language") or {}).get("hints", [])]
1354
1420
  if not report["plugins"]:
1355
1421
  lines.append(_("运行 `{0} install` 预览安装。").format(CLI))
@@ -1446,16 +1512,19 @@ def clear_hook_errors(env: Env) -> bool:
1446
1512
  return False
1447
1513
 
1448
1514
 
1449
- def hook(env: Env, project: Path | None, output: str) -> int:
1515
+ def hook(env: Env, project: Path | None, output: str, *, latest_source: str | None = None,
1516
+ offline: bool = False, clients: list[str] | None = None) -> int:
1450
1517
  """Session-start entry: silent unless something is behind; never fails the session."""
1451
1518
  if not update_check_enabled(env):
1452
1519
  return 0
1520
+ local_notice = capability_notice(capability_findings(env, project, clients))
1453
1521
  try:
1454
- report = run_check(env, project, hook_mode=True)
1522
+ report = run_check(env, project, hook_mode=True, latest_source=latest_source, offline=offline, clients=clients)
1455
1523
  except Exception as exc: # noqa: BLE001 - an update notice must never break a session
1456
1524
  record_hook_error(env, "update-check", exc)
1457
- return 0
1458
- message = "\n".join(part for part in (one_line(report), (report.get("language") or {}).get("session_hint")) if part) or None
1525
+ report = {}
1526
+ message = "\n".join(part for part in (one_line(report) if report else None, local_notice,
1527
+ (report.get("language") or {}).get("session_hint")) if part) or None
1459
1528
  if message is None or not notice_due(env, message):
1460
1529
  return 0
1461
1530
  if output == "claude-hook":
@@ -1565,6 +1634,21 @@ def release_source(latest: dict, workdir: Path, source: Path | None = None) -> P
1565
1634
  roots = [path for path in extracted.iterdir() if path.is_dir()]
1566
1635
  if len(roots) != 1 or not (roots[0] / "plugins").is_dir():
1567
1636
  raise CheckError(_("发布包结构不符合预期"))
1637
+ # Validate every advertised plugin before the first installation writes to the
1638
+ # client's directory. A valid digest alone does not guarantee the advertised BOM.
1639
+ for name, expected in _plugin_versions(latest).items():
1640
+ plugin = roots[0] / "plugins" / name
1641
+ try:
1642
+ identity = read_json(plugin / "plugin.json").get("name")
1643
+ except (OSError, ValueError, AttributeError):
1644
+ identity = None
1645
+ if identity != name:
1646
+ raise CheckError(_("发布包里的 {0} 身份为 {1},与发布清单不符;没有改动客户端安装").format(
1647
+ name, identity or "?"))
1648
+ actual = _manifest_version(plugin)
1649
+ if actual != expected:
1650
+ raise CheckError(_("发布包里的 {0} 版本为 {1},发布清单要求 {2};没有改动客户端安装").format(
1651
+ name, actual or "?", expected))
1568
1652
  return roots[0]
1569
1653
 
1570
1654
 
@@ -1767,11 +1851,13 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
1767
1851
  if pinned:
1768
1852
  newest = max((entry["latest"] for entry in behind if entry["client"] == "claude" and entry.get("latest")),
1769
1853
  key=lambda text: version_key(text) or (0,), default="?")
1770
- note = _("提示:Claude 的 settings 把 agenthelm 市场固定在 {0},更新只会跟随这个 ref,版本可能不会变(最新版本 {1})。"
1854
+ note = _("提示:Claude 的 settings 把 agenthelm 市场固定在 {0},更新只会跟随这个 ref,版本可能不会变(插件最新版本 {1})。"
1771
1855
  "要让它跟随新版本:把 settings.json 里 agenthelm 市场声明的 ref 改成目标 tag,或去掉 ref 跟随 main(agenthelm 不会替你改 settings.json)。"
1772
1856
  ).format(pinned, newest)
1773
1857
  if release_tag(latest):
1774
1858
  note += _("目标 tag:{0}。").format(release_tag(latest))
1859
+ else:
1860
+ note += _("目标版本未知:latest.json 没有 release.tag,无法判断这个 ref 是否已经是目标版本。")
1775
1861
  sync = report.get("market_sync")
1776
1862
  block = dict(blocked=sync["reason"], blocker="market-not-synced", next=sync["next"]) if sync else {}
1777
1863
  steps.append(Step("update", "claude", _("刷新 Claude Code 的 agenthelm 市场"), command, **{"blocked": blocked, **block},
@@ -1805,17 +1891,38 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
1805
1891
  return steps
1806
1892
 
1807
1893
 
1894
+ def content_companion(env: Env, report: dict) -> tuple[Path | None, list[dict]]:
1895
+ """Use the same client selection for planning and execution, retaining an independent runtime sibling."""
1896
+ installed = installed_plugins(env, {"agents-init"})
1897
+ selection = report.get("clients") or select_clients(env, None)
1898
+ selected = selection.get("selected") or selection.get("explicit")
1899
+ excluded = set(selection.get("ignored") or []) | set(selection.get("excluded") or [])
1900
+ available = []
1901
+ for entry in installed:
1902
+ owner = legacy_owner(env, entry) if entry["client"] == "legacy" else entry["client"]
1903
+ if owner is None or (owner not in excluded and (not selected or owner in selected)):
1904
+ available.append(entry)
1905
+ # A sibling can itself be an ignored client install (e.g. Cursor's plugins/local).
1906
+ # Only independent runtime siblings bypass client selection.
1907
+ excluded_paths = {Path(entry["path"]) for entry in installed} - {Path(entry["path"]) for entry in available}
1908
+ return locate_companion("agents-init", available, excluded=excluded_paths), available
1909
+
1910
+
1808
1911
  def content_step(env: Env, item: dict, report: dict, project: Path, accept: list[str], keep: list[str],
1809
1912
  recovery_dir: Path | None, *, content_flags: list[str] | None = None) -> Step:
1810
1913
  if item["plugin"] != "agents-init":
1811
1914
  return Step("content", None, _("{0}:没有可用的刷新工具").format(item['pack']), blocked="unsupported")
1812
- stale = any(entry["plugin"] == "agents-init" and entry["status"] == "behind" for entry in report["plugins"])
1915
+ # Use the same newest available copy that actually runs refresh. A stale copy in
1916
+ # another client (including an unavailable Cursor install) must not veto it.
1917
+ manager, installed = content_companion(env, report)
1918
+ required = report["_latest"].get("plugins", {}).get("agents-init", {}).get("version")
1919
+ current = _manifest_version(manager) if manager is not None else None
1920
+ stale = bool(manager is not None and required and (not current or is_newer(required, current)))
1813
1921
  description = _("重新渲染 {0} {1} → {2}").format(item['pack'], item['version'], item['latest']) \
1814
1922
  if item.get("status") in {"update-available", "conflict"} else _("按当前模板处理指定的文件:{0} {1}").format(item['pack'], item['version'])
1815
1923
 
1816
1924
  def run(apply: bool, _recovery_root: Path | None) -> dict:
1817
- installed = installed_plugins(env, {"agents-init"})
1818
- manager = locate_companion("agents-init", installed)
1925
+ manager, _installed = content_companion(env, report)
1819
1926
  if manager is None:
1820
1927
  raise CheckError(_("未找到已安装的 agents-init"))
1821
1928
  command = [sys.executable, str(manager / "skills/agents-init/scripts/init_project.py"),
@@ -1840,8 +1947,25 @@ def content_step(env: Env, item: dict, report: dict, project: Path, accept: list
1840
1947
  raise CheckError(str(outcome["error"]))
1841
1948
  return outcome
1842
1949
 
1843
- blocked = _("先更新 agents-init 插件,再用新模板预览") if stale else None
1844
- return Step("content", None, description, action=run, blocked=blocked)
1950
+ blocked, advice, note = None, None, None
1951
+ older = [entry for entry in report["plugins"]
1952
+ if entry["plugin"] == "agents-init" and entry["status"] in {"behind", "unavailable"}]
1953
+ if stale:
1954
+ owner = next((entry["client"] for entry in installed if Path(entry["path"]) == manager), None)
1955
+ client = CLIENT_NAMES.get(owner, _("随运行时提供的副本"))
1956
+ updatable = [entry["client"] for entry in installed if entry["client"] in {"claude", "codex"}]
1957
+ update_client = owner if owner in updatable else next(iter(updatable), None)
1958
+ advice = (f"{CLI} update --only plugins --client {update_client}" if update_client
1959
+ else f"{CLI} runtime update --apply")
1960
+ blocked = _("先更新 agents-init:实际选用 {0} {1}({2}),需要 {3};下一步:{4}").format(
1961
+ client, current or "?", manager, required, advice)
1962
+ elif older:
1963
+ copies = _("、").join(f"{CLIENT_NAMES.get(entry['client'], entry['client'])} {entry.get('version') or '?'}"
1964
+ for entry in older)
1965
+ note = _("其他客户端的 agents-init 较旧:{0};建议分别升级;内容刷新使用 {1}({2}),不受这些副本阻塞。").format(
1966
+ copies, current or "?", manager)
1967
+ return Step("content", None, description, action=run, blocked=blocked, note=note,
1968
+ blocker="outdated-agents-init" if stale else None, next=advice)
1845
1969
 
1846
1970
 
1847
1971
  STDERR_LINES = 20
@@ -1932,6 +2056,9 @@ def execute_steps(steps: list[Step], *, apply: bool, recovery_root: Path | None,
1932
2056
  if apply and isinstance(outcome, dict) and outcome.get("applied") is False and outcome.get("blocked"):
1933
2057
  # Files still wait for a choice: nothing was written, so this is not "done".
1934
2058
  record["status"], record["needs_choice"] = "blocked", True
2059
+ record["reason"] = outcome.get("hint") or "\n".join(
2060
+ note for item in outcome.get("files", []) if item.get("action") == "blocked"
2061
+ for note in item.get("note", []))
1935
2062
  except Unavailable as exc:
1936
2063
  record["status"], record["error"] = "unavailable", str(exc)
1937
2064
  if step.client == "cursor":
@@ -1974,7 +2101,7 @@ def step_outcome_ok(results: list[dict], *, blockers: bool = False) -> bool:
1974
2101
  """False when a step failed, ran without effect, or still waits for a choice (``blockers``: or is held back by
1975
2102
  a cause the user has to resolve, e.g. Claude Code has not registered the declared market yet)."""
1976
2103
  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)
2104
+ or (blockers and r["status"] == "blocked" and (r.get("blocker") or r.get("kind") == "content")) for r in results)
1978
2105
 
1979
2106
 
1980
2107
  def outcome_summary(results: list[dict]) -> dict:
@@ -1996,9 +2123,10 @@ def outcome_summary(results: list[dict]) -> dict:
1996
2123
  entry["status"] = status
1997
2124
  if status in {"unavailable"} and record.get("error"):
1998
2125
  entry["reason"] = record["error"]
1999
- if status == "blocked" and record.get("blocker"):
2000
- entry["blocker"] = record["blocker"]
2001
- entry["reason"] = record["blocked"]
2126
+ if status == "blocked":
2127
+ if record.get("blocker"):
2128
+ entry["blocker"] = record["blocker"]
2129
+ entry["reason"] = record.get("blocked") or record.get("reason") or (record.get("result") or {}).get("hint")
2002
2130
  return {"ok": step_outcome_ok(results, blockers=True), "clients": clients}
2003
2131
 
2004
2132
 
@@ -2017,6 +2145,8 @@ def render_outcome(results: list[dict]) -> list[str]:
2017
2145
  if entry["not_run"]:
2018
2146
  text += _(";其后 {0} 步没有执行").format(entry["not_run"])
2019
2147
  lines.append(text)
2148
+ if name == "claude" and entry["applied"]:
2149
+ lines.append(_(RECOVERY_HINTS["claude"]))
2020
2150
  bad = [names.get(n, n) for n, e in ordered if e["status"] in {"failed", "unchanged"} or e.get("blocker")]
2021
2151
  good = [names.get(n, n) for n, e in ordered if e["status"] == "ok"]
2022
2152
  if bad:
@@ -2554,7 +2684,7 @@ def main(argv: list[str] | None = None) -> int:
2554
2684
  if hasattr(args, "no_project") and not args.no_project:
2555
2685
  project = (args.project or Path.cwd()).resolve()
2556
2686
  if args.command == "check" and args.hook:
2557
- return hook(env, project, args.hook_format)
2687
+ return hook(env, project, args.hook_format, latest_source=args.latest, offline=args.offline, clients=args.client)
2558
2688
  if args.command == "locate":
2559
2689
  found = locate(env, args.plugin, args.version, include_legacy=args.include_legacy)
2560
2690
  if args.output == "json":
@@ -2598,7 +2728,7 @@ def main(argv: list[str] | None = None) -> int:
2598
2728
  payload: dict = {"ok": step_outcome_ok(results), "applied": args.apply, "latest": origin,
2599
2729
  "clients": clients, "steps": results}
2600
2730
  elif args.command == "update":
2601
- report = run_check(env, project, latest_source=args.latest, max_age=0, clients=args.client)
2731
+ report = run_check(env, project, latest_source=args.latest, max_age=0, clients=args.client, source=args.source)
2602
2732
  origin = report["latest"]["source"]
2603
2733
  recovery = args.recovery_dir
2604
2734
  if args.apply and recovery is None and project is not None:
@@ -2661,8 +2791,26 @@ def main(argv: list[str] | None = None) -> int:
2661
2791
  return 2
2662
2792
  if args.output == "json":
2663
2793
  print(json.dumps(payload, ensure_ascii=False, indent=2))
2794
+ elif args.command == "update" and args.diff:
2795
+ content_results = [record for record in payload["steps"] if record.get("kind") == "content"]
2796
+ for record in content_results:
2797
+ result = record.get("result") or {}
2798
+ diffs = result.get("diffs") or {}
2799
+ for path, diff in diffs.items():
2800
+ if diff:
2801
+ print(diff, end="" if diff.endswith("\n") else "\n")
2802
+ else:
2803
+ print(_("({0} 与新模板没有差异)").format(path))
2804
+ if not diffs:
2805
+ print(record.get("error") or record.get("blocked") or _("没有可显示的文件差异"))
2806
+ if not content_results:
2807
+ print(payload.get("message") or _("没有可显示的文件差异"))
2664
2808
  else:
2665
2809
  print(origin_line(payload["latest"]))
2810
+ if args.command == "migrate":
2811
+ note = migration_language_note(latest.get("migrations", []))
2812
+ if note:
2813
+ print(note)
2666
2814
  if payload.get("message"):
2667
2815
  print(payload["message"])
2668
2816
  _print_steps(payload["steps"], args.apply)
@@ -462,7 +462,7 @@ def main(argv: list[str], host: Any) -> int:
462
462
  if latest_origin is not None:
463
463
  lines.append(host.origin_line(latest_origin))
464
464
  for version in data["inactive_newer"]:
465
- lines.append(_("已安装但未启用:{0}(current 仍是 {1});启用:agenthelm runtime use {0} --apply").format(
465
+ lines.append(_("其他已安装目录:{0}(目录版本号高于 current {1},不代表内容更新);切换:agenthelm runtime use {0} --apply").format(
466
466
  version, active["version"]))
467
467
  if data["update_available"]:
468
468
  lines.append(_("有新版本 {0}:agenthelm runtime update 预览").format(data['latest_release']))
@@ -605,5 +605,17 @@
605
605
  "按当前模板处理指定的文件:{0} {1}": "Handle the named files against the current template: {0} {1}",
606
606
  "项目没有内容锁(或内容锁里没有可刷新的内容包),--accept / --keep / --append / --diff / --merge 指定的文件没有被处理;没有改动任何文件。没有内容锁的项目用 {0} fix update-content。": "The project has no content lock (or the lock has no refreshable content pack), so the files named by --accept / --keep / --append / --diff / --merge were not handled; no file was changed. For a project without a content lock use {0} fix update-content.",
607
607
  "有 {0} 项无基线差异(内容与模板不同,内容锁里没有基线),请用 {1} fix update-content(或 update --only content --keep {2})逐个处理。": "Differences with no baseline: {0} (the content differs from the template and the content lock has no baseline). Handle them one by one with {1} fix update-content (or update --only content --keep {2}).",
608
- "保持原样": "keep"
608
+ "保持原样": "keep",
609
+ "项目声明的 MCP / Skill 与本机 {0} 不一致;运行 agent-pack doctor --client <客户端> 查看详情。": "Project MCP / Skill declarations differ from this machine’s {0}; run agent-pack doctor --client <client> for details.",
610
+ "随运行时提供的副本": "the copy bundled with the runtime",
611
+ "先更新 agents-init:实际选用 {0} {1}({2}),需要 {3};下一步:{4}": "Update agents-init first: refresh selected {0} {1} ({2}), but requires {3}; next: {4}",
612
+ "其他客户端的 agents-init 较旧:{0};建议分别升级;内容刷新使用 {1}({2}),不受这些副本阻塞。": "Older agents-init copies in other clients: {0}; update them separately. Content refresh uses {1} ({2}) and is not blocked by these copies.",
613
+ "没有可显示的文件差异": "No file diff is available",
614
+ "发布包里的 {0} 版本为 {1},发布清单要求 {2};没有改动客户端安装": "Release archive has {0} version {1}, but the release manifest requires {2}; client installations were not changed",
615
+ "发布包里的 {0} 身份为 {1},与发布清单不符;没有改动客户端安装": "Release archive plugin {0} identifies as {1}, which differs from the release manifest; no client installation was changed",
616
+ "提示:Claude 的 settings 把 agenthelm 市场固定在 {0},更新只会跟随这个 ref,版本可能不会变(插件最新版本 {1})。要让它跟随新版本:把 settings.json 里 agenthelm 市场声明的 ref 改成目标 tag,或去掉 ref 跟随 main(agenthelm 不会替你改 settings.json)。": "Note: Claude's settings pin the agenthelm marketplace to {0}, so an update only follows that ref and the version may not change (plugin latest version: {1}). To follow the new version, change the ref of the agenthelm marketplace declaration in settings.json to the target tag, or remove the ref to follow main (agenthelm does not edit settings.json for you).",
617
+ "目标版本未知:latest.json 没有 release.tag,无法判断这个 ref 是否已经是目标版本。": "Target version unknown: latest.json has no release.tag, so this ref cannot be confirmed as the target version.",
618
+ " [本机] {0},连同 {1} 个本机专属目录:{2}\n 处理:agenthelm local-only check(逐项信息:check --details)": " [Machine] {0}, machine-local directories: {1}: {2}\n Next: agenthelm local-only check (individual findings: check --details)",
619
+ "迁移说明目前仅有中文;界面语言不改变历史发布声明。": "Migration notes are currently available only in Chinese; the interface language does not change historical release declarations.",
620
+ "其他已安装目录:{0}(目录版本号高于 current {1},不代表内容更新);切换:agenthelm runtime use {0} --apply": "Other installed directory: {0} (its version label is higher than current {1}; its contents may be older); switch: agenthelm runtime use {0} --apply"
609
621
  }
@@ -144,6 +144,8 @@ TOOLS = [
144
144
  "mcps": {"type": "array", "items": {"type": "string"}, "default": []},
145
145
  "home": {"type": "string"},
146
146
  "apply": {"type": "boolean", "default": False},
147
+ "update": {"type": "boolean", "default": False},
148
+ "recoveryRoot": {"type": "string"},
147
149
  },
148
150
  "required": ["source", "toProject"],
149
151
  "additionalProperties": False,
@@ -236,7 +238,9 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
236
238
  Path(arguments["toProject"]),
237
239
  arguments.get("skills", []),
238
240
  arguments.get("mcps", []),
239
- apply=bool(arguments.get("apply", False)),
241
+ apply=bool(arguments.get("apply", False)), update=bool(arguments.get("update", False)),
242
+ recovery_root=Path(arguments["recoveryRoot"]) if arguments.get("recoveryRoot") else (
243
+ home / ".agent-pack" / "recovery" if home else None),
240
244
  )
241
245
  if name == "agent_pack_sync":
242
246
  recovery_value = arguments.get("recoveryRoot")
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-init",
3
- "version": "6.8.2",
3
+ "version": "6.9.0",
4
4
  "description": "Initialize or migrate an Agent project contract; ships with project-orchestrator, agent-pack and opinion-manager.",
5
5
  "author": {
6
6
  "name": "lc4t"
@@ -3,7 +3,7 @@
3
3
  "packs": [
4
4
  {
5
5
  "id": "agents-init/project-contract",
6
- "version": "1.3.0",
6
+ "version": "1.4.0",
7
7
  "kind": "template",
8
8
  "title": "项目契约模板",
9
9
  "description": "初始化时渲染为项目入口文件的中文模板与根目录启动器;更新后由用户逐文件选择是否重新渲染。",
@@ -20,7 +20,7 @@
20
20
  ],
21
21
  "project_lock": "agenthelm",
22
22
  "files": {
23
- "skills/agents-init/AGENT.template.md": "c0e807c2f5b979a1b08370ad01c4c5e6e974e65ae54f714ea34b3817fa45f831",
23
+ "skills/agents-init/AGENT.template.md": "4fe1115569c12ab007cd7d388f49c2a4c579864d5c0bf04a3180ea4b0796220d",
24
24
  "skills/agents-init/launcher.sh": "cf27d6cca786905a192446ea4eefe5635942914c3358c78d12117af912107cad"
25
25
  },
26
26
  "materializes_from_profile": [
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "agents-init",
4
- "version": "6.8.2",
4
+ "version": "6.9.0",
5
5
  "description": "Initialize or migrate an Agent project contract (AGENTS.md, Project Profile, root launcher); ships with project-orchestrator, agent-pack and opinion-manager.",
6
6
  "author": {
7
7
  "name": "lc4t"
@@ -510,3 +510,172 @@ v5 把生命周期与扩展管理合并在 `project-runtime` 中,Profile 位
510
510
  - Project Profile 声明记忆提供方;`AGENT.RULES.md` 含记忆的写入去向、召回核实与客户端私有记忆边界。
511
511
  - 个人规则、凭据、token、私有路径或私有 Skill 内容均未进入公开模板。
512
512
  - 除非用户逐项批准替换,否则保留现有文件。
513
+
514
+ ## English project file templates
515
+
516
+ These blocks use the Project Profile `language`, independently of the interface language. Their structure and placeholders match the Chinese blocks above.
517
+
518
+ <!-- agents-init:template AGENTS.md.en -->
519
+ ```markdown
520
+ # PROJECT_NAME — Agent entry point
521
+
522
+ ## Project Profile
523
+
524
+ - Type: PROJECT_TYPE
525
+ - VCS: VCS
526
+ - Stack: STACK
527
+ - Runtime: RUNTIME
528
+ - Agent clients: AGENT_CLI
529
+
530
+ Machine-readable source of truth: `.agents/moe.sakanano.agent-pack/project.json`.
531
+
532
+ ## Session entry
533
+
534
+ 1. Load `project-orchestrator` as the single project lifecycle Skill.
535
+ 2. Have it read the Project Profile, current Git state, and the entry files required for the current task.
536
+ 3. Use domain Skills for deliverables and deterministic Tools for state changes.
537
+ 4. Delegate Plugin, Skill and MCP inventory, synchronization and migration to `agent-pack`.
538
+ 5. When `OPINION.md` contains user-confirmed rules, obtain guidance from `opinion-manager` before implementation and run its check before delivery. If the Profile declares layered loading, read core rules and the bundle index first, then the matching bundles; read the full `OPINION.md` when the tool returns `fallback`.
539
+ 6. Read the memory index declared in the Project Profile's `memory` section. Verify a memory before acting on it, as specified in `AGENT.RULES.md`.
540
+
541
+ ## Responsibilities
542
+
543
+ - `agents-init` only creates or migrates this scaffold.
544
+ - `project-orchestrator` selects the work container by `work.mode`, organizes Case directories, manages progress, validates orchestration, and handles Git handoffs.
545
+ - `agent-pack` manages Plugin/Skill/MCP capabilities between projects and clients.
546
+ - Opinion guides and reviews deliverables; it does not manage the project lifecycle.
547
+ - Domain Skills must not create unrelated Tasks, edit root progress, modify themselves, or commit autonomously.
548
+ - Preserve unrelated changes. Pushes, releases, merges, deletion and destructive migration require explicit authorization.
549
+
550
+ ## Project menu
551
+
552
+ Run `ENTRY_COMMAND` without an Agent to open the project menu: find files, see progress, read the project guide, check and maintain. Agents needing the same information use its subcommands with `--output json` (for example, `ENTRY_COMMAND find <words> --output json`); do not create a separate search implementation. Write commands preview by default.
553
+
554
+ PRIVACY_SECTION
555
+
556
+ ## Project-specific entry points
557
+
558
+ - Commands: TODO
559
+ - Tests: TODO
560
+ - Build: TODO
561
+ - Architecture/documentation: TODO
562
+ - User rules: if `AGENT.USER.md` exists (user content moved from the original `AGENTS.md` during adoption), follow it alongside this file.
563
+ ```
564
+ <!-- /agents-init:template -->
565
+
566
+ <!-- agents-init:template AGENT.RULES.md.en -->
567
+ ```markdown
568
+ # Project-specific rules
569
+
570
+ This file holds stable constraints unique to this repository. The `project-orchestrator` Skill owns the shared lifecycle; `agent-pack` manages additional capabilities.
571
+
572
+ ## Commands and validation
573
+
574
+ - Initialization: TODO
575
+ - Tests: TODO
576
+ - Build: TODO
577
+
578
+ ## File locations and generated output
579
+
580
+ - Source of truth: TODO
581
+ - Generated output: TODO
582
+
583
+ ## Privacy and external systems
584
+
585
+ - PRIVACY_RULES_LINE
586
+ - External writes requiring authorization: all, unless explicitly configured otherwise
587
+
588
+ ## Memory
589
+
590
+ - Destination: each kind of information has one source of truth; other locations contain pointers. Store stable project facts and external reference locations in memory entries, work in progress in the selected work mode's authoritative record, and behavioral or expression preferences through the `opinion-manager` candidate confirmation flow. `.agent-doc/chat-summary.md` contains only unresolved matters and pointers.
591
+ - Exclude from memory: facts directly available from files or version history, information already in rules or this file, completed-work logs, and details useful only in the current conversation.
592
+ - Recall: memories reflect facts when recorded. Before acting on one, verify that its files, commands and external objects still exist; update or retire stale entries.
593
+ - Client-private memory: built-in client memory holds only that client's runtime facts. Put project facts, preferences and conclusions in the repository so every client reads the same content.
594
+ - Wrap-up: generate the memory index and run checks before finishing a milestone.
595
+ - Parameters (size budgets, review intervals): not configured
596
+ ```
597
+ <!-- /agents-init:template -->
598
+
599
+ <!-- agents-init:template OPINION.md.en -->
600
+ ```markdown
601
+ # Project Opinion overlay
602
+
603
+ Opinion is not configured yet.
604
+
605
+ Use `opinion-manager` to apply a template, select individual rules, or start from scratch; candidates can also be proposed from authorized memories. A complete preview takes effect after user confirmation. Personal content belongs only in this project.
606
+ ```
607
+ <!-- /agents-init:template -->
608
+
609
+ <!-- agents-init:template CLAUDE.md.en -->
610
+ ```markdown
611
+ @AGENTS.md
612
+
613
+ ## Claude Code
614
+
615
+ Put Claude Code-specific instructions here; shared project rules belong in `AGENTS.md` and `AGENT.RULES.md`.
616
+ ```
617
+ <!-- /agents-init:template -->
618
+
619
+ <!-- agents-init:template ROUTE.md.en -->
620
+ ```markdown
621
+ # Agent routing
622
+
623
+ Read `AGENTS.md` and follow its Project Profile. Load `project-orchestrator` for the project lifecycle; delegate Plugin/Skill/MCP capability management to `agent-pack`, and Opinion generation, reading and review to `opinion-manager`.
624
+ ```
625
+ <!-- /agents-init:template -->
626
+
627
+ <!-- agents-init:template region/agents-contract.en -->
628
+ ```markdown
629
+ ## agenthelm project contract
630
+
631
+ agenthelm manages this project's lifecycle. Before substantive work:
632
+
633
+ 1. Load `project-orchestrator` and read `.agents/moe.sakanano.agent-pack/project.json` (Project Profile).
634
+ 2. Read `AGENT.RULES.md` for project-specific constraints; delegate Plugin/Skill/MCP management to `agent-pack`, and Opinion to `opinion-manager`.
635
+ 3. The rest of this file contains user rules that existed before adoption. Follow them alongside this contract.
636
+ ```
637
+ <!-- /agents-init:template -->
638
+
639
+ <!-- agents-init:template .agent-doc/plan.md.en -->
640
+ ```markdown
641
+ # Plan
642
+
643
+ There is no active multi-step plan.
644
+ ```
645
+ <!-- /agents-init:template -->
646
+
647
+ <!-- agents-init:template .agent-doc/progress.md.en -->
648
+ ```markdown
649
+ # Progress
650
+
651
+ There is no active work record. `project-orchestrator` manages project work through the configured project subsystem.
652
+ ```
653
+ <!-- /agents-init:template -->
654
+
655
+ <!-- agents-init:template .agent-doc/chat-summary.md.en -->
656
+ ```markdown
657
+ # Session summary
658
+
659
+ This file contains only unresolved matters and pointers to authoritative locations. Once resolved, record the conclusion in its proper location and remove it here.
660
+
661
+ ## Assumptions to confirm
662
+
663
+ None.
664
+
665
+ ## Unresolved conflicts
666
+
667
+ None.
668
+
669
+ ## Opinion evolution candidates
670
+
671
+ None. Submit candidate rules through `opinion-manager` for user confirmation; never promote them automatically here.
672
+ ```
673
+ <!-- /agents-init:template -->
674
+
675
+ <!-- agents-init:template docs/refs/README.md.en -->
676
+ ```markdown
677
+ # References
678
+
679
+ Place reusable references here when the project contract requires retaining them.
680
+ ```
681
+ <!-- /agents-init:template -->