【AI学习笔记】Coze工作流写入飞书多维表格（即：多维表格飞书官方插件使用教程）

背景前摇：

今天遇到一个需求，需要把Coze平台大模型和用户的对话记录保存进飞书表格，这个思路其实不难，因为官方提供了写入飞书表格和多维表格的插件，但是因为平台教程和案例的资料匮乏，依据现有的官方文档落地起来还是有一些坑，所以决定自己写个教程记录下。

正文：

1.飞书授权Coze：

在使用多维表格插件之前，必须要先授权Coze访问飞书的数据。
进入扣子首页，点击左下角自己的头像——账号设置。


打开的页面点击“数据源”，然后给飞书点击授权。如果同时有个人账号和企业账号，允许多个账号同时授权。
第一次授权如果提示无权限的话，按照指引安装一下即可。
然后继续授权流程即可。
能在数据源这里看见自己的账号就说明成功了。

2.多维表格创建：

我们要先创建一个多维表格，作为写入的目标对象，并且编辑好多维表格要写入的目标子表名称和字段名（也就是每一列叫什么）。
这里我图省事，目标子表名称就叫默认的“表格”了。

然后这个多维表格默认创建出来里面是有几列的，看他们又有带锁的标志，数据类型又不一样的（比如第一列是文本数据，第四列是日期格式的数据），我暂时也还不知道这里面有什么奥秘，就统一全删了，然后自己添加字段。
并且这些空白数据行也需要删除，不然到时候插件会直接在空白行的下面新开一行开始写数据，而不是将就现有的空白行开始写。我这里就用记录大模型和用户的交互记录为例，字段写“用户提问”，“模型回复”，“日期”这三个。
第一个字段是索引，无法删除，不过正好是文本类型，我们把他改成用户提问就可以用。
点击加号新建字段，我们就选最简单的文本类型。
然后这个多维表格就准备好了。
表格创建完毕后，我们现在需要记住以下信息：

1.多维表格的链接。

然后就会得到形如：
这样一个链接，这个就是多维飞书表格的url。
但是还不够，把刚刚那个链接粘贴到浏览器网址栏打开，你就会发现这个链接变长了。

建议把这个更完整的链接作为参数传递给插件。
2.表格里面要工作流写入的那个子表id。
上面那个多维表格的链接中，“table = ”和“&”之间的这串符号，就是要写入的目标多维表格的id。
3.要写入子表格的名字（注意，不是多维表格的标题！！）
是这个“表格”，而不是多维表格的大标题。

4.表格里面要写入的字段（就是列名，这里是“用户提问”，“模型回复”，“日期”）。
为什么要记住这几个变量呢？我们可以看看这个多维表格插件的属性说明。
首先找到这个插件的详情页面。传送门https://www.coze.cn/store/plugin/7395043460165779483?from=store_search_suggestion
向下滚动页面，看他的插件工具，因为我们这里的需求是想把大模型和用户的对话写入飞书表格，只涉及增加操作，所以就选这个add_records即可。
我们看看这个插件的参数：是不是就是刚刚提醒大家需要记住的那几个属性。
至于字段名称，在传入records参数的时候会发挥作用，后文会介绍。

3.工作流搭建：

这个大家自由发挥，我就搭个最简明直接的一条线工作流，用户输入——大模型回复——代码节点处理——加入飞书表格——结束。
这里面最关键的，就是要有一个代码节点。
为什么呢？因为这个写入飞书表格的插件，把要写入的数据记录要求的格式特别刁钻。
要给他一个列表，列表里包含两层字典结构。field是第一层字典结构的键，对应的值又是一个字典，这个字典里面的键，就是我们刚刚多维表格里写好的列名，对应的值，就是每次调用工作流动态变化的，用户问题、模型回复，和日期。

如果没有代码节点处理，直接靠配置前面节点的引用参数的话，根本没辙，要么提示参数类型不对，要么没法动态获取每次调用生成的内容。
所以，在写入多维表格的节点前面，必须需要一个代码节点，来完成这个按需拼装输入值的伟业。
点击“在IDE中编辑”，查看代码节点细节如下：

Python代码片段：

import datetime
import json
from typing import List, Any, Dict
def json_serial(obj: Any) -> str:
    """JSON serializer for objects not serializable by default json code"""
    if isinstance(obj, (datetime.datetime, datetime.date)):
        return obj.isoformat()
    raise TypeError ("Type %s not serializable" % type(obj))

async def main(args: Args):
…            }
        }
    ]
    
    return result

如果代码不会写的话，可以用整个代码节点自带的AI，把需求描述给它，先生成一版符合这个代码节点框架要求的初稿，然后再换豆包、GPT等更聪明的AI优化。

4.配置插件参数：

授权搞定了，多维表格建好了，工作流也搭建完成了，最后我们把参数都填进插件的目标位置。
如果忘了每个参数应该填写什么也没关系，可以点击节点界面的“查看示例”参考。

或者去插件的官方页面查阅参数说明和示例。（我也是这样才搞明白url和table_id填什么）

5.（暂未解决的新问题）运行状态是forbidden：

但我运行的时候发现一个问题，状态不是success，而是forbidden。另一个账号之前运行到这个节点，会有个报错说复制链接打开去授权，但是这里并没有弹出那个授权链接。
查了下Qwen（是的最近被其他同学推荐发现这个很好用，感觉比Kimi和豆包都还舒服，说话风格很像GPT），说授权大概是这个流程：
于是我想出一个很邪修的招数，随便创建一个智能体，然后把这个add_records插件（也就是写入飞书多维表格的插件）给它加上，然后给它一个要写入飞书多维表格的指令，这样就会触发插件调用。
接着，智能体和插件调用的地方都会提醒你《未授权》，那么就给他授权就可以啦。

下图蓝色箭头标记的地方，授权二选一即可，完成后另一个待授权图标也会消失。
但我试了还是不行，之前另一个账号运行一次就success，我暂时还没找到解决方法。
后面询问了一位闲鱼大佬，说Coze和飞书账号是一对一的关系，是跟用这个智能体的账号绑定的。我对这个回答的真实性存疑，因为查了相关文档的确没有直接说明这一点，估计还是飞书开发平台的权限问题。

其他经验分享：

还有一些我在使用扣子搭建工作流中总结的经验，也一并写在这里。

1.用户提示词必须要填：

曾几何时，把系统提示词填了，输入输出参数配好了，忘了写用户提示词，导致无论给模型输入什么内容，回复都说“同学，你的问题不够明确噢~”
请教了其他同学，需要在用户提示词里面引用{{input}}，模型才真正知道它需要用哪些输入的变量。
其实更加规范的写法是，系统提示词里面写人设、限制等宏观的要求，具体的变量引用放在用户提示词的部分。
例如：
系统提示词里，只写《你是一个很有帮助的文档查阅助手，会根据用户输入和知识库查询结果来解答用户的疑问…》
用户提示词里，则列出具体的变量代表什么含义：
用户输入{{input}}
知识库查询结果{{knowledgeResult}}

就算是实在懒得给模型说明，起码也要单独放一个{{input}}，不然就会发生无论输入什么，模型都会说《同学，你的问题不够明确噢~》

2.两个节点输出，谁有结果就用谁，代码节点怎么配置：

如果把我们这个示例的工作流变得复杂一些，用户输入先过一个意图识别节点，根据意图不同，调用不同的大模型节点生成回复，并且哪个大模型有生成结果，最后传给多维表格的输入就用谁的，怎么办？
对于代码节点来说，这个很简单，只需要配置两个输入变量，分别代表俩大模型的输出，然后，在代码节点的逻辑中，同时获取俩大模型的输出，然后在组装result的时候判断谁有值就用谁组成答案即可。
Python代码片段：

import datetime
import json
from typing import List, Any, Dict
def json_serial(obj: Any) -> str:
    """JSON serializer for objects not serializable by default json code"""
    if isinstance(obj, (datetime.datetime, datetime.date)):
        return obj.isoformat()
    raise TypeError ("Type %s not serializable" % type(obj))

async def main(args: Args):
    params = args.params
    input = params['input']
    output1 = params['output1']
    output2 = params['output2']

    result: List[Dict[str, Any]] = [
        {
            "fields": {
                "用户提问": input,
                "模型回复": output1 if output1 else output2,
                "日期": json_serial(datetime.datetime.now()),
            }
        }
    ]

    return result

3.两个节点输出，谁有结果就用谁，输出节点怎么配置：

如果场景再简单一些，没有代码节点，，两个大模型直接连结束节点，谁有结果，最终就输出谁的答案，应该怎么实现呢？
很简单，给输出节点俩变量，分别代表两个大模型节点的输出，最后在“回答内容”这里通过“或”符号（就是“||”）来拼接两个输出内容即可。

参考教程：

1.B站@小吴爱折腾《如何在扣子往飞书多维表格插入数据，一个视频教会你 | 扣子教程》传送门
https://www.bilibili.com/video/BV1J5RPYHE3u/?spm_id_from=333.1007.top_right_bar_window_history.content.click&vd_source=cdfd0a0810bcc0bcdbcf373dafdf6a82

这个视频解决了我主页账号数据源授权的问题，不然自己真找不到去哪授权。

2.B站@交给AI办_展宇《Coze工作流操作飞书多维表格(写入数据)》传送门https://www.bilibili.com/video/BV1AxXfY1E7g?spm_id_from=333.788.recommend_more_video.-1&vd_source=cdfd0a0810bcc0bcdbcf373dafdf6a82

看这个视频也是用了代码节点来处理给飞书多维表格的写入数据：

3.B站@小竹熊《【coze教程】coze操作飞书表格-添加数据》传送门https://www.bilibili.com/video/BV1aaZVYrEPM?spm_id_from=333.788.recommend_more_video.19&vd_source=cdfd0a0810bcc0bcdbcf373dafdf6a82
这个是操作飞书表格的教程，也许以后会用到，先存着。
4.知乎@荣姐聊AI《手把手教你使用coze中飞书多维表格插件》传送门https://zhuanlan.zhihu.com/p/17852969533
这个帖子把全流程介绍得很清楚，其中我没有解决的运行状态是forbidden的这个疑难问题，在我另一个账号运行成功之前，就是出现了这个需要工作流内授权的情况，授权完就可以运行了，但不知道为什么我这个账号就是不成功。