Fizzy

核心用法

Fizzy CLI 是一个功能完整的项目管理命令行工具，用于管理 Fizzy 平台上的看板（boards）、卡片（cards）、步骤（steps）、评论（comments）和反馈（reactions）。用户通过 Homebrew 安装后，需配置 API Token 和账户信息（支持环境变量或配置文件），即可在终端执行完整的项目管理工作流。

主要功能模块

看板管理：创建、更新、删除看板，设置访问权限和自动延后周期。卡片操作：支持创建、更新、关闭/重新打开、延后、标记为重要（golden）、分配负责人、添加标签、移动至不同列等完整生命周期管理。步骤管理：为卡片添加待办事项，支持完成状态切换。评论系统：创建富文本评论（支持内联图片），添加表情反馈。文件上传：支持上传图片作为卡片背景或内嵌到描述/评论中。

数据查询与过滤

提供强大的列表过滤能力：按看板、列（支持伪列如 not-yet/maybe/done）、负责人、标签筛选；支持按索引 lane（all/closed/not_now/stalled/postponing_soon/golden）快速定位卡片。所有列表命令支持分页（--page）和全量获取（--all）。

JSON 处理与集成

所有命令返回结构化 JSON，可通过 jq 进行高效的数据提取、过滤和转换。文档提供了丰富的 jq 模式示例，包括字段精简、条件过滤、嵌套数据提取等。支持 --pretty 美化输出和 --verbose 调试请求。

显著优点

• 完整的 CLI 覆盖：几乎所有 Web 端功能都有对应的命令行接口
• 一致的响应格式：统一的 success/data/meta/error 结构，易于程序化解析
• 灵活的身份验证：支持环境变量（适合 CI/CD）和配置文件（适合个人使用）
• 富文本支持：HTML 描述和评论，支持通过 attachable_sgid 嵌入图片
• 清晰的资源标识：区分内部 ID 和数字编号，减少操作混淆

潜在缺点与局限性

• 双标识符系统：卡片同时使用 id（内部）和 number（CLI 命令），易混淆；其他资源仅用 id
• 列表与详情差异：steps 仅在 card show 中返回，card list 不包含，需额外查询
• 无原生限制参数：列表命令无 --limit，需通过 jq 切片（如 .data[:5]）实现
• HTML 格式要求：描述和评论需手动构造 HTML，无 Markdown 等简化格式
• 单次附件复用限制：同一 attachable_sgid 只能使用一次，多次使用需重新上传

适合人群

• 偏好终端工作流的开发者和项目经理
• 需要自动化 Fizzy 工作流、批量操作卡片的 DevOps/运维人员
• 构建 CI/CD 集成、自动化报告或数据迁移脚本的技术团队
• 自托管 Fizzy 实例的管理员

常规风险

• Token 安全：Personal Access Token 需妥善保管，避免硬编码或泄露到版本控制
• 数据误操作：delete、close 等命令不可逆，建议在批量操作前验证过滤条件
• API 限流：高频自动化脚本可能触发限流，需实现退避重试机制
• 字段路径变更：依赖特定 jq 路径的脚本可能因 API 响应结构调整而失效

核心用法

Fizzy 技能是一份完整的 CLI 使用文档，用于管理 Fizzy 看板平台中的各类资源。用户通过 Bash 执行 fizzy 命令完成看板（Board）、卡片（Card）、步骤（Step）、评论（Comment）和反应（Reaction）的全生命周期管理。核心操作包括：使用 fizzy card create 创建任务卡片并添加步骤清单，通过 fizzy card list 配合 jq 过滤查看任务状态，利用 fizzy card column 和 fizzy card assign 实现任务流转与分配，以及借助 fizzy comment create 和 fizzy reaction create 完成团队互动。技能特别强调 ID 格式区分（卡片使用 number 而非 id）、环境变量配置（FIZZY_TOKEN/FIZZY_ACCOUNT）以及 jq 数据过滤模式，支持从纯文档型工作流到复杂自动化的多种场景。

显著优点

该技能具备三大核心优势：命令行原生设计让开发者无需离开终端即可完成看板操作，与现有 DevOps 工具链无缝集成；结构化的 JSON 响应配合详尽的 jq 查询示例，大幅降低 API 学习和数据解析成本；丰富的资源覆盖从基础的 CRUD 到高级功能如卡片置顶（golden）、延期处理（postpone）、文件上传与内联图片嵌入，满足技术团队从简单任务追踪到复杂工作流自动化的多层次需求。此外，技能文档对字段差异（如 card show 与 card list 返回字段不同）、伪列（not-yet/maybe/done）和上传 ID 类型（signed_id vs attachable_sgid）的细致说明，有效减少了实际使用中的常见错误。

潜在缺点与局限性

技能存在明显的生态依赖限制：Fizzy 平台本身非主流工具，相比 Trello、Jira、Notion 等拥有更小用户基础和第三方集成生态，团队迁移或协作时可能面临兼容性问题；纯文档型设计意味着 Skill 本身不包含可执行代码，Agent 需要依赖外部安装的 fizzy-cli，Homebrew 安装源 robzolkos/fizzy-cli/fizzy-cli 属于个人维护 tap，长期稳定性和更新频率存在不确定性；令牌管理负担，虽然文档推荐环境变量配置，但 FIZZY_TOKEN 的权限控制（Read + Write）和轮换机制仍需用户自行保障；无实时同步机制，所有操作基于轮询 API，不适合需要秒级响应的实时协作场景。

适合的目标群体

该技能最适合三类用户：技术驱动型小团队（10-50 人），尤其是已有命令行工作习惯的开发、运维或产品团队，希望在看板管理中保持与 Git、CI/CD 一致的操作体验；自动化工作流构建者，需要将任务管理与现有脚本、定时任务或 ChatOps 机器人集成的场景；自托管需求用户，技能文档明确支持 FIZZY_API_URL 配置，适合对数据主权有要求、希望私有化部署的企业。不适合非技术背景成员占比高的团队，或依赖丰富可视化报表、高级权限矩阵和庞大插件市场的大型组织。

使用风险与注意事项

来源可信度风险：技能维护者为个人开发者（portavion），CLI 工具通过非官方 Homebrew tap 分发，建议验证源码仓库完整性并关注更新动态。令牌安全：Fizzy Token 需具备写权限，泄露可能导致数据篡改，务必使用环境变量而非硬编码或配置文件存储。操作不可逆性：card delete、comment delete 等操作无回收站机制，自动化脚本中应增加二次确认逻辑。字段变更风险：API 响应结构随版本迭代可能调整，依赖特定 jq 路径的自动化流程需建立监控。网络与性能：--all 分页拉取大数据集时可能触发速率限制，建议分批次处理并增加错误重试。