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

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

@@ -23,12 +23,13 @@ import tempfile
 from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
+from i18n_agent_pack import _  # noqa: E402
 
 PLUGINS = ("agent-pack", "agents-init", "opinion-manager", "project-orchestrator")
 SKIP_PARTS = {"tests", "__pycache__", ".DS_Store", "node_modules"}
 MANIFEST = "runtime.json"
 SHIM = """#!/bin/sh
-# agenthelm 运行时 {version}（agenthelm runtime install 生成）。只需要 Python 3.11+，不需要 AI 客户端。
+# agenthelm runtime {version} (generated by agenthelm runtime install). Needs only Python 3.11+, no AI client.
 self=$0
 while [ -L "$self" ]; do  # a command link (--link-bin) points here; follow it to the runtime
   link=$(readlink "$self")
@@ -42,15 +43,19 @@ for candidate in "${{AGENTHELM_PYTHON:-}}" python3 python; do
     exec "$candidate" "$here/plugins/agent-pack/runtime/agenthelm.py" "$@"
   fi
 done
-echo "agenthelm 需要 Python 3.11 或更高版本：安装后重试，或设置 AGENTHELM_PYTHON。" >&2
+case "${{AGENTHELM_LANG:-${{LC_ALL:-${{LANG:-}}}}}}" in
+  zh*) echo "agenthelm 需要 Python 3.11 或更高版本：安装后重试，或设置 AGENTHELM_PYTHON。" >&2 ;;
+  *) echo "agenthelm needs Python 3.11 or newer: install it and retry, or set AGENTHELM_PYTHON." >&2 ;;
+esac
 exit 3
 """
 
 
 class RuntimeInstallError(Exception):
-    def __init__(self, message: str, next_steps: list[str] | None = None) -> None:
+    def __init__(self, message: str, next_steps: list[str] | None = None, *, download: bool = False) -> None:
         super().__init__(message)
         self.next_steps = next_steps or []
+        self.download = download
 
 
 # ---------------------------------------------------------------- locations
@@ -110,12 +115,12 @@ def _shipped_files(root: Path) -> list[Path]:
 
 def describe(root: Path) -> dict:
     if not _is_release_root(root):
-        raise RuntimeInstallError(f"{root} 不是 agenthelm 发布内容（缺少 index.json 或 plugins/<插件>）",
-                            ["--source 指向仓库检出、解压后的发布包目录或 .tar.gz 发布包"])
+        raise RuntimeInstallError(_("{0} 不是 agenthelm 发布内容（缺少 index.json 或 plugins/<插件>）").format(root),
+                            [_("--source 指向仓库检出、解压后的发布包目录或 .tar.gz 发布包")])
     index = json.loads((root / "index.json").read_text(encoding="utf-8"))
     version = str(index.get("plugin", {}).get("version") or "")
     if not version:
-        raise RuntimeInstallError(f"{root}/index.json 没有发布版本号")
+        raise RuntimeInstallError(_("{0}/index.json 没有发布版本号").format(root))
     digest = hashlib.sha256()
     files = _shipped_files(root)
     for relative in files:
@@ -165,14 +170,14 @@ def command_status() -> dict:
 def missing_text(data: dict, commands: dict) -> dict:
     """Wording for “no user-level runtime installed”: says which commands work, instead of leaving “wf: not found” unexplained."""
     def state(name: str) -> str:
-        return f"{name} 在 PATH 上（{commands[name]}）" if commands.get(name) else f"终端里的 {name} 命令目前不可用"
+        return _("{0} 在 PATH 上（{1}）").format(name, commands[name]) if commands.get(name) else _("终端里的 {0} 命令目前不可用").format(name)
     return {
-        "reason": f"本次由 {data['running_from']} 提供；{state('agenthelm')}，{state('wf')}。",
-        "impact": "项目根目录的 ./menu 会通过客户端插件兜底，所以现在能用；"
+        "reason": _("本次由 {0} 提供；{1}，{2}。").format(data['running_from'], state('agenthelm'), state('wf')),
+        "impact": _("项目根目录的 ./menu 会通过客户端插件兜底，所以现在能用；"
                   "没有 AI 客户端或客户端插件被移除时打不开。wf 是单独的查找命令，运行时不会提供它："
-                  "用 ./menu find 词 或 agenthelm project find 词 代替",
-        "label": "安装运行时（agenthelm runtime install --apply，只写用户数据目录）；"
-                 "要在终端直接输入 agenthelm 时加 --link-bin ~/.local/bin（只链接 agenthelm，不含 wf）",
+                  "用 ./menu find 词 或 agenthelm project find 词 代替"),
+        "label": _("安装运行时（agenthelm runtime install --apply，只写用户数据目录）；"
+                 "要在终端直接输入 agenthelm 时加 --link-bin ~/.local/bin（只链接 agenthelm，不含 wf）"),
     }
 
 
@@ -199,15 +204,15 @@ def plan(env: Any, root: Path, origin: str, *, link_bin: Path | None = None) ->
     existing = _read_manifest(target)
     active = current(env)
     if existing and existing.get("digest") != info["digest"]:
-        raise RuntimeInstallError(f"运行时 {info['version']} 已安装，但内容与来源不同（来源：{origin}）",
-                            [f"已装：{target}；同一版本不会被改写",
-                             "确认要换掉时先手动移走该目录（例如移到 ~/.agent-pack/recovery/），再重新安装"])
+        raise RuntimeInstallError(_("运行时 {0} 已安装，但内容与来源不同（来源：{1}）").format(info['version'], origin),
+                            [_("已装：{0}；同一版本不会被改写").format(target),
+                             _("确认要换掉时先手动移走该目录（例如移到 ~/.agent-pack/recovery/），再重新安装")])
     writes = []
     if not existing:
-        writes.append({"path": str(target), "scope": "用户数据目录（新版本，旧版本保留）"})
+        writes.append({"path": str(target), "scope": _("用户数据目录（新版本，旧版本保留）")})
     switch = not active or active.get("version") != info["version"]
     if switch:
-        writes.append({"path": str(current_link(env)), "scope": f"切换当前版本 → {info['version']}"})
+        writes.append({"path": str(current_link(env)), "scope": _("切换当前版本 → {0}").format(info['version'])})
     link = None
     if link_bin is not None:
         link = link_bin.expanduser() / "agenthelm"
@@ -215,9 +220,9 @@ def plan(env: Any, root: Path, origin: str, *, link_bin: Path | None = None) ->
         if link.is_symlink() and Path(os.readlink(link)) == expected:
             link = None
         elif link.exists() or link.is_symlink():
-            raise RuntimeInstallError(f"{link} 已存在且不是本运行时的链接，不会覆盖", ["换一个 --link-bin 目录，或手动处理该文件"])
+            raise RuntimeInstallError(_("{0} 已存在且不是本运行时的链接，不会覆盖").format(link), [_("换一个 --link-bin 目录，或手动处理该文件")])
         else:
-            writes.append({"path": str(link), "scope": "命令链接（指向当前运行时）"})
+            writes.append({"path": str(link), "scope": _("命令链接（指向当前运行时）")})
     return {"version": info["version"], "plugins": info["plugins"], "digest": info["digest"], "source": origin,
             "target": str(target), "install": not existing, "switch": switch,
             "previous": active.get("version") if active else None, "link": str(link) if link else None,
@@ -237,7 +242,7 @@ def apply(env: Any, planned: dict, root: Path) -> dict:
                 shutil.copy2(root / relative, destination)
             shutil.copy2(root / "index.json", staging / "index.json")
             if describe(staging)["digest"] != planned["digest"]:
-                raise RuntimeInstallError("复制后的内容与来源摘要不一致，已放弃安装")
+                raise RuntimeInstallError(_("复制后的内容与来源摘要不一致，已放弃安装"))
             shim = staging / "bin" / "agenthelm"
             shim.parent.mkdir()
             shim.write_text(SHIM.format(version=planned["version"]), encoding="utf-8")
@@ -260,8 +265,8 @@ def apply(env: Any, planned: dict, root: Path) -> dict:
     shim = current_link(env) / "bin" / "agenthelm"
     verified = bool(active and active["version"] == planned["version"] and os.access(shim, os.X_OK))
     return {"ok": verified, "version": planned["version"], "current": active,
-            "verify": (f"重新读取：当前运行时 {planned['version']}，命令 {shim}" if verified
-                       else "回读不一致：请运行 agenthelm runtime status 查看"),
+            "verify": (_("重新读取：当前运行时 {0}，命令 {1}").format(planned['version'], shim) if verified
+                       else _("回读不一致：请运行 agenthelm runtime status 查看")),
             "rollback": f"agenthelm runtime use {planned['previous']} --apply" if planned["previous"]
             and planned["previous"] != planned["version"] else None}
 
@@ -278,8 +283,8 @@ def _switch(env: Any, target: Path) -> None:
 def use(env: Any, version: str, *, apply_change: bool) -> dict:
     target = runtimes_dir(env) / version
     if not _read_manifest(target):
-        versions = "、".join(item["version"] for item in installed(env)) or "（无）"
-        raise RuntimeInstallError(f"没有安装运行时 {version}", [f"已安装：{versions}"])
+        versions = _("、").join(item["version"] for item in installed(env)) or _("（无）")
+        raise RuntimeInstallError(_("没有安装运行时 {0}").format(version), [_("已安装：{0}").format(versions)])
     active = current(env)
     result = {"version": version, "previous": active.get("version") if active else None, "applied": False}
     if apply_change:
@@ -300,45 +305,45 @@ def resolve_source(host: Any, env: Any, args: argparse.Namespace, workdir: Path,
             host._safe_extract(source, extracted)
             roots = [path for path in extracted.iterdir() if path.is_dir()]
             if len(roots) != 1:
-                raise RuntimeInstallError("发布包结构不符合预期")
-            return roots[0], f"本地发布包 {source.name}"
-        return source, f"本地目录 {source}"
+                raise RuntimeInstallError(_("发布包结构不符合预期"))
+            return roots[0], _("本地发布包 {0}").format(source.name)
+        return source, _("本地目录 {0}").format(source)
     bundled = bundled_root()
     if bundled is not None and not prefer_release and not args.from_release:
-        return bundled, f"随附内容（{running_from(env)}）"
+        return bundled, _("随附内容（{0}）").format(running_from(env))
     try:
-        latest, _ = host.load_latest(env, args.latest, max_age=0)
-        return host.release_source(latest, workdir), "GitHub Release（已核对摘要）"
+        latest, _origin = host.load_latest(env, args.latest, max_age=0)
+        return host.release_source(latest, workdir), _("GitHub Release（已核对摘要）")
     except (host.CheckError, OSError, ValueError) as exc:
-        raise RuntimeInstallError(f"无法下载发布包：{exc}",
-                            ["离线时用 --source 指向发布包（.tar.gz）或仓库检出",
-                             "下载地址见 https://github.com/lc4t/agenthelm/releases"]) from exc
+        raise RuntimeInstallError(_("无法下载发布包：{0}").format(exc),
+                            [_("离线时用 --source 指向发布包（.tar.gz）或仓库检出"),
+                             _("下载地址见 https://github.com/lc4t/agenthelm/releases")], download=True) from exc
 
 
 # ---------------------------------------------------------------- command line
 
 def parser() -> argparse.ArgumentParser:
-    result = argparse.ArgumentParser(prog="agenthelm runtime", description=__doc__.split("\n\n")[0])
+    result = argparse.ArgumentParser(prog="agenthelm runtime", description=_("agenthelm 用户级运行时：把四个插件的确定性工具装进用户数据目录，日常只需要 Python 3.11+。"))
     sub = result.add_subparsers(dest="action", required=True)
-    for name, text in (("status", "当前运行时、已装版本与可用更新"),
-                       ("install", "安装运行时（默认用本命令随附的内容；默认预览）"),
-                       ("update", "联网安装最新发布版本并切换（默认预览）"),
-                       ("use", "切换到已安装的某个版本（默认预览）")):
+    for name, text in (("status", _("当前运行时、已装版本与可用更新")),
+                       ("install", _("安装运行时（默认用本命令随附的内容；默认预览）")),
+                       ("update", _("联网安装最新发布版本并切换（默认预览）")),
+                       ("use", _("切换到已安装的某个版本（默认预览）"))):
         command = sub.add_parser(name, help=text)
         command.add_argument("--output", choices=("text", "json"), default="text")
         command.add_argument("--home", type=Path, help=argparse.SUPPRESS)
-        command.add_argument("--latest", help="latest.json 的 URL 或本地路径")
+        command.add_argument("--latest", help=_("latest.json 的 URL 或本地路径"))
         if name == "use":
             command.add_argument("version")
         if name in ("install", "update"):
-            command.add_argument("--source", type=Path, help="本地目录或 .tar.gz 发布包（离线安装）")
-            command.add_argument("--link-bin", type=Path, help="在这个目录建 agenthelm 命令链接（例如 ~/.local/bin）")
+            command.add_argument("--source", type=Path, help=_("本地目录或 .tar.gz 发布包（离线安装）"))
+            command.add_argument("--link-bin", type=Path, help=_("在这个目录建 agenthelm 命令链接（例如 ~/.local/bin）"))
         if name == "install":
-            command.add_argument("--from-release", action="store_true", help="联网下载发布包，而不用随附内容")
+            command.add_argument("--from-release", action="store_true", help=_("联网下载发布包，而不用随附内容"))
         if name != "status":
             command.add_argument("--apply", action="store_true")
         if name == "status":
-            command.add_argument("--offline", action="store_true", help="只用缓存的版本信息")
+            command.add_argument("--offline", action="store_true", help=_("只用缓存的版本信息"))
     return result
 
 
@@ -353,55 +358,55 @@ def main(argv: list[str], host: Any) -> int:
     args = parser().parse_args(argv)
     env = host.current_env(args.home)
     if sys.platform == "win32":
-        print("agenthelm runtime 目前只支持 macOS 与 Linux。", file=sys.stderr)
+        print(_("agenthelm runtime 目前只支持 macOS 与 Linux。"), file=sys.stderr)
         return 4
     try:
         if args.action == "status":
             try:
-                latest, _ = host.load_latest(env, args.latest, offline=args.offline)
+                latest, _origin = host.load_latest(env, args.latest, offline=args.offline)
             except (host.CheckError, OSError, ValueError):
                 latest = None
             data = report(env, latest)
             active = data["current"]
-            lines = [f"当前运行时：{active['version']}（{active['path']}）" if active else "当前运行时：未安装",
-                     f"已安装：{'、'.join(item['version'] for item in data['installed']) or '（无）'}",
-                     f"本次命令来自：{data['running_from']}"]
+            lines = [_("当前运行时：{0}（{1}）").format(active['version'], active['path']) if active else _("当前运行时：未安装"),
+                     _("已安装：{0}").format(_('、').join(item['version'] for item in data['installed']) or _('（无）')),
+                     _("本次命令来自：{0}").format(data['running_from'])]
             if data["update_available"]:
-                lines.append(f"有新版本 {data['latest_release']}：agenthelm runtime update 预览")
+                lines.append(_("有新版本 {0}：agenthelm runtime update 预览").format(data['latest_release']))
             if not active:
-                lines.append("安装：agenthelm runtime install（预览）→ 加 --apply 执行")
+                lines.append(_("安装：agenthelm runtime install（预览）→ 加 --apply 执行"))
             _print({"ok": True, **data}, args.output, lines)
             return 0
         if args.action == "use":
             result = use(env, args.version, apply_change=args.apply)
-            lines = [f"{'已切换' if result['applied'] else '将切换'}：{result['previous']} → {result['version']}"]
+            lines = [_("{0}：{1} → {2}").format(_('已切换') if result['applied'] else _('将切换'), result['previous'], result['version'])]
             if not args.apply:
-                lines.append("以上为预览；加 --apply 执行。")
+                lines.append(_("以上为预览；加 --apply 执行。"))
             _print({"ok": True, **result}, args.output, lines)
             return 0
         with tempfile.TemporaryDirectory(prefix="agenthelm-runtime-") as temporary:
             root, origin = resolve_source(host, env, args, Path(temporary), prefer_release=args.action == "update")
             planned = plan(env, root, origin, link_bin=args.link_bin)
-            lines = [f"运行时 {planned['version']}（来源：{origin}）"]
-            lines += [f"  将写入：{item['path']}（{item['scope']}）" for item in planned["writes"]] or ["  已是当前版本，无需改动。"]
+            lines = [_("运行时 {0}（来源：{1}）").format(planned['version'], origin)]
+            lines += [_("  将写入：{0}（{1}）").format(item['path'], item['scope']) for item in planned["writes"]] or [_("  已是当前版本，无需改动。")]
             if not args.apply or planned["action"] == "none" and not planned["link"]:
                 if args.apply is False and planned["writes"]:
-                    lines.append("以上为预览；加 --apply 执行。")
+                    lines.append(_("以上为预览；加 --apply 执行。"))
                 _print({"ok": True, "applied": False, "plan": planned}, args.output, lines)
                 return 0
             result = apply(env, planned, root)
         lines.append(("  " + result["verify"]))
         if result["rollback"]:
-            lines.append(f"  回到旧版本：{result['rollback']}")
+            lines.append(_("  回到旧版本：{0}").format(result['rollback']))
         if not os.environ.get("PATH", "").count(str(current_link(env) / "bin")) and not planned["link"]:
-            lines.append(f"  直接用命令：把 {current_link(env) / 'bin'} 加入 PATH，或重新运行并加 --link-bin ~/.local/bin")
+            lines.append(_("  直接用命令：把 {0} 加入 PATH，或重新运行并加 --link-bin ~/.local/bin").format(current_link(env) / 'bin'))
         _print({"ok": result["ok"], "applied": True, "plan": planned, **result}, args.output, lines)
         return 0 if result["ok"] else 6
     except RuntimeInstallError as exc:
         if args.output == "json":
             print(json.dumps({"ok": False, "error": str(exc), "next": exc.next_steps}, ensure_ascii=False, indent=2))
         else:
-            print(f"出错：{exc}", file=sys.stderr)
+            print(_("出错：{0}").format(exc), file=sys.stderr)
             for step in exc.next_steps:
                 print(f"  · {step}", file=sys.stderr)
-        return 4 if "无法下载" in str(exc) else 2
+        return 4 if exc.download else 2

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

@@ -0,0 +1,78 @@
+"""运行时文案的多语言：源语言是中文，``_("中文原文")`` 在中文下原样返回，在英文下查 ``locale/en.json``。
+
+语言按这个顺序决定：调用方指定（如 ``nudge.language``）→ 环境变量 ``AGENTHELM_LANG`` → 用户配置
+``~/.config/agenthelm/config.json`` 的 ``language`` → 系统 locale（``LC_ALL``、``LC_MESSAGES``、``LANG``）→ 英文。
+``auto``、空值和 C/POSIX 视为未指定；中文 locale 用中文，其他语言的 locale 暂用英文。
+没有英文译文的文案原样输出（中文），测试守住译文完整。四个插件各带一份相同的本模块（模块名不同，以免
+同一进程里互相覆盖），``tests/test_i18n_parity.py`` 守住它们行为一致。模块级常量里的文案用 ``N_`` 标记
+（原样返回，仅供提取），使用处再调用 ``_``，这样语言在运行时而不是导入时决定。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Mapping
+
+LANGUAGES = ("zh", "en")
+DEFAULT_LANGUAGE = "en"
+LOCALE_DIR = Path(__file__).resolve().parent / "locale"
+_catalogs: dict[str, dict[str, str]] = {}
+_configured: dict[str, tuple[tuple, str | None]] = {}
+
+
+def normalize(value: object) -> str | None:
+    text = str(value or "").strip().lower().replace("_", "-")
+    if not text or text in ("auto", "c", "posix") or text.startswith(("c.", "posix.")):
+        return None
+    return "zh" if text.startswith("zh") else "en"
+
+
+def configured_language(environ: Mapping[str, str]) -> str | None:
+    """用户配置里的 language；按文件修改时间缓存，读不了就当没有。"""
+    base = environ.get("XDG_CONFIG_HOME") or (str(Path(environ["HOME"]) / ".config") if environ.get("HOME") else "")
+    if not base:
+        return None
+    path = Path(base) / "agenthelm" / "config.json"
+    try:
+        info = path.stat()
+        signature = (info.st_mtime_ns, info.st_size)
+        cached = _configured.get(str(path))
+        if cached and cached[0] == signature:
+            return cached[1]
+        data = json.loads(path.read_text(encoding="utf-8"))
+        value = normalize(data.get("language")) if isinstance(data, dict) else None
+    except (OSError, ValueError):
+        return None
+    _configured[str(path)] = (signature, value)
+    return value
+
+
+def resolve_language(requested: str | None = None, environ: Mapping[str, str] | None = None) -> str:
+    environ = os.environ if environ is None else environ
+    for candidate in (requested, environ.get("AGENTHELM_LANG"), configured_language(environ),
+                      environ.get("LC_ALL"), environ.get("LC_MESSAGES"), environ.get("LANG")):
+        language = normalize(candidate)
+        if language:
+            return language
+    return DEFAULT_LANGUAGE
+
+
+def catalog(language: str) -> dict[str, str]:
+    if language not in _catalogs:
+        try:
+            data = json.loads((LOCALE_DIR / f"{language}.json").read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            data = {}
+        _catalogs[language] = data if isinstance(data, dict) else {}
+    return _catalogs[language]
+
+
+def _(message: str) -> str:
+    language = resolve_language()
+    return message if language == "zh" else catalog(language).get(message, message)
+
+
+def N_(message: str) -> str:
+    return message