@sakanano-moe/agenthelm 6.5.2 → 6.6.0

package/bin/agenthelm.js

@@ -5,7 +5,7 @@ const { spawnSync } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { join } = require("node:path");
 
-const script = join(__dirname, "..", "runtime", "agenthelm.py");
+const script = join(__dirname, "..", "runtime", "plugins", "agent-pack", "runtime", "agenthelm.py");
 if (!existsSync(script)) {
   console.error("agenthelm: runtime is missing from this package; reinstall @sakanano-moe/agenthelm.");
   process.exit(2);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sakanano-moe/agenthelm",
-  "version": "6.5.2",
-  "description": "agenthelm 命令行：在 Claude Code、Codex、Cursor 间安装、检查与更新 agenthelm 项目管理插件。",
+  "version": "6.6.0",
+  "description": "agenthelm 命令行：安装、检查与更新 agenthelm 插件；用户级运行时；不需要 AI Agent 的项目入口（agenthelm project）。",
   "license": "MIT",
   "bin": {
     "agenthelm": "bin/agenthelm.js"

package/runtime/index.json

@@ -0,0 +1,80 @@
+{
+  "site": {
+    "id": "agenthelm",
+    "name": "agenthelm",
+    "description": "跨 Agent 的项目管理插件集：项目契约、生命周期、扩展能力与行为规则。",
+    "version": "0.7.0",
+    "updated_at": "2026-10-25",
+    "homepage": "./index.html",
+    "domain": "agenthelm.sakanano.moe",
+    "legacy_domain": "skill.sakanano.moe"
+  },
+  "plugin": {
+    "manifest": "./plugins/agents-init/plugin.json",
+    "version": "6.6.0",
+    "install_unit": "marketplace",
+    "bundled_plugins": [
+      "./plugins/project-orchestrator/plugin.json",
+      "./plugins/agent-pack/plugin.json",
+      "./plugins/opinion-manager/plugin.json"
+    ],
+    "agent_install": "./INSTALL.md",
+    "llms": "./llms.txt",
+    "bootstrap_and_init": "./scripts/bootstrap_and_init.py",
+    "marketplace": "./.claude-plugin/marketplace.json",
+    "latest": "./latest.json",
+    "cli": "npx @sakanano-moe/agenthelm"
+  },
+  "skills": [
+    {
+      "id": "agents-init",
+      "name": "agents-init v6 / Project Profile 初始化与迁移",
+      "description": "创建或迁移项目骨架；写入前验证同包 project-orchestrator、agent-pack 与 opinion-manager。",
+      "version": "6.6.0",
+      "status": "stable",
+      "entrypoints": {
+        "browser": "./plugins/agents-init/skills/agents-init/index.html",
+        "agent": "./plugins/agents-init/skills/agents-init/SKILL.md",
+        "metadata": "./plugins/agents-init/skills/agents-init/skill.json",
+        "template": "./plugins/agents-init/skills/agents-init/AGENT.template.md"
+      }
+    },
+    {
+      "id": "project-orchestrator",
+      "name": "project-orchestrator / 项目生命周期编排",
+      "description": "按项目模式组织 Case 工作目录或兼容既有 Task/Case；提供检索、无损迁移、验证与受控 Git 交付；附不需要 AI Agent 的项目入口（找资料、看进展、指南、检查、维护与记录）。",
+      "version": "1.8.0",
+      "status": "stable",
+      "entrypoints": {
+        "agent": "./plugins/project-orchestrator/skills/project-orchestrator/SKILL.md",
+        "metadata": "./plugins/project-orchestrator/plugin.json",
+        "runtime": "./plugins/project-orchestrator/runtime/project_cli.py"
+      }
+    },
+    {
+      "id": "agent-pack",
+      "name": "agent-pack / Agent 扩展能力管理",
+      "description": "在项目与 Codex / Cursor / Claude 之间盘点、校验、安装、同步、迁移与对账 Plugin、Skill、MCP；agenthelm 命令行与用户级运行时。",
+      "version": "1.7.0",
+      "status": "stable",
+      "entrypoints": {
+        "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
+        "metadata": "./plugins/agent-pack/plugin.json",
+        "mcp": "./plugins/agent-pack/mcp.json",
+        "reference": "./plugins/agent-pack/references/capability-config.md"
+      }
+    },
+    {
+      "id": "opinion-manager",
+      "name": "opinion-manager / Agent 行为规则管理",
+      "description": "三个首次主入口与可选记忆候选；一次内容确认后分别保存 Profile、正文与锁，支持精确版本和个人修改保护；可选的分层加载与项目私有的候选、灰度记账。",
+      "version": "0.4.1",
+      "status": "experimental",
+      "entrypoints": {
+        "agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",
+        "metadata": "./plugins/opinion-manager/plugin.json",
+        "runtime": "./plugins/opinion-manager/runtime/opinion_manager.py"
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,19 @@
+{
+  "name": "agent-pack",
+  "version": "1.7.0",
+  "description": "Deterministic Agent-extension capability management for configured workspaces.",
+  "author": {
+    "name": "lc4t"
+  },
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Agent Pack",
+    "shortDescription": "盘点 / 校验 / 安装 / 同步 / 迁移 Agent Plugin、Skill 与 MCP",
+    "longDescription": "确定性的 Agent 扩展能力管理器：在项目、插件目录与 Codex / Cursor 客户端之间 inventory / doctor / bootstrap / sync / transfer / reconcile。所有写操作默认 dry-run，重名与含密钥的 MCP 条目失败关闭。项目生命周期（Task/Case/路由/验证/Git）由 project-orchestrator 承担，不在本包内。",
+    "developerName": "lc4t",
+    "category": "Developer Tools",
+    "capabilities": ["capability-inventory", "capability-doctor", "plugin-bootstrap", "client-sync", "skill-transfer", "capability-reconcile"],
+    "defaultPrompt": "Use $agent-pack to inventory this project's Agent Plugins, Skills, and MCP servers and report drift against the declared contract."
+  }
+}

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

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "agent-pack": {
+      "command": "python3",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/runtime/mcp_server.py"],
+      "env": {
+        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/runtime"
+      },
+      "cwd": "${CLAUDE_PLUGIN_ROOT}"
+    }
+  }
+}

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

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/runtime/agenthelm.py\" check --hook --hook-format claude-hook",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "agent-pack": {
+      "type": "stdio",
+      "command": "python3",
+      "args": ["${PLUGIN_ROOT}/runtime/mcp_server.py"],
+      "env": {
+        "PYTHONPATH": "${PLUGIN_ROOT}/runtime"
+      },
+      "cwd": "${PLUGIN_ROOT}"
+    }
+  }
+}

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

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "agent-pack",
+  "version": "1.7.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"
+  },
+  "repository": "https://github.com/lc4t/agenthelm",
+  "license": "MIT",
+  "keywords": [
+    "agent-pack",
+    "agent-plugins",
+    "mcp",
+    "capability-management",
+    "inventory",
+    "doctor",
+    "bootstrap"
+  ]
+}

package/runtime/plugins/agent-pack/references/capability-config.md

@@ -0,0 +1,124 @@
+# Agent 能力配置
+
+仅在盘点、迁移、同步或验证 Agent Plugin、Skill、MCP 时读取本参考。
+
+## 可移植项目结构
+
+`agents-init v5` 创建以下能力包：
+
+```text
+.agents/
+├── plugin.json
+├── skills/
+├── mcp.json
+└── moe.sakanano.agent-pack/
+    └── project.json
+```
+
+- `plugin.json` 与 `mcp.json` 面向 Agent Plugins 1.0.0。
+- `skills/` 的直接子目录包含 `SKILL.md`。
+- `project.json` 是客户端扩展，也是机器可读的 Project Profile。
+- 个人偏好和凭据禁止进入可移植公开模板。
+
+## CLI
+
+从已加载 Skill 解析插件根目录，再运行：
+
+```bash
+python3 <plugin-root>/runtime/agent_pack_config.py --output json inventory --source project:/path/to/project
+python3 <plugin-root>/runtime/agent_pack_config.py --output json inventory --source client:codex
+python3 <plugin-root>/runtime/agent_pack_config.py --output json inventory --source client:cursor
+python3 <plugin-root>/runtime/agent_pack_config.py --output json inventory --source client:claude
+python3 <plugin-root>/runtime/agent_pack_config.py --output json doctor --project /path/to/project
+```
+
+runtime 尚未安装时，bootstrap 包含本 Skill 的插件：
+
+```bash
+python3 /path/to/agent-pack/runtime/agent_pack_config.py --output json bootstrap \
+  --plugin /path/to/agent-pack --client codex
+python3 /path/to/agent-pack/runtime/agent_pack_config.py --output json bootstrap \
+  --plugin /path/to/agent-pack --client codex --apply
+```
+
+`--client` 可取 `codex`、`cursor`、`claude`。Claude Code 没有 Agent Plugins 加载器，`bootstrap --client claude` 把插件投影成它实际读取的三处：
+
+- `~/.claude/skills/<skill>` → 源插件 `skills/<skill>` 的符号链接；
+- `~/.claude/agent-pack/plugins/<name>` → 源插件根目录的符号链接（安装记录，`inventory --source client:claude` 从这里读已安装版本）；
+- 插件 `mcp.json` 中每个 server 写入 `~/.claude.json#mcpServers`（user scope）：`${PLUGIN_ROOT}` 展开为安装记录路径，`streamable-http` 映射为 `http`，丢弃 Claude 不支持的 `cwd`；其他 `${VAR}` 原样保留，由 Claude 启动时从进程环境展开。写入保留文件原权限。
+
+Claude 端是**活链接**，不固定副本：源目录改动立即生效，版本即源 `plugin.json#version`。已存在但内容不同的链接或 MCP 条目需要 `--replace`，旧内容进入 `~/.agent-pack/recovery/<stamp>-claude-<name>/`（`replaced-skills/`、`replaced-plugins/`、`replaced-mcp.json`）。装完需重启 Claude Code 才会加载新 Skill / MCP。`sync` / `reconcile` 的项目包仍只支持 Codex 与 Cursor。
+
+在来源与已初始化项目之间迁移选中的组件：
+
+```bash
+# 预演
+python3 <plugin-root>/runtime/agent_pack_config.py --output json transfer \
+  --from client:codex --to-project /path/to/project --skill example-skill
+
+# 审阅预演结果后再应用
+python3 <plugin-root>/runtime/agent_pack_config.py --output json transfer \
+  --from project:/path/to/source --to-project /path/to/destination \
+  --skill example-skill --mcp example-server --apply
+```
+
+为客户端构建并安装项目的可移植能力：
+
+```bash
+# 预演
+python3 <plugin-root>/runtime/agent_pack_config.py --output json sync \
+  --project /path/to/project --client cursor
+
+# 获得授权后应用
+python3 <plugin-root>/runtime/agent_pack_config.py --output json sync \
+  --project /path/to/project --client cursor --apply
+```
+
+迁移时使用 `reconcile` 分类目标，并归档明确选择的旧组件。默认只生成只读计划：
+
+```bash
+python3 <plugin-root>/runtime/agent_pack_config.py --output json reconcile \
+  --project /path/to/project --client cursor \
+  --retire-skill work-engine --retire-skill ai-config-sync
+
+python3 <plugin-root>/runtime/agent_pack_config.py --output json reconcile \
+  --project /path/to/project --client cursor \
+  --retire-skill work-engine --retire-skill ai-config-sync --apply
+```
+
+只退役旧组件、不安装或替换项目包时加 `--retire-only`（至少需要一个 `--retire-skill` / `--retire-plugin`）：
+
+```bash
+python3 <plugin-root>/runtime/agent_pack_config.py --output json reconcile \
+  --project /path/to/project --client cursor --retire-plugin project-runtime --retire-only --apply
+```
+
+结果把组件分为 `exact`、`conflict`、`missing`、`native_only` 与 `blocked`。替换包和明确退役的组件移动到 `~/.agent-pack/recovery/`；事务失败时自动恢复。
+
+Codex 同步会写入 `~/.agents/plugins/plugins/<name>` 可移植包、`.codex-plugin` adapter 与 `~/.agents/plugins/marketplace.json` 的 `personal` 条目。之后需在 Codex 桌面版的插件设置里启用 / 重新同步 `<name>@personal`（并确认 `~/.codex/config.toml` 有 `[plugins."<name>@personal"] enabled = true`）来激活；同步只更新 marketplace 源，Codex 自身缓存 `~/.codex/plugins/cache/personal/` 要到下次激活或重启才追平。homebrew 版 `codex-cli` 无 `codex plugin` 子命令，`plugin` / `marketplace` 命令与 UI 随 Codex 版本变化，以当前 Codex 文档为准。Cursor 同步会在本地插件根目录安装真实的 Agent Plugin 目录。
+
+## MCP Tool
+
+随附的 stdio server 暴露以下 Tool：
+
+- `agent_pack_inventory`
+- `agent_pack_doctor`
+- `agent_pack_transfer`
+- `agent_pack_sync`
+- `agent_pack_bootstrap`
+- `agent_pack_reconcile`
+
+所有会修改状态的 MCP Tool 默认使用 `apply=false`。必须先展示并审阅操作计划，才能使用 `apply=true` 重试。
+
+## 安全与碰撞规则
+
+- 禁止把原生客户端 MCP 配置中的凭据复制进可移植包。
+- 拒绝包含疑似密钥环境变量、header 或 token 字面值的 MCP 条目。
+- 迁移期间禁止跟随指向来源 Skill 目录之外的 symlink。
+- 禁止静默覆盖现有 Skill、MCP 名称、Agent Plugin、客户端包或 marketplace 条目。
+- 在 `native_mcp_sources` 中声明历史或客户端专属 MCP 文件。可移植条目成为打包候选；包含密钥的条目保持为 `blocked`/doctor warning，并留在客户端本地。
+- 原生 MCP 来源可以使用 `__PROJECT_DIR__` 与 `__REPO_ROOT__`；源文件保留占位符，生成客户端包时解析为当前本地项目路径。
+- 把 `credential_env_file` 设置为项目相对路径的 dotenv 文件，权限必须为 `0600`。生成包只保存 `${VAR}` 引用；本地 launcher 在 MCP 启动时读取值，禁止复制进 Git 或插件 manifest。
+- 使用 `mcp_client_policy.<server>.include` 或 `.exclude` 完成客户端路由。禁止在 MCP 定义中放入 adapter 专属 `_skip` 字段。
+- `${PLUGIN_ROOT}` 用于不可变包文件，`${PLUGIN_DATA}` 用于客户端管理的可写状态。
+- 客户端原生 adapter 只在安装阶段使用；Agent Plugins 1.0 文件保持权威源地位。

package/runtime/{agenthelm.py → plugins/agent-pack/runtime/agenthelm.py}

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 """agenthelm：在 Claude Code、Codex、Cursor 间安装、检查与更新 agenthelm 插件。
 
-``check`` 只读：比较各客户端已安装的插件版本、项目里由模板渲染的文件，
+``project`` 打开不需要 AI Agent 的项目自助入口（由 project-orchestrator 实现）；``runtime``
+管理用户级运行时。``check`` 只读：比较各客户端已安装的插件版本、项目里由模板渲染的文件，
 以及 Opinion 来源与云端 ``latest.json``。``install``、``update``、``migrate``
 默认只预览，``--apply`` 才执行。通过 ``npx @sakanano-moe/agenthelm <命令>`` 或
 ``python3 <agent-pack>/runtime/agenthelm.py <命令>`` 运行。``--hook`` 供会话开始时静默调用：
@@ -255,7 +256,9 @@ def plugin_findings(latest: dict, installed: list[dict]) -> list[dict]:
     for item in installed:
         target = latest.get("plugins", {}).get(item["plugin"], {}).get("version")
         current = item.get("version") or ""
-        if target is None:
+        if item["client"] == "legacy":
+            status = "legacy"  # a pre-marketplace copy: it gets migrated, not updated
+        elif target is None:
             status = "unknown"
         elif is_newer(target, current):
             status = "behind"
@@ -421,7 +424,11 @@ def render_text(report: dict) -> str:
     if not report["plugins"]:
         lines.append("未发现已安装的 agenthelm 插件。")
     for item in report["plugins"]:
-        label = {"behind": "可更新", "current": "最新", "ahead": "高于云端", "unknown": "版本未知"}[item["status"]]
+        label = {"behind": "可更新", "current": "最新", "ahead": "高于云端", "unknown": "版本未知",
+                 "legacy": "旧方式安装，待迁移"}[item["status"]]
+        if item["status"] == "legacy":
+            lines.append(f"  [旧方式] {item['plugin']} {item.get('version')}  {label}")
+            continue
         line = f"  [{item['client']}] {item['plugin']} {item.get('version')} → {item.get('latest')}  {label}"
         if item["status"] == "behind":
             kinds = {"code": "代码", "content": "仅模板/样例", "both": "代码与模板"}
@@ -436,8 +443,6 @@ def render_text(report: dict) -> str:
             hint = UPDATE_HINTS.get(item["client"])
             if hint:
                 line += f"\n      更新：{hint.format(plugin=item['plugin'])}"
-        elif item["client"] == "legacy":
-            line += f"\n      旧方式安装：{UPDATE_HINTS['legacy']}"
         lines.append(line)
     for item in report["content"]:
         if item.get("pack") is None:
@@ -458,6 +463,8 @@ def render_text(report: dict) -> str:
     if not report["plugins"]:
         lines.append(f"运行 `{CLI} install` 预览安装。")
     else:
+        if any(item["status"] == "legacy" for item in report["plugins"]):
+            lines.append(f"旧方式安装可用 `{UPDATE_HINTS['legacy']}` 预览迁移。")
         lines.append(one_line(report) or "全部为最新。")
     return "\n".join(lines) + "\n"
 
@@ -512,9 +519,9 @@ def github_slug(latest: dict) -> str:
 
 def detect_clients(env: Env) -> list[str]:
     found = []
-    if shutil.which("claude") or env.claude_dir.is_dir():
+    if find_cli(env, "claude") or env.claude_dir.is_dir():
         found.append("claude")
-    if shutil.which("codex") or env.codex_dir.is_dir():
+    if find_cli(env, "codex") or env.codex_dir.is_dir():
         found.append("codex")
     if (env.home / ".cursor").is_dir():
         found.append("cursor")
@@ -608,8 +615,34 @@ class Step:
         return data
 
 
-def _need(binary: str) -> str | None:
-    return None if shutil.which(binary) else f"未找到 {binary} 命令"
+def known_cli_locations(env: Env, name: str) -> list[Path]:
+    """Where a client's command line lives when it is not on PATH (GUI apps, per-user installs)."""
+    home = env.home
+    if name == "codex":
+        bundle = "ChatGPT.app/Contents/Resources/codex-cli/bin/codex"
+        return [Path("/Applications") / bundle, home / "Applications" / bundle,
+                home / ".local/bin/codex", Path("/opt/homebrew/bin/codex"), Path("/usr/local/bin/codex")]
+    return [home / ".local/bin" / name, Path("/opt/homebrew/bin") / name, Path("/usr/local/bin") / name]
+
+
+def find_cli(env: Env, name: str) -> str | None:
+    """A client's command line: ``AGENTHELM_<NAME>`` override, then PATH, then the usual app locations."""
+    override = env.get(f"AGENTHELM_{name.upper()}")
+    if override and os.access(override, os.X_OK):
+        return override
+    on_path = shutil.which(name, path=env.get("PATH") or "")
+    if on_path:
+        return on_path
+    for candidate in known_cli_locations(env, name):
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return str(candidate)
+    return None
+
+
+def _cli(env: Env, name: str, *args: str) -> tuple[list[str], str | None]:
+    """The command (using the resolved executable) and why it cannot run, if it cannot."""
+    found = find_cli(env, name)
+    return [found or name, *args], (None if found else f"未找到 {name} 命令（已查 PATH 与常见安装位置；可用 AGENTHELM_{name.upper()} 指定）")
 
 
 def install_steps(env: Env, latest: dict, clients: list[str], plugins: list[str], source: Path | None,
@@ -618,17 +651,17 @@ def install_steps(env: Env, latest: dict, clients: list[str], plugins: list[str]
     steps: list[Step] = []
     for client in clients:
         if client == "claude":
-            steps.append(Step("install", "claude", f"Claude Code 添加 agenthelm 市场（{slug}）",
-                              ["claude", "plugin", "marketplace", "add", slug], blocked=_need("claude")))
+            command, blocked = _cli(env, "claude", "plugin", "marketplace", "add", slug)
+            steps.append(Step("install", "claude", f"Claude Code 添加 agenthelm 市场（{slug}）", command, blocked=blocked))
             for plugin in plugins:
-                steps.append(Step("install", "claude", f"Claude Code 安装 {plugin}",
-                                  ["claude", "plugin", "install", f"{plugin}@{MARKETPLACE}"], blocked=_need("claude")))
+                command, blocked = _cli(env, "claude", "plugin", "install", f"{plugin}@{MARKETPLACE}")
+                steps.append(Step("install", "claude", f"Claude Code 安装 {plugin}", command, blocked=blocked))
         elif client == "codex":
-            steps.append(Step("install", "codex", f"Codex 添加 agenthelm 市场（{slug}）",
-                              ["codex", "plugin", "marketplace", "add", slug], blocked=_need("codex")))
+            command, blocked = _cli(env, "codex", "plugin", "marketplace", "add", slug)
+            steps.append(Step("install", "codex", f"Codex 添加 agenthelm 市场（{slug}）", command, blocked=blocked))
             for plugin in plugins:
-                steps.append(Step("install", "codex", f"Codex 安装 {plugin}",
-                                  ["codex", "plugin", "add", f"{plugin}@{MARKETPLACE}"], blocked=_need("codex")))
+                command, blocked = _cli(env, "codex", "plugin", "add", f"{plugin}@{MARKETPLACE}")
+                steps.append(Step("install", "codex", f"Codex 安装 {plugin}", command, blocked=blocked))
         elif client == "cursor":
             steps.append(cursor_step(latest, plugins, source, home, "安装"))
     return steps
@@ -655,17 +688,16 @@ def update_steps(env: Env, report: dict, project: Path | None, source: Path | No
     if only in (None, "plugins"):
         claude = sorted({item["plugin"] for item in behind if item["client"] == "claude"})
         if claude:
-            steps.append(Step("update", "claude", "刷新 Claude Code 的 agenthelm 市场",
-                              ["claude", "plugin", "marketplace", "update", MARKETPLACE], blocked=_need("claude")))
+            command, blocked = _cli(env, "claude", "plugin", "marketplace", "update", MARKETPLACE)
+            steps.append(Step("update", "claude", "刷新 Claude Code 的 agenthelm 市场", command, blocked=blocked))
             for item in [entry for entry in behind if entry["client"] == "claude"]:
-                command = ["claude", "plugin", "update", f"{item['plugin']}@{MARKETPLACE}"]
-                if item.get("scope") and item["scope"] != "user":
-                    command += ["--scope", item["scope"]]
+                extra = ["--scope", item["scope"]] if item.get("scope") and item["scope"] != "user" else []
+                command, blocked = _cli(env, "claude", "plugin", "update", f"{item['plugin']}@{MARKETPLACE}", *extra)
                 steps.append(Step("update", "claude", f"Claude Code 更新 {item['plugin']} → {item['latest']}",
-                                  command, blocked=_need("claude")))
+                                  command, blocked=blocked))
         if any(item["client"] == "codex" for item in behind):
-            steps.append(Step("update", "codex", "Codex 升级 agenthelm 市场与已装插件",
-                              ["codex", "plugin", "marketplace", "upgrade", MARKETPLACE], blocked=_need("codex")))
+            command, blocked = _cli(env, "codex", "plugin", "marketplace", "upgrade", MARKETPLACE)
+            steps.append(Step("update", "codex", "Codex 升级 agenthelm 市场与已装插件", command, blocked=blocked))
         cursor = sorted({item["plugin"] for item in behind if item["client"] == "cursor"})
         if cursor:
             steps.append(cursor_step(latest, cursor, source, home, "更新"))
@@ -799,6 +831,10 @@ def legacy_artifacts(env: Env, names: set[str]) -> list[dict]:
                           "path": str(env.home / ".agents/plugins/marketplace.json")})
     for name in _codex_personal_sections(env, names):
         artifacts.append({"kind": "codex-config-section", "name": name, "path": str(env.codex_dir / "config.toml")})
+    for name in sorted(names):
+        cache = env.codex_dir / "plugins" / "cache" / "personal" / name
+        if cache.is_dir() and not cache.is_symlink():
+            artifacts.append({"kind": "codex-personal-cache", "name": name, "path": str(cache)})
     try:
         servers = read_json(env.home / ".claude.json").get("mcpServers", {})
     except (OSError, ValueError, AttributeError):
@@ -827,10 +863,17 @@ def retire_legacy(env: Env, artifacts: list[dict], recovery: Path) -> list[dict]
     done: list[dict] = []
     backed_up: set[str] = set()
 
+    def inside_recovery(path: Path) -> Path:
+        """The path below the recovery folder: home-relative, or absolute for locations outside home."""
+        try:
+            return path.relative_to(env.home)
+        except ValueError:
+            return Path("external") / str(path).lstrip("/")
+
     def backup(path: Path) -> None:
         if str(path) in backed_up:
             return
-        target = recovery / "files" / path.relative_to(env.home)
+        target = recovery / "files" / inside_recovery(path)
         target.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy2(path, target)
         backed_up.add(str(path))
@@ -840,8 +883,8 @@ def retire_legacy(env: Env, artifacts: list[dict], recovery: Path) -> list[dict]
         if item.get("manual"):
             done.append({**item, "status": "manual"})
             continue
-        if item["kind"] in {"plugin-copy", "plugin-record", "claude-skill-link"}:
-            target = recovery / "moved" / path.relative_to(env.home)
+        if item["kind"] in {"plugin-copy", "plugin-record", "claude-skill-link", "codex-personal-cache"}:
+            target = recovery / "moved" / inside_recovery(path)
             target.parent.mkdir(parents=True, exist_ok=True)
             os.replace(path, target)
             done.append({**item, "status": "moved", "to": str(target)})
@@ -961,6 +1004,10 @@ def parser() -> argparse.ArgumentParser:
     doctor_parser = sub.add_parser("doctor", help="报告重复安装、版本不一致、旧方式残留与检查开关")
     common(doctor_parser)
 
+    sub.add_parser("runtime", add_help=False,
+                   help="用户级运行时：install / update / use / status（日常只需要 Python，不经过 npx）")
+    sub.add_parser("project", add_help=False,
+                   help="项目自助入口：找资料、看进展、项目指南、检查（不需要 AI Agent；详见 project --help）")
     locate_parser = sub.add_parser("locate", help="输出插件的已安装位置（最新优先），供下游脚本查找")
     locate_parser.add_argument("plugin")
     locate_parser.add_argument("--version", help="只要这个版本")
@@ -992,7 +1039,43 @@ def _print_steps(results: list[dict], apply: bool) -> None:
         print("以上为预览；确认后追加 --apply 执行。")
 
 
+def run_project(argv: list[str]) -> int:
+    """``agenthelm project``: hand over to project-orchestrator's project entry, which owns it."""
+    installed = installed_plugins(current_env(), {"project-orchestrator"})
+    copies = [PLUGIN_ROOT.parent / "project-orchestrator", *(Path(item["path"]) for item in installed)]
+    # Older copies predate the project entry; only those that ship it count.
+    usable = [path for path in copies if (path / "runtime" / "project_cli.py").is_file()]
+    if not usable:
+        stale = any((path / "plugin.json").is_file() for path in copies)
+        found = "（已安装的 project-orchestrator 版本过旧）" if stale else ""
+        print(f"agenthelm project 需要 project-orchestrator 的项目入口，但没有找到{found}。\n"
+              f"  · 更新插件：{CLI} update，或从发布包安装运行时（见 INSTALL.md）", file=sys.stderr)
+        return 3
+    # Prefer the copy shipped next to this agent-pack (same release), then the newest installed one.
+    sibling = PLUGIN_ROOT.parent / "project-orchestrator"
+    newest = sibling if sibling in usable else \
+        max(usable, key=lambda path: version_key(_manifest_version(path) or "") or (0,))
+    sys.path.insert(0, str(newest / "runtime"))
+    import project_cli  # noqa: PLC0415  located at run time
+
+    project_cli.HOST = sys.modules[__name__]
+    return project_cli.main(argv)
+
+
+def run_runtime(argv: list[str]) -> int:
+    """``agenthelm runtime``: the user-level runtime that project launchers use without any AI client."""
+    sys.path.insert(0, str(RUNTIME_DIR))
+    import agenthelm_runtime  # noqa: PLC0415 - shipped next to this file
+
+    return agenthelm_runtime.main(argv, sys.modules[__name__])
+
+
 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] == ["runtime"]:
+        return run_runtime(argv[1:])
     args = parser().parse_args(argv)
     env = current_env(args.home)
     home = env.home