@sakanano-moe/agenthelm 6.12.0 → 6.13.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 (27) hide show
  1. package/package.json +1 -1
  2. package/runtime/index.json +5 -5
  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 +32 -1
  6. package/runtime/plugins/agent-pack/references/nudge.en.md +1 -1
  7. package/runtime/plugins/agent-pack/references/nudge.md +1 -1
  8. package/runtime/plugins/agent-pack/runtime/agent_pack_claude.py +172 -20
  9. package/runtime/plugins/agent-pack/runtime/agent_pack_config.py +286 -35
  10. package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +65 -2
  11. package/runtime/plugins/agent-pack/runtime/agenthelm.py +99 -9
  12. package/runtime/plugins/agent-pack/runtime/locale/en.json +15 -1
  13. package/runtime/plugins/agent-pack/runtime/mcp_env_launcher.py +26 -4
  14. package/runtime/plugins/agent-pack/runtime/mcp_server.py +15 -1
  15. package/runtime/plugins/agent-pack/runtime/nudge_text.py +17 -4
  16. package/runtime/plugins/agent-pack/runtime/user_settings.py +25 -6
  17. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  18. package/runtime/plugins/agents-init/plugin.json +1 -1
  19. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +25 -0
  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/references/inbox.en.md +7 -2
  24. package/runtime/plugins/opinion-manager/references/inbox.md +7 -2
  25. package/runtime/plugins/opinion-manager/runtime/inbox.py +155 -7
  26. package/runtime/plugins/opinion-manager/runtime/inbox_text.py +19 -6
  27. package/runtime/plugins/opinion-manager/skills/opinion-manager/SKILL.md +4 -3
@@ -740,6 +740,32 @@ def content_findings(project: Path, latest: dict) -> list[dict]:
740
740
  return findings
741
741
 
742
742
 
743
+ def language_drift(project: Path) -> list[dict]:
744
+ """Packs whose files were last rendered in a different language than the Profile's ``language`` now says.
745
+
746
+ ``config project-language`` changes only the Profile, and the content lock keeps the language each pack was rendered with
747
+ (``render_inputs.language``; ``zh`` when a pre-6.9 lock has ``render_inputs`` without it). Packs with no
748
+ ``render_inputs`` cannot be judged and are skipped, so an old lock or an undeclared language never raises a false alarm.
749
+ """
750
+ try:
751
+ profile = read_json(project / PROFILE_FILE)
752
+ lock = read_json(project / CONTENT_LOCK)
753
+ except (OSError, ValueError, AttributeError):
754
+ return []
755
+ wanted = profile.get("language") if isinstance(profile, dict) else None
756
+ wanted = wanted if wanted in ("zh", "en") else "zh"
757
+ packs = lock.get("packs") if isinstance(lock, dict) else None
758
+ result = []
759
+ for pack_id, entry in sorted((packs or {}).items()):
760
+ inputs = entry.get("render_inputs") if isinstance(entry, dict) else None
761
+ if not isinstance(inputs, dict):
762
+ continue
763
+ rendered = inputs.get("language") if inputs.get("language") in ("zh", "en") else "zh"
764
+ if rendered != wanted:
765
+ result.append({"pack": pack_id, "profile": wanted, "rendered": rendered})
766
+ return result
767
+
768
+
743
769
  def locate_companion(name: str, installed: list[dict], *, excluded: set[Path] | None = None) -> Path | None:
744
770
  """The newest copy of a companion plugin: next to this one or in any client install."""
745
771
  candidates = [PLUGIN_ROOT.parent / name, *(Path(item["path"]) for item in installed if item["plugin"] == name)]
@@ -941,6 +967,16 @@ def baseline_less_differences(env: Env, project: Path | None) -> list[str]:
941
967
  return [item["path"] for item in (report or {}).get("findings", []) if item.get("kind") == "content-differs" and item.get("path")]
942
968
 
943
969
 
970
+ def missing_region_files(env: Env, project: Path | None) -> list[str]:
971
+ """Region-owned files (AGENTS.md / CLAUDE.md of an adopted project) that no longer exist: refresh skips them unless named."""
972
+ try:
973
+ report = scaffold_report(env, project)
974
+ except Exception: # noqa: BLE001 - a hint only; never let it break update
975
+ return []
976
+ paths = {item["path"] for item in (report or {}).get("findings", []) if item.get("kind") == "region-missing" and item.get("path")}
977
+ return sorted(path for path in paths if project is not None and not (project / path).exists() and not (project / path).is_symlink())
978
+
979
+
944
980
  def scaffold_fingerprint(env: Env, scaffold: dict | None) -> dict | None:
945
981
  module = scaffold_module(env)
946
982
  if scaffold is None or module is None or not scaffold.get("available"):
@@ -1090,7 +1126,8 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
1090
1126
  opinion_updates = [item for item in opinion if item["status"] == "update-available"]
1091
1127
  capabilities = capability_findings(env, project, clients)
1092
1128
  settings = user_settings_module()
1093
- language = settings.report_section(env.variables, settings.read_settings(env.config_file)[0], scaffold)
1129
+ language = settings.report_section(env.variables, settings.read_settings(env.config_file)[0], scaffold,
1130
+ drift=language_drift(project) if project else None, cli=CLI)
1094
1131
  return {
1095
1132
  "ok": True,
1096
1133
  "latest": {"source": origin, "released_at": latest.get("released_at")},
@@ -1799,11 +1836,24 @@ def cursor_step(latest: dict, plugins: list[str], source: Path | None, home: Pat
1799
1836
  env: Env | None = None) -> Step:
1800
1837
  def run(apply: bool, recovery_root: Path | None) -> list[dict]:
1801
1838
  config = _agent_pack_config()
1839
+ base = (recovery_root or home / ".agent-pack" / "recovery").expanduser().resolve()
1802
1840
  with tempfile.TemporaryDirectory(prefix="agenthelm-") as temporary:
1803
1841
  root = release_source(latest, Path(temporary), source)
1804
- return [config.install_plugin(root / "plugins" / plugin, "cursor", home=home, apply=apply,
1805
- replace=True, recovery_root=recovery_root)
1806
- for plugin in plugins]
1842
+ results = []
1843
+ for plugin in plugins:
1844
+ before = set(base.glob(f"*-cursor-{plugin}")) if apply and base.is_dir() else set()
1845
+ outcome = config.install_plugin(root / "plugins" / plugin, "cursor", home=home, apply=apply,
1846
+ replace=True, recovery_root=recovery_root)
1847
+ replaced = any(op.get("action") == "replace-plugin" for op in outcome.get("operations", []))
1848
+ if replaced and not apply: # the timestamp is fixed when the replacement runs
1849
+ outcome["backup"] = {"plugin": plugin, "path": str(base / f"<{_('时间戳')}>-cursor-{plugin}" / "replaced-plugin" / plugin),
1850
+ "planned": True}
1851
+ elif replaced:
1852
+ moved = sorted(set(base.glob(f"*-cursor-{plugin}")) - before)
1853
+ if moved:
1854
+ outcome["backup"] = {"plugin": plugin, "path": str(moved[-1] / "replaced-plugin" / plugin), "planned": False}
1855
+ results.append(outcome)
1856
+ return results
1807
1857
  note = None
1808
1858
  if env is not None:
1809
1859
  present = {plugin: version for plugin, version in installed_versions(env, "cursor", plugins).items() if version}
@@ -1945,6 +1995,11 @@ def content_step(env: Env, item: dict, report: dict, project: Path, accept: list
1945
1995
  if completed.returncode not in (0, 1) and isinstance(outcome, dict) and outcome.get("error"):
1946
1996
  # Exit 1 is a normal "blocked, choose per file"; anything else (e.g. no usable backup folder) is a failure.
1947
1997
  raise CheckError(str(outcome["error"]))
1998
+ if isinstance(outcome, dict) and not apply:
1999
+ replacing = [item["path"] for item in outcome.get("files", []) if item.get("action") == "replace"]
2000
+ if replacing: # the timestamp is fixed when the refresh runs; --recovery-dir names the exact folder
2001
+ outcome["backup"] = {"files": replacing, "planned": True, "exact": recovery_dir is not None, "path": str(
2002
+ recovery_dir or env.home / ".agent-pack" / "recovery" / f"<{_('时间戳')}>-agenthelm-content")}
1948
2003
  return outcome
1949
2004
 
1950
2005
  blocked, advice, note = None, None, None
@@ -1962,8 +2017,13 @@ def content_step(env: Env, item: dict, report: dict, project: Path, accept: list
1962
2017
  elif older:
1963
2018
  copies = _("、").join(f"{CLIENT_NAMES.get(entry['client'], entry['client'])} {entry.get('version') or '?'}"
1964
2019
  for entry in older)
1965
- note = _("其他客户端的 agents-init 较旧:{0};建议分别升级;内容刷新使用 {1}({2}),不受这些副本阻塞。").format(
1966
- copies, current or "?", manager)
2020
+ chosen = set((report.get("clients") or {}).get("selected") or [])
2021
+ if chosen and all(entry["client"] in chosen for entry in older): # the user picked these clients: they are not "other"
2022
+ note = _("所选客户端的 agents-init 较旧:{0};建议升级;内容刷新使用 {1}({2}),不受这些副本阻塞。").format(
2023
+ copies, current or "?", manager)
2024
+ else:
2025
+ note = _("其他客户端的 agents-init 较旧:{0};建议分别升级;内容刷新使用 {1}({2}),不受这些副本阻塞。").format(
2026
+ copies, current or "?", manager)
1967
2027
  return Step("content", None, description, action=run, blocked=blocked, note=note,
1968
2028
  blocker="outdated-agents-init" if stale else None, next=advice)
1969
2029
 
@@ -2421,7 +2481,7 @@ def parser() -> argparse.ArgumentParser:
2421
2481
  help=_("内容更新:三方合并这个文件(用旧版本包还原出升级前的基线,保留你的改动并带入新模板的变化;--apply 前先备份)"))
2422
2482
  update.add_argument("--pick", action="append", default=[], metavar=_("文件#块=mine|theirs|both"),
2423
2483
  help=_("内容更新:为 --merge 的冲突块选择 mine(保留你的)、theirs(取新模板)或 both(两边都留)"))
2424
- update.add_argument("--recovery-dir", type=Path, help=_("被替换文件的备份目录(项目外),缺省 ~/.agent-pack/recovery/"))
2484
+ update.add_argument("--recovery-dir", type=Path, help=_("被替换文件的备份目录(项目外;Cursor 插件目录备份在其下的子目录),缺省 ~/.agent-pack/recovery/"))
2425
2485
  update.add_argument("--source", type=Path, help=_("Cursor 更新用的本地仓库(默认下载发布包)"))
2426
2486
  update.add_argument("--apply", action="store_true")
2427
2487
 
@@ -2476,6 +2536,21 @@ def _pad(text: str, width: int = 10) -> str:
2476
2536
  return text + " " * max(width - sum(2 if ord(char) > 0x2E7F else 1 for char in text), 0)
2477
2537
 
2478
2538
 
2539
+ def backup_lines(record: dict, apply: bool) -> list[str]:
2540
+ """Where the files a step replaces are (or will be) backed up; the content step's applied location is printed with the summary."""
2541
+ result = record.get("result")
2542
+ found = [item["backup"] for item in (result if isinstance(result, list) else [result])
2543
+ if isinstance(item, dict) and isinstance(item.get("backup"), dict)]
2544
+ lines = []
2545
+ for item in found:
2546
+ if item.get("planned") and not apply:
2547
+ what = _("被替换的文件({0} 个)").format(len(item["files"])) if "files" in item else _("被替换的 {0} 目录").format(item.get("plugin"))
2548
+ lines.append((_("替换前会把{0}备份到:{1}") if item.get("exact") else _("替换前会把{0}备份到:{1}(时间戳在执行时确定)")).format(what, item["path"]))
2549
+ elif not item.get("planned") and apply and "files" not in item:
2550
+ lines.append(_("已把被替换的 {0} 目录备份到:{1}").format(item.get("plugin"), item["path"]))
2551
+ return lines
2552
+
2553
+
2479
2554
  def _print_steps(results: list[dict], apply: bool) -> None:
2480
2555
  labels = {"preview": _("预览"), "applied": _("完成"), "blocked": _("阻塞"), "failed": _("失败"),
2481
2556
  "unchanged": _("完成,无变化"), "skipped": _("跳过"), "unavailable": _("不可用"), "not_run": _("未执行")}
@@ -2529,11 +2604,19 @@ def _print_steps(results: list[dict], apply: bool) -> None:
2529
2604
  line += "\n" + (diff.rstrip("\n") if diff else _("({0} 与新模板没有差异)").format(path))
2530
2605
  if result.get("hint") and not diffs:
2531
2606
  line += "\n" + "\n".join(f" {hint}" for hint in result["hint"].splitlines())
2607
+ line += "".join(f"\n {text}" for text in backup_lines(record, apply))
2532
2608
  print(line)
2533
2609
  if apply and results:
2534
2610
  print("\n".join(render_outcome(results)))
2535
2611
  if not apply and results:
2536
- print(_("以上为预览;确认后追加 --apply 执行。"))
2612
+ stuck = [r for r in results if r["status"] == "blocked" or (isinstance(r.get("result"), dict) and r["result"].get("blocked"))]
2613
+ runnable = [r for r in results if r["status"] == "preview" and r not in stuck]
2614
+ if stuck and not runnable:
2615
+ print(_("预览被阻塞:没有可以执行的步骤(见上面的 [阻塞] 项与下一步)。先处理,再重新预览;这时运行 --apply 也不会执行任何步骤。"))
2616
+ elif stuck:
2617
+ print(_("以上为预览;其中有步骤被阻塞(见上),--apply 只执行未被阻塞的步骤,被阻塞的步骤需先按提示处理。"))
2618
+ else:
2619
+ print(_("以上为预览;确认后追加 --apply 执行。"))
2537
2620
 
2538
2621
 
2539
2622
  def run_project(argv: list[str]) -> int:
@@ -2741,7 +2824,7 @@ def main(argv: list[str] | None = None) -> int:
2741
2824
  report["market_sync"] = claude_market_sync(env, report, project, args.only)
2742
2825
  steps = update_steps(env, report, project, args.source, home, args.accept, args.keep,
2743
2826
  recovery, args.only, content_flags=flags)
2744
- results = execute_steps(steps, apply=args.apply, recovery_root=None,
2827
+ results = execute_steps(steps, apply=args.apply, recovery_root=args.recovery_dir,
2745
2828
  child_env=env.child_environment(), env=env)
2746
2829
  for record in results: # Codex "no change": say how to pin its marketplace
2747
2830
  if record["status"] == "unchanged" and record.get("client") == "codex":
@@ -2762,8 +2845,15 @@ def main(argv: list[str] | None = None) -> int:
2762
2845
  elif chosen and args.only != "plugins": # 用户点名了文件,却没有任何待更新内容:不能装作处理过
2763
2846
  payload["message"] = _("项目没有内容锁(或内容锁里没有可刷新的内容包),--accept / --keep / --append / --diff / --merge 指定的文件没有被处理;没有改动任何文件。"
2764
2847
  "没有内容锁的项目用 {0} fix update-content。").format(CLI)
2848
+ elif (lost := missing_region_files(env, project) if args.only != "plugins" else []):
2849
+ # 区块归属文件被删除:refresh 默认跳过缺失文件,不能说「没有需要更新的内容」
2850
+ payload["message"] = _("项目里缺少 {0}(接管项目登记了受管区块)。重建带区块标记的文件:{1} update --only content {2} --apply(缺失文件没有本地内容,不需要 --confirm-discard)。").format(
2851
+ _("、").join(lost), CLI, " ".join(f"--accept {path}" for path in lost))
2765
2852
  else:
2766
2853
  payload["message"] = _("没有需要更新的内容。")
2854
+ drift = (report.get("language") or {}).get("drift") if args.only != "plugins" else None
2855
+ if drift: # a language switch changes no version: point at the preview instead of leaving "nothing to do"
2856
+ payload["message"] += " " + user_settings_module().drift_hint(drift, CLI)
2767
2857
  differing = baseline_less_differences(env, project) if args.only != "plugins" else []
2768
2858
  if differing: # check lists them (no baseline in the lock); update has nothing to render for them
2769
2859
  payload["message"] += _("有 {0} 项无基线差异(内容与模板不同,内容锁里没有基线),"
@@ -617,5 +617,19 @@
617
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
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
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"
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",
621
+ "所选客户端的 agents-init 较旧:{0};建议升级;内容刷新使用 {1}({2}),不受这些副本阻塞。": "The agents-init copies in the selected clients are older: {0}; update them. Content refresh uses {1} ({2}) and is not blocked by these copies.",
622
+ "时间戳": "timestamp",
623
+ "被替换的文件({0} 个)": "the files to be replaced ({0})",
624
+ "被替换的 {0} 目录": "the replaced {0} directory",
625
+ "替换前会把{0}备份到:{1}": "Before replacing, {0} will be backed up to: {1}",
626
+ "替换前会把{0}备份到:{1}(时间戳在执行时确定)": "Before replacing, {0} will be backed up to: {1} (the timestamp is fixed when it runs)",
627
+ "已把被替换的 {0} 目录备份到:{1}": "Backed up the replaced {0} directory to: {1}",
628
+ "预览被阻塞:没有可以执行的步骤(见上面的 [阻塞] 项与下一步)。先处理,再重新预览;这时运行 --apply 也不会执行任何步骤。": "Preview blocked: no step can run (see the [blocked] items and their next steps above). Resolve them and preview again; running --apply now would not run any step.",
629
+ "以上为预览;其中有步骤被阻塞(见上),--apply 只执行未被阻塞的步骤,被阻塞的步骤需先按提示处理。": "The above is a preview; some steps are blocked (see above). --apply runs only the steps that are not blocked; resolve the blocked ones first as advised.",
630
+ "被替换文件的备份目录(项目外;Cursor 插件目录备份在其下的子目录),缺省 ~/.agent-pack/recovery/": "Folder for backups of replaced files (outside the project; Cursor plugin directories are backed up in sub-folders of it); default ~/.agent-pack/recovery/",
631
+ "被替换文件的备份目录;缺省 ~/.agent-pack/recovery/<时间>-agenthelm-<标签>(项目 Profile 的备份目录须在项目外)": "Folder for the backup of replaced files; default ~/.agent-pack/recovery/<time>-agenthelm-<label> (for a project Profile the folder must be outside the project)",
632
+ "备份目录里已有 {0}": "The backup folder already holds {0}",
633
+ "项目文件语言(Profile 的 language)是 {0},但内容锁记录的上次渲染语言是 {1}({2}),已有文件仍是{1}。运行 {3} fix update-content 预览整份替换(不加 --apply 不写入;你改过的文件默认保留),或在 agents-init 的 scripts 目录运行 init_project.py --mode refresh --project <项目> 预览。check 与 update --only content 不会自动改写既有文件。": "The project file language (the Profile's language) is {0}, but the content lock records {1} as the language the files were last rendered in ({2}), so the existing files are still {1}. Run {3} fix update-content to preview a full replacement (nothing is written without --apply; files you changed are kept by default), or run init_project.py --mode refresh --project <project> from the agents-init scripts directory to preview. check and update --only content never rewrite existing files on their own.",
634
+ "项目里缺少 {0}(接管项目登记了受管区块)。重建带区块标记的文件:{1} update --only content {2} --apply(缺失文件没有本地内容,不需要 --confirm-discard)。": "{0} is missing (this adopted project registered managed regions). Recreate it with the region markers: {1} update --only content {2} --apply (a missing file has no local content, so --confirm-discard is not needed)."
621
635
  }
@@ -17,6 +17,16 @@ from typing import Any
17
17
 
18
18
 
19
19
  REFERENCE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)\}")
20
+ RESERVED = ("PLUGIN_ROOT", "PLUGIN_DATA")
21
+
22
+
23
+ def plugin_root() -> Path:
24
+ """The installed package root: this launcher lives in ``<plugin_root>/runtime/``.
25
+
26
+ Deliberately not resolved: keep the path the client itself launched, so a symlinked
27
+ install (Claude) still refers to the same files the client sees.
28
+ """
29
+ return Path(__file__).absolute().parent.parent
20
30
 
21
31
 
22
32
  def load_dotenv(path: Path) -> dict[str, str]:
@@ -40,19 +50,24 @@ def load_dotenv(path: Path) -> dict[str, str]:
40
50
  return values
41
51
 
42
52
 
43
- def expand(value: Any, environment: dict[str, str]) -> Any:
53
+ def expand(value: Any, environment: dict[str, str], reserved: dict[str, str] | None = None) -> Any:
54
+ reserved = reserved or {}
44
55
  if isinstance(value, str):
45
56
  def replace(match: re.Match[str]) -> str:
46
57
  name = match.group(1)
58
+ if name in RESERVED and name in reserved:
59
+ return reserved[name]
60
+ if name in RESERVED:
61
+ raise RuntimeError(f"{name} was not provided by the client")
47
62
  if name not in environment:
48
63
  raise RuntimeError(f"credential env file missing key: {name}")
49
64
  return environment[name]
50
65
 
51
66
  return REFERENCE.sub(replace, value)
52
67
  if isinstance(value, list):
53
- return [expand(item, environment) for item in value]
68
+ return [expand(item, environment, reserved) for item in value]
54
69
  if isinstance(value, dict):
55
- return {key: expand(item, environment) for key, item in value.items()}
70
+ return {key: expand(item, environment, reserved) for key, item in value.items()}
56
71
  return value
57
72
 
58
73
 
@@ -60,6 +75,8 @@ def main(argv: list[str] | None = None) -> int:
60
75
  parser = argparse.ArgumentParser()
61
76
  parser.add_argument("--env-file", type=Path, required=True)
62
77
  parser.add_argument("--config", type=Path, required=True)
78
+ # The client expands ${PLUGIN_DATA} in this launcher's own args; the config file it never sees.
79
+ parser.add_argument("--plugin-data", default=None)
63
80
  args = parser.parse_args(argv)
64
81
  try:
65
82
  config = json.loads(args.config.read_text(encoding="utf-8"))
@@ -67,7 +84,12 @@ def main(argv: list[str] | None = None) -> int:
67
84
  raise RuntimeError("launcher config must be a stdio MCP object")
68
85
  environment = dict(os.environ)
69
86
  environment.update(load_dotenv(args.env_file))
70
- config = expand(config, environment)
87
+ reserved = {"PLUGIN_ROOT": str(plugin_root())}
88
+ data = args.plugin_data
89
+ if data and not REFERENCE.search(data):
90
+ reserved["PLUGIN_DATA"] = data
91
+ # Reserved names are never read from the process or dotenv: a credential file must not redirect the package.
92
+ config = expand(config, environment, reserved)
71
93
  command = config.get("command")
72
94
  command_args = config.get("args", [])
73
95
  if not isinstance(command, str) or not command:
@@ -72,6 +72,10 @@ TOOLS = [
72
72
  "project": {"type": "string"},
73
73
  "client": {"type": "string", "enum": ["codex", "cursor", "claude"]},
74
74
  "replace": {"type": "boolean", "default": False},
75
+ "replaceMcp": {"type": "boolean", "default": False},
76
+ "replaceSkills": {"type": "boolean", "default": False},
77
+ "only": {"type": "array", "items": {"type": "string", "enum": ["mcp", "skills", "plugins"]}, "default": [],
78
+ "description": "claude: sync only these types; default is all"},
75
79
  "resetOverrides": {"type": "boolean", "default": False},
76
80
  "home": {"type": "string"},
77
81
  "retireSkills": {"type": "array", "items": {"type": "string"}, "default": []},
@@ -155,7 +159,7 @@ TOOLS = [
155
159
  {
156
160
  "name": "agent_pack_sync",
157
161
  "title": "Sync Project Capabilities to an Agent Client",
158
- "description": "Dry-run or install a project's portable capability package into Codex, Cursor or Claude Code. apply defaults to false; replaced content goes to the recovery directory. Claude Code keeps local credential values unless resetOverrides, and only replaces entries it did not install with replace.",
162
+ "description": "Dry-run or install a project's portable capability package into Codex, Cursor or Claude Code. apply defaults to false; replaced content goes to the recovery directory. Claude Code keeps local credential values unless resetOverrides, and only replaces entries it did not install with replace (replaceMcp / replaceSkills limit that to one type; only limits the sync to mcp, skills or plugins).",
159
163
  "inputSchema": {
160
164
  "type": "object",
161
165
  "properties": {
@@ -165,6 +169,10 @@ TOOLS = [
165
169
  "apply": {"type": "boolean", "default": False},
166
170
  "replace": {"type": "boolean", "default": False},
167
171
  "resetOverrides": {"type": "boolean", "default": False},
172
+ "replaceMcp": {"type": "boolean", "default": False},
173
+ "replaceSkills": {"type": "boolean", "default": False},
174
+ "only": {"type": "array", "items": {"type": "string", "enum": ["mcp", "skills", "plugins"]}, "default": [],
175
+ "description": "claude: sync only these types (plugins = package and install record); default is all"},
168
176
  "recoveryRoot": {"type": "string"},
169
177
  },
170
178
  "required": ["project", "client"],
@@ -223,6 +231,9 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
223
231
  retire_only=bool(arguments.get("retireOnly", False)),
224
232
  replace=bool(arguments.get("replace", False)),
225
233
  reset_overrides=bool(arguments.get("resetOverrides", False)),
234
+ only=arguments.get("only", []),
235
+ replace_mcp=bool(arguments.get("replaceMcp", False)),
236
+ replace_skills=bool(arguments.get("replaceSkills", False)),
226
237
  )
227
238
  if name == "agent_pack_inventory":
228
239
  inventory = inventory_source(arguments["source"], home)
@@ -252,6 +263,9 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
252
263
  replace=bool(arguments.get("replace", False)),
253
264
  reset_overrides=bool(arguments.get("resetOverrides", False)),
254
265
  recovery_root=Path(recovery_value) if isinstance(recovery_value, str) else None,
266
+ only=arguments.get("only", []),
267
+ replace_mcp=bool(arguments.get("replaceMcp", False)),
268
+ replace_skills=bool(arguments.get("replaceSkills", False)),
255
269
  )
256
270
  if name == "agent_pack_cloud_sync_safety_check":
257
271
  import agenthelm # noqa: PLC0415 - shipped next to this file
@@ -61,12 +61,14 @@ MESSAGES: dict[str, dict[str, str]] = {
61
61
  "stop_request": {
62
62
  "zh": "[Opinion] 本次会话暂存了 {count} 条候选观点,尚未向用户确认。请在不重复已完成工作的前提下,"
63
63
  "用下面的编号列表一次性请用户裁决:正式采纳 / 项目内试行 / 暂缓 / 丢弃(也可以逐条说明)。"
64
- "用户明确表态后运行:python3 {manager} inbox decide <编号…> --project {root} --to trial|formal|held|rejected --confirmed --lang {lang}。"
65
- "采纳为正式只改状态,写入 OPINION.md 须走 opinion-manager 的完整预览与确认;未经确认不要写入。\n\n{listing}",
64
+ "用户明确表态后:试行 / 暂缓 / 丢弃运行 python3 {manager} inbox decide <编号…> --project {root} --to trial|held|rejected --confirmed --lang {lang};"
65
+ "用户说“采纳”则不要 decide,直接运行 python3 {manager} inbox adopt <编号…> --project {root} --lang {lang} 预览(零写入),展示结果后经用户确认再加 --apply --confirm <confirmation_sha256> 一次写入并读回。"
66
+ "「已批准」不等于「已生效」:只有 adopt --apply 成功才写入 OPINION.md;未经确认不要写入。\n\n{listing}",
66
67
  "en": "[Opinion] You stashed {count} candidate opinions in this session and have not confirmed them with the user yet. Without repeating finished work, "
67
68
  "ask the user once, using the numbered list below: adopt as formal / trial in this project / hold / discard (they may also answer item by item). "
68
- "After the user states a decision explicitly, run: python3 {manager} inbox decide <ids...> --project {root} --to trial|formal|held|rejected --confirmed --lang {lang}. "
69
- "Adopting as formal only records the decision; writing it into OPINION.md goes through opinion-manager's full preview and confirmation. Do not write anything before the user confirms.\n\n{listing}",
69
+ "After the user states a decision explicitly: for trial / hold / discard run python3 {manager} inbox decide <ids...> --project {root} --to trial|held|rejected --confirmed --lang {lang}; "
70
+ "when the user says \"adopt\", do not decide: run python3 {manager} inbox adopt <ids...> --project {root} --lang {lang} to preview (writes nothing), show the result, and once the user confirms add --apply --confirm <confirmation_sha256> to write and read back in one step. "
71
+ "\"Approved\" is not \"in effect\": OPINION.md is written only when adopt --apply succeeds. Do not write anything before the user confirms.\n\n{listing}",
70
72
  },
71
73
  "note_cursor": {
72
74
  "zh": "Cursor 的 sessionStart 注入是否到达模型取决于 Cursor 版本(社区有未到达的反馈);"
@@ -84,6 +86,17 @@ MESSAGES: dict[str, dict[str, str]] = {
84
86
  "err_hooks_root": {"zh": "{target} 的根节点必须是对象", "en": "The root of {target} must be an object"},
85
87
  "err_backup": {"zh": "无法备份 {target} 到 {backup}({error});没有改动任何文件。",
86
88
  "en": "Could not back up {target} to {backup} ({error}); nothing was changed."},
89
+ "err_unstable_runtime": {
90
+ "zh": "当前运行的 agenthelm 位于临时缓存 {runtime},缓存清理后 hook 会失效,且没有找到已安装的稳定入口(已查找:{searched});"
91
+ "没有写入任何文件。先安装稳定入口:agenthelm install --client cursor --apply,或 agenthelm runtime install --apply,再重新运行 nudge install-hooks。",
92
+ "en": "The running agenthelm is in a temporary cache ({runtime}), so the hooks would break once the cache is cleaned, and no installed stable entry was found (looked in: {searched}); "
93
+ "nothing was written. Install a stable entry first: agenthelm install --client cursor --apply, or agenthelm runtime install --apply, then run nudge install-hooks again.",
94
+ },
95
+ "note_runtime_replaced": {
96
+ "zh": "注意:当前运行的 agenthelm 在临时缓存 {ephemeral},hook 命令改用稳定入口 {stable}。",
97
+ "en": "Note: the running agenthelm is in a temporary cache ({ephemeral}); the hook commands use the stable entry {stable} instead.",
98
+ },
99
+ "install_blocked": {"zh": "预览被阻塞,不会写入", "en": "Preview blocked; nothing would be written"},
87
100
  "status_project": {"zh": "项目:{project}", "en": "Project: {project}"},
88
101
  "status_no_project": {"zh": "(不在启用 opinion-manager 的项目里)", "en": "(not in a project that uses opinion-manager)"},
89
102
  "status_switch": {"zh": "开关:{state}", "en": "Switch: {state}"},
@@ -86,7 +86,18 @@ def short_hint(status: dict) -> str:
86
86
  _(LANGUAGE_NAMES[status["language"]]))
87
87
 
88
88
 
89
- def report_section(variables: Mapping[str, str], settings: Mapping[str, Any], scaffold: dict | None) -> dict:
89
+ def drift_hint(drift: list[dict], cli: str = "agenthelm") -> str:
90
+ """Profile 的 language 与已渲染文件的语言不一致:只指路到预览入口,不改写任何文件。"""
91
+ wanted, rendered = _(LANGUAGE_NAMES[drift[0]["profile"]]), _(LANGUAGE_NAMES[drift[0]["rendered"]])
92
+ return _("项目文件语言(Profile 的 language)是 {0},但内容锁记录的上次渲染语言是 {1}({2}),已有文件仍是{1}。"
93
+ "运行 {3} fix update-content 预览整份替换(不加 --apply 不写入;你改过的文件默认保留),"
94
+ "或在 agents-init 的 scripts 目录运行 init_project.py --mode refresh --project <项目> 预览。"
95
+ "check 与 update --only content 不会自动改写既有文件。").format(
96
+ wanted, rendered, _("、").join(item["pack"] for item in drift), cli)
97
+
98
+
99
+ def report_section(variables: Mapping[str, str], settings: Mapping[str, Any], scaffold: dict | None,
100
+ drift: list[dict] | None = None, cli: str = "agenthelm") -> dict:
90
101
  """check 报告里的 ``language`` 段(无论是否提示都给出,便于脚本读取)。"""
91
102
  status = language_status(variables, settings)
92
103
  declared_known = isinstance(scaffold, dict) and isinstance(scaffold.get("project_language"), dict)
@@ -95,7 +106,9 @@ def report_section(variables: Mapping[str, str], settings: Mapping[str, Any], sc
95
106
  return {"interface": {"language": status["language"], "source": status["source"], "explicit": status["explicit"]},
96
107
  "project": {"declared": declared, "effective": declared or "zh"} if declared_known else None,
97
108
  "hint_dismissed": status["dismissed"],
98
- "hints": ([interface_hint(status)] if status["hint"] else []) + ([project_hint()] if project_needs_hint else []),
109
+ "drift": drift or [],
110
+ "hints": ([interface_hint(status)] if status["hint"] else []) + ([project_hint()] if project_needs_hint else [])
111
+ + ([drift_hint(drift, cli)] if drift else []),
99
112
  "session_hint": short_hint(status) if status["hint"] else None}
100
113
 
101
114
 
@@ -109,6 +122,8 @@ def build_parser() -> argparse.ArgumentParser:
109
122
  def common(parser: argparse.ArgumentParser, project: bool = False) -> None:
110
123
  parser.add_argument("--output", choices=("text", "json"), default="text")
111
124
  parser.add_argument("--apply", action="store_true", help=_("写入(缺省只预览)"))
125
+ parser.add_argument("--recovery-dir", type=Path,
126
+ help=_("被替换文件的备份目录;缺省 ~/.agent-pack/recovery/<时间>-agenthelm-<标签>(项目 Profile 的备份目录须在项目外)"))
112
127
  if project:
113
128
  parser.add_argument("--project", type=Path, help=_("项目目录;缺省当前目录"))
114
129
 
@@ -201,10 +216,13 @@ def _set_key(args: argparse.Namespace, host: Any, env: Any, key: str, value: Any
201
216
  lines.append(" " + _("{0} 已经是这个值,没有需要改的。").format(label))
202
217
  elif args.apply:
203
218
  if path.is_file(): # 替换前备份,和其他会替换文件的命令一样
204
- recovery = host.recovery_dir_for(env, "config")
219
+ recovery = args.recovery_dir.expanduser().resolve() if args.recovery_dir else host.recovery_dir_for(env, "config")
205
220
  try:
206
- recovery.mkdir(parents=True, mode=0o700)
207
- (recovery / path.name).write_bytes(path.read_bytes())
221
+ recovery.mkdir(parents=True, mode=0o700, exist_ok=args.recovery_dir is not None)
222
+ backup = recovery / path.name
223
+ if backup.exists(): # an explicit folder may already hold a copy: never overwrite it
224
+ raise FileExistsError(_("备份目录里已有 {0}").format(backup))
225
+ backup.write_bytes(path.read_bytes())
208
226
  except OSError as exc: # abort before rewriting: no backup, no change
209
227
  message = _("无法备份 {0} 到 {1}({2});没有改动任何文件。").format(path, recovery, exc)
210
228
  _emit(args, {"ok": False, "error": message}, [message])
@@ -230,7 +248,8 @@ def _project_language(args: argparse.Namespace, host: Any, env: Any) -> int:
230
248
  _emit(args, {"ok": False, "error": message}, [message])
231
249
  return 3
232
250
  command = [sys.executable, str(script), "--project", str(project), "--mode", "language", "--language", args.value,
233
- "--output", "json"] + (["--apply"] if args.apply else [])
251
+ "--output", "json"] + (["--apply"] if args.apply else []) \
252
+ + (["--recovery-dir", str(args.recovery_dir.expanduser().resolve())] if args.recovery_dir else [])
234
253
  completed = subprocess.run(command, capture_output=True, text=True, check=False, env=env.child_environment())
235
254
  try:
236
255
  result = json.loads(completed.stdout)
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-init",
3
- "version": "6.9.0",
3
+ "version": "6.9.1",
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"
@@ -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.9.0",
4
+ "version": "6.9.1",
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"
@@ -1230,6 +1230,11 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
1230
1230
  elif current is None:
1231
1231
  state = "missing"
1232
1232
  action = "create" if relative in accept else "skip"
1233
+ if relative.as_posix() in region_paths:
1234
+ # 区块归属的文件:重建的内容是已登记的区块(不是整份模板),与 adopt 在无用户正文时写出的形态一致。
1235
+ rebuilt, region_ids = _rebuild_region_file(relative, entry, templates, inputs.language)
1236
+ new, new_digest = rebuilt, hashlib.sha256(rebuilt.encode("utf-8")).hexdigest()
1237
+ rendered[relative] = new
1233
1238
  elif new_digest == baseline.get(relative.as_posix()):
1234
1239
  # The new template renders this file exactly as before; the user's edits stay untouched.
1235
1240
  state, action = "local-only", "append" if relative in append else "keep"
@@ -1279,6 +1284,8 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
1279
1284
  if decided and relative not in accept:
1280
1285
  state = "kept-by-decision"
1281
1286
  item = {"path": relative.as_posix(), "state": state, "action": action, "new_sha256": new_digest}
1287
+ if state == "missing" and relative.as_posix() in region_paths:
1288
+ item["regions"] = region_ids
1282
1289
  if reason:
1283
1290
  item["reason"] = reason
1284
1291
  if relative in merge:
@@ -1383,6 +1390,9 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
1383
1390
  target = root / relative
1384
1391
  target.parent.mkdir(parents=True, exist_ok=True)
1385
1392
  _atomic_write(target, rendered[relative], 0o755 if relative == Path(inputs.entry_launcher or "\0") else None)
1393
+ for region_id in item.get("regions", []):
1394
+ new_regions.setdefault(item["path"], {})[region_id] = regions.digest(
1395
+ localized(templates, f"region/{region_id}", inputs.language))
1386
1396
  elif item["action"] == "merge":
1387
1397
  target = root / relative
1388
1398
  _atomic_write(target, merged_texts[relative], os.stat(target).st_mode & 0o7777)
@@ -1441,6 +1451,21 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
1441
1451
  return 0, result
1442
1452
 
1443
1453
 
1454
+ def _rebuild_region_file(relative: Path, entry: dict, templates: dict, language: str) -> tuple[str, list[str]]:
1455
+ """被删除的区块归属文件:按锁里登记的区块 ID,用当前模板正文重建带标记的区块(区块外没有用户正文可恢复)。"""
1456
+ regions = _regions()
1457
+ registered = set((entry.get("regions") or {}).get(relative.as_posix()) or {})
1458
+ order = [region_id for region_id in APPEND_REGIONS.get(relative, ()) if region_id in registered]
1459
+ order += sorted(registered - set(order))
1460
+ text, ids = "", []
1461
+ for region_id in order:
1462
+ if f"region/{region_id}" not in templates:
1463
+ continue
1464
+ text, _state = regions.upsert(text, region_id, localized(templates, f"region/{region_id}", language))
1465
+ ids.append(region_id)
1466
+ return text, ids
1467
+
1468
+
1444
1469
  def _adopt():
1445
1470
  here = str(Path(__file__).resolve().parent)
1446
1471
  if here not in sys.path:
@@ -3,7 +3,7 @@
3
3
  "name": "agents-init v6 / Project Profile initialization and migration",
4
4
  "description": "Create or migrate a general project skeleton and Project Profile; the bundled opinion-manager manages user-confirmed Agent behavior rules.",
5
5
  "schema_version": "1.0",
6
- "version": "6.9.0",
6
+ "version": "6.9.1",
7
7
  "status": "stable",
8
8
  "language": "zh-CN",
9
9
  "license": "MIT",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opinion-manager",
3
- "version": "0.5.2",
3
+ "version": "0.6.0",
4
4
  "description": "Choose template variants and exact versions; manage personal Profiles, locked snapshots and upgrade previews.",
5
5
  "author": {
6
6
  "name": "lc4t"
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "opinion-manager",
4
- "version": "0.5.2",
4
+ "version": "0.6.0",
5
5
  "description": "Manage Agent behavior rules through templates, partial selection, blank iteration, and authorized-memory candidates, with complete previews and exact version locks.",
6
6
  "author": {
7
7
  "name": "lc4t"
@@ -2,7 +2,7 @@
2
2
 
3
3
  **English** · [简体中文](inbox.md)
4
4
 
5
- The inbox keeps opinions that the Agent noticed during work and that still await the user's decision. It is not a set of rules: it never writes `OPINION.md`, a Profile or a lock, and it changes nothing the user has already confirmed. Stashing needs no confirmation; every status change needs the user's explicit decision.
5
+ The inbox keeps opinions that the Agent noticed during work and that still await the user's decision. It is not a set of rules: apart from `adopt --apply` it never writes `OPINION.md`, a Profile or a lock, and it changes nothing the user has already confirmed. Stashing needs no confirmation; every status change needs the user's explicit decision.
6
6
 
7
7
  ## Location and privacy
8
8
 
@@ -15,7 +15,7 @@ The inbox keeps opinions that the Agent noticed during work and that still await
15
15
 
16
16
  - `pending`: waits for confirmation and is not in effect yet.
17
17
  - `trial`: the user agreed to try it in this project. The hook injects the full text of trial candidates with the protocol and the Agent works by it; a trial that is not made formal within `nudge.trial_expire_days` (default 30) returns to `pending`.
18
- - `formal`: the user agreed to make it a formal rule. This only records the intent; writing it into `OPINION.md` still goes through the full preview and confirmation.
18
+ - `formal`: the user has approved making it a formal rule. **"Approved" is not "in effect"**: `decide --to formal` only records the status. It does not write `OPINION.md`, and later sessions do not load the rule; the output says `in_opinion: false` and names the next step, `inbox adopt ...`. Only after `adopt --apply` has written and read back is the candidate both `formal` and in effect. The stored status name `formal` is unchanged (renaming it would break existing inbox data).
19
19
  - `held`: put aside, no more reminders.
20
20
  - `rejected`: discarded.
21
21
 
@@ -26,6 +26,11 @@ All commands are `opinion_manager.py inbox <action>`, and `--project` is require
26
26
  - `add --title --text --scope [--quote] [--client] [--session]`: stash a candidate. Title up to 120, text up to 1200 and quote up to 600 characters; at least one `--scope`. Candidates with the same content (ignoring whitespace and case) are merged and the new quote is added as evidence.
27
27
  - `list [--status a,b] [--session ID] [--unpresented]`: list candidates.
28
28
  - `decide <ids...> --to pending|trial|formal|held|rejected --confirmed [--note]`: record a decision. Without `--confirmed` it is always refused; with several ids, either all succeed or none changes.
29
+ - `adopt <ids...> [--apply --confirm SHA256]`: the one-confirmation path from "adopt" to the written rule. Use it when the user has said "adopt" in the conversation; no separate `decide`.
30
+ - Without `--apply`: preview only, nothing is written. The candidate text is appended as personal rules to the custom section of the project's existing Profile (a new `private.my-opinion@1.0.0` if there is none) and goes through the same preview as `profile` and `compose`. It returns the full `content` (what `OPINION.md` will contain), `blocked` (for example hand-written content that must be handled first) and `confirmation_sha256`.
31
+ - With `--apply --confirm <the preview's confirmation_sha256>`: once the user has confirmed, it writes a new Profile version, `OPINION.md` and `opinion.lock.json` in one go, reads them back with `verify`, and only then marks the candidates `formal`. If candidates, the Profile or `OPINION.md` changed since the preview, the fingerprint no longer matches and nothing is written. It does not use `--confirmed`: the confirmation is the preview fingerprint.
32
+ - Several ids share one preview and one confirmation, and either all succeed or none changes; a missing id or an id that is already `formal` fails the whole call and is named. If writing or the read-back fails, `OPINION.md`, the lock and the Profile file created by this run are restored and the candidate status is unchanged.
33
+ - A candidate that `decide --to formal` already recorded but that is not written yet: move it back with `decide --to pending --confirmed`, then `adopt`.
29
34
  - `present <ids...>`: record that the user has been shown these candidates (the hook calls it when it sends the confirmation request, so the same candidate is not raised again and again).
30
35
  - `expire --days N`: return trials older than N days to `pending`. The return keeps `last_action_at`, so the item still counts as "untouched for a long time".
31
36
  - `pending [--session ID]`: the pending-item provider, see below.