chore: prepare GoodBuddy 0.12.6 and Agent 0.11.20 releases

Record approved bilingual notes for complete subagent progress, workspace diffs, knowledge selection, OpenCode stream cleanup, external command directories, and restored GitHub Agent updates. Remote progress and diff improvements require the new Agent package. No LoongArch preview is included.

.github/workflows/agent-release.yml

@@ -0,0 +1,623 @@
+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="$RUNNER_TEMP/agent-release-notes.md"
+          cat > "$notes" <<EOF
+          GoodBuddy Agent $AGENT_VERSION
+
+          此版本供 GoodBuddy 的“设置 > 平台功能 > 远程项目”手动下载。软件包包含 Agent、固定 Node 和 GoodBuddy 适配的远端 OpenCode Runtime。
+
+          This release is downloaded manually from GoodBuddy Settings > Platform Features > Remote Projects. Each package contains the Agent, pinned Node, and the GoodBuddy-adapted remote OpenCode Runtime.
+          EOF
+          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,7 +26,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24
+          node-version: 24.19.0
           cache: npm
 
       - name: Verify release tag version
@@ -50,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
@@ -58,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:
@@ -71,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
@@ -92,7 +151,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24
+          node-version: 24.19.0
           cache: npm
 
       - name: Cache packaging toolsets
@@ -115,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 }} --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 }} --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
@@ -132,8 +305,13 @@ jobs:
 
   release:
     name: Publish GitHub and OSS release
-    if: github.event_name == 'push' && github.ref_type == 'tag'
-    needs: package
+    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: 35
     environment:
@@ -150,7 +328,7 @@ jobs:
 
       - uses: actions/setup-node@v7
         with:
-          node-version: 24
+          node-version: 24.19.0
 
       - name: Verify release tag
         shell: bash

.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.
@@ -30,10 +94,17 @@ Keep Electron security boundaries intact:
 ## Runtime Behavior
 
 - Ask mode must remain read-only at the runtime boundary.
-- Execute mode may use tools only through the existing approval controls.
+- 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.
+- 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 +112,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,6 +127,18 @@ 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
@@ -64,6 +151,22 @@ Keep Electron security boundaries intact:
 - 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
@@ -131,95 +234,43 @@ mode.
 Release note: 修复左上角项目设置与消息通道项目设置不一致的问题；现在从任一入口修改后，另一处会同步显示相同配置。
 ```
 
-## Release Packaging
+## Releases
 
-- `.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.
+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.
 
-### Tagged Release Process
+Repository-wide release invariants:
 
-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.
-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. Only after approval, verify that `package.json` and `package-lock.json`
-   contain the same release version, verify the candidate tag does not already
-   point elsewhere, create `v${package.version}` at the exact approved commit,
-   and push the branch and tag according to the synchronized-remote rules.
-6. 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.
-
-When recovering from a version tag whose workflow never published a GitHub
-Release and its assets:
-
-- If the approved source and release metadata do not need to change, rerun the
-  failed jobs for the same immutable tag instead of creating another tag.
-- 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.
-
-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 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.
+- 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
 
@@ -231,14 +282,58 @@ 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. When the user requests a release tag, push the new tag

BUILD.md

@@ -127,13 +127,88 @@ 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 和 DSH 插件安装 Runtime：
+桌面包会携带经过版本与完整性校验的 OpenCode、Continue 和 DSH 插件安装 Runtime：
 
 - OpenCode 平台二进制来自 `.runtime-resources/<arch>`。
 - Continue Runtime 来自锁定版本的 `@continuedev/cli`。
@@ -143,12 +218,156 @@ npm run dist:linux:arm64
 
 跨架构打包前，确认目标架构的 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.9 的 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 发布失败不会阻塞任何桌面目标。
 
 本地构建单个平台目标：
 
@@ -156,8 +375,21 @@ Linux 的 `x64`、`arm64` 版本。生产 bundle 仅作为短期 Actions artifac
 npm run release:package -- --platform <windows|macos|linux> --arch <x64|arm64>
 ```
 
+`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 与
-ZIP，以及 Linux 的 AppImage 与 DEB。Windows portable ZIP 解压后可直接
+ZIP，以及 Linux 的 AppImage、DEB 与 RPM。Linux 原生 Runner 必须安装
+`rpm`/`rpmbuild` 工具后再调用 electron-builder。Windows portable ZIP 解压后可直接
 运行 `GoodBuddy.exe`，并包含启用便携数据目录的
 `.goodbuddy-portable.json`。每个目标目录都包含带文件大小和 SHA-256 的
 `release-manifest.json`。
@@ -166,12 +398,60 @@ 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 的不可变版本目录，并公开校验 14 个安装包。验证通过后才创建或
+更新 draft GitHub Release、上传 22 个 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”“使用前
@@ -184,13 +464,43 @@ manifests、总 `release-manifest.json` 和 `SHA256SUMS`。随后工作流创建
 
 ```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 和 ZIP，并在 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 签名凭据，并重新验证
+安装、升级和系统安全提示。
 
 ## 发布前冒烟测试
 

FEATURES.md

@@ -1,92 +1,583 @@
-# 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] **文件、截图、窗口、剪贴板上下文**：用户明确选择后才加入模型上下文。
-- [x] **富文本回答**：支持 GitHub Flavored Markdown、LaTeX 数学公式和受控 Mermaid 图表；大图可缩放、拖动或查看源码，失败时保留原始图表代码。
-- [ ] **项目 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] **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 and expanded directories; more than 50 changes
+  remain accessible through incremental loading.
+- [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.
+  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.
+- [ ] **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).
 
-- [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行和图像生成。
-- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、超时和活动记录。
-- [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 运行已启用且受边界约束的工具。
-- [x] **专家与 Subagent**：支持显式专家、团队分析和最多三个只读专家并行分析。
-- [x] **角色绑定模型连接**：每个角色可继承默认模型或选择独立文本模型连接，失效连接安全回退默认模型，综合角色始终继承默认模型。
-- [x] **多协议模型配置**：支持 Anthropic Messages、OpenAI Chat Completions、OpenAI Images 和无认证本机模型。
-- [x] **上下文用量与自动压缩**：直连模型按每次成功调用更新供应商用量，图片与工具轮次使用同一口径，供应商缺失 usage 时才回退估算；界面明确区分“本次模型调用”和“压缩后对话估算”，压缩线始终根据当前设置与所选模型窗口即时计算，不在每个对话中保存旧配置；压缩标识的前后值使用同一估算口径，运行记录仍保留各次模型调用的供应商 usage。对话与多轮工具 Agent 可在已完成调用越过阈值后自动重复压缩，规划时先为固定提示、工具定义和摘要预留预算；同一回复会分别保留 Agent 工具上下文与对话历史的压缩标识，并在应用重启或较早消息滚出本地历史窗口后继续复用摘要。
-- [x] **Main-only 凭据保护**：API Key 使用系统安全存储加密，不暴露给 Renderer。
-- [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；外部 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 监督侧栏**（规划中）：在聊天右侧助手工作栏统一承载 OpenCode、Continue 和 DeepSeek Harness 的 Subagent 控制、后台 Job、Workflow/Hook、长任务与原生会话监督；Composer 只保留对当前消息生效的高频上下文选择。
-- [ ] **可执行 Subagent**（规划中）：提供显式 Execute 委派，限制嵌套、并行、Token、时间和工具权限，在右侧 Runtime 监督页签显示父子状态、取消入口和审计归属。
+### Agent Runtimes and model connections
 
-### Skills、MCP 与知识库
+- [x] **Direct model Runtime**: Supports question answering, knowledge
+  synthesis, controlled tool execution, and image generation.
+- [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, total execution
+  limits, 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. 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. 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 receives no such override 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.20`, while the current Desktop release candidate is `0.12.6`; 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.
+- [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
+  source can use the current format-v1 package. GitHub, Beijing mirror, Linux
+  x64/arm64, cancellation, and offline GoodBuddy transfer validation remains.
+  This status does not mean the path is published or has completed real-Host
+  testing.
+- [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. 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.
+- [x] **Experts and Subagents**: Supports explicit experts, team analysis, and
+  up to three read-only experts running in parallel. 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] **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.
+- [ ] **Executable Subagents** (planned): Explicit Execute delegation with
+  bounded nesting, parallelism, tokens, time, and tool permissions, aggregated
+  by Task in the workbar's fixed Runtime section with cancellation and audit
+  ownership.
 
-- [x] **Skills 按需接入**：可分配给直连模型、OpenCode、Continue 和 DeepSeek Harness，并使用有界资源和受控 Runtime 边界。
-- [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，动态工具仍会重新发现并经过现有执行记录与权限边界。
-- [x] **MCP Prompts 与 Resources 元数据**：MCP 测试仅在 Server 声明对应能力时发现有界的 Prompt、参数与 Resource 元数据，不读取 Resource 内容；Runtime 支持的 Prompt 可填入聊天草稿后继续编辑。OpenCode 可报告实验性 Resource 清单，Continue 当前版本明确不支持 Resources。
-- [x] **本地知识库**：支持文件、目录和网页导入、SQLite FTS5 检索及来源追溯。
-- [x] **知识图谱**：支持规则、模型和混合抽取，以及实体、关系、别名和证据维护。
-- [x] **向量模型配置与检索**：可配置兼容 Embeddings 接口并用于语义检索。
-- [x] **向量诊断与索引任务**：提供真实向量生成诊断、按文档重建进度、取消、失败状态与重启后结果恢复；每篇成功文档立即可用于检索。
-- [x] **混合检索测试台**：支持全文、中文词组、向量和图谱通道诊断，可调 Top K、阈值、权重、本地或学习型重排及上下文预算。
-- [x] **分块、维护与评估**：支持固定、结构化和父子分块，分块维护、可取消重建及双语检索评估。
-- [x] **受控知识本体**：每个知识库可定义实体、关系、别名和端点约束，保留证据偏移、置信度和抽取来源，并显式提示图谱重建。
-- [x] **强制检索与引用上下文**：对话可按需或每次先检索，显示零结果、降级、失败与取消状态，并可查看引用上下文或安全打开来源。
-- [x] **魔法笔记 / Magic Notes**：提供本地优先的笔记与待办工作台、范围管理、编辑、筛选和受控 AI 评论；创建、保存和评论结果使用统一应用通知。
-- [ ] **MCP Server Control Plane**（规划中）：统一 MCP 生命周期、健康检查、重连、Schema 缓存、隔离、审批和审计。
-- [ ] **可追溯笔记摘录与 AI 编辑**（规划中）：从对话、知识和网页收集带来源的摘录，并提供需确认的总结、改写和整理操作。
+### 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 are still rediscovered and pass
+  through existing activity and permission boundaries.
+- [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 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] **任务、活动与成果**：集中管理任务状态、审计活动和成果文件；Token 用量按 Runtime 与模型归类，并针对 OpenAI 兼容与 Anthropic Messages 的不同上报口径归一化展示缓存命中率；活动按会话分组并默认收起，避免长历史占满页面。
-- [x] **记忆与智能心跳**：提供周期回顾、建议记忆、洞察、后续任务和可审计运行轨迹。
-- [ ] **批量运行与对比实验室**（规划中）：对模型、Prompt、角色和工作流配置执行批量对比，汇总质量、耗时、Token、费用、失败率和成果差异。
-- [ ] **时态记忆与事实冲突检测**（规划中）：为记忆和知识图谱增加有效期、当前事实、过期与矛盾检测、事实核验及证据回溯。
-- [ ] **可视化受控工作流**（规划中）：提供版本化 DAG、条件分支、审批、取消和恢复，执行节点继续经过 Main Runtime 边界。
-- [ ] **统一 Run Graph 与回放**（规划中）：关联任务、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,
+  and a persistent warning remains when a migrated legacy cache may already
+  have lost older records or detail. 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. 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] **版本检查与镜像节点**：在“关于与更新”中选择 GitHub（默认）或镜像节点；手动检查、启动时检查和下载页使用同一选择，并只读取固定可信的发布索引，不自动下载或安装。
-- [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.
+- [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 mode**: Enabled by default and permits
+  in-app HTTP plus invalid, self-signed, or expired HTTPS certificates.
+  Disabling it restores strict address and certificate validation.
 
-- [x] **0BSD 开源许可**：原创代码可自由使用、复制、修改、分发和商用；第三方组件和资源仍遵循各自许可证。
-- [x] **可复现依赖安装与源码构建**：使用锁定依赖、Node.js 24 和统一的测试、类型检查、Lint、生产构建命令。
-- [x] **六平台原生发布矩阵**：Windows、macOS、Linux 的 `x64`、`arm64` 目标由原生 Runner 构建，并提供发布清单和 SHA-256 哈希。
+### Open source, builds, and releases
 
-### 开放接口、团队协作与远程执行
+- [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. Linux also produces AppImage, DEB, and RPM.
 
-- [x] **远程任务委派**：仅在用户显式配置端点和令牌后启用，按全局内网兼容模式使用 HTTP(S)，结果进入持久化发件箱。
-- [ ] **Headless Runtime API**（规划中）：提供本机优先的任务、事件、状态和成果 API，以及有范围、有效期、限流和撤销能力的令牌。
-- [ ] **GoodBuddy Team Hub**（规划中）：以可选服务提供组织、RBAC、项目共享、远程 Agent、策略下发和租户审计。
-- [ ] **多云远程沙盒 Agent**（规划中）：通过云厂商 API 和 SSH Agent 管理专用 Linux 沙盒；凭据留在 Main 进程，高风险控制面操作单独确认。
+### Open interfaces, team collaboration, and remote execution
 
-## 规划原则
+- [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.
 
-规划中的工作流、Subagent、MCP、远程 API 和沙盒能力不得绕过现有 Main Runtime、Ask/Execute、权限、取消、超时和审计边界。
+## Roadmap Principles
+
+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,119 @@
+# GoodBuddy 功能矩阵与路线图
+
+[English](./FEATURES.md) | **简体中文**
+
+本文记录 GoodBuddy 的已提供能力和路线图。未完成项目不代表已包含在当前版本中。
+
+## 状态说明
+
+- [x] 已提供
+- [ ] 开发中或规划中，具体以条目标注为准
+
+## 功能总表
+
+### 桌面基础、工作空间与上下文
+
+- [x] **跨平台桌面应用**：支持 Windows、macOS、Linux，以及 `x64`、`arm64` 发布目标。
+- [x] **信创软硬件覆盖**：正式 Linux 安装包覆盖国产 `x64` 与 `arm64` 架构，可用于统信 UOS、银河麒麟及海光、兆芯、鲲鹏、飞腾等兼容环境。龙芯 LoongArch 另行提供 `loong64` 实验预览版，不属于正式发布矩阵，也未纳入自动更新。这里的覆盖范围不等同于厂商或整机兼容认证，具体状态与限制见[龙芯预览版构建说明](./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] **富文本回答**：支持 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、模型、审批策略、预算和超时，并支持模板复用。
+- [ ] **通用助手工作栏与执行空间后续能力**（规划中）：在现有工作栏和多终端基础上继续加入监督、统一 Runtime、受管进程、静态安全 HTML 预览、可固定目标的工作区/浏览器/成果实例、底部停靠与独立窗口。Task Center 保持 Task 的单例索引，附件与知识库继续由会话输入区管理，未来的记忆与历史执行上下文归入关联 Task。详见 [Feature PRD](./docs/features/assistant-workbar/prd.md)。
+
+### Agent Runtime 与模型连接
+
+- [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行和图像生成。
+- [x] **直连模型编程 Agent**：本机直连文本模型可在 Execute 模式运行平台 Shell，并可按父请求模式、模型、工作区和能力范围委派一层编程 Subagent；OpenCode、Continue、DeepSeek Harness 和托管 SSH 不重复注入这两个工具。Windows 本机命令与真实模型“修改、测试、修复、复核”闭环已通过，macOS 与 Linux 真机命令仍待对应平台验收。
+- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、总执行时限、有界流式输出和活动记录；共享进程回收逻辑保留 Windows 完整进程树终止，并对采用独立进程组的 POSIX 子进程执行组回收。聊天状态检查使用一次性探测 Runtime 并在返回后立即回收，不进入按模型与项目隔离的执行 Runtime 缓存；本机 GoodBuddy 管理的 OpenCode 在该被动检查中只确认所选路径和模型凭据，不启动用后即毁的 Server，设置中的显式连接测试和原生能力清单仍执行完整启动及健康检查，原生能力清单随后与首次实际请求复用同一个执行 Runtime，不再重复冷启动；执行 Runtime 仍按项目复用。本机 GoodBuddy 管理的 OpenCode 只对同一会话内的请求保持顺序，不同会话即使属于同一项目也可并行，不同项目同样可并行；请求级动态 MCP 通过默认通配禁用和当前请求精确放行保持隔离。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 验收**：源码已可使用当前 format v1 包；仍需完成 GitHub、北京镜像、Linux x64/arm64、取消和离线 GoodBuddy 传输的真实 Host 验收。当前状态不表示已发布或已完成真实 Host 测试。
+- [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] **专家与 Subagent**：支持显式专家、团队分析和最多三个只读专家并行分析；聊天先展示可逐项展开的专家完整输出，再在其下展示总 Agent 的综合结果，并随会话保存。
+- [x] **OpenCode 子代理过程与最终结果**：子代理卡片按顺序显示文字、推理和工具过程，最终结果独立展示。远程实时过程需要 Agent `0.11.20`，旧包仍显示最终结果但不补造缺失过程。
+- [x] **OpenCode 事件连接回收**：请求结束或取消后关闭自身订阅，不取消其他并行会话。
+- [x] **直连模型命令工作目录**：Execute 命令可通过绝对路径、相对路径或符号链接使用工作区外目录；工作区仍为默认目录和相对路径基准，Ask 保持只读。
+- [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**（规划中）：提供显式 Execute 委派，限制嵌套、并行、Token、时间和工具权限，在助手工作栏固定的 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，动态工具仍会重新发现并经过现有执行记录与权限边界。
+- [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] **智能心跳入口与范围改善**：将“智能心跳 > 心跳计划”作为完整配置的唯一权威入口，支持创建和编辑 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] **远程消息通道项目**：微信 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 证书，关闭后恢复严格地址和证书校验。
+
+### 开源、构建与发布
+
+- [x] **0BSD 开源许可**：原创代码可自由使用、复制、修改、分发和商用；第三方组件和资源仍遵循各自许可证。
+- [x] **可复现依赖安装与源码构建**：使用锁定依赖、Node.js 24 和统一的测试、类型检查、Lint、生产构建命令。
+- [x] **六平台原生发布矩阵**：Windows、macOS、Linux 的 `x64`、`arm64` 目标由原生 Runner 构建，并提供发布清单和 SHA-256 哈希；Linux 同时生成 AppImage、DEB 和 RPM。
+
+### 开放接口、团队协作与远程执行
+
+- [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、权限、取消、超时和审计边界。

README.en.md

@@ -1,78 +0,0 @@
-# GoodBuddy
-
-English | [简体中文](README.md)
-
-A secure, cross-platform, local-first desktop AI assistant and Agent workspace.
-
-![GoodBuddy workspace](docs/screenshots/workspace-overview.png)
-
-## Highlights
-
-- **Controlled execution**: `Ask` stays read-only; `Execute` runs only enabled tools within defined boundaries and records their activity.
-- **Local-first data**: Conversations, tasks, artifacts, memory, knowledge bases, and graphs are stored in local SQLite. API keys are encrypted by the operating system.
-- **Multiple runtimes**: Connect directly to models or use OpenCode, Continue, and the preview DeepSeek Harness, with cancellation, timeouts, output limits, and process cleanup.
-- **Open integrations**: Supports OpenAI Responses, OpenAI-compatible Chat Completions, Anthropic Messages, OpenAI Images, Embeddings, cross-runtime Skills and custom MCP, plus a default-off DeepSeek Harness npm plugin marketplace that users enable explicitly.
-- **Knowledge workspace**: Import files, folders, and web pages, then search them with full-text, phrase, vector, and graph retrieval.
-- **Work management**: Organize projects, conversations, tasks, activity, artifacts, memory, Magic Notes, and Smart Heartbeat.
-- **Remote channels**: Connect WeChat ClawBot, WeCom, and DingTalk with separate remote sessions for each sender.
-- **Desktop context**: Add selected files, screenshots, application windows, clipboard content, and voice.
-- **Offline speech**: Use local SenseVoice, Paraformer, and Whisper models.
-- **Rich responses**: Render Markdown, LaTeX, and controlled Mermaid diagrams.
-
-![GoodBuddy knowledge workspace](docs/screenshots/knowledge-workspace.png)
-
-![GoodBuddy knowledge graph](docs/screenshots/knowledge-graph.png)
-
-![GoodBuddy Magic Notes](docs/screenshots/GoodBuddy_MFSGeK0NoT.gif)
-
-![GoodBuddy Smart Heartbeat](docs/screenshots/smart-heartbeat.png)
-
-See [FEATURES.md](FEATURES.md) for the detailed feature matrix and roadmap.
-
-## Install
-
-Download a build from [GitHub Releases](https://github.com/mesalogo/goodbuddy/releases):
-
-| Platform | Architectures | Formats |
-| --- | --- | --- |
-| Windows | `x64`, `arm64` | NSIS, portable ZIP |
-| macOS | `x64`, `arm64` | DMG, ZIP |
-| Linux | `x64`, `arm64` | AppImage, DEB |
-
-Code signing and macOS notarization are not configured yet, so your 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.
-
-## Privacy and security
-
-- Model requests are sent only to services selected by the user.
-- Local data stays in the operating system's application data directory by default.
-- The Renderer has no access to raw Electron APIs or model credentials.
-- The DeepSeek Harness plugin marketplace is off by default. After it is enabled and a third-party plugin is installed, its install scripts, initialization, and Execute tools run with the current user's permissions. Turning off the marketplace only hides its catalog and management interface; it does not disable or uninstall existing plugins. Installation requires explicit confirmation, and Ask limits only model tool calls.
-- Remote delegation is disabled until 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
-```
-
-## 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.md

@@ -1,49 +1,113 @@
+<div align="center">
+  <img src="./sites/assets/goodbuddy-light.png" width="96" alt="GoodBuddy" />
+
 # GoodBuddy
 
-[English](README.en.md) | 简体中文
+**Desktop access to model chat, coding agents, knowledge, and scheduled work**
 
-安全、跨平台、本地优先的桌面 AI 助手与 Agent 工作空间。
+**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)
 
-## 核心能力
+[![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>
 
-- **安全执行**：`Ask` 保持只读；`Execute` 仅运行已启用且受边界约束的工具，并保留活动记录。
-- **本地优先**：会话、任务、成果、记忆、知识库和图谱保存在本地 SQLite；API Key 由系统安全存储加密。
-- **多 Runtime**：支持直连模型、OpenCode、Continue 和预览版 DeepSeek Harness，统一处理取消、超时、输出限制和进程退出；原生能力清单将 Tools 与 Commands、LSP、Formatters 分开，并显示来源及 Ask/Execute 可用性。内置 OpenCode 提供 Agent、Tool、Command 与原生 Compact，Continue 提供 Rules、Prompt 预设、结构化提问与 GoodBuddy 手动摘要压缩，并明确标记当前版本无法静态发现原生 Tools。
-- **开放连接**：支持 OpenAI Responses、OpenAI 兼容 Chat Completions、Anthropic Messages、OpenAI Images、Embeddings、跨 Runtime Skills 与自定义 MCP，以及默认关闭、由用户显式开启的 DeepSeek Harness npm 插件市场。MCP 测试可读取有界 Prompt/Resource 元数据，但不会读取 Resource 内容。
-- **知识工作区**：支持文件、目录和网页导入，以及全文、词组、向量和图谱混合检索。
-- **工作管理**：集中管理 Projects、对话、任务、活动、成果、记忆、魔法笔记和智能心跳。
-- **远程通道**：支持微信 ClawBot、企业微信和钉钉，每个发送者使用独立远程会话。
-- **桌面上下文**：可选择文件、截图、应用窗口、剪贴板和语音作为上下文。
-- **离线语音**：支持 SenseVoice、Paraformer 和 Whisper 本地模型。
-- **富文本回答**：支持 Markdown、LaTeX 公式和受控 Mermaid 图表。
+![GoodBuddy workspace](./docs/screenshots/workspace-overview.png)
 
-![GoodBuddy 知识工作区](docs/screenshots/knowledge-workspace.png)
+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.
 
-![GoodBuddy 知识图谱](docs/screenshots/knowledge-graph.png)
+## Highlights
 
-![GoodBuddy 魔法笔记](docs/screenshots/GoodBuddy_MFSGeK0NoT.gif)
+- **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.
 
-![GoodBuddy 智能心跳](docs/screenshots/smart-heartbeat.png)
+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.
 
-完整功能和路线图见 [FEATURES.md](FEATURES.md)。
+## Capabilities
 
-## 安装
+| 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 |
 
-从 [GitHub Releases](https://github.com/mesalogo/goodbuddy/releases) 下载：
+## Product tour
 
-| 系统 | 架构 | 格式 |
+### Knowledge bases and graphs
+
+![GoodBuddy knowledge workspace](./docs/screenshots/knowledge-workspace.png)
+
+![GoodBuddy knowledge graph](./docs/screenshots/knowledge-graph.png)
+
+### Magic Notes and Smart Heartbeat
+
+![GoodBuddy Magic Notes](./docs/screenshots/GoodBuddy_MFSGeK0NoT.gif)
+
+![GoodBuddy Smart Heartbeat](./docs/screenshots/smart-heartbeat.png)
+
+## Agent Runtimes
+
+| Runtime | Functions | Configuration |
 | --- | --- | --- |
-| Windows | `x64`、`arm64` | NSIS、便携 ZIP |
-| macOS | `x64`、`arm64` | DMG、ZIP |
-| Linux | `x64`、`arm64` | AppImage、DEB |
+| 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 |
 
-当前尚未配置代码签名和 macOS notarization，系统可能显示安全提示。
+Each run reports cancellation, timeouts, token usage, tool calls, and history.
+Runtime-specific capabilities and configuration remain separate.
 
-## 从源码运行
+## Download
 
-需要 Node.js 24 和 npm：
+Download a build from
+[GitHub Releases](https://github.com/mesalogo/goodbuddy/releases):
+
+| Platform | Architectures | Formats |
+| --- | --- | --- |
+| Windows | `x64`, `arm64` | NSIS, portable ZIP |
+| macOS | `x64`, `arm64` | DMG, ZIP |
+| Linux | `x64`, `arm64` | AppImage, DEB, RPM |
+
+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.
+
+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
@@ -52,20 +116,35 @@ npm ci
 npm run dev
 ```
 
-构建与打包说明见 [BUILD.md](BUILD.md)。
+See [BUILD.md](./BUILD.md) for build and packaging instructions.
 
-## 隐私与安全
+## Documentation
 
-- 模型请求只发送到用户选择的服务。
-- 本地数据默认保存在系统应用数据目录。
-- Renderer 不接触原始 Electron API 或模型凭据。
-- DeepSeek Harness 插件市场默认关闭；开启并安装第三方插件后，其安装脚本、初始化和 Execute 工具以当前用户权限运行。关闭市场只隐藏目录和管理界面，不会停用或卸载已有插件；安装前会明确确认。Ask 只允许 Host 原生 `read`/`skill` 与 Main 管理的 Web Search/Fetch，不允许调用第三方插件工具，也不能限制插件初始化代码。
-- 远程委派仅在用户配置端点和令牌后启用。
-- 内网兼容模式允许应用内 HTTP 和非标准 HTTPS 证书；微信凭据和媒体端点仍执行严格校验。
+- [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
 
-欢迎提交 Issue 和 Pull Request。请先阅读 [AGENTS.md](AGENTS.md)，提交前运行：
+- 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
@@ -73,14 +152,16 @@ npm run typecheck
 npm run lint
 ```
 
-## 社区交流
+## Community communication
 
-目前采用微信群的方式供大家高效交流，大家可以微信扫码进入社区群：
+Scan the QR code to join the GoodBuddy WeChat group:
 
-<img width="1279" height="1306" alt="056bfac87840a95547f9805a8122fc2d" src="https://github.com/user-attachments/assets/b3342635-60a1-484c-959c-f90ba3c39d69" />
+<img width="1250" height="1194" alt="9627ce196b0de42f123c33dd9dea1568" src="https://github.com/user-attachments/assets/e806543f-6d8a-4c5c-ba44-19e74dac9a78" />
 
 
 
-## 开源许可
+## License
 
-GoodBuddy 的原创代码采用 [0BSD License](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

@@ -2,7 +2,8 @@
 
 ## 1. 目的与适用范围
 
-本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、知识库、智能心跳、运行记录，以及后续新增的一级页面。
+本文定义 GoodBuddy 桌面端的统一界面规则，适用于聊天与最近对话、任务中心、知识库、
+智能心跳、运行记录，以及后续新增的一级页面。
 
 设计系统解决两类问题：
 
@@ -144,7 +145,7 @@
 | 变体 | 最大内容宽度 | 适用场景 | 页面映射 |
 | --- | --- | --- | --- |
 | `reading` | `820px` | 连续阅读、单列编辑、对话撰写 | 聊天正文与输入区 |
-| `standard` | `960px` | 常规列表、设置、表单与任务管理 | 最近对话、任务 |
+| `standard` | `960px` | 常规列表、设置与表单 | 最近对话、设置 |
 | `dashboard` | `1040px` | 指标、卡片网格、宽表格与审计数据 | 智能心跳、活动记录 |
 | `master-detail` | 可用空间内流式铺开 | 左侧选择、右侧编辑或预览 | 知识库 |
 
@@ -192,7 +193,7 @@
 
 ### 6.1 PageTabs
 
-用于同一一级页面内的同级内容面板，例如心跳的“成长概览”和“心跳计划”。
+用于同一一级页面内的同级内容面板，例如智能心跳的“运行概览”和“心跳计划”。
 
 - 使用 `tablist`、`tab` 和 `tabpanel` 语义，当前项使用 `aria-selected="true"`。
 - 一级页面之间的导航由应用主导航承担，不复用 `PageTabs`。
@@ -200,6 +201,7 @@
 - 项目过多时优先重组信息架构，不把一级页签做成多行。
 - `PageTabs` 可使用默认视觉或共享的 `segmented` 视觉变体。紧凑主从工作台中的 2 至 4 个同级面板可使用与模型设置一致的分段外观，但不得因此改用按钮组语义。
 - 视觉变体不改变组件含义：分段外观的 `PageTabs` 仍使用页签语义、单一激活面板、游标焦点和方向键切换，不复制页面专属样式。
+- 在独立滚动的 Flex 页面中，`PageTabs` 及其直接包装层必须保持 `flex: 0 0 auto`，不得被剩余内容压缩到零高度。新增页签容器时必须提供对应的 CSS 回归测试。
 
 ### 6.2 SegmentedControl
 
@@ -281,32 +283,137 @@
 - 一级导航与最近会话之间、最近会话与底部账户区之间必须有可见结构分隔线。浅色主题使用 `--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 应用顶栏与全局操作
+### 6.9 助手工作栏
 
-应用顶栏用于窗口级状态、侧栏开关和低频全局操作，不承担页面标题或主要导航。顶栏必须保持紧凑，不能与页面内容争夺注意力。
+助手工作栏是应用级右侧工具容器，不归属于聊天页面，也不根据当前页面、项目或 Runtime
+自动增删入口。产品契约见
+[通用助手工作栏与执行空间 PRD](./docs/features/assistant-workbar/prd.md)，
+动态 Tab、“+”和终端细节见
+[助手工作栏多终端页签 PRD](./docs/features/assistant-workbar/terminal-tabs-prd.md)。
 
-- 顶栏高度默认为 `58px`，图标按钮使用 `34px × 34px` 点击区域。
-- Runtime 状态、同步状态等短标签使用 `--font-caption`，不得放大为正文标题。
+- 升级后默认打开任务中心、工作区、浏览器和成果四个单实例应用，不根据当前页面或 Runtime
+  能力自动增删稳定应用目录入口。
+- Tab 行只显示已打开实例，行末始终提供“+”普通按钮；点击后在内容区打开应用选择页。
+  “+”不使用 `tab` 语义，也不能因为终端或其他应用已经打开而消失。
+- 应用注册表声明单实例或多实例。单实例重复选择时聚焦已有 Tab；终端从首期开始支持
+  多实例，每次选择创建独立 Tab 和 Shell Session。
+- Task Center 是 Task 的单例应用级索引，不使用“跟随 / 固定目标”多实例模式。每个 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 中 Agent 使用的同一隔离浏览器会话，用户导航会
+  有意改变 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.10 上下文单选菜单
+### 6.11 单选选择器
 
 模型、专家角色、工作模式、Runtime Agent、Runtime 预设和 Runtime 快捷操作属于同一输入上下文，其选择器必须共享结构、尺寸和菜单视觉，不能出现一个精细菜单与多个风格不一致的原生下拉框。
 
+- 只有选项能由单行短标签充分区分、不需要补充来源、位置、状态或说明时，才使用原生 `select`。
+- 当用户必须在选择前比较来源、范围、位置、连接状态或其他辅助信息时，使用与输入区选择器同类的自定义富信息单选菜单，不用 CSS 修饰原生 `select` 冒充富信息菜单。
 - 触发按钮复用统一的模型选择按钮样式，保持相同高度、圆角、边框、展开指示和焦点状态。
 - 菜单使用 `menu` 与 `menuitemradio` 语义，当前项同时显示选中标记和 `aria-checked`。选项可以包含一行简短说明，但标签和说明不得被截断到无法区分。
 - 支持上、下方向键、Home、End、Enter 或 Space、Escape；打开后焦点进入当前项，关闭后返回触发按钮。
 - 点击或聚焦菜单外部时关闭；同一输入区内的模型、专家和模式菜单互斥展开。
 - 不可用选项保持可读并说明原因，键盘导航不得停留在不可选择项上。
-- 仅在选项简单且不需要说明、禁用原因或一致菜单行为时使用原生 `select`。
+- 当某个选项需要用户在其展开区域内完成路径选择、授权或其他前置操作时，不得因为前置条件
+  尚未完成而禁用该入口。选择入口只展开流程，验证成功前不提交实际值；不得自动采用第一个
+  候选。取消保持原值，验证错误在对应操作附近显示。
+- 项目选择器属于富信息单选菜单。收起时保持当前项目名称紧凑可见；展开后每项至少显示项目名称，并按数据可用性补充目录、远程来源或其他能帮助辨认项目的信息。托管 SSH 项目在“远程项目”内按已保存 SSH Host 做一层轻量分组，Host 标题旁显示真实 Agent 连接状态；项目副标题只显示远端路径，不重复“托管 SSH”类型。
+- 项目菜单区分“本地项目 / 远程项目 / 远程通道”，不把消息通道命名为远程项目。“远程项目（技术预览）”关闭时完整移除远程项目分组，而不是显示不可操作的残留选项；本地项目和远程通道继续可用。Agent 连接状态使用“未连接 / 连接中 / 就绪 / 异常”等文字标签，读取状态不得发起连接，且不能只依赖图标或颜色；新增项目来源时不得退回仅列名称的原生 `select`。
 
-### 6.11 应用通知与就地反馈
+### 6.12 应用通知与就地反馈
 
 应用级通知统一进入全局通知视口，页面不得自行复制通知卡片或在内容流中长期堆放短期消息。
 
@@ -317,7 +424,7 @@
 - 就地错误必须与对应字段或操作建立程序化关联；全局错误使用 `alert` 和 assertive 实时区域，成功与信息使用 `status` 和 polite 实时区域。
 - 一个事件只能选择一种主要反馈位置，不得同时显示页内横幅和全局通知。失败时不得因通知切换而清空用户输入、筛选或未提交草稿。
 
-### 6.12 Switch 与 Checkbox
+### 6.13 Switch 与 Checkbox
 
 Switch 用于在两个持久状态之间立即切换，例如启用能力、开启索引、允许群消息或显示平台入口。Checkbox 用于独立多选、范围分配或执行前确认，例如选择多个 Runtime、选择知识库、清除已保存密钥。两者不得只因底层都使用 `input[type="checkbox"]` 而混用视觉或语义。
 
@@ -470,13 +577,31 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 
 - 使用 `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 后续的 Subagent 层级与取消、后台 Job 队列/进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止及原生会话监督统一进入右侧助手工作栏的“Runtime”页签，不加入 Composer。侧栏按当前会话和 Runtime 能力动态显示区块，不为未支持能力渲染空卡片或成排禁用按钮；切换会话或 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` 的基准宽度换行而不是被挤压；不能把专属控件重新塞回通用工具栏。
@@ -484,6 +609,9 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - “Enter 发送 · Shift+Enter 换行 · Ctrl+V 粘贴图片或文本”等输入操作提示放在空输入框内部，作为主占位文案的次级行；不得在输入框下方单独占用第二行。输入框下方只保留一行当前模式、安全边界或全局快捷键说明。
 - 输入操作提示不能替代表单的可访问名称，输入框始终保留持久的程序化标签。
 - 空对话展示可执行的起始建议，发送失败保留输入并提供重试。
+- 消息流的滚动范围必须使用已渲染消息的真实高度。长会话可以按批次只挂载最近消息并由用户
+  加载更早内容，但不得用固定的消息占位高度替代实际布局，避免推理、工具列表或长正文被
+  排除在可滚动范围之外。
 
 ### 13.2 最近对话
 
@@ -491,6 +619,11 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - 搜索、范围和时间筛选位于筛选工具栏。
 - 行项目统一显示标题、范围、最近更新时间和必要状态。
 - 侧栏最近会话的更新时间在当天显示本地时间，非当天显示本地日期；非当年记录必须同时显示年份。悬停时间信息时提供完整日期和时间。
+- 侧栏中有关联 Task 的 Conversation 显示行首展开按钮，父行不显示任务标签或数量；展开后
+  最多直接显示 3 个 Task，“查看全部 N 个任务”打开该 Conversation 的完整任务区。
+- Task 子项左侧显示名称，右侧显示本地化的 Ask/Execute、计划摘要和共享状态标记，与父会话
+  的更新时间位置一致；已完成使用带勾成功点，不重复显示完成文字。点击子项打开同一
+  Conversation 并定位 Task，不继续展开 Job/Run。
 - 删除入口使用 `danger-ghost`，并按数据可恢复性执行确认或撤销策略。
 
 ### 13.3 知识库
@@ -504,11 +637,30 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 ### 13.4 智能心跳
 
 - 使用 `dashboard` 壳层。
-- 顶部先呈现运行状态、当前范围和主操作，再呈现指标和配置。
+- 顶部先呈现运行状态、实际范围和主操作，再呈现指标、建议、历史与配置。
+- 范围明确区分 Global 与指定的一个或多个 Project；Global 与指定项目互斥，多项目选择使用
+  Checkbox，不能依靠进入页面时的当前项目推断。
 - 状态卡片使用统一状态令牌，不只依赖颜色。
-- 运行历史与配置使用明确区块，不以多套相似页签混合导航、开关和筛选。
+- 保留“运行概览 / 待处理建议 / 报告与记录 / 心跳计划”四个同级页面。
+- 智能心跳菜单入口是完整配置的权威位置；任务中心和设置中心不得复制同一 CRUD 表单。
+- 分区记忆协同与唤起条件尚未实现，不得显示占位入口或平行的记忆类型。
 
-### 13.5 运行记录
+### 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 默认 Execute，并允许主动切换 Ask。Execute 持续显示实际 Runtime、Project、
+  工作目录、工具和审批摘要；不支持工具时不得静默降级。
+
+### 13.6 运行记录
 
 - 使用 `dashboard` 壳层，并通过 `PageTabs` 提供“任务与会话 / 活动时间线 / 用量统计”三个同级视图。
 - 默认视图按“项目 → 任务或会话 → 活动详情”组织，项目范围持续可见，任务或会话详情可以折叠。
@@ -517,14 +669,23 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - 用量统计与活动记录分离，支持按项目、会话和模型切换统计维度，宽表格在独立容器内横向滚动。
 - 活动状态筛选使用 `SegmentedControl`，不与页面页签混合。清空历史遵循破坏性操作政策。
 
-### 13.6 魔法笔记
+### 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.7 设置中心
+### 13.8 设置中心
 
 - 全页设置使用固定标题区、左侧分类导航和独立滚动的内容区。右上角关闭按钮是离开设置中心的稳定入口。
 - 左侧分类导航在宽屏使用 `220px`，中等窗口使用 `196px`，窄窗口转为横向滚动；纵向滚动条仅在内容溢出时占用右侧空间，不在左侧创建镜像预留，选项与左侧可见边界保持默认内距。分类标题使用正文级字号，分类说明使用辅助字号；右侧内容区在可用空间内流式伸缩，最大宽度使用 `standard` 壳层的 `960px`，不得以页面专属较窄宽度压缩表单。
@@ -533,16 +694,26 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - 所有分类使用共享的 `SettingsCategoryHeader` 呈现分类标题、说明、错误与操作，不得在内容卡片内复制分类标题或创建页面专属操作栏。左侧分类名称与说明来自同一份分类定义，新增分类时不得分别维护导航和内容标题。
 - 当前分类存在“保存”或“测试”等未提交配置操作时，统一放在分类页头右侧；主保存操作在最右侧，测试等次操作排列在其左侧。
 - 自动生效、仅执行即时命令或自行管理编辑流程的分类不显示全局保存操作。窄窗口下操作区可以换行，但保存入口必须保持清晰可见。
+- 智能心跳的单条配置不在设置中心重复管理。设置中心如需呈现平台级说明，只提供
+  “打开智能心跳”导航，不复制创建、暂停、恢复或删除表单。
 - 保存或测试成功统一进入应用通知视口，并按全局规则自动消失，不在分类页头或内容卡片中保留持久成功文案。加载、保存和测试错误显示在分类页头下方，并保留可处理的上下文。
-- “关于与更新”的更新源位于“启动时检查新版本”开关下方，常规宽度下将标签、原生单选下拉框和用途说明放在同一行，并复用设置表单的统一控件样式；关闭启动检查后，下拉框置灰且不可操作。选项显示“GitHub（默认）”和中性的“镜像节点”。该选择同时控制手动检查、启动时检查和下载页，不显示底层服务商名称。
+- “模型连接”的认证字段按“认证方式 → 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 卡片与 Skills 一样提供持久启停和 Runtime 分配；直连模型、GoodBuddy 管理的 OpenCode 与 Continue 默认选中且可调整，DeepSeek Harness 必须以置灰、未选择和“暂不支持”文案持续显示，不能呈现为可保存的分配。魔法笔记 MCP 的自身启停与平台功能依赖分别显示，依赖未开启时保留用户配置并说明当前不会加载。
+- 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.8 文档解析设置
+### 13.9 文档解析设置
 
 - 设置中心新增独立的“文档解析”分类，统一管理聊天附件、知识库导入以及后续文档审阅场景使用的提取、转换和 OCR 策略。OCR 不作为普通对话模型出现在“模型连接”中。
 - 分类页头说明文档解析的跨场景作用，右侧依次显示“测试解析”和“保存设置”；保存位于最右侧。测试必须选择真实文件并执行实际解析，不能只检查模型文件或接口连通性。
@@ -609,8 +780,9 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - [ ] 将输入快捷键与附件提示置于空输入框内部，输入区下方保持单行说明。
 - [ ] 最近对话迁移到 `standard`，统一搜索、范围、时间和删除行为。
 - [ ] 知识库迁移到 `master-detail`，清除内联浅色样式并补齐窄窗口单面板流程。
-- [ ] 智能心跳迁移到 `dashboard`，统一状态卡片、配置和运行历史层级。
-- [ ] 任务迁移到 `standard`，活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。
+- [x] 智能心跳使用 `dashboard`，保留概览、建议、轨迹和计划，并在计划中支持 Global / 多 Project 范围。
+- [x] 在现有工作栏中完善任务中心，统一范围、状态、最近进展和筛选，不新建平行任务平台。
+- [ ] 活动记录迁移到 `dashboard`，统一导航、筛选和表格行为。
 - [ ] 设置中心使用共享分类定义与 `SettingsCategoryHeader`，将保存与测试操作统一放到分类页头右侧，并把成功反馈接入应用通知。
 - [ ] 文档解析设置统一聊天附件与知识库的解析预设、OCR 状态、转换状态、隐私限制和真实文件测试。
 
@@ -636,3 +808,16 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 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.20",
+  "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,938 @@
+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 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
+      if (wanted && size > maximumMetadataBytes) {
+        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

@@ -21,8 +21,8 @@ const targetDefinitions = [
   { 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: '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(
@@ -219,7 +209,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 +272,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 +350,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/build-release.cjs

@@ -5,6 +5,7 @@ const {
   createWriteStream,
   existsSync,
   closeSync,
+  fstatSync,
   mkdirSync,
   mkdtempSync,
   openSync,
@@ -35,6 +36,12 @@ const {
 } = require('@electron/asar')
 const { Zip, ZipDeflate } = require('fflate')
 const { sha256File } = require('./file-hash.cjs')
+const {
+  detectBinaryArchitecture
+} = require('./binary-architecture.cjs')
+const {
+  readZipCentralDirectory
+} = require('./zip-central-directory.cjs')
 
 const root = join(__dirname, '..')
 const packageJson = JSON.parse(
@@ -45,17 +52,28 @@ const packageLock = JSON.parse(
 )
 const productName = packageJson.build?.productName ?? packageJson.name
 const releaseRoot = join(root, 'dist', 'release')
+const releaseBuilderConfig = join(
+  root,
+  'build',
+  'electron-builder.release.cjs'
+)
 const manifestName = 'release-manifest.json'
 const portableMarkerName = '.goodbuddy-portable.json'
 const harnessHostEntry =
   'out/main/deepseek-harness-host-bootstrap.js'
 const harnessBundleManifest = 'out/main/package.json'
 const harnessPackageVersions = {
-  '@deepseek-ai/dsh-agent': '0.1.0-rc.6',
-  '@napi-rs/canvas': '1.0.3',
-  'node-pty': '1.1.0'
+  '@deepseek-ai/dsh-agent':
+    packageLock.packages['node_modules/@deepseek-ai/dsh-agent']
+      ?.version,
+  '@napi-rs/canvas':
+    packageLock.packages['node_modules/@napi-rs/canvas']
+      ?.version,
+  'node-pty':
+    packageLock.packages['node_modules/node-pty']?.version
 }
-const koffiVersion = '3.1.4'
+const koffiVersion =
+  packageLock.packages['node_modules/koffi']?.version
 const harnessLicenseFiles = [
   'agent-client-protocol-Apache-2.0.txt',
   'deepseek-cordis-MIT.txt',
@@ -70,9 +88,11 @@ const portableRequiredFiles = [
   'resources/release-notes.json',
   'resources/icon.ico',
   'resources/tray-icon.png',
+  'resources/tool-environment/managed-python-artifacts.json',
   'resources/runtimes/opencode/opencode.exe',
   'resources/runtimes/continue/package.json',
   'resources/runtimes/npm/bin/npm-cli.js',
+  'resources/runtimes/npm/bin/npx-cli.js',
   'resources/runtimes/npm/package.json',
   'resources/runtimes/npm/node_modules/graceful-fs/package.json'
 ]
@@ -119,8 +139,8 @@ const platformDefinitions = {
   },
   linux: {
     builderFlag: '--linux',
-    defaultFormats: ['AppImage', 'deb'],
-    supportedFormats: ['AppImage', 'deb'],
+    defaultFormats: ['AppImage', 'deb', 'rpm'],
+    supportedFormats: ['AppImage', 'deb', 'rpm'],
     unpackedPattern: /^linux(?:-.+)?-unpacked$/u,
     executable: [packageJson.name],
     runtimeExecutable: 'opencode'
@@ -132,7 +152,8 @@ const formatExtensions = {
   dmg: '.dmg',
   zip: '.zip',
   AppImage: '.AppImage',
-  deb: '.deb'
+  deb: '.deb',
+  rpm: '.rpm'
 }
 
 function normalizePlatform(value) {
@@ -153,6 +174,7 @@ function parseArguments(argv, environment = process) {
     formats: [],
     skipBuild: false,
     dryRun: false,
+    unsigned: false,
     help: false
   }
   for (let index = 0; index < argv.length; index += 1) {
@@ -176,6 +198,8 @@ function parseArguments(argv, environment = process) {
       options.skipBuild = true
     } else if (argument === '--dry-run') {
       options.dryRun = true
+    } else if (argument === '--unsigned') {
+      options.unsigned = true
     } else if (argument === '--help' || argument === '-h') {
       options.help = true
     } else {
@@ -191,6 +215,9 @@ function parseArguments(argv, environment = process) {
   if (!supportedArchitectures.has(options.arch)) {
     throw new Error(`不支持的架构：${options.arch}`)
   }
+  if (options.unsigned && options.platform !== 'macos') {
+    throw new Error('--unsigned 仅支持 macOS 发布包')
+  }
   const definition = platformDefinitions[options.platform]
   const requestedFormats =
     options.formats.length > 0
@@ -321,7 +348,9 @@ function buildElectronBuilderArguments(options, outputDirectory) {
     )
   )]
   const builderArguments = [
-    join(root, 'node_modules', 'electron-builder', 'cli.js'),
+    join(root, 'build', 'run-electron-builder.cjs'),
+    '--config',
+    releaseBuilderConfig,
     definition.builderFlag,
     ...builderFormats,
     `--${options.arch}`,
@@ -337,62 +366,43 @@ function buildElectronBuilderArguments(options, outputDirectory) {
       `--config.nsis.artifactName=${productName}-\${version}-windows-\${arch}-setup.\${ext}`
     )
   }
+  if (options.platform === 'macos' && options.unsigned) {
+    builderArguments.push('--config.mac.notarize=false')
+  }
   return builderArguments
 }
 
-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'
-      }
-    }
+function electronBuilderEnvironment(
+  options,
+  environment = process.env
+) {
+  const builderEnvironment = {
+    ...environment,
+    CSC_IDENTITY_AUTO_DISCOVERY:
+      environment.CSC_IDENTITY_AUTO_DISCOVERY ?? 'false'
   }
-  if (
-    buffer.length >= 20 &&
-    buffer[0] === 0x7f &&
-    buffer.toString('ascii', 1, 4) === 'ELF'
-  ) {
-    const machine =
-      buffer[5] === 2
-        ? buffer.readUInt16BE(18)
-        : buffer.readUInt16LE(18)
-    if (machine === 62) {
-      return 'x64'
-    }
-    if (machine === 183) {
-      return 'arm64'
-    }
+  if (options.platform !== 'macos' || !options.unsigned) {
+    return builderEnvironment
   }
-  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'
-    }
+  for (const name of [
+    'CSC_LINK',
+    'CSC_KEY_PASSWORD',
+    'CSC_NAME',
+    'CSC_INSTALLER_LINK',
+    'CSC_INSTALLER_KEY_PASSWORD',
+    'APPLE_API_KEY',
+    'APPLE_API_KEY_ID',
+    'APPLE_API_ISSUER',
+    'APPLE_ID',
+    'APPLE_APP_SPECIFIC_PASSWORD',
+    'APPLE_TEAM_ID',
+    'APPLE_KEYCHAIN',
+    'APPLE_KEYCHAIN_PROFILE'
+  ]) {
+    delete builderEnvironment[name]
   }
-  return undefined
+  builderEnvironment.CSC_IDENTITY_AUTO_DISCOVERY = 'false'
+  return builderEnvironment
 }
 
 function binaryArchitecture(filePath) {
@@ -518,9 +528,10 @@ function targetHarnessPaths(options) {
     koffiPackage,
     koffiBinary,
     nodePtyBinary:
-      options.platform === 'linux'
-        ? 'build/Release/pty.node'
-        : `prebuilds/${platformName}-${options.arch}/pty.node`,
+      `prebuilds/${platformName}-${options.arch}/` +
+      (options.platform === 'windows'
+        ? 'conpty.node'
+        : 'pty.node'),
     nodePtyDirectory: `${platformName}-${options.arch}`
   }
 }
@@ -885,6 +896,10 @@ function verifyHarnessPackage(
     join(npmRoot, 'bin', 'npm-cli.js'),
     'DSH 插件安装 npm CLI'
   )
+  assertFile(
+    join(npmRoot, 'bin', 'npx-cli.js'),
+    'DSH 插件安装 npx CLI'
+  )
   if (
     !Array.isArray(npmManifest.bundleDependencies) ||
     npmManifest.bundleDependencies.length === 0
@@ -996,7 +1011,7 @@ function verifyHarnessPackage(
     'DeepSeek Harness Canvas'
   )
 
-  if (options.platform === 'darwin') {
+  if (options.platform === 'macos') {
     const helper = join(
       unpackedRoot,
       'node_modules',
@@ -1044,6 +1059,26 @@ function verifyUnpackedOutput(directory, options) {
   assertFile(applicationExecutable, '应用主程序')
   assertFile(join(resources, 'app.asar'), '应用 ASAR')
   assertFile(join(resources, 'release-notes.json'), '版本更新说明')
+  assertFile(
+    join(
+      resources,
+      'tool-environment',
+      'managed-python-artifacts.json'
+    ),
+    '托管 Python 产物目录'
+  )
+  assertFile(
+    join(resources, 'agent-release-keys.json'),
+    'Agent 受信任签名密钥'
+  )
+  assertFile(
+    join(resources, 'agent-runtime-lock.json'),
+    'Agent Runtime 锁定清单'
+  )
+  assertFile(
+    join(resources, 'remote-runtime-lock.json'),
+    'Remote Runtime 锁定清单'
+  )
   assertFile(runtimeExecutable, 'OpenCode Runtime')
   assertFile(
     join(resources, 'runtimes', 'continue', 'dist', 'index.js'),
@@ -1059,6 +1094,16 @@ function verifyUnpackedOutput(directory, options) {
     ),
     'DSH 插件安装 npm Runtime'
   )
+  assertFile(
+    join(
+      resources,
+      'runtimes',
+      'npm',
+      'bin',
+      'npx-cli.js'
+    ),
+    'DSH 插件安装 npx Runtime'
+  )
   verifyHarnessPackage(resources, options)
   for (const [filePath, label] of [
     [applicationExecutable, '应用主程序'],
@@ -1258,98 +1303,42 @@ async function createPortableZip(
 }
 
 function readZipEntryNames(filePath) {
-  const fileSize = statSync(filePath).size
-  if (fileSize < 22) {
-    throw new Error('Portable ZIP 缺少中央目录')
-  }
-  const endChunkSize = Math.min(fileSize, 65_557)
-  const endChunkStart = fileSize - endChunkSize
-  const endChunk = readChunk(
-    filePath,
-    endChunkSize,
-    endChunkStart
-  )
-  let endOffset = -1
-  for (let index = endChunk.length - 22; index >= 0; index -= 1) {
-    if (
-      endChunk.readUInt32LE(index) === 0x06054b50 &&
-      index + 22 + endChunk.readUInt16LE(index + 20) ===
-        endChunk.length
-    ) {
-      endOffset = index
-      break
-    }
-  }
-  if (endOffset < 0) {
-    throw new Error('Portable ZIP 缺少中央目录')
-  }
-  const diskNumber = endChunk.readUInt16LE(endOffset + 4)
-  const centralDisk = endChunk.readUInt16LE(endOffset + 6)
-  const diskEntryCount = endChunk.readUInt16LE(endOffset + 8)
-  const entryCount = endChunk.readUInt16LE(endOffset + 10)
-  const centralSize = endChunk.readUInt32LE(endOffset + 12)
-  const centralOffset = endChunk.readUInt32LE(endOffset + 16)
-  const absoluteEndOffset = endChunkStart + endOffset
-  if (
-    diskNumber !== 0 ||
-    centralDisk !== 0 ||
-    diskEntryCount !== entryCount ||
-    entryCount === 0xffff ||
-    centralSize === 0xffffffff ||
-    centralOffset === 0xffffffff ||
-    entryCount < portableRequiredFiles.length + 1 ||
-    entryCount > maxPortableZipEntries ||
-    centralSize < 46 ||
-    centralSize > maxPortableCentralDirectoryBytes ||
-    centralOffset + centralSize !== absoluteEndOffset
-  ) {
-    throw new Error('Portable ZIP 中央目录无效')
-  }
-  const centralDirectory = readChunk(
-    filePath,
-    centralSize,
-    centralOffset
-  )
-  const names = []
-  let offset = 0
-  for (let index = 0; index < entryCount; index += 1) {
-    if (
-      offset + 46 > centralDirectory.length ||
-      centralDirectory.readUInt32LE(offset) !== 0x02014b50
-    ) {
-      throw new Error('Portable ZIP 中央目录条目无效')
-    }
-    const nameLength = centralDirectory.readUInt16LE(offset + 28)
-    const extraLength = centralDirectory.readUInt16LE(offset + 30)
-    const commentLength = centralDirectory.readUInt16LE(offset + 32)
-    const entryLength = 46 + nameLength + extraLength + commentLength
-    if (offset + entryLength > centralDirectory.length) {
-      throw new Error('Portable ZIP 中央目录条目越界')
-    }
-    const name = centralDirectory
-      .subarray(offset + 46, offset + 46 + nameLength)
-      .toString(
-        centralDirectory.readUInt16LE(offset + 8) & 0x0800
-          ? 'utf8'
-          : 'latin1'
+  const handle = openSync(filePath, 'r')
+  try {
+    let parsed
+    try {
+      parsed = readZipCentralDirectory(
+        handle,
+        fstatSync(handle).size,
+        {
+          label: 'Portable ZIP',
+          minimumEntries: portableRequiredFiles.length + 1,
+          maximumEntries: maxPortableZipEntries,
+          maximumCentralDirectoryBytes:
+            maxPortableCentralDirectoryBytes
+        }
       )
-      .replaceAll('\\', '/')
-    if (
-      !name ||
-      name.startsWith('/') ||
-      /^[a-z]:\//iu.test(name) ||
-      name.includes('\0') ||
-      name.split('/').some((part) => part === '..')
-    ) {
-      throw new Error(`Portable ZIP 包含不安全路径：${name}`)
+    } catch (error) {
+      throw new Error('Portable ZIP 中央目录无效', {
+        cause: error
+      })
     }
-    names.push(name)
-    offset += entryLength
+    return parsed.entries.map((entry) => {
+      const name = entry.name.replaceAll('\\', '/')
+      if (
+        !name ||
+        name.startsWith('/') ||
+        /^[a-z]:\//iu.test(name) ||
+        name.includes('\0') ||
+        name.split('/').some((part) => part === '..')
+      ) {
+        throw new Error(`Portable ZIP 包含不安全路径：${name}`)
+      }
+      return name
+    })
+  } finally {
+    closeSync(handle)
   }
-  if (offset !== centralDirectory.length) {
-    throw new Error('Portable ZIP 中央目录数量不一致')
-  }
-  return names
 }
 
 function verifyPortableZip(filePath) {
@@ -1440,6 +1429,12 @@ function verifyArtifactSignature(filePath, format, arch) {
   ) {
     throw new Error('deb 产物不是有效的 ar 归档')
   }
+  if (
+    format === 'rpm' &&
+    readChunk(filePath, 4).toString('hex') !== 'edabeedb'
+  ) {
+    throw new Error('rpm 产物缺少 RPM lead magic')
+  }
 }
 
 async function writeManifest(directory, options) {
@@ -1568,11 +1563,12 @@ function printHelp() {
   --format <列表>  覆盖默认格式，逗号分隔
   --skip-build     复用已有 out 生产构建
   --dry-run        仅显示目标与 electron-builder 参数
+  --unsigned       仅用于 macOS，明确禁用代码签名与公证
 
 默认格式：
   windows: nsis, portable (ZIP)
   macos:   dmg, zip
-  linux:   AppImage, deb`)
+  linux:   AppImage, deb, rpm`)
 }
 
 async function main(argv = process.argv.slice(2)) {
@@ -1606,6 +1602,11 @@ async function main(argv = process.argv.slice(2)) {
       `${options.platform} 包必须在对应系统构建，当前系统为 ${hostPlatform ?? process.platform}`
     )
   }
+  if (options.unsigned) {
+    console.warn(
+      '警告：正在生成未签名、未公证的 macOS 包，Gatekeeper 可能阻止用户首次打开。'
+    )
+  }
 
   rmSync(stagingDirectory, { recursive: true, force: true })
   let cleanupTargetDependencies = () => undefined
@@ -1622,11 +1623,7 @@ async function main(argv = process.argv.slice(2)) {
     await run(
       process.execPath,
       builderArguments,
-      {
-        ...process.env,
-        CSC_IDENTITY_AUTO_DISCOVERY:
-          process.env.CSC_IDENTITY_AUTO_DISCOVERY ?? 'false'
-      }
+      electronBuilderEnvironment(options)
     )
     const unpackedDirectory = verifyUnpackedOutput(
       stagingDirectory,
@@ -1665,6 +1662,7 @@ module.exports = {
   buildElectronBuilderArguments,
   createPortableZip,
   detectBinaryArchitecture,
+  electronBuilderEnvironment,
   normalizePlatform,
   parseArguments,
   parsePackedPackageMetadata,
@@ -1673,6 +1671,7 @@ module.exports = {
   replaceOutput,
   stageTargetRuntimeDependencies,
   targetRuntimePackageNames,
+  targetHarnessPaths,
   verifyHarnessPackage,
   verifyArchiveIntegrity,
   verifyUnpackedOutput,

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

@@ -4,15 +4,17 @@ const {
   writeFileSync
 } = require('node:fs')
 const { dirname, resolve } = require('node:path')
+const {
+  expectedFormatForFile,
+  targetDefinitions
+} = require('./aggregate-release.cjs')
 
-const supportedTargets = new Map([
-  ['windows-x64', ['nsis', 'portable']],
-  ['windows-arm64', ['nsis', 'portable']],
-  ['macos-x64', ['dmg', 'zip']],
-  ['macos-arm64', ['dmg', 'zip']],
-  ['linux-x64', ['AppImage', 'deb']],
-  ['linux-arm64', ['AppImage', 'deb']]
-])
+const supportedTargets = new Map(
+  targetDefinitions.map((target) => [
+    `${target.platform}-${target.arch}`,
+    target
+  ])
+)
 
 function parseArguments(argv) {
   const options = {}
@@ -81,32 +83,6 @@ function assertFile(file, targetKey) {
   }
 }
 
-function formatForFile(fileName, platform) {
-  if (platform === 'windows') {
-    if (/-setup\.exe$/u.test(fileName)) {
-      return 'nsis'
-    }
-    if (/-portable\.zip$/u.test(fileName)) {
-      return 'portable'
-    }
-  } else if (platform === 'macos') {
-    if (fileName.endsWith('.dmg')) {
-      return 'dmg'
-    }
-    if (fileName.endsWith('.zip')) {
-      return 'zip'
-    }
-  } else if (platform === 'linux') {
-    if (fileName.endsWith('.AppImage')) {
-      return 'AppImage'
-    }
-    if (fileName.endsWith('.deb')) {
-      return 'deb'
-    }
-  }
-  return undefined
-}
-
 function createSiteRelease(manifest, baseUrlValue) {
   if (
     !manifest ||
@@ -123,7 +99,8 @@ function createSiteRelease(manifest, baseUrlValue) {
   const targets = {}
   for (const target of manifest.targets) {
     const key = `${target?.platform}-${target?.arch}`
-    const expectedFormats = supportedTargets.get(key)
+    const expectedTarget = supportedTargets.get(key)
+    const expectedFormats = expectedTarget?.formats
     if (
       !expectedFormats ||
       seenTargets.has(key) ||
@@ -140,7 +117,10 @@ function createSiteRelease(manifest, baseUrlValue) {
     const files = {}
     for (const file of target.files) {
       assertFile(file, key)
-      const format = formatForFile(file.name, target.platform)
+      const format = expectedFormatForFile(
+        file.name,
+        expectedTarget
+      )
       if (!format || !expectedFormats.includes(format) || files[format]) {
         throw new Error(`发布文件格式无效：${file.name}`)
       }

build/deepseek-harness-utility-smoke.cjs

@@ -17,7 +17,7 @@ const {
 const { app, utilityProcess } = require('electron/main')
 
 const protocol = 'goodbuddy.deepseek-harness.control'
-const controlVersion = 2
+const controlVersion = 3
 const byteProtocol = 'goodbuddy.deepseek-harness.byte-stream'
 const byteProtocolVersion = 1
 const configuredHostPath =
@@ -183,7 +183,8 @@ async function run() {
       provider: 'goodbuddy',
       model: 'qwen-plus',
       supportsImageInput: false,
-      harnessVersion: '0.1.0-rc.6',
+      requestHeaders: {},
+      harnessVersion: '0.1.0-rc.8',
       credentialRefs: ['GOODBUDDY_HARNESS_MODEL_API_KEY'],
       skillPackages: [],
       extensionPackages: [],

build/electron-builder.release.cjs

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

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/release-notes.cjs

@@ -32,8 +32,8 @@ function validateItems(value, label) {
       fail(`${label} contains a non-string item`)
     }
     const normalized = item.trim()
-    if (!normalized || normalized.length > 500) {
-      fail(`${label} contains an empty or oversized item`)
+    if (!normalized) {
+      fail(`${label} contains an empty item`)
     }
     return normalized
   })

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

@@ -88,7 +88,7 @@ async function main() {
     `${JSON.stringify(
       {
         name: '@deepseek-ai/dsh-llm',
-        version: '0.1.0-rc.6',
+        version: '0.1.0-rc.8',
         private: true,
         type: 'module'
       },

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

@@ -147,7 +147,7 @@ async function main() {
     )
 
     const packageArguments = [
-      resolve('node_modules/electron-builder/cli.js'),
+      resolve('build/run-electron-builder.cjs'),
       '--projectDir',
       project,
       '--win',

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/verify-site-release.cjs

@@ -1,5 +1,13 @@
 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]) {
@@ -12,7 +20,7 @@ async function verifySiteRelease(manifest, request = fetch) {
   const files = Object.values(manifest?.targets ?? {}).flatMap(
     (target) => Object.values(target?.files ?? {})
   )
-  if (files.length !== 12) {
+  if (files.length !== expectedInstallerCount) {
     throw new Error(`官网发布文件数量错误：${files.length}`)
   }
   const urls = new Set()

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

@@ -5,39 +5,49 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.1 |
-| 日期 | 2026-08-13 |
+| 版本 | 0.3 |
+| 日期 | 2026-08-19 |
 | 适用产品 | GoodBuddy 桌面端 |
-| 文档角色 | 自动任务、目标、并行实验、会话监督、分区记忆与持续学习的总纲 |
+| 文档角色 | Task/Job、调度、目标、并行实验、会话监督、分区记忆与持续学习的总纲 |
+| 领域模型 | [Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md) |
 
 ## 1. 背景
 
 GoodBuddy 当前已经具备若干长期助手能力，但它们仍是彼此分离的功能：
 
-1. 定时任务支持单次、每日和每周触发，创建 Ask 任务并保存任务和成果。
-2. 智能心跳支持全局或项目范围的每日、每周回顾，读取有界会话、任务和已确认记忆，
+1. 当前 Schedule 已支持单次、每日和每周触发，并在创建时绑定稳定产品级 Task 与真实
+   Conversation；重复触发复用同一身份，文本结果写回 Conversation，独立文件和图片保存为
+   Artifact。到期执行与用户在回复期间继续发送的普通消息共用 Conversation 级持久队列，
+   因而不会与当前回复并发写入同一时间线。IANA 时区、Cron、事件触发、租约、重试和完整
+   Job/Run 抽象仍待实现。
+2. 当前智能心跳支持全局或项目范围的每日、每周回顾，读取有界会话、任务和已确认记忆，
    生成摘要、记忆建议和后续任务。
-3. 专家子任务支持有限并发和只读综合，但没有实验变量、重复运行、统一指标和结果晋升。
+3. 专家执行的 Job 支持有限并发和只读综合，但没有实验变量、重复运行、统一指标和结果晋升。
 4. 记忆已有全局、项目、会话三种作用域，以及偏好、事实、摘要、流程四种类型，
    但检索、来源、时态、冲突和运行级隔离仍不完整。
 5. 魔法笔记已经提供“内容旁持续出现 AI 评论”的交互，可作为会话监督的体验参考，
    但它只分析笔记或待办，不观察会话和任务运行。
 
-如果继续把更多能力加入“智能心跳”，心跳将同时承担调度、总结、执行、监督、学习和
-记忆管理，最终无法解释一次后台行为为什么发生、读取了什么、是否越权、产生了什么影响。
+智能心跳长期方向是面向未来的分区记忆，但该模型尚未设计。近期只改善现有心跳的权威入口
+与 Global / 多 Project 范围，并保留 Task Center 作为 Task 索引。若继续把 Task、调度、
+监督、学习和执行加入“智能心跳”，将无法解释一次后台行为为什么发生、读取了什么、是否
+越权、产生了什么影响。
 
 本设计将这些能力统一到一个平台模型中，同时保留不同产品的清晰边界。
 
 ## 2. 核心产品判断
 
-### 2.1 不把心跳升级成万能后台 Agent
+### 2.1 智能心跳保持独立，分区记忆协同另行设计
 
-智能心跳应继续承担周期性观察和回顾，不直接成为所有自动化的宿主。
+当前智能心跳继续承担周期回顾、报告和建议，并支持 Global 或指定 Project 范围。它不是
+Task、通用调度器或后台 Agent，也不进入统一 `AutomationPlan.kind`。按分区回顾、候选生成
+以及时间/内部事件唤起需要独立设计，不能从当前心跳行为直接推导，也不创建平行记忆类型。
 
-- 定时任务解决“何时执行一个已知任务”。
-- 目标任务解决“围绕结果持续规划和推进”。
+- Scheduled Task 解决“何时在一个 Task 中执行新的 Job”。
+- Goal Task 解决“围绕结果在同一 Task 中持续规划和推进”。
 - 并行实验解决“隔离多个候选并用相同标准比较”。
 - 会话监督解决“独立观察并在必要时评论、告警或暂停”。
+- 智能心跳当前解决“在什么范围周期回顾并提出报告和建议”。
 - 记忆系统解决“哪些经验可以在什么范围内被未来运行读取”。
 - 持续学习解决“候选经验如何经过评估后改变未来行为”。
 
@@ -85,8 +95,9 @@ SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现
 
 ### 3.1 用户目标
 
-- 用统一入口创建定时、事件、目标和实验型自动任务。
-- 清楚知道自动任务的触发原因、当前目标、运行状态、预算和停止条件。
+- 在现有 Task Center 中找到 Scheduled、Event 和 Goal Task，并直接打开关联 Conversation
+  和对应 Task。
+- 清楚知道 Task 的触发原因、当前目标、聚合执行状态、预算和停止条件。
 - 在一个工作台中观察多个候选运行，并追溯结论到原始证据。
 - 为重要会话启用独立监督，及时发现偏题、遗漏、矛盾、证据不足和风险。
 - 知道每条记忆属于哪个范围、从哪里产生、何时有效以及被哪些运行使用。
@@ -95,6 +106,8 @@ SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现
 ### 3.2 产品目标
 
 - 复用现有 Project、Conversation、Task、Run、Artifact、Approval 和 Notification 能力。
+- 保持每个 Task 只关联一条 Conversation，同时允许一条 Conversation 承载多个 Task，不为
+  同一项工作建立第二份内容载体。
 - 为所有后台工作提供统一的幂等、租约、恢复、取消、预算和审计语义。
 - 保持 Ask 只读，Execute 继续经过现有能力和审批控制。
 - 保持本地优先，应用退出后不虚假承诺后台持续执行。
@@ -117,20 +130,28 @@ SQLite、FTS 和可选本地向量已经足够支撑第一阶段。只有出现
 
 ## 5. 统一领域模型
 
+以下模型是 Scheduled Task、Goal Task 和实验共享的技术基础，不要求新增独立
+Automation Center。`AutomationPlan` 是 Task 的计划配置，`Job` 是 Task 内执行单位，
+`Run` 是执行尝试。用户主要通过 Task Center、左侧会话 Task 列表和关联 Conversation
+理解工作；当前 UI 不展示 Job/Run 层级。智能心跳
+不属于此模型。
+
 ### 5.1 核心实体
 
 ```text
-AutomationPlan
-  ├─ TriggerPolicy
-  ├─ ObjectiveSet
-  ├─ ExecutionProtocol
-  ├─ BudgetPolicy
-  ├─ ApprovalPolicy
-  ├─ SupervisorPolicy
-  └─ MemoryBinding
-       │
-       └─ AutomationRun
-            ├─ Task / Child Task
+Conversation
+  └─ Task 0..N
+       ├─ AutomationPlan（可选）
+       │   ├─ TriggerPolicy
+       │   ├─ ObjectiveSet
+       │   ├─ ExecutionProtocol
+       │   ├─ BudgetPolicy
+       │   ├─ ApprovalPolicy
+       │   ├─ SupervisorPolicy
+       │   └─ MemoryBinding
+       └─ Job
+            ├─ Run
+            ├─ Subjob
             ├─ Observation
             ├─ SupervisorDecision
             ├─ Artifact
@@ -140,15 +161,17 @@ AutomationPlan
 
 | 实体 | 职责 |
 | --- | --- |
-| `AutomationPlan` | 用户可编辑的长期定义，描述做什么、为何做、何时做和允许做什么 |
+| `Task` | 用户可见工作单位，只关联一条 Conversation；Conversation 可以承载多个 Task |
+| `Job` | Task 内部一次步骤、触发、并行分支或委派执行 |
+| `Run` | Task/Job 的一次执行尝试和审计记录 |
+| `AutomationPlan` | Task 的可编辑计划配置，描述做什么、为何做、何时做和允许做什么 |
 | `TriggerPolicy` | 手动、时间、事件或条件触发，以及错过执行策略 |
 | `ObjectiveSet` | 成功标准、优化指标、约束和停止条件 |
 | `ExecutionProtocol` | 本次运行冻结的提示、步骤模板、变量、Runtime、工具和数据范围 |
-| `BudgetPolicy` | 最大耗时、模型调用、Token、工具次数、子任务数、成果大小和并发 |
+| `BudgetPolicy` | 最大耗时、模型调用、Token、工具次数、Job/Subjob 数、成果大小和并发 |
 | `ApprovalPolicy` | 哪些动作可自动执行、哪些等待批准、哪些禁止 |
 | `SupervisorPolicy` | 观察维度、触发频率、干预级别和确定性门禁 |
 | `MemoryBinding` | 运行可读取和可写入哪些记忆分区 |
-| `AutomationRun` | 一次触发产生的不可变运行快照和聚合状态 |
 | `Observation` | 对消息、步骤、工具、指标或系统状态的结构化观察 |
 | `SupervisorDecision` | `continue`、`comment`、`warn`、`request_review`、`pause` 或 `stop` |
 | `Metric` | 可复现的运行指标及其计算来源 |
@@ -161,12 +184,11 @@ AutomationPlan
 | 类型 | 说明 |
 | --- | --- |
 | `scheduled_task` | 到点运行一个固定任务 |
-| `heartbeat_review` | 周期性观察会话、任务和记忆，输出回顾和建议 |
 | `goal_loop` | 围绕目标重复执行“观察、计划、行动、评估” |
 | `experiment` | 生成隔离候选 Run，按统一协议评估和比较 |
 
-会话监督不是独立执行任务。它是可附着到 Conversation、Task、AutomationRun 或
-Experiment 的 `SupervisorPolicy` 和监督会话。
+会话监督不是独立 Task。用户选择 Conversation、Task 或 Experiment 作为监督对象；
+`SupervisorPolicy` 可以在内部观察所属 Job/Run 事件，但当前 UI 不把它们作为独立目标。
 
 ### 5.3 运行快照
 
@@ -183,7 +205,8 @@ Experiment 的 `SupervisorPolicy` 和监督会话。
 - 预算和并发限制。
 - 审批策略。
 
-运行开始后的设置变化只影响下一次 Run。用户可以查看当前 Run 与最新 Plan 的差异。
+运行开始后的设置变化只影响下一次 Run。用户可以在 Task 执行记录中查看当次快照与最新
+Plan 的差异，但 Run 不作为独立导航对象。
 
 ## 6. 统一状态模型
 
@@ -235,34 +258,56 @@ inactive → observing → attention_required → paused → resolved
 
 ```text
 Trigger
-  → AutomationCoordinator 声明 Run
-  → RunQueue 按优先级和预算排队
-  → AutomationExecutor 创建 Task
+  → AutomationCoordinator 在所属 Task 内声明 Job
+  → ExecutionQueue 按优先级和预算排队
+  → AutomationExecutor 为 Job 创建或恢复 Run
   → Runtime 执行
   → Supervisor 观察
   → Evaluator 计算指标
   → 结果、证据和候选记忆入库
-  → 用户审查或后续 Run
+  → 用户审查或后续执行
 ```
 
-`AutomationCoordinator` 只负责触发、声明和恢复，不直接调用模型。执行仍通过任务和 Runtime
-边界完成。
+`AutomationCoordinator` 只负责触发、声明和恢复，不直接调用模型。执行仍通过 Job 和
+Runtime 边界完成，用户可见结果通过所属 Task 汇入关联 Conversation。
 
 ### 7.2 优先级
 
 默认优先级从高到低：
 
 1. 用户正在等待的前台对话。
-2. 用户手动启动的 Run。
-3. 等待批准后恢复的 Run。
-4. 到期定时任务。
-5. 目标循环和实验 Run。
+2. 用户手动启动的 Task 执行。
+3. 等待批准后恢复的 Task 执行。
+4. 到期 Scheduled Task 的执行。
+5. 目标循环和实验执行。
 6. 心跳回顾、记忆巩固和维护。
 
 后台任务必须可被背压延后。延后记录为 `deferred`，不得丢失，也不得在系统恢复空闲时一次性
 释放全部积压。
 
-### 7.3 幂等和租约
+### 7.3 Conversation 输入仲裁
+
+当前实现以 Main 和 SQLite 中的 `conversation_queue_items` 作为每条 Conversation 的权威
+输入队列，而不是在 Renderer 分别维护聊天草稿队列和 Scheduled Task 队列：
+
+- 普通消息在发送时冻结 Runtime、工作模式、专家/团队、知识范围和附件上下文，再以
+  `source=user` 入队；附件内容使用有界序列化保存，应用重启后仍可恢复。
+- 到期或手动启动的 Scheduled Task 先建立 `schedule_run`，再以 `source=schedule` 进入同一
+  队列。Scheduler 不再绕过队列直接调用 Runtime。
+- Main 对每条 Conversation 只保留一个活动请求或 Renderer 派发保留位。默认按 FIFO 认领；
+  全局 Scheduled Task 执行仍受最多 4 项并发限制。
+- 用户消息由 Main 派发给 Renderer，由 Renderer 建立用户消息和流式助手消息后调用
+  `agent.run`；Scheduled Task 由 Main 直接执行。两条路径共享同一 Conversation 活动锁。
+- 当前执行到达终态后再认领下一项。删除只移除尚未执行的项；“立即中断并插入”取消当前
+  请求并把所选项设为下一项，不重排其他项。
+- 每条 Conversation 最多保留 20 个用户可提交的待执行项。启动时将未完成的派发恢复为
+  `pending`，但应用退出期间不会实际执行任务。
+
+Renderer 只通过显式 IPC 列出、加入、删除、提升、释放和接收用户队列项；Main 在接受
+`agent.run` 时校验队列项仍处于 `dispatching` 且属于同一 Conversation，防止 Renderer
+绕过顺序仲裁。
+
+### 7.4 幂等和租约
 
 - 每次计划触发使用 `planId + scheduledFor + planVersion` 形成幂等键。
 - 手动触发使用调用方提供的单次幂等键。
@@ -372,38 +417,35 @@ Trigger
 
 ## 12. 信息架构
 
-建议将现有“智能心跳”逐步扩展为“自动化中心”，但保留心跳作为一种计划：
+当前阶段保留任务中心并适度完善，不新增独立自动化中心。智能心跳使用自己的菜单入口，
+并已在现有模型上实现 Global / 多 Project 范围与唯一配置入口：
 
 ```text
-自动化中心
-├─ 概览
-│  ├─ 正在运行
-│  ├─ 等待审批
-│  ├─ 需要关注
-│  └─ 最近结果
-├─ 计划
-│  ├─ 定时任务
-│  ├─ 智能心跳
-│  ├─ 目标任务
-│  └─ 实验
-├─ 运行
-│  ├─ 时间线
-│  ├─ 任务与步骤
-│  ├─ 监督记录
-│  ├─ 指标与证据
-│  └─ 成果
-├─ 建议
-│  ├─ 记忆候选
-│  ├─ 后续任务
-│  └─ 学习候选
-└─ 设置
-   ├─ 全局预算
-   ├─ 后台优先级
-   ├─ 通知
-   └─ 数据保留
+任务中心
+├─ 需要关注
+├─ 进行中
+├─ 已暂停
+└─ 已结束
+   └─ 打开任务自身
+
+任务自身
+├─ 消息时间线
+├─ Run、步骤与审批活动
+├─ 监督、指标与证据
+└─ 独立成果
+
+智能心跳
+├─ 运行概览
+├─ 待处理建议
+├─ 报告与记录
+└─ 心跳计划
+   └─ Global / 指定 Project
 ```
 
-会话页面增加可折叠“监督”右栏，与任务、上下文和成果并列，或在已有右侧工作栏中新增页签。
+监督统一进入应用级助手工作栏中固定且始终可访问的“监督”栏目，不再保留“独立可折叠右栏”
+和“动态新增页签”两种实现。栏目默认跟随当前上下文，用户可以固定到其他 Conversation、
+Task 或实验对象；详细范围与交互契约见
+[通用助手工作栏与执行空间 PRD](../features/assistant-workbar/prd.md)。
 
 ## 13. 安全与隐私
 
@@ -421,7 +463,7 @@ Trigger
 
 ## 14. 可观测性
 
-每个 Run 至少展示：
+每次 Task 执行的内部 Job/Run 记录至少保存：
 
 - 触发来源和计划版本。
 - 计划目标和当前 `goalStatus`。
@@ -429,13 +471,14 @@ Trigger
 - 实际读取的知识库与记忆分区。
 - 实际调用的模型、Token、工具、耗时和成果大小。
 - 当前预算和剩余预算。
-- 任务、步骤和子任务状态。
+- Task、Job 和 Subjob 状态。
 - Supervisor 评论、证据、严重度和处理结果。
 - 评估器版本、指标和证据。
 - 产生的候选记忆或学习产物。
 - 重试、延后、中断和恢复原因。
 
-不得只显示一个模糊的“自动化成功率”而隐藏失败 Run、跳过 Run 或无结论 Run。
+UI 在 Task 下呈现上述信息的有界摘要和活动，不提供 Job/Run 树或独立导航。不得只显示一个
+模糊的“自动化成功率”而隐藏失败、跳过或无结论的 Task 执行。
 
 ## 15. 建议的数据模型增量
 
@@ -462,15 +505,20 @@ experiment_runs
 ```
 
 现有 `schedules`、`schedule_runs`、`heartbeat_configs`、`heartbeat_runs`、
-`heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。迁移顺序应先增加统一只读视图和
-关联字段，再逐步让新计划使用统一模型。
+`heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。Schedule 可渐进建立稳定 Task 与
+Conversation 关联，旧 child-task 字段可兼容映射到 Job/Subjob；心跳数据保持独立，不得
+静默转成 `AutomationPlan` 或顶层 Task。分区记忆协同和唤起条件完成设计前，不新增迁移目标。
 
 ## 16. 分阶段实施
 
 ### 阶段 0：统一术语和可观测性
 
-- 固定 Plan、Run、Goal、Protocol、Supervisor、Observation、Memory Candidate 等概念。
-- 为现有定时任务、心跳和专家子任务建立统一活动视图。
+- 固定 Task、Conversation、Job、Subjob、Run、Plan、Goal、Protocol、Supervisor、
+  Observation、Memory Candidate 等概念。
+- 明确 Task N:1 Conversation 关系、左侧行首展开按钮与 Task 子项图标，以及 Task Center
+  索引边界，不复制内容。
+- 为现有 Scheduled Task 和专家执行建立按 Task 聚合的活动视图。
+- 明确当前心跳保持独立，分区记忆协同与唤起条件尚待设计。
 - 补充触发来源、运行版本、预算和读写范围展示。
 
 ### 阶段 1：调度与运行基础
@@ -483,6 +531,7 @@ experiment_runs
 ### 阶段 2：会话监督与分区记忆
 
 - 上线评论型会话监督。
+- 智能心跳配置支持 Global 或指定一个、多个 Project。
 - 增加 Automation 和 Run 记忆分区。
 - 建立来源、证据、时态、冲突和晋升流程。
 
@@ -506,18 +555,27 @@ experiment_runs
 
 ## 17. 相关文档
 
-- [自动任务、目标与调度 PRD](./automation-goals-and-scheduling-prd.md)
-- [并行实验工作台 PRD](./parallel-experiments-prd.md)
-- [会话监督 PRD](./conversation-supervision-prd.md)
-- [分区记忆 PRD](./partitioned-memory-prd.md)
-- [持续学习与评估门 PRD](./continuous-learning-prd.md)
-- [GoodBuddy 长期助手功能规划](../long-term-assistant-roadmap.md)
+- [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. 总体验收标准
 
-- [ ] 心跳、定时、目标和实验使用统一的 Plan 与 Run 术语。
-- [ ] 每个自动 Run 都能解释触发原因、目标、范围、预算、状态和结果。
+- [ ] 智能心跳保持独立，不作为 Task 类型；分区记忆协同与唤起条件尚未设计。
+- [ ] Task Center 只索引 Task；每个 Task 只关联一条 Conversation，一条 Conversation 可以
+  关联多个 Task。
+- [ ] 当前 UI 只展示到 Task，不提供 Job/Subjob/Run 树或独立导航。
+- [ ] Scheduled Task 的重复触发和并行 Job 不创建新的顶层 Task。
+- [ ] 每次自动执行的内部 Run 都记录触发原因、目标、范围、预算、状态和结果，并在所属
+  Task 下提供有界可观测信息。
 - [ ] Ask 自动化无法调用写工具或产生外部副作用。
 - [ ] Execute 自动化不能绕过现有审批、主机执行策略和能力控制。
 - [ ] 会话监督默认只评论，不能替用户发言或批准工具。

docs/architecture/share-network-architecture.md

@@ -0,0 +1,457 @@
+# GoodBuddy 设备共享与 ShareServer 联邦网络总体设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用范围 | 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 服务，提供组织、设备、能力、权限、更新、
+   联邦、中继和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。
+
+### 2.2 能力优先，来源可见
+
+用户日常选择的是能力，不是网络连接。设备、ShareServer 和组织作为能力来源与诊断入口。
+任何调用都必须持续显示提供者、执行位置和数据去向，不能为了统一体验隐藏跨设备或跨组织
+边界。
+
+### 2.3 局域网是默认连接方式，网关是显式附加连接
+
+- 桌面端没有网关配置时，局域网发现、配对、调用和本机共享仍可完整工作。
+- 添加、删除或断开 ShareServer 不改变局域网配对关系。
+- ShareServer 不接管本机局域网发现，也不能静默把局域网设备注册到组织。
+- 同一桌面端可以连接多个 ShareServer；能力来源和授权按连接分别计算。
+
+### 2.4 发现、被发现和开放能力是三个独立动作
+
+- **发现设备**：浏览同一局域网中主动广播的 GoodBuddy 服务。
+- **允许被发现**：广播本设备存在及配对入口。
+- **开放能力**：向指定设备、用户组或组织发布可查看、调用或拉取的能力。
+
+开启其中一项不能推导另外两项已开启。新安装默认不开放能力。
+
+### 2.5 ShareServer 优先作为控制面
+
+ShareServer 负责身份、目录、策略、任务路由、更新和审计。数据面优先在两个已认证端点之间
+直接建立；网络条件不允许时，可按组织策略使用 ShareServer 中继。是否允许中继、正文是否
+端到端加密、是否允许跨组织，由本次任务冻结的策略共同决定。
+
+## 3. 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| `Device` | 安装 GoodBuddy 并拥有稳定设备身份的终端 |
+| `Peer` | 与当前设备存在局域网配对关系的另一台设备 |
+| `ShareServer` | 提供组织控制面和可选数据中继的独立服务 |
+| `Organization` | ShareServer 中隔离成员、设备、能力与策略的管理范围 |
+| `GatewayConnection` | 某台设备与一个 ShareServer 上特定组织身份的连接 |
+| `Capability` | 可被查看、调用或分发的稳定能力标识 |
+| `CapabilityProvider` | 实际持有并执行某项能力的设备或服务节点 |
+| `Publication` | 能力提供者向某一范围发布的可见性和使用声明 |
+| `Grant` | 主体对能力执行某类动作的明确授权 |
+| `Task` | 一次远程能力调用及其输入、执行、输出和终态 |
+| `Package` | 可下载到本机安装的签名能力工件 |
+| `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 |
+
+“网关”是 ShareServer 的网络角色；产品名称为 `ShareServer`，独立仓库为
+`goodbuddy-shareserver`。
+
+## 4. 系统拓扑
+
+```text
+局域网：
+GoodBuddy Desktop A <-- mDNS 发现 + 配对后 TLS 直连 --> GoodBuddy Desktop B
+
+单组织：
+GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B
+
+跨组织：
+Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Device B
+```
+
+局域网和网关连接共享能力、授权和任务的领域语义，但不共享发现方式：
+
+| 维度 | 局域网 | ShareServer |
+| --- | --- | --- |
+| 发现来源 | mDNS/DNS-SD 主动广播 | 已配置 URL 或邀请链接 |
+| 初始身份 | 双端验证码确认设备指纹 | 用户登录、设备注册和组织成员身份 |
+| 能力目录 | 已配对设备直接返回 | 服务端按组织策略过滤 |
+| 连接方向 | 配对后直连 | 设备主动建立出站连接 |
+| 管理范围 | 单个设备间授权 | 用户组、组织和联邦授权 |
+| 审计权威 | 两端各自本地记录 | 组织网关记录元数据，两端保留本地记录 |
+
+## 5. 组件边界
+
+### 5.1 GoodBuddy Desktop
+
+- 浏览和广播局域网服务。
+- 创建、确认和撤销点对点配对。
+- 连接 ShareServer，保存脱敏连接信息和本机受保护凭据。
+- 发布用户明确选择的本机能力。
+- 展示经当前身份过滤的能力目录。
+- 在调用前冻结提供者、输入范围、授权和路由。
+- 执行本机提供的任务，或消费远端任务结果。
+- 校验并安装用户明确选择的签名能力包。
+- 保存本机活动记录和可撤销授权。
+
+### 5.2 ShareServer
+
+- 认证用户、设备、服务节点和其他 ShareServer。
+- 管理组织、成员、用户组和设备目录。
+- 接收能力发布并生成权限过滤后的目录。
+- 计算组织强制策略，签发短期任务授权。
+- 路由任务、维护在线状态，并在允许时中继数据。
+- 管理签名包、发布通道、更新策略和撤销。
+- 建立双边联邦关系并限制跨组织可见性与调用。
+- 保存有界审计元数据、用量和管理操作。
+
+### 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 使用双方共同支持的最低能力集合。
+- 未识别字段在声明允许扩展的位置忽略，安全与授权枚举中的未知值一律拒绝。
+- 联邦只交换双方共同支持的能力和策略表达式，不降低任一方策略。
+
+## 12. 数据与审计
+
+### 12.1 最小审计事件
+
+- 操作者、调用设备和组织。
+- 动作、能力、版本和提供者。
+- 路由与是否跨组织。
+- 输入数据类别、分类、文件数和字节数。
+- 授权结果、策略 ID 和批准者。
+- 任务状态、耗时、输出大小和资源用量。
+- 包下载、安装、更新、撤销和发布变更。
+
+默认不保存提示正文、文件内容、模型输出、密钥、Cookie、认证头或完整私有路径。需要内容
+审计的组织必须单独定义保留期限和访问角色，并在调用前向用户显示。
+
+### 12.2 数据权威
+
+- 桌面端是本地配对、本机共享偏好和本地活动记录的权威。
+- ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。
+- 能力提供者是运行中任务及结果是否产生的权威。
+- 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。
+
+## 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 后停止签发新令牌。
+
+## 14. 建议领域实体
+
+```text
+DeviceIdentity
+PeerPairing
+GatewayConnection
+Organization
+Membership
+Group
+RegisteredDevice
+Capability
+CapabilityVersion
+Publication
+Grant
+Policy
+Approval
+Task
+TaskAttempt
+ArtifactTransfer
+Package
+PackageRelease
+FederationTrust
+AuditEvent
+Revocation
+```
+
+共享协议只定义跨端 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 启动，也不影响桌面端离线使用。
+
+## 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)
+- [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,303 @@
+# 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 and ZIP for
+  macOS, and AppImage, DEB, and RPM 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.
+- 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.
+- 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 14 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 22 assets: 14 installers (two formats
+  for each Windows/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 22 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 14 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 14 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/assistant-workbar/README.md

@@ -0,0 +1,14 @@
+# 助手工作栏
+
+助手工作栏统一承载本机与远程执行空间、Task、成果、文件、浏览器和终端等持续工作界面。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [通用助手工作栏与执行空间 PRD](./prd.md) | 工作栏整体产品范围、执行空间和各工作面板归属 |
+| [多终端页签 PRD](./terminal-tabs-prd.md) | 多终端 Tab、目标选择、关闭确认和终端生命周期 |
+| [实现与验证进度](./progress.md) | 工作区改动的验证证据与剩余阻塞 |
+
+当前尚未拆出独立 User Stories、功能逻辑、UI 设计和技术设计文档；相关内容仍保留在
+两份现有 PRD 中，后续实际维护该功能时按职责拆分。

docs/features/assistant-workbar/progress.md

@@ -0,0 +1,29 @@
+# 工作栏实现与验证进度
+
+## 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/terminal-tabs-prd.md

@@ -0,0 +1,585 @@
+# 助手工作栏多终端页签 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台验证中 |
+| 版本 | 1.1 |
+| 日期 | 2026-08-31 |
+| 适用产品 | 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` 实例策略。
+- 创建实例时可用的默认上下文。
+- 当前不可用时的原因和修复入口。
+
+目录中的应用可发现性与实例是否已经打开相互独立。应用不可用时保留入口并说明原因，不以
+隐藏代替状态。
+
+### 3.2 工作栏 Tab 实例
+
+工作栏 Tab 是应用的一次打开实例。每个实例具有独立 ID、标题、应用类型和状态。Tab 行只
+显示已经打开的实例，不把全部能力同时渲染为 Tab。
+
+### 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. 任务中心、工作区、浏览器和成果首期保持单实例；后续只需修改应用注册表策略即可开放
+   多实例，不重写 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. 选择终端时直接解析当前项目执行空间，创建新 Tab 并聚焦终端输入，不再要求用户
+   重复选择本机或远程目标。
+
+选择页是“+”触发的临时界面，不进入实例顺序，不持久化，也不占用一个普通 Tab。
+
+### 7.3 首期应用注册表
+
+| 应用 | 实例策略 | 升级后默认状态 | 再次从“+”选择 |
+| --- | --- | --- | --- |
+| 任务中心 | `single` | 打开 | 聚焦已有 Tab |
+| 工作区 | `single` | 打开 | 聚焦已有 Tab |
+| 浏览器 | `single` | 打开 | 聚焦已有 Tab |
+| 成果 | `single` | 打开 | 聚焦已有 Tab |
+| 终端 | `multiple` | 不打开 | 每次创建新 Tab |
+
+实例策略是应用注册数据，不能分散硬编码在多个点击处理器中。
+
+### 7.4 Tab 操作
+
+- 点击或使用方向键切换实例不会暂停或终止后台实例。
+- 支持左右方向键、Home、End 和 roving `tabindex`。
+- 关闭非活动 Tab 后焦点保持在当前活动 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'
+  instancePolicy: 'single' | 'multiple'
+}
+
+type WorkbarTabInstance = {
+  id: string
+  appId: WorkbarAppDefinition['id']
+  title: string
+  targetRef?: {
+    type: 'project' | 'local'
+    id?: string
+  }
+}
+```
+
+- 持久化工作栏打开状态、Tab 顺序、活动实例、应用 ID、自定义标题、公开目标引用和宽度比例。
+- 不持久化终端正文、未执行输入、凭据、环境变量、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] 连续选择终端会创建多个互相独立的终端 Tab。
+- [ ] 关闭、切换和重排实例后，“+”仍保持可用。
+- [ ] Tab 溢出时单行横向滚动，不隐藏“+”或把 Tab 换成下拉框。
+- [x] 关闭活动 Tab 后激活正确的相邻 Tab 并恢复焦点。
+- [x] 当前 Tab 的背景、边框、顶部指示和字重清晰可辨；关闭按钮仅在悬停、焦点或无悬停
+  设备上出现，且不引发布局位移。
+- [ ] 升级后现有任务中心、工作区、浏览器和成果仍按默认布局打开且行为不回归。
+- [ ] 在所有主要页面都能打开工作栏；切换主要页面不会销毁 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、“+”、选择页和关闭确认使用正确语义并有可见焦点。
+- [ ] 终端输出不逐行进入 live region，关键状态变化可被辅助技术感知。
+- [ ] 浅色、深色、200% 文字缩放和窄窗口下可以完成核心流程。
+- [ ] Windows、macOS、Linux x64 和 Linux arm64 的正式构建实际启动本机 PTY。
+- [ ] 远程链路在共享 Linux x64 真实 Host 上完成创建、输入、resize、断线、重连、关闭和
+  应用退出验证；若 Host 不可达，远程终端不得标记为完成。
+
+## 19. 验证计划
+
+### 19.1 自动验证
+
+- 共享 Zod Schema 和边界值测试。
+- 单/多实例注册策略、Tab 顺序、关闭焦点和“+”选择页组件测试。
+- 本机 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/automation-goals-and-scheduling-prd.md

@@ -1,399 +0,0 @@
-# 自动任务、目标与调度 PRD
-
-## 文档信息
-
-| 项目 | 内容 |
-| --- | --- |
-| 状态 | 设计中 |
-| 版本 | 0.1 |
-| 日期 | 2026-08-13 |
-| 依赖 | [自动化、监督与记忆平台总体设计](./automation-platform-architecture.md) |
-
-## 1. 背景
-
-GoodBuddy 当前的定时任务支持单次、每日和每周触发固定 Ask 提示，并保存任务和成果；
-智能心跳支持每日或每周回顾有界的会话、任务和已确认记忆。两者尚不能表达事件触发、
-目标、成功标准、预算、停止条件和安全恢复。
-
-## 2. 产品边界
-
-| 类型 | 用户意图 | 是否形成循环 |
-| --- | --- | --- |
-| 定时任务 | 在指定时间执行已知操作 | 否 |
-| 事件任务 | 当明确事件发生时执行已知操作 | 否 |
-| 目标任务 | 在预算内持续推进到可验证结果 | 是 |
-
-智能心跳是特殊的定时观察任务。并行实验属于独立产品。
-
-## 3. 已确认的产品决策
-
-1. 自动化定义与每次运行分离，编辑计划不改变已启动 Run。
-2. 第一阶段保留现有定时任务的 Ask 限制，Execute 分阶段开放。
-3. Execute 自动化不能因无人值守而绕过现有审批、主机执行策略和工具控制。
-4. 应用退出后不承诺继续运行，重启后只进行状态恢复和错过执行结算。
-5. 目标任务必须有成功标准，以及预算或人工结束条件。
-6. 模型可以提出计划，确定性状态机负责预算、停止、权限和恢复。
-7. 同一计划默认最多一个活动 Run。
-8. 后台任务可被背压延后，不能挤占用户正在等待的前台请求。
-9. 结果未知的外部副作用步骤不自动重试。
-10. 项目、知识库、记忆、目录和工具范围在保存和运行页持续可见。
-
-## 4. 目标
-
-- 支持单次、每日、每周、每月、工作日和受限 Cron。
-- 支持任务完成、失败、会话完成等内部事件触发。
-- 允许用户用自然语言生成结构化草稿，再检查后启用。
-- 为目标任务建立有界的“观察、计划、行动、评估”循环。
-- 提供幂等、租约、错过执行、取消、重试、恢复、预算和审计。
-- 为后续并行实验和持续学习复用协议、指标和运行基础。
-
-## 5. 非目标
-
-- 第一阶段不提供任意节点、脚本和循环的通用 DAG 编辑器。
-- 不允许模型编写并执行任意 Shell、SQL 或无限频率 Cron。
-- 不支持应用退出后通过未安装的系统服务继续运行。
-- 不把“模型说完成了”作为唯一成功标准。
-- 不允许自动任务静默修改自身权限、触发器或预算。
-- 不在目标循环中无限创建子任务或专家。
-
-## 6. 创建与启用
-
-用户可以先输入自然语言意图：
-
-```text
-每周五下午 5 点总结本项目本周完成和失败的任务，
-列出下周三个优先事项，不要修改文件。
-```
-
-模型只生成草稿：
-
-- 名称、说明和自动化类型。
-- 触发器。
-- 目标、输出和成功标准建议。
-- 工作模式和 Runtime 建议。
-- 数据范围。
-- 预算、停止条件和通知。
-
-草稿不能自动启用。用户必须检查结构化配置。
-
-### 6.1 所有计划必填
-
-- 名称、范围和类型。
-- 触发器。
-- 工作模式和 Runtime。
-- 输入、输出和通知。
-- 预算和数据保留。
-- 知识库、记忆、目录和工具范围。
-
-### 6.2 目标任务额外必填
-
-- 目标描述。
-- 至少一个成功标准。
-- 约束。
-- 最大轮数或截止时间。
-- 每轮评估方式。
-- 无进展处理。
-
-### 6.3 启用前检查
-
-- 时区和下一次运行时间可解析。
-- 项目、目录、Runtime 和模型可用。
-- Ask 没有写入或外部副作用要求。
-- Execute 的工具和审批范围明确。
-- 预算不是无界值。
-- 事件来源存在且已启用。
-- 目标任务存在停止条件。
-
-## 7. 触发器
-
-### 7.1 时间触发
-
-```ts
-type TimeTrigger =
-  | { type: 'once'; at: string; timezone: string }
-  | { type: 'daily'; localTime: string; timezone: string }
-  | {
-      type: 'weekly'
-      weekdays: number[]
-      localTime: string
-      timezone: string
-    }
-  | {
-      type: 'monthly'
-      day: number | 'last'
-      localTime: string
-      timezone: string
-    }
-  | {
-      type: 'cron'
-      expression: string
-      timezone: string
-    }
-```
-
-受限 Cron 只允许五字段，不支持秒、年份、宏、`L`、`W`、`#` 或供应商扩展。
-Main 负责解析并展示未来五次运行时间，默认最小间隔为 15 分钟。
-
-### 7.2 事件触发
-
-第二阶段支持：
-
-- `conversation.completed`
-- `task.completed`
-- `task.failed`
-- `artifact.created`
-- `knowledge.sync.completed`
-- `magic_note.updated`
-
-事件触发必须配置来源范围、确定性过滤、去重窗口、冷却时间和并发上限。
-基础匹配不调用模型。
-
-### 7.3 手动触发
-
-- “立即运行”创建独立 Run，不改变下次计划时间。
-- 多次点击使用调用级幂等键去重。
-- 未保存的变更需先保存为新版本，或明确使用当前已发布版本。
-
-### 7.4 错过执行
-
-| 策略 | 行为 |
-| --- | --- |
-| `skip` | 记录跳过，不补跑 |
-| `run_once` | 无论错过多少次，只补一次 |
-| `catch_up_bounded` | 在数量和时间窗口上限内补跑 |
-
-有界补跑默认最多 3 次、最多回溯 7 天。补跑同样受并发和预算控制。
-
-### 7.5 时区和夏令时
-
-- 保存 IANA 时区，不保存固定 UTC 偏移。
-- 春季不存在的本地时间在当日第一个有效分钟运行。
-- 秋季重复时间只运行一次。
-- 系统时区变化不自动修改计划时区。
-- UI 显示计划时区与本机时区差异。
-
-## 8. 目标任务
-
-### 8.1 目标模型
-
-```ts
-type AutomationObjective = {
-  statement: string
-  successCriteria: SuccessCriterion[]
-  constraints: Constraint[]
-  deadline?: string
-}
-
-type SuccessCriterion =
-  | { type: 'artifact_exists'; kind: string; minimumCount: number }
-  | { type: 'task_state'; taskId: string; expected: 'completed' }
-  | {
-      type: 'metric_threshold'
-      metric: string
-      operator: string
-      value: number
-    }
-  | { type: 'checklist'; items: string[] }
-  | { type: 'human_review' }
-  | {
-      type: 'model_rubric'
-      rubricId: string
-      minimumScore: number
-    }
-```
-
-模型 Rubric 不能是唯一标准，除非任务本质是开放内容评价且 UI 明确标注。
-
-### 8.2 有界循环
-
-```text
-Observe
-  → Plan next action
-  → Check permissions and budget
-  → Act or request approval
-  → Evaluate progress
-  → Complete, pause, revise or continue
-```
-
-每轮持久化观察摘要、下一步、实际任务或工具、成果、指标、预算、进展状态和
-Supervisor 决策。只保存专门生成的结构化理由摘要，不保存隐藏推理。
-
-### 8.3 无进展检测
-
-出现任一情况进入 `attention_required`：
-
-- 连续两轮没有指标改善或新成果。
-- 重复提出相同下一步。
-- 连续失败达到上限。
-- 需要的输入或权限不可用。
-- 剩余预算不足。
-- Supervisor 判定目标或前提需要澄清。
-
-默认暂停并请求用户选择，不自动扩大范围。
-
-### 8.4 计划修订
-
-目标任务可以建议修改步骤、缩小目标、请求输入、增加预算或改变 Runtime。
-修改范围、预算、Runtime、工作模式或权限必须用户确认，并形成新版本或 Run 修订记录。
-
-## 9. 工作模式与审批
-
-### 9.1 Ask
-
-- 默认只读。
-- 只使用明确开放的只读数据工具。
-- 不写文件、不执行命令、不发送消息、不修改远程数据。
-- 输出进入成果和通知。
-
-### 9.2 Execute
-
-按以下顺序开放：
-
-1. 有人值守，沿用逐工具审批。
-2. 预批准低风险工具和参数范围。
-3. 经过专项验证的内置无人值守模板。
-
-即使预批准，也不能扩大目录和能力。高风险或越界动作进入 `waiting_approval`。
-密码输入、支付、授权、删除、公开发布和生产变更不能预批准。
-
-## 10. 预算与背压
-
-```ts
-type AutomationBudget = {
-  maximumDurationMs: number
-  maximumIterations: number
-  maximumModelCalls: number
-  maximumInputTokens?: number
-  maximumOutputTokens?: number
-  maximumToolCalls: number
-  maximumChildTasks: number
-  maximumArtifactBytes: number
-  maximumConcurrentChildren: number
-}
-```
-
-建议默认值：
-
-| 类型 | 最长时间 | 模型调用 | 子任务并发 |
-| --- | --- | --- | --- |
-| 定时 Ask | 5 分钟 | 4 | 1 |
-| 心跳回顾 | 5 分钟 | 2 | 0 |
-| 目标 Ask | 30 分钟 | 12 | 2 |
-| 目标 Execute | 30 分钟 | 12 | 1 |
-
-前台请求优先。后台使用独立并发池，达到上限时排队。高负载时低优先级心跳和维护任务
-记录为 `deferred`，压力解除后有界恢复，不能一次性释放全部积压。
-
-## 11. 重试、恢复与取消
-
-| 失败类型 | 行为 |
-| --- | --- |
-| 瞬时网络或限流 | 指数退避，有界重试 |
-| 模型格式错误 | 最多一次结构化修复 |
-| 配置或权限错误 | 不重试，等待修复 |
-| 无副作用的确定性工具失败 | 按工具策略重试 |
-| 结果未知或已有外部副作用 | 不自动重试 |
-
-应用退出时停止声明新 Run，取消可取消工作，活动 Run 标记为 `interrupted` 并保存安全
-检查点。重启后用户可恢复、复制剩余步骤或放弃；结果未知步骤必须先人工核实。
-
-暂停 Plan 只阻止新 Run，不终止当前 Run。取消 Run 必须传播到子任务和 Runtime，
-但不能把已发生的外部副作用假装撤销。
-
-## 12. 输出与通知
-
-输出可保存为文字或文件成果、创建后续任务建议，或仅通知。后续可支持更新指定魔法笔记。
-
-通知事件：
-
-- Run 完成或失败。
-- 等待审批。
-- Supervisor 要求关注。
-- 目标达成。
-- 预算达到 80%。
-- 连续无进展。
-
-同一事件不同时显示重复页内横幅和全局通知。
-
-## 13. 信息架构
-
-计划列表显示名称、类型、范围、启用状态、下次运行、最近 Run、目标状态和需要关注数量。
-
-计划详情页签：
-
-- 概览。
-- 目标与协议。
-- 触发器。
-- 权限与预算。
-- 运行历史。
-
-Run 详情展示总览、时间线、任务、审批、监督、指标、证据、成果以及实际读取的知识和记忆。
-
-## 14. 数据模型建议
-
-```ts
-type AutomationPlan = {
-  id: string
-  projectId?: string
-  kind: 'scheduled_task' | 'heartbeat_review' | 'goal_loop'
-  name: string
-  description: string
-  status: 'draft' | 'active' | 'paused' | 'archived'
-  currentVersion: number
-  nextRunAt?: string
-  createdAt: string
-  updatedAt: string
-}
-
-type AutomationPlanVersion = {
-  planId: string
-  version: number
-  trigger: TriggerPolicy
-  objective?: AutomationObjective
-  protocol: ExecutionProtocol
-  budget: AutomationBudget
-  approvalPolicy: ApprovalPolicy
-  supervisorPolicy?: SupervisorPolicy
-  memoryBinding: MemoryBinding
-}
-```
-
-状态、范围、下次运行、版本和索引字段使用显式列；版本化协议可以使用经过共享 Schema
-验证的 JSON。
-
-## 15. 安全要求
-
-1. 所有输入由共享 Zod Schema 验证。
-2. Main 重新验证项目、目录、Runtime、工具、知识库和记忆分区归属。
-3. Renderer 不可直接声明 Run 完成或批准工具。
-4. 自动化提示、事件、记忆和成果都视为不可信数据。
-5. 事件过滤不执行用户 JavaScript、SQL 或无限复杂表达式。
-6. Cron 有复杂度和最小间隔限制。
-7. 自动化不能读取未绑定知识库、桌面上下文或其他项目记忆。
-8. 日志和通知对私人内容、密钥和工具输出有界脱敏。
-
-## 16. 实施顺序
-
-1. 统一现有 Schedule 和 Heartbeat 的 Run 视图。
-2. 增加幂等、租约、月度、工作日、受限 Cron、错过执行和未来运行预览。
-3. 建立内部持久事件、过滤、冷却和去重，首期只支持 Ask。
-4. 上线目标 Ask、有界循环、无进展检测和人工暂停。
-5. 接入会话监督。
-6. 再开放有人值守和预批准低风险 Execute。
-
-## 17. 验收标准
-
-- [ ] 支持单次、每日、每周、每月、工作日和受限 Cron。
-- [ ] UI 显示计划时区和未来五次运行时间。
-- [ ] 夏令时不会造成计划漂移或双跑。
-- [ ] 同一计划同一时间点只产生一个 Run。
-- [ ] 错过执行按配置跳过、补一次或有界补跑。
-- [ ] 手动运行不改变下次计划时间。
-- [ ] Ask 自动化在 Runtime 边界拒绝写工具和外部副作用。
-- [ ] 目标任务必须有成功标准和停止条件。
-- [ ] 每轮都有观察、行动、评估和预算记录。
-- [ ] 连续无进展会暂停，不无限循环。
-- [ ] 达到预算使用 `budget_exceeded`，不伪装为成功。
-- [ ] 设置变化不影响已启动 Run。
-- [ ] 重启后不自动重放结果未知的副作用步骤。
-- [ ] 后台任务排队时不挤占前台模型请求。

docs/features/computer-control/README.md

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

docs/features/computer-control/progress.md

@@ -6,9 +6,9 @@
 | --- | --- |
 | 文档类型 | 实施进度 |
 | 状态 | 持续更新 |
-| 版本 | 0.1 |
-| 日期 | 2026-08-07 |
-| 适用能力 | 电脑控制与托管浏览器 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-03 |
+| 适用能力 | 内置浏览器与客户端电脑控制 |
 
 ## 范围
 
@@ -17,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
 
@@ -59,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 和会话。
 
 ## 本轮已修复缺陷
 
@@ -89,11 +97,27 @@ Linux x64 和 Linux arm64。
 新增“浏览器”页签；活动对话启动浏览器时会自动打开该页签，并显示创建中、
 加载中、操作中、用户交互中、就绪、失败和已停止状态。用户可点击“交互”打开
 同一会话的子窗口辅助 Agent；交互时主窗口暂时禁用，关闭时先刷新最终画面再将
-浏览器窗口最小化，页面和会话继续保留。用户也可立即停止当前对话的浏览器会话。
-
+浏览器窗口最小化，页面和会话继续保留。用户也可明确关闭当前对话的浏览器会话。
 当前实现按导航、快照、点击、输入、选择、返回和截图操作刷新画面，而不是创建
 第二个预览浏览器，因此显示内容与模型受控页面一致。
 
+### 已实现：浏览器工具栏
+
+浏览器 Tab 顶部已增加“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”工具栏。
+它继续操作 Agent 在当前 Conversation 中使用的同一浏览器会话；用户导航会有意改变 Agent
+下一步看到的页面。前往、返回和刷新通过 `BrowserService` 与 Agent 浏览器操作串行执行，
+不会创建第二套 Renderer 导航路径。
+
+工具栏状态以浏览器提交后的权威 URL、是否加载中、能否返回和会话活动状态为准；地址输入
+在用户编辑期间保留本地草稿，不被状态刷新覆盖；提交未带 HTTP(S) 协议的裸域名时会自动添加
+`http://`。创建中、Agent 操作中和完整交互窗口期间禁用其余工具栏控件，但活动导航仍可用
+“停止加载”中断。停止加载只取消页面加载，不关闭浏览器，也不释放 Runtime 上下文；原“停止
+浏览器”会话生命周期操作已统一标为“关闭浏览器”，并在视觉和文案上与停止加载清楚区分。
+
+活动 Conversation 尚无浏览器会话时，可直接从地址栏输入 URL 并“前往”，通过浏览器组件
+可用性检查和同一 URL 策略创建会话。该手动路径不读取 Agent 浏览器开关。实现复用现有每
+Conversation 串行队列和有界状态，不引入恢复、版本化或第二套会话框架。
+
 ### P0：百度输入时元素引用失效，已修复
 
 截图中的“浏览器元素引用已失效，请重新获取快照”来自过宽的导航监听：广告或
@@ -133,23 +157,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

@@ -5,13 +5,14 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中，远期能力 |
-| 版本 | 0.1 |
-| 日期 | 2026-08-13 |
-| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md)、[并行实验 PRD](./parallel-experiments-prd.md)、[分区记忆 PRD](./partitioned-memory-prd.md) |
+| 版本 | 0.3 |
+| 日期 | 2026-08-19 |
+| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../parallel-experiments/prd.md)、[分区记忆 PRD](../memory/prd.md) |
 
 ## 1. 背景
 
-智能心跳已经可以生成摘要、后续任务和记忆候选，但这还不是完整学习：
+智能心跳可以生成摘要、后续任务和记忆候选，但这还不是完整学习。它与分区记忆的协同尚未
+实施，也不承担持续学习、模式挖掘或自动改进：
 
 - 候选是否改善未来行为没有评估。
 - 一条反思是否会被检索和使用并不确定。
@@ -82,8 +83,8 @@ Observe
 ## 5. 候选来源
 
 - 用户对回答、任务或 Supervisor 意见的显式反馈。
-- 智能心跳提出的重复模式。
-- 自动化 Run 的成功与失败比较。
+- 用户对心跳报告或建议的显式反馈。
+- Task 执行的成功与失败比较。
 - 并行实验结论。
 - 回放评估发现的稳定差异。
 - 用户手动创建。
@@ -301,7 +302,8 @@ Shadow 达到配置的最小观察数且无安全退化后进入 `awaiting_appro
 
 ## 14. 信息架构
 
-建议在自动化中心增加“学习”：
+若远期验证确有集中学习管理需求，应提供独立且可审计的“学习”视图，而不是放入智能心跳、
+任务中心或一个尚未确认的自动化中心：
 
 1. **候选**：来源、作用域、预期收益和风险。
 2. **评估中**：进度、案例和预算。

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

@@ -5,9 +5,10 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.1 |
-| 日期 | 2026-08-13 |
-| 依赖 | [自动化平台总体设计](./automation-platform-architecture.md) |
+| 版本 | 0.2 |
+| 日期 | 2026-08-18 |
+| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
+| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
 | 体验参考 | GoodBuddy 魔法笔记 AI 评论流 |
 
 ## 1. 背景
@@ -27,8 +28,10 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写
 
 ## 2. 产品定义
 
-会话监督是在明确范围和策略下，对 Conversation、Task、AutomationRun 或 ExperimentRun
-的可见事件进行独立观察，产生带证据的评论、告警和人工介入请求。
+会话监督是在明确范围和策略下，对普通 Conversation、Task 或 Experiment 的可见事件
+进行独立观察，产生带证据的评论、告警和人工介入请求。每个 Task 只关联一条 Conversation，
+一条 Conversation 可以承载多个 Task；Job/Run 是内部执行和审计对象，不作为当前 UI
+监督目标。
 
 它不是：
 
@@ -53,7 +56,7 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写
 
 ## 4. 已确认的产品决策
 
-1. 监督默认关闭，由用户对会话、任务、自动化或实验显式启用。
+1. 监督默认关闭，由用户对 Conversation、Task 或实验显式启用。
 2. 监督只读取用户可查看的消息、工具事件、状态、指标、成果摘要和目标。
 3. 不读取、推断或保存模型隐藏推理链。
 4. 每条重要判断必须引用具体消息、工具、步骤、指标或成果。
@@ -72,7 +75,7 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写
 - 及时发现目标偏移、缺少证据、相互矛盾、重复循环和遗漏要求。
 - 点击监督意见查看对应证据，而不是接受无来源判断。
 - 对监督意见进行采纳、忽略、标记误报或追问。
-- 对自动任务设置更严格的监督策略和人工检查点。
+- 对 Scheduled/Goal Task 设置更严格的监督策略和人工检查点。
 
 ### 5.2 产品目标
 
@@ -97,10 +100,8 @@ GoodBuddy 的魔法笔记已经提供一种有价值的交互：用户持续写
 | 对象 | 观察内容 | 典型用途 |
 | --- | --- | --- |
 | 普通会话 | 用户消息、助手回答、引用、工具事件 | 质量和证据评论 |
-| 任务 | 目标、步骤、状态、工具、成果 | 偏离、循环和失败分析 |
-| 自动化 Run | 触发、协议、预算、审批、指标 | 无人值守关注 |
-| 实验 Run | 协议、变量、指标、证据 | 协议一致性 |
-| 实验整体 | 各 Run 结算和比较 | 评估公平性与无结论提示 |
+| Task | 目标、状态、Conversation、成果 | 偏离、循环和失败分析 |
+| Experiment | 协议、变量、各候选执行、指标和证据 | 协议一致性、评估公平性与无结论提示 |
 
 每个监督会话只能绑定一个主对象，并继承其项目范围。
 
@@ -156,7 +157,7 @@ type SupervisorAction =
 - 当前对象的名称、目标和约束。
 - 最近有界消息。
 - 工具名称、状态、参数摘要和输出摘要。
-- 任务和子任务状态。
+- Task、Job 和 Subjob 状态。
 - 成果标题、类型、大小和有界摘要。
 - 引用和知识检索诊断。
 - 预算使用。
@@ -224,7 +225,7 @@ type SupervisorDecision = {
 - Ask 出现写工具请求。
 - 工具或路径超出计划快照。
 - 未经批准的跨项目或跨分区读取。
-- Token、时间、工具、子任务和成果预算。
+- Token、时间、工具、Job/Subjob 和成果预算。
 - 幂等键冲突或结果未知。
 - 输出 Schema 不匹配。
 - 实验 Run 读取其他 Run 数据。
@@ -249,7 +250,11 @@ type SupervisorDecision = {
 
 ## 13. 用户交互
 
-### 13.1 右侧评论流
+### 13.1 工作栏监督栏目评论流
+
+监督是助手工作栏中固定且始终可访问的栏目，不是只在聊天页面出现的附属面板。栏目默认
+跟随当前会话，用户也可以固定到其他普通 Conversation、Task 或 Experiment。
+切换页面不会改变固定目标；目标失效时必须显示修复状态，不能静默回到当前会话。
 
 复用魔法笔记的体验方向：
 
@@ -272,7 +277,8 @@ type SupervisorDecision = {
 
 ### 13.2 会话输入区
 
-提供监督状态入口：
+会话输入区可以提供当前会话监督的快捷入口，但不是监督能力的唯一入口，也不控制工作栏中
+已经固定到其他对象的监督目标：
 
 ```text
 监督：关闭 / 综合 / 质疑 / 证据 / 目标 / 风险
@@ -311,7 +317,7 @@ open
 Supervisor 建议“暂停”时：
 
 1. 创建 `request_review`。
-2. 在任务和会话界面显示原因和证据。
+2. 在任务自身的会话界面显示原因和证据。
 3. 用户选择继续、暂停、调整目标或取消。
 4. 用户操作进入任务审计。
 

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

@@ -7,7 +7,7 @@
 | 文档状态 | 实现与发布验收基线 |
 | 设计目标 | 将 DeepSeek Harness 作为 GoodBuddy 的第三个 Agent Runtime |
 | Runtime 标识 | `deepseek-harness` |
-| 首版依赖基线 | 实际使用的 `@deepseek-ai/dsh-*` 底层库，精确锁定 `0.1.0-rc.6` |
+| 当前依赖基线 | 实际使用的 `@deepseek-ai/dsh-*` 底层库，精确锁定 `0.1.0-rc.8` |
 | 上游状态 | Developer Preview，允许出现破坏性变更 |
 | 上游许可证 | MIT |
 | GoodBuddy 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
@@ -163,7 +163,7 @@ Electron utilityProcess
        ├─ 本地 Shell / Filesystem Provider
        ├─ 最小工具集与 Main 代理 MCP
        └─ Main 明确启用的第三方 Cordis 插件
-             │ HTTPS
+             │ HTTP/HTTPS
              ▼
         用户选择的 OpenAI 兼容模型连接
 ```
@@ -219,6 +219,10 @@ GoodBuddy 控制面自身不导出 `apply(ctx, config)`，也不提供默认 std
 - 插件成功激活后可注册工具或后台生命周期逻辑。Ask 只能拦截模型工具调用，不能撤销初始化阶段已经发生的副作用。
 
 GoodBuddy 不扫描任意目录、不读取用户 profile 插件清单，也不接受 Renderer 直接提供文件路径。
+插件安装、升级和移除在目录重命名前写入受管变更日志。Main 下次初始化时以持久
+Store 是否已经提交为准，确定性完成新目录或恢复旧目录，并在处理前重新验证受管
+目录、入口真实路径、符号链接和根目录包含关系。旧版 `store.json` 继续原地迁移，
+不要求用户重新安装插件。
 
 ## 8. 协议设计
 
@@ -250,7 +254,9 @@ GoodBuddy 不扫描任意目录、不读取用户 profile 插件清单，也不
 | `goodbuddy/native/snapshot` | Main → Control Plane | 从无 Agent scope 的 Host Registry 读取有界的原生 Tool/Skill 元数据，排除 GoodBuddy 分配项与请求级代理 |
 | `goodbuddy/shutdown` | Main → Control Plane | 停止接收新请求并有序清理 |
 
-Utility 启动控制协议使用版本 2，严格携带 `supportsImageInput` 与固定 8 MiB 帧上限；版本 1 或缺少该字段的启动消息失败关闭，不能让 Host 自行猜测模型能力。扩展版本独立于 ACP 版本。握手响应至少包含：
+Utility 启动控制协议使用版本 3，严格携带 `supportsImageInput`、模型连接的有界自定义
+Header 与固定 8 MiB 帧上限；旧版本或缺少必需字段的启动消息失败关闭，不能让 Host
+自行猜测模型能力。扩展版本独立于 ACP 版本。握手响应至少包含：
 
 ```ts
 type GoodBuddyHarnessCapabilities = {
@@ -321,17 +327,18 @@ GoodBuddy conversationId -> Harness sessionId + process generation
 - 历史以明确的“不可信会话数据”结构传入，不能拼接成系统指令。
 - 用户分配的 Skill 只通过 Main 校验的包路径进入 Host，并在 Agent scope 注册；不得把 Skill 内容伪装成用户 Prompt。
 
-### 9.3 取消与超时
+### 9.3 取消与有界控制操作
 
 - 用户取消时立即发送 `session/cancel`。
 - 取消等待有界，超时后关闭连接并终止整个 Harness 进程。
-- 初始化、握手、Session 创建、Prompt、权限回传和关闭分别使用独立超时。
-- Prompt 超时与用户取消使用不同错误类型，不能被宽泛 catch 抹平。
+- 初始化、握手、请求准备、权限回传和关闭分别使用独立控制超时。
+- 生产 Prompt 不设置固定墙钟总时限，由 Harness 自身协议终态或用户取消结束。测试可以
+  显式注入短 Prompt 时限验证取消传播，超时错误与用户取消仍不能被宽泛 catch 抹平。
 - 取消后仍可接收并丢弃该请求的最终协议结算帧，但不得写入下一请求。
 
 ### 9.4 释放与退出
 
-- 原生能力清单通过一次性 Runtime 探测，取得有界快照后立即 dispose，不得因浏览设置或切换项目把 Host 缓存在执行 Runtime 池中。
+- 原生能力清单由 `SelectedRuntimeManager` 缓存的执行 Runtime 提供，与随后的对话请求共用同一实例，不再为清单单独启动并销毁一次 Host；该实例遵循执行缓存的空闲淘汰、设置变更 reset 和退出 dispose 规则。
 - 删除或释放对话时调用 `goodbuddy/session/release`。
 - Runtime dispose 时先拒绝新请求，再取消所有 Session。
 - Harness Control Plane 完成 Agent、工具和会话清理，Host 完成 Cordis Fiber 与子进程的反向清理。
@@ -422,13 +429,16 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
 
 - 协议必须是 `openai-chat-completions`。
 - 认证必须是 API Key。
-- 公网服务地址必须使用 HTTPS；`localhost`、`127.0.0.1` 和 `::1` 回环地址可以使用 HTTP。
-- 服务地址可以使用自定义主机、端口和部署路径，但不得包含用户名、密码、查询参数或片段。
+- 服务地址支持 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 加密设置中。
 - 启动环境提供的部署连接只由 Main 自动解析，不在 Renderer 中显示为可选来源。
+- 未显式指定 Harness 模型且没有可用的管理员预置连接时，Main 优先使用当前默认的兼容 GoodBuddy 模型连接；默认连接不兼容时使用首个兼容连接。只有不存在任何兼容连接时才提示用户前往模型或 Runtime 设置。
 
 不允许选择 Harness 自有的用户配置文件或自定义 Host。Runtime 始终使用随当前 GoodBuddy 版本发布的内置 Host，并通过完整内部能力握手。
 
@@ -442,7 +452,7 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
 - 文本模型收到图片时必须在启动 Host 或发起模型网络调用前返回明确错误，不能静默丢弃图片。
 - 图片模型只接受内联 JPEG/PNG，不接受 URL、文件路径、ACP `uri` 或其他媒体类型。
 - Main 已通过 `nativeImage` 解码用户选择的图片并生成有界模型输入；Utility 仍须独立执行严格 base64、签名、容器结构、CRC（PNG）、完整解码、尺寸和摘要校验，不能把 Main 校验当作跨进程信任替代。
-- 每条消息最多 8 张图，单图编码后最多 1 MiB，图片合计最多 2 MiB，单图最多 1,600 万像素，累计解码像素最多 3,200 万（重复引用也计入预算）。进程内 Store 另设 32 MiB、256 个唯一对象的总上限。
+- 每条消息最多 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 配置表达式或模块名。
@@ -455,7 +465,7 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
 | --- | --- |
 | 单个 JSON-RPC 帧 | 8 MiB |
 | 单图 / 单条消息图片 | 1 MiB / 8 张且合计 2 MiB |
-| 单图 / 单条消息解码像素 | 1,600 万 / 3,200 万 |
+| 单图尺寸 / 单条消息解码像素 | 单边最长 8,192 px 且 1,600 万像素 / 3,200 万像素 |
 | Host 临时图片存储 | 32 MiB 且最多 256 个唯一对象 |
 | 单个文本或推理事件 | 64 KiB |
 | 单次请求累计协议输出 | 4 MiB |
@@ -465,7 +475,7 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
 | stderr 累计 | 64 KiB |
 | Host 启动 | 10 秒基础预算 + 每插件 5 秒激活与最多 1 秒失败清理，插件序列最多 91 秒；Main 另预留 2 秒持久化失败状态 |
 | ACP 初始化与内部握手 | 每阶段 10 秒 |
-| 单次 Prompt | 10 分钟 |
+| 单次 Prompt | 无固定墙钟总时限，由 Harness 终态或用户取消结束 |
 | 有序关闭宽限期 | 2 秒 |
 
 超过限制时应取消当前请求。协议帧、队列或 stderr 持续异常时，应终止 Runtime 进程，避免继续信任已失控的通道。
@@ -493,7 +503,7 @@ Runtime：       GoodBuddy 内置 DeepSeek Harness
 模型配置：      跟随 GoodBuddy · 企业网关（qwen-plus）
 状态：          已就绪
 路径：          <受控 Host 路径>
-版本：          0.1.0-rc.6
+版本：          0.1.0-rc.8
 执行权限：      当前用户权限
 
 Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
@@ -523,13 +533,17 @@ OpenCode、Continue 和 DeepSeek Harness 的后续能力按操作生命周期放
 | 表面 | 负责内容 | 不负责内容 |
 | --- | --- | --- |
 | Composer 通用行 | 附件、语音、知识范围、专家、Ask/Execute、Runtime 和发送 | Session 监督、后台进度、历史任务管理 |
-| Composer Runtime 专属行 | 仅对当前消息生效且需要高频选择的 Agent、预设、Prompt/Command 快捷操作 | Subagent 树、后台 Job、Workflow/Hook 生命周期 |
-| 右侧助手工作栏的未来“Runtime”页签 | 当前会话的 Runtime 状态、Subagent 层级与取消、后台 Job 队列/进度/结果、Workflow/Hook 运行、长任务暂停/恢复/终止和会话监督 | 持久模型、程序路径、默认 Agent/预设配置 |
+| 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 或会话时，侧栏必须明确更新归属，不能把上一 Runtime 的 Job/Subagent 状态留在当前会话中。
+Runtime 栏目入口始终存在，并采用统一监督模型；内部再按用户所选目标及其 Runtime 的真实能力
+显示 OpenCode、Continue 或 DSH 的具体区域。未支持能力不渲染空卡片或一排禁用按钮，而是
+在用户需要理解缺口时显示原因和可执行入口。跟随模式切换 Runtime、Conversation 或 Task
+时必须清理上一归属的聚合执行状态，固定目标则保持不变。完整工作栏契约见
+[通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)。
 
-所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、父子任务关系、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。
+所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、Task/Job/Subjob 层级、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。
 
 ## 15. IPC 与共享契约
 
@@ -728,7 +742,7 @@ npm run build
 - Harness 文件和命令工具没有 Runtime OS 隔离，会继承 GoodBuddy 客户端当前用户能够访问的主机资源。
 - 首版不恢复 Harness 原生 Session，Runtime 重启后由 GoodBuddy 历史重建。
 - 图片输入仅在所选模型连接明确声明支持时可用；首版仍不支持知识库、浏览器控制和 Harness Subagent。Web Search/Fetch 仅使用 Main 代理，MCP 仅支持用户分配、Main 代理和 Execute 自动单次授权路径。
-- Harness Subagent、后台 Job、Workflow、Hook 和原生会话监督尚未实现；未来入口固定在右侧 Runtime 监督栏，不扩张 Composer 工具栏。
+- Harness Subagent、后台 Job、Workflow、Hook 和原生会话监督尚未实现；未来按 Task 聚合到右侧 Runtime 监督栏，不扩张 Composer 工具栏或暴露 Job/Run 层级。
 - 推理、工具和用量扩展属于 GoodBuddy 协议，不是标准 ACP 保证。
 - 市场来自公共 npm 关键字搜索，不是精选目录；包的质量、兼容性和维护状态由发布者负责。
 - 插件安装、初始化、后台生命周期和 Execute 工具使用当前用户权限，不受 Runtime OS 沙箱保护；Ask 只控制模型工具调用。
@@ -767,4 +781,4 @@ GoodBuddy 对该 Runtime 采用内部维护策略：
 
 未采用。Main 无法可靠观察 Cordis 内部 Session、Tool、Usage 和权限 seam，只能得到不完整的外部进程行为。
 
-当前选择让双层内部控制面保持 GoodBuddy 私有，同时允许 Main 从受管 Store 向固定 Host 注入标准 Cordis 插件；插件扩展面不会取代 GoodBuddy 的可信 Main 控制权。
+当前选择让双层内部控制面保持 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,51 @@
+# 直连模型 Agent 能力
+
+本目录是 GoodBuddy“直连模型 Agent 能力”的唯一文档入口。本功能为直连文本模型补齐
+跨平台进程执行和编程 Subagent，使其能够在 Execute 模式完成读取、修改、运行和验证组成的
+编程闭环，同时避免向已经拥有原生 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 命令并返回有界结果 |
+| 平台 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) 为准。本功能不重新定义
+这些对象。
+
+## 功能边界
+
+- `process_execute` 和 `subagent_delegate` 是 GoodBuddy 直连模型内置工具，不是外部 MCP。
+- 直连文本模型的普通问答、工具轮次和上下文摘要会在尚无可见输出时，对瞬时网络错误或
+  单次请求超时最多自动重试 3 次。
+- OpenCode、Continue 和 DeepSeek Harness 继续使用各自原生执行与委派能力。
+- Ask 不允许进程执行；Subagent 若在 Ask 中使用，只能继承 Ask 的只读能力。
+- 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,195 @@
+# 直连模型 Agent 能力功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.3 |
+| 日期 | 2026-09-03 |
+| 关联 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 次；用户取消和已显示的部分输出禁止重放。
+
+## 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` | Ask/Execute | SSH，远端后端未实现 | 隐藏 | 当前远端直连模型产品入口不开放 |
+| 其他 Runtime | 任意 | 任意 | 隐藏 | 隐藏 |
+
+工具清单隐藏不是最终授权边界。`callTool` 仍须重新验证 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` 仍产生正常工具结果。
+- 超时和取消结果包含已经取得的有界输出。
+- 进入 `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、浏览器或知识能力时继续经过这些能力已有的作用域和生命周期边界。
+- 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,197 @@
+# 直连模型 Agent 能力 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台 CI 待验证 |
+| 版本 | 0.3 |
+| 日期 | 2026-09-03 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 关联领域 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
+
+## 1. 背景
+
+GoodBuddy 直连模型已经可以读取、列出和写入工作区文本，使用浏览器、联网搜索、知识库及
+分配的 MCP，但没有内置命令执行工具。模型可以生成代码，却不能运行构建、测试、格式化、
+Git 或项目脚本，因此无法独立验证结果。
+
+GoodBuddy 也已经有面向用户专家协作的只读 Subagent，但直连模型不能在自己的工具循环中
+主动委派一个聚焦的编程子任务。OpenCode、Continue 和 DeepSeek Harness 一般已经提供
+Shell、Agent 或 Task 能力，再向它们注入 GoodBuddy 同名工具只会造成重复入口和语义冲突。
+
+本功能只补齐直连模型缺少的基础 Agent 能力：
+
+1. 一个按平台适配的进程执行接口。
+2. 一个单层、继承父请求范围的编程 Subagent 接口。
+
+## 2. 产品目标
+
+1. 让直连模型在 Execute 模式完成“读取代码 → 修改 → 运行 → 根据结果修正”的闭环。
+2. 在 Windows、macOS 和 Linux 使用同一个模型工具契约，不要求模型调用平台专属工具名。
+3. 让直连模型可以把独立工作委派给临时 Subagent，并取得有界、可核验的结果。
+4. 保持 Ask 只读、Execute 完整授权、执行空间、取消、有界输出和进程回收语义不变。
+5. 不向已有原生执行能力的 Agent Runtime 重复注入 GoodBuddy 进程或 Subagent 工具。
+
+## 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 不增加
+“受控执行”“仅测试”“可信命令”或逐命令风险等级，也不重复弹出第二套确认。
+
+## 4. 功能范围
+
+### 4.1 包含
+
+- 本机 Windows、macOS、Linux 的前台 Shell 命令执行。
+- 当前工作区默认工作目录，以及当前用户可访问的本机工作目录选择。
+- Exit Code、标准输出、标准错误、Shell、目录、耗时和截断状态。
+- 命令超时、用户取消、进程树停止和应用退出清理。
+- 新进程使用当前本机工具环境提供的 Node、Python 和 PATH。
+- 直连模型单层 Subagent 委派、排队、运行、部分结果、失败和取消。
+- 父子请求的工具、模型用量、活动和成果归属。
+- 桌面聊天和选择直连模型的消息通道项目使用相同 Runtime 能力矩阵。
+
+### 4.2 不包含
+
+- 交互式 PTY、终端复用、持续 stdin、密码提示或 TUI 自动化。
+- 后台守护进程、任意 PID 枚举、接管或停止用户已有进程。
+- Shell Session 持久化，环境变更不会跨 `process_execute` 调用保留。
+- 首版远程 SSH 直连模型进程执行。
+- 向 OpenCode、Continue 或 DeepSeek Harness 注入本功能工具。
+- 递归 Subagent、长期运行的自治 Agent、Workflow、Hook 或恢复未完成子任务。
+- 新的权限矩阵、逐命令批准、沙箱档位或命令白名单。
+- 自动安装项目依赖；模型可以在 Execute 中显式运行项目已有的安装命令。
+
+## 5. 功能需求
+
+### FR-1 直连模型专属可用性
+
+- 两个工具只由 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 提示、结果、队列和并发全部有界。
+- 截断必须明确标记，不能把不完整输出伪装为完整结果。
+
+### FR-8 环境和凭据
+
+- 新进程使用筛选后的当前用户环境和本机工具环境 PATH。
+- 模型 Provider 凭据、GoodBuddy 加密设置和无关桌面会话变量不进入命令环境。
+- 首版不接受模型提交任意环境变量映射；需要的普通变量由 Shell 命令在单次调用中设置。
+
+### FR-9 状态与活动
+
+- 进程活动显示等待、运行、成功、非零退出、超时、取消和失败。
+- Subagent 显示排队、运行、完成、失败和取消。
+- 命令和子任务失败保留可操作错误及已有部分输出。
+- 同一事件不同时显示页内错误和应用通知。
+
+### FR-10 兼容
+
+- 现有模型连接、MCP 分配、专家设置和 Runtime 选择无需迁移。
+- 不改变现有 Agent Runtime 的工具清单或权限语义。
+- 不修改系统 PATH、Shell Profile 或用户终端会话。
+
+### FR-11 模型请求重试
+
+- 直连文本模型的普通问答、工具轮次和上下文摘要遇到瞬时网络错误或单次请求超时时，
+  在尚未显示文本或推理内容的前提下最多自动重试 3 次。
+- 重试使用递增等待时间并显示当前次数；用户取消必须立即终止等待和后续请求。
+- 一旦本次模型调用已经显示文本或推理内容，不自动重放该调用，避免重复回答。
+- 非网络类 Provider 错误、协议错误和用户取消不进入自动重试。
+
+## 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 次，成功后继续原请求。
+- [ ] 重试等待可取消，已显示部分内容的失败不自动重放。
+- [ ] 全量测试、类型检查、Lint 和生产构建通过。

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

@@ -0,0 +1,166 @@
+# 直连模型 Agent 能力功能进度
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档类型 | 功能进度 |
+| 状态 | 已实施，本机验收完成 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-05 |
+| 关联入口 | [直连模型 Agent 能力](./README.md) |
+
+## 当前结论
+
+本机生产路径已经完成源码接线：直连模型 Execute 可运行平台 Shell，Ask/Execute 均可按
+父模式委派单层编程 Subagent；OpenCode、Continue、DeepSeek Harness 和托管 SSH 路径不注入
+这两个工具。Windows 本机、真实模型和全量项目验证已通过；macOS 与 Linux 真机验证仍需
+由对应平台完成。
+
+## 已确认的当前基线
+
+- [x] 直连模型当前内置工作区读、目录列表和文本写入，但没有进程工具。
+- [x] 内置 MCP 当前没有 Shell；自定义 MCP 不能替代开箱即用的进程能力。
+- [x] `ModelAgentRuntime` 已有多轮工具循环、取消、上下文压缩和有界结果。
+- [x] DeepSeek Harness 已按 Windows PowerShell、macOS/Linux Bash 注册原生 Shell。
+- [x] OpenCode 和 Continue 使用各自原生执行工具。
+- [x] 当前专家 Subagent 是只读协作流程，不是直连模型可调用的编程工具。
+- [x] Task/Job 领域文档已经明确 Subagent 不是新的顶层 Task 或 Conversation。
+- [x] 当前跨平台进程树清理已经覆盖 Windows `taskkill /T /F` 和 POSIX 进程组。
+
+## 已完成设计
+
+- [x] 工具只注入直连模型，不注入 Agent Runtime。
+- [x] 统一 `process_execute` 契约和三平台 Shell 决策。
+- [x] Ask/Execute、执行空间、工作目录和非零退出规则。
+- [x] 输出、超时、取消、环境和进程树边界。
+- [x] 单层 `subagent_delegate`、继承规则、并发和结果模型。
+- [x] 不创建 Child Task/独立 Conversation 的领域归属。
+- [x] 设置能力目录、聊天活动、错误和无障碍行为。
+- [x] 本机、真实模型和项目验证方案。
+
+## 实施状态
+
+### 阶段 1：进程服务
+
+- [x] Shared 工具和 schema。
+- [x] 本机 Shell 探测与能力状态。
+- [x] 工作目录解析。
+- [x] 跨平台前台进程、输出边界、超时和取消。
+- [x] 当前筛选 PATH 和凭据环境过滤。
+
+### 阶段 2：直连模型接入
+
+- [x] `ModelToolProvider` 注册与调用。
+- [x] Ask/Execute、Runtime target 和本机执行空间双重检查。
+- [x] DeepSeek Harness、OpenCode 和 Continue 隔离。
+- [x] 通用工具活动和“设置 > MCP > 直连模型”编程能力目录。
+- [x] 普通问答、工具轮次和上下文摘要的瞬时网络错误及请求超时最多自动重试 3 次。
+- [x] 递增退避、重试状态、取消传播和已显示输出不重放。
+
+### 阶段 3：编程 Subagent
+
+- [x] 编程 Subagent 服务和同 Provider 深度过滤。
+- [x] 父子模式、模型、执行空间和能力继承。
+- [x] 深度、全局并发、队列、超时和取消。
+- [x] 新 Subagent actor 契约和旧专家事件兼容读取。
+- [x] 用量、部分输出、实时活动和终态归并。
+
+### 阶段 4：端到端验收
+
+- [x] Windows PowerShell 真实命令。
+- [ ] macOS Bash/Sh 真实命令。
+- [ ] Linux x64/arm64 Bash/Sh 真实命令。
+- [x] 直连模型“修改 → 测试 → 修复”真实闭环。
+- [x] 假模型端到端 Subagent 编程委派、真实本机命令和父模型综合。
+- [x] 真实模型 Subagent 编程委派和父模型综合。
+- [x] Runtime 隔离、取消、会话释放和进程树回收聚焦测试。
+- [x] 全量测试、类型检查、Lint 和生产构建。
+
+## 当前阻塞项
+
+- 当前没有实现阻塞项。
+- 本机工具环境仍处于计划阶段；在其实施前，进程工具可以使用当前筛选 PATH，但不能宣称
+  GoodBuddy 托管 Node/Python 已可用。
+- 远端直连模型进程执行不在首版，后续需要独立增加 Agent 进程协议和真机验证。
+
+## 2026-09-06 命令工作目录限制修复
+
+- FR-3 / US-A3：移除命令工作目录的工作区范围限制。绝对路径、`..` 和指向工作区外
+  的符号链接均按本机文件系统解析，工作区只作为默认目录和相对路径基准。
+- 保留目录存在性、本机执行空间绑定、Ask 拒绝命令、取消、超时和进程树回收。
+  本次没有改变工作区文件读写工具或远端 Agent 路径。
+- `direct-model-process-service.test.ts` 覆盖绝对路径、相对路径、外部目录、符号链接、
+  不存在的目录和普通文件；当前 Windows 环境通过。
+- `model-runtime.test.ts` 新增两个生产工具链回归：模型协议响应提供绝对或相对外部
+  `cwd`，经 `ModelAgentRuntime → ModelToolProvider → LocalDirectModelProcessService`
+  启动真实 PowerShell，在专用工作区外测试目录复制文件并读回验证。模型响应为本机
+  测试替身，没有外部模型调用；不将此记录为真实模型或 macOS/Linux 真机验收。
+- 最终聚焦验证：`opencode-runtime`、`opencode-runtime-lifecycle`、
+  `direct-model-process-service`、`model-tool-provider`、`model-runtime` 五个测试文件
+  `182 passed, 1 skipped`；`npm run typecheck` 和 `npm run lint` 通过。
+- 本次共享工作区的全量 `npm test` 为 `3542 passed, 57 skipped, 1 failed`。唯一失败是
+  `App.test.tsx` 的 `opens the global assistant sidebar and switches work tabs`，
+  仍期望“项目工作区”标题，单独复测同样失败；该侧栏处于其他会话的修改范围，本次未改动。
+  因此本次全量验证不能记录为全部通过。
+
+## 2026-09-01 至 2026-09-02 实施与验证证据
+
+- 新增 `direct-model-process-service.ts`：PowerShell/Bash/Sh 探测、工作区目录校验、96 KiB
+  首尾输出、超时、取消、进程树回收和环境过滤。
+- 新增 `direct-model-subagent-service.ts`：单层委派、共享并发 3、队列 20、10 分钟上限、
+  192 KiB 输出、父请求取消和临时会话释放。
+- `ModelToolProvider` 只在直连模型上下文注册工具；Ask 隐藏进程工具，深度 1 隐藏委派工具，
+  远端工作区拒绝本机进程。
+- `ModelAgentRuntime` 复用同一已解析模型和 Tool Provider 运行子级，并把子级工具、用量和
+  Subagent 活动实时归并到父请求。
+- 新 actor 联合类型兼容既有专家/OpenCode 记录；编程 Subagent 不创建 Assistant Task。
+- 聚焦验证：
+  - 进程、Provider、Runtime、共享契约与聊天 UI：`290 passed, 1 skipped`。
+  - 设置与 Runtime 隔离：`216 passed`。
+  - Main/Shared 聚焦持久化与 Subagent：`188 passed, 1 skipped`。
+  - Node 与 Web TypeScript no-emit 检查通过。
+- 假模型端到端场景实际启动 Windows PowerShell，子级运行命令后返回父模型；该场景的
+  Runtime 模型调用数为 4 次。
+- 真实 DeepSeek 兼容连接端到端通过：模型创建失败程序、观察非零退出、修复并观察退出码
+  0、委派编程 Subagent 再次运行最终程序并综合结果；最终源码成功验收运行包含 8 次真实
+  模型调用。
+- BigToken 连接的首次验收在 TLS 建立前被 `ECONNRESET` 中断，未进入模型工具路径；切换
+  到仓库已有的 DeepSeek 连接后完成验证。2026-09-03 已针对该故障补充统一模型请求重试。
+
+## 2026-09-03 模型请求重试验证证据
+
+- `ModelAgentRuntime` 对普通问答、工具轮次和上下文摘要统一处理瞬时 Node/Undici 网络错误
+  与请求超时；首次失败后最多重试 3 次，退避为 500 ms、1 s、2 s。
+- 聚焦测试覆盖嵌套 `fetch failed` → `ECONNRESET` 恢复、工具轮次恢复、四次尝试后终止、
+  退避取消，以及已显示部分流式输出时不重放。
+- `npm test -- --run src/main/agent/model-runtime.test.ts`：
+  `72 passed, 1 skipped`。
+- 全量 `npm test`：`3484 passed, 51 skipped`。
+- `npm run typecheck`、`npm run lint` 和 `npm run build`：通过。
+- 最小真实直连文本模型验证：`1 passed, 13 skipped`，实际模型调用 1 次。
+
+- 全量 `npm test`：`3410 passed, 50 skipped`。
+- `npm run typecheck`：通过。
+- `npm run lint`：通过。
+- `npm run build`：Main、Preload、Renderer 和控制面安装器均成功构建。2026-09-02 按产品
+  决策移除未对应实际性能问题的 Renderer bundle 基线门禁后复验通过。
+
+## 2026-09-05 移除直连模型响应字节上限
+
+- 直连模型不再对流式响应总量、单个流式块、非流式回复、模型工具参数、工具请求上下文、
+  聚合工具结果和累计回答长度设置字节上限；长回复和大工具结果由请求超时、取消和上下文
+  压缩控制。用户不再看到“模型接口流式响应超过安全限制”。
+- 图像生成响应仍按可解码图片大小校验，Provider 错误响应仍读取有界文本。
+- 回归测试改为验证超过旧上限的长流式回复可以完整返回，以及超过 1 MB 的图片工具结果会
+  进入下一轮模型请求。
+- `npx vitest run src/main/agent/model-runtime.test.ts`：`74 passed, 1 skipped`。
+- 全量 `npm test`：`3493 passed, 55 skipped`。
+- `npm run typecheck`、`npm run lint` 和 `npm run build`：通过。
+
+## 进度维护要求
+
+- 只有真实生产路径完成并验证后才能勾选实施项。
+- 平台模拟单元测试不能替代对应平台真实命令测试。
+- 真实模型验证必须记录准确调用次数且不得记录凭据。
+- 需求变化回写 PRD、User Stories 和功能逻辑；实现事实只写本文件。

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

@@ -0,0 +1,412 @@
+# 直连模型 Agent 能力技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.3 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 相关架构 | [助手工作栏与执行空间](../assistant-workbar/prd.md)、[本机工具环境](../local-tool-environment/technical-design.md) |
+
+## 1. 实现基线
+
+当前源码已经实现：
+
+- `ModelAgentRuntime` 的多轮工具调用、上下文压缩、取消、用量和有界结果处理。
+- `ModelToolProvider` 的直连模型内置工具、浏览器、Web、知识和自定义 MCP 聚合。
+- `WorkspaceAccess` 的本机和远端工作区抽象。
+- 跨平台子进程树终止辅助函数。
+- 面向用户专家协作的 `SubagentScheduler`、状态事件和只读模型调用。
+- OpenCode、Continue 和 DeepSeek Harness 各自的 Shell/Agent 能力。
+- 直连模型 `process_execute` 和 `subagent_delegate`。
+- 不创建顶层 Task/Conversation 的编程 Subagent actor 与活动归并。
+
+## 2. 总体架构
+
+```text
+ModelAgentRuntime
+  └─ ModelToolProvider
+       ├─ WorkspaceAccess
+       ├─ DirectModelProcessService
+       │    └─ LocalDirectModelProcessService
+       ├─ DirectModelSubagentService
+       │    ├─ SubagentScheduler
+       │    └─ 同一 ModelAgentRuntime 的临时子会话
+       │         └─ 同一 ModelToolProvider（delegationDepth=1 时移除委派）
+       ├─ Browser / Web / Knowledge
+       └─ assigned MCP
+```
+
+OpenCode、Continue 和 DeepSeek Harness 的创建路径不接收
+`DirectModelProcessService` 或 `DirectModelSubagentService`。DeepSeek Harness 即使继续使用
+`ModelToolProvider` 代理 Web/MCP，也必须通过明确的工具视图排除直连模型专属工具。
+
+## 3. 共享工具目录
+
+`BuiltinModelToolSummary` 增加 `programming` 分组和 Runtime 可见性：
+
+```ts
+type BuiltinModelToolSummary = {
+  name: string
+  displayName: string
+  description: string
+  access: 'read' | 'write'
+  group: 'filesystem' | 'browser' | 'web' | 'programming'
+}
+```
+
+`process_execute` 标记为 `write`，只在 Execute 清单中出现。
+`subagent_delegate` 的实际访问级别由父模式决定：
+
+- Ask 清单中提供只读委派定义。
+- Execute 清单中提供继承 Execute 的定义。
+- `callTool` 不依赖静态 `access` 单独授权，必须检查父请求上下文。
+
+工具总数和 schema 总字节继续计入直连模型现有 100 个工具与 512 KiB 上限。
+
+## 4. 进程工具契约
+
+### 4.1 输入
+
+```ts
+const processExecuteInputSchema = z.object({
+  command: z.string().trim().min(1).max(100_000),
+  cwd: z
+    .string()
+    .trim()
+    .min(1)
+    .max(4_096)
+    .optional(),
+  timeoutMs: z
+    .number()
+    .int()
+    .min(1_000)
+    .max(10 * 60_000)
+    .default(120_000)
+}).strict()
+```
+
+- `cwd` 接受绝对路径或相对工作区路径，省略时使用工作区根目录；按本机路径语义解析
+  `..` 和符号链接，不限制目标位于工作区内。工具 schema 向模型明确这一规则。
+- 首版不接受 `env`、`stdin`、`background`、`pty`、`shell` 或任意 executable 参数。
+- Shell 选择由执行后端决定，防止模型绕过平台契约启动另一套受管接口。
+- 命令字符串仍可以调用当前账号本来有权运行的程序；Execute 不增加命令白名单。
+
+### 4.2 结果
+
+```ts
+type ProcessExecuteResult = {
+  shell: {
+    kind: 'powershell' | 'bash' | 'sh'
+    label: string
+  }
+  cwd: string
+  exitCode: number | null
+  signal?: string
+  terminationReason?: 'timeout' | 'cancelled'
+  durationMs: number
+  stdout: string
+  stderr: string
+  stdoutTruncated: boolean
+  stderrTruncated: boolean
+}
+```
+
+`cwd` 在工作区内返回相对显示值，根目录为 `.`；工作区外返回规范化绝对路径，准确说明
+命令实际执行位置。Shell 在模型结果中只返回稳定标签；绝对可执行路径只进入 Main 诊断状态。
+
+### 4.3 输出边界
+
+- stdout 和 stderr 各最多 96 KiB。
+- 超限时分别保留前 48 KiB 与最后 48 KiB，中间插入固定截断标记。
+- JSON 结果加上元数据后必须低于 `ModelToolProvider` 现有 256 KiB 工具结果上限。
+- 流式读取在收到数据时执行边界，不先积累无界 Buffer。
+- 输出按 UTF-8 解码，无效序列使用替换字符并保留字节计数。
+
+## 5. 平台执行
+
+### 5.1 Shell 探测
+
+启动直连模型执行服务时解析一次 Shell：
+
+```text
+Windows: PATH 中 pwsh → Windows PowerShell powershell.exe
+macOS:   /bin/bash → /bin/sh
+Linux:   /bin/bash → /bin/sh
+```
+
+Shell 不可用时保留直连模型对话能力，但不注册 `process_execute`。设置目录继续展示静态能力
+说明，实际 Shell 通过每次请求的工具定义和结果可见；当前不增加独立 Shell 诊断 IPC。
+不下载或捆绑新的 Bash/PowerShell。
+
+### 5.2 启动参数
+
+```text
+PowerShell:
+  <shell> -NoLogo -NoProfile -NonInteractive -Command <command>
+
+Bash:
+  /bin/bash -c <command>
+
+Sh:
+  /bin/sh -c <command>
+```
+
+使用 `spawn(executable, args, { shell: false })`，避免 Node 再增加一层平台 Shell。POSIX 子进程
+作为独立进程组启动；Windows 记录根 PID。停止时复用现有
+`terminateProcessTreeAndWait`：Windows 使用 `taskkill /T /F`，POSIX 终止本次进程组并等待
+有界退出。
+
+### 5.3 环境
+
+进程环境由 Main 构造：
+
+- 继承运行普通项目命令所需的当前用户基础变量。
+- 当前使用筛选后的用户 PATH；[本机工具环境](../local-tool-environment/technical-design.md)
+  实施后可通过现有 `toolBinDirectory` 注入口把受管 bin 放在 PATH 前面。
+- 排除模型 Provider Key、GoodBuddy 加密设置、调试变量和无关应用凭据。
+- 不修改 `process.env`，不写系统 PATH 或 Shell Profile。
+- 每次调用得到独立环境快照；命令内设置的变量不会进入下一次调用。
+
+## 6. 执行空间绑定
+
+定义一个小型进程后端接口，不把任意进程能力塞进 `WorkspaceAccess`：
+
+```ts
+interface ExecutionSpaceProcessExecutor {
+  getCapability(): Promise<
+    | { available: true; shell: ProcessShellSummary }
+    | { available: false; reason: string }
+  >
+  execute(
+    input: ProcessExecuteInput,
+    context: {
+      workspace: WorkspaceAccess
+      signal: AbortSignal
+    }
+  ): Promise<ProcessExecuteResult>
+  dispose(): Promise<void>
+}
+```
+
+首版只有 `LocalProcessExecutor`。`ExecutionSpaceDescriptor.kind === 'ssh'` 时使用不可用实现，
+工具清单不注册进程能力。未来远端实现必须新增 Agent 协议、由 Agent 直接拥有命令进程，并
+按远端身份、取消和断线语义验证；不得把 SSH 路径传给本机 executor。
+
+工作目录通过 `WorkspaceAccess.getIdentity()` 和本机真实路径解析共同确认。路径检查与 spawn
+之间若目录被外部替换，spawn 失败并返回准确错误；不为此增加持久路径凭据或恢复协议。
+
+## 7. Subagent 工具契约
+
+### 7.1 输入
+
+```ts
+const subagentDelegateInputSchema = z.object({
+  task: z.string().trim().min(1).max(100_000)
+}).strict()
+```
+
+首版一次调用只创建一个子任务。不同父请求可以通过全局调度器并发，不增加批量委派 schema。
+
+### 7.2 子请求
+
+`DirectModelSubagentService` 创建临时子请求：
+
+```ts
+type DirectModelSubagentContext = {
+  parentRequestId: string
+  childRunId: string
+  projectId?: string
+  conversationId: string
+  workMode: 'ask' | 'execute'
+}
+```
+
+- 子 `conversationId` 只用于 Runtime 内存和工具会话隔离，完成后立即
+  `releaseConversation`，不保存为用户 Conversation。
+- 子 Prompt 使用明确任务和 Main 可信的编程 Subagent 指令，不复制父会话历史。
+- 子级使用父请求模型连接，首版不增加单独模型选择设置。
+- 子级复用父请求已授权能力快照和知识范围。
+- 子级复用父 Provider；Main 写入的 `delegationDepth=1` 同时在清单和调用边界过滤
+  `subagent_delegate`。
+- Ask 子级使用 Ask 清单；Execute 子级使用 Execute 清单。
+
+### 7.3 调度和结果
+
+- 复用 `SubagentScheduler` 的取消、并发和队列模式。
+- 全局最大并发 3，队列最大 20。
+- 单个子任务最长 10 分钟；父请求更早取消时立即停止。
+- 文本结果最多 192 KiB，错误最多 2 KiB，连同结构化字段保持在 256 KiB 工具结果上限内。
+- 模型用量逐事件归属父请求和 `childRunId`，不能只算入父模型最后一轮。
+- 子级失败和取消返回结构化终态及部分输出，让父模型决定下一步。
+
+### 7.4 领域持久化
+
+当前 `SubagentService` 为历史专家流程创建隐藏 Child Task。新编程 Subagent 不复制该行为：
+
+- 运行身份使用内部 `childRunId`。
+- 父消息通过现有 `subagent` 活动块保存终态和结果摘要。
+- 若通用 Job/Subjob 表已经实现，则记录为所属父 Task/请求的 Subjob/Run。
+- 若通用 Job/Subjob 表尚未实现，首版只保存现有消息活动和模型用量，不先创建另一套持久
+  子任务表、恢复日志或兼容读取器。
+
+可以提取现有 Scheduler、事件归并和用量转发逻辑，但不能把旧数据库字段当成新的产品模型。
+
+## 8. ModelToolProvider 接入
+
+`ModelToolCallContext` 增加不可伪造的运行上下文：
+
+```ts
+type ModelToolCallContext = {
+  conversationId: string
+  requestId: string
+  runtimeTarget: 'model'
+  workMode: 'ask' | 'execute'
+  executionSpaceIdentity: string
+  delegationDepth: 0 | 1
+  knowledgeCapabilityToken?: string
+}
+```
+
+要求：
+
+- `listTools` 根据模式、执行空间能力和深度生成快照。
+- `getApproval` 不为两个工具创建第二套逐次确认；沿用父 Execute 授权和现有通道工具策略。
+- `callTool` 再次检查 `runtimeTarget`、模式、执行空间 identity、深度和请求是否活动。
+- `releaseConversation` 取消并释放该会话拥有的浏览器、Subagent 和进程。
+- `dispose` 等待有界清理，不因模型或子进程不响应而阻塞应用退出。
+
+DeepSeek Harness 的 Main 工具代理必须使用仅包含分配 MCP 和 Web 的 Provider 视图，不能因为
+共享 `ModelToolProvider` 类而自动看到直连模型编程工具。
+
+## 9. 事件与活动
+
+### 9.1 进程事件
+
+继续使用现有 Runtime `tool` 事件：
+
+- `pending`：参数已接收。
+- `running`：Shell 已成功启动。
+- `completed`：返回 exit 0 或非零退出结果。
+- `failed`：启动或契约失败。
+- `cancelled`：父请求取消。
+
+结果摘要包含 Shell、工作目录、退出码、耗时和截断标记。完整有界 stdout/stderr 进入工具
+输出字段，不写应用诊断日志。
+
+### 9.2 Subagent 事件
+
+复用现有 `subagent` 公开事件和消息块，增加 `routingMode: 'native'` 表示模型主动委派。
+`expertId` 不再作为编程 Subagent 必填身份；共享 schema 应改为执行者 discriminated union，
+而不是伪造一个专家记录：
+
+```ts
+type SubagentActor =
+  | { kind: 'expert'; expertId: string; expertName: string }
+  | { kind: 'direct-model'; label: '编程 Subagent' }
+```
+
+迁移只需让读取器接受旧专家事件和新联合类型，不重写既有消息。
+
+## 10. 错误处理
+
+| 情况 | 结果 |
+| --- | --- |
+| 命令非零退出 | 正常 `ProcessExecuteResult` |
+| 命令不存在 | Shell 非零退出及 stderr |
+| Shell 无法启动 | 工具失败 |
+| cwd 无效或越界 | 工具调用前失败 |
+| 超时/取消 | 终止进程树，返回已有输出和原因 |
+| 直连模型瞬时网络错误/请求超时，尚无可见输出 | 500 ms、1 s、2 s 退避，最多自动重试 3 次 |
+| 直连模型失败，已有文本或推理输出 | 保留部分输出并失败，不自动重放 |
+| 子级模型失败 | 返回 `failed`、部分输出和错误 |
+| 子级工具失败 | 由子模型处理；最终无法完成时返回子级失败 |
+| 父请求已终止 | 拒绝新调用，丢弃迟到内容并清理 |
+
+不要用宽泛 catch 抹掉取消、超时、Provider HTTP 状态或进程退出上下文。
+
+模型请求重试由 `ModelAgentRuntime` 的统一流式请求处理，覆盖普通问答、工具轮次和复用
+同一 Runtime 的上下文摘要。重试分类检查错误及有界 `cause` 链中的 Node/Undici 网络错误
+码；每次尝试创建独立超时信号。退避等待监听父请求取消。只有完整模型轮次返回后才执行
+工具，因此未产生可见文本或推理内容的重试不会重复执行工具。
+
+模型回复本身不设固定字节上限：流式响应、非流式回复、模型工具参数、请求上下文和工具
+结果总量都由请求超时、取消和上下文压缩控制，长回复和大工具结果不会被中断。图像生成
+响应仍按可解码图片大小校验。
+
+## 11. 性能
+
+- Shell 探测按执行服务实例缓存，不在每轮模型调用重复探测。
+- stdout/stderr 边读边界定，避免大日志进入内存后再截断。
+- 子级共享父请求已解析的模型配置和工具服务，不复制 MCP 配置或持久状态。
+- 不增加持久 Shell、后台 daemon、工作区快照或恢复状态机。
+- 命令执行不使用 PTY，避免普通构建和测试承担终端渲染成本。
+
+## 12. 测试策略
+
+### 12.1 单元测试
+
+- 工具可见性矩阵和 Runtime target 过滤。
+- Ask 伪造进程调用拒绝。
+- Windows PowerShell、POSIX Bash/Sh 选择和参数。
+- cwd 默认、相对子目录、绝对路径、工作区外目录、指向外部的符号链接和不存在的目录。
+- exit 0、非零退出、spawn 失败、超时、取消和输出截断。
+- 环境筛选、本机工具 PATH 优先且模型凭据不进入进程。
+- 子级模式、模型、项目、执行空间和能力继承。
+- 深度 1 过滤、并发 3、队列 20、取消传播和部分输出。
+- 编程 Subagent 不创建 Task/Conversation。
+- DeepSeek Harness/OpenCode/Continue 不获得本功能工具。
+- TLS 建连 `ECONNRESET`、Undici 连接超时、单次请求超时、三次重试上限和退避取消。
+- 已产生文本或推理增量后发生网络错误时不自动重放。
+
+### 12.2 本机集成测试
+
+- Windows PowerShell 创建临时文件、运行 Node/Python、非零退出和进程树取消。
+- macOS/Linux Bash/Sh 执行相同场景。
+- 直连模型工具循环执行“修改 → 测试失败 → 修复 → 测试通过”。
+- 父模型委派子级修改或验证专用临时项目，并正确综合结果。
+- Runtime 切换后工具清单刷新且没有重复 Shell。
+- 应用退出后无残留 GoodBuddy 命令进程。
+
+所有测试只在专用临时工作区创建文件，不删除或覆盖用户工作。
+
+### 12.3 真实模型验证
+
+使用一个最小真实直连文本模型请求：
+
+1. Execute 创建一段有缺陷的小程序。
+2. 调用进程工具运行聚焦测试并观察失败。
+3. 修改程序并再次运行到通过。
+4. 委派一个 Subagent 检查实现或补充测试。
+5. 父模型读取子级结果并给出最终结论。
+
+每个平台一次完整场景即可，不进行批量或高成本调用。记录准确模型调用次数，不记录 API Key。
+
+### 12.4 项目验证
+
+源码完成后运行：
+
+```text
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+跨平台进程实现必须由 Windows、macOS、Linux x64 和 Linux arm64 CI 验证。首版不改变
+GoodBuddy Agent 或桌面到 Agent 生产路径，因此不要求远端 Host 验证；未来增加远端 executor
+时必须按远程主机技术设计执行共享 Linux Host 真机验证。
+
+## 13. 实施顺序
+
+1. Shared 工具摘要、schema 和 Runtime target 过滤。
+2. 本机 Shell 探测、进程执行、输出边界和进程树取消。
+3. `ModelToolProvider` Execute 接入及 UI 活动。
+4. 编程 Subagent 服务、过滤 Provider、事件和用量。
+5. 设置能力目录与状态诊断。
+6. 三平台真实命令、真实模型和完整项目验证。
+
+每一步都必须保持直连模型正常问答可用；Shell 不可用不能阻止普通对话。

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

@@ -0,0 +1,136 @@
+# 直连模型 Agent 能力 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.3 |
+| 日期 | 2026-09-03 |
+| 设计系统 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
+| 关联 PRD | [PRD](./prd.md) |
+| 关联逻辑 | [功能逻辑设计](./logic-design.md) |
+
+## 1. 信息架构
+
+本功能不增加一级页面、Composer 按钮或 Runtime 专属工具栏。用户主要通过三处理解能力：
+
+1. **设置 > MCP > 直连模型**：查看内置编程能力说明。
+2. **聊天消息活动块**：查看命令和 Subagent 的实时状态与结果。
+3. **运行记录**：按当前 Conversation 或 Task 查看聚合执行活动。
+
+Job、Subjob 和 Run 继续是内部对象，不创建树形 UI、独立路由或操作菜单。
+
+## 2. 设置中的能力目录
+
+在现有直连模型工具目录增加“编程能力”分组：
+
+```text
+编程能力
+  进程执行
+  使用当前用户权限运行 PowerShell、Bash 或 Sh 命令，默认在工作区执行，也可指定其他工作目录。
+  编程 Subagent
+  将聚焦任务委派给同一模型连接；继承当前工作模式和工作区。
+```
+
+要求：
+
+- 两项默认属于直连模型，不提供持久 Switch。
+- 设置目录只定义稳定工具能力，不增加 Shell 状态或重试控件；实际 Shell 标签在模型工具
+  定义和进程结果中返回。
+- Runtime 是 OpenCode、Continue 或 DeepSeek Harness 时，不在其原生能力清单中伪造这两项；
+  用户需要理解差异时，在直连模型分组说明“Agent Runtime 使用自身工具”。
+- 不把模型配置检查成功描述为命令或 Subagent 已经通过真实执行验证。
+
+## 3. 进程活动块
+
+复用现有对话工具活动视觉和语义，不创建页面专属卡片系统。
+
+### 3.1 标题与摘要
+
+```text
+进程执行
+PowerShell · packages/app · npm test
+```
+
+- 命令只显示单行有界摘要，完整参数进入可展开详情。
+- 工作区内目录显示相对路径，工作区根显示 `.`；工作区外目录显示规范化绝对路径。
+- 不在摘要中显示完整环境或凭据。
+
+### 3.2 状态
+
+| 状态 | 文案 |
+| --- | --- |
+| pending | 等待运行 |
+| running | 正在运行 |
+| completed，exit 0 | 已完成 |
+| completed，exit 非零 | 工具已完成，详情显示退出码 N |
+| timeout | 工具已完成，详情显示 timeout |
+| cancelled | 父请求活动显示已取消 |
+| failed | 启动失败 |
+
+状态必须同时有文字和状态图标，不能只依靠颜色。非零退出属于正常结构化工具结果，不显示为
+GoodBuddy 服务崩溃。
+
+### 3.3 结果详情
+
+详情按以下顺序展示：
+
+1. Shell、工作目录、耗时和退出码。
+2. stdout。
+3. stderr。
+4. 截断提示。
+
+日志使用共享等宽字体和可选择文本。长输出在活动块内折叠，展开后仍保持工作栏和聊天布局
+可用；不把完整日志复制为应用通知。
+
+## 4. Subagent 活动块
+
+复用现有 `subagent` 消息块，并将系统执行者显示为“编程 Subagent”，不要求用户预先创建
+专家。
+
+```text
+编程 Subagent
+检查认证模块的测试失败并提出修复
+正在运行 · 直连模型 · Execute
+```
+
+终态：
+
+- 完成：显示有界结果摘要，可展开查看完整返回。
+- 失败：保留部分输出和错误。
+- 取消：显示“父请求已取消”或准确取消原因。
+- 排队：显示当前处于并发队列，不显示虚假百分比。
+
+活动块不提供单独的“批准”“提高权限”或“继续递归”按钮。用户取消父请求即可取消子级。
+
+## 5. Ask/Execute 表达
+
+- Ask 中不显示不可用的进程按钮，因为模型工具没有手动调用入口。
+- Ask Subagent 活动明确显示“只读”。
+- Execute 活动显示“当前用户权限”，不声称 OS 沙箱或工作区隔离。
+- 如果用户从 Ask 切到 Execute，只有下一条请求使用新模式；运行中的 Subagent 不切换。
+
+## 6. 错误与通知
+
+- 参数错误、命令退出、Subagent 失败和部分输出属于当前活动上下文，保留在对应活动块。
+- Runtime 初始化、Shell 探测或全局服务失败可通过应用通知提示，并在设置状态卡提供重试。
+- 同一错误不同时显示活动块副本和通知副本。
+- 失败后保留用户 Prompt、命令摘要、工作目录和已有输出。
+- 直连模型自动重试通过现有聊天状态显示“模型网络请求失败，正在重试（n/3）”，不增加
+  独立按钮、弹窗或通知副本；用户仍可使用当前停止操作取消请求。
+
+## 7. 键盘与无障碍
+
+- 活动块展开按钮使用原生 `button`，提供 `aria-expanded` 和关联详情 ID。
+- 状态变化通过现有活动区域的礼貌级 live region 发布，不逐个朗读流式日志。
+- stdout/stderr 区域具有可见标签，不能只靠顺序区分。
+- 焦点不会因后台状态更新自动移动。
+- 取消父请求后的焦点保持在原取消按钮或恢复到 Composer。
+- 浅色、深色和减少动态效果模式遵守统一设计系统。
+
+## 8. 响应式
+
+- 窄聊天区只保留工具名、状态和一行摘要，元数据换行到下一行。
+- 日志区域横向滚动，不撑宽页面。
+- 运行记录使用紧凑摘要，不复制完整 stdout/stderr；用户回到聊天活动块展开查看详情。

docs/features/direct-model-agent/user-stories.md

@@ -0,0 +1,177 @@
+# 直连模型 Agent 能力 User Stories
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台 CI 待验证 |
+| 版本 | 0.3 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [直连模型 Agent 能力 PRD](./prd.md) |
+| 关联逻辑 | [功能逻辑设计](./logic-design.md) |
+
+## 1. 角色
+
+### 1.1 普通项目用户
+
+希望模型直接完成脚本、文档生成或数据处理，不关心不同平台的 Shell 名称。
+
+### 1.2 开发者
+
+希望直连模型能够修改代码、运行测试、检查 Git 状态并根据失败结果继续修正。
+
+### 1.3 Runtime 用户
+
+已经使用 OpenCode、Continue 或 DeepSeek Harness，希望继续使用 Runtime 原生能力，不看到
+重复的 GoodBuddy Shell 或 Subagent。
+
+## 2. Epic A：跨平台执行
+
+### US-A1 在 Windows 运行项目命令
+
+关联：FR-2、FR-3、FR-4。
+
+Given 当前项目位于 Windows 本机且选择直连模型 Execute，When 模型调用
+`process_execute`，Then GoodBuddy 使用可用 PowerShell 在项目目录运行命令，并返回
+Shell、目录、退出码、输出和耗时。
+
+### US-A2 在 macOS/Linux 运行项目命令
+
+关联：FR-2、FR-3。
+
+Given 当前项目位于 macOS 或 Linux 本机，When 模型运行同一工具，Then GoodBuddy 使用
+Bash，Bash 不可用时使用 Sh，工具契约保持不变且实际 Shell 明确可见。
+
+### US-A3 选择命令工作目录
+
+关联：FR-3。
+
+Given 当前请求为本机 Execute，When 模型传入绝对路径或相对工作区路径，Then 命令在
+解析后的目录执行，包括工作区外目录和符号链接目标，And 后续省略 `cwd` 时仍使用原工作区。
+When 目标不是目录或不存在，Then 命令不启动并返回准确错误。
+
+### US-A4 根据非零退出继续修正
+
+关联：FR-2、FR-9。
+
+Given 测试命令退出码非零，When 进程结束，Then 工具正常返回退出码和 stderr，而不是终止
+整个模型请求，And 模型可以读取失败原因、修改代码并再次运行。
+
+### US-A5 取消长命令
+
+关联：FR-7。
+
+Given 命令仍在运行，When 用户取消父请求，Then 当前 Shell 及其由本次命令创建的子进程树
+停止，And 活动状态显示“已取消”，And 其他用户进程不受影响。
+
+### US-A6 看懂截断结果
+
+关联：FR-7、FR-9。
+
+Given 命令输出超过上限，When 工具返回结果，Then 保留有用的开头和结尾并明确
+`truncated: true`，And 模型与用户都不会把结果理解为完整日志。
+
+### US-A7 从瞬时模型网络故障恢复
+
+关联：FR-7、FR-9、FR-11。
+
+Given 直连模型在 TLS 建连、网络传输或单次请求超时时失败且尚未显示输出，When 请求仍未
+取消，Then GoodBuddy 显示当前重试次数并使用递增等待时间最多重试 3 次，And 成功后继续
+原问答或工具轮次。Given 已经显示文本或推理内容，Then 不自动重放该调用。
+
+## 3. Epic B：编程闭环
+
+### US-B1 修改后运行验证
+
+关联：FR-2、FR-4。
+
+Given 用户选择 Execute 并要求修复代码，When 直连模型修改文件，Then 它可以运行聚焦测试
+或检查命令，并根据真实结果继续修改，直到给出完成或阻塞结论。
+
+### US-B2 使用本机工具环境
+
+关联：FR-8、FR-10。
+
+Given 用户选择了 GoodBuddy 托管或自定义 Node/Python，When 新命令调用 `node`、`npm`、
+`npx`、`python` 或 `pip`，Then 它们解析到当前工具环境，And 不修改系统 PATH 或已有终端。
+
+### US-B3 依赖或命令不存在
+
+关联：FR-2、FR-9。
+
+Given 项目缺少所需命令或依赖，When Shell 返回错误，Then 工具保留退出码和错误文本，
+And 模型说明缺失项或在 Execute 中采取用户要求的安装步骤，不把环境缺失报告为模型故障。
+
+## 4. Epic C：Subagent 委派
+
+### US-C1 委派聚焦编程任务
+
+关联：FR-5、FR-6。
+
+Given 父直连模型正在处理复杂请求，When 它调用 `subagent_delegate` 并给出独立任务，
+Then 子级使用同一项目、模型连接和 Execute 能力完成工作，And 最终结果返回父模型综合。
+
+### US-C2 Ask 中只读委派
+
+关联：FR-4、FR-5。
+
+Given 父请求为 Ask，When 模型委派分析任务，Then 子级保持 Ask，不能写文件或运行命令，
+And 不因 Subagent 存在而扩大权限。
+
+### US-C3 禁止递归委派
+
+关联：FR-5、FR-7。
+
+Given 子级正在执行，When 它读取自己的工具清单，Then 清单中没有
+`subagent_delegate`，And 子级不能创建孙级任务。
+
+### US-C4 子级失败后父级继续
+
+关联：FR-5、FR-9。
+
+Given 子级运行期间失败或超时，When 子任务结算，Then 父模型收到失败状态、部分输出和
+有界错误，And 可以自行继续、改变方案或向用户说明阻塞。
+
+### US-C5 取消传播
+
+关联：FR-7。
+
+Given 一个 Subagent 正在运行模型或命令，When 用户取消父请求，Then 排队和运行中的子级
+全部取消，当前命令进程树停止，And 不再向父请求追加迟到结果。
+
+### US-C6 保持产品对象简单
+
+关联：FR-6。
+
+Given 直连模型完成一次委派，When 用户查看会话、Task Center 和活动，Then 会话内可看到
+Subagent 状态与结果摘要，And Task Center 不出现新的子 Task，And UI 不展示 Job/Run 树。
+
+## 5. Epic D：Runtime 与执行空间边界
+
+### US-D1 Agent Runtime 不重复获得工具
+
+关联：FR-1、FR-10。
+
+Given 用户选择 OpenCode、Continue 或 DeepSeek Harness，When Runtime 启动，Then
+GoodBuddy 不注入 `process_execute` 或 `subagent_delegate`，And Runtime 原生能力保持不变。
+
+### US-D2 切换 Runtime 后工具清单更新
+
+关联：FR-1。
+
+Given 会话从直连模型切换为 Agent Runtime，When 下一次请求开始，Then 新请求只使用目标
+Runtime 的能力；切回直连模型时重新获得符合工作模式的直连工具。
+
+### US-D3 不在错误设备执行
+
+关联：FR-3。
+
+Given 当前执行空间是 SSH 且远端进程后端尚不可用，When 解析工具清单，Then 不注册
+`process_execute`；即使调用参数有效，也不能回退到桌面本机执行。
+
+### US-D4 消息通道使用相同规则
+
+关联：FR-1、FR-4。
+
+Given 消息通道项目选择直连模型，When 合法消息触发 Ask 或 Execute，Then 使用与桌面会话
+相同的工具矩阵和通道既有工具策略，不维护第二套 Shell 能力配置。

docs/features/document-processing/README.md

@@ -0,0 +1,11 @@
+# 文档处理
+
+文档处理负责聊天附件和知识库导入中的文本提取、格式转换与本地 OCR。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [文档解析与本地 OCR PRD](./prd.md) | 产品范围、解析策略、OCR 模型管理和验收 |
+
+当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。

docs/features/document-processing/prd.md

@@ -9,6 +9,8 @@ GoodBuddy 需要用同一条可信文档解析链路服务以下场景：
 - 后续的合同审阅、表格分析、演示文稿理解和文档转换。
 
 文档解析不是对话模型的附属功能。它是主进程管理的独立基础能力，设置入口为“设置中心 / 文档解析”。
+本地 OCR 的模型下载源以
+[平台功能页签与模型下载源设计](../../architecture/model-download-source-design.md)为准。
 
 ## 2. 当前基线
 
@@ -72,11 +74,12 @@ PDF 不是所有文档唯一的中间格式。解析应同时保留：
 OCR 模型区沿用语音模型管理模式：
 
 - 应用不内置模型权重；
-- 用户按需从 ModelScope 下载，下载完成后离线使用；
+- 用户按需从全局选择的 ModelScope 或 Hugging Face 下载，默认 ModelScope，下载完成后
+  离线使用；
 - 显示来源、语言、运行时、模型体积、安装与校验状态；
 - 联网设备可导出已安装模型 ZIP，离线或内网设备可直接导入；
 - 支持下载进度、取消、删除、ZIP 导入导出、打开模型仓库和受管目录；
-- “打开 ModelScope”直接显示在 OCR 模型卡片右上角，不使用手动导入折叠区；
+- “打开模型仓库”直接显示在 OCR 模型卡片右上角，并使用当前下载源对应仓库；
 - 模型操作即时生效，解析策略仍通过分类页头的“保存设置”提交。
 
 ### 4.1 第一阶段字段
@@ -182,11 +185,16 @@ type ParsedDocument = {
 
 ### 7.2 下载与安装
 
-Tiny、Small 和 Medium 模型均由 PaddlePaddle 官方 ModelScope 仓库提供。Small 是默认推荐档位；Medium 面向更高识别质量，但具有更高内存占用和延迟。每个档位的检测模型、识别模型与字符字典配置分别使用固定提交，并在应用内记录文件字节数和 SHA-256。
+Tiny、Small 和 Medium 模型使用 PaddlePaddle 发布的规范工件。GoodBuddy 为 ModelScope
+和 Hugging Face 分别维护固定下载 Target，默认使用 ModelScope。Small 是默认推荐档位；
+Medium 面向更高识别质量，但具有更高内存占用和延迟。每个档位的检测模型、识别模型与
+字符字典配置分别使用固定提交，并在应用内记录各来源解析后的文件字节数和 SHA-256。
+当前 OCR 两个来源的对应文件字节一致；共享下载契约同时支持后续来源声明不同的固定
+工件指纹。
 
 下载流程：
 
-1. 主进程从固定 ModelScope `resolve/<revision>/...` 地址读取文件；
+1. 主进程读取已保存的全局模型下载源，并解析该来源的固定 Target；
 2. 禁用凭据与缓存，限制重定向次数和单文件大小；
 3. 写入受管目录下的随机临时安装目录；
 4. 边下载边计算 SHA-256，并核对完整字节数；
@@ -194,7 +202,9 @@ Tiny、Small 和 Medium 模型均由 PaddlePaddle 官方 ModelScope 仓库提供
 6. 原子重命名为正式模型目录；
 7. 失败、取消或退出时删除临时文件。
 
-模型只在下载或用户显式打开仓库时访问网络。OCR 推理从受管目录读取已校验文件，不发起网络请求。
+单次任务只使用启动时冻结的一个来源。所选来源不可用或缺少任一必需文件时明确失败，
+不请求另一个来源。模型只在下载或用户显式打开仓库时访问网络。OCR 推理从受管目录读取
+已校验文件，不发起网络请求。
 
 ### 7.3 离线 ZIP 迁移
 
@@ -213,7 +223,7 @@ ZIP 根目录包含模型文件和 `goodbuddy-model.json`。清单格式为 `goo
 - 文件名、角色、原始字节数和 SHA-256；
 - 导出时间。
 
-导出不能直接信任已有安装清单，必须重新读取并校验每个文件。导入不能只信任 ZIP 自声明内容，模型 ID、文件角色、字节数和哈希必须再次与当前应用内置目录完全匹配。导入通过后复用普通本地安装的受控临时目录和原子重命名路径。
+导出不能直接信任已有安装清单，必须重新读取并校验每个文件。导入不能只信任 ZIP 自声明内容，模型 ID、文件角色、字节数和哈希必须再次完整匹配当前应用内置目录的默认包或任一来源包；不接受逐文件跨来源组合。导入通过后复用普通本地安装的受控临时目录和原子重命名路径。
 
 归档处理使用有界流式读写，不把大型模型或整个展开结果复制到内存。主进程限制压缩包大小、条目数、清单大小、单文件大小和总展开大小，并拒绝：
 
@@ -298,7 +308,8 @@ DOC、XLS、PPT 通过 `DocumentConversionProvider` 转换：
 - 新增文档解析设置分类和持久化契约；
 - 建立 `DocumentParsingService`，供聊天和知识库共用；
 - 将无文本 PDF 识别为可触发 OCR 的明确状态；
-- 接入 PP-OCRv6 Tiny、Small、Medium 的 ModelScope 下载、校验、ZIP 离线迁移、删除与 WASM Worker；
+- 接入 PP-OCRv6 Tiny、Small、Medium 的双来源下载、校验、ZIP 离线迁移、删除与
+  WASM Worker；
 - 实现真实文件测试和六平台验证入口。
 
 ### 阶段二
@@ -322,7 +333,8 @@ DOC、XLS、PPT 通过 `DocumentConversionProvider` 转换：
 - 模型文件损坏时拒绝加载并显示可恢复错误；
 - 未安装模型时扫描文档提示用户前往“文档解析”下载，文本型文档仍可原生解析；
 - 下载中可显示文件与总进度并允许取消，失败或取消后不留下已安装状态；
-- ModelScope 下载与 ZIP 导入均经过同一大小和 SHA-256 校验；
+- ModelScope、Hugging Face 下载与 ZIP 导入均经过同一大小和 SHA-256 校验；
+- 所选下载源失败或缺少模型时不会请求另一个来源；
 - 语音和 OCR 模型可在联网设备导出 ZIP，并在离线设备导入后完成真实推理；
 - 路径穿越、未知条目、错误模型 ID、篡改文件和超限 ZIP 均被拒绝；
 - 超页数、超时、取消和关闭不会留下运行任务；

docs/features/full-duplex-voice/README.md

@@ -0,0 +1,11 @@
+# 全双工语音
+
+全双工语音定义持续听说、打断、语音活动检测、本地与远端推理以及多平台音频边界。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [技术设计](./technical-design.md) | 产品目标、交互流程、音频架构、模型、打包和实施状态 |
+
+现有文档是综合设计，尚未按 PRD、User Stories、功能逻辑、UI 和进度职责拆分。

docs/features/full-duplex-voice/technical-design.md

@@ -0,0 +1,944 @@
+# GoodBuddy 全双工实时语音交互设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档类型 | 跨功能技术与产品架构 |
+| 状态 | 设计中 |
+| 版本 | 0.1 |
+| 日期 | 2026-08-19 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 相关基线 | [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md)、[统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文定义 GoodBuddy 中类似自然通话的全双工实时语音能力，包括本地与云端语音引擎、
+音频平面、会话状态、打断语义、工具审批、数据留存、失败恢复、跨平台交付和验收指标。
+
+本文所称“支持本地与云端”是指用户可以显式配置并选择不同语音引擎，不代表系统可以在
+它们之间自动切换。**GoodBuddy 不设计静默降级。**
+
+---
+
+## 1. 摘要与核心决策
+
+1. 实时语音是独立的 `VoiceSession`，不把现有一次性语音听写改名后直接复用。
+2. 系统支持三种显式引擎：
+   - 本地模块化全双工：本地流式 ASR、所选 Agent Runtime、本地流式 TTS。
+   - 本地原生全双工：一个本地端到端语音模型同时听、想和说。
+   - 云端原生全双工：通过供应商 Realtime/Live API 进行双向流式音频交互。
+3. 用户开始会话时冻结引擎、Provider、模型、版本、地域、数据位置、声音、能力和
+   Turn Detection 配置。会话过程中不得静默替换。
+4. 同一目标内允许有界重试、网络抖动恢复和语义等价的内部执行优化；任何会改变
+   Provider、模型、数据位置、成本、隐私、能力、质量或可感知延迟的替代路径都必须显式。
+5. 所选引擎不可用时，会话明确进入 `blocked` 或 `failed`，保留可恢复上下文，并提供
+   “重试当前引擎”或“结束后选择其他引擎”。不自动切换本地/云端，不退回听写、纯文本或
+   非全双工模式。
+6. Renderer 负责麦克风采集、回声消除、低延迟播放和即时打断；Main 负责凭据、会话
+   控制、Provider Adapter、工具权限、持久化和资源回收。
+7. 音频帧不进入普通 `AgentEvent` 和聊天消息持久化通道。默认只保存最终文本、会话状态和
+   有界诊断，不保存原始录音。
+8. 语音不能成为新的授权通道。Ask 继续只读，Execute 的工具调用继续经过现有审批控件。
+
+---
+
+## 2. 背景与当前基础
+
+GoodBuddy 当前已经具备：
+
+- Renderer 中的麦克风入口、录音状态和取消操作。
+- `getUserMedia` 的单声道采集、回声消除和噪声抑制。
+- 将完整录音重采样为 16 kHz PCM 的能力。
+- 基于 `sherpa-onnx` 的本地离线识别、模型下载、ZIP 迁移、选择和删除。
+- Main 中受信任发送者校验、Zod IPC 输入校验、超时、取消和应用关闭回收。
+- `AgentRuntime.run()` 的流式文本、工具事件、审批、取消和会话持久化。
+- Renderer 中的流式聊天时间线、全局通知和可访问的输入控件。
+
+当前链路仍是：
+
+```text
+点击麦克风
+→ 最多录音 20 秒
+→ 停止并一次性发送完整 PCM
+→ 本地离线转写
+→ 把文本插入输入框
+→ 用户再次确认发送
+```
+
+该链路适合听写，但不具备：
+
+- 连续流式识别和临时转写。
+- 同时采集与播放。
+- 自动轮次检测。
+- 助手语音输出。
+- 用户抢话和响应截断。
+- 音频队列、背压和时钟同步。
+- 实时语音 Provider 抽象。
+- 语音会话快照和诊断。
+
+因此实时语音必须新增会话层，而不是在现有 `SpeechTranscriptionService` 后面简单追加 TTS。
+
+---
+
+## 3. 目标
+
+### 3.1 用户目标
+
+- 用户可以像通话一样持续说话，不需要每轮点击开始和停止。
+- 助手可以边生成边说，并显示与实际播放进度一致的文本。
+- 用户开口时可以自然打断，助手在很短时间内停止出声并开始听取新内容。
+- 用户始终知道当前使用本地还是云端、具体引擎是什么、音频或转写文本会去哪里。
+- 本地或云端引擎失败时，用户能看到准确状态并决定下一步，不被系统暗中换模型。
+- 语音对话继续拥有文本聊天中的项目、知识库、角色、Ask/Execute、工具审批和历史能力。
+
+### 3.2 产品目标
+
+- 在六个平台/架构目标上提供统一的上层会话契约。
+- 先以现有 `sherpa-onnx` 和 Agent Runtime 构建可跨平台交付的本地模块化引擎。
+- 允许云端 Provider 使用 WebRTC 或 WebSocket，但不把供应商协议泄漏到通用 UI。
+- 允许高性能设备安装本地原生全双工模型，但按真实能力检测决定是否可选。
+- 保持 Main-only 凭据、上下文隔离、沙箱、取消、超时、有界输出和关机回收。
+- 为延迟、打断、回声、音频中断、Provider 错误和成本提供可诊断指标。
+
+---
+
+## 4. 非目标
+
+首期不包含：
+
+- 唤醒词、后台常驻监听或应用退出后的麦克风采集。
+- 根据网络、负载、价格或“智能判断”自动选择语音引擎。
+- 在一个会话内自动从云端切到本地，或从本地切到云端。
+- 从原生全双工自动退到 ASR → LLM → TTS，或反向切换。
+- 在实时语音失败后自动改成一次性听写、纯文本发送或系统 TTS。
+- 默认保存、上传或训练用户原始音频。
+- 声音克隆、未成年人声音模仿、电话呼入或多人会议。
+- 使用口头“同意”替代工具审批按钮或键盘确认。
+- 绕过当前 Agent Runtime 和权限边界的 Provider 直连工具、MCP 或 Connector。
+- 保证所有本地原生语音模型都能在 CPU 或全部六个发布目标上运行。
+
+---
+
+## 5. 术语与全双工范围
+
+| 术语 | 定义 |
+| --- | --- |
+| `VoiceEngineProfile` | 用户保存的语音引擎配置，包含类型、Provider、模型、地域、声音和能力 |
+| `VoiceSession` | 一次从用户显式开始到结束的连续实时语音会话 |
+| `VoiceTurn` | 用户输入和助手响应形成的一次可持久化对话轮次 |
+| 系统级全双工 | 麦克风在助手播放期间继续采集，用户可以随时打断 |
+| 原生模型全双工 | 同一个模型联合处理持续输入、轮次判断和持续语音输出 |
+| 模块化全双工 | ASR、Agent Runtime 和 TTS 分离，但系统保持同时听说与可打断 |
+| 临时文本 | 尚未确认的 ASR 或尚未实际播放的助手文本，不写入长期历史 |
+| 已提交文本 | 用户轮次已确认，或助手对应音频已实际播放的文本 |
+| Barge-in | 用户在助手说话时开口，触发立即静音、取消和上下文截断 |
+| 引擎快照 | 会话开始时冻结的完整、无凭据配置及能力声明 |
+
+“模块化”不等同于“回退”。当用户明确选择模块化本地引擎时，它就是该会话的唯一正式
+执行路径。原生模型和模块化引擎之间没有隐式优先级。
+
+---
+
+## 6. 不静默降级产品契约
+
+### 6.1 必须显式的变化
+
+以下变化不得在活动会话中静默发生：
+
+- 本地与云端之间切换。
+- Provider、Endpoint、地域或账号切换。
+- 模型 ID、模型版本、量化档位或语音角色切换。
+- 原生全双工与模块化全双工之间切换。
+- ASR、LLM 或 TTS 组件切换。
+- 从音频输入改成仅文本输入，或从语音输出改成仅文本输出。
+- 禁用原本声明可用的工具、知识库、角色或 Execute 能力后继续运行。
+- 把原始音频改为上传，或改变云端数据地域和保留策略。
+- 采用明显更慢、更低质量或成本不同的路径。
+
+### 6.2 可自动进行的恢复
+
+以下操作可以自动执行，但必须保持同一引擎快照：
+
+- 同一连接内的丢包恢复、抖动缓冲和音频重排。
+- 同一 Provider、模型、地域和配置的有限重连。
+- 同一本地模型进程的有限重启。
+- 不改变语义、隐私、成本和已声明性能级别的算子或执行 Provider 优化。
+
+恢复在用户可感知前完成时可不打断界面；持续超过 500 ms、导致音频停顿或创建新远端
+会话时，必须显示“正在重新连接当前引擎”。所有恢复都进入有界诊断记录。
+
+### 6.3 失败后的用户决策
+
+恢复预算耗尽后：
+
+1. 停止采集上传和音频播放。
+2. 将临时文本标记为未提交，不伪装成完整轮次。
+3. 保存已提交文本和脱敏错误。
+4. 显示当前失败的引擎、影响和建议。
+5. 提供“重试当前引擎”和“结束语音会话”。
+6. 用户结束后可以显式选择其他引擎并开始新会话。
+
+首期不提供自动 Failover 列表。未来即使允许用户预先配置替代引擎，也必须在切换前获得
+明确确认，并在会话中持续显示新的活动引擎。
+
+### 6.4 产品级适用范围
+
+本契约不仅适用于语音。GoodBuddy 中 Provider、模型、Runtime、数据处理位置、工作模式、
+权限范围和质量档位等影响隐私、成本或能力的用户选择，都不得被静默替换。
+
+用户明确选择名为“自动”的策略时，系统可以在该策略事先声明的范围内选择，但实际结果和
+任何能力退化必须可见、可诊断，不能把空结果或不完整结果表示为正常成功。
+
+---
+
+## 7. 用户体验
+
+### 7.1 入口
+
+现有麦克风入口继续表示“语音输入/听写”，转写进入可编辑输入框，不自动发送。
+
+实时语音使用独立的“开始语音对话”入口，避免用户误以为点击一次听写会开启持续监听。
+入口只在以下条件满足时可用：
+
+- 已选择并验证一个全双工语音引擎。
+- 当前平台满足该引擎能力要求。
+- 麦克风权限可申请。
+- 当前 Conversation 没有冲突的活动请求。
+- 当前工作模式和引擎能力兼容。
+
+### 7.2 会话界面
+
+活动会话显示一个持续可见的语音控制区：
+
+- 当前状态：准备中、正在听、用户说话、正在思考、助手说话、正在打断、等待审批、
+  正在重连、失败。
+- 本地/云端徽标、引擎名称和数据去向。
+- 实时用户转写和与播放同步的助手文本。
+- 麦克风静音、结束会话和必要的设备入口。
+- 输入音量与助手播放状态，但不得只用颜色表达。
+- 云端会话的使用量或成本提示入口。
+
+“结束语音会话”是活动状态下的唯一主操作。波形和头像动效遵守
+`prefers-reduced-motion`，关闭动效后仍使用文字和图标表达状态。
+
+### 7.3 打断
+
+助手说话期间检测到用户有效语音：
+
+1. 在 Renderer 立即对当前音频执行 20–40 ms 淡出。
+2. 清空尚未播放的音频队列。
+3. 向 Main 发送包含播放位置的 `interrupt`。
+4. Main 取消当前 Agent/TTS 响应或向 Provider 发送截断事件。
+5. 尚未播放的助手文本保持临时状态并从会话上下文中移除。
+6. 输入状态切到用户说话，继续采集，不重新建立会话。
+
+键盘点击“停止说话”与语音 Barge-in 使用相同取消和提交语义。
+
+### 7.4 工具和审批
+
+- Ask 模式继续在 Runtime 边界保持只读。
+- Execute 模式的工具调用进入现有 Approval Broker。
+- 等待审批时暂停新的助手音频，可播放一次确定性的短提示，例如“需要你确认一个操作”。
+- 工具参数、风险、范围和确认操作使用现有可访问审批控件。
+- 麦克风中的“同意”“确认”或相似内容只作为普通用户文本，不构成授权。
+- 用户拒绝或取消后，结果作为结构化工具事件返回当前引擎，不私自换模型继续。
+
+### 7.5 设置结构
+
+长期设置结构使用一级“语音”分类，并以 `PageTabs` 组织：
+
+1. **实时对话**：语音引擎列表、默认引擎、能力、数据位置、地域、声音和真实连接测试。
+2. **语音输入**：现有本地 ASR 模型、一次性听写和麦克风设置。
+3. **语音输出**：本地 TTS 模型、声音、语速和试听。
+
+当前“模型连接”中的“语音输入”可在迁移阶段保留，之后移动现有模型管理组件时必须保存
+已安装模型和选择，不创建第二份设置。
+
+模型类型选择器当前已经包含四项，不增加第五个分段项来承载实时语音，以免违反
+`SegmentedControl` 的 2–4 项约束。
+
+语音引擎卡片必须持续显示：
+
+- 本地或云端。
+- Provider、模型和版本。
+- 支持的语言。
+- 系统级或原生模型全双工。
+- 是否支持工具、图像和当前 Ask/Execute 模式。
+- 所需硬件或云端地域。
+- 音频和文本的数据去向。
+- 安装、已验证、不可用或需要凭据状态。
+
+实际生成能力只能通过一次真实、有界、由用户触发的会话测试确认。配置保存成功或只完成
+握手不能证明麦克风输入、语音输出和打断均可工作。
+
+---
+
+## 8. 总体架构
+
+```text
+┌──────────────────────── Renderer ────────────────────────┐
+│ VoiceSession UI                                           │
+│ getUserMedia → AudioWorklet Capture → Fast VAD            │
+│ AudioWorklet Playback ← Jitter/Playback Queue              │
+└────────────── control IPC ─────── media MessagePort ───────┘
+                              │
+┌────────────────────────── Main ────────────────────────────┐
+│ VoiceSessionController                                     │
+│ ├─ Session snapshot and state                              │
+│ ├─ Turn coordinator and interruption                      │
+│ ├─ Tool/approval bridge                                    │
+│ ├─ Transcript/message persistence                         │
+│ ├─ Credential and provider policy                         │
+│ └─ VoiceEngineAdapter                                      │
+│      ├─ LocalModularAdapter                                │
+│      ├─ LocalNativeDuplexAdapter                           │
+│      └─ CloudRealtimeAdapter                               │
+└───────────────┬──────────────────────┬─────────────────────┘
+                │                      │
+        Local managed sidecar     Cloud Realtime API
+        or bounded worker         WebRTC / WebSocket
+```
+
+### 8.1 Renderer 音频平面
+
+Renderer 负责需要接近音频设备的低延迟操作：
+
+- 在用户操作后调用 `getUserMedia`。
+- 请求单声道、回声消除、噪声抑制和受支持时的自动增益。
+- 使用 `AudioWorklet`，不继续扩展 `ScriptProcessorNode`。
+- 将音频切成 10–20 ms 有序帧，并按引擎格式重采样。
+- 执行快速本地 VAD，用于 Barge-in，不独立提交最终轮次。
+- 维护有界播放和抖动缓冲，记录实际播放采样位置。
+- 在打断、设备变化、休眠或窗口销毁时立即静音和释放资源。
+
+Renderer 不持有长期 API Key、不创建本地模型目录、不决定工具权限，也不持久化原始音频。
+
+### 8.2 Preload 与 IPC
+
+控制面使用显式、类型化的 preload 方法：
+
+- `voice.getSnapshot()`
+- `voice.startSession(input)`
+- `voice.stopSession(sessionId)`
+- `voice.setMuted(input)`
+- `voice.interrupt(input)`
+- `voice.respondApproval(...)` 继续复用现有审批接口
+- `voice.onEvent(listener)`
+
+音频帧不使用逐帧 `ipcRenderer.invoke`、JSON 或 Base64。Main 通过
+`MessageChannelMain` 向可信主 Frame 传递专用 `MessagePort`，使用可转移
+`ArrayBuffer` 和严格的帧头。控制事件和媒体帧分别限速、限长和验证。
+
+### 8.3 Main 控制面
+
+`VoiceSessionController` 负责：
+
+- 每个窗口最多一个活动语音会话。
+- 解析并冻结 `VoiceSessionSnapshot`。
+- 建立所选 Adapter，不执行自动 Adapter 选择。
+- 维护输入、输出和生命周期状态。
+- 将 Barge-in 传播到 Provider、Agent Runtime、TTS 和播放队列。
+- 桥接工具调用、审批、问题和取消。
+- 只提交已经确认或实际播放的文本。
+- 处理超时、重连预算、应用退出、系统休眠和窗口销毁。
+- 对错误和诊断执行脱敏与边界限制。
+
+### 8.4 本地进程边界
+
+轻量 ONNX 能力可以运行在受控 Worker。需要 Python、CUDA、Metal/MLX 或独立依赖树的
+原生模型运行在 GoodBuddy 管理的 Sidecar：
+
+- 只绑定 loopback，不监听外部网卡。
+- 使用随机端口和每次启动的短期认证值。
+- 环境变量使用最小 allowlist。
+- 不继承云端 Provider 密钥。
+- 模型路径由 Main 从受管目录解析，不接受任意相对路径。
+- 启动、健康检查、并发、输出、内存、超时和进程树有界。
+- 应用退出时终止完整进程树。
+
+Sidecar 不因本地模型启动失败而自行连接云端。
+
+### 8.5 云端连接边界
+
+供应商支持 WebRTC 时优先使用其媒体传输、编解码和抖动能力：
+
+- Main 使用长期凭据创建受限、短时的会话描述或临时凭据。
+- Renderer 只接收当前会话需要的短期材料。
+- 工具和业务事件优先由 Main sideband 连接处理。
+- Provider 不支持 sideband 时，由 Main 拥有 WebSocket，并通过媒体 `MessagePort`
+  与 Renderer 交换音频。
+
+长期凭据永不进入 Renderer、日志、诊断或会话快照。云端 Profile 必须固定可信 Endpoint、
+地域和数据说明，不跟随重定向切换到未声明的主机。
+
+---
+
+## 9. 共享契约
+
+建议新增 `src/shared/voice-contracts.ts`，核心结构如下：
+
+```ts
+type VoiceEngineKind =
+  | 'local-modular'
+  | 'local-native-duplex'
+  | 'cloud-native-duplex'
+
+type VoiceComponentRef = {
+  providerId: string
+  modelId: string
+  modelVersion?: string
+  endpoint?: string
+  region?: string
+  accountRef?: string
+  credentialRef?: string
+}
+
+type VoiceEngineProfile = {
+  id: string
+  name: string
+  kind: VoiceEngineKind
+  locality: 'local' | 'cloud'
+  voiceId: string
+  components: {
+    asr?: VoiceComponentRef
+    tts?: VoiceComponentRef
+    nativeDuplex?: VoiceComponentRef
+  }
+  dataPath: {
+    audioDestination:
+      | { kind: 'device' }
+      | {
+          kind: 'provider'
+          providerId: string
+          endpoint: string
+          region?: string
+        }
+    transcriptDestination:
+      | { kind: 'device' }
+      | {
+          kind: 'provider'
+          providerId: string
+          endpoint: string
+          region?: string
+        }
+    retentionPolicyId?: string
+  }
+  capabilities: {
+    nativeDuplex: boolean
+    supportsTools: boolean
+    supportsAsk: boolean
+    supportsExecute: boolean
+    inputLanguages: string[]
+    outputLanguages: string[]
+  }
+}
+
+type VoiceRuntimeSnapshot = {
+  selection: Exclude<AgentRuntimeSelection, { provider: 'auto' }>
+  profileRevision?: string
+  configurationDigest: string
+  workspacePath: string
+}
+
+type VoiceSessionSnapshot = {
+  sessionId: string
+  conversationId: string
+  profile: VoiceEngineProfile
+  profileRevision: string
+  engineConfigurationDigest: string
+  runtime?: VoiceRuntimeSnapshot
+  workMode: 'ask' | 'execute'
+  inputFormat: VoiceAudioFormat
+  outputFormat: VoiceAudioFormat
+  turnDetection: VoiceTurnDetectionConfig
+  startedAt: string
+}
+```
+
+`credentialRef` 和 `accountRef` 是不含凭据正文的稳定引用。Endpoint 写入 Profile 或快照前
+必须规范化并删除用户名、密码、查询参数和 Fragment；供应商部署路径仍应保留，以便检测
+Endpoint 是否发生变化。Profile 持久化时只引用 Main 加密设置，快照不包含长期或临时
+Token。
+
+模块化引擎分别记录 ASR 和 TTS 组件，原生引擎记录 `nativeDuplex` 组件；不能用一个
+`modelId` 代表多组件链路。文本 Agent 使用独立 `VoiceRuntimeSnapshot`，记录已解析的明确
+Runtime、模型 Profile 修订、配置摘要和工作区。`dataPath` 分别说明原始音频和转写文本
+留在设备还是发送到哪个供应商。
+
+### 9.1 Runtime Lease
+
+语音会话不能在每轮请求时重新读取可变的全局 Runtime 设置。启动时必须：
+
+1. 将 `auto` 解析为明确的 Runtime 和模型 Profile，并在会话界面显示实际结果。
+2. 根据已解析配置创建或取得一个不可变的 `VoiceRuntimeLease`。
+3. Lease 在整个 Voice Session 内引用同一个 Runtime 实例和配置摘要。
+4. 全局设置变化只为新请求和新 Voice Session 创建 Runtime，不替换活动 Lease。
+5. 用户删除或修改活动 Profile 时，界面说明“下次语音会话生效”；当前 Lease 继续运行。
+6. 固定实例无法继续时，当前语音会话明确失败，不能取得新的全局 Runtime 继续。
+
+现有 `AgentRuntimeController` 的可变 `current` Slot 会在 `replace()` 后中断活动请求，因此
+不能直接作为长期 Voice Session Lease。实现前必须增加引用计数式 Pin/Lease，或由
+`SelectedRuntimeManager` 为会话持有独立 Runtime Slot；会话结束后再
+`releaseConversation()` 并释放 Lease。
+
+### 9.2 事件
+
+控制事件至少包括：
+
+- `session-preparing`
+- `session-ready`
+- `session-reconnecting`
+- `input-speech-started`
+- `input-transcript-delta`
+- `input-transcript-committed`
+- `response-started`
+- `response-transcript-delta`
+- `response-audio-started`
+- `response-interrupted`
+- `response-completed`
+- `approval-required`
+- `tool-state`
+- `usage`
+- `error`
+- `session-ended`
+
+音频帧使用独立二进制协议，包含：
+
+- `sessionId`
+- `generationId`
+- `sequence`
+- `timestampSamples`
+- `sampleRate`
+- `channels`
+- `encoding`
+- `payload`
+
+帧乱序、重复、跨会话或超过大小上限时直接拒绝，不尝试解释为其他格式。
+
+---
+
+## 10. 状态模型
+
+全双工不能只用一个“正在听/正在说”枚举描述。会话使用三个正交状态：
+
+```text
+Lifecycle:
+idle → preparing → active ↔ reconnecting → ended
+                         └──────────────→ failed
+
+Input:
+muted ↔ listening ↔ speech
+
+Output:
+idle → generating → playing → interrupting → idle
+```
+
+用户可见状态由三个状态组合得出。合法示例：
+
+- `input=listening + output=playing`：助手说话，同时继续监听。
+- `input=speech + output=interrupting`：用户抢话，助手正在停止。
+- `lifecycle=reconnecting + input=muted + output=idle`：当前引擎重连，停止上传。
+
+`awaiting-approval` 是运行阻塞原因，不关闭会话；此时输入可以继续听取取消或补充文本，
+但不能把口头内容解释成授权。
+
+---
+
+## 11. Turn、文本与播放提交
+
+### 11.1 用户输入
+
+- 流式 ASR Delta 只用于界面。
+- Endpoint Detector 确认轮次后产生 committed transcript。
+- 空白、纯噪音和低置信度片段不创建用户消息。
+- 用户可在提交前通过键盘修正；修正结果而非原始猜测进入 Agent Runtime。
+
+### 11.2 助手输出
+
+模块化 TTS 可能落后于文本生成，因此助手文本分为：
+
+- `generated`：模型已生成，尚未安排播放。
+- `queued`：已生成音频，尚未播放。
+- `played`：对应音频已从播放时钟确认输出。
+
+助手消息需要区分“用户可见历史”和“下一轮模型上下文”：
+
+- 所有已展示的有界文本和结构化内容都写入可见消息历史。
+- 可朗读文本记录 `generated`、`queued`、`played` 边界；中断后的消息标记为
+  `interrupted`，并保留用户已经看见的内容及已播放边界。
+- 下一轮模型上下文只包含 `played` 可朗读文本，以及已经展示的 `visual-only` 内容。
+- 尚未播放的可朗读尾部即使曾临时显示，也不回送模型，并在历史中显示“未播完”状态。
+
+代码块、表格、URL、引用和工具结果等不适合逐字朗读的内容使用 `visual-only` Block。它们
+一旦完整展示即可进入可见历史和下一轮上下文，不受语音播放边界裁切。这样既不会丢失用户
+已经看到的详细成果，也不会让模型误以为用户听到了被打断的语音尾部。
+
+云端 Provider 支持会话截断时，Main 使用实际播放位置截断远端 Conversation Item；
+不支持时由 GoodBuddy 在下一轮上下文中只组装 `played` 和已展示的 `visual-only` 部分。
+现有消息契约与上下文组装器需要增加对应 Block 状态，不能用删掉完整助手消息来模拟截断。
+
+### 11.3 文本转语音规划
+
+模块化引擎从流式文本中产生可取消的短语块：
+
+- 优先在中文标点、英文句界和自然从句边界提交。
+- 首个短语不等待完整回答，以降低首音频延迟。
+- URL、Markdown 标记、代码块、表格、引用编号和工具 JSON 不逐字符朗读。
+- 不能可靠口述的内容在界面展示，并使用确定性短提示说明“详细内容已显示在对话中”。
+- 不调用第二个未选择的模型生成“语音摘要”。
+
+---
+
+## 12. 引擎设计
+
+### 12.1 本地模块化全双工
+
+首个跨平台本地基线复用现有 `sherpa-onnx`：
+
+```text
+AudioWorklet
+→ Silero/TEN VAD
+→ sherpa-onnx OnlineRecognizer
+→ selected AgentRuntime
+→ deterministic speech text planner
+→ sherpa-onnx TTS callback
+→ AudioWorklet playback
+```
+
+现有 `sherpa-onnx` Node Addon 已提供在线识别、VAD、本地 TTS 和 TTS 音频回调。当前已安装
+的 SenseVoice、Paraformer 和 Whisper 目录主要用于离线识别；实时模式需要独立的在线
+模型目录和能力声明，不能把离线模型误标成流式模型。
+
+“本地模块化”只保证音频采集、ASR 和 TTS 在本机。中间 Agent Runtime 是否本地取决于
+用户明确选择的模型连接：
+
+- 连接到 loopback 本地模型时，完整链路可离线。
+- 连接到云端文本模型时，原始音频留在本地，但最终转写文本和 Agent 上下文会发送到
+  该模型。界面必须明确显示这一数据路径。
+
+不得因当前文本 Runtime 不可用而替换为另一模型连接。
+
+### 12.2 本地原生全双工
+
+本地原生 Adapter 面向 MiniCPM-o、Moshi/PersonaPlex、BayLing-Duplex 等能够持续接收并
+生成音频的模型。具体模型接入前必须逐个验证：
+
+- 中文和目标语言质量。
+- 真正的持续输入、Barge-in 和 Backchannel，而不只是流式输出。
+- 首音频延迟和长期运行内存。
+- Windows、macOS、Linux 及 x64/arm64 Runtime 可用性。
+- NVIDIA CUDA、Apple Silicon 或 CPU 的真实硬件要求。
+- 工具调用、系统指令、上下文长度和取消支持。
+- 模型、声音、训练数据与商业分发许可。
+- 权重下载、ZIP 迁移、校验和、磁盘占用和卸载。
+
+本地原生模型不作为六平台默认能力。只有能力检测和一次真实会话测试通过后才允许选择。
+缺少结构化工具能力的模型可以声明为 Ask-only；Execute 入口必须阻塞并说明原因，不能暗中
+调用另一个文本模型补齐工具。
+
+### 12.3 云端原生全双工
+
+云端 Adapter 可以面向 OpenAI Realtime、Gemini Live、Qwen Realtime、Azure Voice Live
+等正式配置。每个 Adapter 必须显式声明：
+
+- WebRTC 或 WebSocket 传输。
+- 输入输出音频格式。
+- VAD、Semantic Turn Detection 和手动提交能力。
+- 响应取消、音频截断和实际播放对齐能力。
+- 输入与输出转写能力。
+- 工具调用和 sideband 控制能力。
+- 会话时长、上下文、速率限制和费用。
+- 可用地域、数据处理与保留说明。
+
+Provider 配置不使用泛化“OpenAI compatible”推断 Realtime 能力。普通 Chat Completions
+Endpoint 不能因为 URL 相似就被标记为实时语音。
+
+---
+
+## 13. 音频处理
+
+### 13.1 采集
+
+- 浏览器设备通常以 44.1 或 48 kHz 采集，不能假定请求值就是实际值。
+- 使用 `MediaStreamTrack.getSettings()` 记录实际声道、采样率和回声消除状态。
+- AudioWorklet 以原始设备时钟采集，再按引擎要求转换为 16/24/48 kHz。
+- 默认单声道 Float32 内部格式，边界处转换为 PCM16、Opus 或 Provider 指定格式。
+- 每帧 10–20 ms，带序号和采样时间，不使用墙钟猜测播放位置。
+
+### 13.2 回声与抢话
+
+回声处理使用两层信号：
+
+1. Chromium AEC/NS/AGC 处理后的麦克风流。
+2. GoodBuddy 已知的播放活动、播放能量和 VAD 结果。
+
+只有满足最短语音持续时间、能量和回声相关性条件时才触发 Barge-in。阈值必须可测试，
+不能仅依赖一个 Provider 的 `speech_started` 事件。Provider 事件作为权威轮次信号之一，
+本地快速 VAD 负责先静音。
+
+### 13.3 播放与背压
+
+- 每个响应使用独立 `generationId`，旧响应帧不得进入新队列。
+- 播放队列按采样时钟排序，禁止无限积压。
+- 达到高水位时对上游施加背压；无法背压的 Provider 丢弃会话并报告协议错误，不能持续
+  增长内存。
+- 音频缺口使用短静音或 Provider 编解码恢复，不重复上一段语音。
+- 切换输出设备、设备丢失或系统休眠时暂停提交时钟，避免把未播放文本标记为已听到。
+
+---
+
+## 14. 数据与持久化
+
+### 14.1 默认保存
+
+- Voice Session ID、Conversation ID 和时间。
+- 无凭据的引擎快照及其摘要哈希。
+- 最终用户文本、已展示的助手消息、`visual-only` Block、实际播放边界和中断状态。
+- 中断、失败、取消和完成状态。
+- 有界延迟、音频中断和用量指标。
+- 工具与审批事件继续进入现有任务和活动记录。
+
+### 14.2 默认不保存
+
+- 原始麦克风音频。
+- Provider 返回但尚未播放的音频。
+- 临时 ASR Delta。
+- 长期或临时 API Key、Cookie、会话 Token。
+- Provider 原始错误正文和可能包含用户内容的网络帧。
+- 回声参考信号、设备唯一标识和完整声学特征。
+
+未来若提供录音留存，必须是独立、默认关闭的功能，说明保存位置、期限、大小、导出和删除，
+并与“改进模型”授权分离。
+
+### 14.3 崩溃恢复
+
+应用启动时将未结束的 Voice Session 标记为 `interrupted`。恢复文本 Conversation，
+但不自动重新打开麦克风、不自动连接 Provider，也不重播未完成音频。
+
+---
+
+## 15. 错误、重连与资源回收
+
+| 场景 | 行为 |
+| --- | --- |
+| 麦克风权限拒绝 | 阻塞启动，保留引擎选择，提供系统权限说明 |
+| 输入/输出设备消失 | 立即静音或暂停，要求用户处理设备，不改用未选择设备 |
+| 本地模型缺失或损坏 | 阻塞启动，进入模型管理，不连接云端 |
+| 本地 Runtime 启动失败 | 在有界预算内重启同一 Runtime，之后明确失败 |
+| 云端认证或地域错误 | 明确失败，保留配置，不尝试其他 Provider/地域 |
+| 短暂断网 | 同一引擎有界重连，超过 500 ms 显示状态 |
+| Provider 限流或余额不足 | 结束生成并显示原因，不切本地模型 |
+| Agent Runtime 失败 | 终止当前轮次，允许重试同一 Runtime，不换连接 |
+| TTS 失败 | 当前轮次失败，不静默改成系统 TTS 或仅文本成功 |
+| 工具等待审批 | 暂停响应，保留会话；拒绝后把结果返回当前引擎 |
+| 应用退出/窗口销毁 | 取消请求、停止 Track、关闭 Port/PeerConnection、终止 Sidecar |
+| 系统休眠/锁屏 | 停止采集和上传；恢复后要求用户显式继续 |
+
+每个会话必须有最大时长、最大连续无声时间、最大媒体队列、最大临时文本、最大重连次数和
+最大诊断大小。取消优先于重连和重试。
+
+---
+
+## 16. 安全与隐私
+
+1. 只允许可信主窗口主 Frame 创建和控制 Voice Session。
+2. 麦克风权限只放行音频，不因实时语音放开视频。
+3. 任何音频采集都需要用户操作；活动期间持续显示应用内状态和系统麦克风指示。
+4. 云端会话在开始前显示 Provider、地域、发送内容和可能费用。
+5. API Key 只在 Main 的加密设置或受控环境变量中使用。
+6. 临时 Provider 凭据具有最短可行期限、最小能力和单会话作用域。
+7. Provider 工具调用必须回到 Main 的白名单、Schema、Ask/Execute 和审批边界。
+8. 本地 Sidecar 只监听 loopback，使用短期认证，不开放外部端口。
+9. 模型权重按受信任目录、固定来源、大小和 SHA-256 校验，导入 ZIP 防止路径穿越和压缩炸弹。
+10. 日志只记录状态、耗时、错误分类和匿名引擎 ID，不记录语音正文和音频。
+11. 窗口隐藏时若会话仍活动，托盘必须持续显示麦克风状态和停止入口；首期可以选择隐藏即
+    暂停，但不能隐藏后无提示继续采集。
+12. Voice Session 不扩大项目、知识库、文件、浏览器或桌面控制范围。
+
+---
+
+## 17. 性能与质量指标
+
+### 17.1 交互指标
+
+| 指标 | 目标 |
+| --- | --- |
+| 用户开口到本地 VAD 检出 | P95 ≤ 100 ms |
+| Barge-in 检出到扬声器静音 | P95 ≤ 150 ms |
+| 播放队列常态深度 | 100–400 ms |
+| 用户轮次结束到临时文本稳定 | P50 ≤ 300 ms |
+| 用户轮次结束到首段助手音频 | 云端/原生引擎 P50 ≤ 800 ms；模块化引擎 P50 ≤ 1,200 ms |
+| 已提交文本与实际播放偏差 | ≤ 100 ms 或一个最小短语块 |
+| 连续 30 分钟会话 | 无未界定内存增长、重复播放或资源泄漏 |
+
+本地指标必须注明测试硬件，不能把高端 GPU 结果宣传为 CPU 基线。未达到所选引擎声明的
+实时系数时，能力检测应标记为不满足实时要求，而不是静默切到更小模型。
+
+### 17.2 质量指标
+
+- 中文普通话、英文和中英混合词的 ASR 错误率。
+- 长停顿、语气词、短回答和自我修正的轮次准确率。
+- 扬声器回声、键盘声、音乐和旁人说话下的误打断率。
+- 真正用户抢话的漏检率和停止延迟。
+- TTS 首段延迟、断句、数字、日期、英文缩写和代码术语可懂度。
+- 中断后下一轮上下文不包含未播放内容。
+- Provider、模型、数据位置和能力从不发生未声明变化。
+
+---
+
+## 18. 测试策略
+
+### 18.1 自动化
+
+- Voice Contract Schema、大小边界和迁移测试。
+- 三组正交状态及非法状态组合测试。
+- 有序、乱序、重复、迟到和跨 Session 音频帧测试。
+- Barge-in 对播放、Provider、Agent、TTS 和持久化的取消传播测试。
+- 临时文本、已提交文本和播放位置对齐测试。
+- 同一引擎重连预算与超时测试。
+- “禁止静默降级”矩阵测试：任何 Adapter、Provider、模型、地域或 Runtime 变化都必须失败。
+- Ask 只读和 Execute 审批测试。
+- 窗口销毁、应用退出、休眠和设备丢失的资源释放测试。
+- 不持久化音频、临时 Token 和 Provider 原始正文的数据库测试。
+
+### 18.2 模拟与声学测试
+
+建立确定性 Fake Voice Engine，能够注入：
+
+- 固定节奏的输入、文本和音频。
+- 网络抖动、丢包、重复和断开。
+- 超前文本、迟到音频和错误播放位置。
+- 用户抢话、回声、短噪音和长停顿。
+- 工具调用、审批、拒绝和取消。
+
+真实声学测试使用预录双声道夹具，一路作为助手扬声器参考，一路作为用户麦克风输入。
+不能只通过静态单段 WAV 验证全双工。
+
+### 18.3 手动与外部调用
+
+- 六个发布目标分别验证麦克风权限、采集、播放、设备拔插和应用退出。
+- 本地模型在声明的最低硬件上完成 30 分钟稳定性和实时系数测试。
+- 云端 Provider 测试会产生外部调用和费用，只在明确授权的 gated 测试中运行。
+- 每个云端 Adapter 至少验证一次真实音频输入、真实音频输出、打断和工具审批。
+- 真实测试失败时不使用配置握手成功替代生成验证。
+
+---
+
+## 19. 跨平台交付
+
+### 19.1 基线
+
+- 本地模块化引擎作为 Windows、macOS、Linux x64/arm64 的统一功能基线。
+- 在线 ASR、VAD 和轻量 TTS 权重不内置，继续使用按需下载和 ZIP 离线迁移。
+- GoodBuddy 托管模型的下载遵守
+  [平台功能页签与模型下载源设计](../../architecture/model-download-source-design.md)，使用用户显式选择的
+  ModelScope 或 Hugging Face，失败时不切换来源。
+- 云端 Adapter 在六个平台复用同一契约，并分别验证 Electron WebRTC/WebSocket 行为。
+- 本地原生引擎按 Adapter 声明平台与硬件，不伪装成全平台能力。
+
+### 19.2 硬件能力等级
+
+| 等级 | 目标 |
+| --- | --- |
+| CPU 基线 | 本地模块化 ASR/TTS；文本 Runtime 可以本地或云端 |
+| Apple Silicon | 可增加 MLX/Metal 本地原生 Adapter，必须单独验证 |
+| NVIDIA GPU | 可增加 CUDA 本地原生 Adapter，按显存和驱动验证 |
+| 不满足要求 | 引擎卡片显示不可用与原因，不自动选择其他引擎 |
+
+安装包继续保持轻量。大模型权重、CUDA Runtime 和独立 Python 环境不得无条件加入全部
+发布包。
+
+---
+
+## 20. 分阶段实施
+
+### 阶段 0：契约与模拟器
+
+- 新增 Voice Contracts、状态机和 Fake Voice Engine。
+- 建立禁止静默降级测试矩阵。
+- 建立会话快照、事件和诊断结构。
+
+### 阶段 1：Renderer 音频平面
+
+- AudioWorklet 采集与播放。
+- 媒体 `MessagePort`、背压和播放时钟。
+- 快速 VAD、回声关联、Barge-in 和设备生命周期。
+- 实时语音控制区和可访问状态。
+
+### 阶段 2：本地模块化基线
+
+- 在线 ASR 和 VAD 模型管理。
+- Agent Runtime 流式文本桥。
+- 本地 TTS 模型管理、短语规划、音频回调和取消。
+- 最终文本持久化与工具审批。
+- 六个平台/架构验证。
+
+### 阶段 3：首个云端原生 Adapter
+
+- Main-only 凭据和引擎 Profile。
+- WebRTC 或 WebSocket 会话。
+- 转写、音频、截断、用量和 Provider 错误。
+- sideband 工具与审批。
+- 真实有费用的 gated 验证。
+
+### 阶段 4：本地原生全双工 Adapter
+
+- 选择一个中文质量、许可和硬件要求已验证的模型。
+- 建立受管 Sidecar、能力检测和真实会话测试。
+- 验证原生 Barge-in、文本提交、工具能力和长期稳定性。
+
+### 阶段 5：扩展与质量
+
+- 增加经过验证的云端和本地 Adapter。
+- 输出设备选择和企业语音策略。
+- 声学基准、延迟仪表盘和成本诊断。
+- 评估是否允许用户预配置仍需确认的显式替代策略。
+
+---
+
+## 21. 首个垂直切片
+
+首个可合并实现应使用 Fake Voice Engine，不立即绑定某个云端 Provider：
+
+1. 用户显式开始会话。
+2. AudioWorklet 持续采集和播放模拟流。
+3. Fake Engine 产生临时转写、助手文本和音频。
+4. 用户开口触发 150 ms 内静音和响应取消。
+5. 持久化已提交用户文本、已展示助手内容、`visual-only` Block 和实际播放边界；下一轮
+   模型上下文只使用已播放文本与完整显示的 `visual-only` Block。
+6. 模拟工具审批时暂停语音，拒绝口头授权。
+7. 注入 Adapter 失败后明确结束，不切换任何引擎。
+8. 关闭窗口后所有 Track、Port、计时器和模拟任务归零。
+
+该切片先验证最难改变的会话、音频、提交和安全契约，再分别接入本地和云端实现。
+
+---
+
+## 22. 验收标准
+
+- 用户可以明确选择本地模块化、本地原生或云端原生引擎，界面持续显示当前选择。
+- 会话快照冻结 Provider、模型、地域、声音、数据位置和能力。
+- 任何引擎、Provider、模型、地域、Runtime 或模式变化都不能在测试中静默发生。
+- 助手播放期间继续采集麦克风，用户可在 P95 150 ms 内打断。
+- 中断后未播放音频与文本不进入下一轮上下文。
+- Ask 和 Execute 在语音中与文本中使用同一权限和审批边界。
+- 语音口令不能批准工具。
+- 云端长期凭据不进入 Renderer，本地 Sidecar 不监听外部地址。
+- 默认数据库、日志和 Artifact 中没有原始音频。
+- 本地引擎失败不连接云端，云端引擎失败不启动本地模型。
+- 重连只针对同一引擎快照，并在可感知时显示状态。
+- 六个平台目标完成各自声明能力的真实采集、播放、取消和资源回收验证。
+- `npm test`、`npm run typecheck`、`npm run lint` 和生产构建全部通过。
+
+---
+
+## 23. 参考
+
+- [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)：本地在线/离线 ASR、VAD 与 TTS。
+- [OpenAI Realtime](https://developers.openai.com/api/docs/guides/realtime)：云端实时音频会话与 WebRTC/WebSocket。
+- [Gemini Live API](https://ai.google.dev/gemini-api/docs/live-api)：云端双向实时音频与多模态会话。
+- [Qwen Realtime](https://help.aliyun.com/zh/model-studio/realtime)：云端实时音视频输入与音频/文本输出。
+- [MiniCPM-o](https://github.com/OpenBMB/MiniCPM-V)：本地端到端多模态与全双工候选。
+- [Moshi](https://github.com/kyutai-labs/moshi)：本地原生全双工语音模型框架。
+- [PersonaPlex](https://github.com/NVIDIA/personaplex)：本地可控角色与声音的全双工候选。
+- [AudioWorklet](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorklet)：Renderer 低延迟音频处理基础。

docs/features/in-app-feedback/README.md

@@ -0,0 +1,11 @@
+# 应用内反馈
+
+应用内反馈负责用户在 GoodBuddy 中提交反馈、附带受控诊断并获得提交状态。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [技术设计](./technical-design.md) | 产品流程、数据边界、接口、UI 接入和验收 |
+
+现有文档是综合设计，尚未按标准职责拆分。

docs/features/in-app-feedback/technical-design.md

@@ -0,0 +1,710 @@
+# GoodBuddy 应用内反馈系统设计与对接
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档类型 | 跨功能产品与技术架构 |
+| 状态 | 已实施并完成生产联调，待发布 |
+| 版本 | 1.0 |
+| 日期 | 2026-08-25 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 相关基线 | [统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文定义 GoodBuddy 桌面端的应用内反馈入口、数据边界、Renderer / Preload /
+Main 进程职责、公共 API 对接、失败处理和验收方法。反馈平台服务端、管理后台、
+数据库、附件存储、部署和运营流程由独立项目维护，不在本文复制其内部设计。
+
+本文是 **GoodBuddy 客户端实现的权威设计**。服务端字段、状态码和限制以反馈平台
+发布的版本化公共 API 契约为准；两边的同名契约必须通过兼容性测试保持一致，不能各自
+扩展后继续沿用相同的 `schemaVersion`。
+
+---
+
+## 1. 摘要与核心决策
+
+1. 用户在“设置 → 关于与更新”内直接提交问题、功能建议、体验意见或其他反馈，不再跳转
+   GitHub Issue 页面。
+2. Renderer 只负责表单、截图预览和状态展示。所有网络请求、安装标识、应用版本和系统
+   环境组装都在 Main 中完成。
+3. Preload 只暴露用途明确的 `feedback.submit()` 方法，不暴露任意 URL、通用
+   `fetch`、Electron API、文件路径或服务端管理能力。
+4. 公共请求固定使用版本化接口 `POST /api/v1/feedback`，GoodBuddy 的
+   `productKey` 固定为 `goodbuddy`。
+5. 反馈服务的生产 HTTPS Origin 是客户端源代码中的受信产品常量，不是用户设置，不从
+   Renderer、项目、Runtime、环境变量、远程配置或服务端重定向中获取。
+6. GoodBuddy 当前的全局 TLS 策略允许模型和内网服务使用自签名或过期证书。反馈可能包含
+   用户输入和截图，因此 **反馈客户端不得复用全局不校验证书的 Dispatcher 或
+   `globalThis.fetch`**，必须使用独立的 Undici Dispatcher 并显式启用正常证书校验。
+7. 首版允许一张可选截图。截图只能由用户主动选择或粘贴，发送前必须预览并允许移除；
+   GoodBuddy 不自动截屏。原始输入和 PNG 标准化结果都不能超过 5 MiB。
+8. Main 在发送前解码并重编码截图为 PNG，确保原始 EXIF/XMP 等元数据不会离开设备；
+   服务端仍独立执行自己的图片验证和标准化。
+9. 一次新反馈生成一个 `clientRequestId`。网络失败后的手动重试必须复用原 ID，服务端
+   以此保证幂等；创建另一条反馈时才生成新 ID。
+10. GoodBuddy 使用单独的随机安装 UUID 做服务端限流。该 UUID 不得复用 Agent
+    installation ID、硬件 ID、机器名、用户名、项目 ID 或任何设备指纹。
+11. 默认不发送对话、提示词、模型回复、诊断、日志、文件、项目或工作区路径、知识库、模型
+    配置、Runtime 配置、API Key、Token、Cookie、SSH 信息、剪贴板或屏幕内容。用户可通过
+    默认关闭的 Checkbox 主动附加有界的最近桌面诊断摘要。
+12. 反馈提交失败时保留全部表单内容和截图，成功后显示可复制的服务端反馈编号。
+13. 首版不提供反馈历史、状态查询、编辑、撤回、自动日志收集或服务端管理入口。
+14. 生产接口固定为 `https://imp.mesalogo.com/api/v1/feedback`。域名健康检查、
+    TLS、v1 请求校验和客户端调用链必须在发布前一起通过。
+
+---
+
+## 2. 目标与非目标
+
+### 2.1 用户目标
+
+- 不离开 GoodBuddy 即可报告问题或提出建议。
+- 在发送前明确知道哪些字段会离开设备。
+- 只在主动选择后上传截图，并能检查、替换或移除截图。
+- 网络失败后无需重新填写内容。
+- 提交成功后获得稳定编号，便于后续沟通。
+
+### 2.2 产品目标
+
+- 让 GoodBuddy 成为独立多产品反馈平台的第一个客户端。
+- 保持 Electron 上下文隔离和 Main-only 网络边界。
+- 使用小而稳定的版本化契约，不把服务端工单、数据库和管理员概念泄漏到客户端。
+- 对 Windows、macOS、Linux 的 x64 与 arm64 使用相同行为。
+- 以数据最小化为默认，不把应用内反馈演变为隐式遥测或日志上传。
+
+### 2.3 非目标
+
+首版不包含：
+
+- GitHub Issue 创建、GitHub Token 或 GitHub 网页附件上传。
+- GoodBuddy 内的管理员后台、处理状态修改或内部备注。
+- 用户账户、登录、反馈列表、远程状态查询或推送通知。
+- 自动附加当前对话、桌面诊断、日志、错误堆栈、项目、文件、模型或 Runtime 信息。
+- 远端 Agent 日志或通用日志、诊断包和附件框架。
+- 自动截取全屏、当前窗口、浏览器、远程桌面或其他应用窗口。
+- 多截图、视频、录屏、任意文件附件或压缩包。
+- 离线队列、后台自动重试、指数退避、跨重启草稿或发送历史。
+- 用户可编辑的反馈 Endpoint、证书豁免、代理凭据或服务端 API Key。
+- 由 GoodBuddy 推断优先级、自动分类、自动生成描述或代表用户提交。
+
+---
+
+## 3. 用户体验
+
+### 3.1 入口
+
+入口放在现有“关于与更新”页面，不增加新的设置一级分类。
+
+在当前版本与更新卡片之后增加“帮助改进 GoodBuddy”能力卡：
+
+- 标题：`帮助改进 GoodBuddy`
+- 说明：`报告问题、提出建议或反馈使用体验，我们会在独立反馈系统中处理。`
+- 主操作：`提交反馈`
+
+该卡片不显示反馈平台内部状态、管理员信息或 GitHub 链接。服务不可用时仍允许用户打开
+表单和保留输入；提交失败后提供重试，而不是把用户重定向到另一个渠道。
+
+### 3.2 反馈对话框
+
+对话框字段按以下顺序排列：
+
+1. **反馈类型**，必填：
+   - 问题：`bug`
+   - 功能建议：`feature`
+   - 使用体验：`experience`
+   - 其他：`other`
+2. **标题**，必填，1 至 120 字符。
+3. **详细描述**，必填，去除首尾空白后 10 至 5,000 字符；选择桌面诊断时为摘要预留空间，
+   用户描述上限为 3,398 字符。
+4. **附加最近桌面诊断记录**，可选的原生 Checkbox，默认关闭。
+5. **联系邮箱**，可选，最多 254 字符。
+6. **截图**，可选，最多一张，支持选择 PNG/JPEG/WebP 或在对话框中粘贴图片。
+7. **将发送的信息**，只读显示应用版本、系统、架构和界面语言。
+8. **隐私说明**，紧邻提交操作。
+
+隐私说明使用明确文案：
+
+> 将发送反馈类型、标题、描述、可选邮箱、GoodBuddy 版本、操作系统、架构、界面语言，
+> 以及你主动添加的截图。默认不上传桌面诊断；只有勾选后才会把有界诊断摘要追加到描述。
+> 不会发送对话、Prompt、凭据、文件内容、路径、Provider 原始响应或远端 Agent 日志。
+
+Checkbox 下方持续说明：诊断摘要只含时间、组件、阶段、稳定错误码、错误类型和固定短消息。
+Renderer 不预览、不读取也不接收诊断内容或路径。勾选后详细描述上限为 3,398 字符，为附加
+摘要预留 1,600 字符以及分隔换行；超长草稿保留在表单中并显示字段错误，不静默截断。
+
+截图区域必须包含：
+
+- 缩略预览。
+- 尺寸和所选文件大小；Main 仍在发送前独立执行 PNG 标准化和大小检查。
+- `替换截图` 与 `移除截图`。
+- `截图可能包含画面中可见的个人信息，请在发送前检查。`
+
+### 3.3 提交状态
+
+| 状态 | 行为 |
+| --- | --- |
+| 未填写 | 字段保持可编辑，提交按钮按字段有效性启用 |
+| 校验失败 | 在对应字段旁显示错误并把焦点移到第一个无效字段 |
+| 提交中 | 禁止重复提交、关闭和修改字段，按钮显示“正在提交…” |
+| 网络或服务失败 | 保留字段和截图，在表单内显示可操作错误及“重试” |
+| 成功 | 对话框切换为确认面板，显示并允许复制反馈编号 |
+
+提交成功属于必须保留编号的上下文结果，不再同时发送一条重复的全局成功通知。异步失败也
+保留在对话框内，因为错误与当前草稿和重试操作直接关联。
+
+### 3.4 可访问性
+
+- 对话框使用 `role="dialog"`、`aria-modal="true"` 和可见标题。
+- 复用 `activateModalFocus()` 与 `trapTabFocus()`，打开后聚焦反馈类型，关闭后恢复入口
+  按钮焦点。
+- 非提交状态支持 Escape 关闭；提交中保持对话框打开，直到请求完成或到达有界超时。
+- 字段使用原生 `label`、`select`、`input` 和 `textarea`。
+- 图片预览提供说明性替代文本，删除和替换按钮有明确可访问名称。
+- 加载、失败和成功状态使用文字，不依赖颜色。
+- 浅色、深色和 `prefers-reduced-motion` 行为遵循 `UI-DESIGN.md`。
+
+---
+
+## 4. 数据与隐私边界
+
+### 4.1 明确发送的数据
+
+| 数据 | 来源 | 用途 |
+| --- | --- | --- |
+| `schemaVersion` | Main 常量 | 选择公共契约版本 |
+| `productKey` | Main 常量 `goodbuddy` | 服务端产品路由 |
+| `category` | 用户选择 | 分流反馈 |
+| `title` | 用户输入 | 摘要 |
+| `description` | 用户输入；勾选时由 Main 追加桌面诊断摘要 | 问题、建议和主动提供的有界诊断详情 |
+| `contactEmail` | 用户可选输入 | 必要时联系用户 |
+| `environment.appVersion` | `app.getVersion()` | 判断受影响版本 |
+| `environment.platform` | `process.platform` 映射 | 判断受影响平台 |
+| `environment.architecture` | `process.arch` 映射 | 判断受影响架构 |
+| `environment.locale` | 当前 GoodBuddy UI 语言 | 理解用户语言环境 |
+| `installationId` | Main 本地随机 UUID | 服务端安装实例限流 |
+| `clientRequestId` | 当前草稿随机 UUID | 幂等和安全重试 |
+| `screenshot` | 用户主动选择或粘贴 | 复现视觉问题 |
+
+客户端不主动发送来源 IP；IP 是 HTTPS 请求到达服务端时产生的网络元数据。服务端如何保存、
+散列和保留该元数据由独立反馈平台的隐私与运维策略负责。
+
+用户填写联系邮箱后，邮箱会作为业务字段通过 HTTPS 发送并由反馈平台保存，不属于端到端
+加密内容。用户不希望提供联系方式时应留空，GoodBuddy 不尝试从系统账户或其他设置推断
+邮箱。
+
+### 4.2 默认不发送的数据
+
+以下数据不能因为“有助于复现”而隐式加入请求：
+
+- 当前或历史对话、提示词、模型回复和 Supervisor 内容。
+- GoodBuddy、Runtime、Agent、SSH、消息通道、浏览器或操作系统日志。
+- 文件内容、附件、知识库、Magic Notes、成果和工作区改动。
+- 文件名、项目名、本地路径、远程路径、主机名、用户名或 IP 配置。
+- LLM、向量模型、语音模型、OCR、MCP、Skill、Runtime 或通道配置。
+- API Key、Access Token、Cookie、SSH 密码、私钥、代理凭据和其他秘密。
+- 剪贴板、屏幕、摄像头、麦克风或其他应用内容。
+- Remote Agent installation ID、Runtime ID、Conversation ID、Task ID 或 Project ID。
+
+除上述用户主动选择、追加到描述且有界的桌面诊断摘要外，未来若增加日志、诊断包或其他
+附件，必须单独设计字段、预览、大小限制、用户选择和服务端保留策略，不能复用截图字段
+静默上传。
+
+### 4.3 本地数据生命周期
+
+- 表单草稿、邮箱和截图只保存在当前 Renderer 内存中。
+- 首版不把草稿、失败请求、成功响应或截图写入 GoodBuddy 数据库和设置文件。
+- Main 只在请求期间持有标准化图片字节，请求结束后释放引用，不创建临时图片文件。
+- 成功后关闭确认面板时清空草稿。
+- `installationId` 单独保存在用户数据目录中的
+  `feedback-identity.json`，格式为版本化 JSON，文件权限沿用私有原子设置文件机制。
+- “清除本地数据”必须中止进行中的反馈请求并删除该身份文件；下次提交会生成新 UUID。
+
+---
+
+## 5. 公共 API 对接
+
+### 5.1 外部契约所有权
+
+反馈平台负责维护公共 API 的权威定义。GoodBuddy 只固定客户端实际需要的版本 1 子集：
+
+```text
+POST https://imp.mesalogo.com/api/v1/feedback
+```
+
+当前生产 Endpoint 已作为 Main-only 产品常量固定。实现和发布验证必须持续保证：
+
+- 使用 `https:`。
+- URL 不含用户名、密码、查询参数或 fragment。
+- Path 精确为 `/api/v1/feedback`。
+- 对应产品 `goodbuddy` 已在服务端启用。
+- 桌面端所在网络能够直接访问该 Origin。
+
+Renderer、Preload、用户设置、环境变量和远程配置都不能覆盖该 Endpoint。域名迁移必须
+同时修改客户端受信常量、测试、服务端 Origin 配置和部署文档。
+
+### 5.2 请求 JSON
+
+无截图时发送 `application/json`：
+
+```json
+{
+  "schemaVersion": 1,
+  "productKey": "goodbuddy",
+  "category": "bug",
+  "title": "魔法笔记页签不可见",
+  "description": "平台功能中的魔法笔记页签被布局压缩，无法看到或点击。",
+  "contactEmail": "user@example.com",
+  "environment": {
+    "appVersion": "0.11.0",
+    "platform": "windows",
+    "architecture": "x64",
+    "locale": "zh-CN"
+  },
+  "installationId": "00000000-0000-4000-8000-000000000101",
+  "clientRequestId": "00000000-0000-4000-8000-000000000102"
+}
+```
+
+有截图时发送 `multipart/form-data`：
+
+- `payload`：同一 JSON 的字符串形式。
+- `screenshot`：一张标准化 PNG，文件名固定为 `feedback.png`。
+
+`contactEmail` 为空时省略，不发送空字符串。请求对象不附加服务端未声明字段。
+
+### 5.3 成功响应
+
+HTTP 201 表示首次创建，HTTP 200 表示相同 `clientRequestId` 的幂等结果：
+
+```json
+{
+  "reference": "GOODBUDDY-000001",
+  "duplicate": false
+}
+```
+
+客户端对两种成功状态使用相同确认界面。`duplicate: true` 不能显示为失败，它表示先前请求
+已经成功落库。
+
+### 5.4 错误映射
+
+| HTTP / 错误 | 用户结果 |
+| --- | --- |
+| 400 | 提示提交内容无效，保留草稿；同时记录为客户端契约缺陷 |
+| 403 | 提示客户端与反馈服务配置不匹配 |
+| 404 | 提示反馈服务暂不可用 |
+| 413 | 提示截图或请求过大，允许移除截图后重试 |
+| 429 | 提示提交过于频繁，保留草稿并让用户稍后手动重试 |
+| 500–599 | 提示服务暂时异常，保留草稿 |
+| 超时 / DNS / TLS / 离线 | 提示无法连接反馈服务，保留草稿 |
+| 响应格式错误 | 提示服务返回无效结果，不能猜测成功 |
+| 本地诊断读取失败 | 不发送反馈，保留草稿、勾选状态和请求 ID，提示重试或取消勾选 |
+
+首版不自动重试。自动重试容易让用户无法判断是否已经发送，也会在服务持续异常时制造额外
+流量。用户点击“重试”时复用同一个 `clientRequestId`。
+
+---
+
+## 6. 进程与模块设计
+
+### 6.1 调用链
+
+```text
+UpdateSettingsSection / FeedbackDialog
+  → window.goodbuddy.feedback.submit(input)
+  → preload: ipcRenderer.invoke(feedbackSubmit)
+  → Main IPC: trusted sender + Zod parse
+  → FeedbackService: identity + environment + screenshot normalization
+  → StrictFeedbackHttpClient
+  → POST /api/v1/feedback
+  → response schema parse
+  → Renderer confirmation or inline retry state
+```
+
+### 6.2 Shared
+
+新增 `src/shared/feedback-contracts.ts`，包含：
+
+- `feedbackCategorySchema`
+- `feedbackDraftSchema`
+- `feedbackScreenshotInputSchema`
+- `feedbackSubmitInputSchema`
+- `feedbackSubmitResultSchema`
+- `feedbackPublicPayloadSchema`
+- 公共字段长度和截图限制常量
+
+推荐客户端 IPC 输入：
+
+```ts
+type FeedbackSubmitInput = {
+  category: 'bug' | 'feature' | 'experience' | 'other'
+  title: string
+  description: string
+  includeDiagnostics: boolean
+  contactEmail?: string
+  locale: 'zh-CN' | 'en-US'
+  clientRequestId: string
+  screenshot?: {
+    data: Uint8Array
+    mimeType: 'image/png' | 'image/jpeg' | 'image/webp'
+  }
+}
+```
+
+Renderer 不能传入 `productKey`、`appVersion`、`platform`、`architecture` 或
+`installationId`，也不能传入诊断内容或路径。这些字段由 Main 从受信运行环境生成。
+
+### 6.3 IPC 与 Preload
+
+新增：
+
+```text
+ipcChannels.feedbackSubmit = "feedback:submit"
+```
+
+`DesktopApi` 新增必选窄接口：
+
+```ts
+feedback: {
+  submit: (input: FeedbackSubmitInput) => Promise<FeedbackSubmitResult>
+}
+```
+
+Main handler 必须：
+
+1. 调用现有 `assertTrustedSender(event, window)`。
+2. 使用 Shared Zod schema 解析 `unknown` 输入。
+3. 不接收 URL、文件路径、Cookie、Header 或任意请求选项。
+4. 由 `FeedbackService` 跟踪活动 Promise，应用关闭或清除数据时先取消再有界等待。
+
+Preload 只转发已声明输入，不做网络请求或图片文件读取。
+
+反馈 handler 独立放在 `feedback/feedback-ipc.ts`，复用共享的
+`assertTrustedSender()`，避免继续扩展通用 `registerIpcHandlers()` 的位置参数列表。
+
+### 6.4 FeedbackIdentityStore
+
+新增 Main-only `FeedbackIdentityStore`：
+
+- 文件：`<userData>/feedback-identity.json`
+- Schema：
+
+```json
+{
+  "version": 1,
+  "installationId": "00000000-0000-4000-8000-000000000101"
+}
+```
+
+- 缺失时使用 `crypto.randomUUID()` 创建。
+- 使用 `writeJsonFileAtomically()` 写入 0600 临时文件并原子替换。
+- 读取时使用严格 schema。
+- 损坏时隔离原文件并生成新身份，不读取或复用 Remote Agent 身份。
+- 并发首次读取必须合并为同一个 Promise，不能生成两个 UUID。
+- `clear()` 删除文件和内存缓存，供“清除本地数据”调用。
+
+该 UUID 是可重置的应用安装级随机标识，不声称代表真实设备或用户。
+
+### 6.5 FeedbackService
+
+Main-only `FeedbackService` 负责：
+
+- 读取或创建安装 UUID。
+- 映射应用版本、平台和架构。
+- 验证并标准化可选截图。
+- 组装严格的公共 payload。
+- 仅在 `includeDiagnostics: true` 时通过注入的 DesktopDiagnostics provider 读取最多 20 条
+  最近记录；默认提交完全不调用诊断 provider。
+- 将诊断格式化为带
+  `[GOODBUDDY_DESKTOP_DIAGNOSTICS_V1_BEGIN]` /
+  `[GOODBUDDY_DESKTOP_DIAGNOSTICS_V1_END]` 明确分隔、最多 1,600 字符且只保留完整 JSON
+  行的摘要。无记录时写入固定 `{"status":"no-recent-diagnostics"}` 事实。
+- 调用 HTTP Client。
+- 维持单次提交的 AbortController，并在 dispose / 清除本地数据时取消。
+
+平台映射固定为：
+
+| Node 值 | API 值 |
+| --- | --- |
+| `win32` | `windows` |
+| `darwin` | `macos` |
+| `linux` | `linux` |
+| 其他 | `unknown` |
+
+架构只保留 `x64` 和 `arm64`，其他值映射为 `unknown`。
+
+公共 API 继续使用 `schemaVersion: 1` 和原有固定字段。`includeDiagnostics` 只属于客户端
+IPC 输入，不进入公共 payload，也不新增 multipart 字段；Main 把摘要追加到
+`payload.description`。默认未勾选时，公共 payload 与既有实现逐字段一致。诊断读取失败时
+不得发送部分摘要或声称已附加，必须返回可本地化的 `diagnostics-unavailable` 错误。
+
+### 6.6 严格 HTTPS Client
+
+反馈客户端使用 `undici` 的独立 `Agent`：
+
+```ts
+new Agent({
+  connect: {
+    rejectUnauthorized: true
+  }
+})
+```
+
+这是必要边界，不是额外配置。GoodBuddy 的 `GlobalTlsPolicy` 会给模型、MCP 和内网服务
+安装不校验证书的全局 Dispatcher；反馈内容不能经过该 Dispatcher。
+
+每次请求必须满足：
+
+- 固定、预先校验的 HTTPS URL。
+- 使用 Undici 原始 `request()`，不安装重定向处理器；任何 3xx 都按服务不可用处理。
+- 不使用 Cookie Jar、缓存、Referrer 或浏览器凭据模式。
+- `Accept: application/json`。
+- 固定、非敏感 `User-Agent`，例如 `GoodBuddy-Feedback/<version>`。
+- 不发送 `Authorization`、Cookie、API Key 或自定义代理凭据。
+- 总超时建议 15 秒，最大不得超过 30 秒。
+- 成功响应体最多 16 KiB，并检查流式实际字节数，不能只相信
+  `Content-Length`。
+- 只接受 JSON `Content-Type` 和 JSON 响应体，并使用
+  `feedbackSubmitResultSchema` 解析。
+- 日志只记录有界错误类别和 HTTP 状态，不记录请求正文、邮箱、截图、安装 UUID、
+  `clientRequestId` 或响应编号。
+
+测试可以注入 Endpoint、Dispatcher 和 Request Transport。生产构造路径不得读取测试覆盖值或
+环境变量。
+
+---
+
+## 7. 截图处理
+
+### 7.1 Renderer
+
+- 文件输入限制为 `.png,.jpg,.jpeg,.webp`。
+- 原始文件上限固定为 5 MiB，超过后不读取完整内容或调用 IPC。
+- 粘贴事件只处理图片，不拦截普通文本粘贴。
+- 读取 `File.arrayBuffer()` 后先执行 Shared 字节上限校验。
+- 使用临时 Object URL 预览，替换、移除或关闭对话框时立即
+  `URL.revokeObjectURL()`。
+- 不调用 `webUtils.getPathForFile()`，不把本地文件路径传给 Main 或服务端。
+
+### 7.2 Main
+
+Main 不信任 Renderer 声明的 MIME：
+
+1. 校验 PNG、JPEG、WebP 文件签名。
+2. 使用 `nativeImage.createFromBuffer()` 实际解码。
+3. 拒绝空图片、异常尺寸、超过 API 公开上限的像素数。
+4. 使用 `toPNG()` 重编码，去除原始元数据。
+5. 检查标准化后字节数不超过 5 MiB，最大边长不超过 8,192 像素，总像素数不超过
+   3,200 万。
+6. 仅把标准化 PNG 放入当前网络请求，不写入磁盘。
+
+客户端和服务端都执行图片验证属于有意的纵深防御：客户端保证原始元数据不离开设备，
+服务端保证不能信任任意客户端。
+
+---
+
+## 8. Renderer 实施落点
+
+### 8.1 组件
+
+- `UpdateSettingsSection.tsx`
+  - 继续负责应用信息和更新卡片。
+  - 渲染反馈入口卡片。
+- `FeedbackDialog.tsx`
+  - 独立管理草稿、预览、校验、提交、重试和成功编号。
+  - 关闭后销毁草稿状态。
+对话框不与更新检查状态共用 `saving`、`checking` 或 `error`，避免一个功能失败覆盖另一个
+功能的状态。
+
+### 8.2 国际化
+
+在 `settingsSections` 的 `zh-CN` 与 `en-US` 资源中增加同构键：
+
+- 入口卡片标题、说明和按钮。
+- 类型名称。
+- 字段标签、占位、帮助和校验。
+- 截图选择、替换、移除和隐私提醒。
+- 提交中、失败、重试、成功和复制编号。
+- 数据发送说明。
+
+组件不得内嵌只存在于一种语言的产品文案。
+
+### 8.3 样式
+
+- 复用 `capability-card`、`field`、`primary-button`、`secondary-button` 和现有
+  对话框层级。
+- 新样式使用 `UI-DESIGN.md` 的语义颜色、间距、圆角和动效令牌。
+- 对话框桌面端最大宽度建议 600px；窄窗口占可用宽度并保持 16px 页面边距。
+- 不为反馈入口创建新的一级页面、页签视觉或高饱和营销卡片。
+
+---
+
+## 9. 失败、生命周期与恢复
+
+### 9.1 幂等
+
+- 打开新草稿时生成 `clientRequestId`。
+- 字段编辑、截图替换、网络失败和手动重试都不改变 ID。
+- 成功或显式丢弃草稿后，下一条反馈生成新 ID。
+- 同一 ID 返回原编号时按成功处理。
+
+### 9.2 并发
+
+- 对话框同一时间只允许一个提交。
+- Main 同一 `clientRequestId` 只运行一个请求。
+- Main 全局同一时间只发送一条反馈；相同 ID 的重复调用合并，不同 ID 在已有请求期间返回
+  有界 `busy` 结果，不能并行保留多份 5 MiB 截图。
+- 读取截图使用选择代次；旧文件后完成时必须丢弃并释放 Object URL，不能覆盖较新的截图。
+
+### 9.3 应用退出与清除数据
+
+- 反馈请求有独立 AbortController。
+- 应用退出时取消进行中的请求并关闭严格 TLS Dispatcher。
+- “清除本地数据”先取消请求，再删除 `feedback-identity.json`。
+- 失败或取消不写入本地“已发送”状态，服务端是否已接收由同 ID 重试确认。
+
+### 9.4 服务不可用
+
+反馈平台不可用时：
+
+- 保留表单和截图。
+- 显示明确网络或服务错误。
+- 不静默丢弃、不自动切换 GitHub、不打开网页、不自动重试。
+- 其他 GoodBuddy 功能继续可用。
+
+---
+
+## 10. 实施文件
+
+当前实现涉及：
+
+| 文件或目录 | 变更 |
+| --- | --- |
+| `src/shared/feedback-contracts.ts` | 输入、公共 payload、响应和限制 schema |
+| `src/shared/ipc-channels.ts` | `feedbackSubmit` channel |
+| `src/shared/contracts.ts` | `DesktopApi.feedback` |
+| `src/main/feedback/feedback-identity-store.ts` | 随机安装 ID |
+| `src/main/feedback/feedback-screenshot.ts` | 签名、解码和 PNG 标准化 |
+| `src/main/feedback/feedback-http-client.ts` | 固定 Endpoint、严格 TLS、有界响应 |
+| `src/main/feedback/feedback-service.ts` | payload 组装与生命周期 |
+| `src/main/feedback/feedback-ipc.ts` | 独立 trusted sender、schema parse 和 submit handler |
+| `src/main/trusted-ipc-sender.ts` | Main IPC 共享 sender / main Frame 校验 |
+| `src/main/index.ts` | Main service 构造、清理和 IPC 注入 |
+| `src/preload/index.ts` | 窄 `feedback.submit()` bridge |
+| `src/renderer/src/FeedbackDialog.tsx` | 表单和成功/失败流程 |
+| `src/renderer/src/UpdateSettingsSection.tsx` | About 入口卡片 |
+| `src/renderer/src/i18n/locales/*/settingsSections.ts` | 中英文文案 |
+| `src/renderer/src/styles.css` | 令牌化布局与响应式样式 |
+
+每个生产文件应有相邻或现有测试文件覆盖。不要把 Endpoint、截图处理或网络逻辑塞进
+`ipc.ts` 或 React 组件。
+
+---
+
+## 11. 验证
+
+以下 Shared、Main、IPC、Preload 和 Renderer 行为均由相邻或现有自动化测试覆盖；生产
+Endpoint 的健康检查和无副作用 schema 探针也必须在发布前通过。
+
+### 11.1 Shared 合同
+
+- 接受四种反馈类型和有效字段。
+- 拒绝未知字段、空标题、短描述、超长描述、错误邮箱、非 UUID 和多截图。
+- 对截图按字节限制，而不是字符串长度限制。
+- 请求与反馈平台 `schemaVersion: 1` fixture 双向兼容。
+
+### 11.2 Main 单元测试
+
+- 安装 ID 首次创建、并发读取、持久化、损坏隔离和清除。
+- 不复用 Agent、Runtime、Project 或硬件身份。
+- 平台和架构映射。
+- PNG/JPEG/WebP 签名、实际解码、尺寸限制、PNG 重编码和元数据不保留。
+- 无截图 JSON、有截图 multipart、请求 Header 和固定 URL。
+- 独立 Dispatcher 显式 `rejectUnauthorized: true`。
+- 拒绝重定向、非 HTTPS、错误 Origin、超时、超大响应、非 JSON 和错误 response schema。
+- 4xx、429、5xx 和网络错误映射。
+- 手动重试复用 `clientRequestId`。
+- 不同 ID 的并发请求被有界拒绝，清除本地数据期间不能开始新提交。
+
+### 11.3 IPC 与 Preload
+
+- 未知窗口和非主 Frame 被拒绝。
+- Renderer 不能覆盖 `productKey`、版本、平台、架构、安装 ID、Endpoint 或 Header。
+- Preload 只暴露 `feedback.submit()`。
+- Sandbox 测试验证没有通用网络或文件路径能力泄漏。
+
+### 11.4 Renderer
+
+- About 页面展示反馈卡片。
+- 表单字段、字符限制、中英文文案和隐私说明。
+- 普通文本粘贴不被图片处理拦截。
+- 截图选择、预览、替换、移除和 Object URL 清理。
+- 并发截图读取按最新选择生效，关闭对话框后不会留下待处理 Object URL。
+- 失败保留字段、诊断勾选状态，重试使用原 `clientRequestId`。
+- 默认提交不读取诊断且公共 payload 不变；主动附加、描述预算、无记录和读取失败均有覆盖。
+- 成功显示真实编号并清空后续新草稿。
+- Dialog role、初始焦点、Tab 循环、Escape 和焦点恢复。
+- 浅色、深色、窄窗口和 reduced motion。
+
+### 11.5 真实集成
+
+2026-08-25 已从隔离配置的真实 Electron 生产构建完成一次端到端合成提交：
+
+- 标题：`[GOODBUDDY INTEGRATION TEST] 2026-08-25`
+- 类型：`other`
+- 联系邮箱：未填写
+- 截图：GoodBuddy 公共应用图标，经 Main 重编码后以 PNG multipart 上传
+- 服务端编号：`GOODBUDDY-000001`
+
+该结果确认 About UI、Renderer、Preload、trusted IPC、安装身份、Main 图片处理、独立严格
+TLS Dispatcher 和生产 v1 API 调用链可以共同工作。发布候选仍应按以下清单复验：
+
+1. 从打包候选的 About 页面提交一条明确标记的合成反馈。
+2. 可选添加一张不含个人数据的测试截图。
+3. 确认客户端显示的编号与管理后台一致。
+4. 确认版本、平台、架构和语言正确。
+5. 确认服务端只保存标准化 PNG，不含原始图片元数据。
+6. 断网后提交，确认草稿保留；恢复网络后以同一 ID 重试且只产生一条记录。
+7. 使用无效证书的测试服务，确认反馈客户端拒绝连接，即使 GoodBuddy 全局内网 TLS
+   策略允许其他服务继续工作。
+8. 检查 Renderer 和 Main 日志不含正文、邮箱、截图、安装 ID 或凭据。
+
+最终仍需运行仓库统一验证：
+
+```text
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+---
+
+## 12. 发布与兼容性
+
+- `schemaVersion: 1` 与 `/api/v1/feedback` 是同一版本边界。
+- 向请求增加必填字段、修改枚举或改变字段语义属于破坏性变更，必须发布新 schema 或新
+  API 版本。
+- GoodBuddy 对响应执行严格解析。服务端需要扩展响应时，应先协调客户端兼容策略。
+- Endpoint 域名变化属于客户端发布变更，不能依赖 301/302 迁移。
+- 入口发布与 `goodbuddy` 产品启用状态、生产 TLS 和 v1 契约保持同一发布门槛。
+- 此功能不迁移现有用户数据；只新增可重置的随机反馈安装身份。
+- 发布说明应明确：用户现在可以在“关于与更新”内直接提交反馈，邮箱和截图可选；桌面诊断
+  默认不上传，只有用户勾选后才附加有界摘要，并且不会发送对话、Prompt、凭据、文件内容、
+  路径、Provider 原始响应或远端 Agent 日志。
+
+---
+
+## 13. 当前对接状态
+
+截至 2026-08-25：
+
+1. 生产 Origin 已确定为 `https://imp.mesalogo.com`，HTTPS、HSTS 和健康检查正常。
+2. `/api/v1/feedback` 已返回符合 v1 契约的严格校验错误，无副作用探针未创建记录。
+3. `goodbuddy` 产品已启用，实际提交返回 `GOODBUDDY-000001`。
+4. GoodBuddy 客户端已完成 Shared、Main、IPC、Preload、About UI、双语文案、截图和
+   生命周期实现。
+5. 服务端公开 schema、字段长度和 5 MiB 截图上限与客户端一致。
+6. 隔离 Electron 实例已完成浅色、深色、600×800 窄窗口、焦点与背景隔离、截图预览和
+   真实生产提交验收。

docs/features/knowledge-base/README.md

@@ -0,0 +1,34 @@
+# 知识库
+
+知识库已提供本地资料导入、解析、分块、索引、检索、图谱和带来源的知识问答。
+将 Dify、FastGPT 和 RAGFlow 中已有知识库接入同一检索范围仍处于规划阶段，不属于
+当前已提供能力。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [知识库检索与分块增强 PRD](./prd.md) | 检索、分块、诊断和产品验收 |
+| [User Stories](./user-stories.md) | 知识使用者、维护者和调试者场景 |
+| [UI 设计](./ui-design.md) | 当前本地知识库的信息架构、首次使用、状态与高级功能分层 |
+| [实施进度](./progress.md) | 已验证实现事实、验证命令与剩余外部知识库工作 |
+| [本地文本向量技术设计](./local-embedding-technical-design.md) | 本地与兼容向量连接、模型包、索引和进程边界 |
+| [知识检索评估](./retrieval-evaluation.md) | 检索质量评估方法、数据集、指标和门槛 |
+| [外部知识库接入 PRD](./external-knowledge-prd.md) | 外部实例、知识库绑定、检索范围和产品验收 |
+| [外部知识库 User Stories](./external-knowledge-user-stories.md) | 实例配置、添加、使用和故障恢复场景 |
+| [外部知识库逻辑设计](./external-knowledge-logic-design.md) | 状态、不变量、配置优先级和失败规则 |
+| [外部知识库 UI 设计](./external-knowledge-ui-design.md) | 知识库页面、外部实例管理和创建向导交互 |
+| [外部知识库技术设计](./external-knowledge-technical-design.md) | Provider Adapter、凭据、持久化、IPC 和检索标准化 |
+
+## 术语
+
+- **外部实例**：一个由用户配置的 Dify、FastGPT 或 RAGFlow 服务地址及其认证信息。
+- **外部知识库绑定**：GoodBuddy 中的知识库记录与外部实例内一个远端知识库 ID 的只读关联。
+- **Provider 配置**：某一 Provider 检索接口独有的设置，例如 RAGFlow 图谱检索。
+
+外部知识库只提供检索结果。GoodBuddy 不接入外部 App、Chat、Assistant、Workflow
+或 Agent，也不在外部实例中创建、修改、上传或删除知识库内容。远端资料不会批量同步
+或进入本地索引；实际用于回答的有界片段会随引用保存在本地会话中。
+
+本目录尚未拆出统一逻辑设计；当前本地知识库状态规则由 PRD、User Stories 和实现契约
+共同约束。外部知识库继续使用独立逻辑设计，直至进入实施阶段。

docs/features/knowledge-base/external-knowledge-logic-design.md

@@ -0,0 +1,343 @@
+# 外部知识库逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计稿 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联需求 | [外部知识库接入 PRD](./external-knowledge-prd.md) |
+| 关联场景 | [外部知识库 User Stories](./external-knowledge-user-stories.md) |
+
+## 1. 不变量
+
+### EK-I-01 单一知识库身份
+
+本地知识库和外部知识库都使用 GoodBuddy `knowledgeBaseId` 参与聊天范围、检索模式、
+工具授权和活动记录。Provider、实例 ID 和远端知识库 ID 不能替代该授权单位。
+
+对应：`EK-FR-10`、`EK-FR-11`、`EK-US-C1`。
+
+### EK-I-02 外部绑定只读
+
+GoodBuddy 对外部实例只执行连接测试、目录读取、详情读取和检索。添加、编辑、移除
+均只修改本机记录，不调用远端创建、更新、上传或删除接口。
+
+对应：`EK-FR-15`、`EK-US-A3`。
+
+### EK-I-03 凭据不离开 Main
+
+API Key 明文只在 Main 内完成解密并短暂进入请求头。Renderer、Preload 返回值、Runtime、
+Provider 配置、知识库元数据、诊断、日志和错误只能获得凭据状态。
+
+对应：`EK-FR-02`、`EK-FR-11`。
+
+### EK-I-04 Provider 不能定义界面
+
+远端响应只提供数据和能力证据。可显示字段、字段类型、范围、默认值和请求映射均来自
+GoodBuddy 内置、版本化的 Provider Adapter。
+
+对应：`EK-FR-09`、`EK-US-D1`。
+
+### EK-I-05 无静默切换
+
+请求固定使用绑定保存的实例、远端知识库和 Provider 配置。失败时不切换实例、公共云
+地址、认证方式或其他知识库。
+
+对应：`EK-FR-14`、`EK-FR-16`、`EK-US-C4`。
+
+### EK-I-06 零结果与失败分离
+
+成功响应经过过滤后没有片段才是零结果。超时、认证、权限、限流、目标不存在、服务错误
+和响应无效均为失败，不能折叠成零结果。
+
+对应：`EK-FR-14`、`EK-US-D4`。
+
+### EK-I-07 外部证据不可信
+
+Provider 返回的名称、内容、元数据、URL 和错误均视为不可信输入，经过长度、数量、类型
+和 URL 校验后才能显示或进入 Runtime。内容中的指令不能改变系统或工具权限。
+
+对应：`EK-FR-12`。
+
+### EK-I-08 Provider 配置不跨类型复用
+
+Dify、FastGPT 和 RAGFlow 使用各自的判别配置。切换知识库类型或实例 Provider 时，旧类型
+配置不参与新请求，也不能按同名字段自动迁移。
+
+对应：`EK-FR-06`、`EK-FR-09`。
+
+## 2. 对象关系
+
+```text
+ExternalKnowledgeInstance 1 ─── n ExternalKnowledgeBinding
+                                      │
+                                      │ 1:1
+                                      ▼
+                                KnowledgeBase
+```
+
+- 实例可以没有绑定。
+- 外部知识库只能绑定一个实例和一个远端知识库 ID。
+- 同一实例的同一远端知识库默认只允许存在一个绑定，避免重复选择和重复检索。
+- 允许不同实例绑定同名或相同远端 ID，因为实例边界不同。
+- 本地知识库不存在 `ExternalKnowledgeBinding`。
+
+## 3. 实例状态
+
+实例状态由启停、凭据和最近探测三个维度组成，不能用一个布尔值代替。
+
+### 3.1 持久状态
+
+| 维度 | 值 |
+| --- | --- |
+| 启停 | `enabled`、`disabled` |
+| 凭据 | `configured`、`missing`、`unavailable` |
+| 探测 | `untested`、`catalog-ready`、`healthy`、`list-restricted`、`auth-failed`、`unreachable`、`incompatible`、`failed` |
+
+`unavailable` 表示系统安全存储当前无法解密或保存凭据，与用户尚未配置的 `missing` 分开。
+
+### 3.2 派生可用性
+
+| 条件 | 目录读取 | 已绑定知识库检索 | 页面状态 |
+| --- | --- | --- | --- |
+| disabled | 禁止 | 禁止 | 已停用 |
+| missing / unavailable | 禁止 | 禁止 | 缺少凭据 / 凭据不可用 |
+| auth-failed | 禁止 | 禁止 | 认证失效 |
+| unreachable | 可重试 | 可重试 | 无法连接 |
+| incompatible | 禁止 | 禁止 | 接口不兼容 |
+| list-restricted | 禁止 | 允许按 ID 验证与检索 | 需手工指定知识库 |
+| catalog-ready | 允许 | 创建绑定时验证 | 目录可用，检索待验证 |
+| healthy | 允许 | 允许 | 正常 |
+| untested | 允许测试 | 已有绑定可尝试检索 | 未测试 |
+
+保存新实例要求至少完成服务可达和认证验证。目录受限可以保存；检索接口尚未通过时，
+实例不能用于创建绑定。
+
+## 4. 连接测试状态机
+
+```text
+idle
+  └─ test → connecting
+               ├─ network failure → unreachable
+               └─ connected → authenticating
+                                  ├─ 401 → auth-failed
+                                  ├─ incompatible response → incompatible
+                                   └─ authenticated → listing
+                                                         ├─ 403 / unsupported → list-restricted
+                                                         └─ success
+                                                              ├─ no target → catalog-ready
+                                                              └─ target selected → probing-retrieval
+                                                                                       ├─ success / empty → healthy
+                                                                                       └─ failure → failed
+```
+
+检索探测需要一个目标知识库。新增实例尚未选择目标时，目录成功即可把实例保存为“目录可用，
+检索待绑定验证”；创建绑定时补做真实检索。手工模式必须先填写目标 ID，再执行检索探测。
+检索请求正常完成但返回零条结果时，说明接口和目标可访问，可继续创建绑定；失败状态按错误
+分类处理。
+
+每次测试拥有 request ID 和取消信号。用户修改 Provider、地址、凭据或实例后，旧 request ID
+的结果作废。
+
+## 5. 目录读取规则
+
+1. 只有选定、启用且凭据可用的实例可以读取目录。
+2. Provider 列表接口按适配器定义分页，Main 最多向 Renderer 返回 500 个目录项。
+3. FastGPT 列表中的文件夹和知识库必须按类型区分；文件夹不可作为绑定目标。
+4. 列表搜索优先使用 Provider 支持的服务端过滤，不支持时只过滤已经有界加载的当前结果。
+5. 下拉列表以远端 ID 为值，以远端名称为标签；重名时追加短 ID 或父级名称。
+6. 已经绑定的目标显示“已添加”并禁止重复添加。
+7. 远端列表项名称变化不自动修改 GoodBuddy 显示名称，只更新远端名称快照。
+8. 刷新失败时可以保留上次成功目录供查看，但不得用旧目录完成新绑定，直到目标重新验证。
+
+## 6. 创建向导状态
+
+### 6.1 类型
+
+```text
+local | dify | fastgpt | ragflow
+```
+
+`local` 使用现有字段和验证。外部类型使用以下步骤状态：
+
+```text
+provider selected
+→ instance selected
+→ catalog loading / manual ID
+→ remote target selected
+→ configuration valid
+→ retrieval verified
+→ binding created
+```
+
+前置字段变化时，后续状态按下表失效：
+
+| 变化 | 必须清除或重新验证 |
+| --- | --- |
+| 类型 | 实例、远端目标、全部 Provider 配置、测试结果 |
+| 实例 | 远端目标、能力快照、Provider 配置、测试结果 |
+| 远端目标 | 远端详情、能力适用性、测试结果 |
+| 通用或 Provider 配置 | 测试结果 |
+| 显示名称 | 不清除测试结果 |
+
+## 7. 配置模型
+
+### 7.1 通用配置
+
+| 字段 | 范围 | 默认值 | 语义 |
+| --- | --- | --- | --- |
+| `resultLimit` | 1 至 20 | 6 | Provider 结果标准化后最多保留的片段数 |
+| `requestTimeoutMs` | 1,000 至 60,000 | 15,000 | 单次远端请求总时限 |
+| `maxSnippetCharacters` | 500 至 8,000 | 4,000 | 单片段进入 IPC 和 Runtime 前的字符上限 |
+
+Provider 请求仍使用自己的候选数量或 Token 预算。`resultLimit` 只定义 GoodBuddy 最终保留
+上限，不改写 Provider 字段的单位。
+
+### 7.2 Dify 配置
+
+| 字段 | 初始范围 | 说明 |
+| --- | --- | --- |
+| `useDatasetDefaults` | boolean，默认 true | 开启时不发送 `retrieval_model` 覆盖 |
+| `searchMethod` | keyword / semantic / full-text / hybrid | 对应 Dataset Retrieve 检索方式 |
+| `providerTopK` | 1 至适配器上限 | Dify 返回候选数量 |
+| `scoreThresholdEnabled` | boolean | 是否向 Dify 发送分数阈值 |
+| `scoreThreshold` | 0 至 1 | 开启阈值后生效 |
+| `rerankingMode` | weighted-score / reranking-model | 覆盖检索配置时必填 |
+| `rerankingProvider`、`rerankingModel` | 受支持的远端标识 | 选择模型重排时必填 |
+| `keywordWeight`、`vectorWeight` | 0 至 1，总和为 1 | 加权混合模式时生效 |
+| `embeddingProvider`、`embeddingModel` | 受支持的远端标识 | Dify 要求时从知识库详情选择或填写 |
+
+`useDatasetDefaults` 开启时，其余覆盖字段隐藏且不发送。关闭后必须收集当前 Dify 接口
+构造 `retrieval_model` 所需的完整字段，缺少 Provider 或模型标识时不能保存。
+
+### 7.3 FastGPT 配置
+
+| 字段 | 初始范围 | 说明 |
+| --- | --- | --- |
+| `searchMode` | embedding / fullTextRecall / mixedRecall | 搜索方式 |
+| `tokenLimit` | 适配器限制，最高 20,000 | Provider 返回内容预算，不等同结果条数 |
+| `similarity` | 0 至 1 | 最低相关度 |
+| `usingRerank` | boolean | 使用 FastGPT 重排 |
+
+初始版本不开放 FastGPT 查询优化字段，避免把查询发送给 FastGPT 配置的 LLM。检索和重排
+仍可能产生远端 Embedding、Rerank 用量及 API 审计记录，测试与保存配置时必须说明。
+
+### 7.4 RAGFlow 配置
+
+| 字段 | 初始范围 | 说明 |
+| --- | --- | --- |
+| `similarityThreshold` | 0 至 1 | 最低综合相似度 |
+| `vectorSimilarityWeight` | 0 至 1 | 向量分数权重 |
+| `knnTopK` | 1 至适配器上限 | KNN 候选数量，不使用已弃用 `top_k` |
+| `rerankCandidatesCount` | 0 或正整数 | 重排候选数量，实例支持时显示 |
+| `rerankId` | 可选受限字符串 | 远端重排模型 ID |
+| `useKg` | boolean，默认 false | 仅在已有图谱证据成立时允许开启 |
+| `includeKnowledgeCompilation` | boolean，默认 false | 实例支持时显式发送，禁止依赖服务端默认 true |
+| `metadataCondition` | 后续受控编辑器 | 初始版本不接受任意 JSON 文本 |
+
+`parser_config.graphrag.use_graphrag` 描述构建状态，不是检索参数。只有列表、详情或受控
+探测提供已有图谱的证据时，界面才允许开启 `useKg`。Knowledge Compilation 是另一项
+检索能力，必须与旧 GraphRAG 分别显示和保存。
+
+## 8. 配置优先级
+
+生效请求由以下信息组成：
+
+```text
+GoodBuddy 固定安全上限
+∩ 当前 Adapter 支持矩阵
+∩ 当前绑定保存的通用配置和 Provider 配置
+= 本次请求配置
+```
+
+- 固定安全上限不可被实例或用户扩大。
+- 远端知识库自身默认值只用于创建表单的建议值，不在每次请求时覆盖本地已保存值。
+- Provider 增加新字段不会自动启用。
+- 当前实例版本离开 Adapter 支持矩阵，或 Adapter 新版本无法解析已保存配置时，绑定标记
+  配置失效；用户确认前不重写配置。
+- 服务端忽略未知字段不能视为成功。Adapter 只发送已知且受支持的字段。
+
+## 9. 绑定状态
+
+| 状态 | 条件 | 可进入聊天范围 |
+| --- | --- | --- |
+| `ready` | 实例可用，目标最近验证成功，配置有效 | 是 |
+| `untested` | 迁移或新增后尚未完成真实检索 | 否 |
+| `instance-disabled` | 实例停用 | 否 |
+| `credential-error` | 凭据缺失、不可用或认证失败 | 否 |
+| `remote-missing` | 远端目标返回不存在 | 否 |
+| `config-invalid` | 已保存配置不再受支持 | 否 |
+| `temporarily-unavailable` | 超时、限流或服务错误 | 是，但本次显示失败并允许重试 |
+
+短暂故障不立即永久禁用绑定；认证失败、目标不存在和配置失效会改变持久状态。
+
+## 10. 多知识库检索
+
+1. 读取请求冻结的 GoodBuddy 知识库 ID 集合。
+2. 本地库进入本地检索，外部库按实例和绑定构造独立请求。
+3. 同一请求最多选择现有契约允许的 20 个知识库，并遵循全局并发上限。
+4. 每个库单独记录成功、零结果、失败、耗时和截断。
+5. 成功结果按知识库保留来源，不比较不同 Provider 的原始分数。
+6. 上下文拼装使用现有总字符预算，在各成功知识库间采用确定性配额。
+7. 全部失败时返回检索失败；至少一个成功时返回证据和部分失败诊断。
+
+初始版本不对跨 Provider 结果运行统一学习型重排。后续如增加，必须保留原始 Provider
+分数和重排来源，且单独定义评估数据。
+
+## 11. 错误分类
+
+| 稳定错误码 | 用户状态 | 持久影响 |
+| --- | --- | --- |
+| `EXTERNAL_KB_NETWORK` | 无法连接实例 | 无 |
+| `EXTERNAL_KB_TIMEOUT` | 检索超时 | 无 |
+| `EXTERNAL_KB_AUTH` | 认证失效 | 实例标记认证失败 |
+| `EXTERNAL_KB_FORBIDDEN` | 没有访问权限 | 目录或绑定按操作标记受限 |
+| `EXTERNAL_KB_NOT_FOUND` | 远端知识库不存在 | 绑定标记目标不存在 |
+| `EXTERNAL_KB_RATE_LIMITED` | 请求过于频繁 | 无，可显示建议等待 |
+| `EXTERNAL_KB_INCOMPATIBLE` | 接口或配置不兼容 | 实例或绑定标记不兼容 |
+| `EXTERNAL_KB_INVALID_RESPONSE` | 返回内容无法读取 | 无，记录脱敏诊断 |
+| `EXTERNAL_KB_SERVER` | 外部服务处理失败 | 无 |
+| `EXTERNAL_KB_CANCELLED` | 已取消 | 无 |
+
+Provider 原始正文不能直接成为用户错误。Adapter 将其映射为稳定错误码和有界短消息。
+
+## 12. 删除规则
+
+| 操作 | 无绑定 | 有绑定 |
+| --- | --- | --- |
+| 停用实例 | 直接停用 | 允许；绑定变为不可用 |
+| 清除凭据 | 直接清除 | 需要确认；绑定保留但不可用 |
+| 删除实例 | 直接删除 | 阻止直接删除，要求同时移除本地绑定 |
+| 移除绑定 | 删除本地绑定 | 不影响实例和远端知识库 |
+
+删除确认不得使用“删除远端知识库”等文案。
+
+## 13. 需求追踪
+
+| 需求 | 主要逻辑 | User Story |
+| --- | --- | --- |
+| `EK-FR-01` 至 `EK-FR-03` | 实例状态、连接测试状态机 | `EK-US-A1`、`EK-US-A2` |
+| `EK-FR-04`、`EK-FR-05` | 目录读取规则、手工目标验证 | `EK-US-B1`、`EK-US-B2` |
+| `EK-FR-06`、`EK-FR-07`、`EK-FR-08`、`EK-FR-09` | 创建向导状态、配置模型和优先级 | `EK-US-B3`、`EK-US-B4`、`EK-US-D1`、`EK-US-D3` |
+| `EK-FR-10` 至 `EK-FR-13` | 单一身份、多知识库检索和引用规则 | `EK-US-C1` 至 `EK-US-C3`、`EK-US-D2` |
+| `EK-FR-14` | 绑定状态、错误分类和部分失败 | `EK-US-C4`、`EK-US-D4` |
+| `EK-FR-15` | 对象关系和删除规则 | `EK-US-A3` |
+| `EK-FR-16` | 无静默切换、请求冻结和传输风险确认 | `EK-US-C2` |
+
+## 14. 逻辑完整性
+
+已确定：
+
+- 产品入口、对象关系、只读边界和凭据边界。
+- 目录读取与手工 ID 的切换条件。
+- 三种 Provider 的初始配置范围和 RAGFlow 图谱语义。
+- 多知识库部分失败、删除和版本变化规则。
+
+实施前仍需技术验证：
+
+- 选定支持的 Dify、FastGPT、RAGFlow 最低版本，形成固定支持矩阵并保存真实响应 fixture。
+- 验证各版本检索探测的 API 审计、用量和内容修改行为。
+- 确定 Provider 返回 URL 的安全打开策略；未验证前只显示文本定位和远端 ID。
+- 依据真实延迟确定默认并发上限和跨知识库上下文配额。

docs/features/knowledge-base/external-knowledge-prd.md

@@ -0,0 +1,254 @@
+# 外部知识库接入 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计稿 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 关联逻辑 | [外部知识库逻辑设计](./external-knowledge-logic-design.md) |
+| 关联界面 | [外部知识库 UI 设计](./external-knowledge-ui-design.md) |
+| 技术设计 | [外部知识库技术设计](./external-knowledge-technical-design.md) |
+
+## 1. 背景
+
+不少企业已经在内网部署 Dify、FastGPT 或 RAGFlow，并在其中维护制度、产品、研发
+和客服知识。继续要求用户把相同资料导入 GoodBuddy，会产生重复存储、版本分叉和
+额外维护成本。
+
+GoodBuddy 需要把这些已有知识库加入当前知识库列表和聊天检索范围。外部系统只
+承担知识存储与检索，问题理解、上下文组织、模型回答、Agent 和工具执行仍由
+GoodBuddy 负责。
+
+## 2. 产品决策
+
+1. 外部知识库属于现有“知识库”功能，不新增一级页面，也不放入全局设置中心。
+2. 知识库页面标题区增加“管理外部实例”；现有“新建知识库”向导增加知识库类型。
+3. 一个外部实例代表一个 Provider 服务地址和一组凭据，可绑定多个远端知识库。
+4. 一个外部知识库绑定在 GoodBuddy 中仍是一个 `KnowledgeBase`，可以进入现有聊天
+   范围、每次先检索、模型按需检索和检索测试流程。
+5. 外部知识库保持远端检索，不批量同步或本地索引远端文档、分块、向量和图谱，也不
+   显示“已同步”。实际进入回答的有界片段和引用随会话保存在本机，并遵循会话删除规则。
+6. Dify、FastGPT 和 RAGFlow 只使用知识库列表、详情和检索接口。App、Chat、
+   Assistant、Workflow 和 Agent API 均不接入。
+7. 用户点击“添加”只创建本地绑定，不在外部实例中创建知识库；移除绑定也不删除
+   远端知识库。
+8. 通用配置只包含跨 Provider 语义一致的选项。检索算法、阈值、重排和图谱开关
+   由 Provider 配置承担。
+9. Provider 专属字段由 GoodBuddy 内置适配器定义。外部服务器不能下发任意表单、
+   脚本或字段 Schema。
+10. API Key 在用户输入表单和受限 IPC 中短暂存在，由 Main 进程加密保存并用于请求；
+    保存后不回传 Renderer，也不进入 Runtime、日志、普通元数据和检索引用。
+
+## 3. 目标
+
+### 3.1 用户目标
+
+- 在知识库页面配置企业现有的 Dify、FastGPT 或 RAGFlow 实例。
+- 新建知识库时选择 Provider、实例和远端知识库，不手工复制资料。
+- 在同一知识库列表和聊天选择器中使用本地与外部知识库。
+- 按 Provider 能力调整检索参数，例如 RAGFlow 图谱检索。
+- 明确看到查询发送到哪个实例、检索是否成功以及引用来自哪里。
+- 连接失效后能更新凭据、重试或更换远端知识库，不丢失其他知识库配置。
+
+### 3.2 产品目标
+
+- 保持现有知识库 ID 作为聊天和 Runtime 的统一授权单位。
+- 让三种 Provider 的结果进入同一有界证据与引用契约。
+- 保留每种 Provider 的有效检索能力，不用最低公共字段覆盖全部差异。
+- 将实例认证与知识库绑定分离，使一个实例可以服务多个绑定。
+- 对 Provider 版本差异、列表权限关闭和部分检索失败提供可诊断状态。
+
+## 4. 非目标
+
+本功能不包含：
+
+- 调用 Dify App、FastGPT 应用、RAGFlow Chat 或任何外部 Agent。
+- 使用外部系统生成最终回答或维护外部会话。
+- 在外部实例中创建、编辑、删除知识库、文档或分块。
+- 向外部实例上传文件、网页、剪贴板、完整会话或本地知识库内容。
+- 批量同步或本地索引外部文档、分块、Embedding、图谱或模型配置。回答实际引用的
+  有界片段仍会随会话保存在本机。
+- 跨实例复制、迁移或统一管理外部知识内容。
+- 企业 SSO、组织级凭据下发、文档级 ACL 映射或 ShareServer 管理策略。
+- 自定义脚本适配器和任意 HTTP 请求模板。兼容检索 API 需要独立设计。
+- 把不同 Provider 的原始分数解释成可直接比较的统一质量分数。
+
+## 5. 核心对象
+
+| 对象 | 定义 | 用户可执行操作 |
+| --- | --- | --- |
+| 外部实例 | Provider、服务地址、凭据和已探测能力 | 添加、测试、编辑、停用、删除 |
+| 外部知识库目录项 | 实例列表接口返回的远端知识库摘要 | 刷新、选择 |
+| 外部知识库绑定 | GoodBuddy 知识库与远端知识库的只读关联 | 添加、改名、配置、测试、移除 |
+| Provider 配置 | 适配器支持的检索参数 | 查看、修改、恢复默认 |
+| 标准化检索结果 | Provider 结果转换后的片段、来源和诊断 | 查看、引用、提供给 Runtime |
+
+## 6. 主要流程
+
+### 6.1 管理外部实例
+
+1. 用户在知识库页面点击“管理外部实例”。
+2. 页面列出实例名称、Provider、服务地址、状态和已绑定知识库数量。
+3. 用户添加实例，填写名称、Provider、服务地址和 API Key。
+4. “测试连接”分别验证服务可达、认证、知识库列表和检索能力。
+5. 用户保存后，API Key 被加密保存，列表只显示凭据已配置。
+
+列表接口不可用但已知远端知识库 ID 可检索时，实例可以保存为“需手工指定知识库”。
+服务不可达或认证失败时不得保存为可用实例；用户可以保留表单并修正。
+
+### 6.2 添加外部知识库
+
+1. 用户点击现有“新建知识库”。
+2. 在“知识库类型”中选择“本地”、Dify、FastGPT 或 RAGFlow。
+3. 选择外部类型后，左侧选择同 Provider 的外部实例。
+4. GoodBuddy 自动读取远端知识库列表，并填入可搜索下拉框。
+5. 列表权限不可用时，用户可以手工填写远端知识库 ID。
+6. 用户选择一个远端知识库，填写 GoodBuddy 显示名称。
+7. 右侧展示通用配置和当前 Provider 的专属配置。
+8. 用户填写测试查询并执行一次有界检索；请求成功后创建本地绑定，零结果不算失败。
+
+添加完成后沿用现有知识库规则，把新绑定加入当前聊天选择，但不会重新启用用户此前
+取消的其他知识库。
+
+### 6.3 使用外部知识库
+
+外部绑定出现在现有知识库列表和聊天知识范围中，持续显示 Provider 与实例名称。
+检索请求只发送本次查询文本和该绑定已保存的检索配置。返回片段经过 Main 校验、
+截断和标准化后，才作为不可信证据提供给 Runtime。
+
+一次请求选择多个知识库时，本地与外部检索可以并行。单个外部知识库失败不扩大
+检索范围，也不切换其他实例；其他知识库成功时可继续回答，并显示部分失败。
+
+### 6.4 编辑和移除
+
+- 修改显示名称只影响 GoodBuddy 本地名称。
+- 修改 Provider 配置只影响后续检索，不写回远端知识库。
+- 更换远端知识库属于重新绑定，保存前必须重新测试。
+- 删除外部实例前必须处理其所有绑定：取消，或明确移除这些本地绑定。
+- 移除绑定只删除 GoodBuddy 中的绑定和检索配置，不调用远端删除接口。已经保存在历史
+  会话中的引用继续可读，但不再提供依赖当前实例的刷新操作。
+
+## 7. 功能需求
+
+### EK-FR-01 知识库页面入口
+
+知识库页面必须同时提供“管理外部实例”和“新建知识库”。外部实例管理不得迁移到
+全局设置中心或创建新的一级导航。
+
+### EK-FR-02 实例配置
+
+实例必须包含唯一 ID、显示名称、Provider、规范化服务地址、凭据状态、启停状态、
+最近测试结果和适配器能力快照。用户可以使用 `keep`、`replace`、`clear` 语义更新凭据。
+
+### EK-FR-03 分项连接测试
+
+连接测试必须区分服务可达、认证、列表读取和测试检索。新增实例尚未选择知识库时，
+测试检索显示“绑定知识库时验证”，不能伪装成已通过。测试错误应包含可处理原因，
+不得返回凭据、Authorization、完整响应正文或内部堆栈。
+
+### EK-FR-04 远端目录读取
+
+选择实例后自动读取有界、可分页的远端知识库列表。列表支持加载、刷新、搜索、空结果、
+权限不足和失败状态，且异步旧响应不得覆盖当前实例结果。
+
+### EK-FR-05 手工指定远端 ID
+
+列表接口不受支持或没有权限时，允许手工填写远端知识库 ID 和显示名称。保存前必须通过
+该 ID 的详情或检索验证；不能只验证字符串非空。
+
+### EK-FR-06 知识库类型
+
+新建向导必须提供“本地”、Dify、FastGPT、RAGFlow 四种类型。本地类型保持现有创建、
+存储模式、图谱和导入行为；外部类型不得显示本地分块、导入或索引设置。
+
+### EK-FR-07 两栏配置
+
+外部类型的创建向导在常规宽度使用左右两栏。左侧负责 Provider、实例、远端知识库和
+显示名称；右侧负责通用配置与 Provider 专属配置。窄窗口按来源、通用配置、专属配置
+顺序堆叠。
+
+### EK-FR-08 通用配置
+
+通用配置至少包含最终返回片段数、请求超时和单片段最大字符数。数值必须有固定范围，
+由 Main 再次校验。Provider 的 Top K、Token 预算或 Page Size 不得冒充同一字段。
+
+### EK-FR-09 Provider 专属配置
+
+Provider 配置使用受版本控制的判别联合。界面只展示当前适配器和已确认实例版本支持的字段；
+不支持的已保存字段必须明确显示为失效配置并阻止静默提交。
+
+### EK-FR-10 统一知识库列表
+
+外部绑定与本地知识库出现在同一列表，但必须显示 Provider、实例和“远端检索”状态。
+外部绑定不得显示本地文档数、同步、分块、向量覆盖率或本地图谱状态。
+
+### EK-FR-11 统一检索范围
+
+现有聊天知识范围、多选上限、`auto` 和 `always` 模式继续以 GoodBuddy 知识库 ID 工作。
+Runtime 只能获得标准化后的有界证据，不能获得实例地址、API Key 或 Provider 原始响应。
+
+### EK-FR-12 引用来源
+
+每条外部结果必须保留 Provider、实例 ID、远端知识库 ID、文档名称和片段。远端文档 ID、
+远端片段 ID、页码、URL、分数及其他定位只在 Provider 实际返回时保存，不得补造。
+
+### EK-FR-13 检索测试
+
+现有检索测试入口支持外部绑定。页面显示生效配置、总耗时、Provider 耗时、返回数量、
+截断状态和脱敏错误。外部测试不创建聊天、调用 GoodBuddy LLM 或修改远端内容。
+
+### EK-FR-14 故障隔离
+
+认证失败、超时、限流、目标删除、版本不兼容和响应无效必须分别报告。多知识库检索中，
+单项失败不得改写为零结果，也不得阻止已成功证据进入回答。
+
+### EK-FR-15 生命周期边界
+
+删除实例、移除绑定、清除凭据和更换远端目标必须经过明确确认。任何操作都不得调用
+Provider 的远端创建、更新、上传或删除接口。
+
+### EK-FR-16 网络与数据说明
+
+界面必须说明查询会发送到所选实例，并列出不会发送的内容。请求遵循用户配置的服务地址
+和当前内网兼容模式，不自动切换地址、Provider 或公共云端点。HTTP 或放宽证书校验会
+传输 API Key，测试和保存实例前必须显示风险并取得针对当前地址的明确确认。
+
+## 8. Provider 初始范围
+
+| Provider | 目录能力 | 检索能力 | 首批专属配置 |
+| --- | --- | --- | --- |
+| Dify | 知识库列表与详情 | Dataset Retrieve | 使用知识库默认配置，或完整覆盖检索方式、Top K、Score 阈值及 Rerank 模式 |
+| FastGPT | 知识库层级列表与详情 | Dataset Search Test | 搜索模式、Token 上限、相似度、Rerank |
+| RAGFlow | Dataset 列表与详情 | Retrieval | 相似度、向量权重、KNN Top K、Rerank、图谱检索、Knowledge Compilation |
+
+“首批专属配置”表示适配器允许表达的字段，不保证每个实例版本都支持。具体显隐由能力
+探测和[逻辑设计](./external-knowledge-logic-design.md)共同决定。
+
+## 9. 产品验收
+
+1. 用户可以在知识库页面完成三种 Provider 的实例添加、连接测试、编辑和删除。
+2. 每种 Provider 至少通过一个真实自部署实例完成列表读取、绑定和检索。
+3. 列表权限关闭时，可以通过手工 ID 添加并验证一个可检索知识库。
+4. 本地与外部知识库可以同时进入一次聊天检索，引用来源可区分。
+5. RAGFlow 支持时可以开启图谱检索；不支持时不发送该字段。
+6. 外部知识库详情不出现本地导入、同步、分块和索引操作。
+7. 删除绑定或实例不会改变远端知识库和文档。
+8. 保存完成后的 Renderer 状态、Runtime、SQLite 普通元数据、日志和错误中均找不到明文
+   API Key。
+9. 超时、401/403、404、429、5xx 和响应格式错误都有独立测试并显示准确状态。
+10. 中断、切换实例或关闭向导后，过期列表与测试响应不会写入当前表单。
+11. FastGPT 页面说明检索会记录远端 API 使用情况，并可能产生 Embedding 或 Rerank 用量。
+12. HTTP 或放宽证书校验的实例未经明确确认不能保存或发送 API Key。
+
+## 10. 外部资料
+
+以下链接用于核对初始适配范围，实施时仍须用受支持版本的真实实例和响应 fixture 验证：
+
+- [Dify Knowledge API](https://docs.dify.ai/en/guides/knowledge-base/knowledge-and-documents-maintenance/maintain-dataset-via-api)
+- [Dify Retrieve Chunks](https://docs.dify.ai/en/api-reference/knowledge-bases/retrieve-chunks-from-a-knowledge-base-test-retrieval)
+- [FastGPT 知识库接口](https://doc.fastgpt.io/zh-CN/openapi/dataset)
+- [RAGFlow HTTP API](https://ragflow.io/docs/dev/http_api_reference)
+- [RAGFlow Release Notes](https://ragflow.io/docs/dev/release_notes)

docs/features/knowledge-base/external-knowledge-technical-design.md

@@ -0,0 +1,580 @@
+# 外部知识库技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计稿 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 产品需求 | [外部知识库接入 PRD](./external-knowledge-prd.md) |
+| 逻辑设计 | [外部知识库逻辑设计](./external-knowledge-logic-design.md) |
+| UI 设计 | [外部知识库 UI 设计](./external-knowledge-ui-design.md) |
+
+## 1. 设计约束
+
+1. 外部知识库扩展现有知识库领域，不建立独立检索工具、聊天范围或 Runtime 权限模型。
+2. 外部绑定使用远端检索，不落地远端文档、分块、向量和图谱。
+3. 所有网络、凭据、Provider 响应校验和结果标准化都在 Main 完成。
+4. Renderer 只能通过受限 IPC 管理实例、读取目录、保存绑定和发起测试。
+5. Dify、FastGPT、RAGFlow 使用独立 Adapter 和判别配置，不通过任意 JSON 请求模板实现。
+6. 首次实现只调用无内容修改语义的列表、详情和检索接口。
+7. Provider API 变化通过真实 fixture、Adapter 版本和能力快照处理，不通过猜测字段兼容。
+
+## 2. 现有代码边界
+
+当前实现中的主要扩展点：
+
+| 边界 | 现有位置 | 需要的变化 |
+| --- | --- | --- |
+| 共享知识契约 | `src/shared/knowledge-contracts.ts`、`src/shared/contracts.ts` | 增加实例、绑定、Provider 配置和外部引用判别联合 |
+| IPC 名称 | `src/shared/ipc-channels.ts` | 增加实例和目录操作通道 |
+| Preload | `src/preload/index.ts` | 暴露受限、类型化的外部知识库 API |
+| Main IPC | `src/main/ipc.ts` | 校验输入、调用服务、投影脱敏结果 |
+| 知识服务 | `src/main/knowledge/knowledge-service.ts` | 按知识库来源分派本地或外部检索 |
+| 数据库 | `src/main/knowledge/knowledge-database.ts` | 增加实例、绑定和迁移 |
+| 内部类型 | `src/main/knowledge/types.ts` | 增加 Provider、实例、绑定和标准化结果类型 |
+| 知识页面 | `src/renderer/src/KnowledgeWorkspace.tsx` | 实例管理、创建向导类型和外部详情 |
+| 检索测试 | `src/renderer/src/KnowledgeRetrievalWorkbench.tsx` | 支持本地与外部诊断判别联合 |
+| 聊天预检索 | `src/main/ipc.ts` | 统一调用 Provider-aware 检索编排 |
+| Agent 知识工具 | `src/main/agent/knowledge-mcp-gateway.ts` | 与预检索复用同一编排和引用标准化 |
+
+外部 Provider 不是 `KnowledgeSourceType`。现有 `file | directory | url` 表示会进入本地
+文档、分块和索引的资料来源；把远端绑定塞入该枚举会错误触发同步、分块和来源打开逻辑。
+
+## 3. 模块设计
+
+建议增加：
+
+```text
+src/main/knowledge/external/
+├─ external-knowledge-service.ts
+├─ external-knowledge-store.ts
+├─ external-knowledge-errors.ts
+├─ external-knowledge-http.ts
+├─ external-knowledge-registry.ts
+├─ external-knowledge-normalizer.ts
+└─ providers/
+   ├─ dify-adapter.ts
+   ├─ fastgpt-adapter.ts
+   └─ ragflow-adapter.ts
+```
+
+职责：
+
+- `ExternalKnowledgeService`：实例、目录、绑定、测试和检索编排。
+- `ExternalKnowledgeStore`：实例和绑定持久化，凭据加解密。
+- `ExternalKnowledgeHttp`：超时、取消、大小限制、地址和响应读取。
+- `ExternalKnowledgeRegistry`：按 Provider 返回内置 Adapter，不接受运行时插件注册。
+- `ExternalKnowledgeNormalizer`：统一结果边界、截断和引用。
+- Adapter：构造固定端点与请求，解析 Provider 响应，声明静态配置和能力条件。
+
+`KnowledgeService` 继续作为聊天、检索测试和 MCP 网关的统一入口。它根据
+`KnowledgeBase.kind` 调用现有本地检索或 `ExternalKnowledgeService.retrieve`。
+
+## 4. Provider Adapter
+
+```ts
+type ExternalKnowledgeProvider = 'dify' | 'fastgpt' | 'ragflow'
+
+interface ExternalKnowledgeAdapter<PersistedConfig, CapabilitySnapshot> {
+  readonly provider: ExternalKnowledgeProvider
+  readonly configVersion: number
+
+  normalizeBaseUrl(input: string): URL
+  testConnection(context: AdapterContext): Promise<ConnectionTestResult>
+  listKnowledgeBases(
+    context: AdapterContext,
+    input: CatalogPageInput
+  ): Promise<CatalogPage>
+  getKnowledgeBase(
+    context: AdapterContext,
+    remoteKnowledgeBaseId: string
+  ): Promise<RemoteKnowledgeBaseSummary>
+  probeRetrieval(
+    context: AdapterContext,
+    input: ProviderRetrieveInput<PersistedConfig>
+  ): Promise<ProviderRetrieveResult>
+  retrieve(
+    context: AdapterContext,
+    input: ProviderRetrieveInput<PersistedConfig>
+  ): Promise<ProviderRetrieveResult>
+  parseCapabilities(input: unknown): CapabilitySnapshot
+  validateConfig(
+    input: unknown,
+    capabilities: CapabilitySnapshot
+  ): PersistedConfig
+}
+```
+
+`probeRetrieval` 可以复用 `retrieve`，但必须使用用户在创建向导中明确输入的测试查询。
+不得生成会泄露组织信息的默认问题，不得调用 Provider 的 App 或模型问答接口，也不得
+修改远端知识内容。Provider 自身记录 API 审计或计算检索用量不属于内容修改，必须由界面
+提前说明。
+
+Adapter 返回数据对象，不返回 React 组件、HTML 或远端 Schema。Renderer 中的配置定义
+由共享的 Provider 判别联合和本地字段描述生成。
+
+## 5. 共享契约
+
+### 5.1 实例
+
+```ts
+type CredentialMutation =
+  | { action: 'keep' }
+  | { action: 'replace'; value: string }
+  | { action: 'clear' }
+
+interface ExternalKnowledgeInstanceSummary {
+  id: string
+  name: string
+  provider: 'dify' | 'fastgpt' | 'ragflow'
+  baseUrl: string
+  enabled: boolean
+  credentialStatus: 'configured' | 'missing' | 'unavailable'
+  probeStatus:
+    | 'untested'
+    | 'catalog-ready'
+    | 'healthy'
+    | 'list-restricted'
+    | 'auth-failed'
+    | 'unreachable'
+    | 'incompatible'
+    | 'failed'
+  detectedVersion?: string
+  bindingCount: number
+  lastTestedAt?: string
+  lastErrorCode?: string
+}
+```
+
+Renderer 输入使用 `CredentialMutation`，因此新密钥会在输入控件和该次 IPC 中短暂存在。
+Main 返回值永远没有 `credential`、`apiKey`、`authorization` 或加密 envelope。
+
+### 5.2 绑定
+
+```ts
+interface ExternalKnowledgeBinding {
+  knowledgeBaseId: string
+  instanceId: string
+  remoteKnowledgeBaseId: string
+  remoteName: string
+  remoteDescription?: string
+  commonConfig: ExternalKnowledgeCommonConfig
+  providerConfig: DifyConfig | FastGptConfig | RagflowConfig
+  providerConfigVersion: number
+  adapterVersion: number
+  lastVerifiedAt?: string
+}
+```
+
+`providerConfig` 必须带 `provider` 判别字段，且与实例 Provider 一致。`remoteName` 是用于
+显示和变化检测的快照，不是授权标识。
+
+### 5.3 标准化结果
+
+现有 `KnowledgeRetrievalResult` 假定结果映射到本地 `documentId/sourceId/chunkId`。需要改为
+引用定位的判别联合，同时保持现有调用方可按统一字段读取片段：
+
+```ts
+type KnowledgeReferenceLocator =
+  | {
+      kind: 'local'
+      documentId: string
+      sourceId: string
+      chunkId: string
+      parentChunkId?: string
+    }
+  | {
+      kind: 'external'
+      provider: ExternalKnowledgeProvider
+      instanceId: string
+      remoteKnowledgeBaseId: string
+      remoteDocumentId?: string
+      remoteChunkId?: string
+      providerScore?: number
+      location?: string
+      sourceUrl?: string
+      metadata?: Record<string, string | number | boolean | null>
+    }
+
+interface UnifiedKnowledgeRetrievalResult {
+  knowledgeBaseId: string
+  documentTitle: string
+  sourceDisplayName: string
+  snippet: string
+  relevance?: number
+  rank: number
+  locator: KnowledgeReferenceLocator
+}
+```
+
+`remoteDocumentId` 和 `remoteChunkId` 只保存 Provider 实际返回的标识，缺失时不得从标题、
+序号或内容哈希推导。`providerScore` 保留原始值，但不改名为统一 `relevance`。只有经过
+单独定义和验证的归一化算法才能填写跨 Provider `relevance`。初始跨库拼装按结果配额和
+稳定 Provider 顺序工作，不按原始分数混排。
+
+所有共享 Schema 使用严格对象并限制：
+
+- 查询不超过 4,000 字符；同时遵守 Provider 更小限制，例如 Dify 当前公开接口的
+  250 字符限制，超出时在发送前明确失败，不静默截断查询。
+- 单次目录页不超过 100 项，总目录最多 500 项。
+- 标准化结果最多 20 条，单片段最多 8,000 字符。
+- 标题、ID、定位、URL 和元数据键值均设独立上限。
+- Provider 原始响应总字节数设固定上限，超限立即取消读取。
+
+## 6. 持久化
+
+### 6.1 数据库变化
+
+保留现有 `knowledge_bases` 表，增加：
+
+```sql
+ALTER TABLE knowledge_bases
+  ADD COLUMN kind TEXT NOT NULL DEFAULT 'local'
+  CHECK (kind IN ('local', 'external'));
+```
+
+增加实例表：
+
+```sql
+CREATE TABLE external_knowledge_instances (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  provider TEXT NOT NULL CHECK (provider IN ('dify', 'fastgpt', 'ragflow')),
+  base_url TEXT NOT NULL,
+  enabled INTEGER NOT NULL CHECK (enabled IN (0, 1)),
+  credential_envelope_json TEXT,
+  probe_status TEXT NOT NULL,
+  detected_version TEXT,
+  capabilities_json TEXT NOT NULL,
+  transport_security TEXT NOT NULL,
+  transport_risk_accepted_url TEXT,
+  transport_risk_accepted_at TEXT,
+  last_tested_at TEXT,
+  last_error_code TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+```
+
+增加绑定表：
+
+```sql
+CREATE TABLE external_knowledge_bindings (
+  knowledge_base_id TEXT PRIMARY KEY
+    REFERENCES knowledge_bases(id) ON DELETE CASCADE,
+  instance_id TEXT NOT NULL
+    REFERENCES external_knowledge_instances(id) ON DELETE RESTRICT,
+  remote_knowledge_base_id TEXT NOT NULL,
+  remote_name TEXT NOT NULL,
+  remote_description TEXT,
+  common_config_json TEXT NOT NULL,
+  provider_config_json TEXT NOT NULL,
+  provider_config_version INTEGER NOT NULL,
+  adapter_version INTEGER NOT NULL,
+  binding_status TEXT NOT NULL,
+  last_verified_at TEXT,
+  last_success_at TEXT,
+  last_error_code TEXT,
+  UNIQUE(instance_id, remote_knowledge_base_id)
+);
+```
+
+已有知识库迁移为 `kind = 'local'`。外部知识库仍保留现有名称、描述和创建时间，但本地
+`storageMode`、图谱、分块和本地检索设置不进入外部请求；后续可以在数据库重构时再移除
+这些历史必填默认值，本功能不为此扩大迁移范围。
+
+### 6.2 凭据
+
+复用 `SettingsCredentialCipher` 和 Electron `safeStorage`：
+
+- `replace`：Main 加密新值后在一个事务中替换 envelope。
+- `keep`：不读取、不重写现有 envelope。
+- `clear`：确认后删除 envelope，并把实例凭据状态设为缺失。
+- 安全存储不可用时拒绝新增或替换，不降级为明文。
+- 解密只发生在发起请求前；请求结束后不缓存明文。
+
+实例导出、诊断和数据库普通 JSON 视图均排除 `credential_envelope_json`。
+
+## 7. IPC 设计
+
+建议增加独立通道：
+
+```text
+knowledge:external-instances:list
+knowledge:external-instances:test
+knowledge:external-instances:save
+knowledge:external-instances:set-enabled
+knowledge:external-instances:delete
+knowledge:external-catalog:list
+knowledge:external-catalog:get
+knowledge:external-bindings:create
+knowledge:external-bindings:update
+knowledge:external-bindings:remove
+knowledge:external-retrieval:test
+```
+
+所有 Handler 必须：
+
+1. `assertTrustedSender`。
+2. 用共享 Zod Schema 解析严格输入。
+3. 根据实例 ID 在 Main 读取地址和凭据，不接受 Renderer 在检索请求中重复传入。
+4. 使用稳定错误码返回脱敏错误。
+5. 对网络操作支持 AbortSignal、总超时和响应大小限制。
+
+目录和测试请求返回 `requestId`。Renderer 仍需校验当前类型、实例和目标与响应关联，避免
+旧响应覆盖新表单。
+
+## 8. HTTP 边界
+
+### 8.1 服务地址
+
+- 只接受 `http:` 和 `https:`。
+- 拒绝用户名、密码、查询和片段。
+- Adapter 负责规范化 Provider 所需 API 根路径，避免用户填写完整操作端点。
+- 请求只能拼接 Adapter 内置相对路径，远端目录项或错误不能改变目标 URL。
+- 重定向默认拒绝；若某 Provider 的受支持部署确需重定向，只允许同源且不得跨跳转发送
+  Authorization。
+- 当前全局“内网兼容模式”决定是否允许 HTTP 和非标准 HTTPS 证书；操作开始后冻结该值。
+- HTTP 或实际使用证书例外时，Main 返回 `transportSecurity` 风险状态。用户必须针对规范化
+  后的当前地址明确确认，才能保存实例或发送 API Key；地址变化立即使旧确认失效。
+- 不进行公共云回退，不把自部署地址替换成 Provider 官方地址。
+
+用户明确配置内网地址属于产品用途，因此不能采用禁止私网地址的通用 SSRF 规则。安全边界
+依靠显式实例配置、Main-only 请求、固定端点、无任意方法和无远端 URL 跟随。
+
+### 8.2 请求限制
+
+- 默认超时 15 秒，用户可在 1 至 60 秒内调整。
+- 目录、详情和检索分别设置响应字节上限。
+- JSON 解析后仍执行深度、数组数量、字符串长度和未知字段策略。
+- 默认不自动重试。用户重试或上层下一次检索会产生新请求。
+- 取消、应用关闭和实例删除立即终止相关请求。
+- 日志只记录 Provider、实例 ID、操作、状态码、稳定错误码、耗时和字节数。
+
+## 9. Provider 映射
+
+本节记录 2026-09-03 核对的初始公开接口。实施时应把每个受支持版本的真实响应保存为
+去敏 fixture，并以 fixture 和真实实例测试作为发布依据。
+
+### 9.1 Dify
+
+| 操作 | 接口 |
+| --- | --- |
+| 列表 | `GET /v1/datasets` |
+| 检索 | `POST /v1/datasets/{dataset_id}/retrieve` |
+| 认证 | `Authorization: Bearer <knowledge-api-key>` |
+
+Adapter 只接受 Knowledge Service API Key，不调用应用 `/info`、Chat 或 Workflow。默认不
+发送 `retrieval_model`，沿用远端知识库配置。用户选择覆盖时，Adapter 必须一次收集并验证
+当前接口要求的搜索方式、Top K、阈值、`reranking_mode`，以及相应的 Rerank Provider/模型
+或关键词/向量权重与 Embedding Provider/模型；缺少任何必填标识时不构造请求。响应从
+`records[].segment`、`score`、文档名称和元数据提取标准化引用。
+
+Dify 当前文档限制查询不超过 250 字符。GoodBuddy 不静默截断；超出时检索测试和聊天
+诊断返回 Provider 限制，并允许后续单独设计查询压缩策略。
+
+### 9.2 FastGPT
+
+| 操作 | 接口 |
+| --- | --- |
+| 列表 | `POST /api/core/dataset/list` |
+| 详情 | `GET /api/core/dataset/detail?id=...` |
+| 检索 | `POST /api/core/dataset/searchTest` |
+| 认证 | `Authorization: Bearer <api-key>` |
+
+列表响应同时包含文件夹和知识库，只有 `type = dataset` 可以绑定。检索映射 `datasetId`、
+`text`、Token `limit`、`similarity`、`searchMode` 和 `usingReRank`。初始版本不发送查询优化
+字段，避免调用 FastGPT 配置的 LLM。
+响应从 `q`、`a`、`sourceName`、`sourceId`、`collectionId` 和 `score` 构造片段与引用。
+
+FastGPT 4.15.0 起部署实例的 `/apidoc/devapi` 是接口事实来源，手工文档可能落后。支持矩阵
+必须按真实版本测试；不能因为健康页可访问就假定列表和检索 Schema 相同。`searchTest`
+可能记录 `SEARCH_TEST` 等远端审计并更新 API Key 用量；Embedding 和 Rerank 也可能产生
+费用。GoodBuddy 将这些行为作为检索成本显示，不宣称该接口没有副作用。
+
+### 9.3 RAGFlow
+
+| 操作 | 接口 |
+| --- | --- |
+| 列表/详情 | `GET /api/v1/datasets` |
+| 检索 | `POST /api/v1/retrieval` |
+| 认证 | `Authorization: Bearer <api-key>` |
+
+检索映射 `question`、`dataset_ids`、`page_size`、`similarity_threshold`、
+`vector_similarity_weight`、`knn_top_k`、重排、`use_kg` 和
+`include_knowledge_compilation`。不发送已弃用的 `top_k`。响应从 `data.chunks` 和
+`data.doc_aggs` 提取片段、文档、位置和原始相似度。
+
+图谱规则：
+
+- `parser_config.graphrag` 或等价详情字段作为已有图谱的证据，不写回。
+- `use_kg` 是检索时开关，只在已有图谱和受支持版本均确认后发送。
+- Knowledge Compilation 与旧 GraphRAG 分别建模。
+- `include_knowledge_compilation` 使用本地保存的显式布尔值，初始默认 false；即使服务端
+  默认 true，也不依赖字段省略获得隐式行为。
+- Provider 没有返回图节点或路径证据时，GoodBuddy 不生成图谱引用。
+
+## 10. 检索编排
+
+```text
+retrieveMany(knowledgeBaseIds, query, requestContext)
+  ├─ load and authorize GoodBuddy knowledge bases
+  ├─ partition local and external bindings
+  ├─ local: existing retrieval path
+  ├─ external: bounded concurrent adapter requests
+  ├─ validate and normalize each response
+  ├─ allocate deterministic context budget
+  └─ return evidence plus per-library diagnostics
+```
+
+预检索和 `knowledge_search` 工具必须调用同一个 `retrieveMany`。如果只修改聊天预检索而
+未修改 `KnowledgeMcpGateway`，`auto` 和 `always` 会产生不同能力，这是阻断发布的问题。
+
+### 10.1 上下文预算
+
+- 每个知识库先保留不超过其 `resultLimit` 的结果。
+- 先给每个成功知识库一个最小有界配额，再按稳定顺序分配剩余字符。
+- 不用不同 Provider 原始分数决定跨库优先级。
+- 片段截断在 Main 完成并在引用中标记。
+- 相同实例的多个绑定仍按绑定分别请求，除非 Provider 明确支持且 Adapter 实现等价的多
+  Dataset 请求；合并不得改变每个绑定的配置和诊断。
+
+### 10.2 失败结果
+
+返回结构包含每个知识库的：
+
+```ts
+interface KnowledgeRetrievalOutcome {
+  knowledgeBaseId: string
+  status: 'success' | 'empty' | 'failed' | 'cancelled'
+  durationMs: number
+  resultCount: number
+  errorCode?: ExternalKnowledgeErrorCode
+  truncated: boolean
+}
+```
+
+至少一个 `success` 或 `empty` 表示检索编排完成；全部 `failed/cancelled` 时上层显示整体失败。
+
+## 11. 引用与来源打开
+
+外部结果不能进入依赖本地数据库的 `referenceContext` 和 `openSource` 路径。
+
+- 引用详情直接使用请求时保存的标准化片段和定位。
+- Main 可以按远端片段 ID 提供一次只读重新读取，但初始版本不要求。
+- Provider 返回 URL 只作为不可信元数据保存。没有独立 URL 规则和真实实例验证前，
+  Renderer 不显示打开链接操作。
+- 活动和会话持久化保存标准化引用，其中包含实际用于回答的有界远端片段；这属于引用
+  留存，不是批量同步或本地索引。删除会话或对应活动时按现有生命周期删除该副本。
+- 实例删除后，历史引用仍显示 Provider、知识库、文档名称和已保存片段，但标记连接已移除。
+
+## 12. 支持矩阵与版本变化
+
+每个 Adapter 维护明确的最低版本、已验证版本和 `adapterVersion`。连接测试优先读取可靠的
+版本接口或响应头；无法识别版本时，只允许经真实请求验证过的基础列表和检索字段，高级字段
+保持不可用。
+
+Adapter 可以保存少量受控事实，例如“目录接口可用”“详情表明已构建图谱”，但不尝试从
+远端拼出完整 capability manifest，也不计算 capability fingerprint。
+
+- `adapterVersion` 相同且实例仍在支持矩阵内：解析已保存配置并执行。
+- Adapter 升级：使用明确的配置迁移或把绑定标记为 `config-invalid`，不猜测字段迁移。
+- 实例版本离开支持矩阵：停止发送高级字段，并要求重新测试和确认。
+- 新能力出现：保持默认关闭，用户主动配置后才发送。
+- RAGFlow `use_kg` 还要求当前远端知识库存在已构建图谱的证据。
+
+## 13. 安全与隐私
+
+- API Key 在用户输入和保存 IPC 中短暂存在，随后使用系统安全存储加密；保存后不返回
+  Renderer，也不进入 Runtime、日志和普通元数据。
+- 请求不附带完整会话、附件、本地知识库证据、系统提示、模型配置或其他 Provider 结果。
+- Provider 结果使用与本地知识证据相同的不可信上下文标记。
+- Adapter 拒绝响应中的原型污染键、过深对象、超长数组和非有限数值。
+- 远端错误正文只用于 Main 内映射，日志与 UI 使用稳定错误码和短消息。
+- 外部知识库不能扩大当前对话显式选择的 GoodBuddy 知识库 ID。
+- Ask 与 Execute 对知识检索均为只读，Execute 不获得额外 Provider 权限。
+- Provider 配置中的模型 ID、背景文本和 Metadata 条件按独立长度限制验证，不能携带凭据。
+- HTTP 或证书例外需要按当前规范化地址确认凭据传输风险，地址变化后重新确认。
+
+## 14. 测试
+
+### 14.1 契约测试
+
+- 每个 Provider 的列表、详情、检索成功和错误 fixture。
+- 未知字段、缺字段、错误类型、超长内容、非有限分数和超大响应。
+- Dify 查询长度、FastGPT 文件夹过滤、RAGFlow 图谱和 Knowledge Compilation 字段。
+- Provider 配置判别联合拒绝类型错配和未知字段。
+
+### 14.2 安全测试
+
+- 保存完成后的 Renderer 快照、IPC 返回值、日志、错误、活动和导出中不存在明文 API Key；
+  `replace` 输入只在当前表单和单次 IPC 请求中短暂存在。
+- `keep/replace/clear` 凭据语义和安全存储不可用路径。
+- 地址中的凭据、查询、片段、危险 scheme、跨源重定向和远端 URL 注入被拒绝。
+- 取消、超时、响应大小上限和应用关闭释放请求。
+
+### 14.3 集成测试
+
+- 实例保存、目录读取、手工 ID、绑定创建、编辑和本地移除。
+- 同一远端目标重复绑定被拒绝。
+- 删除实例的引用保护和级联本地移除确认。
+- 本地与外部 `retrieveMany` 部分成功、全部失败和确定性上下文预算。
+- 聊天 `always` 与 Agent `knowledge_search` 使用同一 Provider-aware 编排。
+- 历史引用在实例或绑定移除后仍可读。
+
+### 14.4 UI 测试
+
+- 类型切换、异步旧响应、目录搜索、刷新和手工模式。
+- 两栏与窄窗口堆叠、键盘、焦点恢复和离开保护。
+- Provider 字段显隐、失效配置、RAGFlow 图谱说明和恢复默认。
+- 外部详情不出现导入、同步、分块和本地图谱操作。
+- 错误、零结果、部分失败和 Provider 引用显示。
+
+### 14.5 真实实例验收
+
+每个 Provider 至少选择一个明确版本的自部署实例，记录：
+
+- 版本、部署方式和认证范围。
+- 列表与检索的请求/响应 fixture，移除凭据和业务正文。
+- 默认与专属配置是否真实生效。
+- 401、403、404、429、超时和取消行为。
+- 查询、片段、引用和诊断的实际上限。
+
+Mock 或公开文档通过不能代替真实实例验收。
+
+## 15. 实施顺序
+
+这里的顺序只用于控制代码依赖，不裁剪产品设计：
+
+1. 建立共享判别契约、数据库迁移和凭据存储。
+2. 实现 HTTP 边界、错误映射和 Adapter Registry。
+3. 逐个实现三种 Provider，并用 fixture 完成契约测试。
+4. 实现实例管理和目录 IPC。
+5. 扩展创建向导、统一列表和外部详情。
+6. 扩展检索测试、引用和 `retrieveMany`。
+7. 接入聊天预检索与 `KnowledgeMcpGateway`。
+8. 完成真实实例、安全、响应式和跨平台验收。
+
+## 16. 发布条件
+
+- 三种 Provider 的受支持版本和限制已在产品界面或发布说明中可查。
+- 真实实例列表、绑定、检索和错误矩阵均通过。
+- 没有写入远端知识内容的代码路径。
+- API Key 泄漏测试、地址边界和响应大小测试通过。
+- 本地知识库创建、同步、检索、图谱和引用回归测试通过。
+- `auto`、`always`、检索测试和 MCP 知识工具得到一致的外部知识能力。
+
+## 17. 需求追踪
+
+| 需求 | 技术落点 | 验证 |
+| --- | --- | --- |
+| `EK-FR-01` 至 `EK-FR-03` | 实例契约、Store、实例 IPC、凭据和测试状态 | 实例集成测试、安全测试 |
+| `EK-FR-04`、`EK-FR-05` | Adapter 目录与详情接口、目录 IPC | Provider fixture、手工 ID 集成测试 |
+| `EK-FR-06` 至 `EK-FR-09` | Provider 判别联合、Adapter 配置版本、Renderer 本地字段定义 | 契约测试、UI 字段显隐测试 |
+| `EK-FR-10`、`EK-FR-11` | `KnowledgeBase.kind`、绑定表、统一 `retrieveMany` | 本地与外部混合检索测试 |
+| `EK-FR-12`、`EK-FR-13` | 引用定位判别联合、结果标准化、检索测试 IPC | 引用持久化与 UI 测试 |
+| `EK-FR-14` | 稳定错误码、逐库 Outcome、取消和超时 | 错误 fixture、部分失败测试 |
+| `EK-FR-15` | 外键限制、绑定本地删除、无远端写接口 | 删除生命周期测试 |
+| `EK-FR-16` | Main-only HTTP、固定端点、传输风险确认 | 地址、证书和凭据泄漏测试 |

docs/features/knowledge-base/external-knowledge-ui-design.md

@@ -0,0 +1,401 @@
+# 外部知识库 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计稿 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 产品需求 | [外部知识库接入 PRD](./external-knowledge-prd.md) |
+| 行为规则 | [外部知识库逻辑设计](./external-knowledge-logic-design.md) |
+| 全局规范 | [GoodBuddy UI 设计系统](../../../UI-DESIGN.md) |
+
+## 1. 信息架构
+
+外部知识库不增加左侧主导航和知识库一级页签。现有知识库页面结构保持：
+
+```text
+知识库
+├─ 页面标题区
+│  ├─ 管理外部实例
+│  └─ 新建知识库
+├─ 知识库列表
+└─ 当前知识库详情
+```
+
+“管理外部实例”管理可复用连接；“新建知识库”负责创建本地知识库或添加一个远端绑定。
+
+## 2. 页面标题区
+
+常规宽度：
+
+```text
+知识库                              [管理外部实例] [新建知识库]
+导入、检索并维护本地和企业现有知识
+范围：全局
+```
+
+- “新建知识库”保持主按钮。
+- “管理外部实例”是带服务器图标的次按钮。
+- 沿用知识库页面的全局 `ScopeBadge`，创建和管理外部连接时持续可见。
+- 按钮使用文字和图标，不增加只含缩写的厂商快捷入口。
+- 窄窗口下两个按钮换到标题下方，保持同一行；空间不足时各占一半宽度。
+
+对应：`EK-FR-01`。
+
+## 3. 知识库列表
+
+本地和外部知识库保留在同一主列表。条目采用现有列表密度，不增加卡片墙。
+
+```text
+研发规范
+RAGFlow · 研发知识平台 · 远端可检索
+
+产品资料
+本地 · 12 个来源 · 全文与向量可用
+```
+
+### 3.1 外部条目字段
+
+- GoodBuddy 显示名称。
+- Provider 图标或文字徽标。
+- 外部实例名称。
+- “远端可检索”、认证失效、目标不存在等准确状态。
+- 最近一次成功检索时间；从未检索时显示“尚未检索”。
+
+外部条目不显示来源数量、同步进度、向量覆盖率、本地图谱或导入失败数。
+
+### 3.2 列表筛选
+
+现有搜索同时匹配 GoodBuddy 名称、远端名称、Provider 和实例名称。来源筛选使用菜单：
+
+```text
+全部来源
+本地
+Dify
+FastGPT
+RAGFlow
+```
+
+筛选不是新的页面页签。
+
+## 4. 管理外部实例
+
+点击“管理外部实例”打开大尺寸 Modal。Modal 使用标题、可滚动内容和固定操作区，遵循
+全局焦点陷阱、Escape、背景隔离和焦点恢复规则。
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│ 外部实例                                      [添加实例] [×] │
+│ 管理 Dify、FastGPT 和 RAGFlow 的连接                         │
+├──────────────────────────────────────────────────────────────┤
+│ 名称            Provider   服务地址             状态    操作 │
+│ 研发知识平台    RAGFlow    ragflow.example      正常     ⋯   │
+│ 客服知识平台    FastGPT    fastgpt.example      认证失效 ⋯   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 4.1 实例行
+
+显示：
+
+- 名称、Provider、脱敏后的主机名、状态。
+- 已绑定知识库数量。
+- 最近测试时间。
+- 行尾菜单：测试连接、编辑、停用或启用、删除。
+
+服务地址可以显示 scheme、host 和非默认端口，不显示路径中的敏感信息、查询或凭据。
+
+### 4.2 空状态
+
+```text
+尚未配置外部实例
+添加企业现有的 Dify、FastGPT 或 RAGFlow 服务。
+[添加实例]
+```
+
+筛选无结果和加载失败使用不同 `EmptyState` 变体。
+
+## 5. 添加和编辑实例
+
+实例表单在管理 Modal 内切换为编辑面板，不叠加第二层 Modal。
+
+```text
+添加外部实例
+
+实例名称        [研发知识平台                    ]
+Provider        [RAGFlow                       ▾]
+服务地址        [https://ragflow.example        ]
+认证方式        API Key
+API Key         [••••••••••••••••               ]
+凭据状态        尚未保存
+
+连接测试
+服务连接        未测试
+身份认证        未测试
+知识库列表      未测试
+检索接口        绑定知识库时验证
+
+                              [取消] [测试连接] [保存实例]
+```
+
+### 5.1 字段行为
+
+- Provider 使用原生 Select；编辑已被绑定的实例时不可切换 Provider。
+- 服务地址只接受完整 HTTP(S) 地址。字段下方说明其受全局内网兼容模式影响。
+- API Key 使用密码输入和显示/隐藏图标。明文会在当前表单和保存 IPC 中短暂存在；编辑时
+  留空表示保留，不使用占位假密钥。
+- 已保存凭据旁提供“替换凭据”和“清除凭据”，清除属于需要确认的操作。
+- 地址使用 HTTP，或连接测试依赖放宽证书校验时，在测试和保存操作旁持续显示传输风险。
+  用户必须针对当前地址确认后才能保存；地址变化会清除该确认。
+- “测试连接”不保存草稿；测试期间按钮显示进度并提供取消。
+- 保存成功进入应用通知，Modal 返回实例列表并聚焦对应行。
+
+### 5.2 测试结果
+
+分项状态使用图标、文字和说明，不只依靠颜色：
+
+```text
+服务连接       通过       183 ms
+身份认证       通过
+知识库列表     受限       当前凭据不能读取列表，可手工填写知识库 ID
+检索接口       待验证     添加知识库时执行
+```
+
+长错误折叠显示，正文经过脱敏。失败后保留全部草稿和 API Key 输入。
+
+FastGPT 实例额外显示：`检索会计入该实例的 API 使用记录，并可能产生 Embedding 或
+Rerank 用量。`
+
+## 6. 新建知识库向导
+
+扩展现有页面内 `CreateLibraryWizard`，不改为新的全屏页面或 Modal。
+
+### 6.1 类型选择
+
+表单第一项使用单选卡片或共享 SegmentedControl：
+
+```text
+知识库类型
+[本地] [Dify] [FastGPT] [RAGFlow]
+```
+
+只有选择本地时显示现有存储模式、图谱和本地说明。外部类型选中后显示两栏配置。
+
+### 6.2 外部类型两栏布局
+
+```text
+┌──────────────────────────────┬──────────────────────────────┐
+│ 知识库来源                   │ 检索配置                     │
+│                              │                              │
+│ Provider     RAGFlow         │ 通用配置                     │
+│ 外部实例     [研发平台    ▾] │ 返回片段数          [ 6 ]   │
+│ 远端知识库   [研发规范    ▾] │ 请求超时            [15 秒] │
+│                         [↻]  │ 单片段上限          [4000]  │
+│ [手工填写知识库 ID]          │                              │
+│                              │ RAGFlow 配置                 │
+│ 显示名称     [研发规范      ]│ 相似度阈值          [0.20]  │
+│ 远端名称     研发规范        │ 向量相似度权重      [0.30]  │
+│ 远端 ID      7f31…c902       │ KNN Top K           [1024]  │
+│ 测试查询     [部署网络要求  ]│ 图谱检索             [开关] │
+│                              │ Knowledge Compilation [开关]│
+├──────────────────────────────┴──────────────────────────────┤
+│ 将向研发知识平台发送测试查询。不会上传文件或完整会话。       │
+│                              [取消] [测试检索] [添加知识库]   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+测试查询由用户填写，不自动生成，也不取用当前会话内容。“添加知识库”在真实检索请求
+成功前禁用；成功返回零条结果仍可添加，但界面显示“检索成功，未找到匹配片段”。验证结果
+在底部说明区展示，不用成功 Alert 撑高表单。
+添加成功后沿用本地知识库行为，把新绑定加入当前聊天选择，不重新启用其他已取消知识库。
+
+### 6.3 目录下拉框
+
+- 选择实例后自动打开加载状态，不要求再点击“读取”。
+- 使用可搜索 Select，选项显示名称、远端短 ID 和可用状态。
+- 右侧刷新使用刷新图标按钮，Tooltip 为“刷新知识库列表”。
+- 加载时保持控件稳定尺寸，显示“正在读取知识库…”。
+- 目录为空显示“当前实例没有可访问的知识库”。
+- 403 或不支持列表时显示原因和“手工填写知识库 ID”。
+- 列表失败后显示“重试”，不自动切换到手工模式。
+
+### 6.4 手工模式
+
+```text
+远端知识库 ID  [                              ]
+显示名称        [                              ]
+[验证知识库]
+```
+
+验证成功后显示远端名称和 Provider 返回的摘要。返回自动列表不会丢弃已输入 ID，切换前
+如有未保存输入须确认。
+
+## 7. 配置面板
+
+右侧配置固定分为“通用配置”和“{Provider} 配置”，不创建嵌套卡片。高级字段可以使用
+一个折叠区，但核心检索方式、阈值和 RAGFlow 图谱检索保持直接可见。
+
+控件选择：
+
+- 开关：图谱检索、Score 阈值启用、Rerank、使用 Dify 知识库默认配置。
+- Select 或 SegmentedControl：少量固定检索方式。
+- 数字输入或 Stepper：结果数、Token、Top K、超时。
+- Slider 加数字输入：0 至 1 的阈值和权重，二者保持同步。
+- Metadata 条件：初始版本不提供自由 JSON 编辑器。
+
+字段显隐由 GoodBuddy 内置 Provider 描述和 Main 返回的能力状态共同决定。服务端返回的
+任意字符串不得变成 HTML、控件标签或帮助链接。
+
+### 7.1 RAGFlow 图谱文案
+
+开关名称：`图谱检索`
+
+说明：`检索远端知识库已经生成的图谱内容，不会创建或更新图谱。`
+
+只有远端详情或受控探测表明图谱已经构建时，该开关才可用。证据缺失时显示“未确认远端
+图谱状态”并禁用。Knowledge Compilation 单独显示为 `包含 Knowledge Compilation`，默认
+关闭，不把它和旧 GraphRAG 合成同一开关。
+
+## 8. 外部知识库详情
+
+选中外部绑定后，现有详情区按来源类型裁剪：
+
+```text
+研发规范                                      RAGFlow · 远端检索
+研发知识平台 / 远端知识库 7f31…c902
+
+[概览] [检索配置] [检索测试]
+```
+
+### 8.1 概览
+
+显示 Provider、实例、远端名称、远端 ID、连接状态、最近成功检索和数据位置。操作包括：
+
+- 刷新远端信息。
+- 更换远端知识库。
+- 编辑 GoodBuddy 显示名称。
+- 从 GoodBuddy 移除。
+
+不显示导入文件、添加目录、添加网页、同步、分块、重建索引和本地图谱入口。
+
+### 8.2 检索配置
+
+复用创建向导右侧配置面板。存在失效字段时，页头显示“配置需要确认”，字段附近说明
+Provider 版本变化，保存按钮保持禁用直到用户处理。
+
+### 8.3 检索测试
+
+复用现有检索测试工作台的查询、结果和焦点行为，但外部结果采用 Provider 诊断：
+
+```text
+RAGFlow · 研发知识平台
+总耗时 642 ms · 返回 6 条 · 保留 6 条
+
+1  部署规范.pdf
+   第四章 网络要求…
+   Provider 分数 0.82 · 文档 ID 98ab…
+```
+
+外部测试不显示 FTS/CJK/本地向量扫描等本地通道，也不提供依赖本地分块的“查看上下文”。
+
+## 9. 聊天知识范围
+
+现有多选列表保留一个选择面，只在每行增加来源：
+
+```text
+[✓] 产品资料                         本地
+[✓] 研发规范                         RAGFlow · 研发知识平台
+[ ] 客服知识                         FastGPT · 客服平台
+```
+
+- 不按 Provider 创建多套选择器。
+- 不可用绑定保留显示但禁用勾选，并给出认证失效或目标不存在原因。
+- 当前会话已选绑定变为不可用时，不静默移除 ID；发送前提示该知识库本次无法检索。
+
+## 10. 执行状态和引用
+
+活动状态：
+
+```text
+正在检索“研发规范”
+RAGFlow · 研发知识平台 · 已发送当前检索词
+```
+
+部分失败：
+
+```text
+已检索 3 个知识库，2 个成功，1 个超时
+[查看详情]
+```
+
+引用：
+
+```text
+部署规范.pdf / 网络要求
+研发规范 · RAGFlow · 研发知识平台
+```
+
+引用详情显示远端文档名、ID、片段、Provider 分数和实际返回的定位。未完成 URL 安全设计前，
+不显示“打开远端来源”。
+
+## 11. 删除确认
+
+移除绑定：
+
+```text
+从 GoodBuddy 移除“研发规范”？
+这会删除本机绑定和检索配置，不会删除 RAGFlow 中的知识库或文档。
+
+[取消] [移除]
+```
+
+删除有绑定的实例：
+
+```text
+“研发知识平台”仍被 3 个知识库使用
+删除实例会同时从 GoodBuddy 移除这些绑定。远端数据不会改变。
+
+[取消] [查看知识库] [删除实例和本地绑定]
+```
+
+破坏性主操作使用 `danger-solid`，默认焦点放在“取消”。
+
+## 12. 可访问性与响应式
+
+- 常规宽度两栏使用稳定 Grid；小于 `960px` 时改为单栏，顺序为来源、通用配置、Provider 配置。
+- 小于 `720px` 时外部实例表格转为单列列表，行操作保留菜单按钮和完整可访问名称。
+- Modal、创建向导、下拉框和折叠区支持完整键盘操作。
+- 异步列表和测试状态使用 `aria-live="polite"`；错误使用与字段关联的 `role="alert"`。
+- 图标按钮必须提供 Tooltip 和 `aria-label`。
+- 状态不只靠颜色；加载、成功、受限和失败均包含文字。
+- 长实例名、地址、远端名称和 ID 使用单行省略，完整值可通过 Tooltip 或详情查看。
+- 切换类型、实例或退出时存在有效草稿，应按全局离开保护规则确认。
+
+## 13. 文案表
+
+| 场景 | 文案 |
+| --- | --- |
+| 页面操作 | 管理外部实例 |
+| 创建类型 | 本地 / Dify / FastGPT / RAGFlow |
+| 创建主操作 | 添加知识库 |
+| 列表加载 | 正在读取知识库… |
+| 列表受限 | 当前凭据不能读取知识库列表，可手工填写知识库 ID。 |
+| 远端状态 | 远端可检索 |
+| 移除操作 | 从 GoodBuddy 移除 |
+| 图谱开关 | 图谱检索 |
+| 测试说明 | 测试只发送当前查询，不会调用 GoodBuddy 模型或修改远端内容。 |
+
+产品文案不使用“同步外部知识库”“导入 Dify 知识库”或“创建远端知识库”，因为这些动作
+都不是本功能的实际行为。
+
+## 14. 需求追踪
+
+| UI 区域 | 需求 | 场景 |
+| --- | --- | --- |
+| 页面标题与统一列表 | `EK-FR-01`、`EK-FR-10` | `EK-US-C1` |
+| 外部实例管理与表单 | `EK-FR-02`、`EK-FR-03`、`EK-FR-15`、`EK-FR-16` | `EK-US-A1` 至 `EK-US-A3` |
+| 新建知识库向导 | `EK-FR-04` 至 `EK-FR-09` | `EK-US-B1` 至 `EK-US-B4` |
+| 外部详情与检索测试 | `EK-FR-12`、`EK-FR-13` | `EK-US-C3`、`EK-US-D1` 至 `EK-US-D4` |
+| 聊天范围、状态和引用 | `EK-FR-11`、`EK-FR-12`、`EK-FR-14` | `EK-US-C1` 至 `EK-US-C4` |

docs/features/knowledge-base/external-knowledge-user-stories.md

@@ -0,0 +1,212 @@
+# 外部知识库 User Stories
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计稿 |
+| 版本 | 0.1 |
+| 日期 | 2026-09-03 |
+| 关联 PRD | [外部知识库接入 PRD](./external-knowledge-prd.md) |
+
+## 1. 角色
+
+- **知识库使用者**：在聊天中选择已经添加的本地或外部知识库并查看引用。
+- **实例维护者**：持有外部知识库 API Key，负责配置实例、选择远端知识库和处理失效连接。
+- **RAG 调试者**：需要调整 Provider 参数并直接验证检索结果。
+
+## 2. 实例管理
+
+### EK-US-A1 添加外部实例
+
+作为实例维护者，我希望在知识库页面保存一个外部实例，以便后续绑定其中的多个知识库。
+
+验收：
+
+- Given 用户打开“管理外部实例”并选择 Dify、FastGPT 或 RAGFlow
+- When 用户填写名称、服务地址和 API Key，并执行连接测试
+- Then 页面分别显示服务、认证、目录和检索检查结果
+- And 保存后只显示“凭据已配置”，不回显 API Key
+- And 新实例可被同 Provider 的新建知识库向导选择
+- And 使用 HTTP 或放宽证书校验时，保存前明确提示 API Key 的传输风险
+
+### EK-US-A2 修复失效凭据
+
+作为实例维护者，我希望替换认证失效的 API Key，同时保留已有知识库绑定。
+
+验收：
+
+- Given 实例因认证失败处于“认证失效”状态
+- When 用户选择“替换凭据”、测试并保存
+- Then 所有绑定继续引用同一实例 ID
+- And 旧密钥不再使用
+- And 用户没有输入新密钥时可以取消且不清除旧密钥
+
+### EK-US-A3 删除仍被使用的实例
+
+作为实例维护者，我希望删除实例前看到受影响的知识库，以免留下无法解释的绑定。
+
+验收：
+
+- Given 实例仍被一个或多个外部知识库绑定引用
+- When 用户点击“删除实例”
+- Then 确认界面列出受影响数量和名称
+- And 用户可以取消，或明确同时移除本地绑定
+- And 确认后不向外部实例发送删除请求
+
+## 3. 添加知识库
+
+### EK-US-B1 从远端列表添加
+
+作为实例维护者，我希望选择 Provider 和实例后自动看到远端知识库，以便避免手工复制 ID。
+
+验收：
+
+- Given 至少存在一个可用的对应 Provider 实例
+- When 用户在“新建知识库”中选择外部类型和实例
+- Then GoodBuddy 自动读取有界知识库列表
+- And 下拉框支持按名称搜索与刷新
+- And 目录只显示当前凭据可见的知识库，不推断隐藏对象
+- And 切换实例后旧实例的异步响应不会覆盖新列表
+
+### EK-US-B2 手工填写远端 ID
+
+作为实例维护者，我希望列表接口受限时仍可通过远端 ID 添加已有知识库。
+
+验收：
+
+- Given 连接测试表明认证和检索可用，但目录读取无权限或不受支持
+- When 用户进入手工模式并填写远端知识库 ID
+- Then GoodBuddy 使用详情或测试检索验证该目标
+- And 验证失败时保留输入并显示原因
+- And 未经真实验证不能完成添加
+
+### EK-US-B3 配置 RAGFlow 图谱检索
+
+作为 RAG 调试者，我希望在添加 RAGFlow 知识库时设置图谱检索，以便使用远端已经构建的图谱内容。
+
+验收：
+
+- Given 适配器确认实例检索接口支持 `use_kg`
+- When 用户选择一个具备相关能力的 RAGFlow 知识库
+- Then 右侧显示“图谱检索”开关并说明它只影响检索
+- And 开启后测试请求携带该选项
+- And 只有远端知识库存在已构建图谱的证据时才允许开启
+- And 页面不把该开关描述为构建或更新远端图谱
+- And 能力不明确时该开关禁用并说明原因
+
+### EK-US-B4 保持本地创建流程
+
+作为本地知识库用户，我希望新增外部类型后仍能按原流程创建本地知识库。
+
+验收：
+
+- Given 用户在新建向导中选择“本地”
+- When 用户填写名称、存储模式和图谱设置
+- Then 表单字段、默认值和创建结果与现有行为一致
+- And 外部实例、远端 ID 和 Provider 配置不出现
+
+## 4. 检索和引用
+
+### EK-US-C1 在聊天中选择外部知识库
+
+作为知识库使用者，我希望外部知识库出现在现有知识范围选择器中，以便与本地知识库一起使用。
+
+验收：
+
+- Given 外部知识库绑定处于可检索状态
+- When 用户打开聊天知识范围
+- Then 它与本地知识库出现在同一选择器中
+- And 条目持续显示 Provider 和实例名称
+- And 选择结果仍保存 GoodBuddy 知识库 ID
+- And 新添加的绑定进入当前聊天选择，但不重新启用其他已取消知识库
+
+### EK-US-C2 只发送检索查询
+
+作为知识库使用者，我希望清楚知道哪些数据会发送到企业知识库。
+
+验收：
+
+- Given 本次请求选择了外部知识库
+- When GoodBuddy 执行检索
+- Then 只发送本次检索查询、远端知识库 ID 和已保存检索参数
+- And 不发送完整会话、本地附件、其他知识库内容、系统提示或模型凭据
+- And 活动状态显示目标 Provider 和实例
+
+### EK-US-C3 查看外部引用
+
+作为知识库使用者，我希望回答中的引用标明外部来源，以便回到企业知识系统核验。
+
+验收：
+
+- Given Provider 返回文档名、片段 ID、内容和分数
+- When GoodBuddy 展示引用
+- Then 引用显示 Provider、实例、知识库和文档名称
+- And 详情只显示 Provider 实际返回且通过校验的定位信息
+- And 缺失页码、链接或分数时不生成替代值
+
+### EK-US-C4 多知识库部分失败
+
+作为知识库使用者，我希望一个外部实例暂时失败时仍能使用其他成功结果。
+
+验收：
+
+- Given 本次选择了本地知识库和两个外部知识库
+- When 一个外部请求超时，其他请求成功
+- Then 成功证据继续进入回答
+- And 页面显示一个知识库检索失败及其原因
+- And 超时不显示为“未找到相关内容”
+- And GoodBuddy 不自动改用同 Provider 的其他实例
+
+## 5. 配置与诊断
+
+### EK-US-D1 调整 Provider 配置
+
+作为 RAG 调试者，我希望只看到当前 Provider 支持的参数，以便理解设置会怎样影响远端检索。
+
+验收：
+
+- Given 用户编辑一个外部知识库绑定
+- When 页面读取实例能力和已保存配置
+- Then 通用配置与 Provider 专属配置分区显示
+- And 每个字段显示范围、默认值和作用
+- And 不受支持的字段不会被静默发送
+- And 恢复默认只恢复当前绑定的 Provider 配置
+
+### EK-US-D2 运行检索测试
+
+作为 RAG 调试者，我希望在知识库页面直接测试外部检索，不经过聊天模型。
+
+验收：
+
+- Given 当前选中一个外部知识库
+- When 用户输入查询并点击“测试检索”
+- Then 页面显示 Provider 耗时、返回数量、片段、来源和截断状态
+- And 测试不创建聊天消息、不调用 GoodBuddy LLM、不修改远端内容
+- And 远端原始响应和凭据不进入界面或日志
+- And FastGPT 测试明确提示远端可能记录 API 使用并产生检索或重排用量
+
+### EK-US-D3 Provider 版本变化
+
+作为实例维护者，我希望升级外部系统后看到配置是否仍受支持。
+
+验收：
+
+- Given 最近一次能力探测与已保存快照不同
+- When 用户测试实例或打开绑定设置
+- Then 页面指出新增、失效或行为变化的配置
+- And 失效配置不会静默删除或继续发送
+- And 用户确认有效配置后才更新绑定
+
+### EK-US-D4 远端知识库被删除
+
+作为实例维护者，我希望远端目标不存在时看到准确状态并重新绑定。
+
+验收：
+
+- Given Provider 返回目标不存在
+- When 用户打开知识库或执行检索
+- Then 绑定状态显示“远端知识库不存在”
+- And 聊天选择器不把它显示为可用
+- And 用户可以刷新目录并选择新的远端知识库
+- And 保存新目标前必须重新测试

docs/features/knowledge-base/prd.md

@@ -5,10 +5,11 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 实施中 |
-| 版本 | 0.1 |
-| 日期 | 2026-08-11 |
+| 版本 | 0.3 |
+| 日期 | 2026-09-05 |
 | 适用产品 | GoodBuddy 桌面端 |
 | 实施范围 | 第一阶段：可用、可见、可诊断；第二阶段：可调、可优化、可维护 |
+| 相关设计 | [本地文本向量模型与连接设计](./local-embedding-technical-design.md) |
 
 ## 1. 背景
 
@@ -38,7 +39,8 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 3. 保留“模型按需检索”，并新增“每次先检索”模式。后者必须由 Main 进程
    预检索，不能只依赖提示词要求模型调用工具。
 4. 知识库新建后不默认启用全部已有知识库；对话中的范围继续由用户显式选择。
-5. 向量服务不可用时保留全文检索，但必须返回明确降级状态。
+5. 向量服务不可用时保留全文与中文检索，但必须返回明确降级状态。这是可见的检索通道
+   降级，不得自动切换内置连接、用户添加的 OpenAI 兼容连接或其他向量模型。
 6. 中文召回使用应用内可控的 CJK n-gram 索引，不新增远程服务依赖。
 7. 混合检索保留 RRF 候选融合，并增加本地确定性重排、可选的
    Cohere/Jina 兼容学习型重排、最低相关度和上下文预算。学习型重排失败时
@@ -46,7 +48,9 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 8. 向量搜索取消 5,000 分块静默失效，使用有界内存的分页扫描。在没有稳定
    跨平台向量扩展前，接受本地 CPU 线性扫描，并持续显示性能诊断。
 9. 向量索引兼容性同时校验 Provider、Model、维度和 Provider Fingerprint。
-   同名模型切换端点后，旧向量不能继续参与召回。
+   同名模型切换端点后，旧向量不能继续参与召回。Fingerprint 的完整模型、编码与
+   数据路径定义以[本地文本向量模型与连接设计](./local-embedding-technical-design.md)
+   为准。
 10. 失败或取消的重建不能停用上一版已就绪索引。新索引只有完整校验成功后才
     原子替换当前服务版本。
 11. 分块设置属于知识库，修改后不会伪装为立即生效。用户需要显式重建索引。
@@ -56,6 +60,12 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
     用户配置决定。
 14. Ask 的运行时边界保持只读。知识库内容始终被标记为不可信证据，
     不能成为系统指令。
+15. 向量连接是 GoodBuddy Main 管理的知识服务依赖，不是 Agent Runtime 模型。它不进入
+    直连模型、OpenCode、Continue、DeepSeek Harness、远程 Runtime 或项目 Runtime 的
+    模型选择、配置和凭据边界。
+16. Runtime 只能获得 Main 检索后选出的有界文本证据、来源引用和脱敏诊断，不能获得
+    Embedding Provider、连接 Profile、Endpoint、API Key、模型目录、Tokenizer、原始向量
+    或索引 Fingerprint。
 
 ## 3. 目标
 
@@ -98,6 +108,9 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 - 自动问题生成、FAQ 生成和训练数据标注平台。
 - 完整 RAG 离线评测平台。第二阶段只提供手动检索测试与可导出的诊断信息。
 - 在应用内高保真渲染所有原始 Office 和 PDF 文档。
+- 把向量连接用作 LLM、Agent Runtime 模型或 Runtime 模型网关。
+- 让 Runtime 直接调用 Embeddings Endpoint、内置推理进程或向量数据库。
+- 未经独立设计就把知识库向量连接扩展到记忆、自动化、项目文件搜索或其他应用服务。
 
 ## 5. 竞品基线与 GoodBuddy 定位
 
@@ -136,7 +149,7 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 
 ## 6. 信息架构
 
-知识工作区继续使用主从布局和现有四个页签：
+知识工作区使用主从布局和四个面向用户任务的页签：
 
 ```text
 知识库
@@ -147,14 +160,41 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 │  └─ 分块查看与维护
 ├─ 知识图谱
 ├─ 任务中心
-└─ 设置
+└─ 高级设置
+   ├─ 问答效果入口
+   ├─ 向量索引
    ├─ 检索设置
    ├─ 分块设置
    └─ 图谱设置
 ```
 
-“检索测试”是当前知识库的高频诊断操作，通过知识库标题区次操作打开独立
-工作台，不新增第五个一级页签。
+“检索测试”是当前知识库的高频验证操作，通过知识库标题区和“高级设置 →
+问答效果”打开同一个独立工作台，不新增第五个一级页签。工作台首次打开只突出真实
+问题输入和测试操作；候选倍数、权重、阈值、重排和上下文预算默认折叠。
+
+首次使用流程固定为“创建知识库 → 添加资料 → 等待可检索 → 用于当前对话”。创建表单
+默认只展示名称和描述；存储方式与知识图谱属于折叠的高级设置。没有知识库时，唯一主操作
+位于首次使用空状态中。
+
+全局向量模型仍在“设置 → 模型连接 → 向量模型”中配置。GoodBuddy 内置连接和用户添加的
+OpenAI 兼容连接使用同一连接列表；其界面、数据路径及切换语义以
+[本地文本向量模型与连接设计](./local-embedding-technical-design.md)
+为准，知识库页面只显示当前模型、索引兼容性、覆盖率和重建操作。“模型连接”是设置入口
+名称，不表示向量连接可以分配给 Agent Runtime；项目 Runtime 和 Agent Runtime 的模型
+选择中不显示向量连接。
+
+知识检索与 Runtime 的关系固定为：
+
+```text
+用户问题
+→ Main / KnowledgeService 使用当前向量连接检索
+→ Main 生成有界文本证据、引用和检索诊断
+→ 当前 Runtime 仅消费这些不可信检索结果
+```
+
+`always` 模式由 Main 在启动 Runtime 前完成检索；`auto` 模式中的 `knowledge_search`
+也只允许 Runtime 调用 Main 的有界知识工具。两种模式都不把向量连接、凭据、模型文件、
+Tokenizer、原始向量或索引访问能力传入 Runtime。切换 Runtime 不改变当前向量连接。
 
 对话输入区的知识范围弹层包含：
 
@@ -162,6 +202,10 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 2. 检索方式：模型按需检索、每次先检索。
 3. 当前范围为空、索引降级或向量未配置时的短说明。
 
+知识库 ID 选择按 Conversation 持久化。新对话和未保存过知识范围的旧对话默认不选择
+任何知识库；切换对话恢复各自范围，不得在应用启动时自动勾选全部知识库。新建知识库只
+加入当前 Conversation，不重新启用用户已取消的其他知识库。
+
 ## 7. 第一阶段：可用、可见、可诊断
 
 ### 7.1 检索方式
@@ -225,6 +269,10 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 - 相邻分块或父块合并后的实际上下文。
 - “查看分块”“打开来源”操作。
 
+图谱通道对中文自然语言问题生成有界 CJK 二元词和拉丁关键词，在实体名称、
+别名和类型中确定种子，再沿具有有效文档证据的关系执行有界多跳扩展。图谱探索页
+搜索到实体时保留其一跳邻居和关系上下文，并继续允许从实体或关系打开原始证据。
+
 检索测试不创建聊天消息、不写入会话历史、不调用 LLM，也不改变知识库内容。
 
 ### 7.5 可扩展向量搜索
@@ -259,6 +307,14 @@ OpenAI 兼容向量模型、RRF 混合检索、知识图谱、任务状态和来
 - 失败文档数。
 - 当前向量模型与索引是否兼容。
 
+`indexedDocumentCount` 只统计状态为 `ready` 的文档；`queued`、`parsing` 和
+`indexing` 计入处理中，`failed` 单独计入需处理。文档行持续显示全文、向量和图谱通道
+状态。已有可用分块的失败文档仍允许查看分块，并提供重新处理。
+
+文档行可通过受控 `knowledgeBaseId + documentId` 打开数据库中保存的原始来源。
+Renderer 不得提交任意路径。移除来源必须先说明将删除的文档、索引、图谱证据及是否包含
+应用托管副本，用户确认后才执行。
+
 降级事件包括：
 
 - 未配置向量模型。
@@ -495,7 +551,7 @@ type KnowledgeRetrievalResponse = {
 
 | 场景 | 行为 |
 | --- | --- |
-| 向量查询失败 | 继续全文和图谱检索，显示降级原因 |
+| 向量查询失败 | 继续已配置的全文、中文和图谱通道，显示降级原因，不切换向量 Provider 或模型 |
 | 部分文档无向量 | 使用可用文档，显示完成数和失败数 |
 | CJK 索引迁移失败 | 回滚迁移，不损坏旧 FTS |
 | 重排失败 | 回退 RRF 排序并显示诊断 |
@@ -503,6 +559,7 @@ type KnowledgeRetrievalResponse = {
 | 单文档重建失败 | 保留上一版可用索引 |
 | 同名模型端点变化 | 旧 Fingerprint 索引标记不兼容，等待重建 |
 | 新向量重建失败 | 保留上一版就绪向量继续服务，单独记录失败尝试 |
+| 图谱模型空响应、超时或瞬时服务错误 | 按不超过约 8,192 个估算 Token 组织独立抽取批次，每批最多尝试两次；部分批次成功时发布已验证结果并在任务中显示具体警告；所有批次失败时图谱任务失败，但新文档的全文索引仍可发布，已有文档的显式重建继续保留上一版可用索引 |
 | 原文件已移动 | 显示来源不可用，提供重试或移除 |
 | 引用对象已删除 | 显示引用已失效，不打开任意替代路径 |
 | 上下文超预算 | 按排名截断并明确标记 |
@@ -518,6 +575,7 @@ GoodBuddy 不上传私人检索查询或文档内容。本地诊断至少记录
 - 是否发生降级。
 - 最终结果数和上下文字符数。
 - 重建文档数、成功数、失败数和取消状态。
+- 图谱抽取批次数、部分失败警告和具体失败原因。
 
 手动验收使用仓库内不含私人内容的固定样例集，覆盖：
 
@@ -558,6 +616,12 @@ GoodBuddy 不上传私人检索查询或文档内容。本地诊断至少记录
 - “每次先检索”在 Runtime 启动前产生检索诊断和引用，即使模型未调用工具。
 - 未配置向量模型时，中文改写问题仍能通过 CJK 索引召回相关分块。
 - 向量查询失败时回答可继续，界面明确显示已降级。
+- 内置连接和用户添加的 OpenAI 兼容连接之间不会自动切换；用户连接的实际数据去向持续
+  可见，内置连接不重复展示固定本地路径。
+- 项目 Runtime 和 Agent Runtime 的模型选择不显示向量连接。
+- Runtime 只获得有界文本证据、引用和脱敏诊断，不获得向量 Provider、凭据或原始向量。
+- 切换直连模型、OpenCode、Continue、DeepSeek Harness 或远程 Runtime 不改变当前向量
+  连接。
 - 10,000 个分块的向量测试能够返回正确 Top K，不出现固定上限空结果。
 - 同名模型切换端点后，不会读取 Fingerprint 不匹配的旧向量。
 - 重建失败时，上一版已就绪向量仍能继续召回。

docs/features/knowledge-base/progress.md

@@ -0,0 +1,41 @@
+# 知识库实施进度
+
+## 已验证实现
+
+截至 2026-09-05：
+
+- 知识库选择按 Conversation 持久化，新对话默认空范围。
+- 创建流程默认只展示名称和描述，高级存储与图谱设置折叠。
+- 知识库汇总区分可检索、处理中和需处理文档。
+- 文档行展示全文、向量和图谱状态，并支持打开原始来源和重新处理失败文档。
+- 移除来源需要确认并说明级联影响。
+- 检索高级参数默认折叠，“高级设置”提供问答效果入口。
+- 向量未配置状态可直接前往模型设置。
+- 有效 DOCX 与多页 PDF 已通过磁盘文件导入、解析、分块和检索生产链路。
+
+## 验证证据
+
+2026-09-05 最终验证：
+
+- `npm test`：325 个测试文件、3511 项测试通过；8 个文件、55 项手动或集成测试按既有
+  配置跳过。
+- `npm run typecheck`：通过。
+- `npm run lint`：通过。
+- `npm run build`：Electron Main、Preload、Renderer 生产构建及控制面安装包检查通过。
+- `npx vitest run src/main/knowledge/knowledge-service.test.ts -t "imports real DOCX and PDF files from disk into searchable chunks"`：
+  有效 Open XML DOCX 与两页原生文本 PDF 均通过生产 `KnowledgeService.importPaths`
+  导入、解析、分块和全文检索。
+
+2026-09-06 对话知识库选择补充验证：
+
+- `App.test.tsx` 覆盖点击名称、文档数量和行本身时切换选中状态，以及空目标失焦时
+  弹层不提前卸载。Windows 隔离桌面实际点击名称后选中、点击数量后取消，弹层保持打开。
+- 本轮全量校验结果见[工作栏验证记录](../assistant-workbar/progress.md)；本项验证未调用模型。
+
+## 剩余工作
+
+- 外部 Dify、FastGPT 和 RAGFlow 知识库接入仍为规划中能力。
+- 扫描 PDF 的真实 OCR 验收依赖用户已安装并校验的 OCR 模型；本次 DOCX/PDF 回归覆盖
+  原生文本 PDF，不宣称覆盖扫描件 OCR。
+- PDF.js 在测试环境会提示未配置 `standardFontDataUrl`；文本、页码定位与检索结果不受
+  影响。

docs/features/knowledge-base/ui-design.md

@@ -0,0 +1,70 @@
+# 知识库 UI 设计
+
+## 1. 设计目标
+
+知识库优先帮助普通用户完成“添加资料并可靠提问”，高级 RAG 调试和图谱维护不得阻塞
+首次使用。全局视觉、页面壳层、通知、焦点和危险操作遵循
+[UI-DESIGN.md](../../../UI-DESIGN.md)。
+
+## 2. 信息架构
+
+```text
+知识库
+├─ 知识库列表
+└─ 当前知识库
+   ├─ 文档与来源
+   ├─ 知识图谱（启用后显示）
+   ├─ 任务中心
+   └─ 高级设置
+```
+
+标题区提供“用于当前对话”“检索测试”、编辑和删除。新建知识库是页面主操作。
+“高级设置”承载问答效果入口、向量索引、分块与图谱配置，不把工程参数放在首次路径。
+
+## 3. 首次使用
+
+没有知识库时，页面空状态显示唯一的“新建知识库”主操作。创建表单默认只展示名称和
+描述；存储方式与知识图谱放入折叠的“高级设置”。创建完成后进入“文档与来源”，用户
+可以导入文件、文件夹或 URL。
+
+文档处理完成后，标题区“用于当前对话”可用。该操作把当前知识库加入当前
+Conversation 的检索范围，返回对话并聚焦输入框。
+
+## 4. 状态
+
+知识库列表显示“可用”和“需处理”文档数。详情标题持续显示可检索、处理中、需处理和
+总文档数，即使用户填写了知识库描述也不隐藏状态。
+
+文档行显示：
+
+- 总体处理状态。
+- 全文状态。
+- 向量状态。
+- 启用图谱时的图谱状态。
+
+失败文档保留错误信息和“重新处理”。只要仍有可用分块，就允许打开分块管理，避免隐藏
+上一版可用索引。
+
+## 5. 问答效果与高级参数
+
+“检索测试”默认只突出真实问题、测试按钮和结果。高级参数使用折叠区，包含候选倍数、
+通道权重、最低相似度、重排、结果数和上下文预算。“高级设置 → 问答效果”打开同一
+工作台。
+
+向量模型未配置时显示“前往设置”，直接进入模型连接，不使用只有说明文字的死路状态。
+
+## 6. 来源操作
+
+文档行提供“打开来源”，Main 根据知识库和文档归属重新读取保存的文件路径或 URL。
+移除来源使用确认对话框，说明文档数、索引、图谱证据和托管副本影响。初始焦点位于
+取消，提交期间禁止重复操作，失败时保留对话框和错误。
+
+## 7. 对话范围
+
+知识库多选属于 Conversation。新对话默认空范围；切换对话恢复各自选择。创建新知识库
+只加入当前 Conversation，不重新启用其他已取消项。发送请求时冻结当前选择和检索方式。
+
+输入区的知识库选择弹层使用整行原生 Checkbox 标签，点击名称、文档数量或行内空白
+均切换一次选择；选中背景和整行焦点环保持可见。Tab 聚焦、Space 切换，Escape 关闭并
+返回触发按钮。点击行内非焦点元素时产生的空目标失焦不关闭弹层；点击外部或焦点明确
+移到外部时才关闭，避免原生标签完成勾选前被卸载。