@hi-man/himan 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-05-08
+
+### Added
+
+- Added `himan install <type> <name[@version]> --global` to install a resource into the matching user-level agent directory, reusing the current project's resource agent when available and without writing the project lock file.
+
 ## [0.3.1] - 2026-05-07
 
 ### Added

package/README.md

@@ -56,11 +56,16 @@ himan publish rule my-rule --patch
   - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
   - `codex` -> `.agents/{rules|commands|skills}/<name>`
   - `openclaw` -> `.openclaw/{rules|commands|skills}/<name>`
+- 加 `--global` 时会安装到用户级 agent 目录，并仍按当前项目生效的 agent 选择目标：
+  - `cursor` -> `~/.cursor/{rules|commands|skills}/<name>`
+  - `claude-code` -> `~/.claude/{rules|commands|skills}/<name>`
+  - `codex` -> `~/.agents/{rules|commands|skills}/<name>`
+  - `openclaw` -> `~/.openclaw/{rules|commands|skills}/<name>`
 - 开发态目录：
   - `rule` -> `.himan/dev/rule/<name>`
   - `command` -> `.himan/dev/command/<name>`
   - `skill` -> `.himan/dev/skill/<name>`
-- lock 文件：`install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。
+- lock 文件：项目安装 `install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。`--global` 安装不写当前项目的 `himan.lock`。
 - 安装模式：默认 `--mode link` 使用软链；也可用 `--mode copy` 将资源复制到目标 agent 目录，lock 会记录并复现该模式。
 - 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
 
@@ -136,7 +141,7 @@ your-himan-source/
 
 | 命令                              | 说明                                                      |
 | --------------------------------- | --------------------------------------------------------- |
-| `install [type] [name[@version]] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；可覆盖安装目标 agent 或安装模式 |
+| `install [type] [name[@version]] [--global] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；加 `--global` 时安装到用户级 agent 目录且不写项目 lock；可覆盖安装目标 agent 或安装模式 |
 | `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
 | `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
 | `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
@@ -159,7 +164,7 @@ your-himan-source/
 - `himan agent list|use|current|clear ...`
 
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
-若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。
+若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
 
 `publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录。
 

package/dist/cli/builders.js

@@ -63,7 +63,7 @@ Command groups:
            init, source init, source add, source use, source list, source init-docs
   resource Source resource discovery and metadata
            list, history, create, resource list, resource history, resource create
-  project  Resource usage lifecycle in current project
+  project  Resource usage lifecycle in current project or user-level agent dirs
            install, dev, uninstall, publish,
            project install, project dev, project uninstall, project publish
   agent    Default agent configuration

package/dist/cli/project-commands.js

@@ -8,12 +8,17 @@ export function registerProjectCommands(command, services) {
         .argument("[name[@version]]", "resource name with optional @version")
         .option("--agent <list>", "install target agents, comma separated")
         .option("--mode <mode>", "install mode: link or copy")
+        .option("--global", "install into user-level agent directories")
         .description("Install resource, or install from himan.lock")
         .action(async (type, nameVersion, options) => {
         await runAction(async () => {
             const agents = parseAgents(options.agent);
             const mode = parseInstallMode(options.mode);
             if (!type && !nameVersion) {
+                if (options.global) {
+                    throw new HimanError(errorCodes.CLI_USAGE, "Global install requires a resource:\n"
+                        + "  - himan install <type> <name[@version]> --global [--mode link|copy]");
+                }
                 const results = await services.installFromLock(process.cwd(), agents, mode);
                 if (results.length === 0) {
                     process.stdout.write("No resources in lock file.\n");
@@ -27,12 +32,15 @@ export function registerProjectCommands(command, services) {
             if (!type || !nameVersion) {
                 throw new HimanError(errorCodes.CLI_USAGE, "Install usage:\n"
                     + "  - himan install  # install from himan.lock\n"
-                    + "  - himan install <type> <name[@version]> [--mode link|copy]  # install single resource");
+                    + "  - himan install <type> <name[@version]> [--mode link|copy]  # install single resource\n"
+                    + "  - himan install <type> <name[@version]> --global [--mode link|copy]  # install single resource globally");
             }
             const resourceType = ensureResourceType(type);
             const { name, version } = parseNameVersion(nameVersion);
-            const result = await services.install(resourceType, name, version, process.cwd(), agents, mode);
-            process.stdout.write(`Installed ${result.type}/${result.name}@${result.version}\n`);
+            const result = options.global
+                ? await services.installGlobal(resourceType, name, version, process.cwd(), agents, mode)
+                : await services.install(resourceType, name, version, process.cwd(), agents, mode);
+            process.stdout.write(`Installed ${options.global ? "global " : ""}${result.type}/${result.name}@${result.version}\n`);
         });
     });
     command

package/dist/services/index.js

@@ -6,7 +6,7 @@ import { ProjectLockStore, } from "../state/project-lock-store.js";
 import { PathResolver } from "../utils/path-resolver.js";
 import { toRepoId } from "../utils/repo-id.js";
 import { HimanError, errorCodes } from "../utils/errors.js";
-import { getProjectResourcePaths, getSupportedAgentNames, normalizeAgents, } from "../utils/agent-configs.js";
+import { getGlobalResourcePaths, getProjectResourcePaths, getSupportedAgentNames, normalizeAgents, } from "../utils/agent-configs.js";
 import path from "node:path";
 import { promises as fs } from "node:fs";
 import { VersionResolver } from "../adapters/version/version-resolver.js";
@@ -165,6 +165,10 @@ export class ServiceFactory {
         const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
         return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
     }
+    async installGlobal(type, name, version, projectDir, agents, mode = "link") {
+        const source = await this.loadSourceFromConfig();
+        return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
+    }
     async dev(type, name, projectDir) {
         const installInfo = await this.resolveInstalledResource(projectDir, type, name);
         const installedPath = installInfo.installedPath;
@@ -263,12 +267,12 @@ export class ServiceFactory {
         const lockSourceInfo = this.normalizeLockSourceInfo(lock.source);
         const lockedSource = await this.loadSourceFromLock(lockSourceInfo);
         for (const item of lock.resources) {
-            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode));
+            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode), "project");
             results.push(result);
         }
         return results;
     }
-    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode) {
+    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, scope = "project") {
         const history = await source.history(type, name);
         if (history.length === 0) {
             throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
@@ -279,18 +283,27 @@ export class ServiceFactory {
             await source.pull(type, name, resolvedVersion, storePath);
         }
         const resourceMeta = await this.readResourceMetaFromDir(storePath, type);
-        const effectiveTargets = await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
-        const linkPaths = getProjectResourcePaths(projectDir, type, name, effectiveTargets);
+        const effectiveTargets = scope === "global"
+            ? await this.resolveGlobalInstallAgents(projectDir, type, name, agents, resourceMeta?.agents)
+            : await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
+        const linkPaths = scope === "global"
+            ? getGlobalResourcePaths(this.paths.getHomeDir(), type, name, effectiveTargets)
+            : getProjectResourcePaths(projectDir, type, name, effectiveTargets);
         for (const linkPath of linkPaths) {
             await this.materializeResource(storePath, linkPath, mode);
         }
-        await this.lockStore.upsertResource(projectDir, sourceInfo, {
-            type,
-            name,
-            version: resolvedVersion,
-            agents: effectiveTargets,
-            mode,
-        });
+        if (scope === "project") {
+            if (!sourceInfo) {
+                throw new Error("Project install requires source lock information.");
+            }
+            await this.lockStore.upsertResource(projectDir, sourceInfo, {
+                type,
+                name,
+                version: resolvedVersion,
+                agents: effectiveTargets,
+                mode,
+            });
+        }
         return { type, name, version: resolvedVersion, linkPath: linkPaths[0], mode };
     }
     async loadSourceFromConfig() {
@@ -467,6 +480,16 @@ export class ServiceFactory {
         }
         return normalizeAgents(fallbackAgents);
     }
+    async resolveGlobalInstallAgents(projectDir, type, name, explicitAgents, fallbackAgents) {
+        if (explicitAgents?.length) {
+            return normalizeAgents(explicitAgents);
+        }
+        const locked = await this.getLockedResource(projectDir, type, name);
+        if (locked?.agents?.length) {
+            return normalizeAgents(locked.agents);
+        }
+        return this.resolveEffectiveAgents(projectDir, undefined, fallbackAgents);
+    }
     async getConfiguredAgents(projectDir) {
         const [globalConfig, projectConfig] = await Promise.all([
             this.stateStore.loadConfig(),

package/dist/utils/agent-configs.js

@@ -46,8 +46,14 @@ export function normalizeAgent(input) {
     return AGENT_ALIASES.get(input.trim().toLowerCase());
 }
 export function getProjectResourcePaths(projectDir, type, name, agents) {
+    return getResourcePaths(projectDir, type, name, agents);
+}
+export function getGlobalResourcePaths(homeDir, type, name, agents) {
+    return getResourcePaths(homeDir, type, name, agents);
+}
+function getResourcePaths(rootDir, type, name, agents) {
     const typeDir = getTypeDir(type);
-    return normalizeAgents(agents).map((agent) => path.join(projectDir, getAgentBaseDir(agent), typeDir, name));
+    return normalizeAgents(agents).map((agent) => path.join(rootDir, getAgentBaseDir(agent), typeDir, name));
 }
 export function getSupportedAgentNames() {
     return AGENT_CONFIGS.map((config) => config.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hi-man/himan",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Prompt and agent asset management CLI",
   "keywords": [
     "ai",