Merge remote-tracking branch 'origin/master' into 2026-09-26_model-endpoint-patterns
@@ -6,7 +6,7 @@
|
||||
"plugins": [
|
||||
{
|
||||
"name": "billion-context",
|
||||
"version": "0.1.205",
|
||||
"version": "0.1.213",
|
||||
"source": {
|
||||
"source": "local",
|
||||
"path": "./plugins/codex"
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
"name": "billion-context",
|
||||
"source": "./",
|
||||
"description": "Context-compression plugin for Claude Code · month-long single sessions (billions of tokens) · high compression quality even in small context windows (100K is enough) · 5× fewer tokens",
|
||||
"version": "0.1.205",
|
||||
"version": "0.1.213",
|
||||
"author": {
|
||||
"name": "ranxianglei"
|
||||
},
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "billion-context",
|
||||
"version": "0.1.205",
|
||||
"version": "0.1.213",
|
||||
"description": "Context-compression plugin for Claude Code · month-long single sessions (billions of tokens) · high compression quality even in small context windows (100K is enough) · 5× fewer tokens",
|
||||
"author": {
|
||||
"name": "ranxianglei"
|
||||
|
||||
@@ -13,6 +13,7 @@ on:
|
||||
jobs:
|
||||
publish:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
name: Announcements Lint
|
||||
|
||||
# #5548 P3: validate announcements/remote.json with the SAME module the client
|
||||
# parses it with, so a bad feed entry is rejected pre-merge instead of
|
||||
# failing open (silently invisible) on every install after the push.
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "announcements/**"
|
||||
- "scripts/validate-remote-announcements.ts"
|
||||
- "src/remote-notices.ts"
|
||||
push:
|
||||
branches: [master]
|
||||
paths:
|
||||
- "announcements/**"
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
|
||||
- name: Install dependencies
|
||||
run: npm ci
|
||||
|
||||
# #2092: the validator transitively imports src modules that resolve
|
||||
# acp-kernel to its built dist (file:./kernel link, inlined at bundle
|
||||
# time) — same prerequisite as the main test matrix in ci.yml.
|
||||
- name: Build in-repo kernel
|
||||
run: npm --prefix kernel run build
|
||||
|
||||
- name: Validate remote announcement feed
|
||||
run: node --import tsx scripts/validate-remote-announcements.ts
|
||||
@@ -1,307 +0,0 @@
|
||||
name: Backport carry PRs (label `backport` → instant copy PR onto the patch lane)
|
||||
|
||||
on:
|
||||
# Owner flow: apply the `backport` label to ANY OPEN fix PR (merging it into
|
||||
# master later is independent — some fixes are temporary and never reach
|
||||
# master). Instantly a CARRY PR appears: the PR's own commits cherry-picked
|
||||
# onto the current patch lane `bugfix-v<latest-tag>` (cut from the tag if the
|
||||
# lane does not exist yet). Conflicts never disappear: they stay visible
|
||||
# inside the carry PR / the receipt until a human resolves them.
|
||||
pull_request:
|
||||
types: [labeled]
|
||||
# Repair / manual path (re-run after a token hiccup, or backport something
|
||||
# that predates the bot). Reads live PR state through the API, so it also
|
||||
# works for already-merged PRs.
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
pr:
|
||||
description: "PR number to (re)carry"
|
||||
required: true
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
actions: write
|
||||
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
jobs:
|
||||
carry:
|
||||
runs-on: ubuntu-latest
|
||||
concurrency:
|
||||
group: backport-carry-${{ github.event.pull_request.number || github.event.inputs.pr || 'dispatch' }}
|
||||
cancel-in-progress: false
|
||||
env:
|
||||
GITHUB_REPOSITORY: ${{ github.repository }}
|
||||
# No github.event.pull_request.* context here: it is EMPTY on
|
||||
# workflow_dispatch and would silently disable the fork/lane-base gates;
|
||||
# the gate step reads all PR facts live from the API.
|
||||
PR_NUMBER: ${{ github.event.pull_request.number || github.event.inputs.pr || '' }}
|
||||
steps:
|
||||
- name: Resolve the source PR
|
||||
run: |
|
||||
set -uo pipefail
|
||||
if [ -z "$PR_NUMBER" ]; then
|
||||
echo "::notice::no pull_request/labeled event and no pr input — nothing to do"
|
||||
exit 0
|
||||
fi
|
||||
echo "source PR: #$PR_NUMBER"
|
||||
|
||||
- name: Read the source PR
|
||||
id: gate
|
||||
if: env.PR_NUMBER != ''
|
||||
run: |
|
||||
set -euo pipefail
|
||||
gh api repos/"$GITHUB_REPOSITORY"/pulls/"$PR_NUMBER" > "$RUNNER_TEMP/pr.json"
|
||||
TITLE="$(jq -r '.title' "$RUNNER_TEMP/pr.json")"
|
||||
HAS_LABEL="$(jq -r '[.labels[]?.name] | contains(["backport"])' "$RUNNER_TEMP/pr.json")"
|
||||
echo "title=$TITLE labeled=$HAS_LABEL"
|
||||
if [ "$HAS_LABEL" != "true" ]; then
|
||||
echo "::notice::PR #$PR_NUMBER does not carry the 'backport' label — ignoring"
|
||||
exit 0
|
||||
fi
|
||||
LIVE_BASE="$(jq -r '.base.ref' "$RUNNER_TEMP/pr.json")"
|
||||
LIVE_HEAD_REPO="$(jq -r '.head.repo.full_name' "$RUNNER_TEMP/pr.json")"
|
||||
case "$LIVE_BASE" in
|
||||
bugfix-v*) echo "::notice::PR #$PR_NUMBER targets the patch lane itself — nothing to carry"; exit 0 ;;
|
||||
esac
|
||||
if [ "$LIVE_HEAD_REPO" != "$GITHUB_REPOSITORY" ]; then
|
||||
{
|
||||
echo "(ai: zai/glm-5.3) **backport carry**: the head lives in a FORK — this bot only carries same-repo branches. Carry it by hand:"
|
||||
echo
|
||||
echo '```bash'
|
||||
echo "LANE=\$(git ls-remote --heads origin 'bugfix-v*' | awk '{print \$NF}' | sed 's|refs/heads/||' | sort -V | tail -1)"
|
||||
echo "git checkout -b <fix-branch> origin/\$LANE && git pull"
|
||||
echo "git cherry-pick -x <the commit shas of this PR>"
|
||||
echo "git push origin HEAD:<fix-branch> # then open a PR against \$LANE, label it backport-carry"
|
||||
echo '```'
|
||||
} | gh api repos/"$GITHUB_REPOSITORY"/issues/"$PR_NUMBER"/comments -F body=@-
|
||||
exit 0
|
||||
fi
|
||||
echo "gated=true" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Idempotency — prior carry marker / source moved past its pin
|
||||
if: steps.gate.outputs.gated == 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
MARKER="$(gh api repos/"$GITHUB_REPOSITORY"/issues/"$PR_NUMBER"/comments --paginate \
|
||||
--jq '.[] | select(.body | contains("<!-- backport-carry-marker")) | .body' | tail -n 1)"
|
||||
if [ -n "$MARKER" ]; then
|
||||
PIN="$(printf '%s' "$MARKER" | sed -n 's/.*pin:\([0-9a-f]*\).*/\1/p')"
|
||||
LIVE_PIN="$(jq -r '.head.sha' "$RUNNER_TEMP/pr.json")"
|
||||
if [ "$PIN" = "$LIVE_PIN" ]; then
|
||||
echo "::notice::already carried at pin $PIN and the source did not move — no-op"
|
||||
exit 0
|
||||
fi
|
||||
echo "::notice::source moved past pin ${PIN:0:8} (now ${LIVE_PIN:0:8}) — rebuilding the existing carry"
|
||||
fi
|
||||
|
||||
- uses: actions/checkout@v4
|
||||
if: steps.gate.outputs.gated == 'true'
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Resolve the current patch lane (bugfix-v<latest tag>)
|
||||
id: lane
|
||||
if: steps.gate.outputs.gated == 'true'
|
||||
run: |
|
||||
set -euo pipefail
|
||||
LAST="$(git tag --list 'v[0-9]*' --sort=-v:refname | head -1)"
|
||||
[ -n "$LAST" ] || { echo "::error::no v* tags found"; exit 1; }
|
||||
LANE="bugfix-v${LAST#v}"
|
||||
git fetch -q origin "+refs/heads/$LANE:refs/remotes/origin/$LANE" --tags || true
|
||||
if ! git show-ref --verify --quiet "refs/remotes/origin/$LANE"; then
|
||||
git checkout -q -B "_cut-$LANE" "refs/tags/$LAST"
|
||||
if git push -q origin "HEAD:$LANE"; then
|
||||
echo "::notice::cut lane $LANE from tag $LAST (no carried fixes existed yet)"
|
||||
else
|
||||
echo "::notice::lane $LANE appeared mid-run (another carry cut it) — using it"
|
||||
git fetch -q origin "+refs/heads/$LANE:refs/remotes/origin/$LANE"
|
||||
fi
|
||||
fi
|
||||
echo "name=$LANE" >> "$GITHUB_OUTPUT"
|
||||
git checkout -q -B "_work" "origin/$LANE"
|
||||
echo "patch lane: $LANE @ $(git rev-parse --short HEAD)"
|
||||
|
||||
- name: Cherry-pick the PR's own commits onto a carry branch
|
||||
id: pick
|
||||
if: steps.gate.outputs.gated == 'true'
|
||||
run: |
|
||||
set -uo pipefail
|
||||
LANE="${{ steps.lane.outputs.name }}"
|
||||
CARRY="backport/carry-$PR_NUMBER"
|
||||
SRC_SHA="$(jq -r '.head.sha' "$RUNNER_TEMP/pr.json")"
|
||||
SHORT="${SRC_SHA:0:8}"
|
||||
# Exact-sha fetch first (works while the source branch still exists);
|
||||
# the pull ref survives closed PRs and deleted branches.
|
||||
git fetch -q origin "$SRC_SHA" 2>/dev/null \
|
||||
|| git fetch -q origin "refs/pull/$PR_NUMBER/head" \
|
||||
|| { echo "::error::cannot fetch head sha $SHORT"; exit 1; }
|
||||
[ "$(git rev-parse -q --verify FETCH_HEAD)" = "$SRC_SHA" ] \
|
||||
|| { echo "::error::fetched object does not match the API head sha $SHORT"; exit 1; }
|
||||
# Range = the PR's OWN commits: reachable from its head but absent
|
||||
# from CURRENT master — synced-master content can never leak in.
|
||||
MB="$(git merge-base origin/master "$SRC_SHA" || true)"
|
||||
[ -n "$MB" ] || { echo "::error::no common ancestor between master and $SHORT — refusing to guess a range"; exit 1; }
|
||||
SHAS="$(git rev-list --reverse --no-merges "$MB..$SRC_SHA")"
|
||||
TOTAL=0; for s in $SHAS; do TOTAL=$((TOTAL+1)); done
|
||||
if [ "$TOTAL" -eq 0 ] && [ "$(jq -r '.merged' "$RUNNER_TEMP/pr.json")" = "true" ]; then
|
||||
# A real merge-commit merge puts the head ON master, so the own-range
|
||||
# above is empty — yet the fix IS on master and label-after-merge must
|
||||
# still carry it: fall back to the merge shape itself (the pre-lane
|
||||
# bot's proven range; housekeeping merges excluded by --no-merges).
|
||||
MC="$(jq -r '.merge_commit_sha // empty' "$RUNNER_TEMP/pr.json")"
|
||||
if [ -n "$MC" ] && git rev-parse -q --verify "${MC}^2" >/dev/null 2>&1; then
|
||||
SHAS="$(git rev-list --reverse --no-merges "${MC}^1..${MC}^2")"
|
||||
TOTAL=0; for s in $SHAS; do TOTAL=$((TOTAL+1)); done
|
||||
echo "head already on master (merge-commit merge) — picking its ${TOTAL} commit(s) via ${MC:0:8}^1..^2"
|
||||
fi
|
||||
fi
|
||||
CONFLICTS=""
|
||||
CONFLICT_SHAS=""
|
||||
i=0
|
||||
for sha in $SHAS; do
|
||||
i=$((i+1))
|
||||
sub="$(git log -1 --format=%s "$sha")"
|
||||
if ! err="$(git cherry-pick -x "$sha" 2>&1)"; then
|
||||
git cherry-pick --abort
|
||||
SHORT_C="$(git rev-parse --short "$sha")"
|
||||
CONFLICTS="$CONFLICTS $SHORT_C (${i}/${TOTAL}) ${sub}"
|
||||
CONFLICT_SHAS="$CONFLICT_SHAS $SHORT_C"
|
||||
echo "::warning::conflict picking ${sha:0:8} ($sub) — recorded, continuing with the rest"
|
||||
fi
|
||||
done
|
||||
{
|
||||
echo "total=$TOTAL"
|
||||
printf 'conflicts:%s\n' "${CONFLICTS:-none}"
|
||||
printf 'conflictshas:%s\n' "${CONFLICT_SHAS# }"
|
||||
printf 'shas:%s\n' "$(printf '%s ' "$SHAS" | sed 's/ $//')"
|
||||
} > "$RUNNER_TEMP/pick.txt"
|
||||
cat "$RUNNER_TEMP/pick.txt"
|
||||
APPLIED="$(git log "origin/$LANE..HEAD" --format=%H | wc -l)"
|
||||
echo "applied=$APPLIED" >> "$RUNNER_TEMP/pick.txt"
|
||||
if [ "$TOTAL" -eq 0 ] || [ "$APPLIED" -eq 0 ]; then
|
||||
if [ "$TOTAL" -eq 0 ]; then MSG="no own commits beyond current master"; else MSG="every pick conflicted — nothing clean to push yet"; fi
|
||||
{
|
||||
echo "(ai: zai/glm-5.3) **backport carry**: $MSG."
|
||||
if [ -n "$(printf '%s' "${CONFLICTS:-}" )" ]; then
|
||||
echo
|
||||
echo "Conflicting picks (resolve manually on a fresh branch off \`$LANE\`):"
|
||||
echo '```bash'
|
||||
echo "git checkout -b <fix-branch> origin/$LANE"
|
||||
printf '%s\n' ${CONFLICT_SHAS# } | while read -r c; do
|
||||
[ -z "$c" ] && continue
|
||||
echo "git cherry-pick -x $c # resolve the <<<<<<< markers, then continue"
|
||||
done
|
||||
echo "git push origin HEAD:<fix-branch> # open a PR against $LANE, label it backport-carry"
|
||||
echo '```'
|
||||
fi
|
||||
} | gh api repos/"$GITHUB_REPOSITORY"/issues/"$PR_NUMBER"/comments -F body=@-
|
||||
exit 0
|
||||
fi
|
||||
git checkout -q -B "$CARRY"
|
||||
git push -q -f origin "HEAD:$CARRY" || { echo "::error::pushing $CARRY failed"; exit 1; }
|
||||
echo "carried $APPLIED/$TOTAL picks to origin/$CARRY"
|
||||
|
||||
- name: Open / refresh the carry PR
|
||||
id: carrypush
|
||||
if: steps.gate.outputs.gated == 'true'
|
||||
run: |
|
||||
set -uo pipefail
|
||||
LANE="${{ steps.lane.outputs.name }}"
|
||||
CARRY="backport/carry-$PR_NUMBER"
|
||||
if ! git rev-parse -q --verify "refs/remotes/origin/$CARRY" >/dev/null; then
|
||||
git fetch -q origin "+refs/heads/$CARRY:refs/remotes/origin/$CARRY" || true
|
||||
fi
|
||||
if ! git rev-parse -q --verify "refs/remotes/origin/$CARRY" >/dev/null; then
|
||||
echo "::notice::pick step produced nothing to open (receipt already posted) — skipping"
|
||||
exit 0
|
||||
fi
|
||||
TOTAL="$(sed -n 's/^total=//p' "$RUNNER_TEMP/pick.txt")"
|
||||
CONFLICT_LINE="$(sed -n 's/^conflicts://p' "$RUNNER_TEMP/pick.txt")"
|
||||
CONFLICT_SHAS="$(sed -n 's/^conflictshas://p' "$RUNNER_TEMP/pick.txt")"
|
||||
APPLIED="$(sed -n 's/^applied=//p' "$RUNNER_TEMP/pick.txt")"
|
||||
ORIGIN_URL="https://github.com/$GITHUB_REPOSITORY/pull/$PR_NUMBER"
|
||||
ORIG_TITLE="$(jq -r '.title' "$RUNNER_TEMP/pr.json")"
|
||||
BODY="$( {
|
||||
echo "(ai: zai/glm-5.3) Auto-created **carry PR** for source [$ORIGIN_URL]($ORIGIN_URL) (\`$ORIG_TITLE\`)."
|
||||
echo
|
||||
echo "- Base: \`$LANE\` — the current patch lane, cut from the latest released tag"
|
||||
if [ "$APPLIED" != "$TOTAL" ]; then
|
||||
echo "- Picks applied cleanly: **$APPLIED of $TOTAL** — ⚠️ the rest CONFLICTED (table below)"
|
||||
else
|
||||
echo "- Picks applied cleanly: **all $TOTAL** — every commit landed conflict-free"
|
||||
fi
|
||||
echo "- This PR is a COPY (\`backport-carry\`). Its fixes may land here without ever reaching master — the source PR closes independently."
|
||||
echo
|
||||
echo "Merge this PR to put the fixes on the lane. To ship them: Actions → *Release (one-click)* → tick **train**."
|
||||
} )"
|
||||
if [ "$APPLIED" != "$TOTAL" ]; then
|
||||
TBL="$( {
|
||||
echo
|
||||
echo "## ⚠️ Unresolved conflicting picks (resolve INSIDE this PR before merging)"
|
||||
echo
|
||||
echo "| commit | replay command (after pulling this branch) | subject |"
|
||||
echo "|---|---|---|"
|
||||
printf '%s\n' "$CONFLICT_SHAS" | while read -r c; do
|
||||
[ -z "$c" ] && continue
|
||||
subj="$(git log -1 --format=%s "$c" 2>/dev/null || true)"
|
||||
echo "| \`$c\` | \`git cherry-pick -x $c\` → fix the <<<<<<< markers | $subj |"
|
||||
done
|
||||
} )"
|
||||
BODY="$BODY$TBL"
|
||||
fi
|
||||
CREATED="$(gh pr create --repo "$GITHUB_REPOSITORY" --base "$LANE" --head "$CARRY" \
|
||||
--title "[backport of #$PR_NUMBER] $ORIG_TITLE" --body "$BODY" 2>&1)" || {
|
||||
# An open PR with this head already exists (source moved, rebuild path).
|
||||
EXISTING="$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$CARRY" --state open --json number,url --jq '.[0]' 2>/dev/null)"
|
||||
if [ -n "$EXISTING" ]; then
|
||||
N="$(printf '%s' "$EXISTING" | jq -r '.number')"
|
||||
gh pr edit "$N" --repo "$GITHUB_REPOSITORY" --body "$BODY" >/dev/null
|
||||
echo "refreshed existing carry PR #$N"
|
||||
else
|
||||
echo "::error::gh pr create failed and no open carry PR found:"; printf '%s\n' "$CREATED"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
CARRY_N="$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$CARRY" --state open --json number --jq '.[0].number // empty')"
|
||||
[ -n "$CARRY_N" ] || { echo "::error::no open carry PR for $CARRY"; exit 1; }
|
||||
gh pr edit "$CARRY_N" --repo "$GITHUB_REPOSITORY" --add-label backport-carry >/dev/null 2>&1 || true
|
||||
echo "carry PR #$CARRY_N ready"
|
||||
|
||||
- name: Receipt comment on the source PR
|
||||
if: steps.carrypush.outcome == 'success'
|
||||
run: |
|
||||
set -uo pipefail
|
||||
LANE="${{ steps.lane.outputs.name }}"
|
||||
CARRY="backport/carry-$PR_NUMBER"
|
||||
CARRY_N="$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$CARRY" --state open --json number --jq '.[0].number // empty')"
|
||||
[ -n "$CARRY_N" ] || exit 0
|
||||
TOTAL="$(sed -n 's/^total=//p' "$RUNNER_TEMP/pick.txt")"
|
||||
APPLIED="$(sed -n 's/^applied=//p' "$RUNNER_TEMP/pick.txt")"
|
||||
CONFLICT_TXT="none — every pick is clean"
|
||||
[ "$APPLIED" != "$TOTAL" ] && CONFLICT_TXT="⚠️ $((TOTAL - APPLIED)) of $TOTAL conflict(s) — they are listed INSIDE the carry PR; merge it only after resolving them"
|
||||
SRC_PIN="$(jq -r '.head.sha' "$RUNNER_TEMP/pr.json")"
|
||||
{
|
||||
echo "<!-- backport-carry-marker pin:$SRC_PIN carry:$CARRY_N -->"
|
||||
echo
|
||||
echo "(ai: zai/glm-5.3) ✅ **Backport carry created: [#"$CARRY_N"](https://github.com/$GITHUB_REPOSITORY/pull/$CARRY_N)**"
|
||||
echo
|
||||
echo "- Target: \`$LANE\` (current patch lane, cut from the latest released tag)"
|
||||
echo "- Pinned at source head \`${SRC_PIN:0:8}\` — relabel after further edits and the carry rebuilds"
|
||||
echo "- Conflicts: $CONFLICT_TXT"
|
||||
echo
|
||||
echo "Merging the carry PR puts the fixes on the lane. To ship: Actions → *Release (one-click)* → tick **train**. The source PR stays independent — the lane does not need it merged."
|
||||
} | gh api repos/"$GITHUB_REPOSITORY"/issues/"$PR_NUMBER"/comments -F body=@-
|
||||
|
||||
- name: Dispatch CI on the carry ref
|
||||
if: steps.carrypush.outcome == 'success'
|
||||
continue-on-error: true
|
||||
run: |
|
||||
# GITHUB_TOKEN pushes generate no push event (#772): fire the core
|
||||
# matrix on the carry head explicitly so its checks exist before a
|
||||
# human merges.
|
||||
gh workflow run ci.yml --repo "$GITHUB_REPOSITORY" --ref "backport/carry-$PR_NUMBER" \
|
||||
&& echo "dispatched ci.yml on backport/carry-$PR_NUMBER" \
|
||||
|| echo "::warning::CI dispatch failed (the next synchronize will re-trigger CI anyway)"
|
||||
@@ -0,0 +1,42 @@
|
||||
# Blog pipeline — one bilingual GitHub Discussion per blog post (owner decision 2026-11-01).
|
||||
# Fires when the blog surface changes on master; the script no-ops by itself both
|
||||
# when there is nothing to do and on its own manifest write-back pushes (commit
|
||||
# prefix guard — see scripts/blog-discussions.mjs). No third-party host involved:
|
||||
# api.github.com only, so it works from every network the repo itself works from.
|
||||
name: blog-discussions
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
paths:
|
||||
- "website/blog/posts/**"
|
||||
- "website/articles.json"
|
||||
|
||||
permissions:
|
||||
contents: write # write-back commit recording thread numbers in articles.json
|
||||
discussions: write # creating the threads themselves
|
||||
pull-requests: write # opening the single write-back PR for the human merge step
|
||||
|
||||
concurrency:
|
||||
group: blog-discussions
|
||||
cancel-in-progress: false # cancelling between "thread created" and "number recorded" would orphan a thread
|
||||
|
||||
jobs:
|
||||
sync-discussions:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
ref: ${{ github.ref_name }}
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
|
||||
- name: Create missing discussion threads and record their numbers
|
||||
env:
|
||||
GITHUB_REPOSITORY: ${{ github.repository }}
|
||||
GITHUB_REF_NAME: ${{ github.ref_name }}
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
GITHUB_EVENT_PATH: ${{ github.event_path }}
|
||||
run: node scripts/blog-discussions.mjs
|
||||
@@ -21,6 +21,7 @@ permissions:
|
||||
jobs:
|
||||
gate-plugins:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
name: CI Run Janitor
|
||||
|
||||
# 2026-10-30 incident: 29 queued/in-progress runs starved for 8 hours behind
|
||||
# zombies — runs from deleted branches, stale schedule runs, and hung
|
||||
# in-progress jobs. Nothing ever reaped them, so every live check (including
|
||||
# PR required checks) sat behind the pile. This lane sweeps hourly and cancels:
|
||||
# - queued runs older than QUEUE_MAX (default 120 min) — a queued GitHub
|
||||
# hosted job starts within seconds of capacity; 2h queued means the run
|
||||
# is starved, not slow
|
||||
# - in_progress runs older than PROGRESS_MAX (default 240 min) — the slowest
|
||||
# legit lane (windows test shard) measured ~21 min; 4h running is a hang
|
||||
# - any queued/in_progress pull_request run whose head branch no longer
|
||||
# exists (deleted-branch zombies), regardless of age
|
||||
# - BACKLOG BREAKER (2026-10-31 incident): when the queue itself is
|
||||
# overloaded (more than starvedQueueLimit runs queued), EVERY queued run
|
||||
# older than starvedQueuedMaxMinutes (default 60) is cancelled — the 2026-10-31
|
||||
# post-mortem showed queue DEPTH is what stalls dispatch for the whole repo
|
||||
# (236 queued runs sat at ~0 in_progress until the backlog was drained
|
||||
# manually); draining early beats waiting out a multi-hour snowball.
|
||||
# master's own runs (push or schedule) are NEVER cancelled — since #5426 dropped
|
||||
# the push arm, the :03/:33 schedule runs are master's standing verification
|
||||
# (master-build/release stay push-triggered); a starving one is reported as a
|
||||
# workflow warning instead of being reaped.
|
||||
|
||||
on:
|
||||
schedule:
|
||||
# hourly at :57 — just ahead of the :03/:33 CI crons so a sweep clears
|
||||
# the queue before the next scheduled burst lands
|
||||
- cron: '57 * * * *'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
queuedMaxMinutes:
|
||||
description: "Cancel queued runs older than this many minutes"
|
||||
default: "120"
|
||||
required: false
|
||||
progressMaxMinutes:
|
||||
description: "Cancel in_progress runs older than this many minutes"
|
||||
default: "240"
|
||||
required: false
|
||||
dryRun:
|
||||
description: "Log what would be cancelled without cancelling"
|
||||
type: boolean
|
||||
default: false
|
||||
starvedQueueLimit:
|
||||
description: "Starvation alert when more than this many runs sit queued at once (healthy-day ceiling is a low double digit)"
|
||||
default: "30"
|
||||
required: false
|
||||
starvedQueuedMaxMinutes:
|
||||
description: "BACKLOG BREAKER: while the queue is overloaded (> starvedQueueLimit), also cancel queued runs older than this many minutes (0 disables)"
|
||||
default: "60"
|
||||
required: false
|
||||
|
||||
permissions:
|
||||
actions: write
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: ci-run-janitor
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
sweep:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- name: Cancel starved CI runs
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
REPO: ${{ github.repository }}
|
||||
SELF_ID: ${{ github.run_id }}
|
||||
QUEUE_MAX: ${{ inputs.queuedMaxMinutes || '120' }}
|
||||
PROGRESS_MAX: ${{ inputs.progressMaxMinutes || '240' }}
|
||||
DRY_RUN: ${{ inputs.dryRun && '1' || '' }}
|
||||
STARVED_QUEUE: ${{ inputs.starvedQueueLimit || '30' }}
|
||||
STARVED_QUEUE_MAX: ${{ inputs.starvedQueuedMaxMinutes || '60' }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
now=$(date +%s)
|
||||
cancelled=0
|
||||
warned=0
|
||||
|
||||
collect() {
|
||||
gh api --paginate --jq '.workflow_runs[] | [.id, .status, .created_at, .event, (.head_branch // "")] | @tsv' \
|
||||
"repos/$REPO/actions/runs?status=$1&per_page=100"
|
||||
}
|
||||
{ collect queued; collect in_progress; } | sort -u > /tmp/janitor-runs.tsv
|
||||
|
||||
# Runner-starvation circuit breaker (2026-10-31 incident): this sweep
|
||||
# reaps zombies but CANNOT create capacity. When the queue balloons far
|
||||
# past healthy-day depth, the problem is GitHub's hosted allocation
|
||||
# throttling itself, not individual hangs — the 2026-10-31 runs waited
|
||||
# up to ~3.5 h queued before their 2-8 min jobs ever started, and this
|
||||
# very lane's ticks sat in that same queue (self-starvation). Surface it
|
||||
# loudly so a human can intervene (check Actions billing/runner capacity,
|
||||
# manually prune redundant runs: `gh run list --jq ...` + `gh run cancel`)
|
||||
# instead of watching every required check stall silently for hours.
|
||||
queued_count=$(awk -F'\t' '$2 == "queued"' /tmp/janitor-runs.tsv | wc -l)
|
||||
inprogress_count=$(awk -F'\t' '$2 == "in_progress"' /tmp/janitor-runs.tsv | wc -l)
|
||||
starve_mode=0
|
||||
if [ "$queued_count" -gt "$STARVED_QUEUE" ]; then
|
||||
starve_mode=1
|
||||
by_event=$(awk -F'\t' '$2 == "queued" { c[$4]++ } END { for (e in c) printf "%s=%d ", e, c[e] }' /tmp/janitor-runs.tsv)
|
||||
oldest_queued=$(awk -F'\t' '$2 == "queued" { print $3 " run="$1 }' /tmp/janitor-runs.tsv | sort | head -1 || true)
|
||||
starve_note=$([ "$STARVED_QUEUE_MAX" -gt 0 ] && printf 'queued runs older than %sm are cancelled below to break the snowball' "$STARVED_QUEUE_MAX" || printf 'breaker disabled (starvedQueuedMaxMinutes=0), no auto-cancel in this sweep')
|
||||
echo "::warning::RUNNER STARVATION: ${queued_count} runs queued at once (healthy ceiling ${STARVED_QUEUE}; in_progress=${inprogress_count}) [${by_event}] oldest='${oldest_queued:-n/a}' — 2026-10-31 incident class: backlog DEPTH itself stalls dispatch for this repo; ${starve_note}."
|
||||
else
|
||||
echo "queue depth ok (queued=${queued_count} in_progress=${inprogress_count} ceiling=${STARVED_QUEUE})"
|
||||
fi
|
||||
# BUGFIX 2026-10-31: the original release of this lane forgot the input
|
||||
# redirection here — `while read` on stdin never iterates inside an
|
||||
# Actions job, so EVERY rule below (zombie reap, age limits, master
|
||||
# warnings) was dead code from day one (2026-10-30). Feed the collected
|
||||
# list explicitly.
|
||||
while IFS=$'\t' read -r id status created event branch; do
|
||||
if [ "$id" = "$SELF_ID" ]; then continue; fi
|
||||
age_min=$(( (now - $(date -d "$created" +%s)) / 60 ))
|
||||
|
||||
if [ "$branch" = "master" ] && { [ "$event" = "push" ] || [ "$event" = "schedule" ]; }; then
|
||||
echo "::warning::master $event run $id ($status, ${age_min}m old) is starved — not cancelling (master's standing verification)"
|
||||
warned=$((warned + 1))
|
||||
continue
|
||||
fi
|
||||
|
||||
reason=""
|
||||
if [ "$event" = "pull_request" ] && [ -n "$branch" ]; then
|
||||
if ! gh api "repos/$REPO/branches/$branch" >/dev/null 2>&1; then
|
||||
reason="head branch '$branch' deleted"
|
||||
fi
|
||||
fi
|
||||
if [ -z "$reason" ] && [ "$status" = "queued" ] && [ "$starve_mode" = "1" ] && [ "$STARVED_QUEUE_MAX" -gt 0 ]; then
|
||||
# Backlog breaker: under overload the usual QUEUE_MAX patience
|
||||
# makes the snowball bigger — drain the old waiting room early.
|
||||
if [ "$age_min" -ge "$STARVED_QUEUE_MAX" ]; then
|
||||
reason="queued ${age_min}m >= ${STARVED_QUEUE_MAX}m while queue overloaded (${queued_count} > ${STARVED_QUEUE})"
|
||||
fi
|
||||
fi
|
||||
if [ -z "$reason" ]; then
|
||||
limit=$([ "$status" = "queued" ] && echo "$QUEUE_MAX" || echo "$PROGRESS_MAX")
|
||||
if [ "$age_min" -ge "$limit" ]; then
|
||||
reason="$status ${age_min}m >= ${limit}m"
|
||||
fi
|
||||
fi
|
||||
if [ -z "$reason" ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
echo "cancel run $id ($event, branch '$branch'): $reason"
|
||||
if [ -n "$DRY_RUN" ]; then
|
||||
continue
|
||||
fi
|
||||
if ! gh api -X POST "repos/$REPO/actions/runs/$id/cancel" >/dev/null 2>&1; then
|
||||
echo "::warning::cancel of $id failed (run may have just transitioned)"
|
||||
fi
|
||||
cancelled=$((cancelled + 1))
|
||||
done < /tmp/janitor-runs.tsv
|
||||
echo "janitor sweep done (cancelled=$cancelled master_warned=$warned starve_mode=$starve_mode dry_run=${DRY_RUN:-no})"
|
||||
@@ -36,11 +36,22 @@ on:
|
||||
- cron: '16/30 * * * *'
|
||||
# three-layer CI: 30-min smart cron — gate skips when master HEAD is unchanged since the last green scheduled run
|
||||
workflow_dispatch:
|
||||
|
||||
# 2026-10-31 queue-starvation incident: same house pattern as ci-e2e (#3331/#3772)
|
||||
# — one run per ref, superseded PR runs cancelled within their group, scheduled
|
||||
# runs queue behind each other and are NEVER cancelled (the smart gate needs an
|
||||
# un-cancelled green scheduled head to skip), non-ci:full label events sit in
|
||||
# their own '-skip' group so they can never kill an in-flight real run.
|
||||
concurrency:
|
||||
group: theorem-${{ github.event_name == 'schedule' && 'nightly' || github.ref }}${{ (github.event_name == 'pull_request' && github.event.action == 'labeled' && github.event.label.name != 'ci:full') && '-skip' || '' }}
|
||||
cancel-in-progress: ${{ github.event_name != 'schedule' }}
|
||||
|
||||
jobs:
|
||||
# three-layer CI: this lane only runs on demand (ci:full label / dispatch)
|
||||
# or on the 30-min cron when master moved since the last green scheduled run.
|
||||
gate:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
contents: read
|
||||
actions: read
|
||||
@@ -71,6 +82,7 @@ jobs:
|
||||
needs: [gate]
|
||||
if: needs.gate.outputs.run == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 45
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
|
||||
@@ -13,7 +13,16 @@ on:
|
||||
# lane or a bugfix-release/** carve-out get the CORE matrix directly;
|
||||
# backport.yml's token pushes compensate by dispatching this workflow
|
||||
# on the carry/lane ref.
|
||||
branches: [master, "*_release-v*", "bugfix-release/**", "bugfix-v*"]
|
||||
# 2026-11-01 owner decision: drop `master` here. Post-merge re-runs had
|
||||
# zero consumers (nothing blocks on them or reads their red; artifacts
|
||||
# and release lanes fire on their own master-push triggers), so every
|
||||
# merge paid full-shard minutes for a signal nobody saw. Master coverage
|
||||
# does not lapse: the :03/:33 schedule cron below re-runs the FULL
|
||||
# matrix whenever master moved since the last green scheduled run
|
||||
# (bounded ~30 min window), and PR-side blocking still gates everything
|
||||
# pre-merge. Release/bugfix push arms stay — they exist because
|
||||
# bot-authored PR checks sit in action_required (#772).
|
||||
branches: ["*_release-v*", "bugfix-release/**", "bugfix-v*", bugfix]
|
||||
pull_request:
|
||||
# agent-relay: #3468 agent PRs target the relay branch.
|
||||
# bugfix-v*: carry PRs INTO the current patch lane (backport/carry-N)
|
||||
@@ -21,13 +30,18 @@ on:
|
||||
# release-bugfix.yml's dispatch, not this trigger.
|
||||
# bugfix-release/**: legacy one-off carve-out branches keep their old
|
||||
# behaviour.
|
||||
branches: [master, agent-relay, "bugfix-v*", "bugfix-release/**"]
|
||||
# bugfix: THE GATE branch (v3 release model). Ship PRs (tag lane ->
|
||||
# bugfix) must run the FULL matrix BEFORE the merge can happen — the
|
||||
# scope step below forces full for base=bugfix regardless of labels.
|
||||
branches: [master, agent-relay, "bugfix-v*", "bugfix-release/**", bugfix]
|
||||
# three-layer CI (#3295): synchronize keeps the CORE matrix blocking on
|
||||
# every push; `labeled` lets the `ci:full` label widen a PR to the FULL
|
||||
# matrix without a re-push (other labels no-op in the plan job).
|
||||
types: [opened, synchronize, reopened, labeled]
|
||||
# Three-layer CI (#3295): PRs and master pushes pay for the CORE matrix
|
||||
# only. Every 30 minutes this cron asks the plan job whether master moved
|
||||
# Three-layer CI (#3295): PRs pay for the CORE matrix only (master pushes
|
||||
# stopped paying in 2026-11-01 — see the push arm above;
|
||||
# this cron is now master's standing verifier).
|
||||
# Every 30 minutes this cron asks the plan job whether master moved
|
||||
# since the last green scheduled run; only then does the FULL matrix run.
|
||||
# Lane workflows (e2e/registry/image/theorem/zcode) follow the same gated
|
||||
# cron pattern on their own offsets.
|
||||
@@ -95,6 +109,7 @@ jobs:
|
||||
# names (branch protection keys off `test (os, node, shard)`).
|
||||
plan:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
permissions:
|
||||
contents: read
|
||||
actions: read
|
||||
@@ -119,6 +134,7 @@ jobs:
|
||||
# pull_request case below.
|
||||
PR_AUTHOR: ${{ github.event.pull_request.user.login }}
|
||||
PR_HEAD_REF: ${{ github.event.pull_request.head.ref }}
|
||||
PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
|
||||
PR_TITLE: ${{ github.event.pull_request.title }}
|
||||
HEAD_SHA: ${{ github.sha }}
|
||||
FULL_INPUT: ${{ inputs.full }}
|
||||
@@ -192,8 +208,14 @@ jobs:
|
||||
# lane ship PRs are deliberately NOT glob-matched: their own
|
||||
# workflow gates the full suite at the PR head tree already
|
||||
# (lane ship PRs ride the bot-author rule above).
|
||||
# v3 gate-branch model: a ship PR INTO `bugfix` is born
|
||||
# full-scope — that merge IS the publish decision, so the FULL
|
||||
# matrix must exist at the PR head before the human merges
|
||||
# (same label/merge race lesson as #3688); no ci:full label
|
||||
# needed on the ship PR itself.
|
||||
[ "${PR_AUTHOR:-}" = "github-actions" ] \
|
||||
|| [ "${PR_AUTHOR:-}" = "app/github-actions" ] \
|
||||
|| [ "${PR_BASE_REF:-}" = "bugfix" ] \
|
||||
|| case "${PR_HEAD_REF:-}" in *_release-v*) true ;; *) false ;; esac \
|
||||
|| case "${PR_TITLE:-}" in "[PR] release"*|"release v"[0-9]*) true ;; *) false ;; esac
|
||||
then
|
||||
@@ -228,14 +250,14 @@ jobs:
|
||||
# #2637 plan #8 (owner-approved): fail-fast tiering — the ~0-1m guards gate
|
||||
# the four platform legs so a broken commit stops in tier 1 instead of
|
||||
# paying 4x(install+typecheck+suites+build). Guards with `if: pull_request`
|
||||
# skip on push/dispatch — and a SKIPPED need cascades the skip to dependents
|
||||
# skip on push — and a SKIPPED need cascades the skip to dependents
|
||||
# (the GitHub-documented behavior; the old comment here wrongly assumed
|
||||
# "skipped needs count as satisfied" — the master-push run evidence
|
||||
# (#3145/#3035/#3027 all slipped red to master with `test: skipped`)
|
||||
# disproved it). The explicit `if` below tolerates skipped guards so:
|
||||
# - pull_request: guards run; guard failure -> failure() -> legs skip
|
||||
# (required checks show pending, merge blocked — #2637 semantics intact)
|
||||
# - push/dispatch: PR-only guards skip harmlessly, legs RUN — master gets
|
||||
# - push: PR-only guards skip harmlessly, legs RUN — master gets
|
||||
# a real post-merge test signal (the missing master-push hole, #3197 era)
|
||||
test:
|
||||
needs: [plan, version-guard, kernel-guard, pi-subagents-guard, lane-guard, docs-sync, docs-coverage, unused-exports, lock-sync, test-import-graph]
|
||||
@@ -255,6 +277,7 @@ jobs:
|
||||
fail-fast: false
|
||||
matrix: ${{ fromJSON(needs.plan.outputs.testMatrix) }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 90
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -311,6 +334,7 @@ jobs:
|
||||
needs: [plan]
|
||||
if: ${{ !failure() && !cancelled() && needs.plan.outputs.scope != 'skip' }}
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
services:
|
||||
mysql:
|
||||
image: mysql:8.0
|
||||
@@ -336,7 +360,13 @@ jobs:
|
||||
# resolves it to the built dist. Same prerequisite as the main test
|
||||
# matrix (run-ci-tests pretest parity) and ci-e2e-dsh.yml.
|
||||
- run: npm --prefix kernel run build
|
||||
- run: node --import tsx --test tests/storage-backend-contract.test.ts tests/storage-backend-knob.test.ts
|
||||
# --test-concurrency=1: every mysql lane in these files shares ONE DSN
|
||||
# and database; node's default file parallelism (cores-1) would let two
|
||||
# suites race on the same tables once runners grow past 2 vCPUs.
|
||||
# storage-backend-mysql-e2e.test.ts is deliberately NOT listed: its hot-
|
||||
# path test fails deterministically on real MySQL (pre-existing defect,
|
||||
# not caused by any PR in flight) — tracked in #4926; re-add it there.
|
||||
- run: node --import tsx --test --test-concurrency=1 tests/storage-backend-contract.test.ts tests/storage-backend-knob.test.ts tests/issue4666-migration-dedup.test.ts
|
||||
env:
|
||||
BILI_MYSQL_TEST_DSN: mysql://root:bili-test-root@127.0.0.1:3306/bili
|
||||
|
||||
@@ -352,6 +382,7 @@ jobs:
|
||||
fail-fast: false
|
||||
matrix: ${{ fromJSON(needs.plan.outputs.staticMatrix) }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -375,7 +406,8 @@ jobs:
|
||||
|
||||
version-guard:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'pull_request'
|
||||
timeout-minutes: 20
|
||||
if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
@@ -383,9 +415,16 @@ jobs:
|
||||
- name: Verify version field only changes on release branches
|
||||
run: |
|
||||
set -euo pipefail
|
||||
BRANCH="${GITHUB_HEAD_REF}"
|
||||
# GITHUB_HEAD_REF is PR-only; on workflow_dispatch (release-ci-gate
|
||||
# dispatches this workflow at release/bugfix branch refs) fall back to
|
||||
# GITHUB_REF_NAME so the branch-pattern exemptions below keep matching.
|
||||
BRANCH="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
|
||||
# Release + bugfix carve-out branches (#2851/#2853) may bump version — one isolated 'release v{VERSION}' commit each.
|
||||
if [[ "$BRANCH" == *_release-v* || "$BRANCH" == bugfix-release/* || "$BRANCH" == bugfix-v* ]]; then
|
||||
# v3 gate-branch model (#4660): tag lanes keep their ONE legal pre-bump commit (made at cut time); the
|
||||
# auto-opened alignment PR (head=bugfix) carries that bump into master, and backport carry branches
|
||||
# (backport/carry-N) inherit it from their lane base — all three head shapes must pass this guard or the
|
||||
# cycle deadlocks at P3 (alignment never merges → next lane never auto-cuts).
|
||||
if [[ "$BRANCH" == *_release-v* || "$BRANCH" == bugfix-release/* || "$BRANCH" == bugfix-v* || "$BRANCH" == bugfix || "$BRANCH" == backport/carry-* ]]; then
|
||||
echo "✓ release branch ($BRANCH) — version changes allowed"
|
||||
exit 0
|
||||
fi
|
||||
@@ -399,7 +438,8 @@ jobs:
|
||||
|
||||
kernel-guard:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'pull_request'
|
||||
timeout-minutes: 20
|
||||
if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
@@ -407,18 +447,34 @@ jobs:
|
||||
- name: Verify kernel boundary rules (#2092)
|
||||
env:
|
||||
PR_BODY: ${{ github.event.pull_request.body }}
|
||||
EVENT_NAME: ${{ github.event_name }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
BRANCH="${GITHUB_HEAD_REF}"
|
||||
# GITHUB_HEAD_REF is PR-only; on workflow_dispatch fall back to
|
||||
# GITHUB_REF_NAME (same rationale as version-guard above).
|
||||
BRANCH="${GITHUB_HEAD_REF:-${GITHUB_REF_NAME}}"
|
||||
# Kernel release branches bump kernel/package.json alone by design.
|
||||
if [[ "$BRANCH" == *_release-kernel-v* ]]; then
|
||||
echo "✓ kernel release branch ($BRANCH) — kernel version changes allowed"
|
||||
exit 0
|
||||
fi
|
||||
# Rule 1: any PR touching kernel/** must declare 'kernel-change:' in its body.
|
||||
if git diff --name-only origin/master...HEAD -- kernel/ | grep -q .; then
|
||||
if ! printf '%s' "$PR_BODY" | grep -q 'kernel-change:'; then
|
||||
echo "::error::This PR modifies kernel/ but does not declare 'kernel-change: <reason>' in its body."
|
||||
# #4828: kernel/package-lock.json is GENERATED state, not kernel source —
|
||||
# agents' test-prep installs churn it without any intent to change the
|
||||
# kernel (8 PRs tripped this gate on lockfile-only diffs). The human gate
|
||||
# protects kernel SOURCE; lockfile consistency is already enforced by the
|
||||
# separate lock-sync job (which FAILS on real drift). Exempt the lockfile
|
||||
# here so pure churn passes without an owner round-trip.
|
||||
KERNEL_TOUCHED="$(git diff --name-only origin/master...HEAD -- kernel/ | grep -v '^kernel/package-lock\.json$' || true)"
|
||||
if [[ -n "$KERNEL_TOUCHED" ]]; then
|
||||
# Rule 1 enforcement is PR-shaped: the declaration lives in a PR
|
||||
# body. A workflow_dispatch has no PR body — dispatch is
|
||||
# owner-fired (release fallback / bugfix carve-out lanes), so the
|
||||
# human gate has already happened out-of-band; skip only the
|
||||
# body check there. Version-discipline rules below still run.
|
||||
if [[ "${EVENT_NAME:-pull_request}" != "workflow_dispatch" ]] \
|
||||
&& ! printf '%s' "$PR_BODY" | grep -q 'kernel-change:'; then
|
||||
echo "::error::This PR modifies kernel/ ($KERNEL_TOUCHED) but does not declare 'kernel-change: <reason>' in its body."
|
||||
echo "Kernel changes are human-gated: owner approval plus explicit declaration required. See AGENTS.md 'Kernel Boundary'."
|
||||
exit 1
|
||||
fi
|
||||
@@ -452,7 +508,8 @@ jobs:
|
||||
# load-bearing core compression).
|
||||
pi-subagents-guard:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'pull_request'
|
||||
timeout-minutes: 20
|
||||
if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
@@ -485,6 +542,7 @@ jobs:
|
||||
# generator goes red here. Zero-dep script: no npm install needed.
|
||||
docs-sync:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -492,13 +550,14 @@ jobs:
|
||||
node-version: 22
|
||||
- run: node tools/gen-config-docs.mjs generate
|
||||
- name: Fail on artifact drift
|
||||
run: git diff --exit-code -- CONFIGURATION.md CONFIGURATION.zh-CN.md website/main.js website/docs/index.html
|
||||
run: git diff --exit-code -- docs/configuration.md docs/configuration.zh-CN.md website/main.js website/docs/index.html
|
||||
|
||||
# #2107 drift guard B: every BILI_*/ACP_* env var read in src/ and every
|
||||
# FileConfig top-level key must have a seed entry — an undocumented param
|
||||
# added to src goes red here with the missing names listed.
|
||||
docs-coverage:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -506,6 +565,24 @@ jobs:
|
||||
node-version: 22
|
||||
- run: node tools/gen-config-docs.mjs check-coverage
|
||||
|
||||
# #5930 architecture-docs guard (owner ruling 2026-11-08): the docs/architecture
|
||||
# hub is LIVE — mechanical half of the same-PR doc rule. Checks: the
|
||||
# reference/architecture.md file map covers every tracked src/ file (no missing,
|
||||
# no ghosts); the hub module ledger rows match the page pairs (en + .zh-CN);
|
||||
# every active module page links its svg-first diagram + png fallback (all
|
||||
# present); every SVG is basic-well-formed (the en diagram once shipped broken
|
||||
# by an unescaped '&'). Visual freshness is enforced by the same-PR rule in
|
||||
# AGENTS.md + review, not here. Zero-dep: plain node, no install step.
|
||||
architecture-docs:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
- run: node tools/check-architecture-docs.mjs
|
||||
|
||||
# #2643 config-surface guard: closes the two surfaces check-coverage above
|
||||
# does not reach — nested config-file leaf fields (only top-level keys were
|
||||
# enforced) and CLI --flags (never checked). An undocumented addition goes red
|
||||
@@ -513,6 +590,7 @@ jobs:
|
||||
# Not gated to pull_request so master pushes are held to the same surface.
|
||||
config-surface-guard:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -521,12 +599,13 @@ jobs:
|
||||
- run: node scripts/config-surface-guard.mjs
|
||||
|
||||
# #3249 lifecycle ledger guard: every BILI_* env var read in src/ must be
|
||||
# registered in LIFECYCLE.md (§1 transition ledger with release condition, or
|
||||
# registered in docs/lifecycle.md (§1 transition ledger with release condition, or
|
||||
# §2 permanent registry) — a new switch without a lifecycle entry goes red here.
|
||||
# Stale entries (dynamic/unmerged/retired names) notice only. Zero-dep: plain
|
||||
# node, no install step. Not gated to pull_request, same as the guards above.
|
||||
lifecycle-ledger-guard:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -542,7 +621,8 @@ jobs:
|
||||
# mechanical: lane logic moves ⇔ a side-lane suite moves with it.
|
||||
lane-guard:
|
||||
runs-on: ubuntu-latest
|
||||
if: github.event_name == 'pull_request'
|
||||
timeout-minutes: 20
|
||||
if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch'
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
@@ -584,6 +664,7 @@ jobs:
|
||||
# plain node, no install step.
|
||||
unused-exports:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -600,6 +681,7 @@ jobs:
|
||||
# Zero-dep: plain node, no install step.
|
||||
test-import-graph:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -618,6 +700,7 @@ jobs:
|
||||
# AGENTS.md §4 rule 2 ("release commit changes ONLY version + lock if drifts").
|
||||
lock-sync:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
@@ -644,6 +727,7 @@ jobs:
|
||||
needs: [test, static-gates]
|
||||
if: ${{ !cancelled() && github.event_name == 'schedule' }}
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
issues: write
|
||||
contents: read
|
||||
|
||||
@@ -1,47 +0,0 @@
|
||||
name: Lane leak guard (bugfix-v* must never absorb unshipped master)
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: ["bugfix-v*"]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
leak-guard:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: No merge may bring master's unshipped work into a lane
|
||||
# A lane = a released TAG + carried fix commits ONLY. If someone ever
|
||||
# MERGES master into a lane, every feature that landed since the base
|
||||
# tag ships out through the next one-click publish — the exact leak
|
||||
# the dual-lane model exists to prevent. Carries are cherry-picks
|
||||
# (-x, different SHAs), so a clean lane contains no merge whose second
|
||||
# parent is a master ancestor. Scan window = <base tag>..HEAD: covers
|
||||
# exactly the commits the lane adds over its released base, and stays
|
||||
# silent automatically once master catches up past the ship PR.
|
||||
# (The earlier `--not --tags` baseline silently dropped these commits
|
||||
# in some git forms — verified by simulation; window scan verified
|
||||
# both directions: alarms on a master merge, passes a legit carry.)
|
||||
run: |
|
||||
set -euo pipefail
|
||||
BRANCH="${GITHUB_REF_NAME#refs/heads/}"
|
||||
git fetch -q origin master --tags
|
||||
BASE_TAG="$(git describe --match 'v[0-9]*' --tags --abbrev=0 HEAD || true)"
|
||||
[ -n "$BASE_TAG" ] || { echo "::error::cannot find the lane's base tag — refusing to skip the scan"; exit 1; }
|
||||
LEAKS="$(git log --format=%H --merges "${BASE_TAG}..HEAD" \
|
||||
| while read -r M; do
|
||||
P2="$(git rev-parse "${M}^2" 2>/dev/null || echo "")"
|
||||
[ -n "$P2" ] && git merge-base --is-ancestor "$P2" origin/master \
|
||||
&& echo "$M $(git log -1 --format=%s "$M")"
|
||||
done)"
|
||||
if [ -n "$LEAKS" ]; then
|
||||
echo "::error::lane leak detected on $BRANCH — a merge pulled master's UNRELEASED work into the patch lane:"
|
||||
printf '%s\n' "$LEAKS"
|
||||
echo "Fix: rebuild the lane from its base tag and re-apply the intended fixes as PICKS (label the source PR 'backport', or cherry-pick by hand). Never merge master into a lane."
|
||||
exit 1
|
||||
fi
|
||||
echo "no lane leaks on $BRANCH since ${BASE_TAG} (all merge commits have non-master second parents)"
|
||||
@@ -8,9 +8,19 @@ permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
|
||||
# 2026-10-31 queue-starvation incident: every master push also triggered this lane;
|
||||
# a busy day merged eight times and eight full artifact builds piled up behind the
|
||||
# pile. Only the newest master build can be valid (per-sha artifact + PR comment),
|
||||
# so cancel superseded ones like ci.yml does for push events. #3071 discipline:
|
||||
# cancel-in-progress never kills the LATEST run — the head's signal survives.
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
build-artifact:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
|
||||
@@ -1,11 +1,9 @@
|
||||
name: Deploy website to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
paths:
|
||||
- "website/**"
|
||||
- ".github/workflows/pages.yml"
|
||||
# Push trigger suspended (#4598): the repo has no GitHub Pages site, so every
|
||||
# website push red-lined the deploy job. Manual dispatch stays until the
|
||||
# publishing direction is decided.
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
@@ -23,6 +21,7 @@ jobs:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/configure-pages@v5
|
||||
|
||||
@@ -19,6 +19,7 @@ permissions:
|
||||
jobs:
|
||||
build-artifact:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
|
||||
@@ -21,8 +21,15 @@ name: Bugfix Release (carve-out)
|
||||
# deliberately does not match it, so merging the PR cannot double-publish the
|
||||
# post-merge master through the normal channel.
|
||||
#
|
||||
# Emergency fallback: manual workflow_dispatch against an explicitly chosen ref
|
||||
# (a human picks the exact ref in the Actions UI; every guard below still runs).
|
||||
# NOTE 2026-10-25: the workflow_dispatch trigger was REMOVED after a concurrent
|
||||
# agent session abused manual dispatch to publish v0.1.208 outside the intended
|
||||
# flow (see #4718); the human PR merge became the only ignition shape.
|
||||
# NOTE 2026-10-28 (owner decision; revives the 5de4103c/#3613 emergency valve
|
||||
# whose step gates this file kept all along): workflow_dispatch returns AS THE
|
||||
# EMERGENCY VALVE ONLY — and hardened against a repeat of #4718: fast mode
|
||||
# engages solely when `fast` is checked AND `confirm_fast` is typed exactly
|
||||
# "FAST PUBLISH CONFIRMED" (see FAST_ON below). Any default or programmatic
|
||||
# dispatch silently keeps the slow safe path.
|
||||
#
|
||||
# Guarded so it can never:
|
||||
# - move `latest` backwards (target must be strictly newer than npm latest);
|
||||
@@ -40,12 +47,19 @@ on:
|
||||
types: [closed]
|
||||
branches: [master]
|
||||
workflow_dispatch:
|
||||
# Emergency valve only — see the 2026-10-28 header note. Slow-safe unless
|
||||
# BOTH signals arrive together.
|
||||
inputs:
|
||||
fast:
|
||||
description: "EMERGENCY fast publish: skip the full-CI dispatch/gate and the full npm test. Keeps every version guard + npm ci + typecheck + build. Owner-owned risk (opened 2026-10-17 to unblock v0.1.199 when CI flakes stall the normal channel)."
|
||||
description: "EMERGENCY fast publish: skip the full-CI dispatch/gate and the full npm test. Keeps every version guard + npm ci + typecheck + build. Owner-owned risk."
|
||||
type: boolean
|
||||
required: false
|
||||
default: false
|
||||
|
||||
confirm_fast:
|
||||
description: "TYPE EXACTLY: FAST PUBLISH CONFIRMED — anything else (blank included) keeps the normal slow path."
|
||||
type: string
|
||||
required: false
|
||||
default: ""
|
||||
concurrency:
|
||||
group: bugfix-release
|
||||
cancel-in-progress: false
|
||||
@@ -53,11 +67,25 @@ concurrency:
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
env:
|
||||
# Fast mode = BOTH explicit signals (typed-phrase guard vs accidental/
|
||||
# automated dispatches, #4718). Non-dispatch events see FAST_ON=false.
|
||||
FAST_ON: ${{ inputs.fast == true && inputs.confirm_fast == 'FAST PUBLISH CONFIRMED' }}
|
||||
permissions:
|
||||
contents: write
|
||||
id-token: write
|
||||
actions: write
|
||||
steps:
|
||||
- name: Ensure jq (2026-10 runner images are unreliable about it — always install our own)
|
||||
run: |
|
||||
type -a jq || true
|
||||
mkdir -p "$HOME/.local/bin"
|
||||
curl -fsSL "https://github.com/jqlang/jq/releases/download/jq-1.8.1/jq-linux-amd64" -o "$HOME/.local/bin/jq"
|
||||
chmod +x "$HOME/.local/bin/jq"
|
||||
echo "$HOME/.local/bin" >> "$GITHUB_PATH"
|
||||
"$HOME/.local/bin/jq" --version
|
||||
|
||||
- name: Validate trigger + resolve the publish ref
|
||||
id: resolve
|
||||
run: |
|
||||
@@ -71,10 +99,9 @@ jobs:
|
||||
exit 0
|
||||
fi
|
||||
case "$BRANCH" in
|
||||
bugfix-v*) ;; # current patch lane (dual-lane model)
|
||||
bugfix-release/*) ;; # legacy one-off carve-out
|
||||
bugfix-release/*) ;;
|
||||
*)
|
||||
echo "::notice::head branch '$BRANCH' is not a patch lane (bugfix-v*) or a legacy bugfix-release/* carve-out — nothing to publish"
|
||||
echo "::notice::head branch '$BRANCH' is not a bugfix-release/* carve-out branch — nothing to publish"
|
||||
exit 0
|
||||
;;
|
||||
esac
|
||||
@@ -126,13 +153,23 @@ jobs:
|
||||
[ -z "$SHA" ] && SHA="$(git rev-parse HEAD)"
|
||||
echo "::notice::Publishing carve-out from '$REF' @ ${SHA:0:12} -> v$V (master NOT involved)"
|
||||
|
||||
- name: Check plugin manifest versions (#4449)
|
||||
# Same gate as release.yml: the carve-out PR head is a frozen tree
|
||||
# (last tag + fix + bump), so it must ALREADY carry the synced plugin
|
||||
# manifests — drift fails fast here instead of shipping a release whose
|
||||
# marketplace update detection never fires. See reference/release.md.
|
||||
- name: Verify plugin manifests match package.json (#4449)
|
||||
# The four plugin manifests carry their own version fields — the
|
||||
# marketplaces use them for UPDATE DETECTION, so a release whose
|
||||
# manifests disagree with package.json ships a plugin that never
|
||||
# prompts users to upgrade. Drift = red release, nothing shipped.
|
||||
# See reference/release.md.
|
||||
if: steps.resolve.outputs.proceed == 'true'
|
||||
run: node scripts/sync-codex-plugin-version.mjs --check
|
||||
# #4576 follow-up: lanes cut from a pre-#4449 tag do not carry the
|
||||
# manifest sync script at all -- fail-open with a notice there instead
|
||||
# of MODULE_NOT_FOUND (same existence-guard philosophy as release-manual's
|
||||
# lane guard).
|
||||
run: |
|
||||
if [ -f scripts/sync-codex-plugin-version.mjs ]; then
|
||||
node scripts/sync-codex-plugin-version.mjs --check
|
||||
else
|
||||
echo "::notice::this tree predates #4449 (no scripts/sync-codex-plugin-version.mjs) — manifest sync check skipped for the pre-#4449 lane"
|
||||
fi
|
||||
|
||||
- name: Publish guard (monotonic + not-already-live)
|
||||
if: steps.resolve.outputs.proceed == 'true'
|
||||
@@ -187,7 +224,7 @@ jobs:
|
||||
# human-picked ref; with fast=true the human explicitly owns skipping
|
||||
# this lane matrix — version guards and the build sanity below still
|
||||
# run.
|
||||
if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true
|
||||
if: steps.resolve.outputs.proceed == 'true' && env.FAST_ON != 'true'
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
@@ -199,7 +236,7 @@ jobs:
|
||||
|
||||
- name: Pre-flight gate (full suite)
|
||||
# keep the claude-native live e2e subtests in this pre-publish gate (#1248)
|
||||
if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true
|
||||
if: steps.resolve.outputs.proceed == 'true' && env.FAST_ON != 'true'
|
||||
env:
|
||||
ACP_TEST_CLAUDE_NATIVE: "1"
|
||||
run: |
|
||||
@@ -212,9 +249,9 @@ jobs:
|
||||
# EMERGENCY fast mode: keep the cheap sanity (install/typecheck/build)
|
||||
# so a broken tree still fails loudly, but skip the full npm test —
|
||||
# the lane matrix above was skipped by explicit human choice.
|
||||
if: steps.resolve.outputs.proceed == 'true' && inputs.fast == true
|
||||
if: steps.resolve.outputs.proceed == 'true' && env.FAST_ON == 'true'
|
||||
run: |
|
||||
echo "::warning::FAST MODE — full CI lanes and the full npm test were SKIPPED by an explicit human choice (workflow_dispatch fast=true). Publish sanity = version guards + npm ci + typecheck + build only."
|
||||
echo "::warning::FAST MODE by '${{ github.actor }}' (workflow_dispatch fast=true + typed confirmation) — full CI lanes and the full npm test SKIPPED. Publish sanity = version guards + npm ci + typecheck + build only."
|
||||
npm ci
|
||||
npm run typecheck
|
||||
npm run build
|
||||
@@ -224,7 +261,7 @@ jobs:
|
||||
# own lane runs at the head sha) ran in parallel with the pre-flight;
|
||||
# wait them out now. Any red lane or timeout ⇒ release fails, nothing
|
||||
# is published.
|
||||
if: steps.resolve.outputs.proceed == 'true' && inputs.fast != true
|
||||
if: steps.resolve.outputs.proceed == 'true' && env.FAST_ON != 'true'
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
CI_GATE_TIMEOUT_MIN: "60"
|
||||
@@ -297,13 +334,3 @@ jobs:
|
||||
-H "Content-Type: application/json" \
|
||||
"https://api.github.com/repos/${{ github.repository }}/releases" \
|
||||
-d @"$RUNNER_TEMP/release.json"
|
||||
|
||||
- name: Close the patch-lane cycle (notice — the state is derived, nothing to clear)
|
||||
# Dual-lane model: lanes are DERIVED from the latest tag — after this
|
||||
# publish creates vNEXT, the NEXT 'backport' label cuts a fresh
|
||||
# lane bugfix-vNEXT from that tag automatically. No stored pointer,
|
||||
# nothing to reset.
|
||||
if: steps.resolve.outputs.proceed == 'true'
|
||||
run: |
|
||||
BRANCH="${{ steps.resolve.outputs.branch }}"
|
||||
echo "::notice::shipped '$BRANCH' — the fresh tag closes this patch-lane cycle by derivation; the next 'backport' label cuts a fresh lane from it"
|
||||
|
||||
@@ -11,9 +11,18 @@ on:
|
||||
push:
|
||||
branches: [master]
|
||||
|
||||
# 2026-10-31 queue-starvation incident: same fix as release.yml — serialize the
|
||||
# per-merge run pile (eight stacked on a busy day) instead of letting them all
|
||||
# start concurrently once capacity returns. No cancel-in-progress: back-to-back
|
||||
# kernel releases must publish in order (#3071 discipline).
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
release-kernel:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
permissions:
|
||||
contents: write
|
||||
actions: write
|
||||
|
||||
@@ -7,8 +7,13 @@ on:
|
||||
description: "Version to publish. Blank = auto next patch over npm latest."
|
||||
required: false
|
||||
default: ""
|
||||
train:
|
||||
description: "Ship the open patch train (derived from refs): bump its branch, open its ship PR, gate CI green. You merge the PR to publish (release-bugfix publishes the PR-head tree)."
|
||||
skip_ci_gate:
|
||||
description: "EMERGENCY ONLY (owner decision 2026-11-01): tick to skip the 'Full CI green at publish sha' gate — publishes right after the local typecheck+build pre-flight. LEAVE UNTICKED for normal releases; a ticked run ships code CI did not verify at this sha and logs a loud warning."
|
||||
type: boolean
|
||||
required: false
|
||||
default: false
|
||||
raw_publish:
|
||||
description: "NUCLEAR OPTION (owner decision 2026-11-01): fetches the dependency packages once (plain lockfile download — NOT CI, runs no code), then does ONLY npm run build and npm publish immediately — no typecheck, no tests, no CI lanes, no push to master, no release PR. It publishes, pushes the git tag, creates the GitHub Release, and opens a version-sync PR so master can converge. Implies the skip_ci_gate bypass; both audit warnings are logged. Untick everything for normal releases."
|
||||
type: boolean
|
||||
required: false
|
||||
default: false
|
||||
@@ -20,6 +25,7 @@ concurrency:
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
@@ -34,35 +40,11 @@ jobs:
|
||||
node-version: 22
|
||||
registry-url: https://registry.npmjs.org
|
||||
|
||||
- name: Resolve the patch lane (train mode)
|
||||
# Dual-lane model: `train=true` ships the CURRENT patch lane instead
|
||||
# of master. The lane is DERIVED from the latest v* tag (never
|
||||
# stored): `bugfix-v<latest-tag>` — every carried fix lives there
|
||||
# until this release cuts the next tag. This release commit lands on
|
||||
# the LANE branch and publishes via the carve-out channel on ship-PR
|
||||
# merge — never via the direct master push below.
|
||||
- name: Resolve the patch lane (retired 2026-10-25 — stub kept so steps.train references stay inert)
|
||||
id: train
|
||||
if: inputs.train == true
|
||||
if: false
|
||||
run: |
|
||||
set -euo pipefail
|
||||
LAST="$(git tag --list 'v[0-9]*' --sort=-v:refname | head -1)"
|
||||
if [ -z "$LAST" ]; then echo "::error::train mode: no v* tags found"; exit 1; fi
|
||||
TRAIN="bugfix-v${LAST#v}"
|
||||
git fetch -q origin "+refs/heads/$TRAIN:refs/remotes/origin/$TRAIN" || true
|
||||
if ! git show-ref --verify --quiet "refs/remotes/origin/$TRAIN"; then
|
||||
git checkout --quiet -B train "refs/tags/$LAST"
|
||||
git push -q origin "HEAD:$TRAIN"
|
||||
echo "lane $TRAIN did not exist — cut it from tag $LAST (it will be EMPTY)"
|
||||
else
|
||||
git checkout --quiet -B train "origin/$TRAIN"
|
||||
fi
|
||||
if [ "$(git rev-parse HEAD)" = "$(git rev-parse refs/tags/$LAST^{commit})" ]; then
|
||||
echo "::error::train mode: lane $TRAIN holds no carried fixes yet (tree == tag $LAST). Un-tick the box for a normal release, or label a fix PR 'backport' first."
|
||||
exit 1
|
||||
fi
|
||||
echo "name=$TRAIN" >> "$GITHUB_OUTPUT"
|
||||
echo "train mode: shipping $TRAIN ($(git rev-list --count "$LAST..HEAD") carried fix(es) over tag $LAST)"
|
||||
|
||||
echo "train mode is retired: patch lanes publish by merging their final carry PR INTO the protected lane (release-bugfix.yml); see reference/release.md"
|
||||
- name: Resolve version
|
||||
id: version
|
||||
run: |
|
||||
@@ -85,6 +67,7 @@ jobs:
|
||||
echo "version=$V" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Drift guard
|
||||
id: driftguard
|
||||
env:
|
||||
TRAIN_NAME: ${{ steps.train.outputs.name }}
|
||||
run: |
|
||||
@@ -97,8 +80,30 @@ jobs:
|
||||
WHAT="master"
|
||||
[ -n "$TRAIN_NAME" ] && WHAT="patch train $TRAIN_NAME"
|
||||
if [ "$TREE_V" != "$NPM_V" ]; then
|
||||
echo "::error::$WHAT package.json ($TREE_V) != npm latest ($NPM_V). A release must be cut from the live release: sync the base before releasing."
|
||||
exit 1
|
||||
# Pending-bump state (#5376): an earlier one-click's fallback bump PR merged into
|
||||
# master while CI was red — master now sits EXACTLY one patch ahead of npm latest,
|
||||
# with changelog + manifests already staged there. Publishing THAT version is the
|
||||
# intended release; re-bumping would invent a phantom empty patch. Allowed only when
|
||||
# (a) tree == nextPatch(npm latest), (b) the resolved target IS the tree version, and
|
||||
# (c) that version is not already tagged anywhere upstream.
|
||||
NEXT_P="$(node -p 'const p = process.argv[1].split("-")[0].split("."); p[2] = String(Number(p[2]) + 1); p.join(".")' "$NPM_V")"
|
||||
if [ "$TREE_V" = "$NEXT_P" ] \
|
||||
&& [ "${{ steps.version.outputs.version }}" = "$TREE_V" ] \
|
||||
&& ! git ls-remote --exit-code --tags origin "v$TREE_V" >/dev/null 2>&1; then
|
||||
echo "::notice::$WHAT package.json ($TREE_V) is one patch ahead of npm latest ($NPM_V) — pending-bump state; publishing $TREE_V straight from master (no new bump commit)."
|
||||
echo "pending_bump=true" >> "$GITHUB_OUTPUT"
|
||||
elif [ "${{ inputs.raw_publish }}" = "true" ]; then
|
||||
# Emergency channel (owner decision 2026-11-01): raw_publish ships the tree
|
||||
# AS-IS and never pushes master, so a master/npm version skew must NOT block
|
||||
# a second back-to-back emergency publish (the sync PR from publish #1 is
|
||||
# still unmerged — that is the whole point of this button). Drift is logged
|
||||
# loudly; nothing gates on it. Duplicate-publish protection stays in the
|
||||
# Raw emergency publish step, which refuses an npm version that already exists.
|
||||
echo "::warning::EMERGENCY CHANNEL: $WHAT package.json ($TREE_V) != npm latest ($NPM_V) — raw_publish ships the current tree anyway and does not touch master. Drift logged, not blocking; converge master via the version-sync PR after the dust settles."
|
||||
else
|
||||
echo "::error::$WHAT package.json ($TREE_V) != npm latest ($NPM_V). A release must be cut from the live release: sync the base before releasing."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
if [ "${{ steps.version.outputs.version }}" = "$NPM_V" ]; then
|
||||
echo "::error::$NPM_V is already published; pick a newer version"
|
||||
@@ -133,6 +138,9 @@ jobs:
|
||||
" "$VER"
|
||||
|
||||
- name: Bump version
|
||||
# Skipped in pending-bump state: the tree already carries the target
|
||||
# version plus changelog/manifests (merged fallback bump commit).
|
||||
if: ${{ steps.driftguard.outputs.pending_bump != 'true' }}
|
||||
run: |
|
||||
node -e '
|
||||
const fs = require("fs");
|
||||
@@ -149,11 +157,22 @@ jobs:
|
||||
# #4449: plugin manifests (.agents/.claude-plugin/plugins/codex) carry
|
||||
# their version from package.json — sync them into the same release
|
||||
# commit or marketplace update detection sees a stale version.
|
||||
node scripts/sync-codex-plugin-version.mjs
|
||||
# Pre-b87732e2 patch lanes (cut from tags older than #4449) have no
|
||||
# manifests and no script — `git add` fatals on the absent pathspecs
|
||||
# and the script itself is MODULE_NOT_FOUND, killing train mode on
|
||||
# exactly the lanes that need it. Existence-guard both.
|
||||
if [ -f scripts/sync-codex-plugin-version.mjs ]; then
|
||||
node scripts/sync-codex-plugin-version.mjs
|
||||
else
|
||||
echo "::notice::sync-codex-plugin-version.mjs absent on this ref (pre-#4449 patch lane) — skipping manifest sync"
|
||||
fi
|
||||
|
||||
- name: Verify bump diff
|
||||
if: ${{ steps.driftguard.outputs.pending_bump != 'true' }}
|
||||
run: |
|
||||
git add package.json package-lock.json .agents .claude-plugin plugins/codex
|
||||
for P in package.json package-lock.json .agents .claude-plugin plugins/codex; do
|
||||
[ -e "$P" ] && git add "$P"
|
||||
done
|
||||
CHANGED="$(git diff --cached --name-only)"
|
||||
[ -n "$CHANGED" ] || { echo "::error::bump produced no changes"; exit 1; }
|
||||
BAD="$(printf '%s\n' "$CHANGED" | grep -vE '^(package\.json|package-lock\.json|\.agents/plugins/marketplace\.json|\.claude-plugin/marketplace\.json|\.claude-plugin/plugin\.json|plugins/codex/\.codex-plugin/plugin\.json)$' || true)"
|
||||
@@ -170,13 +189,110 @@ jobs:
|
||||
# below (policy 2026-10-10 unchanged); the Full CI gate blocks publish
|
||||
# until they are all green, so coverage is identical — only the
|
||||
# executor moved from this job to the parallel lane matrix.
|
||||
# raw_publish bypasses this whole gate: its own step below downloads the
|
||||
# dependencies (lockfile fetch, no code runs) and builds only,
|
||||
# then publishes (#5430 nuclear option).
|
||||
if: ${{ inputs.raw_publish != 'true' }}
|
||||
run: |
|
||||
npm ci
|
||||
npm run typecheck
|
||||
npm run build
|
||||
|
||||
- name: Raw emergency publish (build only — NO typecheck, NO tests, NO CI, NO master push)
|
||||
id: rawpub
|
||||
# #5430 nuclear option (owner decision 2026-11-01): before `npm publish` this
|
||||
# path does a one-time dependency download (`npm install`, straight from the
|
||||
# lockfile — it executes no project code, it is not CI) and `npm run build`,
|
||||
# and NOTHING else. master is never touched by this path;
|
||||
# it publishes, pushes the git tag, creates the GitHub Release, and opens a
|
||||
# version-sync PR so master can converge without re-running this path. Every
|
||||
# downstream step keys off steps.push.outputs.direct / needs_pr, which stay EMPTY
|
||||
# because the push step is skipped when raw_publish is ticked — so no dispatch,
|
||||
# no wait, no release PR, no second publish can fire from this job.
|
||||
if: inputs.raw_publish == 'true'
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VER="${{ steps.version.outputs.version }}"
|
||||
echo "::warning::raw_publish=true EMERGENCY RAW PUBLISH at ${VER}: deps download + npm run build ONLY — no typecheck, no tests, no CI lanes, no push to master. This log line is the permanent audit record of the bypass."
|
||||
npm install --no-audit --no-fund
|
||||
npm run build
|
||||
if [ -n "$(npm view billion-context@${VER} version 2>/dev/null || true)" ]; then
|
||||
echo "::error::v${VER} already exists on npm — refusing a raw re-publish"
|
||||
exit 1
|
||||
fi
|
||||
NPMTAG="latest"
|
||||
PRERELEASE="false"
|
||||
case "$VER" in *-*) NPMTAG="dev"; PRERELEASE="true";; esac
|
||||
npm publish --tag "$NPMTAG" --access public
|
||||
echo "::warning::RAW PUBLISHED v${VER} to npm (tag ${NPMTAG}) with zero typecheck/test/CI coverage. master is NOT updated yet."
|
||||
# Land the workspace bump as a commit BEFORE tagging / pushing the sync branch:
|
||||
# without it the tag points at a tree that still carries the OLD version
|
||||
# (poisoning later bugfix-lane cuts-from-tag), and the sync branch is byte-
|
||||
# identical to master -> empty diff -> GitHub 422 -> master never converges
|
||||
# and the next NORMAL one-click aborts on the drift guard. On the pending_
|
||||
# bump path nothing is staged and the commit harmlessly no-ops (head already
|
||||
# carries the bumped version).
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "github-actions[bot]@users.noreply.github.com"
|
||||
if ! git commit -q -m "release v${VER} (emergency raw publish; convergence via sync PR)"; then
|
||||
echo "::warning::nothing staged to commit (pending_bump path or clean tree) — tag/sync branch point at the current head as before"
|
||||
fi
|
||||
# --- convergence bookkeeping (best effort; a failure here never un-publishes) ---
|
||||
LAST_TAG="$(git describe --match 'v[0-9]*' --tags --abbrev=0 HEAD~1 2>/dev/null || true)"
|
||||
if [ -n "$LAST_TAG" ]; then
|
||||
NOTES="$(git log --no-merges --pretty='- %s' "${LAST_TAG}..HEAD~1")"
|
||||
else
|
||||
NOTES="(no prior release tag found)"
|
||||
fi
|
||||
git tag "v${VER}" && git push origin "v${VER}" \
|
||||
|| echo "::warning::git tag push failed — patch-lane derivation (bugfix-v* from latest tag) stays on the previous tag until fixed manually"
|
||||
RELEASE_PAYLOAD="$(mktemp)"
|
||||
VER="$VER" PRERELEASE="$PRERELEASE" NOTES="$NOTES" node -e '
|
||||
const fs = require("fs");
|
||||
fs.writeFileSync(process.argv[1], JSON.stringify({
|
||||
tag_name: "v" + process.env.VER, name: "v" + process.env.VER,
|
||||
prerelease: process.env.PRERELEASE === "true",
|
||||
body: "\u{1F6A8} **RAW EMERGENCY PUBLISH** (one-click \u0060raw_publish\u0060 checkbox, #5430): published straight from the pre-flight build — no typecheck, no tests, no CI lanes ran, and master was not pushed.\n\n## Changes since previous tag\n" + (process.env.NOTES || "(no changes recorded)"),
|
||||
}));' "$RELEASE_PAYLOAD"
|
||||
curl -sS -f -X POST -H "Authorization: Bearer $GH_TOKEN" -H "Accept: application/vnd.github+json" \
|
||||
-H "Content-Type: application/json" -d @"$RELEASE_PAYLOAD" \
|
||||
"https://api.github.com/repos/${{ github.repository }}/releases" >/dev/null \
|
||||
|| echo "::warning::GitHub Release creation failed (the npm publish itself succeeded)"
|
||||
SYNC_BRANCH="emergency-sync-v${VER}-$(date +%Y%m%d%H%M%S)"
|
||||
git push -q origin "HEAD:refs/heads/${SYNC_BRANCH}"
|
||||
PR_PAYLOAD="$(mktemp)"
|
||||
VER="$VER" SYNC_BRANCH="$SYNC_BRANCH" NOTES="$NOTES" node -e '
|
||||
const fs = require("fs");
|
||||
fs.writeFileSync(process.argv[1], JSON.stringify({
|
||||
title: "chore: sync package.json to v" + process.env.VER + " after emergency raw publish (#5430)",
|
||||
head: process.env.SYNC_BRANCH, base: "master",
|
||||
body: "Emergency raw publish put v" + process.env.VER + " on npm WITHOUT touching master (one-click \u0060raw_publish\u0060 checkbox). This tiny PR converges master (version bump + changelog/manifests only) so the next one-click release passes the drift guard. Merging it runs the normal CI lanes like any other PR and triggers NO second publish: release.yml gates on the \u0060*_release-v*\u0060 branch shape plus a \u0060release vX\u0060 commit subject, and this branch/title matches neither.\n\n## What shipped\n" + (process.env.NOTES || "(no changes recorded)"),
|
||||
}));' "$PR_PAYLOAD"
|
||||
RESP_FILE="$(mktemp)"
|
||||
HTTP_CODE=$(curl -sS -o "$RESP_FILE" -w '%{http_code}' -X POST \
|
||||
-H "Authorization: Bearer $GH_TOKEN" -H "Content-Type: application/json" \
|
||||
-d @"$PR_PAYLOAD" "https://api.github.com/repos/${{ github.repository }}/pulls")
|
||||
PR_URL=$(node -e 'try{console.log(JSON.parse(require("fs").readFileSync(process.argv[1],"utf8")).html_url||"")}catch(e){console.log("")}' "$RESP_FILE")
|
||||
echo "::notice::Version-sync PR for master convergence opened (HTTP ${HTTP_CODE})${PR_URL:+: ${PR_URL}}"
|
||||
{
|
||||
echo "### :rotating_light: RAW EMERGENCY PUBLISH v${VER}" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "- Published to npm (tag ${NPMTAG}) straight from the pre-flight build — no typecheck/tests/CI ran" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "- Git tag v${VER} pushed; GitHub Release body carries the raw-publish banner" >> "$GITHUB_STEP_SUMMARY"
|
||||
[ -n "$PR_URL" ] && echo "- Merge this version-sync PR to converge master: ${PR_URL}" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo "- Until then the next one-click release ABORTS on the drift guard (master behind npm) — by design" >> "$GITHUB_STEP_SUMMARY"
|
||||
}
|
||||
echo "done"
|
||||
|
||||
- name: Commit and push to master
|
||||
id: push
|
||||
# Skipped on the raw_publish path: that step already published and pushed
|
||||
# the tag; leaving direct/needs_pr empty deactivates every downstream
|
||||
# dispatch/wait/release-PR/publish step in this job.
|
||||
if: ${{ inputs.raw_publish != 'true' }}
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
TRAIN_NAME: ${{ steps.train.outputs.name }}
|
||||
@@ -184,6 +300,14 @@ jobs:
|
||||
git config user.name "github-actions[bot]"
|
||||
git config user.email "github-actions[bot]@users.noreply.github.com"
|
||||
VER="${{ steps.version.outputs.version }}"
|
||||
if [ "${{ steps.driftguard.outputs.pending_bump }}" = "true" ]; then
|
||||
# Pending-bump: master already IS the publish content (release version, changelog and
|
||||
# manifests landed via the merged fallback bump PR). Nothing to commit; every
|
||||
# direct-gated downstream step (Full CI dispatch/gate, tag, publish) applies as-is.
|
||||
echo "pending-bump: master already carries v$VER — publishing the current master head, no release commit needed."
|
||||
echo "direct=true" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
git commit -q -m "release v$VER"
|
||||
if [ -n "$TRAIN_NAME" ]; then
|
||||
# Train mode: the release commit lands ON THE TRAIN; publishing is
|
||||
@@ -232,7 +356,7 @@ jobs:
|
||||
# fallback path fixed (#3539) — without it ci.yml lands only the CORE
|
||||
# matrix at the release sha, and a windows+node-24-only regression
|
||||
# can publish before any CI leg sees it.
|
||||
if: steps.push.outputs.direct == 'true'
|
||||
if: ${{ steps.push.outputs.direct == 'true' && !inputs.skip_ci_gate }}
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
RELEASE_RUN_STARTED_AT: ${{ github.run_started_at }}
|
||||
@@ -243,13 +367,18 @@ jobs:
|
||||
export GITHUB_SHA GITHUB_REF_NAME
|
||||
node scripts/release-ci-gate.mjs --dispatch
|
||||
|
||||
- name: Acknowledge CI-gate bypass (emergency checkbox)
|
||||
if: ${{ inputs.skip_ci_gate && (steps.push.outputs.direct == 'true' || steps.push.outputs.needs_pr == 'true') }}
|
||||
run: |
|
||||
echo "::warning::skip_ci_gate=true: publishing WITHOUT waiting for the full CI lanes at this sha. Only the pre-flight typecheck+build ran. This log line is the permanent audit record of the bypass."
|
||||
|
||||
- name: Full CI gate (all lanes green at the release commit)
|
||||
# Hard precondition for publish: every required lane green at the
|
||||
# publish sha. Any red lane or timeout ⇒ release fails, nothing is
|
||||
# published. The dispatch step above already refused to fire when
|
||||
# master's head was not this commit (#3539); a later push does not
|
||||
# invalidate runs already landed at it.
|
||||
if: steps.push.outputs.direct == 'true'
|
||||
if: ${{ steps.push.outputs.direct == 'true' && !inputs.skip_ci_gate }}
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
RELEASE_RUN_STARTED_AT: ${{ github.run_started_at }}
|
||||
@@ -261,7 +390,9 @@ jobs:
|
||||
node scripts/release-ci-gate.mjs --wait
|
||||
|
||||
- name: Dispatch full CI on fallback branch
|
||||
if: steps.push.outputs.needs_pr == 'true'
|
||||
# #5430 emergency path: with skip_ci_gate ticked nothing is dispatched or
|
||||
# awaited — the owner explicitly traded full-lane verification for speed.
|
||||
if: steps.push.outputs.needs_pr == 'true' && !inputs.skip_ci_gate
|
||||
continue-on-error: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -371,6 +502,7 @@ jobs:
|
||||
PR_BRANCH: ${{ steps.push.outputs.pr_branch }}
|
||||
TRAIN_NAME: ${{ steps.train.outputs.name }}
|
||||
RECONCILE: ${{ steps.reconcile.outputs.missing_md }}
|
||||
SKIP_GATE: ${{ inputs.skip_ci_gate }}
|
||||
run: |
|
||||
VER="${{ steps.version.outputs.version }}"
|
||||
LINK="https://github.com/${{ github.repository }}/pull/new/${PR_BRANCH}"
|
||||
@@ -387,9 +519,12 @@ jobs:
|
||||
const intro = process.env.TRAIN_NAME
|
||||
? "Ship PR for the patch train (dual-lane release): merging publishes the PRE-MERGE head tree — the base tag plus exactly this train\u2019s fixes, none of master\u2019s unreleased work — via release-bugfix.yml."
|
||||
: "Auto-fallback from the one-click release workflow: direct push to master was blocked by branch protection. Merging this PR publishes via the standard release.yml flow.";
|
||||
const skipBanner = process.env.SKIP_GATE === "true"
|
||||
? "\u{1F6A8} **EMERGENCY BYPASS ACTIVE**: the one-click run that prepared this PR ticked `skip_ci_gate` — no full-CI lane was dispatched or awaited at this sha. Merging publishes code CI has not verified here; the audit warning lives in that run log.\n\n"
|
||||
: "";
|
||||
const warn = process.env.RECONCILE ? process.env.RECONCILE + "\n" : "";
|
||||
const body = [
|
||||
intro,
|
||||
skipBanner + intro,
|
||||
"",
|
||||
warn,
|
||||
"## Changes since " + (process.env.LAST_TAG || "n/a"),
|
||||
@@ -446,7 +581,9 @@ jobs:
|
||||
exit 0
|
||||
|
||||
- name: Wait for full CI green on fallback branch (track head)
|
||||
if: steps.push.outputs.needs_pr == 'true'
|
||||
# Same guard as the dispatch step above: the emergency checkbox must not
|
||||
# be silently ignored on the fallback path (v0.1.211 stuck here 2026-11-01).
|
||||
if: steps.push.outputs.needs_pr == 'true' && !inputs.skip_ci_gate
|
||||
continue-on-error: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -497,7 +634,7 @@ jobs:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
run: |
|
||||
VER="${{ steps.version.outputs.version }}"
|
||||
LAST="$(git describe --tags --abbrev=0 2>/dev/null || echo "")"
|
||||
LAST="$(git describe --match 'v*' --exclude "v$VER*" --tags --abbrev=0 2>/dev/null || echo "")"
|
||||
NOTES="$RUNNER_TEMP/release-notes.md"
|
||||
if [ -n "$LAST" ] && [ "$LAST" != "v$VER" ]; then
|
||||
{
|
||||
|
||||
@@ -4,9 +4,21 @@ on:
|
||||
push:
|
||||
branches: [master]
|
||||
|
||||
# 2026-10-31 queue-starvation incident: every master merge triggered a Release run;
|
||||
# a busy day stacked eight of them and, once runner capacity returned, they all
|
||||
# started CONCURRENTLY, burning ~8x slots while each mostly no-ops ("not a release
|
||||
# merge" check). Grouping serializes them — a queued no-op costs ~2 min.
|
||||
# cancel-in-progress stays FALSE deliberately: two real back-to-back releases must
|
||||
# publish in order; cancelling a publishing run mid-tag / mid-npm-publish would
|
||||
# strand its version (#3071 discipline).
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
release:
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 90
|
||||
permissions:
|
||||
contents: write
|
||||
id-token: write
|
||||
|
||||
@@ -6,6 +6,8 @@ dist/
|
||||
.bili-coop-build-stamp
|
||||
tmp/
|
||||
tests/.pp-stamp-state-*/
|
||||
tests/.billing-state-*/
|
||||
tests/.billing-web-state-*/
|
||||
.tmp/
|
||||
plugin-lanes/
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> **This document is the highest-priority specification. All developers (including AI Agents) MUST comply.**
|
||||
>
|
||||
> **How to read this:** the rules and invariants below are loaded every session and are the operative contract. Long procedures, file listings, and test/release/git mechanics live in [`reference/`](reference/) and are **not** auto-loaded — follow the inline `→ reference/…` pointers when you hit that task; don't guess at a procedure, open the file.
|
||||
> **How to read this:** the rules and invariants below are loaded every session and are the operative contract. Long procedures, file listings, and test/release/git mechanics live in [`reference/`](reference/) and are **not** auto-loaded — follow the inline `→ reference/…` pointers when you hit that task; don't guess at a procedure, open the file. The Key Design Decisions (KDD) below carry each entry's **operative consequence**; the full mechanism text (Tier B entries) lives verbatim in [reference/design-decisions.md](reference/design-decisions.md) — KDD numbering is stable and public, the ledger there is append-only.
|
||||
|
||||
## 1. Project Overview
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
| Language | TypeScript (strict, ESM) |
|
||||
| Build | tsup (bundling; inlines the in-repo kernel `kernel/`) |
|
||||
| Test | Node.js built-in: `node --import tsx --test tests/*.test.ts` |
|
||||
| Runtime Dep | the in-repo compression kernel (`kernel/`, npm name `acp-kernel`, bundled inline at build time) + `zod` (external, only used by `dist/agent/opencode-native.js` V1 tools; `dist/index.js` stays dependency-free) |
|
||||
| Runtime Dep | the in-repo compression kernel (`kernel/`, npm name `acp-kernel`, bundled inline at build time) + a small set of lazy external deps: `zod` (exact `4.6.7`, only `dist/agent/opencode-native.js` V1 tools), `mysql2` (opt-in network storage backend, `await import` at backend open), `jimp` (image processing, #3516) — the main entry `dist/index.js` stays dependency-free |
|
||||
|
||||
### Repository Info
|
||||
|
||||
@@ -30,45 +30,47 @@
|
||||
|
||||
### Module Map
|
||||
|
||||
The full file-by-file map lives in [reference/architecture.md](reference/architecture.md) — it drifts as modules land, so **regenerate it when you add/remove a source file; don't trust a stale copy**. Orientation at a glance: `src/server.ts` (+ `src/loop/**` adapters) is the request pipeline; `src/update.ts` is the load-bearing self-updater; `src/persist.ts` + `src/session-id.ts` own persistence/identity; `tests/e2e/` holds the real-client regression suites; the compression engine itself lives in-repo under `kernel/` (the acp-kernel source, #2092).
|
||||
The full file-by-file map lives in [reference/architecture.md](reference/architecture.md) — it drifts as modules land, so **regenerate it when you add/remove a source file; don't trust a stale copy** (CI lane `architecture-docs` enforces full `src/` coverage, #5924). Orientation at a glance: `src/server.ts` + `src/server/` (handle / prepare-* / relay / lane-decisions / snapshot-render / threads-lane / fastpath / admin) + `src/loop/**` (core + wire adapters) is the request pipeline; `src/update.ts` is the load-bearing self-updater; `src/persist.ts` + `src/session-id.ts` own persistence/identity; `src/storage/` is the unified storage layer (SQLite by default, opt-in MySQL backend); `tests/e2e/` holds the real-client regression suites; the compression engine itself lives in-repo under `kernel/` (the acp-kernel source, #2092).
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
1. **The in-repo kernel is bundled inline** — `kernel/` (the acp-kernel source, consumed as a `file:` devDependency, #2092) is NOT listed in tsup `external`, so `dist/index.js` is self-contained. Exception: `zod` (exact `4.1.8`, matching the opencode host's own zod so V1 plugin-tool shapes interoperate) is a real dependency and stays external — only `dist/agent/opencode-native.js` imports it (lazily, at plugin-tool registration); `dist/index.js` and every other entry remain zod-free. When zod cannot be resolved at runtime the V1 plugin degrades to plain proxy mode instead of failing. Same for `pi-subagents/` (the billion-context-pi-subagents source, #2384): consumed via a `file:` devDependency and inlined into the pi-lane entries; its own build inlines the `typebox` peer, so those bundles stay self-contained too.
|
||||
Tier A entries are every-session rules and stay in full below. Tier B entries carry their operative consequence inline; full text → [reference/design-decisions.md](reference/design-decisions.md) (same number).
|
||||
|
||||
1. **The in-repo kernel is bundled inline (Tier B)** — `kernel/` and `pi-subagents/` are `file:` devDependencies inlined by tsup, so every `dist/` entry stays dependency-free; the ONE exception is `zod` (exact `4.6.7`) — imported only by `dist/agent/opencode-native.js` (lazily), every other entry zod-free; unresolvable zod degrades the V1 plugin to plain proxy mode, never fails. Full text: design-decisions.md #1.
|
||||
2. **Tags use XML format** — messages carry ACP tags like `<acp tokens="2" type="text">m00001</acp>` (an opening element with `tokens=`/`type=` attributes wrapping a ref id, closed by its end element). In **source files** these angle brackets MUST be written as hex escapes (`\x3c`, `\x3e`) to avoid tooling that strips well-formed tags.
|
||||
3. **Auto-update**: checks npm registry every 3 min by default (`CHECK_INTERVAL_MS = 3*60*1000`, overridable via `update.checkIntervalMs` / `BILI_UPDATE_CHECK_INTERVAL_MS`, #2030); first check per process ignores throttle. In plugin mode the injected code lives in the HOST process — new code only takes effect after a host restart, and if the injection breaks at runtime, model traffic goes direct (uncompressed) until the host is restarted; since #3581 that state is visible via the panel banner and `/__bili/status` `attribution` field (README Self-update section).
|
||||
4. **Tee logger**: all proxy logs go through `src/logger.ts` (file + stderr). Do NOT use `console.error` in server-side modules — use `loggerLog()`.
|
||||
5. **The kernel lives in-repo; determinism comes from git, not a registry pin (#2092).** The acp-kernel source is vendored under `kernel/` and consumed via `"acp-kernel": "file:./kernel"` (devDependency; inlined into `dist` at build time). A commit IS the pin — there is no registry range left to drift. The kernel keeps its OWN version in `kernel/package.json`: any kernel source change MUST bump it (CI-enforced — see Kernel Boundary below), so accumulated changes can later ship as an independent npm release of `acp-kernel`. `package-lock.json` records the file link and stays committed. Same pattern for `pi-subagents/` (#2384): vendored under `pi-subagents/`, consumed via `"billion-context-pi-subagents": "file:./pi-subagents"`, own version in `pi-subagents/package.json` (CI-enforced — see Pi-Subagents Boundary below).
|
||||
3. **Auto-update (Tier B)** — registry check every 3 min by default (knobs `update.checkIntervalMs` / `BILI_UPDATE_CHECK_INTERVAL_MS`, #2030); first check per process ignores throttle. Plugin mode injects code into the HOST process: new code needs a host restart; a broken injection runs model traffic direct (uncompressed) until restart — visible via panel banner + `/__bili/status` `attribution` (#3581). Full text: design-decisions.md #3.
|
||||
4. **Tee logger** — all proxy logs go through `src/logger.ts` (file + stderr). Do NOT use `console.error` in server-side modules — use `loggerLog()`.
|
||||
5. **The kernel lives in-repo; determinism comes from git, not a registry pin (#2092) (Tier B)** — consumed via `"acp-kernel": "file:./kernel"`; a commit IS the pin. Any kernel source change MUST bump `version` in `kernel/package.json` (CI-enforced — see Kernel Boundary); `pi-subagents/` follows the same pattern. Full text: design-decisions.md #5.
|
||||
6. **Single-writer plugin copies (#991)** — every bili presence has exactly ONE writer; mixing writers is what the guard forbids. The canonical statement is the Install-Lane & Update-Ownership Contract below.
|
||||
7. **Two compression modes with different summary carriers** (CRITICAL — reason in BOTH, see §6):
|
||||
- **pluginMode** (the `x-bili-plugin` header / registered agent, e.g. `bili pi`): the ACP-native agent OWNS compression — it executes `compress` locally, the call+result live in its own re-sent history, and the wire summary carrier is the **tool call** (the proxy suppresses tool + nudge injection; the agent's view never renders the kernel's `acp_summary`).
|
||||
- **proxy mode** (plain client, no header): the proxy executes `compress` server-side; the tool call is ephemeral (never enters the client's history) and preflight blocks have none, so the carrier is the **`acp_summary` message** — the kernel renders it role `system`, but `systemToUser` (`src/util.ts`) re-voices it as a **`user` message** (leaving it at its anchor) so strict backends (SGLang: exactly one system at index 0, #377) accept it and the head system message stays byte-stable for the prefix cache.
|
||||
- The mode is decided per request and bound per session (`session.metadata.pluginAgent`, sticky, upgrade-only). See TECHNICAL-NOTES.md "Two compression modes".
|
||||
- The mode is decided per request and bound per session (`session.metadata.pluginAgent`, sticky, upgrade-only). See docs/technical-notes.md "Two compression modes".
|
||||
8. **Nudge cadence is flat 50K by design (kernel contract)** — acp-kernel pins the growth interval at 50000 for every window size (`nudge.growthFloor == nudge.growthCap == 50000`; window-percentage scaling was deliberately removed — #379/#380 settled "growth-driven, no usage/count proxy gates"). Do NOT re-scale the interval with the context window or reintroduce percentage gates; a 1M-window session folding every 50K of growth is intended lean-context behavior. User escape hatch: `compress.nudgeGrowthTokens` (flattens `growthFloor`+`growthCap` to a fixed step) — big-window users who want a lazier cadence set it explicitly. Prompt wording is kernel-owned (`src/nudge-text.ts`).
|
||||
9. **Hosts that reuse ONE session id across personas get id + system-hash session keys ("hash 不一样自动分裂")** — when a plugin host stamps the SAME conversation id on every model request of a session INCLUDING auxiliary personas (dsh auto-review `classifyRisk()`: fixed REVIEW_POLICY system + a fresh flattened blob before every tool call — #1916/#1307/#1314), those auxiliary requests must be keyed by `subagentNamespace(id, systemText)` so the persona forks onto its own `<id>|sub:<fp>` session instead of overwriting the main session's baseline/snapshots. The FIRST system seen under the id keeps the raw key (kernel anchor), so main turns never fork; an empty system is non-anchoring (verbatim); SIDE REQUESTS never claim the anchor either — dsh's title-gen sidecar fires at session start before/concurrent with the first main turn, and claiming it would fork the whole main conversation onto `|sub:<fp>` while every host-stamped ACP management call (compress/decompress/acp_status) routes into the ghost's empty session and fails forever (#2156/#2160; the `sideRequestLike` gate in `src/server.ts` mirrors the #388 passthrough predicate). This is an EVIDENCE-PERMITLIST (`dshPersonaFingerprintApplies` in `src/session-id.ts`), the same discipline as the instructions fingerprint (#1104/#1107): do NOT enable it wholesale — for everyone else system drift mid-id means "same conversation, evolved", and forking resets compression for no defending bug (#1106). A future host found reusing session ids across personas gets added to that predicate WITH traffic evidence (shape + stability proof: the host's main system must be session-stable, e.g. dsh composes it once per session and puts volatile time-context in a USER message). The fork must record itself under its suffixed id (`personaForked` → `recordPluginSession`) so the single-valued conversations map keeps the raw key owned by the main session (#970 discipline). Tests: `tests/dsh-persona-fingerprint.test.ts`.
|
||||
|
||||
9. **Persona hosts get id + system-hash session keys ("hash 不一样自动分裂") (Tier B)** — when a plugin host stamps the SAME conversation id on auxiliary personas, those requests MUST be keyed by `subagentNamespace(id, systemText)` → `<id>|sub:<fp>`, never overwriting the main session. The FIRST system seen under an id keeps the raw key (kernel anchor); an empty system is non-anchoring; SIDE REQUESTS never claim the anchor. This is an EVIDENCE-PERMITLIST (`dshPersonaFingerprintApplies`, same discipline as #1104/#1107): do NOT enable it wholesale; a new host joins only WITH traffic evidence. Forks record under their suffixed id (`personaForked` → `recordPluginSession`, #970). Full text: design-decisions.md #9.
|
||||
10. **Thinking-family blocks are signature-verified — NEVER rewrite them (#1960)** — Anthropic `thinking`/`redacted_thinking` blocks and Gemini `thoughtSignature` parts are verified byte-for-byte when the latest assistant message is replayed ("thinking blocks ... cannot be modified"). The bytes the proxy forwards become the client's persisted history, and the bytes the loop accumulates become the re-request rebuild — BOTH must stay verbatim. Any transformation (tag/marker stripping, dedup, trimming, re-laying-out block order, dropping empty segments) desynchronizes text from signature and bricks the session: first on the in-turn re-request, then on every subsequent request via the client's echo. #1882 put a prose filter on the thinking channel and it was exactly this bug. Treat ANY future change touching thinking-family payloads as high-risk: it needs loop-level byte-equality tests (re-request body AND client-visible stream) on both signed wires, not just adapter-level ones. The prose filters (#206/#1881) are for the TEXT channel only.
|
||||
11. **身份层级:msgid > 顺序 > hash (Tier B)** — 三层裁决:**(1) msgid 第一**——四条插件车道把宿主 msgid 作为私有信封字段上行,**只存在于宿主↔bili 之间,从不出现在模型线上**;msgid 有效时账本身份以它为准;全有全无——筛查失败/长度不符静默降级为内容 hash;账本主键仍是 (session_id, msg_id, content_hash) 三元组。**(2)无 msgid 时顺序是身份主载体**(fold-state reconcile 的 order-centric ladder)。**(3)hash 为辅助**——逐格硬门但**无全局否决权**:任何单维度 miss 不得级联成全量 unfold;id/指纹失配只作废该格、位置扫描在 MIN_RESYNC_RUN 连续同意后 resync;"never fuzzy similarity" 不变(hash 是逐格硬门);"substrate destroyed" 判决只可计 resync 存活且过内容 pass 的 gap。Full text: design-decisions.md #11。
|
||||
12. **资格判定与执行共用单一投影 (shared unit-projection judgment, #3236) (Tier B)** — whether a range is foldable has exactly ONE definition: `projectUnit` (`kernel/src/unit-projection.ts`), returning the projection OR the ready-to-throw fatal error. The apply side throws it byte-identically; recommend re-screens final merged units and demotes fatal units to gaps (no re-merge after filtering — anti-oscillation); `acp_status` flags rows additively (never drops). Judgment MUST run on the EXACT array class `applyCompression` executes on — hosts whose render view differs pass `applyView` / `StatusReportOptions.originalMessages`. Full text: design-decisions.md #12.
|
||||
13. **出站历史渲染:快照即会话 (snapshot render — #3756, D-lane) (Tier B)** — 绑定 session id 且统一存储可读的会话,出站**前缀**由服务端正史渲染(消息身份 = 服务端行 `seq`);尾巴保持客户端逐字。**任何失步(开关关/无活跃块/存储不可读/链不上)整轮回退 legacy——降级,不猜**;永不复活已覆盖行;观测(`reconcileFoldCoverage`)与渲染刻意分离。规则推论:凡讨论「覆盖 id 失配/destroyed 误诊/断缓存」类 bug,先问是否 D 车道——那类病理在 D 上结构性不存在。Full text: design-decisions.md #13.
|
||||
14. **verif 模块:kernel 决策核的求解器验证 (#3848, PR #3853) (Tier B)** — `verif/` 把守护清单(`verif/guarded-files.ts` Tier A)的真实 TS 翻译成 SMT,cvc5/z3 找反例,反例必须回放真代码复现。**改守护清单文件:常规测试之外必须过 `tests/verif-subset-guard.test.ts`(秒级)+ 涉及的 `tests/verif-bug*`/`verif-generic-*`/`verif-induction-*`**(无求解器环境自动 skip)。新语法先让翻译器支持;例外登记 `verif/exceptions.ts`(过期即红)。教义:`verif/README.md`。Full text: design-decisions.md #14.
|
||||
15. **全量重发水位快路径 (full-resend watermark — #5403/#5418, rollout `pluginFullResendWatermark` 5% 灰度) (Tier B)** — 服务端在成功响应盖 `x-bili-pf-seq`(messages 元素数,零分配结构扫描测出);客户端回带 `x-bili-pf-count` + `x-bili-pf-tail-ids`(宿主 msgid;v4 下 K 取自**服务端账本**)。命中 = 上一轮 canonical cores + 仅尾窗 [K..T) 新解析(跳整包 parse/转换/钉存——#5403 OOM 生产者)。**任何疑点整轮走原封未动的 legacy 全量路径并重新盖戳**(客户端一轮收敛);5 次连续可证实 miss ⇒ 熔断持有一小时。诚实边界:保元素数的前缀字节改写**不可检测**(§7.4 人工评审档);多模态尾部入缓存后该段历史永久回 legacy 轮;pf-* 是协议头不是 hop 头(转发上游前剥,`UPSTREAM_HOP_HEADERS`)。与增量车道可同开、按请求形状分轨不双处理(anthropic wire→增量 divert;openai 形→水位)。Full text: design-decisions.md #15.
|
||||
16. **Notice surface: one registry, three sources, B>A>S shadow (#5548) (Tier B)** — every web-UI banner flows through ONE loop consuming `mergedNotices()`: **S**=built-in (`src/notices.ts`, dead-key-guarded) / **A**=remote feed (`announcements/remote.json`, ~3-min poll, fail-open) / **B**=local files (`<config dir>/announcements/*.json`); equal ids shadow B>A>S. **Exactly ONE banner channel exists — no bespoke feed fetchers, dismissal stores, or inline banners.** Adding a builtin = `src/notices.ts` entry + en/zh i18n pair + registry-test row (+ config yaml seed + `gen-config-docs` when a knob ships). Dismissal receipts live in unified storage (`kv_store` namespace `notices`). Full text: design-decisions.md #16.
|
||||
17. **消息身份公用设施 (sessionid+msgid) 生产/消费声明 (#5826) (Tier B)** — sessionid+msgid 是跨四车道的公用设施,**改任何一处前必须读懂生产与消费来源**(完整地图 `docs/msgid-infrastructure.md`)。生产:宿主铸稳定 UUID(`acp_summary_*` 为 kernel 保留命名空间,宿主 id 不得占用);采集器只做拿到+初筛;四种传输载体**全部转发上游前剥除**。消费五方:统一存储 `messages.msg_id`(唯一 id 事实源)/ session-resolve 末档 #5719 / 结算 membership #4805 / 增量车道 #4491 / 水位尾连续性 v2-v4。校验规则**六份镜像副本**(宿主 bundle 禁 import server 模块的结构性约束):`tests/msgid-rule-parity.test.ts` 钉死每份副本判决——**改任何一份规则必须先过该测试(有意分歧须显式重钉+写明理由)**。Full text: design-decisions.md #17.
|
||||
|
||||
11. **顺序为中心,hash 为辅助 (order-centric reconciliation — owner rule, 2026-10-12, #2821/#2915)** — fold-state reconciliation must treat ORDER as the primary carrier of message identity across resent histories: position claims verified spans (with per-cell fingerprint gates), content hashes and tool-call ids are auxiliary evidence, and NO single dimension's miss may cascade into total unfold. The identity dimensions survive different churn classes — order survives re-encoding AND id re-minting, content survives id churn, ids survive re-encoding — so the ladder is the union of their survival domains, and each rung fails soft: an id/fingerprint mismatch voids that CELL's claim only; the positional scans resync at the next run of same-index agreements (MIN_RESYNC_RUN consecutive matches, bounded gaps) and keep claiming verified spans behind the break. Genuinely changed cells (real edits, regenerations) stay honestly unmatched and re-enter the wire — "never fuzzy similarity" (mis-attribution is the most expensive failure, MESSAGE-IDENTITY.md) is unchanged: the hash stays a HARD per-cell gate, it just no longer holds a global veto over its neighbors. Escalation to "substrate destroyed" may only count gaps that survived resync AND the content passes (byTool/byTwin/byNorm/byTurn). #2821 was the canonical violation: a mid-session model switch re-minted every tool-call id on re-projection (content byte-identical), both positional flank scans died at their FIRST cell (changed preamble at the head, appended turn at the tail), 3289 covered ids went missing, three passes → destroyed verdict → total unfold → doomed-probe 502. #2396's detection-only twins are promoted to a claiming pass (Pass 1.5, k-th discipline + length guard) so id re-mints recover even without a stored positional copy — and after one churn pass the self-saved {ids, canon} copy upgrades recovery to the positional path. A Pass-0 gap cell (order break) is resolved by tiers, owner rule 2026-10-12: any exact channel that matches claims it; failing that, simhash corroboration (≤8 bits on the 64-bit word-shingle sketch — measured margins: re-wording ≈6-8 bits inside, negation flips ≈11 / word drops ≈13 / key reorders ≈21 outside) claims it; failing that, the ORDER BRACKET — same index strictly between VERIFIED claims on both flanks — asserts the SLOT (the owner-sanctioned delete+insert tradeoff: coverage rides the slot, the stale bytes do not); with zero corroboration and no fence the cell stays honest unmatched drift. Deletion is honest loss: the flanks absorb the shift, the deleted id never gets a bracket claim (its slot cell is consumed by the verified tail). Tests: `tests/issue2915-order-centric-reconcile.test.ts`.
|
||||
12. **资格判定与执行共用单一投影 (shared unit-projection judgment, #3236)** — whether a candidate range is foldable has exactly ONE definition: `projectUnit` in `kernel/src/unit-projection.ts` (applySingleRange's pre-block sequence extracted verbatim: boundary widening → carrier/coverage/media/protected-tool carve → protected-zone carve → turn-integrity withdrawal → emptiness), returning either a structured projection or the ready-to-throw fatal error (`zone`/`split`). The apply side throws it byte-identically; the recommend side re-screens every FINAL merged unit through it and demotes fatal units to gaps (no re-merge after filtering — anti-oscillation); the acp_status uncompressed view runs it per displayed row and appends an additive ⚠ flag (diagnostic surface: rows are flagged, never dropped). The judgment must run on the EXACT array class `applyCompression` executes on: hosts whose render view differs from their apply class pass it via `ProcessTurnInput.applyView` / `StatusReportOptions.originalMessages` (plugin lane = raw history per #2627; relay loop = `prepared.originalMessages`); absent it, judgment falls back to the pre-prune original (#2663) or the given view. The bug fixed: recommend judged turn-integrity over the GLOBAL compressible set while apply judged the PER-SUBMITTED-RANGE set — a turn whose partners sat in different advertised units passed global screening yet split per range, producing a permanent advertise→reject loop ("Range would split N turn(s)"). Tests: `kernel/tests/issue3236-recommend-apply-consistency.test.ts`.
|
||||
### #18 — 身份信道接线:所有车道接进同一采集缝,消费者永不直读客户端存储 (#5825) (Tier B)
|
||||
|
||||
13. **出站历史渲染:快照即会话(snapshot render — #3756,rollout `snapshotRender` 默认 0%)** — 消息身份的演进分三段:content-hash 认身份(账本 join,至今有效)→ order-centric reconcile(#2821/#2915/#3641:顺序为主、hash 为辅助证据、判决分类)→ **快照渲染**:对绑定了 session id 且统一存储可读的会话,prepare 层的出站**前缀**由服务端正史渲染(`src/server/snapshot-render.ts`),消息身份 = 服务端行 `seq`,hash/签名只作链回溯兜底(定位客户端逐字尾巴的 join 点);覆盖由块的 seq/签名集**引擎自拥**(不信 reconcile 的 re-key 产物),锚从块状态原位重渲;尾巴保持客户端逐字(缓存稳定)。任何失步(开关关/无活跃块/存储不可读/链不上)整轮回退 legacy 路径——**降级,不猜**;客户端头部 checkpoint 一轮采用滞后,永不复活已覆盖行。观测与渲染刻意分离:`reconcileFoldCoverage` 继续观察客户端视图。完整教义与诚实边界:MESSAGE-IDENTITY.md「快照渲染引擎」。规则推论:凡讨论「覆盖 id 失配/destroyed 误诊/断缓存」类 bug,先问该会话是否走 D 车道——D 上这类病理结构性不存在,修不到点子上等于在修已死的路径。
|
||||
|
||||
14. **verif 模块:kernel 决策核的求解器验证(#3848,PR #3853)** —— `verif/` 目录 + `tests/verif-*.test.ts` 把守护清单内文件(`verif/guarded-files.ts`,Tier A:compress / hide-consumed / refs / render-refs / truncate / truncate-tools / tokenize / rebuild / wire/openai / wire/responses)的真实 TypeScript 翻译成 SMT 公式,用 cvc5/z3 找违反缓存稳定不变量的反例,反例必须回放真代码复现。约束:**改守护清单内的文件,除了常规测试还必须过 `tests/verif-subset-guard.test.ts`(子语言守卫,秒级)和涉及的 `tests/verif-bug*.test.ts` / `tests/verif-generic-*.test.ts` / `tests/verif-induction-*.test.ts`(求解器测试需 `VERIF_PYTHON` 指向装了 cvc5 的 python;无求解器环境自动 skip 不会红)**。新语法想进守护范围,翻译器先支持(守卫报啥补啥),例外在 `verif/exceptions.ts` 登记且过期即红。写新 harness 遵守 `verif/README.md` 的无作弊规则(只调真入口/不变量通用/反例回放/负控制必备)。求解器发现的 bug 一律开 issue + 回归钉(已产出:#3691/#3769/#3676/#3805 形状钉 + 新发现 #3935/#3945)。模块教义与边界:先读 `verif/README.md`。
|
||||
身份信号来源只有三类:**宿主写入**(msgid body 字段 / 信封 `msgIds` / pf 头)、**宿主盖戳头**(opencode V2 `x-bili-msg-ids`)、**自包含采集器**(`src/identity-harvest.ts` 注册表 + `src/identity-<client>.ts` 适配器;双门:env `BILI_IDENTITY_HARVEST` 或灰度键 `rollout.features.identityChannelHarvest`,均默认关 × 仅回环来源)。**消费者(#5719 归属档 / pin-行链路 / membership / 水位)只从统一缝取数**:handle 入口每请求按「body 字段 > 盖戳头 > 采集」取一次快照——绝不新增「逐调用点单独取数」。新车道 = 新适配器文件 + barrel 一行登记 + 文档一行;适配器自包含、整轮退化(任一环节不判定 ⇒ 该轮整体回退接线前路径,绝不做部分映射)。车道状态表与信任边界:docs/identity-channels.md;身份判定逻辑:docs/session-identity-resolution.md。Full text: design-decisions.md #18.
|
||||
|
||||
### Install-Lane & Update-Ownership Contract (#1196)
|
||||
|
||||
Every bili presence on a machine follows ONE contract — decide changes against it, not ad hoc:
|
||||
|
||||
1. **One writer per copy, chosen by the install SOURCE.** A copy installed through a host's own channel (dsh plugin market, opencode/pi managers, pnpm store) is owned by that host: bili NEVER writes it in place (#991, `hostManagedInstall`). `bili plugin install <agent>` only ever DRIVES the host's channel (e.g. `dsh plugin add`), never installs a second bili-owned copy beside it (#966).
|
||||
2. **Every copy must have a LIVE update path** — the actual fix for the "frozen forever" bug class (#1196). Exactly one of:
|
||||
- it IS the global install (npm `i -g`): self-updates in place;
|
||||
- it is a reference lane (omp/claude/codex/kimi/zcode/hermes entries): no copy at all, points at the global dist, follows it automatically;
|
||||
- it lives in a host world (dsh profile bundle, opencode/pi tree): updated through the HOST's channel — driven by a global self-update AND, when no global ever runs (market-only users), by the copy's own periodic check (`refreshDshProfileCopy`, #1196). Self-heal goes THROUGH the owner's sanctioned channel, never around it.
|
||||
3. **Terminal users get the one-copy experience via launchers** (`bili dsh` overlay mode loads the global dist, no persistent copy); market users get self-contained per-context copies. Both are first-class; the user picks by entry point, and the two modes never mix for one lane (duplicate `bili-native` loader ids hard-fail dsh boot).
|
||||
4. **Local pins stay manual.** `link:`/`file:` dev pins are never refreshed (`isRegistryDepSpec` gate) — dev lanes track a live checkout by design.
|
||||
5. **Transient drift is acceptable and bounded**: lanes converge to the registry version within one check cycle (~3 min) plus a host restart. Permanent divergence is a bug — file it under this contract.
|
||||
6. **An in-place writer keeps ALL THREE LEDGERS in step (#3496).** The desktop profile is the one copy bili owns outright (#1575); its self-heal swaps `node_modules/billion-context` directly, so it must ALSO move the profile manifest's declared spec AND the lockfile's recorded resolution (specifier + version) in the same operation (`convergeDshLedger`, `src/dsh-ledger.ts`) — a writer that moves only the copy manufactures exactly the wedge #3224 detects and #3160 bit users on (stale lock record / unresolvable manifest spec → next `pnpm install` 404s or silently reverts the update). Pre-existing drift converges on explicit demand only: `bili doctor --fix`.
|
||||
2. **Every copy must have a LIVE update path** (the fix for the "frozen forever" bug class, #1196) — exactly one of: it IS the global install (self-updates in place) / it is a reference lane (omp/claude/codex/kimi/zcode/hermes — no copy, points at the global dist) / it lives in a host world (dsh profile bundle, opencode/pi tree — updated THROUGH the host's channel, by a global self-update AND, when no global ever runs, the copy's own periodic check `refreshDshProfileCopy`). Self-heal goes THROUGH the owner's sanctioned channel, never around it.
|
||||
3. **Launchers give the one-copy experience** (`bili dsh` overlay mode loads the global dist, no persistent copy); market users get self-contained per-context copies. Both first-class; the two modes never mix for one lane (duplicate `bili-native` loader ids hard-fail dsh boot).
|
||||
4. **Local pins stay manual.** `link:`/`file:` dev pins are never refreshed (`isRegistryDepSpec` gate).
|
||||
5. **Transient drift is acceptable and bounded:** lanes converge to the registry version within one check cycle (~3 min) plus a host restart. Permanent divergence is a bug — file it under this contract.
|
||||
6. **An in-place writer keeps ALL THREE LEDGERS in step (#3496):** the desktop dsh profile is the one copy bili owns outright; its self-heal swaps `node_modules/billion-context` directly, so it must ALSO move the profile manifest's declared spec AND the lockfile's recorded resolution in the same operation (`convergeDshLedger`, `src/dsh-ledger.ts`) — a writer that moves only the copy manufactures the wedge #3224 detects. Pre-existing drift converges on explicit demand only: `bili doctor --fix`.
|
||||
|
||||
Machine-global facilities stay SHARED across all copies (deliberately): `~/.local/state/billion-context/` (log + sessions, #394 multi-instance warning), `~/.cache/billion-context/` (update throttle + cross-process update lock), `~/.config/billion-context/` (providers/compress config).
|
||||
|
||||
@@ -77,28 +79,28 @@ Machine-global facilities stay SHARED across all copies (deliberately): `~/.loca
|
||||
The kernel (`acp-kernel`) guarantees, and billion-context RELIES on: within a session, a raw content-hash id and a ref number (`mNNNNN`) denote exactly one message forever — **never reused, never duplicated**, even after the message dies (edited/truncated/folded). The model can cite any number it has ever seen (summaries cite tags across turns), so a re-issued number silently misattributes on decompress. Consequences for this repo:
|
||||
|
||||
- Host code must NOT prune/repack `session.state.messageRefs` in ways that let a freed number be re-issued (kernel `assignRefsNode` computes its cursor as `highestUsedIndex(map)+1`, so shrinking the map can drop the cursor and re-issue numbers).
|
||||
- Known residual: `applyCompactionArchive` (#421, `src/session.ts`) prunes `byRaw/byRef` to live raw ids on native-compaction boundaries. In practice the highest-numbered (newest) messages stay resident so the cursor does not drop, but this is a theoretical re-issue window — drop the map-prune once the kernel's ref-space widening (post-#191 direction) makes it unnecessary.
|
||||
- The kernel source lives in `kernel/` (#2092); its version at migration was 0.0.101 — the old registry-pin guards are obsolete (see Kernel Boundary below).
|
||||
- Known residual: `applyCompactionArchive` (#421, `src/session.ts`) prunes `byRaw/byRef` to live raw ids on native-compaction boundaries — in practice the cursor does not drop; drop the prune once the kernel's ref-space widening (post-#191 direction) makes it unnecessary.
|
||||
- The kernel source lives in `kernel/` (#2092) — see Kernel Boundary below.
|
||||
|
||||
## Kernel Boundary (in-repo acp-kernel, #2092)
|
||||
|
||||
The compression kernel lives IN THIS REPO under `kernel/` (migrated verbatim from ranxianglei/acp-kernel @ v0.0.101 on 2026-10-04; the old repo stays frozen until the move has settled). It keeps its own identity — npm name `acp-kernel`, own `version`, own unit suite (`kernel/tests/`), own build chain (tsup → `kernel/dist` + d.ts) — and the host consumes it through `"acp-kernel": "file:./kernel"` exactly like the old registry package (same exports map, same typing, same JS inlined by tsup). The merge exists to end cross-repo maintenance pain WITHOUT making the kernel easy to disturb. Enforced rules:
|
||||
The compression kernel lives IN THIS REPO under `kernel/` (migrated verbatim from ranxianglei/acp-kernel @ v0.0.101 on 2026-10-04; the old repo stays frozen until the move has settled). It keeps its own identity — npm name `acp-kernel`, own `version`, own unit suite (`kernel/tests/`), own build chain — and the host consumes it through `"acp-kernel": "file:./kernel"`. The merge exists to end cross-repo maintenance pain WITHOUT making the kernel easy to disturb. Enforced rules:
|
||||
|
||||
1. **Declare before you touch.** Every PR touching anything under `kernel/**` MUST declare `kernel-change: <reason>` in its body (CI job `kernel-guard` fails otherwise) AND needs owner approval BEFORE implementation, via a dedicated issue stating why the host side cannot solve the problem. Commits use the `kernel:` prefix.
|
||||
2. **Version discipline (CI-enforced).** Any change under `kernel/src/**` (or `kernel/tsup.config.ts` / `kernel/tsconfig.json`) MUST bump `version` in `kernel/package.json`; a bump without such a change also fails. Normal kernel changes ride along with billion-context releases; when enough accumulates, a dedicated kernel release publishes `acp-kernel` standalone (§5, Kernel releases).
|
||||
1. **Declare before you touch.** Every PR touching anything under `kernel/**` MUST declare `kernel-change: <reason>` in its body (CI job `kernel-guard` fails otherwise) AND needs owner approval BEFORE implementation, via a dedicated issue stating why the host side cannot solve the problem. Commits use the `kernel:` prefix. **Mechanical-bug exemption (owner policy 2026-11-06):** an obviously mechanical kernel bug (wrong literal, typo, provably-false guard) may be fixed directly WITHOUT the pre-approval issue, provided the fix adds a reproducing regression test, declares `kernel-change: <reason>`, and posts an in-thread report; the human-only review tier (rule 3) still gates the merge. All other kernel work keeps the full prior-approval flow.
|
||||
2. **Version discipline (CI-enforced).** Any change under `kernel/src/**` (or `kernel/tsup.config.ts` / `kernel/tsconfig.json`) MUST bump `version` in `kernel/package.json`; a bump without such a change also fails.
|
||||
3. **Human-only review, always.** ALL kernel changes sit at the same review tier as `src/update.ts` and security (§7.4): no auto-merge, ever.
|
||||
4. **Behavior constants are golden-pinned.** `tests/golden/wire-contract/kernel.json` pins not just the tool schemas but the behavior surface hosts silently depend on: `defaultConfig(100_000)` (incl. the flat-50K nudge constants), `defaultPrompts` (the four load-bearing prompt rules), tool-name tables, wire markers. Regeneration requires stated justification in the PR; the ledger never shrinks (#1304).
|
||||
5. **Two test layers, both must pass.** The kernel's own unit suite (`npm --prefix kernel test` — runs against TS source) plus the bili suite/e2e as the integration layer. A kernel change is done only when BOTH are green on the rebased head.
|
||||
6. **Structural invariants stay human-gated** (carried over from the kernel's own spec): zero runtime deps (no new dependency without owner sign-off), platform-agnostic core (no host API / file I/O / network), message-id immutability, wire-artifact format, lossless round-trip, protected-tool hard exclusion, canonical pipeline node ordering.
|
||||
4. **Behavior constants are golden-pinned.** `tests/golden/wire-contract/kernel.json` pins the behavior surface hosts silently depend on (`defaultConfig(100_000)` incl. flat-50K nudge constants, `defaultPrompts`, tool-name tables, wire markers). Regeneration requires stated justification in the PR; the ledger never shrinks (#1304).
|
||||
5. **Two test layers, both must pass.** The kernel's own unit suite (`npm --prefix kernel test`) plus the bili suite/e2e as the integration layer — both green on the rebased head.
|
||||
6. **Structural invariants stay human-gated:** zero runtime deps (no new dependency without owner sign-off), platform-agnostic core (no host API / file I/O / network), message-id immutability, wire-artifact format, lossless round-trip, protected-tool hard exclusion, canonical pipeline node ordering.
|
||||
|
||||
## Pi-Subagents Boundary (in-repo pi-lane component, #2384)
|
||||
|
||||
The pi sub-agent surface (`acp_delegate` tools) lives IN THIS REPO under `pi-subagents/` (migrated verbatim from ranxianglei/billion-context-pi-subagents @ master `d19481e` on 2026-10-08, INCLUDING the merged-but-unreleased settle-gate notification fix for #2301; initial in-repo version `0.1.2`; the old repo stays frozen until the move has settled — see `pi-subagents/PROVENANCE.md`). It keeps its own identity — npm name `billion-context-pi-subagents`, own `version`, own unit suite (`pi-subagents/tests/`), own build chain (tsup → `pi-subagents/dist` + d.ts) — and the host consumes it through `"billion-context-pi-subagents": "file:./pi-subagents"` exactly like `kernel/`. Enforced rules:
|
||||
The pi sub-agent surface (`acp_delegate` tools) lives IN THIS REPO under `pi-subagents/` (migrated verbatim from ranxianglei/billion-context-pi-subagents on 2026-10-08; the old repo stays frozen until the move has settled — `pi-subagents/PROVENANCE.md`). Same consumption pattern as `kernel/` (`file:` devDependency, inlined by tsup). Enforced rules:
|
||||
|
||||
1. **Version discipline (CI-enforced).** Any change under `pi-subagents/src/**` (or `pi-subagents/tsup.config.ts` / `pi-subagents/tsconfig.json`) MUST bump `version` in `pi-subagents/package.json`; a bump without such a change also fails (CI job `pi-subagents-guard`). Normal changes ride along with billion-context releases; when enough accumulates, a dedicated release can publish `billion-context-pi-subagents` standalone.
|
||||
2. **Two test layers, both must pass.** The component's own unit suite (`npm --prefix pi-subagents test` — runs against TS source) plus the bili suite/e2e as the integration layer. A component change is done only when BOTH are green on the rebased head.
|
||||
3. **Lighter gating than `kernel/` (deliberate).** No PR-body declaration and no human-only review tier: this is a fast-moving pi-lane extension surface, not load-bearing core compression — the point of #2384 is ending the cross-repo npm round-trip. If that assessment changes, tighten HERE first (add the gate, don't improvise it).
|
||||
4. **Zero-runtime-dep contract preserved.** The component's only runtime host import (`@earendil-works/pi-coding-agent`, namespace-imported by its config-dir module for `CONFIG_DIR_NAME`) stays external and is aliased to `src/agent/pi-host-stub.ts` in the bili bundle (#2186); its `typebox` peer is inlined by the component's OWN tsup build, so no new runtime dependency ever reaches `dist/`.
|
||||
1. **Version discipline (CI-enforced).** Any change under `pi-subagents/src/**` (or its `tsup.config.ts` / `tsconfig.json`) MUST bump `version` in `pi-subagents/package.json`; a bump without such a change also fails (CI job `pi-subagents-guard`).
|
||||
2. **Two test layers, both must pass.** `npm --prefix pi-subagents test` plus the bili suite/e2e — both green on the rebased head.
|
||||
3. **Lighter gating than `kernel/` (deliberate).** No PR-body declaration, no human-only tier: this is a fast-moving pi-lane extension surface, not load-bearing core compression. If that assessment changes, tighten HERE first (add the gate, don't improvise it).
|
||||
4. **Zero-runtime-dep contract preserved.** Its only runtime host import (`@earendil-works/pi-coding-agent`, for `CONFIG_DIR_NAME`) stays external, aliased to `src/agent/pi-host-stub.ts` in the bili bundle (#2186); its `typebox` peer is inlined by the component's OWN tsup build — no new runtime dependency ever reaches `dist/`.
|
||||
|
||||
## 3. Development Standards
|
||||
|
||||
@@ -116,32 +118,31 @@ Test against the REAL published artifact: `npm run build && npm install -g billi
|
||||
|
||||
### E2E Regression (real client through bili)
|
||||
|
||||
The suites below cover the full context lifecycle plus the hermetic billing/advisory lanes — the real-client ones are the only coverage that exercises real client behavior (UA, wire quirks, retry loops):
|
||||
The `tests/e2e/` suites are the only coverage that exercises real client behavior (UA, wire quirks, retry loops):
|
||||
|
||||
- `tests/e2e/e2e-codex.test.ts` — real `codex` CLI through a Responses-compatible upstream (warmup → growth → ACP compress → purity → native-compact). Skips by default behind `ACP_TEST_E2E=1`; **never remove the gate**.
|
||||
- `tests/e2e/e2e-image-billing.test.ts` (`npm run test:e2e:image`) — hermetic real-image billing lane (#1843/#1857): deterministic image corpus driven through the real billing pipeline against a mock upstream; ungated, ~1s, always runs in CI (`.github/workflows/ci-image.yml`).
|
||||
- `tests/e2e/e2e-registry.test.ts` — hermetic local verdaccio exercising the real self-update chain; `tests/e2e/e2e-advisory-rollback.test.ts` shares its gate and fixture infra, asserting the #1588 rollback-form advisory contract end-to-end. Gated by `ACP_TEST_REGISTRY=1`.
|
||||
- Newer hermetic lanes each carry their own skip gate (read the test header for the exact env var): release-canary (`ACP_TEST_CANARY=1`), OpenCode V2 Responses-over-WebSocket (`ACP_TEST_E2E_OC_WS=1`, needs a real OpenCode V2 binary), plus real-client native suites under `tests/e2e/` (dsh/opencode/pi/codex-fake/subagent-sessions).
|
||||
- **Request-pipeline changes** (`src/server.ts`, `src/loop/**`, adapters, preflight/compact paths) → run the codex suite first (at least the 4-phase core, `ACP_TEST_E2E=1`; **never remove the gate**).
|
||||
- **`src/update.ts` / `src/advisory.ts` / `src/plugin-install.ts`** → run the registry suite first (`ACP_TEST_REGISTRY=1`, hermetic verdaccio; the advisory-rollback suite shares its gate).
|
||||
- The hermetic image-billing lane (`npm run test:e2e:image`) is ungated and always runs in CI; newer lanes carry their own skip gate in the test header (canary `ACP_TEST_CANARY=1`, OpenCode V2 WS `ACP_TEST_E2E_OC_WS=1`, …).
|
||||
|
||||
Rules: run the codex suite (at least the 4-phase core) before merging changes to the request pipeline (`src/server.ts`, `src/loop/**`, adapters, preflight/compact paths); run the registry suite before changing `src/update.ts`, `src/advisory.ts`, or `src/plugin-install.ts`. Exact env vars, phases, and the CI trigger file-list: [reference/testing.md](reference/testing.md).
|
||||
Exact env vars, phases, and the CI trigger file-list: [reference/testing.md](reference/testing.md).
|
||||
|
||||
### Gate Test Discipline — Negative Assertions (#3617)
|
||||
|
||||
Every gate (suppression / degradation / fallback / exemption) ships with **both directions** asserted: "triggers when it should" AND "does NOT trigger when it should not." A gate that lands with only the positive case is incomplete by definition — #3401 shipped that way and over-suppressed the dsh compress surface for two releases; #3600's PTC `run_code` shape had no row at all in the decision matrix, so the reachability gate closed the whole surface silently while CI stayed green. Row-driven truth tables (`tests/lane-decisions-matrix.test.ts`) take each new tool-shape/profile as a positive+negative row pair; the decision functions in `src/server/lane-decisions.ts` carry doc comments pointing at their matrix file so an added row is discoverable.
|
||||
Every gate (suppression / degradation / fallback / exemption) ships with **both directions** asserted: "triggers when it should" AND "does NOT trigger when it should not." A gate that lands with only the positive case is incomplete by definition — #3401 shipped that way and over-suppressed the dsh compress surface for two releases; #3600's shape had no row at all in the decision matrix, so the gate closed the whole surface silently while CI stayed green. Row-driven truth tables (`tests/lane-decisions-matrix.test.ts`) take each new tool-shape/profile as a positive+negative row pair; the decision functions in `src/server/lane-decisions.ts` carry doc comments pointing at their matrix file.
|
||||
|
||||
### Configuration Surface Discipline (owner-gated)
|
||||
|
||||
The config surface — every field of `~/.config/billion-context/billion-context.json`, every `BILI_*` env var, every CLI flag, mirrored across CONFIGURATION.md en/zh — is **owner-design territory**. Hard rules:
|
||||
The config surface — every field of `~/.config/billion-context/billion-context.json`, every `BILI_*` env var, every CLI flag, mirrored across docs/configuration.md en/zh — is **owner-design territory**. Hard rules:
|
||||
|
||||
1. **Any change that adds, renames, or re-semantics a config field MUST report it explicitly** in the PR under a "config surface" heading: what is added/changed, why the existing surface cannot express it, which existing mechanisms were considered (providers table + its key species, the three-level `compress` hierarchy, env-var conventions, launcher↔extension channels), and the compat/migration story. A PR touching config without this section is incomplete by definition.
|
||||
2. **Agents do NOT invent new config shapes on their own initiative.** A new section/field proposed merely because locally convenient — without mapping it onto the existing system — is rejected on principle: **don't even build it**. File the proposal (issue, with the mapping above) and wait.
|
||||
3. **The only exception is explicit owner sign-off in the issue/PR thread, given BEFORE implementation**, recorded alongside the design rationale. "The agent thought it was a good idea" is never sufficient reason.
|
||||
|
||||
Canonical cautionary case (#1437 → #1469): a one-off `plugin.nonHttpProviders` section drafted alongside the existing `providers` table collided with the table's design and had to be reworked into `providers[<name>].compactionOptIn`. The first shape should never have existed.
|
||||
Canonical cautionary case (#1437 → #1469): a one-off `plugin.nonHttpProviders` section drafted alongside the existing `providers` table collided with the table's design and had to be reworked into `providers[<name>].compactionOptIn` — the first shape should never have existed.
|
||||
|
||||
### Environment Variable Discipline (#2030)
|
||||
|
||||
Env vars are a **scarce surface**: by default a new behavior knob becomes a config-file key resolved through `src/knobs.ts` (**env > file > default**) — not a new `process.env` read. Env-only is reserved for six categories (secrets, per-process spawn channels, host-side posture, path relocation, third-party conventions); every env var must be documented in CONFIGURATION.md en+zh ("document or don't ship"). Full category table, hard rules, and rationale: [reference/env-vars.md](reference/env-vars.md).
|
||||
Env vars are a **scarce surface**: by default a new behavior knob becomes a config-file key resolved through `src/knobs.ts` (**env > file > default**) — not a new `process.env` read. Env-only is reserved for six categories (secrets, per-process spawn channels, host-side posture, path relocation, third-party conventions); every env var must be documented in docs/configuration.md en+zh ("document or don't ship"). Full category table, hard rules, and rationale: [reference/env-vars.md](reference/env-vars.md).
|
||||
|
||||
### Code Quality
|
||||
|
||||
@@ -150,6 +151,17 @@ Env vars are a **scarce surface**: by default a new behavior knob becomes a conf
|
||||
- Hex escapes required for any ACP-tag XML in source files (see KDD #2)
|
||||
- **No `console.error` in server-side modules** — use `loggerLog(level, msg)` from `src/logger.ts`. Exceptions: `src/cli.ts` (user-facing CLI errors) and `src/index.ts` (pre-logger startup crash).
|
||||
|
||||
### Documentation Layout (owner ruling 2026-11-08, #5920)
|
||||
|
||||
- **One hub.** All design/config/protocol/identity docs live under `docs/`. The repo root keeps only four **core** entry files — `README.md`, `README.zh-CN.md`, `AGENTS.md`, `CHANGELOG.md` (plus temporary redirect stubs per rule 5) — and recognized community-maintained README translations (`README.<locale>.md`, e.g. `README.ja.md`, approved 2026-11-09, #6000); the four core files stay locked. New non-translation docs go in `docs/`, never at the root.
|
||||
- **Naming & language.** kebab-case English base name; bilingual (en + `<same>.zh-CN.md`) is the default (en/zh parity per §7.3). A single-language doc must state why in its `docs/index` entry.
|
||||
- **Index.** Every new or moved doc must be listed in `docs/index.md` AND `docs/index.zh-CN.md` in the same PR.
|
||||
- **Split with `reference/`.** `docs/` = decision/reviewer-facing reference material; `reference/` = AGENTS lazy-loaded construction procedures + the KDD full text ([design-decisions.md](reference/design-decisions.md)). New how-to procedures → `reference/` (+ AGENTS.md pointer); new concepts/decisions → `docs/`.
|
||||
- **Moves/renames.** Leave a one-line redirect stub at the old path and a hygiene-ledger entry in `docs/lifecycle.md` §5 with an explicit removal condition (default: 1–2 releases).
|
||||
- **Runtime doc references** (`package.json` `files`, CI diff paths, guard scripts, user-facing strings) use repo-root-relative paths and must be updated in the same PR as the move; a post-move repo-wide relative-link check must pass clean.
|
||||
- **Diagrams.** Vector SVG is the default artifact and default display (owner ruling 2026-11-07); ship a PNG fallback alongside, referenced second. Diagrams live in the doc's `assets/` directory.
|
||||
- **Architecture docs are LIVE (owner ruling 2026-11-08).** `docs/architecture.md` (+ `.zh-CN`) is the hub: overall diagram + module ledger; each module page lives in `docs/architecture/<module>.md` (+ `.zh-CN`) with its own diagram (svg first, png fallback). Any PR that adds/removes/renames a `src/` module OR changes a depicted data flow, table, lane, or wire path MUST update the affected page(s), diagram(s), hub ledger row, and the `reference/architecture.md` file map in the SAME PR. CI lane `architecture-docs` (`tools/check-architecture-docs.mjs`) enforces the mechanical parts; visual freshness rides on this rule + review.
|
||||
|
||||
## 4. Git Safety Rules (MANDATORY)
|
||||
|
||||
| Rule | Enforcement |
|
||||
@@ -160,11 +172,11 @@ Env vars are a **scarce surface**: by default a new behavior knob becomes a conf
|
||||
| **NEVER print the GitHub PAT** | Token stays in a shell variable only. |
|
||||
| **Branch naming** | `YYYY-MM-DD_short-title`; releases: `*_release-v*` (bili) / `*_release-kernel-v*` (kernel, §5) |
|
||||
| **NEVER modify `version` off release branches** | `"version"` touched ONLY on `*_release-v*` branches. Content commits must NEVER bump it. See Version Bumps below. |
|
||||
| **NEVER cut a release without owner approval** | Release branches (`*_release-v*`, `*_release-kernel-v*`, `bugfix-release/*`) and release PRs are opened ONLY after the owner explicitly approves the release in-thread (「发版 vX」/「批准发布」). An Agent may **propose** a release (what's stranded on master, who's blocked, suggested version) but never pushes the branch or opens the PR itself. If asked, reply: "Releases need your go — approve in-thread and I'll cut the PR." (Owner rule 2026-10-12, #2910) |
|
||||
| **NEVER cut a release without owner approval** | Release branches and release PRs are opened ONLY after the owner explicitly approves the release in-thread (「发版 vX」/「批准发布」). An Agent may **propose** a release but never pushes the branch or opens the PR itself. If asked, reply: "Releases need your go — approve in-thread and I'll cut the PR." (Owner rule 2026-10-12, #2910) |
|
||||
|
||||
**Opening a PR** (no `gh` CLI — push + credential helper + GitHub REST API): the full token/curl recipe is in [reference/git-pr.md](reference/git-pr.md). Summary: `git push origin HEAD`, extract the token from `git credential fill` (shell var only, never print), POST to `/repos/ranxianglei/billion-context/pulls` with base `master`. Merging stays human-only.
|
||||
**Opening a PR** (no `gh` CLI): `git push origin HEAD` → token from `git credential fill` (shell var only, never print) → POST `/repos/ranxianglei/billion-context/pulls` with base `master`. Full token/curl recipe: [reference/git-pr.md](reference/git-pr.md). Merging stays human-only.
|
||||
|
||||
**External contributors' PRs — fix directly, don't replace.** Per the owner rule (小问题直接修, 2026-10-01), fixes are pushed as **additive commits to the contributor's PR branch**, whoever authored the PR — same as any other branch. What stays off-limits is REPLACING the contribution: no rebase-and-replace with an Agent-owned PR, no closing a still-mergeable contribution in favor of a new one (#1765) — the contributor's commits, diff and authorship stay in the merged history. Before assuming it's broken: a deleted head branch does NOT kill an open PR (GitHub freezes `refs/pull/N/head`; check `mergeable`/`mergeStateStatus` first), and `BEHIND` is not a blocker. Mechanics: [reference/git-pr.md](reference/git-pr.md).
|
||||
**External contributors' PRs — fix directly, don't replace.** Fixes go out as **additive commits to the contributor's PR branch**, whoever authored it (owner rule 小问题直接修, 2026-10-01). What stays off-limits is REPLACING the contribution: no rebase-and-replace with an Agent-owned PR, no closing a still-mergeable contribution in favor of a new one (#1765) — the contributor's commits, diff and authorship stay in the merged history. A deleted head branch does NOT kill an open PR (GitHub freezes `refs/pull/N/head`; check `mergeable`/`mergeStateStatus` first), and `BEHIND` is not a blocker. Mechanics: [reference/git-pr.md](reference/git-pr.md).
|
||||
|
||||
**Post-merge supplements** → a small follow-up PR whose body references the original PR number; never append to / rebase the merged PR. Verify a supplement is actually needed first (replaying the same commit on newer master is verification, not content).
|
||||
|
||||
@@ -172,39 +184,18 @@ Env vars are a **scarce surface**: by default a new behavior knob becomes a conf
|
||||
|
||||
One issue = one scope; open a PR, never just push a branch; never bundle unrelated changes or mass whitespace/reformatting into a fix.
|
||||
|
||||
**Version-first triage (先定版本 — owner rule, 2026-10-12, #2847):** before ANY code-level analysis of a bug report, pin the reporter's bili (and, when relevant, kernel) version and read the code AT THAT TAG (`git grep <symbol> v0.1.19X -- src/…`, or check out the tag), not master. If the report doesn't state a version, the FIRST triage reply asks for it (startup log line / `bili --version` / `package.json` / ledger meta). Litmus test: "the mechanism should have caught this but didn't" ⇒ before suspecting a design gap, verify the mechanism even EXISTS in the reporter's build. Origin: #2847 — a full day of triage analyzed symptoms against master while the reporter ran v0.1.192, which lacked `reasoningOnlyDrop`/`turnKeyOf` (both shipped in v0.1.193, #2636 + #2193 follow-up); pure version lag, mis-read as an open design gap. When an Agent works an issue, deliverables are mandatory:
|
||||
**Version-first triage (先定版本 — owner rule, 2026-10-12, #2847):** before ANY code-level analysis of a bug report, pin the reporter's bili (and, when relevant, kernel) version and read the code AT THAT TAG, not master. If the report doesn't state a version, the FIRST triage reply asks for it (startup log line / `bili --version` / `package.json` / ledger meta). Litmus test: "the mechanism should have caught this but didn't" ⇒ before suspecting a design gap, verify the mechanism even EXISTS in the reporter's build. (Origin #2847: a full triage day analyzed master while the reporter ran v0.1.192 — pure version lag mis-read as an open design gap.) When an Agent works an issue, deliverables are mandatory:
|
||||
|
||||
1. **Finished development → PR.** Open a PR referencing the CURRENT issue (`Closes #N`) and reply in-thread with the PR link. An issue is never "done" without a PR.
|
||||
2. **Problems DISCOVERED while working** (bug / data-loss / security / architectural) → report in the current thread AND file a separate new issue (repro, impact, suggested fix) in the project the problem belongs to.
|
||||
3. **Problems FIXED** → leave a trace: an issue recording the problem + how it was fixed; if shipped as a PR, the PR references its issue (`Fixes #N`). A bare PR without an issue is not acceptable — file the issue first, then link it.
|
||||
4. **Minor problems → fix directly(小问题直接修)** (owner rule, 2026-10-01): small issues (typos, cosmetic defects, indentation/log-wording quirks, minor UX wrinkles) found while working — including during a PR review — are fixed RIGHT AWAY in the same branch (a tiny follow-up commit on the PR's own branch is fine), with a one-line note in the thread. Do NOT open separate issues for them, and do NOT leave them as "noted, not fixed". Applies to ANY branch, including external contributors' PR branches.
|
||||
4. **Minor problems → fix directly(小问题直接修)** (owner rule, 2026-10-01): small issues (typos, cosmetic defects, log-wording quirks, minor UX wrinkles) found while working — including during a PR review — are fixed RIGHT AWAY in the same branch, with a one-line note in the thread. Do NOT open separate issues for them, and do NOT leave them as "noted, not fixed". Applies to ANY branch, including external contributors' PR branches.
|
||||
|
||||
Split extra findings into their own issues/PRs rather than expanding this one's scope.
|
||||
|
||||
### Issue 分类与标签规则(triage 必做)
|
||||
|
||||
每个新 issue 在 triage 时打齐三组标签,并在评论或讨论里注明主题类别(A–N)。全量开放 issue 的分类总账与各条目对应的修复 PR、处理建议维护在讨论区置顶:https://github.com/ranxianglei/billion-context/discussions/3913 (更新总账时直接编辑该讨论,不开新帖)。
|
||||
|
||||
**1. 优先级(必选其一)**
|
||||
- `p1`:崩溃、数据丢失、会话永久不可用、核心能力整体停摆(可用性缺陷,参照 §7.3「可用性大于性能」);以及**缓存泄露类**(stale cache 渗漏、cache ref 错误改写、上下文/存储只增不减地失控增长)——owner 修订 2026-10-19:两类一律 p1,不许降 p2
|
||||
- `p2`:功能性缺陷但有绕行,或影响局部;确定性的噪音/成本问题(缓存泄露类除外——那是 p1)
|
||||
- `p3`:轻微缺陷、文档、测试补齐、UX 打磨、低频场景
|
||||
|
||||
**2. 宿主车道(涉及哪个客户端打哪个,跨车道不打)**
|
||||
- `dsh` `pi` `codex` `claude` `opencode` `hermes` `kimi` `trae` `claude-code` `opencodev2` `zcode` 等
|
||||
|
||||
**3. 领域(scope/* 为主;旧中文标签「协议接线/内核/storage」尚未退役,沿用即可,不再新增)**
|
||||
- `scope/kernel`:压缩引擎、折叠判定、摘要、ref/账本(`kernel/` 与 src 侧压缩决策面)
|
||||
- `scope/wiring`:协议接线、请求管道、wire 改写、工具注入、nudge
|
||||
- `scope/storage`:持久化、SQLite 统一存储、会话文件、GC
|
||||
- `scope/ci`:CI、发版流水线、测试基建
|
||||
- `scope/ui`:Web UI / CLI 展示面
|
||||
- `scope/docs`:文档面(README、CONFIGURATION.md、CLIENTS.md、AGENTS.md 等 .md)
|
||||
- `scope/other`:其余
|
||||
|
||||
**4. 状态标签(可选)**:`hold` `review中` `review发现修复中` `review发现小问题` `等待反馈` `下次发版` `解冲突中` 等,只描述当前状态,不描述领域。
|
||||
|
||||
**5. 主题类别(A–N,写进讨论总账,不作为标签)**:A 前缀缓存接缝 / B 折叠预算与资格判定 / C 压缩引擎行为 / D 超时重试与降级 / E 存储层 / F dsh 车道 / G fork 与会话继承 / H pi 车道 / I 其他宿主车道 / J 配置面静默失效 / K 启动器·自更新·CI / L Web UI 与文档 / M 跨车道功能提案 / N 服务端杂项。判定口径以讨论帖各类别开头的一句话定义为准。
|
||||
每个新 issue 在 triage 时打齐三组标签(**优先级 p1/p2/p3 必选其一** · 宿主车道 · 领域 `scope/*`),并在评论或讨论里注明主题类别(A–N)。**p1 = 可用性缺陷 + 缓存泄露类(stale cache 渗漏、cache ref 错误改写、上下文/存储只增不减),owner 修订 2026-10-19 两类一律 p1 不许降 p2**;其余分级口径、全量标签表、A–N 类别定义见 [reference/triage.md](reference/triage.md)。全量开放 issue 的分类总账维护在讨论区置顶:https://github.com/ranxianglei/billion-context/discussions/3913 (更新总账时直接编辑该讨论,不开新帖)。
|
||||
|
||||
### Version Bumps — One Version, One Commit, One Branch
|
||||
|
||||
@@ -217,26 +208,26 @@ Split extra findings into their own issues/PRs rather than expanding this one's
|
||||
|
||||
## 5. Release Workflow
|
||||
|
||||
Releases are fully automated via CI (`.github/workflows/release.yml`): the Agent prepares a release PR; merging it builds, tests, publishes to npm, tags, and creates a GitHub Release. Kernel releases (`acp-kernel`) use the parallel flow in `.github/workflows/release-kernel.yml` (below). There's also a one-click fast path for routine patches. Hard rules (exact steps + internals in [reference/release.md](reference/release.md)):
|
||||
Releases are fully automated via CI (`.github/workflows/release.yml`): the Agent prepares a release PR; merging it builds, tests, publishes to npm, tags, and creates a GitHub Release. Hard rules below; exact steps + internals in [reference/release.md](reference/release.md).
|
||||
|
||||
- **Owner-approved start (owner rule 2026-10-12, #2910):** an Agent runs the release flow (steps 1–6 below) ONLY after the owner explicitly approves the release in the trigger thread (「发版 vX」). Triage that ends at "fix stranded on master, users blocked" PROPOSES the release in the issue thread and stops — what ships and when belongs to the owner. Origin: #2906 → a bot autonomously cut v0.1.196 (#2910) mid-triage; every mechanical rule held (no publish, no merge, branch naming, version-only-on-release-branch) yet the decision to ship was never the bot's to make.
|
||||
- **Owner-approved start (owner rule 2026-10-12, #2910):** an Agent runs the release flow ONLY after the owner explicitly approves the release in the trigger thread (「发版 vX」). Triage that ends at "fix stranded on master, users blocked" PROPOSES the release in the issue thread and stops — what ships and when belongs to the owner. (Origin: #2906 — a bot autonomously cut v0.1.196 (#2910) mid-triage; the decision to ship was never the bot's to make.)
|
||||
- **Branch** `YYYY-MM-DD_release-v{VERSION}`; commit `release v{VERSION}` changing ONLY `version`. The Agent does steps 1–6 (sync master → branch → bump → **sync plugin manifest versions (#4449)** → **release-notes entry if severe (#1870)** → pre-flight typecheck+test+build → commit/push/open PR); HUMAN merges step 7; CI publishes step 8.
|
||||
- **Plugin manifest versions sync on every release (#4449).** The four plugin manifests (`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json`, `plugins/codex/.codex-plugin/plugin.json`) carry their own `version` fields, which the Codex/Claude marketplaces use for UPDATE DETECTION — they must equal `package.json`. After the version-bump commit, run `node scripts/sync-codex-plugin-version.mjs` and commit the result as its own `chore:` commit on the release branch (the one-click lane runs it inside CI automatically). ALL THREE publish workflows (`release.yml`, `release-manual.yml`, `release-bugfix.yml`) run `--check` BEFORE tag/publish: drift = red release, nothing shipped. Consequence: a bugfix carve-out PR head (last tag + fix + bump) MUST also carry the synced manifests or its gate fails.
|
||||
- **Release-notes entry (#1870, OPT-IN since 2026-10-04):** only SEVERE releases need an entry in `release-notes/package.json`; ordinary releases ship with NO entry (the gates log a notice and pass when absent, validate when present). Add a severe entry as its own commit in the SAME release PR; the one-click fast path needs it already merged to master before dispatching. Full rules: [reference/release.md](reference/release.md) + `release-notes/README.md`.
|
||||
- **Bugfix carve-out channel (#2011, PR-gated since #2851):** emergency hotfixes ship as a normal-looking release PR whose head branch keeps the `bugfix-release/v{VERSION}-{slug}` marker (cut from the last released TAG, containing ONLY the fix + version bump); merging it publishes the PRE-MERGE PR-head tree — strictly excluding master's other unreleased work. Pushing such a branch triggers nothing anymore; a manual `workflow_dispatch` on an explicitly chosen ref remains the emergency fallback. Mechanics and constraints: [reference/release.md](reference/release.md). Batch form: label an OPEN fix PR `backport` and a carry PR appears instantly on the current patch lane (`bugfix-v<latest-tag>`, auto-cut from the tag; the lane ships via the one-click release and may never merge that fix into master, 2026-10-24) — see "Dual-lane releases" in the same doc.
|
||||
- **Plugin manifest versions sync on every release (#4449).** The four plugin manifests (`.agents/plugins/marketplace.json`, `.claude-plugin/marketplace.json` + `.claude-plugin/plugin.json`, `plugins/codex/.codex-plugin/plugin.json`) carry `version` fields the Codex/Claude marketplaces use for UPDATE DETECTION — they must equal `package.json`. After the bump commit run `node scripts/sync-codex-plugin-version.mjs` and commit the result as its own `chore:` commit on the release branch. ALL THREE publish workflows run `--check` BEFORE tag/publish: drift = red release, nothing shipped — a bugfix carve-out head MUST also carry the synced manifests.
|
||||
- **Release-notes entry (#1870, OPT-IN):** only SEVERE releases need an entry in `release-notes/package.json`; ordinary releases ship with NO entry (gates pass when absent, validate when present). A severe entry is its own commit in the SAME release PR; the one-click fast path needs it already on master. Full rules: [reference/release.md](reference/release.md) + `release-notes/README.md`.
|
||||
- **Bugfix carve-out channel (#2011, PR-gated since #2851):** emergency hotfixes ship as a release PR whose head branch keeps the `bugfix-release/v{VERSION}-{slug}` marker (cut from the last released TAG, containing ONLY the fix + bump); merging publishes the PRE-MERGE PR-head tree, strictly excluding master's other unreleased work. Batch form: label an OPEN fix PR `backport` → a carry PR appears on the current patch lane. Mechanics and constraints: [reference/release.md](reference/release.md).
|
||||
- **NEVER run `npm publish` manually** — CI does it (§4).
|
||||
- **Kernel releases (separate artifact, #2092).** `acp-kernel` can be published standalone from this repo when accumulated kernel changes warrant it: branch `YYYY-MM-DD_release-kernel-v{VERSION}`, commit `release kernel v{VERSION}` changing ONLY the version in `kernel/package.json`. Merging runs `.github/workflows/release-kernel.yml`: full bili gate + kernel suite, publish `acp-kernel` to npm, tag `kernel-v{VERSION}` (separate tag namespace — bili tags stay bare `v*`), GitHub Release. No release-notes entry required (different artifact; the PR body serves as notes). The two branch patterns are mutually exclusive, so bili's and kernel's release flows never cross-trigger. Downstream consumers of the npm package update as usual — zero notice needed.
|
||||
- **Kernel releases (separate artifact, #2092):** branch `YYYY-MM-DD_release-kernel-v{VERSION}`, commit `release kernel v{VERSION}` changing ONLY `kernel/package.json` version; merging runs `release-kernel.yml` (publish `acp-kernel`, tag `kernel-v{VERSION}` — separate namespace, bili tags stay bare `v*`). No release-notes entry required; the PR body serves as notes. The two branch patterns are mutually exclusive.
|
||||
- **Changing `src/update.ts` (the updater itself) requires a NO-OP validation release FIRST** — a pure version bump proves the *existing* upgrade path is healthy end-to-end before the change ships. A broken updater bricks every future upgrade. Full protocol + rationale: [reference/release.md](reference/release.md).
|
||||
|
||||
## 6. Contributing
|
||||
|
||||
Before changes: (1) `npm run typecheck` clean, (2) `npm test` green, (3) understand the module dependency graph, (4) **consider BOTH compression modes** — any change touching the wire (message rebuild, system/developer handling, tool injection, `acp_summary` stripping, preflight, nudge) must be reasoned in BOTH plugin mode and proxy mode; correct-in-one-mode can break the other (#377 only manifested in proxy mode). See TECHNICAL-NOTES.md "Two compression modes" and the `pluginMode` comment in `src/server.ts`. (5) **Kernel changes follow the Kernel Boundary** — declaration marker, owner approval, version discipline, two-layer tests; the kernel is relatively stable by design, touch it only when necessary. (6) **`pi-subagents/` changes follow the Pi-Subagents Boundary** — version discipline + two-layer tests, lighter gating than `kernel/` (see that section).
|
||||
Before changes: (1) `npm run typecheck` clean, (2) `npm test` green, (3) understand the module dependency graph, (4) **consider BOTH compression modes** — any change touching the wire (message rebuild, system/developer handling, tool injection, `acp_summary` stripping, preflight, nudge) must be reasoned in BOTH plugin mode and proxy mode; correct-in-one-mode can break the other (#377 only manifested in proxy mode). See docs/technical-notes.md "Two compression modes" and the `pluginMode` comment in `src/server.ts`. (5) **Kernel changes follow the Kernel Boundary** — declaration marker, owner approval (mechanical-bug exemption per rule 1), version discipline, two-layer tests; the kernel is relatively stable by design, touch it only when necessary. (6) **`pi-subagents/` changes follow the Pi-Subagents Boundary** — version discipline + two-layer tests, lighter gating than `kernel/` (see that section).
|
||||
|
||||
Commit convention: `feat:` / `fix:` / `refactor:` / `test:` / `docs:` / `release:`.
|
||||
|
||||
## 7. Review & Auto-Merge Discipline
|
||||
|
||||
> Distilled from a full-history review of AI auto-dev across billion-context / billion-context-pi / acp-kernel (#801). Goal: ~90% of bugfixes mergeable without rework, without drifting off direction. Evidence appendix (baseline data, per-issue provenance, second-round analysis): [AUTO-MERGE-GUARDRAILS.md](AUTO-MERGE-GUARDRAILS.md) — the authoritative OPERATIVE rule text stays here in §7.
|
||||
> Distilled from a full-history review of AI auto-dev across billion-context / billion-context-pi / acp-kernel (#801). Goal: ~90% of bugfixes mergeable without rework, without drifting off direction. Evidence appendix (baseline data, per-issue provenance, second-round analysis): [docs/auto-merge-guardrails.md](docs/auto-merge-guardrails.md) — the authoritative OPERATIVE rule text stays here in §7.
|
||||
|
||||
### 7.1 Before You Start
|
||||
|
||||
@@ -247,29 +238,29 @@ Commit convention: `feat:` / `fix:` / `refactor:` / `test:` / `docs:` / `release
|
||||
### 7.2 Review Discipline
|
||||
|
||||
- **Rebase to CURRENT master before claiming mergeable.** Verify against live master, not the PR's original base; after rebase run typecheck + build locally — the FULL-suite verdict comes from remote CI on the pushed head (next bullet). Stale base is the #1 cause of second-round rework (#425 Aug-31 base, #467 43 commits behind, #517).
|
||||
- **Full regression = remote GitHub CI, not a local full-suite run.** The authoritative green/red for the full suite is the GitHub Actions `test` lane on the pushed head (`scripts/run-ci-tests.mjs`, #2816: hermetic runner, pinned concurrency, ubuntu/windows × node 22/24 × 3 balanced shards (#3143)). Workflow: run the TARGETED suites locally for the area you touched (`node --import tsx --test tests/<changed-area>.test.ts`), push the branch / update the PR, then read the check runs. A local `npm test` full run is environment noise, not evidence — live lanes probing firewalled networks, port collisions with a concurrently running bili instance (e.g. claude-native binding 18787, #394), and cross-file interference all produce failures that CI proves green. Never cite a local full-suite result as the merge verdict, and never chase a local full-suite failure before confirming it reproduces on CI (or in that single file run standalone).
|
||||
- **Full regression = remote GitHub CI, not a local full-suite run.** The authoritative green/red is the GitHub Actions `test` lane on the pushed head (`scripts/run-ci-tests.mjs`: hermetic runner, pinned concurrency, ubuntu/windows × node 22/24 × shards). Workflow: TARGETED suites locally for the area touched → push → read the check runs. A local full-suite run is environment noise, not evidence (firewalled networks, port collisions with a running bili, cross-file interference) — never cite it as the merge verdict, and never chase a local failure before confirming it reproduces on CI or in that file run standalone.
|
||||
- **Watch hot-file contention.** `src/server.ts`, the preflight paths, `src/persist.ts`, and the `src/agent/*` extension types are rewritten by many concurrent PRs — expect semantic (not textual) conflicts; coordinate/sequence, resolve by union of intent, then prove by running tests (#517↔#587, #571↔#558).
|
||||
- **One linear commit, clean diff.** No diff-exploding rebases, no incidental whitespace re-alignment; every line relates to the PR's purpose (#571 "diff-爆炸", #467).
|
||||
- **Minor flaws found during review get fixed, not filed.** Per the owner rule "小问题直接修" (§4 Issue & Problem Tracking): when your own review of a PR turns up a small, non-semantic flaw (typo, misaligned indent, log wording), push the one-line fix to the PR branch immediately instead of listing it as a caveat — on ANY PR branch, external contributors included.
|
||||
- **Done = evidence, not "should work".** Double-review, then RUN the changed behavior and observe it matches expectation; for context/wire fixes prefer a real e2e A/B against the issue repro over unit tests alone (#254).
|
||||
- **Tests must be deterministic.** No environmental luck (e.g. assuming a port range is free — Windows' ephemeral range 49152–65535 collides with fixed picks; request a port via `listen(0)` instead, #360).
|
||||
- **AI-posted comments self-declare their model.** Any comment, reply, or review an Agent posts on GitHub (issue threads, PR reviews, review replies) opens its body with a model self-declaration on the FIRST line — `(ai: <provider>/<model-id>)` — before any content. Provenance for the reader: which model produced an analysis is part of its weight, and a silent mix of models in one thread is unauditable. Applies to posted text only (comments/replies/review bodies), not to PR descriptions of code changes the PR itself shows.
|
||||
- **One linear commit, clean diff.** No diff-exploding rebases, no incidental whitespace re-alignment; every line relates to the PR's purpose (#571, #467).
|
||||
- **Minor flaws found during review get fixed, not filed** (小问题直接修, §4): a small non-semantic flaw (typo, misaligned indent, log wording) becomes a one-line fix pushed to the PR branch immediately — on ANY PR branch, external contributors included.
|
||||
- **Done = evidence, not "should work".** Double-review, then RUN the changed behavior and observe it; for context/wire fixes prefer a real e2e A/B against the issue repro over unit tests alone (#254).
|
||||
- **Tests must be deterministic.** No environmental luck (assume no port range is free — Windows' ephemeral range 49152–65535 collides with fixed picks; request a port via `listen(0)` instead, #360).
|
||||
- **AI-posted comments self-declare their model.** Any comment/reply/review an Agent posts on GitHub opens with `(ai: <provider>/<model-id>)` on the first line — provenance for the reader; a silent mix of models in one thread is unauditable. Applies to posted text only, not PR descriptions.
|
||||
|
||||
### 7.3 Correctness Guardrails
|
||||
|
||||
- **Availability over performance (可用性永远大于性能 — owner rule, 2026-10-14, #3128).** When a defect makes a capability UNAVAILABLE, restoring availability outranks every other consideration — performance, memory footprint, elegance. Do not block or defer an availability fix on performance grounds: ship the availability fix and track the performance cost as SEPARATE work (it may already be in flight). Canonical case #3128: raising the hardcoded 100 MiB HTTP request-body cap to a 5 GiB default so multi-gigabyte single requests are accepted instead of reset is an AVAILABILITY decision; the in-RAM buffering cost of large single bodies is a distinct performance concern owned by separate streaming/spill work, not a reason to hold the cap.
|
||||
- **Root cause, not symptom (疏, not 堵 — first principle for every fix).** A fix removes the mechanism that PRODUCES the defect; it never merely hides the defect's visible trace at whatever layer is cheapest to intercept. Before writing any fix, name the producer of the offending bytes/behavior and fix it at the source or decision point — never by rewriting or filtering payload in transit to make the symptom invisible. Litmus test: "if the same root cause surfaced in a different shape tomorrow, would this fix still hold?" If not, it is a mask, and a mask is a latent bug. Canonical failure: #933 (model-echoed render tags leaking into a TUI) was "fixed" by stripping tool-call arguments mid-stream; the mask itself became #1039's silent data corruption once users legitimately wrote tag-shaped payloads through write/edit/bash. When the true root cause is out of scope (another repo, a product decision), fix the in-scope part, leave a documented boundary note pointing at the real home of the fix, and do NOT compensate in the wrong layer (#1039's echo-noise belongs on the injection side — host renderTags policy — not on the wire).
|
||||
- **Availability over performance (可用性永远大于性能 — owner rule, 2026-10-14, #3128).** When a defect makes a capability UNAVAILABLE, restoring availability outranks everything — performance, memory, elegance. Ship the availability fix; track the performance cost as SEPARATE work. (Canonical case #3128: raising the 100 MiB body cap to 5 GiB is an availability decision; the in-RAM cost is separate streaming/spill work.)
|
||||
- **Root cause, not symptom (疏, not 堵 — first principle for every fix).** A fix removes the mechanism that PRODUCES the defect; it never merely hides the defect's visible trace at whatever layer is cheapest to intercept. Name the producer of the offending bytes/behavior and fix it at the source or decision point — never by filtering payload in transit. Litmus test: "if the same root cause surfaced in a different shape tomorrow, would this fix still hold?" If not, it is a mask, and a mask is a latent bug. (Canonical failure #933→#1039: model-echoed tags were "fixed" by stripping tool-call arguments mid-stream; the mask itself became silent data corruption once users legitimately wrote tag-shaped payloads. When the true root cause is out of scope, fix the in-scope part, leave a boundary note, and do NOT compensate in the wrong layer.)
|
||||
- **Never silently clobber or drop user config.** Any read-modify-write on user config needs a parse-state guard; reject malformed input loudly (HTTP 400/409) instead of merging into defaults or dropping fields. Whitelists must be complete (#155: a missing key silently erased custom compress prompts).
|
||||
- **Sane defaults & fallbacks.** Fallback values must be reasonable (never a too-small value that thrashes); a static/fallback source must always lose to a fresher authoritative source when both are cheaply available (#282: window fallback 200K/min 100K, not 64K; the bundled registry snapshot must not outrank the live registry).
|
||||
- **Prefer native stable identifiers.** Use a client's native stable session id when available (survives credential/model/provider switches); report clients that expose none; never build identity from derived hashes that drift on switch (#280). With the snapshot-render lane on (#3756), the session id + server transcript IS the outbound message identity — see Key Design Decisions 13 and MESSAGE-IDENTITY.md.
|
||||
- **Prefer native stable identifiers.** Use a client's native stable session id when available (survives credential/model/provider switches); report clients that expose none; never build identity from derived hashes that drift on switch (#280). With snapshot-render (#3756) on, the session id + server transcript IS the outbound message identity — KDD #13 and docs/message-identity.md.
|
||||
- **Wire fidelity (host-side duty).** Never alter upstream protocol shape beyond intended injection: preserve tool_call ids/ordering, SSE structure, and upstream invariants (e.g. `compaction_trigger` must remain the last input item, #283/#209). Reason in BOTH compression modes (§6).
|
||||
- *Tool-call arguments are user intent (#1039).* Any payload a host will EXECUTE or PERSIST — tool-call `arguments` in every wire shape (OpenAI `tool_calls[].function.arguments`, Anthropic `input_json_delta.partial_json` / `tool_use.input`, Responses `function_call_arguments.*`), fragment or whole — is forwarded **byte-exact**. NEVER filter, strip, or "clean" it, not even to remove model-echoed render tags: a shape-based filter cannot distinguish an echo from a literal the user genuinely wants written (bash command strings, write/edit file contents), so any such "fix" silently corrupts executed/persisted data. Echoed tags surfacing in a host TUI is cosmetic noise — the fix belongs on the injection side (host renderTags policy, #933), never in the argument path. Tag-echo stripping applies to model PROSE only (content/reasoning/thinking/summary text fields); see the invariant block atop `src/loop/tag-echo-filter.ts`.
|
||||
- *Kernel-owned split:* the FORMAT CONTRACT of the kernel-emitted ACP artifacts (the compression tags, block refs, `acp_summary` structure — KDD #2) and the **id-never-reused guarantee** belong to **acp-kernel**, not this repo (§2 Kernel Contract). This repo only consumes them faithfully. Codifying the kernel-side spec is a change under `kernel/` — human-gated per the Kernel Boundary.
|
||||
- *Tool-call arguments are user intent (#1039).* Any payload a host will EXECUTE or PERSIST — tool-call `arguments` in every wire shape — is forwarded **byte-exact**. NEVER filter, strip, or "clean" it, not even to remove model-echoed render tags: a shape-based filter cannot distinguish an echo from a literal the user genuinely wants written. Echoed tags surfacing in a host TUI is cosmetic noise — the fix belongs on the injection side (host renderTags policy, #933), never in the argument path. Tag-echo stripping applies to model PROSE only (see the invariant block atop `src/loop/tag-echo-filter.ts`).
|
||||
- *Kernel-owned split:* the FORMAT CONTRACT of the kernel-emitted ACP artifacts (KDD #2) and the **id-never-reused guarantee** belong to **acp-kernel**, not this repo (§2 Kernel Contract). This repo consumes them faithfully. Codifying the kernel-side spec is a change under `kernel/` — human-gated per the Kernel Boundary.
|
||||
- **Symptom ≠ mechanism.** Before attributing a bug to bili's mechanism, verify against upstream logs — repeated-compression logs may be an upstream rate-limit retry illusion, not over-compression (#282).
|
||||
- **Wire-constraint ledger only grows (#1304).** Every upstream rejection or validation constraint discovered in production or provider docs (e.g. #1299: Anthropic rejects top-level `oneOf`/`allOf`/`anyOf` in `tools[].input_schema`) becomes a PERMANENT entry in the wire-contract suite — the ledger (`WIRE_RULES`, defined in `tests/wire-contract-fakes.ts`) plus the gates in `tests/wire-contract.test.ts` (with provenance citing where the constraint was learned) plus enforcement in the matching validation-parity fake upstream (`tests/wire-contract-fakes.ts`) — INSIDE THE FIXING PR. The ledger never shrinks without owner sign-off. Golden schema snapshots (`tests/golden/wire-contract/*.json`) change only via explicit regeneration (`node --import tsx scripts/update-wire-contract-goldens.ts`) with the justification stated in the PR. A pin bump or tool-surface change that trips a gate is a stop-the-line signal, not something to loosen.
|
||||
- **Wire-constraint ledger only grows (#1304).** Every upstream rejection or validation constraint discovered in production or provider docs (e.g. #1299: Anthropic rejects top-level `oneOf`/`allOf`/`anyOf` in `tools[].input_schema`) becomes a PERMANENT entry in the wire-contract suite — the ledger (`WIRE_RULES` in `tests/wire-contract-fakes.ts`) + gates in `tests/wire-contract.test.ts` (provenance cited) + enforcement in the matching fake upstream — INSIDE THE FIXING PR. The ledger never shrinks without owner sign-off. Golden schema snapshots (`tests/golden/wire-contract/*.json`) change only via explicit regeneration (`scripts/update-wire-contract-goldens.ts`) with stated justification; a pin bump or tool-surface change tripping a gate is stop-the-line, not something to loosen.
|
||||
- **Honest output.** Never emit misleading messages for degenerate states (#155: export claimed "original conversation" for a 0-block session).
|
||||
- **Logs.** Mask secret values in all logs; separate trace/debug/info; keep debug-on by default during bug-convergence phases (#247).
|
||||
- **Docs.** Keep zh/en in sync; place content where the actual reader will see it; mirror env-var references into CONFIGURATION.md, not just one README (#571).
|
||||
- **Docs.** Keep zh/en in sync; place content where the actual reader will see it; mirror env-var references into docs/configuration.md, not just one README (#571).
|
||||
|
||||
### 7.4 Auto-Merge Gate (this repo only)
|
||||
|
||||
|
||||
@@ -1,90 +1 @@
|
||||
# 自动合并护栏(Auto-Merge Guardrails)— 证据附录
|
||||
|
||||
> **来源**:[#801](https://github.com/ranxianglei/billion-context/issues/801)「自动合并材料收集」。
|
||||
> **方法**:拉取三个仓库(billion-context / billion-context-pi / acp-kernel)**全部 issue + PR + 评论**(共 1543 项、1072 个 PR、3645 条评论),叠加本仓 `devlog/` 31 条迭代记录、`AGENTS.md` 完整 git 演进史、commit 类型分布,交叉比对得出。
|
||||
> **目标**:让 ~90% 的 bugfix 可自动合并,同时守住大方向不偏移。
|
||||
> **定位(重要)**:规则的**权威文本在 [`AGENTS.md` §7](./AGENTS.md#7-review--auto-merge-discipline) Review & Auto-Merge Discipline**(每次会话自动加载,是唯一操作依据)。本文件只做**证据附录**——保留基线数据、逐条 issue/PR 出处、重灾区数据分析、以及内核 vs 本仓库的归属判断。**凡是规则 / Gate / Checklist 的操作文本,一律以 §7 为准,本文不复述**,避免两处漂移。范围限定:**本次仅改本仓库**,跨仓库改动暂留人工。
|
||||
|
||||
---
|
||||
|
||||
## 1. 基线事实(数据说话)
|
||||
|
||||
| 事实 | 数据 | 含义 |
|
||||
|------|------|------|
|
||||
| fix 是主战场 | 非合并 commit:`fix:` 360 / `feat:` 117 / `docs:` 99 / `test:` 41 / `refactor:` 24 | bugfix 约占 54%,正是自动合并要覆盖的对象 |
|
||||
| 没有"被拒绝"的 PR | 三仓 closed-unmerged **全为 0** | 人工要么合并、要么挂着,从不直接否决。风险不在"AI 的东西被否",而在**剩下 ~10% 需返工的会卡住整条流水线** |
|
||||
| 规则是事后补的 | `AGENTS.md` 每条硬规则几乎都对应一次事故(#377 两种压缩模式、#584 问题必建 issue、version 仅 release 分支、auto-update 改动先发 no-op 版) | 现有 `AGENTS.md` ≈ 已踩坑沉淀;隐性规则现在已并入 §7 |
|
||||
| AI 工作难从作者区分 | 仅 55 个 PR 带 `ework-agent-pr` 标记;多数早期工作以 ranxianglei PAT 直推 | 判断"AI vs 人工"要靠 `[bot] 🏷` 前缀 + 标记,不能靠 authorship |
|
||||
|
||||
---
|
||||
|
||||
## 2. 人工确立的规则(每条的真实出处)
|
||||
|
||||
> 规则文本本身见 `AGENTS.md` §7.1–§7.3;这里只给**为什么有这条**的证据。
|
||||
|
||||
### A. 早已成文(继续守住)
|
||||
git 安全四禁(禁 force-push master / 禁 merge / 禁 npm publish / 禁打印 PAT)、branch 命名 `YYYY-MM-DD_short-title`、version 仅 `*_release-v*` 分支、发布流程 + no-op 校验、acp-kernel 先于本项目发布、issue 先行 + 问题必报、代码质量(no `as any` / hex escape `\x3c\x3e` / loggerLog)、改请求管线前跑 e2e、两种压缩模式都要想。
|
||||
|
||||
### B. 隐性规则(现已并入 §7)——逐条出处
|
||||
1. **先查重再动手** —— *出处*:#268「这个应该已经存在了一个 pr 修复这个问题 检查下重复」;pi #311/#314 同标题重复 PR。
|
||||
2. **rebase 到最新 master 再验证再提** —— 警惕 **rebase 顺序依赖**。*出处*:#249/#221/#155/#479 反复要求基于最新 master 重验。**#479 最典型**:AI 漏了顺序依赖——测试写死 `savedAt=9000/5000/8000`(1970),因另一 PR(#487)先落 master 而失效,人工独立复审才抓到。
|
||||
3. **收敛范围,一 issue 一主题** —— *出处*:#247「先收敛 你先只负责本 issue…额外问题我找其他 agents 去做」;#640 兄弟 issue 批一个 PR、关掉被取代的。
|
||||
4. **交 PR,不是光推分支** —— *出处*:#282「提交 pr 而不是分支」。
|
||||
5. **绝不静默丢/覆盖用户配置** —— *出处*:#155 白名单漏 prompts 键 → web 保存会静默抹掉自定义压缩提示词,改为 malformed 直接 400;`devlog/context-window-fixes`(读失败还往 `{}` 合并 = 静默丢数据)。
|
||||
6. **兜底值要合理** —— *出处*:#282「识别失败默认回 20w、最低 10w,别用 64k」;`devlog/context-window-fixes`(静态表压过活注册表 = freshness 层级倒挂)。
|
||||
7. **优先用客户端原生稳定标识** —— *出处*:#280「session-id 才是唯一不变、绑定当前会话的…不能拿到的客户端你报告一下」。
|
||||
8. **分清症状与机制** —— *出处*:#282「连续压缩」实为上游 429 限流 + 客户端重试刷出的日志假象,并非压缩机制失控。
|
||||
9. **输出要诚实** —— *出处*:#155 export 对 0-block 会话打出"下面是原始对话"的文案,要求改成诚实提示。
|
||||
10. **完成 = 证据** —— *出处*:#784「review 了吗」;#247「本地双 review 然后实际测试切换 观察是否符合预期」。
|
||||
11. **日志:凭证必脱敏 + 分级** —— *出处*:#247(B.1 hdrLog 脱敏、B.3 分级)。
|
||||
12. **文档中英同步 + 位置可见** —— *出处*:#698 QQ 群号三项目中英文都加、且别放最后没人看见。
|
||||
13. **跨仓顺序** —— *出处*:#772「先发一个内核版本,再发这个版本」「内核已经合并」。
|
||||
|
||||
---
|
||||
|
||||
## 3. AI 把握不到的点(审核员重点把关,按出现频率排)
|
||||
|
||||
| # | 类别 | 典型表现 | 为什么 AI 容易漏 |
|
||||
|---|------|----------|------------------|
|
||||
| 1 | **交叉/交互效应**(最高危) | rebase 顺序依赖、并发 PR 相互影响、切模型/切 provider 后状态漂移 | AI 偏局部推理,看不到全局时序与并发 |
|
||||
| 2 | **静默数据丢失路径** | read-modify-write、配置覆盖、持久化版本迁移 | 正常路径测得通,异常/边界路径才丢数据 |
|
||||
| 3 | **协议/线上保真** | tool_call 的 id/顺序、SSE 结构、compaction_trigger 必须是最后一个 input item(#283) | 改了线格式但本地 mock 上游不严格,CI 也测不出 |
|
||||
| 4 | **标识与会话稳定性** | 派生 id vs 原生 id、sticky 会话、中途切换 | 单一场景下派生 id 够用,切换场景才暴露 |
|
||||
| 5 | **默认值/兜底判断** | 不合理 fallback、真值来源优先级 | 属产品判断,AI 易拍脑袋选个"看起来对"的值 |
|
||||
| 6 | **症状 ≠ 根因** | 日志假象、错误归因 | 表象像 A,其实是 B(见 #282) |
|
||||
| 7 | **流程卫生** | 范围蔓延、重复劳动、只推分支不开 PR、跨仓顺序 | 单看每个动作都对,组合起来违反流程 |
|
||||
| 8 | **面向用户的判断** | 文档措辞/语言/位置、诚实性、UX 默认值 | 工程正确 ≠ 用户视角正确 |
|
||||
|
||||
### 3.1 重灾区:二次评论才过的 PR(数据)
|
||||
|
||||
对 455 个已合并 PR 统计"人工评论次数":**229 个 0 次、71 个 1 次、26 个 ≥2 次**——即约 **7%(26/326 有评论者)需要第二轮及以上人工 review 才过**。这些就是"重灾区";其中属 **bugfix**(非 feat)的,才是自动合并真正要防的对象:
|
||||
|
||||
| PR | 主题 | 二次返工原因 |
|
||||
|----|------|--------------|
|
||||
| #571 | hold client through long preflight | diff-爆炸(#575 同病)、反复 rebase 冲突(#558/#593)、文档放错节 + env 变量只写英文 README、漏 zh/CONFIGURATION.md |
|
||||
| #467 | hard backstop plugin-mode overflow | base 落后 43 commits;逐行空格 artifact(1280 off-by-one-space)被挑出 |
|
||||
| #517 | reject stale snapshots rollback | 与 #587 重写 `src/persist.ts` 同文件冲突,需语义 rebase |
|
||||
| #425 | uncompressed baseline + clamp negative | base 停在 8/31;上条评论承诺的 openai 拆分口径没做完 |
|
||||
| #219 | stale context limits + registry-first | 首修漏了"代理网络下 Node fetch 忽略 http(s)_proxy → registry 拉取永久失效";快照从投影扩成全量 |
|
||||
| #428 | re-voice acp_summary as user | 要求确认回归;方案被推翻、移到原 issue |
|
||||
| #360 | /acp panel persistent message | 反复冲突;"为啥新搞一个 acp panel?"(方案质疑);Windows 临时端口范围致 flaky 测试(改 `listen(0)`) |
|
||||
| #254 | preflight-compress on model switch | 需真实 A/B 复现验证(非仅单测) |
|
||||
| #657 | recover stale shim conversation id | review 才发现残留小问题 |
|
||||
|
||||
**两个主导成因**(操作版见 `AGENTS.md` §7.5):
|
||||
1. **stale-base / 并发文件踩踏**:长命分支偏离快速演进的 master,或与别的 PR 抢同一热文件(`server.ts` / preflight / `persist.ts` / `agent/*` 类型)。信号:分支新鲜度 + 是否与其它 open PR 改同一文件。
|
||||
2. **首遍不完整**:只治了报出来的症状,漏了相邻路径/边界、或承诺了却没做完、或方案要重来。信号:修复是否覆盖该 bug 的**所有**路径,而不只是 repro。
|
||||
|
||||
---
|
||||
|
||||
## 附:owner 拍板结论 + 内核 vs 本仓库归属判断
|
||||
|
||||
**已定**:
|
||||
1. ✅ 规则与门槛并入 `AGENTS.md` 新增 **§7 Review & Auto-Merge Discipline**(唯一操作文本)。
|
||||
2. ✅ 范围限定:**跨仓库改动暂留人工**——自动合并门槛只作用于本仓库;acp-kernel bump / 任何跨仓改动一律人工处理。
|
||||
3. 「可自动合并」这套先作为 **reviewer 清单 + AGENTS.md 门槛**;是否再升级为 CI 硬门禁(gate)留待后续单独评估(涉及 CI 改动,属另一件事)。届时以 §7.4 为准。
|
||||
|
||||
**内核 vs 本仓库归属判断**(owner 指出"还有一条落下了,需判断优先沉淀到内核还是本仓库"):
|
||||
- 有真正归属歧义的是 **wire / 内核产物保真** 这一条。判定:**格式契约 + id 永不复用保证归 acp-kernel**(它产出并拥有 ACP 压缩标签、block ref、`acp_summary` 结构、ref 空间);**本仓库只保留 host 侧义务**(忠实消费:不重生成 tool_call id/顺序、不裁剪 ref map、两种压缩模式都要想)。
|
||||
- 依据:`AGENTS.md` §2「Kernel Contract」早已把 id-never-reused 记为内核契约的 host 视角;§7.3 的 wire-fidelity 项已明确标注此 split。
|
||||
- 处置:内核侧的正式 spec **已在 acp-kernel 单独 PR 落地**([acp-kernel#303](https://github.com/ranxianglei/acp-kernel/pull/303),把 ref-id 不可复用 + wire-artifact 格式契约提升为一等不变量);billion-context-pi 对应 PR 为 [pi#457](https://github.com/ranxianglei/billion-context-pi/pull/457)。
|
||||
> Moved to [docs/auto-merge-guardrails.md](docs/auto-merge-guardrails.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -5,7 +5,84 @@ Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed
|
||||
- **AGENTS.md 瘦身(owner 指令 2026-11-08):76 KB → 50.6 KB(−34%),规则零丢失,编号不变**。KDD 分两级:Tier A(#2/#4/#6/#7/#8/#10,每会话操作规则)留 AGENTS.md 全文;Tier B(#1/#3/#5/#9/#11–#18)全文逐字搬入新文件 `reference/design-decisions.md`(append-only 台账,**KDD 编号 = 稳定公共 API,原样保留**),AGENTS.md 每条留 1–3 行操作性后果 + 指针。Issue 分类与标签规则整节搬入 `reference/triage.md`(p1 口径与总账讨论链接留在正文)。E2E/Release 细则收敛为指向既有 `reference/testing.md` / `reference/release.md` 的硬规则。被反向引用的 heading 锚点(`#4-git-safety-rules-mandatory` 等 6 处)文本原样不动。
|
||||
- **系统架构文档体系落地(owner 指令 2026-11-08):`docs/architecture/` 成为实时维护的架构枢纽**:新增 `docs/architecture.md` / `docs/architecture.zh-CN.md` 总枢纽(整体架构图中英双版转正 + 8 模块总表),首个样板模块页 `docs/architecture/storage.{md,zh-CN.md}`(统一存储:职责/原理/工作机制/硬不变量,配模块图中英双版)。文件级地图 `reference/architecture.md` 补齐 125 个缺失条目(新存储层 / marker / fastpath / lanes 等全部新模块)并升级为 CI 强制全量覆盖。新增 CI 车道 `architecture-docs`(`tools/check-architecture-docs.mjs`):地图覆盖全 `src/` 文件、总表↔页面成对、图 svg 优先 + png 备选齐备、SVG 基础良构(未转义 `&` 曾让英文图线上破图)。AGENTS.md「Documentation Layout」新增实时维护规则:改结构 ⇒ 同 PR 更新页 + 图 + 总表。其余 7 个模块页(pipeline / lanes / kernel / identity / fastpaths / webui / update)同一 PR 全部补齐——总表 8 行全 ✅(每页 = 中英双版文档 + 中英双版图)。
|
||||
|
||||
### Fixed
|
||||
- **会话历史的「条数」维度与超大未压缩请求:按真实维度拦下,判死信息点名超重字段(#5000 #5794 #5885)**:#5000 的 26,903 条消息会话(55.2MiB)穿过了**所有**字节/token 闸门、在上游死于消息条数上限——因为条数这个维度从来没有任何闸(它无法被任何字节/token 估算表达:每条消息还各带 ~69B 的 m-ref 标记,26,903 条 ≈ 1.8MB 纯标记)。现在新增按上游配置的**条数闸**(`network.maxMessages` / `BILI_MAX_MESSAGES`,默认 0=关闭——不存在全局「通用上限」,条数上限因上游而异):超限直接 413,信息点名 COUNT 维度并给出可执行指引(重启会话或回退到更早的时点;折叠在一轮 preflight 内关不掉 ~20K 条的缺口,所以是纯判死、不做条数折叠),且在 token 触发器**之前**运行——token 达标但条数超标的体(正是 #5000 的形状)也只有这道闸看得见。同时所有超窗判死信息(#5932 的三道计量闸)现在**点名超重的是哪个字段**——按 #554 计量器同源分桶(messages / tools[] / system / other),不再只给一个总数:#5000 的形状会显示 `tools[] ~X`,巨大粘贴/工具结果会显示 `messages ~X`,运维一眼知道该删什么。另新增 **32MiB 解码摄入成本带**(`network.ingestBodyBytes` / `BILI_INGEST_BODY_BYTES`):#5794 的 51.2MiB/29,619 条请求每轮独占事件循环 5.5–7.2s(本机 CPU 54.6% → 747s FATAL 自重启、全员缓存冷),成本带在 JSON 解析扫掠**之前**按解码后字节 413(stage=ingest)——任何可解析的**文本为主**的 32MiB+ 体都已是 ≥~8M token,超出所有真实模型窗口,放行必然烧钱再死。带图片的体在所有车道豁免(base64 像素按设计不进 token 计量——#496/#1800/#857「图片单独计费、绝不在原始字节上判死」;#3909 的 ~48MiB 图片密集 chat 会话与 #3701 的 ~38.5MiB WS 截图体都是受支持工作负载,由槽位预算/收件上限/车道自身的预发送字节预算+丢弃逻辑治理;Responses 车道无论如何整体豁免);并发槽位预算与 5GiB 收件上限继续独立生效。回归:tests/issue5000-count-gate(3 e2e:token 达标+条数超标→413 零上游 / 无 model 路径 / 条数达标照常转发)、tests/issue5794-ingest-cap(3 e2e:超带文本→413 stage ingest / 带内照常 / 超带带图不拦)、tests/side-request-isolation 分桶计量单测;既有 332 用例(含 #3701/#857/#496/#4079/#4185/#2490 全部回归面)全绿。
|
||||
- **The log/publish secret scrubber now catches JSON-quoted credentials and Groq/Hugging Face keys.** `redactSecretsInText` (every log line, and via `redactForPublish` the diagnostics blob that lands in public GitHub issues) required `:`/`=` right after the key name, so the JSON/dict shape upstream error bodies and config dumps use — `"api_key": "…"`, `"password": "…"`, `'access_token': '…'` — slipped through unless the value happened to start with a known prefix such as `sk-`. An optional quote after the key name now matches it; `gsk_…` (Groq) and `hf_…` (Hugging Face) keys, both on the public-host list, are masked like `sk-…`. Usage-count keys (`"prompt_tokens"`, `"tokens"`, `"max_tokens"`) stay verbatim. Regression: `tests/log-mask.test.ts`.
|
||||
- **超窗请求不再裸发上游:三道转发闸按「真实出站体」计量(#5000 #4543 #5885),未压缩大请求纳入 32MiB 成本带准入(#5794)**:旧判据只量「消息核心文本的字节」,看不见 system/tools/tool_calls 参数——#5000 的 55.2MiB 体(84 个工具)与 #4543 的 4.1MiB CJK 体(1,121,674 tok vs 1M 窗口)都能让全部闸门沉默,然后「转发一次取证」把必然 400 的体真发出去烧钱。现在三个「转发仲裁点」(压缩后再检、#1839 仲裁臂、出站熔断)改按出站体的**逐字符 token 计量**(system+tools+arguments+messages,CJK 感知,#554 侧车道同源尺子)对照**真实模型窗口**本地 413,不再裸发;取证探针闸保持 #2490 字节契约不动(那里的一次 400 是设计内的证据回路,见 #2313/#1001);图片体不进判死——计量器补排 responses 车道的 `image_url` 键(此前把截图 base64 当文本量,40MB 截图体被量成 ~10M token,误杀 #3701 的 WS shed 重发与 #857 的图片计费仲裁转发),判死只比文本量,图片单独超窗仍走 #496/#1800 上游计费仲裁。另:成本准入旧阈值 = 5GiB 收件上限,2 槽位预算形同虚设,#5794 的 51.2MiB/轮未压缩请求(每轮独占事件循环 5.5–7.2s、占本机 CPU 54.6% → 747s FATAL 自重启)从此被拦;未压缩体现在按 32MiB 成本带准入(运维显式调低收件上限仍逐字节生效)。tests:issue4079/issue4185/request-body-budget 新增实测档 e2e 与 32MiB 顺序用例;既有 89+67 用例全绿,#857/#3701/#496/图片与计量相关 173 用例回归全绿。#5885 的 modelContextLimit 被忽略属独立缺陷,另行跟进。
|
||||
- **dsh 闸门:必然被上游拒绝的超窗请求不再裸发直连(#5613 安全网 ①②③)**:`none`/`threw` 归属车道(如经网关的 ds-harness-remote)上的超窗历史请求,旧行为二选一——要么按乐观的 bytes/4 估算判「不超窗」而直接裸发上游(实测计费偏差≈×1.14,估算系统性偏低;真实现场把 max_tokens 挤到 1、乃至上游 400 后整会话报废),要么即便超窗也没有任何持续留痕(只记第一行之后全静默)。现在双档计价:原有 bytes/4 下限继续标记「必然超窗」,另加 ×1.14 校准估算档(会话 ledger 实测偏差,常数 `CALIBRATED_TEXT_TOKEN_RATIO`,src/util.ts),过线即本地 422 拒绝而不是骑 #1117 去赌上游——小体量的合法直通语义(sidecar 短调用等)逐字节保留,未知尺寸流式体保持 fail-open。每次裸发 DIRECT 现在都带体积(`this body N B`)或「尺寸未知、超窗熔断未跑」明示,按 首次/状态变化/每第10次 落 durable 日志(bili.log,[dsh-client] 通道)——连续泄漏环路从此必有痕。tests/dsh-native.test.ts:#2924/#4068 双臂升级为双档断言+校准边界钉(3,508,768 B 直通 / 3,508,772 B 拒)、新增留痕节拍回归、#4111/#4912 谓词改名对齐。
|
||||
- **全量压缩与 persona 文本漂移同轮发生时,主会话不再分叉到 `|sub:` 副车道(#5719)**:dsh 全量压缩 checkpoint(#3733 authored checkpoint,把整段历史头替换成一条 user 消息)与系统提示漂移(如 dsh 重启后 GUI 端口重分配写进 system prompt)落在同一轮时,既有的全部位置型 re-anchor 逃生结构性不可达——被记录的尾部按定义已被抹掉、incoming 比记录更短、压缩后首个模型步零 assistant——于是活着的会话确定性地分叉到 `<id>|sub:<fp16(新tag)>`:父车道记录冻结、副车道从零起步(resume-inheritance miss)、事故当天又触发 3 次再压缩 + 1 次 REFUSED turn + 2 次 max-tokens 截断。根因=判定器要求一种全量压缩按定义抹掉的字节级续接证据,而唯一能存活压缩的自足证明——bili 自己铸造的 checkpoint 内嵌的 `conv="<rawId>"` 自声明——从未被读取。现在 tagChanged 分支最前新增 E5 级:**第一条** user 消息携带我方 `\x3cbili-snapshot v1 …\x3e` 身份头且其 conv 与当前 id 逐字相等 → 直接 re-anchor 回主车道(record() 同步更新 tagHash,后续请求即普通 continue)。外部 persona 引用 checkpoint 的情形照旧分叉:要么根本到不了判定层(sideRequestLike 门,#4438),要么标记 conv 不符 / 不在第一条 user 消息。**旧行为→新行为**:该形状从「必然分叉」变为「带自声明时 re-anchor 回主车道」;无标记的形状逐字节不变(回归测试钉住每一既有 rung 的 reason 文案)。tests/issue5719-self-checkpoint-reanchor.test.ts(验收标准 1/2/3 + 四种 wire 形状 + foreign-quote 边界)。
|
||||
|
||||
### Changed
|
||||
- **文档集中化:14 个根级文档一次性迁入 `docs/`(owner 指令 2026-11-08)**:`CONFIGURATION` → `docs/configuration`、`CLIENTS` → `docs/clients`、`TECHNICAL-NOTES` → `docs/technical-notes`、`MESSAGE-IDENTITY` → `docs/message-identity`、`SESSION-IDENTITY` → `docs/session-identity`、`PLUGIN` → `docs/plugin-protocol`、`LIFECYCLE` → `docs/lifecycle`、`UNIFIED_LOOP_SPEC` → `docs/unified-loop-spec`、`AUTO-MERGE-GUARDRAILS` → `docs/auto-merge-guardrails`(含 zh-CN 对);新增 `docs/index.md` / `docs/index.zh-CN.md` 文档总目录。原路径留单行重定向占位(计划 1–2 个版本后删除,卫生账见 `docs/lifecycle.md` §5)。npm 包 `files` 数组、CI `docs-sync` diff 路径、`scripts/{config-surface-guard,lifecycle-ledger-guard}.mjs` 运行时读路径随迁;全仓链接面(README / AGENTS / reference / src 注释与用户可见文案 / website)改写到新路径。
|
||||
- **pi 内联压缩通道默认开启(#5428,取代 #4687 的手动开启规则)**:装了 bili 扩展的裸 `pi`(没设任何环境变量、没写配置)现在直接跑**进程内引擎**,不再自己派生代理进程。新优先级:kill-switch > /bili/ 改写启动 > 显式内联(`BILI_PI_INLINE=1/on/yes/TRUE` 或 `"pi": {"inline": true}`)> 宣告的附着目标(launcher 预置的 `BILLION_CONTEXT_PROXY/ATTACH`,`bili pi` 照旧用自己的 launcher 代理)> **默认内联** > spawn。**人类入口(短旗标,必须放在子命令前)**:`bili -i pi`(≡ `bili pi-inline`,强制内联+预检扩展+清理继承代理变量)与 `bili -s pi`(钉死代理姿态:子进程预置 `BILI_PI_INLINE=0`,压过继承的内联变量;opencode 同理)。不想用内联:`bili -s pi`、`BILI_PI_INLINE=0/false/no/off` 或 `"pi": {"inline": false}`——都恢复旧的 attach/spawn 姿态(有宣告代理就附着,否则自己派生代理)。`bili pi-inline` 一键车道保留(同 `-i pi`);空白 `BILI_PI_INLINE=""` 按未设置折叠。opencode 通道的默认不变(仍手动开启,`-i/-s` 两个旗标对它可用)。
|
||||
- **The full-resend watermark fastpath (#5403/#5418) passed its §7.4 human review and ships behind the 5% experimental cohort** (owner ruling 2026-11-02: default off, small cohort first; the web switch + one-time intro notice ship alongside): plugin-lane chat-completions turns whose prefix is byte-stable skip the full history re-parse/re-pin on hit (the #5403 OOM producer), any doubt still falls back to the untouched full-parse path per turn. Force either direction per install with `rollout.features.pluginFullResendWatermark: true|false` (or a percent) or `BILI_ROLLOUT_PLUGIN_FULL_RESEND_WATERMARK=1|0`.
|
||||
- **The silent-direct oversized guard (#5405) defaults to 8 MiB and honors `BILI_SILENT_DIRECT_MAX_MB`.** The missing-slot / unattributed arms count RAW body bytes — base64-inflated media included — so an in-window session carrying even one medium image died at 2 MiB with a retryable 422 that could never succeed; the runaway multi-MB prompts the guard exists for are tens of megabytes or more. Default raised 2 → 8 MiB (owner ruling, #5826 release review); installs can lower it back per machine (megabytes, >0; invalid values fall back to the default).
|
||||
|
||||
### Fixed
|
||||
- **KeyRing model-local 429s no longer throttle other models on the same credential.** Bili gives an independent origin+credential+model hold only to HTTP 429 responses whose structured KeyRing or Bili marker has an exact request-model match; `keyring_all_limited`, direct OpenCode monthly quotas, malformed bodies, and mismatches remain origin+credential holds. Large passthrough bodies use a top-level model scan, while Gemini/Vertex/v1 and side-lane paths carry their actual wire model. Account/model probe slots are request-owned and canceled sends release only their token; concurrent provisional 429 observations settle independently. Continuation retries reserve bounded classification capacity per origin+credential before egress; saturation skips only the optional refetch, without a global gate or discarding account-wide evidence. Continuation reads retain the upstream idle/abort policy. Side-lane SSE retains its stream mode so render-tag stripping still runs. Regressions: `tests/issue4204-throttle-governor.test.ts`, `tests/issue4743-degenerate-refetch-429.test.ts`, `tests/proxy-noinject-tag-strip.test.ts`, and `tests/upstream-error-log.test.ts`.
|
||||
|
||||
- **中断后/usage 丢失后的「幻影紧急压缩」:本轮拿不到计费样本时,压力档压缩延后一轮再决定**:中断的流(用户 ESC)或上游短 TTL 缓存把 usage 报告弄丢时,本轮的「计量表针」只能落回字符级本地估算——它量的是即将被改写丢掉的入站字节,实测比真实计费高约 3 倍(0.1.212 当天两起真实现场:ESC 的会话从 9478 跳成 228376、长跑会话被连续两轮注入 153% 幻影压力带,徒劳改写并烧掉前缀缓存)。此前这种坏表针直接按 EMERGENCY/OVER-LIMIT 扣扳机。现在:内核收到以「估算值」计量的压力带读数(宿主标记 tokenCountSource="estimate")时,本轮压力档注压延后一轮——下一次请求必然带着新鲜计费报告,拿真数再决定,代价≈0;计费级读数("usage")与不传 source 的老调用方字节不变,非压力档(增长/节拍)完全不受影响,硬溢出兜底臂全程照旧武装。宿主侧提前广告臂(emergencyNudge)同步镜像该位,不会拿着同一个坏读数抢跑。逃生阀:`compress.requireUsageSampleForPressure: false` 恢复旧的估算驱动行为。tests:kernel/tests/nudge-pressure-no-sample-hold.test.ts(6 例)、tests/nudge-pressure-no-sample-armed.test.ts(3 例);kernel 既有套件 1582/1582 绿。
|
||||
- **External-summary mode no longer reports protected or already-folded ranges as failed compression.** An unchanged kernel preview now returns the normal idempotent no-op or kernel-error receipt without a paid summarizer call; validated internal probe summaries prevent an irrelevant submitted-hint length from blocking that receipt. Probe-created blocks with no recoverable content still refuse rather than folding an unreviewed hint. Regression: `tests/external-summary-runtime.test.ts` (24/24).
|
||||
* **#5412: 异步存储后端的「压缩冻结会话」现在也能自愈。** #5408 事故(一个会话连续 17 次摘要漂移后被保护机制冻住、8 小时无人知晓)的主修复 #5409 只教了同步存储路径(SQLite 直写)自救:漂移挂起期间保存会自动升级为全量重导入并清掉索引里的残留行。异步路径(opt-in 网络后端,如 mysql)那份孪生代码没搬——同样被冻住的会话在那上面永远救不回来,每次保存都重写不完整视图、下轮采样继续漂移。本 PR 在 `src/storage/shadow.ts` 的异步入队路径补上同一行对齐(`completeLog = hasRawTail || driftedSessions.has(id)`),行为与同步路径逐字一致;回归测试同时钉住正门(latch 挂起的折叠保存清掉外来行)与负门(未挂起保存不清扫)。
|
||||
- **中断频繁的会话压缩提醒几乎不触发,积到几十万 token 才压一次(#5415,0.1.210 引入)**:#5293 的修复把每次用户中断后的增长参照点直接抬到当前读数,连「中断前已实测的真实增长」也一起清零;高频中断的客户端(实测一份日志 4.5 小时 85 次中断)永远攒不到增长台阶,30 万可压内容 idle 数小时,最后一次性压 33 万。现在吸收时把被清零的实测增长记入「欠账」(`nudge.absorbedDebt`)并累计吸收次数(`nudge.absorbCount`),两者都只在**第 2 次起**的中断后生效:单次中断字节级保持 #5293 的安静(不打扰用户刚改的主意——欠账再多也不当场弹提醒);第二次中断才证明会话是「高频中断型」而非「改主意」,欠账从此与新增量一起计入增长台阶,恢复 209 时代的节奏。另加「大积压排水」兑底:欠账>0 且可压量≥2×阈值且当前无未消化提醒时不再等增长台阶(与 #194 同哲学);无欠账/单次中断的会话决策字节不变。压缩成功时欠账与计数随其它基线一起清零;idle 日志同步显示 `growth X + absorbed Y across N aborts < floor Z`(单次中断显示 `held (single abort, #5293)`)便于排查。tests:kernel/tests/issue5415-absorb-debt-nudge.test.ts(欠账付台阶/单次中断钉死不弹/排水兑底/忽略提醒不重发/无欠账字节不变/压缩后清账+清计数);tests/issue5415-absorb-debt.test.ts(吸收记账算术、欠账+计数、累次累计、参照点已越过 anchor 不记账也计数、陈旧 flag 丢弃)。
|
||||
- **长会话每回合把 Node 主线程卡死十几秒、网页面板冻结(#5337)**:每回合的压缩筛查把历史切成若干可折叠单元,逐个跑「能否折叠」判定——而每次判定都从零重扫全量消息数组(id 查找无索引,五处线性 `.find()`/`includes`),还重复重算全套整史统计(受保护/过期工具调用集合、工具配对表、末尾锚点、完整性预扫)。总工作量≈单元数×全史长度=历史规模平方级,且同步跑在主线程:2.3万条核心消息实测单回合约17秒(事件循环被占死,请求排队;#5304 同签名报告)。修复=把这批 O(n) 推导提升为每轮筛查**一次**构建(`buildProjectionShared`)、共享给同一轮所有单元;id→序号一次性建表替五处线性查找;「已丢弃」成员判断从 includes-in-some 改为 Set。判定逻辑本身一字未动(#3236 单一判定纪律),只是输入到达判定的方式变了。同机同语料实测:2万条消息完整推荐链 9028ms→约572ms(≈16×),回落到线性量级。单次调用路径(apply/report)保持原有内联计算,输出逐字节不变。kernel v0.0.175。tests/issue5337-shared-screening.test.ts(共享/非共享投影逐字段等价+降级边界一致+n=20000 耗时上界钉);既有 issue3406 曲线钉与 #3236 一致性回归不变。
|
||||
- **web 设置 i18n 目录校验在 master 上自 #5345 起恒红(每个新 PR 的 CI 连带挂三片测试)**:pack 编辑器文案两处不合规——英文 `cfg.q_pack_ai_p1` 少了 `{need}` 占位符(中英占位符必须一致);起稿底本下拉的 4 个 key 经「键名数组」间接引用(`t(pair[1])`),死 key 扫描按字面量匹配把它们误判为无人引用。补占位符 + 扫描器接受源码里逐字出现的点分键名即修;纯守卫侧改动,不改任何界面行为。
|
||||
- **重启后第一次压缩可能把别人的消息静默折叠进去(#5196)**:重启触发的「编号对账」把消息编号对齐成库行序时,腾出来的空位可以被别的消息当场顶班;而解析旧编号的规矩是「活着的号优先」——于是模型拿着重启前看到的号发压缩,HTTP 200 成功、块盖住的却是顶班者(0.1.209 真实事故,fixture 已归档)。现在对账中每个挪窝消息腾出的座位即被保留:顶替者改领游标处的全新号(既有 displaced/rehomed 机制),任何编号从此不可能同时指向两个身份——「活着优先」在这类数据上天然安全,不再需要拦截或披露。代价仅是编号空间里出现稀疏空档(编号是展示层标签,无功能成本);此前 #4807 在「几秒重放窗口 vs 永久死锁」间的取舍保留不变。tests:kernel seq-restamp 改写互换断言+新增 3 条退役/停车回归。
|
||||
- **上游报错证据压低判定窗口时,日志不再自相矛盾(#5191)**:[headroom] 行宣称「nudge/preflight 按窗口 N 判定」,但会话自己的溢出证据(上游 400 明说"X in the messages, Y in the completion"——补全份额和输入记在同一堵墙上)会把真实判定墙压到 min(N, 墙-Y),事故日志里两个窗口互掐,排查被引去查根本不生效的配置(#3450 证据优先于运营者配置是设计)。现在压低发生时新增 [arm-judge] 行直接报出实际判定墙与两个证据数(按 会话|模型|判定墙|headroom 值 去重;headroom 自己被 provider 级证据再压时重报),[headroom] 行同步加上「溢出证据可能判得更低」指引;post-400 恢复重试里 config 窗口已被改写,故对基准改用 `reservedContextLimit` 孪生值而非 config 本身,不再把武装天花板误标成 headroom 窗口。`tests/issue5191-arm-judge-line.test.ts` 钉住首请求中途武装、provider 压低后重报、同值不重报、跨会话各自报四种面。
|
||||
- **磁盘写入临时失败后,会话不再陷入「之后每次触碰都硬报错」(#4788 phase-2 副作用)**:phase 2 的闲时内存折叠会在一次成功保存之后,把内存里的原始内容降成「用时从磁盘重新加载」的惰性代理。若此时盘上信封恰好写不进/已损坏(瞬时写入失败或损坏),下一回合采纳内核新内容时要先读旧内容做差集——按 #2674 纪律它会抛「无法重新物化、拒绝瘦身视图」——整个采纳直接炸掉:新引用记不进去,会话从此每次访问都报 `[persist] resident content store … could not be re-materialized`,直到人工修好文件。现在旧内容重加载失败(镜像与 sidecar 双双已不可读)时按「无存活旧引用」处理——旧字节那时本已不可恢复——新库照样完整采纳、标脏并在下次保存落盘,会话随瞬时故障消除而恢复而不是持续报错。tests/store.test.ts 的 flushAll 瞬时失败重试回归恢复绿。
|
||||
- **重复调用守卫不再一口咬死合法等待/轮询(#5225)**:此前同一工具、同样参数连发到第 5 次时,守卫在调用执行前就掐掉整个回合——调试器等待(`kd_wait` 10 秒一次)、omp 任务轮询这类「参数本来就不变、结果随外部状态变化」的合法调用被整段杀掉(Pi Codemode、omp 两起真实报告,等待还没到期)。现在升级为三段式:连续第 3、4 次照旧随结果附警告;第 5 次改为只拒绝这一次调用并发出明确的最后警告(回合保留——模型此时把多次短等待合并成一次更长等待、或换参数换工具,计数立即重置);被拒之后仍一字不差地重发同样调用,才终止整个回合。真死循环保护不受削弱(最多多烧一次调用)。同时修正提示文案里两处误导说法(「字节级相同」实为规范化后相同;「同样的调用不可能有新结果」对轮询类工具不成立)。tests/tool-guardrails-pi.test.ts 更新升级链断言并新增合法轮询逃生回归。
|
||||
- **两份安装(全局树 + 宿主自带副本)差一个自动更新版本时不再互相卡死、流量裸奔(#4125)**:机器上 bili 本来就有两份合法安装——npm 全局树和宿主管理器自带的独立副本,各由各的更新节奏往前走。当全局树领先一个版本时:宿主插件想接上已占端口的旧进程 →「代码指纹不一致」拒绝采纳(#1225);旧进程置换只敢碰更老的邻居,而占位者是更新的那份,永远够不着(#3544);新拉起的子进程一绑定端口就撞口、向这个谁也不敢采纳的持有者让位退出——三条路全堵死,整条车道直接连模型(无压缩),直到有人整机重启对齐版本。修复三面一起落:①拉起子进程时把自己的代码摘要随环境传下去(`BILI_SPAWN_FINGERPRINT`,64 位 hex sha256;非法/缺失回落本地重算,沿用 #1225「陌生进程自称身份不采信」原则)——「同一构建」从此比字节不比口号;②宿主侧:候选者因指纹不一致被拒之前,先问一次**活着的**持有者真实版本号——严格更新、同车道、同形状、健康应答为证 → 采纳骑上而不是拒掉(跨车道和用户自己起的实例仍一律不碰,它们没有 bili 替身可退路);③子进程侧:确认端口被「严格更新的同车道同形状存活实例」占住时不再逐级换口(那只会造出第二个没人路由到的影子实例),改走既有的采纳信号退出(exit 3),由宿主骑上更新版。手动启动与升级替换流程语义完全不变。`tests/issue4125-two-install-deadlock.test.ts`(9 例)+ listen-policy/issue3654 判定表扩展钉住全部三面。
|
||||
- **压缩「总是失败、要重试很多次才成功」的活锁(#4521)**:长会话里模型重报已被折叠覆盖的区间、或把 endId 猜到尚未发号的 ref 之上、或整段落在保护区,这些「其实无事可做」的请求一律被判 FAILED——原子批整体拒绝、断路器计数、模型照失败提示再猜再试,形成「失败→重试→再失败」循环(实测会话 01a18a4d 在 20:09 连续 4 次 FAILED 才成功)。现在五处修正:①endId 越界自动钳到最高已发 ref(警告提示,不整批拒);②区间全覆盖既有活动块=幂等 no-op 成功收据(`noop: true`,提示用 bN..bM 改写而非重发原文),不失败、不进断路器;③纯保护区区间同样 no-op(警告明说勿重发);④保护区 fatal 不再中止整批,只降级该区间;⑤新增 armed-but-silent 状态行:tier 级 nudge 已备好但本轮不投横幅时(退避/节拍/模型定时),以临时 user 消息刷新「最高已发 ref + 当前可压区间」,模型不再凭记忆猜号;全新会话的低于阈值计划保持完全静默(#196 域隔离、#3910 基线不破坏)。
|
||||
- **自动升级换代旋转的「假存活」误判(#5167)**:旧实例接受 `/__bili/shutdown` 后毫秒级就关 listener(口已释放),但存量 keep-alive 连接照常应答——这是排水的本意(#3890 后最坏 (1+10)×10s 才退进程)。而两条旋转等待(launcher `rotateStalePredecessor` 每 200ms `fetchHealthInfo`、dsh `rotatePinnedStaleProxy` 每 500ms `fetchProxyVersion`)都用全局 fetch 的连接池轮询,轮询节拍远小于服务端 5s keepAliveTimeout,永远落在预热过的池化 socket 上 → 把「正在排水」误判为「没退出」,12s 预算耗尽得到假阴性:dsh 宿主 attach-anyway 骑上将被强退的旧实例、launcher 回退 spawn 阶梯,新旧两进程同写一份 machine-global 会话存储(index.db 双写横幅、#5046 SQLITE_BUSY、JSON 状态互踩)。修复:旋转等待的全部请求(含 shutdown POST)改带 `Connection: close` 每轮全新连接,「应答」重新等于「listener 还在收新连接」=真正的口释放信号;同步修正 12s 预算的过时注释(它只需覆盖 shutdown 请求被处理的延迟,不需覆盖进程退出)。`tests/issue5167-drain-aware-rotation.test.ts` 用真实排水 http 服务器(无 fetch mock、单连接 dispatcher 钉住池化拓扑)双向钉住:排水中的 resident 必须判为已释放,真占口不退的 holder 仍走超时回退。
|
||||
- **shadow 摘要漂移的单实例成因(#4392 / #4986)**:`canonicalize` 曾按 `Object.entries` 插入序参与哈希,而 live 腿(kernel 状态,`byRef` 按发号顺序)与 replay 腿(`loadLegacyView` 按账本 `ord` 重建 `messageRefs`)对同一份等值状态给出不同键序 → 单进程自我报告 `[diverged: state]`,连续 3 次即冻结本进程的信封写入并清掉入库水位。现在任意深度按键排序(数组保序,Map/Set 形态不变),跳过的键(去掉 `storageMode`/`tailGaps`)集中成 `canonical.ts` 导出的 `DIGEST_SKIPPED_KEYS`,供流式摘要路径共用;升级文案不再断言「多个 bili 实例」。storage-corpus manifest 随摘要定义重钉(只有 10 个摘要值变化,文件清单/格式不动);storage-render 金标无需改动——那套驱动在 harness 侧已先 `sortObjectKeys`,排键只改 shadow 腿与 corpus 摘要。`tests/issue4986-digest-drift-ref-order.test.ts`(取自 #4997)钉住 #4986 的 folded-corpus 面。
|
||||
- 出站不变量判官新增 I3 配对不变量(#4862 出口校验缺口):此前判官只对账入站↔出站连续性(I1/I2),折叠区内完全免检,于是「折叠拆断一对 tool_use/tool_result」的出站体拿到 clean fold verdict 直接放行,直到上游用 400 `tool_use ids were found without tool_result blocks` 说出真相。现在每个 tool-call 必须有同 id 的 tool-result 在其后、每个 tool-result 必须有同 id 的 tool-call 在其前,折叠区不再豁免;归因保持“谁的错”职责(宿主自己发来的断对不计 bili、compress 在途调用豁免、id 重铸不可洗白)。纯检测不拦截,受 diagnostics.invariantJudge 旋钮控制。
|
||||
- 块区间边界在重存时不再回退:折叠后客户端重发的视图不含已覆盖原文,重入库时该批次无法重新解析区间(-1/-1),旧逻辑会把已解析的真实区间抹掉。现在区间证据一旦解析即持久(入库 `CASE` 保留;sqlite/mysql 双后端),未知块保持诚实缺口(#4608)。
|
||||
- 优雅停机(SIGTERM → dispose)的 writer 标记现在记录 `stoppedAt`:重启流程(杀旧进程→立即重绑)不再对已确认死亡的前任实例误报 [split-brain]——30s 新鲜度回退从此只覆盖无法证明死亡的崩溃场景(#3923;release-gate lane A 代理重启时观察到误报)。
|
||||
- Claude Code 子代理的 bili 调用不再路由到父会话:Task 子代理与父线程共用一个 MCP shim,启动时抓的绑定只指向父会话;子代理压缩错对象或永久 409。现在 shim 把 host 盖在每次 tools/call 上的 `_meta["claudecode/toolUseId"]` 转发为 body `toolCallId`,代理用它出站时记下的 id→会话映射直接路由到子代理自己的 lane(10 分钟 TTL);id 未知时行为与从前完全一致(#4580)。
|
||||
|
||||
### Added
|
||||
- **消息身份公用设施(sessionid+msgid)的校验规则从「注释自律」升级为 CI 机械锁(#5826 release review 缺口修复,owner 裁定)**:id 卫生规则散落在六份副本(canonical `validateMsgIds` + dsh/incremental-client/pf-channel/fastpath/request-membership 五处镜像;镜像是结构性必需——注入宿主的 bundle 禁止 import server 模块),过去靠「keep in sync」注释同步。新增 `tests/msgid-rule-parity.test.ts`:每个拒绝类(非串/空/超长/保留前缀/空白与控制字符/U+200B/重复/宽度)逐一喂过每份副本并钉死当前判决,有意分歧按分歧钉死并注明理由;改任何一份规则必须先过该测试。同批收敛:`fastpath parseTailIds`(tail-ids 头服务端解码侧)补齐 canonical 保留前缀门——所有生产发射方本就预筛,此为单点收口纵深防御,判决方向更保守。配套文档地图 `docs/msgid-infrastructure.md` + `.zh-CN.md`(生产端→四种传输载体→六份校验副本→存储单一事实源→五个消费方→四条信任边界→改动清单);AGENTS.md KDD #17 声明其生产/消费来源,改动相关代码前先读。
|
||||
- **#5825 身份信道接线:统一消费缝 + 六条车道。** 身份信道的服务端半边(信封 `msgIds`、全量重放 `biliMsgIds`/`biliLedgerSeqs`、统一存储 `(session_id, seq, msg_id)`、#5719 救援档)此前只服务 dsh;本 PR 按 issue #5825 的逐客户端结论把其余车道接进**同一条**消费缝,不做任何逐调用点单独取数(owner 裁定 2026-11-07:能接的都接、不再拆分)。新模块:`src/identity-harvest.ts`(注册表 + 门控:**env `BILI_IDENTITY_HARVEST`(缺省关,可点名车道)与灰度键 `rollout.features.identityChannelHarvest` 二者任其一即可使能、均默认关** × 回环来源 × 整轮退化纪律)+ 自包含适配器:`src/identity-claude.ts`(claude-code 转录 JSONL 尾部快照,sidechain/summary 行排除)、`src/identity-codebuddy.ts`(codebuddy conversation-id==文件名布局)、`src/identity-mcode.ts`(mcode/mavis runtime-state.sqlite 每轮只读快照)、`src/identity-goose.ts`(goose sessions.db `message_id` 行;`agent-session-id` 头已入会话识别低信任层)与 `src/identity-qwen.ts`(qwen-code `chats/<sid>.jsonl` git-log 转录;join 用官方 BYOK 文档示例头名 `x-opencode-session` 的 `${session_id}` 自定义头——用户自选其它名则安全退化)+ barrel `src/identity-sources.ts`。opencode **V2** 宿主侧接入:扩展在自己的 http-request hook 里读**当轮自己的**结构化消息铸 `x-bili-msg-ids` 请求头(同一事件取值零竞态;任一变体缺 id → 整份戳作废),服务端按 body 字段 > 该头 > 采集注册表 的优先级消费。pin/行链路补 openai wire 对等件(prepare-openai 与 prepare-anthropic 同款无条件剥除 + 灰度内钉住,命中水位快路径的轮次因窗口变短按构造不参与)。任何一处不判定 → 整轮回退接线前路径,绝不做部分映射。附带合并 #5825 决定 A:codebuddy 的 `x-conversation-id` 进入会话识别名单(低信任层)。crush(join 键是 xxh3 摘要且库在工程目录内)/ gemini-cli(仅装机级身份)/ hermes(线上零身份信号)/ iflow(产品已下线)四条按审计结论记闭合备忘,见 docs/identity-channels.md §2。默认零行为变化(两个使能方都缺省关 + 仅回环)。测试:`tests/identity-harvest.test.ts`(含夹具级 SQLite/JSONL 布局)、`tests/opencode-v2-msgids.test.ts`、`tests/msgid-header-channel.test.ts`、`tests/openai-msgid-pin.test.ts`(全链路集成:字段绝不上游 + 行带客户端 id)。文档 AGENTS.md 新增 KDD #18(与 #5826 msgid 基础设施条目相邻,合入时如编号冲突顺延)、docs/identity-channels.md/.zh-CN.md、website/config-reference 登记(env-only + rollout)。
|
||||
- **`bili kiro`:Kiro CLI(AWS)启动器车道 / launcher lane for Kiro CLI.** Kiro 的模型调用是 `runtime.<region>.kiro.dev/v1/responses` 上的 Responses wire,每轮重放完整历史、bearer 鉴权、遵守 `HTTPS_PROXY`--现有 responses 管线即可压缩,只需处理两处网关差异:1网关只收 `user`/`assistant` 项,注入的 `developer` 压缩提示会被 400(`param: input[0]`)拒绝 → 对 Kiro 流量内置 `developer`/`system`→`user` 角色映射(最低优先级,`compat.roles` 与学到的角色仍按键覆盖;判官按原角色看待注入提示,不误报 I1);2Kiro 首项跨进程不字节稳定,`--resume` 会新建会话 → 提升 `metadata["kiro:conversation_id"]` 为会话 id(`kiro-<id>`,只覆盖内容指纹)。车道只 MITM 四个 `runtime.*.kiro.dev` 网关,合并 CA 同时写 `SSL_CERT_FILE`(Rust 外壳)与 `NODE_EXTRA_CA_CERTS`(Node 代理服务),回环走 `NO_PROXY`。实测(kiro-cli 2.37,真实账号):0 次 400,14 次独立启动(13 次 --resume)始终同一会话,折叠 16.4K token 后口令仍可召回,判官 clean fold verdict。新文件 `src/kiro.ts`,测试 `tests/kiro.test.ts` + `tests/launcher.test.ts`(runLaunch kiro);文档 CLIENTS.md / CLIENTS.zh-CN.md「Kiro CLI(AWS)」节、README 表格与启动器列表。
|
||||
- **消息时间戳渲染默认开启(#4313 后续)**:此前 `compress.messageTimestamps` 为可选特性(默认关,线上字节与特性前逐字节一致)。生产会话的缓存审计(同会话开关前后命中率均 95.0%、无一条时间戳导致的前缀重写 miss、全部异常可归因上游 TTL 驱逐)证实存戳渲染跨轮逐字节稳定,故默认翻转为**开**:`time=` 压缩标签属性、回执指纹行 `[起 – 止]` 覆盖跨度、摘要 Occurred 行对所有人默认可见(每条消息首次出现时铸一次不可变墙钟戳,渲染只读存戳不读墙钟)。关闭方式不变:文件 `compress.messageTimestamps: false` 或 `BILI_MESSAGE_TIMESTAMPS=0`,关闭后每个出站字节与 pre-#4313 master 一致。升级用户的一次性代价:标志首次解析为开的那个重启后,每个活跃会话付一次冻结前缀缓存重写(旧消息补上 time= 属性 + 提示词变体切换),之后稳定。测试基线:tests/preload-test-env.mjs 整套件 pin 显示门控关,字节对比型金标保持特性前形态;issue4313 toggle 套件按新契约翻转并新增 message-timestamps-default-on.test.ts 钉住生产默认路径。
|
||||
|
||||
|
||||
- **新增回归套件:反复杀掉再重启代理(kill -15 / kill -9 / 优雅停机 ×2)后,压缩状态必须存活、缓存前缀必须保持稳定(#5631)**。此前「重启会话不丢状态」只有手工真模型门禁(bili-gate Lane A/B)覆盖,CI 里没有可回归的自动化断言——一次让磁盘态或前缀渲染在重启边界漂一下的改动,只能靠真跑门禁才看得见。新套件用两种客户端线形(dsh 形 chat-completions / pi 形 anthropic messages)驱动独立子进程代理:首轮塞入远超窗口的超大原始历史(默认 ~6MiB,`RESTART_SURVIVAL_FIBER_BYTES` 可调)逼出确定性 digest 折叠,随后按 SIGTERM/SIGKILL/干净停机混合序杀进程五次,每次以同一会话 id + 同一存储树全史重发续跑;断言每轮出站 ≤512KiB(折叠态存活)、canonical prompt 前缀稳定性 ≥50%(与真模型门禁 Lane A 的 cache 恢复阈值对齐)。判别力由第二控制臂钉死:同代码巨窗实例(10M token 墙)不折叠、每轮完整 fiber 原样穿透 ≥0.9× 原文字节——若折叠机制失效,主臂立刻爆到同等尺寸。仅用既有配置面(`compress.modelContextLimit` / `BILI_CONFIG_FILE` / `x-acp-session`),无新增旋钮、无 kernel 改动。pi 形用中性模型 id:side-request passthrough(#388)只按客户端证据武装(agent 头 / 输出预算 ≤200 / 宿主 sidecar 形状,src/server/side-request.ts),从不按模型家族判定,故任何 id 都留在主压缩路径;中性 id 让套件不依赖 claude 注册表/窗口表条目。本地实测 dsh+pi 双 lane 全绿(~27s);`tests/issue5631-restart-survival.test.ts`,已登记 `scripts/live-files.mjs`。
|
||||
|
||||
### Storage — bun 运行时原生支持(`bun:sqlite`)
|
||||
|
||||
- **在 bun 上跑 bili 不再退回 legacy**:引擎阶梯加了第 0 步 `bun:sqlite`(src/storage/driver.ts,只有 `process.versions.bun` 存在时才 require —— bun 里 `node:sqlite` 根本不存在,而 better-sqlite3 的 N-API 预编译在 bun 下必定 "Could not load the default exports from better-sqlite3",阶梯三步全落空只会得到 legacy-only)。bun 内置引擎与 better-sqlite3 同形(`Database`、同步 `run/get/all`、`.transaction()`),适配层只补三处实测差异:命名参数按 SQL 里书写的记号绑定(`:a`/`@b`/`$c`,而库内 SQL 是 better-sqlite3 风格、传裸键 `{ a: 1 }`)——按语句把裸键复制成该语句真正用到的记号形态(字面量先抹平,故字符串里的 `:name` 不会被误认);BLOB 列回裸 `Uint8Array` → 归一成 Buffer(媒体/载荷读取端按 Buffer 契约写);`run()` 的 `changes`/`lastInsertRowid` 是 BigInt → 收成 number,并补 bun 没有的 `.open` 旗标。写事务走 `.immediate()`、只读走 `.deferred()`(#2690 的写锁拓扑:延迟事务中途升级为写锁会撞 busy_timeout 救不回的 SQLITE_BUSY_SNAPSHOT),`close()` 幂等。
|
||||
- **自举与状态文案不再指错运行时**:bun 上自举直接 `not-needed`(给 bun 下载 N-API 预编译纯属浪费带宽且必加载失败);`nodeSqliteUpgradeHint` 与降级横幅在 bun 上讲 `bun:sqlite`,不再让运维去升 Node;整史后台完整性 worker 是自包含源串、不复用阶梯,也按 `process.versions.bun` 选引擎(bun 的只读选项名是 `readonly`,不是 Node 的 `readOnly`)。
|
||||
- **测试钉住契约**:tests/storage-bun-sqlite.test.ts —— 假 Database 那几组经测试缝 `setBunDatabaseFactoryForTests` 在 Node CI 上同样可跑(记号双写、字面量外只重写一次、BigInt/Uint8Array/null 归一、事务必须 `.immediate()`、阶梯第 0 步优先、被钉的 `{builtin, host}` 探针袋视为 Node 主机);真内置那几组仅在 bun 下跑(真 BEGIN 与回滚、嵌套事务不提前提交、写完锁立刻交还,以及真 UnifiedStore 端到端:开库跑 PRAGMA 阶梯 + quick_check + 迁移、命名参数插入、读回、close 触发 WAL checkpoint 后重开仍在)。
|
||||
- **既有存储套件在 bun 下实测**:7 处写死 `openSqliteDatabase(path, "node:sqlite")` 的裸句柄改为随动自动探测后,block-bounds 1/0、fork-clone-media 3/0、issue4982 18/0、unified-remap 3/0 全绿;storage-unified 从 4 通过/13 失败变成 14 通过/4 跳过/0 失败(三条只驱动 `node:sqlite` 的 leg 现按驱动探针跳过);storage-ingest-watermark 15/1、bounded-load 4/1、engine-proofs 7/5、plugin-fork 51/5、engine-bootstrap 维持 43/1。与改动前同机基线相比:多通过 24 条,零回归。剩余失败与存储引擎无关:bun 的 node:test 垫片没有 `t.mock`(oven-sh/bun#5090)、Node 专用套件顶层静态 `import("node:sqlite")`、以及子进程 harness 在 bun 下的 ERR_SERVER_NOT_RUNNING。
|
||||
|
||||
### #5079 — `prompt_cache_key` 自注入默认关闭,`promptCache.routing` 一个开关管住两条 wire
|
||||
|
||||
- **行为变更(旧→新)**:此前 bili 在插件车道对一切目的地默认给请求体盖 `prompt_cache_key=<会话 id>`(#2218/#2649 定案,Responses wire 仅对 `api.openai.com` 注入)。由于大量服务见到该字段会直接拒绝、且这类服务无法枚举,**默认反转为关闭**:`promptCache.routing` 缺省值从 `"auto"` 变为 `"disabled"`(无法识别的值同样落到 `"disabled"`)。客户端自带的 key 不受影响:任何模式下都原样转发(A/B 探测记忆对已证实拒收的 origin+model 组合照常撤键)。
|
||||
- **单一开关**:`promptCache.routing`(env `ACP_PROMPT_CACHE_ROUTING`,或 Web UI 快速配置下拉)现在同时管住两条 wire 上 bili 的自注入——chat wire 插件车道请求体盖章 + Responses wire key 注入。`"disabled"`(新默认)= 从不写自己的 key;`"auto"` = #5079 之前的行为;`"enabled"` = 所有支持的车道都盖/注(Responses wire 任意 host)。插件车道上等于绑定会话 id 的请求体 key 是 bili 自己机制的回显(dsh `PI_CACHE_RETENTION=long` 栈等),按自注入处理;Responses wire 同理(显式 key = 会话 id 且身份未被提升时算 bili 打的)。
|
||||
- **升级提示**:运行 `"disabled"` 的实例展示一次性提示 —— Web 面板横幅(可关闭,按实例持久化)、`acp_status` 一行、启动日志一行 —— 点名中转站(workbuddy panel/hub 类)/号池场景应设回 `"auto"` 或 `"enabled"` 以维持前缀缓存亲和,直连官方 API 用户忽略即可。
|
||||
- Web UI 快速配置新增 `promptCache.routing` 下拉(disabled/auto/enabled),保存即热生效。
|
||||
|
||||
### D5-5 — 渲染源窗口化 + 判官 tailStart 视图域修复
|
||||
|
||||
- **渲染分窗(storage-review D5-5)**:`buildView` 不再全表加载正史行(数万行 × 每行媒体水合 = 每请求读放大)。新两层查询:`messageIdRows`(seq+msg_id 列,无字节,全行,驱动块锡定+接缝链)+ `uncoveredRows`(仅覆盖区间外的行取字节+媒体;covered 字节永不读——covered 行腐败不再导致渲染降级)。块锡定从字节匹配改 `msg_id` 列匹配零语义变化;两查询间隙新行的竞态→一次全量回退兼音。`unifiedTailViewRows` 保留为回退路径。
|
||||
- **判官 tailStart 视图域(#4241 回归修复)**:`snapshotRenderTailStart` 原记客户端域下标(clientJoin),但判官用它索引 `judgeBaseline`(渲染视图)——视图前缀压缩后 clientJoin 可指向视图末尾之外→判官空转(total=0 空转 clean,T1 合车后把 #4241 牙齿测试打红)。改记视图域(视图行数 − 尾巴数)。牙齿测试同步改注尾巴行(引擎尾随 nudge 占末位,最后一条尾巴在 exitCores.length − 2):渲染前缀豁免是设计内(#4241:跨轮前缀稳定归 seamLcp/shadow),尾巴行丢失必须开火。
|
||||
|
||||
### #4316 层 3 PR3/3 — 存量编号一次性对齐正史 + fork 克隆保号
|
||||
|
||||
- **kernel `restampRefsToLedger`**:把既有引用空间一次性重排到正史账本(ref = store 行 seq + 1)。计数器路径按到达顺序发号但受保护消息不占号,而行 seq 照发 → 两者天然漂移;编辑与 churn 拉大缺口。重排后引用空间与存储真值一致,churn 不再改写编号。诚实边界:无映射 id 留给 assignRefs 的章路径;BLOCKED 仍不占号;死 ref 保留;被夺号的无行引用重安居新号(id 永不复用契约不破);多代(同 id 多行编辑)id 由 `seqByRaw` 排除不误绑。`CompressionState.refLedgerAligned` 标记一次性(`state-hydration` 字段单一事实源自动持久化)。
|
||||
- **挂点=服务触达(getSession)非 loadSync**:loadSync 保持纯对等视图(corpus manifest 摘要钉死不动);`getSession` 双路径(内存命中/盘重载)首次触达触发对齐——同进程重启边界语义不变(新进程无 in-flight compress,半重排映射不可见)。
|
||||
- **superseded 守卫**:重排换手的旧 ref → rawId 映射记在 `Session.restampSuperseded`(进程生命周期);重发 in-flight compress 调用引用旧号 → 诚实拒绝(绝不静默折错段),提示重读 acp_status 后重发。拒绝安全不会错折,一次性代价后消失。
|
||||
- **fork 克隆保号**:`cloneSessionRows`(store+mysql 双后端)把父会话行整段复制到子(session,seq) 保号 + lineage 列(parentSessionId/forkPointSeq 真值)+content/media CAS refcount 提升 + 幂等重放;子 append 自然从父 maxSeq+1(remapPlanToAbsolute)。fork 端点接线,存储不可用降级=kernel-only 克隆(现行为)。
|
||||
- **验收桩**:kernel 4 测(BLOCKED 偏移重排/交换原子性/无行引用保留+被夺号重安居+死 ref 不动/已对齐幂等)+host 4 测(整段克隆保号+lineage+幂等+子续号/部分分支/superseded 拒绝+当前号通过/冷加载纯视图+服务触达对齐一次+二次幂等)。
|
||||
|
||||
### 面板内置博客与长文(#4587)
|
||||
|
||||
- **`/__bili/blog` JSON feed + `/__bili/blog-assets/*` 图片路由**:随 npm 包内置的 markdown(website/blog/posts/*.md + website/articles.json 清单列出的仓库长文,paper 中英文)由服务端 `web/markdown.ts`(转义优先、XSS-safe)渲染进面板自己的「博客 Blog」页——卡片列表点展正文,双语随面板语言切换,离线可读;`web/markdown.ts` 顺带支持了图片引用(http(s)/面板资产路由以外的一律丢弃)和 GFM 管道表格(复用 .data 表格样式)。图片路由带穿越/编码/扩展名三重门。内容随自更新前进,GitHub Pages(#4561)仍是永远最新的完整文库。零新配置键/env/磁盘缓存。
|
||||
|
||||
### 修复 master 回归(搭乘)
|
||||
|
||||
@@ -43,6 +120,7 @@ Versions follow the merge of a `*_release-v*` branch; CI publishes to npm on tag
|
||||
|
||||
### Fixed
|
||||
|
||||
- **win32 统一存储降级提示:READONLY 签名点名 + OS 级拒绝不再建议删 index.db(#4614)**。现场报告(v0.1.205,win32-x64):index.db 已存在且早期可写,某次重启后打开报 `attempt to write a readonly database`——与 #3823 同一类 OS 级拒写(完整性标签/AV/并发写者)在文件已存在时的另一种表面(打开成功、第一次写入被拒 → READONLY 而非 CANTOPEN);但既有提示只认 CANTOPEN 字符串,诊断 reason 零可操作信息,warn 行结尾还跟着「delete the file to reset the index」——full 模式下该建议有害(index.db 可能是被冻结会话近期状态的唯一副本)。修法:`sqliteOpenFailureHint` 扩展覆盖 READONLY 签名(点名完整性标签嫌疑、icacls 查标签命令、递归 Low 重打标、AV、并发写者,明确 do NOT delete);degrade 尾部改为「hint 触发时不附删除建议」(CANTOPEN/READONLY 同享;真损坏文件与非 win32 平台维持原样)。测试:`tests/storage-cantopen-hint.test.ts` 新增 5 例(READONLY 正负双向 + 0444 文件确定性复现 READONLY 降级 wiring + stub-win32 删除建议抑制钉 + 原生平台双向),全绿。
|
||||
- **master CI 全红修复:#4390 historian 的媒体引用释放 + #3250 WAL cap 断言预算(#4506)。** bisect 定位 f161c518..02f544da 窗口 first bad = #4390(row-identity-historian),两个破口:① 权威集清扫改墓碑后,retired 行的 message_media 映射与媒体 CAS 引用永远不释放(默认要等 archive 365 天)——图片重度会话里即 #3762/#3901 的字节泄漏,`media-cas` 家族在 windows 分片稳定红。现在 retire 时释放媒体映射+引用(文本字节照旧史官保留;图片体积大、历史价值低),rewind-redo 复活时由重摄取路径幂等重建映射与引用(sqlite+mysql 双后端同款)。② `#3250: configured cap` 断言的 CAP_SLACK=4KiB(一页余量)预算不住 #4390 新增的每行 WAL 体积(identity 列 64hex + idx_messages_identity 索引项,~192 行超 12 页/47,376B)——截断不变量本身完好,坏的是页级余量的算术;custom-cap 用例改用 64KiB 的 inter-reset 累积预算(注释引用 #4390 行体积),close-converges 等其余断言维持一页余量不变。
|
||||
- **External summary: stop injecting the summary-writing rules into the conversation prompt (#4460).** With `compress.externalSummary.enabled`, the conversation model only selects ranges and the independent service writes the committed summary — yet every conversation request still carried `HOW TO COMPRESS`/`KEEP VERBATIM`/`DROP`/`PRIORITY` (~5.8K chars) plus the per-summary length budget, which the model's non-authoritative hint is never checked against. The conversation-side prompt now drops both while the chain is enabled (all five prompt assembly sites, function and hybrid builders, pack overrides included); philosophy, ACP tags, tools, summaries-in-context and marker integrity stay. The summary requests keep the full rules (`session.meta.summaryInstructions`), and classic mode is byte-identical. New tests/issue4460-external-summary-conversation-prompt.test.ts (7 cases, positive + negative).
|
||||
- **增量车道:拉取回执修复 ack 传输盲区 + 漂移回退取富侧(#4352/#4323)**。2026-10-22 事故双根因修复:① pi 的 after_provider_response 只在部分 provider 传输下暴露响应头,x-bili-applied-seq 丢失时 noteIncrementalAck 永不执行,后续每轮都整包 re-seed(sinceSeq=0 重发 21K 条历史)。现在 GET /__bili/plugin/turn?conversation=<id> 返回热 canonical 的 {appliedSeq, boundary}(boundary=末条 wire 消息哈希,冷重建诚实返回 null),pi 扩展在规划下一轮前拉取回执,仅在 boundary 证明 canonical 吸收了我方末条消息时采纳——绝不按 seq 前进盲目采纳(外来的全量重发也会推进 canonical);② #4323 多实例写同一目录时,漂移回退无条件吃旧信封,把索引里更新的折叠世代(26,971 refs/16 active)换成旧世代(11,849/12),覆盖与 canonical 失配→0 可压区间→preflight 8.29M 假性死局 502。现在漂移两侧按 mapped ref 数取富侧(平局信封赢,平局语义=原子整文件)。新增 tests/incremental-ack-pull.test.ts 3 例(响应头 ack 回归钉/拉取采纳/冷 boundary null 拒采纳)+ storage-full-flip 4b(陈旧信封让位新索引世代)。
|
||||
|
||||
@@ -1,348 +1 @@
|
||||
# 客户端集成详解
|
||||
|
||||
[README 快速上手](README.zh-CN.md#快速上手)里一行带不过来的客户端细节都在这里:各模式(启动器 / `/bili/` URL 前缀 / 原生插件)如何把流量接进代理、往哪儿写了什么、已知局限有哪些。只想知道「该敲哪条命令」的话,从 [README](README.zh-CN.md) 开始 —— 这个文件是给「行为不对劲、想知道为什么」的场景准备的。
|
||||
|
||||
---
|
||||
|
||||
|
||||
## dsh(deepseek-harness)
|
||||
|
||||
两条通道,同一个插件(#941):
|
||||
|
||||
- **启动器:** `bili dsh` 经 `--patch` overlay(`~/.dsh-bili/.bili-acp.patch.yml`)注入完整原生插件 —— 每个 profile 启动即注册 bili 工具,模型请求盖 `x-bili-plugin` + dsh 会话 id(plugin 模式),`/acp` 会话绑定。同一份 patch 同时禁用 dsh 原生自动压缩(宿主平面 `compaction-basic` → `auto: false`,web profile 的 preset 实例由 #3354 加载期 overlay 关闭);非 web profile 下手动 `/compact` 仍可用。
|
||||
- **Profile 安装(免启动器)——统一泳道(#966):** `bili plugin install dsh` 对每个已存在的 profile 执行 `dsh plugin --profile <name> add billion-context` —— pnpm 把包装进各 profile 自己的 `node_modules`,dsh 自动挂载包内 patch 层(`dsh.bundle.patch.yml`)。装哪个源取决于 bili 自身的安装形态(#925):npm 安装传注册表名,checkout/dev 构建传绝对路径(`link:` 依赖,本地改动实时生效)。旧版受管块(`# bili begin` / `# bili end`,#966 之前的安装所写)在安装与卸载时都会被剥离 —— 用户条目与注释保留,清空的文件还原占位 `[]`。先在每个 profile 里跑过一次 dsh 让目录存在。插件加载时自拉起代理(已有健康实例则附看,不重复拉;父进程 pid 看门狗),经全局 fetch 补丁把模型流量改写为 `<proxy>/bili/<上游URL>`,原样注册清单工具,并按工具就绪门控 plugin 模式头(第一轮走 wire 模式)。退出开关:`BILI_NATIVE_DSH=0`。卸载:`bili plugin remove dsh` 或 `dsh plugin --profile <name> remove billion-context` —— 两者走同一通道。经注册表安装要求 npm 上已发布含 `dsh.bundle.patch.yml` 的版本;请装 npm 形态 —— 直接填 GitHub 地址装到的是没有 `dist/` 的源码(入口悬空、dsh 静默跳过该 bundle;安装期守卫现在会响亮失败并给出正确装法,#2471)。若 add 后 dsh 启动即报 `billion-context/dsh` 的 `ERR_MODULE_NOT_FOUND`,说明 profile 从陈旧的包元数据缓存里解析到了不含 bundle 子路径导出的旧版本(#953)——固定版本重装:`dsh plugin --profile <name> add billion-context@latest`。
|
||||
- **桌面应用(Electron 宿主):** 同一插件也运行在 deepseek-harness **desktop** 应用内(经其应用内插件管理器安装)。此时 bootstrap 在应用进程内拉起代理:该进程的 `process.execPath` 是 Electron 二进制而非 Node,GUI 的 PATH 又不含常规安装目录 —— `resolveNodeRuntime`(#819/#1429)先探测众所周知的安装位置(`/opt/homebrew/bin`、`/usr/local/bin`、Volta 等),再回退到以纯 Node 方式运行应用自身二进制(`ELECTRON_RUN_AS_NODE=1`,强制注入子进程 env),于是无需 PATH 里有独立 Node 也能零配置压缩;设 `BILLION_CONTEXT_NODE` 可强制指定某个 Node(优先于两者)。#1429 之前该路径在 spawn 前抛错,所有会话静默降级为直连(不压缩),只能从 bili.log 里发现。
|
||||
- **自动更新保持各 profile 同步:** 刷新有两个触发器 —— 全局自更新完成后,以及**profile 自己的代理**在周期检查里发现注册表有新版本时(全局 bili 从不运行也一样刷新,#1196 —— 插件市场安装的用户往往根本没有全局安装)。两种触发器都扫描 `~/.dsh/profiles/*/package.json`,把注册表钉住的 `billion-context` 依赖刷新到目标版本(全局触发器刷到新全局版本,自触发刷到注册表最新),统一经 dsh 自己的 `plugin add` 通道,绝不在位覆盖 —— 加载的插件与代理从此不再漂移(#953);钉在本地源的 profile 不动。刷新是尽力而为,失败下个周期重试,绝不会让代理或更新本身失败。
|
||||
- **已报告:Profile 安装下部分传输零代理流量(#1158,调查中):** dsh `llm-pi-ai` 层的部分传输服务会话**从未有任何模型请求到达代理**(日志无 `processTurn`,调用 bili 工具返回 404 "no model request has arrived"),而同宿主的其他 provider 正常。根因仍在用运行时证据定性 —— 候选:传输层 fetch 形态(SDK 注入 fetch / 非全局 dispatcher)或宿主侧归属缺口导致流量未被 takeover gate 认领。检测:此类情况会打一次性 `[plugin] NO MODEL REQUESTS seen for conversation …` 告警,dsh 插件还会把归属 gate 放行的每个端点各记一条日志(每进程一次)。期间可靠规避:改用 `bili dsh` 启动 —— 启动器的 settings overlay 会把那些 provider 的 `baseURL` 重写为 `/bili/` URL,无论传输层使用哪种 fetch、归属状态如何,流量都必然过代理。
|
||||
- **Web profile 压缩(#1772,#3354 解决):** 当 profile 的 bundles 含 `@deepseek-ai/dsh-web-app` 时,真正运行的 `compaction-basic` 实例位于 agent preset(`preset-standard.config.plugins`)内部 —— dsh 的 patch 引擎只按 id 索引顶层条目与真 group(`group: true` 且 config 为数组)的子项,preset 内的嵌套行任何 patch 层都无法**按 id 直寻**。于是 bundle 里的 `auto: false` 落在 web-app 已禁用的宿主平面行上、什么都没改。#3354 起 bili 在**加载期**补上这一环:一个**常驻**的 bundle 条目 `bili-compaction-gate`(与 `bili-native` 并列的独立 cordis 条目,由同一组 patch 层挂载,因此 `bili-native` 被禁用或 kill-switch 时它仍然存活,#3662)注册一个 cordis `internal/config` overlay(移植自 deshark42/dsh-compaction-basic-disable,MIT),在 bili 持有该泳道期间把 preset 里的 `compaction-basic` 与 `command-compact` 行标记为 `disabled: true`;#4147 起该匹配是**结构化**的 —— 任何 entry 的 `config.plugins` 里嵌套了这两个包的行都会被禁用,自定义/本地 preset 与官方 preset 一视同仁(`dsh.bundle.patch.yml` 里的四个门控 id 只是对官方 roster 的顺序保险,不是覆盖边界);bundle patch 里的 preset 门控行让每个 Web preset 在注册前等待该 overlay 的服务。这些 profile 里原生自动压缩同样关闭(且 `/compact` 在那里不可用 —— 这是**预期行为而非 bug**(#4002):该泳道的压缩由 bili 接管,preset 的 compact 命令与自动压缩被有意一并撤下;按设计**没有**重新打开的开关(#3651/#3666),见 CONFIGURATION.md);ACP 压缩不受影响。启动的一次性 `[dsh-client]` 日志会列出 overlay 实际改写过的 entry(#3962),patch 行落空(如 roster 改名)无需翻宿主 loader 日志即可见。overlay 依赖 dsh 的内部钩子、对版本敏感 —— 若在新/旧 dsh 构建上仍见到 dsh 压缩 checkpoint 落地,回退到 #2474 配方:profile 层 patch(你 profile 自己的 `cordis.patch.yml`,在所有 bundle 之后生效)用同 id + **完整快照** `config` 整体覆盖 preset-standard —— 从 `dsh --profile <name> --dump-config` 抄下完整的 preset config,在其 `compaction-basic` 行下加 `config.auto: false`,把结果追加进 `cordis.patch.yml`。Config 替换是**整体语义**(片段会静默丢掉一切未重述的键 —— 不只是其他插件,连 preset 自己的 `id`/`order` 身份也会丢,可能使 roster 无法识别该 preset);`- insert:` 同 id 则是在末尾追加一条死行而非合并。dsh 升级 preset 后快照冻结 roster、需重抄一次。此类 profile 启动时插件打一条一次性 `[dsh-client]` 日志,说明两条路径。
|
||||
- **禁用与移除插件的区别(#3662):** #3662 之前,禁用 `bili-native`(dsh 插件管理器,或任何 patch 层里写 `disabled: true`)会把门控服务的**唯一**提供方一并移除,而 preset 行仍在等它 —— 四个 Web preset 永久 pending,新建/恢复会话全部报 `Unknown agent preset: standard`。现在该服务住在独立的常驻条目 `bili-compaction-gate` 里:禁用或 kill-switch(`BILLION_CONTEXT_PLUGIN=0`)`bili-native` 只是把泳道交还 dsh **原生行为** —— preset 正常注册、原生自动压缩恢复,bili 压缩则完全关闭。请勿禁用 `bili-compaction-gate` 本身 —— 那会重新造成「砖」。要彻底卸载:从 profile 的 `dsh.profile.bundles`(及其依赖)里移除 `billion-context` 后重启 —— 整个 patch 层消失,`compaction-basic` 回到原生默认 `auto: true`。若卡在 #3662 之前的版本且插件已被禁用:升级即自愈(patch 层按 bundles 里列出的包装载,与 `bili-native` 的启用状态无关);手动解砖是在 HOME 层 patch `$DSH_HOME/cordis.patch.yml`(`DSH_HOME` 未设时为 `~/.dsh/cordis.patch.yml`)追加四行 `- id: preset-standard` / `preset-ptc` / `preset-minimal` / `preset-cordis`,各配 `inject: null` —— 顶层键为整体替换,清掉 pending 锁。
|
||||
- **全局副本在加载期抢占 profile 副本(#2891):** dsh 解析 `dsh.profile.bundles` 里的裸包名 `billion-context` 时是 installation-anchor-first —— 先在自己的安装树(全局 npm root)里找,再找 profile 的 `node_modules`。因此只要机器上存在一份全局 `billion-context`,dsh 就加载**全局那份**,profile 里装的被静默忽略 —— 不崩溃、无日志。两者版本不一致时,实际运行的可能与 profile 声明的不同(例如 #1590 之前的全局没有 `dsh.client` web 面,设置页菜单凭空消失)。这一事实默认情况下处处不可见:`bili doctor` 现在会按 profile 逐一标记任何版本不一致的全局/本地对(#2891);用 `dsh --profile <name> --dump-config`(读该 bundle 的 `name:` 行)可核对 dsh 实际加载了哪份。
|
||||
|
||||
`bili dsh` 启动下插件**附看**(attach)启动器的代理(不二次拉起)。裸上游 URL 与 spawn 模式一样重写为 `<proxy>/bili/<url>`(回环代理目标永不被代理 env 拦截,等于直接绕开 MITM);已经路由的 `/bili/` 前缀请求原样放行、只盖章。已知局限:手动 `/compact` 没有 dsh 侧事件钩子,其边界交给内核的自然 ingest diff(自动压缩现已处处关闭 —— 宿主平面经 bundle patch,web profile 的 preset 经 #3354 加载期 overlay;见上方 Web profile 说明)。
|
||||
|
||||
**宿主侧上下文计量与模型实际视图按设计不一致(#2837):**plugin 模式下宿主本地持久会话日志有意保持无损 —— 完整未折叠历史会因前缀缓存与严格回显而重发(见 TECHNICAL-NOTES.md「两种压缩模式」)。因此宿主或其插件从该本地日志算出的任何计量,量的都是**未折叠的本地表面**,而不是下一次请求实际携带的量;压缩生效期间本地数字远高于真实输入属预期,不是压缩卡死。有效尺寸以代理为准:读 `/acp`(或 `GET /__bili/plugin/status` 的 `contextTokens`,来源见 `contextTokensSource`),不要本地重新推算。
|
||||
|
||||
## Kimi Code(Moonshot)
|
||||
|
||||
三种对齐模式:`bili kimi`(启动器,证书 MITM —— README 快速上手 方式 2)、`/bili/` URL 前缀,以及原生插件模式(`bili plugin install kimi`,#963)。Kimi Code v2 的插件体系是纯声明式的(`kimi.plugin.json`:MCP server、hooks、skills —— 没有进程内 JS 执行),所以 bili 无法像 pi/opencode/dsh 那样补丁客户端的 fetch 栈。取而代之,插件带两个小型 node 脚本,在客户端外围完成工作:
|
||||
|
||||
- **安装:** `bili plugin install kimi` 写 `$KIMI_CODE_HOME/plugins/managed/billion-context/kimi.plugin.json`,声明一个 stdio MCP server(`node <root>/dist/kimi/native-mcp.js`)加一个 `SessionStart` hook(`node <root>/dist/kimi/bootstrap-hook.js`,超时 30 s),并在 `$KIMI_CODE_HOME/plugins/installed.json` 注册该插件。安装器要求 `kimi --version` ≥ 2.0.0,低于此版本拒绝安装(启动器模式不受影响)。卸载:`bili plugin remove kimi`(managed 目录 + 注册表记录 + 配置还原)。
|
||||
- **每会话自举:** kimi 为每个会话把 MCP server 作为直接子进程拉起;启动时它先附上健康的现有代理(`BILLION_CONTEXT_PROXY`),否则在临时端口自拉起一个,然后用幂等的逐行受管块改写 `~/.kimi-code/config.toml` 的路由:自有 provider `[providers.bili]`(`base_url = http://127.0.0.1:<port>/bili/<上游>`,原样克隆当前 provider 的 `oauth` / `api_key` 引用)、`[models.bili-kimi]` 别名、顶层 `default_model` 重定向(原值记录在块内)。原文件一次性快照到 `config.toml.bili-bak`;每次写入都在 mkdir 锁文件下进行,块外的用户内容绝不被触碰。Kimi 的配置热重载会把变更应用到存活会话。`SessionStart` hook 机会性地跑同样的自举(仅 attach —— 永不拉起代理);它的非阻塞竞态在设计上被容忍:第一轮可能走直连/wire 模式,不变量是绝不把 `base_url` 指向死端口。
|
||||
- **Plugin 模式盖章:** 只有当 ACP 工具清单已在存活代理上验证通过后,块里才会写入 `custom_headers = { x-bili-plugin = "kimi" }` —— 此前流量走 wire 模式。由于 `custom_headers` 按 provider 静态生效,无法承载逐请求的窗口/模型头(会在模型切换后过期),所以 runtime-info 上报只在自举时发生(客户端配置里有模型 + 上下文窗口 + 最大输出就一并上报)。
|
||||
- **看门狗与生命周期:** MCP 子进程每 30 s 探测一次代理。attach 模式下永远等待(绝不碰用户自己的代理);spawn 模式下代理死亡则重新拉起并把路由改写到新 origin。恢复失败时移除受管块,让流量退回直连上游而不是打到死端口。会话结束时 kimi 杀掉 MCP 子进程,父进程 pid 看门狗随之收掉拉起的代理。多个并发 TUI 共享第一个拉起的代理;它消失后其余会话自动重新拉起并改路。
|
||||
- **已知局限:** 子代理会话各自得到独立的派生代理会话(kimi 不暴露稳定的会话 id;工具调用经每次调用的 `conversation_id` 参数绑定);kimi 的原生自动压缩**没有**被推后 —— ACP 压缩只是先触发,与启动器模式一致。退出开关:`BILI_NATIVE_KIMI=0`。
|
||||
- **模型/Provider 切换后流量离开代理(#2954):** 路由只覆盖自举时别名化的默认模型(`bili-kimi`)。`/model` 切换到任何其他模型或第三方 provider 会完全绕过 bili —— 无压缩、无统计 —— 直到之后的某个会话再次自举到别名上。这是单别名设计(#963)有意的爆炸半径取舍:代理挂掉时只有被别名的模型受影响,其余模型继续直连可用;全面接管多 provider 需要就地改写每个用户自有的 `[providers.*]` base_url,违反受管块「标记之外绝不触碰用户内容」的不变量。别名本身逐字继承源模型的 `capabilities` / `support_efforts` / `default_effort`(#2954),且 config.toml 里所有 `[models.*]` 的窗口在拉起时经 `BILI_LAUNCHER_MODEL_WINDOWS` 送达代理,任何流过的模型的逐请求窗口解析都保持准确。
|
||||
|
||||
## Gemini 系(Gemini CLI / iFlow CLI / Qwen Code / Antigravity)
|
||||
|
||||
面向 gemini-cli 架构家族的四个启动器(#1043 第一梯队)。四者中三个有 base-URL 环境变量钩子,一个没有:
|
||||
|
||||
- **`bili gemini`** —— Gemini CLI(`@google/gemini-cli`)。设置
|
||||
`GOOGLE_GEMINI_BASE_URL=<proxy>/bili/<upstream>`(默认上游
|
||||
`https://generativelanguage.googleapis.com`;如果你自己导出了
|
||||
`GOOGLE_GEMINI_BASE_URL`,该值会被中继经过代理)。客户端切换到
|
||||
`gateway` 认证模式,把 Google 原生 wire 请求直接发给回环代理 —— 无 MITM、
|
||||
无需装 CA,`~/.gemini` 零改动。代理本身原生支持这条 wire(模型名在 URL
|
||||
path 里)。局限:headless `-p` 运行需要已保存的认证选择(例如 settings 里
|
||||
`security.auth.selectedType = "gemini-api-key"` + `GEMINI_API_KEY`),因为
|
||||
gemini-cli 在非交互模式下拒绝纯环境变量推导的 gateway 认证;使用 OAuth
|
||||
个人登录(CodeAssist)的用户完全不走这条路 —— 该路径无视 base-URL 钩子。
|
||||
- **`bili iflow`** —— iFlow CLI(`@iflow-ai/iflow-cli`)。同样的模式,走
|
||||
`IFLOW_BASE_URL`(默认 `https://apis.iflow.cn/v1`,你设置过则中继);
|
||||
OpenAI chat-completions wire。
|
||||
- **`bili qwen`** —— Qwen Code(`QwenLM/qwen-code`)。这个 fork 移除了
|
||||
base-URL 钩子(`DASHSCOPE_PROXY_BASE_URL` 只是头部调优旋钮,不是路由),
|
||||
但它遵循标准代理环境变量,所以启动器走证书 MITM:`HTTPS_PROXY=<proxy>` +
|
||||
`NODE_EXTRA_CA_CERTS=<bili CA>`,并把默认模型主机(DashScope / Qwen 网关 /
|
||||
常见第三方端点)静态加白。自建中转主机用 `--mitm-domain <host>` 追加。
|
||||
尽力而为的路由 —— 日志里出现 `BLIND TUNNEL WARNING` 说明有主机没进白名单。
|
||||
- **`bili antigravity`** —— Google Antigravity(#2115)。启动器驱动官方 CLI
|
||||
二进制 **`agy`**(Gemini CLI 的继任者,Gemini CLI 已于 2026-06 退役;在
|
||||
`PATH` 或 `~/.local/bin/agy`,Windows 为 `%LOCALAPPDATA%\agy\bin`)。其模型
|
||||
通道在闭源 Go `language_server` 内部,该进程遵循一个**未公开的**
|
||||
`CLOUD_CODE_URL` 环境变量覆盖(已在 v2.19.1 二进制中验证:*"Overriding
|
||||
CloudCodeServerURL via CLOUD_CODE_URL environment variable"*),形态与
|
||||
gemini-cli 的 base-URL 钩子相同。启动器设置
|
||||
`CLOUD_CODE_URL=<proxy>/bili/<upstream>`(默认上游
|
||||
`https://daily-cloudcode-pa.googleapis.com` —— Antigravity 真实默认;裸
|
||||
`cloudcode-pa` 主机在 `/v1internal:*` 上 400,#3129;如果你自己导出了
|
||||
`CLOUD_CODE_URL`,该值会被中继经过代理)。无 MITM、无需装 CA。代理**按 path 识别 wire**:
|
||||
`:streamGenerateContent` / `:generateContent` / `:countTokens` 请求走
|
||||
Google 原生适配器,与 `bili gemini` 一样被压缩。若服务端改用 gRPC 方法
|
||||
path(`/google.internal.cloud.code.v1internal.CloudCode/*`),这些请求不被
|
||||
识别、原样透传不压缩 —— 属优雅降级,确认后可用按 lane 的 `protocol`
|
||||
声明(#1909)修复。若 Google 将来移除该环境钩子,退路是证书 MITM:
|
||||
language_server 遵循 `HTTPS_PROXY` 且不锁定证书,把
|
||||
`daily-cloudcode-pa.googleapis.com`(Antigravity 真实默认端点;裸
|
||||
`cloudcode-pa` 名称在 `/v1internal:*` 上 400,#3129)加进 `"mitm".domains`
|
||||
并信任 bili 根 CA 即可。桌面端与 IDE 扩展共用同一条 language_server 通道;启动器只驱动
|
||||
CLI —— 桌面用户可手动导出 `CLOUD_CODE_URL`,或直接用上面的 MITM 配方。
|
||||
|
||||
四者都没有 native 模式:均无环内工具注入接缝(gemini-cli 扩展只到自定义命令,
|
||||
fork 继承同一面;Antigravity 自带用户插件系统 —— `plugins/<name>/` 下的
|
||||
`plugin.json`、`hooks.json`、`mcp_config.json`、`skills/`、JS sidecar ——
|
||||
但每个面都只能追加:工具、提示词、UI、事件回调,没有任何一个能拦截或改写
|
||||
模型请求/响应流,那条流完全留在闭源 language_server 内部,所以 wire-only
|
||||
是 v1 的上限)。按设计保持 launcher-only。
|
||||
|
||||
## Hermes(Nous Research)
|
||||
|
||||
三种对齐模式:`bili hermes`(启动器,证书 MITM —— README 快速上手 方式 2)、`/bili/` URL 前缀、原生插件模式(`bili plugin install hermes`,#958)。hermes CLI agent 的插件 API 只有 Python(`desktop/plugin.js` SDK 属于另一个 Desktop app),所以原生插件是随 npm 包分发的一个纯标准库 Python 模块:
|
||||
|
||||
- **安装:** `bili plugin install hermes` 把 `plugin.yaml` + `__init__.py` 拷进 `~/.hermes/plugins/billion-context/`,写一个机器自管的 `bili.json` sidecar(指向全局 bili 安装的 `dist/index.js` + node 路径),并经 hermes 自己的通道启用插件(`hermes plugins enable billion-context` —— CLI 不在 PATH 上时改为打印同一条命令)。新开一个 hermes 会话生效。卸载:`bili plugin remove hermes`;全局更新后刷新:`bili plugin update hermes`。
|
||||
- **生命周期:** 加载时插件先附着到健康的运行中代理 —— #2905 起按泳道:本 hermes lane 的实例第一,其他已声明 lane 的实例绝不 attach(要搭车需在 `native.attachLanePriority` 里列出),8787 用户区守护是最后兜底 —— 否则在临时端口自拉起(声明 `lane: hermes`,别的泳道骑不上来;父进程 pid 看门狗在 hermes 退出时收掉它;并发启动走与启动器相同的 starting-marker 仲裁协议)。只有代理确认健康后,才用 `HTTPS_PROXY` / `https_proxy` + `SSL_CERT_FILE`(bili 组合 CA bundle —— 当前 hermes 经此解析环境信任;`HERMES_CA_BUNDLE` 保留给旧版本)把 hermes 的 httpx 栈指向它 —— **从不改动** `~/.hermes/config.yaml`。provider 的 https 域名从 hermes 配置读出并加入 MITM 白名单;其余域名与启动器模式一样盲隧道。拉不出健康代理时插件静默退场,流量直连(不压缩、无死端口)。
|
||||
- **Plugin 模式盖章:** `llm_request` 中间件打 `x-bili-plugin: hermes` + 会话 id(= hermes session id,gateway 多会话安全)+ 模型,已知后再加 `x-bili-plugin-max-output`,宿主 per-model 窗口已知时再加 `x-bili-plugin-context-window`(读自 `HERMES_HOME/context_length_cache.yaml`,键为 `<model>@<base_url>`;同模型多上游窗口不一致时宁缺毋猜,#3261)—— 且只在 ACP 工具已对着存活代理清单注册完之后;第一轮走 wire 模式。`pre_api_request` hook 捕获生效的 `max_tokens`,把 runtime-info(模型 + 最大输出 + 上下文窗口)推给代理。`compress` / `decompress` / `acp_status` 注册为真正的 hermes 工具,由代理既有的插件端点提供。
|
||||
- **已知局限:** 走 hermes Codex-wire 传输发出的请求可能丢掉逐请求头面,这类配置在该传输暴露头之前停留在 wire 模式。`BILLION_CONTEXT_PROXY` 已设置(启动器管着代理)或定义了 `BILI_PROVIDER_REWRITES` 时插件整体退场。退出开关:`BILI_NATIVE_HERMES=0`。
|
||||
|
||||
## ZCode(Z.ai / bigmodel coding plan)
|
||||
|
||||
三种对齐模式:`/bili/` URL 前缀、GUI「设置 → 网络」证书 MITM(HTTP 代理 + 根 CA 路径)、原生插件模式(`bili plugin install zcode`,#1145)。ZCode 的扩展面是 Claude-Code 形状但纯声明式:`~/.zcode/cli/config.json` 里的用户级 hooks 与 stdio MCP server,没有进程内 JS 接缝。所以原生通道随包带两个小 node 脚本,在客户端外围干活:
|
||||
|
||||
- **安装:** `bili plugin install zcode` 写 `~/.zcode/cli/config.json`:置 `hooks.enabled = true`、追加一条 `SessionStart` process hook(`node <root>/dist/zcode/bootstrap-hook.js`)、注册 stdio MCP server `mcp.servers.bili`(`node <root>/dist/zcode/mcp-entry.js`)。已存在的用户自有 `mcp.servers.bili` 条目**绝不覆盖** —— 安装器会响亮地拒绝。安装时不冻结任何 URL;路由按会话发生。卸载:`bili plugin remove zcode`(只剥离 bili 自己的条目、由 bili 启用的 `hooks.enabled` 予以还原、provider store 从快照恢复)。
|
||||
- **卸载后的已开会话(#2155):**`bili plugin remove zcode` 无法触及已开着的客户端窗口 —— 它们的 MCP 子进程已死,但代理侧的会话绑定(session metadata)仍在。这类僵尸会话在连续 5 轮“有 nudge、无插件头、线上无 bili 工具、零压缩”后被检测到,随即**自愈降级为代理模式** —— ACP 工具改由代理线上回注、压缩重新由代理接管(nudge 保留)。若线上注入不可用(`compress.injectTool=false`)则改为静默 nudge,直到出现一次压缩缩减自动解除。插件头重现(客户端重启/重装)即在同一请求内恢复 plugin 模式。remove 命令在近 10 分钟内见过活跃会话时会打印提示;web UI 会为这类会话挂“自愈”徽标。
|
||||
- **每会话自举:** 每个 ZCode 会话把 MCP 子进程作为直接子进程拉起;启动时附着到健康代理(`BILLION_CONTEXT_PROXY`)或在临时端口自拉起,然后在 mkdir 锁文件下对生效的 provider store 做幂等 JSON 手术:每个可路由 provider 条目的 `baseURL` 变为 `http://127.0.0.1:<port>/bili/<上游>`(你设的自定义 baseURL 原样保留在包装之内)。两代 store 都处理:legacy `~/.zcode/v2/config.json`(`provider.<id>.options.baseURL`)与 v3.14+ personal store `~/.zcode/v2/provider_config.json`(`config.providerConfigRules.providerRules[].config.api.baseUrl`)—— 两者并存时以新 store 为准(其中哪些条目路由、哪些被跳过见下方路由范围)。原始文件按每次用户编辑快照到 `<file>.bili-bak`(快照永远反映你最后一次真实状态,绝不记录 bili 自己的写入);其余所有键逐字节保留。旧世代客户端在启动时加载 provider 配置 —— 安装后重启一次 ZCode;新版构建可在会话中途感知路由变化(约 1 s 轮询)。`SessionStart` hook 机会性地跑同一套自举(仅附着 —— 绝不 spawn);它的非阻塞竞态被设计为可容忍:第一轮可以走 wire 模式,不变量是 `baseURL` 永不指向死端口。
|
||||
- **Plugin 模式盖章:** MCP 子进程对着存活代理清单核验 ACP 工具列表之后,才给路由条目加 `headers["x-bili-plugin"] = "zcode"` —— 此前流量走 wire 模式。工具调用经每次调用的 `conversation_id` 参数绑定(#760)。
|
||||
- **清洗什么、绝不动什么(统一 ACP 不变量):** 模型正文中 bili 渲染标签回声 / marker 行 / 退化残骸可在传输中被剥离;**思考通道**(anthropic `thinking`、google `thought`、openai `reasoning_content`/`reasoning`、responses reasoning summaries)、**工具调用参数**(模型写往文件的内容)与**用户消息**逐字节原样透传。
|
||||
- **路由范围(#1622):** 原生模式包装**每一个**有可用 http(s) `baseURL` 的 provider 条目 —— 与进程内原生(pi/dsh)的「所有 provider 都吃压缩」语义一致 —— 而不是只包 bigmodel coding-plan 账号。无法安全包装的条目会被跳过并记录原因,而非静默丢弃:
|
||||
- **客户端签名账号(#1621):** v3.14+ personal store 上的 coding-plan 账号保持直连(见已知局限);其余 provider 照常路由。
|
||||
- **环回目标(#809):** http 环回 `baseURL`(localhost / 127.x.x.x / ::1)永不二次代理 —— 包装它会把 bili 叠在自己或你自己的本地中继上。
|
||||
- **`direct` 豁免:** `providers` 表(以上游 URL 为键,见 CONFIGURATION.zh-CN.md)里声明 `"direct": true` 的路由保持直连 —— 任何 lane 都能遵守的同一套豁免机制。
|
||||
通道把代理拉在自管端口区(#1660):基准口 `18787`,每 lane 粘性记录(自动跟随历史上的 +1 阶梯漂移),碰撞由子进程 +1 阶梯解决,漂移时共享 store 改写到存活 origin —— 即使没有交接,包装也能跨会话重启存活。`BILI_ZCODE_PORT` 钉死一个确切端口(严格模式:占用者被大声拒绝,不跳口)。`BILI_ZCODE_ROUTE`(`plans`/`none`)是兼容逃生舱;`BILI_ZCODE_SIGNING_FIXED=1` 在 ZCode 发布签名修复后关掉 #1621 跳过。
|
||||
- **看门狗与生命周期:** MCP 子进程每 30 s 探测一次代理。attach 模式下永远等待(绝不碰用户自己的代理);spawn 模式下代理死亡则重新拉起并把路由改写到新 origin。恢复失败时移除受管改写,让流量退回直连上游而不是打到死端口。会话结束时 ZCode 杀掉 MCP 子进程,父进程 pid 看门狗随之收掉拉起的代理;MCP 子进程退出前(SIGTERM/SIGINT/正常退出)在锁下交接:若共享 provider store 仍指向它自己的代理,优先改写到另一个存活兼容实例,没有则移除受管改写退回直连(#1623)——实例死后共享配置不留死端口。看门狗每个 tick 同时检查共享 store:若残留着其他实例的死端口(硬杀场景,上述交接没跑成——如 Windows TerminateProcess 跳过 JS handler),接管修复(优先改到存活实例,否则回退直连);只在 store 指向死端口时动手,绝不从存活实例手里抢路由。多个并发会话共享第一个拉起的代理;它消失后其余会话自动重新拉起并改路。边界:ZCode 按会话缓存 provider baseURL,上述修复只对「之后的新读取」(新会话/新查询)生效,在途会话仍会重试缓存的旧端口直到重读;要结构性规避,把 `BILLION_CONTEXT_PROXY` 钉到一个常驻代理(`bili start`)让所有会话 attach 上去(attach 模式绝不碰用户自己的代理)。
|
||||
- **已知局限:** ZCode 的反欺诈指纹(#661)作用于 `zcode.z.ai` 登录流量的 MITM 重建 body —— 原生模式不碰那个面(模型流量走 provider store,不走 GUI 代理);若你同时使用 GUI 代理/MITM 配置,请保留 `"mitm://zcode.z.ai": { "passthrough": true }` 路由。v3.14+ 构建上,coding-plan 账号的 ClientRequestSigningV4 在模型创建阶段拒绝非 HTTPS origin,且其握手路径只从 origin 派生(丢弃任何 /bili/ 前缀),因此 /bili/ 包装的 baseURL 会以 "Client signing handshake requires HTTPS." 失败(#1621)。该冲突硬编码在 ZCode 侧,原生模式把这些账号**逐条跳过** —— 记录原因、这些账号保持直连;在这些账号上请用 GUI 证书 MITM 配置获得压缩能力,直到 ZCode 发布签名修复,届时设 `BILI_ZCODE_SIGNING_FIXED=1` 即可恢复路由。默认 `route:"all"` 下只有这些账号被跳过 —— store 上其余 provider 继续路由;整体退场(路由全关)只在 `route:"plans"` 下发生,因为那里 plan 账号本身就是签名账号。pre-3.14 legacy-store 客户端不受影响。`BILLION_CONTEXT_PROXY` 已设置(attach 模式管着代理)或定义了 `BILI_PROVIDER_REWRITES` 时插件整体退场。退出开关:`BILI_NATIVE_ZCODE=0`。
|
||||
|
||||
## Codex(OpenAI Codex CLI)
|
||||
|
||||
**模型目录临时断网(#3993)。** 经 Bili 转发的带认证 `GET https://chatgpt.com/backend-api/codex/models` 请求,在网络故障或 HTTP 500/502/503/504 时可使用最近一次完整有效的目录,避免临时发现失败导致 Codex 丢失已知窗口和工具能力。私有缓存位于既有 XDG 缓存目录的 `codex-model-catalog-v1` 子目录,按完整 URL/客户端版本以及认证、账号、组织、项目的指纹隔离,不保存原始凭证;每份最多 1 MiB、最多 16 份、最长六小时。在线发现优先,离线命中不会延长有效期;有可用缓存时,网络及响应体等待上限为四秒。客户端取消、401/403、其他明确错误和无效/空目录不会转成缓存成功。冷缓存、过期或凭证变化仍需要在线发现成功。离线返回不清除上游熔断,也不代表模型推理端点可达。不修改推理载荷、压缩模式或已配置上下文上限。
|
||||
|
||||
**窗口对齐。** 客户端 plugin/runtime 上报及启动器传递的窗口优先于发布时的 Codex 模型表。没有上报时,本机代理只读其 `CODEX_HOME`(默认 `~/.codex`)下的 `models_cache.json` 和基础 `config.toml`,将 `model_context_window` 限制在匹配模型的 `max_context_window` 内,再应用 `effective_context_window_percent`(Codex 默认 95);后续请求会跟随缓存更新。元数据缺失、不可读或无效时,保留内置表及未知模型 272K 的既有回退。远程代理或其他客户端 profile 应通过现有启动器/runtime 机制传递实际窗口,或设置既有的 `compress.modelContextLimit`;代理本机缓存不能证明另一台机器的配置。输出预留仍正常生效。
|
||||
|
||||
Codex 是唯一一个插件安装无法自给自足的客户端。接缝矩阵可以解释:claude 有 SessionStart hook + 受管 settings 块,zcode 有可改写 `baseURL` 的 provider store —— codex 两者都没有。它的模型流量只能经环境变量路由(`HTTPS_PROXY` / `SSL_CERT_FILE` —— `bili codex` 正是这么做的);默认 ChatGPT-登录 provider 没有可改写的配置缝,managed `model_providers` 块会强制 `env_key` API-key 认证、**废掉订阅登录**;而 MCP 子进程无法向父进程注入 env,所以插件永远路由不了 codex 本体流量。三种姿势:
|
||||
|
||||
| 姿势 | 你能得到什么 |
|
||||
|---|---|
|
||||
| `bili codex`(启动器) | 全功能零配置:自管 lane 代理(#1660 端口区,粘性口)+ 注入 codex 的证书 MITM env —— 工具与压缩兼得 |
|
||||
| `bili plugin install codex` + 在跑的 bili + 自行导出 `HTTPS_PROXY` | 自己管 env 的 power user:工具 + 压缩 |
|
||||
| 只装 `bili plugin install codex` | codex 里出现四个工具但没有对话被代理、无话可操作;全不可达时 `tools/list` 报 -32003(`bili proxy unreachable … — start bili or set BILI_MCP_PROXY`) |
|
||||
|
||||
**并发会话(#3203)。** 同一项目目录、同一 `CODEX_HOME` 下可以同时跑多个 `bili codex`:每次启动各取一个独立的每会话 overlay 槽位(`<CODEX_HOME>-bili-s<N>`,池上限 16)和各自的 lane 代理,路由、MCP 会话绑定、压缩状态互不串线。共享状态默认(codex ≥ 0.147.0)下,两个会话的历史都落在真实 home 的同一个活库上,退出顺序不影响保留 —— 见 CONFIGURATION.md 的 `BILI_CODEX_STATE_MODE`。旧版二进制或 `BILI_CODEX_STATE_MODE=legacy` 保持每 home 一个独占 overlay:第二个并发启动会被 `BILI_OVERLAY_BUSY` 拒绝。
|
||||
|
||||
|
||||
安装写入 `~/.codex/config.toml` 单个 `[mcp_servers.bili]` 块(command = node,args = dist/mcp.js)。#1660 去掉了安装时烘焙 origin(#403:烘焙的 URL 在漂移/重启后变成死端口,工具永远指向它);shell 在会话启动时解析代理 —— env `BILI_MCP_PROXY` > 活实例登记(任一 lane 的代理,或 `bili start` 守护)> 8787 用户区默认 —— 漂移或重启后绝不残留死 URL,shell 直接附着到活着的那个。会话绑定是 headless 的:启动器在 spawn 时传 `BILI_CONVERSATION_ID`,插件 shell 否则绑定下一个新会话;逐调用的 `conversation_id` 覆盖与其他客户端一致(#760)。Codex ≥0.160 还在每次 `tools/call` 的 `_meta.threadId` 里盖上真实 thread id;shell 按调用消费(严格校验、绝不写回 spawn 时的全局绑定),优先级高于过期的 `BILI_CONVERSATION_ID` 残留与模型抄写的 `conversation_id`(#2024)。
|
||||
|
||||
**Responses 原生链式(一个坑)。** bili 靠重放完整 `input` 来压缩,因此无法跟随 OpenAI 原生的 `previous_response_id` 链式续传:只带增量的续传请求会在上游丢失之前的轮次,却仍返回 200。对 codex 而言今天这不是问题 —— 观察到的构建都发 `store:false` 且从不设置 `previous_response_id`(是观察不是证明;E2E 未覆盖该形态)。若你把走原生链式的 Responses 客户端指向 bili,要么重发完整 input/output 历史,要么设 `ACP_KEEP_RESPONSE_ID=1`;bili 剥掉非空 `previous_response_id` 时现在会记一条 `warn`(#1954)。完整链式支持跟踪在 #1973。见[官方迁移指南](https://developers.openai.com/api/docs/guides/migrate-to-responses)。
|
||||
|
||||
### 运行模式:`bili codex` 钉死 embedded(#1867)
|
||||
|
||||
自 ~0.156 起,Codex 可以附着到(或自动拉起)一台机器全局共享的后台 server,其模型流量用的是 **daemon 启动时**存在的环境变量,而不是会话启动时的。启动器的代理是会话级的(端口随进程消亡),所以长寿 daemon 没法安全地经它路由:若 codex 先于 bili env 启动,之后的 `bili codex` 会话会静默附着上去、**完全绕过压缩**;若 bili 先启动,幸存的 daemon 则一直指向死端口。因此启动器显式传 `--no-daemon` —— 先探测 `codex --help` 是否有该 flag(旧版本二进制原样启动),且仅当用户未自行钉死模式(`--no-daemon` 或 `--remote`)时。结果:确定性的 embedded 运行,无逐次启动的回退警告,无静默绕过。#321 的预算 `-c` 参数原样保留(embedded 模式同等生效)。想要共享后台 server 的话,直接跑原生 `codex` —— 没有压缩,但工具仍可通过 `bili plugin install codex` 使用。
|
||||
|
||||
### Windows 启动路径:用户 argv 不再重新进入 cmd.exe(#2196)
|
||||
|
||||
Windows 上默认 npm 安装把 `codex.cmd` shim 放上 PATH,它的 `%*` 转发会让每个用户参数再经 **cmd.exe 行解析器**解析一遍——该解析器没有任何转义机制:嵌入双引号拆词(`Please say "hello world" exactly` 到达时变成四个参数)、`%VAR%` 被展开、`&|<>^()` 成为命令操作符、空参数消失。普通带空格提示词恰好能幸存,所以 #679 的空格截断修复没有暴露它。#2196 让启动器拒绝把用户 argv 喂进这个解析器:
|
||||
|
||||
- **解析顺序(win32 专属):** 每个 PATH 目录内原生 `codex.exe` 优先于 `codex.cmd`/`codex.bat`(最早目录仍整体优先);`.cmd`/`.bat` 命中若位于可信 npm 布局旁——`<dir>/node_modules/@openai/codex`,package.json name 为 `@openai/codex`、有可解析的 `"codex"` bin 条目、且 shim 文本引用该包(放在无关树旁的手写 `codex.cmd` 不得劫持启动)——则升级为 `node <官方 bin/codex.js>`。Node 下运行官方 wrapper 与 shim 行为完全一致——vendor 二进制查找、env 初始化、信号转发——而 Node 自己的 CreateProcess argv 编码逐字无损携带每个参数。未识别布局(yarn-classic `.bin` 树、无本地链接的 pnpm store shim……)保留旧 cmd 路径并遵循下述契约。
|
||||
- **透传契约:** 其余 cmd 包装启动——任何客户端的 `.cmd`/`.bat`/无扩展名二进制,加上 dsh-channel spawn——只接受行解析器能逐字携带的 argv;其余(嵌入引号、`%VAR%`、元字符、空参数、换行、奇数尾反斜杠)在**任何进程启动之前**以可操作的错误明确失败,而不是损坏到达或执行非预期命令。直接 spawn 的 `.exe` 不受影响:Node 自身无损编码其 argv。
|
||||
- **绕行 / power-user 旋钮:** `BILI_CLIENT_BIN=<path>` 仍最高优先——指向真实 `codex.exe`(或经 node 运行的脚本入口)即可完全绕开 shim。
|
||||
|
||||
已在 windows-latest CI 上对真实全局 `@openai/codex` 安装验证(`tests/win-cmd-argv.test.ts`,`ci-windows-codex.yml` 硬门禁):完整语料——空参数、普通空格、嵌入引号、TOML `-c` 值、JSON、Unicode、尾反斜杠、`%COMSPEC%`、`!VAR!`、`&|<>^()`——逐项与调用方数组相等地到达子进程。
|
||||
|
||||
### Composer 预测(Codex Desktop):自定义 provider 的线程没有资格(#3408)
|
||||
|
||||
Codex Desktop 的 Composer 预测功能有一道**客户端资格门槛**,在任何预测请求能到达 billion-context 之前执行:它检查被恢复源线程的**实际 provider**,要求是内置 `openai` provider —— 其他任何 provider 都会选中 `unsupported_provider`,客户端直接返回、不生成预测(对 Desktop 26.1013.3656.0 的静态检查,#3408)。门槛读的是*线程*的 provider,而不是当前全局默认值:预测路径以特殊预测模式 fork 源线程,该调用不提供独立的预测 provider,所以改全局默认也不会让既有线程重新获得资格。后果:
|
||||
|
||||
- **自定义 provider 的线程永远不显示预测** —— 这是客户端的设计,不是 bili 缺陷。预测请求根本到不了代理,bili 侧没有可修可配的东西;看不到预测相关的网关流量是预期现象,不是请求被丢的证据。
|
||||
- **保 provider 的传输在机制上保住资格。** 证书 MITM 路由(`bili codex` 启动器注入的 `HTTPS_PROXY` + `SSL_CERT_FILE`)在 provider 层之下拦截:codex 自己的配置与 provider 选择原样不动,线程保留内置 `openai` provider 身份与官方 ChatGPT 认证 —— 正是门槛读取的东西。Desktop 构建上的运行时确认仍待完成(尚无配对 A/B);若你能在该传输下于 Desktop 上证实或证伪预测行为,请到 #3408 回报。
|
||||
- **没有任何受支持的配置能为自定义 provider 线程恢复预测。** 任何走自定义 `model_providers` 条目的路由 —— API-key 认证、第三方一键安装在内 —— 按构造都落在门槛的不合格一侧(这类条目同时废掉订阅登录,见上文)。把自定义 provider 改名冒充 `openai`,或打补丁修改客户端资格检查,不受支持,也不会被文档化为绕行方案。
|
||||
|
||||
经验法则:要预测 → 留在内置 OpenAI provider 路由上;要自定义 provider → 接受这些线程里不会出现预测。
|
||||
|
||||
## Pi(pi.dev coding agent)
|
||||
|
||||
Pi 有完整原生模式(`bili plugin install pi`,README 快速上手方案 1);这一节只讲一行表格装不下的内容——**原生拦截实际覆盖哪些模型传输**。pi 是唯一把 WebSocket 模型流量带进环路的宿主。
|
||||
|
||||
**子代理配置(#2230)。** 内置 `acp_delegate` 面(三个 delegate 工具、角色、fleet 检查器——由 `bili pi` 经内嵌扩展接线)配置在 bili 自己的配置文件:`~/.config/billion-context/billion-context.json` 的 `pi.subagents` 段(布尔简写 `"pi": {"subagents": false}` 可整体关闭)。`~/.pi/acp.json` 的四键(`delegate` / `delegatePrompt` / `displayUsage` / `debug`)是已废弃的回退源——仅当段缺失时读取,段存在后完全忽略。完整字段表与 `PI_ACP_DELEGATE_*` 环境变量见 CONFIGURATION.zh-CN.md 的 [`pi`](CONFIGURATION.zh-CN.md#pi) 段。
|
||||
|
||||
**路由机制。** pi 扩展自行拉起(或附着)代理并进程内 patch `globalThis.fetch`:所有模型 API 的 HTTP 请求被改写到 `<proxy>/bili/<upstream-url>`,扩展经 pi 的 `before_provider_headers` 事件盖 `x-bili-plugin*` 头。所有 HTTP 系 provider(Anthropic、OpenAI chat/completions/responses、Gemini、Mistral、OpenRouter、Azure、自定义中转……)走这条路,得到具名 plugin-mode 会话。
|
||||
|
||||
**WebSocket 覆盖(#2073,#2111 实现)。** WebSocket 连接从不经过 `globalThis.fetch`,所以原生扩展在加载时(首个模型连接之前)同时包装 `globalThis.WebSocket`(pi 的 Node 分支每次调用都读全局,Bun 分支首次调用时缓存子类——两个运行时的安装时序都因此安全)。只重写受支持的 Codex Responses 模型连接——其余 WebSocket(devtools、第三方库、已路由 URL)原样通过:
|
||||
|
||||
| Provider / 传输 | 状态 |
|
||||
|---|---|
|
||||
| 全部 HTTP provider | ✅ 覆盖 —— 具名 plugin-mode 会话 |
|
||||
| `openai-codex-responses`(ChatGPT backend-api),`transport: "sse"` | ✅ 覆盖 —— 与任何 HTTP provider 无异 |
|
||||
| `openai-codex-responses`,`transport: "auto"`(默认)/ `"websocket"` / `"websocket-cached"` | ✅ 覆盖(#2111)—— 构造器 URL 被重写为 `<proxy-ws>/bili/<https-upstream>`(例:`wss://chatgpt.com/backend-api/codex/responses` → `ws://127.0.0.1:<port>/bili/https://chatgpt.com/backend-api/codex/responses`)。构造器参数、子协议、请求头全部保留,pi 在 SSE 上发的同一个 `session-id` 随升级握手到达,会话标识跨传输字节一致;子代理各用自己的会话 ID。`previous_response_id` 增量续传在该车道可用(代理先展开 delta 再进管线,回上游前再优化回 delta) |
|
||||
| AWS Bedrock(`bedrock-converse-stream`) | ❌ Bedrock 流量全部走 WS、无 transport 选项、升级握手不带自定义头 —— 仅靠 URL 拦截无法覆盖,需要代理侧专门的 WS codec(不在 #2111 范围,归入 #2073 另行跟踪) |
|
||||
|
||||
拦截带来一个拓扑后果:pi 的客户端握手现在指向本地代理(总是成功),因此*上游*拒绝 WS 握手会以流中传输失败的形式暴露,而不再触发 pi 的同轮 SSE 回退——该回退只在客户端握手失败时触发。下面的显式 `sse` 车道仍是确定性绕行手段。
|
||||
|
||||
**Codex provider 的绕行办法。** 在 pi 配置里强制 SSE 车道(`~/.pi/agent/settings.json`;项目 `.pi/settings.json` 可覆盖):
|
||||
|
||||
```json
|
||||
{ "transport": "sse" }
|
||||
```
|
||||
|
||||
默认值 `"auto"` 先试 WS、握手失败才回退 SSE;旧布尔键 `"websockets": false` 会自动迁移。该键全局生效,但只有支持多传输的 provider(目前是 codex provider)消费它,纯 HTTP provider 不受影响。Windows + Pi 1.0.2 实机验证(#2063 owner 复现):显式 `sse` 携带正确会话 ID 进入 bili。
|
||||
|
||||
该车道已经过端到端实证(`tests/e2e/e2e-pi-codex-ws.test.ts`,真实 pi 对确定性 mock 上游经真实代理):显式 websocket 与 auto 路由、升级握手上 stamp 与 `session-id` == 会话 ID 一致、compress/decompress 往返并反映到后续请求、`previous_response_id` 展开、上游拒绝行为、显式 sse 回归守卫,以及两个并发子代理式会话共享一个代理互不串扰。
|
||||
|
||||
### 子代理(pi-subagents)— native 安装覆盖(#2185)
|
||||
|
||||
pi-subagents(pi.dev 上的包)为前台/后台子代理运行派生**子会话**。#2185 之前,native 安装(`bili plugin install pi` / `pi install npm:billion-context`)下 bili 扩展并不能可靠地加载进这些子会话:
|
||||
|
||||
- **前台 child** 在进程内运行且 ambient 扩展发现关闭(`noExtensions: true`)→ bili 扩展根本不加载;其流量只是借父进程的全局 fetch patch 到达代理,因此每个 child 被记成**匿名 proxy 模式 `pfa-*` 会话**:压缩成立,但没有具名 `x-bili-plugin-conversation` 身份、没有父会话血统,ACP 工具只以代理侧 wire 注入的形式存在;
|
||||
- **后台 async run** 派生独立 runner,其 child *可能*经 ambient 发现加载扩展——默认配置下靠运气生效,而 agent 定义一旦显式设置 `extensions`(哪怕是 `[]`)或 `denyExtensions`,或遇到 pi-subagents 版本漂移 / npm store 同步问题,就**静默回归直连**(代理侧零可见性)。
|
||||
|
||||
**修法。** pi 扩展在 session_start 时向 pi-subagents 的全局 required-child-extension registry 自注册(对 `globalThis[Symbol.for("pi-subagents.required-child-extensions.v1")]` 做特征探测)。注册条目使 bili 成为**该父会话派生的每个 child 的必需扩展**;必需扩展经 `additionalExtensionPaths` 注入,pi 会把它载入 `cliEnabledExtensions` 桶——**即使 `noExtensions: true` 也加载**——所以下面每一格都是确定性加载。注册按父会话粒度,session_shutdown 时释放;同会话已有条目时让位(先写者胜)。刻意**不设置** `requireForAllRunners`:非 pi 的 runner 放置保持现状,而不是被拒绝。registry 不存在或形状不符(新旧 pi-subagents 版本漂移)时,扩展降级回修复前行为并记一次日志。kill switch `BILLION_CONTEXT_PLUGIN=0` / `BILI_NATIVE_PI=0` 同样会抑制注册。不引入任何新配置面。
|
||||
|
||||
修复后矩阵(pi 0.83.6 + pi-subagents 0.76.0 实机验证,HTTP 传输;WS 行依据 #2073 记录,无实机格):
|
||||
|
||||
| 格子 | 修复前 | 修复后 |
|
||||
|---|---|---|
|
||||
| native × 前台 × 默认配置 | 匿名 `pfa-*` proxy 模式;ACP 工具仅靠代理 wire 注入 | **具名 child-sid plugin 模式会话**;ACP 工具首个请求起本地注册;压缩记在 child 自己的 id 下 |
|
||||
| native × 后台 × 默认配置 | ambient 运气——settings packages 恰好加载时才是具名 plugin 模式 | 同上,但现在是确定性的(child launch-resolved extensions 里 `required: ["bili"]`) |
|
||||
| native × 后台 × agent 定义 `extensions: []` / `denyExtensions` | **静默直连**——代理零可见性、无压缩 | 确定性必需路径加载;具名 plugin 会话。(若运行时能力上限硬性拒绝扩展,pi-subagents 0.76.0 会让 child 启动大声失败——fail-fast 而非静默) |
|
||||
| launcher 模式(`bili pi`)× 后台 | child 继承 provider rewrite(#535),但 bili 加载同样靠 ambient 运气 | 注册生效(刻意**不受** `BILI_PROVIDER_REWRITES` 门控);父与子均为具名会话,经继承的 rewrite 路由 |
|
||||
| 任意 × 纯 WS 传输 | 不在范围——见上方 WS 缺口 | 不变:客户端侧 WS 拦截仍 owner-gated(#2073) |
|
||||
|
||||
值得知道的注意事项:
|
||||
|
||||
- **限制性 `tools:` 白名单的角色会自动拿回 ACP 通道(#2268)。** frontmatter `tools:` 列表未包含任何 ACP 工具名的角色——全部 7 个内置角色都是如此(如 `delegate` 只列 `read,grep,find,ls,bash,edit,write,contact_supervisor`)——在 #2185 具名 plugin 化之后**不再**丢失交互式压缩。bili 按请求检测这类 child(pi-subagents 会在每个子会话的 system prompt 打上完整的 `<active_agent name="…">` 标记;检测只针对 system prompt 载体,历史消息中仅引用该标记的主会话不受影响(#2694);门控还要求请求的 tools 数组——含 namespace 包装声明——未暴露任何 bili 可注入的工具名),并为其走 **proxy-style 压缩通道**:wire 注入 ACP 工具 + nudge、服务端执行、`acp_summary` carrier——同时保留 #2185 的具名 plugin 会话身份。无需任何配置改动;角色的原白名单在 wire 上原样保留,白名单中途变更会在下一个请求自愈。范围仅限 nicobailon/pi-subagents 的 child(标记是它的),其他 plugin host 不受影响。若上游日后移除该标记,这些角色会退回 #2268 之前的行为(具名会话、无本地 ACP 工具)。
|
||||
- 暴露**任一** ACP/bili 可注入名的角色保持纯 plugin 模式(重复的工具声明会被上游拒绝),因此**部分授予不受支持**——要么一个都不给,要么全给(`compress,decompress,search_context,acp_status[,acp_cache]`)。
|
||||
- 想让某个特定角色用本地注册(plugin-carrier)的工具?保留手动授权:省略 `tools:` 字段或在其中补上 ACP 工具名即可。
|
||||
- **后台 child 存在一个请求的注册竞争**(ACP 工具从第二个请求起出现),所有模式下均为既有现象。
|
||||
- **行为变更披露:** 前台 child 从匿名 proxy 模式(`pfa-*`)升级为具名 plugin 模式(child 会话 id + 父会话血统)。信息严格更多,但任何以 `pfa-*` 身份做键的工具将看到不同的 id。
|
||||
|
||||
## 收养未列表的客户端(任何模型 baseURL 可配的客户端)(#2340)
|
||||
|
||||
凡是**模型端点可以自己编辑、且用 API key 认证**(而非账号登录)的客户端,今天改一行就能上压缩——无需启动器、无需开发:在 baseURL 前加代理 origin + `/bili/`(`http://127.0.0.1:8787/bili/https://api.example.com/v1`),API key 原样保留,并让代理常驻(`bili start`)。得到的是完整纯代理待遇:压缩 + wire 级工具注入。细节与示例见 [CONFIGURATION.zh-CN.md → `/bili/` 前缀](CONFIGURATION.zh-CN.md#bili-前缀api-key-客户端)。
|
||||
|
||||
已核实的入口(社区维护清单——机制本身是通用的):
|
||||
|
||||
| 客户端 | baseURL 所在 |
|
||||
|---|---|
|
||||
| **Cline / Roo Code / Kilo Code**(VS Code) | provider 设置 —— "OpenAI Compatible" Base URL,或 Anthropic provider 的 base URL |
|
||||
| **Continue** | `~/.continue/config.yaml` —— 各模型的 `apiBase` |
|
||||
| **OpenHands** | `llm.base_url`(配置或 env) |
|
||||
| **Zed** | `settings.json` —— `language_models.openai_compatible.api_url` |
|
||||
| **Void** | 自定义 OpenAI 兼容端点设置 |
|
||||
| **Cursor**(单模型通道) | Settings → Models → OpenAI API key → **Override Base URL** |
|
||||
| **Warp** | 自定义模型 base URL 设置 |
|
||||
|
||||
注意:
|
||||
|
||||
- **Crush** 已有启动器车道——直接用 `bili crush`(配置零改动,HTTPS 域自动 MITM)。
|
||||
- **Zed** 也已有启动器车道——直接用 `bili zed`(Linux;配置零改动,模型域自动 MITM,环回 provider 保持直连)。上面的 settings.json `api_url` 路径仍是跨平台替代。
|
||||
- **账号登录**型客户端(OAuth/订阅)通常焊死端点——前缀技巧不适用,改看[下方 MITM 节](#客户端用-httpproxyconnect接入但从不压缩)。
|
||||
- 纯 **web 应用**(只在浏览器里的产品)本地没有流量可截。
|
||||
- VS Code 扩展的 baseURL 字段在明文设置里,密钥在系统钥匙串——这里只需要改 baseURL。
|
||||
|
||||
## 客户端用 `http.proxy`(CONNECT)接入但从不压缩
|
||||
|
||||
部分客户端(VS Code 系 IDE:CodeBuddy、Cursor、Windsurf……)只提供一个 HTTP **代理**设置(`http.proxy`、`codingcopilot.httpProxyURL` 等),没有可改写的模型 base-URL。这类客户端不走普通的 `/bili/…` 请求,而是把 `CONNECT <模型域名>:443` 发给代理。只有当模型域名在 bili 的 **MITM 白名单**里时这条路径才会被解密;否则 bili 只做盲隧道(不透明转发),永远看不到——也就无法压缩——模型请求(#897)。
|
||||
|
||||
该失效模式现在不再静默:
|
||||
|
||||
- 日志里对每个目标域名打一次 `BLIND TUNNEL WARNING`,附修复步骤;
|
||||
- `curl -s http://localhost:8787/__bili/health` 与 `/__bili/stats` 输出 `blindTunnels`(计数 + 精确目标域名,仅 loopback);
|
||||
- 存在此类隧道时,`acp_status` 输出会多一节 `UNDECRYPTED TRAFFIC (instance-level)`。
|
||||
|
||||
要真正压缩这类客户端:把它的模型域名加进 `billion-context.json` 的 `"mitm".domains`(如 `"mitm": { "domains": ["copilot.tencent.com"] }`)或环境变量 `BILI_MITM_DOMAINS`,重启 bili,并让客户端信任 bili 的根 CA(Node 系客户端用 `NODE_EXTRA_CA_CERTS=~/.local/share/billion-context/ca/root-ca.pem`,有 CA 路径设置的用其设置)。`/bili/` 前缀方案在这里不适用——没有 URL 可改。详见 [CONFIGURATION.zh-CN.md → MITM](CONFIGURATION.zh-CN.md#mitm-透明代理登录订阅客户端)。
|
||||
|
||||
## 未识别的端点直连、什么都不压缩(#1290)
|
||||
|
||||
bili 只压缩路径匹配已知 wire 协议(`/chat/completions`、`/llm_raw_chat`、`/v1/messages`、`/responses`……)的请求。发往其它路径的请求——例如第三方插件的**自定义 wire**(Command Code 的 Go 套餐发 `POST /alpha/generate`)——会逐字节中继,**永不压缩**。目前没有任何配置口可以声明一种任意新 wire;那是一项独立功能,不是一个能打开的开关。
|
||||
|
||||
这个结果现在不再静默(#1290):
|
||||
|
||||
- 客户端侧 fetch 钩子对每个不同的、以 **POST** 发出的未路由端点每进程记一次日志(`…is not a recognized model endpoint, so bili did not route it through the proxy…`);非 POST 流量——npm 注册表、目录 JSON、git refs——按设计保持静默(#1657:GET 不携带 prompt,不可能是模型流量);
|
||||
- `curl -s http://localhost:8787/__bili/stats` 输出 `unrecognizedPaths`(按路径计数,仅 loopback);
|
||||
- 存在此类请求时,`acp_status` 输出会多一节 `UNRECOGNIZED PATHS (instance-level)`。
|
||||
|
||||
如果你期望这类端点被压缩,改用 provider 的标准协议端点(Command Code 的 Provider 套餐发 `/provider/v1/chat/completions`,bili 能正常压缩);真正的自定义 wire 需要单独的支持。
|
||||
|
||||
## OpenCode
|
||||
|
||||
同一个内置插件同时服务两代 OpenCode:agent 文件同时保留 V1 `server()` 与 V2 `setup()` 导出 —— ≥ 1.18.29 的 1.x 宿主加载 V1 形状,2.x 宿主加载 V2 `setup()`。独立扩展 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 仅支持 V1,在 2.x 下**不加载** —— 对 OpenCode 2.x,**billion-context 是推荐的上下文管理方案**。以下均在 `@opencode/cli` 2.0.3 上端到端验证过(V1 泳道:1.14.46 与 1.18.31)。
|
||||
|
||||
| 路径 | 命令 | 适用 |
|
||||
|---|---|---|
|
||||
| 启动器(最省事) | `bili opencode` | 一条命令拉起代理 + 客户端;不碰真实配置 |
|
||||
| 原生(免启动器) | `bili plugin install opencode` | 自拉起插件写进真实配置;照常启动 `opencode` |
|
||||
| 纯代理(兜底) | baseURL 加 `/bili/` 前缀 | 无插件 —— wire 级工具注入 |
|
||||
|
||||
这三条路径**互斥**——每条都拥有同一批请求的路由权,每个宿主实例只能激活其中一条。手写的 `/bili/` provider baseURL 是纯代理路径的标记;在原生插件已装的情况下写它就是**矛盾配置**(#1958):运行时会每会话警告一次(按 origin 去重)并附修复指引——去掉前缀或卸掉插件——请求则留在其编码的纯代理路径上(无插件会话标记)。受支持的例外是对**同一** origin 的显式钉住——`BILLION_CONTEXT_PROXY` 指向 URL 已经在走的那个代理——保持静默。
|
||||
|
||||
### 启动器 —— `bili opencode`
|
||||
|
||||
HTTPS 走证书 MITM,HTTP 走临时 `opencode.json` 副本(`/bili/` 改写;JSONC 注释照单接受,合并方式与 opencode 自身一致;相对本地插件路径在副本里重新锚定为绝对路径 —— opencode 按声明所在配置文件目录解析,#826)。宿主代次用 `--version` 探测(探测失败默认按 1.x):**2.x** 宿主注入内置 V2 插件(`dist/agent/opencode.js`),以临时包装目录形式给出(目录入口 `index.js` 再 re-export 插件文件 —— 2.x 拒绝配置 `plugin` 数组里的裸文件路径);**1.x** 宿主直接给裸文件路径。
|
||||
|
||||
插件在两代宿主上做的事相同:在宿主内原生注册 bili 工具 —— compress / decompress / search_context / acp_status(另加 absorb)—— 并在每个 provider 请求上盖章代理头,含从宿主自身模型目录(`ctx.catalog.model.list()`,每 60s 刷新)读取的 context-window / max-output,并以 runtime-info 上报给代理(#955)—— 压缩走插件模式,**不做** wire 级工具注入;原生 auto-compaction 自动关闭(`compaction.auto: false`)。所有注册都是防御式的(可选链):任一 2.x build 上接缝缺失或未触发时,插件保持惰性,会话透明回退纯代理模式而不是报错 —— 在相邻的 `dev` build 上观察到过 API 面互不相同(#754 评审探针)。
|
||||
|
||||
1.x 细节(1.14.46 + 1.18.31 验证):V1 `.server()` 钩子在进程内把每个 provider 的 `options.baseURL` 改写为 `<proxy>/bili/…` 并设 `compaction.auto: false`;`chat.headers` 每次请求盖章插件头;`tool` 用真实 zod 形状注册 bili 工具(zod 是运行时依赖 —— 解析不到时降级为只改写)。没有显式 `baseURL` 的 provider(SDK 默认值,如裸 `@ai-sdk/openai` → api.openai.com)由全局 `fetch` 补丁兜住(日志:`v1: fetch patch installed`)—— 幂等,`/bili/` 包装过的 URL 原样直通;含 OpenAI Responses 端点端到端验证。
|
||||
|
||||
### 原生(免启动器)—— `bili plugin install opencode`
|
||||
|
||||
在真实 opencode 配置里注册一个自拉起插件并设 `compaction.auto: false`,之后直接跑 `opencode` 即可。默认不加 MCP 面(原生插件已提供会话绑定的 bili 工具);需要就传 `--with-mcp` —— 该条目不带 origin 钉扎,能扛过插件临时端口的代理重启(#926)。条目形态取决于**本 bili 自身的安装来源**:**npm 安装**写裸包名(`"plugin": ["billion-context"]`)—— 包经 `exports["./server"]` → `dist/agent/opencode-native.js` 暴露插件入口,opencode 用自己的 Npm.add 机制加载、自行管理安装与升级;零绝对路径、可跨机。(这个裸包名条目也可以不经 bili 直接手写进配置 —— 见 README 快速上手 方式 1。)**git checkout / 开发构建**回退到本机 shim 目录(`<configDir>/plugins/billion-context/index.js` → 该 checkout 的 `dist/agent/opencode-native.js`)—— 按构造即机器本地;之后改用 npm 安装再跑一次 install 会把条目迁回裸包名。
|
||||
|
||||
加载时插件自拉起自己的代理(健康的已有实例直接复用不重复起;父进程 pid 看门狗在 opencode 退出时收掉它),把模型流量路由到 `<proxy>/bili/<upstream-url>`,暴露与启动器模式相同的原生 bili 工具 —— 无固定端口、无环境变量、免启动器。退出:`BILI_NATIVE_OPENCODE=0`。若没有任何代理能拉到健康状态,请求直连(不压缩)并给一次性告警,之后自动恢复。在 `bili opencode` 启动下该条目整体跳过(代理归启动器管)。
|
||||
|
||||
### OpenAI Responses WebSocket(V2)
|
||||
|
||||
V2 插件也接管 OpenAI 的 `experimental.ws.handshake` 请求,两端均使用
|
||||
WebSocket:OpenCode → bili → Responses 上游。支持 OpenAI API Key 及
|
||||
ChatGPT Pro/Plus browser/headless OAuth;登录方式不决定传输方式。
|
||||
无需改写 OpenCode 配置或增加 bili 设置。首版只接受本机发起、携带原生
|
||||
插件身份的连接;普通或未接管的 WebSocket 升级仍立即返回 426。
|
||||
|
||||
ACP 处理、原生工具和用量统计保持生效。客户端增量先还原再压缩;只有
|
||||
处理后的历史确实延续上次响应时,上游才使用增量。压缩后在同一连接上
|
||||
发送完整压缩上下文,开始新的响应链。引用标签或其它历史变化也可能要求
|
||||
完整输入,因此复用连接不代表每轮都只发增量。不支持实验钩子的旧宿主
|
||||
需要使用 OpenCode 已有的 `providers.openai.settings.transport: "http"`。
|
||||
Realtime、同一连接的并发多路响应及远程 WS 客户端不在本次范围。
|
||||
验证使用真实 OpenCode V2.0.20 与本地 Responses WS 上游,未使用真实
|
||||
OpenAI/ChatGPT 凭据。
|
||||
|
||||
### 纯代理(无插件)
|
||||
|
||||
与其它客户端一样,把 provider baseURL 指向代理:
|
||||
|
||||
```json
|
||||
{
|
||||
"provider": {
|
||||
"myprovider": {
|
||||
"npm": "@ai-sdk/openai-compatible",
|
||||
"options": {
|
||||
"baseURL": "http://localhost:8787/bili/http://upstream.example/v1",
|
||||
"apiKey": "sk-any"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注意:2.0 AI-SDK provider 即使本地端点从不校验也要求 `apiKey` 字段 —— 随便填个非空值。
|
||||
|
||||
这条路径意味着**无插件**:若同时装了原生插件,运行时每会话警告一次——每个 provider 只选一条路径(#1958)。
|
||||
|
||||
### 状态:`/acp` 与 `acp_status`
|
||||
|
||||
`/acp` 面板在所有模式下都绑定当前会话,`acp_status` 工具是其宿主内等价手段。在命令编辑器支持新增条目的宿主(2.0.x 稳定版,`editor.add`)上,V2 插件额外注册 `/acp` 斜杠命令 —— 以合成非模型消息渲染,面板优先(与 `acp_status` 工具一致);旧形状上该注册保持惰性。注意 `opencode run` 模式完全不派发斜杠命令(它们会透传给模型)—— 请用 TUI。
|
||||
|
||||
同一接缝还承载 `/acp-cache`(#1146)—— prompt-cache 对账报告的人侧入口(输出与 `acp_cache` 工具一致):pi/omp 原生注册(`/acp-cache [full]` 出逐行清单);opencode V1 渲染为一条被忽略的消息,代理在到达 wire 前从模型上下文剥离;opencode V2 渲染为合成消息(报告最多可见 ~8 KB);dsh(两条泳道)显示默认摘要台账——dsh 的命令 API 不传参数,故无 `full`。旧 opencode-acp 会话(#920)收到显式的不可用提示(其流量绕过本代理的压缩状态)。Claude Code 没有进程内命令 API:`bili plugin install claude` 写一个模型中介的 `commands/acp-cache.md` markdown 命令,其 prompt 驱动 `acp_cache` MCP 工具并把报告逐字贴回。codex/kimi/hermes 没有用户可输入的命令接缝——直接让模型调用它的 `acp_cache` 工具。每次折叠的盈亏判定按可选的 `compress.priceProfile`(以输入 token 单价为基准的归一化倍率)计价;任何层级都未设置时,取请求模型在 models.dev 的价格行按绝对 $/Mtok 计(仅无法解析的模型回退内核比率默认值)——因此 breakeven/PAID BACK 开箱即反映你上游的真实经济账;对带自定义加价的中转站可按 provider 覆盖(CONFIGURATION.zh-CN.md,#1279)。
|
||||
|
||||
同一接缝还承载 `/acp-rule`(#1251/#1399)—— 持久指令功能的人侧入口(输出与 `acp_rule` 工具一致):pi/omp 原生注册,操作集与工具完全一致 —— 裸 `/acp-rule` 逐字列出全部已记录指令,`/acp-rule <文本>` 直接记录一条(等价于模型调用),`/acp-rule remove <id>` 删除一条,裸 `/acp-rule clear` 清空全部(`clear <文本>` 是记录而非清空——一个手误不该毁掉所有规则)。包裹后的 transcript 消息按内容签名从模型上下文剥离(与缓存报告同机制)—— 已记录的指令本来就每轮经 system prompt 注入。
|
||||
|
||||
### 旧 opencode-acp 会话(#920)
|
||||
|
||||
在 1.x 宿主上,迁移前的 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 旧会话在两条泳道下都继续可用:启动器从临时配置副本中移除 `opencode-acp` 条目(宿主永远不会以激活状态加载它),各泳道把已安装的包作为库吸收(直接从 `node_modules` 导入 —— `.opencode/node_modules`、项目 `node_modules`、全局 npm root、opencode 配置级 modules,先到先得)。会话属于 legacy ⟺ opencode-acp 的持久化状态文件存在(`<XDG_DATA_HOME>/opencode/storage/plugin/acp/<sessionID>.json`,或 `acp.jsonc` 中 `storagePath` 指定的目录):
|
||||
|
||||
- **旧会话** —— 压缩由被吸收的 opencode-acp 执行(它自己的引用号与块存储照常工作:`compress` / `decompress` / `search_context` / `acp_status` / `acp_context_recap` 全部在它里面执行)。其模型请求带 `x-bili-plugin-bypass: 1`,代理原样转发 —— 不注入 wire 工具、不注 nudge、不绑定会话。
|
||||
- **新会话** —— bili 接管:工具调用转发到代理的 plugin 端点(plugin 模式)。执行器按会话分泳道:新会话的 `compress` 发到代理,旧会话的发给 opencode-acp。`acp_context_recap` 没有代理端对应 —— 新会话调用会收到代理的 unknown-tool 消息。
|
||||
|
||||
`/acp` 与 `/dcp` 同样路由。新会话被 opencode-acp 注册表收编的可能被其 transform 门控(system / messages / text.complete 都过 legacy 谓词)阻断。退化路径:包缺失、导入失败或不是 v1 时,bili 单独运行,旧会话退化为只读存档(旧标签照常渲染、`decompress` 返回 `[Block … not found]`、新引用号从 m00001 重新开始)。
|
||||
|
||||
### 注意事项
|
||||
|
||||
- 2.x 系列以 npm 包 `@opencode/cli` 发布,且插件 API 面在不同 build 间仍在变动(相邻 `dev` 通道构建暴露不同 `ctx` 形状)—— 上文钩子/工具细节是针对具体版本的观察,不是稳定契约。
|
||||
- 设计说明:V2 插件是薄协议客户端(不含 acp-kernel)—— 代理始终是唯一的压缩权威,消除 agent 与代理间的内核版本漂移;它不依赖插件 API 无法改上下文这一事实(该能力随 2.x build 变化)。
|
||||
> 已迁移至 [docs/clients.zh-CN.md](docs/clients.zh-CN.md)。重定向占位,1–2 个版本后删除。
|
||||
|
||||
@@ -1,221 +1 @@
|
||||
# LIFECYCLE.md — 过渡开关台账 · 退役模块盘点 · 卫生记录
|
||||
|
||||
> 与 CONFIGURATION.md 的分工:CONFIGURATION 记录每个旋钮**今天做什么**;本台账记录哪些旋钮是**临时的**(盖子 / kill-switch / 实验性 opt-in,带解除条件),以及哪些模块在退役路径上。
|
||||
> 建立于 #3249(陈年件清理)。纪律:**只立账不删**——删除逐项由 owner 拍板。
|
||||
>
|
||||
> **CI 强制**:`scripts/lifecycle-ledger-guard.mjs`(workflow job `lifecycle-ledger-guard`)会检查 `src/` 里读到的每一个 `BILI_*` 环境变量是否都出现在本文件——**台账外的新变量直接 fail**;台账里有但代码已不读的条目只给 notice(动态生成名、未落 master 的分支变量属正常滞后)。
|
||||
|
||||
## 规则
|
||||
|
||||
1. `src/` 中读取的每个 `BILI_*` 环境变量必须在本文件出现(§1 或 §2)——CI 强制。
|
||||
2. §1 = 过渡开关:有明确解除条件的盖子 / kill-switch / 实验。字段:引入 / 引入原因 / 解除条件 / 状态。
|
||||
3. §2 = 常设面:按类列出,一行一个(名称 / 类别 / 一句话用途),无解除条件预期。
|
||||
4. 新增过渡开关:先在 §1 立账(含解除条件),再落码;CI 保证不漏。
|
||||
5. 共享 `BILI_` 前缀但**不是环境变量**的标识符列在 §3,避免混淆。
|
||||
|
||||
---
|
||||
|
||||
## 1. 过渡开关台账(盖子 / kill-switch / 实验)
|
||||
|
||||
| 开关 | 引入 | 引入原因 | 解除条件 | 状态(2026-10-15) |
|
||||
|------|------|----------|----------|--------------------|
|
||||
| `BILI_ANTHROPIC_THREADS_INJECT` | #2888(未合入 master 的开放 PR,分支 `2026-10-12_claude-global-scope-narrow-gate`) | #2884 CC 全局作用域直通 bug 的临时盖子:threads lane 默认逐字节直通;`=1` 才启用完整注入 | #2926 S5:真实 CC 主会话抓包证明注入后上游 200 + SQLite 统一 rebuild-fold 落地 | 未落 master(PR #2888 open);生命周期跟踪于 #2926 |
|
||||
| `BILI_STREAM_STALL_MS` | #1706 时代的流停滞检测 | #1706 事故(陈年 400ms 误报)后由 #1714 退役;现在只读它来发一条警告(src/server.ts:594) | 已无生产意义——连警告读一起删 | 已退役(只读告警);整体移除候选 |
|
||||
| `BILI_SESSION_WARM_MAX` | #2803 bounded startup | 限制 boot 时预热会话数(master 当前默认 8,src/knobs.ts:230) | 在途 PR #3194 把默认翻成 0 → 本变量退化为纯 opt-back;合入后观察 dogfood 数据再决定去留 | 在用(master 默认 8);决策等 #3194 合入后的数据 |
|
||||
| `BILI_STORAGE_UNIFIED` | #2671 存储统一重建 | dry-run 转正开关 legacy/shadow/full(当前默认 shadow,JSON 仍是唯一事实源) | shadow 跑稳后转正拍板(full 成为默认);届时一并决定「legacy 显式值还要不要支持」 | 在用(默认 shadow);未转正 |
|
||||
| `BILI_STORAGE_JSON_WRITER` | #2960 Phase 3 | full 模式下的 JSON writer 关闭开关(回滚通路;仅 full 模式生效,默认 on) | 与 storage.unified 转正绑定:unified 定案后退役 | 在用(仅 full 生效) |
|
||||
| `BILI_ROLLOUT_`(前缀家族;现成员 `BILI_ROLLOUT_SIMHASH_V2`、`BILI_ROLLOUT_FOLD_GUARD`) | src/rollout.ts 灰度机制 | 每功能灰度 kill-switch:env > config `rollout.features.<name>`(true/false/percent 简写,#3062)> 确定性分桶(sha256(salt\nid)%10000)> off | 单个功能灰度完成并稳定后,从 rollout 表移除该功能,其 env 随之失去意义 | 机制常设;单个成员轮换 |
|
||||
| `BILI_FOLD_RECONCILE` | #1921 | fold 对账模式 off/warn/repair(默认 repair;非法值只告警不致命,src/fold-reconcile.ts:384) | 增量车道 #3248 落地后评估 legacy 对账路径去留 | 在用(默认 repair);与 #3248 联动 |
|
||||
| `BILI_RECLAIM_FETCH_PATCH` | #1158 | escape hatch:`=0` 保留经典直装 fetch patch 路径 | fetch-chain patch 成为既定行为后退役 | 默认开(`=0` 回退经典路径) |
|
||||
| `BILI_CODEX_STATE_MODE` | #2222 | codex state-db 策略逃生口(auto/shared/legacy;auto=二进制认 CODEX_SQLITE_HOME 就 shared 否则 legacy;shared 遇旧二进制降级并告警) | codex 状态策略稳定后随 #2222 收尾 | 默认 auto |
|
||||
| `BILI_CODEX_COMPACT` | #3008 | codex compaction 拦截 kill-switch(intercept/pass);intercept 覆盖显式与内联 auto-compact(SUMMARIZATION_PROMPT 识别) | intercept-by-default 站稳后评估 pass 模式是否还有人需要 | 默认 intercept |
|
||||
| `BILI_CODEX_STATE_MODE` | #2222/#3321 | codex 状态库策略逃生舱:`auto`(默认,二进制支持 CODEX_SQLITE_HOME 则 shared,否则 legacy)/ `legacy`(始终旧拷贝路径)/ `shared`(请求 shared,二进制太旧时降级 legacy 并告警);非法值告警后按 auto(src/launcher.ts:3674) | shared/auto 策略站稳(#3321 并发车道落地后观察)后评估去留 | 在用(默认 auto) |
|
||||
| `BILI_SQLITE_AUTO_DOWNLOAD` | #2833 | sqlite 引擎自下载开关(严格 1/0 > 文件 > 默认 true;被拒时仍用缓存副本) | —(转正为常设安全阀则移 §2) | 在用(默认 true) |
|
||||
| `BILI_NATIVE_ATTACH_EXTERNAL` | #1322/#1335 | 外部 attach opt-in:默认拒绝 attach 到会长命于会话的实例(拒绝文案见 launcher.ts:3561) | —(长期安全姿态则移 §2) | opt-in(默认 false) |
|
||||
| `BILI_LAUNCHER_DIRECT` | launcher direct-URL 模式 | `=1` 进入直通 URL 模式:LLM 流量不过代理 ⇒ 无压缩(只有 bili MCP 调用可用);默认 MITM | —(两种模式都是正式入口则移 §2) | opt-in(`=1`) |
|
||||
| `BILI_LAUNCHER_PLUGIN` | launcher plugin 车道 | `=0` kill switch 回 wire 注入工具;`=1` 强制 plugin 车道;缺省自动 | plugin 车道成为唯一车道后退役 kill switch | 默认 auto |
|
||||
| `BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_RESIGN_BENEFIT` / `BILI_CODEARTS_REF` | #1884 / #2090 | 签名上游重签特性族:`=0` 整族下线(回到 #1884 前重写行为);passthrough 是「此链路不带压缩」的显式确认通道 | 特性族定型后各成员转 §2 | 特性族在用(`=0` 可整族下线) |
|
||||
| `BILI_FAKE_COMPLETION_RETRIES` | fake-completion fallback | 假完成重试(opt-in,默认 0 = 禁用) | fallback 机制定型后转 §2 | opt-in |
|
||||
| `BILI_NO_CACHE_CONTROL` | compat | 历史 no-cache-control 怪癖保留(knobs.ts:458 明言 "Historical quirk preserved in the env") | 兼容窗口结束后退役 | 默认 off |
|
||||
| `BILI_STREAM_ERROR_SHAPE` | compat | 给无法带内上报错误的 SDK 的流错误形状兼容 | 兼容保留(长期) | 常设兼容旋钮 |
|
||||
| `BILI_SUBAGENT_SPLIT` | #970 | subagent 拆分(默认 on) | 成为既定行为后移 §2 | 默认 ON(`=0` 退出) |
|
||||
| `BILI_RESUME_INHERITANCE` | resume inheritance | resume 继承行为(默认 on) | 同上 | 默认 ON(`=0` 退出) |
|
||||
| `BILI_AFFINITY_SIMHASH` | #2265 | simhash adoption kill-switch(`=0` 禁用) | adoption 成为既定行为后移 §2 | 默认 ON |
|
||||
| `BILI_CHAIN_CONTENT` | chain 识别 | chain 内容检测(#1683 背景;默认 off,文件可开) | 实验结论出来转正或删 | 默认 off |
|
||||
| `BILI_CHAIN_STAMP` | egress stamp | stripped-middlebox 场景的出口戳(默认 off) | 同上 | 默认 off |
|
||||
| `BILI_STABLE_SYSTEM_ANCHOR` | stable-system-anchor 实验 | 每会话 system 锚点实验(默认 OFF) | 稳定性评估后转正或删 | opt-in(默认 OFF) |
|
||||
| `BILI_FORK_ADOPTION` | fork-adoption 特性 | fork 继承实验(opt-in;禁用时提示从零开始,fork-adoption.ts:300) | 稳定后转正或退役 | opt-in(默认 off) |
|
||||
| `BILI_ALLOW_DSH_COMPACTION` | dsh compaction | dsh compaction opt-in(env 语义同 BILI_PERSIST 家族) | 转正后移 §2 | opt-in(`=1`) |
|
||||
| `BILI_SNAPSHOT_SHADOW` | #3756 | snapshot-render 影子观测:每个 armed turn 计算快照视图但**不使用**(出站仍走 legacy 路径),与实际发送对比记 per-session 计数(面板 + `snapshot-shadow` 诊断话题)——render 引擎在 rollout 翻转前用真实流量证明健康(dry-run-then-flip,同存储 #2815 shadow→#3818 full 纪律) | render 车道转正(rollout 100% 且影子计数归稳)后退役 | 默认 on(render lane 本身 rollout 0%,纯观测) |
|
||||
| `BILI_DSH_AUTHORED_COMPACTION` | #3733 | dsh 原生 compaction summarize 调用由 #1729 guard 拒绝改为**本地应答折叠快照**(零出账;dsh 记 checkpoint、会话文件收缩) | adoption 后按 #2028 模式转 file/web 开关,env 退役(file 键 `dsh.authoredCompaction` 已镜像) | 0.1.203 dogfood 站稳后默认 on;`=0` 回 #1729 拒绝路径 |
|
||||
| `BILI_PI_INLINE` | #3278 | pi inline 模式(默认 off):不起 proxy 进程,fetch 链在 intercept 之下的一个环节把伪 origin 流量路由进进程内引擎(inline-engine.ts,跑同 startServer 的每请求管线);file 家 `"pi": {"inline": true}`,`=0` 显式关 | inline 车道 GA(转 §2 常设)或实验放弃后收束 | opt-in(默认 off) |
|
||||
| 测试钩子:`BILI_DSH_RECOVERY_INTERVAL_MS` / `BILI_DSH_RETRY_INTERVAL_MS` / `BILI_MODEL_INFO_RETRY_MS` | #2082 等 | 缩短测试/运维节奏(dsh-native.ts;NODE_TEST_CONTEXT 感知,避免生产误缩) | 永久测试设施,随宿主代码走 | 测试钩子 |
|
||||
|
||||
## 2. 常设面全量登记表(src/ 实际读取的其余 BILI_* 环境变量)
|
||||
|
||||
### 2.1 宿主 opt-out(per-host kill switch;另有全局 `BILLION_CONTEXT_PLUGIN=0`)
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_NATIVE_CLAUDE` / `BILI_NATIVE_DSH` / `BILI_NATIVE_KIMI` / `BILI_NATIVE_OMP` / `BILI_NATIVE_OPENCODE` / `BILI_NATIVE_PI` / `BILI_NATIVE_ZCODE` | 对应宿主 native 车道 `=0` 整体退出(bootstrap 各文件入口判断) |
|
||||
| `BILI_NATIVE_ATTACH_POLICY` | native attach 策略(env > 文件 native.attachPolicy) |
|
||||
|
||||
### 2.2 内部 spawn 通道(launcher→子进程,非用户面)
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_LAUNCH_TOKEN` | launch 令牌(spawn 时注入;日志中脱敏) |
|
||||
| `BILI_PARENT_PID` | owner-pid 看门狗(会话生命周期归属) |
|
||||
| `BILI_STRICT_PORT` | `=1` claude SessionStart hook 退出端口重试(#964) |
|
||||
| `BILI_OPENCODE_ACP_SPEC` | 剥离版 ACP spec 临时配置**文件路径**提示 |
|
||||
| `BILI_LAUNCHER_LANE` | lane 身份戳(attach 时比对归属) |
|
||||
| `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` | 模型窗口/输出上限 JSON,传给子进程对齐 nudge 分母与输出预留 |
|
||||
| `BILI_INHERITED_HTTP_PROXY` / `BILI_INHERITED_HTTPS_PROXY` / `BILI_INHERITED_ALL_PROXY` / `BILI_INHERITED_NO_PROXY` | 继承调用方代理设置转发给 proxy 子进程 |
|
||||
| `BILI_MITM_HOSTS` / `BILI_MITM_DOMAINS` | MITM 主机/域名单传给子进程 |
|
||||
| `BILI_NON_HTTP_PROVIDERS` | #1392 非 http(s) baseUrl provider 白名单传递 |
|
||||
| `BILI_PROVIDER_REWRITES` | #535 provider 改写 manifest JSON(存在即关 zcode native) |
|
||||
| `BILI_UPGRADE_REPLACEMENT` | #3044 self-restart 替换进程交接标记(UPGRADE_REPLACEMENT_ENV) |
|
||||
|
||||
### 2.3 网络调优(#2030 迁移家族:env > 文件 network.* > 默认)
|
||||
|
||||
| 变量 | 默认 |
|
||||
|------|------|
|
||||
| `BILI_UPSTREAM_TIMEOUT_MS` | 720000(12 min) |
|
||||
| `BILI_REQUEST_WATCHDOG_MS` | 2× upstream timeout |
|
||||
| `BILI_KEEP_ALIVE_TIMEOUT_MS` | 5000 |
|
||||
| `BILI_CLIENT_ERROR_BACKSTOP_MS` | 30000 |
|
||||
| `BILI_EXPOSURE_LOG_INTERVAL_MS` | 3600000(0 禁用,垃圾值回落 3600000) |
|
||||
| `BILI_MAX_SHRINK_PER_COMPRESS` | unset(不做收缩引导) |
|
||||
| `BILI_REPLAY_RETRY_MAX` / `BILI_REPLAY_RETRY_BASE_MS` | 3 / 1500 |
|
||||
| `BILI_THROTTLE_429` / `BILI_THROTTLE_429_MAX_CONSECUTIVE` / `BILI_THROTTLE_429_BASE_DELAY_MS` / `BILI_THROTTLE_429_MAX_DELAY_MS` | true / 5 / 2000 / 30000(#4204 出站 429 治理器:同一 origin+凭据连续上游 429 后本地 hold、零出站,退避×抖动、尊重 Retry-After;达上限转终局 424(不在各 SDK 重试集合内),每窗口一次探测自动恢复,任何非 429 响应即清除;`false` 恢复旧的总是转发行为) |
|
||||
| `BILI_STREAM_KEEPALIVE_MS` | 15000(0 禁用 hold) |
|
||||
| `BILI_PREFLIGHT_HOLD_MS` | 30000 |
|
||||
| `BILI_PREFLIGHT_DEAD_END_COOLDOWN_MS` | 300000 |
|
||||
| `BILI_POST_RESPONSE_LINGER_MS` | 5000(#1982,曾为纯 env) |
|
||||
| `BILI_PROXY_KEEPALIVE_MAX_MS` | 55000(0 = 一次性连接) |
|
||||
| `BILI_CCR_RETRIEVAL_TTL_MS` | 600000 |
|
||||
| `BILI_DECOMPRESS_TMP_CAP` | 50 |
|
||||
| `BILI_PUBLIC_SNAPSHOT_CAP_BYTES` | 100 MiB(#2017;0 完全禁用留存) |
|
||||
| `BILI_MITM_HANDSHAKE_TIMEOUT_MS` | 10000 |
|
||||
| `BILI_CHAIN_MAX_FUTURE_SKEW_MS` / `BILI_CHAIN_RECENT_WINDOW_MS` | chain-checkpoint 内部默认值 |
|
||||
| `BILI_CA_FILE` | network.caFile,默认无——附加 PEM 根证书与内置根 **MERGE**(企业 MITM/DLP 重签上游证书被拒 SELF_SIGNED_CERT_IN_CHAIN 时,#3776;不替换内置根) |
|
||||
| `BILI_RECEIVE_BODY_BYTES` / `BILI_DECODED_BODY_BYTES` | network.receive/decodedBodyBytes,5 GiB / 10 GiB——单请求入站/解码后内存上限(#3128:曾硬编码 100 MiB,多 GB 单请求被 reset) |
|
||||
| `BILI_OUTBOUND_BODY_BYTES` | network.outboundBodyBytes,5 GiB——重建后转发上游的硬上限(#3128) |
|
||||
| `BILI_WS_OUTBOUND_BYTES` | network.wsOutboundBytes,10 MiB——WS 车道出站软预算:超限先把旧的非保护图归档/降采样再发送(#3701:网关对大帧 close 1009;0 关闭预发送削减;HTTP 车道不受影响) |
|
||||
| `BILI_CACHE_KEEPALIVE`(#3376) | unset(false;同 `cacheKeepalive.enabled` 层级 env 覆盖) |
|
||||
| `BILI_CACHE_KEEPALIVE_ASSUME_TTL` | unset(从 body cache_control 断点探测) |
|
||||
| `BILI_CACHE_KEEPALIVE_TTL_FACTOR` | 0.9 |
|
||||
| `BILI_CACHE_KEEPALIVE_MAX_DURATION_MS` | 86400000(24h) |
|
||||
| `BILI_CACHE_KEEPALIVE_MAX_PINGS` | 4 |
|
||||
| `BILI_CACHE_KEEPALIVE_ARM_WITHOUT_BREAKPOINTS` | unset(false) |
|
||||
| `BILI_CACHE_KEEPALIVE_INTERVAL_MS` | unset(按 TTL 层推导) |
|
||||
|
||||
### 2.4 会话池 / GC / 持久化
|
||||
|
||||
| 变量 | 一句话用途 / 默认 |
|
||||
|------|------------------|
|
||||
| `BILI_MAX_SESSIONS` | sessions.max,默认 256 |
|
||||
| `BILI_SESSION_GC` | 会话 GC 总开关(`=1/true/on` 启用,默认 off;启用后下面三个参数生效) |
|
||||
| `BILI_SESSION_GC_INTERVAL_MS` / `BILI_SESSION_GC_MAX_AGE_DAYS` / `BILI_SESSION_GC_MAX_TOKENS` | 会话 GC 参数(默认 1h / 7d / 1M tokens) |
|
||||
| `BILI_SESSION_RESIDENT_MAX_BYTES` | sessions.residentMaxBytes,512 MiB 软上限(#2803) |
|
||||
| `BILI_SESSION_WARM_MAX_BYTES` | warm 解码字节上限,64 MiB(#2803) |
|
||||
| `BILI_PERSIST` | `=0` 关闭持久化(ephemeral/test) |
|
||||
| `BILI_PERSIST_DEBOUNCE_MS` | persist.debounceMs,500 |
|
||||
| `BILI_PERSIST_EPERM_ALERT_THRESHOLD` / `BILI_PERSIST_EPERM_ALERT_REPEAT_MS` | EPERM 告警阈值 5 / 重复间隔 0(不限次) |
|
||||
| `BILI_PERSIST_TAIL_TOKENS` | persist.tailTokens,16384(0 禁用消息持久化,#401) |
|
||||
| `BILI_PERSIST_ZSTD` | `=1/true` 启用 zstd 压缩持久化(owner 决定 #1080,默认 off) |
|
||||
| `BILI_SESSIONS_DIR` | 状态目录重定位 |
|
||||
| `BILI_STORAGE_ARCHIVE_AFTER_DAYS` | storage.archiveAfterDays,默认 365 天——超龄会话由 gc 归档(export + tombstone + CAS 释放;0 关闭年龄清扫,#3901/#3463) |
|
||||
| `BILI_STORAGE_QUICK_CHECK` | 默认开——index.db 开库在迁移前跑 PRAGMA quick_check 自检;失败=影子层隔离文件组(.corrupt-<ts>)+重建新库(JSON 信封为恢复源);=0 跳过(超大库启动时间敏感场景,#4175) |
|
||||
| `BILI_STORAGE_WAL_JOURNAL_SIZE_LIMIT_BYTES` | storage.walJournalSizeLimitBytes——SQLite WAL 回收字节上限(#3250;垃圾/非正值落回文件/默认层,不让 typo 崩 boot) |
|
||||
| `BILI_MYSQL_DSN` | storage.mysql.dsn——mysql 引擎连接串(env > 文件 > "";空 = mysql 不可用走 sqlite,#3388/#3931) |
|
||||
|
||||
### 2.5 诊断
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_DUMP_4XX` | `=1` 或 diagnostics.dump4xx:4xx 时落盘精确重放 body(#762/#276,默认 off) |
|
||||
| `BILI_DUMP_4XX_MAX_BYTES` | dump 单文件上限,2 MiB(floor 1 KiB) |
|
||||
| `BILI_DUMP_MAX_TOTAL_BYTES` | dump 总量上限,默认 off(null) |
|
||||
| `BILI_DUMP_MAX_AGE_DAYS` | dump 年龄上限,默认 off(null) |
|
||||
| `BILI_FAKE_BUF_CAP` | fake-completion 缓冲上限,16 MiB |
|
||||
| `BILI_CONFLICT_SCAN` | thirdparty-scan 冲突扫描开关 |
|
||||
| `BILI_INVARIANT_JUDGE` | diagnostics.invariantJudge,默认 on——I1/I2 出站不变量法官(L1 顾问:violation 只 warn、流量永不拦;`=0` 解除武装,#3938 decision ②) |
|
||||
|
||||
### 2.6 安全 / 运维通道
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_ENCRYPTION_KEY` | sidecar 加密密钥(hex/base64 恰好 32 字节,#708;设置期间 sidecar 拒绝打开明文) |
|
||||
| `BILI_CONFIG_FILE` | `--config` 等价物 |
|
||||
| `BILI_CLIENT_BIN` | native 可执行文件覆盖(probe 契约同 launcher) |
|
||||
| `BILI_CONVERSATION_ID` | codex spawn 期会话注册(CLAUDE_CODE_SESSION_ID 优先) |
|
||||
| `BILI_MCP_PROXY` | codex MCP shell 用的 proxy origin(含发现回退) |
|
||||
| `BILI_MCP_DEFAULT_ORIGIN` | zcode MCP entry 默认 origin(http://127.0.0.1:8787) |
|
||||
| `BILI_MCP_NO_ORPHAN_ADOPT` | `=1` 多宿主共享一个 proxy 时禁用孤儿 adopt |
|
||||
| `BILI_UPSTREAM_PROXY` / `BILI_UPSTREAM_PROXY_MODE` | 上游出口代理及 manual/auto 模式(默认直连是有意设计,#346/#357) |
|
||||
| `BILI_TUNNEL_ALLOWED_HOSTS` | 远端隧道允许清单(host / host:port) |
|
||||
| `BILI_ZONE_PORT` | USER zone 基址覆盖(#1660) |
|
||||
| `BILI_CLAUDE_NATIVE_PORT` / `BILI_ZCODE_PORT` | 显式 zone 端口覆盖(strict-port 语义,#1660) |
|
||||
| `BILI_ATTACH_EVIDENCE_GRACE_MS` / `BILI_ATTACH_HEALTH_DEADLINE_MS` | native attach 证据宽限窗 / 健康截止窗 |
|
||||
| `BILI_DSH_BIN` / `BILI_PI_BIN` | dsh / pi 可执行文件覆盖 |
|
||||
| `BILI_PLUGIN_AGENT` | `--plugin` 目标 agent 选择(默认 claude) |
|
||||
| `BILI_LOG_MASK_HOSTS` | 日志主机名掩码(默认开;`=0` 本地调试退出) |
|
||||
| `BILI_ALLOW_PRIVATE_HTTP_PROVIDERS` | 私有 http provider 放行(CGNAT 100.64/10 恒拒) |
|
||||
| `BILI_MITM` | MITM 功能总开关(env > 文件 mitm.enabled > 默认开;`=0` 整体关闭;与内部通道 `BILI_MITM_HOSTS`/`BILI_MITM_DOMAINS` 不同) |
|
||||
| `BILI_CLAUDE_UPSTREAM` | direct-URL 模式下绕过预置 relay 的上游 URL(OAuth 订阅流量需 MITM 模式) |
|
||||
|
||||
### 2.7 更新器 / 公告
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_UPDATE_REGISTRY` | registry base URL 覆盖(完整 URL) |
|
||||
| `BILI_UPDATE_CHECK_INTERVAL_MS` | update.checkIntervalMs 覆盖(#2030) |
|
||||
| `BILI_ADVISORY_CHECK` | 公告检查开关(默认 ON;文件 advisoryCheck:false 退出) |
|
||||
| `BILI_ADVISORY_URL` | 公告文档 URL 覆盖 |
|
||||
| `BILI_RELEASE_NOTES_CHECK` | 发布说明检查(#1870,默认 ON) |
|
||||
| `BILI_RELEASE_NOTES_URL` | 发布说明 URL 覆盖 |
|
||||
| `BILI_UPDATE_POLICY_URL` | update.policyUrl——更新策略 URL 覆盖(**测试专用**:生产固定官方 repo,#3619 安全边界) |
|
||||
| `BILI_UPDATE_STAGGER_MIN_MS` / `BILI_UPDATE_STAGGER_MAX_MS` | update.staggerMin/MaxDelayMs——升级错峰窗口(env 为裸 ms;file 层另收 "15m"/"1d12h" 人读时长;0/0 = 本机回立即升级旧行为;默认上限窗 48h,#3619) |
|
||||
|
||||
### 2.8 图像计费 / zcode 兼容
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_IMAGE_BILLING` | `=bytes` 走字节替代路线 |
|
||||
| `BILI_IMAGE_TOKEN_CAP` | 单图成本上限 live-read(#1843 L3) |
|
||||
| `BILI_ZCODE_ROUTE` | zcode 路由兼容逃生舱(`=none` / kill-switch → 降级路由) |
|
||||
| `BILI_ZCODE_SIGNING_FIXED` | zcode 固定签名 |
|
||||
| `BILI_IMAGE_RESCALE` / `BILI_IMAGE_RESCALE_MAX_DIM` | imageRescale(默认 on)/ rescale 最长边目标(默认 1600,floor 128,env-only)——出站图像降尺度:大图缩小发送、原件留本地会话存储(`0` 全尺寸透传,#3400 owner 决定) |
|
||||
|
||||
### 2.9 插件工具 guardrails / 压缩车道开关
|
||||
|
||||
| 变量 | 一句话用途 |
|
||||
|------|-----------|
|
||||
| `BILI_GUARDRAIL_BASH_TIMEOUT` | guardrails.bashTimeout,默认 60s——模型没写 timeout 时宿主侧注入 bash `timeout`(pi/omp host 进程读;0 = 不注入,#3066) |
|
||||
| `BILI_GUARDRAIL_MAX_OUTPUT_BYTES` | guardrails.maxOutputBytes,默认 50KB——工具输出封顶(0 = 不封顶) |
|
||||
| `BILI_GUARDRAIL_REPETITION` | guardrails.repetition,默认 on——相同调用循环熔断(warn 3 / abort 5) |
|
||||
| `BILI_GUARDRAIL_TEXT_RUN_THRESHOLD` | guardrails.textRunThreshold,默认 200——输出端同字符连击熔断阈值(proxy 进程侧读,#3406 item 1;0 关闭) |
|
||||
| `BILI_AUTO_MODE_FORGE` | autoModeForge.enabled,默认 on——auto-mode 分类判定本地 forge,零出账/计费(`=0` 恢复纯透传,留给付真实判定费的用户,#2740 owner 决定) |
|
||||
| `BILI_DSH_CONTEXT_TAB` | dsh.contextTab 的 env 层(#4237):`=0` 隐藏 DSH 顶栏「上下文」标签页(压缩及其余入口全部不受影响);其他值强制开并覆盖文件层;缺省按文件层(默认 true);下次页面加载 / dsh 重启生效 |
|
||||
|
||||
## 3. 非环境变量的 BILI_* 标识符(勿与上表混淆)
|
||||
|
||||
以下共享 `BILI_` 前缀但是代码常量/工具表/错误码,不是环境变量,不在 CI 检查范围:
|
||||
|
||||
`BILI_ACP_HANDLED__`(哨兵 Error 字符串)、`BILI_ACP_TOOLS_{ANTHROPIC,GOOGLE,OPENAI,RESPONSES}[_NO_RANGE]`、`BILI_ACP_READONLY_TOOLS_RESPONSES[_NO_RANGE]`、`BILI_DECOMPRESS_TOOL{,_OPENAI,_RESPONSES,_GOOGLE}`、`BILI_DECOMPRESS_IMG_{ANTHROPIC,GOOGLE,OPENAI,RESPONSES}`、`BILI_SEARCH_CONTEXT_TOOL{,_OPENAI,_RESPONSES,_GOOGLE}`(compress-tool.ts 工具表常量)、`BILI_DSH_PACKAGE`(="billion-context")、`BILI_HOP_HEADER`(="x-bili-hop")、`BILI_INJECTABLE_TOOL_NAMES`(Set)、`BILI_OVERLAY_BUSY`(错误码)、`BILI_PASSTHROUGH_HEADER`、`BILI_PLUGIN_BYPASS_HEADER`(="x-bili-plugin-bypass")、`V2_BILI_TOOLS` / `BILI_TOOLS`(opencode-v2.ts)、`BILI_TOOL_NAMES`(Set,side-request.ts)、`MCP_BILI_TOOL_PREFIX`(="mcp__bili__")、`BILI_TUNNEL_HEADER`(="x-bili-tunnel")。
|
||||
|
||||
## 4. 退役模块盘点
|
||||
|
||||
| 模块 / 标记 | 现状 | 退役条件 | 跟踪 |
|
||||
|-------------|------|----------|------|
|
||||
| `src/persona-anchor.ts`(179 行) | 生产路径已迁 v2.2(session-resolve),但 **src/session-resolve.ts 自身仍 import 它**,另有 src/plugin.ts、src/server/side-request.ts 及 4 个测试套件(dsh-persona-continuity、issue2601-model-drift-absorption、issue2601-persona-fork-lineage、issue2944-neutral-skeleton)引用做断言 | #2989 孪生化完成后整文件删除(注意 session-resolve.ts 的依赖也要切掉) | #2989 |
|
||||
| `src/fold-reconcile.ts` legacy 对账路径 | 在用(`BILI_FOLD_RECONCILE` 默认 repair,见 §1) | 增量车道 #3248 落地后评估去留 | #3248 |
|
||||
| `TODO(#NNNN)` 标记 | 全仓(src/、kernel/src/、pi-subagents/src/)**零命中**——不存在 issue 编号型 TODO | — | 无需跟踪 |
|
||||
| deprecated 标记 | 均为小项:① acp.json delegate 配置弃用(运行时警告"future release 移除",prompt←delegatePrompt 改名,pi-subagents.ts:153/163、config.ts:1502)② config.ts:1713 某章节的 deprecated fallback(仅在章节缺失时读)③ `minCompressRangeChars` 是 `minCompressRange` 的弃用别名(compress-settings.ts:50/223)④ claude-native-bootstrap.ts:263 关于 ps/wmic 的系统 API 注释(非 bili 代码) | 各自随所属特性演进;无批量行动 | — |
|
||||
|
||||
## 5. 卫生记录
|
||||
|
||||
- **2026-10-15 远端分支卫生(#3249 执行)**:删除 origin 已合并远端分支 **1394 条**(1386 条 = 已合并 PR 的同仓 head 分支 + 8 条 = 完全并入 master 但无对应 PR 记录:`2026-08-08_release-v0.1.14`、`2026-09-26_opencode-zen-mitm`、`2026-09-30_responses-side-compaction`、`2026-10-04_plugin-fork-context-provenance`、`2026-10-13_lastmessages-tabling`、`chore/pages-enablement`、`fix/codex-custom-tool-call-text-protocol`、`revert-3189-pages-enablement`)。删除前核对:与 open PR head 交集为空。删除后 origin 剩 361 个 head(其中 128 条为 open PR 分支、201 条 closed-unmerged 且未并入 master、30 条无 PR 未并入 = 废弃工作,均不动)。另执行一次 `git worktree prune` 清掉失效 worktree 登记。
|
||||
- **2026-10-20 台账补登(本 PR)**:#3249 落地本台账时 `src/` 实际读取数已比登记数多 22(#3955 mysql、guardrails、#3128 网络预算、#3400 图像缩放、#3619 错峰、#3733 dsh compaction、#3756 snapshot shadow 等),守卫上线即全线红(master run 均被后续 push 取消所以未暴露)。本次 22 条全部补登(3 条 §1 + 19 条 §2)。
|
||||
- **机器侧纪律(owner 手工做过,记录备查,不做自动化)**:2026-10-15 手工清理 11 个陈年 bili 进程(全部零活跃连接才杀)/ /tmp 清 2.2GB / master-wt worktree 421MB / 20 个已合并本地分支 / index.db 旧归档。**杀进程保持人工**(需要人眼判断连接归属,自动化风险大于收益),每次大版本装机后人工过一遍。
|
||||
> Moved to [docs/lifecycle.md](docs/lifecycle.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -1,388 +1 @@
|
||||
# Message identity: content hashes as the cross-turn join key
|
||||
|
||||
Design record for how billion-context identifies an individual message across
|
||||
turns, and why identity is derived from message **content** rather than an
|
||||
id assigned at ingress and persisted by the host. Written after the #1496
|
||||
review; sibling document to `SESSION-IDENTITY.md` (which settles the same
|
||||
question at session granularity). Implementation anchors:
|
||||
`acp-kernel/src/wire/message-id.ts` (`deriveMessageId`),
|
||||
`acp-kernel/src/refs.ts` (`assignRefs`), `acp-kernel/src/prune.ts`
|
||||
(`isCovered`/`baseIdOf`). #2480 later split the question in two: the
|
||||
**kernel ledger** below stays content-hash, while the **fold-coverage
|
||||
re-anchoring layer** (`src/fold-reconcile.ts`) became positional-with-a-
|
||||
self-stored-canonical-copy — see “The fold-coverage layer goes positional”
|
||||
below; nothing in this document's ledger contract changed. #3641 later added
|
||||
the verdict layer on top — what happens when **no** channel verifies — see
|
||||
“The snapshot-as-session doctrine” below; the ledger contract still stands.
|
||||
|
||||
## The question is the join key, not the id
|
||||
|
||||
"Assign a per-message auto-increment id at ingress" is not a proposal the
|
||||
system lacks — it is what the kernel already does. Every inbound message gets
|
||||
an `mNNNNN` ref from a session-scoped, monotonically increasing, never-reused
|
||||
ledger (repo AGENTS.md: *Kernel Contract — message ids are never reused*).
|
||||
|
||||
The real question is what happens on turn N+1, when a stateless host
|
||||
re-serializes the whole array from its **private** storage: what key do we use
|
||||
to re-pin the ledger onto the new array? Position/order is falsified by
|
||||
production evidence (below). The only key that is stable across all five hosts
|
||||
and all four protocol lanes is the message's **content bytes**:
|
||||
|
||||
```
|
||||
wire bytes --sha256--> h_<sha16> --byRaw join--> mNNNNN (ledger ref)
|
||||
```
|
||||
|
||||
`deriveMessageId` hashes `role | contentType | toolCallId | toolName | text`;
|
||||
`assignRefs` then attaches the ref first-wins (`if (map.byRaw[message.id])
|
||||
continue`). The hash does not *replace* the auto-increment id — it is the
|
||||
**join** that lets the id be re-attached.
|
||||
|
||||
## Handled ≠ authored ≠ stored
|
||||
|
||||
The tempting inference "every message passes through us, so we can stamp an id
|
||||
on it, so 100% coverage" conflates three different properties. Verified per
|
||||
host:
|
||||
|
||||
| Host | Re-serializes from private storage each turn | Can our stamped id round-trip? |
|
||||
|---|---|---|
|
||||
| codex (Responses) | yes (rollout file; environment_context items rotate) | **partially** — response-side items only (#242) |
|
||||
| claude-code (anthropic chat) | yes (session JSONL) | no channel |
|
||||
| pi (chat, MITM/plugin) | yes (`convertToLlm()` rebuilds arrays; message model has no id field) | no channel |
|
||||
| omp | yes (pi-family plugin) | no channel |
|
||||
| hermes plugin | yes (own store, `pre_api_request` hook) | no channel |
|
||||
|
||||
Coverage must be measured at the **re-join point**, not at ingress.
|
||||
|
||||
## Lane survey: where could an id even live?
|
||||
|
||||
| Lane | Message-level id field | Verdict |
|
||||
|---|---|---|
|
||||
| anthropic chat | none (only `tool_use.id`/`tool_use_id` pairing keys) | no candidate |
|
||||
| openai chat | none (only `tool_calls[].id`) | no candidate |
|
||||
| google | none (only `functionCall`/`functionResponse` pairing ids) | no candidate |
|
||||
| responses | `input[].id` exists | **provider namespace**: #242 — our 66-char id exceeded the 64-char cap, 400 every turn; #1474/#1475 — Copilot requires `rs`-prefixed shapes; healing is now confined to our own `msg-proxy-*` namespace |
|
||||
|
||||
Three of four lanes have no field at all; the one that does has rejected
|
||||
locally-minted ids twice in production. Ingress deletes replayed `msg-proxy-*`
|
||||
ids (`src/loop/adapter-responses.ts:62-68`) precisely because they are
|
||||
per-round artifacts, not identities.
|
||||
|
||||
## What "original bytes never change" actually means
|
||||
|
||||
The claim is directionally right with one mandatory refinement: **bytes
|
||||
authored by the user/assistant are stable; slots authored by the environment
|
||||
rotate in place.** codex `environment_context` is rewritten every turn;
|
||||
anonymous OpenAI harnesses rotate the inline system `messages[0]` (#1148);
|
||||
nudge text is re-injected per turn (#728). This is why `SESSION-IDENTITY.md`
|
||||
keeps environment out of identity and why #1148's fix peels the leading
|
||||
system run out of the affinity hash.
|
||||
|
||||
The prefix is even less stable than the item: rolling-window truncation
|
||||
(dsh-class clients, 20–30 items), forks and rollback replays (#1148, #1102),
|
||||
one-message side requests (#1307: `ctx==1` → 163/163 compression failures,
|
||||
`ctx>1` → 62/62 successes), in-place rewrites (#1247), and host-side
|
||||
self-compression (codex `/compact`, claude-code `/compact`).
|
||||
|
||||
## Failure-mode asymmetry: misattribution vs non-recognition
|
||||
|
||||
- **Position/order join fails → misattribution.** A ref or compression block
|
||||
attaches to the *wrong* message; decompress returns wrong content; silent
|
||||
corruption that cannot self-heal. #1307's original ≤2 count guard was
|
||||
exactly this class of order heuristic failing.
|
||||
- **Content-hash join fails → non-recognition.** The conversation forks into
|
||||
a fresh session and rebuilds a cold cache. A performance loss that
|
||||
self-heals (#286 fork semantics).
|
||||
|
||||
Axioms should be chosen by their cheaper failure mode.
|
||||
|
||||
## Hosts must keep tool-call ids byte-stable within a conversation
|
||||
|
||||
The hash includes `toolCallId` as a factor, and the fold-reconcile layer
|
||||
(`src/fold-reconcile.ts`, #1921) uses it as its primary claim key:
|
||||
`tool_use.id` / `tool_call_id` are the only fields that are both
|
||||
protocol-unique per conversation and survive client re-serialization
|
||||
verbatim. That premise has one external dependency — the **host itself**
|
||||
must not rewrite those ids when projecting one conversation onto another
|
||||
provider. #2396 found a real violation: Prime (pi-family runtime) switched
|
||||
one conversation from Codex to a custom Responses provider, and its
|
||||
foreign-provider converter re-sanitized the stored composite ids —
|
||||
`call_switch_seed|fc_0_0` serialized as `call_switch_seed` on the Codex
|
||||
lane but went out as `call_switch_seed_fc_0_0` on the foreign lane, on both
|
||||
sides of every pair. Both claim passes key on the id, so every folded tool
|
||||
pair stopped matching: context billed at ~66,525 input tokens re-entered at
|
||||
558,541/562,549 against a 500,000-token window.
|
||||
|
||||
Bili's response follows the failure-mode axiom above: it does NOT guess
|
||||
old→new pairings (that would convert non-recognition into misattribution —
|
||||
decompress returning wrong content under a plausible-looking id swap). It
|
||||
detects the shape instead: a missing covered id whose normalized identity
|
||||
WITHOUT the toolCallId matches an inbound twin carrying a different
|
||||
toolCallId is counted as a rewrite suspect and named in the drift log
|
||||
(#2396), while the originals honestly re-enter the wire unfolded. The
|
||||
obligation belongs to hosts — see PLUGIN.md ("Obligations of a plugin",
|
||||
item 5): canonicalize ids at the host boundary before the payload reaches
|
||||
the proxy. The #2396 workaround (rewrite `call_id` + `call_output.call_id`
|
||||
together from the authoritative stored history before proxy processing) is
|
||||
the reference implementation of that duty.
|
||||
|
||||
#2480 later dissolved the detection-only stance for this class: the missing
|
||||
piece was **host knowledge of what the bytes used to be**, and the
|
||||
fold-coverage layer now keeps exactly that — a self-stored canonical copy
|
||||
(see next section). Position supplies the pairing, the stored fingerprint
|
||||
verifies it, so claiming across a host-rewritten id scheme is no longer a
|
||||
guess. The drift log and the honest re-entry fallback both remain for the
|
||||
cases the copy cannot cover (structural edits, beyond-window history).
|
||||
|
||||
## The fold-coverage layer goes positional (#2480)
|
||||
|
||||
The kernel ledger and the fold-coverage re-anchor answer different
|
||||
questions:
|
||||
|
||||
- **Ledger join** (turn N+1, re-pin `mNNNNN` onto the re-serialized array):
|
||||
content hash, unchanged, per everything above.
|
||||
- **Fold-coverage re-anchor** (which inbound messages are the ones my
|
||||
compression blocks already cover?): `src/fold-reconcile.ts` now answers
|
||||
this by **position plus a self-stored canonical copy**, ahead of the
|
||||
toolCallId and normalized-content passes it already had.
|
||||
|
||||
Mechanics: every reconcile pass rolls `foldPositions` — per-position
|
||||
`sha256-16` of `role | toolName | canonical text` (JSON-shaped text is
|
||||
key-sorted and compacted; prose keeps raw bytes; `toolCallId` and the
|
||||
`contentType` literal are excluded because they are exactly the tokens that
|
||||
re-encode across codecs; **reasoning is fingerprinted on role alone** — the
|
||||
responses adapter projects the provider item id as the core text, so hashing
|
||||
it would break every pairing at the first reasoning message of a churn).
|
||||
Pass 0 then aligns the churn region head-first and tail-first, claiming an
|
||||
old covered id onto its new counterpart **only when the fingerprint matches
|
||||
at the aligned position**; the first mismatch stops the scan, so mid-history
|
||||
insertions and deletions honestly refuse to bridge. Sessions without a copy
|
||||
(the entire installed base at upgrade time) pay nothing: the first steady
|
||||
pass stores the copy, and the *next* drift is claimed positionally —
|
||||
migration is free because "cannot be recognized" is itself a fresh sequence.
|
||||
|
||||
Why this does not contradict the position rejection below: raw position was
|
||||
rejected because with no memory of the old bytes, a positional claim is a
|
||||
**guess** and fails as misattribution. The copy converts the guess into a
|
||||
verified equality at an aligned offset — the same axiom, one layer up:
|
||||
fingerprint mismatch → honest non-recognition (unmatched, #1001/#1195
|
||||
lanes), never a wrong claim. The verification matrix lives in
|
||||
`tests/identity-proof.test.ts` (mechanism-level, judge-billed, after
|
||||
`tests/cache-proof.test.ts`): 4 wires × 3 phases (fold settles → id-scheme+
|
||||
serialization churn keeps coverage → mid-history edit honestly re-enters),
|
||||
a reconcile-off control proving the churn re-bills without the layer, a
|
||||
cross-wire client swap (anthropic → chat) retaining coverage end to end,
|
||||
and a model-switch phase (#2636): the chat lane carries reasoning-bearing
|
||||
assistant turns and image-bearing user turns, then replays the history onto
|
||||
a differently-shaped model (reasoning inlined pair→merged, images
|
||||
placeholdered) — coverage must survive the shape churn with the covered
|
||||
thinking never re-entering, judged on the FIRST post-churn body (a fresh
|
||||
server-side compress may re-fold a failed replay — the healed round-2 must
|
||||
never stand in for the retention proof), plus its own reconcile-off control
|
||||
proving this churn class re-bills without the layer.
|
||||
|
||||
## The snapshot-as-session doctrine: verdict classes over the id (#3641)
|
||||
|
||||
#2480 made fold coverage positional-with-verification. #3641 settles what
|
||||
happens when **no** channel verifies. The inversion: the **(session id +
|
||||
fold snapshot) is the conversation body** — the wire is only an alignment
|
||||
observation of it. Ids, hashes and shapes are hints; “which messages do my
|
||||
blocks cover, in what order” is the fact. Three production classes forced
|
||||
this: a protocol re-serialization re-minting every id with the words intact
|
||||
(#3640), image-offload rewriting a textless family into placeholders
|
||||
(#3588), and stateless clients truncating the covered slice (#2695) — all
|
||||
three used to be diagnosed as "substrate destroyed".
|
||||
|
||||
The mechanism (all in `src/fold-reconcile.ts` plus one kernel placement
|
||||
rule; proof tests in `tests/fold-anchor-doctrine.test.ts`):
|
||||
|
||||
- **Shape tier** (order-preserving): when a *mass* of covered ids goes
|
||||
missing at once (≥ `SHAPE_MASS_MIN`), residual prose anchors pair with
|
||||
inbound candidates in conversation order under the edit-honesty gate —
|
||||
word-bag equality + simhash ≤ 8 + role + length guard (the same gate the
|
||||
sim tier applies to gaps, applied to claims). Textless anchors (image
|
||||
families: no sh/wh by construction) pair k-th-to-k-th when bracketed by
|
||||
verified flanks on both sides and per-bucket counts match exactly — the
|
||||
byImage discipline generalized past bili's own placeholder variant.
|
||||
- **Residual census and verdict classes**: what the ladder cannot claim is
|
||||
*classified*, not assumed destroyed. `shapeExplained` (transform: claims
|
||||
or near-dup evidence carry the mass) — one info latch, streak reset.
|
||||
`truncationExplained` (benign deletion: residuals absent everywhere, zero
|
||||
near-dups, and a **wire-continuity witness** — the frozen old-order suffix
|
||||
still heads the inbound) — blocks snooze instead of reaping (#2695).
|
||||
Everything else is drift and escalates as before.
|
||||
- **Episode witness**: at the first drift pass the old order's tail is
|
||||
frozen (`foldEpisodeOrder`); a foreign conversation under the same session
|
||||
id has no continuity with it, so wholesale replacement cannot masquerade
|
||||
as truncation.
|
||||
- **Epoch-confirm gate**: total collapse latches `foldEpochConfirmPending`,
|
||||
emits one error, and preflight passes requests through verbatim — folding
|
||||
*pauses*; nothing is deleted, nothing is silently reset. Alignment
|
||||
recovery (the host resends the true history) auto-clears the latch.
|
||||
- **Unresolved-anchor placement** (kernel `prune.ts`): a block whose anchors
|
||||
all failed to resolve now inserts at the last user message instead of the
|
||||
tail — a summary block can no longer ride *after* the user's newest
|
||||
question (#3640's six tail-riding blocks).
|
||||
|
||||
The honesty boundary is deliberate: the shape tier requires **strict**
|
||||
word-bag equality, so a systematic content mutation — a host re-stamping
|
||||
history with a trailing `<system-reminder>` suffix, say — is *not* claimed
|
||||
as the same message (fuzzy content joins misattribute on decompress; see
|
||||
the rejected alternatives below). Such events classify as truncation or
|
||||
collapse and land on the snooze/pause paths — never a silent re-key.
|
||||
Whether a bulk identical-suffix re-stamp (N order-stable pairs sharing the
|
||||
exact same delta) deserves its own *verified* class is an open follow-up,
|
||||
to be sized against production logs (#3640/#3588).
|
||||
|
||||
Compatibility: the doctrine is a matching/verdict-layer change — zero
|
||||
migration, applies to old and new sessions alike, storage-independent
|
||||
(legacy JSON, shadow and full modes behave identically; bookkeeping rides
|
||||
session metadata). The kernel ledger's content-hash contract is untouched.
|
||||
|
||||
## The snapshot render engine: outbound identity moves server-side (#3756)
|
||||
|
||||
#3641 classified verdicts when no channel verifies. #3756 removes the
|
||||
dependence itself for the outbound path: with the `snapshotRender` rollout
|
||||
feature on (default 0%, `BILI_ROLLOUT_SNAPSHOT_RENDER`), the prepare layer
|
||||
no longer rebuilds history FROM the client's resent bytes — it renders the
|
||||
outbound prefix FROM the server's own unified-storage transcript
|
||||
(`src/server/snapshot-render.ts`):
|
||||
|
||||
- **Identity ladder, final form.** Conversation identity = the session
|
||||
binding (host-native session id whenever one exists — §"Prefer native
|
||||
stable identifiers"). Message identity inside a live conversation = the
|
||||
server snapshot row (`seq`), never re-minted. Content hashes/signatures
|
||||
demote to **chain-fallback evidence only** — they locate the divergence
|
||||
point where the client's verbatim tail hands over to the server prefix
|
||||
(id fast path, `role|contentType|toolName|text` + image-length signature
|
||||
fallback — the #3642 canonical form, so a full id re-mint still links).
|
||||
- **Coverage is self-owned by the engine.** Covered rows are suppressed by
|
||||
the block's seq/signature coverage set; `acp_summary_*` anchors re-render
|
||||
in place from block state. The engine does NOT trust the reconcile
|
||||
ladder's re-keyed block ids for this — reconcile may legitimately re-key
|
||||
blocks to freshly minted client ids (#3752's exact failure shape when a
|
||||
16384-anchor cap then dropped them).
|
||||
- **The tail stays client-verbatim.** Everything above the join point is
|
||||
forwarded byte-for-byte as the client sent it — the unfolded working set
|
||||
remains the client's own words, and prefix-cache stability is preserved
|
||||
turn-over-turn. Rewound-away rows sit below the join and never render.
|
||||
- **Degrade, never guess.** Feature off, no active blocks, storage
|
||||
unreadable, or the chain cannot link — the whole turn falls back to the
|
||||
legacy path unchanged. A client-side checkpoint of the head is adopted
|
||||
with a one-turn lag (the view is the previous turn's observation) and can
|
||||
never resurrect covered rows.
|
||||
- What this kills structurally: the #3752 anchor-cap cliff (MAX_ANCHORS ×
|
||||
id re-mints × stateless resend) and the #3751 image `_N` family churn —
|
||||
neither can drop or duplicate folded history anymore, because the
|
||||
rendered prefix follows block seqs and content signatures, not client
|
||||
bytes.
|
||||
|
||||
The #3641 reconcile/verdict layers stay: they remain the safety net for
|
||||
the lanes where D is off, unavailable, or degraded — and the observation
|
||||
channel (`reconcileFoldCoverage`) still watches the CLIENT view (render and
|
||||
observation are deliberately separate inputs).
|
||||
|
||||
## Images are payload-addressed, not family-numbered (#3751)
|
||||
|
||||
The `_N` instance discipline above assumes the base id already separates
|
||||
*which content* this is. Images broke that assumption until #3751: every
|
||||
image core carried the same canonical text (`[image]`), so all images in a
|
||||
conversation hashed to ONE shared base and the `_N` ordinals did all the
|
||||
separating — positionally. One image changing (offload placeholder, re-encode,
|
||||
delete) shifted every sibling's ordinal, re-minting the whole family on every
|
||||
turn (the #3748 write-amplification feeder).
|
||||
|
||||
The fix keeps the doctrine and closes the gap: the canonical seed grows a
|
||||
sixth slot, but only for media cores — `hash(imageBase64)` for data images
|
||||
(the bytes both codecs and the content CAS already hold), the URL string for
|
||||
URL-referenced images (no bytes on the wire — the URL is the only identity
|
||||
available), and the ordered join of part fingerprints for the rare legacy
|
||||
plural-sidecar core. Byte-identical images sharing a base id is intended:
|
||||
`_N` stays as the ordinal for *true duplicates* (the #459/#463 instance
|
||||
discipline, applied to what it was designed for). One image changing now
|
||||
re-mints only its own core. Text cores never gain the slot, so non-image ids
|
||||
stay byte-identical across the upgrade.
|
||||
|
||||
## Known cost of the hash axiom — and how it was fixed
|
||||
|
||||
Same bytes ⇒ same identity has a cost face: #1476 — a user re-sends a short
|
||||
text identical to already-folded content; the bare `h_` id re-derives;
|
||||
`isCovered()` swallows the fresh message. Note the **direction of the fix**:
|
||||
kernel #459 added instance renumbering (`_1/_2…`), and #463 added the
|
||||
`lastPassIds` snapshot to discriminate post-fold **echoes** (id ∈ covered ∧ ∈
|
||||
previous pass → keep id, prune swallows it) from genuinely **new instances**
|
||||
(id ∈ covered ∧ ∉ previous pass → renumber to a free `_k`). The content hash
|
||||
stays the base; only instance discrimination was layered on top. Even the
|
||||
hash axiom's own bugs are repaired by *keeping* the hash, not by retreating
|
||||
to positional ids.
|
||||
|
||||
## The partial round-trip channel that exists — and why it is not identity
|
||||
|
||||
#242 is double-edged evidence. It proves a real store-and-replay channel
|
||||
exists (codex persists our response-side `msg-proxy-*` ids into the rollout
|
||||
and replays them). It also proves the channel is unusable as identity:
|
||||
coverage is response-side items only (user-side items carry no id field),
|
||||
upstream constrains the namespace (64-char cap, `rs` prefix), and it exists on
|
||||
one lane of four. Its current use — round-2 lifecycle consistency plus
|
||||
ingress stripping — is the local optimum.
|
||||
|
||||
## Tags are derived views, not stored identity
|
||||
|
||||
The `<acp:mNNNNN…>` tags are printed at **egress** (toward the model) from the
|
||||
ref map and stripped at **ingress** from host-replayed bytes;
|
||||
`renderMessage()` removes the message's own stale tag before re-rendering
|
||||
(idempotent), while foreign tags survive as content. Identity never rides the
|
||||
round-trip: same bytes → same hash → same ref → same tag, every pass.
|
||||
|
||||
The tag-echo incidents (#206/#295, #14, #673) are the empirical proof of why
|
||||
this must stay so. Models sometimes imitate the rendered markup in visible
|
||||
prose; hosts store those bytes verbatim and replay them; the imitation
|
||||
amplifies (one stored message accumulated 77 echoed tags + ~3,300 blank lines
|
||||
— #14; a typo'd tag name `acip` became a turn's entire visible text — #673).
|
||||
The marker-into-storage channel is real but **dirty**: it typo-es, it
|
||||
amplifies, it namespaces badly. Any marker-as-identity scheme would stake
|
||||
identity on that channel. The design treats leaked markers as strippable
|
||||
noise (`src/loop/tag-echo-filter.ts`, prose only — tool-call arguments are
|
||||
never stripped, #1039) and re-derives identity from bytes.
|
||||
|
||||
## The one place upstream demands round-trip: strict-echo reasoning
|
||||
|
||||
DeepSeek-class gateways require the client to pass back the reasoning items
|
||||
the gateway itself emitted ("the reasoning content from the previous turn must
|
||||
be passed back in thinking mode"). This is the only mandated content
|
||||
round-trip in the fleet, and bili's handling shows the pattern: it is treated
|
||||
as a **repairable shape constraint**, not identity — #762 injected blank
|
||||
`reasoning_content` on the chat wire, #1479/#1482 extend the repair to the
|
||||
Responses wire and to loop retry paths, all gated on `isStrictReasoningEcho`
|
||||
(learned 400 flag or deepseek origin/model) so non-thinking sessions stay
|
||||
byte-identical. Identity bookkeeping is never involved.
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
| Direction | Why rejected |
|
||||
|---|---|
|
||||
| Ingress-assigned ids carried by host storage | No carrier field on 3/4 lanes; provider namespace rejections on the 4th (#242, #1475); coverage measured at re-join, not ingress (per-host table above). |
|
||||
| Position/sequence as join key | Prefix instability is documented across six incident classes (#1148, #1102, #1307, #1247, host `/compact`, our own fold); failure mode is silent misattribution. Still true for the **ledger join**; #2480 later adopted position **with a self-stored canonical copy** for the fold-coverage layer only, where per-position verification removes the guessing — see above. |
|
||||
| Near-match tolerance on content | Byte-exactness is load-bearing (same argument as `SESSION-IDENTITY.md`); fuzzy joins misattribute silently on decompress. |
|
||||
| Promote `msg-proxy-*` to identity | Single lane, response-side coverage only, amplification-prone channel (tag-echo evidence), upstream namespace constraints. |
|
||||
| Marker-as-identity (tags persisted by hosts) | The tag-echo incidents show the channel corrupts what it carries; current design already strips it at both ends. |
|
||||
| Implicit aliasing of host-rewritten tool-call ids | Pairing a missing covered id with an inbound twin that has identical content under a different toolCallId requires host knowledge; without it the claim is a guess and misattributes on decompress (#2396: Prime rewrote composite ids across a provider switch). Detection-only shipped; the fix belongs at the host boundary (PLUGIN.md obligation 5). #2480 update: Pass 0 now supplies that host knowledge (position + stored canonical fingerprint), so this class is claimed rather than only counted; PLUGIN.md obligation 5 stands for hosts that can canonicalize earlier. |
|
||||
|
||||
## Future direction
|
||||
|
||||
If a future host or lane offers a genuinely stable client-side message id,
|
||||
it may be adopted **only as an additional join hint** — never as a replacement
|
||||
for the content-hash base of the LEDGER join. The OUTBOUND join is a
|
||||
different question and already has its answer: with `snapshotRender` on,
|
||||
the outbound prefix is keyed by server snapshot `seq` (#3756, above) and the
|
||||
content-hash ladder serves only as the chain-fallback that finds the join
|
||||
point. Summary: bytes are the anchor, hashes are the ledger join, `seq` is
|
||||
the render join (rollout-gated), mNNNNN is the ledger, tags are the view.
|
||||
|
||||
Related: #1496 (this document's prompt), `SESSION-IDENTITY.md` (session
|
||||
granularity), #1476 + kernel #459/#463 (echo discrimination), #242/#1475
|
||||
(Responses id constraints), #206/#673 (tag echo), #1479/#1482 (strict-echo
|
||||
repair), #1039 (tool-call byte-exactness invariant), #2396 (host-rewritten tool-call ids across a provider switch), #2480 (positional fold coverage;
|
||||
`tests/identity-proof.test.ts` is its proof matrix), #2695/#3588/#3640/#3641
|
||||
(snapshot-as-session doctrine; `tests/fold-anchor-doctrine.test.ts`),
|
||||
#3642 (canonical cross-protocol identity — the chain-fallback's signature
|
||||
form), #3756 (the snapshot render engine; `tests/snapshot-render.test.ts`).
|
||||
> Moved to [docs/message-identity.md](docs/message-identity.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -1,153 +1 @@
|
||||
# 消息身份:内容哈希作为跨轮 join key
|
||||
|
||||
设计记录:billion-context 如何跨轮识别单条消息,以及为什么身份由消息**内容**派生、而不是在入口打一个由宿主持久化的 id。成文于 #1496 复核之后;与 `SESSION-IDENTITY.zh-CN.md`(会话粒度的同题文档)成对。实现锚点:`acp-kernel/src/wire/message-id.ts`(`deriveMessageId`)、`acp-kernel/src/refs.ts`(`assignRefs`)、`acp-kernel/src/prune.ts`(`isCovered`/`baseIdOf`)。#2480 随后把问题一分为二:下文的**内核账本**仍是 content-hash;而**折叠覆盖重锚层**(`src/fold-reconcile.ts`)改为「位置 + 自存规范副本」——见下文「折叠覆盖层改为位置身份」一节;本文档的账本契约未变。#3641 随后在其上补了判决层——**没有**任何通道验证成功时怎么办——见下文「快照即会话教义」一节;账本契约依然不变。
|
||||
|
||||
## 问题是 join key,不是 id
|
||||
|
||||
"在入口给每条消息打自增 id"并不是系统缺少的东西——内核已经在做:每条入站消息都会从会话内单调递增、永不复用的账本拿到 `mNNNNN` ref(repo AGENTS.md:*Kernel Contract — message ids are never reused*)。
|
||||
|
||||
真正的问题是第 N+1 轮:无状态宿主从**私有**存储重新序列化整个数组时,拿什么把账本重新钉回新数组?位置/顺序被生产证据证伪(见下);唯一在全部五个宿主 × 四条协议 lane 上都稳定的 key 是消息的**内容字节**:
|
||||
|
||||
```
|
||||
wire 原始字节 --sha256--> h_<sha16> --byRaw join--> mNNNNN(账本 ref)
|
||||
```
|
||||
|
||||
`deriveMessageId` 对 `role | contentType | toolCallId | toolName | text` 做
|
||||
sha256;`assignRefs` 再 first-wins 挂 ref(`if (map.byRaw[message.id]) continue`)。hash 不是**替代**自增 id,而是让 id 得以**复挂**的 join。
|
||||
|
||||
## 经手 ≠ 执笔 ≠ 存储
|
||||
|
||||
"每条消息都经手 → 能打 id → 100% 覆盖"这个推论混淆了三个概念。逐宿主验证:
|
||||
|
||||
| 宿主 | 每轮从私有存储重序列化 | 我们打的 id 能往返? |
|
||||
|---|---|---|
|
||||
| codex(Responses) | 是(rollout 文件;environment_context 逐轮更新) | **部分**——仅响应侧 item(#242) |
|
||||
| claude-code(anthropic chat) | 是(session JSONL) | 无通道 |
|
||||
| pi(chat,MITM/plugin) | 是(`convertToLlm()` 每次重建数组;消息模型无 id 字段) | 无通道 |
|
||||
| omp | 是(pi 系插件) | 无通道 |
|
||||
| hermes 插件 | 是(自有存储 + `pre_api_request` 钩子) | 无通道 |
|
||||
|
||||
覆盖率必须在 **re-join 时点**衡量,而不是 ingress 时点。
|
||||
|
||||
## Lane 普查:id 能放在哪?
|
||||
|
||||
| Lane | 消息级 id 字段 | 判定 |
|
||||
|---|---|---|
|
||||
| anthropic chat | 无(仅 `tool_use.id`/`tool_use_id` 配对键) | 无候选 |
|
||||
| openai chat | 无(仅 `tool_calls[].id`) | 无候选 |
|
||||
| google | 无(仅 `functionCall`/`functionResponse` 配对 id) | 无候选 |
|
||||
| responses | 有 `input[].id` | **服务商命名空间**:#242——66 字符超 64 上限,每轮 400;#1474/#1475——Copilot 要求 `rs` 前缀形状;healing 已收窄到自家 `msg-proxy-*` 命名空间 |
|
||||
|
||||
四条 lane 三条无字段;唯一有字段的 Responses 在生产中两次拒绝本地铸造的 id。ingress 删除回放的 `msg-proxy-*`(`src/loop/adapter-responses.ts:62-68`)正因为它们是逐轮合成物,不是身份。
|
||||
|
||||
## "原始字节永不变"到底指什么
|
||||
|
||||
方向正确,但必须修正为:**用户/助手执笔的字节稳定;环境执笔的槽位原地轮换。** codex `environment_context` 每轮重写;匿名 OpenAI harness 每轮轮换内联 system `messages[0]`(#1148);nudge 文本逐轮注入(#728)。这正是 `SESSION-IDENTITY.md` 把 environment 排除出身份、#1148 修复把头部 system run 剥出 affinity 哈希的原因。
|
||||
|
||||
前缀比单条更不稳定:滚动窗口截断(dsh 类客户端 20–30 项)、fork/回退重放(#1148、#1102)、单条侧请求(#1307:`ctx==1` → 163/163 压缩全败,`ctx>1` → 62/62 全成)、同位置改写(#1247)、宿主自压缩(codex `/compact`、claude-code `/compact`)。
|
||||
|
||||
## 失败模式不对称:认错 vs 认不出
|
||||
|
||||
- **位置/顺序 join 失效 = 认错。** ref/压缩块挂到错误消息;decompress 取回错误内容;不可自愈的静默损坏。#1307 原始的 ≤2 计数守卫正是这类顺序启发式的失败实例。
|
||||
- **内容哈希 join 失效 = 认不出。** 会话 fork 成新会话、重建冷缓存;可自愈的性能损失(#286 fork 语义)。
|
||||
|
||||
公理应按失败模式更轻者选择。
|
||||
|
||||
## 宿主必须在会话内保持工具调用 id 字节稳定
|
||||
|
||||
hash 以 `toolCallId` 为因子,fold-reconcile 层(`src/fold-reconcile.ts`,#1921)以它为主 claim key:`tool_use.id` / `tool_call_id` 是唯一既按会话协议唯一、又能在客户端重序列化中原样存活的字段。这个前提只有一个外部依赖——**宿主自身**不得在把同一会话投影到另一 provider 时改写这些 id。#2396 找到了真实违例:Prime(pi 系运行时)把同一会话从 Codex 切到自定义 Responses provider,其外部 provider 转换器对存储的复合 id 重新做了净化——`call_switch_seed|fc_0_0` 在 Codex lane 序列化为 `call_switch_seed`,在外部 lane 却发出 `call_switch_seed_fc_0_0`,且每一对的两侧都改。两条 claim pass 都以该 id 为键,于是所有已折叠的工具对全部失配:按 ~66,525 input token 计费的内容以 558,541/562,549 重新进入 500,000 token 窗口的 wire。
|
||||
|
||||
bili 的应对遵循上文的失败模式公理:**不猜** old→new 配对(猜了就是把"认不出"变成"认错"——decompress 在一个貌似合理的 id 替换后取回错误内容)。它只做形状检测:一个缺失 covered id,其**去掉 toolCallId** 的归一化身份与某个携带不同 toolCallId 的入站孪生消息相同,即计为一个 rewrite suspect 并在漂移日志中点名(#2396);原始内容则诚实地以未折叠状态重回 wire。义务在宿主一侧——见 PLUGIN.md("Obligations of a plugin"第 5 条):在 payload 到达代理之前于宿主边界规范化 id。#2396 中的 workaround(在处理前基于权威存储历史同步改写 `call_id` + `call_output.call_id`)就是这项义务的参考实现。
|
||||
|
||||
#2480 后来瓦解了这一类的「只检测」立场:缺的那块是**宿主对原始字节的记忆**,而折叠覆盖层现在恰好保有它——一份自存规范副本(见下节)。位置提供配对,存储的指纹验证配对,于是跨宿主改写 id 方案的 claim 不再是猜测。漂移日志与诚实重入兑底仍保留,用于副本覆盖不了的情形(结构性编辑、超出窗口的历史)。
|
||||
|
||||
## 折叠覆盖层改为位置身份(#2480)
|
||||
|
||||
内核账本与折叠覆盖重锚回答的是两个不同问题:
|
||||
|
||||
- **账本 join**(第 N+1 轮,把 `mNNNNN` 重新钉到重序列化的数组上):内容哈希,不变,遵循上文全部结论。
|
||||
- **折叠覆盖重锚**(哪些入站消息是我压缩块已覆盖的那些?):`src/fold-reconcile.ts` 现在用**位置 + 自存规范副本**回答,排在它原有的 toolCallId pass 与归一化内容 pass 之前。
|
||||
|
||||
机制:每个 reconcile pass 滚动写入 `foldPositions`——按位置的 `sha256-16`,输入 `role | toolName | canonical text`(JSON 形文本键排序紧凑化;散文保留原始字节;`toolCallId` 与 `contentType` 字面量被排除,因为它们恰是跨 codec 重编码的 token;**reasoning 仅按 role 指纹**——responses adapter 把 provider item id 投影为 core text,若参与哈希,每次 churn 的第一条 reasoning 就会断掉全部配对)。Pass 0 随后在 churn 区间内先头扫、后尾扫,**仅在指纹于对齐位置相等时**才把旧 covered id 认领到新对应物;首个失配即停,所以中点插入/删除会诚实地拒绝桥接。没有副本的会话(升级时点的全部存量)零成本:第一个稳态 pass 建立副本,*下一次*漂移即被位置认领——迁移免费,因为"认不出"本身就是新序列。
|
||||
|
||||
这与下文否决「位置当 join key」并不矛盾:裸位置被否决,是因为在没有旧字节记忆的情况下,位置 claim 是**猜测**,以认错告终。副本把猜测变成对齐偏移处的**已验证等值**——同一公理上移一层:指纹失配 → 诚实的认不出(unmatched,走 #1001/#1195 lane),永不认错。验证矩阵在 `tests/identity-proof.test.ts`(机制级、judge 计费,仿 `tests/cache-proof.test.ts`):4 wire × 3 阶段(折叠稳定 → id 方案+序列化 churn 后覆盖保持 → 中点编辑诚实重入)、reconcile-off 对照(无该层时 churn 重新计费)、跨 wire 客户端互换(anthropic → chat)端到端保持覆盖,以及切模型阶段(#2636):chat lane 携带 reasoning 助手轮与图片用户轮,随后把历史重放到另一个形状的模型(reasoning 内联 pair→merged、图片换占位行)——覆盖必须扛住形状 churn 且已覆盖的 thinking 不得重入,以 churn 后**第一个** body 为准(新的服务端 compress 可能把失败重放重新折回去——治愈后的 round-2 不得冒充保持证明),另有自己的 reconcile-off 对照证明无该层时此 churn 类会重新计费。
|
||||
|
||||
## 快照即会话教义:身份之上的判决分类(#3641)
|
||||
|
||||
#2480 让折叠覆盖变成「位置+验证」;#3641 则定论:**没有**通道验证成功时怎么办。反转在于:**(会话 id + 折叠快照)才是会话本体**——wire 只是对它的对齐观察。id、hash、形状都是提示;「我的块覆盖哪些消息、按什么顺序」才是事实。三类生产事故倒逼出这一层:协议重序列化把全部 id 重铸但词还在(#3640)、图片 offload 把无文本族改写成占位串(#3588)、无状态客户端截断已覆盖段(#2695)——三者过去都会被诊断为 "substrate destroyed"。
|
||||
|
||||
机制(全部在 `src/fold-reconcile.ts` 加一条内核摆位规则;证明测试在 `tests/fold-anchor-doctrine.test.ts`):
|
||||
|
||||
- **形状层**(保序):当一次性缺失**成片** covered id(≥ `SHAPE_MASS_MIN`)时,残留散文锚按会话顺序与入站候选配对,受编辑诚实门约束——词袋相等 + simhash ≤ 8 + role + 长度卫兵(sim 层用于 gap 的同一道门,用在 claim 上)。无文本锚(图片族:构造上无 sh/wh)在两侧被已验证的侧翼包夹、且逐桶计数恰相等时按第 k 对第 k 配对——byImage 纪律推广到 bili 自家占位变体之外。
|
||||
- **残差普查与判决分类**:阶梯认不下的部分被*分类*,而非假定已毁。`shapeExplained`(变换:claim 或近重证据承担了主体)——一次性 info latch,清零 streak。`truncationExplained`(良性删除:残差全部到处缺席、零近重、且**wire 连续性见证**——冻结的旧序尾部仍居于入站头部)——块休眠而非 reap(#2695)。其余照旧是 drift,照旧升级。
|
||||
- **episode 见证人**:首个 drift pass 冻结旧序尾部(`foldEpisodeOrder`);同会话 id 下的外来会话与它无连续性,整体替换无法冒充截断。
|
||||
- **epoch 确认门**:全塌 latch `foldEpochConfirmPending`,发一条 error,preflight 原样透传——折叠*暂停*;不删任何东西,不静默重置。对齐恢复(宿主重发真实历史)自动清 latch。
|
||||
- **未解析锚摆位**(内核 `prune.ts`):锚全部解析失败的块,插入点从尾部改为最后一个 user 消息——摘要块再也不会骑在用户最新提问*之后*(#3640 的六个骑尾块)。
|
||||
|
||||
诚实边界是有意的:形状层要求**严格**词袋相等,所以系统性内容突变——比如宿主给历史批量加/删尾部 `<system-reminder>` 后缀——**不会**被认成同一条消息(模糊内容 join 在 decompress 时认错;见下文被否决备选)。这类事件被分类为截断或全塌,落在休眠/暂停路径上——永不静默重键。批量同后缀重戳(N 对保序对共享完全相同的 delta)是否值得单独立一个*可验证*类,是待生产日志定界的开放跟进项(#3640/#3588)。
|
||||
|
||||
兼容性:教义是匹配/判决层变更——零迁移,新老会话一体适用,与存储无关(legacy JSON、shadow、full 三模式行为完全一致;记账走 session metadata)。内核账本的 content-hash 契约分毫米未动。
|
||||
|
||||
## 快照渲染引擎:出站身份移到服务端(#3756)
|
||||
|
||||
#3641 定论了「没有通道验证成功时怎么判」;#3756 则把依赖本身从出站路径上拆掉:灰度开关 `snapshotRender`(默认 0%,`BILI_ROLLOUT_SNAPSHOT_RENDER`)开启时,prepare 层不再**从客户端重发的字节**重建历史,而是**从服务端统一存储正史**渲染出站前缀(`src/server/snapshot-render.ts`):
|
||||
|
||||
- **身份阶梯最终形态**:会话身份 = 会话绑定(宿主原生 session id 优先,凡有即用);会话内消息身份 = 服务端快照行(`seq`),永不重铸;内容 hash/签名降级为**仅作链回溯兜底证据**——定位「客户端逐字尾巴让位给服务端前缀」的分歧点(id 快路径 + `role|contentType|toolName|text`/图片长度签名兜底,即 #3642 的 canonical 形态——id 全部重铸仍可链接)。
|
||||
- **覆盖由引擎自拥**:被覆盖行按块的 seq/签名覆盖集抑制;`acp_summary_*` 锚从块状态原位重渲。引擎**不信任** reconcile 阶梯 re-key 后的块 id——reconcile 合法地把块 re-key 到客户端新铸 id(恰是 #3752 在 16384 锚封顶下把它们丢掉的失败形状)。
|
||||
- **尾巴保持客户端逐字**:分歧点之上按客户端原字节转发——未折叠工作区仍是客户端自己的话,轮轮前缀缓存稳定。rewind 掉的行位于 join 之下,永不渲染。
|
||||
- **降级,不猜**:开关关/无活跃块/存储不可读/链接不上——整轮回退 legacy 路径,零变化。客户端头部 checkpoint 有一轮采用滞后(视图=上一轮的观察),且永不复活已覆盖行。
|
||||
- 结构性消灭:#3752 的锚封顶悬崖(MAX_ANCHORS × id 重铸 × 无状态重发)与 #3751 的图片 `_N` 族位移 churn——渲染前缀跟随块 seq 与内容签名,不再跟随客户端字节,这两类都再也无法丢/重折叠历史。
|
||||
|
||||
#3641 的 reconcile/判决层全部保留:它们仍是 D 关闭/不可用/降级时的安全网;观测通道(`reconcileFoldCoverage`)继续观察**客户端**视图(渲染与观测刻意分离)。
|
||||
|
||||
## 图片按载荷寻址,不再按家族编号(#3751)
|
||||
|
||||
上面的 `_N` 实例纪律有一个前提:base id 本身已经区分了「这是哪份内容」。
|
||||
图片在 #3751 之前打破了这个前提——每条图片 core 的规范文本都是同一个
|
||||
`[image]` 标记,一个会话里所有图片哈希出**同一个共享 base**,全靠 `_N`
|
||||
序号做区分——而序号是**位置敏感**的。一张图变化(offload 占位、重编码、
|
||||
删除)会把全族序号整体位移,每轮把整个家族的 id 重铸一遍(正是 #3748
|
||||
写放大事故的喂数机)。
|
||||
|
||||
修法保持教义、补上缺口:规范种子增加第六个槽位,但**只有媒体 core 才有**
|
||||
——数据图取 `hash(imageBase64)`(字节在 codec 与内容 CAS 两边都已经有),
|
||||
URL 图取 URL 字符串(wire 上没有字节,URL 是唯一可用的身份),罕见的
|
||||
legacy 复数 sidecar core 取各部件指纹的有序串。字节相同的图片共享 base
|
||||
id 是有意的:`_N` 保留给**真正的重复图**(回到 #459/#463 实例纪律的本职)。
|
||||
一张图变化现在只重铸它自己那条 core。文本 core 永不加该槽位,非图片 id
|
||||
跨本次升级逐字节不变。
|
||||
|
||||
## hash 公理的已知代价——以及修复方向
|
||||
|
||||
同字节 ⇒ 同身份有代价面:#1476——用户原样重发与已折叠内容相同的短文本;裸 `h_` id 重新派生;`isCovered()` 吞掉新消息。注意**修复方向**:kernel #459 加实例重编号(`_1/_2…`),#463 加 `lastPassIds` 快照区分折叠后**回声**(id ∈ covered ∧ ∈ 上一轮 → 保持 id,prune 吞掉)与真**新实例**(id ∈ covered ∧ ∉ 上一轮 → 重编号到空闲 `_k`)。content hash 始终是基座,只在其上叠加实例判别——连 hash 公理自己的 bug 都靠**保留 hash** 修,而不是退回位置 id。
|
||||
|
||||
## 存在的部分往返通道——以及为何不用作身份
|
||||
|
||||
#242 是双刃证据。它证明真实存在存回/回放通道(codex 把响应侧 `msg-proxy-*` id 存进 rollout 并回放);也证明该通道不能当身份:覆盖率仅响应侧 item(用户侧 item 无 id 字段)、上游约束命名空间(64 字符上限、`rs` 前缀)、四条 lane 仅此一条。它的现行用途(round-2 生命周期一致性 + ingress 剥离)就是局部最优。
|
||||
|
||||
## 标签是派生视图,不是存储的身份
|
||||
|
||||
`<acp:mNNNNN…>` 标签在**出站**(朝模型)从 ref map 打印、在**入站**从宿主重发字节剥离;`renderMessage()` 渲染前先剥消息自己的旧标签(幂等),外来标签当内容保留。身份从不依赖往返:同字节 → 同 hash → 同 ref → 同标签,每一轮。
|
||||
|
||||
标签回声事故(#206/#295、#14、#673)是"必须如此"的经验证明:模型有时在可见 prose 里模仿渲染标记;宿主原样存下回放;模仿被放大(一条消息累积 77 个回声标签 + ~3300 空行——#14;打错的名字 `acip` 成了一轮的全部可见文本——#673)。"标记进入宿主存储"的通道真实存在但**脏**:会打错、会放大、命名空间不可控。任何"标记当身份"的方案都等于把身份押在这条脏通道上。现行设计把泄漏的标记当可剥离噪声(`src/loop/tag-echo-filter.ts`,仅 prose——工具调用参数绝不剥,#1039),身份从字节重新派生。
|
||||
|
||||
## 上游唯一强制往返的地方:strict-echo reasoning
|
||||
|
||||
DeepSeek 类网关要求客户端传回网关自己发出的 reasoning("the reasoning content from the previous turn must be passed back in thinking mode")。这是全舰队唯一被强制的内容往返,而 bili 的处理方式展示了模式:当**可修复的形状约束**处理,不进身份——#762 在 chat wire 注入空 `reasoning_content`,#1479/#1482 把修复扩展到 Responses wire 和循环重试路径,全部门控在 `isStrictReasoningEcho`(学到的 400 标记或 deepseek 系),非思考会话字节恒等。身份账本从不参与。
|
||||
|
||||
## 被否决的备选
|
||||
|
||||
| 方向 | 否决理由 |
|
||||
|---|---|
|
||||
| 入口打 id、靠宿主存储携带 | 3/4 lane 无承载字段;第 4 条被服务商命名空间拒绝(#242、#1475);覆盖率在 re-join 时点衡量(见上表)。 |
|
||||
| 位置/顺序当 join key | 六类事故证明前缀不稳定(#1148、#1102、#1307、#1247、宿主 `/compact`、自身 fold);失败模式是静默认错。对**账本 join** 仍然成立;#2480 后来仅对折叠覆盖层采纳了「位置 + 自存规范副本」,逐位验证消除了猜测——见上文。 |
|
||||
| 内容近似匹配 | 字节精确性是承重墙(同 `SESSION-IDENTITY.md` 论证);模糊 join 在 decompress 时静默认错。 |
|
||||
| 把 `msg-proxy-*` 升级为身份 | 单 lane、仅响应侧覆盖、通道易放大(标签回声证据)、上游命名空间约束。 |
|
||||
| 标记当身份(标签由宿主持久化) | 标签回声事故证明该通道会污染所载内容;现行设计已在两端剥离。 |
|
||||
| 隐式别名化宿主改写的工具调用 id | 把一个缺失 covered id 与"同内容、不同 toolCallId"的入站孪生配对需要宿主知识;没有它,claim 就是猜测,decompress 时认错(#2396:Prime 跨 provider 切换改写了复合 id)。只交付检测;修复属于宿主边界(PLUGIN.md 义务 5)。#2480 更新:Pass 0 现在提供了那份宿主知识(位置 + 存储的规范指纹),这一类从"只计数"变为"可认领";能在更早边界规范化的宿主,PLUGIN.md 义务 5 依然成立。 |
|
||||
|
||||
## 未来方向
|
||||
|
||||
若未来宿主或 lane 提供真正稳定的客户端消息 id,只允许作为**附加 join hint** 采纳——永不替代 content-hash 基座。在那之前:字节是锚,hash 是 join,mNNNNN 是账本,标签是视图。
|
||||
|
||||
相关:#1496(本文档的起因)、`SESSION-IDENTITY.zh-CN.md`(会话粒度)、#1476 + kernel #459/#463(回声判别)、#242/#1475(Responses id 约束)、#206/#673(标签回声)、#1479/#1482(strict-echo 修复)、#1039(工具调用字节不变量)、#2396(跨 provider 切换时宿主改写的工具调用 id)、#2480(位置折叠覆盖;`tests/identity-proof.test.ts` 是其证明矩阵)、#2636(切模型形状 churn:assistant-turn key + 图片占位变体 pass)、#2695/#3588/#3640/#3641(快照即会话教义;`tests/fold-anchor-doctrine.test.ts`)。
|
||||
> 已迁移至 [docs/message-identity.zh-CN.md](docs/message-identity.zh-CN.md)。重定向占位,1–2 个版本后删除。
|
||||
|
||||
@@ -1,229 +1 @@
|
||||
# billion-context Cooperative Plugin Protocol
|
||||
|
||||
> Status: protocol v2, experimental. Implemented by the proxy (`src/plugin.ts`), exercised by `tests/plugin-protocol.test.ts`. Issue: dog/billion-context#1 ("内外呼应" — inside/outside cooperation).
|
||||
|
||||
## Why
|
||||
|
||||
Pure proxy mode works with any agent but is blind inside the agent: tools are injected at the wire level, the compress tool-call loop is emulated by intercepting and re-requesting SSE streams, and session identity has to be guessed from headers or content fingerprints. Pure extension mode (see billion-context-pi) has native integration but needs one adapter per agent.
|
||||
|
||||
The cooperative plugin mode splits the job:
|
||||
|
||||
| Concern | Owner |
|
||||
|---|---|
|
||||
| Tool registration (native UI, permissions, audit) | **plugin** (inside) |
|
||||
| The agent's own tool loop (multi-round calls) | **plugin / agent** (inside) |
|
||||
| Session identity | **plugin** (inside) — sends the real conversation id |
|
||||
| Compression engine + state + blocks | **proxy** (outside) |
|
||||
| History folding / ref tags / nudges | **proxy** (outside) |
|
||||
| Tool schemas + compression philosophy prompt | **proxy** — single source of truth, served to the plugin |
|
||||
|
||||
The plugin is deliberately a thin pipe: it registers whatever tools the manifest serves, forwards executions to the proxy, and returns the result text as a native tool result. Schema/prompt content always comes from the running proxy, so proxy and plugin can never drift.
|
||||
|
||||
## Protocol
|
||||
|
||||
All endpoints live under the proxy's admin gate (loopback + trusted-origin only).
|
||||
|
||||
### 1. `GET /__bili/plugin/manifest`
|
||||
|
||||
Fetch once at plugin startup.
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"protocolVersion": 2,
|
||||
"proxy": "billion-context",
|
||||
"version": "0.1.42",
|
||||
"toolNames": ["compress", "decompress", "search_context", "acp_status"],
|
||||
"tools": {
|
||||
"anthropic": [ /* Anthropic tool schemas */ ],
|
||||
"openai": [ /* OpenAI function schemas */ ],
|
||||
"responses": [ /* Responses API schemas */ ]
|
||||
},
|
||||
"headers": {
|
||||
"agent": "x-bili-plugin",
|
||||
"conversation": "x-bili-plugin-conversation",
|
||||
"contextWindow": "x-bili-plugin-context-window",
|
||||
"instructionsMutable": "x-bili-plugin-instructions-mutable"
|
||||
},
|
||||
"toolEndpoint": "/__bili/plugin/tool",
|
||||
"statusEndpoint": "/__bili/plugin/status",
|
||||
"capabilities": {
|
||||
"fork": { "protocolVersion": 2, "acceptsProtocolVersions": [1, 2], "endpoint": "/__bili/plugin/fork", "snapshotEndpoint": "/__bili/plugin/snapshot" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Register the tools natively with your agent, in whichever wire format your agent speaks — register exactly what `toolNames` lists. `absorb` appears only when the proxy's config enables it; `acp_rule` is advertised only when the proxy's config enables it (`compress.rules: true`, opt-in). Calling a tool that is known but disabled answers `200` with an explanatory `result` instead of an error (#1192). If `protocolVersion` is higher than you know, still register the tools — extra fields in schemas are ignored by agents.
|
||||
|
||||
### 2. Request headers
|
||||
|
||||
On **every model request** the plugin sends:
|
||||
|
||||
- `x-bili-plugin: <agent-name>` — announces plugin mode for this session.
|
||||
- `x-bili-plugin-conversation: <conversation-id>` — the agent's real conversation/session id, stable for the whole conversation.
|
||||
- `x-bili-plugin-context-window: <tokens>` (optional but recommended) — the model's context window as configured inside the agent (e.g. a pinned/overridden `contextWindow`). This becomes the authoritative "native" window for nudge decisions — it outranks the proxy's built-in table and the models.dev registry (most valuable for private relays and MITM mode), while operator tuning (`compress.modelContextLimit`) still outranks it.
|
||||
- `x-bili-plugin-instructions-mutable: 1` (optional; send only if true) — declares that your conversation ids are **persona-scoped**: one id per persona, and the request's system/instructions text may change mid-conversation without changing the persona (e.g. opencode re-renders AGENTS.md into `instructions` on every edit). The proxy now keys plugin conversation ids verbatim by default (#1106), so this flag is vestigial for current proxies — keep stamping it for compatibility with older proxy versions, which use it to stop mixing the instructions text into the compression-namespace fingerprint.
|
||||
|
||||
- `x-bili-plugin-agent: main` (optional) — vetoes side-request demotion for this one request. Requests are otherwise demoted to the verbatim side lane when they look like auxiliary traffic (#388: small `max_tokens`, or a known side persona such as opencode's title generator). A full main turn that re-sends the conversation can still trip those heuristics; stamping `main` keeps it on the kernel path so it captures history, stays compressible and remains forkable. Any other value declares the side persona id itself (it is then matched against the known side-request persona set, not treated as `main`).
|
||||
|
||||
Every proxied 2xx response carries `x-bili-session: <server-side session id>` (#4082) — the id the proxy itself keys this conversation by. A client that keeps its own conversation object may store it from any response and send it back as `x-bili-plugin-conversation` on later requests (retries, model switches, resends after resume), keeping identity stable even when the request is driven from an execution context the plugin cannot attribute. The dsh bridge does this automatically in-process (it learns the mapping while attribution works and re-stamps when it breaks); other hosts may adopt the header directly.
|
||||
|
||||
Effects on the proxy for that session:
|
||||
|
||||
- Wire-level tool injection is **suppressed** (tools are native; no duplicates).
|
||||
- The compress loop **never intercepts** proxy-named tool calls — a model-emitted `compress` call is forwarded to the agent verbatim, as a normal native tool call.
|
||||
- Session identity is keyed by the conversation id (strongest signal, ahead of all legacy session headers). This also fixes multi-session safety for agents that send no session headers at all.
|
||||
- The compression philosophy system prompt, ref tags and nudges keep flowing from the proxy, exactly as in wire mode.
|
||||
|
||||
### 3. `POST /__bili/plugin/tool`
|
||||
|
||||
Execute a tool against the conversation's compression state.
|
||||
|
||||
```json
|
||||
{
|
||||
"conversationId": "the same value you send as x-bili-plugin-conversation",
|
||||
"tool": "compress",
|
||||
"args": { "content": [{ "startId": "m00001", "endId": "m00042", "summary": "...", "topic": "..." }] }
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{ "ok": true, "tool": "compress", "conversationId": "...", "outcome": "applied", "blocksCreated": 1, "result": "[Compressed m00001–m00042 → 1 block(s), ~1742 tokens saved.]" }
|
||||
```
|
||||
|
||||
Return `result` verbatim as the native tool result content. `ok` reflects transport + execution only (it stays `true` when the kernel refuses a fold range — the refusal receipt then sits in `result`). The machine-readable business outcome rides in the additive `outcome` field (#1875): for `compress` it is `applied` / `partial` / `refused` plus `blocksCreated`; for every other tool `success` / `failure`. Older proxies omit both fields; the #1192 disabled-note answer stays exactly `{ ok: true, result }`.
|
||||
|
||||
Notes:
|
||||
|
||||
- Execution happens **under the session lock**, against the same view the model was shown on the last request (refs match what the model sees).
|
||||
- Optional `expectedRevision` is the opaque `parentRevision` from a snapshot. It requires an explicit `conversationId` and is checked under the same session lock immediately before execution. A stale revision returns `409 PARENT_REVISION_CONFLICT` without executing the tool. This also avoids witness routing to another conversation. Existing callers omitting it retain their routing and execution behavior.
|
||||
- `compress` mutates state. Inline `decompress` marks a block restored for re-folding; range restores queue content for the next request. Successful restores also update the estimated context footprint. `search_context` / `acp_status` are read-only.
|
||||
- Errors: `400` invalid JSON / missing `conversationId` / unknown tool, `404` unknown conversation (no model request has arrived with that conversation id yet), `500` execution failure. A **known but disabled** opt-in tool (`absorb` / `acp_rule`) is not an error: it answers `200` with `ok: true` and a `result` explaining that the feature is off on this proxy (#1192).
|
||||
|
||||
### 4. `GET /__bili/plugin/status?conversationId=<id>`
|
||||
|
||||
Context-level visibility for plugin UIs (status bars / slash commands):
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"conversationId": "...",
|
||||
"sessionId": "...",
|
||||
"pluginAgent": "pi",
|
||||
"contextLimit": 200000,
|
||||
"contextTokens": 138211,
|
||||
"contextTokensSource": "usage",
|
||||
"contextTokensAt": 1755300000000,
|
||||
"contextGeneration": "opaque-generation",
|
||||
"sessionRevision": "opaque-revision",
|
||||
"model": "claude-sonnet-4",
|
||||
"inputTokens": 251000,
|
||||
"outputTokens": 40021,
|
||||
"cachedTokens": 180000,
|
||||
"requests": 42,
|
||||
"blocks": [{ "id": "b3", "tier": 1, "active": true }],
|
||||
"lastSeen": 1755300000000
|
||||
}
|
||||
```
|
||||
|
||||
`contextTokens` is the effective current input footprint, not accumulated billing. `contextTokensSource` is `usage` only for a real positive upstream input measurement with no outstanding fold credit, `estimate` for a local projection, or `unavailable` with `contextTokens: null`. Manual `compress` subtracts only its new credit from the previous observation, once; successful `decompress` adds the returned content (or file pointer) and any newly queued range content. Both publish an independent `estimate` observation without replacing the last-usage calibration baseline or changing cumulative `inputTokens` / `cachedTokens`. Never add those billing fields to infer effective context.
|
||||
|
||||
Forwarding a new model request replaces the previous observation with an estimate until a real positive usage report arrives. That report restores `usage`; zero/missing usage cannot revive an older measured generation. A real report netted against outstanding fold credit remains an estimate of the effective view, not a measurement of that view. Forks start with independent estimates, not inherited parent usage.
|
||||
|
||||
`contextTokensAt` is the observation time in Unix milliseconds (not the status read time), independently of the last usage timestamp. `contextGeneration` is an opaque change detector covering a unique observation id, context, revision, model and limit: successive observations remain distinct even at the same timestamp with identical token counts; repeated status reads do not create observations. Unavailable context has null tokens, timestamp and generation. Legacy persisted sessions without an independently attributed observation are unavailable until another request establishes one. `sessionId` and nullable `sessionRevision` identify the resolved session and its fork state. Pre-first-request/chain-only responses explicitly report unavailable context. Persisted sessions are loaded by the requested id before considering an explicitly requested `fallback=latest`. Errors: `400` missing `conversationId`, `404` unknown conversation.
|
||||
|
||||
`compressibleRanges` is the live kernel recommendation as structured `{startRef, endRef, count, ...}` entries for `sessionRevision`, or `null` if it cannot be computed. An empty list means there is no recommended range. Read the exact conversation without `fallback=latest`, match the snapshot revision and ordered refs, and submit manual `compress` with `expectedRevision`; never parse the human panel or guess a fixed prefix. Hosts must exclude their retained first-user anchor from summaries: kernel pruning retains it even if a recommendation spans it. A concurrent mutation is rejected by the revision guard.
|
||||
|
||||
### 5. `POST /__bili/plugin/compact`
|
||||
|
||||
Notify the proxy that the agent performed an **in-session native compaction** (e.g. omp's `/compact` or its auto threshold): the next model request re-sends a shortened history (compaction summary + retained tail) under the SAME conversation id. Fire-and-forget is fine — a failed notification must never break the agent's compaction.
|
||||
|
||||
```json
|
||||
{ "conversationId": "the same value you send as x-bili-plugin-conversation" }
|
||||
```
|
||||
|
||||
Effect: the proxy marks a one-shot compaction boundary on the session. On the next model request, blocks that were active before the compaction but no longer anchor into the shortened history are downgraded to a pre-compaction archive (listed by `acp_status` with a reason; `decompress` on one returns an explicit "unavailable" error instead of failing silently), and stale `byRaw`/`byRef` mappings are pruned to the live ids. Errors: `400` invalid JSON / missing `conversationId`, `404` unknown conversation.
|
||||
|
||||
### 6. MITM transparent-proxy mode
|
||||
|
||||
The `/bili/` prefix is absent in MITM mode, so URL-based detection cannot work. Instead the proxy's own launcher (`bili pi` / `bili codex` / `bili claude`) exports `BILLION_CONTEXT_PROXY=http://127.0.0.1:<port>` in the child env, next to the `HTTPS_PROXY` + CA vars it already sets. A plugin detects cooperative mode by reading that env var (the proxy origin for all `/__bili/plugin/*` calls); everything else (headers, tool forwarding, status) is identical — the `x-bili-plugin*` headers pass through the MITM tunnel into the same pipeline. This is also where `x-bili-plugin-context-window` matters most: MITM upstreams are often private relays the models.dev registry doesn't know.
|
||||
|
||||
### 7. Lifecycle of one compression (what the plugin does)
|
||||
|
||||
1. Model replies with a native `compress` tool call (args contain `startId`/`endId` refs it read from the tag-annotated context).
|
||||
2. The agent ends the assistant turn; the plugin's tool handler fires.
|
||||
3. Plugin POSTs `{conversationId, tool: "compress", args}` to `/__bili/plugin/tool`.
|
||||
4. Plugin returns `result` as the tool result; the agent appends it to history and re-requests.
|
||||
5. The next model request carries the tool call + result in history; the proxy's `processTurn` hides the consumed call and folds the compressed range out of the wire body. The summary lives in block state, retrievable via `search_context` / `decompress` — the same as wire mode.
|
||||
|
||||
No special handling is needed for decompression: `decompress` results come back through the same endpoint.
|
||||
|
||||
### 8. Public snapshot and fork (fork protocol 2; v1 clients still accepted)
|
||||
|
||||
Discover `capabilities.fork` from the manifest; do not infer support from the package version. No new configuration is required. These endpoints use the same admin gate and request-body limit as the tool API.
|
||||
|
||||
`GET /__bili/plugin/snapshot?conversationId=<stable-parent-id>` returns:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true, "protocolVersion": 2, "status": "exact",
|
||||
"conversationId": "parent", "sessionId": "parent",
|
||||
"parentRevision": "<opaque SHA-256 revision>",
|
||||
"orderHash": "<SHA-256 of the full orderedMessages JSON>",
|
||||
"orderedMessages": [{ "rawId": "h_example", "ref": "m00001", "identityHash": "<opaque SHA-256 identity>" }],
|
||||
"messages": [{ "rawId": "h_example", "ref": "m00001", "role": "user", "text": "original text", "contentType": "text" }]
|
||||
}
|
||||
```
|
||||
|
||||
`messages` is in exactly the same order as `orderedMessages`, describes the raw `pluginSnapshot` rather than a folded view, and includes optional `text`, `toolName`, and `toolCallId`. Compare original text and role to establish the longest matching prefix; tool identities/content type must match too. Copy the corresponding ordered identities verbatim; `identityHash` and revisions are opaque and clients do not need a content-hash algorithm. A message the kernel hard-excludes from compression (`compress.protectedTools`) carries `"ref": null` in both arrays — it participates in ordering and identity but has no addressable ref; copy it verbatim like any other prefix entry. Only `mNNNNN` strings or `null` are legal ref values. Multimodal/opaque content that cannot be verified by this text projection returns `409`, `status: unavailable`, `code: SNAPSHOT_UNAVAILABLE`, not a guessed text match. Missing raw snapshots or inconsistent raw/ref/CCR mappings likewise fail closed. Raw snapshot retention is capped (`BILI_PUBLIC_SNAPSHOT_CAP_BYTES`, default 16 MiB, `0` disables): a session whose serialized raw snapshot grows past the cap stops being forkable — snapshot/fork answer `409 SNAPSHOT_UNAVAILABLE` — instead of retaining an unbounded raw copy forever.
|
||||
|
||||
`POST /__bili/plugin/fork` body:
|
||||
|
||||
```json
|
||||
{
|
||||
"protocolVersion": 2,
|
||||
"parentConversationId": "parent", "childConversationId": "new-child",
|
||||
"parentRevision": "<snapshot.parentRevision>",
|
||||
"branchPoint": { "messageCount": 1, "orderHash": "<prefix order hash>" },
|
||||
"orderedMessages": [{ "rawId": "h_example", "ref": "m00001", "identityHash": "<snapshot identity>" }],
|
||||
"idempotencyKey": "stable-operation-id"
|
||||
}
|
||||
```
|
||||
|
||||
`protocolVersion` is `2` (current) or `1` (legacy) in both directions; the proxy accepts either (`acceptsProtocolVersions` in the manifest advertises this) and rejects anything newer with `400 INVALID_REQUEST`. Under protocol 2 the `parentRevision` token covers exactly the session id, the ordered-prefix length (`messageCount`), and the active block set — so routine stats churn (context estimates, usage bookkeeping) no longer changes the revision, while any structural change (messages appended or rewritten, a block folded or unfolded) still does. Protocol-1 clients that present the legacy whole-store revision token are still matched during the transition window; treat `parentRevision` as opaque in both cases: on `409 PARENT_REVISION_CONFLICT` take a fresh snapshot and re-match, regardless of which protocol version you speak.
|
||||
|
||||
The branch is an ordered prefix, including an empty prefix. Compute its existing order hash as lowercase SHA-256 of UTF-8 `JSON.stringify(orderedMessages)` with each identity object's keys in order `rawId`, `ref`, `identityHash`; for a full prefix reuse snapshot `orderHash`. Do not hash descriptors or folded text. Extra child messages, including a final model reply that has not left the proxy yet, may be appended on the child's first model request after copying the matched prefix.
|
||||
|
||||
New success is `201`; exact payload replay is `200` with `replayed: true`, even after restart or later parent changes. Both return `status`, `parentRevision`, `childRevision`, `sessionId`, `branchPoint`, `inheritedBlocks`, and `expandedBlocks`. Reusing the child id with another parent, key or payload returns `409 CHILD_CONFLICT`. Invalid shapes/version/identifiers return `400 INVALID_REQUEST`; absent parent returns `404 PARENT_NOT_FOUND`; stale parent returns `409 PARENT_REVISION_CONFLICT`; altered order/raw/ref/identity returns `409 BRANCH_POINT_CONFLICT`. Missing nested originals return `409 PARENT_STATE_INCOMPLETE` with `status: unavailable`. Publication/persistence failure returns `503 FORK_FAILED` with `status: unavailable` and exposes no child; the same request may be retried.
|
||||
|
||||
Boundary handling is `exact` when complete blocks fit inside the prefix, `expanded` when a block crosses it (crossing summaries are omitted, affected nested descendants are expanded, matched originals are retained), and `unavailable` when safe reconstruction is impossible. Blocks, nested caches, raw messages, issued ref namespace, token snapshots, rules and prefix CCR payloads are independent copies. Note that the child inherits the parent's ENTIRE issued-ref namespace (dead refs included): refs are never reused, so forks keep allocating fresh refs without colliding with ids a sibling may still hold. The child never reads its parent's later state as a fallback. Registration and first-request resume heuristics do not replace its copied state. With existing persistence enabled, raw snapshots, receipts, nested originals and the child's CCR payloads survive restart; with persistence disabled, durability is not promised. Atomic child publication/idempotency covers concurrent requests to one proxy process; concurrent writers sharing one state directory across processes are not supported by this protocol.
|
||||
|
||||
Lineage-only declaration (#2408): a host that cannot drive the full fork protocol (no snapshot matching, e.g. claude `--fork-session`) may still declare the parent by sending a plain identity register — `POST /__bili/plugin/register` with `conversationId` (the fresh child id), `identity: true` and `parentConversationId` — from its SessionStart hook. The declaration scopes the proxy's content-match resume inheritance (#1486) to that parent chain, so a byte-exact replay of the parent's wire history seeds refs/blocks on the child's first request, and a non-matching replay falls back to the read-only parent link (#1333). A later register without `parentConversationId` never erases the declared parent. This is strictly weaker than §8 (no dead-ref namespace, no nudge inheritance, no receipt verification) but needs no snapshot access.
|
||||
|
||||
Incremental turns (#3248; not yet advertised in the plugin manifest — detect by trying the endpoint and handling the 503): a host that keeps its own full local history may stop resending it. `POST /__bili/plugin/turn` (same `/__bili/` gate; headers `x-bili-plugin` + optional `x-bili-plugin-model`, `x-bili-plugin-context-window`, `x-bili-plugin-max-output`) with `{ conversationId, sinceSeq, resync?, system?, path?, request, messages }`. The first turn (or any recovery) sends `sinceSeq: 0` + the full `messages[]` (`resync: true` is implied on seed — a wholesale replacement never 409s and works whether the canonical is empty or already live); every later turn sends ONLY what the client added since the last ack — including the previous assistant reply (client-owned). `request` carries anthropic params (model, max_tokens, temperature, top_p, top_k, stop_sequences, stream, tools, tool_choice, metadata, thinking, service_tier, parallel_tool_calls); `system` is sticky (omit to keep the last one); `path` defaults to `/v1/messages` (bare relative rides the lane's default upstream; the `/bili/<upstream>/…` form is explicit). The response is the upstream body streamed through, with `x-bili-applied-seq` = the canonical length after applying the delta — echo that value as the next turn's `sinceSeq`. `409 { error: "seq-mismatch" | "turn-in-flight", serverSeq }` means the client MUST recover with a resync turn (`sinceSeq: serverSeq` if it still has the history, else `resync: true` full seed). `503` means the lane runs without `storage.unified` (the canonical log lives in the unified messages table). The lane owns no session identity of its own: the assembled request carries the client's own `x-bili-plugin-conversation`, so incremental and normal full-resend traffic for one conversation share one session, one fold ledger and one canonical — switching modes needs no ceremony, and a conversation may interleave them (e.g. fall back to full resend while a resync is pending). Folding, nudges, tools and the plugin tool endpoints all work unchanged on the assembled body; the model never sees the difference. v1 caveats: the canonical log is the session's messages table — a turn is acked after the assembled body is persisted (best-effort immediate flush; a crash in between surfaces as 409 → resync), and the pipeline still walks the assembled prefix (O(full) CPU, cheap and zero-hit — the server-authored fast path is tracked on #3248). A `resync: true` that replaces a diverged canonical records a base-seq epoch (`session_ext` key `inc:base-seq`): the stale branch's rows stay in the append-only log for audit, but cold rebuilds slice past them — one resync heals, restarts included. On legacy-only storage (no ext surface) the marker degrades and cold rebuilds serve the full row union (409 → resync once, as before).
|
||||
|
||||
Marker divert (#3248 phase 2 — native extensions): instead of switching the provider URL to the turn endpoint, a host may send the incremental body on its ORDINARY model request. Stamp `x-bili-plugin-turn: 1` on the request (the lane requires `x-bili-plugin` too, as for every plugin signal); the body shape — top-level `conversationId` + `sinceSeq` + `messages`, no top-level `model` — is the final word: a marker'd body that is NOT incremental-shaped rides the normal pipeline byte-identically, so a host may stamp the marker whenever the feature is enabled and only convert turns it wants. Incremental-SHAPED turns are lane traffic and carry the same trust class as the direct turn endpoint (#3343): non-loopback / tunnel / untrusted-origin callers get 403 on them (their capability probe already 403s, so a well-behaved host never sends deltas from afar), and management prefixes (`/__bili/`, `/__acp/`) never ride the divert. The lane forwards the assembled request to the ORIGINAL request path (bare or `/bili/…` — no provider reconfiguration). Capability probe: `GET /__bili/plugin/turn` → `{ ok, protocol: 1, feature: "pluginIncrementalTurns", enabled, storage }` (loopback-gated like every `/__bili/` surface; a 404 = older server, stay full-resend). Gating: rollout feature `pluginIncrementalTurns` (default 0% = every install byte-identical to before) — enable with `rollout.features.pluginIncrementalTurns: true` (or a percent) in the bili config, or `BILI_ROLLOUT_PLUGIN_INCREMENTAL_TURNS=1`; the feature additionally requires a live unified sidecar (shadow or full). When disabled mid-flight the lane answers 503 on incremental-shaped turns — fall back to a plain full-resend request. Reference host wiring: pi rides its `before_provider_headers` (marker) + `before_provider_request` (payload replacement) + `after_provider_response` (ack) extension events; dsh-native rides the fetch patch's `beforeSend` (body conversion) + `headersFor` (marker) + `onResponse` (ack). pi-native inherits the pi wiring unchanged (same extension factory — only proxy discovery differs). opencode rides its `http.request` hook (an `incremental` adapter callback appended after routing/stamping swaps the request body via `replaceRequestPayload` and stamps the marker on the replaced request; acks land on the fetch intercept's `onResponse`). omp has no header events at all — its native adapter reads the extension-stamped `prompt_cache_key` body field as the conversation id inside `beforeSend`, stamps the plugin headers directly on the request init (identity upgrades, never forks: wire mode already resolves the same value via `preferPromptCacheKeyIdentity`), and acks on `onResponse`. Non-Anthropic wire shapes (OpenAI `tool_calls`/`role:"tool"`) are detected by `wireMessagesLookAnthropic` and left on full resend — the lane's message ingestion is the anthropic wire. Planned turns are single-in-flight per URL and age out after 30s (a network-dead request must not block the URL forever). The shared client state machine lives in `src/agent/incremental-client.ts` (probe TTL cache, prefix-hash diffing, sticky system, per-conversation dead flag) — new native hosts should reuse it rather than re-implement the diffing.
|
||||
|
||||
中文增量要点(#3248):`POST /__bili/plugin/turn`,首次/恢复用 `sinceSeq:0` 全量(种子隐含 `resync:true`,永不 409);此后每轮只发新增(含上一轮 assistant 回复,客户端自持)。响应即上游原文,`x-bili-applied-seq` 为应用后的长度,下一轮作 `sinceSeq` 回传。409 必须按 serverSeq 对齐或全量重同步;503 表示未开 storage.unified。会话身份沿用客户端自己的 conversation id——增量与全量重发同一会话可任意切换,折叠/工具/状态栏不变。阶段 2(标记分流):普通模型请求上盖 `x-bili-plugin-turn: 1` 头 + 增量形状 body(顶层 conversationId/sinceSeq/messages、无顶层 model)即可,增量形状 turn 属 lane 流量,与直连 turn 端点同信任级(#3343):非回环/隧道/不可信源一律 403(其探针本就 403,正常宿主不会远程发增量);管理前缀(`/__bili/`、`/__acp/`)永不走分流。lane 按原始 URL 转发;探针 `GET /__bili/plugin/turn`;开关 rollout `pluginIncrementalTurns`(默认 0%=零变化,`BILI_ROLLOUT_PLUGIN_INCREMENTAL_TURNS=1` 或配置强制开)。客户端状态机在 src/agent/incremental-client.ts,新宿主复用勿重写。已接宿主:pi/pi-native(同一扩展工厂,后者零代码继承)、dsh-native(fetch 补丁 beforeSend/headersFor/onResponse)、opencode(http.request 钩子 incremental 适配回调换 body+盖章)、omp(无头事件通道,读 body 里 prompt_cache_key 当会话 id,直接在 init 上盖章);OpenAI 工具形状(tool_calls/role:tool)自动回退全量重发;每 URL 单飞行+30s 过期。
|
||||
|
||||
中文集成要点:fork 协议现为 2(服务端同时接受 1);先读取 manifest 能力及 snapshot,按原文、role、工具身份确认匹配前缀,仅提交该前缀的 orderedMessages,不猜测多模态分支点。被 `compress.protectedTools` 硬排除的消息在两个数组中均为 `"ref": null`(参与顺序与身份、无地址 ref),与其他前缀条目一样逐字提交;ref 合法值仅 `mNNNNN` 字符串或 `null`。父 revision 变化必须重新取快照并重新匹配。子会话使用独立稳定 id,首次请求可追加尚未出站的模型回复,不能重置继承的 refs/blocks。手动摘要使用 snapshot 的 refs 和 `expectedRevision: snapshot.parentRevision` 调用公开 tool;摘要期间历史发生变化时返回 409,不执行旧摘要。状态栏读取 `contextTokens`、`contextTokensSource`、`contextTokensAt`、`model`、`contextLimit`、`contextGeneration`、`sessionId` 与 `sessionRevision`,不得用累计账单 input/cache 冒充有效上下文。手动 compress/decompress 后为独立时间及 generation 的 estimate,不改累计账单或 last-usage 基线;下一次正数 usage 才恢复 usage,零值或缺失 usage 不得复活旧观测。未知来源返回 unavailable,tokens/time/generation 为 null。
|
||||
|
||||
## Security
|
||||
|
||||
- The tool endpoints sit behind the `/__bili/` admin gate: loopback-only + trusted-origin. A plugin on the same machine as the proxy can call them; nothing else can.
|
||||
- Plugins only need to talk to the proxy on localhost; no extra credentials. Do NOT expose the proxy's plugin endpoints through reverse proxies.
|
||||
|
||||
## Obligations of a plugin
|
||||
|
||||
1. Register the tools from the manifest (all of them as listed; the model relies on the full set).
|
||||
2. Send both headers on every model request through the proxy.
|
||||
3. Forward tool executions verbatim; return `result` as the tool result.
|
||||
4. Self-disable when not running behind bili (e.g. the agent's baseURL does not point at the proxy) — same convention as billion-context-pi / opencode-acp extensions.
|
||||
5. Keep tool-call ids byte-stable within one conversation, including when projecting it onto another provider. Tool-message identity keys on `toolCallId` as the protocol-stable pairing factor; a projection that rewrites those ids (e.g. sanitizing stored composite ids for a foreign Responses provider) silently loses fold coverage — compressed tool outputs re-enter the wire unfolded (#2396). Canonicalize ids at the host boundary before the payload reaches the proxy; the proxy detects the shape and names it in the fold-drift log, but never repairs onto guessed pairings (see MESSAGE-IDENTITY.md).
|
||||
|
||||
## Reference
|
||||
|
||||
- Proxy implementation: `src/plugin.ts`, wiring in `src/server.ts` (search `pluginMode`).
|
||||
- Tests: `tests/plugin-protocol.test.ts`.
|
||||
> Moved to [docs/plugin-protocol.md](docs/plugin-protocol.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -0,0 +1,731 @@
|
||||
# billion-context
|
||||
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a> | <a href="./README.ja.md">日本語</a></p>
|
||||
|
||||
<p align="center"><strong>コンテキスト圧縮プラグイン</strong> — <em>billion-context is all you need.</em></p>
|
||||
|
||||
<p align="center"><sub>小さなコンテキストウィンドウ(100K で十分) · <em>トークンを 5 分の 1 に</em> · 1 か月続く単一のセッション(数十億トークン) · 高い圧縮品質</sub></p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.npmjs.com/package/billion-context"><img src="https://img.shields.io/npm/v/billion-context.svg?style=flat-square" alt="npm"></a>
|
||||
<a href="https://github.com/ranxianglei/billion-context/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/billion-context.svg?style=flat-square" alt="license"></a>
|
||||
<a href="https://github.com/ranxianglei/billion-context"><img src="https://img.shields.io/badge/GitHub-ranxianglei%2Fbillion--context-181717?style=flat-square&logo=github" alt="GitHub"></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<code>npm install -g billion-context --prefix=~/.local</code>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://claude.com/product/claude-code" title="Claude Code"><img src="https://cdn.simpleicons.org/claude/D97757" height="26" alt="Claude Code"></a>
|
||||
<a href="https://github.com/openai/codex" title="Codex"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.iconify.design/simple-icons/openai.svg?color=white"><img src="https://api.iconify.design/simple-icons/openai.svg" height="26" alt="Codex"></picture></a>
|
||||
<a href="https://opencode.ai" title="OpenCode"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/opencode/FFFFFF"><img src="https://cdn.simpleicons.org/opencode/000000" height="26" alt="OpenCode"></picture></a>
|
||||
<a href="https://pi.dev" title="pi"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/pi/FFFFFF"><img src="https://cdn.simpleicons.org/pi/000000" height="26" alt="pi"></picture></a>
|
||||
<a href="https://github.com/google-gemini/gemini-cli" title="Gemini CLI"><img src="https://cdn.simpleicons.org/googlegemini/8E75B2" height="26" alt="Gemini CLI"></a>
|
||||
<a href="https://www.kimi.com" title="Kimi"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/kimi/FFFFFF"><img src="https://cdn.simpleicons.org/kimi/000000" height="26" alt="Kimi"></picture></a>
|
||||
<a href="https://github.com/QwenLM/qwen-code" title="Qwen Code"><img src="https://cdn.simpleicons.org/qwen/6950EF" height="26" alt="Qwen Code"></a>
|
||||
<a href="https://github.com/github/copilot-cli" title="GitHub Copilot CLI"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/githubcopilot/FFFFFF"><img src="https://cdn.simpleicons.org/githubcopilot/000000" height="26" alt="GitHub Copilot CLI"></picture></a>
|
||||
<a href="https://www.trae.ai" title="TRAE"><img src="https://cdn.simpleicons.org/trae/32F08C" height="26" alt="TRAE"></a>
|
||||
<a href="https://www.codebuddy.cn" title="CodeBuddy"><img src="https://cdn.simpleicons.org/codebuddy/6C4DFF" height="26" alt="CodeBuddy"></a>
|
||||
<a href="https://qoder.com" title="Qoder"><img src="https://icons.duckduckgo.com/ip3/qoder.com.ico" height="26" alt="Qoder"></a>
|
||||
<a href="https://iflow.cn" title="iFlow CLI"><img src="https://img.alicdn.com/imgextra/i4/O1CN01yBfg3x1iNi4YggwIt_!!6000000004401-2-tps-72-72.png" height="26" alt="iFlow CLI"></a>
|
||||
<a href="https://www.minimax.io" title="MiniMax Code (mcode)"><img src="https://cdn.simpleicons.org/minimax/E73562" height="26" alt="MiniMax Code"></a>
|
||||
<a href="https://www.deepseek.com" title="deepseek-harness (dsh)"><img src="https://cdn.simpleicons.org/deepseek/5786FE" height="26" alt="deepseek-harness"></a>
|
||||
<a href="https://ampcode.com" title="Amp"><img src="https://icons.duckduckgo.com/ip3/ampcode.com.ico" height="26" alt="Amp"></a>
|
||||
<a href="https://charm.land/crush" title="Crush"><img src="https://icons.duckduckgo.com/ip3/charm.land.ico" height="26" alt="Crush"></a>
|
||||
<a href="https://zed.dev" title="Zed"><img src="https://icons.duckduckgo.com/ip3/zed.dev.ico" height="26" alt="Zed"></a>
|
||||
<a href="https://aider.chat" title="aider"><img src="https://raw.githubusercontent.com/Aider-AI/aider/main/aider/website/assets/icons/favicon-32x32.png" height="26" alt="aider"></a>
|
||||
<a href="https://github.com/aaif-goose/goose" title="goose"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/aaif-goose/goose/main/documentation/static/img/logo_dark.png"><img src="https://raw.githubusercontent.com/aaif-goose/goose/main/documentation/static/img/logo_light.png" height="26" alt="goose"></picture></a>
|
||||
<a href="https://github.com/NousResearch/hermes-agent" title="hermes"><img src="https://raw.githubusercontent.com/NousResearch/hermes-agent/main/apps/bootstrap-installer/src-tauri/icons/128x128.png" height="26" alt="hermes"></a>
|
||||
<a href="https://z.ai" title="zcode (Z.ai)"><img src="https://z-cdn.chatglm.cn/z-ai/static/logo.svg" height="26" alt="zcode"></a>
|
||||
<a href="https://omp.sh" title="omp (oh-my-pi, Stencil Labs)"><img src="https://omp.sh/favicon.svg" height="26" alt="omp"></a>
|
||||
<a href="https://github.com/1jehuang/jcode" title="jcode"><img src="https://github.com/1jehuang.png" height="26" alt="jcode"></a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
> **キャッシュの健全性をひと目で:** 健全なセッションでは、プレフィックスキャッシュのヒット率が **95〜97%** に保たれ、圧縮そのもののコストは 2% 以下です。それより低い状態が続く場合は、`/acp` か `/acp-cache` で原因を確認してください([FAQ](#faq) を参照)。よくある原因は、多い順に、上流のキャッシュの TTL 切れ · モデルの切り替え · bili のバグ(報告してください) · その他/不明です。
|
||||
|
||||
## コミュニティ
|
||||
|
||||
QQ グループ:
|
||||
1056132097(満員)
|
||||
1108730198(満員)
|
||||
1129868472(参加可能)
|
||||
|
||||
---
|
||||
|
||||
## 📄 論文/プレプリント
|
||||
|
||||
- **[Model-Driven Incremental Hierarchical Compression: Training-Free Multi-Generational Context Management for Long-Lived Coding Agents](./paper/model-driven-incremental-hierarchical-compression-training-free-multi-generational-context-management-for-long-lived-coding-agents.md)**(英語、v0.2)
|
||||
|
||||
> 📝 **論文そのものも、コードベースの一部(`paper/`)として MIT License のもとでオープンソース化されています。これは更新され続ける文書で、誰でも編集でき、プルリクエストによる改善を歓迎します。**
|
||||
|
||||
本番規模の長期的な研究です:4.5 か月、3 つのホスト、174,327 回のモデル呼び出し、累計 187.6 億の入力トークン(全ホストで約 247 億)、204,800 トークンのモデルでのウィンドウ超過ゼロ、8,584〜12,049 回の呼び出しに及ぶマラソンセッション。
|
||||
|
||||
### 📊 独立した第三者によるベンチマーク
|
||||
|
||||
- **[1,500 項目のクロスベンチマーク評価(`LongMemEval-S` · `ContextBench` · `MemoryAgentBench`)](./benchmarks/third-party-1500/README.md)**([中文版](./benchmarks/third-party-1500/README.zh-CN.md))— `billion-context`(`v0.1.202`)を、`full` のコンテキストと 3 種類の RAG(`bm25`、`embedding`、`embedding-rerank`)と、`DeepSeek V4.1 Flash`、`Qwen3-Embedding-8B`、`Qwen3-Reranker-4B`、`Pi Agent` を使って直接比較しました:**ContextBench で 1 位**(Utilized F1 `0.3097`、`full` に比べてコスト `-58.3%`)、**LongMemEval-S で最良の RAG を +16.6% 上回る**(`79.20%` 対 `62.60%`、独立セッションのコストは `full` に比べて `-71.1%`)、**148 万トークンの MemoryAgentBench TTL で生存率 100%**(`full` が `199/199` で失敗するところで、定常状態で `30×` の圧縮)。
|
||||
|
||||
---
|
||||
|
||||
`billion-context` は**あらゆる**エージェントとそのモデル API の間に入り、[acp-kernel](https://github.com/ranxianglei/acp-kernel) による圧縮で Anthropic/OpenAI のストリームを書き換えます。**いつ**、**何を**高い忠実度の要約に圧縮するかはモデルが決めます。固定の切り詰めの上限ではありません。
|
||||
|
||||
## なぜ必要か
|
||||
|
||||
長いコーディングセッションでは、コンテキストが膨れ上がります。どのプロバイダーもトークンごとに課金し、コンテキストウィンドウを超えるとセッションは劣化するか止まってしまいます。`billion-context` は、消費済みの会話を階層的な要約に圧縮するので、1 つのセッションを何日も動かせます。1 つのコンテキストウィンドウで数十億トークンを扱えます。
|
||||
|
||||
ホストに組み込まれた要約機能と違い、ここでの圧縮は**段階的で、元に戻せ、プレフィックスキャッシュに優しい**ものです:要約は小さな範囲ごとに書かれ、必要なときに展開し直せ、キャッシュのプレフィックスはそのまま保たれます。
|
||||
|
||||
## 仕組み
|
||||
|
||||

|
||||
|
||||
### コンテキスト管理ツール
|
||||
|
||||
プロキシは会話に 4 つのコンテキスト管理ツールを注入します。コンテキストが大きくなるにつれてモデル自身がそれらを呼び出し、プロキシは `compress` をサーバー側で実行するので、折りたたんだ範囲は復元されるまで履歴の中で要約されたままになります:
|
||||
|
||||
- **`compress`** — メッセージの範囲を詳しい要約に折りたたみます。
|
||||
- **`decompress`** — 正確な詳細がもう一度必要になったときに、圧縮した範囲を復元します。
|
||||
- **`search_context`** — 圧縮した要約と表示中のメッセージを対象に、キーワードで検索します。
|
||||
- **`acp_status`** — コンテキストの使用状況の概要と、まだ圧縮できる範囲を示します。
|
||||
|
||||
## どれを使えばよいか
|
||||
|
||||
クライアントで選んでください:
|
||||
|
||||
| クライアント | 使うもの |
|
||||
|---|---|
|
||||
| **pi** | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili pi`(ランチャー)または `bili plugin install pi`(ネイティブ)。単体の [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) も引き続き使えます — 詳細:[docs/clients.md](docs/clients.md#pi-pidev-coding-agent) |
|
||||
| **opencode**(1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili opencode`(ランチャー)または `bili plugin install opencode`(ネイティブ)。単体の [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) も 1.x では引き続き使えます — 完全なガイド:[OpenCode](docs/clients.md#opencode) |
|
||||
| **omp** | `bili omp`(組み込みのプラグイン)または `bili plugin install omp`(自分でプロキシを起動するネイティブプラグイン、ランチャー不要)経由の [`billion-context`](https://github.com/ranxianglei/billion-context) |
|
||||
| **dsh** | `bili dsh`(ランチャー — `--patch` による完全なネイティブプラグイン)または `bili plugin install dsh` ≡ `dsh plugin --profile <name> add billion-context`(1 つに統一された経路) — 詳細:[docs/clients.md](docs/clients.md) |
|
||||
| **kimi** | `bili plugin install kimi`(自分でプロキシを起動するネイティブ、Kimi Code ≥ 2.0.0)、`bili kimi`(証明書による MITM)、または `/bili/` プレフィックス — 詳細:[docs/clients.md](docs/clients.md) |
|
||||
| **hermes** | `bili plugin install hermes`(自分でプロキシを起動するネイティブ、Python プラグイン #958)または `bili hermes`(証明書による MITM) |
|
||||
| **zcode**(Z.ai / bigmodel のコーディングプラン) | `bili plugin install zcode`(自分でプロキシを起動するネイティブ、#1145)、GUI の Settings → Network による証明書の MITM、または `/bili/` プレフィックス — 詳細:[docs/clients.md](docs/clients.md) |
|
||||
| **claude** | `bili claude`(ランチャー)または `bili plugin install claude`(ネイティブの構成、#964 — 管理された設定ブロック + セッションが所有するプロキシ。下の注意を参照) |
|
||||
| **codex** | `bili codex`(ランチャー — 設定不要の完全な構成)または `bili plugin install codex`(MCP シェルのツールの補助:**先に bili を起動してください** — シェルがプロキシを起動することはなく、codex 自身の通信を振り向けることもありません) — 詳細:[docs/clients.md](docs/clients.md#codex-openai-codex-cli) |
|
||||
| **jcode** | `bili jcode`(証明書による MITM)または `/bili/` プレフィックス経由の [`billion-context`](https://github.com/ranxianglei/billion-context) — ネイティブモードはありません(コンパイル済みの Rust バイナリで、プラグインの差し込み口がありません。[#962](https://github.com/ranxianglei/billion-context/issues/962)) |
|
||||
| **gemini**(Gemini CLI) | `bili gemini`(ランチャー、`GOOGLE_GEMINI_BASE_URL` の `/bili/` 書き換え)または `/bili/` プレフィックス — ランチャーのみ(ループ内でツールを差し込む口がありません、#1043) |
|
||||
| **iflow**(iFlow CLI) | `bili iflow`(ランチャー、`IFLOW_BASE_URL` の `/bili/` 書き換え)または `/bili/` プレフィックス |
|
||||
| **qwen**(Qwen Code) | `bili qwen`(ランチャー、証明書による MITM)または `/bili/` プレフィックス |
|
||||
| **antigravity**(Antigravity CLI / agy、Google) | `bili antigravity`(ランチャー、daily-cloudcode-pa.googleapis.com の `CLOUD_CODE_URL` の `/bili/` 書き換え — Antigravity の実際のデフォルトの上流、#3129)または `/bili/` プレフィックス — プラグインの差し込み口はありません(クローズドな Go の language_server で、ユーザープラグインの面は追加のみ、#2115) — 詳細:[docs/clients.md](docs/clients.md) |
|
||||
| **mcode**(MiniMax Code) | `bili mcode`(証明書による MITM)または `/bili/` プレフィックス経由の [`billion-context`](https://github.com/ranxianglei/billion-context) — ネイティブモードはありません(イベントのフックのみで、モデルへのリクエストの差し込み口がありません。[#1050](https://github.com/ranxianglei/billion-context/issues/1050)) |
|
||||
| **aider** | `bili aider`(証明書による MITM)または `/bili/` プレフィックス経由の [`billion-context`](https://github.com/ranxianglei/billion-context) — ネイティブモードはありません(シェルコマンドだけのフックで、ツールを注入する口がありません。[#1048](https://github.com/ranxianglei/billion-context/issues/1048)) |
|
||||
| **copilot**(GitHub Copilot CLI) | `bili copilot`(ランチャー、証明書による MITM) — クローズドな Go のバイナリで、プラグインの差し込み口はありません(#1049) |
|
||||
| **amp**(Amp CLI) | `bili amp`(ランチャー、証明書による MITM) — クローズドな Go のバイナリで、プラグインの差し込み口はありません(#1049) |
|
||||
| **kiro**(Kiro CLI、AWS) | `bili kiro`(ランチャー、証明書による MITM) — Rust のシェル + Node のエージェントサーバーで、プラグインの差し込み口はありません。モデルの通信は `runtime.<region>.kiro.dev` 上の Responses の通信形式で、ゲートウェイ特有の癖は組み込みで処理します — 詳細:[docs/clients.md](docs/clients.md#kiro-cli-aws) |
|
||||
| **crush**(Charm Crush) | `bili crush`(ランチャー、証明書による MITM) — オープンソースの Go のバイナリで、プラグインの差し込み口はありません。組み込みのプロバイダーのホストは許可リストに入り、独自の `base_url` は crush.json から自動で見つけます(#2340) |
|
||||
| **zed**(Zed エディター) | `bili zed`(ランチャー、証明書による MITM) — オープンソースの Rust のエディターで、プラグインの差し込み口はありません。reqwest は HTTPS_PROXY に従い、CA は SSL_CERT_FILE で渡します(Linux の環境変数の探索)。組み込みのプロバイダーのホストは許可リストに入り、独自の `api_url` は settings.json から自動で見つけます。ループバックのプロバイダー(ollama/lmstudio)は NO_PROXY で直接接続のままです(#2340) |
|
||||
| **goose**(Goose CLI) | `bili goose`(ランチャー) — rustls は CA ファイルを信頼しないので、証明書による MITM はできません:openai/anthropic の経路は `OPENAI_HOST`/`ANTHROPIC_HOST` で、独自のプロバイダーは作り直した `GOOSE_PATH_ROOT` のオーバーレイで扱います(#1049) |
|
||||
| **それ以外のすべて**(コンテキストのフックなし) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili <client>`(ランチャー、推奨)または `/bili/` プレフィックス |
|
||||
|
||||
**ネイティブモードと単体の拡張機能。** ホストのネイティブプラグイン(`bili plugin install …`)と、単体のプロセス内拡張機能(`billion-context-pi`、`opencode-acp`)は**同時に使えません**。両方が有効だと二重に圧縮されてしまいます。切り替えはインストーラーが行います:古い項目(名前だけのもの、`npm:` の別名、バージョン付き、パスの形式。配列でもオブジェクトでも)を置き換え、元の設定を一度だけ `.bili-bak` にスナップショットします。**プロジェクトのローカル**のインストールには手を付けないので、それは手で削除してください。手動でインストールした場合の実行時の安全網として、ネイティブの項目は読み込み時に同期的に `BILLION_CONTEXT_NATIVE=<host>` を設定するので、単体の拡張機能は動作時に身を引けます。pi 側では、この印を使うには `billion-context-pi` **0.1.72 以降**が必要です。また、pi のネイティブの項目は、プロキシが起動したあとで pi の両方の設定ファイルを走査し、インストーラーが見ていない古い項目が同居していると大きく警告します。古い `billion-context-pi` が黙って二重に圧縮している間、目に見える合図はこの警告だけです。
|
||||
|
||||
|
||||
## インストール
|
||||
|
||||
Linux / macOS — ユーザー単位のプレフィックスでインストールします(`sudo` も npm の設定の変更も不要で、
|
||||
`bili` の自己アップデートが権限エラーに当たることもありません):
|
||||
|
||||
```bash
|
||||
npm install -g billion-context --prefix=~/.local
|
||||
```
|
||||
|
||||
`bili` コマンドは `~/.local/bin` に入ります。ほとんどのディストリビューションでは、すでに PATH に入っています。
|
||||
入っていなければ、`~/.bashrc` か `~/.zshrc` に `export PATH="$HOME/.local/bin:$PATH"` を
|
||||
追加してください。nvm や Homebrew の Node では、デフォルトのプレフィックスがすでにユーザーの所有なので、
|
||||
普通の `npm install -g billion-context` でそのまま動きます。Windows でも、デフォルトの
|
||||
プレフィックス(`%APPDATA%\npm`)はユーザーが書き込めるので、普通の `npm install -g billion-context` で動きます。
|
||||
|
||||
これで `bili` コマンドがインストールされます(`bili-proxy` も別名として残してあります)。root が所有する古いプレフィックスで
|
||||
`EACCES` に当たった場合は、`--prefix=~/.local` を付けてインストールし直してください
|
||||
(今後 npm で `bili` をインストールし直すときも、このフラグをもう一度付けてください)。これが
|
||||
根本的な解決策です。`sudo` は避けてください。
|
||||
|
||||
コンテナーのほうがよいですか? リポジトリのルートに `Dockerfile` があります。下記の
|
||||
[Docker で動かす](#docker-で動かす)を参照してください。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
使い方は 3 つあります。1 つ選んでください:
|
||||
|
||||
- **ネイティブプラグイン(最もネイティブ):** `bili plugin install <client>` — bili が
|
||||
クライアントの中のプラグインになります。クライアントはいつもどおり起動します。
|
||||
- **ランチャー(設定不要):** `bili <client>` のコマンド 1 つで、プロキシとクライアントを
|
||||
いっしょに起動します。本物の設定ファイルに手を付けることはありません。
|
||||
- **URL の変更(最も汎用的):** クライアントの baseURL の前に、プロキシの
|
||||
オリジン + `/bili/` を付けます。
|
||||
|
||||
これら 3 つの方法の裏にある仕組み(プラグインのライフサイクル、runtime-info の
|
||||
プロトコル、注入の優先順位)は [docs/technical-notes.md](docs/technical-notes.md) にあります。
|
||||
|
||||
ポートについて手短に(#1660):`bili start`(手動)は `8787` を使います。レーンが
|
||||
自動で起動するもの(ネイティブのフック、ランチャーのレーン)はすべて、`18787` から始まる
|
||||
自己管理の別の区画に置かれます。衝突すると +1 ずつずれ、各レーンは
|
||||
そのずれを記憶するので、設定不要のインストールがポートを奪い合うことはありません。
|
||||
意図的に起動した `bili start` のデーモンには、デフォルトでつながります。どこにつながるかは
|
||||
レーンごとに決まります(#2905):フックはまず自分のレーンのインスタンスを使い、
|
||||
宣言された別のレーンのものには決してつながりません。
|
||||
ただし `native.attachLanePriority` に並べたレーンは例外です。8787 のユーザー区画のデーモンは
|
||||
最後の手段のフォールバックのままです。
|
||||
アップグレードのための再起動で、前のビルドがまだそのレーンのポートで処理を終えようとしている場合は、
|
||||
それがポートを解放するのを待ち(最大 5 秒)、ずらさずに同じポートにバインドし直します
|
||||
(#1723)。本当に使われているポートだけが +1 ずれ、その移動は
|
||||
はっきりとログに記録されるようになりました。
|
||||
|
||||
### 方法 1 — ネイティブプラグイン(`bili plugin install pi` / `omp` / `opencode` / `dsh` / `kimi` / `hermes` / `zcode`)
|
||||
|
||||
プロキシはクライアントの中に入ります。一度インストールすれば、あとはクライアントを
|
||||
いつもどおり起動するだけです。ランチャーのコマンドも、環境変数も、固定のポートも、
|
||||
URL の編集も要りません。現在、**pi**、**omp**、**opencode**(1.x と
|
||||
2.x)、**dsh**、**kimi**、**hermes**、**zcode** に対応しています:
|
||||
|
||||
```bash
|
||||
bili plugin install pi # registers a "billion-context" entry in pi's settings (npm form when bili itself was npm-installed)
|
||||
bili plugin install omp # registers an extensions entry in omp's config.yml (~/.omp/agent/config.yml)
|
||||
bili plugin install opencode # registers the plugin in opencode's real config + disables native auto-compaction
|
||||
bili plugin install dsh # runs 'dsh plugin --profile <name> add billion-context' for every existing profile
|
||||
bili plugin install kimi # writes $KIMI_CODE_HOME/plugins/managed/billion-context/kimi.plugin.json (+ installed.json record); per-session routing block lands in config.toml on first start (Kimi Code >= 2.0.0)
|
||||
bili plugin install hermes # copies the Python plugin into ~/.hermes/plugins/billion-context/ (+ machine-owned bili.json sidecar) and enables it via `hermes plugins enable billion-context`
|
||||
bili plugin install zcode # writes hooks.enabled + a SessionStart hook + mcp.servers.bili into ~/.zcode/cli/config.json; per-session routing lands in the bigmodel provider store on first start
|
||||
bili plugin remove <client> # undo (dsh removes through the same channel; config snapshots go to .bili-bak)
|
||||
```
|
||||
|
||||
クライアントに独自のプラグインの経路がある場合は、bili のコマンドを使わずに
|
||||
ネイティブにインストールすることもできます:
|
||||
|
||||
- **dsh:** `dsh plugin --profile <name> add billion-context` は、`bili plugin install dsh` が
|
||||
プロファイルごとに実行するコマンドそのものです(npm の形式のみ。git の
|
||||
チェックアウトには公開済みのエントリーがなく、GitHub のアドレスを貼り付けると `dist/` のない
|
||||
ソースがインストールされ、バンドルが読み込まれません)。どちらの方法でも最終的な状態は同じです
|
||||
(プロファイルに pnpm でインストールし、同梱のパッチレイヤーを dsh 自身がマウントします)。削除も
|
||||
同じ経路で行います。下記の dsh のセクションを参照してください。
|
||||
- **opencode:** 本物の設定のプラグインの一覧に、npm の名前だけを追加します —
|
||||
`"plugin": ["billion-context"]`(npm の形式のみ。git のチェックアウトには
|
||||
公開済みのエントリーがありません)。パッケージは `exports["./server"]` →
|
||||
`dist/agent/opencode-native.js` を公開しているので、opencode は自身の
|
||||
Npm.add の仕組みでそれを読み込み、プラグインは bili でインストールした形式と
|
||||
まったく同じように自分でプロキシを起動します。bili のインストーラーが代わりにやっていた
|
||||
2 つのことも行ってください:同じ設定で `"compaction": { "auto": false }` を設定すること
|
||||
(そうしないと OpenCode のネイティブの自動圧縮で二重に圧縮されます)と、先にファイルを
|
||||
手動でバックアップしておくことです。
|
||||
- **claude:** このリポジトリは Claude Code のプラグインのマーケットプレイスも兼ねています —
|
||||
`/plugin marketplace add ranxianglei/billion-context` のあと、
|
||||
`/plugin install billion-context@billion-context` を実行し、さらに
|
||||
`/billion-context:bili-setup` を実行します(これが `bili plugin install claude` を
|
||||
代わりに実行し、再起動するよう伝えます)。最終的な状態は bili のインストーラーと同じです。
|
||||
このプラグイン自身はフックも MCP の項目も持たないので、何も
|
||||
二重に登録されません。
|
||||
|
||||
pi / omp / kimi / claude には、クライアント側の経路がありません。`bili plugin
|
||||
install <client>` がそれらの設定の項目を代わりに書き込みます(kimi の宣言的な
|
||||
`kimi.plugin.json` + レジストリの記録、claude の管理された設定ブロックなど)。
|
||||
|
||||
注意:
|
||||
|
||||
- ネイティブモードは、単体のプロセス内拡張機能(`billion-context-pi`、`opencode-acp`)と**同時に使えません**。インストーラーが項目を入れ替え、元の設定をスナップショットします(`.bili-bak`)。
|
||||
- **pi:** ネイティブのインストールでは、デフォルトで組み込みのサブエージェント(`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`)が組み込まれます。コンテキストの圧縮は残したままそれらを無効にする方法:[pi の組み込みサブエージェント](#pi-の組み込みサブエージェント)。
|
||||
- OpenCode の古いセッション、V1/V2 の形、注意点:[OpenCode](docs/clients.md#opencode)。
|
||||
- `kimi` は runtime-info を起動時にだけ報告します(静的なヘッダーでは、リクエストごとのウィンドウやモデルの値を運べません)。サブエージェントのツール呼び出しは、プロキシの外向きの tool-use の目撃記録のリング(#1685)で振り分けます。モデルから見える会話の id はありません。
|
||||
- `hermes` のネイティブプラグインは Python です:ヘルスチェックのあとで環境変数によって hermes の httpx のスタックをプロキシに向け、`llm_request` のミドルウェアでリクエストごとのヘッダーを付けます。
|
||||
- `codex` は、プラグインのインストールだけでは自立させられない唯一のクライアントです:codex はモデルの通信を環境変数だけで振り向けます(デフォルトの ChatGPT ログインのプロバイダーには、設定ファイルで振り向ける差し込み口がありません。管理された `model_providers` ブロックを置くと API キーでの認証が強制され、サブスクリプションのログインが使えなくなります)。また、MCP サーバーは親に環境変数を注入できません。`bili plugin install codex` は `~/.codex/config.toml` に `[mcp_servers.bili]` ブロックを 1 つだけ書き込み(command = node、args = dist/mcp.js)、4 つの ACP ツールを公開します。セッションの開始時に、シェルはプロキシを決めます — 環境変数 `BILI_MCP_PROXY` > 動いているインスタンスの記録(どのレーンのプロキシでも、`bili start` のデーモンでも) > 8787 のユーザー区画のデフォルト(#1660 でインストール時のオリジンの焼き込みを廃止、#403)。どれにも届かないと `tools/list` が -32003 で失敗します。そのため:先に bili を起動する(`bili start` か、いずれかのクライアントのレーンのプロキシ)、圧縮も使いたいなら HTTPS_PROXY を自分で export する、あるいは設定不要の完全な構成のために `bili codex` を使ってください。仕組み:[docs/clients.md](docs/clients.md#codex-openai-codex-cli)。
|
||||
- `claude` にはネイティブの構成があります(#964):管理された設定ブロック + `SessionStart` のフック + MCP シェルです。フックは自己管理のポートの区画(#1660)を使い、セッションごとに管理された URL を動いているオリジンに付け直すので、ポートのずれは自然に直ります。#1821 以降、MCP シェルはセッション中もプロキシを見張り(30 秒ごと × 3 回の失敗)、死んだレーンのプロキシを自分で起動し直すので、モデルへのリクエストは新しいセッションを始めなくても約 90 秒以内に回復します(zcode のレーンと同じ意味です)。`BILI_NATIVE_CLAUDE=0`(パススルー)で無効にできます。仕組み:[docs/technical-notes.md](docs/technical-notes.md)。**既知の制限(#2290):** Claude Desktop アプリの Code タブ(`CLAUDE_CODE_ENTRYPOINT=claude-desktop`)は、組み込みの Claude Code に独自の `ANTHROPIC_BASE_URL` を設定し、管理されたものを上書きします。デスクトップのセッションはプロキシを完全に迂回する一方で、管理されたブロックの `DISABLE_AUTO_COMPACT=1` は引き続き効くので、bili の圧縮もネイティブの自動圧縮も使えなくなります。フックはセッションの開始時に大きく警告します(そして `bili doctor` 用に記録します。これは、ネイティブのレーンと並んで Claude Desktop がインストールされているマシンにも印を付けます)。ターミナルのセッションには影響しません。**2026-10-06 に実地で確認(#2290):** 設定の `env` ブロックに `HTTPS_PROXY` を置いても、Claude Desktop 2.19675.1 / 組み込みの CC 2.1.288(Windows 11)では、MITM を有効にした動作中のプロキシへの CONNECT の通信はゼロでした。その変数はそこではどのネットワークのスタックにも届かず、当時の CLI の挙動と一致します。新しいビルド(CC 2.1.301 以降)では CLI が `HTTPS_PROXY` に従うので、`bili claude` は `/bili/` のベース URL の書き換えで振り向けています。ランチャーはこのレーンにプロキシも CA もまったく渡さず、自分でプロキシを持ち込む子プロセスには、ループバックのホストを `NO_PROXY`/`no_proxy` に追加するので、その経路はプロキシの挙動に関係なく直接接続のままです(#3446)。そのバージョンの時点で、デスクトップの Code タブには使える振り向けの差し込み口がありません。上流が挙動を変える場合に備えて、このレーンは [#2290](https://github.com/ranxianglei/billion-context/issues/2290) で引き続き追跡しています。**アカウントに結び付いた機能(#4693):** このレーンは独自の `ANTHROPIC_BASE_URL` で振り向けるため、Claude Code はセッションをサードパーティ/API キーのものとして扱い、Anthropic のアカウント/Cloud に結び付いた機能を無効にします。**Remote Control**(`/remote-control`、モバイル/デスクトップ/Web からローカルのセッションを操作するもの)は、bili が通信を振り向けている間、コマンドの一覧から消えます。圧縮には影響しません。それらの機能が必要なセッションでは、bili なしで普通の `claude` を実行してください(または `bili plugin remove claude`)。これはベース URL で振り向ける差し込み口に本来備わったもので(CC の undici のスタックで生き残る代わりの横取りの地点はありません、#2290)、設定が消されたわけではありません。デスクトップだけを使う人は、`bili plugin remove claude` でネイティブの自動圧縮を戻せます。#5095 以降、管理されたブロックは `SubagentStart` のフック(`node <root>/dist/claude-subagent-hook.js`)もインストールし、各サブエージェントのコンテキストに、ディスパッチごとのレーンのトークンを発行します:エージェント id のヘッダーなしで親のセッション id を使うサブエージェント(VS Code の拡張機能のビルド、#4352)は、それぞれ自分の `<id>|sub:…:t:<token>` の圧縮レーンに振り分けられるので、同じ種類の並列のディスパッチが混ざらなくなります(そして最初のメッセージが折りたたまれると、以降のリクエストからトークンは消え、それらはフィンガープリントのレーンにフォールバックします)。アンインストールすると、管理されたブロックとともにフックも削除されます。
|
||||
- `zcode` にはネイティブの構成があります(#1145):管理された `~/.zcode/cli/config.json` のブロック + セッションごとのプロバイダーの `baseURL` の書き換えです。仕組みの詳細:[docs/clients.md](docs/clients.md)。
|
||||
- `jcode` と `aider` にはネイティブモードがありません(プラグイン/MCP/ツール注入の差し込み口がありません:#962、#1048)。`bili jcode` / `bili aider` を使ってください。
|
||||
- `copilot`、`amp`、`goose` はランチャーのみです(#1049)。goose は証明書による MITM ができず(rustls は CA ファイルを信頼しません)、代わりに平文の HTTP のベース URL のリダイレクトを使います。
|
||||
|
||||
### 方法 2 — ランチャー(`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi` / `bili gemini` / `bili iflow` / `bili qwen` / `bili antigravity` / `bili mcode` / `bili aider` / `bili copilot` / `bili amp` / `bili goose` / `bili kiro`)
|
||||
|
||||
ランチャーは、クライアントを 1 つのコマンドで包みます:独立したポートでプロキシを起動し
|
||||
(常に新しいインスタンスを起動し、ポートを使い回すことはありません)、クライアントをそこに向けます。
|
||||
クライアントがプロキシ/CA の環境変数に従う場合は**証明書による MITM** を、
|
||||
従わない場合は分離した **`/bili/` の設定の書き換え**を使います。
|
||||
本物の設定ファイルを編集することはありません。
|
||||
クライアント自身の設定は、どの HTTPS の上流のホストと通信するかを知るために読み込むだけで、
|
||||
それらのホストを MITM の許可リストに入れるので、プロキシはちょうどそれらのホストだけで TLS を終端し、
|
||||
それ以外はすべて中身を見ずにトンネルします。
|
||||
|
||||
```bash
|
||||
bili pi # launch pi through the proxy — file-free (#535): env + extension registerProvider, real ~/.pi untouched
|
||||
bili codex # launch codex through the proxy
|
||||
bili claude # launch claude through the proxy
|
||||
bili omp # pi-style, file-free (#535): env + extension registerProvider + compaction cancel, real ~/.omp untouched
|
||||
bili opencode # OpenCode (1.x & 2.x): full guide in the [OpenCode](docs/clients.md#opencode) section below
|
||||
bili hermes # file-free (#535): hermes proxy env (HTTPS_PROXY + combined CA bundle via SSL_CERT_FILE) — https via CONNECT MITM, http via absolute-form forward proxy; real ~/.hermes untouched
|
||||
bili dsh # deepseek-harness: full native plugin injected via --patch (#941) — real dsh tools, session-bound /acp + /acp-cache (plugin mode); non-loopback upstreams ride proxy envs, loopback keeps the overlay DSH_HOME rewrite (#535); dsh auto-compaction off everywhere — host plane via the bundle patch, web-profile presets at load time (#1772/#2474/#3354)
|
||||
bili codebuddy # Tencent CodeBuddy Code CLI: CODEBUDDY_BASE_URL /bili/ rewrite (OpenAI chat completions wire), budget aligned via CODEBUDDY_AUTO_COMPACT_WINDOW; real ~/.codebuddy untouched
|
||||
bili qoder # qoder CLI (`qoder`/`qodercli`): model endpoint is hardcoded https (no /bili/ rewrite possible) — cert-MITM via HTTPS_PROXY + NODE_EXTRA_CA_CERTS, default model hosts whitelisted (#653). Qoder Desktop is a separate BYOK/custom channel that speaks plaintext OpenAI over a `/bili/` prefix — point it at bili as a normal custom provider (not this MITM lane); its official-subscription traffic is encrypted and out of scope (#764)
|
||||
bili trae # Trae CLI (ByteDance, closed Go binary, no base-URL override) — cert-MITM via HTTPS_PROXY + SSL_CERT_FILE, model host from TRAE_CLI_API_HOST or the default enterprise gateway (#655)
|
||||
bili jcode # jcode (Rust agent harness) — env-only cert-MITM launch: HTTPS_PROXY + SSL_CERT_FILE, model host api.z.ai whitelisted, local loopback providers stay direct via NO_PROXY
|
||||
bili kimi # Kimi Code CLI (Moonshot): standard proxy envs except an unconditional loopback bypass — https via cert-MITM, http via absolute-form forward proxy; loopback endpoints inventoried with a manual /bili/ hint (#757)
|
||||
bili gemini # Gemini CLI (Google): GOOGLE_GEMINI_BASE_URL /bili/ rewrite to generativelanguage.googleapis.com (Google native wire), real ~/.gemini untouched
|
||||
bili iflow # iFlow CLI: IFLOW_BASE_URL /bili/ rewrite to apis.iflow.cn/v1 (OpenAI chat-completions wire), real ~/.iflow untouched
|
||||
bili qwen # Qwen Code (multi-protocol gemini-cli fork, no base-URL hook): cert-MITM via HTTPS_PROXY + NODE_EXTRA_CA_CERTS, default DashScope/Qwen model hosts whitelisted, custom relays via --mitm-domain
|
||||
bili antigravity # Antigravity CLI (agy, Google): CLOUD_CODE_URL /bili/ rewrite of daily-cloudcode-pa.googleapis.com — the real default upstream (bare cloudcode-pa 400s on /v1internal:*, #3129); undocumented language-server env override, v2.19.1 binary-verified; wire recognized as Google native by path (#2115)
|
||||
bili mcode # MiniMax Code CLI: same shape as kimi (proxy envs, unconditional loopback bypass, cert-MITM/absolute-form); session bound via X-Mavis-Session-Id (#1050)
|
||||
bili aider # Aider (Python pair programmer): cert-MITM via HTTPS_PROXY + SSL_CERT_FILE/REQUESTS_CA_BUNDLE; endpoint from OPENAI_API_BASE / ANTHROPIC_BASE_URL / --openai-api-base / .aider.conf.yml (#1048)
|
||||
bili copilot # Copilot CLI (GitHub, closed Go binary) — cert-MITM via HTTPS_PROXY + SSL_CERT_FILE, api.githubcopilot.com + per-plan subdomains whitelisted (#1049)
|
||||
bili amp # Amp CLI (Sourcegraph, closed Go binary) — cert-MITM via HTTPS_PROXY + SSL_CERT_FILE, ampcode.com whitelisted (#1049)
|
||||
bili goose # Goose (Block, Rust/reqwest): rustls release builds trust no CA file — openai/anthropic legs via OPENAI_HOST/ANTHROPIC_HOST, custom providers via a regenerated GOOSE_PATH_ROOT overlay (/bili/ rewrites, real config untouched) (#1049)
|
||||
bili kiro # Kiro CLI (AWS): cert-MITM via HTTPS_PROXY + combined CA on SSL_CERT_FILE and NODE_EXTRA_CA_CERTS; only runtime.<region>.kiro.dev is decrypted; developer/system items re-voiced as user for the gateway; session = Kiro's conversation id (survives --resume)
|
||||
bili pi --mitm-domain api.foo.com # add a domain to the MITM whitelist
|
||||
```
|
||||
|
||||
### 方法 3 — URL の変更(`/bili/` プレフィックス)
|
||||
|
||||
プロキシを起動します:
|
||||
|
||||
```bash
|
||||
bili
|
||||
```
|
||||
|
||||
あとは、クライアントの既存の baseURL の前に `http://localhost:8787/bili/` を付けるだけです。
|
||||
上流の完全な URL がパスに埋め込まれるので、プロキシは設定なしで
|
||||
転送先がわかります:
|
||||
|
||||
```
|
||||
client baseURL before: https://api.openai.com/v1
|
||||
client baseURL after: http://localhost:8787/bili/https://api.openai.com/v1
|
||||
```
|
||||
|
||||
クライアントごとの設定の例は、Web UI のガイド [http://localhost:8787](http://localhost:8787) を参照してください。
|
||||
|
||||
**確認する。** プロキシが動いていて設定を保存したら、プロキシが応答することと、
|
||||
最初の実際のリクエストで圧縮の動きがログに出ることを確認します:
|
||||
|
||||
```bash
|
||||
# Health check (proxy up + where it forwards)
|
||||
curl -s http://localhost:8787/__bili/health
|
||||
# → {"ok":true,"upstream":"https://api.anthropic.com"}
|
||||
|
||||
# Live session stats (after a real request)
|
||||
curl -s http://localhost:8787/__bili/stats
|
||||
```
|
||||
|
||||
それからクライアントからメッセージを 1 つ送り、ログを見てください
|
||||
(`~/.local/state/billion-context/bili.log`。stderr にも出力されます)。
|
||||
リクエストごとに `processTurn` の行が出て、会話が大きくなると、
|
||||
`[acp-usage] round N input=X cached=Y (cache hit Z%)` + `compress` のイベントが出るはずです。
|
||||
|
||||
### クライアントごとの詳細
|
||||
|
||||
クイックスタートの 1 行に収まらないこと — 各クライアントのレーンがどうつながるか、何がどこに書き込まれるか、既知の制限 — はすべて **[docs/clients.md](docs/clients.md)** にあります:dsh · Kimi Code · Hermes · ZCode · Gemini 系(Gemini CLI / iFlow CLI / Qwen Code / Antigravity) · 決して圧縮されない証明書 MITM のクライアント(CONNECT の中身を見ないトンネル、#897) · 直接接続になる未知のエンドポイント(#1290) · OpenCode(ランチャー/ネイティブ/純粋なプロキシ、`/acp` の状態とルール、古い opencode-acp のセッション #920)。
|
||||
|
||||
## ソースから(開発)
|
||||
|
||||
> **注意:** `master` は開発用のブランチで、いつ壊れていてもおかしくありません。未リリースの変更、失敗するビルド、未検証の修正が含まれます。コードにパッチを当てるか、未リリースの修正を試すのでない限り、上記のとおり npm でリリース版をインストールしてください。
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ranxianglei/billion-context.git
|
||||
cd billion-context
|
||||
npm ci
|
||||
npm run build
|
||||
npm link
|
||||
bili --version
|
||||
```
|
||||
|
||||
`npm link` のあとは、どのディレクトリからでも `bili` が使えます。
|
||||
|
||||
## FAQ
|
||||
|
||||
**キャッシュのヒット率はどう確認しますか?** ログを掘り返す必要はありません。`/acp-cache` を実行すると、
|
||||
**クライアントの中にテキストの要約レポート**が表示され、その先頭にクリックできる
|
||||
**Web UI のリンク**があります。それを開くと、セッションのページの Web 版が表示されます:キャッシュの
|
||||
ヒット率の**折れ線グラフ**と、キャッシュが外れた箇所ごとの**原因の特定**です:
|
||||
|
||||

|
||||
レポートには、ひと目で状況をつかめる 4 つの
|
||||
ブロックがあります:**GRAND LEDGER**(合計 + ヒット率と、はっきりした
|
||||
`HEALTHY` の判定。ミスは、新しい内容/
|
||||
圧縮の払い直し/上流の TTL またはクライアントの書き換え、に分解されます) · **FOLD ECONOMICS**(折りたたみごとの
|
||||
損得:節約したトークンの差し引き、元が取れたかの判定) · **LINE ITEMS**(異常のみ:
|
||||
ヒット率 85% 未満またはミス 5000 以上)。目安:**圧縮そのもののコストは 2% 以下**です —
|
||||
健全なセッションは **95〜97%** にとどまります。それより低いときは、原因の特定が
|
||||
よくある容疑者のどれかを、次の順で教えてくれます:① 上流のキャッシュの TTL
|
||||
切れ(安定したプレフィックスのミスとして現れ、上位の急増の行がアイドルの
|
||||
時間を示します)、② モデルの切り替え、③ bili のバグ(ページを添えて報告してください)、
|
||||
④ その他/不明。`/acp-cache [full]` はすべての折りたたみと行を一覧します。同じレポートは
|
||||
#1535 以降、レポートの最後には `MODEL SWITCHES` のセクションがあります:セッションの途中での
|
||||
モデルの変更はプロバイダーのプレフィックスキャッシュを無効にするので、安定したプレフィックス全体が
|
||||
次のリクエストで課金され直します。各切り替えの説明のつかない残り
|
||||
(その `ttl` の区分から新しい内容を引いたもの)は、TTL 切れに見せかけるのではなく
|
||||
切り替えの分として計上されます。イベントごとの `from → to`、ヒット率、原因に計上した
|
||||
トークンが一覧され(`full` ではすべてのイベント、要約では直近の 8 件)、
|
||||
Web のセッションの表にも、それに対応するモデルの切り替えの列が加わります。#2131 以降、
|
||||
同じ仕組みで外向きの認証情報のフィンガープリントを取り(`authorization`/`x-api-key` 系の
|
||||
ヘッダーの sha256 の先頭 12 桁の 16 進数で、生のキーが保存されることはありません)、
|
||||
**キーの切り替え**(固定の URL の裏にあるリレーが別のアカウントに切り替わること)を、
|
||||
専用の `KEY SWITCHES` のセクション、`CACHE INVALIDATION` の `key switch:` の
|
||||
行、Web のセッションの列の 🔑 のバッジで原因として示します。
|
||||
HTTP の場合:`GET /__bili/cache-report`。リクエストごとの生の `[acp-usage]` の行も、
|
||||
詳しく調べるために引き続きログファイルに記録されます。
|
||||
|
||||
**`/acp` は何を表示しますか?** ネイティブプラグインのあるクライアント(opencode、dsh、
|
||||
hermes)では、`/acp` が現在の会話の ACP の状態パネルを、プロキシから
|
||||
直接表示します
|
||||
(セッション、ブロック、圧縮できる範囲、使用量)。最初のモデルへの
|
||||
リクエストの前は、代わりにアイドルの通知を表示します。`/acp-cache [full]` は、上記の
|
||||
キャッシュのレポートを表示します。
|
||||
|
||||
**セッションと設定を Web で確認できますか?** はい。
|
||||
[http://localhost:8787](http://localhost:8787) を開いてください:概要のダッシュボード、セッションの
|
||||
一覧とセッションごとの詳細、ライブのログ、設定のエディター、上流への
|
||||
接続テストがあります。Blog のビューでは、メモや長文の記事をパネルの中で
|
||||
表示します。これはインストールに同梱されていて、オンラインの間は約 1 時間おきに GitHub の master から更新されます
|
||||
(オフラインのときは同梱のコピーに安全に切り替わります)。
|
||||
記事の全体は GitHub Pages にもあります。それ以外もすべて、スクリプトで使える普通の JSON です
|
||||
(`/__bili/stats`、`/__bili/sessions`、`/__bili/config` など)。
|
||||
|
||||
**圧縮はいつ行われますか?** モデルが決めます:注入したコンテキストの
|
||||
ツールは、コンテキストが大きくなるにつれてモデルが呼び出します。穏やかな増加のナッジ
|
||||
(設計上は約 50K トークンごとで、`compress.nudgeGrowthTokens` で調整できます)が
|
||||
途中でモデルを促し、入力だけでウィンドウを超えるときは、事前チェックが最後の歯止めとして
|
||||
働きます(#470)。`/acp` か Web UI で、その様子をライブで見られます。
|
||||
|
||||
**圧縮でクライアント自身の会話ファイルは小さくなりますか?** いいえ。非常に長いセッションで最もよくある
|
||||
驚きです(#5796)。圧縮で小さくなるのは**モデルに送るもの**です:
|
||||
外に出るリクエストはどれも、生きているブロックと要約から作り直されるので、
|
||||
会話がどれだけ長くなっても通信は小さいままです。
|
||||
クライアントが保存している履歴はユーザーのデータで、bili がそれを書き換えることはありません。dsh では、
|
||||
bili が有効な間はホストの自動圧縮も無効になるので(2 つの
|
||||
圧縮の仕組みが 1 つの履歴を奪い合ってはいけないため、#1772/#2474/#3354)、
|
||||
ホスト側のファイルはターンのたびに大きくなります:大きくなるにつれて各ターンに時間がかかるようになり
|
||||
(実測:約 3 万メッセージで 1 ターンに数十秒、#5796)、
|
||||
現実的な収束の方法は、重くなったら**新しいセッションを始める**ことです。
|
||||
Web のセッションの一覧では、5,000 件以上のリクエストのあるセッションにバッジ(长会话/slow)が付き、
|
||||
その段階に達したことを知らせます。
|
||||
|
||||
**最初の圧縮が約 200k まで待つのはなぜですか?** 圧縮は、ウィンドウの中の絶対的な位置ではなく、
|
||||
増加の間隔で起こります:デフォルトでは、最初の穏やかな圧縮は、起動時の内容から
|
||||
50k トークン増えたところで起こります(`compress.nudgeGrowthTokens`、一定でウィンドウに依存しません)。起動時の内容が
|
||||
約 100k ある場合や、増加の刻みを約 100k に設定した場合は、最初の圧縮が
|
||||
約 200k まで待つことがあります。
|
||||
もっと早く起こすには:1) システムプロンプトを削り、不要な
|
||||
ツールを無効にし、スキルを整理する。2) `compress.nudgeGrowthTokens` を約 50k に下げる。
|
||||
3) リーンモードを有効にする。計算例は
|
||||
[docs/configuration.md](docs/configuration.md#why-the-first-compaction-waits-until-200k) にあります。
|
||||
|
||||
**bili は透過的ですか? どうすればオフにできますか?** 未知のエンドポイントは
|
||||
変更せずに転送します([docs/clients.md](docs/clients.md))。そして、どのモードもきれいに元に戻せます:
|
||||
ネイティブのインストールなら `bili plugin remove <client>`、ほかの 2 つなら、ランチャーの
|
||||
コマンド/環境変数/`/bili/` プレフィックスを使うのをやめるだけです。通信はすぐに直接接続に
|
||||
戻ります。
|
||||
|
||||
**bili をモデルのルーティングのゲートウェイ(たとえば [magpie](https://github.com/yetone/magpie))と組み合わせられますか?**
|
||||
はい。クライアントを bili に向け、bili を、ゲートウェイの絶対 URL を埋め込んだ
|
||||
`/bili/` プレフィックスでゲートウェイに向けます:
|
||||
`http://localhost:8787/bili/http://127.0.0.1:3425…`。例:Claude Code →
|
||||
`ANTHROPIC_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:3425` +
|
||||
`ANTHROPIC_API_KEY=magpie`。OpenAI 形式のクライアント →
|
||||
`OPENAI_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:3425/v1`(+
|
||||
`OPENAI_API_KEY=magpie`)。圧縮はルーティングの*前*に行われるので、
|
||||
ゲートウェイのルーティンググループのどのアカウントに届くリクエストも、すでに圧縮されています。
|
||||
認証情報はゲートウェイにとどまります:クライアントのダミーのキーはそのまま
|
||||
通り抜け、本物のキーが bili に触れることはありません。注意点:① 会話の途中での
|
||||
アカウントの切り替えは、プロバイダーのプレフィックスキャッシュを無効にします。これは
|
||||
複数アカウントのルーティングに本来備わったもので、bili のせいではありません(`/acp-cache` の `KEY SWITCHES` の
|
||||
セクションで確認できます)。② ルーティングされたモデル名は、bili のウィンドウの照合からは中身が見えません。
|
||||
providers のキー `http://127.0.0.1:3425` の下で、`models.<name>.context` によって
|
||||
それらのコンテキストウィンドウを宣言してください。そうしないと
|
||||
フォールバックのウィンドウで動きます(ルートが見つからない警告、#2317)。③ リレーが bili の
|
||||
Anthropic のレーンの `cache_control` の付与を拒否する場合は、`compat.noCacheControl` を設定してください。④ ループバックの
|
||||
ゲートウェイはそのまま動きます。ループバックでないプライベートなアドレスにあるゲートウェイでは、
|
||||
さらに `network.allowPrivateHttpProviders` が必要になることがあります(#2984)。⑤ Claude Code の
|
||||
ネイティブプラグインのモード(`bili plugin install claude`)では、インストールの前に
|
||||
`BILI_CLAUDE_UPSTREAM=http://127.0.0.1:3425` を設定しておくと、管理されたブロックが
|
||||
リレーを `ANTHROPIC_BASE_URL` に包み込みます(または直接
|
||||
`ANTHROPIC_BASE_URL=http://127.0.0.1:8787/bili/http://127.0.0.1:3425` を設定します。
|
||||
`localhost` と `127.0.0.1` のどちらでも受け付けます、#5369)。3 つの通信形式すべて
|
||||
(OpenAI Chat / Responses / Anthropic Messages。プロトコルをまたいだ変換を含む)で、
|
||||
端から端まで確認済みです(#4433)。
|
||||
|
||||
**ChatGPT のアカウントプールを持つ、ローカルの Codex/Claude Code のゲートウェイである [opencodex](https://github.com/lidge-jun/opencodex)(`ocx`)と使えますか?** 同じやり方です:クライアントを bili に向け、bili を `/bili/` プレフィックスで ocx に向けます。OpenAI 形式のクライアント(chat completions と Responses、たとえば Codex)→ `OPENAI_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:10100/v1`。Anthropic 形式のクライアント → `ANTHROPIC_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:10100`。キーを必須とするクライアントには、ダミーのキーの値で足ります。それはそのまま通り抜けます。bili は ocx の後ろではなく*前*に置いてください:ocx は最後の段でプロバイダーの認証情報とアカウントプールを持っているので、この順番でしか圧縮とプールが両立しません。ループバックなら 2 つの間でキーは不要です(ocx のデフォルトのループバックのバインドはトークンを読みません)。ループバックでないバインドでは、そのドキュメントのとおり `OPENCODEX_API_AUTH_TOKEN` と `x-opencodex-api-key` のヘッダーが必要です。ルーティングが決定的になるよう、モデルは ocx の `provider/model` の id で指定してください。どのゲートウェイとも同じく、ルーティングされた id は bili のウィンドウの照合からは中身が見えず(`models.<name>.context` で宣言してください)、セッションの途中でアカウントが付け替えられるとプレフィックスキャッシュが無効になります(`/acp-cache` の `KEY SWITCHES` で確認できます)。3 つの通信形式すべて(OpenAI Chat / Responses / Anthropic Messages)で、端から端まで確認済みです(bili 0.1.212 × ocx 2.97.0)。
|
||||
|
||||
**ログとセッションのデータはどこに保存されますか?** ログ:
|
||||
`~/.local/state/billion-context/bili.log`(stderr にも出力されます)。セッションの
|
||||
状態:`~/.local/share/billion-context/`(XDG で上書き可能。Windows のウイルス対策の除外は
|
||||
#362、任意のクリーンアップは #1082) — 完全なパスは [docs/configuration.md](docs/configuration.md) にあります。
|
||||
|
||||
## プロキシの実行
|
||||
|
||||
### Docker で動かす
|
||||
|
||||
リポジトリのルートに `Dockerfile` があります。ビルド時に公開済みの npm の
|
||||
パッケージをインストールし(テスト済みの成果物です。イメージの中では何もコンパイルしません)、
|
||||
プロキシをサービスとして動かします:
|
||||
|
||||
```bash
|
||||
docker build -t billion-context .
|
||||
docker run -d --name bili -p 8787:8787 \
|
||||
-v bili-config:/root/.config/billion-context \
|
||||
-v bili-data:/root/.local/share/billion-context \
|
||||
-v bili-cache:/root/.cache/billion-context \
|
||||
-v bili-state:/root/.local/state/billion-context \
|
||||
billion-context
|
||||
```
|
||||
|
||||
あとは、上記の方法 3 とまったく同じように、クライアントの baseURL を `http://<host>:8787/bili/…` に
|
||||
向けます。
|
||||
|
||||
- **ベース:** `node:24-slim` — 組み込みの `node:sqlite` のストレージエンジンを直接使います(ネイティブのアドオンのダウンロードは不要です)。Node 20 のベースには切り替えないでください:自分でダウンロードする SQLite のエンジンには Node ≥ 22 が必要で、20 ではクラッシュします(#3341)。
|
||||
- **アップデート:** コンテナー内の自己アップデートは**デフォルトでオフ**です(`ACP_AUTO_UPDATE=0`)。コンテナー化したコピーの正式な更新の方法は、新しいイメージをビルドし直すか pull することです。その場で自己アップデートしても、次に作り直したときに黙ってイメージのバージョンに戻ってしまいます。`-e ACP_AUTO_UPDATE=1` で有効に戻せます。ビルド時に `--build-arg BILI_VERSION=0.1.197` でリリースを固定できます(デフォルトは `latest`)。
|
||||
- **データ:** マウントする 4 つのディレクトリは、それぞれ、設定、セッションの状態、アップデートの間隔制御/ロック + キャッシュした SQLite のエンジン、ログを保持します。コンテナーを置き換えても残るよう、ボリュームかバインドマウントでマウントしてください。イメージはそれらを `VOLUME` としても宣言しているので、何も指定しない `docker run` でも、コンテナーのレイヤーの外に置かれます。
|
||||
- **セキュリティ:** コンテナーは、外のクライアントが接続できるよう `0.0.0.0:8787` で待ち受けます。**認証はない**ので、ポートは信頼できるネットワークにだけ公開してください(下記の `--host 0.0.0.0` と同じ注意点です)。Web UI と `/__bili/*` の JSON のエンドポイントは、割り当てたポートを通してそのまま動きます。
|
||||
- **ヘルスチェック:** イメージには、node の組み込みの fetch で 8787 の `/__bili/health` を確認する `HEALTHCHECK` が入っています(slim のベースに curl は不要です)。待ち受けのポートを上書きした場合も、確認は 8787 に固定されたままである点に注意してください。
|
||||
|
||||
### フラグ
|
||||
|
||||
```bash
|
||||
bili --port 9000 # change listen port
|
||||
bili --host 0.0.0.0 # listen on all interfaces (see host note below)
|
||||
bili --debug # verbose logging (also: set "debug": true in config)
|
||||
bili --passthrough # forward without compression (smoke-test mode)
|
||||
bili --config ~/my-bili.json # use a different config file
|
||||
bili update # check & install a newer version now (bypasses throttle)
|
||||
bili doctor --fix # converge drifted dsh profile ledgers (manifest spec / lockfile record / bundle copy) to the on-disk version (#3496)
|
||||
bili --no-auto-update # disable self-update for this run
|
||||
bili --auto-restart-on-update # self-restart when a new version is installed (default off)
|
||||
bili --bin /path/to/client # launcher: spawn this exact client binary instead of auto-detecting (env BILI_CLIENT_BIN)
|
||||
```
|
||||
|
||||
フラグは環境変数と設定ファイルより優先されます。`bili --help` ですべてを一覧できます。
|
||||
|
||||
### リモートのエージェント(`--host`)
|
||||
|
||||
デフォルトでは、プロキシは `127.0.0.1` にバインドし、ループバックの接続だけを受け付けます。ほかのマシンのエージェントに提供するには:`bili --host 0.0.0.0`(または LAN の IP)。リモートのエージェントは、モデルの `baseURL` を `http://<this-host>:<port>/bili/…` に向けます。
|
||||
|
||||
- MITM モードの `CONNECT` も、リモートのクライアントを受け付けるようになります。ただし**許可リストにあるモデルのホストだけ**です。任意のホストへの中身を見ないトンネルはループバックだけのままなので、プロキシがオープンリレーとして使われることはありません。
|
||||
- `/bili/<absolute-url>` の宛先の受け入れ(#409):プロキシ自身と、リンクローカル/メタデータのアドレスは、常に拒否します。ループバック/プライベートの宛先は、ローカルのクライアント(セルフホストの上流)には許可し、リモートのクライアントには、`BILI_TUNNEL_ALLOWED_HOSTS`(`host` または `host:port`、カンマ区切り)に並べない限り拒否します。例外が 1 つあります(#1073):**ローカル**のクライアントが、管理用のパス(`/__bili/*`、`/__acp/*`)を**ループバックの IP リテラル**の宛先に中継する場合は、印を付けずに転送します。リモートの相手とホスト名の宛先には、内部のトンネルの印を無条件に付け続け、管理用のパスには、NAT のヘアピンを通してもトンネル経由では届かないままです。インスタンス自身のエンドポイントの管理用のパスに宛てた絶対形式のリクエストは、トンネルせずにローカルで処理します(フォワードプロキシ形式のヘルスチェックには、本当の応答が返ります)。
|
||||
- **認証はありません**:信頼できる LAN の中か、ファイアウォールの後ろでだけ行ってください。`/__bili/` の管理用のエンドポイントは、ループバックだけのままです。起動時の `[security]` の警告が、上記のことを知らせます。
|
||||
|
||||
### デバッグ
|
||||
|
||||
`bili --debug`(または環境変数 `ACP_DEBUG=1`、または設定の `"debug": true` — フラグ > 環境変数 > 設定)は、すべての `processTurn`(タグの数、トークンの使用量)、ナッジの判断(growth/usage/pendingT1/shouldInject)、クライアントのヘッダー、SSE の書き換えをログに記録します。
|
||||
|
||||
### ログファイル
|
||||
|
||||
すべてのログは、デフォルトで `~/.local/state/billion-context/bili.log`(XDG の state のディレクトリ)にも書き出され、stderr にも引き続き出力されます。設定の `"logFile"` か `ACP_LOG_FILE` で上書きできます(`off` でファイルへの出力を無効にします)。10 MB で自動的にローテーションします(`bili.log.old`)。リクエストごとのキャッシュのヒットの統計は `[acp-usage] round N input=X cached=Y (cache hit Z%)` としてログに出るので、プレフィックスキャッシュの健全性をログから直接測れます。
|
||||
|
||||
### 接続のライフサイクルの調整(#1982)
|
||||
|
||||
クライアントとの接続は、最後の応答のあとで穏やかに閉じます:プロキシが閉じるとき(`Connection: close`)は、ソケットを解放する前に、クライアントからの閉じる合図を最大 `BILI_POST_RESPONSE_LINGER_MS`(デフォルト `5000`)まで待つので、接続をプールするクライアントは、競合するバイトによる RST ではなく、きれいな EOF を受け取ります。関連するつまみ:`BILI_KEEP_ALIVE_TIMEOUT_MS`(アイドルの回収の猶予、デフォルト `5000`)と `BILI_CLIENT_ERROR_BACKSTOP_MS`(エラーの吐き出しの経路の最後の歯止め、デフォルト `30000`) — 詳しい意味は [docs/configuration.md](docs/configuration.md#environment-variables) にあります。
|
||||
|
||||
### 自己アップデート
|
||||
|
||||
プロキシは、起動時と 3 分ごとに npm を確認します。新しいバージョンはその場でインストールされ、通知がログに出ます。**それを使うには `bili` を再起動してください**。ただし、任意の自己再起動(`--auto-restart-on-update` のフラグ、環境変数 `ACP_AUTO_RESTART_ON_UPDATE=1`、または設定の `"autoRestartOnUpdate": true` — デフォルトはオフ)を有効にした場合は別です:処理中のリクエストがゼロのときに、新しいインストールを確認し、接続の受け付けを止め、処理を終わらせ、同じポートで代わりのプロセスを起動し、それが接続を受け付けたら終了します(クライアントは自動で再接続し、セッションの状態はディスク上に残ります)。安全のための関門:処理を終わらせる間の処理中のリクエストがゼロであること、再実行の前のインストールの健全性の確認、そして揺れ動くバージョンがループして再起動し続けないための 10 分間のクールダウンの印です。何かが失敗すると、元のリスナーを再開し、普通の通知に戻ります。
|
||||
|
||||
**段階的な展開(#3619):** 見つかったバージョンが、自動アップデートですぐに適用されることはありません。各インスタンスは、遅延の範囲(組み込みのデフォルトは **15 分〜48 時間**)の中でランダムな時点を 1 つ引き、その時点が来たらアップグレードします。引いた時点は保存されるので、再起動しても引き直すことはありません。そのため、全体のアップグレードはリリースから数分で終わるのではなく、その範囲に分散し、悪いリリースを展開の途中で見つける時間が残ります(#3401/#3600/#3394)。範囲と緊急時の操作は、公開のポリシーファイル(このリポジトリの `auto-update-policy.json`。ETag のキャッシュを使って匿名で取得します)にあります:`hold` は全体の自動アップグレードを凍結し、`blocked` は一覧したバージョンを飛ばし、`pinned` はアップグレードの上限を決めます。設計上、失敗しても開いたままです — 届かないファイルや壊れたファイルはローカルのデフォルトにフォールバックするだけで、このファイルが操作できるのはタイミング/飛ばすもの/固定だけで、何がインストールされるかは決して操作できません。マシンごとの抜け道:手動の `bili update` は `hold`/段階的な展開を迂回します(`blocked`/`pinned` には引き続き従います)。`"staggerMinDelayMs": 0` + `"staggerMaxDelayMs": 0`(または `BILI_UPDATE_STAGGER_MIN_MS`/`BILI_UPDATE_STAGGER_MAX_MS`)で、以前のすぐにアップグレードする動作に戻し、`ACP_AUTO_UPDATE=0` で自動アップデートを完全に無効にします。形式と意味の詳細:[docs/configuration.md → `update`](docs/configuration.md#update)。
|
||||
|
||||
動いているプロセスがディスク上のインストールより古い(「stale」)間は、Web UI にバナー(動いているバージョンとインストール済みのバージョン、自動再起動の状態)が表示され、スクリプト用に `GET /__bili/status` が `{version, diskVersion, stale, autoRestartOnUpdate, advisory, updatePolicy, inFlight}` を返します(`advisory` は有効な重大な欠陥の項目か `null` です。下記を参照。`updatePolicy` は #3619 の展開の状態 — ポリシーの出どころ、`hold`/`pinned`/`blocked`、そして期限付きの保留中の段階的なアップグレード — を報告します)。設定の `"autoUpdate": false` か `ACP_AUTO_UPDATE=0` で永続的に無効にできます。
|
||||
|
||||
**プラグインモード**(`bili opencode` / `bili pi` / `bili dsh` — プロキシは長く動き続けるホストに組み込まれて動きます)では、「bili を再起動する」とは**ホスト**を再起動することです:組み込まれたプロセスは自分では終了できないので、開いたままのホストは起動したときのコードで動き続け、自動アップデートがインストール済みと報告したどの修正も黙って取りこぼします(#1603)。`--auto-restart-on-update` を有効にすると安全な時点で自己再起動させられます。または `/acp` を実行してください(現在は OpenCode のホスト。pi/dsh への対応は #2084 で追跡しています) — ディスク上のインストールが動いているプロセスより新しいときは、状態パネルに古さについての 1 行の警告(動いているバージョンとインストール済みのバージョン)が加わります。自動アップデートが置き換えるのは、ディスク上のファイルと(任意で)プロキシのプロセスだけです。**ホストのプロセスの中に注入したコードは、ホスト自身が再起動して初めて有効になります** — そのため、セッションの途中で実行時に注入が壊れると(破棄されたエージェントのスコープ、無効にされたプラグイン)、それまでの間、モデルの通信は圧縮されずに直接送られます。#3581 以降、この状態は黙っているのではなく見えるようになりました:生きているセッションがないのにプラグインが帰属のゲートの劣化を報告すると、Web UI に「takeover broken」のバナー(エージェント + 拒否の回数)が表示され、`GET /__bili/status` / `/__bili/overview` がエージェントごとの `attribution` の状態(`ok`/`none`/`threw`、拒否の回数、最初の拒否のタイムスタンプ)を公開します。**設計上**エージェントを持たないバックグラウンドのレーン(たとえば dsh のタイトル生成のサイドカー)は、開始者を持たないので、その小さな 1 回限りの呼び出しは定義上、直接送られます。#3651 の取り決めのもとでは、こうした通常の横取りは決して報告されないので、バナーを出すことはありません。バナーが出るのは、帰属の照合そのものが例外を投げたとき(ホストの内部のエラー、たとえば破棄されたエージェントのスコープ)だけで、そのときは何が失敗したかを示します:投げられたエラーの文章、伏せたエンドポイント、その状態がいつ始まったか、圧縮されずに送られたリクエストの数、対処法(ホストのプロセスを再起動する)、そして GitHub の issue をあらかじめ埋めるコピー/診断情報の送信のボタンです。
|
||||
|
||||
**v0.1.183 以降、アップデートの表示はデフォルトで控えめです(#1977):** 通常/推奨のリリースは、`/acp` のパネルのフッターや `acp_status` にアップデートの行を表示しなくなりました。そこに現れるのは `critical` の段階のリリースだけです(`CRITICAL UPDATE READY/AVAILABLE`)。インストール済みで再起動していないリリースを確認する常設の方法は、上記の古さの合図です:Web UI のバナー、`/acp` の 1 行の警告、`GET /__bili/status`。常に出し続ける催促は意図的に置いていません。勧告の経路(#1481)が、自動で目に見える唯一の重大な経路のままです。
|
||||
|
||||
インストールが失敗し続けるとき(書き込めないディレクトリやホストが管理するディレクトリ、ネットワークのエラーなど)、自動アップデートは 3 分の周期のたびに永遠にダウンロードし直して再試行することはなくなりました。3 回続けて失敗すると、指数関数的に間隔を空け(5 分 → 10 → 20 …、上限は 6 時間)、行動につながるヒントを一度だけログに出し(権限/npm のプレフィックスを直す、ユーザー単位でインストールし直す、または `"autoUpdate": false` / `ACP_AUTO_UPDATE=0` で無効にする)、クールダウンの間はその失敗について何もログに出しません(ダウンロードも、再試行の行もありません)。失敗が解消するか、別のバージョンが対象になると、すぐに再開します(#1603)。
|
||||
|
||||
同じ上限付きの再試行は、全体の自己アップデートが自分でコピーを書き込む代わりに動かす**所有者が管理するレーン**にも適用されるようになりました — dsh のデスクトップのその場のコピー、dsh のプロファイルのバンドル、pi の npm のコピーです(#2192)。各レーンは、レーン + 対象のバージョンをキーにして自分の失敗の連続を記録するので、ずっと壊れたままのデスクトップの構成が、周期ごとに tarball 全体をダウンロードし直すことはなくなりました(修正前は、影響を受けたマシン 1 台あたり 1 日に最大約 480 回のダウンロードがありました)。3 回で同じ指数関数的なクールダウンに入り、一度だけのヒントが失敗しているレーンと、その手動での直し方(`dsh plugin --profile <name> add …`、`pi update --extension …`、またはデスクトップのプロファイルを作り直す)を示します。ホストが管理するインスタンスは、全体の 3 分の予算を使う代わりに、別の間隔制御の印のもとで、自分のより遅い周期 — 30 分 + 最大 15 分のゆらぎ — でも確認します。失敗の連続は、キャッシュのディレクトリにある小さな状態ファイル(`.install-backoff.json`)を通して、マシン上のすべての bili のプロセスで共有されるので、複数の動いているインスタンスがそれぞれ自分の再試行の予算を使い切ることはありません。きれいに終わった `bili plugin update` は、dsh のプロファイルのレーンをすぐに解除します。ファイルはアトミックに書き込まれ(tmp + rename)、どの書き手もディスク上にすでにあるものとマージするので、同時に動くインスタンスは互いの連続を上書きせずに協調します。長く動くプロセスは、ファイルが変わると読み直すので、1 つのコピーによる手動の解除は、ほかのコピーの次の確認で見えるようになります。再試行の方向には安全側に倒れます — 壊れたファイルや飛んだ時計は捨てられ、レーンを長く黙らせることは決して許しません。`bili plugin update` は dsh のプロファイルのレーンのキーを消し、修復されたデスクトップのレーンは、次にその場の更新に成功したときに自分のキーを消します。
|
||||
|
||||
### ネットワーク/VPN の変更後に古くなるローカル DNS(#5224)
|
||||
|
||||
**長く動き続ける**単体のプロキシは、WSL/VPN/TUN の構成が変わったあとも、古い OS のリゾルバーの状態を持ち続けることがあります。プロセスはシステムのリゾルバーをキャッシュし、libuv の `getaddrinfo` は `/etc/resolv.conf` を自分では読み直さないためです。症状:`/bili/` のトンネルを通るモデルへのリクエストがすべて、詳細 `unresolvable` 付きの HTTP 502 `tunnel_destination_denied` を返します。同じ時点で新しく起動した `bili` は同じホストを問題なく解決でき、新しいシェルからの `curl` も動くのにです。次のどちらかの対処で直ります:
|
||||
- **プロキシのプロセスを再起動する** — 新しいプロセスはシステムのリゾルバーを読み直します。ランチャーのレーンと dsh の Web プロファイルのレーンでは、プロキシは*別に登録された*プロセス(インスタンスのレジストリ)なので、クライアント/ホストだけを再起動しても同じ固まったプロキシをまた使うだけで、効果は**ありません** — プロキシそのものを止めて起動し直す必要があります。(組み込みのプラグインモードでは、プロキシはホストの中で動くので、ホストを再起動すれば*直ります*。)
|
||||
- **外向きの通信を上流のプロキシに通す** — `-F http://<host:port>` または `BILI_UPSTREAM_PROXY=… BILI_UPSTREAM_PROXY_MODE=auto`:宛先はそのプロキシが遠隔で解決するので、bili が受け入れのために自分の(古い)リゾルバーを参照することはありません。
|
||||
|
||||
### 重大な欠陥の勧告(強制アップデート)
|
||||
|
||||
自動アップデートとは独立して(#1481)、`autoUpdate` がオフでも、プロキシは小さな付属の npm のパッケージ(`billion-context-advisories`。このリポジトリの [`advisories/`](advisories/) のディレクトリから CI が公開します)を同じ 3 分の周期で確認します。各勧告は、壊れたバージョンの semver の範囲(`affected`)、インストールすべき正確なバージョン(`target` — 現在のものより*古い*、つまりロールバックのこともあります)、ユーザー向けの `reason` を示します。ローカルのバージョンが `affected` に入ると、bili は自己アップデーターの完全な安全の連鎖(プロセスをまたいだロック、バックアップ + 確認 + ロールバック。ソースのチェックアウトとホストが管理するインストールは、代わりに手動の手順を示して拒否します)を通して `target` を強制的にインストールし、目立つように警告します:プロセスごと・勧告の id ごとに一度だけの `[advisory] ⚠️ …` のログの行、理由と正確な手動のアップグレードのコマンドを示す Web UI のバナー、そして `/__bili/status` の `advisory` の下の有効な項目です。この確認は設計上、失敗しても開いたままです:届かない、または壊れた勧告の出どころは警告を出すだけで、それによってモデルの通信が止められることは決してありません。設定(`"advisoryCheck": false`)か環境変数(`BILI_ADVISORY_CHECK=0`)で無効にできます。`"advisoryUrl"` / `BILI_ADVISORY_URL` で独自の文書を指定できます。
|
||||
|
||||
**お知らせ**(#5548) — 上記の欠陥の勧告とは別に、3 つの出どころが Web UI のバナーを供給し、同じ id は **ローカルのファイル > リモートのフィード > 組み込み** の順で上書きします:(1) *組み込み* — UI の i18n の文字列から描画する 1 回限りの通知。(2) *ローカル* — `<config dir>/announcements/*.json`(デフォルトは `~/.config/billion-context/announcements/`)に JSON ファイルを置くと、自動で描画されます:種類から色が決まる 2 か国語の記録、npm 形式の `versions` の対象指定(`>=a.b.c`、`^`、`~`、`[lo hi]`、`||` の一覧)、`percent` による段階的な展開、時間の範囲、種類ごとの優先度 — 1 つの悪いファイルは、自分だけを無効にします。(3) *リモート* — このリポジトリの master ブランチの [`announcements/remote.json`](announcements/remote.json)(すべての PR で CI が lint します)。約 3 分の監視の周期で取得し、最後に正常だったスナップショットは再起動や障害を越えて残り、壊れた push は拒否されます。届かないインストール(ファイアウォール)では、`"remoteAnnouncementsUrl"` / `BILI_ANNOUNCEMENTS_URL` を同じ文書のリレーのミラーに向けます。閉じる操作は、各記録が宣言したモードに従います:`persistent`(デフォルト。内容に基づくアドレスで、通知を編集するとまた表示されます)、`instance`(このプロセスの実行の間だけ)、`always`(閉じるボタンなしで表示されます)。組み込みの紹介の通知を閉じたことは、インストールごとに bili の統一ストレージ(デフォルトは SQLite。MySQL のバックエンドも使えます)に記録されるので、再起動しても残ります — 古い `upgrade-notices.json` の状態ファイルは、統一のサイドカーのない古い形式だけのインストールでのフォールバックとして残っているだけです。公式のフィードは、現在は空の一覧を配信しています。
|
||||
|
||||
## 設定
|
||||
|
||||
設定の完全なリファレンス — 設定ファイルの場所、最上位のキー、
|
||||
プロバイダー、圧縮の調整、環境変数 — は
|
||||
**[docs/configuration.md](docs/configuration.md)** にあります。
|
||||
|
||||
### 設定ファイル
|
||||
|
||||
`~/.config/billion-context/billion-context.json` にある 1 つの JSON 文書です
|
||||
(`$XDG_CONFIG_HOME/billion-context/`。パスは `BILI_CONFIG_FILE` で上書きできます)。
|
||||
複数の出どころが同じつまみを設定したときの優先順位:**CLI のフラグ(あるもの) > 環境変数 > 設定ファイル > 組み込みのデフォルト** — どの環境変数も、上書きの段として引き続き使えます。
|
||||
|
||||
中身(詳細は docs/configuration.md):
|
||||
|
||||
- `providers` — プロバイダーごとのルーティングの表:上流の上書き、モデルのコンテキストウィンドウ、プロバイダー/モデルごとの圧縮の調整、通信プロトコルの宣言、圧縮の有効化。
|
||||
- `compress` — 3 段階の圧縮の調整(全体 → プロバイダー → モデル):しきい値、ナッジの周期、保持のルール、プロンプト、段階。
|
||||
- サーバー単位のブロック — プロセス全体の挙動。#2030 で追加されたものを含みます:`network`(タイムアウト/再試行/keep-alive/事前チェックの周期)、`persist`(セッションの永続化の形式 + 末尾)、`sessions`(上限 + GC のポリシー)、`update`(レジストリのミラー + 確認の間隔)、`diagnostics`(ダンプ、描画のタグのモード、注入のスイッチ)、`fakeCompletion`、そしてスカラーの `codexCompact` / `ccrRetrievalTtlMs` / `decompressTmpCap` と、拡張の `mitm.handshakeTimeoutMs`、`compat.noCacheControl`、`compat.keepResponseId`。
|
||||
|
||||
最小限の例:
|
||||
|
||||
```json
|
||||
{
|
||||
"network": { "upstreamTimeoutMs": 900000 },
|
||||
"persist": { "zstd": true },
|
||||
"sessions": { "gc": { "enabled": true, "maxAgeDays": 14 } }
|
||||
}
|
||||
```
|
||||
|
||||
多くの人がまず探すつまみ:
|
||||
|
||||
- **上流のプロキシ(ファイアウォール/GFW)** — プロキシ自身の外向きの通信を v2rayA/clash に通す方法:解決の完全な順序、空文字列 = 明示的な直接接続、SOCKS5 の拒否、両方の外向きの経路、`mitm://` と `https://` のキーの方式は、[docs/configuration.md](docs/configuration.md) にあります(Server Settings → `proxy`、Providers → キーの方式)。
|
||||
- **通信の互換のためのロールの書き換え(`compat.roles`)** — 上流が `developer` のロールを拒否しますか? [docs/configuration.md](docs/configuration.md) で扱っています(Server Settings → `compat`) — 設定をまったく必要としない、失敗から学ぶ自動の修正も含みます。
|
||||
- **署名付きの上流(本文を覆う署名)** — リクエストに本文を覆う署名が付くゲートウェイ(CodeArts APIG の `SDK-HMAC-SHA256`、または `x-ofm-signature` のようなゲートウェイ独自のヘッダー):組み込みの方式は dsh で透過的に署名し直します。それ以外に検出された方式は、常にローカルで拒否します — 署名付きのリクエストは、署名し直して圧縮するか、拒否するかのどちらかで、署名なしで通すことは決してありません — そして bili は、その方式の署名し直しの仕組みを出荷するまで、起動時と Web UI で知らせ続けます(#1884/#2090)。検出のルール、方式ごとの上書き、`BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_CODEARTS_REF` は [docs/configuration.md](docs/configuration.md) にあります(Server Settings → `resign`)。
|
||||
|
||||
### pi の組み込みサブエージェント
|
||||
|
||||
`bili pi` やネイティブの pi プラグイン(`bili plugin install pi`)を使うと、組み込みのサブエージェントの機能がデフォルトで有効になります:`acp_delegate`、`acp_delegate_wait`、`acp_delegate_cancel` です。この追加のツールは pi に固有のものです。
|
||||
|
||||
**サブエージェントの実装は 1 つだけを有効にしてください。** 組み込みの機能を使う場合は、ツール、プロンプト、挙動が重ならないよう、ユーザーとプロジェクトの両方の設定で、ほかの pi のサブエージェントのプラグイン(たとえば `pi-subagents` や、別にインストールした `billion-context-pi-subagents`)を削除するか無効にしてください。別のサブエージェントのプラグインを使いたい場合は、代わりに組み込みの機能を無効にしてください。どちらの範囲(プロジェクトかユーザー)でも `pi-subagents` がインストールされていると、デフォルトで組み込みの delegate が自動で身を引きます — ユーザーの範囲のインストールはすべてのプロジェクトで読み込まれるので、そこでもこの保護が効きます(#5637)。それと並べて `acp_delegate` を残すには、`delegate.forceEnable` を設定してください。
|
||||
|
||||
コンテキストの圧縮は残したまま組み込みのサブエージェントを無効にするには、ほかの設定を残したまま、次の内容を `~/.config/billion-context/billion-context.json`(または `BILI_CONFIG_FILE` で選んだファイル)にマージしてください:
|
||||
|
||||
```json
|
||||
{
|
||||
"pi": {
|
||||
"subagents": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
変更を反映するには、pi を再起動して新しいセッションを始めてください。これで 3 つの delegate のツール、そのシステムプロンプトのセクション、fleet のキーボードショートカットが無効になります。コンテキストの圧縮は有効なままです。別にインストールしたサブエージェントのプラグインは無効になりません。その他のオプション:[サブエージェントの設定](docs/configuration.md#pi)。
|
||||
|
||||
## セッションの仕組み
|
||||
|
||||
プロキシは、圧縮の状態を、**クライアント自身が渡す会話の値をそのまま**キーにして管理します(`src/session-id.ts`) — ハッシュも、プロトコル/上流/API キーの次元も使いません(それらは会話の途中で変わり、ユーザーが話し続けたまさにそのときに状態を孤立させてしまったためです、#280/#286)。この id はプロキシの中にとどまり(状態のストア、永続化、UI のラベル)、上流に送られることはありません。
|
||||
|
||||
値の出どころは、最初に見つかったものが勝ちます:プラグインの
|
||||
`x-bili-plugin-conversation`(`x-bili-plugin` の
|
||||
印のヘッダーと一緒の場合だけ使います)、次にクライアントごとのヘッダー(`x-claude-code-session-id`、
|
||||
`x-grok-session-id`/`x-grok-conv-id`、`x-mavis-session-id`、
|
||||
`x-opencode-session-id`)、次に汎用の
|
||||
ヘッダー(`x-session-affinity`、`x-acp-session`、`x-session-id`、
|
||||
`x-opencode-session`、`session-id`/`session_id`)、そして本文のフィールド:
|
||||
Responses の通信形式の `session_id` / `metadata.session_id`、そして
|
||||
Responses/OpenAI/Anthropic の通信形式で、内容のフィンガープリントによるフォールバックより優先される
|
||||
`prompt_cache_key` です。
|
||||
|
||||
| クライアント | 会話の id を送るか | 出どころ |
|
||||
|---|---|---|
|
||||
| **Codex** | ✅ はい | `body.session_id` / ターンのメタデータのスレッド id |
|
||||
| **OpenCode** | ✅ はい | `x-opencode-session-id` ヘッダー(`ses_…`、リクエスト自身のセッション id。2.x は、それと並べて `x-session-affinity`/`X-Session-Id`/`x-opencode-session` で*親*のキャッシュのルーティングのアフィニティを送ります、#2779 — 1.x はそれらで自分の id を送っていました) |
|
||||
| **Claude Code** | ✅ はい | `x-claude-code-session-id` ヘッダー |
|
||||
| **omp**(プラグイン経由) | ✅ はい | どのフィンガープリントよりも優先される `prompt_cache_key`(#268) |
|
||||
| **pi**(素の状態) | ❌ いいえ | 何もなし → 下記の匿名のプレフィックスアフィニティ |
|
||||
|
||||
**omp の注意点(#2583/#3556):** 最近の OMP のビルドでは、デフォルトの Anthropic(`anthropic-messages`)のリクエストは、OMP の Cowork の通信路を通して node:https で直接ホストを出ていきます — bili の fetch の層に届かないので、そこでは `prompt_cache_key` の付与を*控えます*(付与すると、そのフィールドが Anthropic の厳格なスキーマに漏れて HTTP 400 になります)。#3556 以降、`bili omp` のランチャーのレーンは、デフォルトでその穴を開けたままにしなくなりました:自分で `PI_PROXY` / `PI_PROXY_ANTHROPIC` を設定しない限り、ランチャーが `PI_PROXY_ANTHROPIC=<proxy>` を export し、Cowork を Bun の fetch に乗せて、ほかのすべてのレーンと同じようにプロキシを通します(圧縮され、セッションからも見えます。付与したキーはプロキシが使ってから取り除きます)。直接かつ匿名のままなのは、ネイティブの omp のモードと、自分でプロキシの構成を固定したランチャーのレーンだけです。それ以外の omp の通信は、付与した識別子を保ちます。詳細:[docs/technical-notes.md](docs/technical-notes.md)。
|
||||
|
||||
**omp の advisor の分離(#5567):** omp の永続的なバックグラウンドのストリーム(たとえば、2 つ目のモデルで動くターンのレビュー役の *advisor*)は別々のモデルの会話ですが、その Chat Completions のリクエストは自分自身の会話の合図を持ちません — プラグインはメインのセッションの id を `prompt_cache_key` に付与するので、両方のストリームが 1 つの bili のセッションに入ってしまいます。2 つのモデル/プロトコルが 1 つの台帳に混ざると、台帳が壊れます:参照が DEAD になり(`cannot be anchored` / `content-changed`)、折りたたみの範囲がずれ、使用量/ウィンドウ/ナッジの計量がストリーム間で混線します(ログの行 `foreign payload under a shared session id (#4805)` が、プロキシがそれに気づいた場所を示します)。ホスト側の識別子の修正が入るまで([#5567](https://github.com/ranxianglei/billion-context/issues/5567) で追跡しています)、advisor が通信上で自分の識別子を持てるようにして分離してください:omp のモデルのレジストリの設定(`models.yml` の `providers:` のセクション)で、advisor のプロバイダーの項目に `compat.supportsPromptCacheKey: true` を設定します — そうすると pi-ai は advisor 自身のセッションの UUID を `prompt_cache_key` としてシリアライズし、bili はそれを自分のセッションに結び付けます。限界:omp が advisor に共有のキャッシュのキーを明示的に渡す場合は効きません。分離されると、advisor は自分の圧縮の状態を持つ独立したセッションとして動きます。Web のパネルで、advisor の通信が別のセッション id の下に現れることを確認してください。
|
||||
|
||||
**ヘッダーのないクライアント(pi のようなもの):匿名のプレフィックスアフィニティ。** 会話の合図がまったくない場合、プロキシは再送された履歴そのものからセッションを決めます(`src/prefix-affinity.ts`、#309):リクエストが保存済みのセッションにつながり直すのは、その履歴が、そのセッションのメッセージの連なりを位置 0 からバイト単位で正確に再現する場合だけです。そうでなければ、決定的な自分専用の `pfa-…` のセッションを持ちます。結果として(#1262):**再開した**会話は自分のセッションにつながり直します(プロキシを再起動したあとでも、#499)。**最初の発言が同じ新しいタスクは、ほかの会話のブロックを引き継ぎません** — 新しい、完全に別のセッションを作ります。使える合図がまったくないリクエストには、黙って衝突させるのではなく、明示的な 400 を返します。
|
||||
|
||||
設計の記録と脅威モデル:[docs/session-identity.md](docs/session-identity.md)。
|
||||
メッセージの粒度での兄弟分(識別子が割り当てられた id ではなく、内容から導かれる理由)は
|
||||
[docs/message-identity.md](docs/message-identity.md) です。
|
||||
|
||||
上流でのスティッキーなルーティングのために、プロキシが転送するのは、クライアントが
|
||||
すでに渡した識別子の値だけです(たとえば本文の `session_id` は、上流に
|
||||
`x-session-id` として転送されます)。自分で作り出すことは決してありません。
|
||||
|
||||
**おすすめ:** 明示的な id を持つクライアントは、同時に動かしても安全です。ヘッダーのないクライアントを複数のエージェントで使う場合は、クライアントのプラグイン(会話ごとに安定した id を付与します)を使うか、明示的な `x-acp-session` のヘッダーを渡してください — そうしなくても、プレフィックスアフィニティが別々のタスクを分けたままにします(分岐したフォークには、生の再送 1 回と、圧縮の段階のやり直しのコストがかかります)。
|
||||
|
||||
### 派生(子)セッションは親の圧縮済みコンテキストを引き継ぐ(#1333、#1362)
|
||||
|
||||
子のセッション(空の履歴から始まるサブエージェント/フォーク)は、生まれたときに自分の系譜を報告します — その識別子の登録が `parentConversationId` を運び、プロキシが読み取り専用の `derivedFrom` のリンクを記録します — そのため、`decompress` / `search_context` は、子が自分では見ていない内容について、親の連なりをたどってフォールバックします(循環を防ぎ、深さの上限は 8)。子に何かがコピーされることはなく、親が変更されることもありません。親がわからない場合、子は単に新しく始めます。レーンごとの親の合図(pi/omp の `parentSession` ヘッダー、OpenCode V1/V2 の `parentID`):[docs/session-identity.md](docs/session-identity.md#derived-child-sessions-lineage-at-birth-1333-1362)。claude/codex/dsh は、ここでは何も必要ありません:サブエージェントの間で 1 つのセッション id を共有するか、子のセッションという概念をまったく持たないためです。
|
||||
|
||||
### 複数のインスタンスを動かす(#3633)
|
||||
|
||||
**1 つの会話は、その一生を通じて 1 つのインスタンスに属します。** 折りたたみの状態、
|
||||
プレフィックスアフィニティ、要約の予算は、セッション id をキーにしていて、その本来の居場所は
|
||||
クライアント自身の履歴です — そしてセッションの行は、そのインスタンスの
|
||||
`index.db` にあります。インスタンスの間に共有のストアはありません:何も複製されず、
|
||||
何もフェイルオーバーせず、何もセッションを別のインスタンスに復元しません。
|
||||
|
||||
複数のインスタンスを 1 つの Service の後ろに置きたくなる人への影響:
|
||||
|
||||
- **スティッキーなルーティングが必須で、`ClientIP` のアフィニティは間違った種類です。**
|
||||
会話の識別子はヘッダーかリクエストの本文にあり、送信元の IP にはありません —
|
||||
Service がハッシュできるのは IP だけなので、レプリカ N に固定されたクライアントは、
|
||||
レプリカ N が死ぬと、*すべての*セッションを黙って失います(スループットを買う代わりに
|
||||
可用性を売り払うことになり、まさに負荷のためにスケールアウトしたときに起こります)。
|
||||
正しいルーティングは、会話のヘッダー
|
||||
(`x-bili-plugin-conversation`、`x-opencode-session-id`、`x-acp-session` など)を
|
||||
バックエンドにハッシュする L7 のプロキシで、さらにクライアントが実際にそれを送っていることです(ヘッダーのないクライアントは
|
||||
代わりにプレフィックスアフィニティを使い、L7 のプロキシではそれをハッシュできません)。
|
||||
- **インスタンスの数はボリュームの数です。** 状態のディレクトリは、WAL モードの SQLite
|
||||
(`busy_timeout=5000`)を持つ 1 つのローカルのディレクトリです。一貫して共有される
|
||||
`-shm` と、書き手の間で動くバイト範囲のロックには、決して共有しない RWO のボリュームが
|
||||
必要です。2 つのインスタンスを同じ RWX/NFS のパスに向けても、
|
||||
共有のストアにはなりません — タイムアウトの陰で黙って壊れるだけです。
|
||||
インスタンスごとに 1 つの RWO のボリュームで、
|
||||
`storage.unified` も含みます:「unified」とは、*そのインスタンスにとっての* 1 つのストア
|
||||
(セッション + CCR + CAS を 1 つの `index.db` に)という意味で、全体で 1 つのストアという意味ではありません。
|
||||
- **実際にスケールする作業**は、*多くの独立した短命の
|
||||
会話*です — クライアントごと、またはレーンごとに 1 つのプロキシ — *プロキシの間で負荷分散した 1 つの長い
|
||||
会話*ではありません。長い会話は、
|
||||
設計上、単一のインスタンスです。
|
||||
|
||||
**1 台のマシンに複数のインストール(#5046)。** 上記の構成はデプロイの
|
||||
レプリカについてのものです。1 台のデスクトップにも似た状況があります:1 台の
|
||||
マシンに 2 つのインストール(たとえば 2 つの DSH のプロファイル — デスクトップ + ボット、またはグローバルな npm のコピーと
|
||||
ホストのツリーのコピー)があると、それぞれが自分のプロキシを起動し、分離しない限り、どちらも
|
||||
同じデフォルトの XDG のセッションのディレクトリと同じ設定ファイルを使います。複数の
|
||||
プロセスが 1 つのローカルディスクの `index.db` に書き込むのは、サポートされた構成です
|
||||
(#5082/#5091) — SQLite の WAL はローカルのファイルシステムでは複数のプロセスに対して安全です — そのため、
|
||||
生きているほかの書き手がいても、起動が止まることは決してありません:相手は情報レベルの
|
||||
`[storage] process pid … is also using …` の行と、状態の通信に現れるだけで、
|
||||
それ以上のことはありません(2026-10-31 に決まったポリシーで、まさにこの形について #5046/B の時期の
|
||||
起動の拒否を取り下げたものです)。本当に危険なまま残っているのは、
|
||||
2 つのインストールが同じ*セッション*を同時にたどることで — その場合は
|
||||
別に警告します(スプリットブレインの奪い合い、#3923)。それでもインストールごとに履歴とストアを厳密に
|
||||
分けたい場合は、そのインストールの
|
||||
ランチャー/プロファイルの環境を通して、それぞれに専用の `BILI_SESSIONS_DIR`(設定も変えたい場合は
|
||||
`BILI_CONFIG_FILE` も)を与えてください — 全体の環境変数を変える必要はありません。分離されると、
|
||||
`[instances]` の通知は完全に消えます。上記のデプロイの場合との違いに注意してください:
|
||||
WAL の SQLite を持つローカルディスクは多くの書き手を許容しますが、
|
||||
共有の RWX/NFS のストレージは許容せず、引き続きボリュームごとに 1 つの書き手が必要です。
|
||||
|
||||
名前についての注意:`POST /__bili/replicas` が作るのは、セッションの**チェックポイントのフォーク**
|
||||
(保存済みのチェックポイントから)で、Pod のレプリカではありません — `/__bili/checkpoints` と読み替えてください。
|
||||
|
||||
|
||||
プロキシは、長いセッションのターンごとに、各セッションの状態ファイルを書き直します。Windows では、リアルタイムのウイルス対策(Defender)、検索のインデクサー、同期ツール(OneDrive)が、書き込みの途中でセッションのディレクトリをロックすることがあり、ロックが解けるまで永続化が `EPERM` で失敗します。根本的な対処:`%USERPROFILE%\.local\share\billion-context\` をウイルス対策の除外に追加し(Defender の手順も載っています)、同期ツールをそのパスから外してください — [docs/configuration.md](docs/configuration.md#windows-exclude-the-sessions-dir-from-antivirus-362)。同じ除外で、統一ストレージの `index.db` が開けない問題(`unable to open database file`、#3823)も解決します — ストレージの劣化の警告は、それを最初の容疑者として挙げます。
|
||||
|
||||
### セッションファイルのクリーンアップ(#1082)
|
||||
|
||||
短命のセッションは、二度と再開されない小さな状態ファイルを残します。クリーンアップは**任意**です(`BILI_SESSION_GC=1`。デフォルトはオフ — セッションのファイルはユーザーのデータで、黙って削除するポリシーはありません):有効にすると、bili は起動時と 1 時間ごとにセッションのディレクトリを走査し、次の両方を満たすファイルだけを削除します — `BILI_SESSION_GC_MAX_AGE_DAYS`(デフォルト 7 日)より古く、かつ一度も圧縮されておらず、最新のリクエストの本文が `BILI_SESSION_GC_MAX_TOKENS` トークン(デフォルト 100 万)以下であること — そのため、削除で失われるのはバイトだけです。CCR の内容のストアは、そのセッションのファイルのライフサイクルに従います。圧縮されたセッションが削除されることはなく、すべての削除は監査ログに記録されます。ポリシーの全体:[docs/configuration.md](docs/configuration.md#environment-variables)。
|
||||
|
||||
### ストレージのメンテナンス CLI(#3928)
|
||||
|
||||
パネルが HTTP で公開しているのと同じストアのメンテナンス(`POST /__bili/storage/gc`、`POST /__bili/storage/restore`)には、薄い CLI の層があります — プロキシは不要で、セッションのディレクトリを持つどのマシンでも実行できます:
|
||||
|
||||
```bash
|
||||
bili sessions ls # id, label, decoded size, last-updated, storage status (active/archived)
|
||||
bili sessions rm <id> # full delete (content refcount release incl. media); shrinks index.db afterwards (--no-vacuum skips)
|
||||
bili sessions archive <id> # export to archive/archive.jsonl + sweep rows; tombstone keeps label & identity
|
||||
bili sessions restore <id> # bring an archived session back from the log line
|
||||
bili sessions foreign-blocks # (#5312) list fold blocks whose covered messages never belonged to this transcript — dry-run; --apply reversibly archives them, --restore <sid>:<bid> brings one back
|
||||
bili storage gc [--days N] [--vacuum full|incremental] [--dry-run]
|
||||
# print the sweep plan (sessions past retention, zero-ref content rows, ~pages reclaimable), then run the same gc() the HTTP endpoint calls; --dry-run stops after the plan
|
||||
```
|
||||
|
||||
`archive`/`restore`/`gc` には統一ストア(`BILI_STORAGE_UNIFIED=shadow|full` または設定ファイルの `storage.unified`)が必要です — 古い形式だけのインストールは、ヒントを示して拒否します。`--days` のデフォルトは `storage.archiveAfterDays`(365)です。スケジューラーはありません:これらは必要なときに実行します。すべてのコマンドが `--json` を受け付けます。
|
||||
|
||||
**大きなデータベースでは、完全なバキュームはオフラインの操作です(#4612)。** `--vacuum full`(デフォルト)は、排他的な書き込みのロックのもとで index.db 全体を書き直します — データベースのサイズに比例し、数 GB のデータベースでは数分から数十分かかり、途中の進捗はありません(SQLite の VACUUM はアトミックで、分割できません)。同じセッションのディレクトリからプロキシが動いている間にこれを実行すると、そのプロキシの書き込みが、ストレージの層が劣化するまで止められてしまうので、`storage gc --vacuum full` は**ほかの生きているプロセスがデータベースを持っているときは開始を拒否します**(`index.db.lock` の pid の規律、#4175):CLI は行動につながるメッセージとともに終了コード 1 で終了し、パネルのエンドポイントは HTTP 409 を返します。先にほかのインスタンスを止めて(または終了を待って)から、やり直してください。オンラインで安全に縮めるには `--vacuum incremental` を使ってください。これは排他的なロックを取らずに、短いトランザクションで空いたページを回収します。参照のない行の削除の走査そのものは、どちらの場合もバッチごとに進捗を表示しながら行われます。
|
||||
|
||||
## 状況
|
||||
|
||||
初期段階です。プロトコルの処理と圧縮は、モックのテスト(500 以上が合格)に対して動いています。実際のモデルとの統合テストが次のマイルストーンです。粗い部分があることを想定してください。
|
||||
|
||||
pi / omp / opencode 向けのクライアント側のプラグインは、協調するプロキシの経路のために `billion-context` の中(`dist/agent/*.js`)に同梱されています。`billion-context`、単体の `billion-context-pi`、`opencode-acp` の関係については、上記の **「どれを使えばよいか」** のセクションを参照してください。
|
||||
|
||||
## 帰属表示の要件(MIT に加えた 1 つの条項)
|
||||
|
||||
このプロジェクトは MIT ライセンス**に 1 つの追加の条項を加えたもの**です:ユーザーが目にしたり操作したりできる製品やサービス(商用でもオープンソースでも)で、このソフトウェアを使うものは、ホームページ、ドキュメント、または About/Credits のページで、billion-context を使っていることを、このリポジトリへのリンクとともに表示しなければなりません。純粋にサーバー側で使う場合や組み込んで使う場合は、同梱するドキュメントで満たせます。[LICENSE](LICENSE) の最後にある **Additional Term** を参照してください。
|
||||
|
||||
このプロジェクトを使って何かを作ったら、ぜひ教えてください:issue を開いてもらえれば(義務ではありません)、どこで使われているかを追跡できます。
|
||||
|
||||
## ライセンス
|
||||
|
||||
MIT
|
||||
@@ -1,6 +1,6 @@
|
||||
# billion-context
|
||||
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a></p>
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a> | <a href="./README.ja.md">日本語</a></p>
|
||||
|
||||
<p align="center"><strong>Context-compression plugin</strong> — <em>billion-context is all you need.</em></p>
|
||||
|
||||
@@ -50,7 +50,8 @@
|
||||
|
||||
QQ Group:
|
||||
1056132097 (full)
|
||||
1108730198 (open)
|
||||
1108730198 (full)
|
||||
1129868472 (open)
|
||||
|
||||
---
|
||||
|
||||
@@ -62,6 +63,10 @@ QQ Group:
|
||||
|
||||
A production-scale longitudinal study: 4.5 months, three hosts, 174,327 model calls, 18.76B cumulative input tokens (~24.7B across all hosts), zero window violations on 204,800-token models, marathon sessions of 8,584–12,049 calls.
|
||||
|
||||
### 📊 Independent Third-Party Benchmarks
|
||||
|
||||
- **[1,500-Item Cross-Benchmark Evaluation (`LongMemEval-S` · `ContextBench` · `MemoryAgentBench`)](./benchmarks/third-party-1500/README.md)** ([中文版](./benchmarks/third-party-1500/README.zh-CN.md)) — head-to-head comparison of `billion-context` (`v0.1.202`) against `full` context and 3 RAG arms (`bm25`, `embedding`, `embedding-rerank`) with `DeepSeek V4.1 Flash`, `Qwen3-Embedding-8B`, `Qwen3-Reranker-4B`, and `Pi Agent`: **#1 on ContextBench** (`0.3097` Utilized F1, `-58.3%` cost vs `full`), **+16.6% over best RAG on LongMemEval-S** (`79.20%` vs `62.60%`, `-71.1%` independent-session cost vs `full`), and **100% survival on 1.48M-token MemoryAgentBench TTL** (`30×` steady-state compression where `full` fails `199/199`).
|
||||
|
||||
---
|
||||
|
||||
`billion-context` sits between **any** agent and its model API, rewriting Anthropic/OpenAI streams with [acp-kernel](https://github.com/ranxianglei/acp-kernel) compression. The model decides **when** and **what** to compress into high-fidelity summaries — not a hard truncation limit.
|
||||
@@ -74,21 +79,7 @@ Unlike a host's built-in summarizer, compression here is **incremental, reversib
|
||||
|
||||
## How it works
|
||||
|
||||
```
|
||||
Agent (Claude Code / Codex / Cursor / Aider ...)
|
||||
│ you point the agent's base URL at the proxy
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ billion-context│ 1. parse the request (Anthropic or OpenAI shape)
|
||||
│ proxy │ 2. run acp-kernel compression on the conversation
|
||||
│ │ 3. inject a `compress` tool + compression philosophy
|
||||
│ │ 4. forward to the real model API
|
||||
│ │ 5. rewrite the streaming response
|
||||
└─────────────────┘
|
||||
│
|
||||
▼
|
||||
real model API (Anthropic / OpenAI / compatible)
|
||||
```
|
||||

|
||||
|
||||
### Context-management tools
|
||||
|
||||
@@ -105,24 +96,25 @@ Pick by your client:
|
||||
|
||||
| Client | Use |
|
||||
|---|---|
|
||||
| **pi** | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili pi` (launcher) or `bili plugin install pi` (native); standalone [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) remains usable — details: [CLIENTS.md](CLIENTS.md#pi-pidev-coding-agent) |
|
||||
| **opencode** (1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili opencode` (launcher) or `bili plugin install opencode` (native); standalone [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) remains usable on 1.x — full guide: [OpenCode](CLIENTS.md#opencode) |
|
||||
| **pi** | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili pi` (launcher) or `bili plugin install pi` (native); standalone [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) remains usable — details: [docs/clients.md](docs/clients.md#pi-pidev-coding-agent) |
|
||||
| **opencode** (1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) — `bili opencode` (launcher) or `bili plugin install opencode` (native); standalone [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) remains usable on 1.x — full guide: [OpenCode](docs/clients.md#opencode) |
|
||||
| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili omp` (built-in plugin) or `bili plugin install omp` (self-spawning native plugin, no launcher) |
|
||||
| **dsh** | `bili dsh` (launcher — full native plugin via `--patch`) or `bili plugin install dsh` ≡ `dsh plugin --profile <name> add billion-context` (one unified lane) — details: [CLIENTS.md](CLIENTS.md) |
|
||||
| **kimi** | `bili plugin install kimi` (self-spawning native, Kimi Code ≥ 2.0.0) or `bili kimi` (cert-MITM) or `/bili/` prefix — details: [CLIENTS.md](CLIENTS.md) |
|
||||
| **dsh** | `bili dsh` (launcher — full native plugin via `--patch`) or `bili plugin install dsh` ≡ `dsh plugin --profile <name> add billion-context` (one unified lane) — details: [docs/clients.md](docs/clients.md) |
|
||||
| **kimi** | `bili plugin install kimi` (self-spawning native, Kimi Code ≥ 2.0.0) or `bili kimi` (cert-MITM) or `/bili/` prefix — details: [docs/clients.md](docs/clients.md) |
|
||||
| **hermes** | `bili plugin install hermes` (self-spawning native, Python plugin #958) or `bili hermes` (cert-MITM) |
|
||||
| **zcode** (Z.ai / bigmodel coding plan) | `bili plugin install zcode` (self-spawning native, #1145) or cert-MITM via the GUI's Settings → Network or `/bili/` prefix — details: [CLIENTS.md](CLIENTS.md) |
|
||||
| **zcode** (Z.ai / bigmodel coding plan) | `bili plugin install zcode` (self-spawning native, #1145) or cert-MITM via the GUI's Settings → Network or `/bili/` prefix — details: [docs/clients.md](docs/clients.md) |
|
||||
| **claude** | `bili claude` (launcher) or `bili plugin install claude` (native posture, #964 — managed settings block + session-owned proxy; see the notes below) |
|
||||
| **codex** | `bili codex` (launcher — the full zero-config posture) or `bili plugin install codex` (MCP-shell tools companion: **start bili first** — the shell never spawns a proxy and never routes codex's own traffic) — details: [CLIENTS.md](CLIENTS.md#codex-openai-codex-cli) |
|
||||
| **codex** | `bili codex` (launcher — the full zero-config posture) or `bili plugin install codex` (MCP-shell tools companion: **start bili first** — the shell never spawns a proxy and never routes codex's own traffic) — details: [docs/clients.md](docs/clients.md#codex-openai-codex-cli) |
|
||||
| **jcode** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili jcode` (cert-MITM) or `/bili/` prefix — no native mode (compiled Rust binary, no plugin seam, [#962](https://github.com/ranxianglei/billion-context/issues/962)) |
|
||||
| **gemini** (Gemini CLI) | `bili gemini` (launcher, `GOOGLE_GEMINI_BASE_URL` `/bili/` rewrite) or `/bili/` prefix — launcher-only (no in-loop tool seam, #1043) |
|
||||
| **iflow** (iFlow CLI) | `bili iflow` (launcher, `IFLOW_BASE_URL` `/bili/` rewrite) or `/bili/` prefix |
|
||||
| **qwen** (Qwen Code) | `bili qwen` (launcher, cert-MITM) or `/bili/` prefix |
|
||||
| **antigravity** (Antigravity CLI / agy, Google) | `bili antigravity` (launcher, `CLOUD_CODE_URL` `/bili/` rewrite of daily-cloudcode-pa.googleapis.com — Antigravity's real default upstream, #3129) or `/bili/` prefix — no plugin seam (closed Go language_server; its user-plugin surface is additive-only, #2115) — details: [CLIENTS.md](CLIENTS.md) |
|
||||
| **antigravity** (Antigravity CLI / agy, Google) | `bili antigravity` (launcher, `CLOUD_CODE_URL` `/bili/` rewrite of daily-cloudcode-pa.googleapis.com — Antigravity's real default upstream, #3129) or `/bili/` prefix — no plugin seam (closed Go language_server; its user-plugin surface is additive-only, #2115) — details: [docs/clients.md](docs/clients.md) |
|
||||
| **mcode** (MiniMax Code) | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili mcode` (cert-MITM) or `/bili/` prefix — no native mode (event hooks only, no model-request seam, [#1050](https://github.com/ranxianglei/billion-context/issues/1050)) |
|
||||
| **aider** | [`billion-context`](https://github.com/ranxianglei/billion-context) via `bili aider` (cert-MITM) or `/bili/` prefix — no native mode (shell-command-only hooks, no tool-injection seam, [#1048](https://github.com/ranxianglei/billion-context/issues/1048)) |
|
||||
| **copilot** (GitHub Copilot CLI) | `bili copilot` (launcher, cert-MITM) — closed Go binary, no plugin seam (#1049) |
|
||||
| **amp** (Amp CLI) | `bili amp` (launcher, cert-MITM) — closed Go binary, no plugin seam (#1049) |
|
||||
| **kiro** (Kiro CLI, AWS) | `bili kiro` (launcher, cert-MITM) — Rust shell + Node agent server, no plugin seam; model traffic is the Responses wire on `runtime.<region>.kiro.dev`, gateway quirks handled built-in — details: [docs/clients.md](docs/clients.md#kiro-cli-aws) |
|
||||
| **crush** (Charm Crush) | `bili crush` (launcher, cert-MITM) — open-source Go binary, no plugin seam; built-in provider hosts whitelisted, custom `base_url`s auto-discovered from crush.json (#2340) |
|
||||
| **zed** (Zed editor) | `bili zed` (launcher, cert-MITM) — open-source Rust editor, no plugin seam; reqwest honors HTTPS_PROXY, CA via SSL_CERT_FILE (Linux env probing); built-in provider hosts whitelisted, custom `api_url`s auto-discovered from settings.json; loopback providers (ollama/lmstudio) stay direct via NO_PROXY (#2340) |
|
||||
| **goose** (Goose CLI) | `bili goose` (launcher) — rustls trusts no CA file, so no cert-MITM: openai/anthropic legs via `OPENAI_HOST`/`ANTHROPIC_HOST`, custom providers via a regenerated `GOOSE_PATH_ROOT` overlay (#1049) |
|
||||
@@ -166,7 +158,7 @@ Three ways to use it — pick one:
|
||||
origin + `/bili/`.
|
||||
|
||||
Mechanism details behind these three options (plugin lifecycle, runtime-info
|
||||
protocol, injection priority) live in [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md).
|
||||
protocol, injection priority) live in [docs/technical-notes.md](docs/technical-notes.md).
|
||||
|
||||
Ports, briefly (#1660): `bili start` (manual) owns `8787`. Everything a lane
|
||||
spawns for you (native hooks, launcher lanes) lives in a separate
|
||||
@@ -234,16 +226,16 @@ Notes:
|
||||
|
||||
- Native mode is **mutually exclusive** with the standalone in-process extensions (`billion-context-pi`, `opencode-acp`) — the installer swaps the entries and snapshots the original config (`.bili-bak`).
|
||||
- **pi:** native installs wire in built-in subagents by default (`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`) — how to disable them while keeping context compression: [Pi built-in subagents](#pi-built-in-subagents).
|
||||
- OpenCode legacy sessions, V1/V2 shapes and caveats: [OpenCode](CLIENTS.md#opencode).
|
||||
- OpenCode legacy sessions, V1/V2 shapes and caveats: [OpenCode](docs/clients.md#opencode).
|
||||
- `kimi` reports runtime-info at bootstrap only (static headers can't carry per-request window/model values); subagent tool calls are routed by the proxy's outbound tool-use witness ring (#1685) — no model-visible conversation id.
|
||||
- `hermes`'s native plugin is Python: it points hermes' httpx stack at the proxy via env vars after a health check and stamps per-request headers through an `llm_request` middleware.
|
||||
- `codex` is the one client a plugin install cannot make self-sufficient: codex routes model traffic via env only (no config-file routing seam for the default ChatGPT-login provider — a managed `model_providers` block would force API-key auth and drop subscription login), and an MCP server cannot inject env into its parent. `bili plugin install codex` writes a single `[mcp_servers.bili]` block into `~/.codex/config.toml` (command = node, args = dist/mcp.js) exposing the four ACP tools; at session start the shell resolves a proxy — env `BILI_MCP_PROXY` > the live-instance record (any lane's proxy or a `bili start` daemon) > the 8787 user-zone default (#1660 removed the install-time origin bake, #403) — nothing reachable → `tools/list` fails with -32003. So: start bili first (`bili start` or any client's lane proxy), export HTTPS_PROXY yourself if you also want compression, or use `bili codex` for the zero-config full posture. Mechanics: [CLIENTS.md](CLIENTS.md#codex-openai-codex-cli).
|
||||
- `claude` has a native posture (#964): managed settings block + `SessionStart` hook + MCP shell; the hook rides the self-managed port zone (#1660) and re-pins the managed URL to the live origin each session, so port drift self-heals. Since #1821 the MCP shell also watches the proxy mid-session (30 s tick × 3 failures) and respawns a dead lane proxy itself, so model requests recover within ~90 s instead of a new session (same semantics as the zcode lane). Opt out with `BILI_NATIVE_CLAUDE=0` (passthrough). Mechanics: [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md). **Known limitation (#2290):** the Claude Desktop app's Code tab (`CLAUDE_CODE_ENTRYPOINT=claude-desktop`) sets its own `ANTHROPIC_BASE_URL` on its embedded Claude Code, overriding the managed one — desktop sessions bypass the proxy entirely while the managed block's `DISABLE_AUTO_COMPACT=1` still applies, so they get neither bili compression nor native auto-compaction. The hook warns loudly at session start (and records it for `bili doctor`, which also flags machines where Claude Desktop is installed alongside the native lane); terminal sessions are unaffected. **Field-tested 2026-10-06 (#2290):** putting `HTTPS_PROXY` in the settings `env` block produced zero CONNECT traffic to a live MITM-enabled proxy on Claude Desktop 2.19675.1 / embedded CC 2.1.288 (Windows 11) — the variable reaches no network stack there, matching the CLI behavior of that era — note that newer builds (CC 2.1.301+) DO honour `HTTPS_PROXY` on the CLI, which is why `bili claude` routes via the `/bili/` base-URL rewrite — the launcher gives this lane no proxy and no CA at all, and a child that brings a proxy of its own gets the loopback hosts merged into `NO_PROXY`/`no_proxy` so that leg stays direct regardless of its proxy behavior (#3446). As of that version there is no usable routing seam on the desktop Code tab; the lane stays tracked in [#2290](https://github.com/ranxianglei/billion-context/issues/2290) in case upstream changes behavior. Desktop-only users can restore native auto-compact with `bili plugin remove claude`.
|
||||
- `zcode` has a native posture (#1145): managed `~/.zcode/cli/config.json` block + per-session provider `baseURL` rewrite. Full mechanics: [CLIENTS.md](CLIENTS.md).
|
||||
- `codex` is the one client a plugin install cannot make self-sufficient: codex routes model traffic via env only (no config-file routing seam for the default ChatGPT-login provider — a managed `model_providers` block would force API-key auth and drop subscription login), and an MCP server cannot inject env into its parent. `bili plugin install codex` writes a single `[mcp_servers.bili]` block into `~/.codex/config.toml` (command = node, args = dist/mcp.js) exposing the four ACP tools; at session start the shell resolves a proxy — env `BILI_MCP_PROXY` > the live-instance record (any lane's proxy or a `bili start` daemon) > the 8787 user-zone default (#1660 removed the install-time origin bake, #403) — nothing reachable → `tools/list` fails with -32003. So: start bili first (`bili start` or any client's lane proxy), export HTTPS_PROXY yourself if you also want compression, or use `bili codex` for the zero-config full posture. Mechanics: [docs/clients.md](docs/clients.md#codex-openai-codex-cli).
|
||||
- `claude` has a native posture (#964): managed settings block + `SessionStart` hook + MCP shell; the hook rides the self-managed port zone (#1660) and re-pins the managed URL to the live origin each session, so port drift self-heals. Since #1821 the MCP shell also watches the proxy mid-session (30 s tick × 3 failures) and respawns a dead lane proxy itself, so model requests recover within ~90 s instead of a new session (same semantics as the zcode lane). Opt out with `BILI_NATIVE_CLAUDE=0` (passthrough). Mechanics: [docs/technical-notes.md](docs/technical-notes.md). **Known limitation (#2290):** the Claude Desktop app's Code tab (`CLAUDE_CODE_ENTRYPOINT=claude-desktop`) sets its own `ANTHROPIC_BASE_URL` on its embedded Claude Code, overriding the managed one — desktop sessions bypass the proxy entirely while the managed block's `DISABLE_AUTO_COMPACT=1` still applies, so they get neither bili compression nor native auto-compaction. The hook warns loudly at session start (and records it for `bili doctor`, which also flags machines where Claude Desktop is installed alongside the native lane); terminal sessions are unaffected. **Field-tested 2026-10-06 (#2290):** putting `HTTPS_PROXY` in the settings `env` block produced zero CONNECT traffic to a live MITM-enabled proxy on Claude Desktop 2.19675.1 / embedded CC 2.1.288 (Windows 11) — the variable reaches no network stack there, matching the CLI behavior of that era — note that newer builds (CC 2.1.301+) DO honour `HTTPS_PROXY` on the CLI, which is why `bili claude` routes via the `/bili/` base-URL rewrite — the launcher gives this lane no proxy and no CA at all, and a child that brings a proxy of its own gets the loopback hosts merged into `NO_PROXY`/`no_proxy` so that leg stays direct regardless of its proxy behavior (#3446). As of that version there is no usable routing seam on the desktop Code tab; the lane stays tracked in [#2290](https://github.com/ranxianglei/billion-context/issues/2290) in case upstream changes behavior. **Account-bound features (#4693):** because the lane routes via a custom `ANTHROPIC_BASE_URL`, Claude Code treats the session as third-party/API-key and disables features bound to your Anthropic account/Cloud — **Remote Control** (`/remote-control`, driving a local session from mobile/desktop/web) disappears from the command list while bili routes traffic. Compression is unaffected; run plain `claude` without bili (or `bili plugin remove claude`) for sessions that need those features. This is inherent to the base-URL routing seam — no alternative interception point survives CC's undici stack (#2290) — not a config deletion. Desktop-only users can restore native auto-compact with `bili plugin remove claude`. Since #5095 the managed block also installs a `SubagentStart` hook (`node <root>/dist/claude-subagent-hook.js`) that mints a per-dispatch lane token into each subagent's context: subagents that ride the parent's session id with no agent-id headers (the VS Code extension build, #4352) key onto their own `<id>|sub:…:t:<token>` compression lanes, so parallel same-type dispatches stop merging (and the token disappears from later requests once the first message folds — those fall back to the fingerprint lane). Uninstall removes the hook with the managed block.
|
||||
- `zcode` has a native posture (#1145): managed `~/.zcode/cli/config.json` block + per-session provider `baseURL` rewrite. Full mechanics: [docs/clients.md](docs/clients.md).
|
||||
- `jcode` and `aider` have no native mode (no plugin/MCP/tool-injection seam: #962, #1048) — use `bili jcode` / `bili aider`.
|
||||
- `copilot`, `amp` and `goose` are launcher-only (#1049); goose cannot be cert-MITMed (rustls trusts no CA file) and rides plain-HTTP base-URL redirects instead.
|
||||
|
||||
### Option 2 — Launcher (`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi` / `bili gemini` / `bili iflow` / `bili qwen` / `bili antigravity` / `bili mcode` / `bili aider` / `bili copilot` / `bili amp` / `bili goose`)
|
||||
### Option 2 — Launcher (`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi` / `bili gemini` / `bili iflow` / `bili qwen` / `bili antigravity` / `bili mcode` / `bili aider` / `bili copilot` / `bili amp` / `bili goose` / `bili kiro`)
|
||||
|
||||
The launcher wraps a client in one command: it starts a proxy on an
|
||||
independent port (a fresh instance is always spawned — a port is never
|
||||
@@ -259,11 +251,11 @@ bili pi # launch pi through the proxy — file-fre
|
||||
bili codex # launch codex through the proxy
|
||||
bili claude # launch claude through the proxy
|
||||
bili omp # pi-style, file-free (#535): env + extension registerProvider + compaction cancel, real ~/.omp untouched
|
||||
bili opencode # OpenCode (1.x & 2.x): full guide in the [OpenCode](CLIENTS.md#opencode) section below
|
||||
bili opencode # OpenCode (1.x & 2.x): full guide in the [OpenCode](docs/clients.md#opencode) section below
|
||||
bili hermes # file-free (#535): hermes proxy env (HTTPS_PROXY + combined CA bundle via SSL_CERT_FILE) — https via CONNECT MITM, http via absolute-form forward proxy; real ~/.hermes untouched
|
||||
bili dsh # deepseek-harness: full native plugin injected via --patch (#941) — real dsh tools, session-bound /acp + /acp-cache (plugin mode); non-loopback upstreams ride proxy envs, loopback keeps the overlay DSH_HOME rewrite (#535); dsh auto-compaction off everywhere — host plane via the bundle patch, web-profile presets at load time (#1772/#2474/#3354)
|
||||
bili codebuddy # Tencent CodeBuddy Code CLI: CODEBUDDY_BASE_URL /bili/ rewrite (OpenAI chat completions wire), budget aligned via CODEBUDDY_AUTO_COMPACT_WINDOW; real ~/.codebuddy untouched
|
||||
bili qoder # qoder: model endpoint is hardcoded https (no /bili/ rewrite possible) — cert-MITM via HTTPS_PROXY + NODE_EXTRA_CA_CERTS, default model hosts whitelisted (#653)
|
||||
bili qoder # qoder CLI (`qoder`/`qodercli`): model endpoint is hardcoded https (no /bili/ rewrite possible) — cert-MITM via HTTPS_PROXY + NODE_EXTRA_CA_CERTS, default model hosts whitelisted (#653). Qoder Desktop is a separate BYOK/custom channel that speaks plaintext OpenAI over a `/bili/` prefix — point it at bili as a normal custom provider (not this MITM lane); its official-subscription traffic is encrypted and out of scope (#764)
|
||||
bili trae # Trae CLI (ByteDance, closed Go binary, no base-URL override) — cert-MITM via HTTPS_PROXY + SSL_CERT_FILE, model host from TRAE_CLI_API_HOST or the default enterprise gateway (#655)
|
||||
bili jcode # jcode (Rust agent harness) — env-only cert-MITM launch: HTTPS_PROXY + SSL_CERT_FILE, model host api.z.ai whitelisted, local loopback providers stay direct via NO_PROXY
|
||||
bili kimi # Kimi Code CLI (Moonshot): standard proxy envs except an unconditional loopback bypass — https via cert-MITM, http via absolute-form forward proxy; loopback endpoints inventoried with a manual /bili/ hint (#757)
|
||||
@@ -276,6 +268,7 @@ bili aider # Aider (Python pair programmer): cert-MIT
|
||||
bili copilot # Copilot CLI (GitHub, closed Go binary) — cert-MITM via HTTPS_PROXY + SSL_CERT_FILE, api.githubcopilot.com + per-plan subdomains whitelisted (#1049)
|
||||
bili amp # Amp CLI (Sourcegraph, closed Go binary) — cert-MITM via HTTPS_PROXY + SSL_CERT_FILE, ampcode.com whitelisted (#1049)
|
||||
bili goose # Goose (Block, Rust/reqwest): rustls release builds trust no CA file — openai/anthropic legs via OPENAI_HOST/ANTHROPIC_HOST, custom providers via a regenerated GOOSE_PATH_ROOT overlay (/bili/ rewrites, real config untouched) (#1049)
|
||||
bili kiro # Kiro CLI (AWS): cert-MITM via HTTPS_PROXY + combined CA on SSL_CERT_FILE and NODE_EXTRA_CA_CERTS; only runtime.<region>.kiro.dev is decrypted; developer/system items re-voiced as user for the gateway; session = Kiro's conversation id (survives --resume)
|
||||
bili pi --mitm-domain api.foo.com # add a domain to the MITM whitelist
|
||||
```
|
||||
|
||||
@@ -317,7 +310,7 @@ should see a `processTurn` line per request, and once the conversation grows,
|
||||
|
||||
### Client deep dives
|
||||
|
||||
Everything that doesn't fit in one Quickstart line — how each client's lanes attach, what gets written where, and known limitations — lives in **[CLIENTS.md](CLIENTS.md)**: dsh · Kimi Code · Hermes · ZCode · Gemini family (Gemini CLI / iFlow CLI / Qwen Code / Antigravity) · cert-MITM clients that never compress (CONNECT blind tunnels, #897) · unrecognized endpoints going direct (#1290) · OpenCode (launcher / native / pure proxy, `/acp` status & rules, legacy opencode-acp sessions #920).
|
||||
Everything that doesn't fit in one Quickstart line — how each client's lanes attach, what gets written where, and known limitations — lives in **[docs/clients.md](docs/clients.md)**: dsh · Kimi Code · Hermes · ZCode · Gemini family (Gemini CLI / iFlow CLI / Qwen Code / Antigravity) · cert-MITM clients that never compress (CONNECT blind tunnels, #897) · unrecognized endpoints going direct (#1290) · OpenCode (launcher / native / pure proxy, `/acp` status & rules, legacy opencode-acp sessions #920).
|
||||
|
||||
## From source (development)
|
||||
|
||||
@@ -378,8 +371,11 @@ report above.
|
||||
**Can I query sessions and config over the web?** Yes — open
|
||||
[http://localhost:8787](http://localhost:8787): an overview dashboard, session
|
||||
list with per-session detail, live logs, a config editor, and an upstream
|
||||
connectivity test. Everything is also plain JSON for scripting
|
||||
(`/__bili/stats`, `/__bili/sessions`, `/__bili/config`, …).
|
||||
connectivity test. A Blog view renders notes and long-form articles inside the
|
||||
panel itself — bundled with the install, refreshed from GitHub master on a
|
||||
~1-hour throttle while online (fail-soft to the bundled copy when offline);
|
||||
the full library also lives on GitHub Pages. Everything else is also plain JSON
|
||||
for scripting (`/__bili/stats`, `/__bili/sessions`, `/__bili/config`, …).
|
||||
|
||||
**When does compression happen?** It is model-driven: the injected context
|
||||
tools are called by the model as context grows, gentle growth nudges
|
||||
@@ -387,6 +383,19 @@ tools are called by the model as context grows, gentle growth nudges
|
||||
prompt it along the way, and preflight fires as a hard backstop when the input
|
||||
alone exceeds the window (#470). Watch it live with `/acp` or the web UI.
|
||||
|
||||
**Does compression shrink my client's own conversation file?** No — the most
|
||||
common surprise in very long sessions (#5796). Compression shrinks **what is
|
||||
sent to the model**: every outgoing request is rebuilt from live blocks plus
|
||||
summaries, so the wire stays small however long the conversation runs. The
|
||||
client's stored history is user data — bili never rewrites it. On dsh the
|
||||
host's auto-compaction is additionally disabled while bili is active (two
|
||||
compressors must not fight over one history, #1772/#2474/#3354), so the
|
||||
host-side file grows with every turn: each turn takes longer as it grows
|
||||
(measured: tens of seconds per turn at ~30K messages, #5796), and the
|
||||
practical convergence path is to **start a new session** when it gets heavy.
|
||||
The web session list badges sessions at 5,000+ requests (长会话/slow) as a
|
||||
reminder that this point has been reached.
|
||||
|
||||
**Why does the first compaction wait until ~200k?** Compaction does not
|
||||
trigger on absolute window position but on growth intervals: by default the
|
||||
first soft compaction fires 50k tokens past the boot content
|
||||
@@ -395,10 +404,10 @@ first soft compaction fires 50k tokens past the boot content
|
||||
until ~200k. To make it fire earlier: 1) trim the system prompt, disable
|
||||
unneeded tools, prune skills; 2) lower `compress.nudgeGrowthTokens` to ~50k;
|
||||
3) enable lean mode. Worked example in
|
||||
[CONFIGURATION.md](CONFIGURATION.md#why-the-first-compaction-waits-until-200k).
|
||||
[docs/configuration.md](docs/configuration.md#why-the-first-compaction-waits-until-200k).
|
||||
|
||||
**Is bili transparent? How do I turn it off?** Unrecognized endpoints forward
|
||||
unchanged ([CLIENTS.md](CLIENTS.md)), and every mode reverses cleanly:
|
||||
unchanged ([docs/clients.md](docs/clients.md)), and every mode reverses cleanly:
|
||||
`bili plugin remove <client>` for native installs, stop using the launcher
|
||||
command / env vars / `/bili/` prefix for the other two — traffic goes direct
|
||||
again immediately.
|
||||
@@ -422,14 +431,21 @@ declare their context windows under the providers key
|
||||
fallback window (route-miss warning, #2317); ③ if the relay rejects bili's
|
||||
Anthropic-lane `cache_control` stamps, set `compat.noCacheControl`; ④ loopback
|
||||
gateways work out of the box; a gateway on a private non-loopback address may
|
||||
additionally need `network.allowPrivateHttpProviders` (#2984). Verified
|
||||
end-to-end over all three wires (OpenAI Chat / Responses / Anthropic Messages,
|
||||
including cross-protocol conversion), #4433.
|
||||
additionally need `network.allowPrivateHttpProviders` (#2984); ⑤ for Claude Code
|
||||
native plugin mode (`bili plugin install claude`), set
|
||||
`BILI_CLAUDE_UPSTREAM=http://127.0.0.1:3425` before install so the managed block
|
||||
wraps the relay into `ANTHROPIC_BASE_URL` (or configure
|
||||
`ANTHROPIC_BASE_URL=http://127.0.0.1:8787/bili/http://127.0.0.1:3425` directly;
|
||||
`localhost` and `127.0.0.1` both accepted, #5369). Verified end-to-end over all
|
||||
three wires (OpenAI Chat / Responses / Anthropic Messages, including
|
||||
cross-protocol conversion), #4433.
|
||||
|
||||
**Does this work with [opencodex](https://github.com/lidge-jun/opencodex) (`ocx`) — the local Codex/Claude Code gateway with a ChatGPT account pool?** Same pattern: point the client at bili, and point bili at ocx through the `/bili/` prefix — OpenAI-style clients (chat completions and Responses, e.g. Codex) → `OPENAI_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:10100/v1`; Anthropic-style clients → `ANTHROPIC_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:10100`. A dummy key value satisfies clients that require one; it rides through untouched. Keep bili *in front of* ocx rather than behind it: ocx owns the provider credentials and the account pool at its final hop, so only this order keeps compression and pooling working together. Loopback needs no key between the two (ocx's default loopback bind reads no token); a non-loopback bind takes `OPENCODEX_API_AUTH_TOKEN` plus the `x-opencodex-api-key` header per its docs. Request models by ocx's `provider/model` id so routing is deterministic; as with any gateway, routed ids are opaque to bili's window lookup (declare them via `models.<name>.context`) and a mid-session account rebind invalidates the prefix cache (watch `KEY SWITCHES` in `/acp-cache`). Verified end-to-end over all three wires (OpenAI Chat / Responses / Anthropic Messages), bili 0.1.212 × ocx 2.97.0.
|
||||
|
||||
**Where are logs and session data stored?** Log:
|
||||
`~/.local/state/billion-context/bili.log` (also mirrored to stderr); session
|
||||
state: `~/.local/share/billion-context/` (XDG-overridable; Windows AV exclusion
|
||||
#362, opt-in cleanup #1082) — full paths in [CONFIGURATION.md](CONFIGURATION.md).
|
||||
#362, opt-in cleanup #1082) — full paths in [docs/configuration.md](docs/configuration.md).
|
||||
|
||||
## Running the proxy
|
||||
|
||||
@@ -493,13 +509,13 @@ All logs tee to `~/.local/state/billion-context/bili.log` by default (XDG state
|
||||
|
||||
### Connection lifecycle tuning (#1982)
|
||||
|
||||
Client-facing connections close gracefully after the final response: when the proxy initiates the close (`Connection: close`), it waits up to `BILI_POST_RESPONSE_LINGER_MS` (default `5000`) for the client's close signal before releasing the socket, so pooled clients see a clean EOF instead of a possible RST from racing bytes. Related knobs: `BILI_KEEP_ALIVE_TIMEOUT_MS` (idle-reap budget, default `5000`) and `BILI_CLIENT_ERROR_BACKSTOP_MS` (terminal backstop for the error-drain path, default `30000`) — full semantics in [CONFIGURATION.md](CONFIGURATION.md#environment-variables).
|
||||
Client-facing connections close gracefully after the final response: when the proxy initiates the close (`Connection: close`), it waits up to `BILI_POST_RESPONSE_LINGER_MS` (default `5000`) for the client's close signal before releasing the socket, so pooled clients see a clean EOF instead of a possible RST from racing bytes. Related knobs: `BILI_KEEP_ALIVE_TIMEOUT_MS` (idle-reap budget, default `5000`) and `BILI_CLIENT_ERROR_BACKSTOP_MS` (terminal backstop for the error-drain path, default `30000`) — full semantics in [docs/configuration.md](docs/configuration.md#environment-variables).
|
||||
|
||||
### Self-update
|
||||
|
||||
The proxy checks npm on startup and every 3 minutes; a newer version is installed in place and a notice is logged — **restart `bili` to pick it up**, unless you enable opt-in self-restart (`--auto-restart-on-update` flag, env `ACP_AUTO_RESTART_ON_UPDATE=1`, or `"autoRestartOnUpdate": true` in config — default OFF): with zero in-flight requests it verifies the new install, stops accepting connections, drains, spawns a replacement on the same port, and exits once it accepts connections (clients reconnect automatically; session state survives on disk). Safety gates: zero in-flight through the drain window, an install sanity check before re-exec, and a 10-minute cooldown marker so a flapping version can never loop-restart; any failure resumes the original listener and falls back to the plain reminder.
|
||||
|
||||
**Staggered rollout (#3619):** a discovered version is not applied immediately by automatic updates. Each instance draws ONE random moment inside a delay window (built-in default **15 min – 48 h**) and upgrades when it arrives; the drawn moment is persisted, so restarts never re-roll. Fleet upgrades therefore spread across the window instead of completing within minutes of a release, leaving time to catch a bad release mid-rollout (#3401/#3600/#3394). The window plus emergency controls live in a public policy file (`auto-update-policy.json` in this repo, fetched anonymously with ETag caching): `hold` freezes automatic upgrades fleet-wide, `blocked` skips listed versions, `pinned` sets an upgrade ceiling. Fail-open by design — an unreachable or malformed file simply falls back to local defaults, and the file can steer timing/skip/pin only, never what gets installed. Per-machine exits: manual `bili update` bypasses `hold`/stagger (still respects `blocked`/`pinned`), `"staggerMinDelayMs": 0` + `"staggerMaxDelayMs": 0` (or `BILI_UPDATE_STAGGER_MIN_MS`/`BILI_UPDATE_STAGGER_MAX_MS`) restore legacy immediate upgrades, and `ACP_AUTO_UPDATE=0` disables auto-updates entirely. Full format and semantics: [CONFIGURATION.md → `update`](CONFIGURATION.md#update).
|
||||
**Staggered rollout (#3619):** a discovered version is not applied immediately by automatic updates. Each instance draws ONE random moment inside a delay window (built-in default **15 min – 48 h**) and upgrades when it arrives; the drawn moment is persisted, so restarts never re-roll. Fleet upgrades therefore spread across the window instead of completing within minutes of a release, leaving time to catch a bad release mid-rollout (#3401/#3600/#3394). The window plus emergency controls live in a public policy file (`auto-update-policy.json` in this repo, fetched anonymously with ETag caching): `hold` freezes automatic upgrades fleet-wide, `blocked` skips listed versions, `pinned` sets an upgrade ceiling. Fail-open by design — an unreachable or malformed file simply falls back to local defaults, and the file can steer timing/skip/pin only, never what gets installed. Per-machine exits: manual `bili update` bypasses `hold`/stagger (still respects `blocked`/`pinned`), `"staggerMinDelayMs": 0` + `"staggerMaxDelayMs": 0` (or `BILI_UPDATE_STAGGER_MIN_MS`/`BILI_UPDATE_STAGGER_MAX_MS`) restore legacy immediate upgrades, and `ACP_AUTO_UPDATE=0` disables auto-updates entirely. Full format and semantics: [docs/configuration.md → `update`](docs/configuration.md#update).
|
||||
|
||||
While the running process is behind the on-disk install ("stale"), the web UI shows a banner (running vs installed version, auto-restart state) and `GET /__bili/status` returns `{version, diskVersion, stale, autoRestartOnUpdate, advisory, updatePolicy, inFlight}` for scripting (`advisory` is the active critical-defect entry or `null`, see below; `updatePolicy` reports the #3619 rollout state — policy source, `hold`/`pinned`/`blocked`, and the pending staggered upgrade with its due time). Disable permanently via `"autoUpdate": false` in config or `ACP_AUTO_UPDATE=0`.
|
||||
|
||||
@@ -511,15 +527,23 @@ When an install keeps failing (unwritable or host-managed dir, network error,
|
||||
|
||||
The same bounded retry now covers the **owner-managed lanes** the global self-update drives instead of writing the copy itself — the dsh desktop in-place copy, the dsh profile bundles, and pi's npm copy (#2192). Each lane keeps its own failure streak keyed by lane + target version, so a persistently broken desktop layout no longer re-downloads the full tarball every cycle (up to ~480 downloads/day per affected machine before the fix); three strikes arms the same exponential cooldown, and the one-time hint names the failing lane and its manual fix (`dsh plugin --profile <name> add …`, `pi update --extension …`, or recreate the desktop profile). Host-managed instances additionally check on their own slower cadence — 30 minutes plus up to 15 minutes of jitter, tracked under a separate throttle marker — instead of consuming the global 3-minute budget. Failure streaks are shared across every bili process on the machine through a small state file in the cache dir (`.install-backoff.json`), so several running instances don't each burn their own retry budget; a clean `bili plugin update` disarms the dsh profile lane immediately. The file is written atomically (tmp+rename) and every writer merges with what is already on disk, so concurrent instances cooperate instead of overwriting each other's streaks; long-lived processes re-read it when it changes, so a manual disarm by one copy is visible to the others on their next check. It is fail-safe in the retry direction — a corrupt file or jumped clock is dropped, never allowed to silence a lane for long. `bili plugin update` clears the dsh-profile lane's key; a repaired desktop lane clears its own key on its next successful in-place refresh.
|
||||
|
||||
### Stale local DNS after a network/VPN change (#5224)
|
||||
|
||||
A **long-lived** standalone proxy can keep holding stale OS-resolver state after a WSL/VPN/TUN topology change — the process caches its system resolver and libuv's `getaddrinfo` does not re-read `/etc/resolv.conf` on its own. Symptom: every model request through the `/bili/` tunnel answers HTTP 502 `tunnel_destination_denied` with detail `unresolvable`, even though a freshly started `bili` resolves the same host fine at that moment and `curl` from a new shell works. Either remedy clears it:
|
||||
- **Restart the proxy process** — a fresh process re-reads the system resolver. In the launcher lanes and the dsh web-profile lane the proxy is a *separate registered* process (the instance registry), so restarting only the client/host re-adopts the same wedged proxy and does **not** help — you must stop and relaunch the proxy itself. (In embedded plugin mode the proxy runs inside the host, so restarting the host *does* clear it.)
|
||||
- **Route egress through an upstream proxy** — `-F http://<host:port>` or `BILI_UPSTREAM_PROXY=… BILI_UPSTREAM_PROXY_MODE=auto`: the destination is then resolved remotely by that proxy, so bili never consults its own (stale) resolver for admission.
|
||||
|
||||
### Critical-defect advisories (forced updates)
|
||||
|
||||
Independent of auto-update (#1481): even with `autoUpdate` off, the proxy polls a small companion npm package (`billion-context-advisories`, published by CI from this repo's [`advisories/`](advisories/) directory) on the same 3-minute cadence. Each advisory names a semver range of broken versions (`affected`), the exact version to install (`target` — which may be *older* than the current one, i.e. a rollback), and a user-facing `reason`. When the local version falls inside `affected`, bili force-installs `target` through the self-updater's full safety chain (cross-process lock, backup + verify + rollback; source checkouts and host-managed installs are refused with manual instructions instead) and warns prominently: a one-time `[advisory] ⚠️ …` log line per process per advisory id, a banner on the web UI showing the reason and the exact manual upgrade command, and the active entry under `advisory` in `/__bili/status`. The check is fail-open by design: an unreachable or malformed advisory source only produces a warning — model traffic is never blocked by it. Disable via config (`"advisoryCheck": false`) or env (`BILI_ADVISORY_CHECK=0`); point at a custom document with `"advisoryUrl"` / `BILI_ADVISORY_URL`.
|
||||
|
||||
**Announcements** (#5548) — distinct from the defect advisory above, three sources feed the web-UI banners, and equal ids shadow in the order **local file > remote feed > built-in**: (1) *built-in* one-time notices rendered from the UI i18n strings; (2) *local* — drop JSON files into `<config dir>/announcements/*.json` (`~/.config/billion-context/announcements/` by default) and they render automatically: bilingual records with kind-derived color, npm-style `versions` targeting (`>=a.b.c`, `^`, `~`, `[lo hi]`, `||` lists), `percent` grey rollout, time windows, and per-kind priority — one bad file disables only itself; (3) *remote* — this repo's master branch [`announcements/remote.json`](announcements/remote.json) (CI-linted on every PR), fetched on the ~3-minute watcher cadence, whose last-known-good snapshot survives restarts and outages while malformed pushes are rejected; unreachable installs (firewalls) point `"remoteAnnouncementsUrl"` / `BILI_ANNOUNCEMENTS_URL` at a relay mirror of the same document. Dismissal follows each record's declared mode: `persistent` (default, content-addressed — editing a notice shows it again), `instance` (this process run only), or `always` (renders without a close button). Dismissing a built-in intro notice is recorded per install in bili's unified storage (SQLite by default; the MySQL backend works too), so it survives restarts — the old `upgrade-notices.json` state file remains only as fallback on legacy-only installs without a unified sidecar. The official feed currently ships an empty entry list.
|
||||
|
||||
## Configuration
|
||||
|
||||
The full configuration reference — config file location, top-level keys,
|
||||
providers, compression tuning, environment variables — lives in
|
||||
**[CONFIGURATION.md](CONFIGURATION.md)**.
|
||||
**[docs/configuration.md](docs/configuration.md)**.
|
||||
|
||||
### Config file
|
||||
|
||||
@@ -527,7 +551,7 @@ One JSON document at `~/.config/billion-context/billion-context.json`
|
||||
(`$XDG_CONFIG_HOME/billion-context/`; override the path with `BILI_CONFIG_FILE`).
|
||||
Precedence when several sources set the same knob: **CLI flag (where one exists) > env var > config file > built-in default** — every env var keeps working as the override tier.
|
||||
|
||||
What's inside (details in CONFIGURATION.md):
|
||||
What's inside (details in docs/configuration.md):
|
||||
|
||||
- `providers` — per-provider routing table: upstream override, model context windows, per-provider/model compress tuning, wire-protocol declaration, compaction opt-in.
|
||||
- `compress` — three-level compression tuning (global → provider → model): thresholds, nudge cadence, preservation rules, prompts, tiers.
|
||||
@@ -545,15 +569,15 @@ Minimal example:
|
||||
|
||||
Knobs people look for first:
|
||||
|
||||
- **Upstream proxy (firewall/GFW)** — routing the proxy's own outbound traffic through v2rayA/clash: full resolution order, empty-string = explicit direct, SOCKS5 rejection, both egress paths, and the `mitm://` vs `https://` key schemes live in [CONFIGURATION.md](CONFIGURATION.md) (Server Settings → `proxy`; Providers → key schemes).
|
||||
- **Wire-compat role rewrite (`compat.roles`)** — an upstream that rejects the `developer` role? Covered by [CONFIGURATION.md](CONFIGURATION.md) (Server Settings → `compat`) — including the learn-on-failure auto-fix that needs no configuration at all.
|
||||
- **Signed upstreams (body-covering signatures)** — a gateway whose requests carry a body-covering signature (CodeArts APIG's `SDK-HMAC-SHA256`, or gateway-invented headers like `x-ofm-signature`): the built-in scheme re-signs transparently on dsh; every other detected scheme is ALWAYS refused locally — signed requests are either re-signed+compressed or refused, never passed through unsigned — and bili keeps reminding at startup and in the web UI until it ships the scheme's re-signer (#1884/#2090). Detection rules, per-scheme overrides, and `BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_CODEARTS_REF` live in [CONFIGURATION.md](CONFIGURATION.md) (Server Settings → `resign`).
|
||||
- **Upstream proxy (firewall/GFW)** — routing the proxy's own outbound traffic through v2rayA/clash: full resolution order, empty-string = explicit direct, SOCKS5 rejection, both egress paths, and the `mitm://` vs `https://` key schemes live in [docs/configuration.md](docs/configuration.md) (Server Settings → `proxy`; Providers → key schemes).
|
||||
- **Wire-compat role rewrite (`compat.roles`)** — an upstream that rejects the `developer` role? Covered by [docs/configuration.md](docs/configuration.md) (Server Settings → `compat`) — including the learn-on-failure auto-fix that needs no configuration at all.
|
||||
- **Signed upstreams (body-covering signatures)** — a gateway whose requests carry a body-covering signature (CodeArts APIG's `SDK-HMAC-SHA256`, or gateway-invented headers like `x-ofm-signature`): the built-in scheme re-signs transparently on dsh; every other detected scheme is ALWAYS refused locally — signed requests are either re-signed+compressed or refused, never passed through unsigned — and bili keeps reminding at startup and in the web UI until it ships the scheme's re-signer (#1884/#2090). Detection rules, per-scheme overrides, and `BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_CODEARTS_REF` live in [docs/configuration.md](docs/configuration.md) (Server Settings → `resign`).
|
||||
|
||||
### Pi built-in subagents
|
||||
|
||||
Using `bili pi` or the native pi plugin (`bili plugin install pi`) includes built-in subagent support, enabled by default: `acp_delegate`, `acp_delegate_wait`, and `acp_delegate_cancel`. This additional tool surface is specific to pi.
|
||||
|
||||
**Keep only one subagent implementation enabled.** If you use the built-in support, remove or disable other pi subagent plugins (for example, `pi-subagents` or a separately installed `billion-context-pi-subagents`) in both user and project settings to avoid overlapping tools, prompts, or behavior. If you prefer another subagent plugin, disable the built-in support instead. A project-scope `pi-subagents` install makes the built-in delegate stand down by default, but a user-scope-only install does not; do not rely on that guard for every installation.
|
||||
**Keep only one subagent implementation enabled.** If you use the built-in support, remove or disable other pi subagent plugins (for example, `pi-subagents` or a separately installed `billion-context-pi-subagents`) in both user and project settings to avoid overlapping tools, prompts, or behavior. If you prefer another subagent plugin, disable the built-in support instead. A `pi-subagents` install at either scope (project or user) makes the built-in delegate stand down automatically by default — a user-scope install loads in every project, so the guard applies there too (#5637); set `delegate.forceEnable` to keep `acp_delegate` alongside it.
|
||||
|
||||
To disable the built-in subagents while keeping context compression, merge this into `~/.config/billion-context/billion-context.json` (or the file selected by `BILI_CONFIG_FILE`), preserving your other settings:
|
||||
|
||||
@@ -565,7 +589,7 @@ To disable the built-in subagents while keeping context compression, merge this
|
||||
}
|
||||
```
|
||||
|
||||
Restart pi and start a new session for the change to take effect. This disables the three delegate tools, their system-prompt section, and the fleet keyboard shortcut; context compression remains enabled. It does not disable independently installed subagent plugins. More options: [subagent configuration](CONFIGURATION.md#pi).
|
||||
Restart pi and start a new session for the change to take effect. This disables the three delegate tools, their system-prompt section, and the fleet keyboard shortcut; context compression remains enabled. It does not disable independently installed subagent plugins. More options: [subagent configuration](docs/configuration.md#pi).
|
||||
|
||||
## How sessions work
|
||||
|
||||
@@ -590,13 +614,15 @@ Responses/OpenAI/Anthropic wires.
|
||||
| **omp** (via plugin) | ✅ yes | `prompt_cache_key` promoted over any fingerprint (#268) |
|
||||
| **pi** (bare) | ❌ no | nothing → anonymous prefix affinity below |
|
||||
|
||||
**omp caveat (#2583/#3556):** on recent OMP builds, default Anthropic (`anthropic-messages`) requests leave the host through OMP's Cowork transport over node:https directly — they never reach bili's fetch layer, so the `prompt_cache_key` stamp is *withheld* there (stamping would leak the field into Anthropic's strict schema → HTTP 400). Since #3556 the `bili omp` launcher lane no longer leaves that hole open by default: unless you set `PI_PROXY` / `PI_PROXY_ANTHROPIC` yourself, the launcher exports `PI_PROXY_ANTHROPIC=<proxy>`, which pushes Cowork onto Bun's fetch and routes it through the proxy like every other lane (compressed and session-visible; the stamped key is consumed and stripped by the proxy). Direct-and-anonymous remains only for native omp mode and for launcher lanes where you pin your own proxy posture; all other omp traffic keeps its stamped identity. Details: [TECHNICAL-NOTES.md](TECHNICAL-NOTES.md).
|
||||
**omp caveat (#2583/#3556):** on recent OMP builds, default Anthropic (`anthropic-messages`) requests leave the host through OMP's Cowork transport over node:https directly — they never reach bili's fetch layer, so the `prompt_cache_key` stamp is *withheld* there (stamping would leak the field into Anthropic's strict schema → HTTP 400). Since #3556 the `bili omp` launcher lane no longer leaves that hole open by default: unless you set `PI_PROXY` / `PI_PROXY_ANTHROPIC` yourself, the launcher exports `PI_PROXY_ANTHROPIC=<proxy>`, which pushes Cowork onto Bun's fetch and routes it through the proxy like every other lane (compressed and session-visible; the stamped key is consumed and stripped by the proxy). Direct-and-anonymous remains only for native omp mode and for launcher lanes where you pin your own proxy posture; all other omp traffic keeps its stamped identity. Details: [docs/technical-notes.md](docs/technical-notes.md).
|
||||
|
||||
**omp advisor isolation (#5567):** omp's persistent background streams (e.g. a turn-reviewer *advisor* on a second model) are separate model conversations, but their Chat Completions requests carry no conversation signal of their own — the plugin stamps the main session's id into `prompt_cache_key`, so both streams land in ONE bili session. Two models/protocols interleaving into one ledger corrupts it: refs go DEAD (`cannot be anchored` / `content-changed`), fold coverage drifts, and usage/window/nudge metering cross-talks between the streams (the log line `foreign payload under a shared session id (#4805)` marks where the proxy noticed). Until the host-side identity fix lands (tracked in [#5567](https://github.com/ranxianglei/billion-context/issues/5567)), isolate the advisor by letting it carry its own identity on the wire: in omp's model-registry config (the `providers:` section of `models.yml`), set `compat.supportsPromptCacheKey: true` on the advisor's provider entry — pi-ai then serializes the advisor's own session UUID as `prompt_cache_key`, and bili binds it to its own session. Boundaries: this does not help if omp explicitly passes a shared cache key for the advisor; once isolated, the advisor runs as its own session with its own compression state; verify via the web panel that advisor traffic appears under a separate session id.
|
||||
|
||||
**Header-less clients (pi-like): anonymous prefix affinity.** With no conversation signal at all, the proxy resolves the session from the replayed history itself (`src/prefix-affinity.ts`, #309): a request reattaches to a stored session only when its history reproduces that session's message chain byte-exactly from position 0; otherwise it gets its own deterministic `pfa-…` session. Consequences (#1262): a **resumed** conversation reattaches to its own session (even after a proxy restart, #499); a **new task with an identical opener does NOT inherit** another conversation's blocks — it mints a fresh, fully separate session; a request with no usable signal at all gets an explicit 400 instead of silently colliding.
|
||||
|
||||
Design record and threat model: [SESSION-IDENTITY.md](SESSION-IDENTITY.md). The
|
||||
Design record and threat model: [docs/session-identity.md](docs/session-identity.md). The
|
||||
message-granularity sibling (why identity is content-derived, not an
|
||||
assigned id) is [MESSAGE-IDENTITY.md](MESSAGE-IDENTITY.md).
|
||||
assigned id) is [docs/message-identity.md](docs/message-identity.md).
|
||||
|
||||
For upstream sticky-routing, the proxy forwards only identity values the
|
||||
client already supplied (e.g. a body `session_id` is forwarded upstream as
|
||||
@@ -606,7 +632,7 @@ client already supplied (e.g. a body `session_id` is forwarded upstream as
|
||||
|
||||
### Derived (child) sessions inherit the parent's compressed context (#1333, #1362)
|
||||
|
||||
A child session (subagent/fork starting from an empty history) reports its lineage at birth — its identity registration carries `parentConversationId` and the proxy records a read-only `derivedFrom` link — so `decompress` / `search_context` fall back along the parent chain for content the child never saw itself (cycle-guarded, depth cap 8). Nothing is copied into the child, the parent is never modified; if the parent is unknown the child simply starts fresh. Per-lane parent signals (pi/omp `parentSession` header, OpenCode V1/V2 `parentID`): [SESSION-IDENTITY.md](SESSION-IDENTITY.md#derived-child-sessions-lineage-at-birth-1333-1362). claude/codex/dsh need nothing here: they share one session id across subagents or have no child-session concept at all.
|
||||
A child session (subagent/fork starting from an empty history) reports its lineage at birth — its identity registration carries `parentConversationId` and the proxy records a read-only `derivedFrom` link — so `decompress` / `search_context` fall back along the parent chain for content the child never saw itself (cycle-guarded, depth cap 8). Nothing is copied into the child, the parent is never modified; if the parent is unknown the child simply starts fresh. Per-lane parent signals (pi/omp `parentSession` header, OpenCode V1/V2 `parentID`): [docs/session-identity.md](docs/session-identity.md#derived-child-sessions-lineage-at-birth-1333-1362). claude/codex/dsh need nothing here: they share one session id across subagents or have no child-session concept at all.
|
||||
|
||||
### Running multiple instances (#3633)
|
||||
|
||||
@@ -640,15 +666,35 @@ Consequences for anyone tempted to put several instances behind one Service:
|
||||
conversation load-balanced across proxies*. Long conversations are
|
||||
single-instance by design.
|
||||
|
||||
**Single machine, multiple installs (#5046).** The topology above covers
|
||||
deployment replicas; one desktop has a sibling situation: two installs on ONE
|
||||
machine (e.g. two DSH profiles — desktop + bot, or a global npm copy beside a
|
||||
host-tree copy) each start their own proxy and, unless isolated, both resolve
|
||||
the SAME default XDG sessions directory and the same config file. Multiple
|
||||
processes writing ONE local-disk `index.db` is the SUPPORTED topology
|
||||
(#5082/#5091) — SQLite WAL is multi-process safe on a local filesystem — so
|
||||
startup NEVER blocks on a live foreign writer: the peer shows up as an
|
||||
info-level `[storage] process pid … is also using …` line plus the status wire,
|
||||
nothing more (policy settled 2026-10-31, withdrawing the #5046/B-era
|
||||
refuse-to-start for exactly this shape). What genuinely remains hazardous is
|
||||
two installs walking the SAME *session* concurrently — that case alarms
|
||||
separately (split-brain contest, #3923). If you still want strictly separate
|
||||
histories and stores per install, give each its own `BILI_SESSIONS_DIR` (plus
|
||||
`BILI_CONFIG_FILE` when the config should differ too) through that install's
|
||||
launcher/profile environment — no global env changes needed. Once isolated,
|
||||
the `[instances]` notice drops off entirely. Note the distinction from the
|
||||
deployment case above: local disk with SQLite WAL tolerates many writers;
|
||||
shared RWX/NFS storage does NOT and keeps requiring one writer per volume.
|
||||
|
||||
Naming note: `POST /__bili/replicas` creates a session **checkpoint fork**
|
||||
(from stored checkpoints), not a pod replica — read it as `/__bili/checkpoints`.
|
||||
|
||||
|
||||
The proxy rewrites each session's state file every turn of a long session; on Windows, real-time AV (Defender), the search indexer, or a sync tool (OneDrive) can lock the sessions dir mid-write, so persists fail with `EPERM` until the lock clears. Fix at the root: add `%USERPROFILE%\.local\share\billion-context\` to your antivirus exclusions (Defender steps included) and keep sync tools off that path — [CONFIGURATION.md](CONFIGURATION.md#windows-exclude-the-sessions-dir-from-antivirus-362). The same exclusion also covers the unified-storage `index.db` refusing to open (`unable to open database file`, #3823) — the storage-degrade warning names it as the first suspect.
|
||||
The proxy rewrites each session's state file every turn of a long session; on Windows, real-time AV (Defender), the search indexer, or a sync tool (OneDrive) can lock the sessions dir mid-write, so persists fail with `EPERM` until the lock clears. Fix at the root: add `%USERPROFILE%\.local\share\billion-context\` to your antivirus exclusions (Defender steps included) and keep sync tools off that path — [docs/configuration.md](docs/configuration.md#windows-exclude-the-sessions-dir-from-antivirus-362). The same exclusion also covers the unified-storage `index.db` refusing to open (`unable to open database file`, #3823) — the storage-degrade warning names it as the first suspect.
|
||||
|
||||
### Session file cleanup (#1082)
|
||||
|
||||
Short-lived sessions leave small state files behind that are never resumed. Cleanup is **opt-in** (`BILI_SESSION_GC=1`; off by default — session files are user data, no silent deletion policy): when enabled, bili sweeps the sessions dir at boot and hourly and deletes a file only when BOTH hold — older than `BILI_SESSION_GC_MAX_AGE_DAYS` (default 7 days) AND never compressed with its newest request body ≤ `BILI_SESSION_GC_MAX_TOKENS` tokens (default 1M) — so deletion loses nothing but bytes. CCR content stores follow their session file's lifecycle; compressed sessions are never deleted; every deletion is audit-logged. Full policy: [CONFIGURATION.md](CONFIGURATION.md#environment-variables).
|
||||
Short-lived sessions leave small state files behind that are never resumed. Cleanup is **opt-in** (`BILI_SESSION_GC=1`; off by default — session files are user data, no silent deletion policy): when enabled, bili sweeps the sessions dir at boot and hourly and deletes a file only when BOTH hold — older than `BILI_SESSION_GC_MAX_AGE_DAYS` (default 7 days) AND never compressed with its newest request body ≤ `BILI_SESSION_GC_MAX_TOKENS` tokens (default 1M) — so deletion loses nothing but bytes. CCR content stores follow their session file's lifecycle; compressed sessions are never deleted; every deletion is audit-logged. Full policy: [docs/configuration.md](docs/configuration.md#environment-variables).
|
||||
|
||||
### Storage maintenance CLI (#3928)
|
||||
|
||||
@@ -659,12 +705,15 @@ bili sessions ls # id, label, decoded size, last-updated, storag
|
||||
bili sessions rm <id> # full delete (content refcount release incl. media); shrinks index.db afterwards (--no-vacuum skips)
|
||||
bili sessions archive <id> # export to archive/archive.jsonl + sweep rows; tombstone keeps label & identity
|
||||
bili sessions restore <id> # bring an archived session back from the log line
|
||||
bili sessions foreign-blocks # (#5312) list fold blocks whose covered messages never belonged to this transcript — dry-run; --apply reversibly archives them, --restore <sid>:<bid> brings one back
|
||||
bili storage gc [--days N] [--vacuum full|incremental] [--dry-run]
|
||||
# print the sweep plan (sessions past retention, zero-ref content rows, ~pages reclaimable), then run the same gc() the HTTP endpoint calls; --dry-run stops after the plan
|
||||
```
|
||||
|
||||
`archive`/`restore`/`gc` require the unified store (`BILI_STORAGE_UNIFIED=shadow|full` or `storage.unified` in the config file) — legacy-only installs refuse with a hint. `--days` defaults to `storage.archiveAfterDays` (365). No scheduler: these run on demand. All commands accept `--json`.
|
||||
|
||||
**Full vacuum is an offline operation on large databases (#4612).** `--vacuum full` (the default) rewrites the entire index.db under an exclusive write lock — O(db size), minutes to tens of minutes on multi-GB databases, with no intermediate progress (SQLite's VACUUM is atomic; it cannot be split). Running it while a proxy is serving from the same sessions dir starves that proxy's writes until its storage layer degrades, so `storage gc --vacuum full` **refuses to start when another live process holds the database** (`index.db.lock` pid discipline, #4175): the CLI exits 1 with an actionable message, the panel endpoint returns HTTP 409. Stop the other instance first (or wait for it to exit) and retry; for online-safe shrink use `--vacuum incremental`, which reclaims freed pages in short transactions without taking the exclusive lock. The zero-ref delete sweep itself is batched with per-batch progress output either way.
|
||||
|
||||
## Status
|
||||
|
||||
Early. Protocol handling and compression work against mock tests (500+ passing). Real-model integration testing is the next milestone. Expect rough edges.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# billion-context
|
||||
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a></p>
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a> | <a href="./README.ja.md">日本語</a></p>
|
||||
|
||||
<p align="center"><strong>上下文压缩插件</strong> — <em>billion-context is all you need。</em></p>
|
||||
|
||||
@@ -50,7 +50,8 @@
|
||||
|
||||
QQ群:
|
||||
1056132097(已满)
|
||||
1108730198(未满)
|
||||
1108730198(已满)
|
||||
1129868472(未满)
|
||||
|
||||
---
|
||||
|
||||
@@ -62,6 +63,10 @@ QQ群:
|
||||
|
||||
生产规模纵向研究:四个半月、三宿主、174,327 次模型调用、187.6 亿累计输入 token(三宿主合计约 247 亿),204,800-token 窗口零违规,马拉松会话 8,584–12,049 次调用。
|
||||
|
||||
### 📊 第三方独立评测基准
|
||||
|
||||
- **[1,500 题三大基准横评报告(`LongMemEval-S` · `ContextBench` · `MemoryAgentBench`)](./benchmarks/third-party-1500/README.zh-CN.md)**([English](./benchmarks/third-party-1500/README.md))—— 基于 `DeepSeek V4.1 Flash`、`Qwen3-Embedding-8B`、`Qwen3-Reranker-4B` 与 `Pi Agent`,对 `billion-context` (`v0.1.202`)、`full` 全量上下文及 3 条 RAG 管线(`bm25`、`embedding`、`embedding-rerank`)进行全成本归因盲测:**ContextBench 端到端有效 F1 夺得全场第一**(`0.3097`,比 `full` 省钱 `58.3%`)、**LongMemEval-S 领先最强 RAG 达 +16.6%**(`79.20%` vs `62.60%`,比独立会话 `full` 省钱 `71.1%`)、**MemoryAgentBench 1.48M 超长会话实现 100% 存活与 30× 稳态压缩**(`full` 199 题全部爆窗崩溃)。
|
||||
|
||||
---
|
||||
|
||||
`billion-context` 架在**任意**编程助手与其模型 API 之间,用 [acp-kernel](https://github.com/ranxianglei/acp-kernel) 压缩重写 Anthropic/OpenAI 流。何时压缩、压缩什么 —— <strong>由模型决定</strong>,而非硬截断。
|
||||
@@ -74,21 +79,7 @@ QQ群:
|
||||
|
||||
## 工作原理
|
||||
|
||||
```
|
||||
编程助手 (Claude Code / Codex / Cursor / Aider ...)
|
||||
│ 你把助手的 base URL 指向 proxy
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ billion-context│ 1. 解析请求(Anthropic 或 OpenAI 格式)
|
||||
│ proxy │ 2. 对对话运行 acp-kernel 压缩
|
||||
│ │ 3. 注入 `compress` 工具 + 压缩哲学
|
||||
│ │ 4. 转发到真实模型 API
|
||||
│ │ 5. 重写流式响应
|
||||
└─────────────────┘
|
||||
│
|
||||
▼
|
||||
真实模型 API (Anthropic / OpenAI / 兼容厂商)
|
||||
```
|
||||

|
||||
|
||||
### 上下文管理工具
|
||||
|
||||
@@ -107,24 +98,25 @@ QQ群:
|
||||
|
||||
| 客户端 | 用这个 |
|
||||
|---|---|
|
||||
| **pi** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili pi`(启动器)或 `bili plugin install pi`(原生);独立 [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) 仍可用 —— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md#pipidev-coding-agent) |
|
||||
| **opencode**(1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili opencode`(启动器)或 `bili plugin install opencode`(原生);独立 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 在 1.x 上仍可用 —— 完整指南:[OpenCode](CLIENTS.zh-CN.md#opencode) |
|
||||
| **pi** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili pi`(启动器)或 `bili plugin install pi`(原生);独立 [`billion-context-pi`](https://github.com/ranxianglei/billion-context-pi) 仍可用 —— 细节见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md#pipidev-coding-agent) |
|
||||
| **opencode**(1.x / 2.x) | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili opencode`(启动器)或 `bili plugin install opencode`(原生);独立 [`opencode-acp`](https://github.com/ranxianglei/opencode-acp) 在 1.x 上仍可用 —— 完整指南:[OpenCode](docs/clients.zh-CN.md#opencode) |
|
||||
| **omp** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili omp`(内置插件)或 `bili plugin install omp`(自拉起原生插件,免启动器) |
|
||||
| **dsh** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili dsh`(启动器,经 `--patch` 注入完整原生插件)或 `bili plugin install dsh` ≡ `dsh plugin --profile <name> add billion-context`(统一泳道)—— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
||||
| **kimi** | `bili plugin install kimi`(自拉起原生,需 Kimi Code ≥ 2.0.0)或 `bili kimi`(证书 MITM)或 `/bili/` 前缀 —— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
||||
| **dsh** | [`billion-context`](https://github.com/ranxianglei/billion-context) —— `bili dsh`(启动器,经 `--patch` 注入完整原生插件)或 `bili plugin install dsh` ≡ `dsh plugin --profile <name> add billion-context`(统一泳道)—— 细节见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md) |
|
||||
| **kimi** | `bili plugin install kimi`(自拉起原生,需 Kimi Code ≥ 2.0.0)或 `bili kimi`(证书 MITM)或 `/bili/` 前缀 —— 细节见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md) |
|
||||
| **hermes** | `bili plugin install hermes`(自拉起原生,Python 插件 #958)或 `bili hermes`(证书 MITM) |
|
||||
| **zcode**(Z.ai / bigmodel coding plan) | `bili plugin install zcode`(自拉起原生,#1145)或 GUI「设置 → 网络」证书 MITM 或 `/bili/` 前缀 —— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
||||
| **zcode**(Z.ai / bigmodel coding plan) | `bili plugin install zcode`(自拉起原生,#1145)或 GUI「设置 → 网络」证书 MITM 或 `/bili/` 前缀 —— 细节见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md) |
|
||||
| **claude** | `bili claude`(启动器)或 `bili plugin install claude`(原生姿态,#964 —— 受管 settings 块 + 会话自管代理;见下方"注意") |
|
||||
| **codex** | `bili codex`(启动器 —— 全功能零配置姿势)或 `bili plugin install codex`(MCP shell 工具面配套:**先起 bili 再玩** —— shell 不拉代理,也路由不了 codex 本体流量)—— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md#codexopenai-codex-cli) |
|
||||
| **codex** | `bili codex`(启动器 —— 全功能零配置姿势)或 `bili plugin install codex`(MCP shell 工具面配套:**先起 bili 再玩** —— shell 不拉代理,也路由不了 codex 本体流量)—— 细节见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md#codexopenai-codex-cli) |
|
||||
| **jcode** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili jcode`(cert-MITM)或 `/bili/` 前缀 —— 无原生模式(编译型 Rust 二进制、无插件接缝,[#962](https://github.com/ranxianglei/billion-context/issues/962)) |
|
||||
| **gemini**(Gemini CLI) | `bili gemini`(启动器,`GOOGLE_GEMINI_BASE_URL` `/bili/` 改写)或 `/bili/` 前缀 —— 仅启动器(无环内工具注入接缝,#1043) |
|
||||
| **iflow**(iFlow CLI) | `bili iflow`(启动器,`IFLOW_BASE_URL` `/bili/` 改写)或 `/bili/` 前缀 |
|
||||
| **qwen**(Qwen Code) | `bili qwen`(启动器,cert-MITM)或 `/bili/` 前缀 |
|
||||
| **antigravity**(Antigravity CLI / agy,Google) | `bili antigravity`(启动器,`CLOUD_CODE_URL` 对 `daily-cloudcode-pa.googleapis.com` 的 `/bili/` 改写 —— Antigravity 真实默认上游,#3129)或 `/bili/` 前缀 —— 无插件接缝(闭源 Go language_server;其用户插件面仅可追加、不能拦截模型流,[#2115](https://github.com/ranxianglei/billion-context/issues/2115))—— 细节见 [CLIENTS.zh-CN.md](CLIENTS.zh-CN.md) |
|
||||
| **antigravity**(Antigravity CLI / agy,Google) | `bili antigravity`(启动器,`CLOUD_CODE_URL` 对 `daily-cloudcode-pa.googleapis.com` 的 `/bili/` 改写 —— Antigravity 真实默认上游,#3129)或 `/bili/` 前缀 —— 无插件接缝(闭源 Go language_server;其用户插件面仅可追加、不能拦截模型流,[#2115](https://github.com/ranxianglei/billion-context/issues/2115))—— 细节见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md) |
|
||||
| **mcode**(MiniMax Code) | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili mcode`(cert-MITM)或 `/bili/` 前缀 —— 无原生模式(纯声明式事件钩子,无模型请求接缝,[#1050](https://github.com/ranxianglei/billion-context/issues/1050)) |
|
||||
| **aider** | [`billion-context`](https://github.com/ranxianglei/billion-context),`bili aider`(cert-MITM)或 `/bili/` 前缀 —— 无原生模式(仅 shell 命令钩子,无工具注入接缝,[#1048](https://github.com/ranxianglei/billion-context/issues/1048)) |
|
||||
| **copilot**(GitHub Copilot CLI) | `bili copilot`(启动器,cert-MITM)—— 闭源 Go 二进制、无插件接缝(#1049) |
|
||||
| **amp**(Amp CLI) | `bili amp`(启动器,cert-MITM)—— 闭源 Go 二进制、无插件接缝(#1049) |
|
||||
| **kiro**(Kiro CLI,AWS) | `bili kiro`(启动器,cert-MITM)—— Rust 外壳 + Node 代理服务、无插件接缝;模型流量走 `runtime.<region>.kiro.dev` 的 Responses wire,网关差异已内置处理——详见 [docs/clients.zh-CN.md](docs/clients.zh-CN.md#kiro-cliaws) |
|
||||
| **crush**(Charm Crush) | `bili crush`(启动器,cert-MITM)—— 开源 Go 二进制、无插件接缝;内置 provider 域加白,crush.json 自定义 `base_url` 自动发现(#2340) |
|
||||
| **zed**(Zed 编辑器) | `bili zed`(启动器,cert-MITM)—— 开源 Rust 编辑器、无插件接缝;reqwest 吃 HTTPS_PROXY,CA 走 SSL_CERT_FILE(Linux TLS env 探测);内置 provider 域加白,settings.json 自定义 `api_url` 自动发现;环回 provider(ollama/lmstudio)经 NO_PROXY 保持直连(#2340) |
|
||||
| **goose**(Goose CLI) | `bili goose`(启动器)—— rustls 不信任任何 CA 文件,无法 cert-MITM:openai/anthropic 腿经 `OPENAI_HOST`/`ANTHROPIC_HOST`,自定义 provider 经重新生成的 `GOOSE_PATH_ROOT` overlay(#1049) |
|
||||
@@ -155,7 +147,7 @@ npm install -g billion-context --prefix=~/.local
|
||||
- **启动器(免安装):** `bili <client>` 一条命令拉起代理 + 客户端,不碰任何真实配置文件.
|
||||
- **改url(最通用):** 在客户端 baseURL 前面加上代理地址 + `/bili/`。
|
||||
|
||||
三种方式背后的机制细节(插件生命周期、runtime-info 协议、注入优先级)见 [TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。
|
||||
三种方式背后的机制细节(插件生命周期、runtime-info 协议、注入优先级)见 [docs/technical-notes.zh-CN.md](docs/technical-notes.zh-CN.md)。
|
||||
|
||||
端口,一句话(#1660):`bili start`(手工)拥有 `8787`;lane 替你拉起的一切(原生 hook、启动器 lane)住在独立的自管端口区,从 `18787` 起 —— 碰撞 +1 跳口、每个 lane 记住自己的漂移,零配置安装永不抢端口,刻意常驻的 `bili start` 守护进程则默认被附着。Attach 按泳道感知(#2905):hook 先骑自己 lane 的实例,绝不骑其他已声明 lane —— 除非在 `native.attachLanePriority` 里显式列出 —— 8787 用户区守护永远是最后兜底。升级重启时若旧版本还在该 lane 端口上排水,会最多等 5 秒让它释放并复用同一端口,而不是漂移(#1723);只有真正被占用的端口才 +1 跳口 —— 且这种跳口现在会大声打 warn。
|
||||
|
||||
@@ -186,16 +178,16 @@ pi / omp / kimi / claude 没有客户端侧通道 —— 它们的配置条目
|
||||
|
||||
- 原生模式与独立进程内扩展(`billion-context-pi`、`opencode-acp`)**互斥** —— 安装器负责换条目并把原配置快照(`.bili-bak`)。
|
||||
- **pi:** 原生安装默认自带子代理功能(`acp_delegate` / `acp_delegate_wait` / `acp_delegate_cancel`)—— 如何关闭它们并保留上下文压缩:[Pi 内置子代理](#pi-内置子代理)。
|
||||
- OpenCode 旧会话、V1/V2 插件形态与全部注意事项:[OpenCode](CLIENTS.zh-CN.md#opencode)。
|
||||
- OpenCode 旧会话、V1/V2 插件形态与全部注意事项:[OpenCode](docs/clients.zh-CN.md#opencode)。
|
||||
- `kimi` 仅在自举时上报 runtime-info(静态头无法承载逐请求窗口/模型值);子代理工具调用由代理的出站 tool_use 见证环路由(#1685)——模型看不到任何会话 id。
|
||||
- `hermes` 的原生插件是 Python:健康检查通过后用环境变量把 hermes 的 httpx 栈指向代理,并经 `llm_request` 中间件打逐请求头。
|
||||
- `claude` 有**原生姿态**(#964):受管 settings 块 + `SessionStart` hook + MCP shell;hook 骑自管端口区(#1660),每会话把受管 URL 重钉到存活 origin,端口漂移自愈。#1821 起 MCP shell 还在会话内守护代理(30s × 3 次失败),代理死亡时自行重生,lane 内模型请求 ~90s 内恢复而无需新开会话(与 zcode 车道同语义)。`BILI_NATIVE_CLAUDE=0` 退出(passthrough)。机制:[TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。**已知限制(#2290):** Claude Desktop 应用的 Code 标签页(`CLAUDE_CODE_ENTRYPOINT=claude-desktop`)会为其内嵌的 Claude Code 设置自己的 `ANTHROPIC_BASE_URL`,覆盖受管值——桌面会话完全绕过代理,而受管块的 `DISABLE_AUTO_COMPACT=1` 仍然生效,因此既没有 bili 压缩、也没有原生自动压缩。hook 会在会话开始时大声警告并记录下来供 `bili doctor` 展示(检测到本机装有 Claude Desktop 时,该 lane 也会显示 ⚠️ 提示);终端会话不受影响。**真机验证(2026-10-06,#2290):** 把 `HTTPS_PROXY` 写进 settings 的 `env` 块后,在 Claude Desktop 2.19675.1 / 内嵌 CC 2.1.288(Windows 11)上对一台开启 MITM 的存活代理**零 CONNECT 流量**——该变量没有到达应用内任何网络栈,与该时期的 CLI 行为一致——注意新版构建(CC 2.1.301 起)在 CLI 上会遵守 `HTTPS_PROXY`,这正是 `bili claude` 走 `/bili/` base-URL 改写的原因——launcher 不再为该 lane 设置代理、也不再设置 CA,而自带代理的子进程会把 loopback 主机合并进 `NO_PROXY`/`no_proxy`,确保无论子进程的代理行为如何,这一腿都保持直连(#3446)。截至该版本,桌面 Code 标签页不存在可用的路由缝隙;该 lane 继续在 [#2290](https://github.com/ranxianglei/billion-context/issues/2290) 跟踪,若上游行为变化再议。仅用桌面的用户可用 `bili plugin remove claude` 恢复原生自动压缩。
|
||||
- `zcode` 有**原生姿态**(#1145):受管 `~/.zcode/cli/config.json` 块 + 每会话 provider `baseURL` 改写。完整机制:[CLIENTS.zh-CN.md](CLIENTS.zh-CN.md)。
|
||||
- `omp` 是自拉起原生插件;`codex` 性质不同 —— 它是 MCP shell 工具面配套:codex 的模型流量只能经 env 路由(默认 ChatGPT-登录 provider 没有可改写的配置缝 —— managed `model_providers` 块会强制 API-key 认证、废掉订阅登录),而 MCP 子进程无法向父进程注入 env,所以插件安装既不拉代理、也永远路由不了 codex 本体流量。`bili plugin install codex` 在 `~/.codex/config.toml` 写入 `[mcp_servers.bili]`(command = node,args = dist/mcp.js)注册四个 ACP 工具,会话启动时解析代理:env `BILI_MCP_PROXY` > 活实例登记(任一 lane 的代理或 `bili start` 守护)> 8787 用户区默认(#1660 去掉了安装时烘焙 origin,#403)—— 全不可达则 `tools/list` 报 -32003。结论:**先起 bili**(`bili start` 或任一客户端的 lane 代理),想要压缩再自行导出 HTTPS_PROXY;零配置全功能用 `bili codex`。机制:[CLIENTS.zh-CN.md](CLIENTS.zh-CN.md#codexopenai-codex-cli)。
|
||||
- `claude` 有**原生姿态**(#964):受管 settings 块 + `SessionStart` hook + MCP shell;hook 骑自管端口区(#1660),每会话把受管 URL 重钉到存活 origin,端口漂移自愈。#1821 起 MCP shell 还在会话内守护代理(30s × 3 次失败),代理死亡时自行重生,lane 内模型请求 ~90s 内恢复而无需新开会话(与 zcode 车道同语义)。`BILI_NATIVE_CLAUDE=0` 退出(passthrough)。机制:[docs/technical-notes.zh-CN.md](docs/technical-notes.zh-CN.md)。**已知限制(#2290):** Claude Desktop 应用的 Code 标签页(`CLAUDE_CODE_ENTRYPOINT=claude-desktop`)会为其内嵌的 Claude Code 设置自己的 `ANTHROPIC_BASE_URL`,覆盖受管值——桌面会话完全绕过代理,而受管块的 `DISABLE_AUTO_COMPACT=1` 仍然生效,因此既没有 bili 压缩、也没有原生自动压缩。hook 会在会话开始时大声警告并记录下来供 `bili doctor` 展示(检测到本机装有 Claude Desktop 时,该 lane 也会显示 ⚠️ 提示);终端会话不受影响。**真机验证(2026-10-06,#2290):** 把 `HTTPS_PROXY` 写进 settings 的 `env` 块后,在 Claude Desktop 2.19675.1 / 内嵌 CC 2.1.288(Windows 11)上对一台开启 MITM 的存活代理**零 CONNECT 流量**——该变量没有到达应用内任何网络栈,与该时期的 CLI 行为一致——注意新版构建(CC 2.1.301 起)在 CLI 上会遵守 `HTTPS_PROXY`,这正是 `bili claude` 走 `/bili/` base-URL 改写的原因——launcher 不再为该 lane 设置代理、也不再设置 CA,而自带代理的子进程会把 loopback 主机合并进 `NO_PROXY`/`no_proxy`,确保无论子进程的代理行为如何,这一腿都保持直连(#3446)。截至该版本,桌面 Code 标签页不存在可用的路由缝隙;该 lane 继续在 [#2290](https://github.com/ranxianglei/billion-context/issues/2290) 跟踪,若上游行为变化再议。**账号绑定功能(#4693):** 由于该车道经自定义 `ANTHROPIC_BASE_URL` 路由,Claude Code 会把会话当作第三方/API-key 模式,从而关闭绑定你 Anthropic 账号/云端的功能——**Remote Control**(`/remote-control`,从手机/桌面/网页接管本机会话)会在 bili 路由期间从命令列表消失。压缩本身不受影响;需要这些功能的会话请直接用不带 bili 的原生 `claude`(或 `bili plugin remove claude`)。这是 base-URL 路由缝隙的固有取舍——没有别的拦截点能绕过 CC 的 undici 栈(#2290)——而非配置被删。仅用桌面的用户可用 `bili plugin remove claude` 恢复原生自动压缩。#5095 起受管块还会安装一个 `SubagentStart` hook(`node <root>/dist/claude-subagent-hook.js`),给每次子代理派发铸一个随机 lane token 注入其上下文:骑着父会话 id 且无 agent-id 头的子代理(VS Code 扩展构建,#4352)按 `<id>|sub:…:t:<token>` 键控各自的压缩车道,并行同型派发不再合流(首条消息被折叠后 token 消失,后续请求回落到指纹车道)。卸载时随受管块一并移除。
|
||||
- `zcode` 有**原生姿态**(#1145):受管 `~/.zcode/cli/config.json` 块 + 每会话 provider `baseURL` 改写。完整机制:[docs/clients.zh-CN.md](docs/clients.zh-CN.md)。
|
||||
- `omp` 是自拉起原生插件;`codex` 性质不同 —— 它是 MCP shell 工具面配套:codex 的模型流量只能经 env 路由(默认 ChatGPT-登录 provider 没有可改写的配置缝 —— managed `model_providers` 块会强制 API-key 认证、废掉订阅登录),而 MCP 子进程无法向父进程注入 env,所以插件安装既不拉代理、也永远路由不了 codex 本体流量。`bili plugin install codex` 在 `~/.codex/config.toml` 写入 `[mcp_servers.bili]`(command = node,args = dist/mcp.js)注册四个 ACP 工具,会话启动时解析代理:env `BILI_MCP_PROXY` > 活实例登记(任一 lane 的代理或 `bili start` 守护)> 8787 用户区默认(#1660 去掉了安装时烘焙 origin,#403)—— 全不可达则 `tools/list` 报 -32003。结论:**先起 bili**(`bili start` 或任一客户端的 lane 代理),想要压缩再自行导出 HTTPS_PROXY;零配置全功能用 `bili codex`。机制:[docs/clients.zh-CN.md](docs/clients.zh-CN.md#codexopenai-codex-cli)。
|
||||
- `jcode`、`aider` 无原生模式(无插件/MCP/工具注入接缝:#962、#1048)—— 用 `bili jcode` / `bili aider`。
|
||||
- `copilot`、`amp`、`crush`、`zed`、`goose` 仅启动器模式(#1049/#2340);goose 无法 cert-MITM(rustls 不信任任何 CA 文件),改走纯 HTTP base-URL 重定向。
|
||||
|
||||
### 方式 2 —— 启动器(`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi` / `bili gemini` / `bili iflow` / `bili qwen` / `bili antigravity` / `bili mcode` / `bili aider` / `bili copilot` / `bili amp` / `bili crush` / `bili zed` / `bili goose`)
|
||||
### 方式 2 —— 启动器(`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh` / `bili codebuddy` / `bili qoder` / `bili trae` / `bili jcode` / `bili kimi` / `bili gemini` / `bili iflow` / `bili qwen` / `bili antigravity` / `bili mcode` / `bili aider` / `bili copilot` / `bili amp` / `bili crush` / `bili zed` / `bili goose` / `bili kiro`)
|
||||
|
||||
启动器把客户端包进一条命令:在独立端口拉起一个代理(总是全新实例,绝不复用端口),再按客户端支持的机制把它指向代理 —— 能吃代理/CA 环境变量的走**证书 MITM**,不吃的走隔离的**`/bili/` 配置重写**。真实配置文件从不被修改;客户端自己的配置只被**读取**,用来发现它实际连接的 HTTPS 上游主机,把这些主机加入 MITM 白名单 —— 代理只 TLS 终结它们,其余流量盲透传。
|
||||
|
||||
@@ -204,11 +196,11 @@ bili pi # 拉起 pi,走代理 —— file-free(#53
|
||||
bili codex # 拉起 codex
|
||||
bili claude # 拉起 claude
|
||||
bili omp # pi 同款,file-free(#535):环境变量 + 扩展 registerProvider + 压缩取消,真实 ~/.omp 不动
|
||||
bili opencode # OpenCode(1.x 与 2.x):完整指南见下文 [OpenCode](CLIENTS.zh-CN.md#opencode) 一节
|
||||
bili opencode # OpenCode(1.x 与 2.x):完整指南见下文 [OpenCode](docs/clients.zh-CN.md#opencode) 一节
|
||||
bili hermes # file-free(#535):hermes 代理环境变量(HTTPS_PROXY + SSL_CERT_FILE 组合 CA bundle)—— https 走 CONNECT MITM,http 走绝对形式转发;真实 ~/.hermes 不动
|
||||
bili dsh # deepseek-harness:经 --patch 注入完整原生插件(#941) —— 真实 dsh 工具、会话绑定 /acp(plugin 模式);非回环上游走代理 env,回环保留 overlay DSH_HOME 改写(#535);dsh 自动压缩处处关闭(宿主平面经 bundle patch,web profile 的 preset 经 #3354 加载期 overlay,#1772/#2474/#3354)
|
||||
bili codebuddy # Tencent CodeBuddy Code CLI:CODEBUDDY_BASE_URL /bili/ 重写(OpenAI chat completions wire),预算对齐走 CODEBUDDY_AUTO_COMPACT_WINDOW;真实 ~/.codebuddy 不动
|
||||
bili qoder # qoder:模型端点硬编码 https(无法 /bili/ 改写)—— 证书 MITM(HTTPS_PROXY + NODE_EXTRA_CA_CERTS),默认模型主机已加白名单(#653)
|
||||
bili qoder # qoder CLI(`qoder`/`qodercli`):模型端点硬编码 https(无法 /bili/ 改写)—— 证书 MITM(HTTPS_PROXY + NODE_EXTRA_CA_CERTS),默认模型主机已加白名单(#653)。Qoder Desktop 是另一条 BYOK/自定义渠道,走 `/bili/` 前缀的明文 OpenAI wire —— 当作普通自定义 provider 指向 bili 即可(不走这条 MITM 车道);其官方订阅流量是加密的,不在范围内(#764)
|
||||
bili trae # Trae CLI(字节跳动,闭源 Go 二进制,无 base-URL 覆盖)—— 证书 MITM(HTTPS_PROXY + SSL_CERT_FILE),模型主机取 TRAE_CLI_API_HOST 或默认企业网关(#655)
|
||||
bili jcode # jcode(Rust 终端编码 agent)—— 环境变量式证书 MITM 启动:HTTPS_PROXY + SSL_CERT_FILE,模型主机 api.z.ai 默认加白,本地回环 provider 走 NO_PROXY 直连
|
||||
bili kimi # Kimi Code CLI(Moonshot):除无条件回环绕过外遵循标准代理环境变量 —— https 证书 MITM、http 绝对形式转发;回环端点编目并附手动 /bili/ 提示(#757)
|
||||
@@ -223,6 +215,7 @@ bili amp # Amp CLI(Sourcegraph,闭源 Go 二进制)
|
||||
bili crush # Crush(Charm,开源 Go 二进制)—— 证书 MITM(HTTPS_PROXY + SSL_CERT_FILE),api.anthropic.com/api.openai.com/openrouter.ai + crush.json 自定义 base_url 加白(#2340)
|
||||
bili zed # Zed 编辑器(开源 Rust)—— 证书 MITM(HTTPS_PROXY + SSL_CERT_FILE,Linux TLS env 探测),内置 provider 域 + settings.json 自定义 api_url 加白,环回 provider 保持直连(#2340)
|
||||
bili goose # Goose(Block,Rust/reqwest):rustls 发布构建不信任任何 CA 文件 —— openai/anthropic 腿经 OPENAI_HOST/ANTHROPIC_HOST,自定义 provider 经重新生成的 GOOSE_PATH_ROOT overlay(/bili/ 改写,真实配置不动)(#1049)
|
||||
bili kiro # Kiro CLI(AWS):经 HTTPS_PROXY + SSL_CERT_FILE 与 NODE_EXTRA_CA_CERTS 上的合并 CA 做 cert-MITM;只解密 runtime.<region>.kiro.dev;developer/system 项为网关改写为 user;会话 = Kiro 的 conversation id(--resume 后保持)
|
||||
bili pi --mitm-domain api.foo.com # 向 MITM 白名单追加域名
|
||||
```
|
||||
|
||||
@@ -259,7 +252,7 @@ curl -s http://localhost:8787/__bili/stats
|
||||
|
||||
### 客户端深入
|
||||
|
||||
一行带不过来的细节 —— 各模式(启动器 / `/bili/` URL 前缀 / 原生插件)如何把流量接进代理、往哪儿写了什么、已知局限有哪些 —— 都在 **[CLIENTS.zh-CN.md](CLIENTS.zh-CN.md)**:dsh · Kimi Code · Hermes · ZCode · Gemini 系(Gemini CLI / iFlow CLI / Qwen Code / Antigravity)· CONNECT 盲隧道接入但从不压缩的客户端(#897)· 未识别端点直连(#1290)· OpenCode(启动器 / 原生 / 纯代理、`/acp` 状态与规则、旧 opencode-acp 会话 #920)。
|
||||
一行带不过来的细节 —— 各模式(启动器 / `/bili/` URL 前缀 / 原生插件)如何把流量接进代理、往哪儿写了什么、已知局限有哪些 —— 都在 **[docs/clients.zh-CN.md](docs/clients.zh-CN.md)**:dsh · Kimi Code · Hermes · ZCode · Gemini 系(Gemini CLI / iFlow CLI / Qwen Code / Antigravity)· CONNECT 盲隧道接入但从不压缩的客户端(#897)· 未识别端点直连(#1290)· OpenCode(启动器 / 原生 / 纯代理、`/acp` 状态与规则、旧 opencode-acp 会话 #920)。
|
||||
|
||||
## 从源码安装(开发)
|
||||
|
||||
@@ -285,17 +278,21 @@ bili --version
|
||||
|
||||
**`/acp` 显示什么?** 带原生插件的客户端(opencode、dsh)里,`/acp` 直接从代理取当前会话的 ACP 状态面板(会话、块、可压缩区间、用量);首个模型请求到来前显示空闲提示。`/acp-cache [full]` 打印上面的缓存报告。
|
||||
|
||||
**能用网页查会话和配置吗?** 能 —— 打开 [http://localhost:8787](http://localhost:8787):总览仪表盘、会话列表(含逐会话详情)、实时日志、配置编辑器、上游连通性测试。全部功能同样以纯 JSON 提供(`/__bili/stats`、`/__bili/sessions`、`/__bili/config`、…),方便脚本化。
|
||||
**能用网页查会话和配置吗?** 能 —— 打开 [http://localhost:8787](http://localhost:8787):总览仪表盘、会话列表(含逐会话详情)、实时日志、配置编辑器、上游连通性测试。「博客」页还在面板内直接渲染发布笔记与长文——随装内置,在线时后台自动从 GitHub master 拉取新文章(约 1 小时节流,离线时回退到内置旧内容),完整文库也在 GitHub Pages。其余功能同样以纯 JSON 提供(`/__bili/stats`、`/__bili/sessions`、`/__bili/config`、…),方便脚本化。
|
||||
|
||||
**压缩什么时候发生?** 由模型驱动:注入的上下文工具由模型在上下文增长时自行调用,温和的增长 nudge(按设计固定约 50K token 步长,可用 `compress.nudgeGrowthTokens` 调整)沿途提醒它,仅输入就超窗时预检作为硬兜底触发(#470)。用 `/acp` 或网页界面实时观察。
|
||||
|
||||
**为什么第一次压缩要到 ~200k 才触发?** 压缩触发不是按绝对窗口位置、而是按增长区间:默认在开机内容之上增长 50k token 才触发第一次软压缩(`compress.nudgeGrowthTokens` 恒定步长、与窗口无关)。开机 100k 左右、或把 `compress.nudgeGrowthTokens` 设到 100k 左右时,可能都要到 ~200k 才发生第一次压缩。想更早压缩省 token:1.删减系统提示词、关闭不需要的工具、精简 skill;2.把 nudge 调小到 50k 左右;3.开启 lean 功能。完整算例见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md#为什么第一次压缩要到-200k-才触发)。
|
||||
**压缩会缩小客户端自己的对话文件吗?** 不会 —— 这是超长会话里最常见的意外(#5796)。压缩缩的是**发给模型的内容**:每个出站请求都由存活块加摘要重建,所以对话再长、线上体积也保持小。客户端自己存的对话历史是用户数据 —— bili 从不改写它。dsh 上宿主自带的自动压缩在 bili 激活时还会被一并关闭(两个压缩器不能抢同一份历史,#1772/#2474/#3354),因此宿主侧文件随每一轮增长:文件越大每轮越慢(实测约 3 万条消息时每轮几十秒,#5796),实际可行的收敛路径就是**重开一个新会话**。网页会话列表会对请求数达到 5000+ 的会话打上「长会话/slow」徽标作为提醒。
|
||||
|
||||
**bili 是透明的吗?怎么关掉?** 未识别端点原样转发([CLIENTS.zh-CN.md](CLIENTS.zh-CN.md)),且每种模式都能干净退出:原生安装用 `bili plugin remove <client>`,另两种模式停掉启动器命令 / 环境变量 / `/bili/` 前缀即可 —— 流量立刻恢复直连。
|
||||
**为什么第一次压缩要到 ~200k 才触发?** 压缩触发不是按绝对窗口位置、而是按增长区间:默认在开机内容之上增长 50k token 才触发第一次软压缩(`compress.nudgeGrowthTokens` 恒定步长、与窗口无关)。开机 100k 左右、或把 `compress.nudgeGrowthTokens` 设到 100k 左右时,可能都要到 ~200k 才发生第一次压缩。想更早压缩省 token:1.删减系统提示词、关闭不需要的工具、精简 skill;2.把 nudge 调小到 50k 左右;3.开启 lean 功能。完整算例见 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md#为什么第一次压缩要到-200k-才触发)。
|
||||
|
||||
**能配合模型路由网关(如 [magpie](https://github.com/yetone/magpie))用吗?** 能 —— 客户端指向 bili、bili 经 `/bili/` 前缀指向网关(前缀内嵌网关的绝对 URL):`http://localhost:8787/bili/http://127.0.0.1:3425…`。例:Claude Code → `ANTHROPIC_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:3425` + `ANTHROPIC_API_KEY=magpie`;OpenAI 系客户端 → `OPENAI_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:3425/v1`(+ `OPENAI_API_KEY=magpie`)。压缩发生在路由*之前*——到达网关节点里任何账号的请求都已是压缩后的。凭据留在网关内:客户端的假 key 原样穿过,真实 key 不接触 bili。注意:① 会话中途切换账号会使 provider 前缀缓存失效——多账号路由的固有代价,与 bili 无关(见 `/acp-cache` 的 KEY SWITCHES 段);② 路由后的模型名对 bili 的窗口查询不透明——需在 providers 键 `http://127.0.0.1:3425` 下用 `models.<name>.context` 声明其上下文窗口,否则按兜底窗口运行(route-miss 警告,#2317);③ 中继若拒绝 bili Anthropic 车道的 `cache_control` 标记,设 `compat.noCacheControl`;④ 回环网关开箱即用;网关在非回环私网地址时可能还需 `network.allowPrivateHttpProviders`(#2984)。三条线(OpenAI Chat / Responses / Anthropic Messages,含跨协议转换)已端到端实测,#4433。
|
||||
**bili 是透明的吗?怎么关掉?** 未识别端点原样转发([docs/clients.zh-CN.md](docs/clients.zh-CN.md)),且每种模式都能干净退出:原生安装用 `bili plugin remove <client>`,另两种模式停掉启动器命令 / 环境变量 / `/bili/` 前缀即可 —— 流量立刻恢复直连。
|
||||
|
||||
**日志和会话数据存在哪?** 日志:`~/.local/state/billion-context/bili.log`(同时镜像到 stderr);会话状态:`~/.local/share/billion-context/`(XDG 可覆盖;Windows 杀软排除 #362、可选清理 #1082)—— 完整路径见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。
|
||||
**能配合模型路由网关(如 [magpie](https://github.com/yetone/magpie))用吗?** 能 —— 客户端指向 bili、bili 经 `/bili/` 前缀指向网关(前缀内嵌网关的绝对 URL):`http://localhost:8787/bili/http://127.0.0.1:3425…`。例:Claude Code → `ANTHROPIC_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:3425` + `ANTHROPIC_API_KEY=magpie`;OpenAI 系客户端 → `OPENAI_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:3425/v1`(+ `OPENAI_API_KEY=magpie`)。压缩发生在路由*之前*——到达网关节点里任何账号的请求都已是压缩后的。凭据留在网关内:客户端的假 key 原样穿过,真实 key 不接触 bili。注意:① 会话中途切换账号会使 provider 前缀缓存失效——多账号路由的固有代价,与 bili 无关(见 `/acp-cache` 的 KEY SWITCHES 段);② 路由后的模型名对 bili 的窗口查询不透明——需在 providers 键 `http://127.0.0.1:3425` 下用 `models.<name>.context` 声明其上下文窗口,否则按兜底窗口运行(route-miss 警告,#2317);③ 中继若拒绝 bili Anthropic 车道的 `cache_control` 标记,设 `compat.noCacheControl`;④ 回环网关开箱即用;网关在非回环私网地址时可能还需 `network.allowPrivateHttpProviders`(#2984);⑤ Claude Code 原生插件模式(`bili plugin install claude`)下,可在安装前设 `BILI_CLAUDE_UPSTREAM=http://127.0.0.1:3425`,受管配置块会自动将其包裹为代理 URL(或直接配置 `ANTHROPIC_BASE_URL=http://127.0.0.1:8787/bili/http://127.0.0.1:3425`;`localhost` 与 `127.0.0.1` 均被正确识别,#5369)。三条线(OpenAI Chat / Responses / Anthropic Messages,含跨协议转换)已端到端实测,#4433。
|
||||
|
||||
**能配合 [opencodex](https://github.com/lidge-jun/opencodex)(`ocx`)用吗?——它是带 ChatGPT 账号池的本地 Codex/Claude Code 网关。** 同样的模式:客户端指向 bili、bili 经 `/bili/` 前缀指向 ocx —— OpenAI 系客户端(chat completions 与 Responses,如 Codex)→ `OPENAI_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:10100/v1`;Anthropic 系客户端 → `ANTHROPIC_BASE_URL=http://localhost:8787/bili/http://127.0.0.1:10100`。要求 key 的客户端填个假值即可,原样穿过。bili 要放在 ocx *前面*而不是后面:provider 凭据与账号池都在 ocx 这一最终跳上,只有这个顺序才能让压缩与账号池同时生效。回环下两者之间不需要 key(ocx 默认回环绑定不读 token);非回环绑定按其文档设 `OPENCODEX_API_AUTH_TOKEN` + `x-opencodex-api-key` 头。请求模型时用 ocx 的 `provider/model` id 保证路由确定;和任何网关一样,路由后的 id 对 bili 的窗口查询不透明(用 `models.<name>.context` 声明),会话中途换账号会使前缀缓存失效(见 `/acp-cache` 的 KEY SWITCHES)。三条线(OpenAI Chat / Responses / Anthropic Messages)已端到端实测:bili 0.1.212 × ocx 2.97.0。
|
||||
|
||||
**日志和会话数据存在哪?** 日志:`~/.local/state/billion-context/bili.log`(同时镜像到 stderr);会话状态:`~/.local/share/billion-context/`(XDG 可覆盖;Windows 杀软排除 #362、可选清理 #1082)—— 完整路径见 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)。
|
||||
|
||||
## 运行代理
|
||||
|
||||
@@ -355,13 +352,13 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
|
||||
### 连接生命周期调优(#1982)
|
||||
|
||||
客户端侧连接在最终响应结束后优雅关闭:代理主动发起关闭(`Connection: close`)时,最多等待 `BILI_POST_RESPONSE_LINGER_MS`(默认 `5000`)毫秒的对端关闭信号才释放套接字,池化客户端因此看到的是干净的 EOF,而非字节竞态可能产生的 RST。相关旋钮:`BILI_KEEP_ALIVE_TIMEOUT_MS`(空闲回收预算,默认 `5000`)与 `BILI_CLIENT_ERROR_BACKSTOP_MS`(错误排空路径终局兜底,默认 `30000`)——完整语义见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。
|
||||
客户端侧连接在最终响应结束后优雅关闭:代理主动发起关闭(`Connection: close`)时,最多等待 `BILI_POST_RESPONSE_LINGER_MS`(默认 `5000`)毫秒的对端关闭信号才释放套接字,池化客户端因此看到的是干净的 EOF,而非字节竞态可能产生的 RST。相关旋钮:`BILI_KEEP_ALIVE_TIMEOUT_MS`(空闲回收预算,默认 `5000`)与 `BILI_CLIENT_ERROR_BACKSTOP_MS`(错误排空路径终局兜底,默认 `30000`)——完整语义见 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)。
|
||||
|
||||
### 自动更新
|
||||
|
||||
代理启动时和每 3 分钟检查 npm 是否有新版本。发现新版本就原位安装并打印通知 —— **重启 `bili` 才能生效**,除非启用可选自重启(`--auto-restart-on-update` 参数 / `ACP_AUTO_RESTART_ON_UPDATE=1` 环境变量 / 配置 `"autoRestartOnUpdate": true`,默认关闭):零在途请求时校验新安装、停止接收连接、排空、在同一端口拉起替代进程并在其开始接受连接后退出(客户端自动重连;会话状态在磁盘上保留)。安全门:排空窗口全程零在途、re-exec 前安装完整性检查、10 分钟冷却标记防止版本抖动循环重启;任何失败恢复原监听器并回落到普通提醒。运行进程落后于磁盘安装("stale")时,Web UI 显示横幅,`GET /__bili/status` 返回 `{version, diskVersion, stale, autoRestartOnUpdate, advisory, updatePolicy, inFlight}` 供脚本使用(`advisory` 为生效中的严重缺陷公告或 `null`,见下节;`updatePolicy` 上报 #3619 撒点状态——策略来源、`hold`/`pinned`/`blocked`、以及待执行的撒点升级及其到点时刻)。永久禁用:配置(`"autoUpdate": false`)或环境变量(`ACP_AUTO_UPDATE=0`)。
|
||||
|
||||
**升级撒点(#3619):** 发现新版本后,自动更新不再立即应用。每台实例在延迟窗口内随机抽取**一个**时刻(内置默认 **15 分钟 – 48 小时**),到点再升;抽中的时刻落盘持久化,重启不重摇。全量升级因此摊开在整个窗口内,而不是发版后十几分钟内全体升完,给坏发版留出中途拦截的响应窗(#3401/#3600/#3394)。窗口与紧急控制放在一个公开的策略文件里(本仓库的 `auto-update-policy.json`,匿名 GET + ETag 缓存):`hold` 全局冻结自动升级、`blocked` 跳过指定版本、`pinned` 设置升级天花板。按设计 fail-open——文件不可达或格式非法时直接回退本地默认;而且它只能调节奏/跳过/钉住,**永远控制不了装什么**。本机退出方式:手动 `bili update` 绕过 `hold`/撒点(但仍遵守 `blocked`/`pinned`)、`"staggerMinDelayMs": 0` + `"staggerMaxDelayMs": 0`(或 `BILI_UPDATE_STAGGER_MIN_MS`/`BILI_UPDATE_STAGGER_MAX_MS`)恢复旧版立即升级、`ACP_AUTO_UPDATE=0` 完全停用自动更新。完整格式与语义见 [CONFIGURATION.zh-CN.md → `update`](CONFIGURATION.zh-CN.md#update)。
|
||||
**升级撒点(#3619):** 发现新版本后,自动更新不再立即应用。每台实例在延迟窗口内随机抽取**一个**时刻(内置默认 **15 分钟 – 48 小时**),到点再升;抽中的时刻落盘持久化,重启不重摇。全量升级因此摊开在整个窗口内,而不是发版后十几分钟内全体升完,给坏发版留出中途拦截的响应窗(#3401/#3600/#3394)。窗口与紧急控制放在一个公开的策略文件里(本仓库的 `auto-update-policy.json`,匿名 GET + ETag 缓存):`hold` 全局冻结自动升级、`blocked` 跳过指定版本、`pinned` 设置升级天花板。按设计 fail-open——文件不可达或格式非法时直接回退本地默认;而且它只能调节奏/跳过/钉住,**永远控制不了装什么**。本机退出方式:手动 `bili update` 绕过 `hold`/撒点(但仍遵守 `blocked`/`pinned`)、`"staggerMinDelayMs": 0` + `"staggerMaxDelayMs": 0`(或 `BILI_UPDATE_STAGGER_MIN_MS`/`BILI_UPDATE_STAGGER_MAX_MS`)恢复旧版立即升级、`ACP_AUTO_UPDATE=0` 完全停用自动更新。完整格式与语义见 [docs/configuration.zh-CN.md → `update`](docs/configuration.zh-CN.md#update)。
|
||||
|
||||
**插件模式**(`bili opencode` / `bili pi` / `bili dsh` —— 代理内嵌在长驻宿主里运行时),"重启 bili"指的是重启**宿主**:内嵌进程无法自行退出,所以一直开着的宿主会持续运行它启动时的那份代码,默默地错过自动更新报告为"已安装"的每一处修复(#1603)。启用 `--auto-restart-on-update` 可让它在安全点自重启;或运行 `/acp`(当前仅 OpenCode 宿主,pi/dsh 覆盖见 #2084)—— 当磁盘安装领先于运行进程时,状态面板会追加一行过期警告(运行版本 vs 已安装版本)。若注入代码在运行期损坏(如 agent scope 被销毁),模型流量会静默直连(不压缩),直到宿主重启;自 #3581 起该状态可见:无会话运行时插件上报归属闸门降级,Web UI 显示「接管已失效」横幅,`GET /__bili/status` / `/__bili/overview` 暴露每代理的 `attribution` 状态。**按设计无归属**的后台车道(如 dsh 标题生成 sidecar)本身不携带 initiator,其小体量一次性请求按定义直连——按 #3651 契约这类正常拦截**永不报告**,因此永远不会触发横幅。横幅只在归属查询本身抛错(宿主内部错误,如 agent scope 被销毁)时出现,并给出可诊断信息:抛出的错误文本、脱敏后的端点、起始时间、已直连的请求数、解决方法(重启宿主进程),以及复制/提交诊断按钮(预填 GitHub issue)。
|
||||
|
||||
@@ -371,6 +368,12 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
|
||||
同样的有界重试现在也覆盖全局自更新代为驱动的 **owner 托管通道** —— dsh desktop 原位副本、dsh profile bundle 与 pi 的 npm 副本(#2192)。每条通道按「通道 + 目标版本」维护独立的失败计数,desktop 布局持续损坏时不再每周期重新下载整个 tarball(修复前每台受影响机器每天最多约 480 次下载);连续失败三次进入同样的指数冷却,一次性提示会指明出错的通道与手动修复方式(`dsh plugin --profile <name> add …`、`pi update --extension …`,或重建 desktop profile)。宿主托管实例另走更慢的独立检查节奏 —— 30 分钟加最多 15 分钟抖动,记在独立的节流标记里 —— 不再占用全局 3 分钟预算。失败计数通过缓存目录下的一个小状态文件(`.install-backoff.json`)在机器上所有 bili 进程间共享,多个运行中的实例不会各自烧掉独立的重试预算;`bili plugin update` 成功一次会立即解除 dsh profile 通道的冷却。该文件以原子方式写入(tmp+rename),且每次写入都与磁盘上已有内容合并,并发实例互相协作而不是覆盖彼此的计数;长驻进程会在文件变化时重新读取,任一副本执行的手动解除会在其它副本的下次检查时可见。它的一切失败模式都偏向重试 —— 损坏的文件或时钟跳跃会被丢弃,绝不允许长期沉默某条更新通道。`bili plugin update` 清除 dsh profile 通道的键;修复好的 desktop 通道则在下次成功的原位刷新时清除自己的键。
|
||||
|
||||
### 网络/VPN 切换后本地 DNS 陈旧(#5224)
|
||||
|
||||
**长驻**的独立代理在 WSL/VPN/TUN 拓扑变化后可能一直持有陈旧的 OS 解析器状态 —— 进程会缓存其系统解析器,而 libuv 的 `getaddrinfo` 不会自行重读 `/etc/resolv.conf`。症状:经 `/bili/` 隧道发出的每个模型请求都返回 HTTP 502 `tunnel_destination_denied`(detail `unresolvable`),尽管同一时刻新起的 `bili` 能正常解析同一主机、新 shell 里的 `curl` 也正常。两种解决办法任选其一即可清除:
|
||||
- **重启代理进程** —— 新进程会重读系统解析器。在 launcher 车道和 dsh web-profile 车道里,代理是一个**独立登记的**进程(instance registry),所以只重启客户端/宿主会从 registry 重新收养同一个楔死的代理,**不起作用** —— 必须停掉并重新启动代理本身。(内嵌插件模式下代理跑在宿主内部,重启宿主**能**清除。)
|
||||
- **让出口走上游代理** —— `-F http://<host:port>` 或 `BILI_UPSTREAM_PROXY=… BILI_UPSTREAM_PROXY_MODE=auto`:目标改由那个上游代理远端解析,bili 准入时不再查询自己(已陈旧的)解析器。
|
||||
|
||||
### 严重缺陷公告(强制更新)
|
||||
|
||||
独立于自动更新(#1481):即使关闭了 `autoUpdate`,代理也会按同样的 3 分钟节奏轮询一个小的伴生 npm 包(`billion-context-advisories`,由 CI 从本仓库的 [`advisories/`](advisories/) 目录发布)。每条公告指明受缺陷影响的版本范围(`affected`,semver)、应安装的确切版本(`target`,可以比当前版本**更旧**,即回滚),以及面向用户的缺陷说明(`reason`)。当本地版本落入 `affected` 范围时,bili 会走自更新的全套安全链路强制安装 `target`(跨进程锁、备份+校验+回滚;源码检出和宿主托管的安装会被拒绝并给出手动升级指引),并以警告方式呈现:
|
||||
@@ -379,12 +382,14 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
- Web UI 概览页横幅,显示原因与手动升级命令;
|
||||
- `GET /__bili/status` 在 `advisory` 字段返回生效中的公告。
|
||||
|
||||
该检查默认 fail-open:公告源不可达或格式错误只产生警告,绝不阻断模型流量。禁用方式:配置(`"advisoryCheck": false`)或环境变量(`BILI_ADVISORY_CHECK=0`);可用 `"advisoryUrl"` / `BILI_ADVISORY_URL` 指向自定义文档。
|
||||
该检查默认 fail-open:公告源不可达或格式错误只产生警告,绝不阻断模型流量。禁用方式:配置(`"advisoryCheck": false`)或环境变量(`BILI_ADVISORY_CHECK=0`);可用 `"advisoryUrl"` / `BILI_ADVISORY_URL` 指向自定义文档。**公告(Announcements)**(#5548)——与上面的关键缺陷公告是两回事:三个来源给 Web UI 提供横幅,相同 id 的覆盖顺序为**本地文件 > 远程源 > 内置**:(1)*内置*——一次性提示,直接走界面内置文案;(2)*本地*——把 JSON 文件放进配置目录的 `announcements/*.json`(默认 `~/.config/billion-context/announcements/`)即自动渲染:双语记录、按 kind 定色、npm 风格 `versions` 版本定向(`>=a.b.c`、`^`、`~`、`[lo hi]`、`||` 列表)、`percent` 灰度、时间窗、按类型排优先级——一个坏文件只废掉它自己;(3)*远程*——本仓库 master 分支的 [`announcements/remote.json`](announcements/remote.json)(每个 PR 都过 CI 校验),约每 3 分钟拉取一次,上一份有效公告的快照可跨重启/断网存活,坏推送会被拒绝;无法直连的环境用 `"remoteAnnouncementsUrl"` / `BILI_ANNOUNCEMENTS_URL` 指向同一文档的中继镜像。关闭行为按每条记录声明的模式:`persistent`(默认,按内容寻址——公告内容改动后会再提示一次)、`instance`(仅本进程)或 `always`(不显示关闭按钮)。关闭内置提示的记录按安装持久化在统一存储里(默认 SQLite,MySQL 后端同样可用),重启后不复发;旧的 `upgrade-notices.json` 状态文件只作为无统一存储边车(如显式加密 opt-out)的旧式安装的回退。官方源当前发布的是空条目列表。
|
||||
|
||||
|
||||
|
||||
## 配置
|
||||
|
||||
完整的配置参考 —— 配置文件位置、顶层键、providers、压缩调参、环境变量 ——
|
||||
见 **[CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)**。
|
||||
见 **[docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)**。
|
||||
|
||||
### 配置文件
|
||||
|
||||
@@ -392,7 +397,7 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
(`$XDG_CONFIG_HOME/billion-context/`;用 `BILI_CONFIG_FILE` 可改路径)。
|
||||
同一开关有多个来源时的优先级:**CLI 参数(如有)> 环境变量 > 配置文件 > 内置默认值** —— 每个环境变量都继续作为覆盖层可用。
|
||||
|
||||
里面有什么(细节见 CONFIGURATION.zh-CN.md):
|
||||
里面有什么(细节见 docs/configuration.zh-CN.md):
|
||||
|
||||
- `providers` —— 按 provider 的路由表:上游覆盖、模型上下文窗口、按 provider/模型的压缩调参、wire 协议声明、compaction opt-in。
|
||||
- `compress` —— 三级压缩调参(全局 → provider → 模型):阈值、nudge 节奏、保留规则、prompts、tiers。
|
||||
@@ -410,15 +415,15 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
|
||||
最常找的开关:
|
||||
|
||||
- **上游代理(防火墙/GFW)**—— 让代理自身出站流量走 v2rayA/clash:完整解析顺序、空字符串 = 显式直连、SOCKS5 拒绝、两条出站路径都覆盖,以及 `mitm://` vs `https://` 键 scheme 区分,都在 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)(服务端设置 → `proxy`;Providers → key schemes)。
|
||||
- **线上兼容角色改写(`compat.roles`)**—— 上游拒绝 `developer` 角色?[CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)(服务端设置 → `compat`)已覆盖 —— 包括零配置即用的失败自学习修复。
|
||||
- **签名上游(body 级签名)**—— 请求携带 body 级签名的网关(CodeArts APIG 的 `SDK-HMAC-SHA256`,或 `x-ofm-signature` 一类网关自造头):内置方案在 dsh 上透明重签;其他被形状检测识别出的方案**一律本地拒收** —— 签名请求要么重签+压缩、要么拒绝,绝不无签名放行 —— bili 在补上对应重签器前每次启动与 web UI 持续提醒(#1884/#2090)。检测规则、按方案覆盖、`BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_CODEARTS_REF` 见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)(服务端设置 → `resign`)。
|
||||
- **上游代理(防火墙/GFW)**—— 让代理自身出站流量走 v2rayA/clash:完整解析顺序、空字符串 = 显式直连、SOCKS5 拒绝、两条出站路径都覆盖,以及 `mitm://` vs `https://` 键 scheme 区分,都在 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)(服务端设置 → `proxy`;Providers → key schemes)。
|
||||
- **线上兼容角色改写(`compat.roles`)**—— 上游拒绝 `developer` 角色?[docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)(服务端设置 → `compat`)已覆盖 —— 包括零配置即用的失败自学习修复。
|
||||
- **签名上游(body 级签名)**—— 请求携带 body 级签名的网关(CodeArts APIG 的 `SDK-HMAC-SHA256`,或 `x-ofm-signature` 一类网关自造头):内置方案在 dsh 上透明重签;其他被形状检测识别出的方案**一律本地拒收** —— 签名请求要么重签+压缩、要么拒绝,绝不无签名放行 —— bili 在补上对应重签器前每次启动与 web UI 持续提醒(#1884/#2090)。检测规则、按方案覆盖、`BILI_RESIGN` / `BILI_RESIGN_PASSTHROUGH` / `BILI_CODEARTS_REF` 见 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)(服务端设置 → `resign`)。
|
||||
|
||||
### Pi 内置子代理
|
||||
|
||||
使用 `bili pi` 或 pi 原生插件(`bili plugin install pi`)时,会自带默认启用的子代理功能:`acp_delegate`、`acp_delegate_wait` 和 `acp_delegate_cancel`。这组额外工具仅在 pi 上提供。
|
||||
|
||||
**建议只启用一套子代理实现。** 如果使用内置功能,建议在用户级和项目级配置中移除或禁用其他 pi 子代理插件(例如 `pi-subagents` 或单独安装的 `billion-context-pi-subagents`),避免工具、提示词或行为重叠。如果更喜欢其他子代理插件,可以关闭内置功能。项目级 `pi-subagents` 安装默认会让内置 delegate 自动让位,但仅有用户级安装时不会,因此不能把这项保护当作所有安装方式都适用的保障。
|
||||
**建议只启用一套子代理实现。** 如果使用内置功能,建议在用户级和项目级配置中移除或禁用其他 pi 子代理插件(例如 `pi-subagents` 或单独安装的 `billion-context-pi-subagents`),避免工具、提示词或行为重叠。如果更喜欢其他子代理插件,可以关闭内置功能。`pi-subagents` 在任一作用域(项目级或用户级)的安装都会让内置 delegate 自动让位(#5637)——用户级安装在每个项目中都会加载,因此该保护同样适用;如需与其并存保留 `acp_delegate`,设置 `delegate.forceEnable`。
|
||||
|
||||
要关闭内置子代理并保留上下文压缩,请将以下配置合并到 `~/.config/billion-context/billion-context.json`(或 `BILI_CONFIG_FILE` 指定的文件),保留已有的其他设置:
|
||||
|
||||
@@ -430,7 +435,7 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
}
|
||||
```
|
||||
|
||||
重启 pi 并开启新会话后生效。该配置关闭三个 delegate 工具、配套的系统提示词和子代理管理界面的快捷键,上下文压缩仍然启用;单独安装的其他子代理插件不受此开关控制。更多选项见[子代理配置](CONFIGURATION.zh-CN.md#pi)。
|
||||
重启 pi 并开启新会话后生效。该配置关闭三个 delegate 工具、配套的系统提示词和子代理管理界面的快捷键,上下文压缩仍然启用;单独安装的其他子代理插件不受此开关控制。更多选项见[子代理配置](docs/configuration.zh-CN.md#pi)。
|
||||
|
||||
## 会话机制
|
||||
|
||||
@@ -446,11 +451,13 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
| **omp**(经插件)| ✅ 发 | `prompt_cache_key` 提升为稳定身份(#268)|
|
||||
| **pi**(裸跑)| ❌ 不发 | 无 → 见下方匿名前缀亲和 |
|
||||
|
||||
**omp 注意(#2583/#3556):** 较新的 OMP 构建中,默认 Anthropic(`anthropic-messages`)请求经 OMP 的 Cowork 传输以 node:https **直发** —— 到不了 bili 的 fetch 层,因此那条路径上 `prompt_cache_key` 打戳被*主动放弃*(打了戳反而会把字段泄漏进 Anthropic 严格 schema → HTTP 400)。自 #3556 起,`bili omp` launcher lane 默认不再留这个洞:除非你自己设置了 `PI_PROXY` / `PI_PROXY_ANTHROPIC`,launcher 会导出 `PI_PROXY_ANTHROPIC=<proxy>`,把 Cowork 推回 Bun 的 fetch、像其余 lane 一样经代理路由(可压缩、会话可见;打上的 key 由代理消费并剥离)。直连且匿名的行为只保留在 native omp 模式、以及你自己钉死代理姿态的 launcher lane;其余 omp 流量保持打戳身份。详见 [TECHNICAL-NOTES.zh-CN.md](TECHNICAL-NOTES.zh-CN.md)。
|
||||
**omp 注意(#2583/#3556):** 较新的 OMP 构建中,默认 Anthropic(`anthropic-messages`)请求经 OMP 的 Cowork 传输以 node:https **直发** —— 到不了 bili 的 fetch 层,因此那条路径上 `prompt_cache_key` 打戳被*主动放弃*(打了戳反而会把字段泄漏进 Anthropic 严格 schema → HTTP 400)。自 #3556 起,`bili omp` launcher lane 默认不再留这个洞:除非你自己设置了 `PI_PROXY` / `PI_PROXY_ANTHROPIC`,launcher 会导出 `PI_PROXY_ANTHROPIC=<proxy>`,把 Cowork 推回 Bun 的 fetch、像其余 lane 一样经代理路由(可压缩、会话可见;打上的 key 由代理消费并剥离)。直连且匿名的行为只保留在 native omp 模式、以及你自己钉死代理姿态的 launcher lane;其余 omp 流量保持打戳身份。详见 [docs/technical-notes.zh-CN.md](docs/technical-notes.zh-CN.md)。
|
||||
|
||||
**omp advisor 隔离(#5567):** omp 的持续后台流(例如跑在第二个模型上的 turn-reviewer *advisor*)是独立的模型对话,但它的 Chat Completions 请求不带自己的会话信号——插件会把主会话 id 盖进 `prompt_cache_key`,于是两条流落在**同一个** bili 会话里。两个模型/协议交错写入同一账本会把它弄坏:refs 变 DEAD(`cannot be anchored` / `content-changed`)、fold coverage 漂移、usage/window/nudge 计量在两条流之间串用(日志行 `foreign payload under a shared session id (#4805)` 标记了代理发现异常的位置)。在宿主侧身份修复落地之前(跟踪于 [#5567](https://github.com/ranxianglei/billion-context/issues/5567)),可以让 advisor 带上自己的身份出线来隔离它:在 omp 的模型注册配置(`models.yml` 的 `providers:` 段)里,给 advisor 所用 provider 条目设置 `compat.supportsPromptCacheKey: true` —— pi-ai 就会把 advisor 自己的会话 UUID 序列化为 `prompt_cache_key`,bili 据此把它绑到独立会话。边界:若 omp 显式为 advisor 传了共享缓存键则此法无效;隔离后 advisor 作为独立会话运行(有自己的压缩状态);可在 web 面板确认 advisor 流量出现在独立会话 id 下。
|
||||
|
||||
**无 header 客户端(pi 类):匿名前缀亲和。** 当客户端完全不发任何会话信号时,代理从重放的历史本身解析会话(`src/prefix-affinity.ts`,#309):只有当请求历史从第 0 条开始逐字节复现某已存会话的消息链时,才重新挂回该会话;否则获得一个确定性的新 `pfa-…` 会话。后果(#1262):**恢复(resume)** 的对话重新挂回自己的会话(包括代理重启后,#499);**开头相同的新任务不会继承**另一个会话的 block —— 它拿到全新会话,历史一旦分叉就彻底独立;完全没有任何可用信号时,请求会被显式 400 拒绝,而不是静默与他人状态碰撞。
|
||||
|
||||
设计记录与威胁模型:[SESSION-IDENTITY.md](SESSION-IDENTITY.md)。消息粒度的对偶文档(为什么身份由内容派生、而非指派 id)是 [MESSAGE-IDENTITY.zh-CN.md](MESSAGE-IDENTITY.zh-CN.md)。
|
||||
设计记录与威胁模型:[docs/session-identity.md](docs/session-identity.md)。消息粒度的对偶文档(为什么身份由内容派生、而非指派 id)是 [docs/message-identity.zh-CN.md](docs/message-identity.zh-CN.md)。
|
||||
|
||||
上游粘性路由方面,代理只转发客户端本来就提供的身份值(例如 body 里的 `session_id` 会以 `x-session-id` 上送),绝不自行合成一个。
|
||||
|
||||
@@ -458,15 +465,19 @@ bili --no-auto-update # 本次启动禁用自动更新
|
||||
|
||||
### 派生(子)会话继承父会话的压缩上下文(#1333、#1362)
|
||||
|
||||
当 agent 派生子会话(subagent 或 fork,从空历史起步、不重发父会话内容)时,它会在出生时上报这条血缘:身份注册携带父会话 id(`parentConversationId`),代理在子会话上记录一条只读链接(`derivedFrom`)。此后 `decompress` / `search_context` 对子会话自己从未见过的内容沿父链回退(带环检测、深度上限 8);任何东西都不复制进子会话,父会话也绝不被修改;父会话未知时子会话就按全新起步。各 lane 的父信号(pi/omp `parentSession` header、OpenCode V1/V2 `parentID`):[SESSION-IDENTITY.zh-CN.md](SESSION-IDENTITY.zh-CN.md#派生子会话出生时携带血统1333-1362)。claude/codex/dsh 在这里不需要任何信号:它们的子 agent 共享同一个会话 id,或根本没有子会话概念。
|
||||
当 agent 派生子会话(subagent 或 fork,从空历史起步、不重发父会话内容)时,它会在出生时上报这条血缘:身份注册携带父会话 id(`parentConversationId`),代理在子会话上记录一条只读链接(`derivedFrom`)。此后 `decompress` / `search_context` 对子会话自己从未见过的内容沿父链回退(带环检测、深度上限 8);任何东西都不复制进子会话,父会话也绝不被修改;父会话未知时子会话就按全新起步。各 lane 的父信号(pi/omp `parentSession` header、OpenCode V1/V2 `parentID`):[docs/session-identity.zh-CN.md](docs/session-identity.zh-CN.md#派生子会话出生时携带血统1333-1362)。claude/codex/dsh 在这里不需要任何信号:它们的子 agent 共享同一个会话 id,或根本没有子会话概念。
|
||||
|
||||
### Windows:把会话目录加入杀软排除项(#362)
|
||||
|
||||
代理把每个会话的压缩状态持久化到会话目录(默认 `%USERPROFILE%\.local\share\billion-context\`),长会话每一轮都会重写该文件。在 Windows 上,实时杀毒(Defender)、搜索索引器或同步工具(OneDrive)可能在写入中途锁住该目录,导致 rename 以 `EPERM` 失败。同一会话连续 N 次写失败(默认 `5`)时,代理打一条一次性可操作告警,指明要排除的目录。根上修复:把 `%USERPROFILE%\.local\share\billion-context\` 加入杀软**排除项**,并确认没有同步工具在同步该路径 —— 完整步骤见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md) 的「Windows:把会话目录加入杀软排除项」章节。同一排除项也覆盖统一存储 `index.db` 打不开(`unable to open database file`,#3823)——存储降级告警会把它列为第一嫌疑。
|
||||
代理把每个会话的压缩状态持久化到会话目录(默认 `%USERPROFILE%\.local\share\billion-context\`),长会话每一轮都会重写该文件。在 Windows 上,实时杀毒(Defender)、搜索索引器或同步工具(OneDrive)可能在写入中途锁住该目录,导致 rename 以 `EPERM` 失败。同一会话连续 N 次写失败(默认 `5`)时,代理打一条一次性可操作告警,指明要排除的目录。根上修复:把 `%USERPROFILE%\.local\share\billion-context\` 加入杀软**排除项**,并确认没有同步工具在同步该路径 —— 完整步骤见 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md) 的「Windows:把会话目录加入杀软排除项」章节。同一排除项也覆盖统一存储 `index.db` 打不开(`unable to open database file`,#3823)——存储降级告警会把它列为第一嫌疑。
|
||||
|
||||
### 单机多安装共存(#5046)
|
||||
|
||||
同一台机器上装了**两份及以上** bili(例如两个 DSH profile——桌面端 + bot,或全局 npm 拷贝与宿主树拷贝并存)时,各自的代理默认都解析到**同一个** XDG 会话目录(`%USERPROFILE%\.local\share\billion-context\sessions\`)和同一份配置文件。开了统一存储(`storage.unified` = shadow/full)后,两个进程会双写同一个 `index.db`:日志出现 `[instances] another bili instance is running …`,lane 重叠时还有 `[storage] … two processes on one index.db corrupt it` 级别的 error;SQLite 写锁争用(`SQLITE_BUSY` / `database is locked`)会让整轮模型请求直接失败,持续双写还有损坏风险。正确做法是**隔离**:给每份安装设独立的 `BILI_SESSIONS_DIR`(配置也要分开时再加 `BILI_CONFIG_FILE`),只加在该安装自己的启动器/profile 环境变量里,不动全局环境。隔离后两份可正常并存,`[instances]` 提示会自动降为 info 级(目录不同 ⇒ 无共享状态)。
|
||||
|
||||
### 会话文件清理(#1082)
|
||||
|
||||
短命会话会留下永远不会再被恢复的小状态文件。清理是**可选开启(opt-in)**的:设 `BILI_SESSION_GC=1` 才启用(默认关闭 —— 会话文件属于用户数据,不应有静默删除策略)。启用且持久化开启时,bili 在启动时和每小时扫描会话目录,只有**两个条件同时满足**才删除一个文件:年龄超过 `BILI_SESSION_GC_MAX_AGE_DAYS`(默认 7 天),并且该会话**从未被压缩过**(没有折叠块)、最近一次请求体 ≤ `BILI_SESSION_GC_MAX_TOKENS` token(默认 1M)—— 删除只丢字节不丢内容。CCR 内容存储遵循其会话文件的生命周期;被压缩过的会话永不删除;每次删除都写审计日志。详见 [CONFIGURATION.zh-CN.md](CONFIGURATION.zh-CN.md)。
|
||||
短命会话会留下永远不会再被恢复的小状态文件。清理是**可选开启(opt-in)**的:设 `BILI_SESSION_GC=1` 才启用(默认关闭 —— 会话文件属于用户数据,不应有静默删除策略)。启用且持久化开启时,bili 在启动时和每小时扫描会话目录,只有**两个条件同时满足**才删除一个文件:年龄超过 `BILI_SESSION_GC_MAX_AGE_DAYS`(默认 7 天),并且该会话**从未被压缩过**(没有折叠块)、最近一次请求体 ≤ `BILI_SESSION_GC_MAX_TOKENS` token(默认 1M)—— 删除只丢字节不丢内容。CCR 内容存储遵循其会话文件的生命周期;被压缩过的会话永不删除;每次删除都写审计日志。详见 [docs/configuration.zh-CN.md](docs/configuration.zh-CN.md)。
|
||||
|
||||
### 存储维护 CLI(#3928)
|
||||
|
||||
@@ -483,6 +494,8 @@ bili storage gc [--days N] [--vacuum full|incremental] [--dry-run]
|
||||
|
||||
`archive`/`restore`/`gc` 需要统一存储(`BILI_STORAGE_UNIFIED=shadow|full` 或配置文件里的 `storage.unified`)—— legacy-only 安装会拒绝并给出提示。`--days` 默认取 `storage.archiveAfterDays`(365)。没有调度器:全部按需运行。所有命令都支持 `--json`。
|
||||
|
||||
**大库上 full vacuum 是离线操作(#4612)。** `--vacuum full`(默认)会在独占写锁下重写整个 index.db —— O(库大小),多 GB 的库要几分钟到几十分钟,且没有中间进度(SQLite 的 VACUUM 是原子操作,拆不开)。在有代理正从同一会话目录服务时跑它,会把那个代理的写入饿死到其存储层降级为止,所以 `storage gc --vacuum full` **在另一个存活进程持有该数据库时会拒绝启动**(`index.db.lock` pid 纪律,#4175):CLI 以退出码 1 给出可操作提示,面板端点返回 HTTP 409。先停掉另一个实例(或等它退出)再重试;要在线安全地缩库用 `--vacuum incremental`,它以短事务回收空闲页、不拿独占锁。零引用删除清扫无论哪种模式都分批执行并逐批打印进度。
|
||||
|
||||
## 状态
|
||||
|
||||
早期。协议处理和压缩已通过 mock 测试(500+ 项通过)。真实模型集成测试是下一里程碑。预期会有粗糙的地方。
|
||||
|
||||
@@ -1,268 +1 @@
|
||||
# Session identity for anonymous requests
|
||||
|
||||
Design record for how billion-context decides which session an **anonymous**
|
||||
request (no `session_id` header or body field, no `prompt_cache_key`) belongs
|
||||
to. Written as future reference after the tail-window reattach removal
|
||||
(#1115), and after the wire-neutral canonical projection (#2791).
|
||||
Implementation: `src/prefix-affinity.ts`, `src/affinity-neutral.ts`;
|
||||
behavior tests:
|
||||
`tests/truncation-fork.test.ts`, `tests/prefix-affinity.test.ts`,
|
||||
`tests/affinity-neutral.test.ts`.
|
||||
|
||||
## Principle: content is the only immutable anchor
|
||||
|
||||
Client-provided ids are honored verbatim. Partitioning sessions by anything the
|
||||
client can rotate — credentials, relays, protocol translation — orphans state
|
||||
exactly when the user keeps talking (the #286 lesson). For requests that carry
|
||||
no id at all, the message content is the only stable thing both sides share, so
|
||||
affinity is computed purely from the replayed history.
|
||||
|
||||
Two consequences follow:
|
||||
|
||||
- **Environment is out of identity.** System prompts, tool definitions, and
|
||||
model names never enter the hash. Summaries describe past turns under an
|
||||
earlier environment; including the environment would orphan every session
|
||||
whose harness rotates its prompt (common practice), defeating the mechanism.
|
||||
- **Byte-exactness is load-bearing.** Message ids inside the kernel are
|
||||
content hashes and are never reused. Any near-match tolerance in this path
|
||||
would silently misattribute on decompress, so matching is always byte-exact.
|
||||
The only design freedom is *where* evidence may be sought — never *how much*.
|
||||
|
||||
## Full-prefix match — the only adoption path
|
||||
|
||||
Each tracked chain stores progressive hashes
|
||||
`h_i = sha256(h_{i-1} || canon(msg_i))`. An incoming request matches when its
|
||||
progressive hashes equal a stored chain's **head** for the longest strict
|
||||
prefix (`via: "prefix"`). This is sound:
|
||||
|
||||
- Identity evidence is the entire shared head, anchored at position 0 — a
|
||||
different conversation cannot quote position 0 of yours without holding your
|
||||
actual opening turns.
|
||||
- Divergence self-heals (fork semantics, #286): once a client edits or branches
|
||||
its history, the next request stops matching and mints a fresh session while
|
||||
the old chain keeps serving the unedited line. No explicit invalidation is
|
||||
needed.
|
||||
- Safety: matching requires holding a byte-identical head, so folded state
|
||||
reveals nothing the requester does not already hold.
|
||||
|
||||
## Tail-window reattach — history and removal (#316 → #1072 → #1115)
|
||||
|
||||
### The problem it solved
|
||||
|
||||
A client that TRUNCATES its replayed history (drop-oldest, rolling window) no
|
||||
longer matches from the head. Without reattach it would mint a fresh session on
|
||||
every turn after the first truncation and never build a compression ladder.
|
||||
Observed target class: dsh-style web clients retaining a rolling window of
|
||||
20–30 items.
|
||||
|
||||
### The mechanism (removed)
|
||||
|
||||
The resolver slid the incoming's leading `w = min(8, depth)` per-item hashes
|
||||
against **any mid-chain offset** of every tracked chain and adopted the stored
|
||||
session on exactly one contiguous hit (`via: "tail-window"`).
|
||||
|
||||
### Why it was structurally weak
|
||||
|
||||
A mid-chain contiguous match is **symmetric evidence**: it cannot distinguish
|
||||
|
||||
- "same conversation, truncated replay" (the intended case) from
|
||||
- "a different conversation quoting shared content" — templated tool outputs,
|
||||
standard file contents, stock error messages.
|
||||
|
||||
No attacker is required for the second case: parallel agents working the same
|
||||
codebase produce identical mid-chain slices naturally (passive template
|
||||
collision). And adoption was bidirectionally harmful either way:
|
||||
|
||||
- the adopter's rebuilt wire received the victim session's folded summary
|
||||
blocks (information leak across conversations);
|
||||
- the adopter's new turns were recorded into the victim's session (context
|
||||
pollution for the real owner).
|
||||
|
||||
The interim mitigation (#1072) required the full 8-item window instead of 3,
|
||||
closing sub-8 crafted windows — but a bigger threshold does not break the
|
||||
symmetry: holding any 8 contiguous mid-chain items was still sufficient.
|
||||
|
||||
### Measurement before removal
|
||||
|
||||
Three days of production logs on this daemon's deployment (2026-09-19 →
|
||||
2026-09-22), ~11.5k anonymous resolutions:
|
||||
|
||||
| Outcome | Count |
|
||||
|---|---|
|
||||
| full-prefix match | 9,367 |
|
||||
| new session | 2,106 |
|
||||
| fork lineage recorded | 142 |
|
||||
| **tail-window reattach** | **0** |
|
||||
| ambiguous multi-candidate tail hit | 0 |
|
||||
|
||||
Zero observed usage — including zero near-misses.
|
||||
|
||||
### Decision: drop mid-chain adoption entirely (direction 3 of #1115)
|
||||
|
||||
Truncated replays now fork into a fresh session (`via: "new"`). Cost accepted:
|
||||
one raw resend plus a ladder restart — the same cost class instruction-drift
|
||||
forks already accept (#1106). Two mitigations bound the loss:
|
||||
|
||||
- **Opt-in block adoption (#629)** carries compression blocks whose source
|
||||
messages remain fully present in the incoming replay (raw-id SET semantics,
|
||||
not prefix lineage).
|
||||
- **Kernel reconciliation stays sound**: a truncated replay deactivates
|
||||
affected blocks gracefully, and a full replay revives them (pinned in
|
||||
`tests/truncation-fork.test.ts`).
|
||||
|
||||
The truncated-run scan survives in attribution form only: a NEW session whose
|
||||
leading `TRUNCATION_LINEAGE_WINDOW = 8` run sits strictly inside (offset ≥ 1) a
|
||||
tracked chain records `lineage: { reason: "truncated", parents }`; a shared
|
||||
leading prefix (LCP ≥ `MIN_FORK_PREFIX = 3`) records `reason: "forked"` instead
|
||||
and takes precedence. Lineage is logged and stored for UI/debug and **never
|
||||
affects matching**.
|
||||
|
||||
## Wire-neutral canonical projection (#2791)
|
||||
|
||||
### The cross-wire blind spot
|
||||
|
||||
The progressive hash above was computed over the **raw wire JSON** of each
|
||||
message. Two renders of the *same conversation* on different protocols are
|
||||
never byte-equal — an OpenAI wire renders tool activity as
|
||||
`{role:"assistant", content:null, tool_calls:[{function:{name, arguments:"…json string…"}}]}`
|
||||
plus `{role:"tool", tool_call_id, content}`, while the Anthropic wire renders
|
||||
it as assistant content blocks `[{type:"thinking"}, {type:"tool_use", name,
|
||||
input:{…}}]` plus `tool_result` blocks nested inside the next user message. A
|
||||
dsh session that switches `api` (`openai-completions` → `anthropic-messages`,
|
||||
same conversation, same upstream models) therefore matched nothing, minted a
|
||||
fresh anonymous session, orphaned its fold ledger, and paid a full re-fold
|
||||
(~182 s) plus a cache reset on the switch turn — silently (#2791).
|
||||
|
||||
### The projection
|
||||
|
||||
Hashing now runs on a protocol-neutral projection (`src/affinity-neutral.ts`):
|
||||
each message is normalized to a `NeutralTurn` (`{kind, text}` or
|
||||
`{kind, calls}`) under rules that are injective enough for hashing while
|
||||
dropping wire decoration:
|
||||
|
||||
- leading system/developer run stripped (top-level `system` param never
|
||||
entered the projection);
|
||||
- text content: string ↔ `[{type:"text"}]` blocks concatenated;
|
||||
- tool activity: `tool_calls[].function.arguments` (JSON *string*) and
|
||||
`tool_use[].input` (object) both canonicalized to the parsed value;
|
||||
`{role:"tool", tool_call_id}` ↔ user `tool_result` blocks become a synthetic
|
||||
`{kind:"tool"}` turn (multi-`tool_result` user messages split);
|
||||
- assistant turns carrying tool calls drop their text (the two wires
|
||||
disagree on whether thinking accompanies a tool call);
|
||||
- consecutive assistant messages merge (Anthropic splits them);
|
||||
- client `[model changed: …]` marker turns and churn keys
|
||||
(`cache_control`, ids, signatures) are dropped;
|
||||
- unknown shapes fall back to the raw canonical of the whole message —
|
||||
matching degrades to v1 behavior, never to false matches.
|
||||
|
||||
The per-turn canonical string is `canon({content, role})` — byte-identical
|
||||
to the v1 canonical of a plain OpenAI text message, so the #2265 simhash
|
||||
hamming calibration carries over unchanged (model re-stamp mutations stay
|
||||
inside the adoptable band; verified `coverage ≥ 0.9` on the original
|
||||
fixtures).
|
||||
|
||||
### Storage and migration
|
||||
|
||||
`ChainEntry.hv` distinguishes domains: `hv:2` entries carry neutral
|
||||
per-item hashes and simhash sketches; pre-upgrade `hv:1` entries remain
|
||||
readable and matchable (raw-wire domain, including the legacy churn-tolerant
|
||||
tail hash), so upgrading does **not** re-mint every tracked session — the
|
||||
mass-fork cost is paid only where a conversation actually crosses wires,
|
||||
which is exactly the case that previously forked anyway. Simhash adoption
|
||||
and lineage rungs operate per-domain (`hv:2` only for adoption), and the
|
||||
client-provided append-only guard re-anchors `hv:1` entries unconditionally
|
||||
(depth is only comparable within a domain).
|
||||
|
||||
### Live evidence
|
||||
|
||||
Fresh dsh session, 45 KB knowledge file read on the `openai-completions`
|
||||
lane (fold fired: ~13.5 k tokens saved), then the same dsh session switched
|
||||
to `anthropic-messages` and quizzed on folded content: the anthropic
|
||||
request matched the openai-lane session at prefix depth 9/11, no new
|
||||
anonymous session, no re-fold, answers served from the fold summary, cache
|
||||
hit 97 % within two rounds. Captures and log in the #2791 thread.
|
||||
|
||||
## Snapshot render: the session id becomes the whole message identity (#3756)
|
||||
|
||||
The anonymous-adoption ladder above exists because the wire bytes were the
|
||||
only record of an unauthenticated conversation. For sessions with a bound
|
||||
id (host-native session header or affinity key) and unified storage
|
||||
available, #3756 closes the loop: the OUTBOUND history prefix is rendered
|
||||
from the server's own transcript keyed by that session id
|
||||
(`src/server/snapshot-render.ts`, rollout feature `snapshotRender`, default
|
||||
0%). Message identity for the rendered prefix is the server row `seq` —
|
||||
content hashes demote to chain-fallback evidence that only locates where
|
||||
the client's verbatim tail joins the server prefix. Client edits, host
|
||||
checkpoints and protocol switches can no longer move, drop or duplicate
|
||||
folded coverage, because coverage is computed from the block's seq/
|
||||
signature sets, not from what the client happens to resend. The
|
||||
adoption ladder above remains the fallback for the lanes where the feature
|
||||
is off, the storage is unavailable, or the chain cannot link — degrade,
|
||||
never guess. Full mechanism and honesty boundaries:
|
||||
`MESSAGE-IDENTITY.md` §"The snapshot render engine".
|
||||
|
||||
## Rejected alternatives
|
||||
|
||||
| Direction | Why rejected |
|
||||
|---|---|
|
||||
| Suffix-anchored matching (match must end at the stored tail) | Works only when the client retains exactly the window length (K = 8). Documented rolling windows retain 20–30 items — the dominant legit case breaks. |
|
||||
| Depth-scaled evidence (window must cover ≥ 50% of the stored chain) | A fixed 8-item window cannot cover half of any chain deeper than 16 items — kills long conversations, exactly the ones worth keeping. |
|
||||
| Kernel-verified adoption (cross-check against the full kernel id chain) | Kernel ids are content hashes: the same symmetric evidence extended to greater depth. More precision, still no ownership proof; adds a session lookup to the anonymous hot path. |
|
||||
| Tail-anchored longest-run + floor (dir 1+ variant) | Sound and preserves the feature. Declined *for now* because measured usage was zero; reconsider alongside a client-side identity signal rather than shipping speculative surface. |
|
||||
|
||||
## Three-layer identity framework
|
||||
|
||||
Continuity under mutation decomposes into three independent layers. The unit
|
||||
of truth is the BLOCK, not the session — continuity is partial by
|
||||
construction:
|
||||
|
||||
1. **Attach** — which stored chain a request belongs to. Evidence comes from
|
||||
what the client demonstrably holds; after #1115 only head-anchored
|
||||
full-prefix matches count.
|
||||
2. **Block validity** — per-block, decided by the kernel from message-id
|
||||
PRESENCE (not position): covered messages missing ⇒ the block deactivates;
|
||||
they return ⇒ it revives. "Half a session" is the mechanical outcome of
|
||||
this layer, not a policy knob.
|
||||
3. **Environment** — system prompt / tools / model are out of identity (see
|
||||
principle above). A changed environment changes future turns, not the truth
|
||||
of past summaries.
|
||||
|
||||
## Derived (child) sessions: lineage at birth (#1333, #1362)
|
||||
|
||||
When an agent spawns a child session — a subagent or fork that starts from an
|
||||
empty history instead of resending the parent's conversation — that child
|
||||
could not previously `decompress` or `search_context` content that was folded
|
||||
away in the parent. Each lane now reports the lineage at birth: its identity
|
||||
registration carries the parent's conversation id (`parentConversationId`),
|
||||
and the proxy records a read-only link (`derivedFrom`) on the child session.
|
||||
From then on:
|
||||
|
||||
- `decompress` / `search_context` fall back along the parent chain for
|
||||
content the child never saw itself (resident or on-disk parents,
|
||||
cycle-guarded, depth cap 8);
|
||||
- nothing is copied into the child's state and the parent is never modified —
|
||||
fallback hits are read-only, so a child can never clobber what the parent
|
||||
still owns;
|
||||
- if the parent is unknown to the proxy when the link is recorded, the child
|
||||
simply starts fresh.
|
||||
|
||||
| Lane | Parent signal |
|
||||
|---|---|
|
||||
| **pi** RLM inline spawn | `parentSession` in the session header (path to the parent session file, resolved to its session id) |
|
||||
| **omp** fork / newSession | `parentSession` in the session header (bare session id or file path — both accepted) |
|
||||
| **OpenCode V1** (native plugin) | SDK session info `parentID` (resolved once per session, cached) |
|
||||
| **OpenCode V2** (native plugin) | `session.created` event `data.parentID` |
|
||||
|
||||
claude/codex/dsh need nothing here: they share one session id across
|
||||
subagents or have no child-session concept at all.
|
||||
|
||||
## Future direction
|
||||
|
||||
The durable fix is a **client-side identity signal**: a stable
|
||||
per-conversation id supplied by the client itself. Until clients provide one,
|
||||
byte-exact head-anchored matching remains the safe floor, and any
|
||||
reintroduction of suffix/mid-chain adoption must be justified against this
|
||||
document's threat model first.
|
||||
|
||||
Related: #1148 (an OpenAI inline `messages[0]` system prompt bakes into
|
||||
identity, asymmetric with other protocols — separate issue).
|
||||
> Moved to [docs/session-identity.md](docs/session-identity.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -1,154 +1 @@
|
||||
# 匿名请求的会话身份判定
|
||||
|
||||
设计记录:billion-context 如何判定一个**匿名**请求(无 `session_id` 头或 body
|
||||
字段、无 `prompt_cache_key`)属于哪个会话。在 tail-window reattach 移除(#1115)
|
||||
之后撰写,作为未来参考。实现:`src/prefix-affinity.ts`;行为测试:
|
||||
`tests/truncation-fork.test.ts`、`tests/prefix-affinity.test.ts`。
|
||||
|
||||
## 原则:内容是唯一不可变的锚点
|
||||
|
||||
客户端自带的 id 原样采信。按任何客户端可轮换的东西(凭据、中继、协议转换)
|
||||
划分会话,会在用户继续对话时恰好把状态弄丢(#286 的教训)。对完全不带 id 的
|
||||
请求,消息内容是双方共享的唯一稳定物,因此亲和性完全由重放的历史计算得出。
|
||||
|
||||
由此推出两条推论:
|
||||
|
||||
- **环境不进身份。** 系统提示词、工具定义、模型名从不进入哈希。摘要描述的是
|
||||
更早环境下发生的历史轮次;把环境算进去,会让所有 harness 轮换 prompt 的
|
||||
会话(常见做法)全部断档,机制本身失效。
|
||||
- **字节精确是承重墙。** kernel 内部的消息 id 是内容哈希且永不复用。这条路径
|
||||
上任何"近似匹配"容忍度都会在 decompress 时静默错配,所以匹配永远字节精确。
|
||||
唯一的设计自由度是*去哪里找证据*——而不是*要求多少证据*。
|
||||
|
||||
## 全前缀匹配 —— 唯一的采纳路径
|
||||
|
||||
每条被跟踪的链存储渐进哈希 `h_i = sha256(h_{i-1} || canon(msg_i))`。当来请
|
||||
求的渐进哈希与某条存储链的**头部**在最长严格前缀上相等时命中(`via:
|
||||
"prefix"`)。这是可靠的:
|
||||
|
||||
- 身份证据是整个共享头部,锚定在第 0 位——别的对话不可能在不持有你真实开场
|
||||
轮次的情况下引用你的第 0 位。
|
||||
- 分叉自愈(fork 语义,#286):客户端一旦编辑或分叉历史,下一次请求即停止命
|
||||
中并铸造新会话,旧链继续服务未编辑的那条线。无需显式失效。
|
||||
- 安全性:命中必须持有字节一致的头部,因此折叠状态不会泄露请求者尚未持有的
|
||||
任何东西。
|
||||
|
||||
## Tail-window reattach —— 历史与移除(#316 → #1072 → #1115)
|
||||
|
||||
### 它解决的问题
|
||||
|
||||
截断重放历史(丢最旧、滚动窗口)的客户端不再能从头部匹配。没有 reattach,它
|
||||
会在首次截断后的每一轮都铸造新会话,压缩阶梯永远建不起来。观察到的目标类
|
||||
型:dsh 风格 web 客户端保留 20–30 条的滚动窗口。
|
||||
|
||||
### 被移除的机制
|
||||
|
||||
解析器把来请求的前导 `w = min(8, depth)` 个逐条哈希,对每条被跟踪链的**任意
|
||||
链中偏移**做滑动比对,恰好一处连续命中即采纳该存储会话(`via:
|
||||
"tail-window"`)。
|
||||
|
||||
### 为什么它在结构上脆弱
|
||||
|
||||
链中连续命中是**对称证据**,无法区分:
|
||||
|
||||
- "同一对话,截断重放"(预期场景),与
|
||||
- "另一段对话引用了共享内容"——模板化工具输出、标准文件内容、常见报错文案。
|
||||
|
||||
第二种情形不需要攻击者:并行处理同一代码库的多个 agent 会自然产生相同的链中
|
||||
切片(被动模板碰撞)。而且无论哪种情形,采纳都是双向有害的:
|
||||
|
||||
- 采纳方重建的 wire 会收到受害会话的折叠摘要块(跨对话信息泄露);
|
||||
- 采纳方的新轮次被记入受害会话(对真正主人的上下文污染)。
|
||||
|
||||
临时缓解(#1072)把窗口从 3 提高到完整 8 条,关掉了 sub-8 构造窗口——但更大
|
||||
的阈值并不打破对称性:持有任意 8 条连续链中切片仍然足够。
|
||||
|
||||
### 移除前的测量
|
||||
|
||||
本 daemon 部署 3 天生产日志(2026-09-19 → 2026-09-22),约 1.15 万次匿名解析:
|
||||
|
||||
| 结果 | 次数 |
|
||||
|---|---|
|
||||
| 全前缀命中 | 9,367 |
|
||||
| 新会话 | 2,106 |
|
||||
| 记录 fork lineage | 142 |
|
||||
| **tail-window reattach** | **0** |
|
||||
| 多候选歧义尾部命中 | 0 |
|
||||
|
||||
零使用——连近似命中都没有。
|
||||
|
||||
### 决定:彻底移除链中采纳(#1115 方向 3)
|
||||
|
||||
截断重放现在 fork 出新会话(`via: "new"`)。接受的成本:一次原始重发加阶梯重
|
||||
启——与指令漂移 fork 已接受的同一成本级别(#1106)。两个缓解限定损失:
|
||||
|
||||
- **可选块采纳(#629)** 携带源消息在来请求中仍完整存在的压缩块(raw-id 集合
|
||||
语义,而非前缀血统)。
|
||||
- **kernel 协调保持可靠**:截断重放优雅地停用受影响块,完整重放使其复活
|
||||
(`tests/truncation-fork.test.ts` 固化)。
|
||||
|
||||
截断扫描仅以归因形式保留:新会话若其前导 `TRUNCATION_LINEAGE_WINDOW = 8` 条
|
||||
连续运行严格位于(offset ≥ 1)某条被跟踪链内部,记录 `lineage: { reason:
|
||||
"truncated", parents }`;若与某链共享前导前缀(LCP ≥ `MIN_FORK_PREFIX = 3`)则
|
||||
记录 `reason: "forked"` 并优先。lineage 只用于日志/UI/调试,**永不参与匹
|
||||
配**。
|
||||
|
||||
## 被否决的替代方案
|
||||
|
||||
| 方向 | 否决理由 |
|
||||
|---|---|
|
||||
| 后缀锚定匹配(命中必须结束于存储链尾部) | 仅在客户端恰好保留窗口长度(K = 8)时成立。文档记载的滚动窗口保留 20–30 条——主流合法场景直接断裂。 |
|
||||
| 深度缩放证据(窗口须覆盖存储链 ≥ 50%) | 固定 8 条窗口无法覆盖超过 16 条深度的链的一半——杀掉长对话,恰恰是最值得保留的那些。 |
|
||||
| kernel 校验采纳(对照完整 kernel id 链交叉验证) | kernel id 是内容哈希:同样的对称证据,只是延伸到更大深度。精度更高,仍非所有权证明;还给匿名热路径增加一次会话查找。 |
|
||||
| 尾部锚定最长运行 + 下限(dir 1+ 变体) | 可靠且保留功能。因实测零使用而*暂不*采用;待客户端侧身份信号出现后一并重新考虑,不先上投机性接口。 |
|
||||
|
||||
## 三层身份框架
|
||||
|
||||
变更下的连续性分解为三个独立层。真值单元是**块**而非会话——连续性天生是部
|
||||
分的:
|
||||
|
||||
1. **附着(Attach)**——请求属于哪条存储链。证据来自客户端可证明持有的东西;
|
||||
#1115 之后只有头部锚定的全前缀命中算数。
|
||||
2. **块有效性(Block validity)**——逐块由 kernel 依据消息 id **存在性**(而非
|
||||
位置)判定:被覆盖消息缺失 ⇒ 块停用;它们回来 ⇒ 块复活。"半个会话"是这
|
||||
一层的机械结果,不是策略旋钮。
|
||||
3. **环境(Environment)**——系统提示词/工具/模型不进身份(见原则)。环境变化
|
||||
改变的是未来轮次,不是历史摘要的真值。
|
||||
|
||||
## 快照渲染:session id 升格为完整的消息身份(#3756)
|
||||
|
||||
上面的匿名认领阶梯之所以存在,是因为 wire 字节曾是无凭证会话的唯一记录。对于
|
||||
已绑定 id 的会话(宿主原生 session 头或亲和键)且统一存储可读时,#3756 闭合了
|
||||
这个环:**出站历史前缀直接由该 session id 键下的服务端正史渲染**
|
||||
(`src/server/snapshot-render.ts`,灰度开关 `snapshotRender`,默认 0%)。渲染前缀
|
||||
的消息身份 = 服务端行 `seq`——内容 hash 降级为链回溯兜底证据,只用于定位「客户
|
||||
端逐字尾巴在何处让位给服务端前缀」。客户端编辑、宿主 checkpoint、协议切换都不
|
||||
再能移动/丢失/复制折叠覆盖:覆盖由块的 seq/签名集合计算,不再取决于客户端恰好
|
||||
重发了什么。上述认领阶梯仍是该特性关闭、存储不可用或链不上时的回退路径——降
|
||||
级,不猜。完整机制与诚实边界见 `MESSAGE-IDENTITY.md` §「快照渲染引擎」。
|
||||
|
||||
## 派生(子)会话:出生时携带血统(#1333, #1362)
|
||||
|
||||
当 agent 派生子会话——从空历史起步、而不是重发父会话对话的 subagent 或 fork——此前它无法 `decompress` / `search_context` 父会话里已被折叠的内容。现在每条 lane 在出生时报告血统:身份注册携带父会话 id(`parentConversationId`),代理在子会话上记录一条只读链接(`derivedFrom`)。此后:
|
||||
|
||||
- `decompress` / `search_context` 对子会话自身从未见过的内容沿父链回退(父会话驻留内存或落盘均可,带环保护,深度上限 8);
|
||||
- 不向子会话状态复制任何东西,父会话也绝不被修改——回退命中是只读的,子会话不可能覆盖父会话仍拥有的内容;
|
||||
- 若记录链接时代理不认识该父会话,子会话就只是从零开始。
|
||||
|
||||
| Lane | 父信号 |
|
||||
|---|---|
|
||||
| **pi** RLM inline spawn | 会话头里的 `parentSession`(父会话文件路径,解析为其会话 id) |
|
||||
| **omp** fork / newSession | 会话头里的 `parentSession`(裸会话 id 或文件路径——两者都接受) |
|
||||
| **OpenCode V1**(原生插件) | SDK session info 的 `parentID`(每会话解析一次并缓存) |
|
||||
| **OpenCode V2**(原生插件) | `session.created` 事件的 `data.parentID` |
|
||||
|
||||
claude/codex/dsh 在这里不需要任何信号:它们的 subagent 共享同一个会话 id,或根本没有子会话概念。
|
||||
|
||||
## 未来方向
|
||||
|
||||
持久的修复是**客户端侧身份信号**:由客户端自身提供的稳定 per-conversation
|
||||
id。在那之前,字节精确的头部锚定匹配仍是安全底线;任何后缀/链中采纳的重新引
|
||||
入,必须先对照本文档的威胁模型论证。
|
||||
|
||||
相关:#1148(OpenAI 内联 `messages[0]` 系统提示词会被计入身份,与其他协议不对
|
||||
称——单独 issue)。
|
||||
> 已迁移至 [docs/session-identity.zh-CN.md](docs/session-identity.zh-CN.md)。重定向占位,1–2 个版本后删除。
|
||||
|
||||
@@ -1,492 +1 @@
|
||||
# Technical notes
|
||||
|
||||
Mechanism-level details behind the three usage options in the README. The
|
||||
README keeps each option concise; the "how it actually works" material lives
|
||||
here instead of between the options.
|
||||
|
||||
## Native plugin lifecycle (Option 1)
|
||||
|
||||
At load the plugin **spawns its own proxy** (or attaches to a healthy
|
||||
running one — a parent-pid watchdog tears it down when the client exits),
|
||||
rewrites model traffic to `<proxy>/bili/<upstream-url>`, registers
|
||||
`compress` / `decompress` / `acp_status` as native client tools (plugin
|
||||
mode), and binds the `/acp` panel to the current session. It also reports
|
||||
the client's **own model config** to the proxy (runtime-info protocol,
|
||||
#955) so compression budgets use the real window instead of a registry
|
||||
guess. Opt-out envs: `BILI_NATIVE_PI=0`, `BILI_NATIVE_OMP=0`, `BILI_NATIVE_OPENCODE=0`, `BILI_NATIVE_DSH=0`, `BILI_NATIVE_KIMI=0`, `BILI_NATIVE_HERMES=0`, `BILI_NATIVE_ZCODE=0`.
|
||||
|
||||
## Proxy reuse and the attach gate (#1225, #1335, #1232, #1660)
|
||||
|
||||
A native hook may attach to an already-running proxy instead of spawning its own — only when it passes the lifecycle gate below. Reuse is identity-based (#1225): an existing proxy is attached only when it runs the **same code** (sha256 of the entry script, recorded in the instance file), its **lane is compatible** — each launcher declares its client's lane, two *different declared* lanes never share, and an instance without a declared lane is a manually started user-zone daemon, wildcard-compatible on that axis — **and it passes the lifecycle gate** (§below): an armed parent-pid watchdog (`watchdog.armed == true`), i.e. it was spawned by a launcher with a parent pid and dies when the last attached session dies, **or** it is a user-zone instance (no lane, no launch token), which is exempt by definition (#1660). Instances written before #1225 carry no code fingerprint and are therefore never attached: a rebuilt or updated install always starts a fresh proxy on the next launch, so fixes take effect immediately instead of silently serving stale code.
|
||||
|
||||
| Listener | Attaches? | Why |
|
||||
|---|---|---|
|
||||
| Proxy spawned by this session | ✅ | armed at birth |
|
||||
| Another session's armed shared proxy (watcher set, #1186) | ✅ | sharing is by design |
|
||||
| Manually started `bili start` daemon (user zone, #1660) | 🔶 conditional | **user-zone** instance (no lane, no launch token): an **armed** one (a managed shared proxy, #1225) is ridden by any compatible client lane; an **unarmed** manual one is, by default (`attachPolicy: own-lane`, #2877), NOT ridden by a LANEd hook — it spawns its own instead. Ridden instead under `attachPolicy: global-fallback` (pre-#2877) or `attachExternal=1`. You own its lifetime and version either way |
|
||||
| Unarmed **lane'd** proxy (crashed-session orphan; pre-#1330 unverifiable) | ❌ loudly refused | lifecycle-drift symptom (#1335): riding it would silently reuse a proxy no live session owns |
|
||||
|
||||
The hook probes each candidate's `/__bili/health` before attaching: armed → attach and register a watcher (unchanged); an **armed user-zone** candidate attaches regardless of the lane-affinity policy (a managed shared proxy, #1225); an **unarmed user-zone** (manual) candidate attaches only under `attachPolicy: global-fallback` (pre-#2877) or `attachExternal=1` — by default (`own-lane`) a LANEd hook spawns its own (#2877); an unarmed **lane'd** candidate (a crashed session's orphan, or a pre-#1330 build that reports no `watchdog` field at all — unverifiable, treated as unarmed) is refused **loudly**, and the session spawns its own proxy in the self-managed port zone (base `18787`, or the lane's sticky drift record; armed at birth, dies with the last session, #1186 watcher semantics). Version skew stays fixed: the code-fingerprint check runs first, so a rebuilt or updated install never rides a stale daemon even through the user-zone exemption. Cost: one extra short-lived proxy process per session when nothing attachable exists (session state is shared on disk, so compression continuity is unaffected); the multi-instance warning (#394) becomes correspondingly more common. **Escape hatch:** `native.attachExternal: true` in the config file or `BILI_NATIVE_ATTACH_EXTERNAL=1` extends attaching to *lane'd* listeners regardless of watchdog state (including pre-#1330 builds) — you then own those daemons' lifetimes and versions; `attachExternal` governs only the *lifecycle gate* for **lane'd** daemons (it does not open or close user-zone attachment — that axis is `attachPolicy`); `attachUrl` (env `BILI_MCP_PROXY` / `--origin`) pins an explicit target origin. Explicit user-directed attaches (`BILLION_CONTEXT_ATTACH` / preset `BILLION_CONTEXT_PROXY` for kimi/dsh) bypass discovery entirely and are exempt by construction.
|
||||
|
||||
Attach discovery is lane-aware across **all** live instances (#1232): the launcher probes every live entry in the instance registry, not just the single instance file (last-writer-wins — under concurrent multi-client use it can point at another client's proxy), and applies the gate above to every candidate. Among compatible candidates the newest instance with the launcher's own declared lane wins; an instance without a lane (a user-zone daemon) is wildcard-compatible on the lane axis and gate-exempt by default (#1660) — but whether a LANEd hook actually falls back onto it is governed by `attachPolicy`: `own-lane` (default) does not ride an *unarmed* manual daemon (#2877), while `global-fallback` restores the pre-#2877 wildcard ride. The `another bili instance is running` warning (#394) is lane-aware too: it fires for same-lane or lane-less coexistence, but stays silent between two *different* declared lanes, whose session files are disjoint.
|
||||
|
||||
## Shared state dir and multi-instance security boundary (#394, #1724)
|
||||
|
||||
Every bili instance on a host reads and writes the **same** per-host
|
||||
storage: the XDG data dir (`~/.local/share/billion-context/` — session
|
||||
records, CCR content-store, prefix-affinity) plus the state dir
|
||||
(`~/.local/state/billion-context/` — log, instance registry). The control
|
||||
plane is lane-aware (#1232:
|
||||
attach discovery and the #394 coexistence warning both respect declared
|
||||
lanes), but the **data plane is not partitioned** — there is no per-session
|
||||
owner and no per-lane isolation on disk. Two consequences follow:
|
||||
|
||||
- **Cross-instance session visibility.** Each instance's Web UI
|
||||
(`__bili/sessions` list / detail / logs) re-scans the whole shared store, so
|
||||
any instance reachable over loopback can enumerate and read *any* session —
|
||||
raw messages, content-store payloads, compressed blocks — created by any
|
||||
other instance/lane on that host.
|
||||
- **Restart drain race.** On a restart the new process hydrates the store
|
||||
before the old one finishes flushing, so last-writer-wins can drop the old
|
||||
process's final writes: lost tail updates and a provider prefix-cache bust
|
||||
(the outbound body diverges from what the provider had cached). The #1724
|
||||
mitigations: the #405 snapshot-counter guard (rejects stale session writes),
|
||||
the prefix-affinity union-on-write guard (#1737: one instance's flush never
|
||||
clobbers a sibling chain), and the self-restart ordering fix (#1742: durable
|
||||
state is flushed to disk before the replacement spawns). Host-driven restarts
|
||||
(dsh et al., #991) still rely on these data-layer guards, since their
|
||||
kill/spawn order is not bili-controlled.
|
||||
|
||||
**Security posture:** the shared-state surface is protected *only* by the admin
|
||||
endpoint's loopback gate (non-loopback source addresses are refused) plus
|
||||
filesystem permissions on the user's home tree (both dirs live under $HOME) —
|
||||
there is no per-session authorization. For a **single-user host** that is
|
||||
sufficient. On a **multi-user host** it is not: any local account able to reach
|
||||
the proxy's loopback port can read every session of every user. Such hosts must
|
||||
partition their per-host storage (per-user/per-lane subdirectories) — the root
|
||||
fix named in #1724
|
||||
(direction #1), still open as an architecture decision; Web UI scoping
|
||||
(#1724 direction #4) reduces cross-instance browsing but does not change this
|
||||
boundary.
|
||||
|
||||
## Runtime-info protocol (#955)
|
||||
|
||||
A native plugin lives inside the client process, so it can read the model
|
||||
config the client itself will use. It pushes that truth to the proxy on two
|
||||
channels, and the proxy prefers it over the models.dev registry / built-in
|
||||
table in the context-window chain:
|
||||
|
||||
| Channel | When | Fields |
|
||||
|---|---|---|
|
||||
| Per-request headers (gated on `x-bili-plugin`) | every model request | `x-bili-plugin-context-window`, `x-bili-plugin-max-output`, `x-bili-plugin-model` |
|
||||
| `POST /__bili/plugin/runtime-info` (loopback) | plugin bootstrap + any reported-config change | `{agent, model, contextWindow?, maxOutput?, baseURL?, conversationId?, source}` |
|
||||
|
||||
Resolution order for the window: `anthropic-beta` negotiation > per-request
|
||||
plugin header > runtime-info > launcher env > route config > models.dev
|
||||
registry > built-in table. The runtime-info step reads the **per-agent
|
||||
entry** when the request carries an `x-bili-plugin` header (agent+model must
|
||||
match); requests without one resolve the **conversation-scoped entry**
|
||||
recorded with a `conversationId`, keyed by the same conversation signal the
|
||||
session binds on (client conversation header, custom session header, or the
|
||||
body's `prompt_cache_key`) — model must match either way (#1531: omp stamps
|
||||
`prompt_cache_key` but no plugin header, and main/subagent sessions share
|
||||
the agent name while running different models). A reported `maxOutput` only
|
||||
stands in when the request body carries no output budget of its own.
|
||||
Implementations: `src/agent/pi.ts` (covers pi and omp),
|
||||
`src/agent/opencode-native.ts` (v1), `src/agent/opencode-v2.ts`,
|
||||
`src/agent/dsh-native.ts`, `src/kimi/native-mcp.ts` (bootstrap-time report
|
||||
only — kimi's provider `custom_headers` are static, so per-request headers
|
||||
would go stale on model switch), `hermes-plugin/__init__.py` (Python plugin:
|
||||
per-request headers via an `llm_request` middleware, max output and the host's
|
||||
per-model context window — read from hermes' own
|
||||
`HERMES_HOME/context_length_cache.yaml`, fail-open on any miss (#3261) —
|
||||
captured by a `pre_api_request` hook) — other client integrations should
|
||||
follow the same protocol.
|
||||
|
||||
**DSH `maxOutput` reporting is declaration-gated — an undeclared custom model empties the whole ceiling chain (#2904).** `src/agent/dsh-native.ts` forwards `maxOutput` **only** when the host's `resolveModelInfo(provider, model)` returns a positive `defaultMaxTokens`, and DSH populates that **only** when the model item explicitly declares `maxTokens` — provider-level output defaults are never reported. For a user-added custom model with no declared `maxTokens`, `defaultMaxTokens` is `undefined`, so BOTH runtime-info channels come back empty. With no models.dev entry and no bili-configured `output` either, the four-source ceiling chain (#1840) resolves to nothing, and `restoreOutputBudget` lifts a client-starved budget to the session high-water mark — which on a long session has decayed through small positives to a poisoned low value. Every turn then runs reasoning-only and stops at `length`/`max-tokens`; switching to a model WITH a known ceiling masks it (the high-water is floored up to the ceiling), so the switch is a trigger, not a cause. The real fix home is **DSH-side**: report its configured provider/model output default instead of `undefined` (the immediate user workaround is setting `maxTokens` on the model item). bili deliberately does not guess a quota floor (#1842); instead #2904 surfaces the degraded state persistently on the `/acp` panel, the Web UI session page (data source `/__bili/sessions/<id>/detail`), and `/__bili/plugin/status?conversationId=` (`outputBudgetDegraded`) — clearing automatically once a healthy value or ceiling arrives — and extends `degenerateTurnWarning` to `length`/max-output terminations so the truncation correlates with its cause in the log.
|
||||
|
||||
**omp: the `prompt_cache_key` stamp is withheld when OMP's Cowork transport owns egress (#2583/#3556).** In native omp mode the stamped `prompt_cache_key` is the only per-request session signal, and its sole consumer is bili's own fetch-layer interceptor (it rewrites model URLs to `<proxy>/bili/<url>` and strips the field before forwarding). Recent OMP builds ship a "Cowork transport" (introduced 2026-07-30, can1357/oh-my-pi `642892ae`; proxy handling `e22a5ff2`) that sends default `anthropic`/`anthropic-messages` requests over node:https DIRECTLY — they never touch `globalThis.fetch` unless an explicit proxy env var (`PI_PROXY` / `PI_PROXY_ANTHROPIC`) pushes them back onto Bun's fetch. Since #3556 the `bili omp` launcher closes this gap itself: unless the user has set `PI_PROXY` / `PI_PROXY_ANTHROPIC`, it exports `PI_PROXY_ANTHROPIC=<proxy origin>`, so on the default launcher lane Cowork rides the compressible lane (the stamped key consumed and stripped by the proxy) instead of dialing direct. The withhold also gates the cert-MITM lane — #3556 hoisted it above the destination-routed check, where a nested placement skipped it entirely. Stamping there would ride the field verbatim into Anthropic's strict schema (HTTP 400 `prompt_cache_key: Extra inputs are not permitted`). The stamp gate (`stampPromptCacheKey` → `ompCoworkTransportBypassesFetch` in `src/agent/pi.ts`) mirrors OMP's own per-model egress selection: proven-direct traffic is unstamped, with one loud warning per process per model. Consequence: those direct requests go uncompressed and anonymous to the proxy (identity/panel/billing degrade — the same trade as #1403); every other lane (launcher `/bili/` rewrite, MITM whitelist, other providers/apis, proxy-configured hosts) is unchanged. Known residual: a `NO_PROXY`/`no_proxy` rule matching the model host silences OMP's proxy handling even when `PI_PROXY` / `PI_PROXY_ANTHROPIC` are set — the request then dials direct while still stamped (the same 400 class); remove such hosts from `NO_PROXY` instead. The reverse asymmetry is fail-safe: OMP's shape-based fetch fallbacks (Request-object input, non-record headers, unsupported body) route back onto `globalThis.fetch` even with no proxy envs, where a withheld stamp only degrades identity and never hard-fails. Full coverage would require a host-side change (route Cowork egress through `globalThis.fetch`) — boundary note in #2583.
|
||||
|
||||
The launcher env tier covers pure-proxy clients (no in-process plugin):
|
||||
`bili <client>` reads the client's own model config at launch
|
||||
(`model_context_window` / `model_max_output_tokens` for codex,
|
||||
`contextWindow` / `maxTokens` for pi / omp, `limit.context` / `limit.output`
|
||||
for opencode, `maxInputTokens` / `maxOutputTokens` for codebuddy) and hands
|
||||
it to the proxy via `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS`
|
||||
(#971). A plugin report — when present — always outranks it.
|
||||
|
||||
Before the first model request there is no session yet, so the `/acp` panel
|
||||
probes `GET /__bili/plugin/status?conversationId=<agent>&fallback=latest`,
|
||||
which answers from the runtime table (`phase: "pre-first-request"`) instead
|
||||
of 404ing — the reported config is visible immediately, and the real session
|
||||
takes over once traffic lands.
|
||||
|
||||
## Claude native posture (#964)
|
||||
|
||||
Claude Code has no in-process extension point, so `bili plugin install
|
||||
claude` writes a managed block into `~/.claude/settings.json` (env
|
||||
`ANTHROPIC_BASE_URL=http://127.0.0.1:<port>/bili/<upstream>`,
|
||||
`DISABLE_AUTO_COMPACT=1`, and a `SessionStart` hook) plus the same
|
||||
user-scope MCP shell as before. The hook (fired before claude's first model
|
||||
request) resolves its port like every lane (#1660): an explicit pin
|
||||
(`BILI_CLAUDE_NATIVE_PORT` > config `claude.nativePort`) launches
|
||||
**strict-port** on that exact port (a squatter is refused loudly, #964
|
||||
preserved); otherwise it rides the self-managed zone — the lane's sticky
|
||||
record else base `18787` — non-strict, with the child's EADDRINUSE +1
|
||||
ladder resolving collisions and the settled port recorded sticky. One
|
||||
exception to the ladder (#1723): when the holder of the lane's port is a
|
||||
same-lane instance running a **different build** (the upgrade-restart
|
||||
overlap — the old version still draining), the child waits for it to release
|
||||
(up to 5s) and rebinds the *same* port instead of drifting; a holder that
|
||||
never leaves exhausts the wait and gets the plain ladder as before. After the
|
||||
proxy is up the hook re-pins the managed `ANTHROPIC_BASE_URL` to the live
|
||||
origin each session (`repinClaudeManagedBaseUrl`), so a hopped port
|
||||
self-heals on the next launch and the baked URL never stays desynced from
|
||||
the running proxy. Upstream override: `BILI_CLAUDE_UPSTREAM` (or the
|
||||
existing `claude.anthropicBaseUrl` config). Install no longer persists
|
||||
`claude.nativePort`. Opt out with `BILI_NATIVE_CLAUDE=0` — the hook then
|
||||
brings up a **passthrough** proxy on the same resolved port (verbatim
|
||||
forward, compression off) so claude keeps working. The block is pure JSON
|
||||
merge/strip: foreign keys are never touched, `bili plugin remove claude`
|
||||
restores exactly. `bili claude` still works on a machine with the native
|
||||
block installed — it overrides the static URL with its own proxy and the
|
||||
hook stays dormant.
|
||||
|
||||
## Injection priority — no files unless unavoidable (#535)
|
||||
|
||||
bili never owns user data: every launched client runs on its **real home**, so
|
||||
runtime writes land where the user expects them. When pointing a client at the
|
||||
proxy, the launcher picks by priority — **env vars first** (proxy/CA envs for
|
||||
hermes/dsh/codex; the `BILI_PROVIDER_REWRITES` URL manifest for pi/omp,
|
||||
consumed by their extension's `registerProvider` at load), then **CLI flags or
|
||||
extension APIs** (codex `-c key=value`, opencode plugin), and **generated files
|
||||
last** — today only opencode's temp `opencode.json` (deleted on exit) and dsh's
|
||||
loopback exception: dsh's fetch stack bypasses proxy envs for loopback targets
|
||||
unconditionally, so local upstreams keep the persistent `~/.dsh-bili` overlay
|
||||
rewrite until dsh gains a settings-path env or an upstream loopback opt-out.
|
||||
Overlay dirs created by older versions are left in place and never merged back
|
||||
into the real home.
|
||||
|
||||
## Two compression modes — who executes `compress`
|
||||
|
||||
The proxy runs in one of two modes, and **the mode decides who executes
|
||||
`compress`, which in turn decides how the summary travels to the model** (the
|
||||
"carrier"). This distinction is the root of #377.
|
||||
|
||||
| | **Launcher / plugin mode** (`bili pi`, `bili codex`, …) | **Proxy mode** (plain client → `/bili/`) |
|
||||
|---|---|---|
|
||||
| Client | ACP-native agent with the bili extension (pi/omp) | Any OpenAI/Anthropic client, no extension |
|
||||
| Who executes `compress` | **The agent** (pi runs it locally) | **The proxy** (server-side compress loop) |
|
||||
| `compress` tool call in the re-sent history? | Yes — part of the agent's own conversation | No — ephemeral proxy-loop traffic |
|
||||
| Preflight blocks (no tool call)? | Last-resort backstop — the agent normally compresses on its own `compress` calls, but `src/preflight.ts` still fires (in both modes) when the input alone exceeds the window (#470) | Yes — `src/preflight.ts` compresses behind the client's back |
|
||||
| **Summary carrier on the wire** | **the `compress` tool call** | **an `acp_summary` user message** |
|
||||
| System messages on the wire | always exactly 1 (client + prompt) | always exactly 1 (client + prompt) — summaries ride on user messages |
|
||||
| SGLang "single system" 400 (#377) | cannot happen | cannot happen (summaries are user messages, not system) |
|
||||
| Proxy-injected `compress` tools | none — the agent registers the 4 ACP tools natively | the 4 context tools (when enabled) |
|
||||
| Proxy-injected nudge | **yes** — the agent has no nudge channel of its own, so the proxy-side nudge is the proactive compression trigger (preflight alone only fires at the hard limit; #451) | yes (when enabled) |
|
||||
|
||||
**Why the carriers differ.** In plugin mode the agent owns compression: the
|
||||
`compress` call + result live in the agent's own history and are re-sent every
|
||||
turn, so the summary rides on the tool call and the agent's view never renders
|
||||
the kernel's `acp_summary` fallback (`billion-context-pi` `src/messages.ts`
|
||||
skips `acp_summary_*`). In proxy mode the client is not ACP-native, so the
|
||||
proxy executes `compress` server-side; the tool call never enters the client's
|
||||
history, and preflight blocks have no tool call at all — so the kernel's
|
||||
`acp_summary` message is the only carrier. The kernel renders it as role
|
||||
`system`, but strict OpenAI-compatible backends (SGLang) require exactly one
|
||||
system message at index 0, so `systemToUser` (`src/util.ts`) re-voices it as a
|
||||
`user` message, leaving it at its anchor position. This keeps the head system
|
||||
message (the prefix-cache anchor) byte-stable across compress turns, so a new
|
||||
block does not invalidate the whole-conversation prefix.
|
||||
|
||||
**Why `user`, not `system` or a forged tool call.** A mid-stream `system`
|
||||
message is what SGLang rejects (#377). A forged `compress` tool call would be
|
||||
the "pure" carrier, but in proxy mode it requires fabricating an
|
||||
assistant `tool_calls` + `user` `tool_result` pair by id, declaring the tool in
|
||||
the request, and handling preflight blocks that have no authentic call — far
|
||||
more invasive than re-voicing a standalone note. A `user` message is allowed
|
||||
anywhere in the conversation, so it is the minimal change that satisfies both
|
||||
SGLang's one-system rule and prefix-cache stability. The accepted trade-off:
|
||||
a summary is a stand-in for the folded history, and re-voicing it as a user
|
||||
turn is a semantic mismatch the model tolerates (it is clearly marked
|
||||
`[Compressed conversation section]`).
|
||||
|
||||
**Do the two modes coexist?**
|
||||
|
||||
- **Same proxy instance: yes, by design.** One proxy serves plugin and plain
|
||||
clients at once; `pluginMode` is decided per request (`x-bili-plugin` header)
|
||||
and bound per session (`session.metadata.pluginAgent`). The launcher reuses a
|
||||
running proxy.
|
||||
- **Same session: the mode is sticky.** A session created in plugin mode stays
|
||||
plugin mode (metadata inheritance); a plain session can only be *upgraded* to
|
||||
plugin mode if a plugin request arrives with a matching conversation id (the
|
||||
header outranks) — and never downgraded. In practice a plain→plugin upgrade
|
||||
requires the plugin client's conversation id to match an existing plain
|
||||
session id, which doesn't happen (each client generates its own id).
|
||||
- **Cross-mode block hazard: theoretical only.** It would require the same
|
||||
conversation id to span a mode switch. plugin→proxy is safe (the tool call is
|
||||
in the shared history); proxy→plugin could orphan proxy-created block
|
||||
summaries (their tool call isn't in the agent's history and the agent's view
|
||||
skips `acp_summary`) — but that needs the id match above, which doesn't occur.
|
||||
|
||||
**Verifying that a compression actually landed.** After executing `compress`,
|
||||
the proxy emits a confirmation marker (`📦 [ACP] Compressed …`) as plain
|
||||
assistant text — but under sustained context pressure a model was observed
|
||||
*writing that marker format itself* without ever calling the tool (#717): 17
|
||||
fake "compressions" over ~2 hours while real usage climbed to 89%. A marker
|
||||
line visible in the transcript is therefore not proof of persistence — verify
|
||||
with `acp_status` (block count increased, compressible-range start advanced)
|
||||
before trusting it. As a backstop, the proxy strips any marker-shaped line the
|
||||
model emits on its own and logs a `[marker-echo]` warning, and both the nudge
|
||||
and the injected prompt state explicitly that markers are proxy-emitted only.
|
||||
|
||||
### Mode switches change the Responses projection — attribution must not blame the host (#2867)
|
||||
|
||||
On the Responses lane the two modes also project mid-history `system`/`developer`
|
||||
items differently: plugin mode keeps them in place (`__bili_inplace_sysdev`,
|
||||
#1638 prefix-cache churn fix) — as of #3227 so do Codex clients in native proxy
|
||||
mode (UA-detected via `isCodexClient`); other proxy clients keep the hoist into
|
||||
the head developer block (#1085 hoist-and-anchor). A self-heal degrade-to-proxy
|
||||
(#2155) therefore
|
||||
re-projects the SAME incoming history into different forwarded bytes — the
|
||||
forwarded-system fingerprint (#2350) flips even though the host changed nothing,
|
||||
and a naive ledger would book that under "host rewrote the system prompt".
|
||||
Fix: the ledger now pairs the projection fingerprint (`systemFp`) with a
|
||||
mode-independent **canonical** fingerprint of the raw incoming system/developer
|
||||
stream (`canonicalSysFp`, role + content + order, captured before any
|
||||
projection). At settle time: projection flipped AND canonical stable → cause
|
||||
`projection` (its own dimension: `pf` flag, `projSwitches` counters, cold window,
|
||||
report section — the proxy's own doing); canonical also changed → cause
|
||||
`prompt` (a genuine host-side rewrite, as #2350 intended); canonical changed
|
||||
alone (e.g. a mid-history edit while in plugin mode, which never touches the
|
||||
head block) is recorded observationally (`cf`) without a billing bucket. Unknown
|
||||
canonical sides never classify (legacy reading). Each sample additionally carries
|
||||
its mode (`pm`) and prepare-responses logs one transition line with the reason
|
||||
(self-heal degrade / restore / header absent). Only hash, length, mode and reason
|
||||
are recorded — never the prompt body. No wire behavior changed: both projections
|
||||
stay exactly as before; the switch is now *recorded* instead of misattributed.
|
||||
|
||||
## Responses native chaining is not supported — history must be replayed (#1954)
|
||||
|
||||
The Responses-wire adapter (`prepareResponses` in `src/server.ts`, `buildRequest`
|
||||
in `src/loop/adapter-responses.ts`) is a **stateless replay compressor**: it
|
||||
treats `parsed.input` as the *complete* conversation, compresses that, and then
|
||||
drops `previous_response_id` unless `ACP_KEEP_RESPONSE_ID=1`. It keeps no
|
||||
response-lineage store, so it **cannot materialize the history a native-chaining
|
||||
continuation references**.
|
||||
|
||||
OpenAI's native chaining (`store:true` + `previous_response_id`, server-held
|
||||
history) and bili's client-replayed model are mutually exclusive paradigms. A
|
||||
delta-only continuation (just the new turn + `previous_response_id`, no full
|
||||
replay) therefore reaches the upstream with **neither the reference nor the
|
||||
referenced turns** — prior context is silently lost upstream while the request
|
||||
still returns 200. That is the mechanism behind #1954.
|
||||
|
||||
**What ships here (approach A — visibility only).** When a non-empty
|
||||
`previous_response_id` is stripped, both paths now emit a `warn` naming the id
|
||||
and stating the consequence. The trigger keys off the id **alone**, not off
|
||||
explicit `store:true`, because Responses stores responses by default — an omitted
|
||||
`store` still leaves the referenced response resolvable upstream, so judging on
|
||||
`store` would miss the common case. Approach A changes no forwarded byte and
|
||||
closes nothing: the delta request still loses its history and still returns 200.
|
||||
It only stops the loss from being silent.
|
||||
|
||||
**Observation, not proof.** Current builds/tests show codex sends `store:false`
|
||||
and never sets `previous_response_id`, so this is a no-op for codex *today*. That
|
||||
is an observation from the existing E2E + traffic, not proof that no client ever
|
||||
chains — the E2E does not cover the delta-chaining shape. codex is OpenAI's own
|
||||
CLI against a Responses API that natively supports chaining, so a future version
|
||||
switching to native continuation to save tokens is a reasonable evolution; until
|
||||
then this stays a latent high-severity gap.
|
||||
|
||||
**Safe options for a chaining client today:** resend the full input/output
|
||||
history (bili then compresses/forwards normally), or set `ACP_KEEP_RESPONSE_ID=1`
|
||||
to preserve the id — but under KEEP the referenced history lives server-side and
|
||||
bili's compression/prefix-cache accounting cannot see it. The real fix
|
||||
(materialize lineage before compression) is tracked as feature #1973. Official
|
||||
migration guide: https://developers.openai.com/api/docs/guides/migrate-to-responses
|
||||
|
||||
## Single-writer: who owns which copy (#991)
|
||||
|
||||
Every bili presence on a machine has exactly **one writer** — the thing
|
||||
that installed it is the thing that updates it, and nothing else ever
|
||||
overwrites that copy in place:
|
||||
|
||||
| Lane | Copy lives in | Updated by |
|
||||
|------|---------------|------------|
|
||||
| global `bili` | npm global (`npm i -g billion-context`) | `bili update` / background auto-update |
|
||||
| **pi** | pi's package manager (npm form) | **`pi update`** — bili never overwrites it |
|
||||
| **opencode** | opencode's plugin dir | **opencode's plugin manager** — bili never overwrites it |
|
||||
| **dsh** | each profile's pnpm store | a periodic check re-runs dsh's plugin channel per profile — driven by the global bili self-update **or by the profile copy's own proxy** when the global isn't running (dsh-market installs, #1196); manual: `dsh plugin add billion-context@latest`. pnpm's hardlinked store must never be copied over in place |
|
||||
| omp / claude / codex / kimi / zcode | no copy — entries point at the global bili install | they update together with the global copy |
|
||||
| **hermes** | `~/.hermes/plugins/billion-context/` (copied files + `bili.json` sidecar pointing at the global dist) | **`bili plugin update hermes`** re-copies the files; the sidecar tracks the global install |
|
||||
|
||||
This is enforced in code, not just convention: the self-updater
|
||||
(`src/update.ts` → `hostManagedInstall`) detects install dirs under a pnpm
|
||||
virtual store (`.pnpm`) or a host agent tree (pi / opencode / dsh / kimi /
|
||||
omp homes) and **skips** them; `installViaTarball` refuses them structurally
|
||||
so direct callers cannot corrupt a store either. Mixing *commands* is fine
|
||||
(`dsh plugin add` ≡ `bili plugin install dsh` — same channel, same records);
|
||||
mixing *writers* is what the guard forbids. `bili plugin update [client]`
|
||||
is the one command that drives every lane through its own owner and prints
|
||||
the per-lane update path (`bili plugin list` shows the same per-lane channel).
|
||||
|
||||
## Stuck-session self-heal — detection constants and remedies (#2155)
|
||||
|
||||
Three failure shapes share one detector family in `src/session-self-heal.ts`,
|
||||
evaluated once per request (after `prepare`, on the nudge-carrying lanes only;
|
||||
bypass and side lanes never earn credit):
|
||||
|
||||
- **D2 zombie plugin lane** — the plugin was uninstalled (or its MCP child
|
||||
died) but already-open client windows keep the session plugin-bound
|
||||
(sticky `metadata.pluginAgent`, `src/server.ts`). Signal: 5 consecutive
|
||||
rounds (`SELF_HEAL_WINDOW`) that were nudged, carried **no** `x-bili-plugin`
|
||||
header, declared **no** bili tools on the wire, and produced **no**
|
||||
compression reduction. Remedy: **degrade to proxy mode** — the single
|
||||
`pluginMode` flip (`pluginAgent !== undefined && !pluginLaneDegraded(session)`)
|
||||
re-injects the ACP tools wire-side, re-arms the compress rewriter, CCR
|
||||
stamping and absorb, and **keeps the nudge** (the tools are back). When wire
|
||||
injection is unavailable (`compress.injectTool=false` → `degradeAvailable`
|
||||
false) the remedy falls back to **suppress-nudge**. Recovery: the live
|
||||
plugin header (`pluginLaneRestore`, hoisted BEFORE the `pluginMode` flip so
|
||||
the first header-bearing request is already plugin mode — the sticky
|
||||
`pluginAgent` must NOT be used as the restore signal or the degrade clears
|
||||
one round after arming). The binding is kept, never erased.
|
||||
- **D1 nudge idle** (non-plugin generalization) — 5 consecutive nudged rounds
|
||||
with zero reduction and zero bili tool uses. "Nudged" means the text was
|
||||
ACTUALLY injected — since #3004 the decide gate's verdict is the delivery
|
||||
fact (`prepared.nudgeOutcome === "injected"`); a vetoed arm credits no idle
|
||||
streak (the pre-gate expression armed suppression on channels the model
|
||||
never received). Remedy: suppress the nudge at all four `willInjectNudge`
|
||||
gates (`&& !nudgeSuppressed(session)`, covering the emergency path too).
|
||||
Two bounds keep the suppression from latching forever (#3004): the decide
|
||||
ladder's fallback escape still punches through ONE legacy advisory while
|
||||
suppressed (the failure-recovery path outranks suppression;
|
||||
`consumeFallback` resets the counter), and the latch expires
|
||||
`SELF_HEAL_SUPPRESS_CAP_MS` (10 min) wall-clock after arming — re-arming
|
||||
then costs a fresh full `SELF_HEAL_WINDOW` of idle rounds. Recovery: any
|
||||
compression reduction or bili tool use lifts the suppression early.
|
||||
- **D3 gateway-killed summaries** — a **non-streaming** preflight summary that
|
||||
dies with HTTP 524/504 (Cloudflare class) is not retried in place (the old
|
||||
transient-retry path burned ~100 s per attempt against a dead gateway);
|
||||
instead the session learns `metadata.preflightStreamSummary = true` on the
|
||||
**first** hit and the summary is re-requested as SSE — the same learned
|
||||
store as the manual `compress.streamSummary` knob (#2133), auto-armed.
|
||||
The cascade is honored in both directions: an explicit `streamSummary:
|
||||
false` anywhere (global → provider → model) is the operator's opt-out —
|
||||
neither learn path arms and a stale learned flag is ignored
|
||||
(`streamSummaryOff` in `PreflightDeps`).
|
||||
|
||||
Observability: `session.metadata.selfHeal = { detected, action, since }` is
|
||||
exposed in `/__bili/sessions`, badged in the web UI ("heal"), and every
|
||||
transition logs one `[self-heal]` line (detect + recovery). `bili plugin
|
||||
remove <client>` best-effort queries the live proxy (instance file →
|
||||
`GET /__bili/sessions`, 2.5 s timeout, silent on failure) and prints a note
|
||||
when sessions of that client were active within the last **10 minutes**.
|
||||
|
||||
## Unified ACP tag-echo remediation — the four invariants (#2023/#2066/#2190/#2248)
|
||||
|
||||
One PR folds the three remediation legs together (refs-run residue #2023,
|
||||
degenerate-close stripping + egress audit net #2190, emission drop +
|
||||
signed-thinking verbatim #2066) under a single set of hard rules that govern
|
||||
EVERY text-rewriting surface (loop adapters, plugin passthrough, JSON strip
|
||||
functions, exit audits):
|
||||
|
||||
1. **The thinking channel is byte-verbatim.** Anthropic `thinking`, Google
|
||||
`thought`, OpenAI `reasoning_content`/`reasoning`, and Responses reasoning
|
||||
summaries ride as-is — echo-shaped reasoning included. Rationale: reasoning
|
||||
replay (DeepSeek-style) and signature verification validate these bytes;
|
||||
any rewrite desyncs them and bricks the session (#1960/KDD#10). The
|
||||
adapters route these fields through `createIdentityStreamFilter`, and the
|
||||
strip functions (`stripOpenaiChatText`, `stripResponsesText`) leave them
|
||||
untouched (defense in depth). NOTE: this REVERSES the pre-#1881-era
|
||||
reasoning-echo strip — the thinking channel is no longer cleaned.
|
||||
2. **Model prose is manageable.** Render-tag echoes, marker lines,
|
||||
bili-internal text, degenerate open/close residue, and (when
|
||||
absorb-instructed) whole tool-call emissions are stripped from the visible
|
||||
text channel only.
|
||||
3. **Model output bound for files is byte-identical (#1039).** Tool-call
|
||||
arguments never enter any filter, whatever bytes they carry.
|
||||
4. **User-sent bytes are never rewritten.** A verbatim echo of the user's own
|
||||
fragment survives even when stripping is armed (#463 exemption, keyed on
|
||||
the request text, not shape).
|
||||
|
||||
The egress audit net (#2248) stays log-only: raw exits (unrecognized frames,
|
||||
parse failures) forward as-is and log `[tag-echo] raw exit` so new leak shapes
|
||||
become visible without changing the wire. Pinned by
|
||||
`tests/unified-acp-invariants.test.ts` (eight tests, both lanes).
|
||||
|
||||
## Cache-ledger accrual is coverage-conditioned (#2202)
|
||||
|
||||
The ledger books each request against every elapsed fold
|
||||
(`requestsAfter += 1` per sample), and the panel turns that counter into
|
||||
`netSaved = Σ (S − σ) × requestsAfter`. Booking is a *claim that this
|
||||
request benefited from the fold* — which is only true while the fold's
|
||||
covered bytes actually ride the resent wire. When a host removes them
|
||||
outside bili's knowledge (dsh native compaction, #2193), the old counter
|
||||
kept climbing on a destroyed substrate: the #2193 incident showed
|
||||
netSaved at 355M while 1510 covered ids were permanently gone.
|
||||
|
||||
The fix is writer-side, at the claim site: `reconcileFoldCoverage`
|
||||
already inspects every inbound pass for exactly this evidence, so it now
|
||||
also records per-block presence into
|
||||
`session.metadata["foldCoverageByBlock"]` — `{p, r, t, e}` per blockId
|
||||
(present verbatim / reclaimed via re-anchor / total covered / ever-present
|
||||
latch). The ledger links each fold to its block with a sparse
|
||||
`LedgerFold.bid` (set once in `recordCacheFoldsFromBlocks`, the single
|
||||
choke point for both the eager proxy path and the lazy plugin-mode path),
|
||||
and scales the increment by the measured fraction `(p + r) / t`:
|
||||
|
||||
- **1** — full coverage, or no usable record → byte-identical to the
|
||||
pre-#2202 counter (healthy sessions and all legacy entries);
|
||||
- **f** — partial coverage → proportional accrual;
|
||||
- **0** — verified coverage-lost → accrual frozen until coverage returns.
|
||||
|
||||
Two classes are self-calibrated by the `e` latch: a fold whose covered ids
|
||||
were *ever* seen present is verifiable, so total absence means loss; a fold
|
||||
whose ids *never* appeared post-creation is structurally unverifiable
|
||||
(view-folding hosts that resend folded views instead of raw originals) and
|
||||
keeps status-quo booking rather than being silently zeroed. Coverage-lost
|
||||
is live-computed (`e === 1 && p + r === 0`), so recovery resumes accrual
|
||||
with no sticky state; one warn/info log fires per flip
|
||||
(`foldCoverageLostLogged` dedup key).
|
||||
|
||||
Evidence hygiene mirrors the #1195 guard: side-request-shaped passes
|
||||
(< 10 inbound messages — title-gen, WebSearch refinement) take NO
|
||||
evidence at all (no records, no backbone roll, no drift-streak movement,
|
||||
no resets), because a short pass would skew the next pass's alignment and
|
||||
manufacture phantom total-loss.
|
||||
|
||||
Panel presentation keeps lost folds out of the headline number: the web
|
||||
sessions view shows them as separate labeled segments (row tooltip,
|
||||
overview sub-line, detail stat) — frozen pre-loss savings stay visible,
|
||||
post-loss growth stops.
|
||||
|
||||
## OpenAI chat-wire prompt_cache_key: stamp everywhere by default, protect strict upstreams with an A/B probe (#2218/#2645/#3556)
|
||||
|
||||
The dsh plugin lane's one identity signal readable by body-keyed relays is the chat body's `prompt_cache_key` (the winning conversation header `x-bili-plugin-conversation` is bili-internal and never travels under that name; header-reading relays get `x-session-id`). Two opposing populations meet there: **strict direct APIs** reject unknown body params with a 400 — and strictness is per MODEL on the SAME origin (#2645: one NVIDIA-gateway model accepts the key, its sibling rejects it) — while **account pools**, including remote relay pools, read the key as their prefix-cache routing signal, so dropping it anywhere silently degrades those sessions' cache affinity (the #1403 class inverted). No destination-shape test can arbitrate: a loopback-only gate (the #2649 attempt) fixes the strict APIs but strips the key from the two biggest pool populations (docker-bridge/LAN/VPS/domain-name pools).
|
||||
|
||||
Settled design = **stamp-by-default + empirical self-heal (probe-and-remember)**:
|
||||
|
||||
- Stamp (`src/session-id.ts` → `resolveRelayAffinityPck`): the internal conversation header present ⇒ stamp `<conversation id>` on EVERY destination; a client-supplied key passes through verbatim until its pair is ablated, then it is withheld too (so later turns don't re-pay a 400 round trip). Unparseable origins fail open (stay stamped). Zero config surface — no new field, env var, or CLI flag.
|
||||
- Probe (`src/server/relay.ts`, same buffered-body seam as the #552 compat ladder): the FIRST 400 on an egress body carrying the key re-sends the identical payload once without `prompt_cache_key`. Retry accepted ⇒ causation proven ⇒ remember the `origin(+model)` pair in process memory (`src/pck-probe.ts`) — in-memory ONLY, no persistence, restart re-probes. Retry also failed ⇒ NOT this field's fault ⇒ discard the retry, forward the original 400 untouched, learn nothing (a 400 has many causes; only the A/B verdict may ablate). One probe per request, ever.
|
||||
- Granularity: origin+model, mirroring #2645's measured strictness — one strict model on a shared pool origin leaves sibling models stamped.
|
||||
- Visibility (owner requirement): first ablation logs a WARN naming origin/model, the affected session(s), and the account-pool caveat explicitly ("if this destination is your relay/account pool, its prefix-cache affinity may degrade"); `acp_status` carries a section listing current suppressions; the web panel shows a banner (zh/en) with sessions; scripts read `pckSuppressions` from `GET /__bili/status`. All process-local; a restart clears and re-probes.
|
||||
- Modes: only the plugin lane (registered agent / dsh plugin, internal conversation header present) ever stamps; plain proxy mode stays pure passthrough in both directions, byte-for-byte unchanged.
|
||||
|
||||
Tests: `tests/issue2645-pck-probe.test.ts` (strict upstream self-heals turn 1, remembers turn 2, lenient pool never probes, poisoned upstream forwards the 400 and learns nothing, client-owned keys drop after ablation, model-granular pairs) + the rewritten matrix in `tests/issue2218-relay-affinity-signal.test.ts`.
|
||||
|
||||
## Uncovered-history audit — honest minimum verdict (#4331)
|
||||
|
||||
The "no compressible ranges remain — the context is already at its minimum" stop signal was structurally unverifiable: it fired whenever the PRE-FOLD OFFER was exhausted (`postCompressTail`, #2404 pinning), but nothing ever compared the union of active-block ranges against the session's ref set. A live ZCode session showed the failure at scale — 138 mid-history refs (~65K tok, ~16% of context) in no active block, largest run `m00312`–`m00411` (100 msgs), while the receipt declared the global minimum three times in a row. The kernel DOES find such spans when they are offered (verified by repro on master); what was missing was a GLOBAL coverage audit plus a verdict that only claims "minimum" when one holds.
|
||||
|
||||
Design (`src/uncovered.ts`, host-side only, no kernel change):
|
||||
|
||||
- `uncoveredHistoryRuns()`: walk the message array for entries outside every active block's coverage (the `collectVisible` predicate), group contiguous runs, then classify each run: skip if any current offer covers part of it (the model can act on it now); otherwise diff TWO `core.processTurn` passes over a `structuredClone(state)` — normal config vs relaxed `{preserveRecentMessages: 0, preserveRecentTokens: 0}` — and treat refs offered only in the relaxed pass as zone-hidden (inside the protected recent window). The empirical zone diff deliberately re-uses the kernel's own protected-zone rules instead of copying them, so it self-maintains as those rules evolve (over-approximation errs toward under-reporting). Runs below `VIABLE_RANGE_MIN_TOKENS` (200) stay silent. A caller that already ran the normal offer pass may pass it via `normalRanges` (array = trust-and-reuse, even empty; undefined = no caller data, audit runs its own pass) so acp_status pays ONE extra `processTurn`, not two. Whole function is advisory: any throw degrades to "no runs found" and never breaks receipts or status.
|
||||
- **acp_status** gains an additive `UNCOVERED HISTORY` section (top-5 runs by tokens, rest counted) listing mass that sits outside every active block AND is absent from the live Compressible-ranges list above — including isolated sub-gate runs between covered blocks that no merge will ever fold (the permanent-hole class of #4331 / #847). Named for visibility, explicitly not as fold suggestions; rows drill down via `scope:"uncompressed"` unchanged.
|
||||
- **Tier-2 coverage invariant (reviewed, pinned by P4)**: the audit's covered-set is `coveredMessageIds` = the union of ACTIVE blocks' `effectiveMessageIds` with NO child recursion (kernel/src/state.ts:57-64). That is safe because every block-creation path unions consumed children's `effectiveMessageIds` into the new parent (kernel/src/unit-projection.ts:178-183) and deactivates the children (kernel/src/compress.ts:1578-1581) — a T2/T3 parent therefore carries its full distilled span in the state model, and hydration preserves it (whole state JSON). DB-side walks of `blocks.payload_json` do NOT have that property and need `directBlockIds` recursion (the reason an earlier independent attempt carried one); the state model does not.
|
||||
- **postCompressTail**: on clean whole-offer exhaustion with no tier distillation, the audit runs before the verdict. Runs found AND totalling ≥ `UNCOVERED_RECEIPT_FLOOR_TOKENS` (10K, receipt-only) → honest text naming them ("not at its minimum", pointer to acp_status). Below the floor — or with no runs — the verbatim #1387 contract string fires byte-stable, exactly as on master: small declined leftovers must not re-nag on every fold (pi #521 rule), while material leaks override it. The floor is deliberately NOT applied to the acp_status section: an explicit inspection surface is not a nag surface, and option 1 of #4331 specified no size gate there. The 10K total is a product value pending owner ack (matches the reviewer's independent pick).
|
||||
|
||||
Behavior change (disclosed): old = unconditional "already at its minimum" on offer exhaustion; new = that claim only when the global audit verifies it AND the uncovered mass clears the 10K receipt floor — below the floor the receipt is byte-identical to master (so `tests/compress-success-tail.test.ts` stays at master bytes, zero diff), and its #2404/#1387 sub-floor residue fixtures now double as the floor's pins. Sub-gate residue became visible in acp_status (previously invisible on every surface). No config/env surface added; nudge prompt text untouched (kernel-owned). Known limitation left as a separate observation: the receipt's remaining-calc removes a WHOLE offered batch when any submitted span overlaps it, so a partially-folded merged batch can under-report rather than over-report.
|
||||
|
||||
Tests: `tests/issue4331-uncovered-history.test.ts` (hole session → honest verdict + named span; drained session → verbatim contract string; sub-floor silence; tier precedence; **tier-2 distillation coverage pin** — three T1s distilled into one T2 parent via the real host path must not leak child spans into the audit; both acp_status directions; formatter caps) + `tests/compress-success-tail.test.ts` UNCHANGED from master (its < 10K-residue fixtures pin the floor), `tests/issue2029-status-baseline-provenance.test.ts` (every status-reader kernel call feeds the provenance baseline), `tests/issue847-compress-failure-guards.test.ts` (sub-gate residue visible in the diagnostic, still never offered).
|
||||
> Moved to [docs/technical-notes.md](docs/technical-notes.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -1,132 +1 @@
|
||||
# 技术细节
|
||||
|
||||
README 三种使用方式背后的机制级说明。README 里每种方式只保留简洁的用法;「它到底怎么工作」的内容都放在这里,而不是夹在三种方式中间。
|
||||
|
||||
## 原生插件生命周期(方式 1)
|
||||
|
||||
插件加载时**自拉起自己的代理**(已有健康实例则直接复用 —— 父进程 pid 看门狗在客户端退出时收掉它),把模型流量改写到 `<proxy>/bili/<上游URL>`,把 `compress` / `decompress` / `acp_status` 注册为客户端原生工具(plugin 模式),并把 `/acp` 面板绑定到当前会话。插件还会把客户端**自己的模型配置**上报给代理(runtime-info 协议,#955),压缩预算用真实窗口而不是注册表猜测。退出开关:`BILI_NATIVE_PI=0`、`BILI_NATIVE_OMP=0`、`BILI_NATIVE_OPENCODE=0`、`BILI_NATIVE_DSH=0`、`BILI_NATIVE_KIMI=0`、`BILI_NATIVE_HERMES=0`、`BILI_NATIVE_ZCODE=0`。
|
||||
|
||||
## 代理复用与附着门禁(#1225、#1335、#1232、#1660)
|
||||
|
||||
原生 hook 可以附着到已在运行的代理而不自己拉起 —— 仅当通过下面的生命周期门禁。复用基于身份(#1225):只有当既有代理运行的是**同一份代码**(入口脚本 sha256,记录在实例文件里)、**lane 兼容**(每个启动器声明其客户端 lane,两个*不同声明的* lane 永不共享;未声明 lane 的实例是手工拉起的用户主权区守护进程,在该轴上通配)、**且通过生命周期门禁**(见下:armed 父进程 pid 看门狗 `watchdog.armed == true`,即由带父 pid 的启动器拉起、随最后一个附着会话消亡;**或**属用户主权区实例 —— 无 lane、无 launch token —— 按定义豁免,#1660)时才附着。#1225 之前写入的实例没有代码指纹,因此永不附着:重建或更新后的安装下次启动总会拉起新代理,修复立即生效而不是静默服务旧代码。
|
||||
|
||||
| 监听者 | 附着? | 原因 |
|
||||
|---|---|---|
|
||||
| 本会话拉起的代理 | ✅ | 出生即 armed |
|
||||
| 其他会话的 armed 共享代理(watcher 集,#1186) | ✅ | 共享本就是设计 |
|
||||
| 手工 `bili start` 常驻守护进程(用户主权区,#1660) | 🔶 视情况 | **用户主权区**实例(无 lane、无 launch token):一台**已武装**的(受管共享代理,#1225)会被任何兼容 client lane 搭车;一台**未武装**的手动守护在默认(`attachPolicy: own-lane`,#2877)下**不会**被 lane 型 hook 搭车 —— 它自行派生。仅在 `attachPolicy: global-fallback`(pre-#2877)或 `attachExternal=1` 下被搭。无论哪种,寿命与版本由你自己负责 |
|
||||
| 未武装的 **lane 型**代理(崩溃会话孤儿;pre-#1330 不可验证) | ❌ 大声拒绝 | 生命周期漂移症状(#1335):搭乘等于静默复用无人管理的代理 |
|
||||
|
||||
hook 附着前先探测候选者的 `/__bili/health`:armed → 附着并注册 watcher(现状不变);一台**已武装的用户主权区**候选无论 lane 亲和策略都附着(受管共享代理,#1225);一台**未武装的用户主权区**(手动)候选仅在 `attachPolicy: global-fallback`(pre-#2877)或 `attachExternal=1` 下附着 —— 默认(`own-lane`)lane 型 hook 自行派生(#2877);未武装的 **lane 型**候选(崩溃会话孤儿,或 pre-#1330 构建根本不报 `watchdog` 字段 —— 不可验证,按 unarmed 处理)被**大声拒绝**,本会话在自管端口区自拉起代理(基准口 `18787` 或该 lane 粘性漂移记录;出生即 armed、随最后一个会话消亡,#1186 watcher 语义)。版本偏斜仍被修住:代码指纹检查先行,重建/更新后的安装即使经用户主权区豁免也永不搭乘陈旧守护进程。代价:无可附着实例时每会话多一个短命代理进程(会话状态在磁盘上共享,压缩连续性不受影响);多实例告警(#394)相应变多。**逃生舱:** 配置文件 `"native": { "attachExternal": true }` 或 `BILI_NATIVE_ATTACH_EXTERNAL=1` 把附着扩展到 *lane 型*监听者(无论看门狗状态,含 pre-#1330 构建)—— 那些守护进程的寿命与版本由你自己负责;`attachExternal` 只管辖 **lane 型**守护的*生命周期门禁*(它并不开/关对 user-zone 的附着 —— 那个轴是 `attachPolicy`);`attachUrl`(env `BILI_MCP_PROXY` / `--origin`)钉住显式目标 origin。kimi/dsh 的显式用户指定附着(`BILLION_CONTEXT_ATTACH` / 预置 `BILLION_CONTEXT_PROXY`)完全不经过发现路径,构造上豁免。
|
||||
|
||||
附着发现在**所有**存活实例间是 lane 感知的(#1232):启动器探测实例注册表里的每一条存活记录,而不只是单个实例文件(last-writer-wins —— 并发多客户端下它可能指向别的客户端的代理),并对每个候选应用上面的门禁。兼容候选中,lane 与启动器自身声明一致的最新实例胜出;未声明 lane 的实例(用户主权区守护进程)在 lane 轴上通配,且门禁默认豁免(#1660)。`another bili instance is running` 告警(#394)也是 lane 感知的:同 lane 或无 lane 共存时触发,两个*不同声明* lane 之间保持沉默(它们的会话文件互不相交)。
|
||||
|
||||
## 共享 state 目录与多实例安全边界(#394、#1724)
|
||||
|
||||
同一台 host 上的每个 bili 实例读写的是**同一组** per-host 存储:XDG data 目录(`~/.local/share/billion-context/` —— 会话记录、CCR content-store、prefix-affinity)加 state 目录(`~/.local/state/billion-context/` —— 日志、实例注册表)。控制面是 lane 感知的(#1232:附着发现与 #394 共存告警都尊重已声明 lane),但**数据面没有分区** —— 既无按会话的属主,也无按 lane 的磁盘隔离。由此带来两个后果:
|
||||
|
||||
- **跨实例会话可见。** 每个实例的 Web UI(`__bili/sessions` list / detail / logs)都会重新扫描整个共享存储,因此任何经回环可达的实例都能枚举并读取*任意*会话 —— 原始报文、content-store 载荷、压缩块 —— 无论它由该 host 上哪个其他实例/lane 创建。
|
||||
- **重启 drain 竞态。** 重启时新进程在旧进程完成 flush 之前就 hydrate 了存储,last-writer-wins 可能丢掉旧进程的最终写入:tail 更新丢失,以及 provider 前缀缓存击穿(出站 body 与 provider 已缓存的前缀分叉)。#1724 的缓解措施:#405 快照计数器守卫(拒绝陈旧会话写入)、prefix-affinity union-on-write 守卫(#1737:一个实例的 flush 永不覆盖兄弟 chain)、自重启顺序修复(#1742:durable state 在替换进程 spawn 之前落盘)。host 驱动的重启(dsh 等,#991)仍依赖这些数据层守卫,因为其 kill/spawn 顺序不受 bili 控制。
|
||||
|
||||
**安全边界:** 共享 state 面目前**仅**由管理端点的回环门禁(非回环源地址被拒绝)+ 用户 home 树下这些目录的文件系统权限保护(两个目录都在 $HOME 下)—— 没有按会话的鉴权。对**单用户 host** 这已足够。对**多用户 host** 则不够:任何能触达代理回环端口的本地账户都能读取所有用户的所有会话。这类 host 必须给这组 per-host 存储分区(按用户/按 lane 子目录)—— 即 #1724 指出的根因修复(direction #1),目前仍作为架构决策开放;Web UI scoping(#1724 direction #4)能减少跨实例浏览,但不改变这一边界。
|
||||
|
||||
## Runtime-info 协议(#955)
|
||||
|
||||
原生插件就在客户端进程里,因此能读到客户端自己将要使用的模型配置。它通过两个通道把真相推给代理,代理在上下文窗口解析链里优先采用它而不是 models.dev 注册表/内置表:
|
||||
|
||||
| 通道 | 时机 | 字段 |
|
||||
|---|---|---|
|
||||
| 逐请求头(门控在 `x-bili-plugin`) | 每次模型请求 | `x-bili-plugin-context-window`、`x-bili-plugin-max-output`、`x-bili-plugin-model` |
|
||||
| `POST /__bili/plugin/runtime-info`(回环地址) | 插件自举 + 任一上报字段变更 | `{agent, model, contextWindow?, maxOutput?, baseURL?, conversationId?, source}` |
|
||||
|
||||
窗口解析顺序:`anthropic-beta` 协商 > 逐请求 plugin 头 > runtime-info > launcher 环境变量 > 路由配置 > models.dev 注册表 > 内置表。runtime-info 这一步:带 `x-bili-plugin` 头的请求读**按 agent 的条目**(agent+model 必须匹配);不带该头的请求解析以 `conversationId` 记录的**会话级条目**,键与会话绑定的同一会话信号一致(客户端会话头、自定义 session 头或请求体的 `prompt_cache_key`)—— 无论哪种,model 都必须匹配(#1531:omp 打 `prompt_cache_key` 但不打 plugin 头,且主/子代理会话共用 agent 名却跑不同模型)。上报的 `maxOutput` 仅在请求体自带输出预算缺席时兜底。现有实现:`src/agent/pi.ts`(覆盖 pi 与 omp)、`src/agent/opencode-native.ts`(v1)、`src/agent/opencode-v2.ts`、`src/agent/dsh-native.ts`、`src/kimi/native-mcp.ts`(仅自举时上报 —— kimi 的 provider `custom_headers` 是静态的,逐请求头会在模型切换后过期)、`hermes-plugin/__init__.py`(Python 插件:经 `llm_request` 中间件打逐请求头,`pre_api_request` hook 捕获最大输出与宿主 per-model 上下文窗口 —— 窗口读自 hermes 自己的 `HERMES_HOME/context_length_cache.yaml`,任何缺失/歧义 fail-open(#3261))—— 其他客户端接入请遵循同一协议。
|
||||
|
||||
**omp:当 OMP 的 Cowork 传输接管出口时,不打 `prompt_cache_key`(#2583/#3556)。**native omp 模式下,打上的 `prompt_cache_key` 是唯一的逐请求会话信号,其唯一消费者是 bili 自己的 fetch 层拦截器(把模型 URL 改写成 `<proxy>/bili/<url>` 并在转发前剥掉该字段)。较新的 OMP 构建带有 "Cowork 传输"(2026-07-30 引入,can1357/oh-my-pi `642892ae`;代理处理 `e22a5ff2`):默认 `anthropic`/`anthropic-messages` 请求经 node:https **直发** —— 除非显式代理环境变量(`PI_PROXY` / `PI_PROXY_ANTHROPIC`)把它们推回 Bun 的 fetch,否则根本不经过 `globalThis.fetch`。自 #3556 起,`bili omp` 启动器自行关闭了这一缺口:除非用户已设置 `PI_PROXY` / `PI_PROXY_ANTHROPIC`,否则它会导出 `PI_PROXY_ANTHROPIC=<proxy origin>`,因此在默认启动器通道上,Cowork 走可压缩通道(打上的 key 由代理消费并剥离),而非直发。打戳放弃同时门控 cert-MITM 通道 —— #3556 把它提到了目的地路由检查之上,嵌套放置会完全跳过它。在那条路径上打戳会让字段原样进入 Anthropic 严格 schema(HTTP 400 `prompt_cache_key: Extra inputs are not permitted`)。打戳闸门(`src/agent/pi.ts` 的 `stampPromptCacheKey` → `ompCoworkTransportBypassesFetch`)镜像 OMP 自己的按模型出口选择:证明直发时不打戳,并每进程每模型警告一次。后果:这些直发请求不经压缩、对代理匿名(身份/面板/账单退化 —— 与 #1403 同一取舍);其余 lane(launcher `/bili/` 改写、MITM 白名单、其他 provider/api、配置了代理的宿主)不受影响。已知残留:`NO_PROXY`/`no_proxy` 规则命中模型 host 时,即使设置了 `PI_PROXY` / `PI_PROXY_ANTHROPIC`,OMP 的代理处理也会被静默 —— 请求直发但已打戳(同类 400);这类 host 应从 `NO_PROXY` 中移除而非依赖打戳闸门。反向不对称是 fail-safe 的:OMP 的按形状 fetch 回退(Request 对象入参、非 record headers、不支持的 body)即使没有任何代理环境变量也会走回 `globalThis.fetch`,那里放弃打戳只退化身份、不会硬失败。完整覆盖需要宿主侧变更(Cowork 出口改走 `globalThis.fetch`)—— 作为边界注记记录在 #2583。
|
||||
|
||||
launcher 环境变量这档覆盖纯代理客户端(无进程内插件):`bili <client>` 启动时读客户端自己的模型配置(codex 的 `model_context_window` / `model_max_output_tokens`,pi / omp 的 `contextWindow` / `maxTokens`,opencode 的 `limit.context` / `limit.output`,codebuddy 的 `maxInputTokens` / `maxOutputTokens`),经 `BILI_LAUNCHER_MODEL_WINDOWS` / `BILI_LAUNCHER_MODEL_MAX_OUTPUTS` 交给代理(#971)。插件上报 —— 若存在 —— 永远优先于它。
|
||||
|
||||
首次模型请求之前会话尚不存在,`/acp` 面板会探测 `GET /__bili/plugin/status?conversationId=<agent>&fallback=latest`,代理从 runtime-info 表应答(`phase: "pre-first-request"`)而不是返回 404 —— 上报的配置立即可见,流量落地后由真实会话接管。
|
||||
|
||||
## Claude 原生姿态(#964)
|
||||
|
||||
Claude Code 没有进程内扩展点,所以 `bili plugin install claude` 往 `~/.claude/settings.json` 写一个受管块(env `ANTHROPIC_BASE_URL=http://127.0.0.1:<port>/bili/<upstream>`、`DISABLE_AUTO_COMPACT=1`、`SessionStart` hook),外加同样的用户级 MCP shell。hook 在首个模型请求前触发,端口解析与所有 lane 一致(#1660):显式钉死(`BILI_CLAUDE_NATIVE_PORT` > config `claude.nativePort`)→ 该确切端口**严格端口**启动(占用者被大声拒绝,#964 保留);否则骑自管区 —— 该 lane 粘性记录优先,否则基准口 `18787` —— 非严格,子进程 EADDRINUSE +1 阶梯解决碰撞,落定端口粘性记录。阶梯有一个例外(#1723):lane 端口的持有者是**不同构建**的同 lane 实例(升级重启重叠——旧版本还在排水)时,子进程等它释放(最多 5 秒)后复用*同一*端口,而不是漂移;持有者永不退出则等待预算耗尽,照旧走 +1 阶梯。代理就绪后 hook 每会话把受管 `ANTHROPIC_BASE_URL` 重钉到存活 origin(`repinClaudeManagedBaseUrl`),跳口后下次启动自愈,烘进 URL 永不与运行中代理失步。上游覆盖:`BILI_CLAUDE_UPSTREAM`(或既有 `claude.anthropicBaseUrl`)。install 不再持久化 `claude.nativePort`。`BILI_NATIVE_CLAUDE=0` 退出 —— hook 改为在同一解析端口上拉起 **passthrough** 代理(原样转发、关闭压缩)。块是纯 JSON merge/strip:外部键从不触碰,`bili plugin remove claude` 精确还原。装有原生块的机器上 `bili claude` 仍可用 —— 它用自身代理覆盖静态 URL,hook 保持休眠。
|
||||
|
||||
## 注入优先级 —— 能不写文件就不写(#535)
|
||||
|
||||
bili 永不拥有用户数据:每个被启动的客户端都跑在**真实 home** 上,运行期写入落在用户预期的位置。把客户端指向代理时,启动器按优先级选择——**优先 env 变量**(hermes/dsh/codex 的代理/CA env;pi/omp 的 `BILI_PROVIDER_REWRITES` URL 清单,由扩展加载时经 `registerProvider` 消费),其次 **CLI 参数或扩展 API**(codex `-c key=value`、opencode 插件),最后才是**生成文件**——目前仅剩 opencode 的临时 `opencode.json`(退出即删)和 dsh 的回环例外:dsh 的 fetch 栈对回环目标无条件绕过代理 env,所以本地上游保留持久 `~/.dsh-bili` overlay 改写,直到 dsh 提供 settings-path env 或上游支持回环 opt-out。旧版本创建的 overlay 目录原地保留,绝不合并回真实 home。
|
||||
|
||||
## 两种压缩模式 —— 谁执行 `compress`
|
||||
|
||||
代理有两种工作模式,**模式决定谁来执行 `compress`,进而决定摘要以什么形式("载体")到达模型**。这一区分是 #377 的根源。
|
||||
|
||||
| | **启动器 / 插件模式**(`bili pi`、`bili codex`、…) | **代理模式**(普通客户端 → `/bili/`) |
|
||||
|---|---|---|
|
||||
| 客户端 | 带 bili 扩展的 ACP 原生 agent(pi/omp) | 任意 OpenAI/Anthropic 客户端,无扩展 |
|
||||
| 谁执行 `compress` | **agent**(pi 在本地执行) | **代理**(服务端压缩循环) |
|
||||
| 重发历史里有 `compress` 工具调用吗? | 有 —— agent 自己对话的一部分 | 没有 —— 临时性的代理循环流量 |
|
||||
| 预检块(没有工具调用时)? | 最后防线 —— agent 通常靠自己的 `compress` 调用压缩,但仅输入就超窗时 `src/preflight.ts` 仍会触发(两种模式都如此,#470) | 有 —— `src/preflight.ts` 在客户端背后压缩 |
|
||||
| **线上摘要载体** | **`compress` 工具调用本身** | **一条 `acp_summary` user 消息** |
|
||||
| 线上的 system 消息 | 恒为 1 条(客户端 + prompt) | 恒为 1 条(客户端 + prompt)—— 摘要走 user 消息 |
|
||||
| SGLang「单 system」400(#377) | 不可能发生 | 不可能发生(摘要是 user 消息,不是 system) |
|
||||
| 代理注入的 `compress` 工具 | 无 —— agent 原生注册 4 个 ACP 工具 | 4 个上下文工具(启用时) |
|
||||
| 代理注入的 nudge | **有** —— agent 自己没有 nudge 通道,代理侧 nudge 就是主动压缩触发器(仅预检只在硬上限才触发;#451) | 有(启用时) |
|
||||
|
||||
**为什么载体不同。** 插件模式下 agent 拥有压缩权:`compress` 调用 + 结果都在 agent 自己的历史里、每轮重发,所以摘要搭在工具调用上,agent 视图从不渲染内核的 `acp_summary` 兜底(`billion-context-pi` 的 `src/messages.ts` 跳过 `acp_summary_*`)。代理模式下客户端不是 ACP 原生的,由代理在服务端执行 `compress`;工具调用从不进入客户端历史,预检块则根本没有工具调用 —— 于是内核的 `acp_summary` 消息成为唯一载体。内核把它渲染为 role `system`,但严格的 OpenAI 兼容后端(SGLang)要求 index 0 处恰好一条 system 消息,所以 `systemToUser`(`src/util.ts`)把它改声为 `user` 消息,留在原锚点位置。这使头部 system 消息(前缀缓存锚点)在压缩轮之间保持字节稳定,新块不会使整段对话前缀失效。
|
||||
|
||||
**为什么是 `user`,而不是 `system` 或伪造的工具调用。** 流中间的 `system` 消息正是 SGLang 拒绝的东西(#377)。伪造一个 `compress` 工具调用是「更纯粹」的载体,但在代理模式下需要按 id 捏造 assistant `tool_calls` + user `tool_result` 对、在请求里声明该工具、还要处理没有真实调用的预检块 —— 远比改声一条独立笔记侵入得多。`user` 消息允许出现在对话任何位置,是同时满足 SGLang 单 system 规则与前缀缓存稳定的最小改动。接受的取舍:摘要是被折叠历史的替身,把它改声成 user 回合是一种模型能容忍的语义错位(它被明确标记为 `[Compressed conversation section]`)。
|
||||
|
||||
**两种模式能共存吗?**
|
||||
|
||||
- **同一代理实例:可以,且是设计使然。** 一个代理同时服务插件客户端与普通客户端;`pluginMode` 按请求判定(`x-bili-plugin` header)、按会话绑定(`session.metadata.pluginAgent`)。启动器复用已在跑的代理。
|
||||
- **同一会话:模式是粘滞的。** 插件模式创建的会话保持插件模式(metadata 继承);普通会话只能被*升级*为插件模式 —— 当带匹配会话 id 的插件请求到来(header 优先)—— 且永不降级。实际上 plain→plugin 升级要求插件客户端的会话 id 与既有普通会话 id 相同,而这不会发生(各客户端自生成 id)。
|
||||
- **跨模式块风险:仅理论存在。** 它需要同一个会话 id 跨越一次模式切换。plugin→proxy 安全(工具调用在共享历史里);proxy→plugin 可能孤立代理创建的块摘要(其工具调用不在 agent 历史里,而 agent 视图跳过 `acp_summary`)—— 但那需要上述的 id 匹配,实际不会发生。
|
||||
|
||||
**如何验证一次压缩真的落地了。** 执行 `compress` 后,代理以纯 assistant 文本发出确认标记(`📦 [ACP] Compressed …`)—— 但在持续上下文压力下曾观察到模型*自行写出该标记格式*却从未调用工具(#717):约 2 小时内 17 次假「压缩」,真实用量一路涨到 89%。因此转录中可见的标记行不是持久化的证明 —— 先以 `acp_status`(块数增加、可压缩区间起点前移)核实再采信。作为兜底,代理会剥离模型自行发出的任何形似标记的行并记 `[marker-echo]` 警告,nudge 与注入提示也都明确声明标记只由代理发出。
|
||||
|
||||
## 单写者:哪份拷贝归谁管(#991)
|
||||
|
||||
一台机器上每一份 bili 存在物恰好有**一个写者** —— 装它的那个东西负责更新它,其他任何东西都不就地覆盖那份拷贝:
|
||||
|
||||
| Lane | 拷贝住在哪里 | 由谁更新 |
|
||||
|------|---------------|------------|
|
||||
| 全局 `bili` | npm global(`npm i -g billion-context`) | `bili update` / 后台自动更新 |
|
||||
| **pi** | pi 的包管理器(npm 形态) | **`pi update`** —— bili 从不覆盖 |
|
||||
| **opencode** | opencode 的插件目录 | **opencode 的插件管理器** —— bili 从不覆盖 |
|
||||
| **dsh** | 每个 profile 的 pnpm store | 周期性检查按 profile 重跑 dsh 插件通道 —— 由全局 bili 自更新驱动,**或在全局没跑时由 profile 拷贝自己的代理驱动**(dsh 市场安装,#1196);手动:`dsh plugin add billion-context@latest`。pnpm 硬链接 store 绝不可就地覆盖拷贝 |
|
||||
| omp / claude / codex / kimi / zcode | 无拷贝 —— 条目指向全局 bili 安装 | 随全局拷贝一起更新 |
|
||||
| **hermes** | `~/.hermes/plugins/billion-context/`(拷贝文件 + 指向全局 dist 的 `bili.json` sidecar) | **`bili plugin update hermes`** 重新拷文件;sidecar 跟随全局安装 |
|
||||
|
||||
这在代码里强制,不只是约定:自更新器(`src/update.ts` → `hostManagedInstall`)识别 pnpm 虚拟 store(`.pnpm`)或宿主 agent 树(pi / opencode / dsh / kimi / omp home)下的安装目录并**跳过**它们;`installViaTarball` 从结构上拒绝它们,直接调用方也无法损坏 store。混用*命令*没问题(`dsh plugin add` ≡ `bili plugin install dsh` —— 同一通道、同一记录);混用*写者*才是守卫禁止的事。`bili plugin update [client]` 是唯一能驱动每条 lane 走各自 owner 的命令,并打印逐 lane 更新路径(`bili plugin list` 显示同样的逐 lane 通道)。
|
||||
|
||||
## 会话卡死自愈 —— 检测常量与补救(#2155)
|
||||
|
||||
三种故障形态共享 `src/session-self-heal.ts` 里的同一族检测器,每请求评估一次(prepare 之后,仅有 nudge 的主车道;旁路/侧请求车道不积累信用):
|
||||
|
||||
- **D2 僵尸插件车道** —— 插件已卸载(或 MCP 子进程已死)但已开着的客户端窗口仍带着插件绑定(粘滞 `metadata.pluginAgent`)。信号:连续 5 轮(`SELF_HEAL_WINDOW`)被 nudge、**无** `x-bili-plugin` 头、线上**无** bili 工具声明、**零**压缩缩减。补救:**降级为代理模式** —— 单点 `pluginMode` 翻转(`pluginAgent !== undefined && !pluginLaneDegraded(session)`)线上回注 ACP 工具、重新接管压缩 rewriter/CCR 盖章/absorb,并**保留 nudge**(工具回来了)。线上注入不可用时(`compress.injectTool=false` → `degradeAvailable=false`)退为**静默 nudge**。恢复:**活的**插件头(`pluginLaneRestore`,在 `pluginMode` 翻转**之前**调用,首个带头请求即恢复 plugin 模式 —— 恢复信号绝不能用粘滞 `pluginAgent`,否则降级一轮后即被自己清掉)。绑定保留、永不抹除。
|
||||
- **D1 nudge 空转**(非插件泛化)—— 连续 5 轮被 nudge 却零缩减、零 bili 工具调用。补救:在全部四处 `willInjectNudge` 门加 `&& !nudgeSuppressed(session)`(覆盖 emergency 路径)。恢复:任一次压缩缩减或 bili 工具调用即解除——或者在 `SELF_HEAL_SUPPRESS_CAP_MS`(10 分钟)内两者皆无时,抑制到时自解并重新武装(#3004/#3008:上下文单调增长时永远产生不了恢复证据,纯证据式解除曾把建议通道锁死一个多小时而用量停在 ~75%)。重新武装是有界的:再空转完整一个 `SELF_HEAL_WINDOW`(5 轮)才会再次抑制;决策梯的 fallback 逃逸在抑制期间仍可打出一次性 legacy 建议(`consumeFallback` 重置计数)。
|
||||
- **D3 网关杀摘要** —— **非流式** preflight 摘要以 HTTP 524/504(Cloudflare 类)死亡时不再原地重试(旧的 transient 重试对着死网关每次烧 ~100 秒);会话在**首次**命中即学习 `metadata.preflightStreamSummary = true` 并改用 SSE 重取摘要 —— 与手动 `compress.streamSummary` 旋钮(#2133)同一学习存储,自动武装。级联双向被尊重:任一级显式 `streamSummary: false`(global → provider → model)即操作员 opt-out —— 两条学习路径都不武装、已学习的旧标志被忽略(`PreflightDeps.streamSummaryOff`)。
|
||||
|
||||
可观测:`session.metadata.selfHeal = { detected, action, since }` 进 `/__bili/sessions`、web UI 挂"自愈"徽标、每次转换一行 `[self-heal]` 日志(检测+恢复)。`bili plugin remove <client>` 尽力查询活代理(instance 文件 → `GET /__bili/sessions`,2.5 秒超时,失败静默),该客户端近 **10 分钟**内有活跃会话时打印提示。
|
||||
|
||||
## ACP 标签回声统一整治 —— 四条不变量(#2023/#2066/#2190/#2248)
|
||||
|
||||
一个 PR 把三条整治腿合并(refs-run 残留 #2023、退化闭名剥离+出口审计网 #2190、emission 整段丢弃+签名思考 verbatim #2066),并统一受四条硬规则约束 —— 覆盖**所有**文本改写面(loop 适配器、插件直通、JSON strip 函数、出口审计):
|
||||
|
||||
1. **思考通道逐字节不动。** Anthropic `thinking`、Google `thought`、OpenAI `reasoning_content`/`reasoning`、Responses reasoning summaries 原样透传 —— 哪怕长得像标签回声。理由:reasoning 回放(DeepSeek 式)与签名校验验证的就是这些字节,任何改写都会让它们失步并卡死会话(#1960/KDD#10)。适配器侧走 `createIdentityStreamFilter`,strip 函数(`stripOpenaiChatText`、`stripResponsesText`)同样不动它们(纵深防御)。**注意:这翻转了 #1881 时代的 reasoning 回声剥离 —— 思考通道不再清洗。**
|
||||
2. **模型的正文输出可以治理。** 渲染标签回声、marker 行、bili 内部文本、退化开/闭名残骸,以及(absorb 受指令时)整段工具调用 emission,只在可见文本通道剥离。
|
||||
3. **模型写入文件的内容逐字节不变(#1039)。** 工具调用 arguments 无论携带什么字节都不进任何过滤器。
|
||||
4. **用户发送的消息永不被改写。** 用户自己片段的逐字回声在武装清洗下也保留(#463 豁免,按请求文本匹配,不按形状)。
|
||||
|
||||
出口审计网(#2248)保持仅记日志:裸出口(未识别帧、解析失败)原样转发并打 `[tag-echo] raw exit` 日志,新泄漏形状可见而不改线上行为。由 `tests/unified-acp-invariants.test.ts` 钉住(8 个测试,两条 lane)。
|
||||
|
||||
## OpenAI 聊天线路的 `prompt_cache_key`:默认处处打戳,严格上游用受控 A/B 保护(#2218/#2645/#3556)
|
||||
|
||||
dsh 插件道中,body-keyed 中转站能读到的身份信号只有一个:请求体的 `prompt_cache_key`(会话头 `x-bili-plugin-conversation` 是 bili 内部头、不会以原名转发;读头的中转拿的是 `x-session-id`)。两个相互冲突的群体在这里相遇:严格的直连 API 会对未知 body 字段回 400 —— 而且严格性是**同源按模型**的(#2645:同一个 NVIDIA 网关下,一个模型收这个 key,它的兄弟模型拒收);而号池(包括**远端**中转池)把这个 key 当前缀缓存路由来读,在哪里丢它都会无声地拉低那些会话的缓存命中(#1403 类的反面)。目的地形状的门控裁决不了这件事:只给回环盖章(#2649 的尝试)治好了严格 API,却让两类最大的池子群体(docker 网桥/局域网/VPS/域名池)失去亲和。最终设计 = **默认全盖章 + 实证自愈(probe-and-remember)**,在 #2649 评审中由 owner 定案:
|
||||
|
||||
- **打戳**(`resolveRelayAffinityPck`,`src/session-id.ts`)—— 插件道对**一切**目的地默认盖 `prompt_cache_key=<会话 id>`;客户端自带的 key 在其配对被 A/B 证实前原样透传。零配置面:无新配置字段、无环境变量、无 CLI 旗标。
|
||||
- **探测**(`src/server/relay.ts`,与 #552 兼容阶梯同一 buffered-body 缝)—— 出口体带着该 key 的**第一个** 400 触发:把同一 payload 去掉 `prompt_cache_key` 后重发一次。重试成功 ⇒ 因果坐实:采用该响应,把 `origin(+model)` 记入进程内存(`src/pck-probe.ts` —— **仅内存**,重启重新探测)。重试也失败 ⇒ 不是这字段的锅:丢弃重试,把原始 400 原样转发,什么都不学 —— key 保留,下一轮再探(400 成因很多;只有 A/B 判词可以停用)。每请求至多探一次;无循环。
|
||||
- **记忆效应** —— 被停用的配对在后续轮次同时停掉 bili 自己的戳和客户端自带的 key(否则每轮都要重付一次 400 往返)。粒度是 origin+model:共享池源上一个严格模型不影响兄弟模型。解析不了的 origin 一律 fail-open(保持盖章)。
|
||||
- **可见性** —— 首次停用打 WARN 日志,写明 origin/model、受影响会话、以及号池提示(该目的地可能是你的中转/号池,前缀缓存亲和可能下降);`acp_status` 段与网页面板横幅(中英)展示当前停用列表与会话;脚本可经 `GET /__bili/status` 的 `pckSuppressions` 字段读取。全程进程级状态,重启即清空并重新探测。
|
||||
- **双模式推理** —— 只有插件道(注册 agent / dsh 插件,内部会话头在场)会打戳;纯代理模式双向都是原样透传,逐字节不变。
|
||||
|
||||
pi/omp 线路沿用各自的独立打戳门(上文 Responses 线路的 `prompt_cache_key` 提升、Cowork 弃戳)——本节只讲 OpenAI **聊天**线路。
|
||||
> 已迁移至 [docs/technical-notes.zh-CN.md](docs/technical-notes.zh-CN.md)。重定向占位,1–2 个版本后删除。
|
||||
|
||||
@@ -1,173 +1 @@
|
||||
# Unified Compress-Loop — Design Spec (Phase 1+2)
|
||||
|
||||
## Problem
|
||||
The generic billion-context proxy's three `compress-loop-*.ts` files have an **injection-persistence** bug: the philosophy prompt (injected as a conversation message, not a transient system prompt) and accumulated proxy-tool records PERSIST across re-request rounds, re-priming the model → on rare model paths the model loops `acp_status`/`search_context` until the loop-limit fires a degenerate empty completion (the 炸锅). Root cause confirmed by the user.
|
||||
|
||||
`executeProxyTool` is also copy-pasted ×3 (compress-loop.ts:47, compress-loop-anthropic.ts:59, compress-loop-responses.ts:85).
|
||||
|
||||
## Reference (the ONLY behavioral reference)
|
||||
**billion-context-pi** (`/home/dog/projects/billion-context-pi/src/`), the Pi adapter. It uses an **executor model** (one tool call = one Pi turn, no loop). Key principles to mirror in the loop:
|
||||
- `wireSystemPrompt` (index.ts:229-235): philosophy is a **transient system prompt** returned via Pi's `before_agent_start` event — rebuilt fresh each turn, NOT in message history, does NOT accumulate.
|
||||
- `wireContextTransform` (index.ts:103-227): runs `core.processTurn({messages, state, config, tokenCount})` once per LLM call; nudge is a **per-turn append** (comment index.ts:178-179: "the next context event rebuilds the array from scratch, so it does NOT permanently pollute context").
|
||||
- Kernel `hideConsumedCompressCalls(state, messages)` runs inside processTurn each turn (hide-consumed.ts, exported index.ts:51) — hides consumed/failed compress records, keeps active-block compress calls ("压缩成功留着"), rewrites kept compress text to live ranges.
|
||||
- Kernel `protected.ts`: `ALWAYS_PROTECTED_TOOLS=["compress"]`, recent-zone + last-user protection.
|
||||
|
||||
**Alignment goal**: the proxy's loop must apply the SAME per-turn hygiene bili-pi gets for free (transient philosophy + hideConsumed), but per ROUND of the loop.
|
||||
|
||||
## Architecture: protocol-agnostic core + thin adapters
|
||||
|
||||
### Core message type (acp-kernel, types.d.ts:3-10)
|
||||
```ts
|
||||
interface CoreMessage { id: string; role: "user"|"assistant"|"system"|"tool"; contentType: "text"|"tool-call"|"tool-result"|"reasoning"; text?: string; toolName?: string; toolCallId?: string; }
|
||||
```
|
||||
|
||||
### Loop context (mirrors existing CompressLoopResponsesCtx)
|
||||
```ts
|
||||
interface LoopCtx {
|
||||
core: CompressionCore; // acp-kernel
|
||||
config: Config;
|
||||
messages: CoreMessage[]; // original (pre-loop) messages from processTurn
|
||||
session: Session; // has .state (CompressionState), .stats
|
||||
log: (msg: string) => void;
|
||||
proxyUrl?: string;
|
||||
textProtocol?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
### Parsed stream event (what an adapter yields from the upstream stream)
|
||||
```ts
|
||||
type ParsedStreamEvent =
|
||||
| { kind: "text"; delta: string }
|
||||
| { kind: "tool_call"; name: string; callId: string; arguments: string }
|
||||
| { kind: "usage"; inputTokens?: number; outputTokens?: number; cachedTokens?: number }
|
||||
| { kind: "done"; finishReason?: string };
|
||||
```
|
||||
|
||||
### Adapter interface (protocol-specific; one per protocol)
|
||||
```ts
|
||||
interface CompressLoopAdapter {
|
||||
// Build native upstream request body from CoreMessage[] + TRANSIENT system prompt.
|
||||
// The system prompt MUST NOT be added to coreMessages — it is passed fresh each round.
|
||||
buildRequest(coreMessages: CoreMessage[], systemPrompt: string, requestBody: Record<string, unknown>): Record<string, unknown>;
|
||||
// Parse upstream SSE stream → ParsedStreamEvent (extract text deltas, tool calls, usage, done)
|
||||
parseStream(upstream: ReadableStream<Uint8Array>): AsyncGenerator<ParsedStreamEvent>;
|
||||
// Emit downstream (client-facing) events as SSE Buffers
|
||||
emitText(delta: string): Buffer;
|
||||
emitToolCall(call: { name: string; callId: string; arguments: string }): Buffer; // real-tool passthrough
|
||||
emitMarker(toolName: string, result: string): Buffer; // proxy-tool result visibility
|
||||
emitCompletion(opts?: { finishReason?: string; usage?: { inputTokens?: number; outputTokens?: number; cachedTokens?: number } }): Buffer;
|
||||
emitError(message: string): Buffer;
|
||||
// (Optional) extract text-protocol triggers (<acp_compress>...</acp_compress>) from assistant text
|
||||
extractTextTriggers?(text: string): { clean: string; calls: { name: string; callId: string; arguments: string }[] };
|
||||
}
|
||||
```
|
||||
|
||||
### Core loop (protocol-agnostic)
|
||||
```ts
|
||||
async function* runCompressLoop(
|
||||
upstream: ReadableStream<Uint8Array>, // round-1 stream already fetched by server
|
||||
ctx: LoopCtx,
|
||||
requestBody: Record<string, unknown>, // original client request (for tools, model, etc.)
|
||||
requestOptions: { url: string; headers: Record<string, string> },
|
||||
adapter: CompressLoopAdapter,
|
||||
systemPrompt: string, // TRANSIENT philosophy (never added to coreMessages)
|
||||
): AsyncGenerator<Buffer>
|
||||
```
|
||||
|
||||
Round logic (per bili-pi hygiene):
|
||||
1. `for round in 1..MAX_ROUNDS` (MAX_ROUNDS = 10):
|
||||
- Parse `upstream` stream via `adapter.parseStream`.
|
||||
- Accumulate assistant text; for each tool_call:
|
||||
- If PROXY tool (compress/decompress/search_context/acp_status): execute via shared `executeProxyTool`, `yield adapter.emitMarker(...)`, append `{assistant,tool-call}` + `{tool,tool-result}` to a LOCAL coreMessages copy.
|
||||
- Else (real tool): `yield adapter.emitToolCall(...)`, increment `realCalls`.
|
||||
- After stream done: run `hideConsumedCompressCalls(ctx.session.state, coreMessages)` (per-round hygiene, skipped for textProtocol).
|
||||
- Decision: if `proxyResults.length > 0 && realCalls === 0` → re-request: rebuild body via `adapter.buildRequest(coreMessages, systemPrompt, requestBody)`, fetch new upstream, loop. Else → `yield adapter.emitCompletion(...)`, return.
|
||||
- Note: ALL proxy tools (including read-only acp_status/search_context) drive re-request. This differs from baseline (`hasMutatingOnly`) which only re-requested for compress/decompress. V2 re-requests for read-only tools to feed the result back to the model (fixes the tool_calls-no-body hang, commit d8a1e0d). Safety net: MAX_LOOP_ROUNDS=10 graceful completion (never the degenerate empty completion that caused 炸锅).
|
||||
2. Limit reached: `yield adapter.emitCompletion(...)` **gracefully** (NOT a degenerate empty completion). Log it. This is the key fix — never discard the turn.
|
||||
|
||||
### Shared executeProxyTool (de-dup ×3 → ×1)
|
||||
```ts
|
||||
function executeProxyTool(name: string, args: Record<string, unknown>, ctx: LoopCtx): string
|
||||
```
|
||||
Dispatch (identical to current 3 copies):
|
||||
- `compress` → `applyRanges(parseCompressInput(args), ctx)` (stream.ts applyRanges mutates ctx.session.state)
|
||||
- `decompress` → `resolveDecompress(args, ctx)` (decompress-shared.ts)
|
||||
- `search_context` → `ctx.core.search(query, state).slice(limit)` → formatted lines
|
||||
- `acp_status` → `buildStatusReport(state, messages, estimateTokensFast)`
|
||||
|
||||
## File structure (NEW files; keep originals as baseline)
|
||||
```
|
||||
src/loop/
|
||||
├── core.ts # runCompressLoop + LoopCtx + shared executeProxyTool + ParsedStreamEvent + CompressLoopAdapter interface
|
||||
├── adapter-responses.ts # responses adapter (parseStream/emit*/buildRequest)
|
||||
├── adapter-openai.ts # openai /chat/completions adapter
|
||||
├── adapter-anthropic.ts # anthropic /v1/messages adapter
|
||||
└── index.ts # exports: runCompressLoop + a factory pickAdapter(protocol)
|
||||
```
|
||||
Originals (`src/compress-loop.ts`, `src/compress-loop-anthropic.ts`, `src/compress-loop-responses.ts`) stay UNTOUCHED as baseline.
|
||||
|
||||
## Feature-flag wiring (server.ts)
|
||||
In `server.ts:1131-1200`, gate on `process.env.ACP_LOOP_V2 === "1"`:
|
||||
- if set → use `runCompressLoop(...)` with `pickAdapter(protocol)`.
|
||||
- else → existing baseline loops (unchanged).
|
||||
This allows A/B comparison in live tests (`ACP_LOOP_V2=1 bili-test-pi ...`).
|
||||
|
||||
The transient `systemPrompt` = `buildCompressSystemPrompt()` (or `buildCompressTextSystemPrompt()` when `ctx.textProtocol`). Import from compress-tool.ts. Pass as the `systemPrompt` arg — do NOT inject into requestBody.input/messages in core (the adapter places it per-protocol).
|
||||
|
||||
## Per-protocol adapter notes
|
||||
|
||||
### responses (`/response-input`-style `input[]`)
|
||||
- `buildRequest`: convert CoreMessage[] → ResponseInputItem[] via existing `coreToResponses` (responses.ts:324). Place systemPrompt as a developer message at the head of input (skip leading additional_tools; mirror `injectResponsesDeveloperMessage` responses.ts:362-372). Top-level `instructions` MUST stay empty/absent (code_mode requirement, server.ts:803-804). Preserve `requestBody.tools`, `model`, etc.
|
||||
- `parseStream`: responses SSE events (`response.output_text.delta`, `response.function_call_arguments.done` / `response.output_item.added` with function_call, `response.completed` with usage, `response.done`). Reference existing `stream-responses.ts` helpers (buildMessageItemSequence, buildCompleted) + the baseline `compress-loop-responses.ts:454+` stream parsing for the exact event names/shapes.
|
||||
- `emitText`/`emitToolCall`/`emitMarker`/`emitCompletion`: reuse `stream-responses.ts` SSE builders.
|
||||
- text-protocol: `extractTextTriggers` detects `<acp_compress>...</acp_compress>` (ACP_TEXT_OPEN/CLOSE from compress-tool.ts).
|
||||
|
||||
### openai (`/chat/completions`, `messages[]`)
|
||||
- `buildRequest`: `coreToOpenai(coreMessages)` (openai.ts:106). systemPrompt → a `{role:"system",content}` message at messages[0].
|
||||
- `parseStream`: `data: {choices:[{delta:{content?,tool_calls?}}]}` chunks + `data: [DONE]`. Reference baseline `compress-loop.ts` + `stream-openai.ts`.
|
||||
- emit*: `stream-openai.ts` SSE builders (buildFinishSse etc.).
|
||||
|
||||
### anthropic (`/v1/messages`, `messages[]` with content blocks)
|
||||
- `buildRequest`: `coreToAnthropic(coreMessages)` (anthropic.ts:138). systemPrompt → top-level `system` field.
|
||||
- `parseStream`: `content_block_delta` (text_delta/input_json_delta), `content_block_start` (tool_use), `message_delta` (usage), `message_stop`. Reference baseline `compress-loop-anthropic.ts` + `stream-anthropic.ts`.
|
||||
- emit*: `stream-anthropic.ts` SSE builders (buildTerminalSse etc.).
|
||||
|
||||
## Kernel APIs (all already exported from acp-kernel, version 0.0.17 pinned)
|
||||
- `hideConsumedCompressCalls(state, messages)` — hide-consumed.ts (the per-round cleanup)
|
||||
- `createCore`, `CompressionCore`, `processTurn` — compress.ts
|
||||
- `buildStatusReport`, `estimateTokensFast` — report.ts, tokenize.ts
|
||||
- `COMPRESS_PHILOSOPHY`, `HOW_TO_COMPRESS_RULES` — compression-rules.ts (already wrapped by buildCompressSystemPrompt)
|
||||
- types: `CoreMessage`, `CompressionState`, `Config`, `ProcessTurnResult` — types.ts
|
||||
- `coreToResponses`/`responsesToCore`, `coreToOpenai`/`openaiToCore`, `coreToAnthropic`/`anthropicToCore` — local src/{responses,openai,anthropic}.ts
|
||||
|
||||
## Constraints (from AGENTS.md)
|
||||
- No `as any`, no `@ts-ignore`.
|
||||
- Hex escapes (`\x3c`/`\x3e`) for any `<acp>`/`<acp_compress>` XML in source.
|
||||
- Comments only where strictly necessary (priority-3: encodes an invariant). This is an exception — explain WHY transient/dedup matters in 1-2 lines at the core loop's hygiene point.
|
||||
- TypeScript strict, ESM (.js extensions in imports).
|
||||
|
||||
## Test plan (Phase 3)
|
||||
247 tests total (219 baseline + 28 new in `tests/loop-*.test.ts`). Updated to match d8a1e0d (read-only tools now drive re-request):
|
||||
1. **acp_status-only round**: model calls only acp_status → assert (a) marker surfaced to client, (b) re-request happens (result fed back to model), (c) graceful completion at limit, (d) no hang. **No 炸锅.** *(Changed from "NO re-request" after d8a1e0d fixed the tool_calls-no-body hang.)*
|
||||
2. **search_context-only round**: same shape as #1 (re-request + graceful completion).
|
||||
3. **compress round**: model calls compress → assert re-request happens (mutating), result fed back, hideConsumed ran (consumed compress records hidden in round 2 input).
|
||||
4. **decompress round**: re-request happens.
|
||||
5. **limit-hit graceful**: force 10 rounds → assert graceful completion (NOT degenerate empty), no crash.
|
||||
6. **philosophy transient**: assert philosophy appears exactly ONCE per round in upstream body (not accumulated) — spy on fetch.
|
||||
7. **hideConsumed per round**: after a compress in round 1, round 2's upstream body must NOT contain the consumed compress tool-call/result (verify hideConsumedCompressCalls ran).
|
||||
8. **real-tool passthrough**: model calls a real tool (e.g. `bash`) → emitted to client, loop ends (no re-request).
|
||||
9. **mixed**: compress + real tool in same round → forwarded (no re-request), compress executed, marker shown. *(V2 executes compress in mixed rounds; baseline does NOT — documented difference.)*
|
||||
|
||||
### recordUsage semantics (reviewer P1 clarification)
|
||||
`session.stats.inputTokens` ACCUMULATES across loop rounds (`+=` per round) = total tokens consumed (billing/usage). `session.stats.lastInputTokens` OVERWRITES each round = current context size (used by nudge/compression trigger). Both behaviors are intentional and correct for their respective purposes.
|
||||
Run via `node --import tsx --test tests/loop-*.test.ts` (node/npm at /home/dog/.local/bin; npx NOT available, use `npm test`).
|
||||
|
||||
## Verification gate (must pass before declaring done)
|
||||
- `npm run typecheck` (tsc --noEmit) clean.
|
||||
- `npm test` all green (existing + new).
|
||||
- Manual smoke: `ACP_LOOP_V2=1` path at least imports + a round-trip works under mocked fetch.
|
||||
|
||||
## Out of scope for this delegation
|
||||
- Live testing (bili-test-pi/codex/claude) — Phase 4, done by lead.
|
||||
- Double-agent review — Phase 5, done by lead.
|
||||
- Removing/reverting PR#90's MUTATING/READONLY split in baseline files — leave baseline as-is.
|
||||
> Moved to [docs/unified-loop-spec.md](docs/unified-loop-spec.md). Redirect stub; scheduled for removal after 1–2 releases.
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"v": 1,
|
||||
"entries": []
|
||||
}
|
||||
@@ -0,0 +1,99 @@
|
||||
# Independent Third-Party Evaluation of Billion Context (`v0.1.202`)
|
||||
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a></p>
|
||||
|
||||
> **1,500-Item Cross-Benchmark Evaluation across LongMemEval-S, ContextBench, and MemoryAgentBench**
|
||||
> comparing **Billion Context (`bc`)** against **`full`** (raw baseline) and 3 RAG pipelines (**`bm25`**, **`embedding`**, **`embedding-rerank`**).
|
||||
|
||||
---
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
We conducted an independent, strictly controlled third-party evaluation of **Billion Context (`v0.1.202`)** across **3 orthogonal long-context and agent memory benchmarks (1,500 evaluation instances in total, 500 per benchmark)**:
|
||||
|
||||
| Benchmark | Core Scenario | Context Scale | Best Arm | Billion Context (`bc`) Performance | Key Takeaway |
|
||||
| :--- | :--- | :---: | :---: | :--- | :--- |
|
||||
| **LongMemEval-S (LME)** | Multi-session companion chat & temporal memory | ~110k tokens | `full` (83.20%) | **79.20% (2nd Overall)**<br/>**+16.60%** over best RAG (`62.60%`) | Preserves chronological & cross-session reasoning chains where chunked RAG collapses (`79.7%` vs `45.1%` on Multi-Session Reasoning). **-71.1% lower cost** than independent-session `full` (`$2.30` vs `$7.97`). |
|
||||
| **ContextBench (CB)** | Multi-turn SWE coding agent (`Pi CLI v0.73.1`) over 58 real repos | Multi-turn repo exploration | **`bc` (0.3097 F1)** | **0.3097 Utilized F1 (1st Overall)**<br/>Beats `full` (`0.2928`) & all RAG arms | Pruning intermediate tool search noise boosts end-to-end Evidence Precision (`0.3358`, #1) and Utilized F1 (`0.3097`, #1) while cutting cost by **-58.3%** vs `full` (`$4.61` vs `$11.05`). |
|
||||
| **MemoryAgentBench (MAB)** | Extreme static stress test: needle QA, book summarization & 1.48M-token recommendation | 6k → **1.48M tokens** | `embedding-rerank` (55.21%) | **43.54% Macro Avg**<br/>**18.58% Recall@10** on 1.48M TTL (`full` = **0.00%**, crashed) | Survives the 1.48M-token barrier where `full` fails 100% (`199/199` context overflow), compressing 1.48M tokens down to a **49.5k mean (~16k steady-state, 30× compression)**. Trade-off: lossy semantic compression drops verbatim needle QA (`AR`) from `69.0%` to `27.0%`. |
|
||||
|
||||

|
||||
|
||||
---
|
||||
|
||||
## 2. Experimental Setup & Full Cost Attribution Protocol
|
||||
|
||||
To ensure fair, end-to-end black-box comparison, all 5 arms share the exact same upstream LLM, prompt templates, evaluation judges, and token accounting rules (following the Full Cost Attribution methodology of `arXiv:2609.22114`):
|
||||
|
||||
- **Evaluated System**: `Billion Context (BC) v0.1.202` (transparent HTTP context-compression proxy)
|
||||
- **Base LLM**: `DeepSeek V4.1 Flash 1017` (`deepseek-v4.1-flash-opendesign`)
|
||||
- **Embedding Model**: `Qwen3-Embedding-8B`
|
||||
- **Reranker Model**: `Qwen3-Reranker-4B`
|
||||
- **Coding Agent Harness (ContextBench)**: `Pi CLI v0.73.1`
|
||||
- **Unified Pricing Schedule**:
|
||||
- **LLM**: Input `$0.15 / 1M tokens` | Output `$0.60 / 1M tokens` | Prefix Cache Hit `$0.003 / 1M tokens` (with sensitivity verified at `$0.006 / 1M`)
|
||||
- **Embedding (`Qwen3-Embedding-8B`)**: `$0.01 / 1M tokens`
|
||||
- **Reranker (`Qwen3-Reranker-4B`)**: `$0.02 / 1M tokens`
|
||||
|
||||
---
|
||||
|
||||
## 3. Benchmark 1: LongMemEval-S (500 Items, ~110k Tokens)
|
||||
|
||||
**What it tests**: Multi-session user-assistant history requiring **Knowledge Update (KU)**, **Multi-Session Reasoning (MSR)**, **Temporal Reasoning (TR)**, **Information Extraction (IE)**, and **Abstention (ABS)**.
|
||||
|
||||

|
||||

|
||||
|
||||
| Arm | Overall Acc ↑ | Knowledge Update ↑ | Multi-Session ↑ | Temporal ↑ | Extraction ↑ | Abstention ↑ | Mean Input Tokens ↓ | Billed Cost | Indep.-Session Cost ↓ |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **`full`** | **83.20%** | **89.74%** | **84.21%** | **72.18%** | **88.46%** | 86.67% | 106.0k | $0.42* | $7.97 |
|
||||
| **`bc` (Billion Context)** | **79.20%** | **88.46%** | **79.70%** | **70.68%** | 81.41% | 83.33% | **30.5k** | $2.30 | **$2.30 (-71.1%)** |
|
||||
| **`embedding-rerank`** | 62.60% | 66.67% | 45.11% | 49.62% | 86.54% | 90.00% | 14.3k | $1.39 | $1.39 |
|
||||
| **`bm25`** | 56.40% | 62.82% | 37.59% | 42.11% | 81.41% | **96.67%** | 14.3k | $0.08 | $0.08 |
|
||||
| **`embedding`** | 46.40% | 48.72% | 30.83% | 26.32% | 75.64% | 86.67% | 14.3k | $0.68 | $0.68 |
|
||||
|
||||
> *\*Note on `full` billed cost in LME*: Sequential evaluation of queries sharing haystacks yields a 98.1% prefix cache hit rate (`$0.42`). Under realistic independent user sessions (0% cross-user cache reuse), `full` costs **`$7.97`**, whereas `bc` costs **`$2.30`** (**71.1% savings**) while retaining **95.2% of `full`'s accuracy** (`79.20%` vs `83.20%`).
|
||||
|
||||
---
|
||||
|
||||
## 4. Benchmark 2: ContextBench (500 Items, 58 Code Repositories, Pi Agent)
|
||||
|
||||
**What it tests**: End-to-end multi-turn software engineering repository exploration and bug localization using **Pi CLI (`v0.73.1`)**. Evaluates whether the final selected code spans match ground-truth patches (**Utilized F1**, **Precision**, **Recall**, and **Exploration Efficiency**).
|
||||
|
||||

|
||||

|
||||
|
||||
| Arm | Utilized F1 (End-to-End) ↑ | Evidence Precision ↑ | Evidence Recall ↑ | Trajectory Coverage ↑ | Exploration Efficiency ↑ | Total Billed Cost ↓ |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **`bc` (Billion Context)** | **0.3097 (1st)** | **0.3358 (1st)** | 0.3694 | 0.4533 | 0.7279 | **$4.61 (-58.3% vs `full`)** |
|
||||
| **`full`** | 0.2928 | 0.3125 | **0.3712** | **0.4648** | 0.7134 | $11.05 |
|
||||
| **`embedding-rerank`** | 0.2894 | 0.3095 | 0.3547 | 0.4282 | **0.7429** | $6.35 |
|
||||
| **`bm25`** | 0.2600 | 0.2788 | 0.3264 | 0.3999 | 0.7285 | $6.31 |
|
||||
| **`embedding`** | 0.2584 | 0.2757 | 0.3249 | 0.3958 | 0.7327 | $6.91 |
|
||||
|
||||
**Key Finding**: In multi-turn agentic coding workflows, intermediate `grep`/file-read tool outputs rapidly pollute the context window. **Billion Context (`bc`)** actively compresses noisy intermediate tool observations, enabling the agent to achieve **both the highest Utilized F1 (`0.3097`) and lower total cost (`$4.61`) than every RAG arm (`$6.31–$6.91`) and `full` (`$11.05`)**.
|
||||
|
||||
---
|
||||
|
||||
## 5. Benchmark 3: MemoryAgentBench (500 Items, 6k to 1.48M Tokens)
|
||||
|
||||
**What it tests**: Four distinct stress dimensions across context scales from 6k to **1.48M tokens**:
|
||||
1. **CR (Conflict Resolution, ~6k tokens, F1)**: Resolving contradictory facts in dense histories.
|
||||
2. **AR (Accurate Retrieval / RULER QA, ~197k tokens, Exact Match)**: Verbatim needle-in-a-haystack extraction.
|
||||
3. **LRU (Long-Range Understanding / BookSum, ~180k tokens, ROUGE-L F1)**: Global narrative summarization across 100 independent books.
|
||||
4. **TTL (Test-Time Learning / Movie RecSys, ~1.48M tokens, Recall@10)**: Multi-label recommendation over 1.48M-token interaction logs.
|
||||
|
||||

|
||||

|
||||
|
||||
| Arm | Macro Avg (4 Tasks) ↑ | CR (6k, F1) ↑ | AR (197k, EM) ↑ | LRU (180k, F1) ↑ | TTL (1.48M, Recall@10) ↑ | TTL Mean Prompt ↓ | True Attributed Cost ↓ |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **`embedding-rerank`** | **55.21%** | 92.20% | 66.33% | 41.10% | 21.19% | 42.3k | $4.64 (incl. $1.52 Rerank tax) |
|
||||
| **`bm25`** | 53.70% | 92.55% | 59.00% | 41.17% | **22.08%** | 42.3k | **$3.07** |
|
||||
| **`full`** | 51.11%* | **92.80%** | **69.00%** | **42.65%** | **0.00% (199/199 Crash)** | >1,000k (Failed) | $3.10* (Excl. failed TTL; +$44.40 counterfactual) |
|
||||
| **`embedding`** | 51.10% | 88.22% | 53.67% | 40.58% | 21.92% | 42.3k | $3.28 |
|
||||
| **`bc` (Billion Context)** | 43.54% | 89.97% | 27.00% | 38.62% | **18.58% (100% Survival)** | **49.5k (~16k steady)** | **$3.78** |
|
||||
|
||||
**Key Architectural Insights from MAB**:
|
||||
1. **Surviving the 1.48M-Token Wall (`TTL`)**: `full` crashes on 100% of TTL items (`199/199` HTTP 400 context-length exceeded). `bc` smoothly compresses the 1.48M-token dialogue log into a **~16k steady-state window (49.5k mean, 30× compression ratio)**, achieving **18.58% Recall@10** with zero failures.
|
||||
2. **Boundary Condition Identified (`AR` Verbatim Needle QA)**: Because `bc` performs semantic abstraction and compression, single-sentence verbatim needles buried inside 197k-token haystacks (`AR`) can be smoothed out (`27.00%` EM vs `59.00%–66.33%` for RAG). Moreover, under black-box reasoning model evaluation (`DeepSeek V4.1 Flash`), structured compression tags occasionally caused the model to conclude inside its internal CoT (`reasoning_content`) and emit an empty `content` string on `AR`. This clearly delineates when to use **BC** (multi-turn agents, evolving state, temporal/cross-session reasoning) vs **Index-based RAG** (static verbatim needle lookup).
|
||||
@@ -0,0 +1,99 @@
|
||||
# Billion Context (`v0.1.202`) 第三方独立评测报告(1,500 题跨三大基准)
|
||||
|
||||
<p align="center"><a href="./README.md">English</a> | <a href="./README.zh-CN.md">中文</a></p>
|
||||
|
||||
> **横跨 LongMemEval-S、ContextBench 与 MemoryAgentBench 三大正交基准(共 1,500 道评测题,每个基准 500 题)**
|
||||
> 对标 **Billion Context (`bc`)**、**`full`(原生全量上下文)** 与 3 条标准 RAG 管线(**`bm25`**、**`embedding`**、**`embedding-rerank`**)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 核心结论速览
|
||||
|
||||
我们在严格控制变量的黑盒评测协议下,对 **Billion Context (`v0.1.202`)** 进行了涵盖 **伴随式多会话长对话记忆(LME)**、**真实多轮软件工程 Agent 代码库探索(CB)** 与 **极端静态长文本压力测试(MAB,最高 1.48M tokens)** 的 1,500 题全量盲测:
|
||||
|
||||
| 评测基准 | 核心考察场景 | 上下文规模 | 全场最优臂 | Billion Context (`bc`) 表现 | 核心结论 |
|
||||
| :--- | :--- | :---: | :---: | :--- | :--- |
|
||||
| **LongMemEval-S (LME)** | 伴随式多会话聊天记忆与时序更新 | ~110k tokens | `full` (83.20%) | **79.20%(全场第二)**<br/>领先最强 RAG **+16.60%** (`62.60%`) | 完整保留跨会话因果链与时间线(跨会话推理 `79.7%` vs RAG `45.1%`),相比独立会话 `full` **节省 71.1% 成本**(`$2.30` vs `$7.97`)。 |
|
||||
| **ContextBench (CB)** | 多轮 SWE 编程 Agent(`Pi CLI v0.73.1`)跨 58 个真实代码库定位 | 多轮工具调用探索 | **`bc` (0.3097 F1)** | **0.3097 Utilized F1(全场第一)**<br/>超越 `full` (`0.2928`) 及全部 RAG | 主动折叠中间轮次冗余搜索与文件读取噪音,端到端证据准确率(`0.3358`)与综合 F1(`0.3097`)双双夺冠,且比 `full` **省钱 58.3%**(`$4.61` vs `$11.05`)。 |
|
||||
| **MemoryAgentBench (MAB)** | 极端静态长文压力测试:针尖检索、整书摘要与 1.48M 推荐 | 6k → **1.48M tokens** | `embedding-rerank` (55.21%) | **43.54% 宏平均**<br/>1.48M TTL 达 **18.58% Recall@10**(`full` = **0.00%** 崩溃) | 在 `full` 100% 爆窗崩溃(`199/199` 失败)的 1.48M 超长对话中实现 **100% 存活**,均值窗口压至 **49.5k(稳态 ~16k,30× 压缩比)**;同时清晰界定了有损语义压缩在单句逐字针尖检索(`AR`)上的边界。 |
|
||||
|
||||

|
||||
|
||||
---
|
||||
|
||||
## 2. 统一实验配置与全链路成本归因口径
|
||||
|
||||
为保证五臂对比绝对公平,所有实验臂共享完全一致的底座模型、评测裁判与全链路成本归因方法(遵循 `arXiv:2609.22114` 全成本归因框架):
|
||||
|
||||
- **被测系统**:`Billion Context (BC) v0.1.202`(透明 HTTP 上下文压缩代理)
|
||||
- **底座大模型 (Base LLM)**:`DeepSeek V4.1 Flash 1017` (`deepseek-v4.1-flash-opendesign`)
|
||||
- **向量化模型 (Embedding)**:`Qwen3-Embedding-8B`
|
||||
- **重排模型 (Reranker)**:`Qwen3-Reranker-4B`
|
||||
- **代码 Agent 宿主 (ContextBench)**:`Pi CLI v0.73.1`
|
||||
- **统一定价标准**:
|
||||
- **LLM**:输入 `$0.15 / 1M tokens` | 输出 `$0.60 / 1M tokens` | 前缀缓存命中 `$0.003 / 1M tokens`(同时完成 `$0.006 / 1M` 敏感性校验)
|
||||
- **Embedding (`Qwen3-Embedding-8B`)**:`$0.01 / 1M tokens`
|
||||
- **Reranker (`Qwen3-Reranker-4B`)**:`$0.02 / 1M tokens`
|
||||
|
||||
---
|
||||
|
||||
## 3. 基准一:LongMemEval-S(500 题,~110k Tokens)
|
||||
|
||||
**评测内容**:多会话伴随式人机交互历史,涵盖 **知识动态更新 (KU)**、**跨会话推理 (MSR)**、**时序推理 (TR)**、**细节信息提取 (IE)** 与 **无事实拒答 (ABS)** 五大子任务。
|
||||
|
||||

|
||||

|
||||
|
||||
| 实验臂 | 综合准确率 ↑ | 知识更新 (KU) ↑ | 跨会话推理 (MSR) ↑ | 时序推理 (TR) ↑ | 细节提取 (IE) ↑ | 无事实拒答 (ABS) ↑ | 平均输入 Token ↓ | 顺序实付账单 | 独立会话真实成本 ↓ |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **`full`** | **83.20%** | **89.74%** | **84.21%** | **72.18%** | **88.46%** | 86.67% | 106.0k | $0.42* | $7.97 |
|
||||
| **`bc` (Billion Context)** | **79.20%** | **88.46%** | **79.70%** | **70.68%** | 81.41% | 83.33% | **30.5k** | $2.30 | **$2.30 (-71.1%)** |
|
||||
| **`embedding-rerank`** | 62.60% | 66.67% | 45.11% | 49.62% | 86.54% | 90.00% | 14.3k | $1.39 | $1.39 |
|
||||
| **`bm25`** | 56.40% | 62.82% | 37.59% | 42.11% | 81.41% | **96.67%** | 14.3k | $0.08 | $0.08 |
|
||||
| **`embedding`** | 46.40% | 48.72% | 30.83% | 26.32% | 75.64% | 86.67% | 14.3k | $0.68 | $0.68 |
|
||||
|
||||
> *\*注*:`full` 臂在顺序连跑共享会话背景时触发了 98.1% 的前缀缓存命中(`$0.42`);而在真实生产环境中(不同用户独立新会话、0% 跨用户缓存复用),`full` 成本高达 **`$7.97`**,`bc` 仅需 **`$2.30`(节省 71.1%)**,同时保留了 `full` **95.2% 的性能水平**(`79.20%` vs `83.20%`)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 基准二:ContextBench(500 题,58 个真实代码库,Pi Agent)
|
||||
|
||||
**评测内容**:使用 **Pi CLI (`v0.73.1`)** 在 58 个真实开源仓库中进行多轮代码检索与 Bug 定位,评估最终锁定代码片段与 Ground-Truth Patch 的重合度(**Utilized F1**、**Precision**、**Recall** 与 **Exploration Efficiency**)。
|
||||
|
||||

|
||||

|
||||
|
||||
| 实验臂 | 端到端有效 F1 (Utilized F1) ↑ | 证据准确率 (Precision) ↑ | 证据召回率 (Recall) ↑ | 轨迹覆盖率 (Coverage) ↑ | 探索转化率 (Efficiency) ↑ | 全链路总成本 ↓ |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **`bc` (Billion Context)** | **0.3097(第 1 名)** | **0.3358(第 1 名)** | 0.3694 | 0.4533 | 0.7279 | **$4.61(比 `full` 省 58.3%)** |
|
||||
| **`full`** | 0.2928 | 0.3125 | **0.3712** | **0.4648** | 0.7134 | $11.05 |
|
||||
| **`embedding-rerank`** | 0.2894 | 0.3095 | 0.3547 | 0.4282 | **0.7429** | $6.35 |
|
||||
| **`bm25`** | 0.2600 | 0.2788 | 0.3264 | 0.3999 | 0.7285 | $6.31 |
|
||||
| **`embedding`** | 0.2584 | 0.2757 | 0.3249 | 0.3958 | 0.7327 | $6.91 |
|
||||
|
||||
**核心发现**:在多轮编程 Agent 场景中,中间轮次的 `grep` 和大文件读取输出会迅速稀释模型注意力。**Billion Context (`bc`)** 主动折叠已消费的工具噪音,不仅使端到端 **Utilized F1 (`0.3097`) 和证据准确率 (`0.3358`) 登顶全场第一**,而且总开销(`$4.61`)低于所有 RAG 管线(`$6.31–$6.91`)及 `full`(`$11.05`)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 基准三:MemoryAgentBench(500 题,6k 至 1.48M Tokens)
|
||||
|
||||
**评测内容**:横跨 6k 至 **1.48M tokens** 的四类静态长文本极限压力子任务:
|
||||
1. **CR(冲突消解,~6k tokens,F1)**:密集矛盾事实修正。
|
||||
2. **AR(精准针尖检索 / RULER QA,~197k tokens,Exact Match)**:20 万字长文单句细节精确提取。
|
||||
3. **LRU(长程理解 / BookSum,~180k tokens,ROUGE-L F1)**:100 本独立长篇英文小说全局大纲总结。
|
||||
4. **TTL(测试时学习 / 电影推荐,~1.48M tokens,Recall@10)**:148 万 Token 超长交互日志下的多标签电影推荐。
|
||||
|
||||

|
||||

|
||||
|
||||
| 实验臂 | 四任务宏平均 ↑ | CR (6k, F1) ↑ | AR (197k, EM) ↑ | LRU (180k, F1) ↑ | TTL (1.48M, Recall@10) ↑ | TTL 平均窗口 ↓ | 全链路真实总成本 ↓ |
|
||||
| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **`embedding-rerank`** | **55.21%** | 92.20% | 66.33% | 41.10% | 21.19% | 42.3k | $4.64(含 $1.52 Rerank 税) |
|
||||
| **`bm25`** | 53.70% | 92.55% | 59.00% | 41.17% | **22.08%** | 42.3k | **$3.07** |
|
||||
| **`full`** | 51.11%* | **92.80%** | **69.00%** | **42.65%** | **0.00% (199/199 崩溃)** | >1,000k (爆窗) | $3.10*(漏算崩溃的 TTL,补齐需 +$44.40) |
|
||||
| **`embedding`** | 51.10% | 88.22% | 53.67% | 40.58% | 21.92% | 42.3k | $3.28 |
|
||||
| **`bc` (Billion Context)** | 43.54% | 89.97% | 27.00% | 38.62% | **18.58%(100% 存活)** | **49.5k(稳态 ~16k)** | **$3.78** |
|
||||
|
||||
**MAB 核心洞见与架构边界**:
|
||||
1. **突破 1.48M Token 物理墙 (`TTL`)**:`full` 在 1.48M Token 的 TTL 上 100% 触发上下文溢出崩溃(`199/199` HTTP 400),而 `bc` 将 148 万 Token 平滑折叠至 **~16k 稳态窗口(均值 49.5k,压缩比 30×)**,实现 **100% 零报错存活** 并取得 **18.58% Recall@10**。
|
||||
2. **明确架构适用边界 (`AR` 逐字针尖检索)**:在 19.7 万字中寻找单句孤立事实的 `AR` 任务上,语义摘要折叠会抹平局部字面细节(`27.00%` EM vs RAG `59.00%–66.33%`);同时在黑盒评测中观察到推理模型(`DeepSeek V4.1 Flash`)在面对结构化压缩标记时,偶发将答案写在内部思维链(`reasoning_content`)后直接结束生成、导致用户可见 `content` 为空。这与论文 §1 “我们不宣称覆盖逐字历史类任务” 的理论边界完全吻合。
|
||||
|
After Width: | Height: | Size: 1.7 MiB |
|
After Width: | Height: | Size: 1.4 MiB |
|
After Width: | Height: | Size: 1021 KiB |
|
After Width: | Height: | Size: 1.6 MiB |
|
After Width: | Height: | Size: 1.2 MiB |
|
After Width: | Height: | Size: 1.7 MiB |
|
After Width: | Height: | Size: 1.2 MiB |
@@ -0,0 +1,38 @@
|
||||
# DESIGN #4580 — tool_use id → lane 路由(三层)
|
||||
|
||||
## 机制
|
||||
|
||||
代理是模型输出的唯一通道:每个出站 tool_use 块流经时,代理**知道它属于哪条 lane**。Claude Code ≥2.1.308 在每次 MCP tools/call 上盖 `_meta["claudecode/toolUseId"]`(即那个 tool_use 块的 id)。两侧对上号:id 即 lane。
|
||||
|
||||
```
|
||||
subagent 模型响应 --SSE--> 代理管道 settle: recordToolUseId("toolu_X", subLane)
|
||||
host tools/call --_meta--> shim: body.toolCallId = "toolu_X"
|
||||
shim POST -------> 代理路由: lookupToolUseIdSession("toolu_X") → subLane(host-stamped 权威)
|
||||
```
|
||||
|
||||
## 三层改动
|
||||
|
||||
1. **记录**(src/tool-ring.ts 新增 id 环 + src/plugin.ts 三个 settle 点)
|
||||
- `recordToolUseId(id, sessionId)` / `lookupToolUseIdSession(id)`,TTL 10 分钟(与 witness 环一致),容量 1024,last-write-wins(host id 唯一,重记=重试)。
|
||||
- 记录点与 `recordToolWitness` 同路径:anthropic chat SSE(`seenToolCalls[].id`)、responses SSE(map key = `item.id`,跳过合成 `oi:N` 键)、非流式 JSON(anthropic `tool_use.id` / openai `tool_calls[].id` / responses `call_id`)。
|
||||
|
||||
2. **路由**(src/plugin.ts `handlePluginTool`)
|
||||
- 复用既有 body 字段 `toolCallId`(agent/shared.ts:380 原生路径已在发;plugin.ts:1923 已在验)。
|
||||
- 路由阶梯最前插入:id 环命中且 lane 存活 → `routedBy="native"`,直接路由(与 #2024 host-stamped 同权威等级),跳过 witness 冲突 409;日志 `[plugin] tool "...": routed by host call id (#4580) to "<lane>"`。
|
||||
- 环未命中(代理重启 / TTL 过期 / id 未流经)→ 旧阶梯原样,fail-closed 不变。
|
||||
|
||||
3. **shim**(src/mcp.ts)
|
||||
- `_meta["claudecode/toolUseId"]` 严格校验(非空字符串,trim;否则视为缺失),仅作为 `forwardTool` 新第 6 参 → `body.toolCallId`。
|
||||
- 不触碰 routeOverride、不触碰全局绑定、不置 nativeCaller(路由权威在代理侧判定)。
|
||||
|
||||
## 明确不做
|
||||
|
||||
- 不给 openai/google functionCall 无 id 的协议造假 id(记录点只在 id 真实存在时触发)。
|
||||
- 不改 #4168 shim 自愈路径:id 环未命中时 409 语义原样保留。
|
||||
- 不新增端点、不改 body schema(toolCallId 字段已存在)。
|
||||
|
||||
## 测试(tests/issue4580-claudecode-tooluseid-routing.test.ts,12 用例)
|
||||
|
||||
- 记录:4 条管道各 1 例 + 双 lane 分离 + TTL + 畸形 id。
|
||||
- 路由:子代理调用命中子 lane + 日志断言;环 miss 回退旧行为;空/超长 toolCallId 400(与既有校验对齐);无 id 时 witness 409 不受影响。
|
||||
- shim:POST body 携带 toolCallId 且不误标 nativeCaller。
|
||||
@@ -0,0 +1,10 @@
|
||||
# REQ #4580 — Claude Code 子代理的 bili 调用路由到错误会话
|
||||
|
||||
- **Issue**: #4580(P1)
|
||||
- **现象**: Claude Code 的 Task 子代理与本线程共用同一个 MCP shim 进程。shim 在启动时抓的是父会话的 session id(env 绑定),子代理的模型流量实际走的是代理里另一条 lane,但它的 `mcp__bili__compress` 等调用全部按父会话路由 —— 子代理压缩的是**父会话**(refs 全部 unknown / 误折),或撞上 #2024/#4168 的 witness 409 永久失败。
|
||||
- **触发条件**: Claude Code(任意近版本)+ Task 子代理 + MCP 模式 bili。Claude Code ≥2.1.308 起每次 tools/call 自带 `_meta["claudecode/toolUseId"]`,使本修复可行。
|
||||
- **验收**:
|
||||
1. 子代理的 compress 调用路由到子代理自己的 lane(witness 记录侧可证)。
|
||||
2. 未知/缺失 id 完全回退旧行为(fail-closed 语义不变)。
|
||||
3. 父线程调用行为不变(id 映射回父 lane,与 env 绑定一致)。
|
||||
4. shim 全局绑定不被子代理调用污染。
|
||||
@@ -0,0 +1,33 @@
|
||||
# DESIGN: blog GitHub refresh(#4906)
|
||||
|
||||
## 模块与依赖方向
|
||||
|
||||
- 新文件 `src/web/blog-refresh.ts`:拉取 + 注册。单向依赖 `blogfeed.ts`(复用渲染/排序/资产类型),**不**反向 import,无循环。
|
||||
- `src/web/blogfeed.ts`(改):feed 状态从「本地一次性计算」扩展为「本地 + 已注册的远端」:
|
||||
- 新增纯函数 `resolveRepoRel(base, target)`(无 fs 的相对路径解析,`..` 不得越过仓库根)+ `collectImageTargets(md, base)`(下载前收集候选图,保证渲染丢图判定与下载集一致);remote 渲染走 `rewriteImagesFromAssets`(候选 = 已下载集合),disk 路径不变。输出形态一致(`/__bili/blog-assets/<repo-rel>`)。
|
||||
- posts 拼装抽成共享的 `postsFromPairs()`(bundled/remote 同一套 slug/date/双语标题逻辑);新增导出 `buildRemoteBlogPosts(files, assetKeys)` / `registerRemoteBlogFeed(round)` / `getRemoteBlogAsset(rel)`;`getBlogFeed()` = 按 id 去重合并(远端优先)→ newest-first 排序。
|
||||
- 资产路由先查内存远端 map(rel → {buf, type}),未命中再走原磁盘路径。
|
||||
- `src/server/admin.ts`(改):`/__bili/blog` 路由响应后调 `kickBlogRefresh()`(fire-and-forget,TTL+单飞在模块内部)。
|
||||
- `src/plugin.ts`(改 1 行):`/acp` 状态路径紧跟 `warmChangelogOnce()` 旁加 `warmBlogRefreshOnce()` —— 仅冷启动触发(本进程尚无 master 快照时拉一次);进程已持有 overlay 后,后续状态访问完全不走网络;失败静默。
|
||||
- `src/agent/dsh-native-client.ts`(改,owner 跟进 2026-10-27):dsh 内嵌 bili 设置面的 tab 栏在「版本」后加「博客」按钮 —— `PAGE_IDS` 尾部追加 `"blog"` + `PAGE_KEYS`/zh/en 各一条 i18n;点击只改 iframe hash(`#/blog`),零新增数据通道。
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
GET /__bili/blog ──> handleBlogGet(res) 立即响应(bundled 底/上次远端快照)
|
||||
└─> kickBlogRefresh() (fire-and-forget: throttle 1h, inflight 去重, 不 await)
|
||||
│ 1. api.github.com contents: website/blog/posts?ref=master
|
||||
│ 2. raw.githubusercontent.com/<name> 逐个 .md(并发 ≤4,5s/个超时)
|
||||
│ 3. 解析 ![]() 相对引用 → 去重候选(≤50)→ 同样的 raw 下载
|
||||
│ 4. blogfeed 构建 BlogItem[] + assets map
|
||||
└─> registerRemoteBlogFeed(items, error?) <- 失败时仅记 "offline"
|
||||
handleBlogGet(res) <── getBlogFeed(): sort(mergeDedupe(remote ?? [], bundled), remote-wins)
|
||||
GET /__bili/blog-assets/<rel> -> 远端内存 map 命中 ? buf : 磁盘路径(原逻辑)
|
||||
```
|
||||
|
||||
## 关键取舍
|
||||
|
||||
- **每小时自驱链(2026-10-27 owner 要求,覆盖 v1 的纯访问驱动)**:进程第一次碰本模块(博客路由 / status warm / 测试轮)时启动一条每 1h 强拉一轮的链(kick 内部首行自续)。长跑进程即使零访问,服务内容也不会老于 ~1h;句柄 unref,不拖短命 CLI 退出、不进测试事件循环(`_resetBlogRefreshForTest` 会清);force 保证失败轮也能在下一小时重试(失败轮成本 ≈ 1 次匿名 contents 请求)。
|
||||
- **不 await 刷新**:changelog 的 handler await 是因为单请求;博客是 1+N 请求,阻塞请求路径最坏可达分钟级。改为非阻塞后台预取——本次加载看到旧内容,下一刷看到新内容,可接受且零回归风险。
|
||||
- **匿名 API**:与 changelog 一致不申请 token;限额靠 fail-soft 吸收。
|
||||
- **预算**:md ≤ 512KB/篇、图片 ≤ 2MB/张、总 ≤ 8MB、文件总数 ≤ 200;任一超限 → 放弃本轮远端内容(保留上轮或捆绑),warn 日志(loggerLog,非 console)。
|
||||
@@ -0,0 +1,25 @@
|
||||
# REQ: Web 面板博客定时从 GitHub master 拉取新文章
|
||||
|
||||
**Issue:** #4906 · **Branch:** `2026-10-27_web-blog-github-refresh` · **Date:** 2026-10-27
|
||||
|
||||
## 问题
|
||||
|
||||
Web 面板博客(`/__bili/blog`,#4587)只渲染随 npm 包冻结的 markdown(`website/blog/posts/*.md`)。master 上新写的文章必须等发版 + self-update 才能在面板出现。Owner 要求:面板能自动从 GitHub 拉新文章。
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. `GET /__bili/blog` 立即按既有逻辑响应(捆绑底/上次远端快照),随后在后台触发一次节流刷新(默认 1h 窗口):拉 GitHub `ranxianglei/billion-context` master 的 `website/blog/posts/*.md`(+ 文中引用的图片)。
|
||||
2. 成功 → 远端条目并入 feed;同 id 时远端覆盖本地捆绑副本;本地独有 id 保留(旧版捆绑内容不丢)。排序沿用现有 newest-first。
|
||||
3. 图片经现有 `/__bili/blog-assets/<rel>` 路由服务(内存字节),扩展名白名单不变。
|
||||
4. Fail-soft(与 #3719 changelog 同等纪律):离线 / HTTP 错误 / 畸形 JSON / 超限大小 → 保留已缓存或本地捆绑内容,feed JSON 带 `error: "offline"`,绝不向调用方抛异常,绝不阻塞请求路径(fire-and-forget)。
|
||||
5. 无配置键、无 env var、无磁盘缓存文件——访问驱动 + 每进程冷启动一次 warm-up;**另加每小时自驱刷新链**(首次触碰后启动,句柄 unref,事件循环无常驻负担)——owner 2026-10-27 评审后追加:无论有没有人访问,内容不得老于 ~1h。
|
||||
6. 越界防护:API 返回的路径段不允许 `..`/绝对路径/NUL;下载有 per-file 与总量字节预算、文件数上限;非 `.md` 行跳过。
|
||||
7. 测试覆盖:合并优先级、节流、fail-soft、路径安全、资产 404 降级、size cap、每小时自驱链(mock 时钟)。typecheck + check:unused-exports + web 测试绿。
|
||||
8. dsh 内嵌设置面(`src/agent/dsh-native-client.ts`):tab 栏新增「博客」按钮,位置紧跟「版本」之后(#4906 owner 跟进,2026-10-27);复用内嵌 frame 的既有 `#/blog` hash 路由,不新增数据通道;旧构建的内嵌页面不认识该路由时自行回落默认页,不会白屏。
|
||||
|
||||
## 约束 / 范围外
|
||||
|
||||
- 无鉴权 API:GitHub contents API 匿名限速 60/h/IP — 1h 节流在限额内;超限时 fail-soft 回退本地,不重试风暴;每小时自驱链的失败轮成本 ≈ 1 次匿名请求。
|
||||
- v1 不支持远端 `website/articles.json`(该文件当前在 master 上不存在);posts-only。
|
||||
- 不改面板前端渲染逻辑(新文章以既有 JSON 形状自然出现);不改 `website/` 静态站。
|
||||
- 不发版、不动 `version`(release 分支专属)。
|
||||
@@ -0,0 +1,37 @@
|
||||
# DESIGN — I3 出站配对不变量(#4862 第 1 层:纯检测)
|
||||
|
||||
## 机制
|
||||
|
||||
在 `judgeInboundOutbound`(`src/invariant-judge.ts`)追加第三条不变量 I3:遍历 exit cores,按方向配对——
|
||||
|
||||
- 每个 `tool-call` 必须有同 id 的 `tool-result` 在其后(upstream 方向契约:anthropic 要求 tool_result 跟随 tool_use;openai 要求 role:"tool" 跟在声明它的 assistant 之后);
|
||||
- 每个 `tool-result` 必须有同 id 的 `tool-call` 在其前。
|
||||
|
||||
配对行走与 kernel 守卫完全同构(`kernel/src/prune.ts` stripOrphanedToolResults / stripOrphanedToolCalls,#3046):precedence-only——一个 call 可应答任意多个同 id result、反之亦然(Agent Teams `name:index` id 复用),集合语义、不数多重度。
|
||||
|
||||
新增 ViolationKind:`unpaired-tool-call` / `unpaired-tool-result`。I3 是 exit 内部校验,与折叠切分无关(折叠区不再豁免协议结构),legacy / render-lane / main / loop 四种模式全跑同一检查。
|
||||
|
||||
## 归因(「谁的错」charter)——两层护栏
|
||||
|
||||
1. **逐 id 跳过**:exit 中断配对的 id 若在 entry 侧本来就是断的(宿主自己发来的半对),不计 bili;
|
||||
2. **体量护栏(#2821 交互)**:宿主自己发来的半对在投影时被重铸 id(exit id ∉ entry),逐 id 无法与「bili 拆断了一对后被重铸」区分。体量仲裁:bili 只对 exit 未应答 call 数**超出** entry 未应答 call 数的部分负责。超出才告警,且只告 id ∉ entry 断集的那部分。CCR 占位替换(#4186 G2)、截断孪生(G3)、crush 都保留 id,天然不误报。
|
||||
|
||||
## 豁免(与 kernel 对齐)
|
||||
|
||||
- compress 在途调用豁免(bare `compress` + MCP 方言 `mcp__bili__compress`,lockstep `isMcpBiliCompress` src/config.ts):其结果由 hideConsumedCompressCalls 管理,不走配对——镜像 `kernel/src/prune.ts` stripOrphanedToolCalls 的豁免。result 侧不豁免(同 kernel)。
|
||||
- 判官内联该谓词(不 import config.ts)以保持叶子模块:纯、无 I/O。
|
||||
|
||||
## 不变式
|
||||
|
||||
- 零出站字节改动、零拦截(advisory 层,catch 后静默),`maybeRunInvariantJudge` / `maybeJudgeContinuity` 接线点不变;
|
||||
- 判官只新增告警语义,不改 I1/I2 任何行为——现有 46 个判官测试(invariant-judge.test.ts 30 + e2e + #4241 render 基准)全部原样绿。
|
||||
|
||||
## 测试(tests/issue4862-invariant-judge-unpaired.test.ts,12 例)
|
||||
|
||||
NEG(有牙齿):折叠吃掉 result 半侧→unpaired-tool-call;折叠吃掉 call 半侧→unpaired-tool-result;render-lane 渲染前缀含断对→仍红;id 重铸洗白→仍红。
|
||||
POS(不误报):宿主自发半对回显→clean;孤立重铸 call 压在孤立宿主 call 上(#2821 形状,体量护栏)→clean;compress 在途(bare+MCP 方言)→clean;整对折叠(kernel adjustBoundariesForToolPairs 对齐)→clean;同 id 复用 precedence→clean。
|
||||
Wired:真 anthropic body 主车道断对→红 lane=main;配对→绿;loop 连续性车道第 2+ 轮丢半侧→红 lane=loop。
|
||||
|
||||
## 后续(第 2 层,单独决策)
|
||||
|
||||
真正拦 400 需要出口修复(剥孤儿半侧,镜像 prune 守卫纪律;或 anthropic 邻接楔入上提,把 #766 tool-pair-order 扩到 anthropic 语义)——wire 变更属 §7.4 人工层,等本层红线在真实流量确认命中形状。
|
||||
@@ -0,0 +1,27 @@
|
||||
# REQ — issue #4862 残余缺口:出站判官对断配对 tool_use/tool_result 判 clean 放行
|
||||
|
||||
- 日期:2026-10-28
|
||||
- Issue:#4862(claude 子代理 400 线,三件套之一)
|
||||
- 关联:PR #4774(根修:子代理不再共享 session id)只消除了主触发源;owner 在 #4769 评论明确划界「第二面 = invariant judge 给 clean verdict、破损配对照样出网,是出口校验缺口,不在 #4774 范围内,归 #4862 单独补」。
|
||||
|
||||
## 问题
|
||||
|
||||
`src/invariant-judge.ts` 的判官只定义了两条不变量:
|
||||
|
||||
- I1(无折叠):入站每条 stable 消息按序出现在出站,合法差异仅尾部追加+具名豁免;
|
||||
- I2(折叠):所有差异局限在 `[earliest-fold-start, end)`,冻结前缀字节不变。
|
||||
|
||||
两条都是 entry↔exit 的连续性对账,**没有任何一条对 exit 自身做协议结构校验**。#4862 的实际形状:折叠/渲染把一对 tool_use/tool_result 拆断、只送出半侧 → 差异全部落在折叠区 → I2 判合法 → clean fold verdict(`src/invariant-judge.ts` debug 行)→ 上游 400。这正是日志里最容易被误读成「bili 没问题」的行(owner 原话)。
|
||||
|
||||
## 需求
|
||||
|
||||
1. 出口校验名副其实:协议结构破损的出站体**永远不允许读成 clean**,与差异是否局限在折叠区无关;
|
||||
2. 归因保持「谁的错」职责:宿主自己发来的断对不是 bili 的错,不告警;
|
||||
3. kernel 守卫豁免对齐:compress 在途调用(结果由 hideConsumedCompressCalls 管理)不告警;
|
||||
4. 纯检测、零拦截、零出站字节改动,受既有 `diagnostics.invariantJudge` 旋钮控制;
|
||||
5. 模式无关:legacy 全量、render-lane tail(#4241)、主车道、loop 第 2+ 轮一视同仁;
|
||||
6. #3617 门纪律:正负测试行双向齐全。
|
||||
|
||||
## 非目标(明确划界)
|
||||
|
||||
- 不修「真正拦住 400」的出口修复(剥孤儿半侧/上提楔入项)——那是 wire/message-shape 变更,属人工审核层,等第 1 层判官红线在真实流量确认命中形状后单独决策。
|
||||
@@ -0,0 +1,35 @@
|
||||
# REQ — Google 原生 wire:带命名空间的 model id 被判成「非模型请求」,整段流量静默旁路
|
||||
|
||||
- 日期:2026-11-03
|
||||
- Issue:#5593
|
||||
- 报告人环境:omp 18.16.0 + billion-context 0.1.208,模型 `magpie/antigravity/gemini-3.8-flash`(provider `api: google-generative-ai`)
|
||||
- 关联形状:#2493(native fetch 拦截器认 Google 原生 wire)、#4256(v1internal 方法集只认三个模型方法)
|
||||
|
||||
## 问题
|
||||
|
||||
Google 原生 wire 的 model 在 URL 路径里:`POST /v1beta/models/<model>:(streamGenerateContent|generateContent|countTokens)`。两处解析都假设 `<model>` 不含 `/`:
|
||||
|
||||
- `src/agent/native-intercept.ts` `MODEL_API_SUFFIX` — 客户端侧 `isModelApiUrl`;
|
||||
- `src/server.ts` `googleModelFromPath` — 代理侧取 model。
|
||||
|
||||
omp 的 `google-generative-ai` provider 把 provider 前缀一并写进路径(`/v1beta/models/antigravity/gemini-3.8-flash:streamGenerateContent`,网关路由形如 `/v1beta/models/group/hard:generateContent`),于是:
|
||||
|
||||
1. `isModelApiUrl` 判 false → `installNativeFetchIntercept` 走 `if (!isModelApiUrl(url)) return send(input, init)`,请求**直连上游**,从不经过 `/bili/` 代理;
|
||||
2. 该会话因此没有 `processTurn`、没有窗口解析、没有压缩、没有 conversation 注册;`acp_status`/`acp_cache` 报 `404 unknown plugin conversation`;
|
||||
3. 代理侧即便收到,`googleModelFromPath` 也返回 undefined,所有按 model 决定的窗口/阈值/摘要适配器失去依据。
|
||||
|
||||
现场证据(0.1.208):会话 `01a19f5e-7b02-7519-854c-2f63bc914120` 全程该模型,`bili.log` 零条该会话记录,末轮 `input=684938 / cacheRead=0`,上下文 685k token 未压缩。
|
||||
|
||||
## 需求
|
||||
|
||||
1. 带命名空间的 model id 判为模型请求并**经代理**:`models/<ns>/<id>:<method>` 与 `models/<id>:<method>` 等价;
|
||||
2. 代理侧 `googleModelFromPath` 返回完整 id(`antigravity/gemini-3.8-flash`),不丢前缀;
|
||||
3. 收窄面不变:`/v1beta/models` 列表、`:predict` 等无管线的 Google 方法、`/bili/` 已改写 URL 仍判 false,`v1internal` 控制面方法仍直连;
|
||||
4. 不改 wire、不加配置项、不改 env 面:仅正文字符类收窄(`[^/:?]+` → `[^:?]+`);
|
||||
5. #3617 门纪律:正负断言双向齐全,且含一条真实路由断言(请求确实改写成 `${origin}/bili/<url>`)。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 外部摘要端点(`SummaryEndpoint` 用 `encodeURIComponent(model)` 拼路径)对带斜杠 id 的编码形状;
|
||||
- Antigravity v1internal 的 model 解析(在 envelope,不在路径);
|
||||
- 任何配置面新增。
|
||||
@@ -0,0 +1,57 @@
|
||||
# WORKLOG — Google 原生 wire 命名空间 model id 旁路
|
||||
|
||||
- 日期:2026-11-03
|
||||
- 分支:`2026-11-03_google-namespaced-model-path`
|
||||
- 基线版本:0.1.208(报告人运行版本;0.1.212 同样未修)
|
||||
|
||||
## 根因
|
||||
|
||||
两处 model 解析把 `<model>` 限定为「不含 `/`」:
|
||||
|
||||
| 位置 | 旧 | 新 |
|
||||
|---|---|---|
|
||||
| `src/agent/native-intercept.ts` `MODEL_API_SUFFIX` | `models\/[^/:?]+:` | `models\/[^:?]+:` |
|
||||
| `src/server.ts` `googleModelFromPath` | `\/models\/([^/:?]+):` | `\/models\/([^:?]+):` |
|
||||
|
||||
omp 的 `google-generative-ai` provider 把 provider 前缀写进路径(`/v1beta/models/antigravity/gemini-3.8-flash:streamGenerateContent`)。客户端侧判 false → `installNativeFetchIntercept` 的 `if (!isModelApiUrl(url)) return send(input, init)` 直接放行到上游,代理整段旁路:无 `processTurn`、无窗口解析、无压缩、无 conversation 注册(`acp_status` 报 `unknown plugin conversation`)。
|
||||
|
||||
## 现场证据(0.1.208)
|
||||
|
||||
- 会话 `01a19f5e-7b02-7519-854c-2f63bc914120`:全程 `antigravity/gemini-3.8-flash`,`~/.local/state/billion-context/bili.log` 零条该会话记录;
|
||||
- 末轮 `usage: input=684938, cacheRead=0` —— 685k token 上下文从未折叠;
|
||||
- 同一台机器上 `codex/gpt-6.1-terra`(`/v1/responses`)全程正常:有 `processTurn`/`[acp-usage]`。
|
||||
|
||||
## 验证
|
||||
|
||||
1. 单测(新增,双向):
|
||||
|
||||
```
|
||||
node --import tsx --test tests/native-intercept.test.ts tests/vertex.test.ts
|
||||
ℹ tests 84 / pass 84 / fail 0
|
||||
```
|
||||
|
||||
新增断言覆盖:`models/<ns>/<id>:<method>` 三种方法 + `?alt=sse` 均判 true;`/v1beta/models` 列表、`:predict`、无方法后缀仍判 false;`googleModelFromPath` 返回完整 `antigravity/gemini-3.8-flash`、`group/hard`;含一条真实路由断言(请求改写成 `${origin}/bili/<url>`,不是直连)。
|
||||
|
||||
2. 回归:
|
||||
|
||||
```
|
||||
node --import tsx --test tests/adapter-google.test.ts tests/lane-decisions-matrix.test.ts
|
||||
ℹ tests 111 / pass 111 / fail 0
|
||||
```
|
||||
|
||||
3. `npx tsc --noEmit -p tsconfig.json` 干净(kernel 与 pi-subagents 先 `npm run build`)。
|
||||
|
||||
4. 现场端到端(打补丁后的 0.1.208 dist + 真实上游网关):
|
||||
|
||||
- `omp -p --model=magpie/antigravity/gemini-3.8-flash` → `bili.log` 出现 `forward POST → …/v1beta/models/antigravity/gemini-3.8-flash:streamGenerateContent`、`nudge idle: usage=2% (21399/1048576) … model=antigravity/gemini-3.8-flash`;
|
||||
- 同会话内 `acp_status` 返回真实面板(`BILLED INPUT: 21411 tok`),不再是 `404 unknown plugin conversation`;
|
||||
- `GET /__bili/plugin/status?conversationId=…` 返回 `"model":"antigravity/gemini-3.8-flash"`。
|
||||
|
||||
## 影响面
|
||||
|
||||
- 只放宽字符类,不放宽方法集:`v1internal` 控制面、`:predict`、discovery 列表的直连行为不变;
|
||||
- 无 wire 变更、无配置面变更、无 env 变更。
|
||||
|
||||
## 教训
|
||||
|
||||
「model 在 URL 路径」这一族(Google 原生 / Vertex)在两个模块里各写一遍正则,收窄条件写死在字符类里;任何「id 里出现分隔符」的宿主(网关路由、provider 前缀)都会被静默判成非模型流量,且失败模式是完全静默的(直连上游仍能工作,只是没有压缩)。回归测试因此必须包含**路由断言**,不能只测谓词。
|
||||
@@ -0,0 +1,24 @@
|
||||
# Documentation
|
||||
|
||||
All system documentation for **billion-context** lives in this directory. The repo root keeps only four **core** entry files — `README.md`, `README.zh-CN.md`, `AGENTS.md`, `CHANGELOG.md` — and recognized community-maintained README translations (`README.<locale>.md`, e.g. `README.ja.md`, approved 2026-11-09, #6000). Former root doc paths keep one-line redirect stubs at the root (tracked in [lifecycle §5](lifecycle.md#5-卫生记录)).
|
||||
|
||||
> **Full catalog:** [index.md](index.md) / [index.zh-CN.md](index.zh-CN.md) — every doc with a one-line description. This page is the directory landing: where things are and which rules keep them live.
|
||||
|
||||
## Sections
|
||||
|
||||
| Section | Docs | What you'll find |
|
||||
|---|---|---|
|
||||
| **Start here** | [configuration](configuration.md) · [clients](clients.md) · [how-it-works](how-it-works.en.svg) | Full configuration reference (generated, drift-guarded) · per-client integration deep dives · one diagram of the whole flow |
|
||||
| **System architecture** | [architecture](architecture.md) / [中文](architecture.zh-CN.md) | **LIVE hub**: overall diagram + one page per module (pipeline / lanes / kernel / identity / fastpaths / storage / webui / update), each with its own diagram — freshness is CI-enforced (`architecture-docs` lane) |
|
||||
| **Identity & protocol** | [message-identity](message-identity.md) · [session-identity](session-identity.md) · [session-identity-resolution](session-identity-resolution.md) · [identity-channels](identity-channels.md) · [msgid-infrastructure](msgid-infrastructure.md) · [opencode-responses-websocket](opencode-responses-websocket.md) · [plugin-protocol](plugin-protocol.md) | The identity doctrine (msg id, session id, persona forks, the #5825 channel wiring) and per-client protocol notes |
|
||||
| **Engineering & operations** | [technical-notes](technical-notes.md) · [lifecycle](lifecycle.md) · [auto-merge-guardrails](auto-merge-guardrails.md) · [unified-loop-spec](unified-loop-spec.md) | Mechanism deep-dives · the transition/retirement ledger (CI-enforced) · the evidence appendix behind `AGENTS.md` §7 · historical design (superseded by code) |
|
||||
|
||||
## Rules of the road (why this directory stays readable)
|
||||
|
||||
1. **Bilingual by default** — English base name + `*.zh-CN.md` mirror; a single-language doc must say why in its [index](index.md) entry.
|
||||
2. **Every new or moved doc is listed in [index.md](index.md) + [index.zh-CN.md](index.zh-CN.md) in the same PR** — an unlisted doc does not exist.
|
||||
3. **Architecture docs are LIVE** — structural changes update the affected page, diagram, and hub ledger row in the same PR; CI lane `architecture-docs` enforces the mechanical parts.
|
||||
4. **Procedures live in [`../reference/`](../reference/README.md), not here** — `docs/` is decision/reviewer-facing reference; `reference/` holds the lazy-loaded how-to material (testing / release / git-pr / env-vars / the KDD full-text ledger).
|
||||
5. **Moves leave a stub** — a one-line redirect at the old path + a hygiene-ledger entry in [lifecycle.md](lifecycle.md) §5 with an explicit removal condition.
|
||||
|
||||
The authoritative wording of these rules: [`AGENTS.md` §3 "Documentation Layout"](../AGENTS.md).
|
||||
@@ -0,0 +1,24 @@
|
||||
# 文档导航
|
||||
|
||||
**billion-context** 的全部系统文档都集中在这个目录。仓库根目录只保留四个核心入口文件——`README.md`、`README.zh-CN.md`、`AGENTS.md`、`CHANGELOG.md`——外加受认可的社区 README 译本(`README.<locale>.md`,如 `README.ja.md`,批准于 2026-11-09 / #6000)。原根路径保留单行重定向占位(记账见 [lifecycle §5](lifecycle.md#5-卫生记录))。
|
||||
|
||||
> **全量目录:** [index.zh-CN.md](index.zh-CN.md) / [index.md](index.md) —— 每篇文档一行说明。本页是目录落地页:东西在哪、什么规则让它们保持新鲜。
|
||||
|
||||
## 分区
|
||||
|
||||
| 分区 | 文档 | 里面有什么 |
|
||||
|---|---|---|
|
||||
| **从这里开始** | [configuration](configuration.zh-CN.md) · [clients](clients.zh-CN.md) · [how-it-works](how-it-works.zh-CN.svg) | 全量配置参考(生成式,有漂移守卫)· 各客户端接入深潜 · 一张全流程图 |
|
||||
| **系统架构** | [architecture](architecture.zh-CN.md) / [English](architecture.md) | **实时枢纽**:整体图 + 每模块一页(pipeline / lanes / kernel / identity / fastpaths / storage / webui / update),每页配自己的图 —— 新鲜度由 CI 车道 `architecture-docs` 强制 |
|
||||
| **身份与协议** | [message-identity](message-identity.zh-CN.md) · [session-identity](session-identity.zh-CN.md) · [session-identity-resolution](session-identity-resolution.zh-CN.md) · [identity-channels](identity-channels.zh-CN.md) · [msgid-infrastructure](msgid-infrastructure.zh-CN.md) · [opencode-responses-websocket](opencode-responses-websocket.zh-CN.md) · [plugin-protocol](plugin-protocol.md) | 身份教义(消息 id、会话 id、persona 分叉、#5825 信道接线)与各客户端协议说明 |
|
||||
| **工程与运维** | [technical-notes](technical-notes.zh-CN.md) · [lifecycle](lifecycle.md) · [auto-merge-guardrails](auto-merge-guardrails.md) · [unified-loop-spec](unified-loop-spec.md) | 机制深潜 · 过渡/退役台账(CI 强制)· `AGENTS.md` §7 的证据附录 · 历史设计(以代码为准) |
|
||||
|
||||
## 目录规约(这个目录为什么不会再次变乱)
|
||||
|
||||
1. **默认双语** —— 英文基名 + `*.zh-CN.md` 镜像;单语言文档必须在 [index](index.zh-CN.md) 条目里写明原因。
|
||||
2. **每篇新增/搬动的文档都必须在同一 PR 里进 [index.zh-CN.md](index.zh-CN.md) + [index.md](index.md)** —— 没进目录的文档等于不存在。
|
||||
3. **架构文档是实时的** —— 结构变化在同一 PR 里更新对应页 + 图 + 枢纽总表行;CI 车道 `architecture-docs` 卡机械部分。
|
||||
4. **施工流程在 [`../reference/`](../reference/README.md),不在这里** —— `docs/` 放给决策者/评审者看的参考;`reference/` 放惰性加载的施工材料(测试 / 发版 / git-pr / 环境变量 / KDD 全文台账)。
|
||||
5. **搬家留桩** —— 旧路径留单行重定向 + 在 [lifecycle.md](lifecycle.md) §5 卫生账记一笔,带明确解除条件。
|
||||
|
||||
这些规则的权威表述:[`AGENTS.md` §3「Documentation Layout」](../AGENTS.md)。
|
||||
@@ -0,0 +1,49 @@
|
||||
# Architecture
|
||||
|
||||
> One hub for the system's architecture. This page holds the **overall diagram** and the **module ledger**; each module gets its own page (en + `.zh-CN`) in this directory, each with its own diagram.
|
||||
> 中文: [architecture.zh-CN.md](./architecture.zh-CN.md)
|
||||
>
|
||||
> **Live document (owner ruling 2026-11-08).** A PR that changes a module boundary, a depicted data flow, a table, a lane, or a wire path MUST update the affected page(s), diagram(s), and this hub table in the same PR. CI enforces the mechanical parts (`tools/check-architecture-docs.mjs`); the rule text lives in [AGENTS.md](../AGENTS.md) "Documentation Layout".
|
||||
|
||||
## Overall architecture (as of 2026-11-08, master, storage schema v11)
|
||||
|
||||

|
||||
(bitmap fallback: [architecture-current.en.png](./architecture/assets/architecture-current.en.png))
|
||||
|
||||
How to read it:
|
||||
|
||||
- **Left → right is one model request.** Host lanes (dsh / pi / opencode / codex / bare proxy clients) carry identity already (session id in headers; plugin lanes carry per-element host msgid in the envelope — #5842 collectors). Ingress adapters (`prepare-*`) normalize the wire, `lane-decisions` routes the request to one of four lanes by request shape × sticky session binding, the lanes hand the canonical cores to the **acp-kernel** compression engine (fold judgment / summaries / ref ledger — the kernel is never rewritten by host work), egress mapping (`coreTo*`) re-serializes for the four wires, and the model endpoint answers.
|
||||
- **The indigo band is the single SQLite file** (schema v11): the row-level source of truth. Twelve table chips + the red **kstate JSON** chip.
|
||||
- **The three red boxes on the right are the structural pain points** that the #5643 evolution (snapshot-table compression foundation) targets: state living in three places, host identity never landing on disk, and fastpaths patching their own slices instead of one unified snapshot table. The bottom strip states the evolution target (six-stage fixed chain, one storage source of truth) — it is a *proposal* (#5643), not yet built.
|
||||
|
||||
## Module ledger
|
||||
|
||||
| Module | One line | Pages | Status |
|
||||
|---|---|---|---|
|
||||
| `storage` | Unified SQLite: table family, kstate, checkpoints, GC | [storage.md](./architecture/storage.md) · [zh](./architecture/storage.zh-CN.md) | ✅ |
|
||||
| `pipeline` | Request pipeline (handle / prepare-* / relay / inject) | [pipeline.md](./architecture/pipeline.md) · [zh](./architecture/pipeline.zh-CN.md) | ✅ |
|
||||
| `lanes` | Host lanes (dsh / pi / opencode / codex / bare proxy + lane-decisions) | [lanes.md](./architecture/lanes.md) · [zh](./architecture/lanes.zh-CN.md) | ✅ |
|
||||
| `kernel` | Compression engine (acp-kernel: folds, summaries, ref ledger) | [kernel.md](./architecture/kernel.md) · [zh](./architecture/kernel.zh-CN.md) | ✅ |
|
||||
| `identity` | Session & message identity (session id, persona fork, msgid channels) | [identity.md](./architecture/identity.md) · [zh](./architecture/identity.zh-CN.md) | ✅ |
|
||||
| `fastpaths` | Fastpaths (incremental lane, v5 watermark, D-lane snapshot render) | [fastpaths.md](./architecture/fastpaths.md) · [zh](./architecture/fastpaths.zh-CN.md) | ✅ |
|
||||
| `webui` | Web panel & admin surface | [webui.md](./architecture/webui.md) · [zh](./architecture/webui.zh-CN.md) | ✅ |
|
||||
| `update` | Self-update, advisory, plugin install | [update.md](./architecture/update.md) · [zh](./architecture/update.zh-CN.md) | ✅ |
|
||||
|
||||
The hub table above is the single ledger — CI checks that `✅` rows have their page pairs and no extra pages exist.
|
||||
|
||||
## How this relates to the other docs
|
||||
|
||||
- **File-level map** (which file does what, one line each): [reference/architecture.md](../reference/architecture.md) — CI enforces it covers every `src/` file.
|
||||
- **Construction procedures** (build / test / release / git mechanics): [reference/](../reference/README.md).
|
||||
- **Identity doctrine** (the "why" behind identity rules): [message-identity](./message-identity.md) · [session-identity](./session-identity.md) · [identity-channels](./identity-channels.md).
|
||||
- **Reader-facing overview** (what the README links): [how-it-works](../how-it-works.en.svg).
|
||||
|
||||
## Maintenance rules
|
||||
|
||||
- **Same-PR rule** (owner ruling 2026-11-08): structural change ⇒ doc + diagram + ledger row in the same PR. No "docs later".
|
||||
- **CI lane `architecture-docs`** (`tools/check-architecture-docs.mjs`) enforces the mechanical parts:
|
||||
1. `reference/architecture.md` lists every tracked `src/` file (no missing, no ghosts);
|
||||
2. every `✅` ledger row has both page files (en + `.zh-CN`), and no orphan pages exist;
|
||||
3. every page references its `assets/<module>.{en,zh-CN}.svg` **and** a `.png` fallback, all present;
|
||||
4. every SVG is basic-well-formed (balanced tags, no unescaped `&` — the failure mode that once rendered a broken English diagram).
|
||||
- **Visual freshness** of a diagram is not machine-checkable: it rides on the same-PR rule plus review. Diagrams are vector-first (SVG), PNG shipped as fallback, per the AGENTS.md docs rules.
|
||||
@@ -0,0 +1,49 @@
|
||||
# 架构总览
|
||||
|
||||
> 系统架构的唯一枢纽。本页放**整体架构图**与**模块总表**;每个模块在本目录下有独立页面(中英各一份),每页配自己的图。
|
||||
> English: [architecture.md](./architecture.md)
|
||||
>
|
||||
> **实时维护文档(owner 裁定 2026-11-08)**:任何改动模块边界 / 数据流 / 表 / 车道 / 线上路径的 PR,必须**同一 PR** 更新对应页面 + 图 + 本总表。机械部分由 CI 强制(`tools/check-architecture-docs.mjs`);规则条文见 [AGENTS.md](../AGENTS.md)「Documentation Layout」。
|
||||
|
||||
## 整体架构(截至 2026-11-08,master,存储 schema v11)
|
||||
|
||||

|
||||
(位图备选:[architecture-current.zh-CN.png](./architecture/assets/architecture-current.zh-CN.png))
|
||||
|
||||
读图方式:
|
||||
|
||||
- **从左到右是一次模型请求的完整路径。** 宿主车道(dsh / pi / opencode / codex / 裸代理客户端)自带身份(session id 走请求头;插件车道逐元素宿主 msgid 走信封——#5842 采集)。入站适配器 `prepare-*` 归一化 wire,`lane-decisions` 按请求形状 × 会话粘滞绑定把请求分到四条车道之一,车道把 canonical cores 交给 **acp-kernel 压缩内核**(折叠判定 / 摘要 / ref 账本——宿主侧工作从不改写内核),出站映射 `coreTo*` 重序列化到四条 wire,模型端点应答。
|
||||
- **靛色带是唯一的 SQLite 文件**(schema v11):行级事实源。12 张表 chips + 红色 **kstate JSON** chip。
|
||||
- **右侧三个红盒是结构性痛点**,#5643 演进提案(快照表压缩底座)针对的就是它们:状态三处住、宿主身份不落盘、快路径各自打补丁。底部一行是演进目标(六段固定链、单一存储真源)——那是**提案**(#5643),尚未实现。
|
||||
|
||||
## 模块总表
|
||||
|
||||
| 模块 | 一句话 | 页面 | 状态 |
|
||||
|---|---|---|---|
|
||||
| `storage` | 统一 SQLite 存储(表族 / kstate / ckpt / GC) | [storage.zh-CN.md](./architecture/storage.zh-CN.md) · [EN](./architecture/storage.md) | ✅ |
|
||||
| `pipeline` | 请求管道(handle / prepare-* / relay / inject) | [pipeline.zh-CN.md](./architecture/pipeline.zh-CN.md) · [EN](./architecture/pipeline.md) | ✅ |
|
||||
| `lanes` | 宿主车道(dsh / pi / opencode / codex / 裸代理 + lane-decisions) | [lanes.zh-CN.md](./architecture/lanes.zh-CN.md) · [EN](./architecture/lanes.md) | ✅ |
|
||||
| `kernel` | 压缩内核(acp-kernel:折叠 / 摘要 / ref 账本) | [kernel.zh-CN.md](./architecture/kernel.zh-CN.md) · [EN](./architecture/kernel.md) | ✅ |
|
||||
| `identity` | 会话与消息身份(session id / persona fork / msgid 通道) | [identity.zh-CN.md](./architecture/identity.zh-CN.md) · [EN](./architecture/identity.md) | ✅ |
|
||||
| `fastpaths` | 快路径(增量车道 / v5 watermark / D-lane 快照渲染) | [fastpaths.zh-CN.md](./architecture/fastpaths.zh-CN.md) · [EN](./architecture/fastpaths.md) | ✅ |
|
||||
| `webui` | Web 面板与 admin 面 | [webui.zh-CN.md](./architecture/webui.zh-CN.md) · [EN](./architecture/webui.md) | ✅ |
|
||||
| `update` | 自更新、advisory、插件安装 | [update.zh-CN.md](./architecture/update.zh-CN.md) · [EN](./architecture/update.md) | ✅ |
|
||||
|
||||
上表是唯一账本——CI 校验 `✅` 行必有 en+zh-CN 页面成对、且不存在表外的孤儿页面。
|
||||
|
||||
## 与其他文档的关系
|
||||
|
||||
- **文件级地图**(哪个文件干什么,一行一个):[reference/architecture.md](../reference/architecture.md)——CI 强制它覆盖全部 `src/` 文件。
|
||||
- **施工流程**(构建 / 测试 / 发版 / git 机制):[reference/](../reference/README.md)。
|
||||
- **身份教义**(身份规则背后的 why):[message-identity](./message-identity.zh-CN.md) · [session-identity](./session-identity.zh-CN.md) · [identity-channels](./identity-channels.zh-CN.md)。
|
||||
- **面向读者的总览**(README 里那张):[how-it-works](../how-it-works.zh-CN.svg)。
|
||||
|
||||
## 维护规则
|
||||
|
||||
- **同 PR 规则**(owner 裁定 2026-11-08):结构变化 ⇒ 文档 + 图 + 总表行,同一 PR。不存在「文档回头补」。
|
||||
- **CI 车道 `architecture-docs`**(`tools/check-architecture-docs.mjs`)强制机械部分:
|
||||
1. `reference/architecture.md` 列全全部 tracked `src/` 文件(无缺失、无幽灵条目);
|
||||
2. 总表每个 `✅` 行都有 en + `.zh-CN` 两个页面文件,且不存在表外孤儿页面;
|
||||
3. 每个页面引用自己的 `assets/<模块>.{en,zh-CN}.svg` **和** `.png` 备选,文件必须存在;
|
||||
4. 每个 SVG 基础良构(标签配对、无未转义 `&`——曾有一次英文图因此渲染出破图)。
|
||||
- 图的**视觉新鲜度**机器查不了:靠同 PR 规则 + review 兜底。图一律矢量优先(SVG),PNG 作备选随附(AGENTS.md 文档规则)。
|
||||
|
After Width: | Height: | Size: 264 KiB |
@@ -0,0 +1,176 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1560" height="984" viewBox="0 0 1560 984">
|
||||
<style>
|
||||
text { font-family: sans-serif; }
|
||||
.tt { font-size: 22px; font-weight: 700; fill: #0f172a; }
|
||||
.sub { font-size: 13px; fill: #475569; }
|
||||
.h { font-size: 14px; font-weight: 700; fill: #0f172a; }
|
||||
.b { font-size: 12px; fill: #1e293b; }
|
||||
.s { font-size: 11px; fill: #475569; }
|
||||
.chip { font-size: 11px; fill: #334155; }
|
||||
.warn { font-size: 12px; fill: #7f1d1d; font-weight: 700; }
|
||||
.warnb { font-size: 11px; fill: #991b1b; }
|
||||
.num { font-size: 13px; font-weight: 700; fill: #b91c1c; }
|
||||
.leg { font-size: 11px; fill: #334155; }
|
||||
</style>
|
||||
<defs>
|
||||
<marker id="ar" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#334155"/></marker>
|
||||
<marker id="arra" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#b91c1c"/></marker>
|
||||
</defs>
|
||||
|
||||
<rect x="0" y="0" width="1560" height="984" fill="#ffffff"/>
|
||||
<text x="30" y="42" class="tt">Current architecture · bili context-compression proxy (origin/master @ 2026-11-08, storage schema v11)</text>
|
||||
<text x="30" y="68" class="sub">Four lanes each own their slice + kstate JSON as a parallel source of truth — the three structural pain points are boxed in red on the right (the #5854 v6 line was fully reverted out of master; evolution direction: #5643)</text>
|
||||
|
||||
<!-- legend -->
|
||||
<g>
|
||||
<rect x="620" y="84" width="14" height="14" rx="3" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="640" y="95" class="leg">Host / existing pipeline</text>
|
||||
<rect x="790" y="84" width="14" height="14" rx="3" fill="#dcfce7" stroke="#16a34a"/>
|
||||
<text x="810" y="95" class="leg">Kernel (unchanged)</text>
|
||||
<rect x="950" y="84" width="14" height="14" rx="3" fill="#e0e7ff" stroke="#4f46e5"/>
|
||||
<text x="970" y="95" class="leg">Unified storage</text>
|
||||
<rect x="1090" y="84" width="14" height="14" rx="3" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1110" y="95" class="leg">Structural pain point</text>
|
||||
<rect x="1260" y="84" width="14" height="14" rx="3" fill="#fff" stroke="#334155" stroke-width="2"/>
|
||||
<text x="1280" y="95" class="leg">Default main path</text>
|
||||
<rect x="1390" y="84" width="14" height="14" rx="3" fill="#fff" stroke="#334155" stroke-dasharray="4 3"/>
|
||||
<text x="1410" y="95" class="leg">Experimental rollout lane</text>
|
||||
</g>
|
||||
|
||||
<!-- hosts -->
|
||||
<rect x="30" y="112" width="230" height="238" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="145" y="138" class="h" text-anchor="middle">Host lanes (identity capture in place)</text>
|
||||
<text x="48" y="166" class="b">dsh — shim / incremental envelope</text>
|
||||
<text x="48" y="192" class="b">pi — entry-walker capture</text>
|
||||
<text x="48" y="218" class="b">opencode — transform hooks</text>
|
||||
<text x="48" y="244" class="b">codex — responses wire</text>
|
||||
<text x="48" y="270" class="b">other hosts — bare proxy clients</text>
|
||||
<text x="48" y="300" class="s">session id in the request headers;</text>
|
||||
<text x="48" y="316" class="s">plugin lanes carry per-element host</text>
|
||||
<text x="48" y="332" class="s">msgid in the envelope (#5842 in place)</text>
|
||||
|
||||
<!-- ingress -->
|
||||
<rect x="330" y="148" width="250" height="72" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="455" y="176" class="h" text-anchor="middle">Ingress adapters prepare-*</text>
|
||||
<text x="455" y="200" class="s" text-anchor="middle">anthropic | openai | responses | google</text>
|
||||
<!-- branching -->
|
||||
<rect x="330" y="272" width="250" height="62" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="455" y="298" class="h" text-anchor="middle">lane-decisions routing</text>
|
||||
<text x="455" y="320" class="s" text-anchor="middle">request shape × sticky session binding</text>
|
||||
|
||||
<!-- lanes -->
|
||||
<rect x="640" y="112" width="330" height="80" rx="8" fill="#eef2f7" stroke="#334155" stroke-width="2.5"/>
|
||||
<text x="805" y="138" class="h" text-anchor="middle">legacy full-resend path (today's default)</text>
|
||||
<text x="805" y="160" class="s" text-anchor="middle">JSON.parse of everything + full openaiToCore</text>
|
||||
<text x="805" y="176" class="s" text-anchor="middle">lastMessages AST pinned in memory → #5403 OOM</text>
|
||||
|
||||
<rect x="640" y="214" width="330" height="64" rx="8" fill="#f8fafc" stroke="#64748b"/>
|
||||
<text x="805" y="240" class="h" text-anchor="middle">incremental plugin-turn lane</text>
|
||||
<text x="805" y="262" class="s" text-anchor="middle">anthropic wire divert · x-bili-plugin-turn rounds</text>
|
||||
|
||||
<rect x="640" y="300" width="330" height="64" rx="8" fill="#ffffff" stroke="#334155" stroke-dasharray="5 4"/>
|
||||
<text x="805" y="326" class="h" text-anchor="middle">v5 watermark fastpath (5% rollout)</text>
|
||||
<text x="805" y="348" class="s" text-anchor="middle">fastpath-scan structural scan · pf-seq stamp handshake</text>
|
||||
|
||||
<rect x="640" y="382" width="330" height="72" rx="8" fill="#ffffff" stroke="#334155" stroke-dasharray="5 4"/>
|
||||
<text x="805" y="406" class="h" text-anchor="middle">D-lane snapshot render #3756 (≈0% rollout)</text>
|
||||
<text x="805" y="428" class="s" text-anchor="middle">server-side canonical render of egress prefix</text>
|
||||
<text x="805" y="444" class="s" text-anchor="middle">any failure ⇒ wholesale fallback to legacy</text>
|
||||
|
||||
<!-- kernel -->
|
||||
<rect x="1030" y="128" width="250" height="264" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/>
|
||||
<text x="1155" y="156" class="h" text-anchor="middle">acp-kernel compression engine</text>
|
||||
<text x="1155" y="174" class="s" text-anchor="middle">(zero changes in the #5643 evolution)</text>
|
||||
<text x="1048" y="202" class="b">fold judgment projectUnit</text>
|
||||
<text x="1048" y="220" class="b">(shared projection)</text>
|
||||
<text x="1048" y="246" class="b">summary generation + 4 prompts</text>
|
||||
<text x="1048" y="272" class="b">nudge flat-50K fixed cadence</text>
|
||||
<text x="1048" y="298" class="b">ref/msgid ledger (ids never reused)</text>
|
||||
<text x="1048" y="324" class="b">CompressionState:</text>
|
||||
<text x="1048" y="342" class="s">blocks / refs / deadRefs / ckpt</text>
|
||||
<text x="1048" y="360" class="s">tokenSnapshot / nextBlockId …</text>
|
||||
<text x="1048" y="382" class="s">who hydrates state — see below</text>
|
||||
|
||||
<!-- egress -->
|
||||
<rect x="1330" y="128" width="200" height="230" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1430" y="156" class="h" text-anchor="middle">Egress mapping coreTo*</text>
|
||||
<text x="1348" y="186" class="b">four-wire re-serialization</text>
|
||||
<text x="1348" y="214" class="s">carrier branch:</text>
|
||||
<text x="1348" y="232" class="s">pluginMode: no tool+nudge</text>
|
||||
<text x="1348" y="250" class="s">proxy: acp_summary revoiced</text>
|
||||
<text x="1348" y="268" class="s">as a user message</text>
|
||||
<text x="1348" y="296" class="s">pf-*/envelope headers stay</text>
|
||||
<text x="1348" y="314" class="s">inside the proxy</text>
|
||||
<rect x="1330" y="402" width="200" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1430" y="426" class="h" text-anchor="middle">Model endpoint</text>
|
||||
<text x="1430" y="444" class="s" text-anchor="middle">sglang / openai·responses</text>
|
||||
<text x="1430" y="458" class="s" text-anchor="middle">anthropic / google</text>
|
||||
|
||||
<!-- storage band -->
|
||||
<rect x="30" y="520" width="1300" height="240" rx="8" fill="#eef2ff" stroke="#4f46e5"/>
|
||||
<text x="50" y="550" class="h">Unified SQLite · schema v11 (#5539 FK sub-index) — the row-level source of truth is only half there</text>
|
||||
<!-- table chips row1 -->
|
||||
<g>
|
||||
<rect x="50" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="109" y="588" class="chip" text-anchor="middle">sessions</text>
|
||||
<rect x="178" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="237" y="588" class="chip" text-anchor="middle">content</text>
|
||||
<rect x="306" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="365" y="588" class="chip" text-anchor="middle">messages</text>
|
||||
<rect x="434" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="493" y="588" class="chip" text-anchor="middle">blocks / dead_refs</text>
|
||||
<rect x="562" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="621" y="588" class="chip" text-anchor="middle">refs / checkpoints</text>
|
||||
<rect x="690" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="749" y="588" class="chip" text-anchor="middle">ccr_entries</text>
|
||||
<rect x="818" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="877" y="588" class="chip" text-anchor="middle">kv_store</text>
|
||||
<rect x="946" y="568" width="150" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="1021" y="588" class="chip" text-anchor="middle">message_media / ext</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect x="50" y="608" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="109" y="628" class="chip" text-anchor="middle">conversations</text>
|
||||
<rect x="178" y="608" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="237" y="628" class="chip" text-anchor="middle">session_ext</text>
|
||||
<rect x="306" y="608" width="240" height="30" rx="5" fill="#fee2e2" stroke="#ef4444"/><text x="426" y="628" class="warn" text-anchor="middle">kstate JSON (hydration field list)</text>
|
||||
</g>
|
||||
<text x="50" y="668" class="warnb">messages.msgId stores bili/kernel canonical ids — the host msgid has no landing spot; no table carries sess_raw.</text>
|
||||
<text x="50" y="690" class="warnb">The surviving CompressionState fields are defined once by src/state-hydration.ts mergeState() and stored via kstate JSON through persist.ts.</text>
|
||||
<text x="50" y="730" class="s">#5855 (v6 re-land · PF transaction skeleton) is open, awaiting human merge — the new four-table DDL must layer on top of it.</text>
|
||||
|
||||
<!-- red warning boxes right -->
|
||||
<rect x="1150" y="520" width="380" height="70" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1166" y="545" class="warn">⚠ Pain 1: state lives in three places</text>
|
||||
<text x="1166" y="565" class="warnb">dual-write fork bricked the reverted line; #5403 OOM = full</text>
|
||||
<text x="1166" y="581" class="warnb">lastMessages residency; restart reassembles via mergeState</text>
|
||||
<rect x="1150" y="602" width="380" height="70" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1166" y="627" class="warn">⚠ Pain 2: identity never lands on disk</text>
|
||||
<text x="1166" y="647" class="warnb">host (sess_raw, msgid) pairs stripped at ingest — one-turn</text>
|
||||
<text x="1166" y="663" class="warnb">envelope life only: cold-start re-probe + re-arm every turn</text>
|
||||
<rect x="1150" y="684" width="380" height="76" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1166" y="709" class="warn">⚠ Pain 3: fastpaths patch their own slices</text>
|
||||
<text x="1166" y="729" class="warnb">v5 watermark / incremental / D-lane each own a slice; cache</text>
|
||||
<text x="1166" y="745" class="warnb">stability = stacked patches; a slip = poisoning or rollback</text>
|
||||
|
||||
<!-- problem strip -->
|
||||
<rect x="30" y="800" width="1500" height="100" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
|
||||
<text x="50" y="830" class="h" fill="#b91c1c">Evolution target (#5643): raw bytes → protocol translation → rewrite (compression) → snapshot-table apply → egress mapping → egress — six-stage fixed chain, full every turn, one storage source of truth.</text>
|
||||
<text x="50" y="858" class="b">Kernel (fold judgment / summaries / prompts / ref contract) untouched · hosts with session+msgid all take this path · no msgid degrades by order>hash into the same tables.</text>
|
||||
<text x="50" y="882" class="s">Mapping onto this diagram: ingress → four lanes (replaced by the chain's identity-ized stages 0–1) → kernel (stage 2, untouched) → egress (stages 4–5); the new stage 0 (L1 identity) and stage 3 (snapshot table) do not exist today.</text>
|
||||
|
||||
<!-- arrows -->
|
||||
<g stroke="#334155" fill="none" stroke-width="1.6">
|
||||
<path d="M260,200 H300 V184 H330" marker-end="url(#ar)"/>
|
||||
<path d="M455,220 V272" marker-end="url(#ar)"/>
|
||||
<path d="M580,303 H612"/>
|
||||
<path d="M612,152 V418"/>
|
||||
<path d="M612,152 H640" marker-end="url(#ar)"/>
|
||||
<path d="M612,246 H640" marker-end="url(#ar)"/>
|
||||
<path d="M612,332 H640" marker-end="url(#ar)"/>
|
||||
<path d="M612,418 H640" marker-end="url(#ar)"/>
|
||||
<path d="M970,152 H1002"/>
|
||||
<path d="M970,246 H1002"/>
|
||||
<path d="M970,332 H1002"/>
|
||||
<path d="M970,418 H1002"/>
|
||||
<path d="M1002,152 V418"/>
|
||||
<path d="M1002,265 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1280,243 H1330" marker-end="url(#ar)"/>
|
||||
<path d="M1430,358 V402" marker-end="url(#ar)"/>
|
||||
</g>
|
||||
<!-- state dual-channel arrows to storage -->
|
||||
<g stroke="#b91c1c" fill="none" stroke-width="1.4" stroke-dasharray="5 4">
|
||||
<path d="M1155,392 V520" marker-end="url(#arra)"/>
|
||||
</g>
|
||||
<text x="1163" y="470" class="warnb">State read/write = kstate JSON + tables dual channel (the fork point)</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 326 KiB |
@@ -0,0 +1,174 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1560" height="984" viewBox="0 0 1560 984">
|
||||
<style>
|
||||
html,body { margin:0; padding:0; background:#fff; }
|
||||
text { font-family: 'Noto Sans CJK SC','Droid Sans Fallback',sans-serif; }
|
||||
.tt { font-size: 22px; font-weight: 700; fill: #0f172a; }
|
||||
.sub { font-size: 13px; fill: #475569; }
|
||||
.h { font-size: 14px; font-weight: 700; fill: #0f172a; }
|
||||
.b { font-size: 12px; fill: #1e293b; }
|
||||
.s { font-size: 11px; fill: #475569; }
|
||||
.chip { font-size: 11px; fill: #334155; }
|
||||
.warn { font-size: 12px; fill: #7f1d1d; font-weight: 700; }
|
||||
.warnb { font-size: 11px; fill: #991b1b; }
|
||||
.num { font-size: 13px; font-weight: 700; fill: #b91c1c; }
|
||||
.leg { font-size: 11px; fill: #334155; }
|
||||
</style>
|
||||
<defs>
|
||||
<marker id="ar" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#334155"/></marker>
|
||||
<marker id="arra" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#b91c1c"/></marker>
|
||||
</defs>
|
||||
|
||||
<rect x="0" y="0" width="1560" height="984" fill="#ffffff"/>
|
||||
<text x="30" y="42" class="tt">现状架构 · bili 上下文压缩代理(origin/master @ 2026-11-08,存储 schema v11)</text>
|
||||
<text x="30" y="68" class="sub">四条车道各自为政 + kstate JSON 平行真源 —— 右侧红盒为三个结构性痛点(#5854 已把 v6 整线撤出 master;演进方向见 #5643)</text>
|
||||
|
||||
<!-- legend -->
|
||||
<g>
|
||||
<rect x="620" y="84" width="14" height="14" rx="3" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="640" y="95" class="leg">宿主/既有管道</text>
|
||||
<rect x="740" y="84" width="14" height="14" rx="3" fill="#dcfce7" stroke="#16a34a"/>
|
||||
<text x="760" y="95" class="leg">内核(不改)</text>
|
||||
<rect x="850" y="84" width="14" height="14" rx="3" fill="#e0e7ff" stroke="#4f46e5"/>
|
||||
<text x="870" y="95" class="leg">统一存储</text>
|
||||
<rect x="950" y="84" width="14" height="14" rx="3" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="970" y="95" class="leg">结构性痛点</text>
|
||||
<rect x="1070" y="84" width="14" height="14" rx="3" fill="#fff" stroke="#334155" stroke-width="2"/>
|
||||
<text x="1090" y="95" class="leg">默认主路径</text>
|
||||
<rect x="1190" y="84" width="14" height="14" rx="3" fill="#fff" stroke="#334155" stroke-dasharray="4 3"/>
|
||||
<text x="1210" y="95" class="leg">实验性灰度车道</text>
|
||||
</g>
|
||||
|
||||
<!-- hosts -->
|
||||
<rect x="30" y="112" width="230" height="238" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="145" y="138" class="h" text-anchor="middle">宿主车道(今天已有身份采集)</text>
|
||||
<text x="48" y="166" class="b">dsh — shim / 增量信封</text>
|
||||
<text x="48" y="192" class="b">pi — entry-walker 采集</text>
|
||||
<text x="48" y="218" class="b">opencode — transform 钩子</text>
|
||||
<text x="48" y="244" class="b">codex — responses wire</text>
|
||||
<text x="48" y="270" class="b">其他宿主 — 裸代理客户端</text>
|
||||
<text x="48" y="300" class="s">请求头带 session id;插件车道</text>
|
||||
<text x="48" y="316" class="s">信封里逐元素带宿主 msgid</text>
|
||||
<text x="48" y="332" class="s">(#5842 采集器已就位)</text>
|
||||
|
||||
<!-- ingress -->
|
||||
<rect x="330" y="148" width="250" height="72" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="455" y="176" class="h" text-anchor="middle">入站适配器 prepare-*</text>
|
||||
<text x="455" y="200" class="s" text-anchor="middle">anthropic | openai | responses | google</text>
|
||||
<!-- branching -->
|
||||
<rect x="330" y="272" width="250" height="62" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="455" y="298" class="h" text-anchor="middle">lane-decisions 分轨</text>
|
||||
<text x="455" y="320" class="s" text-anchor="middle">按请求形状 × 会话粘滞绑定</text>
|
||||
|
||||
<!-- lanes -->
|
||||
<rect x="640" y="112" width="330" height="80" rx="8" fill="#eef2f7" stroke="#334155" stroke-width="2.5"/>
|
||||
<text x="805" y="138" class="h" text-anchor="middle">legacy 全量重发路径(今天的默认主路径)</text>
|
||||
<text x="805" y="160" class="s" text-anchor="middle">JSON.parse 全量 + openaiToCore 全量转换</text>
|
||||
<text x="805" y="176" class="s" text-anchor="middle">lastMessages AST 钉在内存跨轮驻留(#5403 OOM 生产者)</text>
|
||||
|
||||
<rect x="640" y="214" width="330" height="64" rx="8" fill="#f8fafc" stroke="#64748b"/>
|
||||
<text x="805" y="240" class="h" text-anchor="middle">增量 plugin-turn 车道</text>
|
||||
<text x="805" y="262" class="s" text-anchor="middle">anthropic wire divert · x-bili-plugin-turn 回合</text>
|
||||
|
||||
<rect x="640" y="300" width="330" height="64" rx="8" fill="#ffffff" stroke="#334155" stroke-dasharray="5 4"/>
|
||||
<text x="805" y="326" class="h" text-anchor="middle">v5 watermark 快路径(5% 灰度)</text>
|
||||
<text x="805" y="348" class="s" text-anchor="middle">fastpath-scan 结构扫描 · x-bili-pf-seq 戳握手</text>
|
||||
|
||||
<rect x="640" y="386" width="330" height="64" rx="8" fill="#ffffff" stroke="#334155" stroke-dasharray="5 4"/>
|
||||
<text x="805" y="412" class="h" text-anchor="middle">D-lane 快照渲染 #3756(≈0% 灰度)</text>
|
||||
<text x="805" y="434" class="s" text-anchor="middle">服务端正史渲染出站前缀 · 失败整体回退 legacy</text>
|
||||
|
||||
<!-- kernel -->
|
||||
<rect x="1030" y="128" width="250" height="252" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/>
|
||||
<text x="1155" y="156" class="h" text-anchor="middle">acp-kernel 压缩内核</text>
|
||||
<text x="1155" y="174" class="s" text-anchor="middle">(#5643 演进提案中零改动)</text>
|
||||
<text x="1048" y="202" class="b">折叠判定 projectUnit(共享投影)</text>
|
||||
<text x="1048" y="228" class="b">摘要生成 + 四条 prompts</text>
|
||||
<text x="1048" y="254" class="b">nudge flat-50K 固定节拍</text>
|
||||
<text x="1048" y="280" class="b">ref/msgid 账本(id 永不复用)</text>
|
||||
<text x="1048" y="306" class="b">CompressionState:</text>
|
||||
<text x="1048" y="324" class="s">blocks / refs / deadRefs / ckpt</text>
|
||||
<text x="1048" y="342" class="s">tokenSnapshot / nextBlockId …</text>
|
||||
<text x="1048" y="368" class="s">状态由谁水合、存哪 —— 见下</text>
|
||||
|
||||
<!-- egress -->
|
||||
<rect x="1330" y="128" width="200" height="230" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1430" y="156" class="h" text-anchor="middle">出站映射 coreTo*</text>
|
||||
<text x="1348" y="186" class="b">四线协议重新序列化</text>
|
||||
<text x="1348" y="214" class="s">carrier 分支:</text>
|
||||
<text x="1348" y="232" class="s">pluginMode:抑制 tool+nudge</text>
|
||||
<text x="1348" y="250" class="s">proxy:acp_summary</text>
|
||||
<text x="1348" y="268" class="s">revoice 为 user 消息</text>
|
||||
<text x="1348" y="296" class="s">pf-*/信封头永不出代理</text>
|
||||
<rect x="1330" y="402" width="200" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1430" y="426" class="h" text-anchor="middle">模型端点</text>
|
||||
<text x="1430" y="444" class="s" text-anchor="middle">sglang / openai·responses</text>
|
||||
<text x="1430" y="458" class="s" text-anchor="middle">anthropic / google</text>
|
||||
|
||||
<!-- storage band -->
|
||||
<rect x="30" y="520" width="1300" height="240" rx="8" fill="#eef2ff" stroke="#4f46e5"/>
|
||||
<text x="50" y="550" class="h">统一 SQLite · schema v11(#5539 FK 子索引)—— 行级真源只有一半</text>
|
||||
<!-- table chips row1 -->
|
||||
<g>
|
||||
<rect x="50" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="109" y="588" class="chip" text-anchor="middle">sessions</text>
|
||||
<rect x="178" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="237" y="588" class="chip" text-anchor="middle">content</text>
|
||||
<rect x="306" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="365" y="588" class="chip" text-anchor="middle">messages</text>
|
||||
<rect x="434" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="493" y="588" class="chip" text-anchor="middle">blocks / dead_refs</text>
|
||||
<rect x="562" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="621" y="588" class="chip" text-anchor="middle">refs / checkpoints</text>
|
||||
<rect x="690" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="749" y="588" class="chip" text-anchor="middle">ccr_entries</text>
|
||||
<rect x="818" y="568" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="877" y="588" class="chip" text-anchor="middle">kv_store</text>
|
||||
<rect x="946" y="568" width="150" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="1021" y="588" class="chip" text-anchor="middle">message_media / ext</text>
|
||||
</g>
|
||||
<g>
|
||||
<rect x="50" y="608" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="109" y="628" class="chip" text-anchor="middle">conversations</text>
|
||||
<rect x="178" y="608" width="118" height="30" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="237" y="628" class="chip" text-anchor="middle">session_ext</text>
|
||||
<rect x="306" y="608" width="240" height="30" rx="5" fill="#fee2e2" stroke="#ef4444"/><text x="426" y="628" class="warn" text-anchor="middle">kstate JSON(hydration 字段清单)</text>
|
||||
</g>
|
||||
<text x="50" y="668" class="warnb">messages.msgId 列存的是 bili/内核规范 id —— 宿主 msgid 没有落点;sess_raw 无任何表承载。</text>
|
||||
<text x="50" y="690" class="warnb">CompressionState 的存活字段由 src/state-hydration.ts mergeState() 单一定义,经 persist.ts 走 kstate JSON 存取。</text>
|
||||
<text x="50" y="730" class="s">#5855(v6 re-land · PF 事务骨架)open,待人工合入 —— 新四表 DDL 必须叠在它落地之后。</text>
|
||||
|
||||
<!-- red warning boxes right -->
|
||||
<rect x="1150" y="520" width="380" height="70" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1166" y="545" class="warn">⚠ 痛点① 状态三处住:进程内存 / 表 / kstate JSON</text>
|
||||
<text x="1166" y="565" class="warnb">双写分叉是刚撤回那条线的根病;#5403 OOM 来自 lastMessages 整包驻留。</text>
|
||||
<text x="1166" y="581" class="warnb">重启靠 mergeState 水合拼装,拼错即降级或烧会话。</text>
|
||||
<rect x="1150" y="602" width="380" height="70" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1166" y="627" class="warn">⚠ 痛点② 身份不落盘:世界匹配永远冷启动</text>
|
||||
<text x="1166" y="647" class="warnb">宿主 (sess_raw, msgid) 对 ingest 即剥掉,只在 in-flight 信封里活一轮。</text>
|
||||
<text x="1166" y="663" class="warnb">「这元素见过没」跨进程/跨重启无法回答 ⇒ 每轮重探测、重武装。</text>
|
||||
<rect x="1150" y="684" width="380" height="76" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="1166" y="709" class="warn">⚠ 痛点③ 快路径各自打补丁,无统一快照表</text>
|
||||
<text x="1166" y="729" class="warnb">v5 水位 / 增量车道 / D-lane 各管一段流量;缓存稳定性靠多层补丁堆叠,</text>
|
||||
<text x="1166" y="745" class="warnb">任何一层失步就是缓存投毒或整体回退。缺一个单一存储真源。</text>
|
||||
|
||||
<!-- problem strip -->
|
||||
<rect x="30" y="800" width="1500" height="100" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
|
||||
<text x="50" y="830" class="h" fill="#b91c1c">演进目标(#5643 提案):原始字节 → 协议转换 → 改写(压缩) → 快照表应用 → 出站映射 → 出站,六段固定链每轮全走完,单一存储真源。</text>
|
||||
<text x="50" y="858" class="b">内核(折判定/摘要/prompts/ref 契约)零改动 · 有 session+msgid 的宿主全走此路 · 无 msgid 按 顺序>hash 降级写同一套表。</text>
|
||||
<text x="50" y="882" class="s">现状图对应物:左起入站 → 四车道(替代为本链第 0–1 段的身份化分轨)→ 内核(第 2 段,不动)→ 出站(第 4–5 段);新增的第 0 段(L1 身份)与第 3 段(快照表)在现状中不存在。</text>
|
||||
|
||||
<!-- arrows -->
|
||||
<g stroke="#334155" fill="none" stroke-width="1.6">
|
||||
<path d="M260,200 H300 V184 H330" marker-end="url(#ar)"/>
|
||||
<path d="M455,220 V272" marker-end="url(#ar)"/>
|
||||
<path d="M580,303 H612"/>
|
||||
<path d="M612,152 V418"/>
|
||||
<path d="M612,152 H640" marker-end="url(#ar)"/>
|
||||
<path d="M612,246 H640" marker-end="url(#ar)"/>
|
||||
<path d="M612,332 H640" marker-end="url(#ar)"/>
|
||||
<path d="M612,418 H640" marker-end="url(#ar)"/>
|
||||
<path d="M970,152 H1002"/>
|
||||
<path d="M970,246 H1002"/>
|
||||
<path d="M970,332 H1002"/>
|
||||
<path d="M970,418 H1002"/>
|
||||
<path d="M1002,152 V418"/>
|
||||
<path d="M1002,265 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1280,243 H1330" marker-end="url(#ar)"/>
|
||||
<path d="M1430,358 V402" marker-end="url(#ar)"/>
|
||||
</g>
|
||||
<!-- state dual-channel arrows to storage -->
|
||||
<g stroke="#b91c1c" fill="none" stroke-width="1.4" stroke-dasharray="5 4">
|
||||
<path d="M1155,380 V520" marker-end="url(#arra)"/>
|
||||
</g>
|
||||
<text x="1163" y="470" class="warnb">状态读写 = kstate JSON + 表 双通道(分叉点)</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 13 KiB |
|
After Width: | Height: | Size: 136 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="720" viewBox="0 0 1240 720">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="720" fill="#ffffff"/><rect x="40" y="100" width="240" height="260" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="340" y="100" width="240" height="260" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="640" y="100" width="290" height="260" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2.5"/><rect x="980" y="100" width="220" height="260" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="560" height="110" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="640" y="420" width="560" height="110" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="40" y="585" width="1160" height="56" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="284" y1="230" x2="336" y2="230" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="584" y1="230" x2="636" y2="230" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="934" y1="230" x2="976" y2="230" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: fastpaths (incremental lane / v5 watermark / D-lane / legacy)</text><text x="40" y="70" class="sub">four ways to skip re-doing wire work on plugin full-resend turns — one request always takes exactly one</text><text x="54" y="126" class="h">Plugin full-resend turn</text><text x="54" y="146" class="b">host re-sends full history each turn</text><text x="54" y="163.5" class="b">+ stamped headers (x-bili-pf-seq /</text><text x="54" y="181" class="b">-count / -tail-ids, #5403/#4491)</text><text x="54" y="198.5" class="b">+ plugin-turn envelope (x-bili-</text><text x="54" y="216" class="b">plugin-turn, #3248)</text><text x="54" y="233.5" class="b">shape gate: anthropic wire →</text><text x="54" y="251" class="b">incremental divert; openai shape →</text><text x="54" y="268.5" class="b">watermark lane (#3433)</text><text x="354" y="126" class="h">lane-decisions</text><text x="354" y="146" class="b">single resolver, per request</text><text x="354" y="163.5" class="b">sticky per session (upgrade-only)</text><text x="354" y="181" class="b">rows = truth-table driven</text><text x="354" y="198.5" class="b">(tests/lane-decisions-matrix.test.ts,</text><text x="354" y="216" class="b">positive+negative pairs #3617)</text><text x="654" y="126" class="h">The three fast lanes</text><text x="654" y="146" class="b">① incremental plugin-turn lane:</text><text x="654" y="163.5" class="b"> diff + ack + resync (host msgids)</text><text x="654" y="181" class="b">② v5 watermark: structural scan</text><text x="654" y="198.5" class="b"> (zero-decode), stamp-verify ladder,</text><text x="654" y="216" class="b"> 5 proven-miss ⇒ 1h breaker</text><text x="654" y="233.5" class="b">③ D-lane snapshot render: outbound</text><text x="654" y="251" class="b"> prefix from server transcript (#3756)</text><text x="654" y="268.5" class="b">any doubt ⇒ whole turn back to legacy</text><text x="994" y="126" class="h">legacy full-resend</text><text x="994" y="146" class="b">untouched full-parse path</text><text x="994" y="163.5" class="b">default for every shape</text><text x="994" y="181" class="b">the fallback safety net</text><text x="994" y="198.5" class="b">re-stamps truth headers so the</text><text x="994" y="216" class="b">client converges in one turn</text><text x="994" y="233.5" class="b">(#5403: OOM producer removed</text><text x="994" y="251" class="b">from hit turns only)</text><text x="54" y="446" class="h">What a hit skips</text><text x="54" y="466" class="b">full JSON.parse + openaiToCore over the whole body (v5)</text><text x="54" y="483.5" class="b">snapshotMessages re-pin of the prefix (v5)</text><text x="54" y="501" class="b">incremental: only the delta is parsed; D-lane: prefix re-rendered from rows</text><text x="654" y="446" class="h">Honest boundaries</text><text x="654" y="466" class="b">byte-rewrites that keep element count are undetectable (human review tier)</text><text x="654" y="483.5" class="b">multimodal tails in cache ⇒ that history stays legacy (KDD #15)</text><text x="654" y="501" class="b">pf-* headers are protocol headers: stripped before upstream</text><text x="58" y="613" class="s">#5643 evolution: all four lanes converge onto the snapshot table foundation (one storage source of truth); until then each lane keeps its own bookkeeping — that bookkeeping sprawl is exactly what the foundation removes.</text></svg>
|
||||
|
After Width: | Height: | Size: 5.2 KiB |
|
After Width: | Height: | Size: 148 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="720" viewBox="0 0 1240 720">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="720" fill="#ffffff"/><rect x="40" y="100" width="240" height="260" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="340" y="100" width="240" height="260" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="640" y="100" width="290" height="260" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2.5"/><rect x="980" y="100" width="220" height="260" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="560" height="110" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="640" y="420" width="560" height="110" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="40" y="585" width="1160" height="56" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="284" y1="230" x2="336" y2="230" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="584" y1="230" x2="636" y2="230" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="934" y1="230" x2="976" y2="230" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:快路径(增量车道 / v5 水位 / D-lane / legacy)</text><text x="40" y="70" class="sub">插件全量重发回合跳过重复 wire 工作的四条路 —— 一个请求恒走其中一条</text><text x="54" y="126" class="h">插件全量重发回合</text><text x="54" y="146" class="b">宿主每轮重发完整历史</text><text x="54" y="163.5" class="b">+ 盖章头(x-bili-pf-seq /</text><text x="54" y="181" class="b">-count / -tail-ids,#5403/#4491)</text><text x="54" y="198.5" class="b">+ plugin-turn 信封(x-bili-</text><text x="54" y="216" class="b">plugin-turn,#3248)</text><text x="54" y="233.5" class="b">形状门:anthropic wire → 增量</text><text x="54" y="251" class="b">divert;openai 形 → 水位车道</text><text x="54" y="268.5" class="b">(#3433)</text><text x="354" y="126" class="h">lane-decisions</text><text x="354" y="146" class="b">单一裁决器、逐请求</text><text x="354" y="163.5" class="b">逐会话粘滞(只升不降)</text><text x="354" y="181" class="b">行 = 真值表驱动</text><text x="354" y="198.5" class="b">(tests/lane-decisions-matrix.</text><text x="354" y="216" class="b">test.ts,正负成对 #3617)</text><text x="654" y="126" class="h">三条快车道</text><text x="654" y="146" class="b">① 增量 plugin-turn 车道:diff +</text><text x="654" y="163.5" class="b"> ack + resync(宿主 msgid)</text><text x="654" y="181" class="b">② v5 水位:结构扫描(零解码)、</text><text x="654" y="198.5" class="b"> 盖戳-验证阶梯、5 次可证 miss ⇒</text><text x="654" y="216" class="b"> 1h 熔断</text><text x="654" y="233.5" class="b">③ D-lane 快照渲染:出站前缀由</text><text x="654" y="251" class="b"> 服务端正史渲染(#3756)</text><text x="654" y="268.5" class="b">任何疑点 ⇒ 整轮回 legacy</text><text x="994" y="126" class="h">legacy 全量重发</text><text x="994" y="146" class="b">原封未动的全量解析路径</text><text x="994" y="163.5" class="b">所有形状的默认</text><text x="994" y="181" class="b">兜底安全网</text><text x="994" y="198.5" class="b">重盖真值头让客户端一轮</text><text x="994" y="216" class="b">收敛(#5403:OOM 生产者</text><text x="994" y="233.5" class="b">只从命中回合上移除)</text><text x="54" y="446" class="h">命中时跳过的活</text><text x="54" y="466" class="b">整包 JSON.parse + openaiToCore 全量转换(v5)</text><text x="54" y="483.5" class="b">snapshotMessages 前缀重钉(v5)</text><text x="54" y="501" class="b">增量:只解析差量;D-lane:前缀按行重渲</text><text x="654" y="446" class="h">诚实边界</text><text x="654" y="466" class="b">保元素数的前缀字节改写不可检测(人工评审级)</text><text x="654" y="483.5" class="b">多模态尾部入缓存 ⇒ 该段历史留在 legacy(KDD #15)</text><text x="654" y="501" class="b">pf-* 是协议头:出代理前剥掉</text><text x="58" y="613" class="s">#5643 演进:四条车道最终收敛到快照表底座(单一存储真源);在那之前各车道各记各的账 —— 这份账目 sprawl 正是底座要消除的东西。</text></svg>
|
||||
|
After Width: | Height: | Size: 5.0 KiB |
|
After Width: | Height: | Size: 116 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="270" height="250" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="360" y="110" width="270" height="250" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="680" y="110" width="270" height="250" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="990" y="110" width="210" height="250" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="314" y1="235" x2="356" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="634" y1="235" x2="676" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="954" y1="235" x2="986" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: session & message identity</text><text x="40" y="70" class="sub">which session a request belongs to, which messages are new, and what identity survives the wire</text><text x="54" y="136" class="h">Session identity</text><text x="54" y="156" class="b">client id verbatim (native stable id</text><text x="54" y="173.5" class="b">preferred, #280)</text><text x="54" y="191" class="b">anonymous → prefix-affinity pfa-*</text><text x="54" y="208.5" class="b">(first-writer provenance #2879)</text><text x="54" y="226" class="b">persona fork: subagentNamespace(id,</text><text x="54" y="243.5" class="b">system) — evidence permitlist (dsh</text><text x="54" y="261" class="b">#1104/#2156), first system anchors</text><text x="54" y="278.5" class="b">the raw key, side requests never do</text><text x="374" y="136" class="h">Message identity</text><text x="374" y="156" class="b">rung: msgid > order > hash (#11)</text><text x="374" y="173.5" class="b">msgid = host envelope, per-element,</text><text x="374" y="191" class="b">stripped at ingest — never on the</text><text x="374" y="208.5" class="b">model wire (#4491/#4834/#5842)</text><text x="374" y="226" class="b">ledger key: (session_id, msg_id,</text><text x="374" y="243.5" class="b">content_hash) — id decides, hash is</text><text x="374" y="261" class="b">the safety belt</text><text x="374" y="278.5" class="b">order = primary carrier for legacy</text><text x="374" y="296" class="b">full-resend (reconcile ladder)</text><text x="694" y="136" class="h">Server-side render</text><text x="694" y="156" class="b">D-lane snapshot render (#3756):</text><text x="694" y="173.5" class="b">outbound PREFIX from server transcript,</text><text x="694" y="191" class="b">row seq = message identity, tail stays</text><text x="694" y="208.5" class="b">client-verbatim (cache-stable)</text><text x="694" y="226" class="b">any desync → whole turn falls back to</text><text x="694" y="243.5" class="b">legacy (degrade, never guess)</text><text x="694" y="261" class="b">reconcileFoldCoverage keeps observing</text><text x="694" y="278.5" class="b">the client view (observe ≠ render)</text><text x="1004" y="136" class="h">Docs</text><text x="1004" y="156" class="b">message-identity.md</text><text x="1004" y="173.5" class="b">session-identity.md</text><text x="1004" y="191" class="b">identity-channels.md</text><text x="1004" y="208.5" class="b">msgid-infrastructure.md</text><text x="1004" y="226" class="b">session-identity-</text><text x="1004" y="243.5" class="b">resolution.md</text><text x="58" y="448" class="s">Identity dimensions survive different churn: order survives re-encoding AND id re-minting, content survives id churn, ids survive re-encoding — the reconcile ladder is the union of their survival domains, each rung fails soft.</text><text x="58" y="474" class="s">P8 (foundation proposal #5643): (sess_raw, ledger_id) first-seen, never deleted, answers identically across restarts — the l1_world table is its planned home.</text></svg>
|
||||
|
After Width: | Height: | Size: 4.6 KiB |
|
After Width: | Height: | Size: 123 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="270" height="250" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="360" y="110" width="270" height="250" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="680" y="110" width="270" height="250" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="990" y="110" width="210" height="250" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="314" y1="235" x2="356" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="634" y1="235" x2="676" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="954" y1="235" x2="986" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:会话与消息身份</text><text x="40" y="70" class="sub">请求属于哪个会话、哪些消息是新的、什么身份能穿过 wire</text><text x="54" y="136" class="h">会话身份</text><text x="54" y="156" class="b">客户端 id 逐字(优先原生稳定</text><text x="54" y="173.5" class="b">id,#280)</text><text x="54" y="191" class="b">匿名 → 前缀亲和 pfa-*</text><text x="54" y="208.5" class="b">(首写者出处 #2879)</text><text x="54" y="226" class="b">persona 分叉:subagentNamespace(id,</text><text x="54" y="243.5" class="b">system) —— 证据白名单(dsh</text><text x="54" y="261" class="b">#1104/#2156),首个 system 锚定</text><text x="54" y="278.5" class="b">原始键,side 请求永不锚定</text><text x="374" y="136" class="h">消息身份</text><text x="374" y="156" class="b">层级:msgid > 顺序 > hash (#11)</text><text x="374" y="173.5" class="b">msgid = 宿主信封、逐元素、入站</text><text x="374" y="191" class="b">即剥 —— 永不出现在模型线</text><text x="374" y="208.5" class="b">(#4491/#4834/#5842)</text><text x="374" y="226" class="b">账本键:(session_id, msg_id,</text><text x="374" y="243.5" class="b">content_hash) —— id 定身份、</text><text x="374" y="261" class="b">hash 是安全带</text><text x="374" y="278.5" class="b">顺序 = legacy 全量重发的主载体</text><text x="374" y="296" class="b">(reconcile 阶梯)</text><text x="694" y="136" class="h">服务端渲染</text><text x="694" y="156" class="b">D-lane 快照渲染(#3756):出站</text><text x="694" y="173.5" class="b">前缀由服务端正史渲染、行 seq =</text><text x="694" y="191" class="b">消息身份、尾巴保持客户端逐字</text><text x="694" y="208.5" class="b">(缓存稳定)</text><text x="694" y="226" class="b">任何失步 → 整轮回退 legacy</text><text x="694" y="243.5" class="b">(降级不猜)</text><text x="694" y="261" class="b">reconcileFoldCoverage 继续观察</text><text x="694" y="278.5" class="b">客户端视图(观测 ≠ 渲染)</text><text x="1004" y="136" class="h">文档</text><text x="1004" y="156" class="b">message-identity.md</text><text x="1004" y="173.5" class="b">session-identity.md</text><text x="1004" y="191" class="b">identity-channels.md</text><text x="1004" y="208.5" class="b">msgid-infrastructure.md</text><text x="1004" y="226" class="b">session-identity-</text><text x="1004" y="243.5" class="b">resolution.md</text><text x="58" y="448" class="s">身份维度抗不同的抖动:顺序抗重编码且抗 id 重铸、内容抗 id 抖动、id 抗重编码 —— reconcile 阶梯是它们存活域的并集,每一档都软失败。</text><text x="58" y="474" class="s">P8(底座提案 #5643):(sess_raw, ledger_id) 首见即写入、永不删改、跨重启恒可答 —— 计划落 l1_world 表。</text></svg>
|
||||
|
After Width: | Height: | Size: 4.5 KiB |
|
After Width: | Height: | Size: 104 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="250" height="220" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="350" y="110" width="250" height="220" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="660" y="110" width="250" height="220" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="3"/><rect x="970" y="110" width="230" height="220" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="294" y1="220" x2="346" y2="220" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="604" y1="220" x2="656" y2="220" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="914" y1="220" x2="966" y2="220" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: compression kernel (kernel/ — acp-kernel, in-repo)</text><text x="40" y="70" class="sub">the decision core: what may fold, what a fold emits, and the state that survives restarts</text><text x="54" y="136" class="h">Input</text><text x="54" y="156" class="b">canonical cores (host-agnostic)</text><text x="54" y="173.5" class="b">CompressionState: blocks / refs /</text><text x="54" y="191" class="b">dead_refs / checkpoints / nudge /</text><text x="54" y="208.5" class="b">tokenSnapshot</text><text x="54" y="226" class="b">applyView = the exact array class</text><text x="54" y="243.5" class="b">applyCompression runs on (KDD #12)</text><text x="364" y="136" class="h">Unit projection</text><text x="364" y="156" class="b">projectUnit — the ONLY foldability</text><text x="364" y="173.5" class="b">definition (KDD #12, #3236):</text><text x="364" y="191" class="b">boundary widen → carrier/coverage/</text><text x="364" y="208.5" class="b">media carve → protected-zone carve</text><text x="364" y="226" class="b">→ turn-integrity → emptiness</text><text x="364" y="243.5" class="b">fatal units → structured error,</text><text x="364" y="261" class="b">byte-identical to apply side</text><text x="674" y="136" class="h">Decision & emission</text><text x="674" y="156" class="b">fold / archive / dead-refs</text><text x="674" y="173.5" class="b">summary text (4 load-bearing</text><text x="674" y="191" class="b">prompt rules, golden-pinned)</text><text x="674" y="208.5" class="b">ref numbering mNNNNN — NEVER</text><text x="674" y="226" class="b">reused (#kernel contract)</text><text x="674" y="243.5" class="b">nudge: flat 50K growth cadence</text><text x="674" y="261" class="b">(#379/#380, no % scaling)</text><text x="984" y="136" class="h">State out</text><text x="984" y="156" class="b">new/updated blocks + refs</text><text x="984" y="173.5" class="b">checkpoint frame (signature)</text><text x="984" y="191" class="b">tokenSnapshot + stats</text><text x="984" y="208.5" class="b">host serializes via mergeState</text><text x="984" y="226" class="b">field list (single source)</text><text x="58" y="448" class="s">Hard invariants (human-gated, Kernel Boundary): zero runtime deps; platform-agnostic core; message-id immutability; lossless round-trip; protected-tool hard exclusion; canonical node order.</text><text x="58" y="474" class="s">Guarded by: golden pins (behavior constants) + two-layer tests (kernel suite + bili e2e) + verif/ SMT solver checks on the decision core (guarded-files.ts).</text></svg>
|
||||
|
After Width: | Height: | Size: 4.1 KiB |
|
After Width: | Height: | Size: 113 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="250" height="220" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="350" y="110" width="250" height="220" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="660" y="110" width="250" height="220" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="3"/><rect x="970" y="110" width="230" height="220" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="294" y1="220" x2="346" y2="220" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="604" y1="220" x2="656" y2="220" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="914" y1="220" x2="966" y2="220" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:压缩内核(kernel/ — acp-kernel,仓内)</text><text x="40" y="70" class="sub">决策核:什么能折、折叠产出什么、状态如何跨重启存活</text><text x="54" y="136" class="h">输入</text><text x="54" y="156" class="b">canonical cores(宿主无关)</text><text x="54" y="173.5" class="b">CompressionState:blocks / refs /</text><text x="54" y="191" class="b">dead_refs / checkpoints / nudge /</text><text x="54" y="208.5" class="b">tokenSnapshot</text><text x="54" y="226" class="b">applyView = applyCompression</text><text x="54" y="243.5" class="b">实际执行的那个数组类(KDD #12)</text><text x="364" y="136" class="h">单元投影</text><text x="364" y="156" class="b">projectUnit —— 唯一的可折叠定义</text><text x="364" y="173.5" class="b">(KDD #12, #3236):边界扩张 →</text><text x="364" y="191" class="b">载体/覆盖/媒体剥离 → 保护区剥离</text><text x="364" y="208.5" class="b">→ turn-integrity → 空判定</text><text x="364" y="226" class="b">致命单元 → 结构化错误</text><text x="364" y="243.5" class="b">与 apply 侧逐字节一致</text><text x="674" y="136" class="h">判定与产出</text><text x="674" y="156" class="b">fold / archive / dead-refs</text><text x="674" y="173.5" class="b">摘要文本(4 条承重提示规则、</text><text x="674" y="191" class="b">金钉锁定)</text><text x="674" y="208.5" class="b">ref 编号 mNNNNN —— 永不复用</text><text x="674" y="226" class="b">(内核契约)</text><text x="674" y="243.5" class="b">nudge:flat 50K 增长节拍</text><text x="674" y="261" class="b">(#379/#380,不按百分比缩放)</text><text x="984" y="136" class="h">状态输出</text><text x="984" y="156" class="b">新/更新块 + refs</text><text x="984" y="173.5" class="b">checkpoint 帧(签名)</text><text x="984" y="191" class="b">tokenSnapshot + stats</text><text x="984" y="208.5" class="b">宿主经 mergeState 字段清单</text><text x="984" y="226" class="b">(单一事实源)序列化</text><text x="58" y="448" class="s">硬不变量(人工闸口,Kernel Boundary):零运行时依赖;平台无关核心;消息 id 不可变;无损往返;受保护工具硬排除;规范节点顺序。</text><text x="58" y="474" class="s">守卫:金钉(行为常数)+ 两层测试(kernel 套件 + bili e2e)+ verif/ 对决策核的 SMT 求解器检查(guarded-files.ts)。</text></svg>
|
||||
|
After Width: | Height: | Size: 4.0 KiB |
|
After Width: | Height: | Size: 117 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="250" height="300" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="350" y="110" width="250" height="300" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="660" y="110" width="250" height="300" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="970" y="110" width="230" height="300" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="294" y1="260" x2="346" y2="260" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="604" y1="260" x2="656" y2="260" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="914" y1="260" x2="966" y2="260" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: host lanes (src/agent + src/server/lane-decisions)</text><text x="40" y="70" class="sub">who carries the request in, how it is attributed, and which processing lane it takes</text><text x="54" y="136" class="h">Host plugins (per-host)</text><text x="54" y="156" class="b">dsh shim (anthropic divert)</text><text x="54" y="173.5" class="b">pi entry-walker (+ omp re-export)</text><text x="54" y="191" class="b">opencode V1/V2 transform hooks</text><text x="54" y="208.5" class="b">codex Responses-over-WebSocket</text><text x="54" y="226" class="b">claude hook (lane token #5095)</text><text x="54" y="243.5" class="b">kimi / zcode native TOML lanes</text><text x="54" y="261" class="b">each: a -native bootstrap gate</text><text x="54" y="278.5" class="b">+ native-intercept fetch routing</text><text x="364" y="136" class="h">Identity & attribution</text><text x="364" y="156" class="b">session id: request header, verbatim</text><text x="364" y="173.5" class="b">per-element host msgid: envelope only,</text><text x="364" y="191" class="b">stripped at ingest (#4491/#5842)</text><text x="364" y="208.5" class="b">persona fingerprint (dsh, evidence</text><text x="364" y="226" class="b">permitlist #1104) → |sub:<fp> fork</text><text x="364" y="243.5" class="b">attribution reports → panel (#3581)</text><text x="364" y="261" class="b">anonymous: prefix-affinity pfa-*</text><text x="364" y="278.5" class="b">(simhash chain #2265)</text><text x="674" y="136" class="h">lane-decisions.ts</text><text x="674" y="156" class="b">single resolver (#3417)</text><text x="674" y="173.5" class="b">request shape × session sticky bind</text><text x="674" y="191" class="b">+ one row: foundation-lane hit</text><text x="674" y="208.5" class="b">(negative+positive pair, #3617)</text><text x="674" y="226" class="b">decides: incremental / v5 / D-lane</text><text x="674" y="243.5" class="b">/ legacy per request</text><text x="984" y="136" class="h">processing lanes</text><text x="984" y="156" class="b">incremental plugin-turn lane</text><text x="984" y="173.5" class="b">(anthropic wire divert)</text><text x="984" y="191" class="b">v5 watermark fastpath (5% cohort)</text><text x="984" y="208.5" class="b">D-lane snapshot render (#3756)</text><text x="984" y="226" class="b">legacy full-resend path</text><text x="984" y="243.5" class="b">(default + safety net)</text><text x="58" y="448" class="s">One request = one lane, decided per request, sticky per session (upgrade-only). Lanes share the kernel and the storage; they differ only in how much of the wire work they skip.</text><text x="58" y="474" class="s">Launcher posture: bili <client> (launcher.ts) auto-proxies both schemes; plugin posture: host loads dist/agent/<entry>.js in-process (default inline for pi, #5428).</text></svg>
|
||||
|
After Width: | Height: | Size: 4.4 KiB |
|
After Width: | Height: | Size: 124 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="250" height="300" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="350" y="110" width="250" height="300" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="660" y="110" width="250" height="300" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="970" y="110" width="230" height="300" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="294" y1="260" x2="346" y2="260" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="604" y1="260" x2="656" y2="260" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="914" y1="260" x2="966" y2="260" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:宿主车道(src/agent + src/server/lane-decisions)</text><text x="40" y="70" class="sub">谁把请求带进来、如何归因、走哪条处理车道</text><text x="54" y="136" class="h">宿主插件(按宿主)</text><text x="54" y="156" class="b">dsh shim(anthropic divert)</text><text x="54" y="173.5" class="b">pi entry-walker(+ omp 复用)</text><text x="54" y="191" class="b">opencode V1/V2 transform 钩子</text><text x="54" y="208.5" class="b">codex Responses-over-WebSocket</text><text x="54" y="226" class="b">claude hook(lane token #5095)</text><text x="54" y="243.5" class="b">kimi / zcode 原生 TOML 车道</text><text x="54" y="261" class="b">每个都有 -native 启动闸门</text><text x="54" y="278.5" class="b">+ native-intercept fetch 路由</text><text x="364" y="136" class="h">身份与归因</text><text x="364" y="156" class="b">session id:请求头、逐字</text><text x="364" y="173.5" class="b">逐元素宿主 msgid:只在信封、</text><text x="364" y="191" class="b">入站即剥(#4491/#5842)</text><text x="364" y="208.5" class="b">persona 指纹(dsh,证据白名单</text><text x="364" y="226" class="b">#1104)→ |sub:<fp> 分叉</text><text x="364" y="243.5" class="b">归因报告 → 面板(#3581)</text><text x="364" y="261" class="b">匿名:前缀亲和 pfa-*</text><text x="364" y="278.5" class="b">(simhash 链 #2265)</text><text x="674" y="136" class="h">lane-decisions.ts</text><text x="674" y="156" class="b">单一裁决器(#3417)</text><text x="674" y="173.5" class="b">请求形状 × 会话粘滞绑定</text><text x="674" y="191" class="b">+ 一行:底座车道命中</text><text x="674" y="208.5" class="b">(正负成对断言 #3617)</text><text x="674" y="226" class="b">逐请求决定:增量 / v5 / D-lane</text><text x="674" y="243.5" class="b">/ legacy</text><text x="984" y="136" class="h">处理车道</text><text x="984" y="156" class="b">增量 plugin-turn 车道</text><text x="984" y="173.5" class="b">(anthropic wire divert)</text><text x="984" y="191" class="b">v5 watermark 快路径(5%灰度)</text><text x="984" y="208.5" class="b">D-lane 快照渲染(#3756)</text><text x="984" y="226" class="b">legacy 全量重发路径</text><text x="984" y="243.5" class="b">(默认 + 兜底安全网)</text><text x="58" y="448" class="s">一个请求 = 一条车道:逐请求裁决、逐会话粘滞(只升不降)。各车道共享内核与存储,差别只在跳过多少 wire 工作。</text><text x="58" y="474" class="s">两种接入姿态:bili <client> 启动器(launcher.ts,自动代理双协议);插件姿态:宿主进程内加载 dist/agent/<entry>.js(pi 默认内联,#5428)。</text></svg>
|
||||
|
After Width: | Height: | Size: 4.3 KiB |
|
After Width: | Height: | Size: 116 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="720" viewBox="0 0 1240 720">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="720" fill="#ffffff"/><rect x="40" y="110" width="220" height="150" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="310" y="110" width="220" height="150" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="580" y="110" width="220" height="150" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="3"/><rect x="850" y="110" width="220" height="150" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="1120" y="110" width="90" height="150" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="40" y="330" width="360" height="120" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="440" y="330" width="360" height="120" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="840" y="330" width="360" height="120" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="40" y="585" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="264" y1="185" x2="306" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="534" y1="185" x2="576" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="804" y1="185" x2="846" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="1074" y1="185" x2="1116" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: request pipeline (src/server + src/loop)</text><text x="40" y="70" class="sub">one HTTP request, from inbound bytes to outbound stream — every wire, both compression modes</text><text x="54" y="136" class="h">Inbound</text><text x="54" y="156" class="b">client bytes</text><text x="54" y="173.5" class="b">marker strip (src/marker/):</text><text x="54" y="191" class="b">ordered pipeline, 4 wires</text><text x="54" y="208.5" class="b">route triage: /__bili/* vs model API</text><text x="324" y="136" class="h">prepare-* (per-wire)</text><text x="324" y="156" class="b">anthropic / openai /</text><text x="324" y="173.5" class="b">responses / google</text><text x="324" y="191" class="b">fold → rebuild → inject</text><text x="324" y="208.5" class="b">system + nudge placement</text><text x="594" y="136" class="h">acp-kernel</text><text x="594" y="156" class="b">(zero changes)</text><text x="594" y="173.5" class="b">fold decision projectUnit</text><text x="594" y="191" class="b">blocks / refs / dead_refs</text><text x="594" y="208.5" class="b">summary + nudge flat 50K</text><text x="864" y="136" class="h">src/loop (unified)</text><text x="864" y="156" class="b">protocol-neutral core</text><text x="864" y="173.5" class="b">4 wire adapters</text><text x="864" y="191" class="b">tool adjudication</text><text x="864" y="208.5" class="b">tag-echo-filter: prose only,</text><text x="864" y="226" class="b">tool args byte-exact</text><text x="1134" y="136" class="h">upstream</text><text x="1134" y="156" class="b"></text><text x="54" y="356" class="h">Preflight & gates</text><text x="54" y="376" class="b">preflight.ts: hold grace, dead-end cooldown</text><text x="54" y="393.5" class="b">reasoning-guard: signed payloads never folded</text><text x="54" y="411" class="b">request-body-budget: receive/decode/send byte caps</text><text x="54" y="428.5" class="b">content-encoding: decompression-bomb guard (413)</text><text x="454" y="356" class="h">Error & recovery</text><text x="454" y="376" class="b">stream-error: minimal SSE error+finish</text><text x="454" y="393.5" class="b">fake-completion: opt-in retry hint</text><text x="454" y="411" class="b">degenerate-turn / degenerate-retry</text><text x="454" y="428.5" class="b">exit-matrix: wire-exit × concerns (#588)</text><text x="854" y="356" class="h">Egress rewrite (stream-*)</text><text x="854" y="376" class="b">SSE per-wire (openai/responses/google)</text><text x="854" y="393.5" class="b">cache-control breakpoints (#1637)</text><text x="854" y="411" class="b">pf-*/envelope headers never leave (hop list)</text><text x="854" y="428.5" class="b">wire-body: trailing-user-turn append</text><text x="58" y="613" class="s">Two compression modes run through the SAME pipeline (KDD #7): plugin lane — agent owns compress, carrier is the tool call; proxy mode — proxy runs compress, carrier is the acp_summary re-voiced as user.</text><text x="58" y="639" class="s">Hard rule: thinking-family blocks are signature-verified, NEVER rewritten (#1960); tool-call arguments are user intent, forwarded byte-exact (#1039).</text></svg>
|
||||
|
After Width: | Height: | Size: 5.2 KiB |
|
After Width: | Height: | Size: 128 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="720" viewBox="0 0 1240 720">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="720" fill="#ffffff"/><rect x="40" y="110" width="220" height="150" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="310" y="110" width="220" height="150" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="580" y="110" width="220" height="150" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="3"/><rect x="850" y="110" width="220" height="150" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="1120" y="110" width="90" height="150" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="40" y="330" width="360" height="120" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="440" y="330" width="360" height="120" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="840" y="330" width="360" height="120" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="1.5"/><rect x="40" y="585" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="264" y1="185" x2="306" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="534" y1="185" x2="576" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="804" y1="185" x2="846" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="1074" y1="185" x2="1116" y2="185" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:请求管道(src/server + src/loop)</text><text x="40" y="70" class="sub">一次 HTTP 请求,从入站字节到出站流 —— 四种 wire、两种压缩模式</text><text x="54" y="136" class="h">入站</text><text x="54" y="156" class="b">客户端字节</text><text x="54" y="173.5" class="b">marker strip(src/marker/):</text><text x="54" y="191" class="b">有序管道、四种 wire</text><text x="54" y="208.5" class="b">路由分诊:/__bili/* 还是模型 API</text><text x="324" y="136" class="h">prepare-*(按 wire)</text><text x="324" y="156" class="b">anthropic / openai /</text><text x="324" y="173.5" class="b">responses / google</text><text x="324" y="191" class="b">折叠 → 重建 → 注入</text><text x="324" y="208.5" class="b">system + nudge 落位</text><text x="594" y="136" class="h">acp-kernel</text><text x="594" y="156" class="b">(零改动)</text><text x="594" y="173.5" class="b">折叠判定 projectUnit</text><text x="594" y="191" class="b">blocks / refs / dead_refs</text><text x="594" y="208.5" class="b">摘要 + nudge flat 50K</text><text x="864" y="136" class="h">src/loop(统一)</text><text x="864" y="156" class="b">协议中立核心</text><text x="864" y="173.5" class="b">4 个 wire 适配器</text><text x="864" y="191" class="b">工具裁决</text><text x="864" y="208.5" class="b">tag-echo-filter:只滤散文、</text><text x="864" y="226" class="b">工具参数逐字节</text><text x="1134" y="136" class="h">上游</text><text x="1134" y="156" class="b"></text><text x="54" y="356" class="h">预检与闸门</text><text x="54" y="376" class="b">preflight.ts:hold 宽限、死路冷却</text><text x="54" y="393.5" class="b">reasoning-guard:签名载荷永不折叠</text><text x="54" y="411" class="b">request-body-budget:收/解/发字节预算</text><text x="54" y="428.5" class="b">content-encoding:解压炸弹守卫(413)</text><text x="454" y="356" class="h">错误与恢复</text><text x="454" y="376" class="b">stream-error:最小 SSE 错误+收尾</text><text x="454" y="393.5" class="b">fake-completion:可选重试提示</text><text x="454" y="411" class="b">degenerate-turn / degenerate-retry</text><text x="454" y="428.5" class="b">exit-matrix:wire 出口 × 关注点(#588)</text><text x="854" y="356" class="h">出站改写(stream-*)</text><text x="854" y="376" class="b">SSE 按 wire(openai/responses/google)</text><text x="854" y="393.5" class="b">cache-control 断点(#1637)</text><text x="854" y="411" class="b">pf-*/信封头永不出代理(hop 白名单)</text><text x="854" y="428.5" class="b">wire-body:尾 user 回合补位</text><text x="58" y="613" class="s">两种压缩模式走同一条管道(KDD #7):plugin 车道——agent 自己压、载体是 tool call;proxy 模式——代理压、载体是 acp_summary 改口为 user。</text><text x="58" y="639" class="s">硬规则:thinking 族块签名验证、永不改写(#1960);tool-call 参数是用户意图,逐字节转发(#1039)。</text></svg>
|
||||
|
After Width: | Height: | Size: 5.1 KiB |
|
After Width: | Height: | Size: 182 KiB |
@@ -0,0 +1,115 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="720" viewBox="0 0 1400 720">
|
||||
<style>
|
||||
text { font-family: sans-serif; }
|
||||
.tt { font-size: 20px; font-weight: 700; fill: #0f172a; }
|
||||
.sub { font-size: 12px; fill: #475569; }
|
||||
.h { font-size: 13px; font-weight: 700; fill: #0f172a; }
|
||||
.b { font-size: 11.5px; fill: #1e293b; }
|
||||
.s { font-size: 10.5px; fill: #475569; }
|
||||
.chip { font-size: 10.5px; fill: #334155; }
|
||||
.warn { font-size: 11.5px; fill: #7f1d1d; font-weight: 700; }
|
||||
.warnb { font-size: 10.5px; fill: #991b1b; }
|
||||
.ok { font-size: 11px; fill: #166534; }
|
||||
</style>
|
||||
<defs>
|
||||
<marker id="ar" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#334155"/></marker>
|
||||
<marker id="arra" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#b91c1c"/></marker>
|
||||
</defs>
|
||||
<rect x="0" y="0" width="1400" height="720" fill="#ffffff"/>
|
||||
<text x="30" y="40" class="tt">Module · Unified storage (src/persist.ts + src/storage/)</text>
|
||||
<text x="30" y="62" class="sub">One SQLite file, one WAL writer — the row-level source of truth; kstate JSON is the parallel second source (pain point 1)</text>
|
||||
|
||||
<!-- writers -->
|
||||
<text x="30" y="100" class="h">Write side (who writes)</text>
|
||||
<rect x="30" y="112" width="300" height="76" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="46" y="136" class="b">src/storage/ingest.ts — unified-view batch writes</text>
|
||||
<text x="46" y="154" class="s">stable absolute seq · content-hash ids (identityOfStoredContent)</text>
|
||||
<text x="46" y="170" class="s">boundary frame boundaryMsgId lands with the batch</text>
|
||||
|
||||
<rect x="30" y="200" width="300" height="66" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="46" y="224" class="b">src/persist.ts — session persistence (StateStore)</text>
|
||||
<text x="46" y="242" class="s">session file save/load · EPERM alert layer persist-eperm</text>
|
||||
|
||||
<rect x="30" y="278" width="300" height="66" rx="8" fill="#dcfce7" stroke="#16a34a"/>
|
||||
<text x="46" y="302" class="b">kernel/ — compression-state writes</text>
|
||||
<text x="46" y="320" class="s">blocks / refs / dead_refs / checkpoints</text>
|
||||
<text x="46" y="336" class="s">(kernel ships the StateStore interface; host swaps the impl)</text>
|
||||
|
||||
<rect x="30" y="356" width="300" height="66" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="46" y="380" class="warn">kstate JSON — hydration field list (parallel source of truth)</text>
|
||||
<text x="46" y="398" class="warnb">surviving CompressionState fields serialized via mergeState()</text>
|
||||
<text x="46" y="414" class="warnb">dual-channel read/write with the tables — the fork point the evolution would remove</text>
|
||||
|
||||
<!-- DB band -->
|
||||
<rect x="430" y="112" width="480" height="310" rx="8" fill="#eef2ff" stroke="#4f46e5"/>
|
||||
<text x="450" y="140" class="h">Unified SQLite · schema v11 (#5539 FK sub-index)</text>
|
||||
<g>
|
||||
<rect x="450" y="156" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="175" class="chip" text-anchor="middle">sessions</text>
|
||||
<rect x="590" y="156" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="175" class="chip" text-anchor="middle">content</text>
|
||||
<rect x="730" y="156" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="175" class="chip" text-anchor="middle">messages (msgId = canonical id)</text>
|
||||
<rect x="450" y="192" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="211" class="chip" text-anchor="middle">blocks</text>
|
||||
<rect x="590" y="192" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="211" class="chip" text-anchor="middle">dead_refs</text>
|
||||
<rect x="730" y="192" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="211" class="chip" text-anchor="middle">refs</text>
|
||||
<rect x="450" y="228" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="247" class="chip" text-anchor="middle">checkpoints</text>
|
||||
<rect x="590" y="228" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="247" class="chip" text-anchor="middle">ccr_entries</text>
|
||||
<rect x="730" y="228" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="247" class="chip" text-anchor="middle">kv_store</text>
|
||||
<rect x="450" y="264" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="283" class="chip" text-anchor="middle">message_media</text>
|
||||
<rect x="590" y="264" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="283" class="chip" text-anchor="middle">conversations</text>
|
||||
<rect x="730" y="264" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="283" class="chip" text-anchor="middle">session_ext</text>
|
||||
</g>
|
||||
<rect x="450" y="308" width="340" height="30" rx="5" fill="#fff" stroke="#6366f1" stroke-dasharray="5 4"/>
|
||||
<text x="620" y="328" class="chip" text-anchor="middle">PF four tables (#5855 open, layers on after merge): pf_rows / pf_log / pf_ckpt / render face</text>
|
||||
<text x="450" y="364" class="s">single file, single WAL writer · migrations = versioned DDL (CREATE IF NOT EXISTS, additive)</text>
|
||||
<text x="450" y="382" class="s">optional at-rest encoding: AES-256-GCM (#708) + zstd (#1080); the mysql dialect is a test mirror (src/storage/mysql.ts)</text>
|
||||
<text x="450" y="400" class="s">integrity: checkpoint frame signatures + S4 per-row checksums (verdicts trust the chain, never content similarity)</text>
|
||||
|
||||
<!-- readers -->
|
||||
<text x="1030" y="100" class="h">Read side (who reads)</text>
|
||||
<rect x="1030" y="112" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="136" class="b">Hydration — src/state-hydration.ts mergeState()</text>
|
||||
<text x="1046" y="154" class="s">single source for surviving fields (tables + kstate assembled)</text>
|
||||
|
||||
<rect x="1030" y="184" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="208" class="b">Egress — fold-reconcile / snapshot-render (#3756)</text>
|
||||
<text x="1046" y="226" class="s">fold-coverage check + server-side canonical render (any desync falls back to legacy for the whole turn)</text>
|
||||
|
||||
<rect x="1030" y="256" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="280" class="b">Billing & cache ledger — cache-ledger / billing</text>
|
||||
<text x="1046" y="298" class="s">per-round token/USD accounting · CCR content retrieval store.ts</text>
|
||||
|
||||
<rect x="1030" y="328" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="352" class="b">Display & export — sessions-data / acp_status / export</text>
|
||||
<text x="1046" y="370" class="s">web panel session tree · status surface · session export (honest output #155)</text>
|
||||
|
||||
<rect x="1030" y="400" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="424" class="b">Maintenance — state-gc / storage-maintenance / orphan-gc</text>
|
||||
<text x="1046" y="442" class="s">orphan-block GC · storage GC (sessions.gc.*, opt-in) · dead-ref reclaim</text>
|
||||
|
||||
<!-- bottom invariants -->
|
||||
<rect x="30" y="492" width="1340" height="118" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
|
||||
<text x="50" y="520" class="h">Hard invariants (read AGENTS.md before touching this)</text>
|
||||
<text x="50" y="546" class="b">· message ids are never reused (kernel contract): messages.msgId is the bili/kernel canonical id — the host msgid still has no landing spot (pain point 2; #5842 only covers in-flight)</text>
|
||||
<text x="50" y="570" class="b">· stable absolute seq (#421 fix): row order is the primary identity carrier; folding = an inactive mark, never a physical delete (GC purges by cover-block lifecycle)</text>
|
||||
<text x="50" y="594" class="b">· upgrades are purely additive: schema version only moves forward, old DBs land via CREATE IF NOT EXISTS — any breaking migration needs a rollback drill first (T1 discipline)</text>
|
||||
|
||||
<!-- arrows -->
|
||||
<g stroke="#334155" fill="none" stroke-width="1.6">
|
||||
<path d="M330,150 H430" marker-end="url(#ar)"/>
|
||||
<path d="M330,233 H430" marker-end="url(#ar)"/>
|
||||
<path d="M330,311 H430" marker-end="url(#ar)"/>
|
||||
<path d="M430,505 H1030"/>
|
||||
<path d="M1030,142 H1000"/>
|
||||
<path d="M1000,142 V430"/>
|
||||
<path d="M1000,142 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,214 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,286 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,358 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,430 H1030" marker-end="url(#ar)"/>
|
||||
</g>
|
||||
<g stroke="#b91c1c" fill="none" stroke-width="1.4" stroke-dasharray="5 4">
|
||||
<path d="M330,389 H430" marker-end="url(#arra)"/>
|
||||
</g>
|
||||
<text x="352" y="380" class="warnb">dual channel</text>
|
||||
|
||||
<text x="30" y="660" class="s">Key entries: src/storage/schema.ts (the single DDL source of truth) · src/storage/store.ts (row read/write) · src/storage/ingest.ts (batch entry) · src/persist.ts (StateStore wrapper) · src/state-hydration.ts (field list)</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 9.0 KiB |
|
After Width: | Height: | Size: 207 KiB |
@@ -0,0 +1,115 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="720" viewBox="0 0 1400 720">
|
||||
<style>
|
||||
text { font-family: 'Noto Sans CJK SC','Droid Sans Fallback',sans-serif; }
|
||||
.tt { font-size: 20px; font-weight: 700; fill: #0f172a; }
|
||||
.sub { font-size: 12px; fill: #475569; }
|
||||
.h { font-size: 13px; font-weight: 700; fill: #0f172a; }
|
||||
.b { font-size: 11.5px; fill: #1e293b; }
|
||||
.s { font-size: 10.5px; fill: #475569; }
|
||||
.chip { font-size: 10.5px; fill: #334155; }
|
||||
.warn { font-size: 11.5px; fill: #7f1d1d; font-weight: 700; }
|
||||
.warnb { font-size: 10.5px; fill: #991b1b; }
|
||||
.ok { font-size: 11px; fill: #166534; }
|
||||
</style>
|
||||
<defs>
|
||||
<marker id="ar" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#334155"/></marker>
|
||||
<marker id="arra" markerWidth="10" markerHeight="8" refX="9" refY="3" orient="auto"><path d="M0,0 L9,3 L0,6 Z" fill="#b91c1c"/></marker>
|
||||
</defs>
|
||||
<rect x="0" y="0" width="1400" height="720" fill="#ffffff"/>
|
||||
<text x="30" y="40" class="tt">模块 · 统一存储(src/persist.ts + src/storage/)</text>
|
||||
<text x="30" y="62" class="sub">单一 SQLite 文件、单一 WAL 写者 —— 行级真源;kstate JSON 是与它并行的第二真源(痛点①)</text>
|
||||
|
||||
<!-- writers -->
|
||||
<text x="30" y="100" class="h">写入侧(谁在写)</text>
|
||||
<rect x="30" y="112" width="300" height="76" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="46" y="136" class="b">src/storage/ingest.ts — 统一视图批量写</text>
|
||||
<text x="46" y="154" class="s">稳定绝对 seq · 内容哈希 id(identityOfStoredContent)</text>
|
||||
<text x="46" y="170" class="s">边界帧 boundaryMsgId 随批落表</text>
|
||||
|
||||
<rect x="30" y="200" width="300" height="66" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="46" y="224" class="b">src/persist.ts — 会话持久化(StateStore)</text>
|
||||
<text x="46" y="242" class="s">会话文件落盘 / 加载 · EPERM 告警层 persist-eperm</text>
|
||||
|
||||
<rect x="30" y="278" width="300" height="66" rx="8" fill="#dcfce7" stroke="#16a34a"/>
|
||||
<text x="46" y="302" class="b">kernel/ — 压缩状态写入</text>
|
||||
<text x="46" y="320" class="s">blocks / refs / dead_refs / checkpoints</text>
|
||||
<text x="46" y="336" class="s">(kernel 自带 StateStore 接口,host 换实现)</text>
|
||||
|
||||
<rect x="30" y="356" width="300" height="66" rx="8" fill="#fee2e2" stroke="#ef4444"/>
|
||||
<text x="46" y="380" class="warn">kstate JSON — hydration 字段清单(平行真源)</text>
|
||||
<text x="46" y="398" class="warnb">CompressionState 存活字段经 mergeState() 序列化</text>
|
||||
<text x="46" y="414" class="warnb">与表双通道读写 —— 分叉点,演进提案要消除</text>
|
||||
|
||||
<!-- DB band -->
|
||||
<rect x="430" y="112" width="480" height="310" rx="8" fill="#eef2ff" stroke="#4f46e5"/>
|
||||
<text x="450" y="140" class="h">统一 SQLite · schema v11(#5539 FK 子索引)</text>
|
||||
<g>
|
||||
<rect x="450" y="156" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="175" class="chip" text-anchor="middle">sessions</text>
|
||||
<rect x="590" y="156" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="175" class="chip" text-anchor="middle">content</text>
|
||||
<rect x="730" y="156" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="175" class="chip" text-anchor="middle">messages(msgId=规范id)</text>
|
||||
<rect x="450" y="192" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="211" class="chip" text-anchor="middle">blocks</text>
|
||||
<rect x="590" y="192" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="211" class="chip" text-anchor="middle">dead_refs</text>
|
||||
<rect x="730" y="192" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="211" class="chip" text-anchor="middle">refs</text>
|
||||
<rect x="450" y="228" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="247" class="chip" text-anchor="middle">checkpoints</text>
|
||||
<rect x="590" y="228" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="247" class="chip" text-anchor="middle">ccr_entries</text>
|
||||
<rect x="730" y="228" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="247" class="chip" text-anchor="middle">kv_store</text>
|
||||
<rect x="450" y="264" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="515" y="283" class="chip" text-anchor="middle">message_media</text>
|
||||
<rect x="590" y="264" width="130" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="655" y="283" class="chip" text-anchor="middle">conversations</text>
|
||||
<rect x="730" y="264" width="160" height="28" rx="5" fill="#e0e7ff" stroke="#6366f1"/><text x="810" y="283" class="chip" text-anchor="middle">session_ext</text>
|
||||
</g>
|
||||
<rect x="450" y="308" width="340" height="30" rx="5" fill="#fff" stroke="#6366f1" stroke-dasharray="5 4"/>
|
||||
<text x="620" y="328" class="chip" text-anchor="middle">PF 四表(#5855 open,待合入后叠加):pf_rows / pf_log / pf_ckpt / render 面</text>
|
||||
<text x="450" y="364" class="s">单文件单 WAL 写者 · 迁移=版本化 DDL(CREATE IF NOT EXISTS 纯加性)</text>
|
||||
<text x="450" y="382" class="s">可选加密:AES-256-GCM(#708)+ zstd(#1080);mysql 方言为测试镜像(src/storage/mysql.ts)</text>
|
||||
<text x="450" y="400" class="s">完整性:checkpoint 帧签名 + S4 逐行校验和(判决只认链,不认内容相似)</text>
|
||||
|
||||
<!-- readers -->
|
||||
<text x="1030" y="100" class="h">消费侧(谁在读)</text>
|
||||
<rect x="1030" y="112" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="136" class="b">水合 — src/state-hydration.ts mergeState()</text>
|
||||
<text x="1046" y="154" class="s">CompressionState 存活字段单一事实源(表 + kstate 拼装)</text>
|
||||
|
||||
<rect x="1030" y="184" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="208" class="b">出站 — fold-reconcile / snapshot-render(#3756)</text>
|
||||
<text x="1046" y="226" class="s">折叠覆盖核对 + 服务端正史渲染(失步整轮回落 legacy)</text>
|
||||
|
||||
<rect x="1030" y="256" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="280" class="b">计费与缓存账 — cache-ledger / billing</text>
|
||||
<text x="1046" y="298" class="s">每轮 token/USD 记账 · CCR 内容取回 store.ts</text>
|
||||
|
||||
<rect x="1030" y="328" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="352" class="b">展示与导出 — sessions-data / acp_status / export</text>
|
||||
<text x="1046" y="370" class="s">Web 面板会话树 · 状态面 · 会话导出(诚实输出 #155)</text>
|
||||
|
||||
<rect x="1030" y="400" width="340" height="60" rx="8" fill="#f3f4f6" stroke="#9ca3af"/>
|
||||
<text x="1046" y="424" class="b">维护 — state-gc / storage-maintenance / orphan-gc</text>
|
||||
<text x="1046" y="442" class="s">孤儿块 GC · 存储 GC(sessions.gc.* 可选)· 死 ref 回收</text>
|
||||
|
||||
<!-- bottom invariants -->
|
||||
<rect x="30" y="492" width="1340" height="118" rx="8" fill="#f8fafc" stroke="#cbd5e1"/>
|
||||
<text x="50" y="520" class="h">硬不变量(改这里前先读 AGENTS.md)</text>
|
||||
<text x="50" y="546" class="b">· 消息 id 永不复用(kernel 契约):messages.msgId 是 bili/内核规范 id —— 宿主 msgid 至今没有落点(痛点②,#5842 只解 in-flight)</text>
|
||||
<text x="50" y="570" class="b">· 稳定绝对 seq(#421 修复):行序即身份主载体;折叠=inactive 标记,不物理删(物理清由 GC 按覆盖块生命周期做)</text>
|
||||
<text x="50" y="594" class="b">· 升级纯加性:schema 版本只进不退,老库 CREATE IF NOT EXISTS 到位 —— 任何破坏性迁移必须先有回滚演练(T1 纪律)</text>
|
||||
|
||||
<!-- arrows -->
|
||||
<g stroke="#334155" fill="none" stroke-width="1.6">
|
||||
<path d="M330,150 H430" marker-end="url(#ar)"/>
|
||||
<path d="M330,233 H430" marker-end="url(#ar)"/>
|
||||
<path d="M330,311 H430" marker-end="url(#ar)"/>
|
||||
<path d="M430,505 H1030"/>
|
||||
<path d="M1030,142 H1000"/>
|
||||
<path d="M1000,142 V430"/>
|
||||
<path d="M1000,142 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,214 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,286 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,358 H1030" marker-end="url(#ar)"/>
|
||||
<path d="M1000,430 H1030" marker-end="url(#ar)"/>
|
||||
</g>
|
||||
<g stroke="#b91c1c" fill="none" stroke-width="1.4" stroke-dasharray="5 4">
|
||||
<path d="M330,389 H430" marker-end="url(#arra)"/>
|
||||
</g>
|
||||
<text x="352" y="380" class="warnb">kstate 双通道</text>
|
||||
|
||||
<text x="30" y="660" class="s">关键入口:src/storage/schema.ts(DDL 唯一事实源)· src/storage/store.ts(行读写)· src/storage/ingest.ts(批量入口)· src/persist.ts(StateStore 包装)· src/state-hydration.ts(字段清单)</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 8.8 KiB |
|
After Width: | Height: | Size: 144 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="260" height="250" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="360" y="110" width="260" height="250" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="680" y="110" width="260" height="250" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="990" y="110" width="210" height="250" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="304" y1="235" x2="356" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="624" y1="235" x2="676" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="944" y1="235" x2="986" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: self-update & install lanes (src/update.ts + lane modules)</text><text x="40" y="70" class="sub">how a copy of bili gets to the newest version without bricking anything</text><text x="54" y="136" class="h">Self-updater (update.ts)</text><text x="54" y="156" class="b">npm registry check, 3-min cadence</text><text x="54" y="173.5" class="b">(knob-overridable #2030); first</text><text x="54" y="191" class="b">check per process ignores throttle</text><text x="54" y="208.5" class="b">tarball extraction, NOT npm install</text><text x="54" y="226" class="b">(no lifecycle scripts on user boxes)</text><text x="54" y="243.5" class="b">in-place swap for the global install</text><text x="54" y="261" class="b">load-bearing: a broken updater bricks</text><text x="54" y="278.5" class="b">every future upgrade → NO-OP release</text><text x="54" y="296" class="b">validation protocol before any change</text><text x="374" y="136" class="h">Install lanes (#991/#1196)</text><text x="374" y="156" class="b">one writer per copy, chosen by</text><text x="374" y="173.5" class="b">install SOURCE</text><text x="374" y="191" class="b">global (npm -g): self-updates in</text><text x="374" y="208.5" class="b">place</text><text x="374" y="226" class="b">reference lanes (omp/claude/codex/</text><text x="374" y="243.5" class="b">kimi/zcode/hermes): point at global</text><text x="374" y="261" class="b">dist, no copy</text><text x="374" y="278.5" class="b">host worlds (dsh bundle, opencode/</text><text x="374" y="296" class="b">pi tree): updated through the HOST's</text><text x="374" y="313.5" class="b">channel, driven by global self-update</text><text x="374" y="331" class="b">+ the copy's own periodic check</text><text x="694" y="136" class="h">Ledger convergence</text><text x="694" y="156" class="b">dsh-ledger.ts: copy + manifest spec</text><text x="694" y="173.5" class="b">+ lockfile record move TOGETHER</text><text x="694" y="191" class="b">(#3496 convergeDshLedger)</text><text x="694" y="208.5" class="b">drift pre-exists ⇒ explicit demand</text><text x="694" y="226" class="b">only (bili doctor --fix)</text><text x="694" y="243.5" class="b">plugin-install.ts: drives the host's</text><text x="694" y="261" class="b">OWN channel (dsh plugin add), never</text><text x="694" y="278.5" class="b">installs a second copy beside it</text><text x="694" y="296" class="b">(#966/#991)</text><text x="1004" y="136" class="h">Advisory & restart</text><text x="1004" y="156" class="b">advisory.ts: critical-defect watcher</text><text x="1004" y="173.5" class="b">(#1481) — advisory, human acts</text><text x="1004" y="191" class="b">update-notes.ts: tiered release-notes</text><text x="1004" y="208.5" class="b">(#1870 severe-only default)</text><text x="1004" y="226" class="b">restart.ts: opt-in self-restart once</text><text x="1004" y="243.5" class="b">newer code is on disk (#811)</text><text x="1004" y="261" class="b">plugin mode: code runs in the HOST</text><text x="1004" y="278.5" class="b">process → host restart needed; broken</text><text x="1004" y="296" class="b">injection is visible (#3581)</text><text x="58" y="448" class="s">Transient drift is acceptable and bounded (converge within one check cycle + host restart); permanent divergence is a bug. Local pins (link:/file:) are never refreshed by design.</text><text x="58" y="474" class="s">Security: the updater is in the human-review tier (§7.4) — it is the one module whose bug converts every future release into an outage.</text></svg>
|
||||
|
After Width: | Height: | Size: 5.1 KiB |
|
After Width: | Height: | Size: 147 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="260" height="250" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="360" y="110" width="260" height="250" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="680" y="110" width="260" height="250" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="990" y="110" width="210" height="250" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="304" y1="235" x2="356" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="624" y1="235" x2="676" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="944" y1="235" x2="986" y2="235" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:自更新与安装车道(src/update.ts + 车道模块)</text><text x="40" y="70" class="sub">一份 bili 如何安全地拿到最新版本 —— 不炸任何机器</text><text x="54" y="136" class="h">自更新器(update.ts)</text><text x="54" y="156" class="b">npm 注册表检查、3 分钟节拍(可旋钮</text><text x="54" y="173.5" class="b">覆盖 #2030);每进程首查忽略节流</text><text x="54" y="191" class="b">tarball 解包,不是 npm install(用户</text><text x="54" y="208.5" class="b">机器上不跑 lifecycle 脚本)</text><text x="54" y="226" class="b">全局安装就地换包</text><text x="54" y="243.5" class="b">承重件:更新器坏 = 以后每次升级都</text><text x="54" y="261" class="b">砖 → 任何改动前先 NO-OP 发版验证</text><text x="374" y="136" class="h">安装车道(#991/#1196)</text><text x="374" y="156" class="b">每份拷贝一个写者,由安装来源定</text><text x="374" y="173.5" class="b">全局(npm -g):就地自更新</text><text x="374" y="191" class="b">引用车道(omp/claude/codex/kimi/</text><text x="374" y="208.5" class="b">zcode/hermes):指全局 dist、无拷贝</text><text x="374" y="226" class="b">宿主世界(dsh bundle、opencode/pi</text><text x="374" y="243.5" class="b">树):走宿主自己的通道更新 —— 全局自</text><text x="374" y="261" class="b">更新驱动 + 拷贝自己的周期检查兜底</text><text x="694" y="136" class="h">三账收敛</text><text x="694" y="156" class="b">dsh-ledger.ts:拷贝 + manifest 声明</text><text x="694" y="173.5" class="b">+ lockfile 记录一起动(#3496</text><text x="694" y="191" class="b">convergeDshLedger)</text><text x="694" y="208.5" class="b">既有漂移只在显式要求时收敛(bili</text><text x="694" y="226" class="b">doctor --fix)</text><text x="694" y="243.5" class="b">plugin-install.ts:只驱动宿主自己的</text><text x="694" y="261" class="b">通道(dsh plugin add),绝不在旁边</text><text x="694" y="278.5" class="b">装第二份(#966/#991)</text><text x="1004" y="136" class="h">通告与重启</text><text x="1004" y="156" class="b">advisory.ts:严重缺陷观察者(#1481)——</text><text x="1004" y="173.5" class="b">只通告、人来处置</text><text x="1004" y="191" class="b">update-notes.ts:分级 release-notes</text><text x="1004" y="208.5" class="b">(#1870 默认只 severe)</text><text x="1004" y="226" class="b">restart.ts:新代码落盘后可选自重启</text><text x="1004" y="243.5" class="b">(#811)</text><text x="1004" y="261" class="b">插件模式:代码跑在宿主进程里 → 需要</text><text x="1004" y="278.5" class="b">宿主重启;注入坏掉要可见(#3581)</text><text x="58" y="448" class="s">瞬态漂移可接受且有界(一个检查周期 + 宿主重启内收敛);永久分叉是 bug。本地 pin(link:/file:)按设计永不自动刷新。</text><text x="58" y="474" class="s">安全面:更新器在人工评审档(§7.4)—— 它是唯一「自己的 bug 会把以后每次发版变成事故」的模块。</text></svg>
|
||||
|
After Width: | Height: | Size: 4.7 KiB |
|
After Width: | Height: | Size: 122 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="250" height="230" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="350" y="110" width="250" height="230" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="660" y="110" width="250" height="230" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="970" y="110" width="230" height="230" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="294" y1="225" x2="346" y2="225" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="604" y1="225" x2="656" y2="225" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="914" y1="225" x2="966" y2="225" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">Module: web panel & admin surface (src/web + src/server/admin.ts)</text><text x="40" y="70" class="sub">the human-facing side: what you can see, where the data comes from, and the notice pipeline</text><text x="54" y="136" class="h">Admin routes</text><text x="54" y="156" class="b">/__bili/* + /__acp/* (admin.ts)</text><text x="54" y="173.5" class="b">loopback + trusted-origin gated</text><text x="54" y="191" class="b">(#1440)</text><text x="54" y="208.5" class="b">status / overview / sessions /</text><text x="54" y="226" class="b">detail / logs / config / plugin /</text><text x="54" y="243.5" class="b">watcher / upstream</text><text x="54" y="261" class="b">/__bili/status attribution field</text><text x="54" y="278.5" class="b">shows broken-injection state (#3581)</text><text x="364" y="136" class="h">Data sources</text><text x="364" y="156" class="b">session pool (live) + storage rows</text><text x="364" y="173.5" class="b">(sessions-data, tier tree #3917)</text><text x="364" y="191" class="b">acp_status: ranges/nudge recomputed</text><text x="364" y="208.5" class="b">LIVE per render (acp-status.ts)</text><text x="364" y="226" class="b">cache ledger (cache-ledger.ts, #1536)</text><text x="364" y="243.5" class="b">billing: USD prices, payback view</text><text x="364" y="261" class="b">(#4899)</text><text x="364" y="278.5" class="b">notice store (kv_store namespace)</text><text x="674" y="136" class="h">Render</text><text x="674" y="156" class="b">server-rendered HTML shell (page.ts)</text><text x="674" y="173.5" class="b">client.ts JS bundle + styles.ts</text><text x="674" y="191" class="b">i18n.ts: zh-CN/en message tables</text><text x="674" y="208.5" class="b">(dead-key guarded by test)</text><text x="674" y="226" class="b">markdown.ts escape-safe</text><text x="674" y="243.5" class="b">report.ts: dependency-free MD+SVG</text><text x="674" y="261" class="b">session reports</text><text x="674" y="278.5" class="b">diagnostics.ts: paste-ready blob</text><text x="674" y="296" class="b">(#3040)</text><text x="984" y="136" class="h">Notices (one channel)</text><text x="984" y="156" class="b">mergedNotices(): one loop</text><text x="984" y="173.5" class="b">S builtin / A remote feed (this</text><text x="984" y="191" class="b">repo announcements/remote.json,</text><text x="984" y="208.5" class="b">~3-min poll, fail-open) / B local</text><text x="984" y="226" class="b">files; equal ids shadow B>A>S</text><text x="984" y="243.5" class="b">(#5548)</text><text x="984" y="261" class="b">dismiss receipts in unified storage</text><text x="984" y="278.5" class="b">(kv_store namespace notices)</text><text x="58" y="448" class="s">The panel never lies: empty-block sessions export nothing, storage degradation is surfaced (runtime-status), and every data row links back to the storage module as the single source of truth.</text><text x="58" y="474" class="s">Update actions live in the panel too (update-actions.ts #3719) over the self-updater — the update module owns the mechanics, this module owns the surface.</text></svg>
|
||||
|
After Width: | Height: | Size: 4.6 KiB |
|
After Width: | Height: | Size: 129 KiB |
@@ -0,0 +1,5 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="1240" height="560" viewBox="0 0 1240 560">
|
||||
<style>text{font-family:'Noto Sans CJK SC','Droid Sans Fallback',sans-serif;}.tt{font-size:24px;font-weight:700;fill:#0f172a;}.sub{font-size:13px;fill:#475569;}.h{font-size:14px;font-weight:700;fill:#0f172a;}.b{font-size:12px;fill:#334155;}.s{font-size:11px;fill:#64748b;}.leg{font-size:11.5px;fill:#475569;}.warn{font-size:12px;fill:#b91c1c;}.num{font-size:11px;font-weight:700;fill:#fff;}</style>
|
||||
<defs><marker id="ar" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#475569"/></marker>
|
||||
<marker id="argr" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L7,3 L0,6 z" fill="#059669"/></marker></defs>
|
||||
<rect width="1240" height="560" fill="#ffffff"/><rect x="40" y="110" width="250" height="230" rx="8" fill="#f8fafc" stroke="#94a3b8" stroke-width="2"/><rect x="350" y="110" width="250" height="230" rx="8" fill="#eff6ff" stroke="#3b82f6" stroke-width="2"/><rect x="660" y="110" width="250" height="230" rx="8" fill="#dcfce7" stroke="#16a34a" stroke-width="2"/><rect x="970" y="110" width="230" height="230" rx="8" fill="#fef3c7" stroke="#d97706" stroke-width="2"/><rect x="40" y="420" width="1160" height="78" rx="8" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.2"/><line x1="294" y1="225" x2="346" y2="225" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="604" y1="225" x2="656" y2="225" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><line x1="914" y1="225" x2="966" y2="225" stroke="#475569" stroke-width="1.6" marker-end="url(#ar)"/><text x="40" y="44" class="tt">模块:Web 面板与 admin 面(src/web + src/server/admin.ts)</text><text x="40" y="70" class="sub">人这一侧:能看到什么、数据从哪来、通告管线怎么走</text><text x="54" y="136" class="h">admin 路由</text><text x="54" y="156" class="b">/__bili/* + /__acp/*(admin.ts)</text><text x="54" y="173.5" class="b">loopback + 受信源门控(#1440)</text><text x="54" y="191" class="b">status / overview / sessions /</text><text x="54" y="208.5" class="b">detail / logs / config / plugin /</text><text x="54" y="226" class="b">watcher / upstream</text><text x="54" y="243.5" class="b">/__bili/status 的 attribution 字段</text><text x="54" y="261" class="b">暴露注入坏状态(#3581)</text><text x="364" y="136" class="h">数据源</text><text x="364" y="156" class="b">会话池(活)+ 存储行(sessions-</text><text x="364" y="173.5" class="b">data,层树 #3917)</text><text x="364" y="191" class="b">acp_status:ranges/nudge 每次渲染</text><text x="364" y="208.5" class="b">现算(acp-status.ts)</text><text x="364" y="226" class="b">缓存账本(cache-ledger.ts,#1536)</text><text x="364" y="243.5" class="b">计费:USD 价格、回本视图(#4899)</text><text x="364" y="261" class="b">通告存储(kv_store namespace)</text><text x="674" y="136" class="h">渲染</text><text x="674" y="156" class="b">服务端渲染 HTML 壳(page.ts)</text><text x="674" y="173.5" class="b">client.ts JS 包 + styles.ts</text><text x="674" y="191" class="b">i18n.ts:zh-CN/en 文案表(死键</text><text x="674" y="208.5" class="b">有测试守卫)</text><text x="674" y="226" class="b">markdown.ts 转义安全</text><text x="674" y="243.5" class="b">report.ts:零依赖 MD+SVG 会话</text><text x="674" y="261" class="b">报告</text><text x="674" y="278.5" class="b">diagnostics.ts:可粘贴诊断块(#3040)</text><text x="984" y="136" class="h">通告(单一通道)</text><text x="984" y="156" class="b">mergedNotices():一个循环</text><text x="984" y="173.5" class="b">S 内置 / A 远端 feed(本仓</text><text x="984" y="191" class="b">announcements/remote.json,~3 分钟</text><text x="984" y="208.5" class="b">轮询、fail-open)/ B 本地文件;</text><text x="984" y="226" class="b">同 id 影子 B>A>S (#5548)</text><text x="984" y="243.5" class="b">关闭回执在统一存储(kv_store</text><text x="984" y="261" class="b">namespace notices)</text><text x="58" y="448" class="s">面板不说谎:空块会话不导「原始对话」、存储降级要可见(runtime-status)、每行数据都能指回存储模块这个唯一真源。</text><text x="58" y="474" class="s">更新动作也在面板里(update-actions.ts #3719)叠在自更新器之上 —— 机制归 update 模块、界面归本模块。</text></svg>
|
||||
|
After Width: | Height: | Size: 4.4 KiB |
@@ -0,0 +1,40 @@
|
||||
# Module: fastpaths (incremental lane / v5 watermark / D-lane / legacy)
|
||||
|
||||
> Part of the [architecture hub](../architecture.md) · 中文: [fastpaths.zh-CN.md](./fastpaths.zh-CN.md) · as of 2026-11-08, master
|
||||
|
||||

|
||||
(bitmap fallback: [fastpaths.en.png](./assets/fastpaths.en.png))
|
||||
|
||||
## Responsibility
|
||||
|
||||
Plugin hosts (dsh threads, pi, opencode, …) re-send the FULL history every turn. This module is the family of mechanisms that skip re-doing the wire work on those turns — parsing, canonical conversion, snapshot pinning — while staying byte-identical to doing it for real. One request always takes exactly one path; the paths are mutually exclusive by construction (shape gate + sticky binding).
|
||||
|
||||
## Principles
|
||||
|
||||
- **Hit or full legacy — nothing in between.** Any doubt (bad/stale stamp, shape mismatch, desync, breaker) sends the WHOLE turn down the untouched legacy path, which re-stamps truth so the client converges in one turn.
|
||||
- **Degrade, never guess.** A missed verification is a cost, not a license to trust the fast result (availability over performance, #3128).
|
||||
- **The fast lane is an optimization of one request, not a new protocol.** pf-*/envelope headers are protocol headers: stripped before upstream (`UPSTREAM_HOP_HEADERS`), never visible to the model endpoint.
|
||||
|
||||
## How it works
|
||||
|
||||
**The turn shape.** Each successful response stamps `x-bili-pf-seq` = message count (measured by `fastpath-scan.ts`, a zero-allocation structural scan — no JSON.parse). The client echoes it back as `x-bili-pf-count`, plus `x-bili-pf-tail-ids` (host msgids since the last anchor, #4491's per-element screening). Plugin-turn turns additionally carry the `x-bili-plugin-turn` envelope (#3248). The shape gate picks the lane: anthropic wire → incremental divert; openai shapes → watermark lane (#3433).
|
||||
|
||||
**① Incremental plugin-turn lane** (`threads-lane.ts`, #3248): diff + ack + resync over the host msgids; only the delta is parsed. Serves the anthropic-wire divert turns.
|
||||
|
||||
**② v5 watermark fastpath** (`fastpath.ts`, #5403/#5418, rollout ~5% cohort): on a verified hit the pipeline input becomes "previous turn's canonical cores (module-level WeakMap) + fresh parse of the tail window [K..T) only" — the full parse, full conversion, and the `lastMessages` pin are skipped (the #5403 OOM producer). Verdict ladder: count from the server ledger when a qualified tail-ids list rides along (v4), otherwise the old stamp ladder; 5 consecutive PROVEN misses trip a breaker held for one hour (scanning/stamping continues during hold to teach truth back).
|
||||
|
||||
**③ D-lane snapshot render** (`snapshot-render.ts`, #3756): the outbound prefix is rendered from the server transcript rows (row seq = message identity); the tail stays client-verbatim. Any desync → whole turn legacy.
|
||||
|
||||
**Legacy full-resend.** The untouched full-parse path — default for every shape, the fallback safety net for all three fast lanes. It re-stamps truth headers on the response, so a missed turn self-heals in one round.
|
||||
|
||||
## What a hit skips / honest boundaries
|
||||
|
||||
Skips: whole-body `JSON.parse` + `openaiToCore` (v5); `snapshotMessages` prefix re-pin (v5); delta-only parsing (incremental); prefix re-render from rows (D-lane). Honest boundaries: byte-rewrites that KEEP the element count are undetectable (that trust-model change is human-review tier, KDD §7.4); once a multimodal tail enters the cache, that history stays on legacy turns (KDD #15 ②); marker-strip counts are inherited from the seed ledger (mid-history is never re-scanned).
|
||||
|
||||
## Key entries
|
||||
|
||||
`src/server/fastpath.ts` · `src/server/fastpath-scan.ts` (structural scanner) · `src/server/threads-lane.ts` (incremental) · `src/server/snapshot-render.ts` (D-lane) · `src/agent/pf-channel.ts` (client state machine) · `src/agent/incremental-client.ts` · `src/server/lane-decisions.ts` (routing)
|
||||
|
||||
## Related
|
||||
|
||||
[lanes](./lanes.md) · [pipeline](./pipeline.md) · [identity](./identity.md) · [#5643 evolution: all four converge onto the snapshot-table foundation](https://github.com/ranxianglei/billion-context/issues/5643) · `tests/issue5403-watermark-fastpath.test.ts`
|
||||
@@ -0,0 +1,40 @@
|
||||
# 模块:快路径(增量车道 / v5 水位 / D-lane / legacy)
|
||||
|
||||
> [架构总览](../architecture.zh-CN.md) 的一个模块 · English: [fastpaths.md](./fastpaths.md) · 截至 2026-11-08,master
|
||||
|
||||

|
||||
(位图备选:[fastpaths.zh-CN.png](./assets/fastpaths.zh-CN.png))
|
||||
|
||||
## 职责
|
||||
|
||||
插件宿主(dsh threads、pi、opencode……)每轮把完整历史重发一次。这个模块是一族机制,专治这些回合上重复的 wire 工作——解析、规范转换、快照钉存——同时保证与真做一遍**逐字节一致**。一个请求恒走其中一条路;各路径按构造互斥(形状门 + 粘滞绑定)。
|
||||
|
||||
## 基本原理
|
||||
|
||||
- **要么命中、要么完整 legacy——没有中间态。** 任何疑点(坏戳/旧戳、形状不符、失步、熔断)整轮走原封未动的 legacy 路径;legacy 重新盖真值头,客户端一轮收敛。
|
||||
- **降级不猜。** 一次验证未过是成本,不是信任快结果的许可证(可用性大于性能,#3128)。
|
||||
- **快车道是一个请求的优化,不是新协议。** pf-*/信封头是协议头:出代理前剥掉(`UPSTREAM_HOP_HEADERS`),模型端点永远看不到。
|
||||
|
||||
## 工作机制
|
||||
|
||||
**回合形状。** 每个成功响应盖 `x-bili-pf-seq` = messages 元素数(由 `fastpath-scan.ts` 的零分配结构扫描测出——不 JSON.parse)。客户端下一轮回带 `x-bili-pf-count`,外加 `x-bili-pf-tail-ids`(上次锚点以来的宿主 msgid,#4491 同一套逐元素筛查)。plugin-turn 回合另带 `x-bili-plugin-turn` 信封(#3248)。形状门选车道:anthropic wire → 增量 divert;openai 形 → 水位车道(#3433)。
|
||||
|
||||
**① 增量 plugin-turn 车道**(`threads-lane.ts`,#3248):基于宿主 msgid 的 diff + ack + resync;只解析差量。服务 anthropic-wire divert 回合。
|
||||
|
||||
**② v5 水位快路径**(`fastpath.ts`,#5403/#5418,rollout ~5% 灰度):验证命中后,管道输入变成「上一轮 canonical cores(模块级 WeakMap)+ 仅尾窗 [K..T) 新解析」——整包解析、全量转换、`lastMessages` 钉存全跳过(#5403 的 OOM 生产者)。判决阶梯:带合格 tail-ids 列表时 K 取自服务端账本(v4),否则旧盖戳阶梯;连续 5 次**可证实** miss 触发熔断、持有一小时(持有期间继续扫描盖戳,把真值教回客户端)。
|
||||
|
||||
**③ D-lane 快照渲染**(`snapshot-render.ts`,#3756):出站前缀由服务端正史行渲染(行 seq = 消息身份);尾巴保持客户端逐字。任何失步 → 整轮 legacy。
|
||||
|
||||
**legacy 全量重发。** 原封未动的全量解析路径——所有形状的默认、三条快车道的兜底安全网。它在响应上重盖真值头,miss 的回合一轮自愈。
|
||||
|
||||
## 命中时跳过的活 / 诚实边界
|
||||
|
||||
跳过:整包 `JSON.parse` + `openaiToCore`(v5);`snapshotMessages` 前缀重钉(v5);只解析差量(增量);前缀按行重渲(D-lane)。诚实边界:保元素数的前缀字节改写**不可检测**(这个信任模型变化在人工评审档,KDD §7.4);多模态尾部一旦进缓存,该段历史留在 legacy 轮(KDD #15 ②);marker-strip 计数随种子账本继承(中部区从不重扫)。
|
||||
|
||||
## 关键入口
|
||||
|
||||
`src/server/fastpath.ts` · `src/server/fastpath-scan.ts`(结构扫描器) · `src/server/threads-lane.ts`(增量) · `src/server/snapshot-render.ts`(D-lane) · `src/agent/pf-channel.ts`(客户端状态机) · `src/agent/incremental-client.ts` · `src/server/lane-decisions.ts`(路由)
|
||||
|
||||
## 相关
|
||||
|
||||
[lanes](./lanes.zh-CN.md) · [pipeline](./pipeline.zh-CN.md) · [identity](./identity.zh-CN.md) · [#5643 演进:四条收敛到快照表底座](https://github.com/ranxianglei/billion-context/issues/5643) · `tests/issue5403-watermark-fastpath.test.ts`
|
||||
@@ -0,0 +1,32 @@
|
||||
# Module: session & message identity
|
||||
|
||||
> Part of the [architecture hub](../architecture.md) · 中文: [identity.zh-CN.md](./identity.zh-CN.md) · as of 2026-11-08, master
|
||||
|
||||

|
||||
(bitmap fallback: [identity.en.png](./assets/identity.en.png))
|
||||
|
||||
## Responsibility
|
||||
|
||||
Decide which session a request belongs to, which of its messages are new versus already stored, and render the outbound history from the surviving identity — so that re-sends, id re-mints, and model switches never corrupt what a summary refers to.
|
||||
|
||||
## Principles
|
||||
|
||||
- **Rung: msgid > order > hash (owner rule #11).** A valid host msgid decides identity (survives cross-model re-encoding); without it, order is the primary carrier and the content hash is a hard per-cell gate with NO global veto.
|
||||
- **Never fuzzy similarity.** Mis-attribution is the most expensive failure (MESSAGE-IDENTITY.md): a wrong join silently misroutes every later `decompress` of a stale ref.
|
||||
- **Degradation, not guessing.** Any desync — chain broken, storage unreadable, switch mid-turn — falls back to the legacy path for the whole turn, re-stamps truth, and converges in one round.
|
||||
|
||||
## How it works
|
||||
|
||||
**Session identity.** The client's session id is used verbatim (native stable ids preferred, #280 — never build identity from derived hashes that drift). Anonymous traffic resolves to `pfa-*` prefix-affinity ids (simhash chain, first-writer provenance #2879/#2265). Persona forking: `subagentNamespace(id, systemText)` forks a host-proven persona onto `|sub:<fp>` — an evidence permitlist (dsh today, #1104/#2156), the first system seen under an id anchors the raw key, side requests never claim it.
|
||||
|
||||
**Message identity.** Plugin lanes carry per-element host msgids in bili's envelope (`msgIds` on `POST /__bili/plugin/turn`) — stripped at ingest, never on the model wire (#4491/#4834/#5842). The ledger key is the triple `(session_id, msg_id, content_hash)`: msgid decides, hash is the safety belt against mis-binding. Legacy full-resend sessions run the order-centric reconcile ladder: positional claims with per-cell fingerprint gates, id/content as auxiliary evidence, each rung failing soft, resync at runs of same-index agreements (MIN_RESYNC_RUN); escalation to "substrate destroyed" only after every pass, or the total-unfold doom loop (#2821).
|
||||
|
||||
**Server-side render (D-lane, #3756).** For sessions bound to a readable unified store, the outbound PREFIX is rendered from the server transcript — row `seq` IS the message identity, signatures/hash are chain back-trace only; the tail stays client-verbatim for prefix-cache stability. Observing (`reconcileFoldCoverage`) and rendering are deliberately separate.
|
||||
|
||||
## Key entries
|
||||
|
||||
`src/session-id.ts` (session key + persona fork) · `src/prefix-affinity.ts` (anonymous resolution) · `src/server/snapshot-render.ts` (D-lane) · `src/fold-reconcile.ts` (reconcile ladder) · `src/agent/incremental-client.ts` (msgid envelope)
|
||||
|
||||
## Related
|
||||
|
||||
[MESSAGE-IDENTITY](../message-identity.md) · [SESSION-IDENTITY](../session-identity.md) · [identity-channels](../identity-channels.md) · [msgid-infrastructure](../msgid-infrastructure.md) · [session-identity-resolution](../session-identity-resolution.md) · [storage](./storage.md)
|
||||