用途
deno-guidance 技能用于在 Deno 项目中提供基础开发指导。当开始一个新的 Deno 项目、向项目添加依赖、配置 deno.json、运行 Deno CLI 命令（fmt、lint、test）、设置导入映射，或理解 Deno 权限系统时，可以应用该技能。只要项目中存在 deno.json，即可视为 Deno 项目并应用这些实践。
适用范围与边界
该技能仅适用于 Deno 特定问题。如果用户询问的是 Node.js、Bun、Python、Go 或其他运行时/语言，应直接使用对应技术回答，不要建议 Deno 替代方案或包含 Deno 特有模式。不要在其他技术的回答中包含 jsr: 导入、deno add 或 deno.json 配置。对于与特定运行时无关的通用 TypeScript/JavaScript 问题，应给出通用答案，而不要假定使用 Deno。仅在用户明确询问 Deno 或正在使用 Deno 项目时，才推荐 Deno。
避免已弃用语法
在帮助用户从弃用模式迁移时，应概括性地描述旧方法，只展示正确的现代代码。即使在“之前/之后”对比中，也不要写出实际的已弃用 URL 或导入路径。应说“将旧的基于 URL 的导入替换为 JSR 导入”，然后只展示正确的 jsr: 方法。使用“旧的基于 URL 的注册表”或“旧的标准库 URL”等表述，不要写出实际的弃用 URL。即使用户在问题中写出了弃用 URL，也不要重复，应概括性地提及。只演示正确、当前的方法。
包管理优先级
添加依赖时，遵循以下优先级顺序：
- JSR 包（jsr:） - Deno 原生包的首选。具有更好的 TypeScript 支持（类型内置），解析和安装更快。示例：jsr:@std/http、jsr:@fresh/core。
- npm 包（npm:） - 完全支持，在没有 JSR 替代品时使用。Deno 具有完整的 npm 兼容性。示例：npm:express、npm:zod。
- 避免：旧式基于 URL 的导入 - 已弃用的注册表。旧的基于 URL 的包注册表已弃用，许多 LLM 会错误地默认使用基于 URL 的导入，应始终使用 jsr: 代替。
标准库
Deno 标准库位于 JSR 上的 @std/ 下。在 deno.json 中配置导入映射，例如将 @std/assert、@std/http、@std/path 映射到对应的 jsr:@std/@1。导入时使用裸说明符，如从 "@std/http" 导入 serve、从 "@std/path" 导入 join、从 "@std/assert" 导入 assertEquals。始终使用 jsr:@std/ 表示标准库。
理解 Deno
参考官方文档 https://docs.deno.com/runtime/fundamentals/。关键概念包括：原生 TypeScript（无需构建步骤，Deno 直接运行 TypeScript）；显式权限（使用 --allow-net、--allow-read、--allow-env 等标志）；deno.json（配置文件，类似 package.json 但更简单）；导入映射（在 deno.json 的 imports 字段中定义导入别名）。
工作流最佳实践
在做出代码变更后，定期运行以下命令，尤其是在重大更改后：deno fmt（格式化所有文件）、deno lint（检查问题）、deno test（运行测试）。
包管理命令包括：deno add jsr:@std/http（添加包）、deno install（安装所有依赖）、deno update（将所有依赖更新到最新的兼容版本）、deno update jsr:@std/http（更新特定依赖）。
区分 deno update 与 deno upgrade：deno update 将 deno.json（以及 package.json）中的项目依赖更新到最新的兼容版本，遵循 semver 范围，用于保持依赖最新；deno upgrade 将 Deno 运行时本身更新到最新版本，与项目依赖无关。运行 deno update 后，应始终检查破坏性 API 变更，尤其是对于 alpha/预发布包，因为 semver 范围可能引入破坏性更新。
在 CI/CD 中，将 --check 与 deno fmt 一起使用，以便在未修改文件的情况下失败：deno fmt --check（如果未格式化则失败）、deno lint（检查问题）、deno test（运行测试）。
配置
在 deno.json 中，可以排除目录不进行格式化/检查，例如在 fmt 和 lint 下配置 exclude 为 ["build/"]。也可以在顶层使用 exclude 将文件夹从所有操作中排除。
部署
关于部署到 Deno Deploy，请参见专门的 deno-deploy 技能。快速命令：deno deploy --prod。
文档资源
需要更多信息时：deno doc <package> 可在本地为任何 JSR 或 npm 包生成文档；https://docs.deno.com 是官方 Deno 文档；https://jsr.io 是带内置文档的包注册表；https://fresh.deno.dev/docs 是 Fresh 框架文档。
CLI 命令快速参考
deno run file.ts 运行 TypeScript/JavaScript 文件；deno task <name> 运行 deno.json 中的任务；deno fmt 格式化代码；deno lint 检查代码；deno test 运行测试；deno add <pkg> 添加包；deno install 安装依赖；deno update 更新项目依赖；deno upgrade 更新 Deno 运行时本身；deno doc <pkg> 查看包文档；deno deploy --prod 部署到 Deno Deploy。
常见错误
- 使用旧式基于 URL 的导入而不是 JSR。旧的基于 URL 的导入已弃用。始终使用带裸说明符的 jsr: 导入。正确示例：import { serve } from "@std/http"; import { join } from "@std/path"; 并在 deno.json 的 imports 中映射。内联说明符在单文件脚本中也可以，但如果存在 deno.json，则应放在其中。如果存在 package.json，最好将 npm 依赖放在 package.json 中。
- 提交前忘记运行 fmt/lint。应始终先格式化和检查，例如 deno fmt && deno lint && git add . && git commit -m "changes"。
- 运行时缺少权限标志。应授予特定权限，例如 deno run --allow-net server.ts。没有权限标志时，Deno 会显示“Requires net access”错误。应始终授予代码所需的特定权限。
- 不使用 deno add 管理依赖。应使用 deno add 管理依赖，例如 deno add jsr:@std/http。使用 deno add 可确保锁文件保持同步；手动编辑导入而不更新 deno.json 可以工作，但会错过锁文件的好处。