docs(openspec): 收紧当前 Thread 引用并定义低成本 Prompt Cache 架构

.env.example

@@ -31,6 +31,19 @@ EVAL_MODEL_ID=
 EVAL_CANDIDATE=
 EVAL_RUN_ID=
 
+# === Thread Chat Prompt Cache（服务端专用） ===
+# off：旧/无缓存控制；observe：只记录候选前缀；enabled：仅已验证 Route 发送缓存参数。
+# 首次部署保持 off，经 fake + staging provider probe 后再按 Route 开启。
+THREAD_PROMPT_CACHE_MODE=off
+# OpenRouter 等支持粘性路由时，用此高熵 secret 生成用户+Project+模型隔离的 HMAC；
+# 原始 user/project/thread id 不会发送给上游。
+THREAD_PROMPT_CACHE_AFFINITY_SALT=
+# 第一阶段只采用 Provider 默认短时缓存（支持时约 5 分钟）。
+# 1 小时 Extended TTL 保持关闭，直到真实间隔/费用与 retention/ZDR 审查证明净节省。
+THREAD_PROMPT_CACHE_EXTENDED_TTL_ENABLED=false
+# L2 只缓存应用侧编译结果，不减少模型 Token；默认 noop，当前不需要 Redis。
+THREAD_PROMPT_COMPILED_SEGMENT_CACHE=off
+
 # === OpenRouter（固定路由的 Thread Chat 模型） ===
 OPENROUTER_API_KEY=
 # 可选：OpenRouter 排行榜/控制台中的应用归因；留空时不会发送对应 header。

.github/workflows/prompt-cache-apply.yml

@@ -0,0 +1,34 @@
+name: Prompt Cache Apply
+
+on:
+  pull_request:
+    paths:
+      - "constants/thread-chat-quote.ts"
+      - "lib/thread-chat/**"
+      - "lib/chat/thread-chat-prompt.ts"
+      - "app/thread-chat/chat/composer/quote-draft.ts"
+      - "e2e/thread-chat/prompt-cache-*.test.mjs"
+      - ".github/workflows/prompt-cache-apply.yml"
+      - "openspec/changes/optimize-thread-chat-prompt-cache/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Typecheck
+        run: pnpm typecheck
+      - name: Quote and cache contracts
+        run: node --import tsx e2e/thread-chat/prompt-cache-quote-contract.test.mjs
+      - name: OpenSpec strict validation
+        run: pnpm exec openspec validate --all --strict

.github/workflows/prompt-cache-baseline.yml

@@ -0,0 +1,106 @@
+name: Prompt Cache Base Baseline
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/prompt-cache-baseline.yml"
+      - "openspec/changes/optimize-thread-chat-prompt-cache/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  record-baseline:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: thread_chat_base_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d thread_chat_base_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    env:
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/thread_chat_base_test
+      DIRECT_URL: postgres://postgres:postgres@localhost:5432/thread_chat_base_test
+      TEST_DATABASE_URL: postgres://postgres:postgres@localhost:5432/thread_chat_base_test
+      EVAL_DATABASE_URL: postgres://postgres:postgres@localhost:5432/thread_chat_base_eval_test
+      EVAL_ALLOW_DATABASE_WRITES: "true"
+      EVAL_DATABASE_GUARD_TOKEN: prompt-cache-base-guard-token-2026
+      BETTER_AUTH_SECRET: prompt-cache-base-better-auth-secret-2026
+      BETTER_AUTH_URL: http://localhost:4040
+      MINIMAX_API_KEY: fake-ci-key
+      AI_TELEMETRY_ENABLED: "false"
+      AI_DEVTOOLS_ENABLED: "false"
+      AI_LANGFUSE_ENABLED: "false"
+    steps:
+      - name: Checkout Base branch
+        uses: actions/checkout@v4
+        with:
+          ref: codex/feat-agent-observability-evaluation
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.32.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Prepare databases
+        env:
+          PGPASSWORD: postgres
+        run: |
+          createdb -h localhost -U postgres thread_chat_base_eval_test || true
+          psql -h localhost -U postgres -d postgres -v ON_ERROR_STOP=1 \
+            -c "ALTER DATABASE thread_chat_base_eval_test SET thread_chat.evaluation_guard TO 'prompt-cache-base-guard-token-2026'"
+          pnpm db:migrate
+          pnpm db:test:setup
+          pnpm db:test:migrate
+          DATABASE_URL="$EVAL_DATABASE_URL" DIRECT_URL="$EVAL_DATABASE_URL" pnpm db:migrate
+      - name: Record baseline checks
+        id: baseline
+        shell: bash
+        run: |
+          set +e
+          : > baseline-results.tsv
+          run_check() {
+            name="$1"
+            shift
+            echo "::group::$name"
+            "$@"
+            code=$?
+            echo "::endgroup::"
+            printf '%s\t%s\n' "$name" "$code" >> baseline-results.tsv
+          }
+          run_check typecheck pnpm typecheck
+          run_check build env NODE_ENV=production pnpm build
+          run_check thread-chat-gate1-db pnpm test:thread-chat:gate1-db
+          run_check thread-chat-gate2-api pnpm test:thread-chat:gate2-api
+          run_check observability pnpm test:observability
+          run_check agent-evals pnpm test:agent-evals
+          run_check openspec pnpm openspec:validate
+          {
+            echo '## Prompt Cache Base Baseline'
+            echo
+            echo '| Check | Exit code |'
+            echo '|---|---:|'
+            while IFS=$'\t' read -r name code; do
+              echo "| $name | $code |"
+            done < baseline-results.tsv
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit 0
+      - name: Upload baseline record
+        uses: actions/upload-artifact@v4
+        with:
+          name: prompt-cache-base-baseline
+          path: baseline-results.tsv
+          retention-days: 30

.github/workflows/prompt-cache-final.yml

@@ -0,0 +1,116 @@
+name: Prompt Cache Final Verification
+
+on:
+  pull_request:
+    paths:
+      - "constants/**"
+      - "lib/ai/**"
+      - "lib/chat/**"
+      - "lib/thread-chat/**"
+      - "app/thread-chat/**"
+      - "app/api/thread-chat/**"
+      - "e2e/**"
+      - "evals/**"
+      - "scripts/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/prompt-cache-final.yml"
+      - "openspec/changes/optimize-thread-chat-prompt-cache/**"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  full-verification:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    services:
+      postgres:
+        image: pgvector/pgvector:pg17
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: thread_chat_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d thread_chat_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 20
+    env:
+      NODE_ENV: test
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/thread_chat_test
+      DIRECT_URL: postgres://postgres:postgres@localhost:5432/thread_chat_test
+      TEST_DATABASE_URL: postgres://postgres:postgres@localhost:5432/thread_chat_test
+      EVAL_DATABASE_URL: postgres://postgres:postgres@localhost:5432/thread_chat_eval_test
+      EVAL_ALLOW_DATABASE_WRITES: "true"
+      EVAL_DATABASE_GUARD_TOKEN: prompt-cache-ci-guard-token-2026
+      BETTER_AUTH_SECRET: prompt-cache-ci-better-auth-secret-2026
+      BETTER_AUTH_URL: http://localhost:4040
+      MINIMAX_API_KEY: fake-ci-key
+      AI_TELEMETRY_ENABLED: "false"
+      AI_DEVTOOLS_ENABLED: "false"
+      AI_LANGFUSE_ENABLED: "false"
+      THREAD_PROMPT_CACHE_MODE: observe
+      THREAD_PROMPT_CACHE_EXTENDED_TTL_ENABLED: "false"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.32.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+      - name: Prepare evaluation database
+        env:
+          PGPASSWORD: postgres
+        run: |
+          createdb -h localhost -U postgres thread_chat_eval_test || true
+          psql -h localhost -U postgres -d postgres -v ON_ERROR_STOP=1 \
+            -c "ALTER DATABASE thread_chat_eval_test SET thread_chat.evaluation_guard TO 'prompt-cache-ci-guard-token-2026'"
+          DATABASE_URL="$EVAL_DATABASE_URL" DIRECT_URL="$EVAL_DATABASE_URL" pnpm db:migrate
+      - name: Apply application migrations
+        run: pnpm db:migrate
+      - name: Prepare normalized Thread Chat test database
+        run: pnpm db:test:setup && pnpm db:test:migrate
+      - name: Typecheck
+        run: pnpm typecheck
+      - name: Lint
+        run: pnpm lint
+      - name: Production build
+        run: pnpm build
+      - name: Prompt cache architecture guard
+        run: node scripts/check-prompt-cache-architecture.mjs
+      - name: Prompt cache and Quote contracts
+        run: >-
+          pnpm test:thread-chat:prompt-cache &&
+          pnpm test:thread-chat:prompt-cache-eval &&
+          pnpm test:thread-chat:composer-quotes &&
+          node --import tsx e2e/thread-chat/fork-origin-contract.test.mjs &&
+          node --import tsx e2e/thread-chat/quote-resolver-contract.test.mjs &&
+          node --import tsx e2e/thread-chat/prompt-cache-adapter.test.mjs &&
+          node --import tsx e2e/thread-chat/prompt-cache-compiler-boundaries.test.mjs &&
+          node --import tsx e2e/thread-chat/prompt-cache-rollout.test.mjs &&
+          node --import tsx e2e/thread-chat/prompt-cache-state.test.mjs &&
+          pnpm prompt-cache:probe
+      - name: Thread Chat database and protocol gates
+        run: >-
+          pnpm test:thread-chat:gate1-db &&
+          pnpm test:thread-chat:gate2-session &&
+          pnpm test:thread-chat:gate2-pipeline &&
+          pnpm test:thread-chat:gate2-db &&
+          pnpm test:thread-chat:gate2-api &&
+          pnpm test:thread-chat:gate2-api-db &&
+          pnpm test:thread-chat:gate3-client &&
+          pnpm test:thread-chat:gate4-cutover
+      - name: Observability suite
+        run: pnpm test:observability
+      - name: Agent evaluation suite
+        run: pnpm test:agent-evals
+      - name: OpenSpec strict validation
+        run: pnpm openspec:validate

.github/workflows/prompt-cache-probe.yml

@@ -0,0 +1,32 @@
+name: Prompt Cache Probe
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "17 4 * * 3"
+
+permissions:
+  contents: read
+
+jobs:
+  fake-contract-probe:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Warm and reuse the fake provider prefix
+        run: >-
+          node --import tsx scripts/probe-thread-chat-prompt-cache.ts
+          --mode=fake
+          --output=evals/agent/results/local/prompt-cache-probe.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: prompt-cache-fake-probe
+          path: evals/agent/results/local/prompt-cache-probe.json
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/prompt-cache-scheduled.yml

@@ -0,0 +1,32 @@
+name: Prompt Cache Scheduled Probe
+
+on:
+  schedule:
+    - cron: "37 5 * * 1"
+  workflow_dispatch:
+
+jobs:
+  fake-cache-probe:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10.32.1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Warm-up and reuse probe
+        run: node --import tsx scripts/probe-prompt-cache.ts > prompt-cache-probe.json
+      - name: Quality and cache eval gate
+        run: node --import tsx e2e/observability/prompt-cache-eval.test.mjs
+      - name: Upload reproducible probe evidence
+        uses: actions/upload-artifact@v4
+        with:
+          name: prompt-cache-fake-probe-${{ github.sha }}
+          path: prompt-cache-probe.json
+          if-no-files-found: error
+          retention-days: 30