1. 项目概述：一个为AI Agent设计的UI生成记录自动化工具

如果你和我一样，每天都在用Cursor、Claude Code或者GitHub Copilot这类AI助手来生成前端页面，那你肯定也遇到过这个头疼的问题：今天到底让AI帮我写了多少代码？花了多少Token？这个月的成本是多少？哪个模型用得最多？这些问题，在一次次零散的对话里，根本没人有耐心去手动记录和统计。

我之前也试过用Excel、Notion，甚至自己写个小脚本，但都坚持不了几天。直到我意识到，既然AI能帮我写代码，为什么不让它顺便把“记账”这个活儿也干了？于是，我动手做了这个叫 ui-gen-record 的Skill。它的核心思路很简单： 让AI Agent在每次完成UI生成任务后，自动把这次“交易”的关键信息，归档到你自己的飞书多维表格里，并生成一个可视化的仪表盘。

这不是一个云端服务，所有数据都留在你自己的飞书账号下。你只需要在对话结束时，对AI说一句“ 整理到表格中 ”，它就会自动提取本次对话的模型、Token消耗、花费、源码文件，并追加到表格里。整个过程，你完全不用离开你的代码编辑器。

2. 核心设计思路：为什么选择飞书多维表格作为数据中枢

在构思这个工具时，我考虑过好几个数据存储方案：本地JSON文件、Notion API、Airtable，甚至自建数据库。最终选择飞书多维表格，是基于以下几个非常实际的考量：

2.1 数据所有权与隐私安全是首要原则

这是我最看重的一点。AI生成的内容，尤其是涉及业务逻辑的代码，本身就比较敏感。我不希望这些数据经过任何第三方服务器。飞书多维表格完美解决了这个问题：所有的表、数据、附件都存储在你自己的飞书云空间里。这个Skill本身只是一个“搬运工”，它通过官方 lark-cli 工具操作你的账号， 全程不接触、不上传你的任何对话内容或文件到外部 。数据从你的AI对话，直接进入你的飞书表格，链路最短，控制权完全在你手里。

2.2 强大的原生能力省去大量开发工作

飞书多维表格不仅仅是一个表格，它内置了公式、分组视图、多种图表类型和仪表盘。这意味着我不需要再额外开发一个数据看板。

  • 自动分组与聚合 ：我只需要在表格里创建一个“月份”字段（用公式从日期派生），飞书就能自动按月份分组展示所有记录，一目了然。
  • 实时仪表盘 ：仪表盘功能可以让我拖拽几个图表块（饼图、柱状图、指标卡），就能实时看到“本月Token总消耗”、“美元总花费”、“模型使用分布”等关键指标。如果我自己从零开发这套可视化，工作量会大得多。
  • 附件管理 ：多维表格原生支持附件字段，这太适合用来存放每次生成的源码文件（ .tsx ）和导出的压缩包（ .zip ）了。文件直接存在飞书，管理起来非常方便。

2.3 与现有工作流无缝集成

对于前端/全栈开发者来说，飞书是很多团队的协作中心。把AI生成记录放在这里，后续如果需要和团队同步成本、复盘AI辅助开发的效率，分享一个链接即可，无需额外导出数据。这种“数据产生即归档，归档即可视化，可视化即可分享”的体验，非常流畅。

2.4 技术栈的亲和性

这个Skill的核心逻辑是用Bash和Python脚本编写的，通过飞书开放的Open API和配套的 lark-cli 命令行工具进行操作。 lark-cli 用Go编写，单文件部署，授权（ lark-cli auth login ）一次后即可长期使用，非常适合集成到自动化脚本中。整个技术栈轻量、直接，没有复杂的依赖，也符合大多数开发者的使用习惯。

注意 ：虽然项目介绍里提到了多个AI Agent（Cursor, Claude Code, Codex, Copilot等），但它们的Skill机制各不相同。这个工具的核心是一套标准的记录格式和飞书API调用脚本。对于原生支持Skill的Agent（如Cursor），安装后即可直接使用指令；对于不支持的，则需要通过引用配置文件等方式来接入，这会在后面的实操部分详细说明。

3. 环境准备与详细安装指南

在开始使用之前，我们需要确保本地环境已经就绪。这个过程不复杂，但有几个关键点需要注意。

3.1 前置依赖检查与安装

打开你的终端，逐一检查以下工具是否可用：

# 1. 检查 Bash 环境（macOS/Linux 通常已内置）
which bash

# 2. 检查 curl，用于 API 调用
which curl

# 3. 检查 jq，用于解析 JSON（如果没有，需要安装）
which jq
# 安装 jq (macOS)
# brew install jq
# 安装 jq (Ubuntu/Debian)
# sudo apt-get install jq

# 4. 检查 Python3
which python3

最重要的依赖：飞书命令行工具 lark-cli 。这是与你的飞书账号交互的桥梁。

  1. 安装 lark-cli ： 访问其GitHub仓库（https://github.com/larksuite/lark-cli ），根据你的操作系统下载最新的二进制文件。对于macOS用户，通常这样操作：

    # 下载（请替换为最新的版本号）
curl -L -o lark-cli-darwin-amd64.tgz https://github.com/larksuite/lark-cli/releases/download/v0.2.5/lark-cli-darwin-amd64.tgz
# 解压
tar -xzf lark-cli-darwin-amd64.tgz
# 移动到可执行路径，例如 /usr/local/bin/
sudo mv lark-cli /usr/local/bin/
# 验证安装
lark-cli version

  2. 授权登录 ： 执行以下命令，会打开浏览器，引导你完成飞书账号的OAuth2授权。 请确保你登录的是想要创建表格的那个飞书账号 。

    lark-cli auth login

    授权成功后，凭证会保存在本地 ~/.lark-cli/config.yaml 中，后续操作无需再次登录。

3.2 获取 Skill 并安装到你的 AI Agent

接下来，我们需要把这个Skill的“指令集”安装到你的AI Agent里。

# 克隆仓库到本地
git clone https://github.com/sunxiaowei12333-netizen/ui-gen-record.git
cd ui-gen-record

# 运行安装脚本
bash scripts/install.sh

这个 install.sh 脚本做了以下几件事：

  1. 它会探测你的系统上安装了哪些AI Agent（通过检查特定的目录是否存在）。
  2. 对于探测到的Agent（如Cursor会在 ~/.cursor/skills/ ，Claude Code在 ~/.claude/skills/ ），它会在该目录下创建一个指向本项目根目录的 软链接（Symbolic Link） ，名字就叫 ui-gen-record 。
  3. 这样，当你在Agent里触发这个Skill时，它就能找到并执行本项目下的 SKILL.md 文件里定义的指令。

不同Agent的特殊处理 ：

  • 对于 Cursor / Claude Code ：上述软链接方式通常就能工作。
  • 对于其他Agent（如VS Code Copilot, Cline, Aider） ：它们可能没有统一的Skill目录。这时，你需要手动将本项目根目录下的 AGENTS.md 文件内容，包含（ @include ）到你Agent的全局配置或项目级配置文件中。具体方法需要参考你所用Agent的文档。 AGENTS.md 文件里定义了让Agent理解如何调用我们脚本的指令模板。

实操心得 ：安装后，最好重启一下你的AI Agent（比如重启Cursor），以确保它能正确加载新添加的Skill。你可以尝试在Agent的聊天框里输入“帮助”或“列出技能”，看看 ui-gen-record 是否出现在技能列表中，这是验证安装是否成功最直接的方法。

4. 核心实操：初始化你的专属记录表格

安装好Skill后，我们还需要在飞书里创建一张“数据库表”来存放记录。这是整个流程的“地基”。项目提供了两种方式：一键新建，或者绑定到你已有的表。

4.1 方式A：一键新建（首次使用强烈推荐）

如果你是第一次使用，运行以下命令：

bash scripts/bootstrap.sh

这个脚本的自动化程度很高，它会帮你完成所有脏活累活：

  1. 创建多维表格 ：通过 lark-cli 调用飞书API，在你的个人空间下新建一个名为 UI页面生成记录 的多维表格（Base）。你可以通过环境变量自定义表名，例如：

    BASE_NAME=“我的AI前端工作记录” bash scripts/bootstrap.sh

  2. 构建表结构 ：在表格里创建好我们定义的所有字段。这里的设计很有讲究：

    • Token消耗 ：设置为“数字”类型，并启用千位分隔符格式。这样在表格里显示为 1,000,000 ，同时仪表盘可以直接对它进行 SUM 求和。
    • 美元花费 ：设置为“货币”类型，币种选择USD。显示为 $25.00 ，同样支持直接求和。
    • 月份 ：这是一个“公式”字段，其公式为 TEXT([需求日期], “YYYY-MM”) 。它会自动从“需求日期”字段提取出年和月，如“2024-03”。 这个字段是实现按月分组统计的关键 。
    • 使用模型 ：设置为“单选”类型，并预置了如 Claude-3.5-Sonnet 、 GPT-4-Turbo 、 Gemini-2.0 等常见模型选项，每个选项都配有不同的颜色标签，方便在图表中区分。
    • 文件 ：设置为“附件”类型，用于上传源码和zip包。

  3. 创建分组视图 ：脚本会自动创建一个名为“按月份分组”的视图，并设置按“月份”字段降序排列，最新的月份显示在最上面。

  4. 搭建仪表盘 ：脚本会接着创建一个名为 UI生成实时统计 的仪表盘，并添加6个数据图表块：

    • 饼图 ：展示“使用最多的模型”分布。
    • 指标卡（两个） ：分别显示“Token总消耗”和“美元总花费”的实时合计。
    • 堆叠柱状图 ：展示“每月使用最多的模型”，可以看到每个月不同模型的贡献。
    • 柱状图（两个） ：分别展示“每月Token总消耗”和“每月美元总花费”的趋势。

  5. 转移所有权并保存配置 ：脚本初始会用 lark-cli 的机器人身份建表，建完后立即将表格的所有权转移（ transfer ）给你当前CLI登录的飞书账号。最后，它将新建表格的访问令牌（ base_token ）、表格ID（ table_id ）以及所有字段的ID（ field_id ）写入项目根目录下的 .config.json 文件。 这个文件已被 .gitignore 排除，确保你的隐私信息不会被意外提交到Git仓库。

脚本运行后唯一需要手动操作的一步 ： 由于飞书Open API目前没有暴露图表配色设置的接口，脚本创建的两张与“模型”相关的图表（饼图和“每月使用最多的模型”柱状图）是默认配色。你需要 手动 进入飞书多维表格的仪表盘编辑界面，为这两个图表选择一套更直观的模型色系（比如给Claude、GPT、Gemini分配不同色系），让可视化效果更好。

4.2 方式B：绑定到已有表格

如果你已经在另一台机器上初始化过，或者想和团队成员共用同一张统计表，你可以直接绑定到现有的表格。

  1. 在浏览器中打开你的飞书多维表格，复制地址栏的URL。格式类似： https://xxx.feishu.cn/base/{base_token}?table={table_id}
  2. 在项目目录下运行： 
    bash scripts/link.sh “https://xxx.feishu.cn/base/xxxxxxxxxx”
    脚本会从URL中解析出 base_token ，然后自动拉取该表格的字段列表，通过字段名反查出对应的 field_id ，并校验字段类型是否与预期匹配。校验通过后，会将配置信息写入本地的 .config.json 。

重要提示 ： link.sh 脚本依赖于表格是由 bootstrap.sh 创建的，或者至少拥有完全相同的字段名和类型。如果你手动创建了一张表，字段名哪怕差一个字符，脚本也无法正确绑定。因此，首次初始化强烈建议使用 bootstrap.sh 。

5. 日常使用流程与Agent交互细节

一切准备就绪后，日常的使用就变得极其简单。你的工作流将变成：

  1. 像往常一样使用AI Agent ：在Cursor等工具中，描述你的UI需求，例如“帮我生成一个用户登录页面，包含邮箱、密码输入框和提交按钮，使用React和Tailwind CSS”。
  2. 完成迭代 ：AI生成代码，你可能还会提出一些修改意见，比如“把按钮颜色改成蓝色”、“增加一个忘记密码的链接”。这就是一次完整的“UI生成需求”。
  3. 触发归档 ：在对话的最后，你只需要对AI Agent说：“ 把这次改动整理到表格中 ”。

接下来，Magic Happens。AI Agent（根据 SKILL.md 中的指令）会：

5.1 自动提取对话信息

  1. 识别核心参数 ：

    • 需求名称 ：Agent通常会从你的第一条主要需求描述中提取关键词，如“用户登录页面”。
    • 需求日期 ：自动取当前时间。
    • 使用模型 ：Agent会从对话的上下文或自身的 /model 命令中识别出本次对话使用的模型（例如 Claude-3.5-Sonnet ）。
    • 修改次数 ：Agent会分析本次对话历史，统计你提出的明确修改点或小需求的数量（例如“改颜色”、“加链接”算2次）。
    • Token消耗与花费 ：这是估算值。 SKILL.md 里内置了一个主流模型的价目表（如GPT-4 Turbo: $10 / 1M tokens）。Agent会根据本次对话的大致Token使用量（可从其内部接口或上下文长度估算）进行计算。 注意：这是一个估算值，并非精确扣费，主要用于趋势分析和成本感知。

  2. 收集产出物 ：

    • 预览链接 ：如果你在本地启动了开发服务器（如 npm run dev ），Agent可能会建议你填入 http://localhost:5173 之类的链接。
    • 设计稿链接 ：如果你在需求中提到了Figma或蓝湖等设计稿链接，Agent会尝试提取。
    • 源码文件 ：Agent会将本次生成的核心代码文件（通常是 .tsx 或 .jsx 组件）保存为一个临时文件。
    • 导出ZIP ：Agent可能会将整个相关的组件目录打包成一个ZIP文件。

5.2 调用脚本写入飞书

信息提取完毕后，Agent会调用本Skill的核心脚本： scripts/append.sh 。

这个脚本的工作流程如下：

#!/bin/bash
# append.sh 简化逻辑示意
# 1. 读取本地 .config.json，获取 base_token, table_id, 所有 field_id
CONFIG=$(cat .config.json)
BASE_TOKEN=$(echo $CONFIG | jq -r '.base_token')
TABLE_ID=$(echo $CONFIG | jq -r '.table_id')

# 2. 从环境变量或参数中接收Agent传递过来的数据
# 例如：DEMAND_NAME="登录页", MODEL="Claude-3.5-Sonnet", TOKEN_COST=1500, ...
# 3. 准备请求体JSON，将数据映射到对应的 field_id
JSON_BODY=$(jq -n \
  --arg field_id_for_name "$FIELD_ID_NAME" \
  --arg name "$DEMAND_NAME" \
  '{
    "fields": {
      ($field_id_for_name): $name,
      # ... 其他字段映射
    }
  }')

# 4. 使用 curl 调用飞书多维表格的“新增记录”API
curl -X POST \
  -H "Authorization: Bearer $(lark-cli auth token)" \
  -H "Content-Type: application/json" \
  -d "$JSON_BODY" \
  "https://open.feishu.cn/open-apis/bitable/v1/apps/$BASE_TOKEN/tables/$TABLE_ID/records"

脚本执行成功后，你的飞书多维表格里就会自动新增一行记录，包含了这次UI生成的所有关键信息。同时，由于仪表盘的数据源就是这张表，所以图表也会实时更新。

6. 表格与仪表盘的深度定制与维护

项目提供的表结构和仪表盘是一个开箱即用的模板，但你完全可以基于自己的需求进行深度定制。

6.1 表格字段的增删改

你可以直接进入飞书多维表格界面，像操作普通表格一样修改：

  • 增加字段 ：例如，你可以增加一个“ 项目归属 ”的单选字段，来区分不同项目产生的AI成本。或者增加一个“ 满意度评分 ”的数字字段，手动为每次生成结果打分，后续可以分析哪个模型在哪些任务上表现更好。
  • 修改字段 ：如果你主要使用某几个特定模型，可以修改“使用模型”单选字段的选项，只保留你常用的，让选择更快捷。
  • 注意 ：如果你修改了 字段名 ，那么 link.sh 脚本和 append.sh 脚本可能就无法通过字段名自动找到对应的 field_id 了。此时，你需要手动更新 .config.json 文件中的字段映射关系，或者重新运行 bootstrap.sh 创建一个新表。

6.2 仪表盘图表的个性化

飞书多维表格的仪表盘编辑器非常直观：

  • 调整图表类型 ：你觉得堆叠柱状图看模型分布不直观？可以试试换成折线图来看每个模型随月份的使用趋势。
  • 添加筛选器 ：在仪表盘上添加一个“ 项目归属 ”或“ 使用模型 ”的筛选器，可以让你动态查看特定项目或模型的统计情况。
  • 修改计算公式 ：默认的“美元总花费”指标卡用的是 SUM （求和）。你可以将其改为 AVERAGE （平均），来看看平均生成一个页面的成本是多少。

6.3 数据的备份与导出

数据安全很重要。虽然数据在飞书，但定期备份是个好习惯。

  1. 导出为CSV ：在表格视图右上角，点击“...”更多按钮，选择“导出”，可以将表格数据导出为CSV文件。
  2. 利用飞书历史版本 ：飞书多维表格有历史版本功能，可以回溯到之前任意时间点的数据状态，这本身就是一个强大的备份机制。
  3. 自动化备份 ：你可以写一个简单的定时任务（Cron Job），定期使用 lark-cli 的 bitable export 命令将表格数据导出到本地或云存储。

7. 常见问题排查与实战经验分享

在实际使用中，你可能会遇到一些问题。下面是我在开发和长期使用中总结的一些常见情况及解决方法。

7.1 Agent 无法识别或执行 Skill

  • 症状 ：对AI说“整理到表格中”，Agent没有反应，或者说“我不知道这个技能”。
  • 排查步骤 ：
    1. 确认安装 ：运行 ls -la ~/.cursor/skills/ （以Cursor为例），检查是否存在 ui-gen-record 这个软链接，并且它指向正确的项目目录。
    2. 检查Skill文件 ：确认项目根目录下的 SKILL.md 文件存在且内容完整。这个文件定义了Agent如何理解你的指令。
    3. 重启Agent ：关闭并重新打开你的AI Agent（如Cursor）。有时新安装的Skill需要重启才能加载。
    4. 查看Agent日志 ：某些Agent有调试模式或日志文件，查看其中是否有加载Skill时的错误信息。

7.2 脚本执行失败，记录未写入飞书

  • 症状 ：Agent提示正在执行，但最终报错，表格里没有新记录。
  • 排查步骤 ：
    1. 检查 .config.json ：首先确认项目根目录下是否存在 .config.json 文件。如果没有，说明初始化未成功，需要重新运行 bootstrap.sh 或 link.sh 。
    2. 检查 lark-cli 授权 ：运行 lark-cli auth status ，确认当前登录的飞书账号是否有权限操作目标表格。有时Token会过期，需要重新 lark-cli auth login 。
    3. 手动运行测试脚本 ：项目里通常有一个 scripts/test_append.sh 或类似的测试脚本。手动运行它，看是否能成功添加一条测试记录。这能帮你定位是Agent传参问题，还是脚本本身的API调用问题。
    4. 查看飞书API返回错误 ：脚本调用失败时，飞书API会返回具体的错误码和消息。仔细阅读终端输出的错误信息。常见错误有 无权限访问该表格 、 字段不存在 、 字段类型不匹配 等。

7.3 Token消耗和美元花费估算不准

  • 说明 ：这是当前方案的一个已知“特性”，而非“缺陷”。精确计算Token消耗需要接入每个AI厂商的详细用量API，这非常复杂且可能违反服务条款。
  • 应对策略 ：
    • 定位为趋势分析工具 ：明确这个工具的核心价值在于让你看清 月度趋势 （这个月比上个月多用了吗？）和 模型对比 （用Claude和用GPT哪个更“费钱”？），而不是做精确的财务核算。
    • 校准系数 ：你可以在 SKILL.md 的价目表部分，根据你的经验调整估算系数。例如，如果你发现Claude-3.5-Sonnet的实际对话成本大约是官方标价的80%，你可以把脚本里的计算系数从1.0调整为0.8。
    • 结合官方账单 ：每月初，可以对照AI服务商（如OpenAI, Anthropic）的官方账单，与仪表盘上的估算总额进行对比，了解大致的偏差范围，做到心中有数。

7.4 在多台机器或团队间同步使用

  • 目标 ：你想在公司的台式机和家里的笔记本上，都将记录归档到同一张飞书表格。
  • 方法 ：
    1. 在其中一台机器上使用 bootstrap.sh 初始化创建表格。
    2. 在另一台机器上克隆本项目，然后使用 link.sh 脚本，填入第一台机器创建好的表格URL进行绑定。
    3. 确保两台机器上的 .config.json 文件 不要 提交到Git（它已在 .gitignore 中）。你可以通过安全的渠道（如密码管理器）分享 base_token ，或者让团队成员用自己的飞书账号 link 到同一张表（需要你提前在飞书中将他们添加为表格协作者）。

我个人最深刻的一个体会是 ，这个工具最大的价值不在于它省去了你手动填表的几分钟，而在于它培养了你对AI开发成本的“体感”。以前成本是模糊的、被忽略的。现在，每次对话结束，一个简单的指令，就能让成本变得可见、可衡量。看着仪表盘上每月不断上升的柱状图，你会自然而然地开始思考：哪些需求真的需要动用最贵的模型？哪些重复性的UI组件可以沉淀成模板？这种数据驱动的反思，对于提升开发效率和优化资源分配，远比工具本身的技术细节更有意义。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

AI动态简报之算力基建篇

avatar DeepSeek技术社区
cover

端侧小模型 vs 云端大模型双轨部署：规则分流还是训练路由器的工程选择

avatar DeepSeek技术社区
cover

Agent 工具权限爆炸？最小权限原则与 DeepSeek 多租户隔离实践

avatar DeepSeek技术社区