@hi-man/himan 0.2.2 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,38 @@ 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
+
+- Added `himan source init-docs` to scaffold source-level `README.md` and `CHANGELOG.md` files.
+- Added automatic source-level README/CHANGELOG maintenance for resource create and publish flows.
+
+### Changed
+
+- Documented the recommended Git source repository-level `README.md` and `CHANGELOG.md` convention.
+
 ## [0.2.2] - 2026-05-07
 
 ### Added

package/README.md

@@ -66,6 +66,43 @@ himan publish rule my-rule --patch
 
 版本以 Git tag 为准，格式：`rule/my-rule@1.0.0`。更多设计见 [docs/mvp](./docs/mvp/README.md)。
 
+## Source 仓库结构
+
+himan Git source 是一个普通 Git 仓库，推荐先维护仓库级 `README.md` 和 `CHANGELOG.md`，用于说明整个资源集合，而不是把说明文档塞进每个 agent 的最终消费目录。
+
+```text
+your-himan-source/
+  README.md
+  CHANGELOG.md
+  rules/
+    my-rule/
+      himan.yaml
+      content.md
+  commands/
+    my-command/
+      himan.yaml
+      content.md
+  skills/
+    my-skill/
+      himan.yaml
+      SKILL.md
+```
+
+- `README.md`：source 仓库入口文档，建议记录资源目录说明、推荐安装方式、默认 agent 策略、常用资源索引和维护约定。
+- `CHANGELOG.md`：source 仓库级变更记录，建议记录新增、变更、废弃、移除的资源，以及重要版本发布说明。
+- `rules/`、`commands/`、`skills/`：按资源类型分组；每个子目录是一份 himan 资源。
+- `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`，并把当前 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 根目录文档：
+
+- `README.md`：只更新 `<!-- himan:resources:start -->` 和 `<!-- himan:resources:end -->` 之间的资源索引；如果没有 marker，会在文件末尾追加一个受控资源索引区。
+- `CHANGELOG.md`：向 `[Unreleased]` 下追加资源变更条目；`create` 记录 `Added`，`publish` 记录 `Changed` / published version。
+
+仓库根目录的 `README.md` 和 `CHANGELOG.md` 不会被安装到 agent 目录；agent 只消费被安装的具体资源目录。当前安装实现会 materialize 资源目录本身，因此对 Cursor 这类要求特定单文件格式的 agent，资源目录内应避免放入会干扰识别的额外文件。
+
 ## 常用命令
 
 ### 1) source（数据源）
@@ -76,6 +113,7 @@ himan publish rule my-rule --patch
 | `source add <name> <git_url>` | 添加命名 Git 源                                    |
 | `source use <name>`           | 切换默认源                                          |
 | `source list [--json]`        | 查看已配置源（标记当前 default）                     |
+| `source init-docs [--force] [--dry-run] [--json]` | 为当前 default source 生成仓库级 README/CHANGELOG |
 | `source init <git_url>`       | 与 `init` 等价，便于统一走 `himan source ...` 入口     |
 
 等价独立命令：
@@ -84,6 +122,7 @@ himan publish rule my-rule --patch
 - `himan-source add <name> <git_url>`
 - `himan-source use <name>`
 - `himan-source list [--json]`
+- `himan-source init-docs [--force] [--dry-run] [--json]`
 
 ### 2) resource（资源）
 
@@ -122,7 +161,7 @@ himan publish rule my-rule --patch
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
 若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。发布前会校验 `himan.yaml` 与入口文件；需要可推送的 Git 权限。若该资源已在 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

@@ -7,6 +7,9 @@ import { createHash } from "node:crypto";
 import path from "node:path";
 import YAML from "yaml";
 import { IndexCacheStore } from "../../state/index-cache-store.js";
+const RESOURCE_TYPES = ["rule", "command", "skill"];
+const README_RESOURCES_START = "<!-- himan:resources:start -->";
+const README_RESOURCES_END = "<!-- himan:resources:end -->";
 export class GitSourceAdapter {
     repoManager = new RepoManager();
     scanner = new ResourceScanner();
@@ -24,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;
@@ -48,18 +51,27 @@ 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)]);
+        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag, undefined, [
+            path.relative(repoDir, targetDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ]);
         return { version, tag };
     }
     async create(type, name, options) {
@@ -67,7 +79,8 @@ export class GitSourceAdapter {
         const resourceDir = path.join(repoDir, this.getTypeDir(type), name);
         const entry = options.entry ?? this.getDefaultEntry(type);
         const agents = options.agents?.length ? options.agents : ["cursor"];
-        if ((await this.exists(resourceDir)) && !options.force) {
+        const resourceExists = await this.exists(resourceDir);
+        if (resourceExists && !options.force) {
             throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
         }
         const files = [path.join(resourceDir, "himan.yaml"), path.join(resourceDir, entry)];
@@ -83,6 +96,12 @@ export class GitSourceAdapter {
                 agents,
             }), "utf8");
             await fs.writeFile(path.join(resourceDir, entry), this.getDefaultContent(type, name), "utf8");
+            await this.maintainSourceDocs(repoDir, {
+                section: resourceExists ? "Changed" : "Added",
+                line: resourceExists
+                    ? `- Updated \`${type}/${name}\`.`
+                    : `- Added \`${type}/${name}\`.`,
+            });
         }
         return {
             type,
@@ -92,6 +111,40 @@ export class GitSourceAdapter {
             dryRun: Boolean(options.dryRun),
         };
     }
+    async initDocs(options = {}) {
+        const repoDir = this.getRepoDir();
+        const files = [
+            {
+                path: path.join(repoDir, "README.md"),
+                content: await this.buildReadmeContent(repoDir),
+            },
+            {
+                path: path.join(repoDir, "CHANGELOG.md"),
+                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";
+            const reason = action === "skipped" ? "file already exists" : undefined;
+            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() {
         if (!this.sourceConfig?.repoDir) {
             throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Git source is not initialized.");
@@ -119,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;
@@ -165,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);
@@ -184,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))) {
@@ -210,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");
@@ -232,4 +334,295 @@ export class GitSourceAdapter {
         }
         return `# ${name}\n\nDescribe skill workflow here.\n`;
     }
+    async buildReadmeContent(repoDir, versionOverrides = new Map()) {
+        const resourceLines = await this.buildResourceIndex(repoDir, versionOverrides);
+        const repo = this.sourceConfig?.repo ?? "<git_url>";
+        return [
+            `# ${this.getSourceTitle()}`,
+            "",
+            "Himan source repository for reusable agent resources.",
+            "",
+            "## Resources",
+            "",
+            README_RESOURCES_START,
+            ...resourceLines,
+            README_RESOURCES_END,
+            "",
+            "## Usage",
+            "",
+            "```bash",
+            `himan source add team ${repo}`,
+            "himan source use team",
+            "himan list rule",
+            "himan install rule <name>",
+            "```",
+            "",
+            "## Maintenance",
+            "",
+            "- Add resources with `himan create <type> <name>`.",
+            "- Publish resource versions with `himan publish <type> <name>`.",
+            "- Record source-level changes in `CHANGELOG.md`.",
+            "- Resource versions are tracked by Git tags such as `rule/code-review@1.0.0`.",
+            "",
+        ].join("\n");
+    }
+    async buildChangelogContent(repoDir) {
+        const resourceLines = await this.buildExistingResourceChangelogLines(repoDir);
+        return [
+            "# Changelog",
+            "",
+            "All notable source-level resource changes are documented in this file.",
+            "",
+            "## [Unreleased]",
+            "",
+            "### Added",
+            "",
+            "- Initial source README/CHANGELOG scaffold.",
+            ...resourceLines,
+            "",
+        ].join("\n");
+    }
+    async buildResourceIndex(repoDir, versionOverrides = new Map()) {
+        const sections = [];
+        for (const type of RESOURCE_TYPES) {
+            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 ref = await this.getResourceRef(repoDir, resource.type, resource.name, versionOverrides);
+                sections.push(`- \`${ref}\`${resource.description ? `: ${resource.description}` : ""}`);
+            }
+            sections.push("");
+        }
+        while (sections.at(-1) === "") {
+            sections.pop();
+        }
+        return sections;
+    }
+    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, versionOverrides = new Map()) {
+        const readmePath = path.join(repoDir, "README.md");
+        if (!(await this.exists(readmePath))) {
+            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, versionOverrides)),
+            README_RESOURCES_END,
+        ].join("\n");
+        const updated = this.replaceOrAppendReadmeResourceSection(current, resourceSection);
+        if (updated !== current) {
+            await fs.writeFile(readmePath, updated, "utf8");
+        }
+        return readmePath;
+    }
+    replaceOrAppendReadmeResourceSection(content, resourceSection) {
+        const startIndex = content.indexOf(README_RESOURCES_START);
+        const endIndex = content.indexOf(README_RESOURCES_END);
+        if (startIndex >= 0 && endIndex > startIndex) {
+            const before = content.slice(0, startIndex).replace(/\s*$/, "\n");
+            const after = content
+                .slice(endIndex + README_RESOURCES_END.length)
+                .replace(/^\s*/, "\n\n");
+            return `${before}${resourceSection}${after}`.replace(/\s*$/, "\n");
+        }
+        const base = content.replace(/\s*$/, "");
+        return `${base}\n\n## Resources\n\n${resourceSection}\n`;
+    }
+    async updateChangelog(repoDir, entry) {
+        const changelogPath = path.join(repoDir, "CHANGELOG.md");
+        const current = (await this.exists(changelogPath))
+            ? await fs.readFile(changelogPath, "utf8")
+            : this.buildChangelogBaseContent();
+        const updated = this.insertChangelogEntry(current, entry);
+        if (updated !== current) {
+            await fs.writeFile(changelogPath, updated, "utf8");
+        }
+        return changelogPath;
+    }
+    buildChangelogBaseContent() {
+        return [
+            "# Changelog",
+            "",
+            "All notable source-level resource changes are documented in this file.",
+            "",
+            "## [Unreleased]",
+            "",
+        ].join("\n");
+    }
+    insertChangelogEntry(content, entry) {
+        const lines = content.replace(/\s*$/, "").split("\n");
+        let unreleasedIndex = lines.findIndex((line) => line.trim() === "## [Unreleased]");
+        if (unreleasedIndex === -1) {
+            const firstVersionIndex = lines.findIndex((line) => line.startsWith("## "));
+            const insertIndex = firstVersionIndex === -1 ? lines.length : firstVersionIndex;
+            lines.splice(insertIndex, 0, "## [Unreleased]", "");
+            unreleasedIndex = insertIndex;
+        }
+        const blockEnd = this.findNextHeadingIndex(lines, unreleasedIndex + 1, "## ");
+        const unreleasedLines = lines.slice(unreleasedIndex, blockEnd);
+        if (unreleasedLines.includes(entry.line)) {
+            return `${lines.join("\n")}\n`;
+        }
+        const sectionHeading = `### ${entry.section}`;
+        const sectionIndex = lines.findIndex((line, index) => index > unreleasedIndex && index < blockEnd && line.trim() === sectionHeading);
+        if (sectionIndex >= 0) {
+            const insertIndex = lines[sectionIndex + 1] === "" ? sectionIndex + 2 : sectionIndex + 1;
+            lines.splice(insertIndex, 0, entry.line);
+            return `${lines.join("\n")}\n`;
+        }
+        const insertIndex = this.findChangelogSectionInsertIndex(lines, unreleasedIndex, blockEnd, entry.section);
+        lines.splice(insertIndex, 0, `### ${entry.section}`, "", entry.line, "");
+        return `${lines.join("\n").replace(/\s*$/, "")}\n`;
+    }
+    findNextHeadingIndex(lines, startIndex, headingPrefix) {
+        const found = lines.findIndex((line, index) => index >= startIndex && line.startsWith(headingPrefix));
+        return found === -1 ? lines.length : found;
+    }
+    findChangelogSectionInsertIndex(lines, unreleasedIndex, blockEnd, section) {
+        const sectionOrder = ["Added", "Changed"];
+        const sectionRank = sectionOrder.indexOf(section);
+        for (let index = unreleasedIndex + 1; index < blockEnd; index += 1) {
+            const line = lines[index].trim();
+            if (!line.startsWith("### "))
+                continue;
+            const foundSection = line.slice(4);
+            const foundRank = sectionOrder.indexOf(foundSection);
+            if (foundRank > sectionRank) {
+                return index;
+            }
+        }
+        return blockEnd;
+    }
+    async readResourceVersion(repoDir, type, name) {
+        const yamlPath = path.join(repoDir, this.getTypeDir(type), name, "himan.yaml");
+        try {
+            const raw = await fs.readFile(yamlPath, "utf8");
+            const parsed = YAML.parse(raw);
+            return typeof parsed?.version === "string" ? parsed.version : undefined;
+        }
+        catch (error) {
+            if (!this.isNotFoundError(error)) {
+                throw error;
+            }
+            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$/, "");
+        return repoName ? `${repoName} Himan Source` : "Himan Source";
+    }
+    getTypeLabel(type) {
+        if (type === "rule")
+            return "Rules";
+        if (type === "command")
+            return "Commands";
+        return "Skills";
+    }
 }

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

@@ -18,4 +18,7 @@ export class RegistrySourceAdapter {
     async create(_type, _name, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async initDocs(_options) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
 }

package/dist/cli/builders.js

@@ -60,7 +60,7 @@ function appendCommandGroupsHelp(program) {
     program.addHelpText("after", `
 Command groups:
   source   Data source management (git now, registry reserved)
-           init, source init, source add, source use, source list
+           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

package/dist/cli/source-commands.js

@@ -55,4 +55,32 @@ export function registerSourceCommands(command, services, options) {
             }
         });
     });
+    command
+        .command("init-docs")
+        .option("--force", "overwrite existing README.md and CHANGELOG.md")
+        .option("--dry-run", "show files without writing")
+        .option("--json", "output json format")
+        .description("Create source-level README.md and CHANGELOG.md")
+        .action(async (options) => {
+        await runAction(async () => {
+            const result = await services.initSourceDocs({
+                force: options.force,
+                dryRun: options.dryRun,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Source docs ${result.dryRun ? "dry-run" : "initialized"}: ${result.sourceDir}\n`);
+            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/domain/source-docs.js

@@ -0,0 +1 @@
+export {};

package/dist/services/index.js

@@ -101,6 +101,10 @@ export class ServiceFactory {
             isDefault: name === config.sources?.default,
         }));
     }
+    async initSourceDocs(options) {
+        const source = await this.loadSourceFromConfig();
+        return source.initDocs(options);
+    }
     async setAgents(agents, scope, projectDir) {
         const normalized = normalizeAgents(agents);
         if (scope === "project") {
@@ -194,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);
@@ -204,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) {
@@ -270,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) {
@@ -424,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;
@@ -437,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);
@@ -460,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 {
@@ -508,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

@@ -39,24 +39,90 @@ himan create <type> <name> [options]
 
 ---
 
-## 3. 资源目录与元数据
+## 3. Source 仓库结构
 
-创建后的仓库结构示例：
+Git source 仓库推荐先维护仓库级 `README.md` 和 `CHANGELOG.md`，用于说明整个资源集合的使用方式与变更历史。它们位于仓库根目录，不属于任何单个资源，也不会通过 `himan install` 安装到 agent 目录。
+
+```text
+repo/
+  README.md
+  CHANGELOG.md
+  rules/
+  commands/
+  skills/
+```
+
+- `README.md`：说明 source 的用途、资源索引、安装示例、默认 agent 策略和维护约定
+- `CHANGELOG.md`：记录 source 级别的新增资源、资源变更、废弃、移除和重要发布说明
+- `rules/`、`commands/`、`skills/`：资源类型根目录，由 himan 扫描
+
+可用 `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` 会自动维护根目录文档：
+
+- `README.md`：只维护 `<!-- himan:resources:start -->` / `<!-- himan:resources:end -->` 标记内的资源索引；如果旧 README 没有标记，则在文件末尾追加受控资源索引区
+- `CHANGELOG.md`：向 `[Unreleased]` 写入资源变更；新增资源写入 `Added`，发布版本写入 `Changed`
+
+推荐的 `README.md` 基本结构：
+
+```md
+# Team Himan Source
+
+## Resources
+
+<!-- himan:resources:start -->
+
+- rule/code-review: Code review behavior for backend changes.
+- command/create-mr: MR creation workflow.
+- skill/api-debugging: API debugging workflow.
+
+<!-- himan:resources:end -->
+
+## Usage
+
+\`\`\`bash
+himan source add team <git_url>
+himan source use team
+himan install rule code-review
+\`\`\`
+
+## Maintenance
+
+- Publish resource versions with himan publish.
+- Record source-level changes in CHANGELOG.md.
+```
+
+推荐的 `CHANGELOG.md` 基本结构：
+
+```md
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Added rule/code-review.
+
+### Changed
+
+- Updated skill/api-debugging usage guidance.
+```
+
+## 4. 资源目录与元数据
+
+`create` 生成资源目录，结构示例：
 
 ```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
@@ -73,7 +139,7 @@ agents:
 
 ---
 
-## 4. 流程概要
+## 5. 流程概要
 
 1. 读取本地配置，确认已初始化源
 2. 校验类型与资源名格式
@@ -86,14 +152,14 @@ agents:
 
 ---
 
-## 5. 模板
+## 6. 模板
 
 - 当前仅 **basic**：最简结构与提示性说明
 - 后续可扩展更多模板名；自定义模板目录可作为后续增强
 
 ---
 
-## 6. 错误场景（产品语义）
+## 7. 错误场景（产品语义）
 
 - 资源目录已存在
 - 模板不存在（含请求了尚未支持的模板名）
@@ -103,13 +169,13 @@ agents:
 
 ---
 
-## 7. 测试关注点
+## 8. 测试关注点
 
 - 名称与类型校验、默认 entry/agents、重复创建与 `--force`、`--dry-run` 不写盘、创建后 `list` 可见
 
 ---
 
-## 8. 与资源工作流衔接
+## 9. 与资源工作流衔接
 
 ```text
 create → edit → publish

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.2.2",
+  "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",