1. 项目概述这不是又一个“代码助手”而是一次对智能体工程范式的重新定义“深入 opencode上篇工程全景、双会话内核与事件溯源”——这个标题里没有“AI编程”“Copilot替代品”这类泛泛而谈的标签它直指三个硬核关键词工程全景、双会话内核、事件溯源。我第一次在内部测试通道看到 opencode 的调试面板时下意识点开了它的会话历史树发现每一条用户输入背后都挂着两套并行演进的状态快照一套是面向用户的“对话流”另一套是面向执行引擎的“操作流”。那一刻我就意识到这根本不是把 LLM API 包一层壳的事它是在用工程化的方式把“人如何思考问题”和“机器如何执行任务”这两条原本纠缠不清的线物理性地拆开、标记、追踪、回溯。opencode 的核心价值不在于它调用了哪个模型而在于它构建了一套可观察、可调试、可审计的智能体运行时环境。你不需要懂 TypeScript 编译原理但如果你写过中大型前端项目就会立刻理解它为什么把类型声明文件.d.ts放在types/目录下——那不是为了炫技而是为了让整个智能体的行为契约像 React 组件 Props 那样在 IDE 里实时提示、静态校验、跨模块复用。它解决的不是“怎么写更快”而是“怎么改得更稳、查得更准、扩得更清”。适合三类人正在被“黑盒式 AI 工具”拖慢交付节奏的全栈工程师需要把 AI 能力嵌入现有 CI/CD 或运维流程的技术负责人以及所有厌倦了“重试三次才出结果”、渴望真正掌控 AI 执行过程的深度使用者。它不承诺“零代码”但承诺“每一行生成逻辑都有迹可循”。2. 内容整体设计与思路拆解为什么必须是“双会话”单线程抽象为何必然失败2.1 工程全景的本质从“功能堆砌”到“运行时契约”的范式迁移传统代码助手的架构图往往是一条清晰的流水线用户输入 → 提示词工程 → 模型调用 → 结果渲染。opencode 的工程全景图则像一张立体网络。它的核心不是 API 封装层而是Runtime Contract Layer运行时契约层。这一层的存在直接回答了我在实际项目中反复踩坑的问题当一个智能体要同时完成“读取 Git 日志”、“分析 PR 变更”、“生成 Changelog”、“更新 README”四个动作时如果中间某一步失败你是想让它从头再来一遍还是只重试“更新 README”这一步抑或你想知道它在“分析 PR 变更”时到底看了哪几个文件、跳过了哪些冲突块单会话模型无法回答这些问题因为它把“用户意图”和“系统动作”压缩在同一个上下文里就像把厨师的菜谱、采购清单、灶台温度、客人反馈全写在同一张便签纸上——信息密度高但完全不可拆分、不可追溯。opencode 的解决方案是强制分离两个维度User Session用户会话和Execution Session执行会话。前者记录“用户说了什么、想要什么、反馈如何”后者记录“系统调用了什么工具、传了什么参数、返回了什么原始数据、状态码是多少”。这两个会话不是简单地“一对一分离”而是通过Event ID Causal Link因果链进行双向锚定。比如用户说“帮我修复 package.json 里的依赖版本冲突”这个语句在 User Session 中生成 Event IDusr-7a3f紧接着系统自动触发npm ls --depth0命令这个动作在 Execution Session 中生成 Event IDexe-9c2d并在其元数据中明确标注caused_by: usr-7a3f。这种设计让整个系统具备了类似数据库事务日志WAL的特性你可以随时按用户视角回放交互也可以按系统视角审计执行路径还能做跨会话的关联分析——比如统计所有caused_by指向某个特定用户指令的失败执行事件从而精准定位提示词缺陷或工具兼容性问题。提示这种分离不是技术炫技。我曾用一个纯单会话的内部工具处理 200 个微服务的依赖升级每次失败后都要手动翻日志、比对时间戳、猜测哪一步出了问题平均排错耗时 47 分钟。切换到 opencode 后同样的任务失败时直接点击错误事件旁的“Show Execution Trace”按钮3 秒内就能定位到是docker build步骤因磁盘空间不足退出且能一键重放该步骤——因为执行会话里完整保存了当时的工作目录、环境变量、命令输出流。2.2 “双会话内核”的底层实现逻辑Bun 作为运行时的不可替代性为什么 opencode 选择 Bun 而非 Node.js 作为底层运行时网上很多文章只说“Bun 更快”但这完全没说到点子上。关键在于Bun 的原生 TypeScript 支持与进程模型。Node.js 的tsc --watch是一个独立的编译进程它和你的主应用进程是割裂的而 Bun 在启动时会将.ts文件直接送入其内置的 Swift 实现的 TypeScript 解析器编译、类型检查、执行一气呵成且共享同一内存空间。这对 opencode 的双会话内核意味着什么我们来看一个典型场景用户在编辑器里修改了一个自定义工具的类型定义比如gitDiffTool.d.ts期望它能立刻影响后续的智能体行为。在 Node.js 环境下你需要手动触发tsc重新编译重启整个 opencode 服务等待新类型定义加载进内存再发起一次新会话。而在 Bun 环境下这个过程被压缩为保存.d.ts文件下一次gitDiffTool.run()调用时Bun 自动检测到类型文件变更即时重新解析并更新类型缓存执行会话直接使用最新类型进行参数校验与返回值推断。这种“热类型重载”能力是双会话内核得以成立的基石。因为 Execution Session 的每一个工具调用都依赖于精确的类型契约来保证输入安全与输出可预测。如果类型定义不能秒级生效那么“执行流”的稳定性就无从谈起。Bun 的另一个杀手锏是其Zero-Copy Buffer 处理。当 opencode 需要将一个 50MB 的git log --oneline输出流实时喂给 LLM 进行摘要时Node.js 会经历多次 Buffer 复制与编码转换UTF-8 ↔ UTF-16而 Bun 可以直接在内存中映射原始字节流并通过其内置的Bun.file()API 进行零拷贝读取。实测下来同等负载下Bun 的内存占用比 Node.js 低 38%GC 暂停时间减少 62%。这不是“锦上添花”而是当你的智能体需要处理大型 monorepo 或二进制资产时“能不能跑起来”的分水岭。2.3 事件溯源Event Sourcing为何是唯一可行的持久化方案很多人看到“事件溯源”第一反应是“这玩意儿太重了小项目用不上”。但在 opencode 的语境下事件溯源不是一种可选的架构风格而是应对智能体不确定性本质的必要约束。智能体的每一次执行本质上都是一个概率性过程模型可能生成语法错误的代码工具可能因网络抖动返回超时用户可能在中途打断并修改指令。如果采用传统的“状态快照”State Snapshot方式存储会话比如每次保存整个sessionState对象你会立刻陷入“状态爆炸”困境——一个包含 10 次交互、每次调用 3 个工具的会话其状态对象可能包含数百个嵌套字段而其中 90% 的字段在两次快照间毫无变化。更致命的是你永远无法回答“用户在第 7 步说‘等等先别提交’这个中断指令具体影响了哪些后续执行” 因为快照只告诉你“最终状态是什么”不告诉你“状态是如何一步步变成这样的”。opencode 的事件溯源方案强制所有状态变更只能由不可变事件Immutable Event驱动。每个事件都是一个结构化的 JSON 对象例如{ eventId: evt-4b8e, eventType: ToolExecutionStarted, timestamp: 2024-05-22T14:23:18.442Z, sessionId: ses-1a9f, toolName: gitCommit, inputParams: { message: chore: update dependencies, files: [package-lock.json] }, causalId: usr-7a3f }所有事件按时间顺序追加到一个只读日志Append-Only Log中。当前会话状态是通过重放Replay该日志中所有相关事件计算得出的。这种设计带来了三个决定性优势可追溯性你可以精确回滚到任意历史时刻的状态只需重放前 N 个事件可审计性每一个状态变更都有明确的“谁、何时、因何、做了什么”的完整证据链可扩展性事件日志天然支持水平分片与流式处理为后续接入 Kafka、Flink 做实时分析埋下伏笔。我曾用一个基于 SQLite 的快照方案做过对比实验处理一个 500 步的复杂部署会话快照存储体积达 127MB而等价的事件日志仅 8.3MB且查询任意中间状态的耗时从 1.2 秒降至 47 毫秒。这不是优化而是范式差异带来的数量级提升。3. 核心细节解析与实操要点从 TypeScript 类型声明到双会话调试的落地细节3.1types/目录下的声明文件不只是类型更是智能体的“接口说明书”opencode 将所有自定义工具、事件、配置的类型定义统一放在types/目录下这绝非随意约定。它遵循的是 TypeScript 社区最成熟的Project References模式其核心思想是每个智能体模块都应该是一个拥有独立类型边界的、可复用的单元。举个真实例子我们团队开发了一个用于自动化安全扫描的工具snykScanTool它的声明文件types/snykScanTool.d.ts内容如下// types/snykScanTool.d.ts declare module snyk-scan-tool { export interface SnykScanOptions { /** * description 扫描目标路径支持 glob 模式 * example ./src/**/*.{js,ts} */ target: string; /** * description 是否启用深度递归扫描影响性能 * default false */ deep?: boolean; /** * description 指定 Snyk API Token若未提供则使用环境变量 SNYK_TOKEN */ token?: string; } export interface SnykScanResult { /** * description 发现的高危漏洞数量 */ highSeverityCount: number; /** * description 漏洞详情列表包含 CVE ID、描述、修复建议 */ vulnerabilities: Array{ cve: string; description: string; remediation: string; }; } export function scan(options: SnykScanOptions): PromiseSnykScanResult; }这份声明文件的价值远超“让 IDE 有提示”这么简单。它实质上是snykScanTool模块对外发布的契约文档。当你在智能体逻辑中调用scan({ target: ./src })时TypeScript 编译器不仅会检查target字段是否存在还会根据example注释为你自动补全./src/**/*.{js,ts}根据default false提醒你deep是可选参数当你传入token: abc时它会静默通过但如果你传入token: 123数字它会立刻报错Type number is not assignable to type string。更重要的是这个契约是可继承、可组合的。另一个团队开发的ciPipelineTool可以在其声明文件中直接import { SnykScanResult } from snyk-scan-tool并将其作为自己输出的一部分。这种基于类型的模块协作让整个智能体生态摆脱了“靠文档约定、靠口头沟通、靠试错验证”的原始阶段进入了“契约即代码、类型即文档”的工程化新阶段。注意不要把.d.ts文件当成“补充说明”。我见过太多团队把类型定义写在.ts文件里然后用export type导出。这会导致类型定义与实现强耦合一旦工具逻辑重构类型就可能失效。正确的做法是.d.ts文件应独立于实现只描述“它应该是什么”而.ts文件负责“它实际上是怎么做的”。两者通过declare module关联互不干扰。3.2 双会话内核的调试实战如何像调试 React 应用一样调试智能体opencode 的调试体验是我见过最接近现代前端开发的 AI 工具。它的核心在于Session Inspector会话检查器一个集成在 VS Code 插件中的可视化面板。打开它你会看到左右两个平行的世界左侧User Session一个标准的聊天界面显示用户消息、AI 回复、用户点赞/点踩反馈。每条消息下方有一个小小的▶图标点击即可展开其关联的 Execution Session。右侧Execution Session一个树状结构的执行轨迹图。根节点是用户指令子节点是它触发的所有工具调用孙子节点是工具调用产生的子任务如git diff命令的 stdout/stderr 流。每个节点都清晰标注了Status:pending/success/error/cancelledDuration: 执行耗时毫秒Input: 传入的参数JSON 格式可折叠Output: 返回的结果支持语法高亮、大文本懒加载Logs: 工具执行过程中的详细日志包括 stderr调试一个失败的会话流程极其简单在 User Session 中找到报错的 AI 回复点击其下方的▶跳转到对应的 Execution Session 根节点在树中找到状态为error的叶子节点比如dockerBuildTool展开其Output发现错误信息是ERROR: failed to solve: rpc error: code Unknown desc failed to compute cache key: /node_modules not found展开其Input确认传入的contextPath确实是./而Dockerfile中的COPY ./node_modules ./node_modules语句要求node_modules必须存在于是立刻明白问题不在 Dockerfile而在于智能体在执行docker build前没有先运行npm install。这是一个典型的“执行顺序缺失”问题而非“模型幻觉”。这个过程和你在 React DevTools 里点击一个报错组件、查看其 props、再逐层向上追溯父组件传入的数据逻辑完全一致。区别只在于React 调试的是虚拟 DOM 的状态流而 opencode 调试的是智能体的动作流。它把原本需要翻阅数万行日志、拼凑碎片信息的“侦探工作”变成了所见即所得的“外科手术”。3.3 事件溯源的日志格式与消费实践不只是记录更是分析的起点opencode 的事件日志并非简单的文本堆砌而是严格遵循CloudEvents 1.0 规范的结构化数据。每一个事件都是一个符合标准的 JSON 对象包含specversion、type、source、id、time等必需字段。这意味着你无需任何定制开发就可以将这些事件无缝接入现有的可观测性生态。我们团队的实践是采集层利用 opencode 提供的--event-log-file启动参数将所有事件追加写入一个本地文件/var/log/opencode/events.log。该文件采用行分隔 JSONNDJSON格式每行一个事件便于tail -f实时监控。传输层部署一个轻量级的filebeat实例配置其multiline.pattern为^{id:确保每个事件被当作一个完整的日志行发送。存储与分析层事件被送入 Elasticsearch。我们创建了一个专门的索引opencode-events-*并为其配置了针对eventType、sessionId、causalId的高效 mapping。可视化层在 Kibana 中我们构建了几个关键看板会话健康度看板统计ToolExecutionFailed事件占总执行事件的比例按toolName分组一眼看出哪个工具最不稳定用户意图漏斗看板追踪从UserMessageReceived到ToolExecutionStarted再到AIResponseGenerated的转化率识别用户指令被“理解失败”的瓶颈环节因果链分析看板输入一个usr-xxxxID自动展示所有causalId为此 ID 的事件形成一条完整的“用户指令→系统响应”全链路视图。这套方案的价值在一次线上事故中得到了充分验证。用户报告“智能体在处理 PR 时总是卡住”我们没有去猜而是直接在 Kibana 中搜索eventType: ToolExecutionStarted AND toolName: githubPrReview发现其duration字段的 P95 值高达 120 秒远超正常值 5 秒。进一步筛选status: error的事件发现错误信息是GitHub API rate limit exceeded。根源立刻浮出水面我们为githubPrReview工具配置的 token 权限不足导致它在获取 PR 评论时被迫降级为未认证请求触发了极低的速率限制。问题定位耗时不到 3 分钟而修复方案就是更换一个拥有pull_requests:read权限的 token。如果没有事件溯源提供的结构化、可查询日志这个故障排查至少需要半天。4. 实操过程与核心环节实现从 Ubuntu 安装到 VS Code 深度集成的完整链路4.1 Ubuntu 系统下的 opencode 安装与初始化绕过所有“免费额度”陷阱在 Ubuntu 上安装 opencode官方文档推荐的curl -fsSL https://get.opencode.dev | sh方式看似简单实则暗藏玄机。最大的坑就是标题里反复出现的错误提示opencodes free tier can only be used from within opencode。这个错误99% 的情况并非因为你没登录而是因为你的终端环境缺少 opencode 所需的“上下文标识”。opencode 的免费额度是与一个特定的、由其 CLI 创建的“沙箱环境”绑定的而不是与你的 GitHub 账号或邮箱绑定的。正确安装流程如下请严格按顺序执行安装 Bun必须opencode 依赖 Bun 的特定版本目前是v1.1.30。不要用apt安装旧版务必使用官方推荐的一行命令curl -fsSL https://bun.sh/install | bash # 安装完成后重启你的 shell 或执行 source ~/.bashrc bun --version # 确认输出 1.1.30安装 opencode CLI使用bunxBun 的 npx 替代品进行安装这是关键一步bunx opencode-clilatest install # 注意这里必须用 bunx不能用 npm install -g 或 yarn global add # 因为 bunx 会确保 CLI 与当前 Bun 运行时完全兼容初始化沙箱环境核心步骤运行以下命令它会启动一个本地 Web 服务器并在浏览器中打开 opencode 的初始化向导opencode init --sandbox这个--sandbox参数至关重要。它会在~/.opencode/sandbox/目录下创建一个隔离的配置与数据存储区生成一个唯一的sandbox-id并将其写入~/.opencode/config.json自动为你申请一个与该 sandbox 绑定的免费额度密钥API Key启动一个本地代理服务将所有模型请求路由到 opencode 的后端同时注入必要的X-Sandbox-ID请求头。提示如果你跳过这一步直接运行opencode start那么 CLI 会尝试使用全局配置而全局配置默认没有 sandbox-id因此后端会拒绝你的免费额度请求抛出那个令人困惑的错误。我第一次踩坑时花了整整一个下午在 GitHub Issues 里搜索最后才发现问题出在没加--sandbox。验证安装在初始化向导的 Web 界面中点击“Test Connection”它会自动运行一个echo Hello, opencode!的最小化会话。如果看到绿色的成功提示说明沙箱环境已就绪。4.2 VS Code 插件的深度配置让智能体成为你编辑器的“第二大脑”opencode 的 VS Code 插件opencode.vscode远不止是一个“发送消息”的窗口。它的真正威力在于与编辑器原生能力的深度缝合。以下是几个必须配置的关键项工作区感知Workspace Awareness默认情况下插件是全局生效的。你需要在你的项目根目录下创建一个.opencode/config.json文件内容如下{ tools: [ { name: gitDiffTool, path: ./tools/git-diff-tool.ts, description: Get a formatted diff of unstaged changes }, { name: jestRunnerTool, path: ./tools/jest-runner-tool.ts, description: Run Jest tests for the current file or project } ], model: opencode-go-v2-cc-switch, temperature: 0.3 }这个配置告诉插件“在这个工作区里我只信任并允许使用gitDiffTool和jestRunnerTool这两个自定义工具且默认使用opencode-go-v2-cc-switch模型”。这样当你在编辑一个.ts文件时右键菜单会出现 “Opencode: Run Jest on Current File”点击后插件会自动调用jestRunnerTool并将当前文件路径作为参数传入。整个过程无需你手动输入任何命令。编辑器命令绑定Command Binding在 VS Code 的settings.json中添加以下配置将常用操作绑定到快捷键keybindings: [ { key: ctrlalti, command: opencode.interact, when: editorTextFocus }, { key: ctrlaltr, command: opencode.runCurrentFile, when: editorTextFocus editorLangId typescript } ]其中opencode.runCurrentFile是一个高级命令它会读取当前文件的 AST提取所有export的函数和类型生成一个动态的提示词描述“这个文件是一个 TypeScript 工具模块它提供了 X, Y, Z 功能”调用模型生成一个完整的、可直接运行的测试用例或使用示例。类型定义自动导入Auto-Import这是最惊艳的功能。当你在.ts文件中输入const result await snykScanTool.scan(时VS Code 不仅会提示SnykScanOptions类型还会在你按下Enter后自动在文件顶部插入import { snykScanTool } from snyk-scan-tool;。这个功能依赖于插件对types/目录的深度索引以及对 TypeScript 语言服务的增强。它让“使用智能体工具”这件事变得和“导入一个 npm 包”一样自然。4.3 构建第一个双会话智能体一个真实的“PR 自动审查”案例现在让我们动手构建一个能解决实际问题的智能体PR 自动审查助手。它的目标是当开发者推送一个 PR 时自动运行代码质量检查、安全扫描并生成一份结构化的审查意见。第一步定义工具契约types/prReviewer.d.tsdeclare module pr-reviewer-tool { export interface PrReviewOptions { /** * description GitHub PR URL例如 https://github.com/user/repo/pull/123 */ prUrl: string; /** * description 是否启用 ESLint 检查默认启用 * default true */ eslint?: boolean; /** * description 是否启用 Snyk 安全扫描默认启用 * default true */ snyk?: boolean; } export interface PrReviewResult { /** * description 代码质量评分0-100 */ qualityScore: number; /** * description 安全风险等级none | low | medium | high | critical */ securityLevel: string; /** * description 生成的审查意见Markdown 格式 */ reviewComment: string; } export function review(options: PrReviewOptions): PromisePrReviewResult; }第二步实现工具逻辑tools/pr-reviewer-tool.tsimport { parsePRUrl } from ./utils/github; import { runESLint } from ./eslint-runner; import { scanWithSnyk } from ./snyk-scanner; export async function review(options: PrReviewOptions): PromisePrReviewResult { const { owner, repo, number } parsePRUrl(options.prUrl); // 并行执行两项检查 const [eslintResult, snykResult] await Promise.all([ options.eslint ? runESLint({ owner, repo, prNumber: number }) : Promise.resolve(null), options.snyk ? scanWithSnyk({ owner, repo, prNumber: number }) : Promise.resolve(null) ]); // 计算综合评分 let qualityScore 100; if (eslintResult?.errors.length) { qualityScore - eslintResult.errors.length * 5; // 每个错误扣5分 } let securityLevel: PrReviewResult[securityLevel] none; if (snykResult?.highSeverityCount) { securityLevel snykResult.highSeverityCount 3 ? critical : high; } else if (snykResult?.mediumSeverityCount) { securityLevel medium; } // 生成 Markdown 评论 const reviewComment ## PR 自动审查报告 ### 代码质量 - **综合评分**: ${Math.max(0, qualityScore)}/100 - **ESLint 错误**: ${eslintResult?.errors.length || 0} 个 ### ⚠️ 安全风险 - **风险等级**: ${securityLevel} - **高危漏洞**: ${snykResult?.highSeverityCount || 0} 个 ### 建议 ${securityLevel critical ? - **立即修复**存在严重安全漏洞请优先处理。 : - 代码质量良好可以合并。} ; return { qualityScore, securityLevel, reviewComment }; }第三步在智能体中调用agents/pr-auto-reviewer.tsimport { prReviewTool } from pr-reviewer-tool; export async function handlePR(prUrl: string) { console.log(开始审查 PR: ${prUrl}); try { const result await prReviewTool.review({ prUrl, eslint: true, snyk: true }); // 这里可以调用 GitHub API将 result.reviewComment 作为 PR 评论发布 console.log(审查完成生成评论:, result.reviewComment); return result; } catch (error) { console.error(审查失败:, error); throw error; } } // 导出为默认函数供 opencode CLI 调用 export default handlePR;第四步在 VS Code 中测试打开一个 PR 的 URL复制到剪贴板然后在 VS Code 中按下CtrlAltI在弹出的输入框中输入“请用 pr-auto-reviewer 审查这个 PR”并粘贴 URL。几秒钟后你将在右侧的 Session Inspector 中清晰地看到User Session你的指令Execution SessionprReviewTool.review()的完整调用链包括runESLint和scanWithSnyk两个子任务的并行执行、各自的输入输出、耗时统计。整个过程你不需要离开编辑器不需要切换到终端不需要手动拼接命令。智能体已经成为了你开发工作流中一个可信赖、可预测、可调试的组成部分。5. 常见问题与排查技巧实录那些只有亲手踩过才知道的坑5.1 “opencodes free tier can only be used from within opencode” 错误的终极排查指南这个错误是 opencode 新手遇到频率最高的问题但它背后的原因却五花八门。根据我协助超过 200 个团队的经验将其归类为以下四层按此顺序排查99% 的问题都能解决排查层级检查项如何验证解决方案L1沙箱环境缺失~/.opencode/config.json中是否存在sandboxId字段cat ~/.opencode/config.json | jq .sandboxId运行opencode init --sandbox重新初始化L2CLI 版本不匹配当前使用的opencodeCLI 是否由bunx安装which opencode应该输出类似/home/user/.bun/bin/opencode卸载所有其他来源的 CLI重新用bunx opencode-clilatest installL3环境变量污染终端中是否设置了OPENCODE_API_KEY或OPENCODE_BASE_URLenv | grep -i opencode清空这些环境变量或在启动 CLI 前unset OPENCODE_API_KEYL4网络代理干扰你的公司网络是否强制使用了 HTTP 代理curl -v https://api.opencode.dev/health查看是否能直连在~/.opencode/config.json中添加proxy: http://your-proxy:8080实操心得我曾经在一个金融客户的内网环境中连续三天无法解决这个问题。最后发现他们的网络策略会劫持所有 HTTPS 请求并在响应头中注入一个X-Internal-Proxy: true字段。而 opencode 的后端服务恰好会检查这个字段如果存在就认为请求来自非官方客户端从而拒绝免费额度。解决方案是在~/.opencode/config.json中添加headers: { X-Internal-Proxy: false }强行覆盖掉这个恶意头。这个技巧官方文档里永远不会写但却是企业级部署的必备知识。5.2 TypeScript 类型声明文件.d.ts的常见误用与最佳实践.d.ts文件是 opencode 的“神经系统”但也是最容易出错的地方。以下是三个高频误用场景及修正方案误用 1在.d.ts中写实现逻辑// ❌ 错误.d.ts 文件里不应该有函数体 declare module my-tool { export function doSomething(): string { return hello; // 这是 JS 实现不能出现在 .d.ts 里 } }✅ 正确只声明签名实现放在.ts文件里// types/my-tool.d.ts declare module my-tool { export function doSomething(): string; } // tools/my-tool.ts export function doSomething(): string { return hello; }误用 2类型定义过于宽泛失去约束力// ❌ 错误any 类型等于没有类型 declare module bad-tool { export function badFunction(input: any): any; }✅ 正确使用精确的、带文档的接口// types/good-tool.d.ts declare module good-tool { /** * description 从指定 URL 获取 JSON 数据 * param url - 必须是有效的 HTTPS URL * returns Promiseresolve 值为 JSON.parse 后的对象 */ export function fetchJsonT(url: string): PromiseT; }误用 3未处理异步操作的类型// ❌ 错误忽略了 Promise 的泛型 declare module async-tool { export function getData(): Promise; // 缺少 T }✅ 正确为 Promise 显式指定泛型
