@hi-man/himan 0.3.0 → 0.3.1

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.1] - 2026-05-07
+
+### Added
+
+- Added the `common-project-changelog` skill to enforce changelog and version history placement rules.
+- Added `scripts/release-changelog.mjs` so package version scripts release `[Unreleased]` changelog entries into the new version section.
+
+### Changed
+
+- Changed `himan source init-docs --force` to list existing source resources in generated docs.
+- Changed `himan source init-docs` to commit and push generated source docs when files changed.
+- Changed generated source docs to show the latest tagged resource version when one exists.
+- Changed `himan publish` to allow resources without `himan.yaml` when their default entry file exists.
+- Changed resource discovery to infer `rule`, `command`, and `skill` resources from default entry files when `himan.yaml` is absent.
+- Changed `himan publish` to reinstall the published version in copy mode, update the lock file, and remove the resource dev directory.
+- Changed package version scripts to archive `[Unreleased]` changelog entries after version bumps.
+
+### Fixed
+
+- Fixed `himan source init-docs --force` so existing Codex-style skills with `SKILL.md` front matter are included in generated source docs.
+
 ## [0.3.0] - 2026-05-07
 
 ### Added

package/README.md

@@ -91,10 +91,10 @@ your-himan-source/
 - `README.md`：source 仓库入口文档，建议记录资源目录说明、推荐安装方式、默认 agent 策略、常用资源索引和维护约定。
 - `CHANGELOG.md`：source 仓库级变更记录，建议记录新增、变更、废弃、移除的资源，以及重要版本发布说明。
 - `rules/`、`commands/`、`skills/`：按资源类型分组；每个子目录是一份 himan 资源。
-- `himan.yaml`：资源元数据，供 himan 扫描、发布和安装时读取。
-- `content.md` / `SKILL.md`：资源主入口，由 `himan.yaml` 的 `entry` 字段指定。
+- `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent。
+- `content.md` / `SKILL.md`：资源主入口；没有 `himan.yaml` 时，`rule` / `command` 默认使用 `content.md`，`skill` 默认使用 `SKILL.md`。
 
-可通过 `himan source init-docs` 为当前 default source 生成根目录文档模板；默认只创建缺失文件，`--force` 才覆盖已有 `README.md` / `CHANGELOG.md`，`--dry-run` 可预览结果。
+可通过 `himan source init-docs` 为当前 default source 生成根目录文档模板；默认只创建缺失文件，`--force` 会覆盖已有 `README.md` / `CHANGELOG.md`，并把当前 source 中已有的 `rule`、`command`、`skill` 整理进 README 资源索引和 CHANGELOG 初始条目；资源引用会优先带上 Git tag 中的最新 semver 版本；对于尚未补齐 `himan.yaml` 的资源，会按默认入口识别，skill 还会读取 `skills/<name>/SKILL.md` front matter。`--dry-run` 可预览结果。有实际文件变更时，命令会提交并 push 到当前 Git source。
 
 `himan create` 和 `himan publish` 会自动维护 source 根目录文档：
 
@@ -161,7 +161,7 @@ your-himan-source/
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
 若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。发布前会校验 `himan.yaml` 与入口文件；需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。若该资源已在 lock 中，发布后会同步更新 lock 版本。
+`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。发布需要可推送的 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/git/repo-manager.js

@@ -48,6 +48,20 @@ export class RepoManager {
     }
     async commitTagAndPush(repoDir, message, tag, branch, paths = ["."]) {
         const git = simpleGit(repoDir);
+        await this.commitChanges(git, message, paths, true);
+        await git.addTag(tag);
+        await this.pushCurrentBranch(git, branch);
+        await git.pushTags("origin");
+    }
+    async commitAndPush(repoDir, message, branch, paths = ["."]) {
+        const git = simpleGit(repoDir);
+        const committed = await this.commitChanges(git, message, paths, false);
+        if (!committed)
+            return false;
+        await this.pushCurrentBranch(git, branch);
+        return true;
+    }
+    async commitChanges(git, message, paths, requireChanges) {
         const pathspecs = paths.length > 0 ? paths : ["."];
         await git.add(pathspecs);
         const stagedFiles = await git.raw([
@@ -58,14 +72,18 @@ export class RepoManager {
             ...pathspecs,
         ]);
         if (!stagedFiles.trim()) {
-            throw new HimanError(errorCodes.PUBLISH_NO_CHANGES, "No changes to publish.");
+            if (requireChanges) {
+                throw new HimanError(errorCodes.PUBLISH_NO_CHANGES, "No changes to publish.");
+            }
+            return false;
         }
         await git.commit(message, pathspecs);
-        await git.addTag(tag);
+        return true;
+    }
+    async pushCurrentBranch(git, branch) {
         const currentBranch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
         const targetBranch = branch ?? currentBranch;
         await git.push("origin", targetBranch);
-        await git.pushTags("origin");
     }
     async exists(targetPath) {
         try {

package/dist/adapters/resource/resource-scanner.js

@@ -15,28 +15,80 @@ export class ResourceScanner {
         const result = [];
         for (const resourceDir of resourceDirs) {
             const yamlPath = path.join(baseDir, resourceDir.name, "himan.yaml");
-            if (!(await this.exists(yamlPath)))
+            if (await this.exists(yamlPath)) {
+                const raw = await fs.readFile(yamlPath, "utf8");
+                const parsed = YAML.parse(raw);
+                if (!parsed)
+                    continue;
+                if (parsed.type !== type)
+                    continue;
+                if (!parsed.name || !parsed.entry)
+                    continue;
+                result.push({
+                    name: parsed.name,
+                    type,
+                    entry: parsed.entry,
+                    description: parsed.description,
+                    agents: Array.isArray(parsed.agents)
+                        ? (parsed.agents ?? [])
+                        : (parsed.targets ?? []),
+                });
                 continue;
-            const raw = await fs.readFile(yamlPath, "utf8");
-            const parsed = YAML.parse(raw);
-            if (!parsed)
-                continue;
-            if (parsed.type !== type)
-                continue;
-            if (!parsed.name || !parsed.entry)
-                continue;
-            result.push({
-                name: parsed.name,
-                type,
-                entry: parsed.entry,
-                description: parsed.description,
-                agents: Array.isArray(parsed.agents)
-                    ? (parsed.agents ?? [])
-                    : (parsed.targets ?? []),
-            });
+            }
+            const inferred = await this.inferResourceMeta(path.join(baseDir, resourceDir.name), resourceDir.name, type);
+            if (inferred)
+                result.push(inferred);
         }
         return result;
     }
+    async inferResourceMeta(resourceDir, dirName, type) {
+        const entry = this.getDefaultEntry(type);
+        const entryPath = path.join(resourceDir, entry);
+        if (!(await this.exists(entryPath)))
+            return undefined;
+        const metadata = type === "skill" ? await this.readSkillFrontMatter(entryPath) : null;
+        return {
+            name: this.readStringMetadata(metadata, "name") ?? dirName,
+            type,
+            entry,
+            description: this.readStringMetadata(metadata, "description"),
+            agents: this.readStringArrayMetadata(metadata, "agents") ??
+                this.readStringArrayMetadata(metadata, "targets") ??
+                [],
+        };
+    }
+    async readSkillFrontMatter(skillPath) {
+        const raw = await fs.readFile(skillPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw.trimStart());
+        if (!match)
+            return null;
+        try {
+            const parsed = YAML.parse(match[1]);
+            return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+                ? parsed
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readStringMetadata(metadata, key) {
+        const value = metadata?.[key];
+        if (typeof value !== "string")
+            return undefined;
+        const trimmed = value.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    readStringArrayMetadata(metadata, key) {
+        const value = metadata?.[key];
+        if (!Array.isArray(value))
+            return undefined;
+        const items = value
+            .filter((item) => typeof item === "string")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return items.length > 0 ? items : undefined;
+    }
     async exists(targetPath) {
         try {
             await fs.access(targetPath);
@@ -53,4 +105,7 @@ export class ResourceScanner {
             return "commands";
         return "skills";
     }
+    getDefaultEntry(type) {
+        return type === "skill" ? "SKILL.md" : "content.md";
+    }
 }

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

@@ -27,7 +27,7 @@ export class GitSourceAdapter {
         const repoId = this.sourceConfig?.repoId ?? "default";
         const typeDir = this.getTypeDir(type);
         const baseDir = path.join(repoDir, typeDir);
-        const metadataHash = await this.getResourceMetadataHash(baseDir);
+        const metadataHash = await this.getResourceMetadataHash(baseDir, type);
         const cached = await this.indexStore.get(repoId, type);
         if (cached && cached.metadataHash === metadataHash) {
             return cached.resources;
@@ -51,20 +51,22 @@ export class GitSourceAdapter {
     async publish(type, name, version, sourceDir) {
         const repoDir = this.getRepoDir();
         const targetDir = path.join(repoDir, `${type}s`, name);
-        const metadata = await this.validatePublishResource(type, name, sourceDir);
+        const metadataResult = await this.validatePublishResource(type, name, sourceDir);
         const sameDir = await this.isSameDirectory(sourceDir, targetDir);
         if (!sameDir) {
             await fs.rm(targetDir, { recursive: true, force: true });
             await fs.mkdir(path.dirname(targetDir), { recursive: true });
             await fs.cp(sourceDir, targetDir, { recursive: true });
         }
-        const yamlPath = path.join(targetDir, "himan.yaml");
-        metadata.version = version;
-        await fs.writeFile(yamlPath, YAML.stringify(metadata), "utf8");
+        if (metadataResult.shouldWriteMetadata) {
+            const yamlPath = path.join(targetDir, "himan.yaml");
+            const metadata = { ...metadataResult.metadata, version };
+            await fs.writeFile(yamlPath, YAML.stringify(metadata), "utf8");
+        }
         const docsPaths = await this.maintainSourceDocs(repoDir, {
             section: "Changed",
             line: `- Published \`${type}/${name}@${version}\`.`,
-        });
+        }, new Map([[this.getResourceVersionOverrideKey(type, name), version]]));
         const tag = `${type}/${name}@${version}`;
         await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag, undefined, [
             path.relative(repoDir, targetDir),
@@ -118,10 +120,11 @@ export class GitSourceAdapter {
             },
             {
                 path: path.join(repoDir, "CHANGELOG.md"),
-                content: this.buildChangelogContent(),
+                content: await this.buildChangelogContent(repoDir),
             },
         ];
         const results = [];
+        const changedPaths = [];
         for (const file of files) {
             const exists = await this.exists(file.path);
             const action = exists ? (options.force ? "updated" : "skipped") : "created";
@@ -129,12 +132,17 @@ export class GitSourceAdapter {
             results.push({ path: file.path, action, reason });
             if (!options.dryRun && action !== "skipped") {
                 await fs.writeFile(file.path, file.content, "utf8");
+                changedPaths.push(path.relative(repoDir, file.path));
             }
         }
+        const committed = !options.dryRun &&
+            changedPaths.length > 0 &&
+            (await this.repoManager.commitAndPush(repoDir, "docs: init source docs", undefined, changedPaths));
         return {
             sourceDir: repoDir,
             files: results,
             dryRun: Boolean(options.dryRun),
+            committed,
         };
     }
     getRepoDir() {
@@ -164,7 +172,10 @@ export class GitSourceAdapter {
     async validatePublishResource(type, name, resourceDir) {
         const yamlPath = path.join(resourceDir, "himan.yaml");
         if (!(await this.exists(yamlPath))) {
-            throw this.invalidResourceMetadata(type, name, "Missing himan.yaml for publish.", { yamlPath });
+            return {
+                metadata: await this.inferPublishResourceMetadata(type, name, resourceDir),
+                shouldWriteMetadata: false,
+            };
         }
         const raw = await fs.readFile(yamlPath, "utf8");
         let parsed;
@@ -210,11 +221,45 @@ export class GitSourceAdapter {
             throw this.invalidResourceMetadata(type, name, `Resource entry is not a file: ${entry}`, { yamlPath, entry, entryPath });
         }
         return {
-            ...parsed,
+            metadata: {
+                ...parsed,
+                name,
+                type,
+                entry,
+            },
+            shouldWriteMetadata: true,
+        };
+    }
+    async inferPublishResourceMetadata(type, name, resourceDir) {
+        const entry = this.getDefaultEntry(type);
+        const entryPath = path.join(resourceDir, entry);
+        let entryStat;
+        try {
+            entryStat = await fs.stat(entryPath);
+        }
+        catch (error) {
+            if (!this.isNotFoundError(error)) {
+                throw error;
+            }
+            throw this.invalidResourceMetadata(type, name, `Missing himan.yaml and default entry file for publish: ${entry}`, { yamlPath: path.join(resourceDir, "himan.yaml"), entry, entryPath });
+        }
+        if (!entryStat.isFile()) {
+            throw this.invalidResourceMetadata(type, name, `Default resource entry is not a file: ${entry}`, { entry, entryPath });
+        }
+        const frontMatter = type === "skill" ? await this.readSkillFrontMatter(entryPath) : null;
+        const metadata = {
             name,
             type,
             entry,
         };
+        const description = this.readStringMetadata(frontMatter, "description");
+        if (description)
+            metadata.description = description;
+        const agents = this.readStringArrayMetadata(frontMatter, "agents") ??
+            this.readStringArrayMetadata(frontMatter, "targets");
+        if (agents)
+            metadata.agents = agents;
+        return metadata;
     }
     invalidResourceMetadata(type, name, message, details) {
         return new HimanError(errorCodes.INVALID_RESOURCE_METADATA, `Invalid metadata for ${type}/${name}: ${message}`, details);
@@ -229,7 +274,7 @@ export class GitSourceAdapter {
             return "commands";
         return "skills";
     }
-    async getResourceMetadataHash(baseDir) {
+    async getResourceMetadataHash(baseDir, type) {
         const hash = createHash("sha256");
         hash.update("himan-resource-index-v1");
         if (!(await this.exists(baseDir))) {
@@ -255,6 +300,18 @@ export class GitSourceAdapter {
                     throw error;
                 }
                 hash.update("\0yaml-missing");
+                const entryPath = path.join(baseDir, resourceDirName, this.getDefaultEntry(type));
+                try {
+                    const raw = await fs.readFile(entryPath);
+                    hash.update("\0entry:");
+                    hash.update(raw);
+                }
+                catch (entryError) {
+                    if (!this.isNotFoundError(entryError)) {
+                        throw entryError;
+                    }
+                    hash.update("\0entry-missing");
+                }
             }
         }
         return hash.digest("hex");
@@ -277,8 +334,8 @@ export class GitSourceAdapter {
         }
         return `# ${name}\n\nDescribe skill workflow here.\n`;
     }
-    async buildReadmeContent(repoDir) {
-        const resourceLines = await this.buildResourceIndex(repoDir);
+    async buildReadmeContent(repoDir, versionOverrides = new Map()) {
+        const resourceLines = await this.buildResourceIndex(repoDir, versionOverrides);
         const repo = this.sourceConfig?.repo ?? "<git_url>";
         return [
             `# ${this.getSourceTitle()}`,
@@ -309,7 +366,8 @@ export class GitSourceAdapter {
             "",
         ].join("\n");
     }
-    buildChangelogContent() {
+    async buildChangelogContent(repoDir) {
+        const resourceLines = await this.buildExistingResourceChangelogLines(repoDir);
         return [
             "# Changelog",
             "",
@@ -320,23 +378,21 @@ export class GitSourceAdapter {
             "### Added",
             "",
             "- Initial source README/CHANGELOG scaffold.",
+            ...resourceLines,
             "",
         ].join("\n");
     }
-    async buildResourceIndex(repoDir) {
+    async buildResourceIndex(repoDir, versionOverrides = new Map()) {
         const sections = [];
         for (const type of RESOURCE_TYPES) {
-            const resources = (await this.scanner.scanByType(repoDir, type)).sort((a, b) => a.name.localeCompare(b.name));
+            const resources = await this.collectResourceDocsItems(repoDir, type);
             sections.push(`### ${this.getTypeLabel(type)}`, "");
             if (resources.length === 0) {
                 sections.push(`- No ${type} resources yet.`, "");
                 continue;
             }
             for (const resource of resources) {
-                const version = await this.readResourceVersion(repoDir, resource.type, resource.name);
-                const ref = version
-                    ? `${resource.type}/${resource.name}@${version}`
-                    : `${resource.type}/${resource.name}`;
+                const ref = await this.getResourceRef(repoDir, resource.type, resource.name, versionOverrides);
                 sections.push(`- \`${ref}\`${resource.description ? `: ${resource.description}` : ""}`);
             }
             sections.push("");
@@ -346,21 +402,98 @@ export class GitSourceAdapter {
         }
         return sections;
     }
-    async maintainSourceDocs(repoDir, changelogEntry) {
-        const readmePath = await this.updateReadmeResourceIndex(repoDir);
+    async buildExistingResourceChangelogLines(repoDir) {
+        const lines = [];
+        for (const type of RESOURCE_TYPES) {
+            const resources = await this.collectResourceDocsItems(repoDir, type);
+            for (const resource of resources) {
+                const ref = await this.getResourceRef(repoDir, resource.type, resource.name);
+                lines.push(`- Documented existing resource \`${ref}\`.`);
+            }
+        }
+        return lines;
+    }
+    async collectResourceDocsItems(repoDir, type) {
+        const resources = await this.scanner.scanByType(repoDir, type);
+        const items = resources.map((resource) => ({
+            name: resource.name,
+            type: resource.type,
+            description: resource.description,
+        }));
+        const managedNames = new Set(resources.map((resource) => resource.name));
+        items.push(...(await this.scanEntryBasedDocsItems(repoDir, type, managedNames)));
+        return items.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async scanEntryBasedDocsItems(repoDir, type, managedNames) {
+        const baseDir = path.join(repoDir, this.getTypeDir(type));
+        if (!(await this.exists(baseDir)))
+            return [];
+        const entries = await fs.readdir(baseDir, { withFileTypes: true });
+        const items = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const resourceEntry = this.getDefaultEntry(type);
+            const entryPath = path.join(baseDir, entry.name, resourceEntry);
+            if (!(await this.exists(entryPath)))
+                continue;
+            const metadata = type === "skill" ? await this.readSkillFrontMatter(entryPath) : null;
+            const name = this.readStringMetadata(metadata, "name") ?? entry.name;
+            if (managedNames.has(name) || managedNames.has(entry.name))
+                continue;
+            items.push({
+                name,
+                type,
+                description: this.readStringMetadata(metadata, "description"),
+            });
+        }
+        return items;
+    }
+    async readSkillFrontMatter(skillPath) {
+        const raw = await fs.readFile(skillPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw.trimStart());
+        if (!match)
+            return null;
+        try {
+            const parsed = YAML.parse(match[1]);
+            return this.isRecord(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readStringMetadata(metadata, key) {
+        const value = metadata?.[key];
+        if (typeof value !== "string")
+            return undefined;
+        const trimmed = value.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    readStringArrayMetadata(metadata, key) {
+        const value = metadata?.[key];
+        if (!Array.isArray(value))
+            return undefined;
+        const items = value
+            .filter((item) => typeof item === "string")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return items.length > 0 ? items : undefined;
+    }
+    async maintainSourceDocs(repoDir, changelogEntry, versionOverrides = new Map()) {
+        const readmePath = await this.updateReadmeResourceIndex(repoDir, versionOverrides);
         const changelogPath = await this.updateChangelog(repoDir, changelogEntry);
         return [readmePath, changelogPath];
     }
-    async updateReadmeResourceIndex(repoDir) {
+    async updateReadmeResourceIndex(repoDir, versionOverrides = new Map()) {
         const readmePath = path.join(repoDir, "README.md");
         if (!(await this.exists(readmePath))) {
-            await fs.writeFile(readmePath, await this.buildReadmeContent(repoDir), "utf8");
+            await fs.writeFile(readmePath, await this.buildReadmeContent(repoDir, versionOverrides), "utf8");
             return readmePath;
         }
         const current = await fs.readFile(readmePath, "utf8");
         const resourceSection = [
             README_RESOURCES_START,
-            ...(await this.buildResourceIndex(repoDir)),
+            ...(await this.buildResourceIndex(repoDir, versionOverrides)),
             README_RESOURCES_END,
         ].join("\n");
         const updated = this.replaceOrAppendReadmeResourceSection(current, resourceSection);
@@ -461,6 +594,25 @@ export class GitSourceAdapter {
             return undefined;
         }
     }
+    async getResourceRef(repoDir, type, name, versionOverrides = new Map()) {
+        const version = versionOverrides.get(this.getResourceVersionOverrideKey(type, name)) ??
+            (await this.readLatestTaggedResourceVersion(repoDir, type, name)) ??
+            (await this.readResourceVersion(repoDir, type, name));
+        return this.formatResourceRef(type, name, version);
+    }
+    getResourceVersionOverrideKey(type, name) {
+        return `${type}/${name}`;
+    }
+    async readLatestTaggedResourceVersion(repoDir, type, name) {
+        const versions = (await this.repoManager.listTags(repoDir, `${type}/${name}@*`))
+            .map((tag) => tag.split("@").at(1) ?? "")
+            .filter((version) => semver.valid(version))
+            .sort(semver.rcompare);
+        return versions.at(0);
+    }
+    formatResourceRef(type, name, version) {
+        return version ? `${type}/${name}@${version}` : `${type}/${name}`;
+    }
     getSourceTitle() {
         const repo = this.sourceConfig?.repo?.replace(/\/$/, "");
         const repoName = repo?.split(/[/:]/).at(-1)?.replace(/\.git$/, "");

package/dist/cli/source-commands.js

@@ -75,6 +75,12 @@ export function registerSourceCommands(command, services, options) {
             for (const file of result.files) {
                 process.stdout.write(`- ${file.action} ${file.path}${file.reason ? ` (${file.reason})` : ""}\n`);
             }
+            if (result.committed) {
+                process.stdout.write("Committed and pushed source docs changes.\n");
+            }
+            else if (!result.dryRun) {
+                process.stdout.write("No source docs changes to commit.\n");
+            }
         });
     });
 }

package/dist/services/index.js

@@ -198,6 +198,7 @@ export class ServiceFactory {
     async publish(type, name, releaseType, projectDir) {
         const source = await this.loadSourceFromConfig();
         const sourceDir = await this.resolvePublishSourceDir(type, name, projectDir);
+        const existingInstallInfo = await this.tryResolveInstalledResource(projectDir, type, name);
         const history = await source.history(type, name);
         const latest = history[0]?.version ?? "0.0.0";
         const nextVersion = this.versions.nextVersion(latest, releaseType);
@@ -208,28 +209,31 @@ export class ServiceFactory {
         if (!(await this.exists(storePath))) {
             await source.pull(type, name, nextVersion, storePath);
         }
-        const agentsFromMeta = normalizeAgents((await this.readResourceMetaFromDir(storePath))?.agents);
         const locked = await this.getLockedResource(projectDir, type, name);
+        const resourceMeta = await this.readResourceMetaFromDir(storePath, type);
+        const configuredAgents = await this.getConfiguredAgents(projectDir);
         const nextAgents = locked?.agents?.length
             ? normalizeAgents(locked.agents)
-            : agentsFromMeta;
-        const installMode = this.resolveInstallMode(locked?.mode);
+            : existingInstallInfo?.agents.length
+                ? normalizeAgents(existingInstallInfo.agents)
+                : configuredAgents ?? normalizeAgents(resourceMeta?.agents);
+        const installMode = "copy";
         const linkPaths = getProjectResourcePaths(projectDir, type, name, nextAgents);
         for (const linkPath of linkPaths) {
-            if (await this.exists(linkPath)) {
-                await this.materializeResource(storePath, linkPath, installMode);
-            }
-        }
-        if (locked) {
-            const sourceInfo = await this.getLockSourceInfo();
-            await this.lockStore.upsertResource(projectDir, sourceInfo, {
-                type,
-                name,
-                version: nextVersion,
-                agents: nextAgents,
-                mode: installMode,
-            });
+            await this.materializeResource(storePath, linkPath, installMode);
         }
+        const sourceInfo = await this.getLockSourceInfo();
+        await this.lockStore.upsertResource(projectDir, sourceInfo, {
+            type,
+            name,
+            version: nextVersion,
+            agents: nextAgents,
+            mode: installMode,
+        });
+        await fs.rm(this.getProjectDevPath(projectDir, type, name), {
+            recursive: true,
+            force: true,
+        });
         return { type, name, version: result.version, tag: result.tag };
     }
     async create(type, name, options, projectDir) {
@@ -274,7 +278,7 @@ export class ServiceFactory {
         if (!(await this.exists(storePath))) {
             await source.pull(type, name, resolvedVersion, storePath);
         }
-        const resourceMeta = await this.readResourceMetaFromDir(storePath);
+        const resourceMeta = await this.readResourceMetaFromDir(storePath, type);
         const effectiveTargets = await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
         const linkPaths = getProjectResourcePaths(projectDir, type, name, effectiveTargets);
         for (const linkPath of linkPaths) {
@@ -428,7 +432,7 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.INSTALL_NOT_FOUND, `Installed resource link not found for ${type}/${name}. Run install first.`);
         }
         const installedPath = await fs.realpath(existingCandidates[0].path);
-        const resourceMeta = await this.readResourceMetaFromDir(installedPath);
+        const resourceMeta = await this.readResourceMetaFromDir(installedPath, type);
         const agentsFromMeta = resourceMeta?.agents?.length
             ? normalizeAgents(resourceMeta.agents)
             : undefined;
@@ -441,6 +445,18 @@ export class ServiceFactory {
             mode: "link",
         };
     }
+    async tryResolveInstalledResource(projectDir, type, name) {
+        try {
+            return await this.resolveInstalledResource(projectDir, type, name);
+        }
+        catch (error) {
+            if (error instanceof HimanError &&
+                error.code === errorCodes.INSTALL_NOT_FOUND) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
     async resolveEffectiveAgents(projectDir, explicitAgents, fallbackAgents) {
         if (explicitAgents?.length) {
             return normalizeAgents(explicitAgents);
@@ -464,15 +480,51 @@ export class ServiceFactory {
         }
         return undefined;
     }
-    async readResourceMetaFromDir(resourceDir) {
+    async readResourceMetaFromDir(resourceDir, type) {
         const yamlPath = path.join(resourceDir, "himan.yaml");
-        if (!(await this.exists(yamlPath)))
+        if (await this.exists(yamlPath)) {
+            const raw = await fs.readFile(yamlPath, "utf8");
+            const parsed = YAML.parse(raw) ??
+                null;
+            if (!parsed)
+                return null;
+            return { agents: parsed.agents ?? parsed.targets };
+        }
+        if (type !== "skill")
             return null;
-        const raw = await fs.readFile(yamlPath, "utf8");
-        const parsed = YAML.parse(raw) ?? null;
-        if (!parsed)
+        const entryPath = path.join(resourceDir, this.getDefaultEntry(type));
+        if (!(await this.exists(entryPath)))
             return null;
-        return { agents: parsed.agents ?? parsed.targets };
+        const metadata = await this.readFrontMatter(entryPath);
+        return {
+            agents: this.readStringArrayMetadata(metadata, "agents") ??
+                this.readStringArrayMetadata(metadata, "targets"),
+        };
+    }
+    async readFrontMatter(filePath) {
+        const raw = await fs.readFile(filePath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw.trimStart());
+        if (!match)
+            return null;
+        try {
+            const parsed = YAML.parse(match[1]);
+            return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+                ? parsed
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readStringArrayMetadata(metadata, key) {
+        const value = metadata?.[key];
+        if (!Array.isArray(value))
+            return undefined;
+        const items = value
+            .filter((item) => typeof item === "string")
+            .map((item) => item.trim())
+            .filter(Boolean);
+        return items.length > 0 ? items : undefined;
     }
     async exists(targetPath) {
         try {
@@ -512,6 +564,9 @@ export class ServiceFactory {
             return "commands";
         return "skills";
     }
+    getDefaultEntry(type) {
+        return type === "skill" ? "SKILL.md" : "content.md";
+    }
     validateCreateInput(type, name, options) {
         if (!["rule", "command", "skill"].includes(type)) {
             throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for create: ${type}`);

package/docs/development.md

@@ -41,9 +41,9 @@ pnpm test
    本地可执行 `pnpm run verify`（类型检查、单测、`build`），确认通过后再提 PR。PR 会自动运行同一组核心校验。
 
 2. **更新 `package.json` 中的 `version` 与 `CHANGELOG.md`**  
-   npm 不允许重复发布同一版本号。合并进 `master` 前，在 PR 里把版本改成 registry 上尚未存在的号，并把用户可见变更记录到 [CHANGELOG.md](../CHANGELOG.md)。  
+   npm 不允许重复发布同一版本号。合并进 `master` 前，在 PR 里把用户可见变更先记录到 [CHANGELOG.md](../CHANGELOG.md) 的 `[Unreleased]`，再把版本改成 registry 上尚未存在的号。
    - 手动改 `version` 字段，或  
-   - 在分支上执行其一（只改版本号，**不会**发包）：`pnpm run version:patch` / `version:minor` / `version:major`（使用 `npm version … --no-git-tag-version`，需自行 `git add` / `commit` 版本变更）。  
+   - 在分支上执行其一（改版本号并把 `[Unreleased]` 归档到新版本，**不会**发包）：`pnpm run version:patch` / `version:minor` / `version:major`（使用 `npm version … --no-git-tag-version`，随后执行 `scripts/release-changelog.mjs`；需自行 `git add` / `commit` 版本和 changelog 变更）。
    Git 标签约定：与 `version` 对应、带前缀 **`v`**（如 `1.2.0` → 标签 `v1.2.0`）。
 
 3. **合并到 `master`**  
@@ -66,7 +66,8 @@ pnpm test
 | `pnpm run release:dry` | 检查 + `npm publish --dry-run`（演练，不上传） |
 | `pnpm run release:test` | 检查 + 将版本打成 `*-test.*` 预发布号并发布到 **`@test` 标签** |
 | `pnpm run release` | 检查 + 发布 **latest**（维护者本地发包时用；**请写 `pnpm run release`**，勿用裸命令 `pnpm publish`，二者不是同一套流程） |
-| `pnpm run version:patch` / `version:minor` / `version:major` | 仅提升 `package.json` 版本号，不发包 |
+| `pnpm run changelog:release` | 把 `CHANGELOG.md` 的 `[Unreleased]` 归档到当前 `package.json` 版本 |
+| `pnpm run version:patch` / `version:minor` / `version:major` | 提升 `package.json` 版本号，并调用 `changelog:release`；不发包 |
 
 发测试标签后，安装示例：`npm i @hi-man/himan@test`。
 

package/docs/error-codes.md

@@ -110,8 +110,8 @@
 ### `E_INVALID_RESOURCE_METADATA`
 
 - **含义**：资源元数据不合法，无法发布或读取为有效资源。
-- **常见触发**：`publish` 目标缺少 `himan.yaml`，`name/type/entry` 不匹配，或 `entry` 指向的入口文件不存在。
-- **建议处理**：检查资源目录下的 `himan.yaml`，确认 `name`、`type`、`entry` 与命令参数和文件结构一致。
+- **常见触发**：`himan.yaml` 存在但 `name/type/entry` 不匹配，`entry` 指向的入口文件不存在，或缺少 `himan.yaml` 且默认入口文件也不存在。
+- **建议处理**：如果使用 `himan.yaml`，确认 `name`、`type`、`entry` 与命令参数和文件结构一致；如果暂不使用 `himan.yaml`，确认默认入口文件存在：`rule` / `command` 为 `content.md`，`skill` 为 `SKILL.md`。
 
 ### `E_PUBLISH_NO_CHANGES`
 

package/docs/mvp/README.md

@@ -30,7 +30,7 @@
 ### 2.2 `list`
 
 - `himan list [type]`，`--json` 可选
-- 扫描源仓库中各类型目录下的 `himan.yaml`，返回名称、描述、目标 agent、入口文件等。
+- 扫描源仓库中各类型目录；优先读取 `himan.yaml`，缺失时按默认入口文件推断资源，返回名称、描述、目标 agent、入口文件等。
 
 ### 2.3 `history`
 
@@ -64,7 +64,7 @@
 - 发布内容优先取项目 `.himan/dev/<type>/<name>`，否则取源仓库内对应资源目录。
 - 新版本：基于已有 tag 最新 semver 递增；无任何历史时从 `0.0.0` 起算。
 - 写回源仓库、提交、打 tag、推送，并将该版本同步到本地 store。
-- 若该资源在项目中已有安装目标，会按 lock 中的安装模式同步到新版本目录。
+- 发布成功后，用新版本 store 以 copy 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>`。
 
 ### 2.7 `create`
 
@@ -106,7 +106,7 @@
 - `.himan/dev/<type>/<name>`：资源开发态可编辑副本
 
 **源仓库内资源布局：**
-- `rules/<name>/`、`commands/<name>/`、`skills/<name>/`，各含 `himan.yaml` 与约定入口文件（如 `content.md`、`SKILL.md`）。
+- `rules/<name>/`、`commands/<name>/`、`skills/<name>/`，可含 `himan.yaml`，并包含约定入口文件（如 `content.md`、`SKILL.md`）。
 
 ### 3.3 技术依赖（概要）
 

package/docs/mvp/create-resource.md

@@ -56,7 +56,7 @@ repo/
 - `CHANGELOG.md`：记录 source 级别的新增资源、资源变更、废弃、移除和重要发布说明
 - `rules/`、`commands/`、`skills/`：资源类型根目录，由 himan 扫描
 
-可用 `himan source init-docs` 生成根目录文档模板。命令默认只创建缺失的 `README.md` / `CHANGELOG.md`；已有文件会保留，除非显式传 `--force`。`--dry-run` 只返回将执行的创建、覆盖或跳过动作，不写盘。
+可用 `himan source init-docs` 生成根目录文档模板。命令默认只创建缺失的 `README.md` / `CHANGELOG.md`；已有文件会保留，除非显式传 `--force`。`--force` 覆盖文档时会扫描当前 source 中已有的 `rule`、`command`、`skill`，写入 README 资源索引，并在 CHANGELOG 初始条目中记录已整理的资源。资源引用会优先使用 Git tag 中的最新 semver 版本，找不到 tag 时再回退到 `himan.yaml` 的 `version`。对于尚未补齐 `himan.yaml` 的资源，文档整理会按默认入口识别资源；其中 skill 会额外读取 `skills/<name>/SKILL.md` front matter 中的 `name` 和 `description`。`--dry-run` 只返回将执行的创建、覆盖或跳过动作，不写盘。有实际文件变更时，命令会提交并 push 到当前 Git source。
 
 `create` 和 `publish` 会自动维护根目录文档：
 
@@ -115,17 +115,14 @@ himan install rule code-review
 ```text
 repo/
   rules/<name>/
-    himan.yaml
     content.md
   commands/<name>/
-    himan.yaml
     content.md
   skills/<name>/
-    himan.yaml
     SKILL.md
 ```
 
-`himan.yaml` 最小字段示例：
+`himan.yaml` 是推荐但非强制的资源元数据文件。存在时，发布会校验 `name`、`type`、`entry` 与入口文件；缺失时，发布按默认入口推断最小元数据：`rule` / `command` 使用 `content.md`，`skill` 使用 `SKILL.md`。`himan.yaml` 最小字段示例：
 
 ```yaml
 name: code-review

package/docs/mvp/impl.md

@@ -30,8 +30,8 @@
 
 ### 2.2 `list [type]`
 
-- 在缓存仓库内按类型扫描子目录，读取 `himan.yaml`
-- 校验类型与必填字段（如 name、entry），不符的目录跳过
+- 在缓存仓库内按类型扫描子目录，优先读取 `himan.yaml`，缺失时按默认入口文件推断资源
+- 校验已有元数据的类型与必填字段（如 name、entry），不符的目录跳过
 - 支持人类可读与 `--json` 输出
 
 ### 2.3 `history <type> <name>`
@@ -58,7 +58,7 @@
 - 下一版本：基于历史最新 tag；无历史则从 `0.0.0` 按 patch/minor/major 递增
 - 将内容同步回缓存仓库中的规范路径，更新元数据中的版本字段，提交、打 tag、推送
 - 将新 tag 对应内容拉取到 store 新版本目录
-- 若当前项目已安装该资源，则按 lock 中的安装模式同步更新项目内对应类型目标到新版本
+- 用新版本 store 以 copy 模式重新安装项目内对应类型目标，更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录
 
 ### 2.7 `create <type> <name>`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hi-man/himan",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Prompt and agent asset management CLI",
   "keywords": [
     "ai",
@@ -59,9 +59,10 @@
     "release": "pnpm run verify && npm publish",
     "release:dry": "pnpm run verify && npm publish --dry-run",
     "release:test": "pnpm run verify && npm version prerelease --preid test --no-git-tag-version && npm publish --tag test",
-    "version:patch": "npm version patch --no-git-tag-version",
-    "version:minor": "npm version minor --no-git-tag-version",
-    "version:major": "npm version major --no-git-tag-version"
+    "changelog:release": "node scripts/release-changelog.mjs",
+    "version:patch": "npm version patch --no-git-tag-version && pnpm run changelog:release",
+    "version:minor": "npm version minor --no-git-tag-version && pnpm run changelog:release",
+    "version:major": "npm version major --no-git-tag-version && pnpm run changelog:release"
   },
   "dependencies": {
     "commander": "^14.0.3",