@hi-man/himan 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [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 扫描、发布和安装时读取。
+- `content.md` / `SKILL.md`：资源主入口，由 `himan.yaml` 的 `entry` 字段指定。
+
+可通过 `himan source init-docs` 为当前 default source 生成根目录文档模板；默认只创建缺失文件，`--force` 才覆盖已有 `README.md` / `CHANGELOG.md`，`--dry-run` 可预览结果。
+
+`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` 与入口文件；需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。若该资源已在 lock 中，发布后会同步更新 lock 版本。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.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();
@@ -58,8 +61,15 @@ export class GitSourceAdapter {
         const yamlPath = path.join(targetDir, "himan.yaml");
         metadata.version = version;
         await fs.writeFile(yamlPath, YAML.stringify(metadata), "utf8");
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Changed",
+            line: `- Published \`${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 +77,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 +94,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 +109,34 @@ 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: this.buildChangelogContent(),
+            },
+        ];
+        const results = [];
+        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");
+            }
+        }
+        return {
+            sourceDir: repoDir,
+            files: results,
+            dryRun: Boolean(options.dryRun),
+        };
+    }
     getRepoDir() {
         if (!this.sourceConfig?.repoDir) {
             throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Git source is not initialized.");
@@ -232,4 +277,200 @@ export class GitSourceAdapter {
         }
         return `# ${name}\n\nDescribe skill workflow here.\n`;
     }
+    async buildReadmeContent(repoDir) {
+        const resourceLines = await this.buildResourceIndex(repoDir);
+        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");
+    }
+    buildChangelogContent() {
+        return [
+            "# Changelog",
+            "",
+            "All notable source-level resource changes are documented in this file.",
+            "",
+            "## [Unreleased]",
+            "",
+            "### Added",
+            "",
+            "- Initial source README/CHANGELOG scaffold.",
+            "",
+        ].join("\n");
+    }
+    async buildResourceIndex(repoDir) {
+        const sections = [];
+        for (const type of RESOURCE_TYPES) {
+            const resources = (await this.scanner.scanByType(repoDir, type)).sort((a, b) => a.name.localeCompare(b.name));
+            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}`;
+                sections.push(`- \`${ref}\`${resource.description ? `: ${resource.description}` : ""}`);
+            }
+            sections.push("");
+        }
+        while (sections.at(-1) === "") {
+            sections.pop();
+        }
+        return sections;
+    }
+    async maintainSourceDocs(repoDir, changelogEntry) {
+        const readmePath = await this.updateReadmeResourceIndex(repoDir);
+        const changelogPath = await this.updateChangelog(repoDir, changelogEntry);
+        return [readmePath, changelogPath];
+    }
+    async updateReadmeResourceIndex(repoDir) {
+        const readmePath = path.join(repoDir, "README.md");
+        if (!(await this.exists(readmePath))) {
+            await fs.writeFile(readmePath, await this.buildReadmeContent(repoDir), "utf8");
+            return readmePath;
+        }
+        const current = await fs.readFile(readmePath, "utf8");
+        const resourceSection = [
+            README_RESOURCES_START,
+            ...(await this.buildResourceIndex(repoDir)),
+            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;
+        }
+    }
+    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,26 @@ 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`);
+            }
+        });
+    });
 }

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") {

package/docs/mvp/create-resource.md

@@ -39,9 +39,78 @@ 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`。`--dry-run` 只返回将执行的创建、覆盖或跳过动作，不写盘。
+
+`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/
@@ -73,7 +142,7 @@ agents:
 
 ---
 
-## 4. 流程概要
+## 5. 流程概要
 
 1. 读取本地配置，确认已初始化源
 2. 校验类型与资源名格式
@@ -86,14 +155,14 @@ agents:
 
 ---
 
-## 5. 模板
+## 6. 模板
 
 - 当前仅 **basic**：最简结构与提示性说明
 - 后续可扩展更多模板名；自定义模板目录可作为后续增强
 
 ---
 
-## 6. 错误场景（产品语义）
+## 7. 错误场景（产品语义）
 
 - 资源目录已存在
 - 模板不存在（含请求了尚未支持的模板名）
@@ -103,13 +172,13 @@ agents:
 
 ---
 
-## 7. 测试关注点
+## 8. 测试关注点
 
 - 名称与类型校验、默认 entry/agents、重复创建与 `--force`、`--dry-run` 不写盘、创建后 `list` 可见
 
 ---
 
-## 8. 与资源工作流衔接
+## 9. 与资源工作流衔接
 
 ```text
 create → edit → publish

package/package.json

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