chore: prepare Desktop 0.12.12 release

Bump the desktop patch version and package matching Chinese and English notes
for image follow-up context, retained questions and answers, simpler Runtime
selection, and docked Git history with automatic project detection.

Review and align both feature matrices with the verified release range.
Agent stays at 0.11.23; no Agent release or LoongArch preview is included.
External knowledge probe tooling remains development-only, not a shipped
external knowledge-base feature.

Validation: 3911 tests passed, 66 skipped; typecheck, lint, and bilingual
release-note verification passed. Production builds use main-branch CI before
the immutable desktop tag; no local production package was built.

.github/workflows/agent-release.yml

@@ -0,0 +1,617 @@
+name: GoodBuddy Agent Release
+
+on:
+  push:
+    tags:
+      - 'agent-v*'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: agent-release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  authorize:
+    name: Authorize Agent release
+    if: >-
+      github.ref_type == 'tag' &&
+      startsWith(github.ref_name, 'agent-v')
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    outputs:
+      authorized: ${{ steps.policy.outputs.authorized }}
+      version: ${{ steps.policy.outputs.version }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Verify immutable Agent release tag
+        id: policy
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(node -p "require('./agent-runtime-lock.json').agentVersion")"
+          expected="agent-v$version"
+          test "$GITHUB_REF_NAME" = "$expected"
+          test "$(git cat-file -t "refs/tags/$GITHUB_REF_NAME")" = "tag"
+          test "$(git rev-parse "refs/tags/$GITHUB_REF_NAME^{commit}")" = "$GITHUB_SHA"
+          git fetch --no-tags origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" refs/remotes/origin/main
+          echo "authorized=true" >> "$GITHUB_OUTPUT"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+  build:
+    name: Build ${{ matrix.platform }} ${{ matrix.arch }} compound package
+    needs: authorize
+    if: needs.authorize.outputs.authorized == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux
+            arch: x64
+            runner: ubuntu-24.04
+          - platform: linux
+            arch: arm64
+            runner: ubuntu-24.04-arm
+          - platform: darwin
+            arch: arm64
+            runner: macos-15
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 25
+    environment:
+      name: agent-signing
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24.19.0
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify native build target
+        run: node -e "if(process.platform !== '${{ matrix.platform }}' || process.arch !== '${{ matrix.arch }}') throw new Error('Native Agent target mismatch')"
+
+      - name: Resolve locked native inputs
+        id: inputs
+        shell: bash
+        env:
+          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
+        run: |
+          set -euo pipefail
+          node - <<'NODE'
+          const { appendFileSync } = require('node:fs')
+          const { createHash } = require('node:crypto')
+          const agent = require('./agent-runtime-lock.json')
+          const remote = require('./remote-runtime-lock.json')
+          const node = agent.node?.targets?.[`${process.env.AGENT_PLATFORM}-${process.env.AGENT_ARCH}`]
+          const runtime = remote.runtimes?.opencode
+          const runtimeKey = process.env.AGENT_PLATFORM === 'linux'
+            ? process.env.AGENT_ARCH : `${process.env.AGENT_PLATFORM}-${process.env.AGENT_ARCH}`
+          const opencode = runtime?.targets?.[runtimeKey]
+          if (
+            !node ||
+            !opencode ||
+            !/^[A-Za-z0-9._-]+\.tar\.gz$/u.test(node.archive) ||
+            !/^[a-f0-9]{64}$/u.test(node.sha256) ||
+            !/^[a-z0-9][a-z0-9._-]*$/u.test(opencode.package) ||
+            !/^sha512-[A-Za-z0-9+/]+={0,2}$/u.test(opencode.integrity)
+          ) {
+            throw new Error('Locked native Agent package inputs are invalid')
+          }
+          const nodeUrl = new URL(node.archive, agent.node.source)
+          if (
+            nodeUrl.protocol !== 'https:' ||
+            nodeUrl.hostname !== 'nodejs.org' ||
+            nodeUrl.username ||
+            nodeUrl.password ||
+            nodeUrl.search ||
+            nodeUrl.hash
+          ) {
+            throw new Error('Agent Node runtime must use the official HTTPS origin')
+          }
+          const opencodeArchive =
+            `${opencode.package}-${runtime.version}.tgz`
+          appendFileSync(
+            process.env.GITHUB_OUTPUT,
+            [
+              `node-archive=${node.archive}`,
+              `node-sha256=${node.sha256}`,
+              `node-url=${nodeUrl.href}`,
+              `opencode-package=${opencode.package}`,
+              `opencode-version=${runtime.version}`,
+              `opencode-integrity=${opencode.integrity}`,
+              `opencode-archive=${opencodeArchive}`,
+              `cache-key=${createHash('sha256')
+                .update(`${node.sha256}:${opencode.integrity}`)
+                .digest('hex')}`,
+              ''
+            ].join('\n')
+          )
+          NODE
+
+      - name: Cache verified native inputs
+        uses: actions/cache@v6
+        with:
+          path: ${{ runner.temp }}/goodbuddy-agent-release-inputs
+          key: goodbuddy-agent-release-${{ matrix.platform }}-${{ matrix.arch }}-${{ steps.inputs.outputs.cache-key }}
+
+      - name: Acquire and verify native inputs
+        shell: bash
+        env:
+          NODE_ARCHIVE: ${{ steps.inputs.outputs.node-archive }}
+          NODE_SHA256: ${{ steps.inputs.outputs.node-sha256 }}
+          NODE_URL: ${{ steps.inputs.outputs.node-url }}
+          OPENCODE_ARCHIVE: ${{ steps.inputs.outputs.opencode-archive }}
+          OPENCODE_INTEGRITY: ${{ steps.inputs.outputs.opencode-integrity }}
+          OPENCODE_PACKAGE: ${{ steps.inputs.outputs.opencode-package }}
+          OPENCODE_VERSION: ${{ steps.inputs.outputs.opencode-version }}
+        run: |
+          set -euo pipefail
+          directory="$RUNNER_TEMP/goodbuddy-agent-release-inputs"
+          mkdir -p "$directory"
+          node_archive="$directory/$NODE_ARCHIVE"
+          if [[ ! -f "$node_archive" ]]; then
+            curl --proto '=https' --tlsv1.2 \
+              --fail --silent --show-error --location \
+              --retry 3 --retry-all-errors \
+              --connect-timeout 15 --max-time 300 \
+              --max-filesize 104857600 \
+              "$NODE_URL" --output "$node_archive.partial"
+            mv "$node_archive.partial" "$node_archive"
+          fi
+          node - "$node_archive" "$NODE_SHA256" <<'NODE'
+          const { createHash } = require('node:crypto')
+          const { readFileSync } = require('node:fs')
+          const [archive, expected] = process.argv.slice(2)
+          if (createHash('sha256').update(readFileSync(archive)).digest('hex') !== expected) {
+            throw new Error('Node runtime archive integrity mismatch')
+          }
+          NODE
+
+          opencode_archive="$directory/$OPENCODE_ARCHIVE"
+          if [[ ! -f "$opencode_archive" ]]; then
+            npm pack \
+              --ignore-scripts \
+              --registry https://registry.npmjs.org/ \
+              --pack-destination "$directory" \
+              "$OPENCODE_PACKAGE@$OPENCODE_VERSION"
+          fi
+          node - "$opencode_archive" "$OPENCODE_INTEGRITY" <<'NODE'
+          const { createHash } = require('node:crypto')
+          const { readFileSync, statSync } = require('node:fs')
+          const [archive, expected] = process.argv.slice(2)
+          const size = statSync(archive).size
+          if (size <= 0 || size > 536870912) {
+            throw new Error('OpenCode Runtime archive exceeds its safety limit')
+          }
+          const actual = `sha512-${createHash('sha512')
+            .update(readFileSync(archive))
+            .digest('base64')}`
+          if (actual !== expected) {
+            throw new Error('OpenCode Runtime archive integrity mismatch')
+          }
+          NODE
+
+      - name: Preflight production GoodBuddy signing identity
+        shell: bash
+        env:
+          GOODBUDDY_SIGNING_KEY_ID: ${{ vars.GOODBUDDY_SIGNING_KEY_ID }}
+        run: |
+          set -euo pipefail
+          node build/agent-bundle.cjs preflight
+
+      - name: Build production compound Agent package
+        shell: bash
+        env:
+          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+          GOODBUDDY_SIGNING_KEY_ID: ${{ vars.GOODBUDDY_SIGNING_KEY_ID }}
+          GOODBUDDY_SIGNING_PRIVATE_KEY: ${{ secrets.GOODBUDDY_SIGNING_PRIVATE_KEY }}
+          NODE_ARCHIVE: ${{ steps.inputs.outputs.node-archive }}
+          OPENCODE_ARCHIVE: ${{ steps.inputs.outputs.opencode-archive }}
+        run: |
+          set -euo pipefail
+          output="$RUNNER_TEMP/goodbuddy-agent-output"
+          mkdir -p "$output"
+          node build/agent-package.cjs build \
+            --platform "$AGENT_PLATFORM" \
+            --arch "$AGENT_ARCH" \
+            --minimum-desktop-version "$(node -p "require('./package.json').version")" \
+            --node-archive "$RUNNER_TEMP/goodbuddy-agent-release-inputs/$NODE_ARCHIVE" \
+            --runtime-archive "$RUNNER_TEMP/goodbuddy-agent-release-inputs/$OPENCODE_ARCHIVE" \
+            --output "$output/goodbuddy-agent-$AGENT_VERSION-$AGENT_PLATFORM-$AGENT_ARCH.gbagent" \
+            > "$output/result.json"
+          node - "$output/result.json" "$AGENT_ARCH" "$AGENT_VERSION" <<'NODE'
+          const { readFileSync } = require('node:fs')
+          const [resultPath, architecture, version] = process.argv.slice(2)
+          const result = JSON.parse(readFileSync(resultPath, 'utf8'))
+          if (
+            result.descriptor?.architecture !== architecture ||
+            result.descriptor?.platform !== process.env.AGENT_PLATFORM ||
+            result.descriptor?.version !== version ||
+            result.archive !==
+              `goodbuddy-agent-${version}-${process.env.AGENT_PLATFORM}-${architecture}.gbagent` ||
+            !/^[a-f0-9]{64}$/u.test(result.sha256)
+          ) {
+            throw new Error('Production Agent package result is invalid')
+          }
+          NODE
+
+      - name: Upload verified compound package
+        uses: actions/upload-artifact@v7
+        with:
+          name: goodbuddy-agent-package-${{ matrix.platform }}-${{ matrix.arch }}
+          path: ${{ runner.temp }}/goodbuddy-agent-output/goodbuddy-agent-*.gbagent
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 7
+
+  catalog:
+    name: Sign cumulative Agent catalog
+    needs:
+      - authorize
+      - build
+    if: needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: agent-signing
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24.19.0
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Download compound packages
+        uses: actions/download-artifact@v8
+        with:
+          pattern: goodbuddy-agent-package-*
+          path: dist/agent-release
+          merge-multiple: true
+
+      - name: Fetch previous signed catalog when available
+        id: previous
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+        run: |
+          set -euo pipefail
+          root="https://goodbuddy.oss-cn-beijing.aliyuncs.com/agent-releases"
+          current_catalog_status="$(
+            curl --silent --show-error \
+              --output dist/agent-release/previous.json \
+              --write-out '%{http_code}' \
+              "$root/v$AGENT_VERSION/agent-catalog.json"
+          )"
+          current_signature_status="$(
+            curl --silent --show-error \
+              --output dist/agent-release/previous.sig \
+              --write-out '%{http_code}' \
+              "$root/v$AGENT_VERSION/agent-catalog.sig"
+          )"
+          if [[ "$current_catalog_status" == 200 && "$current_signature_status" == 200 ]]; then
+            echo "arguments=--previous-catalog dist/agent-release/previous.json --previous-signature dist/agent-release/previous.sig" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [[ "$current_catalog_status" != 404 || "$current_signature_status" != 404 ]]; then
+            echo "Current Agent catalog objects are inconsistent: $current_catalog_status / $current_signature_status" >&2
+            exit 1
+          fi
+          rm -f dist/agent-release/previous.json dist/agent-release/previous.sig
+          pointer_status="$(
+            curl --silent --show-error \
+              --output dist/agent-release/previous-pointer.json \
+              --write-out '%{http_code}' \
+              "$root/latest.json"
+          )"
+          if [[ "$pointer_status" == 200 ]]; then
+          readarray -t paths < <(
+          node - dist/agent-release/previous-pointer.json <<'NODE'
+          const { readFileSync } = require('node:fs')
+          const pointer = JSON.parse(readFileSync(process.argv[2], 'utf8'))
+          if (
+            pointer?.formatVersion !== 1 ||
+            !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(pointer.version) ||
+            pointer.catalog !== `v${pointer.version}/agent-catalog.json` ||
+            pointer.signature !== `v${pointer.version}/agent-catalog.sig`
+          ) {
+            throw new Error('Previous Agent catalog pointer is invalid')
+          }
+          process.stdout.write(`${pointer.catalog}\n${pointer.signature}\n`)
+          NODE
+          )
+            curl --fail --silent --show-error \
+              "$root/${paths[0]}" \
+              --output dist/agent-release/previous.json
+            curl --fail --silent --show-error \
+              "$root/${paths[1]}" \
+              --output dist/agent-release/previous.sig
+            echo "arguments=--previous-catalog dist/agent-release/previous.json --previous-signature dist/agent-release/previous.sig" >> "$GITHUB_OUTPUT"
+          elif [[ "$pointer_status" == 404 ]]; then
+            rm -f dist/agent-release/previous-pointer.json
+            echo "arguments=" >> "$GITHUB_OUTPUT"
+          else
+            echo "Agent catalog pointer request failed: $pointer_status" >&2
+            exit 1
+          fi
+
+      - name: Sign cumulative Agent catalog
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+          PREVIOUS_ARGUMENTS: ${{ steps.previous.outputs.arguments }}
+          GOODBUDDY_SIGNING_KEY_ID: ${{ vars.GOODBUDDY_SIGNING_KEY_ID }}
+          GOODBUDDY_SIGNING_PRIVATE_KEY: ${{ secrets.GOODBUDDY_SIGNING_PRIVATE_KEY }}
+        run: |
+          set -euo pipefail
+          generated_at="$(git show -s --format=%cI "$GITHUB_SHA")"
+          read -r -a previous <<< "$PREVIOUS_ARGUMENTS"
+          node build/agent-catalog.cjs create \
+            --x64-package "dist/agent-release/goodbuddy-agent-$AGENT_VERSION-linux-x64.gbagent" \
+            --arm64-package "dist/agent-release/goodbuddy-agent-$AGENT_VERSION-linux-arm64.gbagent" \
+            --darwin-arm64-package "dist/agent-release/goodbuddy-agent-$AGENT_VERSION-darwin-arm64.gbagent" \
+            "${previous[@]}" \
+            --catalog dist/agent-release/agent-catalog.json \
+            --signature dist/agent-release/agent-catalog.sig \
+            --generated-at "$generated_at"
+          node build/agent-catalog.cjs verify \
+            --catalog dist/agent-release/agent-catalog.json \
+            --signature dist/agent-release/agent-catalog.sig
+
+      - name: Upload signed release set
+        uses: actions/upload-artifact@v7
+        with:
+          name: goodbuddy-agent-release-${{ needs.authorize.outputs.version }}
+          path: |
+            dist/agent-release/goodbuddy-agent-*.gbagent
+            dist/agent-release/agent-catalog.json
+            dist/agent-release/agent-catalog.sig
+          if-no-files-found: error
+          compression-level: 0
+          retention-days: 7
+
+  publish:
+    name: Publish Agent to GitHub and OSS
+    needs:
+      - authorize
+      - catalog
+    if: needs.authorize.outputs.authorized == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    environment:
+      name: aliyun-oss-release
+    permissions:
+      contents: write
+      actions: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24.19.0
+
+      - name: Install verification dependencies
+        run: npm ci
+
+      - name: Download signed release set
+        uses: actions/download-artifact@v8
+        with:
+          name: goodbuddy-agent-release-${{ needs.authorize.outputs.version }}
+          path: dist/agent-release
+
+      - name: Verify signed release set
+        run: |
+          node build/agent-catalog.cjs verify \
+            --catalog dist/agent-release/agent-catalog.json \
+            --signature dist/agent-release/agent-catalog.sig
+
+      - name: Verify OSS release configuration
+        shell: bash
+        env:
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+          OIDC_PROVIDER_ARN: ${{ vars.ALIYUN_OIDC_PROVIDER_ARN }}
+          ROLE_ARN: ${{ vars.ALIYUN_ROLE_ARN }}
+        run: |
+          set -euo pipefail
+          test "$OSS_BUCKET" = "goodbuddy"
+          test "$OSS_ENDPOINT" = "https://oss-cn-beijing.aliyuncs.com"
+          case "$OIDC_PROVIDER_ARN" in
+            acs:ram::*:oidc-provider/*) ;;
+            *) echo "OIDC Provider ARN 无效" >&2; exit 1 ;;
+          esac
+          case "$ROLE_ARN" in
+            acs:ram::*:role/*) ;;
+            *) echo "RAM Role ARN 无效" >&2; exit 1 ;;
+          esac
+
+      - name: Authenticate to Alibaba Cloud
+        uses: aliyun/configure-aliyun-credentials-action@v1
+        with:
+          role-to-assume: ${{ vars.ALIYUN_ROLE_ARN }}
+          oidc-provider-arn: ${{ vars.ALIYUN_OIDC_PROVIDER_ARN }}
+          role-session-name: goodbuddy-agent-${{ github.run_id }}
+          role-session-expiration: 3600
+          audience: sts.aliyuncs.com
+
+      - name: Install ossutil
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="2.3.0"
+          archive="$RUNNER_TEMP/ossutil.zip"
+          directory="$RUNNER_TEMP/ossutil"
+          curl --fail --silent --show-error --location \
+            "https://gosspublic.alicdn.com/ossutil/v2/$version/ossutil-$version-linux-amd64.zip" \
+            --output "$archive"
+          mkdir "$directory"
+          unzip -q "$archive" -d "$directory"
+          binary="$(find "$directory" -type f -name ossutil -print -quit)"
+          test -n "$binary"
+          chmod +x "$binary"
+          echo "$(dirname "$binary")" >> "$GITHUB_PATH"
+
+      - name: Upload immutable Agent release to OSS
+        id: oss
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+        run: |
+          set -euo pipefail
+          export OSS_ACCESS_KEY_ID="$ALIBABA_CLOUD_ACCESS_KEY_ID"
+          export OSS_ACCESS_KEY_SECRET="$ALIBABA_CLOUD_ACCESS_KEY_SECRET"
+          export OSS_SESSION_TOKEN="$ALIBABA_CLOUD_SECURITY_TOKEN"
+          endpoint_host="${OSS_ENDPOINT#https://}"
+          region="${endpoint_host#oss-}"
+          region="${region%.aliyuncs.com}"
+          test "$region" = "cn-beijing"
+          for file in dist/agent-release/*; do
+            name="$(basename "$file")"
+            ossutil cp "$file" \
+              "oss://${OSS_BUCKET}/agent-releases/v${AGENT_VERSION}/${name}" \
+              --endpoint "$OSS_ENDPOINT" \
+              --region "$region" \
+              --update
+          done
+          echo "region=$region" >> "$GITHUB_OUTPUT"
+
+      - name: Verify public immutable OSS packages
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+        run: |
+          set -euo pipefail
+          root="https://goodbuddy.oss-cn-beijing.aliyuncs.com/agent-releases/v$AGENT_VERSION"
+          for target in linux-x64 linux-arm64 darwin-arm64; do
+            name="goodbuddy-agent-$AGENT_VERSION-$target.gbagent"
+            curl --fail --silent --show-error --location \
+              "$root/$name" --output "$RUNNER_TEMP/$name"
+            cmp "dist/agent-release/$name" "$RUNNER_TEMP/$name"
+          done
+          for name in agent-catalog.json agent-catalog.sig; do
+            curl --fail --silent --show-error --location \
+              "$root/$name" --output "$RUNNER_TEMP/immutable-$name"
+            cmp "dist/agent-release/$name" \
+              "$RUNNER_TEMP/immutable-$name"
+          done
+
+      - name: Publish non-Latest GitHub Agent release
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          tag="agent-v$AGENT_VERSION"
+          title="GoodBuddy Agent $AGENT_VERSION"
+          notes="resources/agent-release-notes/$AGENT_VERSION.md"
+          test -s "$notes"
+          if gh release view "$tag" >/dev/null 2>&1; then
+            is_draft="$(gh release view "$tag" --json isDraft --jq .isDraft)"
+            if [[ "$is_draft" == true ]]; then
+              gh release edit "$tag" \
+                --title "$title" \
+                --notes-file "$notes" \
+                --latest=false
+              gh release upload "$tag" dist/agent-release/* --clobber
+              gh release edit "$tag" --draft=false --latest=false
+            else
+              verify="$RUNNER_TEMP/github-agent-release"
+              mkdir "$verify"
+              gh release download "$tag" --dir "$verify"
+              for file in dist/agent-release/*; do
+                cmp "$file" "$verify/$(basename "$file")"
+              done
+            fi
+          else
+            gh release create "$tag" \
+              --draft \
+              --verify-tag \
+              --title "$title" \
+              --notes-file "$notes" \
+              --latest=false
+            gh release upload "$tag" dist/agent-release/* --clobber
+            gh release edit "$tag" --draft=false --latest=false
+          fi
+          test "$(gh api repos/mesalogo/goodbuddy/releases/latest --jq .tag_name)" != "$tag"
+
+      - name: Point OSS Agent catalog to published release
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+          OSS_REGION: ${{ steps.oss.outputs.region }}
+        run: |
+          set -euo pipefail
+          export OSS_ACCESS_KEY_ID="$ALIBABA_CLOUD_ACCESS_KEY_ID"
+          export OSS_ACCESS_KEY_SECRET="$ALIBABA_CLOUD_ACCESS_KEY_SECRET"
+          export OSS_SESSION_TOKEN="$ALIBABA_CLOUD_SECURITY_TOKEN"
+          node - "$AGENT_VERSION" > dist/agent-release/latest.json <<'NODE'
+          const version = process.argv[2]
+          process.stdout.write(`${JSON.stringify({
+            formatVersion: 1,
+            version,
+            catalog: `v${version}/agent-catalog.json`,
+            signature: `v${version}/agent-catalog.sig`
+          }, null, 2)}\n`)
+          NODE
+          ossutil cp dist/agent-release/latest.json \
+            "oss://${OSS_BUCKET}/agent-releases/latest.json" \
+            --endpoint "$OSS_ENDPOINT" \
+            --region "$OSS_REGION" \
+            --force
+
+      - name: Verify public Agent catalogs
+        shell: bash
+        env:
+          AGENT_VERSION: ${{ needs.authorize.outputs.version }}
+        run: |
+          set -euo pipefail
+          mirror="https://goodbuddy.oss-cn-beijing.aliyuncs.com/agent-releases"
+          github="https://github.com/mesalogo/goodbuddy/releases/download/agent-v$AGENT_VERSION"
+          curl --fail --silent --show-error --location \
+            "$mirror/latest.json" --output "$RUNNER_TEMP/mirror-pointer.json"
+          curl --fail --silent --show-error --location \
+            "$mirror/v$AGENT_VERSION/agent-catalog.json" \
+            --output "$RUNNER_TEMP/mirror.json"
+          curl --fail --silent --show-error --location \
+            "$mirror/v$AGENT_VERSION/agent-catalog.sig" \
+            --output "$RUNNER_TEMP/mirror.sig"
+          curl --fail --silent --show-error --location \
+            "$github/agent-catalog.json" --output "$RUNNER_TEMP/github.json"
+          curl --fail --silent --show-error --location \
+            "$github/agent-catalog.sig" --output "$RUNNER_TEMP/github.sig"
+          cmp dist/agent-release/latest.json "$RUNNER_TEMP/mirror-pointer.json"
+          cmp dist/agent-release/agent-catalog.json "$RUNNER_TEMP/mirror.json"
+          cmp dist/agent-release/agent-catalog.sig "$RUNNER_TEMP/mirror.sig"
+          cmp dist/agent-release/agent-catalog.json "$RUNNER_TEMP/github.json"
+          cmp dist/agent-release/agent-catalog.sig "$RUNNER_TEMP/github.sig"

.github/workflows/agents.yml

@@ -0,0 +1,353 @@
+name: GoodBuddy Agents
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - '.github/workflows/agents.yml'
+      - 'agent-runtime-lock.json'
+      - 'build/agent-bundle.cjs'
+      - 'build/agent-package.cjs'
+      - 'build/agent-ci-bundle.cjs'
+      - 'build/agent-build-target.cjs'
+      - 'build/binary-architecture.cjs'
+      - 'build/file-hash.cjs'
+      - 'build/remote-runtime-bundle.cjs'
+      - 'build/signing-key-preflight.cjs'
+      - 'package-lock.json'
+      - 'package.json'
+      - 'resources/agent-release-keys.json'
+      - 'remote-runtime-lock.json'
+      - 'src/agent-daemon/**'
+      - 'src/shared/**'
+      - 'tests/agent-bundle.test.ts'
+      - 'tests/agent-darwin-build.test.ts'
+      - 'tests/agent-package.test.ts'
+      - 'tests/agents-workflow.test.ts'
+      - 'tests/remote-runtime-bundle.test.ts'
+  push:
+    branches:
+      - main
+    paths:
+      - '.github/workflows/agents.yml'
+      - 'agent-runtime-lock.json'
+      - 'build/agent-bundle.cjs'
+      - 'build/agent-package.cjs'
+      - 'build/agent-ci-bundle.cjs'
+      - 'build/agent-build-target.cjs'
+      - 'build/binary-architecture.cjs'
+      - 'build/file-hash.cjs'
+      - 'build/remote-runtime-bundle.cjs'
+      - 'build/signing-key-preflight.cjs'
+      - 'package-lock.json'
+      - 'package.json'
+      - 'resources/agent-release-keys.json'
+      - 'remote-runtime-lock.json'
+      - 'src/agent-daemon/**'
+      - 'src/shared/**'
+      - 'tests/agent-bundle.test.ts'
+      - 'tests/agent-darwin-build.test.ts'
+      - 'tests/agent-package.test.ts'
+      - 'tests/agents-workflow.test.ts'
+      - 'tests/remote-runtime-bundle.test.ts'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: agents-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate Agent source
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24.19.0
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate Agent source and workflow
+        run: |
+          npm test -- \
+            tests/agent-bundle.test.ts \
+            tests/agent-darwin-build.test.ts \
+            tests/agent-package.test.ts \
+            tests/remote-runtime-bundle.test.ts \
+            tests/agents-workflow.test.ts
+          npm run typecheck
+
+  build:
+    name: Build ${{ matrix.platform }} ${{ matrix.arch }} Agent
+    needs: validate
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux
+            arch: x64
+            runner: ubuntu-24.04
+          - platform: linux
+            arch: arm64
+            runner: ubuntu-24.04-arm
+          - platform: darwin
+            arch: arm64
+            runner: macos-15
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24.19.0
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Verify native runner target
+        run: node -e "if (process.platform !== '${{ matrix.platform }}' || process.arch !== '${{ matrix.arch }}') throw new Error('Agent CI requires the native target')"
+
+      - name: Resolve locked official Node runtime
+        id: runtime
+        shell: bash
+        env:
+          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
+        run: |
+          set -euo pipefail
+          node - <<'NODE'
+          const { appendFileSync } = require('node:fs')
+          const { lock } = require('./build/agent-ci-bundle.cjs').readCiLocks(
+            process.env.AGENT_PLATFORM, process.env.AGENT_ARCH
+          )
+          const target = lock.node?.targets?.[`${process.env.AGENT_PLATFORM}-${process.env.AGENT_ARCH}`]
+          if (
+            !target ||
+            !/^[A-Za-z0-9._-]+\.tar\.gz$/u.test(target.archive) ||
+            !/^[a-f0-9]{64}$/u.test(target.sha256)
+          ) {
+            throw new Error('Locked Agent Node runtime metadata is invalid')
+          }
+          const url = new URL(target.archive, lock.node.source)
+          if (
+            url.protocol !== 'https:' ||
+            url.hostname !== 'nodejs.org' ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash
+          ) {
+            throw new Error('Agent Node runtime must use the official HTTPS origin')
+          }
+          appendFileSync(
+            process.env.GITHUB_OUTPUT,
+            [
+              `archive=${target.archive}`,
+              `sha256=${target.sha256}`,
+              `url=${url.href}`,
+              ''
+            ].join('\n')
+          )
+          NODE
+
+      - name: Cache verified Node runtime input
+        uses: actions/cache@v6
+        with:
+          path: ${{ runner.temp }}/goodbuddy-agent-node
+          key: goodbuddy-agent-ci-node-${{ matrix.platform }}-${{ matrix.arch }}-${{ steps.runtime.outputs.sha256 }}
+
+      - name: Acquire and verify locked Node runtime
+        shell: bash
+        env:
+          NODE_ARCHIVE: ${{ steps.runtime.outputs.archive }}
+          NODE_SHA256: ${{ steps.runtime.outputs.sha256 }}
+          NODE_URL: ${{ steps.runtime.outputs.url }}
+        run: |
+          set -euo pipefail
+          directory="$RUNNER_TEMP/goodbuddy-agent-node"
+          archive="$directory/$NODE_ARCHIVE"
+          mkdir -p "$directory"
+          if [[ ! -f "$archive" ]]; then
+            rm -f "$archive.partial"
+            curl --proto '=https' --tlsv1.2 \
+              --fail --silent --show-error --location \
+              --retry 3 --retry-all-errors \
+              --connect-timeout 15 --max-time 300 \
+              --max-filesize 104857600 \
+              "$NODE_URL" --output "$archive.partial"
+            mv "$archive.partial" "$archive"
+          fi
+          node - "$archive" "$NODE_SHA256" <<'NODE'
+          const { createHash } = require('node:crypto')
+          const { readFileSync } = require('node:fs')
+          const [archive, expected] = process.argv.slice(2)
+          if (createHash('sha256').update(readFileSync(archive)).digest('hex') !== expected) {
+            throw new Error('Node runtime archive integrity mismatch')
+          }
+          NODE
+
+      - name: Resolve locked OpenCode Runtime
+        id: opencode
+        shell: bash
+        env:
+          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
+        run: |
+          set -euo pipefail
+          node - <<'NODE'
+          const { appendFileSync } = require('node:fs')
+          const { createHash: hash } = require('node:crypto')
+          const { runtimeLock } = require('./build/agent-ci-bundle.cjs').readCiLocks(
+            process.env.AGENT_PLATFORM, process.env.AGENT_ARCH
+          )
+          const runtime = runtimeLock.runtimes?.opencode
+          const key = process.env.AGENT_PLATFORM === 'linux'
+            ? process.env.AGENT_ARCH
+            : `${process.env.AGENT_PLATFORM}-${process.env.AGENT_ARCH}`
+          const target = runtime?.targets?.[key]
+          if (
+            !runtime ||
+            !target ||
+            !/^[a-z0-9][a-z0-9._-]*$/u.test(target.package) ||
+            !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(runtime.version) ||
+            !/^sha512-[A-Za-z0-9+/]+={0,2}$/u.test(target.integrity)
+          ) {
+            throw new Error('Locked OpenCode Runtime metadata is invalid')
+          }
+          const archive = `${target.package}-${runtime.version}.tgz`
+          appendFileSync(
+            process.env.GITHUB_OUTPUT,
+            [
+              `package=${target.package}`,
+              `version=${runtime.version}`,
+              `integrity=${target.integrity}`,
+              `archive=${archive}`,
+              `cache-key=${hash('sha256').update(target.integrity).digest('hex')}`,
+              ''
+            ].join('\n')
+          )
+          NODE
+
+      - name: Cache verified OpenCode Runtime input
+        uses: actions/cache@v6
+        with:
+          path: ${{ runner.temp }}/goodbuddy-opencode-runtime
+          key: goodbuddy-agent-ci-opencode-${{ matrix.platform }}-${{ matrix.arch }}-${{ steps.opencode.outputs.cache-key }}
+
+      - name: Acquire and verify locked OpenCode Runtime
+        shell: bash
+        env:
+          OPENCODE_ARCHIVE: ${{ steps.opencode.outputs.archive }}
+          OPENCODE_INTEGRITY: ${{ steps.opencode.outputs.integrity }}
+          OPENCODE_PACKAGE: ${{ steps.opencode.outputs.package }}
+          OPENCODE_VERSION: ${{ steps.opencode.outputs.version }}
+        run: |
+          set -euo pipefail
+          directory="$RUNNER_TEMP/goodbuddy-opencode-runtime"
+          archive="$directory/$OPENCODE_ARCHIVE"
+          mkdir -p "$directory"
+          if [[ ! -f "$archive" ]]; then
+            npm pack \
+              --ignore-scripts \
+              --registry https://registry.npmjs.org/ \
+              --pack-destination "$directory" \
+              "$OPENCODE_PACKAGE@$OPENCODE_VERSION"
+          fi
+          node - "$archive" "$OPENCODE_INTEGRITY" <<'NODE'
+          const { createHash } = require('node:crypto')
+          const { readFileSync, statSync } = require('node:fs')
+          const [archive, expected] = process.argv.slice(2)
+          const size = statSync(archive).size
+          if (size <= 0 || size > 536870912) {
+            throw new Error('OpenCode Runtime archive exceeds its safety limit')
+          }
+          const actual = `sha512-${createHash('sha512')
+            .update(readFileSync(archive))
+            .digest('base64')}`
+          if (actual !== expected) {
+            throw new Error('OpenCode Runtime archive integrity mismatch')
+          }
+          NODE
+
+      - name: Run native Agent regressions
+        if: matrix.platform == 'linux'
+        run: |
+          npm test -- \
+            src/agent-daemon/model-bridge.test.ts \
+            src/agent-daemon/lifecycle.test.ts
+
+      - name: Run native macOS process regressions
+        if: matrix.platform == 'darwin'
+        run: npm test -- src/agent-daemon/darwin-process-identity.test.ts
+
+      - name: Build and verify ephemeral signed compound Agent package twice
+        id: agent
+        shell: bash
+        env:
+          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
+          NODE_ARCHIVE: ${{ steps.runtime.outputs.archive }}
+          OPENCODE_ARCHIVE: ${{ steps.opencode.outputs.archive }}
+        run: |
+          set -euo pipefail
+          directory="$RUNNER_TEMP/goodbuddy-agent-ci"
+          rm -rf "$directory"
+          mkdir -p "$directory"
+          agent_version="$(node -p "require('./agent-runtime-lock.json').agentVersion")"
+          node build/agent-ci-bundle.cjs \
+            --platform "$AGENT_PLATFORM" \
+            --arch "$AGENT_ARCH" \
+            --node-archive "$RUNNER_TEMP/goodbuddy-agent-node/$NODE_ARCHIVE" \
+            --opencode-archive "$RUNNER_TEMP/goodbuddy-opencode-runtime/$OPENCODE_ARCHIVE" \
+            --output-directory "$directory/bundle" \
+            --archive "$directory/goodbuddy-agent-$agent_version-$AGENT_PLATFORM-$AGENT_ARCH.gbagent" |
+            tee "$directory/result.json"
+          node - <<'NODE'
+          const { appendFileSync, readFileSync } = require('node:fs')
+          const result = JSON.parse(
+            readFileSync(
+              `${process.env.RUNNER_TEMP}/goodbuddy-agent-ci/result.json`,
+              'utf8'
+            )
+          )
+          if (
+            result.architecture !== process.env.AGENT_ARCH ||
+            result.platform !== process.env.AGENT_PLATFORM ||
+            !/^[a-f0-9]{64}$/u.test(result.archiveSha256)
+          ) {
+            throw new Error('Agent CI result is invalid')
+          }
+          appendFileSync(
+            process.env.GITHUB_OUTPUT,
+            `sha256=${result.archiveSha256}\n`
+          )
+          NODE
+
+      - name: Record verified Agent build
+        shell: bash
+        env:
+          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
+          AGENT_SHA256: ${{ steps.agent.outputs.sha256 }}
+        run: |
+          {
+            echo "### $AGENT_PLATFORM $AGENT_ARCH Agent build"
+            echo
+            echo "Native compound Agent, Node, and OpenCode Runtime build, test-signature verification, launch smoke, and deterministic archive comparison passed."
+            echo
+            echo "Archive SHA-256: \`$AGENT_SHA256\`"
+            echo
+            echo "The ephemeral CI key and bundle are not published."
+            echo "Native build checks do not replace real Host installation, Attach, and Ask/Execute acceptance."
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/packages.yml

@@ -26,13 +26,17 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24
+          node-version: 24.19.0
           cache: npm
 
       - name: Verify release tag version
         if: github.ref_type == 'tag'
         run: node -e "const p=require('./package.json'); const expected='v'+p.version; if(process.env.GITHUB_REF_NAME!==expected){throw new Error('Expected tag '+expected+', received '+process.env.GITHUB_REF_NAME)}"
 
+      - name: Verify bilingual release notes
+        if: github.ref_type == 'tag'
+        run: npm run release:notes:verify
+
       - name: Install dependencies
         run: npm ci
 
@@ -46,7 +50,9 @@ jobs:
         run: npm run build:bundle
 
       - name: Upload production bundle
-        if: github.event_name == 'workflow_dispatch' || github.ref_type == 'tag'
+        if: >-
+          github.ref_type == 'tag' ||
+          (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
         uses: actions/upload-artifact@v7
         with:
           name: goodbuddy-production-bundle
@@ -54,10 +60,67 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  authorize-release:
+    name: Authorize desktop packaging
+    if: >-
+      github.ref_type == 'tag' ||
+      (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+    needs: validate
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    outputs:
+      authorized: ${{ steps.policy.outputs.authorized }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Verify immutable release ref policy
+        id: policy
+        shell: bash
+        run: |
+          set -euo pipefail
+          git fetch --no-tags origin \
+            "+refs/heads/main:refs/remotes/origin/main"
+          git merge-base --is-ancestor \
+            "$GITHUB_SHA" refs/remotes/origin/main
+
+          case "$GITHUB_EVENT_NAME" in
+            push)
+              test "$GITHUB_REF_TYPE" = "tag"
+              test "$(node -p "String(require(process.env.GITHUB_EVENT_PATH).created)")" = "true"
+              test "$(node -p "String(require(process.env.GITHUB_EVENT_PATH).forced)")" = "false"
+              test "$(node -p "String(require(process.env.GITHUB_EVENT_PATH).deleted)")" = "false"
+              expected="v$(node -p "require('./package.json').version")"
+              test "$GITHUB_REF" = "refs/tags/$expected"
+              test "$GITHUB_REF_NAME" = "$expected"
+              git fetch --no-tags origin \
+                "+refs/tags/${GITHUB_REF_NAME}:refs/tags/${GITHUB_REF_NAME}"
+              test "$(git cat-file -t "refs/tags/$GITHUB_REF_NAME")" = "tag"
+              test "$(git rev-parse "refs/tags/$GITHUB_REF_NAME^{commit}")" = "$GITHUB_SHA"
+              ;;
+            workflow_dispatch)
+              test "$GITHUB_REF" = "refs/heads/main"
+              test "$GITHUB_REF_TYPE" = "branch"
+              test "$GITHUB_SHA" = "$(git rev-parse refs/remotes/origin/main)"
+              ;;
+            *)
+              echo "Desktop packaging is limited to immutable version-tag pushes or a manual run of refs/heads/main." >&2
+              exit 1
+              ;;
+          esac
+
+          echo "authorized=true" >> "$GITHUB_OUTPUT"
+
   package:
     name: ${{ matrix.platform }} ${{ matrix.arch }}
-    if: github.event_name == 'workflow_dispatch' || github.ref_type == 'tag'
-    needs: validate
+    if: >-
+      needs.authorize-release.result == 'success' &&
+      needs.authorize-release.outputs.authorized == 'true'
+    needs:
+      - validate
+      - authorize-release
     strategy:
       fail-fast: false
       matrix:
@@ -67,7 +130,7 @@ jobs:
             runner: windows-2025
           - platform: windows
             arch: arm64
-            runner: windows-2025
+            runner: windows-11-vs2026-arm
           - platform: macos
             arch: x64
             runner: macos-15-intel
@@ -88,7 +151,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24
+          node-version: 24.19.0
           cache: npm
 
       - name: Cache packaging toolsets
@@ -111,7 +174,121 @@ jobs:
           name: goodbuddy-production-bundle
           path: out
 
-      - name: Build and verify release packages
+      - name: Verify native runner architecture
+        run: node -e "if(process.arch !== '${{ matrix.arch }}'){throw new Error('Expected ${{ matrix.arch }} runner, received '+process.arch)}"
+
+      - name: Install and validate managed Python
+        run: npm exec vitest run tests/local-tool-environment-live.test.ts
+        env:
+          GOODBUDDY_RUN_LIVE_TOOL_ENVIRONMENT: '1'
+
+      - name: Install RPM packaging tools
+        if: matrix.platform == 'linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends --yes rpm
+          rpmbuild --version
+
+      - name: Resolve macOS signing mode
+        id: macos-signing
+        if: matrix.platform == 'macos'
+        shell: bash
+        env:
+          MACOS_CERTIFICATE_BASE64: ${{ secrets.MACOS_CERTIFICATE_BASE64 }}
+          MACOS_CERTIFICATE_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+          APPLE_API_KEY_BASE64: ${{ secrets.APPLE_API_KEY_BASE64 }}
+          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+        run: |
+          set -euo pipefail
+          names=(
+            MACOS_CERTIFICATE_BASE64
+            MACOS_CERTIFICATE_PASSWORD
+            APPLE_API_KEY_BASE64
+            APPLE_API_KEY_ID
+            APPLE_API_ISSUER
+          )
+          configured=0
+          missing=()
+          for name in "${names[@]}"; do
+            if [[ -n "${!name}" ]]; then
+              configured=$((configured + 1))
+            else
+              missing+=("$name")
+            fi
+          done
+          if [[ "$configured" -eq 0 ]]; then
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::warning title=Unsigned macOS packages::Apple signing credentials are not configured. The macOS DMG and ZIP will be unsigned and unnotarized."
+            {
+              echo "### macOS signing"
+              echo
+              echo "Apple signing credentials are not configured. This target produces unsigned and unnotarized packages that Gatekeeper may block on first launch."
+            } >> "$GITHUB_STEP_SUMMARY"
+            exit 0
+          fi
+          if [[ "$configured" -ne "${#names[@]}" ]]; then
+            missing_names="$(IFS=,; echo "${missing[*]}")"
+            echo "::error title=Incomplete macOS signing credentials::Missing: $missing_names"
+            exit 1
+          fi
+          echo "enabled=true" >> "$GITHUB_OUTPUT"
+          printf '%s' "$MACOS_CERTIFICATE_BASE64" | base64 -D > "$RUNNER_TEMP/goodbuddy-developer-id.p12"
+          printf '%s' "$APPLE_API_KEY_BASE64" | base64 -D > "$RUNNER_TEMP/AuthKey.p8"
+          test -s "$RUNNER_TEMP/goodbuddy-developer-id.p12"
+          test -s "$RUNNER_TEMP/AuthKey.p8"
+          chmod 600 "$RUNNER_TEMP/goodbuddy-developer-id.p12" "$RUNNER_TEMP/AuthKey.p8"
+          {
+            echo "### macOS signing"
+            echo
+            echo "Complete Apple signing credentials were detected. This target will be signed, notarized, and verified."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Build, sign and notarize macOS release packages
+        if: matrix.platform == 'macos' && steps.macos-signing.outputs.enabled == 'true'
+        run: npm run release:package -- --platform ${{ matrix.platform }} --arch ${{ matrix.arch }} --format dmg --skip-build
+        env:
+          ELECTRON_CACHE: ${{ runner.temp }}/electron
+          ELECTRON_BUILDER_CACHE: ${{ runner.temp }}/electron-builder
+          CSC_LINK: ${{ runner.temp }}/goodbuddy-developer-id.p12
+          CSC_KEY_PASSWORD: ${{ secrets.MACOS_CERTIFICATE_PASSWORD }}
+          CSC_IDENTITY_AUTO_DISCOVERY: 'true'
+          APPLE_API_KEY: ${{ runner.temp }}/AuthKey.p8
+          APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+          APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+
+      - name: Build unsigned macOS release packages
+        if: matrix.platform == 'macos' && steps.macos-signing.outputs.enabled == 'false'
+        run: npm run release:package -- --platform ${{ matrix.platform }} --arch ${{ matrix.arch }} --format dmg --skip-build --unsigned
+        env:
+          ELECTRON_CACHE: ${{ runner.temp }}/electron
+          ELECTRON_BUILDER_CACHE: ${{ runner.temp }}/electron-builder
+          CSC_IDENTITY_AUTO_DISCOVERY: 'false'
+
+      - name: Verify macOS signature and notarization ticket
+        if: matrix.platform == 'macos' && steps.macos-signing.outputs.enabled == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          dmg="$(find "dist/release/macos-${{ matrix.arch }}" -maxdepth 1 -type f -name '*.dmg' -print -quit)"
+          test -n "$dmg"
+          mount_point="$RUNNER_TEMP/goodbuddy-dmg"
+          mkdir "$mount_point"
+          cleanup() {
+            hdiutil detach "$mount_point" -quiet || true
+          }
+          trap cleanup EXIT
+          hdiutil attach "$dmg" -nobrowse -readonly -mountpoint "$mount_point" -quiet
+          app="$(find "$mount_point" -maxdepth 1 -type d -name '*.app' -print -quit)"
+          test -n "$app"
+          codesign --verify --deep --strict --verbose=2 "$app"
+          spctl --assess --type execute --verbose=4 "$app"
+          xcrun stapler validate "$app"
+
+      - name: Build and verify non-macOS release packages
+        if: matrix.platform != 'macos'
         run: npm run release:package -- --platform ${{ matrix.platform }} --arch ${{ matrix.arch }} --skip-build
         env:
           ELECTRON_CACHE: ${{ runner.temp }}/electron
@@ -127,14 +304,22 @@ jobs:
           retention-days: 30
 
   release:
-    name: Publish GitHub Release
-    if: github.event_name == 'push' && github.ref_type == 'tag'
-    needs: package
+    name: Publish GitHub and OSS release
+    if: >-
+      github.event_name == 'push' &&
+      github.ref_type == 'tag' &&
+      needs.authorize-release.outputs.authorized == 'true'
+    needs:
+      - authorize-release
+      - package
     runs-on: ubuntu-24.04
-    timeout-minutes: 20
+    timeout-minutes: 35
+    environment:
+      name: aliyun-oss-release
     permissions:
       contents: write
       actions: read
+      id-token: write
 
     steps:
       - uses: actions/checkout@v7
@@ -143,7 +328,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24
+          node-version: 24.19.0
 
       - name: Verify release tag
         shell: bash
@@ -153,6 +338,9 @@ jobs:
           test "$GITHUB_REF_NAME" = "$expected"
           test "$(git rev-parse "refs/tags/$GITHUB_REF_NAME^{commit}")" = "$GITHUB_SHA"
 
+      - name: Prepare bilingual release notes
+        run: node build/release-notes.cjs --output release-notes.md
+
       - name: Download Windows packages
         uses: actions/download-artifact@v8
         with:
@@ -174,18 +362,141 @@ jobs:
       - name: Verify and aggregate release assets
         run: node build/aggregate-release.cjs --input dist/release-downloads --output dist/release-upload
 
-      - name: Create or update draft release
+      - name: Verify OSS release configuration
+        shell: bash
+        env:
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+          OIDC_PROVIDER_ARN: ${{ vars.ALIYUN_OIDC_PROVIDER_ARN }}
+          ROLE_ARN: ${{ vars.ALIYUN_ROLE_ARN }}
+        run: |
+          set -euo pipefail
+          test -n "$OSS_BUCKET"
+          test -n "$OSS_ENDPOINT"
+          test -n "$OIDC_PROVIDER_ARN"
+          test -n "$ROLE_ARN"
+          case "$OSS_BUCKET" in
+            goodbuddy) ;;
+            *) echo "OSS Bucket 必须与应用内置镜像地址一致" >&2; exit 1 ;;
+          esac
+          case "$OSS_ENDPOINT" in
+            https://oss-cn-beijing.aliyuncs.com) ;;
+            *) echo "OSS Endpoint 必须与应用内置镜像地址一致" >&2; exit 1 ;;
+          esac
+          case "$OIDC_PROVIDER_ARN" in
+            acs:ram::*:oidc-provider/*) ;;
+            *) echo "OIDC Provider ARN 无效" >&2; exit 1 ;;
+          esac
+          case "$ROLE_ARN" in
+            acs:ram::*:role/*) ;;
+            *) echo "RAM Role ARN 无效" >&2; exit 1 ;;
+          esac
+
+      - name: Authenticate to Alibaba Cloud
+        uses: aliyun/configure-aliyun-credentials-action@v1
+        with:
+          role-to-assume: ${{ vars.ALIYUN_ROLE_ARN }}
+          oidc-provider-arn: ${{ vars.ALIYUN_OIDC_PROVIDER_ARN }}
+          role-session-name: goodbuddy-release-${{ github.run_id }}
+          role-session-expiration: 3600
+          audience: sts.aliyuncs.com
+
+      - name: Install ossutil
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="2.3.0"
+          archive="$RUNNER_TEMP/ossutil.zip"
+          directory="$RUNNER_TEMP/ossutil"
+          curl --fail --silent --show-error --location \
+            "https://gosspublic.alicdn.com/ossutil/v2/$version/ossutil-$version-linux-amd64.zip" \
+            --output "$archive"
+          mkdir "$directory"
+          unzip -q "$archive" -d "$directory"
+          binary="$(find "$directory" -type f -name ossutil -print -quit)"
+          test -n "$binary"
+          chmod +x "$binary"
+          echo "$(dirname "$binary")" >> "$GITHUB_PATH"
+
+      - name: Prepare OSS website release index
+        id: oss-release
+        shell: bash
+        env:
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+        run: |
+          set -euo pipefail
+          endpoint_host="${OSS_ENDPOINT#https://}"
+          oss_region="${endpoint_host#oss-}"
+          oss_region="${oss_region%.aliyuncs.com}"
+          case "$oss_region" in
+            *[!a-z0-9-]*|'') echo "无法从 OSS Endpoint 推导 Region" >&2; exit 1 ;;
+          esac
+          base_url="https://${OSS_BUCKET}.${endpoint_host}/releases/${GITHUB_REF_NAME}/"
+          node build/create-site-release.cjs \
+            --manifest dist/release-upload/release-manifest.json \
+            --base-url "$base_url" \
+            --output dist/site-release.json
+          echo "base-url=$base_url" >> "$GITHUB_OUTPUT"
+          echo "region=$oss_region" >> "$GITHUB_OUTPUT"
+
+      - name: Upload immutable release assets to OSS
+        shell: bash
+        env:
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+          OSS_REGION: ${{ steps.oss-release.outputs.region }}
+        run: |
+          set -euo pipefail
+          export OSS_ACCESS_KEY_ID="$ALIBABA_CLOUD_ACCESS_KEY_ID"
+          export OSS_ACCESS_KEY_SECRET="$ALIBABA_CLOUD_ACCESS_KEY_SECRET"
+          export OSS_SESSION_TOKEN="$ALIBABA_CLOUD_SECURITY_TOKEN"
+          test -n "$OSS_ACCESS_KEY_ID"
+          test -n "$OSS_ACCESS_KEY_SECRET"
+          test -n "$OSS_SESSION_TOKEN"
+          test -n "$OSS_REGION"
+          for file in dist/release-upload/* dist/site-release.json; do
+            name="$(basename "$file")"
+            ossutil cp "$file" \
+              "oss://${OSS_BUCKET}/releases/${GITHUB_REF_NAME}/${name}" \
+              --endpoint "$OSS_ENDPOINT" \
+              --region "$OSS_REGION" \
+              --update
+          done
+
+      - name: Verify public OSS release assets
+        run: node build/verify-site-release.cjs --manifest dist/site-release.json
+
+      - name: Create or update draft GitHub release
         shell: bash
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
           tag="$GITHUB_REF_NAME"
+          version="$(node -p "require('./package.json').version")"
           if gh release view "$tag" >/dev/null 2>&1; then
-            gh release edit "$tag" --draft
+            gh release edit "$tag" --draft --title "GoodBuddy $version" --notes-file release-notes.md
           else
-            version="$(node -p "require('./package.json').version")"
-            gh release create "$tag" --draft --verify-tag --generate-notes --title "GoodBuddy $version"
+            gh release create "$tag" --draft --verify-tag --title "GoodBuddy $version" --notes-file release-notes.md
           fi
           gh release upload "$tag" dist/release-upload/* --clobber
           gh release edit "$tag" --draft=false --latest
+
+      - name: Point website to verified OSS release
+        shell: bash
+        env:
+          OSS_BUCKET: ${{ vars.ALIYUN_OSS_BUCKET }}
+          OSS_ENDPOINT: ${{ vars.ALIYUN_OSS_ENDPOINT }}
+          OSS_REGION: ${{ steps.oss-release.outputs.region }}
+        run: |
+          set -euo pipefail
+          export OSS_ACCESS_KEY_ID="$ALIBABA_CLOUD_ACCESS_KEY_ID"
+          export OSS_ACCESS_KEY_SECRET="$ALIBABA_CLOUD_ACCESS_KEY_SECRET"
+          export OSS_SESSION_TOKEN="$ALIBABA_CLOUD_SECURITY_TOKEN"
+          test -n "$OSS_REGION"
+          ossutil cp dist/site-release.json \
+            "oss://${OSS_BUCKET}/releases/latest.json" \
+            --endpoint "$OSS_ENDPOINT" \
+            --region "$OSS_REGION" \
+            --force

.github/workflows/pages.yml

@@ -0,0 +1,47 @@
+name: Deploy website to GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'sites/**'
+      - '.github/workflows/pages.yml'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Deploy static website
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Validate website
+        run: |
+          node sites/scripts/validate.mjs
+          node --check sites/app.js
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload website artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: sites
+
+      - name: Deploy website
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,11 +1,17 @@
 node_modules/
 out/
 dist/
+# Local build output left by the extracted ShareServer project.
+shareserver/build-server/
 coverage/
 .vite/
 .runtime-resources/
+.remote-runtime-resources/
+.agent-resources/
 *.log
 *.tsbuildinfo
+__pycache__/
+*.py[cod]
 .env
 .env.*
 !.env.example

AGENTS.md

@@ -4,9 +4,72 @@
 
 These instructions apply to the entire repository.
 
-GoodBuddy is a secure, cross-platform Electron desktop assistant. It uses
-Electron, React, TypeScript, Vite, Vitest, and SQLite. User-facing copy is
-primarily Simplified Chinese.
+GoodBuddy is a cross-platform Electron desktop assistant for internal
+organizational networks. It uses Electron, React, TypeScript, Vite, Vitest, and
+SQLite. User-facing copy is primarily Simplified Chinese.
+
+## Product Priorities
+
+GoodBuddy is primarily an internal-network product. Unless the user states
+otherwise, assume a trusted organizational environment, not a hostile public,
+multi-tenant, or zero-trust deployment.
+
+Use this order when requirements or implementation choices compete:
+
+1. Complete, working product functionality.
+2. Measured performance and responsiveness.
+3. Clear, low-friction user experience.
+4. Simple, conventional, maintainable implementation.
+5. Security controls only for a concrete risk in the actual deployment model.
+
+Functionality and performance are the primary acceptance criteria. Do not
+disable, delay, restrict, or complicate a working product path for speculative
+security hardening. Preserve the existing Electron, credential, user-data, and
+release-signing boundaries, but do not expand them without a concrete current
+risk or an explicit user requirement.
+
+## Design Simplicity
+
+Follow KISS and YAGNI. Use the smallest conventional design that completes the
+real user workflow.
+
+- A demonstrated failure authorizes only the smallest proportional fix, not a
+  general recovery, compatibility, or security framework.
+- Prefer deleting bounded staging and retrying, idempotent operations, and
+  reconciliation from one authoritative source of truth. Do not persist copies
+  of state that can be derived or safely retried.
+- Do not add durable snapshots, journals, versioned internal receipts, rollback
+  engines, compatibility readers, multi-phase state machines, protocol phases,
+  cryptographic identities, trust tiers, consent ceremonies, or quotas when
+  cleanup, retry, or reconciliation is safe.
+- Before introducing any of that machinery, stop before coding. Explain the
+  reproducible current failure, why the simple alternative is insufficient,
+  and obtain the user's explicit approval for the added complexity. A reviewer
+  suggestion, test-only scenario, hypothetical crash, or possible future need
+  is not sufficient evidence.
+- Performance outranks simplicity only for a measured bottleneck. Security
+  complexity requires a concrete threat at an actual trust boundary.
+- Ignore hypothetical threats that require a hostile public network,
+  untrusted tenants, or zero-trust deployment unless that environment is an
+  explicit product requirement. Do not turn such findings into implementation
+  work.
+- A complete workflow means the normal production path plus demonstrated
+  failure cases. It does not require exhaustive recovery from every
+  hypothetical interruption point.
+- Test Hosts are test environments. Do not turn their workflows into production
+  compliance exercises.
+
+When the user asks to implement a feature, deliver the complete usable user
+workflow unless the user explicitly requests a prototype, scaffold, staged
+landing, or partial implementation. Internal contracts, managers, protocols,
+disabled UI, unavailable catalog entries, placeholders, and tests around
+injected fakes do not count as completion when the real product path still
+cannot be used. If required metadata, dependencies, or integration details are
+missing, investigate and resolve them as part of the implementation. Do not
+turn missing implementation work into a product "security gate", permanent
+unavailable state, or acceptance criterion. If a genuine external blocker
+cannot be resolved, stop and ask the user rather than presenting the partial
+work as the implemented feature.
 
 ## Architecture
 
@@ -19,7 +82,8 @@ primarily Simplified Chinese.
 - `build`: packaging scripts and icons.
 - `out` and `dist`: generated output. Change source files instead.
 
-Keep Electron security boundaries intact:
+Keep these existing Electron security boundaries intact. They do not authorize
+additional hardening beyond the actual internal-network threat model:
 
 - Preserve context isolation and sandboxing.
 - Never enable renderer Node integration.
@@ -29,11 +93,26 @@ Keep Electron security boundaries intact:
 
 ## Runtime Behavior
 
-- Ask and Plan modes must remain read-only at the runtime boundary.
-- Execute mode may use tools only through the existing approval controls.
+- Ask mode must remain read-only at the runtime boundary.
+- Execute mode is the user's full authorization for the selected SSH account.
+  It may use all tools, processes, network access, and writable paths available
+  to that account. Do not add T2/T3 trust tiers, separate consent checklists,
+  per-tool approvals, or a second "controlled execution" concept.
 - Preserve cancellation, timeout, bounded-output, and shutdown behavior.
-- Treat OpenCode and Continue as untrusted child runtimes. Preserve environment
-  allowlists, sandbox checks, and per-tool approval enforcement.
+- When fixing Runtime behavior or limits, also inspect the remote Runtime path
+  through GoodBuddy Agent (`gbagent`). Verify whether local and remote execution
+  actually share the affected control logic; do not assume that a desktop fix
+  covers the Agent, bridge, launcher, or bundled Runtime. Fix any affected
+  remote-specific implementation and validate it under the GoodBuddy Agent
+  development validation rules below. If no separate remote fix is needed,
+  record which shared implementation covers it or why the remote path is
+  unaffected.
+- Keep model/provider credentials in Main, but do not otherwise reduce Execute
+  permissions with extra product policy gates. Keep child-process cleanup
+  straightforward and reliable.
+- On test Hosts, GoodBuddy may install and start its own test resources and
+  create dedicated work directories. Never delete or overwrite unrelated Host
+  files.
 - A successful image-model configuration check does not prove generation works.
   Only an actual generation request verifies the provider path.
 - Do not fetch provider-returned image URLs. Accept and validate bounded inline
@@ -41,7 +120,11 @@ Keep Electron security boundaries intact:
 
 ## Data and Compatibility
 
-- Preserve existing user data and migrations.
+- Preserve released user-owned data, migrations required by released data, and
+  supported external contracts.
+- Compatibility does not apply to unshipped, branch-local, or safely disposable
+  internal operation records. Replace or discard those records instead of
+  adding migrations, legacy readers, versioned receipts, or recovery machinery.
 - Do not weaken SQLite transaction, lifecycle, deduplication, or cleanup logic.
 - Treat user workspaces and untracked files as user-owned.
 - Keep Windows, macOS, Linux x64, and Linux arm64 behavior in mind.
@@ -52,18 +135,59 @@ Keep Electron security boundaries intact:
 - Follow surrounding TypeScript and React patterns.
 - Reuse installed libraries and shared contracts before adding dependencies.
 - Keep changes focused. Do not add unrelated refactors or documentation.
+- Reviewer findings do not expand task scope. Implement a finding only when it
+  identifies a reachable current failure, a released compatibility contract,
+  or reproducible user-visible harm. Record speculative concerns without
+  building machinery around them.
+- Validate the real end-to-end path, not only schemas, mocks, injected test
+  doubles, or isolated infrastructure. A feature is not complete until its
+  normal UI action reaches the production implementation and produces the
+  intended result.
+- Security work must remain proportional to a concrete risk and must not
+  replace missing product functionality. Use established platform and
+  repository mechanisms instead of inventing extra gates, ceremonies, or
+  disabled states.
 - Add or update focused tests for behavioral changes and regressions.
+- After completing any functional change, inspect the affected product,
+  architecture, design, feature, setup, and operational documentation and
+  update every relevant document to match the implemented behavior. Treat the
+  final code and validated runtime behavior as the source of truth: correct
+  stale documentation rather than preserving outdated intent. Avoid
+  documentation churn only when the change has no documented impact.
 - Avoid broad catches that erase HTTP status, cancellation, or provider error
   context.
 - Keep UI accessible with labels, keyboard behavior, semantic roles, and visible
   focus states.
 
+## Product Design Documentation
+
+- Organize feature documentation by product feature under
+  `docs/features/<feature-name>/`, not by document type.
+- Treat each feature directory's `README.md` as its documentation entry point.
+- Follow `docs/features/AGENTS.md` for required document responsibilities,
+  naming, traceability, progress evidence, and migration rules.
+- Keep cross-feature architecture, quality protocols, development procedures,
+  and product-wide roadmaps outside feature directories only when they cannot
+  be owned by one feature.
+- Maintain one authoritative definition for each requirement, state rule, UI
+  behavior, technical contract, and implementation fact. Link to it instead of
+  duplicating it across documents.
+- Update the affected feature documents after functional changes. The
+  implemented and validated production behavior is the final source of truth.
+
 ## UI Consistency
 
+- Treat `UI-DESIGN.md` as the canonical UI design system. Read and follow it
+  before changing renderer layout, shared controls, interaction feedback,
+  themes, responsive behavior, or accessibility semantics.
 - Reuse the shared `PageTabs` and `SegmentedControl` primitives instead of
   creating page-specific tab or toggle styles. A semantic tab set may use the
   shared segmented visual variant, but it must retain `tablist`, `tab`,
   `tabpanel`, `aria-selected`, roving focus, and arrow-key behavior.
+- Use the shared sliding Switch pattern for persistent binary states and expose
+  `role="switch"` even when it is implemented with a checkbox input. Keep
+  Checkbox visuals and semantics for multi-select, assignment, and explicit
+  confirmation. Do not create page-specific Switch styling.
 - Use the bundled `Inter Variable` and `Noto Sans SC Variable` UI fonts through
   the shared typography tokens. Do not add remote font requests or page-local
   font stacks. Keep redistributed font licenses in packaged resources and
@@ -77,42 +201,84 @@ Keep Electron security boundaries intact:
 - Do not show the same event both inline and as an application notification.
   Preserve user input and actionable error context when an operation fails.
 
-## Release Packaging
+## Commit Messages and Release Notes
 
-- `.github/workflows/packages.yml` is the canonical cross-platform packaging
-  workflow. It validates and builds `out` once, then packages on six native
-  runners: Windows, macOS, and Linux, each for x64 and arm64.
-- Run the unified packager with
-  `npm run release:package -- --platform <platform> --arch <arch>`. It only
-  packages for the native host and writes to
-  `dist/release/<platform>-<arch>`.
-- Default deliverables are NSIS and portable ZIP for Windows, DMG and ZIP for
-  macOS, and AppImage and DEB for Linux. Every target includes
-  `release-manifest.json` with SHA-256 hashes.
-- `build/build-release.cjs` verifies the unpacked application, `app.asar`,
-  bundled Continue and OpenCode runtimes, executable architecture, and package
-  signatures before atomically replacing a release directory.
-- Keep electron-builder invocations on `--publish never`. Main-branch builds
-  run validation and build the production bundle without running the native
-  package matrix. Manual builds upload 30-day GitHub Actions artifacts.
-  Version-tag builds verify and aggregate packages before publishing GitHub
-  Release assets. Signing and macOS notarization are not configured.
-- Keep `ELECTRON_CACHE` and `ELECTRON_BUILDER_CACHE` under
-  `${{ runner.temp }}` in step-level workflow contexts. A cache beneath the
-  repository inherits the root `"type": "module"` and breaks electron-builder's
-  CommonJS macOS icon tool.
-- Tag builds must use `v${package.version}`. The workflow also supports manual
-  dispatch and main-branch changes to release tooling.
-- Every push that updates the `github` remote is a release push. Before pushing,
-  verify that `package.json` and `package-lock.json` contain the same release
-  version, create `v${package.version}` at the exact commit being pushed, and
-  push that tag so the native package matrix and GitHub Release run.
-- Never move or reuse an existing release tag. If `v${package.version}` already
-  exists locally or on a remote at another commit, increment the package
-  version and create a new matching tag before pushing.
-- Verified baseline on 2026-08-04: commit `2f54938`, GitHub Actions run
-  `30893805567` succeeded for validation and all six package targets, producing
-  six release artifacts plus the shared production bundle.
+Release notes are derived in part from commit history, so commits for
+user-visible changes must record product intent rather than only the
+implementation mechanism.
+
+- Classify the commit by the user-visible behavior. Use `feat` only for a
+  capability users did not previously have. Use `fix` when restoring intended
+  behavior, removing inconsistency, or making two existing entry points reflect
+  the same underlying setting, even if the implementation adds new
+  synchronization logic.
+- Keep the subject concise, then add a commit body for non-trivial user-visible
+  changes. State the previous user-facing problem, the resulting behavior, and
+  the affected surface or workflow. Include permissions, migration,
+  compatibility, cost, data, preview-status, or other usage caveats when
+  relevant.
+- Describe the user outcome precisely. Do not promote an internal refactor,
+  synchronization mechanism, schema change, or newly added implementation code
+  to a product feature unless it creates a genuinely new user capability.
+- When a change is release-note worthy, include a short `Release note:` line in
+  the commit body written in user-facing language. Prefer a concrete usage
+  scenario and benefit over technical implementation terminology.
+- Treat commit messages as evidence, not as the sole source of truth. Before
+  drafting release notes, verify the diff and resulting behavior, correct any
+  inaccurate `feat` or `fix` classification, and include actionable usage
+  notes where the change affects defaults, synchronized settings, permissions,
+  resource usage, compatibility, or user data.
+
+Example:
+
+```text
+fix: unify project settings across channel entry points
+
+The top-left project settings and the project settings shown under messaging
+channels could present or save inconsistent values. They now edit the same
+project configuration for the project name, description, Runtime, and work
+mode.
+
+Release note: 修复左上角项目设置与消息通道项目设置不一致的问题；现在从任一入口修改后，另一处会同步显示相同配置。
+```
+
+## Releases
+
+Detailed release operations are governed by
+[`docs/development/release-runbook.md`](./docs/development/release-runbook.md).
+Read that runbook only when preparing, publishing, recovering, or verifying a
+desktop or GoodBuddy Agent release. It is an operator and CI procedure, not an
+authorization to add product persistence or recovery machinery.
+
+Repository-wide release invariants:
+
+- Write each release-note feature item as two or three clear sentences that
+  identify the user situation, the available action, and the resulting
+  behavior or important boundary. Do not impose an arbitrary per-item
+  character limit; use the detail needed to make the user scenario clear.
+- Before approving the exact release commit and bilingual release notes,
+  inspect the English `FEATURES.md` and Simplified Chinese
+  `FEATURES.zh-CN.md` against the verified changes since the previous stable
+  release. Keep both versions aligned, and update their provided capabilities,
+  roadmap status, current versions, limitations, and remaining release
+  acceptance work as needed. Include any required update in the release
+  candidate; if no change is needed, explicitly confirm that both feature lists
+  were reviewed and remain accurate.
+- Never create or push a release tag before the user approves the exact release
+  commit and bilingual release notes.
+- Never move, delete, recreate, or reuse a release tag.
+- Keep desktop and Agent release paths, tags, artifacts, and Latest status
+  separate.
+- GitHub Actions is the release build and cross-platform packaging authority.
+  During release preparation, run local tests, type checks, and lint, but do
+  not run `npm run build`, `npm run build:bundle`, local packaging, or
+  packaged-app probes. Push the approved candidate commit first and require its
+  main-branch CI validation and production build to pass before tagging it,
+  unless the user explicitly requests an additional local build.
+- LoongArch is a separate experimental preview. Build or publish it only when
+  the user explicitly requests it for that release.
+- Never commit or publish credentials. Production publication uses the existing
+  protected environments and short-lived credentials described in the runbook.
 
 ## Validation
 
@@ -124,16 +290,60 @@ npm run typecheck
 npm run lint
 ```
 
-Run `npm run build` for production build changes. Use `npm run portable` only
-when a current Windows portable package is requested. Gated runtime tests may
-make paid or external calls, so run them only with explicit authorization.
+Run `npm run build` for production build changes during development, but not
+solely as a release-preparation step; release candidates use the main-branch CI
+production build before tagging. Use `npm run portable` only when a current
+Windows portable package is requested. The user has granted standing
+authorization in this repository for bounded real text-model calls needed to
+validate changed product paths; do not ask again for each such call. Keep each
+validation call minimal, disable tools and attachments where possible, and
+report the exact call count. This standing authorization does not cover bulk,
+high-cost, destructive, publishing, messaging, purchasing, or other
+consequential external actions.
+
+### GoodBuddy Agent development validation
+
+Every source change that can alter the deployed GoodBuddy Agent or the
+desktop-to-Agent production path must be validated on the shared Linux x64 test
+Host while the change is being developed. This includes Agent daemon and
+protocol changes, packaging and installation, attach/update behavior, Runtime
+launch and process ownership, workspaces, model bridges, and lifecycle or
+recovery behavior. Unit tests, mocks, fixtures, CI, and waiting for release
+validation are not substitutes for this development-time check.
+
+- Reach the shared Host at `192.168.0.23` on the LAN when available, otherwise
+  use `10.7.0.23` over VPN. These are two routes to the same physical machine,
+  not two independent test targets or architecture results.
+- Exercise the current source or package under development, not only the
+  previously published Agent. Run the affected production path as soon as it is
+  runnable and repeat the relevant scenario after the final change.
+- Select the real-Host scenario from the changed surface: attach/bootstrap or
+  update for installation changes; Ask/Execute and a bounded real model request
+  for Runtime or model-bridge changes; and the applicable disconnect, restart,
+  cancellation, or reconnection sequence for lifecycle and recovery changes.
+- Use the existing pinned Host identity and GoodBuddy credential storage. Never
+  add credentials to source, documentation, commands, logs, or test output, and
+  never hard-code these test addresses into product behavior or defaults.
+- Keep all artifacts in GoodBuddy-owned test directories. Before stopping or
+  changing a remote process, verify that it belongs to the test run; never
+  modify unrelated Host files or processes.
+- If neither route is reachable, report the real-Host validation as blocked and
+  do not present the Agent work as complete or defer its first real validation
+  to release time.
+
+The detailed scenario rules are documented in
+[`docs/features/remote-host/technical-design.md`](./docs/features/remote-host/technical-design.md).
 
 Before committing or pushing, inspect `git status`, `git diff`, and
 `git diff --cached`. Do not commit secrets, local databases, logs, generated
 credentials, or private user artifacts.
 
+Before a push that updates the `github` remote, ask whether the user wants a
+release tag unless they already specified that choice. A branch-only push does
+not require a version bump or tag.
+
 This repository has two synchronized remotes, `origin` and `github`. Unless the
 user explicitly names a remote, every requested push must update the current
-branch on both remotes. Any push that includes `github` must also push the
-required `v${package.version}` release tag to every remote receiving the branch
-update. Verify all updated branch and tag refs after pushing.
+branch on both remotes. When the user requests a release tag, push the new tag
+to every remote receiving the branch update. Verify all updated branch refs and
+any applicable tag refs after pushing.

BUILD.md

@@ -51,7 +51,18 @@ npm run test:watch
 GOODBUDDY_RUN_RUNTIME_E2E=1 npm test -- src/main/agent/runtime-e2e.manual.test.ts
 ```
 
-该测试可能发起真实外部模型调用。测试不会输出 API Key，文件操作在临时工作区中执行。
+OpenCode/Continue 用例默认读取 `dist/harness-package-probe/win-unpacked`；也可用
+`GOODBUDDY_E2E_PACKAGED_ROOT` 指定其他已解包应用目录。该测试可能发起真实外部模型
+调用。测试不会输出 API Key，文件操作在临时工作区中执行。文件包含经 Main 回环
+broker 调用已分配自定义 MCP 的真实 OpenCode 和 Continue 用例。
+
+不使用外部模型的 Runtime 原生交互回归位于
+`src/main/agent/opencode-runtime-permissions.test.ts`、
+`src/main/agent/continue-runtime-permissions.test.ts` 和
+`src/main/agent/deepseek-harness-acp-e2e.test.ts`。它们用本地确定性模型驱动真实 Runtime
+或固定 Host，覆盖工作区外访问、原生问答及 Ask 边界。OpenCode 用例默认使用开发缓存
+二进制；可通过 `GOODBUDDY_TEST_OPENCODE_BINARY` 指定已经安装的候选二进制，避免把
+仍在运行的旧缓存版本当作候选版本验证。这不替代当前源码 Agent 的 Linux Host 验收。
 
 ## 生产构建
 
@@ -63,6 +74,19 @@ npm run build
 
 中间构建输出位于 `out`。该目录为生成内容，应修改源文件后重新构建，不要直接编辑。
 
+## 图标生成
+
+应用图标源文件位于 `icons`。修改源图或图标处理逻辑后运行：
+
+```bash
+npm run icons
+```
+
+脚本会精确裁出亮色和深色圆角卡片，清理圆角外侧背景并使用适合主题的
+边缘颜色生成透明抗锯齿，避免缩放后出现白边。它会统一更新 `build` 中的
+PNG / ICO、Renderer 图标，以及官网使用的亮色和深色品牌图标。任务栏和
+托盘图标保持透明背景。
+
 ## 平台打包
 
 ### 当前平台默认包
@@ -111,26 +135,250 @@ npm run dist:linux:arm64
 每个 Linux 架构生成：
 
 - `deb`：适用于麒麟、统信 UOS 等 Debian 系桌面。
+- `rpm`：适用于 Fedora、RHEL、Rocky Linux、openEuler 等 RPM 系桌面。
 - AppImage：适用于免安装验证和便携运行。
 
 打包产物位于 `dist`。
 
+所有桌面打包入口通过同一个 `electron-builder` 启动脚本运行。正常日志会隐藏
+`duplicate dependency references` 信息摘要，因为它只表示同一已解析依赖被多条
+生产依赖路径共享，并不要求构建操作者处理；调试日志仍会保留该摘要。Renderer 中
+已由 Vite 打包的 `@antv/g6` 归类为构建期依赖，不会再作为独立 Node 模块复制进桌面
+安装包。
+
+以上 `dist*` 与 `portable` 命令用于普通本地桌面打包。它们会携带
+`agent-runtime-lock.json`、`remote-runtime-lock.json` 与公开的
+`agent-release-keys.json`，但所有桌面构建路径（包括本地 `portable`）都不会嵌入
+可安装的远端 Agent 或远端 Runtime payload。没有使用托管 SSH 时，无需下载任何额外
+组件，缺少远端包也不能阻塞普通桌面打包或发布。
+
+“设置 > 平台功能 > 远程项目（技术预览）”列出用户数据目录中已经下载或导入的
+Linux x64、Linux arm64 和 macOS arm64 复合 Agent 包。首次打开和手动刷新会从“关于与更新”所选来源读取
+小型签名目录，显示本地版本、在线最新兼容版本以及 `有更新 / 已是最新 / 未下载 /
+校验失败`；此检查不会下载 `.gbagent`。只有用户点击“下载”或“更新到”后才传输包，
+用户也可导入或导出 `.gbagent` 离线包。
+Main 在写入缓存前校验签名目录、目录签名、大小、SHA-256、桌面最低版本、Agent 协议、
+内部 Agent/Runtime 签名和完整 payload。缓存位于 Electron `userData` 下的
+`remote-components/agent-packages`，不暴露给 Renderer。
+
+公钥 registry 的信任来自严格 schema、唯一 key ID、规范 Base64、有效 Ed25519 key、
+production/test 环境和撤销列表，不来自 JSON 空白或换行。读取桌面资源、复合包和 Host
+已有 registry 时接受等价 UTF-8 JSON 格式；向 Host 写入前统一重新序列化为确定性 LF
+JSON。签名目录、包描述符、manifest、签名和 payload 的原始字节校验保持不变，包下载
+继续流式计算 SHA-256。
+
+“SSH 主机 > 远程运行环境”只有一个按版本事实显示“安装远程环境”“更新远程环境”或
+“重新安装”的主按钮。次级 SegmentedControl 选择默认且不持久化的“自动”、“Host 下载”
+或“GoodBuddy 传输”：
+
+- “Host 下载”使用签名目录中的固定 GitHub/北京镜像 URL、大小、SHA-256、
+  有界重定向链和固定 SSH prepare channel。GoodBuddy 桌面控制面通过该通道发送有界
+  one-shot installer；Host 校验目录绑定的归档大小和 SHA-256 后，由包内固定 Node 解码
+  并运行 installer。
+- 显式“GoodBuddy 传输”在在线目录不可用，或本地已验证包版本不低于在线候选时优先使用
+  本地包，包括版本更高的离线导入；线上存在更新且可用时仍取得线上新包。需要下载时，
+  同一次用户操作会校验 SHA-256 与签名、缓存并取得 lease，再以有界流式 SFTP 上传一个
+  compound archive 和归档内已验证的 bootstrap Node；约 294 MiB 的整包不会一次读入
+  Main `Buffer`，Host 仍再次校验。
+- “自动”只在 operation/prepare 前执行 Host capability probe；直连明确可用才选择
+  Host 下载，否则选择 GoodBuddy 传输。显式选择保持有效，prepare、commit 或 adoption
+  失败后不跨 acquisition 自动 fallback。
+
+两种 acquisition 都把同一签名 compound `.gbagent` 交付到固定 operation staging，随后
+共用 control-plane `prepare → commit → Agent activate/health → Runtime activate →
+finalize → cleanup`。Main 只持久化清理 operation staging 所需的 operation ID，不保存
+Agent/Runtime metadata 副本。操作中断或 adoption 失败后，下一次更新尽力清理旧暂存并
+重新 prepare，不恢复或续写旧操作。确认 adoption 后显式 cleanup。Host 在 prepare
+解包时完成一次完整 payload 校验；commit 只复核签名 metadata
+并原子发布，Agent/Runtime 注册后的 health、capabilities 和 prompt 启动不再遍历或哈希
+完整 payload。cleanup 失败不回滚已健康环境，也不阻塞下一次 fresh prepare。
+
+进入“主机与远程执行”设置页只读取本地 Host 列表，不逐台连接。用户点击某台 Host 的
+“刷新版本”后才执行远端版本和直连准备能力探测。项目切换只更新本地选择，不建立 SSH
+连接；首次实际使用远程 Workspace 或 Runtime 时才建立连接。当前进程会复用该 Host 已确认
+的 Agent/Runtime identity 和 Agent 连接，Host 编辑或环境更新会定向清空它们。
+直连安装本身只依赖 SSH，不依赖已有 Agent。显式选择 Host 下载时由实际安装流程重新探测
+并报告工具、权限、空间或来源不可达等原因；本次操作不会自动改用 GoodBuddy 传输。
+新建远程项目弹窗也只读本地 Host 验证记录；目录浏览或保存才连接所选 Host。Host 卡片
+在版本相同时仍允许显式重装；损坏的 GoodBuddy-owned 同 digest 目录会先隔离、替换并在
+失败时恢复。直连 bootstrap 使用固定短命令 `exec sh -s`，脚本和有界输入经 stdin 发送，
+避免 SSH command 长度限制。
+
+新增 Host 只保存并探测，不提供自动安装开关；只有用户明确点击主按钮后才传输完整包。现有
+package format v1 归档已经包含固定 Agent 和 Node，可直接用于 Host 直连；归档无需携带
+`agent/lib/package-installer.cjs`，签名目录不提供也不检查额外的 bootstrap 能力元数据。
+首次 bootstrap 不依赖已安装 Agent daemon。目标契约见
+[SSH Host 远程环境准备与直连下载设计](./docs/features/remote-host/environment-provisioning-technical-design.md)。
+
+删除 Host 或远程项目属于纯本地管理操作。Host 确认框列出全部关联项目记录并级联清理
+本地数据库，但不连接 Host、不检查远端目录，也不删除远端文件；Host 设置文件和项目事务
+的普通失败会回滚已写入的一侧。
+
 ## Runtime 资源
 
-发布包会携带经过版本与完整性校验的 OpenCode 和 Continue Runtime：
+桌面包会携带经过版本与完整性校验的 OpenCode、Continue 和 DSH 插件安装 Runtime：
 
 - OpenCode 平台二进制来自 `.runtime-resources/<arch>`。
+- Desktop 的离线配置复制以 `.runtime-resources` 为源、`opencode-config{,/**/*}` 为过滤器，避免 electron-builder 对复制源根目录下 `node_modules` 的固定排除。最终包逐文件核对离线配置与依赖；DSH bootstrap 和 chunk 不得残留外部 `@deepseek-ai/*` 导入。Windows x64 CI 在删除解包目录前实际导入包内 OpenCode 插件并运行隔离的 DSH UtilityProcess 握手与 npm 探针，失败即停止发布。
+- OpenCode 离线配置位于 `.runtime-resources/opencode-config`，构建时按已安装 `@opencode-ai/plugin/package.json` 的版本复用，不依赖根 lockfile 或自定义 ready/integrity 标记。缺失、不可读或版本不匹配时，在 staging 中执行精确版本 npm 安装，成功后替换缓存；安装失败保留旧缓存并清理 staging。本机共享配置同样比较随包插件与缓存插件的版本，版本不同时通过 staging 替换。
+- 离线依赖安装禁用 npm bin links；远程 Runtime 组包排除不使用的 `.bin` 命令链接，并把复制后的普通依赖文件统一为 `0644`，OpenCode 入口仍为 `0755`。目录元数据、每个依赖文件及许可证继续纳入签名校验。
 - Continue Runtime 来自锁定版本的 `@continuedev/cli`。
+- DSH 插件安装使用精确锁定并从 `app.asar` 解包的 npm CLI，通过当前 Electron 的 Node 模式运行；最终用户不需要另装 Node.js 或 npm。
+- DSH 图片输入使用精确锁定的 `@napi-rs/canvas` 完整解码 JPEG/PNG。通用包与目标平台、目标架构的 Skia 原生包必须从 `app.asar` 解包；当打包 Runner 的架构与目标架构不同时，发布脚本会根据 lockfile 的精确版本、下载地址和 integrity 临时暂存目标原生包，完成后清理。发布校验会检查版本、目标架构和 MIT 许可证。
 - 打包钩子位于 `build/runtime-hooks.cjs`。
 
 跨架构打包前，确认目标架构的 OpenCode 资源已经准备完成。不要用其他架构的二进制替代目标资源。
 
+GoodBuddy 管理的本机 OpenCode 启动后会轮询已认证的 loopback health 接口，最多等待
+30 秒。该窗口用于兼容 Linux ARM 等较慢环境；不要改回依赖 stdout 文案或 10 秒固定上限。
+聊天中的 Runtime 切换只执行路径和模型凭据就绪检查，不为状态显示启动临时 Server。
+设置中的显式连接测试、原生能力清单读取和首次实际请求仍会启动 OpenCode，并继续使用
+上述完整健康检查。
+
+## GoodBuddy Agent 工件
+
+面向用户发布的是按远端 Host 架构区分的复合 `.gbagent`，每个包同时包含签名
+Agent、固定 Node 和当前桌面源码维护并适配的签名 OpenCode Runtime。Runtime 不建立
+独立的用户版本流。远程直连所需的有界 one-shot installer 由桌面控制面打包并通过固定
+SSH prepare channel 发送，不是 `.gbagent` 的必需条目。Host 按签名目录校验完整归档
+大小和 SHA-256 后，包内固定 Node 解码并运行 installer。两种 acquisition 都在固定
+operation staging 中执行同一 prepare/commit；本地 pending record 只保存清理暂存所需的
+operation ID。失败或中断后的下一次更新尽力清理旧暂存并重新 prepare，不保存或恢复
+Agent/Runtime metadata 副本。生产构建命令为：
+
+```bash
+node build/agent-package.cjs build \
+  --arch <x64|arm64> \
+  --minimum-desktop-version <desktop-version> \
+  --node-archive <locked-node-runtime.tar.gz> \
+  --runtime-archive <locked-opencode-package.tgz> \
+  --output goodbuddy-agent-<agent-version>-linux-<arch>.gbagent
+```
+
+底层 `agent:build/import/verify` 与 `remote-runtime:build/import/verify` 命令继续用于
+开发、签名和复合包组装验证；其 `.agent-resources` 与
+`.remote-runtime-resources` 输出都是不提交的生成内容，也不会被任何桌面打包命令发现
+或嵌入。
+
+### Agent 原生 CI 策略
+
+Agent 源码、共享协议、lock、bundle 工具和测试与桌面应用保持在同一仓库、同一 commit；
+不维护长期分叉的 Agent 源码分支。`.github/workflows/agents.yml` 在相关 Pull Request、
+`main` push 和手工触发时，分别使用 `ubuntu-24.04` 与 `ubuntu-24.04-arm` 原生构建
+Linux x64/arm64 复合包，并使用 `macos-15` 原生构建 Darwin arm64
+复合包。所有 job 从 `agent-runtime-lock.json` 解析官方 Node HTTPS
+地址与 digest，并从 `remote-runtime-lock.json` 解析固定 OpenCode npm 包与 integrity；
+下载后再次校验，随后使用仅存在于进程内的临时 Ed25519 测试 key 构建两次，完成内外层
+测试签名验证、Agent CLI 加载 smoke 和确定性 `.gbagent` 对比。所有目标还验证
+Koffi 原生模块加载与 OpenCode `--version`；Linux job 继续运行 Agent 原生回归。
+
+Darwin arm64 的 Node 和 OpenCode 固定输入分别由同一份
+`agent-runtime-lock.json` 与 `remote-runtime-lock.json` 提供，不再维护 CI 专用副本。
+组包器区分 ELF 与 Mach-O，Darwin CI 产物命名为
+`goodbuddy-agent-<version>-darwin-arm64.gbagent`，不构建 Intel Mac 目标。
+macOS Host 继续通过 SSH 按需启动 detached Agent，不注册 launchd 或开机服务。
+进程身份使用 macOS 原生接口，Unix Socket 使用 `getpeereid`；Host 下载兼容系统自带
+`shasum -a 256`，不要求安装 GNU coreutils。真实 Host 验证记录见
+[远程主机技术设计](./docs/features/remote-host/technical-design.md)。
+
+三个目标共用 `agent-catalog.json` 和现有签名格式，条目按平台与架构区分。旧版 Desktop
+只接受 Linux catalog 条目；首次发布包含 Darwin 的累计 catalog 前必须先发布新版
+Desktop，并在发布说明中要求用户升级 Desktop。旧版的在线 Agent 目录检查会失败，
+本地已验证包不被删除。不得为此改写历史包或复用发布标签。
+
+该验证 workflow 不读取 production signing secret，不修改公开 key registry，也不上传
+可安装 Agent 工件。`.github/workflows/agent-release.yml` 是唯一 production Agent
+发布路径：只接受指向受保护 `main` 历史的 annotated
+`agent-v${agent-runtime-lock.agentVersion}` 标签，在 `agent-signing` Environment 中
+原生构建 Linux x64、Linux arm64、macOS arm64 三个目标，生成并签名累计目录，然后同步到非 Latest 的 GitHub Agent Release
+与北京 OSS。该 Environment 只保护一组 GoodBuddy 通用发布变量与 Secret：
+
+- `GOODBUDDY_SIGNING_KEY_ID` /
+  `GOODBUDDY_SIGNING_PRIVATE_KEY`
+
+该 GoodBuddy 身份统一签署内部 Agent、固定 Runtime manifest、外层 `.gbagent`
+描述符和累计目录，各层通过既有签名域区分用途，不再要求内部 Runtime 单独配置生产
+身份。私钥只注入签名步骤；预检只读取 key ID 并确认公钥已在
+`resources/agent-release-keys.json` 注册为 production 且未撤销。
+
+累计目录使用 `agent-catalog.json` 与 `agent-catalog.sig`。每个条目绑定 Agent 版本、
+最低桌面版本、Agent 协议、远端 OpenCode 版本/digest、架构、文件名、大小、SHA-256
+以及固定 GitHub/OSS URL。同一版本和架构的字节不可改变；目录最多保留 200 个条目。
+OSS 先写 `agent-releases/v<version>/` 不可变对象，GitHub Release 公开且验证后才更新
+单一 `agent-releases/latest.json` 指针。该指针只引用同一不可变版本目录中的
+`agent-catalog.json` 与 `agent-catalog.sig`，避免客户端观察到跨版本组合。Agent Release 必须使用
+`--latest=false`，不得改变桌面 Release 的 Latest 标记。
+
+### 远程 OpenCode Runtime 基础
+
+`remote-runtime-lock.json` 独立锁定首个远程 Runtime：OpenCode 1.18.29 的 Linux x64
+baseline 与 arm64 官方包 integrity、`bin/opencode` 入口和固定 `acp` 参数。它不同于
+`agent-runtime-lock.json`，后者锁定 Agent 自带 Node 以及用于 Linux `SO_PEERCRED`
+的 Koffi 版本。Agent bundle 将 Koffi loader 作为 external module，并只携带目标
+Linux 架构的 glibc/musl 原生 binding；构建与导入都会校验其 ELF 架构和 MIT 许可证。
+
+远程 Runtime 工件由以下命令独立管理：
+
+```bash
+# 在对应 Linux 原生 Runner 上从 lock 指定的 npm 归档构建并签名
+npm run remote-runtime:build -- --arch <x64|arm64> \
+  --runtime-archive <locked-opencode-package.tgz>
+
+# 为复合 Agent 包组装导入并完整验证签名归档
+npm run remote-runtime:import -- --arch x64 --archive <runtime-x64.tar>
+npm run remote-runtime:import -- --arch arm64 --archive <runtime-arm64.tar>
+```
+
+默认生成目录为 `.remote-runtime-resources/linux-<arch>/opencode/<digest>`，
+不提交到仓库。生产 workflow 从 `remote-runtime-lock.json` 解析固定包名、版本和
+integrity，以 `--ignore-scripts` 从官方 npm registry 获取归档；bundle 工具在签名前
+再次验证归档 SHA-512、包名、版本和 ELF 架构。
+
+源码已经实现 Runtime bundle build/import/verify、Daemon 侧
+manifest/Ed25519/payload/ELF/lock 校验、digest registry、ACP v3、直接进程 ownership 和
+`runtime/model-bridge` v1。Agent 通过私有 Unix socket 按需 detached 启动，不依赖
+systemd、D-Bus、Linger 或 bubblewrap。Ask 与 Execute 都直接启动签名 Runtime；两者的
+差异由 OpenCode Ask 权限配置和 Agent 工具权限分发边界共同执行，Execute 不注入该
+权限覆盖。
+
+OpenCode 通过已签名 Agent helper 和每次 Prompt 的私有 Unix socket 使用 Main-only 模型
+网关；Provider URL、API Key 和真实 Provider 认证头不进入远端。helper 的 loopback
+HTTP 入口使用每个进程随机生成的路径 capability，Anthropic/OpenAI SDK 需要的固定非秘密
+本地兼容标记由 helper 核对后丢弃。GoodBuddy 自己维护会话标题，所以生成的 OpenCode
+配置必须禁用 title Agent；工具循环只使用 build Agent 的模型轮次。
+
+Ask 模式的 ACP 权限中介只可为原生 `read` 选择 `allow_once`；其他工具种类和
+`allow_always` 请求必须拒绝。Unix 模型桥
+broker 必须按 socket 当前已缓冲字节增量读取长度帧，不能等待 `read(remaining)` 一次返回
+完整大响应。Agent 传输或权限实现变化后，除了普通测试，还要在原生 Linux 上运行包含
+至少 256 KiB 响应的模型桥回归。
+
+`agent-runtime-lock.json` 维护独立于桌面应用的 Agent 版本，
+`remote-runtime-lock.json` 维护 OpenCode Runtime 版本。Agent 内容变化时必须更新
+`agentVersion`；Runtime 更新时使用 Runtime 自身版本。签名 manifest 或 bundle digest
+唯一标识对应版本的精确工件。变更后必须重新构建、签名并导入 Linux x64/arm64 两套工件；
+旧版本或旧 digest 会按设计校验失败。不要手工把本机 `.runtime-resources` 当作远程 bundle。
+
+桌面应用更新后不会在项目切换时下载或安装 Agent。用户先在 SSH Host 的远程运行环境
+卡片显式选择直连下载或 GoodBuddy 传输。托管 SSH 项目只保存 Host ID、远端路径、
+Runtime 选择和默认模式；创建或保存时验证 Host 当前环境，普通项目切换只读取这些本地
+配置。首次实际使用 Workspace 或 Runtime 时解析 Host current identity；同一进程内后续
+项目复用已确认的 Agent/Runtime identity 和 Agent 连接。该流程不取得安装包、不重读完整
+payload，也不发布组件。
+
+两条手动准备路径都支持阶段进度和取消；成功后定向失效该 Host 的连接与 Runtime 缓存，
+引用项目下一次打开自然使用新的 current 环境。验收应覆盖两种准备方式与项目当前环境
+验证入口，并确认失败或取消不会删除 Host 配置、凭据、项目设置、Workspace 文件、全局
+可信元数据或仍可用的旧安装。
+
 ## 跨平台 CI 与 GitHub Release
 
 `.github/workflows/packages.yml` 是统一发布工作流。它先验证并生成一次
 `out` 生产 bundle，再在六个原生 Runner 上分别打包 Windows、macOS 和
 Linux 的 `x64`、`arm64` 版本。生产 bundle 仅作为短期 Actions artifact
-供打包任务复用，不会上传到 GitHub Release。
+供打包任务复用，不会上传到 GitHub Release。该工作流不构建、下载、签名或嵌入
+远端 Agent/OpenCode 复合包，也不依赖 `agent-signing` Environment；远端包缺失或
+Agent 发布失败不会阻塞任何桌面目标。
 
 本地构建单个平台目标：
 
@@ -138,8 +386,21 @@ Linux 的 `x64`、`arm64` 版本。生产 bundle 仅作为短期 Actions artifac
 npm run release:package -- --platform <windows|macos|linux> --arch <x64|arm64>
 ```
 
-默认发布产物为 Windows 的 NSIS 安装包与 portable ZIP、macOS 的 DMG 与
-ZIP，以及 Linux 的 AppImage 与 DEB。Windows portable ZIP 解压后可直接
+`release:package` 仅构建桌面产品。基础配置统一携带
+`agent-release-keys.json`、`agent-runtime-lock.json` 与 `remote-runtime-lock.json`
+供 Main 校验独立下载的复合包，但 release 配置不增加 `.agent-resources` 或
+`.remote-runtime-resources`。发布校验继续检查桌面自身的 OpenCode、Continue 与
+DeepSeek Harness Runtime、`app.asar`、目标架构和安装包签名。
+
+在 macOS 上明确生成未签名、未公证的开发验证包：
+
+```bash
+npm run release:package -- --platform macos --arch <x64|arm64> --unsigned
+```
+
+默认发布产物为 Windows 的 NSIS 安装包与 portable ZIP、macOS 的 DMG，
+以及 Linux 的 AppImage、DEB 与 RPM。Linux 原生 Runner 必须安装
+`rpm`/`rpmbuild` 工具后再调用 electron-builder。Windows portable ZIP 解压后可直接
 运行 `GoodBuddy.exe`，并包含启用便携数据目录的
 `.goodbuddy-portable.json`。每个目标目录都包含带文件大小和 SHA-256 的
 `release-manifest.json`。
@@ -148,24 +409,109 @@ ZIP，以及 Linux 的 AppImage 与 DEB。Windows portable ZIP 解压后可直
 打包矩阵，避免随后推送版本标签时对同一提交重复完整打包。手动触发会运行
 验证和六平台打包，并保留 30 天 Actions artifacts，但不会创建 Release。
 
+### Desktop 发布顺序（强制）
+
+Desktop 正式发布必须把候选分支推送与标签推送拆成两个阶段，不能在同一批操作中先后
+推送 `main` 和标签：
+
+1. 完成源码、版本、双语 Release Notes 与相关文档修改，运行 Release Notes 校验、
+   `npm test`、`npm run typecheck` 和 `npm run lint`。常规发布准备不在本机运行
+   production build、打包或安装包探针。
+2. 提交候选，确认用户批准的准确 commit SHA 与双语 Release Notes，fetch 两个远端后，
+   将该候选分别推送到 `origin/main` 和 `github/main`。
+3. 等待这个准确 SHA 的 `main` 分支 `Cross-platform packages` workflow 完成。只有
+   `Run validators` 和 `Build production bundle` 都成功，候选才具备打标签条件。
+4. 如果 `main` workflow 失败，不得创建标签。修复必须形成新的 commit，重新完成本地
+   校验、双远端 `main` 推送，并等待新 SHA 的 `main` workflow 成功；旧 SHA 的成功结果
+   不能替代新 SHA 的验证。
+5. `main` 成功后再次 fetch 两个远端，确认工作区干净、两个远端 `main` 都等于获批 SHA、
+   目标标签在本地和远端均未使用。此时才可在该 SHA 创建 annotated tag，并把标签分别
+   推送到两个远端，随后等待六平台打包和正式发布完成。
+
+不可移动、删除、重建或复用失败的发布标签。完整审批、恢复和发布后检查以
+[发布 Runbook](./docs/development/release-runbook.md) 为准。
+
 推送 `v${package.version}` 标签时，工作流运行验证和六平台打包。只有在
 全部目标成功后，才会严格校验并聚合所有平台产物，生成按平台重命名的
-manifests、总 `release-manifest.json` 和 `SHA256SUMS`。随后工作流创建或
-更新 draft GitHub Release，上传全部资产成功后才发布。重跑会保留人工
-编辑的 Release notes 和未知附件。
+manifests、总 `release-manifest.json` 和 `SHA256SUMS`。随后工作流通过
+GitHub OIDC 获取短期 STS 凭据，将发布资产和 `site-release.json` 上传到
+北京 OSS 的不可变版本目录，并公开校验 12 个安装包。验证通过后才创建或
+更新 draft GitHub Release、上传 20 个 Release 资产并正式发布，最后原子
+切换官网 `latest.json`。任一步失败都不会提前切换官网最新版本。
+
+同一标签重跑时，工作流会根据 `resources/release-notes.json` 重新生成并
+覆盖 GitHub Release 正文，以 `--clobber` 更新已知发布资产，同时保留未知
+附件。若源码与发布元数据未变化，应修正外部配置后重跑同一不可变标签；
+只有必须修改代码或元数据时才递增版本并创建新标签。
+
+Agent 发布使用另一套标签和 workflow：
+
+```bash
+agent_tag="agent-v$(node -p "require('./agent-runtime-lock.json').agentVersion")"
+git tag -a "$agent_tag" -m "GoodBuddy Agent $(node -p "require('./agent-runtime-lock.json').agentVersion")"
+```
+
+实际创建或推送前同样必须获得用户确认。`.github/workflows/agent-release.yml`
+原生构建两个 `.gbagent`、签名累计目录、上传
+`agent-releases/v<agent-version>/`，创建 `--latest=false` GitHub Release，再切换
+OSS 签名目录指针。生产发布需要 `agent-signing` 与 `aliyun-oss-release` 两个受保护
+Environment；普通分支/PR 的 `agents.yml` 不使用其中任何 Secret。
+
+Agent 标签也必须遵循与 Desktop 相同的 pre-tag 顺序。更新 Agent 生产源码或
+`agentVersion` 后，先把候选提交推送到两个 `main`，等待该准确 SHA 的
+`GoodBuddy Agents` main workflow 全部成功，再次 fetch 并确认两个远端 `main`、干净
+工作区和未使用标签，最后才可创建和推送 annotated `agent-v<version>`。不得把 Agent
+标签与候选 `main` 放在同一批推送中；任何修正 commit 都必须重新等待新 SHA 的 Agent
+main workflow，旧 SHA 的成功结果不能复用。
+
+中英文发布说明统一维护在 `resources/release-notes.json`。新版本按“本次
+亮点 / Highlights”“功能更新 / Features”“问题修复 / Bug Fixes”“使用前
+请留意 / Before You Start”四段组织，应用首次启动弹窗与 GitHub Release
+正文共用该来源。旧版两段式记录会兼容读取，无需改写。提交发布候选前运行
+`npm run release:notes:verify` 校验版本、双语条目数量并生成 Markdown。
 
 发布标签必须与 `package.json` 版本完全一致。实际推送标签和触发发布前仍
 需人工确认，例如当前版本应使用：
 
 ```bash
 tag="v$(node -p "require('./package.json').version")"
-git tag "$tag"
+git tag -a "$tag" -m "GoodBuddy $(node -p "require('./package.json').version")"
 git push origin "$tag"
 git push github "$tag"
 ```
 
-当前未配置 Windows/macOS 代码签名或 macOS notarization。对外分发前应按
-目标平台配置签名凭据并重新验证安装、升级和系统安全提示。
+macOS 发布 job 会先原子判断 Apple 凭据状态：以下五项 Actions Secrets 全部
+存在时，使用 Developer ID Application 证书签名，并通过 App Store Connect
+API Key 提交 Apple notarization；五项全部缺失时，明确生成未签名、未公证的
+DMG，并在 Actions 日志与摘要中警告 Gatekeeper 限制；只配置一部分时
+任务失败，不能静默降级为未签名包。
+
+- `MACOS_CERTIFICATE_BASE64`：包含证书及私钥的 `.p12` 文件经 Base64 编码后的内容。
+- `MACOS_CERTIFICATE_PASSWORD`：导出 `.p12` 时设置的密码。
+- `APPLE_API_KEY_BASE64`：App Store Connect API Key 的 `.p8` 文件经 Base64 编码后的内容。
+- `APPLE_API_KEY_ID`：App Store Connect API Key 的 Key ID。
+- `APPLE_API_ISSUER`：App Store Connect API Key 的 Issuer ID。
+
+在 macOS 上生成适合 Secrets 的单行 Base64 内容：
+
+```bash
+base64 -i DeveloperIDApplication.p12 | tr -d '\n'
+base64 -i AuthKey_XXXXXXXXXX.p8 | tr -d '\n'
+```
+
+证书必须是 Apple Developer 后台创建的 `Developer ID Application`，并在导出
+`.p12` 的 Mac 钥匙串中同时包含对应私钥。API Key 建议使用团队级 App Store
+Connect Key；`.p8` 只能下载一次。签名材料只放入 GitHub Secrets，不提交到仓库。
+
+凭据完整时，macOS 打包完成后会挂载 DMG，并分别执行 `codesign`、Gatekeeper
+`spctl` 和 `stapler` 校验；签名无效或 notarization ticket 不存在时，发布矩阵
+会在上传产物前失败。完全没有凭据时，六平台矩阵和标签发布仍可完成，但 macOS
+产物没有 Developer ID 签名或 Apple 公证，Gatekeeper 可能阻止首次打开。发布
+工作流必须在 Actions 日志与摘要中明确这一限制；获得完整凭据后应恢复签名
+发布并重新验证。
+
+Windows 代码签名仍未配置。对外分发前还应配置 Windows 签名凭据，并重新验证
+安装、升级和系统安全提示。
 
 ## 发布前冒烟测试
 
@@ -177,5 +523,54 @@ git push github "$tag"
 4. 本地知识库导入、检索和知识图谱。
 5. Ask、Execute 的权限边界与旧版 Plan 数据兼容。
 6. OpenCode 与 Continue 的权限边界、取消和超时。
-7. 智能心跳的创建、暂停、恢复和历史记录。
-8. 应用退出后无残留 Runtime 子进程。
+7. DeepSeek Harness Ask 拒绝写入和第三方插件工具，可调用 Main 管理的 Web Search/Fetch；Execute 可调用已启用插件工具。文本模型在网络调用前拒绝图片，声明图片能力的模型可以实际接收 JPEG/PNG。
+8. OpenCode Agent/Command、原生上下文 Compact，以及 Continue Rules/Prompt 预设、结构化提问和 GoodBuddy 手动摘要压缩。
+9. Runtime 原生清单把 Tools 与 Commands/LSP/Formatters 分开，显示来源及 Ask/Execute 可用性，不混入 GoodBuddy 分配的 Skills/MCP；外部 OpenCode 只报告连接状态，Continue 明确标记原生 Tools 静态发现不支持；内置 MCP 的启停与 Runtime 分配会持久化并限制后续请求，DeepSeek Harness 保持不可分配；MCP 测试只读取有界 Prompt/Resource 元数据，不读取 Resource 内容。
+10. DSH 市场可安装、停用、重新启用和移除插件；启动失败插件不会阻止 Host，并显示为自动停用。
+11. 智能心跳的创建、暂停、恢复和历史记录。
+12. 应用退出后无残留 Runtime 子进程。
+
+DeepSeek Harness 的 Electron Utility Host 可单独执行无模型、无凭据冒烟测试：
+
+```bash
+npm run smoke:deepseek-harness
+```
+
+该命令先生成 production bundle，再从 CommonJS Electron 主入口启动实际
+`utilityProcess`，等待固定 Host 完成本地主机执行器初始化与内部 ready 握手。它不会发起
+模型请求，也不会读取或传递 API Key。
+
+Windows x64 完整打包后的 Utility Host 与内置 npm 冒烟测试：
+
+```bash
+npm run build
+node node_modules/electron-builder/cli.js --win dir --x64 --publish never --config.directories.output=dist/harness-package-probe
+npm run smoke:deepseek-harness:packaged
+```
+
+该测试启动打包后的 Host，并使用打包资源中的准确 npm 版本安装一个本地临时包，
+确认 npm 依赖闭包、Electron Node 模式、`node` shim 和生命周期脚本都可用。它不访问
+npm registry，也不运行模型请求。
+
+真实 DSH 市场测试会访问公共 npm、运行第三方安装与插件代码，因此只在已明确授权时启用：
+
+```bash
+GOODBUDDY_DSH_MARKETPLACE_E2E=1 npm test -- src/main/agent/dsh-extension-marketplace.e2e.test.ts
+```
+
+该测试使用临时用户目录，经捆绑 npm 路径安装已审查的最小测试插件，并验证 Host
+加载和真实工具调用；测试结束后删除临时目录。
+
+要让真实模型同时验证插件的 Ask 拒绝与 Execute 调用，可显式提供兼容的
+OpenAI Chat Completions 配置：
+
+```bash
+GOODBUDDY_DSH_MODEL_E2E=1 \
+GOODBUDDY_DSH_API_KEY=... \
+GOODBUDDY_DSH_BASE_URL=https://api.deepseek.com \
+GOODBUDDY_DSH_MODEL=deepseek-chat \
+npm test -- src/main/agent/deepseek-harness-acp-e2e.test.ts -t "rejects a real npm plugin"
+```
+
+如需覆盖发布包内置 npm 路径，再设置 `GOODBUDDY_DSH_NPM_CLI` 与
+`GOODBUDDY_DSH_NODE_EXECUTABLE` 指向已解包应用中的 npm CLI 和应用主程序。

DESIGN.md

@@ -1,533 +0,0 @@
-# GoodBuddy 统一界面设计系统
-
-## 1. 目的与适用范围
-
-本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、知识库、智能心跳、任务与活动记录，以及后续新增的一级页面。
-
-设计系统解决两类问题：
-
-1. 统一跨页面的视觉语言、信息层级和交互反馈。
-2. 保留不同工作场景所需的布局差异，不强行把阅读、工作台、仪表盘和数据视图做成同一种页面。
-
-所有新界面必须优先使用本文定义的语义令牌、页面壳层和共享组件。现有界面迁移时应保持功能与数据语义不变，不以视觉统一为理由隐藏范围、状态或风险。
-
-## 2. 核心原则
-
-### 2.1 一致的语义，不要求相同的布局
-
-- 相同含义使用相同的颜色、间距、控件和文案结构。
-- 不同任务使用明确命名的页面壳层，不再为单个页面随意设置宽度。
-- 页签只用于同级页面导航，分段控件只用于当前视图内的单选切换，筛选控件只改变当前数据集合。
-
-### 2.2 范围始终可见
-
-知识、任务、自动化和活动记录可能属于全局或某个项目。当前范围必须在页面标题区或对象标题旁持续显示，不能只通过入口位置、默认筛选或颜色暗示。
-
-### 2.3 主任务优先
-
-- 每个页面只保留一个视觉上最突出的主操作。
-- 页面标题、范围、说明、主操作和导航按固定层级排列。
-- 次要设置、筛选和批量操作不得与主任务争夺注意力。
-
-### 2.4 状态明确且可恢复
-
-- 加载、空内容、无结果、失败、只读和权限不足是不同状态，必须分别呈现。
-- 可撤销操作优先提供撤销，不可撤销操作必须在执行前说明影响范围。
-- 不依赖颜色单独表达状态或风险。
-
-### 2.5 默认支持浅色与深色主题
-
-组件不得直接使用原始颜色值。主题差异只在令牌层定义，业务组件仅引用语义令牌。
-
-## 3. 设计令牌
-
-令牌以 CSS 自定义属性实现。`:root` 提供浅色值，`[data-theme="dark"]` 覆盖深色值。组件样式不得新增只服务于单个页面的颜色、阴影、圆角或间距常量。
-
-### 3.1 颜色令牌
-
-| 令牌 | 用途 |
-| --- | --- |
-| `--surface-canvas` | 应用和页面底色 |
-| `--surface-raised` | 卡片、面板、输入框和弹窗 |
-| `--surface-subtle` | 次级区域和控件底色 |
-| `--surface-muted` | 进度轨道和更弱的分隔表面 |
-| `--text-primary` | 标题与主要正文 |
-| `--text-secondary` | 辅助正文 |
-| `--text-muted` | 占位、时间和弱提示 |
-| `--text-on-accent` | 强调色或危险色表面上的文字 |
-| `--border-default` | 常规边框 |
-| `--border-control` | 输入框、分段控件等必须清晰可辨的控件边界 |
-| `--border-subtle` | 区块分隔线 |
-| `--accent`、`--accent-hover` | 强调文字、图标和交互反馈 |
-| `--accent-solid`、`--accent-solid-hover` | 主按钮等需要反白文字的强调背景 |
-| `--accent-selected`、`--accent-subtle` | 选中边框、选中背景和信息强调 |
-| `--success`、`--success-subtle` | 成功状态 |
-| `--warning` | 警告状态 |
-| `--danger`、`--danger-strong` | 危险文本和状态 |
-| `--danger-solid` | 最终确认按钮等需要反白文字的危险背景 |
-| `--danger-border`、`--danger-subtle` | 危险入口和失败状态背景 |
-
-浅色与深色具体值只在 `styles.css` 的主题根节点维护。状态组件必须同时显示文字或图标，不能仅靠颜色区分。
-
-### 3.2 间距令牌
-
-采用 4 像素基准：
-
-| 令牌 | 值 | 典型用途 |
-| --- | --- | --- |
-| `--space-0` | `0` | 显式取消间距 |
-| `--space-1` | `4px` | 图标内部微调 |
-| `--space-2` | `8px` | 紧凑控件、图标与文字 |
-| `--space-3` | `12px` | 表单字段内部、紧凑列表 |
-| `--space-4` | `16px` | 默认组件间距 |
-| `--space-6` | `24px` | 区块间距、窄屏页面内边距 |
-
-使用规则：
-
-- 同一组件内部优先使用 `8px`、`12px`、`16px`。
-- 同一区块内组件之间优先使用 `16px` 或 `24px`。
-- 页面级区块之间优先使用 `32px` 或 `40px`。
-- 不新增 `14px`、`18px`、`22px` 等非令牌间距。
-
-### 3.3 字体令牌
-
-界面默认使用随客户端本地打包的 `Inter Variable` 与 `Noto Sans SC Variable`：英文、数字优先使用 Inter，简体中文由 Noto Sans SC 覆盖。系统无衬线字体仅作为启动和缺失字形回退；代码、标识符和原始日志使用等宽字体栈。字体不得通过运行时网络请求加载。
-
-| 令牌 | 字号 / 行高 | 字重 | 用途 |
-| --- | --- | --- | --- |
-| `--font-caption` | `11px` | 时间、短标签和紧凑元数据 |
-| `--font-body` | `13px` | 默认界面正文 |
-| `--font-section-title` | `14px` | 卡片和区块标题 |
-| `--font-page-title` | `24px` | 一级页面标题 |
-
-使用规则：
-
-- 业务组件通过 `--font-family-ui` 与字体尺寸令牌继承字体，不创建页面专属字体栈。
-- 表单按钮、输入框、选择框和文本域必须继承界面字体，避免回退为原生控件字体。
-- 连续阅读内容使用 `14px`，持久辅助信息不得小于 `11px`。
-- 本地字体资源必须随生产包交付，并同时包含 Inter 与 Noto Sans SC 的 OFL 许可证。
-- 页面内不得通过同时放大字号、加粗和使用强调色制造多个同级主标题。
-
-### 3.4 圆角、阴影与层级
-
-| 令牌 | 值 | 用途 |
-| --- | --- | --- |
-| `--radius-control` | `8px` | 输入框、按钮、菜单项 |
-| `--radius-card` | `12px` | 卡片和面板 |
-| `--shadow-card` | 主题定义 | 卡片和选中分段控件 |
-| `--shadow-dialog` | 主题定义 | 对话框和浮层 |
-
-普通卡片通过表面色和边框区分，不默认添加阴影。阴影只表示真实的浮层关系。不允许页面自行创建高于 `--z-dialog` 的层级。
-
-### 3.5 动效令牌
-
-- `--motion-fast: 120ms`：悬停、按压、焦点反馈。
-- `--motion-normal: 180ms`：菜单、折叠区域、轻量视图切换。
-- `--motion-slow: 240ms`：对话框和抽屉。
-- 默认缓动使用 `ease-out`，退出可使用 `ease-in`。
-- 在 `prefers-reduced-motion: reduce` 下移除非必要位移和缩放，仅保留即时状态切换。
-
-## 4. 页面壳层
-
-所有一级页面使用 `PageShell`。壳层负责水平居中、最大宽度、响应式内边距、页面背景和滚动边界，业务页面不得再次设置独立的整体最大宽度。
-
-| 变体 | 最大内容宽度 | 适用场景 | 页面映射 |
-| --- | --- | --- | --- |
-| `reading` | `820px` | 连续阅读、单列编辑、对话撰写 | 聊天正文与输入区 |
-| `standard` | `960px` | 常规列表、设置、表单与任务管理 | 最近对话、任务 |
-| `dashboard` | `1040px` | 指标、卡片网格、宽表格与审计数据 | 智能心跳、活动记录 |
-| `master-detail` | 可用空间内流式铺开 | 左侧选择、右侧编辑或预览 | 知识库 |
-
-共同规则：
-
-- 宽度计算统一为 `min(100%, 变体最大宽度)`。
-- 页面左右内边距在常规桌面窗口为 `32px`，中等窗口为 `24px`，窄窗口为 `16px`。
-- 页面顶部和底部内边距默认为 `32px`。
-- `master-detail` 的左栏建议为 `280px` 至 `360px`，右栏占剩余空间。分隔线和滚动容器属于壳层，不由内容卡片模拟。
-- 聊天输入区可以粘附在 `reading` 壳层底部，但消息内容和输入区必须共享同一阅读宽度。
-- 宽表格可在 `dashboard` 内容区内部横向滚动，不得撑宽整个应用窗口。
-
-## 5. 信息层级
-
-一级页面按以下顺序组织：
-
-1. `PageHeader`
-2. `PageTabs`，仅在存在同级子页面时出现
-3. 页面级状态或重要提示
-4. 筛选与批量操作工具栏
-5. 主内容
-6. 与主内容就近关联的分页或加载状态
-
-一个页面只能有一个可见的一级标题。卡片标题不得重复页面标题。面包屑只在层级超过两级且返回关系无法通过侧栏或主从布局表达时使用。
-
-### 5.1 PageHeader
-
-`PageHeader` 统一接收以下内容：
-
-- `title`：必填，简短名词或任务名称。
-- `description`：可选，一行说明当前页面能做什么，不重复标题。
-- `scope`：涉及范围的数据页面必填，使用 `ScopeBadge`。
-- `primaryAction`：可选，页面唯一主操作。
-- `secondaryActions`：可选，最多两个直接显示，其余进入更多菜单。
-- `status`：可选，用于只读、同步中、连接异常等页面级状态。
-
-布局规则：
-
-- 标题和范围徽标在同一信息组中，范围不得放入更多菜单。
-- 主操作位于标题区右侧，窄窗口下换行到标题下方并保持靠左。
-- 不在内容卡片中再次渲染同名标题。
-- 标题区默认不粘附。只有主内容长且页面级操作需要持续可用时才启用粘附。
-
-## 6. 共享组件
-
-### 6.1 PageTabs
-
-用于同一一级页面内的同级内容面板，例如心跳的“成长概览”和“心跳计划”。
-
-- 使用 `tablist`、`tab` 和 `tabpanel` 语义，当前项使用 `aria-selected="true"`。
-- 一级页面之间的导航由应用主导航承担，不复用 `PageTabs`。
-- 标签保持短名词，不显示句号，不用页签承载开关或过滤条件。
-- 项目过多时优先重组信息架构，不把一级页签做成多行。
-- `PageTabs` 可使用默认视觉或共享的 `segmented` 视觉变体。紧凑主从工作台中的 2 至 4 个同级面板可使用与模型设置一致的分段外观，但不得因此改用按钮组语义。
-- 视觉变体不改变组件含义：分段外观的 `PageTabs` 仍使用页签语义、单一激活面板、游标焦点和方向键切换，不复制页面专属样式。
-
-### 6.2 SegmentedControl
-
-用于当前页面内互斥的视图或状态切换，例如“列表 / 网格”或少量单选状态。
-
-- 选项数量为 2 至 4 个。
-- 使用带 `aria-pressed` 的按钮组语义，支持方向键切换。
-- 不能用于多选筛选、页面导航或执行即时命令。
-- 控件宽度由内容决定，除移动窄屏外不默认等分整行。
-
-### 6.3 筛选工具栏
-
-筛选不创建第五种类似页签的视觉控件：
-
-- 2 至 4 个互斥状态可使用 `SegmentedControl`。
-- 多维条件使用统一尺寸的选择框、搜索框和复选菜单。
-- 已生效条件以文字和值明确展示，并提供“清除筛选”。
-- 无匹配结果使用“无结果”状态，不能显示为首次使用的空状态。
-- 筛选条件改变数据范围时，结果数量或当前条件必须可见。
-
-### 6.4 ScopeBadge
-
-`ScopeBadge` 表达对象或页面数据的归属范围：
-
-- 全局范围显示“全局”，并配合通用范围图标。
-- 项目范围显示“项目：项目名称”，不得只显示项目名称。
-- 未知或已失效范围显示“范围不可用”，并提供修复入口或只读说明。
-- 徽标始终包含文字，不以颜色作为唯一差异。
-- 可切换范围时，徽标作为范围选择器的触发器，并提供明确的展开状态和键盘操作。
-- 不可切换范围时，徽标为只读状态，不显示下拉箭头。
-
-创建新对象时必须在提交按钮附近再次显示目标范围。跨范围移动属于显式操作，需要说明原范围、目标范围和对关联数据的影响。
-
-### 6.5 EmptyState
-
-`EmptyState` 统一包含：
-
-- 能说明状态的图标或简洁插图。
-- 一句标题。
-- 一至两句原因或下一步说明。
-- 最多一个主操作和一个次操作。
-
-必须区分：
-
-| 状态 | 标题示例 | 操作原则 |
-| --- | --- | --- |
-| 首次为空 | “还没有知识条目” | 提供创建或导入 |
-| 筛选无结果 | “没有符合条件的结果” | 提供清除筛选 |
-| 搜索无结果 | “未找到相关内容” | 建议修改关键词 |
-| 加载失败 | “内容加载失败” | 提供重试并保留错误上下文 |
-| 无权限或只读 | “当前范围不可编辑” | 说明原因和可行路径 |
-
-空状态不得使用孤立的短句或仅显示图标。加载中不得先闪现空状态。
-
-### 6.6 危险操作
-
-共享危险操作样式包含：
-
-- `danger-ghost`：列表行、菜单和工具栏中的删除入口。
-- `danger-solid`：确认对话框中的最终危险操作。
-- `danger-zone`：设置页中集中展示的高影响操作区域。
-
-普通页面不得用实心红色按钮与主操作并列。危险入口必须使用具体动词和对象，例如“删除知识条目”，避免只写“确定”。
-
-### 6.7 数据表格与活动列表
-
-- 表头、单元格、空值、状态和行操作使用统一对齐规则。
-- 文本默认左对齐，数值右对齐，状态与短标签可居中。
-- 时间显示使用一致格式，并在需要时通过工具提示提供完整时间和时区。
-- 行操作默认放在行末。高频安全操作可直接显示，低频或危险操作进入更多菜单。
-- 活动记录必须保留操作者、动作、对象、范围、结果和时间等审计语义，不用纯图标代替关键字段。
-- 表格密度可以选择“默认”或“紧凑”，但同一页面不得混用。
-
-### 6.8 应用顶栏与全局菜单
-
-应用顶栏用于窗口级状态、侧栏开关和低频全局操作，不承担页面标题或主要导航。顶栏必须保持紧凑，不能与页面内容争夺注意力。
-
-- 顶栏高度默认为 `58px`，图标按钮使用 `34px × 34px` 点击区域。
-- Runtime 状态、同步状态等短标签使用 `--font-caption`，不得放大为正文标题。
-- 全局菜单项使用 `--font-body`，图标为 `14px`，单项高度为 `32px`。
-- 菜单标签使用短名称，例如“安全与 Runtime 设置”“使用帮助”，不得同时使用大字号、粗体和强调色。
-- 全局菜单宽度由最长标签决定，建议为 `180px` 至 `200px`；说明性长文放入目标页面，不放在菜单项中。
-- 顶栏只直接显示当前任务所需的高频操作。设置、帮助、关于和版本检查等低频操作进入同一个全局菜单。
-- 窄窗口下优先压缩状态标签并保留图标按钮，不隐藏窗口控制、当前范围或进行中的风险状态。
-- 菜单使用 `menu`、`menuitem` 语义，支持上下方向键、Home、End 和 Escape，关闭后焦点返回触发按钮。
-
-### 6.9 应用通知与就地反馈
-
-应用级通知统一进入全局通知视口，页面不得自行复制通知卡片或在内容流中长期堆放短期消息。
-
-- 异步操作成功、无需立即处理的信息，以及不属于某个字段的异步失败，使用应用级 `success`、`info` 或 `error` 通知。
-- 成功和信息通知默认在约 4.5 秒后自动消失；错误通知保持可见，直到用户关闭或同一去重键的更新替换它。
-- 同一语义和文案的重复通知应去重。通知正文必须有长度上限，不包含凭据、私人内容或未脱敏的提供商响应。
-- 字段校验、破坏性确认、操作进度、阻塞整个页面的状态，以及需要就地重试或修正的错误保留在相关控件附近。
-- 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 `alert` 和 assertive 实时区域，成功与信息使用 `status` 和 polite 实时区域。
-- 一个事件只能选择一种主要反馈位置，不得同时显示页内横幅和全局通知。失败时不得因通知切换而清空用户输入、筛选或未提交草稿。
-
-## 7. 交互状态
-
-所有可交互组件必须实现：
-
-- 默认：文本、边框和背景层级清晰。
-- 悬停：提供轻量背景或边框反馈，不改变布局。
-- 按下：反馈比悬停更强，持续时间使用 `--motion-fast`。
-- 键盘焦点：显示至少 `2px` 的高对比焦点环，不被容器裁切。
-- 选中：同时使用背景、边框、图标或字重中的至少两种信号。
-- 禁用：降低强调度，同时保留可读标签，并通过说明或工具提示解释原因。
-- 加载：防止重复提交，保留原按钮宽度并显示进行中标签。
-- 错误：字段或局部操作错误就近显示可执行说明；非局部异步错误使用不会自动消失的应用级错误通知。
-
-异步提交成功后更新内容并通过统一应用通知提供明确反馈。失败时保留用户输入和筛选上下文。
-
-## 8. 范围与数据语义
-
-### 8.1 页面范围
-
-- 页面范围决定当前列表、搜索、创建和批量操作针对的数据集合。
-- 页面标题区必须持续显示当前范围。
-- 搜索框占位文案应反映范围，例如“搜索当前项目的知识”。
-- 切换范围后清理不再有效的选择项，并明确提示数据集合已变化。
-
-### 8.2 对象范围
-
-- 详情页或主从布局的右侧面板显示所选对象自身的范围。
-- 当页面范围与对象范围不一致时，必须显示解释，不得静默混合。
-- 全局对象可被项目引用时，应分别表达“归属范围”和“当前引用关系”。
-
-### 8.3 操作范围
-
-批量操作、导入、删除、移动和自动化运行前，界面必须明确：
-
-1. 将影响哪些对象。
-2. 对象属于全局还是某个项目。
-3. 操作是否可撤销。
-4. 是否影响关联任务、知识引用或历史记录。
-
-## 9. 破坏性操作政策
-
-### 9.1 风险等级
-
-| 等级 | 示例 | 要求 |
-| --- | --- | --- |
-| 低 | 移除可立即恢复的筛选、取消未保存草稿 | 通常无需确认，必要时提供撤销 |
-| 中 | 删除单个可恢复对象、停止正在运行的任务 | 显式确认或操作后撤销，说明直接影响 |
-| 高 | 永久删除、批量删除、清空历史、删除被引用对象 | 必须使用确认对话框，说明范围、数量和不可逆性 |
-
-### 9.2 确认对话框
-
-- 标题包含具体动作和对象，例如“永久删除 12 条活动记录？”
-- 正文说明范围、关联影响和恢复可能性。
-- 取消按钮在前，危险按钮在后。初始焦点放在取消按钮。
-- 最终按钮使用 `danger-solid`，标签重复具体动作。
-- 仅对高影响且不可恢复的操作要求输入对象名称或确认短语，避免把摩擦用于所有删除。
-- 提交期间锁定重复操作。失败后保持对话框打开并显示可处理的错误信息。
-
-### 9.3 撤销与反馈
-
-- 可恢复删除优先在操作后显示带“撤销”的持久通知。
-- 撤销窗口结束前，不把操作描述为“永久删除”。
-- 删除成功后更新列表、选中项和计数。主从布局中被删除对象的详情面板应回到明确的未选择状态。
-- 审计记录不得因普通对象删除而被静默移除。
-
-## 10. 深色主题
-
-- 深色主题通过语义令牌替换实现，不在组件中使用主题条件分支选择原始颜色。
-- 表面层级主要依靠亮度和边框区分，避免大面积纯黑与高亮白形成刺眼对比。
-- 输入框、代码块、表格悬停、选中行、弹窗遮罩和滚动条必须分别检查深色值。
-- 图片、图表和状态色在深色背景下保持可读。图表系列不能只靠色相区分，还应使用形状、线型或标签。
-- 焦点环、危险文本和弱文本在两种主题下都满足对比度要求。
-- 原生控件和滚动条声明正确的 `color-scheme`。
-- 主题切换不得导致布局、边框宽度或字号变化。
-
-## 11. 无障碍
-
-### 11.1 键盘与焦点
-
-- 所有交互均可通过键盘完成。
-- 焦点顺序与视觉顺序一致，打开弹窗后焦点进入弹窗，关闭后返回触发元素。
-- 页面导航链接按正常 Tab 顺序操作。同页签组和单选组使用方向键，菜单使用上下方向键和 Escape。
-- 不给不可交互容器添加焦点，不用 `div` 模拟按钮而缺少按钮语义。
-
-### 11.2 语义与标签
-
-- 图标按钮必须有可访问名称，并在视觉上提供工具提示。
-- 表单控件有持久标签，不能只使用占位文案。
-- 状态变化使用适当的实时区域，但避免对频繁日志逐条播报。
-- 错误信息与对应字段建立程序化关联。
-- 表格使用正确的表头关系，复杂审计记录在窄屏下仍保持字段标签。
-
-### 11.3 对比度与触控目标
-
-- 正文与背景对比度至少为 `4.5:1`，大号文本至少为 `3:1`。
-- 控件边界、焦点和关键图形对比度至少为 `3:1`。
-- 常规交互目标建议至少 `32px × 32px`。紧凑表格可使用 `28px` 高度，但相邻目标之间必须有足够间隔。
-- 文字缩放至 `200%` 时，核心操作、范围信息和错误提示不能被裁切。
-
-## 12. 响应式与窗口规则
-
-GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证任务连续性，不简单隐藏信息。
-
-### 12.1 宽窗口，`1200px` 及以上
-
-- 使用各 `PageShell` 的完整最大宽度。
-- `dashboard` 可使用 3 至 4 列卡片。
-- `master-detail` 保持双栏，详情区获得主要空间。
-
-### 12.2 中等窗口，`960px` 至 `1199px`
-
-- 页面左右内边距为 `24px`。
-- 仪表盘降为 2 列。
-- 主从布局缩小左栏，但不得低于 `280px`。
-- 表格优先收起低优先级列到详情或行展开区，不隐藏范围、状态和时间。
-
-### 12.3 窄窗口，`720px` 至 `959px`
-
-- `PageHeader` 的操作区换行。
-- `master-detail` 变为单面板导航。进入详情后提供明确返回列表的按钮。
-- 仪表盘使用单列或 2 列，取决于卡片最小宽度。
-- `PageTabs` 可单行横向滚动，不换成下拉菜单。
-- 宽表格在自身容器内横向滚动，并固定关键标识列时确保键盘可达。
-
-### 12.4 极窄窗口，小于 `720px`
-
-- 页面左右内边距为 `16px`。
-- 标题、范围徽标和操作纵向排列，但范围不得隐藏。
-- 主操作可以占满可用宽度，次操作进入更多菜单。
-- 分段控件可等分整行，筛选工具栏改为可展开区域。
-- 聊天输入区保持可见，并考虑窗口安全边距。
-- 对话框使用接近全宽的布局，仍保留 `16px` 外边距。
-
-## 13. 页面应用规范
-
-### 13.1 聊天
-
-- 使用 `reading` 壳层，消息流与输入区共享宽度。
-- 对话标题和当前项目范围位于 `PageHeader` 或对话上下文区，不在消息流中重复。
-- 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。
-- 空对话展示可执行的起始建议，发送失败保留输入并提供重试。
-
-### 13.2 最近对话
-
-- 使用 `standard` 壳层和统一 `PageHeader`。
-- 搜索、范围和时间筛选位于筛选工具栏。
-- 行项目统一显示标题、范围、最近更新时间和必要状态。
-- 删除入口使用 `danger-ghost`，并按数据可恢复性执行确认或撤销策略。
-
-### 13.3 知识库
-
-- 使用 `master-detail` 壳层。
-- 左侧负责范围、搜索、筛选和条目选择，右侧负责详情、编辑和预览。
-- 两侧均只使用语义颜色令牌，禁止内联浅色背景或边框。
-- 选中条目后持续显示对象范围。没有选中项与知识库为空必须使用不同状态。
-- 窄窗口切换为单面板导航，不把双栏压缩到不可读。
-
-### 13.4 智能心跳
-
-- 使用 `dashboard` 壳层。
-- 顶部先呈现运行状态、当前范围和主操作，再呈现指标和配置。
-- 状态卡片使用统一状态令牌，不只依赖颜色。
-- 运行历史与配置使用明确区块，不以多套相似页签混合导航、开关和筛选。
-
-### 13.5 任务与活动
-
-- 任务使用 `standard` 壳层，活动记录使用 `dashboard` 壳层。
-- “任务 / 活动”作为同级页面时使用 `PageTabs`。
-- 任务状态筛选使用 `SegmentedControl` 或筛选工具栏，不再模拟页签。
-- 活动记录保留审计字段和范围，支持独立容器横向滚动。
-- 批量停止、删除和清空历史遵循破坏性操作政策。
-
-### 13.6 魔法笔记
-
-- “笔记 / 待办”属于同一工作台内的同级内容面板，使用 `PageTabs` 的 `segmented` 视觉变体，与模型设置的分段控件保持同一外观。
-- 页签切换保留 `tablist`、`tab` 和 `tabpanel` 语义；待办状态仍使用独立的 `SegmentedControl`，不得与内容页签合并。
-- 创建、保存、更新、删除和 AI 评论完成等短期结果进入应用级通知，不在编辑区或列表上方堆放页内通知。
-- 标题或正文校验、删除确认、同步进度和可就地恢复的错误仍靠近对应编辑器或操作呈现。
-
-## 14. 文案规则
-
-- 使用简体中文，动词直接、对象明确。
-- 页面标题使用名词，例如“知识库”“智能心跳”“活动记录”。
-- 按钮使用“动词 + 对象”，例如“新建任务”“导入知识”“停止运行”。
-- 状态文案描述事实，例如“正在同步”“上次运行失败”，不使用含糊的“异常”。
-- 错误提示包含发生了什么、用户可以做什么。保留必要的错误上下文，但不得暴露凭据、授权头、私人文档或未脱敏的提供商响应。
-- 同一概念固定使用一个名称，不交替使用“项目空间”“工作区”“范围”等近义词。产品内统一使用“范围”表达全局与项目归属。
-
-## 15. 迁移检查清单
-
-### 15.1 基础层
-
-- [ ] 建立浅色与深色语义颜色令牌，移除业务组件中的原始颜色值。
-- [ ] 建立间距、字体、圆角、阴影、层级和动效令牌。
-- [ ] 为主题切换、减少动态效果和原生控件设置全局规则。
-- [ ] 建立组件交互状态和焦点环基线。
-
-### 15.2 页面壳层与层级
-
-- [ ] 实现 `PageShell` 的 `reading`、`standard`、`dashboard`、`master-detail` 变体。
-- [ ] 按页面映射替换 `820px`、`900px`、`1040px` 和全宽等分散宽度声明。
-- [ ] 每个一级页面只保留一个 `PageHeader` 和一个一级标题。
-- [ ] 移除内容卡片中与页面标题重复的标题。
-
-### 15.3 共享组件
-
-- [ ] 实现并迁移 `PageHeader`。
-- [ ] 使用 `PageTabs` 统一同级页面导航。
-- [ ] 使用 `SegmentedControl` 统一少量互斥视图和状态切换。
-- [ ] 需要分段外观的同级面板使用 `PageTabs` 的共享 `segmented` 变体，不复制控件样式。
-- [ ] 建立统一筛选工具栏，移除以页签样式伪装的筛选。
-- [ ] 将短期成功、信息和非局部异步错误接入应用通知视口，移除页面专属通知横幅。
-- [ ] 实现 `ScopeBadge` 并覆盖全局、项目、失效和可切换状态。
-- [ ] 实现 `EmptyState` 的首次为空、无结果、失败和只读变体。
-- [ ] 实现 `danger-ghost`、`danger-solid` 和 `danger-zone`。
-
-### 15.4 页面迁移
-
-- [ ] 聊天迁移到 `reading`，统一消息流与输入区宽度。
-- [ ] 最近对话迁移到 `standard`，统一搜索、范围、时间和删除行为。
-- [ ] 知识库迁移到 `master-detail`，清除内联浅色样式并补齐窄窗口单面板流程。
-- [ ] 智能心跳迁移到 `dashboard`，统一状态卡片、配置和运行历史层级。
-- [ ] 任务迁移到 `standard`，活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。
-
-### 15.5 验收
-
-- [ ] 在浅色与深色主题下检查所有页面、弹窗、菜单、输入框、表格和空状态。
-- [ ] 在大于等于 `1200px`、`960px`、`720px` 和小于 `720px` 的窗口宽度检查布局。
-- [ ] 仅使用键盘完成导航、筛选、创建、编辑、确认和取消。
-- [ ] 验证焦点恢复、可访问名称、表单错误关联和实时状态播报。
-- [ ] 验证页面范围、对象范围和操作范围在关键流程中始终可见。
-- [ ] 验证删除、批量操作、停止运行和清空历史符合风险等级策略。
-- [ ] 验证加载中、首次为空、筛选无结果、搜索无结果、失败和只读状态不会互相混用。
-
-## 16. 完成标准
-
-一个页面只有在满足以下条件时才视为完成迁移：
-
-1. 使用明确的 `PageShell` 变体，没有页面专属整体宽度。
-2. 使用统一标题层级、共享导航和筛选控件。
-3. 所有颜色、间距、字体、圆角和阴影来自令牌。
-4. 全局或项目范围在浏览、创建、编辑和危险操作中均可见。
-5. 浅色、深色、键盘和各窗口宽度下均可完成核心任务。
-6. 空状态、错误状态和危险操作符合本文规则。

FEATURES.md

@@ -1,112 +1,695 @@
-# GoodBuddy 功能矩阵与路线图
+# GoodBuddy Feature Matrix and Roadmap
 
-本文集中记录 GoodBuddy 已提供、正在开发和计划中的主要能力。路线图用于表达产品方向，不代表未完成能力已经包含在当前发布版本中。
+**English** | [简体中文](./FEATURES.zh-CN.md)
 
-## 状态说明
+This document records the capabilities available in GoodBuddy and its roadmap.
+Unchecked items are not included in the current release unless the item says
+otherwise.
 
-- [x] **已提供**：已在当前代码和产品流程中提供。
-- [ ] **开发中**：已进入实现或集成阶段，完整交付前仍可能调整。
-- [ ] **规划中**：已确认产品方向，尚未承诺具体发布时间。
+## Status
 
-## 功能总表
+- [x] Available
+- [ ] In development or planned, as described by the item
 
-### 桌面基础、工作空间与上下文
+## Feature Matrix
 
-- [x] **跨平台桌面应用**：支持 Windows、macOS、Linux，以及 `x64`、`arm64` 发布目标。
-- [x] **Projects 与独立对话**：按项目隔离上下文，管理会话、附件和 Git 工作区变更。
-- [x] **文件、截图、窗口、剪贴板上下文**：用户明确选择后才加入模型上下文。
-- [ ] **项目 Agent Space 与策略包**（规划中）：在现有 Project 中统一角色、知识、Skills/MCP、模型、变量、审批策略、预算和超时，并支持模板化复用。
+### Desktop foundation, workspaces, and context
 
-### Agent Runtime 与模型连接
+- [x] **Cross-platform desktop application**: Supports Windows, macOS, and
+  Linux release targets on `x64` and `arm64`.
+- [x] **Chinese hardware and operating-system coverage**: Standard Linux
+  packages target compatible x64 and arm64 environments, including UOS, Kylin,
+  Hygon, Zhaoxin, Kunpeng, and Phytium systems. This is not vendor certification.
+  LoongArch has a separate experimental loong64 preview outside standard
+  releases and automatic updates; no preview is planned for 0.12.12. See the
+  [preview boundaries](./docs/development/loongarch-preview-build.md).
+- [x] **Configurable global shortcut**: Enable, disable, or record an Electron
+  accelerator under Platform Features / General. The default remains
+  `CommandOrControl+Shift+Space`; if registration conflicts or saving fails,
+  GoodBuddy keeps the previously registered shortcuts and shows an actionable
+  status.
+- [x] **Projects, independent conversations, and conversation branches**:
+  Isolates context by project and manages conversations, attachments, and Git
+  workspace changes. A stable local conversation can be copied into an
+  independent branch; the branch retains a source badge but does not copy
+  Tasks, queues, or artifact ownership. The project selector distinguishes
+  local, managed SSH, and remote messaging-channel projects. Managed SSH
+  projects are grouped by Host, with the real Agent connection state on the
+  Host heading and only the remote path on each project row.
+- [x] **File, screenshot, window, and clipboard context**: Added to model
+  context only after explicit user selection.
+- [x] **Per-file workspace diffs**: Changed files expose separate staged and
+  unstaged diffs, including deleted, renamed, and untracked files. Refresh
+  reloads the selected diff, browsed directory, and expanded directories; more than 50 changes
+  remain accessible through incremental loading.
+- [x] **Workspace file and Git management**: Create, rename, move, and delete
+  files or directories, inspect properties, search and switch local or remote
+  branches, create branches, explicitly Fetch, and browse commit history and
+  per-file commit diffs. File and Git controls are grouped by view, branch
+  search uses the shared compact form style, and subdirectories retain text
+  breadcrumbs without an isolated root icon. Commit history stays docked at
+  the bottom, initially expands to half the Git content area, and supports
+  resizing with independently scrolling panes and one shared refresh action.
+  Project switches automatically detect Git without reusing another project's
+  status. Moves stay inside the workspace,
+  deletion requires confirmation, and branch conflicts never trigger automatic
+  stash or discard. Managed SSH operations require Agent `0.11.23`.
+- [x] **Rich responses**: Supports GitHub Flavored Markdown, LaTeX math,
+  constrained Mermaid diagrams, and static in-conversation HTML previews.
+  Complete HTML and HTML code blocks can be previewed in place after an Agent
+  reply finishes, with icon actions to reveal the source or open a full-screen
+  preview. The feature is on by default and can be disabled under Platform
+  Features / General; previews cannot run scripts, access the network, submit
+  forms, or open windows.
+- [x] **AI response and full-conversation copy**: Completed AI responses expose
+  a bottom action that copies Markdown source without reasoning, tool logs, or
+  citation metadata. Full-conversation copy uses the same validated
+  Preload/Main clipboard path.
+- [x] **Assistant workbar, multiple terminals, and resizable layouts**: The
+  right workbar uses a persistent “+” capability catalog and application tabs.
+  Task Center and Workspace are permanent singleton tabs; browser tabs are
+  independent instances. Task Center can show the current project, global
+  tasks, or all projects, and retains the selected scope with the layout.
+  Users can open multiple independent terminals for the current local or
+  managed SSH project with bounded output, resizing, termination, and explicit
+  reconnection. Closing a terminal tab ends its Shell; restarting the app
+  restores only an ended tab description and never restarts the Shell. The
+  main sidebar and Magic Notes list support pointer and keyboard resizing;
+  the notes list can be hidden, remembers its layout, and stacks at narrow
+  widths.
+- [ ] **Project Agent Space** (planned): Unifies roles, knowledge, Skills/MCP,
+  models, approval policy, budgets, and timeouts in a Project, with reusable
+  templates.
+- [ ] **Application navigation and system-tool shortcuts** (design only):
+  Plans fixed system entries, configurable built-in application visibility,
+  and footer shortcuts into the existing workbar. These are not implemented
+  interface changes. See the [design](./docs/features/application-tool-navigation/README.md).
+- [ ] **Additional assistant workbar and execution-space capabilities**
+  (planned): Builds on the current workbar and multiple terminals with
+  supervision, unified Runtime monitoring, managed processes, safe static HTML
+  preview, target-pinnable workspace/browser/artifact instances, bottom
+  docking, and separate windows. Task Center remains the singleton Task index;
+  attachments and knowledge remain in the conversation composer, while memory,
+  when implemented, and historical execution context belong to the associated Task. See
+  the [Feature PRD](./docs/features/assistant-workbar/prd.md).
+- [ ] **ShareServer Office co-editing** (design): Uses an optional ShareServer
+  integration with ONLYOFFICE Docs to open multiple filename-labelled document
+  tabs in the assistant workbar. The planned scope covers DOCX, XLSX, and PPTX
+  manual editing, save and undo, source-file conflict protection, and later AI
+  selection edits. The selected ShareServer and editor process document content;
+  Desktop neither bundles nor starts Document Server and does not claim offline
+  editing when no service is configured. See the
+  [design](./docs/features/office-document-editing/README.md).
 
-- [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行和图像生成。
-- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、取消、超时和活动记录。
-- [x] **统一 Runtime 配置来源**：普通会话和消息通道共用“Agent Runtime”中的 OpenCode/Continue 模型来源、自有配置、程序路径和服务地址；通道只选择 Runtime 类型，每次远程请求动态解析当前全局配置。
-- [x] **Ask 与 Execute 工作模式**：Ask 保持只读；Execute 运行已启用且受边界约束的工具。
-- [x] **专家与 Subagent**：支持显式专家、团队分析和最多三个只读专家并行分析。
-- [x] **角色绑定模型连接**：每个角色可继承默认模型或选择独立文本模型连接，失效连接安全回退默认模型，综合角色始终继承默认模型。
-- [x] **多协议模型配置**：支持 Anthropic Messages、OpenAI Chat Completions、OpenAI Images 和无认证本机模型。
-- [x] **Main-only 凭据保护**：API Key 使用系统安全存储加密，不暴露给 Renderer。
-- [ ] **可执行 Subagent 与结构化委派**（规划中）：在现有只读专家之外提供显式 Execute 委派，限制嵌套深度、并行数、Token、时间和工具权限，并保留父子任务审计。
+### Agent Runtimes and model connections
 
-### Skills、MCP 与知识库
+- [x] **Direct model Runtime**: Supports question answering, knowledge
+  synthesis, controlled tool execution, image generation, and reference-image
+  editing through providers supporting the OpenAI-compatible image-editing
+  endpoint. Editing sends attached images as multipart data and still requires
+  validated inline image output rather than fetching provider-returned URLs.
+  Follow-up image requests reuse the latest successful image and conversation
+  text, including after reopening a saved conversation; explicit attachments
+  take priority. Missing editing support does not block text-based generation:
+  the affected reply shows a quiet footer explaining that reference images were
+  not used. See [image generation](./docs/features/image-generation/README.md).
+- [x] **Direct model programming agent**: Local direct text models can run the
+  platform Shell in Execute mode and delegate one level of programming
+  Subagent work while inheriting the parent request's mode, model, workspace,
+  and capability scope. OpenCode, Continue, DeepSeek Harness, and managed SSH
+  do not receive duplicate copies of these tools. The Windows local command
+  path and a real-model edit, test, fix, and review loop have passed; native
+  macOS and Linux command validation remains. Execute commands can select
+  absolute, relative, or symbolic-link directories outside the workspace;
+  the workspace stays the default and relative-path base. Ask remains read-only.
+- [x] **OpenCode and Continue**: Use isolated child processes, an environment
+  variable allowlist, unified configuration, cancellation, startup and control-request
+  deadlines, bounded streaming output, and activity records. Shared process
+  cleanup preserves complete Windows process-tree termination and terminates
+  POSIX process groups when a child uses an independent process group. Chat
+  status checks use a one-shot Runtime probe that is immediately cleaned up
+  rather than entering the model-and-project execution cache. For managed
+  local OpenCode, this passive check validates the selected path and model
+  credential without starting a throwaway server; the explicit settings test,
+  native inventory still performs full startup and health checks, then shares
+  that execution Runtime with the first real request instead of cold-starting
+  another server. Execution Runtimes remain reusable per project, while local
+  OpenCode configuration dependencies and content-addressed Skill snapshots are
+  shared globally across projects. Session data, tool output, and request-scoped
+  MCP state remain isolated. GoodBuddy-managed local OpenCode keeps
+  requests in the same conversation ordered, while different conversations in
+  the same project and different projects can run in parallel. Request-scoped
+  dynamic MCP tools remain isolated through default wildcard disablement and
+  explicit current-request enablement. Managed local and remote OpenCode skip
+  unused automatic Git snapshots to avoid synchronous diff stalls; file tools,
+  subagents, and workspace Git diffs remain available. Continue continuously
+  drains unused utility-host stdout so console output cannot fill its pipe.
+  These changes apply to newly started Runtimes, not external OpenCode Servers.
+  OpenCode and Continue runs do not stop
+  at a fixed tool-call or activity count, and every observed tool and Subagent
+  activity remains in the local conversation instead of being discarded while
+  the native task continues.
+  Interactive questions are answered only by foreground conversations; scheduled tasks, remote channels,
+  delegated work, and other background runs fail immediately with guidance to
+  rerun in the foreground
+  instead of waiting indefinitely. Local OpenCode startup uses the selected
+  absolute path directly without checking the file or running `--version`
+  first; invalid paths fail at actual launch. On managed Linux ARM Hosts,
+  Runtime activation reuses the registry and manifest verified during setup
+  instead of rehashing or rechecking the complete OpenCode binary.
+- [x] **Managed SSH OpenCode loop (technical preview)**: Controlled by the
+  separate Remote Projects (Technical Preview) tab under Settings / Platform
+  Features and disabled by default. Disabling it does not affect local
+  projects, ordinary desktop capabilities, or desktop releases. When enabled,
+  users can manage SSH Hosts with pinned Host Keys, browse bounded remote
+  directories, and create Ask or Execute projects. Both modes start the
+  signed Runtime directly without bubblewrap. Ask applies OpenCode's Ask
+  permission configuration and permits only native read approvals at the
+  Agent tool-dispatch boundary, while Execute explicitly allows native permissions
+  and retains all permissions of the selected SSH account. The Agent owns accepted Prompts,
+  provider/tool rounds, Runtime processes, a stable model ledger, and a bounded
+  semantic transcript over a private Unix socket and ACP v5. Work continues on
+  the Host after Desktop exit, network loss, or local-process termination.
+  Reconnection attaches only to the original controller, binding, and
+  operation, then atomically merges provenance into the original conversation
+  without resending the Prompt. Model profiles and API keys enter Agent memory
+  only for the accepted operation and are not written to the Renderer, SSH
+  arguments, remote environment, or disk. Remote components are not embedded
+  in the desktop package; switching projects updates only local selection and
+  does not connect or download. Settings reads a small signed catalog and
+  reports the local version, latest compatible online version, and update
+  state for Linux x64, Linux arm64, and macOS arm64. Intel Macs are not supported.
+  Downloads occur only after a user action, and
+  packages can also be imported or exported offline. Each compound `.gbagent`
+  package contains the Agent, fixed Node, and the compatible OpenCode Runtime
+  maintained by the desktop source. Online sources follow the GitHub/Beijing
+  OSS choice in About and Updates. The cumulative signed catalog binds minimum
+  Desktop version, Agent protocol, platform, architecture, size, SHA-256, and fixed URL.
+  All three targets share one catalog. Users must upgrade Desktop before the
+  first mixed-platform catalog is published because older Linux-only readers
+  reject catalogs containing Darwin entries.
+  The public-key registry accepts equivalent JSON whitespace and line endings
+  while still strictly validating schema, Ed25519 keys, environment, and
+  revocation; catalog, package, manifest, payload signatures, and streaming
+  SHA-256 remain unchanged. A missing architecture package disables managed
+  SSH only for that architecture. Projects store only Host, remote path,
+  Runtime selection, and mode. Current Host identity is read when a
+  Workspace/Runtime is first used, then reused by other projects in the same
+  process. Managed SSH conversations expose only supported OpenCode choices.
+  Multiple projects and conversations can run concurrently on one Host;
+  Agent-owned prompts are not stopped at a fixed model-call count or
+  prompt-wide output-token total, and Runtime output uses transport
+  backpressure instead of cancellation when GoodBuddy buffers fill;
+  recovery separately reports network, Agent, Runtime, committed-event cursor,
+  completion, or failure/retry and blocks only the affected project. A real
+  Linux x64 Host has covered short and long detach, forced local harness exit,
+  concurrency, SSH relay loss, cancellation, definite and uncertain provider
+  failure, Agent `SIGKILL`/restart, and recovery from a reopened Desktop SQLite
+  database. Successful tool START/END events appear exactly once, with no
+  Prompt, provider, or tool replay observed. The current Agent source lock is
+  `0.11.23`, while the current Desktop release candidate is `0.12.12`; formal
+  publication status follows the separate Agent and Desktop
+  release channels. Current macOS source has passed native package installation,
+  detached lifecycle, Attach, real Ask/Execute, and cancellation of tools in
+  separate process groups on a real Host; this does not imply publication.
+  Agent `0.11.23` adds remote workspace management and optional model limits;
+  its bundled Runtime no longer imposes a fixed ten-minute Prompt deadline.
+  Unlimited request duration retains a separate connection timeout. Upgrade
+  Desktop to `0.12.11` before downloading and updating the Host's Agent.
+- [x] **Manual SSH Host environment provisioning source path**: After Host Key,
+  authentication, and system probes succeed, GoodBuddy saves the Host and
+  read-only probes the shared Agent/Runtime. Saving a Host or opening a project
+  never installs automatically. A Host card has one primary action based on
+  version facts, Install Remote Environment, Update Remote Environment, or
+  Reinstall, plus a secondary SegmentedControl for Auto, Host Download, or
+  GoodBuddy Transfer. The selection defaults to Auto and is not persisted; a
+  Version Matched badge does not mean the environment is healthy. Auto probes
+  only before operation preparation and chooses one acquisition route.
+  Explicit choices remain in effect, and prepare, commit, or adoption failures
+  do not silently fall back across acquisition routes. Both routes deliver the
+  same signed compound `.gbagent` into fixed staging and share control-plane
+  prepare, commit, Agent activation/health, Runtime activation, finalize, and
+  explicit cleanup. The GoodBuddy route can download and validate a missing
+  candidate during the same operation, cache it with a lease, and stream one
+  archive plus its verified bootstrap Node over bounded SFTP without loading
+  the roughly 294 MiB package into a Main-process `Buffer`; the Host performs
+  one complete payload verification while extracting. An unfinished operation
+  stores only the operation ID needed to clean staging. A later update makes a
+  best-effort cleanup and starts prepare again, without persisting a remote
+  metadata copy or allowing cleanup failure to block a new update or roll back
+  a healthy environment. Existing projects resolve current Host identity on
+  demand and run a fixed `attach-or-bootstrap`; registered health,
+  capabilities, and prompt startup do not scan the full payload. See the
+  [design](./docs/features/remote-host/environment-provisioning-technical-design.md).
+- [ ] **Real-Host acceptance for SSH Host environment provisioning**: The
+  current source passed isolated Linux x64 package installation, Ask/Execute,
+  native subagent external writes, reconnection, and stop/bootstrap.
+  The complete Host-card acquisition matrix across GitHub, Beijing mirror,
+  Linux x64/arm64, cancellation, and offline GoodBuddy transfer remains.
+  Candidate CI/native packaging and system sleep/wake are not yet verified;
+  this partial development evidence does not imply publication.
+- [x] **DeepSeek Harness (preview)**: Uses the fixed GoodBuddy Host and an
+  OpenAI-compatible model connection. It prefers an administrator-provided
+  connection, otherwise follows the compatible default model or first
+  compatible connection without requiring a duplicate selection. Settings
+  displays the actual administrator or fallback model source. Ask permits
+  only real Host-registered `read` and `skill` tools plus Main-managed Web
+  Search/Fetch proxies, and rejects plugin impersonation of those names.
+  Execute allows all enabled built-in and plugin tools with the current user's
+  permissions. Image input follows the selected model connection's declared
+  capability: text models reject images before Host or model invocation, while
+  image-capable models receive bounded inline JPEG/PNG content through a
+  temporary Attachment Store.
+- [x] **DSH npm plugin marketplace**: Disabled by default and searches public
+  npm `dsh-plugin` packages only after explicit user enablement. It uses the
+  bundled npm to install exact versions with ordinary lifecycle scripts and
+  supports enable/disable, JSON configuration, removal, automatic disablement
+  after startup failure, and offline management of installed plugins.
+  Disabling the marketplace hides only the catalog and management interface;
+  it does not change the enabled state of installed plugins, and third-party
+  code is not subject to Ask initialization isolation.
+- [x] **Ask and Execute work modes**: Ask remains read-only. Execute is the
+  user's authorization for all tools, processes, network access, and writable
+  paths available to the current local or SSH account, including paths outside
+  the workspace and native subagent work.
+- [x] **Efficient direct-model workspace tools**: Direct models use bundled
+  ripgrep for compact file discovery and content search, read large UTF-8 files
+  by line, and apply multi-file patches in Execute. Ask can search and read but
+  cannot patch or run commands; packaged ripgrep does not require a system install.
+- [x] **Long context and paged tool output**: Message history, long replies,
+  and parsed document text no longer use the previous fixed truncation limits.
+  Direct models can continue reading stored command and Subagent output in
+  pages; the selected model's context window and bounded transports still apply.
+- [x] **Native Runtime interaction routing**: OpenCode and Continue questions
+  support choices, yes/no, free-text answers, and skipping through the existing
+  question card. OpenCode also routes questions from owned child sessions.
+  Successful answers and skips retain the original questions and answers
+  across rounds and local conversation reloads; answers discarded by older
+  versions cannot be recovered.
+  Execute permission confirmations are handled automatically rather than
+  waiting for another approval. See the [interaction boundaries](./docs/features/assistant-workbar/runtime-interactions.md).
+- [x] **Experts and Subagents**: Supports explicit experts, team analysis, and
+  up to three experts running in parallel. Experts inherit the parent
+  Ask/Execute mode and can use enabled local direct-model tools; Ask remains
+  read-only. They are not remote OpenCode child sessions. Chat shows each
+  expandable full expert response first and the main Agent's synthesis below,
+  and persists both with the conversation.
+- [x] **OpenCode child progress and final results**: Child cards show ordered
+  text, reasoning, and tool progress separately from the final result. Remote
+  live progress requires Agent `0.11.20`; older packages still expose final
+  results without reconstructing missing progress.
+- [x] **OpenCode event-stream cleanup**: Each completed or cancelled request
+  closes its own subscription without cancelling parallel conversations.
+- [x] **Accurate message-footer status**: Distinguishes request preparation,
+  retry waiting, retry dispatch, tool activity, pending answers, and terminal
+  states. Local OpenCode reports native retry attempts and scheduled times;
+  direct models report their own backoff phase. Footer dots are static, and
+  unsupported Runtime retry details are not invented. Conversation-list
+  indicators and send/stop behavior remain unchanged.
+- [x] **Simplified Runtime selection**: Conversation and project menus no
+  longer enumerate every Runtime/model combination. Configure Runtime models
+  in system settings; saved fixed project selections remain usable and
+  explicitly display their fixed model.
+- [x] **Role-bound model connections**: Each role can inherit the default model
+  or select an independent text-model connection. Invalid connections safely
+  fall back to the default; the synthesis role always inherits the default.
+- [x] **Multiple model protocols**: Supports Anthropic Messages, OpenAI
+  Responses, OpenAI Chat Completions, OpenAI Images, and unauthenticated local
+  models. New users receive a local Ollama-compatible default and no
+  preconfigured third-party cloud provider. During upgrades, GoodBuddy
+  replaces a historical default only when it has never received credentials
+  and still exactly matches the old built-in value; explicitly saved
+  connections and encrypted credentials remain unchanged. Existing
+  deployments that supply credentials only through compatible environment
+  variables retain their historical connection parameters, while generic
+  model environment variables still take precedence. Save and Test Model sends
+  a bounded real text or image-generation request and validates the generated
+  result instead of testing HTTP reachability alone, so it may incur a small
+  provider usage charge.
+- [x] **Custom model request fields**: Each LLM connection accepts bounded
+  JSON objects for additional request headers and top-level body fields.
+  Direct requests and Continue support both; local OpenCode and DeepSeek
+  Harness use only their natively supported headers, while the managed SSH
+  OpenCode model gateway supports both. Runtime, protocol, and authentication
+  fields take precedence, and these ordinary connection settings must not be
+  used to store API keys or other secrets. See
+  [model request customization](./docs/features/model-connections/README.md).
+- [x] **Context usage and automatic compaction**: Direct models update usage
+  from each successful provider call. Images and tool rounds use the same
+  accounting, with estimation only when the provider omits usage. The UI
+  distinguishes This Model Call from Post-Compaction Conversation Estimate,
+  and the compaction line is recalculated from current settings and the
+  selected model window rather than storing old configuration per
+  conversation. Before/after compaction markers use one estimation method,
+  while activity history retains provider usage for each call. Conversations
+  and multi-round tool Agents can compact repeatedly after a completed call
+  crosses the threshold, reserving budget first for fixed prompts, tool
+  definitions, and summaries. One response separately preserves compaction
+  markers for Agent tool context and conversation history, and summaries remain
+  reusable after app restart or when older messages leave the local history
+  window.
+- [x] **Persistent credential protection**: Main encrypts API keys with secure
+  system storage and never exposes them to the Renderer. A managed SSH accepted
+  Prompt places the current profile and key in Agent memory only, never in SSH
+  arguments, the remote environment, or disk; other paths keep credentials
+  inside Main. Credentials remain attached to their model connection when the
+  service URL changes or authentication is temporarily disabled, and are
+  removed only when the user explicitly clears them or deletes the connection.
+- [x] **Bounded failure diagnostics**: Desktop stores a fixed allowlist of
+  startup, Runtime, and remote-connection failure stages in the user-data
+  directory, rotating at four 256 KiB files. Each GoodBuddy Agent rotates
+  daemon, connection, recovery, and Runtime lifecycle diagnostics at three
+  64 KiB files in its private installation state and exposes them through the
+  fixed `diagnostics --installation-id` command. Both sides store only
+  allowlisted stages, stable error codes/types, and fixed short messages, never
+  Prompts, credentials, file contents, paths, environments, SSH arguments, or
+  raw provider responses. Diagnostic-write failure does not alter normal
+  operation.
+- [x] **OpenCode Runtime customization**: GoodBuddy-managed OpenCode can
+  discover native Agents, Tools, Commands, LSPs, Formatters, MCP, Skills,
+  Prompts, and Resources. Tools show read, file-edit, command, network, Agent
+  orchestration, and other types, source, and Ask/Execute availability while
+  hiding OpenCode's internal `invalid` tool and temporary GoodBuddy MCP tools.
+  Users can save a default Agent, override it per request, run Commands through
+  the native SDK, view context usage, and invoke native Compact with a total
+  timeout. Questions from concurrent external Server conversations are mapped
+  by public request ID so answers cannot cross conversations. External
+  OpenCode Servers report connection state only and do not claim native
+  catalog access. Arbitrary plugin installation, Session Share, automatic
+  Worktree, and OpenCode native-session persistence remain unavailable.
+- [x] **Continue Runtime customization**: Exposes native Rules, prompt
+  templates, and MCP from static configuration plus editable GoodBuddy Rules
+  and Prompt presets. Chat can select a preset per request and insert an
+  editable Prompt. The current Continue Host has no trustworthy static native
+  Tool discovery API and runs with an isolated `CONTINUE_GLOBAL_DIR`, so the UI
+  explicitly marks static Tool discovery unsupported and does not present
+  workspace or user Skills that the Host will not load as native capabilities.
+  GoodBuddy-assigned Skills still execute through per-request staging. The
+  temporary Continue Host does not reuse native session compaction; manual
+  compaction uses the GoodBuddy summary model and verifies persisted summary
+  coverage. Agent questions become unified question cards. Resources, Hooks,
+  background Jobs, and Continue native-session management remain deferred.
+- [x] **Native Runtime catalog semantics**: Native capabilities are displayed
+  across 11 tabs: Agents, Tools, Commands, Skills, MCP, Rules, Prompts,
+  Resources, LSP, Formatters, and Context. Catalog state is independent from
+  Runtime connectivity and distinguishes complete, partial, unavailable,
+  connection-only, and unsupported. DeepSeek Harness enumerates bounded
+  built-in/plugin Tools and Skills through the Host Registry, reports real
+  Ask/Execute boundaries, and excludes per-request GoodBuddy Skills and
+  Web/MCP proxies.
+- [ ] **Runtime supervision section** (planned): A fixed section in the
+  application-level assistant workbar for Task-level delegation, background
+  execution, Workflows/Hooks, long-running work, and native-session
+  supervision across OpenCode, Continue, and DeepSeek Harness. Users select
+  only Conversation or Task; Job/Run remains internal rather than becoming a
+  tree or independent object.
+- [ ] **Advanced Subagent supervision** (planned): Task-level aggregation in
+  the workbar's fixed Runtime section, configurable nesting, parallelism,
+  budgets, and lifecycle controls. Basic expert-mode inheritance and
+  single-level direct-model programming delegation are already available.
 
-- [x] **Skills 按需接入**：使用有界资源和受控 Runtime 边界。
-- [x] **MCP Tools**：直连模型可使用显式启用的 MCP Tools。
-- [x] **本地知识库**：支持文件、目录和网页导入、SQLite FTS5 检索及来源追溯。
-- [x] **知识图谱**：支持规则、模型和混合抽取，以及实体、关系、别名和证据维护。
-- [x] **向量模型配置与检索**：可配置兼容 Embeddings 接口并用于语义检索。
-- [x] **向量诊断与索引任务**：提供真实向量生成诊断、按文档重建进度、取消、失败状态与重启后结果恢复；每篇成功文档立即可用于检索。
-- [x] **魔法笔记 / Magic Notes**：提供本地优先的笔记与待办工作台、范围管理、编辑、筛选和受控 AI 评论；创建、保存和评论结果使用统一应用通知。
-- [ ] **MCP Server Control Plane**（规划中）：扩展 MCP Agent Runtime Broker，统一生命周期、健康检查、重连、Schema 缓存、按项目或任务隔离、审批和审计，并受控接入 OpenCode、Continue。
+### Skills, MCP, and knowledge
 
-### 工作管理、长期协作与工作流
+- [x] **On-demand Skills**: Assignable to direct models, OpenCode, Continue,
+  and DeepSeek Harness with bounded resources and controlled Runtime boundaries.
+- [x] **Local tool-execution environment source path**: Under Capabilities and
+  Tools / Tool Environment, users can select GoodBuddy-managed Node.js,
+  on-demand managed Python, or a genuinely validated custom interpreter for
+  local Skills and stdio MCP. The page provides an independent Native/OSS
+  source choice, diagnostics, installation progress, cancellation, and
+  removal. New local Runtimes and stdio MCP processes receive immutable PATH
+  snapshots without changing ordinary terminals, the system environment, or
+  remote Hosts. Managed Node and native-source Python have passed real
+  installation validation on Windows x64. Managed Python archive validation
+  follows the target filesystem: Linux preserves valid case-distinct paths,
+  while every target still rejects exact duplicates and unsafe entries.
+- [ ] **Local tool-execution environment release acceptance**: All six
+  platform/architecture OSS mirror objects have passed public byte, size, and
+  SHA-256 verification. Managed Python remains an on-demand download and does
+  not add license files to the Desktop package. Each standard package job uses
+  a native target-architecture Runner and performs a real managed-Python
+  install, SSL, pip, and venv probe before packaging. The immutable `v0.12.0`
+  attempt passed Windows and macOS but exposed Linux TAR case handling before
+  publication. The immutable `v0.12.1` attempt was cancelled before native
+  packaging while synchronizing the Agent release. Published `v0.12.2`
+  subsequently passed all six native package jobs and their managed-Python
+  install probes. Real Skill/MCP execution, custom interpreter execution, and
+  coordination with affected running processes remain
+  acceptance work. Six-platform release acceptance must not be claimed before
+  the applicable checks pass.
+- [x] **On-demand built-in MCP**: Knowledge, Magic Notes, GoodBuddy
+  configuration, and built-in browser MCP can be enabled independently and assigned to direct
+  models, GoodBuddy-managed OpenCode, and Continue. Settings explicitly marks
+  DeepSeek Harness unsupported. Built-in MCP uses short-lived local authority
+  for the current request, and user configuration cannot loosen Ask/Execute
+  read/write boundaries.
+- [x] **MCP Tools**: Explicitly enabled custom MCP can be assigned to direct
+  models, GoodBuddy-managed OpenCode, Continue Agent Execute, and DeepSeek
+  Harness, and loads only in Execute. Agent child processes receive only
+  per-request local-loopback authority; MCP addresses, commands, and
+  credentials remain in Main. Dynamic tools pass through discovery and the
+  existing activity and permission boundaries; healthy direct-model
+  and Harness calls reuse the discovered request catalog instead of
+  rediscovering it before every call.
+- [x] **MCP Prompts and Resource metadata**: MCP testing discovers bounded
+  Prompt, parameter, and Resource metadata only when the Server declares the
+  corresponding capability and does not read Resource content. Supported
+  Prompts can be inserted into the chat draft for further editing. OpenCode can
+  report an experimental Resource catalog; the current Continue version
+  explicitly does not support Resources.
+- [x] **Local knowledge bases**: Supports file, directory, and web imports,
+  SQLite FTS5 retrieval, and source tracing. Knowledge selection persists per
+  conversation and starts empty for new conversations. Advanced creation and
+  retrieval parameters are collapsed by default. Documents distinguish ready,
+  processing, and failed states, with source opening, retry, and confirmation
+  before source removal.
+- [ ] **External knowledge-base connections** (planned): Manage Dify, FastGPT,
+  and RAGFlow instances from the existing Knowledge page, then discover and
+  bind remote knowledge bases with provider-specific retrieval settings and
+  citations. External systems provide retrieval only: GoodBuddy does not use
+  their App, Chat, Workflow, or Agent APIs, and does not bulk-sync, locally
+  index, or modify remote content. Bounded cited snippets are retained locally
+  with their conversations. See the
+  [external knowledge-base PRD](./docs/features/knowledge-base/external-knowledge-prd.md).
+- [x] **Knowledge graph**: Supports rule-based, model-based, and hybrid
+  extraction plus entity, relationship, alias, and evidence maintenance.
+- [x] **Embedding configuration and retrieval**: Configures compatible
+  Embeddings endpoints and uses them for semantic retrieval.
+- [x] **Embedding diagnostics and indexing jobs**: Provides real embedding
+  diagnostics, per-document rebuild progress, cancellation, failure state, and
+  result recovery after restart. Each successful document becomes immediately
+  searchable.
+- [x] **Hybrid retrieval workbench**: Diagnoses full-text, Chinese phrase,
+  vector, and graph channels with configurable Top K, thresholds, weights,
+  local or learned reranking, and context budgets.
+- [x] **Chunking, maintenance, and evaluation**: Supports fixed, structured,
+  and parent-child chunking, chunk maintenance, cancellable rebuilds, and
+  bilingual retrieval evaluation.
+- [x] **Controlled knowledge ontology**: Each knowledge base can define
+  entities, relationships, aliases, and endpoint constraints while retaining
+  evidence offsets, confidence, and extraction source, with explicit guidance
+  to rebuild the graph.
+- [x] **Required retrieval and cited context**: Conversations can retrieve on
+  demand or before every response, show zero-result, degraded, failed, and
+  cancelled states, and expose cited context or safely open its source.
+- [x] **Magic Notes**: A local-first notes and todo workbench with scope
+  management, editing, filtering, and controlled AI comments. The todo view
+  displays the source entry inside the selected item's details, without
+  showing the previous item's source after a selection change. Failed reads
+  use application notifications, and missing sources have an explicit fallback. The left
+  navigation can show the incomplete-todo count, and create, save, and comment
+  results use application-wide notifications.
+- [ ] **MCP Server Control Plane** (planned): Unified MCP lifecycle, health
+  checks, reconnection, schema cache, isolation, approval, and audit.
+- [ ] **Traceable note excerpts and AI editing** (planned): Collects sourced
+  excerpts from conversations, knowledge, and the web and provides
+  confirmation-based summarization, rewriting, and organization.
 
-- [x] **任务、活动与成果**：集中管理任务状态、审计活动和成果文件；活动按会话分组并默认收起，避免长历史占满页面。
-- [x] **记忆与智能心跳**：提供周期回顾、建议记忆、洞察、后续任务和可审计运行轨迹。
-- [ ] **批量运行与对比实验室**（规划中）：对模型、Prompt、角色和工作流配置执行批量对比，汇总质量、耗时、Token、费用、失败率和成果差异。
-- [ ] **时态记忆与事实冲突检测**（规划中）：为记忆和知识图谱增加有效期、当前事实、过期与矛盾检测、事实核验及证据回溯。
-- [ ] **可视化受控工作流**（规划中）：提供版本化 DAG、条件分支、审批检查点、取消、恢复和成果节点；所有执行节点继续经过 Main Runtime 边界。
-- [ ] **统一运行追踪与回放**（规划中）：关联任务、Subagent、模型调用、知识命中、工具审批、活动和成果，提供节点级耗时、失败定位、重试和脱敏导出。
+### Work management, long-term collaboration, and workflows
 
-### 浏览器、通信、语音与应用维护
+- [x] **Tasks, activity, and artifacts**: Centrally manages task state, audit
+  activity, and independent artifact files. Ordinary chat responses remain
+  only in the conversation and are no longer copied into Artifacts; existing
+  duplicate chat Markdown is hidden from the artifact list but not physically
+  deleted. Run history is stored in Main SQLite without the previous 500-item,
+  4,000-character, or 2 MB Renderer limits; the page renders it in batches,
+  without a persistent legacy-cache truncation warning; previously lost
+  history is not restored. Token usage is grouped by Runtime and
+  model and normalizes the different OpenAI-compatible and Anthropic Messages
+  cache-reporting semantics when showing cache hit rate. Activity is grouped
+  by conversation and collapsed by default so long histories do not fill the
+  page.
+- [x] **Task and custom-task experience**: Each product-level Task belongs to
+  one Conversation, while one Conversation can contain multiple Tasks. The
+  left conversation list exposes Task children through a leading expand
+  button; children share status dots, the parent does not repeat task badges,
+  and the UI stops at Task rather than exposing Job/Run levels. A new custom
+  Task can use the current or a new Conversation, defaults to Execute, and
+  preserves Runtime, tool, and approval boundaries. Repeated triggers reuse the
+  same Task; text returns to the Conversation, while independent files and
+  images remain artifacts. Ordinary messages and due Scheduled Tasks share a
+  persistent Conversation queue that runs one item at a time. Users can keep
+  sending while a response is active; queued items continue in order and can
+  be removed or inserted immediately by interrupting the current item. Task
+  Center remains the complete index rather than creating a separate Automation
+  Center. Current schedules support one-time, daily, and weekly triggers;
+  advanced time zones, Cron, event triggers, and retry governance remain
+  incremental PRD work. Scheduled messages use the conversation's current
+  history, Runtime, work mode, and saved knowledge retrieval settings; task
+  details show the actual mode used, and an active occurrence blocks duplicate
+  Run Now actions. See the
+  [Task Center PRD](./docs/features/task-and-job/task-center-prd.md) and
+  [Scheduled Task PRD](./docs/features/task-and-job/scheduled-task-prd.md).
+- [x] **Memory and Smart Heartbeat**: Provides periodic review, suggested
+  memories, insights, follow-up tasks, and auditable run history.
+- [x] **Improved Smart Heartbeat entry and scope**: Smart Heartbeat / Heartbeat
+  Plans is the sole authoritative full-configuration entry. Plans can be
+  created and edited for Global or one or more selected Projects. Legacy
+  single-project settings migrate without loss, and project-level memory and
+  action output must explicitly target a Project in scope. Task Center and
+  Settings no longer duplicate the form. Partition-aware review, candidate
+  generation, and recall triggers remain to be designed. See the
+  [Smart Heartbeat PRD](./docs/features/smart-heartbeat/prd.md).
+- [ ] **General supervision** (planned): Uses a fixed supervision section to
+  observe user-selected conversations, Tasks, automations, or experiments and
+  provide evidence-backed comments and requests for human intervention,
+  without automatically speaking, approving tools, or switching to Execute.
+  See the
+  [Conversation Supervision PRD](./docs/features/conversation-supervision/prd.md).
+- [ ] **Batch runs and comparison lab** (planned): Compares model, Prompt,
+  role, and workflow configurations in batches and summarizes quality,
+  duration, tokens, cost, failure rate, and artifact differences.
+- [ ] **Temporal memory and fact-conflict detection** (planned): Adds validity
+  periods, current/expired/conflicting fact detection, fact checking, and
+  evidence tracing to memory and the knowledge graph.
+- [ ] **Visual controlled workflows** (planned): Versioned DAGs, conditional
+  branches, approvals, cancellation, and recovery, with execution still
+  passing through Main Runtime boundaries.
+- [ ] **Unified Run Graph and replay** (planned): Connects Tasks, Subagents,
+  models, knowledge, tool approvals, usage, and artifacts for failure
+  diagnosis, retry, and redacted export.
 
-- [x] **浏览器和桌面受控工具**：保留范围、取消、超时、输出边界和执行记录。
-- [x] **远程消息通道项目**：微信 ClawBot、企业微信和钉钉分别拥有系统管理的项目、独立远程会话、工作目录、处理后端、默认 Ask/Execute 模式及任务活动归属。
-- [x] **微信 ClawBot 扫码与媒体**：通过独立 Sidecar 完成本机扫码、验证码、加密凭据和文字收发；支持个人微信私聊图片与文件，单条消息最多 4 个附件、解密后合计不超过 12MB。
-- [x] **微信安全回传**：支持返回当前任务生成的图片，或在用户明确要求时将本次最终文本生成为 Markdown 附件；不自动读取或发送已有工作区文件。
-- [x] **企业微信与钉钉连接**：支持 Main-only 加密设置、环境变量只读覆盖、连接测试、动态启停、发送者范围和状态诊断。
-- [x] **可选本地语音模型管理**：应用不内置模型权重；提供校验下载、进度与取消、来源链接、本地目录导入、切换和删除。
-- [x] **本地录音与离线转写**：采集麦克风音频并使用已选择的本地模型离线转写，支持停止、取消、状态反馈和资源释放。
-- [x] **版本检查**：仅检查固定官方 Release 和当前平台清单，不自动下载或安装。
-- [x] **内网兼容模式**：默认开启；允许应用内 HTTP 与无效、自签名或过期的 HTTPS 证书，关闭后恢复严格地址和证书校验。
+### Browser, communication, voice, and application maintenance
 
-### 开放接口、团队协作与远程执行
+- [x] **Shared built-in browser for runtimes**: Uses GoodBuddy's isolated
+  Chromium and never controls a browser installed by the user. A separate
+  master switch decides whether assigned runtimes receive the capability in
+  Execute, with no per-use prompt after enablement. Turning Agent access off
+  does not disable manual browser workbar actions. The Browser workbar and
+  Agent share the same Conversation-owned session and serialized operation
+  path, with Back, Refresh/Stop Loading, address entry, Go, Interaction, and
+  Close actions. Stop Loading does not close the session, and user navigation
+  changes the page the Agent sees next.
+  Multiple tabs in one conversation share login state while keeping separate
+  pages and navigation. Each model request retains its starting tab binding;
+  unused request reservations do not create browser resources. Released tabs
+  can be reopened, explicit screenshots remain available, and ordinary
+  operations no longer trigger unused automatic screenshot capture.
+- [x] **Client-computer control tools**: Managed separately from the built-in
+  browser with scope, cancellation, timeout, output, and activity boundaries.
+- [x] **Remote messaging-channel projects**: WeChat ClawBot, WeCom, and
+  DingTalk each have a system-managed project, independent remote
+  conversations, working directory, processing backend, default Ask/Execute
+  mode, and task/activity ownership. Each channel controls complete-response
+  length and segmentation according to platform capabilities rather than
+  relying on a shared service truncation.
+- [x] **WeChat ClawBot QR login and media**: A separate Sidecar handles local
+  QR scanning, verification codes, encrypted credentials, and text messaging.
+  Personal WeChat chats support images and files, with at most four
+  attachments and 12 MB total after decryption per message.
+- [x] **Safe WeChat responses**: Can return images generated by the current
+  task, or generate a Markdown attachment from the current final text after an
+  explicit user request. It never automatically reads or sends existing
+  workspace files.
+- [x] **WeCom and DingTalk connections**: Main-only encrypted settings,
+  read-only environment-variable overrides, connection tests, dynamic
+  enable/disable, sender scope, and status diagnostics.
+- [x] **Managed local-model download source**: Platform Features / General
+  selects ModelScope (default) or Hugging Face globally for future speech-input
+  and OCR model downloads. A source without a complete verified file is
+  explicitly unavailable and never silently falls back or combines files.
+- [x] **Optional local speech-model management**: Model weights are not bundled.
+  Provides verified downloads, progress and cancellation, source links, ZIP or
+  local-directory import, switching, and removal.
+- [x] **Local recording and offline transcription**: Captures microphone audio
+  and transcribes with the selected local model, with stop, cancel, state
+  feedback, and resource cleanup.
+- [x] **Version checks and mirror source**: About and Updates selects GitHub
+  (default) or the mirror. Manual checks, startup checks, and the download page
+  use the same choice and read only fixed trusted release indexes; GoodBuddy
+  does not automatically download or install updates.
+- [x] **In-app feedback**: About and Updates can submit problems, suggestions,
+  or experience feedback with an optional email and one screenshot.
+  Diagnostics are not uploaded by default; users can explicitly attach a
+  bounded recent Desktop diagnostic summary. Failed submission preserves the
+  draft, diagnostic choice, and request ID. Conversations, Prompts,
+  credentials, file contents, paths, raw provider responses, and remote Agent
+  logs are never attached.
+- [x] **Private-network compatibility**: Permits in-app HTTP plus invalid,
+  self-signed, or expired HTTPS certificates. Fixed platform services such as
+  feedback and WeChat credential or media endpoints retain strict certificate
+  validation.
 
-- [x] **远程任务委派**：仅在用户显式配置端点和令牌后启用，按全局内网兼容模式使用 HTTP(S)，结果进入持久化发件箱。
-- [ ] **Headless Runtime API 与受控分享**（规划中）：提供本机优先的任务提交、流式事件、状态和成果 API，并使用带范围、有效期、限流和撤销能力的访问令牌。
-- [ ] **GoodBuddy Team Hub**（规划中）：以可选独立服务提供组织、成员、RBAC、项目共享、远程 Agent 注册、策略下发和租户级审计。
-- [ ] **多云远程沙盒 Agent**（规划中）：管理阿里云 ECS、腾讯云 CVM、AWS EC2，并通过 SSH + Agent 提供专用自主沙盒。
+### Open source, builds, and releases
 
-## 重大功能规划
+- Current source candidates are Desktop `0.12.12` and Agent `0.11.23`, with
+  OpenCode pinned to `1.18.29`. Publication status follows the independent
+  Desktop and Agent release channels.
+- [x] **0BSD open-source license**: Original code can be freely used, copied,
+  modified, distributed, and commercialized. Third-party components and
+  resources retain their own licenses.
+- [x] **Reproducible dependency installation and source builds**: Uses locked
+  dependencies, Node.js 24, and unified test, type-check, lint, and production
+  build commands.
+- [x] **Six-target native release matrix**: Native runners build Windows,
+  macOS, and Linux `x64` and `arm64` targets with release manifests and SHA-256
+  hashes. Windows provides NSIS and portable ZIP, macOS DMG only, and Linux
+  AppImage, DEB, and RPM, for 12 installers and 20 published assets.
+- [x] **Desktop Runtime package verification**: Offline OpenCode dependencies
+  are copied without electron-builder's root node_modules exclusion; DSH
+  session projection is bundled into the unpacked Host. Final package checks
+  compare the offline dependency tree and reject external DeepSeek imports.
+  Windows x64 CI additionally imports the packaged OpenCode plugin and checks
+  the real DSH UtilityProcess handshake before publishing.
+- [x] **DMG-only update manifests**: Current Desktop and website readers accept
+  DMG-only and historical DMG/ZIP manifests. Older macOS GitHub readers and all
+  older mirror readers require a manual upgrade from the download page.
 
-### Agent 框架与协作能力
+### Open interfaces, team collaboration, and remote execution
 
-参考 MesaLogo 中已经存在或正在验证的 Action Space、受控工作流、Subagent、MCP 管理、批量实验和运行观测思路，GoodBuddy 计划在现有本地优先架构上逐步增加以下能力。这里列出的项目均为 GoodBuddy 自身规划，不表示 MesaLogo 的原型或路线图已在 GoodBuddy 中提供。
+- [x] **Remote task delegation**: Enabled only after the user explicitly
+  configures an endpoint and token, uses HTTP(S) according to the global
+  private-network compatibility setting, and writes results to a persistent
+  outbox.
+- [ ] **Headless Runtime API** (planned): A local-first Task, event, state, and
+  artifact API with scoped, expiring, rate-limited, and revocable tokens.
+- [ ] **GoodBuddy Team Hub** (planned): An optional service for organizations,
+  RBAC, project sharing, remote Agents, policy distribution, and tenant audit.
+- [ ] **SSH Host and remote execution-space release acceptance**: Host CRUD,
+  Host Key, encrypted credentials, Project UI, Workspace, OpenCode ACP v5,
+  Agent-owned Prompt/gateway/transcript, read-only Ask, full-account Execute,
+  cancellation, exact detached-Agent reconnection, and release-only
+  dual-architecture resource verification are wired. Current Linux x64 source
+  has passed a real-model and tool matrix covering detach, process exit, relay
+  loss, concurrency, cancellation, provider failures, Agent restart, and
+  Desktop SQLite recovery. A current-source, test-signed Agent `0.11.17`
+  package on Linux x64 additionally passed two concurrent Ask reads, an
+  Execute write/read, and six real managed-gateway model requests with the
+  configured custom headers and body fields. No provider request was replayed,
+  and scanning the isolated Agent state found no API key or custom request
+  value. The public signing-key registry is provisioned. Direct control-plane
+  source does not wait for a new installer-bearing package, but the current
+  formally signed Linux x64/arm64 artifact matrix still requires public
+  verification, along with GitHub/Beijing mirror, dual-architecture, and
+  offline GoodBuddy transfer release acceptance. Until these gates pass, this
+  path must not be described as published or as having passed formal release
+  acceptance.
+- [ ] **Multi-cloud remote sandbox Agents** (planned): Manages dedicated Linux
+  sandboxes through cloud-provider APIs and SSH Agents. Credentials remain in
+  Main, and high-risk control-plane operations receive separate confirmation.
 
-- [ ] **项目 Agent Space 与策略包**：不新增与 Project 重复的一级概念，而是在现有 Project 中统一角色、知识集合、Skills/MCP、默认模型、变量、工作模式、审批策略、预算和超时，并支持模板化复用。
-- [ ] **统一 Run Graph**：先统一父子任务、节点、模型调用、知识命中、工具审批、用量、成果和取消事件，作为工作流、可执行 Subagent、批量实验和回放的共同基础。
-- [ ] **MCP Server Control Plane**：由 Main 进程统一管理 `stdio`、HTTP 和 SSE Server，执行连接验证、健康检查、重连、Schema 缓存、环境变量白名单、资源配额、项目或任务隔离以及逐次审批和审计。
-- [ ] **可视化受控工作流**：首版只支持开始、Agent/Subagent、知识、声明式条件、审批、成果和结束节点；流程需要版本化、校验、取消和恢复。任意网络请求或执行节点不得绕过现有 Runtime 与审批边界。
-- [ ] **可执行 Subagent**：保留现有专家默认只读语义，只在显式 Execute 委派中允许受控工具，限制深度、并行数、Token、时间、成果范围和父子权限继承。
-- [ ] **批量运行与对比实验室**：对模型、Prompt、角色和工作流版本进行参数扫描与 A/B 对比，展示质量评分、耗时、Token、费用、失败率和成果差异。
-- [ ] **时态记忆与事实冲突检测**：在现有知识图谱和证据链上增加事实有效期、当前状态、过期与矛盾检测、核验流程及来源回溯。
-- [ ] **Headless Runtime API**：作为可选、本机默认仅监听 loopback 的服务，提供任务提交、流式事件、状态和成果下载；访问令牌必须具有 scope、有效期、速率限制、项目限制和撤销能力。
-- [ ] **GoodBuddy Team Hub**：作为独立可选服务提供组织、成员、RBAC、项目共享、远程 Agent 注册、策略下发和租户级审计，不把 Electron Renderer 或云端服务改造成用户凭据持有者。
+## Roadmap Principles
 
-安全边界保持不变：Ask/Plan 必须在 Runtime 边界只读；Execute、MCP、网络和 Subagent 工具均受 Main 进程能力边界、权限策略、取消和审计约束。普通交互按对应策略审批；受信发送者发起的远程 Execute 不逐次弹窗确认，但不得绕过项目目录、Runtime、沙箱、能力开关或直连模型工具安全策略。不得照搬进程内脚本执行、任意 URL 请求、仅以 `created_by` 模拟多租户或共享无隔离 MCP 会话等做法。
-
-### 知识工作空间与魔法笔记
-
-- [x] **魔法笔记 / Magic Notes 基础工作台**：已提供本地优先的笔记与待办页签、范围管理、编辑、筛选、删除和受控 AI 评论。
-- [ ] **可追溯摘录扩展**（规划中）：支持将用户选中的对话片段、知识条目、文档摘录和网页摘录收集为可编辑笔记，并持续保留来源、位置和引用关系。
-- [ ] **扩展受控 AI 笔记操作**（规划中）：在现有 AI 评论之外提供总结、改写、续写、整理和关联知识等显式操作；操作结果先进入笔记或待确认变更，不静默回写或修改来源知识。
-
-### 多云远程沙盒 Agent
-
-GoodBuddy 将支持把专用云主机作为模型可自主使用的远程沙盒。首批计划接入：
-
-- 阿里云 ECS
-- 腾讯云 CVM
-- AWS EC2
-- 其他可通过 SSH 管理的 Linux 主机
-
-计划包含以下能力：
-
-- [ ] **云主机控制面**：通过云厂商官方 API 发现、创建、启动、停止和删除实例，创建前展示地域、规格、镜像、网络和费用相关配置。
-- [ ] **SSH + GoodBuddy Agent**：校验 SSH 主机指纹后，以专用非 root 账户安装、升级和配对 Agent，不要求模型接触 SSH 私钥。
-- [ ] **沙盒内自主执行**：用户可将明确指定的专用实例设为自主沙盒。模型在该沙盒的工作目录内连续执行命令、修改文件和运行任务，不逐条请求审批。
-- [ ] **控制面与执行面隔离**：云 API 密钥、临时凭据和 SSH 私钥只保存在 Main 进程的系统加密存储中，不下发给 Renderer、模型或远程任务。模型的自主权限不包含云账户管理权限。
-- [ ] **高风险操作保护**：删除实例、修改安全组或网络、扩缩容和其他可能产生额外费用或数据损失的控制面操作仍需单独确认。
-- [ ] **可观测与可恢复**：实时回传心跳、日志、进度、退出状态和有界成果文件，支持取消、超时、断线重连、失败诊断和完整活动审计。
-- [ ] **跨云一致体验**：使用统一的实例状态、Agent 能力和任务协议；阿里云、腾讯云、AWS 的差异由独立 Provider Adapter 隔离。
+Planned workflows, Subagents, MCP, remote APIs, and sandbox capabilities must
+not bypass existing Main Runtime, Ask/Execute, permission, cancellation,
+timeout, or audit boundaries.

FEATURES.zh-CN.md

@@ -0,0 +1,133 @@
+# GoodBuddy 功能矩阵与路线图
+
+[English](./FEATURES.md) | **简体中文**
+
+本文记录 GoodBuddy 的已提供能力和路线图。未完成项目不代表已包含在当前版本中。
+
+## 状态说明
+
+- [x] 已提供
+- [ ] 开发中或规划中，具体以条目标注为准
+
+## 功能总表
+
+### 桌面基础、工作空间与上下文
+
+- [x] **跨平台桌面应用**：支持 Windows、macOS、Linux，以及 `x64`、`arm64` 发布目标。
+- [x] **信创软硬件覆盖**：正式 Linux 安装包覆盖国产 `x64` 与 `arm64` 架构，可用于统信 UOS、银河麒麟及海光、兆芯、鲲鹏、飞腾等兼容环境。龙芯 LoongArch 另行提供 `loong64` 实验预览版，不属于正式发布矩阵，也未纳入自动更新；`0.12.12` 不构建该预览。这里的覆盖范围不等同于厂商或整机兼容认证，具体状态与限制见[龙芯预览版构建说明](./docs/development/loongarch-preview-build.md)。
+- [x] **可配置全局快捷唤起**：在“平台功能 / 通用设置”中启停或录制 Electron accelerator；默认保留 `CommandOrControl+Shift+Space`，冲突或保存失败时继续使用上一组已注册快捷键，并显示可处理的状态。
+- [x] **Projects、独立对话与会话分支**：按项目隔离上下文，管理会话、附件和 Git 工作区变更；本地会话可在稳定状态下复制当前聊天内容到独立分支，分支持续显示来源徽标且不复制 Task、队列或成果归属；项目选择器区分本地、托管 SSH 与远程消息通道项目，托管 SSH 项目按 Host 分组并在 Host 标题显示真实 Agent 连接状态，项目行只保留远端路径。
+- [x] **文件、截图、窗口、剪贴板上下文**：用户明确选择后才加入模型上下文。
+- [x] **工作区单文件差异**：变更文件可分别查看已暂存和未暂存差异，覆盖删除、重命名和未跟踪文件；刷新会重读当前差异、当前浏览目录和已展开目录，超过 50 项变更可继续加载。
+- [x] **工作区文件与 Git 管理**：支持文件和目录的新建、重命名、移动、删除、属性查看，以及本地/远程分支搜索与切换、新建分支、显式 Fetch、提交历史和单文件提交差异。工具按文件/Git 视图分组，分支搜索使用统一紧凑表单，子目录保留文字导航而根目录不再显示孤立图标。提交历史贴底，首次展开占 Git 内容区一半，支持调整比例、独立滚动和统一刷新；切换项目自动检测 Git，不沿用其他项目状态。移动限于工作区内，删除须确认，分支冲突不自动 stash 或丢弃改动；托管 SSH 操作需要 Agent `0.11.23`。
+- [x] **富文本回答**：支持 GitHub Flavored Markdown、LaTeX 数学公式、受控 Mermaid 图表和会话内 HTML 静态预览。Agent 完成回复后，完整 HTML 与 HTML 代码块可在原位置预览，并通过图标按钮查看源码或打开全屏预览；该能力默认开启，可在“平台功能 / 通用设置”关闭，预览不执行脚本、联网、表单提交或窗口操作。
+- [x] **AI 回复与完整会话复制**：已完成的 AI 回复可从消息底部复制不含推理、工具日志和引用元数据的 Markdown 原文；完整会话复制复用同一条经过 Preload/Main 校验的剪贴板路径。
+- [x] **助手工作栏、多终端与可调布局**：右侧工作栏使用持久“+”能力目录和应用 Tab；任务中心与工作区为不可关闭的单实例，浏览器可打开多个独立实例。任务中心可切换当前项目、全局任务和全部项目，范围随布局保存。用户可为当前本机或托管 SSH 项目打开多个独立终端，获得有界输出、调整尺寸、结束与显式重连。关闭终端 Tab 会结束 Shell，应用重启只恢复已结束的 Tab 描述，不自动重启 Shell。主侧栏和魔法笔记列表支持鼠标与键盘调宽，魔法笔记列表可隐藏并记住布局，窄宽度下自动堆叠。
+- [ ] **项目 Agent Space**（规划中）：在 Project 中统一角色、知识、Skills/MCP、模型、审批策略、预算和超时，并支持模板复用。
+- [ ] **应用导航与系统工具快捷入口**（仅设计）：规划固定系统入口、内置应用显隐和打开现有工作栏的底部工具按钮；尚未实现新界面。详见[设计文档](./docs/features/application-tool-navigation/README.md)。
+- [ ] **通用助手工作栏与执行空间后续能力**（规划中）：在现有工作栏和多终端基础上继续加入监督、统一 Runtime、受管进程、静态安全 HTML 预览、可固定目标的工作区/浏览器/成果实例、底部停靠与独立窗口。Task Center 保持 Task 的单例索引，附件与知识库继续由会话输入区管理，未来的记忆与历史执行上下文归入关联 Task。详见 [Feature PRD](./docs/features/assistant-workbar/prd.md)。
+- [ ] **ShareServer Office 协同编辑**（设计中）：通过可选 ShareServer 集成 ONLYOFFICE Docs，在助手工作栏中以文件名打开多个文档 Tab，支持 DOCX、XLSX、PPTX 的人工编辑、保存、撤销、源文件冲突保护和后续 AI 选区修改。Office 正文会由所选 ShareServer 和编辑引擎处理；Desktop 不内置或启动 Document Server，未配置服务时不宣称离线编辑。详见[设计文档](./docs/features/office-document-editing/README.md)。
+
+### Agent Runtime 与模型连接
+
+- [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行、图像生成，以及通过支持 OpenAI 兼容图片编辑接口的服务商进行参考图编辑。连续请求自动复用最近一次成功生成的图片和文字历史，已保存会话重开后仍可继续修改，本轮显式附图优先；上游明确不支持编辑时继续按文字生成，仅在回复底部提示未使用参考图。编辑使用 multipart 上传图片，结果仍只接受经过校验的内联图片，不下载服务商返回的图片 URL。详见[图片生成与连续修改](./docs/features/image-generation/README.md)。
+- [x] **直连模型编程 Agent**：本机直连文本模型可在 Execute 模式运行平台 Shell，并可按父请求模式、模型、工作区和能力范围委派一层编程 Subagent；OpenCode、Continue、DeepSeek Harness 和托管 SSH 不重复注入这两个工具。Windows 本机命令与真实模型“修改、测试、修复、复核”闭环已通过，macOS 与 Linux 真机命令仍待对应平台验收。
+- [x] **高效直连模型工作区工具**：直连模型使用随包 ripgrep 紧凑地发现文件和搜索内容，按行分页读取大型 UTF-8 文件，并在 Execute 中应用多文件补丁。Ask 可以搜索和读取，但不能应用补丁或运行命令；用户无需另行安装 ripgrep。
+- [x] **长上下文与工具输出分页**：历史消息、长回复和文档解析文本不再采用旧的固定截断限制。直连模型可分页续读已保存的命令和 Subagent 输出；所选模型的上下文窗口及传输边界仍然有效。
+- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、启动与控制请求时限、有界流式输出和活动记录；共享进程回收逻辑保留 Windows 完整进程树终止，并对采用独立进程组的 POSIX 子进程执行组回收。聊天状态检查使用一次性探测 Runtime 并在返回后立即回收，不进入按模型与项目隔离的执行 Runtime 缓存；本机 GoodBuddy 管理的 OpenCode 在该被动检查中只确认所选路径和模型凭据，不启动用后即毁的 Server，设置中的显式连接测试和原生能力清单仍执行完整启动及健康检查，原生能力清单随后与首次实际请求复用同一个执行 Runtime，不再重复冷启动；执行 Runtime 仍按项目复用，但 OpenCode 配置依赖和按内容摘要生成的 Skill 快照在所有本机项目间全局复用，会话数据、工具输出及请求级 MCP 状态继续隔离。本机 GoodBuddy 管理的 OpenCode 只对同一会话内的请求保持顺序，不同会话即使属于同一项目也可并行，不同项目同样可并行；请求级动态 MCP 通过默认通配禁用和当前请求精确放行保持隔离。托管的本机和远端 OpenCode 跳过界面未使用的自动 Git 快照，避免同步差异计算拖住会话，文件工具、子代理与工作区 Git 差异保留；Continue 持续排空不用展示的宿主 stdout，防止控制台输出填满管道。这些调整随新启动的 Runtime 生效，不改写外部 OpenCode Server 配置。OpenCode 与 Continue 不再按固定工具调用数或活动数中止单次运行，已观察到的工具与 Subagent 活动全部保留在本地会话，不再在原生任务继续执行时丢弃后续详情。交互提问只由前台对话回答，定时任务、远程通道和委派等后台执行遇到提问时会立即失败并提示改为前台运行，避免无限等待。本机 OpenCode 启动时直接使用已选择的绝对路径，不预先检查文件或运行 `--version`，路径失效时由实际启动返回错误；托管 Linux ARM Host 激活 Runtime 时复用准备阶段已验证的 registry 和 manifest，不重新哈希或检查完整 OpenCode 二进制。
+- [x] **托管 SSH OpenCode 闭环（技术预览）**：该能力由“设置 > 平台功能”中的独立“远程项目（技术预览）”页签控制并默认关闭；关闭时不影响本地项目、普通桌面功能或桌面发布。支持 Linux x64、Linux arm64 和 macOS arm64 Host，不支持 Intel Mac；通过 SSH 按需启动 detached Agent，不要求开机服务。Ask 在 Runtime 工具边界保持只读，Execute 使用所选 SSH 账号的完整权限。Agent 持有 Prompt、模型和工具轮次、Runtime 进程及语义 transcript，Desktop 断开后重新 Attach 原操作而不重发 Prompt；模型凭据仅在当前操作内存中使用，不写入 Renderer、SSH 参数、环境或磁盘。设置页按平台和架构显示包状态，用户显式下载、更新或导入/导出包含 Agent、固定 Node 和 OpenCode 的签名 `.gbagent`；三个目标共用一个签名 catalog，继续校验签名和 SHA-256。首次发布混合 catalog 前需先升级 Desktop，旧版 Linux-only 目录读取器无法解析包含 Darwin 的目录。macOS 原生安装、生命周期、Attach、真实 Ask/Execute 和独立进程组工具取消已在真实 Host 验证；这不等于新版本已经发布。详细运行边界和 Linux 历史回归证据见[远程主机技术设计](docs/features/remote-host/technical-design.md)，正式发布状态以 Agent 与 Desktop 的独立发布渠道为准。
+- [x] **SSH Host 手动环境准备源码链路**：Host Key、认证和系统探针成功后先保存 Host，并只读探测共享 Agent/Runtime；保存 Host、打开项目都不自动安装。Host 卡片只有一个按版本事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮，次级 SegmentedControl 选择默认且不持久化的“自动”、Host 下载或 GoodBuddy 传输；“版本匹配”badge 不等同环境健康。自动模式只在 operation/prepare 前探测并择一，显式选择保持有效，任何 prepare、commit 或 adoption 失败都不跨 acquisition 自动 fallback。两种方式把同一签名 compound `.gbagent` 交付到固定 staging 后，共用 control-plane prepare、commit、Agent activate/health、Runtime activate、finalize 与显式 cleanup。GoodBuddy 路径可在同一次操作下载并验证缺失候选、缓存并取得 lease，再有界流式 SFTP 上传一个归档和其中已验证的 bootstrap Node，不把约 294 MiB 整包读入 Main `Buffer`；Host 在解包时完成一次完整 payload 校验。未完成操作只记录暂存 cleanup 所需的 operation ID；下次更新尽力清理旧暂存后重新 prepare，不保存远端 metadata 副本，也不让 cleanup 失败阻塞新更新或回滚健康环境。已有项目在实际使用 Workspace/Runtime 时按需解析 Host current identity 并执行固定 `attach-or-bootstrap`，注册后的 health、capabilities 和 prompt 启动不扫描完整 payload。详见 [设计说明](./docs/features/remote-host/environment-provisioning-technical-design.md)。
+- [ ] **SSH Host 环境准备真实 Host 验收**：当前源码已在隔离 Linux x64 环境通过包安装、Ask/Execute、原生子代理工作区外写入、重连及 stop/bootstrap。Host 卡片的完整 GitHub、北京镜像、Linux x64/arm64、取消和离线 GoodBuddy 传输矩阵仍待验收，候选 CI/原生打包与系统休眠唤醒也尚未验证；部分开发证据不代表已经发布。
+- [x] **远程工作区与长任务更新**：Agent `0.11.23` 新增远程文件/Git 管理和可选模型限额，随包 Runtime 不再施加固定十分钟 Prompt 时限；无限请求时长仍保留独立连接超时。请先升级 Desktop 至 `0.12.11`，再下载并更新 Host 上的 Agent。
+- [x] **DeepSeek Harness（预览）**：使用 GoodBuddy 固定 Host 和 OpenAI 兼容模型连接；优先使用管理员提供的连接，否则跟随兼容的默认模型或首个兼容连接，无需单独重复选择，设置页显示实际管理员或回退模型来源。Ask 只允许调用 Host 中真实注册的 `read`、`skill` 以及 Main 管理的 Web Search/Fetch 代理，拒绝插件同名冒充，Execute 放行全部已启用内置及插件工具，并以当前用户权限运行。图像输入跟随所选模型连接的能力声明，文本模型在 Host 或模型调用前拒绝图片，图片模型通过有界内联内容和临时 Attachment Store 接收 JPEG/PNG。
+- [x] **DSH npm 插件市场**：市场默认关闭，由用户显式开启后搜索公共 npm 的 `dsh-plugin` 包，使用捆绑 npm 执行精确版本安装和普通 lifecycle scripts，并支持启停、JSON 配置、移除、失败启动自动停用和离线管理已安装插件；关闭市场只隐藏目录与管理界面，不改变已有插件的启停状态，第三方代码不受 Ask 初始化隔离。
+- [x] **Ask 与 Execute 工作模式**：Ask 保持只读；Execute 是用户对当前本机或 SSH 账号可用工具、进程、网络和可写路径的完整授权，包括工作区外路径及原生子代理工作。
+- [x] **Runtime 原生交互转交**：OpenCode 与 Continue 的选择、yes/no、自由文本回答和跳过使用现有问答卡片，OpenCode 同时转交属于当前请求的子会话提问。回答或跳过成功后保留原问题与答案，支持多轮记录和本地会话重载；旧版本已丢弃的答案不能恢复。Execute 权限确认自动处理，不等待第二次审批；具体支持范围见[交互边界](./docs/features/assistant-workbar/runtime-interactions.md)。
+- [x] **专家与 Subagent**：支持显式专家、团队分析和最多三个专家并行分析。专家继承父请求 Ask/Execute 模式，可使用已启用的本机直连模型工具，Ask 仍只读；这些工具不是远程 OpenCode 子会话。聊天先展示可逐项展开的专家完整输出，再在其下展示总 Agent 的综合结果，并随会话保存。
+- [x] **OpenCode 子代理过程与最终结果**：子代理卡片按顺序显示文字、推理和工具过程，最终结果独立展示。远程实时过程需要 Agent `0.11.20`，旧包仍显示最终结果但不补造缺失过程。
+- [x] **OpenCode 事件连接回收**：请求结束或取消后关闭自身订阅，不取消其他并行会话。
+- [x] **准确的消息底部状态**：区分请求准备、等待重试、开始重试、工具活动、待回答和终态；本机 OpenCode 使用原生重试次数和计划时间，直连模型显示自身退避阶段。消息底部状态点保持静态，未接入的 Runtime 重试不编造提示，会话列表闪点及发送、停止行为不变。
+- [x] **直连模型命令工作目录**：Execute 命令可通过绝对路径、相对路径或符号链接使用工作区外目录；工作区仍为默认目录和相对路径基准，Ask 保持只读。
+- [x] **简化 Runtime 选择**：会话与项目菜单不再枚举每个 Runtime 与模型的组合，Runtime 模型在系统设置中配置；已保存的项目固定模型仍可使用，并明确显示其固定模型。
+- [x] **角色绑定模型连接**：每个角色可继承默认模型或选择独立文本模型连接，失效连接安全回退默认模型，综合角色始终继承默认模型。
+- [x] **多协议模型配置**：支持 Anthropic Messages、OpenAI Responses、OpenAI Chat Completions、OpenAI Images 和无认证本机模型；新用户默认连接为本机 Ollama 兼容地址，不预置第三方云模型服务。升级时只替换从未配置凭据且仍完全等于旧内置值的历史默认连接，用户显式保存或加密凭据的连接保持不变；已有部署仅使用兼容环境变量提供凭据时继续沿用对应的历史连接参数，通用模型环境变量仍优先。“保存并测试模型”会发送有界的真实文本或图片生成请求并校验生成结果，而不是只检查 HTTP 连通性，因此可能产生少量服务商用量费用。
+- [x] **模型请求定制**：每个 LLM 连接可填写有界 JSON 自定义请求头和顶层请求体。直连与 Continue 支持两者；本地 OpenCode 和 DeepSeek Harness 只使用各自原生支持的请求头，受管 SSH OpenCode 模型网关支持两者。Runtime、协议和认证字段始终优先，这些普通连接设置不能用于保存 API Key 或其他密钥。详见[模型连接请求定制](./docs/features/model-connections/README.md)。
+- [x] **上下文用量与自动压缩**：直连模型按每次成功调用更新供应商用量，图片与工具轮次使用同一口径，供应商缺失 usage 时才回退估算；界面明确区分“本次模型调用”和“压缩后对话估算”，压缩线始终根据当前设置与所选模型窗口即时计算，不在每个对话中保存旧配置；压缩标识的前后值使用同一估算口径，运行记录仍保留各次模型调用的供应商 usage。对话与多轮工具 Agent 可在已完成调用越过阈值后自动重复压缩，规划时先为固定提示、工具定义和摘要预留预算；同一回复会分别保留 Agent 工具上下文与对话历史的压缩标识，并在应用重启或较早消息滚出本地历史窗口后继续复用摘要。
+- [x] **持久凭据保护**：API Key 由 Main 使用系统安全存储加密且不暴露给 Renderer。托管 SSH accepted Prompt 只把当前 profile 与密钥放入 Agent 内存，不写入 SSH 参数、远端环境或磁盘；其他路径仍在 Main 内使用。密钥随对应模型连接保存，修改服务地址或临时切换为无需认证不会要求重新输入；只有用户显式清除凭据或删除连接时才移除。
+- [x] **有界故障诊断**：Desktop 在用户数据目录中轮转保存启动、Runtime 和远程连接的固定阶段失败，最多 4 个 256 KiB 文件；GoodBuddy Agent 在各 installation 的私有 state 目录中轮转保存 daemon、连接、恢复和 Runtime 生命周期，最多 3 个 64 KiB 文件，并可通过固定 `diagnostics --installation-id` 命令读取。两端都只记录白名单阶段、稳定错误码/类型和固定短消息，不保存 Prompt、凭据、文件内容、路径、环境、SSH 参数或 Provider 原始响应；诊断写入失败不改变正常运行。
+- [x] **OpenCode Runtime 定制**：GoodBuddy 管理的内置 OpenCode 可发现原生 Agents、Tools、Commands、LSP、Formatters、MCP、Skills、Prompts 与 Resources；Tools 单独显示读取、文件修改、命令、网络、Agent 编排等类型、来源及 Ask/Execute 可用性，并隐藏 OpenCode 内部 `invalid` 与 GoodBuddy 临时 MCP 工具。支持保存默认 Agent、每次请求覆盖 Agent、通过原生 SDK 执行 Command、显示上下文用量并调用有总时限的原生 Compact；并发外部 Server 对话的提问使用请求级公开 ID 映射，回答不会串到其他会话。外部 OpenCode Server 只报告连接状态，不宣称原生清单可读。任意插件安装、Session Share、自动 Worktree 和 OpenCode 原生会话持久化仍不开放。
+- [x] **Continue Runtime 定制**：提供静态配置中的原生 Rules、Prompt 模板与 MCP 清单，以及可编辑的 GoodBuddy Rules/Prompt 配置预设；聊天可按请求选择预设和填入可继续编辑的 Prompt。当前 Continue Host 没有可信的静态原生 Tool 发现接口，且使用隔离的 `CONTINUE_GLOBAL_DIR`，因此界面明确标记 Tools 不支持静态发现，也不把 Host 实际不会加载的工作区或用户 Skills 冒充原生能力；GoodBuddy 分配的 Skills 仍按请求暂存执行。Continue 临时 Host 不复用原生会话压缩，手动压缩由 GoodBuddy 摘要模型完成并验证持久化摘要覆盖范围；Agent 交互提问转换为统一问答卡片。Resources、Hooks、后台 Job 和 Continue 原生会话管理继续暂缓。
+- [x] **Runtime 原生清单语义**：原生能力以 Agents、Tools、Commands、Skills、MCP、Rules、Prompts、Resources、LSP、Formatters 和上下文 11 个页签展示；清单状态独立于 Runtime 连通性，区分完整、部分、不可用、仅连接和不支持。DeepSeek Harness 通过 Host Registry 枚举有界的内置/插件 Tools 与 Skills，显示真实 Ask/Execute 边界，并排除 GoodBuddy 按请求分配的 Skills、Web/MCP 代理。
+- [ ] **Runtime 监督栏目**（规划中）：在应用级助手工作栏的固定 Runtime 栏目统一承载 OpenCode、Continue 和 DeepSeek Harness 的 Task 级委派、后台执行、Workflow/Hook、长任务与原生会话监督；用户只选择 Conversation 或 Task，Job/Run 保持内部，不形成树或独立操作对象。
+- [ ] **Subagent 高级监督**（规划中）：在工作栏固定 Runtime 栏目按 Task 聚合，提供可配置的嵌套、并行、预算和生命周期控制。基础专家模式继承与单层直连模型编程委派已经可用。
+
+### Skills、MCP 与知识库
+
+- [x] **Skills 按需接入**：可分配给直连模型、OpenCode、Continue 和 DeepSeek Harness，并使用有界资源和受控 Runtime 边界。
+- [x] **本机工具执行环境源码链路**：在“能力与工具 > 工具执行环境”中为本机 Skills 与 stdio MCP 选择 GoodBuddy 托管 Node.js、按需安装的托管 Python，或经过真实验证的自定义解释器；提供独立的原生地址/OSS 镜像选择、诊断、安装进度、取消和删除。新的本机 Runtime 与 stdio MCP 获得不可变 PATH 快照，不修改普通终端、系统环境或远程 Host。Windows x64 托管 Node 与原生地址 Python 已通过真实安装验证；托管 Python 归档按目标文件系统验证，Linux 保留大小写不同的合法路径，所有目标仍拒绝完全重复路径和不安全条目。
+- [ ] **本机工具执行环境发布验收**：六个平台/架构的 OSS 镜像对象已完成字节、大小和 SHA-256 公开回读验证。托管 Python 保持按需下载，不向 Desktop 发行包额外带入许可证文件。每个标准打包任务使用目标架构原生 Runner，并在打包前真实安装托管 Python，验证 SSL、pip 与 venv。不可变的 `v0.12.0` 尝试在发布前通过 Windows 与 macOS，但暴露了 Linux TAR 大小写处理问题；`v0.12.1` 在同步 Agent 发布时于原生打包前取消。已发布的 `v0.12.2` 随后通过全部六个原生打包任务及其托管 Python 安装探针。真实 Skill/MCP、自定义解释器和运行中进程协调仍是待完成验收。
+- [x] **内置 MCP 按需接入**：知识库、魔法笔记、GoodBuddy 配置与内置浏览器 MCP 可分别启停，并可分配给直连模型、GoodBuddy 管理的 OpenCode 和 Continue；DeepSeek Harness 在设置中明确显示为暂不支持。内置 MCP 仅通过当前请求的短期本机权限提供，Ask / Execute 读写边界不受用户配置放宽。
+- [x] **MCP Tools**：显式启用的自定义 MCP 可按 Runtime 分配给直连模型、GoodBuddy 管理的 OpenCode、Continue Agent Execute 和 DeepSeek Harness，并仅在 Execute 加载；Agent 子进程只获得按请求签发的本机回环权限，MCP 地址、命令和凭据保留在 Main，动态工具仍经过发现、执行记录与权限边界。直连模型与 Harness 的健康调用复用当前请求已发现的工具清单，不在每次调用前重复发现。
+- [x] **MCP Prompts 与 Resources 元数据**：MCP 测试仅在 Server 声明对应能力时发现有界的 Prompt、参数与 Resource 元数据，不读取 Resource 内容；Runtime 支持的 Prompt 可填入聊天草稿后继续编辑。OpenCode 可报告实验性 Resource 清单，Continue 当前版本明确不支持 Resources。
+- [x] **本地知识库**：支持文件、目录和网页导入、SQLite FTS5 检索及来源追溯。知识范围按对话保存，新对话默认不选择知识库；创建与检索高级参数默认折叠。文档区分可用、处理中和失败，支持打开来源、失败重试及移除来源前确认。
+- [ ] **外部知识库接入**（规划中）：在现有知识库页面管理 Dify、FastGPT 和 RAGFlow 实例；新建知识库时可读取并绑定远端知识库，保留 Provider 专属检索配置和引用。外部系统只负责知识检索，不接入其 App、Chat、Workflow 或 Agent，也不批量同步、本地索引或修改远端内容。被回答引用的有界检索片段随会话保存在本机。详见[外部知识库接入 PRD](./docs/features/knowledge-base/external-knowledge-prd.md)。
+- [x] **知识图谱**：支持规则、模型和混合抽取，以及实体、关系、别名和证据维护。
+- [x] **向量模型配置与检索**：可配置兼容 Embeddings 接口并用于语义检索。
+- [x] **向量诊断与索引任务**：提供真实向量生成诊断、按文档重建进度、取消、失败状态与重启后结果恢复；每篇成功文档立即可用于检索。
+- [x] **混合检索测试台**：支持全文、中文词组、向量和图谱通道诊断，可调 Top K、阈值、权重、本地或学习型重排及上下文预算。
+- [x] **分块、维护与评估**：支持固定、结构化和父子分块，分块维护、可取消重建及双语检索评估。
+- [x] **受控知识本体**：每个知识库可定义实体、关系、别名和端点约束，保留证据偏移、置信度和抽取来源，并显式提示图谱重建。
+- [x] **强制检索与引用上下文**：对话可按需或每次先检索，显示零结果、降级、失败与取消状态，并可查看引用上下文或安全打开来源。
+- [x] **魔法笔记 / Magic Notes**：提供本地优先的笔记与待办工作台、范围管理、编辑、筛选和受控 AI 评论；来源记录直接显示在所选待办的详情中，切换事项不会混入上一项的来源内容，读取失败使用应用通知，来源缺失有明确提示。左侧入口可按设置显示未完成待办数量，创建、保存和评论结果使用统一应用通知。
+- [ ] **MCP Server Control Plane**（规划中）：统一 MCP 生命周期、健康检查、重连、Schema 缓存、隔离、审批和审计。
+- [ ] **可追溯笔记摘录与 AI 编辑**（规划中）：从对话、知识和网页收集带来源的摘录，并提供需确认的总结、改写和整理操作。
+
+### 工作管理、长期协作与工作流
+
+- [x] **任务、活动与成果**：集中管理任务状态、审计活动和独立成果文件；普通聊天回复只保留在会话中，不再自动复制到成果栏，已有重复聊天 Markdown 从成果列表隐藏但不物理删除。运行记录改由 Main SQLite 保存，不再受旧 Renderer 的 500 条、单详情 4,000 字符或约 2 MB 上限影响，页面按批继续显示；不再常驻旧缓存截断警告，但不会恢复此前已丢失的历史。Token 用量按 Runtime 与模型归类，并针对 OpenAI 兼容与 Anthropic Messages 的不同上报口径归一化展示缓存命中率；活动按会话分组并默认收起，避免长历史占满页面。
+- [x] **Task 与定制任务体验**：每个产品级 Task 只关联一条 Conversation，一条 Conversation 可承载多个 Task；左侧会话列表通过行首展开按钮显示带共享状态点的 Task 子项，父会话行不重复任务标签，UI 只展示到 Task，不暴露 Job/Run 层级。新建定制任务可关联当前或新 Conversation，默认 Execute 并沿用 Runtime、工具和审批边界；重复触发复用同一 Task，文本结果回写 Conversation，独立文件和图片保留为成果。普通消息与到期 Scheduled Task 共用 Conversation 级持久发送队列，同一会话一次只执行一项；当前回复期间仍可继续发送，队列按顺序续跑，并允许删除或“立即中断并插入”。Task Center 继续作为完整索引，不建设独立 Automation Center。当前计划触发支持单次、每日和每周；高级时区、Cron、事件触发与重试治理仍按 PRD 逐步实现。详见 [Task Center PRD](./docs/features/task-and-job/task-center-prd.md) 和 [Scheduled Task PRD](./docs/features/task-and-job/scheduled-task-prd.md)。
+- [x] **记忆与智能心跳**：当前提供周期回顾、建议记忆、洞察、后续任务和可审计运行轨迹。
+- [x] **定时消息沿用会话**：定时消息使用会话当前历史、Runtime、工作模式和已保存的知识检索设置；任务详情显示实际运行模式，当前 occurrence 未结束时禁止重复“立即运行”。
+- [x] **智能心跳入口与范围改善**：将“智能心跳 > 心跳计划”作为完整配置的唯一权威入口，支持创建和编辑 Global 或指定一个、多个 Project 的计划；旧单项目配置无损迁移，项目级记忆与行动输出必须显式指定范围内的 Project。Task Center 和设置不再复制心跳表单；按分区回顾、候选生成和唤起条件仍待设计。详见 [智能心跳 PRD](./docs/features/smart-heartbeat/prd.md)。
+- [ ] **通用监督**（规划中）：通过固定监督栏目观察用户选择的会话、任务、自动化或实验对象，提供带证据的评论与人工介入请求，但不自动发言、批准工具或切换 Execute。详见 [会话监督 PRD](./docs/features/conversation-supervision/prd.md)。
+- [ ] **批量运行与对比实验室**（规划中）：对模型、Prompt、角色和工作流配置执行批量对比，汇总质量、耗时、Token、费用、失败率和成果差异。
+- [ ] **时态记忆与事实冲突检测**（规划中）：为记忆和知识图谱增加有效期、当前事实、过期与矛盾检测、事实核验及证据回溯。
+- [ ] **可视化受控工作流**（规划中）：提供版本化 DAG、条件分支、审批、取消和恢复，执行节点继续经过 Main Runtime 边界。
+- [ ] **统一 Run Graph 与回放**（规划中）：关联任务、Subagent、模型、知识、工具审批、用量和成果，支持失败定位、重试和脱敏导出。
+
+### 浏览器、通信、语音与应用维护
+
+- [x] **Runtime 共享内置浏览器**：使用 GoodBuddy 内置的隔离 Chromium，不控制客户端已安装的浏览器；用户通过内置 MCP 总开关和 Runtime 分配决定是否提供给 Execute，开启后不逐次询问。关闭 Agent 浏览器能力不影响用户继续在浏览器工作栏中手动前往、返回、刷新、停止加载、交互或关闭浏览器。直连模型、GoodBuddy 管理的 OpenCode 和 Continue 通过请求级权限共享按 Conversation 归属的会话和串行操作路径，用户导航会改变 Agent 下一步看到的页面。
+- [x] **浏览器多页签与按需资源**：同一对话可打开多个共享登录状态、页面与导航独立的浏览器页签，模型请求固定使用开始时绑定的目标。未使用的请求预留不创建浏览器资源，已释放页面可重新打开；保留显式截图，普通操作不再触发无用的自动截图。
+- [x] **客户端电脑控制工具**：与内置浏览器分开管理，并保留范围、取消、超时、输出边界和执行记录。
+- [x] **远程消息通道项目**：微信 ClawBot、企业微信和钉钉分别拥有系统管理的项目、独立远程会话、工作目录、处理后端、默认 Ask/Execute 模式及任务活动归属；完整回复交由各通道按平台能力控制长度与分段，不再由公共服务统一截断。
+- [x] **微信 ClawBot 扫码与媒体**：通过独立 Sidecar 完成本机扫码、验证码、加密凭据和文字收发；支持个人微信私聊图片与文件，单条消息最多 4 个附件、解密后合计不超过 12MB。
+- [x] **微信安全回传**：支持返回当前任务生成的图片，或在用户明确要求时将本次最终文本生成为 Markdown 附件；不自动读取或发送已有工作区文件。
+- [x] **企业微信与钉钉连接**：支持 Main-only 加密设置、环境变量只读覆盖、连接测试、动态启停、发送者范围和状态诊断。
+- [x] **受管本地模型下载源**：在“平台功能 / 通用设置”中为后续语音输入与 OCR 模型下载全局选择 ModelScope（默认）或 Hugging Face；所选来源缺少完整已验证文件时明确不可用，不静默换源或混合文件。
+- [x] **可选本地语音模型管理**：应用不内置模型权重；提供校验下载、进度与取消、来源链接、ZIP 或本地目录导入、切换和删除。
+- [x] **本地录音与离线转写**：采集麦克风音频并使用已选择的本地模型离线转写，支持停止、取消、状态反馈和资源释放。
+- [x] **版本检查与镜像节点**：在“关于与更新”中选择 GitHub（默认）或镜像节点；手动检查、启动时检查和下载页使用同一选择，并只读取固定可信的发布索引，不自动下载或安装。
+- [x] **应用内反馈**：在“关于与更新”中直接提交问题、建议或体验反馈，支持可选邮箱和单张截图；默认不上传诊断，用户可主动附加有界的最近桌面诊断摘要。失败后保留草稿、诊断选择和同一请求编号；不会附加对话、Prompt、凭据、文件内容、路径、Provider 原始响应或远端 Agent 日志。
+- [x] **内网兼容**：允许应用内 HTTP 与无效、自签名或过期的 HTTPS 证书；反馈、微信凭据与媒体等固定平台服务仍保持严格证书校验。
+
+### 开源、构建与发布
+
+- 当前源码候选为 Desktop `0.12.12`、Agent `0.11.23`，OpenCode 固定为 `1.18.29`；正式发布状态以 Desktop 与 Agent 的独立发布渠道为准。
+- [x] **0BSD 开源许可**：原创代码可自由使用、复制、修改、分发和商用；第三方组件和资源仍遵循各自许可证。
+- [x] **可复现依赖安装与源码构建**：使用锁定依赖、Node.js 24 和统一的测试、类型检查、Lint、生产构建命令。
+- [x] **六平台原生发布矩阵**：Windows、macOS、Linux 的 `x64`、`arm64` 目标由原生 Runner 构建，并提供发布清单和 SHA-256 哈希。Windows 提供 NSIS 与 portable ZIP，macOS 仅 DMG，Linux 提供 AppImage、DEB 和 RPM，共 12 个安装包、20 个发布资产。
+- [x] **桌面 Runtime 包校验**：OpenCode 离线依赖复制避开 electron-builder 对源根目录 node_modules 的排除，DSH 会话投影组件打入解包后的 Host。最终包逐文件核对离线依赖并拒绝外部 DeepSeek 导入；Windows x64 CI 还会导入包内 OpenCode 插件、验证真实 DSH UtilityProcess 握手，通过后才发布。
+- [x] **DMG-only 更新清单**：当前 Desktop 和官网读取器同时接受仅 DMG 与历史 DMG/ZIP 清单。旧版 macOS 的 GitHub 更新检查及所有旧版镜像更新检查需要从下载页手动升级。
+
+### 开放接口、团队协作与远程执行
+
+- [x] **远程任务委派**：仅在用户显式配置端点和令牌后启用，按全局内网兼容模式使用 HTTP(S)，结果进入持久化发件箱。
+- [ ] **Headless Runtime API**（规划中）：提供本机优先的任务、事件、状态和成果 API，以及有范围、有效期、限流和撤销能力的令牌。
+- [ ] **GoodBuddy Team Hub**（规划中）：以可选服务提供组织、RBAC、项目共享、远程 Agent、策略下发和租户审计。
+- [ ] **SSH 主机与远程执行空间发布验收**：主机 CRUD、Host Key、加密凭据、Project UI、Workspace、OpenCode ACP v5、Agent-owned Prompt/gateway/transcript、Ask 只读、Execute 完整账号权限、取消、detached Agent 精确重连和 release-only 双架构资源校验已经接线。Linux x64 当前源码已用真实模型与工具通过 detach、进程结束、relay 丢失、并发、取消、Provider 异常、Agent 重启和 Desktop SQLite 恢复矩阵；当前源码测试签名 Agent `0.11.17` 又通过两个并发 Ask 读取、一次 Execute 写入并读回，以及 6 次带自定义 Header 和 Body 的真实受管网关模型请求，未发现 Provider 请求重放，隔离 Agent state 中也没有 API Key 或自定义请求值。公开 signing key registry 已供应。控制面直连源码不等待新 installer-bearing 包，但仍需公开核对当前 Linux x64/arm64 正式签名工件矩阵，并完成 GitHub/北京镜像、双架构和离线 GoodBuddy 传输的发布验收；门槛未满足时不宣称该路径已发布或通过正式发布验收。
+- [ ] **多云远程沙盒 Agent**（规划中）：通过云厂商 API 和 SSH Agent 管理专用 Linux 沙盒；凭据留在 Main 进程，高风险控制面操作单独确认。
+
+## 规划原则
+
+规划中的工作流、Subagent、MCP、远程 API 和沙盒能力不得绕过现有 Main Runtime、Ask/Execute、权限、取消、超时和审计边界。

LICENSE

@@ -0,0 +1,12 @@
+Copyright (C) 2026 MesaLogo
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

@@ -1,118 +1,167 @@
+<div align="center">
+  <img src="./sites/assets/goodbuddy-light.png" width="96" alt="GoodBuddy" />
+
 # GoodBuddy
 
-面向专业工作与国产化环境的安全桌面智能助手。
+**Desktop access to model chat, coding agents, knowledge, and scheduled work**
 
-GoodBuddy 将模型连接、Agent Runtime、本地知识库、知识图谱、远程消息通道、任务协作和持续成长能力组织在同一个桌面工作空间中。它不是简单的聊天窗口，而是一套可审计、可控制、可长期使用的个人智能工作环境。
+**English** | [简体中文](./README.zh-CN.md)
 
-![GoodBuddy 工作空间](docs/screenshots/workspace-overview.png)
+[Website](https://mesalogo.github.io/goodbuddy/en.html) ·
+[Download](https://github.com/mesalogo/goodbuddy/releases) ·
+[Feature Matrix](./FEATURES.md) ·
+[Build Guide](./BUILD.md)
 
-## 为什么选择 GoodBuddy
+[![Release](https://img.shields.io/github/v/release/mesalogo/goodbuddy?label=release)](https://github.com/mesalogo/goodbuddy/releases)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue.svg)](./LICENSE)
+[![Windows](https://img.shields.io/badge/Windows-x64%20%7C%20arm64-0078D4)](https://github.com/mesalogo/goodbuddy/releases)
+[![macOS](https://img.shields.io/badge/macOS-x64%20%7C%20arm64-000000)](https://github.com/mesalogo/goodbuddy/releases)
+[![Linux](https://img.shields.io/badge/Linux-x64%20%7C%20arm64-FCC624)](https://github.com/mesalogo/goodbuddy/releases)
+</div>
 
-### 安全可控的 Agent 执行
+![GoodBuddy workspace](./docs/screenshots/workspace-overview.png)
 
-GoodBuddy 通过统一的 Agent Runtime 控制层接入直连模型、OpenCode 和 Continue。工具不会被直接暴露给界面，所有执行都受到工作模式、权限策略和运行边界约束。
+GoodBuddy is a desktop application for model chat, coding agents, knowledge
+retrieval, notes, and scheduled tasks. No GoodBuddy account is required.
+Workspace data is stored locally by default. Model endpoints can run on the
+same device, on a private network, or at a provider selected by the user.
 
-- `Ask`：只读问答，不调用工具。
-- `Execute`：选择该模式即授权当前交互运行使用已启用的受控工具。
-- 可在设置中禁止直连模型执行所有工具；工具调用仍记录到活动。
-- 统一处理取消、超时、输出边界、进程退出和异常恢复。
+## Highlights
 
-### 数据主权与本地优先
+- **Local-first workspace**: No GoodBuddy account is required. Workspace data
+  stays local by default, and users choose where model services run.
+- **Unified Agent Runtimes**: Use direct models, OpenCode, Continue, and the
+  preview DeepSeek Harness from one desktop interface.
+- **Explicit execution boundaries**: `Ask` remains read-only, while `Execute`
+  uses the current account's permissions. Tool activity, cancellation,
+  timeouts, and token usage are recorded.
+- **Broad platform coverage**: Official Linux releases cover `x64` and `arm64`,
+  including compatible distributions used in China's domestic computing
+  ecosystem. A separate
+  experimental `loong64` preview is available for LoongArch systems.
+- **Knowledge and long-running work**: Knowledge bases, graphs, Magic Notes,
+  tasks, and Smart Heartbeat share one desktop workspace.
 
-- 会话、任务、成果、记忆、知识库和图谱保存在本地 SQLite。
-- API Key 通过系统安全存储加密，不以明文写入配置。
-- Electron Main、Preload、Renderer 严格分层，Renderer 仅能使用类型化 IPC。
-- 子进程使用环境变量白名单，避免继承无关凭据。
-- 默认不依赖 GoodBuddy 云端账户，也不代理用户的模型流量。
+Platform coverage describes operating-system, instruction-set, and package
+compatibility, not certification for every hardware vendor or distribution
+release. LoongArch is outside the official release matrix; see the
+[LoongArch preview notes](./docs/development/loongarch-preview-build.md) for its
+current limitations.
 
-### 面向国产化环境交付
+## Capabilities
 
-- 支持 Windows、macOS 与 Linux。
-- 支持 Linux `x64` 和 `arm64`。
-- 提供适用于麒麟、统信 UOS 等 Debian 系桌面的 `deb` 安装包。
-- 提供 AppImage，便于免安装验证与便携分发。
-- 支持 Anthropic Messages、OpenAI Chat Completions、OpenAI Images 与无认证本机模型。
-- 可连接企业网关、私有模型服务和国产模型适配层。
+| Area | Available in GoodBuddy |
+| --- | --- |
+| Agent Runtimes | Direct model connections, OpenCode, Continue, and the preview DeepSeek Harness |
+| Data and execution | Local SQLite storage, read-only `Ask`, full-account `Execute`, and recorded tool activity |
+| Knowledge | File, folder, and web imports with full-text, Chinese phrase, vector, and knowledge graph retrieval |
+| Desktop releases | Official Windows, macOS, and Linux builds for `x64` and `arm64`, plus an experimental LoongArch preview |
+| Integrations | Local or hosted model endpoints, custom MCP servers, WeChat ClawBot, WeCom, and DingTalk |
 
-## 核心功能
+## Product tour
 
-### 一体化智能工作空间
+### Knowledge bases and graphs
 
-- Projects 与独立对话上下文。
-- 专家角色和最多三个只读专家并行分析。
-- 任务、活动、成果、记忆和自动化集中管理。
-- 支持文件、桌面截图、应用窗口、剪贴板和语音上下文。
-- 显示真实 Git 工作区变更。
-- 支持远程任务委派与持久化结果发件箱。
-- Skills 与 MCP 能力按需接入。
+![GoodBuddy knowledge workspace](./docs/screenshots/knowledge-workspace.png)
 
-### 远程消息通道与微信 ClawBot
+![GoodBuddy knowledge graph](./docs/screenshots/knowledge-graph.png)
 
-微信 ClawBot、企业微信和钉钉分别使用系统管理的通道项目。远程发送者拥有独立会话，任务、活动和成果持续归属于对应通道与项目。
+### Magic Notes and Smart Heartbeat
 
-- 微信 ClawBot 使用本机扫码绑定，支持个人微信私聊文字、图片和文件。
-- 单条微信消息最多 4 个附件，解密后合计不超过 12MB；图片和支持的文档进入现有受控上下文。
-- 通道可选择直连文本模型、OpenCode 或 Continue。OpenCode/Continue 始终跟随“Agent Runtime”中的全局配置，不在通道中维护第二套 Runtime 配置。
-- 远程消息支持 Ask 与 Execute。Execute 不显示通道专属逐次审批，但仍受发送者范围、项目目录、Runtime、沙箱、能力开关和活动审计约束。
-- 当前任务生成的图片可以返回微信；明确要求文件时可将本次最终文本生成为 Markdown 附件，不自动发送已有工作区文件。
-- “断开本机绑定”只停止本机收发并清除本地凭据，不会删除通道项目、远程会话或历史，也不承诺解除微信服务端授权。
+![GoodBuddy Magic Notes](./docs/screenshots/GoodBuddy_MFSGeK0NoT.gif)
 
-完整设计、安全边界和联调状态见[远程消息通道项目与微信 ClawBot 集成 PRD](docs/features/wechat-clawbot-channel-project-prd.md)。
+![GoodBuddy Smart Heartbeat](./docs/screenshots/smart-heartbeat.png)
 
-### 本地知识库与知识图谱
+## Agent Runtimes
 
-文件、目录和网页内容可以按知识库独立管理。GoodBuddy 会完成解析、索引、检索和图谱构建，并保留可追溯的来源与证据。
-
-![GoodBuddy 知识工作区](docs/screenshots/knowledge-workspace.png)
-
-- SQLite FTS5 全文检索与有界上下文召回。
-- 支持规则、模型和混合图谱抽取。
-- 支持实体、关系、别名、证据与来源位置追溯。
-- 图谱可搜索、筛选、缩放和拖动节点。
-- 支持实体编辑、合并以及关系维护。
-- 文档解析包含压缩包展开限制、路径校验和敏感字段过滤。
-
-![GoodBuddy 知识图谱](docs/screenshots/knowledge-graph.png)
-
-### 智能心跳
-
-智能心跳让 GoodBuddy 不只响应当前问题，还能定期回顾近期工作，沉淀长期记忆，发现风险，并将洞察转化为可处理的建议。
-
-![GoodBuddy 智能心跳](docs/screenshots/smart-heartbeat.png)
-
-- 按项目或全局配置周期回顾计划。
-- 展示心跳健康、记忆沉淀、洞察发现和行动转化。
-- 提供成长趋势、最新报告和可审计的运行轨迹。
-- 建议记忆可确认或忽略。
-- 后续任务可带入 Ask 对话、标记完成或忽略。
-- 支持手动运行、暂停、恢复和安全删除计划。
-
-### 多 Runtime 与模型连接
-
-| 能力 | 适用场景 | 控制方式 |
+| Runtime | Functions | Configuration |
 | --- | --- | --- |
-| 直连模型 | 问答、知识总结、受控工具执行、图像生成 | Ask 只读；Execute 自动授权已启用的工作区、浏览器与 MCP 工具，可设置为全部禁止 |
-| OpenCode | 完整编码与工作区任务 | Execute 不弹 GoodBuddy 审批，保留 Runtime 自身权限、取消和活动记录 |
-| Continue | Agent 编码与工作区任务 | Execute 不弹 GoodBuddy 审批，使用独立宿主、取消和活动记录 |
+| Direct models | Chat, retrieval, image generation, and built-in tools | GoodBuddy model connections |
+| OpenCode | Coding agents, native commands, tools, and skills | GoodBuddy-managed or native OpenCode configuration |
+| Continue | Rules, prompt presets, and coding tasks | GoodBuddy-managed or native Continue configuration |
+| DeepSeek Harness (preview) | A fixed host with optional plugin capabilities | GoodBuddy-managed OpenAI-compatible connection |
 
-消息通道选择 OpenCode 或 Continue 时只选择 Runtime 类型，具体模型来源、自有配置、可执行文件和服务地址统一复用“Agent Runtime”设置，并在每次远程请求开始时解析当前全局配置。
+Each run reports cancellation, timeouts, token usage, tool calls, and history.
+Runtime-specific capabilities and configuration remain separate.
 
-## 功能矩阵与路线图
+## Download
 
-以下为仓库首页的简要路线图；完整能力说明、状态和重大规划统一记录在 [FEATURES.md](FEATURES.md)。
+Download a build from
+[GitHub Releases](https://github.com/mesalogo/goodbuddy/releases):
 
-- [x] [跨平台桌面工作空间与安全上下文](FEATURES.md#桌面基础工作空间与上下文)
-- [x] [多 Runtime、模型连接、Skills 与 MCP](FEATURES.md#agent-runtime-与模型连接)
-- [x] [本地知识库、向量检索与知识图谱](FEATURES.md#skillsmcp-与知识库)
-- [x] [任务、成果、记忆与智能心跳](FEATURES.md#工作管理长期协作与工作流)
-- [x] [微信 ClawBot、企业微信与钉钉消息通道](FEATURES.md#浏览器通信语音与应用维护)
-- [x] [本地录音与离线转写](FEATURES.md#浏览器通信语音与应用维护)
-- [x] [魔法笔记 / Magic Notes](FEATURES.md#知识工作空间与魔法笔记)：本地优先的笔记与待办工作台，支持受控 AI 评论。
-- [ ] [Agent 框架、受控工作流与团队协作](FEATURES.md#agent-框架与协作能力)
-- [ ] [多云远程沙盒 Agent](FEATURES.md#多云远程沙盒-agent)
+| Platform | Architectures | Formats |
+| --- | --- | --- |
+| Windows | `x64`, `arm64` | NSIS, portable ZIP |
+| macOS | `x64`, `arm64` | DMG, ZIP |
+| Linux | `x64`, `arm64` | AppImage, DEB, RPM |
 
-`[x]` 表示当前已提供，`[ ]` 表示开发中或规划中；未完成项目不代表已包含在当前发布版本中。
+The experimental LoongArch `loong64` build is distributed through a separate
+preview channel on the [product website](https://mesalogo.github.io/goodbuddy/#download).
 
-## 隐私说明
+Desktop installers do not contain remote Agent payloads. Local projects do not
+need an Agent package; managed SSH users download or import one explicitly in
+Settings.
 
-模型请求只会发送到用户选择的模型连接。本地数据保存在当前系统的应用数据目录中；远程委派仅在用户显式配置端点和令牌后启用。面向纯内网部署的“内网兼容模式”默认开启，允许 HTTP 并接受无效、自签名或过期的 HTTPS 证书；可在“安全与数据”中关闭并恢复严格校验。微信凭据和媒体端点不受该兼容模式放宽，始终只允许经过校验的腾讯微信 HTTPS 主机与重定向。
+Code signing and macOS notarization are not configured yet, so the operating
+system may display a security warning.
+
+## Run from source
+
+Requires Node.js 24 and npm:
+
+```bash
+git clone https://github.com/mesalogo/goodbuddy.git
+cd goodbuddy
+npm ci
+npm run dev
+```
+
+See [BUILD.md](./BUILD.md) for build and packaging instructions.
+
+## Documentation
+
+- [Feature matrix and roadmap](./FEATURES.md)
+- [Product feature documentation](./docs/features/)
+- [UI design system](./UI-DESIGN.md)
+- [Build and packaging](./BUILD.md)
+- [Release runbook](./docs/development/release-runbook.md)
+
+## Privacy and execution boundaries
+
+- Model requests are sent only to services selected by the user.
+- Local data stays in the operating system's application data directory by
+  default. API keys are encrypted by secure system storage.
+- The Renderer has no access to raw Electron APIs or model credentials.
+- The DeepSeek Harness plugin marketplace is off by default. Third-party
+  install scripts, initialization code, and Execute tools run with the current
+  user's permissions.
+- Remote delegation is enabled only after the user configures an endpoint and
+  token.
+- Private-network compatibility permits in-app HTTP and non-standard HTTPS
+  certificates. WeChat credential and media endpoints remain strictly
+  validated.
+
+## Contributing
+
+Issues and pull requests are welcome. Read [AGENTS.md](./AGENTS.md) first, then
+run:
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+```
+
+## Community communication
+
+Scan the QR code to join the GoodBuddy WeChat group:
+
+<img width="1250" height="1194" alt="9627ce196b0de42f123c33dd9dea1568" src="https://github.com/user-attachments/assets/e806543f-6d8a-4c5c-ba44-19e74dac9a78" />
+
+
+
+## License
+
+Original GoodBuddy code is released under the [0BSD License](./LICENSE). You may
+use, modify, distribute, and commercialize it freely. Third-party components
+and resources retain their respective licenses.

README.zh-CN.md

@@ -0,0 +1,136 @@
+<div align="center">
+  <img src="./sites/assets/goodbuddy-light.png" width="96" alt="GoodBuddy" />
+
+# GoodBuddy
+
+**模型对话、编程 Agent、本地知识库和定时任务的桌面入口**
+
+[English](./README.md) | **简体中文**
+
+[产品官网](https://mesalogo.github.io/goodbuddy/) ·
+[下载](https://github.com/mesalogo/goodbuddy/releases) ·
+[功能矩阵](./FEATURES.zh-CN.md) ·
+[构建说明](./BUILD.md)
+
+[![Release](https://img.shields.io/github/v/release/mesalogo/goodbuddy?label=release)](https://github.com/mesalogo/goodbuddy/releases)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue.svg)](./LICENSE)
+[![Windows](https://img.shields.io/badge/Windows-x64%20%7C%20arm64-0078D4)](https://github.com/mesalogo/goodbuddy/releases)
+[![macOS](https://img.shields.io/badge/macOS-x64%20%7C%20arm64-000000)](https://github.com/mesalogo/goodbuddy/releases)
+[![Linux](https://img.shields.io/badge/Linux-x64%20%7C%20arm64-FCC624)](https://github.com/mesalogo/goodbuddy/releases)
+</div>
+
+![GoodBuddy 工作空间](./docs/screenshots/workspace-overview.png)
+
+GoodBuddy 是用于模型对话、编程 Agent、知识检索、笔记和定时任务的桌面应用。使用 GoodBuddy 无需注册账号，工作数据默认保存在本机。模型服务可以运行在本机、组织内网或用户选择的云端服务。
+
+## 产品亮点
+
+- **本地优先**：无需注册 GoodBuddy 账号，工作数据默认保存在本机，模型服务由用户选择。
+- **统一 Agent Runtime**：在一个桌面界面中使用直连模型、OpenCode、Continue 和预览版 DeepSeek Harness。
+- **执行边界明确**：`Ask` 保持只读，`Execute` 使用当前账号权限，工具调用、取消、超时和 Token 用量均有记录。
+- **支持信创软硬件**：正式 Linux 版本覆盖国产 `x64` 与 `arm64` 架构，可用于统信 UOS、银河麒麟及海光、兆芯、鲲鹏、飞腾等兼容环境；龙芯 LoongArch 提供独立 `loong64` 实验预览版。
+- **知识与长期工作一体化**：知识库、知识图谱、魔法笔记、任务和智能心跳共享同一个桌面工作空间。
+
+信创支持按操作系统、指令集和安装包兼容性描述，不代表已完成所有厂商、整机和系统版本的兼容认证。龙芯版本尚未进入正式发布矩阵，具体限制见[龙芯预览版说明](./docs/development/loongarch-preview-build.md)。
+
+## 主要能力
+
+| 范围 | GoodBuddy 提供的能力 |
+| --- | --- |
+| Agent Runtime | 直连模型、OpenCode、Continue 和预览版 DeepSeek Harness |
+| 数据与执行 | 本地 SQLite、只读 `Ask`、使用当前账号完整权限的 `Execute`、工具调用记录 |
+| 知识库 | 导入文件、目录和网页，通过全文、中文词组、向量和知识图谱检索 |
+| 桌面版本 | Windows、macOS、Linux 的 `x64` 与 `arm64` 正式版本，以及龙芯 LoongArch 实验预览版 |
+| 外部连接 | 本机或内网模型服务、自定义 MCP、微信 ClawBot、企业微信和钉钉 |
+
+## 产品界面
+
+### 知识库与知识图谱
+
+![GoodBuddy 知识工作区](./docs/screenshots/knowledge-workspace.png)
+
+![GoodBuddy 知识图谱](./docs/screenshots/knowledge-graph.png)
+
+### 魔法笔记与智能心跳
+
+![GoodBuddy 魔法笔记](./docs/screenshots/GoodBuddy_MFSGeK0NoT.gif)
+
+![GoodBuddy 智能心跳](./docs/screenshots/smart-heartbeat.png)
+
+## Agent Runtime
+
+| Runtime | 适用场景 | 配置来源 |
+| --- | --- | --- |
+| 直连模型 | 对话、知识检索、图片生成和内置工具 | GoodBuddy 模型连接 |
+| OpenCode | 编程 Agent、原生 Commands、Tools 和 Skills | GoodBuddy 管理或 OpenCode 自有配置 |
+| Continue | Rules、Prompt 预设和编程任务 | GoodBuddy 管理或 Continue 自有配置 |
+| DeepSeek Harness（预览） | 固定 Host 与可选插件能力 | GoodBuddy 管理的 OpenAI 兼容连接 |
+
+每次运行都会记录取消、超时、Token 用量、工具调用和执行历史。各 Runtime 的原生能力与配置仍分别管理。
+
+## 下载
+
+从 [GitHub Releases](https://github.com/mesalogo/goodbuddy/releases) 下载：
+
+| 系统 | 架构 | 格式 |
+| --- | --- | --- |
+| Windows | `x64`、`arm64` | NSIS、便携 ZIP |
+| macOS | `x64`、`arm64` | DMG、ZIP |
+| Linux | `x64`、`arm64` | AppImage、DEB、RPM |
+
+龙芯 LoongArch 使用独立的 `loong64` 实验预览通道，可在[产品官网](https://mesalogo.github.io/goodbuddy/#download)选择下载。
+
+桌面安装包不包含远端 Agent payload。本地项目无需 Agent 包；托管 SSH 用户可在设置中单独下载或导入。
+
+当前未配置代码签名和 macOS notarization，操作系统可能显示安全提示。
+
+## 从源码运行
+
+需要 Node.js 24 和 npm：
+
+```bash
+git clone https://github.com/mesalogo/goodbuddy.git
+cd goodbuddy
+npm ci
+npm run dev
+```
+
+构建与打包说明见 [BUILD.md](./BUILD.md)。
+
+## 文档
+
+- [功能矩阵与路线图](./FEATURES.zh-CN.md)
+- [产品功能文档](./docs/features/)
+- [UI 设计系统](./UI-DESIGN.md)
+- [构建与打包](./BUILD.md)
+- [发布流程](./docs/development/release-runbook.md)
+
+## 隐私与执行边界
+
+- 模型请求只发送到用户选择的服务。
+- 本地数据默认保存在系统应用数据目录，API Key 由系统安全存储加密。
+- Renderer 不接触原始 Electron API 或模型凭据。
+- DeepSeek Harness 插件市场默认关闭。第三方插件安装脚本、初始化代码和 Execute 工具以当前用户权限运行。
+- 远程委派只在用户配置端点和令牌后启用。
+- 内网兼容模式允许应用内 HTTP 和非标准 HTTPS 证书；微信凭据和媒体端点仍执行严格校验。
+
+## 参与贡献
+
+欢迎提交 Issue 和 Pull Request。请先阅读 [AGENTS.md](./AGENTS.md)，提交前运行：
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+```
+
+## 社区交流
+
+扫描二维码加入 GoodBuddy 微信群：
+
+<img width="1250" height="1194" alt="9627ce196b0de42f123c33dd9dea1568" src="https://github.com/user-attachments/assets/ff87dfac-d72f-47b7-ac9a-c88b0b4c96d9" />
+
+
+## 开源许可
+
+GoodBuddy 原创代码采用 [0BSD License](./LICENSE)，可自由使用、修改、分发和商用。第三方组件和资源遵循各自许可证。

UI-DESIGN.md

@@ -0,0 +1,836 @@
+# GoodBuddy 统一界面设计系统
+
+## 1. 目的与适用范围
+
+本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、任务中心、知识库、
+智能心跳、运行记录，以及后续新增的一级页面。
+
+设计系统解决两类问题：
+
+1. 统一跨页面的视觉语言、信息层级和交互反馈。
+2. 保留不同工作场景所需的布局差异，不强行把阅读、工作台、仪表盘和数据视图做成同一种页面。
+
+所有新界面必须优先使用本文定义的语义令牌、页面壳层和共享组件。现有界面迁移时应保持功能与数据语义不变，不以视觉统一为理由隐藏范围、状态或风险。
+
+## 2. 核心原则
+
+### 2.1 一致的语义，不要求相同的布局
+
+- 相同含义使用相同的颜色、间距、控件和文案结构。
+- 不同任务使用明确命名的页面壳层，不再为单个页面随意设置宽度。
+- 页签只用于同级页面导航，分段控件只用于当前视图内的单选切换，筛选控件只改变当前数据集合。
+
+### 2.2 范围始终可见
+
+知识、任务、自动化和活动记录可能属于全局或某个项目。当前范围必须在页面标题区或对象标题旁持续显示，不能只通过入口位置、默认筛选或颜色暗示。
+
+### 2.3 主任务优先
+
+- 每个页面只保留一个视觉上最突出的主操作。
+- 页面标题、范围、说明、主操作和导航按固定层级排列。
+- 次要设置、筛选和批量操作不得与主任务争夺注意力。
+
+### 2.4 状态明确且可恢复
+
+- 加载、空内容、无结果、失败、只读和权限不足是不同状态，必须分别呈现。
+- 可撤销操作优先提供撤销，不可撤销操作必须在执行前说明影响范围。
+- 不依赖颜色单独表达状态或风险。
+
+### 2.5 默认支持浅色与深色主题
+
+组件不得直接使用原始颜色值。主题差异只在令牌层定义，业务组件仅引用语义令牌。
+
+两种主题必须保持相同的信息层级，但不要求机械地反转明暗。浅色主题以白色主内容画布、冰蓝灰侧栏和轻微着色的顶栏建立空间关系；深色主题使用深海军蓝与蓝灰表面逐层提亮，避免纯黑。蓝色承担主要选择和交互，青绿色主要承担成功与可用状态，二者不得混用语义。
+
+## 3. 设计令牌
+
+令牌以 CSS 自定义属性实现。`:root` 提供浅色值，`[data-theme="dark"]` 覆盖深色值。组件样式不得新增只服务于单个页面的颜色、阴影、圆角或间距常量。
+
+### 3.1 颜色令牌
+
+| 令牌 | 用途 |
+| --- | --- |
+| `--surface-canvas` | 应用和页面底色 |
+| `--surface-raised` | 卡片、面板、输入框和弹窗 |
+| `--surface-subtle` | 次级区域和控件底色 |
+| `--surface-muted` | 进度轨道和更弱的分隔表面 |
+| `--text-primary` | 标题与主要正文 |
+| `--text-secondary` | 辅助正文 |
+| `--text-muted` | 占位、时间和弱提示 |
+| `--text-on-accent` | 强调色或危险色表面上的文字 |
+| `--border-default` | 常规边框 |
+| `--border-control` | 输入框、分段控件等必须清晰可辨的控件边界 |
+| `--border-subtle` | 区块分隔线 |
+| `--accent`、`--accent-hover` | 强调文字、图标和交互反馈 |
+| `--accent-solid`、`--accent-solid-hover` | 主按钮等需要反白文字的强调背景 |
+| `--accent-selected`、`--accent-subtle` | 选中边框、选中背景和信息强调 |
+| `--success`、`--success-subtle` | 成功状态 |
+| `--warning` | 警告状态 |
+| `--danger`、`--danger-strong` | 危险文本和状态 |
+| `--danger-solid` | 最终确认按钮等需要反白文字的危险背景 |
+| `--danger-border`、`--danger-subtle` | 危险入口和失败状态背景 |
+
+浅色与深色具体值只在 `styles.css` 的主题根节点维护。状态组件必须同时显示文字或图标，不能仅靠颜色区分。
+
+表面与边框使用规则：
+
+- 浅色主题的阅读、编辑和页面主内容使用白色或接近白色的 `--surface-raised`；主侧栏使用更深一阶的冰蓝灰 `--surface-canvas`，顶栏使用弱于侧栏的次级表面。相邻区域必须可辨，但不能形成高饱和色块。
+- 深色主题从深海军蓝画布开始，以蓝灰表面逐层提亮。不同层级优先依靠表面亮度与语义边框区分，不使用纯黑底色或无边界的大面积同色区域。
+- 浅色侧栏中，导航与最近会话、最近会话与账户区之间的结构分隔线使用 `--border-default`。列表行之间或卡片内部的弱分隔仍使用 `--border-subtle`，不得为了增强结构而给每一项加重边框。
+- 控件边界、焦点环和选中边框必须达到至少 `3:1` 的非文本对比度；正文、状态色和弱文本分别遵守无障碍对比度要求。
+- 业务组件不得通过主题条件分支写原始颜色；新增视觉层级时先确认能否复用现有表面、边框和状态令牌。
+
+### 3.2 间距令牌
+
+采用 4 像素基准：
+
+| 令牌 | 值 | 典型用途 |
+| --- | --- | --- |
+| `--space-0` | `0` | 显式取消间距 |
+| `--space-1` | `4px` | 图标内部微调 |
+| `--space-2` | `8px` | 紧凑控件、图标与文字 |
+| `--space-3` | `12px` | 表单字段内部、紧凑列表 |
+| `--space-4` | `16px` | 默认组件间距 |
+| `--space-6` | `24px` | 区块间距、窄屏页面内边距 |
+
+使用规则：
+
+- 同一组件内部优先使用 `8px`、`12px`、`16px`。
+- 同一区块内组件之间优先使用 `16px` 或 `24px`。
+- 页面级区块之间优先使用 `32px` 或 `40px`。
+- 不新增 `14px`、`18px`、`22px` 等非令牌间距。
+
+### 3.3 字体令牌
+
+界面英文和数字优先使用随客户端本地打包的 `Inter Variable`。简体中文优先使用平台原生 UI 字体：macOS 使用 `PingFang SC`，Windows 使用 `Microsoft YaHei UI`，以获得与系统渲染匹配的小字号 hinting；其他平台及缺失字形使用本地打包的 `Noto Sans SC Variable`。代码、标识符和原始日志使用等宽字体栈。字体不得通过运行时网络请求加载。
+
+| 令牌 | 字号 / 行高 | 字重 | 用途 |
+| --- | --- | --- | --- |
+| `--font-caption` | `11px` | 时间、短标签和紧凑元数据 |
+| `--font-body` | `13px` | 默认界面正文 |
+| `--font-section-title` | `14px` | 卡片和区块标题 |
+| `--font-page-title` | `24px` | 一级页面标题 |
+
+使用规则：
+
+- 业务组件通过 `--font-family-ui` 与字体尺寸令牌继承字体，不创建页面专属字体栈。
+- 表单按钮、输入框、选择框和文本域必须继承界面字体，避免回退为原生控件字体。
+- 连续阅读内容使用 `14px`，持久辅助信息不得小于 `11px`。
+- 本地兜底字体资源必须随生产包交付，并同时包含 Inter 与 Noto Sans SC 的 OFL 许可证。
+- 页面内不得通过同时放大字号、加粗和使用强调色制造多个同级主标题。
+
+### 3.4 圆角、阴影与层级
+
+| 令牌 | 值 | 用途 |
+| --- | --- | --- |
+| `--radius-control` | `10px` | 输入框、按钮、菜单项 |
+| `--radius-card` | `14px` | 卡片和面板 |
+| `--shadow-card` | 主题定义 | 卡片和选中分段控件 |
+| `--shadow-dialog` | 主题定义 | 对话框和浮层 |
+
+整体使用适度圆角：控件和卡片保持清晰、克制的几何轮廓，不使用胶囊化的大圆角替代信息层级。普通卡片通过表面色和边框区分，不默认添加阴影；输入区等需要从内容流中明确浮起的持续操作面板可以使用克制的 `--shadow-card`。菜单和对话框使用对应层级阴影，阴影只表示真实的浮层关系。不允许页面自行创建高于 `--z-dialog` 的层级。
+
+### 3.5 动效令牌
+
+- `--motion-fast: 120ms`：悬停、按压、焦点反馈。
+- `--motion-normal: 180ms`：菜单、折叠区域、轻量视图切换。
+- `--motion-slow: 240ms`：对话框和抽屉。
+- 默认缓动使用 `ease-out`，退出可使用 `ease-in`。
+- 在 `prefers-reduced-motion: reduce` 下移除非必要位移和缩放，仅保留即时状态切换。
+
+## 4. 页面壳层
+
+所有一级页面使用 `PageShell`。壳层负责水平居中、最大宽度、响应式内边距、页面背景和滚动边界，业务页面不得再次设置独立的整体最大宽度。
+
+| 变体 | 最大内容宽度 | 适用场景 | 页面映射 |
+| --- | --- | --- | --- |
+| `reading` | `820px` | 连续阅读、单列编辑、对话撰写 | 聊天正文与输入区 |
+| `standard` | `960px` | 常规列表、设置与表单 | 最近对话、设置 |
+| `dashboard` | `1040px` | 指标、卡片网格、宽表格与审计数据 | 智能心跳、活动记录 |
+| `master-detail` | 可用空间内流式铺开 | 左侧选择、右侧编辑或预览 | 知识库 |
+
+共同规则：
+
+- 宽度计算统一为 `min(100%, 变体最大宽度)`。
+- 页面左右内边距在常规桌面窗口为 `32px`，中等窗口为 `24px`，窄窗口为 `16px`。
+- 页面顶部和底部内边距默认为 `32px`。
+- `master-detail` 的左栏建议为 `280px` 至 `360px`，右栏占剩余空间。分隔线和滚动容器属于壳层，不由内容卡片模拟。
+- 聊天输入区可以粘附在 `reading` 壳层底部，但消息内容和输入区必须共享同一阅读宽度。
+- 宽表格可在 `dashboard` 内容区内部横向滚动，不得撑宽整个应用窗口。
+
+## 5. 信息层级
+
+一级页面按以下顺序组织：
+
+1. `PageHeader`
+2. `PageTabs`，仅在存在同级子页面时出现
+3. 页面级状态或重要提示
+4. 筛选与批量操作工具栏
+5. 主内容
+6. 与主内容就近关联的分页或加载状态
+
+一个页面只能有一个可见的一级标题。卡片标题不得重复页面标题。面包屑只在层级超过两级且返回关系无法通过侧栏或主从布局表达时使用。
+
+### 5.1 PageHeader
+
+`PageHeader` 统一接收以下内容：
+
+- `title`：必填，简短名词或任务名称。
+- `description`：可选，一行说明当前页面能做什么，不重复标题。
+- `scope`：涉及范围的数据页面必填，使用 `ScopeBadge`。
+- `primaryAction`：可选，页面唯一主操作。
+- `secondaryActions`：可选，最多两个直接显示，其余进入更多菜单。
+- `status`：可选，用于只读、同步中、连接异常等页面级状态。
+
+布局规则：
+
+- 标题和范围徽标在同一信息组中，范围不得放入更多菜单。
+- 主操作位于标题区右侧，窄窗口下换行到标题下方并保持靠左。
+- 不在内容卡片中再次渲染同名标题。
+- 标题区默认不粘附。只有主内容长且页面级操作需要持续可用时才启用粘附。
+
+## 6. 共享组件
+
+### 6.1 PageTabs
+
+用于同一一级页面内的同级内容面板，例如智能心跳的“运行概览”和“心跳计划”。
+
+- 使用 `tablist`、`tab` 和 `tabpanel` 语义，当前项使用 `aria-selected="true"`。
+- 一级页面之间的导航由应用主导航承担，不复用 `PageTabs`。
+- 标签保持短名词，不显示句号，不用页签承载开关或过滤条件。
+- 项目过多时优先重组信息架构，不把一级页签做成多行。
+- `PageTabs` 可使用默认视觉或共享的 `segmented` 视觉变体。紧凑主从工作台中的 2 至 4 个同级面板可使用与模型设置一致的分段外观，但不得因此改用按钮组语义。
+- 视觉变体不改变组件含义：分段外观的 `PageTabs` 仍使用页签语义、单一激活面板、游标焦点和方向键切换，不复制页面专属样式。
+- 在独立滚动的 Flex 页面中，`PageTabs` 及其直接包装层必须保持 `flex: 0 0 auto`，不得被剩余内容压缩到零高度。新增页签容器时必须提供对应的 CSS 回归测试。
+
+### 6.2 SegmentedControl
+
+用于当前页面内互斥的视图或状态切换，例如“列表 / 网格”或少量单选状态。
+
+- 选项数量为 2 至 4 个。
+- 使用带 `aria-pressed` 的按钮组语义，支持方向键切换。
+- 不能用于多选筛选、页面导航或执行即时命令。
+- 控件宽度由内容决定，除移动窄屏外不默认等分整行。
+
+### 6.3 筛选工具栏
+
+筛选不创建第五种类似页签的视觉控件：
+
+- 2 至 4 个互斥状态可使用 `SegmentedControl`。
+- 多维条件使用统一尺寸的选择框、搜索框和复选菜单。
+- 已生效条件以文字和值明确展示，并提供“清除筛选”。
+- 无匹配结果使用“无结果”状态，不能显示为首次使用的空状态。
+- 筛选条件改变数据范围时，结果数量或当前条件必须可见。
+
+### 6.4 ScopeBadge
+
+`ScopeBadge` 表达对象或页面数据的归属范围：
+
+- 全局范围显示“全局”，并配合通用范围图标。
+- 项目范围显示“项目：项目名称”，不得只显示项目名称。
+- 未知或已失效范围显示“范围不可用”，并提供修复入口或只读说明。
+- 徽标始终包含文字，不以颜色作为唯一差异。
+- 可切换范围时，徽标作为范围选择器的触发器，并提供明确的展开状态和键盘操作。
+- 不可切换范围时，徽标为只读状态，不显示下拉箭头。
+
+创建新对象时必须在提交按钮附近再次显示目标范围。跨范围移动属于显式操作，需要说明原范围、目标范围和对关联数据的影响。
+
+### 6.5 EmptyState
+
+`EmptyState` 统一包含：
+
+- 能说明状态的图标或简洁插图。
+- 一句标题。
+- 一至两句原因或下一步说明。
+- 最多一个主操作和一个次操作。
+
+必须区分：
+
+| 状态 | 标题示例 | 操作原则 |
+| --- | --- | --- |
+| 首次为空 | “还没有知识条目” | 提供创建或导入 |
+| 筛选无结果 | “没有符合条件的结果” | 提供清除筛选 |
+| 搜索无结果 | “未找到相关内容” | 建议修改关键词 |
+| 加载失败 | “内容加载失败” | 提供重试并保留错误上下文 |
+| 无权限或只读 | “当前范围不可编辑” | 说明原因和可行路径 |
+
+空状态不得使用孤立的短句或仅显示图标。加载中不得先闪现空状态。
+
+### 6.6 危险操作
+
+共享危险操作样式包含：
+
+- `danger-ghost`：列表行、菜单和工具栏中的删除入口。
+- `danger-solid`：确认对话框中的最终危险操作。
+- `danger-zone`：设置页中集中展示的高影响操作区域。
+
+普通页面不得用实心红色按钮与主操作并列。危险入口必须使用具体动词和对象，例如“删除知识条目”，避免只写“确定”。
+
+### 6.7 数据表格与活动列表
+
+- 表头、单元格、空值、状态和行操作使用统一对齐规则。
+- 文本默认左对齐，数值右对齐，状态与短标签可居中。
+- 时间显示使用一致格式，并在需要时通过工具提示提供完整时间和时区。
+- 行操作默认放在行末。高频安全操作可直接显示，低频或危险操作进入更多菜单。
+- 活动记录必须保留操作者、动作、对象、范围、结果和时间等审计语义，不用纯图标代替关键字段。
+- 表格密度可以选择“默认”或“紧凑”，但同一页面不得混用。
+
+### 6.8 应用侧栏
+
+主侧栏用于一级导航、最近会话和稳定的账户入口，必须通过表面、结构线和选中状态建立清楚但不过度装饰的层级。
+
+- 浅色侧栏使用冰蓝灰表面，与白色主内容画布形成明确边界；深色侧栏使用比主画布略亮的蓝灰表面。
+- 一级导航与最近会话之间、最近会话与底部账户区之间必须有可见结构分隔线。浅色主题使用 `--border-default`，深色主题可在可辨前提下使用 `--border-subtle`。
+- 当前导航项和当前会话必须同时使用至少三种信号中的两种：强调背景、可见边框、图标或文字强调。浅色主题的当前项优先使用更完整的蓝色选中表面和较高字重。
+- 未选中项保持平整，不为每一行添加卡片边框或阴影。悬停反馈不得强于选中状态。
+- 桌面停靠状态下，主侧栏宽度允许在 `220px` 至 `420px` 范围内通过指针或键盘调整，
+  并记住用户选择；分隔条使用 `separator` 语义，支持方向键、Home 和 End。小于
+  `900px` 时继续使用固定宽度抽屉，不显示拖拽分隔条。
+- 关联 Task 的 Conversation 在行最左侧显示独立展开按钮，父会话行不重复任务标签或数量；
+  展开后的每个 Task 子项左侧显示名称，模式、计划和共享状态标记收在右侧，与父会话的
+  更新时间位置一致；展开层级只到 Task，不展示 Job、Subjob 或 Run。
+- 会话标题保持单行且不挤压更新时间。更新时间默认靠近行右侧；低频的更多操作按钮不常驻
+  占位，只在悬停会话行时替换右侧时间显示。键盘焦点进入会话行或操作菜单展开时，按钮仍
+  保持可见。标题实际溢出时，悬停会话行才在标题的固定裁切区域内平滑横向滑动以展示完整
+  名称；移开后快速复位。未溢出标题不产生位移动效，`prefers-reduced-motion` 下禁用滑动
+  并保留完整标题提示。
+- 分支会话在侧栏标题前和聊天顶栏标题旁显示同一个横向分叉徽标；徽标通过可访问名称和
+  工具提示说明来源会话，不能只靠图形表达。分支不改成树状会话列表，也不挤压更新时间。
+- 新建 Task 后可以首次自动展开所属 Conversation；用户手动折叠后保持其选择，后台状态变化
+  只更新状态提示，不强制展开或抢占焦点。
+- Task 子项右侧复用任务中心的共享状态标记：运行中使用脉冲强调色，已完成使用带勾成功点，
+  失败或中断使用危险色，等待审批使用警告色，暂停或取消使用禁用色；非完成态旁边同时
+  显示本地化状态文字，已完成文案保留给辅助技术而不在紧凑元数据中重复显示，不能只靠
+  颜色或动效表达状态。
+- 左上角品牌区允许用户在“外观”设置中定制品牌名称、中英文副标题和单个 Logo。定制只
+  影响该品牌区，不替换安装包名称、更新协议、Agent 标识或应用正文中的 GoodBuddy 产品
+  身份。副标题按当前界面语言显示，留空时隐藏且不保留空行。
+- 品牌设置必须提供同布局预览、显式保存、默认 Logo 和整组恢复默认操作。自定义 Logo 仅
+  接受用户本机选择的 PNG、JPEG 或 WebP 内联数据，宽高不超过 `4096 × 4096`、总像素不
+  超过 1600 万且大小不超过 `512 KB`；不得读取远程 Logo URL。名称或副标题溢出品牌区时
+  单行截断，不能撑宽或挤压侧栏。
+- 侧栏底部固定显示文件、终端、浏览器和资源监控四个系统工具图标，设置按钮独立靠右。工具
+  图标只负责打开或聚焦助手工作栏面板，不在侧栏复制工具内容。已有稳定设置入口时，不在顶栏
+  重复提供同一入口。
+
+### 6.9 助手工作栏
+
+助手工作栏是应用级右侧工具容器，不归属于聊天页面，也不根据当前页面、项目或 Runtime
+自动增删入口。产品契约见
+[通用助手工作栏与执行空间 PRD](./docs/features/assistant-workbar/prd.md)，
+动态 Tab、“+”和终端细节见
+[助手工作栏多终端页签 PRD](./docs/features/assistant-workbar/terminal-tabs-prd.md)。
+
+- 升级后默认打开任务中心、工作区、一个浏览器实例和成果。任务中心与工作区是不可关闭的
+  单实例基础应用；浏览器是可关闭的多实例应用；成果保持可关闭的单实例应用。不可关闭不
+  等于锁定顺序。
+- 资源监控作为本机单实例应用保留在能力目录，但不加入升级后的默认打开实例。面板只在可见
+  活动时采样，首期不持久化历史或提供后台负载告警。
+- Tab 行只显示已打开实例，行末始终提供“+”普通按钮；点击后在内容区打开应用选择页。
+  “+”不使用 `tab` 语义，也不能因为终端或其他应用已经打开而消失。
+- 应用注册表分别声明单实例或多实例、默认打开、必须存在、可关闭和排序策略。在工作栏“+”目录中，
+  单实例重复选择时聚焦已有 Tab；浏览器和终端每次选择创建独立实例。主侧栏系统工具快捷
+  入口按当前上下文聚焦最近使用的匹配实例，额外实例仍从“+”目录创建。
+- Task Center 是默认跟随当前项目的单实例索引，不使用多实例模式。用户可在同一 Tab 内切换
+  “当前项目”“全局任务”和“全部项目”；范围变化不得创建第二个 Task Center。每个 Task 只
+  关联一条 Conversation，一条 Conversation 可以关联多个 Task；列表不得复制会话内容，也
+  不得把 Job/Run 提升为可导航 UI 对象。
+- 各栏目读取当前会话或项目的对应内容；当前内容不可用时仍保留栏目入口并说明原因。
+- 能力、连接和内容可以动态变化，栏目入口不能随之自动隐藏。不可用状态必须说明原因、影响和可执行入口。
+- 用户可以主动排序栏目，并可关闭可关闭实例或恢复默认布局；任务中心和工作区不能隐藏或
+  关闭。应用不能用用户偏好机制实现自动能力裁剪。
+- 已打开实例保留 `tablist`、`tab`、`tabpanel`、方向键、Home、End 和焦点恢复语义。
+  实例过多时 Tab 区单行横向滚动，“+”保持可见，不换行或改成下拉框。不可关闭实例不渲染
+  关闭按钮，也不响应关闭快捷命令。
+- 当前工作栏 Tab 必须同时使用连续内容表面、可见边框、顶部指示、图标或较高字重中的至少
+  两种信号；悬停反馈不得强于当前选中态。Tab 关闭按钮保留固定布局空间，默认仅在对应 Tab 悬停或
+  `focus-within` 时显示；无悬停或粗指针设备始终显示，键盘与辅助技术始终可访问。
+- 工作栏 Tab、Tab 关闭按钮和“+”入口沿用共享控件圆角；终端面板外框及终端顶部工具栏按钮
+  使用直角，形成紧凑的停靠式终端界面。
+- 选择“终端”后直接绑定当前项目，由项目执行空间自动决定本机或托管 SSH；不再显示第二层
+  目标选择器。终端面板内部不重复提供关闭会话按钮，关闭统一由 Tab 入口完成。
+- 下一次请求使用的附件和知识库由会话输入区展示与管理，不在工作栏重复提供“上下文”栏目；
+  记忆功能实现前不展示占位内容，未来的记忆与历史执行上下文归入关联 Task 的任务中心详情。
+- 徽标可以提示未解决意见、等待审批、失败或连接状态，但不能成为唯一状态信号，也不能无条件抢占当前栏目。
+- 浏览器 Tab 的内容顶部固定使用一条紧凑工具栏，按“返回、刷新/停止加载、地址输入、
+  前往、交互、关闭浏览器”排列。“刷新”在当前页面加载时原位切换为“停止加载”；
+  “关闭浏览器”必须使用明确文字和与页面导航控件清楚区分的危险操作视觉，不能继续标为
+  含义模糊的“停止浏览器”。地址输入显示浏览器权威提交 URL，但用户编辑期间保留本地草稿，
+  不被画面或状态刷新覆盖；提交裸域名时自动添加 `http://`，提交、失焦后的同步规则不得让
+  尚未提交的文字改变 Agent 看到的页面。
+- 浏览器工具栏操作的是该实例绑定的 Conversation 和 Browser Tab。同一 Conversation 的多个
+  Tab 共享隔离登录上下文，但页面、导航、操作队列和元素引用相互独立。模型请求开始时冻结
+  工具目标，用户切换工作栏 Tab 不改变进行中的 Agent 操作。创建中、Agent 操作中或已进入完整交互窗口时禁用其余
+  工具栏控件；仅当前导航仍在加载时保留“停止加载”，且该操作只中止页面加载，不关闭浏览器、
+  不释放 Runtime 上下文。没有会话的活动 Conversation 可以直接在地址栏输入 URL 并“前往”
+  创建会话，但必须复用 Agent 浏览器相同的 URL 策略与能力路径。
+- 所有窗口宽度下均停靠在主工作区右侧并参与水平布局回流；展开时压缩主工作区，不能覆盖、
+  遮罩或隔离其内容。分栏计算排除最左侧主导航，主工作区与工作栏采用相同的 `300px`
+  最小宽度；拖动保存两者在可用分栏宽度中的比例，任一侧到达最小值后都不得继续侵占。
+  所有可容纳两侧最小值的尺寸均支持指针和键盘调整，并须保留全部栏目入口。
+- 工作栏开关固定在窗口关闭按钮正下方，同一个按钮负责展开与收起并持续暴露状态；图标中的
+  箭头方向必须随当前动作切换，收起状态提示展开，展开状态提示收起。按钮保持普通图标按钮
+  视觉，不通过持续高亮表达展开状态。工作栏内部不再重复关闭按钮；当前会话没有 Task 时，
+  不得为了放置该开关而保留一条空上下文栏。
+- 停靠工作栏不得获得对话框语义、焦点陷阱或背景遮罩。关闭后焦点返回同一个工作栏开关；
+  主工作区与工作栏在展开期间都保持可达。
+- 对话消息流、输入区和输入区元信息必须在主工作区内部保留对称的左右安全边距。工作栏
+  分割线只能位于主工作区边界之外，不能覆盖、裁切或挤掉输入框边框、发送按钮或右侧边距。
+- 终端、宽日志和大型成果可以由用户切换到底部停靠或独立窗口，应用不得因内容变化自动改变用户已选布局。
+
+### 6.10 应用顶栏与全局操作
+
+应用顶栏用于当前会话标题、范围、窗口级状态、侧栏开关和低频全局操作，不承担主要导航。
+顶栏必须保持紧凑，不能与页面内容争夺注意力。
+
+- 应用壳层在水平方向分为全高主侧栏和右侧内容框架。主侧栏从窗口顶部贯穿到底部，品牌区、
+  项目切换器、导航和账户区保持同一连续表面；不能用全宽标题栏把整条侧栏向下推移。
+- 无边框窗口的紧凑标题栏只覆盖右侧内容框架，保留侧栏开关、当前会话标题、范围、Runtime
+  状态、主题开关和窗口控制，不得为了新增工作栏入口把这一整组控件下移。普通图标按钮使用
+  `34px × 34px` 点击区域。
+- 发布说明 Modal 与其他应用级 Modal 一样使用整窗遮罩；遮罩必须覆盖主侧栏、右侧内容和
+  顶栏，不能保留一条未被遮罩的窗口控制色块。关闭操作由 Modal 自身提供。
+- 当前会话存在 Task 时，Task 上下文栏位于标题栏下方并承载任务摘要与详情；没有 Task 时
+  整行隐藏。折叠状态保持为 `46px` 单行表面，与右侧工作栏标签栏等高，左右分隔线必须水平
+  对齐。该栏不重复放置新建入口。
+- “新建任务”只位于工作栏“任务索引”标题后方；任务状态筛选占满工作栏可用宽度，四个选项
+  等分，不能保留内容宽度的短控件。
+- Runtime 状态、同步状态等短标签使用 `--font-caption`，不得放大为正文标题。顶栏 Runtime
+  状态由状态点和 Runtime/模型名称紧凑表达：就绪使用绿色，连接中使用黄色，不可用使用灰色，
+  不再重复显示状态文字；完整状态详情继续通过可访问说明和工具提示提供。
+- 浅色与深色切换属于持续可用的窗口级操作，直接显示太阳或月亮图标，并通过可访问名称说明将切换到的主题。选择必须持久化，切换不得改变布局。
+- 顶栏只直接显示当前任务所需的高频操作。已有侧栏账户设置入口时，不再重复显示 Runtime/设置入口；使用帮助优先放在相关操作附近，而不是为单个帮助项创建“更多”菜单。
+- 助手工作栏开关固定在上下文栏最右侧并与窗口关闭按钮纵向对齐；展开后该开关保持原位并
+  负责收起，不在工作栏标题区域增加第二个关闭入口。
+- 只有存在至少两个无法由稳定入口承载的低频全局操作时才增加全局菜单，不为了容纳一个冗余入口而显示省略号按钮。
+- 窄窗口下优先压缩状态标签并保留图标按钮，不隐藏窗口控制、当前范围或进行中的风险状态。
+- 使用全局菜单时，菜单项使用 `--font-body`、`14px` 图标和约 `32px` 单项高度；标签使用短名称。菜单保留 `menu`、`menuitem` 语义，支持上下方向键、Home、End 和 Escape，关闭后焦点返回触发按钮。
+
+### 6.11 单选选择器
+
+模型、专家角色、工作模式、Runtime Agent、Runtime 预设和 Runtime 快捷操作属于同一输入上下文，其选择器必须共享结构、尺寸和菜单视觉，不能出现一个精细菜单与多个风格不一致的原生下拉框。
+
+- 只有选项能由单行短标签充分区分、不需要补充来源、位置、状态或说明时，才使用原生 `select`。
+- 当用户必须在选择前比较来源、范围、位置、连接状态或其他辅助信息时，使用与输入区选择器同类的自定义富信息单选菜单，不用 CSS 修饰原生 `select` 冒充富信息菜单。
+- 触发按钮复用统一的模型选择按钮样式，保持相同高度、圆角、边框、展开指示和焦点状态。
+- 菜单使用 `menu` 与 `menuitemradio` 语义，当前项同时显示选中标记和 `aria-checked`。选项可以包含一行简短说明，但标签和说明不得被截断到无法区分。
+- 支持上、下方向键、Home、End、Enter 或 Space、Escape；打开后焦点进入当前项，关闭后返回触发按钮。
+- 点击或聚焦菜单外部时关闭；同一输入区内的模型、专家和模式菜单互斥展开。
+- 不可用选项保持可读并说明原因，键盘导航不得停留在不可选择项上。
+- 当某个选项需要用户在其展开区域内完成路径选择、授权或其他前置操作时，不得因为前置条件
+  尚未完成而禁用该入口。选择入口只展开流程，验证成功前不提交实际值；不得自动采用第一个
+  候选。取消保持原值，验证错误在对应操作附近显示。
+- 项目选择器属于富信息单选菜单。收起时保持当前项目名称紧凑可见；展开后每项至少显示项目名称，并按数据可用性补充目录、远程来源或其他能帮助辨认项目的信息。托管 SSH 项目在“远程项目”内按已保存 SSH Host 做一层轻量分组，Host 标题旁显示真实 Agent 连接状态；项目副标题只显示远端路径，不重复“托管 SSH”类型。
+- 项目菜单区分“本地项目 / 远程项目 / 远程通道”，不把消息通道命名为远程项目。“远程项目（技术预览）”关闭时完整移除远程项目分组，而不是显示不可操作的残留选项；本地项目和远程通道继续可用。Agent 连接状态使用“未连接 / 连接中 / 就绪 / 异常”等文字标签，读取状态不得发起连接，且不能只依赖图标或颜色；新增项目来源时不得退回仅列名称的原生 `select`。
+
+### 6.12 应用通知与就地反馈
+
+应用级通知统一进入全局通知视口，页面不得自行复制通知卡片或在内容流中长期堆放短期消息。
+
+- 异步操作成功、无需立即处理的信息，以及不属于某个字段的异步失败，使用应用级 `success`、`info` 或 `error` 通知。
+- 成功和信息通知默认在约 4.5 秒后自动消失；错误通知保持可见，直到用户关闭或同一去重键的更新替换它。
+- 同一语义和文案的重复通知应去重。通知正文必须有长度上限，不包含凭据、私人内容或未脱敏的提供商响应。
+- 字段校验、破坏性确认、操作进度、阻塞整个页面的状态，以及需要就地重试或修正的错误保留在相关控件附近。
+- 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 `alert` 和 assertive 实时区域，成功与信息使用 `status` 和 polite 实时区域。
+- 一个事件只能选择一种主要反馈位置，不得同时显示页内横幅和全局通知。失败时不得因通知切换而清空用户输入、筛选或未提交草稿。
+
+### 6.13 Switch 与 Checkbox
+
+Switch 用于在两个持久状态之间立即切换，例如启用能力、开启索引、允许群消息或显示平台入口。Checkbox 用于独立多选、范围分配或执行前确认，例如选择多个 Runtime、选择知识库、清除已保存密钥。两者不得只因底层都使用 `input[type="checkbox"]` 而混用视觉或语义。
+
+- 二元启停必须使用共享滑动开关视觉，当前实现复用 `toggle-row`，不得显示为原生方形 Checkbox。
+- Switch 底层可以使用 `input[type="checkbox"]`，但必须声明 `role="switch"`，通过原生 `checked` 状态暴露开关状态，并具有持久、明确的可访问名称。
+- Checkbox 保留原生 Checkbox 语义和方形勾选视觉，不得添加 `role="switch"`。多项分配、列表选择、确认声明和“保存时清除密钥”等一次性选择均属于 Checkbox。
+- 不创建页面专属 Switch 样式。需要紧凑布局时仍复用同一轨道、滑块、焦点环、禁用状态和动效，只调整共享组件支持的布局变体。
+- Switch 支持 Tab 聚焦和 Space 切换，键盘焦点至少显示 `2px` 高对比焦点环。可见标签应描述被控制的能力，不能只显示“开 / 关”。
+- 异步切换期间禁用重复操作并保留原状态。失败时恢复或保留最后确认状态，通过应用通知或就地可恢复错误说明原因。
+- 涉及联网、上传、电脑控制或其他外部影响的 Switch，附近必须持续说明数据去向、权限范围或风险，不能只靠设置名称表达影响。
+- 自动化测试应按 `switch` 角色查询二元开关，按 `checkbox` 角色查询多选或确认项，防止视觉迁移后语义回退。
+
+## 7. 交互状态
+
+所有可交互组件必须实现：
+
+- 默认：文本、边框和背景层级清晰。
+- 悬停：提供轻量背景或边框反馈，不改变布局。
+- 按下：反馈比悬停更强，持续时间使用 `--motion-fast`。
+- 键盘焦点：显示至少 `2px` 的高对比焦点环，不被容器裁切。
+- 选中：同时使用背景、边框、图标或字重中的至少两种信号。
+- 禁用：降低强调度，同时保留可读标签，并通过说明或工具提示解释原因。
+- 加载：防止重复提交，保留原按钮宽度并显示进行中标签。
+- 错误：字段或局部操作错误就近显示可执行说明；非局部异步错误使用不会自动消失的应用级错误通知。
+
+异步提交成功后更新内容并通过统一应用通知提供明确反馈。失败时保留用户输入和筛选上下文。
+
+## 8. 范围与数据语义
+
+### 8.1 页面范围
+
+- 页面范围决定当前列表、搜索、创建和批量操作针对的数据集合。
+- 页面标题区必须持续显示当前范围。
+- 搜索框占位文案应反映范围，例如“搜索当前项目的知识”。
+- 切换范围后清理不再有效的选择项，并明确提示数据集合已变化。
+
+### 8.2 对象范围
+
+- 详情页或主从布局的右侧面板显示所选对象自身的范围。
+- 当页面范围与对象范围不一致时，必须显示解释，不得静默混合。
+- 全局对象可被项目引用时，应分别表达“归属范围”和“当前引用关系”。
+
+### 8.3 操作范围
+
+批量操作、导入、删除、移动和自动化运行前，界面必须明确：
+
+1. 将影响哪些对象。
+2. 对象属于全局还是某个项目。
+3. 操作是否可撤销。
+4. 是否影响关联任务、知识引用或历史记录。
+
+## 9. 破坏性操作政策
+
+### 9.1 风险等级
+
+| 等级 | 示例 | 要求 |
+| --- | --- | --- |
+| 低 | 移除可立即恢复的筛选、取消未保存草稿 | 通常无需确认，必要时提供撤销 |
+| 中 | 删除单个可恢复对象、停止正在运行的任务 | 显式确认或操作后撤销，说明直接影响 |
+| 高 | 永久删除、批量删除、清空历史、删除被引用对象 | 必须使用确认对话框，说明范围、数量和不可逆性 |
+
+### 9.2 确认对话框
+
+- 标题包含具体动作和对象，例如“永久删除 12 条活动记录？”
+- 正文说明范围、关联影响和恢复可能性。
+- 取消按钮在前，危险按钮在后。初始焦点放在取消按钮。
+- 最终按钮使用 `danger-solid`，标签重复具体动作。
+- 仅对高影响且不可恢复的操作要求输入对象名称或确认短语，避免把摩擦用于所有删除。
+- 提交期间锁定重复操作。失败后保持对话框打开并显示可处理的错误信息。
+
+### 9.3 撤销与反馈
+
+- 可恢复删除优先在操作后显示带“撤销”的持久通知。
+- 撤销窗口结束前，不把操作描述为“永久删除”。
+- 删除成功后更新列表、选中项和计数。主从布局中被删除对象的详情面板应回到明确的未选择状态。
+- 审计记录不得因普通对象删除而被静默移除。
+
+## 10. 深色主题
+
+- 深色主题通过语义令牌替换实现，不在组件中使用主题条件分支选择原始颜色。
+- 主画布使用深海军蓝，侧栏、顶栏、输入区和浮层使用逐级提亮的蓝灰表面；表面层级主要依靠亮度和边框区分，避免大面积纯黑与高亮白形成刺眼对比。
+- 深色强调色使用明亮但不荧光的蓝色，成功状态使用青绿色。用户消息等大面积强调表面使用更深的实心蓝，确保反白文字舒适可读。
+- 输入框、代码块、表格悬停、选中行、弹窗遮罩和滚动条必须分别检查深色值。
+- 图片、图表和状态色在深色背景下保持可读。图表系列不能只靠色相区分，还应使用形状、线型或标签。
+- 焦点环、危险文本和弱文本在两种主题下都满足对比度要求。
+- 原生控件和滚动条声明正确的 `color-scheme`。
+- 主题切换不得导致布局、边框宽度或字号变化。
+
+## 11. 无障碍
+
+### 11.1 键盘与焦点
+
+- 所有交互均可通过键盘完成。
+- 焦点顺序与视觉顺序一致，打开弹窗后焦点进入弹窗，关闭后返回触发元素。
+- 页面导航链接按正常 Tab 顺序操作。同页签组和单选组使用方向键，菜单使用上下方向键和 Escape。
+- 不给不可交互容器添加焦点，不用 `div` 模拟按钮而缺少按钮语义。
+
+### 11.2 语义与标签
+
+- 图标按钮必须有可访问名称，并在视觉上提供工具提示。
+- 表单控件有持久标签，不能只使用占位文案。
+- 状态变化使用适当的实时区域，但避免对频繁日志逐条播报。
+- 错误信息与对应字段建立程序化关联。
+- 表格使用正确的表头关系，复杂审计记录在窄屏下仍保持字段标签。
+
+### 11.3 对比度与触控目标
+
+- 正文与背景对比度至少为 `4.5:1`，大号文本至少为 `3:1`。
+- 控件边界、焦点和关键图形对比度至少为 `3:1`。
+- 常规交互目标建议至少 `32px × 32px`。紧凑表格可使用 `28px` 高度，但相邻目标之间必须有足够间隔。
+- 文字缩放至 `200%` 时，核心操作、范围信息和错误提示不能被裁切。
+
+## 12. 响应式与窗口规则
+
+GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证任务连续性，不简单隐藏信息。
+
+### 12.1 宽窗口，`1200px` 及以上
+
+- 使用各 `PageShell` 的完整最大宽度。
+- `dashboard` 可使用 3 至 4 列卡片。
+- `master-detail` 保持双栏，详情区获得主要空间。
+
+### 12.2 中等窗口，`960px` 至 `1199px`
+
+- 页面左右内边距为 `24px`。
+- 仪表盘降为 2 列。
+- 主从布局缩小左栏，但不得低于 `280px`。
+- 表格优先收起低优先级列到详情或行展开区，不隐藏范围、状态和时间。
+
+### 12.3 窄窗口，`720px` 至 `959px`
+
+- `PageHeader` 的操作区换行。
+- `master-detail` 变为单面板导航。进入详情后提供明确返回列表的按钮。
+- 仪表盘使用单列或 2 列，取决于卡片最小宽度。
+- `PageTabs` 可单行横向滚动，不换成下拉菜单。
+- 宽表格在自身容器内横向滚动，并固定关键标识列时确保键盘可达。
+
+### 12.4 极窄窗口，小于 `720px`
+
+- 页面左右内边距为 `16px`。
+- 标题、范围徽标和操作纵向排列，但范围不得隐藏。
+- 主操作可以占满可用宽度，次操作进入更多菜单。
+- 分段控件可等分整行，筛选工具栏改为可展开区域。
+- 聊天输入区保持可见，并考虑窗口安全边距。
+- 对话框使用接近全宽的布局，仍保留 `16px` 外边距。
+
+## 13. 页面应用规范
+
+### 13.1 聊天
+
+- 使用 `reading` 壳层，消息流与输入区共享宽度。
+- 消息头像放在正文区域外侧：助手头像居左，用户头像居右。输入框左边缘与助手正文左边缘对齐，
+  右边缘与用户气泡右边缘对齐；两侧为头像保留独立安全边距，滚动条出现或工作栏缩放不得改变对齐。
+- 对话标题和当前项目范围位于 `PageHeader` 或对话上下文区，不在消息流中重复。
+- 已结束且包含正文的助手回复在底部提供带可访问名称和工具提示的复制图标；复制 Markdown
+  原文，不包含推理过程、工具日志或引用元数据，结果通过应用通知反馈。流式回复完成前不显示
+  复制入口。
+- 默认开启“会话 HTML 渲染”时，已完成 Agent 回复中的完整 HTML 与 `html` / `htm`
+  代码块在原位置显示隔离静态预览；用户消息、推理过程和流式中的回复不得执行 HTML。
+  每个预览持续标注脚本和网络已禁用，并在标题右侧复用与 Mermaid 图表相同的图标按钮组：
+  源码按钮使用代码图标并暴露 `aria-expanded`，全屏按钮使用放大图标打开统一 Modal。
+  全屏预览遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape 关闭和焦点恢复规则，
+  并沿用同一套清理与 Sandbox/CSP 边界。关闭平台功能后必须显示 HTML 源码，不能隐藏内容
+  或保留旧预览。
+- 本地会话的更多操作提供“在新会话中继续”。创建前必须先持久化当前稳定消息；有活动运行
+  或待发送内容时不可创建。新会话复制聊天内容与当前 Runtime/知识检索选择，重置压缩状态，
+  使用新的会话和消息 ID，且不复制 Task、队列、运行、记忆或成果归属。
+- 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。
+- 模型、专家角色、工作模式、OpenCode Agent、Continue 预设和 Runtime 快捷操作使用统一的上下文单选菜单，并保持菜单互斥、键盘可达和选中状态明确。
+- Runtime 选择菜单必须反映当前执行空间的真实能力。托管 SSH 项目当前只支持 OpenCode，因此输入区只渲染已配置的 OpenCode 选项和管理入口，不显示直连模型、Continue 或 DeepSeek Harness 的不可用入口；旧会话保存的其他 Runtime 选择在项目激活时恢复为当前 OpenCode 配置。
+- 输入区第一行工具栏只承载附件、语音、知识范围、专家角色、工作模式、Runtime 选择和发送等通用操作。OpenCode Agent、Continue 预设及 Runtime 快捷操作必须放入其下方独立的 Runtime 专属功能行，通过可见分组名称、顶部边界和差异化表面与通用操作分层；该行只承载对当前消息生效的高频选择，当前 Runtime 没有可选专属功能时不保留空行。
+- OpenCode、Continue 和 DeepSeek Harness 后续的 Task 级委派与取消、后台执行进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止及原生会话监督统一进入应用级助手工作栏固定的“Runtime”栏目，不加入 Composer。栏目入口始终存在；只选择 Conversation 或 Task，并按 Task 聚合执行状态，不显示 Job/Run 树或独立操作菜单。内部可选区域按用户所选目标和 Runtime 的真实能力显示，不为未支持能力渲染空卡片或成排禁用按钮。切换跟随目标时必须清理上一归属的监督状态，固定目标则保持不变。
+- 设置中心只管理持久 Runtime 配置、默认值和能力清单；右侧 Runtime 栏目管理用户当前跟随或固定目标的生命周期。两处不得复制同一实时操作，栏目中的高风险操作仍须就地确认并保留取消、权限、用量和活动审计。
+- Runtime Prompt 快捷操作只把模板填入输入草稿，用户可以继续编辑；OpenCode Command 由 Runtime 原生 API 执行，输入框只承载可选参数，不以普通斜杠文本冒充执行。
+- OpenCode 原生 Task 调用在本地项目和托管 SSH 项目中统一解析为子 Agent 状态卡，不显示为普通工具卡。状态卡持续显示 Agent 类型、任务说明、运行状态、完成输出或失败原因；身份徽标、Agent 名称和状态位于首层，任务说明作为主信息，Runtime 来源作为次级元数据，输出与错误在同一卡片内按需展开。父 Agent 的推理不冒充子 Agent 过程，必须与状态卡保持明确间距。状态不能只靠颜色表达。推理、子 Agent、工具和正文统一按事件首次出现顺序进入消息块；增量更新只更新原位置，Task 临时工具块重分类后必须原位替换，不能把子 Agent 卡统一提升到消息顶部。同一调用的增量事件按稳定调用 ID 更新，不能因 ACP 首帧尚无参数而永久保留重复工具卡或活动记录。一次请求内已观察到的子 Agent 均保留在消息与活动记录中；父请求取消、失败或意外中断时仍处于活动状态的卡片必须结算为对应终态，父请求成功结束但子 Agent 未报告终态时必须显示为失败而不是推断为完成。
+- Agent 回复进行中锁定模型、专家角色、工作模式和 Runtime 定制选择器，并关闭已打开的上下文菜单；回复结束或停止后再恢复选择，避免界面状态与本次运行实际使用的上下文不一致。
+- Agent 回复进行中不能禁用普通消息发送。新消息与到期 Scheduled Task 共用 Conversation 级待发送队列。队列位于 Composer 容器之外、与输入框等宽并保持独立间距；有待发送项时直接显示无标题栏的极简列表，空队列不保留占位。每项固定为一行，按进入顺序显示轻量来源图标和截断摘要；普通消息使用消息图标，Scheduled Task 统一使用淡出时钟图标。
+- 待发送项默认在当前回复结束后顺序执行。每项提供明确的“立即中断并插入”（空闲时为“立即运行”）和删除操作；前者先取消当前 Conversation 的活动执行，再将所选项提升为下一项，不允许同一 Conversation 并发写入时间线。
+- 队列区域向上增长并设置有界滚动高度，不提供展开、收起或冗余计数标题。宽容器中的操作采用弱化的行内样式，不渲染成强调卡片或胶囊；窄容器中保留来源、摘要和图标操作并隐藏冗长按钮文字。区域、来源和每个操作必须有可读无障碍名称。队列异步错误进入应用通知，不在 Composer 内复制通知样式。
+- 支持上下文状态的 Runtime 在输入区下方复用同一紧凑用量条；文案必须区分“本次模型调用”和“压缩后对话估算”。手动压缩仅在当前 Runtime 明确支持且没有活动回复时显示，作为元信息区左下角的浮动次操作，不参与输入区高度计算；元信息区始终预留稳定高度，切换 Runtime 不得让输入框上下位移。元信息区与窗口底部只保留紧凑安全留白，不形成额外空白区。进行中禁用重复操作，结果通过应用通知反馈。
+- 已选择的工作模式在触发按钮中只显示 `Ask` 或 `Execute`；完整中文含义和说明保留在菜单选项、可访问名称及输入区下方的模式说明中。
+- 宽度大于 `700px` 时，通用工具栏内的添加内容、知识范围、专家、模式和 Runtime 选择保持同一行，Runtime 专属功能在自己的下一行横向排列。窄输入区中两行分别换行，专属选择器以至少 `220px` 的基准宽度换行而不是被挤压；不能把专属控件重新塞回通用工具栏。
+- 输入框原生支持 `Ctrl+V`：文本直接进入草稿，图片转换为本次消息附件。文件选择由上传按钮承担，不再提供独立“读取剪贴板”按钮；默认工具栏也不提供“截取当前屏幕”和“选择应用窗口”入口，避免与系统粘贴、文件选择和后续工具执行重复。
+- “Enter 发送 · Shift+Enter 换行 · Ctrl+V 粘贴图片或文本”等输入操作提示放在空输入框内部，作为主占位文案的次级行；不得在输入框下方单独占用第二行。输入框下方只保留一行当前模式、安全边界或全局快捷键说明。
+- 输入操作提示不能替代表单的可访问名称，输入框始终保留持久的程序化标签。
+- 空对话展示可执行的起始建议，发送失败保留输入并提供重试。
+- 消息流的滚动范围必须使用已渲染消息的真实高度。长会话可以按批次只挂载最近消息并由用户
+  加载更早内容，但不得用固定的消息占位高度替代实际布局，避免推理、工具列表或长正文被
+  排除在可滚动范围之外。
+
+### 13.2 最近对话
+
+- 使用 `standard` 壳层和统一 `PageHeader`。
+- 搜索、范围和时间筛选位于筛选工具栏。
+- 行项目统一显示标题、范围、最近更新时间和必要状态。
+- 侧栏最近会话的更新时间在当天显示本地时间，非当天显示本地日期；非当年记录必须同时显示年份。悬停时间信息时提供完整日期和时间。
+- 侧栏中有关联 Task 的 Conversation 显示行首展开按钮，父行不显示任务标签或数量；展开后
+  最多直接显示 3 个 Task，“查看全部 N 个任务”打开该 Conversation 的完整任务区。
+- Task 子项左侧显示名称，右侧显示本地化的 Ask/Execute、计划摘要和共享状态标记，与父会话
+  的更新时间位置一致；已完成使用带勾成功点，不重复显示完成文字。点击子项打开同一
+  Conversation 并定位 Task，不继续展开 Job/Run。
+- 删除入口使用 `danger-ghost`，并按数据可恢复性执行确认或撤销策略。
+
+### 13.3 知识库
+
+- 使用 `master-detail` 壳层。
+- 左侧负责范围、搜索、筛选和条目选择，右侧负责详情、编辑和预览。
+- 两侧均只使用语义颜色令牌，禁止内联浅色背景或边框。
+- 选中条目后持续显示对象范围。没有选中项与知识库为空必须使用不同状态。
+- 窄窗口切换为单面板导航，不把双栏压缩到不可读。
+
+### 13.4 智能心跳
+
+- 使用 `dashboard` 壳层。
+- 顶部先呈现运行状态、实际范围和主操作，再呈现指标、建议、历史与配置。
+- 范围明确区分 Global 与指定的一个或多个 Project；Global 与指定项目互斥，多项目选择使用
+  Checkbox，不能依靠进入页面时的当前项目推断。
+- 状态卡片使用统一状态令牌，不只依赖颜色。
+- 保留“运行概览 / 待处理建议 / 报告与记录 / 心跳计划”四个同级页面。
+- 智能心跳菜单入口是完整配置的权威位置；任务中心和设置中心不得复制同一 CRUD 表单。
+- 分区记忆协同与唤起条件尚未实现，不得显示占位入口或平行的记忆类型。
+
+### 13.5 Task Center
+
+- 保留现有助手工作栏入口，首期在窄栏内适度完善，不先扩张成新的独立一级页面。
+- 只展示 Task；普通 Conversation、Job、Run、工具步骤、Subagent 和心跳事项不独立占行。
+- 每项显示名称、关联 Conversation、Global 或 Project 范围、Ask/Execute、状态、最近进展、
+  最近真实活动时间及需要关注信息。
+- 点击列表项打开关联 Conversation 并定位该 Task，不显示第二份内容载体。
+- 需要关注、进行中、已暂停和已结束使用共享 `SegmentedControl`；窄栏不足时单行滚动。
+- 完整消息留在 Conversation；长错误、工具、审批和成果按 Task 关联到 Runtime、活动记录和
+  成果查看器，不撑高列表，也不显示 Job/Run 树。
+- “新建定制任务”使用共享 Modal，明确选择当前或新 Conversation。聊天入口默认当前
+  Conversation，Task Center 入口默认新 Conversation；选择必须持续可见。
+- 定时消息创建 Modal 使用关联 Conversation 的 Runtime 与 Ask/Execute 模式，不再提供独立
+  模式开关。未运行计划的详情显示会话当前模式，已运行任务显示该次执行记录的模式；
+  不得用旧计划字段表示下一次执行权限。不支持工具时不得静默降级。
+
+### 13.6 运行记录
+
+- 使用 `dashboard` 壳层，并通过 `PageTabs` 提供“任务与会话 / 活动时间线 / 用量统计”三个同级视图。
+- 默认视图按“项目 → 任务或会话 → 活动详情”组织，项目范围持续可见，任务或会话详情可以折叠。
+- 任务或会话的综合状态以最近一次顶层请求对应的最终 Agent 结果为准；最终结果尚未产生时使用该请求的当前状态。中间工具或子专家的失败、取消和中断保留在活动详情中，但不得覆盖最终成功状态。
+- 活动时间线按项目分组、按任务或会话建立横向轨道，所有轨道共享同一执行顺序并按事件时间排列，以带身份名称的节点表达用户、主 Agent、子专家、工具、审批、状态和并行关系。节点内使用 `U / G / S / T / A` 拉丁字母简称，节点下显示完整身份或名称；选择节点后显示所属会话、不可变范围快照和完整详情。
+- 用量统计与活动记录分离，支持按项目、会话和模型切换统计维度，宽表格在独立容器内横向滚动。
+- 活动状态筛选使用 `SegmentedControl`，不与页面页签混合。清空历史遵循破坏性操作政策。
+
+### 13.7 魔法笔记
+
+- “笔记 / 待办”属于同一工作台内的同级内容面板，使用 `PageTabs` 的 `segmented` 视觉变体，与模型设置的分段控件保持同一外观。
+- 页签切换保留 `tablist`、`tab` 和 `tabpanel` 语义；待办状态仍使用独立的 `SegmentedControl`，不得与内容页签合并。
+- 笔记编辑器保留 Quill 原生列表快捷输入：输入 `-`、`*`、`1.`、`[ ]` 或 `[x]` 后按空格，分别转换为项目符号、编号或待办清单。快捷输入只生成现有 Delta 富文本，不引入 Markdown 源码模式、第二套持久化格式或第三方 Markdown 插件；编辑区附近持续提供简短提示。
+- 左侧笔记与待办列表在双栏布局中允许在 `180px` 至 `360px` 范围内通过指针或键盘调整，
+  也可从页面标题区隐藏和恢复；宽度与显示状态均记住用户选择。分隔条保留 `separator`
+  语义及方向键、Home、End 操作，窄窗口堆叠布局不显示拖拽分隔条。
+- 左侧笔记列表依次显示标题、最多两行内容预览，以及同一行的记录数和本地化更新时间。记录数靠左、更新时间靠右，窄宽度下均保持单行省略，不挤压标题或扩大列表栏。
+- 左侧“魔法笔记”入口可显示未完成待办数量。数量为 0 时隐藏徽标，超过 99 时显示 `99+`，可访问名称仍说明精确数量；勾选、取消勾选以及 Agent / MCP 对笔记清单的写入都必须刷新数量。
+- 未完成待办徽标的高度不得超过主导航图标；数量从 0 变为可见或再次隐藏时，主导航项行高和相邻菜单位置必须保持不变。
+- 在待办面板勾选或取消勾选后，当前缓存中的源笔记正文必须立即同步对应清单状态，不得依赖离开工作区后重新加载。
+- 当前记录草稿非空时，切换笔记、待办或内容面板必须先在编辑器旁就地确认；继续编辑时保留草稿并恢复编辑焦点，只有明确选择放弃后才切换。
+- 创建、保存、更新、删除和 AI 评论完成等短期结果进入应用级通知，不在编辑区或列表上方堆放页内通知。
+- 标题或正文校验、删除确认、同步进度和可就地恢复的错误仍靠近对应编辑器或操作呈现。
+
+### 13.8 设置中心
+
+- 全页设置使用固定标题区、左侧分类导航和独立滚动的内容区。右上角关闭按钮是离开设置中心的稳定入口。
+- 左侧分类导航在宽屏使用 `220px`，中等窗口使用 `196px`，窄窗口转为横向滚动；纵向滚动条仅在内容溢出时占用右侧空间，不在左侧创建镜像预留，选项与左侧可见边界保持默认内距。分类标题使用正文级字号，分类说明使用辅助字号；右侧内容区在可用空间内流式伸缩，最大宽度使用 `standard` 壳层的 `960px`，不得以页面专属较窄宽度压缩表单。
+- 全页设置标题区与双栏内容使用共享 `--page-gutter`，标题、分类导航和内容区在同一页面边距基线上；标题继续使用标准 `PageHeader` 的底部分隔线与下内距。固定标题和双独立滚动区域不改变这些一级页面壳层规则；模态设置保留自身外框与标题边界。
+- 设置中心不显示全局操作页脚，避免重复关闭入口和没有功能意义的整宽分隔线。
+- 所有分类使用共享的 `SettingsCategoryHeader` 呈现分类标题、说明、错误与操作，不得在内容卡片内复制分类标题或创建页面专属操作栏。左侧分类名称与说明来自同一份分类定义，新增分类时不得分别维护导航和内容标题。
+- 当前分类存在“保存”或“测试”等未提交配置操作时，统一放在分类页头右侧；主保存操作在最右侧，测试等次操作排列在其左侧。
+- 自动生效、仅执行即时命令或自行管理编辑流程的分类不显示全局保存操作。窄窗口下操作区可以换行，但保存入口必须保持清晰可见。
+- 智能心跳的单条配置不在设置中心重复管理。设置中心如需呈现平台级说明，只提供
+  “打开智能心跳”导航，不复制创建、暂停、恢复或删除表单。
+- 保存或测试成功统一进入应用通知视口，并按全局规则自动消失，不在分类页头或内容卡片中保留持久成功文案。加载、保存和测试错误显示在分类页头下方，并保留可处理的上下文。
+- “模型连接”的认证字段按“认证方式 → API Key → 凭据状态”排列；只有选择 API Key 时显示输入框。已保存的 API Key 属于该连接，修改模型服务地址或临时选择“无需认证”不得自动清除，也不得要求重新输入；仅由明确的“清除凭据”或“删除连接”操作移除。
+- “保存并测试模型”必须在保存后发送一次有界的真实模型请求。文本连接校验本次随机测试文本，图像连接校验实际返回的内联图片；仅收到成功 HTTP 状态、模型列表或健康检查响应不算测试成功。界面持续说明该操作可能产生少量服务商用量费用，成功反馈明确写为“真实生成测试通过”。
+- 所有显式保存的设置草稿都参与离开保护：关闭、切换分类、主侧栏或工作区导航及托盘导航不得静默丢弃，统一通过设置中心的就地确认提供继续编辑与明确放弃入口，保存失败后保留输入。“平台功能 / 通用设置”承载全局快捷唤起的共享 Switch、可访问 accelerator 录制输入、恢复默认、保存及注册、停用或冲突状态，不新增分类或页签；注册或持久化失败时保留上一组可用快捷键和当前草稿，保存或停用成功后同步更新输入区的快捷键提示。
+- “平台功能 / 通用设置”同时提供默认开启的“在会话中渲染 HTML”持久 Switch。说明必须
+  明确该能力只生成禁用脚本、联网、表单提交和窗口操作的静态预览；保存成功后当前会话立即
+  更新，保存失败时保留最后确认状态。
+- “平台功能”使用共享 `PageTabs` 区分“通用设置”“远程项目（技术预览）”和“魔法笔记”，默认进入通用设置。“远程项目”页将持久 Switch 与用户数据目录中的 Linux x64、Linux arm64、macOS arm64 Agent 包清单分成独立卡片；每张卡片与下载进度按平台和架构区分，不能把两个 arm64 目标合并。清单延迟到首次打开该页签时由 Main 完整校验，并读取所选更新源的小型签名目录，显示本地版本、在线最新兼容版本以及“有更新”“已是最新”“未下载”“校验失败”。打开页签或刷新不得自动下载 `.gbagent`；只有用户点击带目标版本的下载/更新按钮后才传输包。签名目录不可用时继续显示并允许导出已验证本地包，提供就地重试错误；清单不混入 Host 已安装状态、缓存路径或敏感签名细节。下载和导入期间保留上下文进度，成功进入全局通知视口。“魔法笔记”页提供默认开启的“显示未完成待办数量”持久 Switch，关闭后只隐藏左侧数量徽标，不改变待办数据或魔法笔记入口。全局模型下载源使用 `fieldset`、持久 `legend` 与整行可点击的原生 Radio 卡片；选中状态同时依靠 Radio、边框和背景表达，读取失败时不得用默认值伪装为已保存选择。
+- “关于与更新”的更新源位于“启动时检查新版本”开关下方，常规宽度下将标签、原生单选下拉框和用途说明放在同一行，并复用设置表单的统一控件样式；关闭启动检查后仍可选择更新源，手动检查继续使用当前选择。选项显示“GitHub（默认）”和中性的“镜像节点”。该选择同时控制手动检查、启动时检查、下载页和 Agent 包在线下载，不显示底层服务商名称。
+- “关于与更新”在版本信息之后提供应用内反馈卡片。反馈对话框使用原生字段、明确隐私说明和一张可选截图；另提供默认关闭的原生 Checkbox，让用户主动附加最近桌面诊断摘要。Checkbox 附近必须持续说明摘要只含时间、组件、阶段、稳定错误码、错误类型和固定短消息，不含对话、Prompt、凭据、文件内容、路径、Provider 原始响应或远端 Agent 日志。勾选时为诊断摘要预留描述字符预算，超长草稿必须保留并显示字段错误，不得静默截断。失败时保留草稿、勾选状态和请求编号并提供就地重试，成功时在对话框内保留可复制编号而不重复发送全局通知；对话框遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape、焦点恢复和窄窗口布局。
+- Agent Runtime 分类页头的“保存设置”同时保存 Runtime 基础配置与 Runtime 原生定制，不在原生定制卡片内提供第二个保存入口。原生定制存在未保存更改时持续显示状态和撤销入口；切换设置分类或 Runtime 不丢弃草稿，关闭设置中心前必须先保存或撤销。
+- Agent Runtime 页面在低层程序与配置覆盖之外提供“能力与默认配置”区域。能力清单使用共享 `PageTabs`，按 Agents、Tools、Commands、Skills、MCP、Rules、Prompts、Resources、LSP、Formatters 和上下文 11 类单行滚动展示，一次只呈现当前分类的 `tabpanel`；清单只显示 Runtime 自有能力，不混入 GoodBuddy 分配的 Skills、临时 MCP 或 Continue 预设。Tools 必须独立于 Commands、LSP 和 Formatters，显示工具类型、来源及 Ask/Execute 可用性；清单状态必须区分完整、部分、不可用、仅连接和不支持，不能用进程连通性冒充清单可读。
+- “能力与默认配置”只显示一个模块标题，刷新入口位于该标题右侧，能力状态压缩为一行并排在默认 Agent 或 Continue 预设编辑器之前；不得再复制“Runtime 原生能力”等同义标题、说明或状态结论。刷新只更新能力快照，不覆盖未保存的原生定制草稿。
+- OpenCode 的默认 Agent 使用原生下拉选择；Continue 预设编辑器允许管理名称、说明、启用的 Rules 以及 Prompt 名称、说明和正文，并可展开查看原生 Rules 与启用预设 Rules 的最终合并顺序。持久启停仍使用共享 Switch，添加与删除使用明确按钮和可访问名称。
+- MCP 设置按“内置 MCP / 直连模型 / 自定义 MCP / 电脑控制”四个同级 `PageTabs` 组织。联网搜索保留在直连模型；内置浏览器归入内置 MCP，提供持久启停和 Runtime 分配，并明确说明其操作 GoodBuddy 隔离浏览器、不控制客户端已安装的浏览器，开启后可由已分配 Runtime 的 Execute 直接使用，不逐次询问。该开关只控制 Agent 工具访问，关闭时不得禁用浏览器工作栏中的用户手动导航、返回、刷新、停止加载、交互或关闭操作。尚未生效的命名浏览器配置不得显示在界面中，“电脑控制”只显示实际操作客户端电脑的能力。内置 MCP 卡片与 Skills 一样提供持久启停和 Runtime 分配；直连模型、GoodBuddy 管理的 OpenCode 与 Continue 默认选中且可调整，DeepSeek Harness 必须以置灰、未选择和“暂不支持”文案持续显示，不能呈现为可保存的分配。魔法笔记 MCP 的自身启停与平台功能依赖分别显示，依赖未开启时保留用户配置并说明当前不会加载。
+- MCP Server 测试结果在同一展开卡片中分组显示 Tools、Prompts 和 Resources 的支持状态、数量与有界元数据；Prompt 参数标明必填项，Resource 只显示 URI、名称、类型和说明，不读取或渲染 Resource 内容。
+
+### 13.9 文档解析设置
+
+- 设置中心新增独立的“文档解析”分类，统一管理聊天附件、知识库导入以及后续文档审阅场景使用的提取、转换和 OCR 策略。OCR 不作为普通对话模型出现在“模型连接”中。
+- 分类页头说明文档解析的跨场景作用，右侧依次显示“测试解析”和“保存设置”；保存位于最右侧。测试必须选择真实文件并执行实际解析，不能只检查模型文件或接口连通性。
+- 页面首先显示原生解析、文档转换和 OCR 的运行状态，并明确当前可处理格式、回退能力与不可用原因。部分能力未配置时使用“部分可用”状态，不得把原生文本解析一并标记为失败。
+- “使用场景”分别配置聊天附件和知识库导入。普通用户选择“自动解析”“快速文本”“完整索引”等预设；阈值、并发和超时放入默认折叠的高级设置。
+- 本地 OCR 的全平台基线使用同一组 PP-OCRv6 ONNX 模型和 ONNX Runtime WebAssembly，在 Windows、macOS、Linux 的 x64 与 arm64 上保持相同功能。原生 ONNX、WebGPU、DirectML、CoreML 或 CUDA 只能作为可选加速，失败时必须回退到 WASM CPU。
+- OCR 模型管理与语音模型保持一致：应用不内置权重，用户可按需从 ModelScope 下载，也可在联网设备导出 ZIP 并在离线或内网设备直接导入。语音和 OCR 模型的下载、取消、ZIP 导入、ZIP 导出、删除与打开受管目录使用同一交互语义；ZIP 操作不得隐式切换当前模型或保存解析设置。
+- OCR 模型卡片必须持续显示来源、语言、运行时、体积、安装状态和许可。“打开 ModelScope”直接位于卡片右上角，不再使用“模型详情与手动导入”折叠区。窄窗口下仓库操作换行到模型摘要下方，仍须保持可访问名称和键盘操作。
+- PP-OCRv6 提供三个已实现档位：Tiny 约 6 MiB，适合低资源设备；Small 约 30 MiB，官方支持 50 种语言并作为推荐档位；Medium 约 132 MiB，官方支持 50 种语言、质量更高但速度较慢，界面必须提示其更高的内存占用和延迟。
+- 本地模型按受管目录和固定清单加载。ModelScope 下载地址必须固定不可变 revision、字节数和 SHA-256；下载先进入临时目录，全部校验成功后再原子安装。识别时不得从网络或可变分支临时加载模型。
+- 模型 ZIP 使用版本化的 `goodbuddy-model.json` 清单，声明模型类型、内置目录 ID、文件角色、大小与 SHA-256。导出前重新校验已安装文件；导入时限制压缩包大小、条目数、单文件和总展开大小，拒绝路径穿越、重复、未知、缺失或嵌套条目，并以应用内置目录重新校验后原子安装。ZIP 内的自声明信息不能扩大受信任模型集合。
+- PDF 先读取文本层。仅当页面无有效文本、乱码比例过高或用户选择“始终 OCR”时渲染该页并识别；不得因为单页需要 OCR 而丢弃其他页面已经提取的可靠文本。
+- DOCX、XLSX、PPTX 优先保留段落、单元格、公式、备注等原生语义。转换为 PDF 用于补充版面、页码、图表和图片理解，不作为唯一中间格式。
+- DOC、XLS、PPT 等旧格式通过受控转换 Provider 生成新式 Office 文档和 PDF。转换子进程必须禁用宏和网络，限制输入、输出、内存、超时与临时目录，并在关闭或取消时清理。
+- OCR 来源使用“本地模型 / 远程服务”互斥选择。选择本地后显示模型下载、模型下拉选择和本地运行参数；选择远程后显示 MinerU、PaddleOCR-VL 等服务连接配置。未实现的远程服务入口保持可读但禁用，不再增加与来源选择重复的“隐私与云端处理”授权区。
+- 用户配置并保存远程 OCR 服务即表示选择该处理路径，不再逐场景重复询问。界面仍须明确显示当前服务名称、处理范围和远程属性，API 密钥只保存在主进程加密设置中，未选中远程服务时不得上传文档。
+- 解析结果使用统一文档结构，至少保留文档标题、来源格式、页码或工作表定位、正文块、置信度、处理方式和警告。聊天附件对结果做有界截断，知识库使用完整结果分块和索引。
+- 测试结果显示文件类型、页数、实际工作流、提取字数、OCR 页数、耗时和警告。测试文件不得自动进入聊天上下文或知识库。
+
+## 14. 文案规则
+
+- 使用简体中文，动词直接、对象明确。
+- 页面标题使用名词，例如“知识库”“智能心跳”“活动记录”。
+- 按钮使用“动词 + 对象”，例如“新建任务”“导入知识”“停止运行”。
+- 状态文案描述事实，例如“正在同步”“上次运行失败”，不使用含糊的“异常”。
+- 错误提示包含发生了什么、用户可以做什么。保留必要的错误上下文，但不得暴露凭据、授权头、私人文档或未脱敏的提供商响应。
+- 同一概念固定使用一个名称，不交替使用“项目空间”“工作区”“范围”等近义词。产品内统一使用“范围”表达全局与项目归属。
+
+## 15. 迁移检查清单
+
+### 15.1 基础层
+
+- [ ] 建立浅色与深色语义颜色令牌，移除业务组件中的原始颜色值。
+- [ ] 建立白色浅色主画布、冰蓝灰侧栏与深海军蓝深色表面的稳定层级。
+- [ ] 建立间距、字体、圆角、阴影、层级和动效令牌。
+- [ ] 为主题切换、减少动态效果和原生控件设置全局规则。
+- [ ] 建立组件交互状态和焦点环基线。
+- [ ] 验证浅色侧栏结构分隔线与导航、会话选中状态清晰可辨。
+
+### 15.2 页面壳层与层级
+
+- [ ] 实现 `PageShell` 的 `reading`、`standard`、`dashboard`、`master-detail` 变体。
+- [ ] 按页面映射替换 `820px`、`900px`、`1040px` 和全宽等分散宽度声明。
+- [ ] 每个一级页面只保留一个 `PageHeader` 和一个一级标题。
+- [ ] 移除内容卡片中与页面标题重复的标题。
+
+### 15.3 共享组件
+
+- [ ] 实现并迁移 `PageHeader`。
+- [ ] 使用 `PageTabs` 统一同级页面导航。
+- [ ] 使用 `SegmentedControl` 统一少量互斥视图和状态切换。
+- [ ] 需要分段外观的同级面板使用 `PageTabs` 的共享 `segmented` 变体，不复制控件样式。
+- [ ] 建立统一筛选工具栏，移除以页签样式伪装的筛选。
+- [ ] 二元启停统一使用共享 Switch 视觉与 `role="switch"`，多选、范围分配和确认项保留 Checkbox。
+- [ ] 将短期成功、信息和非局部异步错误接入应用通知视口，移除页面专属通知横幅。
+- [ ] 实现 `ScopeBadge` 并覆盖全局、项目、失效和可切换状态。
+- [ ] 实现 `EmptyState` 的首次为空、无结果、失败和只读变体。
+- [ ] 实现 `danger-ghost`、`danger-solid` 和 `danger-zone`。
+- [ ] 统一模型、专家角色和工作模式的单选菜单结构、视觉与键盘行为。
+
+### 15.4 页面迁移
+
+- [ ] 聊天迁移到 `reading`，统一消息流与输入区宽度。
+- [ ] 将输入快捷键与附件提示置于空输入框内部，输入区下方保持单行说明。
+- [ ] 最近对话迁移到 `standard`，统一搜索、范围、时间和删除行为。
+- [ ] 知识库迁移到 `master-detail`，清除内联浅色样式并补齐窄窗口单面板流程。
+- [x] 智能心跳使用 `dashboard`，保留概览、建议、轨迹和计划，并在计划中支持 Global / 多 Project 范围。
+- [x] 在现有工作栏中完善任务中心，统一范围、状态、最近进展和筛选，不新建平行任务平台。
+- [ ] 活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。
+- [ ] 设置中心使用共享分类定义与 `SettingsCategoryHeader`，将保存与测试操作统一放到分类页头右侧，并把成功反馈接入应用通知。
+- [ ] 文档解析设置统一聊天附件与知识库的解析预设、OCR 状态、转换状态、隐私限制和真实文件测试。
+
+### 15.5 验收
+
+- [ ] 在浅色与深色主题下检查所有页面、弹窗、菜单、输入框、表格和空状态。
+- [ ] 在大于等于 `1200px`、`960px`、`720px` 和小于 `720px` 的窗口宽度检查布局。
+- [ ] 仅使用键盘完成导航、筛选、创建、编辑、确认和取消。
+- [ ] 验证焦点恢复、可访问名称、表单错误关联和实时状态播报。
+- [ ] 验证页面范围、对象范围和操作范围在关键流程中始终可见。
+- [ ] 验证删除、批量操作、停止运行和清空历史符合风险等级策略。
+- [ ] 验证加载中、首次为空、筛选无结果、搜索无结果、失败和只读状态不会互相混用。
+- [ ] 在 Windows、macOS、Linux 的 x64 与 arm64 上执行真实本地 OCR，并验证 WASM CPU 回退、取消、超时和离线运行。
+- [ ] 在联网设备导出语音与 OCR 模型 ZIP，在离线设备导入后执行真实推理；验证错误模型 ID、篡改文件、路径穿越、未知条目和压缩炸弹均被拒绝。
+
+## 16. 完成标准
+
+一个页面只有在满足以下条件时才视为完成迁移：
+
+1. 使用明确的 `PageShell` 变体，没有页面专属整体宽度。
+2. 使用统一标题层级、共享导航和筛选控件。
+3. 所有颜色、间距、字体、圆角和阴影来自令牌。
+4. 全局或项目范围在浏览、创建、编辑和危险操作中均可见。
+5. 浅色、深色、键盘和各窗口宽度下均可完成核心任务。
+6. 空状态、错误状态和危险操作符合本文规则。
+
+## 17. 一级页面加载性能
+
+- 首次启动只可在低优先级空闲时预加载轻量一级页面；Knowledge、Magic Notes、
+  Settings、Activity 等较重页面应在对应导航控件获得指针意图或键盘焦点时预加载。
+- 点击、快捷键和程序化导航不能依赖预加载完成，必须保留页面级 `Suspense` 加载
+  状态、错误边界和 KeepAlive 行为。
+- Workspace 与 Conversation 的 KeepAlive 缓存必须在每次访问时立即执行容量上限
+  与 LRU 保护规则；定时清理只负责过期与数据失效兜底，不能作为容量门禁。
+- 页面内大型可选视图应使用局部加载边界。知识图谱画布加载失败时，只替换画布
+  区域并提供可访问的重试操作，不得替换整个 Knowledge 页面或丢失其余页面状态。
+- 加载状态使用 `role="status"`、`aria-live="polite"` 与 `aria-busy="true"`；
+  局部加载失败使用 `role="alert"`，并保留明确的恢复操作。

agent-runtime-lock.json

@@ -0,0 +1,35 @@
+{
+  "formatVersion": 1,
+  "agentVersion": "0.11.23",
+  "protocol": {
+    "major": 2,
+    "minor": 0
+  },
+  "node": {
+    "version": "24.19.0",
+    "source": "https://nodejs.org/dist/v24.19.0/",
+    "targets": {
+      "linux-x64": {
+        "archive": "node-v24.19.0-linux-x64.tar.gz",
+        "sha256": "f625d97cd707df4ff96254916fbc5ff014f09c09effe5a1e0ca8f6d41a8789d4",
+        "binaryPath": "node-v24.19.0-linux-x64/bin/node",
+        "licensePath": "node-v24.19.0-linux-x64/LICENSE"
+      },
+      "darwin-arm64": {
+        "archive": "node-v24.19.0-darwin-arm64.tar.gz",
+        "sha256": "8294b7aa9b03997481c06babf1e8b270c859358f27da57a11509afe537ac381d",
+        "binaryPath": "node-v24.19.0-darwin-arm64/bin/node",
+        "licensePath": "node-v24.19.0-darwin-arm64/LICENSE"
+      },
+      "linux-arm64": {
+        "archive": "node-v24.19.0-linux-arm64.tar.gz",
+        "sha256": "d28c8a5bf0a808f0ed434a1dce8c54ae98f0371c0bd86ac58abc613f73e6643f",
+        "binaryPath": "node-v24.19.0-linux-arm64/bin/node",
+        "licensePath": "node-v24.19.0-linux-arm64/LICENSE"
+      }
+    }
+  },
+  "koffi": {
+    "version": "3.1.4"
+  }
+}

build/agent-build-target.cjs

@@ -0,0 +1,33 @@
+const { readFileSync } = require('node:fs')
+const {
+  detectBinaryArchitecture,
+  detectElfArchitecture
+} = require('./binary-architecture.cjs')
+
+function targetName(architecture, platform = 'linux') {
+  if (
+    !(platform === 'linux' && ['x64', 'arm64'].includes(architecture)) &&
+    !(platform === 'darwin' && architecture === 'arm64')
+  ) {
+    throw new Error(`Unsupported Agent build target: ${platform}-${architecture}`)
+  }
+  return `${platform}-${architecture}`
+}
+
+function assertTargetBinary(filePath, architecture, platform, label) {
+  targetName(architecture, platform)
+  const header = readFileSync(filePath).subarray(0, 64)
+  const isMachO = header.length >= 8 &&
+    (header.readUInt32LE(0) === 0xfeedfacf ||
+      header.readUInt32BE(0) === 0xfeedfacf)
+  const actual = platform === 'linux'
+    ? detectElfArchitecture(header)
+    : isMachO ? detectBinaryArchitecture(header) : undefined
+  if (actual !== architecture) {
+    throw new Error(
+      `${label} architecture mismatch: expected ${platform}-${architecture}, received ${actual ?? 'unknown'}`
+    )
+  }
+}
+
+module.exports = { targetName, assertTargetBinary }

build/agent-catalog.cjs

@@ -0,0 +1,942 @@
+const {
+  createHash,
+  createPublicKey,
+  sign,
+  verify
+} = require('node:crypto')
+const {
+  closeSync,
+  fstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  writeFileSync
+} = require('node:fs')
+const { basename, resolve } = require('node:path')
+const { crc32 } = require('node:zlib')
+const {
+  productionSigningKey,
+  publicKeySpkiBase64,
+  readTrustedKeyRegistry,
+  redactSecrets
+} = require('./agent-bundle.cjs')
+const {
+  canonicalJson,
+  descriptorContentDigest,
+  signatureDomain: packageSignatureDomain
+} = require('./agent-package.cjs')
+const {
+  localFileHeaderSignature,
+  readExactZipBytes,
+  readZipCentralDirectory
+} = require('./zip-central-directory.cjs')
+
+const root = resolve(__dirname, '..')
+function supportedTarget(platform, architecture) {
+  return (platform === 'linux' && ['x64', 'arm64'].includes(architecture)) ||
+    (platform === 'darwin' && architecture === 'arm64')
+}
+const catalogName = 'agent-catalog.json'
+const catalogSignatureName = 'agent-catalog.sig'
+const catalogSignatureDomain = Buffer.from(
+  'GoodBuddy Agent Package Catalog Signature v1\0',
+  'utf8'
+)
+const semanticVersionPattern =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*)|(?:\d*[A-Za-z-][0-9A-Za-z-]*))(?:\.(?:(?:0|[1-9]\d*)|(?:\d*[A-Za-z-][0-9A-Za-z-]*)))*)?$/u
+const sha256Pattern = /^[a-f0-9]{64}$/u
+const maximumPackageBytes = 512 * 1024 * 1024
+const maximumPackageEntries = 50_002
+const maximumPackageEntryBytes = 384 * 1024 * 1024
+const maximumExpandedPackageBytes = 1024 * 1024 * 1024
+const maximumMetadataBytes = 1024 * 1024
+const maximumDescriptorBytes = 4 * 1024 * 1024
+const maximumCentralDirectoryBytes = 32 * 1024 * 1024
+const maximumCatalogEntries = 200
+const windowsReservedNamePattern =
+  /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu
+
+function canonicalBytes(value) {
+  return Buffer.from(`${JSON.stringify(value, null, 2)}\n`, 'utf8')
+}
+
+function trustedProductionKey(registry, keyId) {
+  const key = registry.keys.find(
+    (candidate) =>
+      candidate.keyId === keyId &&
+      candidate.environment === 'production'
+  )
+  if (
+    !key ||
+    registry.revocations.some(
+      (revocation) => revocation.keyId === keyId
+    )
+  ) {
+    throw new Error(`Agent signing key is not trusted: ${keyId}`)
+  }
+  return key
+}
+
+function verifyDetachedSignature(
+  bytes,
+  signatureText,
+  key,
+  domain,
+  label
+) {
+  const signature = Buffer.from(
+    signatureText.toString('utf8').trim(),
+    'base64'
+  )
+  const publicKey = createPublicKey({
+    key: Buffer.from(key.publicKeySpkiBase64, 'base64'),
+    format: 'der',
+    type: 'spki'
+  })
+  if (
+    signature.length !== 64 ||
+    !verify(
+      null,
+      Buffer.concat([domain, bytes]),
+      publicKey,
+      signature
+    )
+  ) {
+    throw new Error(`${label} signature verification failed`)
+  }
+}
+
+function parseCanonicalJson(bytes, label) {
+  const value = JSON.parse(
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+  )
+  if (!canonicalBytes(value).equals(bytes)) {
+    throw new Error(`${label} is not canonical`)
+  }
+  return value
+}
+
+function assertProtocol(value, label) {
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !Number.isSafeInteger(value.major) ||
+    value.major < 1 ||
+    !Number.isSafeInteger(value.minor) ||
+    value.minor < 0
+  ) {
+    throw new Error(`${label} is invalid`)
+  }
+}
+
+function assertPackageDescriptor(descriptor) {
+  if (
+    typeof descriptor !== 'object' ||
+    descriptor === null ||
+    descriptor.format !== 'goodbuddy-agent-package' ||
+    descriptor.formatVersion !== 1 ||
+    descriptor.product !== 'GoodBuddy' ||
+    descriptor.component !== 'agent' ||
+    !semanticVersionPattern.test(descriptor.version ?? '') ||
+    !semanticVersionPattern.test(
+      descriptor.minimumDesktopVersion ?? ''
+    ) ||
+    !supportedTarget(descriptor.platform, descriptor.architecture) ||
+    !['x64', 'arm64'].includes(descriptor.architecture) ||
+    typeof descriptor.signingKeyId !== 'string' ||
+    !/^sha256:[a-f0-9]{64}$/u.test(
+      descriptor.contentDigest ?? ''
+    ) ||
+    !Array.isArray(descriptor.files) ||
+    descriptor.files.length === 0 ||
+    descriptor.files.length > 50_000 ||
+    typeof descriptor.remoteRuntime !== 'object' ||
+    descriptor.remoteRuntime === null ||
+    descriptor.remoteRuntime.runtimeId !== 'opencode' ||
+    descriptor.remoteRuntime.provider !== 'opencode' ||
+    !semanticVersionPattern.test(
+      descriptor.remoteRuntime.version ?? ''
+    ) ||
+    !/^sha256:[a-f0-9]{64}$/u.test(
+      descriptor.remoteRuntime.bundleDigest ?? ''
+    )
+  ) {
+    throw new Error('Agent package descriptor is invalid')
+  }
+  assertProtocol(descriptor.agentProtocol, 'Agent protocol')
+  assertProtocol(
+    descriptor.remoteRuntime.protocol,
+    'Remote Runtime protocol'
+  )
+  const paths = new Set()
+  for (const file of descriptor.files) {
+    if (
+      typeof file !== 'object' ||
+      file === null ||
+      !safePackagePath(file.path) ||
+      !Number.isSafeInteger(file.size) ||
+      file.size < 0 ||
+      !sha256Pattern.test(file.sha256 ?? '') ||
+      !['0644', '0755'].includes(file.mode) ||
+      paths.has(file.path)
+    ) {
+      throw new Error('Agent package file inventory is invalid')
+    }
+    paths.add(file.path)
+  }
+  if (
+    descriptor.contentDigest !==
+    descriptorContentDigest(descriptor)
+  ) {
+    throw new Error('Agent package content identity is invalid')
+  }
+}
+
+function readPackageMetadata(archivePath, registry) {
+  const archive = resolve(archivePath)
+  const streamed = streamPackageMetadata(archive)
+  const descriptorBytes = streamed.descriptor
+  const signatureBytes = streamed.signature
+  if (!descriptorBytes || !signatureBytes) {
+    throw new Error('Agent package metadata is missing')
+  }
+  const descriptor = parseCanonicalJson(
+    Buffer.from(descriptorBytes),
+    'Agent package descriptor'
+  )
+  assertPackageDescriptor(descriptor)
+  verifyPackageFileInventory(descriptor, streamed.files)
+  const key = trustedProductionKey(
+    registry,
+    descriptor.signingKeyId
+  )
+  verifyDetachedSignature(
+    Buffer.from(descriptorBytes),
+    Buffer.from(signatureBytes),
+    key,
+    packageSignatureDomain,
+    'Agent package'
+  )
+  const expectedArchive =
+    `goodbuddy-agent-${descriptor.version}` +
+    `-${descriptor.platform}-${descriptor.architecture}.gbagent`
+  if (basename(archive) !== expectedArchive) {
+    throw new Error(
+      `Agent package archive must be named ${expectedArchive}`
+    )
+  }
+  return {
+    archive: expectedArchive,
+    descriptor,
+    size: streamed.size,
+    sha256: streamed.sha256
+  }
+}
+
+function safePackagePath(path) {
+  return (
+    typeof path === 'string' &&
+    path.length > 0 &&
+    path.length <= 512 &&
+    !path.startsWith('/') &&
+    !path.endsWith('/') &&
+    !path.includes('\\') &&
+    path.split('/').every(
+      (part) =>
+        part.length > 0 &&
+        part !== '.' &&
+        part !== '..' &&
+        !part.endsWith('.') &&
+        !part.endsWith(' ') &&
+        !part.includes(':') &&
+        [...part].every(
+          (character) => character.charCodeAt(0) > 0x1f
+        ) &&
+        !windowsReservedNamePattern.test(part)
+    )
+  )
+}
+
+function verifyPackageFileInventory(descriptor, actualFiles) {
+  const expected = new Set([
+    ...descriptor.files.map((file) => file.path),
+    'agent-package.json',
+    'agent-package.sig'
+  ])
+  if (
+    actualFiles.size !== expected.size ||
+    [...actualFiles.keys()].some((path) => !expected.has(path))
+  ) {
+    throw new Error(
+      'Agent package contains undeclared or missing files'
+    )
+  }
+  for (const file of descriptor.files) {
+    const actual = actualFiles.get(file.path)
+    if (
+      !actual ||
+      actual.size !== file.size ||
+      actual.sha256 !== file.sha256
+    ) {
+      throw new Error(
+        `Agent package payload verification failed: ${file.path}`
+      )
+    }
+  }
+}
+
+function centralDirectoryEntries(handle, archiveSize) {
+  const parsed = readZipCentralDirectory(handle, archiveSize, {
+    label: 'Agent package',
+    minimumEntries: 1,
+    maximumEntries: maximumPackageEntries,
+    maximumCentralDirectoryBytes
+  })
+  const entries = []
+  const seen = new Set()
+  let expandedBytes = 0
+  for (const entry of parsed.entries) {
+    if (
+      entry.flags !== 0x0800 ||
+      entry.compression !== 0 ||
+      entry.compressedSize === 0xffffffff ||
+      entry.size === 0xffffffff ||
+      entry.compressedSize !== entry.size ||
+      entry.size > maximumPackageEntryBytes ||
+      entry.diskStart !== 0 ||
+      entry.localOffset === 0xffffffff
+    ) {
+      throw new Error('Agent package ZIP entry is unsupported')
+    }
+    if (
+      !safePackagePath(entry.name) ||
+      seen.has(entry.name)
+    ) {
+      throw new Error(
+        'Agent package contains an unsafe or duplicate path'
+      )
+    }
+    seen.add(entry.name)
+    expandedBytes += entry.size
+    if (expandedBytes > maximumExpandedPackageBytes) {
+      throw new Error(
+        'Agent package expanded payload exceeds its limit'
+      )
+    }
+    const local = readExactZipBytes(
+      handle,
+      30,
+      entry.localOffset,
+      'Agent package local file header'
+    )
+    const localNameLength = local.readUInt16LE(26)
+    const localExtraLength = local.readUInt16LE(28)
+    if (
+      local.readUInt32LE(0) !== localFileHeaderSignature ||
+      local.readUInt16LE(6) !== entry.flags ||
+      local.readUInt16LE(8) !== entry.compression ||
+      local.readUInt32LE(14) !== entry.checksum ||
+      local.readUInt32LE(18) !== entry.compressedSize ||
+      local.readUInt32LE(22) !== entry.size ||
+      localNameLength !== entry.nameBytes.length
+    ) {
+      throw new Error('Agent package local file header is invalid')
+    }
+    const localName = readExactZipBytes(
+      handle,
+      localNameLength,
+      entry.localOffset + 30,
+      'Agent package local file name'
+    )
+    if (!localName.equals(entry.nameBytes)) {
+      throw new Error('Agent package local file name is invalid')
+    }
+    const dataOffset =
+      entry.localOffset +
+      30 +
+      localNameLength +
+      localExtraLength
+    const recordEnd = dataOffset + entry.compressedSize
+    if (recordEnd > parsed.centralOffset) {
+      throw new Error('Agent package entry exceeds its data region')
+    }
+    entries.push({
+      checksum: entry.checksum,
+      dataOffset,
+      name: entry.name,
+      recordStart: entry.localOffset,
+      recordEnd
+    })
+  }
+  entries.sort(
+    (left, right) => left.recordStart - right.recordStart
+  )
+  for (let index = 1; index < entries.length; index += 1) {
+    if (entries[index].recordStart < entries[index - 1].recordEnd) {
+      throw new Error('Agent package ZIP entries overlap')
+    }
+  }
+  return entries
+}
+
+function sameFileSnapshot(left, right) {
+  return (
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.size === right.size &&
+    left.mtimeMs === right.mtimeMs &&
+    left.ctimeMs === right.ctimeMs
+  )
+}
+
+function streamPackageMetadata(archivePath) {
+  const handle = openSync(archivePath, 'r')
+  const values = new Map()
+  const files = new Map()
+  try {
+    const initialStatus = fstatSync(handle)
+    if (
+      !initialStatus.isFile() ||
+      initialStatus.size <= 0 ||
+      initialStatus.size > maximumPackageBytes
+    ) {
+      throw new Error(
+        'Agent package archive is not a bounded file'
+      )
+    }
+    const entries = centralDirectoryEntries(
+      handle,
+      initialStatus.size
+    )
+    const states = entries.map((entry) => {
+      const wanted =
+        entry.name === 'agent-package.json' ||
+        entry.name === 'agent-package.sig'
+      const size = entry.recordEnd - entry.dataOffset
+      const maximum = entry.name === 'agent-package.json'
+        ? maximumDescriptorBytes
+        : maximumMetadataBytes
+      if (wanted && size > maximum) {
+        throw new Error('Agent package metadata exceeds its limit')
+      }
+      return {
+        ...entry,
+        bytes: 0,
+        contents: wanted
+          ? Buffer.allocUnsafe(size)
+          : undefined,
+        crc32: 0,
+        hash: createHash('sha256')
+      }
+    })
+    const archiveHash = createHash('sha256')
+    const buffer = Buffer.allocUnsafe(1024 * 1024)
+    let position = 0
+    let firstEntry = 0
+    while (position < initialStatus.size) {
+      const bytesRead = readSync(
+        handle,
+        buffer,
+        0,
+        Math.min(buffer.length, initialStatus.size - position),
+        position
+      )
+      if (bytesRead <= 0) {
+        throw new Error('Agent package archive is truncated')
+      }
+      const chunk = buffer.subarray(0, bytesRead)
+      const chunkEnd = position + bytesRead
+      archiveHash.update(chunk)
+      while (
+        firstEntry < states.length &&
+        states[firstEntry].recordEnd <= position
+      ) {
+        firstEntry += 1
+      }
+      for (
+        let index = firstEntry;
+        index < states.length &&
+        states[index].dataOffset < chunkEnd;
+        index += 1
+      ) {
+        const state = states[index]
+        const dataStart = Math.max(position, state.dataOffset)
+        const dataEnd = Math.min(chunkEnd, state.recordEnd)
+        if (dataStart >= dataEnd) {
+          continue
+        }
+        const data = chunk.subarray(
+          dataStart - position,
+          dataEnd - position
+        )
+        state.hash.update(data)
+        state.crc32 = crc32(data, state.crc32)
+        if (state.contents) {
+          data.copy(
+            state.contents,
+            dataStart - state.dataOffset
+          )
+        }
+        state.bytes += data.byteLength
+      }
+      position = chunkEnd
+    }
+    if (!sameFileSnapshot(initialStatus, fstatSync(handle))) {
+      throw new Error(
+        'Agent package archive changed during verification'
+      )
+    }
+    for (const state of states) {
+      const size = state.recordEnd - state.dataOffset
+      if (
+        state.bytes !== size ||
+        (state.crc32 >>> 0) !== state.checksum
+      ) {
+        throw new Error(
+          `Agent package ZIP checksum verification failed: ${state.name}`
+        )
+      }
+      files.set(state.name, {
+        size,
+        sha256: state.hash.digest('hex')
+      })
+      if (state.contents) {
+        values.set(state.name, state.contents)
+      }
+    }
+    return {
+      descriptor: values.get('agent-package.json'),
+      signature: values.get('agent-package.sig'),
+      files,
+      sha256: archiveHash.digest('hex'),
+      size: initialStatus.size
+    }
+  } finally {
+    closeSync(handle)
+  }
+}
+
+function catalogEntry(metadata) {
+  const descriptor = metadata.descriptor
+  const {
+    contentDigest: _contentDigest,
+    files: _files,
+    signingKeyId: _signingKeyId,
+    ...identity
+  } = descriptor
+  void _contentDigest
+  void _files
+  void _signingKeyId
+  return {
+    ...identity,
+    archive: metadata.archive,
+    size: metadata.size,
+    sha256: metadata.sha256,
+    downloads: {
+      github: {
+        url:
+          'https://github.com/mesalogo/goodbuddy/releases/download/' +
+          `agent-v${descriptor.version}/${metadata.archive}`
+      },
+      mirror: {
+        url:
+          'https://goodbuddy.oss-cn-beijing.aliyuncs.com/' +
+          `agent-releases/v${descriptor.version}/${metadata.archive}`
+      }
+    }
+  }
+}
+
+function assertCatalog(catalog) {
+  if (
+    typeof catalog !== 'object' ||
+    catalog === null ||
+    catalog.formatVersion !== 1 ||
+    catalog.product !== 'GoodBuddy' ||
+    catalog.component !== 'agent' ||
+    typeof catalog.signingKeyId !== 'string' ||
+    typeof catalog.generatedAt !== 'string' ||
+    !Number.isFinite(Date.parse(catalog.generatedAt)) ||
+    new Date(catalog.generatedAt).toISOString() !==
+      catalog.generatedAt ||
+    !Array.isArray(catalog.entries) ||
+    catalog.entries.length === 0 ||
+    catalog.entries.length > maximumCatalogEntries
+  ) {
+    throw new Error('Agent catalog is invalid')
+  }
+  const identities = new Set()
+  for (const entry of catalog.entries) {
+    if (
+      typeof entry !== 'object' ||
+      entry === null ||
+      !semanticVersionPattern.test(entry.version ?? '') ||
+      !semanticVersionPattern.test(
+        entry.minimumDesktopVersion ?? ''
+      ) ||
+      !supportedTarget(entry.platform, entry.architecture) ||
+      !['x64', 'arm64'].includes(entry.architecture) ||
+      entry.archive !==
+        `goodbuddy-agent-${entry.version}` +
+        `-${entry.platform}-${entry.architecture}.gbagent` ||
+      !Number.isSafeInteger(entry.size) ||
+      entry.size <= 0 ||
+      !sha256Pattern.test(entry.sha256 ?? '') ||
+      entry.downloads?.github?.url !==
+        'https://github.com/mesalogo/goodbuddy/releases/download/' +
+          `agent-v${entry.version}/${entry.archive}` ||
+      entry.downloads?.mirror?.url !==
+        'https://goodbuddy.oss-cn-beijing.aliyuncs.com/' +
+          `agent-releases/v${entry.version}/${entry.archive}` ||
+      entry.format !== 'goodbuddy-agent-package' ||
+      entry.formatVersion !== 1 ||
+      entry.product !== 'GoodBuddy' ||
+      entry.component !== 'agent' ||
+      entry.remoteRuntime?.runtimeId !== 'opencode' ||
+      entry.remoteRuntime?.provider !== 'opencode' ||
+      !semanticVersionPattern.test(
+        entry.remoteRuntime?.version ?? ''
+      ) ||
+      !/^sha256:[a-f0-9]{64}$/u.test(
+        entry.remoteRuntime?.bundleDigest ?? ''
+      )
+    ) {
+      throw new Error('Agent catalog entry is invalid')
+    }
+    assertProtocol(entry.agentProtocol, 'Agent protocol')
+    assertProtocol(
+      entry.remoteRuntime.protocol,
+      'Remote Runtime protocol'
+    )
+    const identity = `${entry.version}:${entry.platform}:${entry.architecture}`
+    if (identities.has(identity)) {
+      throw new Error('Agent catalog contains duplicate entries')
+    }
+    identities.add(identity)
+  }
+}
+
+function readVerifiedCatalog(catalogPath, signaturePath, registry) {
+  const bytes = readFileSync(resolve(catalogPath))
+  const catalog = parseCanonicalJson(bytes, 'Agent catalog')
+  assertCatalog(catalog)
+  const key = trustedProductionKey(
+    registry,
+    catalog.signingKeyId
+  )
+  verifyDetachedSignature(
+    bytes,
+    readFileSync(resolve(signaturePath)),
+    key,
+    catalogSignatureDomain,
+    'Agent catalog'
+  )
+  return catalog
+}
+
+function parseVersion(value) {
+  const match =
+    /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/u
+      .exec(value)
+  if (!match) {
+    throw new Error(`Invalid semantic version: ${value}`)
+  }
+  return [
+    BigInt(match[1]),
+    BigInt(match[2]),
+    BigInt(match[3]),
+    match[4]?.split('.')
+  ]
+}
+
+function compareVersions(left, right) {
+  const leftParts = parseVersion(left)
+  const rightParts = parseVersion(right)
+  for (const index of [0, 1, 2]) {
+    if (leftParts[index] !== rightParts[index]) {
+      return leftParts[index] > rightParts[index] ? 1 : -1
+    }
+  }
+  const leftPre = leftParts[3]
+  const rightPre = rightParts[3]
+  if (!leftPre && !rightPre) return 0
+  if (!leftPre) return 1
+  if (!rightPre) return -1
+  for (
+    let index = 0;
+    index < Math.max(leftPre.length, rightPre.length);
+    index += 1
+  ) {
+    const leftValue = leftPre[index]
+    const rightValue = rightPre[index]
+    if (leftValue === undefined) return -1
+    if (rightValue === undefined) return 1
+    if (leftValue === rightValue) continue
+    const leftNumeric = /^\d+$/u.test(leftValue)
+    const rightNumeric = /^\d+$/u.test(rightValue)
+    if (leftNumeric && rightNumeric) {
+      return BigInt(leftValue) > BigInt(rightValue) ? 1 : -1
+    }
+    if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1
+    }
+    return leftValue > rightValue ? 1 : -1
+  }
+  return 0
+}
+
+function createCatalog(options) {
+  const projectRoot = options.projectRoot ?? root
+  const registry =
+    options.registry ?? readTrustedKeyRegistry(projectRoot)
+  const signingIdentity =
+    options.signingIdentity ??
+    productionSigningKey(options.environment ?? process.env)
+  const signingRecord = trustedProductionKey(
+    registry,
+    signingIdentity.keyId
+  )
+  if (
+    publicKeySpkiBase64(signingIdentity.privateKey) !==
+    signingRecord.publicKeySpkiBase64
+  ) {
+    throw new Error(
+      'Agent catalog signing key does not match the trusted registry'
+    )
+  }
+  const packages = [
+    readPackageMetadata(options.x64Package, registry),
+    readPackageMetadata(options.arm64Package, registry),
+    ...(options.darwinArm64Package ? [readPackageMetadata(options.darwinArm64Package, registry)] : [])
+  ]
+  const [first, second] = packages
+  const {
+    bundleDigest: _firstRuntimeDigest,
+    ...firstRuntimeIdentity
+  } = first.descriptor.remoteRuntime
+  const {
+    bundleDigest: _secondRuntimeDigest,
+    ...secondRuntimeIdentity
+  } = second.descriptor.remoteRuntime
+  void _firstRuntimeDigest
+  void _secondRuntimeDigest
+  if (
+    first.descriptor.version !== second.descriptor.version ||
+    first.descriptor.minimumDesktopVersion !==
+      second.descriptor.minimumDesktopVersion ||
+    canonicalJson(first.descriptor.agentProtocol) !==
+      canonicalJson(second.descriptor.agentProtocol) ||
+    canonicalJson(firstRuntimeIdentity) !==
+      canonicalJson(secondRuntimeIdentity) ||
+    new Set(packages.map(
+      (metadata) => metadata.descriptor.architecture
+    ).slice(0, 2)).size !== 2 ||
+    first.descriptor.platform !== 'linux' ||
+    second.descriptor.platform !== 'linux'
+  ) {
+    throw new Error(
+      'Agent package matrix does not describe one coherent release'
+    )
+  }
+  if (packages[2]) {
+    const mac = packages[2].descriptor
+    const { bundleDigest: _digest, ...runtimeIdentity } = mac.remoteRuntime
+    void _digest
+    if (
+      mac.platform !== 'darwin' || mac.architecture !== 'arm64' ||
+      mac.version !== first.descriptor.version ||
+      mac.minimumDesktopVersion !== first.descriptor.minimumDesktopVersion ||
+      canonicalJson(mac.agentProtocol) !== canonicalJson(first.descriptor.agentProtocol) ||
+      canonicalJson(runtimeIdentity) !== canonicalJson(firstRuntimeIdentity)
+    ) throw new Error('Agent package matrix does not describe one coherent release')
+  }
+  const previous =
+    options.previousCatalog && options.previousSignature
+      ? readVerifiedCatalog(
+          options.previousCatalog,
+          options.previousSignature,
+          registry
+        )
+      : undefined
+  if (
+    Boolean(options.previousCatalog) !==
+    Boolean(options.previousSignature)
+  ) {
+    throw new Error(
+      'Previous Agent catalog and signature must be provided together'
+    )
+  }
+  const entries = new Map()
+  for (const entry of previous?.entries ?? []) {
+    entries.set(`${entry.version}:${entry.platform}:${entry.architecture}`, entry)
+  }
+  for (const metadata of packages) {
+    const entry = catalogEntry(metadata)
+    const identity = `${entry.version}:${entry.platform}:${entry.architecture}`
+    const existing = entries.get(identity)
+    if (
+      existing &&
+      canonicalJson(existing) !== canonicalJson(entry)
+    ) {
+      throw new Error(
+        `Agent release identity is immutable: ${identity}`
+      )
+    }
+    entries.set(identity, entry)
+  }
+  const sortedEntries = [...entries.values()].sort(
+    (left, right) =>
+      compareVersions(right.version, left.version) ||
+      left.platform.localeCompare(right.platform, 'en') ||
+      left.architecture.localeCompare(right.architecture, 'en')
+  )
+  if (sortedEntries.length > maximumCatalogEntries) {
+    throw new Error('Agent catalog exceeds its retention limit')
+  }
+  const catalog = {
+    formatVersion: 1,
+    product: 'GoodBuddy',
+    component: 'agent',
+    signingKeyId: signingIdentity.keyId,
+    generatedAt: new Date(options.generatedAt).toISOString(),
+    entries: sortedEntries
+  }
+  assertCatalog(catalog)
+  const bytes = canonicalBytes(catalog)
+  const signature = sign(
+    null,
+    Buffer.concat([catalogSignatureDomain, bytes]),
+    signingIdentity.privateKey
+  )
+  writeFileSync(resolve(options.outputCatalog), bytes)
+  writeFileSync(
+    resolve(options.outputSignature),
+    `${signature.toString('base64')}\n`,
+    'utf8'
+  )
+  return {
+    version: first.descriptor.version,
+    catalog: basename(options.outputCatalog),
+    signature: basename(options.outputSignature),
+    entries: sortedEntries.length
+  }
+}
+
+function parseArguments(argv) {
+  const command = argv[0]
+  if (!['create', 'verify'].includes(command)) {
+    throw new Error(
+      'Usage: agent-catalog.cjs <create|verify> [options]'
+    )
+  }
+  const options = {}
+  for (let index = 1; index < argv.length; index += 2) {
+    const flag = argv[index]
+    const value = argv[index + 1]
+    if (
+      ![
+        '--x64-package',
+        '--arm64-package',
+        '--darwin-arm64-package',
+        '--previous-catalog',
+        '--previous-signature',
+        '--catalog',
+        '--signature',
+        '--generated-at'
+      ].includes(flag) ||
+      !value ||
+      value.startsWith('--') ||
+      options[flag] !== undefined
+    ) {
+      throw new Error('Invalid Agent catalog argument')
+    }
+    options[flag] = value
+  }
+  for (const flag of ['--catalog', '--signature']) {
+    if (!options[flag]) {
+      throw new Error(`Agent catalog argument is required: ${flag}`)
+    }
+  }
+  if (command === 'verify') {
+    return {
+      command,
+      catalog: resolve(options['--catalog']),
+      signature: resolve(options['--signature'])
+    }
+  }
+  for (const flag of [
+    '--x64-package',
+    '--arm64-package',
+    '--generated-at'
+  ]) {
+    if (!options[flag]) {
+      throw new Error(`Agent catalog argument is required: ${flag}`)
+    }
+  }
+  return {
+    command,
+    x64Package: resolve(options['--x64-package']),
+    arm64Package: resolve(options['--arm64-package']),
+    ...(options['--darwin-arm64-package'] ? {
+      darwinArm64Package: resolve(options['--darwin-arm64-package'])
+    } : {}),
+    ...(options['--previous-catalog']
+      ? {
+          previousCatalog: resolve(
+            options['--previous-catalog']
+          )
+        }
+      : {}),
+    ...(options['--previous-signature']
+      ? {
+          previousSignature: resolve(
+            options['--previous-signature']
+          )
+        }
+      : {}),
+    outputCatalog: resolve(options['--catalog']),
+    outputSignature: resolve(options['--signature']),
+    generatedAt: options['--generated-at']
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv)
+  const registry = readTrustedKeyRegistry(root)
+  const result =
+    options.command === 'create'
+      ? createCatalog(options)
+      : {
+          entries: readVerifiedCatalog(
+            options.catalog,
+            options.signature,
+            registry
+          ).entries.length
+        }
+  process.stdout.write(`${JSON.stringify(result)}\n`)
+}
+
+module.exports = {
+  catalogName,
+  catalogSignatureDomain,
+  catalogSignatureName,
+  canonicalBytes,
+  catalogEntry,
+  createCatalog,
+  parseArguments,
+  readPackageMetadata,
+  readVerifiedCatalog
+}
+
+if (require.main === module) {
+  try {
+    main()
+  } catch (error) {
+    process.stderr.write(
+      `${redactSecrets(
+        error instanceof Error ? error.message : String(error)
+      )}\n`
+    )
+    process.exitCode = 1
+  }
+}

build/agent-ci-bundle.cjs

@@ -0,0 +1,265 @@
+const { generateKeyPairSync } = require('node:crypto')
+const {
+  mkdirSync,
+  rmSync
+} = require('node:fs')
+const {
+  basename,
+  dirname,
+  join,
+  resolve
+} = require('node:path')
+const { spawnSync } = require('node:child_process')
+const {
+  buildAgentBundle,
+  publicKeySpkiBase64,
+  readRuntimeLock,
+  supportedArchitectures
+} = require('./agent-bundle.cjs')
+const {
+  buildRuntimeBundle,
+  readRemoteRuntimeLock
+} = require('./remote-runtime-bundle.cjs')
+const {
+  assembleAgentPackage
+} = require('./agent-package.cjs')
+const { sha256File } = require('./file-hash.cjs')
+const { targetName } = require('./agent-build-target.cjs')
+
+const ciSigningKeyId = 'goodbuddy-agent-ci-ephemeral'
+
+function parseArguments(argv) {
+  const options = {}
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (
+      ![
+        '--arch',
+        '--platform',
+        '--node-archive',
+        '--opencode-archive',
+        '--output-directory',
+        '--archive'
+      ].includes(argument)
+    ) {
+      throw new Error(`Unknown Agent CI bundle argument: ${argument}`)
+    }
+    const value = argv[index + 1]
+    if (!value || value.startsWith('--')) {
+      throw new Error(`${argument} requires a value`)
+    }
+    const key = argument.slice(2).replaceAll('-', '')
+    if (options[key] !== undefined) {
+      throw new Error(`${argument} may be provided only once`)
+    }
+    options[key] = value
+    index += 1
+  }
+  if (!supportedArchitectures.includes(options.arch)) {
+    throw new Error('--arch must be x64 or arm64')
+  }
+  const platform = options.platform ?? 'linux'
+  targetName(options.arch, platform)
+  for (const key of [
+    'nodearchive',
+    'opencodearchive',
+    'outputdirectory',
+    'archive'
+  ]) {
+    if (!options[key]) {
+      throw new Error(
+        'Usage: agent-ci-bundle.cjs --arch <x64|arm64> --node-archive <path> --opencode-archive <path> --output-directory <path> --archive <path>'
+      )
+    }
+  }
+  return {
+    arch: options.arch,
+    platform,
+    nodeArchive: resolve(options.nodearchive),
+    opencodeArchive: resolve(options.opencodearchive),
+    outputDirectory: resolve(options.outputdirectory),
+    archive: resolve(options.archive)
+  }
+}
+
+function readCiLocks(platform = 'linux', architecture = 'x64') {
+  const projectRoot = resolve(__dirname, '..')
+  targetName(architecture, platform)
+  const lock = readRuntimeLock(projectRoot)
+  const runtimeLock = readRemoteRuntimeLock(projectRoot)
+  return { lock, runtimeLock }
+}
+
+function ephemeralSigningIdentity() {
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519')
+  return {
+    privateKey,
+    registry: {
+      formatVersion: 1,
+      keys: [
+        {
+          keyId: ciSigningKeyId,
+          publicKeySpkiBase64: publicKeySpkiBase64(publicKey),
+          environment: 'test'
+        }
+      ],
+      revocations: []
+    }
+  }
+}
+
+async function buildCiAgentBundle(options) {
+  const projectRoot = resolve(__dirname, '..')
+  const platform = options.platform ?? 'linux'
+  const target = targetName(options.arch, platform)
+  if (process.platform !== platform || process.arch !== options.arch) {
+    throw new Error(`Agent CI build requires a native ${target} host`)
+  }
+  const { lock, runtimeLock } = readCiLocks(platform, options.arch)
+  const signing = ephemeralSigningIdentity()
+  const firstArchiveRoot = resolve(
+    join(
+      dirname(options.archive),
+      `.agent-ci-first-${process.pid}`
+    )
+  )
+  mkdirSync(firstArchiveRoot, { recursive: true })
+  const firstArchive = join(
+    firstArchiveRoot,
+    basename(options.archive)
+  )
+  const runtimeRoot = resolve(
+    `${options.outputDirectory}-runtime`
+  )
+  try {
+    const identity = {
+      keyId: ciSigningKeyId,
+      privateKey: signing.privateKey
+    }
+    rmSync(options.outputDirectory, {
+      recursive: true,
+      force: true
+    })
+    buildAgentBundle({
+      platform,
+      lock,
+      projectRoot,
+      arch: options.arch,
+      runtimeArchive: options.nodeArchive,
+      outputDirectory: options.outputDirectory,
+      registry: signing.registry,
+      testSigningIdentity: identity
+    })
+    const runtime = buildRuntimeBundle({
+      platform,
+      lock: runtimeLock,
+      projectRoot,
+      architecture: options.arch,
+      runtimeArchive: options.opencodeArchive,
+      outputRoot: runtimeRoot,
+      registry: signing.registry,
+      testSigningIdentity: identity
+    })
+    const assemble = (archive) =>
+      assembleAgentPackage({
+        platform,
+        projectRoot,
+        architecture: options.arch,
+        minimumDesktopVersion:
+          require('../package.json').version,
+        output: archive,
+        agentBundle: options.outputDirectory,
+        runtimeBundle: runtime.bundleDirectory,
+        agentLock: lock,
+        runtimeLock,
+        registry: signing.registry,
+        testSigningIdentity: identity
+      })
+
+    assemble(firstArchive)
+    const firstDigest = await sha256File(firstArchive)
+    const second = assemble(options.archive)
+    const archiveDigest = await sha256File(options.archive)
+    if (firstDigest !== archiveDigest) {
+      throw new Error('Agent CI archives are not deterministic')
+    }
+
+    const smoke = spawnSync(
+      resolve(options.outputDirectory, 'goodbuddy-agent'),
+      ['ci-invalid-command'],
+      {
+        encoding: 'utf8',
+        timeout: 10_000,
+        windowsHide: true
+      }
+    )
+    if (
+      smoke.error ||
+      smoke.status !== 2 ||
+      !smoke.stderr.includes(
+        'Expected daemon, attach-or-bootstrap, doctor'
+      )
+    ) {
+      throw new Error('Built Agent native launch smoke failed')
+    }
+
+    const nativeChecks = [
+      [
+        resolve(options.outputDirectory, 'node'),
+        ['-e', `const k = require(${JSON.stringify(resolve(options.outputDirectory, 'lib/node_modules/koffi'))}); if (k.sizeof('int') !== 4) process.exit(1)`]
+      ],
+      [join(runtime.bundleDirectory, 'bin', 'opencode'), ['--version']]
+    ]
+    for (const [executable, args] of nativeChecks) {
+      const result = spawnSync(executable, args, {
+        encoding: 'utf8',
+        timeout: 30_000,
+        windowsHide: true
+      })
+      if (
+        result.error ||
+        result.status !== 0 ||
+        (args[0] === '--version' &&
+          result.stdout.trim() !== runtimeLock.runtimes.opencode.version)
+      ) {
+        throw new Error(`Built native dependency smoke failed: ${basename(executable)}`)
+      }
+    }
+
+    return {
+      platform,
+      agentVersion: lock.agentVersion,
+      remoteRuntimeVersion:
+        runtimeLock.runtimes.opencode.version,
+      architecture: options.arch,
+      archive: second.archive,
+      archiveSha256: archiveDigest
+    }
+  } finally {
+    rmSync(runtimeRoot, { recursive: true, force: true })
+    rmSync(firstArchive, { force: true })
+    rmSync(firstArchiveRoot, { recursive: true, force: true })
+  }
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const result = await buildCiAgentBundle(parseArguments(argv))
+  process.stdout.write(
+    `${JSON.stringify(result)}\n`
+  )
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(
+      `${error instanceof Error ? error.message : String(error)}\n`
+    )
+    process.exitCode = 1
+  })
+}
+
+module.exports = {
+  buildCiAgentBundle,
+  parseArguments,
+  readCiLocks
+}

build/agent-package.cjs

@@ -0,0 +1,640 @@
+const {
+  createHash,
+  sign
+} = require('node:crypto')
+const {
+  closeSync,
+  copyFileSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeSync,
+  writeFileSync
+} = require('node:fs')
+const { basename, dirname, join, relative, resolve, sep } = require('node:path')
+const { tmpdir } = require('node:os')
+const { targetName } = require('./agent-build-target.cjs')
+const { crc32 } = require('node:zlib')
+const {
+  buildAgentBundle,
+  expectedManifestMode: expectedAgentManifestMode,
+  preflightProductionSigningKey,
+  productionSigningKey,
+  publicKeySpkiBase64,
+  readRuntimeLock,
+  readTrustedKeyRegistry,
+  redactSecrets,
+  verifyLockedBundle
+} = require('./agent-bundle.cjs')
+const {
+  buildRuntimeBundle,
+  canonicalJson,
+  readRemoteRuntimeLock,
+  verifyBundleDirectory: verifyRuntimeBundle
+} = require('./remote-runtime-bundle.cjs')
+const {
+  centralDirectoryHeaderSignature: zipCentralHeaderSignature,
+  endOfCentralDirectorySignature: zipEndSignature,
+  localFileHeaderSignature: zipLocalHeaderSignature
+} = require('./zip-central-directory.cjs')
+
+const root = join(__dirname, '..')
+const packageDescriptorName = 'agent-package.json'
+const packageSignatureName = 'agent-package.sig'
+const signatureDomain = Buffer.from(
+  'GoodBuddy Agent Package Descriptor Signature v1\0',
+  'utf8'
+)
+const zipUtf8Flag = 0x0800
+const zipVersion = 20
+const zipMadeByUnix = (3 << 8) | zipVersion
+const zipDosDate = (1 << 5) | 1
+const semanticVersionPattern =
+  /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:(?:0|[1-9]\d*)|(?:\d*[A-Za-z-][0-9A-Za-z-]*))(?:\.(?:(?:0|[1-9]\d*)|(?:\d*[A-Za-z-][0-9A-Za-z-]*)))*)?$/u
+
+function descriptorBytes(descriptor) {
+  return Buffer.from(`${JSON.stringify(descriptor, null, 2)}\n`, 'utf8')
+}
+
+function descriptorContentDigest(descriptor) {
+  const { contentDigest: _contentDigest, ...content } = descriptor
+  void _contentDigest
+  return `sha256:${createHash('sha256')
+    .update(canonicalJson(content))
+    .digest('hex')}`
+}
+
+function listFiles(directory) {
+  const rootPath = resolve(directory)
+  const output = []
+  const visit = (current) => {
+    const currentStat = lstatSync(current)
+    if (currentStat.isSymbolicLink()) {
+      throw new Error(`Agent package source contains a symlink: ${current}`)
+    }
+    if (currentStat.isFile()) {
+      output.push(current)
+      return
+    }
+    if (!currentStat.isDirectory()) {
+      throw new Error(
+        `Agent package source contains an unsupported entry: ${current}`
+      )
+    }
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      visit(join(current, entry.name))
+    }
+  }
+  visit(rootPath)
+  return output.sort((left, right) =>
+    Buffer.from(relative(rootPath, left).split(sep).join('/')).compare(
+      Buffer.from(relative(rootPath, right).split(sep).join('/'))
+    )
+  )
+}
+
+function fileDigests(filePath) {
+  const hash = createHash('sha256')
+  const handle = openSync(filePath, 'r')
+  const buffer = Buffer.allocUnsafe(1024 * 1024)
+  let checksum = 0
+  try {
+    while (true) {
+      const bytesRead = readSync(
+        handle,
+        buffer,
+        0,
+        buffer.length,
+        null
+      )
+      if (bytesRead === 0) {
+        break
+      }
+      const chunk = buffer.subarray(0, bytesRead)
+      hash.update(chunk)
+      checksum = crc32(chunk, checksum)
+    }
+  } finally {
+    closeSync(handle)
+  }
+  return {
+    crc32: checksum >>> 0,
+    sha256: hash.digest('hex')
+  }
+}
+
+function copyTree(source, destination) {
+  for (const filePath of listFiles(source)) {
+    const name = relative(source, filePath).split(sep).join('/')
+    const target = join(destination, ...name.split('/'))
+    mkdirSync(dirname(target), { recursive: true })
+    copyFileSync(filePath, target)
+  }
+}
+
+function packageFileMode(path) {
+  if (path.startsWith('agent/')) {
+    return expectedAgentManifestMode(path.slice('agent/'.length))
+  }
+  return /\/bin\/opencode$/u.test(path) ? '0755' : '0644'
+}
+
+function stagePackagePayload(options) {
+  const staging = options.staging
+  copyTree(options.agentBundle, join(staging, 'agent'))
+  copyTree(
+    options.runtimeBundle,
+    join(
+      staging,
+      'runtime',
+      'opencode',
+      basename(options.runtimeBundle)
+    )
+  )
+  for (const [value, destination] of [
+    [
+      options.registry,
+      'agent-release-keys.json'
+    ],
+    [
+      options.agentLock,
+      'agent-runtime-lock.json'
+    ],
+    [
+      options.runtimeLock,
+      'remote-runtime-lock.json'
+    ]
+  ]) {
+    writeFileSync(
+      join(staging, destination),
+      `${JSON.stringify(value, null, 2)}\n`,
+      'utf8'
+    )
+  }
+}
+
+function payloadFiles(staging) {
+  const crc32ByPath = new Map()
+  const files = listFiles(staging)
+    .map((filePath) => {
+      const path = relative(staging, filePath).split(sep).join('/')
+      const size = statSync(filePath).size
+      const digests = fileDigests(filePath)
+      crc32ByPath.set(path, digests.crc32)
+      return {
+        path,
+        size,
+        sha256: digests.sha256,
+        mode: packageFileMode(path)
+      }
+    })
+    .filter(
+      (file) =>
+        file.path !== packageDescriptorName &&
+        file.path !== packageSignatureName
+    )
+  return { crc32ByPath, files }
+}
+
+function createPackageArchive(
+  staging,
+  output,
+  knownCrc32 = new Map()
+) {
+  mkdirSync(dirname(output), { recursive: true })
+  const entries = listFiles(staging).map((filePath) => {
+    const name = relative(staging, filePath).split(sep).join('/')
+    const nameBytes = Buffer.from(name, 'utf8')
+    const size = statSync(filePath).size
+    if (
+      nameBytes.length === 0 ||
+      nameBytes.length > 0xffff ||
+      size > 0xffffffff
+    ) {
+      throw new Error(`Agent package ZIP entry is too large: ${name}`)
+    }
+    return {
+      filePath,
+      name,
+      nameBytes,
+      size,
+      crc32:
+        knownCrc32.get(name) ?? fileDigests(filePath).crc32,
+      mode: packageFileMode(name),
+      offset: 0
+    }
+  })
+  if (entries.length === 0 || entries.length > 0xffff) {
+    throw new Error('Agent package ZIP entry count is invalid')
+  }
+  const outputHandle = openSync(output, 'w')
+  let outputOffset = 0
+  const archiveHash = createHash('sha256')
+  const writeBytes = (data) => {
+    let offset = 0
+    while (offset < data.byteLength) {
+      const written = writeSync(
+        outputHandle,
+        data,
+        offset,
+        data.byteLength - offset
+      )
+      if (written <= 0) {
+        throw new Error('Agent package archive write made no progress')
+      }
+      offset += written
+    }
+    archiveHash.update(data)
+    outputOffset += data.byteLength
+  }
+  const buffer = Buffer.allocUnsafe(1024 * 1024)
+  try {
+    for (const entry of entries) {
+      entry.offset = outputOffset
+      const header = Buffer.alloc(30)
+      header.writeUInt32LE(zipLocalHeaderSignature, 0)
+      header.writeUInt16LE(zipVersion, 4)
+      header.writeUInt16LE(zipUtf8Flag, 6)
+      header.writeUInt16LE(0, 8)
+      header.writeUInt16LE(0, 10)
+      header.writeUInt16LE(zipDosDate, 12)
+      header.writeUInt32LE(entry.crc32, 14)
+      header.writeUInt32LE(entry.size, 18)
+      header.writeUInt32LE(entry.size, 22)
+      header.writeUInt16LE(entry.nameBytes.length, 26)
+      header.writeUInt16LE(0, 28)
+      writeBytes(header)
+      writeBytes(entry.nameBytes)
+
+      const inputHandle = openSync(entry.filePath, 'r')
+      try {
+        let position = 0
+        while (position < entry.size) {
+          const bytesRead = readSync(
+            inputHandle,
+            buffer,
+            0,
+            Math.min(buffer.length, entry.size - position),
+            null
+          )
+          if (bytesRead <= 0) {
+            throw new Error(
+              `Agent package source read made no progress: ${entry.name}`
+            )
+          }
+          position += bytesRead
+          writeBytes(buffer.subarray(0, bytesRead))
+        }
+      } finally {
+        closeSync(inputHandle)
+      }
+    }
+
+    const centralOffset = outputOffset
+    for (const entry of entries) {
+      const record = Buffer.alloc(46)
+      record.writeUInt32LE(zipCentralHeaderSignature, 0)
+      record.writeUInt16LE(zipMadeByUnix, 4)
+      record.writeUInt16LE(zipVersion, 6)
+      record.writeUInt16LE(zipUtf8Flag, 8)
+      record.writeUInt16LE(0, 10)
+      record.writeUInt16LE(0, 12)
+      record.writeUInt16LE(zipDosDate, 14)
+      record.writeUInt32LE(entry.crc32, 16)
+      record.writeUInt32LE(entry.size, 20)
+      record.writeUInt32LE(entry.size, 24)
+      record.writeUInt16LE(entry.nameBytes.length, 28)
+      record.writeUInt16LE(0, 30)
+      record.writeUInt16LE(0, 32)
+      record.writeUInt16LE(0, 34)
+      record.writeUInt16LE(0, 36)
+      const unixMode =
+        0o100000 | Number.parseInt(entry.mode, 8)
+      record.writeUInt32LE((unixMode << 16) >>> 0, 38)
+      record.writeUInt32LE(entry.offset, 42)
+      writeBytes(record)
+      writeBytes(entry.nameBytes)
+    }
+
+    const centralSize = outputOffset - centralOffset
+    const end = Buffer.alloc(22)
+    end.writeUInt32LE(zipEndSignature, 0)
+    end.writeUInt16LE(0, 4)
+    end.writeUInt16LE(0, 6)
+    end.writeUInt16LE(entries.length, 8)
+    end.writeUInt16LE(entries.length, 10)
+    end.writeUInt32LE(centralSize, 12)
+    end.writeUInt32LE(centralOffset, 16)
+    end.writeUInt16LE(0, 20)
+    writeBytes(end)
+    fsyncSync(outputHandle)
+  } finally {
+    closeSync(outputHandle)
+  }
+  return {
+    size: outputOffset,
+    sha256: archiveHash.digest('hex')
+  }
+}
+
+function assembleAgentPackage(options) {
+  const projectRoot = options.projectRoot ?? root
+  const architecture = options.architecture
+  const platform = options.platform ?? 'linux'
+  const target = targetName(architecture, platform)
+  if (
+    !['x64', 'arm64'].includes(architecture) ||
+    !semanticVersionPattern.test(options.minimumDesktopVersion ?? '') ||
+    typeof options.output !== 'string'
+  ) {
+    throw new Error('Agent package identity is invalid')
+  }
+  const registry =
+    options.registry ?? readTrustedKeyRegistry(projectRoot)
+  const agentLock =
+    options.agentLock ?? readRuntimeLock(projectRoot)
+  const runtimeLock =
+    options.runtimeLock ?? readRemoteRuntimeLock(projectRoot)
+  const signingIdentity =
+    options.testSigningIdentity ??
+    options.signingIdentity ??
+    productionSigningKey(options.environment ?? process.env)
+  const signingRecord = options.testSigningIdentity
+    ? registry.keys.find(
+        (key) => key.keyId === signingIdentity.keyId
+      )
+    : preflightProductionSigningKey({
+        projectRoot,
+        registry,
+        keyId: signingIdentity.keyId
+      })
+  if (!signingRecord) {
+    throw new Error('Agent package signing key is not registered')
+  }
+  if (
+    publicKeySpkiBase64(signingIdentity.privateKey) !==
+    signingRecord.publicKeySpkiBase64
+  ) {
+    throw new Error(
+      'Agent package signing private key does not match the trusted registry'
+    )
+  }
+  const agent = verifyLockedBundle(
+    options.agentBundle,
+    architecture,
+    {
+      platform,
+      projectRoot,
+      registry,
+      lock: agentLock,
+      verificationEnvironment: options.testSigningIdentity
+        ? 'test'
+        : 'production'
+    }
+  )
+  const runtime = verifyRuntimeBundle(options.runtimeBundle, {
+    platform,
+    projectRoot,
+    architecture,
+    registry,
+    lock: runtimeLock,
+    verificationEnvironment: options.testSigningIdentity
+      ? 'test'
+      : 'production'
+  })
+  const expectedArchiveName =
+    `goodbuddy-agent-${agent.manifest.agentVersion}` +
+    `-${target}.gbagent`
+  if (basename(options.output) !== expectedArchiveName) {
+    throw new Error(
+      `Agent package output must be named ${expectedArchiveName}`
+    )
+  }
+  const staging = mkdtempSync(
+    join(tmpdir(), `goodbuddy-agent-package-${target}-`)
+  )
+  try {
+    stagePackagePayload({
+      staging,
+      registry,
+      agentLock,
+      runtimeLock,
+      agentBundle: resolve(options.agentBundle),
+      runtimeBundle: runtime.bundleDirectory
+    })
+    const payload = payloadFiles(staging)
+    const initial = {
+      format: 'goodbuddy-agent-package',
+      formatVersion: 1,
+      product: 'GoodBuddy',
+      component: 'agent',
+      version: agent.manifest.agentVersion,
+      minimumDesktopVersion: options.minimumDesktopVersion,
+      platform,
+      architecture,
+      signingKeyId: signingIdentity.keyId,
+      agentProtocol: agent.manifest.protocol,
+      remoteRuntime: {
+        runtimeId: runtime.manifest.runtimeId,
+        provider: runtime.manifest.provider,
+        version: runtime.manifest.runtimeVersion,
+        bundleDigest: runtime.manifest.bundleDigest,
+        protocol: runtime.manifest.protocol
+      },
+      contentDigest: `sha256:${'0'.repeat(64)}`,
+      files: payload.files
+    }
+    const descriptor = {
+      ...initial,
+      contentDigest: descriptorContentDigest(initial)
+    }
+    const bytes = descriptorBytes(descriptor)
+    const signature = sign(
+      null,
+      Buffer.concat([signatureDomain, bytes]),
+      signingIdentity.privateKey
+    )
+    writeFileSync(join(staging, packageDescriptorName), bytes)
+    writeFileSync(
+      join(staging, packageSignatureName),
+      `${signature.toString('base64')}\n`,
+      'utf8'
+    )
+    const archive = createPackageArchive(
+      staging,
+      options.output,
+      payload.crc32ByPath
+    )
+    return {
+      descriptor,
+      archive: basename(options.output),
+      size: archive.size,
+      sha256: archive.sha256
+    }
+  } finally {
+    rmSync(staging, { recursive: true, force: true })
+  }
+}
+
+function buildAgentPackage(options) {
+  const projectRoot = options.projectRoot ?? root
+  const registry =
+    options.registry ?? readTrustedKeyRegistry(projectRoot)
+  const signingIdentity =
+    options.testSigningIdentity ??
+    options.signingIdentity ??
+    productionSigningKey(options.environment ?? process.env)
+  const agentRoot = mkdtempSync(
+    join(tmpdir(), `goodbuddy-agent-build-${options.architecture}-`)
+  )
+  const runtimeRoot = mkdtempSync(
+    join(tmpdir(), `goodbuddy-runtime-build-${options.architecture}-`)
+  )
+  try {
+    const agentBundle = buildAgentBundle({
+      platform: options.platform ?? 'linux',
+      projectRoot,
+      arch: options.architecture,
+      runtimeArchive: options.nodeArchive,
+      outputDirectory: join(agentRoot, 'agent'),
+      registry,
+      ...(options.agentLock ? { lock: options.agentLock } : {}),
+      ...(options.testSigningIdentity
+        ? { testSigningIdentity: options.testSigningIdentity }
+        : { signingIdentity })
+    })
+    const runtime = buildRuntimeBundle({
+      platform: options.platform ?? 'linux',
+      projectRoot,
+      architecture: options.architecture,
+      runtimeArchive: options.runtimeArchive,
+      outputRoot: runtimeRoot,
+      registry,
+      ...(options.runtimeLock ? { lock: options.runtimeLock } : {}),
+      ...(options.testSigningIdentity
+        ? { testSigningIdentity: options.testSigningIdentity }
+        : { signingIdentity })
+    })
+    return assembleAgentPackage({
+      ...options,
+      projectRoot,
+      registry,
+      ...(options.testSigningIdentity
+        ? {}
+        : { signingIdentity }),
+      agentBundle,
+      runtimeBundle: runtime.bundleDirectory
+    })
+  } finally {
+    rmSync(agentRoot, { recursive: true, force: true })
+    rmSync(runtimeRoot, { recursive: true, force: true })
+  }
+}
+
+function parseArguments(argv) {
+  const command = argv[0]
+  if (!['build', 'assemble'].includes(command)) {
+    throw new Error(
+      'Usage: agent-package.cjs <build|assemble> --arch <x64|arm64> --minimum-desktop-version <version> --output <archive>'
+    )
+  }
+  const options = {}
+  for (let index = 1; index < argv.length; index += 2) {
+    const flag = argv[index]
+    const value = argv[index + 1]
+    if (
+      ![
+        '--arch',
+        '--platform',
+        '--minimum-desktop-version',
+        '--node-archive',
+        '--runtime-archive',
+        '--agent-bundle',
+        '--runtime-bundle',
+        '--output'
+      ].includes(flag) ||
+      !value
+    ) {
+      throw new Error('Invalid Agent package argument')
+    }
+    options[
+      flag.slice(2).replace(/-([a-z])/gu, (_match, valuePart) =>
+        valuePart.toUpperCase()
+      )
+    ] = value
+  }
+  if (
+    !['x64', 'arm64'].includes(options.arch) ||
+    !semanticVersionPattern.test(
+      options.minimumDesktopVersion ?? ''
+    ) ||
+    !options.output
+  ) {
+    throw new Error('Agent package arguments are incomplete')
+  }
+  const common = {
+    platform: options.platform ?? 'linux',
+    architecture: options.arch,
+    minimumDesktopVersion: options.minimumDesktopVersion,
+    output: resolve(options.output)
+  }
+  targetName(common.architecture, common.platform)
+  if (command === 'build') {
+    if (!options.nodeArchive || !options.runtimeArchive) {
+      throw new Error('Agent package build inputs are incomplete')
+    }
+    return {
+      command,
+      ...common,
+      nodeArchive: resolve(options.nodeArchive),
+      runtimeArchive: resolve(options.runtimeArchive)
+    }
+  }
+  if (!options.agentBundle || !options.runtimeBundle) {
+    throw new Error('Agent package assembly inputs are incomplete')
+  }
+  return {
+    command,
+    ...common,
+    agentBundle: resolve(options.agentBundle),
+    runtimeBundle: resolve(options.runtimeBundle)
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv)
+  const result =
+    options.command === 'build'
+      ? buildAgentPackage(options)
+      : assembleAgentPackage(options)
+  process.stdout.write(`${JSON.stringify(result)}\n`)
+}
+
+module.exports = {
+  assembleAgentPackage,
+  buildAgentPackage,
+  canonicalJson,
+  descriptorBytes,
+  descriptorContentDigest,
+  parseArguments,
+  signatureDomain
+}
+
+if (require.main === module) {
+  try {
+    main()
+  } catch (error) {
+    process.stderr.write(
+      `${redactSecrets(
+        error instanceof Error ? error.message : String(error)
+      )}\n`
+    )
+    process.exitCode = 1
+  }
+}

build/aggregate-release.cjs

@@ -19,10 +19,10 @@ const manifestName = 'release-manifest.json'
 const targetDefinitions = [
   { platform: 'windows', arch: 'x64', formats: ['nsis', 'portable'] },
   { platform: 'windows', arch: 'arm64', formats: ['nsis', 'portable'] },
-  { platform: 'macos', arch: 'x64', formats: ['dmg', 'zip'] },
-  { platform: 'macos', arch: 'arm64', formats: ['dmg', 'zip'] },
-  { platform: 'linux', arch: 'x64', formats: ['AppImage', 'deb'] },
-  { platform: 'linux', arch: 'arm64', formats: ['AppImage', 'deb'] }
+  { platform: 'macos', arch: 'x64', formats: ['dmg'] },
+  { platform: 'macos', arch: 'arm64', formats: ['dmg'] },
+  { platform: 'linux', arch: 'x64', formats: ['AppImage', 'deb', 'rpm'] },
+  { platform: 'linux', arch: 'arm64', formats: ['AppImage', 'deb', 'rpm'] }
 ]
 const allowedExtensions = {
   nsis: '.exe',
@@ -30,7 +30,8 @@ const allowedExtensions = {
   dmg: '.dmg',
   zip: '.zip',
   AppImage: '.AppImage',
-  deb: '.deb'
+  deb: '.deb',
+  rpm: '.rpm'
 }
 
 function parseArguments(argv) {
@@ -319,6 +320,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   aggregateRelease,
   assertSafeName,
+  expectedFormatForFile,
   parseArguments,
   targetDefinitions
 }

build/binary-architecture.cjs

@@ -0,0 +1,71 @@
+function detectElfArchitecture(buffer) {
+  if (
+    buffer.length < 20 ||
+    buffer[0] !== 0x7f ||
+    buffer.toString('ascii', 1, 4) !== 'ELF' ||
+    ![1, 2].includes(buffer[5])
+  ) {
+    return undefined
+  }
+  const machine =
+    buffer[5] === 2
+      ? buffer.readUInt16BE(18)
+      : buffer.readUInt16LE(18)
+  if (machine === 62) {
+    return 'x64'
+  }
+  if (machine === 183) {
+    return 'arm64'
+  }
+  return undefined
+}
+
+function detectBinaryArchitecture(buffer) {
+  if (
+    buffer.length >= 64 &&
+    buffer[0] === 0x4d &&
+    buffer[1] === 0x5a
+  ) {
+    const peOffset = buffer.readUInt32LE(0x3c)
+    if (
+      peOffset + 6 <= buffer.length &&
+      buffer.toString('ascii', peOffset, peOffset + 4) === 'PE\0\0'
+    ) {
+      const machine = buffer.readUInt16LE(peOffset + 4)
+      if (machine === 0x8664) {
+        return 'x64'
+      }
+      if (machine === 0xaa64) {
+        return 'arm64'
+      }
+    }
+  }
+
+  const elfArchitecture = detectElfArchitecture(buffer)
+  if (elfArchitecture) {
+    return elfArchitecture
+  }
+
+  if (buffer.length >= 8) {
+    const littleMagic = buffer.readUInt32LE(0)
+    const bigMagic = buffer.readUInt32BE(0)
+    const cpuType =
+      littleMagic === 0xfeedfacf
+        ? buffer.readUInt32LE(4)
+        : bigMagic === 0xfeedfacf
+          ? buffer.readUInt32BE(4)
+          : undefined
+    if (cpuType === 0x01000007) {
+      return 'x64'
+    }
+    if (cpuType === 0x0100000c) {
+      return 'arm64'
+    }
+  }
+  return undefined
+}
+
+module.exports = {
+  detectBinaryArchitecture,
+  detectElfArchitecture
+}

build/build-portable.cjs

@@ -29,19 +29,6 @@ const portablePath = process.env.GOODBUDDY_OUT_DIR
 const markerName = '.goodbuddy-portable.json'
 const portableLocales = new Set(['zh-CN.pak', 'en-US.pak'])
 
-if (process.platform !== 'win32' || process.arch !== 'x64') {
-  throw new Error('Portable 目录当前必须在 Windows x64 上构建')
-}
-if (
-  portablePath === parse(portablePath).root ||
-  portablePath === root ||
-  portablePath === outputRoot
-) {
-  throw new Error(
-    `拒绝使用不安全的输出目录：${portablePath}`
-  )
-}
-
 function assertOutputUnlocked(directory) {
   if (!existsSync(directory)) {
     return
@@ -142,6 +129,9 @@ function portableRequiredPaths(directory) {
   return [
     join(directory, 'GoodBuddy.exe'),
     join(directory, 'resources', 'app.asar'),
+    join(directory, 'resources', 'agent-runtime-lock.json'),
+    join(directory, 'resources', 'remote-runtime-lock.json'),
+    join(directory, 'resources', 'agent-release-keys.json'),
     join(directory, 'resources', 'icon.ico'),
     join(directory, 'resources', 'tray-icon.png'),
     join(
@@ -151,6 +141,13 @@ function portableRequiredPaths(directory) {
       'opencode',
       'opencode.exe'
     ),
+    join(
+      directory,
+      'resources',
+      'runtimes',
+      'opencode',
+      'rg.exe'
+    ),
     join(
       directory,
       'resources',
@@ -219,7 +216,10 @@ function writePortableMarker(directory) {
   )
 }
 
-function replacePortableOutput(source, destination) {
+function replacePortableOutput(
+  source,
+  destination
+) {
   const replacement = `${destination}.replacement-${process.pid}`
   const backup = `${destination}.previous-${process.pid}`
   mkdirSync(dirname(destination), { recursive: true })
@@ -279,36 +279,76 @@ function replacePortableOutput(source, destination) {
   }
 }
 
-const electronDist = ensureElectronRuntime()
-mkdirSync(outputRoot, { recursive: true })
-rmSync(stagingRoot, { recursive: true, force: true })
+function main() {
+  if (process.platform !== 'win32' || process.arch !== 'x64') {
+    throw new Error('Portable 目录当前必须在 Windows x64 上构建')
+  }
+  if (
+    portablePath === parse(portablePath).root ||
+    portablePath === root ||
+    portablePath === outputRoot
+  ) {
+    throw new Error(
+      `拒绝使用不安全的输出目录：${portablePath}`
+    )
+  }
+  const electronDist = ensureElectronRuntime()
+  mkdirSync(outputRoot, { recursive: true })
+  rmSync(stagingRoot, { recursive: true, force: true })
 
-for (const [label, script, args] of [
-  [
-    'Node 类型检查',
-    join(root, 'node_modules', 'typescript', 'bin', 'tsc'),
-    ['--noEmit', '-p', 'tsconfig.node.json']
-  ],
-  [
-    'Renderer 类型检查',
-    join(root, 'node_modules', 'typescript', 'bin', 'tsc'),
-    ['--noEmit', '-p', 'tsconfig.web.json']
-  ],
-  [
-    'Production bundle',
-    join(
-      root,
-      'node_modules',
-      'electron-vite',
-      'bin',
-      'electron-vite.js'
-    ),
-    ['build']
-  ]
-]) {
-  const buildResult = spawnSync(
+  for (const [label, script, args] of [
+    [
+      'Node 类型检查',
+      join(root, 'node_modules', 'typescript', 'bin', 'tsc'),
+      ['--noEmit', '-p', 'tsconfig.node.json']
+    ],
+    [
+      'Renderer 类型检查',
+      join(root, 'node_modules', 'typescript', 'bin', 'tsc'),
+      ['--noEmit', '-p', 'tsconfig.web.json']
+    ],
+    [
+      'Production bundle',
+      join(
+        root,
+        'node_modules',
+        'electron-vite',
+        'bin',
+        'electron-vite.js'
+      ),
+      ['build']
+    ]
+  ]) {
+    const buildResult = spawnSync(
+      process.execPath,
+      [script, ...args],
+      {
+        cwd: root,
+        env: process.env,
+        shell: false,
+        stdio: 'inherit',
+        windowsHide: true
+      }
+    )
+    if (buildResult.error) {
+      throw buildResult.error
+    }
+    if (buildResult.status !== 0) {
+      throw new Error(
+        `${label}失败（code ${buildResult.status ?? 1}）`
+      )
+    }
+  }
+
+  const result = spawnSync(
     process.execPath,
-    [script, ...args],
+    [
+      join(root, 'build', 'run-electron-builder.cjs'),
+      '--dir',
+      '--x64',
+      `--config.directories.output=${stagingRoot}`,
+      `--config.electronDist=${electronDist}`
+    ],
     {
       cwd: root,
       env: process.env,
@@ -317,55 +357,40 @@ for (const [label, script, args] of [
       windowsHide: true
     }
   )
-  if (buildResult.error) {
-    throw buildResult.error
+
+  if (result.error) {
+    rmSync(stagingRoot, { recursive: true, force: true })
+    throw result.error
   }
-  if (buildResult.status !== 0) {
+  if (result.status !== 0) {
+    rmSync(stagingRoot, { recursive: true, force: true })
     throw new Error(
-      `${label}失败（code ${buildResult.status ?? 1}）`
+      `Electron Builder 构建失败（code ${result.status ?? 1}）`
     )
   }
-}
-
-const result = spawnSync(
-  process.execPath,
-  [
-    join(root, 'node_modules', 'electron-builder', 'cli.js'),
-    '--dir',
-    '--x64',
-    `--config.directories.output=${stagingRoot}`,
-    `--config.electronDist=${electronDist}`
-  ],
-  {
-    cwd: root,
-    env: process.env,
-    shell: false,
-    stdio: 'inherit',
-    windowsHide: true
+  if (!statSync(unpackedPath, {
+    throwIfNoEntry: false
+  })?.isDirectory()) {
+    rmSync(stagingRoot, { recursive: true, force: true })
+    throw new Error('Electron Builder 未生成 portable 目录')
+  }
+  try {
+    pruneLocales(unpackedPath)
+    assertPortableOutput(unpackedPath)
+    replacePortableOutput(unpackedPath, portablePath)
+  } finally {
+    rmSync(stagingRoot, { recursive: true, force: true })
   }
-)
 
-if (result.error) {
-  rmSync(stagingRoot, { recursive: true, force: true })
-  throw result.error
-}
-if (result.status !== 0) {
-  rmSync(stagingRoot, { recursive: true, force: true })
-  throw new Error(
-    `Electron Builder 构建失败（code ${result.status ?? 1}）`
-  )
-}
-if (!statSync(unpackedPath, { throwIfNoEntry: false })?.isDirectory()) {
-  rmSync(stagingRoot, { recursive: true, force: true })
-  throw new Error('Electron Builder 未生成 portable 目录')
-}
-try {
-  pruneLocales(unpackedPath)
-  assertPortableOutput(unpackedPath)
-  replacePortableOutput(unpackedPath, portablePath)
-} finally {
-  rmSync(stagingRoot, { recursive: true, force: true })
+  console.log(`Portable 目录构建完成：${portablePath}`)
+  console.log(`启动文件：${join(portablePath, 'GoodBuddy.exe')}`)
 }
 
-console.log(`Portable 目录构建完成：${portablePath}`)
-console.log(`启动文件：${join(portablePath, 'GoodBuddy.exe')}`)
+module.exports = {
+  assertPortableOutput,
+  portableRequiredPaths
+}
+
+if (require.main === module) {
+  main()
+}

build/check-control-plane-package-installer.cjs

@@ -0,0 +1,74 @@
+const { createHash } = require('node:crypto')
+const { readFileSync } = require('node:fs')
+const { resolve } = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+const maximumInstallerBytes = 256 * 1024
+
+function verifyControlPlanePackageInstaller(
+  filePath = resolve(
+    'out',
+    'main',
+    'remote-package-installer.mjs'
+  )
+) {
+  const bytes = readFileSync(filePath)
+  if (
+    bytes.byteLength === 0 ||
+    bytes.byteLength > maximumInstallerBytes
+  ) {
+    throw new Error(
+      'Control-plane package installer exceeds its transfer limit'
+    )
+  }
+  const source = new TextDecoder('utf-8', {
+    fatal: true,
+    ignoreBOM: true
+  }).decode(bytes)
+  if (
+    /(?:^|\n)\s*(?:import|export)\b[^\r\n]*\bfrom\s*['"]\.{1,2}\//u.test(
+      source
+    ) ||
+    /(?:^|\n)\s*import\s*['"]\.{1,2}\//u.test(source) ||
+    /\bimport\s*\(\s*['"]\.{1,2}\//u.test(source)
+  ) {
+    throw new Error(
+      'Control-plane package installer is not a standalone bundle'
+    )
+  }
+  const syntax = spawnSync(
+    process.execPath,
+    ['--check', filePath],
+    {
+      encoding: 'utf8',
+      windowsHide: true
+    }
+  )
+  if (syntax.status !== 0) {
+    throw new Error(
+      `Control-plane package installer is not executable: ${
+        syntax.stderr.trim() || syntax.stdout.trim()
+      }`
+    )
+  }
+  return {
+    size: bytes.byteLength,
+    sha256: createHash('sha256').update(bytes).digest('hex')
+  }
+}
+
+if (require.main === module) {
+  const result = verifyControlPlanePackageInstaller(
+    process.argv[2]
+      ? resolve(process.argv[2])
+      : undefined
+  )
+  process.stdout.write(
+    `Control-plane package installer: ${result.size} bytes, sha256 ${result.sha256}\n`
+  )
+}
+
+module.exports = {
+  maximumInstallerBytes,
+  verifyControlPlanePackageInstaller
+}

build/create-site-release.cjs

@@ -0,0 +1,185 @@
+const {
+  mkdirSync,
+  readFileSync,
+  writeFileSync
+} = require('node:fs')
+const { dirname, resolve } = require('node:path')
+const {
+  expectedFormatForFile,
+  targetDefinitions
+} = require('./aggregate-release.cjs')
+
+const supportedTargets = new Map(
+  targetDefinitions.map((target) => [
+    `${target.platform}-${target.arch}`,
+    target
+  ])
+)
+
+function parseArguments(argv) {
+  const options = {}
+  const optionNames = new Map([
+    ['--manifest', 'manifest'],
+    ['--base-url', 'baseUrl'],
+    ['--output', 'output']
+  ])
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    const optionName = optionNames.get(argument)
+    if (optionName) {
+      const value = argv[index + 1]
+      if (!value) {
+        throw new Error(`${argument} 缺少值`)
+      }
+      options[optionName] = value
+      index += 1
+    } else {
+      throw new Error(`未知参数：${argument}`)
+    }
+  }
+  if (!options.manifest || !options.baseUrl || !options.output) {
+    throw new Error('必须指定 --manifest、--base-url 和 --output')
+  }
+  return {
+    manifest: resolve(options.manifest),
+    baseUrl: options.baseUrl,
+    output: resolve(options.output)
+  }
+}
+
+function validateBaseUrl(value) {
+  let url
+  try {
+    url = new URL(value)
+  } catch {
+    throw new Error(`OSS 基础地址无效：${value}`)
+  }
+  if (
+    url.protocol !== 'https:' ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error('OSS 基础地址必须是无凭据、查询参数和片段的 HTTPS 地址')
+  }
+  if (!url.pathname.endsWith('/')) {
+    url.pathname += '/'
+  }
+  return url
+}
+
+function assertFile(file, targetKey) {
+  if (
+    !file ||
+    typeof file.name !== 'string' ||
+    !/^GoodBuddy-[A-Za-z0-9._-]+$/u.test(file.name) ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    typeof file.sha256 !== 'string' ||
+    !/^[a-f0-9]{64}$/u.test(file.sha256)
+  ) {
+    throw new Error(`发布文件元数据无效：${targetKey}`)
+  }
+}
+
+function createSiteRelease(manifest, baseUrlValue) {
+  if (
+    !manifest ||
+    manifest.formatVersion !== 1 ||
+    manifest.productName !== 'GoodBuddy' ||
+    typeof manifest.version !== 'string' ||
+    !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(manifest.version) ||
+    !Array.isArray(manifest.targets)
+  ) {
+    throw new Error('聚合发布 manifest 元数据无效')
+  }
+  const baseUrl = validateBaseUrl(baseUrlValue)
+  const seenTargets = new Set()
+  const targets = {}
+  for (const target of manifest.targets) {
+    const key = `${target?.platform}-${target?.arch}`
+    const expectedTarget = supportedTargets.get(key)
+    const expectedFormats = expectedTarget?.formats
+    if (
+      !expectedFormats ||
+      seenTargets.has(key) ||
+      !Array.isArray(target.formats) ||
+      !Array.isArray(target.files) ||
+      target.formats.length !== expectedFormats.length ||
+      !expectedFormats.every(
+        (format, index) => target.formats[index] === format
+      ) ||
+      target.files.length !== expectedFormats.length
+    ) {
+      throw new Error(`发布目标元数据无效：${key}`)
+    }
+    const files = {}
+    for (const file of target.files) {
+      assertFile(file, key)
+      const format = expectedFormatForFile(
+        file.name,
+        expectedTarget
+      )
+      if (!format || !expectedFormats.includes(format) || files[format]) {
+        throw new Error(`发布文件格式无效：${file.name}`)
+      }
+      files[format] = {
+        name: file.name,
+        size: file.size,
+        sha256: file.sha256,
+        url: new URL(encodeURIComponent(file.name), baseUrl).href
+      }
+    }
+    if (expectedFormats.some((format) => !files[format])) {
+      throw new Error(`发布目标文件不完整：${key}`)
+    }
+    targets[key] = {
+      platform: target.platform,
+      arch: target.arch,
+      files
+    }
+    seenTargets.add(key)
+  }
+  if (seenTargets.size !== supportedTargets.size) {
+    throw new Error(
+      `发布目标数量错误：期望 ${supportedTargets.size}，实际 ${seenTargets.size}`
+    )
+  }
+  return {
+    formatVersion: 1,
+    productName: manifest.productName,
+    version: manifest.version,
+    targets,
+    checksumUrl: new URL('SHA256SUMS', baseUrl).href,
+    fallbackUrl: 'https://github.com/mesalogo/goodbuddy/releases/latest'
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv)
+  const manifest = JSON.parse(readFileSync(options.manifest, 'utf8'))
+  const siteRelease = createSiteRelease(manifest, options.baseUrl)
+  mkdirSync(dirname(options.output), { recursive: true })
+  writeFileSync(
+    options.output,
+    `${JSON.stringify(siteRelease, null, 2)}\n`,
+    'utf8'
+  )
+  console.log(`官网发布索引已生成：${options.output}`)
+}
+
+module.exports = {
+  createSiteRelease,
+  parseArguments,
+  validateBaseUrl
+}
+
+if (require.main === module) {
+  try {
+    main()
+  } catch (error) {
+    console.error(error)
+    process.exitCode = 1
+  }
+}

build/deepseek-harness-utility-smoke.cjs

@@ -0,0 +1,208 @@
+'use strict'
+
+const {
+  mkdirSync,
+  mkdtempSync
+} = require('node:fs')
+const {
+  rm,
+  writeFile
+} = require('node:fs/promises')
+const { tmpdir } = require('node:os')
+const {
+  isAbsolute,
+  join,
+  resolve
+} = require('node:path')
+const { app, utilityProcess } = require('electron/main')
+
+const protocol = 'goodbuddy.deepseek-harness.control'
+const controlVersion = 3
+const byteProtocol = 'goodbuddy.deepseek-harness.byte-stream'
+const byteProtocolVersion = 1
+const configuredHostPath =
+  process.env.GOODBUDDY_HARNESS_SMOKE_HOST
+const hostPath = configuredHostPath
+  ? isAbsolute(configuredHostPath)
+    ? configuredHostPath
+    : resolve(configuredHostPath)
+  : resolve('out/main/deepseek-harness-host-bootstrap.js')
+const workspace = mkdtempSync(
+  join(tmpdir(), 'goodbuddy-harness-electron-smoke-')
+)
+const dshHome = join(workspace, 'dsh-home')
+mkdirSync(dshHome)
+const configuredResultPath =
+  process.env.GOODBUDDY_HARNESS_SMOKE_RESULT
+const resultPath =
+  configuredResultPath && isAbsolute(configuredResultPath)
+    ? configuredResultPath
+    : join(
+        tmpdir(),
+        `goodbuddy-harness-utility-smoke-${process.pid}.json`
+      )
+
+let child
+let timeout
+let stderr = ''
+let settled = false
+let transportProbed = false
+
+void writeFile(
+  resultPath,
+  JSON.stringify({ status: 'checkpoint', stage: 'script-start' }),
+  'utf8'
+)
+
+async function checkpoint(stage, detail = '') {
+  await writeFile(
+    resultPath,
+    JSON.stringify({ status: 'checkpoint', stage, detail }),
+    'utf8'
+  )
+}
+
+function finish(status, detail = '') {
+  if (settled) {
+    return
+  }
+  settled = true
+  if (timeout) {
+    clearTimeout(timeout)
+  }
+  void writeFile(
+    resultPath,
+    JSON.stringify({
+      status,
+      detail: detail.slice(0, 4_096)
+    }),
+    'utf8'
+  )
+    .catch(() => undefined)
+    .finally(() => {
+      child?.kill()
+      void rm(workspace, {
+        recursive: true,
+        force: true,
+        maxRetries: 5,
+        retryDelay: 100
+      })
+        .catch(() => undefined)
+        .finally(() => {
+          if (!configuredResultPath) {
+            console.log(
+              `GoodBuddy packaged Harness smoke: ${status}`
+            )
+          }
+          app.exit(status === 'ready' ? 0 : 1)
+        })
+    })
+}
+
+async function run() {
+  await checkpoint('module-loaded')
+  await app.whenReady()
+  await checkpoint('app-ready')
+  child = utilityProcess.fork(hostPath, [], {
+    cwd: workspace,
+    env: {
+      PATH: process.env.PATH ?? '',
+      Path: process.env.Path ?? '',
+      PATHEXT: process.env.PATHEXT ?? '',
+      SystemRoot: process.env.SystemRoot ?? '',
+      COMSPEC: process.env.COMSPEC ?? '',
+      TEMP: process.env.TEMP ?? '',
+      TMP: process.env.TMP ?? '',
+      USERPROFILE: process.env.USERPROFILE ?? '',
+      APPDATA: process.env.APPDATA ?? '',
+      LOCALAPPDATA: process.env.LOCALAPPDATA ?? '',
+      DSH_HOME: dshHome,
+      DSH_TELEMETRY_DISABLED: '1',
+      OTEL_SDK_DISABLED: 'true'
+    },
+    serviceName: 'GoodBuddy DeepSeek Harness Smoke',
+    stdio: ['ignore', 'ignore', 'pipe'],
+    allowLoadingUnsignedLibraries: false,
+    disclaim: false
+  })
+  await checkpoint('utility-forked', String(child.pid ?? ''))
+
+  child.stderr?.on('data', (chunk) => {
+    stderr = (stderr + String(chunk)).slice(-4_096)
+  })
+  child.on('message', (message) => {
+    if (
+      message?.protocol === protocol &&
+      message.version === controlVersion &&
+      message.type === 'ready'
+    ) {
+      child.postMessage({
+        protocol: byteProtocol,
+        version: byteProtocolVersion,
+        type: 'data',
+        stream: 'stdin',
+        seq: 0,
+        bytes: Buffer.from('{}\n')
+      })
+      return
+    }
+    if (
+      message?.protocol === byteProtocol &&
+      message.version === byteProtocolVersion &&
+      message.type === 'ack' &&
+      message.stream === 'stdin' &&
+      message.seq === 0
+    ) {
+      transportProbed = true
+      finish('ready')
+      return
+    }
+    if (
+      message?.protocol === protocol &&
+      message.version === controlVersion &&
+      message.type === 'fatal'
+    ) {
+      finish('fatal', String(message.code))
+    }
+  })
+  child.on('exit', (code) => {
+    finish(
+      'exit',
+      `${code}:${stderr.replaceAll(/\s+/gu, ' ').trim()}`
+    )
+  })
+  child.postMessage({
+    protocol,
+    version: controlVersion,
+    type: 'start',
+    config: {
+      workspace,
+      dshHome,
+      baseUrl: 'https://gateway.example/openai/v1',
+      api: 'openai-completions',
+      provider: 'goodbuddy',
+      model: 'qwen-plus',
+      supportsImageInput: false,
+      requestHeaders: {},
+      harnessVersion: '0.1.2-rc.1',
+      credentialRefs: ['GOODBUDDY_HARNESS_MODEL_API_KEY'],
+      skillPackages: [],
+      extensionPackages: [],
+      maxFrameBytes: 8 * 1024 * 1024
+    }
+  })
+
+  timeout = setTimeout(() => {
+    finish(
+      'timeout',
+      `${transportProbed ? 'transport-probed ' : ''}${stderr.replaceAll(/\s+/gu, ' ').trim()}`
+    )
+  }, 20_000)
+}
+
+void run().catch((error) => {
+  finish(
+    'bootstrap-error',
+    error instanceof Error ? error.message : 'unknown error'
+  )
+})

build/electron-builder.release.cjs

@@ -0,0 +1 @@
+module.exports = require('../package.json').build

build/generate-icons.mjs

@@ -17,6 +17,25 @@ const darkSourcePath = join(
   'ChatGPT_qPkaIrLGsm.png'
 )
 const rendererAssetRoot = join(root, 'src', 'renderer', 'src', 'assets')
+const websiteAssetRoot = join(root, 'sites', 'assets')
+
+const lightTile = {
+  left: 40,
+  top: 32,
+  right: 704,
+  bottom: 696,
+  radius: 126,
+  edgeColor: [255, 255, 255]
+}
+
+const darkTile = {
+  left: 20,
+  top: 16,
+  right: 684,
+  bottom: 680,
+  radius: 126,
+  edgeColor: [15, 21, 31]
+}
 
 function cropSquare(source, size) {
   const output = new PNG({ width: size, height: size })
@@ -24,6 +43,102 @@ function cropSquare(source, size) {
   return output
 }
 
+function scaleTile(tile, sourceSize, targetSize) {
+  const scale = targetSize / sourceSize
+  return {
+    left: tile.left * scale,
+    top: tile.top * scale,
+    right: tile.right * scale,
+    bottom: tile.bottom * scale,
+    radius: tile.radius * scale,
+    edgeColor: tile.edgeColor
+  }
+}
+
+function cropTile(source, tile) {
+  const width = Math.round(tile.right - tile.left)
+  const height = Math.round(tile.bottom - tile.top)
+  if (width !== height || width <= 0) {
+    throw new Error('图标卡片裁剪区域必须是有效正方形')
+  }
+  const output = new PNG({ width, height })
+  PNG.bitblt(
+    source,
+    output,
+    Math.round(tile.left),
+    Math.round(tile.top),
+    width,
+    height,
+    0,
+    0
+  )
+  return {
+    image: output,
+    tile: {
+      left: 0,
+      top: 0,
+      right: width,
+      bottom: height,
+      radius: tile.radius,
+      edgeColor: tile.edgeColor
+    }
+  }
+}
+
+function roundedRectangleDistance(x, y, tile) {
+  const centerX = (tile.left + tile.right) / 2
+  const centerY = (tile.top + tile.bottom) / 2
+  const halfWidth = (tile.right - tile.left) / 2
+  const halfHeight = (tile.bottom - tile.top) / 2
+  const offsetX = Math.abs(x - centerX) - (halfWidth - tile.radius)
+  const offsetY = Math.abs(y - centerY) - (halfHeight - tile.radius)
+  return (
+    Math.hypot(Math.max(offsetX, 0), Math.max(offsetY, 0)) +
+    Math.min(Math.max(offsetX, offsetY), 0) -
+    tile.radius
+  )
+}
+
+function applyRoundedTransparency(image, tile) {
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      const offset = pixelOffset(image, x, y)
+      const distance = roundedRectangleDistance(x + 0.5, y + 0.5, tile)
+      const coverage = Math.min(Math.max(0.5 - distance, 0), 1)
+      if (coverage >= 1) {
+        if (distance > -2 && image.data[offset + 3] < 255) {
+          image.data[offset] = tile.edgeColor[0]
+          image.data[offset + 1] = tile.edgeColor[1]
+          image.data[offset + 2] = tile.edgeColor[2]
+        }
+        continue
+      }
+      image.data[offset] = tile.edgeColor[0]
+      image.data[offset + 1] = tile.edgeColor[1]
+      image.data[offset + 2] = tile.edgeColor[2]
+      image.data[offset + 3] = Math.round(
+        image.data[offset + 3] * coverage
+      )
+    }
+  }
+}
+
+function createRoundedIcon(source, tile, size) {
+  const cropped = cropTile(source, tile)
+  applyRoundedTransparency(cropped.image, cropped.tile)
+  const output = resize(
+    cropped.image,
+    size,
+    size,
+    'bicubicInterpolation'
+  )
+  applyRoundedTransparency(
+    output,
+    scaleTile(cropped.tile, cropped.image.width, size)
+  )
+  return output
+}
+
 function pixelOffset(image, x, y) {
   return (y * image.width + x) * 4
 }
@@ -119,6 +234,51 @@ function assertTaskbarIcon(image) {
   }
 }
 
+function assertTransparentCorners(image, label) {
+  const corners = [
+    pixelOffset(image, 0, 0),
+    pixelOffset(image, image.width - 1, 0),
+    pixelOffset(image, 0, image.height - 1),
+    pixelOffset(image, image.width - 1, image.height - 1)
+  ]
+  if (corners.some((offset) => image.data[offset + 3] !== 0)) {
+    throw new Error(`${label} 的圆角外侧必须透明`)
+  }
+}
+
+function assertDarkEdgeHasNoWhiteFringe(image) {
+  const edgeWidth = Math.max(4, Math.round(image.width * 0.08))
+  for (let y = 0; y < image.height; y += 1) {
+    for (let x = 0; x < image.width; x += 1) {
+      if (
+        x >= edgeWidth &&
+        x < image.width - edgeWidth &&
+        y >= edgeWidth &&
+        y < image.height - edgeWidth
+      ) {
+        continue
+      }
+      const offset = pixelOffset(image, x, y)
+      const alpha = image.data[offset + 3]
+      if (
+        alpha > 0 &&
+        alpha < 255 &&
+        Math.max(
+          image.data[offset],
+          image.data[offset + 1],
+          image.data[offset + 2]
+        ) > 96
+      ) {
+        throw new Error(
+          `暗色图标的透明边缘仍包含白色像素：${x},${y} ` +
+            `rgba(${image.data[offset]},${image.data[offset + 1]},` +
+            `${image.data[offset + 2]},${alpha})`
+        )
+      }
+    }
+  }
+}
+
 function repairDarkCursor(dark, light) {
   for (let y = 570; y <= 606; y += 1) {
     const backgroundOffset = pixelOffset(dark, 640, y)
@@ -197,22 +357,31 @@ async function main() {
   repairDarkCursor(darkSquare, lightSquare)
   assertCursorRemoved(lightSquare, darkSquare)
 
-  const light = resize(lightSquare, 512, 512, 'bicubicInterpolation')
-  const dark = resize(darkSquare, 512, 512, 'bicubicInterpolation')
   const taskbar = createTaskbarIcon(lightSquare)
+  const light = createRoundedIcon(lightSquare, lightTile, 512)
+  const dark = createRoundedIcon(darkSquare, darkTile, 512)
+  const rendererLight = createRoundedIcon(lightSquare, lightTile, 128)
+  const rendererDark = createRoundedIcon(darkSquare, darkTile, 128)
   assertTaskbarIcon(taskbar)
+  assertTransparentCorners(light, '亮色图标')
+  assertTransparentCorners(dark, '暗色图标')
+  assertTransparentCorners(rendererLight, '亮色界面图标')
+  assertTransparentCorners(rendererDark, '暗色界面图标')
+  assertTransparentCorners(taskbar, '任务栏图标')
+  assertDarkEdgeHasNoWhiteFringe(dark)
+  assertDarkEdgeHasNoWhiteFringe(rendererDark)
   const tray = resize(taskbar, 32, 32, 'bicubicInterpolation')
+  assertTransparentCorners(tray, '托盘图标')
   const lightPng = PNG.sync.write(light)
   const darkPng = PNG.sync.write(dark)
   const taskbarPng = PNG.sync.write(taskbar)
   const trayPng = PNG.sync.write(tray)
-  const rendererLightPng = PNG.sync.write(
-    resize(light, 128, 128, 'bicubicInterpolation')
-  )
-  const rendererDarkPng = PNG.sync.write(
-    resize(dark, 128, 128, 'bicubicInterpolation')
-  )
-  await mkdir(rendererAssetRoot, { recursive: true })
+  const rendererLightPng = PNG.sync.write(rendererLight)
+  const rendererDarkPng = PNG.sync.write(rendererDark)
+  await Promise.all([
+    mkdir(rendererAssetRoot, { recursive: true }),
+    mkdir(websiteAssetRoot, { recursive: true })
+  ])
 
   const outputs = [
     [join(root, 'build', 'icon-light.png'), lightPng],
@@ -221,7 +390,9 @@ async function main() {
     [join(root, 'build', 'icon-taskbar.png'), taskbarPng],
     [join(root, 'build', 'icon-tray.png'), trayPng],
     [join(rendererAssetRoot, 'goodbuddy-light.png'), rendererLightPng],
-    [join(rendererAssetRoot, 'goodbuddy-dark.png'), rendererDarkPng]
+    [join(rendererAssetRoot, 'goodbuddy-dark.png'), rendererDarkPng],
+    [join(websiteAssetRoot, 'goodbuddy-light.png'), rendererLightPng],
+    [join(websiteAssetRoot, 'goodbuddy-dark.png'), rendererDarkPng]
   ]
   await Promise.all(outputs.map(([path, contents]) => writeFile(path, contents)))
 

build/loongarch-cross/.dockerignore

@@ -0,0 +1 @@
+results

build/loongarch-cross/Dockerfile

@@ -0,0 +1,54 @@
+FROM ubuntu:26.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+ARG RUST_TOOLCHAIN=1.93.1
+
+RUN apt-get update \
+  && apt-get install --yes --no-install-recommends \
+    binutils-loongarch64-linux-gnu \
+    build-essential \
+    ca-certificates \
+    cmake \
+    dpkg-dev \
+    fakeroot \
+    file \
+    g++-loongarch64-linux-gnu \
+    gcc-loongarch64-linux-gnu \
+    libc6-dev-loong64-cross \
+    make \
+    ninja-build \
+    node-gyp \
+    nodejs \
+    npm \
+    pkg-config \
+    python3 \
+    qemu-user \
+    rustup \
+    tar \
+    xz-utils \
+  && rm -rf /var/lib/apt/lists/*
+
+RUN rustup set profile minimal \
+  && rustup toolchain install "${RUST_TOOLCHAIN}" \
+    --target loongarch64-unknown-linux-gnu
+
+ENV CC=loongarch64-linux-gnu-gcc \
+    CXX=loongarch64-linux-gnu-g++ \
+    AR=loongarch64-linux-gnu-ar \
+    RANLIB=loongarch64-linux-gnu-ranlib \
+    STRIP=loongarch64-linux-gnu-strip \
+    CARGO_BUILD_TARGET=loongarch64-unknown-linux-gnu \
+    CARGO_TARGET_LOONGARCH64_UNKNOWN_LINUX_GNU_LINKER=loongarch64-linux-gnu-gcc \
+    RUSTUP_TOOLCHAIN=${RUST_TOOLCHAIN}
+
+COPY toolchain.cmake /opt/goodbuddy/loongarch64-toolchain.cmake
+COPY probe.sh /usr/local/bin/goodbuddy-loongarch-cross-probe
+COPY preview-deb.sh /usr/local/bin/goodbuddy-loongarch-preview-deb
+
+RUN chmod 0755 \
+  /usr/local/bin/goodbuddy-loongarch-cross-probe \
+  /usr/local/bin/goodbuddy-loongarch-preview-deb
+
+WORKDIR /work
+
+ENTRYPOINT ["/usr/local/bin/goodbuddy-loongarch-cross-probe"]

build/loongarch-cross/README.md

@@ -0,0 +1,78 @@
+# LoongArch cross-compilation probe
+
+This directory defines an isolated Ubuntu 26.04 amd64 environment for probing
+GoodBuddy's Linux `loong64` prerequisites. It does not build Electron or
+OpenCode.
+
+The image includes:
+
+- GCC and G++ targeting `loongarch64-linux-gnu`
+- A LoongArch glibc development sysroot
+- QEMU user-mode execution
+- CMake and Ninja
+- Rust's `loongarch64-unknown-linux-gnu` target
+- Node.js, npm, and node-gyp
+
+The probe validates:
+
+- C, C++, CMake, and Rust LoongArch ELF output
+- C, C++, and Rust execution through QEMU
+- A minimal NAPI-RS Rust addon cross-build
+- A Debian package with `Architecture: loong64`
+- Koffi 3.1.4's published LoongArch glibc binding and the absence of a musl
+  binding
+- The current npm availability of an `@napi-rs/canvas` LoongArch package
+- A source cross-build of node-pty 1.1.0
+
+The node-pty probe uses its upstream node-gyp 11.4.2 dependency. Ubuntu's
+distribution node-gyp unconditionally links Linux addons with `-lnode`, which
+is appropriate for Ubuntu's shared Node.js package but not for Electron native
+addons.
+
+Build and run it from this directory on an amd64 Docker host:
+
+```sh
+docker build \
+  --tag goodbuddy-loongarch-cross:ubuntu-26.04 \
+  .
+
+mkdir -p results
+docker run --rm \
+  --volume "$PWD/results:/results" \
+  goodbuddy-loongarch-cross:ubuntu-26.04
+```
+
+Each run writes to a new UTC timestamped directory below `results`. A passing
+run contains `summary.txt`, `SHA256SUMS`, the generated ELF files, and the
+probe DEB.
+
+QEMU only checks user-mode execution against the cross sysroot. Native Electron
+loading, PTY behavior, desktop integration, GPU, audio, and packaging must
+still be validated on a real Debian `loong64` host.
+
+Koffi 3.1.4 currently publishes only `linux_loong64/koffi.node`, not a
+`musl_loong64` binding. That is sufficient for a Debian desktop package but
+does not satisfy GoodBuddy Agent's current dual-glibc/musl bundle contract.
+
+The NAPI-RS probe confirms that a Rust Node addon can be cross-compiled. It
+does not build Canvas itself, whose Skia dependency requires a separate port
+and native validation.
+
+## Experimental desktop preview
+
+`prepare-input.cjs` creates the architecture-neutral GoodBuddy input archive.
+`preview-deb.sh` combines it with the verified community Electron 42.3.0
+LoongArch shell and produces an isolated `goodbuddy-loongarch-preview` DEB.
+
+The preview:
+
+- uses a separate application name and user-data directory;
+- includes the direct model path and Continue runtime;
+- cross-builds the input lockfile's node-pty version against Electron 42.3.0;
+- includes Koffi's LoongArch glibc binding;
+- does not include GoodBuddy Agent, Remote Runtime, OpenCode, or native Canvas;
+- is not part of the production release matrix.
+
+See
+[`docs/development/loongarch-preview-build.md`](../../docs/development/loongarch-preview-build.md)
+for the complete build and validation procedure.

build/loongarch-cross/prepare-input.cjs

@@ -0,0 +1,108 @@
+const {
+  existsSync,
+  mkdirSync,
+  renameSync,
+  rmSync,
+  statSync
+} = require('node:fs')
+const { dirname, join, resolve } = require('node:path')
+const tar = require('tar')
+
+const root = join(__dirname, '..', '..')
+const defaultOutput = join(
+  root,
+  'dist',
+  'loongarch-cross',
+  'goodbuddy-loongarch-cross-input.tgz'
+)
+const inputPaths = [
+  'LICENSE',
+  'agent-runtime-lock.json',
+  'package.json',
+  'package-lock.json',
+  'remote-runtime-lock.json',
+  'out',
+  'resources/agent-release-keys.json',
+  'resources/release-notes.json',
+  'resources/skills',
+  'build/icon.png',
+  'build/icon-tray.png',
+  'node_modules/@continuedev/cli/package.json',
+  'node_modules/@continuedev/cli/dist/cn.js',
+  'node_modules/@continuedev/cli/dist/index.js',
+  'node_modules/@continuedev/cli/dist/xhr-sync-worker.js',
+  'node_modules/npm'
+]
+
+function parseArguments(argv) {
+  const options = { output: defaultOutput }
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index]
+    if (argument !== '--output') {
+      throw new Error(`未知参数：${argument}`)
+    }
+    const value = argv[index + 1]
+    if (!value) {
+      throw new Error('--output 缺少值')
+    }
+    options.output = resolve(value)
+    index += 1
+  }
+  return options
+}
+
+function verifyInputs(projectRoot = root) {
+  for (const relativePath of inputPaths) {
+    if (!existsSync(join(projectRoot, relativePath))) {
+      throw new Error(`龙芯交叉构建输入缺失：${relativePath}`)
+    }
+  }
+}
+
+async function createInputArchive(outputPath, projectRoot = root) {
+  verifyInputs(projectRoot)
+  const resolvedOutput = resolve(outputPath)
+  const temporaryOutput = `${resolvedOutput}.partial-${process.pid}`
+  mkdirSync(dirname(resolvedOutput), { recursive: true })
+  rmSync(temporaryOutput, { force: true })
+  try {
+    await tar.c(
+      {
+        cwd: projectRoot,
+        file: temporaryOutput,
+        gzip: true,
+        portable: true,
+        noMtime: true
+      },
+      inputPaths
+    )
+    if (!statSync(temporaryOutput).isFile()) {
+      throw new Error('龙芯交叉构建输入归档未生成')
+    }
+    rmSync(resolvedOutput, { force: true })
+    renameSync(temporaryOutput, resolvedOutput)
+  } finally {
+    rmSync(temporaryOutput, { force: true })
+  }
+  return resolvedOutput
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv)
+  const output = await createInputArchive(options.output)
+  console.log(`龙芯交叉构建输入已生成：${output}`)
+}
+
+module.exports = {
+  createInputArchive,
+  inputPaths,
+  parseArguments,
+  verifyInputs
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error)
+    process.exitCode = 1
+  })
+}

build/loongarch-cross/preview-deb.sh

@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+input_archive="${1:?missing GoodBuddy input archive}"
+electron_archive="${2:?missing Electron loong64 archive}"
+output_root="${3:-/preview-output}"
+
+electron_version="42.3.0"
+electron_sha256="92b0ca0c9c18ed90166918a4ac1970266c4fa967aee9277031b3b250b905526e"
+koffi_version="3.1.4"
+node_gyp_version="11.4.2"
+preview_iteration="1"
+application_directory="GoodBuddy-LoongArch-Preview"
+executable_name="goodbuddy-loongarch-preview"
+
+assert_file() {
+  if ! test -f "$1"; then
+    echo "missing required file: $1" >&2
+    exit 1
+  fi
+}
+
+assert_loongarch_elf() {
+  local file_path="$1"
+  assert_file "${file_path}"
+  file "${file_path}"
+  readelf -h "${file_path}" | grep -Eq \
+    'Machine:[[:space:]]+(LoongArch|Loongson Loongarch)'
+}
+
+assert_file "${input_archive}"
+assert_file "${electron_archive}"
+mkdir -p "${output_root}"
+
+actual_electron_sha256="$(
+  sha256sum "${electron_archive}" | cut -d ' ' -f 1
+)"
+if test "${actual_electron_sha256}" != "${electron_sha256}"; then
+  echo "Electron loong64 archive digest mismatch" >&2
+  exit 1
+fi
+
+run_id="$(date -u +%Y%m%dT%H%M%SZ)"
+work_root="${output_root}/.work-${run_id}"
+input_root="${work_root}/input"
+package_root="${work_root}/package"
+application_root="${package_root}/opt/${application_directory}"
+resources_root="${application_root}/resources"
+app_root="${resources_root}/app"
+artifact_root="${output_root}/${run_id}"
+
+if test -e "${work_root}" || test -e "${artifact_root}"; then
+  echo "refusing to reuse preview build directory" >&2
+  exit 1
+fi
+
+cleanup() {
+  rm -rf "${work_root}"
+}
+trap cleanup EXIT
+
+mkdir -p "${input_root}" "${app_root}" "${artifact_root}"
+tar -xzf "${input_archive}" -C "${input_root}"
+
+project_version="$(
+  node -p \
+    "require('${input_root}/package.json').version"
+)"
+node_pty_version="$(
+  node -p \
+    "require('${input_root}/package-lock.json').packages['node_modules/node-pty'].version"
+)"
+preview_version="${project_version}-loong64-preview.${preview_iteration}"
+deb_version="${project_version}~loong64preview${preview_iteration}"
+artifact_name="GoodBuddy-${project_version}-linux-loong64-preview.deb"
+
+echo "== extract verified Electron shell =="
+python3 -m zipfile -e "${electron_archive}" "${application_root}"
+assert_loongarch_elf "${application_root}/electron"
+mv "${application_root}/electron" \
+  "${application_root}/${executable_name}"
+chmod 0755 "${application_root}/${executable_name}"
+rm -f "${resources_root}/default_app.asar"
+if test -f "${application_root}/chrome-sandbox"; then
+  chmod 4755 "${application_root}/chrome-sandbox"
+fi
+
+echo "== install production JavaScript dependencies =="
+cp "${input_root}/package.json" "${app_root}/package.json"
+cp "${input_root}/package-lock.json" "${app_root}/package-lock.json"
+(
+  cd "${app_root}"
+  npm ci \
+    --ignore-scripts \
+    --omit=dev \
+    --cpu=loong64 \
+    --os=linux
+)
+
+rm -rf \
+  "${app_root}/node_modules/@esbuild" \
+  "${app_root}/node_modules/@img" \
+  "${app_root}/node_modules/@rollup"
+find "${app_root}/node_modules/@koromix" \
+  -mindepth 1 \
+  -maxdepth 1 \
+  -type d \
+  -exec rm -rf -- {} + 2>/dev/null || true
+find "${app_root}/node_modules/@napi-rs" \
+  -mindepth 1 \
+  -maxdepth 1 \
+  -type d \
+  -name 'canvas-*' \
+  -exec rm -rf -- {} + 2>/dev/null || true
+
+node - "${input_root}" "${app_root}/package.json" \
+  "${preview_version}" <<'NODE'
+const { readFileSync, writeFileSync } = require('node:fs')
+const [inputRoot, outputPath, version] = process.argv.slice(2)
+const metadata = JSON.parse(
+  readFileSync(`${inputRoot}/package.json`, 'utf8')
+)
+metadata.name = 'goodbuddy-loongarch-preview'
+metadata.productName = 'GoodBuddy LoongArch Preview'
+metadata.desktopName = 'GoodBuddy LoongArch Preview'
+metadata.version = version
+metadata.main = './out/main/index.js'
+delete metadata.build
+delete metadata.devDependencies
+delete metadata.optionalDependencies
+writeFileSync(outputPath, `${JSON.stringify(metadata, null, 2)}\n`)
+NODE
+rm -f "${app_root}/package-lock.json"
+
+echo "== stage target Koffi binding =="
+koffi_stage="${work_root}/koffi"
+mkdir -p "${koffi_stage}"
+koffi_pack_json="$(
+  npm pack \
+    "@koromix/koffi-linux-loong64@${koffi_version}" \
+    --ignore-scripts \
+    --json \
+    --pack-destination "${koffi_stage}"
+)"
+koffi_archive="$(
+  node -e \
+    'const value=JSON.parse(process.argv[1]); process.stdout.write(value[0].filename)' \
+    "${koffi_pack_json}"
+)"
+koffi_integrity="$(
+  node -p \
+    "require('${input_root}/package-lock.json').packages['node_modules/@koromix/koffi-linux-loong64'].integrity"
+)"
+node - "${koffi_stage}/${koffi_archive}" \
+  "${koffi_integrity}" <<'NODE'
+const { createHash } = require('node:crypto')
+const { readFileSync } = require('node:fs')
+const [filePath, integrity] = process.argv.slice(2)
+const [algorithm, expected] = integrity.split('-', 2)
+const actual = createHash(algorithm)
+  .update(readFileSync(filePath))
+  .digest('base64')
+if (actual !== expected) {
+  throw new Error('Koffi archive integrity mismatch')
+}
+NODE
+koffi_target="${app_root}/node_modules/@koromix/koffi-linux-loong64"
+mkdir -p "${koffi_target}"
+tar \
+  -xzf "${koffi_stage}/${koffi_archive}" \
+  -C "${koffi_target}" \
+  --strip-components 1
+koffi_binding="${koffi_target}/linux_loong64/koffi.node"
+assert_loongarch_elf "${koffi_binding}"
+
+echo "== cross-build node-pty ${node_pty_version} for Electron ${electron_version} =="
+node_gyp_root="${work_root}/node-gyp"
+npm install \
+  --ignore-scripts \
+  --prefix "${node_gyp_root}" \
+  "node-gyp@${node_gyp_version}"
+node_pty_root="${app_root}/node_modules/node-pty"
+test "$(
+  node -p "require('${node_pty_root}/package.json').version"
+)" = "${node_pty_version}"
+rm -rf "${node_pty_root}/build" "${node_pty_root}/prebuilds"
+(
+  cd "${node_pty_root}"
+  CC=loongarch64-linux-gnu-gcc \
+  CXX=loongarch64-linux-gnu-g++ \
+  npm_config_arch=loong64 \
+  npm_config_target_arch=loong64 \
+  npm_config_runtime=electron \
+  npm_config_target="${electron_version}" \
+  npm_config_disturl=https://electronjs.org/headers \
+  "${node_gyp_root}/node_modules/.bin/node-gyp" rebuild \
+    --arch=loong64
+)
+node_pty_binding="${node_pty_root}/build/Release/pty.node"
+assert_loongarch_elf "${node_pty_binding}"
+
+echo "== stage GoodBuddy application and architecture-neutral runtimes =="
+cp -a "${input_root}/out" "${app_root}/out"
+mkdir -p \
+  "${resources_root}/licenses" \
+  "${resources_root}/runtimes" \
+  "${resources_root}/skills"
+cp -a "${input_root}/resources/skills/." "${resources_root}/skills/"
+cp "${input_root}/resources/release-notes.json" \
+  "${resources_root}/release-notes.json"
+cp "${input_root}/resources/agent-release-keys.json" \
+  "${resources_root}/agent-release-keys.json"
+cp "${input_root}/agent-runtime-lock.json" \
+  "${resources_root}/agent-runtime-lock.json"
+cp "${input_root}/remote-runtime-lock.json" \
+  "${resources_root}/remote-runtime-lock.json"
+cp "${input_root}/build/icon.png" "${resources_root}/icon.png"
+cp "${input_root}/build/icon-tray.png" \
+  "${resources_root}/tray-icon.png"
+cp "${input_root}/LICENSE" \
+  "${resources_root}/licenses/GoodBuddy-0BSD.txt"
+mkdir -p "${resources_root}/runtimes/continue/dist"
+cp "${input_root}/node_modules/@continuedev/cli/package.json" \
+  "${resources_root}/runtimes/continue/package.json"
+cp "${input_root}/node_modules/@continuedev/cli/dist/cn.js" \
+  "${resources_root}/runtimes/continue/dist/cn.js"
+cp "${input_root}/node_modules/@continuedev/cli/dist/index.js" \
+  "${resources_root}/runtimes/continue/dist/index.js"
+cp "${input_root}/node_modules/@continuedev/cli/dist/xhr-sync-worker.js" \
+  "${resources_root}/runtimes/continue/dist/xhr-sync-worker.js"
+cp -a "${input_root}/node_modules/npm" \
+  "${resources_root}/runtimes/npm"
+
+echo "== reject foreign native addons =="
+while IFS= read -r -d '' native_addon; do
+  assert_loongarch_elf "${native_addon}"
+done < <(
+  find "${app_root}/node_modules" \
+    -type f \
+    -name '*.node' \
+    -print0
+)
+
+if test -e "${resources_root}/agents" ||
+  test -e "${resources_root}/remote-runtimes" ||
+  test -e "${resources_root}/runtimes/opencode"
+then
+  echo "preview package unexpectedly contains Agent or OpenCode payload" >&2
+  exit 1
+fi
+
+echo "== build isolated preview DEB =="
+mkdir -p \
+  "${package_root}/DEBIAN" \
+  "${package_root}/usr/bin" \
+  "${package_root}/usr/share/applications" \
+  "${package_root}/usr/share/icons/hicolor/512x512/apps"
+ln -s \
+  "/opt/${application_directory}/${executable_name}" \
+  "${package_root}/usr/bin/${executable_name}"
+cp "${input_root}/build/icon.png" \
+  "${package_root}/usr/share/icons/hicolor/512x512/apps/${executable_name}.png"
+cat > "${package_root}/usr/share/applications/${executable_name}.desktop" <<EOF
+[Desktop Entry]
+Name=GoodBuddy LoongArch Preview
+Comment=GoodBuddy LoongArch 主体预览版
+Exec=/opt/${application_directory}/${executable_name} %U
+Terminal=false
+Type=Application
+Icon=${executable_name}
+Categories=Utility;
+StartupWMClass=GoodBuddy LoongArch Preview
+EOF
+cat > "${package_root}/DEBIAN/control" <<EOF
+Package: goodbuddy-loongarch-preview
+Version: ${deb_version}
+Architecture: loong64
+Maintainer: MesaLogo
+Section: utils
+Priority: optional
+Depends: libasound2t64, libatspi2.0-0t64, libgbm1, libgtk-3-0t64, libnotify4, libnss3, libpulse0, libsecret-1-0, libuuid1, libxss1, libxtst6, xdg-utils
+Description: GoodBuddy LoongArch desktop preview
+ Experimental LoongArch desktop build without bundled Agent, Remote Runtime,
+ OpenCode, or native Canvas image decoding.
+EOF
+
+artifact="${artifact_root}/${artifact_name}"
+dpkg-deb --root-owner-group --build "${package_root}" "${artifact}"
+
+echo "== verify preview package =="
+test "$(dpkg-deb --field "${artifact}" Architecture)" = "loong64"
+verify_root="${work_root}/verify"
+mkdir "${verify_root}"
+dpkg-deb --extract "${artifact}" "${verify_root}"
+assert_loongarch_elf \
+  "${verify_root}/opt/${application_directory}/${executable_name}"
+assert_loongarch_elf \
+  "${verify_root}/opt/${application_directory}/resources/app/${node_pty_binding#${app_root}/}"
+assert_loongarch_elf \
+  "${verify_root}/opt/${application_directory}/resources/app/${koffi_binding#${app_root}/}"
+
+(
+  cd "${artifact_root}"
+  sha256sum "${artifact_name}" > SHA256SUMS
+)
+cat > "${artifact_root}/preview-manifest.json" <<EOF
+{
+  "formatVersion": 1,
+  "product": "GoodBuddy LoongArch Preview",
+  "goodBuddyVersion": "${project_version}",
+  "previewVersion": "${preview_version}",
+  "electronVersion": "${electron_version}",
+  "architecture": "loong64",
+  "artifact": "${artifact_name}",
+  "bundledAgent": false,
+  "bundledRemoteRuntime": false,
+  "bundledOpenCode": false,
+  "nativeCanvas": false,
+  "continueRuntime": true,
+  "nodePty": true,
+  "koffiGlibc": true,
+  "nativeLaunchVerified": false
+}
+EOF
+
+cat "${artifact_root}/preview-manifest.json"
+echo "artifact=${artifact}"

build/loongarch-cross/probe.sh

@@ -0,0 +1,314 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+results_root="${1:-/results}"
+run_id="$(date -u +%Y%m%dT%H%M%SZ)"
+results="${results_root}/${run_id}"
+mkdir -p "${results}"
+
+log="${results}/probe.log"
+exec > >(tee "${log}") 2>&1
+
+assert_loongarch_elf() {
+  local file_path="$1"
+  file "${file_path}"
+  readelf -h "${file_path}" | grep -Eq \
+    'Machine:[[:space:]]+(LoongArch|Loongson Loongarch)'
+}
+
+echo "== tool versions =="
+loongarch64-linux-gnu-gcc --version | head -n 1
+loongarch64-linux-gnu-g++ --version | head -n 1
+loongarch64-linux-gnu-ld --version | head -n 1
+qemu-loongarch64 --version | head -n 1
+node --version
+npm --version
+node-gyp --version
+rustc --version
+cargo --version
+cmake --version | head -n 1
+
+echo "== C probe =="
+cat > "${results}/hello.c" <<'EOF'
+#include <stdio.h>
+
+int main(void) {
+  puts("goodbuddy-loongarch-c-ok");
+  return 0;
+}
+EOF
+
+loongarch64-linux-gnu-gcc \
+  -O2 \
+  -Wall \
+  -Wextra \
+  -Werror \
+  "${results}/hello.c" \
+  -o "${results}/hello-c"
+assert_loongarch_elf "${results}/hello-c"
+test "$(
+  qemu-loongarch64 \
+    -L /usr/loongarch64-linux-gnu \
+    "${results}/hello-c"
+)" = "goodbuddy-loongarch-c-ok"
+
+echo "== C++ probe =="
+cat > "${results}/hello.cpp" <<'EOF'
+#include <iostream>
+#include <string_view>
+
+int main() {
+  constexpr std::string_view message{"goodbuddy-loongarch-cpp-ok"};
+  std::cout << message << '\n';
+  return 0;
+}
+EOF
+
+loongarch64-linux-gnu-g++ \
+  -std=c++20 \
+  -O2 \
+  -Wall \
+  -Wextra \
+  -Werror \
+  "${results}/hello.cpp" \
+  -o "${results}/hello-cpp"
+assert_loongarch_elf "${results}/hello-cpp"
+test "$(
+  qemu-loongarch64 \
+    -L /usr/loongarch64-linux-gnu \
+    "${results}/hello-cpp"
+)" = "goodbuddy-loongarch-cpp-ok"
+
+echo "== CMake probe =="
+mkdir "${results}/cmake-source"
+cat > "${results}/cmake-source/CMakeLists.txt" <<'EOF'
+cmake_minimum_required(VERSION 3.20)
+project(goodbuddy_loongarch_probe LANGUAGES C)
+add_executable(goodbuddy-cmake-probe main.c)
+target_compile_options(
+  goodbuddy-cmake-probe
+  PRIVATE -Wall -Wextra -Werror
+)
+EOF
+cp "${results}/hello.c" "${results}/cmake-source/main.c"
+cmake \
+  -S "${results}/cmake-source" \
+  -B "${results}/cmake-build" \
+  -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_TOOLCHAIN_FILE=/opt/goodbuddy/loongarch64-toolchain.cmake
+cmake --build "${results}/cmake-build"
+assert_loongarch_elf \
+  "${results}/cmake-build/goodbuddy-cmake-probe"
+
+echo "== Rust probe =="
+mkdir -p "${results}/rust-probe/src"
+cat > "${results}/rust-probe/Cargo.toml" <<'EOF'
+[package]
+name = "goodbuddy-loongarch-rust-probe"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+EOF
+cat > "${results}/rust-probe/src/main.rs" <<'EOF'
+fn main() {
+    println!("goodbuddy-loongarch-rust-ok");
+}
+EOF
+cargo build \
+  --release \
+  --manifest-path "${results}/rust-probe/Cargo.toml"
+rust_binary="$(
+  find "${results}/rust-probe/target" \
+    -type f \
+    -name goodbuddy-loongarch-rust-probe \
+    -print \
+    -quit
+)"
+test -n "${rust_binary}"
+assert_loongarch_elf "${rust_binary}"
+test "$(
+  qemu-loongarch64 \
+    -L /usr/loongarch64-linux-gnu \
+    "${rust_binary}"
+)" = "goodbuddy-loongarch-rust-ok"
+
+echo "== NAPI-RS Rust addon probe =="
+mkdir -p "${results}/napi-rs-probe/src"
+cat > "${results}/napi-rs-probe/Cargo.toml" <<'EOF'
+[package]
+name = "goodbuddy-loongarch-napi-probe"
+version = "0.1.0"
+edition = "2024"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "3", default-features = false, features = ["napi8"] }
+napi-derive = "3"
+
+[build-dependencies]
+napi-build = "2"
+EOF
+cat > "${results}/napi-rs-probe/build.rs" <<'EOF'
+fn main() {
+    napi_build::setup();
+}
+EOF
+cat > "${results}/napi-rs-probe/src/lib.rs" <<'EOF'
+use napi_derive::napi;
+
+#[napi]
+pub fn architecture_probe() -> &'static str {
+    "loong64"
+}
+EOF
+cargo build \
+  --release \
+  --manifest-path "${results}/napi-rs-probe/Cargo.toml"
+napi_binding="$(
+  find "${results}/napi-rs-probe/target" \
+    -type f \
+    -name 'libgoodbuddy_loongarch_napi_probe.so' \
+    -print \
+    -quit
+)"
+test -n "${napi_binding}"
+assert_loongarch_elf "${napi_binding}"
+
+echo "== Debian package probe =="
+package_root="${results}/deb-root"
+mkdir -p \
+  "${package_root}/DEBIAN" \
+  "${package_root}/usr/lib/goodbuddy-loongarch-probe"
+cp "${results}/hello-c" \
+  "${package_root}/usr/lib/goodbuddy-loongarch-probe/hello"
+cat > "${package_root}/DEBIAN/control" <<'EOF'
+Package: goodbuddy-loongarch-cross-probe
+Version: 1.0.0
+Architecture: loong64
+Maintainer: MesaLogo
+Description: GoodBuddy LoongArch cross-compilation probe
+EOF
+dpkg-deb --build \
+  "${package_root}" \
+  "${results}/goodbuddy-loongarch-cross-probe_1.0.0_loong64.deb"
+test "$(
+  dpkg-deb \
+    --field \
+    "${results}/goodbuddy-loongarch-cross-probe_1.0.0_loong64.deb" \
+    Architecture
+)" = "loong64"
+
+echo "== Koffi prebuilt probe =="
+mkdir "${results}/koffi"
+npm pack \
+  "@koromix/koffi-linux-loong64@3.1.4" \
+  --ignore-scripts \
+  --pack-destination "${results}/koffi"
+koffi_archive="$(
+  find "${results}/koffi" \
+    -maxdepth 1 \
+    -type f \
+    -name '*.tgz' \
+    -print \
+    -quit
+)"
+test -n "${koffi_archive}"
+mkdir "${results}/koffi/package"
+tar \
+  -xzf "${koffi_archive}" \
+  -C "${results}/koffi/package" \
+  --strip-components 1
+koffi_binding="${results}/koffi/package/linux_loong64/koffi.node"
+assert_loongarch_elf "${koffi_binding}"
+if test -e "${results}/koffi/package/musl_loong64/koffi.node"; then
+  echo "Unexpected Koffi musl binding is present"
+  exit 1
+fi
+echo "Koffi loong64 currently provides a glibc binding only"
+
+echo "== Canvas package availability probe =="
+canvas_package_status=unavailable
+if npm view \
+  "@napi-rs/canvas-linux-loong64-gnu" \
+  version \
+  > "${results}/canvas-package-version.txt" \
+  2> "${results}/canvas-package-error.txt"
+then
+  canvas_package_status=available
+fi
+echo "@napi-rs/canvas loong64 package: ${canvas_package_status}"
+
+echo "== node-pty cross-build probe =="
+mkdir "${results}/node-pty"
+npm pack \
+  "node-pty@1.1.0" \
+  --ignore-scripts \
+  --pack-destination "${results}/node-pty"
+node_pty_archive="$(
+  find "${results}/node-pty" \
+    -maxdepth 1 \
+    -type f \
+    -name '*.tgz' \
+    -print \
+    -quit
+)"
+test -n "${node_pty_archive}"
+mkdir "${results}/node-pty/package"
+tar \
+  -xzf "${node_pty_archive}" \
+  -C "${results}/node-pty/package" \
+  --strip-components 1
+(
+  cd "${results}/node-pty/package"
+  npm install --ignore-scripts --omit=dev
+  npm install \
+    --ignore-scripts \
+    --no-save \
+    "node-gyp@11.4.2"
+  CC=loongarch64-linux-gnu-gcc \
+  CXX=loongarch64-linux-gnu-g++ \
+  npm_config_arch=loong64 \
+  npm_config_target_arch=loong64 \
+  npm_config_runtime=electron \
+  npm_config_target=43.2.0 \
+  npm_config_disturl=https://electronjs.org/headers \
+  ./node_modules/.bin/node-gyp rebuild \
+    --arch=loong64
+)
+node_pty_binding="${results}/node-pty/package/build/Release/pty.node"
+assert_loongarch_elf "${node_pty_binding}"
+
+echo "== summary =="
+sha256sum \
+  "${results}/hello-c" \
+  "${results}/hello-cpp" \
+  "${rust_binary}" \
+  "${napi_binding}" \
+  "${results}/goodbuddy-loongarch-cross-probe_1.0.0_loong64.deb" \
+  "${koffi_binding}" \
+  "${node_pty_binding}" \
+  > "${results}/SHA256SUMS"
+
+cat > "${results}/summary.txt" <<EOF
+result=pass
+target=loong64
+c=pass
+cpp=pass
+cmake=pass
+rust=pass
+napi_rs=pass
+qemu=pass
+deb=pass
+koffi=pass
+koffi_musl=unavailable
+canvas_package=${canvas_package_status}
+node_pty=pass
+EOF
+
+cat "${results}/summary.txt"
+echo "results=${results}"

build/loongarch-cross/toolchain.cmake

@@ -0,0 +1,14 @@
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR loongarch64)
+
+set(CMAKE_C_COMPILER loongarch64-linux-gnu-gcc)
+set(CMAKE_CXX_COMPILER loongarch64-linux-gnu-g++)
+set(CMAKE_AR loongarch64-linux-gnu-ar)
+set(CMAKE_RANLIB loongarch64-linux-gnu-ranlib)
+set(CMAKE_STRIP loongarch64-linux-gnu-strip)
+
+set(CMAKE_FIND_ROOT_PATH /usr/loongarch64-linux-gnu)
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

build/npm-invocation.cjs

@@ -0,0 +1,33 @@
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+
+function npmInvocation(projectDir, environment = process.env) {
+  const npmCli = environment.npm_execpath;
+  if (npmCli) {
+    return {
+      command: process.execPath,
+      prefixArgs: [npmCli],
+    };
+  }
+
+  const bundledNpmCli = join(
+    projectDir,
+    "node_modules",
+    "npm",
+    "bin",
+    "npm-cli.js",
+  );
+  if (existsSync(bundledNpmCli)) {
+    return {
+      command: process.execPath,
+      prefixArgs: [bundledNpmCli],
+    };
+  }
+
+  return {
+    command: process.platform === "win32" ? "npm.cmd" : "npm",
+    prefixArgs: [],
+  };
+}
+
+module.exports = { npmInvocation };

build/opencode-config.cjs

@@ -0,0 +1,110 @@
+const { existsSync } = require("node:fs");
+const {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} = require("node:fs");
+const { join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { npmInvocation } = require("./npm-invocation.cjs");
+
+const opencodeVersion = "1.18.29";
+const opencodePluginPackage = "@opencode-ai/plugin";
+
+function prepareBundledOpenCodeConfig(projectDir) {
+  const targetDirectory = join(
+    projectDir,
+    ".runtime-resources",
+    "opencode-config",
+  );
+  try {
+    const installed = JSON.parse(
+      readFileSync(
+        join(
+          targetDirectory,
+          "node_modules",
+          "@opencode-ai",
+          "plugin",
+          "package.json",
+        ),
+        "utf8",
+      ),
+    );
+    if (installed.version === opencodeVersion) {
+      return targetDirectory;
+    }
+  } catch {
+    // Rebuild an incomplete or stale offline config template.
+  }
+
+  const stagingDirectory = `${targetDirectory}.staging-${process.pid}`;
+  rmSync(stagingDirectory, { recursive: true, force: true });
+  mkdirSync(stagingDirectory, { recursive: true });
+  try {
+    writeFileSync(
+      join(stagingDirectory, "package.json"),
+      `${JSON.stringify(
+        {
+          private: true,
+          dependencies: {
+            [opencodePluginPackage]: opencodeVersion,
+          },
+        },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+    writeFileSync(join(stagingDirectory, ".gitignore"), "node_modules\n");
+    const npm = npmInvocation(projectDir);
+    const environment = { ...process.env };
+    delete environment.NODE_TLS_REJECT_UNAUTHORIZED;
+    const result = spawnSync(
+      npm.command,
+      [
+        ...npm.prefixArgs,
+        "install",
+        "--ignore-scripts",
+        "--bin-links=false",
+        "--omit=dev",
+        "--omit=optional",
+        "--no-audit",
+        "--no-fund",
+        "--save-exact",
+      ],
+      {
+        cwd: stagingDirectory,
+        encoding: "utf8",
+        env: environment,
+        maxBuffer: 16 * 1024 * 1024,
+        shell: false,
+        windowsHide: true,
+      },
+    );
+    if (result.status !== 0) {
+      throw new Error(
+        `Unable to prepare bundled OpenCode config: ${
+          result.error?.message ||
+          result.stderr ||
+          result.stdout ||
+          `npm exited with ${result.status}`
+        }`,
+      );
+    }
+    rmSync(targetDirectory, { recursive: true, force: true });
+    mkdirSync(join(targetDirectory, ".."), { recursive: true });
+    renameSync(stagingDirectory, targetDirectory);
+    return targetDirectory;
+  } finally {
+    if (existsSync(stagingDirectory)) {
+      rmSync(stagingDirectory, { recursive: true, force: true });
+    }
+  }
+}
+
+module.exports = {
+  opencodeVersion,
+  prepareBundledOpenCodeConfig,
+};

build/release-notes.cjs

@@ -0,0 +1,212 @@
+const { readFileSync, writeFileSync } = require('node:fs')
+const { join, resolve } = require('node:path')
+
+const root = resolve(__dirname, '..')
+const packageJson = JSON.parse(
+  readFileSync(join(root, 'package.json'), 'utf8')
+)
+const releaseNotesFile = JSON.parse(
+  readFileSync(join(root, 'resources', 'release-notes.json'), 'utf8')
+)
+
+function fail(message) {
+  throw new Error(`Release notes validation failed: ${message}`)
+}
+
+function hasExactKeys(value, keys) {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === keys.length &&
+    keys.every((key) => Object.hasOwn(value, key))
+  )
+}
+
+function validateItems(value, label) {
+  if (!Array.isArray(value) || value.length > 20) {
+    fail(`${label} must contain no more than 20 items`)
+  }
+  return value.map((item) => {
+    if (typeof item !== 'string') {
+      fail(`${label} contains a non-string item`)
+    }
+    const normalized = item.trim()
+    if (!normalized) {
+      fail(`${label} contains an empty item`)
+    }
+    return normalized
+  })
+}
+
+const releaseNoteSections = [
+  'highlights',
+  'features',
+  'fixes',
+  'notices'
+]
+const legacyReleaseNoteSections = ['features', 'fixes']
+
+function validateRelease(value, index) {
+  const label = `releases[${index}]`
+  if (!hasExactKeys(value, ['version', 'releasedAt', 'notes'])) {
+    fail(`${label} has invalid fields`)
+  }
+  if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u.test(
+    value.version
+  )) {
+    fail(`${label}.version must be a stable semantic version`)
+  }
+  const date = new Date(`${value.releasedAt}T00:00:00.000Z`)
+  if (
+    !/^\d{4}-\d{2}-\d{2}$/u.test(value.releasedAt) ||
+    Number.isNaN(date.getTime()) ||
+    date.toISOString().slice(0, 10) !== value.releasedAt
+  ) {
+    fail(`${label}.releasedAt must be a real YYYY-MM-DD date`)
+  }
+  if (!hasExactKeys(value.notes, ['zh-CN', 'en-US'])) {
+    fail(`${label}.notes must contain zh-CN and en-US`)
+  }
+  const notes = Object.fromEntries(
+    ['zh-CN', 'en-US'].map((locale) => {
+      const localized = value.notes[locale]
+      const isCurrentFormat = hasExactKeys(
+        localized,
+        releaseNoteSections
+      )
+      const isLegacyFormat = hasExactKeys(
+        localized,
+        legacyReleaseNoteSections
+      )
+      if (!isCurrentFormat && !isLegacyFormat) {
+        fail(`${label}.notes.${locale} has invalid fields`)
+      }
+      const normalized = Object.fromEntries(
+        releaseNoteSections.map((section) => [
+          section,
+          section in localized
+            ? validateItems(
+                localized[section],
+                `${label}.notes.${locale}.${section}`
+              )
+            : []
+        ])
+      )
+      if (normalized.highlights.length > 3) {
+        fail(
+          `${label}.notes.${locale}.highlights must contain no more than 3 items`
+        )
+      }
+      if (
+        releaseNoteSections.every(
+          (section) => normalized[section].length === 0
+        )
+      ) {
+        fail(`${label}.notes.${locale} must not be empty`)
+      }
+      return [locale, normalized]
+    })
+  )
+  for (const section of releaseNoteSections) {
+    if (
+      notes['zh-CN'][section].length !==
+      notes['en-US'][section].length
+    ) {
+      fail(`${label} localized ${section} counts do not match`)
+    }
+  }
+  return {
+    version: value.version,
+    releasedAt: value.releasedAt,
+    notes
+  }
+}
+
+if (
+  !hasExactKeys(releaseNotesFile, ['formatVersion', 'releases']) ||
+  releaseNotesFile.formatVersion !== 1 ||
+  !Array.isArray(releaseNotesFile.releases) ||
+  releaseNotesFile.releases.length < 1 ||
+  releaseNotesFile.releases.length > 100
+) {
+  fail('unsupported file format')
+}
+
+const allReleases = releaseNotesFile.releases.map(validateRelease)
+const uniqueVersionCount = new Set(
+  allReleases.map((release) => release.version)
+).size
+if (uniqueVersionCount !== allReleases.length) {
+  fail('release versions must be unique')
+}
+
+const releases = allReleases.filter(
+  (release) => release?.version === packageJson.version
+)
+if (releases.length !== 1) {
+  fail(
+    `expected exactly one entry for package version ${packageJson.version}`
+  )
+}
+
+const release = releases[0]
+
+const localizedDefinitions = [
+  {
+    locale: 'zh-CN',
+    title: `GoodBuddy ${release.version} 更新内容`,
+    highlights: '本次亮点',
+    features: '功能更新',
+    fixes: '问题修复',
+    notices: '使用前请留意'
+  },
+  {
+    locale: 'en-US',
+    title: `What's New in GoodBuddy ${release.version}`,
+    highlights: 'Highlights',
+    features: 'Features',
+    fixes: 'Bug Fixes',
+    notices: 'Before You Start'
+  }
+]
+
+function markdownSection(title, items) {
+  if (items.length === 0) {
+    return []
+  }
+  return [`## ${title}`, '', ...items.map((item) => `- ${item}`), '']
+}
+
+const markdown = localizedDefinitions
+  .flatMap((definition, index) => {
+    const notes = release.notes[definition.locale]
+    return [
+      ...(index === 0 ? [] : ['---', '']),
+      `# ${definition.title}`,
+      '',
+      ...markdownSection(
+        definition.highlights,
+        notes.highlights
+      ),
+      ...markdownSection(definition.features, notes.features),
+      ...markdownSection(definition.fixes, notes.fixes),
+      ...markdownSection(definition.notices, notes.notices)
+    ]
+  })
+  .join('\n')
+  .trimEnd()
+  .concat('\n')
+
+const outputIndex = process.argv.indexOf('--output')
+if (outputIndex >= 0) {
+  const outputPath = process.argv[outputIndex + 1]
+  if (!outputPath) {
+    fail('--output requires a path')
+  }
+  writeFileSync(resolve(root, outputPath), markdown, 'utf8')
+} else {
+  process.stdout.write(
+    `Validated bilingual release notes for ${packageJson.version}\n`
+  )
+}

build/run-browser-tabs-electron-e2e.cjs

@@ -0,0 +1,31 @@
+const { spawnSync } = require('node:child_process')
+const { rmSync } = require('node:fs')
+const { tmpdir } = require('node:os')
+const { join } = require('node:path')
+const { buildSync } = require('esbuild')
+
+const output = join(tmpdir(), `goodbuddy-browser-tabs-e2e-${process.pid}.cjs`)
+
+try {
+  buildSync({
+    entryPoints: [join(process.cwd(), 'tests', 'browser-tabs-electron-e2e.ts')],
+    outfile: output,
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    target: 'node22',
+    external: ['electron']
+  })
+  const environment = { ...process.env }
+  delete environment.ELECTRON_RUN_AS_NODE
+  const result = spawnSync(require('electron'), [output], {
+    cwd: process.cwd(),
+    env: environment,
+    stdio: 'inherit',
+    timeout: 120_000
+  })
+  if (result.error) throw result.error
+  process.exitCode = result.status ?? 1
+} finally {
+  rmSync(output, { force: true })
+}

build/run-deepseek-harness-utility-smoke.cjs

@@ -0,0 +1,149 @@
+'use strict'
+
+const { spawn } = require('node:child_process')
+const {
+  readFile,
+  rm,
+  writeFile
+} = require('node:fs/promises')
+const { tmpdir } = require('node:os')
+const { join, resolve } = require('node:path')
+
+const electronPath = process.env.GOODBUDDY_HARNESS_SMOKE_ELECTRON
+  ? resolve(process.env.GOODBUDDY_HARNESS_SMOKE_ELECTRON)
+  : require('electron')
+const configuredAppPath =
+  process.env.GOODBUDDY_HARNESS_SMOKE_APP
+const appPath = configuredAppPath
+  ? resolve(configuredAppPath)
+  : resolve('build/smoke-app')
+const temporaryAppPath =
+  configuredAppPath ||
+  process.env.GOODBUDDY_HARNESS_SMOKE_ELECTRON
+    ? undefined
+    : join(
+        tmpdir(),
+        `goodbuddy-harness-smoke-app-${process.pid}`
+      )
+const resultPath = join(
+  tmpdir(),
+  `goodbuddy-harness-utility-smoke-result-${process.pid}.json`
+)
+const profilePath = join(
+  tmpdir(),
+  `goodbuddy-harness-utility-smoke-profile-${process.pid}`
+)
+const environment = {
+  ...process.env,
+  GOODBUDDY_HARNESS_SMOKE_RESULT: resultPath
+}
+delete environment.ELECTRON_RUN_AS_NODE
+
+function runElectron(applicationPath) {
+  return new Promise((resolveRun, rejectRun) => {
+    const child = spawn(
+      electronPath,
+      [
+        applicationPath,
+        '--no-sandbox',
+        `--user-data-dir=${profilePath}`,
+        '--no-first-run'
+      ],
+      {
+        cwd: resolve('.'),
+        env: environment,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true
+      }
+    )
+    let output = ''
+    const capture = (chunk) => {
+      output = (output + String(chunk)).slice(-8_192)
+    }
+    child.stdout.on('data', capture)
+    child.stderr.on('data', capture)
+    const timeout = setTimeout(() => {
+      child.kill()
+      rejectRun(
+        new Error(
+          `DeepSeek Harness Electron smoke timed out: ${output.trim()}`
+        )
+      )
+    }, 30_000)
+    child.once('error', (error) => {
+      clearTimeout(timeout)
+      rejectRun(error)
+    })
+    child.once('exit', (code, signal) => {
+      clearTimeout(timeout)
+      resolveRun({ code, signal, output })
+    })
+  })
+}
+
+async function main() {
+  await rm(resultPath, { force: true })
+  await writeFile(
+    resolve('out/main/package.json'),
+    `${JSON.stringify(
+      {
+        name: '@deepseek-ai/dsh-llm',
+        version: '0.1.2-rc.1',
+        private: true,
+        type: 'module'
+      },
+      null,
+      2
+    )}\n`,
+    'utf8'
+  )
+  if (temporaryAppPath) {
+    await rm(temporaryAppPath, {
+      recursive: true,
+      force: true
+    })
+    const { cp, copyFile, mkdir } = require('node:fs/promises')
+    await mkdir(temporaryAppPath, { recursive: true })
+    await cp(resolve('build/smoke-app'), temporaryAppPath, {
+      recursive: true
+    })
+    await copyFile(
+      resolve('build/deepseek-harness-utility-smoke.cjs'),
+      join(temporaryAppPath, 'deepseek-harness-utility-smoke.cjs')
+    )
+  }
+  const execution = await runElectron(
+    temporaryAppPath ?? appPath
+  )
+  let result
+  try {
+    result = JSON.parse(await readFile(resultPath, 'utf8'))
+  } catch (error) {
+    throw new Error(
+      `DeepSeek Harness Electron smoke produced no valid result (code ${execution.code}, signal ${execution.signal ?? 'none'}): ${execution.output.trim()}`,
+      { cause: error }
+    )
+  } finally {
+    await Promise.all([
+      rm(resultPath, { force: true }),
+      rm(profilePath, { recursive: true, force: true }),
+      temporaryAppPath
+        ? rm(temporaryAppPath, {
+            recursive: true,
+            force: true
+          })
+        : Promise.resolve()
+    ])
+  }
+  if (execution.code !== 0 || result.status !== 'ready') {
+    throw new Error(
+      `DeepSeek Harness Electron smoke failed (code ${execution.code}, status ${String(result.status)}): ${String(result.detail ?? execution.output).trim()}`
+    )
+  }
+  console.log('DeepSeek Harness Electron utility smoke: ready')
+}
+
+void main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

build/run-electron-builder.cjs

@@ -0,0 +1,32 @@
+'use strict'
+
+function configureElectronBuilderLogLevels(
+  moduleManager = require(
+    'app-builder-lib/out/node-module-collector/moduleManager'
+  )
+) {
+  const duplicateReferenceMessage =
+    moduleManager.LogMessageByKey.PKG_DUPLICATE_REF
+  if (
+    !duplicateReferenceMessage ||
+    !moduleManager.logMessageLevelByKey[
+      duplicateReferenceMessage
+    ]
+  ) {
+    throw new Error(
+      '当前 electron-builder 不支持依赖引用日志级别配置'
+    )
+  }
+  moduleManager.logMessageLevelByKey[
+    duplicateReferenceMessage
+  ] = 'debug'
+}
+
+if (require.main === module) {
+  configureElectronBuilderLogLevels()
+  require('electron-builder/cli')
+}
+
+module.exports = {
+  configureElectronBuilderLogLevels
+}

build/run-packaged-deepseek-harness-smoke.cjs

@@ -0,0 +1,323 @@
+'use strict'
+
+const { spawn } = require('node:child_process')
+const {
+  chmod,
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  writeFile
+} = require('node:fs/promises')
+const { statSync } = require('node:fs')
+const { tmpdir } = require('node:os')
+const { delimiter, join, resolve } = require('node:path')
+const { pathToFileURL } = require('node:url')
+
+const unpackedPath = process.argv[2]
+  ? resolve(process.argv[2])
+  : resolve('dist/harness-package-probe/win-unpacked')
+const executable = join(
+  unpackedPath,
+  process.platform === 'win32' ? 'GoodBuddy.exe' : 'goodbuddy'
+)
+const host = join(
+  unpackedPath,
+  'resources',
+  'app.asar.unpacked',
+  'out',
+  'main',
+  'deepseek-harness-host-bootstrap.js'
+)
+const npmRoot = join(unpackedPath, 'resources', 'runtimes', 'npm')
+const npmCli = join(npmRoot, 'bin', 'npm-cli.js')
+const npmManifestPath = join(npmRoot, 'package.json')
+
+for (const [path, description] of [
+  [executable, 'packaged Electron executable'],
+  [host, 'packaged DeepSeek Harness host'],
+  [npmCli, 'packaged npm CLI'],
+  [npmManifestPath, 'packaged npm manifest']
+]) {
+  if (!statSync(path, { throwIfNoEntry: false })?.isFile()) {
+    throw new Error(`${description} is missing: ${path}`)
+  }
+}
+
+function quotePosixShell(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`
+}
+
+async function prepareNodeCommand(directory) {
+  await mkdir(directory, { recursive: true })
+  if (process.platform === 'win32') {
+    await writeFile(
+      join(directory, 'node.cmd'),
+      [
+        '@echo off',
+        'set "ELECTRON_RUN_AS_NODE=1"',
+        `"${executable.replaceAll('%', '%%')}" %*`,
+        ''
+      ].join('\r\n'),
+      'utf8'
+    )
+    return
+  }
+  const commandPath = join(directory, 'node')
+  await writeFile(
+    commandPath,
+    [
+      '#!/bin/sh',
+      `ELECTRON_RUN_AS_NODE=1 exec ${quotePosixShell(executable)} "$@"`,
+      ''
+    ].join('\n'),
+    'utf8'
+  )
+  await chmod(commandPath, 0o700)
+}
+
+function run(command, args, env, cwd = resolve('.')) {
+  return new Promise((resolveExit, rejectExit) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true
+    })
+    let output = ''
+    const capture = (chunk) => {
+      output = (output + String(chunk)).slice(-8_192)
+    }
+    child.stdout.on('data', capture)
+    child.stderr.on('data', capture)
+    child.once('error', rejectExit)
+    child.once('exit', (exitCode, signal) => {
+      resolveExit({ exitCode, signal, output })
+    })
+  })
+}
+
+async function main() {
+  const root = await mkdtemp(
+    join(tmpdir(), 'goodbuddy-packaged-harness-smoke-')
+  )
+  try {
+    const project = join(root, 'app')
+    const profile = join(root, 'profile')
+    const resultPath = join(root, 'result.json')
+    const packageManagerBin = join(root, 'package-manager-bin')
+    const npmProject = join(root, 'npm-project')
+    const npmFixture = join(root, 'npm-fixture')
+    await mkdir(project, { recursive: true })
+    const pluginUrl = pathToFileURL(join(
+      unpackedPath, 'resources', 'runtimes', 'opencode-config',
+      'node_modules', '@opencode-ai', 'plugin', 'dist', 'index.js'
+    )).href
+    const importedPlugin = await run(
+      executable,
+      ['--input-type=module', '--eval', `await import(${JSON.stringify(pluginUrl)})`],
+      { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+      root
+    )
+    if (importedPlugin.exitCode !== 0 || importedPlugin.signal) {
+      throw new Error(`Packaged OpenCode plugin import failed: ${importedPlugin.output.trim()}`)
+    }
+    console.log('Packaged OpenCode offline plugin import: ready')
+
+    await copyFile(
+      resolve('build/deepseek-harness-utility-smoke.cjs'),
+      join(project, 'deepseek-harness-utility-smoke.cjs')
+    )
+    await writeFile(
+      join(project, 'package.json'),
+      `${JSON.stringify(
+        {
+          name: 'goodbuddy-packaged-harness-smoke',
+          version: '1.0.0',
+          private: true,
+          main: 'deepseek-harness-utility-smoke.cjs'
+        },
+        null,
+        2
+      )}\n`,
+      'utf8'
+    )
+    await writeFile(
+      join(project, 'electron-builder.yml'),
+      [
+        'appId: live.digiman.goodbuddy.harness-smoke',
+        'productName: GoodBuddyHarnessSmoke',
+        'electronVersion: "43.2.0"',
+        'asar: true',
+        'npmRebuild: false',
+        'files:',
+        '  - package.json',
+        '  - deepseek-harness-utility-smoke.cjs',
+        'win:',
+        '  target:',
+        '    - dir'
+      ].join('\n'),
+      'utf8'
+    )
+
+    const packageArguments = [
+      resolve('build/run-electron-builder.cjs'),
+      '--projectDir',
+      project,
+      '--win',
+      'dir',
+      '--x64',
+      '--publish',
+      'never',
+      `--config.directories.output=${join(root, 'dist')}`
+    ]
+    const electronDist = process.env.GOODBUDDY_ELECTRON_DIST
+      ? resolve(process.env.GOODBUDDY_ELECTRON_DIST)
+      : resolve('node_modules/electron/dist')
+    if (
+      statSync(electronDist, {
+        throwIfNoEntry: false
+      })?.isDirectory()
+    ) {
+      packageArguments.push(
+        `--config.electronDist=${electronDist}`
+      )
+    }
+    const packaged = await run(
+      process.execPath,
+      packageArguments,
+      process.env
+    )
+    if (packaged.exitCode !== 0 || packaged.signal) {
+      throw new Error(
+        `Unable to package Harness smoke app: ${packaged.output.trim()}`
+      )
+    }
+
+    const smokeEnvironment = {
+      ...process.env,
+      GOODBUDDY_HARNESS_SMOKE_HOST: host,
+      GOODBUDDY_HARNESS_SMOKE_RESULT: resultPath
+    }
+    delete smokeEnvironment.ELECTRON_RUN_AS_NODE
+    const executed = await run(
+      join(root, 'dist', 'win-unpacked', 'GoodBuddyHarnessSmoke.exe'),
+      [`--user-data-dir=${profile}`, '--no-first-run'],
+      smokeEnvironment
+    )
+    const result = JSON.parse(await readFile(resultPath, 'utf8'))
+    if (
+      executed.exitCode !== 0 ||
+      executed.signal ||
+      result.status !== 'ready'
+    ) {
+      throw new Error(
+        `Packaged DeepSeek Harness smoke failed (${executed.exitCode}, ${executed.signal ?? 'no signal'}): ${JSON.stringify(result)} ${executed.output.trim()}`
+      )
+    }
+
+    const npmManifest = JSON.parse(
+      await readFile(npmManifestPath, 'utf8')
+    )
+    await prepareNodeCommand(packageManagerBin)
+    await mkdir(npmProject, { recursive: true })
+    await mkdir(npmFixture, { recursive: true })
+    await writeFile(
+      join(npmProject, 'package.json'),
+      '{"name":"goodbuddy-packaged-npm-project","version":"1.0.0","private":true}\n',
+      'utf8'
+    )
+    await writeFile(
+      join(npmFixture, 'package.json'),
+      `${JSON.stringify({
+        name: 'goodbuddy-packaged-npm-smoke',
+        version: '1.0.0',
+        scripts: {
+          install: 'node install.cjs'
+        }
+      })}\n`,
+      'utf8'
+    )
+    await writeFile(
+      join(npmFixture, 'install.cjs'),
+      "require('node:fs').writeFileSync(require('node:path').join(__dirname, 'lifecycle-ran.txt'), 'ready\\n')\n",
+      'utf8'
+    )
+    const inheritedPath =
+      process.env.PATH ?? process.env.Path ?? ''
+    const npmEnvironment = {
+      ...process.env,
+      PATH: inheritedPath
+        ? `${packageManagerBin}${delimiter}${inheritedPath}`
+        : packageManagerBin,
+      Path: inheritedPath
+        ? `${packageManagerBin}${delimiter}${inheritedPath}`
+        : packageManagerBin,
+      ELECTRON_RUN_AS_NODE: '1',
+      npm_execpath: npmCli,
+      npm_node_execpath: executable,
+      npm_config_audit: 'false',
+      npm_config_fund: 'false',
+      npm_config_update_notifier: 'false'
+    }
+    const npmVersion = await run(
+      executable,
+      [npmCli, '--version'],
+      npmEnvironment,
+      npmProject
+    )
+    if (
+      npmVersion.exitCode !== 0 ||
+      npmVersion.signal ||
+      npmVersion.output.trim() !== npmManifest.version
+    ) {
+      throw new Error(
+        `Packaged npm version smoke failed: ${npmVersion.output.trim()}`
+      )
+    }
+    const installed = await run(
+      executable,
+      [
+        npmCli,
+        'install',
+        '--save-exact',
+        '--no-audit',
+        '--no-fund',
+        '--dangerously-allow-all-scripts',
+        '--loglevel=error',
+        npmFixture
+      ],
+      npmEnvironment,
+      npmProject
+    )
+    if (installed.exitCode !== 0 || installed.signal) {
+      throw new Error(
+        `Packaged npm install smoke failed: ${installed.output.trim()}`
+      )
+    }
+    const lifecycleMarker = await readFile(
+      join(
+        npmProject,
+        'node_modules',
+        'goodbuddy-packaged-npm-smoke',
+        'lifecycle-ran.txt'
+      ),
+      'utf8'
+    )
+    if (lifecycleMarker !== 'ready\n') {
+      throw new Error('Packaged npm lifecycle smoke failed')
+    }
+    console.log('Packaged DeepSeek Harness utility smoke: ready')
+    console.log(
+      `Packaged npm install smoke: ready (${npmManifest.version})`
+    )
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+}
+
+void main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

build/runtime-hooks.cjs

@@ -1,4 +1,4 @@
-const { createHash } = require('node:crypto')
+const { createHash } = require("node:crypto");
 const {
   chmod,
   mkdir,
@@ -6,101 +6,84 @@ const {
   rename,
   rm,
   stat,
-  writeFile
-} = require('node:fs/promises')
-const { existsSync } = require('node:fs')
-const { join } = require('node:path')
-const { spawnSync } = require('node:child_process')
-const tar = require('tar')
-const { sha256File } = require('./file-hash.cjs')
+  writeFile,
+} = require("node:fs/promises");
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+const tar = require("tar");
+const { sha256File } = require("./file-hash.cjs");
+const {
+  opencodeVersion,
+  prepareBundledOpenCodeConfig,
+} = require("./opencode-config.cjs");
+const { npmInvocation } = require("./npm-invocation.cjs");
 
-const opencodeVersion = '1.18.9'
 const architectureNames = {
-  1: 'x64',
-  3: 'arm64'
-}
+  1: "x64",
+  3: "arm64",
+};
 const platformNames = {
-  darwin: 'darwin',
-  linux: 'linux',
-  win32: 'windows'
-}
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};
 
 function sha512Integrity(contents) {
-  return `sha512-${createHash('sha512').update(contents).digest('base64')}`
+  return `sha512-${createHash("sha512").update(contents).digest("base64")}`;
 }
 
-async function lockedIntegrity(projectDir, packageName) {
+async function lockedIntegrity(projectDir, packageName, version) {
   const lock = JSON.parse(
-    await readFile(join(projectDir, 'package-lock.json'), 'utf8')
-  )
-  const entry = lock.packages?.[`node_modules/${packageName}`]
+    await readFile(join(projectDir, "package-lock.json"), "utf8"),
+  );
+  const entry = lock.packages?.[`node_modules/${packageName}`];
   if (
-    entry?.version !== opencodeVersion ||
-    typeof entry.integrity !== 'string'
+    entry?.version !== version ||
+    typeof entry.integrity !== "string"
   ) {
     throw new Error(
-      `Missing locked ${packageName}@${opencodeVersion} integrity`
-    )
+      `Missing locked ${packageName}@${version} integrity`,
+    );
   }
-  return entry.integrity
+  return entry.integrity;
 }
 
-function npmInvocation() {
-  const npmCli = process.env.npm_execpath
-  if (npmCli) {
-    return {
-      command: process.execPath,
-      prefixArgs: [npmCli]
-    }
-  }
-  if (process.platform === 'win32') {
-    throw new Error('npm_execpath is required to prepare bundled runtimes')
-  }
-  return {
-    command: 'npm',
-    prefixArgs: []
-  }
-}
-
-async function downloadPackage(projectDir, packageName, integrity) {
-  const cacheDirectory = join(
-    projectDir,
-    '.runtime-resources',
-    'cache'
-  )
-  await mkdir(cacheDirectory, { recursive: true })
+async function downloadPackage(projectDir, packageName, version, integrity) {
+  const cacheDirectory = join(projectDir, ".runtime-resources", "cache");
+  await mkdir(cacheDirectory, { recursive: true });
   const archivePath = join(
     cacheDirectory,
-    `${packageName}-${opencodeVersion}.tgz`
-  )
+    `${packageName.replaceAll("/", "-").replaceAll("@", "")}-${version}.tgz`,
+  );
   if (existsSync(archivePath)) {
-    const cached = await readFile(archivePath)
+    const cached = await readFile(archivePath);
     if (sha512Integrity(cached) === integrity) {
-      return archivePath
+      return archivePath;
     }
-    await rm(archivePath, { force: true })
+    await rm(archivePath, { force: true });
   }
 
-  const npm = npmInvocation()
+  const npm = npmInvocation(projectDir);
   const result = spawnSync(
     npm.command,
     [
       ...npm.prefixArgs,
-      'pack',
-      `${packageName}@${opencodeVersion}`,
-      '--ignore-scripts',
-      '--json',
-      '--pack-destination',
-      cacheDirectory
+      "pack",
+      `${packageName}@${version}`,
+      "--ignore-scripts",
+      "--json",
+      "--pack-destination",
+      cacheDirectory,
     ],
     {
       cwd: projectDir,
-      encoding: 'utf8',
+      encoding: "utf8",
       maxBuffer: 16 * 1024 * 1024,
       shell: false,
-      windowsHide: true
-    }
-  )
+      windowsHide: true,
+    },
+  );
   if (result.status !== 0) {
     throw new Error(
       `Unable to fetch ${packageName}: ${
@@ -108,63 +91,150 @@ async function downloadPackage(projectDir, packageName, integrity) {
         result.stderr ||
         result.stdout ||
         `npm exited with ${result.status}`
-      }`
-    )
+      }`,
+    );
   }
-  const output = JSON.parse(result.stdout)
-  const downloadedPath = join(cacheDirectory, output[0].filename)
-  const contents = await readFile(downloadedPath)
+  const output = JSON.parse(result.stdout);
+  const downloadedPath = join(cacheDirectory, output[0].filename);
+  const contents = await readFile(downloadedPath);
   if (sha512Integrity(contents) !== integrity) {
-    await rm(downloadedPath, { force: true })
-    throw new Error(`Integrity verification failed for ${packageName}`)
+    await rm(downloadedPath, { force: true });
+    throw new Error(`Integrity verification failed for ${packageName}`);
   }
   if (downloadedPath !== archivePath) {
-    await rm(archivePath, { force: true })
-    await rename(downloadedPath, archivePath)
+    await rm(archivePath, { force: true });
+    await rename(downloadedPath, archivePath);
   }
-  return archivePath
+  return archivePath;
 }
 
-module.exports = async function prepareBundledRuntimes(context) {
-  const platform = context.electronPlatformName
-  const architecture = architectureNames[context.arch]
-  const packagePlatform = platformNames[platform]
-  if (!architecture || !packagePlatform) {
-    throw new Error(
-      `Bundled OpenCode does not support ${platform}/${context.arch}`
-    )
-  }
-
-  const suffix =
-    architecture === 'x64' ? `${architecture}-baseline` : architecture
-  const packageName = `opencode-${packagePlatform}-${suffix}`
-  const projectDir = context.packager.projectDir
-  const integrity = await lockedIntegrity(projectDir, packageName)
-  const targetDirectory = join(
-    projectDir,
-    '.runtime-resources',
-    architecture
-  )
-  const readyPath = join(targetDirectory, '.ready.json')
-  const executable = platform === 'win32' ? 'opencode.exe' : 'opencode'
-  const preparedPath = join(targetDirectory, executable)
-  const identity = {
-    packageName,
-    version: opencodeVersion,
-    integrity
-  }
+async function prepareRipgrep(
+  projectDir,
+  targetDirectory,
+  platform,
+  architecture,
+  version,
+) {
+  const packageName = `@vscode/ripgrep-${platform}-${architecture}`;
+  const integrity = await lockedIntegrity(projectDir, packageName, version);
+  const executable = platform === "win32" ? "rg.exe" : "rg";
+  const preparedPath = join(targetDirectory, executable);
+  const readyPath = join(targetDirectory, ".ripgrep-ready.json");
+  const identity = { packageName, version, integrity };
   try {
-    const ready = JSON.parse(await readFile(readyPath, 'utf8'))
+    const ready = JSON.parse(await readFile(readyPath, "utf8"));
     if (
       ready.packageName === identity.packageName &&
       ready.version === identity.version &&
       ready.integrity === identity.integrity &&
-      typeof ready.executableSha256 === 'string' &&
-      (platform === 'win32' ||
+      typeof ready.executableSha256 === "string" &&
+      (platform === "win32" || ((await stat(preparedPath)).mode & 0o111) !== 0) &&
+      (await sha256File(preparedPath)) === ready.executableSha256
+    ) {
+      return;
+    }
+  } catch {
+    // Rebuild an incomplete or stale ripgrep cache.
+  }
+
+  const archivePath = await downloadPackage(
+    projectDir,
+    packageName,
+    version,
+    integrity,
+  );
+  const stagingDirectory = `${targetDirectory}.ripgrep-staging-${process.pid}`;
+  await rm(stagingDirectory, { recursive: true, force: true });
+  await mkdir(stagingDirectory, { recursive: true });
+  try {
+    await tar.x({
+      file: archivePath,
+      cwd: stagingDirectory,
+      strip: 1,
+    });
+    const sourcePath = join(stagingDirectory, "bin", executable);
+    const executableSha256 = await sha256File(sourcePath);
+    if (platform !== "win32") {
+      await chmod(sourcePath, 0o755);
+    }
+    await mkdir(targetDirectory, { recursive: true });
+    await rm(preparedPath, { force: true });
+    await rename(sourcePath, preparedPath);
+    await writeFile(
+      readyPath,
+      JSON.stringify({ ...identity, executableSha256 }),
+      "utf8",
+    );
+  } finally {
+    await rm(stagingDirectory, { recursive: true, force: true });
+  }
+}
+
+module.exports = async function prepareBundledRuntimes(context) {
+  const platform = context.electronPlatformName;
+  const architecture = architectureNames[context.arch];
+  const packagePlatform = platformNames[platform];
+  if (!architecture || !packagePlatform) {
+    throw new Error(
+      `Bundled OpenCode does not support ${platform}/${context.arch}`,
+    );
+  }
+
+  const suffix =
+    architecture === "x64" ? `${architecture}-baseline` : architecture;
+  const packageName = `opencode-${packagePlatform}-${suffix}`;
+  const projectDir = context.packager.projectDir;
+  await prepareBundledOpenCodeConfig(projectDir);
+  const projectPackage = JSON.parse(
+    await readFile(join(projectDir, "package.json"), "utf8"),
+  );
+  const ripgrepVersion = projectPackage.dependencies["@vscode/ripgrep"];
+  if (typeof ripgrepVersion !== "string" || !/^\d+\.\d+\.\d+$/u.test(ripgrepVersion)) {
+    throw new Error("Missing exact @vscode/ripgrep dependency version");
+  }
+  await writeFile(
+    join(projectDir, "out", "main", "package.json"),
+    `${JSON.stringify(
+      {
+        name: "@deepseek-ai/dsh-llm",
+        version: projectPackage.dependencies["@deepseek-ai/dsh-llm"],
+        private: true,
+        type: "module",
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  const integrity = await lockedIntegrity(projectDir, packageName, opencodeVersion);
+  const targetDirectory = join(projectDir, ".runtime-resources", architecture);
+  const readyPath = join(targetDirectory, ".ready.json");
+  const executable = platform === "win32" ? "opencode.exe" : "opencode";
+  const preparedPath = join(targetDirectory, executable);
+  const identity = {
+    packageName,
+    version: opencodeVersion,
+    integrity,
+  };
+  try {
+    const ready = JSON.parse(await readFile(readyPath, "utf8"));
+    if (
+      ready.packageName === identity.packageName &&
+      ready.version === identity.version &&
+      ready.integrity === identity.integrity &&
+      typeof ready.executableSha256 === "string" &&
+      (platform === "win32" ||
         ((await stat(preparedPath)).mode & 0o111) !== 0) &&
       (await sha256File(preparedPath)) === ready.executableSha256
     ) {
-      return
+      await prepareRipgrep(
+        projectDir,
+        targetDirectory,
+        platform,
+        architecture,
+        ripgrepVersion,
+      );
+      return;
     }
   } catch {
     // Rebuild an incomplete or stale runtime cache.
@@ -173,32 +243,40 @@ module.exports = async function prepareBundledRuntimes(context) {
   const archivePath = await downloadPackage(
     projectDir,
     packageName,
-    integrity
-  )
-  const stagingDirectory = `${targetDirectory}.staging-${process.pid}`
-  await rm(stagingDirectory, { recursive: true, force: true })
-  await mkdir(stagingDirectory, { recursive: true })
+    opencodeVersion,
+    integrity,
+  );
+  const stagingDirectory = `${targetDirectory}.staging-${process.pid}`;
+  await rm(stagingDirectory, { recursive: true, force: true });
+  await mkdir(stagingDirectory, { recursive: true });
   try {
     await tar.x({
       file: archivePath,
       cwd: stagingDirectory,
-      strip: 1
-    })
-    const sourcePath = join(stagingDirectory, 'bin', executable)
-    const stagingExecutable = join(stagingDirectory, executable)
-    await rename(sourcePath, stagingExecutable)
-    if (platform !== 'win32') {
-      await chmod(stagingExecutable, 0o755)
+      strip: 1,
+    });
+    const sourcePath = join(stagingDirectory, "bin", executable);
+    const stagingExecutable = join(stagingDirectory, executable);
+    await rename(sourcePath, stagingExecutable);
+    if (platform !== "win32") {
+      await chmod(stagingExecutable, 0o755);
     }
-    const executableSha256 = await sha256File(stagingExecutable)
+    const executableSha256 = await sha256File(stagingExecutable);
     await writeFile(
-      join(stagingDirectory, '.ready.json'),
+      join(stagingDirectory, ".ready.json"),
       JSON.stringify({ ...identity, executableSha256 }),
-      'utf8'
-    )
-    await rm(targetDirectory, { recursive: true, force: true })
-    await rename(stagingDirectory, targetDirectory)
+      "utf8",
+    );
+    await rm(targetDirectory, { recursive: true, force: true });
+    await rename(stagingDirectory, targetDirectory);
   } finally {
-    await rm(stagingDirectory, { recursive: true, force: true })
+    await rm(stagingDirectory, { recursive: true, force: true });
   }
-}
+  await prepareRipgrep(
+    projectDir,
+    targetDirectory,
+    platform,
+    architecture,
+    ripgrepVersion,
+  );
+};

build/signing-key-preflight.cjs

@@ -0,0 +1,31 @@
+function preflightRegisteredProductionKey(options) {
+  const keyId = options.keyId
+  if (!keyId) {
+    throw new Error(options.missingKeyIdMessage)
+  }
+  const signingRecord = options.registry.keys.find(
+    (key) => key.keyId === keyId
+  )
+  if (!signingRecord) {
+    throw new Error(
+      `Production ${options.component} public signing key ID "${keyId}" is absent from resources/agent-release-keys.json; provision the matching public key before building a release`
+    )
+  }
+  if (signingRecord.environment !== 'production') {
+    throw new Error(
+      `Production ${options.component} signing key ID "${keyId}" is not registered for production`
+    )
+  }
+  if (
+    options.registry.revocations.some(
+      (revocation) => revocation.keyId === keyId
+    )
+  ) {
+    throw new Error(
+      `Production ${options.component} signing key ID "${keyId}" is revoked`
+    )
+  }
+  return signingRecord
+}
+
+module.exports = { preflightRegisteredProductionKey }

build/smoke-app/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "goodbuddy-harness-utility-smoke",
+  "private": true,
+  "main": "deepseek-harness-utility-smoke.cjs"
+}

build/verify-desktop-runtimes.cjs

@@ -0,0 +1,39 @@
+const { readdirSync, readFileSync, statSync } = require('node:fs')
+const { join, relative } = require('node:path')
+const { opencodeVersion } = require('./opencode-config.cjs')
+
+function verifyOpenCodeConfig(resources, source) {
+  const destination = join(resources, 'runtimes', 'opencode-config')
+  const manifestPath = join(destination, 'node_modules', '@opencode-ai', 'plugin', 'package.json')
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  if (manifest.name !== '@opencode-ai/plugin' || manifest.version !== opencodeVersion) {
+    throw new Error('Packaged OpenCode plugin version is invalid')
+  }
+  const pending = [source]
+  let files = 0
+  while (pending.length > 0) {
+    const directory = pending.pop()
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const file = join(directory, entry.name)
+      if (entry.isDirectory()) {
+        pending.push(file)
+      } else if (entry.isFile()) {
+        const target = join(destination, relative(source, file))
+        if (!statSync(target, { throwIfNoEntry: false })?.isFile() ||
+            !readFileSync(target).equals(readFileSync(file))) {
+          throw new Error(`Packaged OpenCode dependency is missing or changed: ${relative(source, file)}`)
+        }
+        files++
+      }
+    }
+  }
+  return files
+}
+
+function verifyHarnessBundleImports(source, name) {
+  if (/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?|\brequire\s*\(\s*)["']@deepseek-ai\//u.test(source)) {
+    throw new Error(`DeepSeek Harness bundle contains an external DeepSeek dependency: ${name}`)
+  }
+}
+
+module.exports = { verifyOpenCodeConfig, verifyHarnessBundleImports }

build/verify-site-release.cjs

@@ -0,0 +1,71 @@
+const { readFileSync } = require('node:fs')
+const { resolve } = require('node:path')
+const {
+  targetDefinitions
+} = require('./aggregate-release.cjs')
+
+const expectedInstallerCount = targetDefinitions.reduce(
+  (count, target) => count + target.formats.length,
+  0
+)
+
+function parseArguments(argv) {
+  if (argv.length !== 2 || argv[0] !== '--manifest' || !argv[1]) {
+    throw new Error('必须指定 --manifest')
+  }
+  return { manifest: resolve(argv[1]) }
+}
+
+async function verifySiteRelease(manifest, request = fetch) {
+  const files = Object.values(manifest?.targets ?? {}).flatMap(
+    (target) => Object.values(target?.files ?? {})
+  )
+  if (files.length !== expectedInstallerCount) {
+    throw new Error(`官网发布文件数量错误：${files.length}`)
+  }
+  const urls = new Set()
+  for (const file of files) {
+    if (
+      typeof file?.url !== 'string' ||
+      !Number.isSafeInteger(file.size) ||
+      file.size < 1 ||
+      urls.has(file.url)
+    ) {
+      throw new Error('官网发布文件元数据无效')
+    }
+    urls.add(file.url)
+    const response = await request(file.url, {
+      method: 'HEAD',
+      redirect: 'error'
+    })
+    if (!response.ok) {
+      throw new Error(`OSS 文件不可访问：${file.url}（${response.status}）`)
+    }
+    const contentLength = Number(response.headers.get('content-length'))
+    if (contentLength !== file.size) {
+      throw new Error(
+        `OSS 文件大小不匹配：${file.url}，期望 ${file.size}，实际 ${contentLength}`
+      )
+    }
+  }
+  return files.length
+}
+
+async function main(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv)
+  const manifest = JSON.parse(readFileSync(options.manifest, 'utf8'))
+  const count = await verifySiteRelease(manifest)
+  console.log(`OSS 发布文件验证通过：${count} 个`)
+}
+
+module.exports = {
+  parseArguments,
+  verifySiteRelease
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error)
+    process.exitCode = 1
+  })
+}

build/zip-central-directory.cjs

@@ -0,0 +1,141 @@
+const { readSync } = require('node:fs')
+
+const localFileHeaderSignature = 0x04034b50
+const centralDirectoryHeaderSignature = 0x02014b50
+const endOfCentralDirectorySignature = 0x06054b50
+
+function readExactZipBytes(handle, length, position, label) {
+  const output = Buffer.allocUnsafe(length)
+  let offset = 0
+  while (offset < length) {
+    const bytesRead = readSync(
+      handle,
+      output,
+      offset,
+      length - offset,
+      position + offset
+    )
+    if (bytesRead <= 0) {
+      throw new Error(`${label} is truncated`)
+    }
+    offset += bytesRead
+  }
+  return output
+}
+
+function readZipCentralDirectory(handle, archiveSize, limits) {
+  if (archiveSize < 22) {
+    throw new Error(`${limits.label} central directory is missing`)
+  }
+  const endSize = Math.min(archiveSize, 65_557)
+  const endStart = archiveSize - endSize
+  const end = readExactZipBytes(
+    handle,
+    endSize,
+    endStart,
+    `${limits.label} end record`
+  )
+  let endOffset = -1
+  for (let index = end.length - 22; index >= 0; index -= 1) {
+    if (
+      end.readUInt32LE(index) === endOfCentralDirectorySignature &&
+      index + 22 + end.readUInt16LE(index + 20) === end.length
+    ) {
+      endOffset = index
+      break
+    }
+  }
+  if (endOffset < 0) {
+    throw new Error(`${limits.label} central directory is missing`)
+  }
+  const diskNumber = end.readUInt16LE(endOffset + 4)
+  const centralDisk = end.readUInt16LE(endOffset + 6)
+  const diskEntryCount = end.readUInt16LE(endOffset + 8)
+  const entryCount = end.readUInt16LE(endOffset + 10)
+  const centralSize = end.readUInt32LE(endOffset + 12)
+  const centralOffset = end.readUInt32LE(endOffset + 16)
+  const absoluteEndOffset = endStart + endOffset
+  if (
+    diskNumber !== 0 ||
+    centralDisk !== 0 ||
+    diskEntryCount !== entryCount ||
+    entryCount === 0 ||
+    entryCount === 0xffff ||
+    entryCount < limits.minimumEntries ||
+    entryCount > limits.maximumEntries ||
+    centralSize === 0xffffffff ||
+    centralSize < 46 ||
+    centralSize > limits.maximumCentralDirectoryBytes ||
+    centralOffset === 0xffffffff ||
+    centralOffset + centralSize !== absoluteEndOffset
+  ) {
+    throw new Error(`${limits.label} central directory is invalid`)
+  }
+  const central = readExactZipBytes(
+    handle,
+    centralSize,
+    centralOffset,
+    `${limits.label} central directory`
+  )
+  const entries = []
+  let offset = 0
+  for (let index = 0; index < entryCount; index += 1) {
+    if (
+      offset + 46 > central.length ||
+      central.readUInt32LE(offset) !==
+        centralDirectoryHeaderSignature
+    ) {
+      throw new Error(
+        `${limits.label} central directory entry is invalid`
+      )
+    }
+    const nameLength = central.readUInt16LE(offset + 28)
+    const extraLength = central.readUInt16LE(offset + 30)
+    const commentLength = central.readUInt16LE(offset + 32)
+    const entryLength =
+      46 + nameLength + extraLength + commentLength
+    if (offset + entryLength > central.length) {
+      throw new Error(
+        `${limits.label} central directory entry exceeds its bounds`
+      )
+    }
+    const flags = central.readUInt16LE(offset + 8)
+    const nameBytes = central.subarray(
+      offset + 46,
+      offset + 46 + nameLength
+    )
+    const name = new TextDecoder(
+      flags & 0x0800 ? 'utf-8' : 'latin1',
+      { fatal: true }
+    ).decode(nameBytes)
+    entries.push({
+      name,
+      nameBytes: Buffer.from(nameBytes),
+      flags,
+      compression: central.readUInt16LE(offset + 10),
+      checksum: central.readUInt32LE(offset + 16),
+      compressedSize: central.readUInt32LE(offset + 20),
+      size: central.readUInt32LE(offset + 24),
+      diskStart: central.readUInt16LE(offset + 34),
+      localOffset: central.readUInt32LE(offset + 42)
+    })
+    offset += entryLength
+  }
+  if (offset !== central.length) {
+    throw new Error(
+      `${limits.label} central directory count is invalid`
+    )
+  }
+  return {
+    centralOffset,
+    entries
+  }
+}
+
+module.exports = {
+  centralDirectoryHeaderSignature,
+  endOfCentralDirectorySignature,
+  localFileHeaderSignature,
+  readExactZipBytes,
+  readZipCentralDirectory
+}

docs/architecture/automation-platform-architecture.md

@@ -0,0 +1,589 @@
+# 自动化、监督与记忆平台总体设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.3 |
+| 日期 | 2026-08-19 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 文档角色 | Task/Job、调度、目标、并行实验、会话监督、分区记忆与持续学习的总纲 |
+| 领域模型 | [Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md) |
+
+## 1. 背景
+
+GoodBuddy 当前已经具备若干长期助手能力，但它们仍是彼此分离的功能：
+
+1. 当前 Schedule 已支持单次、每日和每周触发，并在创建时绑定稳定产品级 Task 与真实
+   Conversation；重复触发复用同一身份，文本结果写回 Conversation，独立文件和图片保存为
+   Artifact。到期执行与用户在回复期间继续发送的普通消息共用 Conversation 级持久队列，
+   因而不会与当前回复并发写入同一时间线。IANA 时区、Cron、事件触发、租约、重试和完整
+   Job/Run 抽象仍待实现。
+2. 当前智能心跳支持全局或项目范围的每日、每周回顾，读取有界会话、任务和已确认记忆，
+   生成摘要、记忆建议和后续任务。
+3. 专家执行的 Job 支持有限并发和只读综合，但没有实验变量、重复运行、统一指标和结果晋升。
+4. 记忆已有全局、项目、会话三种作用域，以及偏好、事实、摘要、流程四种类型，
+   但检索、来源、时态、冲突和运行级隔离仍不完整。
+5. 魔法笔记已经提供“内容旁持续出现 AI 评论”的交互，可作为会话监督的体验参考，
+   但它只分析笔记或待办，不观察会话和任务运行。
+
+智能心跳长期方向是面向未来的分区记忆，但该模型尚未设计。近期只改善现有心跳的权威入口
+与 Global / 多 Project 范围，并保留 Task Center 作为 Task 索引。若继续把 Task、调度、
+监督、学习和执行加入“智能心跳”，将无法解释一次后台行为为什么发生、读取了什么、是否
+越权、产生了什么影响。
+
+本设计将这些能力统一到一个平台模型中，同时保留不同产品的清晰边界。
+
+## 2. 核心产品判断
+
+### 2.1 智能心跳保持独立，分区记忆协同另行设计
+
+当前智能心跳继续承担周期回顾、报告和建议，并支持 Global 或指定 Project 范围。它不是
+Task、通用调度器或后台 Agent，也不进入统一 `AutomationPlan.kind`。按分区回顾、候选生成
+以及时间/内部事件唤起需要独立设计，不能从当前心跳行为直接推导，也不创建平行记忆类型。
+
+- Scheduled Task 解决“何时在一个 Task 中执行新的 Job”。
+- Goal Task 解决“围绕结果在同一 Task 中持续规划和推进”。
+- 并行实验解决“隔离多个候选并用相同标准比较”。
+- 会话监督解决“独立观察并在必要时评论、告警或暂停”。
+- 智能心跳当前解决“在什么范围周期回顾并提出报告和建议”。
+- 记忆系统解决“哪些经验可以在什么范围内被未来运行读取”。
+- 持续学习解决“候选经验如何经过评估后改变未来行为”。
+
+这些能力可以共享调度、运行、证据、预算和审计基础，但不能共享一段不断膨胀的提示词。
+
+### 2.2 增加会话监督，但不把它等同于第二个聊天 Agent
+
+建议新增会话监督功能，并借鉴魔法笔记的右侧 AI 评论流：
+
+- 默认只观察和评论，不替用户发言。
+- 只依据可见消息、工具事件、任务状态、成果和目标进行判断。
+- 不读取或展示模型隐藏推理。
+- 评论必须引用具体消息、步骤或证据。
+- 模型监督可以建议暂停，只有确定性安全规则或用户预先批准的门禁才能自动暂停。
+- 监督器不能自动批准工具、扩大目录、跨项目读取记忆或修改安全策略。
+
+### 2.3 先做分区和来源，再做知识图谱
+
+GoodBuddy 当前最需要的不是立即引入重型图数据库，而是保证：
+
+1. 运行只能读取明确允许的记忆分区。
+2. 并行实验的各个 Run 不共享可变记忆。
+3. 每条记忆知道来自哪次会话、任务、监督判断或实验结果。
+4. 新事实与旧事实冲突时保留时态和证据，不静默覆盖。
+5. 记忆进入模型上下文前经过范围、状态、敏感度和预算过滤。
+
+SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现明确的关系追踪和跨实体查询
+需求后，才考虑时间知识图谱。
+
+### 2.4 学习必须有评估门和回滚
+
+“生成一条总结并保存”不等于持续学习。只有当候选经验通过回放或实验验证，并能安全改变
+未来行为时，才构成学习闭环。
+
+初期自动学习只允许产生可审查候选，不允许自动修改：
+
+- 工具权限和审批策略。
+- Electron 安全边界。
+- 项目根目录和数据访问范围。
+- Runtime 当前用户执行权限与 Ask/Execute 边界。
+- 系统级提示词。
+- 远程消息发送或其他外部副作用策略。
+
+## 3. 目标
+
+### 3.1 用户目标
+
+- 在现有 Task Center 中找到 Scheduled、Event 和 Goal Task，并直接打开关联 Conversation
+  和对应 Task。
+- 清楚知道 Task 的触发原因、当前目标、聚合执行状态、预算和停止条件。
+- 在一个工作台中观察多个候选运行，并追溯结论到原始证据。
+- 为重要会话启用独立监督，及时发现偏题、遗漏、矛盾、证据不足和风险。
+- 知道每条记忆属于哪个范围、从哪里产生、何时有效以及被哪些运行使用。
+- 审查、批准、拒绝或回滚系统提出的记忆、模板和策略改进。
+
+### 3.2 产品目标
+
+- 复用现有 Project、Conversation、Task、Run、Artifact、Approval 和 Notification 能力。
+- 保持每个 Task 只关联一条 Conversation，同时允许一条 Conversation 承载多个 Task，不为
+  同一项工作建立第二份内容载体。
+- 为所有后台工作提供统一的幂等、租约、恢复、取消、预算和审计语义。
+- 保持 Ask 只读，Execute 继续经过现有能力和审批控制。
+- 保持本地优先，应用退出后不虚假承诺后台持续执行。
+- 保证项目、会话、自动化和实验 Run 之间的记忆隔离。
+- 先建立可观测和可评估能力，再允许任何形式的自动行为改变。
+
+## 4. 非目标
+
+本组设计不包含：
+
+- 将 GoodBuddy 变为需要常驻服务器、Redis 或云端控制面的多租户平台。
+- 在应用退出后依靠未安装的系统服务继续运行任务。
+- 默认允许无人值守高风险 Execute。
+- 让模型自行扩大工具、目录、知识库、记忆或网络访问范围。
+- 允许多个实验 Run 并发修改同一个用户工作区。
+- 记录键盘、持续录屏或静默监控其他应用。
+- 把隐藏推理链作为监督、记忆或审计数据保存。
+- 初期直接建设通用可视化工作流 DAG 编辑器。
+- 将模型评分当作没有误差的客观真值。
+
+## 5. 统一领域模型
+
+以下模型是 Scheduled Task、Goal Task 和实验共享的技术基础，不要求新增独立
+Automation Center。`AutomationPlan` 是 Task 的计划配置，`Job` 是 Task 内执行单位，
+`Run` 是执行尝试。用户主要通过 Task Center、左侧会话 Task 列表和关联 Conversation
+理解工作；当前 UI 不展示 Job/Run 层级。智能心跳
+不属于此模型。
+
+### 5.1 核心实体
+
+```text
+Conversation
+  └─ Task 0..N
+       ├─ AutomationPlan（可选）
+       │   ├─ TriggerPolicy
+       │   ├─ ObjectiveSet
+       │   ├─ ExecutionProtocol
+       │   ├─ BudgetPolicy
+       │   ├─ ApprovalPolicy
+       │   ├─ SupervisorPolicy
+       │   └─ MemoryBinding
+       └─ Job
+            ├─ Run
+            ├─ Subjob
+            ├─ Observation
+            ├─ SupervisorDecision
+            ├─ Artifact
+            ├─ Metric
+            └─ MemoryCandidate
+```
+
+| 实体 | 职责 |
+| --- | --- |
+| `Task` | 用户可见工作单位，只关联一条 Conversation；Conversation 可以承载多个 Task |
+| `Job` | Task 内部一次步骤、触发、并行分支或委派执行 |
+| `Run` | Task/Job 的一次执行尝试和审计记录 |
+| `AutomationPlan` | Task 的可编辑计划配置，描述做什么、为何做、何时做和允许做什么 |
+| `TriggerPolicy` | 手动、时间、事件或条件触发，以及错过执行策略 |
+| `ObjectiveSet` | 成功标准、优化指标、约束和停止条件 |
+| `ExecutionProtocol` | 本次运行冻结的提示、步骤模板、变量、Runtime、工具和数据范围 |
+| `BudgetPolicy` | 最大耗时、模型调用、Token、工具次数、Job/Subjob 数、成果大小和并发 |
+| `ApprovalPolicy` | 哪些动作可自动执行、哪些等待批准、哪些禁止 |
+| `SupervisorPolicy` | 观察维度、触发频率、干预级别和确定性门禁 |
+| `MemoryBinding` | 运行可读取和可写入哪些记忆分区 |
+| `Observation` | 对消息、步骤、工具、指标或系统状态的结构化观察 |
+| `SupervisorDecision` | `continue`、`comment`、`warn`、`request_review`、`pause` 或 `stop` |
+| `Metric` | 可复现的运行指标及其计算来源 |
+| `MemoryCandidate` | 尚未进入未来上下文的候选经验 |
+
+### 5.2 自动化类型
+
+`AutomationPlan.kind` 第一阶段使用有限枚举，而不是任意工作流：
+
+| 类型 | 说明 |
+| --- | --- |
+| `scheduled_task` | 到点运行一个固定任务 |
+| `goal_loop` | 围绕目标重复执行“观察、计划、行动、评估” |
+| `experiment` | 生成隔离候选 Run，按统一协议评估和比较 |
+
+会话监督不是独立 Task。用户选择 Conversation、Task 或 Experiment 作为监督对象；
+`SupervisorPolicy` 可以在内部观察所属 Job/Run 事件，但当前 UI 不把它们作为独立目标。
+
+### 5.3 运行快照
+
+每次启动必须冻结：
+
+- Plan 版本。
+- 项目和工作目录。
+- Runtime 和模型配置引用。
+- 工作模式。
+- 提示和变量。
+- 工具、Skills、MCP 和知识库范围。
+- 可读、可写记忆分区。
+- 监督策略和评估器版本。
+- 预算和并发限制。
+- 审批策略。
+
+运行开始后的设置变化只影响下一次 Run。用户可以在 Task 执行记录中查看当次快照与最新
+Plan 的差异，但 Run 不作为独立导航对象。
+
+## 6. 统一状态模型
+
+### 6.1 Plan 状态
+
+```text
+draft → active ↔ paused → archived
+```
+
+- `draft`：未通过配置校验，不能自动触发。
+- `active`：可以被触发。
+- `paused`：保留定义和历史，不产生新 Run。
+- `archived`：只读保留，不能恢复运行，复制后可继续使用。
+
+### 6.2 Run 状态
+
+```text
+queued
+  → running
+  → waiting_approval
+  → paused
+  → evaluating
+  → completed
+
+任意活动状态
+  → failed | cancelled | interrupted | budget_exceeded | superseded
+```
+
+规则：
+
+- `completed` 只表示协议成功结束，不自动表示目标达成。
+- `goalStatus` 独立为 `met`、`not_met`、`inconclusive` 或 `not_applicable`。
+- 应用退出时活动 Run 标记为 `interrupted`，不自动重放有副作用步骤。
+- `waiting_approval` 不占用 LLM 并发配额。
+- 预算耗尽必须使用 `budget_exceeded`，不能伪装为普通失败。
+
+### 6.3 Supervisor 状态
+
+```text
+inactive → observing → attention_required → paused → resolved
+```
+
+监督状态不覆盖 Run 状态。Run 可以仍在运行但存在 `attention_required`，也可以因确定性门禁
+进入 `paused`。
+
+## 7. 统一运行循环
+
+### 7.1 调度与执行分离
+
+```text
+Trigger
+  → AutomationCoordinator 在所属 Task 内声明 Job
+  → ExecutionQueue 按优先级和预算排队
+  → AutomationExecutor 为 Job 创建或恢复 Run
+  → Runtime 执行
+  → Supervisor 观察
+  → Evaluator 计算指标
+  → 结果、证据和候选记忆入库
+  → 用户审查或后续执行
+```
+
+`AutomationCoordinator` 只负责触发、声明和恢复，不直接调用模型。执行仍通过 Job 和
+Runtime 边界完成，用户可见结果通过所属 Task 汇入关联 Conversation。
+
+### 7.2 优先级
+
+默认优先级从高到低：
+
+1. 用户正在等待的前台对话。
+2. 用户手动启动的 Task 执行。
+3. 等待批准后恢复的 Task 执行。
+4. 到期 Scheduled Task 的执行。
+5. 目标循环和实验执行。
+6. 心跳回顾、记忆巩固和维护。
+
+后台任务必须可被背压延后。延后记录为 `deferred`，不得丢失，也不得在系统恢复空闲时一次性
+释放全部积压。
+
+### 7.3 Conversation 输入仲裁
+
+当前实现以 Main 和 SQLite 中的 `conversation_queue_items` 作为每条 Conversation 的权威
+输入队列，而不是在 Renderer 分别维护聊天草稿队列和 Scheduled Task 队列：
+
+- 普通消息在发送时冻结 Runtime、工作模式、专家/团队、知识范围和附件上下文，再以
+  `source=user` 入队；附件内容使用有界序列化保存，应用重启后仍可恢复。
+- 到期或手动启动的 Scheduled Task 先建立 `schedule_run`，再以 `source=schedule` 进入同一
+  队列，只派发任务要求和关联会话身份。执行时读取会话最新历史和配置，不保存任务上下文快照。
+- Main 对每条 Conversation 只保留一个活动请求或 Renderer 派发保留位。默认按 FIFO 认领；
+  Scheduled Task 不另设执行器或并发计数。
+- 两种来源均由 Main 派发给 Renderer，建立普通用户消息和流式助手消息后调用 `agent.run`。
+  Renderer 加载会话及设置后才声明队列可派发。SSH 项目同样通过该入口选择远程 Runtime，
+  使用普通请求的上下文、工具范围、取消和恢复流程。
+- `schedule_run.id` 作为普通请求 ID；普通请求终态同步该次计划运行与稳定产品 Task 的状态。
+  尚未接受的派发可释放重试；已经接受的运行在重启后按普通 Task 状态结算或恢复，不重新发送。
+- 当前执行到达终态后再认领下一项。删除只移除尚未执行的项；“立即中断并插入”取消当前
+  请求并把所选项设为下一项，不重排其他项。
+- 每条 Conversation 最多保留 20 个用户可提交的待执行项。启动时将未完成的派发恢复为
+  `pending`，但应用退出期间不会实际执行任务。
+
+Renderer 只通过显式 IPC 列出、加入、删除、提升、释放和接收用户队列项；Main 在接受
+`agent.run` 时校验队列项仍处于 `dispatching` 且属于同一 Conversation，防止 Renderer
+绕过顺序仲裁。
+
+### 7.4 幂等和租约
+
+- 每次计划触发使用 `planId + scheduledFor + planVersion` 形成幂等键。
+- 手动触发使用调用方提供的单次幂等键。
+- Run 和长步骤使用租约，租约过期后才能恢复或重试。
+- 有外部副作用的步骤还需要工具级幂等键，无法确认结果时进入
+  `outcome_unknown`，不得自动重试。
+- 同一个 Plan 可以限制最大活动 Run 数，默认 1。
+
+## 8. 触发模型
+
+### 8.1 支持顺序
+
+| 阶段 | 触发类型 |
+| --- | --- |
+| 第一阶段 | 手动、单次、每日、每周、每月、受限 Cron |
+| 第二阶段 | 应用启动、会话完成、任务完成或失败、文件同步完成、变量变化 |
+| 后续 | 用户定义的组合条件和外部受信任事件 |
+
+事件触发必须来自 Main 进程内的持久事件，不允许 Renderer 临时事件直接启动高影响自动化。
+
+### 8.2 错过执行策略
+
+| 策略 | 行为 |
+| --- | --- |
+| `skip` | 记录跳过，不补跑 |
+| `run_once` | 无论错过多少次，只补一次 |
+| `catch_up_bounded` | 在数量和时间窗口上限内补跑 |
+
+默认：
+
+- 日常摘要使用 `run_once`。
+- 高频事件使用 `skip` 或事件去重。
+- 不允许无限补跑。
+
+## 9. 目标、协议和实验的关系
+
+```text
+目标：想得到什么结果
+协议：用什么固定方法尝试
+运行：协议的一次执行
+实验：同一问题下多个隔离协议或变量组合的运行集合
+监督：运行过程中独立判断是否偏离目标、违反约束或需要人工介入
+记忆：运行可读的历史经验，以及运行结束后提出的候选经验
+```
+
+关键规则：
+
+- 没有可计算或可审查成功标准的目标，不允许宣称“已完成目标”。
+- 实验的最佳结果只在成功 Run 中选择。
+- 全部 Run 失败时，实验状态为失败，不生成伪最佳结果。
+- 模型生成的实验协议必须先由用户审查，或在只读、低成本模板中明确启用自动接受。
+- 实验结果不能直接修改生产自动化，只能创建候选版本。
+
+## 10. 监督边界
+
+监督分为两层：
+
+### 10.1 确定性监督
+
+由代码执行，适合：
+
+- 权限、目录和工具白名单。
+- Token、耗时、并发和输出大小预算。
+- JSON Schema、状态机和幂等约束。
+- 明确的停止条件和指标阈值。
+- 数据分区和跨范围访问。
+
+确定性监督可以阻止、暂停或终止运行。
+
+### 10.2 模型监督
+
+适合：
+
+- 目标偏移。
+- 计划遗漏。
+- 结论与证据不一致。
+- 多个候选之间的定性差异。
+- 用户可能需要澄清的歧义。
+- 质量、表达和风险评论。
+
+模型监督默认只评论或请求关注。它不能替代确定性安全边界，也不能自动批准高风险动作。
+
+## 11. 记忆边界
+
+### 11.1 计划读取链
+
+运行只读取显式绑定的分区。推荐优先级：
+
+```text
+当前 Run
+→ 当前 Automation
+→ 当前 Conversation（如有关联）
+→ 当前 Project
+→ Global
+```
+
+每一层都有独立结果数和字符预算。低层记忆不能通过同名内容自动覆盖高层记忆，
+冲突必须被标记并交给上下文组装器处理。
+
+### 11.2 写入规则
+
+- Run 只能直接写入自己的运行分区和候选区。
+- 向 Automation、Project 或 Global 晋升需要评估或用户确认。
+- 实验 Run 不能直接互相读取运行记忆。
+- Supervisor 的判断保存为观察或候选，不自动变成事实。
+- 被拒绝的候选保留摘要指纹，避免重复建议，同时不进入模型上下文。
+
+## 12. 信息架构
+
+当前阶段保留任务中心并适度完善，不新增独立自动化中心。智能心跳使用自己的菜单入口，
+并已在现有模型上实现 Global / 多 Project 范围与唯一配置入口：
+
+```text
+任务中心
+├─ 需要关注
+├─ 进行中
+├─ 已暂停
+└─ 已结束
+   └─ 打开任务自身
+
+任务自身
+├─ 消息时间线
+├─ Run、步骤与审批活动
+├─ 监督、指标与证据
+└─ 独立成果
+
+智能心跳
+├─ 运行概览
+├─ 待处理建议
+├─ 报告与记录
+└─ 心跳计划
+   └─ Global / 指定 Project
+```
+
+监督统一进入应用级助手工作栏中固定且始终可访问的“监督”栏目，不再保留“独立可折叠右栏”
+和“动态新增页签”两种实现。栏目默认跟随当前上下文，用户可以固定到其他 Conversation、
+Task 或实验对象；详细范围与交互契约见
+[通用助手工作栏与执行空间 PRD](../features/assistant-workbar/prd.md)。
+
+## 13. 安全与隐私
+
+1. Ask 在 Runtime 边界保持只读，而不只是提示词要求只读。
+2. Execute 继续通过现有审批、主机执行策略、工具和目录控制。
+3. 无人值守只允许用户显式批准的能力集合；遇到未预授权动作时进入等待审批。
+4. Supervisor、Evaluator 和 Heartbeat 都把消息、工具输出、记忆和成果视为不可信数据。
+5. 监督器不能读取隐藏推理，只能读取产品允许持久化和展示的事件。
+6. 所有跨分区读取由 Main 根据绑定关系决定，Renderer 不能提交任意分区 ID。
+7. 记忆和监督证据不得包含密钥、认证头、Cookie、完整私有文件或未经限制的工具输出。
+8. 自动化产生的通知默认隐藏私人内容。
+9. 应用退出时停止调度和新执行，持久化中断状态，释放 Runtime 和租约。
+10. 清除项目时按外键和显式事务清理其计划、运行、运行分区、监督记录和候选，
+    不影响 Global 或其他项目。
+
+## 14. 可观测性
+
+每次 Task 执行的内部 Job/Run 记录至少保存：
+
+- 触发来源和计划版本。
+- 计划目标和当前 `goalStatus`。
+- Runtime、工作模式和工作目录。
+- 实际读取的知识库与记忆分区。
+- 实际调用的模型、Token、工具、耗时和成果大小。
+- 当前预算和剩余预算。
+- Task、Job 和 Subjob 状态。
+- Supervisor 评论、证据、严重度和处理结果。
+- 评估器版本、指标和证据。
+- 产生的候选记忆或学习产物。
+- 重试、延后、中断和恢复原因。
+
+UI 在 Task 下呈现上述信息的有界摘要和活动，不提供 Job/Run 树或独立导航。不得只显示一个
+模糊的“自动化成功率”而隐藏失败、跳过或无结论的 Task 执行。
+
+## 15. 建议的数据模型增量
+
+以下为设计建议，字段在实现前仍需共享 Zod Schema 和 SQLite 迁移细化：
+
+```text
+automation_plans
+automation_plan_versions
+automation_triggers
+automation_runs
+automation_run_events
+automation_metrics
+automation_observations
+supervisor_sessions
+supervisor_decisions
+memory_namespaces
+memory_candidates
+learning_artifacts
+evaluation_cases
+evaluation_results
+experiments
+experiment_variants
+experiment_runs
+```
+
+现有 `schedules`、`schedule_runs`、`heartbeat_configs`、`heartbeat_runs`、
+`heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。Schedule 可渐进建立稳定 Task 与
+Conversation 关联，旧 child-task 字段可兼容映射到 Job/Subjob；心跳数据保持独立，不得
+静默转成 `AutomationPlan` 或顶层 Task。分区记忆协同和唤起条件完成设计前，不新增迁移目标。
+
+## 16. 分阶段实施
+
+### 阶段 0：统一术语和可观测性
+
+- 固定 Task、Conversation、Job、Subjob、Run、Plan、Goal、Protocol、Supervisor、
+  Observation、Memory Candidate 等概念。
+- 明确 Task N:1 Conversation 关系、左侧行首展开按钮与 Task 子项图标，以及 Task Center
+  索引边界，不复制内容。
+- 为现有 Scheduled Task 和专家执行建立按 Task 聚合的活动视图。
+- 明确当前心跳保持独立，分区记忆协同与唤起条件尚待设计。
+- 补充触发来源、运行版本、预算和读写范围展示。
+
+### 阶段 1：调度与运行基础
+
+- 统一 Run 声明、幂等、租约、恢复和错过执行策略。
+- 增加月度和受限 Cron。
+- 增加后台优先级与并发预算。
+- 保持现有任务执行器不变。
+
+### 阶段 2：会话监督与分区记忆
+
+- 上线评论型会话监督。
+- 智能心跳配置支持 Global 或指定一个、多个 Project。
+- 增加 Automation 和 Run 记忆分区。
+- 建立来源、证据、时态、冲突和晋升流程。
+
+### 阶段 3：目标任务
+
+- 增加目标、成功标准、约束、预算和停止条件。
+- 支持有界的观察、计划、行动、评估循环。
+- 默认 Ask 或需要逐步审批的 Execute。
+
+### 阶段 4：并行实验
+
+- 变量和运行隔离。
+- 候选、重复、指标、证据、失败结算和最佳结果选择。
+- 复用现有任务和受限子专家并发。
+
+### 阶段 5：持续学习
+
+- 先建立回放集和评估门。
+- 再增加候选、Shadow、晋升、监控、衰减和回滚。
+- 初期只晋升记忆和自动化模板，不自动改变安全策略。
+
+## 17. 相关文档
+
+- [Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md)
+- [Task Center PRD](../features/task-and-job/task-center-prd.md)
+- [Scheduled Task PRD](../features/task-and-job/scheduled-task-prd.md)
+- [Job 与 Subjob PRD](../features/task-and-job/job-and-subjob-prd.md)
+- [智能心跳 PRD](../features/smart-heartbeat/prd.md)
+- [并行实验工作台 PRD](../features/parallel-experiments/prd.md)
+- [会话监督 PRD](../features/conversation-supervision/prd.md)
+- [分区记忆 PRD](../features/memory/prd.md)
+- [持续学习与评估门 PRD](../features/continuous-learning/prd.md)
+- [GoodBuddy 长期助手功能规划](../roadmap/long-term-assistant-roadmap.md)
+- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md)
+
+## 18. 总体验收标准
+
+- [ ] 智能心跳保持独立，不作为 Task 类型；分区记忆协同与唤起条件尚未设计。
+- [ ] Task Center 只索引 Task；每个 Task 只关联一条 Conversation，一条 Conversation 可以
+  关联多个 Task。
+- [ ] 当前 UI 只展示到 Task，不提供 Job/Subjob/Run 树或独立导航。
+- [ ] Scheduled Task 的重复触发和并行 Job 不创建新的顶层 Task。
+- [ ] 每次自动执行的内部 Run 都记录触发原因、目标、范围、预算、状态和结果，并在所属
+  Task 下提供有界可观测信息。
+- [ ] Ask 自动化无法调用写工具或产生外部副作用。
+- [ ] Execute 自动化不能绕过现有审批、主机执行策略和能力控制。
+- [ ] 会话监督默认只评论，不能替用户发言或批准工具。
+- [ ] 并行 Run 的变量、会话、运行记忆、任务和成果相互隔离。
+- [ ] 失败 Run 不参与最佳结果选择，全部失败不报告成功。
+- [ ] 记忆跨分区读取必须显式授权并可审计。
+- [ ] 候选经验在评估门和回滚能力完成前不能自动改变未来行为。
+- [ ] 应用重启后状态可恢复，但不会自动重放结果未知的副作用步骤。

docs/architecture/share-network-architecture.md

@@ -0,0 +1,497 @@
+# GoodBuddy 设备共享与 ShareServer 联邦网络总体设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-09 |
+| 适用范围 | GoodBuddy 桌面端、ShareServer、网关间联邦协议 |
+| 桌面端设计 | [设备发现与共享](../features/device-sharing/README.md) |
+| 服务端设计 | [ShareServer](../../../goodbuddy-shareserver/docs/features/share-server/README.md) |
+
+## 1. 文档职责
+
+本文是设备共享网络的跨端权威设计，负责定义拓扑、术语、身份、能力清单、授权计算、任务
+路由、能力分发、协议边界和共同验收标准。桌面端的产品与界面行为由“设备发现与共享”功能
+文档负责，独立 Web 服务由 ShareServer 功能文档负责。
+
+本文描述完整目标系统，不以交付阶段删减领域模型，也不把尚未实现的设计表述为当前能力。
+
+## 2. 核心决策
+
+### 2.1 两个独立产品面
+
+1. **GoodBuddy Desktop** 在设置中提供“设备发现与共享”，默认使用局域网发现与直连，也可
+   由用户额外连接一个或多个 ShareServer。
+2. **ShareServer** 是独立部署、独立升级的 Web 服务，提供组织、设备、能力、权限、更新、
+   联邦、中继、Office 编辑和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。
+
+### 2.2 能力优先，来源可见
+
+用户日常选择的是能力，不是网络连接。设备、ShareServer 和组织作为能力来源与诊断入口。
+任何调用都必须持续显示提供者、执行位置和数据去向，不能为了统一体验隐藏跨设备或跨组织
+边界。
+
+### 2.3 局域网是默认连接方式，网关是显式附加连接
+
+- 桌面端没有网关配置时，局域网发现、配对、调用和本机共享仍可完整工作。
+- 添加、删除或断开 ShareServer 不改变局域网配对关系。
+- ShareServer 不接管本机局域网发现，也不能静默把局域网设备注册到组织。
+- 同一桌面端可以连接多个 ShareServer；能力来源和授权按连接分别计算。
+
+### 2.4 发现、被发现和开放能力是三个独立动作
+
+- **发现设备**：浏览同一局域网中主动广播的 GoodBuddy 服务。
+- **允许被发现**：广播本设备存在及配对入口。
+- **开放能力**：向指定设备、用户组或组织发布可查看、调用或拉取的能力。
+
+开启其中一项不能推导另外两项已开启。新安装默认不开放能力。
+
+### 2.5 ShareServer 优先作为控制面
+
+ShareServer 负责身份、目录、策略、任务路由、更新和审计。数据面优先在两个已认证端点之间
+直接建立；网络条件不允许时，可按组织策略使用 ShareServer 中继。是否允许中继、正文是否
+端到端加密、是否允许跨组织，由本次任务冻结的策略共同决定。
+
+### 2.6 Office 编辑是 ShareServer 托管服务
+
+ShareServer 可以把 ONLYOFFICE Docs、工作副本存储、保存回调和编辑会话作为一个可选部署
+能力提供给 Desktop。Desktop 只连接用户已明确配置的 ShareServer，不直接配置 Document
+Server，也不在本机启动服务。Office 文档内容会由 ShareServer 和编辑引擎处理，因此不能沿用
+“控制面默认不读取正文”的数据面假设；创建编辑会话前必须明确显示服务端、数据去向和保留期。
+
+编辑后的本地或 SSH 源文件仍由 Desktop 或远程 GoodBuddy Agent 持有和原子回写。ShareServer
+是工作副本及服务端保存检查点的权威，不是源文件最终写入成功的权威。完整设计见
+[Office 协同编辑](../features/office-document-editing/README.md)。
+
+## 3. 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| `Device` | 安装 GoodBuddy 并拥有稳定设备身份的终端 |
+| `Peer` | 与当前设备存在局域网配对关系的另一台设备 |
+| `ShareServer` | 提供组织控制面和可选数据中继的独立服务 |
+| `Organization` | ShareServer 中隔离成员、设备、能力与策略的管理范围 |
+| `GatewayConnection` | 某台设备与一个 ShareServer 上特定组织身份的连接 |
+| `Capability` | 可被查看、调用或分发的稳定能力标识 |
+| `CapabilityProvider` | 实际持有并执行某项能力的设备或服务节点 |
+| `Publication` | 能力提供者向某一范围发布的可见性和使用声明 |
+| `Grant` | 主体对能力执行某类动作的明确授权 |
+| `Task` | 一次远程能力调用及其输入、执行、输出和终态 |
+| `Package` | 可下载到本机安装的签名能力工件 |
+| `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 |
+| `DocumentEditSession` | ShareServer 托管的单文档短期编辑会话、工作副本和保存检查点 |
+
+“网关”是 ShareServer 的网络角色；产品名称为 `ShareServer`，独立仓库为
+`goodbuddy-shareserver`。
+
+## 4. 系统拓扑
+
+```text
+局域网：
+GoodBuddy Desktop A <-- mDNS 发现 + 配对后 TLS 直连 --> GoodBuddy Desktop B
+
+单组织：
+GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B
+
+Office 编辑：
+GoodBuddy Desktop --> ShareServer --> ONLYOFFICE Docs
+                         └-------> 临时工作副本与保存检查点
+
+跨组织：
+Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Device B
+```
+
+局域网和网关连接共享能力、授权和任务的领域语义，但不共享发现方式：
+
+| 维度 | 局域网 | ShareServer |
+| --- | --- | --- |
+| 发现来源 | mDNS/DNS-SD 主动广播 | 已配置 URL 或邀请链接 |
+| 初始身份 | 双端验证码确认设备指纹 | 用户登录、设备注册和组织成员身份 |
+| 能力目录 | 已配对设备直接返回 | 服务端按组织策略过滤 |
+| 连接方向 | 配对后直连 | 设备主动建立出站连接 |
+| 管理范围 | 单个设备间授权 | 用户组、组织和联邦授权 |
+| 审计权威 | 两端各自本地记录 | 组织网关记录元数据，两端保留本地记录 |
+
+## 5. 组件边界
+
+### 5.1 GoodBuddy Desktop
+
+- 浏览和广播局域网服务。
+- 创建、确认和撤销点对点配对。
+- 连接 ShareServer，保存脱敏连接信息和本机受保护凭据。
+- 发布用户明确选择的本机能力。
+- 展示经当前身份过滤的能力目录。
+- 在调用前冻结提供者、输入范围、授权和路由。
+- 执行本机提供的任务，或消费远端任务结果。
+- 校验并安装用户明确选择的签名能力包。
+- 保存本机活动记录和可撤销授权。
+
+### 5.2 ShareServer
+
+- 认证用户、设备、服务节点和其他 ShareServer。
+- 管理组织、成员、用户组和设备目录。
+- 接收能力发布并生成权限过滤后的目录。
+- 计算组织强制策略，签发短期任务授权。
+- 路由任务、维护在线状态，并在允许时中继数据。
+- 管理签名包、发布通道、更新策略和撤销。
+- 可选管理 Office 编辑会话、ONLYOFFICE 接入、工作副本、保存回调、保留和清理。
+- 建立双边联邦关系并限制跨组织可见性与调用。
+- 保存有界审计元数据、用量和管理操作。
+
+### 5.3 能力提供者
+
+- 只执行已发布且本次授权允许的能力。
+- 在执行边界重新验证任务令牌、输入 schema、大小、期限和调用方。
+- 使用自身 Runtime、账号、工作区和数据权限。
+- 返回有界进度、结果、成果或确定终态。
+- 不因收到任务令牌而获得其他能力或任意系统接口。
+
+## 6. 身份与信任
+
+### 6.1 设备身份
+
+每次 GoodBuddy 安装生成稳定设备密钥和自签设备证书，私钥保存在系统安全存储中。对外只
+使用随机设备 ID、公钥指纹、用户设置的设备名称和必要协议版本。操作系统用户名、绝对路径、
+软件资产和能力详情不进入未认证发现广播。
+
+重装或主动重置设备身份会产生新设备。旧局域网配对和 ShareServer 设备注册不会自动迁移。
+
+### 6.2 局域网配对
+
+1. 发起端选择一台主动广播的设备。
+2. 双方建立临时加密通道并计算共同短验证码。
+3. 两端同时显示设备名、系统类型、公钥指纹和验证码。
+4. 双方用户确认后保存对端公钥及配对 ID。
+5. 后续使用双方设备证书认证；任一端可以撤销配对。
+
+IP 地址不作为设备身份，也不单独构成授权依据。
+
+### 6.3 ShareServer 注册
+
+用户通过浏览器/OIDC 或服务端支持的登录方式认证后，为当前设备申请一次性注册挑战。设备
+使用自身私钥签名挑战，ShareServer 建立 `user + organization + device` 绑定并签发可轮换的
+设备凭据。设备凭据不等同于用户 Web 会话，不可用于管理控制台登录。
+
+### 6.4 联邦身份
+
+两个 ShareServer 由双方管理员交换组织标识、网关公钥、公开端点和指纹，并分别确认信任。
+联邦关系只有在双方状态均为 `active` 时生效。单方暂停或撤销后立即停止新目录交换和新任务，
+已执行任务保留审计终态。
+
+## 7. 能力模型
+
+### 7.1 能力清单
+
+```json
+{
+  "schemaVersion": "1.0",
+  "capabilityId": "document.convert.docx",
+  "name": "文档转 Word",
+  "version": "1.4.0",
+  "modes": ["remote", "package"],
+  "inputSchema": {},
+  "outputSchema": {},
+  "permissions": ["receive_text", "receive_files", "return_files"],
+  "limits": {
+    "maxInputBytes": 10485760,
+    "maxOutputBytes": 52428800,
+    "maxDurationSeconds": 900,
+    "maxConcurrentTasks": 2
+  },
+  "dataPolicy": {
+    "retention": "task_lifetime",
+    "networkAccess": false,
+    "delegation": "none"
+  }
+}
+```
+
+清单只描述能力事实，不授予任何主体访问权。`inputSchema` 和 `outputSchema` 使用受限 JSON
+Schema 子集；实现必须限制 schema 深度、属性数、枚举数和总字节，不能把清单当作可执行代码。
+
+### 7.2 发布声明
+
+`Publication` 将一个能力版本发布到以下一种范围：
+
+- 指定局域网 Peer。
+- 所有已配对 Peer。
+- ShareServer 内指定用户、用户组或设备组。
+- 指定联邦组织中的用户组。
+
+发布声明同时定义允许动作：`discover`、`inspect`、`invoke`、`download`。`inspect` 允许查看
+详细清单，`discover` 只允许看到名称和可用状态。
+
+### 7.3 可调用与可分发
+
+- `remote`：代码与受控数据留在提供方，调用方只发送输入并接收结果。
+- `package`：签名工件下载到调用方，经校验和用户/组织策略批准后安装。
+
+同一能力可以同时支持两种模式，但两种模式分别授权。远程调用授权不能推导下载权，下载权
+也不能推导安装后自动启用。
+
+## 8. 授权模型
+
+### 8.1 授权输入
+
+一次动作的最终决定取以下约束交集：
+
+```text
+调用方用户权限
+∩ 调用方设备状态
+∩ 调用方组织强制策略
+∩ 发布范围
+∩ 提供方授权
+∩ 提供方组织强制策略
+∩ 能力输入与数据策略
+∩ 联邦关系限制（跨组织时）
+= allow | require_approval | deny
+```
+
+`deny` 优先于 `require_approval`，`require_approval` 优先于 `allow`。客户端偏好只能在组织强制
+策略允许的范围内收紧权限，不能放宽权限。
+
+### 8.2 Grant
+
+Grant 至少绑定：
+
+- 主体：用户、用户组、设备、设备组或外部组织。
+- 能力 ID 和允许的版本范围。
+- 动作：查看、调用、下载、安装或发布。
+- 输入：文本、文件、数据分类、单项和累计大小。
+- 提供者和执行位置限制。
+- 次数、并发、预算、时间段和有效期。
+- 是否需要每次批准。
+- 是否允许委托及明确的下游组织。
+
+“始终允许”只创建与当前能力、提供者、输入类型和范围匹配的 Grant，不创建整台设备的任意
+访问权。
+
+### 8.3 转委托
+
+默认 `delegation=none`。允许委托时，任务授权中必须冻结完整执行链和最大跳数。任一新组织、
+新能力或新数据接收方加入执行链，都需要重新计算授权，不能沿用原任务令牌。
+
+## 9. 任务协议
+
+### 9.1 任务快照
+
+创建任务时冻结：
+
+- 调用方用户、设备和组织。
+- 能力 ID、版本和提供者。
+- 输入 schema 版本、数据类型、数据分类和字节数。
+- 路由：局域网直连、网关直连、网关中继或联邦路径。
+- 授权决定、批准记录和策略版本。
+- 委托链、预算、期限和幂等键。
+
+设置或策略后续变化不追改已接受任务；紧急撤销可以阻止尚未开始的任务，并按策略取消活动
+任务。
+
+### 9.2 状态
+
+```text
+created -> awaiting_approval -> queued -> connecting -> running
+running -> completed | failed | cancelled | outcome_unknown
+created/awaiting_approval/queued/connecting -> rejected | expired | cancelled
+```
+
+- `completed` 只在提供者提交完整终态且调用方确认接收后成立。
+- 网络中断后无法确认副作用结果时使用 `outcome_unknown`，不得自动重放。
+- 重试创建新 attempt，并复用仅在能力声明支持时才有效的幂等键。
+- 用户取消必须传播到实际提供者；未确认取消时不能声称任务已停止。
+
+### 9.3 数据传输
+
+- 小型 JSON 输入使用任务通道传输。
+- 文件使用内容 SHA-256、声明大小和一次性任务对象令牌传输。
+- 接收端边读边校验大小和摘要，拒绝路径、符号链接和调用方文件名决定的落盘位置。
+- 任务正文、文件和输出不进入普通网关审计日志。
+- 中继模式下是否端到端加密由策略快照明确记录；界面必须显示网关能否读取正文。
+
+## 10. 能力包与更新
+
+每个 Package 必须提供不可变版本、目标平台和架构、内容大小、SHA-256、发布者签名、权限
+声明、依赖和兼容范围。安装流程统一为：
+
+```text
+取得签名目录 -> 选择不可变目标 -> 下载暂存 -> 校验大小/摘要/签名
+-> 展示权限差异 -> 批准 -> 安装到 GoodBuddy-owned 目录 -> 验证 -> 启用
+```
+
+要求：
+
+- 下载开始后冻结来源，不在失败时静默切换 ShareServer 或镜像。
+- 包不得包含凭据；配置只携带非敏感结构和密钥引用。
+- 新版本扩大文件、进程、网络、数据或委托权限时，旧 Grant 不自动继承。
+- 紧急撤销阻止新安装和新调用；已安装包的停用或删除遵循组织策略并向用户说明。
+- 复用现有 GoodBuddy 签名工件原则，但不同用途使用独立签名域。
+
+## 11. 协议分层
+
+### 11.1 局域网发现层
+
+- DNS-SD 服务类型：`_goodbuddy-share._tcp.local`。
+- 广播仅包含协议 major、随机实例 ID、端口和配对状态。
+- 设备名称、证书和详细版本通过临时加密握手取得。
+- 不扫描任意端口，不枚举未主动广播的机器。
+
+### 11.2 ShareServer 控制 API
+
+使用 HTTPS 提供登录、设备注册、目录、管理和审计 API；使用 WebSocket 建立设备出站控制
+通道，承载心跳、任务声明、取消和短期数据通道协商。普通管理 API 与设备通道使用不同凭据
+和受众。
+
+### 11.3 数据通道
+
+数据通道可以是配对 TLS 直连、ShareServer WebSocket 中继或经网关协商的端到端加密流。
+协议只保证有界帧、顺序、取消和终态，不自行实现另一套拥塞控制。
+
+### 11.4 版本协商
+
+- 每层独立声明 `major.minor`。
+- major 不同拒绝连接；minor 使用双方共同支持的最低能力集合。
+- 未识别字段在声明允许扩展的位置忽略，安全与授权枚举中的未知值一律拒绝。
+- 联邦只交换双方共同支持的能力和策略表达式，不降低任一方策略。
+
+### 11.5 Office 编辑协议
+
+Office 编辑使用独立的 HTTPS 会话、文件和事件 API，不复用普通远程能力 Task 表达长生命周期
+编辑器。Desktop 通过设备凭据创建会话和传输源文件；编辑器使用一次性启动授权；ONLYOFFICE
+使用独立短期 JWT 获取工作副本并提交保存回调。三类凭据使用不同 audience，不能互换。
+
+文档页签可以长期存在，但启动 URL、文件 URL、callback token 和编辑 Cookie 必须短期、单用途
+并可撤销。跨端会话、保存和冲突规则见
+[Office 协同编辑技术设计](../features/office-document-editing/technical-design.md)。
+
+## 12. 数据与审计
+
+### 12.1 最小审计事件
+
+- 操作者、调用设备和组织。
+- 动作、能力、版本和提供者。
+- 路由与是否跨组织。
+- 输入数据类别、分类、文件数和字节数。
+- 授权结果、策略 ID 和批准者。
+- 任务状态、耗时、输出大小和资源用量。
+- 包下载、安装、更新、撤销和发布变更。
+
+默认不保存提示正文、文件内容、模型输出、密钥、Cookie、认证头或完整私有路径。需要内容
+审计的组织必须单独定义保留期限和访问角色，并在调用前向用户显示。
+
+### 12.2 数据权威
+
+- 桌面端是本地配对、本机共享偏好和本地活动记录的权威。
+- ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。
+- ShareServer 是 Office 工作副本、服务端保存检查点、编辑会话和保留清理的权威；Desktop 或
+  远程 GoodBuddy Agent 是源文件是否成功回写的权威。
+- 能力提供者是运行中任务及结果是否产生的权威。
+- 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。
+
+## 13. 安全边界
+
+ShareServer 可以部署到公网，因此公网连接、外部组织和服务端多租户是本设计中的实际信任
+边界。共同要求如下：
+
+1. 所有远端清单、名称、schema、错误、文件和模型输出都作为不可信数据处理。
+2. Renderer 不接触设备私钥、网关令牌、任意 socket 或原始文件传输接口。
+3. Main/Provider 在执行边界重新验证任务，不信任 Renderer 或 ShareServer 代替本机授权。
+4. ShareServer 按组织隔离查询，搜索和计数接口不能泄露无权查看的设备或能力。
+5. 设备只建立主动配置的网关出站连接，不接受 ShareServer 发起任意系统调用。
+6. 局域网发现不等于信任，组织成员身份也不等于所有能力授权。
+7. 远程能力不能扩大本机 Ask/Execute、Workspace、Runtime、Skill 或 MCP 现有权限。
+8. 密钥只进入对应安全存储，诊断和审计使用固定字段与脱敏错误码。
+9. 限制握手、清单、帧、文件、并发、速率、任务时长和审计查询大小。
+10. 撤销设备、用户、Grant、Publication、Package 或 FederationTrust 后停止签发新令牌。
+11. Office 编辑器使用固定 origin 和隔离会话，不获得 Electron、文件系统、Shell、Runtime 或
+    普通 ShareServer 管理 API；Document Server 默认禁止任意出站网络和未批准插件。
+12. Office 文件正文由服务端实际处理，组织策略必须定义允许格式、大小、保留和内容访问角色，
+    Desktop 在上传前显示这些事实。
+
+## 14. 建议领域实体
+
+```text
+DeviceIdentity
+PeerPairing
+GatewayConnection
+Organization
+Membership
+Group
+RegisteredDevice
+Capability
+CapabilityVersion
+Publication
+Grant
+Policy
+Approval
+Task
+TaskAttempt
+ArtifactTransfer
+Package
+PackageRelease
+FederationTrust
+AuditEvent
+Revocation
+DocumentEditSession
+DocumentCheckpoint
+```
+
+共享协议只定义跨端 DTO 和状态，不规定桌面 SQLite 与 ShareServer 数据库使用相同表结构。
+
+## 15. 仓库边界
+
+当前仓库边界（跨仓库文档链接约定两个仓库克隆到同一级目录）：
+
+```text
+goodbuddy/
+  docs/architecture/share-network-architecture.md
+  docs/features/device-sharing/
+  src/                   # GoodBuddy Desktop
+goodbuddy-shareserver/
+  docs/features/share-server/
+  server/                # 独立 Hono Web 服务
+  shared/                # 当前原型 fixture，不是跨端协议
+  src/                   # React 管理前端
+```
+
+ShareServer 源码和服务端文档已迁入独立仓库：
+`ssh://git@git.digiman.live:11022/root/goodbuddy-shareserver.git`。
+当前服务是交互原型，尚未提供真实 Desktop 集成。共享网络总体设计仍由本文统一维护。
+
+ShareServer 不反向依赖桌面端 `src/shared`，构建和运行不要求桌面仓库存在。
+真实跨端协议实现时双方依赖独立 `share-protocol` 包，具体仓库归属和发布方式届时确定，
+不提前创建空包。协议包不得包含数据库模型、Electron API、服务实现或凭据。
+
+## 16. 共同验收标准
+
+- [ ] 不配置 ShareServer 时，两台桌面端可通过局域网发现、双端配对、查看获准能力并调用。
+- [ ] 关闭“允许被发现”不会关闭主动发现；关闭主动发现不会撤销既有配对。
+- [ ] 本机没有明确 Publication 时，任何 Peer 或组织成员都不能查看或调用本机能力。
+- [ ] 桌面端可以连接多个 ShareServer，任一连接故障不影响局域网和其他连接。
+- [ ] ShareServer 只展示当前用户、设备和组织获准查看的目录。
+- [ ] 每次远程调用都能说明提供者、执行位置、发送数据、路由、授权依据和委托链。
+- [ ] 网络中断且副作用结果不确定时进入 `outcome_unknown`，不会自动重放。
+- [ ] 能力包经大小、SHA-256、签名、兼容和权限差异校验后才能安装。
+- [ ] 跨组织调用同时满足两端策略；联邦撤销后不能创建新任务。
+- [ ] 审计默认只保存必要元数据，不保存正文、文件、密钥或认证信息。
+- [ ] ShareServer 可独立部署和升级，不由 Electron 启动，也不影响桌面端离线使用。
+- [ ] 启用 Office 服务后，Desktop 可在多实例文档页签中编辑 DOCX、XLSX 和 PPTX；保存回调、
+  源文件冲突或网络故障均不会破坏原文件。
+- [ ] Office 会话的启动、文件和 callback 凭据不可互换，过期或撤销后不能重用；临时工作副本
+  按策略清理，默认审计不保存文档正文或 AI 选区内容。
+
+## 17. 相关设计
+
+- [设备发现与共享 PRD](../features/device-sharing/prd.md)
+- [设备发现与共享功能逻辑](../features/device-sharing/logic-design.md)
+- [设备发现与共享 UI](../features/device-sharing/ui-design.md)
+- [设备发现与共享技术设计](../features/device-sharing/technical-design.md)
+- [ShareServer PRD](../../../goodbuddy-shareserver/docs/features/share-server/prd.md)
+- [ShareServer 功能逻辑](../../../goodbuddy-shareserver/docs/features/share-server/logic-design.md)
+- [ShareServer 管理界面](../../../goodbuddy-shareserver/docs/features/share-server/ui-design.md)
+- [ShareServer 技术设计](../../../goodbuddy-shareserver/docs/features/share-server/technical-design.md)
+- [Office 协同编辑](../features/office-document-editing/README.md)
+- [SSH 远程主机与 Agent](../features/remote-host/README.md)
+- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md)

docs/development/loongarch-preview-build.md

@@ -0,0 +1,252 @@
+# GoodBuddy 龙芯（LoongArch）预览版构建
+
+本文档是 GoodBuddy 龙芯预览版的权威构建与功能状态说明。当前目标是
+Debian `loong64` 桌面，不代表 GoodBuddy 已将龙芯纳入正式发布支持矩阵。
+
+## 当前状态
+
+当前流程可以在 AMD64 Linux 主机上交叉构建一个独立的
+`goodbuddy-loongarch-preview` DEB，并校验包内 Electron、node-pty 和 Koffi
+均为 LoongArch ELF。
+
+预览版使用社区维护的 Electron 42.3.0 LoongArch 构建。GoodBuddy 正式版本
+当前使用 Electron 43.2.0，因此该预览包只用于移植和真机验证，不能作为正式
+发布基线。Electron 官方目前也不提供 Linux LoongArch 预编译包。
+
+已完成的实际构建结果：
+
+| 项目 | 结果 |
+| --- | --- |
+| GoodBuddy 源版本 | `0.11.0` |
+| 预览版本 | `0.11.0-loong64-preview.1` |
+| Debian 架构 | `loong64` |
+| Electron | 社区版 `42.3.0` |
+| DEB 包名 | `goodbuddy-loongarch-preview` |
+| 构建产物 | `GoodBuddy-0.11.0-linux-loong64-preview.deb` |
+| 已验证构建时间（UTC） | `20260825T102937Z` |
+| 已验证产物大小 | `187053208` bytes |
+| 已验证产物 SHA-256 | `461ade49f10a20ef7b28163077a2ecd6afd2c5b1b0befc673c6d174fd58497b3` |
+| DEB 解包、架构和动态库解析 | 已通过 |
+| QEMU Electron 初始化 | 共享库解析通过；Chromium 多线程初始化在 QEMU 下异常退出 |
+| 龙芯真机启动 | 尚未验证 |
+
+版本号和产物名会跟随当前 `package.json` 版本变化，上表只记录首次成功构建。
+
+## 功能列表
+
+“已打包”只表示所需代码或组件进入 DEB，不等同于已在龙芯桌面完成运行验证。
+
+| 功能 | 预览包状态 | 当前验证 |
+| --- | --- | --- |
+| GoodBuddy Electron 桌面主体 | 已打包 | Electron 可执行文件为 LoongArch ELF；尚未完成真机 GUI 启动 |
+| React 界面和主进程业务代码 | 已打包 | 生产 bundle 构建、测试、类型检查和 lint 已通过 |
+| 直接模型调用路径 | 已打包 | JavaScript 代码与生产依赖已包含；待龙芯真机端到端验证 |
+| Continue Runtime | 已打包 | CLI JavaScript 入口及 npm Runtime 已包含；待真机执行验证 |
+| 本地终端能力 | 已打包 | 输入锁文件固定的 node-pty（当前为 1.2.0-beta.15）已针对 Electron 42.3.0 交叉编译并验证为 LoongArch ELF；待真机 PTY 验证 |
+| Koffi glibc 原生绑定 | 已打包 | Koffi 3.1.4 LoongArch glibc binding 已校验为 LoongArch ELF |
+| 内置 Skills | 已打包 | 静态资源已进入 DEB |
+| GoodBuddy Agent | **不包含** | 当前 Agent 的正式构建和双 glibc/musl 产物契约不支持 LoongArch |
+| Remote Runtime | **不包含** | 当前没有 LoongArch Remote Runtime 产物 |
+| OpenCode Runtime | **不包含** | OpenCode 所需 Bun Runtime 当前不支持 LoongArch |
+| 原生 Canvas 图像解码 | **不包含** | npm 当前没有 `@napi-rs/canvas-linux-loong64-gnu` 包 |
+| Koffi musl binding | **不包含** | Koffi 3.1.4 只发布了 `linux_loong64` glibc binding |
+| 正式自动更新和发布索引 | **不支持** | 预览包不加入正式 CI、安装包矩阵或更新索引 |
+
+在真机验证完成前，不应把“已打包”功能描述为正式可用。尤其是窗口显示、GPU、
+音频、系统托盘、桌面集成、PTY 交互和模型调用都必须在真实 LoongArch 桌面上
+重新验证。
+
+## 与正式 GoodBuddy 隔离
+
+预览版有意使用单独身份，避免覆盖正式安装：
+
+- Debian 包名：`goodbuddy-loongarch-preview`
+- 产品名：`GoodBuddy LoongArch Preview`
+- 可执行文件：`goodbuddy-loongarch-preview`
+- 安装目录：`/opt/GoodBuddy-LoongArch-Preview`
+- Electron 应用身份与正式 GoodBuddy 不同，因此使用单独的用户数据目录
+
+该流程不会修改 `.github/workflows/packages.yml`，也不会把 `loong64` 加入
+正式 release manifest 或下载索引。
+
+## 构建前提
+
+### 本地源码主机
+
+- 已完成 `npm ci`
+- Node.js 和 npm 版本满足仓库要求
+- 可以成功执行 `npm run build:bundle`
+
+### AMD64 交叉构建主机
+
+- Linux AMD64
+- Docker
+- 建议至少 30 GiB 内存和 50 GiB 可用磁盘
+- 可访问 Ubuntu、npm、Electron headers 和社区 Electron Release
+
+### Electron LoongArch shell
+
+从
+[`darkyzhou/electron-loong64`](https://github.com/darkyzhou/electron-loong64)
+的 Releases 下载：
+
+```text
+electron-v42.3.0-linux-loong64.zip
+```
+
+构建脚本固定校验以下 SHA-256，摘要不匹配时必须停止：
+
+```text
+92b0ca0c9c18ed90166918a4ac1970266c4fa967aee9277031b3b250b905526e
+```
+
+这是社区产物，不是 Electron 官方发布的 Linux LoongArch 二进制。
+
+## 第一步：生成架构无关输入
+
+在 GoodBuddy 仓库根目录执行：
+
+```sh
+npm ci
+npm run build:bundle
+node build/loongarch-cross/prepare-input.cjs
+```
+
+默认输出：
+
+```text
+dist/loongarch-cross/goodbuddy-loongarch-cross-input.tgz
+```
+
+输入归档包含生产 `out`、锁文件、Skills、Continue Runtime、npm Runtime、
+图标和发布元数据。它不包含 Agent、Remote Runtime 或 OpenCode 二进制。
+
+可通过 `--output` 指定其他输出位置：
+
+```sh
+node build/loongarch-cross/prepare-input.cjs \
+  --output /path/to/goodbuddy-loongarch-cross-input.tgz
+```
+
+## 第二步：构建交叉工具链镜像
+
+将 `build/loongarch-cross`、输入归档和 Electron zip 放到 AMD64 Docker
+主机，然后执行：
+
+```sh
+docker build \
+  --tag goodbuddy-loongarch-cross:ubuntu-26.04 \
+  build/loongarch-cross
+```
+
+工具链镜像包括：
+
+- `loongarch64-linux-gnu-gcc` 和 G++
+- LoongArch glibc 开发 sysroot
+- QEMU user mode
+- CMake 和 Ninja
+- Rust `loongarch64-unknown-linux-gnu` target
+- Node.js、npm 和上游 node-gyp
+
+可先运行基础探针：
+
+```sh
+mkdir -p build/loongarch-cross/results
+docker run --rm \
+  --volume "$PWD/build/loongarch-cross/results:/results" \
+  goodbuddy-loongarch-cross:ubuntu-26.04
+```
+
+探针必须通过 C、C++、CMake、Rust、NAPI-RS、QEMU、DEB、Koffi 和
+node-pty 检查。Canvas 和 Koffi musl 显示为 unavailable 是当前已知限制，
+不是 Debian 桌面主体 DEB 的构建失败。
+
+## 第三步：生成预览 DEB
+
+假设交叉构建主机上的文件布局如下：
+
+```text
+input/goodbuddy-loongarch-cross-input.tgz
+electron/electron-v42.3.0-linux-loong64.zip
+preview-output/
+```
+
+运行：
+
+```sh
+docker run --rm \
+  --entrypoint /usr/local/bin/goodbuddy-loongarch-preview-deb \
+  --volume "$PWD/input:/input:ro" \
+  --volume "$PWD/electron:/electron:ro" \
+  --volume "$PWD/preview-output:/preview-output" \
+  goodbuddy-loongarch-cross:ubuntu-26.04 \
+  /input/goodbuddy-loongarch-cross-input.tgz \
+  /electron/electron-v42.3.0-linux-loong64.zip \
+  /preview-output
+```
+
+每次构建创建一个 UTC 时间戳目录，包含：
+
+```text
+GoodBuddy-<version>-linux-loong64-preview.deb
+preview-manifest.json
+SHA256SUMS
+```
+
+脚本会执行以下强制检查：
+
+1. 校验 Electron zip 的固定 SHA-256。
+2. 删除 npm 错误解析出的宿主架构可选原生包。
+3. 按 lockfile integrity 校验并安装 Koffi LoongArch glibc binding。
+4. 读取输入 lockfile 固定的 node-pty 版本，并使用上游 node-gyp 11.4.2
+   和 Electron 42.3.0 headers 交叉编译。
+5. 拒绝 `node_modules` 中任何不是 LoongArch ELF 的 `.node` 文件。
+6. 拒绝意外进入包内的 Agent、Remote Runtime 或 OpenCode 目录。
+7. 生成 `Architecture: loong64` 的 DEB，解包后再次校验关键 ELF。
+
+Ubuntu 发行版自带的 node-gyp 会在 Linux addon 链接阶段无条件添加
+`-lnode`，不适合此 Electron 交叉编译；不要用它替换脚本固定的上游
+node-gyp。
+
+## 验证边界
+
+### 已由交叉构建验证
+
+- C、C++、CMake 和 Rust 生成 LoongArch ELF
+- C、C++ 和 Rust 程序通过 QEMU user mode 执行
+- 最小 NAPI-RS addon 交叉编译
+- node-pty 针对 Electron headers 交叉编译
+- Koffi LoongArch glibc binding 架构
+- Electron、node-pty、Koffi 和 DEB `loong64` 元数据
+- DEB 完整解包
+- Debian Forky rootfs 中 Electron 全部共享库解析；该检查发现并补充了
+  `libpulse0` DEB 依赖
+
+### 仍需真实龙芯桌面验证
+
+1. 安装 DEB 并从桌面入口启动。
+2. 验证窗口、渲染、GPU 回退、输入法、系统托盘和通知。
+3. 配置模型并执行一次真实的直接模型对话。
+4. 验证 Continue Runtime 启动、取消和退出清理。
+5. 打开本地终端，验证 node-pty 输入、输出、窗口缩放和进程回收。
+6. 验证 Koffi 使用路径。
+7. 验证音频、文件选择器、剪贴板和外部链接。
+8. 确认 Agent、Remote Runtime、OpenCode 和 Canvas 相关入口不会被误认为
+   预览版已支持。
+
+QEMU 可以补充动态链接器和缺库检查，但不能替代上述 GUI、PTY、GPU、音频和
+桌面集成真机测试。当前 Electron 在 QEMU user mode 下可以完成全部共享库
+解析；继续进入 Chromium 多线程初始化后，QEMU 出现 target `SIGSEGV`，因此
+不能用该结果判断真机 Electron 是否可以启动。
+
+## 已知依赖问题
+
+- npm 的 `--cpu=loong64 --os=linux` 仍可能安装宿主 x64 的 Koffi 可选包。
+  打包脚本会删除所有该作用域的已解析原生包，并按 lockfile integrity 手工
+  安装 LoongArch 包。
+- `@napi-rs/canvas` 没有发布 LoongArch 原生包。基础 NAPI-RS 探针通过只说明
+  Rust addon 工具链可用，不代表 Skia/Canvas 已完成移植。
+- Koffi 没有 LoongArch musl binding，因此当前不能满足 GoodBuddy Agent 的
+  双 glibc/musl 产物契约。
+- 预览 Electron 比正式 GoodBuddy 低一个主版本。正式支持必须先获得与当前
+  Electron 基线一致、可重复构建并完成安全维护的 LoongArch shell。

docs/development/release-runbook.md

@@ -0,0 +1,317 @@
+# GoodBuddy Release Runbook
+
+Read this runbook only when preparing, publishing, recovering, or verifying a
+desktop or GoodBuddy Agent release.
+
+This is an operator and CI procedure. It does not authorize adding application
+persistence, snapshots, journals, rollback engines, recovery protocols, or
+compatibility layers to automate release operations. Determine release recovery
+from the authoritative GitHub, OSS, workflow, and Git state, then use the
+smallest existing idempotent rerun or a new immutable version as specified
+below.
+
+## Release Packaging
+
+- Unless the user explicitly requests it, never run a local production build,
+  desktop package, or launch probe as part of release preparation. In
+  particular, do not run `npm run build`, `npm run build:bundle`,
+  `npm run portable`, `npm run release:package`, direct `electron-builder`
+  packaging, or launch a locally packaged app before publishing a release.
+  Local tests, type checks, and lint plus the main-branch and native tag GitHub
+  Actions jobs are the release authorities.
+- After a release is published, confirm only that the expected Windows assets
+  exist in the public release metadata. Do not locally rebuild or launch the
+  Windows package, download or hash published installers, attach browser
+  automation to a packaged app, or perform exhaustive per-asset network probes
+  unless the user explicitly asks for that additional validation.
+- `.github/workflows/packages.yml` is the canonical cross-platform packaging
+  workflow. It validates and builds `out` once, then packages on six native
+  runners: Windows, macOS, and Linux, each for x64 and arm64.
+- The experimental Linux LoongArch (`loong64`) preview is built separately
+  through `build/loongarch-cross` by following
+  `docs/development/loongarch-preview-build.md`. It is not part of
+  `.github/workflows/packages.yml`, the six-runner GitHub Actions matrix,
+  standard release manifests, GitHub Release asset expectations, or the
+  production update index. Do not add it to those paths unless the user
+  explicitly requests a future production-support migration.
+- Run the unified packager with
+  `npm run release:package -- --platform <platform> --arch <arch>`. It only
+  packages for the native host and writes to
+  `dist/release/<platform>-<arch>`.
+- Default deliverables are NSIS and portable ZIP for Windows, DMG for
+  macOS, and AppImage, DEB, and RPM for Linux. Every target includes
+  `release-manifest.json` with SHA-256 hashes.
+- Starting with Desktop 0.12.8, macOS releases contain DMG only. Older macOS
+  GitHub update readers and all older mirror readers require ZIP and cannot
+  validate this new matrix; affected users must upgrade manually from the
+  download page. The user approved this immediate format change. Current
+  readers accept both the historical DMG/ZIP matrix and the DMG-only matrix.
+- Final Desktop package verification compares every bundled OpenCode
+  configuration file with the prepared dependency tree and rejects external
+  DeepSeek imports in the unpacked Host and chunks. Windows x64 CI also
+  imports the packaged OpenCode plugin and starts an isolated packaged
+  UtilityProcess before publishing; source-only tests do not replace it.
+- `build/build-release.cjs` verifies the unpacked application, `app.asar`,
+  bundled Continue and OpenCode runtimes, executable architecture, and package
+  signatures before atomically replacing a release directory.
+- All desktop build paths, including local `portable`, package the Agent and
+  remote Runtime version locks plus the public signing-key registry without
+  embedding installable Linux Agent or remote Runtime payloads. Managed SSH is
+  optional: users explicitly download a compatible compound `.gbagent` package
+  from Settings or import one offline before GoodBuddy can install or update a
+  Host.
+- Each independently published Linux x64, Linux arm64, or macOS arm64 `.gbagent` contains the
+  Agent daemon, pinned Node, and the desktop-maintained compatible OpenCode
+  Runtime. Build all three targets on native GitHub Actions runners from one
+  immutable `agent-v<agentVersion>` tag.
+- Keep the GoodBuddy Agent source, shared protocol/contracts, runtime lock,
+  bundle tooling, and tests in this repository so a desktop commit identifies
+  the exact Agent source it expects. Do not create a separate Agent repository
+  or long-lived Agent release branch unless the Agent becomes an independently
+  released product serving multiple clients.
+- `.github/workflows/agents.yml` is the branch and pull-request build
+  verification workflow for GoodBuddy Agent. It must build Linux x64 and
+  arm64 on native runners from the checked-out commit, acquire the locked
+  official Node archive and locked OpenCode npm archive, verify every locked
+  digest, use only an ephemeral in-memory test signing identity, and verify the
+  resulting compound package and deterministic archive. It must not read
+  production signing secrets, publish installable release artifacts, or modify
+  the checked-in public key registry. The Darwin arm64 target uses `macos-15`
+  and the same production locks. Native CI checks do not replace real Host
+  installation, Attach, Ask/Execute, and lifecycle validation during development.
+- `.github/workflows/agent-release.yml` is the only production compound Agent
+  publication path. It requires an annotated immutable Agent tag, the protected
+  `agent-signing` Environment, native x64/arm64 builds, one production
+  GoodBuddy signing identity for every layer of the compound package and
+  catalog, a non-Latest GitHub Agent Release, and synchronized immutable
+  Beijing OSS objects plus the final signed latest-catalog pointer.
+- `.github/workflows/packages.yml` and `release:package` build only desktop
+  products. Missing Agent packages, remote Runtime inputs, or GoodBuddy signing
+  credentials must never block an ordinary desktop package or release.
+- Keep electron-builder invocations on `--publish never`. Main-branch builds
+  run validation and build the production bundle without running the native
+  package matrix. Manual builds upload 30-day GitHub Actions artifacts.
+  Version-tag builds verify and aggregate packages before publishing GitHub
+  Release assets. The macOS jobs sign, notarize, and verify packages when all
+  five Apple credentials are configured. With no Apple credentials they must
+  use the explicit `--unsigned` path, warn that Gatekeeper may block the
+  packages, and still complete; a partial credential set must fail rather than
+  silently downgrade.
+- Keep `ELECTRON_CACHE` and `ELECTRON_BUILDER_CACHE` under
+  `${{ runner.temp }}` in step-level workflow contexts. A cache beneath the
+  repository inherits the root `"type": "module"` and breaks electron-builder's
+  CommonJS macOS icon tool.
+- Tag builds must use `v${package.version}`. The workflow also supports manual
+  dispatch and main-branch changes to release tooling.
+
+### Agent Release Process
+
+- Agent releases use annotated `agent-v${agent-runtime-lock.agentVersion}` tags
+  and are separate from desktop `v${package.version}` releases. Confirm the
+  exact Agent release commit and tag with the user before creating or pushing
+  either.
+- Store approved bilingual Agent release notes in
+  `resources/agent-release-notes/<agentVersion>.md`. The Agent publication job
+  reads that exact file instead of generating a generic release description;
+  keep it aligned with the approved version and source range.
+- The tagged commit must be reachable from protected `main`. The three native
+  jobs build Linux x64, Linux arm64, and Darwin arm64 packages from the same source and locks;
+  the catalog job rejects missing architectures, changed bytes for an existing
+  version/platform/architecture identity, invalid prior signatures, and incompatible
+  matrix metadata.
+- All three targets share the existing signed `agent-catalog.json`. Before the
+  first mixed-platform catalog is published, release the Desktop reader that
+  accepts Darwin entries and document the required Desktop upgrade. Older
+  Desktop readers reject the entire mixed catalog and cannot check online Agent
+  updates; preserve their locally verified packages and immutable historical
+  releases. Do not introduce a second catalog or silently weaken package
+  signature and integrity verification.
+- Agent GitHub Releases are ordinary non-draft, non-prerelease releases but
+  must use `--latest=false`; they must never replace the desktop release marked
+  Latest. Publish immutable packages and the versioned catalog to
+  `agent-releases/v<agentVersion>/` in Beijing OSS, publish the GitHub Agent
+  Release, then atomically update the single `agent-releases/latest.json`
+  pointer to that version's immutable catalog and signature.
+- Do not report an Agent release complete until both public package
+  architectures match the signed catalog by size and SHA-256, the GitHub and
+  OSS catalog bytes/signatures are identical, the application can read the
+  selected source, and GitHub's repository Latest tag remains the desktop tag.
+
+### Tagged Release Process
+
+Every version-tag release must follow this sequence. A branch-only push does
+not require release notes.
+
+1. Confirm that the user wants a release tag and identify the exact release
+   commit and the new `package.json` version. Separately ask whether this
+   release should also receive an experimental LoongArch preview build; never
+   infer that choice from an earlier release.
+2. Find the latest stable version tag reachable before the release commit and
+   inspect the complete commit and file diff from that tag to the release
+   commit. For the first tagged release, inspect the relevant repository
+   history instead.
+3. Draft concise, user-facing release notes in both Simplified Chinese and
+   English based only on verified changes in that range. Use the titles
+   `GoodBuddy <version> 更新内容` and
+   `What's New in GoodBuddy <version>`, with corresponding `功能更新` /
+   `Features` and `问题修复` / `Bug Fixes` sections when applicable. The two
+   language versions must describe the same changes. Do not expose
+   internal-only details, credentials, private content, or unverified claims.
+4. Show the exact bilingual release-note draft to the user and wait for
+   explicit approval. If the release commit or either language version changes
+   after approval, inspect the updated tag range and request approval again.
+5. Write the approved notes to the single entry for the release version in
+   `resources/release-notes.json`. A failed unpublished candidate whose content
+   is carried forward must not retain a duplicate packaged entry.
+6. Verify that `package.json`, the root `package-lock.json` version, and
+   `package-lock.json.packages[""].version` all equal the release version. Run
+   `npm run release:notes:verify`, `npm test`, `npm run typecheck`, and
+   `npm run lint`. Do not run a local production build, packaging command, or
+   packaged-app launch probe unless the user explicitly requests one.
+   If the user requested a LoongArch preview in step 1, build it separately
+   from this exact candidate by following the LoongArch build document, record
+   its size and SHA-256, and keep it outside the standard GitHub/OSS release
+   asset set unless the user separately authorizes publishing it.
+7. Commit the approved candidate and confirm the exact release commit with the
+   user. Fetch both remotes, inspect branch movement instead of overwriting or
+   silently merging it, then push that commit to `main` on `origin` and
+   `github`. Require the candidate commit's main-branch GitHub Actions source
+   validation and production build to succeed before tagging.
+8. Fetch both remotes again immediately before tagging. Confirm the working
+   tree is clean, both remote `main` refs still equal the approved commit, the
+   candidate tag is unused locally and remotely, and the exact approved commit
+   has not changed. Only then create the annotated `v${package.version}` tag at
+   that commit, push the tag to both remotes, and verify each peeled tag SHA
+   (`refs/tags/<tag>^{}`) equals the release commit.
+9. Keep both approved language versions as the single source for the GitHub
+   Release body and the packaged first-open release-notes modal. The modal
+   displays the release notes matching the current interface language and
+   contains no button linking to a full release page.
+10. Observe the tag workflow through publication and complete the public
+    verification checklist below. A successful push is not a completed
+    release.
+
+### OSS Publication Contract
+
+The tagged release job publishes through the GitHub Environment selected by
+`.github/workflows/packages.yml` (`aliyun-oss-release`) and reads the following
+effective GitHub Actions variables. Before a release or same-tag rerun can
+publish, verify that repository-, organization-, or environment-level
+resolution exposes:
+
+- `ALIYUN_OSS_BUCKET=goodbuddy`
+- `ALIYUN_OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com`
+- a non-empty `ALIYUN_OIDC_PROVIDER_ARN` matching
+  `acs:ram::*:oidc-provider/*`
+- a non-empty `ALIYUN_ROLE_ARN` matching `acs:ram::*:role/*`
+
+For environment-scoped values, use the exact Environment name from the
+workflow; do not assume a similarly named UI environment such as `Production`
+contains the active variables.
+
+The Bucket and Endpoint are a deployment contract, not interchangeable
+examples. They must stay aligned with the trusted URL checks in
+`src/main/version-checker.ts`, `sites/app.js`, website validation, and related
+tests. A host, Bucket, Region, or CDN migration must update and validate every
+surface together before a new release.
+
+- Use GitHub OIDC and the RAM Role to obtain short-lived STS credentials.
+  Never add long-lived AccessKeys to repository or environment secrets.
+- Keep `ossutil` pinned. Its V4 signing requires the Region; derive it from the
+  canonical Endpoint, verify that the production value resolves to
+  `cn-beijing`, and pass `--region` to every `ossutil cp`, including the final
+  `latest.json` update.
+- Grant the RAM Role only the actions and prefixes required by the workflow.
+  It must be able to write immutable version objects and the final latest
+  pointer without granting unrelated administration privileges.
+- Upload release assets and `site-release.json` under the immutable
+  `releases/<tag>/` prefix first. Verify all 12 installer URLs publicly before
+  creating or publishing the GitHub Release. Update
+  `releases/latest.json` only after the GitHub Release is public and all prior
+  checks succeeded.
+- The expected GitHub Release contains 20 assets: 12 installers (two formats
+  for each Windows target, DMG for each macOS target, and three formats for each Linux target), six
+  renamed target manifests, one aggregate `release-manifest.json`, and one `SHA256SUMS`.
+  `site-release.json` is an OSS publication artifact, not a GitHub Release
+  asset.
+
+### Failed Tag Recovery
+
+Classify a failed tag by the external side effects that completed before
+choosing a recovery:
+
+- If no source or release metadata must change, correct only the external
+  configuration and use **Re-run failed jobs** for the same immutable tag. Do
+  not change, move, delete, or recreate the tag.
+- If immutable OSS objects were partially uploaded but their source bytes are
+  unchanged, a same-tag rerun may idempotently re-upload or verify them. Never
+  point `latest.json` at a partially verified prefix.
+- If the GitHub Release is already public but the final latest-pointer step
+  failed, it is a published version. Keep its packaged notes and rerun the
+  failed release job for the same tag; do not classify it as an unpublished
+  candidate.
+- If code or release metadata must change, keep the failed tag immutable,
+  increment the patch version, obtain approval for the revised exact release
+  commit and notes, and create a new tag. Do not reuse the failed version.
+
+When recovering from a version tag whose workflow never published a public
+GitHub Release:
+
+- If a code or metadata change requires a higher version and a new tag, carry
+  the failed candidate's approved user-facing notes forward into the recovery
+  version, then remove the superseded failed version's entry from
+  `resources/release-notes.json`.
+- The packaged first-open modal must show that carried-forward content only
+  once under the recovery version. Never retain both the failed version and
+  its cumulative recovery copy, because users upgrading across them would see
+  duplicate content.
+- Never remove the packaged history for a version that successfully published
+  a GitHub Release. Verify the failed release state before treating an entry as
+  superseded.
+
+### Post-Publication Verification
+
+Do not report a release complete until all of the following are verified:
+
+1. The tag workflow and all six native package jobs succeeded. Verify the
+   recorded macOS signing mode: signed builds must pass `codesign`, `spctl`,
+   and `stapler`; unsigned builds must record the Gatekeeper caveat in the
+   Actions log and job summary. In the final release job, explicitly verify
+   the OSS configuration, OIDC authentication, release-index generation,
+   immutable upload, public asset check, GitHub Release publication, and
+   latest-pointer steps.
+2. The public GitHub Release is non-draft, non-prerelease, marked Latest, and
+   uses the expected tag and title. Its body must exactly match the Markdown
+   generated from the approved packaged bilingual notes.
+3. GitHub release metadata contains exactly the expected 20 uploaded asset
+   names, including the expected Windows x64 and arm64 assets. Do not download,
+   hash, launch, or send individual network probes to published installers
+   unless the user explicitly requests that additional validation.
+4. The Beijing `releases/latest.json` returns HTTP 200, has the expected stable
+   version, exact six targets and 12 installer entries, the trusted Beijing
+   URLs, and the GitHub fallback URL. It must match the immutable
+   `releases/<tag>/site-release.json`. Fetching and comparing these small JSON
+   metadata files is sufficient; rely on the successful publication job for
+   its per-asset public checks.
+5. The live website successfully fetches the index and produces the 12 correct
+   platform/architecture/format links from that metadata.
+6. Both remote `main` refs and both peeled tag refs still equal the approved
+   release commit, and the local working tree is clean.
+
+Never create or push a release tag, and never push a previously created
+release tag, before the release-note draft has received explicit approval.
+
+- Before a push that updates the `github` remote, ask whether the user wants a
+  release tag unless they already specified that choice. A branch-only push
+  does not require a version bump or tag. When the user requests a release,
+  verify that `package.json` and `package-lock.json` contain the same release
+  version, create `v${package.version}` at the exact commit being pushed, and
+  push that tag so the native package matrix and GitHub Release run.
+- Never move or reuse an existing release tag. If `v${package.version}` already
+  exists locally or on a remote at another commit, increment the package
+  version and create a new matching tag before the release push.
+- Verified release baseline on 2026-08-18: commit
+  `60119a4317118fa3f077db0382664f15266a6682`, annotated tag `v0.10.4`, and
+  GitHub Actions run `32038633609` attempt 2 succeeded through all six native
+  packages, GitHub Release publication, Beijing OSS publication, and the final
+  `latest.json` switch.

docs/features/AGENTS.md

@@ -0,0 +1,135 @@
+# GoodBuddy Feature Documentation Guide
+
+## Scope
+
+These instructions apply to all files under `docs/features/`.
+
+Each direct child directory represents one user-visible product feature or one coherent feature family. Organize documentation by feature ownership first, then by document responsibility.
+
+## Standard Structure
+
+Use the smallest applicable subset:
+
+```text
+docs/features/<feature-name>/
+  README.md
+  prd.md
+  user-stories.md
+  logic-design.md
+  ui-design.md
+  technical-design.md
+  progress.md
+```
+
+Additional documents are allowed when one standard file would mix independent responsibilities. List every additional document and its unique responsibility in the feature `README.md`.
+
+Do not create empty placeholders. If a standard document is not needed yet, omit it and state the missing responsibility in `README.md` only when that absence matters to current work.
+
+## Document Responsibilities
+
+### `README.md`
+
+- The sole entry point for the feature.
+- Summarizes feature purpose and boundary.
+- Lists all feature documents and their authoritative responsibilities.
+- Defines feature-specific terminology.
+- Points to cross-feature dependencies without copying them.
+
+### `prd.md`
+
+- Defines the user problem, goals, scope, non-goals, functional requirements, and product acceptance.
+- Describes what the product must do, not module layout or implementation mechanics.
+- Records explicit limitations when a workflow is intentionally unsupported.
+
+### `user-stories.md`
+
+- Defines user roles, scenarios, and Given/When/Then-style acceptance.
+- Covers first use, normal use, failure recovery, compatibility, permissions, and boundary cases relevant to real users.
+- Keeps implementation details out unless the detail is itself an observable contract.
+
+### `logic-design.md`
+
+- Defines invariants, state dimensions, state transitions, decision tables, priority rules, failure outcomes, and cross-story consistency.
+- Resolves overlap between PRD requirements and User Stories before technical implementation.
+- Includes a logic completeness assessment and identifies unresolved product decisions separately from technical selection work.
+
+### `ui-design.md`
+
+- Defines feature information architecture, shared component usage, states, copy, feedback, keyboard behavior, accessibility, and responsive behavior.
+- Must follow the repository root `UI-DESIGN.md`.
+- Does not create feature-local visual systems when shared tokens and primitives already exist.
+
+### `technical-design.md`
+
+- Defines process and module boundaries, shared contracts, persistence, IPC, lifecycle, packaging, compatibility, validation, and implementation order.
+- Implements the PRD and logic design rather than redefining their behavior.
+- Follows KISS and YAGNI. Do not add recovery or compatibility machinery without a demonstrated requirement.
+
+### `progress.md`
+
+- Records only verified implementation facts, remaining work, blockers, validation commands, and dated evidence.
+- Never marks an item complete based only on a design, mock, schema, or injected fake when the production path remains incomplete.
+- Does not duplicate future design. Link back to the authoritative document.
+
+## Traceability
+
+For non-trivial features:
+
+1. PRD requirements use stable IDs such as `FR-1`.
+2. User Stories use stable IDs such as `US-A1`.
+3. Logic design maps rules and state transitions to PRD and User Story IDs.
+4. UI and technical design link to the PRD and logic design.
+5. Progress items map to implementation stages and record actual validation.
+
+Do not renumber stable IDs merely for presentation after implementation begins.
+
+## Source of Truth
+
+- PRD owns product scope and requirements.
+- User Stories own user scenarios and scenario acceptance.
+- Logic design owns behavioral decisions and state rules.
+- Root `UI-DESIGN.md` owns global UI consistency; feature UI design owns feature-specific application.
+- Technical design owns implementation architecture.
+- Progress owns current implementation and validation status.
+- Final code and validated runtime behavior override stale documentation. Correct all affected documents when they diverge.
+
+## Feature Boundaries
+
+- Keep a document in a feature directory when one feature can own its behavior and acceptance.
+- Keep a document in `docs/architecture`, `docs/quality`, `docs/development`, or `docs/roadmap` only when it truly governs multiple features and has no single feature owner.
+- Reference cross-feature documents rather than copying their definitions.
+- When two features share a global domain model, keep that model in the feature family that owns the domain or in cross-feature architecture if ownership is genuinely global.
+
+## Managed External Artifacts
+
+When a feature downloads external artifacts managed by GoodBuddy:
+
+- Define the exact setting that selects the source and the setting scope.
+- Use immutable artifact targets with expected byte size and SHA-256.
+- Freeze the selected source when an operation starts.
+- Fail explicitly when the selected source is unavailable or invalid. Never silently request another source.
+- Keep download URLs and redirect allowlists out of Renderer-controlled input.
+- State whether the setting affects models, application updates, Agent packages, managed tool runtimes, package-manager registries, or user-configured URLs. Do not imply a broader scope than implemented.
+- When two targets are presented as an upstream/original address and its OSS mirror, require byte-identical content with one shared size and SHA-256. A mirror must not rebuild, recompress, or modify the upstream artifact.
+
+## Migration Rules
+
+When moving existing documentation:
+
+1. Preserve content and Git history where practical.
+2. Update every repository link to the new path.
+3. Add or update the destination feature `README.md`.
+4. Delete the old authoritative path; do not leave a duplicate compatibility copy.
+5. Do not rewrite unrelated document content merely because the file moved.
+6. Preserve uncommitted user edits while moving files.
+7. Verify all relative Markdown links after migration.
+
+## Review Checklist
+
+- The feature has one clear entry point.
+- Every document has one declared responsibility.
+- Product requirements, stories, logic, UI, technical design, and progress do not contradict each other.
+- Normal, failure, cancellation, compatibility, permission, and scope behavior are covered where applicable.
+- UI behavior follows `UI-DESIGN.md`.
+- Progress claims are backed by dated evidence.
+- All relative links resolve.

docs/features/application-tool-navigation/README.md

@@ -0,0 +1,34 @@
+# 应用导航与系统工具入口
+
+本功能整理 GoodBuddy 主侧栏的入口层级：系统入口保持固定，应用占用主导航，系统工具从
+侧栏底部快捷打开助手工作栏。该功能同时为后续插件应用和插件工具预留统一的入口类型，但
+不包含插件市场的安装与运行机制。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、产品边界、功能要求与产品验收 |
+| [User Stories](./user-stories.md) | 用户场景及 Given/When/Then 验收 |
+| [功能逻辑设计](./logic-design.md) | 分类规则、入口状态、优先级与失败结果 |
+| [UI 设计](./ui-design.md) | 侧栏信息架构、控件、文案、键盘和响应式行为 |
+| [技术设计](./technical-design.md) | 现有模块映射、状态契约、持久化和实施顺序 |
+
+## 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| 系统入口 | GoodBuddy 工作流程或审计所必需的固定入口，用户不能卸载、隐藏或改变类型 |
+| 应用 | 在主内容区打开完整一级页面的功能，可显示在“当前对话”所在的主导航区 |
+| 系统工具 | GoodBuddy 自带且不可卸载的辅助能力，包括文件、终端、浏览器和资源监控，从侧栏底部打开助手工作栏中的对应面板 |
+| 插件应用 | 未来由插件提供的一级页面入口 |
+| 插件工具 | 未来由插件提供的辅助面板或命令入口 |
+| 快捷入口 | 只负责打开或聚焦能力，不复制该能力的界面和业务状态 |
+
+## 相关文档
+
+- [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md)
+- [通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)
+- [助手工作栏多终端页签 PRD](../assistant-workbar/terminal-tabs-prd.md)
+- [智能心跳 PRD](../smart-heartbeat/prd.md)
+- [知识库功能文档](../knowledge-base/README.md)

docs/features/application-tool-navigation/logic-design.md

@@ -0,0 +1,168 @@
+# 应用导航与系统工具入口功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 关联 User Stories | [User Stories](./user-stories.md) |
+
+## 1. 不变量
+
+1. “当前对话”“运行记录”和“设置”始终是系统入口。
+2. 运行记录不进入工具注册表、应用显隐设置或插件市场。
+3. 文件浏览器、终端、浏览器和资源监控始终是系统工具，不能卸载或被插件替换。
+4. 左下角只提供快捷入口，工具内容仍由助手工作栏承载。
+5. 隐藏应用不等于停用功能，也不删除、迁移或清理业务数据。
+6. 快捷入口不能扩大执行空间、文件、PTY、网络或浏览器权限。
+
+## 2. 入口模型
+
+```ts
+type NavigationContribution =
+  | {
+      type: 'system-entry'
+      id: 'chat' | 'activity' | 'settings'
+      placement: 'primary-start' | 'primary-end' | 'footer'
+    }
+  | {
+      type: 'application'
+      id: 'magic-notes' | 'knowledge' | 'heartbeat'
+      source: 'builtin'
+      visible: boolean
+    }
+  | {
+      type: 'system-tool'
+      id: 'workspace' | 'terminal' | 'browser' | 'resources'
+      workbarAppId: 'workspace' | 'terminal' | 'browser' | 'resources'
+    }
+```
+
+该模型只覆盖首期入口。插件贡献模型随插件 Host、权限和生命周期另行设计。
+
+## 3. 主导航组合规则
+
+主导航按以下顺序计算：
+
+```text
+当前对话
+可见的内置应用
+运行记录
+```
+
+当前对话和运行记录不参与排序。首期内置应用默认顺序为魔法笔记、知识库、智能心跳；显隐
+设置只从中移除对应项，不改变固定入口的位置。
+
+### 3.1 应用可见性与业务状态
+
+| 导航可见 | 功能启用 | 结果 |
+| --- | --- | --- |
+| 是 | 是 | 显示入口并允许进入 |
+| 否 | 是 | 隐藏入口，后台和数据保持原状 |
+| 是 | 否 | 不显示不可用入口；设置页保留启用路径 |
+| 否 | 否 | 不显示入口，保留符合该功能自身规则的数据 |
+
+“功能启用”由各应用现有产品设置负责。例如魔法笔记启停仍使用原设置；导航偏好不能覆盖它。
+
+## 4. 系统工具打开规则
+
+### 4.1 通用流程
+
+```text
+用户激活工具按钮
+  -> 校验按钮仍可用
+  -> 向助手工作栏发送打开意图
+  -> 工作栏按应用实例策略查找或创建实例
+  -> 展开工作栏
+  -> 激活目标实例
+  -> 把焦点移入面板标题或首个主要控件
+```
+
+若创建失败，工作栏保持展开并在对应能力位置显示错误；主页面和其他工作栏实例不被清空。
+
+### 4.2 决策表
+
+| 工具 | 匹配实例存在 | 匹配实例不存在 | 上下文不可用 |
+| --- | --- | --- | --- |
+| 文件 | 激活不可关闭的单实例并保留其跟随或固定状态 | 仅在迁移或布局修复时补回 `workspace` | 打开面板并显示目录修复入口 |
+| 终端 | 激活当前执行空间最近的 `starting` 或 `running` 实例 | 创建一个绑定当前执行空间的实例 | 没有项目时使用本机 Home |
+| 浏览器 | 激活绑定当前 Conversation 的最近使用实例 | 创建绑定当前 Conversation 的新实例 | 激活最近使用实例；不存在时创建待绑定实例 |
+| 资源监控 | 激活 `resources` 单实例 | 创建本机 `resources` 单实例 | 部分指标不可用时显示原因并保留其余指标 |
+
+文件保持单一实例原有绑定。浏览器快捷入口按当前 Conversation 匹配最近使用实例，而工作栏
+“+”始终新建浏览器实例。固定目标失效时显示该目标的修复状态，不回退到当前项目、默认
+工作区或当前会话。
+
+`closing`、`exited`、`interrupted` 和 `failed` 终端不属于可复用实例。当前执行空间只有这些
+终端时，快捷按钮创建新实例并保留原 Tab 的历史状态。用户需要额外的并行终端时使用工作栏
+“+”或终端面板中的既有创建命令。
+
+### 4.3 选中与状态
+
+工具按钮满足以下条件时显示选中：助手工作栏已展开，且当前活动实例的 `appId` 与工具映射
+一致。只有实例存在但未激活时不显示选中。
+
+徽标优先级为：等待用户处理 > 错误 > 运行中 > 无徽标。同一按钮只显示一个视觉徽标，
+可访问名称包含完整状态。
+
+资源监控首期不在后台采样，因此不显示负载告警徽标。只有资源面板是工作栏当前活动实例且
+工作栏已展开时，资源按钮才显示选中状态。
+
+### 4.4 资源采样状态
+
+```text
+inactive -> warming -> loading -> live
+                              -> partial
+                              -> error
+live/partial/error -> loading
+warming/loading/live/partial/error -> inactive
+```
+
+- `inactive`：资源面板未处于可见活动状态，没有采样定时器。
+- `warming`：首次进入或停止后恢复，建立 CPU 和磁盘 IO 区间基线；内存仍可立即显示。
+- `loading`：正在请求后续样本；请求未结束时跳过后续时钟触发。
+- `live`：所有首期指标可用，按 2 秒间隔追加样本。
+- `partial`：至少一个指标可用；不可用项携带稳定错误码，其他指标继续更新。
+- `error`：本次没有任何可用指标，保留已有历史；自动时钟或手动操作可以重试。
+
+资源面板为活动实例、工作栏展开且 `document.visibilityState` 为 `visible` 时才离开 `inactive`。
+任一条件失效即停止定时器并重置区间基线。历史队列只保留最后 150 个样本；时间间隔较长或
+采样失败时保留真实时间缺口，不补零或伪造中间数据。
+
+## 5. 设置保存规则
+
+应用导航偏好与应用业务启停分开保存。Switch 每次切换立即提交完整目标集合；请求完成前禁用
+三个应用显隐 Switch，下一次操作基于最新确认结果提交，防止并发更新互相覆盖。
+
+保存失败时：
+
+- 主导航和 Switch 恢复最后一次成功保存的偏好。
+- 设置行显示可重试错误。
+- 不回滚或修改各应用的业务状态。
+
+## 6. 与需求的对应关系
+
+| 逻辑 | PRD | User Stories |
+| --- | --- | --- |
+| 固定入口不变量 | FR-1、FR-2 | US-A1、US-A2 |
+| 应用显隐和失败恢复 | FR-3、FR-4、FR-11、FR-12 | US-B1、US-B2、US-B4、US-B5 |
+| 工具打开决策表 | FR-5 至 FR-10 | US-C1 至 US-C7 |
+| 资源采样状态 | FR-9 | US-C6 |
+| 无障碍与窄窗口 | FR-13 | US-D1、US-D2 |
+
+## 7. 逻辑完整性评估
+
+首期规则已覆盖固定入口、应用显隐、保存失败、系统工具匹配与显式多实例差异、本机 Home、
+托管 SSH、无活动会话、目录失效、资源部分可用、采样停止、权限边界、键盘和窄窗口。其他
+工具面板内部的取消、超时、
+连接恢复和固定目标失效继续由助手工作栏负责，本功能不复制这些状态机。
+
+## 8. 后续产品决策
+
+- 插件工具上线后，快捷栏允许固定的最大数量及溢出规则。
+- 插件应用是否允许用户排序，以及固定系统入口之间允许的排序范围。
+
+这些决策不影响首期四个系统工具的固定入口和内置应用显隐实现。

docs/features/application-tool-navigation/prd.md

@@ -0,0 +1,177 @@
+# 应用导航与系统工具入口 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 关联设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[助手工作栏 PRD](../assistant-workbar/prd.md) |
+
+## 1. 背景
+
+主侧栏当前把“当前对话”“魔法笔记”“知识库”“智能心跳”和“运行记录”放在同一导航组，
+底部长期显示“GB 本地工作区”和平台架构。底部信息不能反映用户可以执行的操作，文件、终端
+和浏览器则需要先找到右侧助手工作栏后才能打开。
+
+后续插件可能提供完整页面，也可能只提供辅助面板或命令。若不先区分系统入口、应用和工具，
+插件接入后会同时争用主导航、侧栏底部和助手工作栏，用户也无法判断入口会切换页面还是打开
+辅助面板。
+
+## 2. 产品定义
+
+### 2.1 三类入口
+
+| 类型 | 首期成员 | 默认位置 | 用户控制范围 |
+| --- | --- | --- | --- |
+| 系统入口 | 当前对话、运行记录、设置 | 主导航固定位置或侧栏底部 | 不可隐藏、卸载或改变类型 |
+| 应用 | 魔法笔记、知识库、智能心跳 | 主导航应用区 | 可控制是否显示；隐藏不删除数据 |
+| 系统工具 | 文件浏览器、终端、浏览器、资源监控 | 侧栏底部快捷工具栏 | 首期固定提供，不可卸载 |
+
+运行记录是系统审计页面，不属于工具。文件浏览器、终端、浏览器和资源监控是系统工具；它们
+的快捷入口位于左下角，实际界面继续由右侧助手工作栏承载。
+
+### 2.2 后续插件类型
+
+插件市场开放后，插件可以贡献“插件应用”或“插件工具”。插件不能注册、覆盖或替换系统入口，
+也不能冒充系统工具。内置应用继续标记为“内置”，不因采用统一注册协议而显示成待安装商品。
+
+## 3. 目标
+
+- 用户从侧栏底部一次点击即可打开文件、终端、浏览器或资源监控。
+- 主导航只承载完整页面，辅助工具不占用一级页面位置。
+- 运行记录始终可发现，不受应用显示设置和插件状态影响。
+- 内置应用可以从一个设置位置控制主导航可见性，隐藏后仍可恢复。
+- 为插件应用和插件工具保留明确的入口契约，不提前建设插件安装能力。
+
+## 4. 非目标
+
+- 首期不提供第三方插件搜索、下载、安装、更新、签名验证或卸载。
+- 不把文件树、终端或浏览器重新实现到左侧栏。
+- 不改变助手工作栏的面板实例、停靠、执行空间和安全边界。
+- 不允许隐藏运行记录、当前对话或设置。
+- 不因隐藏应用而删除魔法笔记、知识库或智能心跳数据。
+- 不把“显示在侧边栏”解释为停止智能心跳计划或后台任务。
+- 不提供任意本机程序启动器。
+- 首期资源监控不采集远程主机、GPU、显存或网络吞吐，不提供后台告警和历史持久化。
+
+## 5. 功能要求
+
+### FR-1 入口分类
+
+系统必须为每个可见入口声明稳定类型：`system-entry`、`application` 或 `system-tool`。界面位置、
+设置项和点击结果均以该类型为准，不根据当前页面临时改变类型。
+
+### FR-2 固定系统入口
+
+“当前对话”固定在主导航首位；“运行记录”固定在应用区之后；“设置”固定在侧栏底部。
+这些入口不出现在应用显隐、工具固定或插件管理设置中。
+
+### FR-3 内置应用区
+
+魔法笔记、知识库和智能心跳显示在当前对话与运行记录之间。应用入口打开对应一级页面，保留
+现有徽标、范围和页面状态。用户可以在设置中控制其主导航可见性。
+
+### FR-4 隐藏应用
+
+隐藏应用只移除主导航入口，不删除数据、不修改业务启停状态，也不终止正在进行的操作。显隐
+Switch 更新成功后主导航立即生效；更新失败时恢复原状态并允许重试。用户可从设置恢复入口。
+
+### FR-5 系统工具快捷栏
+
+侧栏底部提供文件浏览器、终端、浏览器和资源监控四个图标按钮，并保留独立设置按钮。每个
+按钮具有可见工具提示和可访问名称。首期系统工具顺序固定为文件、终端、浏览器、资源监控。
+
+### FR-6 文件浏览器入口
+
+点击文件按钮时展开助手工作栏，并聚焦默认存在且不可关闭的“工作区”单实例。该实例保持
+“跟随当前上下文”或“固定到指定对象”状态；迁移或布局修复发现实例缺失时补回，并默认跟随
+当前项目。没有项目时使用已配置的默认工作区。跟随上下文所需的路径不可用时，面板显示修复
+入口；已有有效固定目标不受当前项目和默认工作区状态影响。
+
+### FR-7 终端入口
+
+点击终端按钮时展开助手工作栏。当前执行空间有正在启动或运行中的终端时聚焦最近使用的实例；
+没有时创建一个绑定当前执行空间的新终端，已退出、已中断或失败的历史 Tab 保持不变。没有
+项目时当前执行空间为本机 Home。创建额外并行终端继续使用工作栏现有的“+”目录入口。
+
+### FR-8 浏览器入口
+
+点击浏览器按钮时展开助手工作栏，并优先聚焦绑定当前 Conversation 的最近使用浏览器实例；
+没有匹配实例时创建一个。没有活动 Conversation 时聚焦最近使用的浏览器实例；完全不存在时
+创建待绑定空实例。该快捷入口不会因连续点击创建重复实例；用户通过工作栏“+”选择浏览器时
+则始终创建新实例。入口不打开系统默认浏览器，也不创建旁路 WebView。
+
+### FR-9 资源监控入口
+
+点击资源监控按钮时展开助手工作栏，并打开或聚焦单实例的本机“资源监控”面板。面板显示
+整机 CPU 使用率、内存使用量与总量、磁盘读写速率，以及 GoodBuddy 桌面进程的 CPU、内存
+和进程数摘要。指标不可用时显示具体项目和原因，不能显示为 `0`。
+
+资源面板处于可见活动状态、工作栏已展开且应用窗口未隐藏或最小化时，每 2 秒采样一次，在
+Renderer 内存中最多保留最近 5 分钟。任一条件不满足时停止采样；首期不在后台持续监控，
+也不据此产生侧栏告警。首次采样及停止后恢复的首次采样只建立 CPU 和磁盘 IO 速率基线，
+不显示伪造的 `0` 值。
+
+### FR-10 快捷入口状态
+
+工具面板已激活时，对应按钮显示选中状态；面板存在但未激活时保持普通状态。运行中、错误或
+等待用户处理可以显示徽标，但必须有可访问文字，且不得自动抢占当前面板。
+
+### FR-11 应用导航设置
+
+设置页提供“应用与工具”管理入口。首期“应用”区域列出三个内置应用并提供“显示在侧边栏”
+Switch，切换后立即持久化。系统工具区域列出四项内置固定能力，不提供虚假的卸载或停用按钮。
+
+### FR-12 偏好持久化
+
+应用可见性按设备持久化。升级时保留当前行为：已有可用内置应用继续显示；魔法笔记原有功能
+启停设置保持原意，不由新的导航可见性覆盖。
+
+### FR-13 窄窗口行为
+
+窄窗口下主侧栏仍按现有抽屉方式显示。系统工具按钮保持单行且不与设置按钮重叠；空间不足时
+收起文字和非必要分隔，不隐藏四个系统工具或设置。
+
+## 6. 权限与安全
+
+- 快捷入口不授予新的文件、命令、网络或浏览器权限。
+- 系统工具继续使用 Main、Preload、执行空间 Grant、Ask/Execute 和现有审批边界。
+- Renderer 不因新增入口获得任意文件系统、PTY、进程或 Electron API。
+- 资源指标由 Main 采集并以有界结构返回；Renderer 不接收进程命令行、环境变量或任意 PID。
+- 资源样本只保存在当前 Renderer 内存中，不写入运行记录、SQLite 或遥测服务。
+- 插件贡献类型只是界面与导航声明，不能代替权限清单、用户授权和运行隔离。
+- 运行记录继续记录由系统工具触发的受审计操作。
+
+## 7. 产品验收
+
+- 主导航能明确区分固定系统入口和可配置内置应用。
+- 运行记录在所有应用显隐组合下保持可见并可打开。
+- 左下角不再用“本地工作区”与系统架构占据主要空间。
+- 文件、终端、浏览器和资源监控均可从左下角打开正确的工作栏面板，且不产生第二套内容界面。
+- 连续点击系统工具不会无意创建重复的浏览器或终端实例；工作区始终复用不可关闭的固定实例。
+  用户通过工作栏“+”可以显式创建额外浏览器或终端实例。
+- 资源监控以 2 秒间隔更新，保留不超过 150 个样本；面板不活动、工作栏收起或窗口隐藏、
+  最小化后停止请求新样本。
+- CPU、内存、磁盘 IO 或 GoodBuddy 指标不可用时，页面区分部分可用与整体失败。
+- 隐藏内置应用不删除数据、不停止后台计划，并能从设置恢复；保存失败时入口保持原状。
+- 键盘、屏幕阅读器、浅色主题、深色主题和窄窗口均可完成相同操作。
+
+## 8. 分期
+
+### 首期
+
+- 重构侧栏底部，增加四个系统工具按钮和独立设置按钮。
+- 建立从 App 到助手工作栏的“打开或聚焦工具”意图接口。
+- 增加本机资源快照采集与资源监控单实例面板。
+- 增加内置应用的主导航显示设置。
+- 保持运行记录为固定系统入口。
+
+### 后续
+
+- 插件应用和插件工具注册。
+- 插件工具固定、取消固定和排序。
+- 插件市场、权限详情、安装和卸载。
+- 用户级快捷键与命令面板接入同一贡献命令。

docs/features/application-tool-navigation/technical-design.md

@@ -0,0 +1,383 @@
+# 应用导航与系统工具入口技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| UI 设计 | [UI 设计](./ui-design.md) |
+
+## 1. 现状
+
+主页面没有 URL Router，由 `App.tsx` 中的 `WorkspaceView` 和 keep-alive 状态切换：
+
+```ts
+type WorkspaceView =
+  | 'chat'
+  | 'magic-notes'
+  | 'knowledge'
+  | 'heartbeat'
+  | 'activity'
+  | 'settings'
+```
+
+文件、浏览器和终端已经由 `RightAssistantSidebar`、`WorkbarShell` 与 `workbar-contracts.ts`
+承载。工作区是不可关闭的单实例应用，浏览器和终端是多实例应用。浏览器多实例的跨进程
+实现以[浏览器多实例技术设计](../assistant-workbar/browser-tabs-technical-design.md)为准。代码中尚无资源指标采集和资源监控
+面板。现有侧栏底部 `user-card` 整行打开设置，并显示“本地工作区”和平台架构。
+
+本次改动增加入口编排、从主侧栏到工作栏的命令通道，以及本机资源监控的 Main/Preload/
+Renderer 最小实现。文件、终端和浏览器后端保持不变。
+
+## 2. 模块边界
+
+| 模块 | 责任 |
+| --- | --- |
+| `App.tsx` | 组合主导航、系统工具栏、设置入口和页面离开检查 |
+| `SidebarSystemTools`（新增） | 渲染四个系统工具按钮并发送打开意图 |
+| `RightAssistantSidebar.tsx` | 接收打开意图，调用工作栏实例创建或激活逻辑 |
+| `WorkbarShell.tsx` | 继续负责实例策略、Tab、目录和焦点行为 |
+| `workbar-contracts.ts` | 继续作为工作栏应用 ID 和实例布局的权威契约 |
+| `resource-monitor-contracts.ts`（新增） | 定义本机资源快照、可用性和错误码 |
+| `resource-monitor-service.ts`（新增） | 在 Main 中采集并规范化本机与 GoodBuddy 指标 |
+| `ResourceMonitorPanel.tsx`（新增） | 按需轮询、保留有界历史并渲染资源面板 |
+| `application-settings-contracts.ts` | 增加应用导航偏好 schema 和默认值 |
+| `application-settings-store.ts` | 迁移并原子保存应用导航偏好 |
+| `PlatformFeaturesSettingsSection` 或独立设置 Section | 编辑“显示在侧边栏”偏好 |
+
+不要在 `SidebarSystemTools` 中读取文件、创建 PTY、操作浏览器或采集系统指标；该组件只发送
+有界的工具 ID。
+
+## 3. Renderer 契约
+
+### 3.1 系统工具 ID
+
+```ts
+export const sidebarSystemToolIds = [
+  'workspace',
+  'terminal',
+  'browser',
+  'resources'
+] as const
+
+export type SidebarSystemToolId = (typeof sidebarSystemToolIds)[number]
+```
+
+该类型可以放在 Renderer 内共享模块。首期不暴露 IPC，因为动作只编排已有工作栏 Renderer
+状态；实际能力调用继续走现有 Preload API。
+
+### 3.2 打开意图
+
+`App` 向 `RightAssistantSidebar` 传入单调递增的请求或命令对象：
+
+```ts
+type WorkbarOpenIntent = {
+  requestId: number
+  appId: 'workspace' | 'terminal' | 'browser' | 'resources'
+  reason: 'sidebar-system-tool'
+  context?: { conversationId?: string; projectId?: string }
+}
+```
+
+`requestId` 使连续点击同一工具仍能被消费。不要仅设置 `assistantSidebarTab`，因为用户可能已
+关闭对应实例，且终端需要按执行空间寻找实例。
+
+建议由 `RightAssistantSidebar` 在消费意图后通过现有 `WorkbarShell` 控制接口完成。控制器必须
+接收上下文和调用原因，不能只按 `appId` 查找第一个实例：
+
+```ts
+type WorkbarController = {
+  openOrActivate(intent: WorkbarOpenIntent): Promise<WorkbarTabInstance>
+}
+```
+
+若当前 `WorkbarShell` 没有命令式入口，先增加窄的回调或受控请求 Props，不引入全局事件总线。
+
+工作区意图始终激活注册表中的不可关闭单实例；仅在迁移或布局损坏时补回。浏览器意图按
+`conversationId` 激活最近使用的匹配实例，没有匹配实例时创建一个。工作栏“+”不走该去重
+路径，选择浏览器时始终创建新实例。
+
+### 3.3 终端匹配
+
+工作栏“+”目录选择终端时每次创建新实例；侧栏系统工具按钮执行“进入当前终端”，采用：
+
+1. 解析当前项目对应的 `ExecutionSpaceSelection`。
+2. 在现有终端实例中按目标 identity 查找 `starting` 或 `running` 状态。
+3. 存在多个匹配实例时激活最近使用的实例。
+4. 没有匹配实例时调用现有终端创建流程。
+
+`closing`、`exited`、`interrupted` 和 `failed` 实例保留为历史 Tab，不阻止快捷按钮创建新终端。
+工作栏“+”继续按原规则创建额外终端，不受快捷按钮去重影响。
+
+### 3.4 资源监控工作栏应用
+
+在 `workbar-contracts.ts` 中增加 `resources`：
+
+```ts
+{
+  id: 'resources',
+  instancePolicy: 'single',
+  defaultContext: 'application'
+}
+```
+
+该应用不加入升级后的默认打开实例。侧栏资源按钮与工作栏“+”目录都通过既有单实例规则创建
+或聚焦它。
+
+## 4. 应用导航偏好
+
+### 4.1 设置结构
+
+在 `ApplicationSettings` 增加独立字段：
+
+```ts
+type BuiltInApplicationId = 'magic-notes' | 'knowledge' | 'heartbeat'
+
+type ApplicationNavigationSettings = {
+  hiddenBuiltInApplicationIds: BuiltInApplicationId[]
+}
+```
+
+默认值为空数组，保持升级前所有可用入口可见。ID 数组可以避免为每个应用增加一个顶层布尔
+字段；Zod schema 必须去重、限制数量并拒绝未知内置
+ID。
+
+首期不保存排序，因为内置应用顺序固定。插件偏好在插件系统确定稳定 identity 和卸载保留
+规则后另行扩展，不提前混入当前 schema。
+
+### 4.2 与现有开关组合
+
+入口可见条件为：
+
+```ts
+const visible = featureEnabled && !hiddenBuiltInApplicationIds.includes(id)
+```
+
+`magicNotesEnabled` 继续控制功能启停。知识库和智能心跳若未来增加业务启停开关，也按同一组合
+规则处理。功能停用时设置页保留显隐偏好但禁用显隐 Switch，并提供原功能设置入口。导航设置
+不能写回现有开关。
+
+### 4.3 持久化与 IPC
+
+沿用现有应用设置链路：
+
+```text
+Renderer
+  -> window.goodbuddy.updates.updateSettings
+  -> settings:application:update
+  -> application-settings-store
+  -> application-settings.json
+```
+
+更新继续由 Main 校验可信 sender、Zod 输入和原子写入。设置版本迁移只补充默认空数组，不
+修改已有 `magicNotesEnabled` 或其他平台设置。
+
+## 5. 侧栏底部重构
+
+现有 `user-card` 是一个覆盖整行的设置按钮。实现时替换为容器和相邻独立按钮：
+
+```tsx
+<div className="sidebar-footer">
+  <SidebarSystemTools onOpenTool={openSystemTool} />
+  <button aria-label={t('navigation.settings')} ...>
+    <Settings aria-hidden="true" />
+  </button>
+</div>
+```
+
+不能在设置按钮内部嵌套工具按钮。设置按钮继续调用 `navigateFromSidebar('settings', trigger)`，
+保留设置预加载、焦点恢复和未保存离开确认。
+
+系统工具按钮调用统一 `openSystemTool`：
+
+1. 设置工作栏打开意图。
+2. 展开工作栏。
+3. 由工作栏创建或激活实例。
+4. 按现有策略把焦点移入目标面板。
+
+工作栏仍由窗口右上方的固定开关关闭，关闭后的焦点返回该开关。
+
+## 6. 工作栏状态与快捷按钮
+
+`RightAssistantSidebar` 应向 `App` 暴露当前活动实例的 `appId` 和必要的有界状态摘要，或由
+现有 `onTabChange` 扩展得到。主侧栏不读取终端输出、文件内容、URL 或活动详情。
+
+```ts
+type SidebarSystemToolState = {
+  activeToolId?: SidebarSystemToolId
+  statusByToolId?: Partial<Record<SidebarSystemToolId, 'attention' | 'error' | 'running'>>
+}
+```
+
+首期可以只实现 `activeToolId`，没有可靠聚合来源时不显示状态徽标。不能根据局部事件猜测错误
+或运行状态。
+
+## 7. 应用显隐更新
+
+应用显隐 Switch 复用平台功能设置的即时更新模式。请求开始后禁用三个应用显隐 Switch，只
+允许一个完整目标集合处于提交中。Main 返回成功结果后更新 App 中的平台设置快照，主导航
+随之变化。失败时恢复控件原值，在对应设置行显示可重试错误；主导航继续读取最后一次成功
+保存的设置。
+
+## 8. 插件兼容边界
+
+首期不增加插件注册表、插件 schema 或插件持久化字段，只保留系统 ID 不向插件开放的产品边界。
+插件市场设计需要单独确定 Host、权限、签名、生命周期和稳定 identity；不得直接复用 DeepSeek
+Harness 的 npm 插件市场。
+
+## 9. 本机资源监控
+
+### 9.1 采集范围
+
+首期在 Main 中使用经过依赖审查的 `systeminformation` 获取整机 CPU、内存和磁盘 IO，使用
+Electron `app.getAppMetrics()` 汇总 GoodBuddy 桌面进程 CPU、内存和进程数。采集函数不接收
+Renderer 提供的路径、PID、设备名或命令。
+
+首期指标定义：
+
+- CPU：整机忙碌时间占比，规范化为 `0` 至 `100`。
+- 内存：总字节数、可用字节数和 `总量 - 可用量` 得到的使用量。
+- 磁盘 IO：所有可用本机磁盘的每秒读取与写入字节数。
+- GoodBuddy：`app.getAppMetrics()` 返回的桌面进程聚合 CPU、工作集内存和进程数量。各进程
+  CPU 先相加，再按逻辑处理器数量归一化为整机容量占比 `0` 至 `100`；不能通过截断总和处理
+  多核数值。
+
+受管 Runtime、MCP 和终端子进程的逐进程指标不在首期范围。磁盘 IO 在平台或权限不足时返回
+不可用错误码，不能回退为 `0`。新增依赖在合入前需要完成许可证、维护状态、打包体积和供应链
+检查；检查未通过时应选择提供同等跨平台语义的 Main 侧实现，不能改用 Renderer Shell 命令。
+
+### 9.2 快照契约
+
+```ts
+type ResourceMetric<T> =
+  | { status: 'available'; value: T }
+  | { status: 'warming-up' }
+  | { status: 'unavailable'; reason: ResourceMetricUnavailableReason }
+
+type LocalResourceSnapshot = {
+  sampledAt: string
+  host: {
+    cpuPercent: ResourceMetric<number>
+    memory: ResourceMetric<{
+      usedBytes: number
+      totalBytes: number
+    }>
+    diskIo: ResourceMetric<{
+      readBytesPerSecond: number
+      writeBytesPerSecond: number
+    }>
+  }
+  goodbuddy: {
+    cpuPercent: ResourceMetric<number>
+    memoryBytes: ResourceMetric<number>
+    processCount: ResourceMetric<number>
+  }
+}
+```
+
+所有数字必须有限且非负；百分比限制为 `0` 至 `100`，字节数设置跨 IPC 上限。`sampledAt` 由
+Main 生成。不可用原因使用稳定枚举，例如 `unsupported-platform`、`permission-denied`、
+`collector-timeout` 和 `collector-failed`，不向 Renderer 返回原始命令输出。`warming-up` 只用于
+依赖两个采样点的 CPU 与磁盘 IO，不能用于掩盖采集失败。
+
+### 9.3 Preload 与 IPC
+
+Preload 只暴露：
+
+```ts
+resourceMonitor.getLocalSnapshot(input: {
+  resetIntervalBaseline: boolean
+}): Promise<LocalResourceSnapshot>
+```
+
+对应 IPC 为 `resource-monitor:local-snapshot:get`。Main 验证可信 sender；单次采集设置超时，
+并合并同一时刻的并发请求，防止多个 Renderer 重复启动系统采集。采集超时后向调用方返回
+有界错误，但底层 Promise 仍占用唯一单飞槽位，直到实际结束；在此之前不启动第二个采集
+任务。输入只接受布尔值，接口不提供任意进程、磁盘或远程主机查询。
+
+合并规则区分普通请求与基线重置请求：
+
+- 普通请求在途时，新的普通请求复用它。
+- 普通请求在途时收到重置请求，Main 最多登记一个待执行重置；当前采集结束后再执行，不能
+  用普通请求结果满足重置请求。
+- 多个重置请求复用同一个在途或待执行重置。
+- 重置请求在途时，普通请求复用其 `warming-up` 结果，下一次时钟再取得区间值。
+
+因此服务最多持有一个在途采集和一个待执行重置。调用方超时不取消这个顺序，也不增加队列
+长度。
+
+面板每次从非活动状态恢复后的首次请求传入 `resetIntervalBaseline: true`。Main 消费本次
+`systeminformation` 与 Electron CPU 读数并重置区间基线，CPU 和磁盘 IO 返回 `warming-up`；
+内存等瞬时指标正常返回。后续请求传入 `false` 并计算当前区间值，避免把面板停用期间计入
+速率。
+
+### 9.4 轮询与历史
+
+`ResourceMonitorPanel` 仅在工作栏展开、`resources` 为活动实例且
+`document.visibilityState === 'visible'` 时启动轮询：
+
+1. 进入活动状态后立即请求一次，并设置 `resetIntervalBaseline: true`。
+2. 此后每 2 秒请求一次；前一请求未结束时跳过本次时钟。
+3. Tab 失活、工作栏收起、页面变为隐藏或组件卸载时清理定时器，并忽略较晚返回的旧请求。
+4. Renderer 环形队列最多保留 150 个带真实时间戳的样本。
+5. 采集失败不追加伪造样本，也不持久化历史。
+
+资源数据不写入应用设置、工作栏布局、运行记录或 SQLite。工作栏布局只保存 `resources` 实例
+及其活动状态。
+
+## 10. 测试
+
+### 10.1 Renderer 测试
+
+- 固定入口顺序不受三个应用显隐组合影响。
+- 运行记录和设置没有显隐控件。
+- 四个系统工具按钮具有名称、工具提示、键盘行为和选中状态。
+- 文件复用不可关闭单实例；浏览器和终端按当前上下文聚焦匹配实例，工作栏“+”允许显式多实例。
+- 工具按钮展开工作栏但不改变当前主页面。
+- 显隐更新成功后主导航立即变化，失败时 Switch 和主导航恢复原状态。
+- 窄窗口下工具按钮不重叠，焦点恢复正确。
+- 资源面板只在可见活动时轮询，跳过重叠请求并把历史限制为 150 项。
+- 窗口隐藏、最小化和恢复时停止轮询并重新建立区间基线。
+- 资源部分可用、全部失败和重新进入活动状态均显示正确结果。
+
+### 10.2 Main 与契约测试
+
+- 新设置字段默认值、合法 ID、重复 ID、数量上限和未知 ID 校验。
+- 旧版本设置迁移后默认显示所有既有应用。
+- 更新导航偏好不修改魔法笔记启停等无关字段。
+- 原子写入失败时保留最后一次有效设置。
+- 资源快照拒绝 NaN、Infinity、负数字节数、越界百分比和未知错误码。
+- 采集超时、权限不足和磁盘 IO 不支持时返回有界部分结果。
+- 超时采集尚未实际结束时保持单飞，不累积新的后台采集任务。
+- 普通采集在途时收到基线重置请求，最多排队一个重置且不复用普通结果。
+- `resetIntervalBaseline: true` 时把 CPU 与磁盘 IO 标记为 `warming-up`。
+- GoodBuddy CPU 预热时，其内存和进程数仍可独立返回。
+- GoodBuddy 多进程 CPU 按逻辑处理器数量归一化，结果保持在 `0` 至 `100`。
+- GoodBuddy 摘要不包含 PID、命令行、环境变量或其他进程信息。
+
+### 10.3 回归范围
+
+- 工作栏布局恢复和已关闭实例重建。
+- 本地与托管 SSH 终端目标。
+- 浏览器无会话、创建中和 Agent 操作中状态。
+- 设置页未保存离开确认。
+- 魔法笔记待办数和智能心跳建议数徽标。
+- 浅色、深色、`220px` 与 `420px` 侧栏宽度。
+- Windows、macOS 和 Linux 的真实 CPU、内存与磁盘 IO 采集；不支持项显示准确原因。
+
+## 11. 实施顺序
+
+1. 增加应用导航设置 schema、迁移和设置界面。
+2. 按即时保存结果组合主导航，并补充失败恢复。
+3. 增加资源快照契约、Main 采集服务和 Preload API。
+4. 为工作栏增加 `resources` 单实例和 `ResourceMonitorPanel`。
+5. 拆分侧栏底部设置按钮，加入四个系统工具按钮。
+6. 为工作栏增加带上下文的 `openOrActivate` 意图接口，以及浏览器和终端匹配规则。
+7. 接入选中状态、焦点恢复、无障碍文案和响应式样式。
+8. 完成 Renderer、契约、迁移和跨平台回归测试。
+
+插件注册与插件市场不与首期改动一并实施。

docs/features/application-tool-navigation/ui-design.md

@@ -0,0 +1,204 @@
+# 应用导航与系统工具入口 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文定义入口、设置和轻量资源监控界面。文件、终端和浏览器的内容布局继续遵守助手工作栏
+文档。
+
+## 1. 侧栏信息架构
+
+```text
+品牌
+项目选择
+新对话
+搜索
+
+当前对话
+魔法笔记               3
+知识库
+智能心跳               1
+运行记录
+
+最近对话
+...
+
+────────────────────────
+[文件] [终端] [浏览器] [资源]      [设置]
+```
+
+“当前对话”和“运行记录”属于固定系统入口。三个内置应用位于二者之间。侧栏底部不再显示
+“本地工作区”和 `platform · arch`；排障信息移至关于或诊断页面。
+
+## 2. 底部系统工具栏
+
+底部使用连续平整表面和顶部分隔线，不做成账户卡片或嵌套卡片。按钮顺序固定：
+
+| 位置 | 图标 | 可见工具提示 | 点击结果 |
+| --- | --- | --- | --- |
+| 1 | `FolderOpen` | 文件 | 聚焦不可关闭的工作区面板 |
+| 2 | `SquareTerminal` | 终端 | 打开或聚焦当前执行空间终端 |
+| 3 | `Globe` | 浏览器 | 聚焦当前 Conversation 的匹配浏览器实例 |
+| 4 | `Activity` | 资源监控 | 打开或聚焦本机资源监控面板 |
+| 末位 | `Settings` | 设置 | 打开设置页面 |
+
+图标使用项目现有 Lucide 库。每个按钮采用统一的 `34px × 34px` 点击区域，内部图标建议
+`16px`。工具栏使用 `8px` 内边距和 `4px` 间隔；设置按钮通过自动空白靠右，不添加第二条
+视觉分隔线。
+
+### 2.1 状态
+
+- 默认：透明背景，图标使用次级文字色。
+- 悬停：使用弱表面色，不能强于当前选中状态。
+- 选中：使用强调选中背景，并提高图标对比度。
+- 键盘焦点：显示统一焦点环，不能被侧栏边缘裁切。
+- 处理中：创建或激活请求未完成时暂时禁用对应按钮，保留尺寸并提供进行中名称。
+- 徽标：只用于等待处理、错误或活动状态，不显示无意义的常驻绿色圆点。
+
+选中状态表达“对应工作栏面板正在显示”，不表达功能已安装或权限已授予。
+
+## 3. 主导航应用区
+
+应用入口沿用现有 `nav-item` 行，不使用应用卡片。图标、名称和徽标保持单行：
+
+```text
+[图标] 魔法笔记                         3
+[图标] 知识库
+[图标] 智能心跳                         1
+```
+
+隐藏某个应用后，其余应用向上补位。运行记录始终位于最后一个可见应用之后，不因应用显隐
+改变样式或归类为工具。
+
+设置页打开期间，主侧栏显示最后一次成功保存的导航状态。Switch 更新成功后导航立即变化，
+失败时保持原导航。
+
+## 4. 应用与工具设置
+
+设置中心新增“应用与工具”分类，采用 `standard` PageShell：
+
+```text
+应用与工具
+管理主导航中的应用。系统工具由 GoodBuddy 提供并固定在侧栏底部。
+
+应用
+魔法笔记       笔记、待办和评论                 [显示在侧边栏  开]
+知识库         管理和检索知识                   [显示在侧边栏  开]
+智能心跳       查看计划、建议和运行历史          [显示在侧边栏  开]
+
+系统工具
+文件           打开当前工作区                   内置
+终端           进入当前执行空间                 内置
+浏览器         打开 GoodBuddy 受控浏览器         内置
+资源监控       查看本机 CPU、内存和磁盘 IO       内置
+
+系统入口
+当前对话、运行记录和设置位置固定，不参与上述配置。
+```
+
+应用显隐使用共享 Switch，标签必须是“显示在侧边栏”，不能缩写为“启用”。切换时立即保存，
+请求期间禁用三个应用显隐 Switch；失败后恢复原值，并在对应设置行显示可重试错误。系统工具
+使用紧凑只读列表，不渲染禁用的卸载、停用或固定按钮。
+
+功能已停用时，对应应用行显示“功能已停用”和设置入口，保留显隐偏好但暂时禁用 Switch。
+
+若某应用自身支持业务启停，应在该应用原有设置中保留“启用功能”开关，并用说明区分：
+
+- “显示在侧边栏”只控制入口。
+- “启用功能”控制该功能是否运行。
+
+## 5. 助手工作栏反馈
+
+点击系统工具后，右侧工作栏按现有布局回流打开。主内容页面保持不变，侧栏不渲染工具内容。
+
+- 文件：激活默认存在且不可关闭的“工作区”Tab，焦点进入目录区域或错误修复入口。
+- 终端：激活匹配终端，焦点进入终端输入区；新建期间保留按钮宽度和进度状态。
+- 浏览器：激活绑定当前 Conversation 的最近使用“浏览器”Tab；没有匹配实例时创建一个，
+  没有 Conversation 时按产品规则复用最近实例或进入待绑定空状态。
+- 资源监控：激活“资源监控”Tab，焦点进入指标摘要；首个样本加载后开始绘制历史。
+
+后台事件可以更新徽标，不能自动展开工作栏或切换当前 Tab。由用户点击快捷按钮触发的打开
+属于显式操作，可以展开工作栏并切换 Tab。
+
+### 5.1 资源监控面板
+
+资源监控使用紧凑单列，不使用指标卡片墙：
+
+```text
+资源监控                                      本机
+
+CPU                                  18%
+[最近 5 分钟折线图]
+
+内存                         9.6 / 32 GB
+[使用量进度条]
+
+磁盘 IO                 读 12 MB/s · 写 3 MB/s
+
+GoodBuddy
+CPU 4% · 内存 620 MB · 桌面进程 7
+
+更新于 14:32:08
+```
+
+- CPU 折线纵轴固定为 `0%` 至 `100%`，不能根据当前低负载动态放大波动。
+- 内存同时显示使用量、总量和百分比；进度条不代替文字数值。
+- 磁盘 IO 使用每秒读写字节并按统一单位格式化，不显示累计设备字节数。
+- GoodBuddy 摘要只显示聚合值，不列 PID、命令行或环境变量。
+- 首次加载或停止后恢复时，CPU 和磁盘 IO 显示“正在建立采样基线”，不先渲染 `0%`；内存
+  等瞬时指标可以立即显示。
+- 部分可用时只在对应指标行显示“不可用”和简短原因；全部失败时显示重试入口。
+- 图表不使用动效平移；`prefers-reduced-motion` 下行为不变。
+- 面板失去活动状态、工作栏收起或窗口隐藏、最小化时停止更新；返回后重新建立区间指标基线，
+  不填补离开期间的历史。
+
+## 6. 文案
+
+固定使用以下名称：
+
+| 对象 | 文案 |
+| --- | --- |
+| 设置分类 | 应用与工具 |
+| 文件系统工具 | 文件 |
+| 终端系统工具 | 终端 |
+| 浏览器系统工具 | 浏览器 |
+| 浏览器说明 | GoodBuddy 受控浏览器 |
+| 资源系统工具 | 资源监控 |
+| 资源范围 | 本机 |
+| 指标缺失 | 不可用 |
+| 应用显隐开关 | 显示在侧边栏 |
+| 内置来源 | 内置 |
+
+不再使用“本地工作区”作为侧栏底部身份名称。项目和默认工作区的路径继续由项目选择器、页面
+范围或工作区面板显示。
+
+## 7. 键盘和无障碍
+
+- 底部按钮均为独立 `button`，不能嵌套在整行设置按钮中。
+- Tab 顺序为文件、终端、浏览器、资源监控、设置。
+- 图标按钮通过 `aria-label` 提供名称，工具提示不能作为唯一可访问名称。
+- 工作栏打开后按现有焦点策略聚焦目标面板；用户通过固定工作栏开关关闭时，焦点返回该开关。
+- 选中按钮使用 `aria-pressed` 或等价的可访问状态，不能只依靠背景色。
+- 徽标的数量或状态合并进按钮可访问名称，例如“终端，1 个等待处理”。
+- 应用显隐 Switch 支持 Space 切换，保存失败后恢复原值并保留焦点。
+
+## 8. 响应式
+
+- 侧栏宽度 `220px` 至 `420px` 时，底部按钮尺寸不随宽度缩放。
+- 窄窗口继续使用现有侧栏抽屉；工具栏不转为多行。
+- 空间不足时缩小设置按钮前的弹性空白，不隐藏四个系统工具和设置。
+- 工具提示不得超出窗口；靠近底边时显示在按钮上方。
+- 粗指针设备不依赖悬停，按钮的可访问名称和选中反馈保持有效。
+
+## 9. 未来插件入口
+
+插件市场交付后另行定义插件区域、固定数量、溢出和权限界面。系统入口与四个系统工具的位置
+保持保留，不向插件开放。

docs/features/application-tool-navigation/user-stories.md

@@ -0,0 +1,236 @@
+# 应用导航与系统工具入口 User Stories
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 关联逻辑 | [功能逻辑设计](./logic-design.md) |
+
+## 1. 角色
+
+### 1.1 普通用户
+
+使用对话、笔记和知识功能，希望常用入口稳定，不需要理解工作栏实例模型。
+
+### 1.2 本地工作用户
+
+经常查看项目文件、打开终端、使用受控浏览器或检查电脑负载，希望从任意一级页面快速进入
+这些工具。
+
+## 2. Epic A：固定系统入口
+
+### US-A1 始终访问运行记录
+
+作为用户，我希望运行记录保持在固定位置，以便应用入口变化后仍能检查 Agent 和工具活动。
+
+验收：
+
+- Given 用户隐藏任意内置应用
+- When 用户查看主导航
+- Then “运行记录”仍显示在应用区之后
+- And 设置中没有隐藏、卸载或固定运行记录的选项
+
+### US-A2 从固定入口进入设置
+
+作为用户，我希望设置入口始终位于侧栏底部，以便快捷工具状态变化时仍能进入配置。
+
+验收：
+
+- Given 任意主页面和任意侧栏宽度
+- When 用户查看侧栏底部
+- Then 设置按钮保持可见且点击区域不与工具按钮重叠
+- And 点击后继续遵守未保存内容的离开确认
+
+## 3. Epic B：管理应用入口
+
+### US-B1 识别完整应用
+
+作为用户，我希望魔法笔记、知识库和智能心跳显示在主导航，以便知道它们会打开完整页面。
+
+验收：
+
+- Given 对应功能已启用且应用设置为显示
+- When 用户打开主侧栏
+- Then 应用位于“当前对话”和“运行记录”之间
+- And 点击应用在主内容区打开对应一级页面
+- And 原有待办或建议徽标继续显示
+
+### US-B2 隐藏低频应用
+
+作为用户，我希望隐藏不常用的内置应用，以便缩短主导航，但保留已有数据。
+
+验收：
+
+- Given 应用已有内容
+- When 用户关闭该应用的“显示在侧边栏”Switch
+- Then 主导航不再显示该应用
+- And 应用数据、计划和业务启停状态不变
+- And 用户可从同一设置位置恢复显示
+
+### US-B4 保留功能启停语义
+
+作为魔法笔记用户，我希望导航显隐与功能启停相互独立，以免整理导航时关闭功能。
+
+验收：
+
+- Given 魔法笔记功能已启用
+- When 用户只隐藏其侧栏入口
+- Then 笔记及待办处理能力继续按原设置工作
+- And 再次显示时恢复原页面和数据
+
+### US-B5 恢复显隐保存失败
+
+作为用户，我希望入口设置保存失败时继续使用原导航，以免界面状态与实际设置不一致。
+
+验收：
+
+- Given 应用显隐更新尚未完成
+- When 用户切换“显示在侧边栏”Switch
+- Then 三个应用显隐 Switch 在请求期间暂时不可操作
+- And 更新成功后主导航立即变化
+- And 更新失败时 Switch 和主导航恢复原状态并显示可重试错误
+
+## 4. Epic C：使用系统工具
+
+### US-C1 一键查看文件
+
+作为本地工作用户，我希望点击左下角文件按钮后直接查看当前工作区文件。
+
+验收：
+
+- Given 当前项目有有效根目录
+- When 用户点击文件按钮
+- Then 助手工作栏展开
+- And 聚焦默认存在且不可关闭的工作区单实例
+- And 文件按钮通过选中状态表明该面板正在显示
+
+### US-C2 处理无效工作区
+
+作为用户，我希望目录不可用时看到修复方法，并收到明确反馈。
+
+验收：
+
+- Given 工作区面板处于跟随模式
+- And 当前项目和默认工作区均不可用
+- When 用户点击文件按钮
+- Then 工作区面板仍打开
+- And 面板说明目录不可用并提供选择或修复目录的入口
+- And 应用不静默改用其他目录
+
+### US-C3 快速进入终端
+
+作为本地工作用户，我希望点击终端按钮后进入当前执行空间的终端。
+
+验收：
+
+- Given 当前执行空间已有正在启动或运行中的终端
+- When 用户点击终端按钮
+- Then 工作栏聚焦最近使用的匹配终端，不创建重复实例
+- Given 当前执行空间没有终端
+- When 用户点击终端按钮
+- Then 创建一个绑定该执行空间的新终端
+- Given 当前没有项目
+- When 用户点击终端按钮
+- Then 创建或聚焦使用本机 Home 的终端
+- Given 当前执行空间只有已退出、已中断或失败的终端
+- When 用户点击终端按钮
+- Then 创建新终端并保留原终端的历史状态
+
+### US-C4 使用远程项目终端
+
+作为远程项目用户，我希望同一个终端按钮进入远程项目目录，以免误在本机执行命令。
+
+验收：
+
+- Given 当前项目绑定托管 SSH 执行空间
+- When 用户点击终端按钮
+- Then 创建或聚焦绑定该远程项目及其权威目录的终端
+- And 面板持续显示远程主机和工作目录
+- And 连接失败时保留重连与诊断信息
+
+### US-C5 打开受控浏览器
+
+作为用户，我希望浏览器按钮打开 GoodBuddy 受控浏览器，以便查看与 Agent 相同的会话。
+
+验收：
+
+- Given 浏览器面板跟随当前上下文且当前会话已有浏览器会话
+- When 用户点击浏览器按钮
+- Then 工作栏聚焦绑定当前 Conversation 的最近使用浏览器实例
+- And 不打开系统默认浏览器或无意创建重复实例
+- Given 现有浏览器实例都绑定到其他 Conversation
+- When 用户点击浏览器按钮
+- Then 工作栏创建并聚焦绑定当前 Conversation 的新浏览器实例
+- Given 当前没有活动 Conversation
+- And 已存在浏览器实例
+- When 用户点击浏览器按钮
+- Then 工作栏聚焦最近使用的浏览器实例并保持其目标
+- Given 当前没有活动 Conversation
+- And 不存在浏览器实例
+- When 用户点击浏览器按钮
+- Then 创建待选择目标的空实例
+- Given 用户需要同一 Conversation 的另一个独立页面
+- When 用户从工作栏“+”选择浏览器
+- Then 每次创建拥有独立页面和导航状态的新实例
+- And 同一 Conversation 内共享隔离登录上下文
+
+### US-C6 查看本机资源
+
+作为本地工作用户，我希望快速查看 CPU、内存和磁盘 IO，以便判断任务变慢是否与本机负载
+有关。
+
+验收：
+
+- Given 资源监控面板尚未打开
+- When 用户点击左下角资源监控按钮
+- Then 助手工作栏创建并激活单实例资源监控面板
+- And 页面显示整机 CPU、内存、磁盘读写及 GoodBuddy 桌面进程摘要
+- And 页面每 2 秒更新一次，并用图表保留最近 5 分钟
+- When 用户切换到其他工作栏 Tab、收起工作栏、隐藏窗口或最小化窗口
+- Then 资源监控停止请求新样本
+- When 用户再次显示窗口并返回资源监控
+- Then 首次采样建立区间指标基线，下一次采样开始显示 CPU 和磁盘 IO 速率
+- Given 某项指标在当前平台不可用
+- When 页面收到部分结果
+- Then 该指标显示“不可用”及原因，其他指标继续更新
+
+### US-C7 从任意应用打开工具
+
+作为用户，我希望在魔法笔记、知识库、智能心跳和运行记录页面也能打开系统工具。
+
+验收：
+
+- Given 用户位于任意一级页面
+- When 用户点击文件、终端、浏览器或资源监控
+- Then 主页面保持不变
+- And 右侧工作栏打开对应面板
+- And 工具不会覆盖主内容或伪装成一级页面
+
+## 5. Epic D：可访问性和布局
+
+### US-D1 使用键盘打开系统工具
+
+作为键盘用户，我希望按顺序聚焦并打开左下角工具，以便不依赖鼠标。
+
+验收：
+
+- 每个系统工具和设置都是独立按钮
+- Tab 顺序与视觉顺序一致
+- Enter 和 Space 均可激活按钮
+- 每个纯图标按钮都有可访问名称和工具提示
+- 焦点样式不被侧栏边界裁切
+
+### US-D2 在窄窗口使用快捷栏
+
+作为小屏用户，我希望侧栏抽屉中的工具按钮保持可操作。
+
+验收：
+
+- 工具按钮保持单行且不重叠
+- 不因宽度不足隐藏文件、终端、浏览器、资源监控或设置
+- 触控点击区域符合统一界面规范
+- 关闭侧栏抽屉后焦点返回原触发按钮

docs/features/assistant-workbar/README.md

@@ -0,0 +1,16 @@
+# 助手工作栏
+
+助手工作栏统一承载本机与远程执行空间、Task、成果、文件、浏览器和终端等持续工作界面。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [通用助手工作栏与执行空间 PRD](./prd.md) | 工作栏整体产品范围、执行空间和各工作面板归属 |
+| [多终端页签 PRD](./terminal-tabs-prd.md) | 工作栏应用的固定、可关闭、单实例和多实例策略，以及多终端生命周期 |
+| [浏览器多实例技术设计](./browser-tabs-technical-design.md) | 浏览器 Tab 身份、Conversation 绑定、IPC、BrowserService 和 MCP 路由 |
+| [实现与验证进度](./progress.md) | 工作区与 Runtime 相关改动的实现事实、验证证据与剩余阻塞 |
+| [Runtime 交互边界](./runtime-interactions.md) | 原生权限、结构化问答、后台拒绝、终端交互、托管 Runtime 并行与输出及消息底部请求状态的适配范围 |
+
+当前尚未拆出独立 User Stories、功能逻辑和 UI 设计文档；相关内容仍保留在两份现有 PRD
+中。浏览器多实例涉及跨进程身份和工具路由，单独使用技术设计文档维护。

docs/features/assistant-workbar/browser-tabs-technical-design.md

@@ -0,0 +1,198 @@
+# 浏览器多实例技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 基础多实例已实施，Agent 多 Tab 工具待需求 |
+| 版本 | 1.0 |
+| 日期 | 2026-09-10 |
+| 关联 PRD | [通用助手工作栏与执行空间 PRD](./prd.md) |
+| 页签策略 | [助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) |
+
+## 1. 目标与边界
+
+浏览器改为可关闭的多实例工作栏应用。每个工作栏浏览器实例对应一个独立 Browser Tab，拥有
+独立页面、导航状态、操作队列、画面状态和元素引用空间。同一 Conversation 下的多个 Tab
+共享隔离存储与代理上下文，使登录状态符合常规浏览器预期。
+
+本设计不把多个工作栏 Tab 实现为同一页面的重复入口，不允许用户切换 Tab 后改变正在执行的
+Agent 工具目标，也不在首期要求模型主动管理多个 Tab。
+
+## 2. 改造前限制
+
+改造前的链路以 `conversationId` 作为唯一浏览器身份：
+
+- Renderer 只保存每个 Conversation 的一份 `BrowserLiveState`。
+- Browser IPC、Preload API 和 `BrowserService` 操作只携带 `conversationId`。
+- Main 每个 Conversation 只创建一个 Session、一个 `WebContentsView` 和一个 CDP Driver。
+- 请求级 MCP 能力只保存 `browserConversationId`。
+- snapshot 元素 `ref` 只在一个 Driver 的引用空间内有效。
+
+因此只把工作栏注册策略改成 `multiple` 会导致多个 Tab 控制同一页面，并产生 viewport、清理和
+元素引用竞态，不能作为可交付实现。
+
+## 3. 身份与所有权
+
+```ts
+type BrowserTabId = string
+
+type ConversationBrowserContext = {
+  conversationId: string
+  partitionId: string
+  tabs: Map<BrowserTabId, BrowserTab>
+  primaryTabId?: BrowserTabId
+}
+
+type BrowserTab = {
+  id: BrowserTabId
+  conversationId: string
+  view: WebContentsView
+  driver: CdpBrowserDriver
+  state: BrowserLiveState
+}
+```
+
+- Conversation Browser Context 拥有隔离 partition、代理配置和全部 Tab。
+- Browser Tab 拥有页面、Driver、串行操作队列、snapshot 代次、idle 状态和可见 viewport。
+- `BrowserTabId` 是 Main 签发的不透明 ID。Renderer 和 Runtime 不能自行选择或复用。
+- 工作栏实例保存公开的逻辑实例 ID 和 Conversation 绑定；进程重启后不恢复旧
+  `WebContentsView`，首次使用时由 Main 为该逻辑实例创建新的 Browser Tab。
+- 删除 Conversation 时关闭该 Context 下全部 Tab；关闭一个工作栏浏览器实例只关闭对应
+  Browser Tab，不得调用 Conversation 级 Runtime 释放路径。
+
+## 4. Renderer 与 viewport
+
+Renderer 状态改为：
+
+```ts
+Record<ConversationId, Record<BrowserTabId, BrowserLiveState>>
+```
+
+每个浏览器工作栏实例持有自己的 `browserTabId`。只有当前可见实例可以提交 viewport。每次
+获得可见权时生成新的 UUID `leaseToken`；提交请求携带 `browserTabId` 和 token，清理请求必须
+回传同一个 token。Main 只接受当前 token 的清理，避免已隐藏实例的延迟 cleanup 隐藏新实例，
+也避免 Renderer 重载后从零开始的数字序列无法覆盖旧租约。
+
+非活动 Browser Tab 保持页面和状态，但隐藏 `WebContentsView` 并停止非必要画面采集。工作栏
+收起、切换主页面和窗口隐藏时采用相同规则，不销毁 Tab。
+普通导航、快照与页面操作只同步轻量导航状态，不自动截图、等待画面或传输 JPEG；只有显式
+`browser_screenshot` 调用生成图片。侧栏内终端关闭确认显示期间，同样隐藏原生浏览器视图，
+确认或取消后恢复当前实例，避免原生子视图遮挡 HTML 确认按钮。
+
+浏览器应用声明 `visibleAcrossContextSwitches: true`，打开的 Tab 跨项目、会话切换继续显示。
+切换活动 Conversation 不改变当前选中的浏览器或其 `targetRef.conversationId`；用户在会话 B
+查看会话 A 的浏览器时，viewport 和手动导航仍指向 A 的原 Tab。新建实例绑定 B。仅未绑定的
+默认或恢复实例可在首次使用时取得当前会话绑定。
+
+Tab 的跨会话可见性与 MCP 授权分开处理。B 的请求不能选择属于 A 的可见 Tab；A 已取得的
+capability 在用户切到 B 后仍固定路由至 A 的原 Tab，使用租约也继续阻止关闭该 Tab。
+内部点击实例只同步应用类型，不再次按当前 Conversation 改选实例。Main 状态携带对应的
+`workbarInstanceId`，Renderer 据此绑定请求创建的同一 Tab，而不是另建空白页。收到 `stopped`
+后清除该实例的旧 Tab 绑定，下一次使用通过原逻辑实例重新创建，保留地址草稿与错误反馈。
+请求创建的实例也遵守现有 32 个工作栏页签上限；满额时保留 Main 页面及其状态，并就地提示
+关闭一个可关闭页签。释放位置后再绑定该页面，不写入超限布局或丢弃 Agent 页面。
+
+## 5. IPC 与服务接口
+
+共享契约增加有界操作：
+
+```ts
+browser.createTab({ conversationId, workbarInstanceId })
+browser.listTabs({ conversationId })
+browser.closeTab({ conversationId, tabId })
+browser.setViewport({ conversationId, tabId, leaseToken, bounds })
+browser.navigate({ conversationId, tabId, url })
+browser.back({ conversationId, tabId })
+browser.reload({ conversationId, tabId })
+browser.stopLoading({ conversationId, tabId })
+```
+
+Main 必须验证 `tabId` 属于同一 `conversationId` 和当前窗口。BrowserService 将现有
+Conversation 级 slot 拆为 Context 与 Tab 两层；同一 Tab 内操作继续串行，不同 Tab 可以并行，
+但仍受窗口级和 Conversation 级有界数量限制。
+
+现有 Conversation 级 `stop/release` 保留为销毁完整浏览器上下文的操作，不能用作关闭单个
+Browser Tab。
+
+## 6. Agent 与 MCP 路由
+
+### 6.1 兼容阶段
+
+第一阶段不修改模型可见的现有浏览器工具参数。模型请求开始时，Main 按以下顺序选择并冻结
+`boundBrowserTabId`：
+
+1. 当前可见且绑定该 Conversation 的 Browser Tab。
+2. 该 Conversation 的 `primaryTabId`。
+3. 预留 primary Browser Tab 身份，首次实际浏览器操作时才创建页面与 Conversation Context。
+
+未使用浏览器的请求只持有随请求释放的内存预留，不创建 Chromium 资源、不触发浏览器 UI、
+也不占用活动浏览器会话名额。物化后使用同一 Tab 身份和工作栏实例归属；取消、能力撤销及
+服务关闭释放未使用的预留，不保存到磁盘。编程 Subagent 继承父请求的 Browser Tab 与浏览器
+Conversation 归属，不新建租约或把页面重新归属到子级对话。
+
+直连模型上下文和请求级 MCP capability 同时保存 `conversationId` 与
+`boundBrowserTabId`。请求执行期间，用户切换、创建或关闭其他工作栏 Tab 不改变工具目标；
+模型请求使用某个 Tab 时禁用该 Tab 的工作栏关闭操作，并说明请求仍在执行。用户先取消请求
+后才能关闭；系统不得把进行中的操作改投其他 Tab。
+
+该阶段 MCP transport、endpoint 和 token 生命周期不变，只扩展服务端 capability 内容和内部
+路由。旧工具调用继续使用被冻结的 Tab。
+
+### 6.2 Agent 多 Tab 阶段
+
+只有明确需要 Agent 管理多个页面时，才增加：
+
+- `browser_tab_list`
+- `browser_tab_open`
+- `browser_tab_close`
+
+导航、snapshot、back 和 screenshot 增加可选 `tabId`；省略时使用请求绑定的默认 Tab。
+`browser_snapshot` 返回 `tabId` 和 snapshot 代次。click、type 和 select 必须校验 capability、
+`tabId`、引用代次和元素 `ref` 属于同一 Driver，禁止跨 Tab 猜测或解析引用。
+
+## 7. 工作栏创建与快捷入口
+
+- 从“+”选择浏览器时始终创建新工作栏实例，并默认绑定当前 Conversation。
+- 没有活动 Conversation 时创建待绑定实例，不创建无归属 Main Browser Context。
+- 主侧栏浏览器快捷按钮优先激活绑定当前 Conversation 的最近使用实例；没有匹配实例时创建
+  一个。没有活动 Conversation 时激活最近使用的浏览器实例；完全不存在时创建待绑定实例。
+- New browser instances use a numbered browser label followed by the active Conversation title, when
+  available. The number avoids existing titles; restoring the layout preserves each saved title.
+  The address bar shows only that instance's page URL. Binding a numbered instance does not overwrite
+  its title; the default unbound browser receives the Conversation label when first bound.
+- 关闭工作栏 Browser Tab 只释放对应 Browser Tab。关闭浏览器上下文是独立危险操作，需要
+  明确说明会影响该 Conversation 下的全部 Tab 和 Agent 浏览器状态。
+
+## 8. 持久化与恢复
+
+`createTab` reuses a live tab only for the same Conversation and workbar instance ID. A new workbar
+instance can adopt the primary tab only when its request creates the Conversation context. An existing
+primary, including one opened by an Agent, is not adopted by a new instance. New sibling tabs start at
+`about:blank` with no navigation history and share the Conversation's cookie partition.
+
+持久化工作栏实例 ID、顺序、自定义标题和公开 Conversation 绑定，不持久化页面进程、CDP
+引用、snapshot、viewport lease、Cookie、Token 或 Main `BrowserTabId`。应用重启后实例显示
+未启动状态，首次导航或 Agent 使用时按原绑定创建新 Tab。
+
+绑定的 Conversation 已删除或不可见时保留实例并显示目标失效，不自动绑定当前 Conversation。
+
+## 9. 限制与验收
+
+- 分别限制每个 Conversation 的 Tab 数和每个窗口的总活动 Tab 数；达到上限时在创建前反馈。
+- 两个 Tab 的地址、历史、加载状态、截图和元素引用互不覆盖。
+- 同一 Conversation 的 Tab 共享登录状态，不同 Conversation 保持隔离。
+- 延迟 viewport cleanup 不能隐藏另一个已激活 Tab。
+- 一个 Tab 的元素 `ref` 不能在另一个 Tab 中执行。
+- 用户切换工作栏 Tab 不改变进行中模型请求的 MCP 浏览器目标。
+- 关闭一个 Tab 不释放 Conversation Runtime，也不关闭同一 Conversation 的其他 Tab。
+- 旧版无 `tabId` 的模型工具调用仍操作请求绑定的默认 Tab。
+
+## 10. 实施顺序
+
+1. 引入 Browser Context 与 Browser Tab 两层身份，拆分 partition 和页面生命周期。
+2. 扩展 Shared、Preload、IPC 与 BrowserService 的 `tabId` 和 viewport `leaseToken`。
+3. 改造 Renderer 状态与工作栏实例，开放浏览器 `multiple` 策略和单 Tab 关闭。
+4. 将直连模型与 MCP capability 绑定到请求开始时确定的 Browser Tab。
+5. 完成跨 Tab 引用隔离、并行队列、共享 Cookie、关闭和恢复测试。
+6. 有明确 Agent 多页面需求后再开放模型可见的 Tab 管理工具。

docs/features/assistant-workbar/progress.md

@@ -0,0 +1,316 @@
+# 工作栏实现与验证进度
+
+## 2026-09-10 提交后保留问答
+
+- 桌面端在提交成功后保留结构化问答回顾，支持多轮回答、跳过及本地会话重新加载；
+  交互规则见 [Runtime 交互边界](./runtime-interactions.md#运行与失败)。
+- App 回归覆盖提交与重载、下一轮问题提前到达、终态先于提交返回、提交失败；数据库
+  回归覆盖完整替换、增量保存、关闭重开、多选及超过 1,000 字符的自定义答案。
+- `npm test`：3,900 项通过、66 项跳过，Agent 离线依赖清单测试在 60 秒超时；
+  该项独立复跑通过（58.33 秒）。`npm run typecheck`、`npm run lint` 与差异空白检查通过。
+- 本轮未手动运行真实 OpenCode 问答会话，外部模型调用 0 次。修改仅涉及桌面端展示与
+  本地保存，不改变 Runtime 回传协议或 Agent 路径，不新增远程 ACP 问答能力。
+
+## 2026-09-10 Git 历史测试夹具修复
+
+- 桌面候选 `877cf58` 的 CI 在四项工作区测试准备 Git 提交时因缺少作者身份失败。
+  `c037d7f` 移除测试身份后引入了机器配置依赖；本机已有身份使该问题未在本地暴露。
+- 测试现在把已暂存的 tree 写入固定 Git commit 对象，并仅更新临时仓库的分支引用，
+  不调用 `git commit`，不修改或覆盖任何 Git 身份配置。历史、重命名差异、分页和脏文件
+  分支冲突仍由真实 Git 与生产 `manageWorkspace` 验证，不用 mock 或跳过用例替代。
+- 新增夹具自检确认 `git fsck --strict` 通过、父提交链有效、未暂存内容保持不变且仓库配置未改。
+  聚焦测试 11 项通过、2 项因当前文件系统大小写不敏感而跳过；无身份 Runner 的验证待新候选 CI。
+- 完整 `npm test` 为 3845 项通过、66 项跳过、1 项未修改的活动列表测试超时；
+  随后 `ActivityPanel.test.tsx` 的 16 项独立复跑全部通过，未放宽时限或删除断言。
+  `npm run release:notes:verify`、`npm run typecheck`、`npm run lint` 通过。
+  未将这次本地整库结果记为全绿，发布仍以新候选的 CI 校验和生产构建通过为前提。
+- 本轮只改测试和验证记录，产品功能、Agent 源码及已批准的双语发布说明不变，无外部模型调用。
+
+## 2026-09-10 工作区布局与分支输入样式
+
+- 按 [FR-W1、FR-W4](./prd.md#76-工作区) 将视图切换和刷新合并到顶部行，
+  文件与 Git 工具按视图显示；移除根目录的孤立图标及空导航行，子目录保留文字路径导航。
+  分支搜索复用共享 `field`，面板限宽、分支列表限高滚动，创建按钮使用紧凑次操作。
+- 新增布局、子目录返回、焦点恢复、分支搜索/切换/创建回归；工作区、设置界面、设置存储、
+  IPC 和 Sidebar 五个测试文件共 354 项通过。另确认安全与数据的默认 `toolApproval` 为
+  `always`，对应“Execute 自动授权已启用的工具”；已有明确保存的禁止策略仍保留。
+  本轮没有修改授权策略或默认值。
+- 当前构建的 Windows Electron 使用独立 profile 和临时 Git 项目，实际 App → Preload →
+  Main 路径通过分支搜索、切换、创建和子目录新建文件；磁盘与 Git 分支结果均确认。
+  文件/Git 切换保留浏览目录，返回根目录后导航行移除、焦点回到刷新；Escape 收起分支面板并恢复焦点。
+  真实安全与数据页面的默认选中项也确认为自动授权。
+- 浅色与深色下，将实际工作栏布局宽度设为 300、420、650px 后均无工作区横向溢出。
+  输入框为共享 13px 正文、标签 11px，分支面板最大 360px；15 个分支时列表可在 240px 内滚动。
+  这些是布局检查，不作为分栏拖拽或原生浏览器鼠标交互的验证。
+- `npm run build:bundle`、`npm run typecheck`、`npm run lint` 通过。
+  整库 `npm test` 为 3843 项通过、1 项失败、66 项跳过；失败项是未修改的
+  `opencode-runtime-lifecycle.test.ts` 事件流关闭时序断言，单独复跑通过。
+  未再次运行整库，不将此结果记为整库全绿。
+- 本轮产品改动仅为共享 Renderer 工作区布局，未改 Main/Agent 的工作区命令、
+  desktop-to-Agent 协议或 Runtime 执行逻辑；远程项目继续使用同一组件和既有回调，
+  本轮未做新的 Host 实测。无外部模型调用，所属测试应用、浏览器会话和调试监听已关闭。
+
+## 2026-09-10 提交审查修复
+
+- [FR-W3、FR-W6](./prd.md#76-工作区)：同一目录项可仅修改大小写，仍拒绝覆盖其他文件、
+  目录和硬链接目录项；提交 Diff 同时使用重命名前后路径；分支后台刷新不再使历史请求
+  遗留 busy；自动目录刷新包含当前浏览目录并去重。
+- 浏览器请求仅预留目标身份，首次导航才创建实际资源；Main 状态携带工作栏实例身份，
+  Renderer 直接绑定同一页面，停止或回收后清除旧绑定。跨会话显式选择不会被应用类型
+  同步覆盖，终端关闭确认期间释放原生浏览器 viewport。规则以
+  [浏览器多实例技术设计](./browser-tabs-technical-design.md) 为准。
+- 删除普通浏览器操作的自动截图、固定等待、重试及 JPEG 状态缓存/IPC 字段，保留显式截图。
+- 整合复核补齐现有 32 页签容量处理与 Harness 代理的已发现工具复用。新增容量回归验证
+  满额时布局仍有效、页面保留，关闭一项后显示原页面；Harness 回归验证发现接口后续失败时
+  已知工具调用不再触发发现。相关三文件 66 项通过，最新 typecheck 与 lint 通过。
+- 工作区聚焦测试 43 项通过、2 项需大小写敏感文件系统而跳过；IPC 与 Sidebar 聚焦回归
+  132 项通过。随后新增的 Ask 指令、继承 Runtime 用量持久化及计划模式 App 场景，3 项通过。
+- 扩展真实 Electron/MCP E2E 在独立临时 profile 通过：四个未使用的请求预留不创建会话、
+  WebContents 或 UI 事件；首次 MCP 导航物化相同 Tab/工作栏身份，恢复不额外创建页面，
+  并验证独立页面、共享 Cookie、请求租约关闭保护和清理。
+- 当前源码的共享 Linux x64 Host 验证已通过，覆盖工作区目标保护和重命名/Git Diff，
+  并通过桌面托管 ACP → 隔离 Agent → OpenCode 完成 Ask/Execute 和继承 Runtime 指标持久化；
+  该组共 3 次真实模型调用，清理后无所属进程残留。完整记录见
+  [远程 Host 开发验证](../remote-host/technical-design.md#agent-开发期间的真实-host-验证)。
+- 最终整库 `npm test` 为 341 个文件通过、9 个文件跳过，3839 项通过、66 项按平台或手动
+  条件跳过、0 失败；`npm run typecheck`、`npm run lint`、开发期 `npm run build` 和
+  `git diff --check` 通过，19 份修改 Markdown 的相对链接目标检查通过。
+  先前整合中的一轮为 3823 项通过、6 项失败、66 项跳过，另有被移动的测试路径加载失败，
+  不作为最终结果；源码稳定后完整重跑得到上述全绿结果。
+- 原文档解析焦点回归改为等待 Modal 的焦点效果，保留焦点与背景隔离断言，没有改动产品逻辑。
+- Windows 独立 Electron profile 的完整 App → Preload → Main UI 验证通过；最终复测使用
+  本轮最终开发构建。启用浏览器后普通 Execute 没有创建原生浏览器视图，工具导航只创建
+  一张同时显示在工作栏的页面，跨会话选择保留原页面与 viewport。
+- 实际终端连通后，从浏览器关闭该终端可正常显示确认并操作按钮；原生视图可见性按
+  可见 → 确认时隐藏 → 取消后可见变化，终端关闭清理完成。无效地址 `http://` 被拒绝后，
+  原控件可重试有效地址并关闭页面；关闭端口返回了过滤代理错误页，因此该 UI 场景不作为
+  Chromium `loadURL` 拒绝的实机证据。服务与 Renderer 释放绑定回归另有自动测试覆盖。
+- 桌面使用确定性 loopback 模型服务驱动真实生产路径，共 24 次本地 completion 请求，
+  未发出外部模型请求；可选真实 Provider 探针没有找到已加密保存的 OpenAI 兼容文本连接，
+  未据此宣称桌面真实模型验收通过。Ask 与编程 Subagent 的桌面结果见
+  [直连模型验收记录](../direct-model-agent/progress.md#2026-09-10-提交审查后的桌面-ui-验收)。
+  测试应用与具名浏览器会话已退出，所属 Electron/Node 进程及 fixture 监听端口均为 0；
+  临时截图和隔离 profile 保留在本机测试目录，不进入仓库。
+
+## 2026-09-10 固定基础页签与浏览器多实例
+
+- 工作栏注册表已分别声明实例策略、默认上下文、默认打开、必须存在、可关闭和排序属性。
+  任务中心与工作区保持默认存在且不可关闭；浏览器改为当前 Conversation 上下文的多实例。
+  布局加载按 `required` 补回缺失的基础页签，并修复失效活动实例。
+- 任务中心增加“当前项目”“全局任务”“全部项目”范围，默认跟随活动项目；任务和审批按
+  Conversation 所属项目过滤，范围模式随工作栏布局持久化。
+- 浏览器服务已拆分 Conversation Context 与 Browser Tab。每个 Tab 拥有独立页面、Driver、
+  操作队列、状态和元素引用空间，同一 Conversation 的 Tab 共享 partition、代理和 Cookie。
+- Renderer 使用工作栏实例 UUID 原子创建或恢复 Browser Tab，并以 UUID viewport token 防止
+  延迟 cleanup 隐藏新活动 Tab。关闭单个实例只释放对应 Tab。
+- 直连模型和请求级 MCP capability 在请求开始时优先绑定可见 Tab，其次绑定 primary Tab，
+  并持有使用租约。请求结束或 capability 撤销前，绑定 Tab 拒绝关闭；工具参数未增加模型可见
+  `tabId`，已有浏览器工具 schema 保持不变。
+- 聚焦回归命令覆盖 Shared、BrowserService、Electron Session、IPC、Preload、MCP、Renderer
+  和 Workbar，13 个测试文件共 453 项通过；`npm run lint` 与 Web TypeScript 检查通过。
+- `node build/run-browser-tabs-electron-e2e.cjs` 通过。该测试启动真实 Electron/Chromium 和本地
+  HTTP 页面，创建两个 `WebContentsView`，验证页面隔离、同 Conversation Cookie 共享、真实
+  loopback MCP 的固定 Tab 导航与快照、使用租约关闭保护，以及单 Tab 和最终 Context 清理。
+- `npm run typecheck`、`npm run lint`、`npm run build:bundle` 和 `git diff --check` 通过。
+- 本轮整库 `npm test` 为 3686 项通过、61 项跳过、4 项失败。失败位于 portable/release 的
+  ASAR 元数据 fixture、Runtime 版本探测和 DeepSeek Harness 的本地 MCP fixture；定向复跑仍
+  失败。本次工作栏、浏览器、IPC 和 MCP 聚焦回归均通过，不将整库结果记为通过。
+
+## 2026-09-09 移动目录选择与 Git 控件修正
+
+- 本轮在已有文件管理改动上修正 [FR-W3、FR-W4、FR-W6](./prd.md#76-工作区)：
+  本机移动调用创建项目使用的 `settings.selectWorkspace()`；远程移动调用
+  `sshHosts.browseDirectories()`，按项目 Host 浏览。所选目录映射为工作区相对目标，
+  保留原名；取消不提交移动，外部目录在弹窗内提示限制。
+- 取消、分支、Fetch、历史展开和提交行接入共享控件样式；删除菜单项左对齐。
+  远程目录列表限制滚动高度，保留加载、空目录、失败和截断提示。
+- `npm test -- src/renderer/src/WorkspaceFilesPanel.test.tsx src/renderer/src/RightAssistantSidebar.resize.test.tsx src/main/workspace/workspace-management.test.ts src/main/ssh/ssh-host-directory-browser.test.ts`
+  通过 56 项，覆盖本机目录选择桥接、Windows 与 POSIX 目标映射、取消与越界选择、
+  远程 Host 和目录参数、取消未完成的浏览，以及 Git 控件与真实文件管理服务。
+- `npm test -- src/renderer/src/App.test.tsx -t "workspace|stale Git|opens the global assistant sidebar"`
+  通过 12 项。工作栏切换测试改为等待项目目录加载后出现刷新按钮。
+- `npm run typecheck`、`npm run lint` 和 `git diff --check` 通过。
+- 本轮整库 `npm test` 完整运行 944 秒，3642 项通过、61 项跳过、6 项失败。
+  工作栏加载时序断言已修正并定向复测通过；其余 5 项涉及 Agent 离线依赖测试超时、
+  DeepSeek Harness MCP 加载、Runtime 版本探测，以及 portable/release 打包产物检查。
+  未再次运行整库测试，不记为整库通过。
+- 隔离 Electron 窗口加载当前源码组件和 CSS，检查浅色、深色主题下 300px、420px 工作栏：
+  无横向溢出，分支与 Fetch 同行，提交行左对齐；移动弹窗没有路径输入框，取消为次按钮，
+  删除项计算样式为左对齐。截图保留于本机临时验证目录。此检查使用桥接替身，未自动操作
+  系统原生目录对话框，也不替代完整应用中的人工验收。
+- 尝试从隔离 Electron 配置调用真实 SSH 目录浏览服务时，已有凭据在
+  `safeStorage.decryptString` 解密失败，尚未建立 Host 连接。真实远程目录选择验收仍受阻；
+  未修改用户配置或远端文件，本轮未调用真实模型。
+
+## 2026-09-09 文件管理与 Git 工作区扩展
+
+- 已只读核对根目录规范、UI 设计系统、目录浏览组件、WorkspaceAccess 与 Agent 协议。
+  本轮范围定义于 [PRD 工作区 FR-W1 至 FR-W6](./prd.md#76-工作区)。
+- 当前生产路径具备目录、属性、文本预览和工作树 Diff；Agent 的写入及 Git operation
+  仍是只读拒绝接口。文件管理、分支与提交历史尚未实现或验证，不能视为完成。
+- 待完成源码实现、整库 test/typecheck/lint、真实桌面路径与当前源码 Linux Host 验证。
+  本轮开始前已有浏览器与工作区未提交改动，保留这些改动；不提交或推送。
+
+## 2026-09-09 工作区页签交互
+
+- 已核对当前工作树中的 `RightAssistantSidebar.tsx` 和 `WorkspaceFilesPanel.tsx` 差异：
+  文件预览期间目录树保持挂载，接入返回位置与焦点恢复、文件与未提交更改分段视图、
+  目录就地重试，以及文件预览和 Diff 操作。行为定义见 [PRD 工作区](./prd.md#76-工作区)。
+- `npm test -- src/renderer/src/RightAssistantSidebar.resize.test.tsx src/renderer/src/WorkspaceFilesPanel.test.tsx`
+  通过 35 项，覆盖目录展开、返回位置与焦点、视图选择、刷新失败保留内容、Markdown
+  源码切换，以及切换项目后丢弃未完成的文件预览。
+- `npm test -- src/renderer/src/App.test.tsx -t "workspace|stale Git"` 通过 11 项，
+  覆盖应用中的文件预览、路径复制、默认应用打开、返回和任务结束刷新。
+- 本轮 `npm test` 完整运行结果为 3629 通过、61 跳过、5 失败。失败位于 Agent 离线
+  依赖打包超时、DeepSeek Harness MCP 加载、Runtime 版本探测，以及两个打包产物检查，
+  不将该结果记为整库回归通过。
+- `npm run lint` 和差异空白检查通过。最新 `npm run typecheck` 被同时进行的浏览器
+  接口变更阻塞：测试替身缺少 `hide`、`setBounds`、`setViewport`，部分侧栏测试仍传递
+  已移除的浏览器回调。该轮类型检查未通过，未改动另一项任务的接口或测试替身。
+- 尚未进行真实桌面视觉验收；组件测试的滚动断言不代替实际窗口中的布局和滚动检查。
+- 范围仅限工作区页签，不包含项目文件搜索或其他页签改动。
+
+## 2026-09-09 托管 Runtime 并行阻塞
+
+- Windows 完整隔离测试程序通过界面发送 OpenCode 原生双子代理、直连与 Continue 文件
+  任务；随后三路上游请求在 917 ms 内发出并重叠，全部完成。普通并发没有复现全局排队。
+- 在同一程序中，让真实模型执行一次 4,000 行、约 98 KB 文件的 CRLF → LF 转换，
+  同时运行另一个会话。原生进程的无凭据存活探针两次延迟 3,301 ms、3,085 ms；
+  原生热线程持续使用 CPU，而 Main 没有同步满载。操作不是模拟事件或直接调用
+  Runtime 的脚本，模型请求来自实际输入框和发送按钮。
+- 托管 OpenCode 关闭未消费的自动 Git 快照后，完整程序重复相同操作和并行会话，
+  90 秒观察中的最大原生探针延迟为 210 ms，没有超过 500 ms 的探针，两条请求均完成。
+  该对照验证已复现的快照阻塞得到消除，不声称已经证明历史 90–125 秒事件的唯一原因。
+- Continue 的实际 Electron 原生宿主在不排空 stdout 时被注入的 128 KiB 输出阻塞；
+  使用当前生产适配器后，输出在 5 ms 内完成，20 次状态读取全部成功，最大 5 ms。
+  这证明管道修复有效，不代表普通启动约 640 字节的输出就是历史卡顿原因。
+- 修复版完整程序再次完成原生双子代理与 Continue 文件任务，实际请求重叠，三个页面
+  都通过计数按钮功能检查。Windows 诊断与程序验证合计 40 次成功模型调用；
+  另一次 UI 请求返回账户额度不足的 402，用户充值后才继续，没有把失败当成通过。
+- 当前源码 Linux x64 Agent 经桌面生产管理链路完成 Ask 读取和 Execute 换行转换，
+  共 4 次成功模型调用；最终原生配置确认 `snapshot: false` 且权限仍为 `ask`/`allow`。
+  此验证覆盖实际 Agent、模型桥、工具完成和关闭，不量化 Linux 提速，也未注入取消。
+- 定向回归先验证 7 项失败，再验证 124 项通过、5 项 Windows 平台跳过；
+  全项目类型检查和修改文件 lint 已通过。首次全量回归为 3625 通过、1 失败、61 跳过；
+  失败来自生命周期测试的包装流在底层 reader 关闭后仍计数为打开，已通过独立流实验
+  复现并改为观察 `reader.closed`，没有因此修改生产取消逻辑。最终候选全量回归为
+  3626 通过、0 失败、61 跳过，`npm run typecheck`、`npm run lint`、
+  `npm run release:notes:verify`、差异空白与文档相对链接检查通过。本机和远端的
+  测试进程已回收，安装版和正式 Host 环境未改动；正式发布仍需候选 CI 与资产核实。
+  运行策略见
+  [托管 Runtime 并行与输出](./runtime-interactions.md#托管-runtime-的并行与输出)。
+
+## 2026-09-08 消息底部请求状态
+
+- 已接入本机 OpenCode 父会话的原生重试等待及开始事件；直连模型把退避等待与实际发起
+  重试分开显示，Continue 初始文案改为中性的请求处理。显示规则和未接入边界见
+  [消息底部请求状态](./runtime-interactions.md#消息底部请求状态)。
+- 消息底部按真实事件显示准备、工具、待回答及终态；有新进展时清除旧状态，结束后不
+  接受迟到状态覆盖。仅该处状态点改为静态，会话列表闪点、发送和停止按钮未改动。
+- Windows 隔离开发桌面通过实际 UI 发送验证 OpenCode 的 503/Retry-After 等待、
+  原生重试开始、真实模型回复与完成；直连模型通过派发前连接拒绝、500 ms 等待、
+  重试、真实回复与完成。故障由本机测试代理注入，不冒充服务商实际故障。
+  三个隔离测试配置总计 5 次真实文本模型调用；另有一次直连重试被测试代理的调用
+  上限明确拒绝，界面正确显示失败，最终单次补测完成。未执行用户命令或修改安装版。
+- DOM 状态记录确认底部无闪烁、完成后无旧重试文案，浅色截图可见原生重试计划与原因；
+  底部 WCAG 2 A/AA 定向检查无违规。最小化窗口的补充截图超时，未作为通过证据。
+  隔离窗口及测试代理已结束。
+- 最终 `npm test -- --reporter=json --outputFile=<临时报告路径>` 为 3618 项通过、
+  0 项失败、61 项按平台或手动条件跳过；首轮的压缩状态旧断言已修正，途中被用户中断
+  的运行不计为通过。`npm run typecheck`、`npm run lint`、
+  `npm run release:notes:verify`、差异空白与相关文档相对链接检查通过。
+
+## 2026-09-08 Desktop 0.12.8 安装包修复
+
+- 真实 `0.12.7` 安装目录确认 OpenCode 配置缺少整个 `node_modules`。新增测试调用实际
+  electron-builder 资源复制器，复现相同 ENOENT；把复制源上移到 `.runtime-resources`
+  后，插件及传递依赖逐文件复制验证通过。
+- 真实安装的 DSH bootstrap 存在 `dsh-session-projection` 外部导入，而 Host 解包目录没有
+  对应依赖。将其加入 Vite bundling，配置回归从失败转为通过；最终包会拒绝同类外部导入。
+- Windows x64 CI 已接入包内 OpenCode 插件导入、真实 DSH UtilityProcess 握手及 npm
+  探针，位于解包目录清理和发布之前。用户要求不做本地打包；CI 探针结果尚待本候选执行，
+  不能把当前源码回归通过当作真实发布包已通过。
+- 本次不改变 Agent `0.11.21` 源码或包。macOS 改为 DMG-only，用户明确接受旧版客户端
+  手动升级影响；格式与发布规则见[发布手册](../../development/release-runbook.md)。
+
+## 2026-09-08 Execute 目录权限等待修复
+
+- 本机 OpenCode 的内部配置显式允许默认工具权限；每次 Ask 仍设置 deny-all 会话规则并
+  禁用工具，当前请求精确分配的只读能力例外。Execute 不把 Workspace 当作目录边界。
+- `permission.asked` 不再忽略所有非父会话事件。Main 用 OpenCode Session 的 `parentID`
+  确认属于当前请求的子孙会话后按当前模式回复；其他并行会话不受影响，同一请求只回复
+  一次。子会话权限不伪装为父会话中的待完成工具。
+- 真实 OpenCode `1.18.9` 和候选 `1.18.29` 均已通过本地确定性模型驱动的原生 Task
+  工作区外读取回归；同一 Runtime 的 Ask 仍不暴露文件与命令工具。
+- Continue `1.5.47` 的真实 CLI 已通过 Execute Shell 写入工作区外测试文件；DSH 固定
+  Host 已通过 Execute 工作区外写入、随后 Ask 拒绝同一写工具，未增加权限策略或人工审批。
+- 真实 OpenCode `1.18.29` 已完成原生 Task 后的 yes/no 与自由文本问答回传；父、子会话
+  提问及后台任务不能交互时的失败路径均有回归测试。Continue 真实 `AskQuestion` 暴露了
+  QuizService 扁平数据结构与原适配器不一致的问题，现已按锁定版本修正；真实自由文本
+  回传、yes/no、选项及跳过均验证通过，自定义答案不再误标为选项。
+- DSH 活跃 Execute 的 ACP 权限回调不再等待第二次 authorizer，Ask 继续拒绝；未添加
+  通用业务问答工具或从终端日志猜测确认意图。完整范围见
+  [Runtime 交互边界](./runtime-interactions.md)。
+- 当前源码 Linux x64 Agent 通过签名组包、生产安装、真实 Ask/Execute、原生子代理
+  工作区外写入、重连同一 daemon 和 stop/bootstrap。实机回归同时定位并修复了握手
+  Base64URL 响应误用 ID 校验及断流未结算等待；13 项 Unix 原生端点测试和连续 20 次
+  握手通过。两轮真实模型调用合计 10 次，均 completed；本轮测试 Agent 已停止。
+- 最终完整回归使用 `npm test -- --reporter=json --outputFile=<临时报告路径>`，并通过
+  `GOODBUDDY_TEST_OPENCODE_BINARY` 指向已验证版本的候选 OpenCode。结果为 338 个文件、
+  3597 项通过、0 项失败、61 项按平台/手动条件跳过，报告 `success=true`、退出码 0；
+  Windows 跳过的 Unix 端点场景另在 Linux Host 运行了上述 13 项原生测试。
+- 最终 `npm run typecheck`、`npm run lint`、`npm run release:notes:verify` 和差异空白检查
+  通过，相关 Markdown 相对链接有效。此前失败、暂停及控制台截断的回归记录由本次完整
+  JSON 报告覆盖，不代表仍有测试失败。未执行系统休眠/唤醒或本地桌面生产构建、打包；
+  后续发布仍需对应候选的 CI 构建和跨平台验证。
+
+## 2026-09-08 OpenCode 复用与原生控件恢复
+
+- `OpenCodeRuntime` 仅在没有活动请求时探测缓存的 embedded server；活动对话或
+  Compact 期间直接复用服务，避免新会话的一次短探测失败关闭其他会话正在使用的进程。
+  空闲探测失败时仍清除旧 client 和会话映射并重建；并发调用共享检查与重建。
+  进程退出或服务关闭会中止绑定它的对话与 Compact，事件流重连等待也可立即取消，
+  请求明确报错，不自动重放已执行命令。本次修复后的真实模型验证共 6 次：正常并发、
+  已复现场景下的共享服务保护均正常完成；主动结束测试进程后旧请求明确失败，新请求
+  在替换服务上完成。此前“新会话完成、旧会话持续等待”的故障不再出现。
+- 请求级 MCP 注册与断开通过实例内 `mutateMcp` 队列串行执行。仅实际发出 `mcp.add`
+  的名称进入清理列表；注册尚在排队时取消不追加断开。断开的 1 秒超时从出队后开始。
+- `App` 按本机/远程、连接方式、项目和 Runtime 选择组成 scope 缓存原生清单，用请求
+  代次阻止旧 scope 结果回写；同 scope 会话刷新不清空重取，切换会话重置消息级选择，
+  Runtime 切换状态也按 generation 隔离。清单请求失败或返回 `unavailable`/`partial`
+  时保留已有可用缓存并有界重试；没有可用缓存时保留新返回的部分数据，因此
+  `unavailable` 重试为可用 `partial` 后可显示 Agent 和 Command。
+
+验证记录：首轮定向测试 273 项通过、5 项跳过；补充修复后的 Runtime 与生命周期测试
+77 项通过，界面定向测试 6 项通过，类型检查通过。修复前的 lint 检查通过。
+全量测试超过 120 秒被终止，期间出现一项 DS 本地 stdio MCP 测试失败，尚待定位。
+这是当次历史结果。后续发布前修复与实机验证见本文上方及
+[远程主机技术设计](../remote-host/technical-design.md)；真实系统休眠恢复仍未完成验证。
+
+## 2026-09-06 项目工作区
+
+范围见 [PRD 工作区](./prd.md#76-工作区)。
+
+当前源码已移除重复标题与底部完整 Diff 入口，使用彩色 Git 状态字母，点击更改项读取
+单文件 Diff。已暂存与未暂存差异分开展示；本机 Git 测试覆盖无首次提交、未跟踪、
+暂存后继续修改、重命名、删除及包含方括号的路径。Git 刷新驱动目录树重新读取，保留
+展开状态；SSH 项目不提供本机系统打开按钮。审查后补齐了当前 Diff 随刷新重读、
+旧请求结果失效，以及超过 50 项变更的继续加载入口。
+
+验证记录：
+
+- 最终 `npm run typecheck`、`npm run lint`、`npm run build` 均通过。
+- 工作区专项 7 个测试文件复跑：317 项通过，3 项 Linux 专用测试在 Windows 跳过。
+  任务完成测试同时检查目录树出现新文件。
+- 最终 `npm test`：326 个测试文件、3552 项测试通过，9 个文件、58 项测试按既有条件
+  跳过。复核首轮曾有一项浏览器地址草稿测试超时，单独复跑及最终全量复跑均通过；
+  更早的超时/失败记录不再作为最终验收结果。
+- 后续复核已通过既有凭据和固定 Host Key 经 VPN 连接共享 Linux x64 Host，使用当前
+  源码构建的隔离 Agent 包安装并启动。真实 `RemoteWorkspaceAccess → Agent git/status`
+  与 `git/diff` 路径覆盖暂存后继续修改、删除、重命名、未跟踪和方括号路径；均通过。
+  Git 验证未调用模型。
+- Windows 隔离桌面实例已通过真实点击验收：当前项目单文件暂存/工作树 Diff 分组与
+  增删颜色正确，修改测试文件后点击刷新可更新正在查看的 Diff，53 项变更经加载更多
+  全部可访问。截图留在本地验证目录，不纳入产品包。
+
+目录分页、任意目录切换和 HTML 预览不在本轮改动范围内。

docs/features/assistant-workbar/runtime-interactions.md

@@ -0,0 +1,61 @@
+# Runtime 交互边界
+
+本文定义当前原生交互的适配范围，不增加工作模式或第二层 Execute 审批。
+
+| Runtime | 权限确认 | 业务问答 |
+| --- | --- | --- |
+| 本机 GoodBuddy 管理的 OpenCode | 内部默认配置允许权限；每个 Ask 请求仍使用 deny-all 与显式只读能力。Execute 自动回复属于当前请求的父、子孙会话权限事件，不处理其他并行请求 | 通过 `question.asked` 转交父、子孙会话问题，支持原生单选、多选、yes/no、自由文本及跳过；使用公开 ID 回传 `question.reply/reject` |
+| Continue | Execute 启动传入 `--auto`，剩余原生权限请求按当前模式自动答复 | 对接 `1.5.47` QuizService 的扁平 `pendingQuestion`，其中 `question` 是字符串。选项回答与自定义文本分别回传正确的 `isCustomAnswer`；跳过发送拒绝回答的文本 |
+| DeepSeek Harness | 固定 Host 的 Execute 文件与命令工具不询问目录权限；若收到 ACP 权限请求，活跃 Execute 直接选一次性允许，缺少该选项时使用 Runtime 提供的允许选项，Ask 拒绝，不等待额外 authorizer | 固定 Host 当前未提供通用原生业务问答服务，不把普通模型正文误识别成待答协议。模型以普通回复提问时，用户通过下一条消息回答 |
+
+托管 SSH OpenCode 的 ACP 权限处理与直接启动配置由
+[远程主机技术设计](../remote-host/technical-design.md)定义；本机 SDK 问答适配不代表远程
+ACP 已提供相同业务问答接口。
+
+## 运行与失败
+
+- 结构化 yes/no 是普通选项，不从日志、自然语言或 Shell 输出猜测用户意图。
+- 前台问题停留在现有问答卡片，保留回答、提交失败提示与跳过入口。
+- 回答或跳过成功后，会话保留只读的“问题与回答”，显示原问题及对应的选项答案、
+  自定义文本或“已跳过”。同一任务的多轮问答逐次保留，随本地会话保存，重新打开后仍可查看。
+  提交失败时保留输入与重试入口，不生成已回答记录；取消未回答的问题不记为主动跳过。
+- 提交响应晚于任务结束时仍保存已提交的问答，但不覆盖完成或失败状态；晚于下一轮提问时
+  不清除新的待答卡片。旧版会话未保存的问题与答案无法从“已提交”状态文案恢复。
+- 后台任务收到结构化提问时，通过现有 Main 路径明确失败并提示改为前台对话，不永久等待。
+- 请求结束或取消后清除对应待答映射；过期回答明确报错，不转交给后来的请求。
+- 任意终端程序的密码、OAuth 登录、许可证确认或 stdin 提示不自动回复 `yes`。这类程序应
+  使用其非交互参数，或由用户在终端完成；不能把权限确认和业务决策混为一谈。Shell
+  工具保留其现有取消与超时，不新增日志解析或通用交互代理。
+
+## 托管 Runtime 的并行与输出
+
+- 本机和 Agent 管理的 OpenCode 启动配置都显式设置 `snapshot: false`。GoodBuddy 不消费
+  原生自动 Git 快照、快照差异摘要或快照撤销；关闭这条内部路径，避免大行级差异的同步
+  计算阻塞同一原生进程中的其他会话。
+- 文件工具、Shell、原生子代理、工作区 Git 状态和单文件差异保持可用；不新增全局会话
+  队列、请求重放或总执行截止时间。外部 OpenCode Server 的配置不由 GoodBuddy 改写，
+  已运行的旧原生进程也不会热更新配置。
+- Continue 使用 HTTP 传递响应和状态；Electron UtilityProcess 启动后持续排空不用展示的
+  stdout，避免控制台输出填满管道后阻塞宿主。stderr 的有界错误处理、请求取消与进程
+  回收保持不变，不把诊断输出复制进聊天或持久日志。
+- 远端最终启动配置由[远程主机技术设计](../remote-host/technical-design.md)定义，
+  模型桥生成最终配置时同样保留上述快照策略。
+
+## 消息底部请求状态
+
+- 状态属于当前请求，不与顶部 Runtime 的连接中、就绪、不可用混为一谈。提交后先显示
+  “正在准备请求”；没有更具体的活动事件时显示“等待后续进展”，不声称模型正在思考。
+- 本机 OpenCode 只把当前父会话的 `session.status.retry` 映射为等待重试，显示原生
+  `attempt`、计划重试时间和有界脱敏原因；后续 `busy` 才显示已开始重试。其他会话的
+  状态不串入当前消息，不猜测总重试次数，不把 SDK 事件流重连当作模型重试。
+- 显示优先级为待回答、待确认、进行中的上下文压缩、明确的请求状态、待执行或执行中的
+  工具、未完成的子任务、等待后续进展。压缩沿用已有活动块，不重复增加底部提示。
+  正文、推理或工具进展会清除旧状态；子任务更新不覆盖父请求的重试提示。
+- 完成、失败、取消后保留真实终态，迟到的状态事件不能把请求恢复成处理中。底部状态点
+  为静态，不凭请求尚未结束暗示仍有进展；会话列表闪点和发送、停止按钮保持原有行为。
+- Continue、DeepSeek Harness 和远端 ACP 保留其已接入的处理与工具事件，不伪造未接入
+  的原生重试状态。直连模型的重试等待与请求开始文案见
+  [直连模型 UI 设计](../direct-model-agent/ui-design.md#6-错误与通知)；本次不改变任何
+  Runtime 的重试上限、请求重放或取消策略。
+
+实现与真实 Runtime 验证证据见[进度记录](./progress.md)。

docs/features/assistant-workbar/terminal-tabs-prd.md

@@ -0,0 +1,658 @@
+# 助手工作栏多终端页签 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台验证中 |
+| 版本 | 1.2 |
+| 日期 | 2026-09-10 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 界面归属 | [通用助手工作栏与执行空间](./prd.md) |
+| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) |
+| 远程架构 | [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)、[SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md) |
+
+## 1. 文档职责
+
+本文细化助手工作栏中的以下行为：
+
+- 已打开应用以同级 Tab 呈现。
+- Tab 行始终提供“+”入口，用户按需打开应用。
+- 应用通过统一注册表分别声明单实例或多实例、默认打开、可关闭和排序策略。
+- “终端”作为首个多实例应用，自动使用当前项目的本机或托管 SSH 执行空间。
+- 本机与远程交互式终端的生命周期、状态、性能和验收要求。
+
+[通用助手工作栏与执行空间 PRD](./prd.md)
+继续负责工作栏的应用级位置、稳定能力目录、执行空间、范围绑定和总体产品边界。本文不重新
+定义 Host Key、凭据、Agent 安装、Ask/Execute Runtime 或项目持久化契约。
+
+## 2. 背景与当前问题
+
+当前工作栏在聊天页面右侧固定显示“任务中心、工作区、浏览器、成果”四个 Tab。用户不能：
+
+- 通过统一入口按需打开新的工作栏应用。
+- 按应用策略关闭并重新打开可关闭的工作栏应用。
+- 为支持多实例的应用创建第二个独立实例。
+- 在 GoodBuddy 内使用本机或远程 Host 的交互式 Shell。
+
+当前代码已经具备工作栏右侧回流、宽度调整、Tab 键盘导航、SSH Host Key 固定、加密凭据和
+SSH 连接池，但尚不存在工作栏应用实例模型、终端 IPC、终端 Session Manager 或终端模拟器。
+`node-pty` 当前只作为其他 Runtime 的间接依赖被打包，不能视为已经存在用户终端能力。
+
+## 3. 产品定义
+
+### 3.1 工作栏应用
+
+工作栏应用是可以在助手工作栏中打开的一个能力，例如任务中心、工作区、浏览器、成果或
+终端。每项应用通过统一注册表声明：
+
+- 稳定应用 ID。
+- 用户可见名称、图标和说明。
+- `single` 或 `multiple` 实例策略。
+- 是否默认打开、是否必须存在、是否可关闭和是否允许排序；这些属性彼此独立。
+- 创建实例时可用的默认上下文。
+- 当前不可用时的原因和修复入口。
+
+目录中的应用可发现性与实例是否已经打开相互独立。应用不可用时保留入口并说明原因，不以
+隐藏代替状态。
+
+注册表字段如下：
+
+| 字段 | 类型或允许值 | 含义 |
+| --- | --- | --- |
+| `id` | 稳定应用 ID | 关联图标、面板实现和持久化实例 |
+| `label` | 有界文本 | 默认 Tab 名称和目录名称 |
+| `icon` | 稳定图标 ID | 应用目录和 Tab 图标 |
+| `description` | 有界文本 | 目录说明和完整提示 |
+| `instancePolicy` | `single`、`multiple` | 同一应用允许一个还是多个实例 |
+| `defaultContext` | `application`、`current-project`、`current-conversation` | 创建实例时使用的默认范围，不代表实例随后必须跟随 |
+| `visibleAcrossContextSwitches` | boolean | 切换项目或会话后，已打开的 Tab 是否继续留在工作栏中 |
+| `defaultOpen` | boolean | 新布局是否创建默认实例 |
+| `required` | boolean | 布局加载时实例缺失是否必须补回 |
+| `closable` | boolean | 是否渲染关闭入口并接受关闭命令 |
+| `reorderable` | boolean | 是否允许用户改变 Tab 顺序 |
+| `availability` | `available` 或带原因和修复入口的 `unavailable` | 当前能力状态 |
+
+`defaultOpen`、`required` 和 `closable` 不互相推导。例如浏览器默认打开但不是必需实例；任务
+中心和工作区既默认打开又必须存在。`required` 不表示锁定顺序，顺序只由 `reorderable` 控制。
+
+当前五个应用的 `visibleAcrossContextSwitches` 均为 `true`。该属性记录应用目录的显示策略，
+不改变内容归属，也不授予其他会话的 MCP 访问权限；当前没有使用 `false` 的应用，尚未实现
+按上下文隐藏 Tab 的策略。
+
+浏览器在创建时绑定当前 Conversation；切换会话后仍保留原 Tab、选中状态和页面，导航操作
+继续使用原 `targetRef.conversationId`。此时新建浏览器才绑定新会话。默认或旧布局中尚未绑定
+的浏览器在首次使用时绑定活动会话，此后不再随会话切换改绑。终端同样保留创建时执行目标；
+任务中心、工作区和成果的内容继续跟随当前项目。
+
+### 3.2 工作栏 Tab 实例
+
+工作栏 Tab 是应用的一次打开实例。每个实例具有独立 ID、标题、应用类型和状态。Tab 行只
+显示已经打开的实例，不把全部能力同时渲染为 Tab。
+
+实例持久化字段只有 `id`、`appId`、`title` 和可选 `targetRef`。`targetRef` 使用公开引用：
+终端接受 `local` 或 `projectId`，浏览器接受 `conversationId`。Main 签发的 Browser Tab ID、
+Terminal Session ID、元素引用、凭据、路径和运行状态不进入工作栏布局。
+
+### 3.3 终端实例
+
+每个终端 Tab 对应一个独立交互式 Shell Session：
+
+- 本机终端由桌面 Main 进程管理本机 PTY。
+- 远程终端通过现有、已验证的 SSH Host 打开直接 SSH PTY。
+- 不同终端拥有独立 Shell、工作目录、输入、输出、尺寸和结束状态。
+- 创建后固定到当时选择的执行位置，切换项目不会迁移已经运行的终端。
+
+直接 SSH PTY 是用户操作的远程终端，不是连接期临时 GoodBuddy Agent，也不作为 Runtime
+stdio fallback。首期远程终端随 SSH Channel 结束，不提供跨 SSH 或桌面重启的进程恢复。
+
+## 4. 已确认的产品决策
+
+1. 工作栏 Tab 行末尾始终显示“+”按钮。
+2. “+”是普通命令按钮，不是一个 `tab`。
+3. 点击“+”在工作栏内容区显示“新建工作栏应用”选择页；取消后返回原活动 Tab。
+4. 选择应用后创建或激活实例，并关闭临时选择页。
+5. 单实例应用已经打开时，再次选择只聚焦已有实例，不创建重复 Tab。
+6. 多实例应用每次选择都创建新实例。
+7. 终端从首期开始就是多实例应用。
+8. 任务中心和工作区保持单实例、默认打开且不可关闭，分别固定在第一、第二位，`reorderable` 为 `false`。恢复旧布局时也按此规则修正顺序，其余 Tab 保持相对顺序。
+9. 浏览器注册为可关闭的多实例应用，升级后保留一个默认实例；成果保持单实例、默认打开且
+   可关闭。
+10. 用户关闭可关闭实例、切换或重排应用 Tab 后，“+”仍保持可见。
+11. 选择“终端”后不再显示第二层目标选择器。存在当前项目时直接绑定该项目，由 Main
+    根据项目执行空间自动打开本机或托管 SSH Shell；没有当前项目时打开本机 Home Shell。
+12. 远程首期使用直接 SSH PTY。SSH 断线后终端进入“已中断”，重新连接会创建一个新的
+    Shell，不伪装为恢复旧进程。
+13. 工作栏收起、切换主页面或切换 Tab 不终止终端；显式关闭终端 Tab 才终止对应 Shell。
+14. 应用重启不自动启动 Shell。恢复的终端 Tab 显示“会话已结束”，由用户显式重新连接。
+15. 终端是用户交互表面。Ask/Execute 继续约束 Agent Runtime，不把用户键盘操作误判为
+    Agent 工具调用；Agent、自动化和模型不得未经明确用户操作向终端注入输入。
+16. 工作栏继续按上位 PRD 提升为应用级容器；切换聊天、知识、魔法笔记或活动记录等主页面
+    不销毁 Tab 实例或终端 Session。
+
+## 5. 目标
+
+### 5.1 用户目标
+
+- 在工作栏中随时通过“+”发现并打开应用。
+- 同时打开多个本机或远程终端，并通过 Tab 快速切换。
+- 清楚知道每个终端运行在本机还是哪个远程 Host、当前目录和连接状态。
+- 在终端断线、退出或目标失效后获得准确状态和明确恢复操作。
+- 使用键盘完成打开应用、切换 Tab、操作终端和关闭实例。
+
+### 5.2 产品目标
+
+- 用一个可扩展的应用注册表统一单实例与多实例行为。
+- 把现有 Tab 迁移到统一实例模型，同时保持任务中心和工作区始终存在，并允许浏览器和终端
+  创建多个实例。
+- 建立真实的 Main/Preload/Renderer 终端生产链路，而不是用普通文本框模拟终端。
+- 复用现有 SSH Host Key、凭据和连接池，不建立第二套 Host 管理。
+- 保持终端输入输出有序、响应流畅、内存有界，并可靠清理本机和远程资源。
+
+## 6. 非目标
+
+- 不把 GoodBuddy 改造成完整 IDE。
+- 不唤起 Windows Terminal、Terminal.app 等外部终端窗口代替内嵌终端。
+- 不扫描或导入用户全部 SSH config、目录、Shell profile 或命令历史。
+- 不支持任意 `ProxyCommand`、端口转发或 SSH Agent Forwarding。
+- 不在打开远程终端时安装、更新或修复 GoodBuddy Agent。
+- 不把 Agent 工具调用、Runtime 日志或自动化输出伪装成用户终端。
+- 不允许 Renderer 直接访问 PTY、ChildProcess、SSH Client、凭据或 Node API。
+- 首期不提供终端协作、录制、云同步、Shell Session 复用、tmux 管理或跨设备恢复。
+- 首期不实现底部停靠和独立窗口；本文保留兼容模型，后续按工作栏总 PRD 扩展。
+- 首期不通过 GoodBuddy Agent 恢复远程终端，也不为终端复制 Runtime transcript、
+  `outcome_unknown` 或模型调用恢复协议。
+
+## 7. 信息架构与“+”交互
+
+### 7.1 Tab 行
+
+```text
+┌──────────────────────────────────────────────┐
+│ 任务中心 │ 工作区 │ 终端 1 │ 终端 2 │ + │
+├──────────────────────────────────────────────┤
+│ 当前活动实例内容                              │
+└──────────────────────────────────────────────┘
+```
+
+- 已打开实例位于一个语义化 `tablist` 中。
+- 每个实例使用独立 `tab` 和 `tabpanel`。
+- “+”固定在 Tab 行末尾，但位于 `tablist` 之外。
+- Tab 过多时实例区域单行横向滚动，“+”保持可见；不换行、不自动隐藏实例。
+- 终端 Tab 默认使用递增标题，例如“终端 1”“终端 2”；状态栏持续显示项目、Host、
+  工作目录和 Shell。用户可以重命名终端。
+- 当前 Tab 同时使用连续内容表面、选中边框、顶部强调线、图标和较高字重，不能只靠文字颜色。
+- Tab、关闭按钮和“+”入口沿用共享控件圆角；终端面板外框和终端顶部工具栏按钮使用直角，
+  保持紧凑的停靠式终端界面。
+- 只有可关闭实例渲染 Tab 关闭按钮。关闭按钮默认不争夺视觉注意力，仅在鼠标悬停或键盘
+  焦点进入对应 Tab 时出现；
+  粗指针或无悬停设备始终显示，出现与隐藏不得引发布局位移。
+
+### 7.2 新建应用选择页
+
+点击“+”后：
+
+1. 保留当前实例及其运行状态。
+2. 在工作栏内容区显示“新建工作栏应用”。
+3. 列出稳定应用目录，每项显示名称、说明、单/多实例提示和当前可用状态。
+4. 初始焦点进入第一个可用应用；Escape 或“取消”返回原活动实例和“+”按钮。
+5. 选择单实例应用时，若实例已存在，直接聚焦该 Tab；任务中心和工作区始终走此路径。
+6. 选择浏览器时创建绑定当前 Conversation 的新 Browser Tab；没有活动 Conversation 时创建
+   待选择目标的空实例。
+7. 选择终端时直接解析当前项目执行空间，创建新 Tab 并聚焦终端输入，不再要求用户
+   重复选择本机或远程目标。
+
+选择页是“+”触发的临时界面，不进入实例顺序，不持久化，也不占用一个普通 Tab。
+
+### 7.3 首期应用注册表
+
+| 应用 | 实例策略 | 默认上下文 | 默认打开 | 必须存在 | 可关闭 | 可排序 | 再次从“+”选择 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 任务中心 | `single` | 当前项目 | 是 | 是 | 否 | 否 | 聚焦已有 Tab |
+| 工作区 | `single` | 当前项目 | 是 | 是 | 否 | 否 | 聚焦已有 Tab |
+| 浏览器 | `multiple` | 当前 Conversation | 是，一个实例 | 否 | 是 | 是 | 每次创建新 Tab |
+| 成果 | `single` | 当前项目 | 是 | 否 | 是 | 是 | 聚焦已有 Tab |
+| 终端 | `multiple` | 当前项目 | 否 | 否 | 是 | 是 | 每次创建新 Tab |
+
+实例策略、默认状态和可关闭策略都是应用注册数据，不能分散硬编码在多个点击处理器中。
+
+新建浏览器使用独立编号标题，避开已有名称；关闭后再次新建也不产生重名。恢复布局保留已保存
+的标题。会话名称用于标识归属，不替代浏览器实例名称。新建页面为空白页，同会话 Cookie 共享
+不表示复用旧页面或导航历史。
+
+### 7.4 Tab 操作
+
+- 点击或使用方向键切换实例不会暂停或终止后台实例。
+- 支持左右方向键、Home、End 和 roving `tabindex`。
+- 任务中心和工作区没有关闭按钮，也不响应关闭快捷命令。
+- 关闭可关闭的非活动 Tab 后焦点保持在当前活动 Tab。
+- 关闭可关闭的活动 Tab 后激活右侧相邻实例；没有右侧实例时激活左侧实例。任务中心和工作区
+  始终存在，因此正常布局不会进入零实例空状态。
+- 关闭正在运行的终端需要确认“关闭终端将结束 Shell 及其子进程”；取消是初始焦点。
+- 已退出或已中断的终端可以直接关闭，不重复确认。
+
+## 8. 终端创建流程
+
+### 8.1 自动目标解析
+
+- 当前项目是本地项目时，创建目标为公开 Project ID，Main 从权威项目记录解析本机根目录。
+- 当前项目是托管 SSH 项目时，创建目标仍为公开 Project ID，Main 再解析项目 Host、
+  固定 Host Key、凭据和远端根目录。
+- 没有当前项目时使用本机目标和当前用户 Home。
+- Host 未验证、凭据不可用或不支持交互式 Shell 时，终端 Tab 就地显示失败原因和恢复入口，
+  不静默切换到本机或其他 Host。
+
+### 8.2 本机终端
+
+- 当前项目是本地项目时，默认工作目录为项目根目录。
+- 没有本地项目目标时，默认工作目录为当前用户 Home。
+- Windows 优先使用可用的 PowerShell 7，其次 Windows PowerShell，最后使用系统
+  `COMSPEC`。
+- macOS 和 Linux 优先使用当前用户有效的 `$SHELL`，不可用时使用平台常规 Shell fallback。
+- 首期自动选择默认 Shell，不提供任意可执行文件路径输入。
+- Main 只向 Shell 传递正常交互所需的筛选环境，不注入模型 API Key、GoodBuddy 内部
+  Token 或其他产品凭据。
+
+### 8.3 远程终端
+
+- 当前项目是托管 SSH 项目时，自动使用项目 Host 和远端项目根目录。
+- Main 复用现有 Host store、完整 Host Key 固定、认证方式和 SSH connection pool。
+- 远端通过 SSH PTY 打开账号的登录 Shell，并支持输入、ANSI 输出和窗口尺寸同步。
+- 活动终端持有专用 Channel lease，不得被连接池空闲回收。
+- 不把密码、私钥、认证头或 GoodBuddy 模型凭据发送给 Renderer 或写入终端环境。
+- Host 地址、用户、凭据或 Host Key generation 变化时，旧 Session 进入“已中断”，新建
+  Session 必须使用 Host store 中的当前身份。
+
+### 8.4 创建结果
+
+创建成功后：
+
+- 新 Tab 插入当前活动 Tab 右侧并立即激活。
+- 焦点进入终端输入区域。
+- 状态栏显示“本机”或 Host 名称、工作目录、Shell 和连接状态。
+- 终端尺寸使用内容区计算出的首个有效 `cols/rows`，不是固定默认值覆盖实际布局。
+
+创建失败时在终端 Tab 保留错误上下文并提供重试；不得留下不可回收 Session 或显示为已经连接。
+
+## 9. 终端交互与状态
+
+### 9.1 基础交互
+
+首期支持：
+
+- 真实 TTY 输入与 ANSI 输出。
+- 中文输入法、组合字符和常规键盘快捷键。
+- 复制、粘贴、全选、搜索、清屏和滚动。复制与粘贴通过桌面 Main 进程访问系统文本剪贴板，
+  不依赖 Renderer 的浏览器剪贴板权限。
+- 工作栏宽度或窗口尺寸变化后的 PTY resize。
+- 终端重命名。
+- 显式关闭、退出后重新打开和远程中断后重新连接。
+
+浏览器原生页面快捷键与终端按键冲突时，终端聚焦期间优先交给终端；应用级保留快捷键必须
+有明确规则和可访问说明。
+
+### 9.2 状态模型
+
+```ts
+type TerminalSessionState =
+  | 'starting'
+  | 'running'
+  | 'exited'
+  | 'interrupted'
+  | 'closing'
+  | 'failed'
+```
+
+- `starting`：正在创建本机 PTY 或 SSH Channel。
+- `running`：允许输入和 resize。
+- `exited`：Shell 正常或带退出码结束，显示退出码或信号。
+- `interrupted`：远程连接、Host identity 或桌面生命周期导致会话失效。
+- `closing`：已拒绝新输入，正在回收进程或 Channel。
+- `failed`：Session 未成功开始或发生不可恢复错误。
+
+高频输出不逐行进入 live region。只播报连接成功、连接失败、已中断和 Shell 已退出等重要
+状态变化。
+
+### 9.3 重新连接
+
+- 本机或远程 Session 结束后，“重新打开”在同一 Tab 中创建全新的 Shell Session。
+- 远程断线后的按钮文案为“重新连接并新建 Shell”，不能暗示恢复旧进程。
+- 新 Session 使用 Host store 和项目中的当前有效配置，不复用旧 Host identity。
+- 重新连接前清空旧终端画面，并保留可见说明“这是新的 Shell 会话”。
+
+## 10. 实例、Session 与持久化
+
+工作栏实例与运行 Session 分离：
+
+```ts
+type WorkbarAppDefinition = {
+  id: 'tasks' | 'workspace' | 'browser' | 'results' | 'terminal'
+  label: string
+  icon: WorkbarAppDefinition['id']
+  description: string
+  instancePolicy: 'single' | 'multiple'
+  defaultContext: 'application' | 'current-project' | 'current-conversation'
+  defaultOpen: boolean
+  required: boolean
+  closable: boolean
+  reorderable: boolean
+  availability:
+    | { state: 'available' }
+    | { state: 'unavailable'; reason: string; remedy: string }
+}
+
+type WorkbarTabInstance = {
+  id: string
+  appId: WorkbarAppDefinition['id']
+  title: string
+  targetRef?:
+    | { type: 'local' }
+    | { type: 'project'; projectId: string }
+    | { type: 'conversation'; conversationId: string }
+}
+
+type WorkbarLayoutPreferences = {
+  instances: WorkbarTabInstance[]
+  activeInstanceId: string | null
+  expanded: boolean
+  dock: 'right'
+  widthRatio: number
+  taskScope: 'current-project' | 'global' | 'all-projects'
+}
+```
+
+- 持久化工作栏打开状态、Tab 顺序、活动实例、应用 ID、自定义标题、公开目标引用和宽度比例。
+- 加载布局时根据 `required` 补回缺失实例，并拒绝重复的单实例应用；应用策略不写入实例
+  数据，避免持久化状态覆盖注册表。
+- `reorderable` 已进入共享契约；当前 Tab 壳层尚未提供拖放或键盘重排，不能把声明属性视为
+  已完成的排序功能。
+- 不持久化终端正文、未执行输入、凭据、环境变量、PTY PID、SSH Channel 或派生 Host
+  identity。
+- Main 创建终端后返回新的不透明 Session ID；Renderer 不能选择 PID 或 Channel。
+- 应用重启恢复终端 Tab 描述，但状态为“会话已结束”，不自动建立 SSH 连接或启动本机
+  Shell。
+- 运行期间切换项目不会改变已经创建的终端目标。用户需要新目标时通过“+”创建新终端。
+
+## 11. 生命周期与关闭语义
+
+| 用户或系统动作 | Tab | Shell Session |
+| --- | --- | --- |
+| 切换 Tab | 保留 | 继续运行 |
+| 收起工作栏 | 保留 | 继续运行，停止非必要高频 UI 工作 |
+| 切换主页面 | 保留 | 继续运行 |
+| 切换项目 | 保留并显示原目标 | 继续在原目标运行 |
+| 关闭运行中的终端 Tab 并确认 | 删除 | 结束 Shell 和子进程 |
+| Shell 自行退出 | 保留 | 标记 `exited` |
+| SSH 断线 | 保留 | 标记 `interrupted` |
+| 删除或修改目标 Host | 保留 | 关闭旧 Channel 并标记 `interrupted` |
+| Renderer 销毁或应用退出 | 下次恢复描述 | 在总关闭截止时间内回收 |
+
+关闭操作必须安全处理竞态。Main 停止接受新输入，关闭 stdin/Channel，先正常结束，再在既有
+应用关闭截止时间内升级清理；一个卡死终端不能无限阻塞应用退出。关闭后的迟到 ACK 视为已
+完成，input、resize 或重复 close 返回 Session 不存在，不操作其他 Session。
+
+## 12. 技术生产路径
+
+### 12.1 Shared
+
+新增独立终端契约，至少覆盖：
+
+- `create`：目标引用、初始 `cols/rows`。
+- `write`：Session ID 和有界输入。
+- `resize`：Session ID、`cols/rows`。
+- `close`：Session ID。
+- `snapshot`：目标、状态、Shell、目录和终态。
+- `event`：带 Session ID 和单调序号的输出、状态、退出与错误事件。
+
+所有 Schema 使用 Zod 严格校验，并限制 ID、标题、输入、尺寸、事件块、会话数和缓冲字节。
+
+### 12.2 Main
+
+新增统一 `TerminalSessionManager`：
+
+- Session 按所属 `webContents` 和不透明 ID 隔离。
+- 将现有间接 `node-pty` 提升为 GoodBuddy 直接生产依赖，并用于启动平台 Shell。
+- 远程使用现有 `SshConnectionPool` 打开交互式 PTY Channel。
+- 统一处理 write、resize、close、exit、连接中断和应用退出。
+- 终端输出只发送给所属窗口。
+- 复用现有子进程树终止思路，但针对 PTY 验证 Windows 与 POSIX 的实际回收行为。
+
+### 12.3 Preload 与 IPC
+
+- `DesktopApi` 只暴露显式 `terminal.create/write/resize/close/getSnapshot/onEvent`。
+- Main Handler 对每个调用执行可信 sender 检查和共享 Schema parse。
+- Preload 管理事件订阅释放，不暴露 `ipcRenderer`、PTY、SSH Client 或 Node API。
+
+### 12.4 Renderer
+
+- 使用 `@xterm/xterm` 6 和官方 fit/search addon 处理 ANSI、光标、选择、IME、搜索、
+  滚动和可访问输入，不自行实现终端转义状态机。
+- 终端首次打开时按需加载；支持 WebGL2 时使用官方 WebGL renderer，初始化失败或 Context
+  丢失时释放 WebGL addon 并回退到 xterm 默认 renderer。
+- xterm 使用解析后的跨平台系统等宽字体栈，不能把未解析的 CSS `var(...)` 交给 Canvas。
+- Tab 壳层只管理实例与焦点，不持有 PTY 或 SSH 对象。
+- `ResizeObserver` 只在有效非零布局后发送去重后的 `cols/rows`。
+- 组件卸载时退订画面事件；只有显式关闭终端才调用 Session close。
+- 终端样式复用全局语义颜色、边框、焦点和字体令牌，不创建另一套工作台设计系统。
+
+### 12.5 输出顺序与背压
+
+- 输出按 Session 分区并携带单调序号。
+- Main 合并小块输出，限制单事件大小、待发送条目和总字节。
+- Renderer 确认已经消费的序号；慢消费者达到上限时暂停 PTY/SSH stream，消费后恢复。
+- 不通过丢弃中间输出维持界面响应，因为丢失字节会破坏终端状态。
+- Renderer 只保留有界滚动历史；清屏不改变 Main Session 生命周期。
+
+## 13. 权限与边界
+
+- 用户终端以当前本机账号或所选 SSH 账号的正常权限运行，不增加额外虚构的 trust tier。
+- Ask/Execute 是 Agent Runtime 模式，不自动改变用户直接操作终端的 OS 权限。
+- UI 必须持续将其标注为“用户终端”，避免被理解为 Ask Runtime 的只读输出。
+- Agent、模型、监督器和自动化不能调用终端 write，也不能把指令注入已有 Session。
+- 终端输出不会自动进入对话上下文、模型 Prompt、成果或活动记录。
+- Renderer 只能引用项目和 Session 的公开 ID；Main 从权威 store 解析目录、Host、凭据和
+  当前 Host identity。
+- 不接受 Renderer 提交任意 Shell 可执行路径、SSH 命令、PID、环境变量集合或原始凭据。
+- 保持 Electron `contextIsolation`、sandbox 和禁用 Renderer Node integration。
+
+## 14. 错误与反馈
+
+- 创建失败、断线、Shell 退出和目标失效保留在终端面板，提供就地重试。
+- 不与全局通知重复显示同一终端错误。
+- 非局部错误，例如无法保存工作栏布局，可以进入应用通知。
+- 错误文案说明发生了什么、当前 Shell 是否仍在运行、用户可以做什么。
+- Host Key 变化沿用现有 Host 管理流程；终端只显示“主机身份已变化，请重新验证”，不在
+  终端内复制凭据或 Host Key 修改流程。
+- 目标不可用时保留 Tab 名称和目标，不静默切换到本机或其他 Host。
+
+## 15. 性能与资源要求
+
+- 工作栏切换和终端输入在正常负载下保持即时反馈，持续输出不能阻塞主界面导航。
+- 同一窗口的活动终端数量必须有明确上限；达到上限时阻止新建并说明先关闭不用的终端。
+- 每个 Session 的输出队列、Renderer 滚动历史和 IPC 单事件均有硬上限。
+- 工作栏不可见时可以降低渲染刷新频率，但不能丢失终端协议字节或暂停 Shell 本身。
+- 应用退出复用现有总清理截止时间，不因终端新增无界等待。
+- 生产构建必须实际加载本机 PTY 原生模块；不能只验证文件存在。
+- 远程终端不能使 SSH connection pool 的空闲项、Channel 或监听器泄漏。
+
+具体数值在共享契约和性能测试中确定，以现有 IPC、窗口和关闭预算为上限，不在多个进程中
+维护不同常量。
+
+## 16. 无障碍与响应式
+
+- Tab 使用 `tablist/tab/tabpanel`；“+”使用带可访问名称“打开工作栏应用”的普通按钮。
+- 应用选择页使用可键盘操作的列表或菜单语义，不使用 `SegmentedControl`；终端没有重复的
+  目标选择页。
+- 每个终端 Tab 的可访问名称包含自定义名称或位置，多个终端不能都只读作“终端”。
+- Tab 关闭后焦点移动到确定的相邻 Tab；取消创建后焦点返回“+”。
+- 工作栏收起后焦点返回唯一工作栏开关，不增加焦点陷阱或遮罩。
+- 终端高频输出不逐行播报；只播报连接、退出、失败和中断。
+- 200% 文字缩放时，目标、Shell、目录、状态和关闭操作仍可访问。
+- Tab 单行横向滚动，终端内容随工作栏尺寸变化并同步 PTY，不把 Tab 换成下拉框。
+- 深色和浅色主题都使用设计系统语义令牌，并保持终端文本、选择和光标可辨。
+
+## 17. 实施顺序与多代理工作包
+
+功能必须以完整的本机和远程用户流程交付。以下是可并行的开发工作包，不表示可以发布只有
+Schema、假数据终端或不可用入口的中间产品。
+
+### 17.1 依赖顺序
+
+```text
+契约冻结
+  ├─ 工作栏实例壳层
+  ├─ 本机 PTY 后端
+  ├─ SSH PTY 后端
+  └─ 终端 Renderer
+          ↓
+单一集成负责人完成 Main/Preload/App 接线
+          ↓
+完整验证、真实 Host 验收与文档同步
+```
+
+### 17.2 文件所有权
+
+| 工作包 | 主要职责 | 建议文件所有权 | 不应修改 |
+| --- | --- | --- | --- |
+| 契约与注册表 | Workbar/Terminal Schema、状态、测试 | 新建 `src/shared/workbar-contracts.ts`、`terminal-contracts.ts` 及测试 | `App.tsx`、`ipc.ts`、Preload |
+| 工作栏壳层 | 动态实例 Tab、“+”、选择页、单/多实例和焦点 | 新建工作栏组件及其测试 | PTY、SSH、Main IPC |
+| 本机终端后端 | 本机 PTY、输入、resize、退出和进程树清理 | 新建 `src/main/terminal/` 本机文件及测试 | Renderer、远程 Agent |
+| SSH 终端后端 | SSH PTY、lease、resize、断线和 Channel 清理 | 新建 `src/main/terminal/` 远程文件及聚焦测试 | 工作栏 UI、Agent 协议 |
+| 终端 Renderer | 模拟器、IME、搜索、复制粘贴、状态栏和 resize | 新建终端组件、样式和测试 | Main、SSH、中心 IPC |
+| 集成 | 依赖、IPC channel、DesktopApi、Preload、Main 注册、`App` 接线与关闭顺序 | `package.json`、lock、`ipc-channels.ts`、`contracts.ts`、`preload/index.ts`、`main/ipc.ts`、`App.tsx` | 不重写各包已验收内部逻辑 |
+| 验收与文档 | E2E、跨平台构建检查、真实 Host、最终文档 | 测试与相关文档 | 不用假实现替换生产路径 |
+
+中心文件只能由集成负责人修改，避免多个代理同时编辑 `App.tsx`、`main/ipc.ts`、
+`shared/contracts.ts`、`preload/index.ts`、`package.json` 和 lockfile。
+
+### 17.3 并行开发门槛
+
+契约负责人先冻结：
+
+- 应用注册和实例策略。
+- Terminal request、snapshot、event 和 error code。
+- Session 所有权和关闭语义。
+- 输出序号、ACK 与容量常量。
+
+其他代理基于冻结契约工作。接口偏差由集成负责人统一修正，不由多个代理分别修改共享中心
+文件。
+
+## 18. 验收标准
+
+### 18.1 工作栏应用与实例
+
+- [ ] Tab 行末始终显示“+”；任务中心和工作区始终存在，因此正常布局不存在零实例状态。
+- [ ] 点击“+”显示稳定应用目录，取消后返回原实例并恢复焦点。
+- [ ] 选择已打开单实例应用只聚焦已有 Tab。
+- [x] 任务中心和工作区默认存在且不可关闭，不渲染关闭按钮，也不响应关闭快捷命令。
+- [x] 连续选择浏览器会创建页面、导航状态和元素引用相互独立的浏览器 Tab。
+- [x] 连续选择终端会创建多个互相独立的终端 Tab。
+- [ ] 关闭可关闭实例、切换和重排实例后，“+”仍保持可用。
+- [ ] Tab 溢出时单行横向滚动，不隐藏“+”或把 Tab 换成下拉框。
+- [x] 关闭可关闭的活动 Tab 后激活正确的相邻 Tab 并恢复焦点。
+- [x] 当前 Tab 的背景、边框、顶部指示和字重清晰可辨；关闭按钮仅在悬停、焦点或无悬停
+  设备上出现，且不引发布局位移。
+- [x] 升级后任务中心、工作区、一个浏览器实例和成果按默认布局打开；布局恢复会补回缺失的
+  任务中心与工作区。
+- [ ] 在所有主要页面都能打开工作栏；切换主要页面不会销毁 Tab 实例或终端 Session。
+
+### 18.2 本机终端
+
+- [x] 从“+ → 终端”直接打开当前本机项目的真实交互式 Shell，工作目录为项目根。
+- [ ] 没有项目时从用户 Home 打开本机 Shell。
+- [ ] `pwd` / `Get-Location`、交互输入、ANSI 颜色、中文 IME、复制和粘贴工作正常。
+- [ ] 调整工作栏和窗口尺寸会更新 PTY `cols/rows`，全屏 TTY 程序正确重绘。
+- [ ] 多个本机终端的输入、输出、目录和退出状态互不串线。
+- [ ] Shell 有活动子进程时关闭 Tab，确认后回收完整进程树；取消后 Session 继续运行。
+- [ ] 退出后的 Tab 显示退出码，并可在同一 Tab 显式创建新 Shell。
+
+### 18.3 远程终端
+
+- [ ] 从“+ → 终端”直接为当前托管 SSH 项目打开真实 SSH PTY。
+- [ ] 终端持续显示 Host、远端目录、Shell 和连接状态。
+- [ ] 使用现有固定 Host Key 和已存凭据，Renderer、日志和命令参数不出现凭据。
+- [ ] 输入、ANSI、中文、复制粘贴和 resize 在真实 Host 上工作正常。
+- [ ] 活动远程终端不会被 SSH connection pool 空闲回收。
+- [ ] SSH 断线立即标记“已中断”并拒绝继续输入，不显示为仍在运行。
+- [ ] “重新连接并新建 Shell”明确创建新 Session，不宣称恢复旧远端进程。
+- [ ] Host 删除、地址/用户/凭据或 Host Key generation 变化会中断旧 Session；新 Session
+  使用当前 Host identity。
+
+### 18.4 生命周期、性能和边界
+
+- [ ] 收起工作栏、切换主页面、切换 Tab 或切换项目不会终止已有终端。
+- [ ] 终端不会随项目切换静默迁移执行位置。
+- [ ] 应用重启只恢复终端 Tab 描述，不自动连接或启动 Shell。
+- [ ] 输出顺序在持续大输出下保持正确，Main 和 Renderer 内存保持有界，主界面仍可操作。
+- [ ] 慢 Renderer 触发暂停和恢复，不丢弃中间终端字节。
+- [ ] Renderer 不获得 raw PTY、ChildProcess、SSH Client、PID、环境变量或凭据。
+- [ ] Agent、模型和自动化不能向已有用户终端注入输入。
+- [ ] 窗口销毁和应用退出在既有关闭截止时间内回收本机进程、SSH Channel 和监听器。
+- [ ] 重复 close、迟到 input/resize 和退出竞态不会操作其他 Session 或导致进程泄漏。
+
+### 18.5 设计、无障碍和跨平台
+
+- [ ] 仅使用键盘可以打开应用、创建浏览器和终端、切换 Tab、关闭可关闭 Tab、复制、粘贴及
+  重新连接。
+- [ ] Tab、“+”、选择页和关闭确认使用正确语义并有可见焦点。
+- [ ] 终端输出不逐行进入 live region，关键状态变化可被辅助技术感知。
+- [ ] 浅色、深色、200% 文字缩放和窄窗口下可以完成核心流程。
+- [ ] Windows、macOS、Linux x64 和 Linux arm64 的正式构建实际启动本机 PTY。
+- [ ] 远程链路在共享 Linux x64 真实 Host 上完成创建、输入、resize、断线、重连、关闭和
+  应用退出验证；若 Host 不可达，远程终端不得标记为完成。
+
+## 19. 验证计划
+
+### 19.1 自动验证
+
+- 共享 Zod Schema 和边界值测试。
+- 单/多实例、默认打开、可关闭和排序策略，以及 Tab 顺序、关闭焦点和“+”选择页组件测试。
+- 任务中心与工作区缺失时的布局修复、关闭命令拒绝和焦点保持测试。
+- 浏览器多实例的页面隔离、Conversation 匹配和快捷入口去重测试。
+- 本机 PTY Session Manager 的输入、resize、退出、幂等关闭和进程树测试。
+- SSH PTY 的 Host identity、lease、断线、resize 和关闭测试。
+- Main trusted sender、Session 所有权、IPC 输入边界和事件路由测试。
+- Terminal Renderer 的 IME、键盘、ResizeObserver、订阅释放和状态测试。
+- `npm test`
+- `npm run typecheck`
+- `npm run lint`
+- `npm run build`
+
+### 19.2 真实路径验证
+
+- 在当前开发平台通过产品 UI 完成本机终端全流程。
+- 在共享 Linux x64 Host 通过现有 Host 配置完成远程终端全流程。
+- 真实运行需要 TTY 的程序，验证 ANSI、光标和 resize，不只运行非交互命令。
+- 持续输出并主动减慢 Renderer 消费，验证背压和内存上限。
+- 分别在本机和远程启动带子进程的命令，关闭 Tab 和应用后核对无 GoodBuddy 所属遗留资源。
+- 生产构建在各受支持平台实际加载 PTY 原生模块，不以单元测试或包内文件存在代替。
+
+### 19.3 当前开发验证记录
+
+2026-09-01 已通过生产 `SshConnectionPool` 和 `createSshTerminalSession` 在共享 Linux x64
+Host 完成直接 SSH PTY 验证：使用已有固定 Host Key 和测试凭据，以远端项目目录启动登录
+Shell，验证交互输入、ANSI、UTF-8 中文、`80×24` 到 `101×37` resize、连接销毁后进入
+`interrupted`、重新连接创建新 Shell，以及 Session close 和 connection pool dispose
+回收远端 Shell。验证只创建一个
+`$HOME/.goodbuddy/terminal-smoke-<UUID>` 临时目录，结束后已删除并确认无遗留 Shell 进程。
+
+同日使用最新生产构建完成工作栏视觉检查：活动 Tab 使用连续内容表面、顶部强调线和应用
+图标；关闭按钮默认不可见，悬停后以 overlay 显示且 Tab 宽度不变；横向滚动继续可用但不
+显示滚动条，“+”保持独立可见。
+
+本记录不替代尚未勾选的完整产品 UI、剪贴板、macOS、Linux arm64 和各平台本机 PTY 验收。
+
+本 PRD 不改变 Agent 协议，因此首期远程终端无需 Agent package 更新。若实现期间改为
+Agent-owned PTY，必须先修订本文的远程生命周期和恢复语义，并按 Agent 开发规则在共享
+Linux x64 Host 验证当前源码或候选包。
+
+## 20. 相关文档职责
+
+- [通用助手工作栏与执行空间 PRD](./prd.md)：
+  工作栏应用级位置、稳定能力目录、执行空间和总体范围。
+- 本文：持久“+”、应用实例策略、工作栏动态 Tab、自动项目目标、本机与直接 SSH 多终端。
+- [统一界面设计系统](../../../UI-DESIGN.md)：Tab、菜单、布局、主题、焦点和无障碍规则。
+- [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)：
+  Host Key、凭据、连接池、Agent 和远程项目现状。
+- [SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md)：
+  Host 保存、环境准备和项目使用之间的职责。

docs/features/computer-control/README.md

@@ -0,0 +1,11 @@
+# 电脑控制
+
+电脑控制包含 GoodBuddy 对浏览器和客户端桌面能力的产品实现与平台适配状态。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [功能进度](./progress.md) | 当前已实现能力、缺陷修复、平台限制和验证状态 |
+
+当前只有进度文档；产品需求、功能逻辑、UI 和技术设计尚未从历史实现记录中独立整理。

docs/features/computer-control/progress.md

@@ -1,6 +1,14 @@
 # GoodBuddy 电脑控制开发进度
 
-最后更新：2026-08-05
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档类型 | 实施进度 |
+| 状态 | 持续更新 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-03 |
+| 适用能力 | 内置浏览器与客户端电脑控制 |
 
 ## 范围
 
@@ -9,19 +17,20 @@ Linux x64 和 Linux arm64。
 
 ## 已完成
 
-### 直连模型与浏览器
+### Runtime 与浏览器
 
 - 已实现宿主进程拥有的隔离浏览器服务。
 - 使用 Electron 自带 Chromium 和 CDP，不下载额外浏览器。
 - 已实现导航、可访问性快照、点击、输入、选择、返回和有界截图工具。
-- 浏览器工具只在直连模型的 Execute 模式中提供；用户选择 Execute 即授权
-  本次交互运行，不再逐个弹出 GoodBuddy 工具审批。
+- 浏览器工具作为 GoodBuddy 内置能力，可分别分配给直连模型、GoodBuddy 管理的
+  OpenCode 和 Continue；只在 Execute 模式中提供。用户选择 Execute 即授权本次
+  运行，不再逐个弹出 GoodBuddy 工具审批。
 - 支持当前设备可连接的 HTTP、HTTPS、公网、内网、本机和元数据地址，
   导航及重定向仍经过 DNS 解析和目标地址固定。
 - 已实现回环过滤代理、下载和文件选择器阻止、权限拒绝、会话取消、
   空闲回收和应用退出清理。
-- 直连模型工具循环已提高到适合浏览器任务的有界上限，并包含重复调用和
-  无进展保护。
+- 直连模型工具循环不设置工具次数或模型轮次配额；取消、请求超时、工具结果大小和
+  累计输出边界继续防止失控执行。
 
 ### MCP
 
@@ -51,11 +60,18 @@ Linux x64 和 Linux arm64。
 
 ### 设置与安全边界
 
-- 能力存储已迁移到版本 2。
-- 已增加电脑控制能力卡片、诊断、托管浏览器配置元数据、IPC 和 preload
-  契约。
-- 电脑控制能力默认关闭；启用、配置变更和本地数据清除会替换或清理相关
-  Runtime 和会话。
+- 能力存储已迁移到版本 6。版本 2 至 5 中原有的浏览器启停状态会迁移到
+  `builtin-browser`，已有启用状态不丢失；默认分配给直连模型、GoodBuddy 管理的
+  OpenCode 和 Continue。
+- 内置浏览器位于“内置 MCP”，与知识库、笔记和 GoodBuddy 配置一样提供独立启停、
+  Runtime 分配和工具清单；DeepSeek Harness 持续显示为不支持。
+- 浏览器开关只控制 Agent 工具访问。关闭后，任何 Runtime 都不会获得浏览器工具，
+  但用户仍可在浏览器工作栏中手动前往、返回、刷新、停止加载、交互和关闭浏览器。
+  开启后，已分配 Runtime 可在 Execute 模式直接使用，不逐次询问。
+- 尚未实际参与浏览器执行的命名配置已从界面隐藏；底层旧数据和兼容接口继续
+  保留，不删除用户已有记录。
+- “电脑控制”只显示实际操作客户端电脑的能力。能力启用、配置变更和本地
+  数据清除仍会替换或清理相关 Runtime 和会话。
 
 ## 本轮已修复缺陷
 
@@ -76,15 +92,28 @@ Linux x64 和 Linux arm64。
 
 ### P0：右侧没有浏览器实时画面，已修复
 
-浏览器窗口默认使用 `show: false`，但 BrowserService 现在从模型实际操作的同一
-会话捕获页面帧，并通过受限 IPC 发送状态、当前 URL 和约 220KB 的 JPEG 画面。右侧工作栏
-新增“浏览器”页签；活动对话启动浏览器时会自动打开该页签，并显示创建中、
-加载中、操作中、用户交互中、就绪、失败和已停止状态。用户可点击“交互”打开
-同一会话的子窗口辅助 Agent；交互时主窗口暂时禁用，关闭时先刷新最终画面再将
-浏览器窗口最小化，页面和会话继续保留。用户也可立即停止当前对话的浏览器会话。
+早期版本通过同一浏览器会话的 JPEG 帧提供预览。当前工作栏直接嵌入 Agent 操作的原生
+`WebContentsView`，不再自动截图或传输预览帧，也不再用独立交互窗口阻塞主界面。
+页面显示、标签页归属、失败重试和显式截图的当前规则统一见
+[浏览器多实例技术设计](../assistant-workbar/browser-tabs-technical-design.md)；
+该路径的最新验证证据见[工作栏进度](../assistant-workbar/progress.md)。
 
-当前实现按导航、快照、点击、输入、选择、返回和截图操作刷新画面，而不是创建
-第二个预览浏览器，因此显示内容与模型受控页面一致。
+### 已实现：浏览器工具栏
+
+浏览器 Tab 顶部已增加“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”工具栏。
+它继续操作 Agent 在当前 Conversation 中使用的同一浏览器会话；用户导航会有意改变 Agent
+下一步看到的页面。前往、返回和刷新通过 `BrowserService` 与 Agent 浏览器操作串行执行，
+不会创建第二套 Renderer 导航路径。
+
+工具栏状态以浏览器提交后的权威 URL、是否加载中、能否返回和会话活动状态为准；地址输入
+在用户编辑期间保留本地草稿，不被状态刷新覆盖；提交未带 HTTP(S) 协议的裸域名时会自动添加
+`http://`。创建中、Agent 操作中和完整交互窗口期间禁用其余工具栏控件，但活动导航仍可用
+“停止加载”中断。停止加载只取消页面加载，不关闭浏览器，也不释放 Runtime 上下文；原“停止
+浏览器”会话生命周期操作已统一标为“关闭浏览器”，并在视觉和文案上与停止加载清楚区分。
+
+活动 Conversation 尚无浏览器会话时，可直接从地址栏输入 URL 并“前往”，通过浏览器组件
+可用性检查和同一 URL 策略创建会话。该手动路径不读取 Agent 浏览器开关。实现复用现有每
+Conversation 串行队列和有界状态，不引入恢复、版本化或第二套会话框架。
 
 ### P0：百度输入时元素引用失效，已修复
 
@@ -125,23 +154,34 @@ Linux x64 和 Linux arm64。
 区分代理、分区、窗口、CDP 初始化、DNS 或页面导航失败。需要增加有界、脱敏的
 阶段错误码，并保留用户可执行的修复建议。
 
-### P1：命名浏览器配置尚未用于执行
+### P1：命名浏览器配置尚未用于执行，界面已隐藏
 
-设置中的命名浏览器配置当前只保存未来托管隔离所需的元数据。实际执行仍使用
-每个会话随机创建的临时分区，不复用登录状态。
+命名浏览器配置当前只保存未来托管隔离所需的元数据，实际执行仍使用每个会话
+随机创建的临时分区，不复用登录状态。为避免用户误以为该配置已经生效，设置
+界面暂不显示创建、选择、重命名或删除入口；底层数据与兼容接口继续保留。
 
 ## 下一步顺序
 
-1. 在便携版真实模型流程中继续验证返回、取消和右侧画面刷新。
+1. 在便携版真实模型流程中继续验证 OpenCode、Continue 的导航、返回、取消和右侧画面刷新。
 2. 再设计命名隔离 Profile 的持久登录态、引用和清理策略。
 3. 分别实现并真机验证 Windows UIA、macOS AX 和 Linux 原生适配器。
 
 ## 最近验证
 
-- `npm test`：591 项通过，6 项跳过。
+- `npm test`：3496 项通过，53 项跳过。
 - `npm run typecheck`：通过。
 - `npm run lint`：通过。
 - `npm run build`：通过。
+- `GOODBUDDY_RUN_RUNTIME_E2E=1 ... -t "calls the assigned built-in browser
+  through bundled OpenCode"`：通过，真实模型上报 2 次模型调用，OpenCode 经请求级
+  GoodBuddy MCP 调用 `browser_navigate` 并保留正确 Conversation 归属。
+- `GOODBUDDY_RUN_RUNTIME_E2E=1 ... -t "calls the assigned built-in browser
+  through bundled Continue"`：通过，Continue 经同一路径调用 `browser_navigate` 并
+  返回预期结果；当前 Continue Host 为该完整工具轮次上报 1 条聚合模型用量事件。
+- 聚焦的能力迁移、网关、IPC、设置界面测试共 234 项通过。其中覆盖 Agent 浏览器
+  开关关闭时用户手动浏览器操作仍可用。
 
 以上自动化结果覆盖协议、安全边界和模拟驱动，不替代真实 Electron
 BrowserWindow/WebContentsView、目标网站和目标 Linux 桌面环境的集成验证。
+本轮曾尝试用隔离用户目录启动第二个 Electron 实例，但当前已运行的正式 GoodBuddy
+单实例锁阻止了该实例继续运行；未关闭或附着用户正在使用的正式实例。

docs/features/continuous-learning/README.md

@@ -0,0 +1,11 @@
+# 持续学习
+
+持续学习定义 GoodBuddy 如何从运行结果、评估证据和人工反馈中形成可验证的改进闭环。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [持续学习与评估门 PRD](./prd.md) | 产品目标、学习边界、评估门和验收要求 |
+
+当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。

docs/features/continuous-learning/prd.md

@@ -0,0 +1,410 @@
+# 持续学习与评估门 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中，远期能力 |
+| 版本 | 0.3 |
+| 日期 | 2026-08-19 |
+| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../parallel-experiments/prd.md)、[分区记忆 PRD](../memory/prd.md) |
+
+## 1. 背景
+
+智能心跳可以生成摘要、后续任务和记忆候选，但这还不是完整学习。它与分区记忆的协同尚未
+实施，也不承担持续学习、模式挖掘或自动改进：
+
+- 候选是否改善未来行为没有评估。
+- 一条反思是否会被检索和使用并不确定。
+- 没有 Baseline、回放集、Shadow、晋升和回滚。
+- 没有持续监控候选生效后的收益与退化。
+- 如果允许系统直接修改 Prompt、Skill 或规则，可能发生静默劣化。
+
+持续学习必须建立为可观察、可评估、可批准、可回滚的闭环，而不是“让模型自动改自己”。
+
+## 2. 产品定义
+
+```text
+Observe
+  → Propose candidate
+  → Validate structure and safety
+  → Evaluate against baseline
+  → Shadow
+  → Promote with approval
+  → Monitor
+  → Keep, revise, rollback or archive
+```
+
+学习产物只有在改变未来行为后才算生效；只保存一条 Reflection 仍属于记忆候选。
+
+## 3. 已确认的产品决策
+
+1. 评估门必须先于任何自动应用能力上线。
+2. 新候选默认 `candidate`，通过离线评估后先进入 `shadow`。
+3. 第一阶段只允许人工晋升。
+4. 每次晋升必须记录 Baseline、候选、评估结果、作用域和回滚版本。
+5. 学习不能修改安全边界、工具审批、目录权限、沙箱或 Electron 配置。
+6. 失败案例和用户负反馈只作为评估数据，不直接成为新规则。
+7. 回放案例必须脱敏、版本化，并得到用户明确选择或来自仓库公开样例。
+8. 模型评估不是唯一真值，优先使用确定性验收和人工反馈。
+9. 生效后的候选继续监控，发生退化可自动停用，但不能自动换上另一个候选。
+10. 没有足够证据时保持 `inconclusive`，不强行晋升。
+
+## 4. 学习产物
+
+首期只支持：
+
+| 产物 | 作用 | 是否可自动应用 |
+| --- | --- | --- |
+| Memory | 改善相关上下文召回 | 否，人工确认 |
+| Automation Template | 改善目标、步骤、提示或预算默认值 | 否，创建新草稿 |
+| Prompt Variant | 用于实验比较 | 否 |
+| Rubric | 改善评估标准 | 否 |
+| Retrieval Preference | 调整特定 Automation 的检索配置候选 | 否 |
+
+后续评估：
+
+| 产物 | 风险 |
+| --- | --- |
+| Skill | 可能扩大行为和工具使用 |
+| Procedure | 可能长期影响多个任务 |
+| Non-security Rule | 可能阻断或改变行为 |
+| Agent Preference | 可能产生难以解释的个性漂移 |
+
+永久禁止自动学习修改：
+
+- 工具权限和审批策略。
+- 工作区根目录和文件访问范围。
+- 网络、远程消息和电脑控制权限。
+- Electron 安全设置。
+- API Key、凭据和 Provider Endpoint。
+- 删除、支付、发布和生产操作政策。
+
+## 5. 候选来源
+
+- 用户对回答、任务或 Supervisor 意见的显式反馈。
+- 用户对心跳报告或建议的显式反馈。
+- Task 执行的成功与失败比较。
+- 并行实验结论。
+- 回放评估发现的稳定差异。
+- 用户手动创建。
+
+候选必须包含：
+
+- 作用域。
+- 产物类型。
+- 来源证据。
+- 预期改善的指标。
+- 可能影响的行为。
+- 风险级别。
+- Baseline 引用。
+- 建议的评估集。
+
+模型不能仅凭一条成功案例宣称“已学习”。
+
+## 6. 状态机
+
+```text
+candidate
+  → evaluating
+  → rejected
+  → inconclusive
+  → shadow
+  → awaiting_approval
+  → promoted
+  → paused
+  → rolled_back
+  → archived
+```
+
+| 状态 | 含义 |
+| --- | --- |
+| `candidate` | 尚未评估 |
+| `evaluating` | 正在运行离线评估 |
+| `rejected` | 明确退化、安全不合格或无效 |
+| `inconclusive` | 证据不足 |
+| `shadow` | 计算候选决策但不影响真实行为 |
+| `awaiting_approval` | 达到晋升标准，等待用户 |
+| `promoted` | 已作为指定作用域的当前版本 |
+| `paused` | 暂停影响，保留版本 |
+| `rolled_back` | 已恢复前一版本 |
+| `archived` | 不再评估和使用 |
+
+## 7. 评估案例
+
+### 7.1 案例来源
+
+优先级：
+
+1. 仓库内公开、无隐私的固定评测样例。
+2. 用户手动创建的案例和期望。
+3. 用户明确选择并脱敏的历史会话或任务。
+4. 实验中产生、经用户批准保留的案例。
+
+禁止默认采样所有私人会话用于学习。
+
+### 7.2 案例结构
+
+```ts
+type EvaluationCase = {
+  id: string
+  suiteId: string
+  input: EvaluationInput
+  assertions: EvaluationAssertion[]
+  forbiddenBehaviors: EvaluationAssertion[]
+  source: EvaluationCaseSource
+  sensitivity: 'public' | 'private_local'
+  version: number
+}
+```
+
+断言可以是：
+
+- 输出符合 Schema。
+- 包含或不包含确定文本模式。
+- 引用来自允许知识库。
+- 不调用工具。
+- 任务状态和成果存在。
+- 测试命令通过。
+- 人工评分。
+- 模型 Rubric 分项。
+
+### 7.3 冻结
+
+一次评估冻结：
+
+- 案例版本。
+- Baseline 版本。
+- Candidate 版本。
+- Runtime 和模型。
+- 知识、记忆和工作区快照。
+- 预算。
+- 评估器版本。
+
+设置变化不改变已开始的评估。
+
+## 8. 评估门
+
+### 8.1 判定
+
+```ts
+type GateVerdict = {
+  decision: 'reject' | 'inconclusive' | 'shadow'
+  baselineMetrics: MetricValue[]
+  candidateMetrics: MetricValue[]
+  regressions: Regression[]
+  caseIds: string[]
+  evaluatorVersions: string[]
+  notes: string
+}
+```
+
+最小规则：
+
+1. 任何安全、权限或硬约束退化立即 Reject。
+2. 确定性质量指标不能低于配置阈值。
+3. 成本和延迟退化必须在允许范围。
+4. 开放质量指标至少非退化，或收益足以覆盖明确成本。
+5. 案例数或评估器不足时 Inconclusive。
+6. 通过离线门只进入 Shadow，不直接 Promote。
+
+### 8.2 Baseline
+
+Baseline 是当前已生效版本或明确的无候选行为。不能用另一个同时变化的实验配置充当 Baseline。
+
+### 8.3 多模型评估
+
+模型 Rubric 可使用与被评候选不同的模型，但必须：
+
+- 固定版本和提示。
+- 隐藏候选身份。
+- 随机化顺序。
+- 保存分项和证据。
+- 在关键晋升中结合确定性或人工评估。
+
+## 9. Shadow
+
+Shadow 模式：
+
+- 接收与当前真实行为相同的有界输入。
+- 计算候选会做出的选择或输出。
+- 不调用有副作用工具。
+- 不替换用户看到的结果。
+- 不写入长期记忆。
+- 保存与实际结果可比较的指标。
+
+对于成本较高的候选：
+
+- 只对抽样的已授权案例运行。
+- 用户可设置月度调用上限。
+- 系统繁忙时延后。
+
+Shadow 达到配置的最小观察数且无安全退化后进入 `awaiting_approval`。
+
+## 10. 晋升
+
+晋升对话框必须显示：
+
+- 候选将改变什么。
+- 作用域和受影响计划。
+- 来源。
+- Baseline 与 Candidate 指标。
+- 失败案例和不确定性。
+- 额外成本。
+- 回滚版本。
+
+用户可以：
+
+- 晋升。
+- 继续 Shadow。
+- 拒绝。
+- 缩小作用域后重新评估。
+
+晋升采用原子版本切换。不能在一半对象上成功、一半失败。
+
+## 11. 上线后监控
+
+监控：
+
+- 使用次数。
+- 成功、失败和无结论。
+- 确定性指标。
+- 用户采纳、撤销和负反馈。
+- Token、耗时和工具调用变化。
+- Supervisor 警告变化。
+
+自动暂停条件：
+
+- 安全或权限硬约束失败。
+- 确定性错误率超过阈值。
+- 连续崩溃或格式失败。
+- 成本超过批准上限。
+
+自动暂停只恢复到上一已批准版本，并通知用户。系统不能自行选择新候选替代。
+
+## 12. 回滚
+
+- 每个 Promoted 产物有不可变版本。
+- 保存前一版本和作用域绑定。
+- 一键回滚使用原子切换。
+- 回滚不删除失败版本，保留指标和原因。
+- 当前有运行使用该版本时，只影响下一次 Run；紧急安全暂停可取消尚未开始的 Run。
+- 被回滚候选再次晋升必须重新评估。
+
+## 13. 衰减与归档
+
+- 长期未使用的候选和 Shadow 可归档。
+- Promoted 产物不因时间静默删除。
+- Memory 类型遵守分区记忆的衰减规则。
+- 评估案例变化后，相关候选标记为“评估过期”。
+- 模型或 Runtime 大版本变化时，可要求重新回放。
+- 归档保留不含私人正文的指标和版本元数据。
+
+## 14. 信息架构
+
+若远期验证确有集中学习管理需求，应提供独立且可审计的“学习”视图，而不是放入智能心跳、
+任务中心或一个尚未确认的自动化中心：
+
+1. **候选**：来源、作用域、预期收益和风险。
+2. **评估中**：进度、案例和预算。
+3. **Shadow**：观察数、差异和成本。
+4. **待批准**：晋升摘要。
+5. **已生效**：当前版本、使用量和健康状态。
+6. **历史**：拒绝、回滚和归档。
+
+候选详情页签：
+
+- 概览。
+- 变更 Diff。
+- 评估案例。
+- 指标和失败。
+- Shadow。
+- 版本与回滚。
+
+## 15. 数据模型建议
+
+```ts
+type LearningArtifact = {
+  id: string
+  scopeKind: 'global' | 'project' | 'automation' | 'agent'
+  scopeId?: string
+  kind:
+    | 'memory'
+    | 'automation_template'
+    | 'prompt_variant'
+    | 'rubric'
+    | 'retrieval_preference'
+  status:
+    | 'candidate'
+    | 'evaluating'
+    | 'rejected'
+    | 'inconclusive'
+    | 'shadow'
+    | 'awaiting_approval'
+    | 'promoted'
+    | 'paused'
+    | 'rolled_back'
+    | 'archived'
+  payload: JsonValue
+  sourceRefs: LearningSourceRef[]
+  baselineVersionId?: string
+  promotedVersionId?: string
+  createdAt: string
+  updatedAt: string
+}
+```
+
+建议表：
+
+- `learning_artifacts`
+- `learning_artifact_versions`
+- `evaluation_suites`
+- `evaluation_cases`
+- `evaluation_runs`
+- `evaluation_results`
+- `shadow_observations`
+- `promotion_events`
+- `rollback_events`
+
+## 16. 安全与隐私
+
+1. Apply 层拒绝没有 Gate Verdict 的候选。
+2. 产物类型和目标作用域使用代码白名单。
+3. 安全与权限配置不在可学习目标白名单中。
+4. 私人评估案例只在本地使用，不导出或发送到未授权 Provider。
+5. Shadow 不调用有副作用工具。
+6. Candidate 内容和评估输出都视为不可信数据。
+7. Renderer 不能直接设置 Promoted 状态，Main 验证评估与审批。
+8. 删除私人评估案例后清理派生缓存和 Embedding。
+9. 日志不记录完整案例、Prompt、回答、文件或凭据。
+10. 自动暂停采用确定性条件，不依赖模型自由判断。
+
+## 17. 实施顺序
+
+严格顺序：
+
+1. 建立版本化评估案例和确定性断言。
+2. 复用并行实验运行 Baseline 与 Candidate。
+3. 实现 Gate Verdict，只有 Reject、Inconclusive 和 Shadow。
+4. 实现 Shadow，但不允许 Apply。
+5. 实现人工晋升和原子回滚。
+6. 实现上线监控和确定性自动暂停。
+7. 首先开放 Memory 和 Automation Template。
+8. 经过长期验证后再评估 Skill、Procedure 和非安全规则。
+
+不能先做自动改 Prompt，再补评估门。
+
+## 18. 验收标准
+
+- [ ] 没有评估结果的候选无法晋升。
+- [ ] 安全、权限或硬约束退化必定 Reject。
+- [ ] 评估不足时显示 Inconclusive，不强行选优。
+- [ ] Baseline、Candidate、案例、Runtime 和评估器都被冻结和版本化。
+- [ ] Shadow 不影响用户结果、不调用副作用工具、不写长期记忆。
+- [ ] 晋升前展示收益、退化、成本、作用域和回滚版本。
+- [ ] 第一阶段只有用户可以批准晋升。
+- [ ] 晋升和回滚采用原子版本切换。
+- [ ] 生效后出现确定性严重退化时自动暂停并恢复上一批准版本。
+- [ ] 系统不会自动选择另一个候选替代。
+- [ ] 私人会话不会默认进入评估集。
+- [ ] 安全策略、权限、目录、凭据和 Electron 配置不属于可学习产物。

docs/features/conversation-html-rendering/README.md

@@ -0,0 +1,29 @@
+# 会话 HTML 渲染
+
+会话 HTML 渲染让用户直接查看 Agent 回复中的网页结果，而不必先复制代码到外部文件。
+该能力默认开启，也可以在“设置 > 平台功能 > 通用设置”中关闭。
+
+## 功能边界
+
+- 只渲染已完成的 Agent 正文和已完成的子 Agent 输出。
+- 支持完整 HTML 文档、单一 HTML 根元素，以及 Markdown 中的 `html` / `htm` 代码块。
+- 使用无脚本、无网络、无表单提交和无窗口操作权限的静态隔离预览。
+- 每个预览提供源码切换和全屏预览两个图标操作；全屏预览沿用同一清理和隔离边界。
+- 用户消息、推理过程和流式中的回复不执行 HTML；关闭功能后继续显示 HTML 源码。
+- 本功能不把普通聊天回复复制为成果，也不替代助手工作栏中独立成果的预览流程。
+
+## 文档
+
+- [产品需求](./prd.md)：功能范围、状态规则和验收标准。
+- [技术设计](./technical-design.md)：设置持久化、渲染边界与静态隔离方案。
+- [实现进度](./progress.md)：已验证实现和验证记录。
+
+## 术语
+
+- **HTML 源码**：Agent 回复中原始、可复制的 HTML 文本。
+- **静态预览**：在隔离 `iframe` 中显示的 HTML；脚本、联网和外部操作均被禁用。
+- **全屏预览**：在应用级 Modal 中显示同一份静态预览文档，用于查看完整页面布局。
+
+全局聊天和设置界面规则由根目录的
+[统一界面设计系统](../../../UI-DESIGN.md)定义。独立成果预览仍由
+[助手工作栏](../assistant-workbar/README.md)负责。

docs/features/conversation-html-rendering/prd.md

@@ -0,0 +1,69 @@
+# 会话 HTML 渲染产品需求
+
+## 用户问题
+
+Agent 可以生成网页、报告和交互原型的 HTML，但此前会话只能显示源码或忽略原始标签。
+用户必须把内容复制到外部文件后才能查看结果，打断了会话内的阅读和迭代流程。
+
+## 目标
+
+- 让 Agent 生成的 HTML 在回复完成后直接显示为网页预览。
+- 保留一键查看原始 HTML 的能力。
+- 允许用户通过平台功能开关恢复为只看源码。
+- 预览不取得 GoodBuddy Renderer 或外部网络能力。
+
+## 非目标
+
+- 不执行 Agent 提供的 JavaScript。
+- 不提供联网网页、表单、弹窗或 Electron `webview`。
+- 不在流式输出中反复加载不完整页面。
+- 不自动把普通会话回复保存为成果。
+
+## 功能需求
+
+### FR-1 默认设置
+
+“会话 HTML 渲染”是应用级持久设置，默认开启。用户可在“设置 > 平台功能 >
+通用设置”中立即关闭或重新开启；保存失败时保留最后确认的状态并显示错误。
+
+### FR-2 可识别输出
+
+开启后，已完成 Agent 回复中的以下内容显示为静态预览：
+
+1. 完整 HTML 文档。
+2. 由单一 HTML 根元素构成的完整回复。
+3. Markdown 中标记为 `html` 或 `htm` 的代码块。
+
+普通 Markdown 继续按原有规则显示。一个回复中的多个 HTML 代码块各自保持原有位置。
+
+### FR-3 回复状态和角色
+
+- 已完成的主 Agent 正文和已完成的子 Agent 输出可以预览 HTML。
+- 用户消息和 Agent 推理只显示文本或源码。
+- 流式 Agent 正文在完成前显示源码，完成后原位切换为预览。
+
+### FR-4 源码、全屏与关闭行为
+
+每个预览持续显示“静态安全预览，脚本和网络已禁用”，并在标题右侧提供两个图标操作：
+
+1. 源码按钮，就地展开或收起原始 HTML。
+2. 全屏按钮，在应用级 Modal 中查看同一份预览文档。
+
+嵌入预览使用固定高度并在框内滚动，需要更大画面时使用全屏预览。全屏预览可通过关闭
+按钮、Escape 或点击遮罩退出，退出后焦点回到全屏按钮。关闭平台功能后，完整 HTML 回复
+和 HTML 代码块继续显示源码，不能变成空白。
+
+### FR-5 静态隔离
+
+预览必须禁用脚本、网络请求、表单提交、嵌套页面、插件对象和窗口操作。远程链接和远程
+媒体不得从预览加载；内联样式和有界的内联位图可用于还原静态视觉。
+
+## 产品验收
+
+- 新安装和从旧设置升级后，开关均为开启。
+- 完整 HTML 和 fenced HTML 在已完成的 Agent 回复中显示预览。
+- 关闭开关后，当前会话立即恢复显示源码，重启后选择仍保留。
+- 流式回复、推理和用户消息从不执行 HTML。
+- 预览可通过键盘访问源码和全屏按钮，并具有明确的 iframe 标题。
+- 全屏预览隔离背景、初始聚焦关闭按钮，Escape 退出后焦点回到全屏按钮。
+- 恶意脚本、事件属性、远程资源、表单和嵌套 frame 不进入可执行预览。

docs/features/conversation-html-rendering/progress.md

@@ -0,0 +1,39 @@
+# 会话 HTML 渲染实现进度
+
+## 已实现
+
+- [x] 应用级持久开关，默认开启，并提供旧设置迁移。
+- [x] 平台功能通用设置中的共享 Switch。
+- [x] 已完成 Agent 回复和子 Agent 输出中的完整 HTML 与 fenced HTML 识别。
+- [x] 隔离静态预览、持续安全说明和源码切换。
+- [x] 预览保留作者 `<style>` 与 `style` 属性，样式不再被整块丢弃。
+- [x] 与 Mermaid 一致的图标按钮组：源码切换与全屏预览 Modal。
+- [x] 嵌入预览固定 480px 高度，源码面板同值上限。
+- [x] 用户消息、推理、流式回复和关闭状态的源码边界。
+- [x] 设置变更后当前会话立即重新渲染。
+
+## 验证记录
+
+2026-09-05：
+
+- `npm run typecheck`：通过。
+- 聚焦测试（应用设置、Markdown、会话时间线、设置中心、App 集成）：306 项通过。
+- 全量 `npm test`：`3493 passed, 55 skipped`。
+- `npm run lint`：通过。
+- `npm run build`：Main、Preload、Renderer 与控制面安装器均成功构建。
+
+修复样式丢失后复验：
+
+- 原实现只要 `<style>` 或 `style` 属性中出现 `@import` / `url()` 就整块删除，带渐变或
+  背景图的回复因此完全失去样式；现改为保留作者样式，外部资源加载仍由 iframe CSP 拒绝。
+- `npx vitest run src/renderer/src/MarkdownRenderer.test.tsx`：`19 passed`。
+- 聚焦测试（会话时间线、App 集成、设置中心）：`260 passed`。
+- `npm run typecheck`、`npm run lint`：通过。
+
+新增全屏预览与图标化源码按钮后复验：
+
+- 源码按钮改为代码图标并暴露 `aria-expanded`；新增放大图标打开全屏 Modal。
+- 嵌入预览高度由 `min-height: 320px` 改为固定 `height: 480px`，源码面板上限同步为 480px。
+- 新增回归测试覆盖全屏 Modal 的初始焦点、背景 inert、Sandbox/CSP 与 Escape 焦点恢复。
+- 聚焦测试（Markdown、会话时间线、App 集成、设置中心）：`280 passed`。
+- `npm run typecheck`、`npm run lint`：通过。

docs/features/conversation-html-rendering/technical-design.md

@@ -0,0 +1,68 @@
+# 会话 HTML 渲染技术设计
+
+## 进程和设置边界
+
+`conversationHtmlRenderingEnabled` 属于现有 `ApplicationSettings`。Main 继续通过
+版本化 JSON 文件持久化应用设置，IPC 继续复用已验证的
+`settings:application:get/update` 通道，Preload 只暴露类型化设置方法。
+
+应用设置格式升级到版本 11。版本 10 及更早设置在读取时补入默认值 `true`，无需保留第二份
+状态或独立迁移文件。
+
+## Renderer 数据流
+
+1. `App` 启动时读取应用设置，并把当前值传给每个保活的会话视图。
+2. 平台功能 Switch 保存成功后立即更新 `App` 状态。
+3. `ChatTimeline` 只为 `role === "assistant"` 且 `state === "complete"` 的正文传入
+   HTML 渲染权限；推理始终不传入该权限。
+4. `MarkdownRenderer` 识别完整 HTML 回复以及 `html` / `htm` fenced code。
+5. 关闭权限或回复仍在流式阶段时，HTML 保持代码文本。
+
+## 静态预览
+
+`StaticHtmlPreview` 不使用 `dangerouslySetInnerHTML`。它先用 DOMPurify 清理文档，再通过
+`DOMParser` 移除事件属性、非锚点 `href` 和非内联图片的 `src` / `poster`，最后把结果写入
+`<iframe sandbox="" srcDoc>`。
+
+作者样式必须保留：`<style>` 元素和 `style` 属性原样传入预览，不按 `@import` 或 `url()`
+关键字整块删除，否则任何带渐变或背景图的回复都会退化成无样式文档。外部样式表和远程
+字体、图片的实际加载由 iframe 文档的 CSP 拒绝，不需要在清理阶段重复拦截。
+
+iframe 文档注入严格 CSP：
+
+- `default-src 'none'`
+- `script-src 'none'`
+- `connect-src 'none'`
+- `frame-src 'none'`
+- `object-src 'none'`
+- `form-action 'none'`
+- 只允许内联样式以及 `data:` 字体和受支持的内联位图
+
+同时设置 `referrerPolicy="no-referrer"`。Sandbox 不授予 scripts、forms、popups、
+same-origin 或 navigation 权限。预览只在回复完成后创建，并使用 lazy loading。
+
+## UI 与无障碍
+
+预览沿用聊天阅读宽度、语义颜色和共享 `icon-button`。`figure` / `figcaption` 表达预览及其
+说明，iframe 具有本地化标题。标题右侧是一个 `role="group"` 图标按钮组，与 Mermaid 图表
+操作保持一致：源码按钮暴露 `aria-expanded` 与 `aria-controls`，全屏按钮打开 Modal。
+
+嵌入预览高度固定为 480px，超出部分在框内滚动；查看源码面板使用同一数值作为最大高度。
+iframe 无法按内容自适应高度，因为 `sandbox=""` 不含 `allow-same-origin` 或 `allow-scripts`，
+主文档既读不到内部文档尺寸，也不能接收上报；全屏预览覆盖需要更多空间的场景。
+
+全屏预览复用 `dialog-focus` 的 `activateModalFocus` 与 `trapTabFocus`，遵循统一 Modal 的
+背景 inert、初始焦点落在关闭按钮、Tab 循环、Escape 关闭和关闭后焦点恢复。它渲染的是与
+嵌入预览完全相同的清理后文档，不额外放宽 Sandbox 或 CSP。切换回复时，源码面板与全屏
+预览按当前 source 派生开合状态，不使用会引发级联渲染的重置 effect。
+
+## 验证范围
+
+- 应用设置默认值、关闭持久化和版本 10 迁移。
+- fenced HTML、完整 HTML、关闭后的源码回退。
+- 作者 `<style>` 与 `style` 属性在预览中保留。
+- 脚本、远程资源、表单和事件属性清理，以及 iframe Sandbox/CSP。
+- 源码按钮的 `aria-expanded` 切换，以及全屏预览的初始焦点、背景 inert、Escape 关闭和
+  焦点恢复。
+- 主 Agent、子 Agent、用户、推理和流式状态边界。
+- 从设置 Switch 到当前会话重新渲染的应用级集成路径。

docs/features/conversation-supervision/README.md

@@ -0,0 +1,11 @@
+# 会话监督
+
+会话监督定义对长会话、工具执行和异常状态的观察、判断与介入边界。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [会话监督 PRD](./prd.md) | 监督目标、证据、介入方式和产品验收 |
+
+当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。

docs/features/conversation-supervision/prd.md

@@ -0,0 +1,415 @@
+# 会话监督 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-08-18 |
+| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
+| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
+| 体验参考 | GoodBuddy 魔法笔记 AI 评论流 |
+
+## 1. 背景
+
+GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写作，AI 在右侧以长评、建议和
+警告进行评论，用户可以选择综合、扩展、润色、质疑或发散方向。该能力是内容分析，不是
+会话监督：
+
+- 只分析当前笔记或待办文本。
+- 不观察聊天任务、工具调用、目标、预算或成果。
+- 不参与任务状态机。
+- 不引用具体会话步骤。
+- 不支持关注、暂停和解决流程。
+
+随着目标任务和并行实验出现，用户需要一个与执行 Agent 相互独立的观察者，帮助发现偏题、
+遗漏、矛盾、证据不足、循环、成本失控和潜在风险。
+
+## 2. 产品定义
+
+会话监督是在明确范围和策略下，对普通 Conversation、Task 或 Experiment 的可见事件
+进行独立观察，产生带证据的评论、告警和人工介入请求。每个 Task 只关联一条 Conversation，
+一条 Conversation 可以承载多个 Task；Job/Run 是内部执行和审计对象，不作为当前 UI
+监督目标。
+
+它不是：
+
+- 第二个替用户发言的聊天 Agent。
+- 隐藏推理查看器。
+- 工具审批器。
+- 可以绕过安全边界的“总管理员”。
+- 自动修正执行过程的通用控制器。
+
+## 3. 核心产品判断
+
+建议增加会话监督，首期采用“魔法笔记式右侧评论流”，但只开放以下能力：
+
+```text
+观察
+→ 评论 / 警告
+→ 用户查看证据
+→ 用户忽略、采纳、询问、暂停或调整任务
+```
+
+首期模型监督不自动暂停。只有现有确定性安全规则、预算和用户显式配置的硬门禁可以自动暂停。
+
+## 4. 已确认的产品决策
+
+1. 监督默认关闭，由用户对 Conversation、Task 或实验显式启用。
+2. 监督只读取用户可查看的消息、工具事件、状态、指标、成果摘要和目标。
+3. 不读取、推断或保存模型隐藏推理链。
+4. 每条重要判断必须引用具体消息、工具、步骤、指标或成果。
+5. 模型监督默认只评论、警告或请求人工复核。
+6. 确定性监督负责权限、预算、Schema、幂等和硬停止条件。
+7. 监督器不能自动批准工具、扩大范围、修改安全策略或替用户发送消息。
+8. 监督评论不是长期事实，默认不进入记忆。
+9. 监督调用使用独立预算和低于前台对话的优先级。
+10. 同一个事件不能同时产生重复页内警告、评论和全局通知。
+
+## 5. 目标
+
+### 5.1 用户目标
+
+- 在重要会话旁获得不中断主对话的独立评论。
+- 及时发现目标偏移、缺少证据、相互矛盾、重复循环和遗漏要求。
+- 点击监督意见查看对应证据，而不是接受无来源判断。
+- 对监督意见进行采纳、忽略、标记误报或追问。
+- 对 Scheduled/Goal Task 设置更严格的监督策略和人工检查点。
+
+### 5.2 产品目标
+
+- 为普通会话、目标任务和实验提供统一监督契约。
+- 让确定性安全门禁与模型质量判断保持分层。
+- 保存有界、可审计的监督事件，而非复制完整会话。
+- 将用户反馈用于调整规则和评估监督器，但不自动训练或改策略。
+
+## 6. 非目标
+
+- 不展示内部 Chain of Thought。
+- 不持续监控其他应用、键盘、麦克风或屏幕。
+- 不把 Supervisor 设为拥有所有工具的超级 Agent。
+- 不自动修改用户消息或助手回答。
+- 不保证识别所有事实错误、偏见或安全风险。
+- 不把一次模型警告作为任务失败的确定性依据。
+- 不在首期支持 Supervisor 与执行 Agent 自主多轮辩论。
+- 不让 Supervisor 读取未授权项目、会话、知识库或记忆。
+
+## 7. 监督对象
+
+| 对象 | 观察内容 | 典型用途 |
+| --- | --- | --- |
+| 普通会话 | 用户消息、助手回答、引用、工具事件 | 质量和证据评论 |
+| Task | 目标、状态、Conversation、成果 | 偏离、循环和失败分析 |
+| Experiment | 协议、变量、各候选执行、指标和证据 | 协议一致性、评估公平性与无结论提示 |
+
+每个监督会话只能绑定一个主对象，并继承其项目范围。
+
+## 8. 监督模式
+
+### 8.1 评论方向
+
+借鉴魔法笔记，普通会话支持：
+
+| 模式 | 行为 |
+| --- | --- |
+| 综合 | 平衡总结目标、进展、风险和下一步 |
+| 质疑 | 检查逻辑跳跃、前提、反例和证据 |
+| 证据 | 检查重要结论是否有可追溯依据 |
+| 目标 | 检查是否回应用户目标和约束 |
+| 风险 | 检查权限、隐私、外部影响和不可逆行为 |
+
+自动化和实验可组合多个检查维度，不用方向单选替代确定性规则。
+
+### 8.2 触发方式
+
+| 方式 | 说明 |
+| --- | --- |
+| 手动 | 用户点击“检查当前会话” |
+| 每次回复后 | 助手一轮完成后异步分析 |
+| 每 N 步 | 自动化或实验按有界步骤间隔分析 |
+| 关键事件 | 工具失败、预算 80%、等待审批、指标异常 |
+| Run 结束 | 进行最终监督回顾 |
+
+首期优先手动和每次回复后。草稿输入不发送给监督器，除非未来明确增加类似魔法笔记的
+草稿评论模式。
+
+### 8.3 干预级别
+
+```ts
+type SupervisorAction =
+  | 'continue'
+  | 'comment'
+  | 'warn'
+  | 'request_review'
+  | 'pause'
+  | 'stop'
+```
+
+- 模型 Supervisor 首期只可产生前四种。
+- `pause` 和 `stop` 只来自确定性门禁或用户操作。
+- 后续若允许模型建议暂停，仍需确定性策略把建议转换为 `request_review` 或经过用户预授权。
+
+## 9. 观察输入
+
+### 9.1 可见输入
+
+- 当前对象的名称、目标和约束。
+- 最近有界消息。
+- 工具名称、状态、参数摘要和输出摘要。
+- Task、Job 和 Subjob 状态。
+- 成果标题、类型、大小和有界摘要。
+- 引用和知识检索诊断。
+- 预算使用。
+- 明确配置的监督规则。
+- 已解决或被忽略的近期监督意见摘要。
+
+### 9.2 禁止输入
+
+- API Key、Token、Cookie 和认证头。
+- 模型隐藏推理。
+- 未授权文件和完整私人文档。
+- 其他项目、会话或实验 Run 的数据。
+- 原始无限长度工具输出。
+- 已删除或用户要求忘记的记忆。
+
+### 9.3 上下文窗口
+
+- 普通会话默认最近 12 条消息和最多 24,000 字符。
+- 任务按最近 20 个关键事件和当前目标组装。
+- 长会话先使用确定性提取，再由监督器处理有界输入。
+- 不能把 Supervisor 自己的旧评论无限回填，最多保留近期未解决摘要。
+
+## 10. 监督输出
+
+```ts
+type SupervisorDecision = {
+  action:
+    | 'continue'
+    | 'comment'
+    | 'warn'
+    | 'request_review'
+  category:
+    | 'goal_drift'
+    | 'missing_requirement'
+    | 'evidence_gap'
+    | 'contradiction'
+    | 'repetition'
+    | 'quality'
+    | 'risk'
+    | 'budget'
+  severity: 'info' | 'low' | 'medium' | 'high'
+  title: string
+  content: string
+  evidence: SupervisorEvidenceRef[]
+  confidence: number
+  suggestedActions: SupervisorSuggestedAction[]
+}
+```
+
+证据引用可以指向：
+
+- `messageId`
+- `toolCallId`
+- `taskEventId`
+- `artifactId`
+- `metricId`
+- `approvalId`
+
+没有有效证据时，严重度最多为 `low`，且必须显示“推测”。
+
+## 11. 确定性监督
+
+以下检查由代码执行：
+
+- Ask 出现写工具请求。
+- 工具或路径超出计划快照。
+- 未经批准的跨项目或跨分区读取。
+- Token、时间、工具、Job/Subjob 和成果预算。
+- 幂等键冲突或结果未知。
+- 输出 Schema 不匹配。
+- 实验 Run 读取其他 Run 数据。
+- 硬停止条件和必填成果。
+
+确定性监督可以阻止、暂停或终止运行。结果必须包含规则 ID、实际值、阈值和触发事件，
+不通过模型重新解释才能生效。
+
+## 12. 模型监督
+
+适合判断：
+
+- 回答是否偏离用户问题。
+- 计划是否遗漏明确要求。
+- 重要结论是否缺少证据。
+- 当前回答与前文是否矛盾。
+- 是否重复尝试而没有进展。
+- 是否存在值得用户注意的模糊风险。
+
+模型监督输出严格经过 Schema 校验。格式错误最多修复一次；失败不阻塞普通前台会话，
+但在配置为自动化门禁时必须明确记录“监督不可用”，不能假装检查通过。
+
+## 13. 用户交互
+
+### 13.1 工作栏监督栏目评论流
+
+监督是助手工作栏中固定且始终可访问的栏目，不是只在聊天页面出现的附属面板。栏目默认
+跟随当前会话，用户也可以固定到其他普通 Conversation、Task 或 Experiment。
+切换页面不会改变固定目标；目标失效时必须显示修复状态，不能静默回到当前会话。
+
+复用魔法笔记的体验方向：
+
+- 长评卡。
+- 建议卡。
+- 警告卡。
+- 证据链接。
+- 评论方向和时间。
+
+每条意见操作：
+
+- 查看证据。
+- 采纳建议。
+- 追问。
+- 忽略。
+- 标记误报。
+- 对自动化请求暂停。
+
+“采纳”只是把建议带入输入框、计划草稿或任务操作，不让 Supervisor 直接执行。
+
+### 13.2 会话输入区
+
+会话输入区可以提供当前会话监督的快捷入口，但不是监督能力的唯一入口，也不控制工作栏中
+已经固定到其他对象的监督目标：
+
+```text
+监督：关闭 / 综合 / 质疑 / 证据 / 目标 / 风险
+```
+
+这是持久二元启用加方向选择：
+
+- 是否启用使用共享 Switch，`role="switch"`。
+- 方向使用 `SegmentedControl` 或上下文单选菜单。
+- 不把开关和方向做成一组含义不清的页签。
+
+### 13.3 关注状态
+
+会话或任务列表显示未解决意见数量和最高严重度，不能只用颜色。
+只有 `request_review`、高风险警告或确定性暂停触发全局通知。
+
+## 14. 解决流程
+
+```text
+open
+  → acknowledged
+  → resolved
+  → dismissed
+  → false_positive
+```
+
+- `acknowledged`：用户已查看，尚未解决。
+- `resolved`：用户或后续运行说明已处理。
+- `dismissed`：不采纳，但不一定是误报。
+- `false_positive`：明确标记判断不正确。
+
+后续监督输入可以包含未解决意见摘要，已解决意见默认不重复提醒。
+
+## 15. 与任务控制的关系
+
+Supervisor 建议“暂停”时：
+
+1. 创建 `request_review`。
+2. 在任务自身的会话界面显示原因和证据。
+3. 用户选择继续、暂停、调整目标或取消。
+4. 用户操作进入任务审计。
+
+确定性门禁暂停时：
+
+1. Run 进入 `paused` 或 `waiting_approval`。
+2. 显示规则、阈值和实际值。
+3. 只有满足规则或用户完成对应审批后才能恢复。
+4. 模型评论不能覆盖门禁。
+
+## 16. 与记忆的关系
+
+- 监督评论默认保存在监督记录，不属于长期记忆。
+- 用户采纳后可以手动创建记忆候选。
+- “事实错误”“用户偏好”等监督判断不能自动写入 Project 或 Global。
+- 多次被用户标记误报的模式进入监督评估数据，不直接改变 Prompt。
+- 监督器可以读取绑定范围内的已确认记忆，但必须在证据中标明记忆来源。
+
+## 17. 数据模型建议
+
+```ts
+type SupervisorSession = {
+  id: string
+  projectId?: string
+  targetType: 'conversation' | 'task' | 'automation_run' | 'experiment'
+  targetId: string
+  enabled: boolean
+  mode: 'general' | 'challenge' | 'evidence' | 'goal' | 'risk'
+  triggerPolicy: SupervisorTriggerPolicy
+  budget: SupervisorBudget
+}
+
+type SupervisorRecord = {
+  id: string
+  sessionId: string
+  source: 'deterministic' | 'model'
+  decision: SupervisorDecision
+  status:
+    | 'open'
+    | 'acknowledged'
+    | 'resolved'
+    | 'dismissed'
+    | 'false_positive'
+  createdAt: string
+  resolvedAt?: string
+}
+```
+
+证据关系建议独立表或有界结构化 JSON，并在读取时重新验证对象归属。
+
+## 18. 安全与隐私
+
+1. Supervisor 使用独立可信系统指令，所有观察输入视为不可信数据。
+2. 默认不给 Supervisor 任何工具。
+3. 即使后续提供只读证据工具，也只能读取绑定对象和明确范围。
+4. Supervisor 不接收 Runtime 授权回调，不能请求工具批准。
+5. 普通会话监督失败不影响主回答；自动化配置的强制监督失败进入明确关注状态。
+6. 评论和通知不包含完整私人消息，证据点击后才在原对象中查看。
+7. Renderer 传入的 Evidence ID 必须由 Main 重新验证归属。
+8. 删除会话时按产品数据保留策略删除或匿名化监督记录。
+9. 用户关闭监督后停止新分析，但保留历史，除非用户明确删除。
+
+## 19. 性能与预算
+
+- Supervisor 使用独立后台并发池，默认全局并发 1。
+- 前台回复完成后异步运行，不延迟主回答呈现。
+- 同一会话同时只运行一次监督分析，新事件合并为下一次分析。
+- 普通会话每 30 秒最多自动分析一次。
+- 自动化按步骤或关键事件节流。
+- 达到 Supervisor 预算时显示“监督已暂停”，不继续产生费用。
+
+## 20. 实施顺序
+
+1. 定义监督会话、记录、证据和解决状态。
+2. 上线普通会话手动检查和右侧评论流。
+3. 增加每次回复后异步监督、节流和预算。
+4. 接入任务和自动化的确定性观察。
+5. 增加目标、证据和无进展模型检查。
+6. 接入实验协议一致性监督。
+7. 建立误报和有用性评估，不自动改 Prompt。
+
+## 21. 验收标准
+
+- [ ] 监督默认关闭，用户可对单个会话显式启用。
+- [ ] Supervisor 只读取当前对象的有界可见事件。
+- [ ] 隐藏推理、密钥和未授权内容不进入监督输入。
+- [ ] 每条中高严重度意见都有可点击证据。
+- [ ] 无证据推测不会显示为高严重度事实。
+- [ ] 模型监督不能自动暂停、终止、批准工具或替用户发言。
+- [ ] 确定性门禁不依赖模型判断即可阻止越权和超预算行为。
+- [ ] 主会话回答不等待后台 Supervisor 完成。
+- [ ] 用户可采纳、忽略、标记误报和解决意见。
+- [ ] 监督评论默认不进入长期记忆。
+- [ ] 自动化强制监督不可用时明确请求关注，不假装检查通过。
+- [ ] Supervisor 预算耗尽后停止新调用并显示状态。

docs/features/deepseek-harness/README.md

@@ -0,0 +1,12 @@
+# DeepSeek Harness Runtime
+
+本功能定义 DeepSeek Harness 作为 GoodBuddy 本机 Agent Runtime 的产品接入、控制面、
+插件市场、权限和打包边界。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [技术设计](./technical-design.md) | Runtime 产品与技术方案、协议、插件、打包、测试和验收 |
+
+现有文档同时包含部分 PRD、功能逻辑和进度内容，后续修改该 Runtime 时再按标准职责拆分。

docs/features/deepseek-harness/technical-design.md

@@ -0,0 +1,806 @@
+# GoodBuddy 自维护 DeepSeek Harness Runtime 设计
+
+## 1. 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档状态 | 实现与发布验收基线 |
+| 设计目标 | 将 DeepSeek Harness 作为 GoodBuddy 的第三个 Agent Runtime |
+| Runtime 标识 | `deepseek-harness` |
+| 当前依赖基线 | 实际使用的 `@deepseek-ai/dsh-*` 底层库，精确锁定 `0.1.2-rc.1` |
+| 上游状态 | Developer Preview，允许出现破坏性变更 |
+| 上游许可证 | MIT |
+| GoodBuddy 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 本文性质 | 设计与发布验收约定 |
+
+本文定义 DeepSeek Harness 在 GoodBuddy 中的架构边界、协议、执行策略、插件市场、界面、打包和验收要求。实现必须继续遵守 GoodBuddy 已有的 Main 进程安全边界、Ask/Execute 语义、取消、超时、有界输出和资源回收约定。
+
+## 2. 摘要
+
+DeepSeek Harness 的底层库使用 Cordis 组合服务。GoodBuddy 不采用官方产品 profile，也不允许用户配置覆盖内部 Host 或控制服务；GoodBuddy 自行维护 Host、控制协议和生命周期，同时提供一个由 Main 管理、默认关闭的 npm 插件市场。用户显式开启后，市场只搜索带精确 `dsh-plugin` 关键字的公共 npm 包，不代表 GoodBuddy 审核、推荐或承诺兼容这些包。
+
+用户明确安装并启用的插件以当前用户权限运行。Ask/Execute 只控制模型经过 `tools/execute` 发起的工具调用：Ask 只允许 Host 中真实注册的 `read`、`skill` 和 Main 管理的 Web Search/Fetch 代理，Execute 放行 Host 中全部已注册工具。插件不能用同名工具冒充 Ask 允许项。插件安装脚本和初始化代码不属于模型工具调用，不能由 Ask 限制，因此界面在安装前必须明确确认这一边界。
+
+整体分成两个互相约束的部分：
+
+1. **GoodBuddy Main Control Plane**
+   - 运行在 Electron Main 进程。
+   - 持有加密设置、模型连接选择、Ask 只读策略、Runtime 生命周期、插件市场状态和审计归属。
+   - 通过 Electron `utilityProcess` 启动受控 Harness 子进程。
+   - 对环境、输入、输出、超时、取消和进程树执行强制限制，并只把已启用插件的受管入口传给 Host。
+
+2. **GoodBuddy Harness Control Plane**
+   - 运行在 Harness 子进程内，是 Host 私有的内部控制组件，不导出 Cordis 插件入口。
+   - 使用 ACP 兼容的 JSON-RPC stdio 作为基础控制面。
+   - 增加 GoodBuddy 所需的能力握手、每轮权限准备、会话释放、工具事件、推理、用量和安全凭据请求扩展。
+   - 与 GoodBuddy Host 一起维护、构建和发布，不设计为独立 npm 包或市场插件；第三方插件只作为显式配置加载。
+
+DeepSeek Harness 不替换 OpenCode、Continue 或直连模型 Runtime。用户可以按全局、项目、会话或消息通道继续选择现有 Runtime。
+
+## 3. 背景与上游能力
+
+### 3.1 已确认的官方能力
+
+- `@deepseek-ai/dsh` 是官方 profile 启动器。
+- Harness 插件是导出 `apply(ctx, config)` 的 Cordis 模块。
+- npm 包可通过 `dsh.bundle` 声明配置补丁，再通过 `dsh plugin --profile <name> add <package>` 安装。
+- ACP 支持：
+  - 初始化。
+  - 创建多个会话。
+  - 发送 Prompt。
+  - 按会话取消。
+  - 一次性权限选择。
+  - 已提交的助手文本。
+- 官方本地沙箱支持：
+  - Linux：Bubblewrap，或 Landlock 降级。
+  - macOS：Seatbelt。
+  - Windows：ACL 受限令牌，官方明确标记为部分强制执行。
+
+GoodBuddy 不组合上述 Runtime OS 沙箱。当前产品选择 DSH 本地 Shell 与
+Filesystem Provider，以 GoodBuddy 客户端进程的当前用户权限运行工具。
+
+### 3.2 官方通道的缺口
+
+官方 ACP 插件有意只输出已提交文本，不输出推理、工具进度、计划、标题和用量。它也没有标准的会话关闭方法。SDK JSON-RPC 的展示事件更完整，但缺少 GoodBuddy 需要的单轮取消和权限回传。
+
+因此，首版不单独选用其中一个官方通道作为完整实现。GoodBuddy Harness Control Plane 以 ACP 语义为基础，补充有命名空间的扩展方法和事件。
+
+### 3.3 自维护边界
+
+GoodBuddy 自己的 Runtime 和控制面不包装成标准 DSH 插件，也不加载用户 profile 或自定义 Host。只有 GoodBuddy Main 可以启动内部 Host、选择受管插件入口并处理启动失败。公共 npm 市场是第三方扩展来源，不改变 GoodBuddy 对内部 Host、Ask/Execute 语义和协议版本的控制。
+
+## 4. 目标与非目标
+
+### 4.1 首版目标
+
+- 增加 `deepseek-harness` Runtime，并在设置、聊天和消息通道中可选择。
+- 使用 GoodBuddy 管理的模型连接，不在 Renderer 或持久化 Harness 配置中写入 API Key。
+- 当所选模型连接明确声明支持图像输入时，允许向 DeepSeek Harness 发送有界的 JPEG/PNG；文本模型在启动 Host 或调用模型前拒绝图片。
+- Ask 模式在 Runtime 工具分发边界强制只读，阻止 Shell、写入和编辑工具。
+- 在 Web Search 能力启用时，通过 Main 代理向 Ask 与 Execute 提供有界的 `web_search` 和 `web_fetch`，Harness Utility 不持有服务凭据。
+- Execute 模式使用 DSH 本地 Provider，以当前用户权限执行文件与命令工具；工作区是默认工作目录，不是 OS 权限边界。
+- 提供默认关闭的公共 npm DSH 插件市场总开关；用户显式开启后可搜索、查看详情、精确版本安装、启用、停用、配置和移除，首次安装前明确确认当前用户权限。
+- 只加载 Main 明确传入的已启用插件；单个插件启动失败不得阻止 Host，并自动停用失败插件。
+- 允许 Skills 和自定义 MCP 显式分配给 DeepSeek Harness；自定义 MCP 只在 Execute 中通过 Main 代理。
+- 设置页可读取有界的 Host/插件原生 Tool 与 Skill 清单；Tool 元数据显示类型、来源及 Ask/Execute 可用性，并明确排除 GoodBuddy 分配的 Skills、Web/MCP 请求代理。
+- 支持多会话、同会话串行、跨会话并行。
+- 支持按请求取消、超时、会话释放和应用退出时完整回收。
+- 输出文本、推理、工具参数、工具结果、stderr 和协议队列全部有界。
+- 使用真实 OpenAI 兼容 Chat Completions 模型验证调用，而不在日志、测试产物或提交中暴露凭据。
+- 保留 Windows、macOS、Linux 的 x64 和 arm64 发布能力。
+
+### 4.2 首版非目标
+
+- 不替换 OpenCode、Continue 或直连模型 Runtime。
+- 不开放用户 Cordis profile、cordis.patch.yml 或 $DSH_HOME 全局补丁覆盖。
+- 不提供外部 Host、自定义 Harness Control Plane、任意本地模块路径或用户 profile 插件目录。
+- 不加载 Harness Web UI、HMR、遥测、自动更新或目录选择器。
+- 不提供 Runtime OS 沙箱模式或相关持久设置。
+- 不向 Utility 暴露 MCP 凭据或建立直连 MCP Client。只有用户明确分配给 Harness 的 MCP 工具可以通过 Main 代理调用。
+- 不在首版向 Harness 暴露 GoodBuddy 浏览器控制、知识库或 Magic Notes。
+- 不在首版支持会话恢复、Harness Subagent、后台 Job、Hook、浏览器控制或 Workflow；Web Search/Fetch 只通过 Main 代理提供，不加载 Harness 自有网页服务。上述长生命周期能力未来统一进入右侧 Runtime 监督栏，不进入 Composer 工具栏。
+- 不发布独立 npm 包，也不创建上游 PR。
+- 不为第三方插件增加权限矩阵、风险等级、逐工具审批、沙箱档位、回滚代际或兼容性背书。
+
+## 5. 核心设计决策
+
+### 5.1 第三个独立 Runtime
+
+`deepseek-harness` 是明确的 Runtime 类型，不伪装成 `model`、`opencode` 或 `continue`。共享契约、设置迁移、Runtime 选择、检测、聊天标签、消息通道和模型用量都使用同一个稳定标识。
+
+### 5.2 受控组合，不启动用户 profile
+
+GoodBuddy 使用自己固定的 Harness Host 入口和只读组合模板，不调用 `dsh web`，也不启动用户已有 profile。运行时禁止以下来源参与组合：
+
+- 当前工作目录的 `.env`。
+- 用户 Harness Home 的 `.env`。
+- `$DSH_HOME/cordis.patch.yml`。
+- 用户 profile 的 `cordis.patch.yml`。
+- 任意 `--patch`。
+- HMR 和 profile 驱动的动态插件安装。
+
+模型名称、服务地址、工作区、Skills、MCP schema 和已启用插件的规范化入口通过严格校验的 Main 配置传给 Host。API Key 只通过受控凭据通道按需提供，不写入 YAML、命令行、Renderer 或日志。插件配置只来自 GoodBuddy 受管状态，不合并用户 profile 或全局补丁。
+
+### 5.3 双层内部控制面
+
+Harness 子进程内控制面不能取代 Main 控制面，Main 控制面也不能代替进程内的 Session/Tool 适配层：
+
+- Harness Control Plane 最接近 Session、Agent、Tool 和 Usage seam，适合做内部协议转换与 Ask 工具拦截。
+- Main 控制面是可信安全边界，适合持有模式授权策略、加密设置、进程控制和 IPC。
+
+任何一侧缺失能力握手时，Runtime 必须报告不可用，不能降级为不受控执行。
+
+### 5.4 GoodBuddy 继续拥有持久会话
+
+首版不启用 Harness JSONL 会话持久化和 SQLite 会话索引。原因如下：
+
+- GoodBuddy 已经持久化对话、消息、活动、工具事件和用量。
+- 再写一份 Harness 日志会扩大敏感数据副本和清理范围。
+- GoodBuddy 在 Runtime 重启后可以用现有会话历史创建新 Harness Session。
+
+Harness Session 只在当前 Runtime 进程生命周期内存在。释放 GoodBuddy 会话时必须同步释放对应 Harness Agent。
+固定 Host 显式加载 `dsh-session-projection` 的内存 SessionProjectionRegistry，这是
+`0.1.2-rc.1` AgentLoop 的必需依赖；不加载 Session persistence，也不新增磁盘会话副本。
+该依赖与其余 DSH 依赖一起由 Vite 打入 Host，不能从 `app.asar.unpacked` 外部导入
+仅存在于 `app.asar` 的 npm 包。最终打包检查及 Windows CI 的真实 UtilityProcess
+启动探针见 [Runtime 资源与打包](../../../BUILD.md#runtime-资源)。
+
+## 6. 总体架构
+
+```text
+Renderer
+  │ 显式、经 schema 验证的 preload API
+  ▼
+Electron Main
+  ├─ RuntimeSettingsStore
+  ├─ RuntimeExtensionStore / npm Marketplace
+  ├─ AgentRuntimeController
+  ├─ RuntimeAuthorizer（Ask 拒绝 / Main 代理工具授权）
+  └─ DeepSeekHarnessRuntime / Main Control Plane
+       │ ACP + goodbuddy/* 扩展，stdin/stdout
+       ▼
+Electron utilityProcess
+  └─ GoodBuddy Harness Host
+       ├─ 固定 Cordis 组合
+       ├─ GoodBuddy Harness Control Plane（内部组件）
+       ├─ DSH Agent 与 LLM seam
+       ├─ 按模型能力挂载的有界内存图片存储
+       ├─ 本地 Shell / Filesystem Provider
+       ├─ 最小工具集与 Main 代理 MCP
+       └─ Main 明确启用的第三方 Cordis 插件
+             │ HTTP/HTTPS
+             ▼
+        用户选择的 OpenAI 兼容模型连接
+```
+
+### 6.1 信任边界
+
+| 区域 | 信任级别 | 允许持有的内容 |
+| --- | --- | --- |
+| Renderer | 不可信展示层 | 脱敏设置、状态、用户可见事件 |
+| Preload | 窄桥 | 明确方法和共享 schema |
+| Electron Main | 可信控制面 | 加密设置、模式授权策略、Runtime 生命周期 |
+| npm 安装子进程 | 第三方执行面 | 受管暂存目录、去除模型凭据的有界环境和当前用户权限 |
+| Harness utilityProcess | 不可信执行面 | 当前请求、临时凭据、受控工具、第三方插件代码和当前用户权限 |
+| Harness 工具子进程 | 最低信任 | 单次命令所需的最小环境和当前用户权限 |
+
+Harness 子进程崩溃、输出异常、拒绝协议或加载错误时，Main 必须失败关闭。
+
+## 7. GoodBuddy Harness Control Plane
+
+### 7.1 内部组件职责
+
+控制面负责：
+
+- 启动 ACP 兼容的 JSON-RPC stdio 服务。
+- 创建、查找和释放 Harness Agent。
+- 在 Prompt 前应用 GoodBuddy 指定的 Ask/Execute 权限。
+- 将 DSH Session 事件转换为有界的 GoodBuddy 事件。
+- 将 LLM 用量转换为稳定的模型用量事件。
+- 根据 Main 传入的模型能力声明 ACP 图片能力，验证内联图片并转换为 DSH 的不可变 Attachment 引用。
+- 在 dispose 时先取消 Agent，再等待子 Agent 和工具清理。
+- 保证 stdout 只包含协议帧，诊断只写 stderr。
+
+控制面不负责：
+
+- 保存 GoodBuddy 设置。
+- 持久保存 API Key。
+- 决定 Main 的模式授权结果。
+- 直接访问 Renderer 或 Electron API。
+- 接受任意路径、外部 Host 或 profile 覆盖；插件入口只能来自 Main 的受管清单。
+- 自行上传遥测。
+
+### 7.2 第三方插件加载
+
+GoodBuddy 控制面自身不导出 `apply(ctx, config)`，也不提供默认 stdin/stdout 入口或可安装 manifest。第三方插件由 Main 在启动配置中逐项指定：
+
+- Main 只传递受管 Store 中已启用插件的稳定 ID、规范化入口文件和 JSON 配置。
+- Launcher 与 Host 对消息结构和绝对入口路径执行严格校验；Host 解析真实路径并要求入口是普通文件。
+- Host 动态加载 Cordis 插件并等待激活，每个插件有独立的 5 秒激活超时，完整插件序列最多占用 90 秒。
+- Main 的 Host 启动预算使用 10 秒基础预算，加上每个已启用插件 5 秒激活与最多 1 秒失败清理、且整个插件序列最多占用 91 秒，再预留 2 秒保存失败插件状态；显式测试超时仍作为调用方指定的硬上限。
+- 插件按清单依次加载；导入、导出形态或激活失败只记录该插件，不阻止其他插件和 Host 启动。失败 Fiber 的清理同样有界。
+- 有限但超过预算的同步导入或同步 `apply` 在返回后按超时失败并继续加载后续插件；JavaScript 不能在同一事件循环内抢占永不返回的同步第三方代码，此时由 Main 的独立启动截止时间终止整个 Utility。
+- 失败 ID 在 ready 握手中返回 Main；Main 原子写入停用状态和启动错误。
+- 插件成功激活后可注册工具或后台生命周期逻辑。Ask 只能拦截模型工具调用，不能撤销初始化阶段已经发生的副作用。
+
+GoodBuddy 不扫描任意目录、不读取用户 profile 插件清单，也不接受 Renderer 直接提供文件路径。
+插件安装、升级和移除在目录重命名前写入受管变更日志。Main 下次初始化时以持久
+Store 是否已经提交为准，确定性完成新目录或恢复旧目录，并在处理前重新验证受管
+目录、入口真实路径、符号链接和根目录包含关系。旧版 `store.json` 继续原地迁移，
+不要求用户重新安装插件。
+
+## 8. 协议设计
+
+### 8.1 传输
+
+- stdin/stdout 使用换行分隔 JSON-RPC。
+- stdout 不得出现日志、Banner、进度条或调试输出。
+- stderr 只允许有界诊断，不得包含 Prompt、工具完整输出或凭据。
+- 每一帧、每一字段和每个请求累计输出都必须在解析前或接收时限流。
+- 图片只允许作为 ACP 内联 base64 内容传入；拒绝远程 URI，Host 不替用户获取图片 URL。
+
+### 8.2 标准 ACP 方法
+
+首版保留 ACP 的初始化、`session/new`、`session/prompt` 和 `session/cancel` 语义。`promptCapabilities.image` 必须与所选模型连接的 `supportsImageInput` 完全一致，不能仅根据 Provider 或模型名称猜测。标准 ACP 客户端可以使用只读默认行为，但只有完成 GoodBuddy 能力握手的客户端才能启用 Execute。
+
+### 8.3 GoodBuddy 扩展
+
+扩展统一使用 `goodbuddy/` 命名空间：
+
+| 方法或事件 | 方向 | 用途 |
+| --- | --- | --- |
+| `goodbuddy/handshake` | Main → Control Plane | 交换控制协议、Harness、ACP 版本和能力 |
+| `goodbuddy/session/prepare` | Main → Control Plane | 在下一次 Prompt 前设置工作模式和请求标识 |
+| `goodbuddy/session/release` | Main → Control Plane | 取消并释放指定 Session |
+| `goodbuddy/session/event` | Control Plane → Main | 文本、推理、工具、状态和用量事件 |
+| `goodbuddy/credential/resolve` | Control Plane → Main | 按已登记引用请求当前 Runtime 的临时凭据 |
+| `goodbuddy/tools/list` | Control Plane → Main | 取得 Main 管理的有界 Web 工具与当前 Execute 请求的 MCP 工具 schema |
+| `goodbuddy/tools/call` | Control Plane → Main | 校验活动请求、工作模式、参数和精确注册代理身份后调用 Main Web/MCP 工具 |
+| `goodbuddy/native/snapshot` | Main → Control Plane | 从无 Agent scope 的 Host Registry 读取有界的原生 Tool/Skill 元数据，排除 GoodBuddy 分配项与请求级代理 |
+| `goodbuddy/shutdown` | Main → Control Plane | 停止接收新请求并有序清理 |
+
+Utility 启动控制协议使用版本 3，严格携带 `supportsImageInput`、模型连接的有界自定义
+Header 与固定 8 MiB 帧上限；旧版本或缺少必需字段的启动消息失败关闭，不能让 Host
+自行猜测模型能力。扩展版本独立于 ACP 版本。握手响应至少包含：
+
+```ts
+type GoodBuddyHarnessCapabilities = {
+  controlProtocolVersion: 1
+  harnessVersion: string
+  acpProtocolVersion: number
+  supports: {
+    cancellation: true
+    sessionRelease: true
+    reasoningEvents: boolean
+    toolEvents: boolean
+    usageEvents: boolean
+    credentialResolution: true
+  }
+  execution: {
+    mode: 'host'
+  }
+}
+```
+
+版本不兼容、必需能力缺失或 `execution.mode` 不是 `host` 时，Main 不得开始模型请求。
+
+### 8.4 每轮权限准备
+
+GoodBuddy 的工作模式属于每个请求，不属于 Runtime 进程全局状态。同一对话可以在 Ask 和 Execute 之间切换。因此：
+
+1. `session/new` 后默认是 Ask。
+2. 每个 Prompt 前，Main 发送一次 `goodbuddy/session/prepare`。
+3. Harness Control Plane 将准备状态绑定到 `sessionId + requestId`。
+4. `session/prompt` 只能消费匹配且尚未使用的准备状态。
+5. 缺少准备状态、重复使用、请求标识不匹配时，Control Plane 直接拒绝请求。
+6. 同一 Session 只允许一个 Prompt 在途。
+
+若 Runtime 回传 ACP 权限请求，Main 只按活跃 Session 的当前模式答复：Execute 优先选择
+`allow_once`，缺少时使用提供的 `allow_always`，不调用第二次人工 authorizer；
+Ask、已关闭或未知 Session 拒绝。这里不写入永久授权规则，也不把业务问答当作权限确认。
+
+### 8.5 事件模型
+
+Harness Control Plane 只发送 GoodBuddy 能稳定解释的字段：
+
+- `status`：简短运行状态。
+- `text`：已提交的助手文本分片。
+- `reasoning`：可选的有界推理摘要分片。
+- `tool`：工具 ID、名称、状态和有界输入/输出摘要。
+- `model-usage`：模型、提供方、输入、输出和缓存 Token。
+- `done`：停止原因和 Session ID。
+
+禁止发送原始 Cordis Context、完整环境、内部对象、堆栈中的凭据或无界 Session 日志。
+
+## 9. Runtime 生命周期
+
+### 9.1 进程模型
+
+- 每个活动的 DeepSeek Harness Runtime 实例拥有一个 `utilityProcess`。
+- 一个进程可以承载多个 Harness Session。
+- 同一 GoodBuddy 对话的 Prompt 串行执行。
+- 不同对话可以并行，但受全局并发上限控制。
+- Runtime 设置变化时创建新实例，旧实例等待在途请求结束或在宽限期后被取消。
+
+### 9.2 会话映射
+
+Main 保存内存映射：
+
+```text
+GoodBuddy conversationId -> Harness sessionId + process generation
+```
+
+- 首次请求创建 Session。
+- 已有 Session 只发送当前 Prompt。
+- 进程重启或映射失效时，创建新 Session，并只在这一次加入 GoodBuddy 提供的会话历史。
+- 历史以明确的“不可信会话数据”结构传入，不能拼接成系统指令。
+- 用户分配的 Skill 只通过 Main 校验的包路径进入 Host，并在 Agent scope 注册；不得把 Skill 内容伪装成用户 Prompt。
+
+### 9.3 取消与有界控制操作
+
+- 用户取消时立即发送 `session/cancel`。
+- 取消等待有界，超时后关闭连接并终止整个 Harness 进程。
+- 初始化、握手、请求准备、权限回传和关闭分别使用独立控制超时。
+- 生产 Prompt 不设置固定墙钟总时限，由 Harness 自身协议终态或用户取消结束。测试可以
+  显式注入短 Prompt 时限验证取消传播，超时错误与用户取消仍不能被宽泛 catch 抹平。
+- 取消后仍可接收并丢弃该请求的最终协议结算帧，但不得写入下一请求。
+
+### 9.4 释放与退出
+
+- 原生能力清单由 `SelectedRuntimeManager` 缓存的执行 Runtime 提供，与随后的对话请求共用同一实例，不再为清单单独启动并销毁一次 Host；该实例遵循执行缓存的空闲淘汰、设置变更 reset 和退出 dispose 规则。
+- 删除或释放对话时调用 `goodbuddy/session/release`。
+- Runtime dispose 时先拒绝新请求，再取消所有 Session。
+- Harness Control Plane 完成 Agent、工具和会话清理，Host 完成 Cordis Fiber 与子进程的反向清理。
+- Main 在宽限期内等待正常退出。
+- 超时后终止 utilityProcess，并在平台允许时清理完整进程树。
+- 应用退出时中止正在运行的 npm 插件安装并终止其完整进程树，不能让 lifecycle script 在 GoodBuddy 退出后继续运行。
+- 应用退出不得因 Harness 清理无限阻塞。
+
+## 10. 权限与主机执行
+
+### 10.1 模式映射
+
+| GoodBuddy 模式 | Host 内置与插件工具 | Main Web Search/Fetch | GoodBuddy 自定义 MCP | 行为 |
+| --- | --- | --- | --- | --- |
+| Ask | 只允许 Host Registry 中真实注册的 `read` 与 `skill`；其他 Host/插件工具一律拒绝 | 能力启用时注册 Main 的精确代理对象，无逐次审批 | 不注册 | 模型工具调用保持只读 |
+| Execute | 放行 Host 中全部已注册的内置与插件工具 | 能力启用时注册 Main 代理 | 按分配注册并经过既有 RuntimeAuthorizer | 不增加插件权限层，以当前用户权限运行 |
+
+### 10.2 Ask 模式
+
+- Harness Control Plane 在 `tools/execute` 分发边界识别当前 Session 和在途请求。
+- 采用所有权感知的只读允许列表，只接受 Registry 中真实的 `read`、`skill` 和 Main 注册的 Web 代理对象；`write`、`edit`、Shell、MCP 及任意新插件工具默认拒绝。只比较工具名不足以授权，插件注册同名工具仍会被拒绝。
+- Ask 不注册 Main 代理的 MCP 工具。
+- Web Search/Fetch 的凭据、传输与结果限制保留在 Main；Utility 只看到有界 schema 和结果。
+- 只读不等于无限输出，读取仍受字节和工具结果上限控制。
+- 插件安装脚本和 Cordis 初始化生命周期不经过 `tools/execute`。Ask 不能把已启用第三方代码变成沙箱，也不能保证第三方代码没有启动副作用。
+
+### 10.3 Execute 模式
+
+- 工作区来自 Session 创建时的规范化绝对路径，并作为文件与命令工具的默认工作目录。
+- DSH 本地 Filesystem、Bash 或 PowerShell Provider 直接使用 GoodBuddy 客户端当前用户的 OS 权限。
+- 工作区不是 containment 边界；绝对路径和命令可访问当前用户本来有权访问的主机资源。
+- 已启用插件注册的工具与内置工具使用同一分发路径；GoodBuddy 不增加插件权限矩阵或逐工具确认。
+- Main 代理的 MCP 工具继续执行分配、schema、活动请求、模式和 RuntimeAuthorizer 校验。
+  `goodbuddy/tools/list` 按 Session 保存本次发现的工具定义；`goodbuddy/tools/call` 复用该定义
+  校验参数与授权，不因调用健康工具而重新等待故障 MCP 的发现。发现重试留在清单刷新，
+  Session 释放及 Runtime dispose 清除内存定义，不持久化第二份能力状态。
+- 所有工具调用仍作为活动事件记录；Ask 和 delegation 路径继续固定拒绝。
+
+### 10.4 Runtime OS 沙箱
+
+- GoodBuddy 不加载 DSH 平台 Sandbox Provider，也不执行启动沙箱探测。
+- “安全与数据”不提供 Runtime OS 沙箱开关。
+- 握手明确报告 `execution.mode = 'host'`，状态文案明确说明工具使用当前用户权限。
+- Electron Renderer、Preload、Browser Session 等应用安全沙箱不在本设计变更范围内。
+
+### 10.5 环境与凭据
+
+- 使用环境变量白名单构造 utilityProcess 环境。
+- 不继承 `NODE_OPTIONS`、调试端口、任意 npm 配置、用户 `DSH_*` 覆盖或白名单之外的凭据。
+- `DSH_TELEMETRY_DISABLED=1` 必须固定设置。
+- Harness Home 指向 GoodBuddy 管理的隔离目录。
+- 不调用官方 `loadEnv` 或 `loadLayeredEnv`。
+- API Key 由 Main 从加密设置中解析。
+- Harness Control Plane 只能用已握手登记的引用通过 `goodbuddy/credential/resolve` 请求当前 Runtime 的凭据。
+- 凭据只在模型请求所需的子进程内存中短暂存在，不写磁盘、不进入工具环境、不打印。
+- npm 安装使用同一环境白名单并移除模型 Provider 凭据；安装脚本仍拥有当前用户的文件、进程和网络权限。
+
+## 11. 受控 Harness 组合
+
+首版只加载完成文本对话、受控代码操作和用户明确分配能力所需的固定服务：
+
+- Agent、Session、LLM 和 Tool Registry 基础服务。
+- GoodBuddy Harness Control Plane。
+- OpenAI 兼容 Chat Completions LLM 适配器。
+- 仅在所选模型声明图片能力时挂载的进程内 Attachment Store；它完整解码图片、校验格式/尺寸/摘要，以内容寻址引用保存，并随 Session 或 Host 释放。
+- DSH 本地 Subprocess、Filesystem 和平台 Shell Provider。
+- Token Meter 和必要的上下文压缩。
+- 有界的读取、写入、编辑和 Shell 工具。
+- Agent scope 的 Skill Registry 与 `skill` 工具。Skill 目录由 Main 选择并在 Launcher 和 Host 两次规范化、校验。
+- Main 代理的 Web 与 MCP schema 工具。Utility 不持有 Web/MCP URL、凭据或 Transport。
+- Main 明确传入的第三方 Cordis 插件及其 JSON 配置。
+
+首版明确不加载：
+
+- Web UI、HMR、Host API 和目录选择器。
+- Harness 遥测。
+- Settings File 和 Local Credentials。
+- 用户 profile 与全局补丁。
+- Harness 自有 Web Search/Fetch、Utility 直连 Web/MCP、Hooks。
+- Subagent、Workflow、Ralph、后台 Job。
+- JSONL Session Persistence 和 SQLite Session Query。
+- 自动技能发现、任意目录扫描和 profile 市场状态。
+
+如果某个首版工具依赖被排除服务，启动审计必须失败，而不是自动加载更大的默认 bundle。
+
+## 12. 模型配置
+
+### 12.1 配置来源
+
+DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
+
+- 协议必须是 `openai-chat-completions`。
+- 认证必须是 API Key。
+- 服务地址支持 HTTP 和 HTTPS，不根据主机位置、端口、凭据、查询参数或片段增加额外限制。
+- 模型名称不限制为 DeepSeek 品牌，由所选 OpenAI 兼容服务决定。
+- 模型名称和服务地址由 Main 传入受控 Host。
+- 图片能力只读取所选 GoodBuddy 模型连接的 `supportsImageInput`；Main、Utility 启动配置、ACP 能力和 Pi-AI 模型输入模态必须使用同一个布尔值。
+- 模型连接的自定义 Header 通过 Utility 启动配置交给 Pi-AI Provider；Pi-AI 没有受支持的
+  任意 Body 配置入口，因此 DeepSeek Harness 不接收自定义 Body。完整支持矩阵和合并规则
+  见[模型连接请求定制](../model-connections/technical-design.md)。
+- API Key 继续保存在 GoodBuddy 加密设置中。
+- `platform` 在设置页显示为“管理员环境优先，回退 GoodBuddy 兼容连接”，不是 Harness
+  自有配置文件。Main 优先读取完整的 `GOODBUDDY_MODEL_BASE_URL`、
+  `GOODBUDDY_MODEL_NAME` 和 `GOODBUDDY_MODEL_API_KEY` 环境预置；不完整时使用
+  当前默认兼容 GoodBuddy 连接，再回退首个兼容连接。
+- `default` 只跟随 GoodBuddy 默认兼容连接或首个兼容连接，跳过独立管理员预置；
+  `profile` 使用指定的兼容连接。没有兼容连接时，仍允许选择 `platform`，因为完整
+  管理员预置不依赖已保存连接的协议；运行时缺少实际连接才报告不可用。
+- Renderer 通过 Main 的只读平台来源投影展示实际管理员模型或兼容回退，不读取环境
+  或密钥，也不根据 `credentialSource` 猜测。投影直接复用本节所述的生产 resolver，
+  字段、非持久化与草稿展示边界见
+  [Harness 平台来源公开投影](../model-connections/technical-design.md#9-harness-平台来源公开投影)。
+
+不允许选择 Harness 自有的用户配置文件或自定义 Host。Runtime 始终使用随当前 GoodBuddy 版本发布的内置 Host，并通过完整内部能力握手。
+
+### 12.2 设置变化
+
+模型、凭据、Skill、MCP 分配或插件安装、启停、配置、移除变化时，GoodBuddy 创建新 Runtime 实例。Harness Host 路径始终由当前 GoodBuddy 构建提供，不能由设置或环境变量替换。旧实例按现有 Runtime Controller 语义退役，不在一个活动进程内热替换配置。
+
+### 12.3 输入限制
+
+- 文本始终可用；图片是否可用完全取决于所选模型连接是否显式声明 `supportsImageInput: true`。
+- 文本模型收到图片时必须在启动 Host 或发起模型网络调用前返回明确错误，不能静默丢弃图片。
+- 图片模型只接受内联 JPEG/PNG，不接受 URL、文件路径、ACP `uri` 或其他媒体类型。
+- Main 已通过 `nativeImage` 解码用户选择的图片并生成有界模型输入；Utility 仍须独立执行严格 base64、签名、容器结构、CRC（PNG）、完整解码、尺寸和摘要校验，不能把 Main 校验当作跨进程信任替代。
+- 每条消息最多 8 张图，单图编码后最多 1 MiB，图片合计最多 2 MiB，单边最长 8,192 px，单图最多 1,600 万像素，累计解码像素最多 3,200 万（重复引用也计入预算）。进程内 Store 另设 32 MiB、256 个唯一对象的总上限。
+- Attachment Store 只服务当前非持久 Harness Session；引用按 Session 释放，Host 退出时清空，不写入磁盘或 GoodBuddy 第二份会话日志。
+- GoodBuddy 历史、Prompt、系统指令分别保持不同信任层。
+- 任何用户文本都不能进入 Cordis 配置表达式或模块名。
+
+## 13. 输出和资源边界
+
+建议首版默认限制：
+
+| 项目 | 默认上限 |
+| --- | --- |
+| 单个 JSON-RPC 帧 | 8 MiB |
+| 单图 / 单条消息图片 | 1 MiB / 8 张且合计 2 MiB |
+| 单图尺寸 / 单条消息解码像素 | 单边最长 8,192 px 且 1,600 万像素 / 3,200 万像素 |
+| Host 临时图片存储 | 32 MiB 且最多 256 个唯一对象 |
+| 单个文本或推理事件 | 64 KiB |
+| 单次请求累计协议输出 | 无固定总量上限，继续校验单帧和待处理队列 |
+| 单轮模型输出 Token | 由 Harness SDK 与 Provider 决定，GoodBuddy 不固定覆盖为 16K |
+| 工具输入摘要 | 4,000 字符 |
+| 工具输出摘要 | 4,000 字符 |
+| 待处理事件数 | 1,000 |
+| stderr 累计 | 64 KiB |
+| Host 启动 | 10 秒基础预算 + 每插件 5 秒激活与最多 1 秒失败清理，插件序列最多 91 秒；Main 另预留 2 秒持久化失败状态 |
+| ACP 初始化与内部握手 | 每阶段 10 秒 |
+| 单次 Prompt | 无固定墙钟总时限，由 Harness 终态或用户取消结束 |
+| 有序关闭宽限期 | 2 秒 |
+
+超过限制时应取消当前请求。协议帧、队列或 stderr 持续异常时，应终止 Runtime 进程，避免继续信任已失控的通道。
+
+## 14. Runtime 检测与状态
+
+### 14.1 检测
+
+检测只验证：
+
+- 内置 Host 路径是规范化文件。
+- 版本可读取且在支持范围内。
+- 内部控制面能力握手成功。
+
+检测不得调用付费模型，也不得读取或输出 API Key。真实模型测试是单独的显式操作。
+
+### 14.2 设置界面
+
+Agent Runtime 使用共享 `SegmentedControl` 展示 OpenCode、Continue 和 DeepSeek Harness。DeepSeek Harness 必须标记为“开发者预览”，并说明上游 RC 可能发生破坏性变更。
+
+Runtime 的概览、模型配置和检测信息放在同一张详情卡中。当前单独显示的一行“已就绪”应移入卡片，与路径、版本号归为同一组：
+
+```text
+Runtime：       GoodBuddy 内置 DeepSeek Harness
+模型配置：      跟随 GoodBuddy · 企业网关（qwen-plus）
+状态：          已就绪
+路径：          <受控 Host 路径>
+版本：          0.1.2-rc.1
+执行权限：      当前用户权限
+
+Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
+```
+
+界面要求：
+
+- 不再在卡片外重复一行检测结果。
+- 使用语义化键值结构，路径允许换行，不截断关键信息。
+- 状态不能只依靠绿色表达，必须同时有文字。
+- 检测中和不可用分别显示明确文案。
+- 高级设置默认收起。
+- DSH 插件市场提供共享 Switch 样式的总开关并默认关闭。关闭时不请求公共 npm 目录且隐藏市场管理界面，但不修改已有插件的逐项启停状态；因此已启用插件继续随 Host 加载，重新开启后恢复原有管理状态。
+- 同一 Runtime 页面提供紧凑的 DSH 插件市场：客户端筛选名称、包名、描述和许可证，已安装插件优先显示。
+- 安装前使用一个明确 Checkbox 确认 npm 安装脚本、插件初始化和 Execute 工具均使用当前用户权限；不展示权限矩阵或逐工具审批。
+- 已安装插件使用共享 Switch 启停，并提供 JSON 配置、明确移除确认和启动失败信息。
+- npm 目录离线时仍显示并允许管理已安装插件；目录错误就地显示并可重试。
+- 安装、启停、配置和移除的短期结果通过应用通知显示，不重复保留页内成功提示。
+- DSH 不提供独立的“允许图片”开关。Runtime 连接选择只引用“模型连接”中维护的图片能力声明，避免同一模型出现两份冲突配置。
+
+聊天顶栏只显示简短 Runtime 状态，不显示文件路径和版本。完整诊断只在设置页展示。
+
+### 14.3 Agent Runtime 交互表面归属
+
+OpenCode、Continue 和 DeepSeek Harness 的后续能力按操作生命周期放置，不按上游产品分别堆叠入口：
+
+| 表面 | 负责内容 | 不负责内容 |
+| --- | --- | --- |
+| Composer 通用行 | 附件、语音、知识范围、专家、Ask/Execute、Runtime 和发送 | Session 监督、后台进度、历史任务管理 |
+| Composer Runtime 专属行 | 仅对当前消息生效且需要高频选择的 Agent、预设、Prompt/Command 快捷操作 | Task 级委派、后台执行、Workflow/Hook 生命周期 |
+| 助手工作栏固定“Runtime”栏目 | 用户所选 Conversation 或 Task 的 Runtime 状态、Task 级委派与取消、后台执行进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止和会话监督；不显示 Job/Run 树 | 持久模型、程序路径、默认 Agent/预设配置 |
+| 设置 > Agent Runtime | 持久 Runtime 配置、默认值、插件管理、能力清单和连接诊断 | 某次活动会话的实时控制 |
+
+Runtime 栏目入口始终存在，并采用统一监督模型；内部再按用户所选目标及其 Runtime 的真实能力
+显示 OpenCode、Continue 或 DSH 的具体区域。未支持能力不渲染空卡片或一排禁用按钮，而是
+在用户需要理解缺口时显示原因和可执行入口。跟随模式切换 Runtime、Conversation 或 Task
+时必须清理上一归属的聚合执行状态，固定目标则保持不变。完整工作栏契约见
+[通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)。
+
+所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、Task/Job/Subjob 层级、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。
+
+## 15. IPC 与共享契约
+
+共享 schema 需要覆盖：
+
+- `deepseek-harness` provider 和 Runtime ID。
+- Runtime 选择中的 `deepseekHarness` 分支。
+- 检测结果中的路径、版本、详情和主机执行模式。
+- GoodBuddy 模型连接选择。
+- 从所选模型连接解析并传到 Host 的 `supportsImageInput`，以及 ACP 图片能力的一致性。
+- DeepSeek Harness 模型用量归属。
+- Skill 与 MCP 对 `deepseek-harness` 的显式分配。
+- 插件市场总开关、目录、已安装状态、启停状态、JSON 配置和有界启动错误。
+- 插件 `set-marketplace-enabled`、`install`、`set-enabled`、`configure`、`remove` 五类严格 action。
+
+Renderer 只接收公开 npm 元数据和受管插件状态。任何凭据、完整环境、npm 子进程参数、内部 Host 配置或任意插件文件路径都不能由 Renderer 提交；安装 action 只能引用当前目录中的精确包名与版本。
+
+已有设置迁移必须：
+
+- 对没有新字段的用户使用安全默认值。
+- 新建或没有已安装插件的旧 Store 将市场迁移为关闭；已有安装记录的旧 Store 保持开启，避免升级后隐藏用户正在管理的插件。
+- 保留 OpenCode、Continue 和模型连接选择。
+- 修复失效的 DeepSeek Harness 模型引用时给出可报告的迁移警告。
+- 不把旧 Runtime 自动迁移为 DeepSeek Harness。
+
+## 16. 打包与供应链
+
+### 16.1 版本策略
+
+- 官方 RC 包全部精确锁定，不使用 `^` 或 `~`。
+- 同一 Harness 核心包族必须保持同一 RC 版本。
+- 升级前检查 release diff、协议 diff、工具执行语义和依赖闭包。
+- 内部握手同时检查锁定的 Harness 基线和 GoodBuddy 控制协议版本。
+
+### 16.2 插件市场安装
+
+- 目录来自 npm 公共搜索 API，只保留包含精确 `dsh-plugin` 关键字的包，最多读取 1,000 项并短期缓存。
+- 安装时再次读取精确版本 packument，不信任搜索结果替代版本清单。
+- GoodBuddy 精确锁定并随发布包携带 npm `11.19.0`；Electron 以 `ELECTRON_RUN_AS_NODE=1` 启动该 CLI 和受管 `node` shim，不要求用户另装 Node.js 或 npm。
+- npm 使用普通依赖解析并运行包及依赖声明的 lifecycle scripts。安装确认必须准确说明这些脚本以当前用户权限运行。
+- 安装在 Store 的暂存目录中完成，校验包名、精确版本、`dsh.bundle` 声明、入口文件和 lockfile integrity 后才原子替换当前版本。
+- 市场关闭时拒绝新安装且不请求目录，但 `getEnabledExtensions()` 继续按逐项启停状态返回已安装插件。
+- 首次安装默认启用。更新保留既有启停状态和 JSON 配置；失败更新保留原安装。
+- 每个插件只有一个受管目录和一条状态记录；Store 同时持久化市场总开关。状态写入原子化且 mutation 串行。
+- JSON 配置限制为对象根、64 KiB、16 层、每个容器 256 项和 4,096 个节点，避免 IPC、持久化和 Host 启动载荷无界增长。
+- Renderer 不接收受管入口路径；Main 只接受目录中的插件 ID 与精确包版本，不能由 IPC 指定 tarball URL、文件路径或命令。
+
+### 16.3 原生依赖
+
+受控组合可能需要：
+
+- `node-pty`，用于受管理的工具子进程。
+- `koffi`，用于本地 Filesystem 在 Windows 上保持文件 ACL 和原子替换。
+- `@napi-rs/canvas` 及当前平台二进制，用于在 Utility 内完整解码并复核 JPEG/PNG；原生模块必须从 ASAR 解包并通过目标架构校验。
+
+构建 GoodBuddy 自身时不得广泛批准依赖安装脚本；只允许生产组合实际需要、来源已审查、版本已锁定的脚本。这与用户确认后由市场插件执行自身 lifecycle scripts 是两个不同阶段。六个平台的构建必须验证：
+
+- 对应架构的原生文件存在。
+- Electron Utility Process 可加载原生模块。
+- spawn helper 的权限正确。
+- 包中没有混入其他平台不需要的可执行内容，除非上游包无法拆分且已记录。
+
+### 16.4 生产闭包
+
+发布包包含受控 Host、锁定的 npm 安装 Runtime 和许可证。应尽量避免把 Harness Web profile、HMR 和其他未加载产品面带入生产闭包。若 npm 依赖结构无法拆分，必须：
+
+- 确认这些模块不会被加载。
+- 评估它们带来的 audit 和体积风险。
+- 在后续上游版本允许时改为最小包族。
+- 确认 `tests/fixtures` 以及 Web3D 测试 Skill/MCP 不进入正式发布资源。
+
+### 16.5 漏洞门禁
+
+当前安装后的 `npm audit` 报告不能直接用 `npm audit fix --force` 处理。每项漏洞需要区分：
+
+- GoodBuddy 既有依赖。
+- Harness 新增生产依赖。
+- 仅开发或打包依赖。
+- 未加载但被带入的 Web 依赖。
+
+进入 Harness 执行路径且有可利用条件的高危问题必须在发布前修复、替换或移出生产闭包。
+
+### 16.6 发布验证
+
+`build/build-release.cjs` 需要验证：
+
+- Harness Host 和受控配置存在。
+- GoodBuddy Host、内部控制协议与 Harness 依赖版本清单存在。
+- 平台原生 PTY/Koffi 依赖架构正确。
+- Harness、ACP SDK 和其他新增第三方许可证已打包。
+- `app.asar` 外需要执行或动态加载的资源位于预期目录。
+- 独立的 npm Runtime 及其捆绑依赖闭包存在，并可通过当前 Electron Node Runtime 启动和执行生命周期脚本。
+- Web3D Skill/MCP 等测试 fixture 不在 `app.asar` 或 `extraResources` 中。
+
+## 17. 测试策略
+
+### 17.1 单元测试
+
+- Runtime 选择、设置迁移和失效引用修复。
+- 二进制检测、版本解析和路径规范化。
+- ACP 握手、事件转换和请求关联。
+- 每个会话单请求、跨会话并行。
+- Ask 在工具分发边界只允许真实注册的 `read`、`skill` 与 Main Web 代理，并拒绝同名冒充和任意新插件工具；Execute 放行插件工具。
+- 握手只接受明确的 `execution.mode = 'host'`。
+- 未分配 Skill/MCP 不可见；分配后的 Skill catalog 可调用 `skill` 加载。
+- 原生能力快照只包含 Host/插件原生 Skills，不包含 GoodBuddy 分配的 Skills 或 MCP。
+- Ask 不注册 MCP 工具；Web 代理可用于 Ask 与 Execute；Execute 每轮刷新有界 MCP schema，并在调用前再次校验活动请求、模式、参数和 RuntimeAuthorizer 结果。
+- MCP URL、启动命令和凭据不进入 Utility 启动配置或协议结果。
+- 未知授权结果失败关闭。
+- 超时、取消、迟到帧和进程意外退出。
+- 协议帧、事件队列、工具摘要和 stderr 上限。
+- 文本模型在 Host 启动前拒绝图片；图片模型的能力声明、ACP 图片块、Pi-AI 模态和 Attachment Store 保持一致。
+- 图片 base64、格式签名、PNG CRC、完整解码、尺寸、单图/单消息/Store 上限、内容摘要、Session 释放和 Host 清空。
+- release 和 dispose 的幂等性。
+- 状态卡中的状态、路径、版本和当前用户执行权限。
+- 插件 action 与目录 schema 接受严格的市场总开关并拒绝权限、回滚、任意路径和非精确版本等未支持字段。
+- Store 的原子安装、失败更新保留、串行 mutation、离线管理、配置、移除和启动失败停用。
+- npm 分页、精确关键字、捆绑 CLI 调用、lifecycle 参数、包身份、入口和 integrity 校验。
+- Renderer 的搜索、权限确认、Switch、JSON 配置、移除确认、离线目录和通知反馈。
+
+### 17.2 本地集成测试
+
+使用无网络的假控制面/模型验证：
+
+- utilityProcess 管道。
+- 多 Session。
+- Session 释放。
+- Runtime 替换。
+- 进程树回收。
+- 本地 Filesystem 与 Shell Provider 使用规范化工作区作为默认工作目录，且不报告沙箱强制模式。
+- 受控配置不会读取工作区 `.env` 和用户 DSH 配置。
+- 插件导入或激活失败相互隔离，成功插件继续加载，失败 ID 返回 Main。
+- IPC 只接受严格插件 action，可信 Renderer 操作后触发 Runtime 重建。
+
+### 17.3 真实模型测试
+
+真实测试已经获得用户授权，但必须由显式环境门禁启用。Web3D Skill 和 MCP 仅作为 `tests/fixtures` 下的测试资产使用，不属于内置发布能力。至少验证：
+
+1. 文本问答成功，并记录正确 Runtime 和模型用量。
+2. Ask 可以读取工作区，但写入被拒绝，且不会弹出权限对话框。
+3. 启用 Web Search 后，Ask 可以调用 Main 管理的 `web_search` 与 `web_fetch`，插件同名工具仍被拒绝。
+4. Execute 可以在工作区创建测试文件。
+5. Execute 工具确实以当前用户权限运行，且状态和握手不宣称 OS 隔离。
+6. Ask、delegation 和无活动请求不能绕过工具分发检查。
+7. 取消长请求后不再产生文本，并可继续使用其他 Session。
+8. 两个 Session 可并行，事件不会串线。
+9. 释放会话和关闭应用后没有残留 Harness 或工具进程。
+10. 从全新用户设置流程启用一个 3D 游戏 Skill 和实际本地或开放 MCP，工具事件能够证明二者确实被调用。
+11. Harness 生成的 3D 游戏项目可以安装、启动和实际游玩，包含 3D 渲染、玩家控制、目标和反馈，浏览器无关键错误。
+12. 使用公共 npm 搜索，通过 GoodBuddy 捆绑的 npm 安装经审查的最小第三方插件，Host 成功加载并执行其真实工具。
+13. 实际 ACP 路径中 Ask 拒绝该插件工具，Execute 允许该工具，不出现 GoodBuddy 逐工具确认。
+
+测试不得打印、快照或提交 API Key。测试创建的文件只能位于专用临时工作区，并在确认可再现后清理。
+
+### 17.4 项目验证
+
+源码完成后必须运行：
+
+```text
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+涉及发布资源后，还要按可用原生平台运行聚焦的 `release:package` 验证。无法在当前主机执行的目标必须由六平台 CI 验证。
+
+## 18. 验收标准
+
+功能只有同时满足以下条件才算完成：
+
+- `deepseek-harness` 可被保存、选择、检测和显示。
+- Runtime 详情卡内显示状态、路径、版本和当前用户执行权限。
+- Skills 与自定义 MCP 设置可把能力分配给 DeepSeek Harness；请求级 GoodBuddy 内置 MCP 当前不支持分配，并在内置 MCP 卡片中以置灰、未选择状态明确显示。布局、键盘语义、文案和保存回显通过真机检查。
+- DSH 市场初始关闭且不加载 npm 目录；显式开启后可以搜索、安装、启停、配置和移除插件，安装前只出现一次准确的当前用户权限确认。关闭市场后已有启用插件继续运行，重新开启后管理状态不变。
+- Ask 写入测试在 Runtime 边界失败。
+- Ask 可使用已启用的 Main Web Search/Fetch，且插件无法通过同名工具绕过所有权校验。
+- Ask 拒绝任意插件工具，Execute 可调用全部已启用插件工具。
+- Runtime 原生清单只显示 Host/插件原生 Skills，不显示 GoodBuddy 分配项。
+- Execute 工作区内写入成功。
+- Runtime OS 沙箱设置、平台 Runner、启动探测和原生沙箱打包产物均不存在。
+- 取消、超时、切换 Runtime 和退出应用均能回收进程。
+- 多会话不串流、不串权限请求、不串用量。
+- 用户 DSH 配置、`.env`、遥测和 Web UI 未被加载。
+- 一个插件启动失败时 Host 仍可用，失败插件自动停用并在设置中显示。
+- 发布包携带可执行的锁定 npm CLI，安装插件不依赖系统 Node.js/npm。
+- API Key 不进入 Renderer、配置文件、日志、错误文本或测试产物。
+- 全量测试、类型检查、Lint 和生产构建通过。
+- 真实 OpenAI 兼容 Chat Completions 请求成功。
+- 真实请求调用已分配 Skill 和 MCP，并生成、启动和实际游玩一个可用的 3D 游戏项目。
+- 新增第三方许可证和发布校验完整。
+
+## 19. 已知限制
+
+- DeepSeek Harness 底层库当前是 RC，但 GoodBuddy 不自动跟随升级；每次升级都可能要求同步修改内部控制面。
+- Harness 文件和命令工具没有 Runtime OS 隔离，会继承 GoodBuddy 客户端当前用户能够访问的主机资源。
+- 首版不恢复 Harness 原生 Session，Runtime 重启后由 GoodBuddy 历史重建。
+- 图片输入仅在所选模型连接明确声明支持时可用；首版仍不支持知识库、浏览器控制和 Harness Subagent。Web Search/Fetch 仅使用 Main 代理，MCP 仅支持用户分配、Main 代理和 Execute 自动单次授权路径。
+- Harness Subagent、后台 Job、Workflow、Hook 和原生会话监督尚未实现；未来按 Task 聚合到右侧 Runtime 监督栏，不扩张 Composer 工具栏或暴露 Job/Run 层级。
+- 推理、工具和用量扩展属于 GoodBuddy 协议，不是标准 ACP 保证。
+- 市场来自公共 npm 关键字搜索，不是精选目录；包的质量、兼容性和维护状态由发布者负责。
+- 插件安装、初始化、后台生命周期和 Execute 工具使用当前用户权限，不受 Runtime OS 沙箱保护；Ask 只控制模型工具调用。
+- 不支持用户 profile、自定义 Host、任意本地插件路径或 profile patch。
+
+## 20. 自维护与升级策略
+
+GoodBuddy 对该 Runtime 采用内部维护策略：
+
+1. 当前通过验证的 Host、控制协议和依赖锁定随 GoodBuddy 一起版本化。
+2. 不自动跟随 DSH RC、插件 ABI、profile 格式或市场元数据变化；目录只反映 npm 当前精确版本。
+3. 升级前审查实际用户收益、上游 diff、主机工具语义、协议行为、依赖闭包和许可证。
+4. 六个平台的单元、假模型、UtilityProcess、主机执行和真实模型门禁全部通过后才能更新基线。
+5. 若上游方向不再满足 GoodBuddy 用户需求或安全边界，允许维护兼容补丁、替换单个底层包，或逐步移除 DSH 依赖；`goodbuddy/*` 内部协议保持由 GoodBuddy 控制。
+6. GoodBuddy 自身不以进入官方插件目录或服务非 GoodBuddy 客户端为目标；第三方市场兼容仅限当前受测 Cordis 导出和 `dsh.bundle` 声明。
+
+## 21. 备选方案记录
+
+### 21.1 每次调用 `dsh --profile headless`
+
+未采用。它适合一次性任务，但不能满足流式事件、多会话、细粒度取消、权限回传和低延迟复用。
+
+### 21.2 只使用官方 ACP 插件
+
+未采用。取消和一次性权限选择符合需求，但缺少工具、推理、用量和会话释放事件。
+
+### 21.3 只使用官方 SDK JSON-RPC
+
+未采用。事件更完整，但单轮取消和权限回传能力不足。
+
+### 21.4 把全部安全逻辑放进 Harness 子进程
+
+未采用。Harness 子进程属于不可信执行面，不能拥有最终模式授权策略、加密设置和进程回收权限。
+
+### 21.5 把全部控制适配放在 Main
+
+未采用。Main 无法可靠观察 Cordis 内部 Session、Tool、Usage 和权限 seam，只能得到不完整的外部进程行为。
+
+当前选择让双层内部控制面保持 GoodBuddy 私有，同时允许 Main 从受管 Store 向固定 Host 注入标准 Cordis 插件；插件扩展面不会取代 GoodBuddy 的可信 Main 控制权。

docs/features/desktop-pet/README.md

@@ -0,0 +1,50 @@
+# 桌面宠物
+
+桌面宠物是 GoodBuddy 桌面端一个可选的常驻悬浮入口，用于随时发起提问、暂存文件或文字，
+并直观查看当前任务状态。桌面宠物不建立新的对话、任务或执行体系：它只是现有 Conversation、
+Task 和 Runtime 能力的一个轻量触发面和状态镜面。
+
+## 核心边界
+
+- 桌面宠物**不**新增 Ask/Execute 执行通道，也不在自身窗口内直接展示模型回复。快速发起
+  和拖放暂存的内容始终交给主窗口现有输入区确认后发送，从不自动发送或自动执行。
+- 桌面宠物**不**持续读取屏幕内容、剪贴板或全局选中文本。
+- 桌面宠物显示的任务状态、通知和历史记录均来自现有 Task/Conversation 数据，不建立第二套
+  存储或索引。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、范围、功能需求和产品验收 |
+| [User Stories](./user-stories.md) | 首次启用、正常使用、失败恢复、兼容和边界场景 |
+| [功能逻辑](./logic-design.md) | 不变量、状态维度、决策表和失败结果 |
+| [UI 设计](./ui-design.md) | 窗口交互、设置入口、状态呈现、无障碍和响应式行为 |
+| [技术设计](./technical-design.md) | 窗口与进程边界、IPC 边界、持久化、生命周期和验证策略 |
+
+功能尚未实施，因此不创建 `progress.md`；实施开始后按 [`docs/features/AGENTS.md`](../AGENTS.md)
+的证据要求补充。
+
+## 术语
+
+- **桌面宠物窗口**：应用启用该功能后创建的常驻、无边框、可置顶悬浮窗口。
+- **快速发起**：点击宠物打开的小型输入框，用于输入文字或附加单个文件，提交后转入主窗口。
+- **暂存**：快速发起或拖放产生的文字和附件在提交前的中间状态，不代表已发送或已执行。
+- **状态镜面**：宠物窗口对当前任务状态（等待处理、执行中、已完成、失败、空闲）的展示，
+  数据权威来自 Task 与 Conversation，不是独立状态源。
+- **安静模式**：抑制宠物完成/失败气泡提示的设置，可访问的状态查询不受影响。
+
+## 相关功能
+
+- [Task 与 Job 文档集](../task-and-job/README.md)：任务状态、状态优先级和 Task Center
+  导航的权威定义，宠物的状态镜面必须与其保持一致，不重新定义任务生命周期。
+- [助手工作栏](../assistant-workbar/README.md)：主窗口执行空间和输入区的权威定义，宠物的
+  快速发起和拖放暂存最终落地到该输入区，不复制其行为。
+- [直连模型 Agent 能力](../direct-model-agent/README.md)、[远程主机与远程执行](../remote-host/README.md)：
+  Ask/Execute 授权边界的权威定义，宠物不扩大或绕过该边界。
+- [文档处理](../document-processing/README.md)：拖放文件解析和格式支持的权威定义，宠物拖放
+  暂存复用同一处理管线，不重新定义支持类型。
+- 根 [`UI-DESIGN.md`](../../../UI-DESIGN.md)：全局视觉、通知视口、Switch/Checkbox 语义和
+  无障碍规则的权威定义。
+- [`docs/development/release-runbook.md`](../../development/release-runbook.md)：跨平台打包
+  矩阵和交付物的权威定义。

docs/features/desktop-pet/logic-design.md

@@ -0,0 +1,203 @@
+# 桌面宠物功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [桌面宠物 PRD](./prd.md) |
+| User Stories | [桌面宠物 User Stories](./user-stories.md) |
+| 任务模型 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
+
+本文负责桌面宠物自身的状态、不变量和决策规则，不重新定义 Task、Conversation、Ask/
+Execute 或附件的既有语义；这些语义以各自权威文档为准。
+
+## 1. 核心不变量
+
+### INV-1 宠物不是第二条执行通道
+
+快速起草和拖放暂存只产生主窗口会话输入区的草稿数据（文本、附件引用），不产生消息、
+不产生 Task、不触发模型调用。发送、模式选择和 Runtime 选择继续完全由主窗口既有流程
+拥有。
+
+### INV-2 状态镜面是既有状态的投影
+
+宠物状态镜面的取值只能从当前 Task 集合的既有状态推导，不允许引入宠物专属的任务状态
+字段或独立于 Task Center 的状态存储。宠物状态与 Task Center 展示的状态出现分歧即视为
+缺陷。
+
+### INV-3 总开关是唯一的存在性开关
+
+“启用桌面宠物”关闭时，宠物窗口、气泡和托盘条目文案必须整体消失；除该开关外，任何
+子设置（外观、位置、安静模式）的变化都不得单独创建或销毁宠物窗口。
+
+### INV-4 暂时隐藏不影响启用状态
+
+“暂时隐藏”只影响窗口可见性，不修改总开关持久化值，也不清除位置、外观或安静模式设置。
+
+### INV-5 提示与原生通知互斥
+
+同一个任务终态事件（完成或失败）只能产生宠物气泡或现有原生系统通知中的一种，不产生
+两种同时可见的独立提示。
+
+### INV-6 位置始终落在可用显示器内
+
+宠物窗口的持久化位置在应用于当前显示器拓扑之前必须被校验；不能得出宠物窗口完全位于
+任何当前可见显示器之外的最终坐标。
+
+### INV-7 拖放与起草共享暂存规则
+
+拖放产生的文本和文件必须满足与快速起草附件相同的类型、大小、数量限制；两者不允许存在
+两套互不一致的限制值。
+
+## 2. 状态维度
+
+### 2.1 总开关与可见性
+
+```text
+disabled -> enabled_visible
+enabled_visible <-> enabled_hidden        (暂时隐藏 / 重新显示)
+enabled_visible|enabled_hidden -> disabled (关闭总开关)
+```
+
+`disabled` 是唯一没有宠物窗口存在的状态；`enabled_hidden` 窗口不可见但设置全部保留。
+
+### 2.2 快速起草弹出框
+
+```text
+closed -> drafting -> submitted | discarded
+drafting -> closed (Escape / 点击外部 / 关闭按钮)
+```
+
+`submitted` 是终态转换动作，不是持续状态：提交后弹出框立即回到 `closed`，草稿数据已经
+转交给主窗口。
+
+### 2.3 拖放交互
+
+```text
+idle -> drag_over -> dropped_accepted | dropped_rejected | drag_cancelled
+```
+
+`drag_over` 只影响视觉反馈，不产生任何持久数据；只有 `dropped_accepted` 才产生暂存
+数据。`dropped_rejected` 用于文件夹或全部文件超限的场景，不产生暂存也不打开主窗口。
+
+### 2.4 状态镜面
+
+```text
+unavailable | idle | completed_recent | running | waiting_approval | failed_recent
+```
+
+取值由当前活跃与最近终态 Task 集合计算得出，属于派生状态，不单独持久化。
+
+### 2.5 提示气泡
+
+```text
+none -> pending -> shown -> dismissed
+```
+
+`pending` 表示事件已发生但由于主窗口可见或安静模式而被抑制，不进入 `shown`。
+
+## 3. 状态镜面优先级
+
+宠物在任意时刻只呈现一个状态镜面取值。存在多个活跃 Task 时按以下优先级取最高项：
+
+| 优先级 | 状态 | 条件 |
+| --- | --- | --- |
+| 1 | `unavailable` | 用于确认状态的 Runtime 或网络当前不可达 |
+| 2 | `waiting_approval` | 至少一个 Task 处于等待批准 |
+| 3 | `failed_recent` | 至少一个 Task 在最近的“最近失败”窗口内失败，且用户尚未查看 |
+| 4 | `running` | 至少一个 Task 处于执行中 |
+| 5 | `completed_recent` | 至少一个 Task 在最近的“最近完成”窗口内完成，且用户尚未查看 |
+| 6 | `idle` | 以上条件都不满足 |
+
+“最近失败”“最近完成”窗口的具体时长和“已查看”判定属于技术选择，由
+[技术设计](./technical-design.md)基于既有 Task 已读/未读语义确定，不在本文固定具体
+数值。
+
+## 4. 提示归并决策表
+
+| 事件 | 主窗口状态 | 安静模式 | 结果 |
+| --- | --- | --- | --- |
+| 任务完成 | 不可见或未聚焦 | 关闭 | 显示宠物气泡；不触发原生通知 |
+| 任务完成 | 不可见或未聚焦 | 开启 | 不显示气泡；不触发原生通知；仅更新状态镜面 |
+| 任务完成 | 可见并聚焦 | 任意 | 不显示气泡；反馈通过主窗口既有机制呈现 |
+| 任务失败 | 不可见或未聚焦 | 关闭 | 显示宠物气泡并保持可见直到用户查看或关闭 |
+| 任务失败 | 不可见或未聚焦 | 开启 | 不显示气泡；仅更新状态镜面为 `failed_recent` |
+| 任务失败 | 可见并聚焦 | 任意 | 不显示气泡；反馈通过主窗口既有机制呈现 |
+
+“主窗口可见并聚焦”与现有 [`desktop-notification.ts`](../../../src/main/desktop-notification.ts)
+判定原生通知是否触发所使用的条件保持一致，避免宠物和原生通知各自使用不同的可见性
+判定导致同一事件在两处呈现或同时缺失。
+
+## 5. 快速起草与拖放的目标会话决策表
+
+| 场景 | 目标会话 |
+| --- | --- |
+| 主窗口存在当前活跃会话，用户未在弹出框内更改目标 | 该活跃会话 |
+| 用户在弹出框内选择“新建对话” | 提交时新建并激活一个会话 |
+| 主窗口不存在任何会话 | 提交时新建并激活一个会话 |
+| 目标会话在提交前被用户在主窗口中删除 | 视为“不存在任何会话”，回退到新建会话 |
+
+拖放没有目标切换界面，始终采用与快速起草相同的默认目标会话规则。
+
+## 6. 附件与文本限制
+
+快速起草和拖放暂存复用现有聊天附件规则，不定义新的限制数值：
+
+- 单条草稿的附件数量上限、单个附件大小上限、支持的文本与图片类型，与主窗口聊天附件
+  的现有限制一致。
+- 拖放同时包含多个文件时，逐个按上述规则校验；不合规文件被拒绝，不影响合规文件继续
+  暂存。
+- 拖放文件夹被整体拒绝，不做递归展开或部分接受。
+
+## 7. 位置与显示器校验
+
+1. 加载持久化位置后，检查该坐标是否位于当前任一可见显示器的可用区域内。
+2. 位于范围内：直接使用。
+3. 不在范围内（例如记忆的显示器已断开）：改用主显示器上一个默认可见位置，并在下一次
+   用户拖动宠物后覆盖持久化位置。
+4. 开启“贴边”时，拖动释放位置与最近边缘的距离小于吸附阈值即吸附到该边缘；阈值和默认
+   位置的具体数值属于技术选择。
+
+## 8. 失败与恢复
+
+| 场景 | 行为 |
+| --- | --- |
+| 主窗口进程尚未创建或已被销毁 | 提交快速起草或拖放时先创建/恢复主窗口，再写入草稿 |
+| 写入草稿时主窗口窗口对象不可用 | 提交失败，弹出框保留草稿内容供用户重试，不静默丢弃 |
+| 状态查询所需的 Runtime/网络不可达 | 状态镜面显示 `unavailable`，不回退显示 `idle` |
+| 显示器拓扑变化导致位置越界 | 按第 7 节回退到默认可见位置，不隐藏窗口 |
+| 用户在气泡展示期间关闭总开关 | 气泡与宠物窗口一并立即消失 |
+| 应用启动时总开关为开启但窗口创建失败 | 记录失败原因，不阻塞主窗口正常启动，托盘菜单提供重试入口 |
+
+## 9. 需求追踪
+
+| 需求 | 主要逻辑 |
+| --- | --- |
+| `FR-1` | `INV-3`、总开关与可见性状态 |
+| `FR-2` | 位置与显示器校验、`INV-6` |
+| `FR-3` | `INV-1`、快速起草状态、目标会话决策表 |
+| `FR-4` | `INV-1`、`INV-7`、拖放交互状态、附件与文本限制 |
+| `FR-5` | `INV-2`、状态镜面优先级 |
+| `FR-6` | `INV-5`、提示归并决策表 |
+| `FR-7` | 提示归并决策表中安静模式列 |
+| `FR-8` | 位置与显示器校验之外的技术选择，逻辑仅约束持久化立即生效 |
+| `FR-9` | `INV-4`、总开关与可见性状态 |
+| `FR-10` | 快速起草状态中的键盘转换，具体按键映射见 UI 设计 |
+| `FR-11` | `INV-1`、`INV-2`、`INV-7` |
+
+## 10. 逻辑完整性评估
+
+本设计覆盖了启用/关闭、暂时隐藏、快速起草、拖放（含超限和文件夹）、状态镜面优先级、
+提示与原生通知的归并、位置越界恢复、以及主窗口不可用时的失败路径。
+
+未在本文固定、留给技术设计选择的实现细节：
+
+- “最近完成/最近失败”窗口的具体时长和“已查看”判定的确切事件来源。
+- 贴边吸附阈值和默认回退位置的具体像素值。
+- 状态查询的具体轮询或事件驱动机制。
+
+这些是技术选择而非未解决的产品决策：本文的优先级和决策表已经足以在任何取值下保持
+行为一致。

docs/features/desktop-pet/prd.md

@@ -0,0 +1,158 @@
+# 桌面宠物 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用产品 | GoodBuddy Desktop |
+| 关联文档 | [功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md) |
+
+## 1. 背景
+
+GoodBuddy 当前只能通过主窗口发起提问、查看任务和管理执行空间。用户想要快速提问、丢一个
+文件进去，或者只是看一眼任务有没有跑完时，仍必须先唤出并聚焦整个主窗口。这在多任务、多
+显示器场景下打断当前工作流。
+
+桌面宠物提供一个常驻、体积小、不抢焦点的悬浮入口，承担三类高频、轻量的动作：快速起草
+一个问题、拖放文件或文字暂存、以及查看当前任务状态。它不是新的执行通道，只是现有
+Conversation、Task 和 Runtime 能力上的一层轻量触发面和状态镜面。
+
+## 2. 产品目标
+
+1. 用户无需先打开或聚焦主窗口即可起草一条消息或暂存一个文件。
+2. 用户可以在不打开 Task Center 的情况下，一眼看到当前是否有任务在跑、等待处理或失败。
+3. 桌面宠物默认不产生新的干扰：不主动弹窗抢焦点，不重复现有原生通知。
+4. 桌面宠物的开关、位置、外观和提示强度完全由用户控制，且可随时完全关闭并恢复到没有该
+   功能之前的界面状态。
+5. 桌面宠物不新增或绕过 Ask/Execute 授权边界，也不建立第二条消息发送或任务执行路径。
+
+## 3. 功能范围
+
+### 3.1 包含
+
+- 设置中的“桌面宠物”一级分类，包含总开关、外观、位置和提示设置。
+- 常驻悬浮窗口：可拖动、跨显示器记忆位置、贴边、置顶开关。
+- 点击宠物打开的“快速起草”弹出框：输入文字、附加至多一个本机文件，提交后转入主窗口
+  对应会话的输入区草稿，不自动发送。
+- 拖放文字或文件到宠物窗口，效果与快速起草的附件路径一致。
+- 状态镜面：显示当前活跃任务的汇总状态，点击后打开 Task Center 中对应任务。
+- 完成/失败气泡提示，及独立于原生通知的安静模式开关。
+- 从有限的内置角色/外观中选择，调整尺寸、透明度和动画强度。
+- 全局显示/隐藏开关，托盘菜单入口，键盘可达的等效操作路径。
+
+### 3.2 不包含
+
+- 在宠物窗口内直接展示模型回复、执行工具调用或建立第二条 Ask/Execute 通道。
+- 未经用户确认自动发送消息或自动执行任务。
+- 持续读取屏幕内容、剪贴板或系统级选中文本。
+- 用户上传任意自定义头像图片、养成机制、货币或每日签到。
+- 多个宠物实例、宠物之间互动或联网社交功能。
+- 管理员远程强制启用、配置或监控用户的桌面宠物。
+- 替代 Task Center、助手工作栏或现有通知系统的权威数据来源。
+
+## 4. 功能需求
+
+### FR-1 总开关与默认状态
+
+- 设置新增“桌面宠物”一级分类，包含“启用桌面宠物”总开关。
+- 全新安装和现有用户升级后默认关闭，不在未经用户操作时出现在桌面上。
+- 关闭总开关立即隐藏宠物窗口，保留用户此前的位置、外观和提示设置以便重新开启。
+
+### FR-2 常驻悬浮窗口
+
+- 启用后创建一个无边框、默认置顶、不出现在任务栏的小型窗口。
+- 用户可拖动到任意位置；位置按显示器分别记忆，显示器断开重连后回退到最近的可用显示器。
+- 提供“贴边”选项，拖动到屏幕边缘附近时自动吸附。
+- 提供独立的“始终置顶”开关；关闭后宠物仍可见，但可被其他窗口遮挡。
+- 宠物窗口不接受系统级最大化、最小化或调整大小操作。
+
+### FR-3 快速起草
+
+- 点击宠物打开一个紧邻宠物的小型弹出框，包含文本输入和“附加文件”按钮。
+- 文本输入支持多行、粘贴图片；附加文件复用现有附件类型、数量和大小限制。
+- 弹出框显示将要进入的目标：当前活跃会话，或“新建对话”。用户可在弹出框内切换目标，
+  但不能在弹出框内选择模型、Runtime 或 Ask/Execute 模式。
+- 提交后主窗口被显示或聚焦，目标会话被激活，文字和附件作为草稿填入该会话的输入区，
+  输入焦点落在该输入区。提交动作本身不发送消息、不创建任务。
+- 取消或关闭弹出框放弃当前草稿，不影响主窗口任何已有草稿。
+
+### FR-4 拖放暂存
+
+- 用户可以把本机文件或选中文字拖到宠物窗口上。
+- 拖入时宠物给出可放置的视觉反馈；释放后遵循与快速起草提交相同的行为：显示主窗口、
+  激活目标会话、把内容放入该会话输入区草稿。
+- 拖放文件的类型、数量、大小限制与现有聊天附件限制一致；超出限制时明确提示被拒绝的
+  文件，其余合法文件仍正常暂存。
+- 拖放不支持文件夹；文件夹被拖入时提示不支持，不递归展开。
+
+### FR-5 状态镜面
+
+- 宠物在空闲、执行中、等待处理、已完成、失败之间切换外观，反映当前所有活跃 Task 的
+  汇总状态；多个状态并存时按“等待处理 > 失败 > 执行中 > 已完成 > 空闲”的优先级显示。
+- 点击状态镜面打开或聚焦主窗口的 Task Center，并定位到触发当前状态的任务。
+- Runtime 或网络不可用导致任务状态无法确认时，状态镜面显示“状态不可用”而不是回退成
+  “空闲”。
+
+### FR-6 完成与失败提示
+
+- 任务从执行中或等待处理转为已完成或失败，且主窗口不可见或未聚焦时，宠物旁显示一条
+  气泡，说明任务标题和结果。
+- 气泡在用户不操作时于一段时间后自动消失；失败气泡保持可见直到用户查看或手动关闭。
+- 点击气泡等价于点击状态镜面，打开对应任务详情。
+- 同一事件只能触发桌面宠物气泡或现有原生系统通知中的一种，不同时出现两条提示；具体
+  归并规则由[功能逻辑](./logic-design.md)定义。
+
+### FR-7 安静模式
+
+- 独立于总开关的“安静模式”开关，开启后不再显示完成/失败气泡。
+- 安静模式不影响状态镜面本身的外观切换，也不影响原生系统通知的现有行为。
+
+### FR-8 外观与个性化
+
+- 提供数量有限的内置角色供选择，不支持上传自定义图片。
+- 提供尺寸、透明度和动画强度调整；调整立即生效并持久化。
+- 提供“恢复默认外观”操作。
+
+### FR-9 显示、隐藏与退出
+
+- 提供独立于总开关的“暂时隐藏”动作：隐藏宠物窗口但保留启用状态，可通过托盘菜单或
+  设置重新显示。
+- 托盘菜单新增“显示/隐藏桌面宠物”入口，随当前可见性变化文案。
+- 应用退出时宠物窗口一并关闭，不残留独立进程。
+
+### FR-10 键盘可达性
+
+- 宠物窗口本身可通过系统级窗口切换（如 Alt+Tab）取得焦点，取得焦点后可用键盘打开快速
+  起草弹出框、在状态镜面和提示之间移动，并可用 Escape 关闭弹出框。
+- 所有交互提供可访问名称和状态说明，不仅依赖动画或颜色表达状态。
+
+### FR-11 与现有能力的边界
+
+- 快速起草和拖放暂存最终使用主窗口现有的会话、附件、模型和 Ask/Execute 选择逻辑，不
+  新增第二套发送或授权路径。
+- 状态镜面和气泡的任务状态数据来自现有 Task 与 Conversation 记录，不建立独立存储、不
+  与 Task Center 的状态定义产生分歧。
+- 桌面宠物不改变现有全局快捷键、托盘菜单既有条目或主窗口默认行为。
+
+## 5. 产品验收
+
+- 全新安装和已升级用户默认看不到桌面宠物；显式启用后立即出现在预期位置。
+- 关闭总开关后桌面上不再有任何宠物窗口或残留提示，重新开启后恢复此前的位置和外观。
+- 通过快速起草或拖放提交的内容，在主窗口对应会话的输入区中可见为未发送草稿，用户需要
+  自行确认发送；关闭 GoodBuddy 或取消草稿不会产生任何任务或消息记录。
+- 状态镜面呈现的状态与 Task Center 中对应任务的状态一致；两者出现分歧即视为缺陷。
+- 同一任务完成或失败事件不会同时产生宠物气泡和原生系统通知。
+- 安静模式开启时不出现气泡，但状态镜面外观仍随任务状态变化。
+- 键盘用户无需鼠标即可打开快速起草、查看状态并关闭弹出框。
+- 中英文文案、深浅主题、多显示器和 DPI 缩放下宠物窗口位置和内容均正确显示。
+
+## 6. 明确限制
+
+- 桌面宠物不提供在其自身窗口内完成整段对话或查看历史消息的能力；查看完整回复必须进入
+  主窗口。
+- 桌面宠物不支持多实例、多角色同屏或角色之间的模拟互动。
+- 透明背景效果依赖操作系统合成器；在不支持透明合成的 Linux 桌面环境下，宠物窗口可能
+  退化为不透明的小型窗口，具体行为见[技术设计](./technical-design.md)。

docs/features/desktop-pet/technical-design.md

@@ -0,0 +1,335 @@
+# 桌面宠物技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [桌面宠物 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| UI 设计 | [UI 设计](./ui-design.md) |
+
+## 1. 进程与窗口边界
+
+```text
+Main
+  -> createMainWindow()  (既有，src/main/window.ts)
+  -> createPetWindow()   (新增)
+       -> 独立 BrowserWindow：无边框、透明、置顶、不入任务栏
+       -> 独立 preload：src/preload/pet.ts（新增，窄 API）
+       -> 加载独立渲染入口：src/renderer/pet.html + src/renderer/src/pet/
+Renderer（主窗口，既有）
+  -> window.goodbuddy（既有 DesktopApi，不变）
+Renderer（宠物窗口，新增）
+  -> window.goodbuddyPet（新增窄 API，与既有 window.goodbuddy 完全隔离）
+```
+
+宠物窗口是与主窗口平级的第二个 `BrowserWindow`，不是主窗口的子窗口、不是 `WebContentsView`
+叠加层。理由：
+
+- 主窗口现有 `setWindowOpenHandler` 拒绝一切子窗口（`src/main/window.ts`），沿用该策略
+  比引入例外更简单。
+- 宠物窗口需要独立于主窗口的显示/隐藏、位置和置顶状态，作为子窗口会继承父窗口的显示
+  状态，不满足“主窗口隐藏时宠物仍可见”的产品要求。
+
+不复用主窗口的 preload 和渲染入口：主窗口 preload 暴露的 `DesktopApi` 面积很大（对话、
+知识库、设备共享等）。给宠物窗口加载同一 preload 会让一个新增的、长期运行、暴露给
+远程可控网页内容风险更低但攻击面更广的窗口拥有不必要的能力。新增窄 preload 遵循仓库
+现有的“只暴露显式方法”约束。
+
+## 2. 模块职责
+
+| 模块 | 位置 | 职责 |
+| --- | --- | --- |
+| `PetWindowService` | `src/main/pet/pet-window-service.ts`（新增） | 创建/销毁宠物窗口、位置持久化与越界校验、置顶与贴边、显示/隐藏 |
+| `PetSettingsStore` | `src/main/pet/pet-settings-store.ts`（新增） | 总开关、外观、位置、安静模式的持久化，遵循既有 settings-file-utils 模式 |
+| `PetStatusProjector` | `src/main/pet/pet-status-projector.ts`（新增） | 从既有 Task 查询结果计算状态镜面取值，不引入新状态源 |
+| `PetDraftBridge` | `src/main/pet/pet-draft-bridge.ts`（新增） | 把宠物提交的文本/附件转交主窗口渲染进程，驱动会话激活与草稿写入 |
+| `PetNotificationCoordinator` | `src/main/pet/pet-notification-coordinator.ts`（新增） | 与既有 `desktop-notification.ts` 协商同一事件只走一条提示路径 |
+| 既有 `context-manager.ts` | 不变 | 宠物附件校验复用其 `selectFiles`/校验规则，不新增第二套限制 |
+| 既有 `assistant-database.ts` / Task 查询 | 不变 | 状态镜面查询的唯一数据来源 |
+
+`PetStatusProjector` 只读取既有 Task 查询结果并按
+[功能逻辑第 3 节](./logic-design.md#3-状态镜面优先级)的优先级归并，不写入、不缓存跨进程
+重启的状态；重启后状态镜面从当前 Task 集合重新计算。
+
+## 3. 宠物窗口创建
+
+```ts
+// src/main/pet/pet-window-service.ts（示意）
+function createPetWindow(): BrowserWindow {
+  return new BrowserWindow({
+    width: PET_SIZE.width,
+    height: PET_SIZE.height,
+    show: false,
+    frame: false,
+    transparent: true,
+    resizable: false,
+    skipTaskbar: true,
+    alwaysOnTop: true, // 由“始终置顶”设置决定实际值
+    hasShadow: false,
+    backgroundColor: '#00000000',
+    webPreferences: {
+      preload: join(currentDirectory, '../preload/pet.cjs'),
+      contextIsolation: true,
+      nodeIntegration: false,
+      sandbox: true
+    }
+  })
+}
+```
+
+- `transparent: true` 依赖操作系统合成器。按 PRD 6 节明确限制，在不支持透明合成的
+  Linux 桌面环境（例如未运行合成器的部分窗口管理器）下，Electron/Chromium 会把窗口
+  渲染为不透明；`PetWindowService` 不检测合成器能力，只在渲染进程内把背景色设置为
+  当前主题的画布色作为不透明回退，保证内容仍然可读，不尝试探测或声明支持特定合成器。
+- `alwaysOnTop` 的实际值由“始终置顶”Switch 驱动，通过 `window.setAlwaysOnTop(bool)`
+  在设置变更时更新，不需要重建窗口。
+- 复用既有 `resolveWindowIcon`/任务栏排除逻辑作为参考，但宠物窗口 `skipTaskbar: true`
+  固定为真，不提供用户设置。
+- 宠物窗口不设置 `parent`，与主窗口是同级独立窗口；应用单实例锁和 `second-instance`
+  处理（`src/main/index.ts`）不需要改动，因为宠物窗口的存在与否由 `PetWindowService`
+  内部状态决定，而不是第二个 Electron 实例。
+
+## 4. 拖放实现
+
+Electron 渲染进程原生支持 HTML5 拖放；宠物渲染进程监听 `dragenter`/`dragover`/`drop`
+即可获得视觉反馈和释放事件，不需要 Main 参与拖放事件本身。文件路径解析复用既有
+`webUtils.getPathForFile`（已用于 `src/preload/index.ts` 的知识库拖放导入）：
+
+```ts
+// src/preload/pet.ts（示意）
+import { contextBridge, ipcRenderer, webUtils } from 'electron'
+
+contextBridge.exposeInMainWorld('goodbuddyPet', {
+  submitDraft: (input: PetDraftSubmission) =>
+    ipcRenderer.invoke(petIpcChannels.submitDraft, input),
+  resolveDroppedPaths: (files: File[]) =>
+    files.map((file) => webUtils.getPathForFile(file)).filter(Boolean),
+  // ...状态订阅、设置读写等方法
+})
+```
+
+拖入的文本（非文件）通过 `dataTransfer.getData('text/plain')` 直接读取，随普通文本
+字段一起提交，不经过路径解析。
+
+宠物渲染进程把解析出的路径和文本打包为 `PetDraftSubmission`，通过 IPC 交给 Main；Main
+侧的路径校验、类型判断、大小限制和读取，全部复用既有 `ContextManager` 的规则（`src/main/context-manager.ts`
+中的 `supportedExtensions`、`supportedImageExtensions`、`supportedDocumentExtensions`、
+`maximumContextBytes`、`maximumAttachmentsPerMessage`），不新增校验逻辑。`ContextManager`
+目前的公开入口是围绕原生对话框（`selectFiles`）设计的；实现时需要新增一个接受任意
+canonical 路径数组的方法（例如 `stageFromPaths`），内部复用现有扩展名/大小/文档解析
+分支，而不是复制一份判断逻辑。文件夹路径（`fs.stat` 判定为目录）在该方法入口即被拒绝，
+不递归遍历。
+
+## 5. 快速起草提交与主窗口联动
+
+```text
+宠物渲染进程 submitDraft(input)
+  -> Main: PetDraftBridge.handleSubmit(input)
+       -> ContextManager.stageFromPaths(input.filePaths)  (复用既有校验)
+       -> 若主窗口不存在：createMainWindow() + loadMainWindow()（复用既有函数）
+       -> showWindow(mainWindow)（既有函数）
+       -> mainWindow.webContents.send(petIpcChannels.draftReceived, {
+            targetConversationId, text, stagedContextIds
+          })
+  -> 主窗口渲染进程（App.tsx 新增一个事件监听，与既有 conversation:new 监听模式一致）
+       -> 若 targetConversationId 无效或已删除：回退为新建会话（既有新建会话路径）
+       -> 激活目标会话、把 text 写入该会话输入框状态、把 stagedContextIds 追加到该
+          会话的附件状态（既有 App.tsx 附件状态更新路径）
+       -> 聚焦输入框
+```
+
+- 草稿只在主窗口渲染进程内变成“输入框状态”和“待发送附件列表”，与用户手动打字/手动
+  点击附件按钮产生的状态是同一份 React state，不建立并行的草稿存储。这直接满足
+  `INV-1`：宠物不产生消息、不产生 Task。
+- `stagedContextIds` 复用现有 `context:*` IPC 产生的 Context ID；主窗口把这些 ID 加入
+  附件列表的方式，与用户通过“附加文件”按钮选择文件后的状态更新完全一致。
+- 若提交发生时主窗口曾被销毁（用户从未打开过，或者提前研究表明当前架构不销毁主窗口
+  只隐藏），`PetDraftBridge` 调用既有 `createMainWindow`/`loadMainWindow`，等待
+  `ready-to-show` 完成后再发送 `draftReceived`，避免竞态。
+
+## 6. IPC 边界
+
+新增独立 IPC 通道命名空间 `pet:*`，与既有 `ipcChannels` 并列定义在
+`src/shared/ipc-channels.ts`：
+
+```text
+pet:get-snapshot        (设置 + 当前状态镜面取值 + 可见性)
+pet:update-settings      (总开关、外观、贴边、置顶、安静模式)
+pet:submit-draft         (快速起草/拖放提交)
+pet:dismiss-bubble       (关闭完成/失败气泡)
+pet:open-task            (点击状态镜面/气泡，打开 Task Center 对应任务)
+pet:toggle-visibility    (托盘“隐藏/显示桌面宠物”)
+```
+
+- 所有输入使用 `src/shared/pet-contracts.ts`（新增）中的 Zod schema 校验，与既有约定
+  一致。
+- `trusted-ipc-sender.ts` 的 `assertTrustedSender` 按窗口实例参数化使用；宠物窗口的
+  IPC handler 校验 `event.sender === petWindow.webContents`，不能用主窗口的 trusted
+  sender 校验函数验证宠物窗口的请求，也不能反过来。
+- 宠物 preload 不暴露任何既有 `DesktopApi` 方法；需要的能力（提交草稿、读取/写入宠物
+  设置、订阅状态镜面）都通过 `pet:*` 通道单独暴露为 `window.goodbuddyPet` 的具体方法。
+- Main 侧广播状态镜面变化时，只向宠物窗口发送派生后的枚举值（第 3 节的六种状态之一）
+  和最小必要的任务标题/ID，不发送完整 Task 或 Conversation 对象。
+
+## 7. 持久化
+
+新增设置文件，遵循既有 `settings-file-utils.ts` 的原子写入、版本校验和损坏隔离模式，
+不复用 `ApplicationSettingsStore` 或 `ShortcutSettingsStore` 的 schema：
+
+```text
+pet-settings.json
+{
+  version: 1,
+  enabled: boolean,
+  quietMode: boolean,
+  alwaysOnTop: boolean,
+  snapToEdge: boolean,
+  appearance: { character: string, size: 'small'|'medium'|'large',
+                opacity: number, motion: 'off'|'reduced'|'full' },
+  position: { displayId: number, x: number, y: number } | null
+}
+```
+
+- `position` 为 `null` 表示尚未被用户拖动过，使用默认位置计算规则（第 8 节）。
+- `displayId` 使用 Electron `screen.getAllDisplays()` 返回的 `id`；加载时按第 8 节校验，
+  不假设跨重启保持稳定的显示器 id 一定仍然存在。
+- 独立 schema 版本号（从 1 开始），与主设置版本号互不影响；未来变更只需要迁移这一个
+  文件。
+- 是否需要独立数据库表：不需要。宠物没有需要查询、筛选或跨设备同步的历史数据，一个
+  JSON 文件足够，符合仓库 KISS/YAGNI 约束。
+
+## 8. 位置与多显示器校验
+
+```ts
+function resolvePetPosition(
+  saved: PetPosition | null,
+  displays: Display[]
+): { x: number; y: number } {
+  if (saved) {
+    const display = displays.find((d) => d.id === saved.displayId)
+    if (display && pointWithinWorkArea(saved, display.workArea)) {
+      return saved
+    }
+  }
+  const primary = screen.getPrimaryDisplay()
+  return defaultPositionWithin(primary.workArea) // 例如右下角，留出安全边距
+}
+```
+
+- 该函数在宠物窗口创建时以及 `display-added`/`display-removed`/`display-metrics-changed`
+  事件触发时调用；越界立即调用 `window.setPosition` 校正，不等待用户下一次拖动。
+- 用户拖动结束（`moved` 事件）时把当前 `getBounds()` 和 `screen.getDisplayNearestPoint`
+  得到的 `displayId` 写入 `PetSettingsStore`，去抖后原子写入，避免拖动过程中高频写盘。
+- 贴边吸附在渲染进程拖动过程中做视觉预判（不移动实际窗口，只显示吸附提示），在
+  `moved` 事件的最终位置上由 Main 一次性计算是否落入吸附阈值并调用 `setPosition`
+  吸附到边缘，阈值和默认位置的具体像素值作为实现细节调优，不在此固定。
+
+## 9. 状态镜面查询
+
+`PetStatusProjector` 不新增事件源，而是订阅既有 Task 变化通知（主窗口渲染进程已经
+用于更新 Task Center 和会话内任务卡片的同一套 Main → Renderer 事件）在 Main 侧的
+对应版本，或者在 Main 侧直接查询 `assistant-database.ts` 暴露的 Task 读取方法。具体
+选择两者之一属于实现阶段的技术选择，约束条件是：
+
+- 不引入宠物专属的任务状态表或缓存；查询/订阅的结果必须与 Task Center 在同一时刻
+  展示的状态一致。
+- 查询开销必须是有界的（只统计活跃与最近终态 Task 的数量和状态，不拉取消息正文）。
+- Runtime/网络不可达导致查询失败时返回 `unavailable`，不静默返回 `idle`。
+
+“最近完成”“最近失败”窗口时长和“已查看”判定：复用 Task 已有的已读/查看时间戳字段
+（若既有模型已提供）；若当前模型没有这类字段，实现时以“该 Task 终态发生后，用户是否
+已经点击过对应的宠物气泡或状态镜面，或已经在 Task Center 中打开过该 Task”作为已查看
+判定，窗口时长建议与现有原生通知的展示逻辑保持同量级（分钟级），具体数值在实现时
+根据既有 Task 事件粒度确定。
+
+## 10. 提示与原生通知协商
+
+`PetNotificationCoordinator` 与 `desktop-notification.ts` 的 `showDesktopNotificationWhenUnfocused`
+共享同一个“主窗口是否可见并聚焦”判定：
+
+```ts
+function shouldSuppressBecauseMainWindowVisible(mainWindow: BrowserWindow): boolean {
+  return !mainWindow.isDestroyed() && mainWindow.isFocused()
+}
+```
+
+- 现有 `showDesktopNotificationWhenUnfocused` 已经使用等价条件（`window.isFocused()`）
+  决定是否弹出原生通知；`PetNotificationCoordinator` 复用同一判定函数（如需要，提取为
+  共享工具），保证两者的“可见性”定义永远一致，不出现原生通知判定为可见但宠物判定为
+  不可见（或反之）导致同一事件同时出现两条提示或完全没有提示的情况。
+- 实现层面：调用触发通知的代码路径在决定“原生通知 vs 宠物气泡”时二选一，而不是
+  两者分别独立判断后都可能触发；例如由现有触发点先判断安静模式和宠物启用状态，
+  为真则调用 `PetNotificationCoordinator`，否则调用现有 `showDesktopNotificationWhenUnfocused`。
+- 安静模式开启时，两者都不触发；状态镜面仍照常更新（状态镜面更新走独立的
+  `pet:get-snapshot`/推送通道，不经过通知协商）。
+
+## 11. 与既有模块集成
+
+- 快速起草和拖放最终只调用主窗口渲染进程已有的“设置输入框文本”“追加附件”“激活
+  会话”“创建新会话”状态更新函数，不新建与 Ask/Execute、模型选择、Runtime 选择相关
+  的任何路径。
+- 点击状态镜面/气泡打开 Task Center 复用现有 Task Center 导航（既有 IPC/路由，与托盘
+  “新建对话”发送 `conversation:new` 事件属于同一类模式：Main 发送一个事件，主窗口
+  渲染进程消费并完成导航）。
+- 托盘菜单新增项复用现有 `Menu.buildFromTemplate` 结构（`src/main/index.ts` 的
+  `buildTray`），插入一个受当前可见性状态驱动的条目，不重写整个菜单构建函数。
+- 全局快捷键（`src/shared/shortcut.ts`、`shortcut-settings-service.ts`）不受影响，
+  桌面宠物不注册新的全局快捷键，因为激活方式是点击窗口本身或系统级窗口切换，不需要
+  额外抢占全局按键空间。
+
+## 12. 生命周期
+
+- 应用启动读取 `PetSettingsStore`；`enabled: true` 时在既有服务和 IPC 注册完成后创建
+  宠物窗口（与主窗口创建顺序一致，不阻塞主窗口 `ready-to-show`）。
+- 宠物窗口创建失败（例如极端情况下操作系统拒绝创建透明窗口）：记录原因，不阻塞主窗口
+  启动，托盘“显示桌面宠物”下次点击时重试创建。
+- 应用退出（`before-quit`/既有 `isQuitting` 标记）时，宠物窗口与主窗口一并销毁，不需要
+  独立的关闭确认或延迟清理，因为宠物窗口没有正在进行的网络连接或未保存状态：草稿已经
+  转交主窗口的那一刻起就属于主窗口生命周期。
+- “暂时隐藏”只调用 `window.hide()`，不销毁窗口实例，重新显示直接 `showWindow` 复用
+  既有实例，避免频繁创建/销毁透明窗口带来的闪烁。
+
+## 13. 打包
+
+- 宠物渲染入口（HTML、内置角色素材）加入 `electron.vite.config.ts` 的 renderer 构建
+  输入（现有配置已有 `input` 多入口结构，参考现有主渲染入口的声明方式新增一项）。
+- 内置角色素材（数量有限的静态图片/精灵图）作为打包资源加入 `package.json` 的 `files`/
+  `extraResources`，不通过运行时网络下载，符合仓库“不新增远程资源请求”的字体/资源
+  约束的同一精神。
+- 新增 preload 产物（`pet.cjs`）需要加入 `electron.vite.config.ts` 的 main/preload 构建
+  `entryFileNames` 规则，与现有主 preload 产物并列。
+- 六个标准打包目标（Windows/macOS/Linux × x64/arm64）均需验证宠物窗口可创建、透明或
+  回退不透明背景符合第 3 节预期；LoongArch 预览目标不单独验证，遵循仓库现有策略。
+
+## 14. 验证策略
+
+### 14.1 自动化
+
+- `PetSettingsStore` 的默认值、原子写入、损坏隔离和版本校验（沿用
+  `settings-file-utils.ts` 现有测试模式）。
+- `resolvePetPosition` 在显示器存在/不存在/坐标越界三种输入下的返回值。
+- `PetStatusProjector` 按第 3 节优先级表在各种 Task 组合输入下的输出。
+- `PetNotificationCoordinator` 与 `desktop-notification.ts` 共享判定函数在“可见并聚焦”
+  “不可见”“安静模式开启”组合下只触发一条路径或都不触发。
+- `ContextManager.stageFromPaths`（新增方法）对合法文件、超限文件、不支持类型、文件夹
+  路径的分支覆盖，复用现有 `context-manager` 测试基础设施。
+- `pet:*` IPC handler 的 trusted sender、schema 校验和错误码。
+- 快速起草提交后主窗口渲染进程状态更新的单元测试：目标会话激活、文本写入、附件追加、
+  草稿被丢弃时不产生 Task 或消息记录。
+
+### 14.2 真实环境
+
+- Windows、macOS、Linux 至少各一次验证宠物窗口创建、拖动、贴边吸附、透明或回退背景的
+  实际渲染效果。
+- 真实拖放一个合法文件、一个超限文件、一个文件夹到宠物窗口，确认 UI 设计第 4.3 节的
+  反馈和最终主窗口状态符合预期。
+- 真实触发一次任务完成和一次任务失败，在“主窗口隐藏”“主窗口可见”“安静模式开启”
+  三种组合下确认气泡和原生通知的出现符合第 10 节的互斥规则。
+- 多显示器插拔场景下确认位置回退逻辑（断开记忆显示器后宠物仍可见）。
+- 打包后的应用在六个标准目标上完成启用、拖动、快速起草、退出流程的一次冒烟验证。
+
+设计文档完成不代表功能实施或上述验证通过。

docs/features/desktop-pet/ui-design.md

@@ -0,0 +1,207 @@
+# 桌面宠物 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [桌面宠物 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文定义设置中的“桌面宠物”页面和独立宠物窗口的界面。所有颜色、间距、字体、通知、
+Switch/Checkbox、焦点和响应式规则以全局设计系统为准；宠物窗口是应用内唯一不使用标准
+`PageShell` 的持久界面，其例外范围在第 4 节明确限定。
+
+## 1. 设置页面信息架构
+
+设置中心新增“桌面宠物”一级分类，使用 `standard` PageShell，不使用页签，按以下顺序
+纵向排列：
+
+```text
+桌面宠物
+在桌面上保留一个轻量入口，随时起草消息、拖入文件或查看任务状态
+
+启用桌面宠物                                        [Switch 关]
+关闭后不在桌面上显示任何宠物窗口或提示
+
+—— 以下设置仅在启用后可编辑，保持可见但降低强调度 ——
+
+外观
+角色        [分段选择：三到四个内置角色缩略图]
+尺寸        [滑块 小 · 中 · 大]
+透明度      [滑块]
+动画强度    [滑块 关闭 · 轻量 · 完整]
+                                              [恢复默认外观]
+
+位置与窗口
+始终置顶                                            [Switch 开]
+贴边吸附                                            [Switch 开]
+
+提示
+安静模式（不显示完成 / 失败气泡）                    [Switch 关]
+```
+
+- 总开关是本页唯一决定宠物窗口存在与否的控件，符合 `INV-3`；其余控件在总开关关闭时
+  保持可见但不可交互，说明文字保持“关闭后不在桌面上显示任何宠物窗口或提示”。
+- 二元持久状态一律使用共享 Switch；角色选择使用共享 `SegmentedControl`（3-4 个内置
+  角色，符合数量上限）；尺寸、透明度和动画强度使用标准滑块控件并显示当前取值。
+- “恢复默认外观”只重置本区域三项外观设置，不改变总开关、位置或安静模式，与
+  [功能逻辑](./logic-design.md) 中“恢复默认外观”的范围一致。
+- 页面不提供“立即显示 / 隐藏”按钮：暂时隐藏的入口固定放在托盘菜单，避免在设置页和
+  托盘中出现两个含义相近但状态不同步的控件。
+
+## 2. 首次启用与关闭反馈
+
+- 开启总开关后宠物窗口在默认位置出现，不产生任何应用通知或原生通知，因为这是用户刚
+  完成的显式操作，结果已经可见。
+- 关闭总开关后宠物窗口和任何气泡立即消失；设置页本身不产生额外通知。
+- 外观、位置相关 Switch 和滑块的变更立即生效并持久化，失败时通过应用通知报告，不静默
+  丢弃用户输入。
+
+## 3. 托盘入口
+
+- 托盘菜单在“新建对话”与“设置”之间新增一项，文案随当前可见性变化：
+  - 已启用且可见：“隐藏桌面宠物”。
+  - 已启用但隐藏：“显示桌面宠物”。
+  - 未启用：“显示桌面宠物”，点击后等同于在设置中开启总开关并显示窗口。
+- 该菜单项不复制设置页的开关语义，只切换可见性；未启用状态下点击才会连带开启总开关，
+  行为需要在可访问名称或菜单说明中明确，避免用户误以为它只是显示/隐藏。
+
+## 4. 宠物窗口
+
+宠物窗口是无边框、透明背景、不可缩放的持久悬浮窗口，不使用 `PageShell`、不属于标准
+一级页面，因此以下规则专属于该窗口：
+
+```text
+┌───────────┐
+│   角色      │ ← 状态镜面：角色外观随任务状态切换
+│  (idle)    │
+└───────────┘
+```
+
+- 窗口本身没有标题栏、边框或系统窗口控件；关闭宠物只能通过设置总开关、托盘“隐藏桌面
+  宠物”或退出应用完成，窗口自身不提供关闭按钮，避免与“暂时隐藏”“关闭功能”两种含义
+  混淆。
+- 窗口整体可拖动；拖动过程中显示当前吸附意图（开启贴边时，接近边缘会有轻微吸附反馈）。
+- 窗口右键菜单提供“快速起草”“暂时隐藏”“打开设置”“退出 GoodBuddy”，与托盘菜单保持
+  同一套文案。
+
+### 4.1 状态镜面外观
+
+宠物角色在以下六种取值间切换，取值定义见[功能逻辑](./logic-design.md) 第 3 节：
+
+| 状态 | 视觉表达 | 可访问名称 |
+| --- | --- | --- |
+| `unavailable` | 角色显示为暗淡的问号叠加 | “任务状态当前不可用” |
+| `idle` | 角色静止或轻微待机动作 | “没有进行中的任务” |
+| `running` | 角色显示持续的工作动作 | “有任务正在执行” |
+| `waiting_approval` | 角色举牌或举手动作，带醒目但非警示色的强调 | “有任务等待你的确认” |
+| `completed_recent` | 角色短暂展示完成动作后回到待机 | “有任务刚刚完成” |
+| `failed_recent` | 角色显示明显区别于完成的姿态，并叠加警示色边缘 | “有任务失败，需要查看” |
+
+- 状态表达必须同时使用动作/姿态和可访问名称两种信号，不能只依赖颜色区分
+  `completed_recent` 与 `failed_recent`。
+- `prefers-reduced-motion` 或用户将动画强度设为“关闭”时，状态切换只改变静态姿态和颜色
+  强调，不播放位移或缩放动画。
+- 点击状态镜面区域（角色本体）触发 US-D4：显示并聚焦主窗口，Task Center 定位到触发
+  当前状态的任务；`idle` 和 `unavailable` 状态下点击等同于显示并聚焦主窗口，不做定位。
+
+### 4.2 快速起草弹出框
+
+点击宠物打开的弹出框锚定在宠物窗口旁（自动避开屏幕边缘），结构如下：
+
+```text
+发送到：[当前会话名称 v]
+
+[多行文本输入，占位文案“输入消息，或拖入文件…”]
+
+[📎 附加文件]  [已附加：contract.docx  ×]
+
+              [取消]  [提交]
+```
+
+- “发送到”是一个富信息单选菜单，选项为当前活跃会话与“新建对话”，遵循全局设计系统
+  第 6.11 节的单选选择器规则；默认选中当前活跃会话。
+- 文本输入支持多行、`Ctrl+V` 粘贴图片和文字，与主窗口聊天输入框的粘贴行为一致。
+- 附加文件按钮打开原生文件选择；已附加文件以行内标签形式展示，可单独移除。
+- 拒绝的文件（超限或不支持）在附件区下方以就地错误文字展示，不使用应用级通知，因为
+  这是与当前操作直接绑定的字段级反馈。
+- “提交”把文本和附件转交目标会话的输入区草稿，随后关闭弹出框；提交过程中禁用重复
+  点击并显示进行中状态，成功后不额外弹出通知（主窗口的显现和草稿本身就是反馈）。
+- “取消”或点击弹出框外部或按 Escape 关闭弹出框并丢弃草稿，焦点返回宠物窗口。
+- 弹出框打开时焦点进入文本输入；Tab 顺序为文本输入 → 附加文件 → 已附加文件的移除
+  按钮 → 取消 → 提交；关闭后焦点回到宠物窗口本体。
+
+### 4.3 拖放反馈
+
+- 文件或文字拖入宠物窗口范围时，窗口整体出现可放置的高亮边框和轻微放大反馈。
+- 释放后立即按第 4.2 节“提交”的相同路径处理，不额外弹出确认框；这保持“拖动=起草并
+  发送到会话输入区（而非立即发送消息）”的一致语义。
+- 拖入文件夹或全部文件超限时，宠物短暂显示拒绝反馈（边框变为警示色并伴随简短文字
+  提示，例如“不支持文件夹”），不打开主窗口、不产生暂存。
+- 部分文件超限、部分合法时，合法文件正常处理，超限文件的名称通过一条会在数秒后自动
+  消失的就地提示列出，不使用应用级通知（拖放是即时操作，反馈应贴近操作发生的位置）。
+
+### 4.4 完成 / 失败气泡
+
+```text
+┌─────────────────────────────┐
+│ ✓ 已完成                      │
+│ 合同风险检查                    │
+│                          [×] │
+└─────────────────────────────┘
+      ▲
+   （角色）
+```
+
+- 气泡锚定在宠物窗口旁，方向随宠物在屏幕上的位置自动避开边缘。
+- 完成气泡在约 4.5 秒后自动消失，与全局应用通知的成功/信息时长一致；失败气泡保持可见
+  直到用户点击查看或点击关闭按钮。
+- 气泡本体可点击，等同于点击状态镜面：显示并聚焦主窗口并定位到对应任务。
+- 关闭按钮 `[×]` 有独立可访问名称（“关闭提示”），不与气泡主体的点击目标冲突：点击
+  关闭按钮只关闭气泡，不导航到主窗口。
+- 气泡使用 `status`/polite 实时区域播报完成，失败气泡使用 `alert`/assertive，与全局
+  设计系统的通知语义保持一致，即使气泡本身不是应用通知视口的一部分。
+
+## 5. 与应用通知视口的关系
+
+- 宠物气泡是应用通知视口的窗口外等价物，只在主窗口不可见/未聚焦且安静模式关闭时出现；
+  同一事件不会同时进入应用通知视口和宠物气泡，具体归并规则见
+  [功能逻辑](./logic-design.md) 第 4 节。
+- 快速起草和拖放产生的字段级错误（附件超限、不支持类型）始终就地展示在宠物窗口或弹出
+  框内，不进入应用通知视口，保持“就地错误”与“全局通知”分工一致。
+
+## 6. 无障碍
+
+- 状态镜面、气泡和弹出框内的所有交互元素都有持久可访问名称，不依赖占位文案代替标签。
+- 宠物窗口可通过系统级窗口切换获得焦点；获得焦点后：
+  - 预期的激活键（例如 Enter 或 Space）打开快速起草弹出框。
+  - 弹出框内 Tab 顺序遵循第 4.2 节。
+  - Escape 关闭当前打开的弹出框或气泡，焦点回到宠物窗口本体。
+- 状态镜面的状态变化通过 `status`/polite 实时区域播报简短说明，避免因动画本身无法被
+  屏幕阅读器感知而丢失信息；不对每次动画帧重复播报。
+- 焦点环、危险色使用和触控目标尺寸遵循全局设计系统第 11 节的通用要求。
+
+## 7. 响应式与多显示器
+
+- 宠物窗口尺寸不随主窗口大小变化；用户通过设置中的“尺寸”滑块单独控制。
+- 宠物窗口位置按显示器分别记忆；显示器不可用时的回退规则见
+  [功能逻辑](./logic-design.md) 第 7 节，界面表现为宠物出现在主显示器的默认可见位置，
+  不出现在屏幕之外或不可见状态。
+- 弹出框和气泡的锚定方向根据宠物当前位置与屏幕边缘的距离自动选择展开方向（上/下/左/
+  右），确保始终完整可见，不被裁切到屏幕外。
+
+## 8. 深浅主题
+
+- 弹出框、气泡和设置页控件复用全局语义令牌，不新增页面专属颜色。
+- 宠物角色素材本身分别提供适配浅色和深色桌面背景的版本，避免透明背景下角色轮廓在深色
+  桌面壁纸上难以辨认；具体资源交付方式属于技术设计范畴。
+
+## 9. 固定词汇
+
+使用“桌面宠物”“启用桌面宠物”“暂时隐藏”“快速起草”“安静模式”“状态镜面”，定义见
+[README](./README.md) 术语表。不使用“挂件”“桌宠助手”或其他未在术语表中定义的别名，
+保持中文文案统一。

docs/features/desktop-pet/user-stories.md

@@ -0,0 +1,255 @@
+# 桌面宠物 User Stories
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [桌面宠物 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+
+## 角色
+
+- **日常用户**：在多任务、多显示器场景下使用 GoodBuddy 处理日常工作。
+- **首次体验用户**：刚升级或安装 GoodBuddy，尚未接触过桌面宠物功能。
+- **键盘用户**：主要通过键盘操作，可能同时使用屏幕阅读器。
+- **多显示器用户**：使用两个或更多显示器，可能随时插拔外接显示器。
+
+## US-A 首次启用
+
+### US-A1 默认不出现
+
+**Given** 用户全新安装或刚升级 GoodBuddy
+**When** 用户尚未进入“桌面宠物”设置
+**Then** 桌面上不出现任何宠物窗口，托盘菜单显示“显示桌面宠物”而非“隐藏”
+
+### US-A2 首次启用
+
+**Given** 用户在设置中打开“启用桌面宠物”总开关
+**When** 开关切换为开启
+**Then** 宠物窗口在默认位置出现，使用默认外观，且不产生任何应用级或原生通知
+
+### US-A3 关闭后完全消失
+
+**Given** 桌面宠物已启用并可见
+**When** 用户关闭“启用桌面宠物”总开关
+**Then** 宠物窗口立即消失，未完成的气泡提示一并消失，托盘菜单条目恢复为“显示桌面宠物”，
+且用户之前设置的位置、外观和提示偏好被保留供下次开启时使用
+
+## US-B 快速起草
+
+### US-B1 起草文字并转入主窗口
+
+**Given** 桌面宠物已启用，主窗口当前隐藏
+**When** 用户点击宠物并输入一段文字后点击提交
+**Then** 主窗口被显示并聚焦，目标会话的输入区出现刚输入的文字作为草稿，输入焦点落在
+该输入区，且没有任何消息被发送、没有任何任务被创建
+
+### US-B2 起草时附加文件
+
+**Given** 快速起草弹出框已打开
+**When** 用户点击“附加文件”并选择一个受支持类型和大小内的文件
+**Then** 该文件在弹出框内显示为待提交附件；提交后该附件出现在主窗口对应会话输入区的
+待发送附件列表中
+
+### US-B3 附加不受支持的文件
+
+**Given** 快速起草弹出框已打开
+**When** 用户选择一个超出大小限制或类型不受支持的文件
+**Then** 弹出框就地显示明确的拒绝原因，不添加该文件，且不影响已经添加的其他文字或附件
+
+### US-B4 取消起草
+
+**Given** 用户已在快速起草弹出框中输入文字或添加附件
+**When** 用户点击取消或按 Escape 关闭弹出框
+**Then** 弹出框关闭且草稿被丢弃，主窗口任何会话的现有草稿不受影响，且不创建任何草稿或
+任务记录
+
+### US-B5 选择目标会话
+
+**Given** 主窗口当前存在多个会话，且用户在快速起草弹出框中看到默认目标会话
+**When** 用户在弹出框内切换目标为“新建对话”
+**Then** 提交后主窗口创建并激活一个新会话，草稿内容进入该新会话的输入区，不影响原有
+会话的草稿
+
+## US-C 拖放暂存
+
+### US-C1 拖放单个文件
+
+**Given** 桌面宠物已启用并可见
+**When** 用户从文件管理器拖动一个受支持类型的文件到宠物窗口上并释放
+**Then** 宠物在拖入过程中显示可放置的视觉反馈，释放后主窗口被显示并聚焦，该文件出现在
+目标会话输入区的待发送附件列表中
+
+### US-C2 拖放多个文件，部分超限
+
+**Given** 用户同时拖动数量或大小超出限制的多个文件到宠物窗口
+**When** 用户释放拖放
+**Then** 合法文件正常进入目标会话的待发送附件列表，超限或不支持的文件被单独列出拒绝
+原因，不阻止合法文件被暂存
+
+### US-C3 拖放文件夹
+
+**Given** 用户拖动一个文件夹到宠物窗口
+**When** 用户释放拖放
+**Then** 宠物提示不支持文件夹，不递归展开文件夹内容，也不产生任何暂存
+
+### US-C4 拖放选中文字
+
+**Given** 用户在其他应用中选中一段文字并拖动到宠物窗口
+**When** 用户释放拖放
+**Then** 该文字进入目标会话输入区的草稿文本，行为与快速起草输入文字一致
+
+## US-D 状态镜面
+
+### US-D1 查看空闲状态
+
+**Given** 当前没有任何活跃 Task
+**When** 用户查看宠物外观
+**Then** 宠物显示空闲状态，且可访问名称明确说明当前没有进行中的任务
+
+### US-D2 查看执行中状态
+
+**Given** 有一个 Task 处于执行中
+**When** 用户查看宠物外观
+**Then** 宠物切换为执行中状态，且该状态与 Task Center 中该任务的状态一致
+
+### US-D3 多任务状态优先级
+
+**Given** 同时存在一个等待处理的任务和一个执行中的任务
+**When** 用户查看宠物外观
+**Then** 宠物按照“等待处理优先于执行中”的规则显示等待处理状态
+
+### US-D4 点击状态镜面打开任务详情
+
+**Given** 宠物当前显示执行中或失败状态
+**When** 用户点击宠物的状态镜面区域
+**Then** 主窗口被显示并聚焦，Task Center 定位到触发当前状态的具体任务
+
+### US-D5 状态不可用
+
+**Given** 用于确认任务状态的 Runtime 或网络当前不可用
+**When** 用户查看宠物外观
+**Then** 宠物显示“状态不可用”，不回退显示为空闲或执行中
+
+## US-E 完成与失败提示
+
+### US-E1 主窗口不可见时收到完成提示
+
+**Given** 主窗口当前隐藏或未聚焦，安静模式未开启
+**When** 一个任务从执行中变为已完成
+**Then** 宠物旁出现说明任务标题和结果的气泡，且该事件不重复触发原生系统通知
+
+### US-E2 失败提示保持可见
+
+**Given** 主窗口当前隐藏，安静模式未开启
+**When** 一个任务失败
+**Then** 宠物旁出现失败气泡并保持可见，直到用户点击查看或手动关闭，不自动消失
+
+### US-E3 主窗口可见时不重复提示
+
+**Given** 主窗口当前可见并聚焦
+**When** 一个任务完成或失败
+**Then** 不出现宠物气泡；反馈通过主窗口现有机制呈现，避免同一事件重复出现在两个位置
+
+### US-E4 开启安静模式
+
+**Given** 用户在设置中开启“安静模式”
+**When** 之后任意任务完成或失败，且主窗口不可见
+**Then** 不出现任何宠物气泡，但状态镜面外观仍随任务状态正常变化
+
+## US-F 位置、外观与多显示器
+
+### US-F1 记忆位置
+
+**Given** 用户把宠物拖动到某个显示器的特定位置
+**When** 用户重启 GoodBuddy
+**Then** 宠物出现在同一显示器的同一位置
+
+### US-F2 显示器断开后回退
+
+**Given** 宠物位置记忆在一个已插入的外接显示器上
+**When** 该外接显示器被移除后重新启动 GoodBuddy
+**Then** 宠物出现在当前可用的主显示器上一个可见、不越界的位置，而不是不可见或位于屏幕
+之外
+
+### US-F3 贴边吸附
+
+**Given** 用户开启“贴边”选项
+**When** 用户把宠物拖动到接近屏幕边缘的位置并释放
+**Then** 宠物自动吸附到屏幕边缘，且吸附后仍可被再次拖动离开
+
+### US-F4 调整外观
+
+**Given** 用户在设置中调整宠物尺寸、透明度或动画强度
+**When** 用户改变任意一项取值
+**Then** 宠物外观立即按新取值更新，且设置持久化，重启后保持
+
+### US-F5 恢复默认外观
+
+**Given** 用户已经修改过角色、尺寸、透明度或动画强度
+**When** 用户点击“恢复默认外观”
+**Then** 上述设置全部恢复为默认值，宠物位置和总开关状态不受影响
+
+## US-G 暂时隐藏与托盘
+
+### US-G1 暂时隐藏
+
+**Given** 桌面宠物已启用并可见
+**When** 用户从托盘菜单选择“隐藏桌面宠物”
+**Then** 宠物窗口消失，总开关状态和其他设置不变，托盘菜单条目变为“显示桌面宠物”
+
+### US-G2 重新显示
+
+**Given** 桌面宠物已启用但当前隐藏
+**When** 用户从托盘菜单选择“显示桌面宠物”
+**Then** 宠物窗口在此前记忆的位置重新出现
+
+### US-G3 应用退出
+
+**Given** 桌面宠物已启用并可见
+**When** 用户退出 GoodBuddy
+**Then** 宠物窗口一并关闭，不留下任何独立运行的进程或残留窗口
+
+## US-H 键盘与无障碍
+
+### US-H1 键盘打开快速起草
+
+**Given** 桌面宠物窗口通过系统级窗口切换取得焦点
+**When** 键盘用户按下预期的激活键
+**Then** 快速起草弹出框打开，焦点进入输入框
+
+### US-H2 键盘关闭弹出框
+
+**Given** 快速起草弹出框已打开且有键盘焦点
+**When** 用户按下 Escape
+**Then** 弹出框关闭，焦点回到宠物窗口本身
+
+### US-H3 屏幕阅读器状态说明
+
+**Given** 用户使用屏幕阅读器
+**When** 焦点移动到宠物的状态镜面
+**Then** 屏幕阅读器播报当前状态的文字说明，不仅依赖颜色或动画表达状态
+
+## US-I 兼容与边界
+
+### US-I1 升级用户保持现状
+
+**Given** 已在使用 GoodBuddy 且从未接触过桌面宠物功能的用户升级到包含该功能的版本
+**When** 用户正常启动应用
+**Then** 桌面宠物保持关闭，界面和行为与升级前一致
+
+### US-I2 不支持透明合成的环境
+
+**Given** 用户的操作系统或桌面环境不支持窗口透明合成
+**When** 用户启用桌面宠物
+**Then** 宠物窗口退化为不透明的小型窗口而不是渲染异常或无法显示，具体规则见
+[技术设计](./technical-design.md)
+
+### US-I3 拖放到非目标区域
+
+**Given** 用户尝试把文件拖到宠物窗口之外的桌面区域
+**When** 用户释放拖放
+**Then** GoodBuddy 不接收该拖放，不产生任何暂存或错误提示

docs/features/device-sharing/README.md

@@ -0,0 +1,28 @@
+# 设备发现与共享
+
+本功能是 GoodBuddy 桌面端管理附近设备、本机共享和 ShareServer 连接的唯一入口。默认连接
+方式是局域网；网关由用户额外添加。功能不包含 ShareServer 的组织管理 Web 界面。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、范围、功能需求和产品验收 |
+| [功能逻辑](./logic-design.md) | 不变量、状态、授权优先级和失败结果 |
+| [UI 设计](./ui-design.md) | 设置入口、四个页签、配对与调用交互 |
+| [技术设计](./technical-design.md) | Desktop 进程边界、持久化、IPC、网络和验证 |
+| [共享网络总体设计](../../architecture/share-network-architecture.md) | 跨端身份、能力、授权、任务、更新和协议权威 |
+
+当前没有单独的 User Stories：正常、失败、撤销、权限和兼容场景已直接进入 PRD 验收与逻辑
+决策表。功能尚未实施，因此不创建 `progress.md`。
+
+## 术语
+
+- **附近设备**：同一局域网内主动广播 GoodBuddy 共享服务的设备。
+- **已配对设备**：双方确认设备指纹后建立点对点信任的设备。
+- **网关连接**：本机与某个 ShareServer 中特定组织身份的连接。
+- **本机共享**：由本机作为提供者发布给 Peer 或组织的能力。
+- **远端能力**：由其他设备或组织提供、本机可以查看或调用的能力。
+
+SSH 远程项目是用户明确配置 Host 后操作远端工作区的独立功能，不自动进入设备发现与共享，
+详见[远程主机与远程执行](../remote-host/README.md)。

docs/features/device-sharing/logic-design.md

@@ -0,0 +1,202 @@
+# 设备发现与共享功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
+| 共享规则 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+
+本文负责桌面端状态、不变量和决策规则，不重复跨端协议定义。
+
+## 1. 核心不变量
+
+### INV-1 连接方式独立
+
+局域网、每个 GatewayConnection 和本机能力互不拥有生命周期。启停、失败或删除其中一项不
+改写其他项。
+
+### INV-2 三项操作独立
+
+`discovering`、`advertising` 和 `publishing` 是三个独立状态。任何组合均合法，界面不得用
+一个“设备共享”总开关代替。
+
+### INV-3 默认不共享
+
+新安装没有 Publication。允许被发现只公开配对入口，不公开能力清单。
+
+### INV-4 身份先于能力
+
+未配对局域网设备不能取得详细能力；未注册网关设备不能取得组织目录。缓存不能绕过当前
+身份和撤销状态继续调用。
+
+### INV-5 提供者在调用前冻结
+
+自动选择只生成候选决定。用户确认或无需确认的请求创建后，provider、route 和授权快照不可
+改变。失败后切换提供者属于新的请求。
+
+### INV-6 最小发送上下文
+
+只发送能力 schema 要求且用户当前选择的输入。当前 Conversation、Project 和 Workspace 不
+因能力被调用而整体成为输入。
+
+### INV-7 结果未知不重放
+
+已经被提供者接受但终态无法确认的副作用任务进入 `outcome_unknown`。重新执行必须由用户
+发起，并显示可能重复产生副作用。
+
+### INV-8 撤销只影响未来授权
+
+撤销配对、网关连接、Grant 或 Publication 后不再创建新任务。历史记录保留；活动任务按
+冻结策略取消或完成，不能追改为从未发生。
+
+### INV-9 设置导航无业务副作用
+
+四个 PageTabs 只切换视图，不自动开始广播、连接网关、发布能力或保存草稿。
+
+## 2. 状态维度
+
+### 2.1 局域网服务
+
+```text
+discover: off | starting | active | unavailable | error
+advertise: off | starting | active | unavailable | error
+```
+
+操作系统或网络不支持时使用 `unavailable`；运行失败使用 `error`。两者分别重试。
+
+### 2.2 附近设备
+
+```text
+visible_unpaired -> pairing -> paired_online
+pairing -> rejected | expired | failed
+paired_online <-> paired_offline
+paired_* -> identity_changed | revoked
+```
+
+`identity_changed` 不自动接受新证书。用户必须撤销旧配对后重新配对。
+
+### 2.3 网关连接
+
+```text
+draft -> authenticating -> connecting -> connected
+authenticating -> cancelled | auth_failed
+connecting/connected -> offline | auth_expired | policy_blocked
+offline -> connecting
+任意已保存状态 -> removed
+```
+
+`offline` 保留连接和缓存目录供只读说明，但不能创建新任务；`auth_expired` 要求重新登录；
+`policy_blocked` 显示服务端给出的稳定原因和管理员联系路径。
+
+### 2.4 本机发布
+
+```text
+not_published -> draft -> validating -> published
+validating -> invalid
+published -> paused -> published
+published/paused -> removed
+```
+
+草稿和无效发布不对外可见。能力实现消失时发布进入 `paused`，不删除用户配置。
+
+### 2.5 远端任务
+
+采用共享架构定义的状态。本机 UI 归并为：
+
+| 协议状态 | 用户状态 |
+| --- | --- |
+| `created/awaiting_approval` | 等待确认 |
+| `queued/connecting` | 正在连接 |
+| `running` | 正在执行 |
+| `completed` | 已完成 |
+| `failed/rejected/expired` | 未完成，并显示具体原因 |
+| `cancelled` | 已取消 |
+| `outcome_unknown` | 结果未知 |
+
+## 3. 默认状态
+
+| 设置 | 全新安装默认值 |
+| --- | --- |
+| 发现附近设备 | 开启 |
+| 允许其他设备发现本机 | 关闭 |
+| 自动接受配对 | 不支持 |
+| 本机共享能力 | 无 |
+| 网关连接 | 无 |
+| 永久调用 Grant | 无 |
+
+主动发现默认开启只浏览 GoodBuddy 主动广播，不执行端口扫描。操作系统权限尚未授予时，首次
+进入页面再触发对应系统说明和授权，不在应用启动时抢占焦点。
+
+## 4. 提供者选择
+
+自动选择按以下顺序比较满足当前输入和授权的在线候选：
+
+1. 本机提供者。
+2. 已配对局域网提供者。
+3. 当前用户所属组织提供者。
+4. 联邦外部组织提供者。
+5. 同级中按服务端预计排队时间和稳定能力版本排序。
+
+自动选择不跨越 `require_approval` 与 `allow`：若排名第一的候选需要批准，界面显示该候选及
+批准要求，不静默换成权限更宽但来源更远的候选。用户可以明确选择其他候选。
+
+## 5. 调用决策表
+
+| 身份与能力状态 | 授权结果 | 行为 |
+| --- | --- | --- |
+| 身份有效、输入匹配 | allow | 创建任务并展示执行位置 |
+| 身份有效、输入匹配 | require_approval | 显示完整确认后创建 |
+| 身份有效 | deny | 不创建任务，显示策略原因 |
+| 提供者离线 | 任意 | 不创建任务，允许重新选提供者 |
+| 清单过期或版本变化 | 任意 | 刷新后重新计算，不沿用确认 |
+| 文件超过能力或策略上限 | 任意 | 就地拒绝并显示上限 |
+| 委托链与确认不一致 | 任意 | 拒绝并要求以新执行链重新确认 |
+
+## 6. 撤销与删除
+
+| 操作 | 删除内容 | 保留内容 |
+| --- | --- | --- |
+| 撤销 Peer | 配对凭据、该 Peer 的本地 Grant 和目录缓存 | 活动记录、已安装包 |
+| 移除网关 | 本机设备凭据、连接配置、目录缓存 | 服务端账号、活动记录、已安装包 |
+| 停止发布 | 对外 Publication | 能力实现、发布草稿、历史任务 |
+| 删除发布 | Publication 和本地发布设置 | 能力实现、历史任务 |
+| 删除已安装包 | GoodBuddy-owned 安装内容和分配 | 来源审计与任务历史 |
+
+存在活动任务时，撤销操作明确询问是否同时发送取消；无论取消是否确认，立即禁止新任务。
+
+## 7. 失败与恢复
+
+- mDNS 不可用：显示手动地址配对，不关闭已配对直连。
+- 广播失败：保留用户开关意图，状态为错误并允许重试。
+- 网关离线：指数退避重连，用户手动“重新连接”可立即尝试一次。
+- 登录取消：不保存连接。
+- 目录刷新失败：保留最后缓存并标记时间，不允许基于过期授权启动新任务。
+- 调用前连接失败：任务失败，可安全重新执行。
+- 提供者接受后断线：恢复查询同一任务；仍无法确认时进入结果未知。
+- 下载或签名失败：删除候选暂存，保留现有安装，不切换来源。
+
+## 8. 需求追踪
+
+| 需求 | 主要逻辑 |
+| --- | --- |
+| `FR-1`、`FR-2` | `INV-1`、`INV-2`、`INV-9` 和默认状态 |
+| `FR-3`、`FR-4` | 身份不变量和附近设备状态机 |
+| `FR-5` | 连接独立不变量、网关连接状态和删除规则 |
+| `FR-6` | provider 冻结不变量和提供者选择顺序 |
+| `FR-7` | 默认不共享不变量、本机发布状态和撤销规则 |
+| `FR-8` | 最小发送上下文和调用决策表 |
+| `FR-9` | 远端任务状态、结果未知不重放和失败恢复 |
+| `FR-10` | 撤销与删除、下载或签名失败规则；包协议由共享架构定义 |
+| `FR-11` | 撤销后历史保留和任务状态；展示行为由 UI 设计定义 |
+| `FR-12`、`FR-13` | 独立状态维度和失败恢复 |
+| `FR-14` | 身份先于能力、最小发送上下文和调用决策表 |
+
+## 9. 逻辑完整性
+
+本设计已覆盖发现、配对、连接、发布、调用、取消、撤销、离线、身份变化、权限变化和能力
+更新。实现前仍需在共享协议中固定受限 JSON Schema 子集、端到端中继加密套件和桌面端可
+注册为共享能力的首批实际类型；这些是技术选择，不改变本文状态和产品规则。

docs/features/device-sharing/prd.md

@@ -0,0 +1,160 @@
+# 设备发现与共享 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用产品 | GoodBuddy Desktop |
+| 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+| 关联文档 | [功能逻辑](./logic-design.md)、[UI 设计](./ui-design.md)、[技术设计](./technical-design.md) |
+
+## 1. 背景
+
+GoodBuddy 的能力当前主要在本机执行，SSH 远程项目则要求用户预先配置具体 Host。个人和组织
+需要在不复制完整环境的情况下使用附近工作站、其他成员设备或组织节点上的模型、知识、硬件
+和工具，也需要在经过确认后把可分发能力安装到本机。
+
+该能力不能以“扫描局域网机器”的方式实现。产品只发现主动开放 GoodBuddy 服务的设备，
+配对后才查看详细能力，授权后才发送数据或执行任务。
+
+## 2. 产品目标
+
+1. 用户无需配置服务器即可发现并配对同一局域网中的 GoodBuddy 设备。
+2. 用户可以额外连接一个或多个 ShareServer，使用组织或合作组织提供的能力。
+3. 用户能够逐项决定本机向哪些 Peer、用户组或组织开放什么能力。
+4. 远程调用前、中、后都能确认提供者、执行位置、数据去向和授权依据。
+5. 局域网、各网关连接和本机能力彼此独立，单点故障不阻塞其他来源。
+6. 可分发能力必须在明确校验和批准后安装，不迁移对方凭据或机器配置。
+
+## 3. 功能范围
+
+### 3.1 包含
+
+- 设置中的“设备发现与共享”一级分类。
+- 局域网主动发现、选择、双端配对、重命名和撤销。
+- 本机被发现开关和配对请求处理。
+- ShareServer 添加、登录、连接状态、组织身份和移除。
+- 远端能力目录、提供者选择、调用确认、进度、取消和结果。
+- 本机能力逐项发布、范围、允许动作和确认策略。
+- 签名能力包查看、下载、校验、安装和权限变化确认。
+- 局域网与网关活动记录。
+
+### 3.2 不包含
+
+- 扫描未主动广播 GoodBuddy 服务的机器或端口。
+- 在桌面端管理 ShareServer 成员、组织策略、联邦或服务器运维。
+- 自动公开本机 Skill、MCP、知识库、模型、文件或 SSH Host。
+- 同步 API Key、Cookie、系统环境变量、绝对路径或登录状态。
+- 把现有 SSH Host 自动转换为共享设备。
+- 无界远程 Shell、桌面控制或任意文件浏览接口。
+- 在网关断开时把组织授权自动降级为局域网授权。
+
+## 4. 功能需求
+
+### FR-1 设置入口
+
+- 设置中心增加“设备发现与共享”一级分类。
+- 页面提供“局域网”“网关”“本机共享”“活动记录”四个同级页签。
+- 普通入口默认打开“局域网”；定向入口可打开指定页签。
+
+### FR-2 独立开关
+
+- “发现附近设备”和“允许其他设备发现本机”使用两个独立 Switch。
+- 任一开关变化不撤销既有配对、不改变网关连接、不开放能力。
+- 新安装默认允许主动发现；默认不允许本机被发现，默认无共享能力。
+
+### FR-3 附近设备
+
+- 只展示当前收到有效主动广播的 GoodBuddy 设备。
+- 未配对设备只展示配对所需的有限信息，不展示能力和资产详情。
+- 列表区分附近未配对、已配对在线、已配对离线和身份变化。
+- 用户可手动刷新，但持续发现不得因刷新造成列表闪烁或重复项。
+
+### FR-4 双端配对
+
+- 双方显示相同验证码、设备名称、系统类型和证书指纹。
+- 只有双方在时限内确认才建立配对。
+- 任一端拒绝、超时、身份变化或连接中断均不保存半配对关系。
+- 任一端可以撤销；撤销不删除历史活动记录。
+
+### FR-5 网关连接
+
+- 用户可输入 HTTPS ShareServer 地址或打开受支持的邀请链接。
+- 登录在系统浏览器中完成，设备凭据回到 Main 的安全存储。
+- 连接条目显示服务名、组织、当前成员身份、状态和最近策略同步时间。
+- 同一设备可连接多个网关；移除连接只删除本机凭据和缓存，不删除服务端账号。
+
+### FR-6 能力目录
+
+- 已配对 Peer 和已连接网关分别返回当前身份获准查看的能力。
+- 同一能力有多个提供者时合并展示，并允许“自动选择”或明确选择提供者。
+- 自动选择仅比较满足授权和输入要求的在线候选，依次选择本机、已配对局域网 Peer、
+  当前用户所属组织和联邦外部组织；同级候选再按预计等待时间和稳定能力版本排序。
+- 选择结果必须在执行前冻结并展示，不能执行中静默更换提供者。
+
+### FR-7 本机共享
+
+- 只有显式注册为可共享的能力才能出现在本机共享列表。
+- 每项能力分别设置目标范围、`discover/inspect/invoke/download` 动作、输入类型、大小、
+  并发、有效期和是否逐次确认。
+- 关闭能力或目标范围后停止接受新任务，不伪装为删除能力本身。
+- 知识库原文、工作区写入、进程执行和硬件控制需要独立的明确能力声明。
+
+### FR-8 调用确认
+
+- 首次或策略要求时，确认界面显示提供者、执行位置、接收方、输入内容类别、文件名和大小、
+  路由、中继可读性及下游委托。
+- 用户可取消、仅本次允许，或在组织策略允许时按当前范围保存授权。
+- 调用上下文不隐式包含其他会话消息、整个工作区或未选择的知识库内容。
+
+### FR-9 执行状态
+
+- 会话或任务活动持续显示远端能力名称、来源、状态、发送字节和停止入口。
+- 支持排队、连接、执行、完成、失败、取消、过期和结果未知。
+- 网络中断且副作用结果无法确认时显示“结果未知”，不自动重试。
+
+### FR-10 能力包
+
+- 展示来源、版本、发布者、平台、大小、签名、权限和依赖。
+- 下载和安装经过共享架构规定的校验流程。
+- 新版本扩大权限时必须重新批准。
+- 安装到本机后按现有 Skill/MCP/Runtime 分配规则启用，不因来自可信组织自动取得全部 Runtime。
+
+### FR-11 活动记录
+
+- 统一记录本机发出、远端发入、局域网、网关和跨组织活动。
+- 支持按方向、来源、能力、结果和时间筛选。
+- 详情显示授权依据、执行链、数据类别、大小、版本和终态，不默认保存正文。
+
+### FR-12 错误隔离
+
+- 局域网发现失败不影响网关和本机能力。
+- 一个网关认证或连接失败不影响其他网关。
+- 一个提供者离线时不自动改发给另一个提供者；用户重新执行时再选择。
+- 页面保留可修复配置和准确错误，不以空状态代替失败状态。
+
+### FR-13 平台与网络
+
+- 支持 Windows、macOS、Linux 的当前桌面目标架构。
+- mDNS 被网络阻断时允许通过已知局域网地址发起配对，但仍执行相同身份确认。
+- 所有公网 ShareServer 使用 HTTPS；不提供“忽略证书错误”。
+
+### FR-14 与现有能力的边界
+
+- 远端调用不能扩大 Ask/Execute、Workspace、MCP、Skill 和知识库现有权限。
+- 本机提供任务时使用能力声明对应的 Runtime 边界。
+- SSH 远程项目、本机工具环境和模型配置默认不向 Peer 或网关传播。
+
+## 5. 产品验收
+
+- 两台新设备能完成发现、双端配对、授权、调用、取消和撤销。
+- 三个概念“主动发现、允许被发现、开放能力”在状态和界面上互不混淆。
+- 不配置网关时局域网工作完整；任一网关故障不阻塞其他来源。
+- 未配对或未授权主体无法查看详细能力。
+- 远端调用前能准确列出实际发送的数据，执行中和历史中可追溯提供者。
+- 结果未知不会被显示为失败后自动重试或成功。
+- 权限扩大的能力更新不会沿用旧授权静默安装。
+- 中英文、键盘、焦点、窄窗口和深浅主题符合统一设计系统。

docs/features/device-sharing/technical-design.md

@@ -0,0 +1,213 @@
+# 设备发现与共享技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 共享协议 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
+
+## 1. 进程边界
+
+```text
+Renderer
+  -> 窄 Preload API
+Main
+  -> DeviceSharingService
+       -> LanDiscoveryService
+       -> PeerPairingService
+       -> GatewayConnectionService
+       -> CapabilityCatalogService
+       -> CapabilityPublicationService
+       -> RemoteTaskService
+       -> PackageAcquisitionService
+       -> SharingAuditStore
+  -> 既有 Capability / Runtime / Skill / MCP 服务
+```
+
+Renderer 只取得脱敏快照和调用显式动作。设备私钥、Peer 证书、网关凭据、网络 socket、原始
+任务令牌、任意文件读取和包缓存路径只存在于 Main。
+
+## 2. 模块职责
+
+| 模块 | 职责 |
+| --- | --- |
+| `LanDiscoveryService` | mDNS browse/advertise、手动地址握手、接口变化 |
+| `PeerPairingService` | 临时握手、验证码、双端确认、配对凭据与撤销 |
+| `GatewayConnectionService` | 浏览器登录、设备注册、WebSocket、重连和策略同步 |
+| `CapabilityCatalogService` | 合并本机、Peer 和网关目录，保留来源身份 |
+| `CapabilityPublicationService` | 校验本机可共享能力并向目标范围发布 |
+| `RemoteTaskService` | 授权、确认、provider 冻结、传输、取消和终态 |
+| `PackageAcquisitionService` | 固定来源下载、校验、安装协调和权限差异 |
+| `SharingAuditStore` | 本机有界审计查询、筛选和清理 |
+
+目录合并只生成 UI 视图，不能把不同 provider 的授权、版本和执行位置压成一个身份。
+
+## 3. 共享契约
+
+实现前建立独立 `packages/share-protocol`。Desktop 只从该包导入 Zod schema 和 TypeScript
+类型。协议输入在网络边界和 IPC 边界分别验证，不能因已经过网络校验而跳过 Renderer 输入
+校验。
+
+建议导出：
+
+```text
+DeviceSummary
+PairingChallenge
+GatewayDescriptor
+CapabilityManifest
+Publication
+GrantConstraint
+AuthorizationDecision
+RemoteTaskSnapshot
+RemoteTaskEvent
+PackageDescriptor
+AuditEventSummary
+ProtocolError
+```
+
+错误只向 Renderer 返回稳定 code、可本地化参数和可恢复动作，不转发远端堆栈、响应正文或
+内部地址。
+
+## 4. 持久化
+
+建议在现有 Desktop SQLite 中增加：
+
+```text
+device_identity_metadata
+peer_pairings
+gateway_connections
+capability_publications
+local_grants
+remote_tasks
+sharing_audit_events
+installed_shared_packages
+```
+
+- 私钥和 refresh credential 存系统安全存储；SQLite 只存引用和脱敏元数据。
+- 附近广播、在线状态、配对验证码、短期任务令牌和目录候选只存在于内存。
+- 网关能力目录可有界缓存，用于离线说明，不作为离线调用授权。
+- 审计正文不落库，字段和保留上限在实现前固定。
+- 数据库迁移只覆盖已发布 schema；未发布设计不预建兼容读取器。
+
+## 5. 局域网网络实现
+
+- 使用系统支持的 mDNS/DNS-SD 库 browse `_goodbuddy-share._tcp.local`。
+- 广播绑定用户允许的网络接口；接口切换时重建监听，不保留旧地址为身份。
+- 服务端口由 Main 持有，使用设备证书建立 TLS。
+- 未配对握手仅暴露配对所需字段，并限制并发、频率、消息大小和有效时间。
+- 手动地址只替代发现，不替代证书指纹与双端确认。
+- 停止广播时关闭未完成配对监听；已配对活动连接按任务生命周期处理。
+
+## 6. 网关连接
+
+1. Main 校验 HTTPS URL，并取得服务公开描述。
+2. 生成带 PKCE、随机 state 和设备挑战的系统浏览器登录请求。
+3. 本机 loopback 或已注册应用链接只接收一次性回调 code。
+4. Main 交换设备凭据，展示组织身份，用户确认后持久化。
+5. Main 建立带设备身份的 WebSocket 出站连接。
+6. 心跳更新在线状态；断线按有界指数退避重连。
+
+服务器返回的跳转 URL 必须符合已取得服务描述和 HTTPS 限制。Renderer 不能提交认证头、设备
+证书、WebSocket URL 或任意回调地址。
+
+## 7. 本机能力适配
+
+不是所有现有 Capability 都自动可共享。每种可共享类型需要显式 adapter：
+
+```ts
+interface ShareableCapabilityAdapter {
+  describe(): CapabilityManifest
+  validatePublication(input: PublicationDraft): ValidationResult
+  invoke(input: unknown, context: ProviderTaskContext): AsyncIterable<TaskEvent>
+  cancel(taskId: string): Promise<CancelResult>
+}
+```
+
+adapter 负责把共享输入映射到既有生产服务，并保留原权限边界。首批类型在实现前根据真实
+产品需求确定；未有 adapter 的 Skill、MCP、知识库和 Runtime 不出现在共享列表。
+
+## 8. 远端调用生命周期
+
+```text
+Renderer 选择能力和输入
+-> Main 解析候选并取得当前授权
+-> 必要时返回确认描述
+-> 用户批准
+-> Main 冻结 task/provider/route/policy
+-> 建立数据通道并流式发送
+-> Provider 再校验并接受
+-> Main 转发有界进度和结果
+-> 终态与审计事务保存
+```
+
+每次任务使用稳定 `taskId` 和 attempt ID。Provider 未接受前的连接失败可以明确失败；已接受
+后的断线先查询同一任务，不新建 attempt。无法恢复权威终态时保存 `outcome_unknown`。
+
+附件从 Main 已授权的用户选择结果读取，按声明大小流式发送，不把任意本机路径交给远端。
+接收成果先写 GoodBuddy-owned 暂存并校验，再通过现有 Artifact 边界进入产品。
+
+## 9. IPC
+
+Preload 只暴露按产品动作命名的方法，例如：
+
+```text
+sharing.getSnapshot
+sharing.updateLanSettings
+sharing.startPairing / confirmPairing / cancelPairing
+sharing.revokePeer
+sharing.addGateway / completeGatewayLogin / removeGateway
+sharing.listCapabilities
+sharing.savePublication / pausePublication / deletePublication
+sharing.prepareInvocation / confirmInvocation / cancelTask
+sharing.listAuditEvents / getAuditEvent
+```
+
+所有变更方法校验 trusted sender、严格 schema、对象当前 revision 和归属关系。不得暴露通用
+HTTP、WebSocket、mDNS、证书、文件传输或数据库查询 IPC。
+
+## 10. 生命周期与资源边界
+
+- 应用启动按保存设置启动主动发现；不因保存了网关而阻塞窗口创建。
+- 广播只有在用户开启后启动。
+- 网关连接在后台恢复，认证过期只影响对应连接。
+- 应用退出停止接收新任务，取消未接受任务，并有界通知活动 Provider 后关闭连接。
+- 单个 Peer/网关/任务设置连接数、帧、字节、并发和重连上限。
+- 大文件全程流式处理，不进入单个 Main `Buffer` 或 Renderer state。
+
+## 11. 与现有模块集成
+
+- `capability-service` 提供本机能力事实；共享 adapter 明确选择可公开子集。
+- 已安装共享 Skill/MCP 继续使用现有配置、启停和 Runtime 分配，不建立第二套执行器。
+- SSH Host 保持独立；除非未来提供专门 adapter 和用户发布，否则不进入目录。
+- 远端 Task 的公开活动复用现有工具/任务展示语义，但保留 provider 和 route 字段。
+- 应用更新源、模型下载源、Agent 下载源和工具下载源不因添加 ShareServer 自动改变。
+
+## 12. 验证策略
+
+### 12.1 自动化
+
+- schema 边界、未知枚举和协议版本协商。
+- 三个独立开关及默认值。
+- mDNS 去重、接口变化、广播停止和手动地址。
+- 配对双方确认、拒绝、超时、身份变化和撤销。
+- 多网关隔离、认证过期、重连和移除。
+- provider 排序、冻结、授权变化和失败不切换。
+- 调用确认最小输入、附件上限、取消和结果未知。
+- Publication 校验、暂停、撤销和 adapter 消失。
+- 包签名、权限差异、来源冻结和失败保留旧安装。
+- IPC sender、revision、归属和无通用网络/文件接口。
+
+### 12.2 真实环境
+
+- Windows、macOS、Linux 至少两种组合完成同网段发现和配对。
+- mDNS 可用、被防火墙阻断、网络接口切换和设备离线场景。
+- 真实 ShareServer 登录、设备出站连接、目录、调用和认证过期。
+- 小型 JSON、文件流、取消、Provider 进程失败和网络中断。
+- 确认日志、Renderer、诊断和审计中没有凭据或文件正文。
+
+设计文档完成不代表功能实施或上述验证通过。

docs/features/device-sharing/ui-design.md

@@ -0,0 +1,211 @@
+# 设备发现与共享 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [设备发现与共享 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文只定义桌面端界面。所有颜色、间距、字体、通知、Switch、PageTabs、焦点和响应式行为以
+全局设计系统为准。
+
+## 1. 信息架构
+
+设置中心新增一级分类“设备发现与共享”，使用 `standard` PageShell：
+
+```text
+设备发现与共享
+发现附近的 GoodBuddy，或连接组织网关使用和开放能力
+
+[ 局域网 ] [ 网关 ] [ 本机共享 ] [ 活动记录 ]
+```
+
+四项使用共享 `PageTabs` 的 `segmented` 视觉变体。普通入口默认“局域网”；来自能力来源、
+连接错误或审计入口的定向导航打开对应页签。页签选择不持久化为产品设置。
+
+## 2. 局域网页签
+
+页面顺序固定为本机发现状态、已配对设备、附近设备。
+
+```text
+局域网
+
+发现附近设备                                      [Switch 开]
+查看同一网络中主动开放的 GoodBuddy 设备
+
+允许其他设备发现本机                              [Switch 关]
+设备名称：Jiang-PC                                 [编辑]
+
+已配对设备                                      [刷新]
+名称             状态        能力       最近连接       操作
+GPU-Workstation  在线        4 项       刚刚           ...
+
+附近设备
+Design-Mac       等待配对                               [配对]
+```
+
+- 两个 Switch 必须独立成行，不能使用一个总开关。
+- “允许被发现”开启后只显示广播状态和设备名，不暗示已经共享能力。
+- 设备行采用紧凑列表，不使用大卡片墙。
+- 已配对设备行可展开简要能力；完整信息进入设备详情抽屉。
+- 离线设备保留在“已配对设备”，附近广播消失不删除配对。
+
+### 2.1 配对对话框
+
+```text
+与 Design-Mac 配对
+
+验证码        824 193
+设备          Design-Mac · macOS
+设备指纹      7A:31:...:D9
+有效时间      01:42
+
+请确认另一台设备显示相同信息。
+[取消] [信息一致，确认配对]
+```
+
+双方尚未确认时显示独立进度。拒绝、超时和连接失败保留设备行并给出重新配对，不显示成功
+通知。成功使用应用通知，焦点回到对应设备行。
+
+### 2.2 设备详情
+
+详情使用右侧抽屉，包含“概览”“能力”“授权”“活动”四个内部页签。未配对设备不能打开
+能力和授权。撤销配对放在抽屉底部 danger zone，并说明活动任务和历史记录影响。
+
+## 3. 网关页签
+
+```text
+网关                                                   [添加网关]
+
+研发组织网关
+研发中心 · 成员
+已连接 · 策略同步于 14:32
+可用能力 18 项 · 本机发布 2 项                         [...]
+```
+
+空状态说明网关是附加连接，局域网无需网关即可使用。主操作为“添加网关”。
+
+### 3.1 添加网关
+
+对话框只要求 HTTPS 地址，也可由邀请链接预填：
+
+```text
+网关地址
+[https://share.example.com]
+
+[取消] [继续登录]
+```
+
+地址通过 Main 验证后打开系统浏览器。应用内显示“等待浏览器登录”和取消入口，不嵌入第三方
+登录页。回调成功后显示服务名、组织和账号，用户确认才保存连接。
+
+网关详情抽屉包含连接、组织身份、可用能力、本机发布和诊断。移除连接明确说明只移除本机
+连接，不删除组织账号或服务端设备记录。
+
+## 4. 本机共享页签
+
+页首状态摘要不能替代逐项开关：
+
+```text
+本机共享
+已开放 2 项能力 · 局域网 1 项 · 网关 2 项
+
+搜索能力                     [范围筛选] [状态筛选]
+
+文档转 Word                                      [Switch 开]
+范围：研发组织、GPU-Workstation
+允许：查看、远程调用
+确认：每次调用                                    [编辑]
+```
+
+能力关闭时保留配置摘要并标为“已暂停”。点击“编辑”打开共享设置对话框：
+
+- 目标范围使用分组多选，不混合 Peer、网关组织和用户组。
+- 允许动作使用 Checkbox。
+- “每次确认”使用 Switch。
+- 输入类型、大小、并发、时间段和有效期使用对应表单控件。
+- 权限较高的能力在提交区显示具体影响，不用泛化风险等级。
+- 提交按钮附近再次列出目标范围和允许动作。
+
+能力尚未注册为可共享时不展示虚假的禁用行。列表为空时说明当前没有可共享能力，并提供前往
+“能力与工具”的次操作。
+
+## 5. 活动记录页签
+
+使用 `dashboard` 所需的表格能力，但保持在设置 PageShell 内横向滚动：
+
+```text
+方向       能力             对端/来源          状态       时间
+发出       图像生成         研发组织网关       已完成     14:36
+收到       文档转 Word      GPU-Workstation    正在执行   14:31
+```
+
+工具栏提供方向、来源、状态、时间和搜索。详情抽屉显示任务 ID、能力版本、授权依据、路由、
+数据类型和大小、执行链、耗时、结果及取消/撤销入口。正文和文件内容默认不展示。
+
+## 6. 能力选择与调用确认
+
+远端能力进入现有能力目录时，在名称旁持续显示来源标签。多个提供者使用菜单选择：
+
+```text
+图像生成
+提供者 [自动选择：GPU-Workstation v]
+```
+
+调用需要确认时使用对话框：
+
+```text
+调用“合同风险检查”
+
+提供者       法务服务商
+执行位置     外部组织
+将发送       当前输入；contract.docx（1.8 MB）
+连接方式     ShareServer 中继
+网关可见正文 否
+下游调用     无
+
+[取消] [仅本次允许] [按此范围始终允许]
+```
+
+组织策略不允许保存 Grant 时不显示“始终允许”。按钮文字必须表达作用域，不能使用“确定”。
+
+## 7. 执行活动
+
+会话和任务中的远端工具活动至少显示：
+
+```text
+合同风险检查 · 法务服务商
+正在执行 · 已发送 1 个文件（1.8 MB）                 [停止]
+```
+
+展开后显示路由、能力版本和执行链。跨组织来源使用文字“外部组织”，不能只靠颜色。进入结果
+未知时显示持久警告和“查看活动详情”，不提供普通的自动重试按钮。
+
+## 8. 状态与错误
+
+- 首次为空、筛选无结果、加载失败、无权限和离线分别使用不同状态。
+- 缓存目录必须显示“上次更新于”，且离线时不能显示为当前可用。
+- 身份变化使用阻塞状态，唯一修复路径是撤销后重新配对。
+- 网关认证过期在对应网关行提供“重新登录”。
+- 发布字段错误就地显示；异步连接错误显示在对象行或详情中。
+- 配对成功、网关保存和共享发布成功使用应用通知，不重复显示页内成功横幅。
+
+## 9. 无障碍与响应式
+
+- 四个页签使用 `tablist/tab/tabpanel`、方向键、Home、End 和可见焦点。
+- 持久二元状态使用 `role="switch"`；范围和动作多选使用 Checkbox。
+- 表格在窄窗口切换为保留同样字段的列表，不隐藏提供者、状态或执行位置。
+- 指纹和长网关地址允许换行并提供复制按钮，不依靠水平裁切。
+- 对话框关闭后焦点回到触发控件；浏览器登录返回后恢复到等待登录区域。
+- 状态包含文字和图标，不以颜色作为唯一信号。
+
+## 10. 固定词汇
+
+使用“设备发现与共享”“局域网”“网关”“本机共享”“附近设备”“已配对设备”“允许其他
+设备发现本机”“结果未知”“外部组织”。不使用“扫描机器”“公网共享”“永久信任整台设备”
+或把 ShareServer 简称为“云端”。

docs/features/direct-model-agent/README.md

@@ -0,0 +1,59 @@
+# 直连模型 Agent 能力
+
+本目录是 GoodBuddy“直连模型 Agent 能力”的唯一文档入口。本功能为直连文本模型补齐
+高效工作区搜索、分页读取、补丁编辑、跨平台进程执行和编程 Subagent，使其能够完成
+“搜索、读取、修改、运行、验证”的开发闭环，同时避免向已经拥有原生 Shell 或 Agent
+能力的 Runtime 重复注入工具。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、产品范围、功能需求、非目标和产品验收 |
+| [User Stories](./user-stories.md) | 本机开发、失败恢复、委派和 Runtime 边界场景 |
+| [功能逻辑](./logic-design.md) | 能力矩阵、不变量、状态转换、继承规则和失败结果 |
+| [UI 设计](./ui-design.md) | 设置能力目录、聊天活动、Subagent 状态和无障碍行为 |
+| [技术设计](./technical-design.md) | Main 服务、工具契约、平台适配、Subagent、生命周期和测试 |
+| [功能进度](./progress.md) | 当前实现事实、待实施阶段、阻塞项和验证证据 |
+
+## 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| 直连模型 | Runtime provider 为 `model`、由 GoodBuddy 直接调用模型协议的文本模型 |
+| 进程执行 | GoodBuddy 在当前执行空间启动一个前台 Shell 命令并返回有界结果 |
+| 工作区搜索 | 通过安装包内置 ripgrep 搜索内容或列出文件，并返回紧凑结果 |
+| 工作区补丁 | 通过 `*** Begin Patch` 格式新增、修改或删除工作区文本文件 |
+| 输出续读 | 通过 `output_read` 分页读取当前会话保留的进程或 Subagent 输出 |
+| 平台 Shell | Windows 上的 PowerShell，macOS/Linux 上的 Bash 或 POSIX Sh |
+| 编程 Subagent | 由直连模型临时委派、使用直连模型 Runtime 执行一个有界子任务的执行者 |
+| 父请求 | 发起进程调用或 Subagent 委派的当前直连模型请求 |
+| 子任务 | 父请求内部的一项委派工作，对应 Job/Subjob 语义，不是新的顶层 Task |
+
+Task、Job、Subjob、Run 和 Subagent 的对象关系以
+[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 为准。本功能不重新定义
+这些对象。
+
+## 功能边界
+
+- `workspace_rg`、`workspace_read_text`、`workspace_apply_patch`、`process_execute`、
+  `subagent_delegate` 和 `output_read` 是 GoodBuddy 直连模型内置工具，不是外部 MCP。
+- 直连文本模型的普通问答、工具轮次和上下文摘要会在尚无可见输出时，对瞬时网络错误或
+  单次请求超时最多自动重试 3 次。
+- OpenCode、Continue 和 DeepSeek Harness 继续使用各自原生执行与委派能力。
+- Ask 可搜索和分页读取工作区，但不允许补丁写入或进程执行；Subagent 若在 Ask 中使用，
+  只能继承 Ask 的只读能力。
+- 进程和 Subagent 的长输出返回预览与续读位置，完整内容保留到所属会话或 Runtime 释放。
+  Ask 和 Execute 均可续读当前会话已取得的输出，详见 [输出契约](./technical-design.md#43-输出边界)。
+- Execute 表示用户授权当前执行空间账号的完整能力，不增加第二套工具审批或权限档位。
+- 首版跨平台指桌面本机 Windows、macOS 和 Linux。托管 SSH 项目当前继续使用远端
+  OpenCode；未来若向远端直连模型开放本工具，命令必须由 Host Agent 执行，绝不能回退到
+  桌面本机。
+
+## 相关功能
+
+- [模型连接请求定制](../model-connections/README.md)：定义连接级 Header/Body、合并优先级和 Runtime 支持矩阵。
+- [本机工具环境](../local-tool-environment/README.md)：为新进程提供 Node、Python 和 PATH。
+- [助手工作栏与执行空间](../assistant-workbar/prd.md)：定义本机/SSH 执行位置和活动归属。
+- [远程主机与远程执行](../remote-host/README.md)：定义当前托管 SSH Runtime 边界。
+- [DeepSeek Harness Runtime](../deepseek-harness/README.md)：已经拥有平台 Shell 的独立 Runtime。

docs/features/direct-model-agent/logic-design.md

@@ -0,0 +1,209 @@
+# 直连模型 Agent 能力功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-09 |
+| 关联 PRD | [PRD](./prd.md) |
+| 关联故事 | [User Stories](./user-stories.md) |
+
+## 1. 权威不变量
+
+1. `process_execute` 和 `subagent_delegate` 只属于直连文本模型。
+2. Ask 永远不能启动命令、写入工作区或创建 Execute Subagent。
+3. 子级的项目、执行空间、工作模式、模型连接和能力范围只能继承或缩小。
+4. 子级工具清单不包含 `subagent_delegate`，最大深度固定为 1。
+5. 命令必须在父请求绑定的执行空间运行，禁止跨设备静默回退。
+6. 一个 `process_execute` 调用只拥有自己创建的前台进程树，不能管理无关进程。
+7. 非零退出码是命令结果；启动失败、输入无效和后端不可用才是工具失败。
+8. 子任务是父请求内部 Job/Subjob，不创建顶层 Task 或独立 Conversation。
+9. 父请求取消、Runtime 释放或应用退出会传播到全部活动子级和进程。
+10. OpenCode、Continue 和 DeepSeek Harness 的原生能力不被本功能替换或包装。
+11. 直连模型只在尚未显示文本或推理内容时自动重试瞬时网络错误或请求超时，最多重试
+    3 次；用户取消和已显示的部分输出禁止重放。
+12. Ask 可调用 `workspace_rg` 和 `workspace_read_text`，但不能调用
+    `workspace_apply_patch`；Execute 可调用三者。
+13. 工作区搜索固定使用随包 ripgrep 的结构化输出，不把任意 ripgrep 参数转成命令执行。
+14. FR-7 / US-A6：预览之外的进程和 Subagent 输出保留在所属会话下，分页续读不启动新命令。
+    会话释放先停止活动工作，再删除输出；子会话结束不删除父会话拥有的 Subagent 结果。
+
+## 2. 状态维度
+
+| 维度 | 值 |
+| --- | --- |
+| Runtime | `model`、`opencode`、`continue`、`deepseek-harness` |
+| 工作模式 | `ask`、`execute` |
+| 执行空间 | `local`、`ssh` |
+| 本机 Shell | `available`、`unavailable` |
+| Subagent 深度 | `0`、`1` |
+| 父请求 | `active`、`cancelling`、`terminal` |
+| 模型请求重试 | `initial`、`retry 1..3`、`terminal` |
+
+## 3. 工具可见性决策表
+
+| Runtime | 模式 | 工作区读/搜索 | 补丁 | `process_execute` | `subagent_delegate` |
+| --- | --- | --- | --- | --- | --- |
+| `model` | Ask | 提供 | 隐藏 | 隐藏 | 提供，只读继承 |
+| `model` | Execute，本机 Shell 可用 | 提供 | 提供 | 提供 | 提供，Execute 继承 |
+| `model` | Execute，本机 Shell 不可用 | 提供 | 提供 | 隐藏并报告诊断 | 提供 |
+| `model` | SSH，远端后端未实现 | 当前入口不开放 | 当前入口不开放 | 隐藏 | 隐藏 |
+| 其他 Runtime | 任意 | 不注入本功能工具 | 不注入 | 不注入 | 不注入 |
+
+工具清单隐藏不是最终授权边界。`callTool` 仍须重新验证 Runtime、工作模式、执行空间和父请求
+是否活动，以拒绝旧快照或伪造调用。
+
+FR-4 / FR-12 / US-B0：Ask 工作区搜索和读取不依赖知识库、联网搜索或委派开关，不需要
+切到 Execute 或额外批准。MCP 服务器失败也不改变本机只读工具的可用性。
+
+`output_read` 在直连模型拥有进程或 Subagent 服务时提供，Ask/Execute 均可用，不取决于
+本轮 Shell 可用性、是否允许再次委派或委派深度。读取只接受当前会话的句柄；其他 Runtime
+不注册该工具，调用边界同样拒绝。
+
+## 4. 进程状态机
+
+```text
+validating
+  ├─ invalid → failed
+  └─ valid → starting
+               ├─ spawn_failed → failed
+               └─ running
+                    ├─ exit 0 → completed
+                    ├─ exit nonzero → completed_nonzero
+                    ├─ timeout → terminating → timed_out
+                    ├─ parent cancel → terminating → cancelled
+                    └─ output/lifecycle failure → terminating → failed
+```
+
+规则：
+
+- `completed_nonzero` 仍产生正常工具结果。
+- 超时和取消结果包含已取得输出的预览；超出预览的内容按 FR-7 继续保留，直到所属会话释放。
+- 进入 `terminating` 后不再接受新输入，也不启动替代命令。
+- 终止只针对本次调用记录的进程树。
+- 迟到的 `close` 只用于清理，不得覆盖已提交的取消或超时原因。
+
+## 5. 工作目录决策
+
+| 输入 | 结果 |
+| --- | --- |
+| 未提供 | 当前工作区根目录 |
+| `.` 或相对路径 | 以当前工作区为基准解析，可指向工作区外目录 |
+| 绝对路径 | 使用指定目录 |
+| `..` 或指向工作区外的符号链接 | 解析到实际目标目录，按当前用户权限执行 |
+| 不存在或不是目录 | 拒绝 |
+| 当前工作区身份在验证期间变化 | 拒绝本次调用 |
+
+工作区提供默认目录和相对路径基准，不是 Execute 命令的文件系统边界。单次命令选择其他
+工作目录不会修改父请求绑定的项目或工作区，也不会影响后续未指定 `cwd` 的命令。
+
+## 6. Shell 选择
+
+| 平台 | 顺序 | 不可用结果 |
+| --- | --- | --- |
+| Windows | `pwsh` → `powershell.exe` | 进程工具不注册，设置诊断显示 PowerShell 不可用 |
+| macOS | `/bin/bash` → `/bin/sh` | 两者都不可用时不注册 |
+| Linux | `/bin/bash` → `/bin/sh` | 两者都不可用时不注册 |
+
+一次父请求冻结实际 Shell 描述。PATH 或工具环境设置变化只影响新创建的 Runtime/执行服务，
+不在运行中的命令或 Subagent 中途切换。
+
+## 7. Subagent 状态机
+
+```text
+validating
+  ├─ invalid/depth_exceeded → failed
+  └─ queued
+       ├─ parent_cancelled → cancelled
+       └─ running
+            ├─ model done → completed
+            ├─ child failure → failed_with_partial_output
+            ├─ timeout → cancelled
+            └─ parent cancel → cancelled
+```
+
+父模型收到结构化终态：
+
+```ts
+type SubagentDelegateResult = {
+  status: 'completed' | 'failed' | 'cancelled'
+  output: string
+  error?: string
+  modelUsage?: {
+    inputTokens?: number
+    outputTokens?: number
+  }
+}
+```
+
+失败和取消是父模型可以解释的子任务结果。只有契约损坏、未知子任务身份或服务已经释放等
+内部不变量失败才终止父工具循环。
+
+## 8. 权限与能力继承
+
+| 父请求 | 子级模式 | 子级能力 |
+| --- | --- | --- |
+| Ask | Ask | 父级只读工具的子集，不含进程、写入和再次委派 |
+| Execute | Execute | 父级已启用工具的子集，包含本机进程能力，不含再次委派 |
+
+- 子级不能请求更高模式。
+- 子级使用父请求开始时的工具与能力快照；运行中设置变化不重写快照。
+- 子级调用 MCP、浏览器或知识能力时继续经过这些能力已有的作用域和生命周期边界。
+- FR-5 / FR-7 / US-C1：Execute 子级使用父请求的浏览器标签页，不另开标签页或改变所有权；
+  子级结束后父模型仍可继续操作该页，父请求继续负责其使用租约。
+- Execute 子级不弹出额外的“Subagent 执行授权”，也不获得父级没有的 MCP 分配。
+
+## 9. 并发和顺序
+
+- 全局编程 Subagent 最大并发为 3，额外请求进入有界队列。
+- 单个父模型的工具调用仍按直连模型现有顺序结算，不为本功能改写全部工具并发语义。
+- 不同父请求的 Subagent 可以并发；共享工作区的并发写入属于用户已授权的 Execute 行为，
+  活动记录必须保留实际顺序和结果。
+- 首版不自动创建工作树、锁文件或回滚层。出现真实冲突时由父模型读取当前工作区事实并处理。
+
+## 10. 结果优先级
+
+当多个终止原因竞争时，使用以下优先级：
+
+```text
+用户/父请求取消 > 工具超时 > 输出或协议边界 > 进程退出 > 普通工具错误
+```
+
+已经提交的正常终态不被稍后到达的取消覆盖。父请求进入终态后，迟到的子级文本和工具事件
+只用于资源清理，不再写入会话。
+
+## 11. 模型请求重试
+
+```text
+attempt
+  ├─ success → completed
+  ├─ cancel → cancelled
+  ├─ non-retryable failure → failed
+  ├─ transient failure after visible output → failed_with_partial_output
+  └─ transient failure before visible output
+       ├─ retry count < 3 → backoff → attempt
+       └─ retry count = 3 → failed
+```
+
+- 瞬时失败包括常见连接重置、连接/网络不可达、DNS 临时失败、连接管道中断和请求超时。
+- 三次重试分别等待 500 ms、1 s 和 2 s；每次尝试重新建立请求并使用独立请求超时。
+- 普通问答、工具模型轮次和上下文摘要使用同一规则。
+- 重试不重复已经执行的工具；工具只会在模型完整返回一轮工具调用后开始执行。
+- 退避等待绑定父请求取消信号，取消优先于启动下一次尝试。
+
+## 12. 逻辑完整性评估
+
+| 领域 | 结论 |
+| --- | --- |
+| Runtime 隔离 | 完整，工具只注入 `model` |
+| Ask/Execute | 完整，清单过滤和调用边界双重检查 |
+| 本机三平台 | 完整，统一契约和平台 Shell 决策已定义 |
+| Subagent 递归 | 完整，深度固定为 1 |
+| 取消与失败 | 完整，父子和进程传播及优先级已定义 |
+| 模型网络恢复 | 完整，有限重试、输出重放和取消边界已定义 |
+| 产品对象 | 完整，遵循 Task/Job 权威模型 |
+| SSH 远端执行 | 明确不在首版；未来必须增加 Agent 后端后才能开放 |
+
+当前没有需要在实施前由用户补充的产品决策。

docs/features/direct-model-agent/prd.md

@@ -0,0 +1,226 @@
+# 直连模型 Agent 能力 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台 CI 待验证 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-09 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 关联领域 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
+
+## 1. 背景
+
+GoodBuddy 直连模型已经可以读取、列出和写入工作区文本，使用浏览器、联网搜索、知识库及
+分配的 MCP，但没有内置命令执行工具。模型可以生成代码，却不能运行构建、测试、格式化、
+Git 或项目脚本，因此无法独立验证结果。
+
+本功能设计时，GoodBuddy 已有面向用户专家协作的只读 Subagent，但直连模型尚不能在工具
+循环中主动委派编程子任务。当前专家协作已继承父请求 Ask/Execute 模式并使用本机直连模型
+工具，与本功能的 `subagent_delegate` 仍为不同入口。OpenCode、Continue 和 DeepSeek Harness 一般已经提供
+Shell、Agent 或 Task 能力，再向它们注入 GoodBuddy 同名工具只会造成重复入口和语义冲突。
+
+本功能补齐直连模型缺少的基础 Agent 能力：
+
+1. 一组工作区搜索、分页读取和补丁编辑接口。
+2. 一个按平台适配的进程执行接口。
+3. 一个单层、继承父请求范围的编程 Subagent 接口。
+
+## 2. 产品目标
+
+1. 让直连模型在 Execute 模式完成“读取代码 → 修改 → 运行 → 根据结果修正”的闭环。
+2. 在 Windows、macOS 和 Linux 使用同一个模型工具契约，不要求模型调用平台专属工具名。
+3. 让直连模型可以把独立工作委派给临时 Subagent，并取得有界、可核验的结果。
+4. 保持 Ask 只读、Execute 完整授权、执行空间、取消、有界输出和进程回收语义不变。
+5. 不向已有原生执行能力的 Agent Runtime 重复注入 GoodBuddy 进程或 Subagent 工具。
+6. 使用安装包内置 ripgrep 提供跨平台一致的快速代码搜索，不依赖用户预装命令。
+
+## 3. 核心产品决策
+
+### 3.1 统一工具名，平台适配留在 Main
+
+模型只看到 `process_execute`。GoodBuddy 根据当前平台选择 PowerShell、Bash 或 Sh，并在
+工具描述和结果中明确实际 Shell。模型不需要在 Windows 调用 `powershell_execute`、在
+macOS/Linux 改用 `bash_execute`。
+
+### 3.2 它是内置能力，不依赖 MCP
+
+进程生命周期、工作目录、取消和执行空间由 GoodBuddy 管理。用户仍可以配置提供其他命令
+能力的 MCP，但直连模型的基本编程能力不依赖第三方 MCP 是否安装或在线。
+
+### 3.3 Runtime 能力不重复注入
+
+| Runtime | GoodBuddy `process_execute` | GoodBuddy `subagent_delegate` |
+| --- | --- | --- |
+| 直连模型 `model` | Execute 提供 | Ask/Execute 提供 |
+| OpenCode | 不提供 | 不提供 |
+| Continue | 不提供 | 不提供 |
+| DeepSeek Harness | 不提供 | 不提供 |
+
+“不提供”只表示不注入本功能工具，不限制 Runtime 自己的 Bash、PowerShell、Task、
+Agent 或插件能力。
+
+### 3.4 Subagent 继承，不扩权
+
+Subagent 使用父请求的项目、执行空间、工作模式、直连模型连接和已启用能力快照：
+
+- Ask 父请求只能创建 Ask Subagent。
+- Execute 父请求创建 Execute Subagent。
+- 子级不能切换父请求绑定的项目、工作区、Runtime、模型连接或工作模式；Execute 命令的
+  单次工作目录选择遵循 FR-3。
+- 子级不再看到 `subagent_delegate`，首版最大委派深度固定为 1。
+- 子任务不是新的顶层 Task 或 Conversation，结果先返回父模型。
+
+### 3.5 不新增权限档位
+
+Ask 禁止命令和写入。Execute 是用户对当前执行空间账号的完整授权。进程和 Subagent 不增加
+“受控执行”“仅测试”“可信命令”或逐命令风险等级，也不重复弹出第二套确认。
+
+### 3.6 精简工作区工具
+
+直连模型使用 `workspace_rg` 发现文件和搜索内容，使用 `workspace_read_text` 按行分页读取，
+使用 `workspace_apply_patch` 新增、修改或删除文本文件。新请求不再注入低效的单层目录列表和
+整文件覆盖工具。Ask 提供前两个只读工具；Execute 额外提供补丁工具。
+
+## 4. 功能范围
+
+### 4.1 包含
+
+- 本机 Windows、macOS、Linux 的前台 Shell 命令执行。
+- 当前工作区默认工作目录，以及当前用户可访问的本机工作目录选择。
+- Exit Code、标准输出、标准错误、Shell、目录、耗时和截断状态。
+- 命令超时、用户取消、进程树停止和应用退出清理。
+- 新进程使用当前本机工具环境提供的 Node、Python 和 PATH。
+- 直连模型单层 Subagent 委派、排队、运行、部分结果、失败和取消。
+- 父子请求的工具、模型用量、活动和成果归属。
+- 桌面聊天和选择直连模型的消息通道项目使用相同 Runtime 能力矩阵。
+- 安装包按目标平台和架构携带固定版本 ripgrep，并将其提供给工作区搜索和命令 PATH。
+
+### 4.2 不包含
+
+- 交互式 PTY、终端复用、持续 stdin、密码提示或 TUI 自动化。
+- 后台守护进程、任意 PID 枚举、接管或停止用户已有进程。
+- Shell Session 持久化，环境变更不会跨 `process_execute` 调用保留。
+- 首版远程 SSH 直连模型进程执行。
+- 向 OpenCode、Continue 或 DeepSeek Harness 注入本功能工具。
+- 递归 Subagent、长期运行的自治 Agent、Workflow、Hook 或恢复未完成子任务。
+- 新的权限矩阵、逐命令批准、沙箱档位或命令白名单。
+- 自动安装项目依赖；模型可以在 Execute 中显式运行项目已有的安装命令。
+
+## 5. 功能需求
+
+### FR-1 直连模型专属可用性
+
+- 进程、编程 Subagent 和输出续读工具只由 Runtime provider `model` 注册。
+- Agent Runtime 切换为 OpenCode、Continue 或 DeepSeek Harness 后不再显示这些工具。
+- 图像生成连接不获得文本 Agent 工具。
+- 能力不可用时返回准确原因，不以其他 Runtime 或本机 Shell 静默代替。
+
+### FR-2 跨平台进程执行
+
+- 使用统一的 `process_execute` 工具契约。
+- Windows 选择 PowerShell；macOS/Linux 选择 Bash，Bash 不可用时可使用 POSIX Sh。
+- 每次调用启动一个前台进程树，完成后返回结构化结果。
+- 非零退出码是可观察的命令结果，不自动转成模型请求失败。
+- Shell 启动失败、非法参数或执行后端不可用才属于工具失败。
+
+### FR-3 工作目录和执行位置
+
+- 默认目录是父请求当前工作区。
+- 可选工作目录支持绝对路径、相对工作区路径及指向工作区外目录的路径或符号链接，
+  不额外限制在工作区内；目标必须是实际存在且当前用户可访问的目录。
+- 本机执行只能发生在当前桌面执行空间。
+- 当前请求绑定 SSH 执行空间且没有远端进程后端时不注册工具，绝不在桌面目录回退执行。
+
+### FR-4 Ask/Execute
+
+- Ask 工具清单不包含 `process_execute`。
+- Runtime 边界必须再次拒绝 Ask 发起的伪造命令调用。
+- Execute 命令使用 GoodBuddy 客户端当前用户权限，不声称 Runtime OS 沙箱。
+- 消息通道的直连模型 Execute 继续服从该通道既有工具策略。
+
+### FR-5 Subagent 委派
+
+- `subagent_delegate` 接受一个清晰的任务说明，不要求用户预先创建专家。
+- 子级默认使用父请求选择的直连模型连接。
+- 子级继承父请求的工作模式和能力上限，但不获得再次委派能力。
+- 子级最终输出、部分输出、错误、用量和状态返回父请求。
+- 父模型负责综合结果并向用户作最终回答。
+
+### FR-6 Subagent 领域归属
+
+- 子任务使用 Job/Subjob 语义，不创建 Task Center 条目或独立 Conversation。
+- UI 对象层级继续止于用户 Task；活动可以显示 Subagent 状态卡，但不显示 Job/Run 树。
+- 子任务产生的工具、成果和用量可追溯到父请求及子任务标识。
+
+### FR-7 生命周期和资源边界
+
+- 父请求取消必须传播到活动 Subagent 和其当前进程。
+- Runtime 替换、会话释放和应用退出必须停止 GoodBuddy 创建的活动子进程。
+- 命令、Subagent 提示、单次返回的输出预览、队列和并发有界；完整输出不因超过预览容量而丢弃。
+- 预览省略内容时明确标记并提供续读位置。模型可用 `output_read` 逐页取得完整日志及
+  Subagent 结果，包括失败或取消前已取得的部分输出。
+- Ask 和 Execute 均可续读当前会话的输出。会话或 Runtime 释放后，临时输出删除，旧句柄失效。
+
+### FR-8 环境和凭据
+
+- 新进程使用筛选后的当前用户环境和本机工具环境 PATH。
+- 模型 Provider 凭据、GoodBuddy 加密设置和无关桌面会话变量不进入命令环境。
+- 首版不接受模型提交任意环境变量映射；需要的普通变量由 Shell 命令在单次调用中设置。
+
+### FR-9 状态与活动
+
+- 进程活动显示等待、运行、成功、非零退出、超时、取消和失败。
+- Subagent 显示排队、运行、完成、失败和取消。
+- 命令和子任务失败保留可操作错误及已有部分输出。
+- 同一事件不同时显示页内错误和应用通知。
+
+### FR-10 兼容
+
+- 现有模型连接、MCP 分配、专家设置和 Runtime 选择无需迁移。
+- 不改变现有 Agent Runtime 的工具清单或权限语义。
+- 不修改系统 PATH、Shell Profile 或用户终端会话。
+
+### FR-11 模型请求重试
+
+- 直连文本模型的普通问答、工具轮次和上下文摘要遇到瞬时网络错误或单次请求超时时，
+  在尚未显示文本或推理内容的前提下最多自动重试 3 次。
+- 重试使用递增等待时间并显示当前次数；用户取消必须立即终止等待和后续请求。
+- 一旦本次模型调用已经显示文本或推理内容，不自动重放该调用，避免重复回答。
+- 非网络类 Provider 错误、协议错误和用户取消不进入自动重试。
+
+### FR-12 高效工作区工具
+
+- `workspace_rg` 同时支持内容搜索和文件列表，遵循项目忽略规则，并以
+  `path:line:column:text` 紧凑格式返回匹配。
+- `workspace_read_text` 接受起始行和行数，大文件通过续读完成，不因超过旧的整文件上限而
+  完全不可读；超长单行可使用返回的字节位置继续读取。
+- `workspace_apply_patch` 支持一个补丁新增、修改和删除多个 UTF-8 文件；执行前验证全部
+  路径和 hunk，执行失败时准确报告已完成文件。
+- 搜索和读取在 Ask/Execute 均可用；补丁只在 Execute 可用，Main 调用边界再次检查模式。
+- `workspace_rg` 使用固定参数调用随包 ripgrep，不向模型开放 `--pre` 或任意命令参数。
+- 工作区工具不限制文件总大小、补丁总大小、搜索表达式长度、glob 数量或模型请求的结果
+  数量。单次返回按上下文容量截断或分页；读取结果提供续读位置，搜索结果提示模型缩小查询。
+
+## 6. 产品验收
+
+- [ ] Windows 直连模型 Execute 使用 PowerShell 创建文件、运行测试并读取退出码。
+- [ ] macOS/Linux 直连模型 Execute 使用 Bash/Sh 完成同一工作流。
+- [ ] Ask 中模型看不到进程工具，伪造调用也在 Main 边界失败。
+- [ ] 直连模型可以委派编程子任务，子级运行命令并把结果返回父模型。
+- [ ] Ask Subagent 保持只读；Execute Subagent 不增加第二套批准。
+- [ ] Subagent 不能递归委派，不能切换父请求工作区、模式或模型。
+- [ ] 切换到 OpenCode、Continue 或 DeepSeek Harness 后不出现本功能工具。
+- [ ] 非零退出、超时、取消和输出截断均准确展示。
+- [ ] 模型能续读长输出中未出现在预览内的中间与结尾内容，中文和表情不会导致分页停滞。
+- [ ] 取消父请求和退出应用后没有残留 GoodBuddy 命令进程。
+- [ ] 本机工具环境选择对新命令生效，Main 持有的模型凭据不进入子进程。
+- [ ] 子任务不进入 Task Center，不创建独立可导航 Conversation。
+- [ ] TLS 建连重置和请求超时在未输出内容时最多自动重试 3 次，成功后继续原请求。
+- [ ] 重试等待可取消，已显示部分内容的失败不自动重放。
+- [ ] Ask 可使用 ripgrep 搜索和分页读取，但不能应用补丁。
+- [ ] Execute 可通过一个补丁新增、修改和删除多个工作区文件，并运行测试验证。
+- [ ] Windows、macOS、Linux 的 x64/arm64 安装包均携带对应 ripgrep，且无需系统预装。
+- [ ] 全量测试、类型检查、Lint 和生产构建通过。