@sokeai/cli 1.0.23 → 1.0.25

package/README.md

@@ -2,6 +2,17 @@
 
 `soke-cli` 是授客AI官方提供的命令行工具，旨在帮助开发者和系统管理员更便捷地通过命令行与授客AI开放平台进行交互。该工具使用 Go 语言开发，支持多平台，并提供了 NPM 包的安装方式。
 
+## 目录
+
+- [核心能力](#核心能力)
+- [安装方法](#安装方法)
+- [快速开始](#快速开始)
+- [开发指南](#开发指南)
+  - [从接口封装到发布的完整流程](#从接口封装到发布的完整流程)
+  - [本地开发测试](#本地开发测试)
+- [项目结构](#项目结构)
+- [相关文档](#相关文档)
+
 ## 核心能力
 
 `soke-cli` 提供了以下核心能力：
@@ -25,12 +36,16 @@
      - **培训 (training)**: 线下培训查询与分配。
      - **新闻公告 (news)**: 资讯列表与详情。
 
+4. **AI Agent Skills**
+   - 提供 AI Agent 技能（Skills），使 AI 助手能够自动发现和调用 CLI 功能。
+   - 支持自然语言交互，无需记忆复杂的命令参数。
+
 ## 安装方法
 
 ### 方式一：通过 NPM 安装 (推荐)
 如果你本地已安装 Node.js，可以直接使用 npm 全局安装：
 ```bash
-npm install -g @sokeai/cli
+npm install -g @sokeai/cli@latest
 ```
 
 ### 方式二：通过源码编译安装 (需要 Go 环境)
@@ -149,20 +164,377 @@ soke-cli api GET /users/me
 soke-cli api POST /some/endpoint --data '{"key": "value"}'
 ```
 
-## 项目结构说明
+## 开发指南
+
+### 从接口封装到发布的完整流程
+
+#### 1️⃣ 接口封装为 CLI 命令
+
+**步骤 1: 在 shortcuts 目录下定义接口元数据**
+
+```bash
+# 创建新模块目录
+mkdir -p shortcuts/your-module
+
+# 创建命令定义文件
+touch shortcuts/your-module/list_items.go
+```
+
+**示例：定义一个查询列表的命令**
+
+```go
+// shortcuts/your-module/list_items.go
+package yourmodule
+
+import "soke-cli/internal/client"
+
+// ListItemsShortcut 定义查询列表命令
+func ListItemsShortcut() client.Shortcut {
+    return client.Shortcut{
+        Name:        "list-items",           // 命令名称
+        Description: "查询项目列表",          // 命令描述
+        Method:      "GET",                  // HTTP 方法
+        Path:        "/api/v1/items",        // API 路径
+        Params: []client.Param{              // 参数定义
+            {
+                Name:        "page",
+                Type:        "int",
+                Description: "页码",
+                Required:    false,
+                Default:     "1",
+            },
+            {
+                Name:        "page_size",
+                Type:        "int",
+                Description: "每页数量",
+                Required:    false,
+                Default:     "10",
+            },
+            {
+                Name:        "keyword",
+                Type:        "string",
+                Description: "搜索关键词",
+                Required:    false,
+            },
+        },
+    }
+}
+```
+
+**步骤 2: 注册命令到模块**
+
+```go
+// shortcuts/your-module/shortcuts.go
+package yourmodule
+
+import "soke-cli/internal/client"
+
+// Shortcuts 返回该模块的所有快捷命令
+func Shortcuts() []client.Shortcut {
+    return []client.Shortcut{
+        ListItemsShortcut(),
+        // 添加更多命令...
+    }
+}
+```
+
+**步骤 3: 在 cmd 层注册模块**
+
+```go
+// cmd/your_module/your_module.go
+package yourmodule
+
+import (
+    "soke-cli/internal/client"
+    yourmodule "soke-cli/shortcuts/your-module"
+    "github.com/spf13/cobra"
+)
+
+// YourModuleCmd 模块根命令
+var YourModuleCmd = &cobra.Command{
+    Use:   "your-module",
+    Short: "你的模块管理",
+    Long:  "管理你的模块相关功能",
+}
+
+func init() {
+    // 自动注册所有快捷命令
+    client.RegisterShortcuts(YourModuleCmd, yourmodule.Shortcuts())
+}
+```
+
+**步骤 4: 在根命令中注册模块**
+
+```go
+// cmd/root.go
+import (
+    yourmodule "soke-cli/cmd/your_module"
+)
+
+func init() {
+    // 注册模块命令
+    rootCmd.AddCommand(yourmodule.YourModuleCmd)
+}
+```
+
+#### 2️⃣ 创建 AI Agent Skill
+
+**步骤 1: 创建 Skill 目录和文档**
+
+```bash
+# 创建 Skill 目录
+mkdir -p skills/your-module
+
+# 创建 Skill 定义文件
+touch skills/your-module/SKILL.md
+```
+
+**步骤 2: 编写 Skill 文档**
+
+```markdown
+<!-- skills/your-module/SKILL.md -->
+---
+name: your-module
+description: 你的模块管理：查询项目列表、创建项目、更新项目等
+trigger: 当用户需要查询项目、管理项目时使用
+---
+
+# 你的模块管理 Skill
+
+## 功能说明
+
+提供项目管理相关功能，包括：
+- 查询项目列表
+- 创建新项目
+- 更新项目信息
+- 删除项目
+
+## 使用场景
+
+- 用户询问："查询所有项目"
+- 用户询问："创建一个新项目"
+- 用户询问："更新项目信息"
+
+## 可用命令
+
+### 查询项目列表
+
+\`\`\`bash
+soke-cli your-module +list-items [选项]
+\`\`\`
+
+**参数说明：**
+- `--page <number>`: 页码（可选，默认：1）
+- `--page-size <number>`: 每页数量（可选，默认：10）
+- `--keyword <string>`: 搜索关键词（可选）
+
+**使用示例：**
+\`\`\`bash
+# 查询第一页
+soke-cli your-module +list-items
+
+# 搜索包含"测试"的项目
+soke-cli your-module +list-items --keyword "测试"
+\`\`\`
+
+## 交互流程
+
+1. 识别用户意图（查询/创建/更新/删除）
+2. 提示用户提供必要参数
+3. 执行对应的 CLI 命令
+4. 解析并展示结果
+
+## 错误处理
+
+- 如果用户未登录，提示执行 `soke-cli auth login`
+- 如果参数缺失，提示用户补充必要参数
+- 如果 API 返回错误，展示友好的错误信息
+```
+
+**步骤 3: 更新 skills/README.md**
+
+在 `skills/README.md` 中添加新 Skill 的说明。
+
+#### 3️⃣ 本地测试 Skill
+
+**方法一：一键测试脚本（推荐）**
+
+```bash
+# 1. 编译、安装到全局、运行测试
+bash ./scripts/local-test.sh
+# 提示时输入 'y' 更新全局安装
+
+# 2. 链接 Skills 到 AI Agent
+bash ./scripts/link-skills.sh
+# 选择 'all' 链接到所有目录
+
+# 3. 在 AI Agent 中测试
+# 打开 Claude Code，输入："查询所有项目"
+```
+
+**方法二：手动测试**
+
+```bash
+# 1. 编译项目
+go build -o soke-cli main.go
+
+# 2. 测试命令是否正常工作
+./soke-cli your-module +list-items --help
+
+# 3. 安装到全局
+sudo cp soke-cli /usr/local/bin/
+
+# 4. 链接 Skill 到 Claude
+mkdir -p ~/.claude/skills/your-module
+cp skills/your-module/SKILL.md ~/.claude/skills/your-module/
+
+# 5. 在 Claude Code 中测试
+# 输入："查询所有项目"
+```
+
+**测试检查清单：**
+- [ ] CLI 命令能正常执行
+- [ ] 参数验证正确
+- [ ] API 调用成功
+- [ ] 输出格式正确
+- [ ] AI Agent 能识别意图
+- [ ] AI Agent 能正确调用命令
+- [ ] 错误处理友好
+
+#### 4️⃣ 用 Go 编译二进制文件
+
+**编译单平台二进制**
+
+```bash
+# macOS (Intel)
+GOOS=darwin GOARCH=amd64 go build -o bin/soke-cli-darwin-amd64 main.go
+
+# macOS (Apple Silicon)
+GOOS=darwin GOARCH=arm64 go build -o bin/soke-cli-darwin-arm64 main.go
+
+# Linux
+GOOS=linux GOARCH=amd64 go build -o bin/soke-cli-linux-amd64 main.go
+
+# Windows
+GOOS=windows GOARCH=amd64 go build -o bin/soke-cli-windows-amd64.exe main.go
+```
+
+**一键编译所有平台**
+
+```bash
+# 使用编译脚本
+bash ./scripts/build-binaries.sh
+
+# 编译结果在 bin/ 目录下
+ls -lh bin/
+```
+
+**编译优化选项**
+
+```bash
+# 减小二进制文件大小
+go build -ldflags="-s -w" -o soke-cli main.go
+
+# 添加版本信息
+VERSION=$(git describe --tags --always)
+go build -ldflags="-X main.Version=$VERSION" -o soke-cli main.go
+```
+
+#### 5️⃣ 发布到 NPM 和 GitHub
+
+**准备工作**
+
+```bash
+# 1. 确保已登录 NPM
+npm login
+
+# 2. 确保已登录 GitHub CLI
+gh auth login
+
+# 3. 确保代码已提交
+git add .
+git commit -m "feat: 添加新模块"
+git push
+```
+
+**发布流程**
+
+**方法一：一键发布（推荐）**
+
+```bash
+# 1. 更新版本号
+npm version patch  # 1.0.0 -> 1.0.1
+# 或
+npm version minor  # 1.0.0 -> 1.1.0
+# 或
+npm version major  # 1.0.0 -> 2.0.0
+
+# 2. 执行一键发布脚本
+bash ./scripts/release.sh
+
+# 脚本会自动完成：
+# - 编译所有平台二进制文件
+# - 创建 Git 标签
+# - 推送标签到 GitHub
+# - 创建 GitHub Release 并上传二进制文件
+# - 发布到 NPM
+```
+
+**方法二：手动发布**
 
-- `cmd/`: 存放所有 CLI 子命令的定义（按业务模块划分，如 `auth`, `course`, `exam` 等）。
-- `internal/`: 存放核心逻辑，包括认证 (`auth`)、API 客户端封装 (`client`)、配置管理 (`core`) 以及输出格式化 (`output`) 等。
-- `shortcuts/`: 定义了各个业务模块的快捷命令元数据（API路径、参数、默认值等），供 `cmd/` 动态注册命令使用。
-- `scripts/`: NPM 包相关的安装与运行脚本。
-- `main.go`: CLI 的主入口文件。
+```bash
+# 1. 更新版本号
+npm version patch
+
+# 2. 编译所有平台
+bash ./scripts/build-binaries.sh
+
+# 3. 创建并推送标签
+VERSION=$(node -p "require('./package.json').version")
+git tag v$VERSION
+git push origin v$VERSION
+
+# 4. 创建 GitHub Release
+gh release create v$VERSION \
+  bin/soke-cli-darwin-amd64 \
+  bin/soke-cli-darwin-arm64 \
+  bin/soke-cli-linux-amd64 \
+  bin/soke-cli-windows-amd64.exe \
+  --title "v$VERSION" \
+  --notes "Release v$VERSION"
+
+# 5. 发布到 NPM
+npm publish --access public
+
+# 6. 验证发布
+npm view @sokeai/cli version
+```
 
-## 开发与贡献
+**发布后验证**
 
-### 快速开始本地测试
+```bash
+# 1. 测试 NPM 安装
+npm install -g @sokeai/cli@latest
+
+# 2. 验证版本
+soke-cli --version
+
+# 3. 测试命令
+soke-cli your-module +list-items --help
+
+# 4. 测试 Skills 安装
+npx skills add liuchenlong1111/soke-cli -y -g
+
+# 5. 在 AI Agent 中测试
+# 打开 Claude Code，输入："查询所有项目"
+```
+
+### 本地开发测试
+
+**🚀 快速测试流程（推荐）**
 
 ```bash
-# 1. 编译、安装到全局、运行测试（一条命令）
+# 1. 一键测试：编译、安装到全局、运行测试（一条命令）
 bash ./scripts/local-test.sh
 # 提示时输入 'y' 更新全局安装
 
@@ -176,51 +548,72 @@ bash ./scripts/link-skills.sh
 
 **📖 详细指南：** [docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md)
 
-### 本地开发测试
+**完整开发流程**
+
+```bash
+# 1. 修改代码后，运行本地测试（会提示是否更新全局安装）
+bash ./scripts/local-test.sh
+
+# 2. 运行完整 E2E 测试
+bash ./scripts/e2e-test.sh
+
+# 3. 测试 Skills（需要先更新全局安装）
+npx skills add liuchenlong1111/soke-cli -y -g
+
+# 4. 在 AI Agent 中测试自然语言交互
+# 例如："查询张三的学习档案"
+```
+
+**运行完整 E2E 测试**
+
+```bash
+# 测试所有模块
+bash ./scripts/e2e-test.sh
+
+# 测试特定模块
+bash ./scripts/e2e-test.sh learning-profile
+bash ./scripts/e2e-test.sh contact
+```
+
+## 项目结构
+
+```
+soke-cli/
+├── cmd/                    # CLI 子命令定义（按业务模块划分）
+│   ├── root.go            # 根命令和命令注册
+│   ├── auth/              # 认证相关命令
+│   ├── config/            # 配置管理命令
+│   ├── api/               # 通用 API 调用命令
+│   └── your_module/       # 你的业务模块命令
+├── internal/              # 核心逻辑（不对外暴露）
+│   ├── auth/              # 认证逻辑（OAuth Device Flow）
+│   ├── client/            # API 客户端封装
+│   ├── core/              # 配置管理
+│   └── output/            # 输出格式化
+├── shortcuts/             # 业务模块快捷命令元数据定义
+│   └── your-module/       # 各模块的 API 路径、参数、默认值等
+├── skills/                # AI Agent Skills 定义
+│   ├── README.md          # Skills 使用说明
+│   └── your-module/       # 各模块的 Skill 文档
+│       └── SKILL.md
+├── scripts/               # 构建和发布脚本
+│   ├── install.js         # NPM 安装时下载二进制文件
+│   ├── run.js             # NPM 运行时入口
+│   ├── build-binaries.sh  # 编译所有平台二进制
+│   ├── release.sh         # 一键发布脚本
+│   ├── local-test.sh      # 本地测试脚本
+│   └── link-skills.sh     # 链接 Skills 到 AI Agent
+├── main.go                # CLI 主入口
+├── go.mod                 # Go 依赖管理
+├── package.json           # NPM 包配置
+├── Makefile               # 编译和安装脚本
+└── README.md              # 项目说明文档
+```
+
+## 相关文档
 
-1. **一键测试和安装**
-   ```bash
-   # 编译 -> 安装到全局 -> 运行测试（一条命令完成所有步骤）
-   bash ./scripts/local-test.sh
-   ```
-   
-   这个脚本会：
-   - 编译项目
-   - 检查本地版本功能
-   - 检测全局安装状态
-   - 提示是否需要更新全局安装（会自动备份）
-   - 运行功能测试验证
-
-2. **运行完整 E2E 测试**
-   ```bash
-   # 测试所有模块
-   bash ./scripts/e2e-test.sh
-   
-   # 测试特定模块
-   bash ./scripts/e2e-test.sh learning-profile
-   bash ./scripts/e2e-test.sh contact
-   ```
-
-3. **依赖管理**
-   
-   项目使用 Go Modules，可以运行 `go mod tidy` 整理依赖。
-
-4. **添加新命令**
-   - 业务接口建议在 `shortcuts/` 目录下添加对应的结构定义。
-   - 基础功能可在 `cmd/` 下新建对应包并在 `cmd/root.go` 中注册。
-   - 为新模块创建 Skill 文档：`skills/<module-name>/SKILL.md`
-
-5. **完整开发流程**
-   ```bash
-   # 1. 修改代码后，运行本地测试（会提示是否更新全局安装）
-   bash ./scripts/local-test.sh
-   
-   # 2. 运行完整 E2E 测试
-   bash ./scripts/e2e-test.sh
-   
-   # 3. 测试 Skills（需要先更新全局安装）
-   npx skills add liuchenlong1111/soke-cli -y -g
-   
-   # 4. 在 AI Agent 中测试自然语言交互
-   # 例如："查询张三的学习档案"
-   ```
+- **[QUICKSTART.md](QUICKSTART.md)** - 快速开始指南
+- **[CLAUDE.md](CLAUDE.md)** - 项目架构和开发规范
+- **[docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md)** - 本地测试详细指南
+- **[skills/README.md](skills/README.md)** - AI Agent Skills 使用说明
+- **[npm.md](npm.md)** - NPM 包发布详细文档

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sokeai/cli",
-    "version": "1.0.23",
+    "version": "1.0.25",
     "description": "授客AI官方CLI工具 - 支持AI Agent Skills",
     "bin": {
         "soke-cli": "scripts/run.js"

package/scripts/local-test.sh

@@ -107,7 +107,65 @@ else
 fi
 echo ""
 
-# 步骤4: 运行测试
+# 步骤3.5: 分发 Skills 到本地 Agent
+echo -e "${YELLOW}[3.5/4] 分发 Skills 到本地 Agent...${NC}"
+if [ "$SKIP_GLOBAL" = false ]; then
+    echo -e "  执行 scripts/install.js 同步 Skills..."
+    # 注入特殊环境变量或者直接调用 node 执行
+    # 我们只想要触发 syncSkillsToSokeclawWorkspace 和 syncSkillsToWorkclawRegistry
+    # 但原 install.js 会尝试下载二进制文件，所以我们新建一个临时脚本或修改调用方式
+    
+    # 为了安全起见，这里直接使用 node 运行一小段脚本引入 install.js 中的逻辑
+    cat > ./scripts/sync-skills-local.js << 'EOF'
+const fs = require('fs');
+const path = require('path');
+const installCode = fs.readFileSync(path.join(__dirname, 'install.js'), 'utf8');
+
+// 提取需要的函数
+const syncFn1Match = installCode.match(/function syncSkillsToSokeclawWorkspace\(\) \{[\s\S]*?\n\}/);
+const syncFn2Match = installCode.match(/function syncSkillsToWorkclawRegistry\(\) \{[\s\S]*?\n\}/);
+
+// 我们更推荐直接利用已经写好的 js 模块（如果它是通过 module.exports 导出的）
+// 但因为 install.js 是直接执行的脚本，我们通过简单的 node 脚本手动拷贝
+const os = require('os');
+function copyDirRecursive(srcDir, destDir) {
+  if (!fs.existsSync(srcDir)) return;
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) { copyDirRecursive(srcPath, destPath); continue; }
+    fs.copyFileSync(srcPath, destPath);
+  }
+}
+
+const homeDir = os.homedir();
+const defaultSokeclawDir = path.join(homeDir, '.sokeclaw', 'openai-agents', 'workspaces', 'main', 'skills');
+const packageRoot = path.join(__dirname, '..');
+const packagedSkillsDir = path.join(packageRoot, 'skills');
+
+if (fs.existsSync(packagedSkillsDir)) {
+  const skillNames = fs.readdirSync(packagedSkillsDir).filter(n => n.startsWith('soke-'));
+  if (fs.existsSync(defaultSokeclawDir)) {
+    for (const skillName of skillNames) {
+      const src = path.join(packagedSkillsDir, skillName);
+      const dest = path.join(defaultSokeclawDir, skillName);
+      copyDirRecursive(src, dest);
+      console.log(`  ✓ 同步 ${skillName} 到 ${dest}`);
+    }
+  }
+}
+EOF
+    node ./scripts/sync-skills-local.js
+    rm ./scripts/sync-skills-local.js
+    echo -e "${GREEN}  ✓ Skills 同步完成${NC}"
+else
+    echo -e "${YELLOW}  跳过全局安装，同时跳过 Skills 同步${NC}"
+fi
+echo ""
+
+# 步骤4: 运行功能测试
 echo -e "${YELLOW}[4/4] 运行功能测试...${NC}"
 
 # 测试本地版本
@@ -164,15 +222,4 @@ echo ""
 echo -e "${GREEN}========================================${NC}"
 echo -e "${GREEN}  本地测试完成! ✓${NC}"
 echo -e "${GREEN}========================================${NC}"
-echo ""
-echo -e "${BLUE}下一步:${NC}"
-if [ "$SKIP_GLOBAL" = true ]; then
-    echo -e "  ${YELLOW}提示: 未更新全局安装，Skills 可能无法使用新功能${NC}"
-    echo -e "  ${YELLOW}如需测试 Skills，请重新运行此脚本并选择更新全局安装${NC}"
-    echo ""
-fi
-echo -e "  1. 运行完整测试: ${BLUE}bash ./scripts/e2e-test.sh${NC}"
-echo -e "  2. 测试 Skills: ${BLUE}npx skills add liuchenlong1111/soke-cli -y -g${NC}"
-echo -e "  3. 在 AI Agent 中测试: ${BLUE}\"查询张三的学习档案\"${NC}"
-echo ""
 

package/scripts/push.sh

@@ -236,13 +236,3 @@ fi
 
 echo "  - Aliyun (origin): master 分支已更新"
 echo "  - GitHub (github): master 和 main 分支已更新"
-
-if [[ "$IS_RELEASE" == true ]]; then
-    echo ""
-    print_highlight "📦 下一步操作："
-    echo "  1. 编译二进制文件: make build"
-    echo "  2. 发布到 NPM: npm publish"
-    echo "  3. 创建 GitHub Release (可选)"
-fi
-
-echo ""