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

package/runtime/plugins/agent-pack/runtime/agenthelm.py

@@ -2,7 +2,7 @@
 """agenthelm：在 Claude Code、Codex、Cursor 间安装、检查与更新 agenthelm 插件。
 
 ``project`` 打开不需要 AI Agent 的项目自助入口（由 project-orchestrator 实现）；``runtime``
-管理用户级运行时。``check`` 只读：比较各客户端已安装的插件版本、项目里由模板渲染的文件，
+管理用户级运行时；``nudge`` 是各客户端 hook 调用的观点候选采集与未决事项提示（见 references/nudge.md）。``check`` 只读：比较各客户端已安装的插件版本、项目里由模板渲染的文件，
 以及 Opinion 来源与云端 ``latest.json``。``install``、``update``、``migrate``
 默认只预览，``--apply`` 才执行。通过 ``npx @sakanano-moe/agenthelm <命令>`` 或
 ``python3 <agent-pack>/runtime/agenthelm.py <命令>`` 运行。``--hook`` 供会话开始时静默调用：
@@ -28,6 +28,8 @@ from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
+from i18n_agent_pack import _  # noqa: E402
+from i18n_agent_pack import _  # noqa: E402
 
 MARKETPLACE = "agenthelm"
 CLI = "npx @sakanano-moe/agenthelm"
@@ -73,6 +75,10 @@ def write_json_atomic(path: Path, data: Any) -> None:
     os.replace(temporary, path)
 
 
+def sha256_text(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
 def sha256_file(path: Path) -> str:
     return hashlib.sha256(path.read_bytes()).hexdigest()
 
@@ -99,6 +105,11 @@ class Env:
         base = self.get("XDG_CACHE_HOME")
         return (Path(base) if base else self.home / ".cache") / "agenthelm"
 
+    @property
+    def state_dir(self) -> Path:
+        base = self.get("XDG_STATE_HOME")
+        return Path(base) if base else self.home / ".local" / "state"
+
     @property
     def config_file(self) -> Path:
         base = self.get("XDG_CONFIG_HOME")
@@ -165,14 +176,14 @@ def load_latest(env: Env, source: str | None = None, *, offline: bool = False,
     if cached and (offline or time.time() - cached.get("fetched_at", 0) < max_age):
         return cached["latest"], {"source": cached.get("url"), "cached": True, "fetched_at": cached.get("fetched_at")}
     if offline:
-        raise CheckError("离线且没有缓存的 latest.json")
+        raise CheckError(_("离线且没有缓存的 latest.json"))
     failure_file = env.cache_dir / "last_failure.json"
     if backoff:
         try:
             if time.time() - read_json(failure_file).get("at", 0) < FAILURE_BACKOFF_SECONDS:
                 if cached:
                     return cached["latest"], {"source": cached.get("url"), "cached": True, "stale": True}
-                raise CheckError("最近联网失败，稍后再试")
+                raise CheckError(_("最近联网失败，稍后再试"))
         except (OSError, ValueError, AttributeError):
             pass
     errors = []
@@ -194,7 +205,7 @@ def load_latest(env: Env, source: str | None = None, *, offline: bool = False,
     if cached:
         return cached["latest"], {"source": cached.get("url"), "cached": True, "stale": True,
                                   "fetched_at": cached.get("fetched_at")}
-    raise CheckError("无法获取 latest.json：" + "; ".join(errors))
+    raise CheckError(_("无法获取 latest.json：") + "; ".join(errors))
 
 
 # ---------------------------------------------------------------- installed plugins
@@ -213,7 +224,7 @@ def installed_plugins(env: Env, names: set[str]) -> list[dict]:
     except (OSError, ValueError, AttributeError):
         record = {}
     for key, entries in sorted(record.items()):
-        plugin, _, market = key.partition("@")
+        plugin, _sep, market = key.partition("@")
         if market != MARKETPLACE or plugin not in names:
             continue
         for entry in entries:
@@ -241,14 +252,18 @@ def installed_plugins(env: Env, names: set[str]) -> list[dict]:
 
 
 def migrations_between(latest: dict, plugin: str, current: str, target: str) -> list[dict]:
-    steps = []
+    """The steps from ``current`` to ``target``; when two entries end at the same version (a span kept for the
+    release gate and the single steps inside it) the narrower one, with the newer ``from``, is shown."""
+    steps: dict[str, dict] = {}
     for entry in latest.get("migrations", []):
         if entry.get("plugin") != plugin:
             continue
         to = str(entry.get("to"))
         if is_newer(to, current) and not is_newer(to, target):
-            steps.append(entry)
-    return sorted(steps, key=lambda entry: version_key(str(entry.get("to"))) or (0,))
+            kept = steps.get(to)
+            if kept is None or is_newer(str(entry.get("from")), str(kept.get("from"))):
+                steps[to] = entry
+    return sorted(steps.values(), key=lambda entry: version_key(str(entry.get("to"))) or (0,))
 
 
 def plugin_findings(latest: dict, installed: list[dict]) -> list[dict]:
@@ -292,7 +307,7 @@ def content_findings(project: Path, latest: dict) -> list[dict]:
     try:
         lock = read_json(lock_path)
     except (OSError, ValueError) as exc:
-        return [{"pack": None, "status": "error", "error": f"{CONTENT_LOCK} 无法解析：{exc}"}]
+        return [{"pack": None, "status": "error", "error": _("{0} 无法解析：{1}").format(CONTENT_LOCK, exc)}]
     findings = []
     for pack_id, entry in sorted(lock.get("packs", {}).items()):
         plugin = entry.get("plugin") or pack_id.split("/", 1)[0]
@@ -333,11 +348,11 @@ def opinion_findings(project: Path, installed: list[dict]) -> list[dict]:
         return []
     manager = locate_companion("opinion-manager", installed)
     if manager is None:
-        return [{"status": "unknown", "error": "未找到已安装的 opinion-manager"}]
+        return [{"status": "unknown", "error": _("未找到已安装的 opinion-manager")}]
     try:
         profile = read_json(lock_path)["profile"]
     except (OSError, ValueError, KeyError, TypeError) as exc:
-        return [{"status": "error", "error": f"{OPINION_LOCK} 无法解析：{exc}"}]
+        return [{"status": "error", "error": _("{0} 无法解析：{1}").format(OPINION_LOCK, exc)}]
     with tempfile.TemporaryDirectory() as temporary:
         # macOS temporary paths live under /var, a symlink opinion-manager refuses.
         profile_file = Path(temporary).resolve() / "profile.json"
@@ -352,14 +367,174 @@ def opinion_findings(project: Path, installed: list[dict]) -> list[dict]:
     except ValueError:
         return [{"status": "error", "error": (completed.stderr or completed.stdout).strip()[:300]}]
     if not result.get("ok", False):
-        return [{"status": "error", "error": result.get("error", "opinion-manager updates 失败")}]
+        return [{"status": "error", "error": result.get("error", _("opinion-manager updates 失败"))}]
     return [{"status": "update-available" if result["updates"] else "current", "updates": result["updates"]}]
 
 
+# ---------------------------------------------------------------- project scaffold
+
+PROFILE_FILE = Path(".agents/moe.sakanano.agent-pack/project.json")
+_SCAFFOLD_CACHE: dict[str, Any] = {}
+
+
+def profile_root(project: Path | None) -> Path | None:
+    """The project root that holds the Project Profile, searching upwards from ``project``."""
+    if project is None:
+        return None
+    base = project.expanduser().resolve()
+    return next((path for path in [base, *base.parents] if (path / PROFILE_FILE).is_file()), None)
+
+
+def scaffold_module(env: Env) -> Any | None:
+    """agents-init's scaffold module (the sibling copy first, then the newest installed one); None when too old."""
+    installed = installed_plugins(env, {"agents-init"})
+    copies = [PLUGIN_ROOT.parent / "agents-init", *(Path(item["path"]) for item in installed)]
+    usable = [path for path in copies if (path / "skills/agents-init/scripts/scaffold.py").is_file()]
+    if not usable:
+        return None
+    sibling = PLUGIN_ROOT.parent / "agents-init"
+    root = sibling if sibling in usable else max(usable, key=lambda p: version_key(_manifest_version(p) or "") or (0,))
+    scripts = root / "skills/agents-init/scripts"
+    key = str(scripts)
+    if key not in _SCAFFOLD_CACHE:
+        import importlib.util
+        spec = importlib.util.spec_from_file_location(f"agenthelm_scaffold_{len(_SCAFFOLD_CACHE)}", scripts / "scaffold.py")
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = module
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+        _SCAFFOLD_CACHE[key] = module
+    return _SCAFFOLD_CACHE[key]
+
+
+def scaffold_report(env: Env, project: Path | None, *, reprompt: bool = False) -> dict | None:
+    """Read-only comparison of the project with the expected scaffold; None outside a project."""
+    root = profile_root(project)
+    if root is None:
+        return None
+    base = {"available": False, "root": str(root), "findings": [], "skipped": [], "error": ""}
+    module = scaffold_module(env)
+    if module is None:
+        return {**base, "error": _("已安装的 agents-init 没有脚手架检查（更新 agents-init 后再检查）")}
+    try:
+        return {**module.check(root, state_dir=env.state_dir, reprompt=reprompt), "available": True,
+                "root": str(root), "error": ""}
+    except Exception as exc:  # noqa: BLE001 - a broken Profile must not break plugin and content checks
+        return {**base, "error": str(exc)}
+
+
+def _local_only() -> Any:
+    """local_only 模块（与本文件同目录，只用标准库）。"""
+    if str(RUNTIME_DIR) not in sys.path:
+        sys.path.insert(0, str(RUNTIME_DIR))
+    import local_only  # noqa: PLC0415 - shipped next to this file
+
+    return local_only
+
+
+SYNC_SERVICES = tuple((name, pattern) for _identifier, name, pattern in _local_only().SYNC_SERVICES)
+REBUILDABLE_DIRS = {"node_modules", ".venv", "venv", "__pycache__", ".pytest_cache", ".cache", "dist", "build", "target",
+                    ".tox", ".next", ".gradle"}
+
+
+def sync_folder(root: Path) -> dict | None:
+    """The sync service whose folder holds the project (by path), and the rebuildable directories inside it."""
+    resolved = root.resolve()
+    service = next((name for name, pattern in SYNC_SERVICES if any(pattern.match(part) for part in resolved.parts)), None)
+    if service is None:
+        return None
+    found: list[str] = []
+    for current, directories, _files in os.walk(resolved):
+        depth = len(Path(current).relative_to(resolved).parts)
+        descend = []
+        for name in directories:
+            if name in REBUILDABLE_DIRS:
+                found.append((Path(current) / name).relative_to(resolved).as_posix())
+            elif name != ".git" and depth < 1:  # 只看根目录和它的下一层
+                descend.append(name)
+        directories[:] = descend
+    return {"service": service, "path": str(resolved), "rebuildable": sorted(found)}
+
+
+def machine_findings(env: Env, project: Path | None, *, reprompt: bool = False, quick: bool = False) -> dict:
+    """Findings about this machine only (no user-level runtime ...); their decisions live in the user state directory."""
+    root = profile_root(project)
+    result: dict = {"findings": [], "skipped": []}
+    if root is None:
+        return result
+    import agenthelm_runtime  # noqa: PLC0415 - shipped next to this file
+
+    findings = []
+    data = agenthelm_runtime.report(env, None)
+    if data["current"] is None:
+        text = agenthelm_runtime.missing_text(data, agenthelm_runtime.command_status())
+        findings.append({"id": "local:runtime-missing", "kind": "runtime-missing", "level": "suggest", "scope": "machine",
+                         "title": _("这台机器还没有安装用户级运行时"), "reason": text["reason"], "impact": text["impact"],
+                         "fingerprint": "runtime-missing", "fix": "install-runtime", "next": text["label"]})
+    where = sync_folder(root)
+    if where is not None:
+        extra = _("；其中有可重建目录：{0}").format(_('、').join(where['rebuildable'][:6])) if where["rebuildable"] else ""
+        findings.append({"id": "local:sync-folder", "kind": "sync-folder", "level": "suggest", "scope": "machine",
+                         "title": _("项目位于同步盘（{0}）").format(where['service']),
+                         "reason": f"{where['path']}{extra}",
+                         "impact": _("多台机器共用同一份项目时：项目文件随同步盘走，但运行时、缓存与 wf 的台账是每台机器各一份；"
+                                   "可重建目录（依赖、构建产物）同步很慢，也容易产生冲突副本"),
+                         "fingerprint": sha256_text(where["service"]), "fix": "sync-folder",
+                         "next": _("运行 agenthelm fix sync-folder 查看指引（只给方案，不改文件、不删内容）；不需要就 fix --skip local:sync-folder"),
+                         "sync": where})
+    # local-only：同步盘里的本机专属目录、外置链接、HOME、体积……没有同步服务也没有配置时不扫描。
+    try:
+        engine = _local_only().check(root, home=env.home, environ=env.variables, mode="quick" if quick else "standard",
+                                     user_config=env.config_file)
+        findings.extend(engine["findings"])
+    except Exception as exc:  # noqa: BLE001 - 本机目录检查出错不能拖垮插件与脚手架检查
+        findings.append({"id": "local:local-only-error", "kind": "error", "level": "suggest", "scope": "machine",
+                         "title": _("无法检查本机专属目录"), "reason": str(exc), "impact": _("只影响同步盘相关提示"),
+                         "fingerprint": sha256_text(str(exc)), "fix": None, "attention": False, "options": [],
+                         "next": _("运行 agenthelm local-only check 查看详情")})
+    module = scaffold_module(env)
+    if module is None or not findings:
+        result["findings"] = findings
+        return result
+    decisions = module.load_decisions(root, env.state_dir)
+    result["findings"], result["skipped"] = module.partition(findings, decisions, reprompt=reprompt)
+    return result
+
+
+def local_only_report(env: Env, project: Path | None, *, mode: str = "full", reprompt: bool = False) -> dict:
+    """local-only 的完整检查结果（供 ``agenthelm local-only check`` 与 MCP 工具），已套用这台机器上记录的决定。"""
+    module = _local_only()
+    base = (project or Path.cwd()).resolve()
+    root = profile_root(base) or base
+    report = module.check(root, home=env.home, environ=env.variables, mode=mode, user_config=env.config_file)
+    report["skipped"] = []
+    scaffold = scaffold_module(env)
+    if scaffold is not None and report["findings"]:
+        decisions = scaffold.load_decisions(root, env.state_dir)
+        report["findings"], skipped = scaffold.partition(report["findings"], decisions, reprompt=reprompt)
+        report["skipped"] = [{"id": item["id"], "decision": item["decision"]} for item in skipped]
+        report["summary"] = {"findings": len(report["findings"]),
+                             "attention": sum(1 for item in report["findings"] if item.get("attention"))}
+    return report
+
+
+def local_only_plan(env: Env, project: Path | None, **options: Any) -> dict:
+    """``agenthelm local-only fix`` 的预览（不写任何东西）；原因不能处理时抛出 LocalOnlyError。"""
+    base = (project or Path.cwd()).resolve()
+    return _local_only().plan_fix(profile_root(base) or base, home=env.home, environ=env.variables,
+                                  user_config=env.config_file, **options)
+
+
 # ---------------------------------------------------------------- report
 
+def scaffold_fingerprint(env: Env, scaffold: dict | None) -> dict | None:
+    module = scaffold_module(env)
+    if scaffold is None or module is None or not scaffold.get("available"):
+        return None
+    return module.fingerprint(scaffold)
+
+
 def run_check(env: Env, project: Path | None, *, latest_source: str | None = None, offline: bool = False,
-              max_age: int = CACHE_TTL_SECONDS, hook_mode: bool = False) -> dict:
+              max_age: int = CACHE_TTL_SECONDS, hook_mode: bool = False, reprompt: bool = False) -> dict:
     latest, origin = load_latest(
         env, latest_source, offline=offline, max_age=max_age,
         timeout=HOOK_FETCH_TIMEOUT_SECONDS if hook_mode else FETCH_TIMEOUT_SECONDS, backoff=hook_mode,
@@ -369,6 +544,10 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
     plugins = plugin_findings(latest, installed)
     content = content_findings(project, latest) if project else []
     opinion = opinion_findings(project, installed) if project else []
+    scaffold = scaffold_report(env, project, reprompt=reprompt)
+    machine = machine_findings(env, project, reprompt=reprompt, quick=hook_mode)
+    local_attention = sum(1 for item in machine["findings"] if item.get("attention"))
+    scaffold_active = len(scaffold["findings"]) if scaffold else 0
     behind = [item for item in plugins if item["status"] == "behind"]
     legacy = [item for item in plugins if item["client"] == "legacy"]
     content_updates = [item for item in content if item["status"] in {"update-available", "conflict"}]
@@ -380,14 +559,20 @@ def run_check(env: Env, project: Path | None, *, latest_source: str | None = Non
         "plugins": plugins,
         "content": content,
         "opinion": opinion,
+        "scaffold": scaffold,
+        "machine": machine,
         "summary": {
+            "scaffold_findings": scaffold_active,
+            "scaffold_skipped": len(scaffold["skipped"]) if scaffold else 0,
+            "local_only_attention": local_attention,
             "plugins_behind": len(behind),
             "breaking": any(item["breaking"] for item in behind),
             "content_updates": len(content_updates),
             "content_conflicts": sum(1 for item in content if item["status"] == "conflict"),
             "opinion_updates": len(opinion_updates),
             "legacy_installs": len(legacy),
-            "up_to_date": not (behind or content_updates or opinion_updates or legacy),
+            "up_to_date": not (behind or content_updates or opinion_updates or legacy or scaffold_active
+                               or local_attention),
         },
     }
 
@@ -406,66 +591,110 @@ def one_line(report: dict) -> str | None:
         return None
     parts = []
     if summary["plugins_behind"]:
-        parts.append(f"{summary['plugins_behind']} 个插件可更新" + ("（含不兼容变更）" if summary["breaking"] else ""))
+        parts.append(_("{0} 个插件可更新").format(summary['plugins_behind']) + (_("（含不兼容变更）") if summary["breaking"] else ""))
     if summary["content_updates"]:
-        parts.append(f"{summary['content_updates']} 个模板/样例包可更新"
-                     + (f"（{summary['content_conflicts']} 个本地有改动，更新时逐文件确认）" if summary["content_conflicts"] else ""))
+        parts.append(_("{0} 个模板/样例包可更新").format(summary['content_updates'])
+                     + (_("（{0} 个本地有改动，更新时逐文件确认）").format(summary['content_conflicts']) if summary["content_conflicts"] else ""))
     if summary["opinion_updates"]:
-        parts.append("Opinion 有新版本模板或规则")
+        parts.append(_("Opinion 有新版本模板或规则"))
     if summary["legacy_installs"]:
-        parts.append(f"{summary['legacy_installs']} 个旧方式安装待迁移")
-    return "agenthelm：" + "，".join(parts) + f"。运行 `{CLI} check` 查看详情；更新前会先预览，由你决定。"
+        parts.append(_("{0} 个旧方式安装待迁移").format(summary['legacy_installs']))
+    if summary["scaffold_findings"]:
+        parts.append(_("项目脚手架有 {0} 项差异").format(summary['scaffold_findings']))
+    if summary.get("local_only_attention"):
+        parts.append(_("同步目录里有 {0} 项本机专属目录需要处理").format(summary['local_only_attention']))
+    return _("agenthelm：") + _("，").join(parts) + _("。运行 `{0} check` 查看详情；更新前会先预览，由你决定。").format(CLI)
 
 
-def render_text(report: dict) -> str:
+def render_scaffold(report: dict, show_skipped: bool) -> list[str]:
+    scaffold = report.get("scaffold")
+    lines = []
+    if scaffold is None:
+        return lines
+    if scaffold.get("error"):
+        lines.append(_("  [脚手架] 无法检查：{0}").format(scaffold['error']))
+        return lines
+    for item in scaffold["findings"]:
+        mark = _("（稍后）") if item.get("deferred") else _("（期望内容已变化，重新提示）") if item.get("changed_since_decision") else ""
+        fix = _("  处理：fix {0}").format(item['fix']) if item.get("fix") else _("  需要你自己处理")
+        lines.append(_("  [脚手架] {0}{1}：{2}\n      ID {3}{4}").format(item['title'], mark, item['reason'], item['id'], fix))
+    for message in scaffold["decisions"]["errors"]:
+        lines.append(_("  [脚手架] 决定文件有问题：{0}").format(message))
+    if scaffold["decisions"]["conflict_copies"]:
+        lines.append(_("  [脚手架] 同步服务留下了决定文件的冲突副本：")
+                     + _("、").join(scaffold["decisions"]["conflict_copies"]) + _("（合并到 check-decisions.json 后删除）"))
+    if not scaffold["findings"] and not scaffold["decisions"]["errors"]:
+        lines.append(_("  [脚手架] 与期望一致") + (_("（{0} 项已跳过）").format(len(scaffold['skipped'])) if scaffold["skipped"] else ""))
+    skipped = [*scaffold["skipped"], *report.get("machine", {}).get("skipped", [])]
+    if show_skipped:
+        for item in skipped:
+            decision = item["decision"]
+            lines.append(_("  [已跳过·{0}] {1}：{2}  {3}").format(decision['decision'], item['id'], decision.get('reason') or _('（未写理由）'), decision.get('decided_at', '')))
+        if not skipped:
+            lines.append(_("  没有被跳过的项。"))
+    elif skipped:
+        lines.append(_("  （另有 {0} 项已被你跳过：check --show-skipped 查看）").format(len(skipped)))
+    return lines
+
+
+def render_machine(report: dict) -> list[str]:
+    lines = []
+    for item in report.get("machine", {}).get("findings", []):
+        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']))
+    return lines
+
+
+def render_text(report: dict, *, show_skipped: bool = False) -> str:
     lines = []
     origin = report["latest"]["source"]
-    lines.append(f"云端版本源：{origin.get('source')}" + ("（缓存）" if origin.get("cached") else ""))
+    lines.append(_("云端版本源：{0}").format(origin.get('source')) + (_("（缓存）") if origin.get("cached") else ""))
     if not report["plugins"]:
-        lines.append("未发现已安装的 agenthelm 插件。")
+        lines.append(_("未发现已安装的 agenthelm 插件。"))
     for item in report["plugins"]:
-        label = {"behind": "可更新", "current": "最新", "ahead": "高于云端", "unknown": "版本未知",
-                 "legacy": "旧方式安装，待迁移"}[item["status"]]
+        label = {"behind": _("可更新"), "current": _("最新"), "ahead": _("高于云端"), "unknown": _("版本未知"),
+                 "legacy": _("旧方式安装，待迁移")}[item["status"]]
         if item["status"] == "legacy":
-            lines.append(f"  [旧方式] {item['plugin']} {item.get('version')}  {label}")
+            lines.append(_("  [旧方式] {0} {1}  {2}").format(item['plugin'], item.get('version'), label))
             continue
         line = f"  [{item['client']}] {item['plugin']} {item.get('version')} → {item.get('latest')}  {label}"
         if item["status"] == "behind":
-            kinds = {"code": "代码", "content": "仅模板/样例", "both": "代码与模板"}
+            kinds = {"code": _("代码"), "content": _("仅模板/样例"), "both": _("代码与模板")}
             if item["change_kinds"]:
-                line += "（" + "、".join(kinds[kind] for kind in item["change_kinds"]) + "）"
+                line += _("（") + _("、").join(kinds[kind] for kind in item["change_kinds"]) + _("）")
             if item["breaking"]:
-                line += "（含不兼容变更）"
+                line += _("（含不兼容变更）")
             for step in item["steps"]:
                 if step.get("breaking"):
-                    line += f"\n      {step['to']} 不兼容：{step.get('summary')}"
+                    line += _("\n      {0} 不兼容：{1}").format(step['to'], step.get('summary'))
                     line += "".join(f"\n        - {action}" for action in step.get("actions") or [])
             hint = UPDATE_HINTS.get(item["client"])
             if hint:
-                line += f"\n      更新：{hint.format(plugin=item['plugin'])}"
+                line += _("\n      更新：{0}").format(hint.format(plugin=item['plugin']))
         lines.append(line)
     for item in report["content"]:
         if item.get("pack") is None:
-            lines.append(f"  内容锁：{item.get('error')}")
+            lines.append(_("  内容锁：{0}").format(item.get('error')))
             continue
-        label = {"current": "最新", "update-available": "可更新（本地未改动）",
-                 "conflict": "可更新（本地有改动，更新时逐文件确认）", "unknown": "云端未列出"}[item["status"]]
-        line = f"  [内容] {item['pack']} {item['version']} → {item.get('latest')}  {label}"
+        label = {"current": _("最新"), "update-available": _("可更新（本地未改动）"),
+                 "conflict": _("可更新（本地有改动，更新时逐文件确认）"), "unknown": _("云端未列出")}[item["status"]]
+        line = _("  [内容] {0} {1} → {2}  {3}").format(item['pack'], item['version'], item.get('latest'), label)
         if item["locally_changed"]:
-            line += "\n      本地已改动：" + "、".join(item["locally_changed"])
+            line += _("\n      本地已改动：") + _("、").join(item["locally_changed"])
         lines.append(line)
     for item in report["opinion"]:
         if item["status"] == "update-available":
-            refs = "；".join(f"{update['current']} → {update['available'][-1]}" for update in item["updates"])
-            lines.append(f"  [Opinion] 有新版本：{refs}（用 opinion-manager 预览后确认）")
+            refs = _("；").join(f"{update['current']} → {update['available'][-1]}" for update in item["updates"])
+            lines.append(_("  [Opinion] 有新版本：{0}（用 opinion-manager 预览后确认）").format(refs))
         elif item["status"] in {"error", "unknown"}:
             lines.append(f"  [Opinion] {item.get('error')}")
+    lines += render_scaffold(report, show_skipped)
+    lines += render_machine(report)
     if not report["plugins"]:
-        lines.append(f"运行 `{CLI} install` 预览安装。")
+        lines.append(_("运行 `{0} install` 预览安装。").format(CLI))
     else:
         if any(item["status"] == "legacy" for item in report["plugins"]):
-            lines.append(f"旧方式安装可用 `{UPDATE_HINTS['legacy']}` 预览迁移。")
-        lines.append(one_line(report) or "全部为最新。")
+            lines.append(_("旧方式安装可用 `{0}` 预览迁移。").format(UPDATE_HINTS['legacy']))
+        lines.append(one_line(report) or _("全部为最新。"))
     return "\n".join(lines) + "\n"
 
 
@@ -513,7 +742,7 @@ CLIENTS = ("claude", "codex", "cursor")
 def github_slug(latest: dict) -> str:
     match = re.match(r"https://github\.com/([^/]+/[^/]+?)(?:\.git)?/?$", str(latest.get("repository", "")))
     if not match:
-        raise CheckError(f"latest.json 的 repository 不是 GitHub 仓库：{latest.get('repository')}")
+        raise CheckError(_("latest.json 的 repository 不是 GitHub 仓库：{0}").format(latest.get('repository')))
     return match.group(1)
 
 
@@ -533,9 +762,9 @@ def _safe_extract(archive: Path, destination: Path) -> None:
         for member in bundle.getmembers():
             target = (destination / member.name).resolve()
             if destination.resolve() not in target.parents and target != destination.resolve():
-                raise CheckError(f"发布包含越界路径：{member.name}")
+                raise CheckError(_("发布包含越界路径：{0}").format(member.name))
             if not (member.isfile() or member.isdir()):
-                raise CheckError(f"发布包含不支持的条目：{member.name}")
+                raise CheckError(_("发布包含不支持的条目：{0}").format(member.name))
         try:
             bundle.extractall(destination, filter="data")  # noqa: S202 - members validated above
         except TypeError:  # Python without extraction filters
@@ -566,25 +795,25 @@ def release_source(latest: dict, workdir: Path, source: Path | None = None) -> P
     if source is not None:
         root = source.expanduser().resolve()
         if not (root / "plugins").is_dir():
-            raise CheckError(f"{root} 不含 plugins/ 目录")
+            raise CheckError(_("{0} 不含 plugins/ 目录").format(root))
         return root
     release = latest.get("release") or github_release(latest)
     tag, digest = release.get("tag"), release.get("tarball_sha256")
     if not tag or not digest:
-        raise CheckError("云端 latest.json 没有发布 tag 与摘要；请用 --source 指定本地仓库")
+        raise CheckError(_("云端 latest.json 没有发布 tag 与摘要；请用 --source 指定本地仓库"))
     url = release.get("tarball_url") or f"https://github.com/{github_slug(latest)}/releases/download/{tag}/agenthelm-{tag}.tar.gz"
     archive = workdir / "release.tar.gz"
     request = urllib.request.Request(url, headers={"User-Agent": "agenthelm"})
     with urllib.request.urlopen(request, timeout=60) as response, archive.open("wb") as handle:  # noqa: S310
         shutil.copyfileobj(response, handle)
     if sha256_file(archive) != digest:
-        raise CheckError(f"发布包摘要不符：{url}")
+        raise CheckError(_("发布包摘要不符：{0}").format(url))
     extracted = workdir / "release"
     extracted.mkdir()
     _safe_extract(archive, extracted)
     roots = [path for path in extracted.iterdir() if path.is_dir()]
     if len(roots) != 1 or not (roots[0] / "plugins").is_dir():
-        raise CheckError("发布包结构不符合预期")
+        raise CheckError(_("发布包结构不符合预期"))
     return roots[0]
 
 
@@ -642,7 +871,7 @@ def find_cli(env: Env, name: str) -> str | None:
 def _cli(env: Env, name: str, *args: str) -> tuple[list[str], str | None]:
     """The command (using the resolved executable) and why it cannot run, if it cannot."""
     found = find_cli(env, name)
-    return [found or name, *args], (None if found else f"未找到 {name} 命令（已查 PATH 与常见安装位置；可用 AGENTHELM_{name.upper()} 指定）")
+    return [found or name, *args], (None if found else _("未找到 {0} 命令（已查 PATH 与常见安装位置；可用 AGENTHELM_{1} 指定）").format(name, name.upper()))
 
 
 def install_steps(env: Env, latest: dict, clients: list[str], plugins: list[str], source: Path | None,
@@ -652,18 +881,18 @@ def install_steps(env: Env, latest: dict, clients: list[str], plugins: list[str]
     for client in clients:
         if client == "claude":
             command, blocked = _cli(env, "claude", "plugin", "marketplace", "add", slug)
-            steps.append(Step("install", "claude", f"Claude Code 添加 agenthelm 市场（{slug}）", command, blocked=blocked))
+            steps.append(Step("install", "claude", _("Claude Code 添加 agenthelm 市场（{0}）").format(slug), command, blocked=blocked))
             for plugin in plugins:
                 command, blocked = _cli(env, "claude", "plugin", "install", f"{plugin}@{MARKETPLACE}")
-                steps.append(Step("install", "claude", f"Claude Code 安装 {plugin}", command, blocked=blocked))
+                steps.append(Step("install", "claude", _("Claude Code 安装 {0}").format(plugin), command, blocked=blocked))
         elif client == "codex":
             command, blocked = _cli(env, "codex", "plugin", "marketplace", "add", slug)
-            steps.append(Step("install", "codex", f"Codex 添加 agenthelm 市场（{slug}）", command, blocked=blocked))
+            steps.append(Step("install", "codex", _("Codex 添加 agenthelm 市场（{0}）").format(slug), command, blocked=blocked))
             for plugin in plugins:
                 command, blocked = _cli(env, "codex", "plugin", "add", f"{plugin}@{MARKETPLACE}")
-                steps.append(Step("install", "codex", f"Codex 安装 {plugin}", command, blocked=blocked))
+                steps.append(Step("install", "codex", _("Codex 安装 {0}").format(plugin), command, blocked=blocked))
         elif client == "cursor":
-            steps.append(cursor_step(latest, plugins, source, home, "安装"))
+            steps.append(cursor_step(latest, plugins, source, home, _("安装")))
     return steps
 
 
@@ -675,7 +904,7 @@ def cursor_step(latest: dict, plugins: list[str], source: Path | None, home: Pat
             return [config.install_plugin(root / "plugins" / plugin, "cursor", home=home, apply=apply,
                                           replace=True, recovery_root=recovery_root)
                     for plugin in plugins]
-    return Step("install", "cursor", f"Cursor {verb} {'、'.join(plugins)} 到 ~/.cursor/plugins/local（重启 Cursor 生效）",
+    return Step("install", "cursor", _("Cursor {0} {1} 到 ~/.cursor/plugins/local（重启 Cursor 生效）").format(verb, _('、').join(plugins)),
                 action=run)
 
 
@@ -689,18 +918,18 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
         claude = sorted({item["plugin"] for item in behind if item["client"] == "claude"})
         if claude:
             command, blocked = _cli(env, "claude", "plugin", "marketplace", "update", MARKETPLACE)
-            steps.append(Step("update", "claude", "刷新 Claude Code 的 agenthelm 市场", command, blocked=blocked))
+            steps.append(Step("update", "claude", _("刷新 Claude Code 的 agenthelm 市场"), command, blocked=blocked))
             for item in [entry for entry in behind if entry["client"] == "claude"]:
                 extra = ["--scope", item["scope"]] if item.get("scope") and item["scope"] != "user" else []
                 command, blocked = _cli(env, "claude", "plugin", "update", f"{item['plugin']}@{MARKETPLACE}", *extra)
-                steps.append(Step("update", "claude", f"Claude Code 更新 {item['plugin']} → {item['latest']}",
+                steps.append(Step("update", "claude", _("Claude Code 更新 {0} → {1}").format(item['plugin'], item['latest']),
                                   command, blocked=blocked))
         if any(item["client"] == "codex" for item in behind):
             command, blocked = _cli(env, "codex", "plugin", "marketplace", "upgrade", MARKETPLACE)
-            steps.append(Step("update", "codex", "Codex 升级 agenthelm 市场与已装插件", command, blocked=blocked))
+            steps.append(Step("update", "codex", _("Codex 升级 agenthelm 市场与已装插件"), command, blocked=blocked))
         cursor = sorted({item["plugin"] for item in behind if item["client"] == "cursor"})
         if cursor:
-            steps.append(cursor_step(latest, cursor, source, home, "更新"))
+            steps.append(cursor_step(latest, cursor, source, home, _("更新")))
     if only in (None, "content") and project is not None:
         for item in report["content"]:
             if item.get("status") not in {"update-available", "conflict"}:
@@ -712,15 +941,15 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
 def content_step(env: Env, item: dict, report: dict, project: Path, accept: list[str], keep: list[str],
                  recovery_dir: Path | None) -> Step:
     if item["plugin"] != "agents-init":
-        return Step("content", None, f"{item['pack']}：没有可用的刷新工具", blocked="unsupported")
+        return Step("content", None, _("{0}：没有可用的刷新工具").format(item['pack']), blocked="unsupported")
     stale = any(entry["plugin"] == "agents-init" and entry["status"] == "behind" for entry in report["plugins"])
-    description = f"重新渲染 {item['pack']} {item['version']} → {item['latest']}"
+    description = _("重新渲染 {0} {1} → {2}").format(item['pack'], item['version'], item['latest'])
 
     def run(apply: bool, _recovery_root: Path | None) -> dict:
         installed = installed_plugins(env, {"agents-init"})
         manager = locate_companion("agents-init", installed)
         if manager is None:
-            raise CheckError("未找到已安装的 agents-init")
+            raise CheckError(_("未找到已安装的 agents-init"))
         command = [sys.executable, str(manager / "skills/agents-init/scripts/init_project.py"),
                    "--project", str(project), "--mode", "refresh", "--output", "json"]
         for path in accept:
@@ -738,7 +967,7 @@ def content_step(env: Env, item: dict, report: dict, project: Path, accept: list
         except ValueError as exc:
             raise CheckError((completed.stderr or completed.stdout).strip()[:300]) from exc
 
-    blocked = "先更新 agents-init 插件，再用新模板预览" if stale else None
+    blocked = _("先更新 agents-init 插件，再用新模板预览") if stale else None
     return Step("content", None, description, action=run, blocked=blocked)
 
 
@@ -940,86 +1169,97 @@ def doctor(env: Env, report: dict) -> dict:
         clients = [item["client"] for item in items]
         if "legacy" in clients and any(client in {"claude", "codex"} for client in clients):
             issues.append({"plugin": plugin, "issue": "duplicate",
-                           "detail": f"同时存在市场安装与旧方式安装，运行 {CLI} migrate"})
+                           "detail": _("同时存在市场安装与旧方式安装，运行 {0} migrate").format(CLI)})
         versions = {item.get("version") for item in items if item["client"] != "legacy"}
         if len(versions) > 1:
             issues.append({"plugin": plugin, "issue": "version-skew",
-                           "detail": "各客户端版本不一致：" + "、".join(f"{i['client']}={i.get('version')}" for i in items)})
+                           "detail": _("各客户端版本不一致：") + _("、").join(f"{i['client']}={i.get('version')}" for i in items)})
     names = set(report["_latest"].get("plugins", {}))
     installed_names = {item["plugin"] for item in report["plugins"] if item["client"] != "legacy"}
     if installed_names and installed_names != names:
         issues.append({"plugin": None, "issue": "incomplete",
-                       "detail": "缺少：" + "、".join(sorted(names - installed_names))})
+                       "detail": _("缺少：") + _("、").join(sorted(names - installed_names))})
     if not update_check_enabled(env):
-        issues.append({"plugin": None, "issue": "update-check-disabled", "detail": "会话内更新检查已关闭"})
+        issues.append({"plugin": None, "issue": "update-check-disabled", "detail": _("会话内更新检查已关闭")})
     return {"ok": not [issue for issue in issues if issue["issue"] != "update-check-disabled"],
             "issues": issues, "legacy": legacy_artifacts(env, names), "summary": report["summary"]}
 
 
 def parser() -> argparse.ArgumentParser:
-    result = argparse.ArgumentParser(prog="agenthelm", description=__doc__.split("\n\n")[0])
+    result = argparse.ArgumentParser(prog="agenthelm", description=_("agenthelm：在 Claude Code、Codex、Cursor 间安装、检查与更新 agenthelm 插件。"))
     sub = result.add_subparsers(dest="command", required=True)
 
     def common(command: argparse.ArgumentParser, *, project: bool = True) -> None:
-        command.add_argument("--latest", help="latest.json 的 URL 或本地路径（测试、离线镜像）")
+        command.add_argument("--latest", help=_("latest.json 的 URL 或本地路径（测试、离线镜像）"))
         command.add_argument("--output", choices=("text", "json"), default="text")
         command.add_argument("--home", type=Path, help=argparse.SUPPRESS)
         if project:
-            command.add_argument("--project", type=Path, default=None, help="项目目录；默认当前目录")
-            command.add_argument("--no-project", action="store_true", help="不检查项目内容")
+            command.add_argument("--project", type=Path, default=None, help=_("项目目录；默认当前目录"))
+            command.add_argument("--no-project", action="store_true", help=_("不检查项目内容"))
 
-    check = sub.add_parser("check", help="只读检查插件、模板/样例与 Opinion 是否落后于云端")
+    check = sub.add_parser("check", help=_("只读检查插件、模板/样例与 Opinion 是否落后于云端"))
     common(check)
-    check.add_argument("--offline", action="store_true", help="只用缓存，不联网")
-    check.add_argument("--refresh", action="store_true", help="忽略一天的缓存，立即联网")
-    check.add_argument("--hook", action="store_true", help="会话开始时静默调用：有更新才输出一行")
+    check.add_argument("--offline", action="store_true", help=_("只用缓存，不联网"))
+    check.add_argument("--refresh", action="store_true", help=_("忽略一天的缓存，立即联网"))
+    check.add_argument("--hook", action="store_true", help=_("会话开始时静默调用：有更新才输出一行"))
     check.add_argument("--hook-format", choices=("text", "claude-hook"), default="text")
-    check.add_argument("--strict", action="store_true", help="有可更新项时退出码为 1（CI 用）")
-
-    install = sub.add_parser("install", help="经各客户端的原生市场安装 agenthelm 插件（默认预览）")
+    check.add_argument("--strict", action="store_true", help=_("有可更新项或脚手架差异时退出码为 1（CI 用）"))
+    check.add_argument("--show-skipped", action="store_true", help=_("列出被你跳过的项及理由"))
+    check.add_argument("--reprompt", action="store_true", help=_("忽略已记录的决定，重新评估全部脚手架差异"))
+    check.add_argument("--fingerprint", action="store_true",
+                       help=_("输出脚手架指纹（骨架状态 + 受检 Profile 字段 + 内容锁 + 命名规则；不含 Opinion、自有字段、已跳过项）"))
+    check.add_argument("--explain", nargs="?", const="-", metavar=_("对方的 JSON"),
+                       help=_("与 --fingerprint 合用：不带参数时逐项列出这台的明细；带另一台机器 check --fingerprint "
+                            "--output json 的输出文件时，指出两台差在哪里（有差异退出码 1）"))
+
+    install = sub.add_parser("install", help=_("经各客户端的原生市场安装 agenthelm 插件（默认预览）"))
     common(install, project=False)
-    install.add_argument("--client", action="append", choices=CLIENTS, help="默认安装到检测到的全部客户端")
-    install.add_argument("--plugin", action="append", help="默认安装全部插件")
-    install.add_argument("--source", type=Path, help="Cursor 安装用的本地仓库（默认下载发布包）")
-    install.add_argument("--marketplace-source", help="市场来源（默认 latest.json 的 GitHub 仓库；可用镜像或本地路径）")
+    install.add_argument("--client", action="append", choices=CLIENTS, help=_("默认安装到检测到的全部客户端"))
+    install.add_argument("--plugin", action="append", help=_("默认安装全部插件"))
+    install.add_argument("--source", type=Path, help=_("Cursor 安装用的本地仓库（默认下载发布包）"))
+    install.add_argument("--marketplace-source", help=_("市场来源（默认 latest.json 的 GitHub 仓库；可用镜像或本地路径）"))
     install.add_argument("--apply", action="store_true")
 
-    update = sub.add_parser("update", help="更新落后的插件与模板/样例（默认预览，确认后 --apply）")
+    update = sub.add_parser("update", help=_("更新落后的插件与模板/样例（默认预览，确认后 --apply）"))
     common(update)
     update.add_argument("--only", choices=("plugins", "content"))
-    update.add_argument("--accept", action="append", default=[], help="内容更新：用新模板替换这个本地已改动的文件")
-    update.add_argument("--keep", action="append", default=[], help="内容更新：保留这个文件的本地内容")
-    update.add_argument("--recovery-dir", type=Path, help="被替换文件的备份目录（项目外）")
-    update.add_argument("--source", type=Path, help="Cursor 更新用的本地仓库（默认下载发布包）")
+    update.add_argument("--accept", action="append", default=[], help=_("内容更新：用新模板替换这个本地已改动的文件"))
+    update.add_argument("--keep", action="append", default=[], help=_("内容更新：保留这个文件的本地内容"))
+    update.add_argument("--recovery-dir", type=Path, help=_("被替换文件的备份目录（项目外）"))
+    update.add_argument("--source", type=Path, help=_("Cursor 更新用的本地仓库（默认下载发布包）"))
     update.add_argument("--apply", action="store_true")
 
-    migrate = sub.add_parser("migrate", help="把旧方式安装（agent-pack 复制 + 软链）迁到市场安装（默认预览）")
+    migrate = sub.add_parser("migrate", help=_("把旧方式安装（agent-pack 复制 + 软链）迁到市场安装（默认预览）"))
     common(migrate, project=False)
-    migrate.add_argument("--install", action="store_true", help="先经市场安装到检测到的客户端")
+    migrate.add_argument("--install", action="store_true", help=_("先经市场安装到检测到的客户端"))
     migrate.add_argument("--client", action="append", choices=CLIENTS)
     migrate.add_argument("--source", type=Path)
     migrate.add_argument("--marketplace-source")
     migrate.add_argument("--apply", action="store_true")
 
-    doctor_parser = sub.add_parser("doctor", help="报告重复安装、版本不一致、旧方式残留与检查开关")
+    doctor_parser = sub.add_parser("doctor", help=_("报告重复安装、版本不一致、旧方式残留与检查开关"))
     common(doctor_parser)
 
+    sub.add_parser("fix", add_help=False,
+                   help=_("修复项目脚手架差异与更新（等同 project fix；默认预览，--apply 写入；--skip/--unskip 记录决定）"))
+    sub.add_parser("local-only", add_help=False,
+                   help=_("只属于这台机器的目录（.venv、node_modules、缓存）不进云同步盘：check / fix / config（详见 local-only --help）"))
     sub.add_parser("runtime", add_help=False,
-                   help="用户级运行时：install / update / use / status（日常只需要 Python，不经过 npx）")
+                   help=_("用户级运行时：install / update / use / status（日常只需要 Python，不经过 npx）"))
     sub.add_parser("project", add_help=False,
-                   help="项目自助入口：找资料、看进展、项目指南、检查（不需要 AI Agent；详见 project --help）")
-    locate_parser = sub.add_parser("locate", help="输出插件的已安装位置（最新优先），供下游脚本查找")
+                   help=_("项目自助入口：找资料、看进展、项目指南、检查（不需要 AI Agent；详见 project --help）"))
+    locate_parser = sub.add_parser("locate", help=_("输出插件的已安装位置（最新优先），供下游脚本查找"))
     locate_parser.add_argument("plugin")
-    locate_parser.add_argument("--version", help="只要这个版本")
+    locate_parser.add_argument("--version", help=_("只要这个版本"))
     locate_parser.add_argument("--include-legacy", action="store_true",
-                               help="也列出旧方式安装（默认不列，避免清理后才失效）")
+                               help=_("也列出旧方式安装（默认不列，避免清理后才失效）"))
     locate_parser.add_argument("--output", choices=("text", "json"), default="json")
     locate_parser.add_argument("--home", type=Path, help=argparse.SUPPRESS)
     return result
 
 
 def _print_steps(results: list[dict], apply: bool) -> None:
-    labels = {"preview": "预览", "applied": "完成", "blocked": "阻塞", "failed": "失败"}
+    labels = {"preview": _("预览"), "applied": _("完成"), "blocked": _("阻塞"), "failed": _("失败")}
     for record in results:
         line = f"  [{labels.get(record['status'], record['status'])}] {record['description']}"
         if record.get("command"):
@@ -1036,7 +1276,7 @@ def _print_steps(results: list[dict], apply: bool) -> None:
                 line += f"\n      {result['hint']}"
         print(line)
     if not apply and results:
-        print("以上为预览；确认后追加 --apply 执行。")
+        print(_("以上为预览；确认后追加 --apply 执行。"))
 
 
 def run_project(argv: list[str]) -> int:
@@ -1047,9 +1287,8 @@ def run_project(argv: list[str]) -> int:
     usable = [path for path in copies if (path / "runtime" / "project_cli.py").is_file()]
     if not usable:
         stale = any((path / "plugin.json").is_file() for path in copies)
-        found = "（已安装的 project-orchestrator 版本过旧）" if stale else ""
-        print(f"agenthelm project 需要 project-orchestrator 的项目入口，但没有找到{found}。\n"
-              f"  · 更新插件：{CLI} update，或从发布包安装运行时（见 INSTALL.md）", file=sys.stderr)
+        found = _("（已安装的 project-orchestrator 版本过旧）") if stale else ""
+        print(_("agenthelm project 需要 project-orchestrator 的项目入口，但没有找到{0}。\n  · 更新插件：{1} update，或从发布包安装运行时（见 INSTALL.md）").format(found, CLI), file=sys.stderr)
         return 3
     # Prefer the copy shipped next to this agent-pack (same release), then the newest installed one.
     sibling = PLUGIN_ROOT.parent / "project-orchestrator"
@@ -1062,6 +1301,19 @@ def run_project(argv: list[str]) -> int:
     return project_cli.main(argv)
 
 
+def run_nudge(argv: list[str]) -> int:
+    """``agenthelm nudge``: hooks that collect opinion candidates and surface unconfirmed items."""
+    sys.path.insert(0, str(RUNTIME_DIR))
+    import agent_pack_nudge  # noqa: PLC0415 - shipped next to this file
+
+    return agent_pack_nudge.main(argv, sys.modules[__name__])
+
+
+def run_local_only(argv: list[str]) -> int:
+    """``agenthelm local-only``: keep rebuildable directories out of cloud-synced folders."""
+    return _local_only().main(argv, sys.modules[__name__])
+
+
 def run_runtime(argv: list[str]) -> int:
     """``agenthelm runtime``: the user-level runtime that project launchers use without any AI client."""
     sys.path.insert(0, str(RUNTIME_DIR))
@@ -1070,12 +1322,70 @@ def run_runtime(argv: list[str]) -> int:
     return agenthelm_runtime.main(argv, sys.modules[__name__])
 
 
+def print_fingerprint(env: Env, report: dict, args: argparse.Namespace, project: Path | None = None) -> int:
+    """``check --fingerprint [--explain [file]]``: the scaffold fingerprint, and where two machines differ."""
+    result = scaffold_fingerprint(env, report.get("scaffold"))
+    if result is None:
+        reason = (report.get("scaffold") or {}).get("error") or _("当前目录不在 agenthelm 项目里")
+        print(json.dumps({"ok": False, "error": reason}, ensure_ascii=False) if args.output == "json"
+              else _("无法计算脚手架指纹：{0}").format(reason), file=sys.stderr if args.output != "json" else sys.stdout)
+        return 4
+    payload: dict = {"ok": True, "fingerprint": result["fingerprint"], "detail": result["detail"]}
+    lines = [_("脚手架指纹 {0}").format(result['fingerprint'])]
+    mine_local: dict = {}
+    if project is not None:
+        # 本机环境（外置链接、HOME）单独成段：没有 local-only 配置的项目，输出与以前完全一样。
+        mine_local = local_only_report(env, project, mode="quick")["fingerprint"]
+        if mine_local["detail"]:
+            payload["local_only"] = mine_local
+            lines.append(_("本机环境指纹 {0}").format(mine_local['fingerprint']))
+    differences: list[str] = []
+    if args.explain and args.explain != "-":
+        try:
+            other = read_json(Path(args.explain).expanduser())
+        except (OSError, ValueError) as exc:
+            print(_("读不了对方的输出：{0}").format(exc), file=sys.stderr)
+            return 2
+        theirs = other.get("detail") or (other.get("scaffold_fingerprint") or {}).get("detail") or other.get("fingerprint", {}).get("detail")
+        if not isinstance(theirs, dict):
+            print(_("对方的文件里没有指纹明细：请在对方机器运行 agenthelm check --fingerprint --output json 并保存输出"), file=sys.stderr)
+            return 2
+        module = scaffold_module(env)
+        differences = module.explain(result["detail"], theirs)
+        their_local = (other.get("local_only") or {}).get("detail") or {}
+        if mine_local.get("detail") or their_local:
+            if not their_local:
+                differences.append(_("本机环境：对方没有 local-only 明细（对方的 agent-pack 较旧或项目还没配置）"))
+            elif not mine_local.get("detail"):
+                differences.append(_("本机环境：这台没有 local-only 配置，对方有"))
+            else:
+                differences += _local_only().explain(mine_local["detail"], their_local)
+        payload["same"] = not differences
+        payload["differences"] = differences
+        lines.append(_("两台机器的脚手架一致。") if not differences else _("有 {0} 处不同：").format(len(differences)))
+        lines += [f"  {item}" for item in differences]
+    elif args.explain:
+        lines += [f"  {key} = {value}" for key, value in result["detail"].items()]
+        lines += [f"  local-only {key} = {value}" for key, value in mine_local.get("detail", {}).items()]
+    if args.output == "json":
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print("\n".join(lines))
+    return 1 if differences else 0
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
     if argv[:1] == ["project"]:
         return run_project(argv[1:])
+    if argv[:1] == ["fix"]:
+        return run_project(["fix", *argv[1:]])
     if argv[:1] == ["runtime"]:
         return run_runtime(argv[1:])
+    if argv[:1] == ["nudge"]:
+        return run_nudge(argv[1:])
+    if argv[:1] == ["local-only"]:
+        return run_local_only(argv[1:])
     args = parser().parse_args(argv)
     env = current_env(args.home)
     home = env.home
@@ -1094,12 +1404,14 @@ def main(argv: list[str] | None = None) -> int:
     try:
         if args.command == "check":
             report = run_check(env, project, latest_source=args.latest, offline=args.offline,
-                               max_age=0 if args.refresh else CACHE_TTL_SECONDS)
+                               max_age=0 if args.refresh else CACHE_TTL_SECONDS, reprompt=args.reprompt)
             report.pop("_latest")
+            if args.fingerprint or args.explain:
+                return print_fingerprint(env, report, args, project)
             if args.output == "json":
                 print(json.dumps(report, ensure_ascii=False, indent=2))
             else:
-                sys.stdout.write(render_text(report))
+                sys.stdout.write(render_text(report, show_skipped=args.show_skipped))
             return 1 if args.strict and not report["summary"]["up_to_date"] else 0
         if args.command == "doctor":
             result = doctor(env, run_check(env, project, latest_source=args.latest))
@@ -1110,9 +1422,9 @@ def main(argv: list[str] | None = None) -> int:
                     print(f"  [{issue['issue']}] {issue.get('plugin') or ''} {issue['detail']}".rstrip())
                 for item in result["legacy"]:
                     print(f"  [legacy] {item['kind']} {item['name']}: {item['path']}")
-                print("没有发现问题。" if result["ok"] and not result["legacy"] else "")
+                print(_("没有发现问题。") if result["ok"] and not result["legacy"] else "")
             return 0 if result["ok"] else 1
-        latest, _ = load_latest(env, args.latest, max_age=0)
+        latest, _origin = load_latest(env, args.latest, max_age=0)
         if args.command == "install":
             clients = args.client or detect_clients(env)
             plugins = args.plugin or sorted(latest.get("plugins", {}))
@@ -1133,7 +1445,7 @@ def main(argv: list[str] | None = None) -> int:
             payload = {"ok": all(r["status"] != "failed" for r in results), "applied": args.apply,
                        "steps": results, "summary": report["summary"]}
             if not steps:
-                payload["message"] = "没有需要更新的内容。"
+                payload["message"] = _("没有需要更新的内容。")
         else:  # migrate
             names = set(latest.get("plugins", {}))
             artifacts = legacy_artifacts(env, names)
@@ -1160,9 +1472,9 @@ def main(argv: list[str] | None = None) -> int:
             print(payload["message"])
         _print_steps(payload["steps"], args.apply)
         for item in payload.get("legacy", []):
-            print(f"  [旧安装] {item['kind']} {item['name']}: {item['path']}" + ("（需手动处理）" if item.get("manual") else ""))
+            print(_("  [旧安装] {0} {1}: {2}").format(item['kind'], item['name'], item['path']) + (_("（需手动处理）") if item.get("manual") else ""))
         if payload.get("recovery"):
-            print(f"旧安装已移入：{payload['recovery']}（含 migration.json 清单，可按清单恢复）")
+            print(_("旧安装已移入：{0}（含 migration.json 清单，可按清单恢复）").format(payload['recovery']))
     return 0 if payload["ok"] else 1