diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 519a3e4d..bf31c0ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # 贡献指南 / Contributing Guide -> EN summary: file path = doc ID = published URL, no `id:`/`sidebar_position:` frontmatter, no number-prefixed filenames, `title:` is the only page-title source (no body `# H1`), images live in a sibling `.assets/` folder, and every `docs/**/*.md` needs an `i18n/en/docusaurus-plugin-content-docs/current/**/*.md` mirror. Run `pnpm run check` before opening a PR — it enforces all of this. See [REFACTOR_PROPOSAL.md](./REFACTOR_PROPOSAL.md) for the full rationale. +> EN summary: file path = doc ID = published URL, no `id:`/`sidebar_position:` frontmatter, no number-prefixed filenames, `title:` is the only page-title source (no body `# H1`), images live in a sibling `.assets/` folder, and every `docs/**/*.md` needs a mirror in each locale docs tree unless an explicit single-source fallback is configured. Run `pnpm run check` before opening a PR — it enforces all of this. See [REFACTOR_PROPOSAL.md](./REFACTOR_PROPOSAL.md) for the full rationale. 本文档记录本仓库的文档结构约定，帮助人类贡献者和 AI Agent 在不读遍全部历史讨论的情况下，正确地新增/修改文档。 @@ -23,13 +23,13 @@ 2. frontmatter 只写 `title:`（必需）和可选的 `sidebar_label:`；不要写 `id:` 或 `sidebar_position:`。 3. 正文**不要**再写一个 `# 标题` 作为 H1——`title:` 会自动渲染为页面标题。 4. 在 `sidebars.js` 对应的数组里加一行 `"section/xxx"`（除非这是一个故意不出现在侧边栏的隐藏页面，如 `use/install_comple`）。 -5. 在 `i18n/en/docusaurus-plugin-content-docs/current/
/xxx.md` 创建英文镜像，路径和文件名必须完全一致。 +5. 在 `i18n//docusaurus-plugin-content-docs/current/
/xxx.md` 为各非默认 locale 创建镜像，路径和文件名必须完全一致；`scripts/check-config.json` 中声明的单一来源 fallback 路径除外。 6. 图片放在 `docs/
/xxx.assets/` 下，用 `./xxx.assets/foo.png` 引用；纯 UI 截图等语言无关的图片，英文版可以用 `@site/docs/
/xxx.assets/foo.png` 直接复用中文版的图片，不必重复存一份二进制文件。 -7. 跑一次 `pnpm run build && pnpm run check`，确认三项检查全部通过。 +7. 跑一次 `pnpm run build && pnpm run check`，确认全部检查通过。 ## 新增一条更新日志 -`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。 +`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。更新中文源文时仍需同步英文版本；俄语路由由 Docusaurus 直接回退到英文文档树，不要在 `i18n/ru/.../change/` 中恢复一份会漂移的副本。 ## 加载不变的 URL（改动前必须确认不受影响） @@ -43,22 +43,24 @@ ## 翻译对照表 -| 中文 | English | -|---|---| -| 脚本猫 | ScriptCat | -| 用户脚本 | user script | -| 后台脚本 | background script | -| 定时脚本 | scheduled script | -| 油猴 | Tampermonkey | +| 中文 | English | Русский | +|---|---|---| +| 脚本猫 | ScriptCat | ScriptCat | +| 用户脚本 | user script | пользовательский скрипт | +| 后台脚本 | background script | фоновый скрипт | +| 定时脚本 | scheduled script | скрипт по расписанию | +| 定时任务 | scheduled task | задача по расписанию | +| 油猴 | Tampermonkey | Tampermonkey | 英文标题结构应尽量与中文一一对应（标题层级、顺序一致），这样跨语言的锚点链接更容易对齐；注意 Docusaurus 生成的锚点是基于**渲染后的英文标题文本**，不是中文锚点的直接翻译（例如 `## Scheduled Script (\`@crontab\`)` 生成的锚点是 `#scheduled-script-crontab`，需要用构建产物核实，不要凭感觉猜。 ## 本地检查命令 ```bash -pnpm run build # 构建两个语言版本，onBrokenLinks/onBrokenAnchors 设置为 throw -pnpm run check # 依次跑 url 一致性 / i18n 覆盖率 / frontmatter 规范三项检查 +pnpm run build # 构建 zh-Hans/en/ru，onBrokenLinks/onBrokenAnchors 设置为 throw +pnpm run check # 依次跑 URL / fallback 产物 / i18n 覆盖率 / frontmatter 检查 pnpm run check:urls # 单独跑 URL 不变契约检查 -pnpm run check:i18n # 单独跑中英文档配对检查 +pnpm run check:fallbacks # 单独检查 production build 中的 locale 单一来源 fallback +pnpm run check:i18n # 单独跑所有 locale 的文档配对及 fallback 例外检查 pnpm run check:frontmatter # 单独跑 title/id/sidebar_position/H1 规范检查 ``` diff --git a/docusaurus.config.js b/docusaurus.config.js index e1fa33ff..373d037c 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -3,6 +3,35 @@ import { themes as prismThemes } from "prism-react-renderer"; +const { defaultLocale, i18nDocFallbacks = {} } = require("./scripts/check-config.json"); +const currentLocale = process.env.DOCUSAURUS_CURRENT_LOCALE ?? defaultLocale; +const docsFallbackLocale = i18nDocFallbacks[currentLocale]?.sourceLocale; +const docsPath = docsFallbackLocale + ? `i18n/${docsFallbackLocale}/docusaurus-plugin-content-docs/current` + : "docs"; + +const metadataByLocale = { + "zh-Hans": { + keywords: + "scriptcat,userscript,browser extension,浏览器扩展,用户脚本,后台脚本,脚本猫,tampermonkey,violentmonkey,greasemonkey,javascript,自动化脚本,网页增强", + description: + "ScriptCat 是一个可以执行自定义脚本的浏览器扩展，支持用户脚本、后台脚本等多种脚本类型。提供强大的脚本管理、同步、订阅等功能。", + }, + en: { + keywords: + "scriptcat,userscript,browser extension,user scripts,background scripts,scheduled scripts,userscript manager,tampermonkey,violentmonkey,greasemonkey,javascript,browser automation", + description: + "ScriptCat is an open-source browser extension for user scripts, background scripts, and scheduled scripts, with powerful management, sync, and subscription features.", + }, + ru: { + keywords: + "scriptcat,userscript,расширение браузера,пользовательские скрипты,фоновые скрипты,скрипты по расписанию,менеджер пользовательских скриптов,tampermonkey,violentmonkey,greasemonkey,javascript,автоматизация браузера", + description: + "ScriptCat — открытое расширение браузера для пользовательских, фоновых скриптов и скриптов по расписанию с удобным управлением, синхронизацией и подписками.", + }, +}; +const metadata = metadataByLocale[currentLocale] ?? metadataByLocale[defaultLocale]; + /** @type {import('@docusaurus/types').Config} */ const config = { title: "ScriptCat", @@ -47,8 +76,8 @@ const config = { // metadata like html lang. For example, if your site is Chinese, you may want // to replace "en" with "zh-Hans". i18n: { - defaultLocale: "zh-Hans", - locales: ["zh-Hans", "en"], + defaultLocale, + locales: ["zh-Hans", "en", "ru"], localeConfigs: { "zh-Hans": { label: "简体中文", @@ -60,6 +89,11 @@ const config = { direction: "ltr", htmlLang: "en", }, + ru: { + label: "Русский", + direction: "ltr", + htmlLang: "ru", + }, }, }, @@ -69,6 +103,11 @@ const config = { /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { + // Docusaurus normally falls back to the default (Chinese) docs tree. + // For configured locales, use another locale as the base tree while + // still letting localized files override it. check:i18n restricts + // which paths may rely on this fallback. + path: docsPath, sidebarPath: require.resolve("./sidebars.js"), // Please change this to your repo. // Remove this to remove the "edit this page" links. @@ -100,13 +139,11 @@ const config = { metadata: [ { name: "keywords", - content: - "scriptcat,userscript,browser extension,浏览器扩展,用户脚本,后台脚本,脚本猫,tampermonkey,violentmonkey,greasemonkey,javascript,自动化脚本,网页增强", + content: metadata.keywords, }, { name: "description", - content: - "ScriptCat 是一个可以执行自定义脚本的浏览器扩展，支持用户脚本、后台脚本等多种脚本类型。提供强大的脚本管理、同步、订阅等功能。", + content: metadata.description, }, ], navbar: { diff --git a/i18n/en/code.json b/i18n/en/code.json index e4ddca0b..5e632239 100644 --- a/i18n/en/code.json +++ b/i18n/en/code.json @@ -27,6 +27,10 @@ "message": "Find these updates useful? Star us on GitHub to support our work", "description": "GitHub star bar subtitle on changelog page" }, + "homepage.meta.keywords": { + "message": "ScriptCat,user scripts,browser extension,userscript,Tampermonkey,Violentmonkey,background scripts,scheduled scripts,browser automation,ad blocker,script store", + "description": "Homepage SEO keywords" + }, "homepage.meta.title": { "message": "ScriptCat - Powerful Browser Script Engine", "description": "Homepage meta title for SEO" diff --git a/i18n/en/docusaurus-plugin-content-docs/current/change/index.md b/i18n/en/docusaurus-plugin-content-docs/current/change/index.md index ce3ef839..f0e5196d 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/change/index.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/change/index.md @@ -12,7 +12,7 @@ import SponsorBlock from '@site/src/components/SponsorBlock/en.mdx'; For Beta version changelog, please see [Beta Changelog](./beta-changelog.md) -⚠️ Please note that if you are using Windows 8/7/XP, or your browser kernel version is lower than 120, you need to manually install the [legacy version of ScriptCat](https://github.com/scriptscat/scriptcat/releases). v0.16.x is the last version that supports Manifest V2. Installation steps can be found at: [Install Extension by Loading Unpacked](/docs/use/use/#load-unpacked-extension-installation). +⚠️ Please note that if you are using Windows 8/7/XP, or your browser kernel version is lower than 120, you need to manually install the [legacy version of ScriptCat](https://github.com/scriptscat/scriptcat/releases). v0.16.x is the last version that supports Manifest V2. Installation steps can be found at: [Install Extension by Loading Unpacked](/use/use.md#load-unpacked-extension-installation). diff --git a/i18n/ru/code.json b/i18n/ru/code.json new file mode 100644 index 00000000..a1903949 --- /dev/null +++ b/i18n/ru/code.json @@ -0,0 +1,931 @@ +{ + "githubStar.button.label": { + "message": "Star", + "description": "GitHub star button label" + }, + "githubStar.home.title": { + "message": "ScriptCat — бесплатный и с открытым исходным кодом", + "description": "GitHub star bar title on homepage" + }, + "githubStar.home.subtitle": { + "message": "Поставьте Star, если проект полезен — это нас мотивирует", + "description": "GitHub star bar subtitle on homepage" + }, + "githubStar.install.title": { + "message": "Нравится ScriptCat?", + "description": "GitHub star bar title on install-complete page" + }, + "githubStar.install.subtitle": { + "message": "Поставьте Star на GitHub — так больше людей узнают о проекте 🌟", + "description": "GitHub star bar subtitle on install-complete page" + }, + "githubStar.changelog.title": { + "message": "ScriptCat становится всё лучше 🚀", + "description": "GitHub star bar title on changelog page" + }, + "githubStar.changelog.subtitle": { + "message": "Обновления полезны? Поддержите нас Star на GitHub", + "description": "GitHub star bar subtitle on changelog page" + }, + "homepage.meta.keywords": { + "message": "ScriptCat,пользовательские скрипты,расширение браузера,userscript,Tampermonkey,Violentmonkey,фоновые скрипты,скрипты по расписанию,автоматизация браузера,блокировка рекламы,магазин скриптов", + "description": "Homepage SEO keywords" + }, + "homepage.meta.title": { + "message": "ScriptCat — мощный движок пользовательских скриптов", + "description": "Homepage meta title for SEO" + }, + "homepage.meta.description": { + "message": "ScriptCat — мощный открытый движок браузерных скриптов: настраивайте веб-страницы, блокируйте рекламу, автоматизируйте задачи и улучшайте просмотр. Совместим с Tampermonkey и предлагает больше возможностей.", + "description": "Homepage meta description for SEO" + }, + "homepage.og.title": { + "message": "ScriptCat — мощный движок браузерных скриптов", + "description": "Open Graph title for social sharing" + }, + "homepage.og.description": { + "message": "Открытый движок браузерных скриптов, который расширяет возможности браузера. Пользовательские и фоновые скрипты, совместимость с Tampermonkey, расширенный функционал.", + "description": "Open Graph description for social sharing" + }, + "homepage.twitter.title": { + "message": "ScriptCat — мощный движок браузерных скриптов", + "description": "Twitter card title" + }, + "homepage.twitter.description": { + "message": "Открытый движок браузерных скриптов, который делает больше", + "description": "Twitter card description" + }, + "homepage.hero.title": { + "message": "Лучший движок скриптов для", + "description": "Main title on the homepage hero section" + }, + "homepage.hero.title.engine": { + "message": "улучшенного браузера", + "description": "Gradient text in main title" + }, + "homepage.hero.subtitle.userScript": { + "message": "пользовательских скриптов", + "description": "User script highlight" + }, + "homepage.hero.subtitle.possibilities": { + "message": ", открывая безграничные возможности браузера!", + "description": "Browser possibilities text" + }, + "homepage.hero.subtitle.main": { + "message": "ScriptCat — мощный открытый движок браузерных скриптов: легко настраивайте сайты, убирайте рекламу, автоматизируйте задачи и улучшайте веб-серфинг. Совместим с Tampermonkey и даёт дополнительные возможности и оптимизации.", + "description": "Main subtitle description on homepage" + }, + "homepage.hero.subtitle.highlight": { + "message": "Расширение браузера для выполнения", + "description": "Highlighted subtitle on homepage" + }, + "homepage.hero.button.browseScripts": { + "message": "Смотреть библиотеку скриптов", + "description": "Button text for browsing scripts" + }, + "homepage.hero.browser.edge": { + "message": "Добавить в Edge", + "description": "Button text for Edge browser" + }, + "homepage.hero.browser.chrome": { + "message": "Добавить в Chrome", + "description": "Button text for Chrome browser" + }, + "homepage.hero.browser.firefox": { + "message": "Добавить в Firefox", + "description": "Button text for Firefox browser" + }, + "homepage.hero.browser.default": { + "message": "Установить расширение", + "description": "Default button text for browser installation" + }, + "homepage.hero.browser.crx": { + "message": "Скачать пакет для ручной установки", + "description": "Button text for manual installation" + }, + "homepage.hero.trustBadges.title": { + "message": "Доверие и поддержка технического сообщества", + "description": "Trust badges section title" + }, + "homepage.features.title.powerful": { + "message": "Мощные возможности, ", + "description": "Features section title part 1" + }, + "homepage.features.title.possibilities": { + "message": "безграничный потенциал", + "description": "Features section title highlight" + }, + "homepage.features.subtitle": { + "message": "ScriptCat предлагает набор мощных функций, чтобы легко расширять возможности браузера и создавать свой веб-опыт.", + "description": "Features section subtitle" + }, + "homepage.features.tampermonkey.title": { + "message": "Совместимость с Tampermonkey", + "description": "Feature title: Tampermonkey compatibility" + }, + "homepage.features.tampermonkey.description": { + "message": "Полная совместимость с форматом скриптов Tampermonkey: бесшовная миграция существующей библиотеки без затрат на переход.", + "description": "Feature description: Tampermonkey compatibility" + }, + "homepage.features.background.title": { + "message": "Фоновые скрипты", + "description": "Feature title: Background scripts" + }, + "homepage.features.background.description": { + "message": "В отличие от обычных пользовательских скриптов, позволяют работать в фоне без открытых вкладок.", + "description": "Feature description: Background scripts" + }, + "homepage.features.security.title": { + "message": "Безопасность и надёжность", + "description": "Feature title: Security" + }, + "homepage.features.security.description": { + "message": "Строгий контроль разрешений, прозрачное поведение скриптов — защита от вредоносного кода и вашей конфиденциальности.", + "description": "Feature description: Security" + }, + "homepage.features.editor.title": { + "message": "Встроенный редактор кода", + "description": "Feature title: Code editor" + }, + "homepage.features.editor.description": { + "message": "Мощный редактор с подсветкой синтаксиса, автодополнением и подсказками об ошибках — писать скрипты удобнее.", + "description": "Feature description: Code editor" + }, + "homepage.features.api.title": { + "message": "Мощные API", + "description": "Feature title: APIs" + }, + "homepage.features.api.description": { + "message": "Богаче, чем GM: файловое хранилище, пользовательские настройки и другие расширенные возможности.", + "description": "Feature description: APIs" + }, + "homepage.features.store.title": { + "message": "Магазин скриптов", + "description": "Feature title: Script store" + }, + "homepage.features.store.description": { + "message": "Устанавливайте популярные скрипты в один клик или публикуйте свои работы для сообщества — живая экосистема.", + "description": "Feature description: Script store" + }, + "homepage.comparison.title.why": { + "message": "Почему выбирают", + "description": "Comparison section title part 1" + }, + "homepage.comparison.subtitle": { + "message": "По сравнению с другими движками скриптов ScriptCat даёт больше преимуществ и расширенных функций", + "description": "Comparison section subtitle" + }, + "homepage.comparison.feature": { + "message": "Функция", + "description": "Comparison table header: Feature" + }, + "homepage.comparison.feature.compatibility": { + "message": "Совместимость скриптов", + "description": "Comparison feature: Script compatibility" + }, + "homepage.comparison.feature.background": { + "message": "Фоновые скрипты", + "description": "Comparison feature: Background scripts" + }, + "homepage.comparison.feature.opensource": { + "message": "Бесплатный open source", + "description": "Comparison feature: Open source" + }, + "homepage.comparison.feature.mv3": { + "message": "Поддержка MV3", + "description": "Comparison feature: MV3 Support" + }, + "homepage.comparison.feature.sync": { + "message": "Облачная синхронизация", + "description": "Comparison feature: Cloud sync" + }, + "homepage.comparison.feature.api": { + "message": "Мощные API", + "description": "Comparison feature: Powerful APIs" + }, + "homepage.comparison.feature.community": { + "message": "Поддержка сообщества", + "description": "Comparison feature: Community support" + }, + "homepage.comparison.label.efficient": { + "message": "Эффективно", + "description": "Comparison label: Efficient" + }, + "homepage.comparison.label.multiplatform": { + "message": "Кроссплатформенно", + "description": "Comparison label: Multi-platform" + }, + "homepage.scenario.title.solve": { + "message": "Скрипты, которые решают ", + "description": "Scenario section title part 1" + }, + "homepage.scenario.title.problems": { + "message": "реальные задачи", + "description": "Scenario section title highlight" + }, + "homepage.scenario.title.scripts": { + "message": "", + "description": "Scenario section title part 2" + }, + "homepage.scenario.subtitle": { + "message": "Посмотрите, как ScriptCat меняет опыт веб-сёрфинга", + "description": "Scenario section subtitle" + }, + "homepage.scenario.video.title": { + "message": "Улучшение видеосайтов", + "description": "Video scenario title" + }, + "homepage.scenario.video.subtitle": { + "message": "Оптимизируйте просмотр видео", + "description": "Video scenario subtitle" + }, + "homepage.scenario.video.tag": { + "message": "Популярные сценарии", + "description": "Video scenario tag" + }, + "homepage.scenario.video.feature.speed": { + "message": "Управление скоростью видео", + "description": "Video feature: Speed control" + }, + "homepage.scenario.video.feature.download": { + "message": "Скачивание видео в один клик", + "description": "Video feature: Download" + }, + "homepage.scenario.video.feature.adblock": { + "message": "Автопропуск рекламы", + "description": "Video feature: Ad blocking" + }, + "homepage.scenario.video.feature.ui": { + "message": "Упрощение интерфейса", + "description": "Video feature: UI optimization" + }, + "homepage.scenario.video.sites": { + "message": "Поддерживаемые сайты", + "description": "Video scenario supported sites label" + }, + "homepage.scenario.video.getScript": { + "message": "Получить скрипт →", + "description": "Video scenario get script link" + }, + "homepage.scenario.shopping.title": { + "message": "Помощник покупок", + "description": "Shopping scenario title" + }, + "homepage.scenario.shopping.subtitle": { + "message": "Делает покупки проще", + "description": "Shopping scenario subtitle" + }, + "homepage.scenario.shopping.tag": { + "message": "Практичные инструменты", + "description": "Shopping scenario tag" + }, + "homepage.scenario.shopping.feature.history": { + "message": "История цен", + "description": "Shopping feature: Price history" + }, + "homepage.scenario.shopping.feature.coupon": { + "message": "Автопоиск купонов", + "description": "Shopping feature: Coupon search" + }, + "homepage.scenario.shopping.feature.compare": { + "message": "Сравнение цен", + "description": "Shopping feature: Price comparison" + }, + "homepage.scenario.shopping.feature.alert": { + "message": "Уведомления о снижении цены", + "description": "Shopping feature: Price alert" + }, + "homepage.scenario.sites.more": { + "message": "+Ещё", + "description": "More sites indicator in scenario cards" + }, + "homepage.download.title.ready": { + "message": "Готовы", + "description": "Download section title part 1" + }, + "homepage.download.title.enhance": { + "message": "улучшить просмотр в браузере", + "description": "Download section title highlight" + }, + "homepage.download.title.question": { + "message": "?", + "description": "Download section title part 2" + }, + "homepage.download.subtitle": { + "message": "Установите ScriptCat и откройте безграничные возможности веба", + "description": "Download section subtitle" + }, + "homepage.download.edge": { + "message": "Магазин расширений Edge", + "description": "Download button: Edge store" + }, + "homepage.download.chrome": { + "message": "Магазин расширений Chrome", + "description": "Download button: Chrome store" + }, + "homepage.download.firefox": { + "message": "Магазин расширений Firefox", + "description": "Download button: Firefox store" + }, + "homepage.download.github": { + "message": "Скачать с GitHub", + "description": "Download button: GitHub" + }, + "homepage.download.popup.title": { + "message": "ScriptCat включён", + "description": "Extension popup title" + }, + "homepage.download.popup.text": { + "message": "На этой странице работают 3 скрипта", + "description": "Extension popup text" + }, + "homepage.footer.contributors.title": { + "message": "Спасибо всем участникам", + "description": "Footer contributors section title" + }, + "footer.description": { + "message": "Мощный движок браузерных скриптов, который делает веб богаче и интереснее.", + "description": "Footer description" + }, + "footer.product.title": { + "message": "Продукт", + "description": "Footer product section title" + }, + "footer.product.features": { + "message": "Возможности", + "description": "Footer product features link" + }, + "footer.product.scriptStore": { + "message": "Магазин скриптов", + "description": "Footer product script store link" + }, + "footer.product.changelog": { + "message": "История изменений", + "description": "Footer product changelog link" + }, + "footer.resources.title": { + "message": "Ресурсы", + "description": "Footer resources section title" + }, + "footer.resources.devDocs": { + "message": "Документация разработчика", + "description": "Footer resources development docs link" + }, + "footer.resources.apiReference": { + "message": "Справочник API", + "description": "Footer resources API reference link" + }, + "footer.resources.examples": { + "message": "Примеры скриптов", + "description": "Footer resources example scripts link" + }, + "footer.resources.faq": { + "message": "FAQ", + "description": "Footer resources FAQ link" + }, + "footer.community.title": { + "message": "Сообщество", + "description": "Footer community section title" + }, + "footer.community.forum": { + "message": "Форум", + "description": "Footer community forum link" + }, + "footer.community.discord": { + "message": "Канал Discord", + "description": "Footer community Discord link" + }, + "footer.community.contributing": { + "message": "Как внести вклад", + "description": "Footer community contributing guide link" + }, + "footer.community.issues": { + "message": "Сообщить о проблеме", + "description": "Footer community report issues link" + }, + "footer.community.contact": { + "message": "Связаться с командой", + "description": "Footer community contact team link" + }, + "footer.copyright.allRightsReserved": { + "message": "Все права защищены.", + "description": "Footer copyright all rights reserved text" + }, + "footer.copyright.privacy": { + "message": "Политика конфиденциальности", + "description": "Footer copyright privacy policy link" + }, + "footer.copyright.terms": { + "message": "Условия использования", + "description": "Footer copyright terms of use link" + }, + "footer.copyright.license": { + "message": "Лицензионное соглашение", + "description": "Footer copyright license link" + }, + "uninstall.title": { + "message": "Опрос при удалении", + "description": "Title of the uninstall survey page" + }, + "uninstall.description": { + "message": "Спасибо, что пользовались ScriptCat. Расскажите, почему вы удаляете расширение.", + "description": "Description of the uninstall survey page" + }, + "uninstall.header.title": { + "message": "Жаль, что вы удаляете ScriptCat", + "description": "Main header title on uninstall survey page" + }, + "uninstall.header.subtitle": { + "message": "Если несложно, поделитесь мнением — это поможет нам становиться лучше", + "description": "Subtitle on uninstall survey page" + }, + "uninstall.question.reason": { + "message": "Какова основная причина удаления ScriptCat?", + "description": "Question about uninstall reason" + }, + "uninstall.question.feedback": { + "message": "Можете ли вы подробнее описать ситуацию?", + "description": "Question about detailed feedback" + }, + "uninstall.reason.bugs": { + "message": "Ошибки или сбои", + "description": "Uninstall reason: bugs" + }, + "uninstall.reason.no_need": { + "message": "ScriptCat больше не нужен", + "description": "Uninstall reason: no longer need" + }, + "uninstall.reason.features": { + "message": "Нет нужных мне функций", + "description": "Uninstall reason: missing features" + }, + "uninstall.reason.alternative": { + "message": "Нашёл(ла) лучшую альтернативу", + "description": "Uninstall reason: found alternative" + }, + "uninstall.reason.other": { + "message": "Другие причины", + "description": "Uninstall reason: other" + }, + "uninstall.feedback.placeholder": { + "message": "Опишите конкретные проблемы, предложения или другие мысли...", + "description": "Placeholder text for feedback textarea" + }, + "uninstall.button.submit": { + "message": "Отправить отзыв", + "description": "Submit button text" + }, + "uninstall.warning.selectReason": { + "message": "Выберите причину удаления", + "description": "Warning when no reason is selected" + }, + "uninstall.success.submitted": { + "message": "Спасибо за отзыв!", + "description": "Success message after submission" + }, + "uninstall.error.submit": { + "message": "Не удалось отправить, попробуйте позже", + "description": "Error message when submission fails" + }, + "uninstall.thanks.title": { + "message": "Спасибо за отзыв!", + "description": "Thank you page title" + }, + "uninstall.thanks.message": { + "message": "Ваше мнение очень важно и поможет улучшить ScriptCat.", + "description": "Thank you page message" + }, + "uninstall.thanks.backHome": { + "message": "На главную", + "description": "Back to home button" + }, + "uninstall.thanks.reportIssue": { + "message": "Сообщить о проблеме", + "description": "Report issue button" + }, + "uninstall.reinstall.message": { + "message": "Если передумаете, всегда можно установить снова:", + "description": "Reinstall message" + }, + "uninstall.thanks.considerReinstall": { + "message": "Если передумаете — мы всегда рады видеть вас снова", + "description": "Consider reinstall message" + }, + "uninstall.thanks.submitAnother": { + "message": "Отправить другой отзыв", + "description": "Submit another feedback button" + }, + "uninstall.sidebar.reinstall.title": { + "message": "Мы всегда рады видеть вас снова", + "description": "Sidebar reinstall title" + }, + "uninstall.sidebar.help.title": { + "message": "Нужна помощь?", + "description": "Sidebar help title" + }, + "uninstall.sidebar.help.description": { + "message": "Возникли трудности? Мы поможем разобраться", + "description": "Sidebar help description" + }, + "uninstall.sidebar.help.github": { + "message": "GitHub Issues", + "description": "GitHub issues button" + }, + "uninstall.sidebar.help.docs": { + "message": "Документация", + "description": "View docs button" + }, + "uninstall.bug.alert.title": { + "message": "Нашли ошибку?", + "description": "Bug alert title" + }, + "uninstall.bug.alert.description": { + "message": "Если вы столкнулись с ошибкой или сбоем, рекомендуем сразу создать issue на GitHub — так обратная связь и поддержка будут быстрее.", + "description": "Bug alert description" + }, + "uninstall.bug.alert.button": { + "message": "Сообщить о проблеме на GitHub", + "description": "Bug alert button text" + }, + "uninstall.feature.alert.title": { + "message": "Не хватает функции?", + "description": "Feature alert title" + }, + "uninstall.feature.alert.description": { + "message": "Мы ценим запросы на функции! Опишите желаемое подробно на GitHub — так мы лучше поймём потребности и приоритизируем реализацию.", + "description": "Feature alert description" + }, + "uninstall.feature.alert.button": { + "message": "Предложить функцию на GitHub", + "description": "Feature alert button text" + }, + "home.install.edge": { + "message": "Добавить в Edge" + }, + "home.install.chrome": { + "message": "Добавить в Chrome" + }, + "home.install.firefox": { + "message": "Добавить в Firefox" + }, + "home.install.manual": { + "message": "Скачать пакет и установить вручную" + }, + "home.install.guide": { + "message": "Инструкция по установке" + }, + "home.hero.installTo": { + "message": "Добавить в {browser}" + }, + "home.hero.moreBrowsers": { + "message": "Другие браузеры" + }, + "home.hero.eyebrow": { + "message": "Открытый движок userscript · совместим с Tampermonkey" + }, + "home.hero.title1": { + "message": "Дайте браузеру" + }, + "home.hero.title2": { + "message": "" + }, + "home.hero.title3": { + "message": "суперспособности" + }, + "home.hero.subhead": { + "message": "Блокируйте рекламу, улучшайте видео, автоматизируйте рутину — устанавливайте скрипты сообщества из магазина в один клик; для разработчиков — фоновые скрипты и мощные API. Совместим с Tampermonkey: существующие скрипты переносятся без затрат." + }, + "home.hero.browse": { + "message": "Смотреть скрипты" + }, + "home.hero.trust": { + "message": "Работает в Chrome · Edge · Firefox — полностью бесплатно и open source" + }, + "home.hero.mock.speed": { + "message": "Управление скоростью видео" + }, + "home.hero.mock.adblock": { + "message": "Автопропуск рекламы" + }, + "home.hero.mock.dark": { + "message": "Тёмная тема для страниц" + }, + "home.hero.mock.skip": { + "message": "Пропуск рекламы" + }, + "home.hero.mock.running": { + "message": "На этой странице работают 3 скрипта" + }, + "home.hero.mock.add": { + "message": "Добавить из магазина скриптов" + }, + "home.hero.chip.installed": { + "message": "Скрипт установлен" + }, + "home.hero.chip.installedSub": { + "message": "Video Enhancer v2.1" + }, + "home.hero.chip.background": { + "message": "3 скрипта работают в фоне" + }, + "home.trust.eyebrow": { + "message": "ДОВЕРИЕ ПОЛЬЗОВАТЕЛЕЙ И РАЗРАБОТЧИКОВ ПО ВСЕМУ МИРУ" + }, + "home.trust.users": { + "message": "Установок" + }, + "home.trust.scripts": { + "message": "Скриптов сообщества" + }, + "home.trust.stars": { + "message": "GitHub Stars" + }, + "home.trust.contributors": { + "message": "Участников" + }, + "home.sc.eyebrow": { + "message": "Для всех · Код не нужен" + }, + "home.sc.title1": { + "message": "Без кода — только " + }, + "home.sc.title2": { + "message": "один клик" + }, + "home.sc.title3": { + "message": ", чтобы решить повседневные раздражители" + }, + "home.sc.sub": { + "message": "Возьмите скрипт из магазина — реклама, видео, покупки, продуктивность: всё сделано за вас." + }, + "home.sc.featured.tag": { + "message": "Самое популярное" + }, + "home.sc.featured.t": { + "message": "Видео — полностью улучшено" + }, + "home.sc.featured.d": { + "message": "Скорость, автопропуск рекламы, скачивание в один клик, картинка в картинке — удобнее Bilibili / YouTube / Netflix." + }, + "home.sc.featured.c1": { + "message": "Скорость" + }, + "home.sc.featured.c2": { + "message": "Блокировка рекламы" + }, + "home.sc.featured.c3": { + "message": "Скачивание" + }, + "home.sc.featured.c4": { + "message": "Картинка в картинке" + }, + "home.sc.featured.btn": { + "message": "Видеоскрипты" + }, + "home.sc.featured.sites": { + "message": "Поддержка 20+ видеосайтов" + }, + "home.sc.adblock.t": { + "message": "Блокировка рекламы · Чистый веб" + }, + "home.sc.adblock.d": { + "message": "Блокируйте рекламу и всплывающие окна — страница остаётся чистой." + }, + "home.sc.adblock.l": { + "message": "Скрипты блокировки рекламы" + }, + "home.sc.shop.t": { + "message": "Покупки · Сравнение цен" + }, + "home.sc.shop.d": { + "message": "Сравнивайте цены, смотрите историю и применяйте купоны в один клик." + }, + "home.sc.shop.l": { + "message": "Помощник покупок" + }, + "home.sc.auto.t": { + "message": "Продуктивность · Автоматизация" + }, + "home.sc.auto.d": { + "message": "Авто-чек-ин, пакетные действия — удобный набор инструментов." + }, + "home.sc.auto.l": { + "message": "Скрипты продуктивности" + }, + "home.sc.read.t": { + "message": "Чтение · Перевод" + }, + "home.sc.read.d": { + "message": "Тёмная тема, перевод страниц, иммерсивное чтение." + }, + "home.sc.read.l": { + "message": "Улучшения чтения" + }, + "home.step.eyebrow": { + "message": "СТАРТ ЗА 3 ШАГА" + }, + "home.step.title1": { + "message": "30 секунд" + }, + "home.step.title2": { + "message": " до первого скрипта" + }, + "home.step.sub": { + "message": "Без сложной настройки — три простых шага: установили и пользуетесь." + }, + "home.step1.t": { + "message": "Установите расширение" + }, + "home.step1.d": { + "message": "Добавьте из магазина Chrome / Edge / Firefox в один клик или установите вручную." + }, + "home.step1.p": { + "message": "Добавить в браузер" + }, + "home.step2.t": { + "message": "Откройте магазин" + }, + "home.step2.d": { + "message": "Тысячи скриптов сообщества ScriptCat — выберите то, что нужно." + }, + "home.step2.p": { + "message": "Поиск: скорость видео" + }, + "home.step3.t": { + "message": "Установка в один клик" + }, + "home.step3.d": { + "message": "Нажмите «Установить» — скрипт сразу заработает на странице." + }, + "home.step3.p": { + "message": "Установлен · Уже активен" + }, + "home.feat.eyebrow": { + "message": "Ключевые возможности · ПОЧЕМУ SCRIPTCAT" + }, + "home.feat.title1": { + "message": "Мощное ядро, " + }, + "home.feat.title2": { + "message": "спокойствие" + }, + "home.feat.sub": { + "message": "От совместимости до безопасности, от обычных пользователей до разработчиков — ScriptCat закрывает потребности." + }, + "home.feat.compat.t": { + "message": "Совместимость с Tampermonkey" + }, + "home.feat.compat.d": { + "message": "Полная совместимость с форматом userscript и GM API — миграция существующих скриптов без изменений и без затрат на переход." + }, + "home.feat.compat.b": { + "message": "Поддержка GM_* API · тот же блок метаданных" + }, + "home.feat.store.t": { + "message": "Магазин скриптов" + }, + "home.feat.store.d": { + "message": "Устанавливайте тысячи скриптов сообщества в один клик или публикуйте свои — развиваем экосистему вместе." + }, + "home.feat.store.stat": { + "message": "{count} скриптов сообщества" + }, + "home.feat.secure.t": { + "message": "Безопасность и надёжность" + }, + "home.feat.secure.d": { + "message": "Прозрачные и управляемые разрешения, видимое поведение — вредоносные скрипты останавливаются на входе." + }, + "home.feat.sync.t": { + "message": "Облачная синхронизация" + }, + "home.feat.sync.d": { + "message": "Скрипты и настройки синхронизируются между устройствами — ничего не теряется при смене или переустановке." + }, + "home.feat.bg.t": { + "message": "Фоновые скрипты" + }, + "home.feat.bg.d": { + "message": "Уникально: скрипты продолжают работать в фоне без открытой вкладки." + }, + "home.feat.api.t": { + "message": "Мощные API" + }, + "home.feat.api.d": { + "message": "Богаче GM: файловое хранилище, планировщик задач и кросс-доменные запросы под рукой." + }, + "home.feat.devTag": { + "message": "Для разработчиков" + }, + "home.dev.eyebrow": { + "message": "Для разработчиков · FOR DEVELOPERS" + }, + "home.dev.title1": { + "message": "Превратите браузер в " + }, + "home.dev.title2": { + "message": "среду выполнения кода" + }, + "home.dev.sub": { + "message": "Фоновые скрипты, богатые API, встроенный редактор и отладка — от первой строки до продакшена в одном месте." + }, + "home.dev.bg.t": { + "message": "Фоновые скрипты" + }, + "home.dev.bg.d": { + "message": "Не нужно держать вкладку — скрипты работают в фоне." + }, + "home.dev.api.t": { + "message": "Мощные API" + }, + "home.dev.api.d": { + "message": "Файловое хранилище, cron-расписание и кросс-доменные запросы — всё включено." + }, + "home.dev.editor.t": { + "message": "Встроенный редактор" + }, + "home.dev.editor.d": { + "message": "Подсветка синтаксиса, умное автодополнение и подсказки об ошибках — писать скрипты приятно." + }, + "home.dev.debug.t": { + "message": "Живая отладка" + }, + "home.dev.debug.d": { + "message": "Логи, история запусков и отслеживание ошибок — проблемы видны сразу." + }, + "home.dev.docsBtn": { + "message": "Читать документацию" + }, + "home.dev.apiBtn": { + "message": "Справочник API" + }, + "home.dev.run": { + "message": "Запуск" + }, + "home.comm.eyebrow": { + "message": "Open source · ОТКРЫТЫЙ КОД" + }, + "home.comm.title1": { + "message": "Создано " + }, + "home.comm.title2": { + "message": "сообществом" + }, + "home.comm.sub": { + "message": "Полностью открытый, прозрачный и бесплатный. Каждая строка кода доступна для аудита, каждый вклад виден." + }, + "home.comm.btn": { + "message": "Внести вклад на GitHub" + }, + "home.cta.eyebrow": { + "message": "Бесплатно · Open source · Без рекламы" + }, + "home.cta.h1": { + "message": "Готовы дать браузеру" + }, + "home.cta.h2": { + "message": "суперспособности" + }, + "home.cta.h3": { + "message": "?" + }, + "home.cta.sub": { + "message": "Установите из магазина в один клик или скачайте пакет вручную. За 30 секунд — суперспособности для веба." + }, + "home.cta.primary": { + "message": "Бесплатная установка для {browser}" + }, + "home.cta.secondary": { + "message": "Смотреть скрипты" + }, + "home.cta.stores": { + "message": "Поддержка Edge · Chrome · Firefox · ручной пакет" + }, + "home.cta.chip": { + "message": "Установлено и работает" + }, + "home.nav.docs": { + "message": "Документация" + }, + "home.nav.store": { + "message": "Магазин скриптов" + }, + "home.nav.dev": { + "message": "Разработчикам" + }, + "home.nav.changelog": { + "message": "История изменений" + }, + "home.nav.install": { + "message": "Установить" + }, + "home.nav.installTo": { + "message": "Добавить в {browser}" + }, + "home.nav.menu": { + "message": "Меню" + }, + "home.nav.theme": { + "message": "Сменить тему" + } +} diff --git a/i18n/ru/docusaurus-plugin-content-docs/current.json b/i18n/ru/docusaurus-plugin-content-docs/current.json new file mode 100644 index 00000000..8101a4d4 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,18 @@ +{ + "version.label": { + "message": "Next", + "description": "The label for version current" + }, + "sidebar.use.category.服务协议": { + "message": "Пользовательское соглашение", + "description": "The label for category 服务协议 in sidebar use" + }, + "sidebar.use.category.从其它管理器迁移": { + "message": "Миграция из других менеджеров", + "description": "The label for category 从其它管理器迁移 in sidebar use" + }, + "sidebar.dev.category.Agent 智能助手": { + "message": "Agent", + "description": "The label for category Agent 智能助手 in sidebar dev" + } +} diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md new file mode 100644 index 00000000..cce1ec90 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/about/index.md @@ -0,0 +1,20 @@ +--- +sidebar: false +title: О проекте +description: О ScriptCat +icon: info +--- + + +## О ScriptCat + +Вдохновлённый дизайном Tampermonkey и совместимый со скриптами Tampermonkey, ScriptCat реализует фреймворк выполнения фоновых скриптов и предоставляет ряд специальных API, благодаря которым скрипты могут делать больше, а также удобный редактор, в котором писать и разрабатывать код скриптов комфортно и плавно. + +Дорожная карта разработки: [Project #1](https://github.com/scriptscat/scriptcat/projects/1) — там мы публикуем планы разработки. Если у вас есть предложения, создайте [issue](https://github.com/scriptscat/scriptcat/issues), чтобы сообщить нам об этом. + +**Если проект оказался полезным, поставьте нам Star ❤❤❤** + +## Китайский форум Tampermonkey +> [Перейти на форум](https://bbs.tampermonkey.net.cn/) + +Китайский форум Tampermonkey — сообщество, которое мы создали для разработки и обсуждения скриптов в стиле Tampermonkey. На форуме много учебных материалов по скриптам и опытных участников: там можно обсуждать вопросы и задавать их. Также поддерживаются публикация и установка скриптов — каждый может свободно делиться своими работами. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-builtin-tools.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-builtin-tools.md new file mode 100644 index 00000000..63fe76dc --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-builtin-tools.md @@ -0,0 +1,275 @@ +--- +title: Справочник встроенных инструментов +--- + +У Agent есть набор встроенных инструментов, которые AI может автоматически вызывать во время диалога. Эти инструменты доступны по умолчанию в постоянных диалогах, и разработчикам скриптов обычно не нужно вызывать их напрямую — AI сам выбирает подходящий инструмент исходя из намерения пользователя. + +Понимание возможностей этих инструментов помогает писать лучшие системные промпты и пользовательские инструменты. + +## Получение веб-данных + +### web_fetch + +Загружает содержимое URL, поддерживая извлечение текста из HTML и суммаризацию LLM. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `url` | `string` | Да | Целевой URL (только http/https) | +| `prompt` | `string` | Нет | Промпт суммаризации (при указании LLM используется для сжатия содержимого) | +| `max_length` | `number` | Нет | Максимальное число символов содержимого | + +**Подробности поведения:** +- Таймаут запроса 30 секунд +- Из HTML автоматически извлекается основное тело (навигация, боковые панели и т.д. удаляются) +- JSON-ответы автоматически разбираются +- Обычный текст возвращается как есть +- При указании `prompt` загруженное содержимое отправляется в LLM для суммаризации + +**Возвращаемое значение:** +```json +{ + "url": "https://example.com", + "content_type": "text/html", + "content": "The extracted body content...", + "truncated": false, + "final_url": "https://example.com/redirected" +} +``` + +### web_search + +Запрашивает поисковую систему и возвращает структурированные результаты поиска. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `query` | `string` | Да | Поисковые ключевые слова | +| `max_results` | `number` | Нет | Максимальное число результатов (по умолчанию 5, максимум 10) | + +**Поддерживаемые поисковые системы:** + +| Система | Описание | Требуется настройка | +|------|------|---------| +| DuckDuckGo | Система по умолчанию | Настройка не нужна | +| Bing | Microsoft Bing Search | Нужен API Key | +| Baidu | Baidu Search | API Key не нужен | +| Google Custom Search | Google Custom Search | Нужны API Key + CSE ID | + +Поисковые системы настраиваются в панели управления: Agent → Настройки. + +**Возвращаемое значение:** +```json +[ + { + "title": "Search result title", + "url": "https://example.com/result", + "snippet": "Result snippet text..." + } +] +``` + +### get_tab_content + +Читает отрисованное содержимое страницы заданной вкладки, преобразуя его в структурированный Markdown с аннотациями CSS-селекторов. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `tab_id` | `number` | Да | ID вкладки | +| `selector` | `string` | Нет | CSS-селектор; извлекается только совпадающая часть | +| `prompt` | `string` | Нет | Промпт суммаризации | +| `max_length` | `number` | Нет | Максимальное число символов содержимого | + +Отличие от `web_fetch`: `get_tab_content` читает страницу **уже отрисованную браузером** (включая динамический JS-контент), тогда как `web_fetch` делает новый HTTP-запрос. + +**Возвращаемое значение:** +```json +{ + "tab_id": 123, + "url": "https://example.com", + "title": "Page title", + "content": "Structured content...", + "truncated": false, + "used_selector": "main" +} +``` + +## Управление вкладками + +### list_tabs + +Запрашивает открытые вкладки с поддержкой нескольких условий фильтрации. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `url_pattern` | `string` | Нет | Regex для сопоставления URL | +| `title_pattern` | `string` | Нет | Regex для сопоставления заголовка | +| `active` | `boolean` | Нет | Только активная вкладка | +| `window_id` | `number` | Нет | Конкретное окно | +| `audible` | `boolean` | Нет | Только вкладки, воспроизводящие аудио | + +### open_tab + +Открывает новую вкладку или навигирует существующую. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `url` | `string` | Да | Целевой URL | +| `tab_id` | `number` | Нет | ID существующей вкладки (при указании навигирует её; иначе открывается новая) | +| `active` | `boolean` | Нет | Активировать ли (по умолчанию `true`) | +| `window_id` | `number` | Нет | Конкретное окно | +| `wait_until_loaded` | `boolean` | Нет | Ждать ли окончания загрузки страницы (по умолчанию `true`) | + +### close_tab + +Закрывает вкладку. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `tab_id` | `number` | Да | ID вкладки | + +### activate_tab + +Активирует вкладку и фокусирует её окно. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `tab_id` | `number` | Да | ID вкладки | + +## Файловая система (OPFS) + +### opfs_write + +Записывает файл в рабочее пространство. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `path` | `string` | Да | Путь к файлу | +| `content` | `string` | Да | Содержимое файла (бинарные данные через data URL) | + +### opfs_read + +Читает файл из рабочего пространства. По умолчанию автоматически определяет тип: текстовые файлы возвращают содержимое, бинарные — blob URL. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `path` | `string` | Да | Путь к файлу | +| `mode` | `string` | Нет | `"text"` / `"blob"` / `"auto"` (по умолчанию), принудительный режим возврата | +| `offset` | `number` | Нет | Начальный номер строки (с 1), только текстовый режим | +| `limit` | `number` | Нет | Число строк для чтения, только текстовый режим (при более чем 200 строках нужна пагинация) | + +### opfs_list + +Выводит содержимое каталога. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `path` | `string` | Нет | Путь к каталогу (по умолчанию корневой) | + +### opfs_delete + +Удаляет файл или каталог. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `path` | `string` | Да | Путь к файлу/каталогу | + +## Взаимодействие с пользователем + +### ask_user + +Задаёт пользователю вопрос: свободный ввод или структурированный выбор. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `question` | `string` | Да | Текст вопроса | +| `options` | `string[]` | Нет | Список вариантов (при указании — вопрос с выбором) | +| `multiple` | `boolean` | Нет | Разрешить множественный выбор (по умолчанию `false`) | + +**Таймаут:** возвращает `{ answer: null, reason: "timeout" }` после 5 минут без ответа. + +**Возвращаемое значение:** +```json +{ "answer": "The user's answer text" } +``` + +### execute_script + +Выполняет JavaScript-код на странице или в песочнице. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `code` | `string` | Да | Код JavaScript | +| `target` | `string` | Да | `"page"` или `"sandbox"` | +| `tab_id` | `number` | Нет | Целевая вкладка, когда `target` — page (по умолчанию текущая активная) | +| `world` | `string` | Нет | `"MAIN"` или `"ISOLATED"` (по умолчанию), только режим page | + +**Сравнение окружений выполнения:** + +| Окружение | DOM | JS страницы | Blob URL расширения | Сценарий | +|------|-----|---------|---------------|---------| +| page + ISOLATED | Да | Нет | Да | Чтение DOM, извлечение контента | +| page + MAIN | Да | Да | Нет | Вызов функций страницы | +| sandbox | Нет | Нет | Нет | Чистые вычисления | + +## Подагенты + +### agent + +Запускает независимый подагент для сложной подзадачи. + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `prompt` | `string` | Да | Описание подзадачи | +| `description` | `string` | Нет | Короткая метка (3–5 слов, для UI) | +| `type` | `string` | Нет | Тип подагента (см. ниже); по умолчанию `"general"` | +| `tab_id` | `number` | Нет | ID вкладки, передаваемый подагенту для работы с ней | + +**Типы подагентов:** + +| type | Описание | Доступные инструменты | +|------|------|---------| +| `researcher` | Поиск информации (только чтение) | web_search, web_fetch, чтение содержимого страницы | +| `page_operator` | Автоматизация браузера | Управление вкладками, операции DOM, взаимодействие со страницей | +| `general` | Универсальный (по умолчанию) | Все инструменты | + +**Особенности:** +- У подагента свой независимый контекст диалога +- Он **не может** использовать `ask_user` или `agent` (чтобы предотвратить рекурсию) +- События подагента передаются родительскому диалогу через `sub_agent_event` + +## Управление задачами + +Эта группа инструментов управляет временным списком задач внутри диалога (в памяти, без сохранения). + +### create_task + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `subject` | `string` | Да | Заголовок задачи | +| `description` | `string` | Нет | Подробное описание | + +### get_task + +| Параметр | Тип | Обязательно | +|------|------|------| +| `task_id` | `string` | Да | + +### update_task + +| Параметр | Тип | Обязательно | Описание | +|------|------|------|------| +| `task_id` | `string` | Да | ID задачи | +| `status` | `string` | Нет | `"pending"` / `"in_progress"` / `"completed"` | +| `subject` | `string` | Нет | Новый заголовок | +| `description` | `string` | Нет | Новое описание | + +### list_tasks + +Без параметров; возвращает краткий список всех задач. + +### delete_task + +| Параметр | Тип | Обязательно | +|------|------|------| +| `task_id` | `string` | Да | + +> Инструменты управления задачами в основном позволяют AI отслеживать собственный прогресс при сложных многошаговых задачах; данные задач не сохраняются. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-conversation.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-conversation.md new file mode 100644 index 00000000..bbccb10a --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-conversation.md @@ -0,0 +1,285 @@ +--- +title: API диалогов +--- + +`@grant CAT.agent.conversation` + +API диалогов — ядро системы Agent: скрипт может создавать AI-диалоги, отправлять сообщения и получать ответы. + +## Создание диалога + +```javascript +const conv = await CAT.agent.conversation.create(options?); +``` + +### ConversationCreateOptions + +| Параметр | Тип | По умолчанию | Описание | +|------|------|--------|------| +| `id` | `string` | автогенерация | ID диалога, используется для возобновления существующего | +| `system` | `string` | — | Пользовательский системный промпт, добавляется после встроенного | +| `model` | `string` | модель по умолчанию | ID модели (получается после настройки в панели управления) | +| `maxIterations` | `number` | `20` | Максимальное число итераций цикла вызовов инструментов за один ход диалога | +| `skills` | `"auto" \| string[]` | — | `"auto"` загружает все Skills автоматически, либо укажите массив имён Skill | +| `tools` | `ToolDefinition[]` | — | Список пользовательских инструментов (см. ниже) | +| `commands` | `Record` | — | Пользовательские команды диалога | +| `ephemeral` | `boolean` | `false` | Временный диалог, не сохраняется в хранилище | +| `cache` | `boolean` | `true` | Включить Prompt Caching (снижает расход токенов) | +| `background` | `boolean` | `false` | Фоновый диалог, продолжающий работу после отключения UI; можно переподключиться через `attach()` | + +### Пользовательские инструменты + +Скрипт может регистрировать собственные инструменты для вызова AI: + +```javascript +const conv = await CAT.agent.conversation.create({ + tools: [{ + name: "get_weather", + description: "Get weather information for a given city", + parameters: { + type: "object", + properties: { + city: { + type: "string", + description: "City name" + }, + unit: { + type: "string", + enum: ["celsius", "fahrenheit"], + description: "Temperature unit" + } + }, + required: ["city"] + }, + handler: async (args) => { + // args = { city: "Beijing", unit: "celsius" } + const data = await fetchWeather(args.city, args.unit); + return { temperature: data.temp, condition: data.condition }; + } + }] +}); +``` + +`parameters` инструмента следует спецификации [JSON Schema](https://json-schema.org/); AI использует `description`, чтобы понять, когда и как вызывать инструмент. + +### Пользовательские команды + +Можно регистрировать пользовательские команды, начинающиеся с `/`: + +```javascript +const conv = await CAT.agent.conversation.create({ + commands: { + "/export": async (args) => { + // triggered when the user types "/export pdf" + await exportToPdf(args); + return "Export complete"; + } + } +}); +``` + +Встроенные команды: `/new` (новый диалог), `/reset` (сброс контекста), `/compact` (сжатие истории сообщений). + +## Получение существующего диалога + +```javascript +const conv = await CAT.agent.conversation.get(conversationId); +// returns null if the conversation doesn't exist +``` + +## Методы ConversationInstance + +### chat — синхронный чат + +```javascript +const reply = await conv.chat(content, options?); +``` + +Отправляет сообщение и ждёт полного ответа. Пока AI отвечает, он может вызывать инструменты; `chat` ждёт завершения всех вызовов, прежде чем вернуть итоговый результат. + +**Параметры:** + +| Параметр | Тип | Описание | +|------|------|------| +| `content` | `string \| ContentBlock[]` | Содержимое сообщения: текст или мультимодальные блоки | +| `options.tools` | `ToolDefinition[]` | Дополнительные инструменты только для этого вызова (объединяются с заданными при создании) | + +**Возвращаемое значение, ChatReply:** + +| Поле | Тип | Описание | +|------|------|------| +| `content` | `string \| ContentBlock[]` | Содержимое ответа AI | +| `thinking` | `string` | Процесс рассуждения модели (поддерживают только некоторые модели) | +| `toolCalls` | `ToolCall[]` | Зафиксированные вызовы инструментов в этом ответе | +| `usage` | `{ inputTokens, outputTokens }` | Использование токенов | +| `command` | `boolean` | Был ли этот ответ вызван командой | + +### chatStream — потоковый чат + +```javascript +const stream = await conv.chatStream(content, options?); +for await (const chunk of stream) { + // handle streaming events +} +``` + +Получает ответ AI в реальном времени — удобно, когда нужно постепенно отображать вывод. + +**Типы событий StreamChunk:** + +| type | Поле | Описание | +|------|------|------| +| `content_delta` | `content: string` | Инкрементальный текстовый контент | +| `thinking_delta` | `thinking: string` | Инкрементальный контент рассуждений | +| `tool_call` | `toolCall: ToolCall` | Информация о вызове инструмента (при смене состояния) | +| `content_block` | `block: ContentBlock` | Блок контента (изображение, файл и т.д.) | +| `done` | `usage: { inputTokens, outputTokens }` | Ход диалога завершён | +| `error` | `error: string, errorCode?: string` | Произошла ошибка | + +**Коды ошибок (errorCode):** + +| Код ошибки | Описание | +|--------|------| +| `rate_limit` | Лимит частоты API; обычно повторяется автоматически | +| `auth` | Ошибка аутентификации; проверьте API Key | +| `tool_timeout` | Таймаут выполнения инструмента | +| `max_iterations` | Достигнут максимум итераций цикла вызовов инструментов | +| `api_error` | Другая ошибка API | + +### getMessages — получить историю сообщений + +```javascript +const messages = await conv.getMessages(); +``` + +Возвращает `ChatMessage[]` со всеми сообщениями диалога. + +**Структура ChatMessage:** + +| Поле | Тип | Описание | +|------|------|------| +| `id` | `string` | ID сообщения | +| `role` | `"user" \| "assistant" \| "system" \| "tool"` | Роль сообщения | +| `content` | `string \| ContentBlock[]` | Содержимое сообщения | +| `thinking` | `string` | Процесс рассуждения (сообщения assistant) | +| `toolCalls` | `ToolCall[]` | Записи вызовов инструментов (сообщения assistant) | +| `toolCallId` | `string` | Соответствующий ID вызова инструмента (сообщения tool) | +| `usage` | `{ inputTokens, outputTokens }` | Использование токенов | +| `createtime` | `number` | Временная метка создания | + +### clear — очистить диалог + +```javascript +await conv.clear(); +``` + +Очищает всю историю сообщений диалога. + +### save — сохранить диалог + +```javascript +await conv.save(); +``` + +Сохраняет метаданные диалога в хранилище. Временные диалоги (`ephemeral: true`) по умолчанию не сохраняются; вызов этого метода превращает их в постоянные. + +### attach — переподключиться к фоновому диалогу + +```javascript +const stream = await conv.attach(); +for await (const chunk of stream) { + // receive real-time events from the background conversation +} +``` + +Если диалог создан с `background: true` и всё ещё работает в фоне, можно переподключиться через `attach()` и получать последующие потоковые события. + +### Свойства экземпляра + +| Свойство | Тип | Описание | +|------|------|------| +| `id` | `string` | ID диалога | +| `title` | `string` | Заголовок диалога | +| `modelId` | `string` | ID используемой модели | + +## Мультимодальный контент + +Содержимое сообщения может быть обычной строкой или массивом `ContentBlock[]` для поддержки нескольких модальностей: + +```javascript +// Send text + an image +await conv.chat([ + { type: "text", text: "Please analyze the content of this image" }, + { type: "image", attachmentId: "img-id", mimeType: "image/png" } +]); +``` + +### Типы ContentBlock + +| type | Обязательные поля | Описание | +|------|---------|------| +| `text` | `text: string` | Текстовое содержимое | +| `image` | `attachmentId: string, mimeType: string` | Изображение; модель должна поддерживать vision | +| `file` | `attachmentId: string, mimeType: string, name: string` | Файл | +| `audio` | `attachmentId: string, mimeType: string` | Аудио | + +## Временные и постоянные диалоги + +| Свойство | Постоянный диалог (по умолчанию) | Временный диалог | +|------|-------------------|---------------------| +| Хранение сообщений | Сохраняется в OPFS | Только в памяти | +| Встроенные инструменты | Все доступны | Не включены; нужно передавать через `tools` | +| Список диалогов | Виден | Не виден | +| Prompt Caching | Поддерживается | Можно отключить | +| Сценарий | Обычный диалог | Лёгкие разовые задачи, быстрые вопросы | + +## Управление контекстом + +### Автосжатие + +Когда использование контекста диалога превышает **80%** окна контекста модели, система автоматически вызывает LLM для генерации сводки истории, заменяя старые сообщения и освобождая место. + +### Prompt Caching + +Включён по умолчанию. Для моделей Anthropic системный промпт и история сообщений кэшируются, что может существенно снизить расход токенов и задержку на повторных ходах диалога. + +Можно отключить через `cache: false`: + +```javascript +const conv = await CAT.agent.conversation.create({ cache: false }); +``` + +## Полный пример + +```javascript +// ==UserScript== +// @name Smart Translation Assistant +// @match *://*/* +// @grant CAT.agent.conversation +// @grant CAT.agent.dom +// ==/UserScript== + +// Create a conversation with a custom tool +const conv = await CAT.agent.conversation.create({ + system: "You are a translation assistant. The user will give you web page content — please translate it into Chinese.", + tools: [{ + name: "get_selection", + description: "Get the text the user has selected on the page", + parameters: { type: "object", properties: {} }, + handler: async () => { + return { text: window.getSelection()?.toString() || "No text selected" }; + } + }] +}); + +// Stream the translation result +const stream = await conv.chatStream("Please get the selected text and translate it into Chinese"); +let result = ""; +for await (const chunk of stream) { + if (chunk.type === "content_delta") { + result += chunk.content; + // update the UI in real time + updateTranslationUI(result); + } +} +``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-dom.md b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-dom.md new file mode 100644 index 00000000..3ed47f69 --- /dev/null +++ b/i18n/ru/docusaurus-plugin-content-docs/current/dev/agent/agent-dom.md @@ -0,0 +1,336 @@ +--- +title: API DOM +--- + +`@grant CAT.agent.dom` + +API DOM предоставляет полный набор возможностей автоматизации страниц браузера: навигацию, чтение содержимого, скриншоты, взаимодействие с формами и мониторинг DOM. + +## Управление вкладками + +### listTabs — список вкладок + +```javascript +const tabs = await CAT.agent.dom.listTabs(); +``` + +Возвращает информацию о каждой открытой вкладке. + +**Возвращаемое значение, TabInfo[]:** + +| Поле | Тип | Описание | +|------|------|------| +| `tabId` | `number` | ID вкладки | +| `url` | `string` | Текущий URL | +| `title` | `string` | Заголовок страницы | +| `active` | `boolean` | Является ли текущей активной вкладкой | +| `windowId` | `number` | ID окна, которому принадлежит | +| `discarded` | `boolean` | Была ли выгружена (приостановлена) | + +## Навигация + +### navigate — перейти на страницу + +```javascript +const result = await CAT.agent.dom.navigate(url, options?); +``` + +**Параметры:** + +| Параметр | Тип | По умолчанию | Описание | +|------|------|--------|------| +| `url` | `string` | — | Целевой URL (обязательно) | +| `options.tabId` | `number` | текущая активная вкладка | Указать вкладку | +| `options.waitUntil` | `boolean` | `true` | Ждать ли окончания загрузки страницы | +| `options.timeout` | `number` | `30000` | Таймаут в миллисекундах | + +**Возвращаемое значение, NavigateResult:** + +```typescript +{ tabId: number; url: string; title: string } +``` + +## Чтение содержимого + +### readPage — прочитать содержимое страницы + +```javascript +const page = await CAT.agent.dom.readPage(options?); +``` + +Преобразует DOM страницы в структурированный текст, автоматически удаляя нерелевантные элементы вроде `