agent-figma 是一个只读的 Figma 命令行工具，旨在让开发者或 AI 代理在终端中直接读取 Figma 设计内容，而无需打开浏览器。它通过 Figma 个人访问令牌进行认证，并以紧凑的 NDJSON 格式输出数据，便于程序化处理。
用途与主要能力：
- 解析 figma.com 链接（包括 /design/、/file/、/proto/、/board/、/branch/ 等路径）或裸文件键，并自动提取节点 ID。
- 读取页面大纲、节点详情（布局、文本、颜色、SVG 等）、文件索引、组件、样式、变量、评论、版本等。
- 以 NDJSON 格式输出记录，每行一个节点或文件，附带以 @ 为前缀的元数据行（如 @file、@styles、@components、@pagination、@budget 等）。
- 支持 --format json|yaml 将输出包装为单个对象。
- 错误以单个 JSON 对象输出到 stderr，并包含 error、fixable_by（agent|human|retry）、hint 等字段，便于自动处理。
- 提供缓存机制，按配置文件和文件版本缓存，重复读取免费。
- 支持离线模式（--offline）仅从缓存读取，以及刷新模式（--refresh）强制获取最新版本。
- 提供渲染功能，可将节点渲染为 PNG 或 SVG 并缓存到本地。
- 支持组件映射（components.json），将设计组件映射到代码组件、导入和属性。
- 提供 handoff 命令，一键导出截图、树结构、组件、样式、图标、图片和设计者注释。
- 支持 diff 命令比较设计变更，compare 命令比较实现与设计的匹配度。
使用方式： 首次使用需由人工创建 Figma 个人访问令牌，并通过 agent-figma auth add <profile> --form --expires YYYY-MM-DD [--seat full|dev|collab|view] 命令添加，令牌不会经过聊天或命令行参数。之后可使用 agent-figma auth check 验证身份和预算。常用命令包括 resolve、file index、file outline、nodes get、nodes find、render、assets fills、nodes notes 等。详细命令和标志可参考内置帮助。
适用场景：
- 开发者需要从终端快速查看 Figma 设计细节。
- AI 代理需要读取设计文件以生成代码或进行比对。
- 团队需要追踪设计变更或验证实现与设计的一致性。
- 需要控制 Figma API 调用配额的环境。
限制：
- 工具为只读，不能修改 Figma 文件。
- 依赖 Figma 个人访问令牌，且受 Figma API 速率限制（按层级 tier 计量）。
- 某些操作（如创建令牌）必须由人工完成。
- 具体收费、价格、平台支持范围等信息暂未提供。