【免费下载链接】edgeone-makers-tools项目地址https://gitcode.com/gh_mirrors/ed/edgeone-makers-tools点击查看免费下载edgeone-makers-tools 是 EdgeOne Makers 平台的官方 AI 开发技能包覆盖 AI Agent 开发、云函数、KV 存储与一键部署。官方在 makers-agents 技能文档 中明确列出了 13 条Critical Rules红线——每一条背后都是真实线上事故环境变量污染、请求静默返回 undefined、SSE 流中断、会话内存崩溃……本文用大白话把这 13 条 AI Agent 开发必须避开的致命错误讲清楚帮你一次性排掉所有坑。为什么 EdgeOne Makers 需要红线很多新手的第一反应是用熟悉的通用 API 路由写法比如 Vercel AI SDK 的route.tsPOST()、Express 风格来写后端。这正是最大的坑。EdgeOne Makers 的 Agent 运行在专属的 Agent Node Runtime或 Python Runtime里模型网关、沙箱、工具、会话存储全部由平台通过context对象注入你只负责写薄的处理函数。心智模型可以概括为一句话✅ 你写一个薄 handler平台把能力注入context❌ 你自己 import SDK、自己读环境变量、自己拼流等于和平台对着干。官方还附了一张常见错误对照表见 review-checklist.md 的 Remediation Table把 ❌ 写法和 ✅ 写法逐条对齐。13条红线速览一张表先记住#红线一句话说明1路由自动扫描agents/name.ts自动变成POST /name别手写 config.json2入口签名固定TS 用onRequest(context)Python 用handler(ctx)3环境变量走context.env后端禁用process.env/os.environ读和改都不行4Headers 是普通对象用headers[x-foo]不是.get(x-foo)5会话 ID 双通道契约AI 接口必带makers-conversation-id头/stop只走 body6禁止硬编码模型/密钥只认AI_GATEWAY_API_KEYAI_GATEWAY_BASE_URL7SSE 事件类型统一固定事件词表以data: [DONE]收尾8心跳 缓冲控制每 5 秒发ping响应头缺一不可9始终尊重中断信号循环内检查context.request.signal10循环必须设上限硬编码轮数或maxTurns禁止无限循环11错误不能打崩流try/catch 包裹一切错误以error_message发出12选对 store 入口context.store≠context.agent.store形状不同13只用注入的 sandbox/tools细节见runCode是顶层方法、超时单位是秒下面按路由 → 请求 → 流式 → 存储 → 沙箱的顺序逐条拆解。红线 1~2路由与入口从目录结构开始就错了红线 1不要手写.edgeone/agent-node/config.json路由是文件即路由agents/chat/index.ts自动映射为POST /chat_开头的文件_shared.ts、_model.ts是内部模块不参与路由。构建时 CLI 会自动扫描并生成路由配置——你手写的那份迟早和真实扫描结果打架。判断是否违规很简单看.gitignore里有没有.edgeone没有的话说明整个构建产物目录被提交进了仓库详见 node-entry.md。红线 2入口签名是固定的TS 端点必须导出export async function onRequest(context: any)也支持onRequestPost等方法级变体资源全部从context解构Python 端是async def handler(ctx):。写export async function POST(req)这种 Vercel 风格平台根本识别不到你的端点。红线 3~4两个静默杀手——环境变量与请求头红线 3后端只准context.envprocess.env全面禁用这是官方标注频率最高的违规Reviewer SOP 第 1 条。原因有二process.env是整个进程共享的Agent 运行时里多个 handler 并发运行改一个变量会污染所有其他 handler——所以改process.env.X ...同样违规平台只在context.env里注入AI_GATEWAY_*等变量读process.env拿到的是空值且错误往往在运行时才暴露。注意豁免范围前端目录app/、src/不受此限制共享内部模块_model.ts等应把env作为参数传入模块内部不得读全局环境。完整规范见 env-and-model.md。红线 4Headers 是普通对象不是 WebHeadersAPIcontext.request.headers是一个普通对象。写成headers.get(x-foo)不会报语法错而是静默返回 undefined——这类 bug 编译全绿、构建成功、本地预览正常上线才炸。正确写法是headers[x-foo]。顺带一提context.request.body已经被平台解析成对象直接用即可不要再await req.json()。红线 5~6会话与模型配置红线红线 5会话 ID 双通道契约最容易写反的一条前端调用任何AI 端点/chat、/outline、/create…都必须携带请求头makers-conversation-id: uuid。缺失的后果后端拿不到context.conversation_id会话无法续接、粘性路由失效、/stop找不到要取消的运行。唯一的例外是/stop绝对不能带这个头。带了这个头请求会被粘性路由钉在那个卡住的实例上取消指令永远送不到正确做法是把conversation_id放在请求体里传递。前端用crypto.randomUUID()生成 ID 并持久化到localStorage一个 ID 全端点复用。完整调用样式速查表见 conversation-id.md。红线 6不要硬编码模型名、Base URL、API Key只认可AI_GATEWAY_API_KEYAI_GATEWAY_BASE_URL 可选AI_GATEWAY_MODEL三件套全部从context.env读取模型名用常量默认makers/deepseek-v4-flash或走resolveModelName。变量缺失时必须显式报错不许静默降级。特别提醒用了context.tools.web_search工具的项目还要配置WSA_API_KEY否则搜索会以 401 失败见 tools.md。红线 7~11流式输出五连击SSE 一个都别少SSE 是 Agent 体验的核心官方把它拆成五条红线全部指向同一个目标流必须活到最后一刻。红线 7SSE 协议走统一事件词表响应类型为text/event-stream事件格式data: JSON\n\ntype只用固定枚举ai_response/tool_call/tool_result/usage/suggest_actions/file_output/ping/error_message流以data: [DONE]\n\n结束。前端按 type 分发靠[DONE]区分正常结束和中途断流——没有收到[DONE]就要提示用户重试详见 sse-protocol.md。红线 8心跳 缓冲控制是强制项冷启动的 Agent 实例首 token 可能要 10 秒以上期间必须每 5 秒发一个ping保活响应头四件套缺一不可Content-TypeCache-Control: no-cacheConnection: keep-aliveX-Accel-Buffering: no。官方强烈建议把 SSE 逻辑收敛到共享的createSSEResponsehelper 里而不是每个端点各写一份ReadableStream。红线 9始终尊重context.request.signal用户关掉页面或点了停止流就该优雅退出。循环内和流处理中都要检查signal?.abortedPython 是signal.is_set()中止时安静退出不要抛错。红线 10循环必须设上限手动绑定工具的循环写死轮数比如最多 4 轮SDK 路线设置maxTurns。直到模型说停为止的无限循环一次抽风就能把 Token 账单和运行时长都拉爆。红线 11错误必须打不崩流每个模型调用、工具调用都包 try/catchAbortError和用户主动终止静默吞掉其余错误以error_message事件发出流继续活到[DONE]。前端读流时还要记录是否真的收到[DONE]把断流和模型没输出区分开避免把一次网络中断显示成空回答。红线 12存储红线——两个 store 入口形状不等价这是审查清单里标注最多的雷区。平台按端点所在目录决定注入哪个存储入口维度Agent 端点agents/name/云函数cloud-functions/入口context.storecontext.agent.store消息 API / openaiSession / claudeSessionStore✅✅langgraphCheckpointer/langgraphStore✅❌ 运行时明确剥离后果需要 LangGraph 存储的端点必须放在agents/下塞进云函数就会在运行时抛出kv.get is not a function。而store?.langgraphStore ?? store这种兜底写法更糟——兜底拿到的是没有.get方法的 store 本身下一次调用直接崩。另外三条存储细则appendMessage/getMessages用单对象入参context.store是对话存储而非关系型数据库业务数据请用外部数据库进程内new Map()缓存绝不能当持久层冷启动即丢失。完整对照见 store.md。红线 13沙箱与工具——只用注入的别自己拼context.sandbox/context.tools由运行时按需注入不要手写/v1/sandbox/*请求或手动解析 token模板的.env里也不该出现 PROJECT_ID、SANDBOX_API_BASE 之类的配置。API 细节有三个高频陷阱见 sandbox.mdsandbox.runCode(...)是顶层方法不存在code_interpreter命名空间browser.screenshot接收对象参数{ fullPage: true }传布尔值不合法超时单位是秒不是毫秒。还有一个平台级特性沙箱/tmp/的文件可能在两次请求之间被清理上传文件要用进程内 Map 缓存 每次请求重新写入的模式并在系统提示词中禁止模型在FileNotFoundError时编造文件。交付前 3 步自检把红线变成肌肉记忆对照官方检查清单过一遍review-checklist.md 按 A目录结构到 I前端集成分节每条红线都有对应的勾选项文末还附Vercel 风格 → Makers 风格修复对照表。确认部署配置edgeone.json里agents.framework必须与真实框架一致可选claude-agent-sdk/openai-agents-sdk/langgraph/crewai/deepagents没有basic它决定了控制台图标和context.tools的形状。让 AI 助手替你把关本技能包自带 hooks/validate-write.mjs在 AI 写文件时实时拦截process.env、headers.get(等典型违规并给出整改提示——装好技能包即可自动生效。常见问题问我的项目是 Vercel AI SDK 风格能直接迁移吗答思路可以复用写法必须换。按检查清单末尾的修复对照表逐项替换即可app/api/*/route.ts→agents/name/index.tsPOST(req)→onRequest(context)await req.json()→context.request.body。存量项目迁移指南见 makers-migration。问Python 项目红线不同吗答原则完全一致语法不同环境读ctx.env而非os.environ中止信号用signal.is_set()store 方法是小写下划线风格且用位置参数。详见检查清单 J 节。写在最后13 条红线看着多其实浓缩成一个习惯信任平台注入的context别自己造轮子。路由交给目录、环境变量交给context.env、流交给createSSEResponse、记忆交给context.store、沙箱交给运行时——你的代码越薄上线后踩雷的概率就越低。把这份清单收藏起来交付前花 5 分钟过一遍能省下大半夜的线上排查时间 ⭐赞分享【免费下载链接】edgeone-makers-tools项目地址https://gitcode.com/gh_mirrors/ed/edgeone-makers-tools点击查看免费下载相关推荐手机投屏到电脑只需 5 分钟Escrcpy 安卓投屏新手指南手机投屏到电脑只需 5 分钟Escrcpy 安卓投屏新手指南 你有没有遇到过这种情况手机屏幕太小看不清表格想拖拽文件却只能用两根手指在屏幕上抠来抠去或者桌面应用移动开发edgeone-makers-tools是什么AI编程助手的EdgeOne全栈开发技能包完全指南edgeone makers tools是什么AI编程助手的EdgeOne全栈开发技能包完全指南 edgeone makers tools 是面向腾讯 Edg如何在EdgeOne Makers开发AI Agentedgeone-makers-tools五大框架选型决策树如何在EdgeOne Makers开发AI Agentedgeone makers tools五大框架选型决策树 edgeone makers tools 是创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
【免费下载链接】edgeone-makers-tools项目地址https://gitcode.com/gh_mirrors/ed/edgeone-makers-tools点击查看免费下载edgeone-makers-tools 是 EdgeOne Makers 平台的官方 AI 开发技能包覆盖 AI Agent 开发、云函数、KV 存储与一键部署。官方在 makers-agents 技能文档 中明确列出了 13 条Critical Rules红线——每一条背后都是真实线上事故环境变量污染、请求静默返回 undefined、SSE 流中断、会话内存崩溃……本文用大白话把这 13 条 AI Agent 开发必须避开的致命错误讲清楚帮你一次性排掉所有坑。为什么 EdgeOne Makers 需要红线很多新手的第一反应是用熟悉的通用 API 路由写法比如 Vercel AI SDK 的route.tsPOST()、Express 风格来写后端。这正是最大的坑。EdgeOne Makers 的 Agent 运行在专属的 Agent Node Runtime或 Python Runtime里模型网关、沙箱、工具、会话存储全部由平台通过context对象注入你只负责写薄的处理函数。心智模型可以概括为一句话✅ 你写一个薄 handler平台把能力注入context❌ 你自己 import SDK、自己读环境变量、自己拼流等于和平台对着干。官方还附了一张常见错误对照表见 review-checklist.md 的 Remediation Table把 ❌ 写法和 ✅ 写法逐条对齐。13条红线速览一张表先记住#红线一句话说明1路由自动扫描agents/name.ts自动变成POST /name别手写 config.json2入口签名固定TS 用onRequest(context)Python 用handler(ctx)3环境变量走context.env后端禁用process.env/os.environ读和改都不行4Headers 是普通对象用headers[x-foo]不是.get(x-foo)5会话 ID 双通道契约AI 接口必带makers-conversation-id头/stop只走 body6禁止硬编码模型/密钥只认AI_GATEWAY_API_KEYAI_GATEWAY_BASE_URL7SSE 事件类型统一固定事件词表以data: [DONE]收尾8心跳 缓冲控制每 5 秒发ping响应头缺一不可9始终尊重中断信号循环内检查context.request.signal10循环必须设上限硬编码轮数或maxTurns禁止无限循环11错误不能打崩流try/catch 包裹一切错误以error_message发出12选对 store 入口context.store≠context.agent.store形状不同13只用注入的 sandbox/tools细节见runCode是顶层方法、超时单位是秒下面按路由 → 请求 → 流式 → 存储 → 沙箱的顺序逐条拆解。红线 1~2路由与入口从目录结构开始就错了红线 1不要手写.edgeone/agent-node/config.json路由是文件即路由agents/chat/index.ts自动映射为POST /chat_开头的文件_shared.ts、_model.ts是内部模块不参与路由。构建时 CLI 会自动扫描并生成路由配置——你手写的那份迟早和真实扫描结果打架。判断是否违规很简单看.gitignore里有没有.edgeone没有的话说明整个构建产物目录被提交进了仓库详见 node-entry.md。红线 2入口签名是固定的TS 端点必须导出export async function onRequest(context: any)也支持onRequestPost等方法级变体资源全部从context解构Python 端是async def handler(ctx):。写export async function POST(req)这种 Vercel 风格平台根本识别不到你的端点。红线 3~4两个静默杀手——环境变量与请求头红线 3后端只准context.envprocess.env全面禁用这是官方标注频率最高的违规Reviewer SOP 第 1 条。原因有二process.env是整个进程共享的Agent 运行时里多个 handler 并发运行改一个变量会污染所有其他 handler——所以改process.env.X ...同样违规平台只在context.env里注入AI_GATEWAY_*等变量读process.env拿到的是空值且错误往往在运行时才暴露。注意豁免范围前端目录app/、src/不受此限制共享内部模块_model.ts等应把env作为参数传入模块内部不得读全局环境。完整规范见 env-and-model.md。红线 4Headers 是普通对象不是 WebHeadersAPIcontext.request.headers是一个普通对象。写成headers.get(x-foo)不会报语法错而是静默返回 undefined——这类 bug 编译全绿、构建成功、本地预览正常上线才炸。正确写法是headers[x-foo]。顺带一提context.request.body已经被平台解析成对象直接用即可不要再await req.json()。红线 5~6会话与模型配置红线红线 5会话 ID 双通道契约最容易写反的一条前端调用任何AI 端点/chat、/outline、/create…都必须携带请求头makers-conversation-id: uuid。缺失的后果后端拿不到context.conversation_id会话无法续接、粘性路由失效、/stop找不到要取消的运行。唯一的例外是/stop绝对不能带这个头。带了这个头请求会被粘性路由钉在那个卡住的实例上取消指令永远送不到正确做法是把conversation_id放在请求体里传递。前端用crypto.randomUUID()生成 ID 并持久化到localStorage一个 ID 全端点复用。完整调用样式速查表见 conversation-id.md。红线 6不要硬编码模型名、Base URL、API Key只认可AI_GATEWAY_API_KEYAI_GATEWAY_BASE_URL 可选AI_GATEWAY_MODEL三件套全部从context.env读取模型名用常量默认makers/deepseek-v4-flash或走resolveModelName。变量缺失时必须显式报错不许静默降级。特别提醒用了context.tools.web_search工具的项目还要配置WSA_API_KEY否则搜索会以 401 失败见 tools.md。红线 7~11流式输出五连击SSE 一个都别少SSE 是 Agent 体验的核心官方把它拆成五条红线全部指向同一个目标流必须活到最后一刻。红线 7SSE 协议走统一事件词表响应类型为text/event-stream事件格式data: JSON\n\ntype只用固定枚举ai_response/tool_call/tool_result/usage/suggest_actions/file_output/ping/error_message流以data: [DONE]\n\n结束。前端按 type 分发靠[DONE]区分正常结束和中途断流——没有收到[DONE]就要提示用户重试详见 sse-protocol.md。红线 8心跳 缓冲控制是强制项冷启动的 Agent 实例首 token 可能要 10 秒以上期间必须每 5 秒发一个ping保活响应头四件套缺一不可Content-TypeCache-Control: no-cacheConnection: keep-aliveX-Accel-Buffering: no。官方强烈建议把 SSE 逻辑收敛到共享的createSSEResponsehelper 里而不是每个端点各写一份ReadableStream。红线 9始终尊重context.request.signal用户关掉页面或点了停止流就该优雅退出。循环内和流处理中都要检查signal?.abortedPython 是signal.is_set()中止时安静退出不要抛错。红线 10循环必须设上限手动绑定工具的循环写死轮数比如最多 4 轮SDK 路线设置maxTurns。直到模型说停为止的无限循环一次抽风就能把 Token 账单和运行时长都拉爆。红线 11错误必须打不崩流每个模型调用、工具调用都包 try/catchAbortError和用户主动终止静默吞掉其余错误以error_message事件发出流继续活到[DONE]。前端读流时还要记录是否真的收到[DONE]把断流和模型没输出区分开避免把一次网络中断显示成空回答。红线 12存储红线——两个 store 入口形状不等价这是审查清单里标注最多的雷区。平台按端点所在目录决定注入哪个存储入口维度Agent 端点agents/name/云函数cloud-functions/入口context.storecontext.agent.store消息 API / openaiSession / claudeSessionStore✅✅langgraphCheckpointer/langgraphStore✅❌ 运行时明确剥离后果需要 LangGraph 存储的端点必须放在agents/下塞进云函数就会在运行时抛出kv.get is not a function。而store?.langgraphStore ?? store这种兜底写法更糟——兜底拿到的是没有.get方法的 store 本身下一次调用直接崩。另外三条存储细则appendMessage/getMessages用单对象入参context.store是对话存储而非关系型数据库业务数据请用外部数据库进程内new Map()缓存绝不能当持久层冷启动即丢失。完整对照见 store.md。红线 13沙箱与工具——只用注入的别自己拼context.sandbox/context.tools由运行时按需注入不要手写/v1/sandbox/*请求或手动解析 token模板的.env里也不该出现 PROJECT_ID、SANDBOX_API_BASE 之类的配置。API 细节有三个高频陷阱见 sandbox.mdsandbox.runCode(...)是顶层方法不存在code_interpreter命名空间browser.screenshot接收对象参数{ fullPage: true }传布尔值不合法超时单位是秒不是毫秒。还有一个平台级特性沙箱/tmp/的文件可能在两次请求之间被清理上传文件要用进程内 Map 缓存 每次请求重新写入的模式并在系统提示词中禁止模型在FileNotFoundError时编造文件。交付前 3 步自检把红线变成肌肉记忆对照官方检查清单过一遍review-checklist.md 按 A目录结构到 I前端集成分节每条红线都有对应的勾选项文末还附Vercel 风格 → Makers 风格修复对照表。确认部署配置edgeone.json里agents.framework必须与真实框架一致可选claude-agent-sdk/openai-agents-sdk/langgraph/crewai/deepagents没有basic它决定了控制台图标和context.tools的形状。让 AI 助手替你把关本技能包自带 hooks/validate-write.mjs在 AI 写文件时实时拦截process.env、headers.get(等典型违规并给出整改提示——装好技能包即可自动生效。常见问题问我的项目是 Vercel AI SDK 风格能直接迁移吗答思路可以复用写法必须换。按检查清单末尾的修复对照表逐项替换即可app/api/*/route.ts→agents/name/index.tsPOST(req)→onRequest(context)await req.json()→context.request.body。存量项目迁移指南见 makers-migration。问Python 项目红线不同吗答原则完全一致语法不同环境读ctx.env而非os.environ中止信号用signal.is_set()store 方法是小写下划线风格且用位置参数。详见检查清单 J 节。写在最后13 条红线看着多其实浓缩成一个习惯信任平台注入的context别自己造轮子。路由交给目录、环境变量交给context.env、流交给createSSEResponse、记忆交给context.store、沙箱交给运行时——你的代码越薄上线后踩雷的概率就越低。把这份清单收藏起来交付前花 5 分钟过一遍能省下大半夜的线上排查时间 ⭐赞分享【免费下载链接】edgeone-makers-tools项目地址https://gitcode.com/gh_mirrors/ed/edgeone-makers-tools点击查看免费下载相关推荐手机投屏到电脑只需 5 分钟Escrcpy 安卓投屏新手指南手机投屏到电脑只需 5 分钟Escrcpy 安卓投屏新手指南 你有没有遇到过这种情况手机屏幕太小看不清表格想拖拽文件却只能用两根手指在屏幕上抠来抠去或者桌面应用移动开发edgeone-makers-tools是什么AI编程助手的EdgeOne全栈开发技能包完全指南edgeone makers tools是什么AI编程助手的EdgeOne全栈开发技能包完全指南 edgeone makers tools 是面向腾讯 Edg如何在EdgeOne Makers开发AI Agentedgeone-makers-tools五大框架选型决策树如何在EdgeOne Makers开发AI Agentedgeone makers tools五大框架选型决策树 edgeone makers tools 是创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
