@hi-man/himan 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,17 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-05-14
+
+### Added
+
+- Added `himan doctor` to check local Node/Git availability, Himan home state, current source scanning, effective agents, project lock state, and installed targets.
+
+### Changed
+
+- Changed `create` and `dev` to use current project agent target directories for resource authoring, while `publish` now logs stages and can install the published version either into the current project or globally.
+- Changed `himan init` to support quick-start setup with optional `--agent`, `--install type/name[@version],...`, `--mode`, and `--json`.
+
 ## [0.4.0] - 2026-05-13
 
 ### Added

package/README.md

@@ -41,15 +41,21 @@ pnpm dlx @hi-man/himan --help
 以下示例假设你已有一个可访问的 himan Git source 仓库，仓库中存在 `my-rule` 的资源版本 tag，并且你拥有发布所需的 Git push 权限。
 
 ```bash
-himan init https://github.com/your-org/your-himan-registry.git
-himan list rule
-himan agent use codex
-himan install rule my-rule
+himan init https://github.com/your-org/your-himan-registry.git \
+  --agent codex \
+  --install rule/my-rule
+himan doctor
+himan create skill my-skill
+# 编辑并验证项目下 .agents/skills/my-skill/
+himan publish skill my-skill --patch
 himan dev rule my-rule
-# 编辑项目下 .himan/dev/rule/my-rule/
+# 直接编辑项目下 .agents/rules/my-rule/；若只存在全局安装，dev 会先复制到当前项目
 himan publish rule my-rule --patch
 ```
 
+- `init` 的 `--agent` 会写入当前项目默认 agent；`--install` 可一次选择要安装的资源，格式为 `type/name[@version]`，多个资源用逗号分隔，例如 `rule/my-rule,skill/my-skill@1.0.0`。
+- 也可以只执行 `himan init <git_url>` 跳过 agent 和资源安装，后续再用 `himan agent use ...`、`himan list ...`、`himan install ...` 单独配置。
+- `himan doctor` 会检查本机 Node/Git、Himan home、当前 source、资源扫描、默认 agent、lock 和已安装目标。
 - **rule / command / skill**：都支持 `create`、`rename`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`；其中 `rename` 暂不推荐使用。
 - 安装后项目目标位置（按 `agents`，默认 `cursor`）：
   - `cursor` -> `.cursor/{rules|commands|skills}/<name>`
@@ -61,10 +67,11 @@ himan publish rule my-rule --patch
   - `claude-code` -> `~/.claude/{rules|commands|skills}/<name>`
   - `codex` -> `~/.agents/{rules|commands|skills}/<name>`
   - `openclaw` -> `~/.openclaw/{rules|commands|skills}/<name>`
-- 开发态目录：
-  - `rule` -> `.himan/dev/rule/<name>`
-  - `command` -> `.himan/dev/command/<name>`
-  - `skill` -> `.himan/dev/skill/<name>`
+- 创建与开发态目录默认就是当前项目的 agent 目标目录；例如 Codex：
+  - `rule` -> `.agents/rules/<name>`
+  - `command` -> `.agents/commands/<name>`
+  - `skill` -> `.agents/skills/<name>`
+  `dev` 修改项目内资源时不再创建 `.himan/dev`，只在资源仅存在于用户级全局目录时复制到当前项目对应 agent 目录。
 - lock 文件：项目安装 `install <type> <name[@version]>` 会写入 `himan.lock`，记录 source、精确版本、agent 和安装模式；`himan install`（无参数）会按 lock 记录的 source 批量恢复安装，不受当前 default source 切换影响。`--global` 安装不写当前项目的 `himan.lock`。
 - 安装模式：默认 `--mode copy` 将资源复制到目标 agent 目录；也可用 `--mode link` 使用软链，lock 会记录并复现该模式。
 - 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
@@ -131,10 +138,12 @@ analysis:
 
 可通过 `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 rename` 和 `himan publish` 会自动维护 source 根目录文档：
+`himan create` 默认在当前项目 agent 目标目录创建资源脚手架，供用户直接验证；`himan publish` 会把项目目录中的资源同步回当前 default source，并自动维护 source 根目录文档：
 
 - `README.md`：只更新 `<!-- himan:resources:start -->` 和 `<!-- himan:resources:end -->` 之间的资源索引；如果没有 marker，会在文件末尾追加一个受控资源索引区。
-- `CHANGELOG.md`：向 `[Unreleased]` 下追加资源变更条目；`create` 记录 `Added`，`rename` / `publish` 记录 `Changed`。
+- `CHANGELOG.md`：`publish` 向 `[Unreleased]` 下追加 `Changed` / published version 条目。
+
+`himan rename` 也会维护 source 根目录文档：更新 README 资源索引，并向 CHANGELOG 的 `[Unreleased]` 追加 `Changed` 条目。
 
 仓库根目录的 `README.md` 和 `CHANGELOG.md` 不会被安装到 agent 目录；agent 只消费被安装的具体资源目录。当前安装实现会 materialize 资源目录本身，因此对 Cursor 这类要求特定单文件格式的 agent，资源目录内应避免放入会干扰识别的额外文件。
 
@@ -144,11 +153,13 @@ analysis:
 
 | 命令                          | 说明                                             |
 | ----------------------------- | ------------------------------------------------ |
-| `init <git_url>`              | 初始化默认源（当前为 Git）并写入 `~/.himan/config.json` |
+| `init <git_url> [--agent a,b] [--install type/name[@version],...] [--mode link\|copy] [--json]` | 初始化默认源（当前为 Git）并写入 `~/.himan/config.json`；可同时写当前项目默认 agent 并安装选定资源 |
 | `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 clone <from> <to> [--branch b] [--target-branch b] [--add-source name] [--use] [--dry-run] [--json]` | 将 Git source 分支和 himan 管理的资源 tag 复制到空目标 Git 仓库 |
+| `source sync <from> <to> [--target-branch b] [--add-source name] [--use] [--dry-run] [--json]` | 将最新资源快照同步到目标 Git 仓库并创建对应最新 tag |
 | `source init <git_url>`       | 与 `init` 等价，便于统一走 `himan source ...` 入口     |
 
 等价独立命令：
@@ -158,6 +169,8 @@ analysis:
 - `himan-source use <name>`
 - `himan-source list [--json]`
 - `himan-source init-docs [--force] [--dry-run] [--json]`
+- `himan-source clone <from> <to> [...]`
+- `himan-source sync <from> <to> [...]`
 
 ### 2) resource（资源）
 
@@ -165,7 +178,7 @@ analysis:
 | -------------------------------- | ----------------------------------------------------------------------------------- |
 | `list [type] [--agent a,b] [--brief] [--installed] [--json]` | 默认列出当前 default source 的资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源 |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
-| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `create <type> <name>`           | 在当前项目 agent 目录创建脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
 | `rename <type> <old-name> <new-name>` | 暂不推荐使用；重命名当前 default source 中的资源；常用选项：`--dry-run`、`--no-project`、`--json` |
 
 ### 3) project（当前项目）
@@ -174,9 +187,9 @@ analysis:
 | --------------------------------- | --------------------------------------------------------- |
 | `list [type] [--agent a,b] [--json]` | 查看当前项目 `himan.lock` 中记录的已安装资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示 |
 | `install [type] [name[@version]] [--global] [--agent a,b] [--mode link\|copy]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；加 `--global` 时安装到用户级 agent 目录且不写项目 lock；可覆盖安装目标 agent 或安装模式 |
-| `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
+| `dev <type> <name>`               | 切换到开发态；项目资源原地编辑，全局资源先复制到当前项目目标目录 |
 | `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
-| `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
+| `publish <type> <name> [--global]` | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个）；发布后默认安装到当前项目并更新 lock，`--global` 安装到用户级目录 |
 
 ### 4) agent（默认 Agent）
 
@@ -187,6 +200,12 @@ analysis:
 | `agent current [--json]` | 查看当前项目、全局和最终生效的默认 agent |
 | `agent clear [--project\|--global] [--json]` | 清除当前项目或全局默认 agent；默认 `--project` |
 
+### 5) doctor（可用性检查）
+
+| 命令 | 说明 |
+|------|------|
+| `doctor [--json]` | 检查 Node/Git、Himan home、当前 source、资源扫描、默认 agent、项目 lock 和已安装目标；存在 error 时以非零状态退出 |
+
 也可使用分组命令（与上面等价）：
 
 - `himan resource list|history|create|rename ...`
@@ -194,11 +213,12 @@ analysis:
 - `himan project list|install|dev|uninstall|publish ...`
 - `himan-project list|install|dev|uninstall|publish ...`
 - `himan agent list|use|current|clear ...`
+- `himan doctor ...`
 
 说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
-若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
+若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用当前项目已有安装位置，找不到时再从用户级全局安装位置复制到当前项目。`install --global` 会优先复用当前项目 lock 里该资源的 agent，未命中时再使用默认 install 解析顺序，但目标根目录是用户 home 下对应 agent 目录。
 
-`publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录。
+`publish` 会展示 prepare、resolve-version、publish-source、sync-store、install、cleanup、done 等阶段日志。发布源优先使用旧版 `.himan/dev` 目录，其次使用当前项目 agent 目标目录，最后回退到 source 仓库对应资源目录。若资源目录包含 `himan.yaml`，发布前会校验元数据与入口文件；若没有 `himan.yaml`，则按默认入口推断最小元数据并发布，不会强制创建 `himan.yaml`。若待发布资源内容与最新已发布版本一致，则以 `E_PUBLISH_NO_CHANGES` 终止发布。发布需要可推送的 Git 权限。发布 commit 会包含资源目录以及自动维护的 source 根目录 `README.md` / `CHANGELOG.md`。发布成功后会从新版本 store 以 `copy` 模式重新安装；默认安装到当前项目并更新 `himan.lock`，传 `--global` 时安装到用户级目录且不写当前项目 lock。
 
 `rename` 暂不推荐使用。该命令会移动 source 仓库里的资源目录并更新资源 metadata 名称、README 资源索引和 CHANGELOG。已有发布 tag 不会被改写；若旧资源已有历史版本，rename 会为新名字创建一个指向当前最新版本的 tag。默认会迁移当前项目中对应的安装目标、`.himan/dev` 副本和 lock 条目；传 `--no-project` 时只改 source。对于 skill，命令只自动更新 metadata / front matter 中的精确 `name` 字段，不会自动替换 `SKILL.md` 正文中的旧名称引用。
 

package/dist/cli/builders.js

@@ -1,5 +1,6 @@
 import { ServiceFactory } from "../services/index.js";
 import { registerAgentCommands } from "./agent-commands.js";
+import { registerDoctorCommand } from "./doctor-command.js";
 import { registerProjectCommands } from "./project-commands.js";
 import { registerResourceCommands } from "./resource-commands.js";
 import { registerInitCommand, registerSourceCommands } from "./source-commands.js";
@@ -9,6 +10,7 @@ export function buildCli() {
     const services = new ServiceFactory();
     appendCommandGroupsHelp(program);
     registerInitCommand(program, services);
+    registerDoctorCommand(program, services);
     const sourceCmd = program.command("source").description("Manage source repositories");
     registerSourceCommands(sourceCmd, services, { includeInit: true });
     const resourceCmd = program
@@ -70,5 +72,7 @@ Command groups:
            project list, project install, project dev, project uninstall, project publish
   agent    Default agent configuration
            agent list, agent use, agent current, agent clear
+  doctor   Runtime and project health checks
+           doctor
 `);
 }

package/dist/cli/doctor-command.js

@@ -0,0 +1,30 @@
+import { runAction } from "./shared.js";
+export function registerDoctorCommand(command, services) {
+    command
+        .command("doctor")
+        .option("--json", "output json format")
+        .description("Check Himan runtime and project health")
+        .action(async (options) => {
+        await runAction(async () => {
+            const result = await services.doctor(process.cwd());
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                writeDoctorResult(result);
+            }
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        });
+    });
+}
+function writeDoctorResult(result) {
+    process.stdout.write("Himan doctor\n");
+    for (const check of result.checks) {
+        process.stdout.write(`${formatCheckStatus(check)} ${check.name}: ${check.message}\n`);
+    }
+}
+function formatCheckStatus(check) {
+    return `[${check.status}]`;
+}

package/dist/cli/project-commands.js

@@ -82,7 +82,11 @@ export function registerProjectCommands(command, services, options = {}) {
         await runAction(async () => {
             const resourceType = ensureResourceType(type);
             const result = await services.dev(resourceType, name, process.cwd());
-            process.stdout.write(`Switched ${result.type}/${result.name} to dev mode: ${result.devPath}\n`);
+            if (result.sourceScope === "global") {
+                process.stdout.write(`Copied global ${result.type}/${result.name} into current project: ${result.devPath}\n`);
+                return;
+            }
+            process.stdout.write(`Editing ${result.type}/${result.name} in place: ${result.devPath}\n`);
         });
     });
     command
@@ -104,13 +108,23 @@ export function registerProjectCommands(command, services, options = {}) {
         .option("--patch", "patch release")
         .option("--minor", "minor release")
         .option("--major", "major release")
+        .option("--global", "install the published version into user-level agent directories")
         .description("Publish resource (default: --patch)")
         .action(async (type, name, options) => {
         await runAction(async () => {
             const resourceType = ensureResourceType(type);
             const releaseType = resolveReleaseType(options);
-            const result = await services.publish(resourceType, name, releaseType, process.cwd());
-            process.stdout.write(`Published ${result.type}/${result.name}@${result.version}\n`);
+            const installScope = options.global ? "global" : "project";
+            process.stdout.write(options.global
+                ? "Published resource will be installed globally; current project lock will not be updated.\n"
+                : "Published resource will be installed into the current project and recorded in himan.lock. Use --global to install globally instead.\n");
+            const result = await services.publish(resourceType, name, releaseType, process.cwd(), {
+                installScope,
+                onProgress: (progress) => {
+                    process.stdout.write(`[publish:${progress.stage}] ${progress.message}\n`);
+                },
+            });
+            process.stdout.write(`Published ${result.type}/${result.name}@${result.version} and installed ${result.installScope === "global" ? "globally" : "into current project"}\n`);
         });
     });
 }

package/dist/cli/source-commands.js

@@ -1,12 +1,41 @@
+import { getSupportedAgentNames, normalizeAgent } from "../utils/agent-configs.js";
+import { HimanError, errorCodes } from "../utils/errors.js";
 import { runAction } from "./shared.js";
 export function registerInitCommand(command, services) {
     command
         .command("init")
         .argument("<git_repo>", "Git repository URL")
-        .action(async (gitRepo) => {
+        .option("--agent <list>", "set current project default agents, comma separated")
+        .option("--install <refs>", "install resource refs after init, comma separated: rule/name[@version]")
+        .option("--mode <mode>", "install mode for --install: link or copy")
+        .option("--json", "output json format")
+        .action(async (gitRepo, options) => {
         await runAction(async () => {
-            const result = await services.initSource("git", gitRepo);
-            process.stdout.write(`Initialized ${result.sourceType} source: ${result.repo}\n`);
+            const agents = parseAgents(options.agent);
+            const installRefs = parseInstallRefs(options.install);
+            const mode = parseInstallMode(options.mode);
+            if (mode && installRefs.length === 0) {
+                throw new HimanError(errorCodes.CLI_USAGE, "Use --mode only with --install.");
+            }
+            const source = await services.initSource("git", gitRepo);
+            const agentResult = agents?.length
+                ? await services.setAgents(agents, "project", process.cwd())
+                : undefined;
+            const installed = [];
+            for (const ref of installRefs) {
+                installed.push(await services.install(ref.type, ref.name, ref.version, process.cwd(), agents, mode));
+            }
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify({ source, agents: agentResult, installed }, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Initialized ${source.sourceType} source: ${source.repo}\n`);
+            if (agentResult) {
+                process.stdout.write(`Using agents (${agentResult.scope}): ${agentResult.agents.join(", ")}\n`);
+            }
+            for (const item of installed) {
+                process.stdout.write(`Installed ${item.type}/${item.name}@${item.version}\n`);
+            }
         });
     });
 }
@@ -158,3 +187,67 @@ export function registerSourceCommands(command, services, options) {
         });
     });
 }
+function ensureResourceType(type) {
+    if (type !== "rule" && type !== "command" && type !== "skill") {
+        throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type: ${type}`);
+    }
+    return type;
+}
+function parseInstallRefs(input) {
+    if (!input)
+        return [];
+    const refs = input
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (refs.length === 0) {
+        throw new HimanError(errorCodes.INVALID_INPUT, "Install list cannot be empty.");
+    }
+    return refs.map((ref) => {
+        const parts = ref.split("/");
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new HimanError(errorCodes.INVALID_INPUT, `Invalid install ref: ${ref}. Use type/name[@version].`);
+        }
+        const { name, version } = parseNameVersion(parts[1]);
+        if (!name) {
+            throw new HimanError(errorCodes.INVALID_INPUT, `Invalid install ref: ${ref}. Use type/name[@version].`);
+        }
+        return {
+            type: ensureResourceType(parts[0]),
+            name,
+            version,
+        };
+    });
+}
+function parseNameVersion(input) {
+    const idx = input.lastIndexOf("@");
+    if (idx <= 0)
+        return { name: input };
+    return { name: input.slice(0, idx), version: input.slice(idx + 1) };
+}
+function parseInstallMode(input) {
+    if (!input)
+        return undefined;
+    const normalized = input.trim().toLowerCase();
+    if (normalized === "link" || normalized === "copy") {
+        return normalized;
+    }
+    throw new HimanError(errorCodes.INVALID_INPUT, `Unsupported install mode: ${input}. Supported modes: link, copy`);
+}
+function parseAgents(input) {
+    if (!input)
+        return undefined;
+    const agents = input
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (agents.length === 0)
+        return undefined;
+    const supported = getSupportedAgentNames();
+    for (const agent of agents) {
+        if (!normalizeAgent(agent)) {
+            throw new HimanError(errorCodes.INVALID_INPUT, `Unsupported agent: ${agent}. Supported agents: ${supported.join(", ")}`);
+        }
+    }
+    return agents;
+}

package/dist/domain/doctor.js

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

package/dist/services/index.js

@@ -8,9 +8,13 @@ import { toRepoId } from "../utils/repo-id.js";
 import { HimanError, errorCodes } from "../utils/errors.js";
 import { getGlobalResourcePaths, getProjectResourcePaths, getSupportedAgentNames, normalizeAgents, } from "../utils/agent-configs.js";
 import path from "node:path";
+import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
+import { promisify } from "node:util";
 import { VersionResolver } from "../adapters/version/version-resolver.js";
 import YAML from "yaml";
+const execFileAsync = promisify(execFile);
+const RESOURCE_TYPES = ["rule", "command", "skill"];
 export class ServiceFactory {
     stateStore = new StateStore();
     projectConfigStore = new ProjectConfigStore();
@@ -176,6 +180,45 @@ export class ServiceFactory {
             supported: getSupportedAgentNames(),
         };
     }
+    async doctor(projectDir) {
+        const checks = [];
+        checks.push(this.checkNodeVersion());
+        checks.push(await this.checkGit());
+        checks.push(await this.checkHomeState());
+        const config = await this.stateStore.loadConfig();
+        if (!config?.source) {
+            checks.push({
+                name: "source",
+                status: "error",
+                message: "No source configured. Run `himan init <git_repo>` first.",
+                details: { configPath: this.stateStore.getConfigPath() },
+            });
+        }
+        else {
+            const currentName = config.sources?.default ?? "default";
+            const currentSource = config.sources?.items[currentName] ?? config.source;
+            checks.push({
+                name: "source",
+                status: "ok",
+                message: `Using ${currentSource.type} source ${currentName}.`,
+                details: {
+                    name: currentName,
+                    type: currentSource.type,
+                    repo: currentSource.repo,
+                    repoId: currentSource.repoId,
+                },
+            });
+            checks.push(await this.checkSourceResources());
+        }
+        checks.push(await this.checkAgents(projectDir));
+        const lockCheck = await this.checkProjectLock(projectDir);
+        checks.push(lockCheck.check);
+        checks.push(await this.checkProjectTargets(projectDir, lockCheck.lock));
+        return {
+            ok: !checks.some((check) => check.status === "error"),
+            checks,
+        };
+    }
     async clearAgents(scope, projectDir) {
         if (scope === "project") {
             await this.projectConfigStore.clearAgents(projectDir);
@@ -188,6 +231,172 @@ export class ServiceFactory {
         });
         return { scope };
     }
+    checkNodeVersion() {
+        const version = process.versions.node;
+        const major = Number(version.split(".")[0]);
+        if (major === 22) {
+            return {
+                name: "node",
+                status: "ok",
+                message: `Node.js ${version}.`,
+            };
+        }
+        return {
+            name: "node",
+            status: "error",
+            message: `Node.js ${version} is unsupported. Use Node.js 22.x.`,
+        };
+    }
+    async checkGit() {
+        try {
+            const result = await execFileAsync("git", ["--version"]);
+            return {
+                name: "git",
+                status: "ok",
+                message: result.stdout.trim() || "Git is available.",
+            };
+        }
+        catch (error) {
+            return this.errorCheck("git", "Git is not available on PATH.", error);
+        }
+    }
+    async checkHomeState() {
+        const root = this.paths.getHimanRoot();
+        const reposDir = this.paths.getReposDir();
+        const storeDir = this.paths.getStoreDir();
+        const missing = [];
+        if (!(await this.exists(root)))
+            missing.push(root);
+        if (!(await this.exists(reposDir)))
+            missing.push(reposDir);
+        if (!(await this.exists(storeDir)))
+            missing.push(storeDir);
+        if (missing.length > 0) {
+            return {
+                name: "home",
+                status: "warn",
+                message: "Himan home directories are not fully initialized yet.",
+                details: { root, reposDir, storeDir, missing },
+            };
+        }
+        return {
+            name: "home",
+            status: "ok",
+            message: `Himan home is initialized at ${root}.`,
+            details: { root, reposDir, storeDir },
+        };
+    }
+    async checkSourceResources() {
+        try {
+            const source = await this.loadSourceFromConfig();
+            const entries = await Promise.all(RESOURCE_TYPES.map(async (type) => [type, await source.list(type)]));
+            const counts = Object.fromEntries(entries.map(([type, resources]) => [type, resources.length]));
+            const total = RESOURCE_TYPES.reduce((sum, type) => sum + counts[type], 0);
+            return {
+                name: "resources",
+                status: "ok",
+                message: `Scanned ${total} resources from current source.`,
+                details: { counts },
+            };
+        }
+        catch (error) {
+            return this.errorCheck("resources", "Cannot scan current source resources.", error);
+        }
+    }
+    async checkAgents(projectDir) {
+        try {
+            const settings = await this.getAgentSettings(projectDir);
+            const scope = settings.project ? "project" : settings.global ? "global" : "default";
+            return {
+                name: "agents",
+                status: "ok",
+                message: `Effective agents: ${settings.effective.join(", ")} (${scope}).`,
+                details: settings,
+            };
+        }
+        catch (error) {
+            return this.errorCheck("agents", "Cannot resolve effective agents.", error);
+        }
+    }
+    async checkProjectLock(projectDir) {
+        const lockPath = this.lockStore.getLockPath(projectDir);
+        const { lock, state } = await this.lockStore.loadWithState(projectDir);
+        if (state === "missing") {
+            return {
+                check: {
+                    name: "lock",
+                    status: "ok",
+                    message: "No himan.lock found for this project yet.",
+                    details: { lockPath },
+                },
+            };
+        }
+        if (state === "invalid" || !lock) {
+            return {
+                check: {
+                    name: "lock",
+                    status: "error",
+                    message: `Lock file is invalid: ${lockPath}`,
+                    details: { lockPath },
+                },
+            };
+        }
+        if (lock.resources.length === 0) {
+            return {
+                check: {
+                    name: "lock",
+                    status: "warn",
+                    message: "himan.lock has no resources.",
+                    details: { lockPath },
+                },
+                lock,
+            };
+        }
+        return {
+            check: {
+                name: "lock",
+                status: "ok",
+                message: `himan.lock tracks ${lock.resources.length} resources.`,
+                details: { lockPath, source: lock.source },
+            },
+            lock,
+        };
+    }
+    async checkProjectTargets(projectDir, lock) {
+        if (!lock || lock.resources.length === 0) {
+            return {
+                name: "targets",
+                status: "ok",
+                message: "No locked project targets to verify.",
+            };
+        }
+        const missing = [];
+        for (const resource of lock.resources) {
+            const agents = normalizeAgents(resource.agents);
+            const targets = getProjectResourcePaths(projectDir, resource.type, resource.name, agents);
+            for (const targetPath of targets) {
+                if (!(await this.exists(targetPath))) {
+                    missing.push({
+                        resource: `${resource.type}/${resource.name}@${resource.version}`,
+                        path: targetPath,
+                    });
+                }
+            }
+        }
+        if (missing.length > 0) {
+            return {
+                name: "targets",
+                status: "warn",
+                message: `Missing ${missing.length} installed targets. Run \`himan install\` to restore them.`,
+                details: { missing },
+            };
+        }
+        return {
+            name: "targets",
+            status: "ok",
+            message: "All locked project targets exist.",
+        };
+    }
     async list(type, agents) {
         const source = await this.loadSourceFromConfig();
         const resources = await source.list(type);
@@ -231,22 +440,33 @@ export class ServiceFactory {
         return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
     }
     async dev(type, name, projectDir) {
-        const installInfo = await this.resolveInstalledResource(projectDir, type, name);
-        const installedPath = installInfo.installedPath;
-        const devPath = this.getProjectDevPath(projectDir, type, name);
-        if (!(await this.exists(devPath))) {
-            await fs.mkdir(path.dirname(devPath), { recursive: true });
-            await fs.cp(installedPath, devPath, { recursive: true });
+        const projectTarget = await this.tryResolveProjectResourceTarget(projectDir, type, name);
+        if (projectTarget) {
+            return {
+                type,
+                name,
+                devPath: projectTarget.resourcePath,
+                linkPath: projectTarget.linkPaths[0],
+                mode: projectTarget.mode,
+                sourceScope: "project",
+            };
         }
-        for (const linkPath of installInfo.linkPaths) {
-            await this.materializeResource(devPath, linkPath, installInfo.mode);
+        const globalTarget = await this.tryResolveGlobalResourceTarget(projectDir, type, name);
+        if (!globalTarget) {
+            throw new HimanError(errorCodes.INSTALL_NOT_FOUND, `Installed resource link not found for ${type}/${name}. Run install first.`);
+        }
+        const projectLinkPaths = getProjectResourcePaths(projectDir, type, name, globalTarget.agents);
+        for (const [index, linkPath] of projectLinkPaths.entries()) {
+            const sourcePath = globalTarget.linkPaths[index] ?? globalTarget.resourcePath;
+            await this.materializeResource(sourcePath, linkPath, "copy");
         }
         return {
             type,
             name,
-            devPath,
-            linkPath: installInfo.linkPaths[0],
-            mode: installInfo.mode,
+            devPath: projectLinkPaths[0],
+            linkPath: projectLinkPaths[0],
+            mode: "copy",
+            sourceScope: "global",
         };
     }
     async uninstall(type, name, projectDir) {
@@ -260,58 +480,117 @@ export class ServiceFactory {
         await this.lockStore.removeResource(projectDir, { type, name });
         return { type, name, linkPath: installInfo.linkPaths[0] };
     }
-    async publish(type, name, releaseType, projectDir) {
+    async publish(type, name, releaseType, projectDir, options = {}) {
+        const installScope = options.installScope ?? "project";
+        this.reportPublishProgress(options, "prepare", `Preparing ${type}/${name}.`);
         const source = await this.loadSourceFromConfig();
         const sourceDir = await this.resolvePublishSourceDir(type, name, projectDir);
         const existingInstallInfo = await this.tryResolveInstalledResource(projectDir, type, name);
+        const existingGlobalInstallInfo = await this.tryResolveGlobalResourceTarget(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);
+        this.reportPublishProgress(options, "resolve-version", `Resolved ${releaseType} version ${nextVersion}.`);
+        this.reportPublishProgress(options, "publish-source", `Publishing ${type}/${name}@${nextVersion} to the Git source.`);
         const result = await source.publish(type, name, nextVersion, sourceDir, {
             releaseType,
         });
         const storePath = this.getStorePath(type, name, nextVersion);
+        this.reportPublishProgress(options, "sync-store", `Syncing ${type}/${name}@${nextVersion} into the local store.`);
         if (!(await this.exists(storePath))) {
             await source.pull(type, name, nextVersion, storePath);
         }
         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)
-            : existingInstallInfo?.agents.length
-                ? normalizeAgents(existingInstallInfo.agents)
-                : configuredAgents ?? normalizeAgents(resourceMeta?.agents);
         const installMode = "copy";
-        const linkPaths = getProjectResourcePaths(projectDir, type, name, nextAgents);
+        const nextAgents = installScope === "global"
+            ? existingGlobalInstallInfo?.agents.length
+                ? normalizeAgents(existingGlobalInstallInfo.agents)
+                : existingInstallInfo?.agents.length
+                    ? normalizeAgents(existingInstallInfo.agents)
+                    : locked?.agents?.length
+                        ? normalizeAgents(locked.agents)
+                        : configuredAgents ?? normalizeAgents(resourceMeta?.agents)
+            : locked?.agents?.length
+                ? normalizeAgents(locked.agents)
+                : existingInstallInfo?.agents.length
+                    ? normalizeAgents(existingInstallInfo.agents)
+                    : configuredAgents ?? normalizeAgents(resourceMeta?.agents);
+        const linkPaths = installScope === "global"
+            ? getGlobalResourcePaths(this.paths.getHomeDir(), type, name, nextAgents)
+            : getProjectResourcePaths(projectDir, type, name, nextAgents);
+        this.reportPublishProgress(options, "install", installScope === "global"
+            ? `Installing published version globally for ${nextAgents.join(", ")}.`
+            : `Installing published version into the current project for ${nextAgents.join(", ")}.`);
         for (const linkPath of linkPaths) {
             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,
-        });
+        if (installScope === "project") {
+            const sourceInfo = await this.getLockSourceInfo();
+            await this.lockStore.upsertResource(projectDir, sourceInfo, {
+                type,
+                name,
+                version: nextVersion,
+                agents: nextAgents,
+                mode: installMode,
+            });
+        }
+        this.reportPublishProgress(options, "cleanup", `Cleaning up legacy dev copy if present.`);
         await fs.rm(this.getProjectDevPath(projectDir, type, name), {
             recursive: true,
             force: true,
         });
-        return { type, name, version: result.version, tag: result.tag };
+        this.reportPublishProgress(options, "done", `Published ${type}/${name}@${result.version}.`);
+        return {
+            type,
+            name,
+            version: result.version,
+            tag: result.tag,
+            installScope,
+            linkPath: linkPaths[0],
+        };
     }
     async create(type, name, options, projectDir) {
         this.validateCreateInput(type, name, options);
-        const source = await this.loadSourceFromConfig();
-        return source.create(type, name, {
-            description: options.description,
-            agents: await this.resolveEffectiveAgents(projectDir, options.agents),
-            entry: options.entry,
-            template: options.template ?? "basic",
-            force: options.force,
-            dryRun: options.dryRun,
-        });
+        await this.loadSourceFromConfig();
+        const agents = await this.resolveEffectiveAgents(projectDir, options.agents);
+        const resourcePaths = getProjectResourcePaths(projectDir, type, name, agents);
+        const entry = options.entry ?? this.getDefaultEntry(type);
+        const files = resourcePaths.flatMap((resourcePath) => [
+            path.join(resourcePath, "himan.yaml"),
+            path.join(resourcePath, entry),
+        ]);
+        const existingPaths = [];
+        for (const resourcePath of resourcePaths) {
+            if (await this.exists(resourcePath))
+                existingPaths.push(resourcePath);
+        }
+        if (existingPaths.length > 0 && !options.force) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`, { paths: existingPaths });
+        }
+        if (!options.dryRun) {
+            for (const resourcePath of resourcePaths) {
+                await fs.rm(resourcePath, { recursive: true, force: true });
+                await fs.mkdir(resourcePath, { recursive: true });
+                await fs.writeFile(path.join(resourcePath, "himan.yaml"), YAML.stringify({
+                    name,
+                    type,
+                    version: "0.1.0",
+                    entry,
+                    description: options.description ?? `${type} resource ${name}`,
+                    agents,
+                }), "utf8");
+                await fs.writeFile(path.join(resourcePath, entry), this.getDefaultContent(type, name), "utf8");
+            }
+        }
+        return {
+            type,
+            name,
+            resourceDir: resourcePaths[0],
+            files,
+            dryRun: Boolean(options.dryRun),
+        };
     }
     async rename(type, oldName, newName, projectDir, options = {}) {
         this.validateRenameInput(type, oldName, newName);
@@ -636,6 +915,80 @@ export class ServiceFactory {
     resolveInstallMode(mode) {
         return mode === "link" ? "link" : "copy";
     }
+    reportPublishProgress(options, stage, message) {
+        options.onProgress?.({ stage, message });
+    }
+    async tryResolveProjectResourceTarget(projectDir, type, name) {
+        const locked = await this.getLockedResource(projectDir, type, name);
+        const configuredAgents = await this.getConfiguredAgents(projectDir);
+        if (locked?.agents?.length || configuredAgents?.length) {
+            const agents = locked?.agents?.length
+                ? normalizeAgents(locked.agents)
+                : (configuredAgents ?? normalizeAgents());
+            const linkPaths = getProjectResourcePaths(projectDir, type, name, agents);
+            const existingLinkPath = await this.findFirstExistingPath(linkPaths);
+            if (existingLinkPath) {
+                return {
+                    resourcePath: existingLinkPath,
+                    linkPaths,
+                    agents,
+                    mode: this.resolveInstallMode(locked?.mode ?? (await this.readPathMode(existingLinkPath))),
+                };
+            }
+        }
+        const existingCandidates = await this.findExistingAgentPaths(projectDir, type, name, "project");
+        if (existingCandidates.length === 0) {
+            return undefined;
+        }
+        const existingAgents = normalizeAgents(existingCandidates.map((candidate) => candidate.agent));
+        const linkPaths = getProjectResourcePaths(projectDir, type, name, existingAgents);
+        return {
+            resourcePath: existingCandidates[0].path,
+            linkPaths,
+            agents: existingAgents,
+            mode: await this.readPathMode(existingCandidates[0].path),
+        };
+    }
+    async tryResolveGlobalResourceTarget(projectDir, type, name) {
+        const existingCandidates = await this.findExistingAgentPaths(projectDir, type, name, "global");
+        if (existingCandidates.length === 0) {
+            return undefined;
+        }
+        const agents = normalizeAgents(existingCandidates.map((candidate) => candidate.agent));
+        const linkPaths = getGlobalResourcePaths(this.paths.getHomeDir(), type, name, agents);
+        return {
+            resourcePath: existingCandidates[0].path,
+            linkPaths,
+            agents,
+            mode: await this.readPathMode(existingCandidates[0].path),
+        };
+    }
+    async findExistingAgentPaths(projectDir, type, name, scope) {
+        const rootDir = scope === "global" ? this.paths.getHomeDir() : projectDir;
+        const candidates = getSupportedAgentNames().map((agent) => ({
+            agent,
+            path: scope === "global"
+                ? getGlobalResourcePaths(rootDir, type, name, [agent])[0]
+                : getProjectResourcePaths(rootDir, type, name, [agent])[0],
+        }));
+        const existingCandidates = [];
+        for (const candidate of candidates) {
+            if (await this.exists(candidate.path))
+                existingCandidates.push(candidate);
+        }
+        return existingCandidates;
+    }
+    async findFirstExistingPath(paths) {
+        for (const targetPath of paths) {
+            if (await this.exists(targetPath))
+                return targetPath;
+        }
+        return undefined;
+    }
+    async readPathMode(targetPath) {
+        const stat = await fs.lstat(targetPath);
+        return stat.isSymbolicLink() ? "link" : "copy";
+    }
     async resolveInstalledResource(projectDir, type, name) {
         const locked = await this.getLockedResource(projectDir, type, name);
         const configuredAgents = await this.getConfiguredAgents(projectDir);
@@ -816,6 +1169,13 @@ export class ServiceFactory {
             .filter(Boolean);
         return items.length > 0 ? items : undefined;
     }
+    errorCheck(name, message, error) {
+        return {
+            name,
+            status: "error",
+            message: `${message} ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
     async exists(targetPath) {
         try {
             await fs.access(targetPath);
@@ -830,6 +1190,10 @@ export class ServiceFactory {
         if (await this.exists(devPath)) {
             return devPath;
         }
+        const projectTarget = await this.tryResolveProjectResourceTarget(projectDir, type, name);
+        if (projectTarget) {
+            return projectTarget.resourcePath;
+        }
         const repoResourceDir = await this.getRepoResourceDir(type, name);
         if (await this.exists(repoResourceDir)) {
             return repoResourceDir;
@@ -857,6 +1221,15 @@ export class ServiceFactory {
     getDefaultEntry(type) {
         return type === "skill" ? "SKILL.md" : "content.md";
     }
+    getDefaultContent(type, name) {
+        if (type === "rule") {
+            return `# ${name}\n\nDescribe rule instructions here.\n`;
+        }
+        if (type === "command") {
+            return `# ${name}\n\nDescribe command behavior here.\n`;
+        }
+        return `# ${name}\n\nDescribe skill workflow here.\n`;
+    }
     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/mvp/README.md

@@ -53,23 +53,20 @@
 ### 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>`
+- 项目内资源直接在当前 agent 目标目录原地修改；若资源只存在于用户级全局目录，则复制到当前项目对应 agent 目标目录。
 
 ### 2.6 `publish`
 
-- `himan publish <type> <name> --patch|--minor|--major`（默认 patch，三选一）
-- 发布内容优先取项目 `.himan/dev/<type>/<name>`，否则取源仓库内对应资源目录。
+- `himan publish <type> <name> --patch|--minor|--major [--global]`（默认 patch，三选一）
+- 发布内容优先取旧版项目 `.himan/dev/<type>/<name>`，其次取当前项目 agent 目标目录，否则取源仓库内对应资源目录。
 - 新版本：基于已有 tag 最新 semver 递增；无任何历史时从 `0.0.0` 起算。
 - 写回源仓库、提交、打 tag、推送，并将该版本同步到本地 store。
-- 发布成功后，用新版本 store 以 copy 模式重新安装到项目目标、更新 lock，并删除对应 `.himan/dev/<type>/<name>`。
+- 发布过程展示阶段日志。发布成功后，用新版本 store 以 copy 模式重新安装；默认安装到项目目标并更新 lock，`--global` 安装到用户级目录且不写项目 lock。
 
 ### 2.7 `create`
 
 - `himan create <type> <name>` 及常用选项（描述、目标 agent、dry-run、force、json 等）
-- 生成 `rule` / `command` / `skill` 标准目录与 `himan.yaml`、入口模板
+- 在当前项目 agent 目标目录生成 `rule` / `command` / `skill` 标准目录与 `himan.yaml`、入口模板
 - 与 `publish` 衔接：`create → 编辑 → publish`
 
 ### 2.8 `agent`
@@ -103,7 +100,7 @@
 **项目目录：**
 - `.cursor` / `.claude` / `.agents` / `.openclaw`：按 agent 和资源类型保存运行态目标（软链或副本）
 - `.himan/config.json`：项目默认 agent 配置
-- `.himan/dev/<type>/<name>`：资源开发态可编辑副本
+- 当前项目 agent 目标目录：资源创建和开发态可编辑位置；旧版 `.himan/dev/<type>/<name>` 仍可作为 publish 输入
 
 **源仓库内资源布局：**
 - `rules/<name>/`、`commands/<name>/`、`skills/<name>/`，可含 `himan.yaml`，并包含约定入口文件（如 `content.md`、`SKILL.md`）。

package/docs/mvp/create-resource.md

@@ -58,10 +58,10 @@ repo/
 
 可用 `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` 会自动维护根目录文档：
+`create` 默认只在当前项目 agent 目标目录生成可验证资源；`publish` 会把项目目录中的资源同步回 source 仓库，并自动维护根目录文档：
 
 - `README.md`：只维护 `<!-- himan:resources:start -->` / `<!-- himan:resources:end -->` 标记内的资源索引；如果旧 README 没有标记，则在文件末尾追加受控资源索引区
-- `CHANGELOG.md`：向 `[Unreleased]` 写入资源变更；新增资源写入 `Added`，发布版本写入 `Changed`
+- `CHANGELOG.md`：向 `[Unreleased]` 写入发布版本的 `Changed` 条目
 
 推荐的 `README.md` 基本结构：
 
@@ -110,15 +110,15 @@ himan install rule code-review
 
 ## 4. 资源目录与元数据
 
-`create` 生成资源目录，结构示例：
+`create` 生成当前项目 agent 目标目录，结构示例：
 
 ```text
-repo/
-  rules/<name>/
+project/
+  .cursor/rules/<name>/
     content.md
-  commands/<name>/
+  .cursor/commands/<name>/
     content.md
-  skills/<name>/
+  .agents/skills/<name>/
     SKILL.md
 ```
 
@@ -143,7 +143,7 @@ agents:
 
 1. 读取本地配置，确认已初始化源
 2. 校验类型与资源名格式
-3. 解析目标路径 `rules|commands|skills/<name>`
+3. 解析当前项目 agent 目标路径，例如 `.agents/skills/<name>`
 4. 目录已存在且无 `--force` → 报错
 5. 生成 `himan.yaml` 与入口模板（`--dry-run` 则不落盘）
 6. 终端或 `--json` 输出结果；下一步由用户编辑再 `publish`
@@ -178,17 +178,17 @@ agents:
 ## 9. 与资源工作流衔接
 
 ```text
-create → edit → publish
+create → edit in project agent folder → publish
 ```
 
-`create` 会在当前 Git source 缓存仓库中生成资源目录；用户编辑该目录后执行 `publish`。资源已有发布版本并安装到项目后，可再进入 `dev` 工作流：
+`create` 会在当前项目 agent 目标目录中生成资源目录；用户编辑并验证该目录后执行 `publish`。资源已有发布版本并安装到项目后，可再进入 `dev` 工作流，直接在项目 agent 目标目录原地修改：
 
 ```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/
+# 编辑 .cursor/rules/code-review/ 或当前默认 agent 对应目录
 himan publish rule code-review --patch
 ```
 

package/docs/mvp/impl.md

@@ -14,7 +14,7 @@
 **原则：**
 
 - 本地 store 按版本存放，已存在的版本目录不被覆盖（安装时复用缓存）
-- 开发目录 `.himan/dev` 与运行态 agent 目录（`.cursor` / `.claude` / `.agents` / `.openclaw`）分离
+- 创建和开发默认直接使用运行态 agent 目录（`.cursor` / `.claude` / `.agents` / `.openclaw`），旧版 `.himan/dev` 目录仅作为兼容发布输入
 - 正式发布版本以 **Git Tag** 为唯一事实来源；`himan.yaml` 中的 version 在发布时会与 tag 对齐
 
 ---
@@ -49,21 +49,21 @@
 ### 2.5 `dev <type> <name>`
 
 - 命令层接受 `rule|command|skill`；依赖已安装（能解析当前安装目标）
-- 将当前安装内容复制到 `.himan/dev/<type>/<name>`（目录已存在则默认不覆盖）
-- 按安装模式将项目目标更新为 dev 目录的软链或副本
+- 当前项目已存在资源时直接返回项目 agent 目标目录，用户原地修改
+- 当前项目不存在但用户级全局目录存在时，将全局资源复制到当前项目对应 agent 目标目录
 
 ### 2.6 `publish <type> <name>`
 
-- 发布源：优先项目 `.himan/dev/<type>/<name>`，否则缓存仓库内该资源目录
+- 发布源：优先旧版项目 `.himan/dev/<type>/<name>`，其次当前项目 agent 目标目录，否则缓存仓库内该资源目录
 - 下一版本：基于历史最新 tag；无历史则从 `0.0.0` 按 patch/minor/major 递增
 - 将内容同步回缓存仓库中的规范路径，更新元数据中的版本字段，提交、打 tag、推送
 - 将新 tag 对应内容拉取到 store 新版本目录
-- 用新版本 store 以 copy 模式重新安装项目内对应类型目标，更新 lock，并删除对应 `.himan/dev/<type>/<name>` 开发目录
+- 发布过程展示阶段日志；用新版本 store 以 copy 模式重新安装。默认安装到项目内对应类型目标并更新 lock，`--global` 安装到用户级目标且不写项目 lock
 
 ### 2.7 `create <type> <name>`
 
 - 校验类型与资源命名规则
-- 在缓存仓库中创建 `rules|commands|skills/<name>` 及 `himan.yaml`、入口模板
+- 在当前项目 agent 目标目录创建 `rules|commands|skills/<name>` 及 `himan.yaml`、入口模板
 - 支持覆盖、试运行、JSON 输出；创建后不自动发布
 
 ### 2.8 `agent`

package/package.json

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