qskills 1.0.0 → 1.0.2

package/README.md

@@ -1,154 +1,166 @@
 # Qcli-Skills (qskills)
 
-一款面向个人开发者的 CLI 技能管理工具，支持公共技能、私人技能和知识库的统一管理与多源同步。
+一款面向个人开发者的 CLI 技能管理工具，支持多 AI 编程助手的技能、知识库、Agent 配置的统一管理与多源同步。
 
-## 特性
+## 核心特性
 
-- **一站式管理** - 将分散的技能脚本、代码片段、知识笔记统一管理
-- **多源同步** - 通过 Git 仓库实现公共资源与私人资源的分类同步
-- **即取即用** - 通过 npx 一键调用，无需全局安装
-- **安全可控** - 敏感信息检测机制，防止意外泄露
-- **跨平台** - 支持 Windows、macOS、Linux
+- **多环境支持** - 支持 Claude Code、Cursor、通义灵码、OpenAI Codex、CodeBuddy Code 等 6 个 AI 环境
+- **一站式管理** - 技能脚本、代码片段、知识笔记、Agent 配置统一管理
+- **多源同步** - 公共资源与私人资源分类同步到 Git 仓库
+- **即取即用** - npx 一键调用，无需全局安装
+- **安全可控** - 敏感信息自动检测，防止意外泄露
+
+---
 
 ## 快速开始
 
-### 使用 npx（推荐）
+### 方式一：npx 直接使用（推荐）
 
-无需安装，直接使用：
+无需安装，直接运行：
 
 ```bash
 # 查看帮助
 npx qskills --help
 
-# 初始化配置
+# 初始化配置（首次使用必须）
 npx qskills config init
-
-# 添加技能
-npx qskills skill add ./my-script.js --name my-script
-
-# 列出所有技能
-npx qskills skill list
-
-# 同步到远程仓库
-npx qskills sync
 ```
 
-### 全局安装
+### 方式二：全局安装
 
 ```bash
 npm install -g qskills
-
-# 然后可以直接使用
 qskills --help
-qskills skill list
 ```
 
-### 从 GitHub 直接使用
+---
 
-```bash
-# 使用最新版本
-npx github:your-username/qskills skill list
+## 支持的 AI 环境
 
-# 指定版本/分支
-npx github:your-username/qskills#v1.0.0 skill list
-npx github:your-username/qskills#main skill add ./my-skill
+| 环境 | 名称 | 配置目录 | 说明 |
+|------|------|----------|------|
+| `claude` | Claude Code | `~/.claude` | Anthropic Claude Code |
+| `cursor` | Cursor | `~/.cursor` | Cursor AI 编辑器 |
+| `qwen` | 通义灵码 | `~/.qwen` | 阿里云通义灵码 |
+| `codex` | OpenAI Codex | `~/.codex` | OpenAI Codex |
+| `codebuddy` | CodeBuddy Code | `~/.codebuddy` | 腾讯 CodeBuddy |
+| `common` | 通用技能 | 跨环境共享 | 适用于所有环境 |
+
+---
+
+## 使用指南
+
+### 1. 初始化配置
+
+首次使用必须先初始化：
+
+```bash
+npx qskills config init
 ```
 
-## 安装要求
+按提示完成配置，配置文件位于 `~/.qcli/config.json`。
+
+### 2. 查看可用环境
+
+```bash
+npx qskills skill envs
+```
 
-- Node.js 16.0.0 或更高版本
-- npm 8.0.0 或更高版本
+输出示例：
+```
+┌─────────────┬────────────────┬───────────┬──────────┐
+│ 环境        │ 名称           │ 配置目录  │ 状态     │
+├─────────────┼────────────────┼───────────┼──────────┤
+│ claude      │ Claude Code    │ .claude   │ ✓ 启用   │
+│ cursor      │ Cursor         │ .cursor   │ ✓ 启用   │
+│ qwen        │ 通义灵码       │ .qwen     │ ✓ 启用   │
+│ codex       │ OpenAI Codex   │ .codex    │ ✓ 启用   │
+│ codebuddy   │ CodeBuddy Code │ .codebuddy│ ✓ 启用   │
+│ common      │ 通用技能       │ (跨环境)  │ ✓ 启用   │
+└─────────────┴────────────────┴───────────┴──────────┘
+```
 
-## 命令详解
+---
 
-### 技能管理 (skill)
+## 技能管理
 
-#### 添加技能
+### 添加技能
 
 ```bash
-# 添加单文件技能
-npx qskills skill add ./script.js --name my-script
+# 基本用法：添加到指定环境
+npx qskills skill add ./my-script.js --name my-script --env claude
 
 # 添加文件夹技能
-npx qskills skill add ./my-project --name my-project --type folder
+npx qskills skill add ./my-project --name my-project --type folder --env cursor
 
-# 指定来源和标签
+# 完整参数示例
 npx qskills skill add ./tool.py \
   --name my-tool \
+  --env codebuddy \
   --source private \
-  --tags python,automation,tool \
-  --description "A useful automation tool"
-
-# 跳过安全扫描（需确认）
-npx qskills skill add ./config.json --name my-config --skip-scan
+  --tags python,automation \
+  --description "自动化工具脚本"
 ```
 
 **参数说明：**
 
-| 参数 | 简写 | 说明 | 默认值 |
-|------|------|------|--------|
-| `--name` | `-n` | 技能名称 | 必填 |
-| `--type` | `-t` | 类型：single 或 folder | single |
-| `--source` | `-s` | 来源：public 或 private | private |
-| `--tags` | | 标签（逗号分隔） | |
-| `--description` | | 描述 | |
-| `--skip-scan` | | 跳过安全扫描 | false |
+| 参数 | 简写 | 必填 | 说明 | 默认值 |
+|------|------|------|------|--------|
+| `--name` | `-n` | ✓ | 技能名称 | - |
+| `--env` | `-e` | ✓ | 目标环境 | common |
+| `--type` | `-t` | | single / folder | single |
+| `--source` | `-s` | | public / private | private |
+| `--tags` | | | 标签（逗号分隔） | - |
+| `--description` | | | 描述信息 | - |
+| `--skip-scan` | | | 跳过安全扫描 | false |
 
-#### 列出技能
+### 列出技能
 
 ```bash
 # 列出所有技能
 npx qskills skill list
 
-# 按来源筛选
+# 筛选特定环境
+npx qskills skill list --env cursor
+
+# 筛选特定来源
 npx qskills skill list --source public
 
 # 按标签筛选
 npx qskills skill list --tags python,automation
 
-# JSON 格式输出
+# JSON 格式输出（便于脚本处理）
 npx qskills skill list --json
 ```
 
-#### 搜索技能
+### 复制技能到其他环境
 
 ```bash
-# 按关键词搜索
-npx qskills skill search python
+# 将技能从 claude 环境复制到 cursor 环境
+npx qskills skill copy my-script --from claude --to cursor
 
-# 按标签搜索
-npx qskills skill search api --tags automation
+# 从公共库安装到指定环境
+npx qskills skill install api-helper --env qwen
 ```
 
-#### 删除技能
+### 删除技能
 
 ```bash
 # 删除技能（需确认）
 npx qskills skill remove my-script
 
-# 强制删除
+# 强制删除（无需确认）
 npx qskills skill remove my-script --force
 
-# 指定来源删除
-npx qskills skill remove my-script --source private
+# 指定环境删除
+npx qskills skill remove my-script --env claude
 ```
 
-#### 同步技能
-
-```bash
-# 同步所有仓库
-npx qskills skill sync
-
-# 同步指定来源
-npx qskills skill sync --source public
+---
 
-# 强制覆盖本地
-npx qskills skill sync --force
-```
+## 知识库管理
 
-### 知识库管理 (knowledge)
-
-#### 添加知识条目
+### 添加知识条目
 
 ```bash
 # 添加文档
@@ -165,7 +177,7 @@ npx qskills knowledge add ./snippet.js \
   --category utils \
   --tags javascript,utils
 
-# 添加模板
+# 添加项目模板
 npx qskills knowledge add ./template/ \
   --title "React 项目模板" \
   --type template \
@@ -175,14 +187,14 @@ npx qskills knowledge add ./template/ \
 
 **知识类型：**
 
-| 类型 | 说明 |
-|------|------|
-| `document` | 文档、笔记 |
-| `code-snippet` | 代码片段 |
-| `template` | 项目模板 |
-| `note` | 快速笔记 |
+| 类型 | 说明 | 用途 |
+|------|------|------|
+| `document` | 文档 | 技术文档、笔记 |
+| `code-snippet` | 代码片段 | 可复用代码 |
+| `template` | 模板 | 项目模板、配置模板 |
+| `note` | 笔记 | 快速记录 |
 
-#### 列出知识条目
+### 列出知识条目
 
 ```bash
 # 列出所有
@@ -194,106 +206,105 @@ npx qskills knowledge list --type code-snippet
 # 按分类筛选
 npx qskills knowledge list --category api
 
-# JSON 输出
-npx qskills knowledge list --json
+# 按环境筛选
+npx qskills knowledge list --env claude
 ```
 
-#### 搜索知识条目
+### 搜索知识
 
 ```bash
 npx qskills knowledge search "API" --category backend
 ```
 
-#### 删除知识条目
+### 删除知识条目
 
 ```bash
 npx qskills knowledge remove <id>
 ```
 
-### 配置管理 (config)
+---
+
+## Agent 管理
 
-#### 初始化配置
+### 添加 Agent 配置
 
 ```bash
-# 交互式初始化
-npx qskills config init
+npx qskills agent add ./agent-config/ \
+  --name code-reviewer \
+  --env claude \
+  --tags review,code-quality
 ```
 
-初始化过程会引导你完成：
-1. 配置存储路径
-2. 配置 Git 仓库（可选）
-3. 权限和安全设置
-
-#### 查看配置
+### 列出 Agent
 
 ```bash
-# 列出所有配置
-npx qskills config list
-
-# 获取单个配置项
-npx qskills config get storage.baseDir
-
-# JSON 输出
-npx qskills config list --json
+npx qskills agent list --env claude
 ```
 
-#### 修改配置
+---
 
-```bash
-# 设置配置项
-npx qskills config set storage.baseDir ~/.my-skills
+## 同步功能
 
-# 启用自动同步
-npx qskills config set sync.autoSync true
+### 配置远程仓库
 
-# 配置远程仓库
+```bash
+# 配置公共仓库
 npx qskills config set remotes.public.url https://github.com/user/public-skills.git
+npx qskills config set remotes.public.enabled true
+
+# 配置私人仓库
+npx qskills config set remotes.private.url git@github.com:user/private-skills.git
+npx qskills config set remotes.private.enabled true
 ```
 
-### 同步命令 (sync)
+### 执行同步
 
 ```bash
 # 同步所有仓库
 npx qskills sync
 
-# 同步指定来源
+# 只同步公共仓库
+npx qskills sync --source public
+
+# 只同步私人仓库
 npx qskills sync --source private
 
-# 预览变更（不实际同步）
+# 预览变更（不实际执行）
 npx qskills sync --dry-run
 
-# 强制覆盖
+# 强制覆盖本地
 npx qskills sync --force
 ```
 
-## 安全功能
+---
 
-### 敏感信息扫描
+## 安全扫描
 
-添加技能时自动扫描以下敏感信息：
+添加技能时自动扫描敏感信息：
 
-| 类型 | 说明 |
-|------|------|
-| AWS Access Key | AKIA 开头的密钥 |
-| GitHub Token | ghp_/gho_/ghu_/ghs_ 开头的令牌 |
-| 私钥文件 | PEM 格式私钥 |
-| API Key | api_key/secret_key 等模式 |
-| JWT Token | eyJ 开头的 JWT |
-| 数据库 URL | 包含密码的连接字符串 |
-| Slack Token | xox 开头的 Slack 令牌 |
+### 检测的敏感信息类型
+
+| 类型 | 模式示例 | 严重级别 |
+|------|----------|----------|
+| AWS Access Key | `AKIA...` | 高 |
+| GitHub Token | `ghp_...`, `gho_...` | 高 |
+| 私钥文件 | `-----BEGIN PRIVATE KEY-----` | 高 |
+| API Key | `api_key = "..."` | 中 |
+| JWT Token | `eyJ...` | 中 |
+| 数据库连接 | `mysql://user:pass@...` | 高 |
+| Slack Token | `xox...` | 高 |
 
 ### 扫描示例
 
 ```bash
-# 正常添加（自动扫描）
 npx qskills skill add ./config.js --name my-config
 
-# 发现敏感信息时会提示
+# 若检测到敏感信息：
 # ⚠️  Sensitive information detected:
 #   [HIGH] aws-access-key in config.js:10
 #   [MED] api-key-generic in config.js:15
-
-# 确认后可继续或取消
+# 
+# Continue anyway? (y/N)
 ```
 
 ### 跳过扫描
@@ -303,7 +314,38 @@ npx qskills skill add ./config.js --name my-config
 npx qskills skill add ./public-config.json --name public-config --skip-scan
 ```
 
-## 配置文件
+---
+
+## 配置管理
+
+### 查看配置
+
+```bash
+# 列出所有配置
+npx qskills config list
+
+# 获取单个配置项
+npx qskills config get storage.baseDir
+npx qskills config get remotes.public.url
+```
+
+### 修改配置
+
+```bash
+# 修改存储路径
+npx qskills config set storage.baseDir ~/.my-skills
+
+# 启用自动同步
+npx qskills config set sync.autoSync true
+
+# 配置同步间隔（分钟）
+npx qskills config set sync.syncInterval 30
+
+# 添加扫描跳过规则
+npx qskills config set scanner.skipPatterns '["*.md", "docs/**", "test/**"]'
+```
+
+### 配置文件示例
 
 配置文件位于 `~/.qcli/config.json`：
 
@@ -314,20 +356,20 @@ npx qskills skill add ./public-config.json --name public-config --skip-scan
   "storage": {
     "baseDir": "~/.qcli/data",
     "skillsDir": "skills",
-    "knowledgeDir": "knowledge"
+    "knowledgeDir": "knowledge",
+    "agentsDir": "agents"
   },
   "remotes": {
     "public": {
       "url": "https://github.com/user/public-skills.git",
       "branch": "main",
       "enabled": true
-    },
-    "private": {
-      "url": "git@github.com:user/private-skills.git",
-      "branch": "main",
-      "enabled": true
     }
   },
+  "environments": {
+    "enabled": ["claude", "cursor", "qwen", "codex", "codebuddy", "common"],
+    "default": "common"
+  },
   "sync": {
     "autoSync": false,
     "syncInterval": 0,
@@ -344,26 +386,38 @@ npx qskills skill add ./public-config.json --name public-config --skip-scan
 }
 ```
 
-## Git 认证
+---
 
-### 使用 Personal Access Token
+## Git 认证配置
+
+### 方式一：环境变量（推荐）
 
 ```bash
-# 设置环境变量
+# Linux/macOS
 export QSKILLS_TOKEN=ghp_your_token_here
 
-# 或在 Windows CMD
+# Windows CMD
 set QSKILLS_TOKEN=ghp_your_token_here
 
-# 或在 Windows PowerShell
+# Windows PowerShell
 $env:QSKILLS_TOKEN="ghp_your_token_here"
 ```
 
+### 方式二：SSH 密钥
+
+```bash
+# 使用 SSH URL
+npx qskills config set remotes.private.url git@github.com:user/private-skills.git
+```
+
 ### 创建 GitHub Token
 
-1. 访问 GitHub Settings → Developer settings → Personal access tokens
-2. 创建新 Token，勾选 `repo` 权限
-3. 复制 Token 并设置环境变量
+1. 访问 GitHub → Settings → Developer settings → Personal access tokens
+2. 点击 "Generate new token (classic)"
+3. 勾选 `repo` 权限
+4. 复制 Token 并设置环境变量
+
+---
 
 ## 存储结构
 
@@ -372,96 +426,36 @@ $env:QSKILLS_TOKEN="ghp_your_token_here"
 ├── config.json              # 配置文件
 ├── data/
 │   ├── index.json           # 本地索引
-│   ├── skills/
-│   │   ├── public/          # 公共技能
+│   ├── skills/              # 技能存储
+│   │   ├── claude/
 │   │   │   └── skill-name/
 │   │   │       ├── skill.json
 │   │   │       └── ...
-│   │   └── private/         # 私人技能
-│   │       └── skill-name/
-│   │           ├── skill.json
-│   │           └── ...
-│   └── knowledge/
-│       ├── public/
-│       └── private/
+│   │   ├── cursor/
+│   │   ├── qwen/
+│   │   ├── codex/
+│   │   ├── codebuddy/
+│   │   └── common/
+│   ├── knowledge/           # 知识库
+│   │   ├── claude/
+│   │   ├── cursor/
+│   │   └── ...
+│   └── agents/              # Agent 配置
+│       ├── claude/
+│       └── ...
 ├── public-repo/             # 公共仓库克隆
 └── private-repo/            # 私人仓库克隆
 ```
 
-## 开发
-
-### 克隆与构建
-
-```bash
-git clone https://github.com/your-username/qskills.git
-cd qskills
-
-# 安装依赖
-npm install
-
-# 构建
-npm run build
-
-# 测试
-npm test
-
-# 本地运行
-node bin/qskills.js --help
-```
-
-### 开发脚本
-
-```bash
-# 使用开发脚本（推荐）
-./docs/scripts/dev-start.sh    # Linux/macOS
-docs\scripts\dev-start.bat     # Windows
-
-# 或手动执行
-npm run dev           # 监听模式编译
-npm run test:watch    # 监听模式测试
-```
-
-### 运行测试
-
-```bash
-npm test                    # 运行所有测试
-npm run test:watch          # 监听模式
-npm run test:coverage       # 生成覆盖率报告
-```
-
-## 发布
-
-### 发布到 npm
-
-```bash
-# 1. 登录 npm
-npm login
-
-# 2. 检查发布内容
-npm pack --dry-run
-
-# 3. 发布
-npm publish
-
-# 4. 发布 beta 版本
-npm publish --tag beta
-```
-
-### 版本管理
-
-```bash
-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
-```
+---
 
 ## 常见问题
 
 ### Q: npx 提示找不到命令？
 
-确保使用 Node.js 16+：
+确保 Node.js 版本 >= 16：
 ```bash
-node -v  # 应该 >= 16.0.0
+node -v
 ```
 
 ### Q: 同步失败，提示认证错误？
@@ -477,36 +471,45 @@ export QSKILLS_TOKEN=your_token
 npx qskills config set storage.baseDir ~/custom-path
 ```
 
-### Q: 如何查看详细日志？
-
-命令添加 `--verbose` 参数（开发中）
-
-### Q: Windows 下路径问题？
+### Q: Windows 路径问题？
 
-使用正斜杠或双反斜杠：
+使用正斜杠：
 ```bash
 npx qskills skill add "./scripts/tool.js"
-# 或
-npx qskills skill add ".\\scripts\\tool.js"
 ```
 
-## 贡献
+---
 
-欢迎提交 Issue 和 Pull Request！
+## 开发与测试
 
-1. Fork 本仓库
-2. 创建功能分支：`git checkout -b feature/my-feature`
-3. 提交更改：`git commit -am 'Add my feature'`
-4. 推送分支：`git push origin feature/my-feature`
-5. 创建 Pull Request
+```bash
+# 克隆仓库
+git clone https://github.com/your-username/qskills.git
+cd qskills
 
-## 许可证
+# 安装依赖
+npm install
 
-[MIT](LICENSE)
+# 构建
+npm run build
 
-## 相关链接
+# 运行测试
+npm test
+
+# 本地运行
+node bin/qskills.js --help
+```
+
+---
+
+## 相关文档
 
 - [产品需求文档 (PRD)](docs/PRD_Qcli-Skills_20260409.md)
 - [技术规格文档](docs/TECH_SPEC_Qcli-Skills_20260409.md)
-- [验收测试报告](docs/ACCEPTANCE_TEST_REPORT.md)
-- [脚本说明](docs/scripts/README.md)
+- [测试报告](docs/TEST_REPORT_20260409.md)
+
+---
+
+## 许可证
+
+[MIT](LICENSE)