1. 从「能聊天」到「能进代码」OpenCode 与 Pi Coding Agent 的第一道坎很多人第一次接触 AI 编程助手是在网页聊天框里完成的。你输入一句「帮我写个防抖函数」它回你一段代码复制粘贴收工。这个体验很顺但它有个天花板AI 看不到你的项目文件改不了你的代码跑不了你的测试。你想让它真正参与开发就必须让它「进到代码里」。OpenCode 和 Pi Coding Agent 这类工具解决的正是这件事。它们把大模型能力封装成可以读文件、改代码、执行命令的 Agent而这一切的起点其实非常朴素——你的 TypeScript 程序能成功向模型发出一条消息并拿到回复。听起来简单但第一次跑通时卡住新手的往往不是模型能力而是三件小事密钥放哪、请求发给谁、返回怎么读。这篇是「跟着 OpenCode 学习 Pi Coding Agent」系列的第一篇目标只有一个用 Node.js TypeScript 写一个最小可运行的项目通过 TaoToken 的统一 Key 向模型发出第一句话并在终端看到回复。不做封装不引入框架就是最裸的一次请求。因为 Pi 的核心逻辑也是这样起步的——它内部用 OpenAI SDK 调兼容接口区别只是它支持几十家服务商而我们先把一条链路走通。适合谁看写过一点 TypeScript、装过 Node.js、但还没亲手用代码调过模型 API 的开发者。跑完这一篇你会得到一份可复制的config.toml骨架、一套环境变量配置方式以及一个能打印出 AI 回复的npm start。2. TaoToken 前置一把 Key 打通多家模型在写代码之前先把「打电话」这件事想清楚。模型服务商很多接口格式大同小异但每家的密钥、地址、模型名都不一样。如果你每接一家就改一次代码项目很快就会变成一堆 if-else。TaoToken 的价值就在这里它提供统一的 API Key 和统一的接入地址你只需要维护一份配置就能在多个模型之间切换。对 Pi Coding Agent 这类需要频繁切换模型的工具来说这一点很关键。Pi 的架构里有一个「provider 层」专门处理不同服务商的 baseURL 和认证差异。我们在第一篇里先不写那么复杂但可以借用同样的思路把密钥和地址抽到配置文件里代码只读配置不写死。你需要准备的东西一个 TaoToken 账号登录后在控制台创建 API KeyNode.js 18 以上推荐 20 或 22原生支持 ESM 和 top-level await一个空目录用来放这个最小项目。创建 Key 的入口在控制台的 API Keys 页面生成后复制那串以sk-开头的字符串。注意这串字符只在创建时完整显示一次关掉页面就看不到了所以先存到安全的地方。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 控制台和文档都可以从这里进。注意密钥等同于你的账户凭证不要写进代码提交到 Git不要发到群里也不要截图分享。后面我们会用.env文件隔离它。TaoToken 的 API 接入地址是 https://taotoken.net/api 这个地址在代码里作为baseURL使用。它兼容 OpenAI 的接口格式所以我们可以直接用官方的openainpm 包来调用不需要自己手写 HTTP 请求。这一点和 Pi 的做法一致——Pi 内部也是用openai这个包去调各家兼容接口的。3. 可复制配置config.toml 骨架与项目初始化先把项目骨架搭起来。打开终端执行下面几条命令mkdir pi-agent-01 cd pi-agent-01 npm init -y npm install --save-dev typescript tsx types/node npm install openaitsx的作用是直接运行.ts文件不用先编译成.js。types/node提供 Node.js 的类型定义否则process.env这类全局变量在 TypeScript 里会报红。接着在package.json里加上type: module让 Node.js 按 ESM 模块解析。可以用编辑器手动加也可以执行npx --yes json -I -f package.json -e this.typemodule然后创建tsconfig.json{ compilerOptions: { target: ES2022, module: Preserve, moduleResolution: bundler, strict: true, esModuleInterop: true, skipLibCheck: true, noEmit: true, types: [node] } }这里几个选项值得说明。strict: true打开全部严格检查早期多花点时间后期少踩坑。noEmit: true表示不生成.js文件因为我们用tsx直接跑源码。types: [node]让 TypeScript 认识process、console这些 Node 全局对象漏了它process.env会报错。现在来写配置文件。Pi Coding Agent 用config.toml管理模型和 provider我们这里先给一个最小骨架把 TaoToken 的地址和模型名放进去# config.toml [provider.taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [model.default] provider taotoken name gpt-4o-mini temperature 0.7 max_tokens 1024这个骨架的用意是代码不直接读环境变量而是先读config.toml再根据api_key_env字段去环境变量里取密钥。这样以后换模型、换服务商只改配置不改代码。api_key_env存的是环境变量的名字不是密钥本身所以这个文件可以安全地提交到仓库。对应的.env文件不要提交TAOTOKEN_API_KEYsk-你的密钥放这里再创建.gitignorenode_modules .env dist到这里配置层就绪。接下来写真正发请求的代码。4. 验证请求从环境变量到第一句回复创建src/index.ts内容如下import OpenAI from openai; import { readFileSync } from node:fs; import { parse } from smol-toml; // 读取 config.toml const configText readFileSync(new URL(../config.toml, import.meta.url), utf-8); const config parse(configText); const provider config.provider.taotoken; const model config.model.default; // 从环境变量取密钥 const apiKey process.env[provider.api_key_env]; if (!apiKey) { console.error(未找到环境变量 ${provider.api_key_env}); console.error(请检查 .env 文件是否配置正确); process.exit(1); } // 创建客户端 const client new OpenAI({ apiKey, baseURL: provider.base_url, }); console.log(正在向 TaoToken 发送请求...); const response await client.chat.completions.create({ model: model.name, temperature: model.temperature, max_tokens: model.max_tokens, messages: [ { role: user, content: 用一句话解释什么是 AI Agent, }, ], }); const reply response.choices[0].message.content; console.log(AI 回复:, reply);这里用到了smol-toml来解析 TOML先装上npm install smol-toml然后在package.json的scripts里加一行{ type: module, scripts: { start: tsx --env-file.env src/index.ts } }--env-file.env是 Node.js 20.6 以上支持的能力tsx会把它透传给 Node自动把.env里的内容加载成环境变量。这样代码里process.env.TAOTOKEN_API_KEY就能取到值。现在运行npm start如果一切正常终端会输出类似正在向 TaoToken 发送请求... AI 回复: AI Agent 是一种能够感知环境、自主决策并调用工具来完成目标的智能程序。看到这行回复说明从环境变量读取、配置解析、请求发送到响应解析的整条链路已经打通。这就是 Pi Coding Agent 最底层的那一步——它后面所有的读文件、改代码、跑命令都是在这条链路上叠加工具调用和上下文管理。5. 本篇常见错排查第一次跑不通很正常下面几个错误覆盖了大多数情况。报错「未找到环境变量 TAOTOKEN_API_KEY」先确认.env文件在项目根目录且内容格式正确cat .env应该看到TAOTOKEN_API_KEYsk-...等号两边不要有空格值不要加引号。如果文件没问题检查npm start命令里是否带了--env-file.env。报错 401 Unauthorized密钥无效或已过期。去 TaoToken 控制台重新生成一个复制时注意不要多带空格或换行。如果密钥是从网页复制的建议粘贴到编辑器里检查一下首尾字符。报错 404 Not FoundbaseURL或模型名写错了。确认config.toml里base_url是https://taotoken.net/api模型名是控制台文档里列出的可用名称。模型名区分大小写不要凭记忆写。报错「Cannot find module smol-toml」依赖没装全。执行npm install smol-toml后重试。如果之前装过但报错依旧删掉node_modules和package-lock.json重新npm install。返回内容中文乱码Windows PowerShell 默认编码可能不是 UTF-8。执行下面这行切换[Console]::OutputEncoding [Text.Encoding]::UTF8请求一直卡住不返回检查网络是否能访问https://taotoken.net/api。可以在浏览器里打开 TaoToken 的文档页面确认服务可达。如果公司网络有出口限制换一个网络环境试试。TypeScript 报错「Top-level await is not supported」说明package.json里漏了type: module。加上后重启终端再跑。6. 下一步把第一句话接进 Pi 的架构跑通这一篇之后你手里已经有了一个能工作的最小请求链路。它很裸但结构是对的配置和代码分离、密钥走环境变量、请求走统一入口。Pi Coding Agent 的packages/ai里做的事情本质上也是这些只是它把 provider 抽象成了可插拔的模块支持几十家服务商并且加了重试、流式输出、工具调用等能力。接下来可以往两个方向走。一是继续在这个项目上叠加功能比如把消息历史存起来、加上 system prompt、试试流式输出。二是直接去看 Pi 的源码对照openai-completions.ts理解它是怎么把同一套逻辑抽象成通用 provider 的。如果你打算长期做编码类 Agent建议了解一下 TaoToken 的 Coding Plan它在多模型切换和额度管理上对这类场景更友好入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要查模型可用列表和参数说明看接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先在网页里验证模型效果可以直接用模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。密钥管理在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。下一篇会在这个项目上引入 typebox给消息、对话上下文和工具定义设计一套数据格式约束让代码的每一层都知道自己该收什么、该发什么。那是从「能说话」到「会沟通」的一步。