@sakanano-moe/agenthelm 6.6.0 → 6.8.0

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/agent-pack/runtime/mcp_server.py

@@ -43,7 +43,7 @@ TOOLS = [
     {
         "name": "agent_pack_bootstrap",
         "title": "Install Agent Plugin",
-        "description": "Dry-run or install a portable plugin, including agent-pack itself, into Codex, Cursor, or Claude Code without overwriting an existing package.",
+        "description": "Dry-run or install a portable plugin, including agent-pack itself, into Codex, Cursor, or Claude Code without overwriting an existing package. For Claude Code, skills / mcps limit the install to those components, and local credential values on MCP entries are kept unless resetOverrides.",
         "inputSchema": {
             "type": "object",
             "properties": {
@@ -53,6 +53,9 @@ TOOLS = [
                 "apply": {"type": "boolean", "default": False},
                 "replace": {"type": "boolean", "default": False},
                 "recoveryRoot": {"type": "string"},
+                "skills": {"type": "array", "items": {"type": "string"}, "default": []},
+                "mcps": {"type": "array", "items": {"type": "string"}, "default": []},
+                "resetOverrides": {"type": "boolean", "default": False},
             },
             "required": ["plugin", "client"],
             "additionalProperties": False,
@@ -62,12 +65,14 @@ TOOLS = [
     {
         "name": "agent_pack_reconcile",
         "title": "Reconcile Project and Client Capabilities",
-        "description": "Classify capability drift, safely replace the managed project package, and archive explicitly selected legacy Skills or plugins with rollback. apply defaults to false.",
+        "description": "Classify capability drift, safely replace the managed project package, and archive explicitly selected legacy Skills or plugins with rollback. Claude Code gets its own package, MCP entries and Skill links; local credential values are kept unless resetOverrides. apply defaults to false.",
         "inputSchema": {
             "type": "object",
             "properties": {
                 "project": {"type": "string"},
-                "client": {"type": "string", "enum": ["codex", "cursor"]},
+                "client": {"type": "string", "enum": ["codex", "cursor", "claude"]},
+                "replace": {"type": "boolean", "default": False},
+                "resetOverrides": {"type": "boolean", "default": False},
                 "home": {"type": "string"},
                 "retireSkills": {"type": "array", "items": {"type": "string"}, "default": []},
                 "retirePlugins": {"type": "array", "items": {"type": "string"}, "default": []},
@@ -97,10 +102,15 @@ TOOLS = [
     {
         "name": "agent_pack_doctor",
         "title": "Validate Project Capabilities",
-        "description": "Validate an initialized project's Agent Plugin, Skill, MCP, duplicate-name, portability, and secret boundaries.",
+        "description": "Validate an initialized project's Agent Plugin, Skill, MCP, duplicate-name, portability, and secret boundaries. With clients, also report each client's missing, stale and different components and kept local overrides.",
         "inputSchema": {
             "type": "object",
-            "properties": {"project": {"type": "string"}},
+            "properties": {
+                "project": {"type": "string"},
+                "clients": {"type": "array", "items": {"type": "string", "enum": ["codex", "cursor", "claude"]},
+                            "default": []},
+                "home": {"type": "string"},
+            },
             "required": ["project"],
             "additionalProperties": False,
         },
@@ -127,14 +137,17 @@ TOOLS = [
     {
         "name": "agent_pack_sync",
         "title": "Sync Project Capabilities to an Agent Client",
-        "description": "Dry-run or install a project's portable capability package into Codex or Cursor. apply defaults to false and existing targets are never overwritten.",
+        "description": "Dry-run or install a project's portable capability package into Codex, Cursor or Claude Code. apply defaults to false; replaced content goes to the recovery directory. Claude Code keeps local credential values unless resetOverrides, and only replaces entries it did not install with replace.",
         "inputSchema": {
             "type": "object",
             "properties": {
                 "project": {"type": "string"},
-                "client": {"type": "string", "enum": ["codex", "cursor"]},
+                "client": {"type": "string", "enum": ["codex", "cursor", "claude"]},
                 "home": {"type": "string"},
                 "apply": {"type": "boolean", "default": False},
+                "replace": {"type": "boolean", "default": False},
+                "resetOverrides": {"type": "boolean", "default": False},
+                "recoveryRoot": {"type": "string"},
             },
             "required": ["project", "client"],
             "additionalProperties": False,
@@ -174,6 +187,9 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
             apply=bool(arguments.get("apply", False)),
             replace=bool(arguments.get("replace", False)),
             recovery_root=recovery,
+            skills=arguments.get("skills", []),
+            mcps=arguments.get("mcps", []),
+            reset_overrides=bool(arguments.get("resetOverrides", False)),
         )
     if name == "agent_pack_reconcile":
         recovery_value = arguments.get("recoveryRoot")
@@ -187,6 +203,8 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
             recovery_root=recovery,
             apply=bool(arguments.get("apply", False)),
             retire_only=bool(arguments.get("retireOnly", False)),
+            replace=bool(arguments.get("replace", False)),
+            reset_overrides=bool(arguments.get("resetOverrides", False)),
         )
     if name == "agent_pack_inventory":
         inventory = inventory_source(arguments["source"], home)
@@ -194,7 +212,7 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
         payload["ok"] = not payload["issues"]
         return payload
     if name == "agent_pack_doctor":
-        return doctor(Path(arguments["project"]))
+        return doctor(Path(arguments["project"]), arguments.get("clients", []), home)
     if name == "agent_pack_transfer":
         source = inventory_source(arguments["source"], home)
         return transfer_to_project(
@@ -205,11 +223,15 @@ def _call(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
             apply=bool(arguments.get("apply", False)),
         )
     if name == "agent_pack_sync":
+        recovery_value = arguments.get("recoveryRoot")
         return sync_project(
             Path(arguments["project"]),
             arguments["client"],
             home=home,
             apply=bool(arguments.get("apply", False)),
+            replace=bool(arguments.get("replace", False)),
+            reset_overrides=bool(arguments.get("resetOverrides", False)),
+            recovery_root=Path(recovery_value) if isinstance(recovery_value, str) else None,
         )
     raise AgentPackError(f"unknown tool: {name}")
 

package/runtime/plugins/agent-pack/skills/agent-pack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-pack
-description: 确定性地盘点、校验、安装、同步、迁移与对账 Agent Plugin、Skill 与 MCP server——在项目、插件目录与 Codex / Cursor / Claude 等客户端之间。当需要发现、导入、导出、同步或验证 Agent 能力，或诊断某台机器的扩展安装漂移时使用。项目生命周期（Task/Case/路由/验证/Git）不在本 Skill 内——那是 project-orchestrator。
+description: Deterministically inventory, verify, install, sync, migrate and reconcile Agent Plugins, Skills and MCP servers across projects, plugin directories and clients such as Codex, Cursor and Claude. Use when discovering, importing, exporting, syncing or verifying Agent capabilities, or diagnosing extension drift on a machine. The project lifecycle (Task/Case/routing/verification/Git) is not part of this Skill; that is project-orchestrator. 中文：确定性地盘点、校验、安装、同步、迁移与对账 Agent Plugin、Skill 与 MCP server——在项目、插件目录与 Codex / Cursor / Claude 等客户端之间。当需要发现、导入、导出、同步或验证 Agent 能力，或诊断某台机器的扩展安装漂移时使用。项目生命周期（Task/Case/路由/验证/Git）不在本 Skill 内——那是 project-orchestrator。
 ---
 
 # Agent Pack（Agent 扩展能力管理）
@@ -29,7 +29,7 @@ description: 确定性地盘点、校验、安装、同步、迁移与对账 Age
 6. 只应用明确选择的组件；
 7. 对目标运行 `doctor`。
 
-目标客户端尚未安装某包时，从可信本地插件根目录使用 `bootstrap`。`bootstrap` 支持 `codex` / `cursor` / `claude`；Claude 端写入 `~/.claude/skills` 符号链接与 `~/.claude.json` user-scope MCP，装完需重启 Claude Code。处理已有客户端时优先使用 `reconcile`：审阅组件状态，明确列出要退役的旧 Skill/plugin，再执行应用。只退役、不安装项目包时加 `--retire-only`。用户验收迁移前，已退役或替换的内容必须保留在报告的恢复目录（`~/.agent-pack/recovery/`）中。
+目标客户端尚未安装某包时，从可信本地插件根目录使用 `bootstrap`。`bootstrap` 支持 `codex` / `cursor` / `claude`；Claude 端写入 `~/.claude/skills` 符号链接与 `~/.claude.json` user-scope MCP，可用 `--skill` / `--mcp` 只装选中的组件，本机认证值默认保留（`--reset-overrides` 才丢弃），装完需重启 Claude Code。把项目能力同步到 Claude 用 `sync --client claude`：它为 Claude 单独生成包，只增删改本包装过的条目，不要用 `bootstrap` 指向 Codex 的包。核对客户端是否与项目一致用 `doctor --client <客户端>`。处理已有客户端时优先使用 `reconcile`：审阅组件状态，明确列出要退役的旧 Skill/plugin，再执行应用。只退役、不安装项目包时加 `--retire-only`。用户验收迁移前，已退役或替换的内容必须保留在报告的恢复目录（`~/.agent-pack/recovery/`）中。
 
 ## 打包与协议
 

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

@@ -1,15 +1,15 @@
 {
   "name": "agents-init",
-  "version": "6.6.0",
-  "description": "初始化或迁移 Agent 项目契约；同一分发包附带 project-orchestrator、agent-pack 与 opinion-manager。",
+  "version": "6.7.0",
+  "description": "Initialize or migrate an Agent project contract; ships with project-orchestrator, agent-pack and opinion-manager.",
   "author": {
     "name": "lc4t"
   },
   "skills": "./skills/",
   "interface": {
     "displayName": "Agents Init",
-    "shortDescription": "初始化或迁移项目骨架与 Project Profile",
-    "longDescription": "用 agents-init 创建或迁移可移植项目契约。project-orchestrator 管理项目生命周期，agent-pack 管理 Plugin/Skill/MCP，opinion-manager 管理用户与 Agent 之间的行为规则；三者作为独立 Plugin 随同分发。",
+    "shortDescription": "Initialize or migrate the project skeleton and Project Profile",
+    "longDescription": "Use agents-init to create or migrate a portable project contract, including a root launcher that opens the project menu without any AI agent. project-orchestrator manages the project lifecycle, agent-pack manages Plugins/Skills/MCP, and opinion-manager manages behavior rules between the user and the Agent; all three ship alongside it as separate plugins. 中文：用 agents-init 创建或迁移可移植项目契约（含不需要 AI Agent 就能打开项目菜单的根目录启动器）。project-orchestrator 管理项目生命周期，agent-pack 管理 Plugin/Skill/MCP，opinion-manager 管理用户与 Agent 之间的行为规则；三者作为独立 Plugin 随同分发。",
     "developerName": "lc4t",
     "category": "Developer Tools",
     "capabilities": [
@@ -17,6 +17,6 @@
       "project-migration",
       "opinion-configuration"
     ],
-    "defaultPrompt": "使用 $agents-init 初始化或迁移项目，并通过 $opinion-manager 配置当前环境的 Agent 行为规则。"
+    "defaultPrompt": "Use $agents-init to initialize or migrate this project, then use $opinion-manager to configure the Agent behavior rules for this environment."
   }
 }

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,8 +1,8 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agents-init",
-  "version": "6.6.0",
-  "description": "初始化或迁移 Agent 项目契约；同一分发包附带 project-orchestrator、agent-pack 与 opinion-manager。",
+  "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

@@ -1,6 +1,6 @@
 ---
 name: agents-init
-description: 初始化仓库或将既有仓库迁移到 agents-init v6 项目骨架。用户要求初始化 Agent 协作、创建 AGENTS.md、增加 Project Profile（项目配置）或迁移旧版 agents-init 结构（含 v5 的 project-runtime Profile）时使用。本 Skill 只负责结构；project-orchestrator 负责项目生命周期，agent-pack 负责 Plugin/Skill/MCP，opinion-manager 负责用户确认的 Agent 行为规则。
+description: Initialize a repository, or migrate an existing one, to the agents-init v6 project skeleton. Use when the user asks to set up Agent collaboration, create AGENTS.md, add a Project Profile, add a root launcher for the project menu, or migrate an older agents-init layout (including the v5 project-runtime Profile). This Skill only handles structure; project-orchestrator owns the project lifecycle, agent-pack owns Plugins/Skills/MCP, and opinion-manager owns user-confirmed Agent behavior rules. 中文：初始化仓库或将既有仓库迁移到 agents-init v6 项目骨架。用户要求初始化 Agent 协作、创建 AGENTS.md、增加 Project Profile（项目配置）或迁移旧版 agents-init 结构（含 v5 的 project-runtime Profile）时使用。本 Skill 只负责结构；project-orchestrator 负责项目生命周期，agent-pack 负责 Plugin/Skill/MCP，opinion-manager 负责用户确认的 Agent 行为规则。
 ---
 
 # Agents Init（项目初始化）
@@ -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 基线结构如下：