@hi-man/himan 0.1.0 → 0.2.2

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,33 +1,57 @@
 {
   "name": "@hi-man/himan",
-  "version": "0.1.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",
     "registry": "https://registry.npmjs.org/"
   },
   "bin": {
-    "himan": "dist/index.js"
+    "himan": "dist/bin/himan.js",
+    "himan-source": "dist/bin/himan-source.js",
+    "himan-resource": "dist/bin/himan-resource.js",
+    "himan-project": "dist/bin/himan-project.js"
   },
   "scripts": {
+    "clean": "rm -rf dist",
+    "prebuild": "rm -rf dist",
     "build": "tsc -p tsconfig.json",
-    "dev": "tsx src/index.ts",
+    "dev": "tsx src/bin/himan.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",