@sakanano-moe/agenthelm 6.6.0 → 6.8.0

package/README.md

@@ -0,0 +1,68 @@
+# @sakanano-moe/agenthelm
+
+**English** · [简体中文](https://github.com/lc4t/agenthelm/blob/main/packages/cli/README.zh-CN.md)
+
+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).
+
+> The interface and the Skills are currently written in Chinese. An English interface is planned for a later release.
+
+## What it does
+
+- **Install, check and update the plugins** through each client's own marketplace. Every write previews first; add `--apply` to run it.
+- **User-level runtime**: install the deterministic tools once into `~/.local/share/agenthelm/`. After that, project launchers work without npx, without network access and without any AI client.
+- **Project menu without an AI agent**: `agenthelm project` (or the project's root launcher, `./menu` by default) finds files, shows progress, explains the project, checks and maintains it, and records work items. It never calls a model.
+
+## Requirements
+
+- Python 3.11 or later
+- Node.js 18 or later (only for `npx`)
+- Verified on macOS and Linux. The runtime commands do not support Windows.
+
+## Quick start
+
+```bash
+npx @sakanano-moe/agenthelm install            # preview installing the plugins into detected clients
+npx @sakanano-moe/agenthelm install --apply
+npx @sakanano-moe/agenthelm runtime install --apply   # once: the user-level runtime
+npx @sakanano-moe/agenthelm project --demo study      # try the project menu on a fictional project
+```
+
+In an initialized project:
+
+```bash
+./menu                       # interactive menu
+./menu find notes 2026-10    # find files by keyword and date
+./menu progress              # items grouped by status
+./menu health                # checks, each with its reason, impact and next step
+./menu --help
+```
+
+Add `--output json` to any subcommand for scripts and agents. Commands never wait for input when they are not in a terminal. Exit codes: 0 success, 1 nothing found or something must be handled, 2 usage error, 3 runtime missing or incompatible, 4 capability unavailable, 5 write conflict, 6 execution failed.
+
+## Offline
+
+Download `agenthelm-v<version>.tar.gz` from [GitHub Releases](https://github.com/lc4t/agenthelm/releases), extract it, then run:
+
+```bash
+python3 <extracted>/plugins/agent-pack/runtime/agenthelm.py runtime install --apply
+```
+
+Without network access you can still find files, see progress, read the guide and run local checks. Update checks use the cached version information and show when it was fetched.
+
+## Check and update
+
+```bash
+npx @sakanano-moe/agenthelm check          # read-only: plugins, project templates and Opinion
+npx @sakanano-moe/agenthelm update         # preview
+npx @sakanano-moe/agenthelm update --apply
+agenthelm runtime update --apply           # new runtime beside the old one
+agenthelm runtime use <version> --apply    # switch back
+```
+
+## Links
+
+- Repository and full documentation: https://github.com/lc4t/agenthelm
+- Site and version source: https://agenthelm.sakanano.moe/
+- Changes: [CHANGELOG.md](https://github.com/lc4t/agenthelm/blob/main/CHANGELOG.md) · Migration: [MIGRATION.md](https://github.com/lc4t/agenthelm/blob/main/MIGRATION.md)
+
+License: MIT

package/README.zh-CN.md

@@ -0,0 +1,28 @@
+# @sakanano-moe/agenthelm
+
+[English](https://github.com/lc4t/agenthelm/blob/main/packages/cli/README.md) · **简体中文**
+
+[agenthelm](https://github.com/lc4t/agenthelm) 的命令行。agenthelm 是跨 Agent 的项目管理插件集，适用于 Claude Code、Codex 与 Cursor，包含四个插件：agents-init（项目契约）、project-orchestrator（项目生命周期）、agent-pack（Plugin / Skill / MCP 管理）和 opinion-manager（Agent 行为规则）。
+
+- **安装、检查与更新插件**：经各客户端自己的市场完成。写操作默认只预览，加 `--apply` 才执行。
+- **用户级运行时**：一次 `npx @sakanano-moe/agenthelm runtime install --apply`，之后项目启动器打开菜单不联网、不经过 npx，也不需要 AI 客户端。
+- **不需要 AI Agent 的项目菜单**：`agenthelm project` 或项目根目录的 `./menu`，用来找资料、看进展、读项目指南、检查与维护、记录事项，全程不调用模型。
+
+需要 Python 3.11+（使用 npx 时另需 Node.js 18+）。只在 macOS 与 Linux 上验证过。离线时，从 GitHub Releases 下载发布包，解压后运行 `python3 <解压目录>/plugins/agent-pack/runtime/agenthelm.py runtime install --apply`。完整中文说明见仓库的 [README](https://github.com/lc4t/agenthelm#readme) 与 [INSTALL.md](https://github.com/lc4t/agenthelm/blob/main/INSTALL.md)。
+
+## 常用命令
+
+```bash
+npx @sakanano-moe/agenthelm install                   # 预览：安装插件到检测到的客户端
+npx @sakanano-moe/agenthelm install --apply
+npx @sakanano-moe/agenthelm runtime install --apply   # 只需一次：用户级运行时
+npx @sakanano-moe/agenthelm project --demo study      # 用虚构项目体验项目菜单
+./menu                                                # 在已初始化的项目里打开菜单
+./menu find 笔记 2026-10                               # 不进菜单：直接查；--output json 给脚本用
+npx @sakanano-moe/agenthelm check                     # 只读：插件、项目模板与 Opinion 是否落后
+npx @sakanano-moe/agenthelm update --apply            # 更新（先不加 --apply 预览）
+```
+
+退出码：0 成功；1 没有结果或有必须处理的项；2 用法错误；3 运行时缺失或不兼容；4 能力不可用；5 写入冲突；6 执行失败。
+
+许可证：MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sakanano-moe/agenthelm",
-  "version": "6.6.0",
-  "description": "agenthelm 命令行：安装、检查与更新 agenthelm 插件；用户级运行时；不需要 AI Agent 的项目入口（agenthelm project）。",
+  "version": "6.8.0",
+  "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.",
   "license": "MIT",
   "bin": {
     "agenthelm": "bin/agenthelm.js"

package/runtime/index.json

@@ -2,16 +2,16 @@
   "site": {
     "id": "agenthelm",
     "name": "agenthelm",
-    "description": "跨 Agent 的项目管理插件集：项目契约、生命周期、扩展能力与行为规则。",
+    "description": "Cross-agent project management plugins: project contract, lifecycle, extension capabilities and behavior rules. 跨 Agent 的项目管理插件集。",
     "version": "0.7.0",
-    "updated_at": "2026-10-25",
+    "updated_at": "2026-10-27",
     "homepage": "./index.html",
     "domain": "agenthelm.sakanano.moe",
     "legacy_domain": "skill.sakanano.moe"
   },
   "plugin": {
     "manifest": "./plugins/agents-init/plugin.json",
-    "version": "6.6.0",
+    "version": "6.8.0",
     "install_unit": "marketplace",
     "bundled_plugins": [
       "./plugins/project-orchestrator/plugin.json",
@@ -28,9 +28,9 @@
   "skills": [
     {
       "id": "agents-init",
-      "name": "agents-init v6 / Project Profile 初始化与迁移",
-      "description": "创建或迁移项目骨架；写入前验证同包 project-orchestrator、agent-pack 与 opinion-manager。",
-      "version": "6.6.0",
+      "name": "agents-init v6 / Project Profile initialization and migration",
+      "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.",
+      "version": "6.7.0",
       "status": "stable",
       "entrypoints": {
         "browser": "./plugins/agents-init/skills/agents-init/index.html",
@@ -41,9 +41,9 @@
     },
     {
       "id": "project-orchestrator",
-      "name": "project-orchestrator / 项目生命周期编排",
-      "description": "按项目模式组织 Case 工作目录或兼容既有 Task/Case；提供检索、无损迁移、验证与受控 Git 交付；附不需要 AI Agent 的项目入口（找资料、看进展、指南、检查、维护与记录）。",
-      "version": "1.8.0",
+      "name": "project-orchestrator / project lifecycle orchestration",
+      "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.",
+      "version": "1.9.0",
       "status": "stable",
       "entrypoints": {
         "agent": "./plugins/project-orchestrator/skills/project-orchestrator/SKILL.md",
@@ -53,9 +53,9 @@
     },
     {
       "id": "agent-pack",
-      "name": "agent-pack / Agent 扩展能力管理",
-      "description": "在项目与 Codex / Cursor / Claude 之间盘点、校验、安装、同步、迁移与对账 Plugin、Skill、MCP；agenthelm 命令行与用户级运行时。",
-      "version": "1.7.0",
+      "name": "agent-pack / Agent extension capability management",
+      "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.",
+      "version": "1.9.0",
       "status": "stable",
       "entrypoints": {
         "agent": "./plugins/agent-pack/skills/agent-pack/SKILL.md",
@@ -66,9 +66,9 @@
     },
     {
       "id": "opinion-manager",
-      "name": "opinion-manager / Agent 行为规则管理",
-      "description": "三个首次主入口与可选记忆候选；一次内容确认后分别保存 Profile、正文与锁，支持精确版本和个人修改保护；可选的分层加载与项目私有的候选、灰度记账。",
-      "version": "0.4.1",
+      "name": "opinion-manager / Agent behavior rule management",
+      "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.",
+      "version": "0.4.2",
       "status": "experimental",
       "entrypoints": {
         "agent": "./plugins/opinion-manager/skills/opinion-manager/SKILL.md",

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

@@ -1,6 +1,6 @@
 {
   "name": "agent-pack",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Deterministic Agent-extension capability management for configured workspaces.",
   "author": {
     "name": "lc4t"
@@ -9,11 +9,18 @@
   "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 承担，不在本包内。",
+    "shortDescription": "Inventory, verify, install, sync and migrate Agent Plugins, Skills and MCP servers",
+    "longDescription": "Deterministic Agent-extension capability manager: inventory / doctor / bootstrap / sync / transfer / reconcile across projects, plugin directories and Codex / Cursor clients. Writes default to dry-run; name clashes and MCP entries that contain secrets fail closed. The project lifecycle (Task/Case/routing/verification/Git) belongs to project-orchestrator, not this plugin. Also ships the agenthelm command line and the user-level runtime. 中文：确定性的 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"],
+    "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/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "agent-pack",
-  "version": "1.7.0",
+  "version": "1.9.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"

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

@@ -30,8 +30,19 @@ python3 <plugin-root>/runtime/agent_pack_config.py --output json inventory --sou
 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
+python3 <plugin-root>/runtime/agent_pack_config.py --output json doctor --project /path/to/project \
+  --client claude --client codex
 ```
 
+`doctor --client <客户端>`（可重复）在项目检查之外，再把该客户端装的东西和项目权威比一遍，结果放在 `clients.<客户端>`：
+
+- `missing`：项目有、客户端没有；`different`：内容不同；`stale`：本包装过、项目里已经没有；`dangling`：链接或 MCP 参数指向不存在的文件；
+- `coupled`：Claude 的安装记录指向别的客户端的包目录（例如 Codex 包）；
+- `overrides`：只是本机多了或改了认证类值（`headers` / `env`），只报键名，不算问题；
+- `native`：用户自己配置、不属于本包的条目，只列出；`excluded`：被 `mcp_client_policy` 排除的条目。
+
+前四类和 `coupled` 计入 `issues`，`overrides` 计入 `warnings`。不加 `--client` 时行为与以前相同。
+
 runtime 尚未安装时，bootstrap 包含本 Skill 的插件：
 
 ```bash
@@ -47,7 +58,19 @@ python3 /path/to/agent-pack/runtime/agent_pack_config.py --output json bootstrap
 - `~/.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。
+`bootstrap` 在 Claude 端是**活链接**，不固定副本：源目录改动立即生效，版本即源 `plugin.json#version`。
+
+- `--skill <名称>` / `--mcp <名称>`（可重复）只处理选中的组件。安装记录仍会建立，因为 MCP 参数要经过它。
+- 本机条目与插件版本只差认证类值（`headers` / `env` 里插件没有的键、占位符或凭据类键）时，判为 `keep-override` 并保留本机值；还有其他不同时需要 `--replace`，替换后同样保留本机认证。加 `--reset-overrides` 才丢弃本机值。结果只列出保留的键名（`kept_overrides`），不输出值。
+- 旧内容进入 `~/.agent-pack/recovery/<stamp>-claude-<name>/`（`replaced-skills/`、`replaced-plugins/`、`replaced-mcp.json`，后者权限 `0600`）。装完需重启 Claude Code 才会加载新 Skill / MCP。
+
+**项目同步到 Claude 用 `sync` / `reconcile --client claude`**，不要用 `bootstrap` 指向别的客户端的包：
+
+- 按项目和 Claude 的 `mcp_client_policy` 单独生成一份包，放在 `~/.claude/agent-pack/packages/<name>/`；安装记录 `~/.claude/agent-pack/plugins/<name>` 改为指向它；Skill 链接与 MCP 条目都指向这份包。
+- `~/.claude/agent-pack/state/<name>.json` 记下本包装进 Claude 的 Skill 与 MCP。项目里新增的会加上，改了的会更新，删掉或被策略排除的会移除；**只动清单里的条目**，用户自己配置的条目从不改动。
+- 与用户自己的同名条目冲突时停止，加 `--replace` 才替换（旧内容进恢复目录）。本机认证默认保留，`--reset-overrides` 丢弃。
+- 安装记录原来指向别的目录（旧做法：`bootstrap --plugin ~/.agents/plugins/plugins/<name> --client claude`）时，第一次同步自动迁移：旧记录指向写入恢复目录的 `record.json`，指向旧目录的 Skill 链接改为指向新包。此后 Codex 端的包怎么变、是否删除，都不影响 Claude。
+- 默认只预览；`--apply` 时整笔操作写入同一个恢复目录，任一步失败全部回滚。
 
 在来源与已初始化项目之间迁移选中的组件：
 
@@ -65,7 +88,7 @@ python3 <plugin-root>/runtime/agent_pack_config.py --output json transfer \
 为客户端构建并安装项目的可移植能力：
 
 ```bash
-# 预演
+# 预演（--client 可取 codex、cursor、claude）
 python3 <plugin-root>/runtime/agent_pack_config.py --output json sync \
   --project /path/to/project --client cursor
 
@@ -79,11 +102,11 @@ python3 <plugin-root>/runtime/agent_pack_config.py --output json sync \
 ```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
+  --retire-skill old-helper --retire-skill legacy-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-skill old-helper --retire-skill legacy-sync --apply
 ```
 
 只退役旧组件、不安装或替换项目包时加 `--retire-only`（至少需要一个 `--retire-skill` / `--retire-plugin`）：
@@ -119,6 +142,7 @@ Codex 同步会写入 `~/.agents/plugins/plugins/<name>` 可移植包、`.codex-
 - 在 `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` 字段。
+- 使用 `mcp_client_policy.<server>.include` 或 `.exclude` 完成客户端路由（`codex`、`cursor`、`claude` 各自生效）。禁止在 MCP 定义中放入 adapter 专属 `_skip` 字段。
+- 客户端里本机才有的认证值（例如远程 MCP 的 `headers.Authorization`）不进入项目；同步与 bootstrap 默认保留它们，`--reset-overrides` 才丢弃。
 - `${PLUGIN_ROOT}` 用于不可变包文件，`${PLUGIN_DATA}` 用于客户端管理的可写状态。
 - 客户端原生 adapter 只在安装阶段使用；Agent Plugins 1.0 文件保持权威源地位。