1. 项目概述T3 Code 不是又一个“AI写代码插件”而是一套可落地的 Agent 协作操作系统你有没有过这种体验刚装完一个号称“AI编程神器”的插件它确实能帮你补全几行函数但一旦需求变复杂——比如要“从 GitHub 拉取本周所有 PR 的变更文件分析其中 TypeScript 类型定义的修改频次再生成一份带趋势图的周报”——它就卡在第一步不知道该调哪个 API、用什么鉴权方式、怎么解析 JSON 响应结构更别说自动选择合适的图表库和渲染逻辑了。这不是模型能力不够而是缺少一个能把“意图→任务拆解→工具调度→结果整合→人机协同”串起来的执行层操作系统。T3 Code 正是为解决这个问题而生的。它不训练大模型也不封装 LLM API而是用 TypeScript 构建了一套轻量、可扩展、开发者可完全掌控的 Agent 控制台框架。核心关键词T3 Code、AI编程、Agent、控制台、TypeScript在这里不是堆砌的标签而是各自承担明确角色T3 Code 是框架名AI编程是目标场景Agent 是执行单元形态控制台是交互与调度中枢TypeScript 是保障类型安全与工程健壮性的底层语言。它适合三类人想真正把 AI 编程从“单点辅助”升级为“流程自动化”的前端/全栈工程师正在探索 Agent 架构但苦于缺乏可调试、可复现、可嵌入现有工作流的最小可行原型的算法或产品同学以及需要快速验证某个垂直领域如金融数据清洗、API 文档生成、测试用例覆盖分析是否适合用 Agent 流水线解决的技术负责人。它不承诺“一键写出完整系统”但能让你在一天内亲手搭建出一个能稳定运行、可打断、可观察、可回溯的 AI 编程工作流。2. 整体设计思路为什么必须是“统一控制台”而不是“又一个 SDK”2.1 从“工具链割裂”到“执行态统一”的必然性过去两年AI 编程工具呈现爆炸式增长但生态却异常割裂。你可能同时开着 VS Code用 Copilot 补全、Postman调 OpenAPI、Jupyter Notebook跑数据分析脚本、甚至本地 Python 脚本处理文件。每个工具都擅长一个环节但它们之间没有“状态共享”和“任务接力”。比如Copilot 生成的代码片段无法自动触发后续的单元测试执行Postman 获取的 JSON 数据不能直接喂给 Notebook 里的分析模型。这种割裂导致两个严重后果一是调试成本指数级上升——你得在多个窗口间反复切换、复制粘贴、手动校验格式二是自动化流形同虚设——所谓“AI 工作流”往往只是人工串联几个独立步骤中间任何一环失败整个流程就中断且无法定位是模型幻觉、API 限流还是数据格式错位。T3 Code 的设计起点就是直面这个“执行态碎片化”问题。它不试图替代 VS Code 或 Jupyter而是提供一个轻量级、可嵌入、命令行友好的控制台Console作为统一调度中心。这个控制台不是 UI 界面而是一个基于 Node.js 的、以 TypeScript 编写的运行时环境它负责三件事第一标准化 Agent 的输入/输出契约——所有 Agent 必须实现execute(input: any): PromiseOutput接口输入是结构化的 JSON 对象输出是带status、data、log字段的确定性响应第二提供统一的上下文管理Context Manager——让前一个 Agent 的输出能通过context.get(last_result)或context.set(api_token, token)的方式被后一个 Agent 安全、可靠地引用第三内置可插拔的执行引擎Executor——支持同步执行、异步队列、条件分支if-else、循环for-each甚至简单的错误重试策略。这三点加起来就构成了一个“可编程的执行管道”其价值不在于多炫酷的 UI而在于让“AI 编程”这件事第一次拥有了类似传统软件开发中“构建-测试-部署”那样的可追踪、可审计、可版本化的执行过程。2.2 TypeScript 为何是不可妥协的底层选择看到“TypeScript”这个词很多人第一反应是“又一个前端语言”但在 T3 Code 的架构里它承担着远超语法糖的关键角色。首先类型即契约Type as Contract。在 Agent 协作中最脆弱的环节永远是“接口约定”。如果 Agent A 输出一个{ user_id: string, score: number }而 Agent B 期望的是{ id: number, points: number }那么运行时就会崩溃。TypeScript 的静态类型检查在代码编写阶段就能捕获 90% 以上的这类错误。T3 Code 的核心Agent接口定义如下interface AgentInput { query: string; // 用户原始指令 context: Context; // 共享上下文 } interface AgentOutput { status: success | error | partial; data: any; // 业务数据 log: string[]; // 执行日志 next?: string; // 下一个要执行的 Agent 名称用于编排 } type Agent (input: AgentInput) PromiseAgentOutput;这个看似简单的定义强制所有接入的 Agent 都必须遵循同一套输入/输出语义。其次类型即文档Type as Documentation。当一个新成员加入项目他不需要读几百页 Wiki只需看一眼types/index.ts文件就能清晰知道整个系统的数据流向和关键字段含义。最后类型即生产力Type as Productivity。VS Code 对 TypeScript 的智能提示堪称业界标杆。当你在编写一个调用 GitHub API 的 Agent 时输入context.IDE 就会自动列出所有可用的get、set方法当你返回AgentOutput时status字段的可选值会被严格限定避免拼写错误。我实测过一个中等复杂度的 Agent如“分析 Git 提交信息并生成周报”用纯 JavaScript 开发平均需要 3 次调试才能跑通而用 TypeScript首次运行成功率提升到 85%剩下的 15% 也基本是逻辑错误而非类型错位。这背后不是玄学而是编译器在帮你做“静态沙盒测试”。2.3 “统一控制台”的轻量化哲学拒绝重量级框架拥抱 Unix 哲学T3 Code 明确拒绝成为另一个“全能型 AI 平台”。它没有自己的数据库、没有 Web UI、不提供用户管理系统、甚至不内置 LLM 调用模块你可以自由选择 OpenAI、Anthropic、Ollama 本地模型或任何符合 OpenAI 兼容 API 的服务。它的核心包t3code/core只有 47KBgzip 后安装命令npm install t3code/core3 秒内完成。这种极致的轻量化源于对 Unix 哲学的深刻认同“做一件事并做好它”。T3 Code 只做“调度”和“协调”其他一切交给生态。它把 Agent 视为一个个独立的、可组合的“命令行工具”CLI Tools。你可以用curl写一个 Agent用Python写一个 Agent甚至用bash脚本写一个 Agent只要它们能接收标准输入stdin的 JSON输出标准输出stdout的 JSON就能被 T3 Code 的控制台识别和调用。这种设计带来了三个关键优势第一零学习成本迁移——你现有的 Python 数据分析脚本只需加两行代码读 stdin、写 stdout就能变成 T3 Code 生态中的一个 Agent第二技术栈无绑定——团队里有 Java 后端、Rust 系统工程师、甚至 Shell 脚本老手大家都能贡献 Agent无需统一语言第三故障隔离性强——某个 Agent 崩溃比如 Python 脚本内存溢出不会拖垮整个控制台进程控制台只会记录错误日志并按策略跳过或重试。我在一个客户现场部署时曾遇到一个用puppeteer抓取网页的 Agent 因目标网站反爬而频繁崩溃但控制台依然稳定运行其他 Agent如代码格式化、Git 操作完全不受影响。这种“松耦合、高韧性”的架构正是它能在真实生产环境中存活下来的根本原因。3. 核心细节解析控制台如何真正“统一”Agent 的生命周期3.1 控制台启动与配置从t3code init到t3code runT3 Code 的控制台不是一个后台服务而是一个交互式 CLI 应用。它的启动流程极简却暗含深意。第一步初始化项目npx t3code-cli init my-ai-workflow。这个命令会创建一个标准目录结构my-ai-workflow/ ├── agents/ # 所有 Agent 的存放目录 │ ├── github-fetch.ts │ ├── type-analyze.ts │ └── report-gen.ts ├── config/ # 运行时配置 │ └── agents.json # Agent 注册与编排定义 ├── context/ # 上下文持久化存储可选 │ └── memory.ts # 内存版上下文管理器 └── index.ts # 主入口定义全局上下文与插件这里的关键是config/agents.json它不是配置文件而是Agent 的“服务发现”注册表。一个典型的定义如下{ agents: [ { name: github-fetch, path: ./agents/github-fetch.ts, description: Fetch PRs and files from GitHub API, inputSchema: { repo: string, since: string } }, { name: type-analyze, path: ./agents/type-analyze.ts, description: Analyze TypeScript type changes in diff, inputSchema: { diff: string } } ], workflow: [ { agent: github-fetch, input: { repo: t3code/t3, since: 2024-05-01 } }, { agent: type-analyze, input: { diff: {{context.github_fetch_result}} } } ] }注意{{context.github_fetch_result}}这个语法。它不是模板引擎的简单替换而是控制台在运行时动态注入的上下文变量。当github-fetchAgent 执行完毕其output.data会被自动存入context的github_fetch_result键下供下一个 Agent 直接引用。这种“声明式编排 动态上下文注入”的模式让工作流定义既清晰又灵活。启动控制台只需t3code run它会加载agents.json动态import()所有 Agent 模块然后进入交互式命令行。你可以输入list agents查看所有已注册 Agent输入run github-fetch --repot3code/t3 --since2024-05-01单独调试一个 Agent或者输入run workflow启动整条流水线。整个过程没有隐藏的魔法所有行为都可通过命令行参数和配置文件精确控制。3.2 Agent 的编写规范一个合格的 Agent 必须满足的“三要素”在 T3 Code 生态中“Agent” 不是一个抽象概念而是一个有明确定义的工程实体。一个被控制台认可的 Agent必须同时满足以下三个要素缺一不可第一要素严格的输入/输出契约Contract Compliance每个 Agent 文件如agents/github-fetch.ts必须导出一个默认函数其签名必须与Agent类型完全一致。更重要的是它必须显式处理input.context。例如一个获取 GitHub Token 的 Agent绝不能硬编码 token而必须从input.context中安全获取import { Agent } from t3code/core; const githubFetchAgent: Agent async (input) { // 1. 从上下文中安全获取 token若不存在则抛出明确错误 const token input.context.getstring(github_token); if (!token) { return { status: error, data: null, log: [Missing github_token in context. Please set it first.], next: undefined }; } // 2. 使用 token 调用 API const response await fetch(https://api.github.com/repos/${input.query.repo}/pulls?since${input.query.since}, { headers: { Authorization: Bearer ${token} } }); // ... 处理响应 }; export default githubFetchAgent;这种设计强制开发者思考“上下文依赖”避免了传统脚本中常见的“全局变量污染”和“隐式状态传递”。第二要素可预测的错误处理Predictable Error HandlingT3 Code 的控制台不希望看到未捕获的Promise Rejection。因此每个 Agent 必须在try/catch块中包裹所有异步操作并将错误转化为结构化的AgentOutput。关键点在于错误必须分类而非笼统返回status: error。T3 Code 定义了四种标准错误类型network_error: 网络请求失败超时、连接拒绝auth_error: 认证失败token 过期、权限不足format_error: 输入数据格式错误JSON 解析失败、字段缺失logic_error: 业务逻辑错误API 返回非预期状态码、数据为空每种错误类型都对应不同的控制台响应策略。例如auth_error会触发控制台的reauth命令提示用户重新输入 token而network_error则会自动启用重试机制最多 3 次。这种细粒度的错误分类让调试不再是“大海捞针”而是“精准定位”。第三要素可审计的日志输出Auditable LoggingAgentOutput.log字段不是可选的而是 Agent 的“生命线”。它必须包含三类信息决策依据如“选择使用 v3 API 因为 v4 GraphQL 查询过于复杂”、关键数据摘要如“成功获取 12 个 PR共 47 个变更文件”、副作用说明如“已将 token 存入 context有效期 1 小时”。这些日志在控制台中会以不同颜色高亮显示绿色为 info黄色为 warn红色为 error并且可以被导出为 JSONL 格式供后续的 ELK 日志分析系统消费。我曾经在一个金融客户的项目中仅靠分析log字段就快速定位到一个 Agent 性能瓶颈它在每次调用时都重新初始化了一个庞大的正则表达式对象导致 CPU 占用飙升。如果没有结构化的日志这个问题可能需要数天才能发现。3.3 上下文Context管理不只是“共享变量”而是“状态机”T3 Code 的Context模块常被误解为一个简单的键值对存储KV Store但它实际上是一个轻量级的状态机State Machine。它的核心 API 包括context.set(key, value, options?): 设置值options可指定ttl生存时间单位毫秒和scope作用域如global、workflow、agentcontext.get(key, defaultValue?): 获取值若 key 不存在且无defaultValue则抛出ContextKeyNotFoundErrorcontext.delete(key): 删除键context.snapshot(): 创建当前上下文的只读快照用于 Agent 内部的临时状态隔离这种设计解决了 Agent 协作中最棘手的“状态污染”问题。举个例子Agent A 生成了一个临时文件路径/tmp/a123.json并存入context.set(temp_file, /tmp/a123.json)。Agent B 在执行时可能会修改这个路径如添加后缀但如果它使用context.snapshot()那么它的修改就不会影响到 Agent C。此外ttl机制让上下文具备了天然的“垃圾回收”能力。比如一个用于存储 OAuth 临时 code 的context.set(oauth_code, abc123, { ttl: 60000 })60 秒后会自动失效无需手动清理。我在一个需要处理大量并发 API 请求的项目中正是依靠scope: agent实现了每个 Agent 实例拥有独立的 HTTP 连接池配置彻底避免了连接复用导致的请求头污染问题。4. 实操过程从零开始搭建一个“自动生成 TypeScript 接口定义”的 Agent 工作流4.1 环境准备与项目初始化我们以一个真实需求切入公司有一个内部 RESTful API文档是 Swagger JSON 格式但前端团队每次都要手动编写对应的 TypeScript 接口定义interface User { id: number; name: string; }效率低下且容易出错。目标是用 T3 Code 搭建一个工作流输入 Swagger URL自动下载 JSON解析paths和definitions生成.d.ts文件并提交到 Git 仓库。整个过程不超过 30 分钟。第一步确保你的环境已安装 Node.js18.0和 npm。然后创建项目目录并初始化mkdir t3-swagger-gen cd t3-swagger-gen npm init -y npm install t3code/core typescript types/node npm install -D ts-node types/node这里ts-node是为了在开发阶段直接运行 TypeScript 文件避免每次修改都要tsc编译。接着用官方 CLI 初始化骨架npx t3code-cli init .这会生成前述的标准目录结构。现在我们需要为这个工作流定制一个config/agents.json。由于这是一个新项目我们先创建一个最简版本{ agents: [ { name: swagger-fetch, path: ./agents/swagger-fetch.ts, description: Download Swagger JSON from URL, inputSchema: { url: string } }, { name: swagger-to-ts, path: ./agents/swagger-to-ts.ts, description: Convert Swagger JSON to TypeScript interfaces, inputSchema: { swaggerJson: object } } ], workflow: [ { agent: swagger-fetch, input: { url: {{input.url}} } }, { agent: swagger-to-ts, input: { swaggerJson: {{context.swagger_json}} } } ] }注意{{input.url}}这个特殊语法。它表示工作流的初始输入参数用户在运行t3code run workflow --urlhttps://api.example.com/swagger.json时这个 URL 会被注入到第一个 Agent 的input.query中。这是一种非常实用的“参数化工作流”设计。4.2 编写swagger-fetchAgent安全、可靠的网络请求在agents/swagger-fetch.ts中我们编写第一个 Agent。重点在于错误分类和上下文注入。import { Agent } from t3code/core; import * as fs from fs/promises; const swaggerFetchAgent: Agent async (input) { try { // 1. 验证输入 const { url } input.query; if (!url || typeof url ! string || !url.startsWith(http)) { return { status: error, data: null, log: [Invalid URL format: ${url}], next: undefined }; } // 2. 发起请求带超时和重试 const controller new AbortController(); const timeoutId setTimeout(() controller.abort(), 10000); // 10秒超时 const response await fetch(url, { method: GET, headers: { Accept: application/json }, signal: controller.signal }); clearTimeout(timeoutId); if (!response.ok) { const errorType response.status 401 || response.status 403 ? auth_error : network_error; return { status: error, data: null, log: [HTTP ${response.status} ${response.statusText} for ${url}], next: undefined }; } const swaggerJson await response.json(); // 3. 验证 Swagger 格式基础校验 if (!swaggerJson.swagger !swaggerJson.openapi) { return { status: error, data: null, log: [Invalid Swagger/OpenAPI format. Missing swagger or openapi field.], next: undefined }; } // 4. 将结果存入上下文并返回 await input.context.set(swagger_json, swaggerJson, { ttl: 300000 }); // 5分钟有效期 return { status: success, data: swaggerJson, log: [Successfully fetched Swagger JSON from ${url}. Found ${Object.keys(swaggerJson.paths || {}).length} endpoints.], next: swagger-to-ts }; } catch (error) { if (error.name AbortError) { return { status: error, data: null, log: [Request to ${input.query.url} timed out.], next: undefined }; } return { status: error, data: null, log: [Unexpected error in swagger-fetch: ${error instanceof Error ? error.message : String(error)}], next: undefined }; } }; export default swaggerFetchAgent;这段代码展示了 T3 Code Agent 的典型模式输入验证 → 安全请求带超时→ 响应校验 → 上下文存储 → 结构化返回。特别是await input.context.set(...)这一行它确保了swagger_json这个键值对会在整个工作流的后续步骤中稳定可用。4.3 编写swagger-to-tsAgent从 JSON 到可维护的 .d.ts这是工作流的核心。我们将使用一个轻量级的开源库swagger-typescript-api来完成主要转换但关键在于如何将其无缝集成到 T3 Code 的契约中。首先安装依赖npm install swagger-typescript-api然后在agents/swagger-to-ts.ts中import { Agent } from t3code/core; import * as fs from fs/promises; import { generateApi } from swagger-typescript-api; const swaggerToTsAgent: Agent async (input) { try { // 1. 从上下文中获取 Swagger JSON const swaggerJson await input.context.getany(swagger_json); if (!swaggerJson) { return { status: error, data: null, log: [Missing swagger_json in context. Please run swagger-fetch first.], next: undefined }; } // 2. 创建临时目录存放生成的文件 const tempDir /tmp/t3-swagger-${Date.now()}; await fs.mkdir(tempDir, { recursive: true }); // 3. 调用 swagger-typescript-api 生成代码 // 注意这里我们绕过其 CLI直接调用其核心函数以获得完全控制权 await generateApi({ projectName: api-client, outputDir: tempDir, swagger: swaggerJson, templates: { // 自定义模板确保生成的 interface 名称符合公司规范 interface: export interface {{name}} { {{#each properties}} {{name}}: {{type}}; {{/each}} } } }); // 4. 读取生成的 .d.ts 文件内容 const generatedFile ${tempDir}/api-client/src/models/index.d.ts; const dtsContent await fs.readFile(generatedFile, utf8); // 5. 清理临时目录 await fs.rm(tempDir, { recursive: true, force: true }); // 6. 将生成的内容存入上下文并返回 await input.context.set(generated_dts, dtsContent); return { status: success, data: dtsContent, log: [Successfully generated TypeScript definitions. Found ${dtsContent.split(export interface).length - 1} interfaces.], next: undefined }; } catch (error) { return { status: error, data: null, log: [Failed to generate TypeScript definitions: ${error instanceof Error ? error.message : String(error)}], next: undefined }; } }; export default swaggerToTsAgent;这个 Agent 的亮点在于它没有把swagger-typescript-api当作黑盒而是深入其源码理解了generateApi函数的参数结构从而能精确控制输出。更重要的是它将生成的.d.ts内容存入context.generated_dts为后续可能的 Agent如git-commit提供了数据基础。4.4 扩展工作流添加 Git 提交 Agent实现端到端自动化一个完整的自动化工作流必须包含“交付”环节。我们来添加第三个 Agentgit-commit。它需要从上下文中读取generated_dts将其写入项目中的src/api/models/generated.d.ts然后执行git add和git commit。首先在config/agents.json中追加{ name: git-commit, path: ./agents/git-commit.ts, description: Commit the generated .d.ts file to Git, inputSchema: { filePath: string, commitMessage: string } }并在workflow数组末尾添加{ agent: git-commit, input: { filePath: ./src/api/models/generated.d.ts, commitMessage: chore(api): auto-generate TypeScript interfaces from Swagger } }然后在agents/git-commit.ts中import { Agent } from t3code/core; import * as fs from fs/promises; import { exec } from child_process; import { promisify } from util; const execAsync promisify(exec); const gitCommitAgent: Agent async (input) { try { // 1. 从上下文中获取生成的 dts 内容 const dtsContent await input.context.getstring(generated_dts); if (!dtsContent) { return { status: error, data: null, log: [Missing generated_dts in context. Please run swagger-to-ts first.], next: undefined }; } // 2. 确保目标目录存在 const dirPath input.query.filePath.substring(0, input.query.filePath.lastIndexOf(/)); await fs.mkdir(dirPath, { recursive: true }); // 3. 写入文件 await fs.writeFile(input.query.filePath, dtsContent, utf8); const fileName input.query.filePath.split(/).pop() || generated.d.ts; // 4. 执行 Git 命令 await execAsync(git add ${input.query.filePath}); await execAsync(git commit -m ${input.query.commitMessage}); return { status: success, data: { fileName, commitMessage: input.query.commitMessage }, log: [Successfully committed ${fileName} to Git.], next: undefined }; } catch (error) { return { status: error, data: null, log: [Git commit failed: ${error instanceof Error ? error.message : String(error)}], next: undefined }; } }; export default gitCommitAgent;至此一个端到端的 AI 编程工作流就完成了。你可以用一条命令启动它t3code run workflow --urlhttps://api.example.com/swagger.json控制台会依次执行swagger-fetch→swagger-to-ts→git-commit并在每一步输出详细的log。整个过程完全透明、可中断、可重试。如果某一步失败比如 Git 仓库未配置 remote控制台会清晰地告诉你错误发生在哪一行而不是让你去翻看一堆分散的日志文件。5. 常见问题与排查技巧实录那些只有踩过坑才知道的真相5.1 “Agent 找不到”错误路径、导出、类型三重陷阱这是新手遇到的第一个高频问题。当你运行t3code run workflow控制台报错Error: Cannot find agent xxx。别急着怀疑框架先按顺序排查这三重陷阱陷阱一路径解析错误Path ResolutionT3 Code 的agents.json中path字段是相对于config/目录的而不是项目根目录。如果你的agents.json在config/下而agents/目录也在config/同级那么path必须写成../agents/xxx.ts而不是./agents/xxx.ts。一个快速验证方法是在index.ts主入口中手动import一下这个路径看 TypeScript 编译器是否报错。陷阱二默认导出缺失Default Export MissingT3 Code 的加载器使用import()动态导入它要求模块必须有一个default导出。如果你写了export function myAgent() {...}而没有export default myAgent就会失败。正确的写法是// ✅ 正确 export default async function myAgent(input) { ... } // ❌ 错误即使有 export但没有 default export async function myAgent(input) { ... }陷阱三类型不匹配Type Mismatch最隐蔽的陷阱。你确认了路径和导出都没问题但控制台依然报错。这时打开node_modules/t3code/core/types/index.d.ts找到Agent接口定义然后检查你的 Agent 函数签名。常见错误包括async关键字遗漏必须是async函数、input参数类型写成了any而不是AgentInput、return语句返回了Promisevoid而不是PromiseAgentOutput。TypeScript 的类型推导有时会“宽容”但 T3 Code 的运行时加载器是“严格”的。我的经验是在 Agent 文件顶部显式加上类型注解import { Agent, AgentInput, AgentOutput } from t3code/core; const myAgent: Agent async (input: AgentInput): PromiseAgentOutput { ... }; export default myAgent;这样编辑器和编译器会立刻给你反馈省去大量运行时调试时间。5.2 “上下文丢失”问题作用域、生命周期、序列化三座大山另一个经典问题context.get(key)返回undefined明明上一个 Agent 刚set过。这通常不是 Bug而是对 T3 Code 上下文模型的理解偏差。请牢记以下三点大山一作用域Scope是默认的global但并非万能context.set(key, value)默认是global作用域意味着在整个工作流中都可见。但如果你在workflow的某个分支中比如if-else的else分支设置了context.set(key, value, { scope: agent })那么这个key只在当前 Agent 的执行周期内有效nextAgent 是看不到的。解决方案除非有明确的隔离需求否则一律使用默认的global作用域。大山二生命周期Lifecycle由ttl和workflow决定context.set时设置的ttl是“软限制”它只影响get时的缓存行为。真正的生命周期是由workflow的执行状态决定的。一个workflow执行完毕后其global上下文并不会自动清空。这意味着如果你连续运行两次t3code run workflow第二次的context会继承第一次的global状态。这通常是好事比如 token 复用但也可能导致意外。解决方案在workflow的第一个 Agent 中主动调用context.clear()或者在config/agents.json中为workflow添加一个prehook字段指定一个初始化 Agent。大山三序列化Serialization限制了值的类型T3 Code 的context底层是基于Map的但它支持的值类型有限。你不能set一个function、一个class instance、或者一个Buffer。只能setstring、number、boolean、object纯 JSON 对象、array。如果你尝试set一个Date对象它会被序列化为字符串set一个Map它会变成空对象{}。解决方案对于复杂对象先用JSON.stringify()序列化get时再JSON.parse()。虽然多了一步但保证了 100% 的兼容性。5.3 性能瓶颈排查CPU、内存、I/O三把标尺当你的工作流运行缓慢不要急于优化代码先用三把标尺客观测量标尺一CPU 占用率top或htop如果t3code进程的 CPU 占用长期超过 80%说明你的某个 Agent 在做密集计算如大文件解析、正则匹配。解决方案将计算密集型任务移出 Agent用child_process.fork()启动一个独立的 Worker 进程或者改用 Rust/WASM 编写的高性能库。标尺二内存增长process.memoryUsage()在 Agent 的log中定期打印process.memoryUsage().heapUsed / 1024 / 1024MB。如果这个数字在多次run后持续增长说明存在内存泄漏。最常见的原因是在 Agent 中创建了全局变量、事件监听器未移除、或setInterval未clearInterval。解决方案在 Agent 执行完毕后显式