QZhuli CLI 使用说明

1. 安装

全局安装（推荐）

全局安装后，可以直接在任意目录运行 qz

npm install -g @qzhuli/qzhuli-cli
qz --version

也可以使用 pnpm：

pnpm add -g @qzhuli/qzhuli-cli

想让全局命令使用最新版本，请重新执行：

npm install -g @qzhuli/qzhuli-cli

当前项目内安装

如果不希望全局安装：

npm install @qzhuli/qzhuli-cli
npx qz --version

项目内安装不会自动替换系统中已有的全局 qz。如果 qz --version 显示的版本没有变化，请检查实际使用的路径：

which qz
type -a qz
npx qz --version

2. 第一次使用

先确认 CLI 可执行：

qz --version
qz --help

首次使用需要登录 Q 助理：

qz auth login

默认使用二维码登录。登录后检查状态：

qz auth status

退出登录并清除本地凭据：

qz auth logout

除查看状态外，大多数联系人、会话和消息操作都需要先登录。

获取更多帮助

任何命令都可以使用 --help或-h 查看当前版本的参数：

3. 配置语言

查看当前配置：

qz config

切换输出语言：

qz config --locale zh
qz config --locale en

4. 用户、好友和关系

查询用户

默认按 Q助号查询：

qz user search <q-number>

按 UID 查询：

qz user search <uid>

添加好友

qz user add <q-number>

查看好友和联系人

qz friend list

按昵称或 UID 查询好友资料：

qz friend profile "昵称"
qz friend profile <uid> --uid

查看和更新关系

查看关系：

qz relation get <uid>

更新备注或关系类型：

qz relation set <uid> --remark "项目联系人"
qz relation set <uid> --type 5

5. 会话和消息

发送消息、查看历史记录和查看会话资料需要的是 conversationId，不是好友的 UID。可以先列出或搜索会话，再复制返回结果中的 conversationId。

列出会话：

qz conversation list
qz conversation list --limit 20 --offset 0

查看会话资料：

qz conversation profile <conversation-id>

如果目标用户还没有会话，可以创建会话：

qz conversation create <uid> --agent-id <agent-id>

发送消息

qz message send <conversation-id> "你好"

发送者角色默认为 Assistant。以用户身份发送时使用：

qz message send <conversation-id> "这条消息以用户身份发送" --role 1

角色取值：0 为 Assistant，1 为 User。发送前请确认会话 ID、消息内容和发送角色。

查看消息历史

查看最近消息：

qz message history <conversation-id>

6. QFlow 需求管理

QFlow 使用独立的登录状态。首次使用时先确认 Q 助理登录，再登录 QFlow：

qz auth status
qz qflow auth login
qz qflow auth status

项目和需求查询

查看项目：

qz qflow project list

查看我的需求

qz qflow requirement mine

列出待领取的需求

qz qflow requirement unclaimed

查询指定项目的需求

qz qflow requirement list --project-id <project-id>

按需求阶段筛选，例如“待领取”

qz qflow requirement list --status "待领取"

查看需求详情、成员、活动和评论：

qz qflow requirement get <requirement-id>
qz qflow requirement members <requirement-id>
qz qflow requirement members <requirement-id> --keyword "关键词"
qz qflow requirement activities <requirement-id>
qz qflow requirement comments <requirement-id>

创建需求

先确认目标项目：

qz qflow project list

使用文本创建：

qz qflow requirement create \
  --project-id <project-id> \
  --title "增加导出功能" \
  --priority 中 \
  --category 新功能 \
  --content "需求背景、目标和验收标准"

优先级支持：紧急、高、中、低。需求类型支持：功能优化、BUG修复、新功能、技术优化。

更新需求和协作

评论需求：

qz qflow requirement comment <requirement-id> --content "补充验收条件"

流转需求状态：

qz qflow requirement transition <requirement-id> --to <stage> --remark "流转原因"

提醒当前负责人：

qz qflow requirement urge <requirement-id>

7. 可选：安装给 AI Agent 使用的技能

QZhuli CLI 包含一个供 AI Agent 读取的 SKILL.md。如果需要让 Agent 按照 QZhuli CLI 的 ID 类型、确认规则和常用流程操作，可以安装该技能：

npx -p @qzhuli/qzhuli-cli qz-install-skill --target <agent-skill-dir>

查看技能版本：

npx -p @qzhuli/qzhuli-cli qz-install-skill --version

更新已安装的技能：

npx -p @qzhuli/qzhuli-cli qz-install-skill --update