AI 编程常见问题

本文介绍 AI 编程的常见问题。

项目开发

工作空间中的成员为什么无法编辑项目？

默认情况下，AI 编程项目仅允许其所有者进行编辑和部署。如需多人协作，项目所有者可以邀请其他成员成为协作者，共同编辑项目。

为什么我的项目无法跨空间复制？

AI 编程项目默认支持跨工作空间复制。但如果项目中接入了外部集成（如飞书消息等），则无法进行跨工作空间复制。

如何查看智能体使用的模型？

你可以在智能体开发页面的预览窗口查看该智能体使用的模型 。

终端功能支持远程连接吗？

暂不支持。
在 AI 编程环境中，右侧工作区的终端功能兼容传统终端的常见命令操作，但暂不支持本地设备通过 SSH 等方式远程连接到 AI 编程环境。

如何获取网页的访问地址？

1. 在应用开发页面，在右侧单击➕打开新的标签页，在弹出的标签页中选择部署。
   
2. 在部署的总览页面，在生产环境版本的下方可查看该网页应用的公开访问地址。
   
   如果配置了多个自定义域名，默认展示第一个自定义域名。

我可以更改网页应用的访问地址吗？

• 若网页使用扣子编程提供的默认域名，则网页的访问地址不支持更改。
• 若网页使用自定义域名，你可以通过以下步骤更改网页访问地址：
  1. 在域名管理页面删除原有域名。
     
  2. 重新添加新的自定义域名，再重新部署应用。 添加自定义域名的方法请参考配置自定义域名。
     

扣子 AI 生成的代码支持修改吗？

扣子编程提供了一个基于 Web 的 AI 编程开发环境，你可以在代码编辑器中修改代码文件、在终端中执行命令调试代码，和扣子 AI 一起开始开发你的项目。关于 AI 编程开发环境的使用技巧，可参考AI 编程环境。
常见操作如下：

怎么接入扣子 AI 编程开发的智能体和工作流？

你需要将扣子 AI 编程开发的智能体和工作流部署为 API 服务，然后通过 API 调用的方式将其接入到你的系统或应用中，部署的智能体和工作流的详细操作，可参考部署智能体、部署工作流。

怎么查看工作流的日志？

• 试运行阶段，你可以在 AI 编程开发页面的下方，单击运行记录，在下拉列表中选择对应的时间，单击各个工作流节点，可以查看每个环节的消息调用链记录。
  
• 部署上线后，你可以在部署 > 日志页面查看日志信息，详细操作可参考查看日志和 Trace。

上传文件时提示文件过大失败怎么办？

在已部署的 AI 编程项目中上传文件时，单个文件不可超过 16 MB。
如果项目中经常需要传输较大文件，你可以在 AI 编程开发页面的左侧对话框中，让扣子 AI 实现分片上传。指令示例：

当文件超过 16MB 时会遇到错误，现在帮我实现一个分片上传接口，当文件大小大于 16MB 时，将文件分片上传，单个分片不大于 4MB。

在生图等场景中出现连接超时怎么办？

用户使用 AI 编程项目时，如果客户端与服务端无任何数据传输，HTTP 连接最长保持 300 秒。在生图渲染、多轮对话等需要持续连接的场景中，为避免连接断开，需至少每 300 秒发送一次心跳信号，确保服务器与设备的连接持续活跃。你可以在 AI 编程开发页面的左侧对话框中，让扣子 AI 实现心跳保活功能。指令示例：

帮我实现一个心跳保活功能：在生图任务执行期间，每 85 秒自动向服务端发送一次 PING 信号（避免 300 秒超时阈值），确保 HTTP 长连接不中断，包含连接状态监测和自动重连逻辑。

AI 生成的代码可以下载吗？

在扣子 AI 编程项目中，AI 生成的文件可以一键压缩并下载到本地。操作步骤如下：

1. 在 AI 编程项目开发页面右上角单击文件夹图标，打开文件树。
2. 在文件树区域单击下载图标。
   

项目发布后图片、文件不展示，如何处理？

项目开发阶段上传的图片、文件等资源可正常读取与展示，但在项目部署后，无法加载对应的资源，这是因为开发环境与生产环境的文件存储路径不一致。开发阶段的资源存储在 /workspace/project/assets 中；项目部署后，资源存储路径变更为 /opt/bytefaas/assets，导致环境切换后资源定位失败。
你可以在开发项目时，告诉扣子 AI，使用 COZE_WORKSPACE_PATH 环境变量来管理存储路径，将资源存储路径设置为 /$COZE_WORKSPACE_PATH/assets。

如何选择协作模式？

在开发 AI 编程项目时，你可以根据当下的需求，在 Agent 模式与问答模式之间自由切换。
Agent 模式：让 AI 帮你完成工作
在这种模式下， 扣子 AI 是你的“执行助手”，能够提取你的指令，自主拆解任务步骤、编写并修改代码、自动调试，实现端到端的任务闭环。
在 Agent 模式下，你还可以灵活设置两种运行模式：

• 运行所有指令：扣子 AI 将自动执行拆解、开发、测试项目等操作，无需你手动确认。
• 危险操作需确认：当扣子 AI 遇到删除文件、重构大段代码或修改核心逻辑等高风险操作时，会暂停执行并向你请求确认。只有得到你的许可后，它才会继续执行。

问答模式：与 AI 探讨开发思路
在这种模式下，扣子 AI 是你的“资深顾问”，专注于辅助你思考，不会改动你的项目，它主要通过对话帮助你，理清思路，针对你提出的需求进行深度解析，提供解释、优化建议或示例代码。
如果你对需求不确定，可以先在问答模式下讨论方案，待方案确认后，再切换到Agent 模式，由扣子 AI 根据此前的讨论结论执行开发任务。
计划模式：先定开发方案，分步落地执行
在这种模式下，扣子 AI 是你的“项目规划师”。收到需求后，扣子 AI 会先梳理整体开发逻辑、拆分阶段任务、生成清晰的开发计划。并且在需求分析过程中，如果需求不明确，它会逐个向你确认关键的开发方向。
当你确认开发计划后，扣子 AI 会自动切换到 Agent 模式，执行开发任务。

Agent 模式

问答模式

计划模式

你可以参考如下步骤，切换协作模式。

开启设计引导，有什么效果？

当你在开发网页应用、移动应用、小程序时，如果开启设计引导功能，扣子 AI 会引导你先选择设计风格，产出原型，再开发项目，具体流程如下：

1. 选择风格：扣子 AI 会加载原型设计技能，并提供多种预设的设计风格供你选择。
2. 生成原型：在你选定风格后，扣子 AI 会继续加载原型设计技能，生成原型。
3. 开发项目：确认原型设计符合你的预期后，扣子 AI 将根据此原型生成最终代码，完成项目开发。

多人协作时，同时发送需求会冲突吗？

A：不会，系统具备有序协作机制。当多人同时发送需求时，扣子 AI 会依照提交的先后顺序逐个处理，不会产生冲突。

项目所有者和协作者权限分别有哪些？

如何退出多人协作项目？

项目创建者可以移除协作者，协作者可以自主退出项目。

多会话和多对话的主要区别是什么？

扣子 AI 编程项目中有两个并发开发的基本单元：会话和对话。

多会话/多对话的任务是并发进行的吗？

是的。在多会话/多对话模式下，你在不同会话/对话中同时发起的任务会并发执行。

多会话/多对话模式下，同时发送需求会冲突吗？

• 多会话：每个会话拥有独立的工作区和代码副本，同时发送需求不会产生冲突。合并时，扣子 AI 会自动进行冲突检查并修复。
• 多对话：多个对话共享同一份代码，如果同时修改同一个代码文件，可能会产生冲突。为确保代码稳定，扣子 AI 在开发过程中会实时同步文件变更，并在检测到代码存在逻辑问题或运行异常时，自动进行修复。

多会话/多对话模式下，新会话/对话是基于一个全新的空项目吗？

不是。

• 新会话：基于来源分支创建独立工作分支，并复制一份当前代码。你可以在此会话上独立开发，不影响来源会话。
• 新对话：直接使用项目主会话现有的代码文件。它只是提供一个全新的、空白的对话上下文，方便你基于现有代码开始一个全新的任务。

多会话/多对话模式下，我可以在不同的会话/对话中预览不同的开发效果吗？

多会话和多对话的预览机制不同：

• 多会话：每个会话拥有独立的预览环境，可以在不同会话中预览各自的开发效果。
• 多对话：所有对话共享同一个预览环境，预览结果反映的是当前所有对话已完成的最新代码状态，无法单独预览某个对话的效果。

预览页面提示开发态沙箱容量占用率高？

如果 AI 编程项目开发调试过程中，预览页面提示 CPU 或内存占用率过高，你可以尝试以下方式解决：

• 释放容量：在预览页面右下角单击释放容量，编程 AI 会重新加载“开发环境问题诊断”技能，帮你清理内存和磁盘。
• 为开发态沙箱扩容：预览页面默认部署在云端沙箱，各个项目类型的默认容量不同。你可以在预览页面单击提醒信息，选择更高的 CPU 和内存配置，以提高预览页面的性能。
  需要注意的是，仅个人旗舰版及更高的订阅套餐支持调整预览页面的沙箱容量配置。
  

集成服务

如何查看内置集成消耗的积分？

你可以在积分消耗页面中查看各个项目中内置集成服务的调用情况及消耗的积分。具体操作，请参考查看账号消耗明细。

如何切换大语言模型？

当你开发了具备 AI 功能的智能体或工作流时，扣子 AI 会自动提供预置的大语言模型，你可以在界面上切换大模型。例如在智能体页面，你可以单击界面上显示的大语言模型，然后在模型列表中切换为其他模型。也可以通过自然语言告诉扣子 AI 需要使用的大语言模型。切换后，需要重新部署才能使线上的项目使用新模型。

智能体模型替换为Doubao-Seed-1.6-Lite

如何批量切换待下架模型？

当某个模型即将停运时，工作空间的所有者或管理员可以快速定位当前工作空间下所有使用该模型的 AI 编程项目，并批量为这些项目的线上版本切换模型。模型停运 7 天内，仍支持批量切换模型。

1. 在扣子编程的集成管理页面，单击目标大语言模型。
2. 在模型用量页签下，单击切换模型。
   
3. 选中待切换模型的项目，单击确认切换模型，然后选择新模型，单击确定。

4. 查看新旧模型的对比信息，确认新模型符合需求后，单击确定，完成模型切换。

切换完成后，状态将更新为项目已完成模型切换。新模型的用量图表数据将在次日自动更新。

向飞书多维表格推送数据时，提示 [1254045]: FieldNameNotFound错误，如何处理？

向飞书多维表格推送数据时，提示 [1254045]: FieldNameNotFound错误，核心原因是工作流输出的字段名称与飞书多维表格的表头名称不匹配，或者字段数据类型不匹配。请严格按照工作流的输出字段名称及其数据类型，准确设置飞书多维表格的表头。
你也可以继续与 AI Agent 对话，让其帮助定位问题，并准确提供具体的输出字段及数据类型。

组织管理员禁用了某个外部集成后，空间里原已配置的集成是否能继续使用？

如果组织管理员禁用指定工作空间内的某个外部集成前，该外部集成已在工作空间完成配置，那么该外部集成在该工作空间内不受禁用操作影响，仍可正常接入 AI 编程项目。未配置该外部集成的工作空间，将无法配置外部集成。

接入飞书消息集成后，为什么空间内的项目都使用同一个飞书机器人发送消息？

扣子编程的外部集成采用空间内一次性配置原则。外部集成配置完成后，该工作空间内的所有项目均可共享使用。因此工作空间内接入了飞书消息集成的 AI 编程项目，均通过该配置对应的同一个飞书机器人发送消息。

支持接入第三方的 API 吗？

支持。你可以通过如下方式接入第三方的 API 。

• 通过自然语言描述你的接入需求，并提供 API 关键信息，如 API Key、接口地址等，扣子 AI 将自动在项目中编写代码并接入 API。
• 你也可以在项目开发过程中，修改代码文件，自行接入第三方 API。

为什么我的空间无法配置外部集成？

出于安全和控制考虑，团队高阶版、团队旗舰版、团队尊享版、企业旗舰版的外部集成访问权限默认处于关闭状态，需要先由组织管理员在集成管理页面，为指定的工作空间启用外部集成。具体操作，请参考步骤二：在工作空间中配置集成的连接。

如何设置级联删除？

在创建数据表时，可以添加外键关系，并通过如果引用的行删除时的操作配置，来实现级联删除。即指定父表行删除时对子表关联行的处理规则，选项如下：
Cascade：从父表中删除一行时，将进行级联删除，即子表中所有相关的行也会被删除。
Restrict：从父表中删除一行时，如果子表中存在任何相关行，则删除操作将被中止。
Set NULL：当从父表中删除一行时，子表中外键列的值将被设置为 NULL。
Set default：当从父表中删除一行时，子表中外键列的值将设置为其默认值。
No action：当从父表中删除一行时，如果子表中存在任何相关行，将引发报错。

各个项目之间的数据库是共享的吗？

不同 AI 编程项目的数据库相互独立，不支持共享使用。

如何为项目接入数据库能力？

你需要在开发 AI 编程项目时，通过与扣子 AI 对话为项目接入数据库能力。如果仅在可视化界面开通数据库，实际并未完成项目的数据库接入。

各个项目之间的存储桶是共享的吗？

不同 AI 编程项目的对象存储桶是相互独立的，不支持共享使用。

如何为项目接入对象存储能力？

你需要在开发 AI 编程项目时，通过与扣子 AI 对话为项目接入对象存储能力。如果仅在 AI 编程环境的集成管理页签中开通对象存储，并未为项目接入对象存储能力。

各个项目之间的环境变量是共享的吗？

不同 AI 编程项目的环境变量是相互独立的，不支持共享使用。

项目能使用自定义模型吗？

扣子 AI 编程项目支持集成自行部署的模型或第三方在线模型（如火山方舟大模型）。在项目开发过程中，你可以通过自然语言向扣子 AI 描述自定义模型接入需求，并提供 API 信息，如 API Key、接口地址等。

发送图片到企业微信，出现 SignatureDoesNotMatch 错误，如何处理？

由于企业微信侧的限制，为项目接入企业微信机器人外部集成后，发送图片到企业微信时，企业微信侧将在扣子编程生成的图片 URL 后面添加 wework_cfm_code **** 参数，导致服务端验证签名时与原始签名不一致，从而出现 SignatureDoesNotMatch 错误。目前，建议发送图片前，先调用企业微信的图片上传接口，将所有用于机器人消息的图片上传至企业微信素材库，获取官方资源 ID。

部署运维

扣子生成的免费证书和火山证书有什么区别？

扣子生成的免费证书用的是火山引擎免费证书，不过它的有效期只有 3 个月。自己买的火山证书有效期更长，一般是 1 年。具体区别请参考免费证书概述。

可以使用其他厂商的 SSL 证书吗？

默认使用火山引擎 SSL 证书，如果你拥有其他厂商的证书，你可以在火山引擎证书中心控制台上传证书，具体请参考上传证书。上传成功后即可在扣子编程的配置域名页面中选择并添加该 SSL 证书。

免费证书到期后能生成新的免费证书吗？

免费证书到期后，你可以重新生成新的免费证书，但会消耗免费证书的额度。火山引擎主账号及子账号在一个自然年内共享 20 个免费证书的总额度，达到额度上限后，你需要及时切换为付费的火山引擎证书，或等待下一自然年额度重置后，重新生成免费证书。

部署失败时如何修复？

部署失败时，你可以通过对话让扣子 AI 帮你修复问题。

1. 部署失败时，在部署页面的日志中会显示详细的错误信息，你可以拷贝错误日志。
2. 在左侧对话框中，粘贴错误日志并让 AI 自动修复该错误。
3. AI 修复完毕后，重新部署项目。

当然，你也可以直接单击一键修复按钮，系统会自动将错误日志发送给扣子 AI，帮助你修复问题。

能调用历史部署版本的智能体或工作流吗？

仅支持通过 API 调用生产环境运行版本的智能体或工作流，不能调用历史部署版本的智能体或工作流。

如何查看网页应用的历史部署版本？

参考以下流程查看：

1. 在项目管理页面找到并打开指定的网页应用。
2. 在右侧新建页签，打开部署 > 总览页面。
3. 找到状态为部署成功的版本。
4. 展开右侧的折叠按钮，单击查看。
   
5. 复制网页应用的 URL。
   

重新部署后，之前的 API Token 还能继续使用吗？

重新部署智能体或工作流后，原有的 API Token 仍然有效。不同部署版本的 API Token 通用，重新部署不会影响原有 API Token 的正常使用。

忘了 API Token 怎么办？

你可以重新创建新的 API Token，具体步骤请参考创建 API Token。

首次部署和二次部署的数据库同步策略有什么不同？

• 首次部署项目：支持同步开发环境的表数据至生产环境。如果不勾选同步数据，则仅同步表结构（Schema）。
• 后续部署项目：仅同步开发环境的表结构（Schema）变更，不同步具体数据。

回滚项目版本对数据库有什么影响？

回滚 AI 编程项目时，对数据库的影响如下：

• 回滚编辑版本：如果勾选同时回滚数据库，系统将把开发环境数据库还原至对应版本状态，该版本之后添加的数据将丢失，包括 Schema 以及数据。如果不勾选同时回滚数据库，则不会对数据库造成影响。
• 回滚部署版本：暂不支持回滚数据库，回滚后，生产环境数据库中的数据保持不变，包括 Schema 和数据。

AI 编程开发的智能体能发布到以前的官方和公共渠道吗？

通过 AI 编程开发的智能体暂时只支持发布为 API。

如何合理设置部署的服务器资源？

在部署编程项目时，扣子编程提供 CPU 和内存、最大实例数、单实例并发 等配置项。合理理解这些配置项的含义，有助于根据应用负载选择合适的服务器资源。

• CPU 和内存： 每个实例可使用的 CPU 和内存规格。规格越高，单个实例可承载的计算、数据处理和运行时资源越多，应用在复杂任务或高资源消耗场景下通常会更稳定，但成本也会相应增加。
• 最大实例数： 表示应用在高流量情况下最多可启动的服务实例数量。平台会根据实际访问流量自动扩缩容：当请求量超过单个实例的并发承载能力时，会逐步增加实例共同处理请求；当没有访问流量时，服务可缩容至 0 个实例，以减少资源占用和成本。
• 单实例并发： 表示每个实例允许同时处理的最大请求数量。该参数用于控制单个实例的请求承载上限，避免过多请求同时进入同一实例，导致 CPU、内存或外部依赖资源达到运行上限。
  

实际配置时，建议结合应用所处阶段、资源消耗类型和访问量预期进行选择，可参考以下原则。

1. 先使用小规格部署，进行小范围测试
   首次部署时，可以选择较低的 CPU / 内存配置、较小的最大实例数和适中的单实例并发，用于验证应用是否能正常启动、核心功能是否可用，以及基础性能是否满足预期。
2. 发布时根据资源消耗类型和预计访问量配置
   正式发布前，应根据应用特点调整配置。如果单个请求资源消耗较高，例如涉及 AI 调用、文件处理、复杂计算或大量数据加载，可以提高 CPU / 内存，并适当降低单实例并发；如果主要是访问量较高、请求数量较多，可以提高最大实例数，并结合实际情况调整单实例并发。
3. 上线后根据实际访问量灵活扩容
   应用上线后，可在部署 > 分析 > 运维监控 页面查看 CPU 使用率、内存使用率、延迟等情况，持续观察数据。如果发现 CPU 使用率过高、内存不足、执行 QPS 较高、错误 QPS 较高 等异常，说明当前资源可能无法满足应用运行需求。此时建议优先检查 CPU 和内存使用情况，并根据提示提高 CPU / 内存规格；如果是访问量上升导致的排队或响应变慢，则可以同时评估是否需要提高最大实例数或调整单实例并发。
   
4. 不确定时可让扣子编程 AI 辅助判断
   如果不确定如何选择配置，可以将应用类型、服务访问情况、资源使用情况、请求峰值、响应时间、错误率，以及当前可选规格提供给扣子编程 AI，由它结合应用运行情况给出更合适的部署配置建议。例如：

这个项目我应该如何选择部署规格？
预计访问量 PV 1000，高峰并发 100 左右。
当前可选规格见下图。

当前配置为 1 CPU / 2 GB，最大实例数 2，单实例并发 100。
上线后偶尔出现请求超时，内存使用率较高。
请帮我判断是否需要调整部署规格。

项目部署的服务器资源是否支持扩容或缩容？

支持。你可以根据编程项目的线上访问情况调整服务器资源，包括 CPU 和内存、最大实例数、单实例并发等配置。
需要注意的是，部署后暂时不支持在线调整服务器规格。如果需要变更配置，需要重新部署项目，并在重新部署时设置新的服务器资源规格。

AI 编程项目能下线吗？

目前 AI 编程项目暂不支持下线操作，部署成功后的项目无法被撤销部署。如果确定不再使用该项目，你可以删除项目，删除后，网页应用的 URL 将无法继续被访问，智能体和工作流的 API 将无法被调用。

可以下载小程序的代码吗？

不能。扣子编程作为第三方直接托管了你的小程序应用开发和发布工作，你无需查看或下载代码，无需理解小程序的代码逻辑，可以直接在扣子编程中通过自然语言生成并修改小程序、一键发布小程序。

为什么微信里检索不到、无法分享小程序？

在微信公众平台完成完成微信认证后，小程序才能获得“被搜索”和“被分享”能力。未完成微信认证虽然不影响后续版本发布，但微信用户无法搜索和分享这个小程序，只能由小程序管理员本人使用。

自定义域名备案

域名已在其他服务商那边备案，还需要重新备案吗？

根据国家相关法规，所有在中国内地提供服务的网站都必须进行 ICP 备案。扣子编程会自动将你的网页应用将部署在火山引擎的服务器上，因此需要在火山引擎备案系统对域名进行重新备案。

备案审核需要多长时间？

备案审核通常需要 1 到 20 个工作日，建议提前规划并提交备案申请，避免影响应用上线计划。

备案未完成会影响部署吗？

备案未完成会影响部署，在扣子编程部署时会检查备案状态，需要完成备案后，才能正常部署。

可以使用备案授权码进行备案吗？

可以。如果你的火山引擎其他账号下存在符合备案条件的云服务器，可以通过其他账号为当前账号分配备案授权码的方式进行备案。备案授权码分配与使用相关文档请参考备案授权码。
若您当前火山引擎账号下存在符合备案条件的云服务器，可以直接使用云服务器进行备案。
火山引擎云服务器的备案条件：
①计费模式为包年包月；
②购买的云服务器有效期需要大于3个月，剩余有效时长大于24小时；
③云资源备案5个配额数量有剩余；
④需要绑定公网IP；
同时满足以上四个条件的云服务器才能进行备案操作。详细说明可参考准备备案云服务器。

没有火山云服务器可以备案吗？

不可以。如果希望在扣子编程项目中使用自定义域名，则必须在你的火山引擎账号下购买符合备案条件的云服务器，然后备案自定义域名。如果账号下没有符合条件的云服务器，建议使用扣子编程分配的默认域名来部署项目。
火山引擎云服务器的备案条件：
①计费模式为包年包月；
②购买的云服务器有效期需要大于3个月，剩余有效时长大于24小时；
③云资源备案5个配额数量有剩余；
④需要绑定公网IP；
同时满足以上四个条件的云服务器才能进行备案操作。详细说明可参考准备备案云服务器。