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

package/runtime/plugins/project-orchestrator/runtime/sop_structure.py

@@ -0,0 +1,226 @@
+"""SOP 文件的结构：小节名、字段名、前置条件的写法与写进 Case 的文字，按项目文件语言（Project Profile 的 ``language``）。
+
+和 Case 一样（见 case_structure.py），SOP 写进项目的文件用什么语言是项目的属性，随项目同步，不随命令行界面语言
+（AGENTHELM_LANG）变化：``language`` 为 ``en`` 的项目新建的 SOP 用英文小节名与字段名，缺省或 ``zh`` 的项目保持中文。
+读取时两套词表都认，所以手写的、从别的项目拷来的、换过语言的 SOP 都能照常解析；追加内容时沿用文件自己的写法。
+
+frontmatter 的键、枚举值（ask / stop / retry …）本来就是英文，与语言无关，不在这里。
+"""
+from __future__ import annotations
+
+import re
+
+import case_structure
+
+LANGUAGES = case_structure.LANGUAGES
+language_of = case_structure.language_of
+
+SECTIONS = {
+    "purpose": ("目的", "Purpose"),
+    "requires": ("前置条件", "Prerequisites"),
+    "steps": ("步骤", "Steps"),
+    "done": ("完成标准", "Completion criteria"),
+    "exceptions": ("例外与回退", "Exceptions and fallback"),
+    "revisions": ("修订记录", "Revision log"),
+}
+STRICT_SECTIONS = ("requires", "steps", "done")
+
+STEP_KEYS = {
+    "tools": ("工具", "Tools"),
+    "inputs": ("输入", "Inputs"),
+    "intermediates": ("中间产物", "Intermediates"),
+    "finals": ("最终产物", "Final outputs"),
+    "checkpoint": ("检查点", "Checkpoint"),
+    "on_failure": ("失败时", "On failure"),
+    "confirm": ("需确认", "Needs confirmation"),
+    "note": ("说明", "Note"),
+}
+REQ_KINDS = {
+    "command": ("命令", "Command"),
+    "module": ("模块", "Module"),
+    "env": ("环境变量", "Environment variable"),
+    "path": ("路径", "Path"),
+    "skill": ("技能", "Skill"),
+    "mcp": ("MCP", "MCP"),
+    "manual": ("手动确认", "Manual check"),
+}
+REQ_KEYS = {
+    "purpose": ("用途", "Purpose"),
+    "install": ("安装", "Install"),
+    "alternative": ("替代", "Alternative"),
+    "if_missing": ("缺失时", "If missing"),
+    "version": ("版本", "Version"),
+    "when": ("仅当", "Only if"),
+}
+MISSING = {
+    "ask": ("询问用户", "Ask the user"),
+    "stop": ("停止", "Stop"),
+    "skip-step": ("跳过该步", "Skip the step"),
+    "alternative": ("使用替代", "Use the alternative"),
+}
+# 只在读取时认的别名（简写）。
+KIND_ALIASES = {"手动": "manual"}
+MISSING_ALIASES = {"询问": "ask", "跳过": "skip-step", "替代": "alternative", "ask": "ask", "skip": "skip-step"}
+
+TRUE_WORDS = ("是", "y", "yes", "true", "需要", "required")
+NONE_WORDS = ("无", "（无）", "(无)", "不需要", "none", "(none)", "n/a", "not needed")
+LIST_NONE = ("无", "-", "—", "none")
+
+PLACEHOLDERS = ("【待补充】", "[TO FILL IN]")
+EMPTY_REVISIONS = ("暂无。", "None yet.")
+
+# 执行 Case 里 SOP 自己加的小节（Case 的标准小节见 case_structure）。
+CASE_SECTIONS = {
+    "checklist": ("SOP 执行清单", "SOP checklist"),
+    "intermediate": ("中间产物", "Intermediate artifacts"),
+}
+
+# 写进 Case 与 SOP 文件的文字。{…} 是 str.format 的字段。
+TEXTS = {
+    "revision_line": ("{date} v{version}：{note}", "{date} v{version}: {note}"),
+    "note_activated": ("启用（内容与执行约定已与用户确认）", "Activated (content and run conventions confirmed with the user)"),
+    "note_retired": ("退役", "Retired"),
+    "note_restored": ("恢复", "Restored"),
+    "from_case_description": ("{p}（从 {case} 提炼）", "{p} (distilled from {case})"),
+    "from_case_step": ("{index}. {text}\n   - 说明：{p}整理这一步（来自 {case} 的工作记录，需改写成可重复执行的动作）",
+                       "{index}. {text}\n   - Note: {p} tidy this step (from the work log of {case}; rewrite it as a repeatable action)"),
+    "case_created_marker": ("Case 已创建", "Case created"),
+    # 执行清单
+    "cl_source": ("来源：`{id}@{version}`（{note}）", "Source: `{id}@{version}` ({note})"),
+    "snapshot_note": ("快照 {path}", "Snapshot {path}"),
+    "cl_conventions": ("执行约定（开始时从 SOP 与项目习惯固化，执行中不随 SOP 改动）：",
+                       "Run conventions (frozen from the SOP and the project habits at the start; they do not follow later SOP edits):"),
+    "cl_on_error": ("- 出错时：", "- On error: "),
+    "cl_retries": ("（最多重试 {n} 次）", " (at most {n} retries)"),
+    "cl_on_missing": ("- 缺少工具时：", "- On a missing tool: "),
+    "cl_artifacts_label": ("- 中间产物：", "- Intermediate artifacts: "),
+    "cl_artifacts": ("放在 {place}；完成后：{keep}", "kept in {place}; afterwards: {keep}"),
+    "cl_data_dir": ("本 Case 的 data/ 目录", "this Case's data/ directory"),
+    "cl_resume": ("- 失败后重新执行：", "- Resuming after a failure: "),
+    "cl_costly": ("- 花钱或耗时的步骤：", "- Costly or slow steps: "),
+    "cl_private": ("- 私有目录：本次会用到 {dirs}；读取前须经用户确认（用 sop confirm-read 记录），内容默认不进入 git；本 Case 已标为 private",
+                   "- Private directories: this run will use {dirs}; the user must confirm before each read (record it with sop confirm-read), the content stays out of git by default; this Case is marked private"),
+    "cl_params": ("参数：", "Parameters:"),
+    "cl_steps": ("步骤：", "Steps:"),
+    "cl_tools": ("（工具：{tools}）", " (tools: {tools})"),
+    "cl_event_param": ("触发事件：{event}（{id}：{title}）", "Trigger event: {event} ({id}: {title})"),
+    "event_note": ("由 {event} 触发（{id}）", "Triggered by {event} ({id})"),
+    "source_event": ("；{note}", "; {note}"),
+    "next_first": ("步骤 1：{title}", "Step 1: {title}"),
+    "progress0": ("SOP 进度 0/{total}", "SOP progress 0/{total}"),
+    "empty_intermediates": ("暂无。", "None yet."),
+    "log_started": ("{stamp} 按 {id}@{version} 开始执行{event}；执行前检查：就绪 {ok}、缺失 {missing}、待核对 {unknown}",
+                    "{stamp} Started running {id}@{version}{event}; preflight: {ok} ready, {missing} missing, {unknown} to verify"),
+    "log_started_event": ("，{note}", ", {note}"),
+    # 逐步记录
+    "state_done": ("完成", "done"),
+    "state_skip": ("跳过", "skipped"),
+    "state_fail": ("失败", "failed"),
+    "state_pending": ("重置为待办", "reset to to-do"),
+    "log_step": ("{stamp} SOP 步骤 {n}「{title}」{label}{note}", "{stamp} SOP step {n} \"{title}\" {label}{note}"),
+    "note_join": ("：{note}", ": {note}"),
+    "artifact_line": ("步骤 {n}：`{location}`", "Step {n}: `{location}`"),
+    "artifact_what": ("（{what}）", " ({what})"),
+    "next_failed": ("处理步骤 {n} 的失败（约定：{habit}）", "Handle the failure of step {n} (convention: {habit})"),
+    "next_step": ("步骤 {n}：{title}", "Step {n}: {title}"),
+    "next_done": ("核对完成标准（sop.py status）后关闭 Case 或登记交付物",
+                  "Check the completion criteria (sop.py status), then close the Case or register deliverables"),
+    "state_progress": ("SOP 进度 {done}/{total}", "SOP progress {done}/{total}"),
+    "state_failed_suffix": ("，步骤 {n} 失败", ", step {n} failed"),
+    "log_confirm_read": ("{stamp} 用户确认读取私有路径：{paths}{note}", "{stamp} The user confirmed reading private paths: {paths}{note}"),
+    "list_join": ("、", ", "),
+    "confirm_note": ("；{note}", "; {note}"),
+}
+
+_TOOLS_SPLIT = re.compile(r"（工具|\s\(tools:")
+
+
+def text(key: str, language: str, /, **fields: object) -> str:
+    return TEXTS[key][LANGUAGES.index(language)].format(**fields)
+
+
+def name(table: dict, key: str, language: str) -> str:
+    return table[key][LANGUAGES.index(language)]
+
+
+def _lookup(table: dict) -> dict[str, str]:
+    return {variant.lower(): key for key, variants in table.items() for variant in variants}
+
+
+_SECTION_LOOKUP = _lookup(SECTIONS)
+_STEP_LOOKUP = _lookup(STEP_KEYS)
+_KIND_LOOKUP = {**_lookup(REQ_KINDS), **KIND_ALIASES}
+_REQ_LOOKUP = _lookup(REQ_KEYS)
+_MISSING_LOOKUP = {**_lookup(MISSING), **{alias.lower(): key for alias, key in MISSING_ALIASES.items()}}
+
+
+def section_key(heading: str) -> str | None:
+    return _SECTION_LOOKUP.get(heading.strip().lower())
+
+
+def step_key(label: str) -> str | None:
+    return _STEP_LOOKUP.get(label.strip().lower())
+
+
+def kind_key(label: str) -> str | None:
+    return _KIND_LOOKUP.get(label.strip().lower())
+
+
+def req_key(label: str) -> str | None:
+    return _REQ_LOOKUP.get(label.strip().lower())
+
+
+def missing_value(label: str) -> str | None:
+    return _MISSING_LOOKUP.get(label.strip().lower())
+
+
+def section_text(sections: dict[str, str], key: str) -> str:
+    """The body of a logical section, whichever language the file spells its heading in."""
+    for variant in SECTIONS[key]:
+        if variant in sections:
+            return sections[variant]
+    for heading, body in sections.items():
+        if section_key(heading) == key:
+            return body
+    return ""
+
+
+def detect(body: str, default: str = "zh") -> str:
+    """The language this SOP body is written in, judged by its section headings."""
+    counts = {language: 0 for language in LANGUAGES}
+    for line in body.splitlines():
+        match = re.match(r"^##\s+(.+?)\s*$", line)
+        if match:
+            for index, language in enumerate(LANGUAGES):
+                counts[language] += any(variants[index] == match.group(1) for variants in SECTIONS.values())
+    if counts["zh"] == counts["en"]:
+        return default
+    return "zh" if counts["zh"] > counts["en"] else "en"
+
+
+def detect_case(body: str, default: str) -> str:
+    """The language of a SOP run Case, judged by its checklist heading."""
+    for index, language in enumerate(LANGUAGES):
+        if f"## {CASE_SECTIONS['checklist'][index]}\n" in body or body.rstrip().endswith(f"## {CASE_SECTIONS['checklist'][index]}"):
+            return language
+    return default
+
+
+def checklist_headings() -> tuple[str, ...]:
+    return CASE_SECTIONS["checklist"]
+
+
+def prefixes(key: str) -> tuple[str, ...]:
+    return TEXTS[key]
+
+
+def strip_tools(step_text: str) -> str:
+    return _TOOLS_SPLIT.split(step_text)[0]
+
+
+def is_placeholder_free(value: str) -> bool:
+    return not any(marker in value for marker in PLACEHOLDERS)
+
+
+def count_placeholders(value: str) -> int:
+    return sum(value.count(marker) for marker in PLACEHOLDERS)

package/runtime/plugins/project-orchestrator/runtime/wf.py

@@ -1,19 +1,5 @@
 #!/usr/bin/env python3
-"""wf：人用的文件查找入口，基于交付物台账（runtime/assets.py），无需 Agent。
-
-    wf                       交互模式
-    wf 笔记 9月1号             直接查（日期、同义词自动识别）
-    wf -o 笔记 9月1号          查到后直接打开最新一个
-    wf recent                最近改动的交付物
-    wf cases [词]            Case 列表（进行中在前）
-    wf refs <路径|序号> [层数]  谁引用它 / 它引用谁
-    wf o|f|c|p|v <序号>       打开 / 在文件管理器中显示 / 复制路径 / 打印路径 / 列出版本（序号指上一次结果）
-    wf check                 台账巡检摘要
-    wf rebuild               强制重建台账
-
---project <目录> 与 --output json 可写在任意位置；缺省从当前目录向上查找 Project Profile。
-打开、显示与复制只在 macOS 上调用系统命令，其他平台打印绝对路径。
-"""
+"""wf：人用的文件查找入口，基于交付物台账（runtime/assets.py），无需 Agent。"""
 from __future__ import annotations
 
 import json
@@ -28,10 +14,27 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 import assets  # noqa: E402
 from assets import AssetError, Project  # noqa: E402
+from i18n_orchestrator import _, N_  # noqa: E402
+
+USAGE = N_("""wf：人用的文件查找入口，基于交付物台账（runtime/assets.py），无需 Agent。
+
+    wf                       交互模式
+    wf 笔记 9月1号             直接查（日期、同义词自动识别）
+    wf -o 笔记 9月1号          查到后直接打开最新一个
+    wf recent                最近改动的交付物
+    wf cases [词]            Case 列表（进行中在前）
+    wf refs <路径|序号> [层数]  谁引用它 / 它引用谁
+    wf o|f|c|p|v <序号>       打开 / 在文件管理器中显示 / 复制路径 / 打印路径 / 列出版本（序号指上一次结果）
+    wf check                 台账巡检摘要
+    wf rebuild               强制重建台账
+
+--project <目录> 与 --output json 可写在任意位置；缺省从当前目录向上查找 Project Profile。
+打开、显示与复制只在 macOS 上调用系统命令，其他平台打印绝对路径。
+""")
 
 ACTIONS = {"o": "open", "f": "reveal", "c": "copy", "v": "versions", "r": "refs", "p": "path"}
-STATUS_LABEL = {"active": "进行中", "waiting": "等待", "done": "已完成", "captured": "待澄清",
-                "suspended": "挂起", "abandoned": "放弃"}
+STATUS_LABEL = {"active": N_("进行中"), "waiting": N_("等待"), "done": N_("已完成"), "captured": N_("待澄清"),
+                "suspended": N_("挂起"), "abandoned": N_("放弃")}
 
 
 # ---------------------------------------------------------------- display
@@ -90,7 +93,7 @@ def status_text(item: dict) -> str:
     status = item.get("status", "")
     if not status:
         return "project" if item.get("container_kind") == "project" else "-"
-    label = STATUS_LABEL.get(status, status)
+    label = _(STATUS_LABEL.get(status, status))
     return S.green(label) if status == "active" else S.yellow(label) if status == "waiting" else S.dim(label)
 
 
@@ -109,8 +112,8 @@ def render_groups(groups: list[dict]) -> None:
         print(S.dim(f"     {clip(item['path'], width - 6)}"))
         if item.get("versions"):
             names = " · ".join(version["name"] for version in item["versions"][:4])
-            more = f" 等 {len(item['versions'])} 个" if len(item["versions"]) > 4 else ""
-            print(S.dim(f"     └ 同系列另有 {len(item['versions'])} 个：{clip(names, width - 30)}{more}"))
+            more = _(" 等 {0} 个").format(len(item['versions'])) if len(item["versions"]) > 4 else ""
+            print(S.dim(_("     └ 同系列另有 {0} 个：{1}{2}").format(len(item['versions']), clip(names, width - 30), more)))
 
 
 # ---------------------------------------------------------------- last results
@@ -141,7 +144,7 @@ def resolve_target(token: str, last: list[dict]) -> dict | None:
         index = int(token) - 1
         if 0 <= index < len(last):
             return last[index]
-        print(S.red(f"没有第 {token} 项（上一次结果共 {len(last)} 项）"))
+        print(S.red(_("没有第 {0} 项（上一次结果共 {1} 项）").format(token, len(last))))
         return None
     return {"path": token, "name": Path(token).name, "title": "", "modified": "", "versions": []}
 
@@ -154,13 +157,13 @@ def do_action(action: str, relative: str, project: Project, platform: str | None
     mac = (platform or sys.platform) == "darwin"
     if action == "open" and mac and shutil.which("open"):
         subprocess.run(["open", target], check=False)
-        print(S.green("已打开 ") + relative)
+        print(S.green(_("已打开 ")) + relative)
     elif action == "reveal" and mac and shutil.which("open"):
         subprocess.run(["open", "-R", target], check=False)
-        print(S.green("已在 Finder 中显示 ") + relative)
+        print(S.green(_("已在 Finder 中显示 ")) + relative)
     elif action == "copy" and mac and shutil.which("pbcopy"):
         subprocess.run(["pbcopy"], input=target.encode("utf-8"), check=False)
-        print(S.green("已复制绝对路径 ") + target)
+        print(S.green(_("已复制绝对路径 ")) + target)
     else:
         print(target)
         return "printed"
@@ -169,7 +172,7 @@ def do_action(action: str, relative: str, project: Project, platform: str | None
 
 def show_versions(group: dict) -> None:
     print(S.bold(group.get("title") or group.get("name", "")))
-    print(f"  {(group.get('modified') or '')[:16].replace('T', ' ')}  {group['path']}  {S.green('最新')}")
+    print(f"  {(group.get('modified') or '')[:16].replace('T', ' ')}  {group['path']}  {S.green(_('最新'))}")
     for version in group.get("versions", []):
         print(f"  {(version.get('modified') or '')[:16].replace('T', ' ')}  {version['path']}  "
               f"{S.dim(version.get('git', ''))}")
@@ -179,38 +182,38 @@ def show_refs(project: Project, path: str, depth: int = 1) -> dict:
     result = assets.refs(project, path, depth=depth)
     print(S.bold(result["path"]))
     if result["inbound"]:
-        print(S.cyan("  被引用："))
+        print(S.cyan(_("  被引用：")))
         for item in result["inbound"][:25]:
-            via = "" if item["via"] == "file" else S.dim("（目录级）")
+            via = "" if item["via"] == "file" else S.dim(_("（目录级）"))
             print(f"    ← {item['src']}{via}")
     else:
-        print(S.dim("  没有被任何 Case 或扫描根里的文件引用"))
+        print(S.dim(_("  没有被任何 Case 或扫描根里的文件引用")))
     if result["outbound"]:
-        print(S.cyan("  引用了："))
+        print(S.cyan(_("  引用了：")))
         for item in result["outbound"][:25]:
             print(f"    → {item['dst']}")
     if result["affected_containers"]:
-        print(S.yellow("  改动会波及：") + "、".join(result["affected_containers"][:8]))
+        print(S.yellow(_("  改动会波及：")) + _("、").join(result["affected_containers"][:8]))
     return result
 
 
 def do_search(project: Project, terms: list[str], *, limit: int = 10, **filters: str) -> list[dict]:
     if assets.status(project)["status"] != "fresh":
-        print(S.dim("（索引更新中…）"))
+        print(S.dim(_("（索引更新中…）")))
     result = assets.find(project, terms, limit=limit, **filters)
     query = result["query"]
-    description = " ".join(query["terms"]) or "全部"
+    description = " ".join(query["terms"]) or _("全部")
     if query["dates"]:
-        description += " · 日期 " + ",".join(date.replace("*-", "") for date in query["dates"])
-    print(S.dim(f"查找：{description}"))
+        description += _(" · 日期 ") + ",".join(date.replace("*-", "") for date in query["dates"])
+    print(S.dim(_("查找：{0}").format(description)))
     if not result["results"]:
-        print(S.yellow("没有找到。") + S.dim("试试更短的词、去掉日期，或 `wf cases` 先看 Case 列表。"))
+        print(S.yellow(_("没有找到。")) + S.dim(_("试试更短的词、去掉日期，或 `wf cases` 先看 Case 列表。")))
         return []
     render_groups(result["results"])
-    tail = f"共 {result['total']} 组"
+    tail = _("共 {0} 组").format(result['total'])
     if result["total"] > result["returned"]:
-        tail += f"，只显示前 {result['returned']} 组（加关键词收窄）"
-    print(S.dim(tail + "。序号可接 o 打开 / f 显示 / c 复制 / v 版本 / r 引用，例：o1"))
+        tail += _("，只显示前 {0} 组（加关键词收窄）").format(result['returned'])
+    print(S.dim(tail + _("。序号可接 o 打开 / f 显示 / c 复制 / v 版本 / r 引用，例：o1")))
     save_last(project, result["results"])
     return result["results"]
 
@@ -219,11 +222,11 @@ def do_cases(project: Project, term: str | None, limit: int = 30) -> dict:
     result = assets.cases(project, term, limit=limit)
     width = term_width()
     for item in result["results"]:
-        status = STATUS_LABEL.get(item["status"], item["status"] or "-")
+        status = _(STATUS_LABEL.get(item["status"], item["status"] or "-"))
         mark = S.green(f"{status:<4}") if item["status"] == "active" else S.dim(f"{status:<4}")
         print(f" {mark} {S.bold(clip(item['title'] or item['id'], width - 52))}  {S.dim(clip(item['id'], 44))}  "
-              f"{S.dim(str(item['files']) + ' 个文件')}")
-    print(S.dim(f"共 {result['total']} 个 Case" + ("；用 `wf <Case 关键词>` 查其文件" if result["total"] else "")))
+              f"{S.dim(str(item['files']) + _(' 个文件'))}")
+    print(S.dim(_("共 {0} 个 Case").format(result['total']) + (_("；用 `wf <Case 关键词>` 查其文件") if result["total"] else "")))
     return result
 
 
@@ -238,26 +241,28 @@ def do_check(project: Project) -> dict:
     report = assets.check(project)
     totals, tiers, counts = report["totals"], report["claim_tiers"], report["broken_counts"]
     git = totals["git"]
-    print(S.bold("台账巡检"))
-    print(f"  文件 {totals['files']} · 引用 {totals['edges']} · Git 已入库 {git.get('tracked', 0)} / "
-          f"不入库 {git.get('ignored', 0)} / 新建未提交 {git.get('untracked', 0)} / 非 Git {git.get('none', 0)}")
-    print(f"  交付物：文件级被引用 {tiers.get('file', 0)} · 仅目录覆盖 {tiers.get('directory', 0)} · "
-          f"无人认领 {S.yellow(str(tiers.get('none', 0)))}")
-    print(f"  断链：真断链 {S.yellow(str(counts.get('real-broken', 0)))} · "
-          f"说明文字 {counts.get('prose-not-path', 0)} · 主题链接 {counts.get('wikilink-topic', 0)}")
+    print(S.bold(_("台账巡检")))
+    print(_("  文件 {0} · 引用 {1} · Git 已入库 {2} / 不入库 {3} / 新建未提交 {4} / 非 Git {5}").format(totals['files'], totals['edges'], git.get('tracked', 0), git.get('ignored', 0), git.get('untracked', 0), git.get('none', 0)))
+    print(_("  交付物：文件级被引用 {0} · 仅目录覆盖 {1} · 无人认领 {2}").format(tiers.get('file', 0), tiers.get('directory', 0), S.yellow(str(tiers.get('none', 0)))))
+    print(_("  断链：真断链 {0} · 说明文字 {1} · 主题链接 {2}").format(S.yellow(str(counts.get('real-broken', 0))), counts.get('prose-not-path', 0), counts.get('wikilink-topic', 0)))
     for container, paths in list(report["unclaimed"].items())[:5]:
-        print(S.dim(f"  无人认领 · {container}: {paths[0]}"))
+        print(S.dim(_("  无人认领 · {0}: {1}").format(container, paths[0])))
     return report
 
 
 # ---------------------------------------------------------------- entry
 
-HELP = f"""{S.bold('用法')}
-  直接输入关键词查找；可带日期（9月1号 / 0901 / 2026-09-01），同义词按项目的 asset-synonyms.json 展开。
-  {S.cyan('o1')} 打开第 1 项   {S.cyan('f1')} 在文件管理器中显示   {S.cyan('c1')} 复制绝对路径   {S.cyan('p1')} 打印路径
-  {S.cyan('v1')} 查看全部版本   {S.cyan('r1')} 谁引用它（r1 2 为两层）   {S.cyan('1')} 直接打开
-  {S.cyan('recent')} 最近改动   {S.cyan('cases [词]')} Case 列表   {S.cyan('check')} 巡检   {S.cyan('q')} 退出
-  过滤：{S.cyan('ext:xlsx')}  {S.cyan('kind:deliverable')}（也可 draft/source/data）  {S.cyan('in:片段')}（限定 Case/目录）"""
+def help_text() -> str:
+    cyan = S.cyan
+    return (S.bold(_("用法")) + "\n"
+            + _("  直接输入关键词查找；可带日期（9月1号 / 0901 / 2026-09-01），同义词按项目的 asset-synonyms.json 展开。") + "\n"
+            + _("  {0} 打开第 1 项   {1} 在文件管理器中显示   {2} 复制绝对路径   {3} 打印路径").format(
+                cyan("o1"), cyan("f1"), cyan("c1"), cyan("p1")) + "\n"
+            + _("  {0} 查看全部版本   {1} 谁引用它（r1 2 为两层）   {2} 直接打开").format(cyan("v1"), cyan("r1"), cyan("1")) + "\n"
+            + _("  {0} 最近改动   {1} Case 列表   {2} 巡检   {3} 退出").format(
+                cyan("recent"), cyan("cases [词]"), cyan("check"), cyan("q")) + "\n"
+            + _("  过滤：{0}  {1}（也可 draft/source/data）  {2}（限定 Case/目录）").format(
+                cyan("ext:xlsx"), cyan("kind:deliverable"), cyan("in:片段")))
 
 
 def parse_filters(tokens: list[str]) -> tuple[list[str], dict]:
@@ -277,7 +282,7 @@ def split_globals(argv: list[str]) -> tuple[list[str], Path | None, str]:
     index = 0
     while index < len(argv):
         token = argv[index]
-        name, _, inline = token.partition("=")
+        name, _sep, inline = token.partition("=")
         if name in ("--project", "--output"):
             if inline:
                 value = inline
@@ -285,13 +290,13 @@ def split_globals(argv: list[str]) -> tuple[list[str], Path | None, str]:
                 index += 1
                 value = argv[index]
             else:
-                raise AssetError(f"{name} 需要一个值")
+                raise AssetError(_("{0} 需要一个值").format(name))
             if name == "--project":
                 project = Path(value)
             elif value in ("text", "json"):
                 output = value
             else:
-                raise AssetError("--output 只能是 text 或 json")
+                raise AssetError(_("--output 只能是 text 或 json"))
         else:
             rest.append(token)
         index += 1
@@ -305,16 +310,15 @@ def interactive(project: Project) -> int:
         pass
     current = assets.status(project)
     if current["status"] != "fresh":
-        print(S.dim("（索引更新中…）"))
+        print(S.dim(_("（索引更新中…）")))
         assets.rebuild(project)
         current = assets.status(project)
-    print(S.bold(S.cyan("交付物台账")) + S.dim(f"  ·  {current.get('file_count', '?')} 个文件  ·  索引 "
-                                             f"{current.get('built_at', '')[11:16]}"))
-    print(S.dim("输入关键词查找；? 帮助；q 退出"))
+    print(S.bold(S.cyan(_("交付物台账"))) + S.dim(_("  ·  {0} 个文件  ·  索引 {1}").format(current.get('file_count', '?'), current.get('built_at', '')[11:16])))
+    print(S.dim(_("输入关键词查找；? 帮助；q 退出")))
     groups: list[dict] = []
     while True:
         try:
-            line = input(S.bold(S.cyan("\n查找 › "))).strip()
+            line = input(S.bold(S.cyan(_("\n查找 › ")))).strip()
         except (EOFError, KeyboardInterrupt):
             print()
             return 0
@@ -323,7 +327,7 @@ def interactive(project: Project) -> int:
         if line in ("q", "quit", "exit", "退出"):
             return 0
         if line in ("?", "help", "帮助"):
-            print(HELP)
+            print(help_text())
             continue
         try:
             match = re.match(r"^([ofcvrp])\s*(\d+)(?:\s+(\d+))?$", line) or re.match(r"^()(\d+)()$", line)
@@ -351,7 +355,7 @@ def interactive(project: Project) -> int:
             terms, filters = parse_filters(line.split())
             groups = do_search(project, terms, **filters)
         except AssetError as exc:
-            print(S.red(f"出错：{exc}"))
+            print(S.red(_("出错：{0}").format(exc)))
 
 
 def command(project: Project, argv: list[str], output: str) -> tuple[int, dict | None]:
@@ -387,7 +391,7 @@ def command(project: Project, argv: list[str], output: str) -> tuple[int, dict |
         return 0, None
     if head == "rebuild":
         result = assets.rebuild(project, force=True)
-        print(f"{result['action']}：{result['file_count']} 个文件")
+        print(_("{0}：{1} 个文件").format(result['action'], result['file_count']))
         return 0, None
     if (head in ACTIONS and len(argv) > 1 and (argv[1].isdigit() or head == "r")) or (head == "refs" and len(argv) > 1):
         target = resolve_target(argv[1], load_last(project))
@@ -415,23 +419,23 @@ def main(argv: list[str] | None = None) -> int:
     try:
         argv, start, output = split_globals(argv)
         if argv and argv[0] in ("-h", "--help", "help"):
-            print(__doc__)
+            print(_(USAGE))
             return 0
         project = Project.discover(start, explicit=start is not None)
         if not argv:
             if output == "json":
-                raise AssetError("交互模式不支持 --output json")
+                raise AssetError(_("交互模式不支持 --output json"))
             return interactive(project)
         code, result = command(project, argv, output)
         if output == "json":
             print(json.dumps(result if result is not None else {"ok": False, "code": "not-found",
-                                                                  "error": "没有这一项"}, ensure_ascii=False, indent=2))
+                                                                  "error": _("没有这一项")}, ensure_ascii=False, indent=2))
         return code
     except AssetError as exc:
         if output == "json":
             print(json.dumps({"ok": False, "code": exc.code, "error": str(exc)}, ensure_ascii=False))
         else:
-            print(S.red(f"出错：{exc}"), file=sys.stderr)
+            print(S.red(_("出错：{0}").format(exc)), file=sys.stderr)
         return 2
 
 

package/runtime/plugins/project-orchestrator/skills/project-orchestrator/SKILL.md

@@ -116,6 +116,28 @@ Case 自有输入放 `refs/`，交付物放 `docs/`（草稿 `docs/drafts/`）
 
 Project Profile 声明了 `memory` 时，恢复状态后读取记忆索引：`provider` 为 `project-orchestrator` 时运行随包的 `runtime/memory.py index --project <项目>`，为 `project` 时运行其 `index_command`。索引每条一行，说明何时应当想起该条记忆；只在当前任务命中时读取条目正文。依据某条记忆行动前，核对其中提到的文件、命令与外部对象仍然存在；标注为可能过期的条目先核实再使用。
 
+### 3.1 流程（SOP）
+
+用户可以把常用流程固化成 SOP（Standard Operating Procedure，标准作业流程）。契约与命令见 [SOP 契约](../../references/sop.md)，与用户一起建立见 [建立 SOP](../../references/sop-interview.md)。
+
+- **读索引**：存在 `sops/` 目录或用户级 SOP 时，恢复状态后运行随包的 `runtime/sop.py index --project <项目>`（一行一个已启用的 SOP，写明触发与不触发条件）。没有 SOP 时静默跳过。
+- **判断触发**：用户明确指定、事件（新建或关闭 Case 时，`case.py` 与项目入口的结果带 `sop_events`；自有 Case 工具用 `sop.py events <事件> --case <Case>` 查询）、周期到期（`sop.py due`）、意图对照触发与不触发条件，按这个优先级。命中后默认先问用户一次是否按它执行；多个命中合并成一次编号提问；到期只是提醒。只读被命中的那一个 SOP 的正文。
+- **执行**：`sop.py preflight` 检查所需程序与环境，缺失项一次性列给用户并等待处理，**不自行安装软件**；`sop.py run`（预览 → 用户确认 → `--apply`）建立执行 Case；逐步执行并用 `sop.py step --apply` 记录结果与中间产物；出错、缺工具、花钱或耗时步骤按 Case 里固化的“执行约定”处理；收尾用 `sop.py status` 与完成标准核对。
+- **范围与私有目录**：会读取多个事项的流程（复盘、汇总）先让用户指定范围，不默认纳入全部事项；SOP 里用到私有目录（见 3.2）时，`sop.py run` 自动把执行 Case 标为 `private`，读取前按 3.2 取得用户确认。
+- **授权不变**：SOP 不放宽任何授权，写入、外发、删除、push、安装、花钱类步骤仍须用户当次同意；与用户当次请求冲突时以请求为准并说明偏离。
+- **创建与修改**：SOP 里的工具、出错处理、中间产物位置等是用户的习惯，只提问、整理、校验，不替用户决定；`decided` 只在用户确认后用 `sop.py decide` 写入；修改后用 `sop.py revise` 登记版本。
+- 一次执行的状态只写在 Case 里，不在 SOP 目录里另记；SOP 不是 Opinion（表达偏好）也不是记忆（事实），不要写错位置。
+
+### 3.2 私有目录
+
+Profile 的 `privacy.forbidden_default_reads` 声明私有路径（没有声明但项目根有 `private/` 时，按约定它就是私有目录）。三条约定，其余照常：
+
+- **读取前须经用户确认**：默认不读、不列目录、不搜索其中的内容。需要读时，先向用户列出要读的路径和用途，得到确认再读；确认后用 `sop.py confirm-read <Case> <路径…> --apply` 记入该 Case 的决策记录（同时把 Case 标为 `private`）。确认只覆盖当次列出的路径。
+- **内容默认不进入 git**：私有目录里有 `.gitignore`（`*` 加 `!.gitignore`）。`sop.py private` 查看状态，`--apply` 补上缺失的 `.gitignore`；`health` 会提示未被忽略的私有目录和已被跟踪的文件。不要替用户 `git add`、提交或推送私有目录里的内容。
+- **用到私有目录的 Case 标为 `sensitivity: private`**：`case.py update --add-deliverable/--add-evidence` 登记私有路径时自动改，也可 `--sensitivity private`；SOP 里引用了私有路径时 `sop.py run` 自动标。云同步盘同步它没有问题。
+
+这是协议级约束：工具层挡不住 Agent 直接读文件，所以要靠这里的规则；`find` 照常索引 `private` 的 Case（索引只是本机缓存里的索引，不做过滤）。
+
 ## 4. 路由能力
 
 根据三项输入构建执行路由：

package/runtime/plugins/project-orchestrator/sop-templates/blank/SOP.en.md

@@ -0,0 +1,57 @@
+---
+schema_version: "1.0"
+id: "{{id}}"
+title: "{{title}}"
+status: "draft"
+version: "1.0.0"
+description: "[TO FILL IN] One sentence: what this procedure does and when to think of it"
+trigger: "[TO FILL IN] When this procedure should be used"
+exclude: ""
+confirm: "ask"
+creates_case: "always"
+created: "{{date}}"
+aliases: []
+examples_hit: []
+examples_miss: []
+on_events: []
+outputs: []
+sources: []
+decided: []
+---
+# {{title}}
+
+## Purpose
+
+[TO FILL IN] What this procedure should achieve, in a sentence or two.
+
+## Prerequisites
+
+One item per line: `- Kind: name | Purpose: … | Install: … | Alternative: name of another item | If missing: Ask the user`.
+Kinds: Command, Module (a Python module), Environment variable, Path, Skill, MCP, Manual check. If missing: Ask the user, Stop, Skip the step, Use the alternative.
+For API keys write only the environment variable name, never the key itself. If no tool is needed at all, write "None".
+
+- Command: [TO FILL IN] | Purpose: [TO FILL IN] | Install: [TO FILL IN] | If missing: Ask the user
+
+## Steps
+
+One number per step, with indented sub-items below it. Sub-items: Tools, Inputs, Intermediates, Final outputs, Checkpoint, On failure, Needs confirmation, Note.
+Every name under "Tools" must be declared in the prerequisites above.
+
+1. [TO FILL IN] What the first step does
+   - Tools: [TO FILL IN]
+   - Inputs: [TO FILL IN]
+   - Intermediates: [TO FILL IN]
+   - Checkpoint: [TO FILL IN] How to tell the step went right
+   - On failure: [TO FILL IN] (if left out, the "run conventions" apply)
+
+## Completion criteria
+
+- [TO FILL IN] How to tell the whole procedure is done (a condition that can be checked, for example "the output file exists at …")
+
+## Exceptions and fallback
+
+- [TO FILL IN] Common exceptions and how to handle them; write "None" if there are none.
+
+## Revision log
+
+None yet.