Community写作与编辑github.com

swiftpostlabs/agentic-tools

为 AI 代理提供可共享的技能和工具

agentic-tools 是什么?

该技能为现代 Deno 项目提供可移植的默认配置和实践指南,特别适用于混合使用 Deno 与 Node 工具链的代码库、需要从旧版 Deno 模式迁移的项目,或正在将 Deno 集成到现有 TypeScript/Node 仓库的场景。它涵盖了 deno.json 配置、依赖管理、权限控制、与 tsconfig.json 及 ESLint 的共存策略,以及混合仓库中的边界划分。该技能详细指导如何用 Deno 原生工具(deno check、deno task、deno fmt、deno lint)替代 tsc 和 ESLint,同时保留原有配置中的有效规则。支持在 VS Code 等编辑器中通过 deno.enablePaths 实现路径级别的工具激活,避免 Deno 与 Node 工具对同一文件产生冲突。

兼容平台~Claude Code~Codex CLI~Cursor✓Antigravity
npx skills add swiftpostlabs/agentic-tools

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Deno

目的

为现代 Deno 项目提供可移植的默认配置,尤其适用于混合 Deno 与 Node 工具链的代码库、需要从旧版 Deno 模式进行清晰迁移的项目,或正在将 Deno 集成到现有 TypeScript 或 Node 仓库的场景。

何时使用此技能

  • 编写 Deno 脚本、服务器或边缘代码时。
  • 配置 deno.json、任务和依赖来源时。
  • 调整现有的 tsconfig.json 或 eslint.config.* 文件以与 Deno 共存时。
  • 在单个仓库中混合使用 Deno 代码与 Node 或 TypeScript 代码时。
  • 审查 Deno 权限、测试或运行时模式时。

默认配置

  • 使用 deno.json 作为 Deno 的配置来源。
  • 当 Deno 拥有工作流控制权时,优先使用 deno check、deno task、deno fmt、deno lint 和 deno test,而非临时包装工具。
  • Deno 的原生工具链对于 Deno 管理的代码已足够;仅当仓库中同时存在 Deno 边界之外的 Node 管理包或脚本时,才使用 Yarn。
  • 仅针对 Node 拥有的路径或 TypeScript 项目图谱(Deno 工作区和目录范围无法清晰表达的情况)保留 tsconfig.json。
  • 记住现代 Node 也通过内置的类型剥离直接运行 TypeScript;选择 Deno 是出于其运行时、权限、依赖和工具模型,而不仅仅是为了避免使用 tsc 或 ts-node。
  • 对于 Deno 拥有的文件,优先使用 deno lint 和 deno fmt;仅当仓库或编辑器确实需要 ESLint 生态系统时才添加 ESLint。
  • 当用 deno lint 替换 ESLint 时,检查现有 ESLint 意图,并将其转移到 deno.json 的包含、排除、lint 规则或文档化例外中,而不是直接丢弃配置。
  • 当用 deno check 替换 tsc 时,检查现有的 tsconfig.json,将相关的编译器选项、包含、排除、库和严格性期望转换为 deno.json 或范围清晰的保留 tsconfig.json。
  • 当基于 npm 的编辑器工具(如 ESLint)必须在 Deno 仓库中运行时,设置 nodeModulesDir: "auto",并用 deno task 包装命令。
  • 当 Deno 拥有依赖管理权限时,使用 deno add 安装依赖,不要将 deno run npm:<package> 视为安装的替代方案。对仅用于开发的 CLI 和工具,使用 deno add --dev npm:<package>。
  • 对于已安装的 CLI 工具,将其 deno task 命名为工具名,并按名称调用已安装的二进制文件,例如,在 deno add --dev npm:sample-tool 后,添加 "sample-tool": "sample-tool"。
  • 在 Deno 拥有的代码中默认优先使用 .ts 模块;不要为了跳过 Deno 不需要的构建步骤而降级到 JavaScript。
  • 优先使用 JSR 包、npm: 说明符或显式的导入映射条目,而不是分散的旧式 URL 导入。
  • 当基于 npm 的 CLI 具有安装后行为(与一次性执行不兼容)时,优先使用 nodeModulesDir: "auto",在 allowScripts 中允许该包,使用 deno add 或 deno add --dev 添加依赖,然后从 deno task 调用已安装的二进制文件。
  • Deno 2 有意与 package.json、npm 包和 Node 内置模块兼容;将 Deno 特定配置保存在 deno.json 中,而不是试图让 tsconfig.json 同时承载两者。
  • 对于服务器,优先使用 Web 标准 API 和 Deno.serve。
  • 将权限视为设计决策,而非事后补救。

任务框架

命令或操作内容原因时机预期结果
谨慎采用 tsconfig.json 和 ESLint决定哪些保留在 Node 拥有的配置中,哪些移入 deno.json。当两个工具链试图拥有相同文件时,混合仓库会迅速变得混乱。将 Deno 引入现有 TypeScript 或 Node 代码库时。Deno 和 Node 工具链各自拥有明确的边界。
配置 deno.json在 Deno 的配置文件中定义任务、编译器选项和依赖约定。Deno 应该拥有自己的工作流,而不是意外借用 Node 中心的配置。启动或重构 Deno 项目时。Deno 命令和编辑器行为保持一致。
安装 Deno 拥有的 npm CLI对开发工具运行 deno add --dev npm:<package>,然后添加一个同名的任务,调用已安装的二进制文件。依赖、锁文件、本地二进制文件和任务入口点在 Deno 的包管理器下保持一致。向 Deno 拥有的工作流添加代码生成器、浏览器自动化 CLI、linter 或格式化程序等工具时。deno.json 和锁文件记录依赖,deno task <tool> 运行已安装的 CLI。
设置混合边界在混合仓库中分离 Deno 拥有的路径和 Node 拥有的路径。工具冲突是混合仓库最常见的失败原因之一。当 Deno 代码与 Node 或 TS 工具并存时。编辑器和命令不会争夺同一文件。
审查权限选择显式权限和任务包装器以管理运行时访问。Deno 的安全模型仅在权限经过深思熟虑时才有帮助。在运行新脚本或公开 Deno CLI 工作流之前。文件系统、网络和环境访问都是有意且可审计的。
排查 Deno 工作流问题在猜测之前,使用 Deno 原生检查、调试器标志和模块图工具。许多 Deno 问题是配置、权限或所有权问题,而非代码错误。当混合仓库或迁移的工具链出现意外行为时。根本原因缩小到配置、权限或运行时行为。

核心规则

TypeScript、tsconfig.json 和库

  • 将 Deno 编译器设置放在 deno.json 的 compilerOptions 中;不要为了运行 deno check 而复制完整的 Node tsconfig.json。
  • 现有的 Node + TypeScript 工作区可以保留 tsconfig.json;当目录同时包含 deno.json 或 package.json 时,Deno 会探测它。
  • 如果父级 deno.json 定义了 compilerOptions,则这些选项优先于重叠的 tsconfig.json 选项。
  • 如果目标是替换 tsc,首先盘点当前 tsconfig.json 的行为。在 Deno 配置中保留有意义的严格性、模块解析、JSX、库、包含和排除决策,或记录为什么它们不再适用。
  • 使用 deno.json 中的 compilerOptions.lib 来建模真实的运行时表面。对于 SSR 或浏览器加 Deno 代码,优先选择 ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"] 等组合;对于 Deno Worker,优先选择 ["deno.worker"]。
  • 当 JavaScript 模块需要显式类型检查或声明时,使用 compilerOptions.checkJs、// @ts-check、@ts-types、@ts-self-types 或 compilerOptions.types。
  • 仅当 Node 拥有的文件夹、TypeScript 项目引用或包含/排除粒度仍然需要时,才保留 tsconfig.json。

Linting、格式化和 ESLint

  • 使用 deno lint 和 deno.json 中的 lint 部分作为 Deno 拥有代码的默认 lint 所有者。
  • 使用 deno fmt 和 deno.json 中的 fmt 部分作为 Deno 拥有代码的默认格式化程序。
  • deno lint 已经涵盖了一套受 ESLint 启发的推荐规则集;不要仅仅因为习惯而保留 ESLint。
  • 如果目标是替换 ESLint,首先盘点当前 eslint.config.* 的行为。在 Deno 的 lint/fmt 配置中保留有意义的文件范围、全局变量、忽略项和规则意图,或记录哪些规则被有意丢弃(因为 Deno 已经涵盖或拒绝它们)。
  • 如果需要自定义的仅 Deno 规则,考虑使用 lint.plugins;注意 lint 插件 API 是实验性的,需要 Deno 2.2 或更高版本。
  • 如果仓库或编辑器仍然需要 ESLint,将其作为显式的辅助工具:设置 nodeModulesDir: "auto",创建 eslint.config.js,并用 deno task 包装调用,例如 deno task eslint。
  • 尽可能为每个文件集保持一个 lint 所有者。如果 deno lint 和 ESLint 都运行在相同文件上,记录原因,否则可能会遇到重复和冲突的诊断。

Node 兼容性和混合仓库

  • Deno 2 理解 package.json、node_modules、npm 工作区和 Node 内置模块;混合仓库是受支持的方式,而非临时方案。
  • 现代 Node 也可以直接执行 TypeScript。在混合仓库中,根据权限、依赖模型、任务运行器和部署目标来决定 Node 与 Deno 的所有权,而不仅仅是 TypeScript 执行。
  • 如果存在 package.json 并且希望 Deno 自动创建和刷新 node_modules,设置 nodeModulesDir: "auto"。对于 package.json,Deno 2 默认使用 "manual"。
  • nodeModulesDir 是工作区根设置;不要尝试在每个工作区成员中设置它。
  • 当 Deno 拥有依赖更新流程时,使用 deno install 或 deno add。不要假设 Deno 1 的自动安装行为。
  • 在 Deno 拥有的仓库中,对仅用于开发的 npm CLI 使用 deno add --dev npm:<package>。添加后,通过 deno task 暴露二进制文件,例如 "sample-tool": "sample-tool",而不是 "sample-tool": "deno run -A npm:sample-tool"。
  • 提交由 deno add 产生的清单和锁文件更新;仅靠任务别名不是依赖安装。
  • 如果只有单个子树是 Deno,不要为整个混合工作区启用 Deno 工具。
  • 优先使用基于路径的编辑器激活,如 deno.enablePaths,以便 Node 和 Deno 工具不会争夺同一文件。
  • 在文件夹结构、任务和文档中明确 Deno 的边界。

权限、环境和安全

  • 优先使用精确的 --allow-* 标志或在 deno.json 中命名权限集,而非 -A。
  • 当仓库在 deno.json 中定义了权限集时,使用 -P 或 --permission-set=<name>。
  • 当 CLI 应加载 .env 文件时使用 --env-file,或当程序本身需要加载时使用 @std/dotenv;两者都需要显式的环境和文件权限。
  • 对应用程序代码优先使用最小权限,并在任务和示例中明确环境、文件系统、网络和子进程访问。
  • 将 --allow-run 和 --allow-ffi 视为沙箱逃逸通道。除非明确打算完全信任,否则避免使用 --allow-run=deno。
  • 对于权限调试或审计,使用 DENO_TRACE_PERMISSIONS=1 和 DENO_AUDIT_PERMISSIONS=<path>。

故障排除和迁移

  • 当运行时成功与类型检查行为不一致时,使用 deno check、deno check --all 或 deno run --check。
  • 使用 deno info <entrypoint> 检查模块图,了解导入、缓存和权限行为。
  • 在手动编辑每个 lint 问题之前,使用 deno lint --fix 进行常见的迁移清理。
  • 对于调试器设置,当进程生命周期短时使用 --inspect-brk,当检查器或模块解析混乱时使用 --log-level=debug,当运行时挂起或异常缓慢时使用 --strace-ops。
  • 当故障排查问题确实是性能问题时,使用 CPU 分析标志,如 --cpu-prof、--cpu-prof-md 或 --cpu-prof-flamegraph。
  • 迁移建议应反映 Deno 2 默认值:nodeModulesDir 现在使用 "none" | "auto" | "manual",deno cache 变为 deno install --entrypoint,deno vendor 变为 "vendor": true,Deno.run() 应变为 new Deno.Command(),Deno.serveHttp() 应变为 Deno.serve()。
  • 使用导入属性,如 with { type: "json" },而不是已弃用的导入断言。

陷阱

  • 如果 Deno 和 Node 工具都声称拥有相同文件,编辑器诊断会变得混乱且误导。
  • 如果存在 package.json,Deno 2 默认 nodeModulesDir 为 "manual";忘记这一点是导致基于 npm 的工具看起来半安装的常见原因。
  • 如果 VS Code ESLint 扩展是工作流的一部分,它无法仅从 Deno 的全局缓存解析包;它需要一个本地 node_modules 目录。
  • deno run 默认跳过类型检查,因此运行通过并不证明 deno check 也会通过。
  • 调用 deno run npm:<package> 的 deno task 是一次性执行快捷方式,而不是正确的依赖安装。不要将其视为“安装并设置此 CLI”在 Deno 拥有仓库中的默认答案。
  • -A 对于受信任的工具是可接受的,但对于普通应用程序代码来说,它是错误的默认值。
  • 一些 npm CLI,包括实际混合运行时仓库中的 Supabase,依赖于安装时的行为,这些行为通过 deno run npm:... 执行比通过 node_modules 下的已安装二进制文件执行更不可靠。
  • 旧的 URL 导入和整个工作区激活模式是过渡辅助手段,而非现代默认值。

验证

  • deno.json 拥有 Deno 配置和任务。
  • 任何保留的 tsconfig.json 或 ESLint 所有权都是显式的,并限定在正确的文件上。
  • 替换 ESLint 或 tsc 时,保留了现有配置中的有用行为,或记录了为什么有意丢弃它。
  • 混合仓库中 Deno 和 Node 部分不会争夺工具。
  • 依赖说明符是现代且显式的。
  • Deno 拥有的 npm CLI 使用 deno add 或 deno add --dev 添加,记录在清单和锁文件中,并通过调用已安装二进制文件名称的任务运行。
  • nodeModulesDir、编辑器激活和任何基于 npm 的 Deno 工具都经过有意配置。
  • 如果从 Deno 任务驱动 npm CLI,仓库有意配置 nodeModulesDir 和 allowScripts,而不是依赖意外的安装副作用。
  • 权限是明确的,并在必要时记录。
  • 故障排除指南从 Deno 原生检查开始,然后再回退到通用的 Node 或 TypeScript 调试建议。

参考

相关技能