QWencode 使用方法指南 - Sun, Mar 29, 2026

npm install -g qwencode

pip install qwencode

docker pull qwencode/qwencode:latest
docker run -it --rm -v $(pwd):/app qwencode/qwencode

qwencode --version

qwencode init

api:
  provider: openai
  apiKey: sk-...
  model: gpt-4-turbo
  baseURL: https://api.openai.com/v1
  temperature: 0.7
  maxTokens: 4096

workspace: /path/to/project

preferences:
  theme: dark
  language: zh-CN
  autoSave: true
  showLineNumbers: true
  
ignore:
  - node_modules
  - dist
  - build
  - .git
  - "*.log"

features:
  codeCompletion: true
  errorDetection: true
  testGeneration: true
  documentation: true

cd /path/to/your/project
qwencode

# 用户输入
帮我理解这个项目的架构

# QWencode 响应
项目架构分析：

技术栈：
- 前端：React + TypeScript
- 后端：Node.js + Express
- 数据库：PostgreSQL
- 缓存：Redis

目录结构：
├── src/
│   ├── components/     # React 组件
│   ├── services/       # API 服务
│   ├── utils/          # 工具函数
│   └── types/         # TypeScript 类型定义
├── tests/             # 测试文件
└── docs/              # 文档

核心模块：
- AuthModule: 用户认证
- UserModule: 用户管理
- DataModule: 数据处理

qwencode
# 输入: 分析项目结构

qwencode
# 输入: 分析 src/utils.js 的复杂度

代码复杂度报告
==================

函数：processData
- 圈复杂度：12 (高)
- 认知复杂度：8 (中)
- 代码行数：45

问题：
1. 嵌套层级过深（5 层）
2. 多个职责耦合
3. 难以测试

建议：
- 提取子函数降低复杂度
- 使用策略模式替代多重条件
- 增加单元测试覆盖

qwencode
# 输入: 修复这个错误

// 错误代码
function calculateTotal(items: Item[]) {
  let total = 0;
  for (let item of items) {
    total += item.price;
  }
  return total;
}

发现问题：
类型不匹配错误

问题分析：
- total 初始化为 number
- items.price 可能是 string 类型
- TypeScript 编译时无法确定类型

修复方案：
function calculateTotal(items: Item[]) {
  return items.reduce((sum, item) => {
    return sum + Number(item.price);
  }, 0);
}

改进：
- 使用 reduce 更简洁
- 明确类型转换
- 函数式编程风格

qwencode
# 输入: 运行应用并修复崩溃问题

qwencode
# 输入: 实现用户权限管理功能

// src/auth/permissions.ts
export enum Permission {
  READ_USERS = 'users:read',
  WRITE_USERS = 'users:write',
  DELETE_USERS = 'users:delete',
  ADMIN = 'admin:all'
}

export enum Role {
  USER = 'user',
  MODERATOR = 'moderator',
  ADMIN = 'admin'
}

export const rolePermissions: Record<Role, Permission[]> = {
  [Role.USER]: [Permission.READ_USERS],
  [Role.MODERATOR]: [
    Permission.READ_USERS,
    Permission.WRITE_USERS
  ],
  [Role.ADMIN]: [
    Permission.READ_USERS,
    Permission.WRITE_USERS,
    Permission.DELETE_USERS,
    Permission.ADMIN
  ]
};

export function hasPermission(
  userRole: Role,
  requiredPermission: Permission
): boolean {
  return rolePermissions[userRole].includes(requiredPermission);
}

// src/middleware/permission.ts
import { Request, Response, NextFunction } from 'express';
import { Permission, Role, hasPermission } from '../auth/permissions';

export function requirePermission(permission: Permission) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = req.user;
    
    if (!user) {
      return res.status(401).json({ error: 'Unauthorized' });
    }
    
    if (!hasPermission(user.role, permission)) {
      return res.status(403).json({ 
        error: 'Forbidden',
        message: 'Insufficient permissions'
      });
    }
    
    next();
  };
}

// src/routes/users.ts
import express from 'express';
import { requirePermission, Permission } from '../middleware/permission';

const router = express.Router();

router.get(
  '/api/users',
  requirePermission(Permission.READ_USERS),
  async (req, res) => {
    const users = await User.findAll();
    res.json(users);
  }
);

router.post(
  '/api/users',
  requirePermission(Permission.WRITE_USERS),
  async (req, res) => {
    const user = await User.create(req.body);
    res.status(201).json(user);
  }
);

router.delete(
  '/api/users/:id',
  requirePermission(Permission.DELETE_USERS),
  async (req, res) => {
    await User.destroy({ where: { id: req.params.id } });
    res.status(204).send();
  }
);

export default router;

qwencode
# 输入: 搜索所有未使用的变量

# 搜索代码异味
搜索所有超过 100 行的函数

# 搜索安全问题
查找所有未经验证的用户输入

# 搜索性能问题
查找所有在循环中的数据库查询

# 搜索重复代码
查找重复的代码块

qwencode
# 输入: 为 AuthService 生成完整的测试

// tests/services/auth.test.ts
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import { AuthService } from '../../src/services/AuthService';
import bcrypt from 'bcrypt';
import jwt from 'jsonwebtoken';

describe('AuthService', () => {
  let authService: AuthService;
  let mockDb: any;

  beforeEach(() => {
    mockDb = {
      findUserByEmail: vi.fn(),
      createUser: vi.fn(),
      updateUser: vi.fn()
    };
    authService = new AuthService(mockDb);
  });

  afterEach(() => {
    vi.clearAllMocks();
  });

  describe('register', () => {
    it('should register a new user successfully', async () => {
      const userData = {
        email: 'test@example.com',
        password: 'SecurePass123!'
      };
      
      mockDb.findUserByEmail.mockResolvedValue(null);
      mockDb.createUser.mockResolvedValue({
        id: '1',
        email: userData.email,
        role: 'user'
      });

      const result = await authService.register(userData);

      expect(result).toHaveProperty('id');
      expect(result.email).toBe(userData.email);
      expect(mockDb.createUser).toHaveBeenCalledWith(
        expect.objectContaining({
          email: userData.email
        })
      );
    });

    it('should hash password before storing', async () => {
      const userData = {
        email: 'test@example.com',
        password: 'password123'
      };
      
      mockDb.findUserByEmail.mockResolvedValue(null);
      const hashSpy = vi.spyOn(bcrypt, 'hash');
      
      await authService.register(userData);

      expect(hashSpy).toHaveBeenCalledWith(
        userData.password,
        expect.any(Number)
      );
    });

    it('should throw error if email already exists', async () => {
      const userData = {
        email: 'existing@example.com',
        password: 'password123'
      };
      
      mockDb.findUserByEmail.mockResolvedValue({
        email: userData.email
      });

      await expect(authService.register(userData))
        .rejects.toThrow('Email already registered');
    });

    it('should validate email format', async () => {
      const userData = {
        email: 'invalid-email',
        password: 'password123'
      };

      await expect(authService.register(userData))
        .rejects.toThrow('Invalid email format');
    });

    it('should validate password strength', async () => {
      const userData = {
        email: 'test@example.com',
        password: '123'
      };

      await expect(authService.register(userData))
        .rejects.toThrow('Password too weak');
    });
  });

  describe('login', () => {
    it('should authenticate user with valid credentials', async () => {
      const credentials = {
        email: 'test@example.com',
        password: 'password123'
      };
      
      const mockUser = {
        id: '1',
        email: credentials.email,
        password: await bcrypt.hash(credentials.password, 10)
      };
      
      mockDb.findUserByEmail.mockResolvedValue(mockUser);
      
      const result = await authService.login(credentials);

      expect(result).toHaveProperty('token');
      expect(result).toHaveProperty('user');
      expect(result.user.email).toBe(credentials.email);
    });

    it('should throw error for invalid credentials', async () => {
      const credentials = {
        email: 'test@example.com',
        password: 'wrongpassword'
      };
      
      const mockUser = {
        id: '1',
        email: credentials.email,
        password: await bcrypt.hash('correctpassword', 10)
      };
      
      mockDb.findUserByEmail.mockResolvedValue(mockUser);

      await expect(authService.login(credentials))
        .rejects.toThrow('Invalid credentials');
    });

    it('should throw error for non-existent user', async () => {
      const credentials = {
        email: 'nonexistent@example.com',
        password: 'password123'
      };
      
      mockDb.findUserByEmail.mockResolvedValue(null);

      await expect(authService.login(credentials))
        .rejects.toThrow('User not found');
    });
  });

  describe('verifyToken', () => {
    it('should verify valid token', async () => {
      const mockUser = { id: '1', email: 'test@example.com' };
      const token = jwt.sign(mockUser, process.env.JWT_SECRET!);
      
      const result = await authService.verifyToken(token);

      expect(result).toEqual(mockUser);
    });

    it('should throw error for invalid token', async () => {
      await expect(authService.verifyToken('invalid-token'))
        .rejects.toThrow('Invalid token');
    });

    it('should throw error for expired token', async () => {
      const mockUser = { id: '1', email: 'test@example.com' };
      const token = jwt.sign(
        mockUser, 
        process.env.JWT_SECRET!,
        { expiresIn: '-1h' }
      );

      await expect(authService.verifyToken(token))
        .rejects.toThrow('Token expired');
    });
  });
});

# 分步骤实现
第一步：创建数据库模型
第二步：实现基础 CRUD
第三步：添加认证和授权
第四步：添加输入验证
第五步：编写测试
第六步：编写文档

# 提供相关文件
先读取 package.json 了解项目配置
然后读取 tsconfig.json 了解类型配置
最后实现新的 API 端点

# 每次修改后验证
修改后运行：npm test
确保所有测试通过

qwencode
# 输入: 重构这段代码，应用设计模式

qwencode
# 输入: 优化这段代码的性能

// 优化前
function findUsersByName(users, name) {
  const results = [];
  for (let i = 0; i < users.length; i++) {
    if (users[i].name.toLowerCase().includes(name.toLowerCase())) {
      results.push(users[i]);
    }
  }
  return results;
}

// 优化后
function findUsersByName(users, name) {
  const searchTerm = name.toLowerCase();
  return users.filter(user => 
    user.name.toLowerCase().includes(searchTerm)
  );
}

// 进一步优化（如果多次搜索）
class UserSearcher {
  constructor(users) {
    this.index = new Map();
    users.forEach(user => {
      const key = user.name.toLowerCase();
      if (!this.index.has(key)) {
        this.index.set(key, []);
      }
      this.index.get(key).push(user);
    });
  }
  
  search(name) {
    return this.index.get(name.toLowerCase()) || [];
  }
}

qwencode
# 输入: 为这个模块生成 JSDoc 文档

qwencode
# 输入: 将这段代码迁移到 TypeScript

# API 配置
api:
  provider: openai              # openai, anthropic, azure, custom
  apiKey: sk-...             # API 密钥
  model: gpt-4-turbo          # 模型名称
  baseURL: https://api.openai.com/v1  # API 端点
  temperature: 0.7            # 生成温度 (0-2)
  maxTokens: 4096            # 最大 token 数
  timeout: 60000             # 请求超时（毫秒）

# 工作空间配置
workspace: /path/to/project    # 项目根目录
watch: true                   # 监控文件变化
autoSave: true               # 自动保存

# 界面偏好
preferences:
  theme: dark                 # light, dark, auto
  language: zh-CN            # 界面语言
  showLineNumbers: true      # 显示行号
  syntaxHighlight: true       # 语法高亮
  fontSize: 14              # 字体大小

# 忽略模式
ignore:
  - node_modules
  - dist
  - build
  - .git
  - "*.log"
  - "*.tmp"

# 功能开关
features:
  codeCompletion: true       # 代码补全
  errorDetection: true        # 错误检测
  testGeneration: true       # 测试生成
  documentation: true        # 文档生成
  refactoring: true         # 重构建议
  securityScan: false       # 安全扫描

# 集成配置
integrations:
  git:
    enabled: true
    autoCommit: false       # 自动提交
    commitTemplate: |       # 提交信息模板
      {{type}}: {{message}}
  github:
    enabled: false
    token: ghp_...
    createPR: false
  gitlab:
    enabled: false
    token: glpat-...
  jira:
    enabled: false
    url: https://your-domain.atlassian.net
    token: ...

# 性能配置
performance:
  cacheEnabled: true         # 启用缓存
  cacheSize: 100           # 缓存大小 (MB)
  parallelRequests: 3       # 并发请求数
  streamResponse: false      # 流式响应

# 日志配置
logging:
  level: info              # debug, info, warn, error
  file: ~/.qwencode/logs/qwencode.log
  maxFileSize: 10          # MB
  maxFiles: 5

qwencode --cache

# config.yaml
api:
  provider: local
  baseURL: http://localhost:11434/api  # Ollama
  model: codellama:7b

# 一次性处理多个任务
生成所有组件的测试和文档

# config.yaml
performance:
  parallelRequests: 5  # 根据网络情况调整

# config.yaml
performance:
  streamResponse: true  # 更快的响应

// settings.json
{
  "qwencode.apiKey": "sk-...",
  "qwencode.model": "gpt-4-turbo",
  "qwencode.shortcuts": {
    "openPanel": "ctrl+shift+q",
    "explainCode": "ctrl+shift+e",
    "fixCode": "ctrl+shift+f",
    "generateTest": "ctrl+shift+t"
  }
}

" .vimrc
" 打开 QWencode
nnoremap <leader>qc :QWencode<CR>

" 解释选中代码
vnoremap <leader>qe :QWencodeExplain<CR>

" 修复选中代码
vnoremap <leader>qf :QWencodeFix<CR>

" 生成测试
vnoremap <leader>qt :QWencodeTest<CR>

;; .emacs
(require 'qwencode)

(define-key global-map (kbd "C-c q") 'qwencode-open)
(define-key global-map (kbd "C-c e") 'qwencode-explain)
(define-key global-map (kbd "C-c f") 'qwencode-fix)
(define-key global-map (kbd "C-c t") 'qwencode-test)

# ~/.config/sublime-text-3/Packages/User/qwencode.sublime-keymap
[
  {
    "keys": ["ctrl+shift+q"],
    "command": "qwencode_open_panel"
  },
  {
    "keys": ["ctrl+shift+e"],
    "command": "qwencode_explain"
  },
  {
    "keys": ["ctrl+shift+f"],
    "command": "qwencode_fix"
  }
]

# .qwencode/team-config.yaml
team:
  name: "Development Team"
  codingStyle:
    indentation: 2
    quotes: single
    semicolons: true
    trailingComma: es5
  reviewGuidelines:
    requireTests: true
    requireDocs: true
    maxComplexity: 15
    enforceLinting: true
  namingConventions:
    variables: camelCase
    functions: camelCase
    classes: PascalCase
    constants: UPPER_SNAKE_CASE
    privatePrefix: _

# .github/workflows/qwencode-review.yml
name: QWencode Code Review

on:
  pull_request:
    branches: [main]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install QWencode
        run: npm install -g qwencode
      
      - name: Run Code Review
        env:
          QWENCODE_API_KEY: ${{ secrets.QWENCODE_API_KEY }}
        run: |
          qwencode review \
            --pr-number ${{ github.event.number }} \
            --output review-report.md
      
      - name: Comment Review
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('review-report.md', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: report
            });

# 1. 启动 QWencode
qwencode

# 2. 需求分析
帮我实现一个任务管理功能，包括：
- 创建任务
- 更新任务状态
- 删除任务
- 任务列表查询（支持筛选和排序）
- 任务分配

# 3. 数据库设计
生成任务的数据库模型

# 4. API 实现
实现 REST API 端点

# 5. 前端实现
生成 React 组件

# 6. 测试生成
为所有功能生成测试

# 7. 运行测试
/run npm test

# 8. 修复问题
修复测试失败的问题

# 9. 文档生成
生成 API 文档

# 1. 描述问题
用户报告：批量导入用户时偶尔失败，错误信息不明确

# 2. 代码分析
分析 src/services/userImport.ts

# 3. 诊断问题
找出潜在的竞争条件和异常处理问题

# 4. 修复代码
应用修复方案

# 5. 添加日志
添加详细的错误日志

# 6. 测试验证
创建测试用例验证修复

# 7. 性能优化
优化批量导入性能

# 1. 审查代码
审查 src/utils/ 目录下的所有代码

# 2. 分析报告
# QWencode 提供详细的审查报告：
# - 代码风格
# - 潜在问题
# - 性能建议
# - 重构建议

# 3. 应用建议
逐步应用重构建议

# 4. 验证效果
确保重构后功能正常

# .qwencode/templates/rest-api.yaml
name: REST API Endpoint
description: Generate a REST API endpoint with authentication
files:
  - path: "src/routes/{{name}}.ts"
    template: |
      import express from 'express';
      import { authenticate } from '../middleware/auth';
      
      const router = express.Router();
      
      router.post('/api/{{name}}s', authenticate, async (req, res) => {
        // Implementation
      });
      
      router.get('/api/{{name}}s/:id', authenticate, async (req, res) => {
        // Implementation
      });
      
      export default router;
  - path: "tests/{{name}}.test.ts"
    template: |
      import { describe, it, expect } from 'vitest';
      
      describe('{{name}} API', () => {
        // Tests
      });

qwencode template --name rest-api --variable name=product

customCommands:
  deploy:
    description: 部署应用到生产环境
    steps:
      - run: npm run build
      - run: docker build -t myapp .
      - run: docker push myapp:latest
      - run: kubectl set image deployment/myapp myapp=myapp:latest
  
  setup:
    description: 初始化开发环境
    steps:
      - run: npm install
      - run: npm run db:migrate
      - run: cp .env.example .env

qwencode deploy
qwencode setup

# 批量生成测试
qwencode batch --pattern "src/**/*.ts" --action generate-tests

# 批量重构
qwencode batch --pattern "src/**/*.js" --action refactor

# 批量文档生成
qwencode batch --pattern "src/**/*.ts" --action generate-docs

# 安装 git hooks
qwencode git-hooks install

# 这会创建：
# - pre-commit: 自动检查代码
# - pre-push: 运行测试
# - commit-msg: 验证提交信息