diff --git a/.github/workflows/docs-site.yml b/.github/workflows/docs-site.yml new file mode 100644 index 000000000..bd739f33c --- /dev/null +++ b/.github/workflows/docs-site.yml @@ -0,0 +1,65 @@ +name: User documentation +on: + pull_request: + paths: ['docs/site/**', 'docs/screenshots/**', '.github/workflows/docs-site.yml'] + push: + branches: [main, 'docs/**'] + paths: ['docs/site/**', 'docs/screenshots/**', '.github/workflows/docs-site.yml'] + workflow_dispatch: +permissions: + contents: read +concurrency: + group: docs-${{ github.ref }} + cancel-in-progress: true +jobs: + build: + permissions: + contents: read + pages: read + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - uses: actions/setup-python@v5 + with: + python-version: '3.13' + - name: Install documentation build tools + run: pip install -r docs/site/requirements.txt playwright==1.57.0 + - name: Check links, page structure and search coverage + run: python -m unittest discover -s docs/site -p test_site.py + - name: Resolve the configured Pages URL + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.PEBREL_DOCS_PAGES_ENABLED == 'true' + id: pages + uses: actions/configure-pages@v5 + - name: Build portable static site + env: + DOCS_BASE_URL: ${{ vars.PEBREL_DOCS_BASE_URL || steps.pages.outputs.base_url }} + run: python docs/site/build.py --base-url "$DOCS_BASE_URL" + - name: Install browser + run: python -m playwright install --with-deps chromium + - name: Check desktop, mobile, keyboard and reduced-motion behavior + run: python docs/site/check_browser.py + - uses: actions/upload-artifact@v4 + if: always() + with: + name: docs-browser-results + path: docs-browser-results/ + if-no-files-found: ignore + - uses: actions/upload-pages-artifact@v4 + with: + path: docs/site/dist + deploy: + if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && vars.PEBREL_DOCS_PAGES_ENABLED == 'true' + needs: build + runs-on: ubuntu-24.04 + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - uses: actions/deploy-pages@v4 + id: deployment diff --git a/.gitignore b/.gitignore index 4077ca9c0..e9eae77df 100644 --- a/.gitignore +++ b/.gitignore @@ -152,3 +152,79 @@ dist-pack-*/ NebulaTerminal-*/ *-preview-package/ + +# Published static user guide: exact reviewed source allowlist. +!/docs/site/ +!/docs/site/assets/ +!/docs/site/content/ +!/docs/site/README.md +!/docs/site/assets/site.css +!/docs/site/assets/site.js +!/docs/site/build.py +!/docs/site/palettes.py +!/docs/site/check_browser.py +!/docs/site/content/index.md +!/docs/site/content/installation.md +!/docs/site/content/quickstart.md +!/docs/site/requirements.txt +!/docs/site/site.json +!/docs/site/template.html +!/docs/site/test_site.py + +!/docs/site/content/workspace.md +!/docs/site/content/shells.md +!/docs/site/content/clipboard.md +!/docs/site/content/completions.md +!/docs/site/content/palette.md +!/docs/site/content/commands.md +!/docs/site/content/navigation.md +!/docs/site/content/keyboard.md +!/docs/site/content/broadcast.md +!/docs/site/content/sessions.md +!/docs/site/content/layouts.md +!/docs/site/content/quick-terminal.md +!/docs/site/content/ssh.md +!/docs/site/content/ssh-library.md +!/docs/site/content/ssh-auth.md +!/docs/site/content/ssh-routing.md +!/docs/site/content/sftp.md +!/docs/site/content/files.md +!/docs/site/content/vcs.md +!/docs/site/content/documents.md +!/docs/site/content/images.md +!/docs/site/content/remote-edit.md +!/docs/site/content/ai-start.md +!/docs/site/content/hooks.md +!/docs/site/content/ai-history.md +!/docs/site/content/agents.md +!/docs/site/content/send-to-chat.md +!/docs/site/content/appearance.md +!/docs/site/content/themes.md +!/docs/site/content/backgrounds.md +!/docs/site/content/fonts.md +!/docs/site/content/notifications.md +!/docs/site/content/interaction.md +!/docs/site/content/configuration.md +!/docs/site/content/network.md +!/docs/site/content/runtime.md +!/docs/site/content/settings.md +!/docs/site/content/updates.md +!/docs/site/content/migration.md +!/docs/site/content/privacy.md +!/docs/site/content/troubleshooting.md +!/docs/site/screenshots.json +!/docs/site/third-party-notices.txt +!/docs/site/content/terminal-basics.md +!/docs/site/content/wsl.md +!/docs/site/content/ssh-config.md +!/docs/site/content/git-conflicts.md +!/docs/site/content/svn.md +!/docs/site/content/markdown-editing.md +!/docs/site/content/config-examples.md +!/docs/site/content/agent-worktrees.md + +!/docs/site/content/readme.md +!/docs/site/content/contributing.md + +!/docs/site/content/backups.md +!/docs/site/content/mobile.md diff --git a/architecture/notes/docs/site/2026-09-24-static-user-guide.md b/architecture/notes/docs/site/2026-09-24-static-user-guide.md new file mode 100644 index 000000000..d57f78e01 --- /dev/null +++ b/architecture/notes/docs/site/2026-09-24-static-user-guide.md @@ -0,0 +1,80 @@ +# Static user guide build boundary + +## Status + +Proposed with the documentation-site pull request. + +## Context + +The desktop application needs a navigable user manual that can be reviewed in a +fork, published through repository Pages, and read without a running service. +Desktop builds must not acquire a web-toolchain dependency. + +## Evidence + +- [Builder](../../../../docs/site/build.py) converts reviewed Markdown into HTML. +- [Workflow](../../../../.github/workflows/docs-site.yml) builds independently of Cargo. +- [Checks](../../../../docs/site/test_site.py) cover references and search coverage. +- [Operations](../../../../docs/site/README.md) describes Pages activation. + +## Decision + +Keep the site under `docs/site`, with build-only pinned Markdown and highlighting +libraries. Emit independent HTML pages, relative asset links and a local search +index. Use system fonts and repository-owned application imagery. Production +Pages deployment requires explicit repository opt-in and only runs from `main`. + +## Rejected alternatives + +A client-only application would make basic reading depend on JavaScript. A +hosted search service would add a credential and network dependency. A second +large frontend framework is unnecessary for Markdown, navigation and search. + +## Consequences + +Markdown and navigation remain separately reviewable. Rich HTML is trusted +repository content, not an input format for arbitrary visitors. The build has no +server-side user input and does not affect the desktop runtime. Captured app +images require a separate native environment; browser screenshots verify only +the guide's own interface. + +## Validation + +Local structural tests and the independent browser workflow exercise generated +links, search, copying, theme persistence, mobile navigation and no-script reading. +CI results, rather than the presence of workflow files, establish run status. + +## Supersedes + +None. + +## Revisit when + +Multiple maintained languages or versioned manuals make the current navigation +manifest insufficient, or the small local search index no longer meets users' +needs. Re-evaluate on measured behavior rather than adding services in advance. + +## Colour themes (2026-10-07) + +The guide takes its colours from the application's built-in themes instead of a +site-specific palette, so the documentation reads as part of the product and +readers can choose the theme they already use. `docs/site/palettes.py` parses the +catalog from `nebula_settings/src/themes.rs` at build time; the build fails when +that source changes shape. A hand-copied colour table was rejected because it would +drift from the application. A fixed light/dark pair was rejected because the +application ships sixteen themes and a toggle cannot express them. Where a theme's +accent or muted colour is too faint for text, the site darkens or lightens it toward +the theme foreground until it reaches 4.5:1; the application's own colours are +unchanged. The choice is stored in browser storage only. + +## Release baseline (2026-10-07) + +The base pages were re-audited against the `v2.1.1` tag and the manifest now records +that version and commit for every page; the earlier page-level `main` overrides were +removed. The tag, not `main`, is the baseline because the guide describes what readers +can install: `main` carries features that are not in any release. Pages whose behaviour +changed between 1.9.1 and 2.1.1 were updated from the code at the tag (platform +integrations on macOS and Linux, Windows ARM64 installer, release asset names, update +channels, settings navigation) and from the release notes for 2.0.0, 2.1.0 and 2.1.1. +Differences that are only translation refactors were not treated as behaviour changes. + diff --git a/docs/screenshots/pebrel-1.9.1-macos-arm64-ci.png b/docs/screenshots/pebrel-1.9.1-macos-arm64-ci.png new file mode 100644 index 000000000..df72fddb5 Binary files /dev/null and b/docs/screenshots/pebrel-1.9.1-macos-arm64-ci.png differ diff --git a/docs/site/README.md b/docs/site/README.md new file mode 100644 index 000000000..99d29031e --- /dev/null +++ b/docs/site/README.md @@ -0,0 +1,114 @@ +# Pebrel user documentation + +A Chinese user guide built from Markdown into standalone HTML, with local search, +keyboard navigation, light/dark themes, copy controls and image zoom. The build +uses existing repository screenshots; it does not redistribute font files or +change the desktop application's dependencies. + +## Build and check + +```sh +python -m pip install -r docs/site/requirements.txt +python docs/site/build.py +python -m unittest discover -s docs/site -p test_site.py +python -m http.server --directory docs/site/dist 8000 +``` + +For the browser smoke check, install `playwright==1.57.0`, run +`python -m playwright install chromium`, then `python docs/site/check_browser.py`. +The check serves the site under `/pebrel/`, exercising project-site path handling. +`CHROMIUM_PATH` optionally selects an existing Chromium executable. + +The manifest currently contains 56 user-facing guides, organized by tasks rather +than implementation modules. Source links are pinned to the documented commit. + +The documented baseline is the `v2.1.1` release (commit `d574856`). Pages were checked +against that tag, not against later `main`: UI labels, platform availability and file +names such as release assets follow what 2.1.1 shipped. When a later release changes a +page, update that page, its evidence and `site.json` together, or record a page-level +`version` and `source_commit` as described below. + +The generated `dist/` is disposable and ignored. Publish that directory's contents, +not this source directory. Open `index.html` directly for offline reading; browser +clipboard policies may require HTTP(S), in which case select and copy the text. +Search loads a local JavaScript index rather than requiring a backend or CDN. + +## Colour themes + +The site uses the desktop application's own palettes. `palettes.py` parses the 16 +built-in themes from `pebrel_settings/src/themes.rs` (and their names from +`pebrel_app/src/display/ui/theme.rs`) at build time and writes `assets/palettes.css` +plus the syntax colours in `assets/highlight.css`. Nothing is copied by hand, so a +theme added or retuned in the application reaches the site on the next build, and the +build fails if the source no longer has the expected shape. + +Readers pick a theme from the palette button in the header. **Follow system** mirrors the +application's default pair, Nord Light and Nord. The choice is stored in the browser +only. Accent, muted and syntax colours are nudged toward the theme's foreground when +they would fall below a 4.5:1 contrast ratio on the page or code surface; the tests +check this for every theme. + +## GitHub Pages + +The `User documentation` workflow builds and checks documentation on matching +pull requests and documentation-branch pushes. A PR never deploys the production +site. It publishes a Pages artifact and browser screenshots for review. + +A repository administrator must first choose **Settings → Pages → Source → GitHub +Actions**. Set the repository variable `PEBREL_DOCS_PAGES_ENABLED` to `true` to opt +in to deployment from `main`. On production builds, the workflow reads the +configured Pages URL for canonical links, the sitemap and the 404 home link. +Optionally override `PEBREL_DOCS_BASE_URL` with the public +site root, including the repository prefix and trailing slash, such as +`https://kuddev.github.io/pebrel/`, for canonical links and a sitemap. For a custom +domain, supply that domain's root instead. The workflow does not change repository +settings, DNS or domain ownership. + +After the change is merged, the workflow deploys on a matching `main` push; it can +also be run manually from `main`. Fork builds do not deploy unless their owner +separately enables the same opt-in variable and Pages setting. + +## Maintain content + +`site.json` owns navigation, the documented version, the source commit and each +page's evidence paths. A page may override `version` and `source_commit` when +a newer feature has been audited; its displayed version and evidence links then +use that snapshot without relabeling older guides. State the boundary in the page +body too: an audited `main` feature is not a claim of release availability. +Pages live in `content/`. Use Markdown links such as +`[Installation](installation.md)`: the builder resolves them for nested HTML paths. +Use `@ROOT@` for local image paths in rich HTML. Raw HTML is allowed for trusted, +reviewed repository content only; this is not an untrusted Markdown service. + +The build copies images named in `site.json` from `docs/screenshots/` and the +application icon from `extra/logo/nebula.png`. Caption old repository captures as +such. Newly captured application images must state their platform and version; +do not label a mockup or a documentation-page screenshot as an application capture. + +After verifying a feature change, update the relevant page and its evidence. +Lead with the task, identify the actual menu or shortcut, explain the result, +and place cautions beside the affected operation. Use visible entry points from +the page's documented snapshot: retained implementation code is not by itself +evidence of an available UI feature. Keep +implementation rationale out of the user guide. Add each new public source +file to the exact `.gitignore` allowlist rather than opening the whole `docs/` +subtree. The build checks that evidence paths exist; existence alone is not proof +that every sentence has been audited. + +## Application screenshot provenance + +`screenshots.json` records the original source and digest of every bundled image. +Most figures reuse the existing repository images and do not imply a particular +capture version. The macOS installation figure is the unchanged native application +capture from the official 1.9.1 release run `35961098033`, artifact +`stable-evidence-macos-aarch64` (`10792632932`). Its launch report identifies source +commit `e9e83d83a63ca9cc885857439f7f6826c1cbabaf`, whose tree matches the documented +main snapshot, and reports macOS 26.6.2 / aarch64. This was an existing upstream CI +run, not a new run dispatched by the documentation task. Its test message is +captioned as such; it is not presented as default application content. + +For future updates, inspect matching-version release evidence before replacing a +figure. Review the actual image, source commit and launch report, remove unrelated +personal content when necessary, and record any modification. Rebuild after +updating both the image manifest and provenance. Browser captures prove only the +documentation website's layout, not native application behavior. diff --git a/docs/site/assets/site.css b/docs/site/assets/site.css new file mode 100644 index 000000000..4429bc56a --- /dev/null +++ b/docs/site/assets/site.css @@ -0,0 +1,1709 @@ +:root { + --header:60px; + --sidebar:248px; + --radius:8px; + --font:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif; +} + +[hidden] { + display:none!important; +} + +* { + box-sizing:border-box; +} + +html { + scroll-behavior:smooth; + scroll-padding-top:100px; +} + +body { + margin:0; + background:var(--bg); + color:var(--text); + font-family:var(--font); + font-size:15px; + line-height:1.7; + -webkit-font-smoothing:antialiased; +} + +a { + color:inherit; + text-decoration:none; +} + +button,input { + font:inherit; +} + +button { + cursor:pointer; +} + +button,a,input,summary { + -webkit-tap-highlight-color:transparent; +} + +button { + color:inherit; +} + +button:disabled { + cursor:wait; + opacity:.65; +} + +a,button { + transition:background .18s,color .18s,border-color .18s,transform .18s; +} + +/* A palette change repaints everything at once; per-element fades would leave + rounded cards and pills in the old colours for a moment. */ +html[data-switching] *, +html[data-switching] *::before, +html[data-switching] *::after { + transition:none!important; +} + +button:active { + transform:translateY(1px); +} + +:focus-visible { + outline:3px solid var(--accent); + outline-offset:4px; +} + +button svg,.search-heading svg { + width:19px; + height:19px; + fill:none; + stroke:currentColor; + stroke-width:1.6; + stroke-linecap:round; + stroke-linejoin:round; + flex:none; +} + +kbd { + font-family:var(--font); + font-size:11px; + border:1px solid var(--line); + border-radius:5px; + padding:1px 5px; + white-space:nowrap; + background:var(--bg); + box-shadow:0 1px 0 var(--line); +} + +.sr-only { + position:absolute; + width:1px; + height:1px; + overflow:hidden; + clip:rect(0,0,0,0); + white-space:nowrap; +} + +.skip { + position:fixed; + top:-60px; + left:20px; + z-index:100; + padding:10px 20px; + border-radius:8px; + background:var(--text); + color:var(--bg); +} + +.skip:focus { + top:10px; +} + +.header { + height:var(--header); + position:fixed; + inset:0 0 auto; + z-index:40; + display:flex; + align-items:center; + gap:32px; + padding:0 24px; + border-bottom:1px solid var(--line); + background:var(--panel); +} + +.brand { + display:flex; + align-items:center; + gap:10px; + flex:none; +} + +.brand>span:first-of-type { + font-size:22px; + font-weight:620; + letter-spacing:-.8px; +} + +.brand-docs { + color:var(--muted); + font-size:14px; +} + +.brand img { + border-radius:7px; +} + +.header-links { + display:flex; + align-items:center; + gap:26px; + font-size:13px; + height:100%; + color:var(--muted); +} + +.header-links a { + height:100%; + display:flex; + align-items:center; + gap:5px; + position:relative; +} + +.header-links a:hover,.header-links .selected { + color:var(--text); +} + +.header-links .selected:after { + content:""; + position:absolute; + height:2px; + background:var(--text); + left:0; + right:0; + bottom:0; +} + +.header-actions { + display:flex; + align-items:center; + gap:10px; + margin-left:auto; +} + +.search-trigger { + height:38px; + width:230px; + display:flex; + align-items:center; + gap:10px; + border:1px solid var(--line); + border-radius:8px; + background:var(--soft); + color:var(--muted); + padding:0 11px; + font-size:12px; + text-align:left; +} + +.search-trigger kbd { + margin-left:auto; +} + +.search-trigger:hover { + border-color:var(--muted); +} + +.icon-button { + border:0; + background:transparent; + display:grid; + place-items:center; + width:40px; + height:40px; + border-radius:8px; + color:var(--muted); +} + +.icon-button:hover { + background:var(--soft); + color:var(--text); +} + +.menu-toggle { + display:none; +} + +.sidebar { + position:fixed; + top:var(--header); + bottom:0; + left:0; + width:var(--sidebar); + padding:29px 18px 20px 25px; + border-right:1px solid var(--line); + overflow:auto; + background:var(--panel); + scrollbar-width:thin; + scrollbar-color:var(--line) transparent; + z-index:30; + display:flex; + flex-direction:column; +} + +.sidebar-home { + display:flex; + justify-content:space-between; + align-items:center; + padding:0 10px 21px; + font-size:13px; + font-weight:600; +} + +.version { + font:11px ui-monospace,SFMono-Regular,monospace; + border-radius:20px; + padding:2px 7px; + background:var(--soft); + color:var(--muted); + font-weight:400; +} + +.nav-group { + margin:3px 0 23px; +} + +.nav-heading { + font-size:11px; + color:var(--muted); + font-weight:600; + padding:4px 11px 8px; +} + +.nav-link { + display:block; + padding:7px 12px; + border-radius:7px; + font-size:13px; + color:var(--muted); + margin:2px 0; + line-height:1.7; +} + +.nav-link:hover { + background:var(--soft); + color:var(--text); +} + +.nav-link.active { + background:var(--tint); + color:var(--accent); + font-weight:550; +} + +.sidebar-bottom { + border-top:1px solid var(--line); + margin:22px 10px 0; + padding-top:17px; + font-size:10px; + color:var(--muted); +} + +.sidebar-bottom>a { + display:block; + margin:8px 0; +} + +.status-dot { + display:inline-block; + width:5px; + height:5px; + background:var(--accent); + border-radius:50%; + margin-right:7px; +} + +.workspace { + margin-left:var(--sidebar); + padding:calc(var(--header) + 38px) 36px 0 52px; + display:grid; + grid-template-columns:minmax(0,800px) 168px; + gap:56px; + justify-content:center; +} + +main { + min-width:0; + outline:none; +} + +main:focus { + outline:none; +} + +.breadcrumb { + display:flex; + align-items:center; + justify-content:space-between; + gap:18px; + font-size:11px; + color:var(--muted); + margin:0 0 26px; + min-height:34px; +} + +.breadcrumb-path { + display:flex; + align-items:center; + gap:12px; + min-width:0; +} + +.breadcrumb a:hover { + color:var(--accent); +} + +.page-heading { + margin-bottom:34px; +} + +.page-heading h1 { + font-size:32px; + letter-spacing:-.8px; + line-height:1.3; + margin:0 0 12px; + font-weight:600; +} + +.page-description { + font-size:15px; + color:var(--muted); + line-height:1.8; + max-width:650px; + margin:0; +} + +.page-tools { + display:flex; + gap:12px; + align-items:center; + justify-content:flex-end; + margin:0 0 0 auto; + font-size:11px; + color:var(--muted); + white-space:nowrap; +} + +.small-button { + display:inline-flex; + gap:7px; + align-items:center; + background:var(--bg); + border:1px solid var(--line); + padding:5px 11px; + border-radius:7px; + min-height:32px; + font-size:11px; +} + +.small-button:hover { + background:var(--soft); + border-color:var(--muted); +} + +.toc { + position:sticky; + top:calc(var(--header) + 35px); + align-self:start; + font-size:11px; + max-height:calc(100vh - 140px); + overflow:auto; + padding-top:5px; + scrollbar-width:thin; +} + +.toc>span { + display:block; + font-weight:600; + margin:0 0 14px; +} + +.toc nav { + border-left:1px solid var(--line); +} + +.toc a { + display:block; + color:var(--muted); + padding:5px 0 5px 14px; + line-height:1.6; + margin-left:-1px; + border-left:1px solid transparent; +} + +.toc a.level-3 { + padding-left:24px; + font-size:10px; +} + +.toc a:hover { + color:var(--text); +} + +.toc a.active { + border-color:var(--accent); + color:var(--accent); +} + +.back-top { + background:none; + border:0; + color:var(--muted); + font-size:11px; + padding:18px 0; +} + +.back-top:hover { + color:var(--text); +} + +.hero { + margin:0 0 28px; +} + +.hero h1 { + font-size:36px; + font-weight:600; + line-height:1.35; + letter-spacing:-.9px; + margin:0 0 22px; + max-width:540px; +} + +.hero h1 span { + color:var(--accent); +} + +.hero-actions { + display:flex; + align-items:center; + gap:17px; +} + +.button-primary { + background:var(--accent); + color:var(--bg)!important; + display:inline-flex; + align-items:center; + gap:28px; + font-size:12px; + font-weight:500; + padding:10px 17px; + border:1px solid var(--accent); + border-radius:8px; + min-height:40px; + text-decoration:none!important; +} + +.button-primary:hover { + opacity:.88; +} + +.text-link { + font-size:12px; + color:var(--text)!important; + border:0!important; +} + +.text-link:hover { + text-decoration:underline; +} + +.platform-strip { + display:flex; + align-items:center; + gap:20px; + font-size:11px; + color:var(--muted); + margin:0 0 30px; +} + +.platform-strip>span:first-child { + color:var(--text); + font-weight:500; +} + +.platform-strip>a { + color:var(--muted); + text-decoration:none; + border-radius:6px; + padding:4px 2px; +} + +.platform-strip>a:hover, +.platform-strip>a:focus-visible { + color:var(--text); + text-decoration:underline; + text-underline-offset:4px; +} + +.platform-strip small { + font-size:9px; + border:1px solid var(--line); + border-radius:4px; + padding:1px 4px; + margin-left:4px; +} + +.readme-intro { + border-radius:8px; + padding:20px; + background:var(--soft); + margin:18px 0 24px; +} + +.readme-intro strong { + display:block; + font-size:20px; + line-height:1.5; + margin-bottom:8px; +} + +.readme-intro p { + margin:0!important; + color:var(--muted); +} + +.readme-visual-grid { + display:grid; + grid-template-columns:repeat(2,minmax(0,1fr)); + gap:12px; + margin:18px 0 28px; +} + +.readme-visual-card { + border:1px solid var(--line); + border-radius:8px; + padding:19px; + background:var(--panel); +} + +.readme-visual-card small { + display:block; + color:var(--accent); + font-size:10px; + font-weight:650; + letter-spacing:.06em; + margin-bottom:7px; +} + +.readme-visual-card strong { + display:block; + font-size:15px; + margin-bottom:7px; +} + +.readme-visual-card p { + color:var(--muted); + font-size:13px; + margin:0!important; +} + +.readme-badges { + display:flex; + flex-wrap:wrap; + gap:8px; + margin:14px 0 24px; +} + +.readme-badges span { + border:1px solid var(--line); + background:var(--soft); + border-radius:999px; + padding:6px 10px; + font-size:11px; + color:var(--muted); +} + +.contribution-flow { + display:grid; + grid-template-columns:repeat(4,minmax(0,1fr)); + gap:10px; + margin:18px 0 28px; + counter-reset:contrib-step; +} + +.contribution-flow>div { + border:1px solid var(--line); + border-radius:8px; + padding:16px; + min-width:0; +} + +.contribution-flow>div:before { + counter-increment:contrib-step; + content:counter(contrib-step,decimal-leading-zero); + display:block; + color:var(--accent); + font:600 10px ui-monospace,SFMono-Regular,monospace; + margin-bottom:8px; +} + +.contribution-flow strong { + display:block; + font-size:13px; + margin-bottom:5px; +} + +.contribution-flow span { + display:block; + color:var(--muted); + font-size:11px; + line-height:1.65; +} + +.feature-grid { + display:grid; + grid-template-columns:repeat(2,minmax(0,1fr)); + gap:12px; + margin:20px 0 32px; +} + +.feature-card { + border:1px solid var(--line); + border-radius:8px; + padding:18px 20px!important; + display:block; + text-decoration:none!important; + background:var(--bg); +} + +.feature-card:hover { + border-color:var(--accent); +} + +.feature-card h3 { + margin:0 0 6px!important; + font-size:15px!important; +} + +.feature-card p { + font-size:12px!important; + color:var(--muted); + line-height:1.75; + margin:0!important; + max-width:240px; +} + +.prose { + font-size:16px; + line-height:1.9; +} + +.prose h2 { + font-size:24px; + font-weight:560; + letter-spacing:-.5px; + margin:44px 0 16px; + line-height:1.5; + padding-top:3px; + scroll-margin-top:95px; +} + +.prose h3 { + font-size:17px; + font-weight:570; + margin:28px 0 12px; + scroll-margin-top:95px; +} + +.prose h4 { + font-size:15px; + font-weight:600; + margin:22px 0 10px; +} + +.prose p { + margin:14px 0; +} + +.prose a:not(.feature-card):not(.button-primary):not(.text-link):not(.heading-anchor) { + color:var(--accent); + text-decoration:underline; + text-decoration-color:color-mix(in srgb,var(--accent) 40%,transparent); + text-underline-offset:4px; +} + +.prose a:hover { + text-decoration-color:currentColor; +} + +.prose strong { + font-weight:620; +} + +.prose ul,.prose ol { + padding-left:24px; + margin:15px 0; +} + +.prose li { + padding-left:4px; + margin:8px 0; +} + +.prose li::marker { + color:var(--muted); +} + +.prose ol>li::marker { + color:var(--accent); + font-weight:600; +} + +.prose hr { + border:0; + border-top:1px solid var(--line); + margin:36px 0; +} + +.prose :not(pre)>code { + font:13px/1.7 ui-monospace,SFMono-Regular,Consolas,monospace; + color:var(--text); + background:var(--code); + padding:3px 6px; + border:1px solid var(--line); + border-radius:5px; + overflow-wrap:anywhere; +} + +.prose pre { + margin:0; + padding:21px 22px; + overflow:auto; + line-height:1.75; + font-size:13px; + tab-size:2; + scrollbar-width:thin; +} + +.prose pre code { + font-family:ui-monospace,SFMono-Regular,Consolas,monospace; +} + +.code-block { + border:1px solid var(--line); + border-radius:8px; + background:var(--code); + margin:19px 0; + overflow:hidden; +} + +.code-toolbar { + height:37px; + border-bottom:1px solid var(--line); + display:flex; + align-items:center; + justify-content:space-between; + padding:0 10px 0 18px; + font:10px var(--font); + color:var(--muted); + letter-spacing:.02em; +} + +.copy-code { + background:transparent; + border:0; + border-radius:5px; + font-size:10px; + color:var(--muted); + padding:5px 8px; + min-width:66px; + min-height:28px; +} + +.copy-code:hover { + color:var(--text); + background:var(--bg); +} + +.copy-code[data-copied=true] { + color:var(--accent); +} + +.table-wrap { + overflow:auto; + margin:20px 0; + border:1px solid var(--line); + border-radius:8px; + scrollbar-width:thin; +} + +.prose table { + border-collapse:collapse; + width:100%; + font-size:13px; + line-height:1.75; + text-align:left; +} + +.prose th { + font-weight:500; + color:var(--muted); + white-space:nowrap; +} + +.prose th,.prose td { + padding:12px 15px; + border-bottom:1px solid var(--line); + vertical-align:top; +} + +.prose tr:last-child td { + border-bottom:0; +} + +.prose td code { + font-size:11px!important; +} + +.prose td:first-child { + min-width:110px; +} + +.callout,.prose blockquote { + padding:16px 19px; + margin:23px 0; + border-left:3px solid var(--accent); + background:var(--soft); + border-radius:0 6px 6px 0; + font-size:13px; +} + +.callout p,.prose blockquote p { + margin:3px 0; +} + +.callout-title { + display:block; + font-weight:600; + margin:0 0 5px; + color:var(--accent); +} + +.callout.warning { + border-left-color:var(--yellow); +} + +.callout.warning .callout-title { + color:var(--yellow); +} + +.prose details { + margin:18px 0; + border:1px solid var(--line); + border-radius:8px; + padding:15px 18px; +} + +.prose summary { + cursor:pointer; + font-size:13px; + font-weight:550; +} + +.prose details[open] summary { + margin-bottom:12px; +} + +.heading-anchor { + display:inline-block; + margin-left:9px; + font-size:.68em; + color:var(--muted); + opacity:0; + vertical-align:middle; +} + +.prose h2:hover .heading-anchor,.prose h3:hover .heading-anchor,.heading-anchor:focus-visible { + opacity:1; +} + +.prose figure { + margin:27px 0; +} + +.prose figure img { + display:block; + width:100%; + height:auto; + border-radius:8px; + border:1px solid var(--line); + background:var(--soft); +} + +.prose figure button { + display:block; + width:100%; + padding:0; + border:0; + border-radius:8px; + background:none; + cursor:zoom-in; +} + +.prose figcaption { + font-size:10px; + color:var(--muted); + text-align:center; + line-height:1.7; + margin:10px 0; +} + +.prose .narrow-figure { + max-width:310px; + margin-left:auto; + margin-right:auto; +} + +.platform-tabs { + border:1px solid var(--line); + padding:18px 22px; + border-radius:8px; + margin:22px 0; +} + +.platform-tablist { + display:none; + gap:6px; + border-bottom:1px solid var(--line); + margin:-2px 0 18px; + padding-bottom:12px; +} + +.platform-tablist button { + background:none; + border:0; + border-radius:7px; + padding:7px 13px; + font-size:12px; +} + +.platform-tablist button[aria-selected=true] { + background:var(--tint); + color:var(--accent); +} + +.platform-tablist button:hover { + background:var(--soft); +} + +.js .platform-tablist { + display:flex; +} + +.platform-panel>:first-child { + margin-top:8px; +} + +.source-details { + margin:40px 0 30px; + font-size:11px; + color:var(--muted); + border-top:1px solid var(--line); + padding-top:19px; +} + +.source-details summary { + cursor:pointer; +} + +.source-details ul { + padding-left:18px; +} + +.source-details a { + text-decoration:underline; + text-underline-offset:3px; + overflow-wrap:anywhere; +} + +.page-pagination { + display:grid; + grid-template-columns:1fr 1fr; + gap:15px; + margin:25px 0 35px; +} + +.page-pagination a { + border:1px solid var(--line); + border-radius:8px; + padding:16px 18px; + display:flex; + flex-direction:column; + font-size:13px; +} + +.page-pagination a:last-child { + text-align:right; +} + +.page-pagination a:hover { + background:var(--soft); + border-color:var(--muted); +} + +.page-pagination small { + color:var(--muted); + font-size:10px; + margin-bottom:5px; +} + +.article-footer { + display:flex; + gap:20px; + border-top:1px solid var(--line); + padding:20px 0 34px; + font-size:10px; + color:var(--muted); +} + +.article-footer>span { + margin-right:auto; +} + +.article-footer a:hover { + color:var(--accent); +} + +dialog { + color:var(--text); + border:1px solid var(--line); + background:var(--bg); + box-shadow:0 12px 40px color-mix(in srgb,#000 20%,transparent); + padding:0; +} + +dialog::backdrop { + background:color-mix(in srgb,var(--text) 32%,transparent); +} + +.search-dialog { + width:min(680px,calc(100vw - 32px)); + border-radius:8px; + margin:15vh auto auto; + max-height:74vh; + overflow:hidden; +} + +.search-dialog[open] { + display:flex; + flex-direction:column; + animation:dialog-in .2s ease-out; +} + +.search-heading { + display:flex; + align-items:center; + gap:13px; + padding:18px 20px; + border-bottom:1px solid var(--line); +} + +.search-heading svg { + color:var(--muted); +} + +.search-heading input { + flex:1; + min-width:0; + border:0; + outline:none; + background:transparent; + color:var(--text); + font-size:15px; +} + +.search-heading input:focus-visible { + outline:0; +} + +.search-heading:focus-within { + box-shadow:inset 0 -2px var(--accent); +} + +.search-status { + font-size:11px; + color:var(--muted); + padding:0 20px; + margin:12px 0 8px; +} + +.search-results { + padding:0 9px 10px; + overflow:auto; + min-height:120px; + max-height:49vh; +} + +.search-result { + display:block; + width:100%; + text-align:left; + border:1px solid transparent; + background:transparent; + color:var(--text); + padding:12px 14px; + border-radius:8px; + margin:2px 0; +} + +.search-result[aria-selected=true],.search-result:hover { + background:var(--soft); + border-color:var(--line); +} + +.search-result strong { + display:block; + font-size:13px; + font-weight:550; +} + +.search-result small { + display:block; + font-size:11px; + color:var(--muted); + line-height:1.7; + margin-top:3px; + overflow:hidden; + text-overflow:ellipsis; +} + +.search-result mark { + background:var(--tint); + color:var(--accent); + border-radius:2px; +} + +.search-footer { + display:flex; + justify-content:space-between; + font-size:10px; + color:var(--muted); + border-top:1px solid var(--line); + padding:12px 20px; +} + +.search-footer kbd { + font-size:9px; + margin-right:4px; +} + +.image-dialog { + width:calc(100vw - 80px); + max-width:1500px; + max-height:92vh; + border-radius:8px; + padding:18px; + overflow:auto; + text-align:right; +} + +.image-dialog img { + display:block; + width:100%; + height:auto; + margin:14px auto 0; +} + +.image-dialog p { + font-size:12px; + text-align:center; + color:var(--muted); +} + +.toast { + position:fixed; + left:50%; + bottom:28px; + transform:translate(-50%,12px); + background:var(--text); + color:var(--bg); + border:1px solid var(--line); + padding:10px 19px; + border-radius:8px; + font-size:12px; + opacity:0; + pointer-events:none; + transition:.2s; + z-index:100; + max-width:90vw; +} + +.toast.show { + opacity:1; + transform:translate(-50%,0); +} + +.noscript { + position:fixed; + bottom:0; + left:0; + right:0; + background:var(--soft); + padding:10px; + font-size:12px; + text-align:center; + z-index:50; +} + +@keyframes dialog-in { + from { + opacity:0; + transform:translateY(-10px) scale(.985); + } + to { + opacity:1; + transform:none; + } +} + +@media(min-width:1700px) { + .workspace { + padding-left:74px; + gap:72px; + grid-template-columns:minmax(0,840px) 190px; + } +} + +@media(max-width:1280px) { + :root { + --sidebar:232px; + } + .header { + padding:0 23px; + gap:30px; + } + .workspace { + padding-left:38px; + padding-right:30px; + gap:30px; + grid-template-columns:minmax(0,800px) 140px; + } + .sidebar { + padding-left:17px; + } + .search-trigger { + width:195px; + } + .hero h1 { + font-size:35px; + } +} + +@media(max-width:1080px) { + .toc { + display:none; + } + .workspace { + grid-template-columns:minmax(0,800px); + padding-left:38px; + padding-right:38px; + } + .header-links { + gap:20px; + } + .hero h1 { + font-size:37px; + } + .header { + gap:25px; + } + .brand-docs { + display:none; + } +} + +@media(max-width:800px) { + :root { + --header:62px; + --sidebar:272px; + } + .header { + padding:0 17px; + gap:15px; + } + .brand>span:first-of-type { + font-size:20px; + } + .brand img { + width:28px; + height:28px; + } + .header-links { + display:none; + } + .header-actions { + gap:2px; + } + .search-trigger { + width:40px; + padding:0; + display:grid; + place-items:center; + border:0; + background:transparent; + } + .search-trigger span,.search-trigger kbd { + display:none; + } + .menu-toggle { + display:grid; + } + .sidebar { + transform:translateX(-100%); + transition:transform .24s ease; + width:var(--sidebar); + z-index:45; + padding:24px 19px 20px; + visibility:hidden; + } + .sidebar.open { + transform:translateX(0); + visibility:visible; + } + .drawer-backdrop { + position:fixed; + inset:var(--header) 0 0; + background:color-mix(in srgb,var(--text) 32%,transparent); + z-index:44; + } + .workspace { + margin-left:0; + padding:calc(var(--header) + 28px) 24px 0; + display:block; + } + .page-heading h1 { + font-size:31px; + } + .hero { + padding:29px 26px; + border-radius:8px; + } + .hero h1 { + font-size:34px; + } + .hero p { + font-size:13px; + max-width:370px; + } + .breadcrumb { + margin-bottom:22px; + } + .page-description { + font-size:14px; + } + .nav-link { + padding:10px 12px; + min-height:42px; + } + .article-footer { + gap:13px; + flex-wrap:wrap; + } + .article-footer>span { + width:100%; + } + .search-dialog { + margin-top:10vh; + } + .icon-button { + width:42px; + height:42px; + } + .small-button { + min-height:38px; + } + .copy-code { + min-height:32px; + } + .platform-tablist button { + min-height:40px; + } +} + +@media(max-width:480px) { + .workspace { + padding-left:19px; + padding-right:19px; + } + .hero { + padding:26px 23px; + } + .hero h1 { + font-size:29px; + letter-spacing:-.7px; + } + .hero p { + font-size:12px; + } + .hero-actions { + gap:15px; + } + .platform-strip { + gap:11px; + font-size:10px; + flex-wrap:wrap; + } + .contribution-flow { + grid-template-columns:1fr; + } + .feature-grid { + gap:11px; + } + .feature-card { + padding:17px!important; + } + .feature-card h3 { + font-size:14px!important; + } + .feature-card p { + font-size:11px!important; + } + .prose { + font-size:15px; + } + .prose h2 { + font-size:21px; + } + .prose pre { + font-size:12px; + padding:17px; + } + .breadcrumb { + align-items:flex-start; + flex-wrap:wrap; + } + .page-tools { + width:100%; + flex-wrap:wrap; + justify-content:flex-start; + margin-left:0; + } + .readme-visual-grid { + grid-template-columns:1fr; + } + .contribution-flow { + grid-template-columns:repeat(2,minmax(0,1fr)); + } + .page-pagination { + gap:9px; + } + .page-pagination a { + padding:13px; + font-size:12px; + } + .search-heading { + padding:13px; + } + .search-footer { + padding:11px 13px; + } + .search-footer>span:last-child { + display:none; + } + .image-dialog { + width:calc(100vw - 20px); + padding:10px; + } + .prose th,.prose td { + padding:10px; + } + .platform-tabs { + padding:16px; + } + .page-heading h1 { + font-size:29px; + } +} + +@media(prefers-reduced-motion:reduce) { + html { + scroll-behavior:auto; + } + *,*:before,*:after { + animation:none!important; + transition:none!important; + view-transition-name:none!important; + } + ::view-transition-group(*),::view-transition-old(*),::view-transition-new(*) { + animation:none!important; + } + .feature-card:hover { + transform:none; + } +} + +@media print { + html[data-theme] { + --bg:#fff; + --soft:#f7f7f7; + --panel:#fff; + --text:#000; + --muted:#444; + --line:#bbb; + --accent:#111; + --tint:#f7f7f7; + --code:#f5f5f5; + color-scheme:light; + } + .code-block,.code-block code,.code-block code span { + color:#000!important; + background:transparent!important; + } + .header,.sidebar,.toc,.page-tools,.page-pagination,.article-footer,.heading-anchor,dialog,.toast,.back-top,.copy-code { + display:none!important; + } + .workspace { + margin:0; + padding:0; + display:block; + } + body { + font-size:11pt; + background:#fff; + color:#000; + } + .prose { + font-size:10pt; + } + .prose h2,.prose h3 { + break-after:avoid; + } + .code-block,.callout,.prose figure { + break-inside:avoid; + } + .prose pre { + white-space:pre-wrap; + } + .prose a { + color:inherit; + } + .hero { + background:#f5f5f5; + } + .source-details { + display:none; + } + .platform-panel[hidden] { + display:block!important; + } + .platform-tablist { + display:none!important; + } + main { + max-width:100%; + } + .feature-grid { + display:block; + } + .feature-card { + margin-bottom:10px; + } +} + +@media(max-width:800px) { + html:not(.js) .sidebar { + position:relative; + top:auto; + bottom:auto; + transform:none; + visibility:visible; + width:100%; + margin-top:var(--header); + max-height:300px; + border-bottom:1px solid var(--line); + } + html:not(.js) .workspace { + padding-top:28px; + } +} + +.palette-picker { + position:relative; +} + +.palette-menu { + position:absolute; + right:0; + top:calc(100% + 8px); + width:232px; + max-height:min(560px,calc(100vh - var(--header) - 24px)); + overflow:auto; + padding:6px; + border:1px solid var(--line); + border-radius:8px; + background:var(--bg); + box-shadow:0 12px 40px color-mix(in srgb,#000 18%,transparent); + z-index:60; + scrollbar-width:thin; +} + +.palette-group { + display:flex; + flex-direction:column; + margin-top:6px; + padding-top:6px; + border-top:1px solid var(--line); +} + +.palette-group>span { + padding:4px 10px; + font-size:11px; + color:var(--muted); +} + +.palette-menu button { + display:flex; + align-items:center; + gap:10px; + width:100%; + padding:7px 10px; + border:0; + border-radius:6px; + background:transparent; + font-size:13px; + text-align:left; +} + +.palette-menu button:hover, +.palette-menu button:focus-visible { + background:var(--soft); +} + +.palette-menu button[aria-checked=true] { + color:var(--accent); + font-weight:550; +} + +.palette-menu button[aria-checked=true]::after { + content:"✓"; + margin-left:auto; +} + +.swatch { + width:16px; + height:16px; + flex:none; + border:1px solid var(--line); + border-radius:50%; + background:linear-gradient(135deg,var(--a) 50%,var(--b) 50%); +} + +.swatch-system { + --a:#eceff4; + --b:#2e3440; +} diff --git a/docs/site/assets/site.js b/docs/site/assets/site.js new file mode 100644 index 000000000..231936085 --- /dev/null +++ b/docs/site/assets/site.js @@ -0,0 +1,292 @@ +(() => { + 'use strict'; + document.documentElement.classList.add('js'); + const root = document.body.dataset.root; + const $ = (selector) => document.querySelector(selector); + const $$ = (selector) => [...document.querySelectorAll(selector)]; + const reducedMotion = matchMedia('(prefers-reduced-motion: reduce)'); + const toast = $('.toast'); + let toastTimer; + function announce(message) { + clearTimeout(toastTimer); + toast.textContent = message; + toast.classList.add('show'); + toastTimer = setTimeout(() => toast.classList.remove('show'), 2600); + } + + const copyTimers = new WeakMap(); + async function copy(text, button) { + try { + await navigator.clipboard.writeText(text); + clearTimeout(copyTimers.get(button)); + const label = button.dataset.label || button.textContent; + button.dataset.label = label; + button.dataset.copied = 'true'; + button.textContent = '✓ 已复制'; + announce('已复制到剪贴板'); + copyTimers.set(button, setTimeout(() => { + button.textContent = label; + delete button.dataset.copied; + }, 1700)); + } catch { + announce('复制未成功,请选中文本手动复制。'); + } + } + $$('.copy-code').forEach(button => button.addEventListener('click', () => { + copy(button.closest('.code-block').querySelector('code').textContent, button); + })); + const copyPage = $('#copy-page'); + copyPage?.addEventListener('click', () => copy( + JSON.parse($('#page-source').textContent), copyPage + )); + $$('.heading-anchor').forEach(link => link.addEventListener('click', async () => { + try { + await navigator.clipboard.writeText(link.href); + announce('已复制本节链接'); + } catch { + announce('已定位本节;可从地址栏复制链接。'); + } + })); + + const html = document.documentElement; + const paletteButton = $('#theme-toggle'); + const paletteMenu = $('#palette-menu'); + const paletteOptions = $$('[data-palette-option]'); + const darkPalettes = new Set(paletteOptions.filter(option => option.closest('[aria-label="深色"]')).map(option => option.dataset.paletteOption)); + const systemDark = matchMedia('(prefers-color-scheme: dark)'); + function applyPalette(choice, remember) { + const id = choice === 'system' ? (systemDark.matches ? 'Nord' : 'NordLight') : choice; + html.dataset.switching = ''; + requestAnimationFrame(() => requestAnimationFrame(() => delete html.dataset.switching)); + html.dataset.palette = id; + html.dataset.theme = darkPalettes.has(id) ? 'dark' : 'light'; + if (choice === 'system') html.dataset.follow = 'system'; else delete html.dataset.follow; + paletteOptions.forEach(option => option.setAttribute('aria-checked', String(option.dataset.paletteOption === choice))); + $('meta[name=theme-color]')?.setAttribute('content', getComputedStyle(html).getPropertyValue('--bg').trim()); + if (remember) { try { localStorage.setItem('pebrel-docs-palette', choice); } catch { /* Session only. */ } } + } + function currentChoice() { return html.dataset.follow === 'system' ? 'system' : html.dataset.palette; } + function setPaletteMenu(open) { + paletteMenu.hidden = !open; + paletteButton.setAttribute('aria-expanded', String(open)); + if (open) (paletteMenu.querySelector('[aria-checked=true]') || paletteOptions[0]).focus(); + } + applyPalette(currentChoice(), false); + paletteButton.addEventListener('click', () => setPaletteMenu(paletteMenu.hidden)); + paletteOptions.forEach(option => option.addEventListener('click', () => { + applyPalette(option.dataset.paletteOption, true); + setPaletteMenu(false); + paletteButton.focus(); + })); + paletteMenu.addEventListener('keydown', event => { + const index = paletteOptions.indexOf(document.activeElement); + if (event.key === 'ArrowDown' || event.key === 'ArrowUp') { + event.preventDefault(); + paletteOptions[(index + (event.key === 'ArrowDown' ? 1 : -1) + paletteOptions.length) % paletteOptions.length].focus(); + } else if (event.key === 'Escape') { + setPaletteMenu(false); + paletteButton.focus(); + } + }); + document.addEventListener('click', event => { + if (!paletteMenu.hidden && !event.target.closest('.palette-picker')) setPaletteMenu(false); + }); + systemDark.addEventListener('change', () => { if (currentChoice() === 'system') applyPalette('system', false); }); + + const sidebar = $('#sidebar'); + const menu = $('#menu-toggle'); + const backdrop = $('.drawer-backdrop'); + const mobile = matchMedia('(max-width: 800px)'); + function setMenu(open) { + sidebar.classList.toggle('open', open); + backdrop.hidden = !open; + menu.setAttribute('aria-expanded', String(open)); + menu.setAttribute('aria-label', open ? '关闭文档导航' : '打开文档导航'); + document.body.style.overflow = open ? 'hidden' : ''; + sidebar.inert = mobile.matches && !open; + $('.workspace').inert = open; + if (open) sidebar.querySelector('.active, a').focus(); + } + setMenu(false); + menu.addEventListener('click', () => setMenu(!sidebar.classList.contains('open'))); + backdrop.addEventListener('click', () => { setMenu(false); menu.focus(); }); + mobile.addEventListener('change', () => setMenu(false)); + sidebar.querySelector('.active')?.scrollIntoView({ block: 'nearest' }); + + const searchDialog = $('#search-dialog'); + const input = $('#search-input'); + const results = $('#search-results'); + const status = $('.search-status'); + let indexPromise; + let index = []; + let matches = []; + let selected = 0; + let searchOpener; + function loadIndex() { + if (Array.isArray(window.PEBREL_DOCS_SEARCH)) return Promise.resolve(window.PEBREL_DOCS_SEARCH); + if (!indexPromise) indexPromise = new Promise((resolve, reject) => { + const script = document.createElement('script'); + script.src = root + 'search-index.js'; + script.onload = () => resolve(window.PEBREL_DOCS_SEARCH); + script.onerror = () => { script.remove(); indexPromise = null; reject(new Error('Search unavailable')); }; + document.head.append(script); + }); + return indexPromise; + } + function highlight(target, text, query) { + if (!query) { target.textContent = text; return; } + const position = text.toLocaleLowerCase().indexOf(query.toLocaleLowerCase()); + if (position < 0) { target.textContent = text; return; } + target.append(document.createTextNode(text.slice(0, position))); + const mark = document.createElement('mark'); + mark.textContent = text.slice(position, position + query.length); + target.append(mark, document.createTextNode(text.slice(position + query.length))); + } + function selectResult(value) { + selected = Math.max(0, Math.min(value, matches.length - 1)); + [...results.children].forEach((element, position) => { + element.setAttribute('aria-selected', String(position === selected)); + }); + const active = results.children[selected]; + if (active) { + input.setAttribute('aria-activedescendant', active.id); + active.scrollIntoView({ block: 'nearest' }); + } else input.removeAttribute('aria-activedescendant'); + } + function renderResults() { + const query = input.value.trim(); + const terms = query.toLocaleLowerCase().split(/\s+/).filter(Boolean); + matches = index.map(item => { + const title = item.title.toLocaleLowerCase(); + const text = (item.title + ' ' + item.text).toLocaleLowerCase(); + const score = terms.every(term => text.includes(term)) + ? terms.reduce((n, term) => n + (title.includes(term) ? 15 : 1), 0) + (title === query.toLocaleLowerCase() ? 50 : 0) + : -1; + return { ...item, score }; + }).filter(item => item.score >= 0).sort((a, b) => b.score - a.score).slice(0, 18); + results.replaceChildren(); + status.textContent = query ? (matches.length ? `找到 ${matches.length}${matches.length === 18 ? '+' : ''} 个相关章节` : '没有找到相关内容。试试“分屏”“SSH”或“字体”。') : '从常用指南开始,或输入功能、设置与操作步骤。'; + matches.forEach((item, position) => { + const row = document.createElement('div'); + row.className = 'search-result'; + row.id = 'search-result-' + position; + row.setAttribute('role', 'option'); + const title = document.createElement('strong'); + highlight(title, item.title, query); + const description = document.createElement('small'); + const matchPosition = query ? item.text.toLocaleLowerCase().indexOf(terms[0]) : 0; + const start = Math.max(0, matchPosition - 28); + highlight(description, (start ? '…' : '') + item.text.slice(start, start + 130), query); + row.append(title, description); + row.addEventListener('click', () => { location.href = root + item.url; }); + row.addEventListener('pointermove', () => selectResult(position)); + results.append(row); + }); + selectResult(0); + } + async function openSearch() { + if (sidebar.classList.contains('open')) setMenu(false); + searchOpener = document.activeElement; + if (!searchDialog.open) searchDialog.showModal(); + input.focus(); + status.textContent = '正在准备本地搜索索引…'; + try { index = await loadIndex(); renderResults(); } + catch { status.textContent = '搜索索引未能加载。请刷新重试,或使用左侧目录。'; } + } + $$('[data-search]').forEach(button => button.addEventListener('click', openSearch)); + $$('[data-close-search]').forEach(button => button.addEventListener('click', () => searchDialog.close())); + searchDialog.addEventListener('close', () => searchOpener?.focus()); + searchDialog.addEventListener('click', event => { if (event.target === searchDialog) searchDialog.close(); }); + input.addEventListener('input', renderResults); + input.addEventListener('keydown', event => { + if (event.key === 'Escape') { event.preventDefault(); searchDialog.close(); return; } + if (event.key === 'ArrowDown' || event.key === 'ArrowUp') { + event.preventDefault(); selectResult(selected + (event.key === 'ArrowDown' ? 1 : -1)); + } + if (event.key === 'Enter' && matches[selected]) location.href = root + matches[selected].url; + }); + if (!/Mac|iPhone|iPad/.test(navigator.platform)) $$('[data-shortcut]').forEach(kbd => kbd.textContent = 'Ctrl K'); + document.addEventListener('keydown', event => { + const typing = event.target.closest('input,textarea,[contenteditable=true]'); + if (((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') || (event.key === '/' && !typing && !event.ctrlKey && !event.metaKey)) { + event.preventDefault(); openSearch(); + } + if (event.key === 'Escape' && sidebar.classList.contains('open')) { + setMenu(false); menu.focus(); + } + if (event.key === 'Tab' && sidebar.classList.contains('open')) { + const links = [...sidebar.querySelectorAll('a')]; + if (event.shiftKey && document.activeElement === links[0]) { event.preventDefault(); menu.focus(); } + else if (!event.shiftKey && document.activeElement === links.at(-1)) { event.preventDefault(); menu.focus(); } + else if (document.activeElement === menu) { event.preventDefault(); (event.shiftKey ? links.at(-1) : links[0]).focus(); } + } + }); + + const imageDialog = $('#image-dialog'); + $$('figure img').forEach(image => { + const button = document.createElement('button'); + button.type = 'button'; + button.setAttribute('aria-label', '放大查看:' + image.alt); + image.replaceWith(button); button.append(image); + button.addEventListener('click', () => { + const preview = imageDialog.querySelector('img'); + preview.src = image.currentSrc || image.src; preview.alt = image.alt; + imageDialog.querySelector('p').textContent = image.closest('figure').querySelector('figcaption')?.textContent || image.alt; + imageDialog.showModal(); + }); + }); + $('#close-image').addEventListener('click', () => imageDialog.close()); + imageDialog.addEventListener('click', event => { if (event.target === imageDialog) imageDialog.close(); }); + + $$('.platform-tabs').forEach((group, groupIndex) => { + const tabs = [...group.querySelectorAll('[data-platform]')]; + const panels = [...group.querySelectorAll('.platform-panel')]; + group.querySelector('.platform-tablist').setAttribute('role', 'tablist'); + function choose(position, focus = false) { + tabs.forEach((tab, index) => { + tab.setAttribute('role', 'tab'); tab.id = `platform-${groupIndex}-${index}`; + tab.setAttribute('aria-selected', String(index === position)); tab.tabIndex = index === position ? 0 : -1; + panels[index].hidden = index !== position; + panels[index].id = `platform-panel-${groupIndex}-${index}`; + panels[index].setAttribute('role', 'tabpanel'); panels[index].tabIndex = 0; + panels[index].setAttribute('aria-labelledby', tab.id); tab.setAttribute('aria-controls', panels[index].id); + }); + if (focus) tabs[position].focus(); + } + tabs.forEach((tab, position) => { + tab.addEventListener('click', () => choose(position)); + tab.addEventListener('keydown', event => { + let next; + if (event.key === 'ArrowRight') next = (position + 1) % tabs.length; + if (event.key === 'ArrowLeft') next = (position + tabs.length - 1) % tabs.length; + if (event.key === 'Home') next = 0; + if (event.key === 'End') next = tabs.length - 1; + if (next !== undefined) { event.preventDefault(); choose(next, true); } + }); + }); + choose(0); + }); + + const headings = $$('#article-content h2, #article-content h3'); + const tocLinks = $$('.toc a'); + let scheduled = false; + function onScroll() { + if (scheduled) return; + scheduled = true; + requestAnimationFrame(() => { + let active = headings[0]?.id; + for (const heading of headings) { if (heading.getBoundingClientRect().top <= 145) active = heading.id; } + tocLinks.forEach(link => link.classList.toggle('active', decodeURIComponent(link.hash.slice(1)) === active)); + scheduled = false; + }); + } + addEventListener('scroll', onScroll, { passive: true }); + onScroll(); + $('.back-top').addEventListener('click', () => { scrollTo({ top: 0, behavior: reducedMotion.matches ? 'instant' : 'smooth' }); $('#main').focus({ preventScroll: true }); }); + if (!reducedMotion.matches) { + const observer = new IntersectionObserver(entries => entries.forEach(entry => { + if (entry.isIntersecting) { entry.target.classList.add('revealed'); observer.unobserve(entry.target); } + }), { threshold: 0.08 }); + $$('.feature-card, .hero, figure').forEach(element => observer.observe(element)); + } +})(); diff --git a/docs/site/build.py b/docs/site/build.py new file mode 100644 index 000000000..a298fbd88 --- /dev/null +++ b/docs/site/build.py @@ -0,0 +1,237 @@ +#!/usr/bin/env python3 +"""Build Pebrel's Markdown user guide into a portable, server-free HTML site.""" +from __future__ import annotations + +import argparse +import html +import json +import re +import shutil +from pathlib import Path +from string import Template +from urllib.parse import quote +from xml.sax.saxutils import escape as xml_escape + +import mistune +import palettes +from pygments import highlight +from pygments.formatters import HtmlFormatter +from pygments.lexers import TextLexer, get_lexer_by_name +from pygments.util import ClassNotFound + +HERE = Path(__file__).resolve().parent +REPO = HERE.parent.parent +UPSTREAM = "https://github.com/Kuddev/pebrel" +SITE_VERSION = json.loads((Path(__file__).resolve().parent / "site.json").read_text(encoding="utf-8"))["version"] + + +def plain(text: str) -> str: + return re.sub(r"\s+", " ", html.unescape(re.sub(r"<[^>]+>", " ", text))).strip() + + +def page_url(slug: str) -> str: + return "index.html" if slug == "index" else f"{slug}/index.html" + + +class Renderer(mistune.HTMLRenderer): + def __init__(self, root: str): + super().__init__(escape=False) + self.root = root + self.headings: list[tuple[int, str, str]] = [] + self.ids: dict[str, int] = {} + + def heading(self, text: str, level: int, **attrs) -> str: + label = plain(text) + base = re.sub(r"[^\w\-]+", "-", label.lower()).strip("-") or "section" + count = self.ids.get(base, 0) + self.ids[base] = count + 1 + identity = f"{base}-{count}" if count else base + self.headings.append((level, identity, label)) + return (f'{text}' + f'#\n') + + def link(self, text: str, url: str, title=None) -> str: + if not re.match(r"^[a-z]+:|^//|^#", url): + name, sep, fragment = url.partition("#") + if name.endswith(".md"): + url = self.root + page_url(Path(name).stem) + (sep + fragment if sep else "") + return super().link(text, url, title) + + def block_code(self, code: str, info=None) -> str: + language = (info or "text").split()[0] + try: + lexer = get_lexer_by_name(language) + except ClassNotFound: + lexer = TextLexer() + rendered = highlight(code, lexer, HtmlFormatter(nowrap=True)) + return (f'
{html.escape(language)}' + '
' + f'
{rendered}
\n') + + def block_quote(self, text: str) -> str: + match = re.match(r"

\[!(NOTE|TIP|WARNING|IMPORTANT)\]\s*", text) + if match: + kind = match[1] + title = {"NOTE": "说明", "TIP": "使用提示", "WARNING": "注意", "IMPORTANT": "请先确认"}[kind] + text = "

" + text[match.end():] + return (f'

\n') + return super().block_quote(text) + + def table(self, text: str) -> str: + return '
\n' + text + '
\n' + + +def render_markdown(source: str, root: str) -> tuple[str, Renderer]: + renderer = Renderer(root) + markdown = mistune.create_markdown(renderer=renderer, plugins=["table", "strikethrough", "task_lists", "footnotes"]) + return markdown(source.replace("@ROOT@", root)), renderer + + +def navigation(groups: list[dict], active: str, root: str) -> str: + result = [] + for group in groups: + links = [] + for page in group["pages"]: + current = page["slug"] == active + links.append(f'{html.escape(page["title"])}') + result.append(f'') + return "\n".join(result) + + +def home_header() -> str: + release = f"{UPSTREAM}/releases/latest" + return f'''
+

从一个终端开始。
把工作连成一体。

+
开始使用 下载 Pebrel ↗
+
为你的桌面而来WindowsmacOS PreviewLinux Preview
''' + + +def source_details(page: dict, commit: str) -> str: + commit = page.get("source_commit", commit) + sources = page.get("sources", []) + links = "".join(f'
  • {html.escape(path)}
  • ' for path in sources) + return (f'
    版本与参考 · {commit[:7]}' + f'

    适用版本:Pebrel {html.escape(page.get("version", SITE_VERSION))}。以下链接提供相关设置与功能的参考。

    ') + + +def build(destination: Path, base_url: str) -> dict: + config = json.loads((HERE / "site.json").read_text()) + pages = [dict(page, group=group["title"]) for group in config["groups"] for page in group["pages"]] + slugs = [page["slug"] for page in pages] + if len(slugs) != len(set(slugs)): + raise ValueError("Duplicate page slug") + template = Template((HERE / "template.html").read_text()) + destination = destination.resolve() + screenshots = REPO / "docs" / "screenshots" + if destination != HERE / "dist" and ( + REPO.is_relative_to(destination) + or any( + source == destination + or source.is_relative_to(destination) + or destination.is_relative_to(source) + for source in (HERE, screenshots) + ) + ): + raise ValueError("Output directory overlaps repository sources") + if destination.exists(): + if not destination.is_dir(): + raise ValueError("Output path is not a directory") + generated_site = ( + (destination / "build-info.json").is_file() + and (destination / ".nojekyll").is_file() + ) + if any(destination.iterdir()) and not generated_site: + raise ValueError("Refusing to replace an output directory that is not a generated site") + shutil.rmtree(destination) + destination.mkdir(parents=True, exist_ok=True) + shutil.copy2(REPO / "LICENSE", destination / "LICENSE") + shutil.copy2(HERE / "third-party-notices.txt", destination / "third-party-notices.txt") + assets = destination / "assets" + shutil.copytree(HERE / "assets", assets, dirs_exist_ok=True) + shutil.copy2(REPO / "extra/logo/nebula.png", assets / "pebrel.png") + screenshot_dir = assets / "screenshots" + screenshot_dir.mkdir(exist_ok=True) + shutil.copy2(HERE / "screenshots.json", screenshot_dir / "sources.json") + for filename in config["images"]: + shutil.copy2(REPO / "docs/screenshots" / filename, screenshot_dir / filename) + themes = palettes.load() + (assets / "palettes.css").write_text(palettes.stylesheet(themes), encoding="utf-8") + (assets / "highlight.css").write_text(palettes.code_stylesheet(), encoding="utf-8") + palette_menu, dark_palettes = palettes.menu(themes), palettes.dark_ids(themes) + search = [] + total_characters = 0 + all_markdown = [] + for position, page in enumerate(pages): + slug = page["slug"] + root = "./" if slug == "index" else "../" + source = (HERE / "content" / f"{slug}.md").read_text(encoding="utf-8") + for path in page.get("sources", []): + if not (REPO / path.split("#")[0]).is_file(): + raise ValueError(f"{slug}: unknown evidence source {path}") + content, renderer = render_markdown(source, root) + total_characters += len(plain(content)) + if slug == "index": + header = home_header() + breadcrumb_tools = "" + else: + header = ( + f'

    {html.escape(page["title"])}

    ' + f'

    {html.escape(page["description"])}

    ') + breadcrumb_tools = ( + f'
    ' + f'' + f'Markdown ↓
    ') + header += '' + toc = "".join(f'{html.escape(label)}' for level, identity, label in renderer.headings if level in (2, 3)) + pagination = [] + for offset, label, arrow in [(-1, "上一篇", "← "), (1, "下一篇", "→ ")]: + neighbor = position + offset + if 0 <= neighbor < len(pages): + target = pages[neighbor] + pagination.append(f'{label}{arrow}{html.escape(target["title"])}') + else: + pagination.append('') + canonical = f'' if base_url else "" + output = template.substitute( + description=html.escape(page["description"]), title=html.escape(page["title"]), canonical=canonical, + root=root, slug=slug, version=html.escape(page.get("version", config["version"])), group=html.escape(page["group"]), + navigation=navigation(config["groups"], slug, root), main_class="home" if slug == "index" else "document", + breadcrumb_tools=breadcrumb_tools, page_header=header, content=content, source_details=source_details(page, config["source_commit"]), + palette_menu=palette_menu, dark_palettes=dark_palettes, + pagination="".join(pagination), toc=toc, edit_url=f'{UPSTREAM}/edit/main/docs/site/content/{slug}.md') + target = destination / page_url(slug) + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(output, encoding="utf-8") + (destination / "markdown").mkdir(exist_ok=True) + (destination / "markdown" / f"{slug}.md").write_text(source, encoding="utf-8") + # Each section is independently searchable and links to its own anchor. + parts = re.split(r'(.*?)', content, flags=re.S) + search.append({"title": page["title"], "text": page["description"] + " " + plain(parts[0]), "url": page_url(slug)}) + for i in range(1, len(parts), 2): + identity = re.search(r'id="([^"]+)"', parts[i])[1] + heading = plain(re.sub(r'', '', parts[i], flags=re.S)) + search.append({"title": f'{page["title"]} · {heading}', "text": plain(parts[i + 1]), "url": page_url(slug) + "#" + quote(identity)}) + all_markdown.append(f'# {page["title"]}\n\n{source}') + (destination / "search-index.js").write_text('window.PEBREL_DOCS_SEARCH=' + json.dumps(search, ensure_ascii=False).replace("<", "\\u003c") + ';\n', encoding="utf-8") + (destination / ".nojekyll").touch() + (destination / "llms.txt").write_text('# Pebrel 用户手册\n\n' + '\n'.join(f'- [{page["title"]}]({base_url}markdown/{page["slug"]}.md): {page["description"]}' for page in pages) + '\n', encoding="utf-8") + (destination / "llms-full.txt").write_text('\n\n---\n\n'.join(all_markdown), encoding="utf-8") + (destination / "404.html").write_text(f'未找到页面 · Pebrel
    404 / PEBREL DOCS

    这一页不在这里。

    地址可能已变更。回到文档首页,通过目录或搜索继续查找。

    返回文档首页 →
    ', encoding="utf-8") + if base_url: + (destination / "sitemap.xml").write_text('' + ''.join(f'{xml_escape(base_url + page_url(page["slug"]))}' for page in pages) + '', encoding="utf-8") + stats = {"pages": len(pages), "search_sections": len(search), "text_characters": total_characters, "source_commit": config["source_commit"]} + (destination / "build-info.json").write_text(json.dumps(stats, indent=2) + "\n") + return stats + + +if __name__ == "__main__": + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--output", type=Path, default=HERE / "dist") + parser.add_argument("--base-url", default="", help="Canonical URL, including the repository subpath") + args = parser.parse_args() + url = args.base_url.rstrip("/") + "/" if args.base_url else "" + print(json.dumps(build(args.output.resolve(), url), ensure_ascii=False, indent=2)) diff --git a/docs/site/check_browser.py b/docs/site/check_browser.py new file mode 100644 index 000000000..9387806b4 --- /dev/null +++ b/docs/site/check_browser.py @@ -0,0 +1,115 @@ +"""Exercise the built guide under a repository Pages prefix in a real browser.""" +import argparse +import json +import os +import shutil +import tempfile +from functools import partial +from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from threading import Thread + +from playwright.sync_api import sync_playwright, expect + + +class QuietHandler(SimpleHTTPRequestHandler): + def log_message(self, *args): + pass + + +def check(site: Path, output: Path): + output.mkdir(parents=True, exist_ok=True) + with tempfile.TemporaryDirectory() as temporary: + served = Path(temporary) + shutil.copytree(site, served / 'pebrel') + server = ThreadingHTTPServer(('127.0.0.1', 0), partial(QuietHandler, directory=temporary)) + Thread(target=server.serve_forever, daemon=True).start() + base = f'http://127.0.0.1:{server.server_port}/pebrel/' + errors = [] + try: + with sync_playwright() as playwright: + executable = os.environ.get('CHROMIUM_PATH') + browser = playwright.chromium.launch(executable_path=executable) + context = browser.new_context(viewport={'width': 1512, 'height': 1000}, permissions=['clipboard-read', 'clipboard-write']) + page = context.new_page() + page.on('pageerror', lambda error: errors.append(str(error))) + page.goto(base) + expect(page.locator('h1')).to_contain_text('从一个终端开始') + page.wait_for_timeout(650) + page.screenshot(path=str(output / 'docs-desktop.png'), full_page=True) + page.keyboard.press('Control+k') + page.locator('#search-input').fill('分屏') + expect(page.locator('.search-result').first).to_be_visible() + page.keyboard.press('Enter') + # Search may match a complete guide or a section within it. + expect(page).to_have_url(__import__('re').compile(r'/pebrel/[^#?]+/index\.html(?:#.*)?$')) + expect(page.locator('#article-content h2').first).to_be_visible() + page.keyboard.press('Control+k') + page.locator('#search-input').fill('字体') + page.keyboard.press('Escape') + expect(page.locator('#search-dialog')).not_to_be_visible() + page.goto(base + 'quickstart/index.html') + page.locator('.copy-code').first.click() + expect(page.locator('.copy-code').first).to_have_attribute('data-copied', 'true') + assert 'echo Hello, Pebrel' in page.evaluate('navigator.clipboard.readText()') + page.locator('#theme-toggle').click() + page.locator('[data-palette-option="CatppuccinMocha"]').click() + expect(page.locator('html')).to_have_attribute('data-theme', 'dark') + expect(page.locator('html')).to_have_attribute('data-palette', 'CatppuccinMocha') + page.reload() + expect(page.locator('html')).to_have_attribute('data-theme', 'dark') + expect(page.locator('html')).to_have_attribute('data-palette', 'CatppuccinMocha') + dark_background = page.locator('.code-block').first.evaluate('el => getComputedStyle(el).backgroundColor') + assert all(int(channel) < 128 for channel in __import__('re').findall(r'\d+', dark_background)[:3]) + page.screenshot(path=str(output / 'docs-dark.png'), full_page=True) + page.locator('figure button').first.click() + expect(page.locator('#image-dialog')).to_be_visible() + page.keyboard.press('Escape') + expect(page.locator('#image-dialog')).not_to_be_visible() + page.set_viewport_size({'width': 390, 'height': 844}) + page.goto(base) + page.locator('#theme-toggle').click() + page.locator('[data-palette-option="Nord"]').click() + page.wait_for_timeout(650) + assert not page.evaluate('document.documentElement.scrollWidth > innerWidth') + page.screenshot(path=str(output / 'docs-mobile.png'), full_page=True) + page.locator('#menu-toggle').click() + expect(page.locator('#menu-toggle')).to_have_attribute('aria-expanded', 'true') + page.keyboard.press('Escape') + expect(page.locator('#menu-toggle')).to_have_attribute('aria-expanded', 'false') + manifest = json.loads((Path(__file__).parent / 'site.json').read_text()) + pages = {item['slug']: item for group in manifest['groups'] for item in group['pages']} + for slug in ('completions', 'backups', 'mobile'): + page.goto(base + slug + '/index.html') + version = pages[slug].get('version', manifest['version']) + commit = pages[slug].get('source_commit', manifest['source_commit']) + expect(page.locator('.article-footer')).to_contain_text(version) + page.locator('.source-details summary').click() + expect(page.locator('.source-details a').first).to_have_attribute( + 'href', __import__('re').compile(f"/blob/{commit}/")) + assert not page.evaluate('document.documentElement.scrollWidth > innerWidth') + page.screenshot(path=str(output / f'docs-{slug}-mobile.png'), full_page=True) + page.goto(base) + page.emulate_media(reduced_motion='reduce') + assert page.locator('.hero').evaluate("el => getComputedStyle(el).animationName") == 'none' + nojs = browser.new_context(java_script_enabled=False, viewport={'width': 390, 'height': 844}) + fallback = nojs.new_page() + fallback.goto(base) + expect(fallback.locator('#sidebar')).to_be_visible() + fallback.get_by_role('link', name='快速开始', exact=True).first.click() + expect(fallback.locator('h1')).to_have_text('快速开始') + nojs.close() + browser.close() + finally: + server.shutdown() + server.server_close() + assert not errors, errors + (output / 'browser-result.json').write_text(json.dumps({'passed': True, 'page_errors': errors}, indent=2)) + + +if __name__ == '__main__': + parser = argparse.ArgumentParser() + parser.add_argument('--site', type=Path, default=Path(__file__).parent / 'dist') + parser.add_argument('--output', type=Path, default=Path('docs-browser-results')) + args = parser.parse_args() + check(args.site, args.output) diff --git a/docs/site/content/agent-worktrees.md b/docs/site/content/agent-worktrees.md new file mode 100644 index 000000000..72b95ace1 --- /dev/null +++ b/docs/site/content/agent-worktrees.md @@ -0,0 +1,61 @@ +## 为并行任务使用不同目录 + +两个 AI 工具同时修改同一目录,可能覆盖对方的文件。Git worktree 可以让它们使用同一仓库的不同工作目录与分支。 + +开始前保存当前文件,在源项目中运行 `git status`。先提交或妥善保存未提交改动,再创建新的工作目录。 + +## 使用 Pebrel 创建命名 Agent + +在本地 Pebrel 终端中运行: + +```sh +pebrel pane list +pebrel ctl describe --pretty +``` + +确认源窗格的 ID、所属窗口及当前运行时支持的 Agent 能力。假设窗口为 `1`、源窗格为 `17`,且 Codex 已安装: + +```sh +pebrel ctl agent-fork --window 1 --source-pane 17 --name docs-review --kind codex --pretty +``` + +把数字换成自己的列表结果。成功后,响应会给出创建的 worktree 和 Agent 信息,终端将在新目录中启动相应工具。 + +默认分支形如 `pebrel/docs-review`,工作目录位于主仓库旁的 `<仓库名>-worktrees/docs-review`。同名分支或目录已经存在时,改用新的任务名称,或先确认旧任务已不再使用。 + +## 核对目录再发任务 + +读取新 Agent: + +```sh +pebrel ctl agent-get --agent docs-review --pretty +``` + +检查返回的目录与分支,再发送一项任务: + +```sh +pebrel agent send docs-review "检查安装文档中的路径示例,列出需要修改的位置" --wait +pebrel agent read docs-review --lines 80 +``` + +任务完成后,进入这个 worktree 查看 `git diff`并运行相关检查。再按项目的 Git 工作流程提交和合并。 + +## 只需要手动建立 worktree + +也可以使用 Git 自带命令。在源仓库目录中运行下面的示例,再新建终端进入新目录: + +```sh +git worktree add ../my-project-docs -b docs/review +``` + +该命令会创建一个新分支和目录。检查成功后,在新终端中进入 `../my-project-docs`,启动已安装的 AI CLI。 + +## SSH 上的项目 + +Pebrel 的本机 Agent worktree 创建入口不替远端 SSH 会话建立工作目录。需要在服务器上隔离任务时,在服务器终端中使用它的 Git 命令,并选择服务器可写路径。 + +## 完成后清理 + +确认所有修改已提交或保存,并退出使用该目录的工具。先运行 `git worktree list`核对目录,再用 `git worktree remove 实际目录`移除不再使用的工作副本。 + +不要直接删除仍有未提交改动的目录。对话分叉只复制会话上下文,需要文件隔离时仍按本页建立 worktree。 diff --git a/docs/site/content/agents.md b/docs/site/content/agents.md new file mode 100644 index 000000000..eaf7679c3 --- /dev/null +++ b/docs/site/content/agents.md @@ -0,0 +1,116 @@ +> [!NOTE] +> 本页按 Pebrel 2.1.1 核对。支持范围会随版本变化;如果你安装的版本较旧,设置 → Agents 里列出的工具可能比这里少,请以自己版本的界面为准。 + +## Pebrel 如何对待 AI 命令行工具 + +Claude Code、Codex 这类工具本质上是运行在终端里的程序,所以任何 CLI 或 TUI 都能在 Pebrel 里正常使用,不需要先"被支持"。Pebrel 做的是在此之上多走一步:认出你正在运行的是哪一个工具,再给它配上图标、任务状态、通知和对话接续。 + +这些能力分三层,工具支持到哪一层,你能得到的体验就到哪一层: + +| 层级 | 你会得到什么 | 需要你做什么 | +| --- | --- | --- | +| **识别** | Pebrel 认出工具名称,可显示专属图标 | 不需要,直接运行即可 | +| **屏幕识别** | 在识别的基础上,Pebrel 根据终端画面判断工具是在工作,还是在等你确认 | 不需要 | +| **Agent 集成** | 工具自己把"开始、完成、需要你处理"等事件告诉 Pebrel,状态和通知最准确;还能记住会话,用于恢复与分叉 | Claude Code 和 Codex 默认已开启;其他工具在 **设置 → Agents** 里打开一次 | + +Agent 集成最准确,但并不是所有工具都提供可用的事件接口。没有集成的工具,依然可以靠屏幕识别获得不错的状态提示,只是在工具改了界面措辞之后,判断可能暂时不准。 + +## 支持 Agent 集成的工具 + +**设置 → Agents** 页面里列出的就是下面这 9 个工具,在 Windows、macOS 和 Linux 上都可以使用。Claude Code 和 Codex 默认开启,其余的需要自己打开开关;开启后要退出并重新启动对应的工具才会生效,步骤见[配置 Agent 集成](hooks.md)。 + +服务器上的工具也可以使用:通过 Pebrel 的 SSH 连接时,会自动为服务器上的 Claude Code、Codex、OpenCode 和 Pi 配置集成。WSL 里则支持 Claude Code 和 Codex。 + +| 工具 | 启动命令 | 专属图标 | 恢复对话 | 分叉对话 | +| --- | --- | :---: | :---: | :---: | +| Claude Code | `claude` | ✓ | ✓ | ✓ | +| Codex | `codex` | ✓ | ✓ | ✓ | +| OpenCode | `opencode` | ✓ | ✓ | ✓ | +| Cursor Agent | `agent`、`cursor-agent` | — | ✓ | — | +| Kimi Code | `kimi` | ✓ | ✓ | ✓ | +| Pi | `pi` | ✓ | ✓ | ✓ | +| Oh My Pi | `omp` | ✓ | ✓ | ✓ | +| GitHub Copilot | `copilot` | — | ✓ | — | +| Grok | `grok` | ✓ | ✓ | ✓ | + +几点说明: + +- Cursor Agent 的命令是 `agent`,不是 Cursor 桌面编辑器的 `cursor`。只安装了桌面编辑器时,设置里不会把 Cursor Agent 显示为已安装。 +- 没有专属图标的工具会用字体图标代替:Gemini、Cursor Agent 和 GitHub Copilot 各有自己的图案,其余工具显示通用图标。这不影响状态提示。 +- "恢复"指重新打开 Pebrel 后接回原来的对话,或在 [AI 会话历史](ai-history.md) 里重新打开某次对话。"分叉"指从已有对话的上下文开出一个新对话,原对话保持不变。两者都要求 Pebrel 已经知道这次对话的会话标识,而这正是 Agent 集成带来的。 + +## 通过屏幕识别获得状态提示的工具 + +下面这些工具目前没有 Agent 集成入口,但 Pebrel 能认出它们,并根据画面判断工作中或等待确认。 + +| 工具 | 启动命令 | 专属图标 | +| --- | --- | :---: | +| Gemini CLI | `gemini` | — | +| Amp | `amp` | — | +| Antigravity | `agy`、`antigravity` | ✓ | +| Cline | `cline` | — | +| Devin | `devin` | — | +| Droid | `droid` | — | +| Hermes | `hermes` | — | +| Kiro | `kiro`、`kiro-cli` | — | +| Kilo Code | `kilo` | — | +| Qoder | `qodercli` | — | +| Maki | `maki` | — | +| CodeBuddy Code | `codebuddy`、`cbc` | ✓ | + +这一档的工具不在 Pebrel 里恢复或分叉对话。需要接续时,使用工具自己的恢复命令即可,例如 `gemini --resume`。 + +## 目前只做识别的工具 + +下面这些工具能被认出,但暂时没有屏幕识别规则,也没有集成。任务状态提示比较有限,需要你自己回到窗格查看。 + +| 工具 | 启动命令 | 专属图标 | +| --- | --- | :---: | +| Aider | `aider` | — | +| Goose | `goose` | — | +| Auggie | `auggie` | — | +| Vibe | `vibe` | — | +| Qwen Code | `qwen` | — | +| Trae CLI | `trae-cli` | ✓ | + +## 通过 `npx` 等启动器运行也能识别 + +Pebrel 不只看命令的第一个词。通过 `node`、`npx`、`bunx`、`uvx`、`pipx` 等启动器运行的工具,以及在 WSL 里运行的工具,同样会被认出。 + +如果工具没有被认出,先在同一个终端里确认命令能直接运行,再看[配置 Agent 集成](hooks.md)中的排查步骤。 + +## 名单之外的工具 + +不在上面名单里的 CLI 或 TUI,仍然可以在 Pebrel 里正常运行,只是没有专属图标、任务状态和对话接续,终端本身的所有功能不受影响。 + +## 接下来的方向 + +下面是目前的开发方向,不是发布时间的承诺,具体以各版本的发布说明为准: + +- **补齐集成。** 优先为使用广泛、并且官方提供稳定事件接口的工具增加 Agent 集成,让它们从"屏幕识别"升级到最准确的一档。 +- **扩大恢复和分叉的范围。** 只在工具的官方命令经过核对之后才会加入。Pebrel 不会按名字猜测命令,以免把内容输入到错误的位置。 +- **识别更多工具。** 新工具会根据使用情况和启动方式是否稳定来评估。 + +希望支持某个工具,可以在项目的 Issue 里说明工具名称、启动命令和官方文档链接,流程见[参与贡献](contributing.md)。 + +## 常见问题 + +### 状态没有更新,或图标没有出现 + +先确认命令在同一个终端里能直接运行,再刷新 **设置 → Agents**。已经启用集成的工具,重启一次工具后再试。工具刚升级过时,重新启动 Pebrel 和工具可以清掉旧的识别状态。 + +### 在标签上怎么看状态 + +工作中的标签会显示转动的进度标记。工具停下来等你输入或授权时,标签会改为相应的提示。任务完成时,标签先短暂显示对勾,再变成一个小圆点,提醒你回去查看;正在查看的标签不会显示这个小圆点。详见[使用 AI 命令行工具](ai-start.md)。 + +### 通知来自哪个窗格 + +通知会指向发出事件的窗格。多个工具同时运行时,请按窗格上的图标和名称区分,通知方式见[通知](notifications.md)。 + +### 设置里没有我的工具 + +**设置 → Agents** 只列出有 Agent 集成的 9 个工具。其他工具没有开关,但仍会被识别,并显示图标和状态提示。 + +### 恢复或分叉没有出现 + +先看工具是否在上面"支持 Agent 集成"的表里且有 ✓,再检查集成是否已启用并重启过工具。SSH 标签和自定义 Profile 里不会显示分叉入口,详情见[恢复与分叉 AI 对话](ai-history.md)。 diff --git a/docs/site/content/ai-history.md b/docs/site/content/ai-history.md new file mode 100644 index 000000000..1fbd8ccc9 --- /dev/null +++ b/docs/site/content/ai-history.md @@ -0,0 +1,54 @@ +## 找到之前的对话 + +按 **Ctrl+Shift+O**(macOS 为 **⌘⇧O**)打开快速跳转,输入会话标题、项目目录或相关关键字。列表按工具分组,同一次对话可能列出两种操作:**恢复**会接回原对话,**分叉**(仅部分工具提供)会从原对话的上下文开出新对话。每一行会显示工具名称、位置和时间,先核对工具类型和目录,再选择。 + +Pebrel 会尝试使用工具的会话记录打开对话。CLI 出现后,确认上下文确实属于原任务,再输入新的问题。 + +历史列表会读取 Claude Code 和 Codex 自己保存的会话记录;其他已启用 Agent 集成的工具,会在它们上报会话之后出现在列表里。没有集成的工具,请通过工具自己的恢复入口打开。各工具是否支持恢复与分叉,见[支持的 AI 命令行工具](agents.md)。 + +## 每次启动时自动接续 + +在 **设置 → 高级 → 会话生命周期**开启: + +- **启动时恢复上次标签**; +- **恢复时接续 AI 对话**。 + +正常退出后重开 Pebrel,检查对应终端是否恢复了原对话。需要原会话记录、有效的身份信息,以及可用的 CLI 安装。 + +关闭 Pebrel 时,如果还有 AI 对话没有取得身份信息,会弹出"仍有 AI 会话未能识别,继续关闭?"。选择 **保存已知状态并关闭** 会保存布局和已知的对话;没取得身份的对话,下次打开时可能需要手动选择。刚启动的工具需要一点时间取得身份,等它们启动完成后再关闭,可以避免这个提示。 + +能否自动接回,取决于工具是否在[支持列表](agents.md)里有"恢复对话"的 ✓。 + +## 恢复失败或需要选择会话 + +原对话没能接上时,Pebrel 会保留原来的恢复记录,不会丢掉。右键相关终端标签,使用当前可用的 **重试会话恢复** 或 **选择要继续的对话…**。 + +先检查项目目录是否仍存在、CLI 是否需要重新登录,以及原工具的历史记录是否还在。记录不足时,可以打开工具自己的历史选择器查找;Pebrel 列表没有显示某条记录,并不意味着工具已经删除它。 + +## 从已有上下文分出新对话 + +在受支持的本地会话中,右键标签选择 **分叉 AI 会话**;也可以在历史列表里,对某次旧对话选择 **分叉**。目前 Claude Code、Codex、OpenCode、Kimi Code、Pi、Oh My Pi 和 Grok 可以分叉。新会话从已有上下文开始,原对话继续保留。 + +这个入口要求 Pebrel 已识别工具和会话身份;SSH、自定义 Profile 或身份信息不完整时可能不显示。需要分叉时,先在受支持的本地 Shell 中建立会话。 + +对话分叉沿用上下文,但不会自动给代码建立独立工作目录。准备并行修改文件时,使用[Git worktree](agent-worktrees.md)。 + +## 使用已知会话 ID + +已经从工具取得有效 ID 时,也可以在相应环境中运行它的恢复命令。将 `SESSION_ID`换成真实值: + +```sh +claude --resume SESSION_ID +``` + +或: + +```sh +codex resume SESSION_ID +``` + +安装的 CLI 版本需要支持相应命令。CLI 报参数错误时,先查看该版本的帮助,而不是反复尝试同一命令。 + +## 备份对话 + +保存 Pebrel 布局或主机列表不会同时备份所有 CLI 的对话正文。换电脑或清理历史前,按工具自己的方式备份会话记录,并保留对应项目目录。 diff --git a/docs/site/content/ai-start.md b/docs/site/content/ai-start.md new file mode 100644 index 000000000..93194f7b8 --- /dev/null +++ b/docs/site/content/ai-start.md @@ -0,0 +1,43 @@ +## 在项目目录启动工具 + +先按所用 CLI 的官方说明安装并登录。Claude Code、Codex 等工具分别管理自己的账户与网络连接,Pebrel 提供运行它们的终端。Pebrel 目前能识别的工具见[支持的 AI 命令行工具](agents.md)。 + +1. 打开本地、WSL 或 SSH 终端。 +2. 用 `cd`进入准备处理的项目。 +3. 输入已安装的工具命令,例如 `claude`或 `codex`。 +4. 按工具提示完成登录和目录信任确认。 +5. 输入第一项任务,例如“介绍这个项目的目录结构,先不要修改文件”。 + +命令找不到时,在同一环境中检查安装。Windows 中安装的 CLI,不会自动变成 WSL 或服务器中的 Linux 程序。 + +
    Pebrel 分屏中运行多个 AI 命令行工具
    为不同任务使用独立窗格,可以同时查看各工具的输出。
    + +## 查看活动状态 + +Pebrel 会给识别到的 AI CLI 显示工具图标和活动状态:标签和窗格标题上有工具图标,工作中的标签会转动,任务完成后先显示对勾,再变成小圆点。运行任务时可以切到其他标签,通过状态提示判断何时需要回来查看。 + +在 **设置 → Agents** 启用支持的集成,可以获得更准确的任务事件。哪些工具能被识别、各自有哪些功能,见[支持的 AI 命令行工具](agents.md);配置方式见[Agent 集成](hooks.md)。 + +出现需要权限、回答或确认的提示时,回到来源窗格阅读具体请求。任务回到空闲后,仍应查看工具输出和实际改动,确认结果符合需求。 + +## 将报错或截图加入对话 + +从终端选择报错文字,右键使用 **发送到聊天**,补充问题并选择目标工具。这样无需手动整理全部日志,见[发送到聊天](send-to-chat.md)。 + +工具支持图片输入时,复制截图并在其窗格中粘贴。Pebrel 会保存或上传图片并插入路径,随后按 CLI 的方式提交,见[图片](images.md)。 + +## 阅读较长的回答 + +可以直接在 CLI 中滚动和复制回答。需要按标题阅读长结果时,将回答保存为本地 `.md`文件,再从文件树打开,使用[文档阅读器](documents.md)的目录、代码复制和公式排版。 + +这套方式也适用于暂时没有集成事件的工具:保留原始 Markdown 内容,就能在文档标签中阅读。 + +## 同时处理多个任务 + +为不同任务新建窗格,先进入各自的项目目录,再启动 CLI。需要并行修改同一个 Git 仓库时,用独立 worktree 隔离文件,避免两个工具同时覆盖同一路径,见[隔离 AI 工作目录](agent-worktrees.md)。 + +每项任务结束后,查看版本控制面板中的 diff,运行相应测试,再决定是否提交。 + +## 退出后继续对话 + +用工具自己的退出方式结束会话。之后从[AI 会话历史](ai-history.md)查找;希望启动 Pebrel 时自动接续,可开启 **启动时恢复上次标签**和 **恢复时接续 AI 对话**。 diff --git a/docs/site/content/appearance.md b/docs/site/content/appearance.md new file mode 100644 index 000000000..8cb4cc5a0 --- /dev/null +++ b/docs/site/content/appearance.md @@ -0,0 +1,35 @@ +## 更换主题 + +打开 **设置 → 外观**,点击 **更换主题**。浏览或搜索主题,选择喜欢的配色,回到终端查看实际效果。 + +希望随系统切换深浅色时,开启 **跟随系统**,深色使用 Nord,浅色使用 Nord Light。希望始终使用固定配色时,关闭它,再选择主题。主题列表里的 Warm Sand、Slate Light 分别是原来的 Paper 与 Glass Light,旧配置中的名称仍然有效。 + +
    Pebrel 的主题配色示例
    选择主题后,可继续调整终端字体、光标和背景。
    + +## 调整界面大小 + +在 **外观 → 界面**中,**界面字号**用于设置侧栏、按钮和菜单的文字大小,**界面外观**用于选择“标准”或“紧凑”的留白,切换后标题栏、侧栏和顶部标签的间距立即改变。侧栏的分隔线默认就可以拖动调整宽度。 + +终端输出太小时,调整 **终端字号**。希望一屏显示更多内容但仍容易阅读,可以先调整终端字号和字体间距,再决定是否缩小整个界面。 + +## 更换应用图标 + +点击 **更换图标**,查看并选择图标配色。图标与主题分别保存,切换终端主题不会强制改变图标。 + +应用内已经改变,但任务栏、Dock 或系统文件管理器仍显示旧图标时,可以退出并重开应用;系统图标缓存的刷新可能较晚。 + +## 更容易看清当前窗格 + +在外观的界面选项中开启非活动窗格调暗,让当前输入位置更明显。使用多个本地和 SSH 窗格时,可以结合[标签颜色与重命名](workspace.md)区分环境。 + +在 **光标**分组中选择条形、下划线、实心框或空心框。关闭 **光标闪烁**后,光标保持常亮。**平滑光标**可选 **关闭** 或 **平滑(90 ms)**,开启后输入和移动时光标会平滑滑动,大范围跳转仍立即到位,设置立即应用到已打开的终端。 + +## 标签关闭按钮与界面语言 + +**显示标签关闭按钮**控制标签上的关闭入口。关闭显示后,仍可使用鼠标中键、右键菜单或关闭快捷键。 + +在 **语言**选项中选择界面语言。终端程序的输出由各自的环境设置决定;未翻译的界面文字可能使用英文。 + +## 进一步定制 + +需要改文字颜色、ANSI 调色板或行高,见[创建和导入主题](themes.md)。需要调整中英文字体和连字,见[字体](fonts.md)。使用壁纸、透明度或窗口材质,见[背景](backgrounds.md)。 diff --git a/docs/site/content/backgrounds.md b/docs/site/content/backgrounds.md new file mode 100644 index 000000000..a9f580430 --- /dev/null +++ b/docs/site/content/backgrounds.md @@ -0,0 +1,38 @@ +## 设置一张背景图片 + +1. 打开 **设置 → 外观 → 自定义背景**。 +2. 在 **背景图片**中选择本机图片文件。 +3. 设置 **背景图像拉伸模式**和 **背景图像对齐**。 +4. 调低 **背景图像不透明度**,让文字不被图片干扰。 +5. 回到终端检查普通输出、彩色输出和选区的清晰度。 + +图片默认位于终端文字后方。要将图片延伸到标题栏和侧栏,开启相应的覆盖选项,并阅读确认提示。 + +## 选择铺放方式 + +| 模式 | 效果 | 适合的情况 | +| --- | --- | --- | +| **拉伸** | 铺满区域,可能改变图片比例 | 纹理或不怕变形的图案 | +| **适应** | 保持比例,完整显示,可能留空 | 希望看见整张图片 | +| **填充** | 保持比例铺满,可能裁剪边缘 | 壁纸铺满终端 | +| **原始尺寸** | 不缩放图片 | 按原图尺寸放置 | + +主体被裁掉时,在九个对齐位置中选择顶部、左侧、居中等位置,再调整窗口大小查看结果。 + +## 调整图片与终端透明度 + +**背景图像不透明度**越低,图片越淡。**终端正文不透明度**控制终端背景整体的不透明程度,100% 为完全不透明。 + +两者可以分别调整。例如,希望有一张浅淡壁纸、但不透出桌面,可以降低图片不透明度,同时把终端正文不透明度保持为 100%。设置页本身不会按终端正文透明度变化。 + +## 选择背景模糊 + +在 **外观 → 界面 → 背景模糊**中选择当前平台可用的窗口效果。Mica、Aero 和 Acrylic 等效果依赖 Windows 与系统环境,不同系统不会呈现完全相同的材质。 + +出现闪烁、文字难读或窗口拖动不流畅时,先选择“无”并提高不透明度,再逐项恢复效果。 + +## 更换或移除图片 + +重新选择其他图片可以替换背景;需要回到纯色效果时,点击 **背景图片**行的重置按钮移除图片,再选择主题背景色。 + +图片被移动、所在磁盘未挂载或路径失效时,重新选择可读取的文件。迁移到另一台电脑时,把图片素材单独复制过去,并更新路径。 diff --git a/docs/site/content/backups.md b/docs/site/content/backups.md new file mode 100644 index 000000000..2aa4441f7 --- /dev/null +++ b/docs/site/content/backups.md @@ -0,0 +1,68 @@ +> [!NOTE] +> 本页按 Pebrel 2.1.1 核对,**设置 → 备份** 从 2.0 起提供。没有这个入口时,先[更新](updates.md)到 2.0 之后的版本,或使用[备份与迁移](migration.md)中的手动方式。 + +## 先做一份本地加密备份 + +1. 准备一个已有文件夹,例如 U 盘、已挂载的 NAS 或自己的备份目录。 +2. 打开 **设置 → 备份**,在 **备份与恢复** 页面选择 **本地 / 网络目录**,点 **下一步**。 +3. 在 **目录** 中填写路径,或用 **浏览…** 选择文件夹,点 **检查连接并继续**。 +4. 设置至少 8 位的 **备份密码**,在 **再输入一次** 中确认,点 **下一步**。 +5. 勾选需要的内容,点 **完成并开始备份**。只想先保存配置时,选 **完成,稍后备份**。 +6. 等待完成提示,并确认页面出现备份记录;以后使用 **立即备份 → 开始备份** 再生成快照。 + +连接检查只列出已有备份,不写入文件。因此“连接正常”不等于已经成功写入备份,仍需完成第 6 步。 + +**备份密码与存储服务的登录密码是两回事。** Pebrel 只在本次运行的内存中保留备份密码,下次启动后需要重新输入。恢复时必须使用创建那份备份时的密码;忘记密码就无法解开已有备份,请单独妥善保管。 + +## 选择要带走的内容 + +默认推荐外观、终端设置、助手设置、SSH 主机和工作区会话。还可以按需选择同步设置、自定义字体、目录历史和命令历史;每次备份前都能调整,至少选择一项。 + +- **工作区会话**是窗口、标签和分屏布局,不是正在运行的进程或 AI CLI 对话正文 +- **SSH 主机**包含连接配置,不包含 SSH 私钥,也不会复制系统凭据管理器中的密码或 API Key +- **目录历史**可能包含项目路径;**命令历史**可能包含曾经粘贴的令牌,分享或上传前应检查是否真的需要 +- **自定义字体**会增加备份大小;外部项目文件和各 AI CLI 自己的数据仍需另外备份 + +加密并不等于脱敏。自己写进配置或命令中的秘密仍需检查,不要把备份文件和它的密码一起公开。 + +## 导出文件,迁移到另一台电脑 + +在备份页的 **文件** 区域选择 **导出备份文件**,选择内容和保存位置,生成 `.pebrel-backup` 文件。首次配置向导也提供导出入口,因此只做一次离线备份不必配置云存储。 + +把文件安全地复制到新电脑,并准备创建该文件时使用的备份密码。 + +如果新电脑还停在首次配置向导,先按上面的步骤配置一个已有本地文件夹,选择 **完成,稍后备份**。当前界面的导入入口位于配置完成后的页面,不需要为导入额外开通远程存储。 + +## 只恢复需要的部分 + +1. 从已有快照选择恢复,或在 **文件 → 导入备份文件 → 选择文件…** 中打开 `.pebrel-backup`。 +2. 按提示输入该备份的密码并点 **解开**;如果本次运行已有可用密码,可能直接显示内容。 +3. 检查内容清单,只勾选需要恢复的项目,再确认恢复。 +4. 检查外观、主机和配置,新建终端验证 Shell 与路径;跨系统迁移还需修正旧电脑的路径。 + +**恢复会覆盖本机对应的设置,未勾选的内容不变。** 开始前 Pebrel 会把当前相关文件加密保存为恢复点;恢复完成后可在当前设置页面使用 **撤回**。需要撤回时应先执行并确认结果,不要假设关闭设置页或重启后仍保留同一个撤回入口。 + +SSH 私钥、系统凭据、Shell 和 CLI 安装不会由布局备份恢复,需要在新电脑另外准备。完整迁移检查见[备份与迁移](migration.md)。 + +## 使用远程存储 + +存储向导还支持 WebDAV、S3 兼容存储与 SFTP。准备自己的服务地址和权限,按页面要求填写,再检查连接: + +- **WebDAV**:使用已有目录的完整 HTTPS 地址;服务要求应用专用密码时,不要填普通登录密码 +- **S3**:填写服务提供的端点、存储桶、区域和访问凭据 +- **SFTP**:选择已经保存的 SSH 主机和已有远程目录,沿用该主机的认证配置 +- **本地 / 网络目录**:使用已经挂载的目录;选择同步盘时,文件的后续云同步由该同步客户端处理 + +WebDAV / S3 的凭据管理器保存目前仅在 Windows 实现。macOS / Linux 需要在启动 Pebrel 的环境中提供 `PEBREL_BACKUP_WEBDAV_PASSWORD` 或 `PEBREL_BACKUP_S3_SECRET`,并将界面的存储密码输入留空。不要把实际秘密写进公开脚本或截图;不方便配置启动环境时,先使用本地文件夹或离线导出。 + +存储位置按最近 10 份快照保留,成功上传后会尝试清理更旧的快照;清理失败会显示提示,不等于这次上传失败。需要长期保存的一份应另外导出保管。更改存储位置后,页面只列出新位置中的备份,旧位置的备份不会随切换而删除。 + +## 常见问题 + +| 现象 | 下一步 | +| --- | --- | +| 解不开备份 | 确认使用的是这份备份的加密密码,而不是网盘或 SSH 密码 | +| 检查连接通过但备份失败 | 核对目录写权限、空间及实际错误;只读连接检查不能证明上传成功 | +| 找不到导入按钮 | 首次向导先完成本地目录配置,再到文件区域导入 | +| 新电脑的 SSH 仍无法登录 | 重新配置私钥和系统凭据,检查用户名和服务器授权 | +| 恢复后程序或项目路径失效 | 修正跨电脑、跨系统路径,再新建终端验证 | diff --git a/docs/site/content/broadcast.md b/docs/site/content/broadcast.md new file mode 100644 index 000000000..597cefa88 --- /dev/null +++ b/docs/site/content/broadcast.md @@ -0,0 +1,28 @@ +## 同时向多个窗格输入 + +广播输入适合在多个终端中执行相同的查询,例如同时检查几台测试服务器的系统版本。开启后,同一终端标签页里的多个窗格会接收相同的键盘输入。 + +## 开启广播 + +1. 在一个标签页中建立至少两个终端窗格。 +2. 分别连接需要的主机,或切换到准备操作的目录。 +3. 检查每个窗格都停在可以接收命令的位置。 +4. 点击窗格标题栏中的广播输入按钮。 +5. 先输入一条无副作用的测试命令,例如 `echo broadcast-test`,确认各窗格都收到了它。 + +之后输入的字符和提交操作会同步到该标签的窗格。其他标签页不属于这次广播范围。 + +## 只在一个窗格继续操作 + +再次点击广播按钮,将其关闭。检查广播状态已取消后,再输入只针对一台主机的命令。 + +切换焦点只是更换当前窗格;需要结束同步输入时,应明确关闭广播,而不是只点击另一个窗格。 + +> [!WARNING] +> 广播开启时,输入密码、删除命令或生产环境操作可能同时发送给多个会话。开始单独认证、使用交互式菜单或处理不同环境前,先关闭广播。 + +## 图片粘贴 + +图片粘贴需要为目标环境保存或上传文件,不会按普通文本广播给所有窗格。需要给某个 AI 工具提供图片时,关闭广播,聚焦该工具所在窗格后单独粘贴。 + +广播中的某个程序已经退出或进入其他输入状态时,也先暂停广播,分别整理各窗格,再继续操作。 diff --git a/docs/site/content/clipboard.md b/docs/site/content/clipboard.md new file mode 100644 index 000000000..6acff324a --- /dev/null +++ b/docs/site/content/clipboard.md @@ -0,0 +1,42 @@ +## 选择终端输出 + +拖动鼠标选择一段文字;双击可选择一个词,三击可选择一行。按住 **Shift** 可以扩展已有选区。 + +Vim 等程序可能接管鼠标。需要复制它显示的文字时,按住 **Shift** 再拖动,使用终端自身的选区。 + +## 复制和粘贴文字 + +| 操作 | Windows / Linux | macOS | +| --- | --- | --- | +| 复制选区 | Ctrl+Shift+C | ⌘C | +| 粘贴剪贴板 | Ctrl+V 或 Ctrl+Shift+V | ⌘V | + +Windows / Linux 中,Ctrl+C 在存在选区时也会复制文字;没有选区时,它用于中断正在运行的程序。 + +粘贴前点击目标窗格。准备把命令发到服务器时,先确认焦点确实在对应 SSH 终端。 + +## 选中即复制和右键粘贴 + +打开 **设置 → 交互 → 鼠标与选区**,开启 **选中即复制**。之后鼠标选择结束时会复制选区,右键可以粘贴。需要使用常规右键菜单时,将这项设置关闭,右键会打开菜单,里面有复制、粘贴、复制工作目录、左右分屏、上下分屏和关闭此分栏;选中了文字并且有可用的 AI 窗格时,还会出现发送到聊天。无论这项设置是否开启,按住 **Ctrl** 再右键都可以打开这个菜单,同时不影响程序自己接收鼠标事件。 + +这个选项适合频繁从日志中复制文字;如果经常需要右键选择其他动作,保留默认交互会更方便。 + +## 粘贴多行命令 + +在 **设置 → 交互**开启 **粘贴前确认**。在普通 Shell 中粘贴多行或高风险内容时,检查确认框里的文本,再决定是否继续。 + +确认时留意三个位置:当前主机、当前目录,以及命令是否包含删除、提权或覆盖操作。多行文本送入 Shell 后,换行可能触发执行。 + +全屏程序和使用 bracketed paste 的程序会按各自的粘贴方式处理输入;不要把确认框当成所有应用都必定显示的步骤。 + +## 粘贴图片 + +复制一张图片后,在目标终端执行粘贴。Pebrel 会将图片保存为 PNG,再插入对应文件路径。检查输入区中的路径,按正在使用的工具要求提交。 + +在 WSL 或 SSH 中,路径需要指向该环境可访问的图片。SSH 传图依赖远端连接和传输成功;失败时先处理提示,再重试。图片是否显示为附件缩略图由接收的 CLI 决定。 + +关于图片预览、终端内嵌图像及清理缓存,见[图片](images.md)。 + +## 将输出交给 AI + +选择报错或日志,右键打开 **发送到聊天**,再选择目标 AI 窗格。这样可以直接携带选中的输出继续提问。具体示例见[发送到聊天](send-to-chat.md)。 diff --git a/docs/site/content/commands.md b/docs/site/content/commands.md new file mode 100644 index 000000000..ea43df9eb --- /dev/null +++ b/docs/site/content/commands.md @@ -0,0 +1,47 @@ +## 打开保存命令 + +点击工作区顶栏的**闪电图标**打开命令管理器。先点击准备接收命令的终端窗格,再打开管理器;选中的条目会发送到这个终端。 + +搜索框可以查找命令名称或命令文字。列表同时提供内置条目和你自己保存的条目。 + +## 保存第一条命令 + +例如,把检查 Git 工作区状态的命令保存下来: + +1. 点击 **新增命令**。 +2. **名称**填写“查看项目改动”。 +3. **命令**填写 `git status --short`。 +4. 暂时不勾选 **插入后立即按 Enter 执行**。 +5. 点击 **保存**。 + +回到一个 Git 项目的终端,再次打开管理器并选择这条命令。文字会插入输入区,你可以先检查目录,再按 Enter 执行。 + +## 插入文字,还是立即执行 + +| 使用方式 | 适合的条目 | +| --- | --- | +| 不勾选立即执行 | 需要补充参数、路径或检查后再运行的命令 | +| 勾选 **插入后立即按 Enter 执行** | 不需要补充参数的常用命令 | + +开启立即执行时,选择条目会同时发送回车。多行条目会将各非空行整理后用 `; ` 连接再执行;需要保留原始换行的脚本,请保存成脚本文件,或关闭立即执行后按目标程序的要求处理。 + +> [!WARNING] +> 开启立即执行的命令会在当前终端直接运行。对删除、部署或生产环境命令,建议保留插入后确认的方式。 + +## 用分组整理命令 + +点击 **新建分组**并输入名称,例如“项目开发”或“服务器维护”。打开命令条目的菜单,使用 **移到分组**选择目标分组。 + +进入一个分组后,可以使用 **返回全部命令**查看完整列表。将条目移出分组时选择 **移出分组**。选择 **删除分组,保留其中的命令**只会移除分组,命令仍可在列表中找到。 + +## 修改内置命令 + +内置命令提供 Git、Docker、Python 和常见开发工具的示例。要调整其中的参数,打开条目菜单,选择 **保存副本**,然后编辑自己的副本。 + +内置条目会根据当前终端环境筛选。使用前仍需在这个环境中安装相应工具,例如 Docker 命令需要 Docker 可用。 + +## 编辑和删除 + +从自己的命令条目菜单打开 **编辑命令**,修改名称、内容或执行方式后保存。删除不再使用的条目前,确认选中的是自己的那一条。 + +密码、Token 和临时验证码应在终端或凭据提示中输入,不要长期放进命令条目。迁移命令库时,见[备份与迁移](migration.md)。 diff --git a/docs/site/content/completions.md b/docs/site/content/completions.md new file mode 100644 index 000000000..031a1fc17 --- /dev/null +++ b/docs/site/content/completions.md @@ -0,0 +1,56 @@ +> [!NOTE] +> 本页按 Pebrel 2.1.1 核对,智能补全从 2.1.0 起提供。1.9.x 的补全样式和接受键与这里不同;如果界面没有三个模式,先在设置中核对版本,不要照着新界面寻找旧版没有的选项。 + +## 打开命令补全 + +在 **设置 → 终端 → 补全** 开启 **启用命令补全**,再选择 **补齐模式**。回到普通 Shell 提示符,输入命令或路径的开头。切换模式会立即作用于已经打开的终端。 + +候选既可以来自已执行的历史命令,也可以来自当前环境,例如 Git 分支、项目脚本和文件路径。第一次输入命令也可能出现建议,不必先运行一遍;这些补齐不需要请求 AI 服务或安装 Shell 补齐插件。 + +## 选择模式与接受建议 + +| 模式 | 显示方式 | 如何填入 | +| --- | --- | --- | +| **行内补齐** | 建议以灰字接在光标后 | 按 Tab 接受灰字 | +| **列表补齐** | 随输入显示候选列表 | 上下方向键选择,Tab 填入;没有选中项时 Tab 接受第一项 | +| **混合补齐** | 默认显示灰字;Tab 展开列表 | 右方向键接受灰字;列表中用上下方向键选择、Enter 填入 | + +列表打开时可按 Esc 关闭。混合模式的 Tab 用于打开列表或移动选择,不是直接执行命令。 + +**接受建议只填入文字,不执行命令。** 检查完整命令、路径和目标主机,再按 Enter 执行。尤其在混合模式里,第一次 Enter 可能只是接受选中的候选,不要连续按键而跳过检查。 + +当前界面由模式决定按键,不再单独提供“补全接受键”选择。需要完全使用 Shell 自己的补全时,关闭 Pebrel 的 **启用命令补全**。 + +## 试用不依赖历史的补齐 + +先进入已有的本地项目目录。在命令末尾保留表中的空格,再输入部分名称。下面是输入前缀,不是要求直接执行的完整命令: + +| 输入前缀 | 预期候选 | 没有候选时先确认 | +| --- | --- | --- | +| `git switch ` | 当前仓库可用的分支 | 当前目录属于 Git 仓库,且确实有可切换分支 | +| `npm run ` | 项目 `package.json` 中的脚本名 | 最近的项目清单存在有效的 `scripts` | +| `ssh ` | SSH config 中可用的主机别名 | 本机 `~/.ssh/config` 中配置了具体的 Host 名称 | +| `wsl -d ` | 已注册的 WSL 发行版 | 在 Windows 本地 Shell 中输入,且已安装发行版 | +| `cat ` | 当前目录的文件 | 文件存在,当前 Shell 支持该命令;cmd 可使用 `type ` | + +`ssh -F config ` 会使用指定配置文件中的别名;它与 Pebrel 主机库中保存的显示名称不是同一来源。相关设置见 [SSH config](ssh-config.md)。 + +文件名含空格时,接受后检查引号是否覆盖完整路径。不要把候选中存在某个命令理解为已经安装了该程序;例如补齐 npm 脚本不会替你安装 Node.js,也不会运行脚本。 + +## 历史补齐与环境边界 + +运行一次无副作用的 `echo deployment finished`,等提示符返回后输入 `echo dep`,可以检查历史建议。历史补齐是复用已执行的命令;项目补齐则依据当前仍然存在的候选,已经删除的脚本或分支不会仅因出现过而重新成为有效项目候选。 + +本机 Git、项目脚本、SSH 别名和 WSL 发行版发现用于本地 Shell;不要期待它们读取 SSH 服务器或 WSL 项目中的同名文件。WSL、SSH 的路径建议取决于对应会话的目录查询能力,历史也按环境区分,不应拿宿主机路径来判断远端补齐。 + +Vim、全屏程序或正在运行的 AI CLI 有自己的按键行为。检查 Pebrel 补齐时,先回到普通 Shell 提示符。 + +## 排查没有建议或建议不对 + +1. 确认 **启用命令补全** 已打开,输入位置确实是 Shell 提示符。 +2. 用 `pwd`(cmd 使用 `cd`)确认当前目录;Git 和脚本候选需要对应项目上下文。 +3. 区分本地、WSL 和 SSH 窗格,按上面的环境边界检查候选来源。 +4. 用 `echo` 示例区分历史补齐问题与项目候选问题。 +5. 出现两套重复建议时,关闭 Pebrel 补齐或 Shell 插件中的一套再比较。 + +反复使用且不适合依赖历史的长命令,可以存入[保存命令](commands.md)。 diff --git a/docs/site/content/config-examples.md b/docs/site/content/config-examples.md new file mode 100644 index 000000000..c6a212767 --- /dev/null +++ b/docs/site/content/config-examples.md @@ -0,0 +1,104 @@ +## 在已有配置中加入示例 + +以下完整示例可单独用于一份 `pebrel.lua`。已经有配置时,只复制需要的赋值,并放在已有的 `return config`之前,不要重复创建多份配置对象。 + +修改后运行 `pebrel config check`。字段检查通过后,再新建终端验证启动相关设置。 + +## 字体、背景与回滚历史 + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +config.font = { + normal = { family = 'Maple Mono NF CN', style = 'Regular' }, + size = 13.0, +} +config.window = { + opacity = 0.96, + padding = { x = 8, y = 8 }, +} +config.scrolling = { history = 10000 } + +return config +``` + +将字体名称改为当前电脑可用的字体。不透明度范围为 0–1,1 表示完全不透明。GUI 中已有相关偏好时,也检查 **设置 → 外观**是否覆盖了期望效果。 + +## 不同系统选择不同 Shell + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +if pebrel.platform.os == 'windows' then + config.terminal = { + shell = { program = 'pwsh.exe', args = { '-NoLogo' } }, + } +else + config.terminal = { shell = '/bin/bash' } +end + +return config +``` + +该例要求 Windows 已安装 PowerShell 7,其他系统存在 `/bin/bash`。程序路径与参数分开填写;需要选择 WSL 或已识别 Shell 时,日常使用可以直接在 **设置 → 终端**中选择。 + +## 为新终端设置环境变量 + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +config.env = { + EDITOR = 'nvim', + MY_PROJECT_ENV = 'development', +} + +return config +``` + +新建终端后,PowerShell 使用 `$env:MY_PROJECT_ENV`,Bash / Zsh 使用 `echo "$MY_PROJECT_ENV"`检查变量。 + +这些变量适合编辑器和项目标记,不适合写入准备公开分享的密钥或 Token。 + +## 单独保存配色模块 + +在主配置旁建立 `theme.lua`: + +```lua +return { + primary = { + background = '#161616', + foreground = '#e8e8e8', + }, +} +``` + +主文件 `pebrel.lua`: + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +config.colors = require 'theme' + +return config +``` + +保存任一已加载模块后,查看重载结果。模块名不写 `.lua`后缀,文件位置保持在配置可查找的目录里。 + +## 清空 Profile 列表 + +显式空数组使用 `pebrel.array()`: + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +config.profiles = pebrel.array() + +return config +``` + +普通 `{}`表示空对象,不能在需要数组的地方替代空列表。包含条目时,使用连续的 Lua 数组,参见[自定义启动入口](shells.md)。 diff --git a/docs/site/content/configuration.md b/docs/site/content/configuration.md new file mode 100644 index 000000000..bbc7139e4 --- /dev/null +++ b/docs/site/content/configuration.md @@ -0,0 +1,71 @@ +## 创建配置文件 + +主题、通知和 SSH 等常用设置可以直接在界面中完成。需要保存可复用的终端参数、环境变量或 Profile 时,可以创建 Lua 配置。 + +在可运行 Pebrel 命令的终端执行: + +```sh +pebrel config init --language zh-CN +pebrel config check +``` + +第一条生成带中文说明的配置,第二条检查语法与字段。初始化默认不会覆盖已有文件。需要英文说明时使用 `--language en-US`。 + +## 修改一个选项 + +打开生成的 `pebrel.lua`,保留开头的配置创建与结尾的 `return config`。例如: + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +config.scrolling = { history = 10000 } +config.env = { EDITOR = 'nvim' } + +return config +``` + +这个示例设置终端历史行数和默认编辑器环境变量。`EDITOR='nvim'`不会安装程序;使用前仍需安装相应编辑器。 + +保存后再次运行 `pebrel config check`。检查通过,再新建终端查看需要在启动时生效的选项。 + +## 配置文件在哪里 + +标准数据目录为: + +| 系统 | 目录 | +| --- | --- | +| Windows | `%APPDATA%\Pebrel` | +| macOS | `~/Library/Application Support/Pebrel` | +| Linux | `$XDG_CONFIG_HOME/pebrel`,未设置时为 `~/.config/pebrel` | + +初始化时以命令输出的实际路径为准。便携配置、环境变量和显式参数也可能指定其他文件。 + +需要检查特定文件时运行: + +```sh +pebrel config check --config-file /path/to/pebrel.lua +``` + +将路径换成实际位置。这个检查命令不需要打开应用窗口。 + +## 指定另一套配置 + +启动参数 `--config-file`优先于 `PEBREL_CONFIG_FILE`环境变量,再往后才是标准位置的自动查找。使用 **PEBREL_CONFIG_DIR**可以指定独立配置与数据目录,适合隔离测试或便携使用。 + +旧的 `NEBULA_*`变量保留兼容。新旧文件并存时,Pebrel 名称的配置优先;同名配置中,Lua 优先于 TOML,再到旧的 YAML 格式。选中的文件有错误时,修复这份文件即可,不要期待自动换到另一份。 + +## 保存后重新加载 + +有效配置变更会自动重载。重载失败时,正在运行的应用保留上次有效配置;修正提示的行或字段后,再保存一次。 + +Shell、环境变量和回滚容量等启动相关设置,应在新窗格中验证。字体或颜色也可能受到界面偏好的覆盖;同时设置了两处时,先检查界面中是否已有对应覆盖项。 + +## 将配置拆成多个文件 + +主文件可使用 `require`读取旁边的 Lua 模块。例如,把配色放在 `theme.lua`,再在主文件中写 `config.colors = require 'theme'`。模块返回配置表即可;被加载的本地模块也参与重载。 + +更多可复制的例子见[配置示例](config-examples.md)。完整字段与加载规则见仓库的 [Lua 配置参考](https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/lua-configuration.md)。 + +> [!NOTE] +> Lua 配置会执行本地代码。使用他人提供的配置前,先阅读内容;GUI 的 `pebrel_settings.txt`使用另一套偏好键,不能直接当作 Lua 配置粘贴。 diff --git a/docs/site/content/contributing.md b/docs/site/content/contributing.md new file mode 100644 index 000000000..cc2ce29ee --- /dev/null +++ b/docs/site/content/contributing.md @@ -0,0 +1,106 @@ +## 开始前先确认范围 + +贡献不一定从写代码开始。清晰的复现步骤、文档改进、翻译、可访问性反馈和针对性的测试同样有价值。 + +准备修改代码时,先阅读仓库的[贡献指南](https://github.com/Kuddev/pebrel/blob/main/CONTRIBUTING.md)、[架构说明](https://github.com/Kuddev/pebrel/blob/main/docs/architecture.md)和[项目约束](https://github.com/Kuddev/pebrel/blob/main/docs/project-constraints.md)。涉及 UI 文档时,还需要遵循仓库的国际化规则。 + +
    +
    准备Fork 仓库,从目标分支创建独立工作分支。
    +
    修改一次 PR 只解决一个清晰问题,复用已有职责和状态来源。
    +
    验证运行与改动对应的测试、架构检查、格式检查和真实产品检查。
    +
    提交写清用户问题、实际改动、验证结果和仍未验证的范围。
    +
    + +## 准备开发环境 + +1. Fork `Kuddev/pebrel`,从 PR 目标分支创建自己的工作分支。 +2. 按仓库的 [INSTALL.md](https://github.com/Kuddev/pebrel/blob/main/INSTALL.md) 安装当前平台需要的依赖。 +3. 使用 `rust-toolchain.toml` 固定的 Rust 工具链,不要随意切换工具链版本。 +4. 构建实际的 GPUI 产品界面: + +```sh +cargo build --locked -p pebrel --bin pebrel --features gpui-shell +``` + +如果只是修文档,应优先运行文档自己的构建与测试,不需要为了文字改动制造无关的产品代码变化。 + +## 不要用于推广 + +PR、Issue 及其评论不能用于广告、商业推广或引流,包括以功能贡献为名加入服务商推广、返利链接或注册优惠。确认属于未经授权的推广后,对应提交会被直接关闭。商业合作和赞助请发邮件到 [fickleheartedkeys@163.com](mailto:fickleheartedkeys@163.com),不要在 PR 或 Issue 里洽谈。完整规则见[贡献指南](https://github.com/Kuddev/pebrel/blob/main/CONTRIBUTING.md#commercial-promotion-policy)。 + +## 保持改动容易审查 + +- 一个 PR 只承担一个概念上的改动;不要顺便重构无关文件。 +- 先说明用户可观察到的问题,以及哪些既有行为必须保持。 +- 共享规则应继续由现有权威模块负责,UI 只适配,不复制第二套状态或持久化逻辑。 +- 有自然测试入口时,为问题增加最小、聚焦的回归验证。 +- 不要通过放宽预算、移除测试、增加跳过参数或扩大忽略范围来让 CI 变绿。 +- 不提交构建输出、本地探针、包含隐私/凭据的截图或临时调查文件。 + +仓库的 PR size 检查会限制过大的源码改动;文档、锁文件和资源与源码预算的计算规则不同。需要大范围重构时,先拆分成可独立审查的步骤。 + +## 本地快速检查 + +架构检查需要 Python 3.11+。把 `` 替换成实际目标分支的基准提交: + +```sh +python3 scripts/check_architecture.py --base +python3 -m unittest scripts.tests.test_architecture_budgets scripts.tests.test_architecture_dependencies scripts.tests.test_architecture_governance +cargo test --manifest-path tools/i18n-contract/Cargo.toml --locked +cargo test -p pebrel-settings +cargo test -p pebrel --test file_line_budget +cargo fmt --all -- --check +``` + +涉及正式应用行为时,再运行: + +```sh +cargo check -p pebrel --bin pebrel --features gpui-shell --tests --locked +``` + +还应运行与你修改区域直接相关的行为测试。无法在当前机器上验证的平台能力,需要在 PR 描述里明确写出,而不是把“能编译”描述成“UI 已验证”。 + +## 修改文档网站 + +文档站源文件位于 `docs/site/`。本地构建: + +```sh +python -m pip install -r docs/site/requirements.txt +python docs/site/build.py +python -m unittest discover -s docs/site -p test_site.py +``` + +新增公开文档源文件时,还要把具体路径加入 `.gitignore` 中的精确 allowlist。不要直接放开整个 `docs/` 目录。 + +文档应从用户任务出发:先告诉用户去哪里、执行什么、看到什么结果,再补限制和背景。不要把源码结构说明写成用户指南。 + +## 提交 Pull Request + +PR 描述至少应包含: + +| 内容 | 应写什么 | +| --- | --- | +| 问题 | 用户实际遇到了什么,或为什么需要这个变化 | +| 改动 | 哪些行为发生变化;哪些关键行为保持不变 | +| 验证 | 实际运行过的命令、测试和平台结果 | +| 缺口 | 没有运行的 UI、平台或打包验证 | +| 风险 | 持久化格式、依赖、线程、公共接口等是否受到影响 | + +早期需要设计反馈时可以先开 Draft;准备合并前再切换 Ready。维护者根据实际 diff、测试结果、平台验证和代码审查决定是否可以合并。 + +## CI 会检查什么 + +Draft 和 Ready PR 使用相同的验证规划:CI 根据实际改动路径选择需要执行的原生平台测试;纯文档改动不运行原生测试。主分支、定时和发布验证保留五平台完整矩阵。PR 的检查页面会注明各平台是否实际执行,不能把未执行的绿色汇总当作测试覆盖。核心检查还包括架构合同、格式与矩阵规划和源码规模。 + +来自 fork 的首次贡献可能在 GitHub Actions 中显示等待维护者批准。这是 GitHub 的安全边界,不应通过提高 token 权限或改用不安全触发方式绕过。 + +## 提交前自检 + +- 工作分支基于正确的目标分支。 +- Diff 只包含当前功能需要的文件。 +- 没有提交凭据、个人路径、私密日志或无关截图。 +- 相关测试真实运行过,PR 中没有夸大验证范围。 +- CI 失败时修原因,而不是关闭门禁。 +- 如果改动引入新的架构责任或跨层依赖,已经按仓库要求记录和讨论。 + +完成这些步骤后,PR 会更容易复现、审查和维护。 diff --git a/docs/site/content/documents.md b/docs/site/content/documents.md new file mode 100644 index 000000000..74bd8544b --- /dev/null +++ b/docs/site/content/documents.md @@ -0,0 +1,43 @@ +## 打开 Markdown 文档 + +在[文件树](files.md)中选择 `.md`文件。文档会在标签页中打开,并显示标题、段落、列表、代码和支持的公式排版。 + +阅读视图可以选取和复制文字。需要修改文件时,打开文档工具栏的 **文档操作**(省略号),选择 **源码**。编辑步骤见[编辑 Markdown](markdown-editing.md)。 + +
    Pebrel 文档阅读器显示 Markdown 与数学公式
    Markdown 文档中的公式排版。
    + +## 按目录跳转 + +右侧栏的 **目录**按文档标题组织章节。点击标题可以跳到对应位置;长文档中,可折叠暂时不看的层级。 + +侧栏没有显示时,点击 **展开或收起右侧栏**按钮。文档没有 Markdown 标题时,目录会显示相应的空状态;可以在源码中用 `#`、`##`建立章节。 + +## 专注阅读 + +点击文档工具栏中的 **专注阅读**,为正文留出更多空间;再次使用对应入口退出。这个功能调整阅读布局,不会修改文档内容。 + +在普通代码文件中,类似位置可能显示系统全屏按钮,具体作用以按钮提示为准。 + +## 复制代码 + +将鼠标移到代码块,使用 **复制代码**。复制的是代码文本,不包含 Markdown 外层的反引号围栏。 + +语言选择器可以调整当前代码块的语法高亮,帮助阅读没有写明语言的代码。需要把语言永久写入文档时,在源码中修改代码围栏后面的语言名称并保存。 + +## 复制公式 + +在公式相关菜单中选择 **复制 LaTeX 源码**,可将表达式交给其他数学工具。公式已完整渲染且菜单提供图片复制时,可以选择 **复制公式图片**。 + +无法复制为图片时,先使用 LaTeX 源码,或简化不受支持的语法。用鼠标拖选跨过公式的文字时,版面不会跳动,被选中的公式会显示轮廓,复制得到的是它们的 LaTeX 源码。关于文档中的公式写法,见[Markdown 编辑](markdown-editing.md)。 + +## 查看文件信息 + +右侧栏切换到 **文件信息**,查看文件类型、大小、修改时间、字符数、行数、编码和保存状态。 + +相关操作提供 **复制文件名**、**复制文件路径**、**在文件管理器中显示**、**用默认应用打开**与 **重新读取文件**。重新读取前先保存或复制仍需要保留的编辑内容。 + +## 远端文档和大文件 + +从 SFTP 打开的远端 Markdown 使用源码编辑,保存会写回原服务器,见[远端编辑](remote-edit.md)。 + +文件超过 **8 MB**或无法完整作为 UTF-8 文本编辑时,会显示只读或截断提示。要查看大文件全部内容,可以使用系统编辑器,或在终端用 `less`等工具按需读取。 diff --git a/docs/site/content/files.md b/docs/site/content/files.md new file mode 100644 index 000000000..ae0f6a5bc --- /dev/null +++ b/docs/site/content/files.md @@ -0,0 +1,49 @@ +## 打开项目文件 + +先在终端进入项目目录,再按 **Ctrl+Shift+F**(macOS 为 **⌘⇧F**)打开文件树。展开文件夹,选择要查看的文件。 + +文本文件可以在编辑器中打开,Markdown 默认以排版后的阅读视图打开。聚焦内置 SSH 会话时,文件面板显示对应的[SFTP 远端文件](sftp.md)。 + +## 跟随终端目录 + +在终端执行 `cd`切换目录后,文件树可使用终端上报的目录。手动浏览过其他位置时,点击 **跟随当前终端并刷新**,或使用按钮提示的 **Alt+R**,回到当前终端目录。 + +读取失败时先看面板里的路径和错误提示。旧目录可能仍显示在面板中,修复路径或权限后再刷新。 + +## 按名称找文件 + +在文件树搜索框输入文件或文件夹名称。按需要切换以下选项: + +| 选项 | 使用场景 | +| --- | --- | +| **区分大小写** | 区分 `README`与 `readme` | +| **全词匹配** | 按完整词匹配,而不是任意部分字符 | +| **使用正则表达式** | 用模式匹配文件名,例如 `\.md$` | + +搜索用于查找名称。要查找文件里面的文字,可以在终端使用已安装的搜索工具,例如: + +```sh +rg "TODO" . +``` + +出现扫描限制或目录权限提示时,先缩小到相关项目目录,再搜索。 + +## 从文件夹新建终端 + +右键目标文件夹,选择 **在此处打开终端**,或使用面板的 **在此新建终端**入口。新终端打开后运行 `pwd`检查位置;cmd 使用 `cd`。 + +WSL 目录会使用适合该环境的路径。需要把文件路径交给 Linux 命令时,使用菜单中的 **复制 Linux 路径**。 + +## 复制路径或使用系统应用 + +文件或目录菜单提供 **复制路径**、**打开**以及在系统文件管理器中显示的入口。要把路径放进命令时,粘贴后检查路径中是否有空格,并按 Shell 需要添加引号。 + +文件不适合用内置编辑器处理时,可以在系统文件管理器中打开,或使用文件信息中的 **用默认应用打开**。 + +## 从项目中忽略或删除文件 + +在 Git 项目里,**加入 .gitignore**可为不需要跟踪的文件添加忽略规则。已经被 Git 跟踪的文件,仍需按 Git 的规则处理;忽略规则不会从历史提交中移除内容。 + +选择 **删除**后,阅读 **移入回收站**确认框,核对文件名和路径。批量处理前先确认没有选错项目目录;操作失败时按系统提示检查权限或回收站支持情况。 + +查看改动和提交文件,见[版本控制](vcs.md)。 diff --git a/docs/site/content/fonts.md b/docs/site/content/fonts.md new file mode 100644 index 000000000..d2df367de --- /dev/null +++ b/docs/site/content/fonts.md @@ -0,0 +1,43 @@ +## 放大终端文字 + +打开 **设置 → 外观 → 终端外观**,调整 **终端字号(Ctrl+滚轮缩放)**。可以使用加减按钮,也可以直接点击数值输入新的字号,按 **Enter** 或移开焦点生效,按 **Esc** 取消;还可以在终端按 Ctrl+滚轮缩放。 + +键盘缩放使用 **Ctrl++ / Ctrl+-**,macOS 使用 **⌘+ / ⌘-**;**Ctrl+0 / ⌘0**重置缩放。 + +不希望滚动时误改字号,可以关闭同页的 **Ctrl+滚轮调整字号**。关闭后这个手势被完全忽略,既不改变字号,也不滚动终端;键盘快捷键不受影响。 + +按钮或侧栏文字太小时,调整同页 **界面**分组中的 **界面字号**,它同样可以直接输入数值,不会改变终端输出大小。 + +## 选择英文终端字体 + +在 **英文终端字体**一行点击右侧的展开按钮,打开字体列表。列表里可以搜索已安装的字体,点击可用字体旁的 **加入字体组** 把它加入;**当前顺序**里的字体可以上移、下移或移出。字体组按顺序查找字形:标为“主”的第一项优先,缺少字符时使用后面的字体,内置的 Maple Mono 是最后的兜底。 + +选择后查看数字、标点、代码缩进和表格边框。终端使用等宽网格,等宽字体更适合保持这些内容对齐;列表里标有“比例”的是比例字体,不适合终端。 + +刚安装的字体没有出现时,重新打开字体列表;仍找不到则重启 Pebrel。使用系统显示的字体族名称,而不是字体文件名。 + +## 单独设置中文字体 + +**中文终端字体**与英文字体各自独立保存,同样可以展开带搜索的字体列表,设置自己的字体和回退顺序;也可以直接在输入框写字体名称,多个候选用逗号分隔,按 **Enter**或离开输入框后生效。留空时使用内置的 Maple Mono NF CN 回退。 + +修改后同时检查中文、英文和全角标点。只有中文缺字时,优先检查中文字体和回退列表,不必更换整个界面主题。 + +## 连字和字符间距 + +**字体连字**可选择 **开启**、**关闭**或 **跟随主题**。字体支持时,`->`、`!=`等字符组合会以连字显示,选项会立即应用到已打开的终端。 + +**字体间距**可选 **紧凑**或 **宽松**,用于调整终端字符的列宽。小字号下字符挤在一起时,可以试用宽松;需要更细的纵向调整时,在[主题编辑器](themes.md)设置行高。 + +## 中文粗体看不清 + +打开 **设置 → 交互**,调整 **中日韩粗体提亮**。它让相关字符通过提亮表现粗体,拉丁字符仍按自身字体处理。使用中英文混排的实际输出检查结果。 + +## Powerline 箭头显示成方框 + +在 **外观 → 终端外观**中开启 **Powerline 提示符**后,字体需要包含 Powerline 字形。出现方框时,改用具备这些字形的字体,或先关闭该选项。 + +**启动欢迎信息**会在新会话通过 fastfetch 显示系统信息。不需要启动摘要时,将它关闭即可;此项与字体设置独立。 + +## 排查错位或模糊 + +先恢复默认字体与字号,再关闭连字、改回纯色背景,逐项恢复自己的设置。仍有问题时,反馈系统缩放比例、字体名称、字号、字体间距模式,以及能看出错位的截图。 diff --git a/docs/site/content/git-conflicts.md b/docs/site/content/git-conflicts.md new file mode 100644 index 000000000..1deb8b7f2 --- /dev/null +++ b/docs/site/content/git-conflicts.md @@ -0,0 +1,47 @@ +## 打开冲突文件 + +Git 合并、拉取或变基后出现冲突时,在版本控制面板的 **合并冲突**区域找到文件,选择 **在三栏合并器中解决**。 + +编辑器会打开三列:左侧 **当前版本**,中间 **合并结果(可编辑)**,右侧 **传入版本**。 + +## 合并需要保留的内容 + +先比较左右两边,然后在中间结果栏整理最终内容。通常需要同时保留双方不同位置的修改,而不是直接选择一整边。 + +冲突标记形如: + +```text +<<<<<<< 当前版本 +这一侧的内容 +======= +另一侧的内容 +>>>>>>> 传入版本 +``` + +保留正确内容后,删除这些标记行。结果中仍有冲突标记时,页面会显示 **仍有冲突标记**,应用按钮不可用。 + +## 采用一侧的完整版本 + +确定整个文件应使用一侧内容时,可以点击该侧的箭头按钮:**用当前版本替换合并结果**,或 **用传入版本替换合并结果**。 + +这会替换中间结果的完整内容,不是只接受光标附近的一小段。操作前留意中间已经手动整理的修改。 + +Git 变基时,两侧版本的角色容易与直觉不同。以实际文件内容和正在执行的 Git 操作为准,不能只根据“当前”两个字决定保留哪边。 + +## 应用并暂存 + +1. 检查中间结果,确认冲突标记已经全部清除。 +2. 点击 **应用并暂存**。 +3. 等待状态显示 **已写回并暂存**。 +4. 返回版本控制面板,检查这个文件不再列为未解决冲突。 +5. 运行项目测试或检查命令,然后完成原来的 Git 操作。 + +“应用并暂存”会保存文件并执行对应的暂存操作,不会自动替你完成整个合并或变基。 + +在终端运行 `git status`查看下一步提示。如果当前正在变基,按 Git 提示执行 `git rebase --continue`;普通合并则按当前仓库状态完成提交。 + +## 需要重新读取时 + +文件被其他工具修改,或冲突状态发生变化时,可以点击 **重新读取冲突阶段**。先复制中间尚未保存的内容,以便比较或恢复。 + +二进制文件和超出合并器文本大小限制的文件,需要使用相应的外部工具处理。某一侧显示“文件不存在”时,还要决定是否保留该文件;删除类冲突应结合 `git status`提示处理。 diff --git a/docs/site/content/hooks.md b/docs/site/content/hooks.md new file mode 100644 index 000000000..9576c266c --- /dev/null +++ b/docs/site/content/hooks.md @@ -0,0 +1,94 @@ +> [!NOTE] +> 本页按 Pebrel 2.1.1 核对。设置页里的"Hook"是各工具对"事件入口"的称呼,本页统一叫"集成"。 + +## 先了解默认行为 + +集成让工具在开始、结束或需要你处理时主动告诉 Pebrel,Pebrel 据此更新标签和窗格上的活动提示,并发出通知。它在 Windows、macOS 和 Linux 上都可以使用。 + +- **Claude Code 和 Codex 默认开启。** 只要它们安装在这台电脑上,Pebrel 会自行在它们的配置里写入集成入口,通常不需要你操作。 +- **其他工具默认关闭。** 需要在 **设置 → Agents** 里自己打开,包括 OpenCode、Cursor Agent、Kimi Code、Pi、Oh My Pi、GitHub Copilot 和 Grok。 +- **集成只在 Pebrel 里起作用。** 在 Pebrel 之外的终端运行同一个工具,不会发生任何变化。 + +各工具具体支持哪些功能,见[支持的 AI 命令行工具](agents.md)。 + +## 在设置里查看和开关 + +打开 **设置 → Agents**,页面标题是"编程智能体"。每个工具占一行,从左到右依次是: + +- 工具图标和名称; +- Pebrel 找到的程序路径,鼠标停在路径上可以看到完整内容;找不到时显示"未安装"; +- 当前状态; +- 一个开关。 + +1. 先在终端里启动一次要用的工具,让它完成初始配置。工具还没有创建过配置时,这一行会提示"请先运行一次此工具以创建配置,然后刷新"。 +2. 点击右上角的 **刷新**,重新检测。 +3. 打开这个工具的开关。点击整行也可以切换。 +4. 看到"Hooks 已安装,请重启 agent 使其生效"后,退出并重新启动这个工具。 +5. 提交一个简短任务,检查标签上的状态是否随任务变化。 + +只需要打开自己用的工具。开关灰着无法点击,通常是因为 Pebrel 还没有找到这个工具,或它还没有创建过配置。 + +### 状态的含义 + +| 状态 | 含义 | 怎么处理 | +| --- | --- | --- | +| Hook 已安装 | 集成已经就绪 | 重启工具后即可使用 | +| Hook 未安装 | 工具已找到,集成处于关闭状态 | 需要时打开开关 | +| Hook 已安装 · 需修复 | 入口还在,但内容与当前版本不一致,例如工具更新时改写过配置 | 关闭再打开一次 | +| 需要检查 | 读取或写入这个工具的配置时出错,原因会显示在这一行 | 看提示,检查配置文件的权限,再刷新 | +| 处理中… | 正在写入或移除 | 稍候 | + +如果提示"缺少 hook 辅助程序,请修复 Pebrel 安装后再启用",说明 Pebrel 自带的辅助程序没有找到,重新安装 Pebrel 即可。 + +## 开启后会改动什么 + +Pebrel 只写入属于自己的条目,不会改动你已有的其他配置: + +| 工具 | 修改位置(均在用户目录下) | +| --- | --- | +| Claude Code | `.claude/settings.json`,设置了 `CLAUDE_CONFIG_DIR` 时用该目录 | +| Codex | `.codex/` 下的 `config.toml` 和 `hooks.json` | +| OpenCode | `.config/opencode/plugins/pebrel.js` | +| Pi | `.pi/agent/extensions/pebrel.ts` | +| Oh My Pi | `.omp/agent/extensions/pebrel.ts` | +| Kimi Code | `.kimi-code/config.toml` | +| Cursor Agent | `.cursor/hooks.json` | +| GitHub Copilot | `.copilot/hooks/pebrel.json` | +| Grok | `.grok/hooks/pebrel.json` | + +这些文件属于对应工具自己的配置。开关处于打开状态时,如果工具升级或别的程序改动了它们,Pebrel 会检测到并把自己的条目补回;你主动关闭的工具不会被补回。 + +对于 Claude Code 和 Codex,Pebrel 还会放入一个名为 `pebrel-runtime` 的技能,让它们在对话里直接操作 Pebrel,例如分屏、打开文件或把任务交给另一个窗格里的工具,用法见[命令行控制与自动化](runtime.md)。你修改过的技能文件不会被覆盖。 + +## 关闭集成 + +在 **设置 → Agents** 关闭该工具的开关,再重启工具。出现"Hooks 已移除,请重启 agent 使其生效",表示已经移除。关闭后仍可在终端里正常运行这个工具,活动提示会退回到[屏幕识别](agents.md)。 + +想一次移除所有工具的集成,在终端运行: + +```sh +pebrel setup-ai --remove +``` + +它只移除 Pebrel 写入的条目,保留其他集成。不带 `--remove` 再运行一次,会重新为 Claude Code、Codex 以及你在设置里打开过的工具写入集成。 + +## WSL 与 SSH + +**设置 → Agents** 只管理这台电脑上的工具。WSL 和服务器上的工具有各自的配置,由下面的方式处理。 + +- **通过 Pebrel 的 SSH 连接:** 连接时会自动检查服务器,为其中已安装的 Claude Code、Codex、OpenCode 和 Pi 配置集成。这一步失败不会影响你正常使用终端。需要手动处理时运行 `pebrel setup-ai --ssh 主机别名或user@host`;加上 `--remove` 会移除,并记住这台主机不再自动配置。 +- **WSL:** 在 Windows 上打开 WSL 终端时,会为发行版里的 Claude Code 和 Codex 配置集成。手动运行 `pebrel setup-ai --wsl 发行版名称`,需要指定用户时再加 `--wsl-user 用户名`。Codex 可能会要求你在它的 `/hooks` 里确认这些入口。 + +SSH 和 WSL 里的其他工具仍可使用,只是没有集成,状态提示依赖屏幕识别。 + +## 工具没有被检测到 + +先在准备使用它的终端里运行工具命令。命令找不到时,修复安装和 PATH;命令可用,再点 **刷新**。 + +确认安装的是目标 CLI。例如,Cursor 桌面程序的 `cursor` 命令不等于 Cursor Agent CLI,后者的命令是 `agent`。工具刚升级过时,重新启动 Pebrel 和工具可以清除旧的检测与运行状态。 + +## 收不到任务通知 + +先确认工具已在启用集成后重启,再检查 **设置 → 终端 → 提醒** 里的通知选项。任务状态能更新但卡片没有出现时,通常应继续检查通知显示设置,而不是重新安装工具。 + +通知时长、点击跳回来源窗格和系统通知见[通知](notifications.md)。 diff --git a/docs/site/content/images.md b/docs/site/content/images.md new file mode 100644 index 000000000..c0deaef4e --- /dev/null +++ b/docs/site/content/images.md @@ -0,0 +1,41 @@ +## 预览图片文件 + +从文件树选择图片,可以查看支持格式的预览。常见格式包括 PNG、JPEG、WebP、GIF 和 BMP;超出大小限制或解码失败时,可使用系统默认应用打开。 + +PDF 提供首页缩略图,适合辨认文件。需要翻页、批注或编辑时,使用 PDF 阅读器。Linux 的 PDF 缩略图依赖可用的 `pdftoppm`。 + +## 把剪贴板图片交给命令行工具 + +1. 复制图片本身,例如截图结果,而不是图片文件名。 +2. 点击准备接收图片的终端窗格。 +3. 按 **Ctrl+V / ⌘V**粘贴。 +4. 等待 PNG 保存或远端上传完成。 +5. 检查插入的文件路径,再按工具的要求提交。 + +Pebrel 会生成图片文件并插入路径。AI CLI 是否把路径显示为附件缩略图,取决于它自己的图片输入功能。 + +剪贴板同时包含非空文字时,可能优先粘贴文字。看到意外文本时,先撤回或清空输入,再重新复制图片。 + +## 在 WSL 或 SSH 中粘贴 + +WSL 使用转换后的 Linux 可访问路径。原生 SSH 会话需要先把图片传到远端,再插入远端路径;传输失败时先修复连接或权限。 + +同一张本机图片需要发给不同主机时,分别聚焦对应窗格再粘贴。图片不参与[广播输入](broadcast.md)。 + +## 在终端输出里显示图片 + +前台程序输出 Pebrel 支持的 **OSC 1337**图像协议时,终端可以内嵌显示图片。仅打印一个 `.png`路径不会自动变成图像。 + +需要使用这一方式时,选择能够输出相应协议的命令行工具,并按其说明配置。普通图片浏览优先使用文件预览,不必自己编写转义序列。 + +## Markdown 中的图片 + +本地 Markdown 可以引用可访问的图片,路径相对文档位置。比如 `![截图](images/example.png)`要求文档旁有 `images/example.png`。 + +图片缺失时,先在文件树检查目标文件,不要仅修改显示文字。远端 Markdown 编辑不会自动把所有关联图片下载到本地阅读器。 + +## 清理粘贴产生的文件 + +图片粘贴后,可以从插入的路径找到副本。不再需要时按该位置删除;远端副本需要在服务器上清理。 + +发送前检查截图中是否包含密码、Token 或私人信息。删除本机副本不会撤回已经交给远端服务器或 AI 服务的内容。 diff --git a/docs/site/content/index.md b/docs/site/content/index.md new file mode 100644 index 000000000..a648c95f0 --- /dev/null +++ b/docs/site/content/index.md @@ -0,0 +1,31 @@ +## 开始使用 + + + +## 常用操作 + +| 想完成的操作 | 使用指南 | +| --- | --- | +| 安装 Pebrel,或选择适合电脑的版本 | [安装与平台支持](installation.md) | +| 一边运行服务,一边输入其他命令 | [标签页与分屏](workspace.md) | +| 补齐分支、脚本、主机和历史命令 | [命令补全](completions.md) | +| 下次打开时恢复标签和目录 | [会话保存与恢复](sessions.md) | +| 重复使用一组终端布局 | [布局配方](layouts.md) | +| 找到并修改项目文件 | [文件浏览](files.md) · [Markdown 编辑](markdown-editing.md) | +| 查看改动、提交代码和处理冲突 | [Git 提交](vcs.md) · [解决冲突](git-conflicts.md) · [SVN](svn.md) | +| 将文件传到服务器 | [SFTP 文件传输](sftp.md) | +| 从 Android 查看电脑终端或发送输入 | [Android 连接电脑](mobile.md) | +| 查看 Pebrel 支持哪些 AI 命令行工具 | [支持的 AI 命令行工具](agents.md) | +| 重新打开上次的 AI 对话 | [AI 会话历史](ai-history.md) | +| 更改快捷键或通知时间 | [快捷键](keyboard.md) · [通知](notifications.md) | +| 备份设置,或迁移到另一台电脑 | [加密备份](backups.md) · [备份与迁移](migration.md) | +| 处理无法启动、连接或保存的问题 | [故障排查](troubleshooting.md) | + +
    Pebrel 的顶部标签栏与终端工作区
    终端工作区。截图中的主题和窗口装饰可能因平台而不同。
    + +本指南适用于 **Pebrel 2.1.1**。`main` 中更新的功能不代表已发布到你安装的版本;功能随版本变化时,对应页面会在页首注明版本。macOS 和 Linux 安装包目前标为 Preview;平台差异见[安装与平台支持](installation.md)。 diff --git a/docs/site/content/installation.md b/docs/site/content/installation.md new file mode 100644 index 000000000..fbb1f2336 --- /dev/null +++ b/docs/site/content/installation.md @@ -0,0 +1,90 @@ +## 选择安装包 + +打开 [Pebrel Releases](https://github.com/Kuddev/pebrel/releases)。本指南对应 **2.1.1**,安装包名称包含版本、系统和处理器类型。更新版本的文件名只有版本号不同。 + +| 电脑 | 选择的包 | 系统要求 | +| --- | --- | --- | +| Windows,Intel / AMD 64 位处理器 | `Pebrel-v2.1.1-windows-x64-setup.exe` 或 `Pebrel-v2.1.1-windows-x64.zip` | Windows 10 1809+ / Windows 11 | +| Windows,ARM 处理器 | `Pebrel-v2.1.1-windows-arm64-setup.exe` 或 `Pebrel-v2.1.1-windows-arm64.zip` | Windows 10 1809+ / Windows 11,ARM64 | +| Mac,Apple 芯片 | `Pebrel-v2.1.1-macos-arm64-preview.dmg` | 构建目标为 macOS 14+ | +| Mac,Intel 处理器 | `Pebrel-v2.1.1-macos-x64-preview.dmg` | 构建目标为 macOS 14+ | +| Linux,Intel / AMD 64 位处理器 | `Pebrel-v2.1.1-linux-x64-preview.deb`、`Pebrel-v2.1.1-linux-x64-preview.AppImage` 或 `Pebrel-v2.1.1-linux-x64-preview.tar.gz` | glibc 2.35+ | + +在 Mac 的 **苹果菜单 → 关于本机** 中可以查看芯片类型。`x64` 指 64 位 Intel / AMD,不是 32 位 x86。macOS 和 Linux 当前提供 Preview 包;macOS 构建目标为 14+,发布 CI 在 macOS 15 上验证。 + +同一页面还有 `Pebrel-v2.1.1-android-universal-preview.apk`,它是手机端,不是桌面安装包,用法见[Android 连接电脑](mobile.md)。`SHA256SUMS` 用来核对下载文件。 + +## Windows + +### 使用安装程序 + +1. 下载 `Pebrel-v2.1.1-windows-x64-setup.exe`。 +2. 运行安装程序,按页面提示选择安装位置并完成安装。 +3. 从开始菜单或安装完成后的入口启动 Pebrel。 +4. 看到终端提示符后,输入 `echo Hello, Pebrel` 检查运行情况。 + +ARM 处理器的电脑同样使用安装程序,下载 `Pebrel-v2.1.1-windows-arm64-setup.exe`。 + +### 使用便携版 + +1. 下载 `Pebrel-v2.1.1-windows-x64.zip` 或 `Pebrel-v2.1.1-windows-arm64.zip`。 +2. **完整解压**到一个可写目录。 +3. 进入解压后的目录,运行 `pebrel.exe`。 + +保留与可执行文件一起提供的目录和资源;不要在压缩包预览窗口里直接启动,也不要只复制一个 EXE。需要随身携带配置时,参阅[配置文件](configuration.md)和[备份与迁移](migration.md)。 + +## macOS + +1. 下载 Apple Silicon 的 `Pebrel-v2.1.1-macos-arm64-preview.dmg` 或 Intel 的 `Pebrel-v2.1.1-macos-x64-preview.dmg`。 +2. 打开 DMG,将 **Pebrel** 拖入 **Applications/应用程序**。 +3. 弹出 DMG,然后从“应用程序”启动 Pebrel。 + +如果系统拦截首次启动,先确认安装包来自项目官方 Release,再打开 **系统设置 → 隐私与安全性 → 仍要打开**,按系统提示确认。无需为此全局关闭 Gatekeeper。 + +
    Pebrel 1.9.1 在 macOS Apple Silicon 发布 CI 中启动后的真实窗口
    来自 1.9.1 发布 CI 的 macOS 启动截图,仅用于说明首次启动的样子;2.1.1 的界面细节以实际安装后的窗口为准。
    + +## Linux + +### Debian / Ubuntu 安装包 + +在下载目录打开终端,执行: + +```sh +sudo apt install ./Pebrel-v2.1.1-linux-x64-preview.deb +``` + +安装完成后,从应用菜单打开 Pebrel。使用 `apt install` 安装本地 DEB,可同时处理发行版提供的依赖。 + +### AppImage + +```sh +chmod +x Pebrel-v2.1.1-linux-x64-preview.AppImage +./Pebrel-v2.1.1-linux-x64-preview.AppImage +``` + +如果提示缺少 FUSE,请按照你的发行版说明安装兼容组件,或改用 DEB / TAR.GZ 包。 + +### TAR.GZ 便携包 + +解压 `Pebrel-v2.1.1-linux-x64-preview.tar.gz`,进入其中的目录后运行 `./AppRun`。保留解压后的完整目录,启动器需要读取随包资源。 + +## 平台功能差异 + +| 功能 | Windows | macOS | Linux | +| --- | --- | --- | --- | +| 本地终端、标签页、分屏、SSH、SFTP | 支持 | 支持 | 支持 | +| 系统通知 | 支持 | 支持 | 支持,取决于桌面环境 | +| 系统托盘、关窗保留后台会话、登录时启动 | 支持 | 支持 | 支持,托盘需要桌面提供状态通知器 | +| 全局快速终端热键 | 支持 | 支持 | 支持,Wayland 通过桌面门户注册,会按系统流程请求授权 | +| 本地 AI 集成自动设置 | 支持 | 支持 | 支持 | +| 应用内更新安装 | 安装版支持 | 支持,替换应用包 | 不提供,使用包管理器或下载新包 | + +macOS 和 Linux 的这些集成从 2.1 版开始提供,对应的设置项见[设置索引](settings.md)。通过 Scoop 或 Microsoft Store 等渠道安装的 Windows 版本,由原渠道负责更新,见[更新](updates.md)。 + +Linux 保存密码依赖可用且已解锁的系统凭据服务。macOS 使用系统钥匙串。有关认证方式,见[SSH 认证](ssh-auth.md)。 + +## 已经安装过 Nebula + +Pebrel 是项目更名后的名称。首次运行会尝试迁移旧版配置,保留原文件且不覆盖已有 Pebrel 数据。先备份旧配置,再安装新版本;具体数据位置与迁移步骤见[备份与迁移](migration.md)。 + +无法出现窗口、资源报错或 Shell 启动失败时,见[故障排查](troubleshooting.md)。 diff --git a/docs/site/content/interaction.md b/docs/site/content/interaction.md new file mode 100644 index 000000000..aa628bc69 --- /dev/null +++ b/docs/site/content/interaction.md @@ -0,0 +1,49 @@ +## 调整鼠标操作 + +打开 **设置 → 交互 → 鼠标与选区**。 + +**选中即复制**开启后,松开鼠标时自动复制,右键直接粘贴。经常使用右键“发送到聊天”时,可以关闭它,保留常规菜单。 + +**焦点跟随鼠标**开启后,鼠标移到窗格会改变输入焦点。希望明确点击后才切换输入目标时,将它关闭。多个 SSH 窗格并排时,输入前注意焦点位置。 + +**粘贴前确认**用于在普通 Shell 粘贴多行或高风险文本前显示确认。具体规则和快捷键见[剪贴板](clipboard.md)。 + +## 调整侧栏宽度 + +**拖拽调节侧栏宽度** 默认已开启,直接拖动侧栏与工作区之间的分隔线即可。需要固定宽度、防止误拖时,将此项关闭;已经明确关闭过的设置会被保留。 + +分隔线无法拖动时,先检查这个开关。终端内的分屏分隔线与侧栏宽度分别调整。 + +## 更改标签页布局 + +在 **标签与窗口**分组中: + +| 设置 | 可选方式 | +| --- | --- | +| **标签栏位置** | 左侧边栏 / 顶部 | +| **标签展开动效** | 滑动 / 立即 | +| **新标签位置** | 当前标签之后 / 列表末尾 | + +需要减少移动效果时,把标签展开动效改为“立即”。新标签位置影响之后新建的标签,不会把已有标签全部重新排序。 + +显示关闭按钮的设置在 **外观**页;关闭显示后仍可使用菜单、中键或快捷键关闭标签。 + +## 再次启动 Pebrel 时打开哪里 + +**新建实例行为**可选择创建新窗口、附加到最近使用的窗口,或附加到此桌面最近使用的窗口。 + +经常从项目目录启动 Pebrel 时,选择附加到已有窗口可以集中管理标签;需要每个项目独立窗口时,选择创建新窗口。 + +关窗后的后台运行、登录自启动和标签恢复在 **设置 → 高级**中配置,见[会话保存与恢复](sessions.md)。 + +## 版本控制与中文粗体 + +**侧栏版本控制**可设为自动检测、仅 Git 或仅 SVN。切换后进入相应项目目录并打开版本控制面板。 + +**中日韩粗体提亮**控制中文等相关字符的粗体呈现方式。需要调整字体本身时,转到 **外观 → 终端外观**。 + +## 恢复默认设置 + +设置页底部选择 **恢复默认设置**,阅读确认范围后继续。此操作恢复设置和快捷键、备份原设置,并保留 SSH 主机、凭据和历史。 + +只需要改回一个选项时,优先调整该项,避免重置其余个性化设置。 diff --git a/docs/site/content/keyboard.md b/docs/site/content/keyboard.md new file mode 100644 index 000000000..791ab4cb2 --- /dev/null +++ b/docs/site/content/keyboard.md @@ -0,0 +1,53 @@ +## 常用操作 + +下表列出默认按键。**⌘**是 Command,**⇧**是 Shift,**⌥**是 Option。已经自定义过快捷键时,以 **设置 → 按键映射**中显示的内容为准。 + +| 操作 | Windows / Linux | macOS | +| --- | --- | --- | +| 新建标签页 | Ctrl+Shift+T | ⌘T | +| 新建窗口 | Ctrl+Shift+E | ⌘N | +| 关闭当前项 | Ctrl+Shift+W | ⌘W | +| 打开设置 | Ctrl+, | ⌘, | +| 显示或隐藏侧栏 | Ctrl+Shift+B | ⌘B | +| 命令面板 | Ctrl+Shift+P | ⌘⇧P | +| Shell 选择器 | Ctrl+K | ⌘K | +| 快速跳转 | Ctrl+Shift+O | ⌘⇧O | +| 文件树 | Ctrl+Shift+F | ⌘⇧F | +| 版本控制面板 | Ctrl+Shift+G | ⌘⇧G | +| 向右分屏 | Ctrl+Shift+D | ⌘D | +| 向下分屏 | Ctrl+Shift+S | ⌘⇧D | +| 放大或还原窗格 | Ctrl+Shift+Enter | ⌘⇧Enter | +| 切换相邻窗格 | Ctrl+Alt+方向键 | ⌘⌥方向键 | +| 下一个 / 上一个标签 | Ctrl+Tab / Ctrl+Shift+Tab | ⌘⇧] / ⌘⇧[ | +| 增大 / 减小终端字号 | Ctrl++ / Ctrl+- | ⌘+ / ⌘- | +| 重置终端字号 | Ctrl+0 | ⌘0 | +| 全屏 | Alt+Enter | ⌘Ctrl+F | + +复制、粘贴和滚动见[剪贴板](clipboard.md)与[终端基础操作](terminal-basics.md)。文档编辑按键见[Markdown 编辑](markdown-editing.md)。 + +## 更改一个快捷键 + +1. 打开 **设置 → 按键映射**。 +2. 找到要更改的动作,进入按键录入状态。 +3. 按下新的组合键,检查界面显示的结果。 +4. 返回工作区,在相应位置测试。 + +录入时按 **Esc**取消;使用界面提示的清除操作或 Backspace 清除当前录入。出现冲突提示时,换一个组合键,或先调整原来占用它的动作。 + +macOS 上清除一个动作的快捷键时,它对应的 ⌘ 组合也会一并清除,**恢复默认**则两者都恢复。页面下方的只读区还列出了标签页数字切换和确认对话框的按键:确认对话框用 **Enter** 确定、**Esc** 取消。 + +## 同一按键在不同位置的作用 + +快捷键会受当前焦点影响。例如,编辑 Markdown 段落时 **Ctrl+B / ⌘B**用于加粗选区;搜索框里的方向键用于选择结果,而不是移动终端光标。 + +快捷键没有按预期生效时,先点击要操作的终端或文档,再试一次。系统级快捷键也可能先被桌面环境或其他应用接收。 + +## 全局快速终端 + +全局热键可在 Pebrel 不处于前台时使用,在 Windows、macOS 和 Linux 上都可以设置,配置入口位于按键映射相关设置中。设置后,切换到其他应用试按一次,检查是否成功唤起窗口。 + +热键无法注册时,改用没有被其他应用占用的组合。详细设置见[快速终端与托盘](quick-terminal.md)。 + +## 恢复默认按键 + +设置页底部的 **恢复默认设置**会同时恢复设置与快捷键,并备份原设置;SSH 主机、凭据和历史会保留。需要只改一个动作时,优先调整该项,避免重置其他个性化设置。 diff --git a/docs/site/content/layouts.md b/docs/site/content/layouts.md new file mode 100644 index 000000000..4d21506b9 --- /dev/null +++ b/docs/site/content/layouts.md @@ -0,0 +1,38 @@ +## 保存一套常用排布 + +布局配方适合保存“两个项目标签,每个标签各有两个窗格”这类重复使用的工作环境。 + +1. 打开需要的终端,调整标签名称、目录和分屏大小。 +2. 打开[命令面板](palette.md),搜索“布局”。 +3. 选择 **保存当前窗口布局…**。 +4. 输入 **布局名称**,例如“前后端开发”。 +5. 确认保存范围,点击 **保存布局**。 + +列表会显示保存后的配方,并标出包含多少个标签和分屏。 + +## 选择保存范围 + +**当前标签**只保存当前终端标签的排布,适合一组相关窗格。**当前窗口**保存窗口中的终端布局,适合整个项目环境。当前项不是终端时,“当前标签”范围可能不可选。 + +终端标签的右键菜单也提供 **导出为工作区…**入口。日常重复使用的布局,可以从这里进入相应的工作区保存流程。 + +## 恢复布局 + +1. 打开命令面板,选择 **打开布局配方…**。 +2. 找到保存的布局,点击 **恢复**。 +3. 在新窗口中检查每个终端的目录和连接状态。 +4. 启动项目服务或其他需要的程序。 + +恢复会建立新的终端会话。布局记住的是排布和启动信息,不会复制原来正在运行的进程;例如开发服务器需要在新会话中重新启动。 + +## 更新已有工作安排 + +调整当前窗口后,重新保存为一个容易区分的名称,例如“前后端开发 · 数据库”。确认新配方可以正常恢复后,再删除不用的旧配方。 + +不同电脑上的目录、Shell 和 SSH 凭据可能不同。迁移布局后,先校正这些启动条件,再批量恢复。 + +## 删除布局配方 + +在配方列表选择 **删除**,并在确认框中确认。删除配方不会关闭已经打开的终端,也不会删除项目文件。 + +需要自动恢复最近一次退出前的排布,而不是手动选配方时,开启[启动时恢复上次标签](sessions.md)。 diff --git a/docs/site/content/markdown-editing.md b/docs/site/content/markdown-editing.md new file mode 100644 index 000000000..8c50fdd10 --- /dev/null +++ b/docs/site/content/markdown-editing.md @@ -0,0 +1,96 @@ +## 切换到源码并保存 + +1. 从文件树打开本地 Markdown 文件。 +2. 点击工具栏的 **文档操作**(省略号),选择 **源码**;也可以按 `Ctrl+/`(macOS 为 `⌘/`)切换。 +3. 修改文本。文件名附近的未保存标记会反映编辑状态。 +4. 按 **Ctrl+S / ⌘S**,或点击 **保存**。 +5. 再次切换源码选项,查看排版后的结果。 + +Pebrel 2.1.1 的阅读视图用于阅读和选择文字;修改段落、列表与表格时,请在源码中操作。切回阅读视图可以预览尚未保存的编辑,但仍需执行保存才能写入文件。 + +## 标题、强调和链接 + +下面这段可以作为一个简单说明文档: + +```markdown +# 项目说明 + +## 开始使用 + +请先阅读 **安装步骤**,再运行开发服务。 + +需要特别注意的地方可以写成 *斜体*。 + +运行 `npm run dev` 后,打开终端显示的地址。 + +[返回首页](README.md) +``` + +`#`后面保留一个空格。使用 `##`和 `###`划分子章节,右侧目录会根据这些标题更新。 + +## 列表和任务清单 + +```markdown +1. 安装依赖。 +2. 启动服务。 +3. 打开浏览器。 + +- 开发环境 +- 测试环境 + +- [x] 准备配置 +- [ ] 运行测试 +``` + +完成任务时,在源码中将 `[ ]`改为 `[x]`,保存后查看阅读效果。阅读视图中的任务框用于展示完成状态,不作为修改文件的复选框。 + +## 代码块 + +用三条反引号包围代码,在第一行反引号后注明语言。下面的围栏内层是一段完整的 Markdown 示例: + +````markdown +```sh +echo Hello, Pebrel +``` +```` + +阅读时会显示代码排版,并提供复制按钮。常见语言可写 `sh`、`powershell`、`python`、`rust`、`json`或 `lua`。 + +## 表格 + +```markdown +| 环境 | 地址 | 状态 | +| --- | --- | --- | +| 开发 | localhost | 运行中 | +| 测试 | test.example.com | 待检查 | +``` + +每行用 `|`分隔单元格,第二行定义表头分隔线。新增一行时,在源码中按相同列数补一行;需要在单元格显示竖线时,写成 `\|`。 + +## 图片 + +```markdown +![终端工作区截图](images/workspace.png) +``` + +括号内是相对当前 Markdown 文件的图片路径。分享文档时,把被引用的图片目录一起保留。图片无法显示时,检查路径大小写和文件是否存在。 + +## 数学公式 + +行内公式用 `$...$`,独立公式用 `$$`围起: + +```markdown +直角三角形满足 $a^2+b^2=c^2$。 + +$$ +\frac{1}{2}+\frac{1}{3}=\frac{5}{6} +$$ +``` + +切回阅读视图检查排版。复杂 LaTeX 的支持范围以实际渲染为准;不正常的表达式可先缩小成一个简单公式,再逐步添加内容。 + +## 撤销和处理保存冲突 + +在源码编辑状态下,**Ctrl+Z / ⌘Z**撤销,**Ctrl+Shift+Z / ⌘⇧Z**重做。保存使用 **Ctrl+S / ⌘S**。 + +如果其他程序已经修改了文件,保存可能提示冲突。先复制当前编辑内容,再重新读取磁盘版本,比较后合并需要保留的部分。不要直接重读并丢掉尚未保存的文字。 diff --git a/docs/site/content/migration.md b/docs/site/content/migration.md new file mode 100644 index 000000000..08b86415b --- /dev/null +++ b/docs/site/content/migration.md @@ -0,0 +1,55 @@ +新版 `main` 中的 **设置 → 备份** 支持加密快照与选择性恢复,使用步骤和适用范围见[加密备份与恢复](backups.md)。本页保留手动备份与跨电脑迁移的检查步骤。 + +## 找到个人数据目录 + +| 系统 | 标准位置 | +| --- | --- | +| Windows | `%APPDATA%\Pebrel` | +| macOS | `~/Library/Application Support/Pebrel` | +| Linux | `$XDG_CONFIG_HOME/pebrel`,未设置时通常为 `~/.config/pebrel` | + +Windows 可以把路径粘贴到资源管理器地址栏;macOS 可在 Finder 的“前往文件夹”中输入路径。使用 `PEBREL_CONFIG_DIR`时,以指定目录为准。 + +## 备份哪些内容 + +先正常退出 Pebrel,再复制个人数据目录到安全位置。常见文件包括: + +| 内容 | 文件或位置 | +| --- | --- | +| 界面偏好和快捷键 | `pebrel_settings.txt` | +| 保存的常用命令 | `saved_commands.json` | +| 最近会话布局 | `session.json` | +| SSH 配置记录 | `ssh_profiles.json`,及主机库的相关数据 | +| Lua / TOML 终端配置 | 实际加载的 `pebrel.lua`或对应配置文件 | +| 背景、额外字体和主题素材 | 保留使用中的素材及其路径 | + +整目录备份适合自己的恢复用途。需要发给别人或上传仓库时,改为挑选必要的脱敏文件,排除凭据、历史敏感信息及 `runtime.port`等运行时发现文件。 + +## 迁移到另一台电脑 + +1. 在旧电脑退出 Pebrel,备份数据与自定义配置。 +2. 在 SSH 主机库导出 CSV,需要分享或单独迁移的主题使用主题导出。 +3. 在新电脑安装 Pebrel、常用 Shell、字体和 AI CLI。 +4. 放回需要的个人配置,修正旧电脑上的程序和项目路径。 +5. 重新配置系统凭据、私钥位置和需要的账户登录。 +6. 新建终端、连接一台主机,再检查命令库和布局。 + +跨系统迁移时,不要直接沿用另一系统的绝对路径。主题颜色通常可保留,字体、壁纸和 Shell 路径需要在新系统中重新确认。 + +## SSH 密码与私钥 + +CSV 只包含地址、名称和分类信息,不携带密码、私钥或私钥口令。系统凭据库中的内容也不会通过复制应用目录自动迁移。 + +私钥应使用安全方式单独迁移,并保持恰当的访问权限;在新电脑上编辑主机条目,重新选择私钥并测试连接。不要把私钥放进公开仓库或普通分享压缩包。 + +## 从 Nebula 升级 + +Pebrel 会在新位置缺少相应文件时尝试复制旧版数据,保留旧文件,不覆盖已有 Pebrel 数据。首次启动后先检查主题、主机和命令,再清理旧环境。 + +新旧配置同时存在时,检查实际加载的文件。使用 `pebrel config check`可以发现语法问题;配置选择规则见[Lua 配置](configuration.md)。 + +## 还原备份 + +先退出应用并保留当前数据副本,再恢复准备使用的文件。不要恢复旧的运行时控制端口或 Token 文件;让新进程自行建立。 + +恢复后检查目录权限,运行配置检查,再新建终端验证。AI CLI 的对话正文需要按各工具自己的方式备份和恢复,不包含在 Pebrel 的标签布局中。 diff --git a/docs/site/content/mobile.md b/docs/site/content/mobile.md new file mode 100644 index 000000000..394f85e2e --- /dev/null +++ b/docs/site/content/mobile.md @@ -0,0 +1,67 @@ +> [!NOTE] +> 本页按 Pebrel 2.1.1 核对,面向带有 **手机远程** 设置的桌面版本(2.0 起提供)和匹配的 Android 客户端。2.1.1 的发行版提供 `Pebrel-v2.1.1-android-universal-preview.apk`,下载见[项目发行版](https://github.com/Kuddev/pebrel/releases)。桌面和手机端的版本需要匹配,旧版本不支持这些流程。 + +## 准备连接 + +手机可以查看电脑上运行的任务,并在获准后发送终端输入。**命令仍在电脑上执行**:电脑需要保持运行和网络可达,手机不会在断线后接管电脑的进程。 + +先准备已安装的 Android 客户端和电脑上的 Pebrel。下面使用 **局域网 / Tailscale** 连接: + +- 同一 Wi-Fi 或局域网内,两台设备需要能够互相访问 +- 使用 Tailscale 时,两端需要加入可互通的 Tailnet,并选手机可访问的电脑地址 +- 网络隔离、系统防火墙或电脑休眠可能阻止连接;不要为配对把本机运行时控制端口直接公开到互联网 + +当前 Android 项目的最低版本为 Android 8.0(API 26)。这里描述 Android 流程,不代表提供了同样的 iOS 客户端。 + +## 在电脑上开始配对 + +1. 打开 **设置 → 手机远程**,点 **开启并配对手机**。 +2. 选择 **局域网 / Tailscale**。 +3. 在 **网卡** 中选手机可达的地址;**监听端口** 可留空,由程序选择。 +4. 保持配对页面打开,准备扫描二维码或复制配对信息。 + +二维码单次使用,10 分钟后失效。过期或已经用过时,点 **换一个** 生成新的配对信息,不要反复使用旧截图。二维码和完整配对信息都应只交给自己的设备。 + +## 在 Android 上连接电脑 + +打开手机的 **连接电脑**,选择一种方式: + +| 方式 | 操作 | 适用情况 | +| --- | --- | --- | +| **扫码** | 允许相机,扫描电脑上的二维码 | 手机能看到电脑屏幕 | +| **8 位配对码** | 选择同一局域网发现的电脑,输入二维码下方的 8 位数字 | 本地发现已经找到正确电脑 | +| **粘贴** | 电脑点 **复制完整配对信息**,在手机粘贴,再点 **导入并连接** | 不方便使用相机或局域网发现 | + +拒绝相机权限后仍可使用配对码或粘贴。没有发现电脑时,先核对网络与网卡,再尝试扫码或粘贴;不要把 8 位码当作可以跨任意网络寻找电脑的地址,Tailscale 连接也不保证自动发现。 + +## 核对校验码并批准 + +手机显示 **等待电脑批准** 后,在两端核对校验码。只有内容一致、而且确实是自己刚发起的配对,才在电脑点 **批准**;不一致或不认识的请求应点 **拒绝**。 + +8 位配对码用于发起连接,批准时的校验码用于核对这次配对,它们不是同一个用途的码。不要仅因输入过 8 位码就跳过电脑批准。 + +## 从只看改为允许输入 + +首次使用时,**新手机的默认权限** 为 **只看**;如果你曾修改过该默认值,配对后先核对这台手机的实际权限。先在手机查看正确的终端,确认任务和电脑对应。 + +确实需要远程输入时,在电脑 **已配对的手机** 中,把该手机的权限改为 **允许输入**。发送前核对目标终端、当前目录和正在运行的程序;发到普通 Shell 的文字与发到 AI CLI 的文字可能产生不同结果。 + +只看权限并不允许手机发送终端输入。需要收回操作权限时,在电脑改回 **只看**,不必重新配对。 + +## 暂停连接或移除手机 + +- **暂停**:停止监听并断开手机,但保留已经建立的配对 +- **移除**:撤销这台手机的授权,下次连接需要重新配对 + +丢失手机或不再使用该设备时,应在电脑移除它。只退出手机页面不等于撤销电脑上的配对授权。 + +## 连不上时按顺序检查 + +1. 电脑是否正在运行、未休眠,**手机远程** 是否开启而非暂停。 +2. 所选网卡地址是否能从手机访问,网络是否隔离设备。 +3. 二维码是否超过 10 分钟或已经用过;需要时生成新的配对信息。 +4. 电脑是否仍有待批准请求;核对校验码后处理。 +5. 只有输入不可用时,检查这台手机是否仍是 **只看**。 +6. 切换 Wi-Fi 或 Tailscale 地址后,核对实际连接地址;必要时使用新的配对信息。 + +桌面和手机版本差异较大时,先使用匹配版本再排查。与 SSH 服务器建立终端连接是另一种工作流,见[SSH 连接](ssh.md)。 diff --git a/docs/site/content/navigation.md b/docs/site/content/navigation.md new file mode 100644 index 000000000..e3243b560 --- /dev/null +++ b/docs/site/content/navigation.md @@ -0,0 +1,27 @@ +## 打开快速跳转 + +按 **Ctrl+Shift+O**(macOS 为 **⌘⇧O**)。输入名称或关键字,使用方向键选中结果,按 Enter 打开;按 Esc 返回工作区。 + +快速跳转把已有终端、常用目录、SSH 主机和支持的 AI 会话历史集中到同一个查找入口。 + +## 找到已经打开的终端 + +输入标签名称或相关关键字,选择已有标签或窗格结果。Pebrel 会切换到它所在的位置,原来运行的程序继续保留。 + +标签很多时,先为重要终端[重命名](workspace.md),例如“测试日志”和“生产只读”,之后就能按名称查找。 + +## 从目录重新开始工作 + +查找已经记录的常用目录,选择对应目录结果打开终端。打开后运行 `pwd` 确认位置,再执行项目命令。 + +这里列出的是 Pebrel 已知的目录。本地终端成功启动后,它的起始目录会自动加入这个列表;SSH 连接和 WSL 里的路径不会被当作本机目录记录。第一次使用一个尚未记录的路径,可以先在终端 `cd` 进入,或从文件树使用 **在此处打开终端**。 + +## 连接主机或继续 AI 对话 + +选择 SSH 主机结果可打开对应连接;认证信息缺失时,按提示补充。主机名称和分组可在[SSH 主机库](ssh-library.md)中整理。 + +选择 AI 历史结果会尝试通过相应 CLI 恢复会话。会话所属环境需要具备可用的工具和记录,具体见[AI 会话历史](ai-history.md)。 + +## 查找文件 + +需要在目录中定位文件时,打开[文件树](files.md)并使用它的搜索框。该搜索筛选文件名称;需要搜索文件内容时,可以在终端使用项目已有的搜索工具,例如 `rg`。 diff --git a/docs/site/content/network.md b/docs/site/content/network.md new file mode 100644 index 000000000..904861435 --- /dev/null +++ b/docs/site/content/network.md @@ -0,0 +1,50 @@ +## 设置 Pebrel 的网络代理 + +打开 **设置 → 网络**,在 **代理方式**中选择: + +| 方式 | 作用 | +| --- | --- | +| **不使用代理** | 使用直接连接 | +| **跟随系统** | 使用检测到的系统代理配置 | +| **自定义代理** | 使用自己填写的代理协议与地址 | + +选择自定义代理后,填写代理地址并选择协议。例如,本机 SOCKS5 服务监听 `127.0.0.1:1080`时,选择对应协议并填写这个地址。实际端口以自己的代理软件为准。 + +## 测试当前配置 + +1. 完成代理方式、协议和地址输入。 +2. 点击 **测试网络**。 +3. 查看返回的路线、耗时或错误文字。 +4. 修改后重新测试,确认使用的是新的配置。 + +显示网络连接正常,说明本次测试路线可访问测试目标。某个 SSH 账户或 AI 服务仍有问题时,继续在对应连接或工具中测试。 + +## 让新终端接入系统代理 + +网络页还有独立的 **系统代理**开关,用于 Windows 的新建终端:开启后,新终端会使用当前 Windows 系统代理。如果你已经在 **代理方式** 里选了 **自定义代理** 并填写了地址,新开的终端会直接使用这个地址,不必再打开这个开关。PowerShell 5 和 7 的 HTTP 请求也会使用这个 HTTP 代理。 + +开启后新建一个窗格,再启动需要联网的工具;已经运行的 Shell 和 CLI 不会自动得到重新创建的进程环境。 + +这个开关与上面的网络代理方式分别控制。CLI 也可能使用自己的网络设置,出现问题时同时检查工具配置。 + +## 为某个 SSH 主机覆盖代理 + +编辑 SSH 主机,打开 **高级**页,选择跟随全局、不使用或自定义代理。只有某一台服务器需要直连时,修改该主机即可。 + +带代理认证或跳板的连接,按[代理与跳板](ssh-routing.md)填写。连接规则预览可以帮助确认最终路线。 + +## 在 WSL 或服务器中访问网络 + +工具运行在 WSL 或 SSH 服务器时,网络请求从那个环境发出。尤其是 SSH 服务器上的 `127.0.0.1`指服务器自己,不是你的电脑。 + +先在实际运行工具的环境中检查代理地址和可达性,再启动 CLI。不要把 Windows 上一次成功的测试当作远端服务也已配置完成。 + +## 常见失败 + +**连接被拒绝:**检查代理程序是否运行、协议和端口是否匹配。 + +**超时:**检查当前网络、VPN、代理到目标的路线和防火墙。 + +**某个工具仍无法联网:**新建终端重试,并检查工具自己的代理、证书或账户设置。 + +反馈问题时保留协议、脱敏地址和错误文字,移除代理密码和 Token。 diff --git a/docs/site/content/notifications.md b/docs/site/content/notifications.md new file mode 100644 index 000000000..b4821f71e --- /dev/null +++ b/docs/site/content/notifications.md @@ -0,0 +1,35 @@ +## 开启 AI 消息提示 + +打开 **设置 → 终端 → 提醒**,调整 AI 消息通知开关。任务需要关注时,可以通过通知回到对应窗格查看,而不必一直盯着输出。 + +需要更准确的任务事件时,先完成[Agent 集成](hooks.md)。通知开关控制显示,Agent 集成负责提供支持的活动事件。 + +## 调整通知停留时间 + +在同一分组的通知时长选项中选择:**使用默认值**、**5 秒**、**10 秒**、**30 秒**、**90 秒**或 **直到手动关闭**。 + +使用默认值时,短提示停留 5 秒、消息横幅停留 90 秒,更新通知保留到关闭。更改时长后,新出现或被刷新的应用内卡片使用新设置。 + +
    Pebrel 的应用内通知时长选项
    根据需要选择短暂提示或手动关闭。
    + +## 回到发出通知的终端 + +点击通知中的来源操作,Pebrel 会返回对应窗格。阅读 CLI 里的原始问题,完成确认、授权或补充输入。 + +关闭卡片只会隐藏通知;仍待处理的请求留在终端中。忽略了更新通知,也可以回到 **设置 → 应用**重新查看。 + +## 为什么旧卡片不见了 + +应用内最多保留最近三张卡片。新卡片出现时,较旧的卡片可能被替换,即使选择了手动关闭也一样。 + +需要回看任务内容时,到来源终端或工具历史中查找,不依赖通知卡片作为日志。 + +## 终端铃声 + +**终端铃声**可以选择关闭、闪烁、声音或相应组合,用于响应程序发出的提醒。声音效果受当前平台支持情况影响;需要安静工作时,可优先选择关闭或闪烁。 + +## 系统通知没有出现 + +先确认应用内提示是否正常,再检查系统给 Pebrel 的通知权限、勿扰模式以及 Linux 桌面的通知服务。系统通知的停留时间由操作系统控制,不随应用内卡片时长改变。 + +如果连工具状态都不更新,先检查 CLI 是否已在配置集成后重新启动。 diff --git a/docs/site/content/palette.md b/docs/site/content/palette.md new file mode 100644 index 000000000..b06618c3d --- /dev/null +++ b/docs/site/content/palette.md @@ -0,0 +1,30 @@ +## 按名称查找操作 + +按 **Ctrl+Shift+P**(macOS 为 **⌘⇧P**)打开命令面板。在搜索框输入想做的操作,例如“设置”“分屏”或“布局”。 + +使用方向键选择结果,按 **Enter**执行;按 **Esc**关闭面板。暂时不记得快捷键时,可以先从这里查找。 + +## 打开设置或创建布局 + +例如,要保存当前窗口布局: + +1. 打开命令面板,输入“布局”。 +2. 选择 **保存当前窗口布局…**。 +3. 在布局配方中输入名称并保存。 + +下次使用时,在命令面板选择 **打开布局配方…**,再恢复已保存的布局。完整流程见[布局配方](layouts.md)。 + +## 选择合适的查找入口 + +| 需要找到的内容 | 使用的入口 | +| --- | --- | +| 打开设置、切换面板等应用动作 | 命令面板:Ctrl+Shift+P / ⌘⇧P | +| PowerShell、WSL 等启动入口 | Shell 选择器:Ctrl+K / ⌘K | +| 已开的标签、常用目录、SSH 主机和 AI 历史 | 快速跳转:Ctrl+Shift+O / ⌘⇧O | +| 自己保存的命令文字 | 顶栏的闪电图标 | + +命令面板用于执行应用动作。要运行 `git status` 等 Shell 命令,回到终端输入,或从[保存命令](commands.md)插入。 + +## 找不到某个动作 + +先尝试更短的关键字,并确认当前打开的是命令面板。部分动作需要先聚焦一个终端标签;文档标签、没有分屏的标签和不同系统可用的动作可能不同。全局快速终端和托盘设置在 Windows、macOS 和 Linux 上都有,Linux 的托盘需要桌面提供状态通知器。 diff --git a/docs/site/content/privacy.md b/docs/site/content/privacy.md new file mode 100644 index 000000000..7049ebb1f --- /dev/null +++ b/docs/site/content/privacy.md @@ -0,0 +1,37 @@ +## 哪些内容保存在本机 + +Pebrel 的界面偏好、命令条目、主机记录和会话布局存放在个人数据目录中。背景图片和本地文档仍位于各自路径;图片粘贴会额外产生 PNG 副本。 + +SSH 密码等保存到对应的系统凭据库。具体目录与备份范围见[备份与迁移](migration.md)。 + +## 内容什么时候会发送出去 + +连接 SSH 时,认证与终端输入发送给目标服务器;SFTP 上传和远端图片粘贴会传输所选文件。使用 **发送到聊天**时,选区与问题会交给所选 AI 窗格。 + +AI CLI 可能再把提示、文件或截图发送到其服务提供方。具体范围由工具的权限、配置和服务决定,发送前检查当前项目、目标主机和授权提示。 + +## 备份与手机远程 + +加密备份先在本机加密,再保存到你选择的位置,存储服务只能看到密文;SSH 私钥以及系统凭据库中的密码和 API Key 不会被包含。手机远程只有在你扫码并批准后才会连接,手机与电脑之间使用端到端加密,自建中转只转发密文,看不到终端内容。详见[加密备份](backups.md)和[Android 连接电脑](mobile.md)。 + +## 分享配置或截图前 + +移除密码、Token、私钥、带认证的代理地址以及不需要公开的服务器信息。检查保存命令里是否包含凭据,截图中的终端输出是否包含私人数据。 + +分享 SSH 地址与分类时,使用主机库的 CSV 导出;它不包含密码和私钥。分享主题时,检查其中的本机路径是否需要清除。 + +## 本机自动化的控制文件 + +`runtime.port`等发现文件包含本机运行时连接信息和控制凭据。不要提交到仓库、发给其他人或将控制端口转发到公网。 + +使用自动化脚本时,先列出窗格并核对目标,再发送命令。不要让脚本仅根据当前焦点决定修改哪个项目。 + +## 清理不再需要的数据 + +从对应的设置或列表删除不用的命令、主机或布局。图片粘贴产生的本机和远端副本,需要按实际保存位置分别清理。 + +删除本机文件不会撤回已经上传到服务器或交给 AI 服务的内容。工具自己的历史与云端记录,应在该工具或服务中处理。 + +## 文档网站的搜索 + +本网站的全文搜索在浏览器内运行,不向外部搜索服务发送查询。点击 GitHub、下载或其他外部链接时,会进入相应站点,并适用其自身的数据处理方式。 diff --git a/docs/site/content/quick-terminal.md b/docs/site/content/quick-terminal.md new file mode 100644 index 000000000..b9d9eaaea --- /dev/null +++ b/docs/site/content/quick-terminal.md @@ -0,0 +1,31 @@ +## 设置全局热键 + +快速终端在 Windows、macOS 和 Linux 上都可以使用。设置完成后,可以在其他应用中按组合键唤起 Pebrel。 + +1. 打开 **设置 → 按键映射**。 +2. 找到 **快速终端**,录入准备使用的组合键。 +3. 在 **快速终端打开方式**中选择需要的模式。 +4. 切换到其他应用,按一次热键检查唤起效果,再按一次检查隐藏行为。 + +如果提示热键注册失败,换一个没有被系统或其他应用占用的组合。Linux 的 Wayland 桌面通过系统的快捷键门户注册热键,首次可能会弹出授权提示,需要在系统弹窗中允许。只在 Pebrel 窗口内生效的普通快捷键,不能代替这个全局热键。 + +## 选择打开方式 + +| 模式 | 适合的使用方式 | +| --- | --- | +| **独立窗口** | 随时输入几条短命令,不打断主工作区 | +| **唤起已有窗口** | 回到已经打开的项目和终端 | + +“唤起已有窗口”会召回已有工作区,不会每次都额外创建一个标签页。选择独立窗口后,可以按需要调整它的窗口大小。 + +## 从托盘重新打开窗口 + +打开 **设置 → 高级 → 会话生命周期**,开启 **常驻系统托盘图标**。之后可以从系统托盘(macOS 为菜单栏)中的 Pebrel 入口重新显示窗口。Linux 的托盘需要桌面环境提供状态通知器,没有它时托盘图标可能不显示。 + +希望关闭窗口后仍保留运行中的任务,请同时开启 **关窗后保留后台会话**。隐藏窗口后,任务会继续输出;从托盘或热键唤回时,可以接着查看。 + +## 完全退出 + +需要结束 Pebrel 时,使用退出应用的操作,而不是仅关闭一个设置为后台保留的窗口。保存文档并结束需要处理的任务后再退出;应用进程结束后,全局热键也不再驻留。 + +会话恢复设置见[会话保存与恢复](sessions.md)。 diff --git a/docs/site/content/quickstart.md b/docs/site/content/quickstart.md new file mode 100644 index 000000000..618197c37 --- /dev/null +++ b/docs/site/content/quickstart.md @@ -0,0 +1,68 @@ +## 安装并打开 Pebrel + +从[安装与平台支持](installation.md)选择与你的系统和处理器匹配的安装包。首次打开后,Pebrel 会启动一个终端。看到提示符和闪烁的光标后,就可以输入命令。 + +在终端中输入下面这行内容,再按 **Enter**: + +```sh +echo Hello, Pebrel +``` + +如果下一行显示 `Hello, Pebrel`,随后出现新的提示符,终端已经可以正常使用。 + +## 打开项目目录 + +输入 `cd`,后面跟项目的路径。路径包含空格时,用引号包起来。下面两行任选一行,并把路径改成自己的项目位置。 + +**Windows PowerShell:** + +```powershell +cd "C:\Projects\my-project" +``` + +**macOS、Linux 或 WSL:** + +```sh +cd ~/Projects/my-project +``` + +输入 `pwd` 可以查看当前目录。在 Windows 命令提示符(cmd)中,使用不带参数的 `cd` 查看目录。 + +需要切换终端程序时,按 **Ctrl+K**(macOS 为 **⌘K**)打开 Shell 选择器,再选择已安装的 Shell。默认 Shell 和启动目录可以在 **设置 → 终端** 中调整。 + +## 再开一个终端 + +运行开发服务时,原终端可能一直显示日志。另开一个标签页,就能继续输入其他命令。 + +| 操作 | Windows / Linux | macOS | +| --- | --- | --- | +| 新建标签页 | Ctrl+Shift+T | ⌘T | +| 向右分屏 | Ctrl+Shift+D | ⌘D | +| 向下分屏 | Ctrl+Shift+S | ⌘⇧D | +| 放大当前窗格,再按一次还原 | Ctrl+Shift+Enter | ⌘⇧Enter | + +点击要使用的窗格后再输入。新建分屏会启动另一个 Shell,你可以在里面切换到其他目录或运行不同程序。 + +
    Pebrel 中的终端标签页
    通过标签页切换终端;需要同时查看时,可在一个标签页内分屏。
    + +## 连接服务器 + +打开 **设置 → SSH**,选择 **添加 SSH 主机**,填写地址、用户名和认证信息。保存后,从主机列表打开连接。 + +首次连接会要求确认服务器指纹。与服务器管理员提供的指纹核对一致后,再继续登录。完整示例见[连接第一台 SSH 主机](ssh.md)。 + +## 启动 AI 命令行工具 + +已经安装并登录 Claude Code 或 Codex 时,可以直接在项目终端中运行 `claude` 或 `codex`。先试一个范围明确的任务,例如“介绍这个项目的目录结构,先不要修改文件”。 + +Pebrel 会为识别出的工具显示图标和活动状态。如何查看回答、找回历史对话,见[使用 AI 命令行工具](ai-start.md)。 + +## 调整字体和外观 + +点击窗口中的设置按钮,打开 **外观**。文字太小时,先调整 **终端字号**;侧栏、菜单和按钮的文字则由 **界面字号** 控制。主题、字体和行高的详细设置见[外观](appearance.md)。 + +## 结束工作 + +运行中的命令通常可以按 **Ctrl+C** 停止;在 Windows / Linux 中有文字选中时,先点击终端空白处清除选区,再按 Ctrl+C。出现提示符后,输入 `exit` 退出 Shell。 + +希望下次打开时恢复标签页和目录,可以在 **设置 → 高级 → 会话生命周期** 开启 **启动时恢复上次标签**。需要关窗后继续运行任务,请另行开启[后台会话保留](sessions.md)。 diff --git a/docs/site/content/readme.md b/docs/site/content/readme.md new file mode 100644 index 000000000..51f1c19a3 --- /dev/null +++ b/docs/site/content/readme.md @@ -0,0 +1,101 @@ +
    +GPU 加速终端、SSH 工作区,以及 AI CLI 会话空间。 +

    Pebrel 把本地 Shell、远程主机、文件和 AI 命令行工具集中在同一个原生桌面工作区。这个页面把仓库 README 中最常用的信息重新组织成可以快速浏览的图文说明。

    +
    + +
    Rust 2024GPUIWindows 10 / 11macOS 14+ PreviewLinux glibc 2.35+ PreviewGPL-3.0
    + +## 一个工作区里完成什么 + +
    +
    TERMINAL终端与会话

    用标签页和分屏组织多个 Shell;每个窗格保留自己的工作目录,并可保存常用工作区布局。

    +
    REMOTESSH 与文件

    保存远端主机,通过 SSH 连接服务器,并在终端旁使用 SFTP 上传、下载和整理文件。

    +
    AI CLIAI 命令行工作流

    在独立标签或分屏中运行受支持的 AI CLI,通过活动状态、通知和历史记录跟踪任务。

    +
    READER原生阅读与配置

    阅读 Markdown、公式和本地图片,使用主题、背景、快捷键与 Lua 配置调整工作环境。

    +
    + +
    Pebrel 顶部标签和终端工作区
    用标签页组织多个终端,并在同一个窗口里保持工作上下文。
    + +
    Pebrel 中的多 AI CLI 分屏工作流
    多个命令行任务可以并排运行;每个窗格保持独立输入和输出。
    + +## 平台与下载 + +从[最新发行版](https://github.com/Kuddev/pebrel/releases/latest)选择与你的系统和架构对应的安装包。 + +| 平台 | 当前支持 | 安装包 | +| --- | --- | --- | +| Windows 10 1809+ / 11 | 正式版,x64 / ARM64 | .exe 安装器或 .zip 便携包 | +| macOS 14+ | Preview,Apple Silicon / Intel | .dmg | +| Linux,glibc 2.35+ | Preview,x64 | .AppImage、.deb 或 .tar.gz | +| Android 8.0+ | Preview,手机端 | .apk,用于[连接电脑](mobile.md) | + +Pebrel 2.1 在 Windows、macOS 和 Linux 上都提供系统托盘、全局快速终端热键、登录启动和本地 AI 集成自动配置;Windows 和 macOS 还可以在应用内安装更新,Linux 通过包管理器或新安装包升级。细节见[安装与平台支持](installation.md)。 + +## 终端与会话 + +- 侧栏或顶部标签管理终端,并可拖拽调整分屏。 +- 每个窗格可以拥有独立工作目录;复制部分远端或子系统标签时会保留已知目录。 +- 内置智能补全:从当前 Git 仓库、项目脚本、SSH 配置别名、文件目录获取候选(Windows 还包括已注册的 WSL 发行版),也支持历史补全,见[命令补全](completions.md)。 +- 可选择关窗后继续保留后台会话;应用真正退出后的对话恢复属于另一套机制。 + +要实际配置这些行为,参见[标签页与分屏](workspace.md)、[保存与恢复会话](sessions.md)和[快捷键速查](keyboard.md)。 + +## SSH 与文件 + +Pebrel 可以保存主机、读取 SSH 配置别名,并使用代理或单级跳板。认证可使用密码、私钥及服务器支持的交互流程,首次连接时应核对主机密钥。 + +SFTP 面板用于浏览远端目录、上传与下载文件或文件夹、查看传输进度并取消任务。本地文件浏览、Git 操作和远端文件编辑可以与终端同时进行。 + +
    Pebrel 工作区示例
    终端、文件与远端连接围绕同一工作区组织。
    + +## 手机与备份 + +2.0 起,Android 客户端可以连接电脑,查看正在运行的任务、在获准后发送输入并接收提醒,命令仍在电脑上执行,见[Android 连接电脑](mobile.md)。设置、SSH 主机和工作区布局可以先在本机加密,再备份到本地目录、WebDAV、S3 兼容存储或 SSH 主机,见[加密备份](backups.md)。 + +## AI CLI 工作流 + +Pebrel 会识别多种 AI CLI,并在受支持时显示活动状态与更精确的任务提示,各工具的支持范围见[支持的 AI 命令行工具](agents.md)。通知与来源窗格关联,点击后可以回到对应终端。 + +已捕获的回答可以在阅读器中查看 Markdown、公式、原文和本地图片。向终端粘贴图片时,Pebrel 会把图片保存为文件并把路径交给当前会话;终端内联显示是否可用取决于命令行工具输出的协议和内容。 + +
    Pebrel 中的 AI CLI 会话
    AI CLI 与普通 Shell 一样运行在终端中,同时可使用会话相关的辅助能力。
    + +## 外观、文档与配置 + +Pebrel 提供浅色与深色主题、背景、不透明度、图标和界面语言设置。Markdown 文档可以直接在应用内阅读,数学公式由原生界面排版。 + +
    Pebrel 原生文档与公式排版
    文档阅读器可以显示 Markdown 内容和数学公式。
    + +使用命令行初始化并检查 Lua 配置: + +~~~sh +pebrel config init --language zh-CN +pebrel config check +~~~ + +配置重载失败时会继续使用上一份有效配置。完整字段和示例参见[使用 Lua 配置](configuration.md)与[常用配置示例](config-examples.md)。 + +## 通知 + +在 **设置 → 终端 → 提醒** 中可以选择通知显示时长:保留默认时长、5 / 10 / 30 / 90 秒,或保持常驻。隐藏通知卡片只会关闭显示,不会自动执行确认、拒绝或其他任务操作。 + +## 构建 Pebrel + +安装仓库固定的 Rust 工具链和平台依赖后,README 给出的正式产品构建命令为: + +~~~sh +cargo build --release --locked -p pebrel --bin pebrel --features gpui-shell +~~~ + +准备参与开发时,请继续阅读[贡献与开发](contributing.md),按照仓库规定运行相应检查。 + +## 赞助、社区与联系 + +- **赞助**:README 当前感谢 Fluxion AI 对项目的支持。 +- **社区**:可通过项目 README 中列出的社区入口参与讨论。 +- **Discord**:[discord.gg/VFn4rcxmhn](https://discord.gg/VFn4rcxmhn) +- **邮箱**:[fickleheartedkeys@163.com](mailto:fickleheartedkeys@163.com) +- **许可证**:GPL-3.0;第三方版权和许可证声明以仓库内对应文件为准。 + +> [!NOTE] +> 本页是 README 的文档化导览,不替代仓库 README。版本、下载文件和社区入口发生变化时,以仓库当前内容和最新发行版为准。 diff --git a/docs/site/content/remote-edit.md b/docs/site/content/remote-edit.md new file mode 100644 index 000000000..68b562e6c --- /dev/null +++ b/docs/site/content/remote-edit.md @@ -0,0 +1,41 @@ +## 打开远端文本文件 + +建立内置 SSH 连接,进入[SFTP 文件列表](sftp.md),打开要修改的文本文件。编辑器标题包含文件名和目标主机,先确认两者再编辑。 + +远端 Markdown 以源码打开,避免把服务器上的相对资源路径当作本机文件加载。 + +## 保存回服务器 + +1. 修改所需内容。 +2. 点击 **保存**,或按 **Ctrl+S / ⌘S**。 +3. 等待“正在保存”结束,查看保存状态。 +4. 必要时在远端终端中读取文件,确认服务器上的结果。 + +保存目标是打开文件时的原主机和路径。切换到其他 SSH 窗格,不会将这个文件改存到另一台服务器。 + +## 连接断开或权限不足 + +网络断开时,先恢复 SSH 连接;权限不足时,检查当前账户是否可以写入该文件及所在目录。编辑器不会自动提权为管理员账户。 + +错误提示出现后,保留当前编辑内容,再处理问题并保存。重要修改可以先复制到本地文件,防止关闭应用后丢失。 + +## 文件已经被其他人修改 + +保存前检查到服务器文件发生变化时,Pebrel 会报告冲突。此时: + +1. 复制当前尚未保存的内容。 +2. 重新读取远端文件,查看最新版本。 +3. 合并双方需要保留的修改。 +4. 再次保存并检查结果。 + +如果文件由部署程序或其他编辑器自动生成,应先暂停相关修改流程,避免不断覆盖。 + +## 取消读取或保存 + +远端操作进行时,工具栏提供取消入口。点击后等取消状态结束,再开始下一次操作。取消后可以重新读取远端文件,确认服务器上实际保留的版本。 + +## 只读文件 + +超过 **8 MB**的文件可能只预览开头,无法在此保存;非完整 UTF-8 文本也可能只读。此时可以下载后用合适的编辑器处理,或在远端终端使用服务器上的工具。 + +关闭仍有未保存内容的标签时,按提示选择保存、放弃或取消。文件尚未成功保存前,不要只根据终端连接恢复就关闭编辑器。 diff --git a/docs/site/content/runtime.md b/docs/site/content/runtime.md new file mode 100644 index 000000000..33618cf8b --- /dev/null +++ b/docs/site/content/runtime.md @@ -0,0 +1,95 @@ +## 查看当前终端与运行状态 + +在 Pebrel 的本地终端运行: + +```sh +pebrel env --pretty +pebrel ctl describe --pretty +pebrel pane list +``` + +`env`显示调用环境,`describe`列出当前运行时支持的能力,`pane list`列出可以定位的窗格。后续命令中的窗格 ID,要使用实际列表里的值。 + +命令找不到时,检查当前环境是否为本地 Pebrel 窗格,以及 `PEBREL_CLI`指向的程序。SSH 服务器上不会自动安装本机的 Pebrel CLI。 + +## 读取另一个窗格的输出 + +假设目标窗格 ID 为 `17`,读取最近 80 行: + +```sh +pebrel pane read 17 --lines 80 +``` + +多个窗口中存在相同 ID 时,补充对应的窗口参数。不要固定复用上一次启动中的 ID,关闭并重建窗格后应重新查询。 + +## 发送一条命令 + +确认目标停在普通 Shell 提示符,并位于正确项目目录后,发送: + +```sh +pebrel pane send 17 "git status --short" --wait +``` + +`send`会提交文本并发送回车,`--wait`等待相应状态变化。只想插入文字供人工检查时,使用 `--no-submit`,不要同时加等待执行结束的选项。 + +读取窗格输出确认执行结果。等待结束不等于项目测试成功,成功与否仍由实际命令输出和退出状态判断。 + +## 发送保留换行的文本 + +将文本写入 UTF-8 文件 `task.txt`,然后执行: + +```sh +pebrel pane paste 17 --from-file task.txt --wait +``` + +该方式保留换行,目标需要支持 bracketed paste。文件应是普通文本,输入上限为 32 KiB;不用于发送二进制、控制序列或给远端自动转发本机文件。 + +## 独立运行一个命令 + +需要在目标窗格的已知目录执行非交互命令,同时不改变其 Shell 输入时,可以使用: + +```sh +pebrel pane exec 17 -- git status --short +``` + +`exec`直接启动独立子进程。命令和参数分别传入,管道、重定向和变量展开不会自动作为 Shell 语法执行。需要交互式程序时,仍应在终端会话中运行。 + +## 向 AI 工具分配任务 + +先执行 `pebrel agent list`确认工具名称或稳定 ID,再发送任务。例如,列表中的目标确实名为 `codex`时: + +```sh +pebrel agent send codex "检查当前项目的测试入口,先不要修改文件" --wait +pebrel agent read codex --lines 80 +``` + +自动化应使用列表返回的身份,而不是仅根据窗口焦点猜测目标。命名 Agent 和隔离目录的完整示例见[隔离 AI 工作目录](agent-worktrees.md)。 + +## 管理标签页 + +标签页的编号按窗口计算,所以必须指定窗口。编号从 0 开始,以 `pebrel ctl snapshot --pretty` 里的值为准: + +```sh +pebrel tab rename 2 "API 日志" --window 1 +pebrel tab move 2 0 --window 1 +pebrel tab close 2 --window 1 +``` + +`rename` 传入空字符串可以恢复自动标题。`close` 只关闭空闲的标签,里面还有程序在运行时会被拒绝。 + +## 校验和运行本地插件命令 + +2.0 起,`pebrel plugin` 可以在不启动窗口的情况下检查或调用一个本地命令插件包: + +```sh +pebrel plugin check ./my-plugin --pretty +pebrel plugin run ./my-plugin summary --args '{"label":"示例"}' --timeout-ms 3000 +``` + +`check` 只校验插件的清单和入口路径,不执行 Lua。`run` 每次只调用一个已声明的命令,`--timeout-ms` 取值 1 到 30000,默认 3000。命令按需运行,结束后不会留下常驻的插件进程。这个版本支持命令插件,不包含常驻的插件面板。 + +## 超时后如何处理 + +先读取目标状态和最近输出。如果任务已经收到但仍在执行,继续查看或等待;不要立即重复发送同一条任务,以免执行两次。 + +参数和能力相关错误,可以用 `pebrel ctl describe --pretty`检查当前版本,并参阅[运行时控制参考](https://github.com/Kuddev/pebrel/blob/d574856dae42f7a5142045e0b05f3eb43106fa3d/docs/runtime-control-api.md)。运行时发现文件包含本机控制凭据,不应公开、同步给他人或转发端口。 diff --git a/docs/site/content/send-to-chat.md b/docs/site/content/send-to-chat.md new file mode 100644 index 000000000..357833bec --- /dev/null +++ b/docs/site/content/send-to-chat.md @@ -0,0 +1,35 @@ +## 把报错交给 AI 分析 + +先在一个窗格中启动 AI CLI,再在产生报错的终端中操作: + +1. 选择需要分析的报错文字。 +2. 右键选区,选择 **发送到聊天**。 +3. 在对话框中检查引用的内容。 +4. 补充问题,例如“请解释这个错误,并指出下一步要检查的文件,先不要修改代码”。 +5. 选择目标 AI 窗格,确认后发送。 + +消息会将选中的文字作为引用,并附上你的问题。回到目标窗格可以继续查看工具的响应。 + +## 只发送相关日志 + +通常保留错误信息、相关命令和附近几行上下文即可。过长的日志可以先缩小选区;缺少上下文时,再补充运行目录、系统或复现步骤。 + +发送前移除密码、访问令牌、私人路径或其他不应分享的信息。目标工具可能把内容交给它所连接的 AI 服务。 + +## 选择正确的目标 + +目标列表显示可接收输入的 AI 窗格,并标出相应工具。远端目标还会显示主机信息,选择之前先核对。 + +目标需要仍在运行,并处于可接受粘贴消息的状态。工具已经退出、被替换或暂时无法接收时,先回到那个终端处理,再重新打开发送对话框。 + +## 没有可用目标 + +检查 AI CLI 是否已启动、是否被 Pebrel 识别,以及当前是否停在等待输入的位置。仍无法使用时,可以先复制整理后的消息,再手动粘贴到工具的输入区。 + +开启 **选中即复制**后,右键行为可能变为粘贴。需要调出常规选区菜单时,在 **设置 → 交互**关闭该选项,见[剪贴板](clipboard.md)。 + +## 把内容发送到远端 + +选择 SSH 上的 AI 窗格时,这段文字会离开本机。确认引用内容允许发送到该服务器,并确认列表中的主机就是预期目标,再提交。 + +需要发送图片而不是日志时,使用[图片粘贴](images.md)。 diff --git a/docs/site/content/sessions.md b/docs/site/content/sessions.md new file mode 100644 index 000000000..b383d3e99 --- /dev/null +++ b/docs/site/content/sessions.md @@ -0,0 +1,39 @@ +## 下次打开时恢复标签和目录 + +打开 **设置 → 高级 → 会话生命周期**,开启 **启动时恢复上次标签**。正常退出后再次启动 Pebrel,会按已保存的信息重新建立终端标签、分屏和已知目录。 + +建议先用两个空闲终端测试:分别进入不同目录,正常退出并重开,再运行 `pwd` 检查恢复位置。SSH 标签需要重新连接服务器,缺少认证信息时会再次询问。 + +恢复标签会启动新会话。上次终端里没有保存的屏幕内容和普通程序的内存状态,不会作为整个进程一起恢复。 + +## 关窗后让任务继续运行 + +1. 在 **设置 → 高级 → 会话生命周期**开启 **关窗后保留后台会话**。 +2. 建议同时开启 **常驻系统托盘图标**,方便重新打开窗口。 +3. 运行一个需要持续进行的任务,再关闭窗口。 +4. 通过托盘或快速终端重新唤起 Pebrel,查看原任务的输出。 + +这项设置使应用在关窗后继续驻留。真正退出应用、结束进程、注销或重启电脑会终止本地进程;需要跨重启运行的任务,应使用相应系统服务或任务管理工具。 + +## 接续 AI 对话 + +希望恢复标签时继续之前的 Claude Code 或 Codex 对话,在开启标签恢复后,再开启 **恢复时接续 AI 对话**。 + +恢复需要可用的会话标识、原会话记录和对应 CLI。Pebrel 会尝试用 CLI 的恢复入口接续对话;工具仍可能要求登录或确认工作目录。 + +恢复失败时,右键相关终端标签,使用可用的 **重试会话恢复**或 **选择要继续的对话…**。也可以从[AI 会话历史](ai-history.md)手动选择。 + +## 应该开启哪一项 + +| 你的需要 | 设置 | +| --- | --- | +| 重启应用后重新打开标签、分屏与目录 | 启动时恢复上次标签 | +| 关闭窗口但继续运行本地任务 | 关窗后保留后台会话 | +| 重开时接续受支持的 AI 对话 | 启动时恢复上次标签 + 恢复时接续 AI 对话 | +| 按项目保存几套可重复打开的布局 | 使用[布局配方](layouts.md) | + +## 远端任务需要长时间运行 + +SSH 连接断开时,远端命令是否继续由服务器上的程序和会话管理方式决定。对必须持续运行的远端任务,建议使用服务器上已安装的会话保持工具或系统服务;重新连接后按对应工具的恢复方式继续。 + +关闭 Pebrel 前,仍应保存打开的文档。文档编辑缓冲区的保存提示与终端会话恢复是两套操作。 diff --git a/docs/site/content/settings.md b/docs/site/content/settings.md new file mode 100644 index 000000000..daca3fc09 --- /dev/null +++ b/docs/site/content/settings.md @@ -0,0 +1,51 @@ +## 打开设置并查找选项 + +按 **Ctrl+,**(macOS 为 **⌘,**),或点击工作区的设置按钮。 + +顶部搜索可以查找设置所属的分区。例如输入“通知”进入提醒相关设置,输入“字体”进入外观,输入“恢复”查找会话生命周期。搜索无结果时,试用更短的关键字。 + +## 常用设置在哪里 + +| 需要调整的内容 | 位置 | +| --- | --- | +| 查看版本、检查更新 | **应用 → 版本与更新** | +| 更换主题、应用图标、跟随系统深浅色 | **外观** | +| 中英文字体、终端字号、Ctrl+滚轮缩放、平滑光标、字符间距、回滚和滚动 | **外观 → 终端外观** | +| 界面字号、语言、密度与透明度 | **外观 → 界面** | +| 壁纸及图片铺放方式 | **外观 → 自定义背景** | +| 默认 Shell、启动目录、新终端刷新环境变量(Windows) | **终端 → 启动** | +| 命令补全(模式和按键见[补全指南](completions.md)) | **终端 → 补全** | +| AI 通知、卡片时长、终端铃声 | **终端 → 提醒** | +| 工具检测与集成 | **Agents** | +| 选中即复制、鼠标焦点、粘贴确认 | **交互 → 鼠标与选区** | +| 标签位置、新实例行为、Git / SVN 显示 | **交互 → 标签与窗口** | +| 修改组合键、全局快速终端 | **按键映射** | +| 保存主机、密码与密钥、代理和跳板 | **SSH** | +| 网络代理、测试网络、新终端接入系统代理(Windows) | **网络** | +| 备份与恢复、导出和导入备份文件 | **备份**([加密备份](backups.md)) | +| 配对手机、管理已配对的手机、自建中转 | **手机远程**([Android 连接电脑](mobile.md)) | +| 登录启动、托盘、后台会话、恢复标签和 AI 对话 | **高级 → 会话生命周期** | + +## 设置什么时候生效 + +开关和选择项通常在操作后保存。文字输入按相应字段提示,通过 Enter、离开输入框或保存按钮提交。 + +有些设置影响新会话:更改默认 Shell、回滚行数或终端代理环境后,新建窗格检查效果。修改 Agent 集成后,重新启动相应 CLI。 + +出现保存失败提示时,按错误信息检查文件或目录权限,不必删除整套配置。 + +## 更改界面语言 + +在 **外观 → 界面 → 语言**选择需要的语言。设置改变 Pebrel 的菜单和说明文字,不改变 Shell 或远端程序输出。个别未翻译项会显示英文。 + +## 登录时启动 + +在 **高级 → 会话生命周期**中开启 **登录时自启动**。希望启动后先在后台待命时,再开启 **静默启动**;启用时会同时启用托盘,可从托盘重新打开窗口。 + +显式打开目录等启动方式可能仍会显示窗口。先测试一次普通启动和托盘唤回,再决定是否保留静默模式。 + +## 找不到平台专有选项 + +托盘、全局快速终端、登录启动和关窗保留后台会话在 Windows、macOS 和 Linux 上都有对应选项。如果你的版本早于 2.1,macOS 和 Linux 可能没有这些选项,先在[更新](updates.md)中升级。 + +修改配置文件、备份偏好和恢复默认设置,分别见[Lua 配置](configuration.md)、[备份迁移](migration.md)和[交互设置](interaction.md)。 diff --git a/docs/site/content/sftp.md b/docs/site/content/sftp.md new file mode 100644 index 000000000..eba66aafc --- /dev/null +++ b/docs/site/content/sftp.md @@ -0,0 +1,56 @@ +## 打开远端文件列表 + +先建立[内置 SSH 连接](ssh.md),点击对应终端窗格,再打开文件面板。目录加载完成后,选择文件夹进入下一级,使用 **上一级**返回。 + +列表可以跟随终端已知的远端目录。手动浏览其他目录后,点击 **重新跟随**回到终端目录;服务器文件有变化时,点击 **重新读取**刷新。 + +## 上传文件或文件夹 + +1. 在远端列表中进入目标目录。 +2. 点击 **上传文件**或 **上传文件夹**。 +3. 在本机文件选择窗口中选取要上传的内容。 +4. 有同名冲突时,选择处理方式。 +5. 查看传输进度,完成后确认远端列表中的结果。 + +服务器上的目标目录需要写入权限。选择本地文件期间如果切换了目标,Pebrel 可能提示“目标已改变”;此时回到正确的远端目录,重新发起上传。 + +## 下载到本机 + +选中远端文件或文件夹,点击 **下载到本地**,再选择本机保存位置。下载文件夹时会传输其内容,并显示进度。 + +完成后,在本机目标目录检查结果。磁盘空间不足、写入权限或网络断开都可能使传输中止,可以在修复原因后重新发起。 + +## 处理同名项目 + +| 选项 | 结果 | +| --- | --- | +| **覆盖** | 用传入内容替换目标同名文件 | +| **跳过** | 保留目标已有内容,跳过冲突项 | +| **保留两者** | 另取名称保存,让两份内容同时存在 | +| **取消** | 取消这次操作 | + +选择 **覆盖**、**跳过**、**保留两者** 后对话框会关闭并开始处理;**取消** 关闭对话框,不开始传输。聚焦按钮后可按 Enter 或空格确认。文件与目录类型冲突时,覆盖可能不可选。重要文件不确定是否应替换时,先使用“保留两者”,再比较两份内容。 + +## 跳过没有变化的文件 + +重复传输目录时,可以勾选 **跳过未变**,减少重复复制。Pebrel 根据文件大小和修改时间判断可跳过项,不逐个计算完整内容的校验和。 + +需要确保重新传输某个同大小、同时间戳的文件时,关闭此选项后再操作。 + +## 远端复制与粘贴 + +1. 在源主机的远端列表中选中文件或目录。 +2. 点击 **复制远端项目**。 +3. 浏览到目标目录;也可以切换到另一条已连接的 SSH 会话。 +4. 点击 **粘贴到当前远端目录**。 +5. 处理冲突并检查完成状态。 + +跨主机复制需要源和目标都可连接,并具备读取、写入权限。这里复制的是所选项目,后续粘贴的目标由当前远端目录决定。 + +## 取消传输 + +传输过程中点击 **取消**。出现“正在取消”时,等待操作结束再开始下一次传输。取消不会撤回此前已经完成的其他文件;重新传输前检查目标目录,选择合适的同名处理方式。 + +## 修改远端文本文件 + +从远端列表打开支持的文本文件,编辑后按 **Ctrl+S / ⌘S**保存回服务器。保存结果与异常处理见[远端文件编辑](remote-edit.md)。 diff --git a/docs/site/content/shells.md b/docs/site/content/shells.md new file mode 100644 index 000000000..34f09d4a6 --- /dev/null +++ b/docs/site/content/shells.md @@ -0,0 +1,56 @@ +## 为新终端选择 Shell + +按 **Ctrl+K**(macOS 为 **⌘K**)打开 Shell 选择器,选择要启动的终端程序。列表取决于当前电脑已安装的 Shell,以及你配置的启动入口。 + +Windows 可以使用 PowerShell、命令提示符以及已安装的 WSL 发行版。macOS 和 Linux 使用系统中可用的 Shell;安装了 Zellij 时,它也会出现在选择器中,包括 Homebrew 等常见位置。选择一个入口后,Pebrel 会为它建立终端会话。 + +## 更改默认 Shell + +1. 打开 **设置 → 终端**。 +2. 在 **默认 Shell**中选择常用的程序。 +3. 新建终端,检查提示符是否来自所选 Shell。 + +已打开的 Shell 会继续运行。更改默认项不会中途替换它们。 + +找不到刚安装的 Shell 时,先确认该程序可以独立启动,再重新打开 Pebrel。便携终端可以通过设置中的终端目录选择入口添加;应选择包含可执行文件的目录,或其上一级安装目录。 + +## 设定启动目录 + +1. 打开 **设置 → 终端 → 启动**,找到 **启动目录**。 +2. 点击当前路径或“继承当前目录”,在文件夹选择窗口中选取项目目录。 +3. 新建终端,检查是否进入所选目录。 + +要取消固定启动目录,点击路径右侧的 **清除**。该项会重新显示“继承当前目录”,新会话可沿用已有终端的已知目录。 + +在 Windows 上,同一分组还有 **新建终端时刷新系统环境变量**。开启时,打开终端会读取 Windows 当前的环境设置,刚装好的程序和新改的 PATH 不必重启 Pebrel 就能用;关闭后新终端继承启动 Pebrel 时的环境,包括临时加进去的 PATH。已经打开的终端不受影响。 + +输入 `pwd` 查看实际目录;cmd 使用 `cd`。如果 Shell 自己的启动脚本也执行了 `cd`,最终目录会受该脚本影响。 + +## 配置带参数的启动入口 + +例如,你希望在选择器中直接启动一个带指定参数的外部程序,可以在 Lua 配置中添加 Profile: + +```lua +local pebrel = require 'pebrel' +local config = pebrel.config_builder() + +config.profiles = { + { + name = 'SSH — 开发服务器', + command = 'ssh', + args = { 'dev@example.com' }, + }, +} + +return config +``` + +把示例地址换成自己的服务器。保存后执行 `pebrel config check` 检查配置,再从 Shell 选择器打开这个入口。 + +该例使用外部 `ssh` 命令。需要 Pebrel 的主机管理、连接测试和 SFTP 文件面板时,使用[内置 SSH 连接](ssh.md)。 + +## Shell 打不开时 + +如果创建标签后立即退出,先从系统终端运行同一程序,检查路径和启动参数。自定义 Profile 中,程序路径放在 `command`,每个参数分别放进 `args`,不要把整条命令和所有参数合成程序名。 + +WSL 发行版入口与 Windows 本地 Shell 的文件路径不同,具体见[使用 WSL](wsl.md)。 diff --git a/docs/site/content/ssh-auth.md b/docs/site/content/ssh-auth.md new file mode 100644 index 000000000..dd4049f07 --- /dev/null +++ b/docs/site/content/ssh-auth.md @@ -0,0 +1,47 @@ +## 使用账户密码 + +编辑主机,在 **基本**页选择 **密码**认证,填写用户名与密码。希望以后自动使用该密码时,勾选保存到系统凭据库的选项,然后保存主机。 + +Windows 使用凭据管理器,macOS 使用钥匙串;Linux 需要可用且已解锁的系统凭据服务。保存失败时,仍可按连接提示临时输入密码。 + +编辑已有连接时,密码框留空会保留已保存的密码。需要移除已存凭据时,使用界面提供的清除操作,不要把留空当成删除。 + +## 使用私钥 + +1. 编辑主机,将认证方式切换为 **密钥**。 +2. 点击 **选择私钥文件**,选取本机私钥。 +3. 有多个身份时,按需要添加其他私钥文件。 +4. 测试连接;出现私钥口令提示时,输入创建该密钥时设置的口令。 + +私钥通常与同名 `.pub`公钥文件成对存在。这里选择的是私钥;公钥应预先由服务器管理员配置到对应账户。 + +没有手动指定密钥时,连接会结合 SSH config 的 `IdentityFile`和常见默认私钥位置查找。使用 agent 的环境中,也需要确认 agent 中确实加载了所需身份。 + +## 使用自动认证 + +选择 **自动**,让连接先尝试可用密钥,再按需要使用密码。服务器只允许公钥认证时,仍需提供被服务器认可的密钥,密码不会代替它。 + +存在多个身份、经常连错账户时,给这个主机显式指定用户名和私钥,比依赖多个默认身份更容易排查。 + +## 验证码和多轮认证 + +服务器使用动态验证码或键盘交互认证时,选择 **交互式**。启动连接后,逐项阅读服务器发来的问题,再输入密码、验证码等内容。 + +验证码有有效期,输入新的验证码;不需要把动态验证码保存到主机库。服务器问题的内容由服务器决定,不一定每次相同。 + +## 查看主机密钥提示 + +账户认证前还可能出现服务器指纹确认。账户密码或私钥用于证明“你是谁”,主机指纹用于确认“连到的是哪台服务器”。首次使用或指纹变化时,都应独立核对。 + +## 认证失败时检查什么 + +| 提示或现象 | 优先检查 | +| --- | --- | +| 密码认证失败 | 用户名、密码、服务器是否允许密码登录 | +| 私钥无法读取 | 选中的是否为私钥、文件是否存在、当前用户的读取权限 | +| 私钥口令错误 | 是否输入了密钥口令,而不是服务器账户密码 | +| 多个身份均被拒绝 | 为该主机显式选择正确私钥,检查服务器授权 | +| 验证码一直失败 | 选择交互式认证,并检查验证码和设备时间 | +| 无法保存密码 | 系统凭据服务是否可用、是否已解锁 | + +换电脑时,主机 CSV 可以携带连接信息,但密码和私钥需要单独配置,见[迁移](migration.md)。 diff --git a/docs/site/content/ssh-config.md b/docs/site/content/ssh-config.md new file mode 100644 index 000000000..026f1ec8e --- /dev/null +++ b/docs/site/content/ssh-config.md @@ -0,0 +1,54 @@ +## 给连接取一个别名 + +SSH config 可以把地址、用户名、端口和密钥路径放在一个有名称的条目里。用户配置通常位于 `~/.ssh/config`;Windows 对应用户目录下的 `.ssh\config`。 + +例如,为开发服务器添加: + +```sshconfig +Host development + HostName example.com + User dev + Port 22 + IdentityFile ~/.ssh/id_ed25519 +``` + +把地址、账户和私钥路径换成自己的信息。`Host development`定义别名,`HostName`才是真正连接的服务器地址。 + +## 在 Pebrel 中使用 + +1. 保存 SSH config 文件。 +2. 打开 **设置 → SSH**。 +3. 使用重新读取入口刷新已发现的主机。 +4. 查找 `development`并启动连接。 +5. 首次连接时核对指纹,再处理认证提示。 + +如果已经另外保存过同一服务器的主机条目,可以给两者设置容易区分的名称,避免误用不同账户。 + +## 通过跳板机连接 + +配置中可以使用一个独立别名描述跳板,例如: + +```sshconfig +Host bastion + HostName bastion.example.com + User gateway + +Host internal-dev + HostName 10.0.0.20 + User dev + ProxyJump bastion +``` + +然后在主机的 **高级**设置中,让跳板策略 **跟随 SSH config**。也可以改为 **指定主机**,为这一条连接单独设置跳板。界面中的连接规则预览可帮助确认实际路线。 + +涉及多个跳板、复杂匹配或其他 OpenSSH 选项时,先查看 Pebrel 的连接预览并测试;并非所有外部 SSH 配置选项都具有相同支持范围。代理与跳板的具体操作见[连接路由](ssh-routing.md)。 + +## 修改后没有生效 + +确认修改的是当前用户的配置文件,保存后重新读取,再新建连接。已经建立的 SSH 会话不会中途切换到新地址或新密钥。 + +在 Pebrel 中保存的主机覆盖项也可能影响连接。检查 **高级**页是否设置为跟随配置,还是显式指定了代理或跳板。 + +## 隐藏或移除别名 + +只是不想在 Pebrel 列表中看到某个别名时,可以隐藏它。想从 SSH 配置本身移除连接,则编辑原文件并删除相应段落,再刷新列表。修改原文件前保留备份,尤其是在其他 SSH 客户端也使用它的情况下。 diff --git a/docs/site/content/ssh-library.md b/docs/site/content/ssh-library.md new file mode 100644 index 000000000..98d8ae6b3 --- /dev/null +++ b/docs/site/content/ssh-library.md @@ -0,0 +1,56 @@ +## 查找一台主机 + +打开 **设置 → SSH**,在搜索框输入名称、地址、分组、标签或备注。列表上方可以按 **全部**、**置顶**、**最近** 切换范围,也可以按分组筛选。经常使用的主机在主机行的 **主机操作** 菜单里选择 **置顶**,之后在 **置顶** 范围里就能直接找到。 + +每一行会显示这台主机的登录方式,例如密码、私钥文件名;通过跳板连接的主机会注明“经 某某主机”。 + +建议用用途命名条目,例如“开发环境”或“日志服务器”;同一地址的不同账户,也可以在名称中写明账户用途。 + +## 编辑连接和分类 + +打开条目的编辑入口,在 **基本**页修改地址、端口、用户名或认证方式。分组、标签和备注用于整理列表,可以填写环境、项目和用途。 + +保存前检查地址与用户名,再使用 **测试连接**确认。如果只想更改列表显示文字,修改 **主机名称**即可,不必改服务器地址。 + +## 复制一台主机 + +在主机行的 **主机操作** 菜单里选择 **复制**,会立即保存一台连接设置相同的新主机。之后修改副本的地址、凭据、代理或跳板、分组与标签,都不会影响原来的主机。想基于一台现有主机建立类似的连接时,先复制再修改比从头填写更省事。 + +## 使用 SSH config 中的主机 + +Pebrel 可以发现用户 SSH config 文件中的别名。修改配置后,使用列表的重新读取入口刷新。 + +从配置文件发现的主机可以在 Pebrel 列表里隐藏;这不会删除原 SSH config 条目。要重新显示,使用隐藏项的恢复入口。如何编写别名和 IdentityFile,见[使用 SSH config](ssh-config.md)。 + +## 导出主机列表 + +在 SSH 主机库的导出入口选择 CSV 文件位置。导出的连接元数据包含以下列: + +```csv +destination,label,group,tags,notes,connect_to +dev@example.com,开发服务器,开发环境,linux;test,测试账户, +``` + +`connect_to` 是可选列,用来保存“实际要连接的地址”。普通主机留空即可;[复制](#复制一台主机)出来的主机会在这一列写入它真正连接的地址,导入后仍然连到同一台服务器。 + +CSV 不包含密码、私钥内容或私钥口令。它适合备份地址与分类,或在另一台电脑上重建主机列表。 + +## 批量导入主机 + +1. 先从 Pebrel 导出一份 CSV,保留列名作为模板。 +2. 在副本中填写地址、显示名称及分类信息。 +3. 使用导入入口选择文件。 +4. 查看导入结果,确认新增、跳过或失败的条目。 +5. 为新增主机补充认证信息,再测试连接。 + +已有条目不会被导入文件覆盖;重复项会按导入规则跳过。地址或端口有误时,先修正对应行再导入。文件较大时可以分批处理,并逐批查看结果。 + +包含逗号、引号或换行的字段需要正确的 CSV 引号转义。不要把密码或私钥加进表格;非空的敏感凭据列会被拒绝。 + +## 删除主机 + +选择条目的删除入口,并确认删除提示。如果其他连接正在引用它作为跳板,先调整这些连接的跳板设置。 + +删除主机记录不会删除服务器上的文件。配置文件发现的条目需要永久移除时,应编辑原 SSH config;仅在 Pebrel 隐藏时仍可恢复。 + +换电脑后的凭据处理见[备份与迁移](migration.md)。 diff --git a/docs/site/content/ssh-routing.md b/docs/site/content/ssh-routing.md new file mode 100644 index 000000000..b170c3146 --- /dev/null +++ b/docs/site/content/ssh-routing.md @@ -0,0 +1,46 @@ +## 先确认需要哪种连接方式 + +直接能访问服务器时,保持直连即可。网络只允许通过代理访问外部地址时,设置代理;服务器位于内部网络、必须经过堡垒机时,设置跳板。 + +编辑主机并打开 **高级**页,可以分别配置这两部分。 + +## 使用全局代理 + +1. 在 **设置 → 网络**填写代理类型、地址、端口及必要的认证信息。 +2. 使用网络测试入口检查代理。 +3. 编辑 SSH 主机,打开 **高级**页。 +4. 将代理策略设为 **跟随全局**,保存并测试连接。 + +某台主机不需要代理时,把它的代理策略改为 **不使用**;不必关闭所有连接共用的全局代理。 + +## 为单台主机指定代理 + +在主机的 **高级**页选择自定义代理,填写 SOCKS5 或 HTTP CONNECT 代理的地址和端口。代理要求认证时,再填写用户名和密码。 + +代理端口应在 `1–65535`范围内。填写密码时同时填写用户名;编辑后先用 **测试连接**检查,再保存为日常连接。 + +HTTP CONNECT 代理的认证传输本身不等同于经过 TLS 保护的代理通道。使用不可信网络时,应选择管理员提供的安全接入方式。 + +## 使用跳板机 + +假设目标是内部主机 `10.0.0.20`,需要经过 `gateway@bastion.example.com:22`: + +1. 为目标主机填写它自己的地址、用户名和认证信息。 +2. 在 **高级 → 跳板**中选择 **指定主机**。 +3. 选择已有跳板条目,或填写 `gateway@bastion.example.com:22`。 +4. 查看 **连接规则预览**,确认路线经过跳板再到目标。 +5. 测试连接,按需处理跳板和目标各自的认证提示。 + +已有 SSH config 的 `ProxyJump`设置时,可以选择 **跟随 SSH config**。需要忽略配置里的跳板时,选择 **不使用**。 + +跳板账户和目标服务器账户可能不同,请分别填写。把目标密码填给跳板,不会让后续认证自动成功。 + +## 同时使用代理和跳板 + +代理作用于连接路线的第一段。例如可以先通过代理连接堡垒机,再由堡垒机访问内部服务器。使用连接规则预览检查第一跳,避免代理指向或跳板地址配置反了。 + +## 找出失败的是哪一段 + +先测试代理或堡垒机自身是否可达,再测试目标连接。代理拒绝通常需要检查类型、端口和代理认证;跳板认证失败检查跳板账户;到达跳板后仍超时,检查它到内部目标的网络与防火墙。 + +服务器指纹校验仍需要按提示完成,代理和跳板不会替代身份校验。 diff --git a/docs/site/content/ssh.md b/docs/site/content/ssh.md new file mode 100644 index 000000000..8f6c6315b --- /dev/null +++ b/docs/site/content/ssh.md @@ -0,0 +1,60 @@ +## 准备连接信息 + +向服务器管理员取得主机地址、端口、用户名,以及密码或私钥。首次连接还需要核对服务器指纹。下面以 `dev@example.com`、端口 `22`为例;操作时换成你的实际信息。 + +## 添加主机 + +1. 打开 **设置 → SSH**,选择 **添加 SSH 主机**。 +2. 在 **基本**页填写下列信息。 +3. 选择认证方式并补充相应字段。 +4. 点击 **测试连接**,处理认证提示和服务器身份确认。 +5. 测试成功后点击 **保存**。 + +| 字段 | 示例 | 说明 | +| --- | --- | --- | +| **主机名称** | 开发服务器 | 列表中的显示名称,便于查找 | +| **主机地址** | example.com | 域名或 IP 地址,为必填项 | +| **端口** | 22 | 使用管理员提供的 SSH 端口 | +| **用户名** | dev | 服务器上的账户名 | + +地址也可以包含连接信息,例如 `dev@example.com`或 `ssh://dev@example.com:2222`。为便于检查,首次设置时可以分别填写地址、端口和用户名。 + +## 选择认证方式 + +**密码**:填写账户密码。需要记住密码时,勾选保存到系统凭据库的选项;否则连接时按提示输入。 + +**密钥**:点击 **选择私钥文件**,选择私钥,而不是扩展名为 `.pub`的公钥。私钥设置了口令时,连接过程中还会询问口令。 + +**自动**:先尝试可用密钥,再按需要使用密码。 + +**交互式**:适合服务器要求多轮提问、动态验证码或其他交互认证的情况。问题会在连接过程中逐项显示。 + +完整说明见[密码、密钥与交互认证](ssh-auth.md)。 + +## 确认服务器指纹 + +首次连接时,Pebrel 可能显示服务器的主机密钥指纹。通过管理员、服务器控制台或其他独立可信渠道核对,确认一致后再接受。 + +> [!WARNING] +> 已连接过的服务器突然出现指纹变更时,先停止连接并向管理员确认原因。不要仅为了消除提示而直接接受新指纹。 + +## 打开远端终端 + +保存后,从 SSH 主机列表选择这个条目的连接入口。登录完成并出现远端提示符后,运行: + +```sh +hostname +pwd +``` + +确认显示的是目标服务器和预期目录。需要并排处理本地与远端工作时,可以使用[分屏](workspace.md)。 + +## 浏览服务器文件 + +聚焦这个 SSH 窗格,再打开文件面板。远端文件列表可用于浏览目录、上传、下载和编辑支持的文本文件。完整操作见[SFTP](sftp.md)。 + +## 连接未成功 + +超时先检查网络、VPN、地址和端口;“认证失败”先检查账户及认证方式。需要经过代理或跳板机时,编辑主机并打开 **高级**页,按[代理与跳板](ssh-routing.md)设置。 + +“测试连接”通过后仍无法启动所需程序时,在远端终端检查程序是否已安装、当前账户是否有权限。 diff --git a/docs/site/content/svn.md b/docs/site/content/svn.md new file mode 100644 index 000000000..ab152c183 --- /dev/null +++ b/docs/site/content/svn.md @@ -0,0 +1,43 @@ +## 打开工作副本 + +先用 SVN 客户端检出项目,再在 Pebrel 终端进入这个工作副本。打开 **版本控制面板**,保持 **设置 → 交互 → 侧栏版本控制**为 **自动检测**或 **仅 SVN**。 + +常规 SVN 操作需要可用的 `svn`命令或对应客户端。安装后,重新打开 Pebrel,并在终端运行 `svn --version`检查命令行环境。 + +## 添加并提交文件 + +查看变更列表,把尚未纳入版本控制的新文件添加到 SVN。检查准备提交的文件,填写提交信息后执行提交。 + +SVN 的添加是将新文件纳入版本控制;它不等同于 Git 的暂存区。提交会联系版本库服务器,需要网络和对应账户权限。 + +## 更新工作副本 + +使用更新入口获取服务器上的新修订。更新前检查本地未提交的改动;出现冲突时先处理冲突文件,再继续提交。 + +对已经手动解决的冲突,**解决**操作会保留当前文件内容并标记冲突已解决。点击前先确认文件里已经没有需要处理的冲突内容。 + +## Windows 上使用 TortoiseSVN + +安装 TortoiseSVN 后,Pebrel 的 **更多 SVN 操作**菜单可以打开它的图形界面。例如: + +| 菜单项 | 用途 | +| --- | --- | +| **版本库浏览器** | 查看服务器上的目录和文件 | +| **更新至版本…** | 将工作副本更新到指定修订 | +| **分支 / 标记…** | 创建分支或标记 | +| **切换…** | 切换当前工作副本对应的路径 | +| **合并…** | 打开 SVN 合并流程 | +| **导出…** | 导出不含工作副本管理信息的文件 | +| **修订图** | 查看修订关系 | +| **重定位…** | 更改版本库位置 | +| **属性 / 清理** | 查看属性或处理工作副本维护操作 | + +这些操作会进入外部客户端的对话框,按对话框中的路径、修订和确认步骤完成。安装 TortoiseSVN 后若仍提示不可用,重新启动 Pebrel 再检测。 + +## 对单个文件操作 + +文件行的更多菜单提供 **显示日志**、**责任追溯**、**获得锁定…**、**释放锁定**、**加入忽略列表…**、**重命名…**、**删除**、**编辑冲突**和 **属性**。 + +锁定适合需要独占编辑的文件;修改完成后按团队流程提交并释放锁。删除和重命名会改变工作副本状态,提交前再次检查变更列表。 + +macOS 和 Linux 不提供 TortoiseSVN 的 Windows 图形入口,可以在终端使用 `svn`或系统上的 SVN 客户端完成对应操作。 diff --git a/docs/site/content/terminal-basics.md b/docs/site/content/terminal-basics.md new file mode 100644 index 000000000..f798d7081 --- /dev/null +++ b/docs/site/content/terminal-basics.md @@ -0,0 +1,52 @@ +## 输入命令并查看结果 + +终端提示符后的光标表示 Shell 正在等待输入。输入命令,按 **Enter** 执行;程序结束后,提示符会再次出现。 + +```sh +echo Hello, Pebrel +``` + +如果程序持续显示日志且没有新的提示符,它可能还在运行。可以另开一个[标签页或分屏](workspace.md)执行其他命令。 + +## 查看和切换目录 + +| 操作 | PowerShell / macOS / Linux / WSL | Windows cmd | +| --- | --- | --- | +| 查看当前目录 | `pwd` | `cd` | +| 列出文件 | `ls` | `dir` | +| 返回上一级 | `cd ..` | `cd ..` | +| 进入指定目录 | `cd "路径"` | `cd /d "路径"` | + +命令在当前窗格的目录里运行。切换到另一个窗格后,先查看它的目录;各个 Shell 的目录可以不同。 + +路径中的空格需要用引号包围。例如 PowerShell 中的 `cd "C:\My Projects\demo"`,或 macOS 中的 `cd "$HOME/My Projects/demo"`。 + +## 停止运行中的命令 + +通常按 **Ctrl+C** 可向当前程序发送中断请求。Windows / Linux 有文字选中时,Ctrl+C 会先复制选区;先清除选区再中断。macOS 复制使用 **⌘C**,中断仍使用 **Ctrl+C**。 + +程序可能要求确认退出,或自行处理这次中断。回到提示符后,再输入下一条命令。 + +## 查看之前的输出 + +使用滚轮或触控板向上滚动。普通终端画面还支持: + +| 按键 | 作用 | +| --- | --- | +| Shift+PageUp / Shift+PageDown | 按页查看输出 | +| Shift+Home | 移到保留的历史顶部 | +| Shift+End | 返回输出底部 | + +进入 Vim、less 等全屏程序后,优先使用该程序自己的导航按键。程序接管鼠标时,按住 **Shift** 再用鼠标,可使用终端的选择或滚动操作。 + +## 保留更多历史输出 + +打开 **设置 → 外观 → 终端外观**,调整 **回滚行数**。这个数值控制每个窗格能保留的历史行数;修改后,新建终端窗格使用新设置。增加行数会增加长时间运行时的内存用量。 + +**滚动速度**用于调整鼠标滚轮滚动的行数,修改后立即生效;触控板手势不受该倍率控制。 + +## 当前窗格运行在哪台机器 + +本地 Shell 使用电脑上的文件和程序;WSL 使用所选发行版的环境;SSH 使用远端服务器的环境。需要确认位置时,先查看标签、Shell 类型和当前目录,再运行 `pwd` 或 `hostname`。 + +这一步在复制文件路径、启动 AI 工具和执行修改命令前尤其有用。进一步阅读:[WSL](wsl.md)、[SSH](ssh.md)、[复制与粘贴](clipboard.md)。 diff --git a/docs/site/content/themes.md b/docs/site/content/themes.md new file mode 100644 index 000000000..d265dec31 --- /dev/null +++ b/docs/site/content/themes.md @@ -0,0 +1,49 @@ +## 从已有主题创建副本 + +1. 打开 **设置 → 外观 → 更换主题**。 +2. 选择接近目标的主题,从 **作为模板**入口进入 **自定义主题**。 +3. 填写 **主题名称**,例如“我的深色配色”。 +4. 修改需要的颜色或字体,观察旁边的预览。 +5. 点击 **保存并应用**,回到终端检查效果。 + +创建副本不会改动内置模板。只想先收藏这套配色时,点击 **仅保存**,稍后再从自定义主题中选择。 + +## 调整常用设置 + +**常用颜色**包含终端背景、文字颜色、强调色和光标颜色;**字体与显示**包含字体、字号、行高和不透明度。右侧的预览和文字与背景对比度提示会随修改更新。 + +例如,文字拥挤时可以略微增加行高;光标不容易看清时,选择与背景有明显差异的光标颜色。预览包含终端、界面和 ANSI 色彩,修改后分别检查这几处。 + +预览中的变化在应用前不会改动当前终端。离开编辑器时如出现未保存提示,可以选择继续编辑,或放弃草稿。 + +## 调整调色板和界面细节 + +展开 **高级设置**,可继续调整 **ANSI 16 色**、选区背景、选区文字、光标文字,以及主题支持的圆角、留缝、阴影和分割线。 + +ANSI 颜色影响命令行程序输出的不同颜色;选区颜色影响鼠标选中的文字。修改后查看一段带颜色的输出和一段选区,确认文字仍清晰。 + +颜色或数值格式不正确时,修正标出的字段再保存。需要回到当前模板的起点时,使用 **重置修改**。 + +## 导入其他终端的配色 + +选择 **导入**并打开主题文件。Pebrel 可以读取自身 JSON 主题,以及当前版本支持的其他静态主题格式。 + +1. 选择文件,等待读取完成。 +2. 一个文件包含多套配色时,在候选主题中选择一项。 +3. 查看 **导入说明**,确认不支持或未映射的字段。 +4. 点击 **作为模板**,将配色载入编辑器。 +5. 检查预览后点击 **保存并应用**,或 **仅保存**。 + +如果某种主题文件不能直接导入,可先整理为 Pebrel 支持的静态配色格式;包含脚本或动态计算的整份配置,也应先转换为纯配色数据。 + +## 导出主题 + +在编辑器选择 **导出**,选择目标格式,查看 **此格式不会保留的设置**,再指定保存位置。 + +保留 Pebrel 的完整主题设置时,使用 **Pebrel**格式。导出到其他终端时,主要保留目标格式能表达的配色,Pebrel 特有的界面设置可能不会保留。 + +## 避免丢失草稿 + +切换模板会替换当前尚未保存的修改。想比较两个方案时,先保存第一个副本,再从另一个模板创建新副本。 + +多个窗口同时编辑主题而出现保存冲突时,先保留当前草稿,再重新读取主题库比较,不要覆盖另一个窗口刚保存的结果。 diff --git a/docs/site/content/troubleshooting.md b/docs/site/content/troubleshooting.md new file mode 100644 index 000000000..9db5ca9fe --- /dev/null +++ b/docs/site/content/troubleshooting.md @@ -0,0 +1,82 @@ +## 应用打不开或没有窗口 + +先确认安装包与系统、处理器匹配,并已完整解压。Windows 便携版保留整个目录;macOS 从 Applications 启动,不从 DMG 内直接运行;Linux TAR.GZ 使用包内 `AppRun`。 + +开启过 **静默启动**或 **关窗后保留后台会话**时,窗口可能只是隐藏了,先检查系统托盘(macOS 为菜单栏)。macOS 被系统阻止时,按[首次启动说明](installation.md)处理。 + +仍无法启动时,从系统终端运行对应程序并保留错误输出,不要先删除所有个人数据。 + +## 新终端立即退出 + +先从系统终端运行同一 Shell,确认它本身可以启动。再检查 **设置 → 终端 → 默认 Shell**与启动目录。 + +自定义 Profile 的 `command`只填写程序,参数放在 `args`。WSL 先用 `wsl -d 发行版名称`检查发行版是否可启动。修改后新建标签测试。 + +## 字体缺字、箭头变成方框或列不齐 + +恢复默认终端字体和字号,再检查 **中文终端字体**、**字体间距**与 **字体连字**。Powerline 箭头需要字体提供相应字形。 + +只有背景影响阅读时,先关闭图片和模糊、提高不透明度。详细步骤见[字体](fonts.md)。 + +## SSH 连接超时 + +检查服务器地址、端口、VPN 和本地网络。需要代理或跳板时,编辑主机的 **高级**页,查看连接规则预览。 + +先测试第一跳,再检查跳板到目标的连通性。端口可达后仍认证失败,转到下一项,不必反复更换终端字体或 Shell。 + +## SSH 认证失败或指纹变化 + +核对用户名,确认选择了服务器允许的认证方式。私钥认证选择私钥而非 `.pub`文件,密钥口令与账户密码分开输入;需要验证码时选择交互式认证。 + +指纹变化先向管理员确认,不要直接接受以跳过错误。详见[SSH 认证](ssh-auth.md)。 + +## 文件树没有跟随当前目录 + +先在终端运行 `pwd`(cmd 使用 `cd`)确认位置,再点击 **跟随当前终端并刷新**。手动进入其他目录后,需要通过跟随入口回到终端位置。 + +仍不更新时,检查当前 Shell 的目录上报是否可用。SSH 文件列表使用 **重新跟随**和 **重新读取**。 + +## SFTP 上传或下载失败 + +查看目标路径,检查源文件读取权限、目标写入权限、磁盘空间与 SSH 连接。目标在文件选择期间发生变化时,回到正确目录重新发起传输。 + +有同名冲突时明确选择覆盖、跳过或保留两者。取消之后检查哪些文件已完成,再重新传输,见[SFTP](sftp.md)。 + +## 文档无法编辑或保存 + +本地 Markdown 先使用 **文档操作 → 源码**;阅读视图不能直接编辑段落。超过 8 MB 或非完整 UTF-8 文本可能只读,需要外部编辑器。 + +保存冲突先复制未保存内容,再重新读取并比较。远端保存失败还需检查服务器权限与网络,见[远端编辑](remote-edit.md)。 + +## AI 图标、活动状态或历史缺失 + +先在同一终端检查 CLI 是否可运行。启用或更改 Agent 集成后重启 CLI;工具状态异常时刷新 **设置 → Agents**并检查集成结果。 + +历史恢复需要对应工具的会话记录和有效身份。右键标签使用重试或选择会话入口,或在 CLI 自己的历史里查找,见[AI 会话历史](ai-history.md)。 + +## 设置改了却没有效果 + +先确认修改的是正确设置:界面字号与终端字号分开,背景图片不透明度与终端不透明度分开,网络代理与新终端系统代理开关分开。 + +Shell、回滚行数和进程环境需在新建窗格中验证。Lua 配置报错时运行 `pebrel config check`;存在 GUI 覆盖项时检查 **设置**中的当前值。 + +## 更新后还是旧版本 + +完全退出后台实例,检查快捷方式是否仍指向旧目录。便携版应从新解压目录启动,macOS 应从替换后的 Applications 应用启动,再检查 **设置 → 应用**的版本号。 + +## 提交问题反馈 + +打开 **设置 → 应用 → 反馈问题**,提供下面的信息: + +```text +Pebrel 版本: +系统和处理器架构: +安装方式:安装程序 / ZIP / DMG / DEB / AppImage / TAR.GZ +Shell 或远端环境: +操作步骤: +预期结果: +实际结果和错误文字: +是否能稳定重现: +``` + +附上能说明问题的截图或脱敏日志。不要附上密码、Token、私钥或运行时发现文件。涉及主题、字体或缩放时,再补充对应设置。 diff --git a/docs/site/content/updates.md b/docs/site/content/updates.md new file mode 100644 index 000000000..9aad2b10c --- /dev/null +++ b/docs/site/content/updates.md @@ -0,0 +1,57 @@ +## 检查是否有新版本 + +打开 **设置 → 应用**,查看当前版本并点击 **检查更新**。发现新版本后,打开更新详情查看下载和安装操作。 + +**自动检查更新**控制后台检查,预下载选项用于提前下载更新包。普通安装显示的更新通道是 **Stable**。 + +更新前保存文档,并结束或安排好运行中的任务。下载完成后仍需按安装提示继续,重新启动后才能使用新程序。 + +## Windows 安装版 + +使用官方安装程序安装的版本,可以通过更新详情下载并安装,x64 和 ARM64 都会选择匹配的安装程序。按提示完成安装器流程,然后重新启动 Pebrel。 + +完成后回到 **设置 → 应用**,检查版本号是否已更新。安装正在进行时,不要同时手动替换应用文件。 + +## 由 Scoop 或 Microsoft Store 管理的安装 + +通过 Scoop 或 Windows 应用包安装的 Pebrel,更新由原来的安装渠道负责。在 **设置 → 应用** 里,状态会显示 **由安装渠道管理更新**,**检查更新** 和自动检查、预下载这些选项不再提供,页面会写明该渠道: + +- Scoop 安装:在终端执行 `scoop update pebrel`。 +- 通过 Microsoft Store 安装:打开 Microsoft Store 检查更新。 +- 无法识别来源的安装:回到原来的安装渠道更新;这份副本已停用普通安装器更新。 + +## Windows 便携版 + +便携目录使用手动替换包的方式: + +1. 下载匹配架构的新 ZIP。 +2. 备份配置,并正常退出 Pebrel,包括后台驻留实例。 +3. 将新 ZIP 完整解压到新的目录。 +4. 迁移放在旧程序目录旁的个人配置或素材。 +5. 启动新目录中的 `pebrel.exe`,检查版本和设置。 + +确认新版本正常后,再清理旧程序目录。只替换 EXE 可能遗漏随包资源;ARM64 与 x64 包也不要混用。 + +## macOS + +从 Applications 中运行的可写 Pebrel `.app`可使用受支持的更新安装入口。按更新详情提示保存工作、退出相关运行实例并继续安装。 + +如果提示当前安装位置不支持更新,或安装未成功:下载匹配 Apple Silicon / Intel 的官方 DMG,退出 Pebrel,再将应用拖入 Applications 替换。 + +不要从仍挂载的 DMG 或被系统临时转移的路径直接安装更新。完成后从 Applications 重新启动并检查版本;首次启动的系统确认见[安装](installation.md)。 + +## Linux + +使用与当前安装方式一致的新包。DEB 用户通过包管理器安装新版本;AppImage 用户退出旧进程后运行新的 AppImage;TAR.GZ 用户完整解压新包后使用其中的 `AppRun`。 + +Linux 当前仍需手动完成包替换。更新检查可以帮助发现版本,不会自动代替包管理器更新系统安装。 + +## 更新失败 + +**下载失败:**检查网络代理、磁盘空间和 Release 资产是否可访问。 + +**无法写入应用目录:**检查安装位置与权限,必要时改用官方安装包手动更新。 + +**重开后还是旧版本:**检查启动的是不是旧目录中的快捷方式,以及后台是否仍有旧进程。 + +反馈时提供版本号、系统、架构、安装方式和完整错误文字。升级前的数据保存方法见[备份与迁移](migration.md)。 diff --git a/docs/site/content/vcs.md b/docs/site/content/vcs.md new file mode 100644 index 000000000..1153cc32a --- /dev/null +++ b/docs/site/content/vcs.md @@ -0,0 +1,44 @@ +## 查看项目改动 + +在本地终端进入 Git 仓库,按 **Ctrl+Shift+G**(macOS 为 **⌘⇧G**)打开版本控制面板。面板会显示当前仓库、分支和文件状态。 + +如果显示的不是当前项目,使用 **回到终端当前目录**;执行外部 Git 命令后,点击刷新按钮重新读取状态。 + +在 **设置 → 交互 → 侧栏版本控制**中,可以选择 **自动检测**、**仅 Git**或 **仅 SVN**。 + +## 暂存准备提交的文件 + +1. 查看 **变更**列表,打开文件检查内容。 +2. 对需要提交的文件选择 **暂存**。 +3. 在 **已暂存**列表确认本次提交范围。 +4. 放错文件时,选择 **取消暂存**将它移回未暂存区域。 + +确定所有改动都属于同一任务时,可以使用 **全部暂存**。取消暂存只调整提交范围,不会丢失工作区里的文件修改。 + +## 创建提交 + +在提交信息框输入简短说明,例如“修正安装指南中的目录示例”,点击 **提交**。成功后刷新状态,已提交的改动会从待提交列表中移除,并出现在历史中。 + +提交失败时,阅读错误消息。Git 用户身份未设置、提交钩子失败或冲突未解决,都需要先在当前仓库处理,再重试。 + +## 拉取和推送 + +使用 **拉取**获取远端更新,使用 **推送**发送本地提交。提交到本地仓库后,仍需推送才能让远端看到它。 + +远端认证由当前 Git 环境处理;SSH 主机库保存的登录凭据不一定用于 Git。可以在同一终端运行 `git remote -v`检查远端地址。 + +拉取出现冲突时,转到[解决 Git 冲突](git-conflicts.md),不要反复点击拉取或直接丢弃文件。 + +## 阅读历史和分支线路 + +切换到历史相关视图,查看提交信息及线路。线路显示提交之间的连接关系,便于识别分支和合并。检查某次改动时,先确认仓库路径和当前分支,再查看对应文件。 + +## 丢弃不需要的修改 + +对未提交的改动使用 **丢弃改动**,并在确认框核对范围。它会撤销相应文件的本地修改;需要保留的部分应先复制或提交。 + +“取消暂存”用于暂时不提交,“丢弃改动”用于撤销修改,两者不能互换。 + +## 使用 SVN + +进入 SVN 工作副本后,自动检测模式会切换到相应操作。SVN 使用添加、更新和提交,没有 Git 的暂存区与推送步骤。Windows 上的高级图形操作可交由 TortoiseSVN,见[SVN 工作副本](svn.md)。 diff --git a/docs/site/content/workspace.md b/docs/site/content/workspace.md new file mode 100644 index 000000000..fafaf3d58 --- /dev/null +++ b/docs/site/content/workspace.md @@ -0,0 +1,57 @@ +## 窗口、标签页和窗格 + +一个 Pebrel 窗口可以容纳多个标签页。终端标签页里又可以分成多个窗格,每个窗格都有自己的 Shell、当前目录和运行中的程序。 + +例如,可以为两个项目分别建立标签页,在每个标签页里分出“运行服务”和“查看日志”两个窗格。切换项目时切换标签页;同时查看输出时使用分屏。 + +## 创建和切换标签页 + +点击新建终端入口,或按 **Ctrl+Shift+T**(macOS 为 **⌘T**)。需要为新终端选择不同 Shell 时,使用 **Ctrl+K / ⌘K** 打开 Shell 选择器。 + +点击标签即可切换。也可以使用 **Ctrl+Tab** 切到下一个标签、**Ctrl+Shift+Tab** 切到上一个标签;macOS 还支持 **⌘⇧] / ⌘⇧[**。 + +在 **设置 → 交互** 中,**标签栏位置**可选择“左侧边栏”或“顶部”,**新标签位置**可选择“当前标签之后”或“列表末尾”。 + +## 创建分屏 + +1. 点击准备拆分的终端窗格。 +2. 右键标签页,选择 **左右分屏**或**上下分屏**。 +3. 新窗格出现后,点击它并运行需要的命令。 + +快捷键:Windows / Linux 使用 **Ctrl+Shift+D** 向右分屏、**Ctrl+Shift+S** 向下分屏;macOS 使用 **⌘D / ⌘⇧D**。 + +拖动分隔线可以改变两个窗格的大小。需要暂时集中看一个窗格时,按 **Ctrl+Shift+Enter / ⌘⇧Enter** 放大当前窗格,再按一次还原布局。 + +## 在窗格之间移动 + +点击窗格可以将输入焦点移过去。使用键盘时,按 **Ctrl+Alt+方向键**(macOS 为 **⌘⌥方向键**)切换到相邻窗格。 + +拖动窗格标题可以调整排布;将标题拖出终端区域,可以把该窗格拆成独立标签。拖动前先辨认窗格标题与分隔线:前者移动窗格,后者调整大小。 + +## 重命名、排序和标色 + +右键标签页打开菜单: + +| 操作 | 用途 | +| --- | --- | +| **重命名** | 输入项目名或用途,例如“API 日志”;也可使用 F2 | +| **向左移动 / 向右移动** | 调整标签顺序;位于边缘时,对应方向不可用 | +| **标签颜色** | 用颜色区分项目或环境;选择清除项可恢复默认 | +| **移到新窗口** | 将这项工作移到单独窗口中 | +| **复制标签** | 用同类启动入口新建会话,并尽量沿用已知工作目录 | + +“复制标签”适合在同一目录再开一个 Shell;原终端里正在运行的命令仍留在原标签中。 + +## 给窗格命名 + +双击窗格标题可以为这个窗格命名,例如“日志”或“构建”。按 **Enter** 或点到别处保存,按 **Esc** 取消;清空名称会恢复自动标题。窗格移动或恢复会话后名称仍然保留。把鼠标停在标题上,会看到这些操作提示。 + +## 收起侧栏 + +点击侧栏收起按钮,或按 **Ctrl+Shift+B / ⌘B**。打开文件树时使用 **Ctrl+Shift+F / ⌘⇧F**。终端区域需要更多空间时,可以收起不使用的面板。 + +如果经常使用同一套排布,打开命令面板搜索“布局”,将当前标签或窗口保存为[布局配方](layouts.md)。 + +## 关闭终端 + +在 Shell 中输入 `exit`,或使用关闭入口。关闭窗格、标签页或窗口时,如果里面还有程序在运行,Pebrel 会先提示“某程序仍在运行,关闭会中止它”,确认后才会关闭。关闭前先停止仍需处理的命令,并保存文档标签中的修改。有关关窗后保留任务、重启后恢复标签的设置,见[会话保存与恢复](sessions.md)。 diff --git a/docs/site/content/wsl.md b/docs/site/content/wsl.md new file mode 100644 index 000000000..213ad91a9 --- /dev/null +++ b/docs/site/content/wsl.md @@ -0,0 +1,60 @@ +## 打开已安装的发行版 + +**此页适用于 Windows 上的 WSL。** 先在 Windows 中安装并完成 WSL 发行版的初始化,再打开 Pebrel。 + +按 **Ctrl+K**打开 Shell 选择器,选择需要的发行版。进入后,运行: + +```sh +pwd +uname -s +``` + +`uname -s` 应显示 `Linux`。需要检查 Windows 已安装哪些发行版时,可以在 PowerShell 中运行: + +```powershell +wsl --list --verbose +``` + +刚安装的发行版没有出现在选择器中时,先用 Windows 的 WSL 入口启动一次,再重新打开 Pebrel。 + +## 进入 Linux 或 Windows 项目 + +Linux 用户目录通常通过 `~`访问。Windows C 盘在常见 WSL 配置下映射到 `/mnt/c`: + +```sh +cd ~/projects/my-project +``` + +或者进入 Windows 上的项目: + +```sh +cd /mnt/c/Projects/my-project +``` + +把路径换成实际目录。项目位于 Linux 文件系统时,优先使用 Linux 路径;需要复制路径给 WSL 命令时,可以使用文件树提供的 **复制 Linux 路径**。 + +## 将 WSL 作为默认终端 + +打开 **设置 → 终端 → 默认 Shell**,选择相应发行版,然后新建标签。需要沿用当前 Linux 目录时,在 **启动目录**右侧点击 **清除**,让该项显示“继承当前目录”。 + +复制已有 WSL 标签也会尽量使用已知工作目录。新标签打开后运行 `pwd`,可以确认目录是否已跟随。 + +## 安装开发工具和 AI CLI + +WSL 有独立的软件环境。需要在 WSL 中运行 Node.js、Python 或 AI CLI 时,在该发行版内安装并登录。Windows 中能运行某个命令,并不代表 WSL 的 Linux PATH 中也有它。 + +把项目文件交给 AI 之前,先在同一个 WSL 窗格中进入项目目录,再启动工具。 + +## 复制图片与使用 Pebrel CLI + +在 WSL 终端粘贴图片时,Pebrel 会插入适合该环境访问的路径。提交给 CLI 前,检查生成的路径是否完整。 + +从 Pebrel 启动的本地窗格会提供 CLI 环境信息,WSL 会转换相关路径。可以运行 `pebrel env --pretty` 检查;没有找到命令时,检查 `PEBREL_CLI` 指向的程序是否可从 WSL 执行。控制命令的使用见[终端自动化](runtime.md)。 + +## 常见问题 + +**打开后立刻退出:**先从 PowerShell 执行 `wsl -d 发行版名称`。如果也失败,先修复发行版本身的启动问题。 + +**命令可以运行,但字体或颜色不同:**WSL Shell 的提示符配置与 Windows Shell 分开,终端字体则仍在 Pebrel 的 **外观**中设置。 + +**文件树目录没有变化:**确认 Shell 能上报当前目录,再使用文件树的跟随和刷新入口。手动浏览过目录后,点击 **跟随当前终端并刷新**恢复跟随。 diff --git a/docs/site/palettes.py b/docs/site/palettes.py new file mode 100644 index 000000000..192bf023c --- /dev/null +++ b/docs/site/palettes.py @@ -0,0 +1,182 @@ +"""Derive the documentation colour themes from the desktop application's built-in themes. + +The palettes are parsed from the application source rather than copied, so a theme added +or retuned in `pebrel_settings` reaches the site on the next build. The build fails when +the source no longer has the expected shape instead of silently dropping a theme. +""" +import html +import re +from pathlib import Path + +REPO = Path(__file__).resolve().parents[2] +THEMES_RS = REPO / "pebrel_settings/src/themes.rs" +LABELS_RS = REPO / "pebrel_app/src/display/ui/theme.rs" + +# Mirrors the application's factory default (Nord) and its light pair when following the system. +DEFAULT_LIGHT = "NordLight" +DEFAULT_DARK = "Nord" + +FIELDS = ("shell", "background", "foreground", "muted", "accent", "selected", "line", + "red", "green", "yellow", "blue", "purple", "cyan") + + +def _bytes(raw: str) -> tuple[int, ...]: + return tuple(int(value.strip(), 0) for value in raw.split(",") if value.strip()) + + +def _hex(channels: tuple[int, ...]) -> str: + return "#" + "".join(f"{channel:02x}" for channel in channels[:3]) + + +def _mix(front: tuple[int, ...], back: tuple[int, ...], amount: float) -> tuple[int, ...]: + return tuple(round(f * amount + b * (1 - amount)) for f, b in zip(front[:3], back[:3])) + + +def luminance(channels: tuple[int, ...]) -> float: + def linear(value: int) -> float: + value /= 255 + return value / 12.92 if value <= 0.03928 else ((value + 0.055) / 1.055) ** 2.4 + red, green, blue = (linear(value) for value in channels[:3]) + return 0.2126 * red + 0.7152 * green + 0.0722 * blue + + +def contrast(first: tuple[int, ...], second: tuple[int, ...]) -> float: + high, low = sorted((luminance(first), luminance(second)), reverse=True) + return (high + 0.05) / (low + 0.05) + + +def load() -> list[dict]: + """Return the selectable built-in themes in the order the application lists them.""" + source = THEMES_RS.read_text(encoding="utf-8") + order = re.search(r"pub const BUILTIN: \[Self; \d+\] = \[(.*?)\];", source, re.S) + if not order: + raise ValueError("themes.rs: BUILTIN catalog not found") + variants = re.findall(r"Self::(\w+)", order.group(1)) + labels_source = LABELS_RS.read_text(encoding="utf-8") + label_block = re.search(r"pub\(crate\) fn label\(self\) -> &'static str \{(.*?)\n \}", labels_source, re.S) + if not label_block: + raise ValueError("theme.rs: label() not found") + labels = dict(re.findall(r'Self::(\w+) => "([^"]+)"', label_block.group(1))) + reviewed = re.search(r"pub const fn reviewed_palette\(self\).*?\n \}\n", source, re.S) + if not reviewed: + raise ValueError("themes.rs: reviewed_palette() not found") + arms = { + name: body + for name, body in re.findall(r"Self::(\w+) => ReviewedPalette \{(.*?)\n \},", reviewed.group(0), re.S) + } + themes = [] + for variant in variants: + if variant not in arms or variant not in labels: + raise ValueError(f"theme {variant}: palette or label missing in the application source") + palette = {} + for field in FIELDS: + found = re.search(rf"\b{field}: \[([^\]]*)\]", arms[variant]) + if not found: + raise ValueError(f"theme {variant}: field {field} missing") + palette[field] = _bytes(found.group(1)) + themes.append({ + "id": variant, "label": labels[variant], "palette": palette, + "light": luminance(palette["background"]) > 0.4, + }) + ids = {theme["id"] for theme in themes} + if DEFAULT_LIGHT not in ids or DEFAULT_DARK not in ids: + raise ValueError("default theme pair is not selectable") + return themes + + +def _over(front: tuple[int, ...], back: tuple[int, ...]) -> tuple[int, ...]: + """Composite a colour that may carry an alpha channel, as the application does.""" + alpha = front[3] / 255 if len(front) > 3 else 1 + return _mix(front, back, alpha) + + +def readable(color: tuple[int, ...], foreground: tuple[int, ...], background: tuple[int, ...]) -> tuple[int, ...]: + """Keep a theme colour for text, nudged toward the foreground only when too faint to read.""" + for step in range(21): + candidate = _mix(foreground, color, step / 20) + if contrast(candidate, background) >= 4.5: + return candidate + return foreground + + +def tokens(theme: dict) -> dict[str, str]: + palette = theme["palette"] + background = palette["background"] + selected = _mix(_over(palette["selected"], background), background, 0.5) + foreground = palette["foreground"] + accent = readable(palette["accent"], foreground, selected) + muted = readable(palette["muted"], foreground, selected) + + def ink(name: str) -> str: + return _hex(readable(palette[name], foreground, selected)) + return { + "bg": _hex(background), + "panel": _hex(palette["shell"]), + "soft": _hex(selected), + "code": _hex(selected), + "tint": _hex(_mix(accent, background, 0.12)), + "text": _hex(palette["foreground"]), + "muted": _hex(muted), + "line": _hex(_over(palette["line"], background)), + "accent": _hex(accent), + "red": ink("red"), "green": ink("green"), "yellow": ink("yellow"), + "blue": ink("blue"), "purple": ink("purple"), "cyan": ink("cyan"), + } + + +def _block(selector: str, theme: dict) -> str: + scheme = "light" if theme["light"] else "dark" + body = "".join(f"--{name}:{value};" for name, value in tokens(theme).items()) + return f"{selector}{{color-scheme:{scheme};{body}}}\n" + + +def stylesheet(themes: list[dict]) -> str: + by_id = {theme["id"]: theme for theme in themes} + css = "/* Generated by palettes.py from the application's built-in themes. */\n" + css += _block(":root", by_id[DEFAULT_LIGHT]) + css += "@media (prefers-color-scheme: dark){\n" + _block(":root:not([data-palette])", by_id[DEFAULT_DARK]) + "}\n" + for theme in themes: + css += _block(f'html[data-palette="{theme["id"]}"]', theme) + return css + + +def code_stylesheet() -> str: + """Syntax colours that follow the active palette instead of two fixed Pygments styles.""" + groups = [ + ("var(--purple)", "k kd kn kp kr kt"), + ("var(--green)", "s s1 s2 sa sb sc sd se sh si sx sr ss"), + ("var(--yellow)", "m mb mf mh mi mo il na"), + ("var(--blue)", "nf nc fm nd ne nt"), + ("var(--cyan)", "nb bp o ow"), + ("var(--red)", "err gd gr"), + ("var(--green)", "gi"), + ] + lines = [] + for color, classes in groups: + selector = ",".join(f".code-block .{name}" for name in classes.split()) + lines.append(f"{selector}{{color:{color}}}") + comments = ",".join(f".code-block .{name}" for name in "c c1 cm cp cs ch cpf".split()) + lines.append(f"{comments}{{color:var(--muted);font-style:italic}}") + lines.append(".code-block .gh,.code-block .gu,.code-block .gs{font-weight:600}") + return "\n".join(lines) + "\n" + + +def dark_ids(themes: list[dict]) -> str: + return ",".join(f"'{theme['id']}'" for theme in themes if not theme["light"]) + + +def menu(themes: list[dict]) -> str: + def item(theme: dict) -> str: + values = tokens(theme) + return ( + f'') + + def group(title: str, light: bool) -> str: + entries = "".join(item(theme) for theme in themes if theme["light"] is light) + return f'
    {title}{entries}
    ' + + system = ('') + return system + group("浅色", True) + group("深色", False) diff --git a/docs/site/requirements.txt b/docs/site/requirements.txt new file mode 100644 index 000000000..9f922dfb6 --- /dev/null +++ b/docs/site/requirements.txt @@ -0,0 +1,2 @@ +mistune==3.2.1 +Pygments==2.20.0 diff --git a/docs/site/screenshots.json b/docs/site/screenshots.json new file mode 100644 index 000000000..1641b5c06 --- /dev/null +++ b/docs/site/screenshots.json @@ -0,0 +1,86 @@ +{ + "nebula-top-tabs.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/nebula-top-tabs.png", + "sha256": "a857a5d055fff00447e1e3ee5e36fc7b3e8618b1c7ab6c5343f26933ebd225d7", + "capture_version": "not established; do not infer from documentation version" + }, + "split-ai-workflows.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/split-ai-workflows.png", + "sha256": "2d603eb796af45bd927c8ff9a0c3dcc74ffeb6d9df8ace1b5e7a7d5d0bb1fbfb", + "capture_version": "not established; do not infer from documentation version" + }, + "nebula-claude-session.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/nebula-claude-session.png", + "sha256": "aac8e3e610c8d54a145ffe81a238f82415d3eefbe5a472d23b5adfc396352619", + "capture_version": "not established; do not infer from documentation version" + }, + "native-math-rendering.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/native-math-rendering.png", + "sha256": "c1b8e356878ebf5fe368873d37f5daa0cca2de7688129f3a05ec28c8637d6e16", + "capture_version": "not established; do not infer from documentation version" + }, + "themes.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/themes.png", + "sha256": "f8031403d4da402a8dd9388d72a7e13e3d1e31d3d7424a2a8ec0c4bbf9a04946", + "capture_version": "not established; do not infer from documentation version" + }, + "ai-sidebar.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/ai-sidebar.png", + "sha256": "df0916d23dc254b9cbc31238c47606b27466104f800ba53f663674bca4dfc4da", + "capture_version": "not established; do not infer from documentation version" + }, + "notification-duration.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/notification-duration.png", + "sha256": "bff479f36adf609b4fae95d79fcf751357cae133af46cdd9afeb1d6235fa4786", + "capture_version": "not established; do not infer from documentation version" + }, + "reader-selection-opacity.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/reader-selection-opacity.png", + "sha256": "9264f5cdb5e34a9d1f101cb561cf4a8fcbdd67146199f4e99092e46ea7a9f23a", + "capture_version": "not established; do not infer from documentation version" + }, + "hero.png": { + "kind": "existing_repository_screenshot", + "source": "https://github.com/Kuddev/pebrel/blob/9dc058d12765893553d5fc7a2c37c870c96168b0/docs/screenshots/hero.png", + "sha256": "763d24c1cfe411e6624b77fcfa9dd3da82f5d0c5f4e237f52eada418312ce687", + "capture_version": "not established; do not infer from documentation version" + }, + "pebrel-1.9.1-macos-arm64-ci.png": { + "kind": "official_release_ci_screenshot", + "version": "1.9.1", + "platform": "macOS", + "architecture": "aarch64", + "reported_os_version": "26.6.2", + "source_commit": "e9e83d83a63ca9cc885857439f7f6826c1cbabaf", + "source_tree": "601e9bdf8a43323337f6d768759b262b75a16da2", + "workflow_run": "https://github.com/Kuddev/pebrel/actions/runs/35961098033", + "artifact_id": 10792632932, + "artifact_name": "stable-evidence-macos-aarch64", + "artifact_created_at": "2026-09-24T05:58:38Z", + "artifact_sha256": "7c444586185e180881b5ee0c7b1bfadbd7cfddb72dd27ef0504fbf2973157797", + "original_path": "macos-aarch64-launch-artifacts/installed-app.png", + "sha256": "6f2b2a1b42975020ce53bc37bf85e9529dee97ca12f79f9edfc43825b2d892b9", + "modifications": "none", + "scope": "Visible native application launch with CI test text. Existing upstream run; not newly dispatched for this documentation task.", + "launch_report": { + "status": "passed", + "launch_method": "launchservices", + "commit": "e9e83d83a63ca9cc885857439f7f6826c1cbabaf", + "architecture": "aarch64", + "os_version": "26.6.2", + "quarantine_assessment": "not_tested", + "screenshot": "captured", + "rendered_text": true, + "utf8_locale": true, + "home_cwd": true + } + } +} diff --git a/docs/site/site.json b/docs/site/site.json new file mode 100644 index 000000000..aaf856bc9 --- /dev/null +++ b/docs/site/site.json @@ -0,0 +1,650 @@ +{ + "version": "2.1.1", + "source_commit": "d574856dae42f7a5142045e0b05f3eb43106fa3d", + "groups": [ + { + "title": "开始使用", + "pages": [ + { + "slug": "index", + "title": "概览", + "description": "安装 Pebrel,运行命令,连接服务器并管理项目文件。", + "sources": [ + "README.md", + "pebrel_app/src/platform/capabilities.rs" + ] + }, + { + "slug": "readme", + "title": "项目概览", + "description": "用图文方式浏览 README 中的定位、核心能力、平台下载、配置与社区信息。", + "sources": [ + "README.md", + "README.zh-CN.md", + "INSTALL.md" + ] + }, + { + "slug": "quickstart", + "title": "快速开始", + "description": "运行第一条命令,再创建标签页、分屏和 SSH 连接。", + "sources": [ + "INSTALL.md", + "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs" + ] + }, + { + "slug": "installation", + "title": "安装与平台支持", + "description": "选择适合电脑的安装包,完成安装和首次启动。", + "sources": [ + "INSTALL.md", + "pebrel_app/src/platform/capabilities.rs", + "pebrel_app/src/platform/update_installation.rs" + ] + }, + { + "slug": "workspace", + "title": "标签页与分屏", + "description": "新建、移动和关闭标签页,调整分屏大小与焦点。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/tab_menu.rs", + "pebrel_app/src/gpui_shell/workspace/pane_header.rs", + "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs" + ] + }, + { + "slug": "terminal-basics", + "sources": [ + "pebrel_app/src/gpui_shell/terminal/view.rs", + "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs", + "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs" + ], + "title": "运行命令与切换目录", + "description": "查看当前目录、执行命令、停止程序和查找历史输出。" + } + ] + }, + { + "title": "日常终端", + "pages": [ + { + "slug": "shells", + "title": "Shell 与启动目录", + "description": "选择默认 Shell,设定启动目录,添加带参数的启动入口。", + "sources": [ + "pebrel_app/src/terminal_profiles.rs", + "pebrel_app/src/gpui_shell/settings_pane/shell_picker.rs", + "docs/lua-configuration.md", + "pebrel_app/src/gpui_shell/settings_pane.rs" + ] + }, + { + "slug": "wsl", + "sources": [ + "pebrel_app/src/shell_detect.rs", + "pebrel_app/src/agent_env.rs", + "pebrel_app/src/gpui_shell/settings_pane/shell_picker.rs" + ], + "title": "使用 WSL", + "description": "打开已安装的 Linux 发行版,访问项目并运行 Linux 工具。" + }, + { + "slug": "clipboard", + "title": "选择、复制与粘贴", + "description": "复制终端输出,粘贴命令和图片,设置选中即复制。", + "sources": [ + "pebrel_app/src/gpui_shell/terminal/view/image_paste.rs", + "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs", + "pebrel_app/src/gpui_shell/workspace/send_to_chat.rs" + ] + }, + { + "slug": "completions", + "title": "命令补全与智能候选", + "description": "选择三种补齐模式,补齐 Git 分支、项目脚本、SSH 别名、路径与历史命令。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane.rs", + "pebrel_app/i18n/zh-CN.json", + "pebrel_app/src/gpui_shell/terminal/view/completion.rs", + "pebrel_app/src/completion.rs", + "pebrel_app/src/completion/connections.rs", + "pebrel_app/src/completion/project_scripts.rs", + "nebula-completions/src/semantic/common.rs" + ] + }, + { + "slug": "palette", + "title": "命令面板", + "description": "搜索并执行应用操作,快速打开设置或调整工作区。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/palette.rs", + "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs" + ] + }, + { + "slug": "commands", + "title": "保存常用命令", + "description": "保存、搜索和分组命令,选择插入文字或立即执行。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/command_manager.rs", + "pebrel_app/src/gpui_shell/workspace/command_manager/groups.rs", + "pebrel_app/src/saved_commands.rs" + ] + }, + { + "slug": "navigation", + "title": "查找与快速跳转", + "description": "切换已打开的标签,跳转目录、主机和 AI 会话。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/quick_jump.rs", + "pebrel_app/src/ai_sessions.rs" + ] + }, + { + "slug": "keyboard", + "title": "快捷键速查", + "description": "查找 Windows、macOS 和 Linux 常用快捷键,修改按键映射。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/keyboard_bindings.rs", + "pebrel_app/src/gpui_shell/settings_pane/keymap.rs" + ] + } + ] + }, + { + "title": "工作空间", + "pages": [ + { + "slug": "broadcast", + "title": "广播输入", + "description": "选择同一标签中的多个窗格,同时输入命令并退出广播。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/pane_header.rs", + "pebrel_app/src/gpui_shell/terminal/view/image_paste.rs" + ] + }, + { + "slug": "sessions", + "title": "保存与恢复会话", + "description": "设置启动时恢复标签和目录,在 Windows 中保留后台会话。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/session_persistence.rs", + "pebrel_app/src/gpui_shell/workspace/session_recovery.rs", + "pebrel_app/src/gpui_shell/session_restore.rs", + "pebrel_app/src/platform/capabilities.rs", + "pebrel_app/src/gpui_shell/settings_pane.rs" + ] + }, + { + "slug": "layouts", + "title": "保存与打开布局", + "description": "把常用标签和分屏保存为布局配方,在新窗口中打开。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/recipes/mod.rs" + ] + }, + { + "slug": "quick-terminal", + "title": "快速终端与托盘", + "description": "设置 Windows 全局热键,通过托盘召回终端或退出程序。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/quick_terminal.rs", + "pebrel_app/src/gpui_shell/settings_pane/keymap.rs", + "pebrel_app/src/platform/capabilities.rs" + ] + } + ] + }, + { + "title": "远程连接", + "pages": [ + { + "slug": "ssh", + "title": "连接 SSH 服务器", + "description": "填写连接信息、测试认证并核对服务器指纹。", + "sources": [ + "pebrel_app/src/gpui_shell/ssh_settings.rs", + "pebrel_app/src/gpui_shell/ssh_settings/editor.rs", + "pebrel_app/src/gpui_shell/workspace/ssh_dialog.rs" + ] + }, + { + "slug": "ssh-library", + "title": "管理 SSH 主机", + "description": "编辑连接,整理分组与标签,导入或导出主机列表。", + "sources": [ + "pebrel_app/src/gpui_shell/ssh_settings/library.rs", + "pebrel_app/src/gpui_shell/ssh_settings/library/exchange.rs", + "pebrel_app/src/ssh_profiles/exchange.rs", + "pebrel_app/src/ssh_profiles/organization.rs" + ] + }, + { + "slug": "ssh-auth", + "title": "密码、密钥与认证", + "description": "选择认证方式,使用私钥,并管理保存的登录凭据。", + "sources": [ + "pebrel_app/src/ssh_session/lifecycle.rs", + "pebrel_app/src/ssh_session/agent.rs", + "pebrel_app/src/ssh_credentials.rs", + "pebrel_app/src/platform/credentials.rs" + ] + }, + { + "slug": "ssh-config", + "sources": [ + "pebrel_app/src/ssh.rs", + "pebrel_app/src/ssh_session.rs", + "pebrel_app/src/gpui_shell/ssh_settings/library.rs", + "pebrel_app/src/ssh_proxy.rs" + ], + "title": "使用 SSH config", + "description": "通过别名连接服务器,读取配置中的用户名、密钥和跳板。" + }, + { + "slug": "ssh-routing", + "title": "代理与跳板机", + "description": "配置直连、代理或单级跳板,检查连接路线。", + "sources": [ + "pebrel_app/src/gpui_shell/ssh_settings/advanced.rs", + "pebrel_app/src/ssh_profiles/connection.rs", + "pebrel_app/src/ssh_session/route.rs", + "pebrel_app/src/ssh_proxy.rs" + ] + }, + { + "slug": "sftp", + "title": "SFTP 文件传输", + "description": "上传和下载文件夹,复制远端文件,处理同名文件并查看进度。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/remote_files.rs", + "pebrel_app/src/gpui_shell/workspace/remote_files/transfers.rs", + "pebrel_app/src/ssh_sftp/transfer.rs", + "pebrel_app/src/ssh_sftp/transaction.rs" + ] + }, + { + "slug": "mobile", + "title": "Android 连接电脑", + "description": "配对自己的手机、核对校验码、选择只看或允许输入,并撤销不用的设备。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/mobile/view.rs", + "pebrel_app/src/mobile_connection/preferences.rs", + "pebrel_app/i18n/zh-CN.json", + "mobile/android/app/src/main/java/io/github/kuddev/pebrel/mobile/ui/RelayForm.kt", + "mobile/android/app/src/main/java/io/github/kuddev/pebrel/mobile/ui/TerminalScreen.kt", + "mobile/android/app/src/main/res/values-zh-rCN/pairing.xml", + "mobile/android/app/build.gradle.kts", + "mobile/link/src/pairing.rs", + "mobile/link/src/endpoint/host.rs" + ] + } + ] + }, + { + "title": "文件与阅读", + "pages": [ + { + "slug": "files", + "title": "浏览与查找文件", + "description": "打开项目目录,筛选文件,在指定目录新建终端。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/file_tree.rs", + "pebrel_app/src/gpui_shell/file_preview.rs", + "pebrel_app/src/platform/file_preview.rs" + ] + }, + { + "slug": "vcs", + "title": "查看与提交 Git 改动", + "description": "查看差异、暂存文件、提交改动并与远端同步。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/vcs_panel.rs", + "pebrel_app/src/gpui_shell/workspace/vcs_panel/rows.rs", + "pebrel_app/src/gpui_shell/workspace/vcs_panel/list_model.rs" + ] + }, + { + "slug": "git-conflicts", + "sources": [ + "pebrel_app/src/gpui_shell/code_tab.rs", + "pebrel_app/src/gpui_shell/workspace/vcs_panel/rows.rs" + ], + "title": "解决 Git 冲突", + "description": "使用三栏冲突视图整理结果,保存并暂存已解决的文件。" + }, + { + "slug": "svn", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/vcs_panel.rs", + "pebrel_app/src/display/side_panel/vcs.rs" + ], + "title": "使用 SVN", + "description": "查看 SVN 工作副本的改动,执行更新和提交。" + }, + { + "slug": "documents", + "title": "阅读文档", + "description": "打开 Markdown,使用目录、代码复制和公式预览。", + "sources": [ + "pebrel_app/src/gpui_shell/file_editor/mod.rs", + "pebrel_app/src/gpui_shell/file_editor/chrome.rs", + "pebrel_app/src/gpui_shell/file_editor/code_actions.rs", + "pebrel_app/src/gpui_shell/file_editor/tests.rs" + ] + }, + { + "slug": "markdown-editing", + "sources": [ + "pebrel_app/src/gpui_shell/file_editor/mod.rs", + "pebrel_app/src/gpui_shell/file_editor/chrome.rs", + "pebrel_app/src/gpui_shell/file_editor/tests.rs" + ], + "title": "编辑 Markdown", + "description": "切换到源码,编写标题、列表、表格和公式,保存后预览。" + }, + { + "slug": "images", + "title": "查看与粘贴图片", + "description": "预览本地图片和附件,把剪贴板图片传给终端中的工具。", + "sources": [ + "pebrel_app/src/platform/file_preview.rs", + "pebrel_app/src/gpui_shell/file_preview.rs", + "pebrel_app/src/gpui_shell/terminal/view/image_paste.rs", + "README.md" + ] + }, + { + "slug": "remote-edit", + "title": "编辑服务器上的文件", + "description": "从 SFTP 面板打开文本文件,保存修改并处理冲突。", + "sources": [ + "pebrel_app/src/ssh_sftp/document.rs", + "pebrel_app/src/gpui_shell/file_editor/mod.rs", + "pebrel_app/src/gpui_shell/workspace/remote_files.rs" + ] + } + ] + }, + { + "title": "AI 工作流", + "pages": [ + { + "slug": "ai-start", + "title": "使用 AI 命令行工具", + "description": "启动 Claude Code 或 Codex,用标签、分屏和状态提示管理任务。", + "sources": [ + "README.md", + "pebrel_app/src/ai_agents.rs", + "pebrel_app/src/gpui_shell/workspace/agents.rs", + "pebrel_app/src/ai_hook/integrations.rs", + "pebrel_app/src/gpui_shell/terminal/view.rs", + "pebrel_app/src/gpui_shell/terminal/view/agent_activity.rs", + "pebrel_app/src/display/program_identity.rs" + ] + }, + { + "slug": "agents", + "title": "支持的 AI 命令行工具", + "description": "查看 Pebrel 能识别哪些 AI CLI 和 TUI,以及每个工具有哪些状态、图标和会话功能。", + "sources": [ + "pebrel_app/src/ai_agents.rs", + "pebrel_app/src/ai_hook/integrations.rs", + "pebrel_app/src/display/program_identity.rs", + "pebrel_app/src/agent_detection/_shared.toml", + "pebrel_app/src/gpui_shell/settings_pane/agents.rs" + ] + }, + { + "slug": "hooks", + "title": "配置 Agent 集成", + "description": "检测已安装的工具,配置可用集成并检查状态提示。", + "sources": [ + "pebrel_app/src/ai_hook/integrations.rs", + "pebrel_app/src/gpui_shell/settings_pane/agents.rs", + "pebrel_app/src/ai_hook/local/settings.rs", + "pebrel_app/src/platform/capabilities.rs", + "pebrel_app/src/cli.rs", + "pebrel_app/src/ssh_session/integration.rs", + "pebrel_settings/src/agent_hooks.rs", + "pebrel_app/src/ai_hook/local/runtime_skills.rs" + ] + }, + { + "slug": "ai-history", + "title": "恢复与分叉 AI 对话", + "description": "查找历史会话,恢复先前对话,或从已有上下文继续新任务。", + "sources": [ + "pebrel_app/src/ai_sessions.rs", + "pebrel_app/src/gpui_shell/workspace/session_recovery.rs", + "pebrel_app/src/gpui_shell/workspace/tab_menu.rs", + "pebrel_app/src/ai_agents.rs", + "pebrel_app/src/gpui_shell/workspace/agents.rs" + ] + }, + { + "slug": "send-to-chat", + "title": "把输出发送给 AI", + "description": "选中终端文字,补充问题,再选择接收内容的 Agent。", + "sources": [ + "pebrel_app/src/gpui_shell/workspace/send_to_chat.rs" + ] + }, + { + "slug": "agent-worktrees", + "sources": [ + "docs/runtime-control-api.md", + "pebrel_app/src/git_worktree.rs", + "pebrel_app/src/gpui_shell/workspace/residency.rs" + ], + "title": "隔离 AI 工作目录", + "description": "为并行任务创建独立 Git worktree,核对目录后分配任务。" + } + ] + }, + { + "title": "个性化", + "pages": [ + { + "slug": "appearance", + "title": "调整应用外观", + "description": "更换主题和图标,选择界面密度、语言与光标样式。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/appearance.rs", + "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs", + "pebrel_app/src/gpui_shell/settings_pane/appearance_picker.rs" + ] + }, + { + "slug": "themes", + "title": "创建和导入主题", + "description": "从模板创建配色,调整颜色,导入或导出主题文件。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/theme_editor.rs", + "pebrel_app/src/gpui_shell/settings_pane/theme_transfer.rs", + "pebrel_app/src/theme_library/formats.rs", + "pebrel_app/src/gpui_shell/settings_pane/theme_advanced.rs" + ] + }, + { + "slug": "backgrounds", + "title": "背景图片与透明度", + "description": "选择壁纸、设置铺放方式,并调整图片和终端的不透明度。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs", + "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs", + "pebrel_app/src/gpui_shell/settings_pane.rs" + ] + }, + { + "slug": "fonts", + "title": "字体、字号与间距", + "description": "设置中英文字体、调整字号和间距,解决对齐与缺字问题。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/font_picker.rs", + "pebrel_app/src/gpui_shell/settings_pane/appearance.rs", + "pebrel_app/src/gpui_shell/settings_pane/appearance_advanced.rs", + "pebrel_app/src/gpui_shell/settings_pane/scrolling.rs" + ] + }, + { + "slug": "notifications", + "title": "通知与提醒", + "description": "设置 AI 消息、卡片显示时长和终端铃声。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/notifications.rs", + "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs", + "README.md", + "pebrel_app/src/platform/capabilities.rs" + ] + }, + { + "slug": "interaction", + "title": "鼠标与窗口行为", + "description": "调整复制粘贴、鼠标焦点、标签位置和新实例行为。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane.rs", + "pebrel_app/src/gpui_shell/settings_pane/setting_help.rs", + "pebrel_app/src/gpui_shell/settings_pane/navigation.rs" + ] + }, + { + "slug": "configuration", + "title": "使用 Lua 配置", + "description": "创建配置文件,检查语法和字段,修改并重载设置。", + "sources": [ + "docs/lua-configuration.md", + "pebrel_app/src/config/mod.rs" + ] + }, + { + "slug": "config-examples", + "sources": [ + "docs/lua-configuration.md", + "pebrel_app/src/config/mod.rs" + ], + "title": "常用配置示例", + "description": "复制并调整字体、Shell、环境变量和模块化配色示例。" + }, + { + "slug": "network", + "title": "网络与系统代理", + "description": "设置连接代理、测试网络,并让新终端使用系统代理环境。", + "sources": [ + "pebrel_app/src/gpui_shell/network_settings.rs", + "pebrel_app/src/update_proxy.rs", + "pebrel_app/src/ssh_proxy.rs" + ] + } + ] + }, + { + "title": "参考与帮助", + "pages": [ + { + "slug": "runtime", + "title": "命令行控制与自动化", + "description": "列出窗格、发送文本、读取输出,向指定 Agent 分配任务。", + "sources": [ + "docs/runtime-control-api.md", + "pebrel_app/src/runtime_api/cli.rs", + "pebrel_app/src/agent_env.rs" + ] + }, + { + "slug": "settings", + "title": "设置索引", + "description": "按需要完成的操作查找设置位置,了解何时需要新建会话。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/navigation.rs", + "pebrel_app/src/gpui_shell/settings_pane.rs", + "pebrel_app/src/platform/capabilities.rs" + ] + }, + { + "slug": "updates", + "title": "更新 Pebrel", + "description": "检查新版本,按照当前平台和安装方式完成升级。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/about.rs", + "pebrel_app/src/platform/update_installation.rs", + "pebrel_app/src/platform/update_installation/macos.rs", + "pebrel_app/src/update_download.rs" + ] + }, + { + "slug": "backups", + "title": "加密备份与恢复", + "description": "创建加密快照、导出迁移文件、选择恢复内容,检查密码与存储平台限制。", + "sources": [ + "pebrel_app/src/gpui_shell/settings_pane/backup.rs", + "pebrel_app/src/gpui_shell/settings_pane/backup/setup.rs", + "pebrel_app/src/gpui_shell/settings_pane/backup/view.rs", + "pebrel_app/src/gpui_shell/settings_pane/backup/operations.rs", + "pebrel_app/src/encrypted_backup.rs", + "pebrel_app/src/encrypted_backup/recovery.rs", + "pebrel_app/src/backup_remote.rs", + "pebrel_app/i18n/zh-CN.json" + ] + }, + { + "slug": "migration", + "title": "备份与迁移", + "description": "备份偏好、主机和命令,将工作环境迁移到另一台电脑。", + "sources": [ + "pebrel_app/src/brand.rs", + "docs/lua-configuration.md", + "pebrel_app/src/ssh_profiles/exchange.rs", + "pebrel_app/src/platform/credentials.rs" + ] + }, + { + "slug": "privacy", + "title": "数据与凭据", + "description": "查看本地数据的用途,管理凭据,检查分享或发送的内容。", + "sources": [ + "pebrel_app/src/platform/credentials.rs", + "pebrel_app/src/gpui_shell/workspace/send_to_chat.rs", + "pebrel_app/src/runtime_api.rs", + "pebrel_app/src/ssh_profiles/exchange.rs" + ] + }, + { + "slug": "troubleshooting", + "title": "故障排查", + "description": "处理启动、字体、SSH、文件保存和会话恢复中的常见问题。", + "sources": [ + "INSTALL.md", + "pebrel_app/src/gpui_shell/settings_pane/navigation.rs", + "pebrel_app/src/platform/capabilities.rs", + "docs/runtime-control-api.md" + ] + }, + { + "slug": "contributing", + "title": "贡献与开发", + "description": "准备开发环境,完成本地检查,并按仓库规则提交便于审查的改动。", + "sources": [ + "CONTRIBUTING.md", + "docs/project-constraints.md", + "docs/architecture.md", + "INSTALL.md" + ] + } + ] + } + ], + "images": [ + "nebula-top-tabs.png", + "split-ai-workflows.png", + "nebula-claude-session.png", + "native-math-rendering.png", + "themes.png", + "ai-sidebar.png", + "notification-duration.png", + "reader-selection-opacity.png", + "hero.png", + "pebrel-1.9.1-macos-arm64-ci.png" + ] +} diff --git a/docs/site/template.html b/docs/site/template.html new file mode 100644 index 000000000..8a5e4558f --- /dev/null +++ b/docs/site/template.html @@ -0,0 +1,59 @@ + + + + + + + + + $title · Pebrel 文档 + $canonical + + + + + + + + + +
    + Pebrel文档 + +
    + +
    + + +
    + +
    +
    + + +
    +
    + + $page_header +
    $content
    + $source_details + + +
    + +
    + +
    +

    搜索功能、设置或操作步骤。

    +
    + +
    +

    +
    + + + diff --git a/docs/site/test_site.py b/docs/site/test_site.py new file mode 100644 index 000000000..d33e5047e --- /dev/null +++ b/docs/site/test_site.py @@ -0,0 +1,184 @@ +"""Check generated navigation, rich content, and portable asset references.""" +import json +import hashlib +import tempfile +import unittest +from html.parser import HTMLParser +from pathlib import Path +from urllib.parse import unquote, urlsplit + +import palettes +from build import build, HERE, home_header, page_url, source_details + + +class Document(HTMLParser): + def __init__(self, source): + super().__init__() + self.ids = set() + self.duplicates = set() + self.references = [] + self.headings = [] + self.images_without_alt = [] + self.remote_runtime = [] + self.feed(source) + + def handle_starttag(self, tag, attrs): + values = dict(attrs) + identity = values.get('id') + if identity in self.ids: + self.duplicates.add(identity) + if identity: + self.ids.add(identity) + if tag == 'h1': + self.headings.append(tag) + if tag == 'img' and 'alt' not in values: + self.images_without_alt.append(values) + for key in ('src', 'href'): + if key in values: + self.references.append(values[key]) + resource = values.get('src') if tag == 'script' else values.get('href') if tag == 'link' and values.get('rel') == 'stylesheet' else '' + if resource and urlsplit(resource).scheme: + self.remote_runtime.append(resource) + + +class SiteTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.temp = tempfile.TemporaryDirectory() + cls.root = Path(cls.temp.name) + cls.stale_page = cls.root / 'obsolete' / 'index.html' + cls.stale_page.parent.mkdir() + cls.stale_page.write_text('stale output') + (cls.root / 'build-info.json').write_text('{}') + (cls.root / '.nojekyll').touch() + cls.report = build(cls.root, 'https://example.org/pebrel/') + cls.documents = { + path.resolve(): Document(path.read_text()) + for path in cls.root.rglob('*.html') + } + + @classmethod + def tearDownClass(cls): + cls.temp.cleanup() + + def test_build_removes_stale_output(self): + self.assertFalse(self.stale_page.exists()) + + def test_build_preserves_unrelated_output(self): + with tempfile.TemporaryDirectory() as temp: + output = Path(temp) + sentinel = output / 'user-data.txt' + sentinel.write_text('keep') + with self.assertRaisesRegex(ValueError, 'not a generated site'): + build(output, '') + self.assertEqual(sentinel.read_text(), 'keep') + + def test_build_does_not_remove_source_directories(self): + with self.assertRaisesRegex(ValueError, 'overlaps repository sources'): + build(HERE, '') + + def test_internal_links_and_fragments(self): + for path, document in self.documents.items(): + for reference in document.references: + url = urlsplit(reference) + if url.scheme or url.netloc: + continue + target = (path.parent / unquote(url.path)).resolve() if url.path else path + if target.is_dir(): + target /= 'index.html' + with self.subTest(page=path.name, link=reference): + self.assertTrue(target.is_relative_to(self.root), 'Link escapes site root') + self.assertTrue(target.is_file(), f'Missing local destination: {target}') + if url.fragment and target in self.documents: + self.assertIn(unquote(url.fragment), self.documents[target].ids) + + def test_homepage_hero_has_no_eyebrow_or_description(self): + header = home_header() + hero = header.split('', 1)[0] + self.assertNotIn('eyebrow', hero) + self.assertNotIn('