@sakanano-moe/agenthelm 6.6.0 → 6.7.0

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

@@ -1019,8 +1019,15 @@ def install_plugin(
     apply: bool = False,
     replace: bool = False,
     recovery_root: Path | None = None,
+    skills: Iterable[str] = (),
+    mcps: Iterable[str] = (),
+    reset_overrides: bool = False,
 ) -> dict[str, Any]:
-    """Bootstrap a portable plugin into a supported client without overwriting."""
+    """Bootstrap a portable plugin into a supported client without overwriting.
+
+    For Claude Code, ``skills`` / ``mcps`` limit the install to those components
+    and local credential values on MCP entries are kept unless ``reset_overrides``.
+    """
     plugin = plugin.expanduser().resolve()
     manifest, issues = validate_plugin_manifest(plugin)
     if issues:
@@ -1030,8 +1037,11 @@ def install_plugin(
     home = (home or Path.home()).expanduser().resolve()
     if client == "claude":
         return _install_plugin_claude(
-            plugin, name, home=home, apply=apply, replace=replace, recovery_root=recovery_root
+            plugin, name, home=home, apply=apply, replace=replace, recovery_root=recovery_root,
+            select_skills=set(skills), select_mcps=set(mcps), reset_overrides=reset_overrides,
         )
+    if skills or mcps:
+        raise AgentPackError("--skill / --mcp selection is supported for the claude client only")
     destination = _client_package_destination(client, home, name)
     action = "install-plugin"
     if destination.exists() or destination.is_symlink():
@@ -1103,6 +1113,9 @@ def _install_plugin_claude(
     apply: bool,
     replace: bool,
     recovery_root: Path | None,
+    select_skills: set[str] | None = None,
+    select_mcps: set[str] | None = None,
+    reset_overrides: bool = False,
 ) -> dict[str, Any]:
     """Install a plugin into Claude Code as live links plus user-scope MCP entries.
 
@@ -1112,24 +1125,42 @@ def _install_plugin_claude(
     record ``~/.claude/agent-pack/plugins/<name>`` (symlink to the source root)
     that inventory uses to report the installed version.
     """
+    import agent_pack_claude  # noqa: PLC0415 - shipped next to this file
+
+    select_skills, select_mcps = select_skills or set(), select_mcps or set()
+    selective = bool(select_skills or select_mcps)
     record = _claude_plugin_records(home) / name
     links: list[tuple[str, str, Path, Path]] = [("plugin", name, record, plugin)]
+    available_skills: set[str] = set()
     skills_root = plugin / "skills"
     if skills_root.is_dir() and not skills_root.is_symlink():
         for child in sorted(skills_root.iterdir(), key=lambda item: item.name):
             if child.is_dir() and not child.name.startswith(".") and (child / "SKILL.md").is_file():
-                links.append(("skill", child.name, home / ".claude" / "skills" / child.name, child))
+                available_skills.add(child.name)
+                if not selective or child.name in select_skills:
+                    links.append(("skill", child.name, home / ".claude" / "skills" / child.name, child))
+    unknown_skills = select_skills - available_skills
+    if unknown_skills:
+        raise AgentPackError("plugin has no such Skill: " + ", ".join(sorted(unknown_skills)))
 
     config_path = _claude_user_config(home)
     servers: dict[str, dict[str, Any]] = {}
     mcp_path = plugin / "mcp.json"
     if mcp_path.is_file():
         data_root = home / ".claude" / "agent-pack" / "data" / name
-        for server, raw in sorted(_read_json(mcp_path).get("mcpServers", {}).items()):
+        declared = _read_json(mcp_path).get("mcpServers", {})
+        unknown_mcps = select_mcps - set(declared)
+        if unknown_mcps:
+            raise AgentPackError("plugin has no such MCP server: " + ", ".join(sorted(unknown_mcps)))
+        for server, raw in sorted(declared.items()):
+            if selective and server not in select_mcps:
+                continue
             parsed = _portable_mcp(server, raw)
             if not parsed.portable:
                 raise AgentPackError(f"MCP {server} is not portable: " + "; ".join(parsed.issues))
             servers[server] = _claude_mcp_config(parsed.config, record, data_root)
+    elif select_mcps:
+        raise AgentPackError("plugin has no mcp.json: " + ", ".join(sorted(select_mcps)))
 
     config: dict[str, Any] = {}
     if servers and config_path.exists():
@@ -1151,16 +1182,17 @@ def _install_plugin_claude(
         else:
             action = "link"
         operations.append({"action": f"{action}-{kind}", "client": "claude", "name": item_name, "to": str(path)})
+    entries: dict[str, dict[str, Any]] = {}
     for server, rendered in servers.items():
-        current = existing_servers.get(server)
-        if current is None:
-            action = "add"
-        elif current == rendered:
-            action = "keep"
-        else:
-            action = "replace"
+        state, entries[server], kept = agent_pack_claude.classify_mcp(
+            rendered, existing_servers.get(server), reset=reset_overrides)
+        action = {"differ": "replace"}.get(state, state)
+        if action == "replace":
             conflicts.append(f"mcp {server}: {config_path}")
-        operations.append({"action": f"{action}-mcp", "client": "claude", "name": server, "to": str(config_path)})
+        operation = {"action": f"{action}-mcp", "client": "claude", "name": server, "to": str(config_path)}
+        if kept:
+            operation["kept_overrides"] = kept
+        operations.append(operation)
     if conflicts and not replace:
         raise AgentPackError("Claude client already has different content: " + "; ".join(conflicts))
     result: dict[str, Any] = {"ok": True, "applied": apply, "operations": operations}
@@ -1192,8 +1224,8 @@ def _install_plugin_claude(
             os.symlink(target, path, target_is_directory=True)
             created.append(path)
         changed = {
-            server: rendered for server, rendered in servers.items()
-            if existing_servers.get(server) != rendered
+            server: entry for server, entry in entries.items()
+            if existing_servers.get(server) != entry
         }
         if changed:
             replaced = {server: existing_servers[server] for server in changed if server in existing_servers}
@@ -1287,12 +1319,23 @@ def reconcile_project(
     recovery_root: Path | None = None,
     apply: bool = False,
     retire_only: bool = False,
+    replace: bool = False,
+    reset_overrides: bool = False,
 ) -> dict[str, Any]:
     """Reconcile one project package and explicitly selected legacy components.
 
     ``retire_only`` archives the selected legacy components without installing
-    or replacing the project package itself.
+    or replacing the project package itself. Claude Code is handled by
+    ``agent_pack_claude`` (dedicated package, MCP entries, Skill links);
+    ``replace`` and ``reset_overrides`` only apply there.
     """
+    if client == "claude":
+        import agent_pack_claude  # noqa: PLC0415 - shipped next to this file
+
+        return agent_pack_claude.sync_project(
+            project, home=home, apply=apply, replace=replace, reset_overrides=reset_overrides,
+            recovery_root=recovery_root, retire_skills=retire_skills, retire_plugins=retire_plugins,
+            retire_only=retire_only)
     layout = load_project_layout(project)
     authority = inventory_project(layout.root)
     package_name = _package_name(layout.root)
@@ -1402,8 +1445,12 @@ def sync_project(
     *,
     home: Path | None = None,
     apply: bool = False,
+    replace: bool = False,
+    reset_overrides: bool = False,
+    recovery_root: Path | None = None,
 ) -> dict[str, Any]:
-    return reconcile_project(project, client, home=home, apply=apply)
+    return reconcile_project(project, client, home=home, apply=apply, replace=replace,
+                             reset_overrides=reset_overrides, recovery_root=recovery_root)
 
 
 def _update_personal_marketplace(home: Path, package_name: str) -> None:
@@ -1425,7 +1472,81 @@ def _update_personal_marketplace(home: Path, package_name: str) -> None:
     _write_json_atomic(marketplace, payload)
 
 
-def doctor(project: Path) -> dict[str, Any]:
+def _skill_fingerprints(package: Path) -> dict[str, str]:
+    root = package / "skills"
+    if not root.is_dir() or root.is_symlink():
+        return {}
+    found = {}
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and not child.is_symlink() and (child / "SKILL.md").is_file():
+            try:
+                found[child.name] = _tree_fingerprint(child)
+            except AgentPackError:
+                found[child.name] = "unreadable"
+    return found
+
+
+def _package_mcps(package: Path) -> dict[str, Any]:
+    path = package / "mcp.json"
+    if not path.is_file() or path.is_symlink():
+        return {}
+    try:
+        servers = _read_json(path).get("mcpServers", {})
+    except AgentPackError:
+        return {}
+    return servers if isinstance(servers, dict) else {}
+
+
+def client_drift(project: Path, client: str, home: Path | None = None) -> dict[str, Any]:
+    """Compare what a client has installed for this project with the project's authority.
+
+    Codex and Cursor load the project package directory, so the installed package
+    is compared with a freshly built one (Skills, MCP servers, the rest of the
+    files). Claude Code is compared entry by entry by ``agent_pack_claude``.
+    Same-name MCP servers configured by hand in the client are listed as native.
+    """
+    if client == "claude":
+        import agent_pack_claude  # noqa: PLC0415 - shipped next to this file
+
+        return agent_pack_claude.drift(project, home)
+    home = (home or Path.home()).expanduser().resolve()
+    layout = load_project_layout(project)
+    authority = inventory_project(layout.root)
+    name = _package_name(layout.root)
+    destination = _client_package_destination(client, home, name)
+    report: dict[str, Any] = {"client": client, "package": name, "missing": [], "different": [], "overrides": [],
+                              "stale": [], "native": [], "excluded": [], "dangling": [], "coupled": None}
+    report["excluded"] = sorted(item.name for item in authority.mcps
+                                if item.portable and not _mcp_allowed(layout, item.name, client))
+    with tempfile.TemporaryDirectory(prefix="agent-pack-drift-") as temporary:
+        expected = _build_package(authority, name, Path(temporary), client)
+        if destination.is_symlink() and not destination.exists():
+            report["dangling"].append(f"package {name}: {destination}")
+        elif not destination.is_dir():
+            report["missing"].append(f"package {name}")
+            report["missing"] += [f"skill {skill}" for skill in _skill_fingerprints(expected)]
+            report["missing"] += [f"mcp {server}" for server in _package_mcps(expected)]
+        elif _tree_fingerprint(expected) != _tree_fingerprint(destination):
+            want, have = _skill_fingerprints(expected), _skill_fingerprints(destination)
+            report["missing"] += [f"skill {skill}" for skill in sorted(set(want) - set(have))]
+            report["stale"] += [f"skill {skill}" for skill in sorted(set(have) - set(want))]
+            report["different"] += [f"skill {skill}" for skill in sorted(set(want) & set(have))
+                                    if want[skill] != have[skill]]
+            want_mcps, have_mcps = _package_mcps(expected), _package_mcps(destination)
+            report["missing"] += [f"mcp {server}" for server in sorted(set(want_mcps) - set(have_mcps))]
+            report["stale"] += [f"mcp {server}" for server in sorted(set(have_mcps) - set(want_mcps))]
+            report["different"] += [f"mcp {server}" for server in sorted(set(want_mcps) & set(have_mcps))
+                                    if want_mcps[server] != have_mcps[server]]
+            if not (report["missing"] or report["stale"] or report["different"]):
+                report["different"].append(f"package {name}: other files differ")
+        native = _codex_mcps(home) if client == "codex" else _json_client_mcps(home / ".cursor" / "mcp.json")
+        report["native"] = sorted(native)
+    report["in_sync"] = not (report["missing"] or report["different"] or report["stale"] or report["dangling"])
+    return report
+
+
+def doctor(project: Path, clients: Iterable[str] = (), home: Path | None = None) -> dict[str, Any]:
+    """Validate the project; with ``clients``, also report each client's drift from it."""
     layout = load_project_layout(project)
     inventory = inventory_project(layout.root)
     issues = list(inventory.issues)
@@ -1465,7 +1586,17 @@ def doctor(project: Path) -> dict[str, Any]:
                 issues.extend(f"credential env file missing key: {name}" for name in sorted(missing))
             except AgentPackError as exc:
                 issues.append(str(exc))
-    return {
+    reports: dict[str, Any] = {}
+    for client in dict.fromkeys(clients):
+        report = client_drift(layout.root, client, home)
+        reports[client] = report
+        for kind in ("missing", "different", "stale", "dangling"):
+            issues.extend(f"{client}: {kind} {item}" for item in report[kind])
+        if report["coupled"]:
+            issues.append(f"{client}: install record points into another package directory: {report['coupled']}")
+        warnings.extend(f"{client}: kept local override {item['name']} ({', '.join(item['keys'])})"
+                        for item in report["overrides"])
+    result: dict[str, Any] = {
         "ok": not issues,
         "source": inventory.source,
         "counts": {
@@ -1476,6 +1607,9 @@ def doctor(project: Path) -> dict[str, Any]:
         "issues": sorted(set(issues)),
         "warnings": sorted(set(warnings)),
     }
+    if reports:
+        result["clients"] = reports
+    return result
 
 
 def _print(value: dict[str, Any], output: str) -> None:
@@ -1508,6 +1642,9 @@ def build_parser() -> argparse.ArgumentParser:
 
     doctor_parser = sub.add_parser("doctor")
     doctor_parser.add_argument("--project", type=Path, default=Path.cwd())
+    doctor_parser.add_argument("--client", action="append", default=[], choices=("codex", "cursor", "claude"),
+                               help="also compare this client's installed capabilities with the project (repeatable)")
+    doctor_parser.add_argument("--home", type=Path)
 
     transfer_parser = sub.add_parser("transfer")
     transfer_parser.add_argument("--from", dest="source", required=True)
@@ -1519,9 +1656,14 @@ def build_parser() -> argparse.ArgumentParser:
 
     sync_parser = sub.add_parser("sync")
     sync_parser.add_argument("--project", type=Path, default=Path.cwd())
-    sync_parser.add_argument("--client", choices=("codex", "cursor"), required=True)
+    sync_parser.add_argument("--client", choices=("codex", "cursor", "claude"), required=True)
     sync_parser.add_argument("--home", type=Path)
     sync_parser.add_argument("--apply", action="store_true")
+    sync_parser.add_argument("--replace", action="store_true",
+                             help="claude: also replace Skills / MCP entries this package did not install")
+    sync_parser.add_argument("--reset-overrides", action="store_true",
+                             help="claude: drop local credential values (headers / env) instead of keeping them")
+    sync_parser.add_argument("--recovery-root", type=Path)
 
     bootstrap_parser = sub.add_parser("bootstrap")
     bootstrap_parser.add_argument("--plugin", type=Path, required=True)
@@ -1530,10 +1672,18 @@ def build_parser() -> argparse.ArgumentParser:
     bootstrap_parser.add_argument("--apply", action="store_true")
     bootstrap_parser.add_argument("--replace", action="store_true")
     bootstrap_parser.add_argument("--recovery-root", type=Path)
+    bootstrap_parser.add_argument("--skill", action="append", default=[], help="claude: install only this Skill")
+    bootstrap_parser.add_argument("--mcp", action="append", default=[], help="claude: install only this MCP server")
+    bootstrap_parser.add_argument("--reset-overrides", action="store_true",
+                                  help="claude: drop local credential values (headers / env) instead of keeping them")
 
     reconcile_parser = sub.add_parser("reconcile")
     reconcile_parser.add_argument("--project", type=Path, default=Path.cwd())
-    reconcile_parser.add_argument("--client", choices=("codex", "cursor"), required=True)
+    reconcile_parser.add_argument("--client", choices=("codex", "cursor", "claude"), required=True)
+    reconcile_parser.add_argument("--replace", action="store_true",
+                                  help="claude: also replace Skills / MCP entries this package did not install")
+    reconcile_parser.add_argument("--reset-overrides", action="store_true",
+                                  help="claude: drop local credential values (headers / env) instead of keeping them")
     reconcile_parser.add_argument("--home", type=Path)
     reconcile_parser.add_argument("--retire-skill", action="append", default=[])
     reconcile_parser.add_argument("--retire-plugin", action="append", default=[])
@@ -1554,7 +1704,7 @@ def main(argv: list[str] | None = None) -> int:
             result = inventory_source(args.source, args.home).to_dict()
             result["ok"] = not result["issues"]
         elif args.command == "doctor":
-            result = doctor(args.project)
+            result = doctor(args.project, args.client, args.home)
         elif args.command == "transfer":
             if not args.skill and not args.mcp:
                 raise AgentPackError("select at least one --skill or --mcp")
@@ -1567,7 +1717,8 @@ def main(argv: list[str] | None = None) -> int:
             )
         elif args.command == "sync":
             result = sync_project(
-                args.project, args.client, home=args.home, apply=args.apply
+                args.project, args.client, home=args.home, apply=args.apply, replace=args.replace,
+                reset_overrides=args.reset_overrides, recovery_root=args.recovery_root,
             )
         elif args.command == "bootstrap":
             result = install_plugin(
@@ -1577,6 +1728,9 @@ def main(argv: list[str] | None = None) -> int:
                 apply=args.apply,
                 replace=args.replace,
                 recovery_root=args.recovery_root,
+                skills=args.skill,
+                mcps=args.mcp,
+                reset_overrides=args.reset_overrides,
             )
         else:
             result = reconcile_project(
@@ -1588,6 +1742,8 @@ def main(argv: list[str] | None = None) -> int:
                 recovery_root=args.recovery_root,
                 apply=args.apply,
                 retire_only=args.retire_only,
+                replace=args.replace,
+                reset_overrides=args.reset_overrides,
             )
         _print(result, args.output)
         return 0 if result.get("ok", True) else 1

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.6.1",
+  "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/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.6.1",
+  "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（项目初始化）

package/runtime/plugins/agents-init/skills/agents-init/skill.json

@@ -1,9 +1,9 @@
 {
   "id": "agents-init",
-  "name": "agents-init v6 / Project Profile 初始化与迁移",
-  "description": "创建或迁移通用项目骨架与 Project Profile；随包 opinion-manager 管理用户确认的 Agent 行为规则。",
+  "name": "agents-init v6 / Project Profile initialization and migration",
+  "description": "Create or migrate a general project skeleton and Project Profile; the bundled opinion-manager manages user-confirmed Agent behavior rules.",
   "schema_version": "1.0",
-  "version": "6.6.0",
+  "version": "6.6.1",
   "status": "stable",
   "language": "zh-CN",
   "license": "MIT",

package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json

@@ -1,15 +1,15 @@
 {
   "name": "opinion-manager",
-  "version": "0.4.1",
-  "description": "选择模板变体与精确版本，管理个人 Profile、锁定快照和升级预览。",
+  "version": "0.4.2",
+  "description": "Choose template variants and exact versions; manage personal Profiles, locked snapshots and upgrade previews.",
   "author": {
     "name": "lc4t"
   },
   "skills": "./skills/",
   "interface": {
     "displayName": "Opinion Manager",
-    "shortDescription": "生成、组合、审查与维护 Agent 行为规则",
-    "longDescription": "提供经过批准的可选规则与模板；三个主入口为直接用模板、选择部分条目、从空白开始，另可基于已授权记忆提出候选。完整内容集中确认，工具分别核验指纹；支持不可变版本、个人 Profile、锁和升级保护。公开内容仍需用户逐文件批准。",
+    "shortDescription": "Generate, compose, review and maintain Agent behavior rules",
+    "longDescription": "Offers approved, selectable rules and templates. Three main entry points: use a template as is, pick some of its items, or start from blank; candidates can also be proposed from authorized memory. The full content is confirmed once, and each fingerprint is verified by the tool; supports immutable versions, personal Profiles, locks and upgrade protection. Public content still needs the user's file-by-file approval. 中文：提供经过批准的可选规则与模板；三个主入口为直接用模板、选择部分条目、从空白开始，另可基于已授权记忆提出候选。完整内容集中确认，工具分别核验指纹；支持不可变版本、个人 Profile、锁和升级保护。公开内容仍需用户逐文件批准。",
     "developerName": "lc4t",
     "category": "Productivity",
     "capabilities": [
@@ -21,6 +21,6 @@
       "opinion-lock",
       "upgrade-preview"
     ],
-    "defaultPrompt": "使用 $opinion-manager 为当前环境生成或维护 OPINION.md。"
+    "defaultPrompt": "Use $opinion-manager to generate or maintain OPINION.md for this environment."
   }
 }

package/runtime/plugins/opinion-manager/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "opinion-manager",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Manage Agent behavior rules through templates, partial selection, blank iteration, and authorized-memory candidates, with complete previews and exact version locks.",
   "author": {
     "name": "lc4t"

package/runtime/plugins/opinion-manager/skills/opinion-manager/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opinion-manager
-description: 生成、组合、审查和维护用户与 Agent 之间的行为规则。用户要求创建或更新 OPINION.md、导入既有说明、直接用模板、选择部分条目、从空白开始、基于已授权记忆提出候选规则、维护个人 Profile、检查升级与冲突或按当前 Opinion 审查交付物时使用。
+description: Generate, compose, review and maintain behavior rules between the user and the Agent. Use when the user asks to create or update OPINION.md, import existing instructions, apply a template directly, pick some of its items, start from blank, propose rule candidates from authorized memory, maintain a personal Profile, check upgrades and conflicts, or review a deliverable against the current Opinion. 中文：生成、组合、审查和维护用户与 Agent 之间的行为规则。用户要求创建或更新 OPINION.md、导入既有说明、直接用模板、选择部分条目、从空白开始、基于已授权记忆提出候选规则、维护个人 Profile、检查升级与冲突或按当前 Opinion 审查交付物时使用。
 ---
 
 # Opinion Manager（Agent 行为规则管理）

package/runtime/plugins/opinion-manager/skills/opinion-manager/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Opinion Manager"
-  short_description: "选择规则模板变体和版本，生成完整 Opinion 并审阅升级"
-  default_prompt: "使用 $opinion-manager 为当前环境生成或维护 OPINION.md。"
+  short_description: "Generate, compose, review and maintain Agent behavior rules"
+  default_prompt: "Use $opinion-manager to generate or maintain OPINION.md for this environment."