Refactor docs structure: fix title/sidebar mismatches, complete English translation

.gitea/workflows/ci.yaml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches-ignore:
+      - main
+      - release/*
+
+env:
+  RUNNER_TOOL_CACHE: /toolcache
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: pnpm/action-setup@v4
+
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: "20.x"
+        cache: 'pnpm'
+
+    - name: Install
+      run: pnpm install --frozen-lockfile
+
+    - name: Typecheck
+      run: pnpm run typecheck
+
+    - name: Build
+      run: pnpm run build
+
+    - name: Check URL inventory, i18n parity, and frontmatter conventions
+      run: pnpm run check

.gitea/workflows/deploy.yaml

@@ -35,6 +35,7 @@ jobs:
       run: |
         pnpm install --frozen-lockfile
         pnpm run build
+        pnpm run check
 
     - name: Set up QEMU
 #      uses: docker/setup-qemu-action@v3

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# 贡献指南 / 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 `<doc-name>.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.
+
+本文档记录本仓库的文档结构约定，帮助人类贡献者和 AI Agent 在不读遍全部历史讨论的情况下，正确地新增/修改文档。
+
+## 核心约定
+
+| 关注点 | 唯一来源 |
+|---|---|
+| URL / doc ID | 文件路径本身（不使用 `id:`、不使用数字前缀） |
+| 页面标题 / 侧边栏文字 / `<title>` | frontmatter `title:`（可选 `sidebar_label:` 用于侧边栏简称） |
+| 侧边栏排序 | `sidebars.js`，三个 sidebar（`use`/`dev`/`change`）均为显式列表 |
+| 图片 | `<文档名>.assets/` 同级目录 |
+| 内部链接 | 指向 `.md` 文件的相对路径（构建时会校验） |
+| URL 不变契约 | 提交的 `scripts/url-inventory.txt`，每次 PR 由 CI 校验 |
+
+**为什么这样做**：过去 `id:`/`sidebar_position:`/数字前缀/`README.md` 四种机制同时存在，导致侧边栏文字和页面标题可能不一致（例如"VSCode 扩展开发脚本" vs 页面实际标题"使用 VSCode 开发脚本"），且文件名与 URL 无法直接对应。现在文件路径就是 URL，看文件名就知道页面在哪。
+
+## 新增一篇文档
+
+1. 在 `docs/<section>/` 下创建 `xxx.md`（不要加数字前缀，不要用 `README.md`——除非确实是该目录的落地页，此时用 `index.md`）。
+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/<section>/xxx.md` 创建英文镜像，路径和文件名必须完全一致。
+6. 图片放在 `docs/<section>/xxx.assets/` 下，用 `./xxx.assets/foo.png` 引用；纯 UI 截图等语言无关的图片，英文版可以用 `@site/docs/<section>/xxx.assets/foo.png` 直接复用中文版的图片，不必重复存一份二进制文件。
+7. 跑一次 `pnpm run build && pnpm run check`，确认三项检查全部通过。
+
+## 新增一条更新日志
+
+`change/` 下的版本文件（`v1.x.md`）不使用数字前缀排序；在 `sidebars.js` 的 `change` 数组里手动插入新版本号（数组顺序即侧边栏顺序，新版本插在最前面）。`change/beta-changelog.md` 是 Beta 版本的单独更新日志。
+
+## 加载不变的 URL（改动前必须确认不受影响）
+
+以下 URL 被扩展程序硬编码调用，**任何重构都不能改变它们**：
+
+- `/docs/script_installation/`
+- `/docs/use/install_comple/`（`install_comple` 是历史拼写，故意保留，不是笔误）
+- `/uninstall/`
+
+`scripts/check-url-inventory.mjs` 会在每次 `pnpm run build` 后对比 `scripts/url-inventory.txt`；如果你的改动导致路由变化，CI 会失败并列出具体差异。**新增**路由是允许的（比如加一个 redirect），但需要在同一个 PR 里用 `node scripts/check-url-inventory.mjs --write` 更新这个文件，让 review 能看到你有意添加了什么。
+
+## 翻译对照表
+
+| 中文 | English |
+|---|---|
+| 脚本猫 | ScriptCat |
+| 用户脚本 | user script |
+| 后台脚本 | background script |
+| 定时脚本 | scheduled script |
+| 油猴 | Tampermonkey |
+
+英文标题结构应尽量与中文一一对应（标题层级、顺序一致），这样跨语言的锚点链接更容易对齐；注意 Docusaurus 生成的锚点是基于**渲染后的英文标题文本**，不是中文锚点的直接翻译（例如 `## Scheduled Script (\`@crontab\`)` 生成的锚点是 `#scheduled-script-crontab`，需要用构建产物核实，不要凭感觉猜。
+
+## 本地检查命令
+
+```bash
+pnpm run build          # 构建两个语言版本，onBrokenLinks/onBrokenAnchors 设置为 throw
+pnpm run check           # 依次跑 url 一致性 / i18n 覆盖率 / frontmatter 规范三项检查
+pnpm run check:urls       # 单独跑 URL 不变契约检查
+pnpm run check:i18n       # 单独跑中英文档配对检查
+pnpm run check:frontmatter # 单独跑 title/id/sidebar_position/H1 规范检查
+```

docs/change/beta.md → docs/change/beta-changelog.md

@@ -1,18 +1,16 @@
 ---
-id: beta-changelog
-sidebar_position: 1
+title: Beta 更新日志
 ---
 
 import GithubStar from '@site/src/components/GithubStar';
 import SponsorBlock from '@site/src/components/SponsorBlock/zh.mdx';
 
-# Beta 更新日志
 
 <GithubStar variant="bar" scene="changelog" />
 
 <SponsorBlock />
 
-脚本猫的版本发布主要分为两条分支: 正式版本与预发布版本，正式版本更新日志请看：[更新日志](./README.md)
+脚本猫的版本发布主要分为两条分支: 正式版本与预发布版本，正式版本更新日志请看：[更新日志](./index.md)
 
 预发布版本是在正式发布之前的版本.它们通常用于测试新功能,预发布版本的版本号包含一个预发布标识符,例如:
 `1.0.0-beta.1`.

docs/change/README.md → docs/change/index.md

@@ -1,18 +1,16 @@
 ---
-id: change
-sidebar_position: 1
+title: 更新日志
 ---
 
 import GithubStar from '@site/src/components/GithubStar';
 import SponsorBlock from '@site/src/components/SponsorBlock/zh.mdx';
 
-# 更新日志
 
 <GithubStar variant="bar" scene="changelog" />
 
 <SponsorBlock />
 
-Beta 版本更新日志请查看 [Beta 更新日志](./beta.md)
+Beta 版本更新日志请查看 [Beta 更新日志](./beta-changelog.md)
 
 ⚠️ 请注意，如果你使用的 Windows 8/7/XP 系统，或者浏览器内核版本低于\<120，需要自行手动安装[旧版脚本猫](https://bbs.tampermonkey.net.cn/thread-3068-1-1.html)，v0.16.x 是最后一个支持 Manifest V2 的版本，安装步骤可以参考：[加载解压缩方式安装扩展](/docs/use/use/#%E5%8A%A0%E8%BD%BD%E8%A7%A3%E5%8E%8B%E7%BC%A9%E6%96%B9%E5%BC%8F%E5%AE%89%E8%A3%85%E6%89%A9%E5%B1%95)。
 
@@ -2124,7 +2122,7 @@ Firefox 的 Manifest V3 版本还在筹备中。
 
 - 界面 UI 调整
 - 增加`GM_xmlhttpRequest`所支持的`unsafe header`和支持`arraybuffer`,`nocache`,`user`,`password`,`overrideMimeType`,功能
-- 增加运行日志查看功能,点击面板`运行状态`栏即可查看最后一次运行日志.具体请看:[console](/dev/meta.md#console)功能
+- 增加运行日志查看功能,点击面板`运行状态`栏即可查看最后一次运行日志.具体请看:[console](/dev/background.md#日志)功能
 - 修复`GM_notification`的`done`回调
 - 优化调整代码列表排序逻辑
 - 优化最后更新栏点击可进行脚本的手动检查更新

docs/change/v0.16.md

@@ -1,28 +1,26 @@
 ---
-sidebar_position: 10000
+title: v0.16
 ---
 
-# v0.16
-
 ## v0.16.1
 
 ## 最后更新添加排序功能
 
-![image-20240423113515332](img/v0.16.assets/image-20240423113515332.png)
+![image-20240423113515332](v0.16.assets/image-20240423113515332.png)
 
 ## v0.16.2
 
 ## 菜单自动隐藏配置
 
 默认配置为 5 个菜单项，超过 5 个菜单项时，菜单会自动隐藏，点击更多按钮展示隐藏的菜单项。
 
-![alt text](img/README.assets/setting.png)
+![alt text](v0.16.assets/setting.png)
 
-![iShot_2024-04-23_11.14.37](img/README.assets/iShot_2024-04-23_11.14.37.gif)
+![iShot_2024-04-23_11.14.37](v0.16.assets/iShot_2024-04-23_11.14.37.gif)
 
 ## 脚本列表添加列调整隐藏操作
 
-![image-20240423111623608](img/README.assets/image-20240423111623608.png)
+![image-20240423111623608](v0.16.assets/image-20240423111623608.png)
 
 ## v0.16.3
 

docs/change/v0.17.md

@@ -1,9 +1,7 @@
 ---
-sidebar_position: 9999
+title: v0.17
 ---
 
-# v0.17
-
 从 v0.17.0 开始，脚本猫升级为 manifest v3，并且切换储存引擎`indexedDB`为`chrome.storage.local`，储存引擎切换会自动打开本页面并重启扩展，如果发现数据出现问题，请前往[Github](https://github.com/scriptscat/scriptcat/issues)给我们反馈。
 
 ## v0.17.0-alpha
@@ -18,16 +16,16 @@ sidebar_position: 9999
 
 ### 弹出页面增加快速检查脚本更新
 
-![image-20250620165421754](img/v0.17.assets/image-20250620165421754.png)
+![image-20250620165421754](v0.17.assets/image-20250620165421754.png)
 
 
 
 ### 实现网站黑名单功能
 
-![image-20250620165529101](img/v0.17.assets/image-20250620165529101.png)
+![image-20250620165529101](v0.17.assets/image-20250620165529101.png)
 
 
 
 ### UserConfig添加switch类型
 
-![image-20250620165640030](img/v0.17.assets/image-20250620165640030.png)
+![image-20250620165640030](v0.17.assets/image-20250620165640030.png)

docs/change/v1.1.md

@@ -1,9 +1,7 @@
 ---
-sidebar_position: 9998
+title: v1.1
 ---
 
-# v1.1
-
 ## 网盘平台
 
 新增了Dropbox支持

docs/change/v1.2.md

@@ -1,40 +1,38 @@
 ---
-sidebar_position: 9997
+title: v1.2
 ---
 
-# v1.2
-
 修复版本更新不会再主动打开更新日志页面
 
 ## 脚本列表侧边栏 [#794](https://github.com/scriptscat/scriptcat/issues/794)
 
 增加了侧边栏可以进行高级筛选，增加了标签功能，在脚本->设置中可以对标签进行修改调整
 
-![image-20251016230129315](img/v1.2.assets/image-20251016230129315.png)
+![image-20251016230129315](v1.2.assets/image-20251016230129315.png)
 
 ## 卡片视图 [#860](https://github.com/scriptscat/scriptcat/issues/860)
 
 现在增加卡片视图，在首次启动时会自动切换卡片视图和表格视图，让窄屏能够更好的查看脚本信息
 
-![image-20251023103730266](img/v1.2.assets/image-20251023103730266.png)
+![image-20251023103730266](v1.2.assets/image-20251023103730266.png)
 
 ## 更友好的检查更新逻辑 [#755](https://github.com/scriptscat/scriptcat/issues/755)
 
 现在优化了检查更新的逻辑，不会再一股脑的弹出所有脚本的更新提示，而是会合并成一个更新窗口，你可以在这个窗口中选择要更新的脚本，也可以一键更新全部，并且会显示脚本的变动程度
 
-![image-20251016225931823](img/v1.2.assets/image-20251016225931823.png)
+![image-20251016225931823](v1.2.assets/image-20251016225931823.png)
 
 ## 增加编辑器配置和编辑器类型定义 [#708](https://github.com/scriptscat/scriptcat/pull/708)
 
 现在可以自定义编辑器配置和编辑器类型定义，编辑器配置可以参考 `tsconfig.json` 中的 [compilerOptions](https://www.typescriptlang.org/tsconfig/#compilerOptions) 进行编写
 
-![08c2889f-3029-4d3c-b180-c52d77c8077c](img/v1.2.assets/08c2889f-3029-4d3c-b180-c52d77c8077c.png)
+![08c2889f-3029-4d3c-b180-c52d77c8077c](v1.2.assets/08c2889f-3029-4d3c-b180-c52d77c8077c.png)
 
 ## 后台运行选项 [#1048](https://github.com/scriptscat/scriptcat/pull/1048)
 
 在`设置-运行时`中增加了后台运行选项，启用后，即使关闭所有窗口，浏览器仍会在后台运行，并最小化到系统托盘，直到您手动退出浏览器。这使后台脚本能够继续运行。
 
-![image-20251204174034940](img/v1.2.assets/image-20251204174034940.png)
+![image-20251204174034940](v1.2.assets/image-20251204174034940.png)
 
 ## API 更新
 

docs/change/v1.3.md

@@ -1,9 +1,7 @@
 ---
-sidebar_position: 9996
+title: v1.3
 ---
 
-# v1.3
-
 ## 新的脚本安装逻辑 [#842](https://github.com/scriptscat/scriptcat/issues/842)
 
 重新设计了脚本安装流程，不再依赖外部网站跳转打开新窗口进行安装，而是直接在当前页面内完成安装。同时优化了安装页面的布局，支持响应式显示，代码预览区域可滚动查看，下载失败等错误也会直接在页面中展示。

docs/change/v1.4.md

@@ -1,9 +1,7 @@
 ---
-sidebar_position: 9995
+title: v1.4 — Agent 智能助手
 ---
 
-# v1.4 — Agent 智能助手
-
 :::caution 测试阶段
 v1.4 目前仍处于测试阶段，以下功能和 API 可能会在正式发布前进行调整。欢迎试用并反馈问题。
 :::

docs/dev/agent/builtin-tools.md → docs/dev/agent/agent-builtin-tools.md

@@ -1,10 +1,7 @@
 ---
-id: agent-builtin-tools
-sidebar_position: 10
+title: 内置工具参考
 ---
 
-# 内置工具参考
-
 Agent 内置了一系列工具供 AI 在对话中自动调用。这些工具在持久化对话中默认可用，脚本开发者通常不需要直接调用它们——AI 会根据用户意图自动选择合适的工具。
 
 了解这些工具的能力有助于编写更好的系统提示词和自定义工具。

docs/dev/agent/conversation.md → docs/dev/agent/agent-conversation.md

@@ -1,10 +1,7 @@
 ---
-id: agent-conversation
-sidebar_position: 2
+title: 对话 API
 ---
 
-# 对话 API
-
 `@grant CAT.agent.conversation`
 
 对话 API 是 Agent 系统的核心，允许脚本创建 AI 对话、发送消息并接收回复。

docs/dev/agent/dom.md → docs/dev/agent/agent-dom.md

@@ -1,10 +1,7 @@
 ---
-id: agent-dom
-sidebar_position: 3
+title: DOM 操作 API
 ---
 
-# DOM 操作 API
-
 `@grant CAT.agent.dom`
 
 DOM 操作 API 提供完整的浏览器页面自动化能力，包括导航、内容读取、截图、表单交互和 DOM 监控。

docs/dev/agent/mcp.md → docs/dev/agent/agent-mcp.md

@@ -1,10 +1,7 @@
 ---
-id: agent-mcp
-sidebar_position: 8
+title: MCP 管理 API
 ---
 
-# MCP 管理 API
-
 `@grant CAT.agent.mcp`
 
 MCP（[Model Context Protocol](https://modelcontextprotocol.io/)）管理 API 允许脚本管理 MCP 服务器连接，MCP 服务器提供的工具会自动注册到 Agent，供 AI 对话调用。

docs/dev/agent/model.md → docs/dev/agent/agent-model.md

@@ -1,10 +1,7 @@
 ---
-id: agent-model
-sidebar_position: 6
+title: 模型查询 API
 ---
 
-# 模型查询 API
-
 `@grant CAT.agent.model`
 
 模型查询 API 提供只读访问，查询用户在管理页面中已配置的模型信息。出于安全考虑，API Key 不会暴露给脚本。

docs/dev/agent/opfs.md → docs/dev/agent/agent-opfs.md

@@ -1,10 +1,7 @@
 ---
-id: agent-opfs
-sidebar_position: 7
+title: OPFS 文件 API
 ---
 
-# OPFS 文件 API
-
 `@grant CAT.agent.opfs`
 
 OPFS（Origin Private File System）文件 API 允许脚本在 Agent 工作区中读写文件。所有路径相对于 `agents/workspace/` 目录。

docs/dev/agent/skill-dev.md → docs/dev/agent/agent-skill-dev.md

@@ -1,10 +1,7 @@
 ---
-id: agent-skill-dev
-sidebar_position: 9
+title: Skill 开发指南
 ---
 
-# Skill 开发指南
-
 Skill 是 Agent 系统的扩展包，由**提示词 + 工具脚本 + 参考资料**组合而成。通过 Skill，可以为 AI 注入专业领域知识和自定义工具能力。
 
 ## Skill 目录结构