技能介绍

要解决什么问题

在 Agent 或 WorkBuddy 里处理轻流（Qingflow）相关需求时，常见卡点不是「会不会写 API」，而是：CLI 版本是否当天已更新、是否已全局安装、账号是否已登录，以及记录字段 ID 是否与当前应用 schema 一致。本技能把上述前置条件写成固定工作流，并在 CLI 与 MCP 两套入口之间做选择，避免在对话里反复试错。

技能如何工作

执行用户请求前，技能会按顺序处理：当日版本检查（避免重复跑更新）、安装检测（无 qingflow 可执行文件则提示安装官方 @qingflow-tech/qingflow-cli）、登录状态（未登录时向用户索取邮箱与密码，在 Agent 场景下要求带 --email / --password，避免交互式终端阻塞）。若需 MCP，则在 ~/.workbuddy/mcp.json 中配置 qingflow-user 与 qingflow-builder 两个服务，并在 WorkBuddy 连接器里信任后启用。

实际执行业务时有两条路：

CLI：统一使用 qingflow … --json，便于机器解析；命令树见技能内 references/qingflow-cli-overview.md。
MCP：用户域侧重 record_*、task_* 等；搭建域侧重 app_get_fields、app_schema_apply、app_layout_apply、app_flow_apply 等（完整列表见 references/qingflow-mcp-tools.md）。

硬性约定：在 record_list 之前先调 record_browse_schema_get_public；在 record_insert_public 之前先调 record_insert_schema_get_public，否则字段类型与 ID 容易对不上。

适用边界与注意点

MCP 依赖 WorkBuddy 侧连接器已信任；仅装 CLI 时仍可走 Option A，但无法使用 MCP 工具集。
账号密码会经 CLI 完成登录，Agent 不应依赖无参数的交互式 qingflow auth login。
若出现 Transport closed、Python 未找到、版本不一致或终端中文乱码，技能文档中的 Troubleshooting 表给出了对应处理思路（如重装 CLI、设置 QINGFLOW_MCP_PYTHON、auth whoami 在无 --json 时的行为差异等）。

截图预览

使用场景

已在 WorkBuddy 信任 qingflow-user 后，先拉取 `record_browse_schema_get_public`，再按字段 ID 查询并更新某应用的公开记录。
在对话里调用 `task_list` 定位待办，对指定任务执行 `task_action_execute`（如同意、驳回、转交）。
通过 qingflow-builder 读取 `app_get_fields`，再提交 `app_schema_apply` 或 `app_flow_apply` 调整应用结构与流程。
仅安装官方 CLI、未接 MCP 时，用 `qingflow … --json` 完成记录查询或导入导出结果核对。