@sakanano-moe/agenthelm 6.7.0 → 6.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sakanano-moe/agenthelm",
-  "version": "6.7.0",
+  "version": "6.8.0",
   "description": "agenthelm CLI: install, check and update the agenthelm plugins for Claude Code, Codex and Cursor; a user-level runtime; and a project menu that works without any AI agent.",
   "license": "MIT",
   "bin": {

package/runtime/index.json

@@ -4,14 +4,14 @@
     "name": "agenthelm",
     "description": "Cross-agent project management plugins: project contract, lifecycle, extension capabilities and behavior rules. 跨 Agent 的项目管理插件集。",
     "version": "0.7.0",
-    "updated_at": "2026-10-25",
+    "updated_at": "2026-10-27",
     "homepage": "./index.html",
     "domain": "agenthelm.sakanano.moe",
     "legacy_domain": "skill.sakanano.moe"
   },
   "plugin": {
     "manifest": "./plugins/agents-init/plugin.json",
-    "version": "6.7.0",
+    "version": "6.8.0",
     "install_unit": "marketplace",
     "bundled_plugins": [
       "./plugins/project-orchestrator/plugin.json",
@@ -30,7 +30,7 @@
       "id": "agents-init",
       "name": "agents-init v6 / Project Profile initialization and migration",
       "description": "Create or migrate the project skeleton and root launcher; checks that project-orchestrator, agent-pack and opinion-manager from the same release are present before writing.",
-      "version": "6.6.1",
+      "version": "6.7.0",
       "status": "stable",
       "entrypoints": {
         "browser": "./plugins/agents-init/skills/agents-init/index.html",
@@ -43,7 +43,7 @@
       "id": "project-orchestrator",
       "name": "project-orchestrator / project lifecycle orchestration",
       "description": "Organizes Case workspaces or keeps existing Task/Case layouts; search, lossless migration, verification, scoped Git delivery, and a project menu that works without any AI agent.",
-      "version": "1.8.1",
+      "version": "1.9.0",
       "status": "stable",
       "entrypoints": {
         "agent": "./plugins/project-orchestrator/skills/project-orchestrator/SKILL.md",
@@ -55,7 +55,7 @@
       "id": "agent-pack",
       "name": "agent-pack / Agent extension capability management",
       "description": "Inventory, verify, install, sync, migrate and reconcile Plugins, Skills and MCP between projects and Codex / Cursor / Claude; the agenthelm command line and user-level runtime.",
-      "version": "1.8.0",
+      "version": "1.9.0",
       "status": "stable",
       "entrypoints": {
         "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",

package/runtime/plugins/agent-pack/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-pack",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Deterministic Agent-extension capability management for configured workspaces.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/agent-pack/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agent-pack",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Deterministic Agent-extension capability management: inventory, doctor, bootstrap, sync, transfer, and reconcile Agent Plugins / Skills / MCP servers across Codex, Cursor, Claude Code, and project sources. Ships a stdio MCP.",
   "author": {
     "name": "lc4t"

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

@@ -73,6 +73,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 +103,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")
@@ -356,10 +365,132 @@ def opinion_findings(project: Path, installed: list[dict]) -> list[dict]:
     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)}
+
+
+SYNC_SERVICES = (
+    ("iCloud Drive", re.compile(r"^(com~apple~CloudDocs|Mobile Documents|iCloud Drive|iCloudDrive)$")),
+    ("Dropbox", re.compile(r"^Dropbox( \(.*\))?$")),
+    ("OneDrive", re.compile(r"^OneDrive( - .*|-.*)?$")),
+    ("Google Drive", re.compile(r"^(GoogleDrive(-.*)?|Google Drive|My Drive)$")),
+)
+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) -> 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 = f"；其中有可重建目录：{'、'.join(where['rebuildable'][:6])}" if where["rebuildable"] else ""
+        findings.append({"id": "local:sync-folder", "kind": "sync-folder", "level": "suggest", "scope": "machine",
+                         "title": f"项目位于同步盘（{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})
+    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
+
+
 # ---------------------------------------------------------------- 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 +500,9 @@ 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)
+    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 +514,18 @@ 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,
             "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),
         },
     }
 
@@ -414,10 +552,52 @@ def one_line(report: dict) -> str | None:
         parts.append("Opinion 有新版本模板或规则")
     if summary["legacy_installs"]:
         parts.append(f"{summary['legacy_installs']} 个旧方式安装待迁移")
+    if summary["scaffold_findings"]:
+        parts.append(f"项目脚手架有 {summary['scaffold_findings']} 项差异")
     return "agenthelm：" + "，".join(parts) + f"。运行 `{CLI} check` 查看详情；更新前会先预览，由你决定。"
 
 
-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(f"  [脚手架] 无法检查：{scaffold['error']}")
+        return lines
+    for item in scaffold["findings"]:
+        mark = "（稍后）" if item.get("deferred") else "（期望内容已变化，重新提示）" if item.get("changed_since_decision") else ""
+        fix = f"  处理：fix {item['fix']}" if item.get("fix") else "  需要你自己处理"
+        lines.append(f"  [脚手架] {item['title']}{mark}：{item['reason']}\n      ID {item['id']}{fix}")
+    for message in scaffold["decisions"]["errors"]:
+        lines.append(f"  [脚手架] 决定文件有问题：{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("  [脚手架] 与期望一致" + (f"（{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(f"  [已跳过·{decision['decision']}] {item['id']}：{decision.get('reason') or '（未写理由）'}"
+                         f"  {decision.get('decided_at', '')}")
+        if not skipped:
+            lines.append("  没有被跳过的项。")
+    elif skipped:
+        lines.append(f"  （另有 {len(skipped)} 项已被你跳过：check --show-skipped 查看）")
+    return lines
+
+
+def render_machine(report: dict) -> list[str]:
+    lines = []
+    for item in report.get("machine", {}).get("findings", []):
+        lines.append(f"  [本机] {item['title']}：{item['reason']}\n      影响：{item['impact']}\n      处理：{item['next']}"
+                     f"\n      ID {item['id']}（只记在这台机器上；fix --skip {item['id']} --reason …）")
+    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 ""))
@@ -460,6 +640,8 @@ def render_text(report: dict) -> str:
             lines.append(f"  [Opinion] 有新版本：{refs}（用 opinion-manager 预览后确认）")
         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` 预览安装。")
     else:
@@ -974,7 +1156,14 @@ def parser() -> argparse.ArgumentParser:
     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 用）")
+    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)
@@ -1004,6 +1193,8 @@ def parser() -> argparse.ArgumentParser:
     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("runtime", add_help=False,
                    help="用户级运行时：install / update / use / status（日常只需要 Python，不经过 npx）")
     sub.add_parser("project", add_help=False,
@@ -1070,10 +1261,48 @@ 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) -> 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 f"无法计算脚手架指纹：{reason}", file=sys.stderr if args.output != "json" else sys.stdout)
+        return 4
+    payload: dict = {"ok": True, "fingerprint": result["fingerprint"], "detail": result["detail"]}
+    lines = [f"脚手架指纹 {result['fingerprint']}"]
+    differences: list[str] = []
+    if args.explain and args.explain != "-":
+        try:
+            other = read_json(Path(args.explain).expanduser())
+        except (OSError, ValueError) as exc:
+            print(f"读不了对方的输出：{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)
+        payload["same"] = not differences
+        payload["differences"] = differences
+        lines.append("两台机器的脚手架一致。" if not differences else f"有 {len(differences)} 处不同：")
+        lines += [f"  {item}" for item in differences]
+    elif args.explain:
+        lines += [f"  {key} = {value}" for key, value in result["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:])
     args = parser().parse_args(argv)
@@ -1094,12 +1323,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)
             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))

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

@@ -157,6 +157,25 @@ def release_version(latest: dict | None) -> str | None:
     return tag[1:] if isinstance(tag, str) and tag.startswith("v") else tag
 
 
+def command_status() -> dict:
+    """Which of the commands people type are on PATH right now (``wf`` is never installed by the runtime)."""
+    return {"agenthelm": shutil.which("agenthelm"), "wf": shutil.which("wf")}
+
+
+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 {
+        "reason": f"本次由 {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）",
+    }
+
+
 def report(env: Any, latest: dict | None = None) -> dict:
     active = current(env)
     newest = release_version(latest)

package/runtime/plugins/agents-init/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-init",
-  "version": "6.6.1",
+  "version": "6.7.0",
   "description": "Initialize or migrate an Agent project contract; ships with project-orchestrator, agent-pack and opinion-manager.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/agents-init/content.json

@@ -26,6 +26,21 @@
       "materializes_from_profile": [
         "entry.launcher"
       ]
+    },
+    {
+      "id": "agents-init/project-skeleton",
+      "version": "1.0.0",
+      "kind": "manifest",
+      "title": "期望骨架清单",
+      "description": "项目脚手架应有的文件、Profile 受检字段与不参与比较的字段（审计字段、Opinion 设置）；agenthelm check 据此对比项目，不写入项目。",
+      "sources": [
+        "skills/agents-init/skeleton.json"
+      ],
+      "materializes": [],
+      "project_lock": "none",
+      "files": {
+        "skills/agents-init/skeleton.json": "70ea5e360f018c0d840d5d7aa022f811d665642a2d127f254f7a76335b4e77da"
+      }
     }
   ]
 }

package/runtime/plugins/agents-init/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agents-init",
-  "version": "6.6.1",
+  "version": "6.7.0",
   "description": "Initialize or migrate an Agent project contract (AGENTS.md, Project Profile, root launcher); ships with project-orchestrator, agent-pack and opinion-manager.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/agents-init/skills/agents-init/SKILL.md

@@ -69,6 +69,19 @@ python3 scripts/init_project.py --mode migrate --project /path/to/project \
   --replace AGENTS.md --recovery-dir /safe/recovery/example-v6 --apply
 ```
 
+已初始化的项目对照最新脚手架用 `--mode check`（只读）；其余模式默认只预览，`--apply` 才写入，已有文件不被覆盖，替换前备份到 `--recovery-dir`：
+
+```bash
+python3 scripts/init_project.py --project /path/to/project --mode check
+python3 scripts/init_project.py --project /path/to/project --mode add-skeleton [--target docs/refs/README.md]
+python3 scripts/init_project.py --project /path/to/project --mode profile [--target runtime.commit_policy] --recovery-dir /safe/recovery/example
+python3 scripts/init_project.py --project /path/to/project --mode repair-lock
+python3 scripts/init_project.py --project /path/to/project --mode decide --target skel:docs/drafts/.gitkeep --decision skip --reason "…" --apply
+python3 scripts/init_project.py --project /path/to/project --mode case-naming   # 只给改名计划，不移动目录
+```
+
+期望骨架清单是 [skeleton.json](skeleton.json)（内容包 `agents-init/project-skeleton`）；Opinion、Profile 里的项目自有字段与审计字段不参与比较。用户的跳过 / 保留决定写入 `.agents/moe.sakanano.agent-pack/check-decisions.json`，随项目同步。日常入口是 `agenthelm check` 与 `agenthelm fix`。
+
 ## 输出契约
 
 v6 基线结构如下：

package/runtime/plugins/agents-init/skills/agents-init/project.schema.json

@@ -34,7 +34,12 @@
         "distribution": {"enum": ["marketplace", "bundled", "external"]},
         "required": {"type": "boolean"},
         "commit_policy": {"enum": ["explicit", "project-policy"]},
-        "push_policy": {"enum": ["explicit", "project-policy"]}
+        "push_policy": {"enum": ["explicit", "project-policy"]},
+        "source_repository": {"type": "string", "x-agenthelm-scope": "audit", "description": "审计记录：采用的来源仓库。运行时代码不读取，check 不比较，也不进脚手架指纹。"},
+        "source_ref": {"type": "string", "x-agenthelm-scope": "audit", "description": "审计记录：采用的发布 tag。同上，仅作记录。"},
+        "source_commit": {"type": "string", "x-agenthelm-scope": "audit", "description": "审计记录：采用的提交。同上，仅作记录。"},
+        "plugin_version": {"type": "string", "x-agenthelm-scope": "audit", "description": "审计记录：采用时的 project-orchestrator 版本。同上，仅作记录。"},
+        "capability_manager_version": {"type": "string", "x-agenthelm-scope": "audit", "description": "审计记录：采用时的 agent-pack 版本。同上，仅作记录。"}
       }
     },
     "opinion": {
@@ -45,7 +50,8 @@
         "provider": {"type": ["string", "null"]},
         "project_overlay": {"type": ["string", "null"]},
         "strict_mode": {"enum": ["smart", "strict", "disabled"]},
-        "loading_mode": {"enum": ["tiered", "full"]}
+        "loading_mode": {"enum": ["tiered", "full"]},
+        "tool_version": {"type": "string", "x-agenthelm-scope": "audit", "description": "审计记录：生成该 Opinion 时的工具版本；不参与比较。"}
       }
     },
     "memory": {
@@ -99,7 +105,16 @@
           "type": ["object", "null"], "additionalProperties": true,
           "properties": {
             "root": {"$ref": "#/$defs/relativePath"},
-            "artifact_mode": {"enum": ["case-local", "external-references"]}
+            "artifact_mode": {"enum": ["case-local", "external-references"]},
+            "command": {"type": ["array", "string"], "description": "项目自己的 Case 工具命令；声明后项目入口不绕过它写 Case。"},
+            "directory_naming": {
+              "type": "object", "additionalProperties": true,
+              "description": "Case 目录命名规则，check 据此检查目录名；缺省按 CASE-日期-序号-主题。fix case-naming 只给改名计划，不移动目录。",
+              "properties": {
+                "style": {"enum": ["case-id", "date-topic", "custom"]},
+                "pattern": {"type": "string", "description": "匹配整个目录名的正则；style 为 custom 时必填。"}
+              }
+            }
           }
         },
         "assets": {

package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py

@@ -715,6 +715,17 @@ def _profile_launcher(profile: dict) -> str | None:
     return validate_entry_name(launcher) if isinstance(launcher, str) else None
 
 
+def _scaffold():
+    """scaffold.py 与本文件同目录；绑定到正在运行的本模块，保证异常类一致。"""
+    here = str(Path(__file__).resolve().parent)
+    if here not in sys.path:
+        sys.path.insert(0, here)
+    import scaffold  # noqa: PLC0415
+
+    scaffold.bind(sys.modules[__name__])
+    return scaffold
+
+
 def _unified_diff(relative: str, current: str, new: str, limit: int = 200) -> str:
     lines = list(difflib.unified_diff(
         current.splitlines(keepends=True), new.splitlines(keepends=True),
@@ -756,6 +767,7 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
     if accept & keep:
         raise InitError("同一文件不能同时 --accept 与 --keep：" + ", ".join(sorted(map(str, accept & keep))))
     plan: list[dict] = []
+    kept_before = _scaffold().keep_fingerprints(root)
     for relative in tracked:
         new = rendered[relative]
         new_digest = hashlib.sha256(new.encode("utf-8")).hexdigest()
@@ -776,7 +788,10 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
             state, action = "clean", "keep" if relative in keep else "replace"
         else:
             state = "modified"
-            action = "replace" if relative in accept else "keep" if relative in keep else "blocked"
+            decided = kept_before.get(relative.as_posix()) == new_digest  # 之前选过保留，且期望内容没变
+            action = "replace" if relative in accept else "keep" if relative in keep or decided else "blocked"
+            if decided and relative not in accept:
+                state = "kept-by-decision"
         item = {"path": relative.as_posix(), "state": state, "action": action, "new_sha256": new_digest}
         if action in {"replace", "blocked", "create"} or (state == "clean" and action == "keep"):
             item["diff"] = _unified_diff(relative.as_posix(), current or "", new)
@@ -831,6 +846,12 @@ def refresh_project(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
     temporary = lock_path.with_name(f".{lock_path.name}.{os.getpid()}.tmp")
     temporary.write_text(json_text(lock), encoding="utf-8")
     os.replace(temporary, lock_path)
+    # 显式 --keep 的选择记入决定文件：同样的模板内容以后不再追问，模板实质变化时才再问。
+    for item in plan:
+        if Path(item["path"]) in keep and item["state"] in {"modified", "local-only", "kept-by-decision"}:
+            _scaffold().decide(root, f"content:{item['path']}", "keep", reason="refresh --keep",
+                               fingerprint=item["new_sha256"], scope="project", apply=True)
+            result.setdefault("decisions", []).append(f"content:{item['path']}")
     result["applied"] = True
     return 0, result
 
@@ -943,8 +964,10 @@ def add_entry(args: argparse.Namespace, root: Path) -> tuple[int, dict]:
             lock_path = root / CONTENT_LOCK_PATH
             lock = _read_project_json(root, CONTENT_LOCK_PATH, "content lock") if lock_path.exists() \
                 else {"schema_version": 1, "packs": {}}
+            # 新条目只记录刚写入的启动器，它与当前模板一致，所以版本就是当前包版本；
+            # 不再写占位的 0.0.0（那会让 check 永远提示“可更新”）。
             pack_entry = lock.setdefault("packs", {}).get(pack["id"]) or \
-                {"plugin": "agents-init", "version": UNKNOWN_PACK_VERSION, "files": {}}
+                {"plugin": "agents-init", "version": pack["version"], "files": {}}
             pack_entry["files"] = dict(sorted({**pack_entry.get("files", {}),
                                                name: hashlib.sha256(template.encode("utf-8")).hexdigest()}.items()))
             lock["packs"][pack["id"]] = pack_entry
@@ -964,9 +987,20 @@ def parser() -> argparse.ArgumentParser:
     result.add_argument("--stack", type=split_csv)
     result.add_argument("--runtime")
     result.add_argument("--agent-cli", type=split_csv)
-    result.add_argument("--mode", choices=("init", "migrate", "refresh", "entry"), default="init",
+    result.add_argument("--mode", choices=("init", "migrate", "refresh", "entry", "check", "add-skeleton", "profile",
+                                           "repair-lock", "decide", "case-naming"), default="init",
                         help="refresh：内容包更新后按 Profile 重新渲染已跟踪的模板文件；"
-                             "entry：为已初始化的项目补上根目录启动器与 Profile 的 entry 段")
+                             "entry：为已初始化的项目补上根目录启动器与 Profile 的 entry 段；"
+                             "check：只读，对比期望骨架清单；add-skeleton：按模板补上缺失的骨架文件；"
+                             "profile：把缺失或不符的受检字段改为模板值；repair-lock：修复内容锁的 0.0.0 版本；"
+                             "decide：记录或撤销对某个发现的决定；case-naming：只输出 Case 目录改名计划与受影响的引用，不移动任何目录")
+    result.add_argument("--target", action="append", default=[],
+                        help="add-skeleton：骨架路径；profile：字段；decide：发现 ID（可重复；省略则处理全部可处理项）")
+    result.add_argument("--decision", choices=("skip", "keep", "later", "unskip"), help="decide：决定；unskip 撤销")
+    result.add_argument("--reason", help="decide：理由（建议写，随项目同步）")
+    result.add_argument("--fingerprint", help="decide：期望指纹（缺省取该发现当前的指纹）")
+    result.add_argument("--reprompt", action="store_true", help="check：忽略已记录的决定，重新评估全部发现")
+    result.add_argument("--state-dir", type=Path, help="机器本地决定的状态目录（缺省 $XDG_STATE_HOME 或 ~/.local/state）")
     result.add_argument("--entry-name", help=f"根目录启动器文件名（init 缺省 {DEFAULT_ENTRY}；entry 模式必填）")
     result.add_argument("--no-entry", action="store_true", help="init：不生成根目录启动器")
     result.add_argument("--readme-entry", action="store_true",
@@ -996,6 +1030,11 @@ def main(argv: list[str] | None = None) -> int:
     args = parser().parse_args(argv)
     try:
         root = validate_root(args.project)
+        if args.mode in ("check", "add-skeleton", "profile", "repair-lock", "decide", "case-naming"):
+            scaffold = _scaffold()
+            code, result = scaffold.run_mode(args, root)
+            print(json_text(result), end="") if args.output == "json" else print(scaffold.render_text(result), end="")
+            return code
         if args.mode == "entry":
             code, result = add_entry(args, root)
             if args.output == "json":