@sakanano-moe/agenthelm 6.13.0 → 6.13.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sakanano-moe/agenthelm",
3
- "version": "6.13.0",
3
+ "version": "6.13.1",
4
4
  "description": "agenthelm CLI: install, check and update the agenthelm plugins for Claude Code, Codex and Cursor; a user-level runtime; and a project menu that works without any AI agent.",
5
5
  "license": "MIT",
6
6
  "bin": {
@@ -4,14 +4,14 @@
4
4
  "name": "agenthelm",
5
5
  "description": "Cross-agent project management plugins: project contract, lifecycle, extension capabilities and behavior rules. 跨 Agent 的项目管理插件集。",
6
6
  "version": "0.7.0",
7
- "updated_at": "2026-11-10",
7
+ "updated_at": "2026-11-15",
8
8
  "homepage": "./index.html",
9
9
  "domain": "agenthelm.sakanano.moe",
10
10
  "legacy_domain": "skill.sakanano.moe"
11
11
  },
12
12
  "plugin": {
13
13
  "manifest": "./plugins/agents-init/plugin.json",
14
- "version": "6.13.0",
14
+ "version": "6.13.1",
15
15
  "install_unit": "marketplace",
16
16
  "bundled_plugins": [
17
17
  "./plugins/project-orchestrator/plugin.json",
@@ -30,7 +30,7 @@
30
30
  "id": "agents-init",
31
31
  "name": "agents-init v6 / Project Profile initialization and migration",
32
32
  "description": "Create or migrate the project skeleton and root launcher; checks that project-orchestrator, agent-pack and opinion-manager from the same release are present before writing.",
33
- "version": "6.9.1",
33
+ "version": "6.9.2",
34
34
  "status": "stable",
35
35
  "entrypoints": {
36
36
  "browser": "./plugins/agents-init/skills/agents-init/index.html",
@@ -43,7 +43,7 @@
43
43
  "id": "project-orchestrator",
44
44
  "name": "project-orchestrator / project lifecycle orchestration",
45
45
  "description": "Organizes Case workspaces or keeps existing Task/Case layouts; search, lossless migration, verification, scoped Git delivery, and a project menu that works without any AI agent.",
46
- "version": "1.11.4",
46
+ "version": "1.11.5",
47
47
  "status": "stable",
48
48
  "entrypoints": {
49
49
  "agent": "./plugins/project-orchestrator/skills/project-orchestrator/SKILL.md",
@@ -55,7 +55,7 @@
55
55
  "id": "agent-pack",
56
56
  "name": "agent-pack / Agent extension capability management",
57
57
  "description": "Inventory, verify, install, sync, migrate and reconcile Plugins, Skills and MCP between projects and Codex / Cursor / Claude; the agenthelm command line and user-level runtime.",
58
- "version": "1.13.0",
58
+ "version": "1.13.1",
59
59
  "status": "stable",
60
60
  "entrypoints": {
61
61
  "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-pack",
3
- "version": "1.13.0",
3
+ "version": "1.13.1",
4
4
  "description": "Deterministic Agent-extension capability management for configured workspaces.",
5
5
  "author": {
6
6
  "name": "lc4t"
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "agent-pack",
4
- "version": "1.13.0",
4
+ "version": "1.13.1",
5
5
  "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.",
6
6
  "author": {
7
7
  "name": "lc4t"
@@ -43,6 +43,8 @@ python3 <plugin-root>/runtime/agent_pack_config.py --output json doctor --projec
43
43
 
44
44
  前四类和 `coupled` 计入 `issues`,`overrides` 计入 `warnings`。不加 `--client` 时行为与以前相同。
45
45
 
46
+ 运行方式:`python3 -I`、`-P` 与 `PYTHONSAFEPATH=1` 只对 `runtime/agent_pack_config.py` 这一个入口受支持(入口自行把脚本所在目录加入 `sys.path`,与普通运行一致);同目录其他脚本(`agent_pack_claude.py`、`mcp_server.py`、`agenthelm.py` 等)在这些模式下无法导入同目录模块,不受支持。
47
+
46
48
  runtime 尚未安装时,bootstrap 包含本 Skill 的插件:
47
49
 
48
50
  ```bash
@@ -8,7 +8,7 @@
8
8
 
9
9
  - **Claude Code**: the plugin ships `hooks/hooks.json`, effective after installation. SessionStart (`startup|resume|clear|compact`) injects the protocol; UserPromptSubmit reminds when a keyword matches; Stop uses `additionalContext` to make the Agent confirm with the user when the conditions are met.
10
10
  - **Codex**: reads the same `hooks/hooks.json` (Codex also provides `CLAUDE_PLUGIN_ROOT`). By Codex's rules a plugin hook runs only after the user reviews and trusts it in `/hooks`. Stop uses `decision: "block"` with a `reason`, and the reason text becomes the next turn's continuation prompt.
11
- - **Cursor**: has no prompt-level injection (`beforeSubmitPrompt` can only allow or block). Run `agenthelm nudge install-hooks --client cursor` to preview and add `--apply` to write sessionStart and stop into `~/.cursor/hooks.json` (`--scope project` writes the project's `.cursor/hooks.json`; `--remove` undoes it and deletes only the entries agenthelm wrote). When run through `npx`, the hook commands never point into npx's temporary cache (`…/_npx/<hash>/…`; the hooks would break once the cache is cleaned). They use an installed stable entry instead: first `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`, then `<data dir>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py` after `agenthelm runtime install` (the temporary folders of pnpm dlx, yarn dlx and bunx are recognised too). If neither exists, the preview warns and `--apply` refuses to write, exiting with code 2; run `agenthelm install --client cursor --apply` or `agenthelm runtime install --apply` first. `--remove` is not affected. Cursor's `stop` prompt appears as a "user message", so it is off by default. The community reports cases where sessionStart's `additional_context` does not reach the model (see the Cursor forum), so the protocol is also written in opinion-manager's Skill and can be triggered on demand without the hook.
11
+ - **Cursor**: has no prompt-level injection (`beforeSubmitPrompt` can only allow or block). Run `agenthelm nudge install-hooks --client cursor` to preview and add `--apply` to write sessionStart and stop into `~/.cursor/hooks.json` (`--scope project` writes the project's `.cursor/hooks.json`; `--remove` undoes it and deletes only the entries agenthelm wrote). When run through `npx`, the hook commands never point into npx's temporary cache (`…/_npx/<hash>/…`; the hooks would break once the cache is cleaned). They use an installed stable entry instead: first `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`, then `<data dir>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py` after `agenthelm runtime install` (the temporary folders of pnpm dlx, yarn dlx and bunx are recognised too). If neither exists, the preview warns and `--apply` refuses to write, exiting with code 2; run `agenthelm install --client cursor --apply` or `agenthelm runtime install --apply` first. `--remove` is not affected. The stable entry's path deliberately carries no version, so the entry picked may be an old one (an old agent-pack in the Cursor plugin directory, or `current` still linked to an old `runtimes/<version>`), and the generated hooks then call that old version's nudge: before installing the hooks, update the plugin (`agenthelm update --client cursor --apply`) or switch to the target version with `agenthelm runtime use <target version> --apply`, then run `install-hooks`. Cursor's `stop` prompt appears as a "user message", so it is off by default. The community reports cases where sessionStart's `additional_context` does not reach the model (see the Cursor forum), so the protocol is also written in opinion-manager's Skill and can be triggered on demand without the hook.
12
12
 
13
13
  All three clients share these properties: the hook always exits 0 and stays silent on any error; it produces output only in projects that use opinion-manager (the Project Profile's `opinion.provider` is `opinion-manager`, or `.opinion/` or `opinion.lock.json` exists), so other directories never notice it.
14
14
 
@@ -8,7 +8,7 @@
8
8
 
9
9
  - **Claude Code**:插件随附 `hooks/hooks.json`,安装后自动生效。SessionStart(`startup|resume|clear|compact`)注入协议;UserPromptSubmit 在命中关键词时提醒;Stop 在满足条件时用 `additionalContext` 让 Agent 向用户确认。
10
10
  - **Codex**:读取同一个 `hooks/hooks.json`(Codex 同时提供 `CLAUDE_PLUGIN_ROOT`)。按 Codex 的规则,插件 hook 需要用户在 `/hooks` 中审阅并信任后才会运行。Stop 使用 `decision: "block"` 加 `reason`,原因文本成为下一轮的续写提示。
11
- - **Cursor**:没有 prompt 级注入(`beforeSubmitPrompt` 只能放行或拦截)。运行 `agenthelm nudge install-hooks --client cursor` 预览,加 `--apply` 把 sessionStart 与 stop 写入 `~/.cursor/hooks.json`(`--scope project` 写项目的 `.cursor/hooks.json`;`--remove` 撤销,只删除 agenthelm 写入的条目)。经 `npx` 运行时,hook 命令不会指向 npx 的临时缓存(`…/_npx/<哈希>/…`,缓存被清理后 hook 会失效):改用已安装的稳定入口,先找 `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`,再找 `agenthelm runtime install` 之后的 `<数据目录>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py`(pnpm dlx、yarn dlx、bunx 的临时目录同样识别);两处都没有时预览给出警告,`--apply` 拒绝写入并以退出码 2 退出,请先运行 `agenthelm install --client cursor --apply` 或 `agenthelm runtime install --apply`。`--remove` 不受影响。Cursor 的 `stop` 提示以“用户消息”的形式出现,默认关闭。社区有 sessionStart 的 `additional_context` 未到达模型的反馈(见 Cursor 论坛),所以协议同时写在 opinion-manager 的 Skill 里,不依赖 hook 也能按需触发。
11
+ - **Cursor**:没有 prompt 级注入(`beforeSubmitPrompt` 只能放行或拦截)。运行 `agenthelm nudge install-hooks --client cursor` 预览,加 `--apply` 把 sessionStart 与 stop 写入 `~/.cursor/hooks.json`(`--scope project` 写项目的 `.cursor/hooks.json`;`--remove` 撤销,只删除 agenthelm 写入的条目)。经 `npx` 运行时,hook 命令不会指向 npx 的临时缓存(`…/_npx/<哈希>/…`,缓存被清理后 hook 会失效):改用已安装的稳定入口,先找 `~/.cursor/plugins/local/agent-pack/runtime/agenthelm.py`,再找 `agenthelm runtime install` 之后的 `<数据目录>/agenthelm/current/plugins/agent-pack/runtime/agenthelm.py`(pnpm dlx、yarn dlx、bunx 的临时目录同样识别);两处都没有时预览给出警告,`--apply` 拒绝写入并以退出码 2 退出,请先运行 `agenthelm install --client cursor --apply` 或 `agenthelm runtime install --apply`。`--remove` 不受影响。稳定入口的路径刻意不含版本号,选中的入口可能是旧版本(Cursor 插件目录里是旧的 agent-pack,或 `current` 仍指向旧的 `runtimes/<版本>`),生成的 hook 会调用该旧版本的 nudge:安装 hook 前先更新插件(`agenthelm update --client cursor --apply`),或用 `agenthelm runtime use <目标版本> --apply` 切到目标版本,再运行 `install-hooks`。Cursor 的 `stop` 提示以“用户消息”的形式出现,默认关闭。社区有 sessionStart 的 `additional_context` 未到达模型的反馈(见 Cursor 论坛),所以协议同时写在 opinion-manager 的 Skill 里,不依赖 hook 也能按需触发。
12
12
 
13
13
  三个客户端的共同点:hook 永远退出 0,任何异常都静默;只在项目启用了 opinion-manager(Project Profile 的 `opinion.provider` 为 `opinion-manager`,或存在 `.opinion/`、`opinion.lock.json`)时才有输出,其他目录完全无感。
14
14
 
@@ -223,17 +223,48 @@ def _plugin_skill_links(home: Path, plugin_path: Path) -> list[Path]:
223
223
  return found
224
224
 
225
225
 
226
+ def _installed_plugin_mcps(home: Path, plugin: str, plugin_path: Path, config: dict[str, Any]) -> set[str]:
227
+ """Servers in ``~/.claude.json`` that ``bootstrap`` wrote for this plugin, judged by content.
228
+
229
+ Bootstrap leaves no per-server ownership record, so a name counts only when the entry equals what the
230
+ plugin's ``mcp.json`` renders to today; a same-named entry the user changed may be theirs and is not claimed.
231
+ """
232
+ mcp_path = plugin_path / "mcp.json"
233
+ if not mcp_path.is_file():
234
+ return set()
235
+ try:
236
+ declared = core._read_json(mcp_path).get("mcpServers", {})
237
+ except (core.AgentPackError, AttributeError):
238
+ return set()
239
+ owned: set[str] = set()
240
+ for server, raw in declared.items():
241
+ if server not in config:
242
+ continue
243
+ parsed = core._portable_mcp(server, raw)
244
+ if parsed.portable and core._claude_mcp_config(
245
+ parsed.config, record_path(home, plugin), data_root(home, plugin)) == config[server]:
246
+ owned.add(server)
247
+ return owned
248
+
249
+
226
250
  def _plugin_residuals(home: Path, plugin: str, plugin_path: Path, config: dict[str, Any]) -> list[dict[str, str]]:
227
251
  """Entries a retirement leaves on purpose: files Claude Code owns or that may hold local credentials."""
228
252
  residuals: list[dict[str, str]] = []
229
253
  prefixes = {str(plugin_path), str(plugin_path.resolve())}
230
254
  config_path = core._claude_user_config(home)
255
+ installed = _installed_plugin_mcps(home, plugin, plugin_path, config)
231
256
  for server, entry in sorted(config.items()):
232
257
  if any(text.startswith(prefix + os.sep) or text == prefix for text in _strings(entry) for prefix in prefixes):
233
258
  residuals.append({
234
259
  "client": "claude", "kind": "mcp", "name": server, "path": str(config_path),
235
260
  "manual": f"MCP server {server} still points into the retired plugin; remove it with "
236
261
  f"`claude mcp remove --scope user {server}` (the file may hold local credentials, so it is not edited automatically)"})
262
+ elif server in installed:
263
+ residuals.append({
264
+ "client": "claude", "kind": "mcp", "name": server, "path": str(config_path),
265
+ "manual": f"MCP server {server} was installed by the retired plugin (identical to what its mcp.json "
266
+ f"renders to); remove it with `claude mcp remove --scope user {server}` (the file may hold "
267
+ f"local credentials, so it is not edited automatically)"})
237
268
  managed = home / ".claude" / "plugins"
238
269
  if _inside(plugin_path, managed):
239
270
  residuals.append({
@@ -2180,10 +2180,16 @@ def main(argv: list[str] | None = None) -> int:
2180
2180
 
2181
2181
 
2182
2182
  if __name__ == "__main__":
2183
- # Run through the importable module, not ``__main__``: ``agent_pack_claude`` and
2184
- # ``agent_pack_codex_mcp`` do ``import agent_pack_config``, which would otherwise load a
2185
- # second copy of this file whose ``AgentPackError`` is a different class, so ``main()``'s
2186
- # ``except AgentPackError`` could not catch what they raise (a stack trace, exit 1).
2187
- import agent_pack_config as _module # noqa: PLC0415
2188
-
2189
- raise SystemExit(_module.main())
2183
+ # ``agent_pack_claude`` and ``agent_pack_codex_mcp`` do ``import agent_pack_config`` (also lazily,
2184
+ # inside bootstrap/reconcile). Without help that loads a second copy of this file whose
2185
+ # ``AgentPackError`` is a different class, so ``main()``'s ``except AgentPackError`` could not catch
2186
+ # what they raise (a stack trace, exit 1). Register this running module under its import name so
2187
+ # they get the very same module object, and put the script's own directory on ``sys.path`` so those
2188
+ # sibling imports resolve even under ``python3 -I`` / ``-P`` / PYTHONSAFEPATH=1, which drop it
2189
+ # (#98). The directory added is the script's own, exactly what a plain ``python3 script.py`` run adds.
2190
+ _here = str(Path(__file__).resolve().parent)
2191
+ if _here not in sys.path:
2192
+ sys.path.insert(0, _here)
2193
+ sys.modules.setdefault("agent_pack_config", sys.modules[__name__])
2194
+
2195
+ raise SystemExit(main())
@@ -2418,8 +2418,34 @@ def doctor(env: Env, report: dict) -> dict:
2418
2418
  "last_hook_error": failure}
2419
2419
 
2420
2420
 
2421
+ def version_text(root: Path | None = None, plugin_root: Path | None = None) -> str:
2422
+ """The line ``agenthelm --version`` prints. The suite version comes from the release content's ``index.json``
2423
+ (the same fact as the npm package version), read through ``agenthelm_runtime.running_label`` so a pre-release
2424
+ keeps its ``-rc.N``. Runtimes copied into plugin caches ship without ``index.json``: then the agent-pack
2425
+ plugin's own version is shown and the suite version is said to be unknown."""
2426
+ try:
2427
+ import agenthelm_runtime # noqa: PLC0415 - shipped next to this file
2428
+ suite = agenthelm_runtime.running_label(root if root is not None else RUNTIME_DIR.parents[2])
2429
+ except Exception: # noqa: BLE001 - a version query must never crash
2430
+ suite = None
2431
+ if suite:
2432
+ return f"agenthelm {suite}"
2433
+ plugin = _manifest_version(plugin_root if plugin_root is not None else PLUGIN_ROOT)
2434
+ return _("agenthelm(套件版本未知:此运行时不含 index.json);agent-pack 插件 {0}").format(plugin or _("未知"))
2435
+
2436
+
2437
+ class _VersionAction(argparse.Action):
2438
+ def __init__(self, option_strings, dest=argparse.SUPPRESS, default=argparse.SUPPRESS, help=None): # noqa: A002
2439
+ super().__init__(option_strings, dest, nargs=0, default=default, help=help)
2440
+
2441
+ def __call__(self, parser, namespace, values, option_string=None): # noqa: ARG002
2442
+ print(version_text())
2443
+ parser.exit()
2444
+
2445
+
2421
2446
  def parser() -> argparse.ArgumentParser:
2422
2447
  result = argparse.ArgumentParser(prog="agenthelm", description=_("agenthelm:在 Claude Code、Codex、Cursor 间安装、检查与更新 agenthelm 插件。"))
2448
+ result.add_argument("--version", action=_VersionAction, help=_("输出 agenthelm 套件版本后退出"))
2423
2449
  sub = result.add_subparsers(dest="command", required=True)
2424
2450
 
2425
2451
  def refresh(command: argparse.ArgumentParser) -> None:
@@ -2610,8 +2636,17 @@ def _print_steps(results: list[dict], apply: bool) -> None:
2610
2636
  print("\n".join(render_outcome(results)))
2611
2637
  if not apply and results:
2612
2638
  stuck = [r for r in results if r["status"] == "blocked" or (isinstance(r.get("result"), dict) and r["result"].get("blocked"))]
2639
+ broken = [r for r in results if r["status"] in {"unavailable", "failed"}]
2613
2640
  runnable = [r for r in results if r["status"] == "preview" and r not in stuck]
2614
- if stuck and not runnable:
2641
+ if broken and not runnable:
2642
+ counts = [(len(stuck), _("{0} 个步骤阻塞")),
2643
+ (sum(r["status"] == "unavailable" for r in broken), _("{0} 个步骤不可用")),
2644
+ (sum(r["status"] == "failed" for r in broken), _("{0} 个步骤失败"))]
2645
+ print(_("预览中没有可以执行的步骤:{0}(见上面的各项与下一步)。先处理,再重新预览;这时运行 --apply 也不会执行任何步骤。").format(
2646
+ _("、").join(text.format(count) for count, text in counts if count)))
2647
+ elif broken:
2648
+ print(_("以上为预览;其中有步骤不可用或失败(见上),--apply 只执行其余可以执行的步骤,这些步骤需先按提示处理。"))
2649
+ elif stuck and not runnable:
2615
2650
  print(_("预览被阻塞:没有可以执行的步骤(见上面的 [阻塞] 项与下一步)。先处理,再重新预览;这时运行 --apply 也不会执行任何步骤。"))
2616
2651
  elif stuck:
2617
2652
  print(_("以上为预览;其中有步骤被阻塞(见上),--apply 只执行未被阻塞的步骤,被阻塞的步骤需先按提示处理。"))
@@ -631,5 +631,12 @@
631
631
  "被替换文件的备份目录;缺省 ~/.agent-pack/recovery/<时间>-agenthelm-<标签>(项目 Profile 的备份目录须在项目外)": "Folder for the backup of replaced files; default ~/.agent-pack/recovery/<time>-agenthelm-<label> (for a project Profile the folder must be outside the project)",
632
632
  "备份目录里已有 {0}": "The backup folder already holds {0}",
633
633
  "项目文件语言(Profile 的 language)是 {0},但内容锁记录的上次渲染语言是 {1}({2}),已有文件仍是{1}。运行 {3} fix update-content 预览整份替换(不加 --apply 不写入;你改过的文件默认保留),或在 agents-init 的 scripts 目录运行 init_project.py --mode refresh --project <项目> 预览。check 与 update --only content 不会自动改写既有文件。": "The project file language (the Profile's language) is {0}, but the content lock records {1} as the language the files were last rendered in ({2}), so the existing files are still {1}. Run {3} fix update-content to preview a full replacement (nothing is written without --apply; files you changed are kept by default), or run init_project.py --mode refresh --project <project> from the agents-init scripts directory to preview. check and update --only content never rewrite existing files on their own.",
634
- "项目里缺少 {0}(接管项目登记了受管区块)。重建带区块标记的文件:{1} update --only content {2} --apply(缺失文件没有本地内容,不需要 --confirm-discard)。": "{0} is missing (this adopted project registered managed regions). Recreate it with the region markers: {1} update --only content {2} --apply (a missing file has no local content, so --confirm-discard is not needed)."
634
+ "项目里缺少 {0}(接管项目登记了受管区块)。重建带区块标记的文件:{1} update --only content {2} --apply(缺失文件没有本地内容,不需要 --confirm-discard)。": "{0} is missing (this adopted project registered managed regions). Recreate it with the region markers: {1} update --only content {2} --apply (a missing file has no local content, so --confirm-discard is not needed).",
635
+ "以上为预览;其中有步骤不可用或失败(见上),--apply 只执行其余可以执行的步骤,这些步骤需先按提示处理。": "The above is a preview; some steps are unavailable or failed (see above). --apply runs only the remaining runnable steps; resolve the others first as advised.",
636
+ "预览中没有可以执行的步骤:{0}(见上面的各项与下一步)。先处理,再重新预览;这时运行 --apply 也不会执行任何步骤。": "The preview has no runnable steps: {0} (see the items and next steps above). Resolve them and preview again; running --apply now would execute nothing.",
637
+ "{0} 个步骤阻塞": "{0} blocked",
638
+ "{0} 个步骤不可用": "{0} unavailable",
639
+ "{0} 个步骤失败": "{0} failed",
640
+ "agenthelm(套件版本未知:此运行时不含 index.json);agent-pack 插件 {0}": "agenthelm (suite version unknown: this runtime ships without index.json); agent-pack plugin {0}",
641
+ "输出 agenthelm 套件版本后退出": "Print the agenthelm suite version and exit"
635
642
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-init",
3
- "version": "6.9.1",
3
+ "version": "6.9.2",
4
4
  "description": "Initialize or migrate an Agent project contract; ships with project-orchestrator, agent-pack and opinion-manager.",
5
5
  "author": {
6
6
  "name": "lc4t"
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "agents-init",
4
- "version": "6.9.1",
4
+ "version": "6.9.2",
5
5
  "description": "Initialize or migrate an Agent project contract (AGENTS.md, Project Profile, root launcher); ships with project-orchestrator, agent-pack and opinion-manager.",
6
6
  "author": {
7
7
  "name": "lc4t"
@@ -548,9 +548,14 @@ def run(args: Any, root: Path, inputs: Any) -> tuple[int, dict]:
548
548
  "needs_recovery_dir": needs_recovery, "pending_handoff": pending_handoff, "notes": notes,
549
549
  "readme": readme["action"] if readme else ("create" if Path("README.md") in create else "untouched"),
550
550
  }
551
+ recovery_dir = getattr(args, "recovery_dir", None)
552
+ if needs_recovery and not getattr(args, "apply", False):
553
+ # Same refusal as apply, so a folder inside the project is reported before anyone runs --apply.
554
+ target, defaulted = init.resolve_recovery_target(root, recovery_dir, "adopt")
555
+ result.update(recovery_default=defaulted, recovery_plan=str(
556
+ target.parent / "<UTC time>-agenthelm-adopt" if defaulted else target))
551
557
  if not getattr(args, "apply", False):
552
558
  return 0, result
553
- recovery_dir = getattr(args, "recovery_dir", None)
554
559
  recovery: Path | None = None
555
560
  defaulted = False
556
561
  if needs_recovery:
@@ -115,6 +115,17 @@ def default_recovery_dir(label: str) -> Path:
115
115
  return Path.home() / ".agent-pack" / "recovery" / f"{stamp}-agenthelm-{label}"
116
116
 
117
117
 
118
+ def resolve_recovery_target(root: Path, recovery_dir: Path | None, label: str) -> tuple[Path, bool]:
119
+ """Where backups would go, rejected when inside the project: ``(path, was_defaulted)``. Touches nothing on disk."""
120
+ defaulted = recovery_dir is None
121
+ target = (default_recovery_dir(label) if defaulted else recovery_dir.expanduser()).resolve()
122
+ if target == root or root in target.parents:
123
+ if defaulted:
124
+ raise InitError(_("默认恢复目录 {0} 在项目目录内,请用 --recovery-dir 指定项目外的目录").format(target))
125
+ raise InitError("--recovery-dir must be outside the project root")
126
+ return target, defaulted
127
+
128
+
118
129
  def prepare_recovery_dir(root: Path, recovery_dir: Path | None, label: str) -> tuple[Path, bool]:
119
130
  """The folder replaced files are copied to, ready for writing: ``(path, was_defaulted)``.
120
131
 
@@ -122,12 +133,7 @@ def prepare_recovery_dir(root: Path, recovery_dir: Path | None, label: str) -> t
122
133
  folder first. Either way it must be outside the project and writable. Callers resolve it *before* touching any
123
134
  project file, so a backup folder that cannot be used leaves the project unchanged instead of skipping the backup.
124
135
  """
125
- defaulted = recovery_dir is None
126
- target = (default_recovery_dir(label) if defaulted else recovery_dir.expanduser()).resolve()
127
- if target == root or root in target.parents:
128
- if defaulted:
129
- raise InitError(_("默认恢复目录 {0} 在项目目录内,请用 --recovery-dir 指定项目外的目录").format(target))
130
- raise InitError("--recovery-dir must be outside the project root")
136
+ target, defaulted = resolve_recovery_target(root, recovery_dir, label)
131
137
  try:
132
138
  target.mkdir(parents=True, exist_ok=True, mode=0o700)
133
139
  if not target.is_dir():
@@ -184,6 +190,15 @@ def split_csv(value: str) -> tuple[str, ...]:
184
190
  return items
185
191
 
186
192
 
193
+ class ExtendCsvAction(argparse.Action):
194
+ """Multi-value option: repeat the flag and/or comma-separate; keeps first-seen order and drops duplicates."""
195
+
196
+ def __call__(self, parser, namespace, values, option_string=None):
197
+ merged = list(getattr(namespace, self.dest, None) or ())
198
+ merged.extend(item for item in values if item not in merged)
199
+ setattr(namespace, self.dest, tuple(dict.fromkeys(merged)))
200
+
201
+
187
202
  def slugify(value: str) -> str:
188
203
  slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
189
204
  if not slug:
@@ -1620,7 +1635,11 @@ def _adopt_text(result: dict) -> str:
1620
1635
  for note in result.get("notes", []):
1621
1636
  lines.append(_(" 说明:{0}").format(note))
1622
1637
  if result.get("needs_recovery_dir") and not result.get("applied"):
1623
- lines.append(" " + _("改动已有文件前会先备份到 ~/.agent-pack/recovery/(也可用 --recovery-dir 指定项目外的目录)"))
1638
+ if result.get("recovery_default", True):
1639
+ lines.append(" " + _("改动已有文件前会先备份到默认目录 {0}(<UTC time> 在执行时确定;也可用 --recovery-dir 指定项目外的目录)").format(
1640
+ result.get("recovery_plan") or "~/.agent-pack/recovery/<UTC time>-agenthelm-adopt"))
1641
+ else:
1642
+ lines.append(" " + _("改动已有文件前会先备份到 {0}(--recovery-dir)").format(result["recovery_plan"]))
1624
1643
  if scan.get("recommended_flags"):
1625
1644
  lines.append(" " + _("推荐选项:") + " ".join(scan["recommended_flags"]))
1626
1645
  if result.get("check_after"):
@@ -1634,11 +1653,12 @@ def parser() -> argparse.ArgumentParser:
1634
1653
  result.add_argument("--project", type=Path, required=True)
1635
1654
  result.add_argument("--name")
1636
1655
  result.add_argument("--slug")
1637
- result.add_argument("--project-type", type=split_csv)
1656
+ multi_help = _("可多值:重复传参({0} a {0} b)或逗号分隔({0} a,b),可混用;保持先后顺序并去重")
1657
+ result.add_argument("--project-type", type=split_csv, action=ExtendCsvAction, help=multi_help.format("--project-type"))
1638
1658
  result.add_argument("--vcs")
1639
- result.add_argument("--stack", type=split_csv)
1659
+ result.add_argument("--stack", type=split_csv, action=ExtendCsvAction, help=multi_help.format("--stack"))
1640
1660
  result.add_argument("--runtime")
1641
- result.add_argument("--agent-cli", type=split_csv)
1661
+ result.add_argument("--agent-cli", type=split_csv, action=ExtendCsvAction, help=multi_help.format("--agent-cli"))
1642
1662
  result.add_argument("--mode", choices=("init", "migrate", "refresh", "entry", "check", "add-skeleton", "profile",
1643
1663
  "repair-lock", "decide", "case-naming", "scan", "adopt", "region", "language", "accept-current"),
1644
1664
  default="init",
@@ -202,7 +202,6 @@
202
202
  "恢复目录 {0} 无法创建或写入:{1}。项目文件没有改动;请检查权限,或用 --recovery-dir 指定其他项目外目录": "The recovery folder {0} cannot be created or written: {1}. No project file was changed; check the permissions, or use --recovery-dir to name another folder outside the project",
203
203
  "被替换文件的原件已备份到:{0}": "Originals of the replaced files were backed up to: {0}",
204
204
  "还原:把备份目录里的文件按相同的相对路径复制回项目目录(cp -p <备份目录>/<文件> <项目目录>/<文件>)。": "To restore: copy the files from the backup folder back to the project folder under the same relative paths (cp -p <backup>/<file> <project>/<file>).",
205
- "改动已有文件前会先备份到 ~/.agent-pack/recovery/(也可用 --recovery-dir 指定项目外的目录)": "Existing files are backed up to ~/.agent-pack/recovery/ before they change (or use --recovery-dir to name a folder outside the project)",
206
205
  "被替换文件的备份目录(必须在项目外);缺省 ~/.agent-pack/recovery/<UTC 时间>-agenthelm-<模式>/": "Backup folder for replaced files (must be outside the project); default ~/.agent-pack/recovery/<UTC time>-agenthelm-<mode>/",
207
206
  "已经导入或带有这个区块,无需追加": "Already imported or already has this region; nothing to append",
208
207
  "--diff 只用于查看,不能与 --apply 同用": "--diff is for viewing only and cannot be combined with --apply",
@@ -318,5 +317,8 @@
318
317
  "这些文件只管理已登记的区块,请用 --mode region 处理,不能替换或合并整文件:{0}": "Only recorded regions are managed in these files. Use --mode region; whole-file replacement or merge is unavailable: {0}",
319
318
  "历史来源未能提供与内容锁摘要一致的基线(本机缓存、本地 git tag 或 GitHub Release;联网可能已关闭,或下载与校验未成功),无法三方合并;没有改动任何文件,请改用 --keep / --append / --accept 选择": "Historical sources could not provide a baseline matching the content lock digest (runtime cache, local git tags or GitHub Release; networking may be disabled, or download and verification did not succeed). A three-way merge is unavailable; no files changed. Choose --keep / --append / --accept instead",
320
319
  "内容锁里有基线摘要,但对应的历史模板缺少当前渲染所需的区块,无法重新渲染,不能三方合并;没有改动任何文件,此类项目请用 --keep / --append / --accept 选择": "The content lock has a baseline digest, but the corresponding historical template lacks blocks required by the current renderer. It cannot be re-rendered for a three-way merge; no files changed. For these projects, choose --keep / --append / --accept",
321
- "历史来源可用,模板也能渲染,但渲染结果与内容锁记录的摘要不一致(渲染输入或文件基线不同),无法确认你的起点,不能三方合并;没有改动任何文件,请改用 --keep / --append / --accept 选择": "A historical source is available and its template renders, but the result does not match the digest recorded in the content lock (different render inputs or file baseline). Your starting point cannot be confirmed, so a three-way merge is unavailable; no files changed. Choose --keep / --append / --accept instead"
320
+ "历史来源可用,模板也能渲染,但渲染结果与内容锁记录的摘要不一致(渲染输入或文件基线不同),无法确认你的起点,不能三方合并;没有改动任何文件,请改用 --keep / --append / --accept 选择": "A historical source is available and its template renders, but the result does not match the digest recorded in the content lock (different render inputs or file baseline). Your starting point cannot be confirmed, so a three-way merge is unavailable; no files changed. Choose --keep / --append / --accept instead",
321
+ "可多值:重复传参({0} a {0} b)或逗号分隔({0} a,b),可混用;保持先后顺序并去重": "Multi-value: repeat the flag ({0} a {0} b) or comma-separate ({0} a,b), or mix both; first-seen order is kept and duplicates dropped",
322
+ "改动已有文件前会先备份到默认目录 {0}(<UTC time> 在执行时确定;也可用 --recovery-dir 指定项目外的目录)": "Existing files are backed up to the default folder {0} before they change (<UTC time> is set when the command runs; or use --recovery-dir to name a folder outside the project)",
323
+ "改动已有文件前会先备份到 {0}(--recovery-dir)": "Existing files are backed up to {0} (--recovery-dir) before they change"
322
324
  }
@@ -3,7 +3,7 @@
3
3
  "name": "agents-init v6 / Project Profile initialization and migration",
4
4
  "description": "Create or migrate a general project skeleton and Project Profile; the bundled opinion-manager manages user-confirmed Agent behavior rules.",
5
5
  "schema_version": "1.0",
6
- "version": "6.9.1",
6
+ "version": "6.9.2",
7
7
  "status": "stable",
8
8
  "language": "zh-CN",
9
9
  "license": "MIT",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-orchestrator",
3
- "version": "1.11.4",
3
+ "version": "1.11.5",
4
4
  "description": "Portable project lifecycle orchestration for configured workspaces.",
5
5
  "author": {
6
6
  "name": "lc4t"
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3
3
  "name": "project-orchestrator",
4
- "version": "1.11.4",
4
+ "version": "1.11.5",
5
5
  "description": "Portable lifecycle orchestration with Case workspaces, legacy Task/Case compatibility, verified migrations, discovery and scoped Git delivery.",
6
6
  "author": {
7
7
  "name": "lc4t"
@@ -1464,5 +1464,6 @@
1464
1464
  "只预览,不写入(省略时保持直接写入)": "Preview without writing (omitting this keeps the existing immediate-write behavior)",
1465
1465
  "(要求了三方合并,但历史模板无法按当前方式重新渲染,无法合并;没有改动任何文件,请改选保留 / 追加 / 采用新模板)": " (a three-way merge was requested, but the historical template cannot be re-rendered the current way; no files changed. Choose keep / append / accept the new template instead)",
1466
1466
  "(要求了三方合并,但历史模板渲染结果与内容锁摘要不一致,无法合并;没有改动任何文件,请改选保留 / 追加 / 采用新模板)": " (a three-way merge was requested, but the historical template's render does not match the content-lock digest; no files changed. Choose keep / append / accept the new template instead)",
1467
- "{0}({1} 项,展开 {2} 项)": "{0} ({1} shown, {2} expanded)"
1467
+ "{0}({1} 项,展开 {2} 项)": "{0} ({1} shown, {2} expanded)",
1468
+ "这个发现不支持跳过:{0}(它是需要处理的问题,没有可记录的决定;处理后会自动消失)": "This finding cannot be skipped: {0} (it is a problem to fix, with no decision to record; it disappears once fixed)"
1468
1469
  }
@@ -820,7 +820,10 @@ def decide_ids(provider: Any, skip: list[str], unskip: list[str], reason: str, a
820
820
  results = []
821
821
  for identifier in skip:
822
822
  if identifier not in known:
823
- raise EntryError(_("现在没有这个发现:{0}").format(identifier), "usage", [_("可跳过:") + (_("、").join(sorted(known)) or _("(无)"))])
823
+ hint = [_("可跳过:") + (_("、").join(sorted(known)) or _("(无)"))]
824
+ if any(f["id"] == identifier for f in health["findings"]):
825
+ raise EntryError(_("这个发现不支持跳过:{0}(它是需要处理的问题,没有可记录的决定;处理后会自动消失)").format(identifier), "usage", hint)
826
+ raise EntryError(_("现在没有这个发现:{0}").format(identifier), "usage", hint)
824
827
  item = known[identifier]
825
828
  try:
826
829
  results.append(module.decide(provider.root, identifier, "skip", reason=reason,
@@ -9,6 +9,7 @@
9
9
  """
10
10
  from __future__ import annotations
11
11
 
12
+ import hashlib
12
13
  import json
13
14
  import os
14
15
  import platform
@@ -77,6 +78,7 @@ class RealProvider:
77
78
  self._items: dict | None = None
78
79
  self.reprompt = False # health/check:忽略已记录的决定,重新评估
79
80
  self._skipped: list[dict] = []
81
+ self._private_skipped: list[dict] = [] # 已登记跳过的 private-* 发现(与 check_updates 的 _skipped 分开收集)
80
82
 
81
83
  # -------------------------------------------------------------- shared pieces
82
84
 
@@ -344,7 +346,7 @@ class RealProvider:
344
346
  project_write.check_tools(self, findings, ok)
345
347
  source = project_maintain.check_updates(self, findings, ok)
346
348
  self._health = {"findings": findings, "ok": ok, "read_at": now_iso(), "update_source": source,
347
- "skipped": self._skipped}
349
+ "skipped": [*self._skipped, *self._private_skipped]}
348
350
  return self._health
349
351
 
350
352
  def _check_environment(self, findings: list[dict], ok: list[str]) -> None:
@@ -487,23 +489,62 @@ class RealProvider:
487
489
  "reason": names[:160], "impact": _("只是提醒:到期不会自动执行"),
488
490
  "next": [{"label": _("让 Agent 按它执行,或运行 sop run <id>"), "action": ""}]})
489
491
 
492
+ def _private_decisions(self) -> tuple[Any, dict | None]:
493
+ """(脚手架模块, 已记录的决定);模块太旧或决定文件有问题时决定为 None(发现照常显示,也不提供跳过)。"""
494
+ module = project_maintain.scaffold_module(self)
495
+ if module is None or not hasattr(module, "partition") or not hasattr(module, "load_decisions"):
496
+ return None, None
497
+ try:
498
+ decisions = module.load_decisions(self.root, self.host.current_env().state_dir)
499
+ except Exception: # noqa: BLE001 - 决定读不出来时不能让 health 失败
500
+ return None, None
501
+ return module, (None if decisions["errors"] else decisions)
502
+
490
503
  def _check_private(self, findings: list[dict], ok: list[str]) -> None:
491
- """私有目录:内容默认不进 git;用到它的事项应标为 private。"""
504
+ """私有目录:内容默认不进 git;用到它的事项应标为 private。
505
+
506
+ private-ignore / private-tracked 带 decision(项目级),可用 fix --skip 登记;
507
+ 指纹:tracked = 被跟踪文件列表(排序后)的 sha256;ignore = 目录路径 + 其中 .gitignore 是否存在
508
+ (没被忽略的原因要么没有 .gitignore,要么它没覆盖内容;有无该文件变化时重新提示)。"""
492
509
  dirs = private_paths.declared(self.root)
510
+ self._private_skipped = []
493
511
  if not dirs:
494
512
  return
513
+ module, decisions = self._private_decisions()
514
+
515
+ def decide(finding: dict, basis: str) -> dict | None:
516
+ """给发现加 decision;已按当前指纹决定过的返回 None(记入 _private_skipped)。"""
517
+ if decisions is None:
518
+ return finding
519
+ fingerprint = hashlib.sha256(basis.encode("utf-8")).hexdigest()
520
+ raw = {"id": finding["id"], "fingerprint": fingerprint, "scope": "project"}
521
+ active, skipped = module.partition([raw], decisions, reprompt=self.reprompt)
522
+ if skipped:
523
+ self._private_skipped.append({**finding, "decision": skipped[0]["decision"]})
524
+ return None
525
+ if active[0].get("changed_since_decision"):
526
+ finding["title"] += _("(期望内容已变化)")
527
+ finding["decision"] = raw
528
+ return finding
529
+
495
530
  for item in dirs:
496
531
  state = private_paths.git_state(self.root, item)
497
532
  if state["ignored"] is False:
498
- findings.append({"id": f"private-ignore:{item}", "level": "suggest", "area": _("私有目录"),
533
+ found = decide({"id": f"private-ignore:{item}", "level": "suggest", "area": _("私有目录"),
499
534
  "title": _("{0}/ 没有被 git 忽略").format(item), "reason": _("私有目录的内容默认不应进入 git"),
500
535
  "impact": _("git add 时可能把私有内容一起提交"),
501
- "next": [{"label": _("运行 sop private --apply,在 {0}/ 里创建 .gitignore(先预览)").format(item), "action": ""}]})
536
+ "next": [{"label": _("运行 sop private --apply,在 {0}/ 里创建 .gitignore(先预览)").format(item), "action": ""}]},
537
+ f"private-ignore\n{item}\n{(self.root / item / private_paths.IGNORE_FILE).exists()}")
538
+ if found:
539
+ findings.append(found)
502
540
  elif state["tracked"]:
503
- findings.append({"id": f"private-tracked:{item}", "level": "suggest", "area": _("私有目录"),
541
+ found = decide({"id": f"private-tracked:{item}", "level": "suggest", "area": _("私有目录"),
504
542
  "title": _("{0}/ 下有 {1} 个文件已被 git 跟踪").format(item, len(state['tracked'])),
505
543
  "reason": _("例如 {0}").format(state['tracked'][0]), "impact": _("它们会随提交一起上传;.gitignore 对已跟踪的文件无效"),
506
- "next": [{"label": _("确认后运行 git rm -r --cached {0} 取消跟踪(历史里的内容仍在)").format(item), "action": ""}]})
544
+ "next": [{"label": _("确认后运行 git rm -r --cached {0} 取消跟踪(历史里的内容仍在)").format(item), "action": ""}]},
545
+ "private-tracked\n" + "\n".join(sorted(state["tracked"])))
546
+ if found:
547
+ findings.append(found)
507
548
  else:
508
549
  ok.append(_("私有目录 {0}/(").format(item) + (_("已被 git 忽略") if state["ignored"] else _("不在 git 仓库里")) + _(";读取前须经你确认)"))
509
550
  loose = []