@hi-man/himan 0.2.0 → 0.2.2

package/.nvmrc

@@ -0,0 +1 @@
+22.22.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on Keep a Changelog, and this project follows semver for the npm package version.
+
+## [Unreleased]
+
+## [0.2.2] - 2026-05-07
+
+### Added
+
+- Added a PR verify workflow that runs typecheck, tests, and build before merging to `master`.
+
+## [0.2.1] - 2026-05-07
+
+### Added
+
+- Added this changelog to make release notes and user-visible changes explicit.
+- Added npm package metadata for Node.js engine compatibility and package discovery.
+- Added public contributing, security, and code of conduct documents.
+
+### Changed
+
+- Clean `dist` before every build so npm packages cannot include stale generated files.
+- Aligned MVP, v1.0, and roadmap docs with current resource type and multi-agent behavior.
+- Added publish preflight checks for resource metadata and entry files, with stable publish error codes.
+- Restored lock-file installs from the source recorded in `himan.lock` instead of the current default source.
+- Updated repository links to `https://github.com/himan-group/himan`.
+- Updated Git source refresh to fast-forward clean cached working trees after fetch while preserving dirty local edits.
+- Updated list cache invalidation to track `himan.yaml` metadata content instead of parent directory mtimes.
+- Moved developer, testing, release, and CI maintenance documentation from README to `docs/development.md`.
+- Improved README installation guidance for npm, one-off execution, local development, and CLI entry points.
+- Included README-linked user documentation in the npm package and changed GitHub workflow links to repository URLs.
+
+## [0.2.0] - 2026-05-06
+
+### Added
+
+- Added command groups for `source`, `resource`, `project`, and `agent`, while keeping backward-compatible top-level lifecycle commands.
+- Added dedicated binaries: `himan-source`, `himan-resource`, and `himan-project`.
+- Added default agent configuration commands for project and global scopes.
+- Added multi-agent installation targets for `cursor`, `claude-code`, `codex`, and `openclaw`.
+- Added `command` and `skill` lifecycle support across create, list, history, install, dev, publish, and uninstall flows.
+- Added project `himan.lock` support for reproducible installs.
+- Added copy install mode in addition to symlink mode.
+- Added local index cache support for resource listing.
+- Added repository guidance files for Codex workflows.
+
+### Changed
+
+- Split CLI registration into source, resource, project, agent, and shared command modules.
+- Expanded README and planning docs to reflect multi-type resources, lock behavior, multi-agent targets, and source management.
+
+## [0.1.0] - 2026-04-08
+
+### Added
+
+- Initial Git-backed CLI for managing prompt and agent assets.
+- Added source initialization, resource listing, history, install, dev, publish, create, and uninstall workflows.
+- Added resource metadata scanning from `himan.yaml`.
+- Added semver tag-based resource versioning.
+- Added local store, repo cache, config, and index state foundations.
+- Added npm publishing and version tag GitHub Actions workflows.
+- Added Vitest coverage for adapters, state, utilities, and CLI integration paths.

package/README.md

@@ -2,29 +2,44 @@
 
 himan（含义为"Hey, man"），AI Coding 时代的 Prompt / Agent 资产管理系统（CLI + Git source）
 
+## 环境要求
+
+- Node.js 22.x；本仓库开发环境由 [.nvmrc](./.nvmrc) 固定为 `22.22.1`。
+- Git；Git source 的初始化、版本查询、安装和发布都依赖本机 Git。
+
 ## 安装与运行
 
+### 使用 npm 包
+
+全局安装后可直接使用 `himan`：
+
 ```bash
-pnpm install
-pnpm run build
+npm install -g @hi-man/himan
+himan --help
 ```
 
-之后任选其一执行命令：
+也可以一次性运行主入口：
+
+```bash
+npx @hi-man/himan --help
+pnpm dlx @hi-man/himan --help
+```
 
-- 已全局安装本包：`himan <子命令>`
-- 本地开发：`pnpm run dev -- <子命令>`
-- 或直接：`node dist/bin/himan.js <子命令>`
+### 命令入口
 
-也支持两个独立入口：
+包内提供四个 CLI 入口：
 
+- `himan <子命令>`（主入口）
 - `himan-source <子命令>`（source 相关）
 - `himan-resource <子命令>`（resource/project 相关）
 - `himan-project <子命令>`（project 相关）
 
-下文用 `himan` 代指上述入口。
+下文默认使用 `himan` 主入口；三个专用入口在对应章节单独列出。
 
 ## 一分钟上手
 
+以下示例假设你已有一个可访问的 himan Git source 仓库，仓库中存在 `my-rule` 的资源版本 tag，并且你拥有发布所需的 Git push 权限。
+
 ```bash
 himan init https://github.com/your-org/your-himan-registry.git
 himan list rule
@@ -45,7 +60,7 @@ himan publish rule my-rule --patch
   - `rule` -> `.himan/dev/rule/<name>`
   - `command` -> `.himan/dev/command/<name>`
   - `skill` -> `.himan/dev/skill/<name>`
-- lock 文件：`install <type> <name[@version]>` 会写入 `himan.lock`；`himan install`（无参数）会按 lock 批量恢复安装。
+- lock 文件：`install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。
 - 安装模式：默认 `--mode link` 使用软链；也可用 `--mode copy` 将资源复制到目标 agent 目录，lock 会记录并复现该模式。
 - 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
 
@@ -82,7 +97,7 @@ himan publish rule my-rule --patch
 
 | 命令                              | 说明                                                      |
 | --------------------------------- | --------------------------------------------------------- |
-| `install [type] [name[@version]] [--agent a,b] [--mode link\|copy]` | 有参数时安装指定资源；**无参数**时按 `himan.lock` 批量安装；可覆盖安装目标 agent 或安装模式 |
+| `install [type] [name[@version]] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；可覆盖安装目标 agent 或安装模式 |
 | `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
 | `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
 | `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
@@ -107,15 +122,16 @@ himan publish rule my-rule --patch
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
 若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。需要可推送的 Git 权限。若该资源已在 lock 中，发布后会同步更新 lock 版本。
+`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。发布前会校验 `himan.yaml` 与入口文件；需要可推送的 Git 权限。若该资源已在 lock 中，发布后会同步更新 lock 版本。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 
-多源说明：当前是「**多来源可配置，单来源生效**」模型。业务命令（`list/install/history/dev/publish`）只作用于当前 default source；切换后再执行命令。
+多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。
 
 ## 当前范围
 
 - 源：**仅 Git**（`init`）。Registry 适配器已预留，尚未实现。
+- 包定位：当前仅承诺 CLI 使用，不提供稳定的 Node.js 程序化 API。
 
 ## FAQ
 
@@ -133,56 +149,6 @@ himan source list
 **Q: `list` 和 `source list` 有什么区别？**  
 A: `source list` 查看「我配置了哪些来源」；`list` 查看「当前 default source 里有哪些资源」。
 
-## 开发与测试
-
-```bash
-pnpm test
-```
-
-## 发布 npm 包（维护者）
-
-### 流程概览
-
-1. **在分支上完成开发与合并前检查**  
-   本地可执行 `pnpm run verify`（类型检查、单测、`build`），确认通过后再提 PR。
-
-2. **更新 `package.json` 中的 `version`**  
-   npm 不允许重复发布同一版本号。合并进 `master` 前，在 PR 里把版本改成 registry 上尚未存在的号。  
-   - 手动改 `version` 字段，或  
-   - 在分支上执行其一（只改版本号，**不会**发包）：`pnpm run version:patch` / `version:minor` / `version:major`（使用 `npm version … --no-git-tag-version`，需自行 `git add` / `commit` 版本变更）。  
-   Git 标签约定：与 `version` 对应、带前缀 **`v`**（如 `1.2.0` → 标签 `v1.2.0`）。
-
-3. **合并到 `master`**  
-   推送合并后的 `master` 会触发 GitHub Actions 工作流 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml)：安装依赖后执行 **`pnpm run release`**（即再次 `verify` + `npm publish`）。  
-   npm 发布认证使用 **Trusted Publishing**，不使用长期 `NPM_TOKEN`。需在 npmjs.com 的 `@hi-man/himan` 包设置中添加 Trusted Publisher：
-   - Provider: GitHub Actions
-   - Organization or user: `lidetao`
-   - Repository: `himan`
-   - Workflow filename: `publish-npm.yml`
-   workflow 已授予 OIDC 所需的 `id-token: write` 权限，并在发布前升级 npm CLI 到支持 Trusted Publishing 的版本。
-
-4. **手动从 CI 再发一次（可选）**  
-   在 GitHub **Actions → Publish to npm → Run workflow** 可手动运行同一流程（例如在修复密钥后重试）。
-
-### 本地命令（与 CI 中的 `pnpm run release` 一致）
-
-| 命令 | 作用 |
-|------|------|
-| `pnpm run verify` | 仅检查（类型 / 测试 / 构建） |
-| `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` 版本号，不发包 |
-
-发测试标签后，安装示例：`npm i @hi-man/himan@test`。
-
-### CI：合并前校验与合并后打 Git 标签
-
-| 工作流 | 文件 | 说明 |
-|--------|------|------|
-| **PR version tag check** | [`.github/workflows/pr-master-version-tag.yml`](.github/workflows/pr-master-version-tag.yml) | 目标分支为 `master` 的 PR：读取 **PR 头提交**上的 `package.json` 的 `version`，若远端已存在同名标签 **`v{version}`**，则 **检查失败**（用于在合并前拦截重复版本）。 |
-| **Tag version on master** | [`.github/workflows/push-master-version-tag.yml`](.github/workflows/push-master-version-tag.yml) | 向 `master` **推送**后（含合并 PR）：在 **当前推送提交**上创建并推送注释标签 **`v{version}`**。若标签已存在、创建或 `git push` 失败，仅输出 **告警**（`::warning::`），**工作流仍成功**，不撤销已发生的 merge；请按日志提示在本机补打标签并 `git push origin v{x.y.z}`。 |
-
-**启用「合并前拦截」**：在 GitHub **Settings → Branches** 中为 `master` 配置分支保护，勾选 **Require status checks to pass before merging**，并勾选必选检查 **`PR version tag check / version-tag-available`**（名称以仓库里 Actions 界面为准）。
+## 开发与维护
 
-说明：来自 fork 的 PR 同样会跑上述 PR 检查；打标签工作流需要 **Actions 对仓库有写权限**（工作流内已设 `contents: write`）。若组织策略禁止 `GITHUB_TOKEN` 写标签，推送标签会失败，需按告警手动推送。
+源码开发、测试和 npm 发包流程见 [docs/development.md](./docs/development.md)。

package/dist/adapters/git/repo-manager.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { simpleGit } from "simple-git";
+import { HimanError, errorCodes } from "../../utils/errors.js";
 export class RepoManager {
     async cloneOrFetch(repo, targetDir) {
         const gitDir = path.join(targetDir, ".git");
@@ -12,6 +13,7 @@ export class RepoManager {
         }
         const git = simpleGit(targetDir);
         await git.fetch(["--tags", "--prune"]);
+        await this.fastForwardCleanWorkingTree(git);
     }
     async listTags(repoDir, pattern) {
         const git = simpleGit(repoDir);
@@ -44,14 +46,21 @@ export class RepoManager {
             await fs.writeFile(destination, content, "utf8");
         }
     }
-    async commitTagAndPush(repoDir, message, tag, branch) {
+    async commitTagAndPush(repoDir, message, tag, branch, paths = ["."]) {
         const git = simpleGit(repoDir);
-        await git.add(["."]);
-        const status = await git.status();
-        if (status.isClean()) {
-            throw new Error("No changes to publish.");
+        const pathspecs = paths.length > 0 ? paths : ["."];
+        await git.add(pathspecs);
+        const stagedFiles = await git.raw([
+            "diff",
+            "--cached",
+            "--name-only",
+            "--",
+            ...pathspecs,
+        ]);
+        if (!stagedFiles.trim()) {
+            throw new HimanError(errorCodes.PUBLISH_NO_CHANGES, "No changes to publish.");
         }
-        await git.commit(message);
+        await git.commit(message, pathspecs);
         await git.addTag(tag);
         const currentBranch = (await git.raw(["rev-parse", "--abbrev-ref", "HEAD"])).trim();
         const targetBranch = branch ?? currentBranch;
@@ -67,4 +76,30 @@ export class RepoManager {
             return false;
         }
     }
+    async fastForwardCleanWorkingTree(git) {
+        const status = await git.status();
+        if (!status.isClean()) {
+            return;
+        }
+        const upstream = await this.getCurrentUpstream(git);
+        if (!upstream) {
+            return;
+        }
+        await git.raw(["merge", "--ff-only", upstream]);
+    }
+    async getCurrentUpstream(git) {
+        try {
+            const upstream = await git.raw([
+                "rev-parse",
+                "--abbrev-ref",
+                "--symbolic-full-name",
+                "@{u}",
+            ]);
+            const trimmed = upstream.trim();
+            return trimmed.length > 0 ? trimmed : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
 }

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

@@ -3,6 +3,7 @@ import { ResourceScanner } from "../resource/resource-scanner.js";
 import semver from "semver";
 import { HimanError, errorCodes } from "../../utils/errors.js";
 import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import YAML from "yaml";
 import { IndexCacheStore } from "../../state/index-cache-store.js";
@@ -23,13 +24,13 @@ export class GitSourceAdapter {
         const repoId = this.sourceConfig?.repoId ?? "default";
         const typeDir = this.getTypeDir(type);
         const baseDir = path.join(repoDir, typeDir);
-        const baseDirMtimeMs = await this.getMtimeMs(baseDir);
+        const metadataHash = await this.getResourceMetadataHash(baseDir);
         const cached = await this.indexStore.get(repoId, type);
-        if (cached && cached.baseDirMtimeMs === baseDirMtimeMs) {
+        if (cached && cached.metadataHash === metadataHash) {
             return cached.resources;
         }
         const scanned = await this.scanner.scanByType(repoDir, type);
-        await this.indexStore.upsert(repoId, type, baseDirMtimeMs, scanned);
+        await this.indexStore.upsert(repoId, type, metadataHash, scanned);
         return scanned;
     }
     async history(type, name) {
@@ -47,6 +48,7 @@ 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 sameDir = await this.isSameDirectory(sourceDir, targetDir);
         if (!sameDir) {
             await fs.rm(targetDir, { recursive: true, force: true });
@@ -54,14 +56,10 @@ export class GitSourceAdapter {
             await fs.cp(sourceDir, targetDir, { recursive: true });
         }
         const yamlPath = path.join(targetDir, "himan.yaml");
-        if (await this.exists(yamlPath)) {
-            const raw = await fs.readFile(yamlPath, "utf8");
-            const parsed = YAML.parse(raw);
-            parsed.version = version;
-            await fs.writeFile(yamlPath, YAML.stringify(parsed), "utf8");
-        }
+        metadata.version = version;
+        await fs.writeFile(yamlPath, YAML.stringify(metadata), "utf8");
         const tag = `${type}/${name}@${version}`;
-        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag);
+        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag, undefined, [path.relative(repoDir, targetDir)]);
         return { version, tag };
     }
     async create(type, name, options) {
@@ -118,14 +116,66 @@ export class GitSourceAdapter {
             return false;
         }
     }
-    async getMtimeMs(targetPath) {
+    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 });
+        }
+        const raw = await fs.readFile(yamlPath, "utf8");
+        let parsed;
         try {
-            const stat = await fs.stat(targetPath);
-            return stat.mtimeMs;
+            parsed = YAML.parse(raw);
         }
-        catch {
-            return 0;
+        catch (error) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml is not valid YAML.", { yamlPath, reason: error instanceof Error ? error.message : String(error) });
+        }
+        if (!this.isRecord(parsed)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml must be an object.", { yamlPath });
+        }
+        if (parsed.name !== name) {
+            throw this.invalidResourceMetadata(type, name, `himan.yaml name must be "${name}".`, { yamlPath, actual: parsed.name });
+        }
+        if (parsed.type !== type) {
+            throw this.invalidResourceMetadata(type, name, `himan.yaml type must be "${type}".`, { yamlPath, actual: parsed.type });
+        }
+        if (typeof parsed.entry !== "string" || parsed.entry.trim().length === 0) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml entry is required.", { yamlPath });
+        }
+        const entry = parsed.entry.trim();
+        const entryPath = path.resolve(resourceDir, entry);
+        const resourceRoot = path.resolve(resourceDir);
+        const relativeEntryPath = path.relative(resourceRoot, entryPath);
+        if (path.isAbsolute(entry) ||
+            relativeEntryPath === "" ||
+            relativeEntryPath.startsWith("..") ||
+            path.isAbsolute(relativeEntryPath)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml entry must point to a file inside the resource directory.", { yamlPath, entry });
+        }
+        let entryStat;
+        try {
+            entryStat = await fs.stat(entryPath);
+        }
+        catch (error) {
+            if (!this.isNotFoundError(error)) {
+                throw error;
+            }
+            throw this.invalidResourceMetadata(type, name, `Resource entry file not found: ${entry}`, { yamlPath, entry, entryPath });
         }
+        if (!entryStat.isFile()) {
+            throw this.invalidResourceMetadata(type, name, `Resource entry is not a file: ${entry}`, { yamlPath, entry, entryPath });
+        }
+        return {
+            ...parsed,
+            name,
+            type,
+            entry,
+        };
+    }
+    invalidResourceMetadata(type, name, message, details) {
+        return new HimanError(errorCodes.INVALID_RESOURCE_METADATA, `Invalid metadata for ${type}/${name}: ${message}`, details);
+    }
+    isRecord(value) {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
     }
     getTypeDir(type) {
         if (type === "rule")
@@ -134,6 +184,42 @@ export class GitSourceAdapter {
             return "commands";
         return "skills";
     }
+    async getResourceMetadataHash(baseDir) {
+        const hash = createHash("sha256");
+        hash.update("himan-resource-index-v1");
+        if (!(await this.exists(baseDir))) {
+            hash.update("\0missing");
+            return hash.digest("hex");
+        }
+        const entries = await fs.readdir(baseDir, { withFileTypes: true });
+        const resourceDirNames = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        for (const resourceDirName of resourceDirNames) {
+            hash.update("\0dir:");
+            hash.update(resourceDirName);
+            const yamlPath = path.join(baseDir, resourceDirName, "himan.yaml");
+            try {
+                const raw = await fs.readFile(yamlPath);
+                hash.update("\0yaml:");
+                hash.update(raw);
+            }
+            catch (error) {
+                if (!this.isNotFoundError(error)) {
+                    throw error;
+                }
+                hash.update("\0yaml-missing");
+            }
+        }
+        return hash.digest("hex");
+    }
+    isNotFoundError(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT");
+    }
     getDefaultEntry(type) {
         return type === "skill" ? "SKILL.md" : "content.md";
     }

package/dist/services/index.js

@@ -2,7 +2,7 @@ import { GitSourceAdapter } from "../adapters/source/git-source-adapter.js";
 import { RegistrySourceAdapter } from "../adapters/source/registry-source-adapter.js";
 import { StateStore } from "../state/state-store.js";
 import { ProjectConfigStore } from "../state/project-config-store.js";
-import { ProjectLockStore } from "../state/project-lock-store.js";
+import { ProjectLockStore, } from "../state/project-lock-store.js";
 import { PathResolver } from "../utils/path-resolver.js";
 import { toRepoId } from "../utils/repo-id.js";
 import { HimanError, errorCodes } from "../utils/errors.js";
@@ -158,31 +158,8 @@ export class ServiceFactory {
         return source.history(type, name);
     }
     async install(type, name, version, projectDir, agents, mode = "link") {
-        const source = await this.loadSourceFromConfig();
-        const sourceInfo = await this.getLockSourceInfo();
-        const history = await source.history(type, name);
-        if (history.length === 0) {
-            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
-        }
-        const resolvedVersion = this.resolveVersion(history, version);
-        const storePath = this.getStorePath(type, name, resolvedVersion);
-        if (!(await this.exists(storePath))) {
-            await source.pull(type, name, resolvedVersion, storePath);
-        }
-        const resourceMeta = await this.readResourceMetaFromDir(storePath);
-        const effectiveTargets = await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
-        const linkPaths = getProjectResourcePaths(projectDir, type, name, effectiveTargets);
-        for (const linkPath of linkPaths) {
-            await this.materializeResource(storePath, linkPath, mode);
-        }
-        await this.lockStore.upsertResource(projectDir, sourceInfo, {
-            type,
-            name,
-            version: resolvedVersion,
-            agents: effectiveTargets,
-            mode,
-        });
-        return { type, name, version: resolvedVersion, linkPath: linkPaths[0], mode };
+        const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
+        return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
     }
     async dev(type, name, projectDir) {
         const installInfo = await this.resolveInstalledResource(projectDir, type, name);
@@ -275,21 +252,69 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.LOCK_NOT_FOUND, `Lock file has no resources: ${this.lockStore.getLockPath(projectDir)}`);
         }
         const results = [];
+        const lockSourceInfo = this.normalizeLockSourceInfo(lock.source);
+        const lockedSource = await this.loadSourceFromLock(lockSourceInfo);
         for (const item of lock.resources) {
-            const result = await this.install(item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode));
+            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode));
             results.push(result);
         }
         return results;
     }
+    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode) {
+        const history = await source.history(type, name);
+        if (history.length === 0) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
+        }
+        const resolvedVersion = this.resolveVersion(history, version);
+        const storePath = this.getStorePath(type, name, resolvedVersion);
+        if (!(await this.exists(storePath))) {
+            await source.pull(type, name, resolvedVersion, storePath);
+        }
+        const resourceMeta = await this.readResourceMetaFromDir(storePath);
+        const effectiveTargets = await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
+        const linkPaths = getProjectResourcePaths(projectDir, type, name, effectiveTargets);
+        for (const linkPath of linkPaths) {
+            await this.materializeResource(storePath, linkPath, mode);
+        }
+        await this.lockStore.upsertResource(projectDir, sourceInfo, {
+            type,
+            name,
+            version: resolvedVersion,
+            agents: effectiveTargets,
+            mode,
+        });
+        return { type, name, version: resolvedVersion, linkPath: linkPaths[0], mode };
+    }
     async loadSourceFromConfig() {
+        return (await this.loadSourceWithInfoFromConfig()).source;
+    }
+    async loadSourceWithInfoFromConfig() {
+        const { name, source: stateSource } = await this.getCurrentSourceState();
+        const sourceInfo = this.toLockSourceInfo(stateSource, name);
+        const source = await this.loadSourceFromInfo(sourceInfo);
+        return {
+            source,
+            sourceInfo,
+        };
+    }
+    async loadSourceFromLock(sourceInfo) {
+        return this.loadSourceFromInfo(sourceInfo);
+    }
+    async loadSourceFromInfo(sourceInfo) {
+        const normalizedSourceInfo = this.normalizeLockSourceInfo(sourceInfo);
+        const sourceConfig = this.buildSourceConfig(normalizedSourceInfo.type, normalizedSourceInfo.repo, normalizedSourceInfo.repoId);
+        const source = this.createSource(normalizedSourceInfo.type);
+        await source.init(sourceConfig);
+        return source;
+    }
+    async getCurrentSourceState() {
         const config = await this.stateStore.loadConfig();
         if (!config?.source) {
             throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Source config not found. Please run `himan init <git_repo>` first.");
         }
-        const sourceConfig = this.buildSourceConfig(config.source.type, config.source.repo, config.source.repoId);
-        const source = this.createSource(config.source.type);
-        await source.init(sourceConfig);
-        return source;
+        const currentName = config.sources?.default ?? "default";
+        const currentSource = config.sources?.items[currentName] ?? config.source;
+        return { name: currentName, source: currentSource };
     }
     createSource(type) {
         return type === "registry"
@@ -297,14 +322,24 @@ export class ServiceFactory {
             : new GitSourceAdapter();
     }
     async getLockSourceInfo() {
-        const config = await this.stateStore.loadConfig();
-        if (!config?.source) {
-            throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Source config not found. Please run `himan init <git_repo>` first.");
+        const { name, source } = await this.getCurrentSourceState();
+        return this.toLockSourceInfo(source, name);
+    }
+    toLockSourceInfo(source, name) {
+        return this.normalizeLockSourceInfo({
+            name,
+            type: source.type,
+            repo: source.repo,
+            repoId: source.repoId,
+        });
+    }
+    normalizeLockSourceInfo(sourceInfo) {
+        if (sourceInfo.type !== "git" || !sourceInfo.repo) {
+            return sourceInfo;
         }
         return {
-            type: config.source.type,
-            repo: config.source.repo,
-            repoId: config.source.repoId,
+            ...sourceInfo,
+            repoId: sourceInfo.repoId ?? toRepoId(sourceInfo.repo),
         };
     }
     async getLockedResource(projectDir, type, name) {

package/dist/state/index-cache-store.js

@@ -12,12 +12,13 @@ export class IndexCacheStore {
             return null;
         return data.entries.find((item) => item.repoId === repoId && item.type === type) ?? null;
     }
-    async upsert(repoId, type, baseDirMtimeMs, resources) {
+    async upsert(repoId, type, metadataHash, resources) {
         const now = new Date().toISOString();
         const file = (await this.load()) ?? { version: 1, entries: [] };
         const found = file.entries.find((item) => item.repoId === repoId && item.type === type);
         if (found) {
-            found.baseDirMtimeMs = baseDirMtimeMs;
+            found.metadataHash = metadataHash;
+            delete found.baseDirMtimeMs;
             found.resources = resources;
             found.updatedAt = now;
         }
@@ -25,7 +26,7 @@ export class IndexCacheStore {
             file.entries.push({
                 repoId,
                 type,
-                baseDirMtimeMs,
+                metadataHash,
                 resources,
                 updatedAt: now,
             });

package/dist/utils/errors.js

@@ -21,5 +21,7 @@ export const errorCodes = {
     RESOURCE_EXISTS: "E_RESOURCE_EXISTS",
     TEMPLATE_NOT_FOUND: "E_TEMPLATE_NOT_FOUND",
     INVALID_RESOURCE_NAME: "E_INVALID_RESOURCE_NAME",
+    INVALID_RESOURCE_METADATA: "E_INVALID_RESOURCE_METADATA",
+    PUBLISH_NO_CHANGES: "E_PUBLISH_NO_CHANGES",
     UNSUPPORTED_RESOURCE_TYPE: "E_UNSUPPORTED_RESOURCE_TYPE",
 };

package/docs/development.md

@@ -0,0 +1,83 @@
+# Development
+
+本文面向 `himan` 仓库开发者和 npm 包维护者。用户安装和使用 CLI 请优先阅读 [README.md](../README.md)。
+
+## 环境要求
+
+- Node.js 22.x；本仓库开发环境由 [.nvmrc](../.nvmrc) 固定为 `22.22.1`。
+- pnpm 10.32.1；包管理器版本由 [package.json](../package.json) 固定。
+- Git；测试和发布流程会使用本地 Git。
+
+## 本地源码开发
+
+```bash
+pnpm install
+pnpm run build
+pnpm run dev -- --help
+node dist/bin/himan.js --help
+```
+
+## 开发与测试
+
+```bash
+pnpm test
+```
+
+常用脚本：
+
+| 命令 | 作用 |
+|------|------|
+| `pnpm run clean` | 删除 `dist/` |
+| `pnpm run build` | 清理并编译 TypeScript 到 `dist/` |
+| `pnpm run typecheck` | 运行 TypeScript 类型检查，不输出文件 |
+| `pnpm test` | 运行 Vitest 一次 |
+| `pnpm run verify` | 依次运行 typecheck、test、build |
+
+## 发布 npm 包（维护者）
+
+### 流程概览
+
+1. **在分支上完成开发与合并前检查**  
+   本地可执行 `pnpm run verify`（类型检查、单测、`build`），确认通过后再提 PR。PR 会自动运行同一组核心校验。
+
+2. **更新 `package.json` 中的 `version` 与 `CHANGELOG.md`**  
+   npm 不允许重复发布同一版本号。合并进 `master` 前，在 PR 里把版本改成 registry 上尚未存在的号，并把用户可见变更记录到 [CHANGELOG.md](../CHANGELOG.md)。  
+   - 手动改 `version` 字段，或  
+   - 在分支上执行其一（只改版本号，**不会**发包）：`pnpm run version:patch` / `version:minor` / `version:major`（使用 `npm version … --no-git-tag-version`，需自行 `git add` / `commit` 版本变更）。  
+   Git 标签约定：与 `version` 对应、带前缀 **`v`**（如 `1.2.0` → 标签 `v1.2.0`）。
+
+3. **合并到 `master`**  
+   推送合并后的 `master` 会触发 GitHub Actions 工作流 [`.github/workflows/publish-npm.yml`](https://github.com/himan-group/himan/blob/master/.github/workflows/publish-npm.yml)：安装依赖后执行 **`pnpm run release`**（即再次 `verify` + `npm publish`）。
+   npm 发布认证使用 **Trusted Publishing**，不使用长期 `NPM_TOKEN`。需在 npmjs.com 的 `@hi-man/himan` 包设置中添加 Trusted Publisher：
+   - Provider: GitHub Actions
+   - Organization or user: `himan-group`
+   - Repository: `himan`
+   - Workflow filename: `publish-npm.yml`
+   workflow 已授予 OIDC 所需的 `id-token: write` 权限，并在发布前升级 npm CLI 到支持 Trusted Publishing 的版本。
+
+4. **手动从 CI 再发一次（可选）**  
+   在 GitHub **Actions → Publish to npm → Run workflow** 可手动运行同一流程（例如在修复密钥后重试）。
+
+### 本地命令（与 CI 中的 `pnpm run release` 一致）
+
+| 命令 | 作用 |
+|------|------|
+| `pnpm run verify` | 仅检查（类型 / 测试 / 构建） |
+| `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` 版本号，不发包 |
+
+发测试标签后，安装示例：`npm i @hi-man/himan@test`。
+
+### CI：PR 校验、发布与合并后打 Git 标签
+
+| 工作流 | 文件 | 说明 |
+|--------|------|------|
+| **PR verify** | [`.github/workflows/pr-verify.yml`](https://github.com/himan-group/himan/blob/master/.github/workflows/pr-verify.yml) | 目标分支为 `master` 的 PR：安装依赖后依次运行 `pnpm run typecheck`、`pnpm run test`、`pnpm run build`。 |
+| **PR version tag check** | [`.github/workflows/pr-master-version-tag.yml`](https://github.com/himan-group/himan/blob/master/.github/workflows/pr-master-version-tag.yml) | 目标分支为 `master` 的 PR：读取 **PR 头提交**上的 `package.json` 的 `version`，若远端已存在同名标签 **`v{version}`**，则 **检查失败**（用于在合并前拦截重复版本）。 |
+| **Tag version on master** | [`.github/workflows/push-master-version-tag.yml`](https://github.com/himan-group/himan/blob/master/.github/workflows/push-master-version-tag.yml) | 向 `master` **推送**后（含合并 PR）：在 **当前推送提交**上创建并推送注释标签 **`v{version}`**。若标签已存在、创建或 `git push` 失败，仅输出 **告警**（`::warning::`），**工作流仍成功**，不撤销已发生的 merge；请按日志提示在本机补打标签并 `git push origin v{x.y.z}`。 |
+
+**启用「合并前拦截」**：在 GitHub **Settings → Branches** 中为 `master` 配置分支保护，勾选 **Require status checks to pass before merging**，并勾选必选检查 **`PR verify / verify`** 和 **`PR version tag check / version-tag-available`**（名称以仓库里 Actions 界面为准）。
+
+说明：来自 fork 的 PR 同样会跑上述 PR 检查；打标签工作流需要 **Actions 对仓库有写权限**（工作流内已设 `contents: write`）。若组织策略禁止 `GITHUB_TOKEN` 写标签，推送标签会失败，需按告警手动推送。

package/docs/error-codes.md

@@ -0,0 +1,132 @@
+# himan 错误码说明
+
+本文档面向 CLI 使用者与自动化脚本维护者，说明 `himan` 的错误码、典型触发场景和建议处理方式。
+
+## `--json` 错误输出格式
+
+当命令带 `--json` 且执行失败时，CLI 会输出结构化错误（输出到 `stderr`）。  
+该规则同时覆盖：
+
+- 命令执行业务错误（如资源不存在）
+- 参数/命令解析错误（如缺参数、未知命令）
+
+输出格式：
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "E_RESOURCE_NOT_FOUND",
+    "message": "Resource not found: rule/code-review",
+    "details": {
+      "key": "value"
+    }
+  }
+}
+```
+
+字段说明：
+
+- `ok`: 固定为 `false`
+- `error.code`: 稳定错误码，建议脚本优先按此分流
+- `error.message`: 人类可读错误信息
+- `error.details`: 可选，附加上下文
+
+## 错误码列表
+
+### `E_CONFIG_NOT_FOUND`
+
+- **含义**：未找到源配置。
+- **常见触发**：首次使用前直接执行 `list/install/dev/publish`。
+- **建议处理**：先执行 `himan init <git_repo>`，或检查 `~/.himan/config.json` 是否存在。
+
+### `E_NOT_IMPLEMENTED`
+
+- **含义**：功能已预留但尚未实现。
+- **常见触发**：使用 registry 相关路径。
+- **建议处理**：改用 Git source；关注后续版本计划。
+
+### `E_INVALID_INPUT`
+
+- **含义**：输入参数不合法。
+- **常见触发**：source 名称不符合 kebab-case、git source 未提供 repo、install mode 不是 `link|copy`、agent 名称不支持等。
+- **建议处理**：按命令帮助修正参数格式。
+
+### `E_RESOURCE_NOT_FOUND`
+
+- **含义**：资源或来源不存在。
+- **常见触发**：安装不存在的资源、切换到不存在的 source 名称、发布目标资源不存在。
+- **建议处理**：先执行 `himan list <type>` / `himan source list` 确认名称。
+
+### `E_VERSION_NOT_FOUND`
+
+- **含义**：指定版本不存在。
+- **常见触发**：`install <type> <name@version>` 中版本号不在 tag 历史内。
+- **建议处理**：先执行 `himan history <type> <name>` 查看可用版本。
+
+### `E_INSTALL_NOT_FOUND`
+
+- **含义**：项目内未找到已安装目标。
+- **常见触发**：未安装直接 `dev`、或手动删除了 `.cursor/*/<name>` 等安装目标。
+- **建议处理**：先重新执行 `himan install <type> <name[@version]>`。
+
+### `E_LOCK_NOT_FOUND`
+
+- **含义**：未找到 lock 文件，或 lock 中无资源可恢复。
+- **常见触发**：项目未生成 `himan.lock` 就执行 `himan install`（无参数）。
+- **建议处理**：先安装至少一个资源以生成 lock，或检查 `himan.lock` 路径。
+
+### `E_LOCK_INVALID`
+
+- **含义**：`himan.lock` 存在但格式不合法。
+- **常见触发**：手动编辑导致 JSON 结构损坏、`version/resources` 字段异常。
+- **建议处理**：修复 lock JSON，或删除后重新通过 `install <type> <name[@version]>` 生成。
+
+### `E_CLI_USAGE`
+
+- **含义**：CLI 参数或命令解析错误（Commander 层）。
+- **常见触发**：缺少必填参数、未知命令、未知选项。
+- **建议处理**：检查命令拼写与参数数量，使用 `himan <command> --help` 查看正确用法。
+- **附加信息**：`error.details.commanderCode` 可用于进一步区分错误类别（如 `commander.missingArgument`）。
+
+### `E_RESOURCE_EXISTS`
+
+- **含义**：资源已存在，无法重复创建。
+- **常见触发**：重复执行 `create <type> <name>`。
+- **建议处理**：改名，或显式使用 `--force`。
+
+### `E_TEMPLATE_NOT_FOUND`
+
+- **含义**：模板不存在。
+- **常见触发**：`create` 使用了不支持的模板名。
+- **建议处理**：使用当前支持模板（默认 `basic`）。
+
+### `E_INVALID_RESOURCE_NAME`
+
+- **含义**：资源名不符合命名规则。
+- **常见触发**：使用非 kebab-case 的名称。
+- **建议处理**：改为 `kebab-case`（如 `code-review`）。
+
+### `E_INVALID_RESOURCE_METADATA`
+
+- **含义**：资源元数据不合法，无法发布或读取为有效资源。
+- **常见触发**：`publish` 目标缺少 `himan.yaml`，`name/type/entry` 不匹配，或 `entry` 指向的入口文件不存在。
+- **建议处理**：检查资源目录下的 `himan.yaml`，确认 `name`、`type`、`entry` 与命令参数和文件结构一致。
+
+### `E_PUBLISH_NO_CHANGES`
+
+- **含义**：发布时没有可提交的资源变更。
+- **常见触发**：重复发布已写入相同内容和版本的资源目录。
+- **建议处理**：确认资源内容或元数据已经变更，再重新执行 `publish`。
+
+### `E_UNSUPPORTED_RESOURCE_TYPE`
+
+- **含义**：资源类型不受支持。
+- **常见触发**：输入了 `rule|command|skill` 之外的类型。
+- **建议处理**：修正类型为 `rule`、`command` 或 `skill`。
+
+### `E_UNKNOWN`
+
+- **含义**：未映射到业务错误码的通用异常。
+- **常见触发**：程序运行期意外错误、普通 `Error` 抛出。
+- **建议处理**：保留完整命令与错误文本，提交 issue 或定位堆栈来源。

package/docs/mvp/README.md

@@ -0,0 +1,143 @@
+# himan MVP 功能点与技术设计
+
+> 状态说明：本文记录 MVP 设计和当前实现范围的收敛版。当前 CLI 行为以仓库根目录 [README.md](../../README.md) 和 [Codex repo map](../codex/repo-map.md) 为准。
+
+## 1. MVP 目标
+
+在 1 周内交付一个可实际使用的最小版本，完成资源资产的管理与发布闭环。
+
+**当前实现范围：**
+- 默认源模型：Git（`himan init <git_repo>`，本地缓存仓库并写配置）；已支持命名 source 的 `add/use/list`，业务命令按当前 default source 生效。
+- 本地 CLI，命令说明见仓库根目录 [README.md](../../README.md)
+- 资源版本以 Git Tag 为准，格式 `<type>/<name>@<semver>`
+- 资源类型能力：
+  - `rule`：`create` / `list` / `history` / `install` / `dev` / `publish` / `uninstall`
+  - `command`：`create` / `list` / `history` / `install` / `dev` / `publish` / `uninstall`
+  - `skill`：`create` / `list` / `history` / `install` / `dev` / `publish` / `uninstall`
+- 远程 Registry 源：仅占位，二期实现
+
+**不包含：** 可用 Registry、AI 搜索、PR 自动发布。
+
+---
+
+## 2. MVP 功能清单
+
+### 2.1 `init`
+
+- `himan init <git_repo>`
+- 克隆或更新远程仓库到用户目录下的缓存路径，并记录默认源配置。
+
+### 2.2 `list`
+
+- `himan list [type]`，`--json` 可选
+- 扫描源仓库中各类型目录下的 `himan.yaml`，返回名称、描述、目标 agent、入口文件等。
+
+### 2.3 `history`
+
+- `himan history <type> <name>`
+- 按 tag 模式 `<type>/<name>@*` 列出历史，semver 合法项排序输出。
+
+### 2.4 `install`
+
+- `himan install <type> <name>` 或 `<name>@version`，`type` 支持 `rule|command|skill`
+- 也支持 `himan install`（无参数）按 `himan.lock` 批量复现安装。
+- 未指定版本则安装该资源最新 tag 对应版本。
+- 若本地 store 中已有该版本缓存，则复用、不重新从 Git 导出；否则导出到 store。
+- 在项目下按安装模式创建目标（默认 `--mode link` 软链；`--mode copy` 复制）。
+- 目标路径由 agent 和资源类型共同决定：
+  - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
+  - `claude-code` -> `.claude/{rules|commands|skills}/<name>`
+  - `codex` -> `.agents/{rules|commands|skills}/<name>`
+  - `openclaw` -> `.openclaw/{rules|commands|skills}/<name>`
+
+### 2.5 `dev`
+
+- `himan dev <type> <name>`，`type` 支持 `rule|command|skill`；需先 `install`。
+- 将当前安装内容复制到项目开发目录（已存在则默认不覆盖），再按安装模式更新项目目标：
+  - `rule`：`.himan/dev/rule/<name>`
+  - `command`：`.himan/dev/command/<name>`
+  - `skill`：`.himan/dev/skill/<name>`
+
+### 2.6 `publish`
+
+- `himan publish <type> <name> --patch|--minor|--major`（默认 patch，三选一）
+- 发布内容优先取项目 `.himan/dev/<type>/<name>`，否则取源仓库内对应资源目录。
+- 新版本：基于已有 tag 最新 semver 递增；无任何历史时从 `0.0.0` 起算。
+- 写回源仓库、提交、打 tag、推送，并将该版本同步到本地 store。
+- 若该资源在项目中已有安装目标，会按 lock 中的安装模式同步到新版本目录。
+
+### 2.7 `create`
+
+- `himan create <type> <name>` 及常用选项（描述、目标 agent、dry-run、force、json 等）
+- 生成 `rule` / `command` / `skill` 标准目录与 `himan.yaml`、入口模板
+- 与 `publish` 衔接：`create → 编辑 → publish`
+
+### 2.8 `agent`
+
+- `himan agent list` 查看支持的 agent。
+- `himan agent use <agent[,agent]>` 设置当前项目默认 agent；加 `--global` 设置全局默认 agent。
+- `himan agent current` 查看当前项目、全局和最终生效的默认 agent。
+- `himan agent clear` 清除默认 agent 配置；默认清除当前项目，加 `--global` 清除全局配置。
+- 默认 agent 解析顺序：显式 `--agent` > 当前项目配置 > 全局配置 > 资源 metadata > `cursor`。
+
+---
+
+## 3. MVP 技术架构
+
+### 3.1 分层（概念）
+
+- **CLI**：解析参数、格式化输出、帮助与错误信息
+- **编排**：初始化源、列表、历史、安装、开发态、发布、创建等资源生命周期
+- **领域**：资源类型、版本、路径约定
+- **适配**：Git 实现 + Registry 预留；扫描与解析元数据；版本计算；配置与全局路径
+
+**原则：** store 按版本目录追加、不覆盖已有缓存；开发目录与项目安装目标分离；项目侧默认以软链引用资源，也支持复制。
+
+### 3.2 目录与数据
+
+**用户目录（如 `~/.himan`）：**
+- `repos/…`：Git 源缓存
+- `store/<type>/<name>/<version>/`：按版本的资源快照
+- `config.json`：当前源类型（git / registry 预留）、仓库地址、全局默认 agent 等
+
+**项目目录：**
+- `.cursor` / `.claude` / `.agents` / `.openclaw`：按 agent 和资源类型保存运行态目标（软链或副本）
+- `.himan/config.json`：项目默认 agent 配置
+- `.himan/dev/<type>/<name>`：资源开发态可编辑副本
+
+**源仓库内资源布局：**
+- `rules/<name>/`、`commands/<name>/`、`skills/<name>/`，各含 `himan.yaml` 与约定入口文件（如 `content.md`、`SKILL.md`）。
+
+### 3.3 技术依赖（概要）
+
+- Git：克隆、拉取、tag、按 tag 导出目录、提交与推送
+- Semver：排序与下一版本计算
+- YAML：资源元数据
+- 文件系统：目录复制、符号链接
+
+更细的实现说明见 [impl.md](./impl.md)；创建资源见 [create-resource.md](./create-resource.md)。
+
+---
+
+## 4. 非功能要求
+
+- 幂等：`install` / `dev` 重复执行不破坏合理预期状态
+- 可恢复：发布失败可重试，不依赖未文档化的中间态
+- 可诊断：错误信息能指向仓库、tag、路径或权限问题
+- 可测试：主流程有自动化测试覆盖
+
+---
+
+## 5. 测试策略
+
+- 自动化测试覆盖：版本解析、元数据扫描、配置、以及 CLI 主流程（含临时用户目录与模拟 Git 远端）。
+- 建议人工补充：真实网络 clone、鉴权失败、推送拒绝、脏工作区等。
+
+---
+
+## 6. 交付标准
+
+- 命令可执行，帮助信息完整
+- 主流程在自动化测试中可回归
+- 用户文档（根 README）与本 MVP 文档一致
+- 配置与适配层为二期 Registry 预留扩展空间

package/docs/mvp/create-resource.md

@@ -0,0 +1,129 @@
+# himan `create` 命令说明（rule / command / skill）
+
+说明「新建资源」的命令、目录与元数据约定，支撑 `create -> edit -> publish` 工作流。
+
+---
+
+## 1. 设计目标
+
+- 支持三类资源：`rule`、`command`、`skill`
+- 统一目录结构、`himan.yaml` 与默认入口内容
+- 与 `list` / `history` / `publish` / `install` / `dev` / `uninstall` 对所有类型保持一致
+
+**本阶段不做：** AI 生成正文、通过 Registry 在线创建、创建后自动发布。
+
+---
+
+## 2. 命令
+
+```bash
+himan create <type> <name> [options]
+```
+
+- `name`：kebab-case，例如 `code-review`
+
+**常用选项：**
+
+- `--description`：描述
+- `--agent`：目标 Agent，逗号分隔；未指定时使用当前项目默认 agent、全局默认 agent，最终回退到 `cursor`
+- `--entry`：入口文件名（各类型有默认值）
+- `--template`：模板名；MVP 仅内置 **basic**，其它名称会报错
+- `--force`：目录已存在时覆盖
+- `--dry-run`：只展示将创建的内容，不写盘
+- `--json`：结构化输出
+
+**默认入口文件：**
+
+- `rule`、`command` → `content.md`
+- `skill` → `SKILL.md`
+
+---
+
+## 3. 资源目录与元数据
+
+创建后的仓库结构示例：
+
+```text
+repo/
+  rules/<name>/
+    himan.yaml
+    content.md
+  commands/<name>/
+    himan.yaml
+    content.md
+  skills/<name>/
+    himan.yaml
+    SKILL.md
+```
+
+`himan.yaml` 最小字段示例：
+
+```yaml
+name: code-review
+type: rule
+version: 0.1.0
+entry: content.md
+description: enforce code review standards
+agents:
+  - cursor
+```
+
+- `version` 为初始占位；**正式发布版本以 Git Tag 为准**
+- `agents` 来自 `--agent` 或默认 agent 解析结果
+
+---
+
+## 4. 流程概要
+
+1. 读取本地配置，确认已初始化源
+2. 校验类型与资源名格式
+3. 解析目标路径 `rules|commands|skills/<name>`
+4. 目录已存在且无 `--force` → 报错
+5. 生成 `himan.yaml` 与入口模板（`--dry-run` 则不落盘）
+6. 终端或 `--json` 输出结果；下一步由用户编辑再 `publish`
+
+创建能力随源类型走同一抽象：**Git 已实现，Registry 未实现。**
+
+---
+
+## 5. 模板
+
+- 当前仅 **basic**：最简结构与提示性说明
+- 后续可扩展更多模板名；自定义模板目录可作为后续增强
+
+---
+
+## 6. 错误场景（产品语义）
+
+- 资源目录已存在
+- 模板不存在（含请求了尚未支持的模板名）
+- 资源名不合法
+- 不支持的资源类型
+- 源未初始化或当前源不支持创建
+
+---
+
+## 7. 测试关注点
+
+- 名称与类型校验、默认 entry/agents、重复创建与 `--force`、`--dry-run` 不写盘、创建后 `list` 可见
+
+---
+
+## 8. 与资源工作流衔接
+
+```text
+create → edit → publish
+```
+
+`create` 会在当前 Git source 缓存仓库中生成资源目录；用户编辑该目录后执行 `publish`。资源已有发布版本并安装到项目后，可再进入 `dev` 工作流：
+
+```bash
+himan create rule code-review --description "enforce standards"
+himan publish rule code-review --patch
+himan install rule code-review
+himan dev rule code-review
+# 编辑 .himan/dev/rule/code-review/
+himan publish rule code-review --patch
+```
+
+创建与发布职责分离，便于审核与版本治理。

package/docs/mvp/impl.md

@@ -0,0 +1,111 @@
+# himan MVP 详细技术实现方案
+
+本文档从**行为与技术选型**说明 MVP 如何实现，不绑定具体源码文件或符号名。
+
+> 状态说明：本文是 MVP 设计落地说明；当前 CLI 行为以仓库根目录 [README.md](../../README.md) 和 [Codex repo map](../codex/repo-map.md) 为准。
+
+---
+
+## 1. 技术栈与原则
+
+- TypeScript，运行于 Node.js LTS
+- CLI 解析、Git 封装、YAML 解析、Semver、基于 Promise 的文件与软链操作
+
+**原则：**
+
+- 本地 store 按版本存放，已存在的版本目录不被覆盖（安装时复用缓存）
+- 开发目录 `.himan/dev` 与运行态 agent 目录（`.cursor` / `.claude` / `.agents` / `.openclaw`）分离
+- 正式发布版本以 **Git Tag** 为唯一事实来源；`himan.yaml` 中的 version 在发布时会与 tag 对齐
+
+---
+
+## 2. 功能到实现要点
+
+### 2.1 `init <git_repo>`
+
+- 确保全局目录（缓存仓库、store、配置）存在
+- 由仓库 URL 推导稳定 id，首次克隆、后续拉取（含 tags）
+- 写入本地配置：当前源为 Git、仓库地址与 id
+- CLI 仅提供「Git URL」初始化；Registry 类型虽可在配置中预留，但尚无可用实现
+
+### 2.2 `list [type]`
+
+- 在缓存仓库内按类型扫描子目录，读取 `himan.yaml`
+- 校验类型与必填字段（如 name、entry），不符的目录跳过
+- 支持人类可读与 `--json` 输出
+
+### 2.3 `history <type> <name>`
+
+- 列出匹配 `<type>/<name>@*` 的 tag，解析 semver，非法 tag 忽略
+- 按版本倒序输出
+
+### 2.4 `install <type> <name>[@version]`
+
+- 命令层接受 `rule|command|skill`
+- 无版本则取该资源历史中的最新 semver
+- 若本地 store 已有该版本目录则不再从 Git 导出；否则从对应 tag 导出资源树到 store
+- 在项目中按 agent 和资源类型创建/更新安装目标，例如 `cursor -> .cursor/{rules|commands|skills}`、`codex -> .agents/{rules|commands|skills}`；默认软链到 store 中该版本，也可通过 `--mode copy` 复制内容
+
+### 2.5 `dev <type> <name>`
+
+- 命令层接受 `rule|command|skill`；依赖已安装（能解析当前安装目标）
+- 将当前安装内容复制到 `.himan/dev/<type>/<name>`（目录已存在则默认不覆盖）
+- 按安装模式将项目目标更新为 dev 目录的软链或副本
+
+### 2.6 `publish <type> <name>`
+
+- 发布源：优先项目 `.himan/dev/<type>/<name>`，否则缓存仓库内该资源目录
+- 下一版本：基于历史最新 tag；无历史则从 `0.0.0` 按 patch/minor/major 递增
+- 将内容同步回缓存仓库中的规范路径，更新元数据中的版本字段，提交、打 tag、推送
+- 将新 tag 对应内容拉取到 store 新版本目录
+- 若当前项目已安装该资源，则按 lock 中的安装模式同步更新项目内对应类型目标到新版本
+
+### 2.7 `create <type> <name>`
+
+- 校验类型与资源命名规则
+- 在缓存仓库中创建 `rules|commands|skills/<name>` 及 `himan.yaml`、入口模板
+- 支持覆盖、试运行、JSON 输出；创建后不自动发布
+
+### 2.8 `agent`
+
+- 命令层支持 `agent list|use|current|clear`
+- 当前项目默认 agent 写入 `.himan/config.json`
+- 全局默认 agent 写入 `~/.himan/config.json`
+- 默认 agent 生效顺序：显式 `--agent` > 当前项目配置 > 全局配置 > 资源 metadata > `cursor`
+
+---
+
+## 3. 架构：源适配与编排
+
+为避免上层与「一定是 Git」强耦合：
+
+- 抽象一层 **资源源**：初始化、列表、历史、按版本拉取内容、发布、创建
+- **Git** 为当前唯一完整实现
+- **Registry** 为占位：调用即提示未实现，二期对接 API 与下载/上传
+
+编排层负责：解析配置选择源、默认 agent、资源 store 路径、dev 拷贝、项目目标 materialize（软链或复制）；与具体 Git 子命令细节隔离。
+
+配置中可区分源类型并预留 Registry 所需字段（如 endpoint）；当前 CLI 初始化路径只写入 Git 源。
+
+---
+
+## 4. 其他实现注意点
+
+- 全局路径与用户主目录约定一致，避免魔法字符串散落
+- 错误应能区分：未初始化、资源不存在、版本不存在、模板不支持、重复创建等
+- 幂等与重试：安装、dev、发布在合理重复执行下行为可预期
+- 平台：优先保证 macOS/Linux；Windows 软链与路径差异可后续单独验证
+
+---
+
+## 5. 测试
+
+- 运行仓库内测试脚本（如 `pnpm test`），包含单元场景与 CLI 端到端场景（临时 HOME、本地裸仓库模拟远端等）
+- 仍建议补充：真实网络失败、Windows、并发安装等
+
+---
+
+## 6. 文档与示例
+
+- 命令参数与快速上手以根 README 为准
+- 创建资源字段与目录约定见 [create-resource.md](./create-resource.md)

package/package.json

@@ -1,22 +1,41 @@
 {
   "name": "@hi-man/himan",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Prompt and agent asset management CLI",
+  "keywords": [
+    "ai",
+    "agent",
+    "prompt",
+    "prompt-management",
+    "cli",
+    "git",
+    "codex",
+    "cursor",
+    "claude"
+  ],
   "license": "MIT",
   "type": "module",
   "packageManager": "pnpm@10.32.1",
+  "engines": {
+    "node": ">=22 <23"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/lidetao/himan.git"
+    "url": "git+https://github.com/himan-group/himan.git"
   },
   "bugs": {
-    "url": "https://github.com/lidetao/himan/issues"
+    "url": "https://github.com/himan-group/himan/issues"
   },
-  "homepage": "https://github.com/lidetao/himan#readme",
+  "homepage": "https://github.com/himan-group/himan#readme",
   "files": [
     "dist",
+    "docs/development.md",
+    "docs/mvp",
+    "docs/error-codes.md",
     "README.md",
-    "LICENSE"
+    "CHANGELOG.md",
+    "LICENSE",
+    ".nvmrc"
   ],
   "publishConfig": {
     "access": "public",
@@ -29,6 +48,8 @@
     "himan-project": "dist/bin/himan-project.js"
   },
   "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/bin/himan.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",