Merge github/main README updates into release candidate

Preserve the published English and Chinese README community QR-code updates. Desktop 0.13.5, Agent 0.13.0, approved bilingual release notes, and the validated product code remain unchanged.
chore: prepare Desktop 0.13.5 and Agent 0.13.0 releases
2026-09-15 17:29:33 +08:00 · 2026-09-15 17:25:12 +08:00 · 2026-09-15 16:58:28 +08:00 · 2026-09-15 16:52:57 +08:00 · 2026-09-15 15:59:13 +08:00 · 2026-09-15 15:51:52 +08:00
749 changed files with 151379 additions and 45585 deletions
@@ -45,17 +45,22 @@ jobs:
          echo "version=$version" >> "$GITHUB_OUTPUT"

  build:
-    name: Build Linux ${{ matrix.arch }} compound package
+    name: Build ${{ matrix.platform }} ${{ matrix.arch }} compound package
    needs: authorize
    if: needs.authorize.outputs.authorized == 'true'
    strategy:
      fail-fast: false
      matrix:
        include:
-          - arch: x64
+          - platform: linux
+            arch: x64
            runner: ubuntu-24.04
-          - arch: arm64
+          - platform: linux
+            arch: arm64
            runner: ubuntu-24.04-arm
+          - platform: darwin
+            arch: arm64
+            runner: macos-15
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 25
    environment:
@@ -76,11 +81,15 @@ jobs:
      - 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'
@@ -88,9 +97,11 @@ jobs:
          const { createHash } = require('node:crypto')
          const agent = require('./agent-runtime-lock.json')
          const remote = require('./remote-runtime-lock.json')
-          const node = agent.node?.targets?.[`linux-${process.env.AGENT_ARCH}`]
+          const node = agent.node?.targets?.[`${process.env.AGENT_PLATFORM}-${process.env.AGENT_ARCH}`]
          const runtime = remote.runtimes?.opencode
-          const opencode = runtime?.targets?.[process.env.AGENT_ARCH]
+          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 ||
@@ -136,7 +147,7 @@ jobs:
        uses: actions/cache@v6
        with:
          path: ${{ runner.temp }}/goodbuddy-agent-release-inputs
-          key: goodbuddy-agent-release-${{ matrix.arch }}-${{ steps.inputs.outputs.cache-key }}
+          key: goodbuddy-agent-release-${{ matrix.platform }}-${{ matrix.arch }}-${{ steps.inputs.outputs.cache-key }}

      - name: Acquire and verify native inputs
        shell: bash
@@ -162,8 +173,14 @@ jobs:
              "$NODE_URL" --output "$node_archive.partial"
            mv "$node_archive.partial" "$node_archive"
          fi
-          printf '%s  %s\n' "$NODE_SHA256" "$node_archive" |
-            sha256sum --check --strict -
+          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
@@ -201,6 +218,7 @@ jobs:
        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 }}
@@ -211,11 +229,12 @@ jobs:
          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-linux-$AGENT_ARCH.gbagent" \
+            --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')
@@ -223,9 +242,10 @@ jobs:
          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}-linux-${architecture}.gbagent` ||
+              `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')
@@ -235,7 +255,7 @@ jobs:
      - name: Upload verified compound package
        uses: actions/upload-artifact@v7
        with:
-          name: goodbuddy-agent-package-linux-${{ matrix.arch }}
+          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
@@ -269,7 +289,7 @@ jobs:
      - name: Download compound packages
        uses: actions/download-artifact@v8
        with:
-          pattern: goodbuddy-agent-package-linux-*
+          pattern: goodbuddy-agent-package-*
          path: dist/agent-release
          merge-multiple: true

@@ -353,6 +373,7 @@ jobs:
          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 \
@@ -489,8 +510,8 @@ jobs:
        run: |
          set -euo pipefail
          root="https://goodbuddy.oss-cn-beijing.aliyuncs.com/agent-releases/v$AGENT_VERSION"
-          for architecture in x64 arm64; do
-            name="goodbuddy-agent-$AGENT_VERSION-linux-$architecture.gbagent"
+          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"
@@ -511,14 +532,8 @@ jobs:
          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
+          notes="resources/agent-release-notes/$AGENT_VERSION.md"
+          test -s "$notes"
          if gh release view "$tag" >/dev/null 2>&1; then
            is_draft="$(gh release view "$tag" --json isDraft --jq .isDraft)"
            if [[ "$is_draft" == true ]]; then
@@ -9,6 +9,8 @@ on:
      - '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'
@@ -19,6 +21,7 @@ on:
      - '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'
@@ -31,6 +34,8 @@ on:
      - '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'
@@ -41,6 +46,7 @@ on:
      - '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'
@@ -73,22 +79,28 @@ jobs:
        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 Linux ${{ matrix.arch }} Agent
+    name: Build ${{ matrix.platform }} ${{ matrix.arch }} Agent
    needs: validate
    strategy:
      fail-fast: false
      matrix:
        include:
-          - arch: x64
+          - platform: linux
+            arch: x64
            runner: ubuntu-24.04
-          - arch: arm64
+          - platform: linux
+            arch: arm64
            runner: ubuntu-24.04-arm
+          - platform: darwin
+            arch: arm64
+            runner: macos-15
    runs-on: ${{ matrix.runner }}
    timeout-minutes: 20

@@ -103,17 +115,23 @@ jobs:
      - 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('./agent-runtime-lock.json')
-          const target = lock.node?.targets?.[`linux-${process.env.AGENT_ARCH}`]
+          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) ||
@@ -147,7 +165,7 @@ jobs:
        uses: actions/cache@v6
        with:
          path: ${{ runner.temp }}/goodbuddy-agent-node
-          key: goodbuddy-agent-ci-node-${{ matrix.arch }}-${{ steps.runtime.outputs.sha256 }}
+          key: goodbuddy-agent-ci-node-${{ matrix.platform }}-${{ matrix.arch }}-${{ steps.runtime.outputs.sha256 }}

      - name: Acquire and verify locked Node runtime
        shell: bash
@@ -170,22 +188,34 @@ jobs:
              "$NODE_URL" --output "$archive.partial"
            mv "$archive.partial" "$archive"
          fi
-          printf '%s  %s\n' "$NODE_SHA256" "$archive" |
-            sha256sum --check --strict -
+          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 lock = require('./remote-runtime-lock.json')
-          const runtime = lock.runtimes?.opencode
-          const target = runtime?.targets?.[process.env.AGENT_ARCH]
+          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 ||
@@ -213,7 +243,7 @@ jobs:
        uses: actions/cache@v6
        with:
          path: ${{ runner.temp }}/goodbuddy-opencode-runtime
-          key: goodbuddy-agent-ci-opencode-${{ matrix.arch }}-${{ steps.opencode.outputs.cache-key }}
+          key: goodbuddy-agent-ci-opencode-${{ matrix.platform }}-${{ matrix.arch }}-${{ steps.opencode.outputs.cache-key }}

      - name: Acquire and verify locked OpenCode Runtime
        shell: bash
@@ -251,16 +281,22 @@ jobs:
          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: |
@@ -270,11 +306,12 @@ jobs:
          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-linux-$AGENT_ARCH.gbagent" |
+            --archive "$directory/goodbuddy-agent-$agent_version-$AGENT_PLATFORM-$AGENT_ARCH.gbagent" |
            tee "$directory/result.json"
          node - <<'NODE'
          const { appendFileSync, readFileSync } = require('node:fs')
@@ -286,6 +323,7 @@ jobs:
          )
          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')
@@ -300,14 +338,16 @@ jobs:
        shell: bash
        env:
          AGENT_ARCH: ${{ matrix.arch }}
+          AGENT_PLATFORM: ${{ matrix.platform }}
          AGENT_SHA256: ${{ steps.agent.outputs.sha256 }}
        run: |
          {
-            echo "### Linux $AGENT_ARCH Agent"
+            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"
@@ -130,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
@@ -174,6 +174,14 @@ jobs:
          name: goodbuddy-production-bundle
          path: out

+      - 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
@@ -240,7 +248,7 @@ jobs:

      - 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
+        run: npm run release:package -- --platform ${{ matrix.platform }} --arch ${{ matrix.arch }} --format dmg --skip-build
        env:
          ELECTRON_CACHE: ${{ runner.temp }}/electron
          ELECTRON_BUILDER_CACHE: ${{ runner.temp }}/electron-builder
@@ -253,7 +261,7 @@ jobs:

      - 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
+        run: npm run release:package -- --platform ${{ matrix.platform }} --arch ${{ matrix.arch }} --format dmg --skip-build --unsigned
        env:
          ELECTRON_CACHE: ${{ runner.temp }}/electron
          ELECTRON_BUILDER_CACHE: ${{ runner.temp }}/electron-builder
@@ -1,6 +1,8 @@
 node_modules/
 out/
 dist/
+# Local build output left by the extracted ShareServer project.
+shareserver/build-server/
 coverage/
 .vite/
 .runtime-resources/
@@ -8,6 +10,8 @@ coverage/
 .agent-resources/
 *.log
 *.tsbuildinfo
+__pycache__/
+*.py[cod]
 .env
 .env.*
 !.env.example
@@ -4,26 +4,60 @@

 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. Working product functionality.
-2. Performance and responsiveness.
+1. Complete, working product functionality.
+2. Measured performance and responsiveness.
 3. Clear, low-friction user experience.
 4. Simple, conventional, maintainable implementation.
-5. Security controls proportional to a concrete, realistic risk.
+5. Security controls only for a concrete risk in the actual deployment model.

-Follow KISS and YAGNI. Do not add trust tiers, consent ceremonies, durable
-state machines, protocol phases, cryptographic identities, quotas, recovery
-machinery, or compatibility layers unless they are needed for an actual user
-workflow or a demonstrated failure mode. Prefer the normal platform mechanism
-and the smallest design that works. Test Hosts are test environments; do not
-turn their workflows into production compliance exercises.
+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
@@ -48,7 +82,8 @@ work as the implemented feature.
 - `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.
@@ -64,6 +99,14 @@ Keep Electron security boundaries intact:
  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.
+- When fixing Runtime behavior or limits, also inspect the remote Runtime path
+  through GoodBuddy Agent (`gbagent`). Verify whether local and remote execution
+  actually share the affected control logic; do not assume that a desktop fix
+  covers the Agent, bridge, launcher, or bundled Runtime. Fix any affected
+  remote-specific implementation and validate it under the GoodBuddy Agent
+  development validation rules below. If no separate remote fix is needed,
+  record which shared implementation covers it or why the remote path is
+  unaffected.
 - Keep model/provider credentials in Main, but do not otherwise reduce Execute
  permissions with extra product policy gates. Keep child-process cleanup
  straightforward and reliable.
@@ -77,7 +120,16 @@ Keep Electron security boundaries intact:

 ## Data and Compatibility

- Preserve existing user data and migrations.
+- Before changing released database schemas or large-data migrations, read
+  [`docs/development/database-migrations.md`](./docs/development/database-migrations.md).
+  Keep feature-specific storage rules and validation evidence in the owning
+  feature documents.
+
+- 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.
@@ -88,6 +140,10 @@ 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
@@ -97,6 +153,13 @@ Keep Electron security boundaries intact:
  repository mechanisms instead of inventing extra gates, ceremonies, or
  disabled states.
 - Add or update focused tests for behavioral changes and regressions.
+- Read [`docs/quality/recurring-defects.md`](./docs/quality/recurring-defects.md)
+  before changing overlays, store lookups, retrieval entry points, cancellation
+  behavior, or render-time derived values. It records defect types that have
+  already recurred in this repository and the shared mechanism that covers each
+  one. When fixing an instance of a listed type, extend that shared mechanism
+  instead of patching the one reported case, and add an entry when a new defect
+  type recurs.
 - After completing any functional change, inspect the affected product,
  architecture, design, feature, setup, and operational documentation and
  update every relevant document to match the implemented behavior. Treat the
@@ -108,6 +171,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
@@ -133,11 +212,6 @@ Keep Electron security boundaries intact:
  blocking page state, or an error with an immediate local recovery action.
 - Do not show the same event both inline and as an application notification.
  Preserve user input and actionable error context when an operation fails.
- Treat renderer bundle budgets as regression guardrails, not UX targets. Do
-  not lazy-load one lightweight peer tab solely to satisfy a byte ceiling.
-  When a genuinely heavy view needs deferred loading, preserve peer
-  interaction semantics, render a non-empty layout-stable local fallback,
-  and test its first interaction rather than only its eventual appearance.

 ## Commit Messages and Release Notes

@@ -180,276 +254,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.
- 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 or arm64 `.gbagent` contains the
-  Agent daemon, pinned Node, and the desktop-maintained compatible OpenCode
-  Runtime. Build both architectures 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.
- `.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.
+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.

-### Agent Release Process
+Repository-wide release invariants:

- 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 two native
-  jobs build the compound x64/arm64 packages from the same source and locks;
-  the catalog job rejects missing architectures, changed bytes for an existing
-  version/architecture identity, invalid prior signatures, and incompatible
-  matrix metadata.
- 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`, the required source validators, the
-   production build, and any native candidate launch probe available on the
-   current host. The six native CI jobs remain the cross-platform authority.
-   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. Fetch both remotes immediately before tagging. Inspect any remote branch
-   movement instead of overwriting or silently merging it. Confirm the working
-   tree is clean, the candidate tag is unused locally and remotely, and the
-   exact approved commit has not changed.
-8. Only after all previous steps pass, create an annotated
-   `v${package.version}` tag at the exact approved commit. Push `main` to
-   `origin` and `github`, verify both branch SHAs, then 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. The GitHub asset set has exactly the expected 22 names and every asset is
-   uploaded. Compare installer sizes and SHA-256 digests with the aggregate
-   manifest and `SHA256SUMS`.
-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`.
-5. All 14 public installer URLs accept `HEAD` without redirects and report the
-   declared size. For small JSON/checksum metadata, prefer a `GET` byte and
-   digest comparison; OSS may gzip JSON responses and omit an uncompressed
-   `Content-Length` on `HEAD`.
-6. The live website successfully fetches the index and produces the 14 correct
-   platform/architecture/format links. Exercise the application's actual
-   mirror checker against the public index for all six targets.
-7. 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.
+- 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

@@ -461,19 +302,62 @@ 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. 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.
+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.
+- During remote testing, prefer dedicated test directories under `/root/tmp`
+  for temporary files. Avoid creating files under `/tmp` where possible, since
+  it may be memory-backed and consume additional RAM. Set `TMPDIR` to the
+  dedicated test directory when needed so test tools use it as well.
+- 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
@@ -31,6 +31,10 @@ npm start

 ## 质量验证

+跨功能测试方法见[质量验证索引](./docs/quality/README.md)。桌面界面的测试分层、
+原生键盘、截图与计算样式取证、隔离启动和脱敏报告遵循
+[Electron UI 自动化测试规范](./docs/quality/electron-ui-automation.md)。
+
 提交或打包前运行：

 ```bash
@@ -56,6 +60,14 @@ OpenCode/Continue 用例默认读取 `dist/harness-package-probe/win-unpacked`
 调用。测试不会输出 API Key，文件操作在临时工作区中执行。文件包含经 Main 回环
 broker 调用已分配自定义 MCP 的真实 OpenCode 和 Continue 用例。

+不使用外部模型的 Runtime 原生交互回归位于
+`src/main/agent/opencode-runtime-permissions.test.ts`、
+`src/main/agent/continue-runtime-permissions.test.ts` 和
+`src/main/agent/deepseek-harness-acp-e2e.test.ts`。它们用本地确定性模型驱动真实 Runtime
+或固定 Host，覆盖工作区外访问、原生问答及 Ask 边界。OpenCode 用例默认使用开发缓存
+二进制；可通过 `GOODBUDDY_TEST_OPENCODE_BINARY` 指定已经安装的候选二进制，避免把
+仍在运行的旧缓存版本当作候选版本验证。这不替代当前源码 Agent 的 Linux Host 验收。
+
 ## 生产构建

 生成 Electron Main、Preload 和 Renderer 生产文件：
@@ -132,6 +144,12 @@ npm run dist:linux:arm64

 打包产物位于 `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`）都不会嵌入
@@ -139,7 +157,7 @@ npm run dist:linux:arm64
 组件，缺少远端包也不能阻塞普通桌面打包或发布。

 “设置 > 平台功能 > 远程项目（技术预览）”列出用户数据目录中已经下载或导入的
-Linux x64/arm64 复合 Agent 包。首次打开和手动刷新会从“关于与更新”所选来源读取
+Linux x64、Linux arm64 和 macOS arm64 复合 Agent 包。首次打开和手动刷新会从“关于与更新”所选来源读取
 小型签名目录，显示本地版本、在线最新兼容版本以及 `有更新 / 已是最新 / 未下载 /
 校验失败`；此检查不会下载 `.gbagent`。只有用户点击“下载”或“更新到”后才传输包，
 用户也可导入或导出 `.gbagent` 离线包。
@@ -151,17 +169,63 @@ Main 在写入缓存前校验签名目录、目录签名、大小、SHA-256、
 production/test 环境和撤销列表，不来自 JSON 空白或换行。读取桌面资源、复合包和 Host
 已有 registry 时接受等价 UTF-8 JSON 格式；向 Host 写入前统一重新序列化为确定性 LF
 JSON。签名目录、包描述符、manifest、签名和 payload 的原始字节校验保持不变，包下载
-继续流式计算 SHA-256，不使用 MD5。
+继续流式计算 SHA-256。

-“SSH 主机 > 远程运行环境”的“更新版本”只使用已验证的本地复合包。对应 Host 架构
-尚未下载时会提示先到设置下载或导入，不会联网，也不会影响本地项目、普通桌面功能或
-其他架构的 Agent 包。
+“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 平台二进制来自 `.runtime-resources/<arch>`。
+- Desktop 的离线配置复制以 `.runtime-resources` 为源、`opencode-config{,/**/*}` 为过滤器，避免 electron-builder 对复制源根目录下 `node_modules` 的固定排除。最终包逐文件核对离线配置与依赖；DSH bootstrap 和 chunk 不得残留外部 `@deepseek-ai/*` 导入。Windows x64 CI 在删除解包目录前实际导入包内 OpenCode 插件并运行隔离的 DSH UtilityProcess 握手与 npm 探针，失败即停止发布。
+- OpenCode 离线配置位于 `.runtime-resources/opencode-config`，构建时按已安装 `@opencode-ai/plugin/package.json` 的版本复用，不依赖根 lockfile 或自定义 ready/integrity 标记。缺失、不可读或版本不匹配时，在 staging 中执行精确版本 npm 安装，成功后替换缓存；安装失败保留旧缓存并清理 staging。本机共享配置同样比较随包插件与缓存插件的版本，版本不同时通过 staging 替换。
+- 离线依赖安装禁用 npm bin links；远程 Runtime 组包排除不使用的 `.bin` 命令链接，并把复制后的普通依赖文件统一为 `0644`，OpenCode 入口仍为 `0755`。目录元数据、每个依赖文件及许可证继续纳入签名校验。
 - Continue Runtime 来自锁定版本的 `@continuedev/cli`。
 - DSH 插件安装使用精确锁定并从 `app.asar` 解包的 npm CLI，通过当前 Electron 的 Node 模式运行；最终用户不需要另装 Node.js 或 npm。
 - DSH 图片输入使用精确锁定的 `@napi-rs/canvas` 完整解码 JPEG/PNG。通用包与目标平台、目标架构的 Skia 原生包必须从 `app.asar` 解包；当打包 Runner 的架构与目标架构不同时，发布脚本会根据 lockfile 的精确版本、下载地址和 integrity 临时暂存目标原生包，完成后清理。发布校验会检查版本、目标架构和 MIT 许可证。
@@ -169,11 +233,22 @@ JSON。签名目录、包描述符、manifest、签名和 payload 的原始字

 跨架构打包前，确认目标架构的 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 \
@@ -194,16 +269,32 @@ node build/agent-package.cjs build \
 Agent 源码、共享协议、lock、bundle 工具和测试与桌面应用保持在同一仓库、同一 commit；
 不维护长期分叉的 Agent 源码分支。`.github/workflows/agents.yml` 在相关 Pull Request、
 `main` push 和手工触发时，分别使用 `ubuntu-24.04` 与 `ubuntu-24.04-arm` 原生构建
-Linux x64/arm64 复合包。每个 job 从 `agent-runtime-lock.json` 解析官方 Node HTTPS
+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 原生启动 smoke 和确定性 `.gbagent` 对比。
+测试签名验证、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 中
-原生构建两种架构，生成并签名累计目录，然后同步到非 Latest 的 GitHub Agent Release
+原生构建 Linux x64、Linux arm64、macOS arm64 三个目标，生成并签名累计目录，然后同步到非 Latest 的 GitHub Agent Release
 与北京 OSS。该 Environment 只保护一组 GoodBuddy 通用发布变量与 Secret：

 - `GOODBUDDY_SIGNING_KEY_ID` /
@@ -224,7 +315,7 @@ OSS 先写 `agent-releases/v<version>/` 不可变对象，GitHub Release 公开

 ### 远程 OpenCode Runtime 基础

-`remote-runtime-lock.json` 独立锁定首个远程 Runtime：OpenCode 1.18.9 的 Linux x64
+`remote-runtime-lock.json` 独立锁定首个远程 Runtime：OpenCode 1.18.29 的 Linux x64
 baseline 与 arm64 官方包 integrity、`bin/opencode` 入口和固定 `acp` 参数。它不同于
 `agent-runtime-lock.json`，后者锁定 Agent 自带 Node 以及用于 Linux `SO_PEERCRED`
 的 Koffi 版本。Agent bundle 将 Koffi loader 作为 external module，并只携带目标
@@ -248,10 +339,11 @@ 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、
-Ask 的固定 `bwrap` 只读 profile 和 `runtime/model-bridge` v1。Agent 通过私有 Unix socket
-按需 detached 启动，不依赖 systemd、D-Bus 或 Linger。Execute 直接以所选 SSH 账号权限
-启动签名 Runtime；Ask 才使用只读 bubblewrap。
+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
@@ -260,7 +352,7 @@ HTTP 入口使用每个进程随机生成的路径 capability，Anthropic/OpenAI
 配置必须禁用 title Agent；工具循环只使用 build Agent 的模型轮次。

 Ask 模式的 ACP 权限中介只可为原生 `read` 选择 `allow_once`；其他工具种类和
-`allow_always` 请求必须拒绝，Workspace 的真正只读边界仍由 `bwrap` 执行。Unix 模型桥
+`allow_always` 请求必须拒绝。Unix 模型桥
 broker 必须按 socket 当前已缓冲字节增量读取长度帧，不能等待 `read(remaining)` 一次返回
 完整大响应。Agent 传输或权限实现变化后，除了普通测试，还要在原生 Linux 上运行包含
 至少 256 KiB 响应的模型桥回归。
@@ -271,15 +363,17 @@ broker 必须按 socket 当前已缓冲字节增量读取长度帧，不能等
 唯一标识对应版本的精确工件。变更后必须重新构建、签名并导入 Linux x64/arm64 两套工件；
 旧版本或旧 digest 会按设计校验失败。不要手工把本机 `.runtime-resources` 当作远程 bundle。

-桌面应用更新后不会在项目激活时自动下载 Agent。用户先在设置中显式下载“最新兼容”
-版本或导入离线包；随后打开托管 SSH 项目时，Main 才使用该 Host 架构的本地验证包执行
-完整激活。所需版本健康且项目事务提交成功后才刷新项目绑定；失败不会覆盖旧安装或把
-未提交的新 identity 暴露给 Workspace/Runtime。
+桌面应用更新后不会在项目切换时下载或安装 Agent。用户先在 SSH Host 的远程运行环境
+卡片显式选择直连下载或 GoodBuddy 传输。托管 SSH 项目只保存 Host ID、远端路径、
+Runtime 选择和默认模式；创建或保存时验证 Host 当前环境，普通项目切换只读取这些本地
+配置。首次实际使用 Workspace 或 Runtime 时解析 Host current identity；同一进程内后续
+项目复用已确认的 Agent/Runtime identity 和 Agent 连接。该流程不取得安装包、不重读完整
+payload，也不发布组件。

-用户也可在 SSH Host 的远程运行环境卡片显式选择“更新版本”。该路径按 Agent、
-OpenCode Runtime 顺序使用对应架构的本地复合包，支持阶段进度和取消；成功后使引用该 Host
-的项目重新验证。验收应覆盖激活与此手动入口，并确认失败或取消不会删除
-Host 配置、凭据、项目设置、Workspace 文件或仍可用的旧安装。
+两条手动准备路径都支持阶段进度和取消；成功后定向失效该 Host 的连接与 Runtime 缓存，
+引用项目下一次打开自然使用新的 current 环境。验收应覆盖两种准备方式与项目当前环境
+验证入口，并确认失败或取消不会删除 Host 配置、凭据、项目设置、Workspace 文件、全局
+可信元数据或仍可用的旧安装。

 ## 跨平台 CI 与 GitHub Release

@@ -308,8 +402,8 @@ DeepSeek Harness Runtime、`app.asar`、目标架构和安装包签名。
 npm run release:package -- --platform macos --arch <x64|arm64> --unsigned
 ```

-默认发布产物为 Windows 的 NSIS 安装包与 portable ZIP、macOS 的 DMG 与
-ZIP，以及 Linux 的 AppImage、DEB 与 RPM。Linux 原生 Runner 必须安装
+默认发布产物为 Windows 的 NSIS 安装包与 portable ZIP、macOS 的 DMG，
+以及 Linux 的 AppImage、DEB 与 RPM。Linux 原生 Runner 必须安装
 `rpm`/`rpmbuild` 工具后再调用 electron-builder。Windows portable ZIP 解压后可直接
 运行 `GoodBuddy.exe`，并包含启用便携数据目录的
 `.goodbuddy-portable.json`。每个目标目录都包含带文件大小和 SHA-256 的
@@ -319,12 +413,34 @@ ZIP，以及 Linux 的 AppImage、DEB 与 RPM。Linux 原生 Runner 必须安装
 打包矩阵，避免随后推送版本标签时对同一提交重复完整打包。手动触发会运行
 验证和六平台打包，并保留 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`。随后工作流通过
 GitHub OIDC 获取短期 STS 凭据，将发布资产和 `site-release.json` 上传到
-北京 OSS 的不可变版本目录，并公开校验 14 个安装包。验证通过后才创建或
-更新 draft GitHub Release、上传 22 个 Release 资产并正式发布，最后原子
+北京 OSS 的不可变版本目录，并公开校验 12 个安装包。验证通过后才创建或
+更新 draft GitHub Release、上传 20 个 Release 资产并正式发布，最后原子
 切换官网 `latest.json`。任一步失败都不会提前切换官网最新版本。

 同一标签重跑时，工作流会根据 `resources/release-notes.json` 重新生成并
@@ -345,6 +461,13 @@ git tag -a "$agent_tag" -m "GoodBuddy Agent $(node -p "require('./agent-runtime-
 OSS 签名目录指针。生产发布需要 `agent-signing` 与 `aliyun-oss-release` 两个受保护
 Environment；普通分支/PR 的 `agents.yml` 不使用其中任何 Secret。

+Agent 标签也必须遵循与 Desktop 相同的 pre-tag 顺序。更新 Agent 生产源码或
+`agentVersion` 后，先把候选提交推送到两个 `main`，等待该准确 SHA 的
+`GoodBuddy Agents` main workflow 全部成功，再次 fetch 并确认两个远端 `main`、干净
+工作区和未使用标签，最后才可创建和推送 annotated `agent-v<version>`。不得把 Agent
+标签与候选 `main` 放在同一批推送中；任何修正 commit 都必须重新等待新 SHA 的 Agent
+main workflow，旧 SHA 的成功结果不能复用。
+
 中英文发布说明统一维护在 `resources/release-notes.json`。新版本按“本次
 亮点 / Highlights”“功能更新 / Features”“问题修复 / Bug Fixes”“使用前
 请留意 / Before You Start”四段组织，应用首次启动弹窗与 GitHub Release
@@ -364,7 +487,7 @@ git push github "$tag"
 macOS 发布 job 会先原子判断 Apple 凭据状态：以下五项 Actions Secrets 全部
 存在时，使用 Developer ID Application 证书签名，并通过 App Store Connect
 API Key 提交 Apple notarization；五项全部缺失时，明确生成未签名、未公证的
-DMG 和 ZIP，并在 Actions 日志与摘要中警告 Gatekeeper 限制；只配置一部分时
+DMG，并在 Actions 日志与摘要中警告 Gatekeeper 限制；只配置一部分时
 任务失败，不能静默降级为未签名包。

 - `MACOS_CERTIFICATE_BASE64`：包含证书及私钥的 `.p12` 文件经 Base64 编码后的内容。
@@ -455,36 +578,3 @@ npm test -- src/main/agent/deepseek-harness-acp-e2e.test.ts -t "rejects a real n

 如需覆盖发布包内置 npm 路径，再设置 `GOODBUDDY_DSH_NPM_CLI` 与
 `GOODBUDDY_DSH_NODE_EXECUTABLE` 指向已解包应用中的 npm CLI 和应用主程序。
-
-## Renderer bundle 性能门禁
-
-`electron-vite` 会在 `out/renderer/.vite` 生成 Vite manifest 和仅含构建模块
-归属的 module manifest。`npm run build:bundle` 在 bundle 完成后自动运行
-`build/check-renderer-bundle.cjs`，去重统计首屏同步闭包及 Knowledge、知识图谱、
-Activity、Magic Notes、Settings 动态入口同步加载的 JS 与 CSS 合计 raw / gzip
-大小并执行预算校验。
-
-门禁同时验证以下结构约束：
-
- Knowledge、Activity 与 G6 不得进入首屏同步闭包。
- `KnowledgeGraphChart` 与 G6 不得进入 Knowledge shell 的同步闭包。
- G6 必须由知识图谱动态入口同步拥有。
-
-路径遍历使用 manifest 中的相对文件名并通过 Node `path.resolve` 读取，因此兼容
-Windows 与 POSIX 构建输出。构建专用 module manifest 只记录项目相对路径、
-`node_modules/` 相对路径或稳定的虚拟模块名，不记录 Runner 的盘符、主目录或
-绝对路径；检查成功后会删除该诊断文件，检查失败时保留以便排查。标准 Vite
-manifest 会保留在输出中。预算以干净生产构建为基线并保留有限余量；若业务确需
-提高预算，必须先检查 manifest 闭包和产物差异，不能只为通过 CI 调大数值。
-
-Bundle 大小是发现意外依赖和持续膨胀的粗粒度工程护栏，不是用户体验指标，也不能替代
-Electron 中的实际交互验证。Settings 的硬上限以 2026-08-23 验证构建
-`648.78 kB raw / 97.79 kB gzip` 为基线，增加约 15% 评审余量后取整为
-`750 kB raw / 115 kB gzip`。该上限用于拦截显著增长，不要求实现长期贴线运行。
-
-调整 Renderer 拆包时遵守以下优先级：
-
-1. 同级页签的交互一致性、首个绘制帧内反馈和输入保留优先于包体数字。
-2. 不得仅为通过预算，把一个原本轻量的同级页签单独改成首次点击才加载。
-3. 确需动态加载重型功能时，必须提供非空、无布局跳变的局部状态，并增加首次交互测试。
-4. 修改预算必须记录干净生产构建基线、增量闭包差异和 Electron 实测结果。
@@ -1,103 +1,799 @@
-# 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] Completed
+- [ ] To implement

-### 桌面基础、工作空间与上下文
+Status describes implementation, not publication or test coverage. Validation
+records are listed separately and do not introduce another feature status.

- [x] **跨平台桌面应用**：支持 Windows、macOS、Linux，以及 `x64`、`arm64` 发布目标。
- [x] **可配置全局快捷唤起**：在“平台功能 / 通用设置”中启停或录制 Electron accelerator；默认保留 `CommandOrControl+Shift+Space`，冲突或保存失败时继续使用上一组已注册快捷键，并显示可处理的状态。
- [x] **Projects、独立对话与会话分支**：按项目隔离上下文，管理会话、附件和 Git 工作区变更；本地会话可在稳定状态下复制当前聊天内容到独立分支，分支持续显示来源徽标且不复制 Task、队列或成果归属；项目选择器区分本地、托管 SSH 与远程消息通道项目，并显示对应目录或来源。
- [x] **文件、截图、窗口、剪贴板上下文**：用户明确选择后才加入模型上下文。
- [x] **富文本回答**：支持 GitHub Flavored Markdown、LaTeX 数学公式和受控 Mermaid 图表；大图可缩放、拖动或查看源码，失败时保留原始图表代码。
- [ ] **项目 Agent Space**（规划中）：在 Project 中统一角色、知识、Skills/MCP、模型、审批策略、预算和超时，并支持模板复用。
- [ ] **通用助手工作栏与执行空间**（规划中）：保留 Task Center 作为 Task 的单例索引，并把监督、Runtime、终端、进程、工作区、浏览器和成果作为始终可访问的应用级能力；除 Task Center 外的可绑定能力由用户选择跟随或固定目标，并逐步支持静态安全 HTML 预览、本机/SSH 执行空间和远程 Agent Runtime。附件与知识库继续由会话输入区管理，未来的记忆与历史执行上下文归入关联 Task。详见 [Feature PRD](./docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。
+## Feature Matrix

-### Agent Runtime 与模型连接
+### Desktop foundation, workspaces, and context

- [x] **直连模型 Runtime**：支持问答、知识总结、受控工具执行和图像生成。
- [x] **OpenCode 与 Continue**：使用隔离子进程、环境变量白名单、统一配置、取消、总执行时限、有界流式输出和活动记录；共享进程回收逻辑保留 Windows 完整进程树终止，并对采用独立进程组的 POSIX 子进程执行组回收。交互提问只由前台对话回答，定时任务、远程通道和委派等后台执行遇到提问时会立即失败并提示改为前台运行，避免无限等待。
- [x] **托管 SSH OpenCode 闭环（技术预览）**：该能力由“设置 > 平台功能”中的独立“远程项目（技术预览）”页签控制并默认关闭；关闭时不影响任何本地项目、普通桌面功能或桌面发布。启用后可管理固定 Host Key 的 SSH Host、浏览有界远端目录并创建 Ask/Execute 项目；Ask 在 Runtime 边界通过 bubblewrap 保持 Workspace 只读，Execute 使用所选 SSH 账号的完整权限。Main 通过签名 Agent、私有 Unix socket、ACP v3、持久恢复 cursor 和 Main-only 模型桥维持长任务、重连与会话恢复，模型凭据不进入远端。远端组件不嵌入桌面包，也不会在项目激活时自动下载；设置页只读取小型签名目录并按 Linux x64/arm64 显示本地版本、在线最新兼容版本和“有更新/已是最新”，用户点击后才下载签名 `.gbagent`，也可导入/导出离线包。每个复合包包含 Agent、固定 Node 与由桌面源码统一维护适配的 OpenCode Runtime；在线来源跟随“关于与更新”的 GitHub/北京 OSS 选择，签名累计目录绑定最低桌面版本、Agent 协议、架构、大小、SHA-256 和固定 URL。公钥 registry 接受等价 JSON 空白和换行，但仍严格校验 schema、Ed25519 key、环境与撤销；目录、包、manifest、payload 签名和流式 SHA-256 不变。缺少某架构包只使该架构托管 SSH 不可用。持久化验证继续精确绑定 Agent installation 与签名 Runtime digest；托管 SSH 会话只显示支持的 OpenCode 选择。Windows 到 Linux x64 的安装、provider-free 模型桥、断线重放、Session 续接和零残留清理已完成真实 Host 验证；签名 Agent 0.11.2-e2e.12 与 OpenCode Runtime 1.18.9 已完成一次只提交一遍、只调用一个 Ask 原生 read、无标题轮次且精确返回证据内容的有界真实模型验收，当前源码 lock 已转为正式 Agent 0.11.5。
- [x] **SSH Host 运行环境手动更新**：远程运行环境卡片只读取 Host 已安装 Agent/Runtime 与当前本地复合包所需版本，不会联网。用户显式触发后，Main 按 Agent、Runtime 顺序使用对应 Host 架构的已验证本地 `.gbagent` 强制重新校验并安装，显示阶段进度并允许在最终收尾前取消；尚未下载时提示先到平台功能设置下载或导入。更新期间保留旧版本卡片，失败或取消后刷新实际状态并允许重试；成功后定向清理该 Host 缓存并使引用项目重新验证，不删除 Host 配置、凭据、项目设置或 Workspace 文件。
- [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] **角色绑定模型连接**：每个角色可继承默认模型或选择独立文本模型连接，失效连接安全回退默认模型，综合角色始终继承默认模型。
- [x] **多协议模型配置**：支持 Anthropic Messages、OpenAI Responses、OpenAI Chat Completions、OpenAI Images 和无认证本机模型；新用户默认连接为本机 Ollama 兼容地址，不预置第三方云模型服务。升级时只替换从未配置凭据且仍完全等于旧内置值的历史默认连接，用户显式保存或加密凭据的连接保持不变；已有部署仅使用兼容环境变量提供凭据时继续沿用对应的历史连接参数，通用模型环境变量仍优先。“保存并测试模型”会发送有界的真实文本或图片生成请求并校验生成结果，而不是只检查 HTTP 连通性，因此可能产生少量服务商用量费用。
- [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；并发外部 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 聚合状态、取消入口和审计归属。
+- [x] **Cross-platform desktop application**: Supports Windows, macOS, and
+  Linux release targets on `x64` and `arm64`.
+- [x] **Chinese hardware and operating-system coverage**: Standard Linux
+  packages target compatible x64 and arm64 environments, including UOS, Kylin,
+  Hygon, Zhaoxin, Kunpeng, and Phytium systems. This is not vendor certification.
+  LoongArch has a separate experimental loong64 preview outside standard
+  releases and automatic updates; no preview is planned for 0.13.5. See the
+  [preview boundaries](./docs/development/loongarch-preview-build.md).
+- [x] **Configurable global shortcut**: Enable, disable, or record an Electron
+  accelerator under Platform Features / General. The default remains
+  `CommandOrControl+Shift+Space`; if registration conflicts or saving fails,
+  GoodBuddy keeps the previously registered shortcuts and shows an actionable
+  status.
+- [x] **Projects, independent conversations, and conversation branches**:
+  Isolates context by project and manages conversations, attachments, and Git
+  workspace changes. A stable local conversation can be copied into an
+  independent branch; the branch retains a source badge but does not copy
+  Tasks, queues, or artifact ownership. The project selector distinguishes
+  local, managed SSH, and remote messaging-channel projects. Managed SSH
+  projects are grouped by Host, with the real Agent connection state on the
+  Host heading and only the remote path on each project row.
+- [x] **Cross-project conversation activity**: A shared activity entry lists
+  running conversations and conversations needing attention across projects,
+  including older conversations with live work. Anchored project-to-conversation
+  menus provide keyboard navigation and exact conversation opening without a
+  full activity dialog. The summary hides when idle, long conversation submenus
+  scroll independently, and project selection continues to show activity counts.
+- [x] **Compact conversation controls**: Composer options share a compact
+  settings panel while Runtime, mode, sending, and queue controls remain
+  available. Conversation search has an inline clear action that restores the
+  scoped list and returns focus to the input.
+- [x] **File, screenshot, window, and clipboard context**: Added to model
+  context only after explicit user selection. Paste one or more supported local
+  files into the chat composer with `Ctrl+V` to add attachments, using the same
+  parsing progress and limits as the attachment button. Text and screenshot
+  paste remain available. See [attachment rules](./docs/features/document-processing/prd.md#321-聊天附件入口).
+- [x] **Text recognition in image-based PPTX files**: With local OCR configured
+  and an OCR-enabled parsing workflow, embedded PNG, JPEG, and WebP images are
+  recognized alongside native text, retaining slide locations. OCR releases
+  model memory after 60 seconds without active or queued work and reloads on
+  demand; fast text/index modes still skip OCR. See the
+  [parsing behavior and real-file evidence](./docs/features/document-processing/chat-attachments-technical-design.md).
+- [x] **Per-file workspace diffs**: Changed files expose separate staged and
+  unstaged diffs, including deleted, renamed, and untracked files. Refresh
+  reloads the selected diff, browsed directory, and expanded directories; more than 50 changes
+  remain accessible through incremental loading.
+- [x] **Workspace file and Git management**: Create, rename, move, and delete
+  files or directories, inspect properties, search and switch local or remote
+  branches, create branches, explicitly Fetch, and browse commit history and
+  per-file commit diffs. File and Git controls are grouped by view, branch
+  search uses the shared compact form style, and subdirectories retain text
+  breadcrumbs without an isolated root icon. Commit history stays docked at
+  the bottom, initially expands to half the Git content area, and supports
+  resizing with independently scrolling panes and one shared refresh action.
+  Project switches automatically detect Git without reusing another project's
+  status. Moves stay inside the workspace,
+  deletion requires confirmation, and branch conflicts never trigger automatic
+  stash or discard. Managed SSH operations require Agent `0.11.23`.
+- [x] **Rich responses**: Supports GitHub Flavored Markdown, LaTeX math,
+  constrained Mermaid diagrams, and static in-conversation HTML previews.
+  Complete HTML and HTML code blocks can be previewed in place after an Agent
+  reply finishes, with icon actions to reveal the source or open a full-screen
+  preview. The feature is on by default and can be disabled under Platform
+  Features / General; previews cannot run scripts, access the network, submit
+  forms, or open windows.
+- [x] **AI response and full-conversation copy**: Completed AI responses expose
+  a bottom action that copies Markdown source without reasoning, tool logs, or
+  citation metadata. Full-conversation copy uses the same validated
+  Preload/Main clipboard path.
+- [x] **Assistant workbar, multiple terminals, and resizable layouts**: The
+  toggle sits beside the theme switch. The right workbar uses a persistent “+”
+  capability catalog and application tabs.
+  Task Center and Workspace are permanent singleton tabs; browser tabs are
+  independent instances. Task Center can show the current project, global
+  tasks, or all projects, and retains the selected scope with the layout.
+  Users can open multiple independent terminals for the current local or
+  managed SSH project with bounded output, resizing, termination, and explicit
+  reconnection. Closing a terminal tab ends its Shell; restarting the app
+  restores only an ended tab description and never restarts the Shell. The
+  main sidebar and Magic Notes list support pointer and keyboard resizing;
+  the notes list can be hidden, remembers its layout, and stacks at narrow
+  widths.
+- [ ] **Project Agent Space** (planned): Unifies roles, knowledge, Skills/MCP,
+  models, approval policy, budgets, and timeouts in a Project, with reusable
+  templates.
+- [ ] **Application navigation and system-tool shortcuts** (design only):
+  Plans fixed system entries, configurable built-in application visibility,
+  and footer shortcuts into the existing workbar. These are not implemented
+  interface changes. See the [design](./docs/features/application-tool-navigation/README.md).
+- [ ] **Additional assistant workbar and execution-space capabilities**
+  (planned): Builds on the current workbar and multiple terminals with
+  supervision, unified Runtime monitoring, managed processes, safe static HTML
+  preview, target-pinnable workspace/browser/artifact instances, bottom
+  docking, and separate windows. Task Center remains the singleton Task index;
+  attachments and knowledge remain in the conversation composer, while memory,
+  when implemented, and historical execution context belong to the associated Task. See
+  the [Feature PRD](./docs/features/assistant-workbar/prd.md).
+- [ ] **ShareServer Office co-editing** (design): Uses an optional ShareServer
+  integration with ONLYOFFICE Docs to open multiple filename-labelled document
+  tabs in the assistant workbar. The planned scope covers DOCX, XLSX, and PPTX
+  manual editing, save and undo, source-file conflict protection, and later AI
+  selection edits. The selected ShareServer and editor process document content;
+  Desktop neither bundles nor starts Document Server and does not claim offline
+  editing when no service is configured. See the
+  [design](./docs/features/office-document-editing/README.md).

-### Skills、MCP 与知识库
+### Agent Runtimes and model connections

- [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 编辑**（规划中）：从对话、知识和网页收集带来源的摘录，并提供需确认的总结、改写和整理操作。
+- [x] **Compact subagent history without lost details**: Local and managed SSH
+  subagent events store changes instead of repeated full progress snapshots.
+  The first upgrade automatically converts existing history and reclaims disk
+  space, with visible progress and quit/retry support. Chats, execution details,
+  results, and remote event deduplication are preserved; older clients cannot
+  reopen the upgraded database. The schema-35 repair released in 0.13.2 also handles
+  repeated tool blocks written after upgrading to 0.13.1, without deleting events.
+  Terminal tasks release their write caches; duplicate remote replay does not
+  rebuild a released cache. See
+  [storage and upgrade behavior](./docs/features/assistant-workbar/execution-history-storage.md).

-### 工作管理、长期协作与工作流
+- [x] **Direct model Runtime**: Supports question answering, knowledge
+  synthesis, controlled tool execution, image generation, and reference-image
+  editing through providers supporting the OpenAI-compatible image-editing
+  endpoint. Editing sends attached images as multipart data and still requires
+  validated inline image output rather than fetching provider-returned URLs.
+  Follow-up image requests reuse the latest successful image and conversation
+  text, including after reopening a saved conversation; explicit attachments
+  take priority. Missing editing support does not block text-based generation:
+  the affected reply shows a quiet footer explaining that reference images were
+  not used. See [image generation](./docs/features/image-generation/README.md).
+- [x] **Image tools in the current conversation**:
+  Enable conversation access for an image model to let tool-capable chat models
+  generate images and edit uploads or earlier artifacts in Execute, without a
+  separate conversation or manually switching to an image model. Direct text
+  models, local OpenCode, Continue, DeepSeek Harness, and managed remote OpenCode
+  use the shared service; Runtime assignment is derived from model settings.
+  Requests may incur provider charges and editing requires provider support.
+  See the [implementation and validation records](./docs/features/conversation-media-generation/progress.md).
+- [x] **Cross-project Runtime process reuse**: Compatible local OpenCode and
+  DeepSeek Harness configurations share heavyweight processes; managed OpenCode
+  sessions share a process on the same Host. Project adapters and session
+  workspaces, models, tools, questions, and cancellation stay independently
+  routed. Remote pending questions and task status recover after reconnect or
+  Desktop restart without resending accepted prompts. Requires Desktop `0.13.5`
+  and Agent `0.13.0` together for the new remote behavior. See the
+  [design and measured validation](./docs/features/assistant-workbar/runtime-process-reuse-technical-design.md).
+- [x] **Direct model programming agent**: Local direct text models can run the
+  platform Shell in Execute mode and delegate one level of programming
+  Subagent work while inheriting the parent request's mode, model, workspace,
+  and capability scope. OpenCode, Continue, DeepSeek Harness, and managed SSH
+  do not receive duplicate copies of these tools. The Windows local command
+  path and a real-model edit, test, fix, and review loop have passed; native
+  macOS and Linux command validation remains. Execute commands can select
+  absolute, relative, or symbolic-link directories outside the workspace;
+  the workspace stays the default and relative-path base. Ask remains read-only.
+- [x] **OpenCode and Continue**: Use isolated child processes, an environment
+  variable allowlist, unified configuration, cancellation, startup and control-request
+  deadlines, bounded streaming output, and activity records. Shared process
+  cleanup preserves complete Windows process-tree termination and terminates
+  POSIX process groups when a child uses an independent process group. Chat
+  status checks use a one-shot Runtime probe that is immediately cleaned up
+  rather than entering the model-and-project execution cache. For managed
+  local OpenCode, this passive check validates the selected path and model
+  credential without starting a throwaway server; the explicit settings test,
+  native inventory still performs full startup and health checks, then shares
+  that execution Runtime with the first real request instead of cold-starting
+  another server. Execution Runtime adapters remain reusable per project, while local
+  OpenCode configuration dependencies and content-addressed Skill snapshots are
+  shared globally across projects. Session data, tool output, and request-scoped
+  MCP state remain isolated. GoodBuddy-managed local OpenCode keeps
+  requests in the same conversation ordered, while different conversations in
+  the same project and different projects can run in parallel. Request-scoped
+  dynamic MCP tools remain isolated through default wildcard disablement and
+  explicit current-request enablement. Managed local and remote OpenCode skip
+  unused automatic Git snapshots to avoid synchronous diff stalls; file tools,
+  subagents, and workspace Git diffs remain available. Continue continuously
+  drains unused utility-host stdout so console output cannot fill its pipe.
+  These changes apply to newly started Runtimes, not external OpenCode Servers.
+  OpenCode and Continue runs do not stop
+  at a fixed tool-call or activity count, and every observed tool and Subagent
+  activity remains in the local conversation instead of being discarded while
+  the native task continues.
+  Interactive questions are answered only by foreground conversations; scheduled tasks, remote channels,
+  delegated work, and other background runs fail immediately with guidance to
+  rerun in the foreground
+  instead of waiting indefinitely. Local OpenCode startup uses the selected
+  absolute path directly without checking the file or running `--version`
+  first; invalid paths fail at actual launch. On managed Linux ARM Hosts,
+  Runtime activation reuses the registry and manifest verified during setup
+  instead of rehashing or rechecking the complete OpenCode binary.
+- [x] **Managed SSH OpenCode loop (technical preview)**: Controlled by the
+  separate Remote Projects (Technical Preview) tab under Settings / Platform
+  Features and disabled by default. Disabling it does not affect local
+  projects, ordinary desktop capabilities, or desktop releases. When enabled,
+  users can manage SSH Hosts with pinned Host Keys, browse bounded remote
+  directories, and create Ask or Execute projects. Both modes start the
+  signed Runtime directly without bubblewrap. Ask applies OpenCode's Ask
+  permission configuration and permits only native read approvals at the
+  Agent tool-dispatch boundary, while Execute explicitly allows native permissions
+  and retains all permissions of the selected SSH account. The Agent owns accepted Prompts,
+  provider/tool rounds, Runtime processes, a stable model ledger, and a bounded
+  semantic transcript over a private Unix socket and ACP v5. Work continues on
+  the Host after Desktop exit, network loss, or local-process termination.
+  Reconnection attaches only to the original controller, binding, and
+  operation, then atomically merges provenance into the original conversation
+  without resending the Prompt. Model profiles and API keys enter Agent memory
+  only for the accepted operation and are not written to the Renderer, SSH
+  arguments, remote environment, or disk. Remote components are not embedded
+  in the desktop package; switching projects updates only local selection and
+  does not connect or download. Settings reads a small signed catalog and
+  reports the local version, latest compatible online version, and update
+  state for Linux x64, Linux arm64, and macOS arm64. Intel Macs are not supported.
+  Downloads occur only after a user action, and
+  packages can also be imported or exported offline. Each compound `.gbagent`
+  package contains the Agent, fixed Node, and the compatible OpenCode Runtime
+  maintained by the desktop source. Online sources follow the GitHub/Beijing
+  OSS choice in About and Updates. The cumulative signed catalog binds minimum
+  Desktop version, Agent protocol, platform, architecture, size, SHA-256, and fixed URL.
+  All three targets share one catalog. Users must upgrade Desktop before the
+  first mixed-platform catalog is published because older Linux-only readers
+  reject catalogs containing Darwin entries.
+  The public-key registry accepts equivalent JSON whitespace and line endings
+  while still strictly validating schema, Ed25519 keys, environment, and
+  revocation; catalog, package, manifest, payload signatures, and streaming
+  SHA-256 remain unchanged. A missing architecture package disables managed
+  SSH only for that architecture. Projects store only Host, remote path,
+  Runtime selection, and mode. Current Host identity is read when a
+  Workspace/Runtime is first used, then reused by other projects in the same
+  process. Managed SSH conversations expose only supported OpenCode choices.
+  Multiple projects and conversations can run concurrently on one Host;
+  Agent-owned prompts are not stopped at a fixed model-call count or
+  prompt-wide output-token total, and Runtime output uses transport
+  backpressure instead of cancellation when GoodBuddy buffers fill;
+  recovery separately reports network, Agent, Runtime, committed-event cursor,
+  completion, or failure/retry and blocks only the affected project. A real
+  Linux x64 Host has covered short and long detach, forced local harness exit,
+  concurrency, SSH relay loss, cancellation, definite and uncertain provider
+  failure, Agent `SIGKILL`/restart, and recovery from a reopened Desktop SQLite
+  database. Successful tool START/END events appear exactly once, with no
+  Prompt, provider, or tool replay observed. The current Agent source lock is
+  `0.13.0`, while the current Desktop release candidate is `0.13.5`; formal
+  publication status follows the separate Agent and Desktop
+  release channels. Previous macOS validation covered native package installation,
+  detached lifecycle, Attach, real Ask/Execute, and cancellation of tools in
+  separate process groups on a real Host; this does not imply publication.
+  Agent `0.11.23` adds remote workspace management and optional model limits;
+  its bundled Runtime no longer imposes a fixed ten-minute Prompt deadline.
+  Unlimited request duration retains a separate connection timeout. Agent
+  `0.11.23` requires Desktop `0.12.11` or later.
+  Agent `0.11.24` requires Desktop `0.13.0` and fixes native question routing
+  and sending another message after cancelling a pending question.
+- [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).
+- **SSH Host environment provisioning validation records**: The
+  current source passed isolated Linux x64 package installation, Ask/Execute,
+  native subagent external writes, reconnection, and stop/bootstrap.
+  The complete Host-card acquisition matrix across GitHub, Beijing mirror,
+  Linux x64/arm64, cancellation, and offline GoodBuddy transfer remains.
+  Candidate CI/native packaging and system sleep/wake are not yet verified;
+  this partial development evidence does not imply publication.
+- [x] **DeepSeek Harness (preview)**: Uses the fixed GoodBuddy Host and an
+  OpenAI-compatible model connection. It prefers an administrator-provided
+  connection, otherwise follows the compatible default model or first
+  compatible connection without requiring a duplicate selection. Settings
+  displays the actual administrator or fallback model source. Ask permits
+  only real Host-registered `read` and `skill` tools plus Main-managed Web
+  Search/Fetch proxies, and rejects plugin impersonation of those names.
+  Execute allows all enabled built-in and plugin tools with the current user's
+  permissions. Image input follows the selected model connection's declared
+  capability: text models reject images before Host or model invocation, while
+  image-capable models receive bounded inline JPEG/PNG content through a
+  temporary Attachment Store. On Windows, Host startup and ACP sessions share
+  one canonical workspace path, so equivalent path spellings reuse the same
+  working Runtime instead of failing session creation.
+- [x] **DSH npm plugin marketplace**: Disabled by default and searches public
+  npm `dsh-plugin` packages only after explicit user enablement. It uses the
+  bundled npm to install exact versions with ordinary lifecycle scripts and
+  supports enable/disable, JSON configuration, removal, automatic disablement
+  after startup failure, and offline management of installed plugins.
+  Disabling the marketplace hides only the catalog and management interface;
+  it does not change the enabled state of installed plugins, and third-party
+  code is not subject to Ask initialization isolation.
+- [x] **Ask and Execute work modes**: Ask remains read-only. Execute is the
+  user's authorization for all tools, processes, network access, and writable
+  paths available to the current local or SSH account, including paths outside
+  the workspace and native subagent work.
+- [x] **Efficient direct-model workspace tools**: Direct models use bundled
+  ripgrep for compact file discovery and content search, read large UTF-8 files
+  by line, and apply multi-file patches in Execute. Ask can search and read but
+  cannot patch or run commands; packaged ripgrep does not require a system install.
+  Actionable read/search errors let the model correct its arguments and
+  continue. Partial search results remain available with an explicit
+  incomplete-coverage warning.
+- [x] **Long context and paged tool output**: Message history, long replies,
+  and parsed document text no longer use the previous fixed truncation limits.
+  Direct models can continue reading stored command and Subagent output in
+  pages; the selected model's context window and bounded transports still apply.
+- [x] **Native Runtime interaction routing**: OpenCode and Continue questions
+  support choices, yes/no, free-text answers, and skipping through the existing
+  question card. Local and managed SSH OpenCode also route questions from
+  owned child sessions. Managed SSH requires Desktop `0.13.0`, Agent `0.11.24`,
+  and a newly started managed Runtime;
+  this does not extend question support to arbitrary ACP services.
+  Successful answers and skips retain the original questions and answers
+  across rounds and local conversation reloads; answers discarded by older
+  versions cannot be recovered.
+  Concurrent questions wait in order, duplicate events preserve drafts, and
+  failed submissions remain retryable. Cancelling a pending managed SSH
+  question allows another message in the same conversation.
+  Execute permission confirmations are handled automatically rather than
+  waiting for another approval. See the [interaction boundaries](./docs/features/assistant-workbar/runtime-interactions.md).
+- [x] **Experts and Subagents**: Supports explicit experts, team analysis, and
+  up to three experts running in parallel. Experts inherit the parent
+  Ask/Execute mode and can use enabled local direct-model tools; Ask remains
+  read-only. They are not remote OpenCode child sessions. Chat shows each
+  expandable full expert response first and the main Agent's synthesis below,
+  and persists both with the conversation.
+- [x] **OpenCode child progress and final results**: Child cards show ordered
+  text, reasoning, and tool progress separately from the final result. Remote
+  live progress requires Agent `0.11.20`; older packages still expose final
+  results without reconstructing missing progress.
+- [x] **OpenCode event-stream cleanup**: Chat requests and native context
+  compaction close their own subscriptions before ending event iteration,
+  including completion, failure, cancellation, and early consumer exit,
+  without cancelling parallel conversations.
+- [x] **Accurate message-footer status**: Distinguishes request preparation,
+  retry waiting, retry dispatch, tool activity, pending answers, and terminal
+  states. Local OpenCode reports native retry attempts and scheduled times;
+  direct models report their own backoff phase. Footer dots are static, and
+  unsupported Runtime retry details are not invented. Conversation-list
+  indicators and send/stop behavior remain unchanged.
+- [x] **Simplified Runtime selection**: Conversation and project menus no
+  longer enumerate every Runtime/model combination. Configure Runtime models
+  in system settings; saved fixed project selections remain usable and
+  explicitly display their fixed model.
+- [x] **Role-bound model connections**: Each role can inherit the default model
+  or select an independent text-model connection. Invalid connections safely
+  fall back to the default; the synthesis role always inherits the default.
+- [x] **Multiple model protocols**: Supports Anthropic Messages, OpenAI
+  Responses, OpenAI Chat Completions, OpenAI Images, and unauthenticated local
+  models. New users receive a local Ollama-compatible default and no
+  preconfigured third-party cloud provider. During upgrades, GoodBuddy
+  replaces a historical default only when it has never received credentials
+  and still exactly matches the old built-in value; explicitly saved
+  connections and encrypted credentials remain unchanged. Existing
+  deployments that supply credentials only through compatible environment
+  variables retain their historical connection parameters, while generic
+  model environment variables still take precedence. Save and Test Model sends
+  a bounded real text or image-generation request and validates the generated
+  result instead of testing HTTP reachability alone, so it may incur a small
+  provider usage charge.
+- [x] **Custom model request fields**: Each LLM connection accepts bounded
+  JSON objects for additional request headers and top-level body fields.
+  Direct requests and Continue support both; local OpenCode and DeepSeek
+  Harness use only their natively supported headers, while the managed SSH
+  OpenCode model gateway supports both. Runtime, protocol, and authentication
+  fields take precedence, and these ordinary connection settings must not be
+  used to store API keys or other secrets. See
+  [model request customization](./docs/features/model-connections/README.md).
+- [x] **Context usage and automatic compaction**: Direct models update usage
+  from each successful provider call. Images and tool rounds use the same
+  accounting, with estimation only when the provider omits usage. The UI
+  distinguishes This Model Call from Post-Compaction Conversation Estimate,
+  and the compaction line is recalculated from current settings and the
+  selected model window rather than storing old configuration per
+  conversation. Before/after compaction markers use one estimation method,
+  while activity history retains provider usage for each call. Conversations
+  and multi-round tool Agents can compact repeatedly after a completed call
+  crosses the threshold, reserving budget first for fixed prompts, tool
+  definitions, and summaries. One response separately preserves compaction
+  markers for Agent tool context and conversation history, and summaries remain
+  reusable after app restart or when older messages leave the local history
+  window.
+- [x] **Persistent credential protection**: Main encrypts API keys with secure
+  system storage and never exposes them to the Renderer. A managed SSH accepted
+  Prompt places the current profile and key in Agent memory only, never in SSH
+  arguments, the remote environment, or disk; other paths keep credentials
+  inside Main. Credentials remain attached to their model connection when the
+  service URL changes or authentication is temporarily disabled, and are
+  removed only when the user explicitly clears them or deletes the connection.
+- [x] **Bounded failure diagnostics**: Desktop stores a fixed allowlist of
+  startup, Runtime, and remote-connection failure stages in the user-data
+  directory, rotating at four 256 KiB files. Each GoodBuddy Agent rotates
+  daemon, connection, recovery, and Runtime lifecycle diagnostics at three
+  64 KiB files in its private installation state and exposes them through the
+  fixed `diagnostics --installation-id` command. Both sides store only
+  allowlisted stages, stable error codes/types, and fixed short messages, never
+  Prompts, credentials, file contents, paths, environments, SSH arguments, or
+  raw provider responses. Diagnostic-write failure does not alter normal
+  operation.
+- [x] **OpenCode Runtime customization**: GoodBuddy-managed OpenCode can
+  discover native Agents, Tools, Commands, LSPs, Formatters, MCP, Skills,
+  Prompts, and Resources. Tools show read, file-edit, command, network, Agent
+  orchestration, and other types, source, and Ask/Execute availability while
+  hiding OpenCode's internal `invalid` tool and temporary GoodBuddy MCP tools.
+  Users can save a default Agent, override it per request, run Commands through
+  the native SDK, view context usage, and invoke native Compact with a total
+  timeout. Questions from concurrent external Server conversations are mapped
+  by public request ID so answers cannot cross conversations. External
+  OpenCode Servers report connection state only and do not claim native
+  catalog access. Arbitrary plugin installation, Session Share, automatic
+  Worktree, and OpenCode native-session persistence remain unavailable.
+- [x] **Continue Runtime customization**: Exposes native Rules, prompt
+  templates, and MCP from static configuration plus editable GoodBuddy Rules
+  and Prompt presets. Chat can select a preset per request and insert an
+  editable Prompt. The current Continue Host has no trustworthy static native
+  Tool discovery API and runs with an isolated `CONTINUE_GLOBAL_DIR`, so the UI
+  explicitly marks static Tool discovery unsupported and does not present
+  workspace or user Skills that the Host will not load as native capabilities.
+  GoodBuddy-assigned Skills still execute through per-request staging. The
+  temporary Continue Host does not reuse native session compaction; manual
+  compaction uses the GoodBuddy summary model and verifies persisted summary
+  coverage. Agent questions become unified question cards. Resources, Hooks,
+  background Jobs, and Continue native-session management remain deferred.
+- [x] **Native Runtime catalog semantics**: Native capabilities are displayed
+  across 11 tabs: Agents, Tools, Commands, Skills, MCP, Rules, Prompts,
+  Resources, LSP, Formatters, and Context. Catalog state is independent from
+  Runtime connectivity and distinguishes complete, partial, unavailable,
+  connection-only, and unsupported. DeepSeek Harness enumerates bounded
+  built-in/plugin Tools and Skills through the Host Registry, reports real
+  Ask/Execute boundaries, and excludes per-request GoodBuddy Skills and
+  Web/MCP proxies.
+- [ ] **Runtime supervision section** (planned): A fixed section in the
+  application-level assistant workbar for Task-level delegation, background
+  execution, Workflows/Hooks, long-running work, and native-session
+  supervision across OpenCode, Continue, and DeepSeek Harness. Users select
+  only Conversation or Task; Job/Run remains internal rather than becoming a
+  tree or independent object.
+- [ ] **Advanced Subagent supervision** (planned): Task-level aggregation in
+  the workbar's fixed Runtime section, configurable nesting, parallelism,
+  budgets, and lifecycle controls. Basic expert-mode inheritance and
+  single-level direct-model programming delegation are already available.

- [x] **任务、活动与成果**：集中管理任务状态、审计活动和独立成果文件；普通聊天回复只保留在会话中，不再自动复制到成果栏，已有重复聊天 Markdown 从成果列表隐藏但不物理删除。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/prd/task-and-job/task-center-prd.md) 和 [Scheduled Task PRD](./docs/prd/task-and-job/scheduled-task-prd.md)。
- [x] **记忆与智能心跳**：当前提供周期回顾、建议记忆、洞察、后续任务和可审计运行轨迹。
- [x] **智能心跳入口与范围改善**：将“智能心跳 > 心跳计划”作为完整配置的唯一权威入口，支持创建和编辑 Global 或指定一个、多个 Project 的计划；旧单项目配置无损迁移，项目级记忆与行动输出必须显式指定范围内的 Project。Task Center 和设置不再复制心跳表单。“未来分区记忆”仍只是尚待独立设计的长期方向。详见 [智能心跳 PRD](./docs/prd/smart-heartbeat/smart-heartbeat-prd.md)。
- [ ] **通用监督**（规划中）：通过固定监督栏目观察用户选择的会话、任务、自动化或实验对象，提供带证据的评论与人工介入请求，但不自动发言、批准工具或切换 Execute。详见 [会话监督 PRD](./docs/prd/supervision/conversation-supervision-prd.md)。
- [ ] **批量运行与对比实验室**（规划中）：对模型、Prompt、角色和工作流配置执行批量对比，汇总质量、耗时、Token、费用、失败率和成果差异。
- [ ] **时态记忆与事实冲突检测**（规划中）：为记忆和知识图谱增加有效期、当前事实、过期与矛盾检测、事实核验及证据回溯。
- [ ] **可视化受控工作流**（规划中）：提供版本化 DAG、条件分支、审批、取消和恢复，执行节点继续经过 Main Runtime 边界。
- [ ] **统一 Run Graph 与回放**（规划中）：关联任务、Subagent、模型、知识、工具审批、用量和成果，支持失败定位、重试和脱敏导出。
+### 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 validation records**: All six
+  platform/architecture OSS mirror objects have passed public byte, size, and
+  SHA-256 verification. Managed Python remains an on-demand download and does
+  not add license files to the Desktop package. Each standard package job uses
+  a native target-architecture Runner and performs a real managed-Python
+  install, SSL, pip, and venv probe before packaging. The immutable `v0.12.0`
+  attempt passed Windows and macOS but exposed Linux TAR case handling before
+  publication. The immutable `v0.12.1` attempt was cancelled before native
+  packaging while synchronizing the Agent release. Published `v0.12.2`
+  subsequently passed all six native package jobs and their managed-Python
+  install probes. Real Skill/MCP execution, custom interpreter execution, and
+  coordination with affected running processes remain
+  acceptance work. Six-platform release acceptance must not be claimed before
+  the applicable checks pass.
+- [x] **On-demand built-in MCP**: Knowledge, Magic Notes, GoodBuddy
+  configuration, and built-in browser MCP can be enabled independently and assigned to direct
+  models, GoodBuddy-managed OpenCode, and Continue. Settings explicitly marks
+  DeepSeek Harness unsupported. Built-in MCP uses short-lived local authority
+  for the current request, and user configuration cannot loosen Ask/Execute
+  read/write boundaries.
+- [x] **MCP Tools**: Explicitly enabled custom MCP can be assigned to direct
+  models, GoodBuddy-managed OpenCode, Continue Agent Execute, and DeepSeek
+  Harness, and loads only in Execute. Agent child processes receive only
+  per-request local-loopback authority; MCP addresses, commands, and
+  credentials remain in Main. Dynamic tools pass through discovery and the
+  existing activity and permission boundaries; healthy direct-model
+  and Harness calls reuse the discovered request catalog instead of
+  rediscovering it before every call.
+- [x] **MCP Prompts and Resource metadata**: MCP testing discovers bounded
+  Prompt, parameter, and Resource metadata only when the Server declares the
+  corresponding capability and does not read Resource content. Supported
+  Prompts can be inserted into the chat draft for further editing. OpenCode can
+  report an experimental Resource catalog; the current Continue version
+  explicitly does not support Resources.
+- [x] **Local knowledge bases**: Supports file, directory, and web imports,
+  SQLite FTS5 retrieval, and source tracing. Knowledge selection persists per
+  conversation and starts empty for new conversations. Advanced creation and
+  retrieval parameters are collapsed by default. Documents distinguish ready,
+  processing, and failed states, with source opening, retry, and confirmation
+  before source removal.
+- [x] **External knowledge-base connections**: Manage Dify, FastGPT,
+  and RAGFlow instances from the Knowledge page, then discover remote
+  knowledge bases or enter their IDs and verify bindings with provider-specific
+  retrieval settings and citations. Conversations support on-demand and
+  required pre-answer retrieval. 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).
+- **External knowledge-base validation records**: All three providers have passed
+  real service, local HTTP MCP, and production-IPC short-answer checks; Dify
+  additionally passed the complete App composer-to-answer-and-citation path.
+  FastGPT/RAGFlow desktop-specific parameters, complex multi-library answers,
+  and remote pre-answer retrieval remain unverified. See the
+  [validation evidence and remaining work](./docs/features/knowledge-base/progress.md).
+- [x] **Knowledge graph**: Supports rule-based, model-based, and hybrid
+  extraction plus entity, relationship, alias, and evidence maintenance.
+- [x] **Embedding configuration and retrieval**: Configures compatible
+  Embeddings endpoints and uses them for semantic retrieval.
+- [x] **Embedding diagnostics and indexing jobs**: Provides real embedding
+  diagnostics, per-document rebuild progress, cancellation, failure state, and
+  result recovery after restart. Each successful document becomes immediately
+  searchable.
+- [x] **Hybrid retrieval workbench**: Diagnoses full-text, Chinese phrase,
+  vector, and graph channels with configurable Top K, thresholds, weights,
+  local or learned reranking, and context budgets.
+- [x] **Chunking, maintenance, and evaluation**: Supports fixed, structured,
+  and parent-child chunking, chunk maintenance, cancellable rebuilds, and
+  bilingual retrieval evaluation.
+- [x] **Controlled knowledge ontology**: Each knowledge base can define
+  entities, relationships, aliases, and endpoint constraints while retaining
+  evidence offsets, confidence, and extraction source, with explicit guidance
+  to rebuild the graph.
+- [x] **Required retrieval and cited context**: Conversations can retrieve on
+  demand or before every response, show zero-result, degraded, failed, and
+  cancelled states, and expose cited context or safely open its source.
+- [x] **Magic Notes**: A local-first notes and todo workbench with scope
+  management, editing, filtering, and controlled AI comments. The todo view
+  displays the source entry inside the selected item's details, without
+  showing the previous item's source after a selection change. Failed reads
+  use application notifications, and missing sources have an explicit fallback. The left
+  navigation can show the incomplete-todo count, and create, save, and comment
+  results use application-wide notifications. Agent/MCP note writes automatically
+  refresh the open workbench while preserving selection and unsaved drafts.
+- [ ] **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] **直连模型内置浏览器**：使用 GoodBuddy 内置的隔离 Chromium，不控制客户端已安装的浏览器；用户通过独立总开关决定是否提供给 Execute，开启后不逐次询问。
- [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] **应用内反馈**：在“关于与更新”中直接提交问题、建议或体验反馈，支持可选邮箱和单张截图；失败后保留草稿并按同一请求编号重试，不自动附加对话、日志、文件、配置或凭据。
- [x] **内网兼容模式**：默认开启；允许应用内 HTTP 与无效、自签名或过期的 HTTPS 证书，关闭后恢复严格地址和证书校验。
+### Work management, long-term collaboration, and workflows

-### 开源、构建与发布
+- [x] **Tasks, activity, and artifacts**: Centrally manages task state, audit
+  activity, and independent artifact files. Ordinary chat responses remain
+  only in the conversation and are no longer copied into Artifacts; existing
+  duplicate chat Markdown is hidden from the artifact list but not physically
+  deleted. Run history is stored in Main SQLite without the previous 500-item,
+  4,000-character, or 2 MB Renderer limits; the page renders it in batches,
+  without a persistent legacy-cache truncation warning; previously lost
+  history is not restored. Token usage is grouped by Runtime and
+  model and normalizes the different OpenAI-compatible and Anthropic Messages
+  cache-reporting semantics when showing cache hit rate. Activity is grouped
+  by conversation and collapsed by default so long histories do not fill the
+  page.
+- [x] **Compact conversation tool records**: Expand individual tool records
+  to read or copy results, errors, and input parameters. Conversation and
+  child-task progress use concise rows without repeated Runtime summaries.
+  OpenCode, Continue, DeepSeek Harness, and direct models show available file
+  paths, commands, or search summaries and retain them through completion and
+  conversation reloads.
+- [x] **Task and custom-task experience**: Each product-level Task belongs to
+  one Conversation, while one Conversation can contain multiple Tasks. The
+  left conversation list exposes Task children through a leading expand
+  button; children share status dots, the parent does not repeat task badges,
+  and the UI stops at Task rather than exposing Job/Run levels. A new custom
+  Task can use the current or a new Conversation, defaults to Execute, and
+  preserves Runtime, tool, and approval boundaries. Repeated triggers reuse the
+  same Task; text returns to the Conversation, while independent files and
+  images remain artifacts. Ordinary messages and due Scheduled Tasks share a
+  persistent Conversation queue that runs one item at a time. Users can keep
+  sending while a response is active; queued items continue in order and can
+  be removed or inserted immediately by interrupting the current item. Task
+  Center remains the complete index rather than creating a separate Automation
+  Center. Current schedules support one-time, daily, and weekly triggers;
+  advanced time zones, Cron, event triggers, and retry governance remain
+  incremental PRD work. Scheduled messages use the conversation's current
+  history, Runtime, work mode, and saved knowledge retrieval settings; task
+  details show the actual mode used, and an active occurrence blocks duplicate
+  Run Now actions. See the
+  [Task Center PRD](./docs/features/task-and-job/task-center-prd.md) and
+  [Scheduled Task PRD](./docs/features/task-and-job/scheduled-task-prd.md).
+- [x] **Memory and Smart Heartbeat**: Provides periodic review, suggested
+  memories, insights, follow-up tasks, and auditable run history.
+- [x] **Improved Smart Heartbeat entry and scope**: Smart Heartbeat / Heartbeat
+  Plans is the sole authoritative full-configuration entry. Plans can be
+  created and edited for Global or one or more selected Projects. Legacy
+  single-project settings migrate without loss, and project-level memory and
+  action output must explicitly target a Project in scope. Task Center and
+  Settings no longer duplicate the form. Partition-aware review, candidate
+  generation, and recall triggers remain to be designed. See the
+  [Smart Heartbeat PRD](./docs/features/smart-heartbeat/prd.md).
+- [ ] **General supervision** (planned): Uses a fixed supervision section to
+  observe user-selected conversations, Tasks, automations, or experiments and
+  provide evidence-backed comments and requests for human intervention,
+  without automatically speaking, approving tools, or switching to Execute.
+  See the
+  [Conversation Supervision PRD](./docs/features/conversation-supervision/prd.md).
+- [ ] **Batch runs and comparison lab** (planned): Compares model, Prompt,
+  role, and workflow configurations in batches and summarizes quality,
+  duration, tokens, cost, failure rate, and artifact differences.
+- [ ] **Temporal memory and fact-conflict detection** (planned): Adds validity
+  periods, current/expired/conflicting fact detection, fact checking, and
+  evidence tracing to memory and the knowledge graph.
+- [ ] **Visual controlled workflows** (planned): Versioned DAGs, conditional
+  branches, approvals, cancellation, and recovery, with execution still
+  passing through Main Runtime boundaries.
+- [ ] **Unified Run Graph and replay** (planned): Connects Tasks, Subagents,
+  models, knowledge, tool approvals, usage, and artifacts for failure
+  diagnosis, retry, and redacted export.

- [x] **0BSD 开源许可**：原创代码可自由使用、复制、修改、分发和商用；第三方组件和资源仍遵循各自许可证。
- [x] **可复现依赖安装与源码构建**：使用锁定依赖、Node.js 24 和统一的测试、类型检查、Lint、生产构建命令。
- [x] **六平台原生发布矩阵**：Windows、macOS、Linux 的 `x64`、`arm64` 目标由原生 Runner 构建，并提供发布清单和 SHA-256 哈希；Linux 同时生成 AppImage、DEB 和 RPM。
+### Browser, communication, voice, and application maintenance

-### 开放接口、团队协作与远程执行
+- [x] **Shared built-in browser for runtimes**: Uses GoodBuddy's isolated
+  Chromium and never controls a browser installed by the user. A separate
+  master switch decides whether assigned runtimes receive the capability in
+  Execute, with no per-use prompt after enablement. Turning Agent access off
+  does not disable manual browser workbar actions. The Browser workbar and
+  Agent share the same Conversation-owned session and serialized operation
+  path, with Back, Refresh/Stop Loading, address entry, Go, Interaction, and
+  Close actions. Stop Loading does not close the session, and user navigation
+  changes the page the Agent sees next.
+  Multiple tabs in one conversation share login state while keeping separate
+  pages and navigation. Each model request retains its starting tab binding;
+  unused request reservations do not create browser resources. Released tabs
+  can be reopened, explicit screenshots remain available, and ordinary
+  operations no longer trigger unused automatic screenshot capture.
+  Tabs can be closed while an AI request uses them without cancelling the
+  whole request. A later explicit navigation creates a separate replacement
+  tab; blank pages cannot reload, and switching or closing panels clears stale
+  action errors.
+- [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] **Window recovery controls**: Rendering errors show a localized Reload
+  action and renderer crashes offer a native recovery confirmation. Reload may
+  lose unsaved input. See [window recovery](./docs/development/window-recovery.md).
+- [x] **In-app feedback**: About and Updates can submit problems, suggestions,
+  or experience feedback with an optional email and one screenshot.
+  Diagnostics are not uploaded by default; users can explicitly attach a
+  bounded recent Desktop diagnostic summary. Failed submission preserves the
+  draft, diagnostic choice, and request ID. Conversations, Prompts,
+  credentials, file contents, paths, raw provider responses, and remote Agent
+  logs are never attached.
+- [x] **Private-network compatibility**: Permits in-app HTTP plus invalid,
+  self-signed, or expired HTTPS certificates. Fixed platform services such as
+  feedback and WeChat credential or media endpoints retain strict certificate
+  validation.

- [x] **远程任务委派**：仅在用户显式配置端点和令牌后启用，按全局内网兼容模式使用 HTTP(S)，结果进入持久化发件箱。
- [ ] **Headless Runtime API**（规划中）：提供本机优先的任务、事件、状态和成果 API，以及有范围、有效期、限流和撤销能力的令牌。
- [ ] **GoodBuddy Team Hub**（规划中）：以可选服务提供组织、RBAC、项目共享、远程 Agent、策略下发和租户审计。
- [ ] **SSH 主机与远程执行空间发布验收**：主机 CRUD、Host Key、加密凭据、Project UI、Workspace、OpenCode ACP、Main-only 模型桥、Ask 只读、Execute 完整账号权限、取消、detached Agent 重连和 release-only 双架构资源校验已经接线。Windows 到 Linux x64 的真实 Host provider-free 安装、metadata-only Portable 复用与项目保存、桥接、断线恢复、输出重放、同 Session 续接与清理已经通过；Agent 0.11.2-e2e.12 与 OpenCode Runtime 1.18.9 的真实模型 Ask 验收也已通过，单次用户操作只执行一个原生 read，两个 build 模型轮次均完成交付，没有 title 轮次或请求重放。公开 signing key registry 已供应。剩余门槛是生成并导入 Linux x64/arm64 当前发布版本的正式签名工件完整矩阵。门槛未满足时不提供未验证 SSH fallback。
- [ ] **多云远程沙盒 Agent**（规划中）：通过云厂商 API 和 SSH Agent 管理专用 Linux 沙盒；凭据留在 Main 进程，高风险控制面操作单独确认。
+### Open source, builds, and releases

-## 规划原则
+- Current source candidates are Desktop `0.13.5` and Agent `0.13.0`, with
+  OpenCode pinned to `1.18.29`. Publication status follows the independent
+  Desktop and Agent release channels.
+- Agent `0.13.0` adds remote image-tool integration and shared Runtime processes
+  with conversation recovery fixes. Its packages require Desktop `0.13.5`;
+  update Desktop first, then the Host environment. Node remains `24.19.0`.
+- Validation records remain separate from implementation status. Current-source
+  storage validation covers real local and Linux x64 Host tool workloads,
+  concurrent projects/conversations, cancellation, and lossless database migration.
+  Runtime process reuse has real Windows full-App and Linux x64 Host evidence;
+  PPTX OCR and idle-memory release have real Windows file evidence. Image tools
+  have real provider generation/editing and Host transport evidence. Full
+  UI-driven natural-language invocation and local/remote switching are not
+  covered by those records. The candidate still requires main CI and
+  native release packaging. See the [Runtime evidence](./docs/features/assistant-workbar/progress.md)
+  and [image-tool evidence](./docs/features/conversation-media-generation/progress.md).
+- Candidate checks on 2026-09-15 passed: bilingual release notes, `npm test`
+  (4,293 passed, 67 skipped), `npm run typecheck`, and `npm run lint`.
+  This metadata/documentation preparation made no new real model calls and did
+  not rerun Host scenarios or build local production packages.
+- [x] **0BSD open-source license**: Original code can be freely used, copied,
+  modified, distributed, and commercialized. Third-party components and
+  resources retain their own licenses.
+- [x] **Reproducible dependency installation and source builds**: Uses locked
+  dependencies, Node.js 24, and unified test, type-check, lint, and production
+  build commands.
+- [x] **Six-target native release matrix**: Native runners build Windows,
+  macOS, and Linux `x64` and `arm64` targets with release manifests and SHA-256
+  hashes. Windows provides NSIS and portable ZIP, macOS DMG only, and Linux
+  AppImage, DEB, and RPM, for 12 installers and 20 published assets.
+- [x] **Desktop Runtime package verification**: Offline OpenCode dependencies
+  are copied without electron-builder's root node_modules exclusion; DSH
+  session projection is bundled into the unpacked Host. Final package checks
+  compare the offline dependency tree and reject external DeepSeek imports.
+  Windows x64 CI additionally imports the packaged OpenCode plugin and checks
+  the real DSH UtilityProcess handshake before publishing.
+- [x] **DMG-only update manifests**: Current Desktop and website readers accept
+  DMG-only and historical DMG/ZIP manifests. Older macOS GitHub readers and all
+  older mirror readers require a manual upgrade from the download page.

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

-GoodBuddy是一个开箱即用的 AI 生产平台，安全、跨平台、本地优先的桌面 AI 助手与 Agent 工作空间。
+**English** | [简体中文](./README.zh-CN.md)

-产品官网：https://mesalogo.github.io/goodbuddy/
+[Website](https://mesalogo.github.io/goodbuddy/en.html) ·
+[Download](https://github.com/mesalogo/goodbuddy/releases) ·
+[Feature Matrix](./FEATURES.md) ·
+[Build Guide](./BUILD.md)

-五大特点：
-1. 支持国产信创系统和硬件
-2. 免注册，不收集个人信息
-3. 完全开源和免费，友好的OBSD协议
-4. 不需要联网，纯私有网络也可以用
-5. 开放生态，内置主流好用的Agent Runtime，目前支持OpenCode、Continue和DeepSeek Harness，让小白用户也可以快速用起来最前沿的Agent工具
+[![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 workspace](./docs/screenshots/workspace-overview.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.

- **安全执行**：`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、企业微信和钉钉，每个发送者使用独立远程会话。
- **托管 SSH 项目（技术预览）**：远程能力默认关闭且不影响普通桌面使用。启用后，在“设置 > 平台功能 > 远程项目”按 Linux Host 架构手动下载独立签名的 Agent 包，或导入/导出 `.gbagent` 离线包；每个包包含 Agent、固定 Node 和 GoodBuddy 适配的远端 OpenCode Runtime，在线来源跟随“关于与更新”的 GitHub/镜像选择。
- **桌面上下文**：可选择文件、截图、应用窗口、剪贴板和语音作为上下文。
- **离线语音**：支持 SenseVoice、Paraformer 和 Whisper 本地模型。
- **富文本回答**：支持 Markdown、LaTeX 公式和受控 Mermaid 图表。
+## Highlights

-![GoodBuddy 知识工作区](docs/screenshots/knowledge-workspace.png)
+- **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/knowledge-graph.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.

-![GoodBuddy 魔法笔记](docs/screenshots/GoodBuddy_MFSGeK0NoT.gif)
+## Capabilities

-![GoodBuddy 智能心跳](docs/screenshots/smart-heartbeat.png)
+| 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 |

-完整功能和路线图见 [FEATURES.md](FEATURES.md)，产品、架构、设计与质量文档见
-[文档导航](docs/README.md)。
+## Product tour

-## 安装
+### Knowledge bases and graphs

-从 [GitHub Releases](https://github.com/mesalogo/goodbuddy/releases) 下载：
+![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、RPM |
+| 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 |

-桌面安装包不包含远端 Agent payload。仅使用本地项目时无需下载任何
-Agent 包；托管 SSH 用户可在设置中按需管理。
+Each run reports cancellation, timeouts, token usage, tool calls, and history.
+Runtime-specific capabilities and configuration remain separate.

-当前尚未配置代码签名和 macOS notarization，系统可能显示安全提示。
+## Download

-## 从源码运行
+Download a build from
+[GitHub Releases](https://github.com/mesalogo/goodbuddy/releases):

-需要 Node.js 24 和 npm：
+| 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
@@ -66,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
@@ -87,18 +152,17 @@ npm run typecheck
 npm run lint
 ```

-## 为什么选择GoodBuddy
+## Community communication

-<img width="1024" height="1536" alt="6dd45371542dea9fb2d99474387708f5" src="https://github.com/user-attachments/assets/ca608646-ea48-4039-9177-d862be8396ac" />
+Scan the QR code to join the GoodBuddy WeChat group:
+
+<img width="1250" height="1743" alt="46b5c3b5936388b0a55db6fe034a7d7f" src="https://github.com/user-attachments/assets/45cd1736-f1ae-4f99-85be-cdb2cc1160c0" />


-## 社区交流
-
-目前采用微信群的方式供大家高效交流，大家可以微信扫码进入社区群：
-
-<img width="993" height="1335" alt="image" src="https://github.com/user-attachments/assets/4893715a-edaf-4db6-8a6d-d529b972db8e" />


-## 开源许可
+## 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.
@@ -0,0 +1,137 @@
+<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="1743" alt="46b5c3b5936388b0a55db6fe034a7d7f" src="https://github.com/user-attachments/assets/cc094468-2885-447a-afb4-91c7ac117fd3" />
+
+
+
+## 开源许可
+
+GoodBuddy 原创代码采用 [0BSD License](./LICENSE)，可自由使用、修改、分发和商用。第三方组件和资源遵循各自许可证。
@@ -193,7 +193,7 @@

 ### 6.1 PageTabs

-用于同一一级页面内的同级内容面板，例如智能心跳的“成长概览”和“心跳计划”。
+用于同一一级页面内的同级内容面板，例如智能心跳的“运行概览”和“心跳计划”。

 - 使用 `tablist`、`tab` 和 `tabpanel` 语义，当前项使用 `aria-selected="true"`。
 - 一级页面之间的导航由应用主导航承担，不复用 `PageTabs`。
@@ -201,6 +201,7 @@
 - 项目过多时优先重组信息架构，不把一级页签做成多行。
 - `PageTabs` 可使用默认视觉或共享的 `segmented` 视觉变体。紧凑主从工作台中的 2 至 4 个同级面板可使用与模型设置一致的分段外观，但不得因此改用按钮组语义。
 - 视觉变体不改变组件含义：分段外观的 `PageTabs` 仍使用页签语义、单一激活面板、游标焦点和方向键切换，不复制页面专属样式。
+- 在独立滚动的 Flex 页面中，`PageTabs` 及其直接包装层必须保持 `flex: 0 0 auto`，不得被剩余内容压缩到零高度。新增页签容器时必须提供对应的 CSS 回归测试。

 ### 6.2 SegmentedControl

@@ -209,6 +210,8 @@
 - 选项数量为 2 至 4 个。
 - 使用带 `aria-pressed` 的按钮组语义，支持方向键切换。
 - 不能用于多选筛选、页面导航或执行即时命令。
+- 与 `PageTabs` 一样，共享控件根节点必须 `flex: 0 0 auto`，不能被同级长表单或滚动区域
+  压缩高度。横向空间不足时保留控件自身滚动，不把标签裁成一条窄缝。
 - 控件宽度由内容决定，除移动窄屏外不默认等分整行。

 ### 6.3 筛选工具栏
@@ -282,6 +285,12 @@
 - 一级导航与最近会话之间、最近会话与底部账户区之间必须有可见结构分隔线。浅色主题使用 `--border-default`，深色主题可在可辨前提下使用 `--border-subtle`。
 - 当前导航项和当前会话必须同时使用至少三种信号中的两种：强调背景、可见边框、图标或文字强调。浅色主题的当前项优先使用更完整的蓝色选中表面和较高字重。
 - 未选中项保持平整，不为每一行添加卡片边框或阴影。悬停反馈不得强于选中状态。
+- 项目选择器下方常驻跨项目活动汇总，空闲时显示“暂无活动”；项目计数与项目、会话级联菜单遵守
+  [项目活动汇总 UI 规则](./docs/features/application-tool-navigation/ui-design.md#10-项目活动汇总)。
+  活动数量不改变项目菜单的稳定分组和顺序。
+- 桌面停靠状态下，主侧栏宽度允许在 `220px` 至 `420px` 范围内通过指针或键盘调整，
+  并记住用户选择；分隔条使用 `separator` 语义，支持方向键、Home 和 End。小于
+  `900px` 时继续使用固定宽度抽屉，不显示拖拽分隔条。
 - 关联 Task 的 Conversation 在行最左侧显示独立展开按钮，父会话行不重复任务标签或数量；
  展开后的每个 Task 子项左侧显示名称，模式、计划和共享状态标记收在右侧，与父会话的
  更新时间位置一致；展开层级只到 Task，不展示 Job、Subjob 或 Run。
@@ -298,31 +307,73 @@
  失败或中断使用危险色，等待审批使用警告色，暂停或取消使用禁用色；非完成态旁边同时
  显示本地化状态文字，已完成文案保留给辅助技术而不在紧凑元数据中重复显示，不能只靠
  颜色或动效表达状态。
- 账户与设置入口固定在侧栏底部。已有稳定设置入口时，不在顶栏重复提供同一入口。
+- 左上角品牌区允许用户在“外观”设置中定制品牌名称、中英文副标题和单个 Logo。定制只
+  影响该品牌区，不替换安装包名称、更新协议、Agent 标识或应用正文中的 GoodBuddy 产品
+  身份。副标题按当前界面语言显示，留空时隐藏且不保留空行。
+- 品牌设置必须提供同布局预览、显式保存、默认 Logo 和整组恢复默认操作。自定义 Logo 仅
+  接受用户本机选择的 PNG、JPEG 或 WebP 内联数据，宽高不超过 `4096 × 4096`、总像素不
+  超过 1600 万且大小不超过 `512 KB`；不得读取远程 Logo URL。名称或副标题溢出品牌区时
+  单行截断，不能撑宽或挤压侧栏。
+- 侧栏底部固定显示文件、终端、浏览器和资源监控四个系统工具图标，设置按钮独立靠右。工具
+  图标只负责打开或聚焦助手工作栏面板，不在侧栏复制工具内容。已有稳定设置入口时，不在顶栏
+  重复提供同一入口。

 ### 6.9 助手工作栏

 助手工作栏是应用级右侧工具容器，不归属于聊天页面，也不根据当前页面、项目或 Runtime
 自动增删入口。产品契约见
-[通用助手工作栏与执行空间 PRD](./docs/prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。
+[通用助手工作栏与执行空间 PRD](./docs/features/assistant-workbar/prd.md)，
+动态 Tab、“+”和终端细节见
+[助手工作栏多终端页签 PRD](./docs/features/assistant-workbar/terminal-tabs-prd.md)。

- 默认固定提供任务中心、工作区、浏览器和成果四个标准栏目，不根据当前页面或
-  Runtime 能力自动增删入口。
- Task Center 是 Task 的单例应用级索引，不使用“跟随 / 固定目标”多实例模式。每个 Task
-  只关联一条 Conversation，一条 Conversation 可以关联多个 Task；列表不得复制会话内容，
-  也不得把 Job/Run 提升为可导航 UI 对象。
+- 升级后默认打开任务中心、工作区、一个浏览器实例和成果。任务中心与工作区是不可关闭的
+  单实例基础应用；浏览器是可关闭的多实例应用；成果保持可关闭的单实例应用。不可关闭不
+  等于锁定顺序。
+- 资源监控作为本机单实例应用保留在能力目录，但不加入升级后的默认打开实例。面板只在可见
+  活动时采样，首期不持久化历史或提供后台负载告警。
+- Tab 行只显示已打开实例，行末始终提供“+”普通按钮；点击后在内容区打开应用选择页。
+  “+”不使用 `tab` 语义，也不能因为终端或其他应用已经打开而消失。
+- 应用注册表分别声明单实例或多实例、默认打开、必须存在、可关闭和排序策略。在工作栏“+”目录中，
+  单实例重复选择时聚焦已有 Tab；浏览器和终端每次选择创建独立实例。主侧栏系统工具快捷
+  入口按当前上下文聚焦最近使用的匹配实例，额外实例仍从“+”目录创建。
+- Task Center 是默认跟随当前项目的单实例索引，不使用多实例模式。用户可在同一 Tab 内切换
+  “当前项目”“全局任务”和“全部项目”；范围变化不得创建第二个 Task Center。每个 Task 只
+  关联一条 Conversation，一条 Conversation 可以关联多个 Task；列表不得复制会话内容，也
+  不得把 Job/Run 提升为可导航 UI 对象。
 - 各栏目读取当前会话或项目的对应内容；当前内容不可用时仍保留栏目入口并说明原因。
 - 能力、连接和内容可以动态变化，栏目入口不能随之自动隐藏。不可用状态必须说明原因、影响和可执行入口。
- 用户可以主动排序或隐藏栏目，并可恢复默认布局；应用不能用用户偏好机制实现自动能力裁剪。
- 四个栏目使用稳定标签并保留 `tablist`、`tab`、`tabpanel`、方向键、Home、End 和焦点恢复语义。
+- 用户可以主动排序栏目，并可关闭可关闭实例或恢复默认布局；任务中心和工作区不能隐藏或
+  关闭。应用不能用用户偏好机制实现自动能力裁剪。
+- 已打开实例保留 `tablist`、`tab`、`tabpanel`、方向键、Home、End 和焦点恢复语义。
+  实例过多时 Tab 区单行横向滚动，“+”保持可见，不换行或改成下拉框。不可关闭实例不渲染
+  关闭按钮，也不响应关闭快捷命令。
+- 当前工作栏 Tab 必须同时使用连续内容表面、可见边框、顶部指示、图标或较高字重中的至少
+  两种信号；悬停反馈不得强于当前选中态。Tab 关闭按钮保留固定布局空间，默认仅在对应 Tab 悬停或
+  `focus-within` 时显示；无悬停或粗指针设备始终显示，键盘与辅助技术始终可访问。
+- 工作栏 Tab、Tab 关闭按钮和“+”入口沿用共享控件圆角；终端面板外框及终端顶部工具栏按钮
+  使用直角，形成紧凑的停靠式终端界面。
+- 选择“终端”后直接绑定当前项目，由项目执行空间自动决定本机或托管 SSH；不再显示第二层
+  目标选择器。终端面板内部不重复提供关闭会话按钮，关闭统一由 Tab 入口完成。
 - 下一次请求使用的附件和知识库由会话输入区展示与管理，不在工作栏重复提供“上下文”栏目；
  记忆功能实现前不展示占位内容，未来的记忆与历史执行上下文归入关联 Task 的任务中心详情。
 - 徽标可以提示未解决意见、等待审批、失败或连接状态，但不能成为唯一状态信号，也不能无条件抢占当前栏目。
+- 浏览器 Tab 的内容顶部固定使用一条紧凑工具栏，按“返回、刷新/停止加载、地址输入、
+  前往、交互、关闭浏览器”排列。“刷新”在当前页面加载时原位切换为“停止加载”；
+  “关闭浏览器”必须使用明确文字和与页面导航控件清楚区分的危险操作视觉，不能继续标为
+  含义模糊的“停止浏览器”。地址输入显示浏览器权威提交 URL，但用户编辑期间保留本地草稿，
+  不被画面或状态刷新覆盖；提交裸域名时自动添加 `http://`，提交、失焦后的同步规则不得让
+  尚未提交的文字改变 Agent 看到的页面。
+- 浏览器工具栏操作的是该实例绑定的 Conversation 和 Browser Tab。同一 Conversation 的多个
+  Tab 共享隔离登录上下文，但页面、导航、操作队列和元素引用相互独立。模型请求开始时冻结
+  工具目标，用户切换工作栏 Tab 不改变进行中的 Agent 操作。创建中、Agent 操作中或已进入完整交互窗口时禁用其余
+  工具栏控件；仅当前导航仍在加载时保留“停止加载”，且该操作只中止页面加载，不关闭浏览器、
+  不释放 Runtime 上下文。没有会话的活动 Conversation 可以直接在地址栏输入 URL 并“前往”
+  创建会话，但必须复用 Agent 浏览器相同的 URL 策略与能力路径。
 - 所有窗口宽度下均停靠在主工作区右侧并参与水平布局回流；展开时压缩主工作区，不能覆盖、
  遮罩或隔离其内容。分栏计算排除最左侧主导航，主工作区与工作栏采用相同的 `300px`
  最小宽度；拖动保存两者在可用分栏宽度中的比例，任一侧到达最小值后都不得继续侵占。
  所有可容纳两侧最小值的尺寸均支持指针和键盘调整，并须保留全部栏目入口。
- 工作栏开关固定在窗口关闭按钮正下方，同一个按钮负责展开与收起并持续暴露状态；图标中的
+- 工作栏开关固定在顶栏 `.topbar__actions` 内、紧邻浅色/深色主题按钮之前，同一个按钮负责展开与收起并持续暴露状态；图标中的
  箭头方向必须随当前动作切换，收起状态提示展开，展开状态提示收起。按钮保持普通图标按钮
  视觉，不通过持续高亮表达展开状态。工作栏内部不再重复关闭按钮；当前会话没有 Task 时，
  不得为了放置该开关而保留一条空上下文栏。
@@ -344,15 +395,27 @@
  `34px × 34px` 点击区域。
 - 发布说明 Modal 与其他应用级 Modal 一样使用整窗遮罩；遮罩必须覆盖主侧栏、右侧内容和
  顶栏，不能保留一条未被遮罩的窗口控制色块。关闭操作由 Modal 自身提供。
+- 整窗固定遮罩通过 `createPortal(..., document.body)` 挂载，避免页面层叠上下文影响；
+  保留 React Context、关闭与焦点管理，表单样式不得依赖已移出的页面祖先选择器。
+- 原生浏览器 `WebContentsView` 不受网页 `z-index` 控制。应用级 Modal 打开时统一释放
+  浏览器 viewport；非模态对话框、菜单、局部确认或应用通知与浏览器区域相交时也释放。
+  浮层关闭后只恢复当前活动实例的 viewport，不关闭、重建或刷新网页。接线与测试见
+  [浏览器多实例技术设计](./docs/features/assistant-workbar/browser-tabs-technical-design.md#4-renderer-与-viewport)。
+- 遮罩必须 `inset: 0` 铺满整窗，并由 `styles.css` 中统一的遮罩选择器声明
+  `-webkit-app-region: no-drag`，否则 `.brand` 与 `.topbar` 的原生拖动区域会截获指针，
+  使遮罩上的控件无法悬停和点击。新增整窗遮罩时扩展该共享选择器，不要在各自规则里复制
+  `no-drag`，也不要用 `inset: 38px 0 0` 之类的偏移绕开标题栏。
 - 当前会话存在 Task 时，Task 上下文栏位于标题栏下方并承载任务摘要与详情；没有 Task 时
  整行隐藏。折叠状态保持为 `46px` 单行表面，与右侧工作栏标签栏等高，左右分隔线必须水平
  对齐。该栏不重复放置新建入口。
 - “新建任务”只位于工作栏“任务索引”标题后方；任务状态筛选占满工作栏可用宽度，四个选项
  等分，不能保留内容宽度的短控件。
- Runtime 状态、同步状态等短标签使用 `--font-caption`，不得放大为正文标题。
+- Runtime 状态、同步状态等短标签使用 `--font-caption`，不得放大为正文标题。顶栏 Runtime
+  状态由状态点和 Runtime/模型名称紧凑表达：就绪使用绿色，连接中使用黄色，不可用使用灰色，
+  不再重复显示状态文字；完整状态详情继续通过可访问说明和工具提示提供。
 - 浅色与深色切换属于持续可用的窗口级操作，直接显示太阳或月亮图标，并通过可访问名称说明将切换到的主题。选择必须持久化，切换不得改变布局。
 - 顶栏只直接显示当前任务所需的高频操作。已有侧栏账户设置入口时，不再重复显示 Runtime/设置入口；使用帮助优先放在相关操作附近，而不是为单个帮助项创建“更多”菜单。
- 助手工作栏开关固定在上下文栏最右侧并与窗口关闭按钮纵向对齐；展开后该开关保持原位并
+- 助手工作栏开关固定在顶栏 `.topbar__actions` 内、紧邻浅色/深色主题按钮之前；展开后该开关保持原位并
  负责收起，不在工作栏标题区域增加第二个关闭入口。
 - 只有存在至少两个无法由稳定入口承载的低频全局操作时才增加全局菜单，不为了容纳一个冗余入口而显示省略号按钮。
 - 窄窗口下优先压缩状态标签并保留图标按钮，不隐藏窗口控制、当前范围或进行中的风险状态。
@@ -369,8 +432,11 @@
 - 支持上、下方向键、Home、End、Enter 或 Space、Escape；打开后焦点进入当前项，关闭后返回触发按钮。
 - 点击或聚焦菜单外部时关闭；同一输入区内的模型、专家和模式菜单互斥展开。
 - 不可用选项保持可读并说明原因，键盘导航不得停留在不可选择项上。
- 项目选择器属于富信息单选菜单。收起时保持当前项目名称紧凑可见；展开后每项至少显示项目名称和项目类型，并按数据可用性补充本地目录、远程来源、平台、连接状态或其他能帮助辨认项目的信息。
- 项目菜单区分“本地项目 / 远程项目 / 远程通道”，不把消息通道命名为远程项目。“远程项目（技术预览）”关闭时完整移除远程项目分组，而不是显示不可操作的残留选项；本地项目和远程通道继续可用。分组、项目类型和连接状态均须显示文字，不只依赖图标或颜色；新增项目来源时不得退回仅列名称的原生 `select`。
+- 当某个选项需要用户在其展开区域内完成路径选择、授权或其他前置操作时，不得因为前置条件
+  尚未完成而禁用该入口。选择入口只展开流程，验证成功前不提交实际值；不得自动采用第一个
+  候选。取消保持原值，验证错误在对应操作附近显示。
+- 项目选择器属于富信息单选菜单。收起时保持当前项目名称紧凑可见；展开后每项至少显示项目名称，并按数据可用性补充目录、远程来源或其他能帮助辨认项目的信息。托管 SSH 项目在“远程项目”内按已保存 SSH Host 做一层轻量分组，Host 标题旁显示真实 Agent 连接状态；项目副标题只显示远端路径，不重复“托管 SSH”类型。
+- 项目菜单区分“本地项目 / 远程项目 / 远程通道”，不把消息通道命名为远程项目。“远程项目（技术预览）”关闭时完整移除远程项目分组，而不是显示不可操作的残留选项；本地项目和远程通道继续可用。Agent 连接状态使用“未连接 / 连接中 / 就绪 / 异常”等文字标签，读取状态不得发起连接，且不能只依赖图标或颜色；新增项目来源时不得退回仅列名称的原生 `select`。

 ### 6.12 应用通知与就地反馈

@@ -535,28 +601,50 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 ### 13.1 聊天

 - 使用 `reading` 壳层，消息流与输入区共享宽度。
+- 消息头像放在正文区域外侧：助手头像居左，用户头像居右。输入框左边缘与助手正文左边缘对齐，
+  右边缘与用户气泡右边缘对齐；两侧为头像保留独立安全边距，滚动条出现或工作栏缩放不得改变对齐。
 - 对话标题和当前项目范围位于 `PageHeader` 或对话上下文区，不在消息流中重复。
+- 已结束且包含正文的助手回复在底部提供带可访问名称和工具提示的复制图标；复制 Markdown
+  原文，不包含推理过程、工具日志或引用元数据，结果通过应用通知反馈。流式回复完成前不显示
+  复制入口。
+- 默认开启“会话 HTML 渲染”时，已完成 Agent 回复中的完整 HTML 与 `html` / `htm`
+  代码块在原位置显示隔离静态预览；用户消息、推理过程和流式中的回复不得执行 HTML。
+  每个预览持续标注脚本和网络已禁用，并在标题右侧复用与 Mermaid 图表相同的图标按钮组：
+  源码按钮使用代码图标并暴露 `aria-expanded`，全屏按钮使用放大图标打开统一 Modal。
+  全屏预览遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape 关闭和焦点恢复规则，
+  并沿用同一套清理与 Sandbox/CSP 边界。关闭平台功能后必须显示 HTML 源码，不能隐藏内容
+  或保留旧预览。
 - 本地会话的更多操作提供“在新会话中继续”。创建前必须先持久化当前稳定消息；有活动运行
  或待发送内容时不可创建。新会话复制聊天内容与当前 Runtime/知识检索选择，重置压缩状态，
  使用新的会话和消息 ID，且不复制 Task、队列、运行、记忆或成果归属。
 - 模式、模型或工具权限属于上下文控制，不与页面导航页签混用。
 - 模型、专家角色、工作模式、OpenCode Agent、Continue 预设和 Runtime 快捷操作使用统一的上下文单选菜单，并保持菜单互斥、键盘可达和选中状态明确。
 - Runtime 选择菜单必须反映当前执行空间的真实能力。托管 SSH 项目当前只支持 OpenCode，因此输入区只渲染已配置的 OpenCode 选项和管理入口，不显示直连模型、Continue 或 DeepSeek Harness 的不可用入口；旧会话保存的其他 Runtime 选择在项目激活时恢复为当前 OpenCode 配置。
- 输入区第一行工具栏只承载附件、语音、知识范围、专家角色、工作模式、Runtime 选择和发送等通用操作。OpenCode Agent、Continue 预设及 Runtime 快捷操作必须放入其下方独立的 Runtime 专属功能行，通过可见分组名称、顶部边界和差异化表面与通用操作分层；该行只承载对当前消息生效的高频选择，当前 Runtime 没有可选专属功能时不保留空行。
+- 输入区使用一个完整容器，主工具栏保留附件、语音、Runtime、工作模式、会话选项及停止/发送。知识范围、专家角色、OpenCode Agent、Continue 预设和 Runtime 快捷操作收纳在会话选项浮层中；Runtime 专属选择在浮层内按提供方分组，无可选功能时不保留空分组。输入框上方以简短摘要显示生效的专家、知识范围、检索方式和 Runtime 专属选择。
+- 会话选项浮层与主行菜单互斥，内部复用上下文选择菜单；子菜单就地展开，浮层统一限制宽高并滚动。Escape 先关闭子菜单并恢复其触发按钮焦点，再关闭会话选项并恢复入口焦点；点击外部、焦点离开、切换会话或开始/结束回复时关闭浮层。
+- 会话选项入口紧随录音键，使用无常驻边框的调节图标，保留可访问名称、悬停说明和展开态反馈；浮层在工具栏左侧展开，最大宽度为 `300px`，窄窗口不超过输入区。浮层内选择器使用整行轻量列表样式，避免重复的按钮边框；知识库行右侧显示展开箭头，展开时朝上。
 - 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 过程中使用同一轻量折叠记录：不显示外层“工具执行”标题、计数、背景和边框，保留无障碍区域名称。记录纵向左对齐，头部按内容收宽且不超过消息宽度；展开箭头在左，工具名作为主标题，有额外信息的单行摘要弱化显示。右侧以绿色对勾显示成功完成，以图标显示运行和待执行状态，提供悬停文字和无障碍名称；失败和可恢复状态保留文字。仅重复工具名和执行状态的已知 Runtime 模板摘要在头部与详情中均隐藏；刷新重试、审批等额外提示保留。默认折叠，状态和输出更新不改变用户的展开选择；折叠时露出一行错误，展开详情使用消息可用宽度、浅背景和左侧细线，按错误、结果、独立折叠的输入参数阅读。详情保留原始文本，完整 JSON 输入可缩进显示，复制仍使用收到的原文，并通过应用通知反馈。详情工具栏只保留复制按钮，文本默认自动换行，长内容在固定最大高度内滚动，不提供换行切换和展开全部按钮。
+- OpenCode 主会话和子 Agent 的工具记录均保留 Runtime 提供的操作标题作为摘要，显示文件路径、命令或操作描述；本地 SDK 标题去除首尾空白后最多保留 240 字符，没有标题时沿用工具名回退规则。主会话工具失败或中断时保留已收到的标题；远端 ACP 继续在记录名称中显示其提供的标题。
+- 工具取消后保留“已取消”文字，避免与失败图标混淆。
+- Continue、DeepSeek Harness 和直连模型的工具名后显示单行操作摘要，内容提取、长度与完成态保留规则见[工具操作摘要](./docs/features/assistant-workbar/runtime-interactions.md#工具操作摘要)。
 - Agent 回复进行中不能禁用普通消息发送。新消息与到期 Scheduled Task 共用 Conversation 级待发送队列。队列位于 Composer 容器之外、与输入框等宽并保持独立间距；有待发送项时直接显示无标题栏的极简列表，空队列不保留占位。每项固定为一行，按进入顺序显示轻量来源图标和截断摘要；普通消息使用消息图标，Scheduled Task 统一使用淡出时钟图标。
 - 待发送项默认在当前回复结束后顺序执行。每项提供明确的“立即中断并插入”（空闲时为“立即运行”）和删除操作；前者先取消当前 Conversation 的活动执行，再将所选项提升为下一项，不允许同一 Conversation 并发写入时间线。
 - 队列区域向上增长并设置有界滚动高度，不提供展开、收起或冗余计数标题。宽容器中的操作采用弱化的行内样式，不渲染成强调卡片或胶囊；窄容器中保留来源、摘要和图标操作并隐藏冗长按钮文字。区域、来源和每个操作必须有可读无障碍名称。队列异步错误进入应用通知，不在 Composer 内复制通知样式。
 - 支持上下文状态的 Runtime 在输入区下方复用同一紧凑用量条；文案必须区分“本次模型调用”和“压缩后对话估算”。手动压缩仅在当前 Runtime 明确支持且没有活动回复时显示，作为元信息区左下角的浮动次操作，不参与输入区高度计算；元信息区始终预留稳定高度，切换 Runtime 不得让输入框上下位移。元信息区与窗口底部只保留紧凑安全留白，不形成额外空白区。进行中禁用重复操作，结果通过应用通知反馈。
 - 已选择的工作模式在触发按钮中只显示 `Ask` 或 `Execute`；完整中文含义和说明保留在菜单选项、可访问名称及输入区下方的模式说明中。
- 宽度大于 `700px` 时，通用工具栏内的添加内容、知识范围、专家、模式和 Runtime 选择保持同一行，Runtime 专属功能在自己的下一行横向排列。窄输入区中两行分别换行，专属选择器以至少 `220px` 的基准宽度换行而不是被挤压；不能把专属控件重新塞回通用工具栏。
- 输入框原生支持 `Ctrl+V`：文本直接进入草稿，图片转换为本次消息附件。文件选择由上传按钮承担，不再提供独立“读取剪贴板”按钮；默认工具栏也不提供“截取当前屏幕”和“选择应用窗口”入口，避免与系统粘贴、文件选择和后续工具执行重复。
- “Enter 发送 · Shift+Enter 换行 · Ctrl+V 粘贴图片或文本”等输入操作提示放在空输入框内部，作为主占位文案的次级行；不得在输入框下方单独占用第二行。输入框下方只保留一行当前模式、安全边界或全局快捷键说明。
+- 宽度大于 `700px` 时，主工具栏的添加内容、Runtime、模式、会话选项与发送保持同一行。窄输入区按容器宽度换行，保留发送及停止入口；选项浮层不得超出输入区宽度，不再常驻独立的 Runtime 专属功能行。
+- 输入框原生支持 `Ctrl+V`：文本直接进入草稿，系统截图和从文件管理器复制的一个或多个支持文件加入本次消息附件。文件粘贴与上传按钮共用读取、解析进度和数量限制；读取期间阻止重复导入及发送，错误就地关联输入框和附件按钮。具体类型、大小及批次失败规则见[聊天附件要求](./docs/features/document-processing/prd.md#321-聊天附件入口)。默认工具栏不提供独立“读取剪贴板”“截取当前屏幕”和“选择应用窗口”入口。
+- “Enter 发送 · Shift+Enter 换行 · Ctrl+V 粘贴文件、图片或文本”等输入操作提示放在空输入框内部，作为主占位文案的次级行；不得在输入框下方单独占用第二行。输入框下方只保留一行当前模式、安全边界或全局快捷键说明。
 - 输入操作提示不能替代表单的可访问名称，输入框始终保留持久的程序化标签。
 - 空对话展示可执行的起始建议，发送失败保留输入并提供重试。
+- 消息流的滚动范围必须使用已渲染消息的真实高度。长会话可以按批次只挂载最近消息并由用户
+  加载更早内容，但不得用固定的消息占位高度替代实际布局，避免推理、工具列表或长正文被
+  排除在可滚动范围之外。

 ### 13.2 最近对话

@@ -586,9 +674,9 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - 范围明确区分 Global 与指定的一个或多个 Project；Global 与指定项目互斥，多项目选择使用
  Checkbox，不能依靠进入页面时的当前项目推断。
 - 状态卡片使用统一状态令牌，不只依赖颜色。
- 保留“成长概览 / 待处理建议 / 心跳轨迹 / 心跳计划”四个同级页面。
+- 保留“运行概览 / 待处理建议 / 报告与记录 / 心跳计划”四个同级页面。
 - 智能心跳菜单入口是完整配置的权威位置；任务中心和设置中心不得复制同一 CRUD 表单。
- “未来分区记忆”仅为长期方向，数据、状态和页面尚未设计，不得显示占位入口。
+- 分区记忆协同与唤起条件尚未实现，不得显示占位入口或平行的记忆类型。

 ### 13.5 Task Center

@@ -602,8 +690,9 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
  成果查看器，不撑高列表，也不显示 Job/Run 树。
 - “新建定制任务”使用共享 Modal，明确选择当前或新 Conversation。聊天入口默认当前
  Conversation，Task Center 入口默认新 Conversation；选择必须持续可见。
- 创建 Modal 默认 Execute，并允许主动切换 Ask。Execute 持续显示实际 Runtime、Project、
-  工作目录、工具和审批摘要；不支持工具时不得静默降级。
+- 定时消息创建 Modal 使用关联 Conversation 的 Runtime 与 Ask/Execute 模式，不再提供独立
+  模式开关。未运行计划的详情显示会话当前模式，已运行任务显示该次执行记录的模式；
+  不得用旧计划字段表示下一次执行权限。不支持工具时不得静默降级。

 ### 13.6 运行记录

@@ -618,9 +707,16 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证

 - “笔记 / 待办”属于同一工作台内的同级内容面板，使用 `PageTabs` 的 `segmented` 视觉变体，与模型设置的分段控件保持同一外观。
 - 页签切换保留 `tablist`、`tab` 和 `tabpanel` 语义；待办状态仍使用独立的 `SegmentedControl`，不得与内容页签合并。
+- 笔记编辑器保留 Quill 原生列表快捷输入：输入 `-`、`*`、`1.`、`[ ]` 或 `[x]` 后按空格，分别转换为项目符号、编号或待办清单。快捷输入只生成现有 Delta 富文本，不引入 Markdown 源码模式、第二套持久化格式或第三方 Markdown 插件；编辑区附近持续提供简短提示。
+- 左侧笔记与待办列表在双栏布局中允许在 `180px` 至 `360px` 范围内通过指针或键盘调整，
+  也可从页面标题区隐藏和恢复；宽度与显示状态均记住用户选择。分隔条保留 `separator`
+  语义及方向键、Home、End 操作，窄窗口堆叠布局不显示拖拽分隔条。
+- 左侧笔记列表依次显示标题、最多两行内容预览，以及同一行的记录数和本地化更新时间。记录数靠左、更新时间靠右，窄宽度下均保持单行省略，不挤压标题或扩大列表栏。
 - 左侧“魔法笔记”入口可显示未完成待办数量。数量为 0 时隐藏徽标，超过 99 时显示 `99+`，可访问名称仍说明精确数量；勾选、取消勾选以及 Agent / MCP 对笔记清单的写入都必须刷新数量。
 - 未完成待办徽标的高度不得超过主导航图标；数量从 0 变为可见或再次隐藏时，主导航项行高和相邻菜单位置必须保持不变。
 - 在待办面板勾选或取消勾选后，当前缓存中的源笔记正文必须立即同步对应清单状态，不得依赖离开工作区后重新加载。
+- Agent / MCP 或其他入口成功写入笔记后，已打开的工作台自动更新笔记列表、当前详情、待办及来源记录，不增加刷新按钮。保留仍存在的笔记与待办选择、搜索和筛选，以及未保存的标题、输入区和记录编辑草稿；普通后台刷新不重建编辑器。
+- 外部删除当前笔记时，无草稿则选择剩余笔记；有草稿则保留编辑区并提示先复制草稿。外部删除正在编辑的记录时，同样保留该编辑器并明确提示记录已删除；保存失败不得清空草稿。
 - 当前记录草稿非空时，切换笔记、待办或内容面板必须先在编辑器旁就地确认；继续编辑时保留草稿并恢复编辑焦点，只有明确选择放弃后才切换。
 - 创建、保存、更新、删除和 AI 评论完成等短期结果进入应用级通知，不在编辑区或列表上方堆放页内通知。
 - 标题或正文校验、删除确认、同步进度和可就地恢复的错误仍靠近对应编辑器或操作呈现。
@@ -628,6 +724,8 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 ### 13.8 设置中心

 - 全页设置使用固定标题区、左侧分类导航和独立滚动的内容区。右上角关闭按钮是离开设置中心的稳定入口。
+- 新建项目与项目设置弹窗固定标题、关闭按钮和底部操作区，仅表单内容滚动；滚动条不进入标题区，关闭按钮保留至少 40 × 40px 的点击区域。
+- 项目弹窗通过 Portal 挂载到 `document.body`，避免侧栏内的弹窗与主窗口标题栏拖动区域重叠时，Electron 截获关闭按钮的鼠标输入。
 - 左侧分类导航在宽屏使用 `220px`，中等窗口使用 `196px`，窄窗口转为横向滚动；纵向滚动条仅在内容溢出时占用右侧空间，不在左侧创建镜像预留，选项与左侧可见边界保持默认内距。分类标题使用正文级字号，分类说明使用辅助字号；右侧内容区在可用空间内流式伸缩，最大宽度使用 `standard` 壳层的 `960px`，不得以页面专属较窄宽度压缩表单。
 - 全页设置标题区与双栏内容使用共享 `--page-gutter`，标题、分类导航和内容区在同一页面边距基线上；标题继续使用标准 `PageHeader` 的底部分隔线与下内距。固定标题和双独立滚动区域不改变这些一级页面壳层规则；模态设置保留自身外框与标题边界。
 - 设置中心不显示全局操作页脚，避免重复关闭入口和没有功能意义的整宽分隔线。
@@ -640,15 +738,19 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - “模型连接”的认证字段按“认证方式 → API Key → 凭据状态”排列；只有选择 API Key 时显示输入框。已保存的 API Key 属于该连接，修改模型服务地址或临时选择“无需认证”不得自动清除，也不得要求重新输入；仅由明确的“清除凭据”或“删除连接”操作移除。
 - “保存并测试模型”必须在保存后发送一次有界的真实模型请求。文本连接校验本次随机测试文本，图像连接校验实际返回的内联图片；仅收到成功 HTTP 状态、模型列表或健康检查响应不算测试成功。界面持续说明该操作可能产生少量服务商用量费用，成功反馈明确写为“真实生成测试通过”。
 - 所有显式保存的设置草稿都参与离开保护：关闭、切换分类、主侧栏或工作区导航及托盘导航不得静默丢弃，统一通过设置中心的就地确认提供继续编辑与明确放弃入口，保存失败后保留输入。“平台功能 / 通用设置”承载全局快捷唤起的共享 Switch、可访问 accelerator 录制输入、恢复默认、保存及注册、停用或冲突状态，不新增分类或页签；注册或持久化失败时保留上一组可用快捷键和当前草稿，保存或停用成功后同步更新输入区的快捷键提示。
- “平台功能”使用共享 `PageTabs` 区分“通用设置”“远程项目（技术预览）”和“魔法笔记”，默认进入通用设置。“远程项目”页将持久 Switch 与用户数据目录中的 Linux x64/arm64 Agent 包清单分成独立卡片；清单延迟到首次打开该页签时由 Main 完整校验，并读取所选更新源的小型签名目录，显示本地版本、在线最新兼容版本以及“有更新”“已是最新”“未下载”“校验失败”。打开页签或刷新不得自动下载 `.gbagent`；只有用户点击带目标版本的下载/更新按钮后才传输包。签名目录不可用时继续显示并允许导出已验证本地包，提供就地重试错误；清单不混入 Host 已安装状态、缓存路径或敏感签名细节。下载和导入期间保留上下文进度，成功进入全局通知视口。“魔法笔记”页提供默认开启的“显示未完成待办数量”持久 Switch，关闭后只隐藏左侧数量徽标，不改变待办数据或魔法笔记入口。全局模型下载源使用 `fieldset`、持久 `legend` 与整行可点击的原生 Radio 卡片；选中状态同时依靠 Radio、边框和背景表达，读取失败时不得用默认值伪装为已保存选择。
- “关于与更新”的更新源位于“启动时检查新版本”开关下方，常规宽度下将标签、原生单选下拉框和用途说明放在同一行，并复用设置表单的统一控件样式；关闭启动检查后，下拉框置灰且不可操作。选项显示“GitHub（默认）”和中性的“镜像节点”。该选择同时控制手动检查、启动时检查、下载页和 Agent 包在线下载，不显示底层服务商名称。
- “关于与更新”在版本信息之后提供应用内反馈卡片。反馈对话框使用原生字段、明确隐私说明和一张可选截图，失败时保留草稿并提供就地重试，成功时在对话框内保留可复制编号而不重复发送全局通知；对话框遵循统一 Modal 的背景隔离、初始焦点、Tab 循环、Escape、焦点恢复和窄窗口布局。
+- “平台功能 / 通用设置”同时提供默认开启的“在会话中渲染 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` 组织。直连模型中的联网搜索与内置浏览器使用一致的折叠卡片和独立总开关；内置浏览器必须明确说明其操作 GoodBuddy 隔离浏览器，不控制客户端已安装的浏览器，开启后可由 Execute 直接使用，不逐次询问。尚未生效的命名浏览器配置不得显示在界面中，“电脑控制”只显示实际操作客户端电脑的能力。内置 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 内容。
+- 内置 MCP 中的“图片生成与编辑”是自动管理例外：该行始终可见，标记“内置 · 自动管理”，不提供独立启停、分配保存、移除或凭据编辑。直连 Model、OpenCode、Continue、DeepSeek Harness 的分配只由已保存图片模型的“允许 AI 在会话中调用”设置推导；至少一个开启则全部勾选，没有开启模型则全部取消。使用禁用的原生 Checkbox、Runtime 标签及关联说明，保留可聚焦的“前往图片模型设置”导航；远程适用范围通过 GoodBuddy Agent 说明持续可见。Ask、离线、无工具能力或调用错误不改变勾选。图片模型默认关闭会话调用；默认生图模型独立于普通默认连接，关闭或删除后保留失效选择并提示改选，不自动回退。

 ### 13.9 文档解析设置

@@ -667,7 +769,7 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证
 - DOC、XLS、PPT 等旧格式通过受控转换 Provider 生成新式 Office 文档和 PDF。转换子进程必须禁用宏和网络，限制输入、输出、内存、超时与临时目录，并在关闭或取消时清理。
 - OCR 来源使用“本地模型 / 远程服务”互斥选择。选择本地后显示模型下载、模型下拉选择和本地运行参数；选择远程后显示 MinerU、PaddleOCR-VL 等服务连接配置。未实现的远程服务入口保持可读但禁用，不再增加与来源选择重复的“隐私与云端处理”授权区。
 - 用户配置并保存远程 OCR 服务即表示选择该处理路径，不再逐场景重复询问。界面仍须明确显示当前服务名称、处理范围和远程属性，API 密钥只保存在主进程加密设置中，未选中远程服务时不得上传文档。
- 解析结果使用统一文档结构，至少保留文档标题、来源格式、页码或工作表定位、正文块、置信度、处理方式和警告。聊天附件对结果做有界截断，知识库使用完整结果分块和索引。
+- 解析结果使用统一文档结构，至少保留文档标题、来源格式、页码或工作表定位、正文块、置信度、处理方式和警告。聊天附件保留完整解析文本，超过暂存容量时报错；知识库使用完整结果分块和索引，具体要求见[文档处理 PRD](./docs/features/document-processing/prd.md#32-场景工作流)。
 - 测试结果显示文件类型、页数、实际工作流、提取字数、OCR 页数、耗时和警告。测试文件不得自动进入聊天上下文或知识库。

 ## 14. 文案规则
@@ -725,6 +827,8 @@ GoodBuddy 是可调整窗口大小的桌面应用。响应式设计优先保证

 ### 15.5 验收

+执行与取证方法见 [Electron UI 自动化测试规范](./docs/quality/electron-ui-automation.md)，包括真实 Portal、原生键盘、计算样式与 PNG 审阅；视觉 fixture 与完整生产 App 的结果须分别标注。
+
 - [ ] 在浅色与深色主题下检查所有页面、弹窗、菜单、输入框、表格和空状态。
 - [ ] 在大于等于 `1200px`、`960px`、`720px` 和小于 `720px` 的窗口宽度检查布局。
 - [ ] 仅使用键盘完成导航、筛选、创建、编辑、确认和取消。
@@ -1,6 +1,6 @@
 {
  "formatVersion": 1,
-  "agentVersion": "0.11.5",
+  "agentVersion": "0.13.0",
  "protocol": {
    "major": 2,
    "minor": 0
@@ -15,6 +15,12 @@
        "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",
@@ -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 }
@@ -29,9 +29,11 @@ const {
  sep
 } = require('node:path')
 const tar = require('tar')
+const { detectElfArchitecture } = require('./binary-architecture.cjs')
 const {
-  detectElfArchitecture
-} = require('./binary-architecture.cjs')
+  targetName,
+  assertTargetBinary
+} = require('./agent-build-target.cjs')
 const {
  preflightRegisteredProductionKey
 } = require('./signing-key-preflight.cjs')
@@ -132,15 +134,8 @@ function readTrustedKeyRegistry(projectRoot = root) {
  return registry
 }

-function targetName(arch) {
-  if (!supportedArchitectures.includes(arch)) {
-    throw new Error(`Unsupported Agent architecture: ${arch}`)
-  }
-  return `linux-${arch}`
-}
-
-function lockedRuntimeInput(lock, arch, archivePath) {
-  const target = targetName(arch)
+function lockedRuntimeInput(lock, arch, archivePath, platform = 'linux') {
+  const target = targetName(arch, platform)
  const input = lock.node?.targets?.[target]
  if (
    !input ||
@@ -177,24 +172,23 @@ function lockedRuntimeInput(lock, arch, archivePath) {
 function assertElfArchitecture(
  filePath,
  expectedArchitecture,
-  description = 'Agent Node runtime'
+  description = 'Agent Node runtime',
+  platform = 'linux'
 ) {
-  const actual = detectElfArchitecture(readFileSync(filePath).subarray(0, 64))
-  if (actual !== expectedArchitecture) {
-    throw new Error(
-      `${description} architecture mismatch: expected ${expectedArchitecture}, received ${actual ?? 'unknown'}`
-    )
-  }
+  assertTargetBinary(filePath, expectedArchitecture, platform, description)
 }

-function koffiNativePackageName(arch) {
-  return `@koromix/koffi-linux-${arch}`
+function koffiNativePackageName(arch, platform = 'linux') {
+  return `@koromix/koffi-${targetName(arch, platform)}`
 }

-function koffiPayloadPaths(arch) {
+function koffiPayloadPaths(arch, platform = 'linux') {
  const packageRoot = `lib/node_modules/${koffiPackageName}`
  const nativeRoot =
-    `lib/node_modules/${koffiNativePackageName(arch)}`
+    `lib/node_modules/${koffiNativePackageName(arch, platform)}`
+  const native = platform === 'linux'
+    ? [`${nativeRoot}/linux_${arch}/koffi.node`, `${nativeRoot}/musl_${arch}/koffi.node`]
+    : [`${nativeRoot}/darwin_${arch}/koffi.node`]
  return {
    packageRoot,
    nativeRoot,
@@ -205,13 +199,9 @@ function koffiPayloadPaths(arch) {
      `${packageRoot}/src/koffi/src/static.js`,
      `${nativeRoot}/package.json`,
      `${nativeRoot}/index.js`,
-      `${nativeRoot}/linux_${arch}/koffi.node`,
-      `${nativeRoot}/musl_${arch}/koffi.node`
+      ...native
    ],
-    native: [
-      `${nativeRoot}/linux_${arch}/koffi.node`,
-      `${nativeRoot}/musl_${arch}/koffi.node`
-    ]
+    native
  }
 }

@@ -328,6 +318,20 @@ function createManifest(bundleDirectory, metadata) {
      spdx: 'MIT',
      path: 'licenses/zod-MIT.txt'
    },
+    ...(files.some(
+      (file) =>
+        file.path ===
+        'licenses/agent-client-protocol-Apache-2.0.txt'
+    )
+      ? [
+          {
+            package: '@agentclientprotocol/sdk',
+            version: metadata.acpSdkVersion,
+            spdx: 'Apache-2.0',
+            path: 'licenses/agent-client-protocol-Apache-2.0.txt'
+          }
+        ]
+      : []),
    {
      package: koffiPackageName,
      version: metadata.koffiVersion,
@@ -345,7 +349,7 @@ function createManifest(bundleDirectory, metadata) {
    formatVersion: 1,
    product: 'GoodBuddy',
    agentVersion: metadata.agentVersion,
-    platform: 'linux',
+    platform: metadata.platform ?? 'linux',
    arch: metadata.arch,
    protocol: metadata.protocol,
    signingKeyId: metadata.signingKeyId,
@@ -438,7 +442,10 @@ function validateManifestShape(manifest, expected) {
    manifest.product !== 'GoodBuddy' ||
    typeof manifest.agentVersion !== 'string' ||
    !semanticVersionPattern.test(manifest.agentVersion) ||
-    manifest.platform !== 'linux' ||
+    !(
+      manifest.platform === 'linux' ||
+      (manifest.platform === 'darwin' && manifest.arch === 'arm64')
+    ) ||
    !supportedArchitectures.includes(manifest.arch) ||
    !Number.isSafeInteger(manifest.protocol?.major) ||
    !Number.isSafeInteger(manifest.protocol?.minor) ||
@@ -603,7 +610,7 @@ function verifyBundleDirectory(bundleDirectory, options = {}) {
      throw new Error(`Agent entrypoint payload is missing: ${required}`)
    }
  }
-  const koffiPaths = koffiPayloadPaths(manifest.arch)
+  const koffiPaths = koffiPayloadPaths(manifest.arch, manifest.platform)
  for (const required of koffiPaths.required) {
    if (!declaredPaths.has(required)) {
      throw new Error(`Agent Koffi payload is missing: ${required}`)
@@ -612,7 +619,7 @@ function verifyBundleDirectory(bundleDirectory, options = {}) {
  const koffiLicense = manifest.licenses.find(
    (license) => license.package === koffiPackageName
  )
-  const nativePackage = koffiNativePackageName(manifest.arch)
+  const nativePackage = koffiNativePackageName(manifest.arch, manifest.platform)
  const nativeLicense = manifest.licenses.find(
    (license) => license.package === nativePackage
  )
@@ -627,13 +634,16 @@ function verifyBundleDirectory(bundleDirectory, options = {}) {
  }
  assertElfArchitecture(
    join(bundleDirectory, manifest.entrypoint.runtimePath),
-    manifest.arch
+    manifest.arch,
+    'Agent Node runtime',
+    manifest.platform
  )
  for (const nativePath of koffiPaths.native) {
    assertElfArchitecture(
      join(bundleDirectory, ...nativePath.split('/')),
      manifest.arch,
-      'Agent Koffi native binding'
+      'Agent Koffi native binding',
+      manifest.platform
    )
  }
  return {
@@ -654,7 +664,8 @@ function assertReplaceableBundle(directory) {
    if (
      manifest.formatVersion === 1 &&
      manifest.product === 'GoodBuddy' &&
-      manifest.platform === 'linux'
+      (manifest.platform === 'linux' ||
+        (manifest.platform === 'darwin' && manifest.arch === 'arm64'))
    ) {
      return
    }
@@ -703,13 +714,13 @@ function copyRegularFile(source, destination) {
  chmodSync(destination, 0o644)
 }

-function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion) {
+function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion, platform = 'linux') {
  const sourceRoot = join(projectRoot, 'node_modules', koffiPackageName)
  const packageMetadata = readJson(
    join(sourceRoot, 'package.json'),
    'Koffi package metadata'
  )
-  const nativePackage = koffiNativePackageName(arch)
+  const nativePackage = koffiNativePackageName(arch, platform)
  const nativeSourceRoot = join(
    projectRoot,
    'node_modules',
@@ -725,7 +736,7 @@ function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion) {
    nativeMetadata.name !== nativePackage ||
    nativeMetadata.version !== lockedVersion ||
    !Array.isArray(nativeMetadata.os) ||
-    !nativeMetadata.os.includes('linux') ||
+    !nativeMetadata.os.includes(platform) ||
    !Array.isArray(nativeMetadata.cpu) ||
    !nativeMetadata.cpu.includes(arch)
  ) {
@@ -734,10 +745,13 @@ function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion) {
    )
  }

-  const paths = koffiPayloadPaths(arch)
+  const paths = koffiPayloadPaths(arch, platform)
  const files = [
    ['package.json', `${paths.packageRoot}/package.json`],
    ['index.js', `${paths.packageRoot}/index.js`],
+    ['index.cjs', `${paths.packageRoot}/index.cjs`],
+    ['src/koffi/index.cjs', `${paths.packageRoot}/src/koffi/index.cjs`],
+    ['src/koffi/src/static.cjs', `${paths.packageRoot}/src/koffi/src/static.cjs`],
    [
      'src/koffi/index.js',
      `${paths.packageRoot}/src/koffi/index.js`
@@ -756,8 +770,7 @@ function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion) {
  for (const source of [
    'package.json',
    'index.js',
-    `linux_${arch}/koffi.node`,
-    `musl_${arch}/koffi.node`
+    ...paths.native.map((path) => path.slice(paths.nativeRoot.length + 1))
  ]) {
    const destination = `${paths.nativeRoot}/${source}`
    copyRegularFile(
@@ -769,7 +782,8 @@ function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion) {
    assertElfArchitecture(
      join(staging, ...nativePath.split('/')),
      arch,
-      'Agent Koffi native binding'
+      'Agent Koffi native binding',
+      platform
    )
  }
  return {
@@ -781,11 +795,13 @@ function copyKoffiRuntime(projectRoot, staging, arch, lockedVersion) {
 function buildAgentBundle(options) {
  const projectRoot = options.projectRoot ?? root
  const arch = options.arch
+  const platform = options.platform ?? 'linux'
  const lock = options.lock ?? readRuntimeLock(projectRoot)
  const runtimeInput = lockedRuntimeInput(
    lock,
    arch,
-    options.runtimeArchive
+    options.runtimeArchive,
+    platform
  )
  const registry =
    options.registry ?? readTrustedKeyRegistry(projectRoot)
@@ -829,13 +845,13 @@ function buildAgentBundle(options) {

  const destination =
    options.outputDirectory ??
-    join(projectRoot, '.agent-resources', targetName(arch))
+    join(projectRoot, '.agent-resources', targetName(arch, platform))
  mkdirSync(dirname(destination), { recursive: true })
  const staging = mkdtempSync(
-    join(dirname(destination), `.stage-${targetName(arch)}-`)
+    join(dirname(destination), `.stage-${targetName(arch, platform)}-`)
  )
  const runtimeStaging = mkdtempSync(
-    join(tmpdir(), `goodbuddy-node-${targetName(arch)}-`)
+    join(tmpdir(), `goodbuddy-node-${targetName(arch, platform)}-`)
  )
  try {
    tar.x({
@@ -858,7 +874,7 @@ function buildAgentBundle(options) {
      runtimeStaging,
      ...runtimeInput.licensePath.split('/')
    )
-    assertElfArchitecture(runtimeBinary, arch)
+    assertElfArchitecture(runtimeBinary, arch, 'Agent Node runtime', platform)
    copyFileSync(runtimeBinary, join(staging, 'node'))
    chmodSync(join(staging, 'node'), 0o755)

@@ -898,7 +914,8 @@ function buildAgentBundle(options) {
      projectRoot,
      staging,
      arch,
-      lock.koffi.version
+      lock.koffi.version,
+      platform
    )
    const launcher = [
      '#!/bin/sh',
@@ -923,6 +940,20 @@ function buildAgentBundle(options) {
      join(projectRoot, 'node_modules', 'zod', 'LICENSE'),
      join(staging, 'licenses', 'zod-MIT.txt')
    )
+    copyLicense(
+      join(
+        projectRoot,
+        'node_modules',
+        '@agentclientprotocol',
+        'sdk',
+        'LICENSE'
+      ),
+      join(
+        staging,
+        'licenses',
+        'agent-client-protocol-Apache-2.0.txt'
+      )
+    )
    copyLicense(
      join(projectRoot, 'node_modules', 'koffi', 'LICENSE.txt'),
      join(staging, 'licenses', 'koffi-MIT.txt')
@@ -935,12 +966,24 @@ function buildAgentBundle(options) {
      join(projectRoot, 'node_modules', 'zod', 'package.json'),
      'zod package metadata'
    )
+    const acpSdkPackage = readJson(
+      join(
+        projectRoot,
+        'node_modules',
+        '@agentclientprotocol',
+        'sdk',
+        'package.json'
+      ),
+      'ACP SDK package metadata'
+    )
    const manifest = createManifest(staging, {
      agentVersion: lock.agentVersion,
      nodeVersion: lock.node.version,
      zodVersion: zodPackage.version,
+      acpSdkVersion: acpSdkPackage.version,
      koffiVersion: koffi.version,
      koffiNativePackage: koffi.nativePackage,
+      platform,
      arch,
      protocol: lock.protocol,
      signingKeyId: signingIdentity.keyId
@@ -965,6 +1008,7 @@ function buildAgentBundle(options) {
        ? 'test'
        : 'production',
      expected: {
+        platform,
        agentVersion: lock.agentVersion,
        arch,
        protocol: lock.protocol
@@ -1034,6 +1078,7 @@ function verifyLockedBundle(bundleDirectory, arch, options = {}) {
      options.registry ?? readTrustedKeyRegistry(projectRoot),
    verificationEnvironment: options.verificationEnvironment ?? 'production',
    expected: {
+      platform: options.platform ?? 'linux',
      agentVersion: lock.agentVersion,
      arch,
      protocol: lock.protocol
@@ -1164,6 +1209,7 @@ function main(argv = process.argv.slice(2)) {
 }

 module.exports = {
+  koffiPayloadPaths,
  assertElfArchitecture,
  assertSafeManifestPath,
  buildAgentBundle,
@@ -32,6 +32,10 @@ const {
 } = 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(
@@ -46,6 +50,7 @@ const maximumPackageEntries = 50_002
 const maximumPackageEntryBytes = 384 * 1024 * 1024
 const maximumExpandedPackageBytes = 1024 * 1024 * 1024
 const maximumMetadataBytes = 1024 * 1024
+const maximumDescriptorBytes = 4 * 1024 * 1024
 const maximumCentralDirectoryBytes = 32 * 1024 * 1024
 const maximumCatalogEntries = 200
 const windowsReservedNamePattern =
@@ -136,7 +141,7 @@ function assertPackageDescriptor(descriptor) {
    !semanticVersionPattern.test(
      descriptor.minimumDesktopVersion ?? ''
    ) ||
-    descriptor.platform !== 'linux' ||
+    !supportedTarget(descriptor.platform, descriptor.architecture) ||
    !['x64', 'arm64'].includes(descriptor.architecture) ||
    typeof descriptor.signingKeyId !== 'string' ||
    !/^sha256:[a-f0-9]{64}$/u.test(
@@ -214,7 +219,7 @@ function readPackageMetadata(archivePath, registry) {
  )
  const expectedArchive =
    `goodbuddy-agent-${descriptor.version}` +
-    `-linux-${descriptor.architecture}.gbagent`
+    `-${descriptor.platform}-${descriptor.architecture}.gbagent`
  if (basename(archive) !== expectedArchive) {
    throw new Error(
      `Agent package archive must be named ${expectedArchive}`
@@ -408,7 +413,10 @@ function streamPackageMetadata(archivePath) {
        entry.name === 'agent-package.json' ||
        entry.name === 'agent-package.sig'
      const size = entry.recordEnd - entry.dataOffset
-      if (wanted && size > maximumMetadataBytes) {
+      const maximum = entry.name === 'agent-package.json'
+        ? maximumDescriptorBytes
+        : maximumMetadataBytes
+      if (wanted && size > maximum) {
        throw new Error('Agent package metadata exceeds its limit')
      }
      return {
@@ -566,11 +574,11 @@ function assertCatalog(catalog) {
      !semanticVersionPattern.test(
        entry.minimumDesktopVersion ?? ''
      ) ||
-      entry.platform !== 'linux' ||
+      !supportedTarget(entry.platform, entry.architecture) ||
      !['x64', 'arm64'].includes(entry.architecture) ||
      entry.archive !==
        `goodbuddy-agent-${entry.version}` +
-          `-linux-${entry.architecture}.gbagent` ||
+        `-${entry.platform}-${entry.architecture}.gbagent` ||
      !Number.isSafeInteger(entry.size) ||
      entry.size <= 0 ||
      !sha256Pattern.test(entry.sha256 ?? '') ||
@@ -600,7 +608,7 @@ function assertCatalog(catalog) {
      entry.remoteRuntime.protocol,
      'Remote Runtime protocol'
    )
-    const identity = `${entry.version}:${entry.architecture}`
+    const identity = `${entry.version}:${entry.platform}:${entry.architecture}`
    if (identities.has(identity)) {
      throw new Error('Agent catalog contains duplicate entries')
    }
@@ -698,7 +706,8 @@ function createCatalog(options) {
  }
  const packages = [
    readPackageMetadata(options.x64Package, registry),
-    readPackageMetadata(options.arm64Package, registry)
+    readPackageMetadata(options.arm64Package, registry),
+    ...(options.darwinArm64Package ? [readPackageMetadata(options.darwinArm64Package, registry)] : [])
  ]
  const [first, second] = packages
  const {
@@ -721,12 +730,26 @@ function createCatalog(options) {
      canonicalJson(secondRuntimeIdentity) ||
    new Set(packages.map(
      (metadata) => metadata.descriptor.architecture
-    )).size !== 2
+    ).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(
@@ -745,11 +768,11 @@ function createCatalog(options) {
  }
  const entries = new Map()
  for (const entry of previous?.entries ?? []) {
-    entries.set(`${entry.version}:${entry.architecture}`, entry)
+    entries.set(`${entry.version}:${entry.platform}:${entry.architecture}`, entry)
  }
  for (const metadata of packages) {
    const entry = catalogEntry(metadata)
-    const identity = `${entry.version}:${entry.architecture}`
+    const identity = `${entry.version}:${entry.platform}:${entry.architecture}`
    const existing = entries.get(identity)
    if (
      existing &&
@@ -764,6 +787,7 @@ function createCatalog(options) {
  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) {
@@ -813,6 +837,7 @@ function parseArguments(argv) {
      ![
        '--x64-package',
        '--arm64-package',
+        '--darwin-arm64-package',
        '--previous-catalog',
        '--previous-signature',
        '--catalog',
@@ -852,6 +877,9 @@ function parseArguments(argv) {
    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(
@@ -24,6 +24,7 @@ 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'

@@ -34,6 +35,7 @@ function parseArguments(argv) {
    if (
      ![
        '--arch',
+        '--platform',
        '--node-archive',
        '--opencode-archive',
        '--output-directory',
@@ -56,6 +58,8 @@ function parseArguments(argv) {
  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',
@@ -70,6 +74,7 @@ function parseArguments(argv) {
  }
  return {
    arch: options.arch,
+    platform,
    nodeArchive: resolve(options.nodearchive),
    opencodeArchive: resolve(options.opencodearchive),
    outputDirectory: resolve(options.outputdirectory),
@@ -77,6 +82,14 @@ function parseArguments(argv) {
  }
 }

+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 {
@@ -97,8 +110,12 @@ function ephemeralSigningIdentity() {

 async function buildCiAgentBundle(options) {
  const projectRoot = resolve(__dirname, '..')
-  const lock = readRuntimeLock(projectRoot)
-  const runtimeLock = readRemoteRuntimeLock(projectRoot)
+  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(
@@ -124,6 +141,8 @@ async function buildCiAgentBundle(options) {
      force: true
    })
    buildAgentBundle({
+      platform,
+      lock,
      projectRoot,
      arch: options.arch,
      runtimeArchive: options.nodeArchive,
@@ -132,6 +151,8 @@ async function buildCiAgentBundle(options) {
      testSigningIdentity: identity
    })
    const runtime = buildRuntimeBundle({
+      platform,
+      lock: runtimeLock,
      projectRoot,
      architecture: options.arch,
      runtimeArchive: options.opencodeArchive,
@@ -141,6 +162,7 @@ async function buildCiAgentBundle(options) {
    })
    const assemble = (archive) =>
      assembleAgentPackage({
+        platform,
        projectRoot,
        architecture: options.arch,
        minimumDesktopVersion:
@@ -181,7 +203,31 @@ async function buildCiAgentBundle(options) {
      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,
@@ -214,5 +260,6 @@ if (require.main === module) {

 module.exports = {
  buildCiAgentBundle,
-  parseArguments
+  parseArguments,
+  readCiLocks
 }
@@ -19,6 +19,7 @@ const {
 } = 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,
@@ -345,6 +346,8 @@ function createPackageArchive(
 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 ?? '') ||
@@ -386,6 +389,7 @@ function assembleAgentPackage(options) {
    options.agentBundle,
    architecture,
    {
+      platform,
      projectRoot,
      registry,
      lock: agentLock,
@@ -395,6 +399,7 @@ function assembleAgentPackage(options) {
    }
  )
  const runtime = verifyRuntimeBundle(options.runtimeBundle, {
+    platform,
    projectRoot,
    architecture,
    registry,
@@ -405,14 +410,14 @@ function assembleAgentPackage(options) {
  })
  const expectedArchiveName =
    `goodbuddy-agent-${agent.manifest.agentVersion}` +
-    `-linux-${architecture}.gbagent`
+    `-${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-linux-${architecture}-`)
+    join(tmpdir(), `goodbuddy-agent-package-${target}-`)
  )
  try {
    stagePackagePayload({
@@ -431,7 +436,7 @@ function assembleAgentPackage(options) {
      component: 'agent',
      version: agent.manifest.agentVersion,
      minimumDesktopVersion: options.minimumDesktopVersion,
-      platform: 'linux',
+      platform,
      architecture,
      signingKeyId: signingIdentity.keyId,
      agentProtocol: agent.manifest.protocol,
@@ -493,6 +498,7 @@ function buildAgentPackage(options) {
  )
  try {
    const agentBundle = buildAgentBundle({
+      platform: options.platform ?? 'linux',
      projectRoot,
      arch: options.architecture,
      runtimeArchive: options.nodeArchive,
@@ -504,6 +510,7 @@ function buildAgentPackage(options) {
        : { signingIdentity })
    })
    const runtime = buildRuntimeBundle({
+      platform: options.platform ?? 'linux',
      projectRoot,
      architecture: options.architecture,
      runtimeArchive: options.runtimeArchive,
@@ -544,6 +551,7 @@ function parseArguments(argv) {
    if (
      ![
        '--arch',
+        '--platform',
        '--minimum-desktop-version',
        '--node-archive',
        '--runtime-archive',
@@ -571,10 +579,12 @@ function parseArguments(argv) {
    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')
@@ -19,8 +19,8 @@ const manifestName = 'release-manifest.json'
 const targetDefinitions = [
  { platform: 'windows', arch: 'x64', formats: ['nsis', 'portable'] },
  { platform: 'windows', arch: 'arm64', formats: ['nsis', 'portable'] },
-  { platform: 'macos', arch: 'x64', formats: ['dmg', 'zip'] },
-  { platform: 'macos', arch: 'arm64', formats: ['dmg', 'zip'] },
+  { platform: 'macos', arch: 'x64', formats: ['dmg'] },
+  { platform: 'macos', arch: 'arm64', formats: ['dmg'] },
  { platform: 'linux', arch: 'x64', formats: ['AppImage', 'deb', 'rpm'] },
  { platform: 'linux', arch: 'arm64', formats: ['AppImage', 'deb', 'rpm'] }
 ]
@@ -141,6 +141,13 @@ function portableRequiredPaths(directory) {
      'opencode',
      'opencode.exe'
    ),
+    join(
+      directory,
+      'resources',
+      'runtimes',
+      'opencode',
+      'rg.exe'
+    ),
    join(
      directory,
      'resources',
@@ -336,7 +343,7 @@ function main() {
  const result = spawnSync(
    process.execPath,
    [
-      join(root, 'node_modules', 'electron-builder', 'cli.js'),
+      join(root, 'build', 'run-electron-builder.cjs'),
      '--dir',
      '--x64',
      `--config.directories.output=${stagingRoot}`,
@@ -42,6 +42,10 @@ const {
 const {
  readZipCentralDirectory
 } = require('./zip-central-directory.cjs')
+const {
+  verifyOpenCodeConfig,
+  verifyHarnessBundleImports
+} = require('./verify-desktop-runtimes.cjs')

 const root = join(__dirname, '..')
 const packageJson = JSON.parse(
@@ -88,9 +92,15 @@ 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/opencode/rg.exe',
+  'resources/licenses/vscode-ripgrep-MIT.txt',
+  'resources/runtimes/opencode-config/node_modules/@opencode-ai/plugin/package.json',
+  'resources/runtimes/opencode-config/node_modules/@opencode-ai/plugin/dist/index.js',
  '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'
 ]
@@ -120,11 +130,12 @@ const platformDefinitions = {
    supportedFormats: ['nsis', 'portable'],
    unpackedPattern: /^win(?:-.+)?-unpacked$/u,
    executable: [`${productName}.exe`],
-    runtimeExecutable: 'opencode.exe'
+    runtimeExecutable: 'opencode.exe',
+    ripgrepExecutable: 'rg.exe'
  },
  macos: {
    builderFlag: '--mac',
-    defaultFormats: ['dmg', 'zip'],
+    defaultFormats: ['dmg'],
    supportedFormats: ['dmg', 'zip'],
    unpackedPattern: /^mac(?:-.+)?$/u,
    executable: [
@@ -133,7 +144,8 @@ const platformDefinitions = {
      'MacOS',
      productName
    ],
-    runtimeExecutable: 'opencode'
+    runtimeExecutable: 'opencode',
+    ripgrepExecutable: 'rg'
  },
  linux: {
    builderFlag: '--linux',
@@ -141,7 +153,8 @@ const platformDefinitions = {
    supportedFormats: ['AppImage', 'deb', 'rpm'],
    unpackedPattern: /^linux(?:-.+)?-unpacked$/u,
    executable: [packageJson.name],
-    runtimeExecutable: 'opencode'
+    runtimeExecutable: 'opencode',
+    ripgrepExecutable: 'rg'
  }
 }
 const formatExtensions = {
@@ -346,7 +359,7 @@ 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,
@@ -818,6 +831,10 @@ function verifyHarnessPackage(
    join(unpackedRoot, ...harnessHostEntry.split('/')),
    'DeepSeek Harness 可执行 Host'
  )
+  verifyHarnessBundleImports(
+    readFileSync(join(unpackedRoot, ...harnessHostEntry.split('/')), 'utf8'),
+    harnessHostEntry
+  )
  const harnessLlmChunk = [...entries]
    .map((entry) => entry.slice(1).split(sep).join('/'))
    .find((entry) =>
@@ -866,6 +883,10 @@ function verifyHarnessPackage(
      join(unpackedRoot, ...chunkPath.split('/')),
      'DeepSeek Harness 可执行 module chunk'
    )
+    verifyHarnessBundleImports(
+      readFileSync(join(unpackedRoot, ...chunkPath.split('/')), 'utf8'),
+      chunkPath
+    )
  }
  for (const [packageName, expectedVersion] of Object.entries(
    harnessPackageVersions
@@ -894,6 +915,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
@@ -1050,9 +1075,23 @@ function verifyUnpackedOutput(directory, options) {
    'opencode',
    definition.runtimeExecutable
  )
+  const ripgrepExecutable = join(
+    resources,
+    'runtimes',
+    'opencode',
+    definition.ripgrepExecutable
+  )
  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 受信任签名密钥'
@@ -1066,6 +1105,11 @@ function verifyUnpackedOutput(directory, options) {
    'Remote Runtime 锁定清单'
  )
  assertFile(runtimeExecutable, 'OpenCode Runtime')
+  assertFile(ripgrepExecutable, 'ripgrep Runtime')
+  verifyOpenCodeConfig(
+    resources,
+    join(root, '.runtime-resources', 'opencode-config')
+  )
  assertFile(
    join(resources, 'runtimes', 'continue', 'dist', 'index.js'),
    'Continue Runtime'
@@ -1080,10 +1124,21 @@ 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, '应用主程序'],
-    [runtimeExecutable, 'OpenCode Runtime']
+    [runtimeExecutable, 'OpenCode Runtime'],
+    [ripgrepExecutable, 'ripgrep Runtime']
  ]) {
    const actualArchitecture = binaryArchitecture(filePath)
    if (actualArchitecture !== options.arch) {
@@ -1543,7 +1598,7 @@ function printHelp() {

 默认格式：
  windows: nsis, portable (ZIP)
-  macos:   dmg, zip
+  macos:   dmg
  linux:   AppImage, deb, rpm`)
 }

@@ -1605,6 +1660,16 @@ async function main(argv = process.argv.slice(2)) {
      stagingDirectory,
      options
    )
+    if (
+      process.env.GITHUB_ACTIONS === 'true' &&
+      options.platform === 'windows' &&
+      options.arch === 'x64'
+    ) {
+      await run(process.execPath, [
+        join(root, 'build', 'run-packaged-deepseek-harness-smoke.cjs'),
+        unpackedDirectory
+      ])
+    }
    if (
      options.platform === 'windows' &&
      options.formats.includes('portable')
@@ -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
+}
@@ -1,401 +0,0 @@
-const { existsSync, readFileSync, rmSync } = require('node:fs')
-const { gzipSync } = require('node:zlib')
-const { resolve } = require('node:path')
-
-// These are hard regression ceilings, not user-experience targets. In
-// particular, do not lazy-load one peer tab solely to stay below a ceiling.
-// The Settings ceiling is the validated 2026-08-23 production baseline
-// (648.78 kB raw / 97.79 kB gzip), rounded up with about 15% review headroom.
-const rendererBundleBudgets = Object.freeze({
-  initial: Object.freeze({ raw: 3_500_000, gzip: 720_000 }),
-  knowledge: Object.freeze({ raw: 330_000, gzip: 50_000 }),
-  graph: Object.freeze({ raw: 3_500_000, gzip: 720_000 }),
-  activity: Object.freeze({ raw: 55_000, gzip: 9_000 }),
-  magicNotes: Object.freeze({ raw: 630_000, gzip: 130_000 }),
-  settings: Object.freeze({ raw: 750_000, gzip: 115_000 })
-})
-
-function normalizePath(value) {
-  return value.replaceAll('\\', '/')
-}
-
-function findEntryKey(manifest) {
-  const entries = Object.entries(manifest).filter(
-    ([, item]) => item && item.isEntry
-  )
-  if (entries.length !== 1) {
-    throw new Error(
-      `Expected one renderer entry in the manifest, found ${entries.length}`
-    )
-  }
-  return entries[0][0]
-}
-
-function findSourceKey(manifest, sourceSuffix) {
-  const normalizedSuffix = normalizePath(sourceSuffix)
-  let matches = Object.entries(manifest).filter(([key, item]) => {
-    const source = normalizePath(item.src || key)
-    return source.endsWith(normalizedSuffix)
-  })
-  if (matches.length === 0) {
-    const sourceName = normalizedSuffix
-      .split('/')
-      .at(-1)
-      ?.replace(/\.[^.]+$/u, '')
-    matches = Object.entries(manifest).filter(
-      ([, item]) =>
-        item?.isDynamicEntry &&
-        item.name === sourceName
-    )
-  }
-  if (matches.length !== 1) {
-    throw new Error(
-      `Expected one manifest entry for ${sourceSuffix}, found ${matches.length}`
-    )
-  }
-  return matches[0][0]
-}
-
-function findModuleOwnerKeys(manifest, moduleManifest, pattern) {
-  const keysByFile = new Map(
-    Object.entries(manifest).map(([key, item]) => [item.file, key])
-  )
-  const keys = new Set()
-  for (const [file, modules] of Object.entries(moduleManifest)) {
-    if (modules.some((id) => pattern.test(normalizePath(id)))) {
-      const key = keysByFile.get(normalizePath(file))
-      if (!key) {
-        throw new Error(`Module manifest chunk is missing: ${file}`)
-      }
-      keys.add(key)
-    }
-  }
-  if (keys.size === 0) {
-    throw new Error(`No renderer chunk owns modules matching ${pattern}`)
-  }
-  return keys
-}
-
-function assertSafeModuleManifest(moduleManifest) {
-  for (const modules of Object.values(moduleManifest)) {
-    for (const id of modules) {
-      const normalized = normalizePath(id)
-      if (
-        normalized !== id ||
-        normalized.startsWith('/') ||
-        normalized.startsWith('../') ||
-        /[A-Za-z]:\//u.test(normalized) ||
-        normalized.includes('/Users/') ||
-        normalized.includes('/home/')
-      ) {
-        throw new Error(`Unsafe renderer module manifest path: ${id}`)
-      }
-    }
-  }
-}
-
-function collectSynchronousClosure(manifest, rootKey) {
-  if (!manifest[rootKey]) {
-    throw new Error(`Manifest entry is missing: ${rootKey}`)
-  }
-  const visited = new Set()
-  const pending = [rootKey]
-  while (pending.length > 0) {
-    const key = pending.pop()
-    if (visited.has(key)) {
-      continue
-    }
-    const item = manifest[key]
-    if (!item) {
-      throw new Error(`Manifest import is missing: ${key}`)
-    }
-    visited.add(key)
-    for (const imported of item.imports || []) {
-      pending.push(imported)
-    }
-  }
-  return visited
-}
-
-function collectAssetFiles(manifest, keys) {
-  const files = new Set()
-  for (const key of keys) {
-    const item = manifest[key]
-    if (!item) {
-      throw new Error(`Manifest entry is missing: ${key}`)
-    }
-    files.add(normalizePath(item.file))
-    for (const cssFile of item.css || []) {
-      files.add(normalizePath(cssFile))
-    }
-  }
-  return files
-}
-
-function measureFiles(files, readAsset, metricCache = new Map()) {
-  let raw = 0
-  let gzip = 0
-  const measuredFiles = [...files].sort()
-  for (const file of measuredFiles) {
-    let metrics = metricCache.get(file)
-    if (!metrics) {
-      const bytes = Buffer.from(readAsset(file))
-      metrics = {
-        raw: bytes.byteLength,
-        gzip: gzipSync(bytes).byteLength
-      }
-      metricCache.set(file, metrics)
-    }
-    raw += metrics.raw
-    gzip += metrics.gzip
-  }
-  return { raw, gzip, files: measuredFiles }
-}
-
-function withoutItems(keys, excluded) {
-  return new Set([...keys].filter((key) => !excluded.has(key)))
-}
-
-function describeEntry(
-  manifest,
-  key,
-  initialKeys,
-  initialFiles,
-  readAsset,
-  metricCache
-) {
-  const closureKeys = collectSynchronousClosure(manifest, key)
-  const closureFiles = collectAssetFiles(manifest, closureKeys)
-  const incrementalKeys = withoutItems(closureKeys, initialKeys)
-  const incrementalFiles = withoutItems(closureFiles, initialFiles)
-  const root = measureFiles(
-    collectAssetFiles(manifest, new Set([key])),
-    readAsset,
-    metricCache
-  )
-  return {
-    key,
-    file: manifest[key].file,
-    rootRaw: root.raw,
-    rootGzip: root.gzip,
-    closureKeys,
-    incrementalKeys,
-    ...measureFiles(incrementalFiles, readAsset, metricCache)
-  }
-}
-
-function assertDisjoint(description, keys, forbiddenKeys) {
-  const matches = [...forbiddenKeys].filter((key) => keys.has(key))
-  if (matches.length > 0) {
-    throw new Error(
-      `${description} synchronously includes ${matches.join(', ')}`
-    )
-  }
-}
-
-/**
- * @typedef {object} RendererAnalysisKeys
- * @property {string} initial
- * @property {string} knowledge
- * @property {string} graph
- * @property {string} activity
- * @property {string} magicNotes
- * @property {string} settings
- * @property {string[]} g6
- */
-
-/**
- * Analyzes one renderer manifest.
- *
- * `keys` is the authoritative set of discovered roots and module owners;
- * notably, `keys.g6` is always an array because G6 may span several chunks.
- *
- * @returns {{ keys: RendererAnalysisKeys, sections: Record<string, object> }}
- */
-function analyzeRendererManifest(manifest, readAsset, moduleManifest) {
-  assertSafeModuleManifest(moduleManifest)
-  const metricCache = new Map()
-  const keys = {
-    initial: findEntryKey(manifest),
-    knowledge: findSourceKey(manifest, 'KnowledgeWorkspace.tsx'),
-    graph: findSourceKey(manifest, 'KnowledgeGraphChart.tsx'),
-    activity: findSourceKey(manifest, 'ActivityPanel.tsx'),
-    magicNotes: findSourceKey(manifest, 'MagicNotesWorkspace.tsx'),
-    settings: findSourceKey(manifest, 'SettingsPanel.tsx')
-  }
-  const g6Keys = findModuleOwnerKeys(
-    manifest,
-    moduleManifest,
-    /(?:^|\/)node_modules\/@antv\/g6\//u
-  )
-  const initialKeys = collectSynchronousClosure(manifest, keys.initial)
-  const initialFiles = collectAssetFiles(manifest, initialKeys)
-  const initialRoot = measureFiles(
-    collectAssetFiles(manifest, new Set([keys.initial])),
-    readAsset,
-    metricCache
-  )
-  const initial = {
-    key: keys.initial,
-    file: manifest[keys.initial].file,
-    rootRaw: initialRoot.raw,
-    rootGzip: initialRoot.gzip,
-    closureKeys: initialKeys,
-    incrementalKeys: initialKeys,
-    ...measureFiles(initialFiles, readAsset, metricCache)
-  }
-  const sections = {
-    initial,
-    knowledge: describeEntry(
-      manifest,
-      keys.knowledge,
-      initialKeys,
-      initialFiles,
-      readAsset,
-      metricCache
-    ),
-    graph: describeEntry(
-      manifest,
-      keys.graph,
-      initialKeys,
-      initialFiles,
-      readAsset,
-      metricCache
-    ),
-    activity: describeEntry(
-      manifest,
-      keys.activity,
-      initialKeys,
-      initialFiles,
-      readAsset,
-      metricCache
-    ),
-    magicNotes: describeEntry(
-      manifest,
-      keys.magicNotes,
-      initialKeys,
-      initialFiles,
-      readAsset,
-      metricCache
-    ),
-    settings: describeEntry(
-      manifest,
-      keys.settings,
-      initialKeys,
-      initialFiles,
-      readAsset,
-      metricCache
-    )
-  }
-
-  assertDisjoint(
-    'The renderer entry',
-    initialKeys,
-    new Set([keys.knowledge, keys.graph, keys.activity, ...g6Keys])
-  )
-  assertDisjoint(
-    'The Knowledge shell',
-    sections.knowledge.closureKeys,
-    new Set([keys.graph, ...g6Keys])
-  )
-  for (const g6Key of g6Keys) {
-    if (!sections.graph.closureKeys.has(g6Key)) {
-      throw new Error('The graph chunk no longer synchronously owns G6')
-    }
-  }
-
-  return { keys: { ...keys, g6: [...g6Keys] }, sections }
-}
-
-function checkBudgets(analysis, budgets = rendererBundleBudgets) {
-  const failures = []
-  for (const [name, budget] of Object.entries(budgets)) {
-    const section = analysis.sections[name]
-    if (!section) {
-      failures.push(`Unknown budget section: ${name}`)
-      continue
-    }
-    for (const metric of ['raw', 'gzip']) {
-      if (section[metric] > budget[metric]) {
-        failures.push(
-          `${name} ${metric} ${section[metric]} exceeds ${budget[metric]}`
-        )
-      }
-    }
-  }
-  if (failures.length > 0) {
-    throw new Error(`Renderer bundle budget failed:\n- ${failures.join('\n- ')}`)
-  }
-}
-
-function formatBytes(bytes) {
-  return `${(bytes / 1000).toFixed(2)} kB`
-}
-
-function formatReport(analysis) {
-  return [
-    'Renderer bundle budget:',
-    ...Object.entries(analysis.sections).map(
-      ([name, section]) =>
-        `- ${name}: root ${formatBytes(section.rootRaw)} raw / ` +
-        `${formatBytes(section.rootGzip)} gzip, ` +
-        `incremental closure ${formatBytes(section.raw)} raw / ` +
-        `${formatBytes(section.gzip)} gzip`
-    )
-  ].join('\n')
-}
-
-function checkRendererBundle(root = process.cwd()) {
-  const rendererRoot = resolve(root, 'out', 'renderer')
-  const manifestPath = resolve(rendererRoot, '.vite', 'manifest.json')
-  const moduleManifestPath = resolve(
-    rendererRoot,
-    '.vite',
-    'module-manifest.json'
-  )
-  if (!existsSync(manifestPath)) {
-    throw new Error(`Renderer manifest not found: ${manifestPath}`)
-  }
-  if (!existsSync(moduleManifestPath)) {
-    throw new Error(
-      `Renderer module manifest not found: ${moduleManifestPath}`
-    )
-  }
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-  const moduleManifest = JSON.parse(
-    readFileSync(moduleManifestPath, 'utf8')
-  )
-  const analysis = analyzeRendererManifest(
-    manifest,
-    (file) => readFileSync(resolve(rendererRoot, file)),
-    moduleManifest
-  )
-  checkBudgets(analysis)
-  rmSync(moduleManifestPath)
-  return analysis
-}
-
-module.exports = {
-  analyzeRendererManifest,
-  checkBudgets,
-  checkRendererBundle,
-  collectAssetFiles,
-  collectSynchronousClosure,
-  findEntryKey,
-  findModuleOwnerKeys,
-  findSourceKey,
-  formatReport,
-  assertSafeModuleManifest,
-  measureFiles,
-  rendererBundleBudgets
-}
-
-if (require.main === module) {
-  try {
-    const analysis = checkRendererBundle()
-    console.log(formatReport(analysis))
-  } catch (error) {
-    console.error(error instanceof Error ? error.message : String(error))
-    process.exitCode = 1
-  }
-}
@@ -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.8',
+      requestHeaders: {},
+      harnessVersion: '0.1.2-rc.1',
      credentialRefs: ['GOODBUDDY_HARNESS_MODEL_API_KEY'],
      skillPackages: [],
      extensionPackages: [],
@@ -300,7 +300,10 @@ assert_loongarch_elf \
 assert_loongarch_elf \
  "${verify_root}/opt/${application_directory}/resources/app/${koffi_binding#${app_root}/}"

-sha256sum "${artifact}" > "${artifact_root}/SHA256SUMS"
+(
+  cd "${artifact_root}"
+  sha256sum "${artifact_name}" > SHA256SUMS
+)
 cat > "${artifact_root}/preview-manifest.json" <<EOF
 {
  "formatVersion": 1,
@@ -0,0 +1,33 @@
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+
+function npmInvocation(projectDir, environment = process.env) {
+  const npmCli = environment.npm_execpath;
+  if (npmCli) {
+    return {
+      command: process.execPath,
+      prefixArgs: [npmCli],
+    };
+  }
+
+  const bundledNpmCli = join(
+    projectDir,
+    "node_modules",
+    "npm",
+    "bin",
+    "npm-cli.js",
+  );
+  if (existsSync(bundledNpmCli)) {
+    return {
+      command: process.execPath,
+      prefixArgs: [bundledNpmCli],
+    };
+  }
+
+  return {
+    command: process.platform === "win32" ? "npm.cmd" : "npm",
+    prefixArgs: [],
+  };
+}
+
+module.exports = { npmInvocation };
@@ -0,0 +1,110 @@
+const { existsSync } = require("node:fs");
+const {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} = require("node:fs");
+const { join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { npmInvocation } = require("./npm-invocation.cjs");
+
+const opencodeVersion = "1.18.29";
+const opencodePluginPackage = "@opencode-ai/plugin";
+
+function prepareBundledOpenCodeConfig(projectDir) {
+  const targetDirectory = join(
+    projectDir,
+    ".runtime-resources",
+    "opencode-config",
+  );
+  try {
+    const installed = JSON.parse(
+      readFileSync(
+        join(
+          targetDirectory,
+          "node_modules",
+          "@opencode-ai",
+          "plugin",
+          "package.json",
+        ),
+        "utf8",
+      ),
+    );
+    if (installed.version === opencodeVersion) {
+      return targetDirectory;
+    }
+  } catch {
+    // Rebuild an incomplete or stale offline config template.
+  }
+
+  const stagingDirectory = `${targetDirectory}.staging-${process.pid}`;
+  rmSync(stagingDirectory, { recursive: true, force: true });
+  mkdirSync(stagingDirectory, { recursive: true });
+  try {
+    writeFileSync(
+      join(stagingDirectory, "package.json"),
+      `${JSON.stringify(
+        {
+          private: true,
+          dependencies: {
+            [opencodePluginPackage]: opencodeVersion,
+          },
+        },
+        null,
+        2,
+      )}\n`,
+      "utf8",
+    );
+    writeFileSync(join(stagingDirectory, ".gitignore"), "node_modules\n");
+    const npm = npmInvocation(projectDir);
+    const environment = { ...process.env };
+    delete environment.NODE_TLS_REJECT_UNAUTHORIZED;
+    const result = spawnSync(
+      npm.command,
+      [
+        ...npm.prefixArgs,
+        "install",
+        "--ignore-scripts",
+        "--bin-links=false",
+        "--omit=dev",
+        "--omit=optional",
+        "--no-audit",
+        "--no-fund",
+        "--save-exact",
+      ],
+      {
+        cwd: stagingDirectory,
+        encoding: "utf8",
+        env: environment,
+        maxBuffer: 16 * 1024 * 1024,
+        shell: false,
+        windowsHide: true,
+      },
+    );
+    if (result.status !== 0) {
+      throw new Error(
+        `Unable to prepare bundled OpenCode config: ${
+          result.error?.message ||
+          result.stderr ||
+          result.stdout ||
+          `npm exited with ${result.status}`
+        }`,
+      );
+    }
+    rmSync(targetDirectory, { recursive: true, force: true });
+    mkdirSync(join(targetDirectory, ".."), { recursive: true });
+    renameSync(stagingDirectory, targetDirectory);
+    return targetDirectory;
+  } finally {
+    if (existsSync(stagingDirectory)) {
+      rmSync(stagingDirectory, { recursive: true, force: true });
+    }
+  }
+}
+
+module.exports = {
+  opencodeVersion,
+  prepareBundledOpenCodeConfig,
+};
@@ -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
  })
@@ -0,0 +1,31 @@
+const { spawnSync } = require('node:child_process')
+const { rmSync } = require('node:fs')
+const { tmpdir } = require('node:os')
+const { join } = require('node:path')
+const { buildSync } = require('esbuild')
+
+const output = join(tmpdir(), `goodbuddy-browser-tabs-e2e-${process.pid}.cjs`)
+
+try {
+  buildSync({
+    entryPoints: [join(process.cwd(), 'tests', 'browser-tabs-electron-e2e.ts')],
+    outfile: output,
+    bundle: true,
+    platform: 'node',
+    format: 'cjs',
+    target: 'node22',
+    external: ['electron']
+  })
+  const environment = { ...process.env }
+  delete environment.ELECTRON_RUN_AS_NODE
+  const result = spawnSync(require('electron'), [output], {
+    cwd: process.cwd(),
+    env: environment,
+    stdio: 'inherit',
+    timeout: 120_000
+  })
+  if (result.error) throw result.error
+  process.exitCode = result.status ?? 1
+} finally {
+  rmSync(output, { force: true })
+}
@@ -88,7 +88,7 @@ async function main() {
    `${JSON.stringify(
      {
        name: '@deepseek-ai/dsh-llm',
-        version: '0.1.0-rc.8',
+        version: '0.1.2-rc.1',
        private: true,
        type: 'module'
      },
@@ -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
+}
@@ -13,6 +13,7 @@ const {
 const { statSync } = require('node:fs')
 const { tmpdir } = require('node:os')
 const { delimiter, join, resolve } = require('node:path')
+const { pathToFileURL } = require('node:url')

 const unpackedPath = process.argv[2]
  ? resolve(process.argv[2])
@@ -109,6 +110,20 @@ async function main() {
    const npmProject = join(root, 'npm-project')
    const npmFixture = join(root, 'npm-fixture')
    await mkdir(project, { recursive: true })
+    const pluginUrl = pathToFileURL(join(
+      unpackedPath, 'resources', 'runtimes', 'opencode-config',
+      'node_modules', '@opencode-ai', 'plugin', 'dist', 'index.js'
+    )).href
+    const importedPlugin = await run(
+      executable,
+      ['--input-type=module', '--eval', `await import(${JSON.stringify(pluginUrl)})`],
+      { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+      root
+    )
+    if (importedPlugin.exitCode !== 0 || importedPlugin.signal) {
+      throw new Error(`Packaged OpenCode plugin import failed: ${importedPlugin.output.trim()}`)
+    }
+    console.log('Packaged OpenCode offline plugin import: ready')

    await copyFile(
      resolve('build/deepseek-harness-utility-smoke.cjs'),
@@ -147,7 +162,7 @@ async function main() {
    )

    const packageArguments = [
-      resolve('node_modules/electron-builder/cli.js'),
+      resolve('build/run-electron-builder.cjs'),
      '--projectDir',
      project,
      '--win',
@@ -1,4 +1,4 @@
-const { createHash } = require('node:crypto')
+const { createHash } = require("node:crypto");
 const {
  chmod,
  mkdir,
@@ -6,101 +6,84 @@ const {
  rename,
  rm,
  stat,
-  writeFile
-} = require('node:fs/promises')
-const { existsSync } = require('node:fs')
-const { join } = require('node:path')
-const { spawnSync } = require('node:child_process')
-const tar = require('tar')
-const { sha256File } = require('./file-hash.cjs')
+  writeFile,
+} = require("node:fs/promises");
+const { existsSync } = require("node:fs");
+const { join } = require("node:path");
+const { spawnSync } = require("node:child_process");
+const tar = require("tar");
+const { sha256File } = require("./file-hash.cjs");
+const {
+  opencodeVersion,
+  prepareBundledOpenCodeConfig,
+} = require("./opencode-config.cjs");
+const { npmInvocation } = require("./npm-invocation.cjs");

-const opencodeVersion = '1.18.9'
 const architectureNames = {
-  1: 'x64',
-  3: 'arm64'
-}
+  1: "x64",
+  3: "arm64",
+};
 const platformNames = {
-  darwin: 'darwin',
-  linux: 'linux',
-  win32: 'windows'
-}
+  darwin: "darwin",
+  linux: "linux",
+  win32: "windows",
+};

 function sha512Integrity(contents) {
-  return `sha512-${createHash('sha512').update(contents).digest('base64')}`
+  return `sha512-${createHash("sha512").update(contents).digest("base64")}`;
 }

-async function lockedIntegrity(projectDir, packageName) {
+async function lockedIntegrity(projectDir, packageName, version) {
  const lock = JSON.parse(
-    await readFile(join(projectDir, 'package-lock.json'), 'utf8')
-  )
-  const entry = lock.packages?.[`node_modules/${packageName}`]
+    await readFile(join(projectDir, "package-lock.json"), "utf8"),
+  );
+  const entry = lock.packages?.[`node_modules/${packageName}`];
  if (
-    entry?.version !== opencodeVersion ||
-    typeof entry.integrity !== 'string'
+    entry?.version !== version ||
+    typeof entry.integrity !== "string"
  ) {
    throw new Error(
-      `Missing locked ${packageName}@${opencodeVersion} integrity`
-    )
+      `Missing locked ${packageName}@${version} integrity`,
+    );
  }
-  return entry.integrity
+  return entry.integrity;
 }

-function npmInvocation() {
-  const npmCli = process.env.npm_execpath
-  if (npmCli) {
-    return {
-      command: process.execPath,
-      prefixArgs: [npmCli]
-    }
-  }
-  if (process.platform === 'win32') {
-    throw new Error('npm_execpath is required to prepare bundled runtimes')
-  }
-  return {
-    command: 'npm',
-    prefixArgs: []
-  }
-}
-
-async function downloadPackage(projectDir, packageName, integrity) {
-  const cacheDirectory = join(
-    projectDir,
-    '.runtime-resources',
-    'cache'
-  )
-  await mkdir(cacheDirectory, { recursive: true })
+async function downloadPackage(projectDir, packageName, version, integrity) {
+  const cacheDirectory = join(projectDir, ".runtime-resources", "cache");
+  await mkdir(cacheDirectory, { recursive: true });
  const archivePath = join(
    cacheDirectory,
-    `${packageName}-${opencodeVersion}.tgz`
-  )
+    `${packageName.replaceAll("/", "-").replaceAll("@", "")}-${version}.tgz`,
+  );
  if (existsSync(archivePath)) {
-    const cached = await readFile(archivePath)
+    const cached = await readFile(archivePath);
    if (sha512Integrity(cached) === integrity) {
-      return archivePath
+      return archivePath;
    }
-    await rm(archivePath, { force: true })
+    await rm(archivePath, { force: true });
  }

-  const npm = npmInvocation()
+  const npm = npmInvocation(projectDir);
  const result = spawnSync(
    npm.command,
    [
      ...npm.prefixArgs,
-      'pack',
-      `${packageName}@${opencodeVersion}`,
-      '--ignore-scripts',
-      '--json',
-      '--pack-destination',
-      cacheDirectory
+      "pack",
+      `${packageName}@${version}`,
+      "--ignore-scripts",
+      "--json",
+      "--pack-destination",
+      cacheDirectory,
    ],
    {
      cwd: projectDir,
-      encoding: 'utf8',
+      encoding: "utf8",
      maxBuffer: 16 * 1024 * 1024,
      shell: false,
-      windowsHide: true
-    }
-  )
+      windowsHide: true,
+    },
+  );
  if (result.status !== 0) {
    throw new Error(
      `Unable to fetch ${packageName}: ${
@@ -108,81 +91,150 @@ async function downloadPackage(projectDir, packageName, integrity) {
        result.stderr ||
        result.stdout ||
        `npm exited with ${result.status}`
-      }`
-    )
+      }`,
+    );
  }
-  const output = JSON.parse(result.stdout)
-  const downloadedPath = join(cacheDirectory, output[0].filename)
-  const contents = await readFile(downloadedPath)
+  const output = JSON.parse(result.stdout);
+  const downloadedPath = join(cacheDirectory, output[0].filename);
+  const contents = await readFile(downloadedPath);
  if (sha512Integrity(contents) !== integrity) {
-    await rm(downloadedPath, { force: true })
-    throw new Error(`Integrity verification failed for ${packageName}`)
+    await rm(downloadedPath, { force: true });
+    throw new Error(`Integrity verification failed for ${packageName}`);
  }
  if (downloadedPath !== archivePath) {
-    await rm(archivePath, { force: true })
-    await rename(downloadedPath, archivePath)
+    await rm(archivePath, { force: true });
+    await rename(downloadedPath, archivePath);
  }
-  return archivePath
+  return archivePath;
 }

-module.exports = async function prepareBundledRuntimes(context) {
-  const platform = context.electronPlatformName
-  const architecture = architectureNames[context.arch]
-  const packagePlatform = platformNames[platform]
-  if (!architecture || !packagePlatform) {
-    throw new Error(
-      `Bundled OpenCode does not support ${platform}/${context.arch}`
-    )
-  }
-
-  const suffix =
-    architecture === 'x64' ? `${architecture}-baseline` : architecture
-  const packageName = `opencode-${packagePlatform}-${suffix}`
-  const projectDir = context.packager.projectDir
-  const projectPackage = JSON.parse(
-    await readFile(join(projectDir, 'package.json'), 'utf8')
-  )
-  await writeFile(
-    join(projectDir, 'out', 'main', 'package.json'),
-    `${JSON.stringify(
-      {
-        name: '@deepseek-ai/dsh-llm',
-        version:
-          projectPackage.dependencies['@deepseek-ai/dsh-llm'],
-        private: true,
-        type: 'module'
-      },
-      null,
-      2
-    )}\n`,
-    'utf8'
-  )
-  const integrity = await lockedIntegrity(projectDir, packageName)
-  const targetDirectory = join(
-    projectDir,
-    '.runtime-resources',
-    architecture
-  )
-  const readyPath = join(targetDirectory, '.ready.json')
-  const executable = platform === 'win32' ? 'opencode.exe' : 'opencode'
-  const preparedPath = join(targetDirectory, executable)
-  const identity = {
-    packageName,
-    version: opencodeVersion,
-    integrity
-  }
+async function prepareRipgrep(
+  projectDir,
+  targetDirectory,
+  platform,
+  architecture,
+  version,
+) {
+  const packageName = `@vscode/ripgrep-${platform}-${architecture}`;
+  const integrity = await lockedIntegrity(projectDir, packageName, version);
+  const executable = platform === "win32" ? "rg.exe" : "rg";
+  const preparedPath = join(targetDirectory, executable);
+  const readyPath = join(targetDirectory, ".ripgrep-ready.json");
+  const identity = { packageName, version, integrity };
  try {
-    const ready = JSON.parse(await readFile(readyPath, 'utf8'))
+    const ready = JSON.parse(await readFile(readyPath, "utf8"));
    if (
      ready.packageName === identity.packageName &&
      ready.version === identity.version &&
      ready.integrity === identity.integrity &&
-      typeof ready.executableSha256 === 'string' &&
-      (platform === 'win32' ||
+      typeof ready.executableSha256 === "string" &&
+      (platform === "win32" || ((await stat(preparedPath)).mode & 0o111) !== 0) &&
+      (await sha256File(preparedPath)) === ready.executableSha256
+    ) {
+      return;
+    }
+  } catch {
+    // Rebuild an incomplete or stale ripgrep cache.
+  }
+
+  const archivePath = await downloadPackage(
+    projectDir,
+    packageName,
+    version,
+    integrity,
+  );
+  const stagingDirectory = `${targetDirectory}.ripgrep-staging-${process.pid}`;
+  await rm(stagingDirectory, { recursive: true, force: true });
+  await mkdir(stagingDirectory, { recursive: true });
+  try {
+    await tar.x({
+      file: archivePath,
+      cwd: stagingDirectory,
+      strip: 1,
+    });
+    const sourcePath = join(stagingDirectory, "bin", executable);
+    const executableSha256 = await sha256File(sourcePath);
+    if (platform !== "win32") {
+      await chmod(sourcePath, 0o755);
+    }
+    await mkdir(targetDirectory, { recursive: true });
+    await rm(preparedPath, { force: true });
+    await rename(sourcePath, preparedPath);
+    await writeFile(
+      readyPath,
+      JSON.stringify({ ...identity, executableSha256 }),
+      "utf8",
+    );
+  } finally {
+    await rm(stagingDirectory, { recursive: true, force: true });
+  }
+}
+
+module.exports = async function prepareBundledRuntimes(context) {
+  const platform = context.electronPlatformName;
+  const architecture = architectureNames[context.arch];
+  const packagePlatform = platformNames[platform];
+  if (!architecture || !packagePlatform) {
+    throw new Error(
+      `Bundled OpenCode does not support ${platform}/${context.arch}`,
+    );
+  }
+
+  const suffix =
+    architecture === "x64" ? `${architecture}-baseline` : architecture;
+  const packageName = `opencode-${packagePlatform}-${suffix}`;
+  const projectDir = context.packager.projectDir;
+  await prepareBundledOpenCodeConfig(projectDir);
+  const projectPackage = JSON.parse(
+    await readFile(join(projectDir, "package.json"), "utf8"),
+  );
+  const ripgrepVersion = projectPackage.dependencies["@vscode/ripgrep"];
+  if (typeof ripgrepVersion !== "string" || !/^\d+\.\d+\.\d+$/u.test(ripgrepVersion)) {
+    throw new Error("Missing exact @vscode/ripgrep dependency version");
+  }
+  await writeFile(
+    join(projectDir, "out", "main", "package.json"),
+    `${JSON.stringify(
+      {
+        name: "@deepseek-ai/dsh-llm",
+        version: projectPackage.dependencies["@deepseek-ai/dsh-llm"],
+        private: true,
+        type: "module",
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  const integrity = await lockedIntegrity(projectDir, packageName, opencodeVersion);
+  const targetDirectory = join(projectDir, ".runtime-resources", architecture);
+  const readyPath = join(targetDirectory, ".ready.json");
+  const executable = platform === "win32" ? "opencode.exe" : "opencode";
+  const preparedPath = join(targetDirectory, executable);
+  const identity = {
+    packageName,
+    version: opencodeVersion,
+    integrity,
+  };
+  try {
+    const ready = JSON.parse(await readFile(readyPath, "utf8"));
+    if (
+      ready.packageName === identity.packageName &&
+      ready.version === identity.version &&
+      ready.integrity === identity.integrity &&
+      typeof ready.executableSha256 === "string" &&
+      (platform === "win32" ||
        ((await stat(preparedPath)).mode & 0o111) !== 0) &&
      (await sha256File(preparedPath)) === ready.executableSha256
    ) {
-      return
+      await prepareRipgrep(
+        projectDir,
+        targetDirectory,
+        platform,
+        architecture,
+        ripgrepVersion,
+      );
+      return;
    }
  } catch {
    // Rebuild an incomplete or stale runtime cache.
@@ -191,32 +243,40 @@ module.exports = async function prepareBundledRuntimes(context) {
  const archivePath = await downloadPackage(
    projectDir,
    packageName,
-    integrity
-  )
-  const stagingDirectory = `${targetDirectory}.staging-${process.pid}`
-  await rm(stagingDirectory, { recursive: true, force: true })
-  await mkdir(stagingDirectory, { recursive: true })
+    opencodeVersion,
+    integrity,
+  );
+  const stagingDirectory = `${targetDirectory}.staging-${process.pid}`;
+  await rm(stagingDirectory, { recursive: true, force: true });
+  await mkdir(stagingDirectory, { recursive: true });
  try {
    await tar.x({
      file: archivePath,
      cwd: stagingDirectory,
-      strip: 1
-    })
-    const sourcePath = join(stagingDirectory, 'bin', executable)
-    const stagingExecutable = join(stagingDirectory, executable)
-    await rename(sourcePath, stagingExecutable)
-    if (platform !== 'win32') {
-      await chmod(stagingExecutable, 0o755)
+      strip: 1,
+    });
+    const sourcePath = join(stagingDirectory, "bin", executable);
+    const stagingExecutable = join(stagingDirectory, executable);
+    await rename(sourcePath, stagingExecutable);
+    if (platform !== "win32") {
+      await chmod(stagingExecutable, 0o755);
    }
-    const executableSha256 = await sha256File(stagingExecutable)
+    const executableSha256 = await sha256File(stagingExecutable);
    await writeFile(
-      join(stagingDirectory, '.ready.json'),
+      join(stagingDirectory, ".ready.json"),
      JSON.stringify({ ...identity, executableSha256 }),
-      'utf8'
-    )
-    await rm(targetDirectory, { recursive: true, force: true })
-    await rename(stagingDirectory, targetDirectory)
+      "utf8",
+    );
+    await rm(targetDirectory, { recursive: true, force: true });
+    await rename(stagingDirectory, targetDirectory);
  } finally {
-    await rm(stagingDirectory, { recursive: true, force: true })
+    await rm(stagingDirectory, { recursive: true, force: true });
  }
-}
+  await prepareRipgrep(
+    projectDir,
+    targetDirectory,
+    platform,
+    architecture,
+    ripgrepVersion,
+  );
+};
@@ -0,0 +1,39 @@
+const { readdirSync, readFileSync, statSync } = require('node:fs')
+const { join, relative } = require('node:path')
+const { opencodeVersion } = require('./opencode-config.cjs')
+
+function verifyOpenCodeConfig(resources, source) {
+  const destination = join(resources, 'runtimes', 'opencode-config')
+  const manifestPath = join(destination, 'node_modules', '@opencode-ai', 'plugin', 'package.json')
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  if (manifest.name !== '@opencode-ai/plugin' || manifest.version !== opencodeVersion) {
+    throw new Error('Packaged OpenCode plugin version is invalid')
+  }
+  const pending = [source]
+  let files = 0
+  while (pending.length > 0) {
+    const directory = pending.pop()
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const file = join(directory, entry.name)
+      if (entry.isDirectory()) {
+        pending.push(file)
+      } else if (entry.isFile()) {
+        const target = join(destination, relative(source, file))
+        if (!statSync(target, { throwIfNoEntry: false })?.isFile() ||
+            !readFileSync(target).equals(readFileSync(file))) {
+          throw new Error(`Packaged OpenCode dependency is missing or changed: ${relative(source, file)}`)
+        }
+        files++
+      }
+    }
+  }
+  return files
+}
+
+function verifyHarnessBundleImports(source, name) {
+  if (/(?:\bfrom\s*|\bimport\s*(?:\(\s*)?|\brequire\s*\(\s*)["']@deepseek-ai\//u.test(source)) {
+    throw new Error(`DeepSeek Harness bundle contains an external DeepSeek dependency: ${name}`)
+  }
+}
+
+module.exports = { verifyOpenCodeConfig, verifyHarnessBundleImports }
@@ -1,54 +0,0 @@
-# GoodBuddy 文档导航
-
-GoodBuddy 文档按“文档类型 → 功能域”组织。新增文档应先选择类型，再放入对应功能目录，
-避免继续把所有设计平铺到单一 `features` 目录。
-
-## 产品需求
-
-| 功能域 | 入口 |
-| --- | --- |
-| Task 与 Job | [Task 与 Job 总览](./prd/task-and-job/README.md) |
-| Smart Heartbeat | [智能心跳 PRD](./prd/smart-heartbeat/smart-heartbeat-prd.md) |
-| 助手工作栏 | [通用助手工作栏与执行空间 PRD](./prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
-| 会话监督 | [会话监督 PRD](./prd/supervision/conversation-supervision-prd.md) |
-| 记忆 | [分区记忆 PRD](./prd/memory/partitioned-memory-prd.md) |
-| 并行实验 | [并行实验工作台 PRD](./prd/experiments/parallel-experiments-prd.md) |
-| 持续学习 | [持续学习与评估门 PRD](./prd/learning/continuous-learning-prd.md) |
-| 知识库 | [知识库检索与分块增强 PRD](./prd/knowledge/knowledge-rag-enhancement-prd.md) |
-| 文档处理 | [文档解析与本地 OCR](./prd/document-processing/document-extraction-and-local-ocr.md) |
-| 消息通道 | [微信 ClawBot 通道 PRD](./prd/channels/wechat-clawbot-channel-project-prd.md) |
-
-## Task 与 Job 文档
-
- [统一领域模型](./prd/task-and-job/task-and-job-model.md)
- [Task Center](./prd/task-and-job/task-center-prd.md)
- [Scheduled Task](./prd/task-and-job/scheduled-task-prd.md)
- [Goal Task](./prd/task-and-job/goal-task-prd.md)
- [Job 与 Subjob](./prd/task-and-job/job-and-subjob-prd.md)
-
-## 跨功能文档
-
- [自动化平台架构](./architecture/automation-platform-architecture.md)
- [平台功能页签与模型下载源设计](./architecture/model-download-source-design.md)
- [本地文本向量模型与连接设计](./architecture/local-text-embedding-model-design.md)
- [全双工实时语音交互设计](./architecture/full-duplex-voice-design.md)
- [DeepSeek Harness Runtime 设计](./architecture/deepseek-harness-runtime-design.md)
- [应用内反馈系统设计与对接](./architecture/in-app-feedback-integration-design.md)
- [SSH 远程主机与 GoodBuddy Agent 稳定终态设计](./architecture/remote-host-and-goodbuddy-agent-design.md)
- [跨平台助手产品设计](./design/cross-platform-assistant-product-design.md)
- [长期助手路线图](./roadmap/long-term-assistant-roadmap.md)
- [电脑控制实施状态](./status/computer-control-implementation-status.md)
- [知识检索评估](./quality/knowledge-retrieval-evaluation.md)
- [GoodBuddy 龙芯（LoongArch）预览版构建与功能列表](./development/loongarch-preview-build.md)
- [统一界面设计系统](../UI-DESIGN.md)
-
-## 目录规则
-
-1. PRD 放在 `docs/prd/<功能域>/`。
-2. 跨功能技术总纲放在 `docs/architecture/`。
-3. 产品级设计放在 `docs/design/`，路线图和实施状态分别放在 `roadmap`、`status`。
-4. 测试方法、评估协议和质量报告放在 `docs/quality/`。
-5. 开发环境、实验性构建和移植说明放在 `docs/development/`。
-6. 一个概念只能有一份权威定义；其他文档链接到它，不复制另一套术语。
-7. Task、Job、Run、Subagent 和 Conversation 的含义以
-   [Task 与 Job 统一领域模型](./prd/task-and-job/task-and-job-model.md) 为准。
@@ -9,7 +9,7 @@
 | 日期 | 2026-08-19 |
 | 适用产品 | GoodBuddy 桌面端 |
 | 文档角色 | Task/Job、调度、目标、并行实验、会话监督、分区记忆与持续学习的总纲 |
-| 领域模型 | [Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md) |
+| 领域模型 | [Task 与 Job 统一领域模型](../features/task-and-job/task-and-job-model.md) |

 ## 1. 背景

@@ -37,11 +37,11 @@ GoodBuddy 当前已经具备若干长期助手能力，但它们仍是彼此分

 ## 2. 核心产品判断

-### 2.1 智能心跳保持独立，未来分区记忆另行设计
+### 2.1 智能心跳保持独立，分区记忆协同另行设计

 当前智能心跳继续承担周期回顾、报告和建议，并支持 Global 或指定 Project 范围。它不是
-Task、通用调度器或后台 Agent，也不进入统一 `AutomationPlan.kind`。未来分区记忆的
-数据、状态、唤起和页面需要独立设计，不能从当前方向直接推导。
+Task、通用调度器或后台 Agent，也不进入统一 `AutomationPlan.kind`。按分区回顾、候选生成
+以及时间/内部事件唤起需要独立设计，不能从当前心跳行为直接推导，也不创建平行记忆类型。

 - Scheduled Task 解决“何时在一个 Task 中执行新的 Job”。
 - Goal Task 解决“围绕结果在同一 Task 中持续规划和推进”。
@@ -293,11 +293,14 @@ Runtime 边界完成，用户可见结果通过所属 Task 汇入关联 Conversa
 - 普通消息在发送时冻结 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 活动锁。
+  Scheduled Task 不另设执行器或并发计数。
+- 两种来源均由 Main 派发给 Renderer，建立普通用户消息和流式助手消息后调用 `agent.run`。
+  Renderer 加载会话及设置后才声明队列可派发。SSH 项目同样通过该入口选择远程 Runtime，
+  使用普通请求的上下文、工具范围、取消和恢复流程。
+- `schedule_run.id` 作为普通请求 ID；普通请求终态同步该次计划运行与稳定产品 Task 的状态。
+  尚未接受的派发可释放重试；已经接受的运行在重启后按普通 Task 状态结算或恢复，不重新发送。
 - 当前执行到达终态后再认领下一项。删除只移除尚未执行的项；“立即中断并插入”取消当前
  请求并把所选项设为下一项，不重排其他项。
 - 每条 Conversation 最多保留 20 个用户可提交的待执行项。启动时将未完成的派发恢复为
@@ -435,9 +438,9 @@ Renderer 只通过显式 IPC 列出、加入、删除、提升、释放和接收
 └─ 独立成果

 智能心跳
-├─ 成长概览
+├─ 运行概览
 ├─ 待处理建议
-├─ 心跳轨迹
+├─ 报告与记录
 └─ 心跳计划
   └─ Global / 指定 Project
 ```
@@ -445,7 +448,7 @@ Renderer 只通过显式 IPC 列出、加入、删除、提升、释放和接收
 监督统一进入应用级助手工作栏中固定且始终可访问的“监督”栏目，不再保留“独立可折叠右栏”
 和“动态新增页签”两种实现。栏目默认跟随当前上下文，用户可以固定到其他 Conversation、
 Task 或实验对象；详细范围与交互契约见
-[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。
+[通用助手工作栏与执行空间 PRD](../features/assistant-workbar/prd.md)。

 ## 13. 安全与隐私

@@ -507,7 +510,7 @@ experiment_runs
 现有 `schedules`、`schedule_runs`、`heartbeat_configs`、`heartbeat_runs`、
 `heartbeat_entries`、`tasks` 和 `runs` 不应一次性重写。Schedule 可渐进建立稳定 Task 与
 Conversation 关联，旧 child-task 字段可兼容映射到 Job/Subjob；心跳数据保持独立，不得
-静默转成 `AutomationPlan` 或顶层 Task。未来分区记忆完成设计前，不新增迁移目标。
+静默转成 `AutomationPlan` 或顶层 Task。分区记忆协同和唤起条件完成设计前，不新增迁移目标。

 ## 16. 分阶段实施

@@ -518,7 +521,7 @@ Conversation 关联，旧 child-task 字段可兼容映射到 Job/Subjob；心
 - 明确 Task N:1 Conversation 关系、左侧行首展开按钮与 Task 子项图标，以及 Task Center
  索引边界，不复制内容。
 - 为现有 Scheduled Task 和专家执行建立按 Task 聚合的活动视图。
- 明确当前心跳保持独立，未来分区记忆尚待设计。
+- 明确当前心跳保持独立，分区记忆协同与唤起条件尚待设计。
 - 补充触发来源、运行版本、预算和读写范围展示。

 ### 阶段 1：调度与运行基础
@@ -555,21 +558,21 @@ Conversation 关联，旧 child-task 字段可兼容映射到 Job/Subjob；心

 ## 17. 相关文档

- [Task 与 Job 统一领域模型](../prd/task-and-job/task-and-job-model.md)
- [Task Center PRD](../prd/task-and-job/task-center-prd.md)
- [Scheduled Task PRD](../prd/task-and-job/scheduled-task-prd.md)
- [Job 与 Subjob PRD](../prd/task-and-job/job-and-subjob-prd.md)
- [智能心跳 PRD](../prd/smart-heartbeat/smart-heartbeat-prd.md)
- [并行实验工作台 PRD](../prd/experiments/parallel-experiments-prd.md)
- [会话监督 PRD](../prd/supervision/conversation-supervision-prd.md)
- [分区记忆 PRD](../prd/memory/partitioned-memory-prd.md)
- [持续学习与评估门 PRD](../prd/learning/continuous-learning-prd.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. 总体验收标准

- [ ] 智能心跳保持独立，不作为 Task 类型；未来分区记忆尚未设计。
+- [ ] 智能心跳保持独立，不作为 Task 类型；分区记忆协同与唤起条件尚未设计。
 - [ ] Task Center 只索引 Task；每个 Task 只关联一条 Conversation，一条 Conversation 可以
  关联多个 Task。
 - [ ] 当前 UI 只展示到 Task，不提供 Job/Subjob/Run 树或独立导航。
@@ -10,7 +10,7 @@
 | 日期 | 2026-08-19 |
 | 适用产品 | GoodBuddy 桌面端 |
 | 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
-| 相关基线 | [统一界面设计系统](../../UI-DESIGN.md)、[文档解析与本地 OCR](../prd/document-processing/document-extraction-and-local-ocr.md)、[本地文本向量模型与连接设计](./local-text-embedding-model-design.md)、[全双工实时语音交互设计](./full-duplex-voice-design.md) |
+| 相关基线 | [统一界面设计系统](../../UI-DESIGN.md)、[文档解析与本地 OCR](../features/document-processing/prd.md)、[本地文本向量模型与连接设计](../features/knowledge-base/local-embedding-technical-design.md)、[全双工实时语音交互设计](../features/full-duplex-voice/technical-design.md) |

 本文定义“设置 → 平台功能”的二级页签结构，以及所有 GoodBuddy 托管本地模型共同使用的
 “模型下载源”设置。首期下载源为 ModelScope 和 Hugging Face，默认使用 ModelScope。
@@ -1,247 +0,0 @@
-# SSH 远程主机与 GoodBuddy Agent 实现说明
-
-## 状态
-
-本文记录当前代码实现，不定义额外的信任框架。Windows 到 Linux x64 的安装、Main-only 模型桥、断线恢复、输出重放、同一 OpenCode Session 续接与终态清理已经在真实 Host 上完成 provider-free 验证。上一轮 Linux x64 验收使用 Agent `0.11.2-e2e.12` 与 OpenCode Runtime `1.18.9` 完成了一次有界真实模型工具调用；加入每 helper 随机 loopback 路径 capability 后，当前源码 lock 已转为正式 Agent `0.11.5`。失败的 `agent-v0.11.3` 保持不可变且未发布。远程 OpenCode 功能仍处于发布前验证阶段；公开签名 key registry 已供应，当前发布门槛是通过独立 Agent workflow 正式发布并公开验证 Linux x64/arm64 复合包和签名累计目录。
-
-## 产品语义
-
-远程 Host 与项目能力是默认关闭的技术预览。用户在“设置 > 平台功能”的独立
-“远程项目（技术预览）”页签启用开关后，Renderer 才显示 SSH Host 管理、托管 SSH 项目创建和已保存
-远程项目；Main 在 IPC 边界执行同一开关校验，避免隐藏界面被绕过。关闭开关不删除 Host、
-项目或凭据；进行中的激活允许取消，当前远程项目切回第一个普通本地项目。应用启动仍固定
-选择普通本地项目，不会因为保存了远程项目而自动连接 Host。
-
-远程项目只有两种工作模式：
-
- **Ask**：Runtime 在操作系统边界以只读方式访问项目 Workspace。
- **Execute**：用户已授权使用所选 SSH 账号的完整权限。Runtime 可以使用该账号可访问的文件、进程、网络和工具，不再要求额外 trust tier、consent checklist、逐工具审批或“受控执行”授权。
-
-Execute 不获得 root 或 SSH 账号本身没有的权限。模型 API Key 与 Provider 认证仍保留在 Electron Main，不传给远端 Runtime。
-
-## 组件
-
-```text
-Renderer
-  -> 窄 Preload / Main IPC
-Main
-  -> SSH Host 与 Host Key 管理
-  -> SSH connection pool
-  -> 签名 Agent / Runtime 安装
-  -> 远程项目验证与 SQLite 事务
-  -> Main-owned model bridge
-SSH attach
-  -> 远端私有 Unix socket
-Detached GoodBuddy Agent
-  -> Workspace / Git 协议
-  -> OpenCode ACP channel
-  -> 直接拥有的 Runtime 进程
-```
-
-不提供把远端路径交给本机 Runtime 的伪本地模式，也不提供 SSH stdio Runtime fallback。
-
-## SSH Host
-
- Renderer 只管理脱敏 Host 快照，不接触密码、密文、SSH Client 或任意命令接口。
- Main 在认证前取得 Host Key，展示算法与 SHA-256 指纹，并保存完整 key blob。
- 首次连接需要用户确认。Host Key 变化展示旧/新值并要求显式替换。
- 密码使用 Electron `safeStorage`；系统 SSH Agent 认证不启用 Agent forwarding。
- Host 地址、用户或 Host Key generation 变化时关闭旧连接，并定向退役依赖旧 Host identity 的 Workspace 和 Runtime 会话。保存开始后，所有引用该 Host 的项目保持“需要重新激活”状态；当前项目立即执行完整激活并原子刷新 Host revision 等验证结果，其他项目在下次选择时刷新。激活失败或取消不会恢复发送能力，Composer 和来自 Main 持久队列的用户消息都要等待后续成功激活；排队消息会退回原队列，并在成功后通过既有 queue-ready 流程继续。用户重新选择当前 SSH 项目也会显式触发相同验证，而不是复用旧项目快照。
-
-## Agent 安装与生命周期
-
- Agent bundle 通过 manifest、Ed25519 签名、payload digest、平台和架构校验。
- 安装使用当前 SSH 用户目录中的 GoodBuddy-owned 路径和 side-by-side digest 目录。
- Agent 代码与固定 Node Runtime 是独立 payload。升级时如果当前 Host Agent 的签名
-  manifest、registry identity、owner/mode/size 和 Node digest 都可验证，且候选
-  manifest 声明完全相同的 Node，安装器直接在新的 side-by-side 目录中复用该 Node；
-  否则正常上传候选 Node。Agent 不匹配不会阻止升级，也不会覆盖旧安装。
- 桌面包只携带版本 lock 与 production 公钥，不携带远端 payload。用户必须先在设置中显式下载最新兼容的目标架构复合包，或导入离线 `.gbagent`；项目激活不会联网下载。每个复合包绑定 Agent、固定 Node 与桌面维护的 OpenCode Runtime 精确工件。应用重启固定进入第一个普通本地项目，不自动连接上次远程项目；用户主动切换托管 SSH 项目时，Main 从本地验证缓存选择 Host 架构工件，Host 尚未安装该 identity 时上传并启动。相同 Renderer 对同一项目的并发激活共享一个 Main 操作。
- Agent、Workspace 和 Runtime 全部验证成功后，Main 才在同一 SQLite 事务中刷新项目保存的 Agent/Runtime evidence，然后把项目设为当前项目。上传、启动、验证或事务失败时，项目继续绑定旧 identity，不能用未提交的新 identity 绕过持久化绑定校验。
- SSH 连接先尝试 attach；Agent 不存在或未运行时执行幂等 bootstrap，然后重新 attach。
- Agent 是按需启动的 detached process，不注册开机服务，不依赖 systemd、D-Bus 或 Linger。
- 每个模型桥 helper 都为 loopback HTTP 入口生成一次性随机路径 capability；只有写入当前 OpenCode 子进程配置的 URL 可以访问该入口，其他本机用户即使发现临时端口也不能提交模型请求。
- Agent 监听当前用户拥有的私有 Unix socket。SSH 中断只关闭 relay，不拥有 Agent 和活动 Runtime 的生命周期。
- SSH Host 设置通过固定探针和有界 SFTP 显示 Host 已登记的 Agent/OpenCode 版本，并与当前 GoodBuddy 所需版本比较；打开设置或“刷新版本”只读取状态，不安装或切换远端组件。
- “平台功能 > 远程项目”中的本地 Agent 包清单与 Host 状态分离。Main 对用户数据目录中
-  Linux x64/arm64 `.gbagent` 分别执行外层可信签名、桌面/协议兼容性、内部 Agent/Runtime
-  签名、架构与完整 payload 校验；首次打开和手动刷新还会读取“关于与更新”所选来源的
-  小型签名目录。Renderer 只得到本地/在线版本、是否有更新、架构、远端 Runtime 版本、
-  协议和本地状态，不得到缓存路径、key ID 或 digest。目录检查不下载 `.gbagent`，在线
-  包下载只由用户点击带目标版本的操作触发；离线导入/导出通过 Main 管理的文件对话框完成。
- 当任一组件缺失或不是当前版本时，用户可显式选择“更新版本”。Main 使用同一个取消信号依次强制执行 Agent、Runtime 安装器，并把 Agent、Runtime、Finalizing 阶段只发送给发起更新的 Renderer。更新启动仍受技术预览开关和可信 Sender 校验约束；取消不受开关约束，确保操作开始后即使关闭功能也能停止。
- 更新成功后才定向清理该 Host 的 Agent 连接和 Runtime 选择缓存，并让当前引用项目重新激活；失败或取消保留 Host 配置、凭据、项目、Workspace 和可继续验证的旧组件，Renderer 刷新实际版本并允许重试。同一 Renderer 同时只更新一个 Host，窗口销毁或 Main 退出会取消活动更新并执行有界收尾。
- 显式 stop、升级、身份冲突或进程退出时清理 GoodBuddy 自己的 socket、状态和子进程；不得删除或覆盖无关 Host 文件。
-
-## Workspace
-
-Main 传入已规范化的绝对 POSIX root。Agent 返回 Workspace identity、访问模式、Git 状态和有界能力。
-
- 创建项目时，用户可以直接输入远端工作目录，或通过输入框右侧的文件夹按钮浏览并选择目录。
- 项目保存前的目录浏览使用 Main 管理的只读、有界 SFTP，只返回目录；每次请求重新解析并校验当前 Host revision 与 Host Key generation，不安装 Agent、不暴露任意 shell/SFTP 接口。
- 浏览从 SSH 账号 Home 或当前有效绝对路径开始，限制扫描次数、返回条目和总时限；取消、Host 变化、超时或连接失败时关闭 SFTP 并保留用户原先输入。
- 选择目录只更新项目草稿，仍需通过正常的 Agent、Workspace、Runtime 验证和项目保存事务才会持久化。
- Ask Workspace handle 不暴露写入方法。
- Execute Workspace handle 可读写，但这不是 Execute 的唯一权限面；Execute Runtime 本身使用 SSH 账号的正常权限。
- 文件预览、搜索、Git diff、目录项和显式文件传输保持字节、条目数和路径长度上限。
-
-## Runtime
-
-首个远程 Runtime 固定为签名 OpenCode ACP bundle。
-托管 SSH 项目的 Composer Runtime 菜单只显示当前配置的 OpenCode 和管理入口，不显示
-直连模型、Continue 或 DeepSeek Harness。激活旧远程会话时，若其保存了其他 Runtime
-selection，Renderer 会恢复为当前 OpenCode 配置；Main 的远程请求校验仍是最终边界。
-
-### Ask
-
-Ask 使用系统 `bwrap`：
-
- Workspace 和 Runtime bundle 只读 bind；
- 独立可写 scratch HOME、TMPDIR 和 XDG 目录；
- 固定环境名和固定 Runtime argv；
- 通过只读边界阻止 Workspace 修改。
- ACP 权限请求只有在工具种类为原生 `read` 且 Runtime 提供 `allow_once` 选项时才允许；
-  search、edit、execute、未知工具以及只提供持久授权的请求全部拒绝。
-
-`allow_once` 只解决 OpenCode 发起原生读取前的 ACP 协商，真正的文件系统边界仍是只读
-`bwrap` bind。Host 缺少 `bwrap` 时 Ask 不可用。
-
-### Execute
-
-Execute 不经过 Ask 的 bubblewrap profile：
-
- 直接启动已签名 Runtime entrypoint；
- 使用 Main-only 模型桥时，签名 Agent launcher 会 `exec` 候选 manifest 锁定的
-  Node Runtime；完全相同且已验证的 Node 可在 Agent 版本间复用。进程 owner 校验
-  最终 Node executable，而不是已经被替换的 shell launcher 路径；
- `cwd` 为项目 Workspace；
- 继承 SSH 账号的正常环境、文件系统、进程和网络能力；
- 不进行 T2/T3、confinement attestation、approval bridge 或逐工具批准。
-
-两种模式都保留请求 deadline、输入/输出字节上限、取消和进程组清理。
-
-## ACP 与断线
-
- 管控面只负责有界 JSON-RPC：连接、查询、启动、取消、关闭和重连。数据面只负责
-  ACP/blob 数据与 Agent 本机 journal。二者共享同一个经过 Host Key 校验和认证的
-  SSH attach 字节流，但不共享生命周期：管控连接关闭不会隐式取消 Agent 已接受的
-  Runtime 动作。
- 帧只保留连接 identity、channel identity、单调 sequence、类型和长度。Main 与
-  Agent 都按调用顺序 FIFO 写入，输入队列达到固定字节或条目上限时暂停 SSH stream。
-  顺序、可靠传输、分包和网络背压全部交给 SSH；协议不实现 credit/window、优先级
-  调度、跨 channel 超车、批发送或第二套拥塞控制。
- Agent 在把 Main 输入交给 Runtime 前、以及把 Runtime 输出交给 Main 前，先把 ACP frame 写入本机 journal。ACK 只推进 cursor 并裁剪已确认 frame，不表示 channel 已终止。
- Main 持久化 binding identity 和单调 cursor；保留中的 connection lease 即使处于 offline/reconnecting，也可以先把新 cursor 落盘。重连提交不能覆盖 resume 过程中并发落盘的更新。
- 同一 detached Agent 存活时，短暂 SSH 断线依次执行 `controller/resume`、`runtime/resumeAcpChannel` 和 `runtime/replayAcpChannel`，从 Main 已确认的 cursor 后只重放 Agent 到 Main 的已记录输出。重复 frame 会被确认但不会再次交给上层。
- Main 到 Runtime 的 ACP 输入、模型请求、工具请求和 blob 不自动重放。
- 无法确认外部 Provider 是否已处理的模型调用保持结果未知，避免重复计费或重复副作用。
- 只有远端返回 identity 匹配且 `closed: true` 时，Main 才删除持久化 binding；传输失败或未确认 close 会保留 recovery identity。
- 终态 close 由 Agent 在一个事务中为两个方向记录 sequence high-water tombstone，删除剩余 frame 和 active channel，并归零对应 journal quota。tombstone 用于拒绝迟到的旧 epoch frame，因此当前不会按时间自动裁剪。
- 断线不主动终止正在运行的 Runtime。用户取消、deadline、显式关闭或 Agent shutdown 才触发停止。
- Agent 失联期间继续把 Runtime 输出写入本机 journal；重新连接只校验 controller
-  identity、恢复 binding，并从 Main 最后确认的 cursor 后同步缺失数据。已接受的
-  指令和结果不确定的 Provider 请求都不自动重放。
-
-## 模型桥
-
- Provider URL、API Key 和认证头只存在于 Main。
- 远端 OpenCode 通过 GoodBuddy Agent helper 和每次 Prompt 的私有 Unix socket 使用模型桥。
- Main 校验固定模型 profile、协议、请求路径和有界传输格式，并记录 Provider
-  返回的实际 usage；不限制 Prompt 内的模型调用轮数、工具调用次数、累计 Token
-  或单次模型输出 Token。取消、Runtime deadline、请求/响应字节上限和结果不确定时
-  禁止自动重放仍然保留。
- helper 可以接收同一 Prompt 内并发到达的模型桥请求；它在单一稳定模型桥上按到达
-  顺序等待并交付，不返回本地 `bridge-busy`，每个响应只有在 HTTP 完整 flush 后才
-  发送 delivery ACK。
- GoodBuddy 自己管理会话标题，因此传给 OpenCode 的配置禁用 title Agent；一次用户
-  Prompt 不会额外触发标题模型请求。
- 一条模型桥消息编码为一个 canonical JSON blob frame；blob frame 最大 2 MiB，
-  Provider 请求与响应 body 仍各自限制为 768 KiB。每条模型消息只调用一次 SSH
-  write，不再二次分片、等待逐帧 credit 或合并多个协议帧。凭据不进入 Renderer、
-  SSH 命令参数或远端环境。
- Unix socket 接收端按 `readableLength` 中已经缓冲的字节增量排空一个声明长度的帧，
-  不会在部分大响应到达时反复请求尚未缓冲的完整剩余长度；短读、连接结束、错误和取消
-  都会使当前交换失败。原生 Linux 回归覆盖至少 256 KiB 的 broker 响应。
- Renderer 把相邻 text/reasoning delta 合并为消息 block 时始终替换最后一个 block，
-  不修改既有 React state 对象。这样开发环境 StrictMode 重复调用 state updater 时，
-  block metadata 与 canonical 消息正文保持一致。
-
-## 已完成的 E2E 验收记录
-
- 2026-08 的本地 fixture 完整验证 Linux x64 Agent `0.11.2-e2e.12`、Node `24.19.0`
-  和 Agent protocol `2.0`；当时没有 arm64 fixture，因此该记录不能作为当前独立发布
-  的双架构验收。当前源码 lock 是正式版本 `0.11.5`，需要由新的复合包发布流程另行验证。
- 正常 Host 更新路径把 Linux x64 Host 的 Agent 更新为 `0.11.2-e2e.12`，并确认
-  OpenCode Runtime 已安装版本与所需版本均为 `1.18.9`。
- 一条新的 Ask 用户操作只提交一次。OpenCode 先在 build 模型轮次请求一个原生
-  `read`，读取专用测试 Workspace 中的证据文件，再在第二个 build 模型轮次生成最终
-  回答；没有 title 模型轮次，也没有第二个工具调用。
- 两个模型轮次都记录已交付，远端 helper 保持休眠且 Unix socket 没有未读响应积压。
-  持久化的 canonical 助手正文精确为 `GOODBUDDY_REMOTE_TOOL_4C6B9D8A`。验收操作没有
-  重放任何结果未知或已经完成的 Provider 请求。
-
-## 项目保存
-
-远程项目持久化稳定配置和当前验证结果：
-
- Host ID、Host revision 与 Host Key generation；
- 远端工作目录和 Workspace identity；
- Agent installation identity；
- Runtime selection、bundle digest、adapter digest；
- `ask | execute`。
-
-打开托管 SSH 项目会从这些已保存字段重建验证输入，不接受 Renderer 回传的旧项目草稿。桌面更新后，用户先显式准备兼容复合包，第一次打开才可安装对应 Agent/Runtime 并原子刷新以上字段，同时保留项目名称、说明、Host、远端工作目录、Runtime selection 和默认工作模式。
-
-请求前置校验只要求 Workspace 验证与 Runtime 验证来自同一个当前 Agent
-installation。它不比较激活时保存的模型 profile 或默认工作模式与当前会话选择，
-因为这些不是签名远端 Runtime 的身份；切换当前模型配置或 Ask/Execute 不需要重新激活
-项目。实时 Runtime 创建仍只接受 OpenCode，使用当前解析后的模型 profile 建立 Main-only
-模型桥，并再次精确核对 Agent identity、Runtime bundle/adapter digest、架构、capability
-和连接身份。Ask/Execute 权限继续由每次 Prompt 的 ACP Runtime 边界执行。
-
-Renderer 在用户主动打开托管 SSH 项目时订阅同一次 Main 保存操作的进度，依次显示
-Host、Agent、Workspace、Runtime 和 Saving。操作完成、失败或取消后会清除阻塞进度；
-进行中可显式取消，并禁用会产生冲突的项目切换、创建和设置入口。远端 RPC 拒绝只向
-Renderer 暴露固定方法名、数字 RPC code 和有界 service code，不转发 Host 私有错误详情。
-`runtime/preparePrompt` 在远端明确拒绝且尚未接受 Prompt 时会关闭对应 Main binding，
-不会把确定性失败错误保留为 `outcome-unknown`。
-
-不持久化 T2/T3、consent、approval bridge 或 confinement 证明。数据库迁移可以保留旧列以安全读取历史数据库，但新 domain object 不再暴露这些字段。
-
-## 资源与发布
-
- 所有桌面构建（包括 `portable` 与 `release:package`）只携带
-  `agent-runtime-lock.json`、`remote-runtime-lock.json` 与公开的
-  `agent-release-keys.json`，不嵌入 `.agent-resources`、
-  `.remote-runtime-resources` 或任何可安装 Linux 远端 payload。
- `build/agent-package.cjs` 在对应原生 Linux 架构组装确定性 `.gbagent`，外层签名覆盖
-  描述符和每个内部文件身份；内部 Agent 与 Runtime 仍分别使用既有签名 manifest 和 lock
-  校验，但所有 production 层统一使用一组 GoodBuddy 通用发布身份并通过签名域区分用途，
-  不要求内部 Runtime 单独配置密钥。`build/agent-catalog.cjs` 为双架构包生成签名累计目录，
-  拒绝同一版本/架构改变字节。
- `.github/workflows/agents.yml` 只使用进程内临时测试 key 做分支/PR 原生验证，不发布。
-  `.github/workflows/agent-release.yml` 才可在 annotated `agent-v<version>` 标签和受保护
-  `agent-signing` Environment 中构建 production 包。Agent GitHub Release 必须
-  `--latest=false`；北京 OSS 先写 `agent-releases/v<version>/`，GitHub 公开后才切换
-  单一 `agent-releases/latest.json` 指针，使客户端始终从同一不可变版本目录读取目录与签名。
- Main 的本地缓存只发布完整验证成功的内容。在线目录和包都绑定固定 GitHub/OSS URL、
-  大小和 SHA-256；选取规则是桌面最低版本满足、Agent protocol major 相同且 minor 不高于
-  当前支持值的最高 SemVer。缺少某架构仅使该架构 Host 的托管 SSH 无法激活。
- `agent-release-keys.json` 读取时按 UTF-8 JSON 解析并严格验证 schema、唯一 key ID、
-  规范 Base64、有效 Ed25519 key、环境和撤销列表，不把 CRLF/LF 或普通 JSON 空白作为
-  信任条件。上传到 Host 前重新序列化为确定性 LF JSON。签名目录、描述符、manifest 和
-  payload 仍按原始签名字节及 SHA-256 验证。
-
-## 发布前验证
-
-1. `npm test`
-2. `npm run typecheck`
-3. `npm run lint`
-4. `npm run build`
-5. 用测试签名复合包验证在线下载源选择和离线导入/导出；正式 Agent 候选还需公开校验
-   双架构 production 包与签名目录。
-6. 在已固定 Host Key 的 Linux x64 测试 Host 上验证 attach-or-bootstrap。
-7. 在 GoodBuddy 专用测试目录验证 Ask 无法修改文件。
-8. 验证 Execute 可以写文件、启动进程和访问网络，同时不触碰无关 Host 文件。
-9. 运行一次有界的真实模型调用，确认凭据只由 Main 使用。
-10. 中断并恢复 SSH，确认活动 Runtime 不被网络抖动终止。
@@ -0,0 +1,497 @@
+# GoodBuddy 设备共享与 ShareServer 联邦网络总体设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-09 |
+| 适用范围 | GoodBuddy 桌面端、ShareServer、网关间联邦协议 |
+| 桌面端设计 | [设备发现与共享](../features/device-sharing/README.md) |
+| 服务端设计 | [ShareServer](../../../goodbuddy-shareserver/docs/features/share-server/README.md) |
+
+## 1. 文档职责
+
+本文是设备共享网络的跨端权威设计，负责定义拓扑、术语、身份、能力清单、授权计算、任务
+路由、能力分发、协议边界和共同验收标准。桌面端的产品与界面行为由“设备发现与共享”功能
+文档负责，独立 Web 服务由 ShareServer 功能文档负责。
+
+本文描述完整目标系统，不以交付阶段删减领域模型，也不把尚未实现的设计表述为当前能力。
+
+## 2. 核心决策
+
+### 2.1 两个独立产品面
+
+1. **GoodBuddy Desktop** 在设置中提供“设备发现与共享”，默认使用局域网发现与直连，也可
+   由用户额外连接一个或多个 ShareServer。
+2. **ShareServer** 是独立部署、独立升级的 Web 服务，提供组织、设备、能力、权限、更新、
+   联邦、中继、Office 编辑和审计管理。它不运行在 Electron Main 中，也不由桌面端代为启动。
+
+### 2.2 能力优先，来源可见
+
+用户日常选择的是能力，不是网络连接。设备、ShareServer 和组织作为能力来源与诊断入口。
+任何调用都必须持续显示提供者、执行位置和数据去向，不能为了统一体验隐藏跨设备或跨组织
+边界。
+
+### 2.3 局域网是默认连接方式，网关是显式附加连接
+
+- 桌面端没有网关配置时，局域网发现、配对、调用和本机共享仍可完整工作。
+- 添加、删除或断开 ShareServer 不改变局域网配对关系。
+- ShareServer 不接管本机局域网发现，也不能静默把局域网设备注册到组织。
+- 同一桌面端可以连接多个 ShareServer；能力来源和授权按连接分别计算。
+
+### 2.4 发现、被发现和开放能力是三个独立动作
+
+- **发现设备**：浏览同一局域网中主动广播的 GoodBuddy 服务。
+- **允许被发现**：广播本设备存在及配对入口。
+- **开放能力**：向指定设备、用户组或组织发布可查看、调用或拉取的能力。
+
+开启其中一项不能推导另外两项已开启。新安装默认不开放能力。
+
+### 2.5 ShareServer 优先作为控制面
+
+ShareServer 负责身份、目录、策略、任务路由、更新和审计。数据面优先在两个已认证端点之间
+直接建立；网络条件不允许时，可按组织策略使用 ShareServer 中继。是否允许中继、正文是否
+端到端加密、是否允许跨组织，由本次任务冻结的策略共同决定。
+
+### 2.6 Office 编辑是 ShareServer 托管服务
+
+ShareServer 可以把 ONLYOFFICE Docs、工作副本存储、保存回调和编辑会话作为一个可选部署
+能力提供给 Desktop。Desktop 只连接用户已明确配置的 ShareServer，不直接配置 Document
+Server，也不在本机启动服务。Office 文档内容会由 ShareServer 和编辑引擎处理，因此不能沿用
+“控制面默认不读取正文”的数据面假设；创建编辑会话前必须明确显示服务端、数据去向和保留期。
+
+编辑后的本地或 SSH 源文件仍由 Desktop 或远程 GoodBuddy Agent 持有和原子回写。ShareServer
+是工作副本及服务端保存检查点的权威，不是源文件最终写入成功的权威。完整设计见
+[Office 协同编辑](../features/office-document-editing/README.md)。
+
+## 3. 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| `Device` | 安装 GoodBuddy 并拥有稳定设备身份的终端 |
+| `Peer` | 与当前设备存在局域网配对关系的另一台设备 |
+| `ShareServer` | 提供组织控制面和可选数据中继的独立服务 |
+| `Organization` | ShareServer 中隔离成员、设备、能力与策略的管理范围 |
+| `GatewayConnection` | 某台设备与一个 ShareServer 上特定组织身份的连接 |
+| `Capability` | 可被查看、调用或分发的稳定能力标识 |
+| `CapabilityProvider` | 实际持有并执行某项能力的设备或服务节点 |
+| `Publication` | 能力提供者向某一范围发布的可见性和使用声明 |
+| `Grant` | 主体对能力执行某类动作的明确授权 |
+| `Task` | 一次远程能力调用及其输入、执行、输出和终态 |
+| `Package` | 可下载到本机安装的签名能力工件 |
+| `FederationTrust` | 两个组织网关之间经管理员确认的双边信任关系 |
+| `DocumentEditSession` | ShareServer 托管的单文档短期编辑会话、工作副本和保存检查点 |
+
+“网关”是 ShareServer 的网络角色；产品名称为 `ShareServer`，独立仓库为
+`goodbuddy-shareserver`。
+
+## 4. 系统拓扑
+
+```text
+局域网：
+GoodBuddy Desktop A <-- mDNS 发现 + 配对后 TLS 直连 --> GoodBuddy Desktop B
+
+单组织：
+GoodBuddy Desktop A -- 出站连接 --> ShareServer <-- 出站连接 -- Provider Device B
+
+Office 编辑：
+GoodBuddy Desktop --> ShareServer --> ONLYOFFICE Docs
+                         └-------> 临时工作副本与保存检查点
+
+跨组织：
+Desktop A --> ShareServer A <== 联邦信任 ==> ShareServer B <-- Provider Device B
+```
+
+局域网和网关连接共享能力、授权和任务的领域语义，但不共享发现方式：
+
+| 维度 | 局域网 | ShareServer |
+| --- | --- | --- |
+| 发现来源 | mDNS/DNS-SD 主动广播 | 已配置 URL 或邀请链接 |
+| 初始身份 | 双端验证码确认设备指纹 | 用户登录、设备注册和组织成员身份 |
+| 能力目录 | 已配对设备直接返回 | 服务端按组织策略过滤 |
+| 连接方向 | 配对后直连 | 设备主动建立出站连接 |
+| 管理范围 | 单个设备间授权 | 用户组、组织和联邦授权 |
+| 审计权威 | 两端各自本地记录 | 组织网关记录元数据，两端保留本地记录 |
+
+## 5. 组件边界
+
+### 5.1 GoodBuddy Desktop
+
+- 浏览和广播局域网服务。
+- 创建、确认和撤销点对点配对。
+- 连接 ShareServer，保存脱敏连接信息和本机受保护凭据。
+- 发布用户明确选择的本机能力。
+- 展示经当前身份过滤的能力目录。
+- 在调用前冻结提供者、输入范围、授权和路由。
+- 执行本机提供的任务，或消费远端任务结果。
+- 校验并安装用户明确选择的签名能力包。
+- 保存本机活动记录和可撤销授权。
+
+### 5.2 ShareServer
+
+- 认证用户、设备、服务节点和其他 ShareServer。
+- 管理组织、成员、用户组和设备目录。
+- 接收能力发布并生成权限过滤后的目录。
+- 计算组织强制策略，签发短期任务授权。
+- 路由任务、维护在线状态，并在允许时中继数据。
+- 管理签名包、发布通道、更新策略和撤销。
+- 可选管理 Office 编辑会话、ONLYOFFICE 接入、工作副本、保存回调、保留和清理。
+- 建立双边联邦关系并限制跨组织可见性与调用。
+- 保存有界审计元数据、用量和管理操作。
+
+### 5.3 能力提供者
+
+- 只执行已发布且本次授权允许的能力。
+- 在执行边界重新验证任务令牌、输入 schema、大小、期限和调用方。
+- 使用自身 Runtime、账号、工作区和数据权限。
+- 返回有界进度、结果、成果或确定终态。
+- 不因收到任务令牌而获得其他能力或任意系统接口。
+
+## 6. 身份与信任
+
+### 6.1 设备身份
+
+每次 GoodBuddy 安装生成稳定设备密钥和自签设备证书，私钥保存在系统安全存储中。对外只
+使用随机设备 ID、公钥指纹、用户设置的设备名称和必要协议版本。操作系统用户名、绝对路径、
+软件资产和能力详情不进入未认证发现广播。
+
+重装或主动重置设备身份会产生新设备。旧局域网配对和 ShareServer 设备注册不会自动迁移。
+
+### 6.2 局域网配对
+
+1. 发起端选择一台主动广播的设备。
+2. 双方建立临时加密通道并计算共同短验证码。
+3. 两端同时显示设备名、系统类型、公钥指纹和验证码。
+4. 双方用户确认后保存对端公钥及配对 ID。
+5. 后续使用双方设备证书认证；任一端可以撤销配对。
+
+IP 地址不作为设备身份，也不单独构成授权依据。
+
+### 6.3 ShareServer 注册
+
+用户通过浏览器/OIDC 或服务端支持的登录方式认证后，为当前设备申请一次性注册挑战。设备
+使用自身私钥签名挑战，ShareServer 建立 `user + organization + device` 绑定并签发可轮换的
+设备凭据。设备凭据不等同于用户 Web 会话，不可用于管理控制台登录。
+
+### 6.4 联邦身份
+
+两个 ShareServer 由双方管理员交换组织标识、网关公钥、公开端点和指纹，并分别确认信任。
+联邦关系只有在双方状态均为 `active` 时生效。单方暂停或撤销后立即停止新目录交换和新任务，
+已执行任务保留审计终态。
+
+## 7. 能力模型
+
+### 7.1 能力清单
+
+```json
+{
+  "schemaVersion": "1.0",
+  "capabilityId": "document.convert.docx",
+  "name": "文档转 Word",
+  "version": "1.4.0",
+  "modes": ["remote", "package"],
+  "inputSchema": {},
+  "outputSchema": {},
+  "permissions": ["receive_text", "receive_files", "return_files"],
+  "limits": {
+    "maxInputBytes": 10485760,
+    "maxOutputBytes": 52428800,
+    "maxDurationSeconds": 900,
+    "maxConcurrentTasks": 2
+  },
+  "dataPolicy": {
+    "retention": "task_lifetime",
+    "networkAccess": false,
+    "delegation": "none"
+  }
+}
+```
+
+清单只描述能力事实，不授予任何主体访问权。`inputSchema` 和 `outputSchema` 使用受限 JSON
+Schema 子集；实现必须限制 schema 深度、属性数、枚举数和总字节，不能把清单当作可执行代码。
+
+### 7.2 发布声明
+
+`Publication` 将一个能力版本发布到以下一种范围：
+
+- 指定局域网 Peer。
+- 所有已配对 Peer。
+- ShareServer 内指定用户、用户组或设备组。
+- 指定联邦组织中的用户组。
+
+发布声明同时定义允许动作：`discover`、`inspect`、`invoke`、`download`。`inspect` 允许查看
+详细清单，`discover` 只允许看到名称和可用状态。
+
+### 7.3 可调用与可分发
+
+- `remote`：代码与受控数据留在提供方，调用方只发送输入并接收结果。
+- `package`：签名工件下载到调用方，经校验和用户/组织策略批准后安装。
+
+同一能力可以同时支持两种模式，但两种模式分别授权。远程调用授权不能推导下载权，下载权
+也不能推导安装后自动启用。
+
+## 8. 授权模型
+
+### 8.1 授权输入
+
+一次动作的最终决定取以下约束交集：
+
+```text
+调用方用户权限
+∩ 调用方设备状态
+∩ 调用方组织强制策略
+∩ 发布范围
+∩ 提供方授权
+∩ 提供方组织强制策略
+∩ 能力输入与数据策略
+∩ 联邦关系限制（跨组织时）
+= allow | require_approval | deny
+```
+
+`deny` 优先于 `require_approval`，`require_approval` 优先于 `allow`。客户端偏好只能在组织强制
+策略允许的范围内收紧权限，不能放宽权限。
+
+### 8.2 Grant
+
+Grant 至少绑定：
+
+- 主体：用户、用户组、设备、设备组或外部组织。
+- 能力 ID 和允许的版本范围。
+- 动作：查看、调用、下载、安装或发布。
+- 输入：文本、文件、数据分类、单项和累计大小。
+- 提供者和执行位置限制。
+- 次数、并发、预算、时间段和有效期。
+- 是否需要每次批准。
+- 是否允许委托及明确的下游组织。
+
+“始终允许”只创建与当前能力、提供者、输入类型和范围匹配的 Grant，不创建整台设备的任意
+访问权。
+
+### 8.3 转委托
+
+默认 `delegation=none`。允许委托时，任务授权中必须冻结完整执行链和最大跳数。任一新组织、
+新能力或新数据接收方加入执行链，都需要重新计算授权，不能沿用原任务令牌。
+
+## 9. 任务协议
+
+### 9.1 任务快照
+
+创建任务时冻结：
+
+- 调用方用户、设备和组织。
+- 能力 ID、版本和提供者。
+- 输入 schema 版本、数据类型、数据分类和字节数。
+- 路由：局域网直连、网关直连、网关中继或联邦路径。
+- 授权决定、批准记录和策略版本。
+- 委托链、预算、期限和幂等键。
+
+设置或策略后续变化不追改已接受任务；紧急撤销可以阻止尚未开始的任务，并按策略取消活动
+任务。
+
+### 9.2 状态
+
+```text
+created -> awaiting_approval -> queued -> connecting -> running
+running -> completed | failed | cancelled | outcome_unknown
+created/awaiting_approval/queued/connecting -> rejected | expired | cancelled
+```
+
+- `completed` 只在提供者提交完整终态且调用方确认接收后成立。
+- 网络中断后无法确认副作用结果时使用 `outcome_unknown`，不得自动重放。
+- 重试创建新 attempt，并复用仅在能力声明支持时才有效的幂等键。
+- 用户取消必须传播到实际提供者；未确认取消时不能声称任务已停止。
+
+### 9.3 数据传输
+
+- 小型 JSON 输入使用任务通道传输。
+- 文件使用内容 SHA-256、声明大小和一次性任务对象令牌传输。
+- 接收端边读边校验大小和摘要，拒绝路径、符号链接和调用方文件名决定的落盘位置。
+- 任务正文、文件和输出不进入普通网关审计日志。
+- 中继模式下是否端到端加密由策略快照明确记录；界面必须显示网关能否读取正文。
+
+## 10. 能力包与更新
+
+每个 Package 必须提供不可变版本、目标平台和架构、内容大小、SHA-256、发布者签名、权限
+声明、依赖和兼容范围。安装流程统一为：
+
+```text
+取得签名目录 -> 选择不可变目标 -> 下载暂存 -> 校验大小/摘要/签名
+-> 展示权限差异 -> 批准 -> 安装到 GoodBuddy-owned 目录 -> 验证 -> 启用
+```
+
+要求：
+
+- 下载开始后冻结来源，不在失败时静默切换 ShareServer 或镜像。
+- 包不得包含凭据；配置只携带非敏感结构和密钥引用。
+- 新版本扩大文件、进程、网络、数据或委托权限时，旧 Grant 不自动继承。
+- 紧急撤销阻止新安装和新调用；已安装包的停用或删除遵循组织策略并向用户说明。
+- 复用现有 GoodBuddy 签名工件原则，但不同用途使用独立签名域。
+
+## 11. 协议分层
+
+### 11.1 局域网发现层
+
+- DNS-SD 服务类型：`_goodbuddy-share._tcp.local`。
+- 广播仅包含协议 major、随机实例 ID、端口和配对状态。
+- 设备名称、证书和详细版本通过临时加密握手取得。
+- 不扫描任意端口，不枚举未主动广播的机器。
+
+### 11.2 ShareServer 控制 API
+
+使用 HTTPS 提供登录、设备注册、目录、管理和审计 API；使用 WebSocket 建立设备出站控制
+通道，承载心跳、任务声明、取消和短期数据通道协商。普通管理 API 与设备通道使用不同凭据
+和受众。
+
+### 11.3 数据通道
+
+数据通道可以是配对 TLS 直连、ShareServer WebSocket 中继或经网关协商的端到端加密流。
+协议只保证有界帧、顺序、取消和终态，不自行实现另一套拥塞控制。
+
+### 11.4 版本协商
+
+- 每层独立声明 `major.minor`。
+- major 不同拒绝连接；minor 使用双方共同支持的最低能力集合。
+- 未识别字段在声明允许扩展的位置忽略，安全与授权枚举中的未知值一律拒绝。
+- 联邦只交换双方共同支持的能力和策略表达式，不降低任一方策略。
+
+### 11.5 Office 编辑协议
+
+Office 编辑使用独立的 HTTPS 会话、文件和事件 API，不复用普通远程能力 Task 表达长生命周期
+编辑器。Desktop 通过设备凭据创建会话和传输源文件；编辑器使用一次性启动授权；ONLYOFFICE
+使用独立短期 JWT 获取工作副本并提交保存回调。三类凭据使用不同 audience，不能互换。
+
+文档页签可以长期存在，但启动 URL、文件 URL、callback token 和编辑 Cookie 必须短期、单用途
+并可撤销。跨端会话、保存和冲突规则见
+[Office 协同编辑技术设计](../features/office-document-editing/technical-design.md)。
+
+## 12. 数据与审计
+
+### 12.1 最小审计事件
+
+- 操作者、调用设备和组织。
+- 动作、能力、版本和提供者。
+- 路由与是否跨组织。
+- 输入数据类别、分类、文件数和字节数。
+- 授权结果、策略 ID 和批准者。
+- 任务状态、耗时、输出大小和资源用量。
+- 包下载、安装、更新、撤销和发布变更。
+
+默认不保存提示正文、文件内容、模型输出、密钥、Cookie、认证头或完整私有路径。需要内容
+审计的组织必须单独定义保留期限和访问角色，并在调用前向用户显示。
+
+### 12.2 数据权威
+
+- 桌面端是本地配对、本机共享偏好和本地活动记录的权威。
+- ShareServer 是组织成员、设备注册、组织策略、发布目录和组织审计的权威。
+- ShareServer 是 Office 工作副本、服务端保存检查点、编辑会话和保留清理的权威；Desktop 或
+  远程 GoodBuddy Agent 是源文件是否成功回写的权威。
+- 能力提供者是运行中任务及结果是否产生的权威。
+- 联邦两端各自保存本组织审计，不复制对方完整成员目录或内部策略。
+
+## 13. 安全边界
+
+ShareServer 可以部署到公网，因此公网连接、外部组织和服务端多租户是本设计中的实际信任
+边界。共同要求如下：
+
+1. 所有远端清单、名称、schema、错误、文件和模型输出都作为不可信数据处理。
+2. Renderer 不接触设备私钥、网关令牌、任意 socket 或原始文件传输接口。
+3. Main/Provider 在执行边界重新验证任务，不信任 Renderer 或 ShareServer 代替本机授权。
+4. ShareServer 按组织隔离查询，搜索和计数接口不能泄露无权查看的设备或能力。
+5. 设备只建立主动配置的网关出站连接，不接受 ShareServer 发起任意系统调用。
+6. 局域网发现不等于信任，组织成员身份也不等于所有能力授权。
+7. 远程能力不能扩大本机 Ask/Execute、Workspace、Runtime、Skill 或 MCP 现有权限。
+8. 密钥只进入对应安全存储，诊断和审计使用固定字段与脱敏错误码。
+9. 限制握手、清单、帧、文件、并发、速率、任务时长和审计查询大小。
+10. 撤销设备、用户、Grant、Publication、Package 或 FederationTrust 后停止签发新令牌。
+11. Office 编辑器使用固定 origin 和隔离会话，不获得 Electron、文件系统、Shell、Runtime 或
+    普通 ShareServer 管理 API；Document Server 默认禁止任意出站网络和未批准插件。
+12. Office 文件正文由服务端实际处理，组织策略必须定义允许格式、大小、保留和内容访问角色，
+    Desktop 在上传前显示这些事实。
+
+## 14. 建议领域实体
+
+```text
+DeviceIdentity
+PeerPairing
+GatewayConnection
+Organization
+Membership
+Group
+RegisteredDevice
+Capability
+CapabilityVersion
+Publication
+Grant
+Policy
+Approval
+Task
+TaskAttempt
+ArtifactTransfer
+Package
+PackageRelease
+FederationTrust
+AuditEvent
+Revocation
+DocumentEditSession
+DocumentCheckpoint
+```
+
+共享协议只定义跨端 DTO 和状态，不规定桌面 SQLite 与 ShareServer 数据库使用相同表结构。
+
+## 15. 仓库边界
+
+当前仓库边界（跨仓库文档链接约定两个仓库克隆到同一级目录）：
+
+```text
+goodbuddy/
+  docs/architecture/share-network-architecture.md
+  docs/features/device-sharing/
+  src/                   # GoodBuddy Desktop
+goodbuddy-shareserver/
+  docs/features/share-server/
+  server/                # 独立 Hono Web 服务
+  shared/                # 当前原型 fixture，不是跨端协议
+  src/                   # React 管理前端
+```
+
+ShareServer 源码和服务端文档已迁入独立仓库：
+`ssh://git@git.digiman.live:11022/root/goodbuddy-shareserver.git`。
+当前服务是交互原型，尚未提供真实 Desktop 集成。共享网络总体设计仍由本文统一维护。
+
+ShareServer 不反向依赖桌面端 `src/shared`，构建和运行不要求桌面仓库存在。
+真实跨端协议实现时双方依赖独立 `share-protocol` 包，具体仓库归属和发布方式届时确定，
+不提前创建空包。协议包不得包含数据库模型、Electron API、服务实现或凭据。
+
+## 16. 共同验收标准
+
+- [ ] 不配置 ShareServer 时，两台桌面端可通过局域网发现、双端配对、查看获准能力并调用。
+- [ ] 关闭“允许被发现”不会关闭主动发现；关闭主动发现不会撤销既有配对。
+- [ ] 本机没有明确 Publication 时，任何 Peer 或组织成员都不能查看或调用本机能力。
+- [ ] 桌面端可以连接多个 ShareServer，任一连接故障不影响局域网和其他连接。
+- [ ] ShareServer 只展示当前用户、设备和组织获准查看的目录。
+- [ ] 每次远程调用都能说明提供者、执行位置、发送数据、路由、授权依据和委托链。
+- [ ] 网络中断且副作用结果不确定时进入 `outcome_unknown`，不会自动重放。
+- [ ] 能力包经大小、SHA-256、签名、兼容和权限差异校验后才能安装。
+- [ ] 跨组织调用同时满足两端策略；联邦撤销后不能创建新任务。
+- [ ] 审计默认只保存必要元数据，不保存正文、文件、密钥或认证信息。
+- [ ] ShareServer 可独立部署和升级，不由 Electron 启动，也不影响桌面端离线使用。
+- [ ] 启用 Office 服务后，Desktop 可在多实例文档页签中编辑 DOCX、XLSX 和 PPTX；保存回调、
+  源文件冲突或网络故障均不会破坏原文件。
+- [ ] Office 会话的启动、文件和 callback 凭据不可互换，过期或撤销后不能重用；临时工作副本
+  按策略清理，默认审计不保存文档正文或 AI 选区内容。
+
+## 17. 相关设计
+
+- [设备发现与共享 PRD](../features/device-sharing/prd.md)
+- [设备发现与共享功能逻辑](../features/device-sharing/logic-design.md)
+- [设备发现与共享 UI](../features/device-sharing/ui-design.md)
+- [设备发现与共享技术设计](../features/device-sharing/technical-design.md)
+- [ShareServer PRD](../../../goodbuddy-shareserver/docs/features/share-server/prd.md)
+- [ShareServer 功能逻辑](../../../goodbuddy-shareserver/docs/features/share-server/logic-design.md)
+- [ShareServer 管理界面](../../../goodbuddy-shareserver/docs/features/share-server/ui-design.md)
+- [ShareServer 技术设计](../../../goodbuddy-shareserver/docs/features/share-server/technical-design.md)
+- [Office 协同编辑](../features/office-document-editing/README.md)
+- [SSH 远程主机与 Agent](../features/remote-host/README.md)
+- [GoodBuddy 统一界面设计系统](../../UI-DESIGN.md)
@@ -0,0 +1,75 @@
+# 数据库迁移与大数据升级指南
+
+本文约束已发布用户数据的数据库升级。具体字段、存储表示和功能行为由对应功能文档负责；
+本文不建立通用迁移框架、回滚引擎或独立状态日志。
+
+## 先确认问题和数据边界
+
+1. 先只读统计文件大小、WAL、页数、空闲页、表与字段的字节数，不先删除或压缩数据库。
+2. 区分有效内容、重复存储、索引和已释放但未回收的空间。空闲页少时，单独
+   `VACUUM` 不能消除重复记录。
+3. 查清实际写入、读取、删除、重放与恢复入口。修改 Runtime 相关持久化时，同时检查
+   本机和 GoodBuddy Agent 的桌面路径，不假设一个入口覆盖另一个入口。
+4. 明确用户必须保留的信息、稳定 ID、顺序、时间、引用与远程去重字段。
+   分支内未发布、可安全重建的内部记录不需要兼容机制。
+
+## 实现原则
+
+- 先修新增数据路径，再修历史数据。历史转换与新写入尽量使用同一套转换函数。
+- 普通 schema 变更使用既有 `PRAGMA user_version` 和 SQLite 事务；
+  已升级 schema 不允许旧客户端强行打开，不通过回写版本号支持降级。
+- 大数据转换不得同步阻塞 Electron Main 或 Renderer。放到工作线程，在业务连接
+  打开前处理，并使用应用的共享字体、主题与页面组件显示进度和可执行的失败提示。
+- 根据实测设置有界读取批次与缓存，批次提交后再报告进度。保持 SQLite 事务与
+  checkpoint，不靠关闭同步落盘、取消约束或一次性读入整库提速。
+- 从已提交数据直接重试和还原即可完成的迁移，不增加 durable snapshot、journal、
+  receipt 或多阶段恢复状态。退出及失败至少回滚未提交批次，保留已完成部分。
+- 差量编码必须能精确还原原始事件。更新内容、删除或重排都要覆盖；涉及远程来源时，
+  去重、冲突判断、消息投影和恢复序号不得失效。
+- 释放数据库页和归还文件系统空间是不同步骤。先减少实际存储内容，再执行需要的
+  空间回收；保留足够临时空间，磁盘不足时明确失败并允许重试。
+- SQLite 同库写入是串行的。是否增加读取／转换并行，应由实际读取、解析、写入、
+  提交与 checkpoint 的耗时决定，不把增加写线程当作默认优化。
+
+## 验证与备份
+
+### 合成回归
+
+覆盖正常转换、无变化记录、重复打开、内容修订、失败事务和退出续跑。数据库大小问题
+必须同时验证新增写入的增长量、旧记录可还原性以及文件实际缩小，而不只检查 schema。
+对象比较必须覆盖真实生产形状和 JSON 往返，尤其是可选字段值为 `undefined` 时与字段缺省
+的差异。再次修复已发布迁移产生的数据时，提高目标 schema，并覆盖已升级用户的入口；
+不能只处理尚未迁移的旧库。
+
+### 真实旧库
+
+1. 关闭占用源数据库的应用，确认 WAL 状态。没有 WAL 时可复制已关闭的数据库；
+   有活动 WAL 时使用 SQLite 一致性备份机制，不只复制主文件。
+2. 备份到空间足够的位置，记录字节数并校验 SHA-256。备份和测试副本分离，
+   不直接在唯一原件或唯一备份上试跑。
+3. 使用当前源码或用户要求的 portable 正常启动入口执行升级，不用手工 SQL 代替
+   产品升级过程。退出一次后重新启动，验证已提交数据可以继续处理。
+4. 比较升级前后消息、任务、成果等用户表的内容；对转换事件逐条还原后比较原始内容、
+   ID、顺序、时间和去重来源，不只比较行数。日志只能包含统计和断言结果，不记录正文。
+5. 运行数据库完整性检查，记录主文件和 WAL 的实际字节数、回收比例、耗时、平台、
+   源 schema 与目标 schema。确认原件和备份未被改写。
+6. 运行 `npm test`、`npm run typecheck`、`npm run lint`；生产构建变化按开发验证规则
+   检查，发布准备则遵循[发布手册](./release-runbook.md)，不重复本地打包。
+7. 用真实模型模拟正常用户任务，允许主代理与子代理按需调用工具、修改独立测试项目、
+   运行测试和处理失败；只读纯文字模型调用不能证明工具事件增长正常。记录实际提供商
+   请求数与统计范围，不把 Runtime 用量上报数当成全部 HTTP 请求数。
+
+## 发布与维护
+
+发布说明应告知升级范围、可能耗时、退出重试、额外磁盘空间和降级边界。不得把一个测试库
+的回收比例当作所有用户都能获得的保证。功能文档记录具体转换规则，进度文档记录实际
+证据和未完成项；未经验证的阶段不能标为完成。
+
+### 已有实例
+
+- Desktop 0.13.1：子任务累计过程重复保存导致数据库膨胀，转换到 schema 34 的差量事件
+  表示，并回收空间。具体规则见
+  [执行记录存储与升级回收](../features/assistant-workbar/execution-history-storage.md)，
+  数据保留与真实旧库验证见[工作栏进度](../features/assistant-workbar/progress.md)。
+- 当前未发布源码：schema 35 同时整理旧快照和 schema 34 的重复工具块，工具字段按
+  JSON 可保存的值比较，不因 `undefined` 被省略而误判变化。
@@ -0,0 +1,317 @@
+# GoodBuddy Release Runbook
+
+Read this runbook only when preparing, publishing, recovering, or verifying a
+desktop or GoodBuddy Agent release.
+
+This is an operator and CI procedure. It does not authorize adding application
+persistence, snapshots, journals, rollback engines, recovery protocols, or
+compatibility layers to automate release operations. Determine release recovery
+from the authoritative GitHub, OSS, workflow, and Git state, then use the
+smallest existing idempotent rerun or a new immutable version as specified
+below.
+
+## Release Packaging
+
+- Unless the user explicitly requests it, never run a local production build,
+  desktop package, or launch probe as part of release preparation. In
+  particular, do not run `npm run build`, `npm run build:bundle`,
+  `npm run portable`, `npm run release:package`, direct `electron-builder`
+  packaging, or launch a locally packaged app before publishing a release.
+  Local tests, type checks, and lint plus the main-branch and native tag GitHub
+  Actions jobs are the release authorities.
+- After a release is published, confirm only that the expected Windows assets
+  exist in the public release metadata. Do not locally rebuild or launch the
+  Windows package, download or hash published installers, attach browser
+  automation to a packaged app, or perform exhaustive per-asset network probes
+  unless the user explicitly asks for that additional validation.
+- `.github/workflows/packages.yml` is the canonical cross-platform packaging
+  workflow. It validates and builds `out` once, then packages on six native
+  runners: Windows, macOS, and Linux, each for x64 and arm64.
+- The experimental Linux LoongArch (`loong64`) preview is built separately
+  through `build/loongarch-cross` by following
+  `docs/development/loongarch-preview-build.md`. It is not part of
+  `.github/workflows/packages.yml`, the six-runner GitHub Actions matrix,
+  standard release manifests, GitHub Release asset expectations, or the
+  production update index. Do not add it to those paths unless the user
+  explicitly requests a future production-support migration.
+- Run the unified packager with
+  `npm run release:package -- --platform <platform> --arch <arch>`. It only
+  packages for the native host and writes to
+  `dist/release/<platform>-<arch>`.
+- Default deliverables are NSIS and portable ZIP for Windows, DMG for
+  macOS, and AppImage, DEB, and RPM for Linux. Every target includes
+  `release-manifest.json` with SHA-256 hashes.
+- Starting with Desktop 0.12.8, macOS releases contain DMG only. Older macOS
+  GitHub update readers and all older mirror readers require ZIP and cannot
+  validate this new matrix; affected users must upgrade manually from the
+  download page. The user approved this immediate format change. Current
+  readers accept both the historical DMG/ZIP matrix and the DMG-only matrix.
+- Final Desktop package verification compares every bundled OpenCode
+  configuration file with the prepared dependency tree and rejects external
+  DeepSeek imports in the unpacked Host and chunks. Windows x64 CI also
+  imports the packaged OpenCode plugin and starts an isolated packaged
+  UtilityProcess before publishing; source-only tests do not replace it.
+- `build/build-release.cjs` verifies the unpacked application, `app.asar`,
+  bundled Continue and OpenCode runtimes, executable architecture, and package
+  signatures before atomically replacing a release directory.
+- All desktop build paths, including local `portable`, package the Agent and
+  remote Runtime version locks plus the public signing-key registry without
+  embedding installable Linux Agent or remote Runtime payloads. Managed SSH is
+  optional: users explicitly download a compatible compound `.gbagent` package
+  from Settings or import one offline before GoodBuddy can install or update a
+  Host.
+- Each independently published Linux x64, Linux arm64, or macOS arm64 `.gbagent` contains the
+  Agent daemon, pinned Node, and the desktop-maintained compatible OpenCode
+  Runtime. Build all three targets on native GitHub Actions runners from one
+  immutable `agent-v<agentVersion>` tag.
+- Keep the GoodBuddy Agent source, shared protocol/contracts, runtime lock,
+  bundle tooling, and tests in this repository so a desktop commit identifies
+  the exact Agent source it expects. Do not create a separate Agent repository
+  or long-lived Agent release branch unless the Agent becomes an independently
+  released product serving multiple clients.
+- `.github/workflows/agents.yml` is the branch and pull-request build
+  verification workflow for GoodBuddy Agent. It must build Linux x64 and
+  arm64 on native runners from the checked-out commit, acquire the locked
+  official Node archive and locked OpenCode npm archive, verify every locked
+  digest, use only an ephemeral in-memory test signing identity, and verify the
+  resulting compound package and deterministic archive. It must not read
+  production signing secrets, publish installable release artifacts, or modify
+  the checked-in public key registry. The Darwin arm64 target uses `macos-15`
+  and the same production locks. Native CI checks do not replace real Host
+  installation, Attach, Ask/Execute, and lifecycle validation during development.
+- `.github/workflows/agent-release.yml` is the only production compound Agent
+  publication path. It requires an annotated immutable Agent tag, the protected
+  `agent-signing` Environment, native x64/arm64 builds, one production
+  GoodBuddy signing identity for every layer of the compound package and
+  catalog, a non-Latest GitHub Agent Release, and synchronized immutable
+  Beijing OSS objects plus the final signed latest-catalog pointer.
+- `.github/workflows/packages.yml` and `release:package` build only desktop
+  products. Missing Agent packages, remote Runtime inputs, or GoodBuddy signing
+  credentials must never block an ordinary desktop package or release.
+- Keep electron-builder invocations on `--publish never`. Main-branch builds
+  run validation and build the production bundle without running the native
+  package matrix. Manual builds upload 30-day GitHub Actions artifacts.
+  Version-tag builds verify and aggregate packages before publishing GitHub
+  Release assets. The macOS jobs sign, notarize, and verify packages when all
+  five Apple credentials are configured. With no Apple credentials they must
+  use the explicit `--unsigned` path, warn that Gatekeeper may block the
+  packages, and still complete; a partial credential set must fail rather than
+  silently downgrade.
+- Keep `ELECTRON_CACHE` and `ELECTRON_BUILDER_CACHE` under
+  `${{ runner.temp }}` in step-level workflow contexts. A cache beneath the
+  repository inherits the root `"type": "module"` and breaks electron-builder's
+  CommonJS macOS icon tool.
+- Tag builds must use `v${package.version}`. The workflow also supports manual
+  dispatch and main-branch changes to release tooling.
+
+### Agent Release Process
+
+- Agent releases use annotated `agent-v${agent-runtime-lock.agentVersion}` tags
+  and are separate from desktop `v${package.version}` releases. Confirm the
+  exact Agent release commit and tag with the user before creating or pushing
+  either.
+- Store approved bilingual Agent release notes in
+  `resources/agent-release-notes/<agentVersion>.md`. The Agent publication job
+  reads that exact file instead of generating a generic release description;
+  keep it aligned with the approved version and source range.
+- The tagged commit must be reachable from protected `main`. The three native
+  jobs build Linux x64, Linux arm64, and Darwin arm64 packages from the same source and locks;
+  the catalog job rejects missing architectures, changed bytes for an existing
+  version/platform/architecture identity, invalid prior signatures, and incompatible
+  matrix metadata.
+- All three targets share the existing signed `agent-catalog.json`. Before the
+  first mixed-platform catalog is published, release the Desktop reader that
+  accepts Darwin entries and document the required Desktop upgrade. Older
+  Desktop readers reject the entire mixed catalog and cannot check online Agent
+  updates; preserve their locally verified packages and immutable historical
+  releases. Do not introduce a second catalog or silently weaken package
+  signature and integrity verification.
+- Agent GitHub Releases are ordinary non-draft, non-prerelease releases but
+  must use `--latest=false`; they must never replace the desktop release marked
+  Latest. Publish immutable packages and the versioned catalog to
+  `agent-releases/v<agentVersion>/` in Beijing OSS, publish the GitHub Agent
+  Release, then atomically update the single `agent-releases/latest.json`
+  pointer to that version's immutable catalog and signature.
+- Do not report an Agent release complete until both public package
+  architectures match the signed catalog by size and SHA-256, the GitHub and
+  OSS catalog bytes/signatures are identical, the application can read the
+  selected source, and GitHub's repository Latest tag remains the desktop tag.
+
+### Tagged Release Process
+
+Every version-tag release must follow this sequence. A branch-only push does
+not require release notes.
+
+1. Confirm that the user wants a release tag and identify the exact release
+   commit and the new `package.json` version. Separately ask whether this
+   release should also receive an experimental LoongArch preview build; never
+   infer that choice from an earlier release.
+2. Find the latest stable version tag reachable before the release commit and
+   inspect the complete commit and file diff from that tag to the release
+   commit. For the first tagged release, inspect the relevant repository
+   history instead.
+3. Draft concise, user-facing release notes in both Simplified Chinese and
+   English based only on verified changes in that range. Use the titles
+   `GoodBuddy <version> 更新内容` and
+   `What's New in GoodBuddy <version>`, with corresponding `功能更新` /
+   `Features` and `问题修复` / `Bug Fixes` sections when applicable. The two
+   language versions must describe the same changes. Do not expose
+   internal-only details, credentials, private content, or unverified claims.
+4. Show the exact bilingual release-note draft to the user and wait for
+   explicit approval. If the release commit or either language version changes
+   after approval, inspect the updated tag range and request approval again.
+5. Write the approved notes to the single entry for the release version in
+   `resources/release-notes.json`. A failed unpublished candidate whose content
+   is carried forward must not retain a duplicate packaged entry.
+6. Verify that `package.json`, the root `package-lock.json` version, and
+   `package-lock.json.packages[""].version` all equal the release version. Run
+   `npm run release:notes:verify`, `npm test`, `npm run typecheck`, and
+   `npm run lint`. Do not run a local production build, packaging command, or
+   packaged-app launch probe unless the user explicitly requests one.
+   If the user requested a LoongArch preview in step 1, build it separately
+   from this exact candidate by following the LoongArch build document, record
+   its size and SHA-256, and keep it outside the standard GitHub/OSS release
+   asset set unless the user separately authorizes publishing it.
+7. Commit the approved candidate and confirm the exact release commit with the
+   user. Fetch both remotes, inspect branch movement instead of overwriting or
+   silently merging it, then push that commit to `main` on `origin` and
+   `github`. Require the candidate commit's main-branch GitHub Actions source
+   validation and production build to succeed before tagging.
+8. Fetch both remotes again immediately before tagging. Confirm the working
+   tree is clean, both remote `main` refs still equal the approved commit, the
+   candidate tag is unused locally and remotely, and the exact approved commit
+   has not changed. Only then create the annotated `v${package.version}` tag at
+   that commit, push the tag to both remotes, and verify each peeled tag SHA
+   (`refs/tags/<tag>^{}`) equals the release commit.
+9. Keep both approved language versions as the single source for the GitHub
+   Release body and the packaged first-open release-notes modal. The modal
+   displays the release notes matching the current interface language and
+   contains no button linking to a full release page.
+10. Observe the tag workflow through publication and complete the public
+    verification checklist below. A successful push is not a completed
+    release.
+
+### OSS Publication Contract
+
+The tagged release job publishes through the GitHub Environment selected by
+`.github/workflows/packages.yml` (`aliyun-oss-release`) and reads the following
+effective GitHub Actions variables. Before a release or same-tag rerun can
+publish, verify that repository-, organization-, or environment-level
+resolution exposes:
+
+- `ALIYUN_OSS_BUCKET=goodbuddy`
+- `ALIYUN_OSS_ENDPOINT=https://oss-cn-beijing.aliyuncs.com`
+- a non-empty `ALIYUN_OIDC_PROVIDER_ARN` matching
+  `acs:ram::*:oidc-provider/*`
+- a non-empty `ALIYUN_ROLE_ARN` matching `acs:ram::*:role/*`
+
+For environment-scoped values, use the exact Environment name from the
+workflow; do not assume a similarly named UI environment such as `Production`
+contains the active variables.
+
+The Bucket and Endpoint are a deployment contract, not interchangeable
+examples. They must stay aligned with the trusted URL checks in
+`src/main/version-checker.ts`, `sites/app.js`, website validation, and related
+tests. A host, Bucket, Region, or CDN migration must update and validate every
+surface together before a new release.
+
+- Use GitHub OIDC and the RAM Role to obtain short-lived STS credentials.
+  Never add long-lived AccessKeys to repository or environment secrets.
+- Keep `ossutil` pinned. Its V4 signing requires the Region; derive it from the
+  canonical Endpoint, verify that the production value resolves to
+  `cn-beijing`, and pass `--region` to every `ossutil cp`, including the final
+  `latest.json` update.
+- Grant the RAM Role only the actions and prefixes required by the workflow.
+  It must be able to write immutable version objects and the final latest
+  pointer without granting unrelated administration privileges.
+- Upload release assets and `site-release.json` under the immutable
+  `releases/<tag>/` prefix first. Verify all 12 installer URLs publicly before
+  creating or publishing the GitHub Release. Update
+  `releases/latest.json` only after the GitHub Release is public and all prior
+  checks succeeded.
+- The expected GitHub Release contains 20 assets: 12 installers (two formats
+  for each Windows target, DMG for each macOS target, and three formats for each Linux target), six
+  renamed target manifests, one aggregate `release-manifest.json`, and one `SHA256SUMS`.
+  `site-release.json` is an OSS publication artifact, not a GitHub Release
+  asset.
+
+### Failed Tag Recovery
+
+Classify a failed tag by the external side effects that completed before
+choosing a recovery:
+
+- If no source or release metadata must change, correct only the external
+  configuration and use **Re-run failed jobs** for the same immutable tag. Do
+  not change, move, delete, or recreate the tag.
+- If immutable OSS objects were partially uploaded but their source bytes are
+  unchanged, a same-tag rerun may idempotently re-upload or verify them. Never
+  point `latest.json` at a partially verified prefix.
+- If the GitHub Release is already public but the final latest-pointer step
+  failed, it is a published version. Keep its packaged notes and rerun the
+  failed release job for the same tag; do not classify it as an unpublished
+  candidate.
+- If code or release metadata must change, keep the failed tag immutable,
+  increment the patch version, obtain approval for the revised exact release
+  commit and notes, and create a new tag. Do not reuse the failed version.
+
+When recovering from a version tag whose workflow never published a public
+GitHub Release:
+
+- If a code or metadata change requires a higher version and a new tag, carry
+  the failed candidate's approved user-facing notes forward into the recovery
+  version, then remove the superseded failed version's entry from
+  `resources/release-notes.json`.
+- The packaged first-open modal must show that carried-forward content only
+  once under the recovery version. Never retain both the failed version and
+  its cumulative recovery copy, because users upgrading across them would see
+  duplicate content.
+- Never remove the packaged history for a version that successfully published
+  a GitHub Release. Verify the failed release state before treating an entry as
+  superseded.
+
+### Post-Publication Verification
+
+Do not report a release complete until all of the following are verified:
+
+1. The tag workflow and all six native package jobs succeeded. Verify the
+   recorded macOS signing mode: signed builds must pass `codesign`, `spctl`,
+   and `stapler`; unsigned builds must record the Gatekeeper caveat in the
+   Actions log and job summary. In the final release job, explicitly verify
+   the OSS configuration, OIDC authentication, release-index generation,
+   immutable upload, public asset check, GitHub Release publication, and
+   latest-pointer steps.
+2. The public GitHub Release is non-draft, non-prerelease, marked Latest, and
+   uses the expected tag and title. Its body must exactly match the Markdown
+   generated from the approved packaged bilingual notes.
+3. GitHub release metadata contains exactly the expected 20 uploaded asset
+   names, including the expected Windows x64 and arm64 assets. Do not download,
+   hash, launch, or send individual network probes to published installers
+   unless the user explicitly requests that additional validation.
+4. The Beijing `releases/latest.json` returns HTTP 200, has the expected stable
+   version, exact six targets and 12 installer entries, the trusted Beijing
+   URLs, and the GitHub fallback URL. It must match the immutable
+   `releases/<tag>/site-release.json`. Fetching and comparing these small JSON
+   metadata files is sufficient; rely on the successful publication job for
+   its per-asset public checks.
+5. The live website successfully fetches the index and produces the 12 correct
+   platform/architecture/format links from that metadata.
+6. Both remote `main` refs and both peeled tag refs still equal the approved
+   release commit, and the local working tree is clean.
+
+Never create or push a release tag, and never push a previously created
+release tag, before the release-note draft has received explicit approval.
+
+- Before a push that updates the `github` remote, ask whether the user wants a
+  release tag unless they already specified that choice. A branch-only push
+  does not require a version bump or tag. When the user requests a release,
+  verify that `package.json` and `package-lock.json` contain the same release
+  version, create `v${package.version}` at the exact commit being pushed, and
+  push that tag so the native package matrix and GitHub Release run.
+- Never move or reuse an existing release tag. If `v${package.version}` already
+  exists locally or on a remote at another commit, increment the package
+  version and create a new matching tag before the release push.
+- Verified release baseline on 2026-08-18: commit
+  `60119a4317118fa3f077db0382664f15266a6682`, annotated tag `v0.10.4`, and
+  GitHub Actions run `32038633609` attempt 2 succeeded through all six native
+  packages, GitHub Release publication, Beijing OSS publication, and the final
+  `latest.json` switch.
@@ -0,0 +1,54 @@
+# Desktop Window Recovery
+
+This is recovery hardening for intermittent blank windows, not an established
+diagnosis of their cause.
+
+- `src/renderer/src/main.tsx` wraps the locale provider, App and storage-upgrade
+  page in `AppErrorBoundary`. A React render/lifecycle failure replaces the tree
+  with a blocking recovery page and an explicit Reload button. It uses the saved
+  UI language (including system preference resolution), shared theme tokens and
+  primary-button styling, without depending on the failed application providers.
+- Reload refreshes the current document, retaining its URL and storage-upgrade
+  query. It can lose unsaved input. There are no automatic React retries.
+- `src/main/window.ts` listens for `render-process-gone`. Abnormal exits open one
+  native dialog at a time, using the OS locale because renderer language storage
+  is unavailable to Main. Reload occurs only on explicit confirmation. Cancel
+  leaves the window unchanged; persistent failures require quitting and reopening
+  GoodBuddy. Clean exits, shutdown and destroyed windows do not trigger recovery.
+- Main-frame load failures are logged; aborted navigation and subframe failures
+  are ignored. Initial load promises are caught, without automatic load retries
+  or a new load-failure UI.
+- Native crashes and main-frame load failures use the existing bounded desktop
+  diagnostics store (`desktop.renderer.gone`, `desktop.renderer.load-failed`,
+  stage `renderer`). Persistent records retain fixed summaries rather than raw
+  errors. Crash reason/exit code and React errors/component stacks go to their
+  respective process consoles. There is no new diagnostic IPC.
+
+The boundary does not catch module evaluation/startup failures before React
+mounts, event-handler exceptions, asynchronous rejections, a hung renderer, or
+main-process failure. Reload does not establish that a repeated underlying error
+has been fixed. Agent runtimes and remote execution are unchanged.
+
+Targeted regressions are in `AppErrorBoundary.test.tsx`, `window.test.ts` and
+`desktop-diagnostics.test.ts`. Electron API mocks verify decision paths but do
+not establish native dialog appearance or full application recovery.
+
+Validation on Windows, 2026-09-15:
+
+- Targeted Vitest run: 20 tests passed across the three files above.
+- `npm test`: 359 files passed, 9 skipped; 4,225 tests passed, 67 skipped.
+- `npm run typecheck`, `npm run lint` and `git diff --check` passed.
+- An isolated Electron fixture bundled the current boundary, shared styles and
+  production window module. Both languages and themes at requested content sizes
+  1280x800, 960x720, 720x640 and 640x420 passed visibility, focus and horizontal
+  overflow checks. Windows scaling rounded actual widths down by one CSS pixel.
+  The 16-image overview and Chinese/light and English/dark short-window originals
+  were visually reviewed; no clipping or focus-style defect was found.
+- A native Space key activated the recovery button and reloaded the document.
+  Two actual renderer crashes verified confirmed reload with URL retention and
+  cancellation without retry. Only native dialog responses were mocked; native
+  dialog appearance, full App business-state recovery and other OSes were not
+  verified. No model calls were made by this fixture.
+- The first temporary Electron driver timed out during ESM startup. Removing its
+  top-level readiness await fixed the driver; the subsequent run passed. This
+  was a test-driver failure, not evidence of the reported application root cause.
@@ -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.
@@ -0,0 +1,96 @@
+# 应用导航与系统工具入口
+
+本功能整理 GoodBuddy 主侧栏的入口层级：系统入口保持固定，内置应用通过最底部应用中心
+访问，并可常驻主导航；系统工具由右侧工作栏 Tab 承载。应用商店是后续功能，首期不提供
+商店入口、推荐位或安装流程。
+
+当前分期见 [PRD 第 8 节](./prd.md#8-分期)，实施步骤见[技术设计第 11 节](./technical-design.md#11-实施顺序)。
+本轮更新实施计划与范围，旧版功能要求、验收和配套设计仍需按新计划同步，此项列为实现前的第一步。
+
+新增计划包括 [私有化市场与 YAML 交换](./prd.md#fr-15-私有化市场与-yaml-交换后续)：
+通过市场 URL 获取应用，支持 `.yml` 导入导出，未来由 ShareServer 提供私有目录与分发。
+[本机模型管理入口](./prd.md#fr-16-本机模型管理入口新增计划项)可独立于商店交付，拟作为
+可常驻左侧的内置管理应用，区分受管进程、外部服务和进程内模型。两项均为需求记录，
+未实现，相关后续验收见 [User Stories](./user-stories.md#7-后续需求场景)。
+
+项目活动汇总独立于上述应用中心计划，范围见 [FR-14](./prd.md#fr-14-项目活动汇总)。
+计数规则由[活动逻辑](./logic-design.md#9-项目活动汇总)定义，入口与级联菜单见
+[活动界面](./ui-design.md#10-项目活动汇总)，数据加载与会话跳转见
+[技术设计](./technical-design.md#12-项目活动汇总)。此处“活动”指当前运行或待处理会话，
+与用于审计的“运行记录”不同；已完成未读面板属于后续范围，本次未实现。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、产品边界、功能要求与产品验收 |
+| [User Stories](./user-stories.md) | 用户场景及 Given/When/Then 验收 |
+| [功能逻辑设计](./logic-design.md) | 分类规则、入口状态、优先级与失败结果 |
+| [UI 设计](./ui-design.md) | 侧栏信息架构、控件、文案、键盘和响应式行为 |
+| [技术设计](./technical-design.md) | 现有模块映射、状态契约、持久化和实施顺序 |
+| [实施进度](./progress.md) | 项目活动级联的生产实现与验证记录 |
+| [应用中心交互 Demo](./navigation-demo.html) | 对比六个候选方案；配套 CSS 和 JS 仅服务原型 |
+
+Demo 可直接在浏览器中打开，支持方案切换、浅深主题、添加、移除、排序和商店模拟。
+六个方案共用本次页面会话内的应用配置，刷新后恢复默认。商店、资源指标和工具内容均为
+演示数据，不执行真实安装或本机操作。窄屏上下排列侧栏与输入区，桌面展示完整应用布局。
+这些方案用于讨论最底部应用中心；其中商店页、商店应用安装与 F 方案属于未来交互参考，
+不纳入首期实现或验收。首期产品只提供内置应用；Demo 暂保留远期示例以便后续讨论。
+底部输入区共用一个简化候选布局：附件、语音、Runtime、模式和发送位于主操作行，专家、
+知识范围及 Runtime 专属选项通过“选项”展开，非默认选择显示为可移除标签。可体验文件名
+附件、模拟语音、模板填入、原生命令选择、8 秒模拟回复、发送排队、立即插入、删除、停止，
+以及上下文详情和模拟压缩。文件只读取名称，语音使用固定示例文本，不录音、不上传、不调用 AI。
+这是输入区设计讨论用的原型，尚未改变正式产品或替代现有 UI 规范。
+左上角项目选择器下方仅在有运行中或待处理会话时显示活动摘要，全部空闲时隐藏。点击摘要打开项目
+列表，悬停或点击项目向右展开会话子菜单，点击会话才切换项目与对话。子菜单与项目列表
+相接，项目行保留子菜单箭头，会话行只显示名称与状态。支持上下方向键选择、右键进入、左键或 Esc 返回，顶层 Esc 关闭；窄屏在同一浮层内
+进入会话层，并提供返回按钮。页面上方可切换“有待处理、仅运行中、仅当前项目运行、全部
+空闲”四种场景。项目与会话均为演示数据；该级联交互已接入正式产品活动入口，范围与
+验证记录见[实施进度](./progress.md)。
+按最新讨论，Demo 已移除左侧系统工具快捷区：文件、终端、浏览器和资源监控只在右侧
+工作栏 Tab 中演示，不列入应用中心。上方正式文档仍保留原设计，待方案确定后同步。
+
+六个方案共用“我的应用”区：通过 ＋ 或“全部应用”选择常驻应用，编辑时可拖动或使用
+上下箭头排序、移除入口。未常驻的已安装应用仍可从“全部应用”打开。商店包含“项目管理”
+和“阅读空间”应用示例，支持仅安装或安装并常驻左侧菜单，常驻不表示后台运行。
+常驻应用在本次页面会话内跨方案保持一致；“恢复默认应用”重置安装与常驻配置。
+移除入口不会卸载应用或关闭当前页面，刷新后恢复默认。
+
+魔法笔记提供应用中心“设置”、笔记页面“笔记设置”和全局设置演示入口，均打开同一设置
+面板，共用本次页面会话内的配置。面板沿用现有选项：显示未完成待办数量、AI 评论方式
+（即时／保存后自动／保存后手动）、AI 评论形式（长评 + 要点／长评／要点）。现有“显示
+魔法笔记入口”在原型中与“常驻左侧菜单”统一，不额外增加功能启停开关。侧栏待办数为
+固定的 3 项演示数据。修改即时生效于原型，不调用 AI 或写入真实应用设置。
+
+| 方案 | 讨论重点 |
+| --- | --- |
+| A：紧凑入口 | 从底部向上展开应用列表 |
+| B：应用宫格 | 在展开面板中展示应用图标、名称和常驻操作 |
+| C：应用预览 | 用卡片说明应用用途 |
+| D：搜索启动台 | 搜索打开能力，支持 Ctrl / Command K、方向键与 Enter |
+| E：常驻管理 | 已常驻应用优先排列，可取消常驻或打开 |
+| F：商店发现（未来） | 默认展开模拟商店，不纳入首期 |
+
+D 参考 [Raycast](https://www.raycast.com/) 的搜索启动与扩展发现方式。早期方案参考过
+Notion 收藏和 VS Code Profiles，当前版本已移除场景工具包与快捷区。
+原型支持 URL 的 `#launcher`、`#favorites`、
+`#scenes` 等片段直接打开指定方案。
+
+## 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| 系统入口 | GoodBuddy 工作流程或审计所必需的固定入口，用户不能卸载、隐藏或改变类型 |
+| 应用 | 在主内容区打开完整一级页面的功能，可显示在“当前对话”所在的主导航区 |
+| 系统工具 | GoodBuddy 自带且不可卸载的辅助能力，包括文件、终端、浏览器和资源监控，由右侧助手工作栏 Tab 承载 |
+| 插件应用 | 未来由插件提供的一级页面入口 |
+| 插件工具 | 未来由插件提供的辅助面板或命令入口 |
+| 快捷入口 | 只负责打开或聚焦能力，不复制该能力的界面和业务状态 |
+
+## 相关文档
+
+- [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md)
+- [通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)
+- [助手工作栏多终端页签 PRD](../assistant-workbar/terminal-tabs-prd.md)
+- [智能心跳 PRD](../smart-heartbeat/prd.md)
+- [知识库功能文档](../knowledge-base/README.md)
@@ -0,0 +1,196 @@
+# 应用导航与系统工具入口功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 关联 User Stories | [User Stories](./user-stories.md) |
+
+## 1. 不变量
+
+1. “当前对话”“运行记录”和“设置”始终是系统入口。
+2. 运行记录不进入工具注册表、应用显隐设置或插件市场。
+3. 文件浏览器、终端、浏览器和资源监控始终是系统工具，不能卸载或被插件替换。
+4. 左下角只提供快捷入口，工具内容仍由助手工作栏承载。
+5. 隐藏应用不等于停用功能，也不删除、迁移或清理业务数据。
+6. 快捷入口不能扩大执行空间、文件、PTY、网络或浏览器权限。
+
+## 2. 入口模型
+
+```ts
+type NavigationContribution =
+  | {
+      type: 'system-entry'
+      id: 'chat' | 'activity' | 'settings'
+      placement: 'primary-start' | 'primary-end' | 'footer'
+    }
+  | {
+      type: 'application'
+      id: 'magic-notes' | 'knowledge' | 'heartbeat'
+      source: 'builtin'
+      visible: boolean
+    }
+  | {
+      type: 'system-tool'
+      id: 'workspace' | 'terminal' | 'browser' | 'resources'
+      workbarAppId: 'workspace' | 'terminal' | 'browser' | 'resources'
+    }
+```
+
+该模型只覆盖首期入口。插件贡献模型随插件 Host、权限和生命周期另行设计。
+
+## 3. 主导航组合规则
+
+主导航按以下顺序计算：
+
+```text
+当前对话
+可见的内置应用
+运行记录
+```
+
+当前对话和运行记录不参与排序。首期内置应用默认顺序为魔法笔记、知识库、智能心跳；显隐
+设置只从中移除对应项，不改变固定入口的位置。
+
+### 3.1 应用可见性与业务状态
+
+| 导航可见 | 功能启用 | 结果 |
+| --- | --- | --- |
+| 是 | 是 | 显示入口并允许进入 |
+| 否 | 是 | 隐藏入口，后台和数据保持原状 |
+| 是 | 否 | 不显示不可用入口；设置页保留启用路径 |
+| 否 | 否 | 不显示入口，保留符合该功能自身规则的数据 |
+
+“功能启用”由各应用现有产品设置负责。例如魔法笔记启停仍使用原设置；导航偏好不能覆盖它。
+
+## 4. 系统工具打开规则
+
+### 4.1 通用流程
+
+```text
+用户激活工具按钮
+  -> 校验按钮仍可用
+  -> 向助手工作栏发送打开意图
+  -> 工作栏按应用实例策略查找或创建实例
+  -> 展开工作栏
+  -> 激活目标实例
+  -> 把焦点移入面板标题或首个主要控件
+```
+
+若创建失败，工作栏保持展开并在对应能力位置显示错误；主页面和其他工作栏实例不被清空。
+
+### 4.2 决策表
+
+| 工具 | 匹配实例存在 | 匹配实例不存在 | 上下文不可用 |
+| --- | --- | --- | --- |
+| 文件 | 激活不可关闭的单实例并保留其跟随或固定状态 | 仅在迁移或布局修复时补回 `workspace` | 打开面板并显示目录修复入口 |
+| 终端 | 激活当前执行空间最近的 `starting` 或 `running` 实例 | 创建一个绑定当前执行空间的实例 | 没有项目时使用本机 Home |
+| 浏览器 | 激活绑定当前 Conversation 的最近使用实例 | 创建绑定当前 Conversation 的新实例 | 激活最近使用实例；不存在时创建待绑定实例 |
+| 资源监控 | 激活 `resources` 单实例 | 创建本机 `resources` 单实例 | 部分指标不可用时显示原因并保留其余指标 |
+
+文件保持单一实例原有绑定。浏览器快捷入口按当前 Conversation 匹配最近使用实例，而工作栏
+“+”始终新建浏览器实例。固定目标失效时显示该目标的修复状态，不回退到当前项目、默认
+工作区或当前会话。
+
+`closing`、`exited`、`interrupted` 和 `failed` 终端不属于可复用实例。当前执行空间只有这些
+终端时，快捷按钮创建新实例并保留原 Tab 的历史状态。用户需要额外的并行终端时使用工作栏
+“+”或终端面板中的既有创建命令。
+
+### 4.3 选中与状态
+
+工具按钮满足以下条件时显示选中：助手工作栏已展开，且当前活动实例的 `appId` 与工具映射
+一致。只有实例存在但未激活时不显示选中。
+
+徽标优先级为：等待用户处理 > 错误 > 运行中 > 无徽标。同一按钮只显示一个视觉徽标，
+可访问名称包含完整状态。
+
+资源监控首期不在后台采样，因此不显示负载告警徽标。只有资源面板是工作栏当前活动实例且
+工作栏已展开时，资源按钮才显示选中状态。
+
+### 4.4 资源采样状态
+
+```text
+inactive -> warming -> loading -> live
+                              -> partial
+                              -> error
+live/partial/error -> loading
+warming/loading/live/partial/error -> inactive
+```
+
+- `inactive`：资源面板未处于可见活动状态，没有采样定时器。
+- `warming`：首次进入或停止后恢复，建立 CPU 和磁盘 IO 区间基线；内存仍可立即显示。
+- `loading`：正在请求后续样本；请求未结束时跳过后续时钟触发。
+- `live`：所有首期指标可用，按 2 秒间隔追加样本。
+- `partial`：至少一个指标可用；不可用项携带稳定错误码，其他指标继续更新。
+- `error`：本次没有任何可用指标，保留已有历史；自动时钟或手动操作可以重试。
+
+资源面板为活动实例、工作栏展开且 `document.visibilityState` 为 `visible` 时才离开 `inactive`。
+任一条件失效即停止定时器并重置区间基线。历史队列只保留最后 150 个样本；时间间隔较长或
+采样失败时保留真实时间缺口，不补零或伪造中间数据。
+
+## 5. 设置保存规则
+
+应用导航偏好与应用业务启停分开保存。Switch 每次切换立即提交完整目标集合；请求完成前禁用
+三个应用显隐 Switch，下一次操作基于最新确认结果提交，防止并发更新互相覆盖。
+
+保存失败时：
+
+- 主导航和 Switch 恢复最后一次成功保存的偏好。
+- 设置行显示可重试错误。
+- 不回滚或修改各应用的业务状态。
+
+## 6. 与需求的对应关系
+
+| 逻辑 | PRD | User Stories |
+| --- | --- | --- |
+| 固定入口不变量 | FR-1、FR-2 | US-A1、US-A2 |
+| 应用显隐和失败恢复 | FR-3、FR-4、FR-11、FR-12 | US-B1、US-B2、US-B4、US-B5 |
+| 工具打开决策表 | FR-5 至 FR-10 | US-C1 至 US-C7 |
+| 资源采样状态 | FR-9 | US-C6 |
+| 无障碍与窄窗口 | FR-13 | US-D1、US-D2 |
+
+## 7. 逻辑完整性评估
+
+首期规则已覆盖固定入口、应用显隐、保存失败、系统工具匹配与显式多实例差异、本机 Home、
+托管 SSH、无活动会话、目录失效、资源部分可用、采样停止、权限边界、键盘和窄窗口。其他
+工具面板内部的取消、超时、
+连接恢复和固定目标失效继续由助手工作栏负责，本功能不复制这些状态机。
+
+## 8. 后续产品决策
+
+- 插件工具上线后，快捷栏允许固定的最大数量及溢出规则。
+- 插件应用是否允许用户排序，以及固定系统入口之间允许的排序范围。
+
+这些决策不影响首期四个系统工具的固定入口和内置应用显隐实现。
+
+## 9. 项目活动汇总
+
+对应 [FR-14](./prd.md#fr-14-项目活动汇总)，按 Conversation ID 聚合，每条会话最多一行。
+数据来源为活动会话 ID、会话中的流式消息及待回答/待审批请求，以及全部可见的运行中或
+等待处理 Task；不能只取当前项目、当前搜索结果或每条会话的最新 Task。
+
+| 优先级（高到低） | 条件 | 汇总类别 |
+| --- | --- | --- |
+| 待回答 | 消息有待回答问题 | 待处理 |
+| 待审批 | 消息有待审批请求 | 待处理 |
+| Task 等待处理 | Task 为 `waiting_approval`，尚无更具体的消息状态 | 待处理 |
+| 运行中 | 活动会话 ID、`streaming` 消息或运行中 Task | 运行中 |
+
+同一会话只采用最高优先级状态；Task 的 `waiting_approval` 也可能对应提问，不能直接
+标成待审批。“待处理”和“运行中”数量互斥，全局总数为两者之和；项目计数使用相同结果。
+项目归属优先取会话元数据，缺少会话时取 Task 元数据；无项目归属的活动只计入全局汇总。
+
+历史排队项、仅待调度的 Task、终态 Task 和未读标记本身不构成活动。活动结束且没有其他
+运行或等待条件时移除该行，不能因历史任务或未读状态继续计数。
+
+级联菜单先按项目归属聚合活动行，沿用本地、SSH Host、通道的稳定项目顺序；缺少项目
+元数据的归属组及“未归属项目”组放在已知项目之后。无归属组只用于访问这些会话，不增加
+项目计数。每个项目内先列待处理会话，再列运行中会话，同类别保留来源顺序。
+
+展开项目只改变菜单层级，不导航。选中项目的活动全部结束后返回项目列表；全局活动结束后
+关闭菜单并隐藏摘要入口。后台更新保留仍存在的焦点项，删除焦点项时将焦点
+移至当前层可用项。关闭菜单后，新的活动只恢复摘要，不会自动重新打开菜单。
@@ -0,0 +1,133 @@
+:root {
+  color-scheme: light;
+  --surface-canvas: #e8f0f5; --surface-raised: #fff; --surface-subtle: #f4f8fb;
+  --text-primary: #17263a; --text-secondary: #4f6278; --border-default: #cedce7;
+  --accent: #086fc7; --accent-subtle: #e8f4ff; --accent-selected: #a7cfea;
+  --font-family-ui: "Inter Variable", "PingFang SC", "Microsoft YaHei UI", "Noto Sans SC Variable", system-ui, sans-serif;
+  --radius-control: 10px; --radius-card: 14px;
+  --warning: #865200;
+}
+[data-theme="dark"] { --warning: #f2bd66; }
+.project-lab { max-width: 1440px; margin: 0 auto 12px; display: flex; align-items: center; flex-wrap: wrap; gap: 8px 16px; color: var(--text-secondary); font-size: 12px; }
+.project-lab select { font: inherit; color: var(--text-primary); background: var(--surface-raised); padding: 4px 8px; border: 1px solid var(--border-default); border-radius: var(--radius-control); }
+.project-entry { position: relative; margin-bottom: 12px; }
+#project-trigger { width: 100%; display: flex; align-items: center; gap: 8px; text-align: left; border: 1px solid var(--border-default); }
+#project-name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.project-waiting { color: var(--warning); font-weight: 600; }
+#activity-trigger { display: flex; justify-content: space-between; align-items: center; gap: 8px; margin: -8px 0 12px; padding: 4px 8px; color: var(--text-secondary); font-size: 11px; text-align: left; }
+#project-activity { position: fixed; inset: auto; margin: 0; padding: 0; border: 1px solid var(--border-default); border-radius: var(--radius-control); background: var(--surface-raised); color: var(--text-primary); max-width: calc(100vw - 32px); }
+#project-activity:popover-open { display: flex; align-items: stretch; }
+#project-activity > section { width: 264px; max-width: calc(100vw - 34px); max-height: min(480px, calc(100dvh - 32px)); overflow: auto; padding: 8px; }
+#project-activity h3 { margin: 8px; font-size: 11px; font-weight: 500; color: var(--text-secondary); overflow-wrap: anywhere; }
+#activity-project-list > p { padding: 8px; }
+#activity-project-list button { display: grid; grid-template-columns: minmax(0, 1fr) auto; width: 100%; gap: 4px 8px; text-align: left; }
+#activity-project-list button > span:first-child { overflow-wrap: anywhere; }
+#activity-project-list small { grid-column: 1; font-size: 11px; color: var(--text-secondary); }
+#activity-project-list button > span:last-child { grid-column: 2; grid-row: 1 / 3; align-self: center; }
+#activity-project-list [aria-expanded="true"] { background: var(--accent-subtle); color: var(--accent); }
+#activity-sessions { border-left: 1px solid var(--border-default); }
+#activity-back { display: none; font-size: 12px; color: var(--accent); }
+#project-activity.activity-left { flex-direction: row-reverse; }
+.activity-left #activity-sessions { border-left: 0; border-right: 1px solid var(--border-default); }
+.activity-compact.has-submenu #activity-projects { display: none; }
+.activity-compact #activity-back { display: block; }
+.activity-compact #activity-sessions { border: 0; }
+#project-menu { position: fixed; inset: auto; margin: 0; width: min(300px, calc(100vw - 32px)); max-height: calc(100dvh - 32px); overflow: auto; padding: 8px; border: 1px solid var(--border-default); border-radius: var(--radius-control); background: var(--surface-raised); color: var(--text-primary); }
+#project-list h3, #activity-list h3 { margin: 8px; font-size: 11px; font-weight: 500; color: var(--text-secondary); }
+#project-list button { width: 100%; display: flex; flex-wrap: wrap; align-items: center; gap: 4px 8px; text-align: left; }
+.project-row-name { flex: 1; min-width: 0; overflow-wrap: anywhere; }
+#project-list [aria-current="true"] { background: var(--accent-subtle); color: var(--accent); }
+#project-list small { width: 100%; display: flex; gap: 12px; font-size: 11px; color: var(--text-secondary); }
+#activity-list button { display: grid; grid-template-columns: minmax(0, 1fr); width: 100%; text-align: left; padding: 12px; }
+#activity-list strong { font-weight: 500; overflow-wrap: anywhere; }
+#activity-list small { grid-column: 1; color: var(--text-secondary); overflow-wrap: anywhere; }
+.history button small { display: block; font-size: 11px; color: var(--text-secondary); }
+[data-theme="dark"] { color-scheme: dark; --surface-canvas: #07131f; --surface-raised: #102335; --surface-subtle: #162c40; --text-primary: #edf7ff; --text-secondary: #b5c6d5; --border-default: #29445a; --accent: #72c5ff; --accent-subtle: #123b5b; --accent-selected: #28668f; }
+* { box-sizing: border-box; }
+body { margin: 0; padding: 24px 32px; font: 13px/1.6 var(--font-family-ui); background: var(--surface-subtle); color: var(--text-primary); }
+button, input, textarea { font: inherit; color: inherit; }
+button { cursor: pointer; border: 0; background: transparent; border-radius: var(--radius-control); padding: 8px 12px; }
+button:hover { background: var(--accent-subtle); color: var(--accent); }
+button:focus-visible, input:focus-visible, textarea:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+button:disabled { opacity: .45; cursor: default; }
+svg { width: 18px; height: 18px; fill: none; stroke: currentColor; stroke-width: 1.6; stroke-linecap: round; stroke-linejoin: round; vertical-align: middle; flex-shrink: 0; }
+p, h1, h2 { margin: 0; } h1 { font-size: 30px; font-weight: 550; margin: 12px 0; letter-spacing: -.8px; } h2 { font-size: 24px; }
+.muted, .eyebrow { color: var(--text-secondary); }.eyebrow { font-size: 11px; letter-spacing: 1px; }
+.lab-header, .design-note, .lab-footer { display: flex; align-items: center; justify-content: space-between; gap: 24px; max-width: 1440px; margin: auto; }
+.lab-header strong { font-size: 16px; }.lab-header p { color: var(--text-secondary); font-size: 12px; margin-top: 4px; }
+.variants { display: grid; grid-template-columns: repeat(3, 1fr); padding: 4px; border: 1px solid var(--border-default); border-radius: var(--radius-control); }
+.variants button[aria-pressed="true"] { background: var(--surface-raised); color: var(--accent); box-shadow: 0 1px 3px var(--border-default); }
+.design-note { margin: 24px auto 12px; font-size: 12px; }.design-note #variant-label { color: var(--accent); font-weight: 600; white-space: nowrap; }.design-note p { flex: 1; }.design-note > span:last-child { color: var(--text-secondary); font-size: 11px; }
+.app { display: flex; max-width: 1440px; height: min(780px, calc(100dvh - 204px)); min-height: 590px; margin: auto; border: 1px solid var(--border-default); border-radius: var(--radius-card); overflow: hidden; background: var(--surface-raised); }
+.sidebar { width: 278px; flex: 0 0 278px; background: var(--surface-canvas); display: flex; flex-direction: column; padding: 20px 12px 8px; border-right: 1px solid var(--border-default); }
+.brand { display: flex; gap: 8px; align-items: center; padding: 0 8px 24px; }.brand > .muted { margin-left: auto; font-size: 11px; }.brand-mark { display: grid; place-items: center; width: 32px; height: 32px; background: var(--text-primary); color: var(--surface-raised); border-radius: 10px; font-weight: 650; font-size: 12px; }
+.new-chat { border: 1px solid var(--border-default); background: var(--surface-raised); text-align: left; margin-bottom: 16px; }.new-chat span { margin-right: 8px; }
+.navigation { display: grid; gap: 3px; }.navigation button, .fixed-entry button { display: flex; align-items: center; gap: 10px; text-align: left; padding: 9px 10px; }.navigation .selected { background: var(--accent-subtle); color: var(--accent); }
+.history { flex: 1; min-height: 72px; overflow: auto; padding: 24px 0 8px; }.history .eyebrow { display: block; padding: 0 10px 8px; }.history button { display: block; width: 100%; text-align: left; color: var(--text-secondary); font-size: 12px; }
+.fixed-entry { border-top: 1px solid var(--border-default); padding: 8px 0; }.fixed-entry button { width: 100%; }
+.shortcuts { border-top: 1px solid var(--border-default); padding-top: 12px; max-height: 52%; overflow: auto; flex-shrink: 0; }.section-label { display: flex; align-items: center; justify-content: space-between; margin-bottom: 8px; padding-left: 8px; font-size: 11px; color: var(--text-secondary); }.section-label button { font-size: 11px; padding: 4px 8px; }
+.shortcut-list { display: grid; gap: 4px; }.shortcut-item { min-width: 0; }.shortcut-button { width: 100%; display: flex; align-items: center; justify-content: center; gap: 8px; }.shortcut-button.active { color: var(--accent); background: var(--accent-subtle); }.shortcut-button .icon-tile { display: grid; place-items: center; }.shortcut-button .item-name { font-size: 11px; }
+[data-variant="dock"] .shortcut-list { grid-template-columns: repeat(5, minmax(0, 1fr)); background: var(--surface-raised); padding: 4px; border: 1px solid var(--border-default); border-radius: var(--radius-card); }
+[data-variant="dock"] .shortcut-button { padding: 10px 0; flex-direction: column; gap: 4px; }[data-variant="dock"] .shortcut-button .item-name { display: none; }[data-variant="dock"] .shortcut-list.editing { grid-template-columns: repeat(3, minmax(0, 1fr)); }[data-variant="dock"] .editing .item-name { display: block; }
+.store-link { margin-top: 8px; padding: 8px; display: flex; align-items: center; width: 100%; gap: 8px; text-align: left; font-size: 12px; }.store-link span:last-child { margin-left: auto; color: var(--text-secondary); }
+[data-variant="grid"] .shortcut-list { grid-template-columns: repeat(3, minmax(0, 1fr)); }[data-variant="grid"] .shortcut-button { flex-direction: column; gap: 4px; padding: 8px 4px; }[data-variant="grid"] .icon-tile { width: 36px; height: 36px; border: 1px solid var(--border-default); border-radius: var(--radius-control); background: var(--surface-raised); }
+.featured { border: 1px solid var(--border-default); border-radius: var(--radius-control); padding: 12px; margin-top: 12px; background: var(--surface-raised); position: relative; }.featured p { font-size: 11px; color: var(--text-secondary); margin: 4px 0; }.featured .dismiss { position: absolute; right: 4px; top: 4px; padding: 0 8px; }.featured .feature-open { color: var(--accent); padding: 4px 0 0; font-size: 11px; }
+[data-variant="cards"] .shortcut-list { grid-template-columns: repeat(2, minmax(0, 1fr)); }[data-variant="cards"] .shortcut-button { background: var(--surface-raised); border: 1px solid var(--border-default); padding: 12px 8px; flex-direction: column; align-items: flex-start; }[data-variant="cards"] .shortcut-button .item-name { font-size: 12px; }.card-detail { font-size: 11px; color: var(--text-secondary); text-align: left; }.mini-meter { display: flex; gap: 3px; align-items: end; height: 24px; }.mini-meter i { display: block; width: 5px; background: var(--accent-selected); border-radius: 2px; }.mini-meter i:nth-child(3n) { background: var(--accent); }
+.edit-actions { display: flex; justify-content: center; }.edit-actions button { padding: 2px 6px; font-size: 12px; }.sidebar-footer { display: flex; justify-content: space-between; align-items: center; margin-top: 8px; padding-left: 8px; font-size: 11px; }
+.workspace { flex: 1; min-width: 0; display: flex; flex-direction: column; }.workspace-header { display: flex; justify-content: space-between; padding: 16px 24px; border-bottom: 1px solid var(--border-default); font-size: 12px; }.conversation { flex: 1; padding: 64px 40px 24px; max-width: 740px; width: 100%; margin: auto; display: flex; flex-direction: column; justify-content: center; align-items: flex-start; }.suggestions { display: flex; gap: 12px; margin-top: 32px; flex-wrap: wrap; }.suggestions button { border: 1px solid var(--border-default); font-size: 12px; }.suggestions span { margin-left: 24px; }
+.composer-area { margin: 16px 24px 8px; flex-shrink: 0; }
+.composer { padding: 12px; border: 1px solid var(--border-default); border-radius: var(--radius-card); background: var(--surface-subtle); }
+.composer:focus-within { border-color: var(--accent-selected); }
+.composer textarea { display: block; width: 100%; height: 76px; min-height: 76px; max-height: 180px; padding: 4px; border: 0; resize: none; background: transparent; line-height: 1.8; }
+.composer textarea::placeholder { color: var(--text-secondary); font-size: 12px; }
+.composer-toolbar { display: flex; align-items: center; gap: 2px; flex-wrap: wrap; margin-top: 8px; }
+.composer-toolbar button { padding: 6px 8px; font-size: 12px; white-space: nowrap; }
+.composer-toolbar .composer-icon { width: 32px; height: 32px; padding: 4px; font-size: 20px; }
+.composer-select select { max-width: 132px; padding: 6px 2px; border: 0; background: transparent; cursor: pointer; font: inherit; font-size: 12px; color: var(--text-primary); }
+select option { background: var(--surface-raised); color: var(--text-primary); }
+select:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+.composer-actions { display: flex; gap: 4px; margin-left: auto; }
+#send { width: 32px; height: 32px; padding: 0; font-size: 20px; background: var(--accent); color: var(--surface-raised); }
+#voice[aria-pressed="true"] { background: var(--accent-subtle); color: var(--accent); }
+.composer-meta { display: flex; justify-content: space-between; align-items: center; gap: 8px; min-height: 32px; color: var(--text-secondary); font-size: 10px; }
+.composer-meta button { font-size: 10px; padding: 4px; }
+#composer-tags { display: flex; flex-wrap: wrap; gap: 6px; padding: 0 4px 8px; max-height: 96px; overflow: auto; }
+#composer-tags button { max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; padding: 3px 8px; font-size: 11px; background: var(--accent-subtle); color: var(--accent); }
+#composer-options, #context-details { position: fixed; inset: auto; margin: 0; width: min(320px, calc(100vw - 32px)); max-height: min(460px, 70dvh); overflow: auto; padding: 16px; border: 1px solid var(--border-default); border-radius: var(--radius-card); background: var(--surface-raised); color: var(--text-primary); box-shadow: 0 8px 32px #07131f26; font-size: 12px; }
+#composer-options header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 8px; }
+.option-row { display: flex; justify-content: space-between; align-items: center; gap: 12px; padding: 10px 0; }
+.option-row select { width: 166px; padding: 6px; border: 1px solid var(--border-default); border-radius: 6px; font: inherit; background: var(--surface-subtle); color: var(--text-primary); }
+#composer-options fieldset { margin: 8px 0; padding: 12px 0; border: 0; border-top: 1px solid var(--border-default); }
+#composer-options fieldset label { display: inline-flex; align-items: center; gap: 4px; margin-right: 12px; }
+#composer-options input { accent-color: var(--accent); }
+#composer-options p { margin-top: 12px; font-size: 11px; }
+#context-details p { margin: 8px 0; color: var(--text-secondary); }
+#context-details progress { width: 100%; accent-color: var(--accent); }
+#compact { margin-top: 8px; color: var(--accent); background: var(--accent-subtle); }
+#demo-queue { max-height: 96px; overflow: auto; margin-bottom: 8px; }
+.queue-row { display: flex; align-items: center; gap: 8px; font-size: 11px; }
+.queue-row span { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.queue-row button { flex-shrink: 0; padding: 4px; font-size: 11px; }
+.workbar { width: 280px; flex-shrink: 0; border-left: 1px solid var(--border-default); background: var(--surface-subtle); }.workbar header { display: flex; align-items: center; justify-content: space-between; padding: 12px 16px; border-bottom: 1px solid var(--border-default); }#tool-content { padding: 24px 16px; }.metric { margin: 20px 0; }.metric strong { float: right; }.metric progress { width: 100%; accent-color: var(--accent); }.file-row { padding: 12px 0; border-bottom: 1px solid var(--border-default); }pre { white-space: pre-wrap; overflow-wrap: anywhere; font-size: 12px; }
+.lab-footer { margin-top: 12px; font-size: 12px; color: var(--text-secondary); }
+dialog { width: min(580px, calc(100% - 32px)); max-height: 85dvh; border: 1px solid var(--border-default); padding: 24px; border-radius: var(--radius-card); background: var(--surface-raised); color: var(--text-primary); }dialog::backdrop { background: #07131f80; }dialog header { display: flex; justify-content: space-between; align-items: start; }dialog > p { margin: 12px 0 16px; }dialog input { width: 100%; padding: 10px 12px; background: var(--surface-subtle); border: 1px solid var(--border-default); border-radius: var(--radius-control); }.catalog-row { display: flex; align-items: center; gap: 12px; padding: 16px 0; border-bottom: 1px solid var(--border-default); }.catalog-row > div { flex: 1; }.catalog-row p { font-size: 11px; color: var(--text-secondary); }.catalog-row button { color: var(--accent); background: var(--accent-subtle); font-size: 12px; }dialog footer { font-size: 11px; color: var(--text-secondary); margin-top: 16px; }
+#toast { position: fixed; bottom: 24px; left: 50%; transform: translateX(-50%); padding: 10px 20px; border-radius: var(--radius-control); background: var(--text-primary); color: var(--surface-raised); pointer-events: none; opacity: 0; }#toast.visible { opacity: 1; }
+[hidden] { display: none !important; }
+#page-actions { margin-left: auto; }#page-actions button { padding: 4px 8px; font-size: 12px; }.note-count { margin-left: auto; padding: 0 6px; background: var(--accent-subtle); border-radius: var(--radius-control); color: var(--accent); }.note-setting-row { display: flex; gap: 16px; align-items: center; justify-content: space-between; padding: 16px 0; border-bottom: 1px solid var(--border-default); }.note-setting-row p, .note-setting-options p { font-size: 11px; color: var(--text-secondary); margin-top: 6px; }.demo-switch { width: 36px; height: 20px; border-radius: 20px; border: 1px solid var(--text-secondary); background: var(--surface-canvas); padding: 2px; flex-shrink: 0; }.demo-switch::after { content: ''; display: block; width: 14px; height: 14px; border-radius: 50%; background: var(--text-secondary); }.demo-switch[aria-checked="true"] { background: var(--accent); border-color: var(--accent); }.demo-switch[aria-checked="true"]::after { margin-left: 16px; background: var(--surface-raised); }.note-setting-options { border: 0; padding: 16px 0; margin: 0; min-width: 0; }.note-setting-options legend { padding-top: 16px; font-weight: 550; }.note-segments { display: flex; padding: 4px; gap: 4px; background: var(--surface-subtle); border: 1px solid var(--border-default); border-radius: var(--radius-control); }.note-segments button { flex: 1; padding: 8px 4px; font-size: 12px; }.note-segments [aria-pressed="true"] { color: var(--accent); background: var(--surface-raised); box-shadow: 0 1px 3px var(--border-default); }.note-settings-preview { padding: 16px; background: var(--accent-subtle); border-radius: var(--radius-control); }.note-settings-preview small { color: var(--text-secondary); font-size: 11px; }#back-to-apps { margin-bottom: 12px; padding-left: 0; color: var(--accent); }#note-settings-summary { margin: 16px 0; }
+.sidebar-footer { border-top: 1px solid var(--border-default); padding: 8px 0 0; gap: 4px; }#center-entry { flex: 1; min-width: 0; }#open-center { width: 100%; display: flex; align-items: center; gap: 10px; padding: 8px; text-align: left; }#open-center strong { font-size: 13px; font-weight: 550; }#open-center small { display: block; font-size: 11px; color: var(--text-secondary); }.entry-arrow { margin-left: auto; }.tool-tabs { display: flex; padding: 8px; gap: 2px; }.tool-tabs button { flex: 1; padding: 8px 4px; font-size: 12px; }.tool-tabs [aria-selected="true"] { background: var(--accent-subtle); color: var(--accent); }.center-switch { display: flex; gap: 4px; padding-bottom: 12px; }.center-switch [aria-pressed="true"] { background: var(--accent-subtle); color: var(--accent); }.center-app { display: flex; gap: 12px; align-items: start; padding: 16px 0; border-bottom: 1px solid var(--border-default); }.center-app > svg { margin-top: 4px; color: var(--accent); }.center-app-info { flex: 1; }.center-app p { color: var(--text-secondary); font-size: 11px; }.center-actions { display: flex; gap: 4px; flex-wrap: wrap; }.center-actions button { font-size: 11px; background: var(--accent-subtle); color: var(--accent); }.center-actions [aria-pressed="true"] { border: 1px solid var(--accent-selected); }
+dialog[data-variant="dock"], dialog[data-variant="grid"], dialog[data-variant="favorites"] { position: fixed; left: 48px; bottom: 100px; top: auto; right: auto; margin: 0; width: min(520px, calc(100% - 32px)); max-height: 72dvh; }
+dialog[data-variant="grid"] #catalog-items { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 12px; margin-top: 16px; }dialog[data-variant="grid"] .center-app { flex-direction: column; padding: 16px; border: 1px solid var(--border-default); border-radius: var(--radius-control); }dialog[data-variant="cards"] .center-app { padding: 24px 0; }dialog[data-variant="cards"] .center-app > svg { width: 32px; height: 32px; }dialog[data-variant="cards"] .app-detail { margin-top: 8px; font-size: 13px; }dialog[data-variant="favorites"] .app-detail { display: none; }dialog[data-variant="scenes"] .center-app { background: var(--surface-subtle); border: 1px solid var(--border-default); border-radius: var(--radius-card); padding: 20px; margin-top: 16px; flex-wrap: wrap; }dialog[data-variant="scenes"] .center-actions { width: 100%; justify-content: flex-end; }
+@media (max-width: 640px) { dialog[data-variant] { left: 16px; right: 16px; bottom: 16px; top: auto; margin: 0; max-height: 85dvh; width: calc(100% - 32px); padding: 16px; }.center-app { flex-wrap: wrap; }.center-actions { width: 100%; }.app { flex-direction: column; }.app .sidebar { flex: 1; min-height: 0; }.app .workspace { display: block; flex: 0 0 auto; }.app .workspace .conversation, .app .workspace .composer { display: none; }.app .workspace-header { padding: 8px 16px; align-items: center; }.app .workbar { z-index: 2; } }
+.reference-note { max-width: 1440px; margin: 12px auto 0; display: flex; flex-wrap: wrap; gap: 8px 16px; color: var(--text-secondary); font-size: 11px; }.reference-note a { color: var(--accent); text-underline-offset: 3px; }
+.sidebar > * { flex-shrink: 0; }.sidebar .history { flex: 1 1 80px; min-height: 0; }.sidebar .shortcuts { flex-shrink: 1; min-height: 80px; }
+.sidebar .resident-apps { margin-top: 12px; min-height: 96px; flex-shrink: 1; display: flex; flex-direction: column; max-height: 240px; }.resident-apps .section-label { margin-bottom: 4px; flex-shrink: 0; }#resident-list { overflow: auto; min-height: 0; }.resident-row { display: flex; align-items: center; }.resident-row > button { display: flex; align-items: center; gap: 10px; padding: 8px 10px; flex: 1; min-width: 0; text-align: left; }.resident-row > button span { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }.resident-row [aria-current="page"] { background: var(--accent-subtle); color: var(--accent); }.resident-row[draggable="true"] { cursor: grab; }.resident-row .edit-actions { flex-shrink: 0; }.all-apps { display: flex; justify-content: space-between; padding: 6px 10px; font-size: 11px; color: var(--text-secondary); flex-shrink: 0; }.empty-apps { padding: 8px 10px; font-size: 11px; color: var(--text-secondary); }.app-placement { display: flex; flex-wrap: wrap; gap: 4px; margin-top: 8px; }.app-placement button { font-size: 11px; padding: 6px 8px; }.app-placement button[aria-pressed="true"] { border: 1px solid var(--accent-selected); }.app-catalog-row { align-items: flex-start; }.app-catalog-row > svg { margin-top: 4px; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+.launcher-trigger { display: flex; align-items: center; gap: 8px; width: 100%; padding: 12px 8px; border: 1px solid var(--border-default); background: var(--surface-raised); margin-bottom: 12px; font-size: 12px; }.launcher-trigger kbd { margin-left: auto; font: 10px var(--font-family-ui); color: var(--text-secondary); white-space: nowrap; }
+[data-variant="launcher"] .shortcut-list { grid-template-columns: repeat(4, minmax(0, 1fr)); }[data-variant="launcher"] .shortcut-button { flex-direction: column; padding: 8px 0; }[data-variant="launcher"] .icon-tile { height: 24px; }[data-variant="launcher"] .store-link { border-top: 1px solid var(--border-default); border-radius: 0; }
+[data-variant="favorites"] .section-label { padding-left: 0; }[data-variant="favorites"] .shortcut-list { gap: 0; }[data-variant="favorites"] .shortcut-button { justify-content: flex-start; padding: 8px 12px; }[data-variant="favorites"] .item-name { font-size: 12px; }[data-variant="favorites"] .shortcut-item { display: flex; align-items: center; }[data-variant="favorites"] .edit-actions { margin-left: auto; }[data-variant="favorites"] .store-link { margin-top: 12px; border: 1px dashed var(--border-default); }.count { padding: 0 6px; color: var(--text-secondary); }
+.scene-banner { display: flex; align-items: center; gap: 12px; margin: 0 4px 12px; padding: 12px; background: var(--accent-subtle); border-radius: var(--radius-control); }.scene-banner > svg { color: var(--accent); width: 24px; height: 24px; }.scene-banner .eyebrow { letter-spacing: 0; font-size: 10px; }.scene-count { margin-left: auto; font-size: 11px; color: var(--text-secondary); }.scene-label { display: block; }.scene-label select { font: inherit; font-weight: 600; color: var(--text-primary); background: transparent; border: 0; padding: 0; cursor: pointer; }.scene-label option { background: var(--surface-raised); }
+[data-variant="scenes"] .shortcut-list { grid-template-columns: repeat(2, minmax(0, 1fr)); }[data-variant="scenes"] .shortcut-button { border: 1px solid var(--border-default); background: var(--surface-raised); padding: 10px 8px; justify-content: flex-start; }.pack-preview { display: flex; gap: 8px; align-items: center; width: 100%; margin-top: 12px; padding: 12px 8px; text-align: left; background: var(--surface-raised); border: 1px solid var(--border-default); }.pack-preview strong { font-size: 11px; font-weight: 550; }.pack-preview small { display: block; color: var(--text-secondary); font-size: 10px; }.pack-preview > span:last-child { margin-left: auto; }.pack-symbol { color: var(--accent); }
+.catalog-pack { padding: 20px 0; border-bottom: 1px solid var(--border-default); }.catalog-pack h3 { margin: 8px 0; font-size: 18px; font-weight: 550; }.pack-art { display: grid; place-items: center; float: right; width: 56px; height: 56px; border: 1px solid var(--accent-selected); background: var(--accent-subtle); color: var(--accent); border-radius: var(--radius-card); }.pack-art svg { width: 28px; height: 28px; }.pack-includes { display: flex; flex-wrap: wrap; gap: 8px; margin: 16px 0; }.pack-includes span { padding: 4px 8px; font-size: 11px; background: var(--surface-subtle); border-radius: var(--radius-control); }.pack-includes svg { width: 14px; height: 14px; }.catalog-pack > button { border: 1px solid var(--accent-selected); color: var(--accent); background: var(--accent-subtle); }
+dialog[data-mode="launch"] { width: min(640px, calc(100% - 32px)); }dialog[data-mode="launch"] .catalog-row:focus-within { background: var(--accent-subtle); }.catalog-row { padding-left: 8px; padding-right: 8px; }
+@media (max-width: 1080px) { body { padding: 16px; }.app { position: relative; }.workbar { position: absolute; right: 0; top: 52px; bottom: 0; width: min(320px, 100%); box-shadow: -8px 0 24px var(--border-default); }.lab-header { flex-wrap: wrap; gap: 12px; }.design-note > span:last-child { display: none; }.conversation { padding: 32px 24px; } }
+@media (max-width: 640px) { body { padding: 12px; }.lab-header > div:first-child { flex: 1; }.variants { order: 3; width: 100%; }.variants button { flex: 1; padding: 8px 4px; font-size: 12px; }.design-note { align-items: flex-start; gap: 12px; }.app { height: auto; min-height: 0; }.app .sidebar { width: 100%; flex: 0 0 auto; border: 0; padding-top: 12px; }.brand { padding-bottom: 12px; }.app .history { display: none; }.app .workspace { display: flex; min-height: 320px; border-top: 1px solid var(--border-default); }.app .workspace .composer { display: block; }.composer-area { margin: 12px 12px 4px; margin-top: auto; }.composer-toolbar { gap: 2px; }.composer-select select { max-width: 108px; font-size: 11px; }.composer-toolbar button { font-size: 11px; padding: 6px; }.composer-toolbar .composer-icon { width: 28px; }.composer-meta { flex-wrap: wrap; gap: 0; }.shortcut-list { max-height: 300px; overflow: auto; }.lab-footer { align-items: flex-start; }.lab-footer button { white-space: nowrap; }.workbar { top: 0; width: 100%; }.design-note p { font-size: 11px; } }
@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>GoodBuddy · 应用中心设计实验</title>
+  <link rel="stylesheet" href="navigation-demo.css">
+  <script src="navigation-demo.js" defer></script>
+</head>
+<body>
+  <header class="lab-header">
+    <div><strong>GoodBuddy <span class="muted">/ 设计实验</span></strong><p>左下角应用中心 · 六个交互方案</p></div>
+    <div class="variants" role="group" aria-label="选择设计方案">
+      <button data-variant="dock" aria-pressed="true">A · 紧凑入口</button>
+      <button data-variant="grid" aria-pressed="false">B · 应用宫格</button>
+      <button data-variant="cards" aria-pressed="false">C · 应用预览</button>
+      <button data-variant="launcher" aria-pressed="false">D · 搜索启动台</button>
+      <button data-variant="favorites" aria-pressed="false">E · 常驻管理</button>
+      <button data-variant="scenes" aria-pressed="false">F · 商店发现</button>
+    </div>
+    <button id="theme">切换深色</button>
+  </header>
+  <div class="design-note"><span id="variant-label">A / 紧凑 Dock</span><p id="variant-description"></p><span>交互原型 · 商店与指标均为演示数据</span></div>
+  <div class="project-lab"><label>项目活动演示 <select id="project-scenario"><option value="waiting">有待处理</option><option value="running">仅运行中</option><option value="current">仅当前项目运行</option><option value="idle">全部空闲</option></select></label><span>有活动时显示摘要，悬停或点击项目向右展开会话。</span></div>
+  <main class="app" data-variant="dock">
+    <aside class="sidebar" aria-label="主侧栏">
+      <div class="brand"><span class="brand-mark">GB</span><strong>GoodBuddy</strong><span class="muted">个人空间</span></div>
+      <div class="project-entry"><button id="project-trigger" popovertarget="project-menu" aria-expanded="false" aria-controls="project-menu"><span id="project-name">GoodBuddy</span><span class="muted" aria-hidden="true">⌄</span></button></div>
+      <button id="activity-trigger" popovertarget="project-activity" aria-expanded="false" aria-controls="project-activity"><span id="activity-summary"></span><span aria-hidden="true">⌄</span></button>
+      <div id="project-menu" popover aria-label="切换项目"><div id="project-list"></div></div>
+      <div id="project-activity" popover aria-label="所有项目活动"><section id="activity-projects"><h3>所有项目活动</h3><div id="activity-project-list"></div></section><section id="activity-sessions" hidden><button id="activity-back">‹ 返回项目列表</button><h3 id="activity-project-title"></h3><div id="activity-list"></div></section></div>
+      <button class="new-chat" data-page="当前对话"><span>＋</span> 新对话</button>
+      <nav class="navigation" aria-label="应用导航">
+        <button class="selected" data-page="当前对话"><span data-icon="chat"></span>当前对话</button>
+      </nav>
+      <section class="resident-apps" aria-label="我的应用"><div class="section-label"><span>我的应用</span><div><button id="edit-apps">编辑</button><button data-catalog="apps" aria-label="管理常驻应用">＋</button></div></div><nav id="resident-list" aria-label="常驻应用"></nav><button class="all-apps" data-catalog="apps">全部应用 <span>›</span></button></section>
+      <div class="history"><span class="eyebrow">最近对话</span><button data-page="整理产品设计思路">整理产品设计思路</button><button data-page="本周工作计划">本周工作计划</button><button data-page="项目文档检索">项目文档检索</button></div>
+      <div class="fixed-entry"><button data-page="运行记录"><span data-icon="history"></span>运行记录</button></div>
+      <div class="sidebar-footer"><div id="center-entry"></div><button data-page="设置" aria-label="设置" title="设置"><span data-icon="settings"></span></button></div>
+    </aside>
+    <section class="workspace">
+      <header class="workspace-header"><span id="page-label">当前对话</span><div id="page-actions"></div><button id="toggle-workbar" aria-expanded="true" aria-controls="workbar">助手工作栏</button></header>
+      <div class="conversation" id="page-content">
+        <span class="eyebrow">LET'S MAKE SOMETHING</span>
+        <h1>从一个想法开始。</h1>
+        <p class="muted">对话留在这里，常用能力随手打开。</p>
+        <div class="suggestions"><button data-page="项目文档检索">查找项目资料 <span>↗</span></button><button data-page="整理产品设计思路">梳理一个想法 <span>↗</span></button></div>
+      </div>
+      <section class="composer-area" aria-label="会话输入">
+        <div id="demo-queue" aria-label="待发送消息" hidden></div>
+        <div class="composer">
+          <div id="composer-tags" aria-label="当前附件与选项" hidden></div>
+          <textarea id="message" aria-label="演示消息输入" placeholder="向 GoodBuddy 提问…&#10;Enter 发送 · Shift+Enter 换行"></textarea>
+          <div class="composer-toolbar">
+            <button id="attach" class="composer-icon" aria-label="添加附件" title="添加附件">＋</button>
+            <input id="attachment-input" type="file" multiple hidden>
+            <button id="voice" class="composer-icon" aria-label="模拟语音输入" aria-pressed="false" title="模拟语音输入"><svg viewBox="0 0 24 24" aria-hidden="true"><rect x="9" y="3" width="6" height="12" rx="3"/><path d="M5 10v2a7 7 0 0 0 14 0v-2M12 19v3m-4 0h8"/></svg></button>
+            <label class="composer-select"><span class="sr-only">Runtime</span><select id="composer-runtime"><option>OpenCode</option><option>Continue</option><option>直连模型</option></select></label>
+            <label class="composer-select"><span class="sr-only">工作模式</span><select id="composer-mode"><option value="Execute">Execute</option><option value="Ask">Ask</option></select></label>
+            <button id="composer-options-trigger" popovertarget="composer-options" aria-expanded="false">选项 <span class="muted">⌃</span></button>
+            <div class="composer-actions"><button id="stop" hidden aria-label="停止演示回复">停止</button><button id="send" aria-label="发送演示消息" title="发送" disabled>↑</button></div>
+          </div>
+          <div id="composer-options" popover aria-label="会话选项">
+            <header><strong>会话选项</strong><button popovertarget="composer-options" popovertargetaction="hide" aria-label="关闭会话选项">×</button></header>
+            <label class="option-row">专家<select id="composer-expert"><option value="">默认助手</option><option>产品顾问</option><option>代码审查专家</option></select></label>
+            <fieldset><legend>知识范围</legend><label><input type="checkbox" data-knowledge="产品文档"> 产品文档</label><label><input type="checkbox" data-knowledge="团队知识"> 团队知识</label></fieldset>
+            <label class="option-row">检索方式<select id="composer-retrieval"><option value="auto">自动检索</option><option value="always">每次检索</option></select></label>
+            <div id="runtime-options"><label class="option-row"><span id="agent-label">Agent</span><select id="composer-agent"><option value="">默认</option><option value="plan">Plan</option><option value="review">Review</option></select></label><label class="option-row">快捷操作<select id="composer-command"><option value="">无</option><option value="prompt">填入总结模板</option><option value="command">原生命令 /init</option></select></label></div>
+            <p class="muted">非默认选项会显示在输入框上方。</p>
+          </div>
+        </div>
+        <div class="composer-meta"><span id="composer-status" role="status">交互演示 · 不调用 AI</span><button id="context-trigger" popovertarget="context-details">上下文 <span id="context-value">42%</span></button></div>
+        <div id="context-details" popover aria-label="上下文用量"><strong>上下文用量 · 示例</strong><p id="context-description">本次模型调用：84k / 200k tokens</p><progress id="context-progress" value="42" max="100"></progress><button id="compact">压缩上下文</button></div>
+      </section>
+    </section>
+    <aside class="workbar" id="workbar" aria-label="助手工作栏"><header><strong>助手工作栏</strong><button id="close-tool" aria-label="关闭工作栏">×</button></header><div class="tool-tabs" role="tablist" aria-label="系统工具"><button role="tab" id="tab-files" data-tool="files" aria-selected="true" aria-controls="tool-content">文件</button><button role="tab" id="tab-terminal" data-tool="terminal" aria-selected="false" aria-controls="tool-content" tabindex="-1">终端</button><button role="tab" id="tab-browser" data-tool="browser" aria-selected="false" aria-controls="tool-content" tabindex="-1">浏览器</button><button role="tab" id="tab-resources" data-tool="resources" aria-selected="false" aria-controls="tool-content" tabindex="-1">资源</button></div><div id="tool-content" role="tabpanel" aria-labelledby="tab-files" tabindex="0"></div></aside>
+  </main>
+  <footer class="lab-footer"><span id="design-tradeoff"></span><button id="reset">恢复默认应用</button></footer>
+  <div class="reference-note">设计参考：<a href="https://www.raycast.com/" target="_blank" rel="noreferrer">Raycast · 搜索与扩展</a><a href="https://www.notion.com/help/intro-to-workspaces" target="_blank" rel="noreferrer">Notion · 收藏与折叠分区</a><a href="https://code.visualstudio.com/docs/configure/profiles" target="_blank" rel="noreferrer">VS Code · Profiles</a><span>借鉴交互思路，保留 GoodBuddy 的视觉与入口分类。</span></div>
+  <dialog id="catalog" aria-labelledby="catalog-title"><button id="back-to-apps" hidden>‹ 返回应用中心</button><header><div><span class="eyebrow">GOODBUDDY COLLECTION</span><h2 id="catalog-title">应用中心</h2></div><button id="close-catalog" aria-label="关闭">×</button></header><p class="muted" id="catalog-description"></p><div class="center-switch" role="group" aria-label="应用中心视图"><button data-catalog="apps">我的应用</button><button data-catalog="store">商店</button></div><input id="search" type="search" aria-label="搜索应用" placeholder="搜索应用…"><div id="catalog-items"></div><section id="app-settings" aria-label="魔法笔记设置" hidden></section><footer>常驻只表示菜单入口，不表示后台运行。安装与内容均为演示。</footer></dialog>
+  <div id="toast" role="status" aria-live="polite"></div>
+</body>
+</html>
@@ -0,0 +1,407 @@
+/* global document, window, history, location, matchMedia, innerWidth, Event, setTimeout, clearTimeout */
+const paths = {
+  note: '<rect x="4" y="3" width="16" height="18" rx="2"/><path d="M8 8h8M8 12h8M8 16h5"/>',
+  book: '<path d="M12 5v16M12 5C8 2 4 3 2 4v15c4-1 7-1 10 2 3-3 6-3 10-2V4c-2-1-6-2-10 1Z"/>',
+  chat: '<path d="M21 11a9 9 0 0 1-9 9H3l1-5A9 9 0 1 1 21 11Z"/>',
+  history: '<path d="M3 4v5h5M3 9a9 9 0 1 1 0 6m9-8v5l3 2"/>',
+  settings: '<circle cx="12" cy="12" r="4"/><path d="M12 2v3m0 14v3M2 12h3m14 0h3M5 5l2 2m10 10 2 2M5 19l2-2M17 7l2-2"/>',
+  activity: '<path d="M2 12h5l3-8 4 16 3-8h5"/>',
+  layers: '<path d="m12 3 10 5-10 5L2 8Zm-10 9 10 5 10-5M2 17l10 5 10-5"/>',
+  search: '<circle cx="10" cy="10" r="6"/><path d="m15 15 6 6"/>'
+};
+const icon = name => `<svg viewBox="0 0 24 24" aria-hidden="true">${paths[name] || paths.layers}</svg>`;
+const items = [
+  { id: 'notes', name: '魔法笔记', icon: 'note', detail: '记录想法、整理待办', summary: '把刚才的灵感留在这里', builtin: true },
+  { id: 'knowledge', name: '知识库', icon: 'book', detail: '整理资料、检索知识', summary: '下一次提问，从已有知识开始', builtin: true },
+  { id: 'heartbeat', name: '智能心跳', icon: 'activity', detail: '管理定时任务与主动提醒', summary: '让例行任务按计划发生', builtin: true },
+  { id: 'projects', name: '项目管理', icon: 'layers', detail: '跟踪项目、任务与进度', summary: '把一个想法变成可跟进的项目', builtin: false },
+  { id: 'reading', name: '阅读空间', icon: 'book', detail: '集中阅读、批注与摘录', summary: '给长文和深度阅读留一个空间', builtin: false }
+];
+const variants = {
+  dock: ['A / 紧凑入口', '最底部保留一个应用中心入口，向上展开紧凑列表。', '适合希望把侧栏空间留给对话的用户。'],
+  grid: ['B / 应用宫格', '底部入口展示应用数量，展开后用宫格浏览已安装应用。', '图标与名称同时可见，常驻位置由用户选择。'],
+  cards: ['C / 应用预览', '入口展示内置应用图标，展开后用卡片说明每个应用的用途。', '适合通过内容理解应用，卡片不代表后台持续运行。'],
+  launcher: ['D / 搜索启动台', '最底部就是搜索入口，也可以按 Ctrl / ⌘ K 打开。', '输入名称，用方向键与 Enter 打开已安装应用。'],
+  favorites: ['E / 常驻管理', '从底部管理哪些应用常驻菜单，未常驻应用也可直接打开。', '常驻应用优先排列；入口显隐不影响安装和运行状态。'],
+  scenes: ['F / 商店发现', '底部入口强调应用发现，展开后查看商店应用与安装位置。', '先模拟安装，再决定是否常驻；我的应用始终可切换访问。']
+};
+const $ = selector => document.querySelector(selector);
+const demoProjects = [
+  { id: 'goodbuddy', name: 'GoodBuddy', group: '本地', conversations: ['优化项目导航', '检查构建问题'] },
+  { id: 'website', name: '官网改版', group: '本地', conversations: ['发布首页'] },
+  { id: 'remote', name: '客户方案与交付文档工作空间', group: 'SSH', conversations: ['整理报价'] },
+  { id: 'channel', name: '团队助手', group: '通道', conversations: ['本周工作计划'] }
+];
+let currentProject = 'goodbuddy';
+let projectActivity = [];
+let expandedActivityProject = '';
+function renderProjects() {
+  const scenario = $('#project-scenario').value;
+  const activity = demoProjects.flatMap(project => project.conversations.map((name, index) => ({ project, name, index,
+    state: scenario === 'idle' || project.id === 'channel' || (scenario === 'current' && project.id !== currentProject) ? '' : scenario === 'waiting' && project.id === 'website' ? '等待审批' : '运行中'
+  }))).filter(row => row.state);
+  projectActivity = activity;
+  const waiting = activity.filter(row => row.state !== '运行中').length;
+  const running = activity.length - waiting;
+  const project = demoProjects.find(entry => entry.id === currentProject);
+  $('#project-name').textContent = project.name;
+  $('#project-trigger').setAttribute('aria-label', `切换项目，当前项目：${project.name}`);
+  $('#activity-trigger').hidden = !activity.length;
+  if (!activity.length && $('#project-activity').matches(':popover-open')) $('#project-activity').hidePopover();
+  $('#activity-summary').innerHTML = `${running ? `运行中 ${running}` : ''}${waiting && running ? ' · ' : ''}${waiting ? `<span class="project-waiting">待处理 ${waiting}</span>` : ''}`;
+  $('#activity-trigger').setAttribute('aria-label', `所有项目活动：${$('#activity-summary').textContent}`);
+  $('#project-list').innerHTML = ['本地', 'SSH', '通道'].map(group => `<section><h3>${group}</h3>${demoProjects.filter(entry => entry.group === group).map(entry => {
+    const rows = activity.filter(row => row.project.id === entry.id);
+    const pending = rows.filter(row => row.state !== '运行中').length;
+    const active = rows.length - pending;
+    return `<button data-project="${entry.id}" ${entry.id === currentProject ? 'aria-current="true"' : ''}><span class="project-row-name">${entry.name}</span>${entry.id === currentProject ? '<span aria-hidden="true">✓</span>' : ''}${rows.length ? `<small>${pending ? `<span class="project-waiting">待处理 ${pending}</span>` : ''}${active ? `<span>运行中 ${active}</span>` : ''}</small>` : ''}</button>`;
+  }).join('')}</section>`).join('');
+  $('#activity-project-list').innerHTML = demoProjects.map(entry => {
+    const rows = activity.filter(row => row.project.id === entry.id);
+    if (!rows.length) return '';
+    const pending = rows.filter(row => row.state !== '运行中').length;
+    return `<button data-activity-project="${entry.id}" aria-expanded="false" aria-controls="activity-sessions"><span>${entry.name}</span><small>${pending ? `<span class="project-waiting">待处理 ${pending}</span>` : `运行中 ${rows.length}`}</small><span aria-hidden="true">›</span></button>`;
+  }).join('') || '<p class="muted">暂无运行中或待处理会话。</p>';
+  expandActivityProject('');
+  $('.history').innerHTML = `<span class="eyebrow">当前项目对话</span>${project.conversations.map((name, index) => {
+    const row = activity.find(entry => entry.project.id === currentProject && entry.index === index);
+    return `<button data-conversation="${currentProject}" data-conversation-index="${index}">${name}${row ? `<small>${row.state}</small>` : ''}</button>`;
+  }).join('')}`;
+}
+$('#project-scenario').onchange = renderProjects;
+const projectMenu = $('#project-menu');
+function positionProjectMenu() {
+  const rect = $('#project-trigger').getBoundingClientRect();
+  projectMenu.style.left = `${Math.max(16, Math.min(rect.left, innerWidth - projectMenu.offsetWidth - 16))}px`;
+  projectMenu.style.top = `${Math.max(16, Math.min(rect.bottom + 8, window.innerHeight - projectMenu.offsetHeight - 16))}px`;
+}
+projectMenu.addEventListener('toggle', event => {
+  $('#project-trigger').setAttribute('aria-expanded', String(event.newState === 'open'));
+  if (event.newState === 'open') positionProjectMenu();
+});
+window.addEventListener('resize', () => { if (projectMenu.matches(':popover-open')) positionProjectMenu(); });
+window.addEventListener('scroll', () => { if (projectMenu.matches(':popover-open')) positionProjectMenu(); }, true);
+function positionActivityMenu() {
+  const panel = $('#project-activity');
+  const rect = $('#activity-trigger').getBoundingClientRect();
+  panel.classList.toggle('activity-compact', innerWidth < 620);
+  panel.classList.toggle('activity-left', innerWidth >= 620 && rect.left + panel.offsetWidth > innerWidth - 16 && rect.right >= panel.offsetWidth + 16);
+  const left = panel.classList.contains('activity-left') ? rect.right - panel.offsetWidth : rect.left;
+  panel.style.left = `${Math.max(16, Math.min(left, innerWidth - panel.offsetWidth - 16))}px`;
+  panel.style.top = `${Math.max(16, Math.min(rect.bottom + 4, window.innerHeight - panel.offsetHeight - 16))}px`;
+}
+function expandActivityProject(id, focus = false) {
+  expandedActivityProject = id;
+  $('#activity-sessions').hidden = !id;
+  $('#project-activity').classList.toggle('has-submenu', Boolean(id));
+  document.querySelectorAll('[data-activity-project]').forEach(button => button.setAttribute('aria-expanded', String(button.dataset.activityProject === id)));
+  if (id) {
+    $('#activity-project-title').textContent = demoProjects.find(project => project.id === id).name;
+    $('#activity-list').innerHTML = projectActivity.filter(row => row.project.id === id).sort((a, b) => Number(a.state === '运行中') - Number(b.state === '运行中')).map(row => `<button data-conversation="${id}" data-conversation-index="${row.index}"><strong>${row.name}</strong><small>${row.state}</small></button>`).join('');
+  }
+  if ($('#project-activity').matches(':popover-open')) positionActivityMenu();
+  if (focus) $('#activity-list button')?.focus();
+}
+$('#project-activity').addEventListener('toggle', event => {
+  $('#activity-trigger').setAttribute('aria-expanded', String(event.newState === 'open'));
+  if (event.newState === 'open') { expandActivityProject(''); positionActivityMenu(); }
+});
+$('#activity-project-list').addEventListener('pointerover', event => {
+  const button = event.target.closest('[data-activity-project]');
+  if (event.pointerType === 'mouse' && innerWidth >= 620 && button && button.dataset.activityProject !== expandedActivityProject) expandActivityProject(button.dataset.activityProject);
+});
+$('#activity-project-list').addEventListener('click', event => {
+  const button = event.target.closest('[data-activity-project]');
+  if (button) expandActivityProject(button.dataset.activityProject, true);
+});
+$('#activity-back').onclick = () => {
+  const id = expandedActivityProject;
+  expandActivityProject('');
+  $(`[data-activity-project="${id}"]`)?.focus();
+};
+$('#project-activity').addEventListener('keydown', event => {
+  const button = event.target.closest('[data-activity-project]');
+  if (event.key === 'ArrowRight' && button) { event.preventDefault(); expandActivityProject(button.dataset.activityProject, true); }
+  if ((event.key === 'ArrowLeft' || event.key === 'Escape') && expandedActivityProject) { event.preventDefault(); event.stopPropagation(); $('#activity-back').click(); }
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    const buttons = [...document.querySelectorAll(button ? '[data-activity-project]' : '#activity-list button')];
+    const index = buttons.indexOf(document.activeElement);
+    if (index >= 0) { event.preventDefault(); buttons[(index + (event.key === 'ArrowDown' ? 1 : -1) + buttons.length) % buttons.length].focus(); }
+  }
+});
+window.addEventListener('resize', () => { if ($('#project-activity').matches(':popover-open')) positionActivityMenu(); });
+window.addEventListener('scroll', () => { if ($('#project-activity').matches(':popover-open')) positionActivityMenu(); }, true);
+renderProjects();
+let variant = 'dock';
+let catalogMode = 'apps';
+let residentApps = ['notes', 'knowledge'];
+let editingApps = false;
+let draggedApp = '';
+let installed = new Set(items.filter(item => item.builtin).map(item => item.id));
+let toastTimer;
+let settingsOpen = false;
+const noteSettings = { showCount: true, mode: 'immediate', format: 'combined' };
+const noteModes = { immediate: '即时', 'after-save-auto': '保存后自动', 'after-save-manual': '保存后手动' };
+const noteFormats = { combined: '长评 + 要点', narrative: '长评', structured: '要点' };
+function renderNoteSettings() {
+  $('#app-settings').innerHTML = `<div class="note-setting-row"><div><strong>常驻左侧菜单</strong><p>对应“显示魔法笔记入口”，移除后仍可从应用中心打开。</p></div><button class="demo-switch" role="switch" aria-label="常驻左侧菜单" aria-checked="${residentApps.includes('notes')}" data-note-toggle="resident"></button></div>
+    <div class="note-setting-row"><div><strong>显示未完成待办数量</strong><p>在左侧入口显示数量，超过 99 项显示 99+。本 Demo 使用 3 项示例。</p></div><button class="demo-switch" role="switch" aria-label="显示未完成待办数量" aria-checked="${noteSettings.showCount}" data-note-toggle="showCount"></button></div>
+    <fieldset class="note-setting-options"><legend>AI 评论方式</legend><div class="note-segments" role="group" aria-label="AI 评论方式">${Object.entries(noteModes).map(([value, label]) => `<button data-note-mode="${value}" aria-pressed="${noteSettings.mode === value}">${label}</button>`).join('')}</div><p>即时：按回车并停止输入 5 秒后评论未保存草稿。保存后自动：保存后评论。保存后手动：点击 AI 分析后评论。</p></fieldset>
+    <fieldset class="note-setting-options"><legend>AI 评论形式</legend><div class="note-segments" role="group" aria-label="AI 评论形式">${Object.entries(noteFormats).map(([value, label]) => `<button data-note-format="${value}" aria-pressed="${noteSettings.format === value}">${label}</button>`).join('')}</div><p>默认同时生成流式长评和结构化要点，也可只保留其中一种。</p></fieldset>
+    <div class="note-settings-preview"><span class="eyebrow">当前配置预览</span><p>${noteModes[noteSettings.mode]} · ${noteFormats[noteSettings.format]}</p><small>选择后即时保留于本次 Demo 会话，不调用 AI、不修改真实设置。</small></div>`;
+  if ($('#note-settings-summary')) $('#note-settings-summary').textContent = `当前设置：${noteModes[noteSettings.mode]} · ${noteFormats[noteSettings.format]}。待办数量${noteSettings.showCount ? '显示' : '隐藏'}。`;
+}
+function showNoteSettings() {
+  if (!$('#catalog').open) { catalogMode = 'apps'; $('#search').value = ''; }
+  settingsOpen = true;
+  $('#catalog').dataset.variant = variant;
+  $('#catalog-title').textContent = '魔法笔记设置';
+  $('#catalog-description').textContent = '调整入口与 AI 评论行为。应用中心和笔记页面共享这份演示配置。';
+  $('#back-to-apps').hidden = false; $('#app-settings').hidden = false;
+  for (const selector of ['.center-switch', '#search', '#catalog-items']) $(selector).hidden = true;
+  renderNoteSettings();
+  if (!$('#catalog').open) $('#catalog').showModal();
+  $('#back-to-apps').focus();
+}
+function notify(text) {
+  $('#toast').textContent = text; $('#toast').classList.add('visible');
+  clearTimeout(toastTimer); toastTimer = setTimeout(() => $('#toast').classList.remove('visible'), 2200);
+}
+function renderApps() {
+  $('#edit-apps').textContent = editingApps ? '完成' : '编辑';
+  $('#resident-list').innerHTML = residentApps.map((id, index) => {
+    const item = items.find(entry => entry.id === id);
+    return `<div class="resident-row" data-resident="${id}" draggable="${editingApps}"><button data-open="${id}" ${$('#page-label').textContent === item.name ? 'aria-current="page"' : ''}>${icon(item.icon)}<span>${item.name}</span>${id === 'notes' && noteSettings.showCount ? '<small class="note-count" aria-label="3 项未完成待办（示例）">3</small>' : ''}</button>${editingApps ? `<div class="edit-actions"><button data-move="${id}" data-direction="-1" aria-label="上移${item.name}" ${index === 0 ? 'disabled' : ''}>↑</button><button data-pin="${id}" aria-label="移除${item.name}">×</button><button data-move="${id}" data-direction="1" aria-label="下移${item.name}" ${index === residentApps.length - 1 ? 'disabled' : ''}>↓</button></div>` : ''}</div>`;
+  }).join('') || '<p class="empty-apps">点击 ＋，选择常驻应用。</p>';
+  const subtitles = { dock: '', grid: `${installed.size} 个已安装应用`, cards: '笔记 · 知识 · 自动化', launcher: 'Ctrl / ⌘ K', favorites: `${residentApps.length} 个应用常驻菜单`, scenes: '发现你的下一个好应用' };
+  $('#center-entry').innerHTML = `<button id="open-center" aria-haspopup="dialog"><span class="brand-mark">${variant === 'launcher' ? icon('search') : 'GB'}</span><span><strong>${variant === 'launcher' ? '搜索应用…' : '应用中心'}</strong>${subtitles[variant] ? `<small>${subtitles[variant]}</small>` : ''}</span><span class="entry-arrow">${variant === 'scenes' ? '↗' : '⌃'}</span></button>`;
+}
+function renderCatalog() {
+  const query = $('#search').value.trim().toLowerCase();
+  const matches = items.filter(item => (catalogMode === 'store' ? !item.builtin : installed.has(item.id)) && `${item.name}${item.detail}`.toLowerCase().includes(query));
+  if (variant === 'favorites') matches.sort((a, b) => Number(residentApps.includes(b.id)) - Number(residentApps.includes(a.id)));
+  $('#catalog-items').innerHTML = matches.map(item => {
+    const ready = installed.has(item.id); const pinned = residentApps.includes(item.id);
+    return `<article class="center-app">${icon(item.icon)}<div class="center-app-info"><strong>${item.name}</strong><p>${item.builtin ? '内置应用' : '商店应用 · 示例'}</p><p class="app-detail">${variant === 'cards' ? item.summary : item.detail}</p></div><div class="center-actions">${ready ? `<button data-open="${item.id}">打开</button>${item.id === 'notes' ? '<button data-note-settings aria-label="魔法笔记设置">设置</button>' : ''}<button data-pin="${item.id}" aria-pressed="${pinned}">${pinned ? '取消常驻' : '常驻左侧'}</button>` : `<button data-install="${item.id}">模拟安装</button><button data-install-pin="${item.id}">安装并常驻</button>`}</div></article>`;
+  }).join('') || '<p class="empty-apps">没有匹配的应用。可以换个关键词，或切换到商店。</p>';
+  document.querySelectorAll('.center-switch button').forEach(button => button.setAttribute('aria-pressed', String(button.dataset.catalog === catalogMode)));
+}
+function openCatalog(mode = 'apps') {
+  settingsOpen = false; $('#back-to-apps').hidden = true; $('#app-settings').hidden = true;
+  for (const selector of ['.center-switch', '#search', '#catalog-items']) $(selector).hidden = false;
+  catalogMode = mode; $('#catalog').dataset.variant = variant;
+  $('#catalog-title').textContent = mode === 'store' ? '发现新应用' : '应用中心';
+  $('#catalog-description').textContent = mode === 'store' ? '安装你需要的应用，自主决定是否常驻左侧菜单。' : '打开应用，或把常用应用留在左侧。系统工具请使用右侧工作栏。';
+  $('#search').value = ''; renderCatalog();
+  if (!$('#catalog').open) $('#catalog').showModal();
+  $('#search').focus();
+}
+function openPage(name) {
+  if ($('#catalog').open) $('#catalog').close();
+  $('#page-label').textContent = name;
+  $('#page-content').replaceChildren();
+  const title = document.createElement('h1'); title.textContent = name;
+  const description = document.createElement('p'); description.className = 'muted'; description.textContent = '主内容区页面预览。右侧工作栏保持当前工具状态。';
+  $('#page-content').append(title, description);
+  $('#page-actions').innerHTML = name === '魔法笔记' ? `<button data-note-settings>${icon('settings')} 笔记设置</button>` : '';
+  if (name === '魔法笔记' || name === '设置') {
+    const summary = document.createElement('p'); summary.id = 'note-settings-summary'; summary.className = 'muted'; $('#page-content').append(summary);
+    if (name === '设置') { const button = document.createElement('button'); button.dataset.noteSettings = ''; button.textContent = '魔法笔记设置'; $('#page-content').append(button); }
+    renderNoteSettings();
+  }
+  document.querySelectorAll('.navigation button').forEach(button => button.classList.toggle('selected', button.dataset.page === name));
+  renderApps(); notify(`已打开${name}`);
+}
+function selectVariant(name) {
+  variant = name; $('.app').dataset.variant = name;
+  document.querySelectorAll('button[data-variant]').forEach(button => button.setAttribute('aria-pressed', String(button.dataset.variant === name)));
+  [$('#variant-label').textContent, $('#variant-description').textContent, $('#design-tradeoff').textContent] = variants[name];
+  history.replaceState(null, '', `#${name}`); renderApps();
+}
+function selectTool(id) {
+  const content = {
+    files: '<span class="eyebrow">本机 / goodbuddy · 示例</span><div class="file-row">src /</div><div class="file-row">docs /</div><div class="file-row">resources /</div><div class="file-row">README.md</div>',
+    terminal: '<span class="eyebrow">当前项目 · 演示终端</span><pre>PS &gt; git status\nOn branch main\nworking tree clean\n\nPS &gt;</pre>',
+    browser: '<span class="eyebrow">浏览器 · 静态示例</span><div class="file-row">https://example.com</div><h2>Example Domain</h2>',
+    resources: '<span class="eyebrow">本机 · 静态演示数据</span><div class="metric">CPU <strong>18%</strong><progress value="18" max="100"></progress></div><div class="metric">内存 <strong>9.6 / 32 GB</strong><progress value="30" max="100"></progress></div><p>磁盘 IO：读 12 MB/s · 写 3 MB/s</p>'
+  };
+  $('#tool-content').innerHTML = content[id]; $('#tool-content').setAttribute('aria-labelledby', `tab-${id}`);
+  document.querySelectorAll('[data-tool]').forEach(button => { button.setAttribute('aria-selected', String(button.dataset.tool === id)); button.tabIndex = button.dataset.tool === id ? 0 : -1; });
+}
+document.addEventListener('click', event => {
+  const button = event.target.closest('button'); if (!button) return;
+  const data = button.dataset;
+  if (data.project || data.conversation) {
+    currentProject = data.project || data.conversation;
+    if (projectMenu.matches(':popover-open')) projectMenu.hidePopover();
+    if ($('#project-activity').matches(':popover-open')) $('#project-activity').hidePopover();
+    renderProjects();
+    const project = demoProjects.find(entry => entry.id === currentProject);
+    openPage(data.conversation ? project.conversations[Number(data.conversationIndex)] : '当前对话');
+    $('#page-label').textContent = `${project.name} / ${data.conversation ? project.conversations[Number(data.conversationIndex)] : '当前对话'}`;
+    $('#project-trigger').focus();
+  }
+  if (data.variant) selectVariant(data.variant);
+  if (data.catalog) openCatalog(data.catalog);
+  if (data.page) openPage(data.page);
+  if (data.open) openPage(items.find(item => item.id === data.open).name);
+  if (data.tool) selectTool(data.tool);
+  if (button.hasAttribute('data-note-settings')) showNoteSettings();
+  if (data.noteToggle || data.noteMode || data.noteFormat) {
+    if (data.noteToggle === 'resident') residentApps = residentApps.includes('notes') ? residentApps.filter(id => id !== 'notes') : [...residentApps, 'notes'];
+    if (data.noteToggle === 'showCount') noteSettings.showCount = !noteSettings.showCount;
+    if (data.noteMode) noteSettings.mode = data.noteMode;
+    if (data.noteFormat) noteSettings.format = data.noteFormat;
+    renderApps(); renderNoteSettings();
+    const selector = data.noteToggle ? `[data-note-toggle="${data.noteToggle}"]` : data.noteMode ? `[data-note-mode="${data.noteMode}"]` : `[data-note-format="${data.noteFormat}"]`;
+    $(selector).focus();
+  }
+  if (button.id === 'open-center') openCatalog(variant === 'scenes' ? 'store' : 'apps');
+  if (button.id === 'edit-apps') { editingApps = !editingApps; renderApps(); $('#edit-apps').focus(); }
+  if (data.pin || data.install || data.installPin) {
+    const id = data.pin || data.install || data.installPin;
+    if (data.install || data.installPin) installed.add(id);
+    if (data.pin || data.installPin) residentApps = residentApps.includes(id) ? residentApps.filter(entry => entry !== id) : [...residentApps, id];
+    renderApps();
+    if ($('#catalog').open) { renderCatalog(); ($(`#catalog [data-pin="${id}"]`) || $('#search')).focus(); }
+    else $('#edit-apps').focus();
+  }
+  if (data.move) {
+    const from = residentApps.indexOf(data.move); const to = from + Number(data.direction);
+    if (to >= 0 && to < residentApps.length) [residentApps[from], residentApps[to]] = [residentApps[to], residentApps[from]];
+    renderApps(); $(`#resident-list [data-pin="${data.move}"]`).focus();
+  }
+});
+$('#resident-list').addEventListener('dragstart', event => { draggedApp = event.target.closest('[data-resident]')?.dataset.resident || ''; if (!editingApps || !draggedApp) { event.preventDefault(); return; } event.dataTransfer.setData('text/plain', draggedApp); });
+$('#resident-list').addEventListener('dragover', event => { if (editingApps && draggedApp) event.preventDefault(); });
+$('#resident-list').addEventListener('drop', event => {
+  event.preventDefault(); const target = event.target.closest('[data-resident]')?.dataset.resident;
+  if (!editingApps || !residentApps.includes(draggedApp) || !target || target === draggedApp) return;
+  const to = residentApps.indexOf(target); residentApps.splice(residentApps.indexOf(draggedApp), 1); residentApps.splice(to, 0, draggedApp); draggedApp = ''; renderApps(); $('#edit-apps').focus();
+});
+$('#resident-list').addEventListener('dragend', () => { draggedApp = ''; });
+$('#search').addEventListener('input', renderCatalog);
+$('#close-catalog').onclick = () => $('#catalog').close();
+$('#back-to-apps').onclick = () => { const query = $('#search').value; openCatalog(catalogMode); $('#search').value = query; renderCatalog(); ($('#catalog [data-note-settings]') || $('#search')).focus(); };
+function toggleWorkbar(visible) { $('.workbar').hidden = !visible; $('#toggle-workbar').setAttribute('aria-expanded', String(visible)); }
+$('#toggle-workbar').onclick = () => toggleWorkbar($('.workbar').hidden);
+$('#close-tool').onclick = () => { toggleWorkbar(false); $('#toggle-workbar').focus(); };
+$('.tool-tabs').addEventListener('keydown', event => {
+  const tabs = [...document.querySelectorAll('[data-tool]')]; const index = tabs.indexOf(event.target);
+  if (index < 0 || !['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return;
+  event.preventDefault(); const next = event.key === 'Home' ? 0 : event.key === 'End' ? tabs.length - 1 : (index + (event.key === 'ArrowRight' ? 1 : -1) + tabs.length) % tabs.length;
+  selectTool(tabs[next].dataset.tool); tabs[next].focus();
+});
+document.addEventListener('keydown', event => {
+  if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'k') { event.preventDefault(); openCatalog(); }
+  if (!$('#catalog').open || settingsOpen || variant !== 'launcher') return;
+  const actions = [...document.querySelectorAll('#catalog [data-open]')]; if (!actions.length) return;
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') { event.preventDefault(); const index = actions.indexOf(document.activeElement); const next = index < 0 ? (event.key === 'ArrowDown' ? 0 : actions.length - 1) : (index + (event.key === 'ArrowDown' ? 1 : -1) + actions.length) % actions.length; actions[next].focus(); }
+  if (event.key === 'Enter' && document.activeElement === $('#search')) { event.preventDefault(); actions[0].click(); }
+});
+$('#theme').onclick = () => { const dark = document.documentElement.dataset.theme !== 'dark'; document.documentElement.dataset.theme = dark ? 'dark' : 'light'; $('#theme').textContent = dark ? '切换浅色' : '切换深色'; };
+$('#reset').onclick = () => { installed = new Set(items.filter(item => item.builtin).map(item => item.id)); residentApps = ['notes', 'knowledge']; editingApps = false; renderApps(); notify('应用安装与常驻配置已恢复默认'); };
+let demoRunning = false;
+let demoRecording = false;
+let demoAttachments = [];
+let demoQueue = [];
+let demoReplyTimer;
+function renderComposer() {
+  const tags = $('#composer-tags'); tags.replaceChildren();
+  const addTag = (text, clear) => {
+    const button = document.createElement('button'); button.textContent = `${text} ×`; button.setAttribute('aria-label', `移除${text}`);
+    button.onclick = () => { clear(); renderComposer(); $('#message').focus(); }; tags.append(button);
+  };
+  demoAttachments.forEach((name, index) => addTag(name, () => demoAttachments.splice(index, 1)));
+  for (const id of ['composer-expert', 'composer-agent', 'composer-command']) {
+    const select = $(`#${id}`);
+    if (select.value) addTag(select.selectedOptions[0].textContent, () => { select.value = ''; });
+  }
+  document.querySelectorAll('[data-knowledge]:checked').forEach(input => addTag(input.dataset.knowledge, () => { input.checked = false; }));
+  if ($('#composer-retrieval').value === 'always') addTag('每次检索', () => { $('#composer-retrieval').value = 'auto'; });
+  tags.hidden = !tags.childElementCount;
+  $('#stop').hidden = !demoRunning;
+  $('#send').disabled = !$('#message').value.trim() && $('#composer-command').value !== 'command';
+  $('#send').title = demoRunning ? '加入队列' : '发送';
+  $('#send').setAttribute('aria-label', demoRunning ? '加入演示队列' : '发送演示消息');
+  $('#composer-status').textContent = demoRecording ? '模拟录音中 · 再次点击结束' : demoRunning ? '模拟回复中 · 可继续发送加入队列' : '交互演示 · 不调用 AI';
+  for (const id of ['composer-runtime', 'composer-mode', 'composer-expert', 'composer-agent', 'composer-command']) $(`#${id}`).disabled = demoRunning;
+  $('#compact').disabled = demoRunning;
+  $('#runtime-options').hidden = $('#composer-runtime').value === '直连模型';
+  $('#compact').hidden = $('#composer-runtime').value === '直连模型';
+  $('#demo-queue').replaceChildren();
+  demoQueue.forEach((text, index) => {
+    const row = document.createElement('div'); row.className = 'queue-row';
+    const label = document.createElement('span'); label.textContent = text; label.title = text;
+    const insert = document.createElement('button'); insert.textContent = '立即插入'; insert.setAttribute('aria-label', `立即中断并插入：${text}`);
+    insert.onclick = () => { demoQueue.splice(index, 1); startDemoReply(text); };
+    const remove = document.createElement('button'); remove.textContent = '×'; remove.setAttribute('aria-label', `删除待发送消息：${text}`);
+    remove.onclick = () => { demoQueue.splice(index, 1); renderComposer(); };
+    row.append(label, insert, remove); $('#demo-queue').append(row);
+  });
+  $('#demo-queue').hidden = !demoQueue.length;
+}
+function startDemoReply(text) {
+  clearTimeout(demoReplyTimer); demoRunning = true;
+  if ($('#composer-options').matches(':popover-open')) $('#composer-options').hidePopover();
+  notify(`模拟处理：${text}`); renderComposer();
+  demoReplyTimer = setTimeout(() => {
+    demoRunning = false;
+    if (demoQueue.length) startDemoReply(demoQueue.shift());
+    else { renderComposer(); notify('演示回复已完成，未调用 AI'); }
+  }, 8000);
+}
+$('#send').onclick = () => {
+  if ($('#send').disabled) return;
+  const text = $('#composer-command').value === 'command' ? `/init ${$('#message').value.trim()}` : $('#message').value.trim();
+  $('#message').value = ''; $('#message').style.height = ''; demoAttachments = [];
+  if (demoRunning) { demoQueue.push(text); renderComposer(); }
+  else startDemoReply(text);
+};
+$('#stop').onclick = () => {
+  clearTimeout(demoReplyTimer); demoRunning = false;
+  if (demoQueue.length) startDemoReply(demoQueue.shift());
+  else { renderComposer(); notify('已停止演示回复'); }
+};
+$('#message').addEventListener('input', () => { $('#message').style.height = 'auto'; $('#message').style.height = `${Math.min(180, $('#message').scrollHeight)}px`; renderComposer(); });
+$('#message').addEventListener('keydown', event => { if (event.key === 'Enter' && !event.shiftKey && !event.isComposing) { event.preventDefault(); $('#send').click(); } });
+$('#attach').onclick = () => $('#attachment-input').click();
+$('#attachment-input').onchange = () => { demoAttachments.push(...Array.from($('#attachment-input').files, file => file.name)); $('#attachment-input').value = ''; renderComposer(); };
+$('#voice').onclick = () => {
+  demoRecording = !demoRecording; $('#voice').setAttribute('aria-pressed', String(demoRecording));
+  if (!demoRecording) { $('#message').value += '请帮我整理一下今天的工作计划。'; $('#message').dispatchEvent(new Event('input')); }
+  renderComposer();
+};
+$('#composer-options').addEventListener('change', event => {
+  if (event.target.id === 'composer-command' && event.target.value === 'prompt') {
+    $('#message').value = '请总结当前讨论，列出关键结论和下一步行动。'; event.target.value = ''; $('#message').dispatchEvent(new Event('input'));
+  }
+  renderComposer();
+});
+$('#composer-runtime').onchange = () => {
+  $('#composer-agent').value = ''; $('#composer-command').value = '';
+  $('#agent-label').textContent = $('#composer-runtime').value === 'Continue' ? '预设' : 'Agent';
+  $('#composer-command').querySelector('[value="command"]').hidden = $('#composer-runtime').value !== 'OpenCode';
+  renderComposer();
+};
+$('#compact').onclick = () => {
+  $('#context-value').textContent = '18%'; $('#context-progress').value = 18;
+  $('#context-description').textContent = '压缩后对话估算：36k / 200k tokens';
+  $('#context-details').hidePopover(); notify('已模拟压缩上下文');
+};
+for (const [panelId, triggerId] of [['composer-options', 'composer-options-trigger'], ['context-details', 'context-trigger']]) {
+  const panel = $(`#${panelId}`); const trigger = $(`#${triggerId}`);
+  const position = () => {
+    const rect = trigger.getBoundingClientRect();
+    panel.style.left = `${Math.max(16, Math.min(rect.right - panel.offsetWidth, innerWidth - panel.offsetWidth - 16))}px`;
+    panel.style.top = `${Math.max(16, rect.top - panel.offsetHeight - 8)}px`;
+  };
+  panel.addEventListener('toggle', event => { trigger.setAttribute('aria-expanded', String(event.newState === 'open')); if (event.newState === 'open') position(); });
+  window.addEventListener('resize', () => { if (panel.matches(':popover-open')) position(); });
+  window.addEventListener('scroll', () => { if (panel.matches(':popover-open')) position(); }, true);
+}
+renderComposer();
+document.querySelectorAll('[data-icon]').forEach(element => { element.innerHTML = icon(element.dataset.icon); });
+window.addEventListener('hashchange', () => { if (Object.hasOwn(variants, location.hash.slice(1))) selectVariant(location.hash.slice(1)); });
+selectVariant(Object.hasOwn(variants, location.hash.slice(1)) ? location.hash.slice(1) : 'dock'); selectTool('files');
+if (matchMedia('(max-width: 1080px)').matches) toggleWorkbar(false);
@@ -0,0 +1,263 @@
+# 应用导航与系统工具入口 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 关联设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[助手工作栏 PRD](../assistant-workbar/prd.md) |
+
+## 1. 背景
+
+计划修订说明：当前实施范围以[第 8 节](#8-分期)为准。本文其余章节仍包含 v0.2 的
+左下角系统工具方案；启动实现前须同步功能要求、验收及配套设计，旧快捷工具条不再列入实施。
+
+主侧栏当前把“当前对话”“魔法笔记”“知识库”“智能心跳”和“运行记录”放在同一导航组，
+底部长期显示“GB 本地工作区”和平台架构。底部信息不能反映用户可以执行的操作，文件、终端
+和浏览器则需要先找到右侧助手工作栏后才能打开。
+
+后续插件可能提供完整页面，也可能只提供辅助面板或命令。若不先区分系统入口、应用和工具，
+插件接入后会同时争用主导航、侧栏底部和助手工作栏，用户也无法判断入口会切换页面还是打开
+辅助面板。
+
+## 2. 产品定义
+
+### 2.1 三类入口
+
+| 类型 | 首期成员 | 默认位置 | 用户控制范围 |
+| --- | --- | --- | --- |
+| 系统入口 | 当前对话、运行记录、设置 | 主导航固定位置或侧栏底部 | 不可隐藏、卸载或改变类型 |
+| 应用 | 魔法笔记、知识库、智能心跳 | 主导航应用区 | 可控制是否显示；隐藏不删除数据 |
+| 系统工具 | 文件浏览器、终端、浏览器、资源监控 | 侧栏底部快捷工具栏 | 首期固定提供，不可卸载 |
+
+运行记录是系统审计页面，不属于工具。文件浏览器、终端、浏览器和资源监控是系统工具；它们
+的快捷入口位于左下角，实际界面继续由右侧助手工作栏承载。
+
+### 2.2 后续插件类型
+
+插件市场开放后，插件可以贡献“插件应用”或“插件工具”。插件不能注册、覆盖或替换系统入口，
+也不能冒充系统工具。内置应用继续标记为“内置”，不因采用统一注册协议而显示成待安装商品。
+
+## 3. 目标
+
+- 用户从侧栏底部一次点击即可打开文件、终端、浏览器或资源监控。
+- 主导航只承载完整页面，辅助工具不占用一级页面位置。
+- 运行记录始终可发现，不受应用显示设置和插件状态影响。
+- 内置应用可以从一个设置位置控制主导航可见性，隐藏后仍可恢复。
+- 为插件应用和插件工具保留明确的入口契约，不提前建设插件安装能力。
+
+## 4. 非目标
+
+- 首期不提供应用商店页面、商店导航、推荐位或安装按钮，也不提供第三方插件搜索、下载、
+  安装、更新、签名验证或卸载。内置应用的浏览、搜索与打开属于应用中心，不依赖商店。
+- 不把文件树、终端或浏览器重新实现到左侧栏。
+- 不改变助手工作栏的面板实例、停靠、执行空间和安全边界。
+- 不允许隐藏运行记录、当前对话或设置。
+- 不因隐藏应用而删除魔法笔记、知识库或智能心跳数据。
+- 不把“显示在侧边栏”解释为停止智能心跳计划或后台任务。
+- 不提供任意本机程序启动器。
+- 首期资源监控不采集远程主机、GPU、显存或网络吞吐，不提供后台告警和历史持久化。
+
+## 5. 功能要求
+
+### FR-1 入口分类
+
+系统必须为每个可见入口声明稳定类型：`system-entry`、`application` 或 `system-tool`。界面位置、
+设置项和点击结果均以该类型为准，不根据当前页面临时改变类型。
+
+### FR-2 固定系统入口
+
+“当前对话”固定在主导航首位；“运行记录”固定在应用区之后；“设置”固定在侧栏底部。
+这些入口不出现在应用显隐、工具固定或插件管理设置中。
+
+### FR-3 内置应用区
+
+魔法笔记、知识库和智能心跳显示在当前对话与运行记录之间。应用入口打开对应一级页面，保留
+现有徽标、范围和页面状态。用户可以在设置中控制其主导航可见性。
+
+### FR-4 隐藏应用
+
+隐藏应用只移除主导航入口，不删除数据、不修改业务启停状态，也不终止正在进行的操作。显隐
+Switch 更新成功后主导航立即生效；更新失败时恢复原状态并允许重试。用户可从设置恢复入口。
+
+### FR-5 系统工具快捷栏
+
+侧栏底部提供文件浏览器、终端、浏览器和资源监控四个图标按钮，并保留独立设置按钮。每个
+按钮具有可见工具提示和可访问名称。首期系统工具顺序固定为文件、终端、浏览器、资源监控。
+
+### FR-6 文件浏览器入口
+
+点击文件按钮时展开助手工作栏，并聚焦默认存在且不可关闭的“工作区”单实例。该实例保持
+“跟随当前上下文”或“固定到指定对象”状态；迁移或布局修复发现实例缺失时补回，并默认跟随
+当前项目。没有项目时使用已配置的默认工作区。跟随上下文所需的路径不可用时，面板显示修复
+入口；已有有效固定目标不受当前项目和默认工作区状态影响。
+
+### FR-7 终端入口
+
+点击终端按钮时展开助手工作栏。当前执行空间有正在启动或运行中的终端时聚焦最近使用的实例；
+没有时创建一个绑定当前执行空间的新终端，已退出、已中断或失败的历史 Tab 保持不变。没有
+项目时当前执行空间为本机 Home。创建额外并行终端继续使用工作栏现有的“+”目录入口。
+
+### FR-8 浏览器入口
+
+点击浏览器按钮时展开助手工作栏，并优先聚焦绑定当前 Conversation 的最近使用浏览器实例；
+没有匹配实例时创建一个。没有活动 Conversation 时聚焦最近使用的浏览器实例；完全不存在时
+创建待绑定空实例。该快捷入口不会因连续点击创建重复实例；用户通过工作栏“+”选择浏览器时
+则始终创建新实例。入口不打开系统默认浏览器，也不创建旁路 WebView。
+
+### FR-9 资源监控入口
+
+点击资源监控按钮时展开助手工作栏，并打开或聚焦单实例的本机“资源监控”面板。面板显示
+整机 CPU 使用率、内存使用量与总量、磁盘读写速率，以及 GoodBuddy 桌面进程的 CPU、内存
+和进程数摘要。指标不可用时显示具体项目和原因，不能显示为 `0`。
+
+资源面板处于可见活动状态、工作栏已展开且应用窗口未隐藏或最小化时，每 2 秒采样一次，在
+Renderer 内存中最多保留最近 5 分钟。任一条件不满足时停止采样；首期不在后台持续监控，
+也不据此产生侧栏告警。首次采样及停止后恢复的首次采样只建立 CPU 和磁盘 IO 速率基线，
+不显示伪造的 `0` 值。
+
+### FR-10 快捷入口状态
+
+工具面板已激活时，对应按钮显示选中状态；面板存在但未激活时保持普通状态。运行中、错误或
+等待用户处理可以显示徽标，但必须有可访问文字，且不得自动抢占当前面板。
+
+### FR-11 应用导航设置
+
+设置页提供“应用与工具”管理入口。首期“应用”区域列出三个内置应用并提供“显示在侧边栏”
+Switch，切换后立即持久化。系统工具区域列出四项内置固定能力，不提供虚假的卸载或停用按钮。
+
+### FR-12 偏好持久化
+
+应用可见性按设备持久化。升级时保留当前行为：已有可用内置应用继续显示；魔法笔记原有功能
+启停设置保持原意，不由新的导航可见性覆盖。
+
+### FR-13 窄窗口行为
+
+窄窗口下主侧栏仍按现有抽屉方式显示。系统工具按钮保持单行且不与设置按钮重叠；空间不足时
+收起文字和非必要分隔，不隐藏四个系统工具或设置。
+
+### FR-14 项目活动汇总
+
+用户在任一项目中都能查看跨项目的运行中与待处理会话，并从活动列表直接进入所选会话。
+汇总入口仅在有运行中或待处理会话时显示在项目选择器下方，无活动时整行隐藏。点击后先显示有活动会话的项目，
+悬停或点击项目展开会话子菜单，点击会话进入该条对话。项目菜单保留原有分组与顺序，并显示
+各项目的活动数量；级联菜单内的项目顺序不随待处理或运行中数量变化。
+汇总不受当前项目、搜索条件或最近历史条数限制。计数与排除规则见
+[活动逻辑](./logic-design.md#9-项目活动汇总)，交互见[活动界面](./ui-design.md#10-项目活动汇总)。
+
+验收覆盖跨项目后台运行、同会话多任务去重、提问与审批优先、较早的仍在运行或等待处理的
+会话可见，以及从带搜索条件的页面或有未保存修改的设置页跳转。结束后仅有未读标记的
+会话不保留在活动汇总中；已完成未读面板不属于本项交付。
+
+## 6. 权限与安全
+
+- 快捷入口不授予新的文件、命令、网络或浏览器权限。
+- 系统工具继续使用 Main、Preload、执行空间 Grant、Ask/Execute 和现有审批边界。
+- Renderer 不因新增入口获得任意文件系统、PTY、进程或 Electron API。
+- 资源指标由 Main 采集并以有界结构返回；Renderer 不接收进程命令行、环境变量或任意 PID。
+- 资源样本只保存在当前 Renderer 内存中，不写入运行记录、SQLite 或遥测服务。
+- 插件贡献类型只是界面与导航声明，不能代替权限清单、用户授权和运行隔离。
+- 运行记录继续记录由系统工具触发的受审计操作。
+
+## 7. 产品验收
+
+- 主导航能明确区分固定系统入口和可配置内置应用。
+- 运行记录在所有应用显隐组合下保持可见并可打开。
+- 左下角不再用“本地工作区”与系统架构占据主要空间。
+- 文件、终端、浏览器和资源监控均可从左下角打开正确的工作栏面板，且不产生第二套内容界面。
+- 连续点击系统工具不会无意创建重复的浏览器或终端实例；工作区始终复用不可关闭的固定实例。
+  用户通过工作栏“+”可以显式创建额外浏览器或终端实例。
+- 资源监控以 2 秒间隔更新，保留不超过 150 个样本；面板不活动、工作栏收起或窗口隐藏、
+  最小化后停止请求新样本。
+- CPU、内存、磁盘 IO 或 GoodBuddy 指标不可用时，页面区分部分可用与整体失败。
+- 隐藏内置应用不删除数据、不停止后台计划，并能从设置恢复；保存失败时入口保持原状。
+- 键盘、屏幕阅读器、浅色主题、深色主题和窄窗口均可完成相同操作。
+
+## 8. 分期
+
+### 首期
+
+- 将侧栏最底部改为内置应用中心入口，设置按钮保持独立；具体列表、宫格或卡片样式从
+  Demo 中收敛确定。
+- 应用中心提供魔法笔记、知识库、智能心跳的浏览、搜索与打开，不要求安装。
+- 支持应用常驻主导航、取消常驻和排序；未常驻应用仍可从应用中心打开，隐藏不删除数据或停止后台任务。
+- 应用中心和应用页面就近提供已有功能设置，共享真实设置来源；已有全局设置入口定位到同一界面。
+  魔法笔记优先接入待办数量、AI 评论方式和评论形式，入口显示与常驻控制统一，避免重复开关。
+- 文件、终端、浏览器保留在右侧工作栏 Tab，不在左下角复制入口，也不纳入应用中心。
+- 原计划的本机资源监控仍作为系统工具交付项，在右侧增加单实例面板；与应用中心分别实现和验证。
+- 保持运行记录为固定系统入口。
+
+首期验收需覆盖：无商店入口时可以访问全部内置应用；取消常驻后仍可重新打开和配置；
+不同设置入口状态一致；常驻排序重启后保留；右侧工具切换不改变当前应用页面。
+本节是范围调整，Demo 交互通过不代表正式功能已经实现。
+
+### 补充要求：魔法笔记迁移与入口联动
+
+- 将现有魔法笔记设置迁入应用中心的应用设置界面，笔记页面内的设置入口访问同一份配置。
+  魔法笔记可常驻主导航；原全局设置位置如保留入口，应定位到共同设置界面。
+- 魔法笔记相关布尔开关默认全部开启，包括入口显示（常驻）和未完成待办数量显示。
+  AI 评论方式、评论形式是单选项，沿用现有默认值，不把“全部开启”解释为同时选中多个模式。
+  新默认值适用于未配置状态，迁移时保留用户已明确保存的选择。
+- 应用关闭后的入口联动必须覆盖主导航和会话页面，不能只更新应用中心卡片或一个菜单。
+  知识库关闭后，左侧知识库菜单及会话中的知识库入口按钮同步移除；重新开启后按配置恢复。
+- “取消常驻”只移除主导航捷径；“关闭应用”移除该应用在主导航、会话等业务界面的入口。
+  应用中心保留管理和重新开启入口。原型中仅有常驻控制，正式设计需补齐这两种状态，避免混用。
+- 入口变化不删除已有笔记或知识数据。知识库已打开页面、会话已关联知识以及后台任务的处理，
+  在详细逻辑同步时分别定义，不能仅凭隐藏按钮推断功能或后台行为已经停用。
+
+补充验收：从任一配置入口关闭知识库，主导航和当前会话按钮立即同步移除，切换会话、
+重启后也不重新出现；重新开启后恢复相应入口。验证魔法笔记未配置时的默认开启，以及
+已有关闭选择在迁移后保留。设置保存失败时各入口保持原状态，不能出现互相矛盾的显示。
+
+### 后续：应用商店与扩展
+
+- 单独设计应用商店的目录、搜索、推荐、详情及安装管理，时间与具体范围另行确定。
+- 插件应用和插件工具注册，以及安装、更新、卸载与权限说明。
+- 插件应用可常驻主导航；插件工具按工作栏扩展设计接入，不恢复左下角重复系统工具条。
+- 用户级快捷键与命令面板接入同一贡献命令。
+
+现有 Demo 的商店页、项目管理和阅读空间安装流程仅保留为未来交互参考，不纳入首期验收，
+也不作为已有商店能力的说明。首期实现不预建插件安装服务或远程目录协议。
+
+### FR-15 私有化市场与 YAML 交换（后续）
+
+市场面向组织私有化部署。用户配置市场 URL 后即可获取该来源的应用目录与详情，并按需获取
+应用；需要认证的来源复用其登录流程。市场不可达时说明原因并允许重试，不影响已安装应用
+和内置应用使用，也不自动切换到公共市场。市场 URL 只影响应用市场，不改变模型、桌面更新
+或 Runtime 的下载源。
+
+应用支持以 `.yml` 导入、导出，兼容 `.yaml` 扩展名，用于组织内部共享、备份和迁移。
+导出内容为应用定义及可迁移配置，包含格式版本、应用标识、应用版本、入口声明和依赖说明；
+凭据、会话、笔记及知识库业务数据不随应用定义导出。导入前展示应用摘要、缺失依赖和与已有
+应用的冲突；同标识应用由用户选择更新或取消，不静默覆盖本机配置。
+
+YAML 描述文件不能代替模型权重或插件程序包。有外部依赖时应明确资源引用；离线导入仅在
+所需资源已具备时可完成使用，否则列出需要补充的资源，不显示为可运行。导入应用不会自动
+启动模型或执行任务。
+
+未来 ShareServer 提供私有市场目录、应用定义的导入导出、发布和版本资源分发；桌面端负责
+配置来源、获取目录、本地导入导出及应用安装管理。服务端职责归属见
+[ShareServer 总体设计](../../architecture/share-network-architecture.md)。本节记录后续需求，
+尚未确定 API、YAML Schema 或服务端交付版本，不纳入应用中心首期。
+
+### FR-16 本机模型管理入口（新增计划项）
+
+应用中心提供“本机模型”内置管理应用，可选择常驻左侧，打开主内容区管理页。该入口统一
+查看各功能使用的本机模型及服务状态，包括已接入的 OCR、向量、语音或推理引擎；具体支持
+清单需核对现有模型服务后确定，不因提供入口而假定全部引擎均已支持进程控制。
+
+页面展示模型名称、用途、所属引擎、管理方式、运行状态、占用情况及使用它的应用或任务。
+GoodBuddy 管理的进程提供启动、停止、重启和错误查看；外部启动的模型服务标明“外部管理”，
+提供连接状态与配置入口，未接入其管理接口时不提供停止或重启。进程内运行的模型按引擎实际
+能力提供加载与释放，不伪造独立进程。
+
+停止或重启前展示正在使用该服务的任务和影响，由用户决定是否继续；取消时保留运行状态，
+失败时显示实际状态和原因。多个应用共用同一模型服务时展示同一个服务及其使用方，不重复
+启动进程。隐藏管理入口、关闭管理页面或取消应用常驻均不停止模型；卸载模型文件是独立操作。
+
+资源监控仍是只读系统工具，本机模型管理负责模型生命周期，两者共享可用的状态来源。
+该项可独立于商店交付；当前只纳入计划，具体分期、任务使用期间的停止策略和各引擎管理能力
+在详细设计中确定。原首期资源监控的 GoodBuddy 桌面进程统计范围不因此扩大。
@@ -0,0 +1,64 @@
+# 项目活动级联实施进度
+
+## 2026-09-14：菜单独立高度修正
+
+生产菜单移除共用双栏表面，会话层独立定位到选中项目行。打开较长会话列表时，项目层的位置、
+宽度与高度保持不变；会话层独立限制窗口边界和滚动。两侧均无法容纳子菜单时使用同层返回交互。
+
+`npx vitest run src/renderer/src/ProjectActivity.test.tsx` 通过 13 项，类型检查与 Lint 通过。
+`npm test` 运行 60 秒后超时，未取得完整结果。
+
+最终源码的 Electron 43.2.0 / Chromium 150 组件 fixture 使用生产样式与中文 i18n、模拟活动数据，
+深浅主题共 14 个场景、108 条检查通过，覆盖短/60 条会话、两层独立滚动、底部避让、向左展开、
+375px 窄屏及 640px 两侧空间不足。桌面项目层打开前后矩形一致，短窗口会话层底部保留 16px。
+此项验证实际组件排版和交互，不代表完整 Main/Preload 端到端验证；未修改远程执行路径。
+
+## 2026-09-13：生产活动入口
+
+对应 [FR-14](./prd.md#fr-14-项目活动汇总)、[US-E1 / US-E2](./user-stories.md#6-epic-e项目活动级联)。
+本页只记录项目活动入口，不表示应用中心计划已交付。
+
+`App` 已接入 `ProjectActivity` 常驻摘要和锚定级联菜单。会话和项目计数继续使用现有
+`deriveConversationActivity` 结果，点击会话继续调用 `openActivityConversation`。未增加
+持久化字段、IPC 或 Runtime 状态。项目选择器分组及计数保持原有行为。
+
+组件与 App 定向回归通过 32 项，覆盖空闲入口、稳定项目及 SSH Host 顺序、待处理优先、
+跨项目精确跳转、设置离开检查、实时状态清理、键盘返回、外部关闭和窄侧栏焦点。
+
+Windows Electron 视觉 fixture 使用当前 `ProjectActivity`、生产样式和 i18n，活动数据为
+受控样例。浅深主题分别验证 `1280×800`、`960×720`、`720×640`、`640×420`、`375×600`；
+原生键盘验证 Enter、上下及右方向键、End、两级 Escape、Tab 退出，另测左侧回退和空闲入口。
+此项证明组件的实际 Chromium 排版与交互，不代表完整生产 Main/Preload 的端到端验证。
+
+浏览器遮挡复用共享菜单相交机制，组件测试检查相交和非相交结果；本轮未单独驱动原生
+`WebContentsView` 可见性。远程 Agent 执行路径未改动，未发出模型或知识库请求。
+
+提交前复核：`npm run typecheck`、`npm run lint` 通过；单独运行
+`npx vitest run src/renderer/src/ProjectActivity.test.tsx`，11 项通过。
+`npm test` 在 240 秒后超时，超时前 `tests/agent-package.test.ts` 的
+`verifies and installs offline dependency inventories larger than one MiB` 用例失败，未取得完整结果。
+
+Demo 已按最新讨论隐藏空闲摘要并移除会话行箭头；生产空闲摘要在下述非驻留修正中对齐。
+后续界面修正已移除生产会话行箭头，并为活动摘要与下方新建会话增加 `8px` 间距。
+
+## 2026-09-14：摘要非驻留修正
+
+生产 `ProjectActivity` 在无活动时返回空内容，活动归零时关闭级联菜单；新活动只恢复摘要。
+组件回归 11 项通过，覆盖初始空闲、活动归零关闭菜单及活动恢复后不自动展开。
+App 的 `project activity integration` 定向回归 18 项通过，类型检查与 Lint 通过。
+本轮 `npm test` 在 60 秒后超时，未取得全量结果；未重新执行 Electron 视觉验证。
+
+## 2026-09-14：0.13.2 候选验证
+
+正式发布准备时再次复现 App 问答用例的时序失败。活动摘要改为常驻后，等待该入口出现
+不再意味着会话初始化和 Runtime 状态读取已经完成；测试有时点击仍被禁用的发送按钮，
+留下未消费的一次性问答 mock，继而影响后续用例。
+
+测试现等待已加载的会话和可用发送按钮，并在每个用例前重置问答及审批响应 mock。
+答案重载用例等待提交后的界面状态，而不只等待 API 被调用。未修改生产交互、
+未增加固定延时，也未跳过失败用例。相关 20 项连续三轮通过，完整 App 与 Agent
+发布说明检查共 227 项通过。
+
+最终候选 `npm test` 通过 4,155 项、跳过 66 项、失败 0 项；`npm run typecheck`、
+`npm run lint` 和 `npm run release:notes:verify` 均通过。发布准备未执行本地生产构建、
+打包或安装包启动探针，原生包验收由主分支与标签 CI 完成。
@@ -0,0 +1,437 @@
+# 应用导航与系统工具入口技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| UI 设计 | [UI 设计](./ui-design.md) |
+
+## 1. 现状
+
+主页面没有 URL Router，由 `App.tsx` 中的 `WorkspaceView` 和 keep-alive 状态切换：
+
+```ts
+type WorkspaceView =
+  | 'chat'
+  | 'magic-notes'
+  | 'knowledge'
+  | 'heartbeat'
+  | 'activity'
+  | 'settings'
+```
+
+文件、浏览器和终端已经由 `RightAssistantSidebar`、`WorkbarShell` 与 `workbar-contracts.ts`
+承载。工作区是不可关闭的单实例应用，浏览器和终端是多实例应用。浏览器多实例的跨进程
+实现以[浏览器多实例技术设计](../assistant-workbar/browser-tabs-technical-design.md)为准。代码中尚无资源指标采集和资源监控
+面板。现有侧栏底部 `user-card` 整行打开设置，并显示“本地工作区”和平台架构。
+
+本次改动增加入口编排、从主侧栏到工作栏的命令通道，以及本机资源监控的 Main/Preload/
+Renderer 最小实现。文件、终端和浏览器后端保持不变。
+
+## 2. 模块边界
+
+| 模块 | 责任 |
+| --- | --- |
+| `App.tsx` | 组合主导航、系统工具栏、设置入口和页面离开检查 |
+| `SidebarSystemTools`（新增） | 渲染四个系统工具按钮并发送打开意图 |
+| `RightAssistantSidebar.tsx` | 接收打开意图，调用工作栏实例创建或激活逻辑 |
+| `WorkbarShell.tsx` | 继续负责实例策略、Tab、目录和焦点行为 |
+| `workbar-contracts.ts` | 继续作为工作栏应用 ID 和实例布局的权威契约 |
+| `resource-monitor-contracts.ts`（新增） | 定义本机资源快照、可用性和错误码 |
+| `resource-monitor-service.ts`（新增） | 在 Main 中采集并规范化本机与 GoodBuddy 指标 |
+| `ResourceMonitorPanel.tsx`（新增） | 按需轮询、保留有界历史并渲染资源面板 |
+| `application-settings-contracts.ts` | 增加应用导航偏好 schema 和默认值 |
+| `application-settings-store.ts` | 迁移并原子保存应用导航偏好 |
+| `PlatformFeaturesSettingsSection` 或独立设置 Section | 编辑“显示在侧边栏”偏好 |
+
+不要在 `SidebarSystemTools` 中读取文件、创建 PTY、操作浏览器或采集系统指标；该组件只发送
+有界的工具 ID。
+
+## 3. Renderer 契约
+
+### 3.1 系统工具 ID
+
+```ts
+export const sidebarSystemToolIds = [
+  'workspace',
+  'terminal',
+  'browser',
+  'resources'
+] as const
+
+export type SidebarSystemToolId = (typeof sidebarSystemToolIds)[number]
+```
+
+该类型可以放在 Renderer 内共享模块。首期不暴露 IPC，因为动作只编排已有工作栏 Renderer
+状态；实际能力调用继续走现有 Preload API。
+
+### 3.2 打开意图
+
+`App` 向 `RightAssistantSidebar` 传入单调递增的请求或命令对象：
+
+```ts
+type WorkbarOpenIntent = {
+  requestId: number
+  appId: 'workspace' | 'terminal' | 'browser' | 'resources'
+  reason: 'sidebar-system-tool'
+  context?: { conversationId?: string; projectId?: string }
+}
+```
+
+`requestId` 使连续点击同一工具仍能被消费。不要仅设置 `assistantSidebarTab`，因为用户可能已
+关闭对应实例，且终端需要按执行空间寻找实例。
+
+建议由 `RightAssistantSidebar` 在消费意图后通过现有 `WorkbarShell` 控制接口完成。控制器必须
+接收上下文和调用原因，不能只按 `appId` 查找第一个实例：
+
+```ts
+type WorkbarController = {
+  openOrActivate(intent: WorkbarOpenIntent): Promise<WorkbarTabInstance>
+}
+```
+
+若当前 `WorkbarShell` 没有命令式入口，先增加窄的回调或受控请求 Props，不引入全局事件总线。
+
+工作区意图始终激活注册表中的不可关闭单实例；仅在迁移或布局损坏时补回。浏览器意图按
+`conversationId` 激活最近使用的匹配实例，没有匹配实例时创建一个。工作栏“+”不走该去重
+路径，选择浏览器时始终创建新实例。
+
+### 3.3 终端匹配
+
+工作栏“+”目录选择终端时每次创建新实例；侧栏系统工具按钮执行“进入当前终端”，采用：
+
+1. 解析当前项目对应的 `ExecutionSpaceSelection`。
+2. 在现有终端实例中按目标 identity 查找 `starting` 或 `running` 状态。
+3. 存在多个匹配实例时激活最近使用的实例。
+4. 没有匹配实例时调用现有终端创建流程。
+
+`closing`、`exited`、`interrupted` 和 `failed` 实例保留为历史 Tab，不阻止快捷按钮创建新终端。
+工作栏“+”继续按原规则创建额外终端，不受快捷按钮去重影响。
+
+### 3.4 资源监控工作栏应用
+
+在 `workbar-contracts.ts` 中增加 `resources`：
+
+```ts
+{
+  id: 'resources',
+  instancePolicy: 'single',
+  defaultContext: 'application'
+}
+```
+
+该应用不加入升级后的默认打开实例。侧栏资源按钮与工作栏“+”目录都通过既有单实例规则创建
+或聚焦它。
+
+## 4. 应用导航偏好
+
+### 4.1 设置结构
+
+在 `ApplicationSettings` 增加独立字段：
+
+```ts
+type BuiltInApplicationId = 'magic-notes' | 'knowledge' | 'heartbeat'
+
+type ApplicationNavigationSettings = {
+  hiddenBuiltInApplicationIds: BuiltInApplicationId[]
+}
+```
+
+默认值为空数组，保持升级前所有可用入口可见。ID 数组可以避免为每个应用增加一个顶层布尔
+字段；Zod schema 必须去重、限制数量并拒绝未知内置
+ID。
+
+首期不保存排序，因为内置应用顺序固定。插件偏好在插件系统确定稳定 identity 和卸载保留
+规则后另行扩展，不提前混入当前 schema。
+
+### 4.2 与现有开关组合
+
+入口可见条件为：
+
+```ts
+const visible = featureEnabled && !hiddenBuiltInApplicationIds.includes(id)
+```
+
+`magicNotesEnabled` 继续控制功能启停。知识库和智能心跳若未来增加业务启停开关，也按同一组合
+规则处理。功能停用时设置页保留显隐偏好但禁用显隐 Switch，并提供原功能设置入口。导航设置
+不能写回现有开关。
+
+### 4.3 持久化与 IPC
+
+沿用现有应用设置链路：
+
+```text
+Renderer
+  -> window.goodbuddy.updates.updateSettings
+  -> settings:application:update
+  -> application-settings-store
+  -> application-settings.json
+```
+
+更新继续由 Main 校验可信 sender、Zod 输入和原子写入。设置版本迁移只补充默认空数组，不
+修改已有 `magicNotesEnabled` 或其他平台设置。
+
+## 5. 侧栏底部重构
+
+现有 `user-card` 是一个覆盖整行的设置按钮。实现时替换为容器和相邻独立按钮：
+
+```tsx
+<div className="sidebar-footer">
+  <SidebarSystemTools onOpenTool={openSystemTool} />
+  <button aria-label={t('navigation.settings')} ...>
+    <Settings aria-hidden="true" />
+  </button>
+</div>
+```
+
+不能在设置按钮内部嵌套工具按钮。设置按钮继续调用 `navigateFromSidebar('settings', trigger)`，
+保留设置预加载、焦点恢复和未保存离开确认。
+
+系统工具按钮调用统一 `openSystemTool`：
+
+1. 设置工作栏打开意图。
+2. 展开工作栏。
+3. 由工作栏创建或激活实例。
+4. 按现有策略把焦点移入目标面板。
+
+工作栏仍由窗口右上方的固定开关关闭，关闭后的焦点返回该开关。
+
+## 6. 工作栏状态与快捷按钮
+
+`RightAssistantSidebar` 应向 `App` 暴露当前活动实例的 `appId` 和必要的有界状态摘要，或由
+现有 `onTabChange` 扩展得到。主侧栏不读取终端输出、文件内容、URL 或活动详情。
+
+```ts
+type SidebarSystemToolState = {
+  activeToolId?: SidebarSystemToolId
+  statusByToolId?: Partial<Record<SidebarSystemToolId, 'attention' | 'error' | 'running'>>
+}
+```
+
+首期可以只实现 `activeToolId`，没有可靠聚合来源时不显示状态徽标。不能根据局部事件猜测错误
+或运行状态。
+
+## 7. 应用显隐更新
+
+应用显隐 Switch 复用平台功能设置的即时更新模式。请求开始后禁用三个应用显隐 Switch，只
+允许一个完整目标集合处于提交中。Main 返回成功结果后更新 App 中的平台设置快照，主导航
+随之变化。失败时恢复控件原值，在对应设置行显示可重试错误；主导航继续读取最后一次成功
+保存的设置。
+
+## 8. 插件兼容边界
+
+首期不增加插件注册表、插件 schema 或插件持久化字段，只保留系统 ID 不向插件开放的产品边界。
+插件市场设计需要单独确定 Host、权限、签名、生命周期和稳定 identity；不得直接复用 DeepSeek
+Harness 的 npm 插件市场。
+
+## 9. 本机资源监控
+
+### 9.1 采集范围
+
+首期在 Main 中使用经过依赖审查的 `systeminformation` 获取整机 CPU、内存和磁盘 IO，使用
+Electron `app.getAppMetrics()` 汇总 GoodBuddy 桌面进程 CPU、内存和进程数。采集函数不接收
+Renderer 提供的路径、PID、设备名或命令。
+
+首期指标定义：
+
+- CPU：整机忙碌时间占比，规范化为 `0` 至 `100`。
+- 内存：总字节数、可用字节数和 `总量 - 可用量` 得到的使用量。
+- 磁盘 IO：所有可用本机磁盘的每秒读取与写入字节数。
+- GoodBuddy：`app.getAppMetrics()` 返回的桌面进程聚合 CPU、工作集内存和进程数量。各进程
+  CPU 先相加，再按逻辑处理器数量归一化为整机容量占比 `0` 至 `100`；不能通过截断总和处理
+  多核数值。
+
+受管 Runtime、MCP 和终端子进程的逐进程指标不在首期范围。磁盘 IO 在平台或权限不足时返回
+不可用错误码，不能回退为 `0`。新增依赖在合入前需要完成许可证、维护状态、打包体积和供应链
+检查；检查未通过时应选择提供同等跨平台语义的 Main 侧实现，不能改用 Renderer Shell 命令。
+
+### 9.2 快照契约
+
+```ts
+type ResourceMetric<T> =
+  | { status: 'available'; value: T }
+  | { status: 'warming-up' }
+  | { status: 'unavailable'; reason: ResourceMetricUnavailableReason }
+
+type LocalResourceSnapshot = {
+  sampledAt: string
+  host: {
+    cpuPercent: ResourceMetric<number>
+    memory: ResourceMetric<{
+      usedBytes: number
+      totalBytes: number
+    }>
+    diskIo: ResourceMetric<{
+      readBytesPerSecond: number
+      writeBytesPerSecond: number
+    }>
+  }
+  goodbuddy: {
+    cpuPercent: ResourceMetric<number>
+    memoryBytes: ResourceMetric<number>
+    processCount: ResourceMetric<number>
+  }
+}
+```
+
+所有数字必须有限且非负；百分比限制为 `0` 至 `100`，字节数设置跨 IPC 上限。`sampledAt` 由
+Main 生成。不可用原因使用稳定枚举，例如 `unsupported-platform`、`permission-denied`、
+`collector-timeout` 和 `collector-failed`，不向 Renderer 返回原始命令输出。`warming-up` 只用于
+依赖两个采样点的 CPU 与磁盘 IO，不能用于掩盖采集失败。
+
+### 9.3 Preload 与 IPC
+
+Preload 只暴露：
+
+```ts
+resourceMonitor.getLocalSnapshot(input: {
+  resetIntervalBaseline: boolean
+}): Promise<LocalResourceSnapshot>
+```
+
+对应 IPC 为 `resource-monitor:local-snapshot:get`。Main 验证可信 sender；单次采集设置超时，
+并合并同一时刻的并发请求，防止多个 Renderer 重复启动系统采集。采集超时后向调用方返回
+有界错误，但底层 Promise 仍占用唯一单飞槽位，直到实际结束；在此之前不启动第二个采集
+任务。输入只接受布尔值，接口不提供任意进程、磁盘或远程主机查询。
+
+合并规则区分普通请求与基线重置请求：
+
+- 普通请求在途时，新的普通请求复用它。
+- 普通请求在途时收到重置请求，Main 最多登记一个待执行重置；当前采集结束后再执行，不能
+  用普通请求结果满足重置请求。
+- 多个重置请求复用同一个在途或待执行重置。
+- 重置请求在途时，普通请求复用其 `warming-up` 结果，下一次时钟再取得区间值。
+
+因此服务最多持有一个在途采集和一个待执行重置。调用方超时不取消这个顺序，也不增加队列
+长度。
+
+面板每次从非活动状态恢复后的首次请求传入 `resetIntervalBaseline: true`。Main 消费本次
+`systeminformation` 与 Electron CPU 读数并重置区间基线，CPU 和磁盘 IO 返回 `warming-up`；
+内存等瞬时指标正常返回。后续请求传入 `false` 并计算当前区间值，避免把面板停用期间计入
+速率。
+
+### 9.4 轮询与历史
+
+`ResourceMonitorPanel` 仅在工作栏展开、`resources` 为活动实例且
+`document.visibilityState === 'visible'` 时启动轮询：
+
+1. 进入活动状态后立即请求一次，并设置 `resetIntervalBaseline: true`。
+2. 此后每 2 秒请求一次；前一请求未结束时跳过本次时钟。
+3. Tab 失活、工作栏收起、页面变为隐藏或组件卸载时清理定时器，并忽略较晚返回的旧请求。
+4. Renderer 环形队列最多保留 150 个带真实时间戳的样本。
+5. 采集失败不追加伪造样本，也不持久化历史。
+
+资源数据不写入应用设置、工作栏布局、运行记录或 SQLite。工作栏布局只保存 `resources` 实例
+及其活动状态。
+
+## 10. 测试
+
+### 10.1 Renderer 测试
+
+- 固定入口顺序不受三个应用显隐组合影响。
+- 运行记录和设置没有显隐控件。
+- 四个系统工具按钮具有名称、工具提示、键盘行为和选中状态。
+- 文件复用不可关闭单实例；浏览器和终端按当前上下文聚焦匹配实例，工作栏“+”允许显式多实例。
+- 工具按钮展开工作栏但不改变当前主页面。
+- 显隐更新成功后主导航立即变化，失败时 Switch 和主导航恢复原状态。
+- 窄窗口下工具按钮不重叠，焦点恢复正确。
+- 资源面板只在可见活动时轮询，跳过重叠请求并把历史限制为 150 项。
+- 窗口隐藏、最小化和恢复时停止轮询并重新建立区间基线。
+- 资源部分可用、全部失败和重新进入活动状态均显示正确结果。
+
+### 10.2 Main 与契约测试
+
+- 新设置字段默认值、合法 ID、重复 ID、数量上限和未知 ID 校验。
+- 旧版本设置迁移后默认显示所有既有应用。
+- 更新导航偏好不修改魔法笔记启停等无关字段。
+- 原子写入失败时保留最后一次有效设置。
+- 资源快照拒绝 NaN、Infinity、负数字节数、越界百分比和未知错误码。
+- 采集超时、权限不足和磁盘 IO 不支持时返回有界部分结果。
+- 超时采集尚未实际结束时保持单飞，不累积新的后台采集任务。
+- 普通采集在途时收到基线重置请求，最多排队一个重置且不复用普通结果。
+- `resetIntervalBaseline: true` 时把 CPU 与磁盘 IO 标记为 `warming-up`。
+- GoodBuddy CPU 预热时，其内存和进程数仍可独立返回。
+- GoodBuddy 多进程 CPU 按逻辑处理器数量归一化，结果保持在 `0` 至 `100`。
+- GoodBuddy 摘要不包含 PID、命令行、环境变量或其他进程信息。
+
+### 10.3 回归范围
+
+- 工作栏布局恢复和已关闭实例重建。
+- 本地与托管 SSH 终端目标。
+- 浏览器无会话、创建中和 Agent 操作中状态。
+- 设置页未保存离开确认。
+- 魔法笔记待办数和智能心跳建议数徽标。
+- 浅色、深色、`220px` 与 `420px` 侧栏宽度。
+- Windows、macOS 和 Linux 的真实 CPU、内存与磁盘 IO 采集；不支持项显示准确原因。
+
+## 11. 实施顺序
+
+实施范围以 [PRD 分期](./prd.md#8-分期)为准。本节替代旧实施顺序；前文关于四个左侧
+系统工具按钮、仅持久化隐藏 ID 的契约需在实现前同步，不能直接按旧规格开发。
+
+1. 同步 PRD 功能要求、User Stories、逻辑、UI 与技术契约，收敛首期应用中心样式。
+2. 接入现有内置应用页面与最底部应用中心入口，保留独立设置和固定运行记录入口。
+3. 为常驻显隐和排序设计最小持久化契约，保留已发布的相关设置与用户数据，按保存结果更新导航。
+4. 接入应用设置的共同界面与既有设置更新路径，先验证魔法笔记多入口状态一致性。
+5. 验证右侧现有文件、终端、浏览器 Tab；移除计划中的左下角工具快捷条和专用于该快捷条的意图接口工作。
+6. 单独实现资源快照契约、Main 采集服务、Preload API 与右侧 `resources` 单实例面板。
+7. 验证键盘、焦点、浅深主题、窄窗口、设置失败、重启持久化和跨平台行为。
+
+首期使用内置应用清单，不依赖远程商店、插件注册或安装服务。商店目录、推荐、安装与
+更新机制在后续独立设计中确定；Demo 中的模拟商店不接入首期产品界面。
+
+后续设计输入见 [FR-15](./prd.md#fr-15-私有化市场与-yaml-交换后续) 与
+[FR-16](./prd.md#fr-16-本机模型管理入口新增计划项)：
+
+- 私有市场的 YAML Schema 应由桌面本地导入与 ShareServer 发布共用，具体协议与字段在
+  市场功能设计中确定。市场 URL 按设备保存，认证信息沿用受保护凭据存储；导出仅包含
+  可迁移应用定义与非敏感配置。
+- 程序包与模型资源单独分发。受管下载声明不可变版本、预期字节数和 SHA-256，下载开始后
+  固定来源，失败不静默切源；下载地址与重定向范围由 Main 验证，不接受 Renderer 任意覆盖。
+  市场来源配置不覆盖现有模型、应用更新或 Runtime 下载源设置。
+- ShareServer 的市场发布与分发实现由其独立仓库承接，本仓库先记录依赖，不将桌面需求
+  记录标为服务端已实现。
+- 本机模型管理实施前盘点现有 OCR、向量、语音及推理服务的生命周期接口，优先复用其
+  Main 服务。只为实际支持的操作提供 typed IPC；区分受管子进程、外部服务和进程内模型，
+  不把直连模型 HTTP 请求等同于独立模型进程。
+- 模型管理的详细逻辑需确定共享服务的使用方识别、忙碌时停止与重启、退出应用时的释放
+  行为，再接入管理页面并验证实际引擎。该工作单独排期，不依赖市场上线。
+
+## 12. 项目活动汇总
+
+对应 [FR-14](./prd.md#fr-14-项目活动汇总)，按[活动逻辑](./logic-design.md#9-项目活动汇总)
+派生状态，界面行为见[活动界面](./ui-design.md#10-项目活动汇总)。
+
+- `conversation-activity.ts` 从 `App.tsx` 的会话、`activeConversationIds`、全部可见
+  `assistantTasks` 和项目元数据派生会话行、全局及项目计数，不新增持久化活动副本。
+  `ProjectActivity` 在有活动时渲染汇总与项目、会话级联菜单，`ProjectSwitcher` 复用项目计数。
+- `App` 向 `ProjectActivity` 传入项目元数据、活动行、侧栏可见状态与既有精确跳转回调。
+  菜单按项目 ID 分组并记忆化派生集合；排序仅影响展示，不改聚合状态或持久化数据。
+- 两层菜单在同一 body Portal 内相接，桌面会话层使用独立 fixed 定位，不参与项目层高度计算。
+  项目层锚定摘要，会话层锚定选中项目行并独立限制窗口边界。布局在打开、层级变化、实时数据更新、窗口缩放和
+  滚动时按锚点重算；窄窗口隐藏项目面板并保留返回操作。菜单不调用 Modal 焦点隔离，
+  捕获阶段消费 Escape，防止触发窄侧栏的文档级监听；Tab 关闭后交还正常焦点顺序。
+  菜单关闭与焦点恢复在导航回调之前同步完成。
+- `role="menu"` 使浮层直接进入共享 `browser-viewport-occlusion.ts` 相交检测。未增加
+  浏览器实例的特殊隐藏条件，也不关闭或重建浏览器会话。
+- 持久化快照刷新时，同一条仍在流式输出的消息保留本地待审批、待回答信息，持久化终态
+  则清除这些信息。响应成功后对应 Task 立即退出等待状态；响应期间到达的新问题、审批或
+  终态不能被旧响应覆盖。
+- `AssistantDatabase.listTasks()` 保留最近历史窗口（默认 100 条），额外包含窗口外当前
+  运行或等待处理的可见 Task；`activeVisibleTaskSelect` 与 `toTask` 的有效状态保持一致，
+  待调度运行规范化为 `queued`，不因旧 Task 状态被误纳入实时集合。
+- `listConversations()` 保留最近 100 条活动会话，同时包含上述 Task 关联的较早活动会话，
+  以及含 `streaming` 消息的较早活动会话。两类列表去重后仍按原时间顺序返回，结果允许超过
+  历史窗口大小，避免后台工作被最近记录挤出。
+- `openActivityConversation` 按确切 Conversation ID 导航；内存中缺失时刷新持久化会话
+  列表并合并，再查找同一 ID。刷新失败或会话已不存在时显示通知，不回退到项目最新会话。
+  设置离开检查通过后才提交项目、会话及界面清理状态。
+- 远程恢复成功提示沿用独立的自动消失计时器；活动汇总更新不重置或替代该计时器。
+
+验证记录见[项目活动级联实施进度](./progress.md)。本次只改 Renderer 展示与交互，远程
+Runtime、Agent 协议和桌面到 Agent 的执行路径未改变。
@@ -0,0 +1,234 @@
+# 应用导航与系统工具入口 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 全局规范 | [GoodBuddy 统一界面设计系统](../../../UI-DESIGN.md) |
+
+本文定义入口、设置和轻量资源监控界面。文件、终端和浏览器的内容布局继续遵守助手工作栏
+文档。
+
+## 1. 侧栏信息架构
+
+```text
+品牌
+项目选择
+项目活动汇总（仅有活动时显示）
+新对话
+搜索
+
+当前对话
+魔法笔记               3
+知识库
+智能心跳               1
+运行记录
+
+最近对话
+...
+
+────────────────────────
+[文件] [终端] [浏览器] [资源]      [设置]
+```
+
+“当前对话”和“运行记录”属于固定系统入口。三个内置应用位于二者之间。侧栏底部不再显示
+“本地工作区”和 `platform · arch`；排障信息移至关于或诊断页面。
+
+## 2. 底部系统工具栏
+
+底部使用连续平整表面和顶部分隔线，不做成账户卡片或嵌套卡片。按钮顺序固定：
+
+| 位置 | 图标 | 可见工具提示 | 点击结果 |
+| --- | --- | --- | --- |
+| 1 | `FolderOpen` | 文件 | 聚焦不可关闭的工作区面板 |
+| 2 | `SquareTerminal` | 终端 | 打开或聚焦当前执行空间终端 |
+| 3 | `Globe` | 浏览器 | 聚焦当前 Conversation 的匹配浏览器实例 |
+| 4 | `Activity` | 资源监控 | 打开或聚焦本机资源监控面板 |
+| 末位 | `Settings` | 设置 | 打开设置页面 |
+
+图标使用项目现有 Lucide 库。每个按钮采用统一的 `34px × 34px` 点击区域，内部图标建议
+`16px`。工具栏使用 `8px` 内边距和 `4px` 间隔；设置按钮通过自动空白靠右，不添加第二条
+视觉分隔线。
+
+### 2.1 状态
+
+- 默认：透明背景，图标使用次级文字色。
+- 悬停：使用弱表面色，不能强于当前选中状态。
+- 选中：使用强调选中背景，并提高图标对比度。
+- 键盘焦点：显示统一焦点环，不能被侧栏边缘裁切。
+- 处理中：创建或激活请求未完成时暂时禁用对应按钮，保留尺寸并提供进行中名称。
+- 徽标：只用于等待处理、错误或活动状态，不显示无意义的常驻绿色圆点。
+
+选中状态表达“对应工作栏面板正在显示”，不表达功能已安装或权限已授予。
+
+## 3. 主导航应用区
+
+应用入口沿用现有 `nav-item` 行，不使用应用卡片。图标、名称和徽标保持单行：
+
+```text
+[图标] 魔法笔记                         3
+[图标] 知识库
+[图标] 智能心跳                         1
+```
+
+隐藏某个应用后，其余应用向上补位。运行记录始终位于最后一个可见应用之后，不因应用显隐
+改变样式或归类为工具。
+
+设置页打开期间，主侧栏显示最后一次成功保存的导航状态。Switch 更新成功后导航立即变化，
+失败时保持原导航。
+
+## 4. 应用与工具设置
+
+设置中心新增“应用与工具”分类，采用 `standard` PageShell：
+
+```text
+应用与工具
+管理主导航中的应用。系统工具由 GoodBuddy 提供并固定在侧栏底部。
+
+应用
+魔法笔记       笔记、待办和评论                 [显示在侧边栏  开]
+知识库         管理和检索知识                   [显示在侧边栏  开]
+智能心跳       查看计划、建议和运行历史          [显示在侧边栏  开]
+
+系统工具
+文件           打开当前工作区                   内置
+终端           进入当前执行空间                 内置
+浏览器         打开 GoodBuddy 受控浏览器         内置
+资源监控       查看本机 CPU、内存和磁盘 IO       内置
+
+系统入口
+当前对话、运行记录和设置位置固定，不参与上述配置。
+```
+
+应用显隐使用共享 Switch，标签必须是“显示在侧边栏”，不能缩写为“启用”。切换时立即保存，
+请求期间禁用三个应用显隐 Switch；失败后恢复原值，并在对应设置行显示可重试错误。系统工具
+使用紧凑只读列表，不渲染禁用的卸载、停用或固定按钮。
+
+功能已停用时，对应应用行显示“功能已停用”和设置入口，保留显隐偏好但暂时禁用 Switch。
+
+若某应用自身支持业务启停，应在该应用原有设置中保留“启用功能”开关，并用说明区分：
+
+- “显示在侧边栏”只控制入口。
+- “启用功能”控制该功能是否运行。
+
+## 5. 助手工作栏反馈
+
+点击系统工具后，右侧工作栏按现有布局回流打开。主内容页面保持不变，侧栏不渲染工具内容。
+
+- 文件：激活默认存在且不可关闭的“工作区”Tab，焦点进入目录区域或错误修复入口。
+- 终端：激活匹配终端，焦点进入终端输入区；新建期间保留按钮宽度和进度状态。
+- 浏览器：激活绑定当前 Conversation 的最近使用“浏览器”Tab；没有匹配实例时创建一个，
+  没有 Conversation 时按产品规则复用最近实例或进入待绑定空状态。
+- 资源监控：激活“资源监控”Tab，焦点进入指标摘要；首个样本加载后开始绘制历史。
+
+后台事件可以更新徽标，不能自动展开工作栏或切换当前 Tab。由用户点击快捷按钮触发的打开
+属于显式操作，可以展开工作栏并切换 Tab。
+
+### 5.1 资源监控面板
+
+资源监控使用紧凑单列，不使用指标卡片墙：
+
+```text
+资源监控                                      本机
+
+CPU                                  18%
+[最近 5 分钟折线图]
+
+内存                         9.6 / 32 GB
+[使用量进度条]
+
+磁盘 IO                 读 12 MB/s · 写 3 MB/s
+
+GoodBuddy
+CPU 4% · 内存 620 MB · 桌面进程 7
+
+更新于 14:32:08
+```
+
+- CPU 折线纵轴固定为 `0%` 至 `100%`，不能根据当前低负载动态放大波动。
+- 内存同时显示使用量、总量和百分比；进度条不代替文字数值。
+- 磁盘 IO 使用每秒读写字节并按统一单位格式化，不显示累计设备字节数。
+- GoodBuddy 摘要只显示聚合值，不列 PID、命令行或环境变量。
+- 首次加载或停止后恢复时，CPU 和磁盘 IO 显示“正在建立采样基线”，不先渲染 `0%`；内存
+  等瞬时指标可以立即显示。
+- 部分可用时只在对应指标行显示“不可用”和简短原因；全部失败时显示重试入口。
+- 图表不使用动效平移；`prefers-reduced-motion` 下行为不变。
+- 面板失去活动状态、工作栏收起或窗口隐藏、最小化时停止更新；返回后重新建立区间指标基线，
+  不填补离开期间的历史。
+
+## 6. 文案
+
+固定使用以下名称：
+
+| 对象 | 文案 |
+| --- | --- |
+| 设置分类 | 应用与工具 |
+| 文件系统工具 | 文件 |
+| 终端系统工具 | 终端 |
+| 浏览器系统工具 | 浏览器 |
+| 浏览器说明 | GoodBuddy 受控浏览器 |
+| 资源系统工具 | 资源监控 |
+| 资源范围 | 本机 |
+| 指标缺失 | 不可用 |
+| 应用显隐开关 | 显示在侧边栏 |
+| 内置来源 | 内置 |
+
+不再使用“本地工作区”作为侧栏底部身份名称。项目和默认工作区的路径继续由项目选择器、页面
+范围或工作区面板显示。
+
+## 7. 键盘和无障碍
+
+- 底部按钮均为独立 `button`，不能嵌套在整行设置按钮中。
+- Tab 顺序为文件、终端、浏览器、资源监控、设置。
+- 图标按钮通过 `aria-label` 提供名称，工具提示不能作为唯一可访问名称。
+- 工作栏打开后按现有焦点策略聚焦目标面板；用户通过固定工作栏开关关闭时，焦点返回该开关。
+- 选中按钮使用 `aria-pressed` 或等价的可访问状态，不能只依靠背景色。
+- 徽标的数量或状态合并进按钮可访问名称，例如“终端，1 个等待处理”。
+- 应用显隐 Switch 支持 Space 切换，保存失败后恢复原值并保留焦点。
+
+## 8. 响应式
+
+- 侧栏宽度 `220px` 至 `420px` 时，底部按钮尺寸不随宽度缩放。
+- 窄窗口继续使用现有侧栏抽屉；工具栏不转为多行。
+- 空间不足时缩小设置按钮前的弹性空白，不隐藏四个系统工具和设置。
+- 工具提示不得超出窗口；靠近底边时显示在按钮上方。
+- 粗指针设备不依赖悬停，按钮的可访问名称和选中反馈保持有效。
+
+## 9. 未来插件入口
+
+插件市场交付后另行定义插件区域、固定数量、溢出和权限界面。系统入口与四个系统工具的位置
+保持保留，不向插件开放。
+
+## 10. 项目活动汇总
+
+对应 [FR-14](./prd.md#fr-14-项目活动汇总)，状态与计数遵守
+[活动逻辑](./logic-design.md#9-项目活动汇总)。
+
+- 全局汇总按钮仅在有活动时显示在项目选择器下方，紧凑显示待处理与运行中数量，空闲时整行隐藏，
+  右侧显示展开箭头，与下方新建会话保留 `8px` 间距。可访问名称明确数量属于“全项目活动”。
+- 项目菜单在项目行显示同口径数量，保留“本地项目 / 远程项目 / 远程通道”分组和 SSH Host
+  层级，不因活动状态重排项目。数量为零时不显示标记，连接状态仍独立显示。
+  项目名独占一行，状态数量排列在名称下方，避免窄侧栏中数量挤占名称宽度。
+- 点击汇总在按钮下方打开项目菜单，只列有活动会话的项目，每项显示项目名和同口径计数。
+  桌面鼠标悬停或点击项目展开右侧会话菜单，右侧空间不足且左侧可容纳时向左展开。两个面板
+  相接，各自拥有边框、圆角与阴影；会话层对齐所选项目行，底部空间不足时仅上移会话层，
+  不改变项目层的位置或高度。指针离开项目行进入会话层时不收起。展开项目不切换当前会话。
+- 会话层顶部显示项目名，每行显示完整可换行的会话标题与明确状态文字，待处理会话排在
+  运行中会话之前。项目行保留子菜单箭头，会话行不显示箭头。不展开 Task、Job 或 Run 列表。
+- 点击会话先关闭菜单并恢复入口焦点，再请求进入该条会话；允许离开当前页面后，
+  选择所属项目、清除搜索和该会话未读标记、清除任务选择与会话操作菜单，窄窗口同时关闭侧栏。
+  设置页沿用未保存修改的离开检查，取消离开时保留原页面。
+- 菜单挂载到 body，使用 `menu`、`menuitem`、`aria-haspopup`、`aria-expanded` 与控制关系，
+  不隔离背景、不增加遮罩。原生浏览器相交遮挡沿用共享机制。
+- 打开后焦点进入首个项目；上下方向键循环选择当前层项目或会话，Home、End 到首尾，
+  Enter、Space 激活，右方向键进入会话层。左方向键或 Escape 返回项目层并恢复对应项目
+  焦点；顶层 Escape 关闭并恢复汇总焦点，不继续关闭窄侧栏。Tab 关闭菜单后继续正常焦点
+  顺序；点击外部、焦点离开、再次点击入口或隐藏侧栏也关闭菜单。
+- 单面板宽度为 `264px`，窗口小于 `620px` 或项目菜单两侧均无法容纳子菜单时，就地进入会话层并显示“返回项目列表”，
+  触控无需悬停。浮层距窗口边缘至少 `16px`，每层最大高度为 `480px`，短窗口进一步限制
+  高度并独立滚动。活动全部结束时，关闭已打开菜单并隐藏摘要。
@@ -0,0 +1,307 @@
+# 应用导航与系统工具入口 User Stories
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 设计中 |
+| 版本 | 0.2 |
+| 日期 | 2026-09-08 |
+| 关联 PRD | [应用导航与系统工具入口 PRD](./prd.md) |
+| 关联逻辑 | [功能逻辑设计](./logic-design.md) |
+
+## 1. 角色
+
+### 1.1 普通用户
+
+使用对话、笔记和知识功能，希望常用入口稳定，不需要理解工作栏实例模型。
+
+### 1.2 本地工作用户
+
+经常查看项目文件、打开终端、使用受控浏览器或检查电脑负载，希望从任意一级页面快速进入
+这些工具。
+
+## 2. Epic A：固定系统入口
+
+### US-A1 始终访问运行记录
+
+作为用户，我希望运行记录保持在固定位置，以便应用入口变化后仍能检查 Agent 和工具活动。
+
+验收：
+
+- Given 用户隐藏任意内置应用
+- When 用户查看主导航
+- Then “运行记录”仍显示在应用区之后
+- And 设置中没有隐藏、卸载或固定运行记录的选项
+
+### US-A2 从固定入口进入设置
+
+作为用户，我希望设置入口始终位于侧栏底部，以便快捷工具状态变化时仍能进入配置。
+
+验收：
+
+- Given 任意主页面和任意侧栏宽度
+- When 用户查看侧栏底部
+- Then 设置按钮保持可见且点击区域不与工具按钮重叠
+- And 点击后继续遵守未保存内容的离开确认
+
+## 3. Epic B：管理应用入口
+
+### US-B1 识别完整应用
+
+作为用户，我希望魔法笔记、知识库和智能心跳显示在主导航，以便知道它们会打开完整页面。
+
+验收：
+
+- Given 对应功能已启用且应用设置为显示
+- When 用户打开主侧栏
+- Then 应用位于“当前对话”和“运行记录”之间
+- And 点击应用在主内容区打开对应一级页面
+- And 原有待办或建议徽标继续显示
+
+### US-B2 隐藏低频应用
+
+作为用户，我希望隐藏不常用的内置应用，以便缩短主导航，但保留已有数据。
+
+验收：
+
+- Given 应用已有内容
+- When 用户关闭该应用的“显示在侧边栏”Switch
+- Then 主导航不再显示该应用
+- And 应用数据、计划和业务启停状态不变
+- And 用户可从同一设置位置恢复显示
+
+### US-B4 保留功能启停语义
+
+作为魔法笔记用户，我希望导航显隐与功能启停相互独立，以免整理导航时关闭功能。
+
+验收：
+
+- Given 魔法笔记功能已启用
+- When 用户只隐藏其侧栏入口
+- Then 笔记及待办处理能力继续按原设置工作
+- And 再次显示时恢复原页面和数据
+
+### US-B5 恢复显隐保存失败
+
+作为用户，我希望入口设置保存失败时继续使用原导航，以免界面状态与实际设置不一致。
+
+验收：
+
+- Given 应用显隐更新尚未完成
+- When 用户切换“显示在侧边栏”Switch
+- Then 三个应用显隐 Switch 在请求期间暂时不可操作
+- And 更新成功后主导航立即变化
+- And 更新失败时 Switch 和主导航恢复原状态并显示可重试错误
+
+## 4. Epic C：使用系统工具
+
+### US-C1 一键查看文件
+
+作为本地工作用户，我希望点击左下角文件按钮后直接查看当前工作区文件。
+
+验收：
+
+- Given 当前项目有有效根目录
+- When 用户点击文件按钮
+- Then 助手工作栏展开
+- And 聚焦默认存在且不可关闭的工作区单实例
+- And 文件按钮通过选中状态表明该面板正在显示
+
+### US-C2 处理无效工作区
+
+作为用户，我希望目录不可用时看到修复方法，并收到明确反馈。
+
+验收：
+
+- Given 工作区面板处于跟随模式
+- And 当前项目和默认工作区均不可用
+- When 用户点击文件按钮
+- Then 工作区面板仍打开
+- And 面板说明目录不可用并提供选择或修复目录的入口
+- And 应用不静默改用其他目录
+
+### US-C3 快速进入终端
+
+作为本地工作用户，我希望点击终端按钮后进入当前执行空间的终端。
+
+验收：
+
+- Given 当前执行空间已有正在启动或运行中的终端
+- When 用户点击终端按钮
+- Then 工作栏聚焦最近使用的匹配终端，不创建重复实例
+- Given 当前执行空间没有终端
+- When 用户点击终端按钮
+- Then 创建一个绑定该执行空间的新终端
+- Given 当前没有项目
+- When 用户点击终端按钮
+- Then 创建或聚焦使用本机 Home 的终端
+- Given 当前执行空间只有已退出、已中断或失败的终端
+- When 用户点击终端按钮
+- Then 创建新终端并保留原终端的历史状态
+
+### US-C4 使用远程项目终端
+
+作为远程项目用户，我希望同一个终端按钮进入远程项目目录，以免误在本机执行命令。
+
+验收：
+
+- Given 当前项目绑定托管 SSH 执行空间
+- When 用户点击终端按钮
+- Then 创建或聚焦绑定该远程项目及其权威目录的终端
+- And 面板持续显示远程主机和工作目录
+- And 连接失败时保留重连与诊断信息
+
+### US-C5 打开受控浏览器
+
+作为用户，我希望浏览器按钮打开 GoodBuddy 受控浏览器，以便查看与 Agent 相同的会话。
+
+验收：
+
+- Given 浏览器面板跟随当前上下文且当前会话已有浏览器会话
+- When 用户点击浏览器按钮
+- Then 工作栏聚焦绑定当前 Conversation 的最近使用浏览器实例
+- And 不打开系统默认浏览器或无意创建重复实例
+- Given 现有浏览器实例都绑定到其他 Conversation
+- When 用户点击浏览器按钮
+- Then 工作栏创建并聚焦绑定当前 Conversation 的新浏览器实例
+- Given 当前没有活动 Conversation
+- And 已存在浏览器实例
+- When 用户点击浏览器按钮
+- Then 工作栏聚焦最近使用的浏览器实例并保持其目标
+- Given 当前没有活动 Conversation
+- And 不存在浏览器实例
+- When 用户点击浏览器按钮
+- Then 创建待选择目标的空实例
+- Given 用户需要同一 Conversation 的另一个独立页面
+- When 用户从工作栏“+”选择浏览器
+- Then 每次创建拥有独立页面和导航状态的新实例
+- And 同一 Conversation 内共享隔离登录上下文
+
+### US-C6 查看本机资源
+
+作为本地工作用户，我希望快速查看 CPU、内存和磁盘 IO，以便判断任务变慢是否与本机负载
+有关。
+
+验收：
+
+- Given 资源监控面板尚未打开
+- When 用户点击左下角资源监控按钮
+- Then 助手工作栏创建并激活单实例资源监控面板
+- And 页面显示整机 CPU、内存、磁盘读写及 GoodBuddy 桌面进程摘要
+- And 页面每 2 秒更新一次，并用图表保留最近 5 分钟
+- When 用户切换到其他工作栏 Tab、收起工作栏、隐藏窗口或最小化窗口
+- Then 资源监控停止请求新样本
+- When 用户再次显示窗口并返回资源监控
+- Then 首次采样建立区间指标基线，下一次采样开始显示 CPU 和磁盘 IO 速率
+- Given 某项指标在当前平台不可用
+- When 页面收到部分结果
+- Then 该指标显示“不可用”及原因，其他指标继续更新
+
+### US-C7 从任意应用打开工具
+
+作为用户，我希望在魔法笔记、知识库、智能心跳和运行记录页面也能打开系统工具。
+
+验收：
+
+- Given 用户位于任意一级页面
+- When 用户点击文件、终端、浏览器或资源监控
+- Then 主页面保持不变
+- And 右侧工作栏打开对应面板
+- And 工具不会覆盖主内容或伪装成一级页面
+
+## 5. Epic D：可访问性和布局
+
+### US-D1 使用键盘打开系统工具
+
+作为键盘用户，我希望按顺序聚焦并打开左下角工具，以便不依赖鼠标。
+
+验收：
+
+- 每个系统工具和设置都是独立按钮
+- Tab 顺序与视觉顺序一致
+- Enter 和 Space 均可激活按钮
+- 每个纯图标按钮都有可访问名称和工具提示
+- 焦点样式不被侧栏边界裁切
+
+### US-D2 在窄窗口使用快捷栏
+
+作为小屏用户，我希望侧栏抽屉中的工具按钮保持可操作。
+
+验收：
+
+- 工具按钮保持单行且不重叠
+- 不因宽度不足隐藏文件、终端、浏览器、资源监控或设置
+- 触控点击区域符合统一界面规范
+- 关闭侧栏抽屉后焦点返回原触发按钮
+
+## 6. Epic E：项目活动级联
+
+### US-E1 从摘要进入确切会话
+
+对应 [FR-14](./prd.md#fr-14-项目活动汇总)。用户在当前项目工作时，可从项目选择器下方
+查看跨项目活动，先定位项目，再进入需要处理的会话。
+
+- Given 多个项目存在运行中和待处理会话，当前搜索仅匹配当前项目
+- When 打开全项目活动并悬停或点击另一个项目
+- Then 项目顺序保持稳定，该项目会话按待处理优先展示，当前页面和会话保持原选择
+- When 点击会话
+- Then 进入该确切 Conversation ID，清除搜索、任务选择和会话菜单，窄窗口关闭侧栏
+- Given 设置页有未保存修改
+- Then 会话跳转仍需通过既有离开检查，取消离开保留设置草稿和原项目
+
+### US-E2 键盘、窄窗口与实时结束
+
+- Given 菜单已打开
+- Then 上下方向键与 Home、End 选择当前层，右方向键或 Enter 进入会话层，左方向键或
+  Escape 返回；再次 Escape 关闭活动菜单并恢复摘要焦点，窄侧栏保持打开
+- Given 窗口小于 `620px`
+- Then 点击项目后仅显示会话层，可通过返回按钮回到项目列表；长列表可滚动到最后一项
+- Given 鼠标从项目行移向相接的会话面板
+- Then 子菜单保持打开，点击会话正常导航
+- Given 当前项目的活动全部结束
+- Then 返回项目层并恢复可用焦点；全局无活动时整行隐藏摘要并关闭菜单，新活动到来时只恢复摘要
+- When 点击外部、焦点离开、按 Tab 或隐藏侧栏
+- Then 菜单关闭，后台新活动不自动重新展开
+
+## 7. 后续需求场景
+
+本节对应新增计划，不计入应用中心首期完成条件。
+
+### US-F1 连接组织应用市场
+
+对应 [FR-15](./prd.md#fr-15-私有化市场与-yaml-交换后续)。
+
+- Given 组织已部署提供应用市场的 ShareServer
+- When 用户配置市场 URL，并在来源要求时完成登录
+- Then 可以浏览该来源的应用目录、详情及可获取版本
+- Given 市场暂时不可达
+- Then 显示失败原因与重试入口，已安装和内置应用仍可打开，不切换公共市场
+
+### US-F2 导入导出应用定义
+
+对应 FR-15。
+
+- Given 用户需要在私有部署间迁移应用
+- When 导出应用为 `.yml` 并在另一台设备导入
+- Then 预览应用身份、版本、可迁移配置和依赖，凭据与业务数据不包含在导出文件中
+- Given 同标识应用已存在
+- Then 用户可选择更新或取消，取消后原应用与配置保持不变
+- Given 文件格式无效、版本不支持或离线环境缺失程序包或模型资源
+- Then 显示具体问题与补充要求，不将应用误报为可运行，也不自动启动模型或任务
+
+### US-F3 管理本机模型服务
+
+对应 [FR-16](./prd.md#fr-16-本机模型管理入口新增计划项)。
+
+- Given 用户使用依赖本机模型的应用
+- When 从应用中心或常驻菜单打开“本机模型”
+- Then 可查看已接入模型的状态、管理方式及使用方，两处入口访问同一页面
+- Given 多个应用共用一个 GoodBuddy 受管模型服务
+- Then 展示同一服务及使用方，启动操作不重复创建进程
+- When 用户停止或重启仍有任务使用的受管服务
+- Then 先展示任务影响供用户决定，取消后服务保持运行；操作失败显示原因与实际状态
+- Given 模型服务由外部程序启动，且未接入其管理接口
+- Then 展示“外部管理”与连接配置，不提供停止或重启
+- When 用户关闭管理页或取消常驻
+- Then 模型运行状态不变
@@ -0,0 +1,25 @@
+# 助手工作栏
+
+助手工作栏统一承载本机与远程执行空间、Task、成果、文件、浏览器和终端等持续工作界面。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [通用助手工作栏与执行空间 PRD](./prd.md) | 工作栏整体产品范围、执行空间和各工作面板归属 |
+| [多终端页签 PRD](./terminal-tabs-prd.md) | 工作栏应用的固定、可关闭、单实例和多实例策略，以及多终端生命周期 |
+| [浏览器多实例技术设计](./browser-tabs-technical-design.md) | 浏览器 Tab 身份、Conversation 绑定、IPC、BrowserService 和 MCP 路由 |
+| [实现与验证进度](./progress.md) | 工作区与 Runtime 相关改动的实现事实、验证证据与剩余阻塞 |
+| [执行记录存储与升级回收](./execution-history-storage.md) | 子任务过程差量存储、远程去重、旧库转换、空间回收及升级界面 |
+| [Runtime 交互边界](./runtime-interactions.md) | 原生权限、结构化问答、后台拒绝、终端交互、并行与输出、消息请求状态及资源生命周期规则 |
+| [Runtime 进程复用技术设计](./runtime-process-reuse-technical-design.md) | 跨 Runtime 资源调研、锁定协议证据、进程与会话拆分、远端模型桥、实施顺序和性能验收 |
+| [Runtime 执行清单技术设计](./runtime-checklist-technical-design.md) | OC/CN 原生清单提取、远程 Agent 传递复用、消息恢复与真实部署验收；尚未实现 |
+
+当前尚未拆出独立 User Stories、功能逻辑和 UI 设计文档；产品场景与验收保留在现有 PRD，
+Runtime 资源状态规则由交互边界文档维护。浏览器多实例和 Runtime 进程复用涉及不同的
+跨进程身份与工具路由，分别使用技术设计文档维护。
+
+执行清单的需求、场景和顶部布局见 [PRD](./prd.md#131-runtime-执行清单)，状态规则见
+[Runtime 交互边界](./runtime-interactions.md#runtime-执行清单)。本目录拥有该功能；
+[Task 与 Job](../task-and-job/README.md)拥有产品任务领域，
+[远程主机](../remote-host/technical-design.md#执行清单接入范围)拥有远程部署与连接边界。
@@ -0,0 +1,216 @@
+# 浏览器多实例技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 基础多实例已实施，Agent 多 Tab 工具待需求 |
+| 版本 | 1.0 |
+| 日期 | 2026-09-13 |
+| 关联 PRD | [通用助手工作栏与执行空间 PRD](./prd.md) |
+| 页签策略 | [助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) |
+
+## 1. 目标与边界
+
+浏览器改为可关闭的多实例工作栏应用。每个工作栏浏览器实例对应一个独立 Browser Tab，拥有
+独立页面、导航状态、操作队列、画面状态和元素引用空间。同一 Conversation 下的多个 Tab
+共享隔离存储与代理上下文，使登录状态符合常规浏览器预期。
+
+本设计不把多个工作栏 Tab 实现为同一页面的重复入口，不允许用户切换 Tab 后改变正在执行的
+Agent 工具目标，也不在首期要求模型主动管理多个 Tab。
+
+## 2. 改造前限制
+
+改造前的链路以 `conversationId` 作为唯一浏览器身份：
+
+- Renderer 只保存每个 Conversation 的一份 `BrowserLiveState`。
+- Browser IPC、Preload API 和 `BrowserService` 操作只携带 `conversationId`。
+- Main 每个 Conversation 只创建一个 Session、一个 `WebContentsView` 和一个 CDP Driver。
+- 请求级 MCP 能力只保存 `browserConversationId`。
+- snapshot 元素 `ref` 只在一个 Driver 的引用空间内有效。
+
+因此只把工作栏注册策略改成 `multiple` 会导致多个 Tab 控制同一页面，并产生 viewport、清理和
+元素引用竞态，不能作为可交付实现。
+
+## 3. 身份与所有权
+
+```ts
+type BrowserTabId = string
+
+type ConversationBrowserContext = {
+  conversationId: string
+  partitionId: string
+  tabs: Map<BrowserTabId, BrowserTab>
+  primaryTabId?: BrowserTabId
+}
+
+type BrowserTab = {
+  id: BrowserTabId
+  conversationId: string
+  view: WebContentsView
+  driver: CdpBrowserDriver
+  state: BrowserLiveState
+}
+```
+
+- Conversation Browser Context 拥有隔离 partition、代理配置和全部 Tab。
+- Browser Tab 拥有页面、Driver、串行操作队列、snapshot 代次、idle 状态和可见 viewport。
+- `BrowserTabId` 是 Main 签发的不透明 ID。Renderer 和 Runtime 不能自行选择或复用。
+- 工作栏实例保存公开的逻辑实例 ID 和 Conversation 绑定；进程重启后不恢复旧
+  `WebContentsView`，首次使用时由 Main 为该逻辑实例创建新的 Browser Tab。
+- 删除 Conversation 时关闭该 Context 下全部 Tab；关闭一个工作栏浏览器实例只关闭对应
+  Browser Tab，不得调用 Conversation 级 Runtime 释放路径。
+
+## 4. Renderer 与 viewport
+
+Renderer 状态改为：
+
+```ts
+Record<ConversationId, Record<BrowserTabId, BrowserLiveState>>
+```
+
+每个浏览器工作栏实例持有自己的 `browserTabId`。只有当前可见实例可以提交 viewport。每次
+获得可见权时生成新的 UUID `leaseToken`；提交请求携带 `browserTabId` 和 token，清理请求必须
+回传同一个 token。Main 只接受当前 token 的清理，避免已隐藏实例的延迟 cleanup 隐藏新实例，
+也避免 Renderer 重载后从零开始的数字序列无法覆盖旧租约。
+
+非活动 Browser Tab 保持页面和状态，但隐藏 `WebContentsView` 并停止非必要画面采集。工作栏
+收起、切换主页面和窗口隐藏时采用相同规则，不销毁 Tab。
+普通导航、快照与页面操作只同步轻量导航状态，不自动截图、等待画面或传输 JPEG；只有显式
+`browser_screenshot` 调用生成图片。
+
+`BrowserViewport` 统一观察 body Portal 的插入、移除和可见属性变化，以及浮层尺寸、
+窗口尺寸、滚动和过渡结束。`browser-viewport-occlusion.ts` 按共享语义识别
+`aria-modal="true"`、dialog、alertdialog、menu 和应用通知：可见应用级 Modal 始终释放
+viewport，其余浮层只在与浏览器区域相交时释放。隐藏节点和隐藏祖先不阻塞浏览器。
+最后一个遮挡消失后，只有当前活动实例恢复同一 viewport 租约；网页、历史和页面状态不变。
+终端关闭确认复用此机制，不再维护单独的隐藏条件。页面无需逐个登记弹窗，也不能靠提高
+CSS `z-index` 覆盖原生子视图。此逻辑仅涉及 Desktop Renderer 的显示租约，不改变
+Runtime、MCP 或远端 Agent 的请求、导航与生命周期。
+
+浏览器应用声明 `visibleAcrossContextSwitches: true`，打开的 Tab 跨项目、会话切换继续显示。
+切换活动 Conversation 不改变当前选中的浏览器或其 `targetRef.conversationId`；用户在会话 B
+查看会话 A 的浏览器时，viewport 和手动导航仍指向 A 的原 Tab。新建实例绑定 B。仅未绑定的
+默认或恢复实例可在首次使用时取得当前会话绑定。
+
+Tab 的跨会话可见性与 MCP 授权分开处理。B 的请求不能选择属于 A 的可见 Tab；A 已取得的
+capability 在用户切到 B 后仍固定路由至 A 的原 Tab；使用租约不阻止用户关闭该 Tab。
+内部点击实例只同步应用类型，不再次按当前 Conversation 改选实例。Main 状态携带对应的
+`workbarInstanceId`，Renderer 据此绑定请求创建的同一 Tab，而不是另建空白页。收到 `stopped`
+后清除该实例的旧 Tab 绑定，下一次使用通过原逻辑实例重新创建，保留地址草稿。
+刷新可用性读取 Main 的已提交 URL，不使用地址草稿或仅凭 `sessionActive` 判断。
+侧栏操作错误以当前工作栏实例和面板展开状态为作用域；切换或关闭时清空，旧作用域的
+异步回调不再写入错误，即使用户随后返回同一实例。
+请求创建的实例也遵守现有 32 个工作栏页签上限；满额时保留 Main 页面及其状态，并就地提示
+关闭一个可关闭页签。释放位置后再绑定该页面，不写入超限布局或丢弃 Agent 页面。
+
+## 5. IPC 与服务接口
+
+共享契约增加有界操作：
+
+```ts
+browser.createTab({ conversationId, workbarInstanceId })
+browser.listTabs({ conversationId })
+browser.closeTab({ conversationId, tabId })
+browser.setViewport({ conversationId, tabId, leaseToken, bounds })
+browser.navigate({ conversationId, tabId, url })
+browser.back({ conversationId, tabId })
+browser.reload({ conversationId, tabId })
+browser.stopLoading({ conversationId, tabId })
+```
+
+Main 必须验证 `tabId` 属于同一 `conversationId` 和当前窗口。BrowserService 将现有
+Conversation 级 slot 拆为 Context 与 Tab 两层；同一 Tab 内操作继续串行，不同 Tab 可以并行，
+但仍受窗口级和 Conversation 级有界数量限制。
+
+现有 Conversation 级 `stop/release` 保留为销毁完整浏览器上下文的操作，不能用作关闭单个
+Browser Tab。
+
+## 6. Agent 与 MCP 路由
+
+### 6.1 兼容阶段
+
+第一阶段不修改模型可见的现有浏览器工具参数。模型请求开始时，Main 按以下顺序选择并冻结
+`boundBrowserTabId`：
+
+1. 当前可见且绑定该 Conversation 的 Browser Tab。
+2. 该 Conversation 的 `primaryTabId`。
+3. 预留 primary Browser Tab 身份，首次实际浏览器操作时才创建页面与 Conversation Context。
+
+未使用浏览器的请求只持有随请求释放的内存预留，不创建 Chromium 资源、不触发浏览器 UI、
+也不占用活动浏览器会话名额。物化后使用同一 Tab 身份和工作栏实例归属；取消、能力撤销及
+服务关闭释放未使用的预留，不保存到磁盘。编程 Subagent 继承父请求的 Browser Tab 与浏览器
+Conversation 归属，不新建租约或把页面重新归属到子级对话。
+
+直连模型上下文和请求级 MCP capability 同时保存 `conversationId` 与
+`boundBrowserTabId`。请求执行期间，用户切换、创建或关闭其他工作栏 Tab 不改变工具目标；
+用户可直接关闭模型正在使用的 Tab。关闭释放该 Tab 的页面和使用租约，中止其浏览器操作，
+不取消整个模型请求、不撤销 MCP capability，也不关闭同级 Tab。系统不得把进行中的操作改投其他 Tab。
+
+关闭后，快照等非导航工具返回“浏览器标签页已关闭，请调用 browser_navigate 打开新标签页”，
+不自动创建页面或使用现有 primary/sibling。只有显式且参数有效的 `browser_navigate` 才创建
+专用替代 Tab 并绑定后续工具；旧 Tab 身份与元素引用不复用。Gateway 与直连 Provider 均隔离
+单次工具取消信号、Tab 使用租约信号和请求信号，取消一次工具调用不终止后续调用。
+
+该阶段 MCP transport、endpoint 和 token 生命周期不变，只扩展服务端 capability 内容和内部
+路由。工具调用使用当前请求绑定的 Tab，只有上述显式导航恢复会更换绑定。
+
+### 6.2 Agent 多 Tab 阶段
+
+只有明确需要 Agent 管理多个页面时，才增加：
+
+- `browser_tab_list`
+- `browser_tab_open`
+- `browser_tab_close`
+
+导航、snapshot、back 和 screenshot 增加可选 `tabId`；省略时使用请求绑定的默认 Tab。
+`browser_snapshot` 返回 `tabId` 和 snapshot 代次。click、type 和 select 必须校验 capability、
+`tabId`、引用代次和元素 `ref` 属于同一 Driver，禁止跨 Tab 猜测或解析引用。
+
+## 7. 工作栏创建与快捷入口
+
+- 从“+”选择浏览器时始终创建新工作栏实例，并默认绑定当前 Conversation。
+- 没有活动 Conversation 时创建待绑定实例，不创建无归属 Main Browser Context。
+- 主侧栏浏览器快捷按钮优先激活绑定当前 Conversation 的最近使用实例；没有匹配实例时创建
+  一个。没有活动 Conversation 时激活最近使用的浏览器实例；完全不存在时创建待绑定实例。
+- New browser instances use a numbered browser label followed by the active Conversation title, when
+  available. The number avoids existing titles; restoring the layout preserves each saved title.
+  The address bar shows only that instance's page URL. Binding a numbered instance does not overwrite
+  its title; the default unbound browser receives the Conversation label when first bound.
+- 关闭工作栏 Browser Tab 只释放对应 Browser Tab。关闭浏览器上下文是独立危险操作，需要
+  明确说明会影响该 Conversation 下的全部 Tab 和 Agent 浏览器状态。
+
+## 8. 持久化与恢复
+
+`createTab` reuses a live tab only for the same Conversation and workbar instance ID. A new workbar
+instance can adopt the primary tab only when its request creates the Conversation context. An existing
+primary, including one opened by an Agent, is not adopted by a new instance. New sibling tabs start at
+`about:blank` with no navigation history and share the Conversation's cookie partition.
+
+持久化工作栏实例 ID、顺序、自定义标题和公开 Conversation 绑定，不持久化页面进程、CDP
+引用、snapshot、viewport lease、Cookie、Token 或 Main `BrowserTabId`。应用重启后实例显示
+未启动状态，展开浏览器面板或 Agent 首次使用时按原绑定创建新 Tab。
+
+绑定的 Conversation 已删除或不可见时保留实例并显示目标失效，不自动绑定当前 Conversation。
+
+## 9. 限制与验收
+
+- 分别限制每个 Conversation 的 Tab 数和每个窗口的总活动 Tab 数；达到上限时在创建前反馈。
+- 两个 Tab 的地址、历史、加载状态、截图和元素引用互不覆盖。
+- 同一 Conversation 的 Tab 共享登录状态，不同 Conversation 保持隔离。
+- 延迟 viewport cleanup 不能隐藏另一个已激活 Tab。
+- 一个 Tab 的元素 `ref` 不能在另一个 Tab 中执行。
+- 用户切换工作栏 Tab 不改变进行中模型请求的 MCP 浏览器目标。
+- 关闭一个 Tab 不释放 Conversation Runtime，也不关闭同一 Conversation 的其他 Tab。
+- 关闭已租用 Tab 后，同一 MCP 会话仍可列出工具；旧目标快照报错且不创建页面，显式导航创建
+  不同身份的替代 Tab，同级页面、导航状态与其他 Conversation 的可见 viewport 保持不变。
+- 旧版无 `tabId` 的模型工具调用仍操作请求绑定的默认 Tab。
+
+## 10. 实施顺序
+
+1. 引入 Browser Context 与 Browser Tab 两层身份，拆分 partition 和页面生命周期。
+2. 扩展 Shared、Preload、IPC 与 BrowserService 的 `tabId` 和 viewport `leaseToken`。
+3. 改造 Renderer 状态与工作栏实例，开放浏览器 `multiple` 策略和单 Tab 关闭。
+4. 将直连模型与 MCP capability 绑定到请求开始时确定的 Browser Tab。
+5. 完成跨 Tab 引用隔离、并行队列、共享 Cookie、关闭和恢复测试。
+6. 有明确 Agent 多页面需求后再开放模型可见的 Tab 管理工具。
@@ -0,0 +1,64 @@
+# 执行记录存储与升级回收
+
+通用迁移、备份、性能测量和发布要求见
+[数据库迁移与大数据升级指南](../../development/database-migrations.md)。
+
+## 用户行为
+
+子任务仍实时显示完整的文字、思考、工具过程和最终结果。运行时间较长、工具输出较多时，
+数据库不再为每个流式更新重复保存此前的整份过程；本机和托管 SSH OpenCode 使用相同
+的桌面存储机制。此修复不关闭子任务、不截短已有过程，也不增加 Execute 权限门槛。
+
+已有数据库在首次升级时自动处理。启动页铺满窗口，显示处理数量、全宽进度条和近期
+处理速度；处理时间取决于历史数据量与磁盘速度，不承诺固定几分钟。用户可以退出，
+下次启动重新检查并继续转换未完成的数据；完成后回收空闲页并进入应用。失败时留在
+该页提供重试与退出，磁盘空间不足会明确说明，不删除聊天来腾出空间。
+
+## 存储规则
+
+- `messages.metadata_json` 继续保存供会话显示的完整子任务过程。
+- `task_events` 的 `subagent` 内容由共享 `SubagentProgressStorage` 编码。
+  `progressUpdates` 只保存文字追加、变更的块，或确有删除／重排时的完整重置。
+  完全相同的过程使用空更新数组。工具字段按值比较，缺省字段与 `undefined` 等价，
+  不因 JSON 省略空字段而重复写入整个工具结果；空字符串与实际输出／错误变化仍保留。
+  其他事件内容不改变。
+- 每个任务内按事件 ID 顺序、按 `childTaskId` 独立还原过程。事件 ID、顺序、状态、
+  最终输出、错误、时间及远程来源字段均保留，不按天数裁剪或删除旧事件。
+- Runtime、Agent transcript、Preload 和 Renderer 的公共 `SubagentEvent` 仍传完整
+  `progress`；差量表示只存在于桌面数据库内部，不要求更新远端 Agent 协议。
+- 远程消息投影与事件插入仍共用 SQLite 事务。重放时还原已保存内容进行等值校验，
+  相同来源重复事件不重复投影，不同内容继续报冲突。内存过程缓存通过已提交事件 ID
+  核对；事务回滚或重新打开后从数据库重建，不保存独立快照或回收日志。
+- 存储层最多缓存 16 个任务；收到任务完成、错误、取消或中断的终态记录后立即移除该任务
+  的缓存引用，不影响其他会话。若事务随后回滚或仍收到该任务的后续事件，按已提交记录重建。
+  释放引用不等于进程 RSS 立即下降，垃圾回收和 Runtime 自身会话缓存另按生命周期回收。
+
+## 旧库升级
+
+桌面在打开业务数据库之前启动独立 Node 工作线程，使用同一套编码和还原函数转换旧库。
+按任务有序读取，每批最多 32 条，提交后报告进度；SQLite 保留事务原子性及正常 WAL
+自动 checkpoint，每个任务结束时截断 WAL。读取缓存为 64 MiB，避免 1 MiB 级历史
+快照在过小缓存中反复读取；不以关闭事务或同步落盘换取速度。
+
+转换可以混合读取旧完整记录与已经转换的记录，也会重新编码 schema 34 中重复的工具块
+更新。因此退出、磁盘写入失败后可以重新扫描并继续；已是相同 JSON 的记录不重复更新，
+不建立额外的恢复状态表。最后运行 SQLite `VACUUM` 回收已释放的空间，而非
+在转换前复制整份膨胀内容。回收仍需要额外可用磁盘空间，失败保留已提交转换并允许重试。
+
+当前源码的业务初始化随后将数据库升级为 schema 35；schema 34 用户也会执行本次整理，
+成功后后续启动直接跳过。继续复用 schema 34 的子任务事件部分索引和同一差量表示。
+低于该 schema 的旧版客户端不能重新打开已经升级的数据库。需要回退客户端时，必须使用
+升级前备份，不要修改 `user_version` 强行绕过版本检查。
+
+## 验证要求
+
+- 使用可还原的合成过程验证文字追加、内容修订、块重排、清空和多次打开。
+- 工具 fixture 必须含生产对象会携带的 `undefined` 可选字段，并经过实际 JSON 写入／重读。
+  同时验证旧完整事件和 schema 34 差量事件的整理、混合重试及无变化记录不被重写。
+- 验证远程重复事件、冲突事件，以及消息更新失败时事件和过程缓存的事务回滚。
+- 在真实旧库的已核验备份副本上运行 portable 的正常启动入口，核对事件逐条等价、
+  其他用户表内容、数据库完整性和实际文件大小，不能只统计空闲页或只测试内存 fixture。
+- 同时验证真实本地 Runtime 和共享 Linux Host 的桌面持久化路径。真实场景必须让主代理
+  与子代理按正常任务需要读取、修改文件和执行测试，不能用“子代理不使用工具”的纯文字
+  场景代替工具存储验收；记录实际请求数、有效变化、重复工具块及还原结果。具体证据见
+  [实现与验证进度](./progress.md)。
@@ -5,11 +5,11 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | 设计中 |
-| 版本 | 0.5 |
-| 日期 | 2026-08-21 |
+| 版本 | 0.6 |
+| 日期 | 2026-08-31 |
 | 适用产品 | GoodBuddy 桌面端 |
-| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../../architecture/remote-host-and-goodbuddy-agent-design.md) |
-| 相关能力 | [会话监督](../supervision/conversation-supervision-prd.md)、[自动化平台](../../architecture/automation-platform-architecture.md)、[长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) |
+| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md)、[SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md) |
+| 相关能力 | [会话监督](../conversation-supervision/prd.md)、[自动化平台](../../architecture/automation-platform-architecture.md)、[长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) |

 ## 1. 背景

@@ -36,8 +36,8 @@ Runtime 统一抽象为“执行空间”。
 ### 2.1 助手工作栏

 助手工作栏是 GoodBuddy 中始终可访问的应用级工具容器。它提供稳定能力目录，用户从中
-查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器和成果
-面板实例。稳定的是能力的可发现性，不是八个同时占据界面的固定面板。
+查看任务中心，并按需打开一个或多个监督、Runtime、终端、进程、工作区、浏览器、资源监控、
+成果和文档面板实例。稳定的是能力的可发现性，不是十个同时占据界面的固定面板。

 工作栏不是：

@@ -83,30 +83,36 @@ Runtime
 进程
 工作区
 浏览器
+资源监控
 成果
+文档
 ```

 - 应用不得根据当前项目、会话、Runtime、主机或探测结果无提示地增删能力目录项。
- 用户主动打开、关闭、排序和停靠面板实例；应用不默认同时挂载全部能力。
- Task Center 是 Task 的单例应用级索引。每个 Task 只关联一条 Conversation，一条
-  Conversation 可以关联多个 Task；Task Center 不复制会话内容，也不显示普通 Conversation、
-  Job、Run 或心跳事项。
+- 用户主动打开、关闭、排序和停靠可关闭的面板实例；任务中心和工作区作为基础工作入口默认
+  存在且不可关闭，分别固定在第一、第二位，排序属性为不可重排。
+- Task Center 是默认跟随当前项目的单实例 Task 索引。每个 Task 只关联一条 Conversation，
+  一条 Conversation 可以关联多个 Task；Task Center 不复制会话内容，也不显示普通
+  Conversation、Job、Run 或心跳事项。
 - 当前能力、连接、数据和空状态可以动态变化。
 - 能力不可用时，目录项或已打开面板显示原因、影响和可执行的配置或切换入口，不能只通过隐藏表示。
 - 用户可以在设置中调整目录顺序；恢复默认布局恢复标准目录与默认打开面板，不强制打开全部能力。
- 同一能力需要并排比较不同目标时可以创建多个实例，每个实例拥有独立身份和范围绑定。
+- 浏览器、终端及其他声明为多实例的能力可以创建多个实例，每个实例拥有独立身份和范围绑定。

 ### 3.2 当前上下文只提供默认值

-任务中心作为全局索引不跟随当前会话，也不支持为同一列表打开多个目标实例。其他可绑定
+任务中心只有一个工作栏实例，默认跟随当前项目，不跟随当前 Conversation。用户可以在同一
+实例内显式切换到全局任务或全部项目，但不能为不同项目打开多个任务中心 Tab。其他可绑定
 目标的能力使用当前会话、项目、Runtime 和主机帮助新面板实例初始定位，但这些上下文不是
 使用门槛：

 - 监督默认选择当前会话，用户可以改选其他 Conversation、Task 或实验对象。
 - Runtime 默认跟随当前会话或 Task；执行事件可以查看，但 Job/Run 不作为独立选择对象。
- 终端默认使用当前项目执行空间，用户可以新建本机或远程终端。
+- 终端创建时固定到当前项目执行空间，由项目配置自动决定本机或托管 SSH；没有当前项目时
+  使用本机 Home。
 - 工作区默认显示当前项目目录，用户可以打开其他本机目录或远程目录。
 - 成果默认使用当前范围，用户可以切换到项目、全局或其他允许范围。
+- 文档创建时固定到用户明确打开的文件和 ShareServer 编辑会话，不提供跟随模式。
 - 下一次请求的附件和知识库由当前 Composer 展示与管理，不作为工作栏能力。历史执行上下文
  随关联 Task 查看；记忆功能实现后也归入任务中心，而不是新增独立上下文面板。

@@ -132,10 +138,10 @@ Runtime
 稳定能力目录和已打开面板必须准确呈现能力差异：

 - 当前 Runtime 不支持后台 Job 时，Runtime 能力仍可发现；打开后说明当前可监督的内容。
- 当前执行空间没有 Git 仓库时，工作区文件功能仍可使用，Git 区域显示不可用原因。
+- 当前执行空间没有 Git 仓库时，工作区文件功能仍可使用，仅确认是 Git 仓库后显示 Git 工作区入口。
 - 没有活动进程时，进程面板提供创建终端或启动 Runtime 的入口。
- 没有项目时，终端和工作区允许用户选择本机目录或远程主机，但必须先取得有界临时
-  Execution Space Grant，不能把可选路径直接传给文件、Git、Process 或 Runtime。
+- 没有项目时，终端使用当前用户本机 Home；工作区等允许选择路径的能力仍必须先取得有界
+  临时 Execution Space Grant，不能把可选路径直接传给文件、Git、Process 或 Runtime。
 - 监督未启用时，监督面板提供目标、模式和“开始监督”，而不是隐藏能力。

 不得渲染成排没有解释的禁用按钮，也不得把“进程连通”描述为已经支持完整原生监督。
@@ -167,7 +173,7 @@ Runtime
 - 建立统一范围、执行空间、生命周期、成果和控制契约。
 - 复用现有 Project、Conversation、Task、Artifact、Activity 和 Approval 数据。
 - 保持 Renderer 无任意文件、进程、PTY、SSH 或 Electron API 能力。
- 保持 Ask 只读、Execute 审批、取消、超时、输出边界和活动审计。
+- 保持 Ask 只读、Execute 账号完整授权、取消、超时、输出边界和活动审计。
 - 为本机与远程能力提供一致 UI，同时准确表达能力差异。

 ## 5. 非目标
@@ -201,22 +207,32 @@ Runtime

 ### 6.2 能力目录与面板实例

-能力目录不等于同时打开八个面板。推荐使用工作栏内的纵向能力导航，并在旁边或停靠区域管理
-用户已经打开的面板实例：
+能力目录不等于同时打开十个面板。当前产品采用“已打开实例 Tab + 持久新增按钮”的工作栏
+模型：Tab 行只显示已打开实例，行末“+”始终可见；点击后在工作栏内容区打开稳定能力目录，
+用户再创建或激活应用实例。详细交互以
+[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。

 - 每项始终显示稳定图标，并提供可见标签或可持续查看的工具提示。
- 目录使用与其交互模型匹配的列表、工具栏或菜单语义；单实例切换使用 `tablist`、`tab`、
-  `tabpanel`，多实例停靠区使用有名称的区域和明确面板标题。
- 支持方向键、Home、End、Enter、Space、关闭面板和正确焦点恢复。
+- 已打开实例使用 `tablist`、`tab`、`tabpanel`；“+”是位于 `tablist` 外的普通命令按钮。
+- 应用注册表分别声明实例策略、默认打开、必须存在、是否可关闭和是否允许排序。`single` 或
+  `multiple` 只控制实例数量；`required` 控制布局修复，不能兼作关闭或排序策略。
+- 在工作栏“+”目录中重复选择单实例应用时聚焦已有实例；选择浏览器、终端等多实例应用时
+  每次创建新实例。主侧栏系统工具快捷入口按当前上下文聚焦匹配实例，不能因连续点击无意
+  创建重复实例。
+- 支持方向键、Home、End、Enter、Space、可关闭面板的关闭命令和正确焦点恢复。不可关闭
+  实例不渲染关闭按钮，也不响应关闭快捷命令。
 - 徽标显示未解决数量、等待审批或失败状态，并同时提供文字或可访问名称。
- 用户调整目录顺序、打开实例、停靠位置和尺寸后持久化；关闭实例后能力仍可从目录重新打开。
+- 用户调整目录顺序、打开实例、停靠位置和尺寸后持久化；关闭可关闭实例后能力仍可从目录
+  重新打开。布局加载和恢复默认布局必须补回缺失的任务中心与工作区实例。
 - 默认布局只恢复经过产品确认的少量常用面板，不自动打开全部标准能力。
 - 每个实例显示稳定实例 ID、能力名称、跟随或固定状态与当前目标；同能力多实例不能只靠位置区分。

-当前聊天右栏过渡实现保留 Task Center、工作区、浏览器和成果四个横向页签时，必须
-单行横向滚动，不能自动隐藏或缩写到不可辨认。Task Center 继续作为 Task 的现有入口；
-审批定位到所属 Task 或 Runtime。智能心跳不作为工作栏页签，其报告、建议、历史和完整配置统一归属
-“智能心跳”菜单入口。当前阶段不新增独立自动化中心。
+从当前聊天右栏迁移时，Task Center 和工作区作为默认打开、单实例且不可关闭的基础应用保留；
+浏览器保留一个默认打开实例，但注册为可关闭的多实例应用；成果保持默认打开、单实例且可
+关闭；终端不默认打开，由用户通过“+”创建，并从首期开始支持多实例。Tab 必须单行横向滚动，
+不能自动隐藏或缩写到不可辨认，“+”不能随滚动消失。Task Center 继续作为 Task 的现有
+入口；审批定位到所属 Task 或 Runtime。智能心跳不作为工作栏页签，其报告、建议、历史和
+完整配置统一归属“智能心跳”菜单入口。当前阶段不新增独立自动化中心。

 ### 6.3 工作栏尺寸

@@ -229,7 +245,7 @@ Runtime
  项目切换器和导航整体向下推移。
 - 对话内容与输入区始终保留对称的左右安全边距，工作栏边界不得覆盖或裁切输入框、发送
  按钮及主工作区右侧边距。
- 唯一展开与收起开关固定在窗口关闭按钮正下方。工作栏内部不重复关闭入口。开关图标中的
+- 唯一展开与收起开关固定在顶栏操作区、紧邻浅色/深色主题按钮之前。工作栏内部不重复关闭入口。开关图标中的
  箭头方向随当前动作切换，按钮不以持续高亮表达展开状态；当前会话没有 Task 时不渲染空
  Task 上下文栏。
 - “新建任务”入口位于工作栏“任务索引”标题后方，不在会话 Task 上下文栏重复出现；索引
@@ -251,8 +267,13 @@ Task Center 保留为工作栏中的稳定入口，并在现有基础上适度
  活动记录和成果查看器中，不在窄栏复制，也不呈现 Job/Run 树。
 - 智能心跳的报告、建议、历史和配置不进入任务中心。

-任务中心是单例索引，不使用其他能力的“跟随 / 固定目标”多实例模型。后台状态可以更新
-徽标和排序，但不能自动打开面板或抢占用户当前工作。
+任务中心是应用级单例，默认存在且不可关闭。它的数据范围默认跟随当前项目，并在标题或范围
+控件中明确显示项目；用户可以切换到“全局任务”或“全部项目”，该选择只改变同一实例的列表
+范围，不创建第二个任务中心 Tab。切换回“跟随当前项目”后，项目变化立即刷新列表。后台状态
+可以更新徽标和排序，但不能抢占用户当前工作。
+
+当前实现已按活动项目过滤 Scheduled Task 和审批，并提供“当前项目”“全局任务”“全部项目”
+范围控件。

 主侧栏最近会话为关联 Task 提供轻量入口：父会话行只显示行首展开按钮，Task 子项使用
 任务图标和本地化摘要，展开层级只到 Task；点击 Task 子项打开同一 Conversation 并定位。
@@ -265,7 +286,7 @@ Conversation，默认 Execute，并持续显示 Runtime、Project、工作目录
 ### 7.2 监督

 监督是通用观察与评论入口，详细行为以
-[会话监督 PRD](../supervision/conversation-supervision-prd.md) 为准。
+[会话监督 PRD](../conversation-supervision/prd.md) 为准。

 监督能力在目录中稳定可发现；用户打开面板实例后可以选择：

@@ -311,10 +332,12 @@ Runtime 能力统一监督直连模型、OpenCode、Continue、DeepSeek Harness

 ### 7.4 终端

-终端面板允许用户主动创建和管理本机或 SSH 终端：
+终端面板允许用户通过工作栏“+”主动创建和管理多个本机或 SSH 终端。详细产品行为、首期
+直接 SSH PTY 技术选择、生命周期和验收以
+[助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 为准。

 - 新建、重命名、切换、关闭和重新连接终端。
- 选择执行空间、工作目录和 Shell。
+- 创建时自动绑定当前项目执行空间、权威工作目录和平台默认 Shell，不显示重复目标选择。
 - 显示本机或远程主机、目录、Shell 和连接状态。
 - 支持复制、粘贴、搜索、清屏、滚动和调整终端尺寸。
 - 支持将终端切换到右侧、底部或独立窗口。
@@ -345,6 +368,10 @@ Renderer 不接收任意系统 PID 控制能力。控制动作引用 Main 签发

 ### 7.6 工作区

+工作区是默认存在、单实例且不可关闭的基础应用。它默认跟随当前项目；项目或目录不可用时
+保留同一 Tab 并显示修复入口，不能通过关闭 Tab 隐藏范围错误。任务中心固定在第一位，工作区
+固定在第二位，恢复布局时保持此顺序。
+
 工作区面板允许用户选择：

 - 当前项目目录。
@@ -353,30 +380,156 @@ Renderer 不接收任意系统 PID 控制能力。控制动作引用 Main 签发

 面板提供：

- 有界目录树和文本文件预览。
+- 有界目录树和分页文本文件预览；文件超过单页传输大小时先显示已读取内容，并允许用户继续加载后续内容，不因文件总大小超过单页上限而拒绝预览。
 - 当前选择、规范化路径和执行空间。
 - 可选 Git 状态、Diff 和仓库信息。
 - 显式打开、下载副本或在终端中打开。
 - HTML 文件的源码与安全预览。

+当前项目目录的文件浏览与 Git 交互遵循以下规则：
+
+- FR-W1：顶部同一行放置“文件 / Git 工作区”视图切换和右侧刷新；非 Git 目录仍保留刷新。
+  下一行只提供当前视图的工具：文件视图提供新建文件、新建目录，Git 视图提供分支、Fetch 和更改显示方式，
+  不在 Git 视图重复目录导航或新建文件操作。操作使用带名称和提示的紧凑图标按钮。
+  文件视图在根目录不显示孤立的文件夹图标或空路径行；进入子目录后提供“项目目录名 / 子目录”
+  文字路径导航和返回父目录按钮。根目录文字可点击返回，提示显示完整根路径；返回根目录后焦点移至顶部刷新。
+  长目录名单行省略，完整路径通过提示查看；多级路径在导航内部横向滚动，不撑宽工作栏。
+  选中目录时在该目录创建，选中文件时在其父目录创建，未选择时在当前浏览目录创建。
+  无可用目录时隐藏无关操作。
+- 使用共享 `SegmentedControl` 切换“文件”和“Git 工作区”，默认显示文件；
+  选择只在当前面板挂载期间保存在内存中，不持久化。未提交更改包含当前项目的全部
+  Git 更改，不按 AI、用户或其他工具的修改来源筛选。
+- FR-W2：只有已确认的 Git 仓库显示 Git 工作区入口。临时读取或连接错误保留同一项目
+  已确认的 Git 可用性和内容，提供重试；切换项目不能沿用上一项目的确认结果。
+- FR-W3：文件和目录行的更多按钮与左侧会话行一致，在悬停、键盘聚焦或菜单打开时显示。
+  菜单复用会话操作的图标、间距和悬停样式，浮层限制在窗口内，不受文件列表滚动边界裁切；
+  支持方向键、Home、End 和 Escape，Escape 或选定操作后焦点返回触发按钮，删除入口独立分隔。
+  菜单提供重命名、移动、删除、属性、复制路径和本机默认应用打开；删除须明确确认对象
+  与不可恢复性。操作失败保留输入与上下文。本机和远程均支持文件管理，系统默认打开仅本机可用。
+  重命名允许仅修改同一目录项的名称大小写，不得覆盖另一个已存在的文件、目录或硬链接目录项。
+  移动通过与创建项目相同的目录选择流程指定目标：本机打开系统目录选择器，远程浏览当前
+  SSH Host 的目录。选择目录后保留原名，确认后执行；取消不移动文件。目标限于当前工作区，
+  选择外部目录时在弹窗内说明限制，不切换项目或工作区范围。取消按钮使用共享次按钮样式，
+  更多菜单中的删除图标和文字与其他菜单项一样左对齐。
+- FR-W4：Git 分支标签打开可搜索的本地与远程分支选择器，支持创建和切换分支，以及显式
+  Fetch。切换使用普通 Git switch，保留可携带的未提交修改；冲突时显示 Git 错误。
+  不自动 force、reset、discard 或 stash，不因浏览分支而自动 Fetch。
+  分支触发器复用共享模型选择按钮，带分支图标和展开箭头；Fetch 使用共享次按钮，二者在
+  紧凑工作栏内保持同一行，长分支名省略并提供完整名称提示。
+  展开的分支选择面板不超过 360px 或工作栏可用宽度；搜索使用共享表单标签、输入框与主题样式，
+  分支列表独立限高滚动，创建按钮以紧凑次操作放在列表下方。Escape 收起面板并将焦点返回分支触发器。
+- FR-W5：未提交更改支持列表和目录树切换；两种视图均可打开单文件 Diff。
+- FR-W6：Git 工作区底部提供默认收起的提交历史区，独立滚动，可调整高度。
+  历史标题默认停在面板底部，首次展开向上占用当前 Git 内容区的一半高度；收起后标题回到底部。
+  上方变更列表和下方提交历史独立滚动；分隔条支持指针及键盘调整比例，底部位置保持不变。
+  顶部刷新入口同时更新已展开的提交历史，历史区内不重复提供刷新按钮。
+  按当前分支分页读取提交，展示摘要、作者、时间、短 OID 和 refs。选中提交显示该次修改文件，
+  再选文件进入内联提交 Diff；逐层返回保留分支、分页、选择、滚动位置与焦点。
+  提交 Diff 保留重命名前后路径和实际内容修改；后台工作区刷新不得使正在加载的历史或详情
+  永久停留在忙碌状态。
+  历史展开入口使用带方向箭头的紧凑列表行；提交行沿用文件列表的表面、悬停和焦点样式，
+  摘要与元信息左对齐分行展示，长内容省略并提供完整提示，不撑宽侧栏。
+- Git 错误和无更改提示只在 Git 工作区显示，不阻断文件浏览。
+  切换项目时自动检测 Git 状态，无需手动刷新；检测结果和失败时保留的数据仅用于所属项目。
+- 未提交更改以彩色 Git 字母标识状态：M 修改、A 新增、D 删除、R 重命名、C 复制、
+  U 未跟踪或冲突、T 类型变化；冲突用危险色区别于未跟踪文件，同时保留原始状态。
+- 点击更改项进入该文件 Diff，分别显示已暂存和未暂存差异，增删行使用对应状态色；
+  删除文件也可查看。目录树中的文件仍打开内容预览。不再提供底部全仓库 Diff 入口。
+- 文件预览保留在右侧工作区内；预览期间隐藏列表但保持目录树挂载，返回后保留已展开
+  目录、滚动位置和选中行，并恢复触发行焦点。Diff 返回未提交更改列表时同样恢复
+  滚动位置、选中行和焦点。
+- 文件预览提供复制项目相对路径、刷新，以及仅本机项目可用的“使用默认应用打开”。
+  刷新失败保留此前内容并显示错误；Markdown 默认渲染预览，可切换源码。
+- Diff 提供刷新、复制项目相对路径和“查看当前文件”；删除项不显示查看当前文件入口。
+- 手动刷新或任务结束更新 Git 状态时，同步重读根目录、当前浏览目录和已展开目录并去重，保留目录展开状态，
+  刷新失败保留已有目录列表；重新展开目录时重读。目录读取错误在对应目录旁显示，
+  可就地重试。正在查看的单文件 Diff 同时重读，旧请求不得覆盖新结果。
+  无首次提交的仓库也应显示新增和暂存文件。
+- 未提交更改首批显示 50 项，可继续分批加载其余变更，不能使后续文件尤其是已删除
+  文件失去 Diff 入口。
+- 系统默认应用和资源管理器打开按钮仅用于本机项目，SSH 项目不显示这两个按钮。
+
+项目内目录导航属于 FR-W1；项目外目录选择、下载副本、终端打开及 HTML 安全预览仍属于后续能力。
+本轮工作区交互不包含项目文件搜索，也不调整其他工作栏页签。
+
 本机和远程访问都必须由 Main 或远程 GoodBuddy Agent 在对应文件系统上执行路径规范化、相对路径和
 符号链接边界检查。Renderer 只能提交受约束的相对路径和已授权范围 ID。

 ### 7.7 浏览器

+浏览器是可关闭的多实例应用。升级后的默认布局保留一个浏览器实例；用户从“+”目录选择
+浏览器时每次创建新的 Browser Tab。每个实例必须显示可区分的标题和绑定 Conversation，
+不能让多个工作栏 Tab 只是同一页面的重复控制入口。
+
 浏览器能力在目录中稳定可发现，打开面板后允许用户：

- 创建新的 GoodBuddy 隔离浏览器会话。
- 选择当前会话或其他受控浏览器会话。
+- 在当前 Conversation 的隔离浏览器上下文中创建独立 Browser Tab。
+- 选择当前 Conversation 或其他允许访问的 Conversation 作为实例目标。
 - 查看状态、当前 URL、有界画面和错误。
- 进入明确的交互模式或停止会话。
+- 通过顶部浏览器工具栏返回、刷新或停止加载、编辑地址并前往。
+- 进入明确的交互模式或关闭浏览器。

-没有浏览器会话时显示“新建浏览器会话”，而不是隐藏能力。模型或后台浏览器活动可以更新
-徽标，但不得无条件打开面板或切换用户当前面板。
+顶部工具栏按“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”组织。“刷新”在
+页面加载期间原位切换为“停止加载”；“关闭浏览器”是清楚独立于导航的会话生命周期操作，
+必须与“停止加载”在文案和视觉上明确区分。现有“停止浏览器”语义统一改名为“关闭浏览器”。
+
+新建或重新创建的空白标签页尚无已提交 URL 时禁用刷新；只输入地址草稿不会启用刷新。
+首次导航期间仍可停止加载。操作错误仅在当前面板本次打开期间显示，切换面板、关闭当前
+页签或收起工作栏后清除，已离开面板的异步失败不得重新显示旧提示。
+
+同一 Conversation 下的 Browser Tab 共享隔离存储和代理上下文，但每个 Tab 拥有独立页面、
+导航状态、操作队列和元素引用空间。模型请求开始时绑定一个确定的 Browser Tab；用户切换
+工作栏实例不能在请求途中改变 Agent 的工具目标。用户在该实例执行前往、返回或刷新会有意
+改变绑定到同一 Tab 的 Agent 后续操作。所有请求都进入 `BrowserService`；Renderer 不建立
+第二套导航队列、抢占规则或恢复状态机。
+
+用户可关闭 Agent 正在使用的标签页，无需先取消整轮请求。关闭只中止该页的浏览器操作，
+其他标签页和请求的其他工具继续可用。后续快照等操作应提示标签页已关闭；Agent 显式导航
+时打开专用新标签页并继续操作，不能自动接管用户的其他页面。
+
+浏览器工具栏读取的权威状态至少包含：
+
+```ts
+type BrowserToolbarState = {
+  committedUrl: string
+  loading: boolean
+  canGoBack: boolean
+  sessionActivity: 'inactive' | 'creating' | 'ready' | 'agent_action' | 'full_interaction'
+}
+```
+
+`committedUrl` 是浏览器已经提交的权威 URL。地址输入在未编辑时与它同步；获得编辑意图后，
+输入文字保持为 Renderer 本地草稿，画面、加载状态和 URL 更新不得覆盖草稿，直到用户“前往”
+或放弃编辑。用户提交未带 `http://` 或 `https://` 的裸域名时，Renderer 自动补上
+`http://`，再通过既有浏览器 URL 策略提交。地址草稿不属于浏览器会话持久状态，也不需要
+恢复或版本化机制。
+
+创建会话、Agent 操作和完整交互窗口期间，返回、刷新、地址提交、前往、交互和关闭浏览器
+控件禁用，避免与同一会话并发操作。例外是活动导航处于加载中时，“停止加载”保持可用，
+可中断当前页面加载；
+它只取消页面加载，不销毁浏览器会话、不执行“关闭浏览器”，也不释放当前 Runtime 上下文。
+“关闭浏览器”沿用现有停止会话的生命周期语义。
+
+没有浏览器会话时仍显示工具栏。活动 Conversation 可以直接在地址栏输入非空 URL 并“前往”，
+由 `BrowserService` 通过 Agent 浏览器相同的能力检查和 URL 策略创建会话并导航；不得为这一
+空状态增加旁路 WebView 或宽松 URL 入口。没有活动 Conversation 时说明需要先选择或创建会话。
+模型或后台浏览器活动可以更新对应实例的徽标，但不得无条件打开面板或切换用户当前面板。
+
+浏览器多实例的跨进程身份、可见 viewport 所有权、关闭语义和 MCP 兼容方案以
+[浏览器多实例技术设计](./browser-tabs-technical-design.md)为准。

 浏览器面板只管理 GoodBuddy 受控浏览器，不表示可以控制用户已安装的浏览器。

-### 7.8 成果
+### 7.8 资源监控
+
+资源监控是本机单实例面板，显示整机 CPU、内存、磁盘 IO 和 GoodBuddy 桌面进程摘要。面板
+只在自身可见并处于活动状态时采样，数据保留在 Renderer 有界内存中，不进入运行记录或长期
+存储。首期不提供远程主机、GPU、显存、网络吞吐、后台告警或任意进程查看。
+
+指标缺失时保留面板入口并显示不可用原因。资源监控入口、采样频率、数据契约与验收由
+[应用导航与系统工具入口](../application-tool-navigation/README.md)定义。
+
+### 7.9 成果

 成果面板统一显示全局、项目、Conversation、Task 执行和监督显式产生的独立成果：

@@ -404,7 +557,20 @@ Task 呈现来源，不把 Run 作为导航对象。
 - 不使用 `dangerouslySetInnerHTML`，不启用 Electron `webviewTag`。
 - 外部打开是明确的用户操作，并说明外部浏览器可能执行脚本或联网。

-### 7.9 Composer 与任务上下文
+### 7.10 文档
+
+文档是可创建多个实例的工作栏应用。用户从工作区、成果或会话文件引用打开受支持的 Office
+文件时新增文档 Tab；每个实例固定到一个 ShareServer 编辑会话，不随当前 Conversation 或
+Project 切换。Tab 使用文档文件名，同名实例增加序号，完整来源通过 Tooltip 和页签内信息
+显示。编辑器、保存、冲突、AI 选区修改和关闭行为以
+[Office 协同编辑](../office-document-editing/README.md)为准。
+
+完整编辑器需要至少 `720px` 可用宽度；低于 `480px` 时不把第三方工具栏压缩到重叠，而显示
+摘要和“展开编辑”命令。展开到主内容区、底部或独立窗口继续使用同一页签实例和编辑会话。
+文档编辑依赖用户明确配置且声明健康能力的 ShareServer；不可用时保留入口和原因，不回退为
+未经说明的远程服务。本地默认应用打开仍是独立用户操作。
+
+### 7.11 Composer 与任务上下文

 工作栏不提供独立“上下文”能力。用户准备下一次模型请求时：

@@ -428,7 +594,9 @@ type WorkbarCapabilityId =
  | 'processes'
  | 'workspace'
  | 'browser'
+  | 'resources'
  | 'results'
+  | 'document'

 type WorkbarTargetRef =
  | { type: 'conversation'; id: string }
@@ -441,6 +609,7 @@ type WorkbarTargetRef =
  | { type: 'managed-process'; id: string }
  | { type: 'browser-session'; id: string }
  | { type: 'artifact'; id: string }
+  | { type: 'document-session'; id: string }
 ```

 Renderer 选择目标后，Main 必须重新验证对象存在、归属范围和当前用户可见性。不能把目标 ID
@@ -470,15 +639,15 @@ type WorkbarPanelInstance = {

 本节定义产品入口和用户行为。Host Key、凭据、远程 Agent 协议、模型请求代理、签名更新、
 断线和 Runtime 适配的技术边界以
-[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../../architecture/remote-host-and-goodbuddy-agent-design.md)
+[SSH 远程主机与 GoodBuddy Agent 稳定终态设计](../remote-host/technical-design.md)
 为准。

 ### 9.1 设置入口

 设置中心“平台功能”提供独立“远程项目（技术预览）”页签及开关，默认关闭。关闭时不显示
 “主机与远程执行”分类、托管 SSH 项目创建选项和已保存远程项目，Main IPC 同时拒绝新的
-SSH/远程项目操作；已有 Host、项目和凭据保持不变。若关闭时正在激活远程项目，应用发出
-取消并保持或切回普通本地项目；若当前项目已经是远程项目，则切回项目列表中的第一个普通
+SSH/远程项目操作；已有 Host、项目和凭据保持不变。若当前项目已经是远程项目，则切回
+项目列表中的第一个普通
 本地项目。重新启用后恢复完整入口和既有数据。

 启用后，设置中心显示“主机与远程执行”分类，管理：
@@ -491,6 +660,9 @@ SSH/远程项目操作；已有 Host、项目和凭据保持不变。若关闭
 - 删除、重新验证或更新 Host Key。

 主机配置是全局资源。项目或工作栏只引用主机 ID，不能复制凭据。
+删除 Host 前列出所有引用它的本地项目记录，包括归档项目；确认后仅删除本机 Host、凭据、
+项目和关联数据，不建立 SSH 连接，也不删除远端目录或内容。若当前项目被删除，界面切回
+普通本地项目。

 当前实施状态：设置中心已经实现主机 CRUD 和模态验证向导。新增或目标/认证编辑依次完成
 连接信息、认证前 Host Key 核对、密码/系统 SSH Agent 认证和平台/架构/Shell/Home 有界
@@ -501,22 +673,51 @@ SSH/远程项目操作；已有 Host、项目和凭据保持不变。若关闭
 和文本模型 profile 验证后原子提交。私钥导入仍未开放。旧流程已保存但
 没有成功探针记录的主机继续读取，但在完成新向导前显示为“需要重新验证”。

-应用重启后固定进入项目列表中的第一个普通本地项目，不自动激活上次远程项目。用户主动
-打开已有托管 SSH 项目时，Main 会用数据库中的项目字段重新执行同一套
-Host/Agent/Workspace/Runtime 验证。桌面版本携带的 Agent 或 Runtime identity 已变化时，
-先 side-by-side 安装新候选，全部成功后再原子刷新项目 evidence 并切换当前项目；失败保留
-此前项目和安装绑定，不由 Renderer 用旧草稿重建更新请求。同一 Renderer 对同一项目的
-重复激活共享一个操作，不会并行启动第二次保存。
-主动打开期间，项目切换器在原位置展示 Host、Agent、Workspace、Runtime、Saving
-五个阶段及原生 `progressbar` 语义；用户可以取消，项目切换、创建和设置入口在操作结束前
-保持禁用。成功后才提交项目选择，失败或取消继续保留此前项目。
+当前源码已把 Agent/Runtime 生命周期归入 Host 管理。新增或重新验证 Host
+在身份、认证和系统探针成功后先保存 Host，再只读探测实际组件状态和瞬时下载能力，然后
+结束新增向导。产品不提供自动安装开关，也不在保存后传输包。Host 卡片只有一个按版本
+事实显示“安装远程环境”“更新远程环境”或“重新安装”的主按钮；次级 SegmentedControl
+选择“自动”“Host 下载”或“GoodBuddy 传输”，默认“自动”且不持久化。版本匹配 badge
+不代表环境健康。环境准备失败或取消保留 Host 并显示可重试状态；重新安装失败时显示
+本次操作未完成，并以随后重新检查的版本卡片表达当前事实，不对不确定提交宣称旧版本
+未被替换。详细技术契约见
+[SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)。
+
+进入或切回“主机与远程执行”页面只读取本地 Host 列表，不逐台建立 SSH 连接。版本和瞬时
+下载能力仅在用户点击某台 Host 的“刷新版本”时探测，成功结果在当前 Renderer 进程内按
+Host 持久化缓存，切换页面或重启应用后返回直接显示；Host 编辑、删除或开始更新远程环境后
+不复用旧结果。该动作不是项目连接前置条件；用户
+切换已有远程项目只更新 Renderer 的本地项目选择，不建立 Host/Agent 连接。
+新建远程项目弹窗同样只读取本地 Host 验证记录，不扫描所有 Host；浏览目录或保存时才连接
+所选 Host。版本号相同时仍允许用户显式重新安装，以修复 registry、签名或 identity 异常，
+且不删除 Host、凭据或项目。由远程主机安装只使用 SSH 和远端系统工具，不依赖已有 Agent；
+“自动”仅在操作开始时探测：直连明确可用才选 Host 下载，否则选 GoodBuddy 传输；用户
+显式选择不被改写，prepare、commit 或 adoption 失败后不在同次操作中切换 acquisition。
+
+项目选择器中每个项目的管理按钮默认隐藏，在悬停、键盘焦点或触屏环境显示。该入口直接
+打开目标项目设置而不先切换项目，因此 Host 不可达或远端目录已不存在时仍可删除本地项目
+记录；删除操作从不删除远端项目内容。
+
+应用重启后固定进入项目列表中的第一个普通本地项目。用户主动打开已有托管 SSH 项目时只
+切换本地项目配置；首次实际使用 Workspace 或 Runtime 时，Main 才通过 Agent/Runtime
+安装管理器解析 Host current identity，执行固定 `attach-or-bootstrap`，并使用同一 Agent
+连接。
+项目数据库不保存 Agent installation、Host revision、Workspace identity 或 Runtime
+digest。当前 registry、连接或 capability 无效时项目保持未切换，并提示到 Host 管理显式
+修复。当前进程缓存每个 Host 已确认的 Agent/Runtime identity，并复用 Agent 连接；Host
+编辑或环境更新会定向清空。Agent 的 attach/按需启动只读取 Host 管理已提交的 registry 与
+匹配 manifest 元数据，不重新验签或哈希完整 Agent payload。项目切换器立即提交本地选择，
+不展示远程激活进度；完整进度和取消只属于新建或显式保存项目。
+
+项目只持久化 Host ID、规范远端路径、Runtime 选择和默认工作模式。新建和保存验证当前
+Workspace/Runtime，但不写入组件 identity；普通切换不做远程验证。未就绪或版本过旧时，
+实际 Workspace/Runtime 操作显示错误。桌面更新造成组件版本变化时，用户先在 Host 管理中
+准备环境；项目切换本身不连接、不下载、不扫描、不安装，也不改写项目。

 已保存 Host 的地址、用户或固定 Host Key 变化后，Main 关闭旧连接并定向退役该 Host 的
-Runtime 缓存。当前项目引用该 Host 时，设置保存成功会立即运行上述完整激活流程并刷新
-项目验证；其他项目在下次选择时刷新。用户再次选择当前 SSH 项目也会执行完整激活，
-不能因为项目已经选中而跳过验证。从 Host 保存到项目成功激活之间，项目持续保持需要
-重新连接状态；失败或取消不会重新开放 Composer。已由 Main 派发的用户排队消息退回原
-持久队列，不生成失败消息、不丢失附件，并在成功激活后的 queue-ready 通知中继续派发。
+Runtime 缓存。引用项目下次选择时使用 Host 管理的当前 revision、Host Key 和用户执行固定
+attach 并读取 current registry，不存在项目中的旧 Host revision 或组件 identity；
+当前环境无效时才要求显式修复。

 新建托管 SSH 项目时，远端工作目录既可手工输入，也可通过文件夹按钮打开 Main 管理的
 只读、有界 SFTP 目录选择器。选择器从 SSH 账号 Home 或当前有效绝对路径开始，只返回目录，
@@ -545,11 +746,25 @@ Runtime 缓存。当前项目引用该 Host 时，设置保存成功会立即运
 - 安装到远程当前用户的 GoodBuddy-owned 目录，不要求 root。首次连接先 attach，Agent
  不存在或未运行时幂等 bootstrap 为 detached process，再重新 attach；不注册开机服务，
  不依赖 systemd、D-Bus 或 `Linger=yes`。
- SSH 负责 Host Key、认证、SFTP 安装和固定 `goodbuddy-agent attach` 中继；attach 只连接
-  用户私有 Unix socket。SSH relay 断开不终止 Agent 或活动 Runtime。
- 上传内容使用应用内置公钥验证的签名 manifest，并校验组件版本、协议、平台、架构、大小
-  和 SHA-256。Agent 与 Runtime 各自维护版本，签名摘要标识精确工件；使用 side-by-side
-  安装、自检和健康切换，失败时不改变当前项目绑定。
+- SSH 负责 Host Key、认证、固定 bootstrap、可选 SFTP 安装和 `goodbuddy-agent attach`
+  中继；attach 只连接用户私有 Unix socket。SSH relay 断开不终止 Agent 或活动 Runtime。
+- Host 环境准备可让远端按签名目录固定的 GitHub/北京镜像 URL、大小和 SHA-256 下载完整
+  `.gbagent`，也可由 GoodBuddy 下载、完整验证后通过有界流式 SFTP 传输一个 compound
+  archive 和归档中已验证的 bootstrap Node；完整包不一次读入 Main `Buffer`，Host 仍再次
+  校验。两种 acquisition 交付到固定 operation staging 后共用
+  `prepare → commit → Agent activate/health → Runtime activate → finalize → cleanup`。
+- 直连首次 bootstrap 不依赖已安装 Agent daemon。GoodBuddy 桌面控制面通过固定 SSH
+  prepare channel 发送有界 one-shot installer；Host 先验证目录绑定的归档大小和 SHA-256，
+  再由 format v1 归档内固定 Node 解码并运行 installer。归档无需包含
+  `agent/lib/package-installer.cjs`，目录不提供或检查额外的 bootstrap 能力元数据。
+- Agent 与 Runtime 各自维护版本，签名摘要标识精确工件。Host 在解包到准备目录的同一遍
+  处理中完成完整 payload 校验，commit 只复核签名 metadata 并原子替换 side-by-side
+  目录，不重新读取归档、扫描旧目录或使用跨安装硬链接。
+- Main 只保存清理 operation staging 所需的 operation ID。控制通道中断或 adoption 失败
+  后，下次更新尽力清理旧暂存并重新 prepare，不保存或恢复 Agent/Runtime metadata 副本。
+  新 Agent/Runtime 各自最多完整验证一次；注册后的
+  health、capabilities 和 prompt 启动只检查 registry、签名 manifest 与入口 metadata。
+  确认 adoption 后显式 cleanup，cleanup 失败不回滚健康环境，也不阻塞下一次 fresh prepare。
 - 握手报告 installation、Daemon boot identity、协议、系统、架构、用户监督器和能力。
 - 在远程执行路径规范化、Git、文件、PTY、进程组和 Runtime 管理。
 - 持久化有界 Agent 到 Main 输出；SSH 断开后 Agent 继续运行，同一 Agent 重连时只恢复
@@ -663,12 +878,16 @@ remote_operations
 其中：

 - 工作栏偏好只保存能力目录顺序、面板实例、停靠布局、尺寸和目标引用。
+- 资源监控只保存面板实例，不保存采样结果或历史曲线。
 - 主机表只保存非敏感元数据和加密凭据引用。
 - 应用重启后先通过远程 Daemon 的 journal、lease、boot identity 和 event cursor 核对活动
  终端、进程与 Runtime；无法确认时标记 `interrupted` 或 `outcome_unknown`。
 - 日志使用有界环形缓冲或分页持久化，不能无限写入 SQLite。
 - Artifact 继续作为成果的权威实体，不把完整成果复制进工作栏状态。
- 当前 Renderer `localStorage` 活动记录不能作为 Runtime、监督或进程的权威来源。
+- 运行记录由 Main SQLite 持久化，Renderer 只保留当前内存视图。升级时迁移旧
+  `localStorage` 记录；若旧缓存达到原数量、详情或总大小边界，页面持续说明更早记录或
+  部分详情可能已经丢失。新记录不再按固定活动数或详情字符数丢弃，长列表只做可继续展开的
+  分批渲染。

 ### 11.3 IPC 与 Preload

@@ -679,7 +898,7 @@ Renderer 只通过显式方法访问：
 - 终端创建、输入、调整大小、关闭和有界输出订阅。
 - 受管进程列表、日志和允许的控制动作。
 - Runtime Inspector 快照、事件和允许的控制动作。
- 工作区、成果、浏览器和监督的既有或扩展服务。
+- 工作区、成果、浏览器和监督的既有或扩展服务，以及有界的本机资源快照。

 每个 Main Handler 都必须验证可信发送者、Zod 输入、对象归属和当前状态。不得暴露 raw
 Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
@@ -688,7 +907,7 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。

 1. 工作栏能力目录项和面板实例不授予任何能力；权限只由 Main 中的范围和控制契约产生。
 2. Ask 在本机和远程 Runtime 边界保持只读。
-3. Execute 继续经过现有 Runtime 和审批控制，工作栏不能直接放宽。
+3. Execute 使用当前执行账号的完整权限，不另加目录或逐工具审批；工作栏不能绕过 Main、Preload 与用户数据边界。
 4. 用户终端和 Agent 工具执行使用不同身份和事件来源。
 5. 进程面板只控制 GoodBuddy 受管对象，不接受任意 PID。
 6. 本机和远程路径分别在对应文件系统上 canonicalize 并验证符号链接边界。
@@ -718,6 +937,55 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 应用通知；预览失败、终端断线、Host Key 变化、监督证据失效等需要本地恢复的错误留在面板
 内。同一事件不得同时重复显示为面板警告和应用通知。

+### 13.1 Runtime 执行清单
+
+本节为待实施设计。用户需要在对话顶部查看 Agent 本轮列出的工作项及完成情况，避免在
+工具记录中反复查找。这里的“执行清单”由 Runtime 更新，术语边界见
+[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md#17-runtime-执行清单)。
+
+- **FR-CL1**：接入 OpenCode（OC）的 `todowrite` 与 Continue（CN）的 `Checklist`，
+  范围包括本地及远程 GoodBuddy Agent 上运行这两个 Runtime。远程 CN 的部署和正常请求
+  路径也属于交付范围，当前可用程度见[进度](./progress.md#2026-09-15-runtime-执行清单设计未实现)。
+- **FR-CL2**：顶部展示本轮最新有效清单，更新按整份替换处理，支持明确清空。每轮请求、
+  会话、项目、执行空间与 Runtime 的清单分别归属；普通聊天续轮不能沿用旧清单冒充本轮进度。
+- **FR-CL3**：清单只读，用户不能手动勾选。请求完成、失败或取消保留清单实际状态，
+  不自动完成工作项；原生工具调用继续进入消息与活动记录。
+- **FR-CL4**：重新打开会话可恢复已保存的清单及请求结果，远程重连遵循已有 Agent 恢复
+  流程，不重新发送模型或工具请求。没有原生清单的请求不显示空占位。
+
+ACP 仅是传输及远端协议，不分类为 Runtime。DeepSeek Harness（DS）真实默认环境无
+todo/plan，本次不为其增加工具。也不增加 plan 工作模式、计划文档、计划编辑器或定时任务
+能力；只有格式已确认的原生 plan entries 可以适配清单。
+
+#### 顶部布局
+
+执行清单位于聊天内容区顶部、已有 Task 上下文栏下方、消息流上方；没有 Task 时仍可独立
+显示。它不占用窗口标题栏操作区，也不替换 Task 摘要、任务索引或右侧 Runtime 栏目。
+布局遵循 [UI-DESIGN](../../../UI-DESIGN.md#610-应用顶栏与全局操作)。
+
+默认折叠为一行“执行清单 · 已完成 m/n”，有进行中条目时附简短摘要；展开后按原生顺序
+显示内容、状态及原生提供的优先级。行内状态使用图标和“待处理 / 进行中 / 已完成 / 已取消”文字，
+不用可勾选 Checkbox，也不根据位置推测优先级或进行中状态。请求结束后的摘要附真实
+请求结果，例如“已取消”，不改变条目状态。后台更新不强制展开、不抢焦点。
+
+展开按钮提供 `aria-expanded` 和 `aria-controls`，支持 Enter/Space，折叠后焦点留在
+按钮；实时区域只播报摘要变化。复用全局颜色、间距和字体令牌，浅深主题均可读。窄窗口
+摘要截短、展开内容换行并有界滚动，保留完成计数、请求结果与输入区；200% 缩放时仍可
+操作。没有清单或收到有效空清单时整行隐藏，历史内容仍按消息归属查看。
+
+#### 场景验收
+
+| 场景 | Given / When / Then | 需求 |
+| --- | --- | --- |
+| US-CL1，连续更新 | OC/CN 本轮产生清单并修改、重排或删除条目；顶部显示最新完整内容，工具活动仍可查 | FR-CL1–FR-CL3 |
+| US-CL2，请求隔离 | 同会话开始下一请求、切换 Runtime 或并行使用另一会话；旧轮迟到事件不覆盖当前清单，历史按原归属保留 | FR-CL2、FR-CL4 |
+| US-CL3，失败与取消 | CN 更新失败或请求被取消；失败候选不替换上次有效清单，取消不把未完成项勾完；有效空清单清除顶部 | FR-CL2、FR-CL3 |
+| US-CL4，本地与远程恢复 | 重新打开本地会话或重连共享 Linux Host 上的 OC/CN 请求；已有记录按原请求恢复，重复事件不重复展示，不重新调用模型或工具 | FR-CL1、FR-CL4 |
+| US-CL5，无清单与无障碍 | DS 默认请求或普通 Markdown/list 工具输出没有已确认清单；顶部不出现伪清单；有清单时键盘、窄窗口及浅深主题可用 | FR-CL1–FR-CL3 |
+
+行为规则见 [Runtime 交互边界](./runtime-interactions.md#runtime-执行清单)，接入与验证见
+[技术设计](./runtime-checklist-technical-design.md)。
+
 ## 14. 性能与资源边界

 - 工作栏关闭或面板实例关闭时停止对应非必要画面和高频日志推送，但保留 Main 中的受管运行。
@@ -730,6 +998,41 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
  用户级 GoodBuddy Agent Daemon。依赖 Main 模型网关、审批或本机工具的 Run 不能被描述为
  可以无人值守继续。

+### 14.1 Runtime 资源复用
+
+2026-09-14 调研确认：多个项目可能各自保留一个重型 Runtime，状态或原生清单读取也会
+影响其启动与保留。用户需要多项目/多会话自然并行工作，而不是为避免内存增长关闭工具、
+子代理或删除历史。以下为新需求，**不表示 Desktop 0.13.2 / Agent 0.11.25 已实现**。
+
+- **FR-RR1**：支持原生多会话的 Runtime，在同一账号和兼容启动配置下跨项目复用重型
+  进程；不得仅因项目目录或会话不同重复启动。等价的默认和显式选择应得到相同复用结果。
+  不兼容的 Runtime、Host、模型连接或插件配置可以分开，不要求全产品只有一个进程。
+- **FR-RR2**：仅查看被动状态不启动重型 Runtime。显式连接测试、原生清单和执行请求
+  复用兼容的已启动实例；尚未握手时不能显示为已经验证连接。
+- **FR-RR3**：共享进程仍保持各会话的目录、历史、模型用量、工具、权限和业务问答归属。
+  同一会话顺序执行，不同会话并行；Ask 保持只读，Execute 不增加第二层审批。
+- **FR-RR4**：请求结束、会话释放与进程退出分别处理。取消一个普通请求、关闭工作栏
+  或释放一个会话不得误停其他健康会话；无会话的空闲重型实例及时释放。正常续聊保留
+  原生上下文，应用退出、配置替换和真实进程故障仍有明确的终态与有界回收。
+- **FR-RR5**：托管 SSH 独立实现并验证复用，保留 Agent 对活动 Prompt 的所有权、
+  断线续接、事件去重和模型调用结果不确定性规则。不能以本机通过代替远端交付。
+- **FR-RR6**：对不具备原生多会话 Host 的 Continue 保留正确的请求隔离；直连模型不
+  新增独立模型进程。优化应有前后性能证据，不以删历史、禁用工具、全局串行化或
+  推迟正常用户操作来换取进程/内存指标。
+
+产品场景验收：
+
+| 场景 | Given / When / Then |
+| --- | --- |
+| US-RR1，首次与热启动 | 同一有效配置的两个项目，分别查看状态、打开清单并开始四个对话；状态不冷启动，后续共用一个可多会话的重型 Runtime |
+| US-RR2，并行与取消 | 两个项目有同名不同内容文件，四个会话进行真实开发；目录及成果正确，取消其中一个后其余三个继续完成 |
+| US-RR3，续聊与释放 | 一轮任务完成后继续原会话，再释放其中一个；原生上下文可续用、其他会话不受影响，数据库完整历史仍可查看 |
+| US-RR4，边界与远程 | 切换不兼容配置、查看 Continue/直连状态或中断 SSH；不串配置、不伪造多会话能力，Agent 已接受工作按现有归属恢复 |
+
+资源状态规则由 [Runtime 交互边界](./runtime-interactions.md#runtime-资源生命周期)
+定义；锁定版本研究、实现选择与逐项验收由
+[进程复用技术设计](./runtime-process-reuse-technical-design.md)定义。
+
 ## 15. 无障碍与响应式

 - 能力目录、所有面板实例、目标选择器、终端控制和进程操作可用键盘完成。
@@ -759,16 +1062,19 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。

 ### 阶段 1：成果与 Runtime 可观测性

+- 本机 CPU、内存、磁盘 IO 和 GoodBuddy 桌面进程摘要的按需资源监控。
 - 通用 Artifact Event。
 - HTML 工作区和成果的静态即时预览。
 - Runtime Inspector Snapshot 与事件。
- OpenCode 会话、子会话、Todo、工具、用量和取消。
- 直连模型及现有 GoodBuddy Subagent 的统一展示。
+- OpenCode 会话、子会话、Todo、工具、用量和取消；本地与托管 SSH 的原生 Task 调用在
+  Conversation 中统一显示为可追踪的 Subagent 状态，而不是普通工具参数卡。
+- 直连模型、OpenCode 原生 Subagent 及现有 GoodBuddy Subagent 的统一展示。

 ### 阶段 2：监督、终端与受管进程

 - 普通会话手动监督和右栏评论流。
- 本机 PTY 终端。
+- 工作栏持久“+”、应用注册表和单/多实例 Tab。
+- 本机 PTY 与直接 SSH PTY 多终端。
 - 受管进程注册、日志和终止。
 - 自动回复后监督、节流和独立预算。
 - 用户选择终端停靠位置。
@@ -788,11 +1094,22 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 - 签名、side-by-side GoodBuddy Agent 安装和按需 detached Daemon。
 - SSH connection pool、固定 attach relay、Agent 控制协议、Agent 本地 ACP 日志和断线重连同步。
 - 远程工作区、Git、终端和受管进程。
- 先完成签名 OpenCode bundle、Ask bubblewrap、Execute 直接进程、官方 ACP channel、
-  Main 模型网关、取消、超时和活动记录。
+- 当前签名 OpenCode bundle 的 Ask/Execute 均直接启动，Ask 在工具边界保持只读，
+  Execute 使用账号完整权限；官方 ACP channel、Agent 本地模型网关、取消、超时和活动记录
+  以[远程主机技术设计](../remote-host/technical-design.md)为准。
 - OpenCode 闭环稳定后，Continue 与 DeepSeek Harness 复用相同面板和通道契约逐个接入。
- 一次远程项目保存请求完成 Host/Agent/Workspace/Runtime 全量验证和 SQLite 原子提交。
- 桌面更新后，用户主动首次打开远程项目时自动安装当前签名 Agent/Runtime，并在成功后原子刷新项目绑定；应用启动本身不连接远程项目。
+- 新增或重新验证 Host 时只保存并探测 Agent/Runtime，不自动安装。用户在 Host 卡片用
+  单一主按钮启动，并用次级控件选择自动、Host 下载或 GoodBuddy 传输；Host 保存与环境
+  准备是两个可独立重试的事务。
+- 控制面直连源码直接使用既有 package format v1 包；不等待发布携带 installer 的新
+  Agent 包，也不通过额外目录元数据判断 bootstrap 能力。GitHub/北京镜像、
+  Linux x64/arm64、取消和离线 GoodBuddy 传输仍须真实 Host 验收，不能据此声称已发布或已完成
+  真实 Host 测试。
+- 一次远程项目保存请求完成 Host/Agent/Workspace/Runtime 当前环境验证和 SQLite 原子
+  提交，但只持久化 Host、路径、Runtime 选择和模式，也不获取或安装组件。
+- 桌面更新后，用户先在 Host 管理中更新当前签名 Agent/Runtime；远程项目下一次实际使用
+  Workspace/Runtime 时直接使用新的 current 环境，无需刷新项目绑定。应用启动和项目切换
+  本身都不连接 Host，也不下载或安装组件。
 - SSH、Main、Daemon、Runtime 和远端重启后的核对、恢复与 `outcome_unknown`。
 - 支持平台的安装、Ask、Execute、取消和重连冒烟测试通过后开放对应 OpenCode 能力。

@@ -807,7 +1124,7 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。

 ### 17.1 稳定能力目录与用户控制

- [ ] 八个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。
+- [ ] 十个标准能力在所有主要页面的目录中始终可发现，但不会默认同时打开。
 - [ ] Task Center 继续作为 Task 的单例索引，不删除入口、不复制会话，也不混入 Job、Run 或心跳事项。
 - [ ] 项目、会话、Runtime 或主机变化不会无提示地增删能力目录项。
 - [ ] 用户可以按需打开、关闭、排序和停靠面板实例。
@@ -822,6 +1139,8 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 - [ ] 监督可以作用于普通 Conversation、Task 和后续实验对象，不假设编程语境。
 - [ ] 工作区不是 Git 仓库时仍可浏览文件。
 - [ ] Runtime 不支持某项原生能力时仍可从目录打开面板并获得准确说明。
+- [ ] 文档能力可以打开多个以文件名命名的固定实例；未配置健康 ShareServer 时显示原因，
+  不把系统默认应用或静态预览冒充内置编辑。

 ### 17.3 安全与控制

@@ -843,6 +1162,11 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。
 - [ ] 重连先恢复 event cursor 并查询 operation；有副作用操作不会自动重放，无法确认的
  结果显示为 `outcome_unknown`。
 - [ ] Agent side-by-side 更新支持所需签名版本的健康切换，失败时保留旧项目绑定。
+- [x] 新增 Host 只探测远端下载能力，不提供自动安装开关，也不传输完整包；Host 卡片用
+  一个按版本事实命名的主按钮与不持久化的 acquisition SegmentedControl 启动准备。
+- [x] 创建、保存、打开和切换托管 SSH 项目都从 Host current registry 与当前 Agent
+  连接验证环境；项目只保存稳定配置，且这些流程不下载 `.gbagent`、上传 payload 或发布
+  安装。
 - [ ] 切换跟随目标后不显示上一对象的过期状态。
 - [ ] 固定目标的订阅在页面切换后保持，关闭时正确释放。
 - [ ] 日志、终端、文件、成果和远程传输均有明确上限和背压。
@@ -851,24 +1175,36 @@ Electron、ChildProcess、PTY、SSH Client、Socket 或文件句柄。

 - [ ] 宽、中、窄窗口均可访问完整能力目录和用户打开的面板实例。
 - [ ] 工作栏在宽、中、窄窗口展开时都推动主工作区回流，不覆盖、遮罩或隔离主内容；唯一
-  开关始终固定在窗口关闭按钮正下方。
+  开关始终固定在顶栏操作区、紧邻浅色/深色主题按钮之前。
 - [ ] 仅使用键盘可以选择能力、面板实例、目标、执行空间和控制动作。
 - [ ] 状态不只依赖颜色，徽标具有文字或可访问名称。
 - [ ] 终端、HTML、监督证据和高频日志具有可访问替代或降噪行为。
+- [ ] 浏览器 Tab 顶部工具栏始终清楚区分“停止加载”和“关闭浏览器”；地址编辑草稿不会被
+  权威状态刷新覆盖，用户与 Agent 的导航通过同一 `BrowserService` 会话串行执行。
+- [ ] 创建中、Agent 操作中和完整交互期间禁用浏览器其余工具栏控件；活动加载仍可单独停止，
+  且停止加载不会关闭会话或释放 Runtime 上下文。
+- [ ] 活动 Conversation 没有浏览器会话时，可从同一地址栏按 Agent 相同 URL 策略启动会话。
+- [ ] 文档编辑器在右侧宽度不足时不发生工具栏或正文重叠，并可使用同一会话展开到可编辑布局。

 ## 18. 相关文档的职责

 - 本文是助手工作栏稳定能力目录、用户面板实例、范围控制和执行空间的产品总契约。
+- [助手工作栏多终端页签 PRD](./terminal-tabs-prd.md) 定义持久“+”、应用实例策略、
+  动态 Tab 以及本机与直接 SSH 多终端。
 - [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 定义 Task、Conversation、
  Job、Subjob、Run 与 Subagent。
- [Task Center PRD](../task-and-job/task-center-prd.md) 定义应用级 Task 索引。
- [智能心跳 PRD](../smart-heartbeat/smart-heartbeat-prd.md) 定义心跳入口、范围和长期边界。
- [会话监督 PRD](../supervision/conversation-supervision-prd.md) 定义监督判断、证据、预算和介入边界。
+- [Task Center PRD](../task-and-job/task-center-prd.md) 定义单实例、项目跟随和显式范围切换。
+- [智能心跳 PRD](../smart-heartbeat/prd.md) 定义心跳入口、范围和长期边界。
+- [会话监督 PRD](../conversation-supervision/prd.md) 定义监督判断、证据、预算和介入边界。
 - [自动化平台总体设计](../../architecture/automation-platform-architecture.md) 定义 Plan、Job、Run、监督、预算和记忆。
 - [长期助手路线图](../../roadmap/long-term-assistant-roadmap.md) 记录整体长期能力与实施背景。
- [DeepSeek Harness Runtime 设计](../../architecture/deepseek-harness-runtime-design.md) 定义该 Runtime 的具体适配边界。
+- [DeepSeek Harness Runtime 设计](../deepseek-harness/technical-design.md) 定义该 Runtime 的具体适配边界。
+- [SSH Host 远程环境准备与直连下载设计](../remote-host/environment-provisioning-technical-design.md)
+  定义 Host 级组件获取、首次准备、更新、回退和项目只验证边界。
+- [Office 协同编辑](../office-document-editing/README.md) 定义文档多实例、ShareServer 编辑会话、
+  保存、冲突和 AI 选区修改。
 - [统一界面设计系统](../../../UI-DESIGN.md) 定义视觉、语义、响应式和无障碍规则。

-若其他文档把工作栏描述为八个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口，
+若其他文档把工作栏描述为十个同时固定显示的栏目、根据项目或 Runtime 自动裁剪的动态入口，
 或仅属于当前聊天的附属区域，以本文“能力目录稳定、面板实例由用户打开、当前上下文只提供
 默认值”的产品决策为准。
@@ -0,0 +1,106 @@
+# Runtime 执行清单技术设计
+
+状态：设计阶段，尚未实现。需求、场景与顶部布局由 [PRD](./prd.md#131-runtime-执行清单)
+维护，替换、隔离和终态规则由 [Runtime 交互边界](./runtime-interactions.md#runtime-执行清单)
+维护。研究证据与交付状态见[进度](./progress.md#2026-09-15-runtime-执行清单设计未实现)。
+
+## 1. 原生数据与提取位置
+
+| Runtime / 路径 | 已确认格式与设计接入 |
+| --- | --- |
+| 本地 OC 1.18.29 | `todo.updated` 与 `session.todo` 返回完整条目列表，字段为 `content/status/priority`，无 item ID；以原生更新事件驱动本轮整份替换 |
+| 本地 CN 1.5.47 | 精确原生工具 `Checklist` 的参数 `checklist` 是 Markdown 勾选列表，`- [ ]` / `- [x]` 表示未完成/完成；按一次成功调用提交完整替换 |
+| 远程 OC/CN | 先核对实际部署版本、原生输出与 Agent 传递结果；只有格式已确认且来源归属明确的原生 plan entries 或精确清单工具参数可以映射，当前尚无本功能远程实测 |
+
+`opencode-runtime.ts` 当前将普通工具 input 经 `boundedToolDetail(..., 4_000)` 转成
+展示字符串。接入应在 SDK 原始事件层消费 `todo.updated`；如需核对 `todowrite` 参数，
+必须在该截断之前处理。`session.todo` 是 Session 当前快照，读取结果必须与请求生命周期
+关联；不在每轮开始时无条件读旧快照充当新清单，也不轮询代替事件。
+
+CN 的提取位置在 `continue-host-adapter.ts`：宿主产生工具事件、HTTP 状态合并及输入
+校验均存在 4,000 字符展示限制，不能等到 `continue-runtime.ts` 收到截断字符串后再解析。
+宿主应在最早的原始参数层提取 `checklist`，按工具调用 ID 保留候选，结合最终成功状态
+提交；成功帧省略参数时使用同次调用的候选，失败不得提交。普通工具事件继续沿现有路径
+流转。超出 4,000 字符的清单需要独立验证完整性，但不扩大所有普通工具输入的展示上限。
+
+Markdown 解析只适用于已确认的 CN `Checklist.checklist`，不扫描助手正文或其他工具
+输出。空数组在统一事件中明确表示清除；CN 原生如何表达空清单，以及空白、大小写和
+非条目行的实际接受规则，实施时核对后固定解析规则。未确认或无效输入保留旧清单，
+不能误当清空。
+
+## 2. 统一事件与消息归属
+
+拟在现有 Runtime 事件联合中增加完整清单事件，承载 `requestId`、条目数组和原生来源；
+条目包含 `content`、`status` 及可选 `priority`。最终命名随实现确定，不设计条目级增删
+协议或稳定 item ID。空数组必须经过 schema、IPC、消息投影和保存链路，不能被“无内容”
+过滤丢弃。
+
+Main 使用现有请求到助手消息的映射投影清单，Renderer 顶部读取该消息的最新有效状态。
+同一请求若同时观察到原生清单事件与其工具记录，只以前者更新清单，后者保留活动；不能
+提交两次替换。原生父 Session、请求开始/结束边界需共同校验，子 Session 或旧请求事件
+不得通过当前活动请求映射到新轮。
+
+优先扩展现有消息 metadata、Runtime 事件和数据库投影，历史清单与所属助手消息一起保存。
+远端沿用事件提交、消息投影和 ACK 的既有事务及去重规则；相关存储边界见
+[执行记录存储](./execution-history-storage.md)。实施前核对本地会话与远程任务实际落库
+字段，选择能复用的最小表示。不新建清单数据库、独立快照系统、恢复日志或持久化服务。
+旧消息没有结构化清单时保持缺省，不从已截断工具字符串或状态文案补造历史。
+
+## 3. 远程 Agent 与 ACP 复用
+
+本次源码检查确认以下传递位置，属于设计依据，不是本功能远程验证结果：
+
+1. `AgentAcpConnection` 按原生 `sessionId` 分派 `sessionUpdate`；
+   `AgentOwnedAcpPrompt` 校验 Session 后，以 `bindingId/operationId` 将通知写入
+   既有 semantic transcript。
+2. `ProtocolRemoteRuntimeChannel` 已有 transcript 读取/ACK、身份核对，以及 ACP
+   channel 恢复与重放；`AcpRemoteRuntime` 消费 `session-update` 并转换桌面事件。
+3. `AcpRemoteRuntime` 当前将 `plan.entries` 及 `plan_update` 的 items 转成 `status`
+   字符串；markdown/URI 也只形成状态消息。工具事件按 `toolCallId` 合并 `rawInput`、
+   `status` 和结果，再有界保留。清单提取应发生在结构丢失或截断前。
+
+优先复用上述通知和 transcript，不另建远端清单通道。对实际 OC/CN 部署确认过的
+`plan.entries`，或已确认等价的 `plan_update` items，校验条目字段和状态后转成统一
+清单事件。普通 `status`、plan markdown/URI、`plan_removed` 文案以及泛化工具名均不
+触发清单更新；在没有确认对应原生清单身份前，`plan_removed` 也不能清空顶部。
+
+若远程原生输出走精确清单工具，须确认原始参数、调用身份与成功状态确实贯穿 Agent，
+再按同一提取规则接入。是否能直接复用原生 entries，或需补充最小 Agent 适配，取决于
+真实格式证据，不能根据 ACP 类型定义推断 OC/CN 一定会发送。ACP 是协议，Runtime 身份
+仍为 OC 或 CN。
+
+当前托管 SSH 产品及受管安装、校验、创建链路只支持 OC，详见
+[远程范围](../remote-host/technical-design.md#执行清单接入范围)。远程 CN 交付需补齐
+受管工件、安装与启动、项目选择/校验及原生事件接入，确认 Main 模型桥、请求归属、取消
+和已有恢复流程能用于该部署。不能只放开选择菜单或使用本地 CN 调远程模型来宣称完成。
+
+重连按[既有 ACP 与断线规则](../remote-host/technical-design.md#acp-与断线)执行。
+已接受 Prompt 使用原 binding/operation 恢复，清单从已提交消息和其后的既有事件恢复；
+重复事件不重复展示。连接丢失不表示条目完成，不为恢复清单重新发送 Prompt、模型请求或
+工具调用，也不新增独立重连机制。
+
+## 4. 实施与验收
+
+| 阶段 | 必须完成的工作 | 对应需求 |
+| --- | --- | --- |
+| CL-P1 | 原始层提取、严格格式校验、统一事件及请求归属；保留工具活动 | FR-CL1–FR-CL3 |
+| CL-P2 | 消息投影和既有存储恢复、顶部只读布局、空数组清除及终态展示 | FR-CL2–FR-CL4 |
+| CL-P3 | 确认远程 OC 原生格式，补齐远程 CN 真实部署与事件接入，复用 Agent 传递和恢复 | FR-CL1、FR-CL4 |
+| CL-P4 | 本地与共享 Linux 真实 Host 逐项验收，记录版本、结果、调用口径与剩余阻塞 | FR-CL1–FR-CL4 |
+
+以下均为待执行验收，本次文档工作不运行模型或代码测试：
+
+- 本地 OC/CN 各经桌面正常发送路径产生并连续修改清单，检查新增、修改、重排、删除、
+  重复文本、有效清空及超过 4,000 字符的完整内容；CN 成功才替换，失败保留前值。
+- 同会话连续两轮、并行会话、切换 Runtime/项目/执行空间、旧轮迟到事件和子会话事件
+  不串数据；完成、失败、取消不改写条目状态。默认 DS、任意 status/Markdown/list
+  工具不生成伪清单，工具活动仍可查。
+- 本地会话重新打开及应用重启恢复历史；顶部折叠、键盘操作、浅深主题、窄窗口和 200%
+  缩放符合 PRD，保存与重放后的空清单不会恢复旧内容。
+- 在共享 Linux x64 真实 Host 使用开发中的 Agent 与实际部署的 OC/CN，分别从远程项目
+  完成原生清单更新、取消、断线续接及历史恢复。沿用
+  [Agent 开发验证规则](../../../AGENTS.md#goodbuddy-agent-development-validation)，
+  LAN/VPN 是同一机器的两条路径，不能计作两台 Host。
+- 逐个记录 OC/CN 的安装、启动、模型请求、清单传递、顶部显示、取消和重连结果；基础
+  Runtime 成功不等于清单通过。任一步未执行写“待验证”，被外部条件阻塞则记录原因，
+  不以 mock、协议 fixture 或本地成功代替远程验收。
@@ -0,0 +1,175 @@
+# Runtime 交互边界
+
+本文定义当前原生交互的适配范围，不增加工作模式或第二层 Execute 审批。
+
+| Runtime | 权限确认 | 业务问答 |
+| --- | --- | --- |
+| 本机 GoodBuddy 管理的 OpenCode | 内部默认配置允许权限；每个 Ask 请求仍使用 deny-all 与显式只读能力。Execute 自动回复属于当前请求的父、子孙会话权限事件，不处理其他并行请求 | 通过 `question.asked` 转交父、子孙会话问题，支持原生单选、多选、yes/no、自由文本及跳过；使用公开 ID 回传 `question.reply/reject` |
+| 托管 SSH OpenCode | Agent 按已接受 Prompt 的 Ask/Execute 模式处理 ACP 权限，规则见远程主机技术设计 | 当前 Agent 插件转交原生父、子孙会话 `question.asked`；前台使用同一问答队列，回答和跳过经认证 Agent 控制通道回传，已知 Task 关联显示子任务归属 |
+| Continue | Execute 启动传入 `--auto`，剩余原生权限请求按当前模式自动答复 | 对接 `1.5.47` QuizService 的扁平 `pendingQuestion`，其中 `question` 是字符串。选项回答与自定义文本分别回传正确的 `isCustomAnswer`；跳过发送拒绝回答的文本 |
+| DeepSeek Harness | 固定 Host 的 Execute 文件与命令工具不询问目录权限；若收到 ACP 权限请求，活跃 Execute 直接选一次性允许，缺少该选项时使用 Runtime 提供的允许选项，Ask 拒绝，不等待额外 authorizer | 固定 Host 当前未提供通用原生业务问答服务，不把普通模型正文误识别成待答协议。模型以普通回复提问时，用户通过下一条消息回答 |
+
+托管 SSH OpenCode 的权限、原生问题事件与回复链路由
+[远程主机技术设计](../remote-host/technical-design.md)定义。该远端业务问答基线需要
+Desktop `0.13.0`、Agent `0.11.24` 和新启动的托管 Runtime；请先升级 Desktop，再更新
+Host 环境。2026-09-14 的已发布 Desktop `0.13.2` / Agent `0.11.25` 已包含此前问答修复，
+但不包含本文末尾尚未发布的进程复用改动。任意第三方 ACP 服务及旧 Agent 不因此获得通用问答接口。
+
+## 运行与失败
+
+- 结构化 yes/no 是普通选项，不从日志、自然语言或 Shell 输出猜测用户意图。
+- 前台同一请求的待答问题按公开 `questionId` 去重，按到达顺序保存在消息的
+  `pendingQuestions` 中。每次显示队首表单；有多个待答请求时显示数量。后续提问和重复
+  事件不替换当前表单或清空输入，回答或跳过成功后只移除对应 ID，再显示下一张表单。
+  提交失败保留队列、输入和重试入口，队列未清空时继续显示“等待你的回答”。
+- 本机与托管 SSH OpenCode 在提问到达前已收到原生 Task 的 `metadata.sessionId` 时，将精确匹配的
+  子会话关联为可选 `childTaskId`。问答卡片显示该任务名称；对应 Task 卡片显示
+  “等待你的回答”，展开后可点击“前往问答表单”滚动并聚焦当前队首表单，仍按顺序回答。
+  没有已知关联的子孙会话问题照常排队，不猜测子任务归属，也不从工具名或进度文本构造表单。
+- 回答或跳过成功后，会话保留只读的“问题与回答”，显示原问题及对应的选项答案、
+  自定义文本或“已跳过”。同一任务的多轮问答逐次保留，随本地会话保存，重新打开后仍可查看。
+  提交失败时保留输入与重试入口，不生成已回答记录；取消未回答的问题不记为主动跳过。
+- 提交响应晚于任务结束时仍保存已提交的问答，但不覆盖完成或失败状态；晚于下一轮提问时
+  不清除新的待答卡片。旧版会话未保存的问题与答案无法从“已提交”状态文案恢复。
+- 待答队列仅保存在当前桌面会话内存中，不写入持久会话快照。刷新仍在运行的消息时保留整个
+  本地队列；完成、失败、取消事件或持久化终态快照清除整个队列。迟到的提交结果可以保存
+  已回答记录，但不会恢复表单或覆盖终态。本机 Runtime 不恢复重启前未提交的问题；托管 SSH
+  重新附加同一存活 Agent Prompt 时，由 Agent 当前待答列表补发问题，已回答的历史事件不补发。
+- 未发布的进程复用源码在 Desktop 重启后由 Main 并行附加同项目的存活任务，将待答
+  列表和 Stop 所需的请求 ID 投影到实时 `activeRequest`，不保存该字段或重新发送任务。
+  回答/跳过成功由 Main 写回原远程助理消息的既有问答历史，Renderer 不覆盖远程正文或终态。
+  Runtime 设置、定制和能力更新让旧请求在原配置上结束，已有问题仍可回答；新请求使用
+  新配置。专家团队例外：既有专家调度器在设置替换时取消子任务，团队父请求也随之停止，
+  不使用替换后的模型汇总旧结果。详细实现见
+  [恢复与终态投影](./runtime-process-reuse-technical-design.md#63-恢复与终态投影)。
+- 后台任务收到结构化提问时，通过现有 Main 路径明确失败并提示改为前台对话，不永久等待。
+- 请求结束或取消后清除对应待答映射；过期回答明确报错，不转交给后来的请求。
+- 任意终端程序的密码、OAuth 登录、许可证确认或 stdin 提示不自动回复 `yes`。这类程序应
+  使用其非交互参数，或由用户在终端完成；不能把权限确认和业务决策混为一谈。Shell
+  工具保留其现有取消与超时，不新增日志解析或通用交互代理。
+
+## 托管 Runtime 的并行与输出
+
+子任务完整过程的显示与数据库差量存储相互独立，本机和托管 SSH 共用桌面存储层；
+旧库升级与空间回收规则见[执行记录存储与升级回收](./execution-history-storage.md)。
+
+- 本机和 Agent 管理的 OpenCode 启动配置都显式设置 `snapshot: false`。GoodBuddy 不消费
+  原生自动 Git 快照、快照差异摘要或快照撤销；关闭这条内部路径，避免大行级差异的同步
+  计算阻塞同一原生进程中的其他会话。
+- 文件工具、Shell、原生子代理、工作区 Git 状态和单文件差异保持可用；不新增全局会话
+  队列、请求重放或总执行截止时间。外部 OpenCode Server 的配置不由 GoodBuddy 改写，
+  已运行的旧原生进程也不会热更新配置。
+- Continue 使用 HTTP 传递响应和状态；Electron UtilityProcess 启动后持续排空不用展示的
+  stdout，避免控制台输出填满管道后阻塞宿主。stderr 的有界错误处理、请求取消与进程
+  回收保持不变，不把诊断输出复制进聊天或持久日志。
+- 远端最终启动配置由[远程主机技术设计](../remote-host/technical-design.md)定义，
+  模型桥生成最终配置时同样保留上述快照策略。
+
+## 工具操作摘要
+
+工具记录沿用 [UI 设计系统](../../../UI-DESIGN.md)的折叠布局。Continue、DeepSeek Harness
+和直连模型共用 `toolOperationSummary`：优先使用有效原生标题，否则从参数提取命令、
+文件路径、搜索条件或 URL，合并空白后最多显示 240 字符。无法识别时保留原有工具名
+回退规则；文件正文、整份参数 JSON 不进入标题，参数详情仍可展开查看。
+
+Continue 在宿主截断输入前提取摘要，流式完成与失败事件使用合并后的输入和摘要。
+DeepSeek Harness 按调用 ID 保留名称、输入和摘要，结束事件省略输入时仍能显示操作内容。
+直连模型从原始参数生成一次摘要，在待执行、执行中和完成时复用；审批失败、拒绝和
+执行失败、刷新重试仍保留已有提示。
+
+本机 OpenCode 沿用原生操作标题。远端 ACP 独立使用原生标题作为记录名称，不经过上述
+本地转换，本次没有修改 Agent、远程桥或协议。
+
+## 消息底部请求状态
+
+- 状态属于当前请求，不与顶部 Runtime 的连接中、就绪、不可用混为一谈。提交后先显示
+  “正在准备请求”；没有更具体的活动事件时显示“等待后续进展”，不声称模型正在思考。
+- 本机 OpenCode 只把当前父会话的 `session.status.retry` 映射为等待重试，显示原生
+  `attempt`、计划重试时间和有界脱敏原因；后续 `busy` 才显示已开始重试。其他会话的
+  状态不串入当前消息，不猜测总重试次数，不把 SDK 事件流重连当作模型重试。
+- 显示优先级为待回答、待确认、进行中的上下文压缩、明确的请求状态、待执行或执行中的
+  工具、未完成的子任务、等待后续进展。压缩沿用已有活动块，不重复增加底部提示。
+  正文、推理或工具进展会清除旧状态；子任务更新不覆盖父请求的重试提示。
+- 完成、失败、取消后保留真实终态，迟到的状态事件不能把请求恢复成处理中。底部状态点
+  为静态，不凭请求尚未结束暗示仍有进展；会话列表闪点和发送、停止按钮保持原有行为。
+- Continue、DeepSeek Harness 和远端 ACP 保留其已接入的处理与工具事件，不伪造未接入
+  的原生重试状态。直连模型的重试等待与请求开始文案见
+  [直连模型 UI 设计](../direct-model-agent/ui-design.md#6-错误与通知)；本次不改变任何
+  Runtime 的重试上限、请求重放或取消策略。
+
+实现与真实 Runtime 验证证据见[进度记录](./progress.md)。
+
+## Runtime 执行清单
+
+本节为未实现的状态设计，对应 [FR-CL1–FR-CL4、US-CL1–US-CL5](./prd.md#131-runtime-执行清单)。
+原始格式和传递边界由[技术设计](./runtime-checklist-technical-design.md)维护。
+
+清单属于一次请求及其助手消息。沿用项目、执行空间、Conversation、Runtime 选择和
+原生 Session 到请求的既有映射；远端还需核对 binding/operation。不能仅以原生 Session
+或 Conversation 为键更新顶部，因为同一会话会连续执行多轮请求。
+
+| 输入或操作 | 清单与顶部行为 |
+| --- | --- |
+| 本轮尚无有效清单 | 隐藏顶部清单，不复制上一轮内容 |
+| 收到本轮有效完整清单 | 按原生顺序整体替换，包括修改、删除、重排和重复文本；不按条目文本合并 |
+| 收到有效空数组 | 记录明确清空并隐藏；空数组与缺少清单字段不同 |
+| CN 调用进行中 | 候选只按该请求的调用 ID 暂存；成功后才提交完整替换 |
+| CN 调用失败、取消或格式无效 | 丢弃该候选，保留上次有效清单，工具记录保留实际结果 |
+| 请求完成、失败、取消或中断 | 冻结最新已提交清单，并显示请求真实结果；不推断条目完成，迟到输入不改写已结算清单 |
+| 同一会话开始下一轮 | 顶部转向新请求，上一轮清单留在原消息；旧轮事件不得归入新轮 |
+| 切换会话、项目、执行空间或 Runtime | 只读取目标归属的数据；原请求在原归属结算，不把原清单标为新 Runtime 的进度 |
+| 查看历史或重连 | 从原消息及既有事件恢复；按原请求和远程来源顺序去重，不能用最新原生 Session 快照覆盖历史轮次 |
+
+条目状态支持 `pending`、`in_progress`、`completed`、`cancelled`。OC 原生提供的 priority 保留；
+CN 未勾选项映射为 `pending`，已勾选项为 `completed`，不推断 `in_progress` 或 priority。
+OC 无稳定 item ID，视图索引仅服务本次完整列表渲染，不生成跨更新的条目身份。
+
+清单内容不创建、调度或完成产品 Task，也不改变底部请求状态。清单更新与工具活动可以
+同时保留，但顶部计数只来自已确认的结构化清单，不能反向解析普通状态文本、任意
+Markdown 或名称含 `list` 的工具。子会话清单不覆盖父请求顶部。
+
+以上产品状态规则已明确；远程 CN 接入、原生格式确认及历史字段选择仍属技术待办，见
+[进度记录](./progress.md#2026-09-15-runtime-执行清单设计未实现)。
+
+## Runtime 资源生命周期
+
+本节对应 [FR-RR1–FR-RR6、US-RR1–US-RR4](./prd.md#141-runtime-资源复用)，
+定义进程复用的行为规则。当前源码已接入本机共享 owner 和 Agent 共享 ACP；
+完整验收状态以[进度记录](./progress.md#2026-09-14-runtime-进程复用实施中)为准，不表示已发布。
+具体 owner、兼容键和协议实现见[技术设计](./runtime-process-reuse-technical-design.md)。
+
+资源有三个独立维度：进程是否启动/退役，会话是否仍持有原生上下文，请求是否在途。
+“任务完成”“当前没有选中该项目”“工作栏关闭”均不能直接推导进程可以销毁。
+
+| 触发 | 请求与会话行为 | 进程行为 | 对应需求/场景 |
+| --- | --- | --- | --- |
+| 被动状态读取 | 不取得新执行会话，已有状态可读取 | 不冷启动，不延长无会话 owner 的空闲期限；不为探测替换服务中的进程 | RR2 / US-RR1 |
+| 显式测试/原生清单 | 取得临时检查引用；清单带明确工作区 | 与执行共用启动 Promise 和 owner；结束只释放检查引用 | RR1、RR2 / US-RR1 |
+| 首次或并行 Prompt | 取得对应 execution space + conversation 的绑定 | 同兼容组复用，非兼容组分别启动 | RR1、RR3 / US-RR1、RR2 |
+| 普通请求完成 | 释放请求订阅、临时 token、问题和 callback，保留可续聊 Session | 不因为一个请求完成关闭整个进程 | RR3、RR4 / US-RR3 |
+| 取消一个请求 | 取消其模型/工具调用并结算，其他会话继续 | 不以 kill 共享进程代替正常会话取消 | RR3、RR4 / US-RR2 |
+| 关闭面板/切换项目 | 停止非必要 UI 推送；不取消后台任务或抹掉会话所有权 | 不触发隐式关闭 | RR4 / US-RR3 |
+| 显式释放/删除会话 | 释放该 Session 与会话工具资源；删除历史仍只由原有明确删除操作决定 | 其他引用仍在则保留 | RR4 / US-RR3 |
+| 无会话、无请求、无检查引用 | 不存在需要保留的原生上下文 | 进入短空闲等待，再关闭；新使用者到来取消等待 | RR4 / US-RR1、RR3 |
+| 配置替换 | 已接受请求使用旧配置结算，新请求使用新配置 | 旧 owner 排空后退役；不积累只被历史 ID 持有的旧配置进程 | RR1、RR4 / US-RR4 |
+| 进程故障/不可响应 | 只给该 owner 下受影响请求明确中断；未知结果不自动重放 | 有界终止失效 owner，不伪造逐会话故障隔离 | RR3、RR4 / US-RR2、RR4 |
+| SSH detach | 保留 Agent 已接受 Prompt 及既有恢复归属 | 关闭传输不关闭 Agent 或活动 Runtime | RR5 / US-RR4 |
+
+表中 RRn 是 PRD 稳定需求 ID `FR-RRn` 的简写。
+
+不变量：
+
+1. 一条请求始终使用接受时的 execution space、工作模式、配置和归属；不能读取后来
+   切换的 UI 选择，也不以进程 cwd 表示所有会话的 cwd。
+2. 同一会话串行，跨会话不增加全局 Prompt 队列。权限、子代理、问题、用量和最终清理
+   必须沿同一 Session/请求归属，不因共享进程放宽 Ask 或限制 Execute。
+3. owner 的退出条件依据所有使用者，不依据某个 adapter 的空闲状态。
+   未启动对象的 dispose 不产生冷启动；一个等待者取消不取消其他等待者的初始化。
+4. 正常会话仍持有原生上下文时，不用任意 TTL 清掉它来声称“空闲内存已回收”。
+   无会话 owner 的短空闲等待为 60 秒；
+   不增加用户配置项。它是进程引用回收，不是聊天历史保留期限。
+5. 持久历史不因请求结束、进程 idle、配置变化或测试 cleanup 被删除。
+   原生进程确实重启后的续聊沿现有历史重建规则，不新增第二套持久会话快照。
+
+已明确普通并行、取消、释放、配置替换及断线行为。各项实际通过的场景及尚未完成的
+组合/性能验证以[进度记录](./progress.md#2026-09-14-runtime-进程复用实施中)为准。
@@ -0,0 +1,386 @@
+# Runtime 进程复用技术设计
+
+## 1. 状态与结论
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已接入本机与 Agent 生产源码，Windows / Linux x64 验证结果及边界已记录，未发布 |
+| 日期 | 2026-09-15 |
+| 调研源码 | `de14a6157a6c34f1e3ef22619eca374a50a83706`；相关 Runtime 与 Desktop 0.13.2 一致 |
+| 需求 | [工作栏 PRD §14.1，FR-RR1–FR-RR6](./prd.md#141-runtime-资源复用) |
+| 行为规则 | [Runtime 资源生命周期](./runtime-interactions.md#runtime-资源生命周期) |
+| 验证事实 | [实施与验证记录](./progress.md#2026-09-14-runtime-进程复用实施中)，原始调研记录保留在同页 |
+
+**修复对象是进程所有权过细，不是工具太多，也不是历史记录应该删除。** 本机 OpenCode
+和 DeepSeek Harness 应在兼容启动配置内共享重型进程，工作区与会话上下文仍各自独立。
+远端 OpenCode 必须同时调整 Agent 进程所有权、ACP 连接和模型桥，不能把桌面修复当作远端
+修复。Continue 的锁定版本是单会话 Host，不做未经验证的常驻进程池；直连模型没有独立
+模型进程，应检查对象、历史和工具资源的生命周期。
+
+“一个进程”指一组兼容启动配置对应一个 Runtime Server/Host，不是把不同 Runtime、
+不同 SSH 账号、不同插件组合强行塞入一个进程。正常工具命令产生的短期子进程不属于重复
+Server，也不能通过关闭 Shell、子代理或 MCP 来达成进程数指标。
+
+## 2. 修复前证据与缺陷
+
+### 2.1 已测现象和解释边界
+
+Windows 已安装 0.13.2 的只读采样发现两个属于同一 App 的 OpenCode Server：一个原生
+数据库为 0 Session / 0 Message，约 527 MiB Private Commit；另一个已有会话并执行请求。
+两个 Server 的启动工作区不同。源码能解释“清单查询也可启动按工作区缓存的 Runtime”，
+但没有取得能独立证明空 Server 最初由哪一个 UI 操作启动的调用链记录。
+
+该缺陷不等于整个 App 内存的唯一来源。五分钟活跃采样的 App 相关进程 Private Commit
+约 3.15–3.78 GiB，CPU 平均占整机约 3.15%；后续一分钟包含新任务，不是空闲回收试验。
+数据库五分钟增长约 2.72 MiB，新增子代理负载约 1.49 MiB，重复工具 upsert 为 0。
+schema 35 的存储修复与本方案独立，不能回退或删历史来改善指标。
+
+同次源数据检查还发现最近 100 个会话的消息 metadata 合计约 107.75 MiB，
+`listConversations()` 会读入这些会话的全部消息详情。它是 Renderer 大对象加载的明确
+检查方向，不是堆快照已经证明的泄漏。进程复用不能代替历史按需加载的独立性能工作。
+
+### 2.2 调研基线的源码归属
+
+| 位置 | 已确认行为 | 修复含义 |
+| --- | --- | --- |
+| [SelectedRuntimeManager](../../../src/main/agent/selected-runtime-manager.ts) | 缓存键包含原始 selection 与 execution-space identity；默认 8 个缓存、16 个保留实例；只在容量压力下淘汰 | 轻量工作区适配器和重型进程不能继续按同一键、同一数量计费 |
+| [AgentRuntimeController](../../../src/main/agent/runtime-controller.ts) | `canRetire` 同时要求无请求、无 owned conversation；普通完成不移除会话所有权 | 不能把“已完成请求”和“已释放原生会话”混为一谈 |
+| [本机 OpenCode](../../../src/main/agent/opencode-runtime.ts) | 对象私有 Server/client/初始化 Promise；已有多会话映射；多个入口使用固定 `defaultWorkspace` | 仅删除 manager 的 workspace 键会把后续操作送进错误目录 |
+| [DeepSeek Runtime](../../../src/main/agent/deepseek-harness-runtime.ts) | 每对象一个 Utility Host；`getStatus()` 调用 `getState()` 启动 Host | manager 的临时状态实例会额外启动、探测并销毁 Host |
+| [Harness Host](../../../src/main/deepseek-harness-host.ts)、[控制面](../../../src/main/agent/goodbuddy-harness-control-plane.ts) | 根 Provider 有 cwd 默认值；控制面拒绝与 Host workspace 不同的 `newSession.cwd` | 限制主要在 GoodBuddy 创建入口，不是原生工具缺少会话 cwd |
+| [Continue Host Adapter](../../../src/main/agent/continue-host-adapter.ts) | 每次 run 启动临时 Host，最终 `/exit` 与进程树回收；准备结果已在 adapter 内缓存 | 不重复添加已有缓存；研究跨 adapter 重复准备，不直接共享活动 Host |
+| [直连模型](../../../src/main/agent/model-runtime.ts) | Main 内 HTTP；历史 Map 按 50 个会话限制，其他归属及工具资源依赖 release/dispose | 没有可合并的常驻模型子进程，按对象和资源检查 |
+| [远端 ACP](../../../src/main/agent/acp-remote-runtime.ts)、[Agent backend](../../../src/agent-daemon/runtime-acp-backend.ts) | 会话取得 binding/channel；backend 按 binding 拥有进程并拒绝跨 binding 复用 process identity | 必须拆开会话绑定与进程所有权 |
+| [Agent-owned Prompt](../../../src/agent-daemon/agent-owned-acp-prompt.ts)、[模型桥](../../../src/agent-daemon/model-bridge-helper.ts) | owner 一个 ACP connection/session/当前 operation；helper 固定模型和工作模式并串行 dispatch | 共享进程还要求会话路由、请求归属和取消隔离 |
+
+原始 selection 的 `auto`、默认 profile 和显式 profile 可能解析为同一有效配置。当前
+已确认“先按原始 selection 建键、后解析配置”的顺序，但尚未证明全部 UI 调用会实际生成
+等价重复实例。实施时从 [runtime-selection](../../../src/main/agent/runtime-selection.ts)
+和调用者验证，不把可能性记为另一次生产复现。
+
+### 2.3 锁定依赖与协议基础
+
+以仓库 lock 和本机已安装代码为准，不用最新网页替代锁定版本：
+
+| 依赖 | 基线 | 本次核验 |
+| --- | --- | --- |
+| OpenCode binary / SDK / plugin | 1.18.29 | HTTP API 接受 directory；ACP 接受多个 Session；`chat.headers` 有 sessionID |
+| ACP SDK | 0.25.1 | 一条连接关联多个 request ID，session notification/permission 带 sessionId |
+| DeepSeek Harness 包族 | 0.1.2-rc.1 | Agent factory/scoped context、Session header.cwd、真实文件与 Shell 工具 |
+| Cordis | 4.0.2 | Host 根组件与 Agent scope 的生命周期 |
+| Continue CLI | 1.5.47 | 实际受管补丁入口的单 `M.session`、QuizService 和权限状态 |
+
+已通过的三个隔离探针：
+
+1. **OpenCode HTTP**：调用当前生产 Server launcher，只有一次 spawn；同一个 SDK client
+   在两个目录创建四个 Session，读取各自的同名文件；删除一个 Session 后其余三个仍可取回。
+   没有调用 `Runtime.run`、模型或活动取消。
+2. **DeepSeek 工具**：当前 Host composition 和真实 Agent factory 在同一 Node 测试进程中
+   创建两个不同 cwd 的原生 Agent；并行执行真正的 `read`、`write` 和 PowerShell，
+   同名相对路径各自命中正确目录。另确认生产控制面仍拒绝第二工作区。没有启动 Electron
+   Utility、ACP Prompt 或模型流，不能据此声称生产多工作区已经可用。
+3. **原生 ACP 与模型归属**：Windows 上一个 1.18.29 `opencode acp` 进程、一条 ACP
+   connection、两个工作区 Session；分别选模型并发出并行 Prompt。本机确定性 HTTP
+   服务收到两次请求，原生 `chat.headers` 插件传来的 sessionID 分别匹配两个 Session。
+   不经过已发布 Agent backend/helper，没有测试真实工具、子代理、Linux 或断线恢复。
+
+三个探针真实模型调用均为 **0**，其中第三个有 **2 次本机合成提供方请求**。
+它们证明方案有原生基础，不替代后文的真实开发任务验收。
+
+特别纠正：`dsh-tool-fs` 将 `exec.agent.session.header.cwd` 传给 `fs.resolve`；
+`dsh-tool-bash` / `dsh-tool-pwsh` 也从 Session cwd 补全相对 workdir。
+`dsh-fs-local` / 本地 Shell 的根 cwd 是非会话调用的默认值，不是工作区隔离边界。
+不需要为这个已具备的能力新建一套“每工作区 Filesystem/Shell Provider”。
+
+官方背景资料：[OpenCode Server](https://opencode.ai/docs/server/)、
+[DeepSeek Harness](https://www.deepseek.com/harness/en/)、
+[Continue CLI](https://docs.continue.dev/cli/quickstart)。
+网页只用于核对产品入口；上述版本结论来自本地锁定代码和探针。
+
+## 3. 选定的结构
+
+### 3.1 两层对象，不建立通用进程池框架
+
+```text
+SelectedRuntimeManager
+  -> 轻量 Runtime adapter（有效 selection + execution space）
+       -> OpenCode process owner / Harness Host owner（兼容启动配置）
+            -> Session binding（execution space + conversationId）
+                 -> 当前 requestId / 原生 sessionId / 工作目录
+```
+
+- 保留 Main 已解析、校验的 execution space；adapter 每次将其显式交给共享 owner。
+  目录不是 Renderer 新增的任意启动参数，也不依赖 `process.chdir` 或进程级可变 cwd。
+- owner 持有唯一启动 Promise、client/connection、子进程、会话映射与关闭逻辑。两个
+  工作区同时冷启动时复用同一 Promise；一个调用者取消等待不取消其他使用者的启动。
+- adapter 的 `dispose` 只释放其引用，不直接关闭同组进程。会话映射由 owner 持有，避免
+  adapter 缓存淘汰丢掉原生续接。会话操作通过 binding 查目录，不从“当前选中项目”反查。
+- 设置重建沿用现有 reset/drain：新请求取得新配置，旧请求持有启动时的配置直到结算。
+  旧配置不再有在途使用者后释放旧绑定和进程，不能被历史会话 ID 永久钉住。
+  IPC 的 Runtime 设置、定制及能力更新不再主动取消全部请求或清空审批；controller
+  退役仍允许回答其已拥有的问题，但拒绝新请求和未知问题。
+  既有专家调度器仍在配置替换时取消专家子任务，团队父请求一起停止，防止用新模型
+  汇总旧 generation 的部分结果；不为该单独生命周期新建通用退役框架。
+- 8/16 的旧上限不应继续限制轻量项目 adapter 数量。若保留重型 owner 的容量保护，
+  应统计实际进程配置组及退役进程；不靠提高常数掩盖“一项目一进程”。
+- 只用进程内 Map、现有 controller、Promise 和普通定时器。会话历史仍以现有 SQLite /
+  Agent transcript 为准，不增加数据库表、迁移、持久化池快照、恢复日志或新配额。
+
+### 3.2 兼容键与上下文
+
+先通过 `applyRuntimeSelection` 等现有解析取得有效配置，再生成进程键；公开的 selection
+仍按现有语义保存，不能把“跟随默认”永久改写成某个显式 profile。
+
+| 范围 | 参与进程兼容性 | 留在会话/请求 |
+| --- | --- | --- |
+| 本机 OpenCode | 本机账号、二进制身份、有效模型连接/配置、启动环境、原生配置和插件组合 | 目录、conversation/session、Prompt、模式、当前权限和问答、请求级 MCP/知识 token |
+| 本机 Harness | Host/依赖版本、有效模型连接、图片能力、凭据引用、启动环境、启用插件及配置、启动 Skill 集合 | cwd、conversation/session、请求模式、Main Web/MCP 代理与用量归属 |
+| SSH OpenCode | 已有 Host/SSH 身份、Agent/Runtime installation identity、模型协议/连接、原生插件与启动配置 | Workspace、binding/session、operation、请求凭据和账本归属 |
+
+第一轮只合并同一有效模型连接及等价默认选择，不顺便支持任意不同模型连接共享：
+本机 OpenCode 配置使用固定 provider ID，Harness 用量也读取 Host config，跨 profile
+混用会引入另一项真实风险。不同 profile ID 不通过比较或序列化明文 API Key 来合并；
+密钥、Header 和插件配置更新通过现有设置失效路径使旧 owner 退役。
+
+调研基线的 SSH launch profile 把 workMode 写入原生启动配置。当前实现把工作模式
+放入 Session/当前 Prompt 路由，并设置原生 Session 工具规则，详见 §6.1；
+不能仅从兼容键中删除 workMode，也不向用户增加逐工具审批。
+
+## 4. 本机 OpenCode
+
+在 [opencode-runtime.ts](../../../src/main/agent/opencode-runtime.ts) 中抽出重型 owner，
+由 [create-runtime](../../../src/main/agent/create-runtime.ts) 的 Main composition 复用。
+保留工作区 adapter，逐项替换隐式 `options.defaultWorkspace`：
+
+1. create/get/delete Session、Prompt、历史初始化和压缩。
+2. 原生能力、工具、文件、Skill、MCP 查询的 directory。
+3. SSE 订阅、父子 Session 归属、待答 question 的 directory 与原生 ID。
+4. 权限更新、abort、问题答复/拒绝、MCP 临时注册及最终清理。
+
+会话绑定记录规范化绝对目录及原生 sessionId。同一 conversation 的请求继续串行，
+不同 conversation 并行，不引入覆盖整个 Server 的 Prompt 队列。
+现有 `snapshot: false` 必须保留。
+
+`mcpMutationTail` 目前属于 Runtime 对象；共享后同一原生目录的变更必须由同一 owner
+串行协调。注册名称、工具可见性、knowledge token 和清理仍按请求区分，不能用一个全局
+“当前 MCP 列表”覆盖同目录或跨目录的其他请求。探针未覆盖动态 MCP，这是实施验收项。
+
+第一轮保留现有按请求消费事件流和结束清理的方式，扩展目录及 Session 过滤即可。
+只有测出重复 SSE 消费是瓶颈时才另做 owner 级事件分发，不同时引入第二套事件总线。
+健康检查也读取 owner 的总 activeRequests，不能从一个空闲 adapter 判断整个 Server
+无任务后重启。异常退出使该 owner 的全部绑定失效，明确结算受影响请求，不重放已执行工具。
+
+## 5. DeepSeek Harness
+
+### 5.1 共享 Host 的最小改法
+
+- 将 `HarnessState`、Utility 启动 Promise、ACP connection 和事件路由提升到兼容配置
+  owner；Runtime adapter 保留请求工作区。
+- 每个新 Session 在 Main 解析 `realpath`，Host 校验绝对路径格式，
+  不再要求它等于 Host 启动工作区；`meta.cwd` 传入已有 Agent factory。
+  不依赖 Windows 大小写字符串猜测，也不取消路径存在性校验。
+- 保留一个本地 Filesystem、Subprocess 和平台 Shell Provider。Session 使用原生 cwd
+  路由；非 Session 的清单查询显式传入查询工作区，不能回退到第一个项目。
+- 保留 `setup(agentCtx)` 注册 Skill 和工具视图、每 Session 的 Ask definition 身份校验、
+  `sessionId + requestId` 准备及事件路由。Main 的 Web/MCP callback 按对应请求找
+  ToolProvider，不挂到某个最先创建的 adapter 上。
+- 第一轮保持同 profile、图片能力和插件组合共享，`queueUsage` 的模型配置因此仍一致。
+  给用量加跨会话断言，不借本次改造扩大跨模型 Host 能力。
+
+第三方插件的初始化可能依赖配置中的路径，不能因为内置工具支持 cwd 就声称所有插件
+天然多工作区安全。已启用插件组合属于进程配置；对实际产品支持的插件验证它使用
+Agent scope/Session cwd。若某插件确实有项目级初始化状态，将该状态显式作为不兼容
+启动配置，而不是默认给所有工作区各起一套 Provider 或禁止 Execute 工具。
+
+### 5.2 状态与取消
+
+被动 `getStatus` 改为已有 owner 快照或本地配置/Host 资源检查，不调用 `getState()`。
+没有启动过时不能写“握手已验证”，可表示资源已安装、尚未连接。
+状态检查不取得执行引用，也不清除或重置无会话 owner 的空闲计时；owner 已回收时，
+临时配置检查对象用完即释放，不将其登记成新的执行 owner。
+用户显式连接测试与原生清单可启动共享 owner；已有 owner 时只做有界控制检查，最终
+释放的是检查引用，不能在 `finally` dispose 掉仍服务其他会话的 Host。
+
+当前取消超时会 terminate 整个 Utility。共享后先取消并释放目标 Session 的 Agent /
+工具资源，不因一个请求结算较慢就杀掉仍健康服务其他 Session 的 Host。若真实控制面
+已失去响应，保留整个 Host 的有界终止，向受影响会话分别报告中断；不得把它说成
+“取消完全不影响其他任务”。同步插件卡死的进程级故障无法在同一 JS 进程中强行隔离，
+不为此新增通用恢复框架。普通长工具取消与整 Host 故障必须分开测试。
+
+## 6. SSH OpenCode 与 Agent
+
+本节定义当前源码的共享进程改造；当前已发布版本仍见
+[远程技术设计](../remote-host/technical-design.md)。不能删除或绕过其持久 binding、
+operation、transcript、ACK 和模型 dispatch 结果不确定性规则。
+
+### 6.1 连接与所有权
+
+将 `RuntimeAcpBackend` 的进程 owner 与 binding 分开：
+
+```text
+Agent 当前 Runtime installation + 兼容配置
+  -> 一个 process owner / 一条 ACP ClientSideConnection
+       -> sessionId -> binding -> 当前 operation / 原始 Prompt Promise
+```
+
+- 一条 stdio 流只交给一套 ACP decoder/connection，不能让几个 ClientSideConnection
+  竞争读取同一 stdout。消息和 permission 按 sessionId 分派给 binding 的当前 operation。
+- `AgentAcpConnection` 统一连接级握手、stdio 解码与退出监听，Prompt
+  生命周期仍留在 binding。同一 Session 串行，其他 Session 不等待它完成。
+- `closeAcpChannel`、取消和 release 只释放所属 binding/Session；最后一个 binding
+  离开后空闲 60 秒关闭进程。关闭 Session 时等待原生 `closeSession` 和原始 Prompt
+  结算，不等待排在 backend 控制队列后面的完成回调。只有原生控制面不响应时才有界
+  终止共享进程，并向其余请求报告中断，不声称这类故障可以逐 Session 隔离。
+- terminal 与物理进程状态分开：取消/失败的 Session 也可返回
+  `processTree: running`，表示进程继续服务其他 Session，不能伪报进程树为空。
+  Desktop 与 Agent 须使用配套的新契约；原始字节透传 binding 仍保留独占进程规则。
+- 共享 stdio owner 不使用单 Prompt 的累积输入和墙钟期限管理整进程；单次写入、
+  待写队列、输出背压继续有界，Prompt 输入与截止时间由 binding 管理。
+- SSH attach 仍不拥有活动 Prompt，断线不能取消或重发 Agent 已接受的工作。
+  历史 binding 的语义和原生 sessionId 保留；内存进程索引从当前安装和已有绑定得出，
+  不增加第二份持久进程恢复账本。
+- 同一 PID 的多个 binding 不代表同一权限或同一 operation。Host/installation identity
+  变化仍使用已有失效和退役规则，不把不同 Host、账号或 Runtime generation 合并。
+
+原生 `chat.message` 在模型请求前设置该 Session 的工具规则：Execute 允许工具；
+Ask 只开放原生只读、搜索和读取网络内容的工具，不开放 Shell/编辑/写入。
+OpenCode 1.18.29 的 ACP 不转发未注册子 Session 的权限请求，且原生子代理只继承父
+Session 的拒绝规则、不继承允许规则，因此子 Session 也按根 Prompt 设置规则，再
+保留原生子代理的显式限制。不能只把进程启动配置统一设成 `ask`，否则子代理工具会等待。
+
+### 6.2 模型桥归属
+
+选用锁定 OpenCode 已有的 **`chat.headers` 会话标记**，扩展当前受管
+[原生插件](../../../src/agent-daemon/opencode-subagent-plugin.ts)，不靠解析正文、猜测
+“当前最新 Prompt”或重写用户模型名来路由：
+
+1. 现有 Agent prepare/start 顺序在 helper 的进程内登记 Session/根 Session 与
+   binding、operation；插件从原生 sessionID 及已建立的父子关系取得精确归属。
+2. 在请求生成时固定所属 operation，将有界内部归属 Header 加到 loopback 模型请求。
+   归属必须覆盖原生子代理、自动/手动压缩，不能等 HTTP 到达后才绑定“目前活动的请求”。
+3. helper 检查它是否仍属于已登记的 Prompt，选择对应现有 Agent gateway/凭据上下文。
+   转发真实提供方前剥离内部 Header；不将其当作密钥或新增认证体系。
+4. 当前 helper 的单 socket/全局 dispatchBusy 改成按 operation 隔离的派发状态；
+   每个 operation 的现有轮次、顺序、字节和结果不确定性规则不变，取消 A 只关闭 A 的
+   提供方流，不关闭 B 的 socket、response 或待处理请求。
+5. Prompt 终态撤销对应映射及凭据；迟到请求不能借用下一轮 operation。保留
+   `snapshot: false`、关闭不消费的 title 请求和现有父子问题转交。
+
+普通 ACP 双 Session 的 Header 路由已有探针证据；子代理、压缩和终态竞态的实际
+验证结果以进度记录为准。若锁定版本某条实际调用路径不触发 hook，先定位那条原生路径，
+不得悄悄用全局串行 Prompt 或一个共享凭据槽冒充并行复用。
+内部桥字段如需调整，按既有受管 Agent/Runtime 版本配套交付，不移动发布标签，不给
+旧 Agent 宣称具备新行为。
+
+### 6.3 恢复与终态投影
+
+- Agent-owned 语义 Prompt 不一定产生原始 ACP journal 行。binary replay 仍校验现有
+  cursor 边界，但不存在 raw cursor 时不向 journal ACK 0；不虚建记录来满足 replay。
+- 同一 Agent 断线恢复后，保留的 Session binding 使用新 transport generation，
+  Runtime 可以同时接纳新 Session。安装身份已经更换的 attach-only 请求明确失败，
+  不能无限重试阻塞项目，也不能借此重发旧 Prompt。
+- Desktop 重启时，同项目的可恢复任务并行附加，不能等待一个待答 Prompt 结束才附加
+  第二个。live `question`/`question-resolved` 不属于有 provenance 的 transcript，
+  使用既有 pending Map，清除时只影响对应 request/question。
+- `conversations.list` 将恢复租约的 request/message ID 和待答列表投影为可选
+  `activeRequest`，Renderer 合并表单并使 Stop 指向真实请求。保存 header/消息时不保存
+  这个实时字段。回答/跳过成功由 Main 按 task → assistant message 归属更新既有
+  `answeredQuestions`，不写另一份问题日志，不覆盖流式正文、已完成或失败状态。
+- 明确确认的取消使用现有消息/任务终态事务一并结算，避免 Task cancelled 而消息仍
+  streaming。仍无法确认的 Stop 保持可恢复；连接中断本身不是已取消或已失败的证据。
+
+## 7. Continue、直连模型与相邻内存问题
+
+### 7.1 Continue
+
+保留每请求 Host 的隔离和最终清理。1.5.47 的单 Session、QuizService/权限队列意味着
+“一个 HTTP Server”不等于可安全承载多会话；这一例外有锁定源码依据。
+
+`getPreparedHost()` 已缓存本 adapter 的准备 Promise，磁盘也有按内容确认的补丁产物。
+先分别测量读取/哈希/补丁准备、Utility 启动、HTTP ready、首个提供方请求和退出耗时。
+若确认跨 adapter 重复准备明显，再将只读准备结果与启动 Promise 按已验证的 CLI
+identity/补丁版本放到 Main composition 复用；失败仍允许重试。不得复用临时 config、
+token、global dir、活动 Session 或权限/问题队列。设置替换及窗口状态刷新也纳入测量。
+
+不在本次给 Continue 加多 Session 补丁或常驻池。将来只有锁定版本真正支持多 Session
+且生产桥验证通过，才替换这一实现。
+
+### 7.2 直连模型及历史详情
+
+- 不新增模型 Utility 或进程池。检查 `conversations`、`knownConversationIds`、
+  summary、ToolProvider 与 DirectModelProcessService 的实际引用与 release 调用链。
+- 活动请求、会话可续读的有界输出和数据库历史是不同资源。请求结束回收临时闭包/
+  callback；会话释放才结束其可续读输出和工具资源，不在工具刚完成时删掉用户可查看结果。
+- 当前 50 个会话的 history 限制不是字节上限。先采堆与 retained size，再决定可从
+  SQLite 重建的历史缓存是否使用字节约束和 LRU，不能先增加一套持久历史副本。
+- Renderer 最近 100 个会话整包 metadata 加载另做列表摘要、当前会话分页、展开后取
+  详情的性能改造；本方案只记录依赖，不将这一尚未设计完成的 UI 改造算进进程修复交付。
+  必须保持完整历史、搜索、重新打开和当前活动事件可用。
+- 旧 Runtime 磁盘缓存可单独评估版本清理策略，不在本次研究或进程 idle 时删除安装、
+  用户工作区、数据库、备份或历史。
+
+## 8. 内部实施顺序
+
+| 阶段 | 具体工作 | 必须产出的证据 |
+| --- | --- | --- |
+| P0 | 固化本次原生探针为聚焦回归；补有效 selection/进程计数和状态启动计数 | 修复前能复现重复启动，失败原因不依赖真实用户配置 |
+| P1 | Main composition、兼容键、owner 与 adapter 生命周期；本机 OpenCode 全入口目录化 | 真实 UI 两项目四会话同一 Server，文件/工具/问答/取消不串线 |
+| P2 | DeepSeek 共享 Utility、会话 cwd、被动状态、请求级代理及取消收敛 | 实际 Utility/ACP 两项目四会话，原生工具与插件验证，状态刷新无额外 Host |
+| P3 | Agent process/session owner、ACP 单连接路由、Header 模型桥、权限和终态清理 | 开发中的真实 Linux x64 Host，含多会话工具、断线/重连和结果不确定性 |
+| P4 | 全 Runtime 资源回归；Continue 冷启动分解与有证据的准备复用；直连对象释放检查 | 相同输入的前后进程/内存/CPU/磁盘/延迟报告；没有残留测试进程 |
+
+这是依赖顺序，不是发布一半实现的许可。涉及的正常生产 UI 路径、远端专用修复和下节
+验收全部完成后，才能称为 Runtime 复用修复。Continue 测量若没有显示重复准备成本，
+明确记录不改；不要为凑齐阶段增加代码。历史 UI 分页是后续独立工作。
+
+## 9. 验收与性能比较
+
+### 9.1 必测场景
+
+| 编号 | 对应需求 | 场景与通过条件 |
+| --- | --- | --- |
+| V1 | FR-RR1、FR-RR2 | 全新 profile 仅查看状态、切换设置，OpenCode/DSH 重型启动次数为 0；已有 Host 时刷新不新建；清单与首个真实请求并发只有一次初始化 |
+| V2 | FR-RR1、FR-RR3 | 同一有效模型连接，两个独立项目各两会话同时自然开发，OpenCode/DSH 各一重型进程；各项目同名不同内容文件、命令 cwd、Git/测试结果都正确 |
+| V3 | FR-RR3 | 第二轮复用同一批会话；Ask/Execute 混合，Ask 写入被边界拒绝，Execute 不增审批；Skill、MCP、图片能力、用量和业务问答不串归属 |
+| V4 | FR-RR3、FR-RR4 | 一会话取消真实长工具/子代理时另外三会话完成并通过独立项目测试；分别检查请求 abort、SSE、问题映射和工具句柄释放 |
+| V5 | FR-RR4 | 关闭面板不取消工作；释放一个会话不关闭共享进程；无会话 owner 空闲后退出；App 退出后本机受管进程无残留，远端按已有 detach 规则保留 Agent-owned 工作 |
+| V6 | FR-RR1、FR-RR4 | 等价默认/显式选择复用；不同实际连接/插件配置不串用；配置更新期间旧请求完成，旧 generation 不永久积累；超过八个项目不因轻量 adapter 报重型容量满 |
+| V7 | FR-RR5 | 当前源码 Desktop → SSH → 当前开发 Agent → 原生 Runtime，两个项目/四会话；断线、重连、取消、重复 ACK/事件、迟到模型请求不重复调用或跨 operation 归账 |
+| V8 | FR-RR6 | Continue 并发请求仍各自正确清理；直连 HTTP 不生出额外模型进程；会话 release 后工具/分页输出资源释放；性能采样不靠删除历史或禁用工具达标 |
+
+V2/V4 必须是正常开发任务，模型可自然调用读写、Shell、测试和已支持的原生子代理；
+不是要求模型“不用工具”后回复一行。验证产出应用本身可运行、独立测试通过，模型口头
+说完成不算完成。每个 Runtime 只验证它已经支持的能力，不伪造 DSH/Continue 子代理。
+
+### 9.2 采样口径
+
+- 使用同一源码变更前后、同一机器、隔离 profile 与等规模历史副本；不改写用户运行库。
+  覆盖至少三次冷启动、五次热请求，以及三轮多项目任务和至少十分钟**确无新任务**的
+  空闲观察。分别记录中位数、范围与实际样本数，不从一次采样推断泄漏已消失。
+- 记录 Main、Renderer、Runtime 和工具子进程的 Private Commit、工作集/RSS、堆、
+  CPU、PID/启动次数、会话数、活动请求、SSE/ACP 订阅与残留句柄。Windows 工作集求和
+  会重复计算共享页，Private Commit 也不等于独占物理 RAM。
+- 同时报首轮准备、HTTP/ACP ready、首个模型请求、首次可见输出和总耗时。降低进程数
+  但把不同会话全局串行化，不能通过验收。
+- 数据库/WAL 字节与新增事件负载分开；进程 I/O 包含管道，不能称为物理磁盘读写。
+  继续检查未变化工具 upsert 为 0，旧历史读取/搜索/展开正常。
+- 核心硬指标是每个兼容组一重型进程、无额外被动启动、无跨会话错误、无结束后持续
+  增加的活动句柄、无重复提供方 dispatch。没有证据前不承诺“固定省 527 MiB”或
+  “整个 App 降到某个 RAM 上限”；原生 Session 仍保留时必须单独说明其常驻成本。
+
+### 9.3 源码与平台验证
+
+定向覆盖 manager/controller、各 Runtime lifecycle、Harness Host/control plane、
+ACP backend/owner、模型桥与插件，随后执行仓库要求的 `npm test`、`npm run typecheck`、
+`npm run lint`；生产构建改动在开发阶段按仓库规则构建验证。
+
+凡改变 Agent 或桌面到 Agent 路径，必须在开发期间按
+[真实 Host 验证规则](../remote-host/technical-design.md#agent-开发期间的真实-host-验证)
+使用当前源码的共享 Linux x64 Host 验证。Windows 原生 ACP 探针、旧版本 Host、mock、
+CI 和将来发布测试都不能替代它。Windows PowerShell 与 Linux Bash 的工作目录及取消
+分别验证；macOS/Linux arm64 生命周期与原生依赖由可用原生平台和 CI 补齐并明确报告。
+
+当前源码的真实 Linux Host、完整生产 UI 和最终整仓门禁结果均保留在进度记录；
+各次失败、修正、模型调用数及未测平台也一并记录，不以本机单测或原生协议探针
+替代完整产品验收。完整 App 性能样本保留用户要求的按钮位置调整，属于包含该 UI
+差异的实测对照，不是纯 Runtime 单变量实验。
@@ -0,0 +1,658 @@
+# 助手工作栏多终端页签 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台验证中 |
+| 版本 | 1.2 |
+| 日期 | 2026-09-10 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 界面归属 | [通用助手工作栏与执行空间](./prd.md) |
+| 相关设计 | [统一界面设计系统](../../../UI-DESIGN.md) |
+| 远程架构 | [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)、[SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md) |
+
+## 1. 文档职责
+
+本文细化助手工作栏中的以下行为：
+
+- 已打开应用以同级 Tab 呈现。
+- Tab 行始终提供“+”入口，用户按需打开应用。
+- 应用通过统一注册表分别声明单实例或多实例、默认打开、可关闭和排序策略。
+- “终端”作为首个多实例应用，自动使用当前项目的本机或托管 SSH 执行空间。
+- 本机与远程交互式终端的生命周期、状态、性能和验收要求。
+
+[通用助手工作栏与执行空间 PRD](./prd.md)
+继续负责工作栏的应用级位置、稳定能力目录、执行空间、范围绑定和总体产品边界。本文不重新
+定义 Host Key、凭据、Agent 安装、Ask/Execute Runtime 或项目持久化契约。
+
+## 2. 背景与当前问题
+
+当前工作栏在聊天页面右侧固定显示“任务中心、工作区、浏览器、成果”四个 Tab。用户不能：
+
+- 通过统一入口按需打开新的工作栏应用。
+- 按应用策略关闭并重新打开可关闭的工作栏应用。
+- 为支持多实例的应用创建第二个独立实例。
+- 在 GoodBuddy 内使用本机或远程 Host 的交互式 Shell。
+
+当前代码已经具备工作栏右侧回流、宽度调整、Tab 键盘导航、SSH Host Key 固定、加密凭据和
+SSH 连接池，但尚不存在工作栏应用实例模型、终端 IPC、终端 Session Manager 或终端模拟器。
+`node-pty` 当前只作为其他 Runtime 的间接依赖被打包，不能视为已经存在用户终端能力。
+
+## 3. 产品定义
+
+### 3.1 工作栏应用
+
+工作栏应用是可以在助手工作栏中打开的一个能力，例如任务中心、工作区、浏览器、成果或
+终端。每项应用通过统一注册表声明：
+
+- 稳定应用 ID。
+- 用户可见名称、图标和说明。
+- `single` 或 `multiple` 实例策略。
+- 是否默认打开、是否必须存在、是否可关闭和是否允许排序；这些属性彼此独立。
+- 创建实例时可用的默认上下文。
+- 当前不可用时的原因和修复入口。
+
+目录中的应用可发现性与实例是否已经打开相互独立。应用不可用时保留入口并说明原因，不以
+隐藏代替状态。
+
+注册表字段如下：
+
+| 字段 | 类型或允许值 | 含义 |
+| --- | --- | --- |
+| `id` | 稳定应用 ID | 关联图标、面板实现和持久化实例 |
+| `label` | 有界文本 | 默认 Tab 名称和目录名称 |
+| `icon` | 稳定图标 ID | 应用目录和 Tab 图标 |
+| `description` | 有界文本 | 目录说明和完整提示 |
+| `instancePolicy` | `single`、`multiple` | 同一应用允许一个还是多个实例 |
+| `defaultContext` | `application`、`current-project`、`current-conversation` | 创建实例时使用的默认范围，不代表实例随后必须跟随 |
+| `visibleAcrossContextSwitches` | boolean | 切换项目或会话后，已打开的 Tab 是否继续留在工作栏中 |
+| `defaultOpen` | boolean | 新布局是否创建默认实例 |
+| `required` | boolean | 布局加载时实例缺失是否必须补回 |
+| `closable` | boolean | 是否渲染关闭入口并接受关闭命令 |
+| `reorderable` | boolean | 是否允许用户改变 Tab 顺序 |
+| `availability` | `available` 或带原因和修复入口的 `unavailable` | 当前能力状态 |
+
+`defaultOpen`、`required` 和 `closable` 不互相推导。例如浏览器默认打开但不是必需实例；任务
+中心和工作区既默认打开又必须存在。`required` 不表示锁定顺序，顺序只由 `reorderable` 控制。
+
+当前五个应用的 `visibleAcrossContextSwitches` 均为 `true`。该属性记录应用目录的显示策略，
+不改变内容归属，也不授予其他会话的 MCP 访问权限；当前没有使用 `false` 的应用，尚未实现
+按上下文隐藏 Tab 的策略。
+
+浏览器在创建时绑定当前 Conversation；切换会话后仍保留原 Tab、选中状态和页面，导航操作
+继续使用原 `targetRef.conversationId`。此时新建浏览器才绑定新会话。默认或旧布局中尚未绑定
+的浏览器在首次使用时绑定活动会话，此后不再随会话切换改绑。终端同样保留创建时执行目标；
+任务中心、工作区和成果的内容继续跟随当前项目。
+
+### 3.2 工作栏 Tab 实例
+
+工作栏 Tab 是应用的一次打开实例。每个实例具有独立 ID、标题、应用类型和状态。Tab 行只
+显示已经打开的实例，不把全部能力同时渲染为 Tab。
+
+实例持久化字段只有 `id`、`appId`、`title` 和可选 `targetRef`。`targetRef` 使用公开引用：
+终端接受 `local` 或 `projectId`，浏览器接受 `conversationId`。Main 签发的 Browser Tab ID、
+Terminal Session ID、元素引用、凭据、路径和运行状态不进入工作栏布局。
+
+### 3.3 终端实例
+
+每个终端 Tab 对应一个独立交互式 Shell Session：
+
+- 本机终端由桌面 Main 进程管理本机 PTY。
+- 远程终端通过现有、已验证的 SSH Host 打开直接 SSH PTY。
+- 不同终端拥有独立 Shell、工作目录、输入、输出、尺寸和结束状态。
+- 创建后固定到当时选择的执行位置，切换项目不会迁移已经运行的终端。
+
+直接 SSH PTY 是用户操作的远程终端，不是连接期临时 GoodBuddy Agent，也不作为 Runtime
+stdio fallback。首期远程终端随 SSH Channel 结束，不提供跨 SSH 或桌面重启的进程恢复。
+
+## 4. 已确认的产品决策
+
+1. 工作栏 Tab 行末尾始终显示“+”按钮。
+2. “+”是普通命令按钮，不是一个 `tab`。
+3. 点击“+”在工作栏内容区显示“新建工作栏应用”选择页；取消后返回原活动 Tab。
+4. 选择应用后创建或激活实例，并关闭临时选择页。
+5. 单实例应用已经打开时，再次选择只聚焦已有实例，不创建重复 Tab。
+6. 多实例应用每次选择都创建新实例。
+7. 终端从首期开始就是多实例应用。
+8. 任务中心和工作区保持单实例、默认打开且不可关闭，分别固定在第一、第二位，`reorderable` 为 `false`。恢复旧布局时也按此规则修正顺序，其余 Tab 保持相对顺序。
+9. 浏览器注册为可关闭的多实例应用，升级后保留一个默认实例；成果保持单实例、默认打开且
+   可关闭。
+10. 用户关闭可关闭实例、切换或重排应用 Tab 后，“+”仍保持可见。
+11. 选择“终端”后不再显示第二层目标选择器。存在当前项目时直接绑定该项目，由 Main
+    根据项目执行空间自动打开本机或托管 SSH Shell；没有当前项目时打开本机 Home Shell。
+12. 远程首期使用直接 SSH PTY。SSH 断线后终端进入“已中断”，重新连接会创建一个新的
+    Shell，不伪装为恢复旧进程。
+13. 工作栏收起、切换主页面或切换 Tab 不终止终端；显式关闭终端 Tab 才终止对应 Shell。
+14. 应用重启不自动启动 Shell。恢复的终端 Tab 显示“会话已结束”，由用户显式重新连接。
+15. 终端是用户交互表面。Ask/Execute 继续约束 Agent Runtime，不把用户键盘操作误判为
+    Agent 工具调用；Agent、自动化和模型不得未经明确用户操作向终端注入输入。
+16. 工作栏继续按上位 PRD 提升为应用级容器；切换聊天、知识、魔法笔记或活动记录等主页面
+    不销毁 Tab 实例或终端 Session。
+
+## 5. 目标
+
+### 5.1 用户目标
+
+- 在工作栏中随时通过“+”发现并打开应用。
+- 同时打开多个本机或远程终端，并通过 Tab 快速切换。
+- 清楚知道每个终端运行在本机还是哪个远程 Host、当前目录和连接状态。
+- 在终端断线、退出或目标失效后获得准确状态和明确恢复操作。
+- 使用键盘完成打开应用、切换 Tab、操作终端和关闭实例。
+
+### 5.2 产品目标
+
+- 用一个可扩展的应用注册表统一单实例与多实例行为。
+- 把现有 Tab 迁移到统一实例模型，同时保持任务中心和工作区始终存在，并允许浏览器和终端
+  创建多个实例。
+- 建立真实的 Main/Preload/Renderer 终端生产链路，而不是用普通文本框模拟终端。
+- 复用现有 SSH Host Key、凭据和连接池，不建立第二套 Host 管理。
+- 保持终端输入输出有序、响应流畅、内存有界，并可靠清理本机和远程资源。
+
+## 6. 非目标
+
+- 不把 GoodBuddy 改造成完整 IDE。
+- 不唤起 Windows Terminal、Terminal.app 等外部终端窗口代替内嵌终端。
+- 不扫描或导入用户全部 SSH config、目录、Shell profile 或命令历史。
+- 不支持任意 `ProxyCommand`、端口转发或 SSH Agent Forwarding。
+- 不在打开远程终端时安装、更新或修复 GoodBuddy Agent。
+- 不把 Agent 工具调用、Runtime 日志或自动化输出伪装成用户终端。
+- 不允许 Renderer 直接访问 PTY、ChildProcess、SSH Client、凭据或 Node API。
+- 首期不提供终端协作、录制、云同步、Shell Session 复用、tmux 管理或跨设备恢复。
+- 首期不实现底部停靠和独立窗口；本文保留兼容模型，后续按工作栏总 PRD 扩展。
+- 首期不通过 GoodBuddy Agent 恢复远程终端，也不为终端复制 Runtime transcript、
+  `outcome_unknown` 或模型调用恢复协议。
+
+## 7. 信息架构与“+”交互
+
+### 7.1 Tab 行
+
+```text
+┌──────────────────────────────────────────────┐
+│ 任务中心 │ 工作区 │ 终端 1 │ 终端 2 │ + │
+├──────────────────────────────────────────────┤
+│ 当前活动实例内容                              │
+└──────────────────────────────────────────────┘
+```
+
+- 已打开实例位于一个语义化 `tablist` 中。
+- 每个实例使用独立 `tab` 和 `tabpanel`。
+- “+”固定在 Tab 行末尾，但位于 `tablist` 之外。
+- Tab 过多时实例区域单行横向滚动，“+”保持可见；不换行、不自动隐藏实例。
+- 终端 Tab 默认使用递增标题，例如“终端 1”“终端 2”；状态栏持续显示项目、Host、
+  工作目录和 Shell。用户可以重命名终端。
+- 当前 Tab 同时使用连续内容表面、选中边框、顶部强调线、图标和较高字重，不能只靠文字颜色。
+- Tab、关闭按钮和“+”入口沿用共享控件圆角；终端面板外框和终端顶部工具栏按钮使用直角，
+  保持紧凑的停靠式终端界面。
+- 只有可关闭实例渲染 Tab 关闭按钮。关闭按钮默认不争夺视觉注意力，仅在鼠标悬停或键盘
+  焦点进入对应 Tab 时出现；
+  粗指针或无悬停设备始终显示，出现与隐藏不得引发布局位移。
+
+### 7.2 新建应用选择页
+
+点击“+”后：
+
+1. 保留当前实例及其运行状态。
+2. 在工作栏内容区显示“新建工作栏应用”。
+3. 列出稳定应用目录，每项显示名称、说明、单/多实例提示和当前可用状态。
+4. 初始焦点进入第一个可用应用；Escape 或“取消”返回原活动实例和“+”按钮。
+5. 选择单实例应用时，若实例已存在，直接聚焦该 Tab；任务中心和工作区始终走此路径。
+6. 选择浏览器时创建绑定当前 Conversation 的新 Browser Tab；没有活动 Conversation 时创建
+   待选择目标的空实例。
+7. 选择终端时直接解析当前项目执行空间，创建新 Tab 并聚焦终端输入，不再要求用户
+   重复选择本机或远程目标。
+
+选择页是“+”触发的临时界面，不进入实例顺序，不持久化，也不占用一个普通 Tab。
+
+### 7.3 首期应用注册表
+
+| 应用 | 实例策略 | 默认上下文 | 默认打开 | 必须存在 | 可关闭 | 可排序 | 再次从“+”选择 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 任务中心 | `single` | 当前项目 | 是 | 是 | 否 | 否 | 聚焦已有 Tab |
+| 工作区 | `single` | 当前项目 | 是 | 是 | 否 | 否 | 聚焦已有 Tab |
+| 浏览器 | `multiple` | 当前 Conversation | 是，一个实例 | 否 | 是 | 是 | 每次创建新 Tab |
+| 成果 | `single` | 当前项目 | 是 | 否 | 是 | 是 | 聚焦已有 Tab |
+| 终端 | `multiple` | 当前项目 | 否 | 否 | 是 | 是 | 每次创建新 Tab |
+
+实例策略、默认状态和可关闭策略都是应用注册数据，不能分散硬编码在多个点击处理器中。
+
+新建浏览器使用独立编号标题，避开已有名称；关闭后再次新建也不产生重名。恢复布局保留已保存
+的标题。会话名称用于标识归属，不替代浏览器实例名称。新建页面为空白页，同会话 Cookie 共享
+不表示复用旧页面或导航历史。
+
+### 7.4 Tab 操作
+
+- 点击或使用方向键切换实例不会暂停或终止后台实例。
+- 支持左右方向键、Home、End 和 roving `tabindex`。
+- 任务中心和工作区没有关闭按钮，也不响应关闭快捷命令。
+- 关闭可关闭的非活动 Tab 后焦点保持在当前活动 Tab。
+- 关闭可关闭的活动 Tab 后激活右侧相邻实例；没有右侧实例时激活左侧实例。任务中心和工作区
+  始终存在，因此正常布局不会进入零实例空状态。
+- 关闭正在运行的终端需要确认“关闭终端将结束 Shell 及其子进程”；取消是初始焦点。
+- 已退出或已中断的终端可以直接关闭，不重复确认。
+
+## 8. 终端创建流程
+
+### 8.1 自动目标解析
+
+- 当前项目是本地项目时，创建目标为公开 Project ID，Main 从权威项目记录解析本机根目录。
+- 当前项目是托管 SSH 项目时，创建目标仍为公开 Project ID，Main 再解析项目 Host、
+  固定 Host Key、凭据和远端根目录。
+- 没有当前项目时使用本机目标和当前用户 Home。
+- Host 未验证、凭据不可用或不支持交互式 Shell 时，终端 Tab 就地显示失败原因和恢复入口，
+  不静默切换到本机或其他 Host。
+
+### 8.2 本机终端
+
+- 当前项目是本地项目时，默认工作目录为项目根目录。
+- 没有本地项目目标时，默认工作目录为当前用户 Home。
+- Windows 优先使用可用的 PowerShell 7，其次 Windows PowerShell，最后使用系统
+  `COMSPEC`。
+- macOS 和 Linux 优先使用当前用户有效的 `$SHELL`，不可用时使用平台常规 Shell fallback。
+- 首期自动选择默认 Shell，不提供任意可执行文件路径输入。
+- Main 只向 Shell 传递正常交互所需的筛选环境，不注入模型 API Key、GoodBuddy 内部
+  Token 或其他产品凭据。
+
+### 8.3 远程终端
+
+- 当前项目是托管 SSH 项目时，自动使用项目 Host 和远端项目根目录。
+- Main 复用现有 Host store、完整 Host Key 固定、认证方式和 SSH connection pool。
+- 远端通过 SSH PTY 打开账号的登录 Shell，并支持输入、ANSI 输出和窗口尺寸同步。
+- 活动终端持有专用 Channel lease，不得被连接池空闲回收。
+- 不把密码、私钥、认证头或 GoodBuddy 模型凭据发送给 Renderer 或写入终端环境。
+- Host 地址、用户、凭据或 Host Key generation 变化时，旧 Session 进入“已中断”，新建
+  Session 必须使用 Host store 中的当前身份。
+
+### 8.4 创建结果
+
+创建成功后：
+
+- 新 Tab 插入当前活动 Tab 右侧并立即激活。
+- 焦点进入终端输入区域。
+- 状态栏显示“本机”或 Host 名称、工作目录、Shell 和连接状态。
+- 终端尺寸使用内容区计算出的首个有效 `cols/rows`，不是固定默认值覆盖实际布局。
+
+创建失败时在终端 Tab 保留错误上下文并提供重试；不得留下不可回收 Session 或显示为已经连接。
+
+## 9. 终端交互与状态
+
+### 9.1 基础交互
+
+首期支持：
+
+- 真实 TTY 输入与 ANSI 输出。
+- 中文输入法、组合字符和常规键盘快捷键。
+- 复制、粘贴、全选、搜索、清屏和滚动。复制与粘贴通过桌面 Main 进程访问系统文本剪贴板，
+  不依赖 Renderer 的浏览器剪贴板权限。
+- 工作栏宽度或窗口尺寸变化后的 PTY resize。
+- 终端重命名。
+- 显式关闭、退出后重新打开和远程中断后重新连接。
+
+浏览器原生页面快捷键与终端按键冲突时，终端聚焦期间优先交给终端；应用级保留快捷键必须
+有明确规则和可访问说明。
+
+### 9.2 状态模型
+
+```ts
+type TerminalSessionState =
+  | 'starting'
+  | 'running'
+  | 'exited'
+  | 'interrupted'
+  | 'closing'
+  | 'failed'
+```
+
+- `starting`：正在创建本机 PTY 或 SSH Channel。
+- `running`：允许输入和 resize。
+- `exited`：Shell 正常或带退出码结束，显示退出码或信号。
+- `interrupted`：远程连接、Host identity 或桌面生命周期导致会话失效。
+- `closing`：已拒绝新输入，正在回收进程或 Channel。
+- `failed`：Session 未成功开始或发生不可恢复错误。
+
+高频输出不逐行进入 live region。只播报连接成功、连接失败、已中断和 Shell 已退出等重要
+状态变化。
+
+### 9.3 重新连接
+
+- 本机或远程 Session 结束后，“重新打开”在同一 Tab 中创建全新的 Shell Session。
+- 远程断线后的按钮文案为“重新连接并新建 Shell”，不能暗示恢复旧进程。
+- 新 Session 使用 Host store 和项目中的当前有效配置，不复用旧 Host identity。
+- 重新连接前清空旧终端画面，并保留可见说明“这是新的 Shell 会话”。
+
+## 10. 实例、Session 与持久化
+
+工作栏实例与运行 Session 分离：
+
+```ts
+type WorkbarAppDefinition = {
+  id: 'tasks' | 'workspace' | 'browser' | 'results' | 'terminal'
+  label: string
+  icon: WorkbarAppDefinition['id']
+  description: string
+  instancePolicy: 'single' | 'multiple'
+  defaultContext: 'application' | 'current-project' | 'current-conversation'
+  defaultOpen: boolean
+  required: boolean
+  closable: boolean
+  reorderable: boolean
+  availability:
+    | { state: 'available' }
+    | { state: 'unavailable'; reason: string; remedy: string }
+}
+
+type WorkbarTabInstance = {
+  id: string
+  appId: WorkbarAppDefinition['id']
+  title: string
+  targetRef?:
+    | { type: 'local' }
+    | { type: 'project'; projectId: string }
+    | { type: 'conversation'; conversationId: string }
+}
+
+type WorkbarLayoutPreferences = {
+  instances: WorkbarTabInstance[]
+  activeInstanceId: string | null
+  expanded: boolean
+  dock: 'right'
+  widthRatio: number
+  taskScope: 'current-project' | 'global' | 'all-projects'
+}
+```
+
+- 持久化工作栏打开状态、Tab 顺序、活动实例、应用 ID、自定义标题、公开目标引用和宽度比例。
+- 加载布局时根据 `required` 补回缺失实例，并拒绝重复的单实例应用；应用策略不写入实例
+  数据，避免持久化状态覆盖注册表。
+- `reorderable` 已进入共享契约；当前 Tab 壳层尚未提供拖放或键盘重排，不能把声明属性视为
+  已完成的排序功能。
+- 不持久化终端正文、未执行输入、凭据、环境变量、PTY PID、SSH Channel 或派生 Host
+  identity。
+- Main 创建终端后返回新的不透明 Session ID；Renderer 不能选择 PID 或 Channel。
+- 应用重启恢复终端 Tab 描述，但状态为“会话已结束”，不自动建立 SSH 连接或启动本机
+  Shell。
+- 运行期间切换项目不会改变已经创建的终端目标。用户需要新目标时通过“+”创建新终端。
+
+## 11. 生命周期与关闭语义
+
+| 用户或系统动作 | Tab | Shell Session |
+| --- | --- | --- |
+| 切换 Tab | 保留 | 继续运行 |
+| 收起工作栏 | 保留 | 继续运行，停止非必要高频 UI 工作 |
+| 切换主页面 | 保留 | 继续运行 |
+| 切换项目 | 保留并显示原目标 | 继续在原目标运行 |
+| 关闭运行中的终端 Tab 并确认 | 删除 | 结束 Shell 和子进程 |
+| Shell 自行退出 | 保留 | 标记 `exited` |
+| SSH 断线 | 保留 | 标记 `interrupted` |
+| 删除或修改目标 Host | 保留 | 关闭旧 Channel 并标记 `interrupted` |
+| Renderer 销毁或应用退出 | 下次恢复描述 | 在总关闭截止时间内回收 |
+
+关闭操作必须安全处理竞态。Main 停止接受新输入，关闭 stdin/Channel，先正常结束，再在既有
+应用关闭截止时间内升级清理；一个卡死终端不能无限阻塞应用退出。关闭后的迟到 ACK 视为已
+完成，input、resize 或重复 close 返回 Session 不存在，不操作其他 Session。
+
+## 12. 技术生产路径
+
+### 12.1 Shared
+
+新增独立终端契约，至少覆盖：
+
+- `create`：目标引用、初始 `cols/rows`。
+- `write`：Session ID 和有界输入。
+- `resize`：Session ID、`cols/rows`。
+- `close`：Session ID。
+- `snapshot`：目标、状态、Shell、目录和终态。
+- `event`：带 Session ID 和单调序号的输出、状态、退出与错误事件。
+
+所有 Schema 使用 Zod 严格校验，并限制 ID、标题、输入、尺寸、事件块、会话数和缓冲字节。
+
+### 12.2 Main
+
+新增统一 `TerminalSessionManager`：
+
+- Session 按所属 `webContents` 和不透明 ID 隔离。
+- 将现有间接 `node-pty` 提升为 GoodBuddy 直接生产依赖，并用于启动平台 Shell。
+- 远程使用现有 `SshConnectionPool` 打开交互式 PTY Channel。
+- 统一处理 write、resize、close、exit、连接中断和应用退出。
+- 终端输出只发送给所属窗口。
+- 复用现有子进程树终止思路，但针对 PTY 验证 Windows 与 POSIX 的实际回收行为。
+
+### 12.3 Preload 与 IPC
+
+- `DesktopApi` 只暴露显式 `terminal.create/write/resize/close/getSnapshot/onEvent`。
+- Main Handler 对每个调用执行可信 sender 检查和共享 Schema parse。
+- Preload 管理事件订阅释放，不暴露 `ipcRenderer`、PTY、SSH Client 或 Node API。
+
+### 12.4 Renderer
+
+- 使用 `@xterm/xterm` 6 和官方 fit/search addon 处理 ANSI、光标、选择、IME、搜索、
+  滚动和可访问输入，不自行实现终端转义状态机。
+- 终端首次打开时按需加载；支持 WebGL2 时使用官方 WebGL renderer，初始化失败或 Context
+  丢失时释放 WebGL addon 并回退到 xterm 默认 renderer。
+- xterm 使用解析后的跨平台系统等宽字体栈，不能把未解析的 CSS `var(...)` 交给 Canvas。
+- Tab 壳层只管理实例与焦点，不持有 PTY 或 SSH 对象。
+- `ResizeObserver` 只在有效非零布局后发送去重后的 `cols/rows`。
+- 组件卸载时退订画面事件；只有显式关闭终端才调用 Session close。
+- 终端样式复用全局语义颜色、边框、焦点和字体令牌，不创建另一套工作台设计系统。
+
+### 12.5 输出顺序与背压
+
+- 输出按 Session 分区并携带单调序号。
+- Main 合并小块输出，限制单事件大小、待发送条目和总字节。
+- Renderer 确认已经消费的序号；慢消费者达到上限时暂停 PTY/SSH stream，消费后恢复。
+- 不通过丢弃中间输出维持界面响应，因为丢失字节会破坏终端状态。
+- Renderer 只保留有界滚动历史；清屏不改变 Main Session 生命周期。
+
+## 13. 权限与边界
+
+- 用户终端以当前本机账号或所选 SSH 账号的正常权限运行，不增加额外虚构的 trust tier。
+- Ask/Execute 是 Agent Runtime 模式，不自动改变用户直接操作终端的 OS 权限。
+- UI 必须持续将其标注为“用户终端”，避免被理解为 Ask Runtime 的只读输出。
+- Agent、模型、监督器和自动化不能调用终端 write，也不能把指令注入已有 Session。
+- 终端输出不会自动进入对话上下文、模型 Prompt、成果或活动记录。
+- Renderer 只能引用项目和 Session 的公开 ID；Main 从权威 store 解析目录、Host、凭据和
+  当前 Host identity。
+- 不接受 Renderer 提交任意 Shell 可执行路径、SSH 命令、PID、环境变量集合或原始凭据。
+- 保持 Electron `contextIsolation`、sandbox 和禁用 Renderer Node integration。
+
+## 14. 错误与反馈
+
+- 创建失败、断线、Shell 退出和目标失效保留在终端面板，提供就地重试。
+- 不与全局通知重复显示同一终端错误。
+- 非局部错误，例如无法保存工作栏布局，可以进入应用通知。
+- 错误文案说明发生了什么、当前 Shell 是否仍在运行、用户可以做什么。
+- Host Key 变化沿用现有 Host 管理流程；终端只显示“主机身份已变化，请重新验证”，不在
+  终端内复制凭据或 Host Key 修改流程。
+- 目标不可用时保留 Tab 名称和目标，不静默切换到本机或其他 Host。
+
+## 15. 性能与资源要求
+
+- 工作栏切换和终端输入在正常负载下保持即时反馈，持续输出不能阻塞主界面导航。
+- 同一窗口的活动终端数量必须有明确上限；达到上限时阻止新建并说明先关闭不用的终端。
+- 每个 Session 的输出队列、Renderer 滚动历史和 IPC 单事件均有硬上限。
+- 工作栏不可见时可以降低渲染刷新频率，但不能丢失终端协议字节或暂停 Shell 本身。
+- 应用退出复用现有总清理截止时间，不因终端新增无界等待。
+- 生产构建必须实际加载本机 PTY 原生模块；不能只验证文件存在。
+- 远程终端不能使 SSH connection pool 的空闲项、Channel 或监听器泄漏。
+
+具体数值在共享契约和性能测试中确定，以现有 IPC、窗口和关闭预算为上限，不在多个进程中
+维护不同常量。
+
+## 16. 无障碍与响应式
+
+- Tab 使用 `tablist/tab/tabpanel`；“+”使用带可访问名称“打开工作栏应用”的普通按钮。
+- 应用选择页使用可键盘操作的列表或菜单语义，不使用 `SegmentedControl`；终端没有重复的
+  目标选择页。
+- 每个终端 Tab 的可访问名称包含自定义名称或位置，多个终端不能都只读作“终端”。
+- Tab 关闭后焦点移动到确定的相邻 Tab；取消创建后焦点返回“+”。
+- 工作栏收起后焦点返回唯一工作栏开关，不增加焦点陷阱或遮罩。
+- 终端高频输出不逐行播报；只播报连接、退出、失败和中断。
+- 200% 文字缩放时，目标、Shell、目录、状态和关闭操作仍可访问。
+- Tab 单行横向滚动，终端内容随工作栏尺寸变化并同步 PTY，不把 Tab 换成下拉框。
+- 深色和浅色主题都使用设计系统语义令牌，并保持终端文本、选择和光标可辨。
+
+## 17. 实施顺序与多代理工作包
+
+功能必须以完整的本机和远程用户流程交付。以下是可并行的开发工作包，不表示可以发布只有
+Schema、假数据终端或不可用入口的中间产品。
+
+### 17.1 依赖顺序
+
+```text
+契约冻结
+  ├─ 工作栏实例壳层
+  ├─ 本机 PTY 后端
+  ├─ SSH PTY 后端
+  └─ 终端 Renderer
+          ↓
+单一集成负责人完成 Main/Preload/App 接线
+          ↓
+完整验证、真实 Host 验收与文档同步
+```
+
+### 17.2 文件所有权
+
+| 工作包 | 主要职责 | 建议文件所有权 | 不应修改 |
+| --- | --- | --- | --- |
+| 契约与注册表 | Workbar/Terminal Schema、状态、测试 | 新建 `src/shared/workbar-contracts.ts`、`terminal-contracts.ts` 及测试 | `App.tsx`、`ipc.ts`、Preload |
+| 工作栏壳层 | 动态实例 Tab、“+”、选择页、单/多实例和焦点 | 新建工作栏组件及其测试 | PTY、SSH、Main IPC |
+| 本机终端后端 | 本机 PTY、输入、resize、退出和进程树清理 | 新建 `src/main/terminal/` 本机文件及测试 | Renderer、远程 Agent |
+| SSH 终端后端 | SSH PTY、lease、resize、断线和 Channel 清理 | 新建 `src/main/terminal/` 远程文件及聚焦测试 | 工作栏 UI、Agent 协议 |
+| 终端 Renderer | 模拟器、IME、搜索、复制粘贴、状态栏和 resize | 新建终端组件、样式和测试 | Main、SSH、中心 IPC |
+| 集成 | 依赖、IPC channel、DesktopApi、Preload、Main 注册、`App` 接线与关闭顺序 | `package.json`、lock、`ipc-channels.ts`、`contracts.ts`、`preload/index.ts`、`main/ipc.ts`、`App.tsx` | 不重写各包已验收内部逻辑 |
+| 验收与文档 | E2E、跨平台构建检查、真实 Host、最终文档 | 测试与相关文档 | 不用假实现替换生产路径 |
+
+中心文件只能由集成负责人修改，避免多个代理同时编辑 `App.tsx`、`main/ipc.ts`、
+`shared/contracts.ts`、`preload/index.ts`、`package.json` 和 lockfile。
+
+### 17.3 并行开发门槛
+
+契约负责人先冻结：
+
+- 应用注册和实例策略。
+- Terminal request、snapshot、event 和 error code。
+- Session 所有权和关闭语义。
+- 输出序号、ACK 与容量常量。
+
+其他代理基于冻结契约工作。接口偏差由集成负责人统一修正，不由多个代理分别修改共享中心
+文件。
+
+## 18. 验收标准
+
+### 18.1 工作栏应用与实例
+
+- [ ] Tab 行末始终显示“+”；任务中心和工作区始终存在，因此正常布局不存在零实例状态。
+- [ ] 点击“+”显示稳定应用目录，取消后返回原实例并恢复焦点。
+- [ ] 选择已打开单实例应用只聚焦已有 Tab。
+- [x] 任务中心和工作区默认存在且不可关闭，不渲染关闭按钮，也不响应关闭快捷命令。
+- [x] 连续选择浏览器会创建页面、导航状态和元素引用相互独立的浏览器 Tab。
+- [x] 连续选择终端会创建多个互相独立的终端 Tab。
+- [ ] 关闭可关闭实例、切换和重排实例后，“+”仍保持可用。
+- [ ] Tab 溢出时单行横向滚动，不隐藏“+”或把 Tab 换成下拉框。
+- [x] 关闭可关闭的活动 Tab 后激活正确的相邻 Tab 并恢复焦点。
+- [x] 当前 Tab 的背景、边框、顶部指示和字重清晰可辨；关闭按钮仅在悬停、焦点或无悬停
+  设备上出现，且不引发布局位移。
+- [x] 升级后任务中心、工作区、一个浏览器实例和成果按默认布局打开；布局恢复会补回缺失的
+  任务中心与工作区。
+- [ ] 在所有主要页面都能打开工作栏；切换主要页面不会销毁 Tab 实例或终端 Session。
+
+### 18.2 本机终端
+
+- [x] 从“+ → 终端”直接打开当前本机项目的真实交互式 Shell，工作目录为项目根。
+- [ ] 没有项目时从用户 Home 打开本机 Shell。
+- [ ] `pwd` / `Get-Location`、交互输入、ANSI 颜色、中文 IME、复制和粘贴工作正常。
+- [ ] 调整工作栏和窗口尺寸会更新 PTY `cols/rows`，全屏 TTY 程序正确重绘。
+- [ ] 多个本机终端的输入、输出、目录和退出状态互不串线。
+- [ ] Shell 有活动子进程时关闭 Tab，确认后回收完整进程树；取消后 Session 继续运行。
+- [ ] 退出后的 Tab 显示退出码，并可在同一 Tab 显式创建新 Shell。
+
+### 18.3 远程终端
+
+- [ ] 从“+ → 终端”直接为当前托管 SSH 项目打开真实 SSH PTY。
+- [ ] 终端持续显示 Host、远端目录、Shell 和连接状态。
+- [ ] 使用现有固定 Host Key 和已存凭据，Renderer、日志和命令参数不出现凭据。
+- [ ] 输入、ANSI、中文、复制粘贴和 resize 在真实 Host 上工作正常。
+- [ ] 活动远程终端不会被 SSH connection pool 空闲回收。
+- [ ] SSH 断线立即标记“已中断”并拒绝继续输入，不显示为仍在运行。
+- [ ] “重新连接并新建 Shell”明确创建新 Session，不宣称恢复旧远端进程。
+- [ ] Host 删除、地址/用户/凭据或 Host Key generation 变化会中断旧 Session；新 Session
+  使用当前 Host identity。
+
+### 18.4 生命周期、性能和边界
+
+- [ ] 收起工作栏、切换主页面、切换 Tab 或切换项目不会终止已有终端。
+- [ ] 终端不会随项目切换静默迁移执行位置。
+- [ ] 应用重启只恢复终端 Tab 描述，不自动连接或启动 Shell。
+- [ ] 输出顺序在持续大输出下保持正确，Main 和 Renderer 内存保持有界，主界面仍可操作。
+- [ ] 慢 Renderer 触发暂停和恢复，不丢弃中间终端字节。
+- [ ] Renderer 不获得 raw PTY、ChildProcess、SSH Client、PID、环境变量或凭据。
+- [ ] Agent、模型和自动化不能向已有用户终端注入输入。
+- [ ] 窗口销毁和应用退出在既有关闭截止时间内回收本机进程、SSH Channel 和监听器。
+- [ ] 重复 close、迟到 input/resize 和退出竞态不会操作其他 Session 或导致进程泄漏。
+
+### 18.5 设计、无障碍和跨平台
+
+- [ ] 仅使用键盘可以打开应用、创建浏览器和终端、切换 Tab、关闭可关闭 Tab、复制、粘贴及
+  重新连接。
+- [ ] Tab、“+”、选择页和关闭确认使用正确语义并有可见焦点。
+- [ ] 终端输出不逐行进入 live region，关键状态变化可被辅助技术感知。
+- [ ] 浅色、深色、200% 文字缩放和窄窗口下可以完成核心流程。
+- [ ] Windows、macOS、Linux x64 和 Linux arm64 的正式构建实际启动本机 PTY。
+- [ ] 远程链路在共享 Linux x64 真实 Host 上完成创建、输入、resize、断线、重连、关闭和
+  应用退出验证；若 Host 不可达，远程终端不得标记为完成。
+
+## 19. 验证计划
+
+### 19.1 自动验证
+
+- 共享 Zod Schema 和边界值测试。
+- 单/多实例、默认打开、可关闭和排序策略，以及 Tab 顺序、关闭焦点和“+”选择页组件测试。
+- 任务中心与工作区缺失时的布局修复、关闭命令拒绝和焦点保持测试。
+- 浏览器多实例的页面隔离、Conversation 匹配和快捷入口去重测试。
+- 本机 PTY Session Manager 的输入、resize、退出、幂等关闭和进程树测试。
+- SSH PTY 的 Host identity、lease、断线、resize 和关闭测试。
+- Main trusted sender、Session 所有权、IPC 输入边界和事件路由测试。
+- Terminal Renderer 的 IME、键盘、ResizeObserver、订阅释放和状态测试。
+- `npm test`
+- `npm run typecheck`
+- `npm run lint`
+- `npm run build`
+
+### 19.2 真实路径验证
+
+- 在当前开发平台通过产品 UI 完成本机终端全流程。
+- 在共享 Linux x64 Host 通过现有 Host 配置完成远程终端全流程。
+- 真实运行需要 TTY 的程序，验证 ANSI、光标和 resize，不只运行非交互命令。
+- 持续输出并主动减慢 Renderer 消费，验证背压和内存上限。
+- 分别在本机和远程启动带子进程的命令，关闭 Tab 和应用后核对无 GoodBuddy 所属遗留资源。
+- 生产构建在各受支持平台实际加载 PTY 原生模块，不以单元测试或包内文件存在代替。
+
+### 19.3 当前开发验证记录
+
+2026-09-01 已通过生产 `SshConnectionPool` 和 `createSshTerminalSession` 在共享 Linux x64
+Host 完成直接 SSH PTY 验证：使用已有固定 Host Key 和测试凭据，以远端项目目录启动登录
+Shell，验证交互输入、ANSI、UTF-8 中文、`80×24` 到 `101×37` resize、连接销毁后进入
+`interrupted`、重新连接创建新 Shell，以及 Session close 和 connection pool dispose
+回收远端 Shell。验证只创建一个
+`$HOME/.goodbuddy/terminal-smoke-<UUID>` 临时目录，结束后已删除并确认无遗留 Shell 进程。
+
+同日使用最新生产构建完成工作栏视觉检查：活动 Tab 使用连续内容表面、顶部强调线和应用
+图标；关闭按钮默认不可见，悬停后以 overlay 显示且 Tab 宽度不变；横向滚动继续可用但不
+显示滚动条，“+”保持独立可见。
+
+本记录不替代尚未勾选的完整产品 UI、剪贴板、macOS、Linux arm64 和各平台本机 PTY 验收。
+
+本 PRD 不改变 Agent 协议，因此首期远程终端无需 Agent package 更新。若实现期间改为
+Agent-owned PTY，必须先修订本文的远程生命周期和恢复语义，并按 Agent 开发规则在共享
+Linux x64 Host 验证当前源码或候选包。
+
+## 20. 相关文档职责
+
+- [通用助手工作栏与执行空间 PRD](./prd.md)：
+  工作栏应用级位置、稳定能力目录、执行空间和总体范围。
+- 本文：持久“+”、应用实例策略、工作栏动态 Tab、自动项目目标、本机与直接 SSH 多终端。
+- [统一界面设计系统](../../../UI-DESIGN.md)：Tab、菜单、布局、主题、焦点和无障碍规则。
+- [SSH 远程主机与 GoodBuddy Agent 实现说明](../remote-host/technical-design.md)：
+  Host Key、凭据、连接池、Agent 和远程项目现状。
+- [SSH Host 远程环境准备与控制面直连设计](../remote-host/environment-provisioning-technical-design.md)：
+  Host 保存、环境准备和项目使用之间的职责。
@@ -0,0 +1,11 @@
+# 电脑控制
+
+电脑控制包含 GoodBuddy 对浏览器和客户端桌面能力的产品实现与平台适配状态。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [功能进度](./progress.md) | 当前已实现能力、缺陷修复、平台限制和验证状态 |
+
+当前只有进度文档；产品需求、功能逻辑、UI 和技术设计尚未从历史实现记录中独立整理。
@@ -6,8 +6,8 @@
 | --- | --- |
 | 文档类型 | 实施进度 |
 | 状态 | 持续更新 |
-| 版本 | 0.3 |
-| 日期 | 2026-08-18 |
+| 版本 | 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,14 @@ Linux x64 和 Linux arm64。

 ### 设置与安全边界

- 能力存储已迁移到版本 2。
- 内置浏览器已归入“直连模型”工具，与联网搜索并列，并明确说明不会控制
-  客户端已安装的浏览器；原有开关和配置 ID 保持不变，用户状态无需迁移。
- 用户通过内置浏览器总开关决定是否向直连模型提供工具；开启后可在 Execute
-  模式直接使用，不逐次询问。诊断位于同一分类。
+- 能力存储已迁移到版本 6。版本 2 至 5 中原有的浏览器启停状态会迁移到
+  `builtin-browser`，已有启用状态不丢失；默认分配给直连模型、GoodBuddy 管理的
+  OpenCode 和 Continue。
+- 内置浏览器位于“内置 MCP”，与知识库、笔记和 GoodBuddy 配置一样提供独立启停、
+  Runtime 分配和工具清单；DeepSeek Harness 持续显示为不支持。
+- 浏览器开关只控制 Agent 工具访问。关闭后，任何 Runtime 都不会获得浏览器工具，
+  但用户仍可在浏览器工作栏中手动前往、返回、刷新、停止加载、交互和关闭浏览器。
+  开启后，已分配 Runtime 可在 Execute 模式直接使用，不逐次询问。
 - 尚未实际参与浏览器执行的命名配置已从界面隐藏；底层旧数据和兼容接口继续
  保留，不删除用户已有记录。
 - “电脑控制”只显示实际操作客户端电脑的能力。能力启用、配置变更和本地
@@ -88,15 +92,28 @@ Linux x64 和 Linux arm64。

 ### P0：右侧没有浏览器实时画面，已修复

-浏览器窗口默认使用 `show: false`，但 BrowserService 现在从模型实际操作的同一
-会话捕获页面帧，并通过受限 IPC 发送状态、当前 URL 和约 220KB 的 JPEG 画面。右侧工作栏
-新增“浏览器”页签；活动对话启动浏览器时会自动打开该页签，并显示创建中、
-加载中、操作中、用户交互中、就绪、失败和已停止状态。用户可点击“交互”打开
-同一会话的子窗口辅助 Agent；交互时主窗口暂时禁用，关闭时先刷新最终画面再将
-浏览器窗口最小化，页面和会话继续保留。用户也可立即停止当前对话的浏览器会话。
+早期版本通过同一浏览器会话的 JPEG 帧提供预览。当前工作栏直接嵌入 Agent 操作的原生
+`WebContentsView`，不再自动截图或传输预览帧，也不再用独立交互窗口阻塞主界面。
+页面显示、标签页归属、失败重试和显式截图的当前规则统一见
+[浏览器多实例技术设计](../assistant-workbar/browser-tabs-technical-design.md)；
+该路径的最新验证证据见[工作栏进度](../assistant-workbar/progress.md)。

-当前实现按导航、快照、点击、输入、选择、返回和截图操作刷新画面，而不是创建
-第二个预览浏览器，因此显示内容与模型受控页面一致。
+### 已实现：浏览器工具栏
+
+浏览器 Tab 顶部已增加“返回、刷新/停止加载、地址输入、前往、交互、关闭浏览器”工具栏。
+它继续操作 Agent 在当前 Conversation 中使用的同一浏览器会话；用户导航会有意改变 Agent
+下一步看到的页面。前往、返回和刷新通过 `BrowserService` 与 Agent 浏览器操作串行执行，
+不会创建第二套 Renderer 导航路径。
+
+工具栏状态以浏览器提交后的权威 URL、是否加载中、能否返回和会话活动状态为准；地址输入
+在用户编辑期间保留本地草稿，不被状态刷新覆盖；提交未带 HTTP(S) 协议的裸域名时会自动添加
+`http://`。创建中、Agent 操作中和完整交互窗口期间禁用其余工具栏控件，但活动导航仍可用
+“停止加载”中断。停止加载只取消页面加载，不关闭浏览器，也不释放 Runtime 上下文；原“停止
+浏览器”会话生命周期操作已统一标为“关闭浏览器”，并在视觉和文案上与停止加载清楚区分。
+
+活动 Conversation 尚无浏览器会话时，可直接从地址栏输入 URL 并“前往”，通过浏览器组件
+可用性检查和同一 URL 策略创建会话。该手动路径不读取 Agent 浏览器开关。实现复用现有每
+Conversation 串行队列和有界状态，不引入恢复、版本化或第二套会话框架。

 ### P0：百度输入时元素引用失效，已修复

@@ -145,16 +162,26 @@ Linux x64 和 Linux arm64。

 ## 下一步顺序

-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
+单实例锁阻止了该实例继续运行；未关闭或附着用户正在使用的正式实例。
@@ -0,0 +1,11 @@
+# 持续学习
+
+持续学习定义 GoodBuddy 如何从运行结果、评估证据和人工反馈中形成可验证的改进闭环。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [持续学习与评估门 PRD](./prd.md) | 产品目标、学习边界、评估门和验收要求 |
+
+当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
@@ -7,12 +7,12 @@
 | 状态 | 设计中，远期能力 |
 | 版本 | 0.3 |
 | 日期 | 2026-08-19 |
-| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../experiments/parallel-experiments-prd.md)、[分区记忆 PRD](../memory/partitioned-memory-prd.md) |
+| 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md)、[并行实验 PRD](../parallel-experiments/prd.md)、[分区记忆 PRD](../memory/prd.md) |

 ## 1. 背景

-智能心跳可以生成摘要、后续任务和记忆候选，但这还不是完整学习。其长期“未来分区记忆”
-方向尚未设计，也不承担持续学习、模式挖掘或自动改进：
+智能心跳可以生成摘要、后续任务和记忆候选，但这还不是完整学习。它与分区记忆的协同尚未
+实施，也不承担持续学习、模式挖掘或自动改进：

 - 候选是否改善未来行为没有评估。
 - 一条反思是否会被检索和使用并不确定。
@@ -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)负责。
@@ -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 不进入可执行预览。
@@ -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`：通过。
@@ -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 到当前会话重新渲染的应用级集成路径。
@@ -0,0 +1,37 @@
+# 会话媒体生成
+
+实现状态：已完成。纳入 Desktop 0.13.5 / Agent 0.13.0 候选，尚未发布。日期：2026-09-15。实际验证范围单独见[进度记录](./progress.md)。
+
+用户添加图片模型后，可以开启“允许 AI 在会话中调用”。支持工具调用的聊天模型通过 GoodBuddy 生成图片、编辑上传图片和历史成果。切换聊天模型或 Agent Runtime 后仍可发起生成和编辑；已提交操作固定生成模型，结果保存到原会话。
+
+本目录负责普通 LLM 调用媒体模型的产品行为、调用入口和生命周期。现有直连图片协议及连续修改仍由[图片生成](../image-generation/README.md)维护；本设计不表示现有功能已改变。
+
+## 范围
+
+图片生成与编辑覆盖直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness，以及 GoodBuddy Agent 远程路径上的适用 Runtime。复用已有图片协议和各 Runtime 的内部工具或 MCP 注入，由 GoodBuddy 自动管理；用户无需创建 Skill、搭建 MCP server 或重复配置凭据。
+
+使用稳定工具 `generate_image` 完成生成与编辑。全局默认和本次指定模型足够，不新增会话级选择器或独立生成表单。无工具能力的聊天模型明确提示限制，可使用已有直连图片工作流。视频不在本设计范围；完整需求以[产品需求](./prd.md)为准。
+
+图片能力在现有内置 MCP 列表持续可见，Runtime 分配以只读复选框展示，由图片模型的会话调用设置自动管理；没有开启的模型时全部取消勾选，仍保留该行和模型设置入口。分配规则见[行为规则](./logic-design.md)，展示与说明见[界面设计](./ui-design.md)。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [产品需求](./prd.md) | 范围、需求编号与产品验收 |
+| [用户场景](./user-stories.md) | 用户操作及场景验收 |
+| [行为规则](./logic-design.md) | 选择优先级、切换规则、状态和失败处理 |
+| [界面设计](./ui-design.md) | 配置入口、会话操作、结果卡片和反馈 |
+| [技术设计](./technical-design.md) | 工具注入、Main 服务、存储与 Runtime 接入 |
+| [进度记录](./progress.md) | 当前代码事实、剩余工作与验证证据 |
+
+## 术语与依赖
+
+聊天模型负责理解请求、调用工具和组织回答；生成模型负责图片生成与编辑；Agent Runtime 承载聊天模型及工具执行。工具提供结构化调用入口，使用说明随工具提供，不要求用户管理 Skill。
+
+“生成操作”指一次图片生成或编辑及其结果记录，不自动创建任务中心的 Task，也不引入新的通用 Job 调度系统。领域边界遵循 [Task 与 Job 模型](../task-and-job/task-and-job-model.md)。
+
+- [模型连接](../model-connections/README.md)：连接、凭据、协议及请求定制。
+- [直连文本 Agent](../direct-model-agent/README.md)：文本工具循环与上下文。
+- [远程主机](../remote-host/README.md)：远程 Runtime 与桌面通信。
+- [统一界面规则](../../../UI-DESIGN.md)：控件、反馈和可访问性。
@@ -0,0 +1,78 @@
+# 行为规则
+
+状态：设计草案。此文是模型选择、切换与生成状态的权威定义，范围见[产品需求](./prd.md)。L-1 至 L-5 编号保留，以下规则替代原视频、会话级选择及通用查询恢复规则。
+
+## 能力与调用时点
+
+L-1（FR-1、FR-3、FR-7、FR-9；US-01、US-08、US-11、US-15 至 US-19）：自动生成与编辑要求图片连接允许会话调用、协议支持所需操作、聊天模型支持工具调用且当前请求处于 Execute。直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness 及 GoodBuddy Agent 远程适用 Runtime 均须接入同一图片能力，内部工具或 MCP 注入由 GoodBuddy 管理。
+
+允许调用的模型目录取自已保存且“允许 AI 在会话中调用”开启的图片模型配置。目录非空时，图片生成与编辑能力的全部支持 Runtime 分配自动勾选；目录为空时全部取消勾选。模型配置是唯一事实来源，不保存独立可变的能力启用或分配设置，用户不能操作分配复选框。
+
+| 配置或运行变化 | 分配与目录结果 |
+| --- | --- |
+| 首次开启或重新开启一个图片模型 | 自动勾选全部支持 Runtime，目录包含该模型 |
+| 关闭或删除一个模型，仍有其他开启模型 | 分配保持勾选，从目录移除该模型 |
+| 最后一个开启模型被关闭或删除，或从未开启任何模型 | 全部分配取消勾选，目录为空；能力行、说明和模型设置入口仍可见 |
+| Runtime 离线、聊天模型无工具能力、Ask、配置或执行错误 | 保持按模型开关推导的勾选和目录，另行显示调用限制或错误 |
+
+配置保存成功后同步刷新分配展示和允许模型目录；保存失败时保留最后已保存配置推导的状态。分配不表示运行就绪，也不保证每个图片模型支持编辑；协议及实际提交校验仍适用。
+
+请求开始和聊天模型、Runtime、配置切换后刷新可用能力；进程复用也须刷新。运行中的聊天回合保留原工具协议，Main 在实际提交前检查最新配置及工作模式，已关闭的连接不能接受新操作。无工具模型说明限制并提示已有直连图片工作流；Ask 不提交生成或编辑，不自动切换模式。Runtime 接入尚未完成属于实施缺口，不能作为减少支持范围的规则。
+
+## 模型和素材选择
+
+L-2（FR-2、FR-5；US-02、US-03、US-05、US-07、US-14、US-15）：先确定新建或编辑，再选择图片模型。
+
+| 操作 | 选择优先级，由高到低 |
+| --- | --- |
+| 新建图片 | 用户本次明确指定 > 全局默认 |
+| 编辑历史成果 | 用户本次明确指定 > 原成果模型 > 全局默认 |
+| 编辑上传图片（无来源模型） | 用户本次明确指定 > 全局默认 |
+
+只有较高优先级未设置时才查看下一项。选定模型被删除、关闭或不支持编辑时提示改选，不静默跳过。未设默认时提示本次指定或去设置默认后重新发送；名称歧义先澄清，LLM 不得编造模型 ID。不持久化会话级生成模型选择。
+
+显式附件或点选成果优先。“刚才那张”等指代仅在对象唯一时解析；多义指代先澄清。新建不相关图片不附带旧图。编辑能力不足或原图缺失时保留输入并提示，不把编辑自动降为文生图；用户可以明确要求按文字重新生成。已有直连图片路径的行为仍由[图片技术设计](../image-generation/technical-design.md)定义。
+
+## 切换规则
+
+L-3（FR-4；US-03 至 US-07、US-11、US-15）：Main 接受提交时固定原会话、触发消息、实际图片模型、当次连接参数、生成参数及素材引用。未提交请求在实际提交时解析默认值并校验显式选择；提交后不重选模型。图片请求由 Main 持有，独立于聊天 Runtime 生命周期。
+
+| 变化 | 未提交操作 | 已提交操作与成果 |
+| --- | --- | --- |
+| 切换聊天模型 | 新回合使用新模型及可用工具，无工具能力时说明限制 | 图片模型不变，操作独立继续 |
+| 切换本地或远程 Runtime | 新回合注入图片工具，可发起生成和编辑 | 不依赖旧进程，不向新进程补发旧工具响应，不重放生成 |
+| 更改全局默认或本次指定 | 新操作按 L-2 解析 | 保持提交时模型 |
+| 关闭或删除连接 | 拒绝新操作并提示改选 | 已发请求使用当次配置尽力完成 |
+| 更改地址、凭据或参数 | 新操作使用新配置 | 当前操作不混用新端点或凭据 |
+| 离开或重开会话 | 使用当前请求及全局配置 | 只更新原会话，历史成果仍可引用 |
+| 远程断连 | 未被 Main 接收的请求不能声称已提交 | 桌面仍运行时由 Main 继续管理已接收操作 |
+
+“停止回复”只结束文字回合；“取消生成”单独处理图片操作。切到 Ask 不撤销先前 Execute 已提交的操作，也不允许新增生成。运行时切换不自动唤起新的 LLM 请求。
+
+## 操作状态
+
+L-4（FR-6、FR-8；US-04、US-09、US-13）：复用现有操作与成果反馈，状态只表达实际知道的事实。没有上游百分比时显示状态及等待时间，不虚构进度。
+
+| 状态表达 | 条件与处理 |
+| --- | --- |
+| 进行中 | 正在发送或等待响应；仅有上游确认时才说明已接受生成 |
+| 保存中 | 已取得图片，Main 正在校验并保存 |
+| 已完成 | 图片及会话引用已保存，可重新读取 |
+| 取消中 | 已请求终止，尚无明确结果 |
+| 已停止等待／已取消 | 本地中断只说明“已停止等待，上游可能继续生成”；上游确认停止才说明“生成已取消” |
+| 失败 | 有明确的请求或保存失败原因，保留输入和错误上下文 |
+| 结果未确认 | 响应丢失、超时或重启后无法确认结果，不当作上游失败或取消 |
+
+同一操作的通知更新同一记录。取消后仍取得图片时，在原卡片保存并说明“取消未生效，已生成”，不恢复旧工具回合。超时不等于上游取消，不承诺退款。
+
+人工重新生成创建新操作，沿用原模型与输入并重新校验；改选模型时在新卡片显示实际选择。失败、结果未确认及保存失败均不自动重发收费请求，不设置独立保存重试入口。应用退出后不承诺继续本地执行，重启时未完成记录显示结果未确认，不建立跨重启查询恢复或通用恢复框架。
+
+## 历史成果
+
+L-5（FR-5、FR-8；US-07、US-12、US-14、US-15）：历史上下文提供成果引用、提示词及实际图片模型信息。只有具备视觉输入能力的聊天模型才接收适用的图片内容；无视觉模型可根据用户文字将原图引用交给编辑工具，但不能声称看过图片。上传图片和历史成果均使用已有可持久化素材引用。
+
+删除会话沿用已有确认流程，说明活动生成的取消及无法保证上游停止的情况；删除后的晚到结果不能重建会话。
+
+## 完整性与实施验证
+
+规则覆盖配置、新建、上传图与历史图编辑、模型与 Runtime 切换、Ask、无工具或无视觉模型、取消、失败、重启和会话归属。没有待定产品范围；各 Runtime 工具注入、远程往返及取消传播的具体接法需在实施时核验，按[技术设计](./technical-design.md)完成真实路径验收。视频、跨设备同步和应用退出后的本地执行不在范围内。
@@ -0,0 +1,37 @@
+# 产品需求
+
+状态：设计草案。本文描述目标行为，不作为现有能力说明。
+
+## 用户问题与范围
+
+用户希望在文字会话中直接提出“画一张海报”“把上传图片的背景改成蓝色”“继续修改刚才的图片”，由聊天助手调用已配置的图片模型。切换聊天模型或 Runtime 后，应能继续生成、引用和编辑图片。
+
+范围包括图片模型调用开关、全局默认与本次指定、文生图、已有协议支持的上传图片和历史图片编辑、成果保存、取消及状态反馈。支持直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness，以及 GoodBuddy Agent 远程路径上的适用 Runtime；各路径的生成、编辑和切换均属于验收范围。
+
+GoodBuddy 自动管理内部工具或 MCP 注入，复用模型连接与凭据。用户无需创建 Skill、搭建 MCP server 或填写第二套凭据。自动调用要求聊天模型支持工具调用；无工具能力时明确说明限制，用户可使用已有直连图片工作流。
+
+不包含视频生成、模型训练、自动采购服务、通用文本指令执行器、批量渲染平台或应用退出后继续本地执行的承诺。不新增图片协议、会话级生成模型选择器、独立生成表单或通用恢复框架，也不安排视频交付计划。
+
+## 功能需求
+
+保留 FR-1 至 FR-9 编号。原需求中的视频部分移出范围，FR-2 的会话级选择由全局默认和本次指定替代，FR-7 的新增显式入口由已有直连图片工作流替代；下表为当前定义。
+
+| 编号 | 要求 | 产品验收 |
+| --- | --- | --- |
+| FR-1 | 图片模型提供“允许 AI 在会话中调用”开关；新增和已有连接默认关闭，由用户主动开启；模型配置是图片能力启用与 Runtime 分配的唯一事实来源 | 至少一个模型开启时自动勾选全部支持 Runtime；全部关闭或删除时全部取消勾选；关闭或删除其中一个后若仍有开启模型，保持勾选并更新允许调用的模型目录；被关闭模型拒绝新操作，历史成果保留 |
+| FR-2 | 支持全局默认和本次明确指定；编辑可沿用原成果模型 | 按[选择规则](./logic-design.md)解析并显示实际模型；失效或有歧义时提示，不静默换服务 |
+| FR-3 | 在支持工具调用的聊天模型下，以自然语言生成和编辑图片 | 上传图片、历史图片及文生图均可经真实服务处理，保存后在原会话展示，活动记录可见 |
+| FR-4 | 支持聊天模型、Runtime 及生成模型切换 | 切换后可发起新的生成和编辑；已提交操作固定原模型和原会话，不重复提交 |
+| FR-5 | 支持上传素材、历史成果引用与连续编辑 | 重开会话及切换 Runtime 后可引用已保存原图；缺失素材或能力不足时保留输入并提示处理方式 |
+| FR-6 | 生成操作独立显示状态，支持取消及人工重新生成 | 离开会话不取消；保存成功才完成；不虚构进度，不自动重试收费请求；重启后未完成操作显示结果未确认 |
+| FR-7 | 遵循工作模式及模型能力边界 | Ask 不提交生成或编辑；无工具模型说明限制，可使用已有直连图片工作流，无需新增表单 |
+| FR-8 | 图片作为会话成果保存 | 可预览、导出和重新打开，来源模型可追溯；无视觉聊天模型只接收文字事实及引用，不编造观察 |
+| FR-9 | 本地及 GoodBuddy Agent 远程适用 Runtime 均支持图片工具；GoodBuddy 管理的图片生成与编辑能力及 Runtime 分配持续可见 | 分别完成真实生成、编辑、切换验收；分配复选框只读，不可手动切换；无开启模型时仍显示该行、未勾选状态、自动管理说明及模型设置入口；无独立能力启停、分配、移除或凭据编辑设置，用户无需维护 Skill 或 MCP server |
+
+分配表示模型配置允许的调用范围。聊天模型不支持工具、Ask、Runtime 离线、配置错误或执行失败均单独说明，不取消配置分配的勾选；不保存可独立修改的能力启用或 Runtime 分配状态。具体推导与刷新规则由 L-1 定义。
+
+## 产品验收
+
+以[用户场景](./user-stories.md)验收。各 Runtime 分别记录真实工具往返、生成、上传图编辑、历史图编辑及切换结果，不能用单一路径成功代替其他路径。配置检查或工具注入成功不等于生成成功，成果必须可在会话中重新打开。
+
+Runtime 接入细节和真实 Host 验证属于实施工作，未验证时如实记录未完成，不据此缩减 FR-9 的支持范围。
@@ -0,0 +1,83 @@
+# 进度记录
+
+## 2026-09-15
+
+### 真实图片请求与构建修复
+
+已使用现有 `gpt-image2` 连接（模型 `sub-gpt-image-2`）经生产 `ImageGenerationService` 发起两次真实图片请求：生成白底蓝色圆形，再上传该成果将圆形改成红色。两次均 HTTP 200，保存并重新解码成功，导出图片目视检查符合要求。请求数为 2，自动重试为 0，用户保存的配置未修改。请求尺寸为 1024×1024，供应商实际返回两张 1254×1254 PNG；未对结果重采样。证据保存在本机临时目录 `image-bounded-oiOPRi/`。此项验证 Main 图片服务与真实供应商，尚不替代真实聊天模型经各 Runtime 自行调用工具及完整界面切换验收。
+
+用户报告 Renderer 生产构建失败，定位到 `remote-image-tool-contracts.ts` 的 `node:crypto` 被共享契约间接引入浏览器。已将 MCP 名称哈希移至仅 Main 与 Agent 引用的 `remote-image-tool-node.ts`，共享消息编解码使用标准 `TextEncoder`/`TextDecoder`，无新增依赖或 polyfill。修复后 `npm run build`（含类型检查、Main、Preload、Renderer 构建）、`npm run lint` 通过，4 个相关测试文件共 89 项通过。此前仅运行类型检查和测试未发现这一构建问题，不能作为生产构建通过证据。
+
+### 实施与集成复验
+
+工作区已有模型会话调用开关、默认图片模型、配置派生的四种 Runtime 只读分配、Main 图片服务、上传与历史成果引用、操作状态及取消/重新生成 IPC。本地 Model、OpenCode、Continue、DeepSeek Harness 和受管远程 OpenCode 均已接入同一服务。操作复用消息 metadata 和成果存储，未新增任务表或独立分配设置。
+
+本轮修复远程保留会话在图片目录清空后未刷新 MCP，以及 Continue 准备自定义 MCP 失败时未释放本次图片工具令牌的问题。图片卡片更新保持原顺序；取消提示区分请求取消、停止等待和取消未生效后的结果保存。失败卡片提供模型设置与素材重选入口，无工具能力及 Ask 有相应提示。长名称和提示词自动换行，窄窗口及 200% 缩放下恢复按钮可换行。
+
+验证证据如下；此前小节中的超时和未验证记录仅代表各次检查时点：
+
+| 验证 | 结果与边界 |
+| --- | --- |
+| `npm test` | 364 个文件通过、9 个跳过；4,267 项通过、67 项跳过。后续恢复入口及样式修改另有 269 项定向测试通过，未再运行全量测试 |
+| `npm run typecheck`、`npm run lint` | 最后一次 Renderer 修改后通过 |
+| 真实 Linux Host | 最终 Agent 构建通过固定主机身份连接，使用实际远程 OpenCode；Ask、Execute 各 1 次真实文本请求均 HTTP 200 并完成，真实图片请求 0 次 |
+| Host 图片工具往返 | 最终运行含 7 次受控图片请求、15 次受控文本请求；生成、上传和历史图编辑、目录刷新、Ask 隐藏、并发会话归属、停止回复和断连后 Main 继续保存均通过。图片服务返回固定内联 PNG，不构成真实生图证明 |
+| Electron 界面 | 当前生产组件、样式、字体及双语文案，使用隔离 fixture API；初轮 94 项检查，恢复入口完成后 40 项检查通过。覆盖明暗主题、四种窗口尺寸、键盘导航及 200% 缩放；没有修改用户配置 |
+
+最终 Host 运行退出码为 0，残留自有进程为 0，隔离目录和上传文件已清理。此前受控复验另有 7 次图片请求和 15 次文本请求，因此本轮合计真实文本请求 2 次、真实图片请求 0 次、受控图片请求 14 次、受控文本请求 30 次。此前历史测试记录不计入此合计。
+
+本机临时证据位于 `C:/Users/jiang/AppData/Local/Temp/opencode/`：`image-review-full-tests-20260915.stdout.log`、`image-host-final-real-20260915.stdout.log`、`image-host-review-20260915.stdout.log` 及 `image-visual-0915/`。这些是开发检查产物，不随产品发布。
+
+当时尚未完成真实图片供应商生成与编辑；后续验证见上方记录。完整 Electron Main/Preload 路径中的自然语言触发及本地/远程双向切换验收仍待完成，FR-3、FR-9 尚未完成全部产品验收。
+
+隔离的真实图片验证脚本离线校验通过后，已按用户要求执行上述两次真实请求。该连接的会话调用仅在验证内存中启用，不修改保存配置。此前 `deai-writing` 文档扫描阻断项为 0，25 个候选经语境复核保留产品边界、状态限制和历史证据；`git diff --check` 通过。
+
+### Renderer 与设置复查
+
+本轮在已有未提交实现上修复图片操作卡片：状态事件原位更新，保留同一消息中多次生成的卡片顺序；取消提示区分正在请求取消、已停止等待和取消未生效但图片已保存。按钮通过 `aria-describedby` 关联就地操作错误，中英文提示同步更新。补充组件回归，并在现有 App 测试中检查离开原会话、结果晚到、返回及切换 Runtime 后继续修改时的卡片顺序。
+
+已检查模型设置、RuntimeSettingsStore、CapabilityService 和共享设置契约。现有实现从已保存模型开关派生四种 Runtime 的只读分配，不持久化独立分配；关闭或删除默认图片模型后保留失效默认。相关测试本轮通过，未改动这些生产契约。共享工具目录测试原先仅排除浏览器工具，现补充图片受管能力例外，确认 `generate_image` 保持写操作且不重复进入直连模型设置分组。
+
+验证记录：
+
+- `npx vitest run src/renderer/src/ImageOperationStatus.test.tsx src/renderer/src/App.test.tsx src/renderer/src/SettingsPanel.test.tsx src/main/runtime-settings-store.test.ts src/main/capabilities/capability-service.test.ts`：5 个文件、451 项通过。
+- 修正目录测试后，`npx vitest run src/shared/builtin-model-tools.test.ts src/renderer/src/ImageOperationStatus.test.tsx`：2 个文件、5 项通过。
+- `npm run typecheck`、`npm run lint` 通过。
+- `npm test` 在 120 秒上限被终止；期间报告的共享工具目录测试失败已单独修正并复验，未取得全量测试通过结论。
+- 未调用真实文本或图片服务，请求数均为 0；未执行 Electron 视觉验收或真实 Host 验证。本轮没有修改 `src/main/agent` 或 `src/agent-daemon`。各 Runtime 的真实生成、编辑、取消及切换验收仍待完成。
+
+### 此前文档修订记录
+
+本日补充：已按最新明确接受的要求修订 FR-1、FR-9、L-1、界面与技术设计，并新增 US-16 至 US-19。只读分配及模型配置派生规则见[行为规则](./logic-design.md)，受管行、说明与无障碍要求见[界面设计](./ui-design.md)。已读取根目录与 features 的 AGENTS、根 UI-DESIGN.md 及本目录七份现有文档，保留此前未提交修订；本次未修改目录外文件或应用代码，相关行为仍待实现与产品验收。
+
+本日更正：此前将其他 Runtime 自动调用排除在交付范围之外的记录不符合用户要求，现由本条替代。七份文档已统一为图片生成和编辑，支持范围及验收以[产品需求](./prd.md)和[用户场景](./user-stories.md)为准，不再保留分期规则。视频移出范围，US-10 保留编号并明确标注；其他被替代要求已记录编号变更。
+
+本次只修改本目录设计文档，未检查或改变应用实现。2026-09-14 记录仅为当日历史证据，不表示已重新验证。图片工具、Main 请求生命周期、各本地及 GoodBuddy Agent 远程适用 Runtime 的生成、编辑和切换均仍需实施与实际验证；具体注入及桥接核验属于实施工作，不缩减支持范围。
+
+本次文档验证：7 份文档的 38 个相对 Markdown 链接均可解析；一致性审阅覆盖模型配置唯一来源、只读分配、空目录保留行、运行状态独立及完整 Runtime 范围，未发现分期或缩减支持范围的现行规则。`deai-writing` 扫描阻断项为 0，25 个复核候选涉及设计状态、职责与必要行为限制，逐条按语境保留，并通读检查结构及前后规则。`git diff --check -- docs/features/conversation-media-generation` 通过；本次七份文件均已被 Git 跟踪，检查覆盖其工作区差异。该命令不覆盖未跟踪文件，不能沿用此前“目录未跟踪”的结论。未运行应用测试或真实生成请求，未声称功能完成或重新验证此前代码。
+
+## 2026-09-14（历史记录）
+
+以下保留当日检查与原设计记录，其中视频、保存重试等旧范围已被 2026-09-15 更正取代，不作为当前实施要求。
+
+当前阶段：设计草案已落盘，功能未实现。本次只新增设计文档与相关入口链接。
+
+代码与文档检查确认以下基础能力：
+
+| 事实 | 证据 |
+| --- | --- |
+| 已有直连图片生成、编辑及历史成果引用 | [图片技术设计](../image-generation/technical-design.md)、`src/main/agent/model-runtime.ts` |
+| 模型连接及 Main 凭据存储已存在 | `src/shared/contracts.ts`、`src/main/runtime-settings-store.ts` |
+| 已有 Skill 发现、Runtime 分配及工具分发 | `src/main/capabilities/capability-service.ts`、`src/main/agent/model-tool-provider.ts` |
+| 会话、消息 metadata 和成果已有 SQLite 存储 | `src/main/assistant/assistant-database.ts`、`src/shared/assistant-contracts.ts` |
+| 生图尚未成为普通 LLM 的内置生成工具 | 检查 `src/shared/builtin-model-tools.ts` 及工具分发路径 |
+| 本次检查未发现第一方视频生成协议实现 | 检查模型能力契约、Runtime 及现有功能文档；不据此推断外部 MCP 的能力 |
+
+剩余工作对应[技术设计实施顺序](./technical-design.md)：模型调用设置与选择、图片服务及会话入口、各 Runtime 接入、视频真实服务与成果交付均待实施。视频协议选择和远程工具桥接验证待完成。
+
+本次未修改应用代码，未运行应用测试或真实生成请求。文档验证记录如下：
+
+- 相对 Markdown 链接检查：7 份新文档及图片功能入口共 33 个链接，失效链接为 0。
+- `deai-writing` 扫描：阻断项为 0；人工复核保留设计状态、能力边界和禁止行为等必要限定，以及真实并列的验收项。
+- 独立一致性审阅发现“重新生成”与“重试保存”的操作身份表述不一致，已在 L-4 和 US-09 中统一：前者创建新操作，后者更新原操作。
+- `git diff --check` 通过。上述检查只验证文档，不构成功能验收。
@@ -0,0 +1,81 @@
+# 技术设计
+
+状态：工作区实现已接通，真实图片服务与完整产品验收未完成，证据见[进度记录](./progress.md)。内部契约实现 [FR-1 至 FR-9](./prd.md)及[行为规则 L-1 至 L-5](./logic-design.md)，不作为外部公开 API。
+
+## 调用结构
+
+```mermaid
+flowchart TD
+  Direct[直连文本 Model Runtime] --> Tool[generate_image]
+  Local[本地 OpenCode / Continue / DeepSeek Harness] --> Injection[GoodBuddy 管理的内部 MCP 注入]
+  Remote[GoodBuddy Agent 远程适用 Runtime] --> Bridge[现有 Agent 通信与工具桥接]
+  Bridge --> Injection
+  Injection --> Tool
+  Tool --> Main[Main 图片服务]
+  Main --> Profile[现有模型连接与凭据]
+  Main --> Adapter[现有图片生成与编辑协议]
+  Main --> Artifact[原会话操作记录与图片成果]
+```
+
+Main 持有图片请求、取消句柄及结果保存职责，生命周期独立于聊天 Runtime controller。切换或释放聊天进程不释放已提交图片操作。Renderer 的取消等操作经明确 preload/IPC 方法进入 Main，沿用共享契约和发送方校验。凭据只在 Main 解密，不写入工具说明、参数、输出或远程 Runtime 配置。
+
+`ImageGenerationService` 复用 `ModelAgentRuntime.generateImage` 的图片请求和校验，在 Main 保存操作及成果。工具路径按 L-2 明确区分新建和编辑，不自动将缺少素材或不支持的编辑降为文生图；已有直连图片路径保持原上下文规则。
+
+## 工具与注入
+
+稳定图片工具 `generate_image` 同时负责生成和编辑。当前输入为 `prompt`、可选 `modelProfileId`、`intent`（`create` 或 `edit`）、`sourceArtifactIds` 和可选 `quality`；类型及编辑素材约束由 `src/shared/image-generation-contracts.ts` 校验。每次请求沿用已有协议的单图生成和尺寸行为，没有新增数量或尺寸参数。原会话、触发消息和工具调用关联由运行上下文绑定，LLM 不能自由指定结果写入位置或任意文件路径。
+
+每个新回合提供可调用图片模型的脱敏 ID、名称及生成、编辑能力，模型切换、配置变化或进程复用时刷新。Main 提交前重新校验工作模式、连接开关、所需能力及素材。优先由工具描述承载模型选择、图片引用和结果使用说明，不把 Skill 管理作为依赖。
+
+直连文本 Model Runtime 使用内置工具契约及分发；外部 Runtime 复用内部 MCP 注入，由 GoodBuddy 自动注册、配置和管理生命周期，远程路径经现有 Agent 工具桥接调用同一服务。内置 MCP 列表中的图片行只展示这项受管能力，不代表直连 Model 也通过 MCP 调用。无需用户创建 Skill、另建 MCP server 或复制凭据，不按模型连接复制工具或 Skill。
+
+Main 从已保存图片 profile 的会话调用开关推导允许模型目录，并以目录是否非空推导全部支持 Runtime 的分配。Renderer 只读取派生分配；该受管行不接入通用 MCP 的启停、分配、删除或凭据编辑写入接口。模型配置保存后刷新展示及注入目录，进程复用和下一回合重新读取；运行中的回合及已提交操作继续遵循 L-1、L-3。配置错误、Runtime 在线状态、聊天模型工具能力与执行结果独立于派生分配，不因这些状态移除允许目录中的模型或取消勾选。
+
+不预建能力发现、查询或取消工具目录。只有实际 Runtime 协议要求独立发现、查询或取消交互，且现有工具描述、响应及 UI 操作不能满足时，才增加所需的最小适配，并记录协议依据；这些适配仍调用同一 Main 图片服务，不形成新的媒体平台。取消默认从会话卡片进入 Main。
+
+工具等待遵循现有超时约束，返回操作 ID、实际模型、真实状态及完成后的成果 ID，不把 Base64 塞入工具历史。原回合仍有效时通过合法工具响应返回结果；回合结束或 Runtime 切换后，Main 继续写原会话，下一回合读取操作摘要及成果引用，不补发旧响应、不自动唤起 LLM 或重发图片请求。
+
+## 配置与持久化
+
+| 对象 | 最小数据与职责 |
+| --- | --- |
+| 图片模型连接 | 复用 settings/profile，增加会话调用开关；现有连接缺少开关时解释为关闭 |
+| 图片能力与 Runtime 分配 | 从图片模型配置派生，只读展示；不新增独立可变的 capability enabled、assignment 设置或持久化副本 |
+| 全局偏好 | 默认图片 profile ID，复用应用设置；本次指定只属于请求，不新增会话级选择 |
+| 生成操作 | 优先使用现有消息 metadata，保存操作 ID、原会话/消息、工具关联、状态、实际模型 ID 与名称、提示词、有效参数、素材引用、时间、错误及成果 ID |
+| 素材与成果 | 复用附件和 artifact 持久化，保存上传图片、生成图片及编辑来源关系，不能只存于 Runtime 内存 |
+
+活动请求在 Main 内存持有提交时连接参数，持久记录不复制凭据。应用重启后未完成操作显示结果未确认，不建立跨重启查询恢复、凭据历史、通用恢复日志或自动重试。取消和晚到结果按 L-4 更新同一记录；人工重新生成使用新操作 ID。
+
+不新增独立任务表、视频字段或通用调度器，操作不自动成为 Task/Job。若实施涉及已发布数据，按[迁移规范](../../development/database-migrations.md)处理实际兼容需求，不预建迁移或恢复机制。
+
+Main 仅在图片和会话引用持久化成功后发布完成事件。素材必须是当前会话可访问的附件或成果，沿用已有项目和会话边界；删除会话后的晚到结果不重建会话。
+
+## 图片协议
+
+沿用[图片技术设计](../image-generation/technical-design.md)的已有生成、编辑协议及素材限制。接收并校验有界内联图片，不下载 Provider 返回的图片 URL。沿用现有成果存储限制，实施时核对编码开销与超限反馈，不以配置检查成功代替真实生成验收。视频协议、下载、播放及交付计划均不属于本设计。
+
+## Runtime 接入
+
+| 路径 | 设计接入点 | 必须完成的验证 |
+| --- | --- | --- |
+| 直连文本 Model Runtime | 现有内置工具契约及工具分发转入 Main 图片服务 | 自然语言生成、上传图编辑、历史图编辑及切换 |
+| 本地 OpenCode | 现有内部 MCP 注入转入同一服务 | 实际工具往返、能力刷新、生成编辑及切换 |
+| 本地 Continue | 现有内部 MCP 注入转入同一服务 | 实际工具往返、能力刷新、生成编辑及切换 |
+| 本地 DeepSeek Harness | 现有内部 MCP 注入转入同一服务 | 实际工具往返、能力刷新、生成编辑及切换 |
+| GoodBuddy Agent 远程适用 Runtime | 复用桌面与 Agent 通信及工具桥接，将请求绑定原会话，由 Main 调用图片模型 | 逐一验证实际支持的远程 Runtime，覆盖真实 Host 工具往返、生成编辑、本地与远程双向切换、断连及成果归属 |
+| 无工具能力的聊天模型 | 说明自动调用限制，可使用已有直连图片工作流 | 不解析普通文字伪装工具调用，不新增表单；Ask 不提交 |
+
+本地 OpenCode、Continue 和 DeepSeek Harness 经内部 MCP gateway 注入；直连 Model 使用内置工具分发。远程通过 `main-image-tool-session.ts`、Agent 协议和 `image-tool-mcp.ts` 回到同一 Main 服务。现有 GoodBuddy Agent 的受管远程 Runtime 为 OpenCode，项目校验和 Runtime 创建均沿用此范围；共享契约包含其他 Runtime 不表示存在其远程执行路径。保留会话在目录清空时也刷新 MCP，Continue 准备失败时释放本次分配的令牌。工具发现成功或 Skill 注入成功不能代替真实生成与编辑。
+
+Main 已接收的请求在桌面仍运行时独立于远程连接继续；未确认是否接收的请求不自动重放。聊天回合停止等待与用户取消图片是不同动作，须验证现有取消传播不会误杀 Main 图片请求。
+
+## 实施与验证
+
+实施工作包括配置与选择、Main 图片服务提取、各本地及远程 Runtime 工具适配、成果与状态 UI。它们共同完成本图片功能，不按 Runtime 划分交付范围。
+
+针对 L-1 至 L-5 验证选择优先级、失效配置、上传与历史素材、无视觉模型、Ask、会话归属、重复通知、取消及晚到结果。检查切换聊天模型、图片默认模型、本地与远程 Runtime 后的新生成和编辑，以及旧操作不重复提交。回归已有直连图片工作流。
+
+按 US-16 至 US-19 验证从零到一个开启模型、多个中关闭或删除一个、最后一个关闭或删除、重新开启，以及配置错误和 Runtime 离线时的派生分配、目录刷新、行可见性与只读交互。重开设置和应用后均从模型配置推导，不恢复独立分配值；辅助技术可读取标签、勾选状态和说明，键盘可到达模型设置导航。
+
+源代码实现后运行 `npm test`、`npm run typecheck`、`npm run lint`，并逐路径执行[用户场景](./user-stories.md)的真实产品验收，记录模型、Runtime、请求数量和结果。涉及 Agent 的实现按[远程主机验证要求](../remote-host/technical-design.md)在真实测试 Host 验证。实施和集成验证状态由[进度记录](./progress.md)维护。
@@ -0,0 +1,41 @@
+# 界面设计
+
+状态：工作区已有实现及 Electron 组件验收，完整应用验收见[进度记录](./progress.md)。遵循[统一界面设计](../../../UI-DESIGN.md)，实现 [FR-1 至 FR-9](./prd.md)，行为以[行为规则](./logic-design.md)为准。
+
+## 模型配置
+
+在现有图片模型连接表单提供“允许 AI 在会话中调用”。说明文字：“开启后，支持工具调用的聊天助手可使用此模型生成和编辑图片，编辑能力取决于图片协议。结果保存在发起请求的会话中。”复用共享 Switch，提供 `role="switch"`、键盘操作及可见焦点。
+
+开启后提供“设为默认生图模型”，列表显示可调用和默认标识。关闭或删除默认连接时提示默认选择不可用，保留失效选择供改选，不自动指定其他模型。用户无需创建 Skill、搭建 MCP server 或重复填写 API 凭据；内部注入由 GoodBuddy 管理，不作为配置步骤展示。
+
+## 能力与 Runtime 分配
+
+复用设置中心“MCP / 内置 MCP”的列表与分配布局，增加“图片生成与编辑”行，标记“内置 · 自动管理”。这是 GoodBuddy 管理能力的展示入口，直连 Model 通过内部工具调用，外部 Runtime 通过内部 MCP 接入；不显示为用户另行添加的 MCP 或 Skill，也不混入 Runtime 原生能力清单。
+
+该行按 L-1 展示直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness 及 GoodBuddy Agent 远程适用 Runtime 的只读分配复选框。此图片能力采用用户已接受的自动管理规则，不沿用其他内置 MCP 的手动启停、可调分配或 DeepSeek Harness“暂不支持”状态。没有开启模型时仍保留整行及全部未勾选项，不能因目录为空隐藏。
+
+持续显示说明“由图片模型的「允许 AI 在会话中调用」设置自动管理。”，并提供“前往图片模型设置”导航。该行不提供独立启用开关、保存分配、移除、编辑连接或凭据入口。运行就绪、无工具能力、配置或调用错误单独显示，不改变分配勾选。
+
+分配复用共享 Checkbox 的方形视觉和原生语义，以 `checked` 表示派生值并使用 `disabled` 禁止鼠标、标签点击或键盘切换；仅在共享控件已有受支持的只读实现时采用该实现，不给原生 Checkbox 添加无效的 `readonly` 或自行添加 `aria-readonly`。每项保留 Runtime 标签和可访问名称，以 `aria-describedby` 关联自动管理说明。说明放在禁用控件之外，保持可读及辅助技术可访问；导航保持正常 Tab 顺序和可见焦点。窄窗口下分配项换行，保留标签、勾选状态、说明和导航。
+
+## 会话入口
+
+在现有聊天输入区以自然语言发起图片生成或编辑，本次指定模型也通过请求表达。复用上传附件和历史成果引用入口，输入区显示素材缩略图或文件名并允许移除。不新增会话级图片模型选择器、独立生成表单或视频入口。
+
+未设默认时，助手提示本次指定可用模型，或到设置选择默认后重新发送；名称歧义先澄清。没有图片连接时提供现有模型设置入口。模型不支持编辑或素材缺失时保留输入，提示更换模型或重新选择素材。
+
+直连文本、本地各 Runtime 和 GoodBuddy Agent 远程适用 Runtime 使用一致的图片操作与成果反馈。切换后可继续生成及编辑历史图；工具调用异常时显示具体原因，不宣称已提交。接入未完成的开发状态记录在进度文档，不能作为产品支持范围。
+
+不支持工具调用时提示“当前聊天模型无法自动调用图片工具，可使用已有直连图片工作流”。Ask 下提示“生成或编辑图片需要 Execute 模式”，由用户切换，不自动切换。无视觉能力时说明无法直接查看图片，不妨碍按用户文字调用编辑工具。
+
+## 图片卡片
+
+复用现有图片成果展示，卡片就近显示实际模型、操作状态、成果或错误。提示词、适用参数和来源素材放在详情中；不显示密钥、认证头或供应商私有地址。活动记录与卡片使用同一操作标识。
+
+完成后可预览、下载和“继续修改”。继续修改将成果加入输入区，用户填写修改要求；切换 Runtime 或重开会话后仍可使用。离开会话不取消操作，结果只出现在原会话。
+
+进行中提供“取消生成”，与“停止回复”分开。取消、晚到结果和结果未确认的文案遵循 L-4。失败提供适用的“重新生成”“重新选择模型”或“重新选择素材”；重新生成由用户明确触发，并说明会发起新的模型请求。没有独立“重试保存”按钮。
+
+“重新选择模型”进入已有模型连接设置；改变模型后，用户在新请求中明确指定。“重新选择素材”聚焦输入区并打开已有附件选择器，保留草稿和已有附件；空草稿填入原提示词及模型名称。历史成果仍使用“继续修改”加入引用并聚焦输入区。上述操作不自动发送请求，“重新生成”继续使用原操作的模型和输入。
+
+卡片错误不重复弹全局通知；模型设置保存等非上下文反馈使用应用通知。状态使用文字，不能只靠颜色；状态变化通过适度的 `aria-live` 提示，避免逐秒播报等待时间。窄窗口操作可换行，图片不超过消息区宽度，模型长名称截断时保留完整可访问名称。复用的菜单关闭后焦点回到触发控件。
@@ -0,0 +1,34 @@
+# 用户场景
+
+状态：设计草案。Given、When、Then 分别为前提、操作和预期结果。范围以[产品需求](./prd.md)为准，行为以[行为规则](./logic-design.md)为准。
+
+## 场景验收
+
+适用的自动调用场景须在直连文本 Model Runtime、本地 OpenCode、Continue、DeepSeek Harness 和 GoodBuddy Agent 远程适用 Runtime 分别验证，前提为 Execute 且聊天模型支持工具调用。切换验收同时检查原操作归属和目标 Runtime 的新生成、编辑能力。
+
+| 编号 | 需求 | Given | When | Then |
+| --- | --- | --- | --- | --- |
+| US-01 | FR-1、FR-3、FR-9 | 已添加图片模型、开启会话调用并设为默认 | 在文字会话中要求画海报 | 自动调用并显示活动，原会话出现图片及实际模型；无需创建 Skill、MCP server 或重复凭据 |
+| US-02 | FR-2 | 有两个可调用图片模型，未选默认 | 请求生成图片 | 提示本次指定模型或到设置选择默认后重新发送；名称歧义先澄清，不按列表顺序提交 |
+| US-03 | FR-4、FR-5 | 聊天模型 A 已调用图片模型生成图片 | 切换聊天模型 B，要求修改该图 | B 获得成果引用和可用工具，编辑模型按规则选择 |
+| US-04 | FR-4、FR-6、FR-9 | 生成操作已提交 | 切换 Runtime 并打开其他会话，再请求生成或编辑 | 原操作继续且只写回原会话；目标 Runtime 可提交新操作，不重放旧调用 |
+| US-05 | FR-2、FR-4 | 当前操作使用图片模型 X | 将全局默认改为 Y，再请求新建图片 | 旧操作仍用 X，新操作用 Y；本次明确指定可覆盖默认 |
+| US-06 | FR-1、FR-2、FR-4 | 默认或本次指定模型为 X | X 被关闭或删除后请求生成 | 显示 X 不可用并提示改选，历史图仍可打开，不静默换模型 |
+| US-07 | FR-5、FR-8 | 已保存图片并重新打开会话或切换 Runtime | 引用原图，指定另一个支持编辑的模型 | 新模型接收原图；素材缺失时要求重新选择，不能假装已编辑 |
+| US-08 | FR-7 | 当前聊天模型不支持工具调用，或处于 Ask | 请求生成或编辑 | 无工具能力时说明可使用已有直连图片工作流；Ask 下不提交并提示需要 Execute，不自动切换模式 |
+| US-09 | FR-6 | 操作正在生成或保存，或已经失败 | 取消，或明确要求重新生成 | 如实显示取消结果；人工重新生成创建新操作，不自动重复收费请求，不提供独立保存重试入口 |
+| US-11 | FR-4、FR-9 | 使用 GoodBuddy Agent 远程适用 Runtime | 生成及编辑图片，切换本地后继续编辑，再切回远程生成 | 工具往返可用，成果可继续引用；活动归原会话，凭据留在 Main；远程断连不取消 Main 已接收的操作 |
+| US-12 | FR-5、FR-7、FR-8 | 聊天模型无视觉能力但支持工具 | 请求分析图片或根据文字修改图片 | 说明无法直接查看图片；可传原图给编辑工具，不编造视觉观察 |
+| US-13 | FR-6 | 图片操作尚未取得可保存结果 | 退出并重开应用 | 未完成记录显示结果未确认，不承诺后台继续，不自动查询恢复或重新提交 |
+| US-14 | FR-5 | 会话有多张图片 | 要求“修改第二张”或“新画一张无关图片” | 前者引用指定成果，后者不附带旧图；指代不清先澄清 |
+| US-15 | FR-3、FR-5、FR-9 | 上传图片并选择支持编辑的图片模型 | 要求修改背景，再切换 Runtime 继续修改成果 | 上传原图及后续成果被正确引用，编辑结果保存在各自发起会话；不降为纯文生图 |
+| US-16 | FR-1、FR-9 | 尚无开启会话调用的图片模型 | 查看内置 MCP 列表，再开启一个图片模型并保存 | 图片生成与编辑行一直可见且标记“内置 · 自动管理”；全部支持 Runtime 从未勾选变为勾选，目录包含该模型；重开设置或应用仍按模型配置显示 |
+| US-17 | FR-1、FR-9 | 至少两个图片模型开启会话调用 | 关闭或删除其中一个并保存 | 全部支持 Runtime 保持勾选，允许目录移除该模型、保留其他开启模型；新操作不能调用已关闭或删除模型 |
+| US-18 | FR-1、FR-9 | 仅剩一个开启会话调用的图片模型 | 关闭或删除该模型，再重新开启或添加并开启一个模型 | 目录为空时全部取消勾选，整行和说明、模型设置导航仍可见；再次开启后自动恢复全部勾选，无需另行分配 |
+| US-19 | FR-1、FR-7、FR-9 | 至少一个图片模型开启会话调用 | 尝试用鼠标或键盘切换分配，或切换到无工具聊天模型、Ask、离线 Runtime，或遇到配置或执行错误 | 分配不可手动修改，运行限制与错误不取消勾选；无独立启用、分配保存、移除或凭据编辑操作；自动管理说明持续可读，辅助技术可识别勾选和禁用状态，键盘可通过“前往图片模型设置”导航修改源配置 |
+
+## 编号变更
+
+US-10（图生视频）移出本图片设计范围，编号保留，不安排实施。US-02、US-05、US-06 的会话选择预期由全局默认和本次指定替代；US-08 使用已有直连图片工作流；US-09 取消独立保存重试要求；US-13 的视频查询恢复由图片中断状态说明替代。其余编号保持，US-15 补充上传图片编辑的显式验收。
+
+US-16 至 US-19 补充自动管理分配验收，设置展示不依赖 Execute 或当前聊天模型支持工具；自动生成与编辑仍遵循本节的调用前提。
@@ -0,0 +1,11 @@
+# 会话监督
+
+会话监督定义对长会话、工具执行和异常状态的观察、判断与介入边界。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [会话监督 PRD](./prd.md) | 监督目标、证据、介入方式和产品验收 |
+
+当前尚无独立 User Stories、功能逻辑、UI、技术设计和进度文档。
@@ -8,7 +8,7 @@
 | 版本 | 0.2 |
 | 日期 | 2026-08-18 |
 | 依赖 | [自动化平台总体设计](../../architecture/automation-platform-architecture.md) |
-| 界面归属 | [通用助手工作栏与执行空间](../assistant-experience/assistant-workbar-and-execution-spaces-prd.md) |
+| 界面归属 | [通用助手工作栏与执行空间](../assistant-workbar/prd.md) |
 | 体验参考 | GoodBuddy 魔法笔记 AI 评论流 |

 ## 1. 背景
@@ -0,0 +1,18 @@
+# DeepSeek Harness Runtime
+
+本功能定义 DeepSeek Harness 作为 GoodBuddy 本机 Agent Runtime 的产品接入、控制面、
+插件市场、权限和打包边界。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [技术设计](./technical-design.md) | Runtime 产品与技术方案、协议、插件、打包、测试和验收 |
+| [实现进度](./progress.md) | Windows 工作区路径修复及验证记录 |
+
+现有文档同时包含部分 PRD、功能逻辑和进度内容，后续修改该 Runtime 时再按标准职责拆分。
+
+跨项目共享 Host 和状态检查不冷启动的实现设计，由
+[Runtime 进程复用技术设计](../assistant-workbar/runtime-process-reuse-technical-design.md)
+统一维护；本 Runtime 的生命周期见[技术设计 §9](./technical-design.md#9-runtime-生命周期)，
+未发布实现的验收状态见[工作栏进度](../assistant-workbar/progress.md#2026-09-14-runtime-进程复用实施中)。
@@ -0,0 +1,45 @@
+# DeepSeek Harness 实现进度
+
+## 2026-09-14 Windows 工作区路径修复
+
+本机 Runtime 的 Host 启动与 `newSession.cwd` 已共用初始化时解析的 `realpath`，
+规则见[技术设计](./technical-design.md#52-受控组合不启动用户-profile)。修复此前
+`C:/...\workspace` 写法触发 ACP `-32602`，以及随后换成同目录规范写法仍复用
+错误 Runtime 的问题。Host 严格比较与 execution-space 缓存规则保持原样。
+
+新增 Windows 真目录回归，连接真实 ACP、Host 和控制面，分别用混合分隔符及规范
+路径创建会话，断言共用同一 Runtime、只启动一次 Host、两次均完成。该自动化回归
+使用内存模型；外部真实模型验证单独由完整 App 完成。
+
+Windows 完整 App 使用当前源码构建的 Main、Preload、Renderer 和新建隔离配置。
+正式配置只读，模型凭据由隔离配置中的 safeStorage 解密；真实 composer 输入请求，
+由 `deepseek-v4-flash` 在 Ask 模式读取 `summary-probe.txt`，校验码未放入 prompt。
+
+| 目录写法 | Composer 提交 | 真实模型 HTTP dispatch | 文件读取 | 结果 |
+| --- | ---: | ---: | ---: | --- |
+| Windows 混合分隔符 | 1 | 2 | 1 | 仅返回文件中校验码，任务完成 |
+| 同目录规范路径 | 1 | 2 | 1 | 仅返回文件中校验码，任务完成 |
+| 合计 | 2 | 4 | 2 | 两条会话均通过 |
+
+两轮 dispatch 来自同一 DS Utility Host 进程，切换目录写法未新增 Host；ACP 会话
+ID 不同。两条工具卡片均显示路径摘要，原生点击展开后可查看输入与输出；重载
+Renderer 并重新选择项目后，已保存会话的摘要、详情和完成状态仍通过检查。四张
+局部截图已逐张打开审阅。驱动曾返回不可克隆的监听器函数，以及在重载后默认项目
+等待工具卡片超时；修正定位后通过，这两次驱动错误没有增加模型请求。
+
+本机临时 `ds-windows-path-live/report.json`、`dispatch.jsonl` 与 `source.json`
+记录结果、逐请求计数和构建哈希，原 `runtime-summary-live` 报告未覆盖。
+本次 App 正常退出，退出前记录的 5 个所属进程均已停止；隔离 profile、数据库、
+工作区、临时构建和私有日志已清理。正式模型配置与启动前逐字节一致，报告和截图
+保留在本机临时目录，不作为长期可用的仓库资源。
+测试沿用生产 HTTPS 与证书处理，未单独验证严格证书校验或 Main 重启。
+
+专项 7 个测试文件通过，91 项通过、3 项跳过。`npm run typecheck` 与
+`npm run lint` 通过。最初两个假时钟测试因异步目录解析尚未结束就推进启动时钟而
+超时；调整为等待 launcher 启动后，DS Runtime 的 34 项测试全部通过。
+最终全量 `vitest run`（`npm test` 的脚本入口）为 353 个文件通过、9 个跳过，
+4155 项通过、66 项跳过、0 失败，耗时 602.00 秒。`git diff --check` 通过。
+
+远端核查：Main 的 SSH 分支创建托管远程 Runtime，最终使用 `AcpRemoteRuntime`；
+`create-runtime.ts` 的本机 DS 入口拒绝 SSH execution space。本次未改远端代码，
+未调用远端模型，也未进行 Linux Host 实测。
@@ -7,7 +7,7 @@
 | 文档状态 | 实现与发布验收基线 |
 | 设计目标 | 将 DeepSeek Harness 作为 GoodBuddy 的第三个 Agent Runtime |
 | Runtime 标识 | `deepseek-harness` |
-| 当前依赖基线 | 实际使用的 `@deepseek-ai/dsh-*` 底层库，精确锁定 `0.1.0-rc.8` |
+| 当前依赖基线 | 实际使用的 `@deepseek-ai/dsh-*` 底层库，精确锁定 `0.1.2-rc.1` |
 | 上游状态 | Developer Preview，允许出现破坏性变更 |
 | 上游许可证 | MIT |
 | GoodBuddy 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
@@ -121,6 +121,11 @@ GoodBuddy 使用自己固定的 Harness Host 入口和只读组合模板，不

 模型名称、服务地址、工作区、Skills、MCP schema 和已启用插件的规范化入口通过严格校验的 Main 配置传给 Host。API Key 只通过受控凭据通道按需提供，不写入 YAML、命令行、Renderer 或日志。插件配置只来自 GoodBuddy 受管状态，不合并用户 profile 或全局补丁。

+Main 在创建 Session 前解析该请求工作区的 `realpath`，把绝对路径传给 ACP
+`newSession.cwd`。Host 不再要求 Session cwd 等于启动 cwd，原生 Agent header.cwd
+驱动文件与 Shell 工具；启动 cwd 仅为默认值。远端 SSH 由 `ManagedRemoteAcpRuntime` /
+`AcpRemoteRuntime` 单独处理，不经过本机 DS Runtime 的目录解析。
+
 ### 5.3 双层内部控制面

 Harness 子进程内控制面不能取代 Main 控制面，Main 控制面也不能代替进程内的 Session/Tool 适配层：
@@ -136,9 +141,14 @@ Harness 子进程内控制面不能取代 Main 控制面，Main 控制面也不

 - GoodBuddy 已经持久化对话、消息、活动、工具事件和用量。
 - 再写一份 Harness 日志会扩大敏感数据副本和清理范围。
- GoodBuddy 在 Runtime 重启后可以用现有的有界历史创建新 Harness Session。
+- GoodBuddy 在 Runtime 重启后可以用现有会话历史创建新 Harness Session。

 Harness Session 只在当前 Runtime 进程生命周期内存在。释放 GoodBuddy 会话时必须同步释放对应 Harness Agent。
+固定 Host 显式加载 `dsh-session-projection` 的内存 SessionProjectionRegistry，这是
+`0.1.2-rc.1` AgentLoop 的必需依赖；不加载 Session persistence，也不新增磁盘会话副本。
+该依赖与其余 DSH 依赖一起由 Vite 打入 Host，不能从 `app.asar.unpacked` 外部导入
+仅存在于 `app.asar` 的 npm 包。最终打包检查及 Windows CI 的真实 UtilityProcess
+启动探针见 [Runtime 资源与打包](../../../BUILD.md#runtime-资源)。

 ## 6. 总体架构

@@ -163,7 +173,7 @@ Electron utilityProcess
       ├─ 本地 Shell / Filesystem Provider
       ├─ 最小工具集与 Main 代理 MCP
       └─ Main 明确启用的第三方 Cordis 插件
-             │ HTTPS
+             │ HTTP/HTTPS
             ▼
        用户选择的 OpenAI 兼容模型连接
 ```
@@ -254,7 +264,9 @@ Store 是否已经提交为准，确定性完成新目录或恢复旧目录，
 | `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 = {
@@ -288,6 +300,10 @@ GoodBuddy 的工作模式属于每个请求，不属于 Runtime 进程全局状
 5. 缺少准备状态、重复使用、请求标识不匹配时，Control Plane 直接拒绝请求。
 6. 同一 Session 只允许一个 Prompt 在途。

+若 Runtime 回传 ACP 权限请求，Main 只按活跃 Session 的当前模式答复：Execute 优先选择
+`allow_once`，缺少时使用提供的 `allow_always`，不调用第二次人工 authorizer；
+Ask、已关闭或未知 Session 拒绝。这里不写入永久授权规则，也不把业务问答当作权限确认。
+
 ### 8.5 事件模型

 Harness Control Plane 只发送 GoodBuddy 能稳定解释的字段：
@@ -296,6 +312,7 @@ Harness Control Plane 只发送 GoodBuddy 能稳定解释的字段：
 - `text`：已提交的助手文本分片。
 - `reasoning`：可选的有界推理摘要分片。
 - `tool`：工具 ID、名称、状态和有界输入/输出摘要。
+- 操作标题与增量完成事件的参数保留遵循[工具操作摘要规则](../assistant-workbar/runtime-interactions.md#工具操作摘要)，本机适配器按调用 ID 合并，详情上限保持不变。
 - `model-usage`：模型、提供方、输入、输出和缓存 Token。
 - `done`：停止原因和 Session ID。

@@ -305,37 +322,42 @@ Harness Control Plane 只发送 GoodBuddy 能稳定解释的字段：

 ### 9.1 进程模型

- 每个活动的 DeepSeek Harness Runtime 实例拥有一个 `utilityProcess`。
- 一个进程可以承载多个 Harness Session。
+- Main `LocalRuntimeRegistry` 按兼容模型及 Host 配置共享重型实例；
+  每组拥有一个 `utilityProcess`，不同工作区使用轻量适配器及独立 Session cwd。
 - 同一 GoodBuddy 对话的 Prompt 串行执行。
 - 不同对话可以并行，但受全局并发上限控制。
- Runtime 设置变化时创建新实例，旧实例等待在途请求结束或在宽限期后被取消。
+- Runtime 设置变化时旧配置停止接收新请求，在途请求结算后释放旧实例。

 ### 9.2 会话映射

 Main 保存内存映射：

 ```text
-GoodBuddy conversationId -> Harness sessionId + process generation
+GoodBuddy conversationId -> Harness sessionId + workspace + process generation
 ```

 - 首次请求创建 Session。
 - 已有 Session 只发送当前 Prompt。
- 进程重启或映射失效时，创建新 Session，并只在这一次加入 GoodBuddy 提供的有界历史。
+- 进程重启或映射失效时，创建新 Session，并只在这一次加入 GoodBuddy 提供的会话历史。
 - 历史以明确的“不可信会话数据”结构传入，不能拼接成系统指令。
 - 用户分配的 Skill 只通过 Main 校验的包路径进入 Host，并在 Agent scope 注册；不得把 Skill 内容伪装成用户 Prompt。

-### 9.3 取消与超时
+### 9.3 取消与有界控制操作

 - 用户取消时立即发送 `session/cancel`。
- 取消等待有界，超时后关闭连接并终止整个 Harness 进程。
- 初始化、握手、Session 创建、Prompt、权限回传和关闭分别使用独立超时。
- Prompt 超时与用户取消使用不同错误类型，不能被宽泛 catch 抹平。
+- 取消等待有界，超时先释放目标 Session 的 Agent、工具和 Main 代理资源；
+  只有该控制操作也不响应时才终止整个 Harness 进程。
+- 初始化、握手、请求准备、权限回传和关闭分别使用独立控制超时。
+- 生产 Prompt 不设置固定墙钟总时限，由 Harness 自身协议终态或用户取消结束。测试可以
+  显式注入短 Prompt 时限验证取消传播，超时错误与用户取消仍不能被宽泛 catch 抹平。
 - 取消后仍可接收并丢弃该请求的最终协议结算帧，但不得写入下一请求。

 ### 9.4 释放与退出

- 原生能力清单通过一次性 Runtime 探测，取得有界快照后立即 dispose，不得因浏览设置或切换项目把 Host 缓存在执行 Runtime 池中。
+- 原生清单与执行使用共享 owner，查询携带工作区。轻量适配器被缓存淘汰不结束原生
+  Session；无会话、无请求的 owner 空闲 60 秒退出，再次使用按需启动。
+- `getStatus()` 只读取已有状态和配置，不启动 Host，也不重置空闲回收计时；显式 `testConnection()` 才启动
+  并验证连接，临时检查适配器的 dispose 不终止其他会话。
 - 删除或释放对话时调用 `goodbuddy/session/release`。
 - Runtime dispose 时先拒绝新请求，再取消所有 Session。
 - Harness Control Plane 完成 Agent、工具和会话清理，Host 完成 Cordis Fiber 与子进程的反向清理。
@@ -344,6 +366,17 @@ GoodBuddy conversationId -> Harness sessionId + process generation
 - 应用退出时中止正在运行的 npm 插件安装并终止其完整进程树，不能让 lifecycle script 在 GoodBuddy 退出后继续运行。
 - 应用退出不得因 Harness 清理无限阻塞。

+### 9.5 跨项目复用
+
+锁定 0.1.2-rc.1 的文件和 Bash/PowerShell 工具已按原生 Session header.cwd 路由，
+Provider 的根 cwd 只是默认值。不为每工作区复制本地 Provider；
+Main 的 Web/MCP ToolProvider 按工作区保存，最后一个对应 Session 释放时 dispose。
+
+共享 Utility、逐 Session cwd、被动状态、Main 工具代理和取消升级统一由
+[Runtime 进程复用技术设计](../assistant-workbar/runtime-process-reuse-technical-design.md#5-deepseek-harness)
+定义，证据及剩余验收见[工作栏进度](../assistant-workbar/progress.md#2026-09-14-runtime-进程复用实施中)。
+本节描述当前未发布源码，不将新行为归入已发布的 Desktop 0.13.2。
+
 ## 10. 权限与主机执行

 ### 10.1 模式映射
@@ -369,6 +402,9 @@ GoodBuddy conversationId -> Harness sessionId + process generation
 - 工作区不是 containment 边界；绝对路径和命令可访问当前用户本来有权访问的主机资源。
 - 已启用插件注册的工具与内置工具使用同一分发路径；GoodBuddy 不增加插件权限矩阵或逐工具确认。
 - Main 代理的 MCP 工具继续执行分配、schema、活动请求、模式和 RuntimeAuthorizer 校验。
+  `goodbuddy/tools/list` 按 Session 保存本次发现的工具定义；`goodbuddy/tools/call` 复用该定义
+  校验参数与授权，不因调用健康工具而重新等待故障 MCP 的发现。发现重试留在清单刷新，
+  Session 释放及 Runtime dispose 清除内存定义，不持久化第二份能力状态。
 - 所有工具调用仍作为活动事件记录；Ask 和 delegation 路径继续固定拒绝。

 ### 10.4 Runtime OS 沙箱
@@ -426,13 +462,25 @@ 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 中显示为可选来源。
+- `platform` 在设置页显示为“管理员环境优先，回退 GoodBuddy 兼容连接”，不是 Harness
+  自有配置文件。Main 优先读取完整的 `GOODBUDDY_MODEL_BASE_URL`、
+  `GOODBUDDY_MODEL_NAME` 和 `GOODBUDDY_MODEL_API_KEY` 环境预置；不完整时使用
+  当前默认兼容 GoodBuddy 连接，再回退首个兼容连接。
+- `default` 只跟随 GoodBuddy 默认兼容连接或首个兼容连接，跳过独立管理员预置；
+  `profile` 使用指定的兼容连接。没有兼容连接时，仍允许选择 `platform`，因为完整
+  管理员预置不依赖已保存连接的协议；运行时缺少实际连接才报告不可用。
+- Renderer 通过 Main 的只读平台来源投影展示实际管理员模型或兼容回退，不读取环境
+  或密钥，也不根据 `credentialSource` 猜测。投影直接复用本节所述的生产 resolver，
+  字段、非持久化与草稿展示边界见
+  [Harness 平台来源公开投影](../model-connections/technical-design.md#9-harness-平台来源公开投影)。

 不允许选择 Harness 自有的用户配置文件或自定义 Host。Runtime 始终使用随当前 GoodBuddy 版本发布的内置 Host，并通过完整内部能力握手。

@@ -462,14 +510,15 @@ DeepSeek Harness 首版只使用符合下列边界的 GoodBuddy 模型连接：
 | 单图尺寸 / 单条消息解码像素 | 单边最长 8,192 px 且 1,600 万像素 / 3,200 万像素 |
 | Host 临时图片存储 | 32 MiB 且最多 256 个唯一对象 |
 | 单个文本或推理事件 | 64 KiB |
-| 单次请求累计协议输出 | 4 MiB |
+| 单次请求累计协议输出 | 无固定总量上限，继续校验单帧和待处理队列 |
+| 单轮模型输出 Token | 由 Harness SDK 与 Provider 决定，GoodBuddy 不固定覆盖为 16K |
 | 工具输入摘要 | 4,000 字符 |
 | 工具输出摘要 | 4,000 字符 |
 | 待处理事件数 | 1,000 |
 | stderr 累计 | 64 KiB |
 | Host 启动 | 10 秒基础预算 + 每插件 5 秒激活与最多 1 秒失败清理，插件序列最多 91 秒；Main 另预留 2 秒持久化失败状态 |
 | ACP 初始化与内部握手 | 每阶段 10 秒 |
-| 单次 Prompt | 10 分钟 |
+| 单次 Prompt | 无固定墙钟总时限，由 Harness 终态或用户取消结束 |
 | 有序关闭宽限期 | 2 秒 |

 超过限制时应取消当前请求。协议帧、队列或 stderr 持续异常时，应终止 Runtime 进程，避免继续信任已失控的通道。
@@ -497,7 +546,7 @@ Runtime：       GoodBuddy 内置 DeepSeek Harness
 模型配置：      跟随 GoodBuddy · 企业网关（qwen-plus）
 状态：          已就绪
 路径：          <受控 Host 路径>
-版本：          0.1.0-rc.8
+版本：          0.1.2-rc.1
 执行权限：      当前用户权限

 Host 始终由当前 GoodBuddy 版本提供，不存在自定义 Host 入口。
@@ -535,7 +584,7 @@ Runtime 栏目入口始终存在，并采用统一监督模型；内部再按用
 显示 OpenCode、Continue 或 DSH 的具体区域。未支持能力不渲染空卡片或一排禁用按钮，而是
 在用户需要理解缺口时显示原因和可执行入口。跟随模式切换 Runtime、Conversation 或 Task
 时必须清理上一归属的聚合执行状态，固定目标则保持不变。完整工作栏契约见
-[通用助手工作栏与执行空间 PRD](../prd/assistant-experience/assistant-workbar-and-execution-spaces-prd.md)。
+[通用助手工作栏与执行空间 PRD](../assistant-workbar/prd.md)。

 所有未来的 Subagent、Job、Workflow、Hook 和会话操作仍须经过 Main 的 Runtime 边界，保留取消、超时、权限、Task/Job/Subjob 层级、用量和活动审计。高风险动作在侧栏就地确认，运行结果进入活动与成果记录，不以 Composer 按钮代替监督面板。DeepSeek Harness 首版仍不加载这些服务，本节只确定未来跨 Runtime 的产品位置和协议归属。

@@ -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)：跨平台打包
+  矩阵和交付物的权威定义。
@@ -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. 逻辑完整性评估
+
+本设计覆盖了启用/关闭、暂时隐藏、快速起草、拖放（含超限和文件夹）、状态镜面优先级、
+提示与原生通知的归并、位置越界恢复、以及主窗口不可用时的失败路径。
+
+未在本文固定、留给技术设计选择的实现细节：
+
+- “最近完成/最近失败”窗口的具体时长和“已查看”判定的确切事件来源。
+- 贴边吸附阈值和默认回退位置的具体像素值。
+- 状态查询的具体轮询或事件驱动机制。
+
+这些是技术选择而非未解决的产品决策：本文的优先级和决策表已经足以在任何取值下保持
+行为一致。
@@ -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)。
@@ -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 节的互斥规则。
+- 多显示器插拔场景下确认位置回退逻辑（断开记忆显示器后宠物仍可见）。
+- 打包后的应用在六个标准目标上完成启用、拖动、快速起草、退出流程的一次冒烟验证。
+
+设计文档完成不代表功能实施或上述验证通过。
@@ -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) 术语表。不使用“挂件”“桌宠助手”或其他未在术语表中定义的别名，
+保持中文文案统一。
@@ -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 不接收该拖放，不产生任何暂存或错误提示
@@ -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)。
@@ -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 子集、端到端中继加密套件和桌面端可
+注册为共享能力的首批实际类型；这些是技术选择，不改变本文状态和产品规则。
@@ -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. 产品验收
+
+- 两台新设备能完成发现、双端配对、授权、调用、取消和撤销。
+- 三个概念“主动发现、允许被发现、开放能力”在状态和界面上互不混淆。
+- 不配置网关时局域网工作完整；任一网关故障不阻塞其他来源。
+- 未配对或未授权主体无法查看详细能力。
+- 远端调用前能准确列出实际发送的数据，执行中和历史中可追溯提供者。
+- 结果未知不会被显示为失败后自动重试或成功。
+- 权限扩大的能力更新不会沿用旧授权静默安装。
+- 中英文、键盘、焦点、窄窗口和深浅主题符合统一设计系统。
@@ -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、诊断和审计中没有凭据或文件正文。
+
+设计文档完成不代表功能实施或上述验证通过。
@@ -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 简称为“云端”。
@@ -0,0 +1,59 @@
+# 直连模型 Agent 能力
+
+本目录是 GoodBuddy“直连模型 Agent 能力”的唯一文档入口。本功能为直连文本模型补齐
+高效工作区搜索、分页读取、补丁编辑、跨平台进程执行和编程 Subagent，使其能够完成
+“搜索、读取、修改、运行、验证”的开发闭环，同时避免向已经拥有原生 Shell 或 Agent
+能力的 Runtime 重复注入工具。
+
+## 文档导航
+
+| 文档 | 权威职责 |
+| --- | --- |
+| [PRD](./prd.md) | 用户问题、产品范围、功能需求、非目标和产品验收 |
+| [User Stories](./user-stories.md) | 本机开发、失败恢复、委派和 Runtime 边界场景 |
+| [功能逻辑](./logic-design.md) | 能力矩阵、不变量、状态转换、继承规则和失败结果 |
+| [UI 设计](./ui-design.md) | 设置能力目录、聊天活动、Subagent 状态和无障碍行为 |
+| [技术设计](./technical-design.md) | Main 服务、工具契约、平台适配、Subagent、生命周期和测试 |
+| [功能进度](./progress.md) | 当前实现事实、待实施阶段、阻塞项和验证证据 |
+
+## 术语
+
+| 术语 | 定义 |
+| --- | --- |
+| 直连模型 | Runtime provider 为 `model`、由 GoodBuddy 直接调用模型协议的文本模型 |
+| 进程执行 | GoodBuddy 在当前执行空间启动一个前台 Shell 命令并返回有界结果 |
+| 工作区搜索 | 通过安装包内置 ripgrep 搜索内容或列出文件，并返回紧凑结果 |
+| 工作区补丁 | 通过 `*** Begin Patch` 格式新增、修改或删除工作区文本文件 |
+| 输出续读 | 通过 `output_read` 分页读取当前会话保留的进程或 Subagent 输出 |
+| 平台 Shell | Windows 上的 PowerShell，macOS/Linux 上的 Bash 或 POSIX Sh |
+| 编程 Subagent | 由直连模型临时委派、使用直连模型 Runtime 执行一个有界子任务的执行者 |
+| 父请求 | 发起进程调用或 Subagent 委派的当前直连模型请求 |
+| 子任务 | 父请求内部的一项委派工作，对应 Job/Subjob 语义，不是新的顶层 Task |
+
+Task、Job、Subjob、Run 和 Subagent 的对象关系以
+[Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) 为准。本功能不重新定义
+这些对象。
+
+## 功能边界
+
+- `workspace_rg`、`workspace_read_text`、`workspace_apply_patch`、`process_execute`、
+  `subagent_delegate` 和 `output_read` 是 GoodBuddy 直连模型内置工具，不是外部 MCP。
+- 直连文本模型的普通问答、工具轮次和上下文摘要会在尚无可见输出时，对瞬时网络错误或
+  单次请求超时最多自动重试 3 次。
+- OpenCode、Continue 和 DeepSeek Harness 继续使用各自原生执行与委派能力。
+- Ask 可搜索和分页读取工作区，但不允许补丁写入或进程执行；Subagent 若在 Ask 中使用，
+  只能继承 Ask 的只读能力。
+- 进程和 Subagent 的长输出返回预览与续读位置，完整内容保留到所属会话或 Runtime 释放。
+  Ask 和 Execute 均可续读当前会话已取得的输出，详见 [输出契约](./technical-design.md#43-输出边界)。
+- Execute 表示用户授权当前执行空间账号的完整能力，不增加第二套工具审批或权限档位。
+- 首版跨平台指桌面本机 Windows、macOS 和 Linux。托管 SSH 项目当前继续使用远端
+  OpenCode；未来若向远端直连模型开放本工具，命令必须由 Host Agent 执行，绝不能回退到
+  桌面本机。
+
+## 相关功能
+
+- [模型连接请求定制](../model-connections/README.md)：定义连接级 Header/Body、合并优先级和 Runtime 支持矩阵。
+- [本机工具环境](../local-tool-environment/README.md)：为新进程提供 Node、Python 和 PATH。
+- [助手工作栏与执行空间](../assistant-workbar/prd.md)：定义本机/SSH 执行位置和活动归属。
+- [远程主机与远程执行](../remote-host/README.md)：定义当前托管 SSH Runtime 边界。
+- [DeepSeek Harness Runtime](../deepseek-harness/README.md)：已经拥有平台 Shell 的独立 Runtime。
@@ -0,0 +1,209 @@
+# 直连模型 Agent 能力功能逻辑设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-09 |
+| 关联 PRD | [PRD](./prd.md) |
+| 关联故事 | [User Stories](./user-stories.md) |
+
+## 1. 权威不变量
+
+1. `process_execute` 和 `subagent_delegate` 只属于直连文本模型。
+2. Ask 永远不能启动命令、写入工作区或创建 Execute Subagent。
+3. 子级的项目、执行空间、工作模式、模型连接和能力范围只能继承或缩小。
+4. 子级工具清单不包含 `subagent_delegate`，最大深度固定为 1。
+5. 命令必须在父请求绑定的执行空间运行，禁止跨设备静默回退。
+6. 一个 `process_execute` 调用只拥有自己创建的前台进程树，不能管理无关进程。
+7. 非零退出码是命令结果；启动失败、输入无效和后端不可用才是工具失败。
+8. 子任务是父请求内部 Job/Subjob，不创建顶层 Task 或独立 Conversation。
+9. 父请求取消、Runtime 释放或应用退出会传播到全部活动子级和进程。
+10. OpenCode、Continue 和 DeepSeek Harness 的原生能力不被本功能替换或包装。
+11. 直连模型只在尚未显示文本或推理内容时自动重试瞬时网络错误或请求超时，最多重试
+    3 次；用户取消和已显示的部分输出禁止重放。
+12. Ask 可调用 `workspace_rg` 和 `workspace_read_text`，但不能调用
+    `workspace_apply_patch`；Execute 可调用三者。
+13. 工作区搜索固定使用随包 ripgrep 的结构化输出，不把任意 ripgrep 参数转成命令执行。
+14. FR-7 / US-A6：预览之外的进程和 Subagent 输出保留在所属会话下，分页续读不启动新命令。
+    会话释放先停止活动工作，再删除输出；子会话结束不删除父会话拥有的 Subagent 结果。
+
+## 2. 状态维度
+
+| 维度 | 值 |
+| --- | --- |
+| Runtime | `model`、`opencode`、`continue`、`deepseek-harness` |
+| 工作模式 | `ask`、`execute` |
+| 执行空间 | `local`、`ssh` |
+| 本机 Shell | `available`、`unavailable` |
+| Subagent 深度 | `0`、`1` |
+| 父请求 | `active`、`cancelling`、`terminal` |
+| 模型请求重试 | `initial`、`retry 1..3`、`terminal` |
+
+## 3. 工具可见性决策表
+
+| Runtime | 模式 | 工作区读/搜索 | 补丁 | `process_execute` | `subagent_delegate` |
+| --- | --- | --- | --- | --- | --- |
+| `model` | Ask | 提供 | 隐藏 | 隐藏 | 提供，只读继承 |
+| `model` | Execute，本机 Shell 可用 | 提供 | 提供 | 提供 | 提供，Execute 继承 |
+| `model` | Execute，本机 Shell 不可用 | 提供 | 提供 | 隐藏并报告诊断 | 提供 |
+| `model` | SSH，远端后端未实现 | 当前入口不开放 | 当前入口不开放 | 隐藏 | 隐藏 |
+| 其他 Runtime | 任意 | 不注入本功能工具 | 不注入 | 不注入 | 不注入 |
+
+工具清单隐藏不是最终授权边界。`callTool` 仍须重新验证 Runtime、工作模式、执行空间和父请求
+是否活动，以拒绝旧快照或伪造调用。
+
+FR-4 / FR-12 / US-B0：Ask 工作区搜索和读取不依赖知识库、联网搜索或委派开关，不需要
+切到 Execute 或额外批准。MCP 服务器失败也不改变本机只读工具的可用性。
+
+`output_read` 在直连模型拥有进程或 Subagent 服务时提供，Ask/Execute 均可用，不取决于
+本轮 Shell 可用性、是否允许再次委派或委派深度。读取只接受当前会话的句柄；其他 Runtime
+不注册该工具，调用边界同样拒绝。
+
+## 4. 进程状态机
+
+```text
+validating
+  ├─ invalid → failed
+  └─ valid → starting
+               ├─ spawn_failed → failed
+               └─ running
+                    ├─ exit 0 → completed
+                    ├─ exit nonzero → completed_nonzero
+                    ├─ timeout → terminating → timed_out
+                    ├─ parent cancel → terminating → cancelled
+                    └─ output/lifecycle failure → terminating → failed
+```
+
+规则：
+
+- `completed_nonzero` 仍产生正常工具结果。
+- 超时和取消结果包含已取得输出的预览；超出预览的内容按 FR-7 继续保留，直到所属会话释放。
+- 进入 `terminating` 后不再接受新输入，也不启动替代命令。
+- 终止只针对本次调用记录的进程树。
+- 迟到的 `close` 只用于清理，不得覆盖已提交的取消或超时原因。
+
+## 5. 工作目录决策
+
+| 输入 | 结果 |
+| --- | --- |
+| 未提供 | 当前工作区根目录 |
+| `.` 或相对路径 | 以当前工作区为基准解析，可指向工作区外目录 |
+| 绝对路径 | 使用指定目录 |
+| `..` 或指向工作区外的符号链接 | 解析到实际目标目录，按当前用户权限执行 |
+| 不存在或不是目录 | 拒绝 |
+| 当前工作区身份在验证期间变化 | 拒绝本次调用 |
+
+工作区提供默认目录和相对路径基准，不是 Execute 命令的文件系统边界。单次命令选择其他
+工作目录不会修改父请求绑定的项目或工作区，也不会影响后续未指定 `cwd` 的命令。
+
+## 6. Shell 选择
+
+| 平台 | 顺序 | 不可用结果 |
+| --- | --- | --- |
+| Windows | `pwsh` → `powershell.exe` | 进程工具不注册，设置诊断显示 PowerShell 不可用 |
+| macOS | `/bin/bash` → `/bin/sh` | 两者都不可用时不注册 |
+| Linux | `/bin/bash` → `/bin/sh` | 两者都不可用时不注册 |
+
+一次父请求冻结实际 Shell 描述。PATH 或工具环境设置变化只影响新创建的 Runtime/执行服务，
+不在运行中的命令或 Subagent 中途切换。
+
+## 7. Subagent 状态机
+
+```text
+validating
+  ├─ invalid/depth_exceeded → failed
+  └─ queued
+       ├─ parent_cancelled → cancelled
+       └─ running
+            ├─ model done → completed
+            ├─ child failure → failed_with_partial_output
+            ├─ timeout → cancelled
+            └─ parent cancel → cancelled
+```
+
+父模型收到结构化终态：
+
+```ts
+type SubagentDelegateResult = {
+  status: 'completed' | 'failed' | 'cancelled'
+  output: string
+  error?: string
+  modelUsage?: {
+    inputTokens?: number
+    outputTokens?: number
+  }
+}
+```
+
+失败和取消是父模型可以解释的子任务结果。只有契约损坏、未知子任务身份或服务已经释放等
+内部不变量失败才终止父工具循环。
+
+## 8. 权限与能力继承
+
+| 父请求 | 子级模式 | 子级能力 |
+| --- | --- | --- |
+| Ask | Ask | 父级只读工具的子集，不含进程、写入和再次委派 |
+| Execute | Execute | 父级已启用工具的子集，包含本机进程能力，不含再次委派 |
+
+- 子级不能请求更高模式。
+- 子级使用父请求开始时的工具与能力快照；运行中设置变化不重写快照。
+- 子级调用 MCP、浏览器或知识能力时继续经过这些能力已有的作用域和生命周期边界。
+- FR-5 / FR-7 / US-C1：Execute 子级使用父请求的浏览器标签页，不另开标签页或改变所有权；
+  子级结束后父模型仍可继续操作该页，父请求继续负责其使用租约。
+- Execute 子级不弹出额外的“Subagent 执行授权”，也不获得父级没有的 MCP 分配。
+
+## 9. 并发和顺序
+
+- 全局编程 Subagent 最大并发为 3，额外请求进入有界队列。
+- 单个父模型的工具调用仍按直连模型现有顺序结算，不为本功能改写全部工具并发语义。
+- 不同父请求的 Subagent 可以并发；共享工作区的并发写入属于用户已授权的 Execute 行为，
+  活动记录必须保留实际顺序和结果。
+- 首版不自动创建工作树、锁文件或回滚层。出现真实冲突时由父模型读取当前工作区事实并处理。
+
+## 10. 结果优先级
+
+当多个终止原因竞争时，使用以下优先级：
+
+```text
+用户/父请求取消 > 工具超时 > 输出或协议边界 > 进程退出 > 普通工具错误
+```
+
+已经提交的正常终态不被稍后到达的取消覆盖。父请求进入终态后，迟到的子级文本和工具事件
+只用于资源清理，不再写入会话。
+
+## 11. 模型请求重试
+
+```text
+attempt
+  ├─ success → completed
+  ├─ cancel → cancelled
+  ├─ non-retryable failure → failed
+  ├─ transient failure after visible output → failed_with_partial_output
+  └─ transient failure before visible output
+       ├─ retry count < 3 → backoff → attempt
+       └─ retry count = 3 → failed
+```
+
+- 瞬时失败包括常见连接重置、连接/网络不可达、DNS 临时失败、连接管道中断和请求超时。
+- 三次重试分别等待 500 ms、1 s 和 2 s；每次尝试重新建立请求并使用独立请求超时。
+- 普通问答、工具模型轮次和上下文摘要使用同一规则。
+- 重试不重复已经执行的工具；工具只会在模型完整返回一轮工具调用后开始执行。
+- 退避等待绑定父请求取消信号，取消优先于启动下一次尝试。
+
+## 12. 逻辑完整性评估
+
+| 领域 | 结论 |
+| --- | --- |
+| Runtime 隔离 | 完整，工具只注入 `model` |
+| Ask/Execute | 完整，清单过滤和调用边界双重检查 |
+| 本机三平台 | 完整，统一契约和平台 Shell 决策已定义 |
+| Subagent 递归 | 完整，深度固定为 1 |
+| 取消与失败 | 完整，父子和进程传播及优先级已定义 |
+| 模型网络恢复 | 完整，有限重试、输出重放和取消边界已定义 |
+| 产品对象 | 完整，遵循 Task/Job 权威模型 |
+| SSH 远端执行 | 明确不在首版；未来必须增加 Agent 后端后才能开放 |
+
+当前没有需要在实施前由用户补充的产品决策。
@@ -0,0 +1,226 @@
+# 直连模型 Agent 能力 PRD
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施，跨平台 CI 待验证 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-09 |
+| 适用产品 | GoodBuddy 桌面端 |
+| 目标平台 | Windows、macOS、Linux，x64 与 arm64 |
+| 关联领域 | [Task 与 Job 统一领域模型](../task-and-job/task-and-job-model.md) |
+
+## 1. 背景
+
+GoodBuddy 直连模型已经可以读取、列出和写入工作区文本，使用浏览器、联网搜索、知识库及
+分配的 MCP，但没有内置命令执行工具。模型可以生成代码，却不能运行构建、测试、格式化、
+Git 或项目脚本，因此无法独立验证结果。
+
+本功能设计时，GoodBuddy 已有面向用户专家协作的只读 Subagent，但直连模型尚不能在工具
+循环中主动委派编程子任务。当前专家协作已继承父请求 Ask/Execute 模式并使用本机直连模型
+工具，与本功能的 `subagent_delegate` 仍为不同入口。OpenCode、Continue 和 DeepSeek Harness 一般已经提供
+Shell、Agent 或 Task 能力，再向它们注入 GoodBuddy 同名工具只会造成重复入口和语义冲突。
+
+本功能补齐直连模型缺少的基础 Agent 能力：
+
+1. 一组工作区搜索、分页读取和补丁编辑接口。
+2. 一个按平台适配的进程执行接口。
+3. 一个单层、继承父请求范围的编程 Subagent 接口。
+
+## 2. 产品目标
+
+1. 让直连模型在 Execute 模式完成“读取代码 → 修改 → 运行 → 根据结果修正”的闭环。
+2. 在 Windows、macOS 和 Linux 使用同一个模型工具契约，不要求模型调用平台专属工具名。
+3. 让直连模型可以把独立工作委派给临时 Subagent，并取得有界、可核验的结果。
+4. 保持 Ask 只读、Execute 完整授权、执行空间、取消、有界输出和进程回收语义不变。
+5. 不向已有原生执行能力的 Agent Runtime 重复注入 GoodBuddy 进程或 Subagent 工具。
+6. 使用安装包内置 ripgrep 提供跨平台一致的快速代码搜索，不依赖用户预装命令。
+
+## 3. 核心产品决策
+
+### 3.1 统一工具名，平台适配留在 Main
+
+模型只看到 `process_execute`。GoodBuddy 根据当前平台选择 PowerShell、Bash 或 Sh，并在
+工具描述和结果中明确实际 Shell。模型不需要在 Windows 调用 `powershell_execute`、在
+macOS/Linux 改用 `bash_execute`。
+
+### 3.2 它是内置能力，不依赖 MCP
+
+进程生命周期、工作目录、取消和执行空间由 GoodBuddy 管理。用户仍可以配置提供其他命令
+能力的 MCP，但直连模型的基本编程能力不依赖第三方 MCP 是否安装或在线。
+
+### 3.3 Runtime 能力不重复注入
+
+| Runtime | GoodBuddy `process_execute` | GoodBuddy `subagent_delegate` |
+| --- | --- | --- |
+| 直连模型 `model` | Execute 提供 | Ask/Execute 提供 |
+| OpenCode | 不提供 | 不提供 |
+| Continue | 不提供 | 不提供 |
+| DeepSeek Harness | 不提供 | 不提供 |
+
+“不提供”只表示不注入本功能工具，不限制 Runtime 自己的 Bash、PowerShell、Task、
+Agent 或插件能力。
+
+### 3.4 Subagent 继承，不扩权
+
+Subagent 使用父请求的项目、执行空间、工作模式、直连模型连接和已启用能力快照：
+
+- Ask 父请求只能创建 Ask Subagent。
+- Execute 父请求创建 Execute Subagent。
+- 子级不能切换父请求绑定的项目、工作区、Runtime、模型连接或工作模式；Execute 命令的
+  单次工作目录选择遵循 FR-3。
+- 子级不再看到 `subagent_delegate`，首版最大委派深度固定为 1。
+- 子任务不是新的顶层 Task 或 Conversation，结果先返回父模型。
+
+### 3.5 不新增权限档位
+
+Ask 禁止命令和写入。Execute 是用户对当前执行空间账号的完整授权。进程和 Subagent 不增加
+“受控执行”“仅测试”“可信命令”或逐命令风险等级，也不重复弹出第二套确认。
+
+### 3.6 精简工作区工具
+
+直连模型使用 `workspace_rg` 发现文件和搜索内容，使用 `workspace_read_text` 按行分页读取，
+使用 `workspace_apply_patch` 新增、修改或删除文本文件。新请求不再注入低效的单层目录列表和
+整文件覆盖工具。Ask 提供前两个只读工具；Execute 额外提供补丁工具。
+
+## 4. 功能范围
+
+### 4.1 包含
+
+- 本机 Windows、macOS、Linux 的前台 Shell 命令执行。
+- 当前工作区默认工作目录，以及当前用户可访问的本机工作目录选择。
+- Exit Code、标准输出、标准错误、Shell、目录、耗时和截断状态。
+- 命令超时、用户取消、进程树停止和应用退出清理。
+- 新进程使用当前本机工具环境提供的 Node、Python 和 PATH。
+- 直连模型单层 Subagent 委派、排队、运行、部分结果、失败和取消。
+- 父子请求的工具、模型用量、活动和成果归属。
+- 桌面聊天和选择直连模型的消息通道项目使用相同 Runtime 能力矩阵。
+- 安装包按目标平台和架构携带固定版本 ripgrep，并将其提供给工作区搜索和命令 PATH。
+
+### 4.2 不包含
+
+- 交互式 PTY、终端复用、持续 stdin、密码提示或 TUI 自动化。
+- 后台守护进程、任意 PID 枚举、接管或停止用户已有进程。
+- Shell Session 持久化，环境变更不会跨 `process_execute` 调用保留。
+- 首版远程 SSH 直连模型进程执行。
+- 向 OpenCode、Continue 或 DeepSeek Harness 注入本功能工具。
+- 递归 Subagent、长期运行的自治 Agent、Workflow、Hook 或恢复未完成子任务。
+- 新的权限矩阵、逐命令批准、沙箱档位或命令白名单。
+- 自动安装项目依赖；模型可以在 Execute 中显式运行项目已有的安装命令。
+
+## 5. 功能需求
+
+### FR-1 直连模型专属可用性
+
+- 进程、编程 Subagent 和输出续读工具只由 Runtime provider `model` 注册。
+- Agent Runtime 切换为 OpenCode、Continue 或 DeepSeek Harness 后不再显示这些工具。
+- 图像生成连接不获得文本 Agent 工具。
+- 能力不可用时返回准确原因，不以其他 Runtime 或本机 Shell 静默代替。
+
+### FR-2 跨平台进程执行
+
+- 使用统一的 `process_execute` 工具契约。
+- Windows 选择 PowerShell；macOS/Linux 选择 Bash，Bash 不可用时可使用 POSIX Sh。
+- 每次调用启动一个前台进程树，完成后返回结构化结果。
+- 非零退出码是可观察的命令结果，不自动转成模型请求失败。
+- Shell 启动失败、非法参数或执行后端不可用才属于工具失败。
+
+### FR-3 工作目录和执行位置
+
+- 默认目录是父请求当前工作区。
+- 可选工作目录支持绝对路径、相对工作区路径及指向工作区外目录的路径或符号链接，
+  不额外限制在工作区内；目标必须是实际存在且当前用户可访问的目录。
+- 本机执行只能发生在当前桌面执行空间。
+- 当前请求绑定 SSH 执行空间且没有远端进程后端时不注册工具，绝不在桌面目录回退执行。
+
+### FR-4 Ask/Execute
+
+- Ask 工具清单不包含 `process_execute`。
+- Runtime 边界必须再次拒绝 Ask 发起的伪造命令调用。
+- Execute 命令使用 GoodBuddy 客户端当前用户权限，不声称 Runtime OS 沙箱。
+- 消息通道的直连模型 Execute 继续服从该通道既有工具策略。
+
+### FR-5 Subagent 委派
+
+- `subagent_delegate` 接受一个清晰的任务说明，不要求用户预先创建专家。
+- 子级默认使用父请求选择的直连模型连接。
+- 子级继承父请求的工作模式和能力上限，但不获得再次委派能力。
+- 子级最终输出、部分输出、错误、用量和状态返回父请求。
+- 父模型负责综合结果并向用户作最终回答。
+
+### FR-6 Subagent 领域归属
+
+- 子任务使用 Job/Subjob 语义，不创建 Task Center 条目或独立 Conversation。
+- UI 对象层级继续止于用户 Task；活动可以显示 Subagent 状态卡，但不显示 Job/Run 树。
+- 子任务产生的工具、成果和用量可追溯到父请求及子任务标识。
+
+### FR-7 生命周期和资源边界
+
+- 父请求取消必须传播到活动 Subagent 和其当前进程。
+- Runtime 替换、会话释放和应用退出必须停止 GoodBuddy 创建的活动子进程。
+- 命令、Subagent 提示、单次返回的输出预览、队列和并发有界；完整输出不因超过预览容量而丢弃。
+- 预览省略内容时明确标记并提供续读位置。模型可用 `output_read` 逐页取得完整日志及
+  Subagent 结果，包括失败或取消前已取得的部分输出。
+- Ask 和 Execute 均可续读当前会话的输出。会话或 Runtime 释放后，临时输出删除，旧句柄失效。
+
+### FR-8 环境和凭据
+
+- 新进程使用筛选后的当前用户环境和本机工具环境 PATH。
+- 模型 Provider 凭据、GoodBuddy 加密设置和无关桌面会话变量不进入命令环境。
+- 首版不接受模型提交任意环境变量映射；需要的普通变量由 Shell 命令在单次调用中设置。
+
+### FR-9 状态与活动
+
+- 进程活动显示等待、运行、成功、非零退出、超时、取消和失败。
+- Subagent 显示排队、运行、完成、失败和取消。
+- 命令和子任务失败保留可操作错误及已有部分输出。
+- 同一事件不同时显示页内错误和应用通知。
+
+### FR-10 兼容
+
+- 现有模型连接、MCP 分配、专家设置和 Runtime 选择无需迁移。
+- 不改变现有 Agent Runtime 的工具清单或权限语义。
+- 不修改系统 PATH、Shell Profile 或用户终端会话。
+
+### FR-11 模型请求重试
+
+- 直连文本模型的普通问答、工具轮次和上下文摘要遇到瞬时网络错误或单次请求超时时，
+  在尚未显示文本或推理内容的前提下最多自动重试 3 次。
+- 重试使用递增等待时间并显示当前次数；用户取消必须立即终止等待和后续请求。
+- 一旦本次模型调用已经显示文本或推理内容，不自动重放该调用，避免重复回答。
+- 非网络类 Provider 错误、协议错误和用户取消不进入自动重试。
+
+### FR-12 高效工作区工具
+
+- `workspace_rg` 同时支持内容搜索和文件列表，遵循项目忽略规则，并以
+  `path:line:column:text` 紧凑格式返回匹配。
+- `workspace_read_text` 接受起始行和行数，大文件通过续读完成，不因超过旧的整文件上限而
+  完全不可读；超长单行可使用返回的字节位置继续读取。
+- `workspace_apply_patch` 支持一个补丁新增、修改和删除多个 UTF-8 文件；执行前验证全部
+  路径和 hunk，执行失败时准确报告已完成文件。
+- 搜索和读取在 Ask/Execute 均可用；补丁只在 Execute 可用，Main 调用边界再次检查模式。
+- `workspace_rg` 使用固定参数调用随包 ripgrep，不向模型开放 `--pre` 或任意命令参数。
+- 工作区工具不限制文件总大小、补丁总大小、搜索表达式长度、glob 数量或模型请求的结果
+  数量。单次返回按上下文容量截断或分页；读取结果提供续读位置，搜索结果提示模型缩小查询。
+
+## 6. 产品验收
+
+- [ ] Windows 直连模型 Execute 使用 PowerShell 创建文件、运行测试并读取退出码。
+- [ ] macOS/Linux 直连模型 Execute 使用 Bash/Sh 完成同一工作流。
+- [ ] Ask 中模型看不到进程工具，伪造调用也在 Main 边界失败。
+- [ ] 直连模型可以委派编程子任务，子级运行命令并把结果返回父模型。
+- [ ] Ask Subagent 保持只读；Execute Subagent 不增加第二套批准。
+- [ ] Subagent 不能递归委派，不能切换父请求工作区、模式或模型。
+- [ ] 切换到 OpenCode、Continue 或 DeepSeek Harness 后不出现本功能工具。
+- [ ] 非零退出、超时、取消和输出截断均准确展示。
+- [ ] 模型能续读长输出中未出现在预览内的中间与结尾内容，中文和表情不会导致分页停滞。
+- [ ] 取消父请求和退出应用后没有残留 GoodBuddy 命令进程。
+- [ ] 本机工具环境选择对新命令生效，Main 持有的模型凭据不进入子进程。
+- [ ] 子任务不进入 Task Center，不创建独立可导航 Conversation。
+- [ ] TLS 建连重置和请求超时在未输出内容时最多自动重试 3 次，成功后继续原请求。
+- [ ] 重试等待可取消，已显示部分内容的失败不自动重放。
+- [ ] Ask 可使用 ripgrep 搜索和分页读取，但不能应用补丁。
+- [ ] Execute 可通过一个补丁新增、修改和删除多个工作区文件，并运行测试验证。
+- [ ] Windows、macOS、Linux 的 x64/arm64 安装包均携带对应 ripgrep，且无需系统预装。
+- [ ] 全量测试、类型检查、Lint 和生产构建通过。
@@ -0,0 +1,244 @@
+# 直连模型 Agent 能力功能进度
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 文档类型 | 功能进度 |
+| 状态 | 已实施，本机验收完成 |
+| 版本 | 0.5 |
+| 日期 | 2026-09-09 |
+| 关联入口 | [直连模型 Agent 能力](./README.md) |
+
+## 当前结论
+
+本机生产路径已经完成源码接线：直连模型 Execute 可运行平台 Shell，Ask/Execute 均可按
+父模式委派单层编程 Subagent；长输出可通过 `output_read` 续读。OpenCode、Continue、
+DeepSeek Harness 和托管 SSH 路径不注入这些工具。既有功能的 Windows 本机、真实模型和
+全量项目验证已通过；本次分页验证记录见下方 2026-09-10 条目。macOS 与 Linux 真机验证
+仍需由对应平台完成。
+
+## 2026-09-10 提交审查后的桌面 UI 验收
+
+- Windows 隔离配置使用本轮最终开发构建，通过普通输入框发送触发完整
+  App → Preload → Main → ModelAgentRuntime → ModelToolProvider 路径。
+- Ask 在已保存 `toolApproval: policy` 下完成实际 `workspace_read_text` 与 `workspace_rg`，
+  读取同一专用哨兵，24 字节测试文件与校验值保持不变。未放开 Ask 写工具。
+- 父请求调用实际编程 Subagent；子级在父浏览器归属下完成导航和快照，子级页面显示在
+  父级工作栏 Tab，没有额外空白原生页面。
+- 本组使用确定性 loopback 模型服务，不声称执行了桌面真实 Provider 推理。
+  请求计数、浏览器/终端 UI 场景、明确覆盖边界及清理结果统一记录在
+  [工作栏验收进度](../assistant-workbar/progress.md#2026-09-10-提交审查修复)。
+- 最终整库回归与静态检查结果同见该记录；测试进程已退出，不改变用户安装版或工作区。
+
+## 设计前基线（历史）
+
+- [x] 直连模型当前内置工作区读、目录列表和文本写入，但没有进程工具。
+- [x] 内置 MCP 当前没有 Shell；自定义 MCP 不能替代开箱即用的进程能力。
+- [x] `ModelAgentRuntime` 已有多轮工具循环、取消、上下文压缩和有界结果。
+- [x] DeepSeek Harness 已按 Windows PowerShell、macOS/Linux Bash 注册原生 Shell。
+- [x] OpenCode 和 Continue 使用各自原生执行工具。
+- [x] 专家协作与直连模型可调用的编程工具是不同入口；当前专家继承父请求 Ask/Execute，
+  使用已启用本机直连模型工具并记录工具活动。模式与 authorizer 传递已由
+  `subagent-service.test.ts` 覆盖，不把该单元测试作为额外的真实模型或远程执行验收。
+- [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-09 高效工作区工具
+
+- [x] 新增 `workspace_rg`，以随包 ripgrep 同时提供内容搜索和文件发现；内部解析 JSON，向
+  模型返回紧凑的路径、行号、列号和预览。
+- [x] `workspace_read_text` 改为按行分页读取，大文件不再因旧的整文件 256 KiB 上限完全
+  不可读。
+- [x] 移除搜索表达式、glob 数量、请求结果数、读取行数、补丁大小和目标文件大小的固定上限；
+  单次输出继续分页或截断，超长单行可通过 `offsetBytes` 续读。
+- [x] 新增 `workspace_apply_patch`，支持一个补丁新增、修改和删除多个 UTF-8 文件，并在
+  修改前完成路径和 hunk 验证。
+- [x] Ask 工具清单开放工作区搜索和读取，补丁与进程仍只在 Execute 提供。
+- [x] 设置中的“文件系统操作”更新为“工作区文件”，“编程能力”更新为“开发工具”。
+- [x] 固定 `@vscode/ripgrep` 1.18.0；构建钩子按目标平台/架构从锁定平台包提取二进制，
+  安装包携带当前目标的 `rg` 和 MIT 许可证。
+- [x] 本次聚焦测试 `212 passed, 1 skipped`；全量 `npm run lint` 和
+  `npm run build:bundle` 通过。构建钩子在 Windows x64 实际准备并运行随包
+  ripgrep 15.0.0。
+- [x] 中文文档审校覆盖本目录 7 个 Markdown 文件，阻断项为 0。
+- [ ] 全量 `npm test` 和 `npm run typecheck` 仍受同一工作树中并行开发的浏览器标签页接口及
+  测试夹具修改阻塞；当前类型错误位于 `ipc.test.ts` 和 `browser-tabs-electron-e2e.ts`，最终
+  全量验证需在这些改动稳定后复跑。
+
+## 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`：通过。
+
+## 2026-09-10 进程与 Subagent 完整输出续读
+
+- FR-7 / US-A6：`PagedOutputStore` 完整写入临时输出文件，进程和 Subagent 返回前缀预览
+  与续读引用。JSON 转义计入预览预算，避免 Provider 二次裁剪后丢失续读位置。
+- `ModelToolProvider` 已注册并分发 `output_read`，Ask/Execute 均可读取所属会话输出。
+  工具数量预留一个槽位，页结果不再裁剪。详细字段以 [技术设计](./technical-design.md#44-输出续读)
+  为准。
+- Provider、进程、Subagent、分页存储及共享工具目录五个测试文件共 `73 passed`。
+  覆盖真实 PowerShell stdout/stderr、Subagent 父会话归属、JSON 转义、Unicode 小页面前进、
+  句柄失效、活动调用取消和资源清理。`npm run typecheck`、`npm run lint` 通过。
+- `runtime-e2e.manual.test.ts` 新增真实模型边界场景：运行一次输出超过 96 KiB 的 Node
+  脚本，随机中间与结尾标记均不在预览中；模型经 `output_read` 读到 EOF 后准确返回两个标记。
+  最终带报告的运行 `1 passed, 19 skipped`，上游模型请求精确为 4 次，进程调用 1 次，续读
+  调用 2 次。先前同场景也通过，但其控制台计数未保留，不据此推算两次运行的精确累计调用数。
+- 真实调用使用现有 `RuntimeSettingsStore` 与 Electron `safeStorage` 解密已配置文本连接，
+  凭据仅经测试子进程环境传递。`GOODBUDDY_E2E_OUTPUT_REPORT` 可记录不含凭据、Prompt
+  或输出正文的调用计数；测试工作区和输出存储在结束后释放。
+- 本目录中文文档已按 `deai-writing` 审校，扫描阻断项为 0；保留技术枚举、权限限制和历史
+  验证记录中的明确边界。本次未运行全量测试或生产构建，也不作为其他平台真机验收。
+
+## 2026-09-10 直连工具接线回归修复
+
+- FR-4 / FR-12 / US-B0：普通 Ask 不再依赖可选能力才进入工具循环；明确允许工作区搜索、
+  文本读取和当前会话输出续读绕过 Ask 默认拒绝 authorizer，保留写入、补丁、进程和浏览器
+  的 Ask 拒绝。内部无工具摘要路径不变。
+- FR-5 / FR-7 / US-C1：编程 Subagent 继承父浏览器标签页及所属 Conversation；子级历史和
+  输出仍独立，浏览器资源不转移所有权。回归通过真实 Runtime、Provider 和 Subagent 服务，
+  浏览器使用校验父 Conversation/标签页身份的测试替身，并确认子级结束后父级可继续调用。
+- MCP 已发现工具调用不再触发其他失败服务器的发现重试；覆盖连接失败、清单失败、动态
+  刷新失效、健康调用、配置替换与 dispose 清空。发现重试仍只发生在下一次 `listTools`。
+- 验证命令：`npm test -- --run src/main/agent/model-tool-provider.test.ts src/main/agent/model-runtime.test.ts`。
+  最终结果为 `122 passed, 1 skipped`（Provider 36；Runtime 86 通过、1 跳过）。
+  Ask 回归实际执行随包 ripgrep、工作区分页读取和真实本机输出续读；模型响应均为测试夹具。
+- 本次真实模型调用精确为 0，没有外部网络或远端 Host 操作；未运行全量测试、类型检查、
+  Lint 或构建。桌面 IPC 提示词、浏览器租约生产入口和最小真实模型验收由集成工作继续验证，
+  以上聚焦测试不作为真实浏览器、真实模型或整条桌面路径验收。
+- 源码检查：GoodBuddy Agent 不导入这两个 Runtime/Provider；本机 DeepSeek Harness 的
+  MCP 代理复用 Provider 发现快照规则，托管 SSH Runtime 不经过该本机构造路径。本次未
+  修改远端 Agent、桥接或启动器。
+
+## 进度维护要求
+
+- 只有真实生产路径完成并验证后才能勾选实施项。
+- 平台模拟单元测试不能替代对应平台真实命令测试。
+- 真实模型验证必须记录准确调用次数且不得记录凭据。
+- 需求变化回写 PRD、User Stories 和功能逻辑；实现事实只写本文件。
@@ -0,0 +1,534 @@
+# 直连模型 Agent 能力技术设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-09 |
+| 关联 PRD | [PRD](./prd.md) |
+| 功能逻辑 | [功能逻辑设计](./logic-design.md) |
+| 相关架构 | [助手工作栏与执行空间](../assistant-workbar/prd.md)、[本机工具环境](../local-tool-environment/technical-design.md) |
+
+## 1. 实现基线
+
+当前源码已经实现：
+
+- `ModelAgentRuntime` 的多轮工具调用、上下文压缩、取消、用量和有界结果处理。
+- `ModelToolProvider` 的直连模型内置工具、浏览器、Web、知识和自定义 MCP 聚合。
+- `workspace_rg`、分页 `workspace_read_text` 和 `workspace_apply_patch` 工作区工具。
+- `WorkspaceAccess` 的本机和远端工作区抽象。
+- 跨平台子进程树终止辅助函数。
+- 面向用户专家协作的 `SubagentScheduler` 和状态事件。专家使用具备已启用本机能力的
+  直连模型 Runtime，继承父请求 Ask/Execute 及 authorizer，工具事件记入子任务；
+  Ask 保持只读，不把这些本机工具表述为远程 OpenCode 子会话。
+- OpenCode、Continue 和 DeepSeek Harness 各自的 Shell/Agent 能力。
+- 直连模型 `process_execute`、`subagent_delegate` 和 `output_read`。
+- 不创建顶层 Task/Conversation 的编程 Subagent actor 与活动归并。
+
+## 2. 总体架构
+
+直连模型在 Main 内执行 HTTP，本身没有独立模型进程。跨 Runtime 资源调研中的直连
+部分仅检查历史缓存、会话引用和工具资源释放，不为它新增进程池；分析与验证范围
+见 [Runtime 资源技术设计 §7.2](../assistant-workbar/runtime-process-reuse-technical-design.md#72-直连模型及历史详情)。
+以下当前功能不因此改变，进程工具产生的子进程仍按各自会话生命周期管理。
+
+```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 上限。
+
+## 工作区工具契约
+
+### 工具输入与执行
+
+- `workspace_rg` 接受 `pattern`、相对目录、glob、固定字符串、忽略大小写、文件列表模式和
+  最大结果数。Main 固定追加 `--no-config`，内容搜索读取 `--json`，对模型返回紧凑文本。
+- `workspace_read_text` 接受 `path`、从 1 开始的 `offset` 和 `limit`，通过现有
+  `WorkspaceAccess.readText` 字节分页组装带行号结果；`offsetBytes` 提供原始字节续读，
+  覆盖跨多个页面的超长单行。
+- `workspace_apply_patch` 接受一个 `*** Begin Patch` 文本，支持 `Add File`、`Update File`
+  和 `Delete File`。全部操作先解析并验证；更新文件保留原换行和权限位，单文件原子替换。
+- Ask 只注册前两个只读工具；Execute 注册全部三个工具。旧的目录列表和整文件覆盖不再进入
+  新工具清单。
+- 输入和目标文件不设固定总量上限。单次工具结果仍遵守直连模型上下文边界；读取返回续读
+  位置，搜索截断时要求模型缩小路径、glob 或表达式。
+
+### 读取与搜索失败恢复
+
+`workspace_read_text` 和 `workspace_rg` 的输入校验及预期工作区错误由 `ModelToolProvider`
+转为 `RecoverableModelToolError`，保留原始 cause。范围包括 schema 校验失败、绝对路径或
+越界路径、目标不存在或类型不符、无效 UTF-8、无效读取范围，以及 `ENOENT`、`ENOTDIR`、
+`EISDIR`、`EACCES`、`EPERM`、`ELOOP`、`ENAMETOOLONG` 等已列明的文件系统错误。
+Runtime 向模型返回 `{ ok: false, recoverable: true, error, nextAction }` 的 JSON 文本工具结果，
+工具活动记为 `recoverable`，继续工具循环，由模型修正路径、分页参数、glob 或搜索表达式；
+提示不得原样重复失败参数。取消、远端断线、失效工作区、缺失 rg 可执行文件及未分类的内部
+错误继续向外传播，不转为可恢复结果。
+
+读取和搜索仍只接受工作区内相对路径，绝对路径即使指向工作区内文件也拒绝；原有越界及
+符号链接检查继续生效。仅当本机直连模型 Execute 的 `process_execute` 实际可用时，恢复
+提示才建议用它访问工作区外文件。此处理不改变 Windows 用户权限、UAC 或文件 ACL，
+也不提升进程权限；Ask 仍保持只读。
+
+ripgrep 结果按退出状态处理：
+
+- exit 1 保持正常无匹配结果。
+- exit 2 有 stdout 且不是 regex/glob 编译错误时，保留已取得的匹配或文件列表，附加
+  `incomplete search coverage` 警告及有界 stderr。零匹配只代表已搜索部分，不能据此断言
+  整个目标不存在匹配；输出截断提示仍独立保留。
+- exit 2 无 stdout，或出现无效 regex/glob 编译错误时，搜索层抛错，再由 Provider 转为
+  上述可恢复结果；模型可修正表达式，字面搜索可使用 `fixedStrings`。
+
+该契约属于桌面 `ModelAgentRuntime → ModelToolProvider` 内置工具路径，复用浏览器标签页
+关闭和元素引用失效已有的可恢复错误机制；浏览器分别提示 `browser_navigate` 或
+`browser_snapshot`，路由规则见[浏览器技术设计](../assistant-workbar/browser-tabs-technical-design.md#61-兼容阶段)。
+`workspace_read_text` 若使用 `RemoteWorkspaceAccess`，仍经同一 Provider 分类远端
+`data.code` 中的预期文件系统和路径/文本错误。Agent daemon 的 RPC 错误序列化保留
+`ENOENT` 等大写系统错误码，避免远端文件不存在被误判为不可恢复错误；远端原生工具
+处理不变。内置 rg 仍仅支持本机工作区，托管 SSH 当前仍使用远端 OpenCode 原生工具，
+不因共享读取抽象而开放远端直连模型，见[远程 Runtime 边界](../remote-host/technical-design.md#runtime)。
+
+### ripgrep 打包
+
+固定依赖 `@vscode/ripgrep`，构建钩子根据 Electron 目标选择对应 Windows、macOS 或 Linux
+x64/arm64 平台包，使用 lockfile integrity 校验后提取 `rg`。安装包只复制当前目标二进制和
+MIT 许可证。运行时通过 `BundledRuntimePaths.ripgrep` 使用绝对路径，并将所在目录放到直连
+模型进程 PATH 前部。
+
+## 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
+  stdoutReference?: PagedOutputReference
+  stderrReference?: PagedOutputReference
+}
+```
+
+`cwd` 在工作区内返回相对显示值，根目录为 `.`；工作区外返回规范化绝对路径，准确说明
+命令实际执行位置。Shell 在模型结果中只返回稳定标签；绝对可执行路径只进入 Main 诊断状态。
+
+### 4.3 输出边界
+
+- stdout 和 stderr 各返回最多 96 KiB 的前缀预览，JSON 转义后的内容也计入预览预算。
+- `PagedOutputStore` 将流式输出完整写入系统临时目录，内存只保留预览；超限后继续写盘。
+  存储失败明确报错，不把缺失内容标记为完整结果。
+- 预览省略内容时返回 `stdoutReference` 或 `stderrReference`，包含 `handle`、`nextCursor`
+  和 `totalBytes`。短输出返回完整文本并删除临时文件，不附带句柄。
+- JSON 结果加上元数据后必须低于 `ModelToolProvider` 现有 256 KiB 工具结果上限。
+- 输出按 UTF-8 解码，无效序列使用替换字符并保留字节计数。
+
+### 4.4 输出续读
+
+`output_read` 接受严格对象 `{ handle, cursor?, limitBytes? }`：`cursor` 为从 0 开始的 UTF-8
+字节位置，省略时从头读取；`limitBytes` 为 1 至 32,768 的整数，默认 32,768。页面返回
+`{ handle, content, cursor, nextCursor, totalBytes, eof }`，模型沿 `nextCursor` 读取至 `eof`。
+页面在字符边界结束；若请求大小容不下首个完整字符，最多扩展到 4 字节，保证续读前进。
+位于 UTF-8 延续字节的输入 cursor、负数、越界和未知字段均拒绝。
+
+Provider 根据 `process:` 或 `subagent:` 前缀选择服务，以当前 `conversationId` 校验所有者，
+不接受模型另传 owner。Ask/Execute 均可用，工具总数为此预留一个槽位；不要求本轮能够启动
+命令或再次委派。分页结果直接 JSON 序列化，不进行二次文本裁剪，以免 cursor 与内容不一致。
+32 KiB 的页面即使全部需要 JSON 转义，也能保留在现有工具结果容量内。
+
+进程输出归属调用会话，Subagent 最终输出归属父会话。子级临时会话释放后，父模型仍能续读
+Subagent 结果。会话释放会等待活动调用结算再删除所属文件；服务退出关闭写入句柄并删除临时
+目录。输出不写入 SQLite，不跨 Runtime 重启恢复。
+
+## 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 清单。
+- Execute 子级经 `ModelSubagentRequestContext` 继承父 `browserTabId` 和浏览器所属
+  `browserConversationId`。后者只在 Main 内部请求与工具上下文中传递：浏览器操作使用父
+  Conversation，历史与分页输出仍使用子 Conversation。子级不新建标签页或申请使用租约，
+  结束时只释放自己的临时会话，父标签页和租约仍由父请求生命周期管理。
+
+### 7.3 调度和结果
+
+- 复用 `SubagentScheduler` 的取消、并发和队列模式。
+- 全局最大并发 3，队列最大 20。
+- 单个子任务最长 10 分钟；父请求更早取消时立即停止。
+- 文本预览最多 192 KiB，JSON 转义也计入预算；错误最多 2 KiB。省略的正文通过
+  `outputReference` 续读，字段与生命周期沿用第 4.4 节，完整输出不受预览容量限制。
+- 模型用量逐事件归属父请求和 `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` 等待有界清理，不因模型或子进程不响应而阻塞应用退出。
+
+### 8.1 Ask 工具循环
+
+普通 Ask 请求进入工具循环，不再依赖知识、联网搜索或 Subagent 是否启用。Runtime 对
+`workspace_rg`、`workspace_read_text`、`output_read` 三个明确只读工具免去 Ask authorizer
+调用，避免生产 authorizer 的默认拒绝使已列出的只读工具无法执行。Execute 仍沿用既有
+authorizer；补丁、进程和其他写入不因此获准。Provider 按清单和调用边界继续校验模式，
+浏览器工具不加入 Ask 免审批集合。内部上下文摘要使用 `noModelTools`，保留无工具问答路径。
+
+### 8.2 MCP 发现与调用
+
+`listTools` 发现 MCP 并保存当前绑定快照；已知工具调用只查该快照，不在每次调用前重试
+其他失败服务器。未知名称直接失败。失败服务器只在下一次发现入口重试，动态清单刷新失败
+时从新快照中移除该服务器工具，下一次发现再刷新；健康连接继续复用。
+
+绑定只在 Provider 内存中存在，`dispose` 与连接缓存一起清空。MCP 配置保存通过
+`refreshCapabilities → onRuntimeSettingsChanged → reconfigureRuntimes` 替换 Runtime，
+`SelectedRuntimeManager.reset` 使后续请求创建新 Provider；退役 Runtime 按原有会话生命周期
+清理。没有新增持久缓存、失败重试日志或配置兼容层。
+
+DeepSeek Harness 的 Main 工具代理必须使用仅包含分配 MCP 和 Web 的 Provider 视图，不能因为
+共享 `ModelToolProvider` 类而自动看到直连模型编程工具。
+
+## 9. 事件与活动
+
+### 9.1 进程事件
+
+继续使用现有 Runtime `tool` 事件：
+
+- `pending`：参数已接收。
+- `running`：Shell 已成功启动。
+- `completed`：返回 exit 0 或非零退出结果。
+- `failed`：启动或契约失败。
+- `cancelled`：父请求取消。
+
+结果包含 Shell、工作目录、退出码、耗时、输出预览和续读引用，不写应用诊断日志。
+通用工具活动仍显示有界摘要，模型通过 `output_read` 取得的页面记为后续工具活动。
+
+### 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 网络错误
+码；每次尝试创建独立超时信号。退避等待监听父请求取消。只有完整模型轮次返回后才执行
+工具，因此未产生可见文本或推理内容的重试不会重复执行工具。
+
+模型回复本身不设固定字节上限：流式响应、非流式回复、模型工具参数、请求上下文和工具
+结果总量都由请求超时、取消和上下文压缩控制，长回复和大工具结果不会被中断。图像生成
+响应仍按可解码图片大小校验。
+
+会话历史在请求校验、Renderer 发送与保存、SQLite 读写和直连模型缓存中均保留完整消息，
+不按消息条数、单条文本长度或累计文本量裁剪。上下文大小由现有压缩策略和模型上下文窗口
+处理。Continue 接收完整历史，已有有效摘要只替换其覆盖的前缀，剩余消息全部交给原生
+Runtime；GoodBuddy 不再额外保留最后 20 条或限制为 128,000 字符。
+
+## 11. 性能
+
+- Shell 探测按执行服务实例缓存，不在每轮模型调用重复探测。
+- stdout/stderr 边读边写入临时文件，内存仅保存有界预览；续读每次只读取一页。
+- 子级共享父请求已解析的模型配置和工具服务，不复制 MCP 配置或持久状态。
+- 不增加持久 Shell、后台 daemon、工作区快照或恢复状态机。
+- 命令执行不使用 PTY，避免普通构建和测试承担终端渲染成本。
+
+## 12. 测试策略
+
+### 12.1 单元测试
+
+- 工具可见性矩阵和 Runtime target 过滤。
+- Ask 伪造进程调用拒绝。
+- Windows PowerShell、POSIX Bash/Sh 选择和参数。
+- cwd 默认、相对子目录、绝对路径、工作区外目录、指向外部的符号链接和不存在的目录。
+- exit 0、非零退出、spawn 失败、超时、取消和输出截断。
+- 输出预览加分页能还原全文，包括 JSON 转义文本、中文、表情和字面替换字符；覆盖一字节
+  页面前进、跨会话拒绝、活动调用释放、短输出删除及服务退出清理。
+- 环境筛选、本机工具 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。
+
+输出边界场景复用 `runtime-e2e.manual.test.ts`：真实模型运行一次专用 Node 脚本，输出超过
+96 KiB，并在预览之后生成随机中间与结尾标记。模型必须通过生产 `output_read` 连续读到 EOF，
+最终回答包含两个标记。测试限制工具为进程与续读，记录上游请求数和工具调用数；凭据由现有
+加密设置解密后仅在内存及测试子进程环境中传递。
+
+### 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 不可用不能阻止普通对话。
@@ -0,0 +1,150 @@
+# 直连模型 Agent 能力 UI 设计
+
+## 文档信息
+
+| 项目 | 内容 |
+| --- | --- |
+| 状态 | 已实施 |
+| 版本 | 0.4 |
+| 日期 | 2026-09-09 |
+| 设计系统 | [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 标题与摘要
+
+正常执行状态的操作摘要遵循[工具操作摘要规则](../assistant-workbar/runtime-interactions.md#工具操作摘要)，从原始调用参数提取并在完成后保留；异常状态继续显示原有提示。
+
+```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. 预览省略提示与工具结果中的续读引用。
+
+日志使用共享等宽字体和可选择文本。长输出在活动块内折叠，展开后仍保持工作栏和聊天布局
+可用；不把完整日志复制为应用通知。
+
+模型使用 `output_read` 续读时显示普通工具活动“续读工具输出”。活动展开只展示该次返回的
+摘要，不等同于自动加载完整日志；当前不增加手动分页按钮。
+
+## 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，s 秒后）”与
+  “〈模型名〉正在重试请求（n/3），等待响应”；只有退避结束且未取消才显示后者。
+  初始请求显示“〈模型名〉请求处理中”，不把尚无输出的等待描述成思考。
+- 不增加独立按钮、弹窗或通知副本；用户仍可使用当前停止操作取消请求。
+  底部静态状态点、工具进展、待回答及终态优先规则由
+  [消息底部请求状态](../assistant-workbar/runtime-interactions.md#消息底部请求状态)统一定义。
+
+## 7. 键盘与无障碍
+
+- 活动块展开按钮使用原生 `button`，提供 `aria-expanded` 和关联详情 ID。
+- 状态变化通过现有活动区域的礼貌级 live region 发布，不逐个朗读流式日志。
+- stdout/stderr 区域具有可见标签，不能只靠顺序区分。
+- 焦点不会因后台状态更新自动移动。
+- 取消父请求后的焦点保持在原取消按钮或恢复到 Composer。
+- 浅色、深色和减少动态效果模式遵守统一设计系统。
+
+## 8. 响应式
+
+- 窄聊天区只保留工具名、状态和一行摘要，元数据换行到下一行。
+- 日志区域横向滚动，不撑宽页面。
+- 运行记录使用紧凑摘要，不复制完整 stdout/stderr；用户回到聊天活动块展开查看详情。
--- a/Show More
+++ b/Show More