@hi-man/himan 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -6,6 +6,27 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-05-11
+
+### Changed
+
+- Changed project guidance to require changelog updates for user-visible CLI behavior changes.
+
+### Fixed
+
+- Fixed `himan publish` so publishing stops with `E_PUBLISH_NO_CHANGES` when the resource content matches the latest published version.
+
+## [0.3.3] - 2026-05-11
+
+### Added
+
+- Added `himan project list` and `himan list --installed` to show resources recorded in the current project's `himan.lock`.
+
+### Changed
+
+- Changed `himan list` without a resource type to group all source resources by `rule`, `command`, and `skill`.
+- Added `himan list --brief` to hide resource descriptions in concise list output.
+
 ## [0.3.2] - 2026-05-08
 
 ### Added

package/README.md

@@ -133,7 +133,7 @@ your-himan-source/
 
 | 命令                             | 说明                                                                                |
 | -------------------------------- | ----------------------------------------------------------------------------------- |
-| `list [type] [--agent a,b] [--json]` | 列出当前 default source 的资源；可按 agent 过滤；`type` 默认 `rule` |
+| `list [type] [--agent a,b] [--brief] [--installed] [--json]` | 默认列出当前 default source 的资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源 |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
 | `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
 
@@ -141,6 +141,7 @@ your-himan-source/
 
 | 命令                              | 说明                                                      |
 | --------------------------------- | --------------------------------------------------------- |
+| `list [type] [--agent a,b] [--json]` | 查看当前项目 `himan.lock` 中记录的已安装资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示 |
 | `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` 条目           |
@@ -159,14 +160,14 @@ your-himan-source/
 
 - `himan resource list|history|create ...`
 - `himan-resource list|history|create ...`（兼容保留：也可执行 install/dev/uninstall/publish）
-- `himan project install|dev|uninstall|publish ...`
-- `himan-project install|dev|uninstall|publish ...`
+- `himan project list|install|dev|uninstall|publish ...`
+- `himan-project list|install|dev|uninstall|publish ...`
 - `himan agent list|use|current|clear ...`
 
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 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>` 开发目录。
+`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 

package/dist/adapters/source/git-source-adapter.js

@@ -4,6 +4,7 @@ import semver from "semver";
 import { HimanError, errorCodes } from "../../utils/errors.js";
 import { promises as fs } from "node:fs";
 import { createHash } from "node:crypto";
+import os from "node:os";
 import path from "node:path";
 import YAML from "yaml";
 import { IndexCacheStore } from "../../state/index-cache-store.js";
@@ -52,6 +53,7 @@ export class GitSourceAdapter {
         const repoDir = this.getRepoDir();
         const targetDir = path.join(repoDir, `${type}s`, name);
         const metadataResult = await this.validatePublishResource(type, name, sourceDir);
+        await this.ensurePublishHasContentChanges(type, name, sourceDir);
         const sameDir = await this.isSameDirectory(sourceDir, targetDir);
         if (!sameDir) {
             await fs.rm(targetDir, { recursive: true, force: true });
@@ -261,6 +263,76 @@ export class GitSourceAdapter {
             metadata.agents = agents;
         return metadata;
     }
+    async ensurePublishHasContentChanges(type, name, sourceDir) {
+        const latest = (await this.history(type, name))[0];
+        if (!latest)
+            return;
+        const previousDir = await fs.mkdtemp(path.join(os.tmpdir(), "himan-publish-"));
+        try {
+            await this.repoManager.archiveResource(this.getRepoDir(), latest.raw, `${type}s/${name}`, previousDir);
+            const [nextSnapshot, previousSnapshot] = await Promise.all([
+                this.readComparableResourceSnapshot(sourceDir),
+                this.readComparableResourceSnapshot(previousDir),
+            ]);
+            if (this.resourceSnapshotsEqual(nextSnapshot, previousSnapshot)) {
+                throw new HimanError(errorCodes.PUBLISH_NO_CHANGES, `No changes to publish for ${type}/${name}.`);
+            }
+        }
+        finally {
+            await fs.rm(previousDir, { recursive: true, force: true });
+        }
+    }
+    async readComparableResourceSnapshot(resourceDir) {
+        const files = await this.listResourceFiles(resourceDir);
+        const snapshot = new Map();
+        for (const file of files) {
+            const relative = this.toPosixPath(path.relative(resourceDir, file));
+            const content = await fs.readFile(file, "utf8");
+            snapshot.set(relative, relative === "himan.yaml"
+                ? this.normalizeComparableResourceMetadata(content)
+                : content);
+        }
+        return snapshot;
+    }
+    async listResourceFiles(resourceDir) {
+        const result = [];
+        const entries = await fs.readdir(resourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(resourceDir, entry.name);
+            if (entry.isDirectory()) {
+                result.push(...(await this.listResourceFiles(fullPath)));
+            }
+            else if (entry.isFile()) {
+                result.push(fullPath);
+            }
+        }
+        return result.sort((a, b) => a.localeCompare(b));
+    }
+    normalizeComparableResourceMetadata(content) {
+        try {
+            const parsed = YAML.parse(content);
+            if (!this.isRecord(parsed))
+                return content;
+            const normalized = { ...parsed };
+            delete normalized.version;
+            return YAML.stringify(normalized);
+        }
+        catch {
+            return content;
+        }
+    }
+    resourceSnapshotsEqual(a, b) {
+        if (a.size !== b.size)
+            return false;
+        for (const [file, content] of a) {
+            if (b.get(file) !== content)
+                return false;
+        }
+        return true;
+    }
+    toPosixPath(filePath) {
+        return filePath.split(path.sep).join("/");
+    }
     invalidResourceMetadata(type, name, message, details) {
         return new HimanError(errorCodes.INVALID_RESOURCE_METADATA, `Invalid metadata for ${type}/${name}: ${message}`, details);
     }

package/dist/cli/builders.js

@@ -25,7 +25,7 @@ export function buildCli() {
     registerAgentCommands(agentCmd, services);
     // Backward compatible top-level resource lifecycle commands.
     registerResourceCommands(program, services);
-    registerProjectCommands(program, services);
+    registerProjectCommands(program, services, { includeList: false });
     return program;
 }
 export function buildSourceCli() {
@@ -43,7 +43,7 @@ export function buildResourceCli() {
         .description("Manage default agent configuration");
     registerAgentCommands(agentCmd, services);
     // Backward compatible: keep project lifecycle commands in himan-resource.
-    registerProjectCommands(program, services);
+    registerProjectCommands(program, services, { includeList: false });
     return program;
 }
 export function buildProjectCli() {
@@ -62,10 +62,11 @@ Command groups:
   source   Data source management (git now, registry reserved)
            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
+           list, list --installed, history, create,
+           resource list, resource history, resource create
   project  Resource usage lifecycle in current project or user-level agent dirs
-           install, dev, uninstall, publish,
-           project install, project dev, project uninstall, project publish
+           list, install, dev, uninstall, publish,
+           project list, project install, project dev, project uninstall, project publish
   agent    Default agent configuration
            agent list, agent use, agent current, agent clear
 `);

package/dist/cli/installed-resource-list.js

@@ -0,0 +1,46 @@
+const RESOURCE_TYPES = ["rule", "command", "skill"];
+export async function listInstalledResourceGroups(services, projectDir, agents) {
+    const resources = await services.listInstalled(projectDir, undefined, agents);
+    return groupInstalledResources(resources);
+}
+export function groupInstalledResources(resources) {
+    return {
+        rule: resources.filter((resource) => resource.type === "rule"),
+        command: resources.filter((resource) => resource.type === "command"),
+        skill: resources.filter((resource) => resource.type === "skill"),
+    };
+}
+export function writeInstalledResourceGroups(groups) {
+    const hasResources = RESOURCE_TYPES.some((type) => groups[type].length > 0);
+    if (!hasResources) {
+        process.stdout.write("No installed resources found.\n");
+        return;
+    }
+    for (const type of RESOURCE_TYPES) {
+        const resources = groups[type];
+        if (resources.length === 0)
+            continue;
+        process.stdout.write(`${formatGroupTitle(type)}:\n`);
+        writeInstalledResources(resources);
+    }
+}
+export function writeInstalledResources(resources) {
+    if (resources.length === 0) {
+        process.stdout.write("No installed resources found.\n");
+        return;
+    }
+    for (const resource of resources) {
+        process.stdout.write(`- ${formatInstalledResource(resource)}\n`);
+    }
+}
+function formatInstalledResource(resource) {
+    const agents = resource.agents.length > 0 ? ` [${resource.agents.join(", ")}]` : "";
+    return `${resource.type}/${resource.name}@${resource.version}${agents} (${resource.mode})`;
+}
+function formatGroupTitle(type) {
+    if (type === "rule")
+        return "Rules";
+    if (type === "command")
+        return "Commands";
+    return "Skills";
+}

package/dist/cli/project-commands.js

@@ -1,7 +1,37 @@
 import { HimanError, errorCodes } from "../utils/errors.js";
 import { getSupportedAgentNames, normalizeAgent } from "../utils/agent-configs.js";
+import { listInstalledResourceGroups, writeInstalledResourceGroups, writeInstalledResources, } from "./installed-resource-list.js";
 import { runAction } from "./shared.js";
-export function registerProjectCommands(command, services) {
+export function registerProjectCommands(command, services, options = {}) {
+    if (options.includeList !== false) {
+        command
+            .command("list")
+            .argument("[type]", "resource type")
+            .option("--agent <list>", "agent list filter, comma separated")
+            .option("--json", "output json format")
+            .description("List resources installed in current project")
+            .action(async (type, commandOptions) => {
+            await runAction(async () => {
+                const agents = parseAgents(commandOptions.agent);
+                if (!type) {
+                    const groups = await listInstalledResourceGroups(services, process.cwd(), agents);
+                    if (commandOptions.json) {
+                        process.stdout.write(`${JSON.stringify(groups, null, 2)}\n`);
+                        return;
+                    }
+                    writeInstalledResourceGroups(groups);
+                    return;
+                }
+                const resourceType = ensureResourceType(type);
+                const resources = await services.listInstalled(process.cwd(), resourceType, agents);
+                if (commandOptions.json) {
+                    process.stdout.write(`${JSON.stringify(resources, null, 2)}\n`);
+                    return;
+                }
+                writeInstalledResources(resources);
+            });
+        });
+    }
     command
         .command("install")
         .argument("[type]", "resource type")

package/dist/cli/resource-commands.js

@@ -1,28 +1,41 @@
 import { HimanError, errorCodes } from "../utils/errors.js";
 import { getSupportedAgentNames, normalizeAgent } from "../utils/agent-configs.js";
+import { listInstalledResourceGroups, writeInstalledResourceGroups, writeInstalledResources, } from "./installed-resource-list.js";
 import { runAction } from "./shared.js";
+const RESOURCE_TYPES = ["rule", "command", "skill"];
 export function registerResourceCommands(command, services) {
     command
         .command("list")
-        .argument("[type]", "resource type", "rule")
+        .argument("[type]", "resource type")
         .option("--agent <list>", "agent list filter, comma separated")
+        .option("--brief", "hide resource descriptions")
+        .option("--installed", "list resources installed in current project")
         .option("--json", "output json format")
-        .description("List resources from current default source")
+        .description("List resources from current default source or project installs")
         .action(async (type, options) => {
         await runAction(async () => {
-            const resourceType = ensureResourceType(type);
-            const resources = await services.list(resourceType, parseAgents(options.agent));
-            if (options.json) {
-                process.stdout.write(`${JSON.stringify(resources, null, 2)}\n`);
+            const agents = parseAgents(options.agent);
+            const showDescription = !options.brief;
+            if (options.installed) {
+                await writeInstalledList(services, type, agents, Boolean(options.json));
                 return;
             }
-            if (resources.length === 0) {
-                process.stdout.write("No resources found.\n");
+            if (!type) {
+                const groups = await listGroupedResources(services, agents);
+                if (options.json) {
+                    process.stdout.write(`${JSON.stringify(formatResourceGroups(groups, showDescription), null, 2)}\n`);
+                    return;
+                }
+                writeGroupedResources(groups, showDescription);
                 return;
             }
-            for (const resource of resources) {
-                process.stdout.write(`- ${resource.type}/${resource.name}${resource.description ? `: ${resource.description}` : ""}\n`);
+            const resourceType = ensureResourceType(type);
+            const resources = await services.list(resourceType, agents);
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(formatResources(resources, showDescription), null, 2)}\n`);
+                return;
             }
+            writeResourceList(resources, showDescription);
         });
     });
     command
@@ -79,12 +92,82 @@ export function registerResourceCommands(command, services) {
         });
     });
 }
+async function writeInstalledList(services, type, agents, json) {
+    if (!type) {
+        const groups = await listInstalledResourceGroups(services, process.cwd(), agents);
+        if (json) {
+            process.stdout.write(`${JSON.stringify(groups, null, 2)}\n`);
+            return;
+        }
+        writeInstalledResourceGroups(groups);
+        return;
+    }
+    const resourceType = ensureResourceType(type);
+    const resources = await services.listInstalled(process.cwd(), resourceType, agents);
+    if (json) {
+        process.stdout.write(`${JSON.stringify(resources, null, 2)}\n`);
+        return;
+    }
+    writeInstalledResources(resources);
+}
 function ensureResourceType(type) {
     if (type !== "rule" && type !== "command" && type !== "skill") {
         throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type: ${type}`);
     }
     return type;
 }
+async function listGroupedResources(services, agents) {
+    return {
+        rule: await services.list("rule", agents),
+        command: await services.list("command", agents),
+        skill: await services.list("skill", agents),
+    };
+}
+function formatResourceGroups(groups, showDescription) {
+    return {
+        rule: formatResources(groups.rule, showDescription),
+        command: formatResources(groups.command, showDescription),
+        skill: formatResources(groups.skill, showDescription),
+    };
+}
+function formatResources(resources, showDescription) {
+    if (showDescription)
+        return resources;
+    return resources.map((resource) => {
+        const { description: _description, ...withoutDescription } = resource;
+        return withoutDescription;
+    });
+}
+function writeGroupedResources(groups, showDescription) {
+    const hasResources = RESOURCE_TYPES.some((type) => groups[type].length > 0);
+    if (!hasResources) {
+        process.stdout.write("No resources found.\n");
+        return;
+    }
+    for (const type of RESOURCE_TYPES) {
+        const resources = groups[type];
+        if (resources.length === 0)
+            continue;
+        process.stdout.write(`${formatGroupTitle(type)}:\n`);
+        writeResourceList(resources, showDescription);
+    }
+}
+function writeResourceList(resources, showDescription) {
+    if (resources.length === 0) {
+        process.stdout.write("No resources found.\n");
+        return;
+    }
+    for (const resource of resources) {
+        process.stdout.write(`- ${resource.type}/${resource.name}${showDescription && resource.description ? `: ${resource.description}` : ""}\n`);
+    }
+}
+function formatGroupTitle(type) {
+    if (type === "rule")
+        return "Rules";
+    if (type === "command")
+        return "Commands";
+    return "Skills";
+}
 function parseAgents(input) {
     if (!input)
         return undefined;

package/dist/services/index.js

@@ -157,6 +157,28 @@ export class ServiceFactory {
         const selected = normalizeAgents(agents);
         return resources.filter((resource) => normalizeAgents(resource.agents).some((agent) => selected.includes(agent)));
     }
+    async listInstalled(projectDir, type, agents) {
+        const { lock, state } = await this.lockStore.loadWithState(projectDir);
+        if (state === "invalid") {
+            throw new HimanError(errorCodes.LOCK_INVALID, `Lock file is invalid: ${this.lockStore.getLockPath(projectDir)}`);
+        }
+        if (state === "missing" || !lock) {
+            return [];
+        }
+        const selectedAgents = agents?.length ? normalizeAgents(agents) : undefined;
+        return lock.resources
+            .filter((resource) => !type || resource.type === type)
+            .map((resource) => ({
+            type: resource.type,
+            name: resource.name,
+            version: resource.version,
+            agents: normalizeAgents(resource.agents),
+            mode: this.resolveInstallMode(resource.mode),
+            updatedAt: resource.updatedAt,
+        }))
+            .filter((resource) => !selectedAgents ||
+            resource.agents.some((agent) => selectedAgents.includes(agent)));
+    }
     async history(type, name) {
         const source = await this.loadSourceFromConfig();
         return source.history(type, name);

package/docs/error-codes.md

@@ -116,7 +116,7 @@
 ### `E_PUBLISH_NO_CHANGES`
 
 - **含义**：发布时没有可提交的资源变更。
-- **常见触发**：重复发布已写入相同内容和版本的资源目录。
+- **常见触发**：重复发布与最新已发布版本内容一致的资源目录；`himan.yaml` 中仅版本字段不同也会视为无内容变化。
 - **建议处理**：确认资源内容或元数据已经变更，再重新执行 `publish`。
 
 ### `E_UNSUPPORTED_RESOURCE_TYPE`

package/package.json

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