@hi-man/himan 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on Keep a Changelog, and this project follows semver for the
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-05-14
+
+### Fixed
+
+- Fixed `himan-skill-metadata` so newly generated skill metadata starts at version `0.0.1`.
+
+## [0.5.0] - 2026-05-14
+
+### Added
+
+- Added `himan resource archive` and `himan resource restore` for moving source resources into `archive/<plural>/<name>`, listing archived resources, and explicitly installing archived history with `--include-archived`.
+- Added the `himan-resource-manage` skill for creating, editing, validating, and publishing Himan resources from project agent folders.
+
+### Changed
+
+- Changed `himan doctor` to warn when a project lock references resources archived in its recorded source.
+
 ## [0.4.1] - 2026-05-14
 
 ### Added

package/README.md

@@ -98,11 +98,19 @@ your-himan-source/
     my-skill/
       himan.yaml
       SKILL.md
+  archive/
+    rules/
+      old-rule/
+        himan.yaml
+        content.md
+    commands/
+    skills/
 ```
 
 - `README.md`：source 仓库入口文档，建议记录资源目录说明、推荐安装方式、默认 agent 策略、常用资源索引和维护约定。
 - `CHANGELOG.md`：source 仓库级变更记录，建议记录新增、变更、废弃、移除的资源，以及重要版本发布说明。
 - `rules/`、`commands/`、`skills/`：按资源类型分组；每个子目录是一份 himan 资源。
+- `archive/rules/`、`archive/commands/`、`archive/skills/`：归档资源目录；默认列表、文档索引和 source sync 不把它们视为 active 资源。
 - `himan.yaml`：可选资源元数据；存在时供 himan 扫描、校验、读取入口和默认 agent；skill 资源可包含 `analysis` 静态分析信息。
 - `content.md` / `SKILL.md`：资源主入口；没有 `himan.yaml` 时，`rule` / `command` 默认使用 `content.md`，`skill` 默认使用 `SKILL.md`。
 
@@ -176,9 +184,11 @@ analysis:
 
 | 命令                             | 说明                                                                                |
 | -------------------------------- | ----------------------------------------------------------------------------------- |
-| `list [type] [--agent a,b] [--brief] [--installed] [--json]` | 默认列出当前 default source 的资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源 |
+| `list [type] [--agent a,b] [--brief] [--installed] [--archived] [--include-archived] [--json]` | 默认列出当前 default source 的 active 资源；未传 `type` 时按 `rule`/`command`/`skill` 分组展示全部资源；可按 agent 过滤；默认显示描述，`--brief` 可隐藏描述；`--installed` 改为查看当前项目 `himan.lock` 中的已安装资源；`--archived` 只看归档资源，`--include-archived` 同时展示 active 和归档资源 |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
 | `create <type> <name>`           | 在当前项目 agent 目录创建脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
+| `archive <type> <name>`          | 将当前 default source 中的资源移动到 `archive/<plural>/<name>`；常用选项：`--reason`、`--dry-run`、`--json` |
+| `restore <type> <name>`          | 将归档资源恢复回 active 类型目录；常用选项：`--dry-run`、`--json` |
 | `rename <type> <old-name> <new-name>` | 暂不推荐使用；重命名当前 default source 中的资源；常用选项：`--dry-run`、`--no-project`、`--json` |
 
 ### 3) project（当前项目）
@@ -186,7 +196,7 @@ 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 或安装模式 |
+| `install [type] [name[@version]] [--global] [--agent a,b] [--mode link\|copy] [--include-archived]` | 有参数时从当前 default source 安装指定资源；**无参数**时按 `himan.lock` 记录的 source 批量安装；加 `--global` 时安装到用户级 agent 目录且不写项目 lock；可覆盖安装目标 agent 或安装模式；归档资源必须显式传 `--include-archived` 才能按历史版本安装 |
 | `dev <type> <name>`               | 切换到开发态；项目资源原地编辑，全局资源先复制到当前项目目标目录 |
 | `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
 | `publish <type> <name> [--global]` | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个）；发布后默认安装到当前项目并更新 lock，`--global` 安装到用户级目录 |
@@ -204,12 +214,12 @@ analysis:
 
 | 命令 | 说明 |
 |------|------|
-| `doctor [--json]` | 检查 Node/Git、Himan home、当前 source、资源扫描、默认 agent、项目 lock 和已安装目标；存在 error 时以非零状态退出 |
+| `doctor [--json]` | 检查 Node/Git、Himan home、当前 source、资源扫描、默认 agent、项目 lock、归档资源引用和已安装目标；存在 error 时以非零状态退出 |
 
 也可使用分组命令（与上面等价）：
 
-- `himan resource list|history|create|rename ...`
-- `himan-resource list|history|create|rename ...`（兼容保留：也可执行 install/dev/uninstall/publish）
+- `himan resource list|history|create|archive|restore|rename ...`
+- `himan-resource list|history|create|archive|restore|rename ...`（兼容保留：也可执行 install/dev/uninstall/publish）
 - `himan project list|install|dev|uninstall|publish ...`
 - `himan-project list|install|dev|uninstall|publish ...`
 - `himan agent list|use|current|clear ...`
@@ -222,6 +232,8 @@ analysis:
 
 `rename` 暂不推荐使用。该命令会移动 source 仓库里的资源目录并更新资源 metadata 名称、README 资源索引和 CHANGELOG。已有发布 tag 不会被改写；若旧资源已有历史版本，rename 会为新名字创建一个指向当前最新版本的 tag。默认会迁移当前项目中对应的安装目标、`.himan/dev` 副本和 lock 条目；传 `--no-project` 时只改 source。对于 skill，命令只自动更新 metadata / front matter 中的精确 `name` 字段，不会自动替换 `SKILL.md` 正文中的旧名称引用。
 
+`archive` 是 source 级软下线操作：它把资源目录移动到 `archive/<plural>/<name>`，从默认 `list`、source README 资源索引和 `source sync` 的 active 快照中移除，并在 `CHANGELOG.md` 记录归档事件；已有 Git tag、本地 store、项目安装目录和 `himan.lock` 不会被删除。直接安装归档资源会返回 `E_RESOURCE_ARCHIVED`，需要显式加 `--include-archived`；无参数 `himan install` 仍会按 lock 恢复已记录的归档资源。`doctor` 会对 lock 中引用归档资源的项目给出 warning。`restore` 会把资源从 archive 目录移回 active 类型目录。
+
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
 
 多源说明：当前是「**多来源可配置，单来源生效**」模型。显式资源命令（`list/install <type> .../history/dev/publish/rename`）作用于当前 default source；`himan install` 无参数恢复时使用 `himan.lock` 中记录的 source。

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

@@ -5,8 +5,10 @@ export class ResourceScanner {
     async scanRules(repoDir) {
         return this.scanByType(repoDir, "rule");
     }
-    async scanByType(repoDir, type) {
-        const baseDir = path.join(repoDir, this.getTypeDir(type));
+    async scanByType(repoDir, type, options = {}) {
+        const baseDir = options.archived
+            ? path.join(repoDir, "archive", this.getTypeDir(type))
+            : path.join(repoDir, this.getTypeDir(type));
         const hasBaseDir = await this.exists(baseDir);
         if (!hasBaseDir)
             return [];
@@ -32,16 +34,23 @@ export class ResourceScanner {
                     agents: Array.isArray(parsed.agents)
                         ? (parsed.agents ?? [])
                         : (parsed.targets ?? []),
+                    ...(options.archived
+                        ? {
+                            archived: true,
+                            archivedAt: this.readStringMetadata(parsed, "archivedAt"),
+                            archiveReason: this.readStringMetadata(parsed, "archiveReason"),
+                        }
+                        : {}),
                 });
                 continue;
             }
-            const inferred = await this.inferResourceMeta(path.join(baseDir, resourceDir.name), resourceDir.name, type);
+            const inferred = await this.inferResourceMeta(path.join(baseDir, resourceDir.name), resourceDir.name, type, options);
             if (inferred)
                 result.push(inferred);
         }
         return result;
     }
-    async inferResourceMeta(resourceDir, dirName, type) {
+    async inferResourceMeta(resourceDir, dirName, type, options) {
         const entry = this.getDefaultEntry(type);
         const entryPath = path.join(resourceDir, entry);
         if (!(await this.exists(entryPath)))
@@ -55,6 +64,7 @@ export class ResourceScanner {
             agents: this.readStringArrayMetadata(metadata, "agents") ??
                 this.readStringArrayMetadata(metadata, "targets") ??
                 [],
+            ...(options.archived ? { archived: true } : {}),
         };
     }
     async readSkillFrontMatter(skillPath) {

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

@@ -24,19 +24,31 @@ export class GitSourceAdapter {
         this.sourceConfig = sourceConfig;
         await this.repoManager.cloneOrFetch(sourceConfig.repo, sourceConfig.repoDir);
     }
-    async list(type) {
+    async list(type, options = {}) {
         const repoDir = this.getRepoDir();
+        if (options.archived) {
+            return this.scanner.scanByType(repoDir, type, { archived: true });
+        }
         const repoId = this.sourceConfig?.repoId ?? "default";
         const typeDir = this.getTypeDir(type);
         const baseDir = path.join(repoDir, typeDir);
         const metadataHash = await this.getResourceMetadataHash(baseDir, type);
         const cached = await this.indexStore.get(repoId, type);
+        let active;
         if (cached && cached.metadataHash === metadataHash) {
-            return cached.resources;
+            active = cached.resources;
+        }
+        else {
+            active = await this.scanner.scanByType(repoDir, type);
+            await this.indexStore.upsert(repoId, type, metadataHash, active);
+        }
+        if (!options.includeArchived) {
+            return active;
         }
-        const scanned = await this.scanner.scanByType(repoDir, type);
-        await this.indexStore.upsert(repoId, type, metadataHash, scanned);
-        return scanned;
+        const archived = await this.scanner.scanByType(repoDir, type, {
+            archived: true,
+        });
+        return [...active, ...archived].sort((a, b) => a.name.localeCompare(b.name));
     }
     async history(type, name) {
         const tags = await this.repoManager.listTags(this.getRepoDir(), `${type}/${name}@*`);
@@ -46,6 +58,9 @@ export class GitSourceAdapter {
             .sort((a, b) => semver.rcompare(a.version, b.version));
         return versions;
     }
+    async isArchived(type, name) {
+        return this.exists(path.join(this.getRepoDir(), "archive", this.getTypeDir(type), name));
+    }
     async pull(type, name, version, targetDir) {
         const tag = `${type}/${name}@${version}`;
         await this.repoManager.archiveResource(this.getRepoDir(), tag, `${type}s/${name}`, targetDir);
@@ -175,6 +190,101 @@ export class GitSourceAdapter {
             dryRun: false,
         };
     }
+    async archive(type, name, options = {}) {
+        const repoDir = this.getRepoDir();
+        const typeDir = this.getTypeDir(type);
+        const previousResourceDir = path.join(repoDir, typeDir, name);
+        const archiveDir = path.join(repoDir, "archive", typeDir, name);
+        const archiveReason = this.normalizeArchiveReason(options.reason);
+        const archivedAt = new Date().toISOString();
+        if (!(await this.exists(previousResourceDir))) {
+            if (await this.exists(archiveDir)) {
+                throw new HimanError(errorCodes.RESOURCE_ARCHIVED, `Resource already archived: ${type}/${name}`);
+            }
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
+        }
+        if (await this.exists(archiveDir)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Archived resource already exists: ${type}/${name}`);
+        }
+        if (options.dryRun) {
+            return {
+                type,
+                name,
+                previousResourceDir,
+                archiveDir,
+                archivedAt,
+                archiveReason,
+                committed: false,
+                dryRun: true,
+            };
+        }
+        await this.markArchivedResourceMetadata(previousResourceDir, type, name, archivedAt, archiveReason);
+        await fs.mkdir(path.dirname(archiveDir), { recursive: true });
+        await fs.rename(previousResourceDir, archiveDir);
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Deprecated",
+            line: archiveReason
+                ? `- Archived \`${type}/${name}\`: ${archiveReason}.`
+                : `- Archived \`${type}/${name}\`.`,
+        });
+        const committed = await this.repoManager.commitAndPush(repoDir, `archive ${type}/${name}`, undefined, [
+            path.relative(repoDir, previousResourceDir),
+            path.relative(repoDir, archiveDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ]);
+        return {
+            type,
+            name,
+            previousResourceDir,
+            archiveDir,
+            archivedAt,
+            archiveReason,
+            committed,
+            dryRun: false,
+        };
+    }
+    async restore(type, name, options = {}) {
+        const repoDir = this.getRepoDir();
+        const typeDir = this.getTypeDir(type);
+        const previousArchiveDir = path.join(repoDir, "archive", typeDir, name);
+        const resourceDir = path.join(repoDir, typeDir, name);
+        if (!(await this.exists(previousArchiveDir))) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Archived resource not found: ${type}/${name}`);
+        }
+        if (await this.exists(resourceDir)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
+        }
+        if (options.dryRun) {
+            return {
+                type,
+                name,
+                previousArchiveDir,
+                resourceDir,
+                committed: false,
+                dryRun: true,
+            };
+        }
+        await this.clearArchivedResourceMetadata(previousArchiveDir, type, name);
+        await fs.mkdir(path.dirname(resourceDir), { recursive: true });
+        await fs.rename(previousArchiveDir, resourceDir);
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Changed",
+            line: `- Restored \`${type}/${name}\` from archive.`,
+        });
+        const committed = await this.repoManager.commitAndPush(repoDir, `restore ${type}/${name}`, undefined, [
+            path.relative(repoDir, previousArchiveDir),
+            path.relative(repoDir, resourceDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ]);
+        return {
+            type,
+            name,
+            previousArchiveDir,
+            resourceDir,
+            committed,
+            dryRun: false,
+        };
+    }
     async initDocs(options = {}) {
         const repoDir = this.getRepoDir();
         const files = [
@@ -299,6 +409,44 @@ export class GitSourceAdapter {
         const updated = `---\n${frontMatter}\n---\n${raw.slice(match[0].length)}`;
         await fs.writeFile(skillPath, updated, "utf8");
     }
+    normalizeArchiveReason(reason) {
+        const trimmed = reason?.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    async markArchivedResourceMetadata(resourceDir, type, name, archivedAt, archiveReason) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (!(await this.exists(yamlPath)))
+            return;
+        const parsed = await this.readResourceYamlObject(yamlPath, type, name);
+        await fs.writeFile(yamlPath, YAML.stringify({
+            ...parsed,
+            archived: true,
+            archivedAt,
+            ...(archiveReason ? { archiveReason } : {}),
+        }), "utf8");
+    }
+    async clearArchivedResourceMetadata(resourceDir, type, name) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (!(await this.exists(yamlPath)))
+            return;
+        const parsed = await this.readResourceYamlObject(yamlPath, type, name);
+        const { archived: _archived, archivedAt: _archivedAt, archiveReason: _archiveReason, ...rest } = parsed;
+        await fs.writeFile(yamlPath, YAML.stringify(rest), "utf8");
+    }
+    async readResourceYamlObject(yamlPath, type, name) {
+        const raw = await fs.readFile(yamlPath, "utf8");
+        let parsed;
+        try {
+            parsed = YAML.parse(raw);
+        }
+        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 });
+        }
+        return parsed;
+    }
     async validatePublishResource(type, name, resourceDir) {
         const yamlPath = path.join(resourceDir, "himan.yaml");
         if (!(await this.exists(yamlPath))) {
@@ -785,7 +933,12 @@ export class GitSourceAdapter {
         return found === -1 ? lines.length : found;
     }
     findChangelogSectionInsertIndex(lines, unreleasedIndex, blockEnd, section) {
-        const sectionOrder = ["Added", "Changed"];
+        const sectionOrder = [
+            "Added",
+            "Changed",
+            "Deprecated",
+            "Removed",
+        ];
         const sectionRank = sectionOrder.indexOf(section);
         for (let index = unreleasedIndex + 1; index < blockEnd; index += 1) {
             const line = lines[index].trim();

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

@@ -3,12 +3,15 @@ export class RegistrySourceAdapter {
     async init(_sourceConfig) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
-    async list(_type) {
+    async list(_type, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
     async history(_type, _name) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async isArchived(_type, _name) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
     async pull(_type, _name, _version, _targetDir) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
@@ -21,6 +24,12 @@ export class RegistrySourceAdapter {
     async rename(_type, _oldName, _newName, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async archive(_type, _name, _options) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
+    async restore(_type, _name, _options) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
     async initDocs(_options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }

package/dist/cli/builders.js

@@ -65,10 +65,12 @@ Command groups:
            init, source init, source add, source use, source list,
            source init-docs, source clone, source sync
   resource Source resource discovery and metadata
-           list, list --installed, history, create, rename (not recommended yet),
-           resource list, resource history, resource create, resource rename
+           list, list --archived, list --installed, history, create,
+           archive, restore, rename (not recommended yet),
+           resource list, resource history, resource create,
+           resource archive, resource restore, resource rename
   project  Resource usage lifecycle in current project or user-level agent dirs
-           list, install, dev, uninstall, publish,
+           list, install, install --include-archived, dev, uninstall, publish,
            project list, project install, project dev, project uninstall, project publish
   agent    Default agent configuration
            agent list, agent use, agent current, agent clear

package/dist/cli/project-commands.js

@@ -39,12 +39,16 @@ export function registerProjectCommands(command, services, options = {}) {
         .option("--agent <list>", "install target agents, comma separated")
         .option("--mode <mode>", "install mode: link or copy")
         .option("--global", "install into user-level agent directories")
+        .option("--include-archived", "allow installing an archived resource explicitly")
         .description("Install resource, or install from himan.lock")
         .action(async (type, nameVersion, options) => {
         await runAction(async () => {
             const agents = parseAgents(options.agent);
             const mode = parseInstallMode(options.mode);
             if (!type && !nameVersion) {
+                if (options.includeArchived) {
+                    throw new HimanError(errorCodes.CLI_USAGE, "--include-archived only applies to single-resource install.");
+                }
                 if (options.global) {
                     throw new HimanError(errorCodes.CLI_USAGE, "Global install requires a resource:\n"
                         + "  - himan install <type> <name[@version]> --global [--mode link|copy]");
@@ -68,8 +72,8 @@ export function registerProjectCommands(command, services, options = {}) {
             const resourceType = ensureResourceType(type);
             const { name, version } = parseNameVersion(nameVersion);
             const result = options.global
-                ? await services.installGlobal(resourceType, name, version, process.cwd(), agents, mode)
-                : await services.install(resourceType, name, version, process.cwd(), agents, mode);
+                ? await services.installGlobal(resourceType, name, version, process.cwd(), agents, mode, { includeArchived: options.includeArchived })
+                : await services.install(resourceType, name, version, process.cwd(), agents, mode, { includeArchived: options.includeArchived });
             process.stdout.write(`Installed ${options.global ? "global " : ""}${result.type}/${result.name}@${result.version}\n`);
         });
     });

package/dist/cli/resource-commands.js

@@ -10,18 +10,30 @@ export function registerResourceCommands(command, services) {
         .option("--agent <list>", "agent list filter, comma separated")
         .option("--brief", "hide resource descriptions")
         .option("--installed", "list resources installed in current project")
+        .option("--archived", "list archived resources only")
+        .option("--include-archived", "include archived resources in source list")
         .option("--json", "output json format")
         .description("List resources from current default source or project installs")
         .action(async (type, options) => {
         await runAction(async () => {
             const agents = parseAgents(options.agent);
             const showDescription = !options.brief;
+            if (options.installed && (options.archived || options.includeArchived)) {
+                throw new HimanError(errorCodes.CLI_USAGE, "--archived and --include-archived only apply to source resource lists.");
+            }
+            if (options.archived && options.includeArchived) {
+                throw new HimanError(errorCodes.CLI_USAGE, "Use only one of --archived or --include-archived.");
+            }
+            const listOptions = {
+                archived: Boolean(options.archived),
+                includeArchived: Boolean(options.includeArchived),
+            };
             if (options.installed) {
                 await writeInstalledList(services, type, agents, Boolean(options.json));
                 return;
             }
             if (!type) {
-                const groups = await listGroupedResources(services, agents);
+                const groups = await listGroupedResources(services, agents, listOptions);
                 if (options.json) {
                     process.stdout.write(`${JSON.stringify(formatResourceGroups(groups, showDescription), null, 2)}\n`);
                     return;
@@ -30,7 +42,7 @@ export function registerResourceCommands(command, services) {
                 return;
             }
             const resourceType = ensureResourceType(type);
-            const resources = await services.list(resourceType, agents);
+            const resources = await services.list(resourceType, agents, listOptions);
             if (options.json) {
                 process.stdout.write(`${JSON.stringify(formatResources(resources, showDescription), null, 2)}\n`);
                 return;
@@ -91,6 +103,48 @@ export function registerResourceCommands(command, services) {
             process.stdout.write(`Created ${result.type}/${result.name} at ${result.resourceDir}${result.dryRun ? " (dry-run)" : ""}\n`);
         });
     });
+    command
+        .command("archive")
+        .argument("<type>", "resource type")
+        .argument("<name>", "resource name")
+        .option("--reason <text>", "archive reason")
+        .option("--dry-run", "show archive result without writing")
+        .option("--json", "output json format")
+        .description("Archive resource in current default source")
+        .action(async (type, name, options) => {
+        await runAction(async () => {
+            const resourceType = ensureResourceType(type);
+            const result = await services.archive(resourceType, name, {
+                reason: options.reason,
+                dryRun: options.dryRun,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Archived ${result.type}/${result.name}${result.dryRun ? " (dry-run)" : ""}\n`);
+        });
+    });
+    command
+        .command("restore")
+        .argument("<type>", "resource type")
+        .argument("<name>", "resource name")
+        .option("--dry-run", "show restore result without writing")
+        .option("--json", "output json format")
+        .description("Restore archived resource into current default source")
+        .action(async (type, name, options) => {
+        await runAction(async () => {
+            const resourceType = ensureResourceType(type);
+            const result = await services.restore(resourceType, name, {
+                dryRun: options.dryRun,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Restored ${result.type}/${result.name}${result.dryRun ? " (dry-run)" : ""}\n`);
+        });
+    });
     command
         .command("rename")
         .argument("<type>", "resource type")
@@ -139,11 +193,11 @@ function ensureResourceType(type) {
     }
     return type;
 }
-async function listGroupedResources(services, agents) {
+async function listGroupedResources(services, agents, options = {}) {
     return {
-        rule: await services.list("rule", agents),
-        command: await services.list("command", agents),
-        skill: await services.list("skill", agents),
+        rule: await services.list("rule", agents, options),
+        command: await services.list("command", agents, options),
+        skill: await services.list("skill", agents, options),
     };
 }
 function formatResourceGroups(groups, showDescription) {
@@ -181,7 +235,8 @@ function writeResourceList(resources, showDescription) {
         return;
     }
     for (const resource of resources) {
-        process.stdout.write(`- ${resource.type}/${resource.name}${showDescription && resource.description ? `: ${resource.description}` : ""}\n`);
+        const archived = resource.archived ? " [archived]" : "";
+        process.stdout.write(`- ${resource.type}/${resource.name}${archived}${showDescription && resource.description ? `: ${resource.description}` : ""}\n`);
     }
 }
 function formatGroupTitle(type) {

package/dist/services/index.js

@@ -213,6 +213,7 @@ export class ServiceFactory {
         checks.push(await this.checkAgents(projectDir));
         const lockCheck = await this.checkProjectLock(projectDir);
         checks.push(lockCheck.check);
+        checks.push(await this.checkProjectArchiveStatus(lockCheck.lock));
         checks.push(await this.checkProjectTargets(projectDir, lockCheck.lock));
         return {
             ok: !checks.some((check) => check.status === "error"),
@@ -362,6 +363,44 @@ export class ServiceFactory {
             lock,
         };
     }
+    async checkProjectArchiveStatus(lock) {
+        if (!lock || lock.resources.length === 0) {
+            return {
+                name: "archive",
+                status: "ok",
+                message: "No locked resources to check for archive status.",
+            };
+        }
+        try {
+            const source = await this.loadSourceFromLock(this.normalizeLockSourceInfo(lock.source));
+            const archived = [];
+            for (const resource of lock.resources) {
+                if (await source.isArchived(resource.type, resource.name)) {
+                    archived.push(`${resource.type}/${resource.name}@${resource.version}`);
+                }
+            }
+            if (archived.length > 0) {
+                return {
+                    name: "archive",
+                    status: "warn",
+                    message: `${archived.length} locked resources are archived in the current source.`,
+                    details: { resources: archived },
+                };
+            }
+            return {
+                name: "archive",
+                status: "ok",
+                message: "No locked resources are archived in the current source.",
+            };
+        }
+        catch (error) {
+            return {
+                name: "archive",
+                status: "warn",
+                message: `Cannot check archived resources. ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
     async checkProjectTargets(projectDir, lock) {
         if (!lock || lock.resources.length === 0) {
             return {
@@ -397,14 +436,27 @@ export class ServiceFactory {
             message: "All locked project targets exist.",
         };
     }
-    async list(type, agents) {
+    async list(type, agents, options = {}) {
         const source = await this.loadSourceFromConfig();
-        const resources = await source.list(type);
+        const resources = await source.list(type, options);
         if (!agents?.length)
             return resources;
         const selected = normalizeAgents(agents);
         return resources.filter((resource) => normalizeAgents(resource.agents).some((agent) => selected.includes(agent)));
     }
+    async archive(type, name, options = {}) {
+        this.validateResourceIdentity(type, name, "archive");
+        const source = await this.loadSourceFromConfig();
+        return source.archive(type, name, {
+            ...options,
+            reason: options.reason?.trim(),
+        });
+    }
+    async restore(type, name, options = {}) {
+        this.validateResourceIdentity(type, name, "restore");
+        const source = await this.loadSourceFromConfig();
+        return source.restore(type, name, options);
+    }
     async listInstalled(projectDir, type, agents) {
         const { lock, state } = await this.lockStore.loadWithState(projectDir);
         if (state === "invalid") {
@@ -431,13 +483,13 @@ export class ServiceFactory {
         const source = await this.loadSourceFromConfig();
         return source.history(type, name);
     }
-    async install(type, name, version, projectDir, agents, mode = "copy") {
+    async install(type, name, version, projectDir, agents, mode = "copy", options = {}) {
         const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
-        return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
+        return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, "project", options);
     }
-    async installGlobal(type, name, version, projectDir, agents, mode = "copy") {
+    async installGlobal(type, name, version, projectDir, agents, mode = "copy", options = {}) {
         const source = await this.loadSourceFromConfig();
-        return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
+        return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global", options);
     }
     async dev(type, name, projectDir) {
         const projectTarget = await this.tryResolveProjectResourceTarget(projectDir, type, name);
@@ -484,6 +536,9 @@ export class ServiceFactory {
         const installScope = options.installScope ?? "project";
         this.reportPublishProgress(options, "prepare", `Preparing ${type}/${name}.`);
         const source = await this.loadSourceFromConfig();
+        if (await source.isArchived(type, name)) {
+            throw new HimanError(errorCodes.RESOURCE_ARCHIVED, `Resource is archived: ${type}/${name}. Restore it before publishing a new version.`);
+        }
         const sourceDir = await this.resolvePublishSourceDir(type, name, projectDir);
         const existingInstallInfo = await this.tryResolveInstalledResource(projectDir, type, name);
         const existingGlobalInstallInfo = await this.tryResolveGlobalResourceTarget(projectDir, type, name);
@@ -632,12 +687,16 @@ export class ServiceFactory {
         const lockSourceInfo = this.normalizeLockSourceInfo(lock.source);
         const lockedSource = await this.loadSourceFromLock(lockSourceInfo);
         for (const item of lock.resources) {
-            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode), "project");
+            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode), "project", { includeArchived: true });
             results.push(result);
         }
         return results;
     }
-    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, scope = "project") {
+    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, scope = "project", options = {}) {
+        const archived = await source.isArchived(type, name);
+        if (archived && !options.includeArchived) {
+            throw new HimanError(errorCodes.RESOURCE_ARCHIVED, `Resource is archived: ${type}/${name}. Use --include-archived to install an archived version explicitly.`);
+        }
         const history = await source.history(type, name);
         if (history.length === 0) {
             throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
@@ -1241,6 +1300,14 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.TEMPLATE_NOT_FOUND, `Template not found: ${options.template}`);
         }
     }
+    validateResourceIdentity(type, name, action) {
+        if (!["rule", "command", "skill"].includes(type)) {
+            throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for ${action}: ${type}`);
+        }
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+            throw new HimanError(errorCodes.INVALID_RESOURCE_NAME, `Invalid resource name: ${name}. Use kebab-case only.`);
+        }
+    }
     validateRenameInput(type, oldName, newName) {
         if (!["rule", "command", "skill"].includes(type)) {
             throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for rename: ${type}`);

package/dist/utils/errors.js

@@ -13,6 +13,7 @@ export const errorCodes = {
     NOT_IMPLEMENTED: "E_NOT_IMPLEMENTED",
     INVALID_INPUT: "E_INVALID_INPUT",
     RESOURCE_NOT_FOUND: "E_RESOURCE_NOT_FOUND",
+    RESOURCE_ARCHIVED: "E_RESOURCE_ARCHIVED",
     VERSION_NOT_FOUND: "E_VERSION_NOT_FOUND",
     INSTALL_NOT_FOUND: "E_INSTALL_NOT_FOUND",
     LOCK_NOT_FOUND: "E_LOCK_NOT_FOUND",

package/docs/error-codes.md

@@ -58,6 +58,12 @@
 - **常见触发**：安装不存在的资源、切换到不存在的 source 名称、发布目标资源不存在。
 - **建议处理**：先执行 `himan list <type>` / `himan source list` 确认名称。
 
+### `E_RESOURCE_ARCHIVED`
+
+- **含义**：资源已归档，默认不允许作为 active 资源继续使用。
+- **常见触发**：直接安装或发布已归档资源，或重复归档已经在 `archive/<plural>/<name>` 下的资源。
+- **建议处理**：如需继续维护，先执行 `himan resource restore <type> <name>`；如只需安装历史版本，显式传 `--include-archived`。
+
 ### `E_VERSION_NOT_FOUND`
 
 - **含义**：指定版本不存在。

package/package.json

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