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

package/runtime/plugins/opinion-manager/references/inbox.en.md

@@ -0,0 +1,48 @@
+# Candidate inbox (inbox)
+
+**English** · [简体中文](inbox.md)
+
+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.
+
+## Location and privacy
+
+- File: `.opinion/inbox.json` inside the project (a project-private directory, like `.opinion/profiles`).
+- **It holds the user's own words, which may contain sensitive information.** Projects that use this feature should stay private, or at least stay out of public channels. If you want to make the repository public, sync it to a shared folder or let others see it, whether to exclude `.opinion/` and its contents is your decision. The tool only reminds you; it does not decide for you and never edits `.gitignore`, deletes or rewrites anything.
+- When you are reminded: the first `add` that creates the inbox returns a `notice` (the Agent passes it on to you); each project gets one reminder when a session starts (the `nudge` hook); `inbox exposure` or `agenthelm nudge status` shows the current state at any time (ignored by Git / tracked by Git / not ignored / not a Git repository). Nothing is shown once Git ignores the file.
+- Symbolic links are refused; read-modify-write holds `.opinion/.inbox.lock`, so several sessions can stash at the same time without losing entries.
+
+## Statuses
+
+- `pending`: waits for confirmation and is not in effect yet.
+- `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`.
+- `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.
+- `held`: put aside, no more reminders.
+- `rejected`: discarded.
+
+## Commands
+
+All commands are `opinion_manager.py inbox <action>`, and `--project` is required. `--lang zh|en` selects the message language (by default `AGENTHELM_LANG`, then the system locale, then English). Output is JSON; `list --output markdown` gives a numbered list for the user.
+
+- `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.
+- `list [--status a,b] [--session ID] [--unpresented]`: list candidates.
+- `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.
+- `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).
+- `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".
+- `pending [--session ID]`: the pending-item provider, see below.
+- `exposure`: read-only; reports the Git state of `.opinion/inbox.json` and the reminder text.
+- `brief [--session ID] [--max-chars N]`: builds the protocol and the full text of trial candidates injected at session start; the default limit is 6000 characters.
+
+## Pending-item provider contract
+
+agent-pack's session-start check aggregates every source with the same structure (opinion candidates, and later SOP to-dos and so on). A provider returns:
+
+```json
+{"ok": true, "source": "opinion",
+ "items": [{"id": "cand-20261029-001", "source": "opinion", "kind": "candidate", "title": "…",
+            "status": "pending", "created_at": "…Z", "last_action_at": "…Z", "age_days": 3.2,
+            "hint_command": "the command that handles this item"}],
+ "counts": {"pending": 2, "trial": 1, "formal": 0, "held": 0, "rejected": 0},
+ "oldest_pending_days": 3.2, "last_action_at": "…Z", "session_unpresented": ["cand-…"]}
+```
+
+Items whose `status` is `pending` count toward the reminder thresholds; `age_days` is measured from `last_action_at` (the user's last action, creation time when there is none). A provider is read-only and never changes state while reading.

package/runtime/plugins/opinion-manager/references/inbox.md

@@ -0,0 +1,48 @@
+# 候选收件箱（inbox）
+
+[English](inbox.en.md) · **简体中文**
+
+收件箱保存 Agent 在工作中发现的、尚待用户裁决的观点。它不是规则：不写入 `OPINION.md`、Profile 或锁，也不改变任何已确认内容。暂存无需确认，所有状态变化都需要用户明确表态。
+
+## 位置与隐私
+
+- 文件：项目内的 `.opinion/inbox.json`（与 `.opinion/profiles` 同属项目私有目录）。
+- **含用户原话，可能含敏感信息。**启用本功能的项目建议保持私有（至少不要放进公开渠道）。若要公开仓库、同步到共享目录或让他人看到，是否排除 `.opinion/` 及其中内容由你决定；工具只提醒，不会替你决定，也不会自动修改 `.gitignore`、删除或改写任何内容。
+- 提醒的时机：第一次 `add` 创建收件箱时，返回里带 `notice`（Agent 会转告你）；会话开始时每个项目提醒一次（`nudge` 的 hook）；`inbox exposure` 或 `agenthelm nudge status` 随时查看当前状态（已被 Git 忽略 / 已被跟踪 / 未被忽略 / 不是 Git 仓库）。已被 Git 忽略时不再提醒。
+- 拒绝符号链接；读改写持有 `.opinion/.inbox.lock`，多个会话同时暂存不会丢失。
+
+## 状态
+
+- `pending`：待确认，尚未生效。
+- `trial`：用户同意在本项目试行。hook 会把试行候选的全文随协议注入会话，Agent 按其工作；超过 `nudge.trial_expire_days`（默认 30）未转正回到 `pending`。
+- `formal`：用户同意转为正式规则。这里只记录意愿，写入 `OPINION.md` 仍走完整预览与确认。
+- `held`：暂缓，不再提示。
+- `rejected`：丢弃。
+
+## 命令
+
+以下命令都在 `opinion_manager.py inbox <动作>` 下，`--project` 必填；`--lang zh|en` 指定提示语言（缺省按 `AGENTHELM_LANG`、系统 locale 决定，最后用英文）；输出为 JSON，`list` 可用 `--output markdown` 得到给用户看的编号列表。
+
+- `add --title --text --scope [--quote] [--client] [--session]`：暂存。标题 ≤120、正文 ≤1200、原话 ≤600 个字符；至少一个 `--scope`。内容相同（忽略空白与大小写）的候选合并，新原话追加为证据。
+- `list [--status a,b] [--session ID] [--unpresented]`：列出候选。
+- `decide <编号…> --to pending|trial|formal|held|rejected --confirmed [--note]`：裁决。没有 `--confirmed` 一律拒绝；多个编号要么全部成功，要么都不改。
+- `present <编号…>`：记录已向用户展示过（hook 在发出确认请求时调用，避免同一候选反复提示）。
+- `expire --days N`：把试行超过 N 天的候选退回 `pending`。退回保留 `last_action_at`，因此仍计入“久未处理”。
+- `pending [--session ID]`：待确认项提供者，见下。
+- `exposure`：只读，报告 `.opinion/inbox.json` 在 Git 里的状态与提醒文字。
+- `brief [--session ID] [--max-chars N]`：生成会话开始时注入的协议与试行候选全文，默认上限 6000 字符。
+
+## 待确认项提供者契约
+
+agent-pack 的会话开始检测按同一结构汇总各来源（opinion 候选，以及将来的 SOP 待办等）。一个提供者返回：
+
+```json
+{"ok": true, "source": "opinion",
+ "items": [{"id": "cand-20261029-001", "source": "opinion", "kind": "candidate", "title": "…",
+            "status": "pending", "created_at": "…Z", "last_action_at": "…Z", "age_days": 3.2,
+            "hint_command": "处理这一项的命令"}],
+ "counts": {"pending": 2, "trial": 1, "formal": 0, "held": 0, "rejected": 0},
+ "oldest_pending_days": 3.2, "last_action_at": "…Z", "session_unpresented": ["cand-…"]}
+```
+
+`status` 为 `pending` 的条目计入提醒阈值；`age_days` 按 `last_action_at`（上一次用户动作，缺省为创建时间）计算。提供者只读，不在读取时改变状态。

package/runtime/plugins/opinion-manager/runtime/context.py

@@ -8,9 +8,10 @@ from pathlib import Path
 from typing import Any
 
 import versioned
+from i18n_opinion import _, N_  # noqa: E402
 
 
-FALLBACK = "完整读取项目根目录 OPINION.md"
+FALLBACK = N_("完整读取项目根目录 OPINION.md")
 PROJECT_PROFILE = Path(".agents") / "moe.sakanano.agent-pack" / "project.json"
 DIRECT = "(direct)"
 EXIT_OK, EXIT_MISSING, EXIT_ERROR, EXIT_FULL = 0, 1, 2, 3
@@ -26,7 +27,7 @@ def project_mode(root: Path) -> str:
         return "tiered"
     mode = versioned.read_object(path).get("opinion", {}).get("loading_mode", "tiered")
     if mode not in ("tiered", "full"):
-        versioned.fail(f"Project Profile 的 opinion.loading_mode 必须为 tiered 或 full：{mode!r}")
+        versioned.fail(_("Project Profile 的 opinion.loading_mode 必须为 tiered 或 full：{0!r}").format(mode))
     return mode
 
 
@@ -36,15 +37,15 @@ def load(args: argparse.Namespace) -> tuple[dict[str, Any], dict[str, Any] | Non
         profile, lock = versioned.load_profile(args.profile), None
     else:
         if args.project is None:
-            versioned.fail("context 需要 --project 或 --profile")
+            versioned.fail(_("context 需要 --project 或 --profile"))
         root = versioned.safe_path(args.project)
         versioned.verify_project(root)
         lock = versioned.read_object(root / "opinion.lock.json")
         profile = lock["profile"]
         if project_mode(root) == "full":
-            raise FullReading("Project Profile 设为完整读取")
+            raise FullReading(_("Project Profile 设为完整读取"))
     if "loading" not in profile:
-        raise FullReading("当前 Profile 未声明分层加载")
+        raise FullReading(_("当前 Profile 未声明分层加载"))
     return profile, lock
 
 
@@ -58,7 +59,7 @@ def partition(profile: dict[str, Any]) -> dict[str, Any]:
     always = set(loading["core"]) | set(unlisted)
     assigned: dict[str, str] = {}
     for wanted in (True, False):
-        for _, family, value in templates:
+        for _ref, family, value in templates:
             if (family in always) is not wanted:
                 continue
             for ref in value["rules"]:
@@ -100,13 +101,13 @@ def core_text(profile: dict[str, Any], lock: dict[str, Any] | None) -> str:
 def resolve_bundle(parts: dict[str, Any], name: str) -> str:
     family = {ref: family for family, ref in parts["refs"].items()}.get(name, name)
     if family not in {bundle["family"] for bundle in parts["bundles"]}:
-        versioned.fail(f"未知的按需规则束：{name}")
+        versioned.fail(_("未知的按需规则束：{0}").format(name))
     return family
 
 
 def bundle_text(profile: dict[str, Any], names: list[str]) -> str:
     if not names:
-        versioned.fail("bundle 需要至少一个模板系列或精确模板引用")
+        versioned.fail(_("bundle 需要至少一个模板系列或精确模板引用"))
     parts = partition(profile)
     lines: list[str] = []
     for name in names:
@@ -138,12 +139,12 @@ def check(profile: dict[str, Any], signals: list[str], loaded: list[str]) -> dic
     vocabulary = profile["loading"]["signals"]
     declared: dict[str, set[str]] = {}
     for item in signals:
-        key, _, value = item.partition("=")
+        key, _sep, value = item.partition("=")
         if key not in vocabulary or value not in vocabulary[key]:
-            versioned.fail(f"未声明的交付信号：{item}")
+            versioned.fail(_("未声明的交付信号：{0}").format(item))
         declared.setdefault(key, set()).add(value)
     if not declared:
-        versioned.fail("check 至少需要一个 --signal")
+        versioned.fail(_("check 至少需要一个 --signal"))
     have = {resolve_bundle(parts, name) for name in loaded}
     required = [bundle["family"] for bundle in parts["bundles"]
                 if any(all(declared.get(key, set()) & set(values) for key, values in route.items()) for route in bundle["routes"])]
@@ -153,13 +154,13 @@ def check(profile: dict[str, Any], signals: list[str], loaded: list[str]) -> dic
 
 
 def add_command(subparsers: Any) -> None:
-    parser = subparsers.add_parser("context", help="按已确认的加载声明只读切分正文，并核对交付信号")
+    parser = subparsers.add_parser("context", help=_("按已确认的加载声明只读切分正文，并核对交付信号"))
     parser.add_argument("action", choices=("core", "bundle", "index", "check"))
-    parser.add_argument("names", nargs="*", help="bundle 的模板系列或精确模板引用")
+    parser.add_argument("names", nargs="*", help=_("bundle 的模板系列或精确模板引用"))
     parser.add_argument("--project", type=Path)
-    parser.add_argument("--profile", type=Path, help="用候选或已保存的 Profile 预览，不读取项目锁")
-    parser.add_argument("--signal", action="append", default=[], help="交付信号，格式为 键=值，可重复")
-    parser.add_argument("--loaded", action="append", default=[], help="本次已读取的规则束，可重复")
+    parser.add_argument("--profile", type=Path, help=_("用候选或已保存的 Profile 预览，不读取项目锁"))
+    parser.add_argument("--signal", action="append", default=[], help=_("交付信号，格式为 键=值，可重复"))
+    parser.add_argument("--loaded", action="append", default=[], help=_("本次已读取的规则束，可重复"))
     parser.add_argument("--output", choices=("json", "markdown"), default="markdown")
 
 
@@ -175,6 +176,6 @@ def execute(args: argparse.Namespace) -> tuple[int, str]:
         result = check(profile, args.signal, args.loaded)
         return (EXIT_OK if result["ok"] else EXIT_MISSING), versioned.pretty(result)
     except FullReading as exc:
-        return EXIT_FULL, versioned.pretty({"ok": False, "error": str(exc), "fallback": FALLBACK})
+        return EXIT_FULL, versioned.pretty({"ok": False, "error": str(exc), "fallback": _(FALLBACK)})
     except (versioned.OpinionVersionError, OSError, UnicodeDecodeError, json.JSONDecodeError, KeyError, TypeError) as exc:
-        return EXIT_ERROR, versioned.pretty({"ok": False, "error": str(exc), "fallback": FALLBACK})
+        return EXIT_ERROR, versioned.pretty({"ok": False, "error": str(exc), "fallback": _(FALLBACK)})

package/runtime/plugins/opinion-manager/runtime/i18n_opinion.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