devvit-docs

Devvit 文档

从 reddit/devvit-docs 查阅 Devvit 文档。

限制：

• 只能以 reddit/devvit-docs 为准。
• 不要使用其他仓库、分支、博客文章或网页搜索结果。
• 如果找不到答案，请说明这一点，并引用最相关的文件。

工作原理

1. 运行 ensure-docs.cjs 脚本，克隆或刷新项目本地的文档缓存。
2. 让脚本维护稀疏本地克隆，其中包含已跟踪的 Markdown 和 MDX 文档。脚本会在每次运行时验证检出状态。
3. 读取 JSON 输出，获取文档目录路径。
4. 按顺序在每个 searchRoots 目录中搜索 Markdown 和 MDX 文件；如果可用，使用 rg，否则使用其他递归文本搜索工具。搜索确切的 API 名称和相关关键词，然后打开最匹配的文件并阅读其相关段落。
5. 不要搜索或引用 excludeRoots 中任何路径下的文件。
6. 如果首次搜索没有结果，且 cacheStatus 为 cached，请使用 --force 重新运行脚本一次，然后再次搜索。
7. 如果配置的搜索根目录不完整，可将 repoDir 作为备用搜索范围，同时继续排除 excludeRoots。
8. 引用相对于 repoDir 的具体文件和章节。

用法

node ./scripts/ensure-docs.cjs [--force] [--ttl <hours>] [--project-dir <path>] [--cache-dir <path>]

脚本路径相对于此技能目录。

• --force — 无论缓存时效如何都执行拉取
• --ttl <hours> — 缓存有效期（小时，默认值：24）
• --project-dir <path> — 用户的项目根目录，用于检测版本（默认值：cwd）
• --cache-dir <path> — 缓存基础目录。克隆内容存放在 <path>/devvit-docs 中（默认值：<project-dir>/node_modules/.cache/devvit-skills）

示例：

node ./scripts/ensure-docs.cjs
node ./scripts/ensure-docs.cjs --force
node ./scripts/ensure-docs.cjs --cache-dir ./tmp/devvit-cache

输出

{
  "cacheStatus": "cached",
  "docsRoot": "/path/to/project/node_modules/.cache/devvit-skills/devvit-docs/versioned_docs/version-0.11",
  "repoDir": "/path/to/project/node_modules/.cache/devvit-skills/devvit-docs",
  "searchRoots": [
    "/path/to/project/node_modules/.cache/devvit-skills/devvit-docs/versioned_docs/version-0.11",
    "/path/to/project/node_modules/.cache/devvit-skills/devvit-docs/docs/api/redditapi"
  ],
  "excludeRoots": [
    "/path/to/project/node_modules/.cache/devvit-skills/devvit-docs/docs/api/public-api"
  ],
  "matchedVersion": true,
  "appDevvitVersion": "0.11",
  "docsRepoCommit": "3f4f2d1c0b0e..."
}

• cacheStatus — 如果本次运行创建或替换了克隆，则为 cloned；否则为 cached。
• docsRoot — 主要文档目录。如果找到匹配版本，则为版本化目录；否则为 docs/。
• repoDir — 克隆仓库的根目录（如果版本化文档不完整，可将其用作备用目录）。
• searchRoots — 按顺序搜索的目录。包括 docsRoot，以及存在时最新的 docs/api/redditapi 参考文档。
• excludeRoots — 搜索和引用时要排除的目录。存在时包括 docs/api/public-api。
• matchedVersion — docsRoot 是否与检测到的应用版本匹配。
• appDevvitVersion — 用户 package.json 中的 Devvit 版本；如果没有则为 null。
• docsRepoCommit — 文档仓库缓存的提交哈希；如果不可用则为 null。

向用户呈现结果

• 引用支持每项结论的具体文档文件和章节。
• 如果文档中包含代码示例，请提供一个精简的示例。
• 如果文档未涵盖相关内容，请说明这一点，并建议查阅找到的最接近的材料。

故障排除

• 未找到 git — 需要将 git 添加到 PATH。
• 稀疏检出错误 — 需要使用支持 sparse-checkout 和部分克隆的较新版本 Git。
• 网络错误 — 刷新失败时，脚本会使用现有缓存。
• 文档过时 — 使用 --force 绕过 TTL 缓存。