@cli-skill/cli 0.0.1-beta-d3a2d41 → 0.0.1-beta.20260402073007

package/README.md

@@ -0,0 +1,123 @@
+# @cli-skill/cli
+
+`@cli-skill/cli` 是 `cli-skill` 的平台命令行入口。
+
+它不是某一个具体 skill 的运行时，而是整个 skill 生命周期的管理入口。
+
+## 主要职责
+
+- 创建新的 skill 项目
+- 提供统一的 skill 作用域命令入口
+- 构建 `skill/` 产物
+- 安装和卸载已发布 skill
+- 挂载和取消挂载本地 skill
+- 发布本地 skill
+- 读写 `~/.cli-skill/config.json`
+
+## 命令结构
+
+### 平台命令
+
+```bash
+cli-skill create <skillName> --cli-name <cliName> [--template <templateName>]
+cli-skill list
+cli-skill install <skillName> [--packageName <packageName>]
+cli-skill uninstall <packageName>
+cli-skill config get [keyPath]
+cli-skill config set <keyPath> <value>
+```
+
+### skill 作用域命令
+
+```bash
+cli-skill <skillName> list
+cli-skill <skillName> run <toolName> [rawInput]
+cli-skill <skillName> config get [keyPath]
+cli-skill <skillName> config set <keyPath> <value>
+cli-skill <skillName> config unset <keyPath>
+cli-skill <skillName> mount [targetPath]
+cli-skill <skillName> unmount [targetPath]
+cli-skill <skillName> build
+cli-skill <skillName> publish [--dry-run] [--tag <tag>]
+```
+
+## 典型工作流
+
+```bash
+cli-skill create my-skill --cli-name my-skill
+cd ~/.cli-skill/skills/my-skill
+bun install
+cli-skill my-skill build
+cli-skill my-skill mount
+```
+
+## skill 项目结构
+
+一个标准 skill 项目包含：
+
+- `src/index.ts`
+- `src/tools/*`
+- `src/skill/*`
+
+其中：
+
+- `src/index.ts`
+  - 定义并导出 skill
+- `src/tools/*`
+  - 定义 tools
+- `src/skill/*`
+  - 文档模板源目录
+
+执行 `build` 后会生成：
+
+- `skill/SKILL.md`
+- `skill/agents/openai.yaml`
+
+所以：
+
+- `src/skill/` 是源码
+- 根目录 `skill/` 是产物
+
+## build 输入
+
+`cli-skill <skillName> build` 会读取：
+
+- `src/index.ts`
+- `src/skill/`
+
+`src/skill/` 下的 `.md`、`.yaml`、`.yml` 文件会被当成模板渲染到根目录 `skill/`。
+
+当前常用模板变量有：
+
+- `{{name}}`
+- `{{description}}`
+- `{{overview}}`
+- `{{toolReference}}`
+- `{{configReference}}`
+
+## 安装模型
+
+本地 skill 默认放在：
+
+- `~/.cli-skill/skills`
+
+托管安装目录默认是：
+
+- `~/.cli-skill/installed`
+
+默认 agent 目录是：
+
+- `~/.agents/skills`
+
+`install` 默认接受 skill 名。CLI 会在 npm 中查找同时包含：
+
+- `cli-skill`
+- `<skillName>`
+
+这两个关键词的包。
+
+如果已经知道包名，可以显式指定：
+
+```bash
+cli-skill install fx --packageName @scope/cli-skill-fx
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cli-skill/cli",
-  "version": "0.0.1-beta-d3a2d41",
+  "version": "0.0.1-beta.20260402073007",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -15,11 +15,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "check": "tsc --noEmit -p tsconfig.json"
+    "test": "tsc -p tsconfig.test.json && bun test ./test"
   },
   "dependencies": {
-    "@cli-skill/core": "^0.0.1-beta-d3a2d41",
+    "@cli-skill/core": "^0.0.1-beta.20260402073007",
     "cac": "^6.7.14",
-    "lodash": "^4.17.21"
+    "lodash": "^4.17.21",
+    "zod": "^3.25.76"
   }
 }

package/skill/SKILL.md

@@ -1,106 +1,154 @@
 ---
 name: cli-skill-creator
-description: 当需要创建、接通、安装或维护 cli skill 时，使用 cli-skill CLI 完成标准流程。
+description: 当任务涉及 cli skill 的创建、挂载、安装、发布或配置时，使用 cli-skill CLI。
 ---
 
 # cli-skill-creator
 
-当用户要创建一个新的 cli skill，接通本地开发中的 skill，安装一个已发布的 skill，或者维护 cli-skill 的全局配置时，使用这个 skill。
+这个 skill 面向的是：需要创建、修改、接通、安装或发布 cli skill 的任务。
 
-## 何时使用
+如果需要查看 skill 源码结构和 core API 参考，继续看：
 
-- 用户说“创建一个 cli skill”
-- 用户要把一个本地 skill 接成可直接执行的 CLI
-- 用户要安装或卸载一个已发布的 cli skill
-- 用户要查看或修改 `~/.cli-skill/config.json`
-- 用户要更新某个 skill 的 `SKILL.md` 中的 Tool / Config 文档区块
+- [references/core.md](/Users/bin.jia1/work/github/cli-skill/packages/cli/skill/references/core.md)
+
+## 使用时机
+
+- 创建新的 cli skill
+- 修改已有 skill
+- 构建 `skill/` 产物
+- 把本地 skill 接到 agent 目录
+- 安装或卸载已发布 skill
+- 发布本地 skill
+- 读写 cli-skill 配置
+
+## 工作模型
+
+处理 cli skill 时，默认按两层命令来理解：
+
+- 平台命令
+  - `cli-skill create`
+  - `cli-skill list`
+  - `cli-skill install`
+  - `cli-skill uninstall`
+  - `cli-skill config ...`
+- skill 作用域命令
+  - `cli-skill <skill-name> ...`
+
+skill 自己的 bin 只是一个转发入口，仍然会落到 `cli-skill <skill-name> ...`。
 
 ## 默认流程
 
-如果用户要新建一个 skill，默认按下面顺序执行：
+当用户要新建一个 skill 时，默认流程是：
 
 ```bash
 cli-skill create <skill-name> --cli-name <cli-name>
 bun install
-cli-skill enable <skill-name>
-cli-skill sync-skill --write
+cli-skill <skill-name> build
+cli-skill <skill-name> mount
 ```
 
-如果用户没有指定 `cli-name`，默认令它等于 `skill-name`。
+如果没有提供 `cli-name`，默认令它等于 `skill-name`。
+
+## 项目结构
 
-## 命令对照
+默认 skill 项目结构：
+
+- `src/index.ts`
+- `src/tools/*`
+- `src/skill/*`
+
+含义：
+
+- `src/index.ts`
+  - skill 定义入口
+- `src/tools/*`
+  - tool 源码
+- `src/skill/*`
+  - 文档模板源目录
+
+执行：
+
+```bash
+cli-skill <skill-name> build
+```
+
+会生成：
+
+- `skill/SKILL.md`
+- `skill/agents/openai.yaml`
+
+## 常用命令
 
 | 场景 | 命令 |
 | --- | --- |
 | 创建 skill | `cli-skill create <skill-name> --cli-name <cli-name> [--template <templateName>]` |
-| 激活本地 skill | `cli-skill enable <skill-name> [--agentPath <path>]` |
-| 取消激活本地 skill | `cli-skill disable <skill-name> [--agentPath <path>]` |
+| 查看 skill 列表 | `cli-skill list` |
 | 安装已发布 skill | `cli-skill install <skill-name>` |
 | 卸载已发布 skill | `cli-skill uninstall <package-name>` |
-| 发布本地 skill | `cli-skill publish <skill-name> [--dry-run]` |
-| 查看 skill 列表 | `cli-skill list` |
-| 同步 skill 文档 | 在 skill 根目录执行 `cli-skill sync-skill --write` |
-| 读取配置 | `cli-skill config get [keyPath]` |
-| 写入配置 | `cli-skill config set <keyPath> <value>` |
+| 查看 tool 列表 | `cli-skill <skill-name> list` |
+| 运行 tool | `cli-skill <skill-name> run <tool-name> [rawInput]` |
+| 读取 skill 配置 | `cli-skill <skill-name> config get [keyPath]` |
+| 写入 skill 配置 | `cli-skill <skill-name> config set <keyPath> <value>` |
+| 删除 skill 配置 | `cli-skill <skill-name> config unset <keyPath>` |
+| 挂载 skill | `cli-skill <skill-name> mount [targetPath]` |
+| 取消挂载 skill | `cli-skill <skill-name> unmount [targetPath]` |
+| 构建 skill 产物 | `cli-skill <skill-name> build` |
+| 发布本地 skill | `cli-skill <skill-name> publish [--dry-run] [--tag <tag>]` |
+| 读取全局配置 | `cli-skill config get [keyPath]` |
+| 写入全局配置 | `cli-skill config set <keyPath> <value>` |
 
 ## 关键规则
 
-- `create` 会通过 `bunx` 调 templates 包创建 skill 项目。
-- 默认模板名是 `basic`，对应 templates 包里的内置基础模板。
-- `create` 只创建项目，不会自动执行 `bun install`，也不会自动注册 CLI。
-- `enable` 只做两件事：
-  - 把目标 skill 的 bin 接到 Bun 全局 bin
-  - 把目标 skill 的 `./skill` 注册到目标 skill 目录，默认是 `~/.agents/skills/<skill-name>`
-- `enable` / `disable` 都通过 `skill-name` 到 `~/.cli-skill/skills/<skill-name>` 查找本地 skill 项目
-- `install` / `uninstall` 面向已发布或已打包的 skill：
-  - `install` 会把 skill 安装到 `~/.cli-skill/installed`
-  - 同时把 bin 接到 Bun 全局 bin
-  - 同时把 `skill/` 注册到目标 skill 目录，默认是 `~/.agents/skills/<skill-name>`
-- `install <skill-name>` 会先按 skill 名去 npm search API 查找：
-  - 搜索条件包含 `cli-skill` 和 `<skill-name>`
-  - 只有唯一命中时才会安装
-- `install <skill-name> --packageName <package-name>` 会直接按显式包名安装
-- `i` 是 `install` 的简写
-- `publish <skill-name>` 会从 `~/.cli-skill/skills/<skill-name>` 找到本地 skill 项目，并执行 `bun publish`
-- skill 项目默认创建在：
+- `create` 只创建项目，不会自动安装依赖，也不会自动挂载。
+- `build` 负责把 `src/skill/*` 渲染成根目录 `skill/*`。
+- `mount` 负责：
+  - 接通 skill 的 bin
+  - 注册根目录 `skill/` 到 agent 目录
+- `mount` 不应隐式执行 `install`。
+- `install` / `uninstall` 面向已发布 skill。
+- `publish` 只针对本地 skill。
+
+默认目录：
+
+- 本地 skill：
   - `~/.cli-skill/skills/<skill-name>`
-- 托管安装的 skill 默认放在：
+- 托管安装目录：
   - `~/.cli-skill/installed`
-- agent 读取 skill 的目录默认是：
+- agent 默认目录：
   - `~/.agents/skills/<skill-name>`
-- 包名可以带 `cli-skill-` 前缀，但 agent 使用的 skill 名不带这个前缀。
-- 如果用户只是要修改某个已有 skill，不要重新 `create`，直接进入现有 skill 目录工作。
 
-## 配置规则
+## 配置
 
-- 全局配置文件是：
-  - `~/.cli-skill/config.json`
-- 通过下面命令读写：
+全局配置文件：
+
+- `~/.cli-skill/config.json`
+
+skill 作用域配置路径：
+
+- `skillConfig.<skill-name>`
+
+常见命令：
 
 ```bash
 cli-skill config get
-cli-skill config get skillConfig.fx
-cli-skill config set skillConfig.fx.baseUrl https://example.com
+cli-skill config set skillsRoot ~/.cli-skill/skills
+cli-skill <skill-name> config get
+cli-skill <skill-name> config set baseUrl https://example.com
 ```
 
-- `get` / `set` 支持点路径，如：
-  - `skillConfig.fx.baseUrl`
-  - `skillConfig.fx.env.TEST_VALUE`
-
-## 文档同步规则
+## 文档规则
 
-- skill 的 `SKILL.md` 里，`Tool Reference` 和 `Config Reference` 应由平台命令生成。
-- 当工具或配置发生变化后，优先执行：
+- `src/skill/*` 是模板源目录
+- `skill/*` 是生成产物
+- tool 或配置变更后，应重新执行：
 
 ```bash
-cli-skill sync-skill --write
+cli-skill <skill-name> build
 ```
 
-- 不要手写维护这两个生成区块，除非用户明确要求。
-
 ## 不要做的事
 
 - 不要把 `create` 当成“已经可执行”
-- 不要让 `enable` 隐式执行 `install`
-- 不要手动改 `~/.agents/skills`，优先通过 `cli-skill` CLI 管理
-- 不要把测试 skill 长期留在工作区；测试时统一使用 `test-skill-1`、`test-skill-2` 这类名字
+- 不要手动改 `~/.agents/skills`
+- 不要把 skill bin 当成独立平台
+- 不要在修改已有 skill 时重新 `create`

package/skill/references/core.md

@@ -0,0 +1,229 @@
+# Core Reference
+
+这份参考页回答的不是“命令怎么敲”，而是：
+
+**一个 cli skill 的源码应该怎么组织。**
+
+如果主 `SKILL.md` 解决的是工作流，那么这里解决的是源码模型。
+
+## 先建立心智
+
+写一个 cli skill 时，先把这三层区分开：
+
+- `tool`
+  - 真正执行动作的最小单元
+- `skill`
+  - 对 tools 的组织与描述
+- `build` 产物
+  - 给 agent 使用的 `skill/` 目录
+
+源码不是直接写给 agent 的。  
+源码先定义 skill 和 tools，然后再由 `build` 生成 agent 真正消费的产物。
+
+## skill 项目源码结构
+
+当前单个 skill 项目默认包含：
+
+- `src/index.ts`
+- `src/tools/*`
+- `src/skill/*`
+
+它们的职责分别是：
+
+- `src/index.ts`
+  - 定义并导出 skill
+- `src/tools/*`
+  - 定义 tools
+- `src/skill/*`
+  - 文档模板源目录
+
+执行：
+
+```bash
+cli-skill <skill-name> build
+```
+
+之后，根目录会生成：
+
+- `skill/SKILL.md`
+- `skill/agents/openai.yaml`
+
+所以一定要区分：
+
+- `src/skill/*` 是源码
+- `skill/*` 是产物
+
+## `defineSkill` 负责什么
+
+`defineSkill` 只负责描述这个 skill 本身。
+
+当前它声明的是：
+
+- `name`
+- `description`
+- `overview`
+- `config`
+- `tools`
+
+也就是说，skill 只做“组织”和“说明”，不直接承担运行时能力注入。
+
+## `defineTool` 负责什么
+
+`defineTool` 才是运行能力的核心。
+
+一个 tool 当前声明这些内容：
+
+- `name`
+- `description`
+- `plugins`
+- `examples`
+- `inputSchema`
+- `outputSchema`
+- `run(input, ctx)`
+
+最关键的一点是：
+
+- tool 自己声明 `plugins`
+- `ctx` 从 `plugins` 自动推导
+
+所以你不需要手写 `ctx` 泛型，也不需要在 skill 上重复声明插件。
+
+## 为什么 plugin 放在 tool 上
+
+当前模型里，tool 才是真正执行动作的单位。
+
+所以：
+
+- skill 只负责组织 tools
+- tool 负责声明自己需要什么能力
+
+这样做的结果是：
+
+- skill 更轻
+- tool 的依赖更清楚
+- `ctx` 的来源更明确
+
+换句话说，运行时能力是“执行问题”，不是“文档问题”。  
+所以 plugin 挂在 tool 上，比挂在 skill 上更合理。
+
+## plugin 注入怎么理解
+
+plugin 负责两件事：
+
+1. 提供运行时能力
+2. 为 `ctx` 提供类型
+
+例如 `browserPlugin` 会提供：
+
+- `browser`
+- `context`
+- `page`
+- `request`
+
+当 tool 写成：
+
+```ts
+plugins: [browserPlugin]
+```
+
+那么 `run(input, ctx)` 里的 `ctx.page`、`ctx.request` 就会自动可用。
+
+当前 plugin 生命周期是单次执行：
+
+1. `setup`
+2. `tool.run`
+3. `dispose`
+
+所以现在默认模型是“一次命令，一次 runtime”。
+
+## 最小源码示例
+
+```ts
+import { z } from "zod";
+import { browserPlugin, defineSkill, defineTool } from "@cli-skill/core";
+
+const inputSchema = z.object({
+  url: z.string().url(),
+});
+
+const outputSchema = z.object({
+  url: z.string().url(),
+  title: z.string(),
+});
+
+const openPageTool = defineTool({
+  name: "open_page",
+  description: "Open a page and return its title.",
+  plugins: [browserPlugin],
+  inputSchema,
+  outputSchema,
+  async run(input, ctx) {
+    await ctx.page.goto(input.url);
+    return {
+      url: input.url,
+      title: await ctx.page.title(),
+    };
+  },
+});
+
+export default defineSkill({
+  name: "example",
+  description: "Example skill.",
+  overview: "An example skill powered by Playwright.",
+  config: {},
+  tools: [openPageTool],
+});
+```
+
+这个例子里：
+
+- `tool` 负责声明自己要 `browserPlugin`
+- `skill` 只负责把它组织起来
+- `build` 再负责生成 `skill/` 产物
+
+## 文档模板怎么写
+
+`src/skill/*` 下的 `.md/.yaml/.yml` 文件会在 build 时做变量替换。
+
+当前常用变量有：
+
+- `{{name}}`
+- `{{description}}`
+- `{{overview}}`
+- `{{toolReference}}`
+- `{{configReference}}`
+
+所以建议把：
+
+- Tool Reference
+- Config Reference
+
+交给模板变量，而不是手写重复内容。
+
+## 依赖约定
+
+`@cli-skill/core` 是一个库，不是最终 skill 包。
+
+因此：
+
+- `zod` 在 `core` 里是 `peerDependencies`
+- skill 自己如果直接 `import { z } from "zod"`，就应在自己的包里声明 `zod`
+
+这也是为什么生成出来的 skill 模板会把 `zod` 放在自己的 `dependencies` 里。
+
+## 什么时候继续往下看
+
+如果你需要的是：
+
+- 怎么创建 skill
+- 怎么 mount / install / publish
+- 怎么 build 产物
+
+优先回到主 skill 文档：
+
+- [SKILL.md](/Users/bin.jia1/work/github/cli-skill/packages/cli/skill/SKILL.md)
+
+这里更适合解决：
+
+- skill 源码应该怎么写
+- tool / skill / plugin 的职责边界是什么

package/src/app.ts

@@ -1,28 +1,22 @@
 import { cac } from "cac";
 import { registerConfigCommand } from "./commands/config";
 import { registerCreateCommand } from "./commands/create";
-import { registerDisableCommand } from "./commands/disable";
-import { registerSyncSkillCommand } from "./commands/docs";
-import { registerEnableCommand } from "./commands/enable";
 import { registerInstallCommand } from "./commands/install";
 import { registerListCommand } from "./commands/list";
-import { registerPublishCommand } from "./commands/publish";
+import { registerSkillCommand } from "./commands/skill";
 import { registerUninstallCommand } from "./commands/uninstall";
 
-export function createApp() {
+export function createApp(version: string) {
   const cli = cac("cli-skill");
 
   registerCreateCommand(cli);
   registerConfigCommand(cli);
-  registerSyncSkillCommand(cli);
   registerListCommand(cli);
-  registerEnableCommand(cli);
-  registerDisableCommand(cli);
   registerInstallCommand(cli);
   registerUninstallCommand(cli);
-  registerPublishCommand(cli);
+  registerSkillCommand(cli);
 
   cli.help();
-  cli.version("0.1.0");
+  cli.version(version);
   return cli;
 }