Community寫作與編輯github.com

swiftpostlabs/agentic-tools

可共享的 AI 智能體技能與工具

agentic-tools 是什麼?

此技能為一個全面的 Deno 開發指南,旨在為開發者與 AI 智能體提供標準化的現代 Deno 專案設定與工作流程。其核心價值在於解決 Deno 與 Node.js 生態系共存的常見痛點,提供從 tsconfig.json、ESLint 到許可權管理的明確遷移路徑與最佳實踐。此技能支援 Deno 專案、混合倉儲及任何正在採用 Deno 的 TypeScript 或 Node.js 程式庫。透過詳細的任務框架、核心規則與注意事項,它引導使用者建立清晰的工具鏈所有權邊界、正確使用 `deno.json` 進行配置、並採用最小權限原則來強化安全性。此技能適合需要整合或遷移至 Deno 的開發團隊,幫助他們避免常見的配置衝突與工具鏈混亂。

相容平台~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。
  • 僅保留 tsconfig.json 給 Node 擁有的路徑,或用於 Deno 工作區和目錄範圍無法乾淨表達的 TypeScript 專案圖情況。
  • 記住現代 Node 也已透過內建的類型剝離直接執行 TypeScript;選擇 Deno 是基於其執行環境、權限、依賴和工具鏈模型,而不僅僅是為了避免使用 tsc 或 ts-node。
  • 對於 Deno 擁有的檔案,優先使用 deno lint 和 deno fmt;僅當儲存庫或編輯器確實需要 ESLint 生態系時才添加 ESLint。
  • 當用 deno lint 取代 ESLint 時,檢查並保留現有 ESLint 的意圖,將其轉移到 deno.json 的 includes、excludes、lint 規則或記錄的例外中,而不是完全拋棄配置。
  • 當用 deno check 取代 tsc 時,檢查現有的 tsconfig.json 並將相關的編譯器選項、includes、excludes、libs 和嚴格性期望轉移到 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、函式庫、include 和 exclude 決策,或記錄為何它們不再適用。
  • 在 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 擁有的資料夾、TS 專案引用或 include/exclude 的粒度仍然需要時,才保留 tsconfig.json。

Linting、格式化與 ESLint

  • 對於 Deno 擁有的程式碼,使用 deno lint 和 deno.json 中的 lint 部分作為預設的 linting 擁有者。
  • 對於 Deno 擁有的程式碼,使用 deno fmt 和 deno.json 中的 fmt 部分作為預設的格式化工具。
  • 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 是一次性的執行捷徑,並非正確的依賴安裝。不要將其作為在 Deno 擁有的儲存庫中「安裝並設定此 CLI」的預設答案。
  • 對於受信任的工具,-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 工具鏈都已正確配置。
  • 如果 npm CLI 是從 Deno 任務驅動的,儲存庫會特意配置 nodeModulesDir 和 allowScripts,而不是依賴於偶然的安裝副作用。
  • 權限是意圖明確的,並在重要之處有文件記錄。
  • 排錯指導從 Deno 原生檢查開始,然後才回退到通用的 Node 或 TypeScript 除錯建議。

參考資料

…

[為翻譯而截斷]

相關技能