@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.
- package/README.md +2 -1
- package/README.zh-CN.md +3 -0
- package/package.json +1 -1
- package/runtime/index.json +4 -4
- package/runtime/plugins/agent-pack/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/agent-pack/plugin.json +1 -1
- package/runtime/plugins/agent-pack/references/nudge.md +1 -1
- package/runtime/plugins/agent-pack/runtime/agent_pack_nudge.py +51 -11
- package/runtime/plugins/agent-pack/runtime/agenthelm.py +1320 -120
- package/runtime/plugins/agent-pack/runtime/agenthelm_runtime.py +120 -19
- package/runtime/plugins/agent-pack/runtime/local_only.py +3 -1
- package/runtime/plugins/agent-pack/runtime/locale/en.json +244 -20
- package/runtime/plugins/agent-pack/runtime/nudge_text.py +21 -1
- package/runtime/plugins/agent-pack/runtime/user_settings.py +275 -0
- package/runtime/plugins/agent-pack/skills/agent-pack/SKILL.md +2 -0
- package/runtime/plugins/agents-init/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/agents-init/content.json +2 -2
- package/runtime/plugins/agents-init/plugin.json +1 -1
- package/runtime/plugins/agents-init/skills/agents-init/AGENT.template.md +95 -6
- package/runtime/plugins/agents-init/skills/agents-init/SKILL.md +17 -9
- package/runtime/plugins/agents-init/skills/agents-init/project.schema.json +9 -0
- package/runtime/plugins/agents-init/skills/agents-init/scripts/adopt.py +33 -14
- package/runtime/plugins/agents-init/skills/agents-init/scripts/baseline.py +221 -0
- package/runtime/plugins/agents-init/skills/agents-init/scripts/init_project.py +620 -103
- package/runtime/plugins/agents-init/skills/agents-init/scripts/locale/en.json +131 -24
- package/runtime/plugins/agents-init/skills/agents-init/scripts/merge3.py +149 -0
- package/runtime/plugins/agents-init/skills/agents-init/scripts/scaffold.py +402 -46
- package/runtime/plugins/agents-init/skills/agents-init/skill.json +1 -1
- package/runtime/plugins/opinion-manager/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/opinion-manager/plugin.json +1 -1
- package/runtime/plugins/opinion-manager/runtime/context.py +12 -8
- package/runtime/plugins/opinion-manager/runtime/inbox.py +3 -2
- package/runtime/plugins/opinion-manager/runtime/inbox_text.py +13 -0
- package/runtime/plugins/opinion-manager/runtime/locale/en.json +10 -1
- package/runtime/plugins/opinion-manager/runtime/versioned.py +6 -2
- package/runtime/plugins/project-orchestrator/.codex-plugin/plugin.json +1 -1
- package/runtime/plugins/project-orchestrator/plugin.json +1 -1
- package/runtime/plugins/project-orchestrator/runtime/locale/en.json +87 -32
- package/runtime/plugins/project-orchestrator/runtime/memory.py +1 -2
- package/runtime/plugins/project-orchestrator/runtime/project_cli.py +122 -11
- package/runtime/plugins/project-orchestrator/runtime/project_maintain.py +139 -36
- package/runtime/plugins/project-orchestrator/runtime/project_menu.py +22 -0
- package/runtime/plugins/project-orchestrator/runtime/project_real.py +4 -1
- package/runtime/plugins/project-orchestrator/runtime/wf.py +2 -2
- package/runtime/plugins/agents-init/skills/agents-init/scripts/test_adopt.py +0 -551
- package/runtime/plugins/agents-init/skills/agents-init/scripts/test_init_project.py +0 -722
- 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
|
|
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.
|
|
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": {
|
package/runtime/index.json
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
71
|
+
"version": "0.5.1",
|
|
72
72
|
"status": "experimental",
|
|
73
73
|
"entrypoints": {
|
|
74
74
|
"agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",
|
|
@@ -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.
|
|
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=
|
|
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
|
-
|
|
425
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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))
|