@sakanano-moe/agenthelm 6.11.0-rc.1 → 6.11.0-rc.3

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.
Files changed (47) hide show
  1. package/README.md +2 -1
  2. package/README.zh-CN.md +3 -0
  3. package/package.json +1 -1
  4. package/runtime/index.json +4 -4
  5. package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
  6. package/runtime/plugins/agent-pack/plugin.json +1 -1
  7. package/runtime/plugins/agent-pack/references/nudge.md +1 -1
  8. package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +51 -11
  9. package/runtime/plugins/agent-pack/runtime/agenthelm.py +1320 -120
  10. package/runtime/plugins/agent-pack/runtime/agenthelm_runtime.py +120 -19
  11. package/runtime/plugins/agent-pack/runtime/local_only.py +3 -1
  12. package/runtime/plugins/agent-pack/runtime/locale/en.json +244 -20
  13. package/runtime/plugins/agent-pack/runtime/nudge_text.py +21 -1
  14. package/runtime/plugins/agent-pack/runtime/user_settings.py +275 -0
  15. package/runtime/plugins/agent-pack/skills/agent-pack/SKILL.md +2 -0
  16. package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
  17. package/runtime/plugins/agents-init/content.json +2 -2
  18. package/runtime/plugins/agents-init/plugin.json +1 -1
  19. package/runtime/plugins/agents-init/skills/agents-init/AGENT.template.md +95 -6
  20. package/runtime/plugins/agents-init/skills/agents-init/SKILL.md +17 -9
  21. package/runtime/plugins/agents-init/skills/agents-init/project.schema.json +9 -0
  22. package/runtime/plugins/agents-init/skills/agents-init/scripts/adopt.py +33 -14
  23. package/runtime/plugins/agents-init/skills/agents-init/scripts/baseline.py +221 -0
  24. package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +620 -103
  25. package/runtime/plugins/agents-init/skills/agents-init/scripts/locale/en.json +131 -24
  26. package/runtime/plugins/agents-init/skills/agents-init/scripts/merge3.py +149 -0
  27. package/runtime/plugins/agents-init/skills/agents-init/scripts/scaffold.py +402 -46
  28. package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
  29. package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
  30. package/runtime/plugins/opinion-manager/plugin.json +1 -1
  31. package/runtime/plugins/opinion-manager/runtime/context.py +12 -8
  32. package/runtime/plugins/opinion-manager/runtime/inbox.py +3 -2
  33. package/runtime/plugins/opinion-manager/runtime/inbox_text.py +13 -0
  34. package/runtime/plugins/opinion-manager/runtime/locale/en.json +10 -1
  35. package/runtime/plugins/opinion-manager/runtime/versioned.py +6 -2
  36. package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
  37. package/runtime/plugins/project-orchestrator/plugin.json +1 -1
  38. package/runtime/plugins/project-orchestrator/runtime/locale/en.json +87 -32
  39. package/runtime/plugins/project-orchestrator/runtime/memory.py +1 -2
  40. package/runtime/plugins/project-orchestrator/runtime/project_cli.py +122 -11
  41. package/runtime/plugins/project-orchestrator/runtime/project_maintain.py +139 -36
  42. package/runtime/plugins/project-orchestrator/runtime/project_menu.py +22 -0
  43. package/runtime/plugins/project-orchestrator/runtime/project_real.py +4 -1
  44. package/runtime/plugins/project-orchestrator/runtime/wf.py +2 -2
  45. package/runtime/plugins/agents-init/skills/agents-init/scripts/test_adopt.py +0 -551
  46. package/runtime/plugins/agents-init/skills/agents-init/scripts/test_init_project.py +0 -722
  47. package/runtime/plugins/agents-init/skills/agents-init/scripts/test_scaffold.py +0 -555
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  The command line for [agenthelm](https://github.com/lc4t/agenthelm), a set of cross-agent project management plugins for Claude Code, Codex and Cursor: **agents-init** (project contract), **project-orchestrator** (project lifecycle), **agent-pack** (Plugin / Skill / MCP management) and **opinion-manager** (Agent behavior rules).
6
6
 
7
- > The interface and the Skills are currently written in Chinese. An English interface is planned for a later release.
7
+ > The command-line interface is in English by default and can be switched to Chinese (`AGENTHELM_LANG=zh`, or `agenthelm config language zh --apply`). The Skills and the files written into your project are mostly Chinese. See the [root README](https://github.com/lc4t/agenthelm#readme) for the two language settings.
8
8
 
9
9
  ## What it does
10
10
 
@@ -57,6 +57,7 @@ npx @sakanano-moe/agenthelm update # preview
57
57
  npx @sakanano-moe/agenthelm update --apply
58
58
  agenthelm runtime update --apply # new runtime beside the old one
59
59
  agenthelm runtime use <version> --apply # switch back
60
+ agenthelm runtime install --apply --use # a candidate (-rc.N) is installed beside the current one and does NOT become current unless you pass --use
60
61
  ```
61
62
 
62
63
  ## Links
package/README.zh-CN.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  [agenthelm](https://github.com/lc4t/agenthelm) 的命令行。agenthelm 是跨 Agent 的项目管理插件集,适用于 Claude Code、Codex 与 Cursor,包含四个插件:agents-init(项目契约)、project-orchestrator(项目生命周期)、agent-pack(Plugin / Skill / MCP 管理)和 opinion-manager(Agent 行为规则)。
6
6
 
7
+ > 命令行界面默认英文,可切到中文(`AGENTHELM_LANG=zh`,或 `agenthelm config language zh --apply`);两种语言设置的区别见根 [README](https://github.com/lc4t/agenthelm#readme)。
8
+
7
9
  - **安装、检查与更新插件**:经各客户端自己的市场完成。写操作默认只预览,加 `--apply` 才执行。
8
10
  - **用户级运行时**:一次 `npx @sakanano-moe/agenthelm runtime install --apply`,之后项目启动器打开菜单不联网、不经过 npx,也不需要 AI 客户端。
9
11
  - **不需要 AI Agent 的项目菜单**:`agenthelm project` 或项目根目录的 `./menu`,用来找资料、看进展、读项目指南、检查与维护、记录事项,全程不调用模型。
@@ -21,6 +23,7 @@ npx @sakanano-moe/agenthelm project --demo study # 用虚构项目体验项
21
23
  ./menu find 笔记 2026-10 # 不进菜单:直接查;--output json 给脚本用
22
24
  npx @sakanano-moe/agenthelm check # 只读:插件、项目模板与 Opinion 是否落后
23
25
  npx @sakanano-moe/agenthelm update --apply # 更新(先不加 --apply 预览)
26
+ agenthelm runtime install --apply --use # 候选版(-rc.N)默认只装在旁边、不成为 current;加 --use 才切换
24
27
  ```
25
28
 
26
29
  退出码:0 成功;1 没有结果或有必须处理的项;2 用法错误;3 运行时缺失或不兼容;4 能力不可用;5 写入冲突;6 执行失败。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sakanano-moe/agenthelm",
3
- "version": "6.11.0-rc.1",
3
+ "version": "6.11.0-rc.3",
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": {
@@ -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.8.0",
33
+ "version": "6.8.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.1",
46
+ "version": "1.11.3",
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.11.0",
58
+ "version": "1.11.2",
59
59
  "status": "stable",
60
60
  "entrypoints": {
61
61
  "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
@@ -68,7 +68,7 @@
68
68
  "id": "opinion-manager",
69
69
  "name": "opinion-manager / Agent behavior rule management",
70
70
  "description": "Three first-run entry points plus optional memory candidates; one content confirmation, then Profile, body and lock are saved separately, with exact versions and protection of personal edits.",
71
- "version": "0.5.0",
71
+ "version": "0.5.1",
72
72
  "status": "experimental",
73
73
  "entrypoints": {
74
74
  "agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agent-pack",
3
- "version": "1.11.0",
3
+ "version": "1.11.2",
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.11.0",
4
+ "version": "1.11.2",
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"
@@ -33,7 +33,7 @@
33
33
  - `stop_prompt`:`off` / `on-completion` / `always`,或按客户端设置,默认 `{"claude": "on-completion", "codex": "on-completion", "cursor": "off"}`。
34
34
  - `keywords`、`completion_keywords`:字符串数组,替换内置列表。
35
35
 
36
- 环境变量 `AGENTHELM_NO_NUDGE=1` 临时关闭全部输出;`AGENTHELM_NUDGE_DEBUG=1` 把 hook 内部异常打印到 stderr。`agenthelm nudge status [--project P]` 显示生效配置、当前汇总以及开新会话是否会提示。
36
+ 环境变量 `AGENTHELM_NO_NUDGE=1` 临时关闭全部输出;`AGENTHELM_NUDGE_DEBUG=1` 把 hook 内部异常打印到 stderr。`agenthelm nudge status [--project P]` 显示生效配置、当前汇总以及开新会话是否会提示。hook 内部的异常(含 opinion-manager 调用失败)仍然静默、退出码为 0,但会把最近 5 次的摘要(时间、钩子名、异常类型、一行截断消息,不含用户原话)记到用户状态目录的 `agenthelm/hook-errors.json`;`nudge status`(JSON 字段 `last_hook_error`)与 `agenthelm doctor` 会显示最近一次,`nudge status --clear-errors` 清除。
37
37
 
38
38
  ## 提示语言
39
39
 
@@ -17,20 +17,21 @@ import argparse
17
17
  import json
18
18
  import os
19
19
  import re
20
+ import shlex
20
21
  import subprocess
21
22
  import sys
22
23
  import time
23
24
  from pathlib import Path
24
25
  from typing import Any
25
26
 
26
- from nudge_text import LANGUAGES, resolve_language, text as say
27
+ from nudge_text import LANGUAGES, resolve_language, session_flag, text as say
27
28
 
28
29
  ENV_DISABLE = "AGENTHELM_NO_NUDGE"
29
30
  ENV_DEBUG = "AGENTHELM_NUDGE_DEBUG"
30
31
  CLIENTS = ("claude", "codex", "cursor")
31
32
  EVENTS = ("session-start", "prompt-submit", "stop")
32
33
  STOP_MODES = ("off", "on-completion", "always")
33
- OURS = re.compile(r"agenthelm\.py\"?\s+nudge\s+hook")
34
+ OURS = re.compile(r"agenthelm\.py['\"]?\s+nudge\s+hook")
34
35
  SUBPROCESS_TIMEOUT = 5
35
36
  MAX_PROMPT_CHARS = 1500
36
37
  SESSION_RETENTION_SECONDS = 14 * 24 * 3600
@@ -182,20 +183,31 @@ def find_manager(host: Any, env: Any) -> Path | None:
182
183
  return found / "runtime" / "opinion_manager.py" if found is not None else None
183
184
 
184
185
 
186
+ MANAGER_FAILURES: list[str] = [] # opinion-manager calls that failed during this hook run (summaries, no user text)
187
+
188
+
189
+ def _manager_failed(arguments: tuple[str, ...], reason: str) -> None:
190
+ words = [word for word in arguments[:2] if re.fullmatch(r"[a-z][a-z-]*", word)]
191
+ MANAGER_FAILURES.append(f"opinion-manager {' '.join(words)}: {reason}")
192
+
193
+
185
194
  def run_manager(manager: Path, *arguments: str, lang: str | None = None) -> Any:
186
195
  command = [*arguments, "--lang", lang] if lang else list(arguments)
187
196
  try:
188
197
  completed = subprocess.run([sys.executable, str(manager), *command], capture_output=True, text=True,
189
198
  check=False, timeout=SUBPROCESS_TIMEOUT)
190
- except (OSError, subprocess.SubprocessError):
199
+ except (OSError, subprocess.SubprocessError) as exc:
200
+ _manager_failed(arguments, type(exc).__name__)
191
201
  return None
192
202
  if completed.returncode != 0:
203
+ _manager_failed(arguments, f"exit {completed.returncode}")
193
204
  return None
194
205
  if "markdown" in arguments:
195
206
  return completed.stdout
196
207
  try:
197
208
  result = json.loads(completed.stdout)
198
209
  except ValueError:
210
+ _manager_failed(arguments, "invalid JSON output")
199
211
  return None
200
212
  return result if isinstance(result, dict) and result.get("ok") else None
201
213
 
@@ -354,7 +366,7 @@ def prompt_submit(host: Any, env: Any, payload: dict, client: str, root: Path, c
354
366
  manager = find_manager(host, env)
355
367
  lang = config["lang"]
356
368
  command = say("add_command", lang, manager=manager, root=root, lang=lang,
357
- session=f" --session {session}" if session else "") if manager else say("add_command_fallback", lang)
369
+ session=session_flag(session)) if manager else say("add_command_fallback", lang)
358
370
  context = say("prompt_hint", lang, hits=say("sep", lang).join(hits[:3]), command=command)
359
371
  return render(client, "prompt-submit", context=context)
360
372
 
@@ -408,7 +420,9 @@ def read_payload() -> dict:
408
420
 
409
421
 
410
422
  def run_hook(args: argparse.Namespace, host: Any, payload: dict | None = None) -> dict | None:
411
- """hook 入口:任何异常都吞掉,保证不影响客户端会话。"""
423
+ """hook 入口:任何异常都吞掉,保证不影响客户端会话;最近一次错误的摘要(不含用户原话)记到用户状态目录,供 nudge status / doctor 查看。"""
424
+ del MANAGER_FAILURES[:]
425
+ env = None
412
426
  try:
413
427
  env = host.current_env(args.home)
414
428
  if env.get(ENV_DISABLE) not in (None, "0", "false"):
@@ -421,22 +435,37 @@ def run_hook(args: argparse.Namespace, host: Any, payload: dict | None = None) -
421
435
  config, _ = load_config(host, env, root)
422
436
  if not config["enabled"]:
423
437
  return None
424
- return HANDLERS[args.event](host, env, payload, client, root, config)
425
- except Exception: # noqa: BLE001 - a nudge must never break a session
438
+ output = HANDLERS[args.event](host, env, payload, client, root, config)
439
+ if MANAGER_FAILURES:
440
+ _record(host, env, args.event, MANAGER_FAILURES[0])
441
+ return output
442
+ except Exception as exc: # noqa: BLE001 - a nudge must never break a session
443
+ _record(host, env, args.event, exc, home=args.home)
426
444
  if os.environ.get(ENV_DEBUG):
427
445
  import traceback
428
446
  traceback.print_exc(file=sys.stderr)
429
447
  return None
430
448
 
431
449
 
450
+ def _record(host: Any, env: Any, event: str, error: Any, home: Path | None = None) -> None:
451
+ try:
452
+ if env is None:
453
+ env = host.current_env(home)
454
+ host.record_hook_error(env, f"nudge {event}", error)
455
+ except Exception: # noqa: BLE001 - recording is best effort and silent
456
+ pass
457
+
458
+
432
459
  # ---------------------------------------------------------------- status and hook installation
433
460
 
434
461
  def status(args: argparse.Namespace, host: Any) -> dict:
435
462
  env = host.current_env(args.home)
436
463
  root = find_project(host, args.project or Path.cwd())
437
464
  config, warnings = load_config(host, env, root)
465
+ cleared = host.clear_hook_errors(env) if getattr(args, "clear_errors", False) else False
438
466
  result: dict[str, Any] = {"ok": True, "project": str(root) if root else None, "config": config, "warnings": warnings,
439
- "disabled_by_environment": env.get(ENV_DISABLE) not in (None, "0", "false")}
467
+ "disabled_by_environment": env.get(ENV_DISABLE) not in (None, "0", "false"),
468
+ "last_hook_error": host.last_hook_error(env), "hook_errors_cleared": cleared}
440
469
  if root is None:
441
470
  result["note"] = say("note_no_project", config["lang"])
442
471
  return result
@@ -451,7 +480,9 @@ def status(args: argparse.Namespace, host: Any) -> dict:
451
480
 
452
481
 
453
482
  def cursor_commands(runtime: Path) -> dict[str, dict]:
454
- base = f'python3 "{runtime}" nudge hook --client cursor --event'
483
+ # POSIX 用 shlex.quote(路径含 $、反引号、双引号时双引号不够);Windows 的 cmd 不认单引号,保留双引号
484
+ quoted = shlex.quote(str(runtime)) if os.name == "posix" else f'"{runtime}"'
485
+ base = f"python3 {quoted} nudge hook --client cursor --event"
455
486
  return {"sessionStart": {"command": f"{base} session-start", "timeout": 10},
456
487
  "stop": {"command": f"{base} stop", "timeout": 10}}
457
488
 
@@ -495,8 +526,11 @@ def install_hooks(args: argparse.Namespace, host: Any) -> dict:
495
526
  if args.apply and changed:
496
527
  if target.is_file():
497
528
  backup = target.with_name(target.name + ".agenthelm-bak")
498
- if not backup.exists():
499
- backup.write_text(target.read_text(encoding="utf-8"), encoding="utf-8")
529
+ if not backup.exists(): # the first original only: it is never refreshed
530
+ try:
531
+ backup.write_text(target.read_text(encoding="utf-8"), encoding="utf-8")
532
+ except (OSError, ValueError) as exc:
533
+ raise host.CheckError(say("err_backup", lang, target=target, backup=backup, error=exc)) from exc
500
534
  result["backup"] = str(backup)
501
535
  host.write_json_atomic(target, merged)
502
536
  result["applied"] = True
@@ -514,6 +548,7 @@ def parser() -> argparse.ArgumentParser:
514
548
  hook.add_argument("--home", type=Path, help=argparse.SUPPRESS)
515
549
  state = sub.add_parser("status", help="show the effective config, the current pending summary and whether a new session would remind")
516
550
  state.add_argument("--project", type=Path)
551
+ state.add_argument("--clear-errors", action="store_true", help="clear the recorded last hook error")
517
552
  state.add_argument("--output", choices=("text", "json"), default="text")
518
553
  state.add_argument("--home", type=Path, help=argparse.SUPPRESS)
519
554
  install = sub.add_parser("install-hooks", help="write the nudge hooks into Cursor's hooks.json (preview by default)")
@@ -561,6 +596,11 @@ def main(argv: list[str], host: Any) -> int:
561
596
  if result.get("exposure"):
562
597
  lines.append(say("status_exposure", lang, message=result["exposure"]["message"]))
563
598
  lines += [say("status_warning", lang, item=item) for item in result["warnings"]]
599
+ if result["hook_errors_cleared"]:
600
+ lines.append(say("status_errors_cleared", lang))
601
+ failure = result["last_hook_error"]
602
+ if failure:
603
+ lines.append(say("status_hook_error", lang, line=host.hook_error_line(failure), count=failure["count"]))
564
604
  if result.get("note"):
565
605
  lines.append(result["note"])
566
606
  print("\n".join(lines))