QCI — QoderCN Resource Installer

一个基于 TypeScript 的 CLI 安装器，从 Git 仓库或本地路径安装 Skill、Agent、MCP、指令 资源到 QoderCN Desktop。

安装

# 无需安装，直接使用
npx @annopick/qci add <source>

# 或全局安装
npm install -g @annopick/qci
qci add <source>

快速开始

# 从 Git 仓库安装所有资源
npx @annopick/qci add https://github.com/your-org/your-skills-repo

# 从本地路径安装
npx @annopick/qci add /path/to/your-skills-repo

# 使用 SSH 克隆
npx @annopick/qci add [email protected]:your-org/your-skills-repo.git

# 只查看仓库中有哪些可用资源
npx @annopick/qci add https://github.com/your-org/your-skills-repo --list

命令

add — 安装资源

qci add <source> [options]

| 选项 | 说明 | |------|------| | --all | 安装所有发现的资源 | | --skill [name...] | 只安装 Skill（不指定名字则安装所有 Skill） | | --agent [name...] | 只安装 Agent（不指定名字则安装所有 Agent） | | --mcp [name...] | 只安装 MCP 服务（不指定名字则安装所有 MCP） | | --command [name...] | 只安装指令（不指定名字则安装所有指令） | | --path <subpath> | 指定仓库内的子目录（仅 Git 来源） | | --list | 列出可用资源，不安装 | | -y, --yes | 跳过确认提示 |

# 只安装所有 Skill（其他类型不装）
qci add https://github.com/org/repo --skill

# 安装所有 Skill 和所有指令
qci add https://github.com/org/repo --skill --command

# 只安装指定的 Skill 和 MCP
qci add https://github.com/org/repo --skill code-review --mcp github

# 从大型仓库中指定子目录
qci add https://github.com/org/repo --path skills/team-a

list — 列出已安装资源

qci list [options]

| 选项 | 说明 | |------|------| | --skill | 只列出 Skill | | --agent | 只列出 Agent | | --mcp | 只列出 MCP 服务 | | --command | 只列出指令 | | --json | JSON 格式输出 |

remove — 移除已安装资源

qci remove [options]

| 选项 | 说明 | |------|------| | --skill <name...> | 移除指定 Skill | | --agent <name...> | 移除指定 Agent | | --mcp <name...> | 移除指定 MCP 服务 | | --command <name...> | 移除指定指令 | | --all | 移除所有资源 |

update — 更新已安装资源

qci update [options]

| 选项 | 说明 | |------|------| | --skill <name...> | 只更新指定 Skill | | --agent <name...> | 只更新指定 Agent | | --mcp <name...> | 只更新指定 MCP 服务 | | --command <name...> | 只更新指定指令 |

更新时从原始来源重新拉取，自动检测变更。MCP 服务更新时同名配置会被覆盖。

资源仓库目录结构

资源仓库需遵循以下目录结构：

repo/
├── skills/
│   └── <skill-name>/
│       ├── SKILL.md          # 必须含 name 和 description 的 YAML frontmatter
│       └── (references/, scripts/ 等子目录)
├── agents/
│   └── <agent-name>.md       # 必须含 name 和 description 的 YAML frontmatter
├── mcp/
│   └── <mcp-name>/
│       ├── MCP.md             # 推荐：YAML frontmatter + JSON 正文，支持变量占位符
│       └── mcp.json           # 兼容旧格式：标准 mcpServers JSON 结构
└── commands/
    └── <command-name>.md      # 可选含 description 的 YAML frontmatter

每种资源类型都是可选的——仓库可以只包含 Skill、只包含 Agent，或任意组合。

Skill（技能）

标准 Anthropic skill 格式，由 SKILL.md 定义：

---
name: code-review
description: 代码审查技能
---

技能内容...

Agent（自定义智能体）

Qoder 自定义智能体，由 .md 文件定义：

---
name: security-audit
description: 安全审计专家
tools: Read, Grep, Bash
---

你是一位安全审计专家...

MCP（Model Context Protocol）

支持两种格式，MCP.md 优先，不存在时回退到 mcp.json。

MCP.md（推荐）

YAML frontmatter 定义变量元数据，JSON 正文中使用 {{VAR_NAME}} 占位符引用。安装时原始文件会被保留到 ~/.qoder-cn/mcp/<name>/MCP.md，由 QoderCN Desktop 在运行时替换变量值。

---
name: github
description: GitHub MCP server
variables:
  - name: GITHUB_TOKEN
    description: GitHub API token
    type: string
    required: true
    sensitive: true
---

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "{{GITHUB_TOKEN}}" }
    }
  }
}

变量占位符 `{{VAR_NAME}}` 可用在 JSON 正文的任何字符串位置，包括 `env` 字段和 `args` 数组中的 URL：

```markdown
---
name: my-private-mcp
description: Private MCP server with token in URL
variables:
  - name: PRIVATE_TOKEN
    description: Token for private package registry
    type: string
    required: true
    sensitive: true
---

```json
{
  "mcpServers": {
    "my-private-mcp": {
      "command": "uvx",
      "args": [
        "--index-url",
        "https://user:{{PRIVATE_TOKEN}}@private-registry.example.com/org/pypi/-/packages/simple",
        "my-private-mcp-pkg"
      ]
    }
  }
}

变量字段说明：

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 变量名，与 JSON 中的 `{{name}}` 对应 |
| `description` | string | 是 | 变量描述，用于提示用户输入 |
| `type` | string | 否 | `string`（默认）/ `number` / `boolean` |
| `required` | boolean | 否 | 是否必填，默认 `true` |
| `sensitive` | boolean | 否 | 是否敏感值，默认 `true` |

#### mcp.json（兼容旧格式）

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "..." }
    }
  }
}

指令（Command）

Qoder 自定义指令，由 .md 文件定义，文件名即指令名：

---
description: 代码检查指令
---

## 概述
用于评估源代码的系统化框架...

YAML frontmatter 为可选，无 frontmatter 的文件也会被正常安装。

安装位置

| 资源类型 | 路径 | |---------|------| | Skill | ~/.qoder-cn/skills/<name>/ | | Agent | ~/.qoder-cn/agents/<name>.md | | 指令 | ~/.qoder-cn/commands/<name>.md | | MCP（macOS） | ~/Library/Application Support/QoderCN/SharedClientCache/mcp.json | | MCP（Windows） | %APPDATA%\QoderCN\SharedClientCache\mcp.json | | MCP 原始文件 | ~/.qoder-cn/mcp/<name>/MCP.md |

本地开发

# 克隆仓库
git clone https://github.com/Annopick/qoder-cn-installers.git
cd qoder-cn-installers

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

# 本地链接为全局命令
npm link
qci --help

技术栈

• TypeScript + ESM
• tsup 构建
• @clack/prompts CLI 交互
• yaml frontmatter 解析
• Node.js >= 24

License

MIT