Translated ['', 'AGENTS.md'] to zh

AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md
+
+面向在此仓库中工作的未来 agents 的指导。
+
+## Repository Context
+
+这是 HackTricks Cloud mdBook 仓库。相关的主书位于：
+
+`/Users/carlospolop/git/hacktricks`
+
+对共享 theme/search 行为的更改，通常需要在两个仓库中都应用。
+
+## Search Index Loading Contract
+
+自定义 search UI 位于：
+
+`theme/ht_searcher.js`
+
+也可能有一个生成的副本位于：
+
+`book/theme/ht_searcher.js`
+
+如果 production 正在部署已经构建好的 `book/` 目录，请更新这两个副本，或者在部署前重新构建 book。
+
+search index 的加载顺序很重要，而且对成本敏感：
+
+1. 先从 GitHub 仓库加载所有按语言区分的和 fallback 的 search index：
+`HackTricks-wiki/hacktricks-searchindex`
+2. 只有当所有 GitHub 托管的候选项都失败后，才回退到同源的 mdBook 输出。
+
+不要把本地的 `/searchindex.js` fallback 放在任何 GitHub 托管的 fallback 之前，例如
+`searchindex-cloud-en.js.gz`。在 production 中从 `cloud.hacktricks.wiki` 提供 `searchindex.js` 代价很高。
+
+对于这个仓库，预期的本地 fallback 是：
+
+`/searchindex.js`
+
+主书的 fallback 是：
+
+`/searchindex-book.js`
+
+该文件只是 fallback。主要来源必须仍然是远程
+`searchindex-<lang>.js.gz` 和 `searchindex-cloud-<lang>.js.gz` 文件，位于
+`HackTricks-wiki/hacktricks-searchindex`。
+
+## Search Index Publishing
+
+发布加密压缩 search index 到 `HackTricks-wiki/hacktricks-searchindex` 的 workflows 是：
+
+- `.github/workflows/build_master.yml`
+- `.github/workflows/translate_all.yml`
+
+生成的源文件是 `book/searchindex.js`。发布到远程的 artifact 名称是：
+
+- `searchindex-cloud-en.js.gz`
+- `searchindex-cloud-<lang>.js.gz`
+
+浏览器 loader 期望远程 `.js.gz` 文件是使用 `theme/ht_searcher.js` 中定义的 key 的 XOR-encrypted gzip payloads。
+
+## Build And Validation
+
+常见的本地检查：
+
+- `node --check theme/ht_searcher.js`
+- `mdbook build`
+
+如果 `mdbook build` 失败，检查：
+
+- `hacktricks-preprocessor-error.log`
+- `hacktricks-preprocessor.log`
+
+## Editing Notes
+
+- 搜索时优先使用 `rg`。
+- 除非明确要求，不要把生成的 `book/` 输出提交到 commits 中。Search loader 修复是一个例外，因为如果已经构建好的 pages 必须立即修正。
+- 如果修改共享 theme 行为，请对比并更新 `/Users/carlospolop/git/hacktricks` 中的匹配文件。
+- 不要回滚无关的本地更改。