@hi-man/himan 0.1.0 → 0.2.0

package/README.md

@@ -13,7 +13,13 @@ pnpm run build
 
 - 已全局安装本包：`himan <子命令>`
 - 本地开发：`pnpm run dev -- <子命令>`
-- 或直接：`node dist/index.js <子命令>`
+- 或直接：`node dist/bin/himan.js <子命令>`
+
+也支持两个独立入口：
+
+- `himan-source <子命令>`（source 相关）
+- `himan-resource <子命令>`（resource/project 相关）
+- `himan-project <子命令>`（project 相关）
 
 下文用 `himan` 代指上述入口。
 
@@ -22,6 +28,7 @@ pnpm run build
 ```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 dev rule my-rule
 # 编辑项目下 .himan/dev/rule/my-rule/
@@ -29,15 +36,18 @@ himan publish rule my-rule --patch
 ```
 
 - **rule / command / skill**：都支持 `create`、`list`、`history`、`install`、`dev`、`publish`、`uninstall`。
-- 安装后项目链接位置：
-  - `rule` -> `.cursor/rules/<name>`
-  - `command` -> `.cursor/commands/<name>`
-  - `skill` -> `.cursor/skills/<name>`
+- 安装后项目目标位置（按 `agents`，默认 `cursor`）：
+  - `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>`
 - 开发态目录：
   - `rule` -> `.himan/dev/rule/<name>`
   - `command` -> `.himan/dev/command/<name>`
   - `skill` -> `.himan/dev/skill/<name>`
 - lock 文件：`install <type> <name[@version]>` 会写入 `himan.lock`；`himan install`（无参数）会按 lock 批量恢复安装。
+- 安装模式：默认 `--mode link` 使用软链；也可用 `--mode copy` 将资源复制到目标 agent 目录，lock 会记录并复现该模式。
+- 默认 agent：`agent use <agent>` 默认写当前项目 `.himan/config.json`；加 `--global` 写入 `~/.himan/config.json`。当前项目配置优先于全局配置。
 
 版本以 Git tag 为准，格式：`rule/my-rule@1.0.0`。更多设计见 [docs/mvp](./docs/mvp/README.md)。
 
@@ -51,24 +61,52 @@ himan publish rule my-rule --patch
 | `source add <name> <git_url>` | 添加命名 Git 源                                    |
 | `source use <name>`           | 切换默认源                                          |
 | `source list [--json]`        | 查看已配置源（标记当前 default）                     |
+| `source init <git_url>`       | 与 `init` 等价，便于统一走 `himan source ...` 入口     |
+
+等价独立命令：
+
+- `himan-source init <git_url>`
+- `himan-source add <name> <git_url>`
+- `himan-source use <name>`
+- `himan-source list [--json]`
 
 ### 2) resource（资源）
 
 | 命令                             | 说明                                                                                |
 | -------------------------------- | ----------------------------------------------------------------------------------- |
-| `list [type] [--json]`           | 列出当前 default source 的资源；`type` 为 `rule` / `command` / `skill`，默认 `rule` |
+| `list [type] [--agent a,b] [--json]` | 列出当前 default source 的资源；可按 agent 过滤；`type` 默认 `rule` |
 | `history <type> <name> [--json]` | 按 tag 查看版本历史                                                                 |
-| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--target a,b`、`--dry-run`、`--force`、`--json` |
+| `create <type> <name>`           | 脚手架；常用选项：`--description`、`--agent a,b`、`--dry-run`、`--force`、`--json` |
 
 ### 3) project（当前项目）
 
 | 命令                              | 说明                                                      |
 | --------------------------------- | --------------------------------------------------------- |
-| `install [type] [name[@version]]` | 有参数时安装指定资源；**无参数**时按 `himan.lock` 批量安装 |
-| `dev <type> <name>`               | 切换到开发态并把项目链接指向 `.himan/dev/...`              |
-| `uninstall <type> <name>`         | 从项目移除安装链接，并同步删除 `himan.lock` 条目           |
+| `install [type] [name[@version]] [--agent a,b] [--mode link\|copy]` | 有参数时安装指定资源；**无参数**时按 `himan.lock` 批量安装；可覆盖安装目标 agent 或安装模式 |
+| `dev <type> <name>`               | 切换到开发态，并按安装模式将项目目标指向或复制自 `.himan/dev/...` |
+| `uninstall <type> <name>`         | 从项目移除安装目标，并同步删除 `himan.lock` 条目           |
 | `publish <type> <name>`           | 默认 `--patch`；可选 `--minor` / `--major`（勿同时使用多个） |
 
+### 4) agent（默认 Agent）
+
+| 命令 | 说明 |
+|------|------|
+| `agent list [--json]` | 查看支持的 agent |
+| `agent use <agent[,agent]> [--project\|--global] [--json]` | 设置当前项目或全局默认 agent；默认 `--project` |
+| `agent current [--json]` | 查看当前项目、全局和最终生效的默认 agent |
+| `agent clear [--project\|--global] [--json]` | 清除当前项目或全局默认 agent；默认 `--project` |
+
+也可使用分组命令（与上面等价）：
+
+- `himan resource list|history|create ...`
+- `himan-resource list|history|create ...`（兼容保留：也可执行 install/dev/uninstall/publish）
+- `himan project install|dev|uninstall|publish ...`
+- `himan-project install|dev|uninstall|publish ...`
+- `himan agent list|use|current|clear ...`
+
+说明：资源与项目相关命令统一使用 `--agent` 指定目标 Agent。
+若未显式传 `--agent`，`create` / `install` 会使用当前项目默认 agent、全局默认 agent、资源 metadata 或内置默认 `cursor` 中最合适的一项；`dev` 会优先使用 lock 中记录的 agent。
+
 `publish` 优先使用项目里 `.himan/dev` 对应目录，否则用源仓库里对应目录。需要可推送的 Git 权限。若该资源已在 lock 中，发布后会同步更新 lock 版本。
 
 `--json` 模式下，失败时会输出机器可读错误 JSON（`stderr`）。错误码定义见 [docs/error-codes.md](./docs/error-codes.md)。
@@ -116,7 +154,12 @@ pnpm test
 
 3. **合并到 `master`**  
    推送合并后的 `master` 会触发 GitHub Actions 工作流 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml)：安装依赖后执行 **`pnpm run release`**（即再次 `verify` + `npm publish`）。  
-   需在仓库 **Settings → Secrets → Actions** 中配置 **`NPM_TOKEN`**（npm 侧「Access Tokens」，建议 Automation / 具备发包权限的 granular token）。
+   npm 发布认证使用 **Trusted Publishing**，不使用长期 `NPM_TOKEN`。需在 npmjs.com 的 `@hi-man/himan` 包设置中添加 Trusted Publisher：
+   - Provider: GitHub Actions
+   - Organization or user: `lidetao`
+   - Repository: `himan`
+   - Workflow filename: `publish-npm.yml`
+   workflow 已授予 OIDC 所需的 `id-token: write` 权限，并在发布前升级 npm CLI 到支持 Trusted Publishing 的版本。
 
 4. **手动从 CI 再发一次（可选）**  
    在 GitHub **Actions → Publish to npm → Run workflow** 可手动运行同一流程（例如在修复密钥后重试）。

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

@@ -30,7 +30,9 @@ export class ResourceScanner {
                 type,
                 entry: parsed.entry,
                 description: parsed.description,
-                targets: parsed.targets,
+                agents: Array.isArray(parsed.agents)
+                    ? (parsed.agents ?? [])
+                    : (parsed.targets ?? []),
             });
         }
         return result;

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

@@ -68,7 +68,7 @@ export class GitSourceAdapter {
         const repoDir = this.getRepoDir();
         const resourceDir = path.join(repoDir, this.getTypeDir(type), name);
         const entry = options.entry ?? this.getDefaultEntry(type);
-        const targets = options.targets?.length ? options.targets : ["cursor"];
+        const agents = options.agents?.length ? options.agents : ["cursor"];
         if ((await this.exists(resourceDir)) && !options.force) {
             throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
         }
@@ -82,7 +82,7 @@ export class GitSourceAdapter {
                 version: "0.1.0",
                 entry,
                 description: options.description ?? `${type} resource ${name}`,
-                targets,
+                agents,
             }), "utf8");
             await fs.writeFile(path.join(resourceDir, entry), this.getDefaultContent(type, name), "utf8");
         }

package/dist/bin/himan-project.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildProjectCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildProjectCli);
+}
+void main();

package/dist/bin/himan-resource.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildResourceCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildResourceCli);
+}
+void main();

package/dist/bin/himan-source.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildSourceCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildSourceCli);
+}
+void main();

package/dist/bin/himan.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { buildCli } from "../cli/index.js";
+import { runCliMain } from "./shared.js";
+async function main() {
+    await runCliMain(buildCli);
+}
+void main();

package/dist/{index.js → bin/shared.js}

@@ -1,8 +1,7 @@
-#!/usr/bin/env node
 import { CommanderError } from "commander";
-import { buildCli, writeCliError } from "./cli/index.js";
-async function main() {
-    const program = buildCli();
+import { writeCliError } from "../cli/index.js";
+export async function runCliMain(buildProgram) {
+    const program = buildProgram();
     try {
         await program.parseAsync(process.argv);
     }
@@ -14,4 +13,3 @@ async function main() {
         process.exitCode = error instanceof CommanderError ? error.exitCode : 1;
     }
 }
-void main();

package/dist/cli/agent-commands.js

@@ -0,0 +1,93 @@
+import { HimanError, errorCodes } from "../utils/errors.js";
+import { getSupportedAgentNames, normalizeAgent } from "../utils/agent-configs.js";
+import { runAction } from "./shared.js";
+export function registerAgentCommands(command, services) {
+    command
+        .command("list")
+        .option("--json", "output json format")
+        .description("List supported agents")
+        .action(async (options) => {
+        await runAction(async () => {
+            const agents = getSupportedAgentNames();
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(agents, null, 2)}\n`);
+                return;
+            }
+            for (const agent of agents) {
+                process.stdout.write(`- ${agent}\n`);
+            }
+        });
+    });
+    command
+        .command("use")
+        .argument("<agent_list>", "agent list, comma separated")
+        .option("--global", "save as global default")
+        .option("--project", "save as current project default")
+        .option("--json", "output json format")
+        .description("Set default agents globally or for current project")
+        .action(async (agentList, options) => {
+        await runAction(async () => {
+            const scope = parseScope(options);
+            const result = await services.setAgents(parseAgents(agentList), scope, process.cwd());
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Using agents (${result.scope}): ${result.agents.join(", ")}\n`);
+        });
+    });
+    command
+        .command("current")
+        .option("--json", "output json format")
+        .description("Show configured and effective default agents")
+        .action(async (options) => {
+        await runAction(async () => {
+            const settings = await services.getAgentSettings(process.cwd());
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(settings, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`effective: ${settings.effective.join(", ")}\n`);
+            process.stdout.write(`project: ${(settings.project ?? []).join(", ") || "-"}\n`);
+            process.stdout.write(`global: ${(settings.global ?? []).join(", ") || "-"}\n`);
+        });
+    });
+    command
+        .command("clear")
+        .option("--global", "clear global default agents")
+        .option("--project", "clear current project default agents")
+        .option("--json", "output json format")
+        .description("Clear configured default agents")
+        .action(async (options) => {
+        await runAction(async () => {
+            const result = await services.clearAgents(parseScope(options), process.cwd());
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Cleared agents (${result.scope}).\n`);
+        });
+    });
+}
+function parseScope(options) {
+    if (options.global && options.project) {
+        throw new HimanError(errorCodes.CLI_USAGE, "Use only one of --global or --project.");
+    }
+    return options.global ? "global" : "project";
+}
+function parseAgents(input) {
+    const agents = input
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    if (agents.length === 0) {
+        throw new HimanError(errorCodes.INVALID_INPUT, "Agent list cannot be empty.");
+    }
+    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/cli/builders.js

@@ -0,0 +1,72 @@
+import { ServiceFactory } from "../services/index.js";
+import { registerAgentCommands } from "./agent-commands.js";
+import { registerProjectCommands } from "./project-commands.js";
+import { registerResourceCommands } from "./resource-commands.js";
+import { registerInitCommand, registerSourceCommands } from "./source-commands.js";
+import { createBaseProgram } from "./shared.js";
+export function buildCli() {
+    const program = createBaseProgram("himan", "Prompt and agent asset management CLI");
+    const services = new ServiceFactory();
+    appendCommandGroupsHelp(program);
+    registerInitCommand(program, services);
+    const sourceCmd = program.command("source").description("Manage source repositories");
+    registerSourceCommands(sourceCmd, services, { includeInit: true });
+    const resourceCmd = program
+        .command("resource")
+        .description("Manage resources from current default source");
+    registerResourceCommands(resourceCmd, services);
+    const projectCmd = program
+        .command("project")
+        .description("Manage installed resources in current project");
+    registerProjectCommands(projectCmd, services);
+    const agentCmd = program
+        .command("agent")
+        .description("Manage default agent configuration");
+    registerAgentCommands(agentCmd, services);
+    // Backward compatible top-level resource lifecycle commands.
+    registerResourceCommands(program, services);
+    registerProjectCommands(program, services);
+    return program;
+}
+export function buildSourceCli() {
+    const program = createBaseProgram("himan-source", "Source repository management CLI");
+    const services = new ServiceFactory();
+    registerSourceCommands(program, services, { includeInit: true });
+    return program;
+}
+export function buildResourceCli() {
+    const program = createBaseProgram("himan-resource", "Resource lifecycle management CLI");
+    const services = new ServiceFactory();
+    registerResourceCommands(program, services);
+    const agentCmd = program
+        .command("agent")
+        .description("Manage default agent configuration");
+    registerAgentCommands(agentCmd, services);
+    // Backward compatible: keep project lifecycle commands in himan-resource.
+    registerProjectCommands(program, services);
+    return program;
+}
+export function buildProjectCli() {
+    const program = createBaseProgram("himan-project", "Project lifecycle management CLI");
+    const services = new ServiceFactory();
+    const agentCmd = program
+        .command("agent")
+        .description("Manage default agent configuration");
+    registerAgentCommands(agentCmd, services);
+    registerProjectCommands(program, services);
+    return program;
+}
+function appendCommandGroupsHelp(program) {
+    program.addHelpText("after", `
+Command groups:
+  source   Data source management (git now, registry reserved)
+           init, source init, source add, source use, source list
+  resource Source resource discovery and metadata
+           list, history, create, resource list, resource history, resource create
+  project  Resource usage lifecycle in current project
+           install, dev, uninstall, publish,
+           project install, project dev, project uninstall, project publish
+  agent    Default agent configuration
+           agent list, agent use, agent current, agent clear
+`);
+}